Claude docs changes for August 29th, 2026 [diff]

Executive Summary

• Claude Code now enforces a "first-byte" streaming deadline separate from the overall request timeout, aborting and retrying once if no response headers arrive in time, with a new CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS variable and a new "No response from API" error.
• Security hardening: file-access tools now re-confirm a path's symlink resolution at the moment they open or search it (not just at write time), and plugin path-traversal protection now also covers paths declared in plugin.json, not just marketplace entries.
• Prompt caching improved broadly: the mid-conversation system-context block is now cacheable on every provider and gateway (previously left uncached on some), and /usage/the status line now surface per-session cache-hit statistics.
• Effort above high is now rejected client-side when thinking is turned off on models that don't support the combination (e.g. Opus 5), replacing a silent server-side failure with an explicit error.
• MCP and Agent SDK updates: a new per-server timeout option for SDK MCP servers, a new maxResultSizeChars tool annotation field, and a new /servername:promptname (MCP) prompt-listing format.

No versions/ or docs-md/api changes today; this update touched only docs-md/claude-code.

Claude Code changes

Changed documents

advisor [Source]

• Clarifies that /model applies "from the next request onward" rather than "for all subsequent turns," reflecting that a mid-turn switch takes effect starting with the next request. [line 157] [Source]

agent-sdk/cost-tracking [Source]

• New: the SDK's cost fields now model data-residency pricing — when a response reports inference_geo: "us", the SDK multiplies that response's token price by 1.1 (per-request fees like web search are excluded). Requires TypeScript Agent SDK v0.3.239+ or Python Agent SDK v0.2.144+. [line 12] [Source]

agent-sdk/file-checkpointing [Source]

• Documents the success message a --rewind-files rewind now prints: Files rewound to state at message <checkpoint-uuid>, exiting without sending a prompt. [line 248] [Source]

agent-sdk/mcp [Source]

• Removed the (incorrect) claim that Claude Code applies the 30s MCP connection timeout only to the connection attempt. [line 51] [Source]
• New: in TypeScript, a single SDK MCP server's tool-call timeout can now be set via a timeout option passed to createSdkMcpServer(). [line 57] [Source]

agent-sdk/python [Source]

• ToolAnnotations now extends the MCP SDK's type with a new maxResultSizeChars field, accepts camelCase or snake_case field names, and accepts a plain mcp.types.ToolAnnotations. Requires Python Agent SDK 0.2.140+ for the snake_case names and typed field; versions 0.1.55–0.2.139 can still pass maxResultSizeChars as an untyped keyword argument. [lines 137-138] [Source]
• New maxResultSizeChars field in the ToolAnnotations table: caps (up to 500,000) how many characters of a tool's text result Claude Code keeps inline instead of saving to a file; sent via _meta as anthropic/maxResultSizeChars. [line 148] [Source]

agent-sdk/typescript [Source]

• New timeout option on createSdkMcpServer() and a matching timeout field on McpSdkServerConfigWithInstance: sets the tool-call timeout for that server in place of MCP_TOOL_TIMEOUT (minimum 1000ms). Requires TypeScript Agent SDK v0.3.248+. [lines 163, 176, 1024]
• ScheduleWakeupInput gains a new noop field (required unless stop is true) to report a wake-up where nothing changed. [lines 2816, 2821]

agent-sdk/user-input [Source]

• Revises guidance for long-pending canUseTool callbacks: instead of returning defer directly from the callback, register a PreToolUse hook that returns the defer decision. [line 6] [Source]

agent-teams [Source]

• Idle notifications from a teammate now include the teammate's final answer; previously the notification carried no output, requiring a separate message. [line 259] [Source]
• Removed the "subagents vs. teammates report back differently" caveat and its "orchestration flow that waits on subagent results can stall" warning, now that idle notifications carry output. [lines 371-373] [Source]

agent-view [Source]

• New condition where Claude skips moving into a worktree: when the file being edited is already inside a linked git worktree the session or a subagent created. [line 397] [Source]
• New --restricted flag for claude agents, starting every dispatched session in restricted mode. Requires v2.1.248+. [line 492] [Source]
• Claude Code now forwards a cloud-provider gateway (e.g. ANTHROPIC_VERTEX_BASE_URL/ANTHROPIC_BEDROCK_BASE_URL plus its auth-bypass flag) exported in the dispatching shell to the background session's worker, under the same conditions as ANTHROPIC_BASE_URL; previously such sessions failed every request. [lines 575, 765-767]
• Version table: v2.1.251 also fixed a bug where a background session starting during a sibling session's plugin-marketplace refresh could start without that marketplace's skills, agents, hooks, and MCP servers for its whole run. [line 767] [Source]

