Claude Code 2.1.89
**Headless resumption with deferred permissions** — `"defer"` permission decision in `PreToolUse` hooks + `-p --resume` now enables agents and headless scripts to pause at permission gates and resume after hook re-evaluation, unblocking long-running workflows and interactive permission resolution without operator presence.
New primitives
"defer" permission decisionhook-return-valueAllows PreToolUse hooks to pause tool execution and resume later with `-p --resume` for re-evaluation
CLAUDE_CODE_NO_FLICKER=1environment-variableOpts into flicker-free alt-screen rendering with virtualized scrollback for cleaner terminal output
PermissionDenied hookhook-typeFires after auto mode classifier denials; can return `{retry: true}` to signal model should retry the denied command
Named subagents in @ mentioncapabilityTypeahead suggestions now include named subagents for direct mention and reference
MCP_CONNECTION_NONBLOCKING=trueenvironment-variableFor `-p` mode, skips MCP connection wait entirely and bounds `--mcp-config` server connections at 5s instead of blocking
/buddy commandcommandApril 1st feature: hatch a small creature that watches you code
Workflow recipes
Long-running orchestration workflows can now pause at permission boundaries, notify human operators, and resume with fresh evaluation — without blocking or losing session state. Named subagents in mention discovery let agents route permission decisions to specialized auditors.
Build a multi-stage agent cascade where a headless controller agent encounters a PreToolUse hook that returns {defer: true} on high-risk operations (deployments, credential writes, destructive commands). The hook stores the deferred tool request, control returns to the agent loop, and the agent mentions a specialized @audit-agent subagent to inspect the request and approve/deny. The parent agent resumes with -p --resume, the hook re-evaluates with updated approval state, and proceeds or fails with the auditor's decision. Combines permission gates, subagent orchestration, and stateful resumption.
Scheduled cloud agents and persistent orchestration loops can now render cleanly without terminal flicker and skip MCP connection blocking, reducing visual noise and latency in observability dashboards and long-running monitor loops.
Configure a scheduled agent (schedule skill) that runs every 5 minutes to probe service health, ingest metrics, and trigger downstream workflows. Enable CLAUDE_CODE_NO_FLICKER=1 to eliminate scrollback artifacts during heavy parallel Bash tool use, and set MCP_CONNECTION_NONBLOCKING=true to skip waiting for slow MCP servers at startup. The Bash tool warns if any formatter/linter modifies previously-read files, preventing stale-edit errors during repeated probe cycles. Result: clean, fast, debuggable observability agent suitable for dashboards.
Agentic relevance
Permission deferral and named subagent discovery enable headless orchestration workflows where multi-step agent chains can request operator approval at permission gates without blocking the entire session. `CLAUDE_CODE_NO_FLICKER` and `MCP_CONNECTION_NONBLOCKING` reduce latency and visual noise in long-running automated sessions, making them more suitable for orchestration loops and scheduled cloud agents.
Hardening & fixes (46)
- Fixed `Edit(//path/**)` and `Read(//path/**)` allow rules to check the resolved symlink target, not just the requested path
- Fixed voice push-to-talk not activating for some modifier-combo bindings, and voice mode on Windows failing with "WebSocket upgrade rejected with HTTP 101"
- Fixed Edit/Write tools doubling CRLF on Windows and stripping Markdown hard line breaks (two trailing spaces)
- Fixed `StructuredOutput` schema cache bug causing ~50% failure rate when using multiple schemas
- Fixed memory leak where large JSON inputs were retained as LRU cache keys in long-running sessions
- Fixed a crash when removing a message from very large session files (over 50MB)
- Fixed LSP server zombie state after crash — server now restarts on next request instead of failing until session restart
- Fixed prompt history entries containing CJK or emoji being silently dropped at 4KB boundaries in `~/.claude/history.jsonl`
- Fixed `/stats` undercounting tokens by excluding subagent usage, and losing historical data beyond 30 days
- Fixed `-p --resume` hangs when deferred tool input exceeds 64KB or no deferred marker exists
- Fixed `-p --continue` not resuming deferred tools
- Fixed `claude-cli://` deep links not opening on macOS
- Fixed MCP tool errors truncating to only the first content block on multi-element errors
- Fixed skill reminders and system context being dropped when sending messages with images via SDK
- Fixed PreToolUse/PostToolUse hooks to receive `file_path` as absolute path for Write/Edit/Read tools
- Fixed autocompact thrash loop — stops with actionable error instead of burning API calls
- Fixed prompt cache misses in long sessions caused by tool schema bytes changing mid-session
- Fixed nested CLAUDE.md files being re-injected dozens of times in long sessions
- Fixed `--resume` crash when transcript contains tool result from older CLI version or interrupted write
- Fixed misleading "Rate limit reached" message — now shows actual entitlement error with actionable hints
- Fixed hooks `if` condition filtering not matching compound commands or env-var prefixes
- Fixed collapsed search/read group badges duplicating in terminal scrollback during heavy parallel tool use
- Fixed notification `invalidates` not clearing currently-displayed notification immediately
- Fixed prompt briefly disappearing after submit when background messages arrived during processing
- Fixed Devanagari and other combining-mark text being truncated in assistant output
- Fixed rendering artifacts on main-screen terminals after layout shifts
- Fixed voice mode failing to request microphone permission on macOS Apple Silicon
- Fixed Shift+Enter submitting instead of inserting newline on Windows Terminal Preview 1.25
- Fixed periodic UI jitter during streaming in iTerm2 when running inside tmux
- Fixed PowerShell tool incorrectly reporting failures when commands wrote progress to stderr on Windows PowerShell 5.1
- Fixed potential out-of-memory crash when Edit tool used on very large files (>1 GiB)
- Improved collapsed tool summary to show "Listed N directories" for `ls`/`tree`/`du`
- Improved Bash tool to warn when formatter/linter command modifies previously-read files
- Improved `@`-mention typeahead to rank source files above MCP resources with similar names
- Improved PowerShell tool prompt with version-appropriate syntax guidance (5.1 vs 7+)
- Changed `Edit` to work on files viewed via `Bash` with `sed -n` or `cat` without separate `Read` call
- Changed hook output over 50K characters to be saved to disk with file path + preview
- Changed `cleanupPeriodDays: 0` to be rejected with validation error (previously silently disabled persistence)
- Changed thinking summaries to no longer generate by default in interactive sessions
- Documented `TaskCreated` hook event and its blocking behavior
- Preserved task notifications when backgrounding running command with Ctrl+B
- PowerShell tool on Windows: external-command arguments with both double-quote and whitespace now prompt
- `/env` now applies to PowerShell tool commands
- `/usage` now hides redundant "Current week (Sonnet only)" bar for Pro and Enterprise plans
- Image paste no longer inserts trailing space
- Pasting `!command` into empty prompt now enters bash mode
Raw changelog
## 2.1.89
- Added `"defer"` permission decision to `PreToolUse` hooks — headless sessions can pause at a tool call and resume with `-p --resume` to have the hook re-evaluate
- Added `CLAUDE_CODE_NO_FLICKER=1` environment variable to opt into flicker-free alt-screen rendering with virtualized scrollback
- Added `PermissionDenied` hook that fires after auto mode classifier denials — return `{retry: true}` to tell the model it can retry
- Added named subagents to `@` mention typeahead suggestions
- Added `MCP_CONNECTION_NONBLOCKING=true` for `-p` mode to skip the MCP connection wait entirely, and bounded `--mcp-config` server connections at 5s instead of blocking on the slowest server
- Auto mode: denied commands now show a notification and appear in `/permissions` → Recent tab where you can retry with `r`
- Fixed `Edit(//path/**)` and `Read(//path/**)` allow rules to check the resolved symlink target, not just the requested path
- Fixed voice push-to-talk not activating for some modifier-combo bindings, and voice mode on Windows failing with "WebSocket upgrade rejected with HTTP 101"
- Fixed Edit/Write tools doubling CRLF on Windows and stripping Markdown hard line breaks (two trailing spaces)
- Fixed `StructuredOutput` schema cache bug causing ~50% failure rate when using multiple schemas
- Fixed memory leak where large JSON inputs were retained as LRU cache keys in long-running sessions
- Fixed a crash when removing a message from very large session files (over 50MB)
- Fixed LSP server zombie state after crash — server now restarts on next request instead of failing until session restart
- Fixed prompt history entries containing CJK or emoji being silently dropped when they fall on a 4KB boundary in `~/.claude/history.jsonl`
- Fixed `/stats` undercounting tokens by excluding subagent usage, and losing historical data beyond 30 days when the stats cache format changes
- Fixed `-p --resume` hangs when the deferred tool input exceeds 64KB or no deferred marker exists, and `-p --continue` not resuming deferred tools
- Fixed `claude-cli://` deep links not opening on macOS
- Fixed MCP tool errors truncating to only the first content block when the server returns multi-element error content
- Fixed skill reminders and other system context being dropped when sending messages with images via the SDK
- Fixed PreToolUse/PostToolUse hooks to receive `file_path` as an absolute path for Write/Edit/Read tools, matching the documented behavior
- Fixed autocompact thrash loop — now detects when context refills to the limit immediately after compacting three times in a row and stops with an actionable error instead of burning API calls
- Fixed prompt cache misses in long sessions caused by tool schema bytes changing mid-session
- Fixed nested CLAUDE.md files being re-injected dozens of times in long sessions that read many files
- Fixed `--resume` crash when transcript contains a tool result from an older CLI version or interrupted write
- Fixed misleading "Rate limit reached" message when the API returned an entitlement error — now shows the actual error with actionable hints
- Fixed hooks `if` condition filtering not matching compound commands (`ls && git push`) or commands with env-var prefixes (`FOO=bar git push`)
- Fixed collapsed search/read group badges duplicating in terminal scrollback during heavy parallel tool use
- Fixed notification `invalidates` not clearing the currently-displayed notification immediately
- Fixed prompt briefly disappearing after submit when background messages arrived during processing
- Fixed Devanagari and other combining-mark text being truncated in assistant output
- Fixed rendering artifacts on main-screen terminals after layout shifts
- Fixed voice mode failing to request microphone permission on macOS Apple Silicon
- Fixed Shift+Enter submitting instead of inserting a newline on Windows Terminal Preview 1.25
- Fixed periodic UI jitter during streaming in iTerm2 when running inside tmux
- Fixed PowerShell tool incorrectly reporting failures when commands like `git push` wrote progress to stderr on Windows PowerShell 5.1
- Fixed a potential out-of-memory crash when the Edit tool was used on very large files (>1 GiB)
- Improved collapsed tool summary to show "Listed N directories" for `ls`/`tree`/`du` instead of "Read N files"
- Improved Bash tool to warn when a formatter/linter command modifies files you have previously read, preventing stale-edit errors
- Improved `@`-mention typeahead to rank source files above MCP resources with similar names
- Improved PowerShell tool prompt with version-appropriate syntax guidance (5.1 vs 7+)
- Changed `Edit` to work on files viewed via `Bash` with `sed -n` or `cat`, without requiring a separate `Read` call first
- Changed hook output over 50K characters to be saved to disk with a file path + preview instead of being injected directly into context
- Changed `cleanupPeriodDays: 0` in settings.json to be rejected with a validation error — it previously silently disabled transcript persistence
- Changed thinking summaries to no longer be generated by default in interactive sessions — set `showThinkingSummaries: true` in settings.json to restore
- Documented `TaskCreated` hook event and its blocking behavior
- Preserved task notifications when backgrounding a running command with Ctrl+B
- PowerShell tool on Windows: external-command arguments containing both a double-quote and whitespace now prompt instead of auto-allowing (PS 5.1 argument-splitting hardening)
- `/env` now applies to PowerShell tool commands (previously only affected Bash)
- `/usage` now hides redundant "Current week (Sonnet only)" bar for Pro and Enterprise plans
- Image paste no longer inserts a trailing space
- Pasting `!command` into an empty prompt now enters bash mode, matching typed `!` behavior
- `/buddy` is here for April 1st — hatch a small creature that watches you code