claude_hooks 1.1.0 → 1.2.0

data/docs/API/ELICITATION.md

@@ -0,0 +1,44 @@
+# Elicitation API
+
+Available when inheriting from `ClaudeHooks::Elicitation`:
+
+Runs when an MCP server requests user input (an elicitation dialog). Can accept, decline, or cancel the request.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `mcp_server_name` | The MCP server requesting input |
+| `message` | The message / prompt shown to the user |
+| `mode` | Optional interaction mode |
+| `url` | Optional URL associated with the request |
+| `elicitation_id` | Optional unique ID for this elicitation |
+| `requested_schema` | Optional JSON schema describing the expected response |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `accept!(content = {})` | Accept the elicitation with optional content hash |
+| `decline!` | Decline the elicitation |
+| `cancel!` | Cancel the elicitation |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.action` | Get the chosen action: `'accept'`, `'decline'`, or `'cancel'` |
+| `output.content` | Get the accepted content hash |
+| `output.accepted?` | Check if the elicitation was accepted |
+| `output.declined?` | Check if the elicitation was declined |
+| `output.cancelled?` | Check if the elicitation was cancelled |
+
+## Hook Exit Codes
+
+Uses the JSON API (exit 0 / stdout). The `hookSpecificOutput.action` field controls the response.

data/docs/API/ELICITATION_RESULT.md

@@ -0,0 +1,43 @@
+# ElicitationResult API
+
+Available when inheriting from `ClaudeHooks::ElicitationResult`:
+
+Runs after a user has responded to an elicitation dialog. Can override the action or content before it is sent back to the MCP server.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `mcp_server_name` | The MCP server that requested input |
+| `action` | The user's chosen action: `'accept'`, `'decline'`, or `'cancel'` |
+| `mode` | Optional interaction mode |
+| `elicitation_id` | Optional unique ID for this elicitation |
+| `content` | The content the user provided (for `'accept'` action) |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `accept!(content = {})` | Override the response with an accept + content |
+| `decline!` | Override the response to decline |
+| `cancel!` | Override the response to cancel |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.action` | Get the (possibly overridden) action |
+| `output.content` | Get the (possibly overridden) content |
+| `output.accepted?` | Check if the action is `'accept'` |
+| `output.declined?` | Check if the action is `'decline'` |
+| `output.cancelled?` | Check if the action is `'cancel'` |
+
+## Hook Exit Codes
+
+Uses the JSON API (exit 0 / stdout).

data/docs/API/FILE_CHANGED.md

@@ -0,0 +1,37 @@
+# FileChanged API
+
+Available when inheriting from `ClaudeHooks::FileChanged`:
+
+Runs when a watched file is created, modified, or deleted. Can update the watch paths list.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `file_path` | The path of the changed file |
+| `event` | The type of change: `'change'`, `'add'`, or `'unlink'` |
+| `modified?` | Convenience: `event == 'change'` |
+| `created?` | Convenience: `event == 'add'` |
+| `deleted?` | Convenience: `event == 'unlink'` |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `watch_paths!(paths)` | Update the list of paths Claude Code should watch |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.watch_paths` | Get the configured watch paths |
+
+## Hook Exit Codes
+
+Non-blocking. Only `watchPaths` output is consumed.

data/docs/API/INSTRUCTIONS_LOADED.md

@@ -0,0 +1,30 @@
+# InstructionsLoaded API
+
+Available when inheriting from `ClaudeHooks::InstructionsLoaded`:
+
+Runs when a `CLAUDE.md` instructions file is loaded. Non-blocking — exit code is ignored.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `file_path` | Path to the loaded instructions file |
+| `load_reason` | Why the file was loaded (e.g. `'startup'`, `'cwd_change'`) |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+No event-specific state methods — this hook is non-blocking.
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+No event-specific output helpers.
+
+## Hook Exit Codes
+
+Non-blocking. Exit code is ignored by Claude Code.

data/docs/API/MESSAGE_DISPLAY.md

@@ -0,0 +1,38 @@
+# MessageDisplay API
+
+Available when inheriting from `ClaudeHooks::MessageDisplay`:
+
+Runs when a message is about to be displayed. Can override the displayed text via `hookSpecificOutput.displayContent`.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `turn_id` | ID of the current turn |
+| `message_id` | ID of this message |
+| `index` | Position of this message in the turn |
+| `final` | Whether this is the final message chunk (`true`/`false`) |
+| `delta` | The incremental text content of this message |
+| `message_text` | Alias for `delta` |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `display_content!(text)` | Override the displayed text for this message |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.display_content` | Get the overridden display content (if set) |
+
+## Hook Exit Codes
+
+Exit code and output stream are ignored for MessageDisplay. The only honored output is `hookSpecificOutput.displayContent`.

