claude_hooks 1.2.0 → 1.3.0

data/example_dotclaude/hooks/entrypoints/session_end.rb

@@ -1,35 +1,18 @@
 #!/usr/bin/env ruby
 
-require 'json'
+require 'claude_hooks'
 require_relative '../handlers/session_end/cleanup_handler'
 require_relative '../handlers/session_end/log_session_stats'
 
-begin
-  # Read input from stdin
-  input_data = JSON.parse(STDIN.read)
-
-  # Initialize handlers
+ClaudeHooks::CLI.run_hook do |input_data|
   cleanup_handler = CleanupHandler.new(input_data)
   log_handler = LogSessionStats.new(input_data)
 
-  # Execute handlers
   cleanup_handler.call
   log_handler.call
 
-  # Merge outputs using the SessionEnd output merger
-  merged_output = ClaudeHooks::Output::SessionEnd.merge(
+  ClaudeHooks::Output::SessionEnd.merge(
     cleanup_handler.output,
     log_handler.output
-  )
-
-  # Output result and exit with appropriate code
-  merged_output.output_and_exit
-
-rescue StandardError => e
-  STDERR.puts JSON.generate({
-    continue: false,
-    stopReason: "Hook execution error: #{e.message}",
-    suppressOutput: false
-  })
-  exit 2
-end
+  ).output_and_exit
+end

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -1,40 +1,18 @@
 #!/usr/bin/env ruby
 
-# Example of the NEW simplified entrypoint pattern using output objects
-# Compare this to the existing user_prompt_submit.rb to see the difference!
-
 require 'claude_hooks'
-require 'json'
-# Require the output classes
-require_relative '../../../lib/claude_hooks/output/base'
-require_relative '../../../lib/claude_hooks/output/user_prompt_submit'
 require_relative '../handlers/user_prompt_submit/append_rules'
 require_relative '../handlers/user_prompt_submit/log_user_prompt'
 
-begin
-  # Read input from stdin
-  input_data = JSON.parse(STDIN.read)
-
-  # Execute all hook scripts
+ClaudeHooks::CLI.run_hook do |input_data|
   append_rules = AppendRules.new(input_data)
   append_rules.call
 
   log_user_prompt = LogUserPrompt.new(input_data)
   log_user_prompt.call
 
-  merged_output = ClaudeHooks::Output::UserPromptSubmit.merge(
+  ClaudeHooks::Output::UserPromptSubmit.merge(
     append_rules.output,
     log_user_prompt.output
-  )
-
-  merged_output.output_and_exit
-
-rescue StandardError => e
-  # Same simple error pattern
-  STDERR.puts JSON.generate({
-    continue: false,
-    stopReason: "Hook execution error: #{e.message} #{e.backtrace.join("\n")}",
-    suppressOutput: false
-  })
-  exit 2
-end
+  ).output_and_exit
+end

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

@@ -238,16 +238,10 @@ class GithubGuard < ClaudeHooks::PreToolUse
   end
 end
 
-# When running this file directly (for debugging)
-if __FILE__ == $PROGRAM_NAME
-  ClaudeHooks::CLI.run_with_sample_data(GithubGuard) do |data|
-    data.merge!(
-      'session_id' => 'GithubGuardTest',
-      'transcript_path' => '',
-      'cwd' => Dir.pwd,
-      'hook_event_name' => 'PreToolUse',
-      'tool_name' => 'mcp__github__create_pull_request',
-      'tool_input' => { 'draft' => false },
-    )
-  end
-end
+# Registered directly in settings.json under PreToolUse. Claude Code runs this file
+# with the hook payload on STDIN. on_error: :block makes the guard fail-closed — a
+# crash blocks the tool instead of silently allowing it.
+#
+# Debug it by piping sample JSON:
+#   echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push --force"}}' | ruby github_guard.rb
+ClaudeHooks::CLI.run_hook(GithubGuard, on_error: :block)

data/example_dotclaude/settings.json

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

data/lib/claude_hooks/cli.rb

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

data/lib/claude_hooks/directory_added.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class DirectoryAdded < Base
+    def self.hook_type
+      'DirectoryAdded'
+    end
+
+    def self.input_fields
+      %w[directory source]
+    end
+
+    def directory
+      @input_data['directory']
+    end
+
+    # Values: slash_command | register_repo_root
+    def source
+      @input_data['source']
+    end
+  end
+end

data/lib/claude_hooks/output/base.rb

