Claude Code 2.1.69

New primitives

Workflow recipes

Agentic relevance

2.1.69 is the most hook-dense release in recent history: `InstructionsLoaded` + `agent_id`/`agent_type` + `worktree` status-line field together give orchestrators a complete signal surface for instruction-load timing, sub-agent identity, and multi-worktree context. The `includeGitInstructions`/`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` pair enables clean system-prompt surgery for agent fleets that manage their own git workflows. The `git-subdir` plugin source type and `/reload-plugins` command streamline the plugin authoring loop for agents that hot-patch their own tooling.

Hardening & fixes (90)

• Security fix: nested skill discovery no longer loads skills from gitignored directories like `node_modules`
• Security fix: symlink bypass blocked — writing through symlinked parent directory can no longer escape working directory in `acceptEdits` mode
• Security fix: sandbox no longer prompts for non-allowed domains when `allowManagedDomainsOnly` is set — blocked automatically
• Security fix: interactive tools (e.g., `AskUserQuestion`) in skill allowed-tools no longer silently auto-allowed; permission prompt is now shown
• Fixed trust dialog silently enabling all `.mcp.json` servers on first run
• Fixed `claude remote-control` crashing on npm installs ("bad option: --sdk-url")
• Fixed `--model claude-opus-4-0` / `claude-opus-4-1` resolving to deprecated versions
• Fixed macOS keychain corruption with multiple OAuth MCP servers (large blob stdin overflow)
• Fixed `.credentials.json` losing `subscriptionType` on transient profile endpoint failure
• Fixed ghost dotfiles appearing as untracked after sandboxed Bash on Linux
• Fixed Shift+Enter printing `[27;2;13~` in Ghostty over SSH
• Fixed stash (Ctrl+S) cleared on submit while Claude is working
• Fixed Ctrl+O transcript toggle freezing in long sessions with many file edits
• Fixed plan mode feedback input not supporting multi-line entry
• Fixed cursor not moving into blank lines at top of input box
• Fixed `/stats` crash on malformed timestamps in transcript files
• Fixed brief hang after streaming error on long sessions (transcript truncation)
• Fixed `--setting-sources user` not blocking dynamically discovered project skills
• Fixed duplicate CLAUDE.md/slash commands/agents/rules in worktree nested inside main repo
• Fixed plugin Stop/SessionEnd/etc hooks not firing after `/plugin` operations
• Fixed plugin hooks silently dropped when two plugins share the same `${CLAUDE_PLUGIN_ROOT}/...` template
• Fixed memory leak in long-running SDK/CCR sessions (retained conversation messages)
• Fixed API 400 errors in forked agents when resuming mid-tool-batch interrupted sessions
• Fixed "unexpected tool_use_id" error when resuming sessions starting with orphaned tool result
• Fixed teammates accidentally spawning nested teammates via Agent tool `name` parameter
• Fixed `CLAUDE_CODE_MAX_OUTPUT_TOKENS` ignored during conversation compaction
• Fixed `/compact` summary rendering as user bubble in SDK consumers
• Fixed voice space bar stuck after failed voice activation
• Fixed worktree file copy on Windows
• Fixed global `.claude` folder detection on Windows
• Fixed multi-GB memory spike when committing with large untracked binary files
• Fixed Escape not interrupting running turn when input box has draft text
• Fixed Android app crash on local slash commands in Remote Control sessions
• Fixed memory leak: old message array versions in React Compiler `memoCache`
• Fixed memory leak: REPL render scopes accumulated over long sessions (~35MB/1000 turns)
• Fixed memory retention: parent conversation history pinned in in-process teammates after `/clear`
• Fixed memory leak: hook events accumulating unboundedly in interactive mode
• Fixed hang when `--mcp-config` points to corrupted file
• Fixed slow startup when many skills/plugins installed
• Fixed `cd <outside-dir> && <cmd>` permission prompt surfacing wrong command
• Fixed conditional `.claude/rules/*.md` and nested CLAUDE.md not loading in print mode (`-p`)
• Fixed `/clear` not fully clearing all session caches
• Fixed terminal flicker at scrollback boundary
• Fixed UI frame drops on macOS with OAuth MCP servers (regression from 2.1.x)
• Fixed frame stalls during typing from synchronous debug log flushes
• Fixed `TeammateIdle`/`TaskCompleted` hooks to support `{"continue": false, "stopReason": "..."}` to stop teammate
• Fixed `WorktreeCreate`/`WorktreeRemove` plugin hooks being silently ignored
• Fixed skill descriptions with colons failing to load from SKILL.md frontmatter
• Fixed project skills without `description:` frontmatter not appearing in available skills list
• Fixed `/context` showing identical token counts for all MCP tools from a server
• Fixed literal `nul` file creation on Windows from CMD-style `2>nul` redirection in Git Bash
• Fixed extra blank lines below tool calls in expanded subagent transcript view
• Fixed Tab/arrow keys not cycling Settings tabs when `/config` search box is focused but empty
• Fixed service key OAuth sessions (CCR) spamming `[ERROR]` 403 logs from profile-scoped endpoints
• Fixed inconsistent color for "Remote Control active" status indicator
• Fixed Voice waveform cursor covering first suffix letter
• Fixed Voice input showing all 5 warmup spaces instead of capping at ~2
• Improved spinner performance (isolated 50ms animation loop)
• Improved UI rendering performance with React Compiler in native binaries
• Improved `--worktree` startup (eliminated git subprocess)
• Improved macOS startup (eliminated redundant settings reloads)
• Improved macOS startup for enterprise/team users (skipped unnecessary keychain lookup)
• Improved MCP `-p` startup (pipelined config fetch + concurrency pool)
• Improved voice startup (removed warmup pulse re-render stutter)
• Improved MCP binary content handling: PDFs/Office/audio saved to disk with correct extension instead of raw base64 in context; WebFetch also saves binary alongside summary
• Improved memory usage in long sessions (stabilized `onSubmit`)
• Improved LSP tool rendering and memory context building (no longer reads entire files)
• Improved session upload and memory sync (avoids reading large files before size/binary checks)
• Improved file operation performance (avoids reading contents for existence checks, 6 sites)
• Improved docs: clarified `--append-system-prompt-file` / `--system-prompt-file` work in interactive mode
• Reduced baseline memory ~16MB (deferred Yoga WASM preloading)
• Reduced memory footprint for SDK/CCR sessions with stream-json output
• Reduced memory usage when resuming large sessions
• Reduced token usage on multi-agent tasks with more concise subagent final reports
• Changed Sonnet 4.5 Pro/Max/Team Premium users auto-migrated to Sonnet 4.6
• Changed `/resume` picker to show most recent prompt instead of first
• Changed claude.ai MCP connector failures to show notification instead of silently disappearing
• Changed example command suggestions to deterministic generation (no longer calls Haiku)
• Changed resuming after compaction: no longer produces preamble recap
• [SDK] Changed task creation: `activeForm` field no longer required
• [VSCode] Added compaction display as collapsible "Compacted chat" card
• [VSCode] Permission mode picker respects `permissions.disableBypassPermissionsMode`
• [VSCode] Fixed RTL text rendering reversed in chat panel (regression in v2.1.63)
• Added Ctrl+U keybinding on empty bash prompt to exit bash mode (UX, not a new invocable primitive)
• Added numeric keypad support for interview question option selection (UX)
• Added Voice STT support for 10 new languages (language coverage, not new primitive)
• Added effort level display in logo/spinner (display)
• Added agent name display in terminal title with `--agent` (display)
• Added one-time Desktop startup suggestion prompt on macOS/Windows (display)
• Added Team plan policy limit fetching for OAuth users (infrastructure)

