claude_hooks 0.2.1 → 1.0.2

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 |

data/{WHY.md → 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
 ```

data/docs/external/claude-hooks-reference.md

@@ -0,0 +1,34 @@
+Documentation
+
+Page
+
+## Page Not Found
+
+### The requested page could not be found.
+
+Go back
+
+Ask Docs
+![Chat avatar](https://platform.claude.com/docs/images/book-icon-light.svg)
+
+a.claude.ai
+
+# a.claude.ai is blocked
+
+**a.claude.ai** refused to connect.
+
+ERR\_BLOCKED\_BY\_RESPONSE
+
+**a.claude.ai** refused to connect.
+
+![](<Base64-Image-Removed>)![](<Base64-Image-Removed>)
+
+Invalid domain for site key.
+
+ERROR for site owner:
+
+Invalid domain for site key
+
+reCAPTCHA
+
+[Privacy](https://www.google.com/intl/en/policies/privacy/) \- [Terms](https://www.google.com/intl/en/policies/terms/)

data/example_dotclaude/hooks/entrypoints/pre_tool_use.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+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
+
+  github_guard.output_and_exit
+rescue StandardError => e
+  puts JSON.generate(
+    {
+      continue: false,
+      stopReason: "Error in PreToolUse hook, #{e.message}, #{e.backtrace.join("\n")}",
+      suppressOutput: false,
+    },
+  )
+  # Allow anyway, to not block developers if there is an issue with the hook
+  exit 1
+end

data/example_dotclaude/hooks/entrypoints/session_end.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+require 'json'
+require_relative '../handlers/session_end/cleanup_handler'
+require_relative '../handlers/session_end/log_session_stats'
+
+begin
+  # Read input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  # Initialize handlers
+  cleanup_handler = CleanupHandler.new(input_data)
+  log_handler = LogSessionStats.new(input_data)
+
+  # Execute handlers
+  cleanup_handler.call
+  log_handler.call
+
+  # Merge outputs using the SessionEnd output merger
+  merged_output = ClaudeHooks::Output::SessionEnd.merge(
+    cleanup_handler.output,
+    log_handler.output
+  )
+
+  # Output result and exit with appropriate code
+  merged_output.output_and_exit
+
+rescue StandardError => e
+  STDERR.puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 2
+end

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -1,7 +1,13 @@
 #!/usr/bin/env ruby
 
+# Example of the NEW simplified entrypoint pattern using output objects
+# Compare this to the existing user_prompt_submit.rb to see the difference!
+
 require 'claude_hooks'
 require 'json'
+# Require the output classes
+require_relative '../../../lib/claude_hooks/output/base'
+require_relative '../../../lib/claude_hooks/output/user_prompt_submit'
 require_relative '../handlers/user_prompt_submit/append_rules'
 require_relative '../handlers/user_prompt_submit/log_user_prompt'
 
@@ -11,25 +17,24 @@ begin
 
   # Execute all hook scripts
   append_rules = AppendRules.new(input_data)
-  appended_rules_result = append_rules.call
+  append_rules.call
 
   log_user_prompt = LogUserPrompt.new(input_data)
-  log_user_prompt_result = log_user_prompt.call
+  log_user_prompt.call
 
-  # Merge all hook results intelligently using the UserPromptSubmit class method
-  hook_output = ClaudeHooks::UserPromptSubmit.merge_outputs(appended_rules_result, log_user_prompt_result)
+  merged_output = ClaudeHooks::Output::UserPromptSubmit.merge(
+    append_rules.output,
+    log_user_prompt.output
+  )
 
-  # Output final merged result to Claude Code
-  puts JSON.generate(hook_output)
+  merged_output.output_and_exit
 
-  exit 0 # Don't forget to exit with the right exit code (0, 1, 2)
 rescue StandardError => e
-  STDERR.puts "Error in UserPromptSubmit hook: #{e.message} #{e.backtrace.join("\n")}"
-
-  puts JSON.generate({
+  # Same simple error pattern
+  STDERR.puts JSON.generate({
     continue: false,
     stopReason: "Hook execution error: #{e.message} #{e.backtrace.join("\n")}",
     suppressOutput: false
   })
-  exit 1
-end
+  exit 2
+end

data/example_dotclaude/hooks/handlers/pre_tool_use/github_guard.rb

@@ -0,0 +1,253 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'claude_hooks'
+require 'json'
+require 'open3'
+
+# GitHub Guard hook to prevent unauthorized or dangerous GitHub/Git actions
+class GithubGuard < ClaudeHooks::PreToolUse
+  BLOCKED_TOOL_TIP = 'If they are sure they want to proceed, the user should run the command themselves using `!` (e.g. `!gh pr merge`, `!git push --force`, etc...)'
+
+  RULES = {
+    # MCP GitHub tools
+    mcp_tools: {
+      always_blocked: %w[
+        mcp__github__delete_repository
+        mcp__github__delete_file
+      ],
+      owner_restricted_pr: %w[
+        mcp__github__merge_pull_request
+        mcp__github__update_pull_request
+      ],
+      pr_draft_required: %w[
+        mcp__github__create_pull_request
+      ],
+    },
+
+    # Bash command patterns (gh & github)
+    bash_patterns: {
+      always_blocked: [
+        /\Agh\s+pr\s+merge.*--rebase/,
+        /\Agh\s+repo\s+delete/,
+        /\Agh\s+secret\s+(set|delete)/,
+        /\Agit\s+push\s+.*--force/,
+        /\Agit\s+reset\s+--hard/,
+        /\Agit\s+reset\s+--hard\s+HEAD~[0-9]+/,
+        /\Agit\s+clean\s+-[fd]/,
+        /\Agit\s+reflog\s+expire/,
+        /\Agit\s+filter-branch/,
+        /\Agit\s+checkout\s+--\s+\./,
+      ],
+      requires_permission: [
+        /\Agh\s+api/,
+        /\Agit\s+branch\s+(-D|-d|--delete)/,
+        /\Agit\s+rebase\s+(master|main)/,
+        /\Agit\s+commit\s+--amend/,
+        /\Agit\s+rebase\s+-i/,
+      ],
+      owner_restricted_pr: [
+        'gh pr merge',
+        'gh pr edit',
+        'gh pr close',
+        'gh pr ready',
+        'gh pr lock',
+      ],
+      pr_draft_required: [
+        'gh pr create',
+      ],
+    },
+  }.freeze
+
+  CURRENT_USER = begin
+    github_user_data = Open3.capture2('gh api user').then { |data, _| JSON.parse(data) }
+    git_user, = Open3.capture2('git config user.name')
+
+    {
+      name: github_user_data['name'] || git_user.strip,
+      login: github_user_data['login'] || '',
+    }
+  rescue StandardError => e
+    log "Error fetching github user data, #{e.message}, make sure Github CLI is installed and you are logged in.",
+        :error
+    { name: '', login: '' }
+  end
+
+  def call
+    log "Input data: #{input_data.inspect}"
+
+    case tool_name
+    when /\Amcp__github__/
+      log "Checking MCP tool: #{tool_name}"
+      validate_mcp_github_tool!
+    when 'Bash'
+      log "Checking tool: #{tool_name}(#{command})"
+      validate_bash_command!
+    else
+      approve_tool!("Tool #{tool_name} is allowed")
+    end
+
+    output_data
+  end
+
+  private
+
+  # Main validation methods
+  def validate_mcp_github_tool!
+    return block_with_tip!("#{tool_name} is dangerous and not allowed.") if always_blocked_mcp_tool?
+    return validate_pr_ownership!(tool_name, extract_pr_number_from_input) if owner_restricted_mcp_tool?
+    return validate_mcp_pr_draft_mode! if pr_draft_required_mcp_tool?
+
+    approve_tool!('Safe github MCP call')
+  end
+
+  def validate_bash_command!
+    return block_with_tip!("Command blocked: #{command} - dangerous pattern.") if always_blocked_command?
+    return ask_for_permission!("Command requires permission: #{command}") if requires_permission_command?
+    return validate_pr_ownership!(command, extract_pr_number_from_command) if owner_restricted_pr_command?
+    return prevent_remote_branch_deletion! if remote_branch_deletion_command?
+    return validate_bash_pr_draft_mode! if pr_draft_required_command?
+
+    approve_tool!('Safe bash command')
+  end
+
+  # Helper validation methods
+  def validate_pr_ownership!(context, pr_number)
+    return ask_for_permission!("Could not determine PR number from #{context}") unless pr_number
+
+    pr_owner = get_pr_owner(pr_number)
+    return ask_for_permission!("Could not determine owner of PR ##{pr_number}") unless pr_owner
+
+    if user_owns_pr?(pr_owner)
+      approve_tool!("PR ##{pr_number} belongs to current user (#{pr_owner})")
+    else
+      block_with_tip!("Cannot execute '#{context}' - PR ##{pr_number} belongs to #{pr_owner}, you are #{CURRENT_USER[:login]}") # rubocop:disable Layout/LineLength
+    end
+  end
+
+  def validate_mcp_pr_draft_mode!
+    if tool_input&.dig('draft') == true
+      approve_tool!('PR creation allowed (draft mode)')
+    else
+      block_with_tip!('PR creation must use draft: true. All PRs should be created as drafts.')
+    end
+  end
+
+  def validate_bash_pr_draft_mode!
+    if command.include?('--draft')
+      approve_tool!('PR creation allowed (draft mode)')
+    else
+      block_with_tip!('gh pr create must use --draft flag. All PRs should be created as drafts.')
+    end
+  end
+
+  def prevent_remote_branch_deletion!
+    branch = extract_branch_from_deletion
+    return ask_for_permission!('Could not determine branch name') unless branch
+
+    if remote_branch_deletion?
+      block_with_tip!("Cannot delete remote branch '#{branch}'")
+    else
+      approve_tool!('Branch deletion allowed')
+    end
+  end
+
+  # Rule matching methods
+  def always_blocked_mcp_tool?
+    RULES[:mcp_tools][:always_blocked].include?(tool_name)
+  end
+
+  def owner_restricted_mcp_tool?
+    RULES[:mcp_tools][:owner_restricted_pr].include?(tool_name)
+  end
+
+  def pr_draft_required_mcp_tool?
+    RULES[:mcp_tools][:pr_draft_required].include?(tool_name)
+  end
+
+  def always_blocked_command?
+    RULES[:bash_patterns][:always_blocked].any? { |pattern| command.match?(pattern) }
+  end
+
+  def requires_permission_command?
+    RULES[:bash_patterns][:requires_permission].any? { |pattern| command.match?(pattern) }
+  end
+
+  def owner_restricted_pr_command?
+    RULES[:bash_patterns][:owner_restricted_pr].any? { |cmd| command.start_with?(cmd) }
+  end
+
+  def pr_draft_required_command?
+    RULES[:bash_patterns][:pr_draft_required].any? { |cmd| command.start_with?(cmd) }
+  end
+
+  def remote_branch_deletion_command?
+    command.match?(/\Agit\s+push.*(--delete|-d|-D)/)
+  end
+
+  def remote_branch_deletion?
+    command.include?('origin') || command.include?('upstream')
+  end
+
+  # Utility methods
+  def user_owns_pr?(pr_owner)
+    pr_owner == CURRENT_USER[:login] || pr_owner == CURRENT_USER[:name]
+  end
+
+  # Extraction methods
+  def command
+    @command ||= tool_input&.dig('command') || ''
+  end
+
+  def extract_pr_number_from_input
+    params = tool_input || {}
+    params['pullNumber'] || params['pull_number'] || params['number']
+  end
+
+  def extract_pr_number_from_command
+    command.match(/\s+(\d+)/)&.[](1)&.to_i
+  end
+
+  def extract_branch_from_deletion
+    command.match(/(?:--delete|-d|-D)\s+(\S+)/)&.[](1)
+  end
+
+  def get_pr_owner(pr_number)
+    return nil unless pr_number
+
+    begin
+      # Try to get PR info using gh CLI
+      pr_info, status = Open3.capture2e("gh pr view #{pr_number} --json author")
+
+      if status.success?
+        data = JSON.parse(pr_info)
+        data.dig('author', 'login')
+      else
+        log "Could not fetch PR info: #{pr_info}", :warn
+        nil
+      end
+    rescue StandardError => e
+      log "Error fetching PR owner: #{e.message}", :error
+      nil
+    end
+  end
+
+  # Utility methods
+  def block_with_tip!(message)
+    block_tool!("#{message}\n#{BLOCKED_TOOL_TIP}")
+  end
+end
+
+# When running this file directly (for debugging)
+if __FILE__ == $PROGRAM_NAME
+  ClaudeHooks::CLI.run_with_sample_data(GithubGuard) do |data|
+    data.merge!(
+      'session_id' => 'GithubGuardTest',
+      'transcript_path' => '',
+      'cwd' => Dir.pwd,
+      'hook_event_name' => 'PreToolUse',
+      'tool_name' => 'mcp__github__create_pull_request',
+      'tool_input' => { 'draft' => false },
+    )
+  end
+end

data/example_dotclaude/hooks/handlers/session_end/cleanup_handler.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require_relative '../../../../lib/claude_hooks'
+
+class CleanupHandler < ClaudeHooks::SessionEnd
+  def call
+    log "Session ended with reason: #{reason}"
+    
+    case reason
+    when 'clear'
+      log "Performing cleanup after /clear command"
+      cleanup_temp_files
+    when 'logout'
+      log "Performing cleanup after logout"
+      save_session_state
+    when 'prompt_input_exit'
+      log "User exited during prompt input"
+      save_partial_state
+    else
+      log "General session cleanup"
+      general_cleanup
+    end
+    
+    output
+  end
+
+  private
+
+  def cleanup_temp_files
+    log "Cleaning up temporary files for session #{session_id}"
+    # Example cleanup logic
+  end
+
+  def save_session_state
+    log "Saving session state for session #{session_id}"
+    # Example state saving logic
+  end
+
+  def save_partial_state
+    log "Saving partial state for session #{session_id}"
+    # Example partial state saving logic
+  end
+
+  def general_cleanup
+    log "Performing general cleanup for session #{session_id}"
+    # Example general cleanup logic
+  end
+end
+
+# CLI testing support
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(CleanupHandler) do |input_data|
+    input_data['reason'] ||= 'other'
+  end
+end