Claude Code v2.1.307 Major Updates - Addition of safety_event and /claude-api api-version

This is Ishikawa from the Cloud Business Division. Claude Code v2.1.307 (released October 21, 2026) has been released. This article focuses on notable updates and verification results on actual hardware. Today, I tried out the new safety_event.

The previous update article is here.

https://dev.classmethod.jp/articles/20261021-cc-updates-v2-1-306/

Update Summary

v2.1.307 includes 43 changes. In this article's classification, there are 26 fixes, 5 improvements, 4 security changes, 3 new features, 2 performance improvements, 2 breaking changes, and 1 developer experience improvement.

The fixes include many related to MCP server connections and authentication, cloud sessions, and Self-hosted runners. The 2 breaking changes both involve changes to existing configuration and hook behavior. There are also changes to the VS Code extension, Cloud sessions, and Code Review.

Notable Updates

Ability to migrate to API version 2026-10-21 with /claude-api api-version

/claude-api api-version has been added, enabling migration of code using the Claude API to API version 2026-10-21.

https://x.com/ClaudeDevs/status/2113013247209021918

According to the official documentation (Versions), 2026-10-21 is the next API version after 2023-06-01, available on the Claude API as well as Claude Platform on AWS, Microsoft Foundry, and Google Cloud, with Amazon Bedrock supporting Claude 4.7 and later models. In the Messages API, the temperature, top_p, and top_k request parameters have been removed, and sending any of them will result in a 400 error for all models. If using an SDK, you need to update to the first SDK version that uses 2026-10-21; if not using an SDK, you need to change the anthropic-version header. The steps are summarized in the migration guide (Migrating to API version 2026-10-21).

Those maintaining Claude API code that specifies sampling parameters such as temperature may find it worthwhile to try this command alongside the migration guide.

Added OpenTelemetry event safety_event for when permission rules or other mechanisms stop tool calls

The OpenTelemetry event claude_code.safety_event has been added, recorded per tool call whenever a permission rule, auto mode, safety check, hook, or sandbox stops, requests confirmation for, or rolls back a tool call. The attributes actually output will be verified in "Trying out safety_event" described later.

Administrators who have deployed Claude Code in their organization and are collecting telemetry with OpenTelemetry may find this useful for aggregating tool calls that were stopped, required confirmation, or were rolled back by permission rules, sandboxes, and similar mechanisms.

Fixed issue where HTTP MCP tool calls were sent twice

An issue where tool calls were sent twice when the connection dropped mid-call for HTTP MCP has been fixed. Additionally, retries are now limited to read-only or idempotent tools only.

This fix seems especially impactful for those using write-type tools on HTTP-connected MCP servers. Since tools that are neither read-only nor idempotent will no longer be retried if the connection drops mid-call, it would be good to also verify how failures in those cases are handled.

axScreenReader now restricted to user settings, managed settings, and --settings

The axScreenReader setting and CLAUDE_AX_SCREEN_READER within the env block of settings will now only be applied from user settings, managed settings, and settings specified with --settings. The CHANGELOG notes "(since 2.1.305)". Configuration examples are shown in the "Breaking Changes and Deprecations" section below.

Those who had axScreenReader written in project settings or local settings will need to move it to user settings, managed settings, or --settings.

Self-hosted runner checkout hooks now stopped by default after 30 minutes

Self-hosted runner checkout hooks are now stopped by default after 30 minutes, causing session setup to fail. If more time is needed, increase the value of --checkout-hook-timeout-min or set it to 0.

Those who perform large repository fetches or pre-builds in checkout hooks should verify the time required before updating and adjust the timeout if necessary.

Update Details

New Features

• /claude-api api-version has been added, enabling migration of code using the Claude API to API version 2026-10-21 (see Notable Updates).
• [VS Code] When voice input stops automatically (after 15 seconds without recognized speech, or upon reaching the 2-minute limit), the microphone button now shows a notification indicating the reason for stopping and that the text entered so far is preserved.
• [Code Review] @claude review stop (also accepts off and pause) has been added, allowing you to end a subscription from @claude review always on a pull request without starting a new review.

Security

