claude_hooks 1.2.1 → 1.4.0

data/docs/mitts/prd.md

@@ -102,6 +102,14 @@ The `pr-review` action loads `AGENTS.md` (via its own `load_project_skills` call
 but does not use `agent_task.py`, so it doesn't have cross-run memory or the
 guardrail hook.
 
+The workflow runs the upstream review script (`plugins/pr-review/scripts/agent_script.py`,
+pinned to an `OpenHands/extensions` commit) through `.github/mitts/pr_review_entry.py`.
+The upstream script can't pass extra request headers, and the OpenCode gateway rejects
+requests without `x-opencode-session`. So the wrapper adds the same headers as
+`agent_task.py`: `User-Agent: mitts-agent/1.0`, plus `x-opencode-session` set to
+`OPENHANDS_CONVERSATION_KEY` (`pr-review-<number>`). The wrapper is checked out from the
+default branch, never from the PR under review.
+
 ### Issue and PR bots — `agent_task.py`
 
 There is no turnkey OpenHands Action for "issue → PR" or "PR follow-up", so these

data/docs/mitts/setup.md

@@ -267,9 +267,11 @@ reference:
 - `OPENHANDS_CONVERSATION_KEY` — per-thread key for the artifact (e.g. `pr-42`,
   `issue-7`).
 
-The `mitts-pr-review.yml` review action also accepts an `extensions-version:`
-input (currently `main`) — pin it to a tag/SHA alongside `EXTENSIONS_REF` when
-you want reproducible reviews.
+`mitts-pr-review.yml` sets its own `OPENHANDS_CONVERSATION_KEY` (`pr-review-<number>`),
+which `.github/mitts/pr_review_entry.py` sends as the `x-opencode-session` header. It
+pins the `OpenHands/extensions` checkout to a commit SHA. When you bump that SHA, check
+that the upstream `agent_script.py` still builds its LLM with `openhands.sdk.LLM(...)`,
+because the wrapper relies on it.
 
 ---
 

data/lib/claude_hooks/base.rb

@@ -92,6 +92,14 @@ module ClaudeHooks
       @input_data.dig('effort', 'level')
     end
 
+    # Path to the session's scratchpad directory. Absent when the session has no
+    # scratchpad or the temp directory is unavailable. Requires Claude Code v2.1.257+.
+    # Intentionally not in COMMON_INPUT_FIELDS: it is version-gated and often absent,
+    # so it must not trigger the missing-field warning in validate_input!.
+    def scratchpad_dir
+      @input_data['scratchpad_dir'] || @input_data['scratchpadDir']
+    end
+
     def read_transcript
       unless transcript_path && File.exist?(transcript_path)
         log "Transcript file not found at #{transcript_path}", level: :warn
@@ -120,10 +128,14 @@ module ClaudeHooks
     end
 
     # Hide stdout from transcript mode (default: false)
+    #
+    # DEPRECATED: Claude Code accepts the `suppressOutput` field but no longer acts
+    # on it (it has no effect). Kept for backward compatibility; safe to call, but a no-op.
     def suppress_output!
       @output_data['suppressOutput'] = true
     end
 
+    # DEPRECATED: see suppress_output! — `suppressOutput` is now a no-op in Claude Code.
     def show_output!
       @output_data['suppressOutput'] = false
     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,12 @@ module ClaudeHooks
           ElicitationResult.new(data)
         when 'WorktreeCreate'
           WorktreeCreate.new(data)
+        when 'DirectoryAdded'
+          DirectoryAdded.new(data)
+        when 'PreModelSwitch'
+          PreModelSwitch.new(data)
+        when 'PostModelSwitch'
+          PostModelSwitch.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/output/notification.rb

@@ -6,9 +6,18 @@ module ClaudeHooks
   module Output
     class Notification < Base
       # === EXIT CODE LOGIC ===
+      #
+      # Claude Code ignores Notification's exit code and stderr, and discards
+      # `systemMessage`/`continue`, while still emitting `terminalSequence`.
+      # So always exit 0 and write JSON to stdout, keeping the desktop-notification
+      # (`terminal_sequence!`) pattern working even when a handler set continue:false.
 
       def exit_code
-        default_exit_code
+        0
+      end
+
+      def output_stream
+        :stdout
       end
 
       # === MERGE HELPER ===

data/lib/claude_hooks/output/post_model_switch.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    # PostModelSwitch is context-only — it can't block, because the model has
+    # already changed. Its stdout is shown to Claude as additional context.
+    class PostModelSwitch < 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
+
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'PostModelSwitch',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/post_tool_batch.rb

@@ -33,6 +33,7 @@ module ClaudeHooks
         merged = super(*outputs)
         merged_data = merged.data
         reasons = []
+        contexts = []
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
@@ -41,9 +42,18 @@ module ClaudeHooks
             r = output_data['reason']
             reasons << r if r && !r.empty?
           end
+
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          contexts << context if context && !context.empty?
         end
 
         merged_data['reason'] = reasons.join('; ') if reasons.any?
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'PostToolBatch',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
         new(merged_data)
       end
     end

data/lib/claude_hooks/output/post_tool_use.rb

@@ -27,6 +27,10 @@ module ClaudeHooks
         hook_specific_output['updatedMCPToolOutput']
       end
 
+      def classifier_context
+        hook_specific_output['classifierContext'] || ''
+      end
+
       # === SEMANTIC HELPERS ===
 
       def blocked?
@@ -64,6 +68,11 @@ module ClaudeHooks
         merged = super(*outputs)
         merged_data = merged.data
         contexts = []
+        classifier_contexts = []
+        # Tool-output rewrites: last non-nil wins (most recent transformation), as with
+        # PreToolUse's updatedInput. Dropping them would let e.g. a redacted output
+        # revert to the original when composed with another handler.
+        rewrites = {}
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
@@ -72,13 +81,22 @@ module ClaudeHooks
 
           context = output_data.dig('hookSpecificOutput', 'additionalContext')
           contexts << context if context && !context.empty?
+
+          classifier_context = output_data.dig('hookSpecificOutput', 'classifierContext')
+          classifier_contexts << classifier_context if classifier_context && !classifier_context.empty?
+
+          %w[updatedToolOutput updatedMCPToolOutput].each do |key|
+            value = output_data.dig('hookSpecificOutput', key)
+            rewrites[key] = value unless value.nil?
+          end
         end
 
-        unless contexts.empty?
-          merged_data['hookSpecificOutput'] = {
-            'hookEventName' => 'PostToolUse',
-            'additionalContext' => contexts.join("\n\n")
-          }
+        if !contexts.empty? || !classifier_contexts.empty? || !rewrites.empty?
+          hso = { 'hookEventName' => 'PostToolUse' }
+          hso['additionalContext'] = contexts.join("\n\n") unless contexts.empty?
+          hso['classifierContext'] = classifier_contexts.join("\n\n") unless classifier_contexts.empty?
+          hso.merge!(rewrites)
+          merged_data['hookSpecificOutput'] = hso
         end
 
         new(merged_data)

data/lib/claude_hooks/output/pre_model_switch.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  module Output
+    class PreModelSwitch < Base
+      # === PERMISSION DECISION ACCESSORS ===
+
+      def permission_decision
+        hook_specific_output['permissionDecision']
+      end
+
+      def permission_reason
+        hook_specific_output['permissionDecisionReason'] || ''
+      end
+
+      # === TOP-LEVEL DECISION ACCESSORS ===
+
+      def decision
+        @data['decision']
+      end
+
+      def reason
+        @data['reason'] || ''
+      end
+
+      # === SEMANTIC HELPERS ===
+
+      def allowed?
+        permission_decision == 'allow'
+      end
+
+      def denied?
+        permission_decision == 'deny'
+      end
+
+      # Blocked when denied via permissionDecision OR via top-level decision:block.
+      def blocked?
+        denied? || decision == 'block'
+      end
+
+      def should_ask?
+        permission_decision == 'ask'
+      end
+      alias should_ask_permission? should_ask?
+
+      # === EXIT CODE LOGIC ===
+      #
+      # PreModelSwitch uses the advanced JSON API with exit code 0.
+      # As on PreToolUse, structured JSON with permissionDecision always goes to
+      # stdout with exit 0; the decision fields control whether the switch proceeds.
+      def exit_code
+        0
+      end
+
+      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
+
+        # PreModelSwitch precedence: deny > ask > allow (most restrictive wins).
+        # Stays nil when no hook decided, so the merge doesn't invent an 'allow'.
+        permission_decision = nil
+        permission_reasons = []
+        block_reasons = []
+        any_block = false
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+
+          if output_data['decision'] == 'block'
+            any_block = true
+            block_reasons << output_data['reason'] if output_data['reason'] && !output_data['reason'].empty?
+          end
+
+          current_decision = output_data.dig('hookSpecificOutput', 'permissionDecision')
+          case current_decision
+          when 'deny'
+            permission_decision = 'deny'
+          when 'ask'
+            permission_decision = 'ask' unless permission_decision == 'deny'
+          when 'allow'
+            permission_decision ||= 'allow'
+          end
+
+          reason = output_data.dig('hookSpecificOutput', 'permissionDecisionReason')
+          permission_reasons << reason if reason && !reason.empty?
+        end
+
+        # A top-level block cancels the switch, so the merged permissionDecision
+        # must agree with it instead of saying 'allow'.
+        permission_decision = 'deny' if any_block && permission_decision
+
+        if permission_decision
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'PreModelSwitch',
+            'permissionDecision' => permission_decision,
+            'permissionDecisionReason' => permission_reasons.join('; ')
+          }
+        end
+
+        if any_block
+          merged_data['decision'] = 'block'
+          merged_data['reason'] = block_reasons.join('; ') unless block_reasons.empty?
+        end
+
+        new(merged_data)
+      end
+    end
+  end
+end