amazon-bedrock [Source]

• Setup wizard now "asks for" your AWS region instead of auto-detecting it. [line 38] [Source]
• Clarifies that automatic 1M-context enablement for non-Sonnet-5 models applies only on the Invoke API, not the Mantle endpoint. [line 345] [Source]

claude-apps-gateway-config [Source]

• Narrowed boot validation: only an unrecognized top-level key now fails gateway boot; a malformed value for a recognized key no longer does. [line 515] [Source]

claude-apps-gateway-deploy [Source]

• The gateway's Postgres schema now has five data tables plus a _migrations table (previously described as just five tables). [line 136] [Source]
• Client analytics behavior reversed: the CLI now sends startup events and a feature-flag request to Anthropic before sign-in, even on machines with forceLoginMethod: "gateway" — previously documented as suppressed pre-sign-in. [line 192] [Source]
• Simplified: gateway sign-in (not managed-settings-forced sign-in) is what disables the Anthropic-bound survey-rating sink. [line 195] [Source]
• The token exchange failed log line now includes a request_id=<id>. [line 225] [Source]

claude-apps-gateway-spend-limits [Source]

• New: on v2.1.251+, Claude Code shows a Spend limit bar in /usage and adds a rate_limits.spend_limit object to the status line input, using the same gateway headers (server still only needs v2.1.225+). [line 75] [Source]

claude-apps-gateway [Source]

• Documents the exact openssl command to print the TLS fingerprint in the same truncated, colon-free form shown at the /login prompt. [line 230] [Source]
• Behavior change: the CLI now marks the mid-conversation system-context block for prompt caching on gateway sessions too — previously that block was left uncached only on gateway sessions. [line 380] [Source]

claude-code-on-the-web [Source]

• New privacy behavior on macOS/Linux/WSL: uncommitted changes to credential-like files (.env, Terraform *.tfvars, id_rsa, *.pem) are excluded by default from a cloud session's upload bundle, naming the excluded files; in a linked worktree/submodule those changes are uploaded instead. [line 90] [Source]
• New error: Couldn't verify your organization's policy for cloud sessions... when the policy fetch fails — the CLI now refuses to send rather than assume cloud sessions are allowed. [line 135] [Source]
• New: running claude --teleport with no session ID under API-key auth or stale account details now shows Error loading Claude Code sessions in the picker. [line 282] [Source]
• New: background work still running when a cloud session's VM was reclaimed (subagents, shell commands) is not restored on reopen. [line 296] [Source]

claude-directory [Source]

• cache/changelog.md is now described as shown by /release-notes, no longer as used "to show release notes after an update" (matches the new proactive changelog fetch in network-config.md). [line 221] [Source]

claude-platform-on-aws [Source]

• The awsAuthRefresh credential-refresh flow is now reached via /login → 3rd-party platform → Claude Platform on AWS · refresh credentials, rather than a shortcut option; documented as requiring Claude Code v2.1.186+. [line 42] [Source]

claude-security [Source]

• New output file: CLAUDE-SECURITY-RESULTS.sarif, a SARIF 2.1.0 log (with CWE categories) for GitHub code scanning and other SARIF-reading tools. [line 98] [Source]

cli-reference [Source]

• --agents now validates its JSON at startup and exits on invalid values (with a flag and env var to skip validation). Requires v2.1.242+. [line 54] [Source]
• --restricted now also refuses to create cloud sessions. [line 111] [Source]

cloud-environments [Source]

• Changed the cloud-session environment fallback logic: falls back to the Anthropic-hosted environment when present, otherwise the first non-"bridge" environment (a Remote Control-registered entry for your own machine) — previously just "first available cloud environment." The same logic now applies when the saved default environment is archived. [lines 26, 78]

code-review [Source]

• /code-review ultra now applies the same credential/secret-file exclusion rules as cloud-session uploads to uncommitted changes in its scope. [line 336] [Source]

commands [Source]