• The OpenTelemetry event claude_code.safety_event has been added (see Notable Updates).
• In Self-hosted runners, the certificate files created for Anthropic-managed git now filter trusted certificates the same way as the CLI. The number of excluded certificates is shown in [runner:warn] lines.
• [VS Code] Voice input now filters trusted certificates the same way as the CLI.
• [VS Code] Requests from the extension itself now filter trusted certificates the same way as the CLI, and trust NODE_EXTRA_CA_CERTS files specified via environment variables or user settings.

Improvements

• Recovery from unparseable tool calls has been improved, with up to 2 retries before ending the turn with an error.
• Simultaneously launched fork subagents are now each informed which launch is their own, greatly reducing the likelihood of them attempting to start each other's work.
• The notification Claude receives when the WebSearch budget is exhausted now includes a message to avoid using search engines through the browser or computer use.
• Additionally, improvements have been made to the browser sign-in success page display, web search error display in cloud sessions and Self-hosted runner sessions, and the "still open somewhere else" notification in the VS Code extension.

Performance

• Improved time to first response in cloud sessions when any desktop app MCP server fails to connect.
• Improved Remote Control connection time for sessions with transcripts containing large image pastes or PDF loads.

Fixes

• Fixed issue where HTTP MCP tool calls were sent twice: This occurred when the connection dropped mid-call. Retries are now limited to read-only or idempotent tools only (see Notable Updates).
• Fixed model-not-found error with model aliases containing [1m]: When specifying an alias with a [1m] suffix such as opus[1m] with CLAUDE_CODE_DISABLE_1M_CONTEXT set, requests were failing.
• Fixed issue where MCP servers showed "needs authentication" while macOS keychain was locked: This occurred with claude -p. The reason is now displayed, and subsequent runs after unlocking will reconnect without re-signing in.
• Fixed issue where MCP servers remained failed after sleep: When a macOS or Linux computer went to sleep while an MCP server was connecting, it was reported as a timeout and remained failed in headless execution.
• Fixed "Autocompact is thrashing" error on turns reading large tool results: Some errors that occurred on turns reading many PDF pages, images, or other large tool results have been fixed.
• Fixed issue where conversations cleared with /clear returned after restart: This could occur when cloud sessions or Self-hosted runner sessions restarted.
• Fixed display and approval handling in /permissions Recently denied: Fixed an issue where denied shell commands were not displayed, and an issue where the auto mode local classifier ignored approvals when confirming retried commands. Approving a line now shows the command itself rather than its description.
• Fixed issue where model switching via Agent SDK's setModel() was rejected: Model switching with setModel() and apps built using it was being rejected when API model verification took more than 5 seconds. It now waits up to 15 seconds.
• Fixed issue where .claude/settings.local.json was committed in Self-hosted runner: In sessions using --use-anthropic-git-proxy, .claude/settings.local.json left in clones by previous sessions was being committed.
• Additionally, numerous minor bugs have been fixed in Claude apps gateway, cloud sessions, desktop app, VS Code extension, Self-hosted runner checkout hooks, and more.

Breaking Changes and Deprecations

Of the changes listed as "Changed" in the CHANGELOG, we cover 2 that affect the behavior of existing configurations and hooks. No deprecations are noted.

axScreenReader and CLAUDE_AX_SCREEN_READER now restricted in their sources

This is the change introduced in Notable Updates. Since applicable sources are limited to user settings, managed settings, and --settings, values written in project settings (.claude/settings.json) or local settings (.claude/settings.local.json) will not be applied. The CHANGELOG notes "(since 2.1.305)".

The following are configuration examples.

Before: Writing either of the following in project settings .claude/settings.json would apply them.

{
  "axScreenReader": true
}

{
  "env": {
    "CLAUDE_AX_SCREEN_READER": "1"
  }
}

After: The above entries are not applied in project settings. Write them in user settings ~/.claude/settings.json, managed settings, or --settings. When specifying with --settings, do the following:

claude --settings '{"axScreenReader": true}'

Self-hosted runner checkout hooks now stopped by default after 30 minutes

