Claude Code v2.1.250 to v2.1.251 Key Updates - Project Settings env Restrictions and Prompt Cache Visualization

This is Ishikawa from the Cloud Business Division. I'll summarize the Claude Code updates for v2.1.250 ~ v2.1.251 (2026-08-27 ~ 2026-08-28). This edition is notable for permission-related fixes, and I feel it's worth checking out especially if you've been fine-tuning your settings. Today, I tried out the new prompt cache visualization feature.

The previous update article is here.

https://dev.classmethod.jp/articles/20260828-cc-updates-v2-1-248/

Update Summary

This covers 2 versions (v2.1.250 ~ v2.1.251, 2026-08-27 ~ 2026-08-28), totaling 72 items. v2.1.250 only has a single line in the CHANGELOG reading "Bug fixes and reliability improvements," while the remaining 71 items belong to v2.1.251. The breakdown shows fixes as the most numerous, followed by improvements, permission/sandbox-related changes, new features, and breaking changes.

Notable Updates

Prompt cache status added to /cost (v2.1.251)

A session-level prompt cache line has been added to /cost. It displays hit ratio, miss count, re-cached token count, and warm/cold status, along with a corresponding prompt_cache object for status line scripts.

Since cache effectiveness directly impacts costs in longer sessions, I find it operationally helpful to be able to break things down with actual numbers.

Hook events for model switching added (v2.1.251)

PreModelSwitch and PostModelSwitch hook events have been added, enabling blocking, confirmation, and annotation of model switches. Additionally, the SessionStart resume hook now receives session staleness and estimated re-caching costs.

I feel there's significant value in being able to stop unintended switches via hooks, whether you want to standardize the model used across your organization or simply avoid unexpected changes.

Fixed conversation stopping on thinking-only turns (v2.1.251)

A bug where conversation would stop progressing with a "text content blocks must be non-empty" error after a turn where the model only output thinking has been fixed.

Since this type of bug prevents the conversation from advancing at all, I think it's worth prioritizing the update if this sounds familiar.

Fixed loss of Vertex / Bedrock gateway settings when backgrounding (v2.1.251)

A bug where backgrounded sessions (←, /background, --bg) would lose shell-exported Vertex / Bedrock gateway settings (ANTHROPIC_*_BASE_URL and CLAUDE_CODE_SKIP_*_AUTH), causing all requests to fail, has been fixed.

For environments using Bedrock or Vertex AI via a gateway, background execution was entirely non-functional, so the impact was likely not small.

Fixed file operation tools following swapped symlinks (v2.1.251)

A bug where file operation tools (Read / Write / Edit) would follow symlinks that were swapped within the working directory after permission checks, potentially reading and writing outside approved locations, has been fixed.

Since this was a path that could bypass restrictions even with the working directory as a scope, I feel this is an important fix especially for environments with fine-grained allow / deny configurations.

Fixed Bash permission check auto-approving arithmetic assignment expressions (v2.1.251)

A bug where the Bash permission check would auto-approve commands that assign arithmetic expressions to integer shell variables (e.g., OPTIND=1/0, RANDOM=2+2) has been fixed. These will now prompt for approval.

Since seemingly harmless variable assignments were being auto-approved, I feel this is a fix worth reviewing from the perspective of permission check coverage.

Target Versions and Period

New Features

• PreModelSwitch / PostModelSwitch hook events have been added, enabling blocking, confirmation, and annotation of model switches. The SessionStart resume hook now receives session staleness and estimated re-caching costs (v2.1.251)
• Tool calls and results from foreground subagents are now live-streamed to Remote Control clients. Background subagents, which are the default, continue to show status only as before (v2.1.251)
• A session-level prompt cache line (hit ratio, miss count, re-cached token count, warm/cold) and a prompt_cache object for status line scripts have been added to /cost (v2.1.251)
• A Spend limit bar has been added to /usage, along with a rate_limits.spend_limit field for status lines. This targets developers under Claude apps gateways with spending limits configured (v2.1.251)
• attach / logs / stop / respawn / rm are now listed in claude --help. The --resume message for running background sessions also now accurately shows the claude attach <id> command to run (v2.1.251)

Permission and Sandbox Changes

