Claude docs changes for May 30th, 2026 [diff]

Executive Summary

  • Skills-directory plugins now auto-load from .claude/skills/ without a marketplace install, and a new claude plugin init command scaffolds them in place
  • WebSocket (type: "ws") added as a fourth MCP server transport type for persistent bidirectional connections
  • Auto mode is now available on Bedrock, Vertex, and Foundry for Opus 4.7 and Opus 4.8 (opt in with CLAUDE_CODE_ENABLE_AUTO_MODE=1)
  • EnterWorktree can now switch between Claude-managed worktrees mid-session without returning to the canonical repo root
  • Memory stores documented with a 2,000-memory limit and new best practices section for staying under it

New Claude Code versions

2.1.157

New features

  • Plugins in .claude/skills directories are now automatically loaded — no marketplace or install step required
  • Added claude plugin init <name> to scaffold a new plugin directly in .claude/skills
  • Added autocomplete for /plugin arguments: subcommands, installed plugin names, and plugins from known marketplaces
  • claude agents: the agent field in settings.json is now honored for dispatched sessions; pass --agent <name> to override it per session
  • EnterWorktree can now switch between Claude-managed worktrees mid-session
  • tool_decision telemetry events now include tool_parameters (bash commands, MCP/skill names) when OTEL_LOG_TOOL_DETAILS=1
  • Added a "Workflow keyword trigger" setting in /config to stop the word "workflow" in a prompt from triggering a dynamic workflow
  • Pressing Backspace immediately after a workflow trigger keyword now dismisses the workflow request (same as alt+w)

Existing feature improvements

  • Worktrees managed by Claude are now left unlocked when the agent finishes, so git worktree remove/prune can clean them up
  • /terminal-setup now disables GPU acceleration in VS Code, Cursor, and Windsurf integrated terminals to prevent garbled-text rendering
  • Feature of the Week credit-claim status now appears as a notification in the status area instead of a line above the prompt
  • claude agents: slash-command autocomplete in the dispatch input now matches substrings
  • Removed the "bash commands will be sandboxed" startup banner — sandbox status still visible in /status and when a command is blocked
  • Removed the "/ide for …" startup hint toast
  • Improved performance of long and resumed conversations by eliminating redundant message-rendering recomputations

Major bug fixes

  • Fixed unprocessable images (zero-byte, corrupt) attached via paste, MCP, or dialog crashing the request instead of becoming a text placeholder
  • Fixed sandbox network permission prompts appearing in auto and bypass-permissions mode when using the desktop app, IDE extensions, or SDK
  • Fixed claude agents completed sessions not retiring when an idle subagent was still parked or had leaked a backgrounded shell
  • Fixed claude agents pressing Esc not cancelling a slow "opening…", leaving the list unresponsive
  • Fixed background agent worktrees under .claude/worktrees/ being orphaned after the 30-day job retention sweep
  • Fixed background sessions re-attached after a sleep/wake not telling the model the correct date
  • Fixed copy-on-select in claude agents not reaching the system clipboard inside tmux with set-clipboard on (regression in 2.1.153)
  • Fixed --resume not reporting background subagents that were running when the previous Claude Code process exited
  • Fixed --worktree returning to the canonical repo root instead of the current linked worktree
  • Fixed the /model picker showing an incorrect "Newer version available" hint when the selected model is already the newest in its family
  • Fixed literal markdown markers (backticks, asterisks) appearing in in-progress message text in fullscreen mode
  • Fixed the terminal freezing after approving the managed-settings security dialog at startup
  • Fixed right-click paste duplicating the clipboard in VS Code, Cursor, and Windsurf integrated terminals
  • WSL: fixed image paste (alt+v keybinding), screenshot paste on Windows 11, and added support for dragging images from Windows Explorer
  • [IDE] Fixed clicking Stop while a background subagent is running not actually stopping it
  • [VSCode] Fixed the fast mode indicator not appearing on Opus 4.8

2.1.158

New features

  • Auto mode is now available on Bedrock, Vertex, and Foundry for Opus 4.7 and Opus 4.8 — opt in by setting CLAUDE_CODE_ENABLE_AUTO_MODE=1

Claude Code changes

Changed documents

agent-sdk/hosting [Source]

  • Major rewrite: page expanded from a brief FAQ into a comprehensive self-hosting guide. New sections cover the subprocess model, session patterns (ephemeral, long-running, hybrid, multi-agent container), container provisioning, and production concerns (persistence, observability, auth/secrets, scaling, cost, multi-tenant isolation). [line 9] [Source]
  • Multi-tenant isolation options documented: settingSources: [], CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, per-tenant CLAUDE_CONFIG_DIR, and per-tenant cwd
  • Known limitations table added: no session timeout, memory growth, rate limit fanouts, no per-subagent wall-clock deadline

