Claude docs changes for Sept, 28th 2026 [diff]
Executive Summary
- Claude Sonnet 5.5 (
claude-sonnet-5-5) launches: 1M context, $2/$10 per MTok, with a new overview, what's-new page, migration guide and prompting guide, and Claude Code 2.1.284 adopts it as the default Sonnet model - Sonnet 5.5 brings breaking API changes:
thinking: disabledis replaced bybetween_tools, forced tool use is rejected, thinking blocks are bound to the account and conversation prefix, and computer use requirescomputer_toolset_20260801 - Claude Code now starts in auto mode by default when no permission mode is configured, and Ultracode becomes its own toggle in
/effort - Agent SDK docs explain the system reminders Claude Code adds outside the system prompt and how to turn them off
- Claude apps gateway gains dollar-based spend limits, Google Cloud OTLP telemetry export and certificate client authentication
New Claude Code versions
2.1.284
New features
- Added Claude Sonnet 5.5 (
claude-sonnet-5-5) as the default Sonnet model on the Anthropic API (1M context, $2/$10 per Mtok) - Added a "Yes, but ask again next time" answer to auto mode's prompt for reads outside the working directories
- Added dollar amounts for the Claude apps gateway spend limit in
/usageand the status line (rate_limits.spend_limitgainsused_usd,limit_usd,period) - Added
effortSlider:decreaseEffort,increaseEffortandtoggleUltracodekeybinding actions - Added
/rate-limit-optionsto/helpfor claude.ai subscribers, and/mcp reconnect allto retry every failed or unauthenticated MCP server - Added Claude apps gateway startup warnings for empty or inconsistent
availableModels,auth: { google: {} }fortelemetry.forward_todestinations, andprivate_key_jwtcertificate client authentication with the identity provider - [VSCode] Added optional message timestamps, plugin load errors in Manage plugins, and an Ultracode on/off switch under the Effort slider
- [Claude Tag] Added model family choices such as "Opus (latest)" and org-wide limit spend in the analytics projection chart
Existing feature improvements
- Interactive terminal and VS Code sessions now start in auto mode when no permission mode is configured (
permissions.defaultModestill overrides it) - Ultracode is its own toggle in
/effort(Tab, or/effort ultracode [on|off]), no longer forces xhigh effort, and works at any effort level - Retries after a dropped mid-response connection share one budget with other retries, so failing requests give up sooner
- Safety-flag notices for Sonnet models explain the cause and offer edit and retry; on pinned Opus models the API picks the fallback model
- Auto-memory loading neutralizes invisible characters and look-alike markup tags in
MEMORY.mdand recalled notes - Improved startup time and memory use by building only the used parts of the settings schema
claude plugin marketplace addsays when it replaces a marketplace of the same name;/recapdeclines when relayed from chat threads, routines or webhooks- Improved
/claude-apihillclimb, aligned columns in/tasks,/copyand/hooks, and better Monitor event rows
Major bug fixes
- Fixed damaged response streams showing raw errors ("JSON Parse error", "undefined") instead of being retried, and overloaded errors after a thinking block ending the turn instead of being retried
- Fixed "Prompt is too long" errors persisting after compaction; Claude Code now compacts again keeping less recent conversation
- Fixed
allowed-toolsin marketplace, claude.ai and npm plugins pre-approving tools under managedallowManagedPermissionRulesOnly - Fixed rules symlinked into
.claude/rulesfrom outside the project skipping the external-imports approval prompt - Fixed
{"decision":"block"}from Elicitation and ElicitationResult hooks being ignored - Fixed MCP tool calls in resumed sessions failing with "No such tool available" while the server was still connecting
- Fixed
claude mcp addreporting success when managed settings restrict MCP servers to plugins - Fixed Agent SDK sessions crashing on images with malformed
source - Fixed Bash tool failing on Windows with many plugins, and sandboxed Bash failing to start on Linux with write-denied working directories
- Fixed the Claude apps gateway returning 431 for sign-ins with many identity provider groups
- Fixed repeated plan-usage endpoint calls after rate-limiting or login rejection
Claude Code changes
Changed documents
advisor [Source]
- Advisor pairing table updated for Sonnet 5.5 (accepts Fable, Opus 4.7+, Sonnet 5+) and for the new Opus 5.5 and Fable 5.1 constraints. [lines 84-93] [Source]
agent-sdk/modifying-system-prompts [Source]
- New section "Context Claude Code adds outside the system prompt": lists the system reminders (CLAUDE.md, output style, attribution, hook output, skills, subagents, task nudges, file-changed notes). [lines 367-468] [Source]
- Table and TypeScript/Python example for turning off built-in context (
includeGitInstructions,attribution,CLAUDE_CODE_DISABLE_CLAUDE_MDS,CLAUDE_CODE_DISABLE_ATTACHMENTS), and how to log raw requests to see what Claude received.
agent-sdk/typescript [Source]
- Substantial updates to the TypeScript SDK reference (about 150 lines changed).
claude-md [Source]
/doctor prompt-audit [path]audits CLAUDE.md, rules, skills, commands and subagents for outdated or conflicting instructions. [line 88] [Source]- Troubleshooting tip: instructions may compete with built-in commit/PR guidance; disable it with
includeGitInstructions. [line 547] [Source]
commands [Source]
- Command table updated:
/rate-limit-options,/mcp reconnect all,/doctor [prompt-audit [path]],/claude-apiprompt-audit and other modes. [lines 44-160] [Source]
env-vars [Source]
- Added
VERTEX_REGION_CLAUDE_5_5_SONNET; updated descriptions ofCLAUDE_CODE_DISABLE_THINKING,CLAUDE_CODE_DISABLE_ADAPTIVE_THINKINGandMAX_THINKING_TOKENS. [line 492] [Source]
errors [Source]
- New sections for marketplace names that impersonate official Anthropic marketplaces, plugin uninstall refusals, and unresolvable path refusals. [lines 3441-3462] [Source]
- Startup refusal when
forceLoginMethod/forceLoginOrgUUIDconflicts with a configured credential, and how to remove it. [line 1275] [Source] - Minimum Claude Code version for Sonnet 5.5 thinking support, and safeguard-flag notices for Opus 5.5/Sonnet 5.5. [line 2359] [Source]
glossary [Source]
- About 23 lines of new glossary entries.
model-config [Source]
- Sonnet 5.5 added as the default Sonnet alias, with updated effort, thinking and extended-context guidance.
permission-modes [Source]
- Documentation of auto mode as the default start mode and the new "ask again next time" read answer.
claude-apps-gateway-config [Source]
- Gateway docs (config, deploy, AWS, GCP, spend limits) updated for Google OTLP telemetry auth,
private_key_jwtidentity provider auth, dollar spend limits and startup warnings.
plugins/loading [Source]
- Plugin docs (loading, CLI reference, manifest, marketplace reference, troubleshooting) updated for reserved marketplace names,
allowed-toolspre-approval rules and install/uninstall behavior.
API changes
New Documents
build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5 [Source]
Prompting guide for Claude Sonnet 5.5, covering how to steer the model and what to change when migrating prompts from Sonnet 5.
models/sonnet-5-5/migration-guide [Source]
Long migration guide from earlier models to Sonnet 5.5, with code samples for the breaking changes (thinking, forced tool use, computer use, advisor).
models/sonnet-5-5/overview [Source]
Overview of Claude Sonnet 5.5, "the best combination of speed and intelligence": model ID, capabilities, pricing and platform availability.
models/sonnet-5-5/whats-new-sonnet-5-5 [Source]
Five breaking changes versus Sonnet 5: between_tools replaces disabled thinking, forced tool use errors, thinking blocks bound to model and conversation, computer_20251124 not accepted, and advisor pairing restrictions. Also notes that text between tool calls now comes back in thinking blocks, and covers behavior differences, pricing and availability.
Changed documents
about-claude/pricing [Source]
- Sonnet 5.5 added: $2 input, $2.50/$4 cache writes, $0.20 cache reads, $10 output per MTok. [line 31] [Source]
- Batch pricing ($1/$5) and 286-token tool-use system prompt overhead. [line 200] [Source]
api/errors [Source]
- New 400 errors for Sonnet 5.5:
thinking.type.disabled,between_toolsatxhigh/maxeffort, mid-conversation effort changes withbetween_tools, andbetween_toolson other models. [lines 484-511] [Source] - Forced tool use rejected on Opus 5.5, Sonnet 5.5, Fable 5.1 and Mythos 5.1; computer use only as
computer_toolset_20260801on Opus 5.5 and Sonnet 5.5. [lines 516-532] [Source] - Thinking-block prefix check now covers Sonnet 5.5. [line 536] [Source]
build-with-claude/compaction [Source]
- Comparison table reworked around on-demand compaction, with links to keep-recent-turns, background compaction and thinking-blocks pages. [lines 17-26] [Source]
build-with-claude/effort [Source]
- Sonnet 5.5 supports all five effort levels (default
high, recalibrated); new "Recommended effort levels for Claude Sonnet 5.5" section. [lines 306-313] [Source] - Per-message effort changes now supported on Sonnet 5.5 (beta header
mid-conversation-output-config-2026-07-01). [line 361] [Source]
build-with-claude/preserved-thinking [Source]
- New section: Sonnet 5.5 thinking blocks stay with the account that produced them; other accounts' blocks are dropped (
organization_binding_mismatch). [lines 68-73] [Source] - Sonnet 5.5 reads thinking blocks from Sonnet 5, Opus 4.8, Haiku 4.5 and earlier, but not Opus 5/5.5, Fable or Mythos. [line 43] [Source]
- Prefix check enforced for new accounts on Sonnet 5.5;
block_bindingworks only with adaptive thinking on Sonnet 5.5. [line 130] [Source]
build-with-claude/thinking [Source]
- New per-model table showing what each
thinkingvalue does (adaptive, enabled,between_tools, disabled), including the newbetween_toolsmode. [lines 47-70] [Source] - Rewritten introduction explaining up-front thinking, with a diagram. [lines 13-23] [Source]
build-with-claude/thinking-troubleshooting [Source]
- New troubleshooting entries for the
between_toolsand effort errors.
agents-and-tools/tool-use/advisor-tool [Source]
- Compatibility and result-format guidance updated for Sonnet 5.5 and the newer Opus/Fable advisors.
agents-and-tools/tool-use/computer-use-tool [Source]
- Sonnet 5.5 requires
computer_toolset_20260801; migration fromcomputer_20251124.
build-with-claude/prompt-engineering/claude-prompting-best-practices [Source]
- Updated to cover Sonnet 5.5 and link to its prompting guide.
models/overview [Source]
- Sonnet 5.5 added as the newest Sonnet; model pages for other models (Opus, Fable, Mythos, Sonnet, Haiku) and
choosing-a-modelupdated accordingly.
release-notes/overview [Source]
- Release notes entry for Claude Sonnet 5.5 and related API changes.
build-with-claude/refusals-and-fallback [Source]
- Refusal and fallback guidance updated for Sonnet 5.5.