claude_hooks 0.2.0 → 1.0.0

data/lib/claude_hooks/configuration.rb

@@ -122,7 +122,7 @@ module ClaudeHooks
         # Check if we have a config value for this method
         env_key = method_name.to_s.upcase
         config_key = snake_case_to_camel_case(method_name.to_s)
-        
+
         !get_config_value(env_key, config_key).nil? || super
       end
 
@@ -155,10 +155,10 @@ module ClaudeHooks
       def load_config
         # Load and merge config files from both locations
         merged_file_config = load_and_merge_config_files
-        
+
         # Merge with ENV variables
         env_config = load_env_config
-        
+
         # ENV variables take precedence over file configs
         merged_file_config.merge(env_config)
       end
@@ -166,10 +166,10 @@ module ClaudeHooks
       def load_and_merge_config_files
         home_config = load_config_file_from_path(home_config_file_path)
         project_config = load_config_file_from_path(project_config_file_path) if project_config_file_path
-        
+
         # Determine merge strategy
-        merge_strategy = ENV['CLAUDE_HOOKS_CONFIG_MERGE_STRATEGY'] || 'project'
-        
+        merge_strategy = ENV['RUBY_CLAUDE_HOOKS_CONFIG_MERGE_STRATEGY'] || 'project'
+
         if project_config && merge_strategy == 'project'
           # Project config takes precedence
           home_config.merge(project_config)
@@ -205,15 +205,15 @@ module ClaudeHooks
 
       def load_env_config
         env_config = {}
-        
+
         ENV.each do |key, value|
           next unless key.start_with?(ENV_PREFIX)
-          
+
           # Remove prefix and convert to config key format
           config_key = env_key_to_config_key(key.sub(ENV_PREFIX, ''))
           env_config[config_key] = value
         end
-        
+
         env_config
       end
 

data/lib/claude_hooks/logger.rb

@@ -5,7 +5,6 @@ require_relative 'configuration'
 
 module ClaudeHooks
   # Session-based logger for Claude Code hooks
-  # Provides both single-line and multiline block-based logging
   class Logger
     def initialize(session_id, source)
       @session_id = session_id