• /claude-api gains a new cost-optimize subcommand that profiles Claude API spend and proposes savings. Requires v2.1.247+. [line 48] [Source]
• /radio is no longer restricted on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. [line 99] [Source]
• /effort, /model, and /fast can now run while Claude is responding rather than only queueing until the turn ends; before v2.1.242 this depended on a feature flag and always queued on sessions that don't fetch feature flags. [lines 65, 68, 91]
• New /workflow-authoring bundled command to load the dynamic-workflow script-writing reference; available only when dynamic workflows are enabled. Requires v2.1.248+. [line 142] [Source]
• MCP prompt command discovery text simplified, no longer inlining the /mcp__server__prompt naming format (see the mcp.md listing-format change below). [line 156] [Source]

corporate-launcher [Source]

• Removed the statement that a launcher running far past budget is "treated as a stalled start and restarted" — that behavior is no longer documented. [line 100] [Source]

costs [Source]

• Session cost figures now apply the 1.1× data-residency multiplier to responses billed at that rate, matching the status line and --max-budget-usd; before v2.1.239 this multiplier wasn't applied to the displayed cost. [line 25] [Source]
• New: /usage shows a Prompt cache (main) line summarizing the session's prompt-cache hit ratio, misses, and warm/cold state. Requires v2.1.251+. [line 29] [Source]
• Hook-verification instructions now use claude --debug-file and describe a modified tool input keys log line, replacing a reference to claude --debug with a command-only key list. [line 274] [Source]

cross-session-messaging [Source]

• Behavior change: @ mentions in cross-session messages no longer auto-attach files/MCP resources — they now always arrive as plain text, whether the message starts a new turn or arrives mid-turn. Before v2.1.251, an @ mention that started a new turn did attach the file/resource. [line 58] [Source]

debug-your-config [Source]

• /context's skills section now also includes bundled skills, which /skills itself doesn't list. [line 8] [Source]
• Clarifies that claude doctor (terminal, read-only) and /doctor (in-session, proposes and applies fixes) are distinct checks. [line 31] [Source]

desktop [Source]

• New: the receiving Claude in cross-session messaging can now reply, with the reply delivered back through the desktop surface — previously one-way. [line 312] [Source]
• With thinking turned off on the Anthropic API, Claude Code now sends effort high instead of a higher level to models that reject that combination (e.g. Opus 5). [line 560] [Source]

devcontainer [Source]

• Describes init-firewall.sh as limiting outbound traffic to allowed destinations, rather than "blocking all outbound traffic except allowed domains." [line 117] [Source]

env-vars [Source]

• New CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS variable: sets the deadline for the first byte of a streaming response. Requires v2.1.242+. [line 374] [Source]
• CLAUDE_ENABLE_BYTE_WATCHDOG=0 now also disables the new first-byte deadline; CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1 now also enables it for Bedrock streaming requests. [lines 368-369] [Source]
• MAX_THINKING_TOKENS: with thinking off on the Anthropic API, Claude Code now sends effort high instead of a higher level to models it knows reject that combination (e.g. Opus 5). [line 414] [Source]
• Restructured which sessions skip feature-flag fetching into an explicit list (third-party provider, Claude apps gateway, or opt-out env vars). [line 465] [Source]

errors [Source]

