claude_hooks 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbd6349008b693bddb770b79ac5883a746c826a800ed7141f4de466bd88025e0
-  data.tar.gz: b7a724ed1655ecb7c4af3393619e5dd800b0b59a08721c6d4b7279c4d31a185d
+  metadata.gz: d82c5deaa5426bc2ca898300f7772fa58c56a2998fd00af4eb1a93de25d3336e
+  data.tar.gz: ffde711d996ad0f43f7f75a3002f5a1e74e84f28ed2197ddf9c53c8b982a5152
 SHA512:
-  metadata.gz: a1596119ed1ee346ed133a76a0991cc64f8be594905e96e6b056e6e5187be91ca43ffd4c28c3e822725b5ee4bdb0bdbc03aa0cea38c06a5813b94c3a381ff0c3
-  data.tar.gz: 6063e35f39ffabd8eaf78e9deccd009e56f9103c86f69dedb6a2ed66b97cc9a8606d0aafb6ee2467d6fa29536031f4d0d671ff20e466c672009d16e2c2a962ea
+  metadata.gz: 8256eeed53e717873271ea94b9d85610e741ade7d6009b41a9df6eccc8ea58ec4af3b4ab8883d8dfba3d0ef849afdcae6939786d7cb7ad4d000dd7dc749a73ab
+  data.tar.gz: 306144f71bd099d70df514ee21eb9e63a11389562322927465b1aecff447c78eaafc602aa973db8a925bf0885c4e212fbcbfacb410c6d34c30a7b56eb9e51145

data/CHANGELOG.md