data/lib/claude_hooks/output/base.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ClaudeHooks
+  module Output
+    # Base class for all Claude Code hook output handlers
+    # Handles common functionality like continue/stop logic, output streams, and exit codes
+    class Base
+      attr_reader :data
+
+      def initialize(data)
+        @data = data || {}
+      end
+
+      # === COMMON FIELD ACCESSORS ===
+
+      # Check if Claude should continue processing
+      def continue?
+        @data['continue'] != false
+      end
+
+      # Get the stop reason if continue is false
+      def stop_reason
+        @data['stopReason'] || ''
+      end
+
+      # Check if output should be suppressed from transcript
+      def suppress_output?
+        @data['suppressOutput'] == true
+      end
+
+      # Get the system message (if any)
+      def system_message
+        @data['systemMessage'] || ''
+      end
+
+      # Get the hook-specific output data
+      def hook_specific_output
+        @data['hookSpecificOutput'] || {}
+      end
+
+      # === JSON SERIALIZATION ===
+
+      # Convert to JSON string (same as existing stringify_output)
+      def to_json(*args)
+        JSON.generate(@data, *args)
+      end
+      alias_method :stringify, :to_json
+
+      # === EXECUTION CONTROL ===
+
+      # Main execution method - handles output and exits with correct code
+      def output_and_exit
+        stream = output_stream
+        code = exit_code
+
+        case stream
+        when :stdout
+          $stdout.puts to_json
+        when :stderr
+          $stderr.puts to_json
+        else
+          raise "Unknown output stream: #{stream}"
+        end
+
+        exit code
+      end
+
+      # === ABSTRACT METHODS ===
+      # These must be implemented by subclasses
+
+      # Determine the exit code based on hook-specific logic
+      def exit_code
+        raise NotImplementedError, "Subclasses must implement exit_code"
+      end
+
+      # Determine the output stream (:stdout or :stderr)
+      def output_stream
+        default_output_stream
+      end
+
+      # === MERGE HELPER ===
+
+      # Base merge method - handles common fields like continue, stopReason, suppressOutput
+      # Subclasses should call super and add their specific logic
+      def self.merge(*outputs)
+        compacted_outputs = outputs.compact
+
+        merged_data = {
+          'continue' => true,
+          'stopReason' => '',
+          'suppressOutput' => false,
+          'systemMessage' => ''
+        }
+
+        return compacted_outputs.first if compacted_outputs.length == 1
+        return self.new(merged_data) if compacted_outputs.empty?
+
+        # 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('; ')
+        end
+
+        self.new(merged_data)
+      end
+
+      # === FACTORY ===
+
+      # Factory method to create the correct output class for a given hook type
+      def self.for_hook_type(hook_type, data)
+        case hook_type
+        when 'UserPromptSubmit'
+          UserPromptSubmit.new(data)
+        when 'PreToolUse'
+          PreToolUse.new(data)
+        when 'PostToolUse'
+          PostToolUse.new(data)
+        when 'Stop'
+          Stop.new(data)
+        when 'SubagentStop'
+          SubagentStop.new(data)
+        when 'Notification'
+          Notification.new(data)
+        when 'SessionStart'
+          SessionStart.new(data)
+        when 'SessionEnd'
+          SessionEnd.new(data)
+        when 'PreCompact'
+          PreCompact.new(data)
+        else
+          raise ArgumentError, "Unknown hook type: #{hook_type}"
+        end
+      end
+
+      protected
+
+      def default_exit_code
+        continue? ? 0 : 2
+      end
+
+      def default_output_stream
+        exit_code == 2 ? :stderr : :stdout
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/notification.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class Notification < Base
+      # === EXIT CODE LOGIC ===
+
+      def exit_code
+        default_exit_code
+      end
+
+      # === MERGE HELPER ===
+      
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end 
+    end
+  end
+end

data/lib/claude_hooks/output/post_tool_use.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class PostToolUse < Base
+      # === DECISION ACCESSORS ===
+
+      def decision
+        @data['decision']
+      end
+
+      def reason
+        @data['reason'] || ''
+      end
+
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
+      # === SEMANTIC HELPERS ===
+
+      def blocked?
+        decision == 'block'
+      end
+
+      # === EXIT CODE LOGIC ===
+
+      def exit_code
+        return 2 unless continue?
+        return 2 if blocked?
+
+        0
+      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 = []
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+          merged_data['decision'] = 'block' if output_data['decision'] == 'block'
+          merged_data['reason'] = [merged_data['reason'], output_data['reason']].compact.reject(&:empty?).join('; ')
+
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          contexts << context if context && !context.empty?
+        end
+
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'PostToolUse',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/pre_compact.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class PreCompact < Base
+      def exit_code
+        default_exit_code
+      end
+
+      # === MERGE HELPER ===
+
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end 
+    end
+  end
+end