• New error: No response from API — Claude Code now aborts a streaming request if no response headers arrive within a first-byte deadline (rather than waiting the full API_TIMEOUT_MS), retries once, then fails with this message. Requires v2.1.242+. [line 321] [Source]
• New error: Effort isn't available with thinking turned off — running above effort high with thinking off is now rejected client-side; before v2.1.251 Claude Code sent the request anyway and Opus 5 rejected it every time. [line 1550] [Source]
• New error: Invalid --agents configuration — --agents JSON is now validated at startup (parse errors, schema mismatches, names starting with -), exiting with code 1; skippable via --safe-mode/--resume/--continue/CLAUDE_CODE_SAFE_MODE. Requires v2.1.242+. [line 1705] [Source]
• New error: Cloud sessions cannot be created from a --restricted session — --restricted sessions now refuse to create cloud sessions client-side. [line 1725] [Source]
• New error: Not carried over to the sessions Remote Control starts — a global claude flag placed before the remote-control verb that would affect spawned sessions (e.g. --settings, --mcp-config) now stops the command instead of silently dropping it. Requires v2.1.248+. [line 1802] [Source]
• New error: Server rejected the Authorization header minted by the configured headersHelper — a 401/403 from an MCP server whose headersHelper supplies Authorization is now reported distinctly, with OAuth fallback disabled. [line 1879] [Source]
• New error: The GitHub App preflight failed transiently — a transient GitHub reachability check failure during cloud-session bundle upload now suggests retrying instead of pointing at GitHub setup, which it did before v2.1.251. [line 2056] [Source]
• New error: Path escapes plugin directory — component paths in plugin.json or a marketplace entry that resolve outside the plugin directory are now rejected; before v2.1.251 a marketplace-declared commands path could still load from outside the plugin. [line 2219] [Source]
• New error family: Refusing to read, write, or search a path — Claude Code now re-confirms a path's symlink resolution at the moment a tool opens/searches it, not just at write time as before v2.1.251, refusing when resolution changed, a parent-directory symlink changed, the target is itself a symlink, a Read-deny-rule path changed mid-search, the search root couldn't be opened, the permission check expired under concurrency, or ripgrep couldn't be resolved to an absolute path. [line 2423] [Source]
• New warning: Remote managed settings failed to load — interactive sessions now show a warning (with cause and cached-vs-no-policy status) when a server-managed-settings fetch fails; before v2.1.248 this was debug-log-only. [line 2881] [Source]

fast-mode [Source]

• /fast can now be run while Claude is working; the toggle applies without waiting for the turn to end, though the running turn keeps its original speed, and a forced model switch (for models without fast mode) applies from the next request in that turn. [line 23] [Source]

feature-availability [Source]

• Splits the platform-restricted commands list into per-command bullets and drops /radio from it, matching the commands.md change that makes it available everywhere. [lines 32-35] [Source]
• New: gateway feature availability is now qualified — whenever ANTHROPIC_BASE_URL points somewhere other than api.anthropic.com, Claude Code itself turns off features like Remote Control and server-managed settings regardless of what the gateway forwards. [line 85] [Source]
• /radio removed from the "Not available" feature list on three of the provider-specific tabs, consistent with the commands.md change above. [lines 97, 105, 121]

gateways [Source]

• Removed the claim that forceLoginMethod: "gateway" disables Anthropic-bound analytics from startup before sign-in — simplified to say analytics are disabled once the session signs in (matches the claude-apps-gateway-deploy.md reversal above). [line 50] [Source]

hooks-guide [Source]

• Distinguishes a new failure mode: stdout that looks like JSON but fails to parse is now a separate non-blocking error case from stdout that parses but fails schema validation. [line 572] [Source]
• New troubleshooting tip: build hook JSON output with a JSON encoder like jq instead of string concatenation, to avoid parse failures from unescaped quotes/backslashes. [lines 918-919] [Source]

hooks [Source]