agent-sdk/overview [Source]

  • Python SDK now requires Python 3.10+; troubleshooting tip added for No matching distribution found pip error

agent-sdk/quickstart [Source]

  • Windows-specific installation instructions added: py -m venv .venv, .venv\Scripts\Activate.ps1, and a note on PowerShell execution policy

agent-sdk/subagents [Source]

  • New section "Scale up with dynamic workflows" recommends the Workflow tool for dozens-to-hundreds of agents; notes availability in TypeScript Agent SDK v0.3.149+

agent-sdk/typescript [Source]

  • New Workflow tool input schema documented: script, name, scriptPath, args, resumeFromRunId fields
  • New WorkflowOutput schema documented: status, taskId, runId, summary, transcriptDir, scriptPath, error fields
  • AskUserQuestionOutput: new response field for freeform user replies that bypass structured questions
  • applyFlagSettings() documentation clarifies which settings take effect mid-session vs. require a new session

agent-sdk/user-input [Source]

  • AskUserQuestionOutput.response: new optional field documented; when set, Claude receives "The user responded: …" instead of per-question answers

agent-view [Source]

  • claude agents now accepts --agent flag to set the default subagent for dispatched sessions. [line 344] [Source]
  • Version compatibility table expanded: --agent and honoring the agent setting requires v2.1.157+. [line 358] [Source]

cli-reference [Source]

  • claude agents now accepts --agent flag to set the default subagent for dispatched sessions

desktop [Source]

  • Clarified multi-agent limitation: parallel session orchestration is CLI-only, but dynamic workflows (available in Desktop) support multi-agent work within one session

env-vars [Source]

  • CLAUDE_CODE_DISABLE_TERMINAL_TITLE: also skips the background Haiku request that generates the session title in Agent SDK and claude -p sessions
  • CLAUDE_EFFORT: "ultra" removed as a distinct level; ultracode reports as xhigh

errors [Source]

  • New fix documented for "thinking blocks cannot be modified" error: run claude update first if using Opus 4.7 or Opus 4.8 — versions before v2.1.156 can trigger this error during normal tool use

hooks [Source]

  • effort.level field: "ultra" removed as a distinct level; ultracode reports as "xhigh" instead

interactive-mode [Source]

  • Image paste shortcut updated: Alt+V now applies to both Windows and WSL; both Ctrl+V and Alt+V are bound by default on WSL

keybindings [Source]

  • chat:imagePaste binding updated: Alt+V now applies to Windows and WSL

mcp [Source]

  • New "Option 4: Add a remote WebSocket server" — type: "ws" entries with url, headers, headersHelper, timeout, alwaysLoad fields; authentication is header-only; claude mcp add --transport does not accept ws. [line 114] [Source]
  • Plugin MCP transport support updated: WebSocket added alongside stdio, SSE, and HTTP
  • New behavior: if headers.Authorization is configured and the server rejects it, Claude reports connection failure instead of falling back to OAuth

memory [Source]

  • autoMemoryDirectory: now accepted from any settings scope (user, project, local, policy, --settings); when set in project/local settings, requires workspace trust dialog acceptance

monitoring-usage [Source]

  • New tool_parameters attribute added to tool_decision (permission decision) event when OTEL_LOG_TOOL_DETAILS=1; documents shape per tool type including new WorkspaceBash. [line 533] [Source]
  • MCP monitoring: tool_decision now includes mcp_server_name and mcp_tool_name in tool_parameters. [line 969] [Source]
  • Security use-case table updated: "rejected commands" now queries tool_decision event

permission-modes [Source]

  • .cargo added to the list of protected directories in default permission mode

permissions [Source]

  • bypassPermissions mode now also skips prompts for writes to .cargo (added alongside .git, .vscode, .idea, .husky). [line 47] [Source]

plugin-marketplaces [Source]

  • Clarified that each user can register only one marketplace per name; adding a second with the same name replaces the first

plugins [Source]

  • New section "Develop a plugin in your skills directory" — documents claude plugin init scaffolding a plugin in ~/.claude/skills/<name>/ that auto-loads as <name>@skills-dir without a marketplace install step

plugins-reference [Source]

  • New major section "Skills-directory plugins" — documents auto-loading from skills directories, scope/trust rules, project-scope restrictions, and /reload-plugins. [line 330] [Source]
  • New CLI command plugin init documented with full options table (--description, --author, --author-email, --with, --force) and examples. [line 763] [Source]

