Claude docs changes for September 4th, 2026 [diff]
Executive Summary
- A large swathe of the API guides regained content that had been missing from their Markdown source — code examples, language tabs and FAQ sections across
develop-tests(+505 lines),prompt-caching(+404),increase-consistency(+332),text-editor-tool,bash-tool,computer-use-tool,handle-tool-calls,structured-outputsand more - New
--permission-prompts noneflag for unattended runs: denies anything that would prompt, removesAskUserQuestionfrom the session entirely, cancels unanswered MCP elicitations, and tells Claude not to retry - Auto mode now asks once before the first file read outside the working directories, and answering "block from now on" writes
permissions.blockReadsOutsideWorkingDirectories: trueto your user settings — which then refuses such reads in every mode,bypassPermissionsincluded - A managed settings document that can't be parsed as a JSON object now makes Claude Code refuse to start — deliberately failing closed, even when another admin source carries a valid policy
- On Fable 5.1 with an API key or Claude subscription, changing effort mid-session no longer invalidates the prompt cache (2.1.260), and two new weekly "What's new" pages land for weeks 33 and 34
New Claude Code versions
2.1.260
New features
- Added a diff panel that opens beside the conversation in fullscreen mode and shows uncommitted changes as Claude edits; toggle it with
/diff - Added a likely cause for prompt-cache misses to
/costand the status line'sprompt_cachefield - Added
/reload-pluginsto headless sessions, so it appears in the Desktop and SDK command lists - Added a text form of
/advisorfor the desktop app, Remote Control and other headless sessions - Added
oidc.scope_on_refreshto the Claude apps gateway for IdPs that return an id_token on refresh only when asked foropenidagain
Existing feature improvements
- Improved
/efforton Claude Fable 5.1 so changing effort mid-session no longer invalidates the prompt cache - Improved auto-compact for 1M-context models: Opus and Fable sessions compact shortly before the 1M limit, and recovery compaction on very large contexts no longer times out at 10 minutes
- Improved deleting a background session whose worktree has unpushed commits: the message names the branch and commit count, and deleting again discards the worktree
- Improved
/ultrareviewto wait up to 45 minutes for long-running cloud reviews, up from 30 - Improved idle CPU usage of non-interactive sessions
- Changed
ctrl+l/cmd+kin fullscreen to clear the transcript view like a terminalclear - Changed a managed CLAUDE.md (
claudeMd) to no longer trigger the security approval dialog - Changed commands typed at the
!bash-mode prompt to run outside the sandbox even under strict sandbox mode - Changed permission rules with text after the closing parenthesis to be reported as invalid rather than silently ignored
- Removed the one-hour time limit on background commands started by subagents
Major bug fixes
- Fixed
Edit/Write/Readpermission rules whose path contains parentheses being dropped as invalid or ignored by the Bash sandbox, which left "read-only" folders writable - Fixed one file permission rule with an uncompilable pattern making every file edit fail with
Invalid regular expression - Fixed Bash permission checks auto-approving zsh commands hiding a command substitution in a
REPORTTIME,REPORTMEMORYorDIRSTACKSIZEassignment - Fixed prompt caching on Claude Fable 5.1 not covering the context attached after tool results, so it was re-sent uncached on every tool-call turn
- Fixed the
/modelpicker not showing Fable 5.1 for organizations that can use it - Fixed
model: fableagents ignoring the[1m]tag on anANTHROPIC_DEFAULT_FABLE_MODELpin and silently running at 200K - Fixed
permissions.blockReadsOutsideWorkingDirectorieson macOS hiding the user's git config from sandboxed git - Fixed Bedrock model discovery and AWS SSO/STS calls failing with "unable to get local issuer certificate" when the corporate root CA is only in the OS certificate store
- Fixed
/rewindreporting success when checkpoint backup files were missing and nothing was restored - Fixed managed
skillOverrideskeyed on a bundled skill's alias not applying, andSkill(name)deny rules not covering a nested skill - Reverted the 2.1.259 change applying
Read()deny rules to Bash arguments, which deniednpm run buildunder aRead(./**/build/**)rule in every mode
Claude Code changes
New Documents
whats-new/2026-w33 [Source]
Week 33 (August 10–14, v2.1.225 → v2.1.233): auto-continue when usage limits reset, fork mode on by default (CLAUDE_CODE_FORK_SUBAGENT=0 to turn it off), and GitLab merge requests and marketplaces — bare gitlab.com marketplace clones including nested subgroups, —worktree from a merge request URL, !N labels in claude agents, and redaction of glpat-/glrt- token families.
whats-new/2026-w34 [Source]
Week 34 (August 17–21, v2.1.234 → v2.1.239): the /design skill bringing Claude Design's artboard workflow into the CLI (research preview), the Concise built-in output style, and Remote Control leaving research preview with machines appearing as device cards at the top of the Code tab in the Claude app. Plus a long "Other wins" list including the spellcheck setting, the MR !N GitLab badge, opening /permissions while Claude is working, ANTHROPIC_DEFAULT_MODEL, notify_when_idle on SendMessage, keybindingFlavor: "readline", and cross-session messaging on native Windows.
Changed documents
advisor [Source]
- Toggling
/advisormid-session does not invalidate the main model's prompt cache, unlike switching models; the advisor's guidance is cached as part of the transcript on later turns. [line 127] [Source]
agent-sdk/python [Source]
- New
terminal_reasonfield on results, with"aborted_streaming"and"aborted_tools"marking a turn aborted before completing — commonly byinterrupt()or a permission callback denying withinterrupt=True. [line 1540] [Source]
claude-apps-gateway [Source]
- A running gateway serves its own protocol reference at
GET /protocol, covering SSO sign-in, inference, managed settings delivery, model discovery and telemetry — a separate document from the general compatibility guide. [line 35] [Source]
cli-reference [Source]
cloud-environments [Source]
- New API credentials feature, on Pro and Max plans only: store a key once on the environment and the agent proxy attaches it to requests for hosts you list, so sessions never see it. Environment variables, by contrast, are readable by anyone who uses the environment. Team and Enterprise plans don't have this yet, so the section doesn't appear there. [lines 63-68] [Source]
- Shared organization environments documented as editable by an Owner from the environment selector and read-only to other members, with an explicit warning against secrets in their variables. [lines 143-144] [Source]
errors [Source]
- New "Managed settings document could not be parsed" section. Claude Code exits with code 1 at startup when a deployed managed document is present but unparseable, naming the source — a file path, a macOS managed preferences profile, or the HKLM registry value. It refuses even when another admin source delivers a valid policy, and the page states the reasoning plainly: settings it can't parse can't be enforced, so starting anyway would run sessions without the organization's controls. An empty
managed-settings.jsoncounts as{}and doesn't block launch. [lines 2931-2952] [Source] - Cut-off responses now have four cases where Claude Code handles the failure without showing the incomplete-response notice, including prompting a subagent to continue — before v2.1.257 a subagent showed the notice on the first cut-off. [lines 367-372] [Source]
headless [Source]
- New "Turn off permission prompts in unattended runs" section.
--permission-prompts nonematters most when the run has a permission host — an SDKcanUseToolcallback or a--permission-prompt-tool— because without it the run waits on that host. With the flag, Claude Code removes tools needing a human answer such asAskUserQuestionso Claude can't call them, cancels any MCP elicitation noElicitationhook answers, and tells Claude not to retry. Permission rules,PermissionRequesthooks and the permission mode still decide every call first. [lines 243-256] [Source]
llm-gateway-protocol [Source]
- Retitled "Claude Code gateway compatibility guide" and positioned as the operator reference across the gateway pages: what Claude Code sends, the headers and fields to forward, and what breaks when they're stripped. [lines 1-4] [Source]
llm-gateway-rollout [Source]
- Rate-limit sizing guidance: account for the client retrying transient failures,
429s included, up to 10 times with backoff while honoringRetry-After. [line 234] [Source]
managed-settings [Source]
- A precise account of the validation ladder: individual repairable entries are skipped with a warning, then any top-level key still failing is dropped, and every remaining valid key is enforced. A
policyHelper'smanagedSettingsis held to a stricter standard — any surviving schema violation fails the whole run and refuses startup. [lines 241-242] [Source] - Exactly what makes each source unparseable, and the three states that don't cause a refusal: an absent source, an empty file (
{}), and a malformed value in the user-writable HKCU key, which is reported as a notice instead. [lines 243-253] [Source]
model-config [Source]
- New troubleshooting section "A new session starts on a different model than you picked", with four causes — a one-session choice (
s,--model,/modelin-p), something higher-priority setting the model, a~/.claude/settings.jsonClaude Code couldn't write to, and resuming a session that keeps its own model. [lines 163-170] [Source]
permission-modes [Source]
- New "The first read outside the working directories" section. In auto mode, the first Read, Grep or Glob on an outside path asks you once. "Block from now on" writes
permissions.blockReadsOutsideWorkingDirectories: trueinto your user settings, which makes the file tools refuse such reads in every later session and every permission mode — reversible only by/add-diror removing the setting. The prompt never appears in-pruns or background sessions. [lines 326-334] [Source] - Reads fenced by that setting are added to the actions no mode auto-approves — they prompt even in auto mode and
bypassPermissions. [line 32] [Source]
permissions [Source]
- The built-in read-only Bash command set is now explicitly fenced by
blockReadsOutsideWorkingDirectories. [line 209] [Source] - Plan mode no longer substitutes sandboxed commands; built-in read-only commands still run unprompted, and a bare
Bashask rule makes every command prompt, sandboxed read-only ones included. Before v2.1.212 the substitution applied in plan mode too. [line 496] [Source]
prompt-caching [Source]
- New "Changing effort level" guidance. On most models a mid-session effort change recomputes the entire request, so Claude Code asks you to confirm while the cache is warm. On Fable 5.1 with an API key or Claude subscription the cache survives and no confirmation appears — but not on Bedrock, Agent Platform or a Claude apps gateway, nor under
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASor a HIPAA configuration. Before v2.1.260 it invalidated the cache there too. [lines 73-75] [Source]
sandboxing [Source]
- To be prompted on every unsandboxed retry even in auto mode, add an ask rule for
Bash(dangerouslyDisableSandbox:true). [line 119] [Source] - Recommends
blockReadsOutsideWorkingDirectoriesover hand-written path rules for denying sandboxed commands access to home directories and mounted volumes. [line 178] [Source]
server-managed-settings [Source]
- A managed CLAUDE.md via
claudeMdno longer requires approval, on the reasoning that it's instruction text rather than a command Claude Code runs — permissions still gate the tools Claude uses while following it. Before v2.1.260 it required approval. [line 202] [Source]
settings-reference [Source]
- New
permissions.blockReadsOutsideWorkingDirectoriesentry: refuses outside reads through Read, Grep, Glob and LSP in every permission mode includingbypassPermissions, and makes a recognized file-reading Bash command such ascatprompt even in auto mode. Requires v2.1.257. [lines 957-960] [Source] - The settings count rose to 223. [line 19] [Source]
security [Source]
- The working-directory boundary now covers reads: in Manual mode Claude Code asks before reading outside it with Read, Grep and Glob. [line 20] [Source]
hooks [Source]
PermissionRequesthooks documented as receiving apermission_suggestionsarray, which a hook can echo back as its ownupdatedPermissionsoutput — with the caveat that the array isn't an exact list of the options a user sees. [lines 1677-1756] [Source]
monitoring-usage [Source]
- The retention sweep pauses with
result: "skipped"and askip_reasonwhen the retention period can't be determined safely; a managedcleanupPeriodDayspins it and lets the sweep run even when a lower-priority settings file is broken. [line 1043] [Source]
claude-code-on-the-web [Source]
- API credentials added to the list of things that stay outside the sandbox, attached to matching requests after they leave the session — Pro and Max only. [line 266] [Source]
API changes
Changed documents
The dominant change on the API side is a restoration: a dozen guide pages regained substantial content that had been absent from their Markdown source — worked code examples with their Python/TypeScript/C#/Go/Java/PHP/Ruby language tabs, request and response bodies, and FAQ sections.
test-and-evaluate/develop-tests [Source]
- The page grew from 124 to 629 lines, gaining its full grading-method walkthrough: exact match, cosine similarity with SBERT, ROUGE-L, LLM-based Likert scale, binary classification for PHI detection, and ordinal scales for context utilization — each with what it measures, example test-case counts, and runnable code. [lines 123-441] [Source]
- Also regained the criteria questions that open the page: task fidelity, consistency, relevance, tone and style, privacy preservation, context utilization, latency and cost. [lines 61-89] [Source]
build-with-claude/prompt-caching [Source]
- Regained its worked examples and FAQ, including the four-breakpoint example and the advice that a single breakpoint at the end of your static content is usually sufficient — place it on the last block that stays identical across requests. [lines 877-932] [Source]
- An easily-missed point is now spelled out:
input_tokensdoes not represent all input tokens, only the portion after your last cache breakpoint, so with a 200k document cached it will look much smaller than your real input. [lines 946-967] [Source] - The 5-minute TTL is measured from the start of the request that writes or reads the entry, not the end of its response, so generation time eats into the reuse window — a reason to reach for the 1-hour TTL when responses are long. [lines 977-979] [Source]
- Cache breakpoints themselves are free; only cached and read content is billed, so the number of breakpoints doesn't affect pricing. [lines 936-942] [Source]
- Tool-definition caching documented: place
cache_controlon the last tool intools, and everything up to and including it caches as one prefix. [lines 677-712] [Source]
agents-and-tools/tool-use/bash-tool [Source]
- Regained its request and result examples, including the
restartinvocation and the timeout error shape. [lines 100-333] [Source]
agents-and-tools/tool-use/text-editor-tool [Source]
- 179 net-new lines of command examples and error handling, taking the page from 515 to 738 lines.
agents-and-tools/tool-use/handle-tool-calls [Source]
- 139 net-new lines restoring the worked tool-result loop across every SDK language.
agents-and-tools/tool-use/computer-use-tool [Source]
- 102 net-new lines of action examples and screenshots handling.
build-with-claude/structured-outputs [Source]
- Regained the empty-response troubleshooting (common causes and prevention) and the explicit list of supported and unsupported regex features. [lines 81-450] [Source]
strengthen-guardrails/increase-consistency [Source]
- 332 lines restored, the largest gain outside
develop-tests.
cli-sdks-libraries/cli/scripting [Source]
- Moved in the other direction, shrinking from 236 to 159 lines: the YAML-resource version-control walkthrough — defining a
summarizer.agent.yamland creating it withant beta:agents create— was removed from this page.
cli-sdks-libraries/sdks/go [Source]
- 173 net-new lines of Go SDK examples.