claude_hooks 1.0.0 → 1.1.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,7 @@ 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'`, `'dontAsk'`, `'bypassPermissions'` (defaults to `'default'`) |
 | `read_transcript` | Read the transcript file |
 | `transcript` | Alias for `read_transcript` |
 

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_REQUEST.md

@@ -0,0 +1,196 @@
+# 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 = '')` | Deny the permission request with reason |
+| `update_input_and_allow!(updated_input, reason = '')` | Update tool input and allow (convenience method) |
+
+## 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' |
+| `output.permission_reason` | Get the reason for the permission decision |
+| `output.updated_input` | Get the updated input (if provided) |
+
+## 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 reasons are concatenated with `'; '`
+- **Updated Input**: Last updated input 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`, `dontAsk`, `bypassPermissions`

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/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,7 @@ 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 |
+| `update_tool_input!(updated_input)` | Update the tool input and automatically approve the tool (sets `permissionDecision` to `'allow'`) |
 
 ## Output Helpers
 Output helpers provide access to the hook's output data and helper methods for working with the output state.
@@ -34,8 +36,10 @@ Output helpers provide access to the hook's output data and helper methods for w
 | `output.denied?` | Check if the tool has been denied (permission_decision == 'deny') |
 | `output.blocked?` | Alias for `denied?` |
 | `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_reason` | Get the reason for the permission decision |
+| `output.updated_input` | Get the updated input (if provided) |
 
 ## Hook Exit Codes
 

data/docs/API/SESSION_START.md

@@ -9,7 +9,7 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 
 | Method | Description |
 |--------|-------------|
-| `source` | Get the session start source: `'startup'`, `'resume'`, or `'clear'` |
+| `source` | Get the session start source: `'startup'`, `'resume'`, `'clear'`, or `'compact'` |
 
 ## 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/WHY.md

@@ -3,6 +3,7 @@
 When creating fairly complex hook systems for Claude Code it is easy to end up either with:
 - Fairly monolithic scripts that becomes hard to maintain and have to handle complex merging logic for the output.
 - A lot of scripts set up in the `settings.json` that all use the same hook input / output logic that needs to be rewritten multiple times.
+- Having to understand the very chaotic exit code and output steam logic of Claude Code and how to handle it.
 
 Furthermore, Claude's documentation on hooks is a bit hard to navigate and setting up hooks is not necessarily intuitive or straightforward having to play around with STDIN, STDOUT, STDERR, exit codes, etc.
 
@@ -25,9 +26,9 @@ settings.json
 
 ## For both approaches it will bring
 
-1. Normalized Input/Output handling - input parsing, validation, straightforward output helpers (block_tool!, add_context!).
+1. Normalized Input/Output handling - input parsing, validation, straightforward output helpers (`ask_for_permission!`, `approve_tool!`, `block_tool!`, `block_prompt!`, `add_context!`).
 
-2. Hook-Specific APIs - 8 different hook types with tailored methods (e.g., ask_for_permission! vs block_tool!) and smart merge logic for combining outputs.
+2. Hook-Specific APIs - all 9 hook types with tailored methods and output objects (with `output_and_exit`) and smart merge logic for combining outputs.
 
 3. Session-Based Logging - Dedicated logger to understand the flow of what happens in Claude Code and write it out to a `session-{session_id}.log` file.
 
@@ -35,7 +36,6 @@ settings.json
 
 5. Testing Support - Standalone execution mode for individual hook testing and CLI testing with sample JSON input.
 
-
 ## For a monolithic approach it will additionally bring
 
 1. Composable Hook Handlers
@@ -43,11 +43,19 @@ For instance, `entrypoints/user_prompt_submit.rb` orchestrates multiple handlers
 ```ruby
 # Add contextual rules
 append_rules_result = AppendRules.new(input_data).call
+append_rules_result.call
+
 # Audit logging
 log_result = LogUserPrompt.new(input_data).call
-
-# Merge outputs to Claude Code
-puts ClaudeHooks::UserPromptSubmit.merge_outputs(append_rules_result, log_result)
+log_result.call
+
+  # Merge outputs and yield back to Claude Code
+  merged = ClaudeHooks::Output::UserPromptSubmit.merge(
+    append_rules.output,
+    log_handler.output
+  )
+  merged.output_and_exit
+end
 ```
 
 2. Intelligent Output Merging
@@ -59,7 +67,6 @@ puts ClaudeHooks::UserPromptSubmit.merge_outputs(append_rules_result, log_result
 Each handler can run standalone for testing:
 ```ruby
 if __FILE__ == $0
-  hook = AppendRules.new(JSON.parse(STDIN.read))
-  puts hook.stringify_output
+  ClaudeHooks::CLI.test_runner(AppendRules)
 end
 ```