@@ -180,6 +180,8 @@ module ClaudeHooks
           ElicitationResult.new(data)
         when 'WorktreeCreate'
           WorktreeCreate.new(data)
+        when 'DirectoryAdded'
+          DirectoryAdded.new(data)
         else
           raise ArgumentError, "Unknown hook type: #{hook_type}"
         end

data/lib/claude_hooks/output/directory_added.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # DirectoryAdded is non-blocking — the directory is already added.
+    # Only `systemMessage` is consumed (as Claude context for `slash_command`,
+    # debug log for `register_repo_root`).
+    class DirectoryAdded < Base
+      def exit_code
+        0
+      end
+
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/version.rb

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

data/lib/claude_hooks.rb

@@ -37,6 +37,7 @@ require_relative "claude_hooks/permission_denied"
 require_relative "claude_hooks/elicitation"
 require_relative "claude_hooks/elicitation_result"
 require_relative "claude_hooks/worktree_create"
+require_relative "claude_hooks/directory_added"
 
 # Output classes
 require_relative "claude_hooks/output/base"
@@ -70,6 +71,7 @@ require_relative "claude_hooks/output/permission_denied"
 require_relative "claude_hooks/output/elicitation"
 require_relative "claude_hooks/output/elicitation_result"
 require_relative "claude_hooks/output/worktree_create"
+require_relative "claude_hooks/output/directory_added"
 
 module ClaudeHooks
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude_hooks
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Gabriel Dehan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -64,7 +64,6 @@ files:
 - ".agents/skills/ci-monitoring/SKILL.md"
 - ".agents/skills/run-tests/SKILL.md"
 - ".claude/auto-fix.md"
-- ".claude/settings.local.json"
 - AGENTS.md
 - CHANGELOG.md
 - README.md
@@ -74,6 +73,7 @@ files:
 - docs/API/COMMON.md
 - docs/API/CONFIG_CHANGE.md
 - docs/API/CWD_CHANGED.md
+- docs/API/DIRECTORY_ADDED.md
 - docs/API/ELICITATION.md
 - docs/API/ELICITATION_RESULT.md
 - docs/API/FILE_CHANGED.md
@@ -110,10 +110,9 @@ files:
 - docs/mitts/setup.md
 - docs/mitts/task.md
 - example_dotclaude/commands/.gitkeep
-- example_dotclaude/hooks/entrypoints/pre_tool_use.rb
 - example_dotclaude/hooks/entrypoints/session_end.rb
 - example_dotclaude/hooks/entrypoints/user_prompt_submit.rb
-- example_dotclaude/hooks/handlers/pre_tool_use/github_guard.rb
+- example_dotclaude/hooks/github_guard.rb
 - example_dotclaude/hooks/handlers/session_end/cleanup_handler.rb
 - example_dotclaude/hooks/handlers/session_end/log_session_stats.rb
 - example_dotclaude/hooks/handlers/user_prompt_submit/append_rules.rb
@@ -126,6 +125,7 @@ files:
 - lib/claude_hooks/config_change.rb
 - lib/claude_hooks/configuration.rb
 - lib/claude_hooks/cwd_changed.rb
+- lib/claude_hooks/directory_added.rb
 - lib/claude_hooks/elicitation.rb
 - lib/claude_hooks/elicitation_result.rb
 - lib/claude_hooks/file_changed.rb
@@ -136,6 +136,7 @@ files:
 - lib/claude_hooks/output/base.rb
 - lib/claude_hooks/output/config_change.rb
 - lib/claude_hooks/output/cwd_changed.rb
+- lib/claude_hooks/output/directory_added.rb
 - lib/claude_hooks/output/elicitation.rb
 - lib/claude_hooks/output/elicitation_result.rb
 - lib/claude_hooks/output/file_changed.rb

data/.claude/settings.local.json

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

data/example_dotclaude/hooks/entrypoints/pre_tool_use.rb

@@ -1,25 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'claude_hooks'
-require_relative '../handlers/pre_tool_use/github_guard'
-
-begin
-  # Read Claude Code input from stdin
-  input_data = JSON.parse($stdin.read)
-
-  github_guard = GithubGuard.new(input_data)
-  github_guard.call
-
-  github_guard.output_and_exit
-rescue StandardError => e
-  puts JSON.generate(
-    {
-      continue: false,
-      stopReason: "Error in PreToolUse hook, #{e.message}, #{e.backtrace.join("\n")}",
-      suppressOutput: false,
-    },
-  )
-  # Allow anyway, to not block developers if there is an issue with the hook
-  exit 1
-end