claude_hooks 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1803cc66c5f4c6e0d2ca706c4106654a2aa961e8a8e968d3198acab8ff95a7d
-  data.tar.gz: 5dba30b7bce90d4a420cb1c83be1b9e2e2c3a1b0b1dfc42f47b0edd01e08941c
+  metadata.gz: 4ff845df334960263a1d36b01aeba57393609c59acbc63424572c9d7fdca7999
+  data.tar.gz: 70029c193102d9a63b6d6e5ff8361fcf42e506bff26435c907ec4a06010a571a
 SHA512:
-  metadata.gz: f5b394c9005bea73bdb66db595e3783fc7cb2e67889dbf2923b945899bd8c907edf0df241a534ac4a2679c887a07538ec9e1d65d58d24f2b9313cded33e5ca18
-  data.tar.gz: b9867904501454ef867f5be72a0c82e63de3d7bcfdfe6981c8cfbbf946fdd50cc2968671dfd341a1811736da51302c67e412e09302e295b61b30abca25790b23
+  metadata.gz: 28a4548cafd93c7f5d5c9d1f577399d8e90503c2e4ae1fa279a9723234045848c0b3bdbb1c41df9f0808d375eb5d345a5210d9db46fe74ba3332fb2394920530
+  data.tar.gz: e2555f3731aad5bacb7e572c9630fa9e39721b625684664bc2ea41d9b0579af146f697b10a6d99410368140ebb7cd37de53b2bd195e2a2c13a5100722502fcd2

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2026-07-15
+
+### Added
+
+- **`CLI.run_hook` — new primary entrypoint method** replacing `CLI.entrypoint`. Reads JSON from STDIN, runs the hook, and exits with the correct code and stream for the hook type.
+  - Accepts `on_error: :allow` (default, exit 1 — non-blocking) or `on_error: :block` (exit 2 — blocking). Use `:block` for security/policy hooks where a crash should never silently pass through.
+  - Supports a class form (`CLI.run_hook(MyHook)`) and a block form for multi-handler merging.
+
+### Changed
+
+- **`CLI.entrypoint` deprecated** in favour of `CLI.run_hook`. It remains as a delegating alias with a deprecation warning and will be removed in a future minor version.
+- **`CLI.run_hook` (old)** — the previous public `run_hook(hook_class, input_data)` helper used internally by `test_runner`/`run_with_sample_data` has been renamed to `run_hook_with_data` and made private. It was never intended as part of the public API.
+- **Error output stream** — `CLI.run_hook` / `CLI.entrypoint` now write errors exclusively to stderr (previously the `:allow` path also wrote to stdout). On the `on_error: :block` (exit 2) path the message is written as **plain text**, not JSON, since Claude Code shows exit-2 stderr to the model verbatim and never parses it as JSON. The `:allow` (exit 1) path still writes the JSON error object to stderr.
+- **README and examples** updated throughout to use `CLI.run_hook`.
+
+### Notes
+
+- No hook class or output class changes — existing hook scripts continue to work without modification
+- `CLI.entrypoint` still works; only a deprecation warning is emitted
+- 3 new tests covering `on_error: :block` (hook error → exit 2, invalid JSON → exit 2) and the deprecation warning
+
 ## [1.2.0] - 2026-07-14
 
 ### Added

data/README.md

@@ -50,10 +50,8 @@ Here's how to create a simple command hook with this DSL:
 1. **Create a simple hook script**
 ```ruby
 #!/usr/bin/env ruby
-require 'json'
 require 'claude_hooks'
 
-# Inherit from the right hook type class to get access to helper methods
 class AddContextAfterPrompt < ClaudeHooks::UserPromptSubmit
   def call
     log "User asked: #{prompt}"
@@ -62,18 +60,7 @@ class AddContextAfterPrompt < ClaudeHooks::UserPromptSubmit
   end
 end
 
-# Run the hook
-if __FILE__ == $0
-  # Read Claude Code's input data from STDIN
-  input_data = JSON.parse(STDIN.read)
-
-  hook = AddContextAfterPrompt.new(input_data)
-  hook.call
-
-  # Handles output and exit code depending on the hook state.
-  # In this case, uses exit code 0 (success) and prints output to STDOUT
-  hook.output_and_exit
-end
+ClaudeHooks::CLI.run_hook(AddContextAfterPrompt)
 ```
 
 3. ⚠️ **Make it executable**
@@ -102,7 +89,7 @@ echo '{"session_id":"test","prompt":"Hello!"}' | ./add_context_after_prompt.rb
 That's it! Your hook will now add context to every user prompt. 🎉
 
 > [!TIP]