Raw changelog

## 2.1.69

- Added the `/claude-api` skill for building applications with the Claude API and Anthropic SDK
- Added Ctrl+U on an empty bash prompt (`!`) to exit bash mode, matching `escape` and `backspace`
- Added numeric keypad support for selecting options in Claude's interview questions (previously only the number row above QWERTY worked)
- Added optional name argument to `/remote-control` and `claude remote-control` (`/remote-control My Project` or `--name "My Project"`) to set a custom session title visible in claude.ai/code
- Added Voice STT support for 10 new languages (20 total) — Russian, Polish, Turkish, Dutch, Ukrainian, Greek, Czech, Danish, Swedish, Norwegian
- Added effort level display (e.g., "with low effort") to the logo and spinner, making it easier to see which effort setting is active
- Added agent name display in terminal title when using `claude --agent`
- Added `sandbox.enableWeakerNetworkIsolation` setting (macOS only) to allow Go programs like `gh`, `gcloud`, and `terraform` to verify TLS certificates when using a custom MITM proxy with `httpProxyPort`
- Added `includeGitInstructions` setting (and `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` env var) to remove built-in commit and PR workflow instructions from Claude's system prompt
- Added `/reload-plugins` command to activate pending plugin changes without restarting
- Added a one-time startup prompt suggesting Claude Code Desktop on macOS and Windows (max 3 showings, dismissible)
- Added `${CLAUDE_SKILL_DIR}` variable for skills to reference their own directory in SKILL.md content
- Added `InstructionsLoaded` hook event that fires when CLAUDE.md or `.claude/rules/*.md` files are loaded into context
- Added `agent_id` (for subagents) and `agent_type` (for subagents and `--agent`) to hook events
- Added `worktree` field to status line hook commands with name, path, branch, and original repo directory when running in a `--worktree` session
- Added `pluginTrustMessage` in managed settings to append organization-specific context to the plugin trust warning shown before installation
- Added policy limit fetching (e.g., remote control restrictions) for Team plan OAuth users, not just Enterprise
- Added `pathPattern` to `strictKnownMarketplaces` for regex-matching file/directory marketplace sources alongside `hostPattern` restrictions
- Added plugin source type `git-subdir` to point to a subdirectory within a git repo
- Added `oauth.authServerMetadataUrl` config option for MCP servers to specify a custom OAuth metadata discovery URL when standard discovery fails
- Fixed a security issue where nested skill discovery could load skills from gitignored directories like `node_modules`
- Fixed trust dialog silently enabling all `.mcp.json` servers on first run. You'll now see the per-server approval dialog as expected
- Fixed `claude remote-control` crashing immediately on npm installs with "bad option: --sdk-url" (anthropics/claude-code#28334)
- Fixed `--model claude-opus-4-0` and `--model claude-opus-4-1` resolving to deprecated Opus versions instead of current
- Fixed macOS keychain corruption when using multiple OAuth MCP servers. Large OAuth metadata blobs could overflow the `security -i` stdin buffer, silently leaving stale credentials behind and causing repeated `/login` prompts.
- Fixed `.credentials.json` losing `subscriptionType` (showing "Claude API" instead of "Claude Pro"/"Claude Max") when the profile endpoint transiently fails during token refresh (anthropics/claude-code#30185)
- Fixed ghost dotfiles (`.bashrc`, `HEAD`, etc.) appearing as untracked files in the working directory after sandboxed Bash commands on Linux
- Fixed Shift+Enter printing `[27;2;13~` instead of inserting a newline in Ghostty over SSH
- Fixed stash (Ctrl+S) being cleared when submitting a message while Claude is working
- Fixed ctrl+o (transcript toggle) freezing for many seconds in long sessions with lots of file edits
- Fixed plan mode feedback input not supporting multi-line text entry (backslash+Enter and Shift+Enter now insert newlines)
- Fixed cursor not moving down into blank lines at the top of the input box
- Fixed `/stats` crash when transcript files contain entries with missing or malformed timestamps
- Fixed a brief hang after a streaming error on long sessions (the transcript was being fully rewritten to drop one line; it is now truncated in place)
- Fixed `--setting-sources user` not blocking dynamically discovered project skills
- Fixed duplicate CLAUDE.md, slash commands, agents, and rules when running from a worktree nested inside its main repo (e.g. `claude -w`)
- Fixed plugin Stop/SessionEnd/etc hooks not firing after any `/plugin` operation
- Fixed plugin hooks being silently dropped when two plugins use the same `${CLAUDE_PLUGIN_ROOT}/...` command template
- Fixed memory leak in long-running SDK/CCR sessions where conversation messages were retained unnecessarily
- Fixed API 400 errors in forked agents (autocompact, summarization) when resuming sessions that were interrupted mid-tool-batch
- Fixed "unexpected tool_use_id found in tool_result blocks" error when resuming conversations that start with an orphaned tool result
- Fixed teammates accidentally spawning nested teammates via the Agent tool's `name` parameter
- Fixed `CLAUDE_CODE_MAX_OUTPUT_TOKENS` being ignored during conversation compaction
- Fixed `/compact` summary rendering as a user bubble in SDK consumers (Claude Code Remote web UI, VSCode extension)
- Fixed voice space bar getting stuck after a failed voice activation (module loading race, cold GrowthBook)
- Fixed worktree file copy on Windows
- Fixed global `.claude` folder detection on Windows
- Fixed symlink bypass where writing new files through a symlinked parent directory could escape the working directory in `acceptEdits` mode
- Fixed sandbox prompting users to approve non-allowed domains when `allowManagedDomainsOnly` is enabled in managed settings — non-allowed domains are now blocked automatically with no bypass
- Fixed interactive tools (e.g., `AskUserQuestion`) being silently auto-allowed when listed in a skill's allowed-tools, bypassing the permission prompt and running with empty answers
- Fixed multi-GB memory spike when committing with large untracked binary files in the working tree
- Fixed Escape not interrupting a running turn when the input box has draft text. Use Up arrow to pull queued messages back for editing, or Ctrl+U to clear the input line.
- Fixed Android app crash when running local slash commands (`/voice`, `/cost`) in Remote Control sessions
- Fixed a memory leak where old message array versions accumulated in React Compiler `memoCache` over long sessions
- Fixed a memory leak where REPL render scopes accumulated over long sessions (~35MB over 1000 turns)
- Fixed memory retention in in-process teammates where the parent's full conversation history was pinned for the teammate's lifetime, preventing GC after `/clear` or auto-compact
- Fixed a memory leak in interactive mode where hook events could accumulate unboundedly during long sessions
- Fixed hang when `--mcp-config` points to a corrupted file
- Fixed slow startup when many skills/plugins are installed
- Fixed `cd <outside-dir> && <cmd>` permission prompt to surface the chained command instead of only showing "Yes, allow reading from <dir>/"
- Fixed conditional `.claude/rules/*.md` files (with `paths:` frontmatter) and nested CLAUDE.md files not loading in print mode (`claude -p`)
- Fixed `/clear` not fully clearing all session caches, reducing memory retention in long sessions
- Fixed terminal flicker caused by animated elements at the scrollback boundary
- Fixed UI frame drops on macOS when using MCP servers with OAuth (regression from 2.1.x)
- Fixed occasional frame stalls during typing caused by synchronous debug log flushes
- Fixed `TeammateIdle` and `TaskCompleted` hooks to support `{"continue": false, "stopReason": "..."}` to stop the teammate, matching `Stop` hook behavior
- Fixed `WorktreeCreate` and `WorktreeRemove` plugin hooks being silently ignored
- Fixed skill descriptions with colons (e.g., "Triggers include: X, Y, Z") failing to load from SKILL.md frontmatter
- Fixed project skills without a `description:` frontmatter field not appearing in Claude's available skills list
- Fixed `/context` showing identical token counts for all MCP tools from a server
- Fixed literal `nul` file creation on Windows when the model uses CMD-style `2>nul` redirection in Git Bash
- Fixed extra blank lines appearing below each tool call in the expanded subagent transcript view (Ctrl+O)
- Fixed Tab/arrow keys not cycling Settings tabs when `/config` search box is focused but empty
- Fixed service key OAuth sessions (CCR containers) spamming `[ERROR]` logs with 403s from profile-scoped endpoints
- Fixed inconsistent color for "Remote Control active" status indicator
- Fixed Voice waveform cursor covering the first suffix letter when dictating mid-input
- Fixed Voice input showing all 5 spaces during warmup instead of capping at ~2 (aligning with the "keep holding…" hint)
- Improved spinner performance by isolating the 50ms animation loop from the surrounding shell, reducing render and CPU overhead during turns
- Improved UI rendering performance in native binaries with React Compiler
- Improved `--worktree` startup by eliminating a git subprocess on the startup path
- Improved macOS startup by eliminating redundant settings-file reloads when managed settings resolve
- Improved macOS startup for Claude.ai enterprise/team users by skipping an unnecessary keychain lookup
- Improved MCP `-p` startup by pipelining claude.ai config fetch with local connections and using a concurrency pool instead of sequential batching
- Improved voice startup by removing imperceptible warmup pulse animations that were causing re-render stutter
- Improved MCP binary content handling: tools returning PDFs, Office documents, or audio now save decoded bytes to disk with the correct file extension instead of dumping raw base64 into the conversation context. WebFetch also saves binary responses alongside its summary.
- Improved memory usage in long sessions by stabilizing `onSubmit` across message updates
- Improved LSP tool rendering and memory context building to no longer read entire files
- Improved session upload and memory sync to avoid reading large files into memory before size/binary checks
- Improved file operation performance by avoiding reading file contents for existence checks (6 sites)
- Improved documentation to clarify that `--append-system-prompt-file` and `--system-prompt-file` work in interactive mode (the docs previously said print mode only)
- Reduced baseline memory by ~16MB by deferring Yoga WASM preloading
- Reduced memory footprint for SDK and CCR sessions using stream-json output
- Reduced memory usage when resuming large sessions (including compacted history)
- Reduced token usage on multi-agent tasks with more concise subagent final reports
- Changed Sonnet 4.5 users on Pro/Max/Team Premium to be automatically migrated to Sonnet 4.6
- Changed the `/resume` picker to show your most recent prompt instead of the first one. This also resolves some titles appearing as `(session)`.
- Changed claude.ai MCP connector failures to show a notification instead of silently disappearing from the tool list
- Changed example command suggestions to be generated deterministically instead of calling Haiku
- Changed resuming after compaction to no longer produce a preamble recap before continuing
- [SDK] Changed task creation to no longer require the `activeForm` field — the spinner falls back to the task subject
- [VSCode] Added compaction display as a collapsible "Compacted chat" card with the summary inside
- [VSCode] The permission mode picker now respects `permissions.disableBypassPermissionsMode` from your effective Claude Code settings (including managed/policy settings) — when set to `disable`, bypass permissions mode is hidden from the picker
- [VSCode] Fixed RTL text (Arabic, Hebrew, Persian) rendering reversed in the chat panel (regression in v2.1.63)