Claude docs changes for October 27th, 2026 [diff]

Executive Summary

  • Claude Code 2.1.311 adds ultrathink as 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 with reloadPlugins({ 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 auto and bypassPermissions modes, plus a new CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT variable.
  • 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-file and --max-hold-min to self-hosted-runner to keep an idle session while the host reports processes it left running
  • ultrathink typed 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
  • /teleport warns 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_COMPACT in settings files and in a mod's $.env.set can now only turn compaction off
  • --output-format json / stream-json escape 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_TELEMETRY set 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 -p and SDK sessions saving transcript messages out of order
  • Fixed SubagentStop hooks 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_COMPACT being ignored by agent teammates and the rewind menu
  • Fixed /mcp authentication status being wrong for remote servers

Claude Code changes

New Documents

None.

Changed documents

agent-sdk/agent-loop [Source]

  • The dontAsk and bypassPermissions mode descriptions now note calls that still reach canUseTool or 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_policy to always_ask or always_deny (TypeScript SDK) on the config returned by createSdkMcpServer(). [lines 377-403] [Source]
  • Set destructiveHint: true on always_ask tools 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-ask connector tools, always_ask custom tools, network-path reads and critical-path removals. [lines 97-110] [Source]
  • Clarified how deny rules, always_deny policies, bypassPermissions and plan mode interact with canUseTool. [lines 23-50] [Source]
  • Documented the CLAUDE_SDK_CAN_USE_TOOL_SHADOWED warning. [line 69] [Source]
  • dontAsk mode lists the calls denied even when an allow rule matches; touch with options or prefixes is no longer auto-approved in acceptEdits. [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 an addPlugins option, with a troubleshooting section for when folders don't load. [lines 1135-1167] [Source]
  • McpSdkServerConfigWithInstance gains a tools list of the new McpServerToolPolicy type (permission_policy: always_allow / always_ask / always_deny), changeable mid-session through setMcpServers(). 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, /loop tasks), 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_desktop is a legacy key with no effect when Desktop uses bootstrapUrl, 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_token on /v1/logs and /v1/metrics when otelHeadersHelper is 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 SearchPlugins and SuggestPluginInstall to 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, medium default, 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_HANDOFF and CLAUDE_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": true or upgrading the SDK. [lines 3473-3503] [Source]
  • claude rm <id> --discard-unpushed documented for sessions whose worktree has unpushed commits. [line 5114] [Source]

hooks-guide [Source]

  • Hooks can't loosen calls to Agent SDK tools marked always_ask. [line 628] [Source]

ide-integrations [Source]

  • New attachSelection (v2.1.300+) and attachOpenFile (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:name output. [lines 202-210] [Source]

mcp [Source]

  • New "Elicitation modes Claude Code declares" section for MCP server authors. [line 1623] [Source]

model-config [Source]

  • ultrathink can raise a turn to xhigh effort 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 auto clears the saved level. [lines 685-709] [Source]

permission-modes [Source]

  • New "The Dangerous rm operation not ruled out prompt" section; no allow rule or hook approves it. [lines 846-861] [Source]
  • Time limits and denials for critical-path removals in auto and bypassPermissions modes (v2.1.281+), per surface, with CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT to change it. [lines 918-955] [Source]
  • acceptEdits: touch with options, globs or prefixes still prompts. Files passed via --settings, --mcp-config or --agents are protected. [lines 264-271] [Source]
  • Auto mode is available in cloud sessions in Anthropic-hosted environments. [line 369] [Source]

plugins/mods/gallery [Source]

  • Input accepts a rows prop 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 Raster cells, 2 MiB of images. [lines 371-377] [Source]
  • Step names and size/weight/mono/tabular require v2.1.299+. [lines 332-355] [Source]

plugins/mods/troubleshoot [Source]

  • Expanded guidance for invalid ui.render trees, with example messages and a new "A ui.render line says refused" section. [lines 225-247] [Source]

plugins/mods/interface [Source]

  • Invalid-tree failure example and Input rows / scrolling key behavior. [lines 420-545] [Source]

plugins/mods/test [Source]

  • Test handle input() supports multi-line text for rows fields and kind: 'change'. [line 311] [Source]

plugins/org [Source]

  • disableSideloadFlags now also covers the Agent SDK plugins option, CLAUDE_CODE_PLUGIN_DIRS, --mcp-config and 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-file and --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, @terminal references.

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 target object (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]

  • Added an overview video on tracing agents with OpenTelemetry. [line 16] [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 ~/workspace as 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 a synthetic.conf entry, run apfs.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 /workspace can'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.

release-notes/overview [Source]

  • The Claude Tag API beta announcement is now dated October 23, 2026. [line 15] [Source]