claude_hooks 0.2.0 → 1.0.0

data/claude_hooks.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "A Ruby DSL framework for creating Claude Code hooks with composable hook scripts that enable teams to easily implement logging, security checks, and workflow automation."
   spec.homepage = "https://github.com/gabriel-dehan/claude_hooks"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.7.0"
+  spec.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
   spec.metadata["homepage_uri"] = spec.homepage
@@ -35,5 +35,5 @@ Gem::Specification.new do |spec|
 
   # Development dependencies
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
 end

data/docs/API/COMMON.md

@@ -0,0 +1,83 @@
+# Common API Methods
+
+Those methods are available in **all hook types** and are inherited from `ClaudeHooks::Base`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+| Method | Description |
+|--------|-------------|
+| `input_data` | Input data reader |
+| `session_id` | Get the current session ID |
+| `transcript_path` | Get path to the transcript file |
+| `cwd` | Get current working directory |
+| `hook_event_name` | Get the hook event name |
+| `read_transcript` | Read the transcript file |
+| `transcript` | Alias for `read_transcript` |
+
+## Hook State Helpers
+Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
+
+| Method | Description |
+|--------|-------------|
+| `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) |
+| `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 |
+
+## Output Helpers
+
+From a hook, you can always access the `output` object via `hook.output`. 
+This object provides helpers to access output data, for merging multiple outputs as well as sending the right exit codes and data back to Claude Code.
+
+### Output data access
+
+| Method | Description |
+|--------|-------------|
+| `output` | Output object accessor |
+| `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.hook_specific_output` | Get the hook-specific output data |
+| `output.system_message` | Get the system message if any |
+
+### 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)`.
+
+| Method | Description |
+|--------|-------------|
+| `merge(*outputs)` | Intelligently merge multiple outputs of the same type into a single output |
+
+### Exit Control and Yielding back to Claude Code
+
+| Method | Description |
+|--------|-------------|
+| `output.output_and_exit` | Automatically output to correct stream and exit with proper code |
+| `output.exit_code` | Get the calculated exit code based on hook state |
+| `output.output_stream` | Get the proper output stream (:stdout or :stderr) depending on hook state |
+| `output.to_json` | Generates a JSON string of the output |
+
+## Configuration and Utility Methods
+
+### Utility Methods
+| Method | Description |
+|--------|-------------|
+| `log(message, level: :info)` | Log to session-specific file (levels: :info, :warn, :error) |
+
+### Configuration Methods
+| Method | Description |
+|--------|-------------|
+| `home_claude_dir` | Get the home Claude directory (`$HOME/.claude`) |
+| `project_claude_dir` | Get the project Claude directory (`$CLAUDE_PROJECT_DIR/.claude`, or `nil`) |
+| `home_path_for(relative_path)` | Get absolute path relative to home Claude directory |
+| `project_path_for(relative_path)` | Get absolute path relative to project Claude directory (or `nil`) |
+| `base_dir` | Get the base Claude directory (**deprecated**) |
+| `path_for(relative_path, base_dir=nil)` | Get absolute path relative to specified or default base dir (**deprecated**) |
+| `config` | Access the merged configuration object |
+| `config.get_config_value(env_key, config_file_key, default)` | Get any config value with fallback |
+| `config.logs_directory` | Get logs directory path (always under home directory) |
+| `config.your_custom_key` | Access any custom config via method_missing |

data/docs/API/NOTIFICATION.md

@@ -0,0 +1,32 @@
+# Notification API
+
+Available when inheriting from `ClaudeHooks::Notification`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `message` | Get the notification message content |
+| `notification_message` | Alias for `message` |
+
+## Hook State Helpers
+Notifications are outside facing and do not have any specific state to modify.
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+## Output Helpers
+Output helpers provide access to the hook's output data and helper methods for working with the output state.
+Notifications don't have any specific hook state and thus doesn't have any specific output helpers.
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+## Hook Exit Codes
+
+| 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`) |

data/docs/API/POST_TOOL_USE.md

@@ -0,0 +1,45 @@
+# PostToolUse API
+
+Available when inheriting from `ClaudeHooks::PostToolUse`:
+
+## 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 that was used |
+| `tool_input` | Get the input that was passed to the tool |
+| `tool_response` | Get the tool's response/output |
+
+## 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 |
+|--------|-------------|
+| `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 |
+
+## 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.decision` | Get the decision: "block" or nil (default) |
+| `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 |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Operation continues<br/>`STDOUT` shown to user in transcript mode |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
+| `exit 2` | N/A<br/>`STDERR` shown to Claude *(tool already ran)* |

data/docs/API/PRE_COMPACT.md

@@ -0,0 +1,39 @@
+# PreCompact API
+
+Available when inheriting from `ClaudeHooks::PreCompact`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `trigger` | Get the compaction trigger: `'manual'` or `'auto'` |
+| `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)
+
+## Utility Methods
+Utility methods for transcript management.
+
+| Method | Description |
+|--------|-------------|
+| `backup_transcript!(backup_file_path)` | Create a backup of the transcript at the specified path |
+
+## 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)
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Operation continues<br/>`STDOUT` shown to user in transcript mode |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
+| `exit 2` | N/A<br/>`STDERR` shown to user only|