-> This was a very simple example but we recommend using the entrypoints/handlers architecture [described below](#recommended-structure-for-your-claudehooks-directory) to create more complex hook systems.
+> Need to run multiple hooks for the same event and merge their outputs? See [Multi-hook structure](#multi-hook-structure) below.
 
 ## 📦 Installation
 
@@ -232,34 +219,47 @@ end
 ### Core Components
 
 1. **`ClaudeHooks::Base`** - Base class with common functionality (logging, config, validation)
-2. **Hook Handler Classes** - Self-contained classes (`ClaudeHooks::UserPromptSubmit`, `ClaudeHooks::PreToolUse`, etc.)
-3. **Output Classes** - `ClaudeHooks::Output::UserPromptSubmit`, etc... are output objects that handle intelligent merging of multiple outputs, as well as using the right exit codes and outputting to the proper stream (`STDIN` or `STDERR`) depending on the the hook state.
-4. **Configuration** - Shared configuration management via `ClaudeHooks::Configuration`
-5. **Logger** - Dedicated logging class with multiline block support
+2. **Hook Classes** - One class per event type (`ClaudeHooks::UserPromptSubmit`, `ClaudeHooks::PreToolUse`, etc.) that you can inherit from in your hook scripts
+3. **Output Classes**: those hook classes return instances of output objects (`ClaudeHooks::Output::UserPromptSubmit`, etc.) that handle intelligent merging of multiple outputs, correct exit codes, and routing to `STDOUT` or `STDERR` depending on hook state
+4. **`ClaudeHooks::CLI`** - Entrypoint helpers: `CLI.run_hook` for production, `CLI.test_runner`/`CLI.run_with_sample_data` for local testing
+5. **Configuration** - Shared configuration management via `ClaudeHooks::Configuration`
+6. **Logger** - Dedicated logging class with multiline block support
 
-### Recommended structure for your .claude/hooks/ directory
+### Hook file structure
+
+For simple cases like one hook class per event, a single file is all you need. Name each file after what it does — the event it runs on comes from where you register it in `settings.json`, not from the filename:
 
 ```
 .claude/hooks/
-├── entrypoints/                # Main entry points
-│   ├── notification.rb
-│   ├── pre_tool_use.rb
-│   ├── post_tool_use.rb
-│   ├── pre_compact.rb
-│   ├── session_start.rb
-│   ├── stop.rb
-│   └── subagent_stop.rb
-|
-└── handlers/                    # Hook handlers for specific hook type
-    ├── user_prompt_submit/
-    │   ├── append_rules.rb
-    │   └── log_user_prompt.rb
-    ├── pre_tool_use/
-    │   ├── github_guard.rb
-    │   └── tool_monitor.rb
-    └── ...
+├── github_guard.rb       # PreToolUse   — ClaudeHooks::CLI.run_hook(GithubGuard, on_error: :block)
+├── format_on_write.rb    # PostToolUse  — ClaudeHooks::CLI.run_hook(FormatOnWrite)
+├── load_project_rules.rb # SessionStart — ClaudeHooks::CLI.run_hook(LoadProjectRules)
+└── append_rules.rb       # UserPromptSubmit — ClaudeHooks::CLI.run_hook(AppendRules)
 ```
 
+See [`example_dotclaude/hooks/github_guard.rb`](example_dotclaude/hooks/github_guard.rb) for a complete, self-contained `PreToolUse` hook wired up this way.
+
+### Multi-hook structure
+
+When you need to run multiple hooks for the same event and merge their outputs, split into entrypoints and handlers:
+
+```
+.claude/hooks/
+├── entrypoints/                 # Coordinates multiple handlers per event
+│   ├── session_end.rb
+│   └── user_prompt_submit.rb
+│
+└── handlers/                    # One class per concern
+    ├── session_end/
+    │   ├── cleanup_handler.rb
+    │   └── log_session_stats.rb
+    └── user_prompt_submit/
+        ├── append_rules.rb
+        └── log_user_prompt.rb
+```
+
+Use this structure only when you need `Output.merge` across multiple handlers — a single-handler entrypoint is just noise; register the hook class directly instead (see [Hook file structure](#hook-file-structure) above). See [`example_dotclaude/hooks/entrypoints/session_end.rb`](example_dotclaude/hooks/entrypoints/session_end.rb) for a working two-handler entrypoint.
+
 ## 🪝 Hook Types
 
 The framework supports the following hook types:
@@ -314,37 +314,11 @@ graph LR
   A[Hook triggers] --> B[JSON from STDIN] --> C[Hook does its thing] --> D[JSON to STDOUT or STDERR<br />Exit Code] --> E[Yields back to Claude Code] --> A
 ```
 
-The main issue is that there are many different types of hooks and they each have different expectations regarding the data outputted to `STDIN` or `STDERR` and Claude Code will react differently for each specific exit code used depending on the hook type.
+The main issue is that there are many different types of hooks and they each have different expectations regarding the data outputted to `STDOUT` or `STDERR` and Claude Code will react differently for each specific exit code used depending on the hook type. This DSL handles all of that for you.
 
-### 🔄 Proposal: a more robust Claude Hook execution flow
+### Basic hook structure
 
-1. An entrypoint for a hook is set in `~/.claude/settings.json`
-2. Claude Code calls the entrypoint script (e.g., `hooks/entrypoints/pre_tool_use.rb`)
-3. The entrypoint script reads STDIN and coordinates multiple **hook handlers**
-4. Each **hook handler** executes and returns its output data
-5. The entrypoint script combines/processes outputs from multiple **hook handlers**
-6. And then returns final response to Claude Code with the correct exit code
-
-```mermaid
-graph TD
-  A[🔧 Hook Configuration<br/>settings.json] --> B
-  B[🤖 Claude Code<br/><em>User submits prompt</em>] --> C[📋 Entrypoint<br />entrypoints/user_prompt_submit.rb]
-
-  C --> D[📋 Entrypoint<br />Parses JSON from STDIN]
-  D --> E[📋 Entrypoint<br />Calls hook handlers]
-
-  E --> F[📝 Handler<br />AppendContextRules.call<br/><em>Returns output</em>]
-  E --> G[📝 Handler<br />PromptGuard.call<br/><em>Returns output</em>]
-
-  F --> J[📋 Entrypoint<br />Calls _ClaudeHooks::Output::UserPromptSubmit.merge_ to 🔀 merge outputs]
-  G --> J
-
-  J --> K[📋 Entrypoint<br />- Writes output to STDOUT or STDERR<br />- Uses correct exit code]
-  K --> L[🤖 Yields back to Claude Code]
-  L --> B
-```
-
-### Basic Hook Handler Structure
+The simplest pattern is a single file: define your hook class, call `CLI.run_hook`. It handles STDIN parsing, error handling, and correct exit codes.
 
 ```ruby
 #!/usr/bin/env ruby
@@ -353,47 +327,53 @@ require 'claude_hooks'
 
 class AddContextAfterPrompt < ClaudeHooks::UserPromptSubmit
   def call
-    # Access input data
-    log do
-      "--- INPUT DATA ---"
-      "session_id: #{session_id}"
-      "cwd: #{cwd}"
-      "hook_event_name: #{hook_event_name}"
-      "prompt: #{current_prompt}"
-      "---"
-    end
-
+    log "session_id: #{session_id}, prompt: #{prompt}"
     log "Full conversation transcript: #{read_transcript}"
 
-    # Use a Hook state method to modify what's sent back to Claude Code
     add_additional_context!("Some custom context")
 
-    # Control execution, for instance: block the prompt
-    if current_prompt.include?("bad word")
+    if prompt.include?("bad word")
       block_prompt!("Hmm no no no!")
-      log "Prompt blocked: #{current_prompt} because of bad word"
     end
 
-    # Return output if you need it
     output
   end
 end
 
-# Use your handler (usually from an entrypoint file, but this is an example)
-if __FILE__ == $0
-  # Read Claude Code's input data from STDIN
-  input_data = JSON.parse(STDIN.read)
+ClaudeHooks::CLI.run_hook(AddContextAfterPrompt)
+```
 
-  hook = AddContextAfterPrompt.new(input_data)
-  # Call the hook
-  hook.call
+### Multi-handler flow
 
-  # Uses exit code 0 (success) and outputs to STDIN if the prompt wasn't blocked
-  # Uses exit code 2 (blocking error) and outputs to STDERR if the prompt was blocked
-  hook.output_and_exit
-end
+When multiple hook classes need to respond to the same event, use an entrypoint file to coordinate them:
+
+1. A hook is registered in `~/.claude/settings.json`
+2. Claude Code calls an entrypoint script
+3. The entrypoint instantiates each handler and calls them
+4. Outputs are merged with `Output.merge` (most restrictive behavior wins)
+5. The merged output is returned to Claude Code with the correct exit code
+
+```mermaid
+graph TD
+  A[🔧 Hook Configuration<br/>settings.json] --> B
+  B[🤖 Claude Code<br/><em>User submits prompt</em>] --> C[📋 Entrypoint<br />entrypoints/user_prompt_submit.rb]
+
+  C --> D[📋 Entrypoint<br />Parses JSON from STDIN]
+  D --> E[📋 Entrypoint<br />Calls hook handlers]
+
+  E --> F[📝 Handler<br />AppendRules.call<br/><em>Returns output</em>]
+  E --> G[📝 Handler<br />LogUserPrompt.call<br/><em>Returns output</em>]
+
+  F --> J[📋 Entrypoint<br />Calls _ClaudeHooks::Output::UserPromptSubmit.merge_ to 🔀 merge outputs]
+  G --> J
+
+  J --> K[📋 Entrypoint<br />- Writes output to STDOUT or STDERR<br />- Uses correct exit code]
+  K --> L[🤖 Yields back to Claude Code]
+  L --> B
 ```
 
+See [Hook Output Merging](#-hook-output-merging) below for the entrypoint code that implements this flow, and [`example_dotclaude/hooks/entrypoints/user_prompt_submit.rb`](example_dotclaude/hooks/entrypoints/user_prompt_submit.rb) for a working `AppendRules` + `LogUserPrompt` example.
+
 ## 📚 API Reference
 
 The goal of those APIs is to simplify reading from `STDIN` and writing to `STDOUT` or `STDERR` as well as exiting with the right exit codes: the way Claude Code expects you to.
@@ -522,7 +502,7 @@ Logs are written to session-specific files in the configured log directory:
 
 Let's create a hook that will monitor tool usage and ask for permission before using dangerous tools.
 
-First, register an entrypoint in `~/.claude/settings.json`:
+First, register your hook in `~/.claude/settings.json`:
 
 ```json
 "hooks": {
@@ -532,7 +512,7 @@ First, register an entrypoint in `~/.claude/settings.json`:
       "hooks": [
         {
           "type": "command",
-          "command": "~/.claude/hooks/entrypoints/pre_tool_use.rb"
+          "command": "~/.claude/hooks/tool_monitor.rb"
         }
       ]
     }
@@ -540,43 +520,11 @@ First, register an entrypoint in `~/.claude/settings.json`:
 }
 ```
 
-Then, create your main entrypoint script and _don't forget to make it executable_:
-```bash
-touch ~/.claude/hooks/entrypoints/pre_tool_use.rb
-chmod +x ~/.claude/hooks/entrypoints/pre_tool_use.rb
-```
-
-```ruby
-#!/usr/bin/env ruby
-
-require 'json'
-require_relative '../handlers/pre_tool_use/tool_monitor'
-
-begin
-  # Read input from stdin
-  input_data = JSON.parse(STDIN.read)
-
-  tool_monitor = ToolMonitor.new(input_data)
-  tool_monitor.call
-
-  # You could also call any other handler here and then merge the outputs
-
-  tool_monitor.output_and_exit
-rescue StandardError => e
-  STDERR.puts JSON.generate({
-    continue: false,
-    stopReason: "Hook execution error: #{e.message}",
-    suppressOutput: false
-  })
-  # Non-blocking error
-  exit 1
-end
-```
-
-Finally, create the handler that will be used to monitor tool usage.
+Then create the hook script and make it executable:
 
 ```bash
-touch ~/.claude/hooks/handlers/pre_tool_use/tool_monitor.rb
+touch ~/.claude/hooks/tool_monitor.rb
+chmod +x ~/.claude/hooks/tool_monitor.rb
 ```
 
 ```ruby
@@ -592,17 +540,16 @@ class ToolMonitor < ClaudeHooks::PreToolUse
 
     if DANGEROUS_TOOLS.include?(tool_name)
       log "Dangerous tool detected: #{tool_name}", level: :warn
-      # Use one of the ClaudeHooks::PreToolUse methods to modify the hook state and block the tool
       ask_for_permission!("The tool '#{tool_name}' can impact your system. Allow?")
     else
-      # Use one of the ClaudeHooks::PreToolUse methods to modify the hook state and allow the tool
       approve_tool!("Safe tool usage")
     end
 
-    # Accessor provided by ClaudeHooks::PreToolUse
     output
   end
 end
+
+ClaudeHooks::CLI.run_hook(ToolMonitor, on_error: :block)
 ```
 
 ## 🔄 Hook Output
@@ -620,24 +567,24 @@ This method will return an output object based on the hook's type class (e.g: `C
 
 ### 🔄 Hook Output Merging
 
-Often, you will want to call multiple hooks from a same entrypoint.
-Each hook type's `output` provides a `merge` method that will try to intelligently merge multiple hook results.
-Merged outputs always inherit the **most restrictive behavior**.
+When running multiple hooks for the same event, each hook type's `output` provides a `merge` method that intelligently combines results. Merged outputs always inherit the **most restrictive behavior**.
 
 ```ruby
+#!/usr/bin/env ruby
 
 require 'json'
+require 'claude_hooks'
 require_relative '../handlers/user_prompt_submit/hook1'
 require_relative '../handlers/user_prompt_submit/hook2'
 require_relative '../handlers/user_prompt_submit/hook3'
 
 begin
-# Read input from stdin
+  # Read input from stdin
   input_data = JSON.parse(STDIN.read)
 
   hook1 = Hook1.new(input_data)
-  hook2 = Hook1.new(input_data)
-  hook3 = Hook1.new(input_data)
+  hook2 = Hook2.new(input_data)
+  hook3 = Hook3.new(input_data)
 
   # Execute the multiple hooks
   hook1.call
@@ -659,6 +606,14 @@ begin
 
   # Automatically handles outputting to the right stream (STDOUT or STDERR) and uses the right exit code depending on hook state
   merged_output.output_and_exit
+rescue StandardError => e
+  # This is exactly what CLI.run_hook does for you (non-blocking / fail-open):
+  STDERR.puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 1
 end
 ```
 
@@ -781,12 +736,7 @@ class PluginFormatter < ClaudeHooks::PostToolUse
   end
 end
 
-if __FILE__ == $0
-  input_data = JSON.parse(STDIN.read)
-  hook = PluginFormatter.new(input_data)
-  hook.call
-  hook.output_and_exit
-end
+ClaudeHooks::CLI.run_hook(PluginFormatter)
 ```
 
 **Environment variables available in plugins:**
@@ -822,7 +772,7 @@ You can use matchers to target specific MCP tools or all tools from a server:
         "hooks": [
           {
             "type": "command",
-            "command": "~/.claude/hooks/entrypoints/github_guard.rb"
+            "command": "~/.claude/hooks/github_guard.rb"
           }
         ]
       },
@@ -831,7 +781,7 @@ You can use matchers to target specific MCP tools or all tools from a server:
         "hooks": [
           {
             "type": "command",
-            "command": "~/.claude/hooks/entrypoints/destructive_operation_guard.rb"
+            "command": "~/.claude/hooks/destructive_operation_guard.rb"
           }
         ]
       }
@@ -867,124 +817,103 @@ See the [official MCP documentation](https://modelcontextprotocol.io/) for more
 
 ## ⚠️ Troubleshooting
 
-### Make your entrypoint scripts executable
+### Make your hook scripts executable
 
 Don't forget to make the scripts called from `settings.json` executable:
 
 ```bash
-chmod +x ~/.claude/hooks/entrypoints/user_prompt_submit.rb
+chmod +x ~/.claude/hooks/my_hook.rb
 ```
 
 
 ## 🧪 CLI Debugging
 
-The `ClaudeHooks::CLI` module provides utilities to simplify testing hooks in isolation. Instead of writing repetitive JSON parsing and error handling code, you can use the CLI test runner.
+`ClaudeHooks::CLI` provides two helpers: `run_hook` (for production use) and `test_runner`/`run_with_sample_data` (for local testing with custom input).
 
-### Basic Usage
+### CLI.run_hook
 
-Replace the traditional testing boilerplate:
+`CLI.run_hook` is what you put at the bottom of every simple hook script. It reads JSON from STDIN, runs your hook, handles errors, and calls `output_and_exit` with the right exit code.
 
 ```ruby
-# Old way (15+ lines of repetitive code)
-if __FILE__ == $0
-  begin
-    require 'json'
-    input_data = JSON.parse(STDIN.read)
-    hook = MyHook.new(input_data)
-    result = hook.call
-    puts JSON.generate(result)
-  rescue StandardError => e
-    STDERR.puts "Error: #{e.message}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "Error: #{e.message}",
-      suppressOutput: false
-    })
-    exit 1
-  end
-end
+# Single hook (most common)
+ClaudeHooks::CLI.run_hook(MyHook)
 ```
 
-With the simple CLI test runner:
+It replaces the more verbose
 
 ```ruby
-# New way (1 line!)
-if __FILE__ == $0
-  ClaudeHooks::CLI.test_runner(MyHook)
+begin
+  # Read input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  hook = MyHook.new(input_data)
+  hook.call
+  hook.output_and_exit
+rescue StandardError => e
+  # Non-blocking by default (fail-open): Claude continues as if the hook didn't run.
+  # Pass `on_error: :block` to CLI.run_hook to exit 2 (fail-closed) instead.
+  STDERR.puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 1
 end
 ```
 
-### Customization with Blocks
+#### on_error: fail-open vs fail-closed
 
-You can customize the input data for testing using blocks:
+By default, if your hook raises an unexpected exception, `CLI.run_hook` exits 1 (non-blocking) — Claude continues as if the hook didn't run. This is **fail-open**.
 
-```ruby
-if __FILE__ == $0
-  ClaudeHooks::CLI.test_runner(MyHook) do |input_data|
-    input_data['debug_mode'] = true
-    input_data['custom_field'] = 'test_value'
-    input_data['user_name'] = 'TestUser'
-  end
-end
-```
-
-### Testing Methods
+For security or policy hooks (`PreToolUse` guards, prompt filters, etc.) you almost certainly want **fail-closed** instead — a crash should block the action, not silently pass it through:
 
-#### 1. Test with STDIN (default)
 ```ruby
-ClaudeHooks::CLI.test_runner(MyHook)
-# Usage: echo '{"session_id":"test","prompt":"Hello"}' | ruby my_hook.rb
-```
+# Default: hook crash is non-blocking — Claude continues anyway (exit 1)
+ClaudeHooks::CLI.run_hook(MyHook)
 
-#### 2. Test with default sample data instead of STDIN
-```ruby
-ClaudeHooks::CLI.run_with_sample_data(MyHook, { 'prompt' => 'test prompt' })
-# Provides default values, no STDIN needed
-```
+# Fail-closed: hook crash blocks the action (exit 2)
+ClaudeHooks::CLI.run_hook(MyHook, on_error: :block)
 
-#### 3. Test with Sample Data + Customization
-```ruby
-ClaudeHooks::CLI.run_with_sample_data(MyHook) do |input_data|
-  input_data['prompt'] = 'Custom test prompt'
-  input_data['debug'] = true
+# Also works with block form
+ClaudeHooks::CLI.run_hook(on_error: :block) do |input_data|
+  # ...
 end
 ```
 
-### Example Hook with CLI Testing
-
-```ruby
-#!/usr/bin/env ruby
-
-require 'claude_hooks'
+> [!WARNING]
+> If you're writing a `PreToolUse` or `UserPromptSubmit` hook that enforces security policy, use `on_error: :block`. Without it, a Ruby exception (network timeout, nil reference, etc.) will silently allow the action through.
 
-class MyTestHook < ClaudeHooks::UserPromptSubmit
-  def call
-    log "Debug mode: #{input_data['debug_mode']}"
-    log "Processing: #{prompt}"
+### CLI.test_runner — local testing
 
-    if input_data['debug_mode']
-      log "All input keys: #{input_data.keys.join(', ')}"
-    end
+Use `test_runner` when running the script directly (outside of Claude Code) to inject custom input data:
 
-    output
+```ruby
+# At the bottom of your hook file, guarded so it only runs directly:
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(MyHook) do |input_data|
+    input_data['debug_mode'] = true
+    input_data['prompt'] = 'Test prompt'
   end
 end
 
-# Test runner with customization
+# Or test with synthetic data (no STDIN needed):
 if __FILE__ == $0
-  ClaudeHooks::CLI.test_runner(MyTestHook) do |input_data|
-    input_data['debug_mode'] = true
-  end
+  ClaudeHooks::CLI.run_with_sample_data(MyHook, { 'prompt' => 'test prompt' })
 end
 ```
 
+Test with real STDIN:
+```bash
+echo '{"session_id":"test","prompt":"Hello"}' | ruby my_hook.rb
+```
+
 ## 🐛 Debugging
 
-### Test an individual entrypoint
+### Test a hook script directly
 
 ```bash
 # Test with sample data
-echo '{"session_id": "test", "transcript_path": "/tmp/transcript", "cwd": "/tmp", "hook_event_name": "UserPromptSubmit", "user_prompt": "Hello Claude"}' | CLAUDE_PROJECT_DIR=$(pwd) ruby ~/.claude/hooks/entrypoints/user_prompt_submit.rb
+echo '{"session_id": "test", "transcript_path": "/tmp/transcript", "cwd": "/tmp", "hook_event_name": "UserPromptSubmit", "user_prompt": "Hello Claude"}' | CLAUDE_PROJECT_DIR=$(pwd) ruby ~/.claude/hooks/user_prompt_submit.rb
 ```
 
 ## 🧪 Development & Contributing

data/docs/1.0.0_MIGRATION_GUIDE.md

@@ -169,18 +169,17 @@ merged_output.output_and_exit  # Handles everything automatically
 
 ## Simplified Entrypoint Pattern
 
+> [!NOTE]
+> As of 1.2.1, `CLI.entrypoint` is deprecated in favour of `CLI.run_hook`. The examples below use the current API. `CLI.entrypoint` still works (with a deprecation warning) but will be removed in a future minor version.
+
 ### 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
+# Super simple - just 1 line!
+ClaudeHooks::CLI.run_hook(MyHook)
 ```
 
 ### For Multiple Hooks with Merging
@@ -190,7 +189,7 @@ require 'claude_hooks'
 require_relative '../handlers/hook1'
 require_relative '../handlers/hook2'
 
-ClaudeHooks::CLI.entrypoint do |input_data|
+ClaudeHooks::CLI.run_hook do |input_data|
   hook1 = Hook1.new(input_data)
   hook2 = Hook2.new(input_data)
   hook1.call

data/example_dotclaude/hooks/entrypoints/session_end.rb

@@ -1,35 +1,18 @@
 #!/usr/bin/env ruby
 
-require 'json'
+require 'claude_hooks'
 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
+ClaudeHooks::CLI.run_hook do |input_data|
   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(
+  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
+  ).output_and_exit
+end

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -1,40 +1,18 @@
 #!/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'
 
-begin
-  # Read input from stdin
-  input_data = JSON.parse(STDIN.read)
-
-  # Execute all hook scripts
+ClaudeHooks::CLI.run_hook do |input_data|
   append_rules = AppendRules.new(input_data)
   append_rules.call
 
   log_user_prompt = LogUserPrompt.new(input_data)
   log_user_prompt.call
 
-  merged_output = ClaudeHooks::Output::UserPromptSubmit.merge(
+  ClaudeHooks::Output::UserPromptSubmit.merge(
     append_rules.output,
     log_user_prompt.output
-  )
-
-  merged_output.output_and_exit
-
-rescue StandardError => e
-  # Same simple error pattern
-  STDERR.puts JSON.generate({
-    continue: false,
-    stopReason: "Hook execution error: #{e.message} #{e.backtrace.join("\n")}",
-    suppressOutput: false
-  })
-  exit 2
-end
+  ).output_and_exit
+end

data/example_dotclaude/hooks/{handlers/pre_tool_use/github_guard.rb → github_guard.rb}

@@ -238,16 +238,10 @@ class GithubGuard < ClaudeHooks::PreToolUse
   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
+# Registered directly in settings.json under PreToolUse. Claude Code runs this file
+# with the hook payload on STDIN. on_error: :block makes the guard fail-closed — a
+# crash blocks the tool instead of silently allowing it.
+#
+# Debug it by piping sample JSON:
+#   echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push --force"}}' | ruby github_guard.rb
+ClaudeHooks::CLI.run_hook(GithubGuard, on_error: :block)

data/example_dotclaude/settings.json

@@ -10,7 +10,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/entrypoints/pre_tool_use.rb"
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/github_guard.rb"
           }
         ]
       }

data/lib/claude_hooks/cli.rb

@@ -3,191 +3,126 @@
 require 'json'
 
 module ClaudeHooks
-  # CLI utility for testing hook handlers in isolation
-  # This module provides a standardized way to run hooks directly from the command line
-  # for testing and debugging purposes.
   module CLI
     class << self
-      # Run a hook class directly from command line
-      # Usage: 
-      #   ClaudeHooks::CLI.run_hook(YourHookClass)
-      #   ClaudeHooks::CLI.run_hook(YourHookClass, custom_input_data)
-      #   
-      #   # With customization block:
-      #   ClaudeHooks::CLI.run_hook(YourHookClass) do |input_data|
-      #     input_data['debug_mode'] = true
-      #   end
-      def run_hook(hook_class, input_data = nil, &block)
-        # If no input data provided, read from STDIN
-        input_data ||= read_stdin_input
-        
-        # Apply customization block if provided
+      # Run a hook script from the command line.
+      # Reads JSON from STDIN, calls hook.call, and exits with the correct code.
+      #
+      # on_error controls what happens when the hook raises an unexpected exception:
+      #   :allow (default) — exit 1, non-blocking; Claude continues as if the hook didn't run.
+      #   :block           — exit 2, blocking; Claude stops and shows the error. Use this for
+      #                      security/policy hooks where a crash should never silently pass through.
+      #
+      # Usage patterns:
+      #
+      # 1. Single hook class:
+      #    ClaudeHooks::CLI.run_hook(MyHook)
+      #    ClaudeHooks::CLI.run_hook(MyHook, on_error: :block)  # fail-closed
+      #
+      # 2. Multiple hooks with merging:
+      #    ClaudeHooks::CLI.run_hook(on_error: :block) do |input_data|
+      #      hook1 = Hook1.new(input_data)
+      #      hook2 = Hook2.new(input_data)
+      #      hook1.call
+      #      hook2.call
+      #      ClaudeHooks::Output::PreToolUse.merge(hook1.output, hook2.output).output_and_exit
+      #    end
+      def run_hook(hook_class = nil, on_error: :allow, &block)
+        input_data = JSON.parse(STDIN.read)
+
         if block_given?
           yield(input_data)
+        elsif hook_class
+          hook = hook_class.new(input_data)
+          hook.call
+          hook.output_and_exit
+        else
+          raise ArgumentError, "Either provide a hook_class or a block"
         end
-        
-        # Create and execute the hook
-        hook = hook_class.new(input_data)
-        result = hook.call
-        
-        # Output the result as JSON (same format as production hooks)
-        puts JSON.generate(result) if result
-        
-        result
+
+      rescue JSON::ParserError => e
+        handle_run_error("JSON parsing error: #{e.message}", on_error)
+
       rescue StandardError => e
-        handle_error(e, hook_class)
+        handle_run_error("Hook execution error: #{e.message}", on_error, backtrace: e.backtrace)
       end
 
-      # Create a test runner block for a hook class
-      # This generates the common if __FILE__ == $0 block content
-      # 
-      # Usage: 
-      #   ClaudeHooks::CLI.test_runner(YourHookClass)
-      #   
-      #   # With customization block:
-      #   ClaudeHooks::CLI.test_runner(YourHookClass) do |input_data|
-      #     input_data['custom_field'] = 'test_value'
-      #     input_data['user_name'] = 'TestUser'
-      #   end
+      # @deprecated Use {run_hook} instead.
+      def entrypoint(hook_class = nil, on_error: :allow, &block)
+        warn "[ClaudeHooks] CLI.entrypoint is deprecated — use CLI.run_hook instead."
+        run_hook(hook_class, on_error: on_error, &block)
+      end
+
+      # Testing helpers — use these inside `if __FILE__ == $0` blocks, not in production.
+
+      # Run a hook with input read from STDIN, with optional block to mutate input_data before running.
       def test_runner(hook_class, &block)
         input_data = read_stdin_input
-        
-        # Apply customization block if provided
-        if block_given?
-          yield(input_data)
-        end
-        
-        run_hook(hook_class, input_data)
+        yield(input_data) if block_given?
+        run_hook_with_data(hook_class, input_data)
       end
 
-      # Run hook with sample data (useful for development)
-      # Usage:
-      #   ClaudeHooks::CLI.run_with_sample_data(YourHookClass)
-      #   ClaudeHooks::CLI.run_with_sample_data(YourHookClass, { 'prompt' => 'test prompt' })
-      #   
-      #   # With customization block:
-      #   ClaudeHooks::CLI.run_with_sample_data(YourHookClass) do |input_data|
-      #     input_data['prompt'] = 'Custom test prompt'
-      #     input_data['debug'] = true
-      #   end
+      # Run a hook with synthetic sample data (no STDIN needed).
       def run_with_sample_data(hook_class, sample_data = {}, &block)
-        default_sample = {
+        input_data = {
           'session_id' => 'test-session',
           'transcript_path' => '/tmp/test_transcript.md',
           'cwd' => Dir.pwd,
           'hook_event_name' => hook_class.hook_type
-        }
+        }.merge(sample_data)
 
-        # Merge with hook-specific sample data
-        merged_data = default_sample.merge(sample_data)
-        
-        # Apply customization block if provided
-        if block_given?
-          yield(merged_data)
-        end
-        
-        run_hook(hook_class, merged_data)
+        yield(input_data) if block_given?
+        run_hook_with_data(hook_class, input_data)
       end
 
-      # Simplified entrypoint helper for hook scripts
-      # This handles all the STDIN reading, JSON parsing, error handling, and output execution
-      # 
-      # Usage patterns:
-      # 
-      # 1. Block form - custom logic:
-      #    ClaudeHooks::CLI.entrypoint do |input_data|
-      #      hook = MyHook.new(input_data)
-      #      hook.call
-      #      hook.output_and_exit
-      #    end
-      #
-      # 2. Simple form - single hook class:
-      #    ClaudeHooks::CLI.entrypoint(MyHook)
-      #
-      # 3. Multiple hooks with merging:
-      #    ClaudeHooks::CLI.entrypoint do |input_data|
-      #      hook1 = Hook1.new(input_data)
-      #      hook2 = Hook2.new(input_data)
-      #      result1 = hook1.call
-      #      result2 = hook2.call
-      #      
-      #      # Use the appropriate output class for merging
-      #      merged = ClaudeHooks::Output::PreToolUse.merge(
-      #        hook1.output,
-      #        hook2.output
-      #      )
-      #      merged.output_and_exit
-      #    end
-      def entrypoint(hook_class = nil, &block)
-        # Read and parse input from STDIN
-        input_data = JSON.parse(STDIN.read)
-        
-        if block_given?
-          # Custom block form
-          yield(input_data)
-        elsif hook_class
-          # Simple single hook form
-          hook = hook_class.new(input_data)
-          hook.call
-          hook.output_and_exit
-        else
-          raise ArgumentError, "Either provide a hook_class or a block"
-        end
-        
-      rescue JSON::ParserError => e
-        STDERR.puts "JSON parsing error: #{e.message}"
-        error_response = {
-          continue: false,
-          stopReason: "JSON parsing error: #{e.message}",
-          suppressOutput: false
-        }
-        response = JSON.generate(error_response)
-        puts response
-        STDERR.puts response
-        exit 1
-        
+      private
+
+      # Runs a hook with already-parsed input_data. Returns the result without exiting.
+      # Used internally by test_runner and run_with_sample_data.
+      def run_hook_with_data(hook_class, input_data)
+        hook = hook_class.new(input_data)
+        result = hook.call
+        puts JSON.generate(result) if result
+        result
       rescue StandardError => e
-        STDERR.puts "Hook execution error: #{e.message}"
+        hook_name = hook_class.name || hook_class.to_s
+        STDERR.puts "Error in #{hook_name} hook: #{e.message}"
         STDERR.puts e.backtrace.join("\n") if e.backtrace
-        
-        error_response = {
+        response = JSON.generate({
           continue: false,
-          stopReason: "Hook execution error: #{e.message}",
+          stopReason: "#{hook_name} execution error: #{e.message}",
           suppressOutput: false
-        }
-        response = JSON.generate(error_response)
+        })
         puts response
         STDERR.puts response
         exit 1
       end
 
-      private
+      def handle_run_error(message, on_error, backtrace: nil)
+        if on_error == :block
+          # Exit 2: Claude Code shows stderr to the model as plain text (never
+          # parsed as JSON), so emit just the message and block.
+          STDERR.puts message
+          exit 2
+        else
+          # Exit 1: non-blocking. stderr's first line surfaces in the transcript.
+          STDERR.puts backtrace.join("\n") if backtrace
+          STDERR.puts JSON.generate({
+            continue: false,
+            stopReason: message,
+            suppressOutput: false
+          })
+          exit 1
+        end
+      end
 
       def read_stdin_input
         stdin_content = STDIN.read.strip
         return {} if stdin_content.empty?
-        
         JSON.parse(stdin_content)
       rescue JSON::ParserError => e
         raise "Invalid JSON input: #{e.message}"
       end
-
-      def handle_error(error, hook_class)
-        STDERR.puts "Error in #{hook_class.name} hook: #{error.message}"
-        STDERR.puts error.backtrace.join("\n") if error.backtrace
-
-        # Output error response in Claude Code format
-        error_response = {
-          continue: false,
-          stopReason: "#{hook_class.name} execution error: #{error.message}",
-          suppressOutput: false
-        }
-
-        response = JSON.generate(error_response)
-        puts response
-        STDERR.puts response
-        exit 1
-      end
     end
   end
-end
+end

data/lib/claude_hooks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeHooks
-  VERSION = "1.2.0"
+  VERSION = "1.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_hooks
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Gabriel Dehan
@@ -64,7 +64,6 @@ files:
 - ".agents/skills/ci-monitoring/SKILL.md"
 - ".agents/skills/run-tests/SKILL.md"
 - ".claude/auto-fix.md"
-- ".claude/settings.local.json"
 - AGENTS.md
 - CHANGELOG.md
 - README.md
@@ -110,10 +109,9 @@ files:
 - docs/mitts/setup.md
 - docs/mitts/task.md
 - example_dotclaude/commands/.gitkeep
-- example_dotclaude/hooks/entrypoints/pre_tool_use.rb
 - example_dotclaude/hooks/entrypoints/session_end.rb
 - example_dotclaude/hooks/entrypoints/user_prompt_submit.rb
-- example_dotclaude/hooks/handlers/pre_tool_use/github_guard.rb
+- example_dotclaude/hooks/github_guard.rb
 - example_dotclaude/hooks/handlers/session_end/cleanup_handler.rb
 - example_dotclaude/hooks/handlers/session_end/log_session_stats.rb
 - example_dotclaude/hooks/handlers/user_prompt_submit/append_rules.rb

data/.claude/settings.local.json

@@ -1,21 +0,0 @@
-{
-  "env": {
-    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
-  },
-  "permissions": {
-    "allow": [
-      "Read(//Users/gdehan/**)",
-      "Read(//Users/gdehan/.config/**)",
-      "Bash(herdr --help)",
-      "Bash(herdr config *)",
-      "Bash(herdr api *)",
-      "Bash(python3 -m json.tool)",
-      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(list\\(d.keys\\(\\)\\)\\)\")",
-      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\(list\\(d.keys\\(\\)\\), indent=2\\)\\)\")",
-      "Bash(python3 -c ' *)",
-      "Bash(herdr server *)",
-      "WebFetch(domain:opencode.ai)",
-      "Bash(ruby *)"
-    ]
-  }
-}

data/example_dotclaude/hooks/entrypoints/pre_tool_use.rb

@@ -1,25 +0,0 @@
-#!/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