• Hooks intro now lists MCP tool calls and subagents as additional hook mechanisms, alongside shell commands, HTTP endpoints, and LLM prompts. [line 5] [Source]
• New behavior: if a hook's working directory no longer exists mid-session (e.g. a deleted worktree/temp dir), Claude Code now falls back to the session's start directory, then project root, home directory, or system temp directory, logging a warning. [line 379] [Source]
• New Bash if-matching rules: a substitution at any argument position is checked (e.g. echo before $(date) after), and an unresolvable command-name expansion (e.g. $TOOL git push) now runs the hook regardless of pattern. [lines 404-405] [Source]
• effort field in hook JSON now documented as the level "in effect when the hook runs," rather than "active for the turn," linking to how a downgraded level is chosen. [line 663] [Source]
• JSON-vs-plain-text stdout detection changed: now requires stdout to both start with { and end with } (previously just start with {), with new rules for multi-line JSON-looking output. A new "parse failure" outcome (JSON-looking but invalid) is now a distinct non-blocking error on any exit code other than 2; before v2.1.248 such stdout was treated as plain text. [lines 707, 712]

interactive-mode [Source]

• New section: /model, /effort, and /fast now run immediately rather than queueing until the turn ends, each with its own rule for whether the change applies to the current turn or only the next one. [line 325] [Source]

llm-gateway-connect [Source]

• Notes that before v2.1.196, a non-Anthropic base URL didn't block Remote Control; it does now. [line 243] [Source]
• claude doctor's Remote Control section now names whatever is currently blocking Remote Control, not just the credential variable. [line 244] [Source]
• Gateway model-discovery debug logging changed: Claude Code now logs the cached model count only the first time discovery succeeds and again only when the gateway's list changes, instead of every time. [line 283] [Source]

llm-gateway-protocol [Source]

• New capability-gap row: prompt caching has no beta pairing but relies on cache_control markers on system/messages blocks; a gateway that drops them silently bills the whole conversation as uncached with no error. [line 114] [Source]
• Automatic retry/error-forwarding now also covers a cache_control marker rejected by the upstream, previously limited to thinking, thinking signatures, and mid-conversation system messages. [line 121] [Source]
• Model-discovery request now sends both Authorization and x-api-key credential headers (omitting whichever doesn't resolve), and waits for an apiKeyHelper to return before sending. Requires v2.1.248+ (earlier versions sent only one header); discovery is now skipped entirely, with a debug-log line, when neither header resolves. [lines 150, 156]

managed-settings [Source]

• New: when a managed policy key isn't applying and it was deployed via server-managed settings, claude doctor now reports the fetch outcome. [line 235] [Source]

mcp-quickstart [Source]

• New /mcp status indicator: ⊘ Disabled for this project (re-enable via /mcp), for a server turned off by the project's disabledMcpServers list. [line 61] [Source]

mcp [Source]

• Authentication-error retries: an MCP server whose headersHelper is the sole source of Authorization is now retried on an auth error, rather than treated as a fixed configuration error. [lines 331, 847-848]
• Per-request timer for HTTP/SSE/connector servers now computed as the greatest of 60 seconds, the applicable tool timeout, and MCP_TIMEOUT, replacing a different, narrower rule. [line 362] [Source]
• New: a 401/403 from a server whose Authorization header you configured yourself (via headers or headersHelper) no longer flags the server as "needing authentication" — it's reported as a failed connection instead. [line 633] [Source]
• New: connectors whose authentication your organization manages in claude.ai now show a managed badge in /mcp and /plugin (cosmetic only). [line 994] [Source]
• New: elicitation URL-mode requests now have a documented length cap (roughly 8,000 chars for a plain URL, ~4,000 for one dense with percent-escapes); over the cap you can only decline. [line 1195] [Source]
• MCP prompt listing format changed: prompts now appear as /servername:promptname (MCP) in the command menu, with the old /mcp__server__prompt form still working but no longer the primary listing. Server-name normalization for that fallback form now replaces any character outside A-Z a-z 0-9 _ - with _ (previously just spaces), and prompt names are used as declared rather than normalized. [line 1329] [Source]
• Prompt argument parsing changed: arguments are now split strictly on whitespace (each argument a single token), so a previously shown quoted multi-word argument example no longer works as written; the example was updated to a single-token value. [lines 1343, 1350]

model-config [Source]

• With thinking turned off on the Anthropic API, Claude Code now sends effort high instead of a higher level to models that reject that combination (e.g. Opus 5). [line 484] [Source]

monitoring-usage [Source]

• Debug-log OTel errors are now prefixed [3P telemetry] to distinguish them from Anthropic's own [Anthropic telemetry] operational lines, which don't indicate a setup problem. [lines 33, 1174]

network-config [Source]

• New fourth streaming timer, the first-byte deadline, covering the wait for response headers before any bytes arrive; runs on the direct Anthropic API and Claude Platform on AWS by default, is opt-in on Bedrock, and doesn't run on GCP Agent Platform/Microsoft Foundry. Default 180s (Anthropic API) / 300s elsewhere, plus 1s per 32KB of request body. New CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS variable sets the deadline directly. [lines 153, 157, 167]
• New: Claude Code never routes its WebSocket connections to localhost/::1/127.0.0.0/8 through a proxy, so no NO_PROXY loopback entry is needed. [line 30] [Source]
• Changelog fetch behavior changed: interactive sessions now also fetch raw.githubusercontent.com in the background at startup when the cached changelog doesn't cover the running version (e.g. right after an update), not only when /release-notes is invoked. [line 190] [Source]

permission-modes [Source]

• New: in a --restricted session (v2.1.248+), the auto-mode classifier can no longer approve protected-path writes. [line 429] [Source]

permissions [Source]

• New: Claude Code now re-confirms a path still resolves to the location a permission check approved when a tool actually opens the file, tied to the new symlink-refusal errors above. [line 349] [Source]
• Clarifies that Grep/Glob apply Read deny rules to the resolved search directory. [line 350] [Source]

plugin-marketplaces [Source]

• New: a marketplace-entry commands/agents path resolving outside the plugin directory (e.g. ./../shared.md) is now rejected with a path escapes plugin directory error, loading the rest of the plugin without that component; previously such a path could load. [line 681] [Source]

plugins-reference [Source]

• Path-traversal protection now explicitly covers paths declared in plugin.json as well as marketplace entries, rejecting any that resolve outside the plugin root with a path escapes plugin directory error. [line 749] [Source]

prompt-caching [Source]

• Major behavior change: the mid-conversation system-context block (e.g. file-change notices) is now marked for caching on every provider and connection, including gateways and custom ANTHROPIC_BASE_URL setups that previously left it uncached. [line 38] [Source]
• New table of gateway cache_control handling outcomes: forwards unchanged (fully cached), rejects with 400 (Claude Code moves the marker to the last message, keeping conversation caching), or silently strips markers (bills as fully uncached). [line 42] [Source]
• New: a subagent's experimental.cacheTtl frontmatter value now ranks above ENABLE_PROMPT_CACHING_1H in the TTL-selection precedence order, ignoring 1h while on usage credits. Requires v2.1.248+. [line 219] [Source]
• New: /usage's Prompt cache (main) line and the status line's prompt_cache object now surface per-session cache-hit statistics. Requires v2.1.251+. [line 243] [Source]

remote-control [Source]

• Reconnection after an interruption now also queues permission prompts, previously only messages and status updates. [line 11] [Source]
• New claude remote-control flags: --permission-mode <mode> (starting permission mode for spawned sessions) and --debug-file <path>. [lines 55-56] [Source]
• New restriction: a global claude flag placed before the remote-control verb is now either silently dropped (if known harmless, e.g. --verbose, --model) or causes a refusal naming the flag (e.g. --settings); before v2.1.248 any flag before the verb broke option parsing entirely. [line 60] [Source]
• VS Code extension UI changed: Remote Control status is now shown via a footer indicator (click to open the session) rather than a banner. [line 96] [Source]
• New: a connected device's diff pane now works in every session type, not just sessions served by claude remote-control, showing uncommitted changes or, if the tree is clean, the branch's changes since diverging from default. [line 145] [Source]
• New: while Remote Control is off in a second terminal (after resuming elsewhere), that terminal's Claude also can't see or be reached via cross-session messaging from other machines. [line 177] [Source]

sandboxing [Source]

• Default sandbox write access widened: now includes any directories added with --add-dir//add-dir, not just the working directory and session temp dir. [lines 40, 129]
• Permission prompts for commands that fall back to unsandboxed execution are now titled "Bash command (unsandboxed)" instead of "Bash command." [line 40] [Source]

self-hosted-environments-deploy [Source]

• SIGTERM shutdown now terminates each session's whole process tree, including commands Claude was still running, not just the child process. [line 296] [Source]
• New troubleshooting entry: Poll failed ... rejecting the malformed poll response — the runner now detects and rejects poll responses it can't parse (e.g. from an intercepting proxy) instead of, before v2.1.246, treating them as an empty queue and potentially ending live sessions. [line 415] [Source]

self-hosted-environments-reference [Source]

• New --client-label / SELF_HOSTED_RUNNER_CLIENT_LABEL flag to label a runner at registration, surfaced in the client_label metric. Requires v2.1.248+. [line 17] [Source]
• --kill-session-after-min now documented as terminating the full process tree, with its mid-turn deferral bounded by the new SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS variable (default 900000ms). [lines 31, 85]

self-hosted-environments [Source]

• Poll-retry logic now also triggers on a response the runner can't parse, not just timeouts/lost requests, e.g. from an intercepting proxy. [line 75] [Source]

server-managed-settings [Source]

• New: claude doctor's Managed settings (remote) line reports one of four fetch outcomes (loaded / none configured / failed with cause / skipped with reason). Requires v2.1.248+. [line 83] [Source]
• Startup fetch behavior changed: when a developer signs in at startup, Claude Code now waits up to 5 seconds for the settings fetch before opening the session, enforcing the policy from the first screen if it arrives in time; other startups proceed without waiting as before. [line 138] [Source]
• New: interactive sessions now show a warning when the startup settings fetch fails outright ("no remote policy applies") or falls back to cached settings ("cached policy is in effect"). [lines 140, 147]
• New: API_FORCE_IDLE_TIMEOUT now only needs security-dialog approval for non-truthy values (a truthy value, which only enables the safe default idle timeout, applies silently); before v2.1.248 any non-empty value triggered the dialog. [line 234] [Source]

settings-reference [Source]

• sandbox.filesystem.allowWrite default now includes --add-dir//add-dir directories. [line 1194] [Source]
• gitCommitCoAuthor default now has three cases instead of two: a confirmed Claude model name, Claude alone for an unconfirmed-but-recognized Claude model, and Claude Code for an unrecognized/third-party model ID. [lines 3147-3148] [Source]
• cloudEnvironment default fallback logic updated to match the new bridge-environment-aware rule in cloud-environments.md. [line 4612] [Source]
• forceRemoteSettingsRefresh clarified: even when false (default), Claude Code now waits up to 5 seconds for the fetch at a sign-in startup. [line 5102] [Source]

skills [Source]

• Clarifies that some bundled skills are conditionally available, e.g. /workflow-authoring only when dynamic workflows are enabled — previously stated bundled skills are simply "available in every session." [line 14] [Source]
• New parsing rule: skill frontmatter is only read when the opening --- is the file's very first line; otherwise the whole file is treated as skill content. [line 290] [Source]

statusline [Source]

• Status line now also refreshes when a warm prompt cache reaches its expires_at time. [line 136] [Source]
• New rate_limits.spend_limit fields (used_percentage, which can exceed 100; resets_at) for gateway spend limits. Requires v2.1.251+. [line 178] [Source]
• New prompt_cache object in the status line JSON input, with fields warm, caching_observed, ttl, expires_at, requests, misses, expected_rebuilds, hit_ratio, cache_write_tokens, miss_recache_tokens, last_miss_at, recache_tokens_if_cold. Requires v2.1.251+. [lines 179, 344]

sub-agents [Source]

• Clarifies that each top-level key in --agents JSON is the agent's name, and names must not start with -. [line 189] [Source]
• New frontmatter field experimental.cacheTtl (5m or 1h) to set a subagent's own prompt-cache TTL; ignores 1h on usage credits, and is only read from subagent files. Requires v2.1.248+. [line 258] [Source]
• New subagent-file skip condition: an opening --- that isn't the file's first line is now treated as no frontmatter (a plain documentation file). [line 276] [Source]
• New: a background subagent can leave a background Bash/PowerShell command running past its own turn's end, and Claude Code notifies the subagent when that command finishes. [line 754] [Source]

terminal-config [Source]

• New theme color key effortUltra, for the ultracode tag on the input border; overrides take effect on v2.1.239+. [line 213] [Source]
• diffAddedDimmed/diffRemovedDimmed redefined as specifically the dimmed diff shown after you reject an edit, rather than generic "unchanged context near changed lines." [lines 223-224] [Source]

ultrareview [Source]

• Branch-review uploads now follow the same credential/secret-file exclusion rules as cloud-session uploads for uncommitted changes. [line 22] [Source]

workflows [Source]

• New parallel() function documented: runs a set of agent tasks concurrently and waits for all of them, alongside the existing agent() and pipeline(). [line 277] [Source]
• New "Edit a saved script" section: run /workflow-authoring before hand-editing a saved workflow's .js file, then /reload-skills and re-run /<name>; documents rules Claude Code enforces on load (fixed meta block shape, allowed body calls, phases entries must match phase() titles exactly, and Date.now()/Math.random()/no-arg new Date() now throw inside scripts to keep resumed runs deterministic). [lines 280, 286, 289]
• New: Claude can only start a workflow from a script file the session is already allowed to read; scripts outside the working directory need /add-dir or a Read allow rule first. [line 297] [Source]
• New hard cap: up to 4,096 items per parallel()/pipeline() call, rejected with an error beyond that; previously uncapped/undocumented. [line 317] [Source]
• Disabling workflows now also disables the /workflow-authoring skill. [line 381] [Source]