claude_hooks 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbd6349008b693bddb770b79ac5883a746c826a800ed7141f4de466bd88025e0
-  data.tar.gz: b7a724ed1655ecb7c4af3393619e5dd800b0b59a08721c6d4b7279c4d31a185d
+  metadata.gz: d7cd63a0fbf165b912baa3fab487e056f05bc10d29b77123e2029ef1dce385a4
+  data.tar.gz: '054837c4d15be8b9d248aa81db5966d80c2c5e0f9a322c622bdf781bf8d0af20'
 SHA512:
-  metadata.gz: a1596119ed1ee346ed133a76a0991cc64f8be594905e96e6b056e6e5187be91ca43ffd4c28c3e822725b5ee4bdb0bdbc03aa0cea38c06a5813b94c3a381ff0c3
-  data.tar.gz: 6063e35f39ffabd8eaf78e9deccd009e56f9103c86f69dedb6a2ed66b97cc9a8606d0aafb6ee2467d6fa29536031f4d0d671ff20e466c672009d16e2c2a962ea
+  metadata.gz: 38ef48d0b9cb24d30522f213302d5a3af48fca24ecd90af259b7d6a034fcbd8ddc706c0c2783db8b5372fb59c3d7a4429b7cc7523cd0299e7ed2a7b8cb8b023e
+  data.tar.gz: 82cdb4b713646492a92a1bae0143a7051fe2bc4f6afe0ad7394bb6f7d50704035a8ddd863bb1b4d12885867859cd6b5b743c618d2fc87682e26918150162b25a

data/.claude/auto-fix.md

@@ -0,0 +1,7 @@
+Context: This gem is a wrapper around Claude Code Hooks system, providing a Ruby DSL to define hooks. The github repository has an automated system through github actions that automatically (weekly) creates a diff of the last known state of Claude Code's hook documentation vs the current (online) Claude Code's hooks documentation. It then generates a diff between those and create an issue with the diff.
+
+Intended goal: Take all those issues and all those diffs and evaluate if the gem / code needs to be updated to match the changes made by anthropic to their Claude Code Hooks system.
+
+First step: Retrieve all the issues at: https://github.com/gabriel-dehan/claude_hooks/issues
+And assess which issues may implement things that need to be changed (a lot of issues contain useless diff, with wording changes, link changes, etc that are not relevant).
+Second step: Take those relevant issues and look at the diff, then compare it with the current codebase / readme / documentation to see if there is a mismatch Third step: Create a plan to tackle those changes

data/CHANGELOG.md

@@ -5,11 +5,106 @@ 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.1.0] - 2026-01-04
+
+### Added
+
+- **New PermissionRequest hook type** - Handles permission request events from Claude Code
+  - New `ClaudeHooks::PermissionRequest` hook class
+  - New `ClaudeHooks::Output::PermissionRequest` output class
+  - Methods: `allow_permission!`, `deny_permission!`, `update_input_and_allow!`
+  - Semantic helpers: `allowed?`, `denied?`, `input_updated?`
+  - Exit code 0 with stdout (JSON API pattern)
+  - Merge logic: deny > allow (most restrictive wins)
+
+- **permission_mode field** - Added to all hooks as common input field
+  - Values: `default`, `plan`, `acceptEdits`, `dontAsk`, `bypassPermissions`
+  - Accessible via `permission_mode` method on all hook instances
+  - Defaults to `'default'` when not provided
+  - Supports both snake_case (`permission_mode`) and camelCase (`permissionMode`)
+
+- **tool_use_id field** - Added to PreToolUse and PostToolUse hooks
+  - Unique identifier for each tool use event (e.g., `"toolu_01ABC123..."`)
+  - Accessible via `tool_use_id` method
+  - Supports both snake_case and camelCase input
+
+- **notification_type field** - Added to Notification hook
+  - Values: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`
+  - Accessible via `notification_type` method
+  - Enables filtering notifications by type using matchers
+
+- **updatedInput support** - Added to PreToolUse hook
+  - New method: `update_tool_input!(hash)` for modifying tool input before execution
+  - Output helpers: `input_updated?`, `updated_input`
+  - Automatically sets `permissionDecision` to `'allow'`
+  - Merge logic: last updatedInput wins (most recent transformation)
+  - Works seamlessly with existing approval/denial methods
+
+### Changed
+
+- Updated all hook classes to include new input fields where applicable
+- Enhanced PreToolUse output class with updatedInput merge logic
+- Updated main module to require PermissionRequest classes
+- Updated output factory to support PermissionRequest hook type
+
+### Notes
+
+- **All changes are backward compatible** - Existing hooks continue to work without modification
+- New fields are optional with sensible defaults
+- No breaking changes to existing APIs
+- Aligns with Anthropic's Claude Code Hooks documentation as of January 2026
+- Total hook types: 10 (added PermissionRequest)
+
+## [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 +152,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 +184,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,10 +261,11 @@ 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 |
+| **[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 |
@@ -269,7 +276,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 +349,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 +362,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
@@ -381,11 +388,12 @@ 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` |
+| **Common**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `permission_mode` |
 | **UserPromptSubmit**  | `prompt` |
-| **PreToolUse**  | `tool_name`, `tool_input` |
-| **PostToolUse**  | `tool_name`, `tool_input`, `tool_response` |
-| **Notification**  | `message` |
+| **PreToolUse**  | `tool_name`, `tool_input`, `tool_use_id` |
+| **PermissionRequest**  | `tool_name`, `tool_input`, `tool_use_id` |
+| **PostToolUse**  | `tool_name`, `tool_input`, `tool_response`, `tool_use_id` |
+| **Notification**  | `message`, `notification_type` |
 | **Stop**  | `stop_hook_active` |
 | **SubagentStop**  | `stop_hook_active` |
 | **PreCompact**  | `trigger`, `custom_instructions` |
@@ -401,6 +409,7 @@ The framework supports all existing hook types with their respective input field
 - [🚀 Session Start Hooks](docs/API/SESSION_START.md)
 - [🖋️ User Prompt Submit Hooks](docs/API/USER_PROMPT_SUBMIT.md)
 - [🛠️ Pre-Tool Use Hooks](docs/API/PRE_TOOL_USE.md)
+- [🔐 Permission Request Hooks](docs/API/PERMISSION_REQUEST.md)
 - [🔧 Post-Tool Use Hooks](docs/API/POST_TOOL_USE.md)
 - [📝 Pre-Compact Hooks](docs/API/PRE_COMPACT.md)
 - [⏹️ Stop Hooks](docs/API/STOP.md)
@@ -535,9 +544,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 +556,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 +588,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 +657,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.