claude_hooks 0.2.1 → 1.0.2

data/lib/claude_hooks/output/post_tool_use.rb

@@ -0,0 +1,76 @@
+# 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 ===
+      #
+      # 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
+        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 = []
+
+        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,94 @@
+# 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 blocked? denied?
+
+      def should_ask_permission?
+        permission_decision == 'ask'
+      end
+
+      # === EXIT CODE LOGIC ===
+      #
+      # PreToolUse hooks use the advanced JSON API with exit code 0.
+      # Per Anthropic guidance: when using structured JSON with permissionDecision,
+      # always output to stdout with exit 0 (not stderr with exit 2).
+      # The permissionDecision field ('allow', 'deny', 'ask') controls behavior.
+      # Reference: https://github.com/anthropics/claude-code/issues/10875
+      def exit_code
+        0
+      end
+
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # PreToolUse 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
+
+        # 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
+
+          next unless 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
+
+        merged_data['hookSpecificOutput'] ||= { 'hookEventName' => 'PreToolUse' }
+        merged_data['hookSpecificOutput']['permissionDecision'] = permission_decision
+        merged_data['hookSpecificOutput']['permissionDecisionReason'] = if permission_reasons.any?
+                                                                          permission_reasons.join('; ')
+                                                                        else
+                                                                          ''
+                                                                        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,83 @@
+# 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 ===
+      #
+      # Stop 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
+        0
+      end
+
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # Stop hooks always output to stdout when using the JSON API.
+      # This follows the same pattern as PreToolUse hooks.
+      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
+
+        # 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,78 @@
+# 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 ===
+      #
+      # UserPromptSubmit 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
+        0
+      end
+
+      # === OUTPUT STREAM LOGIC ===
+      #
+      # UserPromptSubmit 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 = []
+
+        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

data/lib/claude_hooks/pre_tool_use.rb

@@ -47,42 +47,5 @@ module ClaudeHooks
         'permissionDecisionReason' => reason
       }
     end
-
-    # === MERGE HELPER ===
-
-    # Merge multiple PreToolUse hook results intelligently
-    def self.merge_outputs(*outputs_data)
-      merged = super(*outputs_data)
-
-      # For PreToolUse: deny > ask > allow (most restrictive wins)
-      permission_decision = 'allow'
-      permission_reasons = []
-
-      outputs_data.compact.each do |output|
-        if output.dig('hookSpecificOutput', 'permissionDecision')
-          current_decision = output['hookSpecificOutput']['permissionDecision']
-          case current_decision
-          when 'deny'
-            permission_decision = 'deny'
-          when 'ask'
-            permission_decision = 'ask' unless permission_decision == 'deny'
-          end
-
-          if output['hookSpecificOutput']['permissionDecisionReason']
-            permission_reasons << output['hookSpecificOutput']['permissionDecisionReason']
-          end
-        end
-      end
-
-      unless permission_reasons.empty?
-        merged['hookSpecificOutput'] = {
-          'hookEventName' => hook_type,
-          'permissionDecision' => permission_decision,
-          'permissionDecisionReason' => permission_reasons.join('; ')
-        }
-      end
-
-      merged
-    end
   end
 end

data/lib/claude_hooks/session_end.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class SessionEnd < Base
+    def self.hook_type
+      'SessionEnd'
+    end
+
+    def self.input_fields
+      %w[reason]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def reason
+      @input_data['reason']
+    end
+
+    # === REASON HELPERS ===
+
+    # Check if session was cleared with /clear command
+    def cleared?
+      reason == 'clear'
+    end
+
+    # Check if user logged out
+    def logout?
+      reason == 'logout'
+    end
+
+    # Check if user exited while prompt input was visible
+    def prompt_input_exit?
+      reason == 'prompt_input_exit'
+    end
+
+    # Check if reason is unspecified or other
+    def other_reason?
+      !cleared? && !logout? && !prompt_input_exit?
+    end
+  end
+end

data/lib/claude_hooks/session_start.rb

@@ -31,28 +31,5 @@ module ClaudeHooks
     def empty_additional_context!
       @output_data['hookSpecificOutput'] = nil
     end
-
-    # === MERGE HELPER ===
-
-    # Merge multiple SessionStart hook results intelligently
-    def self.merge_outputs(*outputs_data)
-      merged = super(*outputs_data)
-      contexts = []
-
-      outputs_data.compact.each do |output|
-        if output.dig('hookSpecificOutput', 'additionalContext')
-          contexts << output['hookSpecificOutput']['additionalContext']
-        end
-      end
-
-      unless contexts.empty?
-        merged['hookSpecificOutput'] = {
-          'hookEventName' => hook_type,
-          'additionalContext' => contexts.join("\n\n")
-        }
-      end
-
-      merged
-    end
   end
 end

data/lib/claude_hooks/stop.rb

@@ -3,6 +3,14 @@
 require_relative 'base'
 
 module ClaudeHooks
+  # Stop hook for preventing Claude Code from stopping execution.
+  #
+  # When using continue_with_instructions!, this hook outputs JSON to stdout
+  # with exit code 0 (advanced JSON API approach).
+  #
+  # References:
+  # - https://github.com/anthropics/claude-code/issues/10875
+  # - https://github.com/gabriel-dehan/claude_hooks/issues/11
   class Stop < Base
     def self.hook_type
       'Stop'
@@ -32,30 +40,5 @@ module ClaudeHooks
       @output_data.delete('decision')
       @output_data.delete('reason')
     end
-
-    # === MERGE HELPER ===
-
-    # Merge multiple Stop hook results intelligently
-    def self.merge_outputs(*outputs_data)
-      merged = super(*outputs_data)
-
-      # A blocking reason is actually a "continue instructions"
-      blocking_reasons = []
-
-      outputs_data.compact.each do |output|
-        # Handle decision - if any hook says 'block', respect that
-        if output['decision'] == 'block'
-          merged['decision'] = 'block'
-          blocking_reasons << output['reason'] if output['reason'] && !output['reason'].empty?
-        end
-      end
-
-      # Combine all blocking reasons / continue instructions
-      unless blocking_reasons.empty?
-        merged['reason'] = blocking_reasons.join('; ')
-      end
-
-      merged
-    end
   end
 end

data/lib/claude_hooks/user_prompt_submit.rb

@@ -43,31 +43,5 @@ module ClaudeHooks
       @output_data['decision'] = nil
       @output_data['reason'] = nil
     end
-
-    # === MERGE HELPER ===
-
-    # Merge multiple UserPromptSubmit hook results intelligently
-    def self.merge_outputs(*outputs_data)
-      merged = super(*outputs_data)
-      contexts = []
-
-      outputs_data.compact.each do |output|
-        merged['decision'] = 'block' if output['decision'] == 'block'
-        merged['reason'] = [merged['reason'], output['reason']].compact.reject(&:empty?).join('; ')
-
-        if output.dig('hookSpecificOutput', 'additionalContext')
-          contexts << output['hookSpecificOutput']['additionalContext']
-        end
-      end
-
-      unless contexts.empty?
-        merged['hookSpecificOutput'] = {
-          'hookEventName' => hook_type,
-          'additionalContext' => contexts.join("\n\n")
-        }
-      end
-
-      merged
-    end
   end
 end

data/lib/claude_hooks/version.rb

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