claude_hooks 1.2.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ff845df334960263a1d36b01aeba57393609c59acbc63424572c9d7fdca7999
-  data.tar.gz: 70029c193102d9a63b6d6e5ff8361fcf42e506bff26435c907ec4a06010a571a
+  metadata.gz: cca02ef252dc6564f109b8f4a09e7ef7c107695dbfb76bafbf44313215f1713e
+  data.tar.gz: f8d90408c943f7b0a8b91d9d067557bafb015dfa33943a369839badb189c5374
 SHA512:
-  metadata.gz: 28a4548cafd93c7f5d5c9d1f577399d8e90503c2e4ae1fa279a9723234045848c0b3bdbb1c41df9f0808d375eb5d345a5210d9db46fe74ba3332fb2394920530
-  data.tar.gz: e2555f3731aad5bacb7e572c9630fa9e39721b625684664bc2ea41d9b0579af146f697b10a6d99410368140ebb7cd37de53b2bd195e2a2c13a5100722502fcd2
+  metadata.gz: dba4a8356c7a11faedeb51d5ff8cf03bdf70e365ee0b922f9b11e779d24d13037469d2f3bbf0facedf555bb031a35ddffea06e9043f6375276a4faf9bc394161
+  data.tar.gz: b1a5334e3a2001a567063b8b896b4fac0debea9e344f0491569902c96eb31f3a8b793b50b67d1bbb1aa0ba0619d9fb0f5183b70c0146107685aa16f54b3708c6