data/docs/API/PRE_TOOL_USE.md

@@ -0,0 +1,110 @@
+# PreToolUse API
+
+Available when inheriting from `ClaudeHooks::PreToolUse`:
+
+## 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 being used |
+| `tool_input` | Get the input data for the tool |
+
+## 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_tool!(reason)` | Explicitly approve tool usage |
+| `block_tool!(reason)` | Block tool usage with feedback |
+| `ask_for_permission!(reason)` | Request user permission |
+
+## 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 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.should_ask_permission?` | Check if user permission is required (permission_decision == 'ask') |
+| `output.permission_decision` | Get the permission decision: 'allow', 'deny', or 'ask' |
+| `output.permission_reason` | Get the reason for the permission decision |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Operation continues<br/>`STDOUT` shown to user in transcript mode |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
+| `exit 2` | **Blocks the tool call**<br/>`STDERR` shown to Claude |
+
+## Exit code behaviors related to chosen output stream
+Outputting to a specific stream has a different effect depending on the exit code.
+
+> [!TIP]
+> The most common and useful cases expressed in the tables below are handled automatically by calling `hook.output_and_exit`. 
+> You only need to worry about this when you want very specific behavior.
+
+### ALLOW
+
+#### Claude Code behavior depending on combination
+
+| Exit Code  | STDERR | STDOUT |
+|------------|--------|--------|
+| 0          | RUNS   | RUNS   |
+| 1          | RUNS   | RUNS   |
+| 2          | BLOCKS | RUNS   |
+
+#### Output visibility depending on exit code
+
+| Output Visibility / Exit Code | 0     | 1     | 2       |
+|-------------------------------|-------|-------|---------|
+| **STDOUT sent to Claude**     | ✅ YES | ✅ YES | ✅ YES |
+| **STDOUT shown to User**      | ❌ NO  | ❌ NO  | ❌ NO  |
+| **STDERR sent to Claude**     | ❌ NO  | ❌ NO  | ✅ YES |
+| **STDERR shown to User**      | ❌ NO  | ✅ YES | ✅ YES |
+
+### ASK
+
+#### Claude Code behavior depending on combination
+
+| Exit Code  | STDERR | STDOUT |
+|------------|--------|--------|
+| 0          | RUNS   | ASKS   |
+| 1          | RUNS   | ASKS   |
+| 2          | BLOCKS | ASKS   |
+
+#### Output visibility depending on exit code
+
+| Output Visibility / Exit Code | 0     | 1     | 2       |
+|-------------------------------|-------|-------|---------|
+| **STDOUT sent to Claude**     | ✅ YES | ✅ YES | ✅ YES |
+| **STDOUT shown to User**      | ✅ YES | ✅ YES | ✅ YES |
+| **STDERR sent to Claude**     | ❌ NO  | ❌ NO  | ✅ YES |
+| **STDERR shown to User**      | ❌ NO  | ✅ YES | ✅ YES |
+
+### DENY
+
+#### Claude Code behavior depending on combination
+
+| Exit Code  | STDERR | STDOUT |
+|------------|--------|--------|
+| 0          | BLOCKS | BLOCKS |
+| 1          | BLOCKS | BLOCKS |
+| 2          | BLOCKS | BLOCKS |
+
+#### Output visibility depending on exit code
+
+| Output Visibility / Exit Code | 0     | 1     | 2       |
+|-------------------------------|-------|-------|---------|
+| **STDOUT sent to Claude**     | ✅ YES | ✅ YES | ✅ YES |
+| **STDOUT shown to User**      | ✅ YES | ✅ YES | ✅ YES |
+| **STDERR sent to Claude**     | ❌ NO  | ❌ NO  | ✅ YES |
+| **STDERR shown to User**      | ❌ NO  | ✅ YES | ✅ YES |

data/docs/API/SESSION_END.md

