claude_hooks 1.1.0 → 1.2.1

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class ConfigChange < Base
+    def self.hook_type
+      'ConfigChange'
+    end
+
+    def self.input_fields
+      %w[source]
+    end
+
+    def source
+      @input_data['source']
+    end
+
+    def file_path
+      @input_data['file_path'] || @input_data['filePath']
+    end
+
+    def block!(reason = '')
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = reason
+    end
+  end
+end

data/lib/claude_hooks/cwd_changed.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class CwdChanged < Base
+    def self.hook_type
+      'CwdChanged'
+    end
+
+    def self.input_fields
+      %w[old_cwd new_cwd]
+    end
+
+    def old_cwd
+      @input_data['old_cwd'] || @input_data['oldCwd']
+    end
+
+    def new_cwd
+      @input_data['new_cwd'] || @input_data['newCwd']
+    end
+
+    def watch_paths!(paths)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['watchPaths'] = Array(paths)
+    end
+  end
+end

data/lib/claude_hooks/elicitation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class Elicitation < Base
+    def self.hook_type
+      'Elicitation'
+    end
+
+    def self.input_fields
+      %w[mcp_server_name message]
+    end
+
+    def mcp_server_name
+      @input_data['mcp_server_name'] || @input_data['mcpServerName']
+    end
+
+    def message
+      @input_data['message']
+    end
+
+    def mode
+      @input_data['mode']
+    end
+
+    def url
+      @input_data['url']
+    end
+
+    def elicitation_id
+      @input_data['elicitation_id'] || @input_data['elicitationId']
+    end
+
+    def requested_schema
+      @input_data['requested_schema'] || @input_data['requestedSchema']
+    end
+
+    def accept!(content = {})
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'accept',
+        'content' => content
+      }
+    end
+
+    def decline!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'decline'
+      }
+    end
+
+    def cancel!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'cancel'
+      }
+    end
+  end
+end

data/lib/claude_hooks/elicitation_result.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class ElicitationResult < Base
+    def self.hook_type
+      'ElicitationResult'
+    end
+
+    def self.input_fields
+      %w[mcp_server_name action]
+    end
+
+    def mcp_server_name
+      @input_data['mcp_server_name'] || @input_data['mcpServerName']
+    end
+
+    def action
+      @input_data['action']
+    end
+
+    def mode
+      @input_data['mode']
+    end
+
+    def elicitation_id
+      @input_data['elicitation_id'] || @input_data['elicitationId']
+    end
+
+    def content
+      @input_data['content']
+    end
+
+    def accept!(content = {})
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'accept',
+        'content' => content
+      }
+    end
+
+    def decline!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'decline'
+      }
+    end
+
+    def cancel!
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'action' => 'cancel'
+      }
+    end
+  end
+end

data/lib/claude_hooks/file_changed.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class FileChanged < Base
+    def self.hook_type
+      'FileChanged'
+    end
+
+    def self.input_fields
+      %w[file_path event]
+    end
+
+    def file_path
+      @input_data['file_path'] || @input_data['filePath']
+    end
+
+    # Values: change | add | unlink
+    def event
+      @input_data['event']
+    end
+
+    def created?
+      event == 'add'
+    end
+
+    def modified?
+      event == 'change'
+    end
+
+    def deleted?
+      event == 'unlink'
+    end
+
+    def watch_paths!(paths)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['watchPaths'] = Array(paths)
+    end
+  end
+end

data/lib/claude_hooks/instructions_loaded.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class InstructionsLoaded < Base
+    def self.hook_type
+      'InstructionsLoaded'
+    end
+
+    def self.input_fields
+      %w[file_path load_reason]
+    end
+
+    def file_path
+      @input_data['file_path'] || @input_data['filePath']
+    end
+
+    def load_reason
+      @input_data['load_reason'] || @input_data['loadReason']
+    end
+  end
+end