data/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-10-14
+
+Spec-parity update tracking the Claude Code hooks documentation changes analyzed in issues #61, #62, #63, #65, #69, #70, and #71. (Issue #64 required no changes; #70 is docs-only.)
+
+### Added
+
+- **`PreModelSwitch` hook event** (`ClaudeHooks::PreModelSwitch` / `ClaudeHooks::Output::PreModelSwitch`): runs before a requested model switch (Claude Code v2.1.251+). Decision-control hook modeled on `PreToolUse` — builders `approve!`/`allow!`, `deny!`/`block_switch!`, `ask!` (via `permissionDecision`), plus a top-level `block!(reason)` (`decision: "block"`). Input readers: `from_model`, `to_model`, `requested_model`, `source`, `context_tokens`, `prompt_cache_warm`, `cache_ttl`, `estimated_cache_write_usd`, `pricing`. Output accessors `allowed?`/`denied?`/`blocked?`/`should_ask?`, `permission_decision`, `permission_reason`, `decision`, `reason`. Always exits 0 (JSON API); merge precedence `deny > ask > allow`, a top-level block makes the merged decision `deny`, and the merge only emits a `permissionDecision` when some hook set one.
+- **`PostModelSwitch` hook event** (`ClaudeHooks::PostModelSwitch` / `ClaudeHooks::Output::PostModelSwitch`): runs after the session's model changes (Claude Code v2.1.251+). Context-only (can't block); builder `add_additional_context!` / `add_context!`, output accessor `additional_context`. Same input readers as `PreModelSwitch`, with extra `source` values `"auto"`/`"resume"`.
+- **`PostToolUse#classifier_context!(note)`** and **`Output::PostToolUse#classifier_context`**: set/read `hookSpecificOutput.classifierContext`, a note for the auto-mode classifier (Claude Code v2.1.236+). Carried through multi-handler merge.
+- **`TaskCreated#block!(reason)`** / **`allow!`** and **`Output::TaskCreated#decision`/`#reason`/`#blocked?`**: block task creation via a top-level `decision: "block"` (the `reason` is returned to Claude as the task-creation error).
+- **`scratchpad_dir` common input reader** on `ClaudeHooks::Base` (Claude Code v2.1.257+). Not added to `COMMON_INPUT_FIELDS` — it is version-gated and often absent, so it never triggers the missing-field warning.
+- **`mcp_server` input reader** on `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PostToolUseFailure`, and `PermissionDenied` (Claude Code v2.1.274+): for MCP tools, a hash with the server's `name` and `source` (where its definition came from). `nil` for non-MCP tools; not added to `input_fields`.
+- **`UserPromptSubmit` session title and prompt suppression**: `session_title` input reader; `session_title!(title)` and `suppress_original_prompt!` builders (`hookSpecificOutput.sessionTitle` / `suppressOriginalPrompt`); `output.session_title` / `output.suppress_original_prompt?` accessors, both carried through merge (last title wins; suppression wins if any hook asks). `suppress_original_prompt!` keeps a blocked prompt's text out of the block message only; the text can still appear in the session transcript and prompt history.
+- **`SessionStart` resume/fork cost fields**: readers `seconds_since_last_response`, `context_tokens`, `prompt_cache_likely_expired`, `estimated_cache_write_usd` (present when `source` is `"resume"`/`"fork"`).
+
+### Changed
+
+- **`Notification` now always exits 0.** Claude Code ignores a Notification hook's exit code and stderr, so `Output::Notification` no longer exits 2 on `continue: false` — it always exits 0 and writes JSON to stdout, keeping the `terminal_sequence!` (desktop-notification) pattern working.
+- **`WorktreeRemove` exit code now reports failure.** Upstream reversed the contract: a non-zero exit now fails the worktree removal when the directory still exists (previously the exit code was ignored). With a `WorktreeRemove` hook configured, the hook itself does the cleanup (exit 0 means "counts as removed") and its JSON output is discarded. `Output::WorktreeRemove#exit_code` now follows `continue` (0/2) instead of hard-coding 0; use `prevent_continue!(reason)` to block. Note that a `WorktreeRemove` hook that raises now also leaves the worktree on disk, since `CLI.run_hook` exits 1 on errors and Claude Code fails the removal on any non-zero exit.
+- **`UserPromptSubmit#add_additional_context!` / `#empty_additional_context!` no longer wipe other `hookSpecificOutput` fields**, so they compose with the new title/suppression builders in any order. Output for existing single-call usage is unchanged.
+- **`TaskCreated` `continue: false` is ignored** by Claude Code; block via the new `block!` (top-level `decision`) or exit 2 instead.
+- **Docs**: `Stop`/`SubagentStop` input tables now list the inherited `last_assistant_message`, `background_tasks`, and `session_crons` readers; notes added for the stop-hook continuation cap (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`), SubagentStop firing for internal agents, and expanded pasted content in `UserPromptSubmit#prompt`.
+
+### Fixed
+
+- **`Output::PostToolUse.merge` no longer drops rewritten tool output.** `updatedToolOutput` / `updatedMCPToolOutput` (from `update_tool_output!` / `update_mcp_tool_output!`) were lost when merged with any other output, so e.g. a redacting hook's rewrite was silently discarded when composed with a context hook. The last non-nil rewrite now wins, as with `PreToolUse`'s `updatedInput`.
+- **`additionalContext` survives merging on `PreToolUse`, `PostToolBatch`, and `UserPromptExpansion`.** These merges dropped it; contexts are now joined with `"\n\n"` like the other context-carrying events.
+- **`PermissionRequest` no longer warns about a missing `tool_use_id`.** Claude Code doesn't send that field to PermissionRequest hooks, so it was removed from `input_fields` (and the README/API docs); every real invocation used to log a spurious missing-field warning.
+
+### Deprecated
+
+- **`suppressOutput` is a no-op.** `suppress_output!` / `show_output!` / `output.suppress_output?` remain callable for backward compatibility, but Claude Code accepts the field without acting on it.
+- **`Setup` output is discarded.** `Setup#add_additional_context!` remains callable but Claude Code discards all Setup JSON output; use a `SessionStart` hook to inject context instead.
+- **`PermissionRequest#tool_use_id`** always returns `nil` (Claude Code doesn't send the field); kept callable for backward compatibility.
+
+### Notes
+
+- Total hook event classes: 33 (was 31).
+- No DSL methods removed — deprecated helpers stay callable as no-ops.
+- All test files pass (`ruby test/run_all_tests.rb`). Two existing tests that used `Notification` as an "exits 2 on `continue: false`" example were retargeted to `PreCompact`, and the `WorktreeRemove` exit-code test was rewritten for the new blocking contract.
+
+## [1.3.0] - 2026-08-15
+
+### Added
+
+- **`DirectoryAdded` hook event** (`ClaudeHooks::DirectoryAdded` / `ClaudeHooks::Output::DirectoryAdded`): non-blocking hook that runs after a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request. Exposes `directory` and `source` readers plus a `system_message!` builder.
+
 ## [1.2.1] - 2026-07-15
 
 ### Added

data/README.md

@@ -289,12 +289,15 @@ The framework supports the following hook types:
 | **[PostCompact](docs/API/POST_COMPACT.md)** | `ClaudeHooks::PostCompact` | Runs after transcript compaction completes |
 | **[ConfigChange](docs/API/CONFIG_CHANGE.md)** | `ClaudeHooks::ConfigChange` | Runs when Claude Code configuration changes; can block it |
 | **[CwdChanged](docs/API/CWD_CHANGED.md)** | `ClaudeHooks::CwdChanged` | Runs when the working directory changes |
+| **[DirectoryAdded](docs/API/DIRECTORY_ADDED.md)** | `ClaudeHooks::DirectoryAdded` | Runs when a working directory is added mid-session |
 | **[FileChanged](docs/API/FILE_CHANGED.md)** | `ClaudeHooks::FileChanged` | Runs when a watched file is created, modified, or deleted |
 | **[InstructionsLoaded](docs/API/INSTRUCTIONS_LOADED.md)** | `ClaudeHooks::InstructionsLoaded` | Runs when a CLAUDE.md instructions file is loaded |
 | **[Elicitation](docs/API/ELICITATION.md)** | `ClaudeHooks::Elicitation` | Runs when an MCP server requests user input |
 | **[ElicitationResult](docs/API/ELICITATION_RESULT.md)** | `ClaudeHooks::ElicitationResult` | Runs after an elicitation response is provided |
 | **[WorktreeCreate](docs/API/WORKTREE_CREATE.md)** | `ClaudeHooks::WorktreeCreate` | Runs when Claude Code creates a git worktree |
-| **[WorktreeRemove](docs/API/WORKTREE_REMOVE.md)** | `ClaudeHooks::WorktreeRemove` | Runs when a git worktree is removed |
+| **[WorktreeRemove](docs/API/WORKTREE_REMOVE.md)** | `ClaudeHooks::WorktreeRemove` | Runs when a git worktree is removed; can block the removal |
+| **[PreModelSwitch](docs/API/PRE_MODEL_SWITCH.md)** | `ClaudeHooks::PreModelSwitch` | Runs before a requested model switch; can allow, deny, ask, or block it |
+| **[PostModelSwitch](docs/API/POST_MODEL_SWITCH.md)** | `ClaudeHooks::PostModelSwitch` | Runs after the session's model changes; adds context (can't block) |
 | **[SessionEnd](docs/API/SESSION_END.md)** | `ClaudeHooks::SessionEnd` | Runs when a Claude Code session ends |
 
 ## 🚀 Claude Hook Flow
@@ -393,23 +396,23 @@ The framework supports all existing hook types with their respective input field
 
 | Hook Type | Input Fields |
 |-----------|--------------|
-| **Common (all hooks)**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `permission_mode`, `prompt_id`, `agent_id`, `agent_type`, `effort` |
-| **SessionStart**  | `source`, `model`, `session_title` |
+| **Common (all hooks)**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `permission_mode`, `prompt_id`, `agent_id`, `agent_type`, `effort`, `scratchpad_dir` |
+| **SessionStart**  | `source`, `model`, `session_title` + on resume/fork: `seconds_since_last_response`, `context_tokens`, `prompt_cache_likely_expired`, `estimated_cache_write_usd` |
 | **Setup**  | `source` |
-| **UserPromptSubmit**  | `prompt` |
+| **UserPromptSubmit**  | `prompt`, `session_title` |
 | **UserPromptExpansion**  | `expansion_type`, `command_name`, `command_args`, `command_source`, `prompt` |
 | **Notification**  | `message`, `notification_type` |
 | **MessageDisplay**  | `turn_id`, `message_id`, `index`, `final`, `delta` |
-| **PreToolUse**  | `tool_name`, `tool_input`, `tool_use_id` |
-| **PermissionRequest**  | `tool_name`, `tool_input`, `tool_use_id`, `permission_suggestions` |
-| **PermissionDenied**  | `tool_name`, `tool_input`, `tool_use_id`, `reason` |
-| **PostToolUse**  | `tool_name`, `tool_input`, `tool_response`, `tool_use_id` |
+| **PreToolUse**  | `tool_name`, `tool_input`, `tool_use_id`, `mcp_server` (MCP tools) |
+| **PermissionRequest**  | `tool_name`, `tool_input`, `permission_suggestions`, `mcp_server` (MCP tools) |
+| **PermissionDenied**  | `tool_name`, `tool_input`, `tool_use_id`, `reason`, `mcp_server` (MCP tools) |
+| **PostToolUse**  | `tool_name`, `tool_input`, `tool_response`, `tool_use_id`, `mcp_server` (MCP tools) |
 | **PostToolBatch**  | `tool_calls` |
-| **PostToolUseFailure**  | `tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`, `duration_ms` |
+| **PostToolUseFailure**  | `tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`, `duration_ms`, `mcp_server` (MCP tools) |
 | **Stop**  | `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons` |
 | **StopFailure**  | `error`, `error_details`, `last_assistant_message` |
 | **SubagentStart**  | *(common only: `agent_id`, `agent_type`)* |
-| **SubagentStop**  | `stop_hook_active`, `agent_transcript_path` + common `agent_id`/`agent_type` |
+| **SubagentStop**  | `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`, `agent_transcript_path` + common `agent_id`/`agent_type` |
 | **TaskCreated**  | `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` |
 | **TaskCompleted**  | `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` |
 | **TeammateIdle**  | `teammate_name`, `team_name` |
@@ -417,12 +420,15 @@ The framework supports all existing hook types with their respective input field
 | **PostCompact**  | `trigger`, `compact_summary` |
 | **ConfigChange**  | `source`, `file_path` |
 | **CwdChanged**  | `old_cwd`, `new_cwd` |
+| **DirectoryAdded**  | `directory`, `source` |
 | **FileChanged**  | `file_path`, `event` |
 | **InstructionsLoaded**  | `file_path`, `load_reason` |
 | **Elicitation**  | `mcp_server_name`, `message`, `mode`, `url`, `elicitation_id`, `requested_schema` |
 | **ElicitationResult**  | `mcp_server_name`, `action`, `mode`, `elicitation_id`, `content` |
 | **WorktreeCreate**  | `name` |
 | **WorktreeRemove**  | `worktree_path` |
+| **PreModelSwitch**  | `from_model`, `to_model`, `requested_model`, `source`, `context_tokens`, `prompt_cache_warm`, `cache_ttl`, `estimated_cache_write_usd`, `pricing` |
+| **PostModelSwitch**  | `from_model`, `to_model`, `requested_model`, `source`, `context_tokens`, `prompt_cache_warm`, `cache_ttl`, `estimated_cache_write_usd`, `pricing` |
 | **SessionEnd**  | `reason` |
 
 ### Hooks API
@@ -646,11 +652,11 @@ Claude Code hooks support multiple exit codes with different behaviors depending
 | SessionEnd       | Operation continues<br/><br />Logged to debug only (`--debug`) | Non-blocking error<br/><br />Logged to debug only (`--debug`)                | N/A<br/><br />Logged to debug only (`--debug`)                                   |
 
 > [!NOTE]
-> The 20 events added in `1.2.0` follow the same families. Their per-event exit-code behavior is documented on each API page under [`docs/API/`](docs/API/):
-> - **Blocking via top-level `decision`** (behave like `PreToolUse`/`Stop`): `UserPromptExpansion`, `PostToolBatch`, `ConfigChange`.
-> - **Blocking via `exit 2` / `continue: false`** (no `decision` field): `TaskCreated`, `TaskCompleted`, `TeammateIdle`.
-> - **JSON-API special** (always `exit 0`, decision in `hookSpecificOutput`): `PermissionDenied`, `Elicitation`, `ElicitationResult`, `WorktreeCreate` (bare-path stdout).
-> - **Non-blocking / context-only** (exit code effectively ignored): `Setup`, `SubagentStart`, `PostToolUseFailure`, `StopFailure`, `PostCompact`, `CwdChanged`, `FileChanged`, `InstructionsLoaded`, `WorktreeRemove`, `MessageDisplay`.
+> The additional events follow the same families. Their per-event exit-code behavior is documented on each API page under [`docs/API/`](docs/API/):
+> - **Blocking via top-level `decision`** (behave like `PreToolUse`/`Stop`): `UserPromptExpansion`, `PostToolBatch`, `ConfigChange`, `TaskCreated` (also honors `exit 2`).
+> - **Blocking via `exit 2` / `continue: false`** (no `decision` field): `TaskCompleted`, `TeammateIdle`, `WorktreeRemove` (a non-zero exit now fails the removal).
+> - **JSON-API special** (always `exit 0`, decision in `hookSpecificOutput`): `PermissionDenied`, `Elicitation`, `ElicitationResult`, `WorktreeCreate` (bare-path stdout), `PreModelSwitch` (allow/deny/ask, also honors top-level `decision`/`exit 2`).
+> - **Non-blocking / context-only** (exit code effectively ignored): `Setup`, `SubagentStart`, `PostToolUseFailure`, `StopFailure`, `PostCompact`, `CwdChanged`, `DirectoryAdded`, `FileChanged`, `InstructionsLoaded`, `MessageDisplay`, `Notification` (exit code **and** stderr ignored), `PostModelSwitch` (stdout added as context).
 
 
 #### Manually outputing and exiting example with success

data/docs/API/COMMON.md

@@ -17,6 +17,7 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `agent_id` | Get the agent ID (present in subagent contexts) |
 | `agent_type` | Get the agent type (present in subagent contexts) |
 | `effort` | Get the effort level string (reads `effort.level`) |
+| `scratchpad_dir` | Path to the session's scratchpad directory. Absent (`nil`) when there is no scratchpad or the temp dir is unavailable (Claude Code v2.1.257+) |
 | `read_transcript` | Read the transcript file |
 | `transcript` | Alias for `read_transcript` |
 
@@ -27,8 +28,8 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 |--------|-------------|
 | `allow_continue!` | Allow Claude to continue (default) |
 | `prevent_continue!(reason)` | Stop Claude with reason |
-| `suppress_output!` | Hide stdout from transcript |
-| `show_output!` | Show stdout in transcript (default) |
+| `suppress_output!` | **Deprecated / no-op.** Claude Code accepts `suppressOutput` but no longer acts on it. Safe to call; has no effect |
+| `show_output!` | **Deprecated / no-op** (see `suppress_output!`) |
 | `clear_specifics!` | Clear hook-specific output |
 | `system_message!(message)` | Set a system message shown to the user (not to Claude) |
 | `clear_system_message!` | Clear the system message |
@@ -47,7 +48,7 @@ This object provides helpers to access output data, for merging multiple outputs
 | `output_data` | RAW output data accessor |
 | `output.continue?` | Check if Claude should continue processing |
 | `output.stop_reason` | Get the stop reason if continue is false |
-| `output.suppress_output?` | Check if output should be suppressed from transcript |
+| `output.suppress_output?` | Check the `suppressOutput` flag (deprecated — Claude Code ignores it) |
 | `output.hook_specific_output` | Get the hook-specific output data |
 | `output.system_message` | Get the system message if any |
 | `output.terminal_sequence` | Get the terminal escape sequence (if set) |

data/docs/API/DIRECTORY_ADDED.md

@@ -0,0 +1,34 @@
+# DirectoryAdded API
+
+Available when inheriting from `ClaudeHooks::DirectoryAdded`:
+
+Runs after a working directory is added mid-session via `/add-dir` or the SDK `register_repo_root` control request. Non-blocking — the directory is already added when the hook runs.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `directory` | Absolute path of the directory that was added |
+| `source` | How the directory was added: `'slash_command'` for `/add-dir` or `'register_repo_root'` for the SDK control request |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `system_message!` | Set a message delivered to Claude as context on the next turn (`slash_command`) or written to the debug log (`register_repo_root`) |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.system_message` | The configured system message |
+
+## Hook Exit Codes
+
+Non-blocking. Exit code is ignored; only `systemMessage` is consumed.

data/docs/API/NOTIFICATION.md

@@ -11,7 +11,7 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 |--------|-------------|
 | `message` | Get the notification message content |
 | `notification_message` | Alias for `message` |
-| `notification_type` | Get the notification type: `'permission_prompt'`, `'idle_prompt'`, `'auth_success'`, `'elicitation_dialog'` |
+| `notification_type` | Get the notification type: `'permission_prompt'`, `'idle_prompt'`, `'auth_success'`, `'elicitation_dialog'`, `'elicitation_url_dialog'`, `'elicitation_complete'`, `'elicitation_response'`, `'agent_needs_input'`, `'agent_completed'`, `'quota_auto_resume_fired'`, `'quota_auto_resume_stale'`, `'quota_auto_resume_disabled'` |
 
 ## Hook State Helpers
 Notifications are outside facing and do not have any specific state to modify.
@@ -26,8 +26,9 @@ Notifications don't have any specific hook state and thus doesn't have any speci
 
 ## Hook Exit Codes
 
+Claude Code **ignores** a Notification hook's exit code and stderr, and discards `systemMessage`/`continue`, while still emitting `terminalSequence`. `ClaudeHooks::Output::Notification` therefore always exits `0` and writes JSON to stdout — even after `prevent_continue!` — so the `terminal_sequence!` (desktop-notification) pattern keeps working.
+
 | Exit Code | Behavior |
 |-----------|----------|
-| `exit 0` | Operation continues<br/>Logged to debug only (`--debug`) |
-| `exit 1` | Non-blocking error<br/>Logged to debug only (`--debug`) |
-| `exit 2` | N/A<br/>Logged to debug only (`--debug`) |
+| `exit 0` | Ignored — always the effective exit code |
+| any other | Ignored (exit code and stderr are discarded) |

data/docs/API/PERMISSION_DENIED.md

@@ -13,6 +13,7 @@ Runs when a permission request is denied. Can request that Claude Code retries t
 | `tool_name` | The name of the tool whose permission was denied |
 | `tool_input` | The input data for the tool |
 | `tool_use_id` | The unique identifier for this tool use |
+| `mcp_server` | For MCP tools, a hash with the server's `name` and `source` (where its definition came from: `plugin`, `sdk`, `user`, `project`, …). Base trust decisions on `source`, not the name. `nil` for non-MCP tools (Claude Code v2.1.274+) |
 | `reason` | The reason the permission was denied |
 
 ## Hook State Helpers
@@ -35,3 +36,6 @@ Runs when a permission request is denied. Can request that Claude Code retries t
 ## Hook Exit Codes
 
 Exit code is ignored. Output is via `hookSpecificOutput.retry` (JSON API, exit 0 / stdout).
+
+> [!NOTE]
+> `retry: true` is ignored for "no-verdict" denials (where Claude Code produced no permission verdict to retry). `retry!` remains correct for the cases it applies to.

data/docs/API/PERMISSION_REQUEST.md

@@ -11,7 +11,8 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 |--------|-------------|
 | `tool_name` | Get the name of the tool requiring permission |
 | `tool_input` | Get the input data for the tool |
-| `tool_use_id` | Get the unique identifier for this tool use |
+| `tool_use_id` | **Deprecated** — Claude Code doesn't send `tool_use_id` to PermissionRequest hooks, so this is always `nil`. Kept for backward compatibility |
+| `mcp_server` | For MCP tools, a hash with the server's `name` and `source` (where its definition came from: `plugin`, `sdk`, `user`, `project`, …). Base trust decisions on `source`, not the name. `nil` for non-MCP tools (Claude Code v2.1.274+) |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
@@ -49,7 +50,7 @@ PermissionRequest hooks use the JSON API with exit code 0 for all permission dec
 |-----------|----------|
 | `exit 0` | Permission decision processed<br/>`STDOUT` contains JSON with decision |
 | `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
-| `exit 2` | **Not recommended for PermissionRequest**<br/>Use JSON API with exit 0 instead |
+| `exit 2` | **No longer honored for PermissionRequest** (Claude Code no longer treats it as a denial)<br/>Use the JSON API with exit 0 and a `decision.behavior` object instead |
 
 ## Example: Basic Permission Guard
 
@@ -63,7 +64,6 @@ class PermissionGuard < ClaudeHooks::PermissionRequest
 
   def call
     log "Permission requested for: #{tool_name}"
-    log "Tool use ID: #{tool_use_id}"
     log "Permission mode: #{permission_mode}"
 
     # Auto-allow safe tools

data/docs/API/POST_MODEL_SWITCH.md

@@ -0,0 +1,53 @@
+# PostModelSwitch API
+
+Available when inheriting from `ClaudeHooks::PostModelSwitch`:
+
+Runs after the session's model changes (Claude Code v2.1.251+), including changes Claude Code makes on its own (automatic fallback, restoring the model on resume). Use it to give Claude model-specific guidance. It **can't block** — the model has already changed. Its `STDOUT` is added as context for Claude.
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+`PostModelSwitch` receives the same fields as [PreModelSwitch](PRE_MODEL_SWITCH.md#input-helpers), with two extra `source` values: `'auto'` (a change Claude Code made on its own) and `'resume'` (the model restored when resuming a session). `requested_model` is `nil` when `source` is `'auto'`.
+
+| Method | Description |
+|--------|-------------|
+| `from_model` | Model ID the switch changes from |
+| `to_model` | Model ID the session switched to |
+| `requested_model` | The model the request named (`nil` for `'auto'`; the restored setting for `'resume'`) |
+| `source` | `'command'`, `'picker'`, `'sdk'`, `'auto'`, or `'resume'` |
+| `context_tokens` | Tokens the next request re-sends as its prompt |
+| `prompt_cache_warm` | Whether the prompt cache is likely still warm |
+| `cache_ttl` | Prompt cache lifetime: `'5m'` or `'1h'` |
+| `estimated_cache_write_usd` | Estimated cost (USD) of re-caching `context_tokens` |
+| `pricing` | How `estimated_cache_write_usd` was priced |
+
+## Hook State Helpers
+Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `add_additional_context!(context)` | Add context for Claude after the model changes |
+| `add_context!(context)` | Alias for `add_additional_context!` |
+
+## Output Helpers
+Output helpers provide access to the hook's output data and helper methods for working with the output state.
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.additional_context` | Get the additional context that was added |
+
+## Hook Exit Codes
+
+Context-only — `PostModelSwitch` can't block.
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Operation continues<br/>**`STDOUT` added as context to Claude** |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
+| `exit 2` | N/A — rendered as a `<hook name> hook error` notice; the session proceeds |

data/docs/API/POST_TOOL_USE.md

@@ -13,6 +13,7 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `tool_input` | Get the input that was passed to the tool |
 | `tool_response` | Get the tool's response/output |
 | `tool_use_id` | Get the unique identifier for this tool use (e.g., `"toolu_01ABC123..."`) |
+| `mcp_server` | For MCP tools, a hash with the server's `name` and `source` (where its definition came from: `plugin`, `sdk`, `user`, `project`, …). Base trust decisions on `source`, not the name. `nil` for non-MCP tools (Claude Code v2.1.274+) |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
@@ -24,6 +25,9 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `block_tool!(reason)` | Block the tool result from being used |
 | `approve_tool!(reason)` | Clear any previous block decision (default behavior) |
 | `add_additional_context!(context)` | Add context for Claude to consider after tool use |
+| `update_tool_output!(value)` | Rewrite the tool output shown to Claude |
+| `update_mcp_tool_output!(value)` | Rewrite an MCP tool's output |
+| `classifier_context!(note)` | Add a short note about this call's result for the auto-mode classifier, not for Claude (Claude Code v2.1.236+) |
 
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
@@ -36,6 +40,9 @@ Output helpers provide access to the hook's output data and helper methods for w
 | `output.reason` | Get the reason that was set for the decision |
 | `output.blocked?` | Check if the tool result has been blocked |
 | `output.additional_context` | Get the additional context that was added |
+| `output.classifier_context` | Get the note sent to the auto-mode classifier |
+| `output.updated_tool_output` | Get the rewritten tool output (if any) |
+| `output.updated_mcp_tool_output` | Get the rewritten MCP tool output (if any) |
 
 ## Hook Exit Codes
 

data/docs/API/POST_TOOL_USE_FAILURE.md

@@ -13,6 +13,7 @@ Runs when a tool call fails. Non-blocking — output and exit code are ignored e
 | `tool_name` | The name of the tool that failed |
 | `tool_input` | The input data for the tool |
 | `tool_use_id` | The unique identifier for this tool use |
+| `mcp_server` | For MCP tools, a hash with the server's `name` and `source` (where its definition came from: `plugin`, `sdk`, `user`, `project`, …). Base trust decisions on `source`, not the name. `nil` for non-MCP tools (Claude Code v2.1.274+) |
 | `error` | The error message |
 | `is_interrupt` | Whether the failure was caused by an interrupt (`true`/`false`) |
 | `interrupt?` | Alias for `is_interrupt` |

data/docs/API/PRE_MODEL_SWITCH.md

@@ -0,0 +1,67 @@
+# PreModelSwitch API
+
+Available when inheriting from `ClaudeHooks::PreModelSwitch`:
+
+Runs before Claude Code applies a model switch that you or a client requested (Claude Code v2.1.251+). Use it to block a switch, require confirmation, or show what the switch will cost before it happens. Claude Code doesn't run this hook for switches it makes on its own (automatic fallback, resume) — those reach [PostModelSwitch](POST_MODEL_SWITCH.md) only.
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `from_model` | Model ID the switch changes from |
+| `to_model` | Model ID the switch changes to (the matcher compares against its canonical name) |
+| `requested_model` | The model the request named (an alias, a full ID, or `nil` for the default model) |
+| `source` | Where the request came from: `'command'`, `'picker'`, or `'sdk'` |
+| `context_tokens` | Tokens the next request re-sends as its prompt (`0` before the first response) |
+| `prompt_cache_warm` | Whether the current model's prompt cache is likely still warm |
+| `cache_ttl` | Prompt cache lifetime requested for this session: `'5m'` or `'1h'` |
+| `estimated_cache_write_usd` | Estimated cost (USD) of re-caching `context_tokens` on `to_model` |
+| `pricing` | How `estimated_cache_write_usd` was priced: `'configured'`, `'catalog'`, or `'default'` |
+
+## Hook State Helpers
+Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `approve!(reason)` / `allow!(reason)` | Let the switch proceed (skips the warm-cache confirmation) |
+| `deny!(reason)` / `block_switch!(reason)` | Cancel the switch (`permissionDecision: 'deny'`) |
+| `ask!(reason)` | Prompt the user to confirm the switch (`permissionDecision: 'ask'`) |
+| `block!(reason)` | Cancel the switch via a top-level `decision: "block"` (equivalent to exit 2) |
+
+`PreModelSwitch` does not accept `defer`, `updatedInput`, or `additionalContext`. Only `/model` in an interactive session can show the `'ask'` prompt; elsewhere `'ask'` is treated as a refusal.
+
+## Output Helpers
+Output helpers provide access to the hook's output data and helper methods for working with the output state.
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.allowed?` | Whether the switch was allowed (`permission_decision == 'allow'`) |
+| `output.denied?` | Whether the switch was denied (`permission_decision == 'deny'`) |
+| `output.blocked?` | Whether the switch was blocked (via `deny` **or** top-level `decision: "block"`) |
+| `output.should_ask?` | Whether the user is asked to confirm (`permission_decision == 'ask'`) |
+| `output.permission_decision` | The permission decision: `'allow'`, `'deny'`, or `'ask'` |
+| `output.permission_reason` | The reason for the permission decision |
+| `output.decision` | The top-level decision (`'block'` or `nil`) |
+| `output.reason` | The top-level block reason |
+
+When multiple hooks return different decisions, precedence is `deny > ask > allow`. `Output::PreModelSwitch.merge` follows the same order. If any hook calls `block!`, the merged `permissionDecision` becomes `deny`. If no hook set a `permissionDecision`, the merge leaves the field out rather than adding an `allow`.
+
+## Hook Exit Codes
+
+`PreModelSwitch` uses the JSON API with exit code 0; the `permissionDecision` (or top-level `decision`) controls whether the switch proceeds.
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Decision processed<br/>`STDOUT` contains JSON with the decision |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user; the switch applies |
+| `exit 2` | **Cancels the switch**<br/>`STDERR` shown to user |
+
+> [!NOTE]
+> A `PreModelSwitch` hook that doesn't respond before its timeout **blocks** the switch (unlike `PreToolUse`). The default timeout for this event is 30 seconds.

data/docs/API/PRE_TOOL_USE.md

@@ -12,6 +12,7 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `tool_name` | Get the name of the tool being used |
 | `tool_input` | Get the input data for the tool |
 | `tool_use_id` | Get the unique identifier for this tool use (e.g., `"toolu_01ABC123..."`) |
+| `mcp_server` | For MCP tools, a hash with the server's `name` and `source` (where its definition came from: `plugin`, `sdk`, `user`, `project`, …). Base trust decisions on `source`, not the name. `nil` for non-MCP tools (Claude Code v2.1.274+) |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.

data/docs/API/SESSION_START.md

@@ -9,7 +9,13 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 
 | Method | Description |
 |--------|-------------|
-| `source` | Get the session start source: `'startup'`, `'resume'`, `'clear'`, or `'compact'` |
+| `source` | Get the session start source: `'startup'`, `'resume'`, `'clear'`, `'compact'`, or `'fork'` |
+| `model` | The session model (Claude Code doesn't always include it) |
+| `session_title` | The session title, when set |
+| `seconds_since_last_response` | Wall-clock seconds since the last response (present on `resume`/`fork`) |
+| `context_tokens` | Tokens the first request re-sends as its prompt (present on `resume`/`fork`) |
+| `prompt_cache_likely_expired` | Whether the prompt cache is likely expired (present on `resume`/`fork`) |
+| `estimated_cache_write_usd` | Estimated cost of re-caching `context_tokens` (present on `resume`/`fork`) |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.

data/docs/API/SETUP.md

@@ -18,8 +18,8 @@ Runs once during Claude Code startup (before any session begins). Use it to inje
 
 | Method | Description |
 |--------|-------------|
-| `add_additional_context!(context)` | Add contextual information for Claude |
-| `add_context!(context)` | Alias for `add_additional_context!` |
+| `add_additional_context!(context)` | **Deprecated / no-op.** Claude Code now discards all `Setup` JSON output, including `additionalContext`. Use a `SessionStart` hook to inject context instead |
+| `add_context!(context)` | Alias for `add_additional_context!` (also a no-op) |
 
 ## Output Helpers
 
@@ -33,5 +33,5 @@ Runs once during Claude Code startup (before any session begins). Use it to inje
 
 | Exit Code | Behavior |
 |-----------|----------|
-| `exit 0` | Continues normally; `STDOUT` added as context |
+| `exit 0` | Continues normally. Claude Code discards all `Setup` output (including stdout context) |
 | `exit 2` | N/A — non-blocking event |

data/docs/API/STOP.md

@@ -10,6 +10,9 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | Method | Description |
 |--------|-------------|
 | `stop_hook_active` | Check if Claude Code is already continuing as a result of a stop hook |
+| `last_assistant_message` | Text of Claude's final response for this turn |
+| `background_tasks` | Background tasks still running (array) |
+| `session_crons` | Scheduled session crons (array) |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
@@ -26,6 +29,9 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `block!(instructions)` | Alias for `continue_with_instructions!` |
 | `ensure_stopping!` | Allow Claude to stop normally (default behavior) |
 
+> [!NOTE]
+> Claude Code caps consecutive stop-hook continuations: after 8 in a row it lets the turn end despite the next block. The count resets each time Claude calls a tool. Raise the cap with the `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` environment variable. Check `stop_hook_active` to avoid loops.
+
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
 

data/docs/API/SUBAGENT_STOP.md

@@ -10,6 +10,13 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | Method | Description |
 |--------|-------------|
 | `stop_hook_active` | Check if Claude Code is already continuing as a result of a stop hook |
+| `last_assistant_message` | Text of the subagent's final response (with `SubagentHandback`, its closing text — not the delivered report) |
+| `background_tasks` | Background tasks still running (array, scoped to the parent session) |
+| `session_crons` | Scheduled session crons (array, scoped to the parent session) |
+| `agent_transcript_path` | Path to the subagent's own transcript |
+
+> [!NOTE]
+> SubagentStop also fires when Claude Code's own internal agents finish (e.g. prompt suggestions, `/btw` side questions). For those, `agent_type` is the agent the session itself runs as, so don't assume every event is a subagent Claude spawned.
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
@@ -26,6 +33,9 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `block!(instructions)` | Alias for `continue_with_instructions!` |
 | `ensure_stopping!` | Allow Claude to stop normally (default behavior) |
 
+> [!NOTE]
+> Claude Code caps consecutive stop-hook continuations: after 8 in a row it lets the turn end despite the next block. The count resets each time Claude calls a tool. Raise the cap with the `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` environment variable. Check `stop_hook_active` to avoid loops.
+
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
 

data/docs/API/TASK_CREATED.md

@@ -2,7 +2,7 @@
 
 Available when inheriting from `ClaudeHooks::TaskCreated`:
 
-Runs when a teammate task is created. Can block Claude from continuing via `prevent_continue!` or exit 2.
+Runs when a teammate task is created. Block task creation via `block!` (top-level `decision: "block"`) or exit 2. Claude Code **ignores** `continue: false` for this event, so `prevent_continue!` alone no longer blocks unless it results in exit 2.
 
 ## Input Helpers
 
@@ -22,9 +22,10 @@ Runs when a teammate task is created. Can block Claude from continuing via `prev
 
 | Method | Description |
 |--------|-------------|
-| `prevent_continue!(reason)` | Block Claude from continuing (`continue: false` + `stopReason`) |
+| `block!(reason)` | Block task creation via top-level `decision: "block"`; `reason` is returned to Claude as the task-creation error |
+| `allow!` / `unblock!` | Clear a previously set block |
 
-There is no top-level `decision` field for this event — block via `prevent_continue!` or exit 2.
+Block via `block!` (top-level `decision`) or exit 2. `continue: false` is ignored for this event.
 
 ## Output Helpers
 
@@ -32,12 +33,13 @@ There is no top-level `decision` field for this event — block via `prevent_con
 
 | Method | Description |
 |--------|-------------|
-| `output.continue?` | Whether Claude will continue |
-| `output.stop_reason` | The reason Claude was stopped |
+| `output.decision` | The decision (`'block'` or `nil`) |
+| `output.reason` | The block reason returned to Claude |
+| `output.blocked?` | Whether task creation was blocked (`decision == 'block'`) |
 
 ## Hook Exit Codes
 
 | Exit Code | Behavior |
 |-----------|----------|
-| `exit 0` | Claude continues |
-| `exit 2` | Blocks Claude (`continue: false`) |
+| `exit 0` | Task creation proceeds (unless `decision: "block"` is set) |
+| `exit 2` | Blocks task creation |

data/docs/API/USER_PROMPT_SUBMIT.md

@@ -12,6 +12,13 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `prompt` | Get the user's prompt text |
 | `user_prompt` | Alias for `prompt` |
 | `current_prompt` | Alias for `prompt` |
+| `session_title` | The session's custom title, when one is set (same meaning as SessionStart's `session_title`) |
+
+> [!NOTE]
+> `UserPromptSubmit` also fires on turns Claude Code starts on its own — a scheduled task or `/loop` iteration, a background subagent reporting back, or a message another session sends — so `prompt` isn't always text the user typed.
+
+> [!NOTE]
+> Pasted content that collapsed to a `[Pasted text #N]` placeholder arrives expanded in `prompt`. When Claude Code marks pasted text for Claude, it sits between `<pasted_content id="…">` and `</pasted_content id="…">` lines — account for them if you parse the prompt.
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
@@ -25,6 +32,11 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `empty_additional_context!` | Remove additional context |
 | `block_prompt!(reason)` | Block the prompt from processing |
 | `unblock_prompt!` | Unblock a previously blocked prompt |
+| `session_title!(title)` | Set the session title (e.g. name sessions from the prompt content) |
+| `suppress_original_prompt!(value = true)` | When the prompt is blocked (`block_prompt!` or exit 2), leave the prompt text out of the block message |
+
+> [!WARNING]
+> By default the block message ends with `Original prompt:` and the submitted text, and is written to the session transcript on disk. `suppress_original_prompt!` removes it from that message only — the text can still appear in other local files such as prompt history, so a blocking hook isn't a way to keep a secret off disk.
 
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
@@ -37,6 +49,8 @@ Output helpers provide access to the hook's output data and helper methods for w
 | `output.reason` | Get the reason for the decision |
 | `output.blocked?` | Check if the prompt has been blocked (decision == 'block') |
 | `output.additional_context` | Get the additional context that was added |
+| `output.session_title` | Get the session title that was set (if any) |
+| `output.suppress_original_prompt?` | Whether the prompt text is left out of the block message |
 
 ## Hook Exit Codes