@@ -0,0 +1,100 @@
+# SessionEnd API
+
+> [!NOTE] 
+> SessionEnd hooks cannot block session termination - they are designed for cleanup tasks only.
+
+Available when inheriting from `ClaudeHooks::SessionEnd`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `reason` | Get the reason for session termination |
+
+### Reason Helpers
+
+| Method | Description |
+|--------|-------------|
+| `cleared?` | Check if session was cleared with `/clear` command |
+| `logout?` | Check if user logged out |
+| `prompt_input_exit?` | Check if user exited while prompt input was visible |
+| `other_reason?` | Check if reason is unspecified or other |
+
+## Hook State Helpers
+Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.
+SessionEnd hooks do not have any specific state to modify.
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+## Output Helpers
+Output helpers provide access to the hook's output data and helper methods for working with the output state.
+SessionEnd hooks don't have any specific hook state and thus doesn't have any specific output helpers.
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+## Hook Exit Codes
+
+| 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`) |
+
+## Example Usage
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+
+class MySessionCleanup < ClaudeHooks::SessionEnd
+  def call
+    log "Session ending with reason: #{reason}"
+    
+    if cleared?
+      log "Cleaning up after /clear command"
+      add_cleanup_message!("Temporary files cleaned")
+    elsif logout?
+      log "User logged out - saving state"
+      log_session_info!("Session saved successfully")
+    elsif prompt_input_exit?
+      log "Interrupted during prompt - partial cleanup"
+      add_cleanup_message!("Partial state saved")
+    else
+      log "General session cleanup"
+      add_cleanup_message!("Session ended normally")
+    end
+    
+    output
+  end
+end
+
+# CLI testing
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(MySessionCleanup)
+end
+```
+
+## Session Configuration
+
+Register the hook in your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/entrypoints/session_end.rb"
+          }
+        ]
+      }
+    ]
+  }
+}
+```

data/docs/API/SESSION_START.md

@@ -0,0 +1,40 @@
+# SessionStart API
+
+Available when inheriting from `ClaudeHooks::SessionStart`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `source` | Get the session start source: `'startup'`, `'resume'`, or `'clear'` |
+
+## 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 contextual information for Claude's session |
+| `add_context!(context)` | Alias for `add_additional_context!` |
+| `empty_additional_context!` | Clear 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
+
+| 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<br/>`STDERR` shown to user only |

data/docs/API/STOP.md

@@ -0,0 +1,47 @@
+# Stop API
+
+Available when inheriting from `ClaudeHooks::Stop`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `stop_hook_active` | Check if Claude Code is already continuing as a result of a stop hook |
+
+## 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)
+
+> [!NOTE] 
+> In Stop hooks, the decision to "block" actually means to "force Claude to continue", we are "blocking" the blockage. 
+> This is counterintuitive and the reason why the method `block!` is aliased to `continue_with_instructions!`
+
+| Method | Description |
+|--------|-------------|
+| `continue_with_instructions!(instructions)` | Block Claude from stopping and provide instructions to continue |
+| `block!(instructions)` | Alias for `continue_with_instructions!` |
+| `ensure_stopping!` | Allow Claude to stop normally (default behavior) |
+
+## 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.should_continue?` | Check if Claude should be forced to continue (decision == 'block') |
+| `output.should_stop?` | Check if Claude should stop normally (decision != 'block') |
+| `output.continue_instructions` | Get the continue instructions (alias for `reason`) |
+| `output.reason` | Get the reason for the decision |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Agent will stop<br/>`STDOUT` shown to user in transcript mode |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
+| `exit 2` | **Blocks stoppage**<br/>`STDERR` shown to Claude |

data/docs/API/SUBAGENT_STOP.md

@@ -0,0 +1,47 @@
+# SubagentStop API
+
+Available when inheriting from `ClaudeHooks::SubagentStop` (inherits from `ClaudeHooks::Stop`):
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `stop_hook_active` | Check if Claude Code is already continuing as a result of a stop hook |
+
+## 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)
+
+> [!NOTE] 
+> In Stop hooks, the decision to "block" actually means to "force Claude to continue", we are "blocking" the blockage. 
+> This is counterintuitive and the reason why the method `block!` is aliased to `continue_with_instructions!`
+
+| Method | Description |
+|--------|-------------|
+| `continue_with_instructions!(instructions)` | Block Claude from stopping and provide instructions to continue |
+| `block!(instructions)` | Alias for `continue_with_instructions!` |
+| `ensure_stopping!` | Allow Claude to stop normally (default behavior) |
+
+## 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.should_continue?` | Check if Claude should be forced to continue (decision == 'block') |
+| `output.should_stop?` | Check if Claude should stop normally (decision != 'block') |
+| `output.continue_instructions` | Get the continue instructions (alias for `reason`) |
+| `output.reason` | Get the reason for the decision |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Subagent will stop<br/>`STDOUT` shown to user in transcript mode |
+| `exit 1` | Non-blocking error<br/>`STDERR` shown to user |
+| `exit 2` | **Blocks stoppage**<br/>`STDERR` shown to Claude subagent |

data/docs/API/USER_PROMPT_SUBMIT.md

@@ -0,0 +1,47 @@
+# UserPromptSubmit API
+
+Available when inheriting from `ClaudeHooks::UserPromptSubmit`:
+
+## Input Helpers
+Input helpers to access the data provided by Claude Code through `STDIN`.
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `prompt` | Get the user's prompt text |
+| `user_prompt` | Alias for `prompt` |
+| `current_prompt` | Alias for `prompt` |
+
+## 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 to the prompt |
+| `add_context!(context)` | Alias for `add_additional_context!` |
+| `empty_additional_context!` | Remove additional context |
+| `block_prompt!(reason)` | Block the prompt from processing |
+| `unblock_prompt!` | Unblock a previously blocked prompt |
+
+## 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.decision` | Get the decision: "block" or nil (default) |
+| `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 |
+
+## Hook Exit Codes
+
+| 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` | **Blocks prompt processing**<br/>**Erases prompt**<br/>`STDERR` shown to user only |