This is the change introduced in Notable Updates. In v2.1.307, claude self-hosted-runner --help describes --checkout-hook-timeout-min as follows:

  --checkout-hook-timeout-min <n>
                              Wall-clock budget for each run of the checkout lifecycle hook. A hook
                              still running at the budget is stopped (SIGTERM, then SIGKILL) and the
                              session fails setup with a "checkout hook timed out" error instead of
                              staying at "Preparing…". Default: 30. 0 disables. Max: 10080.
                              [env: SELF_HOSTED_RUNNER_CHECKOUT_HOOK_TIMEOUT_MS, in ms]

Hooks that reach the time limit are stopped with SIGTERM followed by SIGKILL, and the session fails setup with a "checkout hook timed out" error. The default is 30 minutes, 0 disables it, the maximum is 10080 minutes, and it can also be specified via the environment variable SELF_HOSTED_RUNNER_CHECKOUT_HOOK_TIMEOUT_MS (in milliseconds). Note that as of the time of writing (October 22, 2026), this flag was not listed in the flag reference in the official documentation (Self-hosted environments reference).

The following are configuration examples (file paths are examples).

Before (up to v2.1.306): With the following startup, checkout hooks exceeding 30 minutes were not stopped by default.

claude self-hosted-runner \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

After (v2.1.307 and later): With the same startup, checkout hooks exceeding 30 minutes will be stopped and session setup will fail. Specify --checkout-hook-timeout-min to extend or disable this.

# Example of extending to 60 minutes
claude self-hosted-runner \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks \
  --checkout-hook-timeout-min 60

# Example of disabling the timeout
claude self-hosted-runner \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks \
  --checkout-hook-timeout-min 0

Trying out safety_event

Here are the steps to output and inspect the contents of the OpenTelemetry event claude_code.safety_event added in Claude Code v2.1.307 in a local environment. We pass a deny rule for the Read tool via --settings and verify that a Read call rejected by that rule is recorded as a safety_event.

• Only 1 claude -p is executed (in this environment, there was 1 api_request event).
• Configuration files (such as ~/.claude/settings.json) are not modified. The deny rule is passed via --settings.
• The telemetry output destination is set to console (standard output), and nothing is sent to an external collector.

The verification steps and output examples were confirmed by running on Claude Code v2.1.307 on macOS.

What this verification confirms

1. That when a Read call matching the deny rule is rejected, 1 claude_code.safety_event is output
2. The attributes recorded in safety_event and their values
3. How to share the output while excluding lines containing identifying information

Overall flow

Prerequisites

• macOS or Linux shell (uses grep and awk)
• No variables starting with OTEL_ set in the env of ~/.claude/settings.json

Step 1: Confirm there are no OTEL settings

Confirm that there are no environment variables starting with OTEL_ in the user settings.

% grep -n OTEL ~/.claude/settings.json

If nothing is output, there is no issue. If something is output, the telemetry destination may differ from what is expected due to those settings, so please review the content before proceeding.

Step 2: Create an empty working directory

% mkdir -p ~/safety-event-handson
% cd ~/safety-event-handson
% ls -A

Confirm that ls -A outputs nothing. Do not create secret.txt. In this verification, even without the file existing, the Read call was rejected by the deny rule.

Step 3: Run claude -p with telemetry output to console

While rejecting the Read call via the deny rule, we prompt for reading of secret.txt with "Please read secret.txt using the Read tool" and output telemetry to console.

Run the following command and save standard output to telemetry.log.

% CLAUDE_CODE_ENABLE_TELEMETRY=1 \
OTEL_LOGS_EXPORTER=console \
OTEL_METRICS_EXPORTER=none \
claude -p --max-turns 1 \
  --settings '{"permissions":{"deny":["Read(./secret.txt)"]}}' \
  "Read ツールで secret.txt を読んでください" > telemetry.log
% echo "exit code: $?"
exit code: 1

The meaning of each specification is as follows:

The exit code becomes 1 because execution ends upon reaching the --max-turns 1 limit. telemetry.log contains the following line:

% grep -o 'Error: Reached max turns ([0-9]*)' telemetry.log
Error: Reached max turns (1)

