claude_hooks 1.0.2 → 1.2.0

data/docs/1.1.0_UPGRADE_GUIDE.md

@@ -0,0 +1,269 @@
+# Upgrading to v1.1.0
+
+Version 1.1.0 adds new features to align with Anthropic's updated Claude Code Hooks documentation. **All changes are backward compatible** - existing hooks continue to work without modification.
+
+## What's New
+
+### 1. New PermissionRequest Hook
+
+Handle permission request events from Claude Code:
+
+```ruby
+class PermissionGuard < ClaudeHooks::PermissionRequest
+  def call
+    if dangerous_tool?
+      deny_permission!("Requires manual approval")
+    else
+      allow_permission!("Safe to proceed")
+    end
+    output
+  end
+
+  private
+
+  def dangerous_tool?
+    %w[rm git-reset curl].include?(tool_name)
+  end
+end
+```
+
+**When to use**: Create permission guards that automatically approve/deny permission requests based on custom logic.
+
+### 2. New Fields Available
+
+All hooks now receive these additional fields:
+
+- **`permission_mode`** (all hooks): Access via `permission_mode` method
+  - Values: `'default'`, `'plan'`, `'acceptEdits'`, `'dontAsk'`, `'bypassPermissions'`
+  - Defaults to `'default'`
+
+- **`tool_use_id`** (PreToolUse, PostToolUse, PermissionRequest): Access via `tool_use_id` method
+  - Unique identifier for each tool use (e.g., `"toolu_01ABC123..."`)
+
+- **`notification_type`** (Notification): Access via `notification_type` method
+  - Values: `'permission_prompt'`, `'idle_prompt'`, `'auth_success'`, `'elicitation_dialog'`
+
+**Example usage:**
+
+```ruby
+class MyHook < ClaudeHooks::PreToolUse
+  def call
+    log "Permission mode: #{permission_mode}"
+    log "Tool use ID: #{tool_use_id}"
+
+    # Adjust behavior based on permission mode
+    if permission_mode == 'bypassPermissions'
+      # More restrictive checks
+      deny_permission!("Cannot bypass for sensitive operations")
+    else
+      approve_tool!("Approved")
+    end
+
+    output
+  end
+end
+```
+
+### 3. Update Tool Input (PreToolUse)
+
+Modify tool input before execution:
+
+```ruby
+class InputModifier < ClaudeHooks::PreToolUse
+  def call
+    case tool_name
+    when 'Bash'
+      # Add safety flags to bash commands
+      if tool_input['command']&.include?('rm')
+        sanitized = tool_input.merge('command' => "#{tool_input['command']} --interactive")
+        update_tool_input!(sanitized)
+      else
+        approve_tool!("Safe command")
+      end
+    when 'Write'
+      # Validate file paths
+      if tool_input['file_path']&.start_with?('/etc')
+        deny_permission!("Cannot write to /etc")
+      else
+        approve_tool!("Safe write")
+      end
+    else
+      approve_tool!("No special handling")
+    end
+
+    output
+  end
+end
+```
+
+**Output helpers:**
+- `output.input_updated?` - Check if input was modified
+- `output.updated_input` - Get the updated input hash
+
+## Do I Need to Change My Existing Hooks?
+
+**No!** All changes are backward compatible:
+
+- New fields have sensible defaults (return `nil` or `'default'`)
+- Existing methods continue to work exactly as before
+- No breaking changes to any APIs
+- Your existing hooks will work with v1.1.0 without any modifications
+
+## Should I Update My Hooks?
+
+Consider updating if:
+
+- ✅ You want to handle PermissionRequest events
+- ✅ You need to check the current permission mode
+- ✅ You want to modify tool inputs dynamically
+- ✅ You need to differentiate notification types
+- ✅ You want to track specific tool use instances via IDs
+
+## New Hook Type Summary
+
+| Hook Type | When It Runs | Key Methods |
+|-----------|--------------|-------------|
+| **PermissionRequest** | When Claude requests permission | `allow_permission!`, `deny_permission!`, `update_input_and_allow!` |
+
+## New Fields Summary
+
+| Field | Available In | Purpose |
+|-------|--------------|---------|
+| `permission_mode` | All hooks | Know the current permission mode |
+| `tool_use_id` | PreToolUse, PermissionRequest, PostToolUse | Track specific tool use instances |
+| `notification_type` | Notification | Filter notifications by type |
+
+## New PreToolUse Features
+
+| Feature | Method | Description |
+|---------|--------|-------------|
+| Update input | `update_tool_input!(hash)` | Modify tool input and auto-approve |
+| Check if updated | `output.input_updated?` | Boolean check for modification |
+| Get updated input | `output.updated_input` | Retrieve the modified input |
+
+## Testing
+
+All existing tests should pass without modification. Run:
+
+```bash
+bundle exec rake test
+# or
+ruby test/run_all_tests.rb
+```
+
+## Migration Examples
+
+### Example 1: Using permission_mode
+
+**Before (v1.0.x):**
+```ruby
+class GitGuard < ClaudeHooks::PreToolUse
+  def call
+    if tool_name == 'Bash' && tool_input['command']&.include?('git push')
+      ask_for_permission!("Git push requires confirmation")
+    else
+      approve_tool!("Approved")
+    end
+    output
+  end
+end
+```
+
+**After (v1.1.0 - enhanced):**
+```ruby
+class GitGuard < ClaudeHooks::PreToolUse
+  def call
+    if tool_name == 'Bash' && tool_input['command']&.include?('git push')
+      # Skip asking in dontAsk mode, but still log
+      if permission_mode == 'dontAsk'
+        log "Auto-approving git push in dontAsk mode", level: :warn
+        approve_tool!("Auto-approved due to permission mode")
+      else
+        ask_for_permission!("Git push requires confirmation")
+      end
+    else
+      approve_tool!("Approved")
+    end
+    output
+  end
+end
+```
+
+### Example 2: Using PermissionRequest
+
+**Before (v1.0.x):**
+```ruby
+# Permission requests couldn't be handled automatically
+```
+
+**After (v1.1.0 - new capability):**
+```ruby
+class AutoPermissionGuard < ClaudeHooks::PermissionRequest
+  SAFE_TOOLS = %w[ls cat grep find read].freeze
+
+  def call
+    if SAFE_TOOLS.include?(tool_name)
+      allow_permission!("Safe tool, auto-approved")
+    else
+      # Let user decide
+      deny_permission!("Requires manual approval")
+    end
+    output
+  end
+end
+```
+
+### Example 3: Updating tool input
+
+**Before (v1.0.x):**
+```ruby
+class BashSanitizer < ClaudeHooks::PreToolUse
+  def call
+    # Could only approve or deny, not modify
+    if tool_input['command']&.include?('rm')
+      block_tool!("Dangerous command blocked")
+    else
+      approve_tool!("Safe")
+    end
+    output
+  end
+end
+```
+
+**After (v1.1.0 - new capability):**
+```ruby
+class BashSanitizer < ClaudeHooks::PreToolUse
+  def call
+    if tool_input['command']&.include?('rm')
+      # Add safety flags instead of blocking
+      safe_command = "#{tool_input['command']} --interactive --verbose"
+      update_tool_input!({'command' => safe_command})
+      log "Added safety flags to rm command"
+    else
+      approve_tool!("Safe")
+    end
+    output
+  end
+end
+```
+
+## Questions?
+
+- See the [full CHANGELOG](../CHANGELOG.md) for all changes
+- Check the [API documentation](API/) for detailed method references
+- Review the [PermissionRequest API](API/PERMISSION_REQUEST.md) for the new hook type
+- Look at [example implementations](../example_dotclaude/) for patterns
+
+## Rollback
+
+If you need to rollback to v1.0.2:
+
+```bash
+gem uninstall claude_hooks
+gem install claude_hooks -v 1.0.2
+```
+
+Or in your Gemfile:
+```ruby
+gem 'claude_hooks', '~> 1.0.2'
+```

