claude_hooks 0.2.1 → 1.0.2

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/1.0.0_MIGRATION_GUIDE.md

@@ -0,0 +1,228 @@
+# Migration Guide: 1.0.0
+
+This guide shows how to migrate from the old manual exit code patterns to the new simplified way introduced in v1.0.0.
+
+## Problem: The Old Way (Before)
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+require_relative '../handlers/pre_tool_use/github_guard'
+
+begin
+  # Read Claude Code input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  github_guard = GithubGuard.new(input_data)
+  guard_output = github_guard.call
+
+  # MANUAL: Extract hook-specific decision
+  hook_specific_decision = guard_output['hookSpecificOutput']['permissionDecision']
+  is_allowed_to_continue = guard_output['continue'] != false
+  final_output = github_guard.stringify_output
+
+  # MANUAL: Complex exit logic that you need to understand and get right
+  if is_allowed_to_continue
+    case hook_specific_decision
+    when 'block'
+      STDERR.puts final_output
+      exit 1
+    when 'ask'
+      STDERR.puts final_output
+      exit 2
+    else
+      puts final_output
+      exit 0
+    end
+  else
+    STDERR.puts final_output
+    exit 1
+  end
+rescue StandardError => e
+  # MANUAL: Error handling with manual JSON generation and stream selection
+  puts JSON.generate({
+    continue: false,
+    stopReason: "PreToolUser Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 1 # Allow anyway to not block developers if there is an issue
+end
+```
+
+**Problems with this approach:**
+- A lot of lines of repetitive boilerplate
+- Need to understand Claude Code's internal exit code semantics
+- Manual stream selection (STDOUT vs STDERR)
+- Error-prone - easy to get exit codes wrong
+- Need to manually extract hook-specific data from nested hashes
+
+## Solution: The New Way (After)
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+require_relative '../handlers/pre_tool_use/github_guard'
+
+begin
+  # Read Claude Code input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  github_guard = GithubGuard.new(input_data)
+  github_guard.call
+
+  # NEW: One line handles everything!
+  github_guard.output_and_exit
+
+rescue StandardError => e
+  # NEW: Simple error handling
+  STDERR.puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  # Non-blocking error
+  exit 1
+end
+```
+
+**Benefits:**
+- **More concise+** - 70% less boilerplate code
+- **No Claude Code knowledge needed** - just use the gem's API
+- **Automatic exit codes** based on hook-specific logic
+- **Automatic stream selection** (STDOUT/STDERR). Note: `PreToolUse` always outputs to STDOUT.
+- **Type-safe access** to hook-specific fields
+
+## New Output Object API
+
+### PreToolUse Hooks
+
+```ruby
+hook = GithubGuard.new(input_data)
+hook.call
+output = hook.output
+
+# Clean semantic access
+puts "Permission: #{output.permission_decision}"  # 'allow', 'deny', or 'ask'
+puts "Reason: #{output.permission_reason}"
+puts "Allowed? #{output.allowed?}"
+puts "Should ask? #{output.should_ask_permission?}"
+
+# Automatic exit logic
+puts "Exit code: #{output.exit_code}"      # 0, 1, or 2 based on permission
+puts "Stream: #{output.output_stream}"     # :stdout or :stderr
+
+# One call handles everything
+hook.output_and_exit  # Prints JSON to correct stream and exits with correct code
+```
+
+### UserPromptSubmit Hooks
+
+```ruby
+hook = MyPromptHook.new(input_data)
+hook.call
+output = hook.output
+
+# Clean semantic access
+puts "Blocked? #{output.blocked?}"
+puts "Reason: #{output.reason}"
+puts "Context: #{output.additional_context}"
+
+# Automatic execution
+hook.output_and_exit # Handles all the exit logic
+```
+
+### Stop Hooks (Special Logic)
+
+```ruby
+hook = MyStopHook.new(input_data)
+hook.call
+output = hook.output
+
+# Note: Stop hooks have inverted logic - 'decision: block' means "continue working"
+puts "Should continue? #{output.should_continue?}"      # true if decision == 'block'
+puts "Continue instructions: #{output.continue_instructions}"
+
+hook.output_and_exit  # exit 2 for "continue", exit 0 for "stop"
+```
+
+## Merging Multiple Hooks
+
+```ruby
+# OLD WAY: Manual merging with class methods
+result1 = hook1.call
+result2 = hook2.call
+merged_hash = ClaudeHooks::PreToolUse.merge_outputs(result1, result2)
+# ... then manual exit logic
+
+# NEW WAY: Clean object-based merging
+hook1.call
+hook2.call
+merged_output = ClaudeHooks::Output::PreToolUse.merge(
+  hook1.output,
+  hook2.output
+)
+# /!\ Called on the merged output
+merged_output.output_and_exit  # Handles everything automatically
+```
+
+## Simplified Entrypoint Pattern
+
+### For Single Hooks
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+require_relative '../handlers/my_hook'
+
+# Super simple - just 3 lines!
+ClaudeHooks::CLI.entrypoint do |input_data|
+  hook = MyHook.new(input_data)
+  hook.call
+  hook.output_and_exit
+end
+```
+
+### For Multiple Hooks with Merging
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+require_relative '../handlers/hook1'
+require_relative '../handlers/hook2'
+
+ClaudeHooks::CLI.entrypoint do |input_data|
+  hook1 = Hook1.new(input_data)
+  hook2 = Hook2.new(input_data)
+  hook1.call
+  hook2.call
+  
+  merged = ClaudeHooks::Output::PreToolUse.merge(
+    hook1.output,
+    hook2.output
+  )
+  # /!\ Called on the merged output
+  merged.output_and_exit
+end
+```
+
+## All Supported Hook Types
+
+- `ClaudeHooks::Output::UserPromptSubmit`
+- `ClaudeHooks::Output::PreToolUse` 
+- `ClaudeHooks::Output::PostToolUse`
+- `ClaudeHooks::Output::Stop`
+- `ClaudeHooks::Output::SubagentStop`
+- `ClaudeHooks::Output::Notification`
+- `ClaudeHooks::Output::SessionStart`
+- `ClaudeHooks::Output::SessionEnd`
+- `ClaudeHooks::Output::PreCompact`
+
+Each handles the specific exit code logic and semantic helpers for its hook type.
+
+## Migration Steps
+
+1. **Update your hook handlers** to return ``output` instead of `output_data`
+2. **Replace manual exit logic** with `hook.output_and_exit` or `merged_output.output_and_exit`
+3. **Use semantic helpers** instead of digging through hash structures
+4. **Use output object classes for merging** instead of hook class methods
+

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'`, `'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.
+
+[📚 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 |