claude_hooks 1.0.0 → 1.1.0

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/base.rb

@@ -9,7 +9,7 @@ module ClaudeHooks
   # Base class for Claude Code hook scripts
   class Base
     # Common input fields for all hook types
-    COMMON_INPUT_FIELDS = %w[session_id transcript_path cwd hook_event_name].freeze
+    COMMON_INPUT_FIELDS = %w[session_id transcript_path cwd hook_event_name permission_mode].freeze
 
     # Override in subclasses to specify hook type
     def self.hook_type
@@ -71,6 +71,10 @@ module ClaudeHooks
       @input_data['hook_event_name'] || @input_data['hookEventName'] || hook_type
     end
 
+    def permission_mode
+      @input_data['permission_mode'] || @input_data['permissionMode'] || 'default'
+    end
+
     def read_transcript
       unless transcript_path && File.exist?(transcript_path)
         log "Transcript file not found at #{transcript_path}", level: :warn

data/lib/claude_hooks/notification.rb

@@ -9,7 +9,7 @@ module ClaudeHooks
     end
 
     def self.input_fields
-      %w[message]
+      %w[message notification_type]
     end
 
     # === INPUT DATA ACCESS ===
@@ -18,5 +18,9 @@ module ClaudeHooks
       @input_data['message']
     end
     alias_method :notification_message, :message
+
+    def notification_type
+      @input_data['notification_type'] || @input_data['notificationType']
+    end
   end
 end

data/lib/claude_hooks/output/base.rb

@@ -119,6 +119,8 @@ module ClaudeHooks
           UserPromptSubmit.new(data)
         when 'PreToolUse'
           PreToolUse.new(data)
+        when 'PermissionRequest'
+          PermissionRequest.new(data)
         when 'PostToolUse'
           PostToolUse.new(data)
         when 'Stop'

data/lib/claude_hooks/output/permission_request.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class PermissionRequest < Base
+      # === PERMISSION DECISION ACCESSORS ===
+
+      def permission_decision
+        hook_specific_output['permissionDecision']
+      end
+
+      def permission_reason
+        hook_specific_output['permissionDecisionReason'] || ''
+      end
+
+      def updated_input
+        hook_specific_output['updatedInput']
+      end
+
+      # === SEMANTIC HELPERS ===
+
+      def allowed?
+        permission_decision == 'allow'
+      end
+
+      def denied?
+        permission_decision == 'deny'
+      end
+
+      def input_updated?
+        !updated_input.nil?
+      end
+
+      # === EXIT CODE LOGIC ===
+      #
+      # PermissionRequest hooks use the advanced JSON API with exit code 0.
+      # Following the same pattern as PreToolUse (permission-based hooks).
+      def exit_code
+        0
+      end
+
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # PermissionRequest 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
+
+        # PermissionRequest specific merge: deny > allow (most restrictive wins)
+        permission_decision = 'allow'
+        permission_reasons = []
+        updated_inputs = []
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+
+          next unless output_data.dig('hookSpecificOutput', 'permissionDecision')
+
+          current_decision = output_data['hookSpecificOutput']['permissionDecision']
+          permission_decision = 'deny' if current_decision == 'deny'
+
+          reason = output_data.dig('hookSpecificOutput', 'permissionDecisionReason')
+          permission_reasons << reason if reason && !reason.empty?
+
+          updated = output_data.dig('hookSpecificOutput', 'updatedInput')
+          updated_inputs << updated if updated
+        end
+
+        merged_data['hookSpecificOutput'] ||= { 'hookEventName' => 'PermissionRequest' }
+        merged_data['hookSpecificOutput']['permissionDecision'] = permission_decision
+        merged_data['hookSpecificOutput']['permissionDecisionReason'] = if permission_reasons.any?
+                                                                          permission_reasons.join('; ')
+                                                                        else
+                                                                          ''
+                                                                        end
+        # Last updated input wins
+        merged_data['hookSpecificOutput']['updatedInput'] = updated_inputs.last if updated_inputs.any?
+
+        new(merged_data)
+      end
+    end
+  end
+end

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