--- title: "Claude Code v2.1.307: A Safety Event for Every Blocked Tool Call, and a One-Command API Migration" date: 2026-10-22 tags: ["claude-code","opentelemetry","security","mcp","claude-api","changelog"] categories: ["AI Tools","Agentic Workflows"] summary: "Claude Code v2.1.307 adds a claude_code.safety_event OpenTelemetry event for tool calls stopped, prompted or sent back by permission rules, auto mode, hooks or the sandbox, plus /claude-api api-version to move code to API version 2026-10-21. It also fixes HTTP MCP tool calls being sent twice. Changelog-only analysis; not run." --- ![Claude Code v2.1.307: A Safety Event for Every Blocked Tool Call, and a One-Command API Migration](/images/claude-code-v2-1-307-safety-event-telemetry-api-version-migration.png) Most Claude Code releases are bug fixes with a feature or two. v2.1.307 has 43 changelog bullets, and two of them matter for anyone running agents at team scale. One is about observability of your guardrails. The other is about keeping API code current. Everything below comes from the [official changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md); I haven't run this release, so treat behavior claims as the changelog's, not mine. ## `claude_code.safety_event`: telemetry for the "no" The changelog says v2.1.307 adds a `claude_code.safety_event` OpenTelemetry event "for each tool call a permission rule, auto mode, a safety…" check stops, prompts or sends back. The text I could read is truncated, but the summary line is clear: permission rules, auto mode, safety checks, hooks and the sandbox are the sources. Until now, if you wanted to know how often your guardrails fired, you had to infer it from tool-result logs or transcripts. One event type that covers every intervention source is a real improvement for three reasons: - **Tuning permission rules.** A rule that fires 400 times a day on harmless commands is a rule that trains people to click "allow" without reading. You can now measure that. - **Auto mode audit.** [Auto mode](/posts/claude-code-auto-mode-anthropic-hands-ai-more-control/) lets the agent act without per-call approval. Knowing how often its safety layer steps in tells you whether your setup is calm or hovering at the edge. - **Incident review.** After something odd happens, "what did the agent try and what stopped it" is a query, not an archaeology project. If you already export Claude Code's OTel data (the [v2.1.300 cache-write split](/posts/claude-code-subagent-cost-controls-v2-1-296-v2-1-300/) work pointed the same way), add a dashboard panel for this event grouped by source. I'd start with one alert: a sudden spike of sandbox or hook denials in a single session. That's usually a prompt-injected or confused agent. Caveat: I haven't seen the event's attribute schema. Check the monitoring docs before you build queries on field names. ## `/claude-api api-version`: migrations as a command The other addition: `/claude-api api-version` moves Claude API code to API version `2026-10-21`. It extends the existing `claude-api` skill, which already helps with model IDs and SDK usage. This is the spec-driven pattern in miniature. The migration is well-defined, the target is a published version, and the diff is reviewable. You don't want to hand-edit headers and request shapes across forty call sites. Run it on a branch, read the diff, run your tests. My advice: keep your integration tests that hit the API behind a flag, and run them before and after. A migration tool that "works" and a migration that preserves behavior are different claims. ## MCP fixes that affect real workloads The item I'd read twice: "Fixed HTTP MCP tool calls being sent twice when the connection closed mid-call; only read-only or idempotent…" (truncated in the text I could read). The wording suggests the retry now applies only to safe calls. A duplicated call to a tool that creates a ticket, sends a message or triggers a deploy is exactly the failure that makes people distrust agents. If you run HTTP MCP servers with side effects, make them idempotent anyway. Don't rely on the client. Other MCP and runtime fixes in the release: - MCP servers showing "needs authentication" in `claude -p` on macOS while the login keychain was locked. - MCP servers reported as timed out, and staying failed in headless runs, in some macOS and Linux cases. - A turn sometimes starting without an SDK MCP server's latest tools when a background task was running. - Some "Autocompact is thrashing" errors in turns that read many PDF pages, images or large tool results. - Unparseable tool calls are now retried up to twice before giving up. Headless and CI users get the most from these. Interactive sessions hide this class of bug because a human retries. ## Smaller changes worth knowing - **Fork subagents.** Forks launched together are now each told which launch is their own, so they stop duplicating work. - **Gateway users.** The `prompt-caching-scope` beta header is no longer sent behind custom `ANTHROPIC_BASE_URL` gateways, and `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` is now honored in Claude apps gateway sessions. - **1M context flag.** A model-not-found error when `CLAUDE_CODE_DISABLE_1M_CONTEXT` is set is fixed. - **Accessibility.** The `axScreenReader` setting and `CLAUDE_AX_SCREEN_READER` in a settings `env` block now apply only from certain settings sources (the source list is truncated in the text I read). If you set it through the wrong layer, check it still takes effect. - **Self-hosted runners.** Checkout hooks are stopped after 30 minutes by default. A hook that legitimately runs longer will now fail the checkout. - **Code Review.** `@claude review stop` (also `off` and `pause`) ends an in-progress review, which pairs with the review levels covered in [the v2.1.304 post](/posts/claude-code-v2-1-304-auto-mode-setup-mod-tool-check-resume-warning/). - **VS Code.** Voice dictation and the extension's own requests now filter trusted certificates the way the CLI does, which should help behind TLS-inspecting proxies. v2.1.308 follows with a single line: "Bug fixes and reliability improvements." ## What to do this week 1. Upgrade a non-critical project first and confirm that nothing in your gateway setup depends on the old beta-header behavior. 2. Wire `claude_code.safety_event` into your telemetry pipeline and look at a week of data before changing any rules. 3. Try `/claude-api api-version` on a branch and review the diff by hand. 4. Audit HTTP MCP servers with side effects for idempotency. 5. If you run self-hosted runners, check whether any checkout hook takes longer than 30 minutes. ## The point Cursor-style tools keep a human clicking "accept" and call it safety. Claude Code's approach is the opposite: let the agent run, and make the guardrails (rules, auto mode, hooks, sandbox) inspectable. A uniform safety event is the first piece of telemetry that lets you manage those guardrails with data. That is what autonomy with accountability looks like. ## Sources - [Claude Code CHANGELOG (v2.1.305–2.1.308)](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code)