data/lib/claude_hooks/message_display.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  # MessageDisplay runs while assistant message text is displayed on screen.
+  # Display-only: exit code and decision fields are ignored. The only effect is
+  # replacing the on-screen text via hookSpecificOutput.displayContent — the
+  # transcript and what Claude sees keep the original text.
+  class MessageDisplay < Base
+    def self.hook_type
+      'MessageDisplay'
+    end
+
+    def self.input_fields
+      %w[turn_id message_id index final delta]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def turn_id
+      @input_data['turn_id'] || @input_data['turnId']
+    end
+
+    def message_id
+      @input_data['message_id'] || @input_data['messageId']
+    end
+
+    def index
+      @input_data['index']
+    end
+
+    def final
+      @input_data.key?('final') ? @input_data['final'] : @input_data['isFinal']
+    end
+    alias_method :final?, :final
+
+    # The streamed assistant text delta for this event.
+    def delta
+      @input_data['delta']
+    end
+
+    # Some payloads expose the full text so far; kept as a convenience reader.
+    def message_text
+      @input_data['message_text'] || @input_data['messageText']
+    end
+
+    # === OUTPUT DATA HELPERS ===
+
+    # Replace the text shown on screen (display-only).
+    def display_content!(content)
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'displayContent' => content
+      }
+    end
+  end
+end

data/lib/claude_hooks/output/base.rb

@@ -40,6 +40,10 @@ module ClaudeHooks
         @data['hookSpecificOutput'] || {}
       end
 
+      def terminal_sequence
+        @data['terminalSequence']
+      end
+
       # === JSON SERIALIZATION ===
 
       # Convert to JSON string (same as existing stringify_output)
@@ -100,11 +104,12 @@ module ClaudeHooks
         # Apply base merge logic
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
-          
+
           merged_data['continue'] = false if output_data['continue'] == false
           merged_data['suppressOutput'] = true if output_data['suppressOutput'] == true
           merged_data['stopReason'] = [merged_data['stopReason'], output_data['stopReason']].compact.reject(&:empty?).join('; ')
           merged_data['systemMessage'] = [merged_data['systemMessage'], output_data['systemMessage']].compact.reject(&:empty?).join('; ')
+          merged_data['terminalSequence'] = output_data['terminalSequence'] unless output_data['terminalSequence'].nil?
         end
 
         self.new(merged_data)
@@ -129,12 +134,52 @@ module ClaudeHooks
           SubagentStop.new(data)
         when 'Notification'
           Notification.new(data)
+        when 'MessageDisplay'
+          MessageDisplay.new(data)
         when 'SessionStart'
           SessionStart.new(data)
         when 'SessionEnd'
           SessionEnd.new(data)
         when 'PreCompact'
           PreCompact.new(data)
+        when 'Setup'
+          Setup.new(data)
+        when 'SubagentStart'
+          SubagentStart.new(data)
+        when 'UserPromptExpansion'
+          UserPromptExpansion.new(data)
+        when 'PostToolBatch'
+          PostToolBatch.new(data)
+        when 'ConfigChange'
+          ConfigChange.new(data)
+        when 'TaskCreated'
+          TaskCreated.new(data)
+        when 'TaskCompleted'
+          TaskCompleted.new(data)
+        when 'TeammateIdle'
+          TeammateIdle.new(data)
+        when 'PostToolUseFailure'
+          PostToolUseFailure.new(data)
+        when 'StopFailure'
+          StopFailure.new(data)
+        when 'PostCompact'
+          PostCompact.new(data)
+        when 'CwdChanged'
+          CwdChanged.new(data)
+        when 'FileChanged'
+          FileChanged.new(data)
+        when 'InstructionsLoaded'
+          InstructionsLoaded.new(data)
+        when 'WorktreeRemove'
+          WorktreeRemove.new(data)
+        when 'PermissionDenied'
+          PermissionDenied.new(data)
+        when 'Elicitation'
+          Elicitation.new(data)
+        when 'ElicitationResult'
+          ElicitationResult.new(data)
+        when 'WorktreeCreate'
+          WorktreeCreate.new(data)
         else
           raise ArgumentError, "Unknown hook type: #{hook_type}"
         end