Claude docs changes for October 27th, 2026 [diff]
Executive Summary
- Claude Code 2.1.311 adds
ultrathinkas a real xhigh-effort trigger, a long list of stability fixes (startup freezes, MCP and subagent issues, compaction) and new self-hosted runner flags for holding idle sessions. - The Agent SDK gets per-tool approval policies for custom tools (
always_ask/always_deny) and the ability to add plugins to a running session withreloadPlugins({ addPlugins }). The permissions docs were rewritten to match. - Permission docs now cover the "Dangerous rm operation not ruled out" prompt, with time limits and denials for critical-path removals in
autoandbypassPermissionsmodes, plus a newCLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUTvariable. - Managed Agents self-hosted sandboxes now support macOS hosts, with a step-by-step guide for preparing
/mnt/memory. - The Best practices guide was substantially rewritten and reorganized, and the Claude Security plugin gained scan effort levels.
New Claude Code versions
2.1.311
New features
- Added
--hold-idle-fileand--max-hold-mintoself-hosted-runnerto keep an idle session while the host reports processes it left running ultrathinktyped in the interactive terminal now runs its turn at xhigh effort on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 through Anthropic's API, and the rainbow highlight only appears where it can take effect- [VSCode] Syntax coloring for code blocks in Claude's replies, and a "Running UserPromptSubmit hooks" spinner and screen reader announcement
- [Claude Tag] New Skills view in Claude Tag analytics showing how often each attached skill runs in Slack channels
Existing feature improvements
- Faster startup for Pro and Max accounts and for launches whose only arguments are options
- Compaction now usually asks again for the summary when the model's reply lacks one
- Shell commands that hit their timeout now show the output so far and say the command is still running in the background
/teleportwarns when a compacted cloud session loads from its last compaction- Clearer messages when a background session's process exits, on "Connection dropped" API errors and on refused sign-in codes
- Artifact tool better distinguishes artifact pages from documents; multi-view artifacts route on the link's
#name - Model names and IDs drop the
[1m]suffix where it has no effect (the suffix is still accepted) - Claude Code on Bedrock, Mantle, Vertex and Foundry loads model settings from a signed file on downloads.claude.ai (disable with
CLAUDE_CODE_MODEL_CATALOG=off) DISABLE_COMPACTin settings files and in a mod's$.env.setcan now only turn compaction off--output-format json/stream-jsonescape DEL, C1 control and Unicode format characters as\uXXXX- Ctrl+D in agent view now matches the prompt: on empty input, press twice to exit
- [VSCode] Sessions start with
DISABLE_TELEMETRYset while VS Code's telemetry setting is off - [Claude Tag] Routines with nothing to report can end without posting a message
- [Code Review] Transient session start failures are retried once automatically
Major bug fixes
- Fixed long freezes at startup and after file reads/edits when CLAUDE.md contains a very long list item
- Fixed interrupts not taking effect while an MCP server hadn't answered a resource read or a skill was downloading
- Fixed standard-context sessions stopping with "Usage credits required for 1M context"; Claude Code now compacts and continues
- Fixed Write and Edit stalling up to 5 seconds and reporting 0 lines changed on very large edits
- Fixed subagents being unable to use MCP tools from servers that connect after the subagent starts
- Fixed stale MEMORY.md and CLAUDE.md content after automatic compaction
- Fixed
claude -pand SDK sessions saving transcript messages out of order - Fixed
SubagentStophooks firing repeatedly for running subagents instead of once at the end - Fixed a subagent's worktree being removed while its background subagent was still using it
- Fixed Claude Code retrying requests the API marked not to retry, which could hold a turn indefinitely
- Fixed agent teams sessions showing an empty task list after
--resume/--continue - Fixed Cowork cloud sessions losing connectors and tools after a restart when a plugin or setting named an
agent - Fixed pasted text mentioning an image path attaching the image and dropping the path
- Fixed
DISABLE_COMPACTbeing ignored by agent teammates and the rewind menu - Fixed
/mcpauthentication status being wrong for remote servers
Claude Code changes
New Documents
None.
Changed documents
agent-sdk/agent-loop [Source]
- The
dontAskandbypassPermissionsmode descriptions now note calls that still reachcanUseToolor are denied, such as network-path reads. [lines 232-234] [Source]
agent-sdk/custom-tools [Source]
- New "Require approval for specific tools" section: set a tool's
permission_policytoalways_askoralways_deny(TypeScript SDK) on the config returned bycreateSdkMcpServer(). [lines 377-403] [Source] - Set
destructiveHint: trueonalways_asktools so the auto mode classifier doesn't approve them. [line 322] [Source]
agent-sdk/permissions [Source]
- Documents calls that no allow rule approves:
AskUserQuestion, org-askconnector tools,always_askcustom tools, network-path reads and critical-path removals. [lines 97-110] [Source] - Clarified how deny rules,
always_denypolicies,bypassPermissionsandplanmode interact withcanUseTool. [lines 23-50] [Source] - Documented the
CLAUDE_SDK_CAN_USE_TOOL_SHADOWEDwarning. [line 69] [Source] dontAskmode lists the calls denied even when an allow rule matches;touchwith options or prefixes is no longer auto-approved inacceptEdits. [lines 269-287] [Source]
agent-sdk/plugins [Source]
- New "Add plugins to a running session" section using
reloadPlugins({ addPlugins }). [lines 67-82] [Source]
agent-sdk/typescript [Source]
reloadPlugins()gains anaddPluginsoption, with a troubleshooting section for when folders don't load. [lines 1135-1167] [Source]McpSdkServerConfigWithInstancegains atoolslist of the newMcpServerToolPolicytype (permission_policy:always_allow/always_ask/always_deny), changeable mid-session throughsetMcpServers(). Requires SDK v0.3.301+ and Claude Code v2.1.301+. [lines 1463-1562] [Source]
agent-view [Source]
- Peek panel shows how long a session has waited on you, and a safe-mode indicator for
claude --bg --safe-mode. [lines 205-209] [Source] - Explains which in-flight work carries over when you background a session (shell commands, subagents,
/looptasks), which continues only when Claude relaunches it (dynamic workflows) and which stops (monitors). [lines 470-495] [Source]
best-practices [Source]
- Largely rewritten and reorganized. New sections cover deterministic vs. non-deterministic instructions, what Claude can't see, writing specific prompts, a short CLAUDE.md, scoped rules, team skills, review against a spec, Stop-hook checks, enforcing rules with hooks/permissions/sandbox, changing defaults, subagent costs, running without you (scripts, schedules, parallel sessions). [line 1] [Source]
claude-apps-gateway-config [Source]
- Clarified that
serve_to_desktopis a legacy key with no effect when Desktop usesbootstrapUrl, and how to silence the boot warning. [line 926] [Source] - New "Test a policy before deployment" section using a throwaway Postgres database. [line 1007] [Source]
claude-apps-gateway-deploy [Source]
- Troubleshooting entry for
auth.denied/invalid_tokenon/v1/logsand/v1/metricswhenotelHeadersHelperis set in managed settings. [line 392] [Source]
claude-code-on-the-web [Source]
- New "Plugin suggestions in the conversation" section: Claude can suggest plugins with an Add button; deny
SearchPluginsandSuggestPluginInstallto turn it off. [lines 287-308] [Source]
claude-directory [Source]
- Transcripts can also hold the system prompt, tool definitions, request parameters and loaded instruction files; subagent transcripts are listed. [lines 102-117] [Source]
claude-security [Source]
- New "Choose a scan effort" section (
low,mediumdefault,high). [lines 100-111] [Source] - Scans can target only a set of changes (branch, PR or commit diff); a revision stamp file records scan details; new "Update the plugin" section. [lines 5-7] [Source]
desktop [Source]
- Worktree can be enabled with third-party providers and set as default for saved local or SSH environments. [lines 400-403] [Source]
- Switch sessions with Ctrl+Tab / Ctrl+Shift+Tab; diff comments are added via the "+" beside a line number. [lines 165-283] [Source]
env-vars [Source]
- New
CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFFandCLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT. [lines 235-241] [Source]
errors [Source]
- New section for MCP servers on Java MCP SDK 0.17.0 or older rejecting the elicitation capability; fix with
"bareElicitationCapability": trueor upgrading the SDK. [lines 3473-3503] [Source] claude rm <id> --discard-unpusheddocumented for sessions whose worktree has unpushed commits. [line 5114] [Source]
hooks-guide [Source]
ide-integrations [Source]
- New
attachSelection(v2.1.300+) andattachOpenFile(v2.1.271+) settings to keep selected text and the open file out of messages; also apply in the integrated terminal. [lines 225-250] [Source] - Section reorganization; new sections for reading specific PDF pages and including
@terminal:nameoutput. [lines 202-210] [Source]
mcp [Source]
model-config [Source]
ultrathinkcan raise a turn toxhigheffort in the terminal (v2.1.311+), with troubleshooting for when the rainbow doesn't appear. [lines 673-679] [Source]- New sections on checking the effort level you set and when a new level takes effect (queueing a message while Claude works);
/effort autoclears the saved level. [lines 685-709] [Source]
permission-modes [Source]
- New "The
Dangerous rm operation not ruled outprompt" section; no allow rule or hook approves it. [lines 846-861] [Source] - Time limits and denials for critical-path removals in
autoandbypassPermissionsmodes (v2.1.281+), per surface, withCLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUTto change it. [lines 918-955] [Source] acceptEdits:touchwith options, globs or prefixes still prompts. Files passed via--settings,--mcp-configor--agentsare protected. [lines 264-271] [Source]- Auto mode is available in cloud sessions in Anthropic-hosted environments. [line 369] [Source]
plugins/mods/gallery [Source]
Inputaccepts arowsprop for multi-line fields (Enter submits, backslash+Enter or Shift+Enter adds a line). [lines 245-290] [Source]
plugins/mods/reference [Source]
- New limits table rows: string lengths, nesting depth 32, 20,000 elements, 262,144
Rastercells, 2 MiB of images. [lines 371-377] [Source] - Step names and
size/weight/mono/tabularrequire v2.1.299+. [lines 332-355] [Source]
plugins/mods/troubleshoot [Source]
- Expanded guidance for invalid
ui.rendertrees, with example messages and a new "Aui.renderline saysrefused" section. [lines 225-247] [Source]
plugins/mods/interface [Source]
- Invalid-tree failure example and
Inputrows/ scrolling key behavior. [lines 420-545] [Source]
plugins/mods/test [Source]
- Test handle
input()supports multi-line text forrowsfields andkind: 'change'. [line 311] [Source]
plugins/org [Source]
disableSideloadFlagsnow also covers the Agent SDKpluginsoption,CLAUDE_CODE_PLUGIN_DIRS,--mcp-configand more; cloud plugin suggestions note. [lines 181-362] [Source]
plugins/relevance [Source]
- Terminal suggestions from a marketplace appear only after an admin allowlists it in managed settings. [line 7] [Source]
self-hosted-environments-deploy [Source]
- New "Keep an idle session while its processes run" guide for
--hold-idle-fileand--max-hold-min. [lines 731-775] [Source] - Guidance on idle sessions holding runner slots and using
--release-idle-session-min; package-registry mirror added to network host requirements. [lines 67-725] [Source]
self-hosted-environments-reference [Source]
- Runner CLI flag reference updated for the new hold-idle flags.
vs-code [Source]
- Mirrors the ide-integrations changes: selection/open-file context controls, PDF page reading,
@terminalreferences.
workflows [Source]
- Notes on resuming a workflow after leaving or backgrounding the session.
API changes
New Documents
None.
Changed documents
api/completions [Source]
- Text Completions prompt-format examples now show
\n\nHuman:and\n\nAssistant:inline instead of broken line-wrapped text (same fix across all SDK language variants). [lines 252-278] [Source]
build-with-claude/preserved-thinking [Source]
- The API can drop a thinking block produced by another account no longer in good standing; the request still succeeds. Applies to Fable, Mythos, Opus 5, Opus 5.5, Sonnet 5.5 and Haiku 5.5. [line 76] [Source]
- Removed the Claude API skill automation prompt; the check is now described as a manual procedure. [line 439] [Source]
manage-claude/access-transparency [Source]
- Turning the Compliance API off stops access to Access Transparency events, not their recording. [line 75] [Source]
manage-claude/api-and-data-retention [Source]
- Claude in Microsoft Foundry is now HIPAA-eligible with a BAA plus the HIPAA configuration enabled on the Azure subscription; only Claude Platform on AWS remains unavailable. [lines 57-64] [Source]
manage-claude/claude-tag-api [Source]
- Bundle target examples updated to a typed
targetobject (slack_channel/slack_workspace) across CLI and SDKs; C# and Java examples fixed. [lines 1920-2160] [Source]
manage-claude/compliance-faq [Source]
- Clarified Compliance API on/off behavior in Claude Console: events captured earlier are kept, recording resumes when turned back on, and the change is logged as
org_compliance_api_settings_updated. [lines 19-27] [Source]
manage-claude/opentelemetry [Source]
managed-agents/self-hosted-sandboxes [Source]
- Workers now run on Linux or macOS hosts (macOS uses system Bash 3.2); quickstart gets separate Linux and macOS steps with
~/workspaceas the working directory on macOS. [lines 38-216] [Source]
managed-agents/self-hosted-sandboxes-memory [Source]
- New "Prepare a macOS host" section: create
/System/Volumes/Data/mnt/memory, add asynthetic.confentry, runapfs.util -t, and verify. Notes macOS volumes are case-insensitive by default. [lines 44-96] [Source]
managed-agents/self-hosted-sandboxes-operations [Source]
- Memory-mount troubleshooting now points macOS users to the macOS host preparation steps. [line 333] [Source]
managed-agents/self-hosted-sandboxes-reference [Source]
- Worker host requirement is now Linux or macOS; on macOS, set the working directory somewhere writable since
/workspacecan't be created. [lines 47-56] [Source]
models/*/migration-guide [Source]
- The Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 migration guides no longer promote the bundled Claude API skill for automating migration.