settings [Source]

  • agent setting now also sets the default agent for sessions dispatched from claude agents
  • autoMemoryDirectory: now accepted from any settings scope; requires workspace trust dialog when set in project/local settings
  • New workflowKeywordTriggerEnabled setting: controls whether typing "workflow" in a prompt triggers a dynamic workflow (default true). [line 250] [Source]

skills [Source]

  • New note: adding .claude-plugin/plugin.json to a skill folder loads it as a plugin named <name>@skills-dir
  • Live change detection clarification: covers SKILL.md text only; hooks/MCP/agents/output-styles inside a plugin require /reload-plugins
  • ${CLAUDE_EFFORT} substitution: "ultra" removed as a distinct value; ultracode reports as xhigh

statusline [Source]

  • effort.level field: "ultra" removed; ultracode reports as xhigh

sub-agents [Source]

  • bypassPermissions mode: .cargo added to the list of directories where prompts are skipped

terminal-config [Source]

  • /terminal-setup behavior change in VS Code, Cursor, and Windsurf: now also sets terminal.integrated.gpuAcceleration to "off" to prevent garbled text; documented how to undo this change

tools-reference [Source]

  • EnterWorktree: from within a worktree or a subagent with pinned working directory, only the path form is available and the target must be under .claude/worktrees/
  • New Workflow tool documented: runs a dynamic workflow script that orchestrates many subagents in the background; requires permission approval. [line 53] [Source]

workflows [Source]

  • New way to cancel a workflow keyword trigger: press Backspace while the cursor is immediately after the highlighted word (in addition to alt+w)
  • Documented workflowKeywordTriggerEnabled setting in /config to permanently disable the keyword trigger

worktrees [Source]

  • EnterWorktree: from within a worktree, Claude can now switch directly to another worktree under .claude/worktrees/ by calling EnterWorktree with the target path. [line 33] [Source]
  • Cleanup behavior clarified: automatic cleanup sweep covers both subagent and background-session worktrees

API changes

Changed documents

agents-and-tools/mcp-connector [Source]

  • New section "When Claude uses MCP tools" — explains trigger conditions (explicit/implicit requests vs. general knowledge) and guidance on steering tool-use frequency via system prompt
  • Denylist section: added recommendation to denylist write/destructive tools for read-only assistants or human-confirmation workflows
  • Multi-server section: new note that clear, specific tool descriptions improve selection accuracy; recommendation to use defer_loading with Tool Search for large tool sets

agents-and-tools/remote-mcp-servers [Source]

  • Cross-reference added linking to the new "When Claude uses MCP tools" section in mcp-connector.md

agents-and-tools/tool-use/computer-use-tool [Source]

  • New tip #7: when using computer_20251124 with enable_zoom: true, Claude zooms in on small text or specific UI elements; guidance on how to trigger zoom behavior

agents-and-tools/tool-use/overview [Source]

  • New section "When Claude uses tools" — explains the default auto tool_choice behavior, when Claude calls tools vs. responds directly, and how to steer behavior via system prompt or tool_choice

agents-and-tools/tool-use/web-fetch-tool [Source]

  • New section "When Claude fetches" — documents when Claude triggers a fetch (specific URL or named resource) vs. responds directly (general knowledge)
  • New combined search+fetch note: when both tools are enabled, Claude uses search to find a URL for a named resource, then fetches it

build-with-claude/adaptive-thinking [Source]

  • high effort level description changed from "always thinks" to "almost always thinks"
  • New guidance on system prompt phrases to encourage thinking (e.g., "Think carefully before responding")
  • New per-message thinking steering from the user turn: appending "Please think hard before responding." encourages thinking; "Answer directly without deliberating." suppresses it. [line 163] [Source]

build-with-claude/context-windows [Source]

  • New note: Claude's tool selection is designed to work with 100K+ token contexts; references tool context management and Tool Search for large tool sets

managed-agents/agent-setup [Source]

  • New behavior note: updating an agent does not automatically update coordinator rosters that reference it — coordinators keep the version pinned at their last create/update; must update the coordinator explicitly to delegate to a newer version

managed-agents/memory [Source]

  • Memory store cap documented: a store holds a maximum of 2,000 memories; writes to new memories fail when the limit is reached (existing memories remain readable/editable). [line 46] [Source]
  • "Limits" section replaced with "Best practices for memory management": guidance on focused stores, condensing/pruning before hitting the limit, attaching a new store, and limiting write access

managed-agents/multi-agent [Source]

  • Version pinning clarified: {"type": "agent", "id": ...} without a version pins to the latest version at coordinator creation time, not the agent's future latest version
  • New explicit note: coordinator configuration (including multiagent.agents roster) is snapshotted at create/update time and does not automatically pick up later agent updates