claude_hooks 1.0.2 → 1.2.0

data/docs/API/PERMISSION_REQUEST.md

@@ -0,0 +1,199 @@
+# PermissionRequest API
+
+Available when inheriting from `ClaudeHooks::PermissionRequest`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `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 |
+
+## 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 |
+|--------|-------------|
+| `allow_permission!(reason = '')` | Allow the permission request with optional reason |
+| `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.
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `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'` (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
+
+PermissionRequest hooks use the JSON API with exit code 0 for all permission decisions.
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `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 |
+
+## Example: Basic Permission Guard
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class PermissionGuard < ClaudeHooks::PermissionRequest
+  SENSITIVE_TOOLS = %w[rm git-push curl wget].freeze
+  SAFE_TOOLS = %w[ls cat grep find].freeze
+
+  def call
+    log "Permission requested for: #{tool_name}"
+    log "Tool use ID: #{tool_use_id}"
+    log "Permission mode: #{permission_mode}"
+
+    # Auto-allow safe tools
+    if SAFE_TOOLS.include?(tool_name)
+      allow_permission!("Safe tool, automatically allowed")
+      return output
+    end
+
+    # Block dangerous tools
+    if SENSITIVE_TOOLS.include?(tool_name)
+      deny_permission!("Dangerous tool #{tool_name} requires manual approval")
+      return output
+    end
+
+    # Default: allow with logging
+    allow_permission!("Tool allowed by default")
+    output
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  input_data = JSON.parse(STDIN.read)
+  hook = PermissionGuard.new(input_data)
+  hook.call
+  hook.output_and_exit
+end
+```
+
+## Example: Permission Mode-Aware Guard
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class SmartPermissionGuard < ClaudeHooks::PermissionRequest
+  DANGEROUS_TOOLS = %w[rm git-reset curl wget].freeze
+
+  def call
+    log "Permission mode: #{permission_mode}"
+
+    # Block dangerous tools in bypass mode
+    if permission_mode == 'bypassPermissions' && dangerous_tool?
+      log "Blocking dangerous tool in bypass mode", level: :warn
+      deny_permission!("Cannot bypass permissions for dangerous tool: #{tool_name}")
+      return output
+    end
+
+    # Allow in 'dontAsk' mode if tool is not dangerous
+    if permission_mode == 'dontAsk' && !dangerous_tool?
+      allow_permission!("Auto-allowed in dontAsk mode")
+      return output
+    end
+
+    # Default behavior
+    allow_permission!("Permission granted")
+    output
+  end
+
+  private
+
+  def dangerous_tool?
+    DANGEROUS_TOOLS.include?(tool_name)
+  end
+end
+```
+
+## Example: Input Modification
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class InputSanitizer < ClaudeHooks::PermissionRequest
+  def call
+    case tool_name
+    when 'Bash'
+      # Add safety flags to bash commands
+      if tool_input['command']&.include?('rm')
+        sanitized_input = tool_input.merge(
+          'command' => tool_input['command'] + ' --interactive'
+        )
+        update_input_and_allow!(sanitized_input, "Added --interactive flag for safety")
+      else
+        allow_permission!("Bash command is safe")
+      end
+    when 'Write'
+      # Validate file paths before writing
+      if tool_input['file_path']&.start_with?('/tmp')
+        deny_permission!("Cannot write to /tmp directory")
+      else
+        allow_permission!("File write is safe")
+      end
+    else
+      allow_permission!("No special handling needed")
+    end
+
+    output
+  end
+end
+```
+
+## Multiple Hooks Merging
+
+When multiple PermissionRequest hooks are executed, their outputs merge with these rules:
+
+- **Decision**: `deny` > `allow` (most restrictive wins)
+- **Reasons**: All `decision.message` values are concatenated with `'; '`
+- **Updated Input**: Last `decision.updatedInput` wins (most recent transformation)
+
+```ruby
+# Hook 1
+hook1.deny_permission!("Reason 1")
+
+# Hook 2
+hook2.allow_permission!("Reason 2")
+
+# Merged result
+merged = ClaudeHooks::Output::PermissionRequest.merge(
+  hook1.output,
+  hook2.output
+)
+
+merged.denied? # => true (deny wins)
+merged.permission_reason # => "Reason 1; Reason 2"
+```
+
+## Notes
+
+- PermissionRequest runs when Claude Code shows a permission dialog
+- 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`, `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.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 that was used |
 | `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..."`) |
 
 ## 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/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

@@ -11,6 +11,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..."`) |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
@@ -22,6 +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.
@@ -33,9 +38,12 @@ 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.permission_decision` | Get the permission decision: 'allow', 'deny', or 'ask' |
+| `output.input_updated?` | Check if tool input has been updated |
+| `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) |
 
 ## Hook Exit Codes
 

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`) |

data/docs/API/USER_PROMPT_EXPANSION.md

@@ -0,0 +1,43 @@
+# UserPromptExpansion API
+
+Available when inheriting from `ClaudeHooks::UserPromptExpansion`:
+
+Runs when a slash command or other prompt-expansion mechanism is triggered. Can block the expansion.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `expansion_type` | Type of expansion (e.g. `'slash_command'`) |
+| `command_name` | The command name (without the `/`) |
+| `command_args` | The arguments passed to the command |
+| `command_source` | Where the command was defined (`'user'`, `'project'`, etc.) |
+| `prompt` | The expanded prompt text |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `block!(reason)` | Block the expansion with a reason |
+| `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 expansion was blocked |
+| `output.decision` | Get the decision (`'block'` or nil) |
+| `output.reason` | Get the block reason |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Expansion proceeds |
+| `exit 2` | Blocks the expansion; `STDERR` shown to Claude |

data/docs/API/WORKTREE_CREATE.md

@@ -0,0 +1,39 @@
+# WorktreeCreate API
+
+Available when inheriting from `ClaudeHooks::WorktreeCreate`:
+
+Runs when Claude Code is about to create a git worktree. **Special contract**: the hook must print the worktree path as the last non-empty line of stdout and exit 0. An empty or missing path is treated as failure.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `name` | The slug/name for the worktree (e.g. `'feature-x'`) |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `worktree_path!(path)` | Set the path where the worktree will be created |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.worktree_path` | Get the configured worktree path |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` (with path on stdout) | Worktree created at the printed path |
+| `exit 1` / empty stdout | Creation fails |
+
+> [!IMPORTANT]
+> `output_and_exit` for WorktreeCreate prints the **bare path** (not JSON). Do not emit JSON for this hook type.