data/docs/API/PERMISSION_DENIED.md

@@ -0,0 +1,37 @@
+# PermissionDenied API
+
+Available when inheriting from `ClaudeHooks::PermissionDenied`:
+
+Runs when a permission request is denied. Can request that Claude Code retries the request.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `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 |
+| `reason` | The reason the permission was denied |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `retry!` | Request that Claude Code retry the permission request |
+| `no_retry!` | Explicitly decline to retry (default) |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.retry?` | Check if a retry was requested |
+
+## Hook Exit Codes
+
+Exit code is ignored. Output is via `hookSpecificOutput.retry` (JSON API, exit 0 / stdout).

data/docs/API/PERMISSION_REQUEST.md

@@ -21,8 +21,8 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | Method | Description |
 |--------|-------------|
 | `allow_permission!(reason = '')` | Allow the permission request with optional reason |
-| `deny_permission!(reason = '')` | Deny the permission request with reason |
-| `update_input_and_allow!(updated_input, reason = '')` | Update tool input and allow (convenience method) |
+| `deny_permission!(reason = '', interrupt: nil)` | Deny the permission request with reason; pass `interrupt: true` to interrupt the current operation |
+| `update_input_and_allow!(updated_input, reason = '', updated_permissions: nil)` | Update tool input and allow |
 
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
@@ -34,9 +34,12 @@ Output helpers provide access to the hook's output data and helper methods for w
 | `output.allowed?` | Check if permission has been allowed |
 | `output.denied?` | Check if permission has been denied |
 | `output.input_updated?` | Check if tool input has been updated |
-| `output.permission_decision` | Get the permission decision: 'allow' or 'deny' |
-| `output.permission_reason` | Get the reason for the permission decision |
-| `output.updated_input` | Get the updated input (if provided) |
+| `output.permission_decision` | Get the permission decision: `'allow'` or `'deny'` (reads nested `decision.behavior`; falls back to legacy flat key) |
+| `output.permission_reason` | Get the decision message (reads nested `decision.message`; falls back to legacy `permissionDecisionReason`) |
+| `output.updated_input` | Get the updated input (reads nested `decision.updatedInput`; falls back to legacy flat key) |
+| `output.behavior` | Get the raw `decision.behavior` value |
+| `output.updated_permissions` | Get the `decision.updatedPermissions` array (if provided) |
+| `output.interrupt?` | Check if `decision.interrupt` was set to true |
 
 ## Hook Exit Codes
 
@@ -167,8 +170,8 @@ end
 When multiple PermissionRequest hooks are executed, their outputs merge with these rules:
 
 - **Decision**: `deny` > `allow` (most restrictive wins)
-- **Reasons**: All reasons are concatenated with `'; '`
-- **Updated Input**: Last updated input wins (most recent transformation)
+- **Reasons**: All `decision.message` values are concatenated with `'; '`
+- **Updated Input**: Last `decision.updatedInput` wins (most recent transformation)
 
 ```ruby
 # Hook 1
@@ -193,4 +196,4 @@ merged.permission_reason # => "Reason 1; Reason 2"
 - It can automatically allow or deny on behalf of the user
 - Uses the same JSON API pattern as PreToolUse hooks
 - Supports modifying tool inputs before execution
-- Works with all permission modes: `default`, `plan`, `acceptEdits`, `dontAsk`, `bypassPermissions`
+- Works with all permission modes: `default`, `plan`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`

data/docs/API/POST_COMPACT.md

@@ -0,0 +1,30 @@
+# PostCompact API
+
+Available when inheriting from `ClaudeHooks::PostCompact`:
+
+Runs after transcript compaction completes. Non-blocking — use for logging or post-compaction side effects.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `trigger` | What triggered the compaction: `'auto'` or `'manual'` |
+| `compact_summary` | The summary produced by the compaction |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+No event-specific state methods — this hook is non-blocking.
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+No event-specific output helpers.
+
+## Hook Exit Codes
+
+Non-blocking. Exit code is ignored.

