Claude Code v2.1.251: Model Switch Hooks, Prompt-Cache Stats in /cost, and Permission Hardening

Claude Code v2.1.251 is a large release with 71 changelog entries. It adds hook events that fire around model switches, prompt-cache and spend-limit reporting, and live streaming of foreground subagent activity to Remote Control clients. Many of the remaining changes tighten permissions, covering symlinked paths, plugin command paths, sandboxed output files, and settings that now require approval before they apply.

What’s New

Model Switch Hooks

The new PreModelSwitch and PostModelSwitch hook events let hooks block, confirm, or annotate a model switch. Separately, SessionStart hooks that run on resume now receive the session’s staleness and the estimated re-cache cost.

Prompt-Cache and Spend-Limit Reporting

/cost now includes a per-session prompt-cache line showing the hit ratio, misses, tokens re-cached, and warm/cold state, and status line scripts get a matching prompt_cache object. For developers behind a Claude apps gateway with spend limits, /usage adds a Spend limit bar and the status line gains a rate_limits.spend_limit field.

Live Subagent Activity in Remote Control

Remote Control clients now receive a live stream of a foreground subagent’s tool calls and results. Background subagents, which are the default, still show status only.

Background Session Commands in Help

claude --help now lists attach, logs, stop, respawn, and rm. When you use --resume on a background session that is still running, the message now names the exact claude attach <id> command.

Model and Effort Defaults

CLAUDE_CODE_SUBAGENT_MODEL now sets the default subagent model instead of overriding everything: an agent definition’s model: and an explicit per-spawn model take precedence over it.
/effort now saves your default effort level per model, so each model keeps its own setting when you switch.
Seat-based Enterprise subscriptions now default to Opus 5, matching other premium plans.
When the active model isn’t a recognized Claude model (for example, a third-party model behind a custom ANTHROPIC_BASE_URL), the default commit trailer is now Co-Authored-By: Claude Code.

Settings That Now Require Approval

Server-managed settings that terminate sandbox TLS, route sandbox traffic through your own proxy, inject credentials, or weaken sandbox isolation must now be approved before they apply.
ANTHROPIC_CUSTOM_HEADERS coming from managed or project settings now requires approval when it sets a credential, org/tenant, routing, or API-behavior header, such as Authorization or Host.
Project-level .claude/settings.json env no longer sets CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, or TMPDIR/TMP/TEMP; set these in your shell, user, or managed settings instead.
The managed settings approval dialog now lists only the settings that changed since you last approved them.

Claude in Chrome Uses Claude Code Permission Checks

Browser actions from Claude in Chrome now always go through Claude Code’s permission checks. This includes sessions with telemetry disabled, which previously used the Chrome extension’s own prompts.

Smaller Native Binary

The native binary is about 5 MB smaller. Separately, syntax highlighting was removed for six rarely used languages (1c, gml, isbl, mathematica, maxima, sqf), which the changelog says makes the binary 2.5 MB smaller.

Fixes and Improvements

Permissions and security

File tools (Read, Write, Edit) no longer follow a symlink swapped inside the working directory after the permission check, which could read or write outside the approved location.
Grep and Glob now apply Read(...) deny rules to files reached through a symlinked search path.
Plugin commands declared in a marketplace entry can no longer point outside the plugin directory; such paths are rejected with a path-traversal error.
Bash commands that assign an arithmetic expression to an integer shell variable (e.g. OPTIND=1/0, RANDOM=2+2) now prompt for approval instead of being auto-approved.
Project settings can no longer enable detailed beta tracing or raw API body logging, and a lower-scope beta tracing endpoint can no longer bypass an OTLP collector pinned by managed settings or a host app.
When commands run in the sandbox, Bash output files are now created and read back in a way that a sandboxed command cannot redirect or replace.

Conversations and modes

Conversations no longer get stuck on “text content blocks must be non-empty” errors after a turn in which the model produced only thinking.
Opus 5 requests no longer fail when effort is xhigh/max and thinking is turned off; effort is sent as high in that case.
A managed-settings disableAutoMode that arrives mid-session now moves an already-running auto-mode session back to default mode.
Session transcripts are no longer silently overwritten when a directory change relocates a session onto an existing transcript with the same ID.

Background sessions and subagents

Background sessions and their subagents can now edit files inside a git worktree they created with git worktree add.
Backgrounded sessions (←, /background, --bg) no longer lose a Vertex/Bedrock gateway (ANTHROPIC_*_BASE_URL + CLAUDE_CODE_SKIP_*_AUTH) exported in the shell, which had made every request fail.
Many parallel subagents no longer cause TUI lag: per-second progress ticks now replace their predecessor instead of piling up in the transcript.
In agent teams, a teammate’s final answer now reaches the team lead in the idle notification instead of a content-free “available” notice.

SDK, MCP, and cloud sessions

SDK and cloud sessions no longer hang indefinitely when an SDK MCP server’s handshake acknowledgment is lost; the wait now times out after 70 seconds and marks only that server as failed.
With --input-format stream-json, client-injected assistant tool calls sent without a message id are no longer merged into the first one with their results lost, including when resuming older sessions.

Performance and providers

CPU usage during turns in interactive sessions is lower thanks to fewer redundant UI re-renders.
When the model’s tool call is malformed, the broken output is now dropped from the retry context, including on Bedrock, Vertex, and Foundry.
/radio is now available on Bedrock, Vertex AI, Foundry, and Claude Platform on AWS, and when telemetry is disabled.

VS Code

The Remote Control banner is now a footer pill, shown while Remote Control is on or has failed, that opens the session on claude.ai/code; turn it on or off with /remote-control.

v2.1.251 contains 71 changes in total; see the full changelog for the complete list.

How to Update

Check your installed version: claude --version
Update in place: claude update
If your project’s .claude/settings.json sets CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, or TMPDIR/TMP/TEMP under env, move them to your shell, user, or managed settings, because project-level env no longer sets them. If you use CLAUDE_CODE_SUBAGENT_MODEL, note that an agent definition’s model: and an explicit per-spawn model now take precedence over it.