data/docs/API/COMMON.md

@@ -12,6 +12,11 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `transcript_path` | Get path to the transcript file |
 | `cwd` | Get current working directory |
 | `hook_event_name` | Get the hook event name |
+| `permission_mode` | Get the permission mode: `'default'`, `'plan'`, `'acceptEdits'`, `'auto'`, `'dontAsk'`, `'bypassPermissions'` (defaults to `'default'`) |
+| `prompt_id` | Get the current prompt ID |
+| `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`) |
 | `read_transcript` | Read the transcript file |
 | `transcript` | Alias for `read_transcript` |
 
@@ -27,6 +32,7 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `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 |
+| `terminal_sequence!(seq)` | Emit an ANSI/terminal escape sequence in the output |
 
 ## Output Helpers
 
@@ -44,6 +50,7 @@ This object provides helpers to access output data, for merging multiple outputs
 | `output.suppress_output?` | Check if output should be suppressed from transcript |
 | `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) |
 
 ### Output data merging
 For each hook type, the `output` object provides a **class method** `merge` that will try to intelligently merge multiple hook results, e.g. `ClaudeHooks::Output::UserPromptSubmit.merge(output1, output2, output3)`.

data/docs/API/CONFIG_CHANGE.md

@@ -0,0 +1,39 @@
+# ConfigChange API
+
+Available when inheriting from `ClaudeHooks::ConfigChange`:
+
+Runs when Claude Code configuration changes. Can block the change for most sources (note: `policy_settings` changes cannot be blocked).
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `source` | The source of the config change (e.g. `'project'`, `'user'`, `'policy_settings'`) |
+| `file_path` | Path to the changed config file (optional) |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `block!(reason)` | Block the config change (ineffective for `policy_settings`) |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.blocked?` | Check if the change was blocked |
+| `output.decision` | Get the decision (`'block'` or nil) |
+| `output.reason` | Get the block reason |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Config change proceeds |
+| `exit 2` | Blocks the change; `STDERR` shown to Claude |

data/docs/API/CWD_CHANGED.md

@@ -0,0 +1,34 @@
+# CwdChanged API
+
+Available when inheriting from `ClaudeHooks::CwdChanged`:
+
+Runs when the working directory changes. Can update the list of watched paths.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `old_cwd` | The previous working directory |
+| `new_cwd` | The new working directory |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `watch_paths!(paths)` | Set the list of paths Claude Code should watch for changes |
+
+## 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/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/NOTIFICATION.md

@@ -11,6 +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'` |
 
 ## Hook State Helpers
 Notifications are outside facing and do not have any specific state to modify.

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