data/docs/API/POST_TOOL_BATCH.md

@@ -0,0 +1,39 @@
+# PostToolBatch API
+
+Available when inheriting from `ClaudeHooks::PostToolBatch`:
+
+Runs after a full batch of tool calls completes. Can block Claude from continuing.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `tool_calls` | Array of tool call results; each entry has `tool_name`, `tool_input`, `tool_use_id`, `tool_response` |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `block!(reason)` | Block Claude from continuing after this batch |
+| `add_additional_context!(context)` | Add additional context visible to Claude |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.blocked?` | Check if the batch was blocked |
+| `output.decision` | Get the decision (`'block'` or nil) |
+| `output.reason` | Get the block reason |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Claude continues |
+| `exit 2` | Blocks Claude; `STDERR` shown to Claude |

data/docs/API/POST_TOOL_USE_FAILURE.md

@@ -0,0 +1,31 @@
+# PostToolUseFailure API
+
+Available when inheriting from `ClaudeHooks::PostToolUseFailure`:
+
+Runs when a tool call fails. Non-blocking — output and exit code are ignored except for `additionalContext`.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `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 |
+| `error` | The error message |
+| `is_interrupt` | Whether the failure was caused by an interrupt (`true`/`false`) |
+| `interrupt?` | Alias for `is_interrupt` |
+| `duration_ms` | How long the tool ran before failing (milliseconds) |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `add_additional_context!(context)` | Add additional context visible to Claude about the failure |
+
+## Hook Exit Codes
+
+Non-blocking. Exit code and output are ignored by Claude Code; only `additionalContext` is consumed.

data/docs/API/PRE_COMPACT.md

@@ -13,10 +13,13 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `custom_instructions` | Get custom instructions (only available for manual trigger) |
 
 ## Hook State Helpers
