claude_hooks 1.1.0 → 1.2.1

data/README.md

@@ -1,7 +1,7 @@
 # Ruby DSL for Claude Code hooks
 
 > [!IMPORTANT]
-> v1.0.0 just released and is introducing breaking changes. Please read the [CHANGELOG](CHANGELOG.md) for more information.
+> v1.2.0 just released and is introducing a great number of changes. Please read the [CHANGELOG](CHANGELOG.md) for more information.
 
 
 A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will hopefully make creating and configuring new hooks way easier.
@@ -24,6 +24,7 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
   - [📝 Example: Tool usage monitor](#-example-tool-usage-monitor)
   - [🔄 Hook Output](#-hook-output)
   - [🔌 Plugin Hooks Support](#-plugin-hooks-support)
+  - [🛠️ MCP Tools Integration](#️-mcp-tools-integration)
   - [🚨 Advices](#-advices)
   - [⚠️ Troubleshooting](#️-troubleshooting)
   - [🧪 CLI Debugging](#-cli-debugging)
@@ -35,7 +36,11 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
 > [!TIP]
 > Examples are available in [`example_dotclaude/hooks/`](example_dotclaude/hooks/). The GithubGuard in particular is a good example of a solid hook. You can also check [Kyle's hooks for some great examples](https://github.com/kylesnowschwartz/dotfiles/blob/main/claude/hooks)
 
-Here's how to create a simple hook:
+Claude Code supports two types of hooks:
+- **Command hooks** (`type: "command"`) - Execute Ruby/bash scripts (what this DSL is for)
+- **Prompt-based hooks** (`type: "prompt"`) - Delegate decisions to an LLM ([see guide](docs/PROMPT_BASED_HOOKS.md))
+
+Here's how to create a simple command hook with this DSL:
 
 1. **Install the gem:**
 ```bash
@@ -45,10 +50,8 @@ Here's how to create a simple hook:
 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}"
@@ -57,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**
@@ -97,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
 
@@ -227,50 +219,83 @@ 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
+
+### 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/
+├── 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)
+```
 
-### Recommended structure for your .claude/hooks/ directory
+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/                # 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
-    └── ...
+├── 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:
 
 | Hook Type | Class | Description |
 |-----------|-------|-------------|
-| **[SessionStart](docs/API/SESSION_START.md)** | `ClaudeHooks::SessionStart` | Hooks that run when Claude Code starts a new session, resumes, or compacts |
-| **[UserPromptSubmit](docs/API/USER_PROMPT_SUBMIT.md)** | `ClaudeHooks::UserPromptSubmit` | Hooks that run before the user's prompt is processed |
-| **[Notification](docs/API/NOTIFICATION.md)** | `ClaudeHooks::Notification` | Hooks that run when Claude Code sends notifications |
-| **[PreToolUse](docs/API/PRE_TOOL_USE.md)** | `ClaudeHooks::PreToolUse` | Hooks that run before a tool is used |
-| **[PermissionRequest](docs/API/PERMISSION_REQUEST.md)** | `ClaudeHooks::PermissionRequest` | Hooks that run when Claude requests permission |
-| **[PostToolUse](docs/API/POST_TOOL_USE.md)** | `ClaudeHooks::PostToolUse` | Hooks that run after a tool is used |
-| **[Stop](docs/API/STOP.md)** | `ClaudeHooks::Stop` | Hooks that run when Claude Code finishes responding |
-| **[SubagentStop](docs/API/SUBAGENT_STOP.md)** | `ClaudeHooks::SubagentStop` | Hooks that run when subagent tasks complete |
-| **[SessionEnd](docs/API/SESSION_END.md)** | `ClaudeHooks::SessionEnd` | Hooks that run when Claude Code sessions end |
-| **[PreCompact](docs/API/PRE_COMPACT.md)** | `ClaudeHooks::PreCompact` | Hooks that run before transcript compaction |
+| **[SessionStart](docs/API/SESSION_START.md)** | `ClaudeHooks::SessionStart` | Runs when Claude Code starts, resumes, or compacts a session |
+| **[Setup](docs/API/SETUP.md)** | `ClaudeHooks::Setup` | Runs once on Claude Code startup before any session |
+| **[UserPromptSubmit](docs/API/USER_PROMPT_SUBMIT.md)** | `ClaudeHooks::UserPromptSubmit` | Runs before the user's prompt is processed |
+| **[UserPromptExpansion](docs/API/USER_PROMPT_EXPANSION.md)** | `ClaudeHooks::UserPromptExpansion` | Runs when a slash command or prompt expansion is triggered |
+| **[Notification](docs/API/NOTIFICATION.md)** | `ClaudeHooks::Notification` | Runs when Claude Code sends a notification |
+| **[MessageDisplay](docs/API/MESSAGE_DISPLAY.md)** | `ClaudeHooks::MessageDisplay` | Runs when a message is about to be displayed |
+| **[PreToolUse](docs/API/PRE_TOOL_USE.md)** | `ClaudeHooks::PreToolUse` | Runs before a tool is used; can allow, deny, defer or ask |
+| **[PermissionRequest](docs/API/PERMISSION_REQUEST.md)** | `ClaudeHooks::PermissionRequest` | Runs when Claude requests an explicit permission |
+| **[PermissionDenied](docs/API/PERMISSION_DENIED.md)** | `ClaudeHooks::PermissionDenied` | Runs when a permission request is denied; can request a retry |
+| **[PostToolUse](docs/API/POST_TOOL_USE.md)** | `ClaudeHooks::PostToolUse` | Runs after a tool is used; can rewrite output |
+| **[PostToolBatch](docs/API/POST_TOOL_BATCH.md)** | `ClaudeHooks::PostToolBatch` | Runs after a full batch of tool calls completes |
+| **[PostToolUseFailure](docs/API/POST_TOOL_USE_FAILURE.md)** | `ClaudeHooks::PostToolUseFailure` | Runs when a tool call fails |
+| **[Stop](docs/API/STOP.md)** | `ClaudeHooks::Stop` | Runs when Claude Code finishes responding; can force continuation |
+| **[StopFailure](docs/API/STOP_FAILURE.md)** | `ClaudeHooks::StopFailure` | Runs when the stop phase itself errors; logging only |
+| **[SubagentStart](docs/API/SUBAGENT_START.md)** | `ClaudeHooks::SubagentStart` | Runs when a subagent task starts |
+| **[SubagentStop](docs/API/SUBAGENT_STOP.md)** | `ClaudeHooks::SubagentStop` | Runs when a subagent task completes |
+| **[TaskCreated](docs/API/TASK_CREATED.md)** | `ClaudeHooks::TaskCreated` | Runs when a teammate task is created |
+| **[TaskCompleted](docs/API/TASK_COMPLETED.md)** | `ClaudeHooks::TaskCompleted` | Runs when a teammate task completes |
+| **[TeammateIdle](docs/API/TEAMMATE_IDLE.md)** | `ClaudeHooks::TeammateIdle` | Runs when a teammate goes idle |
+| **[PreCompact](docs/API/PRE_COMPACT.md)** | `ClaudeHooks::PreCompact` | Runs before transcript compaction; can block it |
+| **[PostCompact](docs/API/POST_COMPACT.md)** | `ClaudeHooks::PostCompact` | Runs after transcript compaction completes |
+| **[ConfigChange](docs/API/CONFIG_CHANGE.md)** | `ClaudeHooks::ConfigChange` | Runs when Claude Code configuration changes; can block it |
+| **[CwdChanged](docs/API/CWD_CHANGED.md)** | `ClaudeHooks::CwdChanged` | Runs when the working directory changes |
+| **[FileChanged](docs/API/FILE_CHANGED.md)** | `ClaudeHooks::FileChanged` | Runs when a watched file is created, modified, or deleted |
+| **[InstructionsLoaded](docs/API/INSTRUCTIONS_LOADED.md)** | `ClaudeHooks::InstructionsLoaded` | Runs when a CLAUDE.md instructions file is loaded |
+| **[Elicitation](docs/API/ELICITATION.md)** | `ClaudeHooks::Elicitation` | Runs when an MCP server requests user input |
+| **[ElicitationResult](docs/API/ELICITATION_RESULT.md)** | `ClaudeHooks::ElicitationResult` | Runs after an elicitation response is provided |
+| **[WorktreeCreate](docs/API/WORKTREE_CREATE.md)** | `ClaudeHooks::WorktreeCreate` | Runs when Claude Code creates a git worktree |
+| **[WorktreeRemove](docs/API/WORKTREE_REMOVE.md)** | `ClaudeHooks::WorktreeRemove` | Runs when a git worktree is removed |
+| **[SessionEnd](docs/API/SESSION_END.md)** | `ClaudeHooks::SessionEnd` | Runs when a Claude Code session ends |
 
 ## 🚀 Claude Hook Flow
 
@@ -289,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.
-
-### 🔄 Proposal: a more robust Claude Hook execution flow
-
-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
+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.
 
-  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 structure
 
-### 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
@@ -328,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.
@@ -388,16 +393,36 @@ The framework supports all existing hook types with their respective input field
 
 | Hook Type | Input Fields |
 |-----------|--------------|
-| **Common**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `permission_mode` |
+| **Common (all hooks)**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `permission_mode`, `prompt_id`, `agent_id`, `agent_type`, `effort` |
+| **SessionStart**  | `source`, `model`, `session_title` |
+| **Setup**  | `source` |
 | **UserPromptSubmit**  | `prompt` |
+| **UserPromptExpansion**  | `expansion_type`, `command_name`, `command_args`, `command_source`, `prompt` |
+| **Notification**  | `message`, `notification_type` |
+| **MessageDisplay**  | `turn_id`, `message_id`, `index`, `final`, `delta` |
 | **PreToolUse**  | `tool_name`, `tool_input`, `tool_use_id` |
-| **PermissionRequest**  | `tool_name`, `tool_input`, `tool_use_id` |
+| **PermissionRequest**  | `tool_name`, `tool_input`, `tool_use_id`, `permission_suggestions` |
+| **PermissionDenied**  | `tool_name`, `tool_input`, `tool_use_id`, `reason` |
 | **PostToolUse**  | `tool_name`, `tool_input`, `tool_response`, `tool_use_id` |
-| **Notification**  | `message`, `notification_type` |
-| **Stop**  | `stop_hook_active` |
-| **SubagentStop**  | `stop_hook_active` |
+| **PostToolBatch**  | `tool_calls` |
+| **PostToolUseFailure**  | `tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`, `duration_ms` |
+| **Stop**  | `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons` |
+| **StopFailure**  | `error`, `error_details`, `last_assistant_message` |
+| **SubagentStart**  | *(common only: `agent_id`, `agent_type`)* |
+| **SubagentStop**  | `stop_hook_active`, `agent_transcript_path` + common `agent_id`/`agent_type` |
+| **TaskCreated**  | `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` |
+| **TaskCompleted**  | `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` |
+| **TeammateIdle**  | `teammate_name`, `team_name` |
 | **PreCompact**  | `trigger`, `custom_instructions` |
-| **SessionStart**  | `source` |
+| **PostCompact**  | `trigger`, `compact_summary` |
+| **ConfigChange**  | `source`, `file_path` |
+| **CwdChanged**  | `old_cwd`, `new_cwd` |
+| **FileChanged**  | `file_path`, `event` |
+| **InstructionsLoaded**  | `file_path`, `load_reason` |
+| **Elicitation**  | `mcp_server_name`, `message`, `mode`, `url`, `elicitation_id`, `requested_schema` |
+| **ElicitationResult**  | `mcp_server_name`, `action`, `mode`, `elicitation_id`, `content` |
+| **WorktreeCreate**  | `name` |
+| **WorktreeRemove**  | `worktree_path` |
 | **SessionEnd**  | `reason` |
 
 ### Hooks API
@@ -405,15 +430,35 @@ The framework supports all existing hook types with their respective input field
 **All hook types** inherit from `ClaudeHooks::Base` and share a common API, as well as hook specific APIs.
 
 - [📚 Common API Methods](docs/API/COMMON.md)
-- [🔔 Notification Hooks](docs/API/NOTIFICATION.md)
 - [🚀 Session Start Hooks](docs/API/SESSION_START.md)
+- [⚙️ Setup Hooks](docs/API/SETUP.md)
 - [🖋️ User Prompt Submit Hooks](docs/API/USER_PROMPT_SUBMIT.md)
+- [🔀 User Prompt Expansion Hooks](docs/API/USER_PROMPT_EXPANSION.md)
+- [🔔 Notification Hooks](docs/API/NOTIFICATION.md)
+- [💬 Message Display Hooks](docs/API/MESSAGE_DISPLAY.md)
 - [🛠️ Pre-Tool Use Hooks](docs/API/PRE_TOOL_USE.md)
 - [🔐 Permission Request Hooks](docs/API/PERMISSION_REQUEST.md)
+- [🚫 Permission Denied Hooks](docs/API/PERMISSION_DENIED.md)
 - [🔧 Post-Tool Use Hooks](docs/API/POST_TOOL_USE.md)
-- [📝 Pre-Compact Hooks](docs/API/PRE_COMPACT.md)
+- [📦 Post-Tool Batch Hooks](docs/API/POST_TOOL_BATCH.md)
+- [❌ Post-Tool Use Failure Hooks](docs/API/POST_TOOL_USE_FAILURE.md)
 - [⏹️ Stop Hooks](docs/API/STOP.md)
+- [💥 Stop Failure Hooks](docs/API/STOP_FAILURE.md)
+- [▶️ Subagent Start Hooks](docs/API/SUBAGENT_START.md)
 - [⏹️ Subagent Stop Hooks](docs/API/SUBAGENT_STOP.md)
+- [✅ Task Created Hooks](docs/API/TASK_CREATED.md)
+- [✅ Task Completed Hooks](docs/API/TASK_COMPLETED.md)
+- [💤 Teammate Idle Hooks](docs/API/TEAMMATE_IDLE.md)
+- [📝 Pre-Compact Hooks](docs/API/PRE_COMPACT.md)
+- [📄 Post-Compact Hooks](docs/API/POST_COMPACT.md)
+- [🔩 Config Change Hooks](docs/API/CONFIG_CHANGE.md)
+- [📂 Cwd Changed Hooks](docs/API/CWD_CHANGED.md)
+- [📄 File Changed Hooks](docs/API/FILE_CHANGED.md)
+- [📋 Instructions Loaded Hooks](docs/API/INSTRUCTIONS_LOADED.md)
+- [💬 Elicitation Hooks](docs/API/ELICITATION.md)
+- [💬 Elicitation Result Hooks](docs/API/ELICITATION_RESULT.md)
+- [🌳 Worktree Create Hooks](docs/API/WORKTREE_CREATE.md)
+- [🗑️ Worktree Remove Hooks](docs/API/WORKTREE_REMOVE.md)
 - [🔚 Session End Hooks](docs/API/SESSION_END.md)
 
 ### 📝 Logging
@@ -457,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": {
@@ -467,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"
         }
       ]
     }
@@ -475,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
@@ -527,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
@@ -555,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
@@ -594,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
 ```
 
@@ -625,6 +645,13 @@ Claude Code hooks support multiple exit codes with different behaviors depending
 | SessionStart     | Operation continues<br/><br />**`STDOUT` added as context to Claude**       | Non-blocking error<br/><br />`STDERR` shown to user                | N/A<br/><br />`STDERR` shown to user only                                   |
 | SessionEnd       | Operation continues<br/><br />Logged to debug only (`--debug`) | Non-blocking error<br/><br />Logged to debug only (`--debug`)                | N/A<br/><br />Logged to debug only (`--debug`)                                   |
 
+> [!NOTE]
+> The 20 events added in `1.2.0` follow the same families. Their per-event exit-code behavior is documented on each API page under [`docs/API/`](docs/API/):
+> - **Blocking via top-level `decision`** (behave like `PreToolUse`/`Stop`): `UserPromptExpansion`, `PostToolBatch`, `ConfigChange`.
+> - **Blocking via `exit 2` / `continue: false`** (no `decision` field): `TaskCreated`, `TaskCompleted`, `TeammateIdle`.
+> - **JSON-API special** (always `exit 0`, decision in `hookSpecificOutput`): `PermissionDenied`, `Elicitation`, `ElicitationResult`, `WorktreeCreate` (bare-path stdout).
+> - **Non-blocking / context-only** (exit code effectively ignored): `Setup`, `SubagentStart`, `PostToolUseFailure`, `StopFailure`, `PostCompact`, `CwdChanged`, `FileChanged`, `InstructionsLoaded`, `WorktreeRemove`, `MessageDisplay`.
+
 
 #### Manually outputing and exiting example with success
 For the operation to continue for a `UserPromptSubmit` hook, you would `STDOUT.puts` structured JSON data followed by `exit 0`:
@@ -709,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:**
@@ -722,7 +744,70 @@ end
 - `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)
 - All standard environment variables and configuration options work the same way
 
-See the [plugin components reference](https://docs.claude.com/en/docs/claude-code/plugins-reference#hooks) for more details on creating plugin hooks.
+See the [plugin components reference](https://code.claude.com/docs/en/plugins-reference#hooks) for more details on creating plugin hooks.
+
+## 🛠️ MCP Tools Integration
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools can be used with Claude Code hooks. When MCP servers are configured, their tools become available and can be intercepted by hooks just like built-in tools.
+
+### MCP Tool Naming Convention
+
+MCP tools follow a specific naming pattern: `mcp__<server-name>__<tool-name>`
+
+**Example MCP tool names:**
+- `mcp__filesystem__read_file`
+- `mcp__github__create_issue`
+- `mcp__database__query`
+
+### Configuring Hooks for MCP Tools
+
+You can use matchers to target specific MCP tools or all tools from a server:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__github__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/github_guard.rb"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*__create.*|mcp__.*__delete.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/destructive_operation_guard.rb"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Common MCP Tool Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `mcp__*__*` | All MCP tools from all servers |
+| `mcp__github__*` | All tools from the github server |
+| `mcp__*__read*` | All read operations from any server |
+| `mcp__.*__create.*\|mcp__.*__delete.*` | All create/delete operations |
+
+### Best Practices for MCP Tools
+
+1. **Use regex matchers** - MCP tool names are predictable, making regex patterns very effective
+2. **Guard destructive operations** - Always review create/delete/update operations
+3. **Server-specific rules** - Different MCP servers may need different security policies
+4. **Log MCP tool usage** - Track which external tools are being used
+5. **Test with your MCP servers** - Tool names vary by server implementation
+
+See the [official MCP documentation](https://modelcontextprotocol.io/) for more information about MCP servers and tools.
 
 ## 🚨 Advices
 
@@ -732,124 +817,103 @@ See the [plugin components reference](https://docs.claude.com/en/docs/claude-cod
 
 ## ⚠️ 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
-```
+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:
 
-### Testing Methods
-
-#### 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
+> [!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.
 
-require 'claude_hooks'
+### CLI.test_runner — local testing
 
-class MyTestHook < ClaudeHooks::UserPromptSubmit
-  def call
-    log "Debug mode: #{input_data['debug_mode']}"
-    log "Processing: #{prompt}"
+Use `test_runner` when running the script directly (outside of Claude Code) to inject custom input data:
 
-    if input_data['debug_mode']
-      log "All input keys: #{input_data.keys.join(', ')}"
-    end
-
-    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