claude_hooks 1.1.0 → 1.2.1

data/lib/claude_hooks/output/pre_tool_use.rb

@@ -38,6 +38,10 @@ module ClaudeHooks
         !updated_input.nil?
       end
 
+      def deferred?
+        permission_decision == 'defer'
+      end
+
       # === EXIT CODE LOGIC ===
       #
       # PreToolUse hooks use the advanced JSON API with exit code 0.
@@ -66,7 +70,7 @@ module ClaudeHooks
         merged = super(*outputs)
         merged_data = merged.data
 
-        # PreToolUse specific merge: deny > ask > allow (most restrictive wins)
+        # PreToolUse specific merge: deny > defer > ask > allow (most restrictive wins)
         permission_decision = 'allow'
         permission_reasons = []
 
@@ -79,8 +83,10 @@ module ClaudeHooks
           case current_decision
           when 'deny'
             permission_decision = 'deny'
+          when 'defer'
+            permission_decision = 'defer' unless permission_decision == 'deny'
           when 'ask'
-            permission_decision = 'ask' unless permission_decision == 'deny'
+            permission_decision = 'ask' unless %w[deny defer].include?(permission_decision)
           end
 
           reason = output_data.dig('hookSpecificOutput', 'permissionDecisionReason')

data/lib/claude_hooks/output/session_start.rb

@@ -11,6 +11,22 @@ module ClaudeHooks
         hook_specific_output['additionalContext'] || ''
       end
 
+      def session_title
+        hook_specific_output['sessionTitle']
+      end
+
+      def initial_user_message
+        hook_specific_output['initialUserMessage']
+      end
+
+      def watch_paths
+        hook_specific_output['watchPaths'] || []
+      end
+
+      def reload_skills?
+        hook_specific_output['reloadSkills'] == true
+      end
+
       # === EXIT CODE LOGIC ===
 
       def exit_code
@@ -27,19 +43,25 @@ module ClaudeHooks
         merged = super(*outputs)
         merged_data = merged.data
         contexts = []
-        
+        specific = {}
+
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
-          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          hso = output_data['hookSpecificOutput'] || {}
+
+          context = hso['additionalContext']
           contexts << context if context && !context.empty?
+
+          # Last-non-nil wins for the scalar/array session fields.
+          %w[sessionTitle initialUserMessage watchPaths reloadSkills].each do |key|
+            specific[key] = hso[key] unless hso[key].nil?
+          end
         end
 
-        # Set merged additional context
-        unless contexts.empty?
-          merged_data['hookSpecificOutput'] = {
-            'hookEventName' => 'SessionStart',
-            'additionalContext' => contexts.join("\n\n")
-          }
+        specific['additionalContext'] = contexts.join("\n\n") unless contexts.empty?
+
+        unless specific.empty?
+          merged_data['hookSpecificOutput'] = { 'hookEventName' => 'SessionStart' }.merge(specific)
         end
 
         new(merged_data)

data/lib/claude_hooks/output/setup.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class Setup < Base
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
+      def exit_code
+        default_exit_code
+      end
+
+      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
+
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'Setup',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/stop.rb

@@ -18,6 +18,10 @@ module ClaudeHooks
       end
       alias_method :continue_instructions, :reason
 
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
       # === SEMANTIC HELPERS ===
 
       # Check if Claude should be forced to continue (decision == 'block')
@@ -61,6 +65,7 @@ module ClaudeHooks
 
         # A blocking reason is actually a "continue instructions"
         blocking_reasons = []
+        contexts = []
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
@@ -71,11 +76,21 @@ module ClaudeHooks
             reason = output_data['reason']
             blocking_reasons << reason if reason && !reason.empty?
           end
+
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          contexts << context if context && !context.empty?
         end
 
         # Combine all blocking reasons / continue instructions
         merged_data['reason'] = blocking_reasons.join('; ') unless blocking_reasons.empty?
 
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => merged_data.dig('hookSpecificOutput', 'hookEventName') || 'Stop',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
         new(merged_data)
       end
     end

data/lib/claude_hooks/output/stop_failure.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # StopFailure is purely a logging event — output/exit is ignored by Claude Code.
+    class StopFailure < Base
+      def exit_code
+        0
+      end
+
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/subagent_start.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class SubagentStart < Base
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
+      def exit_code
+        default_exit_code
+      end
+
+      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
+
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'SubagentStart',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/task_completed.rb

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

