Claude Code v2.1.307 Update: API Version Migration and Safety Event Tracking

Claude Code has released version v2.1.307. This update doesn't introduce game-changing new features, but it makes meticulous fixes in several areas developers encounter daily: API version switching, safety observability for tool calls, MCP connection stability, and session reliability for cloud and self-hosted Runners. Developer ashwin-ant published this version on October 21, marked as an Immutable release — release notes can be edited but the artifacts cannot.

API Version Migration: Switching Code Baseline with One Command

The new /claude-api api-version command allows you to migrate Claude API-related code to a specified API version (2026-10-21). For teams maintaining multiple projects and needing to keep pace with Anthropic API evolution, this means no more manually comparing interface differences — version alignment can be done directly within the session.

Alongside this, a configuration conflict was fixed: when CLAUDE_CODE_DISABLE_1M_CONTEXT is set and the model is an alias with a [1m] suffix (such as opus[1m]), requests would fail with a model-not-found error. This configuration combination is not uncommon in long-context scenarios, and the fix avoids hidden failures caused by environment variables layered with aliases.

Another gateway-related fix: the prompt-caching-scope beta header is no longer sent to custom ANTHROPIC_BASE_URL gateways and Foundry — where it never took effect anyway, so this was previously a no-op transmission.

Anthropic API uses date-based versioning: each API version is named after its release date (e.g., 2026-10-21) and specified via the anthropic-version request header or SDK configuration. Once a version is released, its semantics are frozen; new capabilities are typically introduced as beta headers or new version numbers to ensure existing integrations don't silently break due to upstream changes. This design lets clients explicitly control their upgrade cadence, but it also means cross-version migration requires checking field and behavior differences item by item — especially concerning tool call formats, streaming response structures, and beta feature toggles. The value of /claude-api api-version lies precisely in collapsing this alignment work into a single in-session command.

Safety Event Observability: Every Tool Call on Record

This update adds a claude_code.safety_event OpenTelemetry event for every tool call, covering scenarios involving permission rules, auto mode, safety checks, hooks, or sandbox intervention — whether blocking, prompting, or reverting an operation, a corresponding event is generated.

The significance of this change is turning "safety decisions" from a black box into an auditable data stream. After integrating OTEL, teams can measure which types of tool calls most frequently trigger permission blocks, what the false-positive rate of auto mode is, and under what conditions the sandbox intervenes. For organizations deploying AI coding tools in regulated industries, this kind of telemetry is compliance review infrastructure. The same version also fixed an issue where telemetry for Claude Desktop sessions behind the Claude apps gateway was rejected when OTEL_EXPORTER_OTLP_HEADERS was set.

OpenTelemetry (OTEL) is an open-source observability standard under the CNCF, unifying the data model and transport protocol (OTLP) for three signal types: traces, metrics, and logs. In AI coding tool scenarios, teams typically already have an OTEL Collector and backend (such as Prometheus, Jaeger, Datadog); once Claude Code outputs custom events like claude_code.safety_event, they can flow directly into existing pipelines and be correlated with build, deployment, and other chain data. Note that OTEL_EXPORTER_OTLP_HEADERS is used to pass authentication headers to the Collector, and improper configuration can cause exports to be rejected — exactly the issue this fix addresses.

MCP Connection Stability: Sleep, Disconnection, and Duplicate Calls

MCP-related fixes take up considerable space in the changelog, all pointing to edge cases in real-world use:

• When the macOS login keychain is locked, MCP servers in claude -p no longer just show "authentication required" but explain the reason; after unlocking, the next run can connect without re-login.
• When a macOS or Linux machine sleeps during an MCP connection, it is no longer falsely reported as a timeout and persistently stuck in a failed state in headless runs.
• HTTP MCP tool calls that were previously sent twice when the connection closed mid-call now only retry for read-only or idempotent tools — an important semantic boundary that prevents non-idempotent operations from being executed twice.
• Turns no longer occasionally start without the latest tools from the SDK MCP server when background tasks are running.

