Claude docs changes for September 16th, 2026 [diff]
Executive Summary
- On-demand compaction arrives behind the
compact-2026-09-04beta: send a top-levelcompactionparameter and get back a single signed block with no reply, so the summary can be generated in the background while the conversation keeps running, and recent turns can be kept word-for-word after it - New
gatewayInternalNetworksmanaged setting lets organizations whose internal network is numbered from public IPv4 space they own sign in to a Claude apps gateway there — with a carefully-bounded validation regime: at most four non-overlapping blocks, none touching private, documentation, or reserved space - New Agent SDK "Configure your agent" page pulling options, settings files, environment variables, model selection, limits and mid-session changes into one place
PostToolUsehooks can now receive the files a Bash command changed intool_response.bashEditDiff, with explicit honesty about its limits: "best effort and in public beta… use the list to find what to review, not to enforce a policy"- The per-language SDK reference pages were regenerated so every type declaration carries its language keyword (
interface/typein TypeScript,classin Python, Java and C#,typein Go) — a cosmetic change that accounts for the great majority of this commit's 155,000 changed lines
New Claude Code versions
2.1.273
New features
- Added
x-claude-code-request-class,x-claude-code-agent-type,x-claude-code-prev-tool-durations,x-claude-code-compactionandx-claude-code-context-compactedrequest headers for LLM gateways, behindCLAUDE_CODE_GATEWAY_HINT_HEADERS=1 - Added a notification when an MCP server disconnects mid-session and automatic reconnection gives up
- Added forking a Remote Control session from the Claude app; the fork runs as a background session on your computer
Existing feature improvements
- Improved the Artifact tool's error when a publish includes an unserved file type, and its page read to state the capabilities and database rules the artifact service holds for the page
- Improved artifact database writes so an update can remove a single field instead of rewriting the whole document
- Improved artifact publishing so a publish whose connection drops after reaching claude.ai is re-sent safely rather than failing or duplicating a version
- Improved a family of error messages to name the actual cause: cloud-session GitHub failures (IP allow list, suspended installation, SAML),
/autofix-prsurfacinggh's own error,/web-setuptoken refusals, SSL and proxy errors namingNODE_EXTRA_CA_CERTS, and expired MCP sign-ins pointing at/mcp - Improved responsiveness in long sessions: hook progress and subagent activity no longer re-process the whole conversation on every update
- Changed auto mode on Bedrock, Vertex and Foundry to use the local classifier by default for now;
CLAUDE_CODE_AUTO_MODE_SERVER=1selects the server-side one - Changed
OTEL_LOG_TOOL_DETAILS=1to also include real agent, skill, plugin and MCP server names on cost and token metrics
Major bug fixes
- Fixed Bash commands the permission checker can't fully analyze skipping the prompt under
permissions.blockReadsOutsideWorkingDirectories, and a subshell hiding a dangerousrmin bypass mode - Fixed
allowManagedMcpServersOnly,deniedMcpServersanddisableClaudeAiConnectorsset via MDM ormanaged-settings.jsonbeing ignored when server-managed settings are also present - Fixed skills synced from claude.ai staying available after an organization turns Skills off
- Fixed
permissions.blockReadsOutsideWorkingDirectoriesso a memory directory chosen by a repository's settings is no longer loaded into the prompt, recalled, indexed, or used by memory extraction - Fixed the context meter and auto-compact counting advisor-tool turns at roughly twice their real size, which made auto-compact fire at about half the real window
- Fixed
/login,/upgradeand/extra-usagediscarding earlier thinking, forcing a full prompt-cache rewrite on the next request - Fixed subagents and background agents being reported as failed, with their result never delivered, when the final streamed reply omitted token usage or carried no model id
- Fixed Read on macOS refusing a dragged-in screenshot with "symlink resolution changed after permission was checked"
- Fixed saved scheduled tasks running in the wrong session after
.claude/scheduled_tasks.jsonwas copied into another folder, such as a new worktree - Fixed SDK and
stream-jsonoutput dropping a subagent's remaining messages and final report after it moves to the background mid-run - Reverted a 2.1.268 change checking Read and Edit deny rules on Bash lines the checker can't analyze, which made
time -p make buildbe denied rather than prompt
Claude Code changes
New Documents
agent-sdk/configuration [Source]
A single page for composing an Agent SDK session's configuration, covering how settings files, environment variables and the options object combine. Sections: passing options to a session (with a worked read-only example written as TypeScript / Python pairs where spellings differ), loading settings files, choosing a model, setting environment variables and the working directory, limiting turns and spend, changing configuration mid-session, and an index of each feature option's own page.
Changed documents
claude-apps-gateway [Source]
- New "Allow a gateway on public address space you own" section for the
gatewayInternalNetworksmanaged setting, which lets/loginaccept a gateway on public IPv4 space your organization owns. The stated reason for the private-address rule it relaxes is worth quoting: "a trusted gateway can push settings that run commands on developer machines." [lines 268-272] [Source] - The validation is deliberately narrow: at most four non-overlapping IPv4 blocks from
/8to/32, none overlapping private space (already accepted without the key), none overlapping space that is never an organization's network —198.18.0.0/15,192.0.0.0/24, the three documentation ranges,0.0.0.0/8,192.88.99.0/24and multicast.240.0.0.0/4is allowed, since some large networks use it as internal unicast space. [lines 288-291] [Source] - With a valid list, three further checks run at
/login: every address the hostname resolves to must be inside that one block (a name with any record outside it is refused), the machine must connect from inside the same block (refusing NAT, containers, WSL2 and off-block VPN pools, naming the address it saw), and the connection must be direct or/loginnames theNO_PROXYentry to add. [lines 297-301] [Source] - A blunt closing caveat: a declared block narrows who can sign in but doesn't prove where a machine is, so a block shared with other tenants, such as a cloud provider's public range, lets anyone in it pass the same check. And an invalid entry fails closed — every new gateway sign-in on that machine is refused, private-address gateways included, while existing sign-ins keep working. [lines 295-307] [Source]
hooks [Source]
- New Bash edit-diff documentation:
PostToolUsereceives changed files intool_response.bashEditDiff, with a field table coveringchangedFiles(up to 200 paths),files(diffs of up to 5),moreFiles,unavailable,skipped(for a Git command that moves the working tree) andshared(another Bash call ran in the same repository concurrently, so some listed changes may be its). Requires v2.1.269. [lines 1597-1612] [Source] - The accompanying caveat is unusually direct: the list is "best effort and in public beta", can miss a change, include another process's file, or stop at its size limits, and the field shape may change — "use the list to find what to review, not to enforce a policy." [line 1601] [Source]
SubagentHandbackchanges how a subagent's report reaches you on v2.1.271+: thecompletedresult'scontentcarries only a short note about the hand-back, and the report itself is that call'stool_input.message, so match a hook onSubagentHandbackto read it. The same applies tolast_assistant_message, which now holds closing text rather than the report. [lines 1731-2341] [Source]- SessionStart hooks now run in the background at launch and on
/clear, so you can type right away and a resumed conversation appears without waiting — but Claude's first response still waits. Switching with/resumeinside a session waits instead, and anything the hooks return is discarded if you/clearor switch while they're still running. [lines 1106-1108] [Source] - SessionEnd's 1.5-second budget explained: a per-hook
timeoutraises the overall budget to the highest one set, capped at 60 seconds, but a hook without its owntimeoutkeeps the default — whileCLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MSraises both. Before v2.1.268 the variable raised only the budget. Plugin-provided hooks' timeouts don't raise it. [lines 3286-3297] [Source] - New note on where cloud-session hooks come from: not your local
~/.claude/settings.json, but the repo and your organization's server-managed settings, plus (in a self-hosted environment) the runner host's seeded hooks and the runner image's managed settings when that file is among the applied managed sources. [line 245] [Source]
errors [Source]
- New "Cloud sessions are disabled by your organization's policy" section for the server-side
allow_remote_sessionspolicy, which can't be overridden from local settings, environment variables or CLI flags. Before v2.1.268 the affected commands answeredUnknown commandinstead. A separate message covers the case where the policy simply couldn't be fetched. [lines 2171-2190] [Source] - New "No available ports for OAuth redirect" section: Claude Code couldn't bind a local listener on
127.0.0.1for an MCP OAuth callback. Before v2.1.268 there was no fallback to an OS-assigned port, which also hit Windows hosts where Hyper-V reserves the port ranges Claude Code picks from. [lines 2448-2461] [Source] - New "GitHub isn't connected to your Claude account" section, which blocks a cloud-session launch but appears only as a non-blocking setup note when creating a routine with
/schedule. [lines 2664-2674] [Source] --restrictedsessions now refuse to create cloud sessions on the client, before contacting the server, because the new session would run outside the restricted process. [line 2158] [Source]- A useful plan-upgrade note: the stored token reflects your plan at sign-in time, so upgrading on claude.ai doesn't take effect in an existing session until you
/logoutthen/login. [line 1871] [Source] - The
origin/HEADfailure is now explained by the three setups that produce it — a single-branch or CI checkout, a server-side HEAD pointing at an unpushed branch, and a repository with nooriginor one never fetched — and generalized to any skill injecting dynamic context, where a failed injected command aborts the skill's invocation. [lines 2476-2484] [Source] - The page opens by scoping itself across the CLI, Desktop app and cloud sessions, "since all three wrap the same Claude Code CLI". [line 7] [Source]
- The "Usage credits required for 1M context" message now says the change takes effect only after a restart; before v2.1.268 it didn't mention restarting. [lines 569-583] [Source]
- A restricted model set via
--model,ANTHROPIC_MODELor themodelsetting is substituted and the session continues, while/model <name>for one is rejected outright — and the substitution notice can appear mid-session when an admin disables the model a session is running on. [line 1898] [Source]
claude-code-on-the-web [Source]
- Retitled "Use Claude Code in the cloud" and restructured around the five surfaces a cloud session can start from — browser, mobile Code tab, Desktop's Cloud option,
claude --cloud, and routines — with an explicit contrast against Remote Control for steering a local session. [lines 1-19] [Source] - States the CLI asymmetry plainly: handoff is one-way. You can pull cloud sessions into your terminal with
--teleport, but you can't push an existing terminal session to the cloud —--cloudcreates a new session, and with-pplus a session ID it queues a message into an existing one instead. Only the Desktop app's Continue in menu sends a local session to the cloud. [line 60] [Source] - Claude Tag channel sessions use organization-level environments only — shared or self-hosted. [line 35] [Source]
mcp [Source]
- A CLI parsing gotcha:
--envaccepts multipleKEY=valuepairs, so if the server name comes straight after--envthe CLI reads it as another pair and rejects it — put another option such as--transport stdiobetween them. [line 131] [Source] - New guidance for adding a server whose setup instructions were written for Claude Desktop, Cursor or another client and give no
claude mcp addcommand. [line 148] [Source]
API changes
Changed documents
build-with-claude/compaction [Source]
- New "Compact on demand with the
compactionparameter" section, roughly 140 lines documenting thecompact-2026-09-04beta. The shape: send your conversation with"compaction": {"type": "summarize"}, the API summarizes every message once, generates no reply, and returns a single signed block alone withstop_reason: "compaction". From then on that block goes first inmessages, replacing what it summarized — and leaving the summarized messages in front of it is a 400. This inverts threshold compaction, whose block follows the messages it summarizes. [lines 3384-3386] [Source] - The three things it buys you: you choose when to compact; the summarization request can run in the background while the conversation continues on its full history (async compaction); and you can keep recent turns word-for-word after the summary (keep-tail compaction) — with their thinking still valid on preserved-thinking models. [line 3388] [Source]
- Billing and limits: the summarization call uses the request's model,
system,tools, thinking settings andmax_tokens, is billed and rate-limited like any request, and reports as thecompactionentry inusage.iterations— while the top-levelinput_tokensandoutput_tokensare zero because no reply was generated.max_tokenscaps the whole call including pre-summary thinking, so allow several thousand tokens. [line 3454] [Source] - Rejections up front: a trailing tool call with no result yet,
stop_sequences, structured-outputoutput_config.format, and atool_choiceofanyortoolare all refused. And the conversation must still fit the context window, so compact before you outgrow it, not after. [line 3456] [Source] - The async swap given as pseudocode: drop exactly the messages you sent in the compaction request from the front of your history, put the returned message in their place, keep everything appended since — and don't edit your history in between, making the swap on the first request after the block arrives, so thinking produced while the summary was being written stays valid. [lines 3498-3509] [Source]
- A subtle constraint on keep-tail: the first kept message mustn't be one the API would merge into the last summarized message — same role, or a
role: "system"message. The simplest way to satisfy it is to compact exactly themessagesof a request you already made, and to changesystemortoolswithout invalidating kept thinking, compact the whole conversation first so nothing is kept. [line 3516] [Source] - Custom
instructions(up to 16,384 characters) replace the API's prompt entirely, and here the summarizer reads the whole conversation including earlier thinking with or without them — unlike threshold compaction on Fable 5.1 and Mythos 5.1, where custom instructions leave earlier thinking out. [lines 3522-3535] [Source] - "When no summary comes back": a summary only appears when the call ends normally with text and no tool call; otherwise you get a 200 with empty
content, still billed, with thestop_reasontelling you whether to raisemax_tokens, shorteninstructions, or tell the model not to call tools. A transient failure is a retryable 529 witherror_code: compaction_unavailable, and a missing beta header fails with a genericcompaction: Extra inputs are not permittedthat doesn't mention the header. [lines 3537-3549] [Source] - Availability: Claude API only, not Amazon Bedrock or Google Cloud, on Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Mythos Preview, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5 and Sonnet 4.6. It can't be combined with
context_managementon one request. [line 3390] [Source] - Streaming detail: the block arrives whole as one
content_block_startcarrying the complete block, thencontent_block_stop, with no deltas. [line 3458] [Source]
api/beta [Source]
compact-2026-09-04added to the beta-header enum, which now reads "43 more". [lines 14-110] [Source]- New
capabilities.compactionon the Models API, reporting whether a model accepts the top-levelcompactionparameter with one entry per supportedcompaction.type— so you can discover support programmatically rather than from the page's model list. [lines 606-618] [Source]
Per-language SDK reference pages
- Every generated SDK reference page —
messages,beta,beta/messages,beta/sessions,beta/messages/batchesand the rest, across TypeScript, Python, Java, C#, Go, Ruby and PHP — was regenerated so each type declaration carries its language's keyword:interfaceandtypein TypeScript,classin Python, Java and C#,typein Go. Around 1,400 declarations per page changed this way. No described behavior changed, but it accounts for the bulk of this commit's size.