data/lib/claude_hooks/output/task_created.rb

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

data/lib/claude_hooks/output/teammate_idle.rb

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

data/lib/claude_hooks/output/user_prompt_expansion.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class UserPromptExpansion < Base
+      def decision
+        @data['decision']
+      end
+
+      def reason
+        @data['reason'] || ''
+      end
+
+      def blocked?
+        decision == 'block'
+      end
+
+      def additional_context
+        hook_specific_output['additionalContext'] || ''
+      end
+
+      def exit_code
+        default_exit_code
+      end
+
+      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
+        reasons = []
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+          if output_data['decision'] == 'block'
+            merged_data['decision'] = 'block'
+            r = output_data['reason']
+            reasons << r if r && !r.empty?
+          end
+        end
+
+        merged_data['reason'] = reasons.join('; ') if reasons.any?
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/worktree_create.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # WorktreeCreate has a special bare-stdout contract:
+    # the last non-empty stdout line is interpreted as the worktree path.
+    # An empty/missing path causes Claude Code to treat creation as failed.
+    class WorktreeCreate < Base
+      def worktree_path
+        @data['hookSpecificOutput']&.dig('worktreePath') || @data['_worktree_path']
+      end
+
+      def exit_code
+        worktree_path && !worktree_path.empty? ? 0 : 1
+      end
+
+      def output_stream
+        :stdout
+      end
+
+      # Overrides the default JSON output — prints the bare path instead.
+      def output_and_exit
+        path = worktree_path
+        if path && !path.empty?
+          $stdout.puts path
+          exit 0
+        else
+          exit 1
+        end
+      end
+
+      def self.merge(*outputs)
+        compacted_outputs = outputs.compact
+        return compacted_outputs.first if compacted_outputs.length == 1
+        return super(*outputs) if compacted_outputs.empty?
+
+        # Last set path wins
+        merged = super(*outputs)
+        merged_data = merged.data
+        last_path = nil
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+          p = output_data.dig('hookSpecificOutput', 'worktreePath') || output_data['_worktree_path']
+          last_path = p if p && !p.empty?
+        end
+
+        if last_path
+          merged_data['hookSpecificOutput'] ||= { 'hookEventName' => 'WorktreeCreate' }
+          merged_data['hookSpecificOutput']['worktreePath'] = last_path
+          merged_data['_worktree_path'] = last_path
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/worktree_remove.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # WorktreeRemove is non-blocking — only suppressOutput is honored.
+    class WorktreeRemove < Base
+      def exit_code
+        0
+      end
+
+      def self.merge(*outputs)
+        merged = super(*outputs)
+        new(merged.data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/permission_denied.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PermissionDenied < Base
+    def self.hook_type
+      'PermissionDenied'
+    end
+
+    def self.input_fields
+      %w[tool_name tool_input tool_use_id reason]
+    end
+
+    def tool_name
+      @input_data['tool_name']
+    end
+
+    def tool_input
+      @input_data['tool_input']
+    end
+
+    def tool_use_id
+      @input_data['tool_use_id'] || @input_data['toolUseId']
+    end
+
+    def reason
+      @input_data['reason']
+    end
+
+    def retry!
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['retry'] = true
+    end
+
+    def no_retry!
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['retry'] = false
+    end
+  end
+end

data/lib/claude_hooks/permission_request.rb

@@ -26,30 +26,37 @@ module ClaudeHooks
       @input_data['tool_use_id'] || @input_data['toolUseId']
     end
 
+    def permission_suggestions
+      @input_data['permissionSuggestions'] || @input_data['permission_suggestions'] || []
+    end
+
     # === OUTPUT DATA HELPERS ===
 
     def allow_permission!(reason = '')
       @output_data['hookSpecificOutput'] = {
         'hookEventName' => hook_event_name,
-        'permissionDecision' => 'allow',
-        'permissionDecisionReason' => reason
+        'decision' => { 'behavior' => 'allow' }
       }
+      @output_data['hookSpecificOutput']['decision']['message'] = reason unless reason.empty?
     end
 
-    def deny_permission!(reason = '')
+    def deny_permission!(reason = '', interrupt: nil)
+      decision = { 'behavior' => 'deny' }
+      decision['message'] = reason unless reason.empty?
+      decision['interrupt'] = interrupt unless interrupt.nil?
       @output_data['hookSpecificOutput'] = {
         'hookEventName' => hook_event_name,
-        'permissionDecision' => 'deny',
-        'permissionDecisionReason' => reason
+        'decision' => decision
       }
     end
 
-    def update_input_and_allow!(updated_input, reason = '')
+    def update_input_and_allow!(updated_input, reason = '', updated_permissions: nil)
+      decision = { 'behavior' => 'allow', 'updatedInput' => updated_input }
+      decision['message'] = reason unless reason.empty?
+      decision['updatedPermissions'] = updated_permissions unless updated_permissions.nil?
       @output_data['hookSpecificOutput'] = {
         'hookEventName' => hook_event_name,
-        'permissionDecision' => 'allow',
-        'permissionDecisionReason' => reason,
-        'updatedInput' => updated_input
+        'decision' => decision
       }
     end
   end

data/lib/claude_hooks/post_compact.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PostCompact < Base
+    def self.hook_type
+      'PostCompact'
+    end
+
+    def self.input_fields
+      %w[trigger compact_summary]
+    end
+
+    def trigger
+      @input_data['trigger']
+    end
+
+    def compact_summary
+      @input_data['compact_summary'] || @input_data['compactSummary']
+    end
+  end
+end

data/lib/claude_hooks/post_tool_batch.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PostToolBatch < Base
+    def self.hook_type
+      'PostToolBatch'
+    end
+
+    def self.input_fields
+      %w[tool_calls]
+    end
+
+    def tool_calls
+      @input_data['tool_calls'] || @input_data['toolCalls'] || []
+    end
+
+    # Convenience partitions over tool_calls. Entries carry a `tool_response`
+    # rather than an explicit success flag, so success is derived from the
+    # presence of a response that isn't flagged as an error. When your payload
+    # shape differs, use the raw `tool_calls` array instead.
+    def succeeded_calls
+      tool_calls.reject { |call| failed_call?(call) }
+    end
+
+    def failed_calls
+      tool_calls.select { |call| failed_call?(call) }
+    end
+
+    def block!(reason = '')
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = reason
+    end
+
+    def add_additional_context!(context)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['additionalContext'] = context
+    end
+
+    private
+
+    # A call is considered failed when its response is missing or carries an
+    # error marker (`is_error`/`isError` true, or an `error` key).
+    def failed_call?(call)
+      return true unless call.is_a?(Hash)
+
+      response = call['tool_response'] || call['toolResponse']
+      return true if response.nil?
+
+      if response.is_a?(Hash)
+        return true if response['is_error'] == true || response['isError'] == true
+        return true if response.key?('error') && !response['error'].nil?
+      end
+
+      false
+    end
+  end
+end

data/lib/claude_hooks/post_tool_use.rb

@@ -49,5 +49,15 @@ module ClaudeHooks
       }
     end
     alias_method :add_context!, :add_additional_context!