data/lib/claude_hooks/output/pre_tool_use.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class PreToolUse < Base
+      # === PERMISSION DECISION ACCESSORS ===
+
+      def permission_decision
+        hook_specific_output['permissionDecision']
+      end
+
+      def permission_reason
+        hook_specific_output['permissionDecisionReason'] || ''
+      end
+
+      # === SEMANTIC HELPERS ===
+
+      def allowed?
+        permission_decision == 'allow'
+      end
+
+      def denied?
+        permission_decision == 'deny'
+      end
+      alias_method :blocked?, :denied?
+
+      def should_ask_permission?
+        permission_decision == 'ask'
+      end
+
+      # === EXIT CODE LOGIC ===
+
+      # Priority: continue false > permission decision
+      def exit_code
+        return 2 unless continue?
+
+        case permission_decision
+        when 'deny'
+          2 
+        when 'ask'
+          1 
+        else # allow 
+          0 
+        end
+      end
+
+      # STDOUT always works for PreToolUse
+      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
+
+        # PreToolUse specific merge: deny > ask > allow (most restrictive wins)
+        permission_decision = 'allow'
+        permission_reasons = []
+
+        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?
+          end
+        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
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/session_end.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # Note: SessionEnd hooks cannot block session termination - they're for cleanup only
+    class SessionEnd < Base      
+      # === EXIT CODE LOGIC ===
+
+      # SessionEnd hooks always return 0 - they're for cleanup only
+      def exit_code
+        0  
+      end
+
+      # === MERGE HELPER ===
+
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/session_start.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class SessionStart < Base
+      # === CONTEXT ACCESSORS ===
+
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
+      # === EXIT CODE LOGIC ===
+
+      def exit_code
+        default_exit_code
+      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 = []
+        
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          contexts << context if context && !context.empty?
+        end
+
+        # Set merged additional context
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'SessionStart',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/stop.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # Note: In Stop hooks, 'decision: block' actually means "force Claude to continue"
+    # This is counterintuitive but matches Claude Code's expected behavior
+    class Stop < Base
+      # === DECISION ACCESSORS ===
+
+      def decision
+        @data['decision']
+      end
+
+      def reason
+        @data['reason'] || ''
+      end
+      alias_method :continue_instructions, :reason
+
+      # === SEMANTIC HELPERS ===
+
+      # Check if Claude should be forced to continue (decision == 'block')
+      # Note: 'block' in Stop hooks means "block the stopping", i.e., continue
+      def should_continue?
+        decision == 'block'
+      end
+
+      # Check if Claude should stop normally (decision != 'block')
+      def should_stop?
+        decision != 'block'
+      end
+
+      # === EXIT CODE LOGIC ===
+
+      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
+
+      # === 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
+
+        # A blocking reason is actually a "continue instructions"
+        blocking_reasons = []
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+
+          # Handle decision - if any hook says 'block', respect that
+          if output_data['decision'] == 'block'
+            merged_data['decision'] = 'block'
+            reason = output_data['reason']
+            blocking_reasons << reason if reason && !reason.empty?
+          end
+        end
+
+        # Combine all blocking reasons / continue instructions
+        merged_data['reason'] = blocking_reasons.join('; ') unless blocking_reasons.empty?
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/subagent_stop.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'stop'
+
+module ClaudeHooks
+  module Output
+    class SubagentStop < Stop
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/user_prompt_submit.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class UserPromptSubmit < Base
+      # === DECISION ACCESSORS ===
+
+      def decision
+        @data['decision']
+      end
+
+      def reason
+        @data['reason'] || ''
+      end
+
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
+      # === SEMANTIC HELPERS ===
+
+      def blocked?
+        decision == 'block'
+      end
+
+      # === EXIT CODE LOGIC ===
+
+      def exit_code
+        return 2 unless continue?
+        return 2 if blocked?
+
+        0
+      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
+
+          merged_data['decision'] = 'block' if output_data['decision'] == 'block'
+          merged_data['reason'] = [merged_data['reason'], output_data['reason']].compact.reject(&:empty?).join('; ')
+
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          contexts << context if context && !context.empty?
+        end
+
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'UserPromptSubmit',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/post_tool_use.rb

@@ -38,18 +38,12 @@ module ClaudeHooks
       @output_data['reason'] = nil
     end
 
-    # === MERGE HELPER ===
-
-    # Merge multiple PostToolUse hook results intelligently
-    def self.merge_outputs(*outputs_data)
-      merged = super(*outputs_data)
-
-      outputs_data.compact.each do |output|
-        merged['decision'] = 'block' if output['decision'] == 'block'
-        merged['reason'] = [merged['reason'], output['reason']].compact.reject(&:empty?).join('; ')
-      end
-
-      merged
+    def add_additional_context!(context)
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'additionalContext' => context
+      }
     end
+    alias_method :add_context!, :add_additional_context!
   end
 end