Note that hooks, MCP servers, plugins, and the default permission mode (permissions.defaultMode) set in ~/.claude/settings.json are loaded as normal with this command.

Step 4: Check the types and counts of output events

% wc -l < telemetry.log
% grep -o 'body: "claude_code\.[a-z_]*"' telemetry.log | sort | uniq -c | sort -rn
    2695
  31 body: "claude_code.mcp_server_connection"
  15 body: "claude_code.hook_registered"
  10 body: "claude_code.plugin_loaded"
   2 body: "claude_code.hook_execution_start"
   2 body: "claude_code.hook_execution_complete"
   1 body: "claude_code.user_prompt"
   1 body: "claude_code.safety_event"
   1 body: "claude_code.managed_settings_resolved"
   1 body: "claude_code.api_request"

Counts will vary depending on the number of hooks, MCP servers, and plugins loaded. We confirmed that there is 1 claude_code.safety_event. In this environment, no claude_code.tool_decision events were included in the same output.

Step 5: Extract safety_event and remove lines with identifying information

The console exporter output contains attributes that identify the account and session, such as user.email and organization.id. Use the following command to extract only the safety_event record and save it to safety_event.txt after removing those lines.

% awk '/body: "claude_code.safety_event"/{f=1} f{print} f&&/^}$/{f=0}' telemetry.log \
  | grep -v -E '"(user\.id|session\.id|organization\.id|user\.email|user\.account_uuid|user\.account_id|prompt\.id)":|tool_use_id:' \
  > safety_event.txt
% cat safety_event.txt
  body: "claude_code.safety_event",
  attributes: {
    "terminal.type": "zed",
    "event.name": "safety_event",
    "event.timestamp": "2026-10-22T01:21:38.852Z",
    "event.sequence": 47,
    category: "permission_rule",
    decision: "reject",
    decision_source: "config",
    reason_type: "rule",
    reason_code: "rule:flagSettings",
    rule_source: "flagSettings",
    tool_class: "file",
    tool_name: "Read",
    tool_source: "builtin",
    permission_mode: "auto",
    sandbox_violation_count: "0",
    sandbox_enabled: "false",
  },
}

• The awk portion: Outputs from the line containing body: "claude_code.safety_event" through the } line that closes the record. If there are multiple safety_event entries, all are output.
• The grep -v portion: Removes lines for user.id, session.id, organization.id, user.email, user.account_uuid, user.account_id, prompt.id, and tool_use_id.

The console exporter output is not JSON. Some keys lack quotes (e.g., category:), values may contain undefined, and there are trailing commas before closing brackets. Additionally, multiple records are output consecutively across multiple lines. Running jq . telemetry.log will actually stop with a parse error, which is why we use grep and awk to extract the data.

Step 6: Review the attributes

Let's examine the attributes specific to safety_event and their values in this run.

As of the time of writing (October 22, 2026), the official documentation's monitoring page does not include a description of safety_event, so the "Correspondence to steps" column only lists items where the specified content in the steps corresponds to the values.

https://code.claude.com/docs/en/monitoring-usage

This verification confirmed that the above attribute values are observable from safety_event.

Notes

• Sharing telemetry.log as-is will include email addresses, organization IDs, and similar information. When sharing, please remove the relevant lines using the method in Step 6.
• Attribute names and values are those observed in v2.1.307. Since there is no official documentation yet, please re-verify the output in the version you use before incorporating it into dashboards or alerts.
• According to the CHANGELOG, safety_event is also recorded when auto mode, safety checks, hooks, or sandboxes stop, request confirmation for, or roll back a tool call, in addition to permission rules. This verification only confirmed one pattern: rejection by a permission rule's deny rule.

Closing

v2.1.307 feels like a release where safety_event for recording safety mechanism activity and /claude-api api-version for assisting migration to API version 2026-10-21 stand out. The fix for double-sending of HTTP MCP tool calls is also something to check, especially for those using write-type MCP tools.

Those operating Self-hosted runners or who have axScreenReader written in project settings should review the breaking changes section before updating and giving it a try.

References

https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

https://code.claude.com/docs/en/changelog

https://dev.classmethod.jp/articles/20261021-cc-updates-v2-1-306/