+
+    def update_tool_output!(value)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['updatedToolOutput'] = value
+    end
+
+    def update_mcp_tool_output!(value)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['updatedMCPToolOutput'] = value
+    end
   end
 end

data/lib/claude_hooks/post_tool_use_failure.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PostToolUseFailure < Base
+    def self.hook_type
+      'PostToolUseFailure'
+    end
+
+    def self.input_fields
+      %w[tool_name tool_input tool_use_id error]
+    end
+
+    def tool_name
+      @input_data['tool_name']
+    end
+
+    def tool_input
+      @input_data['tool_input']
+    end
+
+    def tool_use_id
+      @input_data['tool_use_id'] || @input_data['toolUseId']
+    end
+
+    def error
+      @input_data['error']
+    end
+
+    def is_interrupt
+      @input_data.key?('is_interrupt') ? @input_data['is_interrupt'] : @input_data['isInterrupt']
+    end
+    alias_method :interrupt?, :is_interrupt
+
+    def duration_ms
+      @input_data['duration_ms'] || @input_data['durationMs']
+    end
+
+    def add_additional_context!(context)
+      @output_data['hookSpecificOutput'] ||= { 'hookEventName' => hook_event_name }
+      @output_data['hookSpecificOutput']['additionalContext'] = context
+    end
+  end
+end

data/lib/claude_hooks/pre_compact.rb

@@ -27,6 +27,13 @@ module ClaudeHooks
       end
     end
 
+    # === OUTPUT DATA HELPERS ===
+
+    def block!(reason = '')
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = reason
+    end
+
     # === UTILITY HELPERS ===
 
     def backup_transcript!(backup_file_path)