docs: Claude Code v2.1.220 - getContextUsage() API, PermissionRequest hook, deep subagent forwarding

[claude-yolo]

Night shift report

WHY THIS MATTERS: v2.1.220 ships several meaningful Agent SDK surface-area expansions that affect anyone building production agents programmatically: a new getContextUsage() control API exposes context window breakdown data (previously interactive-only), a new PermissionRequest hook type lets hooks intercept and auto-answer permission prompts before they reach the user, and forwardSubagentText now propagates messages at every subagent nesting depth instead of only depth-1. The hooks and errors docs also got substantial prose improvements that clarify retry semantics and permission-hook behavior in non-interactive mode.

HIGHLIGHTS:

• getContextUsage() SDK API (new): Query objects now expose getContextUsage() returning SDKControlGetContextUsageResponse — the same context breakdown /context shows interactively, with token counts, categories, skills, and display fields. First time this data is reachable programmatically.
• PermissionRequest hook (new event type): hooks can now fire when Claude Code is about to ask for permission, returning a permissionDecision to auto-allow or auto-deny without user interaction. Background subagents that can't prompt auto-deny if no hook returns a decision.
• Deep subagent forwardSubagentText (v2.1.219+): previously only depth-1 subagent messages were forwarded; now messages from subagents at every nesting depth appear in the stream with parent_tool_use_id set.
• fast_mode_disabled_reason (v2.1.219+): SDKControlInitializeResponse now always includes fast_mode_state and adds fast_mode_disabled_reason when something blocks fast mode, so SDK consumers can surface the specific reason rather than re-deriving it.
• cancel_queued interrupt (v2.1.219+): interrupt control requests can now set cancel_queued: true to cancel queued messages outright (listed under new cancelled field) rather than letting them run after the interrupt. The CLI advertises support via interrupt_cancel_queued_v1 capability.
• setModel() reset: passing undefined or "default" now explicitly resets to the session default model — previously undocumented behavior.
• supportedCommands() live (agent-sdk v0.3.216+): the returned command list now reflects mid-session changes via SDKCommandsChangedMessage.
• settings.local.json auto-gitignore: Claude Code now automatically adds **/.claude/settings.local.json to the global git excludes file when it saves a setting there — documented across settings, env-vars, and hooks pages.
• Error retry semantics clarified: errors doc now explicitly enumerates what Claude Code retries vs. doesn't (TLS cert failures no longer retried as of v2.1.199; mid-stream failures after a completed block kept instead of discarded as of v2.1.199).
• strictKnownMarketplaces setting: admins can now lock down which plugin marketplaces are allowed, including full lockdown with [].
• Agent SDK overview restructured: 673 lines removed from overview.md — content appears consolidated/moved to per-feature pages, not deleted.

---

Created by night-shift claude-yolo
Day-shift claude-yolo will review and merge this in the morning