• A bug where file operation tools (Read / Write / Edit) would follow symlinks swapped within the working directory after permission checks, potentially reading and writing outside approved locations, has been fixed (v2.1.251)
• A bug where Grep and Glob were not applying Read(...) deny rules to files reached via symlinked search paths has been fixed (v2.1.251)
• A bug where plugin commands declared in marketplace entries could point outside the plugin directory has been fixed. Such paths are now rejected as path traversal errors (v2.1.251)
• A bug where the Workflow tool would read a scriptPath that the session was not permitted to read before permission checks, and also quote it in error messages, has been fixed (v2.1.251)
• A bug where detailed beta tracing or raw API body logging could be enabled from project settings, and where a lower-scope beta tracing endpoint could bypass OTLP collectors fixed by managed settings or host apps, has been fixed (v2.1.251)
• A bug where the Bash permission check would auto-approve commands assigning arithmetic expressions to integer shell variables (e.g., OPTIND=1/0, RANDOM=2+2) has been fixed (v2.1.251)
• A bug where sessions already running in auto mode would not revert to default mode when disableAutoMode arrived from managed settings mid-session has been fixed (v2.1.251)
• Browser operations in Claude in Chrome now always go through Claude Code's permission checks, including sessions with telemetry disabled. Previously, those sessions used the Chrome extension's own prompts (v2.1.251)
• Server-managed settings for terminating sandbox TLS, routing sandbox traffic through a custom proxy, injecting credentials, or weakening sandbox isolation now require approval before being applied (v2.1.251)
• ANTHROPIC_CUSTOM_HEADERS from managed settings or project settings now requires approval when setting headers related to credentials, organization/tenant, routing, or API behavior (such as Authorization, Host, etc.) (v2.1.251)
• The method for creating and reading back Bash output files for commands run inside the sandbox has been changed so that sandboxed commands can no longer redirect or replace them (v2.1.251)
• Sanitization of MCP server names in error messages, menus, and command results has been improved (v2.1.251)

Improvements

• CPU usage during interactive session turns has been improved by reducing redundant UI redraws (v2.1.251)
• Installation size has been improved, with native binaries reduced by approximately 5 MB (v2.1.251)
• Amazon Bedrock session startup under CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST (such as Claude Desktop) has been improved, so sessions given a Bedrock model ID or ARN no longer wait for inference profile discovery (v2.1.251)
• The default model for seat-billed Enterprise subscriptions is now Opus 5, consistent with other premium plans (v2.1.251)
• /effort now saves the default effort level per model, so each model's setting is preserved when switching models (v2.1.251)
• /radio is now available on Bedrock, Vertex AI, Foundry, and Claude Platform on AWS, as well as when telemetry is disabled (v2.1.251)
• The PR badge in the footer on Bedrock, Vertex, Foundry, and when telemetry is disabled now calls the GitHub API directly using gh auth token, GH_TOKEN, or GITHUB_TOKEN instead of gh pr view (v2.1.251)
• Retry behavior for malformed model tool calls has been improved, removing broken output from retry context. This also applies to Bedrock, Vertex, and Foundry (v2.1.251)
• The managed settings approval dialog now shows only settings that have changed since the last approval (v2.1.251)
• Plugin/LSP installation suggestions and auto mode default suggestions now wait to display until current input is submitted or cleared, preventing Enter from accidentally responding to them when submitting a prompt (v2.1.251)
• The presentation of messages arriving from subagents has been improved, conveying to Claude that the sender is a worker within this session rather than an unrelated Claude session (v2.1.251)
• When viewing transcripts of background subagents or forks opened from the subagent panel or /tasks, the prompt placeholder now reads "Message @name…" (v2.1.251)
• When the active model is not a recognized Claude model (such as a third-party model under a custom ANTHROPIC_BASE_URL), the default commit trailer is now Co-Authored-By: Claude Code (v2.1.251)
• In cloud sessions, when the session's network proxy drops the connection while a Bash command is running, the tool result now shows the hostname and reason rather than just "connection reset" (v2.1.251)
• /schedule now explains that MCP servers configured in Claude Code cannot connect to cloud routines (v2.1.251)
• Analytics are no longer disabled before sign-in solely because managed settings force a gateway login (or cannot read settings) (v2.1.251)
• [VSCode] The Remote Control banner has been changed to a footer pill display (shown when Remote Control is active or has failed). Sessions can be opened at claude.ai/code. Toggle on/off with /remote-control (v2.1.251)

Fixes (Major)

Here is a selection focused on stability and usability fixes.