-No specific hook state methods are available to alter compaction behavior.
 
 [📚 Shared hook state methods](COMMON.md#hook-state-methods)
 
+| Method | Description |
+|--------|-------------|
+| `block!(reason)` | Block the compaction with a reason (top-level `decision: 'block'`) |
+
 ## Utility Methods
 Utility methods for transcript management.
 
@@ -26,10 +29,15 @@ Utility methods for transcript management.
 
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
-PreCompact hooks don't have any specific hook state and thus doesn't have any specific output helpers.
 
 [📚 Shared output helpers](COMMON.md#output-helpers)
 
+| Method | Description |
+|--------|-------------|
+| `output.blocked?` | Check if the compaction was blocked |
+| `output.decision` | Get the decision (`'block'` or nil) |
+| `output.reason` | Get the block reason |
+
 ## Hook Exit Codes
 
 | Exit Code | Behavior |

data/docs/API/PRE_TOOL_USE.md

@@ -23,7 +23,10 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `approve_tool!(reason)` | Explicitly approve tool usage |
 | `block_tool!(reason)` | Block tool usage with feedback |
 | `ask_for_permission!(reason)` | Request user permission |
+| `defer_permission!` | Defer the permission decision to a later hook in the chain |
 | `update_tool_input!(updated_input)` | Update the tool input and automatically approve the tool (sets `permissionDecision` to `'allow'`) |
+| `update_input!(updated_input)` | Update `updatedInput` without changing the permission decision |
+| `add_additional_context!(context)` | Add additional context visible to Claude |
 
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
@@ -35,9 +38,10 @@ Output helpers provide access to the hook's output data and helper methods for w
 | `output.allowed?` | Check if the tool has been explicitly allowed (permission_decision == 'allow') |
 | `output.denied?` | Check if the tool has been denied (permission_decision == 'deny') |
 | `output.blocked?` | Alias for `denied?` |
+| `output.deferred?` | Check if the permission decision was deferred (permission_decision == 'defer') |
 | `output.should_ask_permission?` | Check if user permission is required (permission_decision == 'ask') |
 | `output.input_updated?` | Check if tool input has been updated |
-| `output.permission_decision` | Get the permission decision: 'allow', 'deny', or 'ask' |
+| `output.permission_decision` | Get the permission decision: `'allow'`, `'deny'`, `'ask'`, or `'defer'` |
 | `output.permission_reason` | Get the reason for the permission decision |
 | `output.updated_input` | Get the updated input (if provided) |
 

data/docs/API/SETUP.md

@@ -0,0 +1,37 @@
+# Setup API
+
+Available when inheriting from `ClaudeHooks::Setup`:
+
+Runs once during Claude Code startup (before any session begins). Use it to inject global context or perform one-time initialization.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `source` | Startup reason: `'init'` (first launch) or `'maintenance'` |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `add_additional_context!(context)` | Add contextual information for Claude |
+| `add_context!(context)` | Alias for `add_additional_context!` |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.additional_context` | Get the additional context that was added |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Continues normally; `STDOUT` added as context |
+| `exit 2` | N/A — non-blocking event |

data/docs/API/STOP_FAILURE.md

@@ -0,0 +1,19 @@
+# StopFailure API
+
+Available when inheriting from `ClaudeHooks::StopFailure`:
+
+Runs when the stop phase itself errors. Purely a logging event — output and exit code are completely ignored by Claude Code.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `error` | The error message |
+| `error_details` | Additional error detail (stack trace, etc.) |
+| `last_assistant_message` | The last message Claude produced before the failure |
+
+## Hook Exit Codes
+
+Exit code and all output are ignored. Use this hook only for logging or alerting.

data/docs/API/SUBAGENT_START.md

@@ -0,0 +1,40 @@
+# SubagentStart API
+
+Available when inheriting from `ClaudeHooks::SubagentStart`:
+
+Runs when a subagent task starts. Use it to inject context specific to the subagent or log the start.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+The `agent_id` and `agent_type` common fields are populated for this event.
+
+| Method | Description |
+|--------|-------------|
+| `agent_id` | The subagent's unique ID |
+| `agent_type` | The subagent's type |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `add_additional_context!(context)` | Add contextual information for the subagent |
+| `add_context!(context)` | Alias for `add_additional_context!` |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.additional_context` | Get the additional context that was added |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Continues normally; `STDOUT` added as context |
+| `exit 2` | N/A — non-blocking event |

data/docs/API/TASK_COMPLETED.md

@@ -0,0 +1,43 @@
+# TaskCompleted API
+
+Available when inheriting from `ClaudeHooks::TaskCompleted`:
+
+Runs when a teammate task completes. Can block Claude from continuing via `prevent_continue!` or exit 2.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `task_id` | The unique task ID |
+| `task_subject` | Short title of the task |
+| `task_description` | Optional longer description |
+| `teammate_name` | The teammate who completed the task |
+| `team_name` | The team name |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `prevent_continue!(reason)` | Block Claude from continuing (`continue: false` + `stopReason`) |
+
+There is no top-level `decision` field for this event — block via `prevent_continue!` or exit 2.
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.continue?` | Whether Claude will continue |
+| `output.stop_reason` | The reason Claude was stopped |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Claude continues |
+| `exit 2` | Blocks Claude (`continue: false`) |

data/docs/API/TASK_CREATED.md

@@ -0,0 +1,43 @@
+# TaskCreated API
+
+Available when inheriting from `ClaudeHooks::TaskCreated`:
+
+Runs when a teammate task is created. Can block Claude from continuing via `prevent_continue!` or exit 2.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `task_id` | The unique task ID |
+| `task_subject` | Short title of the task |
+| `task_description` | Optional longer description |
+| `teammate_name` | The teammate assigned to the task |
+| `team_name` | The team name |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `prevent_continue!(reason)` | Block Claude from continuing (`continue: false` + `stopReason`) |
+
+There is no top-level `decision` field for this event — block via `prevent_continue!` or exit 2.
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.continue?` | Whether Claude will continue |
+| `output.stop_reason` | The reason Claude was stopped |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Claude continues |
+| `exit 2` | Blocks Claude (`continue: false`) |

data/docs/API/TEAMMATE_IDLE.md

@@ -0,0 +1,40 @@
+# TeammateIdle API
+
+Available when inheriting from `ClaudeHooks::TeammateIdle`:
+
+Runs when a teammate goes idle. Can block Claude from continuing via `prevent_continue!` or exit 2.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `teammate_name` | The name of the idle teammate |
+| `team_name` | The team name |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `prevent_continue!(reason)` | Block Claude from continuing (`continue: false` + `stopReason`) |
+
+There is no top-level `decision` field for this event — block via `prevent_continue!` or exit 2.
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.continue?` | Whether Claude will continue |
+| `output.stop_reason` | The reason Claude was stopped |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Claude continues |
+| `exit 2` | Blocks Claude (`continue: false`) |