@@ -5,11 +5,56 @@ 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.0.2] - 2026-01-04
+
+### Fixed
+
+- **Critical: Fixed hook output contract for JSON API** - Stop, PostToolUse, UserPromptSubmit, and PreToolUse hooks now correctly use stdout + exit 0 when outputting structured JSON
+  - Stop hooks now output to stdout with exit 0 instead of stderr with exit 2 (PR #15, fixes #11)
+  - PostToolUse hooks now use stdout + exit 0 for JSON API consistency
+  - UserPromptSubmit hooks now use stdout + exit 0 for JSON API consistency
+  - PreToolUse hooks now use exit 0 for all permission decisions (previously varied: 0 for allow, 1 for ask, 2 for deny)
+  - This aligns with Anthropic's official guidance: when using advanced JSON API with decision/reason fields, hooks must output to stdout with exit 0
+  - **Breaking behavior fixed**: Plugin hooks with `continue_with_instructions!` now work correctly
+  - Reference: https://github.com/anthropics/claude-code/issues/10875
+  - Reference: https://github.com/gabriel-dehan/claude_hooks/issues/11
+
+### Notes
+
+- All tests updated and passing (147 runs, 262 assertions, 0 failures)
+- This fix ensures compatibility with Claude Code's plugin system
+- The exit code 2 + stderr approach is only for simple text output without JSON structure
+
+## [1.0.1] - 2025-10-13
+
+### Documentation
+
+- **Added comprehensive plugin hooks documentation** - Full guide on using the Claude Hooks DSL with Claude Code plugins
+  - New "Plugin Hooks Support" section in README with working examples
+  - Created `example_dotclaude/plugins/README.md` with complete plugin development guide
+  - Example plugin formatter implementation using the DSL
+  - Environment variables documentation for plugin development
+  - Best practices and testing instructions for plugin hooks
+- **Updated SessionStart hook documentation** - Added the new `compact` matcher introduced in official Claude Hooks documentation
+  - Updated `docs/API/SESSION_START.md` to include `'compact'` as a valid source value
+  - Updated SessionStart hook type description to mention compact functionality
+- **Synchronized with official documentation** - All documentation now matches the official Claude Hooks reference as of 2025-10-13
+  - Plugin hooks feature (Issue #9)
+  - SessionStart `compact` matcher (Issue #2)
+
+### Notes
+
+- No code changes required - the implementation already supports all documented features
+- The DSL's dynamic implementation handles the new `compact` source automatically
+- Plugin environment variables (`CLAUDE_PLUGIN_ROOT`) work seamlessly with existing configuration system
+
 ## [1.0.0] - 2025-08-27
 
 > [!WARNING]
 > These changes are not backward compatible (hence the version bump to 1.0.0), the API has changed too much.
 
+Follow the [migration guide](docs/1.0.0_MIGRATION_GUIDE.md) to migrate to the new API.
+
 ### Changed
 
 #### Revamped documentation
@@ -57,13 +102,13 @@ begin
   input_data = JSON.parse(STDIN.read)
   hook = MyHook.new(input_data)
   result = hook.call
-  
+
   # Manual stream and exit code selection
   if result['continue'] != false
     if result.dig('hookSpecificOutput', 'permissionDecision') == 'deny'
       STDERR.puts hook.stringify_output
       exit 1
-    elsif result.dig('hookSpecificOutput', 'permissionDecision') == 'ask'  
+    elsif result.dig('hookSpecificOutput', 'permissionDecision') == 'ask'
       STDERR.puts hook.stringify_output
       exit 2
     else
@@ -89,9 +134,9 @@ begin
   input_data = JSON.parse(STDIN.read)
   hook = MyHook.new(input_data)
   hook.call
-  
+
   # Handles everything automatically!
-  hook.output_and_exit  
+  hook.output_and_exit
 rescue StandardError => e
   # Error handling...
 end

data/README.md

@@ -1,11 +1,16 @@
 # 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.
+
+
 A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will hopefully make creating and configuring new hooks way easier.
 
 [**Why use this instead of writing bash, or simple ruby scripts?**](docs/WHY.md)
 
 > You might also be interested in my other project, a [Claude Code statusline](https://github.com/gabriel-dehan/claude_monitor_statusline) that shows your Claude usage in realtime, inside Claude Code ✨.
 
+
 ## 📖 Table of Contents
 
 - [Ruby DSL for Claude Code hooks](#ruby-dsl-for-claude-code-hooks)
@@ -18,6 +23,7 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
   - [📚 API Reference](#-api-reference)
   - [📝 Example: Tool usage monitor](#-example-tool-usage-monitor)
   - [🔄 Hook Output](#-hook-output)
+  - [🔌 Plugin Hooks Support](#-plugin-hooks-support)
   - [🚨 Advices](#-advices)
   - [⚠️ Troubleshooting](#️-troubleshooting)
   - [🧪 CLI Debugging](#-cli-debugging)
@@ -27,7 +33,7 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
 ## 🚀 Quick Start
 
 > [!TIP]
-> An example is available in [`example_dotclaude/hooks/`](example_dotclaude/hooks/)
+> 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:
 
@@ -58,7 +64,7 @@ if __FILE__ == $0
 
   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
@@ -255,7 +261,7 @@ 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 or resumes |
+| **[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 |
@@ -269,7 +275,7 @@ The framework supports the following hook types:
 
 ### A very simplified view of how a hook works in Claude Code
 
-Claude Code hooks in essence work in a very simple way: 
+Claude Code hooks in essence work in a very simple way:
 - Claude Code passes data to the hook script through `STDIN`
 - The hook uses the data to do its thing
 - The hook outputs data to `STDOUT` or `STDERR` and then `exit`s with the proper code:
@@ -342,7 +348,7 @@ class AddContextAfterPrompt < ClaudeHooks::UserPromptSubmit
       log "Prompt blocked: #{current_prompt} because of bad word"
     end
 
-    # Return output if you need it 
+    # Return output if you need it
     output
   end
 end
@@ -355,7 +361,7 @@ if __FILE__ == $0
   hook = AddContextAfterPrompt.new(input_data)
   # Call the hook
   hook.call
-  
+
   # 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
@@ -535,9 +541,9 @@ end
 
 Hooks provide access to their output (which acts as the "state" of a hook) through the `output` method.
 
-This method will return an output object based on the hook's type class (e.g: `ClaudeHooks::Output::UserPromptSubmit`) that provides helper methods: 
+This method will return an output object based on the hook's type class (e.g: `ClaudeHooks::Output::UserPromptSubmit`) that provides helper methods:
 - to access output data
-- for merging multiple outputs 
+- for merging multiple outputs
 - for sending the right exit codes and output data back to Claude Code through the proper stream.
 
 > [!TIP]
@@ -547,7 +553,7 @@ 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. 
+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**.
 
 ```ruby
@@ -579,12 +585,12 @@ begin
   # - additionalContext: concatenated
   merged_output = ClaudeHooks::Output::UserPromptSubmit.merge(
     hook1.output,
-    hook2.output, 
+    hook2.output,
     hook3.output
   )
 
   # 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 
+  merged_output.output_and_exit
 end
 ```
 
@@ -648,6 +654,73 @@ exit 2
 > [!WARNING]
 > You don't have to manually do this, just use `output_and_exit` to automatically handle this.
 
+## 🔌 Plugin Hooks Support
+
+This DSL works seamlessly with [Claude Code plugins](https://docs.claude.com/en/docs/claude-code/plugins)! When creating plugin hooks, you can use the exact same Ruby DSL and enjoy all the same benefits.
+
+**How plugin hooks work:**
+- Plugin hooks are defined in the plugin's `hooks/hooks.json` file
+- They use the `${CLAUDE_PLUGIN_ROOT}` environment variable to reference plugin files
+- Plugin hooks are automatically merged with user and project hooks when plugins are enabled
+- Multiple hooks from different sources can respond to the same event
+
+**Example plugin hook configuration (`hooks/hooks.json`):**
+```json
+{
+  "description": "Automatic code formatting",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/formatter.rb",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Using this DSL in your plugin hooks (`hooks/scripts/formatter.rb`):**
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class PluginFormatter < ClaudeHooks::PostToolUse
+  def call
+    log "Plugin executing from: #{ENV['CLAUDE_PLUGIN_ROOT']}"
+
+    if tool_name.match?(/Write|Edit/)
+      file_path = tool_input['file_path']
+      log "Formatting file: #{file_path}"
+
+      # Your formatting logic here
+      # Can use all the DSL helper methods!
+    end
+
+    output
+  end
+end
+
+if __FILE__ == $0
+  input_data = JSON.parse(STDIN.read)
+  hook = PluginFormatter.new(input_data)
+  hook.call
+  hook.output_and_exit
+end
+```
+
+**Environment variables available in plugins:**
+- `${CLAUDE_PLUGIN_ROOT}`: Absolute path to the plugin directory
+- `${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.
+
 ## 🚨 Advices
 
 1. **Logging**: Use `log()` method instead of `puts` to avoid interfering with Claude Code's expected output.

data/docs/{OUTPUT_MIGRATION_GUIDE.md → 1.0.0_MIGRATION_GUIDE.md}

@@ -1,6 +1,6 @@
-# Migration Guide: Using Output Objects
+# Migration Guide: 1.0.0
 
-This guide shows how to migrate from the old manual exit code patterns to the new simplified output object system.
+This guide shows how to migrate from the old manual exit code patterns to the new simplified way introduced in v1.0.0.
 
 ## Problem: The Old Way (Before)
 
@@ -46,12 +46,12 @@ rescue StandardError => e
     stopReason: "PreToolUser Hook execution error: #{e.message}",
     suppressOutput: false
   })
-  exit 0 # Allow anyway to not block developers if there is an issue
+  exit 1 # Allow anyway to not block developers if there is an issue
 end
 ```
 
 **Problems with this approach:**
-- 30+ lines of repetitive boilerplate
+- A lot of lines of repetitive boilerplate
 - Need to understand Claude Code's internal exit code semantics
 - Manual stream selection (STDOUT vs STDERR)
 - Error-prone - easy to get exit codes wrong
@@ -77,20 +77,21 @@ begin
 
 rescue StandardError => e
   # NEW: Simple error handling
-  error_output = ClaudeHooks::Output::PreToolUse.new({
-    'continue' => false,
-    'stopReason' => "Hook execution error: #{e.message}",
-    'suppressOutput' => false
+  STDERR.puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message}",
+    suppressOutput: false
   })
-  error_output.output_and_exit  # Automatically uses STDERR and exit 1
+  # Non-blocking error
+  exit 1
 end
 ```
 
 **Benefits:**
-- **10 lines instead of 30+** - 70% less code
+- **More concise+** - 70% less boilerplate code
 - **No Claude Code knowledge needed** - just use the gem's API
 - **Automatic exit codes** based on hook-specific logic
-- **Automatic stream selection** (STDOUT/STDERR)
+- **Automatic stream selection** (STDOUT/STDERR). Note: `PreToolUse` always outputs to STDOUT.
 - **Type-safe access** to hook-specific fields
 
 ## New Output Object API
@@ -143,7 +144,7 @@ output = hook.output
 puts "Should continue? #{output.should_continue?}"      # true if decision == 'block'
 puts "Continue instructions: #{output.continue_instructions}"
 
-hook.output_and_exit  # exit 1 for "continue", exit 0 for "stop"
+hook.output_and_exit  # exit 2 for "continue", exit 0 for "stop"
 ```
 
 ## Merging Multiple Hooks
@@ -213,16 +214,15 @@ end
 - `ClaudeHooks::Output::SubagentStop`
 - `ClaudeHooks::Output::Notification`
 - `ClaudeHooks::Output::SessionStart`
+- `ClaudeHooks::Output::SessionEnd`
 - `ClaudeHooks::Output::PreCompact`
 
 Each handles the specific exit code logic and semantic helpers for its hook type.
 
 ## Migration Steps
 
-1. **Update your hook handlers** to return `output_data` (most already do)
-2. **Replace manual exit logic** with `hook.output_and_exit` or `output.output_and_exit`
+1. **Update your hook handlers** to return ``output` instead of `output_data`
+2. **Replace manual exit logic** with `hook.output_and_exit` or `merged_output.output_and_exit`
 3. **Use semantic helpers** instead of digging through hash structures
-4. **Use output object merging** instead of class methods
-5. **Enjoy the simplified, cleaner code!**
+4. **Use output object classes for merging** instead of hook class methods
 
-The old patterns still work for backward compatibility, but the new output objects make everything much cleaner and less error-prone.

data/docs/API/SESSION_START.md

@@ -9,7 +9,7 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 
 | Method | Description |
 |--------|-------------|
-| `source` | Get the session start source: `'startup'`, `'resume'`, or `'clear'` |
+| `source` | Get the session start source: `'startup'`, `'resume'`, `'clear'`, or `'compact'` |
 
 ## Hook State Helpers
 Hook state methods are helpers to modify the hook's internal state (`output_data`) before yielding back to Claude Code.

data/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/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/user_prompt_submit/append_rules.rb

@@ -2,7 +2,8 @@
 
 require 'claude_hooks'
 
-# Hook script that appends rules to user prompt
+# Hook script that appends rules to user prompt as additional context.
+# A great way to make sure specific context is added with each user prompt.
 class AppendRules < ClaudeHooks::UserPromptSubmit
 
   def call

data/example_dotclaude/plugins/README.md

@@ -0,0 +1,175 @@
+# Plugin Hooks Examples
+
+This directory demonstrates how to use the Claude Hooks Ruby DSL when creating plugin hooks for [Claude Code plugins](https://docs.claude.com/en/docs/claude-code/plugins).
+
+## Overview
+
+The Claude Hooks DSL works seamlessly with plugin development! When creating plugins, you can use the exact same Ruby DSL as you would for regular hooks. The only difference is that plugin hooks are referenced through `${CLAUDE_PLUGIN_ROOT}` in the plugin's `hooks/hooks.json` configuration file.
+
+## Benefits of Using This DSL in Plugins
+
+- ✨ **Same powerful abstractions** - All the helper methods, logging, and state management work identically
+- 🔄 **Automatic output handling** - `output_and_exit` manages streams and exit codes correctly
+- 📝 **Built-in logging** - Session-specific logs work out of the box
+- 🛠️ **Configuration access** - Access both plugin and project configurations
+- 🎯 **Type safety** - Strong typed hook classes for each event type
+
+## Example Plugin Structure
+
+```
+my-formatter-plugin/
+├── .claude-plugin/
+│   └── plugin.json           # Plugin metadata
+├── hooks/
+│   ├── hooks.json            # Hook configuration (references scripts)
+│   └── scripts/
+│       └── formatter.rb      # Hook script using ClaudeHooks DSL
+└── README.md
+```
+
+## Example: Code Formatter Plugin
+
+### Plugin Configuration (`hooks/hooks.json`)
+
+```json
+{
+  "description": "Automatic code formatting on file writes",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/formatter.rb",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook Script (`hooks/scripts/formatter.rb`)
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class PluginFormatter < ClaudeHooks::PostToolUse
+  def call
+    log "Plugin formatter executing from: #{ENV['CLAUDE_PLUGIN_ROOT']}"
+
+    # Only format code files
+    file_path = tool_input['file_path']
+    return output unless should_format?(file_path)
+
+    log "Formatting file: #{file_path}"
+
+    # Perform formatting (example)
+    if format_file(file_path)
+      add_additional_context!("File formatted successfully: #{file_path}")
+    else
+      log "Failed to format #{file_path}", level: :warn
+    end
+
+    output
+  end
+
+  private
+
+  def should_format?(file_path)
+    # Example: only format Ruby files
+    file_path.end_with?('.rb')
+  end
+
+  def format_file(file_path)
+    # Your formatting logic here
+    # For example, using rubocop or prettier
+    return true  # Simulated success
+  end
+end
+
+if __FILE__ == $0
+  input_data = JSON.parse(STDIN.read)
+  hook = PluginFormatter.new(input_data)
+  hook.call
+  hook.output_and_exit
+end
+```
+
+## Environment Variables in Plugins
+
+When your hook scripts run as part of a plugin, these environment variables are available:
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_PLUGIN_ROOT` | Absolute path to the plugin directory |
+| `CLAUDE_PROJECT_DIR` | Project root directory (where Claude Code was started) |
+| `RUBY_CLAUDE_HOOKS_*` | All standard configuration environment variables |
+
+### Accessing Plugin Root in Your Hooks
+
+```ruby
+class MyPluginHook < ClaudeHooks::PreToolUse
+  def call
+    # Access plugin root
+    plugin_root = ENV['CLAUDE_PLUGIN_ROOT']
+    log "Plugin root: #{plugin_root}"
+
+    # Load plugin-specific config files
+    plugin_config_path = File.join(plugin_root, 'config', 'settings.json')
+
+    # Your hook logic here
+    output
+  end
+end
+```
+
+## Best Practices for Plugin Hooks
+
+1. **Keep hooks focused** - Each hook should have a single, well-defined purpose
+2. **Use logging extensively** - Helps users debug plugin behavior
+3. **Handle errors gracefully** - Don't crash on unexpected input
+4. **Document environment requirements** - If your plugin needs external tools (rubocop, prettier, etc.)
+5. **Test thoroughly** - Test with various file types and scenarios
+
+## Testing Plugin Hooks Locally
+
+You can test your plugin hooks before publishing:
+
+```bash
+# Test the hook script directly
+echo '{"session_id":"test","transcript_path":"/tmp/test","cwd":"/tmp","hook_event_name":"PostToolUse","tool_name":"Write","tool_input":{"file_path":"test.rb"},"tool_response":{"success":true}}' | CLAUDE_PLUGIN_ROOT=/path/to/plugin ruby hooks/scripts/formatter.rb
+```
+
+Or use the CLI test runner:
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class PluginFormatter < ClaudeHooks::PostToolUse
+  # ... your implementation ...
+end
+
+if __FILE__ == $0
+  ClaudeHooks::CLI.run_with_sample_data(PluginFormatter) do |input_data|
+    input_data['tool_name'] = 'Write'
+    input_data['tool_input'] = { 'file_path' => 'test.rb' }
+    input_data['tool_response'] = { 'success' => true }
+  end
+end
+```
+
+## Resources
+
+- [Official Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
+- [Plugin Components Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference#hooks)
+- [Hooks API Reference](../../docs/API/)
+- [Claude Hooks Main README](../../README.md)
+
+## Contributing Examples
+
+If you create a plugin using this DSL, consider contributing an example! Open a PR or issue on the [claude_hooks repository](https://github.com/gabriel-dehan/claude_hooks).

data/example_dotclaude/settings.json

@@ -4,6 +4,17 @@
     "allow": []
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/entrypoints/pre_tool_use.rb"
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "matcher": "",

data/lib/claude_hooks/output/post_tool_use.rb

@@ -26,21 +26,29 @@ module ClaudeHooks
       end
 
       # === EXIT CODE LOGIC ===
-
+      #
+      # PostToolUse hooks use the advanced JSON API with exit code 0.
+      # Per Anthropic guidance: when using structured JSON with decision/reason fields,
+      # always output to stdout with exit 0 (not stderr with exit 2).
+      # Reference: https://github.com/anthropics/claude-code/issues/10875
       def exit_code
-        return 2 unless continue?
-        return 2 if blocked?
-
         0
       end
 
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # PostToolUse hooks always output to stdout when using the JSON API.
+      def output_stream
+        :stdout
+      end
+
       # === MERGE HELPER ===
 
       def self.merge(*outputs)
         compacted_outputs = outputs.compact
         return compacted_outputs.first if compacted_outputs.length == 1
         return super(*outputs) if compacted_outputs.empty?
-        
+
         merged = super(*outputs)
         merged_data = merged.data
         contexts = []
@@ -65,4 +73,4 @@ module ClaudeHooks
       end
     end
   end
-end
+end

data/lib/claude_hooks/output/pre_tool_use.rb

@@ -24,29 +24,26 @@ module ClaudeHooks
       def denied?
         permission_decision == 'deny'
       end
-      alias_method :blocked?, :denied?
+      alias blocked? denied?
 
       def should_ask_permission?
         permission_decision == 'ask'
       end
 
       # === EXIT CODE LOGIC ===
-
-      # Priority: continue false > permission decision
+      #
+      # PreToolUse hooks use the advanced JSON API with exit code 0.
+      # Per Anthropic guidance: when using structured JSON with permissionDecision,
+      # always output to stdout with exit 0 (not stderr with exit 2).
+      # The permissionDecision field ('allow', 'deny', 'ask') controls behavior.
+      # Reference: https://github.com/anthropics/claude-code/issues/10875
       def exit_code
-        return 2 unless continue?
-
-        case permission_decision
-        when 'deny'
-          2 
-        when 'ask'
-          1 
-        else # allow 
-          0 
-        end
+        0
       end
 
-      # STDOUT always works for PreToolUse
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # PreToolUse hooks always output to stdout when using the JSON API.
       def output_stream
         :stdout
       end
@@ -57,7 +54,7 @@ module ClaudeHooks
         compacted_outputs = outputs.compact
         return compacted_outputs.first if compacted_outputs.length == 1
         return super(*outputs) if compacted_outputs.empty?
-        
+
         merged = super(*outputs)
         merged_data = merged.data
 
@@ -67,31 +64,31 @@ module ClaudeHooks
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
-          
-          if output_data.dig('hookSpecificOutput', 'permissionDecision')
-            current_decision = output_data['hookSpecificOutput']['permissionDecision']
-            case current_decision
-            when 'deny'
-              permission_decision = 'deny'
-            when 'ask'
-              permission_decision = 'ask' unless permission_decision == 'deny'
-            end
-
-            reason = output_data.dig('hookSpecificOutput', 'permissionDecisionReason')
-            permission_reasons << reason if reason && !reason.empty?
+
+          next unless output_data.dig('hookSpecificOutput', 'permissionDecision')
+
+          current_decision = output_data['hookSpecificOutput']['permissionDecision']
+          case current_decision
+          when 'deny'
+            permission_decision = 'deny'
+          when 'ask'
+            permission_decision = 'ask' unless permission_decision == 'deny'
           end
+
+          reason = output_data.dig('hookSpecificOutput', 'permissionDecisionReason')
+          permission_reasons << reason if reason && !reason.empty?
         end
 
         merged_data['hookSpecificOutput'] ||= { 'hookEventName' => 'PreToolUse' }
         merged_data['hookSpecificOutput']['permissionDecision'] = permission_decision
-        if permission_reasons.any?
-          merged_data['hookSpecificOutput']['permissionDecisionReason'] = permission_reasons.join('; ')
-        else
-          merged_data['hookSpecificOutput']['permissionDecisionReason'] = ''
-        end
+        merged_data['hookSpecificOutput']['permissionDecisionReason'] = if permission_reasons.any?
+                                                                          permission_reasons.join('; ')
+                                                                        else
+                                                                          ''
+                                                                        end
 
         new(merged_data)
       end
     end
   end
-end
+end

data/lib/claude_hooks/output/stop.rb

@@ -32,16 +32,23 @@ module ClaudeHooks
       end
 
       # === EXIT CODE LOGIC ===
-
+      #
+      # Stop hooks use the advanced JSON API with exit code 0.
+      # Per Anthropic guidance: when using structured JSON with decision/reason fields,
+      # always output to stdout with exit 0 (not stderr with exit 2).
+      # Reference: https://github.com/anthropics/claude-code/issues/10875
       def exit_code
-        # For Stop hooks: we assume 'continue' means continue to stop
-        return 0 unless continue?
-        # For Stop hooks: decision 'block' means force continue (exit 2)
-        return 2 if should_continue?
-
         0
       end
 
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # Stop hooks always output to stdout when using the JSON API.
+      # This follows the same pattern as PreToolUse hooks.
+      def output_stream
+        :stdout
+      end
+
       # === MERGE HELPER ===
 
       def self.merge(*outputs)

data/lib/claude_hooks/output/user_prompt_submit.rb

@@ -26,26 +26,33 @@ module ClaudeHooks
       end
 
       # === EXIT CODE LOGIC ===
-
+      #
+      # UserPromptSubmit hooks use the advanced JSON API with exit code 0.
+      # Per Anthropic guidance: when using structured JSON with decision/reason fields,
+      # always output to stdout with exit 0 (not stderr with exit 2).
+      # Reference: https://github.com/anthropics/claude-code/issues/10875
       def exit_code
-        return 2 unless continue?
-        return 2 if blocked?
-
         0
       end
 
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # UserPromptSubmit hooks always output to stdout when using the JSON API.
+      def output_stream
+        :stdout
+      end
+
       # === MERGE HELPER ===
 
       def self.merge(*outputs)
         compacted_outputs = outputs.compact
         return compacted_outputs.first if compacted_outputs.length == 1
         return super(*outputs) if compacted_outputs.empty?
-        
+
         merged = super(*outputs)
         merged_data = merged.data
 
         contexts = []
-        reasons = []
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
@@ -68,4 +75,4 @@ module ClaudeHooks
       end
     end
   end
-end
+end

data/lib/claude_hooks/stop.rb

@@ -3,6 +3,14 @@
 require_relative 'base'
 
 module ClaudeHooks
+  # Stop hook for preventing Claude Code from stopping execution.
+  #
+  # When using continue_with_instructions!, this hook outputs JSON to stdout
+  # with exit code 0 (advanced JSON API approach).
+  #
+  # References:
+  # - https://github.com/anthropics/claude-code/issues/10875
+  # - https://github.com/gabriel-dehan/claude_hooks/issues/11
   class Stop < Base
     def self.hook_type
       'Stop'

data/lib/claude_hooks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude_hooks
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Gabriel Dehan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-29 00:00:00.000000000 Z
+date: 2026-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -64,6 +64,7 @@ files:
 - CHANGELOG.md
 - README.md
 - claude_hooks.gemspec
+- docs/1.0.0_MIGRATION_GUIDE.md
 - docs/API/COMMON.md
 - docs/API/NOTIFICATION.md
 - docs/API/POST_TOOL_USE.md
@@ -74,15 +75,18 @@ files:
 - docs/API/STOP.md
 - docs/API/SUBAGENT_STOP.md
 - docs/API/USER_PROMPT_SUBMIT.md
-- docs/OUTPUT_MIGRATION_GUIDE.md
 - docs/WHY.md
+- docs/external/claude-hooks-reference.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/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
 - example_dotclaude/hooks/handlers/user_prompt_submit/log_user_prompt.rb
+- example_dotclaude/plugins/README.md
 - example_dotclaude/settings.json
 - lib/claude_hooks.rb
 - lib/claude_hooks/base.rb