data/lib/claude_hooks/output/pre_tool_use.rb

@@ -111,6 +111,14 @@ module ClaudeHooks
 
         merged_data['hookSpecificOutput']['updatedInput'] = updated_inputs.last if updated_inputs.any?
 
+        # Join every handler's additionalContext, as the other context-carrying merges do.
+        contexts = compacted_outputs.filter_map do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          context unless context.nil? || context.empty?
+        end
+        merged_data['hookSpecificOutput']['additionalContext'] = contexts.join("\n\n") if contexts.any?
+
         new(merged_data)
       end
     end

data/lib/claude_hooks/output/task_created.rb

@@ -5,13 +5,46 @@ require_relative 'base'
 module ClaudeHooks
   module Output
     class TaskCreated < Base
+      # === DECISION ACCESSORS ===
+      #
+      # Claude Code ignores `continue: false` for TaskCreated; block via exit 2 or
+      # a top-level decision:block.
+
+      def decision
+        @data['decision']
+      end
+
+      def reason
+        @data['reason'] || ''
+      end
+
+      def blocked?
+        decision == 'block'
+      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)
-        new(merged.data)
+        merged_data = merged.data
+        reasons = []
+
+        compacted_outputs.each do |output|
+          output_data = output.respond_to?(:data) ? output.data : output
+          merged_data['decision'] = 'block' if output_data['decision'] == 'block'
+          reason = output_data['reason']
+          reasons << reason if reason && !reason.empty?
+        end
+
+        merged_data['reason'] = reasons.join('; ') unless reasons.empty?
+
+        new(merged_data)
       end
     end
   end