These fixes collectively point to one judgment: MCP has moved from experimental integration to production dependency, and the priority of stability issues has risen accordingly.

Idempotency means that executing the same operation multiple times has the same effect as executing it once. Read operations (such as querying files or fetching resources) are naturally idempotent, while write operations (such as committing code, sending messages, or creating tickets) may produce side effects when repeated. Therefore, when a connection is interrupted, only tools explicitly marked as read-only or idempotent are suitable for automatic retry; otherwise the operation must fail and be escalated to upper layers for decision-making. MCP tools declare their semantics through annotations (such as readOnlyHint, idempotentHint), and clients use these to decide retry strategy — this is the technical basis for the fix "only retry read-only or idempotent tools."

Cloud and Self-Hosted Runner: More Controllable Session Lifecycle

Several behavior changes in self-hosted Runner are worth noting:

• Sessions using --use-anthropic-git-proxy no longer commit a .claude/settings.local.json left in the clone by a previous session.
• Archiving, requeuing sessions, or stopping the Runner during the checkout hook no longer leaves hook processes lingering and occupying Runner slots.
• The checkout hook is now stopped by default after 30 minutes, causing session setup to fail; for longer needs, raise it via --checkout-hook-timeout-min, or set it to 0 to disable.

Cloud sessions had several state consistency issues fixed: conversations cleared with /clear occasionally resurrecting after a Runner restart, /autocompact returning to the default window after a session restart, and CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS being ignored in Claude apps gateway sessions. WebFetch in Cowork cloud sessions now returns normal results instead of tool errors when encountering 4xx or robots.txt rejections, aligning with local session behavior.

Tool Calls and Subagents: Enhanced Fault Tolerance

When facing unparseable tool calls, Claude Code now retries up to twice before ending the turn with an error. Fork subagents launched in parallel are told which launch belongs to them, significantly reducing the probability of "stepping on each other's toes." Subagent transcripts no longer record placeholder token usage and empty stop reasons.

The Agent SDK's setModel() now waits up to 15 seconds (up from 5) for model confirmation, avoiding model switches being rejected when API responses are slightly slow. Background commands stopped via connected apps (such as when the desktop app archives an idle session) are no longer reported as "user stopped" but instead indicate their output file.

Fork subagents are parallel subtasks derived from the current session, each with its own independent context and potentially operating on the same codebase simultaneously. When multiple forks launch in parallel, without attribution identifiers, subagents can easily process the same file or task repeatedly — the so-called "stepping on each other's toes." Assigning a recognizable identifier to each launch enables subagents to determine whether a given change or task was initiated by themselves, thereby avoiding duplicate edits and mutual overwrites. This shares the same origin as the task partitioning problem in parallel agent orchestration, and is a key engineering detail for multi-agent systems becoming practical.

Editor and Voice Input: Detail Polish

The VSCode extension fixed several experience issues: collapsed long prompts have a fixed area taking up at most 40% of the panel and are scrollable; list items or table cells containing LaTeX math in the rich text editor are no longer pasted as new lists or tables; when voice dictation stops on its own due to 15 seconds of no recognized speech or hitting the 2-minute limit, the microphone button displays the reason and explains what text was retained. Certificate filtering logic for dictation and the extension's own requests is now aligned with the CLI, and supports NODE_EXTRA_CA_CERTS and CLAUDE_CODE_CERT_STORE.

Code Review adds @claude review stop (along with off and pause) to end the @claude review always subscription on a PR without triggering a new review.

Summary

v2.1.307 is a typical "productionization" update: new capabilities concentrate in two directions — API version migration and safety telemetry — while the bulk of the changelog is devoted to eliminating edge-case failures in MCP, cloud sessions, and Runner lifecycle. For teams already running Claude Code in CI or self-hosted environments, the checkout hook timeout, MCP idempotent retry, and safety_event telemetry are the three behavioral changes to watch.