• Fixed conversation stopping after thinking-only turns: A bug where conversation would stop progressing with a "text content blocks must be non-empty" error after a turn where the model only output thinking has been fixed (v2.1.251)
• Fixed Opus 5 request failures: A bug where requests to Opus 5 would fail with "effort … is not supported when thinking is disabled" when effort was set to xhigh / max with thinking disabled has been fixed. In this case, effort is sent as high (v2.1.251)
• Fixed session transcript overwriting: A bug where a transcript would be silently overwritten when a directory change caused a session to be relocated on top of an existing transcript with the same ID has been fixed (v2.1.251)
• Fixed gateway settings loss in background sessions: A bug where backgrounded sessions would lose shell-exported Vertex / Bedrock gateway settings (ANTHROPIC_*_BASE_URL and CLAUDE_CODE_SKIP_*_AUTH), causing all requests to fail, has been fixed (v2.1.251)
• Fixed agent team responses not being delivered: A bug where a teammate's final answer would not reach the team lead has been fixed. Answers are now included in idle notifications rather than empty "available" notifications (v2.1.251)
• Fixed missing plugin skills in background sessions: A bug where a background session would start with no plugin skills and remain that way if another Claude Code process was updating the plugin marketplace at the time has been fixed (v2.1.251)
• Fixed SDK MCP server hangs: A bug where SDK and cloud sessions would hang indefinitely when a handshake response was lost has been fixed. It now times out after 70 seconds, treating only the affected server as failed (v2.1.251)
• Fixed missing tool calls with stream-json: A bug with --input-format stream-json where client-injected assistant tool calls sent without a message ID would be merged into the first item and their results lost has been fixed. This includes resuming old sessions (v2.1.251)
• A small but welcome fix: A bug where Ctrl+G in a background session would fail with "Emacs quit unexpectedly" for editors that open /dev/tty, such as emacs -nw or micro, has been fixed (v2.1.251). Since your usual editor will now open normally even in background sessions, this is a subtle but impactful improvement to the daily experience
• In addition, numerous minor bugs have been fixed in Remote Control and /mcp error display, display and selection in tmux / GNU screen, file editing in git worktrees and background sessions, display in /usage-credits and Claude apps gateway, and the VSCode extension sign-in screen, among others. Note that v2.1.250 only has "Bug fixes and reliability improvements" as a single line in the CHANGELOG, with no individual changes listed

Breaking Changes and Deprecations

Some environment variables can no longer be set via env in project settings (v2.1.251)

CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, and TMPDIR/TMP/TEMP can no longer be set via env in project-level .claude/settings.json. These should now be set via shell, user settings, or managed settings.

Below are examples using only the setting key names listed in the CHANGELOG.

Before (~ v2.1.250):

// <project>/.claude/settings.json
{
  "env": {
    "CLAUDE_CONFIG_DIR": "/path/to/shared-config",
    "CLAUDE_CODE_TMPDIR": "/path/to/work-tmp",
    "TMPDIR": "/path/to/work-tmp"
  }
}

After (v2.1.251 ~):

# Specify in the shell (or user settings / managed settings)
export CLAUDE_CONFIG_DIR=/path/to/shared-config
export CLAUDE_CODE_TMPDIR=/path/to/work-tmp
export TMPDIR=/path/to/work-tmp

CLAUDE_CODE_SUBAGENT_MODEL priority has changed (v2.1.251)

CLAUDE_CODE_SUBAGENT_MODEL has changed from overriding everything to setting the default model for subagents. The model: in agent definitions and explicit specification at spawn time take priority.

Below is an example using only the environment variable name and setting key listed in the CHANGELOG.

Syntax highlighting for 6 languages has been removed (v2.1.251)

Syntax highlighting for 6 infrequently used languages (1c, gml, isbl, mathematica, maxima, sqf) has been removed. The binary is 2.5 MB smaller as a result.

Trying Out the /cost Prompt Cache Display

The session-level prompt cache line added to /cost in v2.1.251 is checked in interactive mode. The steps are as follows:

1. Launch claude in the target project directory to enter interactive mode
2. Conduct several exchanges involving file reading or editing (since the prompt cache line is a session-level aggregate)
3. Run /cost at the prompt input

Actual Output

Line Added in v2.1.251

Prompt cache (main):   11 requests · 90% of input tokens from cache · no misses · warm (1h TTL, last activity 31s ago)

The correspondence with the CHANGELOG description (hit ratio, misses, tokens re-cached, warm/cold) is as follows:

About the Item That Did Not Appear

tokens re-cached (number of re-cached tokens) listed in the CHANGELOG does not appear in this output. My assumption is that since there were no misses and no re-caching occurred, it may be an item that only appears when misses are generated.

What (main) Means

I assume (main) refers to the main conversation rather than a subagent. My basis is a discrepancy in the aggregate values.

• Prompt cache (main) is an aggregate for 11 requests
• Usage by model accounts for 877k tokens of cache reads

The cache ratio calculated from the per-model breakdown is 877.9k ÷ (877.9k + 76.6k + 1.5k) ≒ 92%, which slightly differs from the displayed 90%. I believe this is because the two aggregation scopes differ (with Usage by model including subagent figures).

Closing

This edition featured fixes for paths that could bypass permission checks, such as symlinks and arithmetic assignment expressions. Since these are areas that are easy to overlook in normal operation, I feel it's worth updating sooner rather than later, especially for environments with fine-grained allow / deny configurations.

If you have env written in your project settings or have been fixing subagent models with CLAUDE_CODE_SUBAGENT_MODEL, please review the breaking changes section. If anything catches your attention, try updating and checking it out.

References

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

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

https://dev.classmethod.jp/articles/20260828-cc-updates-v2-1-248/