data/lib/claude_hooks/output/user_prompt_expansion.rb

@@ -33,6 +33,7 @@ module ClaudeHooks
         merged = super(*outputs)
         merged_data = merged.data
         reasons = []
+        contexts = []
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
@@ -41,9 +42,18 @@ module ClaudeHooks
             r = output_data['reason']
             reasons << r if r && !r.empty?
           end
+
+          context = output_data.dig('hookSpecificOutput', 'additionalContext')
+          contexts << context if context && !context.empty?
         end
 
         merged_data['reason'] = reasons.join('; ') if reasons.any?
+        unless contexts.empty?
+          merged_data['hookSpecificOutput'] = {
+            'hookEventName' => 'UserPromptExpansion',
+            'additionalContext' => contexts.join("\n\n")
+          }
+        end
         new(merged_data)
       end
     end

data/lib/claude_hooks/output/user_prompt_submit.rb

@@ -19,6 +19,14 @@ module ClaudeHooks
         hook_specific_output['additionalContext'] || ''
       end
 
+      def session_title
+        hook_specific_output['sessionTitle']
+      end
+
+      def suppress_original_prompt?
+        hook_specific_output['suppressOriginalPrompt'] == true
+      end
+
       # === SEMANTIC HELPERS ===
 
       def blocked?
@@ -53,22 +61,27 @@ module ClaudeHooks
         merged_data = merged.data
 
         contexts = []
+        specific = {}
 
         compacted_outputs.each do |output|
           output_data = output.respond_to?(:data) ? output.data : output
+          hso = output_data['hookSpecificOutput'] || {}
 
           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')
+          context = hso['additionalContext']
           contexts << context if context && !context.empty?
+
+          # Last non-nil title wins; suppressing the prompt wins if any hook asks for it.
+          specific['sessionTitle'] = hso['sessionTitle'] unless hso['sessionTitle'].nil?
+          specific['suppressOriginalPrompt'] = true if hso['suppressOriginalPrompt'] == true
         end
 
