Claude docs changes for September 16th, 2026 [diff]

Executive Summary

  • On-demand compaction arrives behind the compact-2026-09-04 beta: send a top-level compaction parameter 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 gatewayInternalNetworks managed 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
  • PostToolUse hooks can now receive the files a Bash command changed in tool_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/type in TypeScript, class in Python, Java and C#, type in 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-compaction and x-claude-code-context-compacted request headers for LLM gateways, behind CLAUDE_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-pr surfacing gh's own error, /web-setup token refusals, SSL and proxy errors naming NODE_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=1 selects the server-side one
  • Changed OTEL_LOG_TOOL_DETAILS=1 to 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 dangerous rm in bypass mode
  • Fixed allowManagedMcpServersOnly, deniedMcpServers and disableClaudeAiConnectors set via MDM or managed-settings.json being ignored when server-managed settings are also present
  • Fixed skills synced from claude.ai staying available after an organization turns Skills off
  • Fixed permissions.blockReadsOutsideWorkingDirectories so 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, /upgrade and /extra-usage discarding 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.json was copied into another folder, such as a new worktree
  • Fixed SDK and stream-json output 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 build be 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 gatewayInternalNetworks managed setting, which lets /login accept 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 /8 to /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/24 and multicast. 240.0.0.0/4 is 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 /login names the NO_PROXY entry 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: PostToolUse receives changed files in tool_response.bashEditDiff, with a field table covering changedFiles (up to 200 paths), files (diffs of up to 5), moreFiles, unavailable, skipped (for a Git command that moves the working tree) and shared (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]
  • SubagentHandback changes how a subagent's report reaches you on v2.1.271+: the completed result's content carries only a short note about the hand-back, and the report itself is that call's tool_input.message, so match a hook on SubagentHandback to read it. The same applies to last_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 /resume inside a session waits instead, and anything the hooks return is discarded if you /clear or switch while they're still running. [lines 1106-1108] [Source]
  • SessionEnd's 1.5-second budget explained: a per-hook timeout raises the overall budget to the highest one set, capped at 60 seconds, but a hook without its own timeout keeps the default — while CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS raises 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_sessions policy, which can't be overridden from local settings, environment variables or CLI flags. Before v2.1.268 the affected commands answered Unknown command instead. 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.1 for 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]
  • --restricted sessions 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 /logout then /login. [line 1871] [Source]
  • The origin/HEAD failure 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 no origin or 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_MODEL or the model setting 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 — --cloud creates a new session, and with -p plus 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: --env accepts multiple KEY=value pairs, so if the server name comes straight after --env the CLI reads it as another pair and rejects it — put another option such as --transport stdio between 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 add command. [line 148] [Source]

API changes

Changed documents

build-with-claude/compaction [Source]

  • New "Compact on demand with the compaction parameter" section, roughly 140 lines documenting the compact-2026-09-04 beta. 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 with stop_reason: "compaction". From then on that block goes first in messages, 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 and max_tokens, is billed and rate-limited like any request, and reports as the compaction entry in usage.iterations — while the top-level input_tokens and output_tokens are zero because no reply was generated. max_tokens caps 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-output output_config.format, and a tool_choice of any or tool are 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 the messages of a request you already made, and to change system or tools without 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 the stop_reason telling you whether to raise max_tokens, shorten instructions, or tell the model not to call tools. A transient failure is a retryable 529 with error_code: compaction_unavailable, and a missing beta header fails with a generic compaction: Extra inputs are not permitted that 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_management on one request. [line 3390] [Source]
  • Streaming detail: the block arrives whole as one content_block_start carrying the complete block, then content_block_stop, with no deltas. [line 3458] [Source]

api/beta [Source]

  • compact-2026-09-04 added to the beta-header enum, which now reads "43 more". [lines 14-110] [Source]
  • New capabilities.compaction on the Models API, reporting whether a model accepts the top-level compaction parameter with one entry per supported compaction.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/batches and the rest, across TypeScript, Python, Java, C#, Go, Ruby and PHP — was regenerated so each type declaration carries its language's keyword: interface and type in TypeScript, class in Python, Java and C#, type in 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.