Claude docs changes for September 12th, 2026 [diff]
Executive Summary
claude plugin evalarrives with a 625-line manual of its own. Write realistic prompts plus graders, run each case three times with your plugin and three times without, and read theΔthat says what the plugin actually contributed — with CI gating, cost ceilings, MCP mocking and a documented sandbox- Glob and Grep are no longer in the default tool set on macOS, Linux and WSL. Claude searches with
findandgrepthrough Bash instead (running embeddedbfsandugrep), so those searches now reach your hooks and permission rules asBashcalls - OpenTelemetry gains repository identity:
OTEL_METRICS_INCLUDE_REPOSITORY=truetags metrics and events withvcs.*attributes derived from theoriginremote, alongside a set of new "safe" bounded attributes (tool_name_safe,query_source_safe,bash_argv0,error_class) that carry no user-chosen names - Cloud sessions' GitHub access rewritten: a browser GitHub App connection now reaches private repositories only where the App is installed, while
/web-setupreaches anything yourghtoken can.claude --cloudfalls back to uploading a local bundle in more cases, including a github.com repo without the App - Claude Desktop no longer puts every session in a worktree — it's a worktree option next to the branch name — and Windows no longer requires Git just to open the Code tab
New Claude Code versions
2.1.269
New features
- Added
claude plugin eval: run a plugin's eval suite and get scored, reproducible results as JSON and an HTML report - Added
/output-style [name]to list and switch output styles, including over Remote Control and in cloud and other headless sessions - Added a diff of the files a Bash command changed to the Bash tool result, under the
bashEditDiffEnabledsetting - Added
OTEL_METRICS_INCLUDE_REPOSITORYforvcs.*repository attributes; commit events getvcs.ref.head.*withOTEL_LOG_TOOL_DETAILS - Added
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MSto extend the LLM gateway/v1/modelsdiscovery timeout past its 3s default - Added
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS(1–256) to raise the Workflow tool's per-run concurrent agent limit
Existing feature improvements
- Improved keyboard support over SSH and in unrecognized terminals: terminals answering the kitty keyboard query, such as foot and Alacritty 0.16+, now get Shift+Enter and Ctrl+Shift shortcuts without
/terminal-setup - Improved responsiveness in long sessions by no longer re-processing the whole conversation to build collapsed tool-use summaries
- Improved prompt suggestion filtering for Japanese, Chinese and Korean text
- Changed
/ultrareview --postto post the PR comment directly when findings arrive instead of starting a second cloud session - Changed skills synced from claude.ai in cloud sessions to be named
anthropic-skills:<name>, matching Claude Desktop - [VSCode] Added an agent map behind an "N agents" footer pill, with per-agent cards, Stop agent, and read-only transcripts
- [VSCode] Added Hooks and Permission rules dialogs for viewing and editing user, project and local settings; managed, plugin and session entries stay read-only
Major bug fixes
- Fixed a deny or ask permission rule starting with
!applying beyond the settings source that wrote it; such a rule now applies only within its own source, and a bare!negation is ignored - Fixed
Edit()deny rules and the write-path check not applying to the file a Bashteecommand writes - Fixed plugin archives extracted for a session being readable by other local users, files keeping world-writable bits, and stale files surviving re-extraction
- Fixed the prompt cache being partially invalidated on the turn after a response was cut off at the output-token limit and resumed
- Fixed sessions getting permanently stuck on "Prompt is too long" when auto-compaction had no complete earlier exchange to summarize
- Fixed
/goalruns silently stalling after API errors, network drops or token limits; the goal now retries with backoff or pauses and says why - Fixed the git status Claude is told after a compaction being the one from session start rather than the current status
- Fixed the attribution reminder overriding a CLAUDE.md or memory rule against commit and pull request attribution
- Fixed
permission_denialsin--output-format stream-jsonomitting Read, Edit and Write calls blocked by a path-scoped deny rule - Fixed F1/F2/F4 in kitty-protocol terminals, Delete in st, Alt+arrows in rxvt-unicode, and Shift+punctuation in WezTerm (a 2.1.247 regression)
- Fixed
CLAUDE_CODE_RESUME_INTERRUPTED_TURNre-running a turn that had failed more than six hours earlier - Fixed organization plugins enabled through managed settings not loading in headless sessions and on Claude Desktop
- Fixed
/btwanswers containing made-up tool calls and output - Fixed CMYK JPEG images failing to attach with "cannot decode"
Claude Code changes
New Documents
plugin-evals [Source]
A complete guide to claude plugin eval, the new command for measuring whether a plugin actually steers Claude to the right outcome. It covers the whole surface:
- The scoring model. Each case is a prompt plus graders. A case runs three times by default, a run's score is the weighted fraction of graders that passed, and the case's score is the mean across runs. Crucially, every case also runs the same number of times without the plugin, producing
WITH,W/OUTandΔcolumns — a case scoring 1.0 in both arms proves the plugin isn't what made it pass. - Six grader types.
regex,tool_used,tool_orderandfile_existsare computed from the transcript and cost nothing;llmandbaselinecall a judge model. There are no custom-code graders. Guidance favoursregexover long output andllmonly over short output with concrete PASS/FAIL rubrics. - Baseline fairness. A
tool_used: Skillgrader can never pass without the plugin, so Claude Code excludes it from the score in both arms and reports it as an indicator only — otherwiseΔwould be inflated.arm: with-onlyandarm: bothcontrol this per grader. - Hard tool isolation. Runs never stop to ask for permission: ungranted tools such as
Bash,WriteandWebFetchare removed from the session entirely. GrantingBashputs every command under Claude Code's OS-level sandbox, and on a machine with no sandbox backend Claude Code refuses the run rather than running it unconfined — so native Windows needs WSL2 and Linux needsbubblewrapandsocat. - What a run can access. Each run gets a throwaway home, working directory and configuration, with no user settings,
CLAUDE.md, MCP servers, memory or other plugins. The case definitions are hidden from the agent. The page is blunt that this isolates the agent under test, not the plugin's own code: "a suite that passes says nothing about whether the plugin is safe." - CI usage, with
--trust-pluginto skip the trust prompt,--thresholdto gate the exit code,--max-cost-usdas a ceiling (exit 2 on a partial run), and pinned--modeland--judge-modelso a model rollout isn't mistaken for a plugin regression.
Changed documents
admin-setup [Source]
- The WSL
/statusinterpretation guide was replaced with a link to the managed-settings page's new "Read the source in /status" section. [line 74] [Source]
advisor [Source]
- A Fable 5.1 main model now accepts a Fable 5 advisor; the row no longer restricts it to "the same Fable version". [line 89] [Source]
agent-sdk/agent-loop [Source]
- Permission wording tightened throughout to distinguish tools from calls that need approval:
dontAsknow runs calls that need no approval indefaultmode, such as file reads inside your working directories, and denies only what would otherwise prompt. [lines 168-226] [Source]
agent-sdk/permissions [Source]
- The evaluation flow now documents that a call the tool approves on its own — a file read inside your working directories, a read-only Bash command — resolves without any rule. [line 38] [Source]
- New paragraph under the locked-down-agent example spelling out that
dontAskplusallowedToolsstill runs read-only Bash commands,Agent, and working-directory reads whether or not you list them. To put a tool out of reach entirely, use its bare name indisallowedTools. [line 94] [Source]
agent-sdk/typescript [Source]
- New "What
readFile()can read" section: it serves a narrower set than the Read tool — a regular file inside the session's working directories, plus a few of Claude Code's own session files.Readdeny and ask rules still block a path, and a broadReadallow rule doesn't widen it. Anything else resolvesnull. [lines 820-829] [Source] artifactReaddocumented as Claude Code's own bookkeeping that your code needn't act on, withverabsent when no version was recorded. [line 3669] [Source]- Correction: Claude Code doesn't emit the local-command-output message type at all. Sending
/contextor/usageas a prompt returns anSDKAssistantMessage. [line 5017] [Source]
artifacts [Source]
- A bare
WebFetchdeny or ask rule no longer turns artifacts off or blocks artifact reads — you need aWebFetch(domain:claude.ai)rule. [line 316] [Source]
authentication [Source]
- The list of per-key exceptions was replaced by a link, and the keys needing duplication narrowed to
forceLoginOrgUUIDplus the"claudeai"and"console"values offorceLoginMethod. [line 149] [Source]
claude-apps-gateway [Source]
- Two new unavailability rows:
/design-syncand/design-loginneed claude.ai, which the CLI doesn't contact on gateway sessions, and every feature that needs feature-flag fetching (such as/import) is off there too. [lines 408-409] [Source]
claude-code-on-the-web [Source]
- Reversal of a documented behavior. The page previously said a cloud session could access any repository the connecting account could see and that App installation "is not a session-level access control". The GitHub-authentication table now has a "Repositories sessions can reach" column: the GitHub App reaches any public repository plus private repositories it's installed on, while
/web-setupreaches anything theghtoken can. [lines 33-38] [Source] - The local-bundle fallback now also triggers for a github.com repository the Claude GitHub App isn't installed on — not just a repo with no remote — and applies even if you connected with
/web-setup. [line 98] [Source] - Bundle-created sessions can push back to a GitHub remote when your connection has push access, replacing the flat "can't push back". [line 113] [Source]
- Sending a GitLab or Bitbucket repository to a cloud session now explicitly requires
CCR_FORCE_BUNDLE=1. [line 332] [Source]
cli-reference [Source]
--tools "default"now means "the default set" rather than "all", because that set leaves outGlobandGrepon macOS, Linux and WSL. [line 131] [Source]
commands [Source]
/design-syncand/importare now also unavailable through a Claude apps gateway, and/design-sync's restriction is explained as needing claude.ai rather than as a tool limitation. [lines 74-91] [Source]
corporate-launcher [Source]
- Corrected: with a launcher configured the helper processes simply lose their
claude bg-pty-hostlabels rather than showing the versioned binary name. [line 40] [Source]
costs [Source]
- New admin-facing bullet for the spend-limit family of messages, pointing at Admin settings > Usage and noting that a named plan reset time is an alternative to raising the limit. [line 188] [Source]
desktop [Source]
- Worktrees are now opt-in per session: select the worktree option next to the branch name, rather than every Git-repository session automatically getting one. [line 305] [Source]
- Git is no longer required to open the Code tab on Windows — only sessions that run in their own worktree need it. Desktop versions before 1.49585.0 asked for Git before any local session. [lines 21-928] [Source]
desktop-changelog [Source]
- Carries the same worktree opt-in and Windows Git changes. [lines 21-928] [Source]
desktop-quickstart [Source]
- Dropped the Windows Git prerequisite from the getting-started steps, and softened parallel sessions to "optionally each in its own Git worktree". [lines 53-117] [Source]
env-vars [Source]
- Added
OTEL_METRICS_INCLUDE_REPOSITORY, requiring v2.1.269. [line 458] [Source] CCR_FORCE_BUNDLEreworded from "even when GitHub access is available" to "instead of cloning from its remote", matching the broader fallback. [line 179] [Source]
errors [Source]
- New "You've hit your monthly spend limit" section covering five message variants — individual, org monthly, team's shared budget, channel's monthly, and the usage-based-billing spelling
individual usage limit. Each variant's text after the·names the route to a higher limit, and a named plan-window reset time means access returns without anyone raising anything. Before v2.1.268 a pooled group budget produced theindividual spend limitmessage instead. [line 211] [Source] - New "plugin eval is currently in early access" section: the first message means a build older than v2.1.269, the second means Anthropic switched the command off server-side and nothing local re-enables it. [line 211] [Source]
- The
claude importunavailability list now includes Claude apps gateway sessions. [line 211] [Source] - The marketplace entry-path refusal text gained "backslash-containing" and "or opens outside its tree" to its list of rejected shapes. [line 211] [Source]
headless [Source]
dontAskrewritten for CI: actions needing no approval in Manual mode still run, including the read-only command set. [line 261] [Source]
hooks-guide [Source]
- New troubleshooting for a hook whose JSON parses but does nothing. Two causes: extra stdout before the JSON (usually an
echoin your shell profile), or a field at the wrong level —permissionDecisionbelongs insidehookSpecificOutput. Misplaced fields are silently ignored; find them withclaude --debugand search the log forHook JSON output had unrecognized keys. [lines 996-1019] [Source]
iam [Source]
ide-integrations [Source]
- New "Share a plugin install link" section documenting a
vscode://anthropic.claude-code/install-pluginURL that opens VS Code on a plugin's scope choice. Nothing installs until a scope is picked,marketplacedefaults toanthropics/claude-plugins-official, and the section warns that GitHub strips non-httpschemes so the URL needs a code block there. [lines 233-253] [Source]
managed-settings [Source]
- The gateway login keys follow a separate rule: never read from server-managed settings, so the highest-ranked admin source carrying a policy key supplies them regardless. [line 169] [Source]
model-config [Source]
- Documents pressing
sin the model picker for a session-only switch (rebindable asmodelPicker:thisSessionOnly), and clarifies that/model <name>typed directly behaves likeEnter. [lines 117-121] [Source]
monitoring-usage [Source]
- New "Repository attributes" section:
OTEL_METRICS_INCLUDE_REPOSITORY=truederivesvcs.repository.url.full,vcs.owner.name,vcs.repository.nameandvcs.provider.nameonce per session from theoriginremote, with HTTPS and SSH remotes producing identical values. Credentials, query strings and fragments never appear; the attributes are omitted with noorigin, a non-URL remote, or when the only enclosing repository is your home directory. These flow only to your own exporters — Anthropic's telemetry drops everyvcs.*key. [lines 481-498] [Source] - A batch of new bounded "safe" attributes that carry no user-chosen names, all requiring v2.1.268:
query_source_safe(user-named agents collapse toagent.custom),tool_name_safe(MCP tools becomemcp_otherapart from a few fixed shapes),bash_command_class,bash_argv0,error_classandfirst_content_ms. [lines 213-249] [Source] vcs.ref.head.*attributes on commit events underOTEL_LOG_TOOL_DETAILS=1, giving the SHA, branch andbranchtype of a successfulgit commit, omitted on a detached HEAD. [lines 691-694] [Source]- New
parent.sourcespan attribute distinguishingenv(parented under an inboundTRACEPARENT) fromnone. [line 203] [Source] - Custom
OTEL_RESOURCE_ATTRIBUTESkeys still never override standard attributes — withvcs.*now the documented exception. [line 358] [Source]
permission-modes [Source]
dontAskrestated as "reads and pre-approved tools; anything that would prompt is denied", and its section now names PreToolUse hook approvals as another thing that still runs. [lines 19-489] [Source]
permissions [Source]
- Symlink deny rules now apply when either the symlink path or its target matches, with a worked example:
./project/keypointing at~/.ssh/id_rsais blocked. A rule written through a symlinked directory also applies at the real location — before v2.1.268 it didn't. [lines 404-406] [Source] - Artifact reads carved out of bare
WebFetchrules: you now need adomain:rule coveringclaude.aior*.claudeusercontent.com, or anArtifactrule. Before v2.1.268 a bare deny rule blocked every artifact read. [lines 435-437] [Source]
plugins [Source]
- New pointer from plugin development to
claude plugin evalfor measuring how often Claude actually reaches for the plugin. [lines 299-454] [Source]
plugins-reference [Source]
- New
plugin evalandplugin eval initcommand reference sections with their full option tables and exit codes: 0 when every case meets the threshold, 1 on a failing case or untrusted directory, 2 on a partial run, 130 interrupted, 143 terminated. [lines 1246-1293] [Source] - New
experimental.evalsmanifest field for a non-default eval directory. [line 540] [Source] - Every CLI command section gained explicit "The command takes these arguments" / "accepts these options" lead-ins, and the
new,remove/rmandautoremovealiases are now documented. [lines 932-1067] [Source]
sandbox-environments [Source]
- Sharpened the boundary: the sandboxed Bash tool restricts Bash only — file tools, MCP servers and hooks still run directly on your host, while every other approach in the table puts the whole process inside the boundary. [lines 24-68] [Source]
server-managed-settings [Source]
- A third class of no-merge exception: gateway sign-in keys, never read from server-managed settings. [line 144] [Source]
ANTHROPIC_CUSTOM_HEADERSapproval now depends on the delivered value: tagging headers such asAccept-Languageapply silently, while anything naming a credential, org selector, routing override or API-behavior header requires approval. The check matches words inside the name, soX-Client-Versionneeds approval. Before v2.1.251 any value applied without the dialog. [line 282] [Source]
settings-reference [Source]
- New
managedSourcesBehaviordocumentation defining a "policy key" as any settings key other than itself andwslInheritsWindowsSettings, and explaining that"merge"combines every admin source. Requires v2.1.242. [line 5571] [Source] - New table row listing the keys read only from the highest-priority source, and a following list of keys with extra conditions. [lines 5598-5608] [Source]
/effort ultracodedocumented as a per-session override needing no settings key. [line 1247] [Source]
setup [Source]
- How to confirm
DISABLE_AUTOUPDATERtook effect:claude doctorshould showdisabled (set by env: DISABLE_AUTOUPDATER). [line 259] [Source]
skills [Source]
- Distinguishes the two eval tools:
claude plugin evalfor a skill that ships in a plugin, and the skill-creator plugin's ownevals/evals.jsonfor iterating inside a conversation. The two formats aren't interchangeable. [lines 790-1029] [Source]
slash-commands [Source]
- Carries the same eval-tooling guidance as the skills page.
terminal-config [Source]
- Terminals speaking the kitty keyboard protocol, such as foot and Alacritty 0.16+, now work without
/terminal-setupon v2.1.269. Alacritty before 0.16 and Zed still need it, and the page warns to run it in the host terminal rather than inside tmux or screen. [lines 26-30] [Source]
tools-reference [Source]
- Glob and Grep are absent by default on macOS, Linux and WSL. Claude searches with
findandgrepthrough the Bash tool, which run embeddedbfsandugrep, so searches now arrive at your hooks and permission rules asBashcalls rather thanGlob/Grepcalls. On Windows both remain in the default set. [lines 28-256] [Source] - Three ways to get them back: name them in
--toolsor--allowedToolsat startup (naming either in--allowedToolsrestores both, and an allow rule in a settings file does not have this effect); removeBashfrom the session with a deny rule,--disallowedToolsor--restricted; or have a subagent list them intoolswhile leaving outBash. [lines 258-262] [Source]
troubleshoot-install [Source]
- Added a next step when
downloads.claude.aiis reachable but the install failed: the failure was likely intermittent, so retry or try another install method. [line 378] [Source]
vs-code [Source]
- Carries the same
install-plugindeep-link section as the IDE integrations page.
web-quickstart [Source]
- Onboarding now states plainly that a browser GitHub connection clones any public repository but reaches a private one only where the Claude GitHub App is installed — and that an organization owner may need to approve the installation. [line 61] [Source]
- New "Remove the
/web-setuptoken" section: disconnecting GitHub at claude.ai/customize/connectors deletes the stored credentials but leaves your localghsigned in and the token valid on GitHub. To invalidate it, revoke the GitHub CLI OAuth app entry — which also signsghout on your machines. [lines 108-114] [Source] - Spells out what
/web-setupdoes with your token: Claude Code readsgh auth token, asks you to confirm, and sends it to Anthropic, which stores it encrypted against your claude.ai account. On Team and Enterprise it's available only after an Owner turns on Quick web setup. [lines 78-82] [Source] /web-setupnow creates a cloud environment with Trusted network access if you have none. [line 106] [Source]- New troubleshooting for "No repositories appear after connecting GitHub", split by connection method. [lines 185-187] [Source]
API changes
Changed documents
agents-and-tools/tool-use/browser-use-tool [Source]
- New "Report downloads" behavior: the API renders each download entry into a line of text for Claude, after the result's text and before the Tab Context footer, carrying
download_id,url, andpath/size_bytesorerror. A result with no text block gets them as a text block of its own. [lines 1405-1437] [Source] - Expanded prompt-injection guidance: tab URLs render verbatim, so sanitize them yourself, while titles are escaped by the API — meaning a pre-escaped title reaches Claude double-escaped. A download's
url,pathanderrorare untrusted too, and the API's length limits are "a floor, not a defense". [lines 1108-1291] [Source] - Clarified that an image-only result renders nothing and defers tab context to the next result carrying text — unless it reports a download event. [line 1359] [Source]
api/errors [Source]
- The thinking-block signature error now names the
thinking-binding-controls-2026-08-01beta header when it's absent, and points atprefix_mismatch_behavior: "drop_block"as the way to continue. A block from a model the target can't read is dropped rather than rejected. [line 504] [Source]
build-with-claude/context-editing [Source]
- On Fable 5.1, server-side context management never invalidates thinking blocks, but client-side edits to earlier turns invalidate every later assistant turn's. For accounts created on or after August 31, 2026, replaying an invalidated block is rejected unless you opt into dropping it. [line 59] [Source]
build-with-claude/thinking [Source]
- New guidance on switching models mid-conversation: keep passing thinking blocks back unchanged. A block is readable only by its producing model or a newer one, so switching up to Fable 5.1 or Mythos 5.1 keeps the conversation's reasoning while switching down drops it. Never strip blocks when redeeming a fallback credit, which requires the body unchanged. [line 989] [Source]
cli-sdks-libraries/cli/apply [Source]
- Documents that resources refer to each other by relative file path wherever the API expects an ID, and that
ant applycreates them in dependency order and fills in the real IDs. [line 105] [Source]
manage-claude/cmek [Source]
- A much fuller list of what CMEK turns off: chat search (titles and content are encrypted under your key, so the Search and reference chats toggle stays off), Claude Code on the web and routines, Claude in Slack, organization data and audit log exports, and response ratings. Claude Code Desktop stays available for local sessions but is off until an admin enables it. [lines 88-93] [Source]
- Claude Science data sent to users' own compute, such as SSH hosts or cloud accounts, is held on those systems and isn't covered. [line 72] [Source]
manage-claude/inference-hooks [Source]
- Added a flow diagram and a walkthrough of which points are hooked — step 1 where the prompt arrives and step 6 where the tool result returns, each triggering a validation exchange with your AI security server. [lines 26-28] [Source]
models/fable-5-1/migration-guide [Source]
- When a Fable 5.1 conversation lands on an older model through a router switch, retry or classifier fallback, the API removes unreadable blocks, the request succeeds, and you aren't billed for the dropped tokens — but the target re-plans without that reasoning, raising first-turn cost and latency. The
thinking-binding-controls-2026-08-01header surfaces each drop in aninput_transformationsarray. [line 929] [Source]
models/fable-5-1/whats-new-fable-5-1 [Source]
- Without the beta header the drop is silent, which is the operative warning here. [line 47] [Source]
- Practical recipe for keeping thinking valid across a long session: treat the conversation as append-only, add instructions via mid-conversation system messages, change tools via mid-conversation tool changes, and trim with server-side context editing or compaction, which don't count as edits. To find out whether your integration edits history, run with
prefix_mismatch_behavior: "drop_block"and loginput_transformations. [line 64] [Source]
models/fable-5/migration-guide [Source]
- The "strip thinking blocks before replaying on an earlier model" advice now carries an exception in both places: keep them when moving a conversation up to Fable 5.1 or Mythos 5.1, and never strip when redeeming a fallback credit. [lines 319-687] [Source]
api/compliance [Source]
- An upstream generation fix removed thousands of lines of repeated boilerplate ("Automated background processing performed by Anthropic systems…" and its asserting-party note) from the compliance reference and its
activitiespages. No described behavior changed. The same de-duplication trimmed repeated tool and content-block descriptions from thebeta/messagesandmessagesreference pages across every SDK language.