-        unless contexts.empty?
-          merged_data['hookSpecificOutput'] = {
-            'hookEventName' => 'UserPromptSubmit',
-            'additionalContext' => contexts.join("\n\n")
-          }
+        specific['additionalContext'] = contexts.join("\n\n") unless contexts.empty?
+
+        unless specific.empty?
+          merged_data['hookSpecificOutput'] = { 'hookEventName' => 'UserPromptSubmit' }.merge(specific)
         end
 
         new(merged_data)

data/lib/claude_hooks/output/worktree_remove.rb

@@ -4,10 +4,12 @@ require_relative 'base'
 
 module ClaudeHooks
   module Output
-    # WorktreeRemove is non-blocking — only suppressOutput is honored.
+    # WorktreeRemove can block: a non-zero exit code now fails the worktree
+    # removal when the directory still exists (Claude Code no longer ignores it).
+    # Use prevent_continue!(reason) to block; exit code follows continue (0/2).
     class WorktreeRemove < Base
       def exit_code
-        0
+        default_exit_code
       end
 
       def self.merge(*outputs)

data/lib/claude_hooks/permission_denied.rb

@@ -24,6 +24,13 @@ module ClaudeHooks
       @input_data['tool_use_id'] || @input_data['toolUseId']
     end
 
+    # For MCP tools: { 'name' => ..., 'source' => ... } describing where the server's
+    # definition came from (e.g. 'plugin', 'sdk', 'user', 'project'). Base trust
+    # decisions on 'source', not on the name. nil for non-MCP tools. Requires Claude Code v2.1.274+.
+    def mcp_server
+      @input_data['mcp_server'] || @input_data['mcpServer']
+    end
+
     def reason
       @input_data['reason']
     end

data/lib/claude_hooks/permission_request.rb

@@ -9,7 +9,7 @@ module ClaudeHooks
     end
 
     def self.input_fields
-      %w[tool_name tool_input tool_use_id]
+      %w[tool_name tool_input]
     end
 
     # === INPUT DATA ACCESS ===
@@ -22,10 +22,19 @@ module ClaudeHooks
       @input_data['tool_input']
     end
 
+    # DEPRECATED: Claude Code doesn't send tool_use_id to PermissionRequest hooks, so this
+    # is always nil. Kept for backward compatibility; not part of input_fields.
     def tool_use_id
       @input_data['tool_use_id'] || @input_data['toolUseId']
     end
 
+    # For MCP tools: { 'name' => ..., 'source' => ... } describing where the server's
+    # definition came from (e.g. 'plugin', 'sdk', 'user', 'project'). Base trust
+    # decisions on 'source', not on the name. nil for non-MCP tools. Requires Claude Code v2.1.274+.
+    def mcp_server
+      @input_data['mcp_server'] || @input_data['mcpServer']
+    end
+
     def permission_suggestions
       @input_data['permissionSuggestions'] || @input_data['permission_suggestions'] || []
     end

data/lib/claude_hooks/post_model_switch.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PostModelSwitch < Base
+    def self.hook_type
+      'PostModelSwitch'
+    end
+
+    def self.input_fields
+      %w[from_model to_model requested_model source]
+    end
+
+    # === INPUT DATA ACCESS ===
+    #
+    # PostModelSwitch receives the same fields as PreModelSwitch, with two extra
+    # `source` values ("auto", "resume"). `requested_model` is null when source is
+    # "auto", and the restored setting when source is "resume".
+
+    def from_model
+      @input_data['from_model'] || @input_data['fromModel']
+    end
+
+    def to_model
+      @input_data['to_model'] || @input_data['toModel']
+    end
+
+    def requested_model
+      @input_data['requested_model'] || @input_data['requestedModel']
+    end
+
+    def source
+      @input_data['source']
+    end
+
+    def context_tokens
+      @input_data['context_tokens'] || @input_data['contextTokens']
+    end
+
+    def prompt_cache_warm
+      @input_data.key?('prompt_cache_warm') ? @input_data['prompt_cache_warm'] : @input_data['promptCacheWarm']
+    end
+
+    def cache_ttl
+      @input_data['cache_ttl'] || @input_data['cacheTtl']
+    end
+
+    def estimated_cache_write_usd
+      @input_data['estimated_cache_write_usd'] || @input_data['estimatedCacheWriteUsd']
+    end
+
+    def pricing
+      @input_data['pricing']
+    end
+
+    # === OUTPUT DATA HELPERS ===
+    #
+    # PostModelSwitch can't block (the model already changed); it only adds context.
+    # Its stdout is also shown to Claude as context.
+
+    def add_additional_context!(context)
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'additionalContext' => context
+      }
+    end
+    alias_method :add_context!, :add_additional_context!
+  end
+end