claude_hooks 0.2.1 → 1.0.0

data/docs/OUTPUT_MIGRATION_GUIDE.md

@@ -0,0 +1,228 @@
+# Migration Guide: Using Output Objects
+
+This guide shows how to migrate from the old manual exit code patterns to the new simplified output object system.
+
+## Problem: The Old Way (Before)
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+require_relative '../handlers/pre_tool_use/github_guard'
+
+begin
+  # Read Claude Code input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  github_guard = GithubGuard.new(input_data)
+  guard_output = github_guard.call
+
+  # MANUAL: Extract hook-specific decision
+  hook_specific_decision = guard_output['hookSpecificOutput']['permissionDecision']
+  is_allowed_to_continue = guard_output['continue'] != false
+  final_output = github_guard.stringify_output
+
+  # MANUAL: Complex exit logic that you need to understand and get right
+  if is_allowed_to_continue
+    case hook_specific_decision
+    when 'block'
+      STDERR.puts final_output
+      exit 1
+    when 'ask'
+      STDERR.puts final_output
+      exit 2
+    else
+      puts final_output
+      exit 0
+    end
+  else
+    STDERR.puts final_output
+    exit 1
+  end
+rescue StandardError => e
+  # MANUAL: Error handling with manual JSON generation and stream selection
+  puts JSON.generate({
+    continue: false,
+    stopReason: "PreToolUser Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 0 # Allow anyway to not block developers if there is an issue
+end
+```
+
+**Problems with this approach:**
+- 30+ lines of repetitive boilerplate
+- Need to understand Claude Code's internal exit code semantics
+- Manual stream selection (STDOUT vs STDERR)
+- Error-prone - easy to get exit codes wrong
+- Need to manually extract hook-specific data from nested hashes
+
+## Solution: The New Way (After)
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+require_relative '../handlers/pre_tool_use/github_guard'
+
+begin
+  # Read Claude Code input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  github_guard = GithubGuard.new(input_data)
+  github_guard.call
+
+  # NEW: One line handles everything!
+  github_guard.output_and_exit
+
+rescue StandardError => e
+  # NEW: Simple error handling
+  error_output = ClaudeHooks::Output::PreToolUse.new({
+    'continue' => false,
+    'stopReason' => "Hook execution error: #{e.message}",
+    'suppressOutput' => false
+  })
+  error_output.output_and_exit  # Automatically uses STDERR and exit 1
+end
+```
+
+**Benefits:**
+- **10 lines instead of 30+** - 70% less code
+- **No Claude Code knowledge needed** - just use the gem's API
+- **Automatic exit codes** based on hook-specific logic
+- **Automatic stream selection** (STDOUT/STDERR)
+- **Type-safe access** to hook-specific fields
+
+## New Output Object API
+
+### PreToolUse Hooks
+
+```ruby
+hook = GithubGuard.new(input_data)
+hook.call
+output = hook.output
+
+# Clean semantic access
+puts "Permission: #{output.permission_decision}"  # 'allow', 'deny', or 'ask'
+puts "Reason: #{output.permission_reason}"
+puts "Allowed? #{output.allowed?}"
+puts "Should ask? #{output.should_ask_permission?}"
+
+# Automatic exit logic
+puts "Exit code: #{output.exit_code}"      # 0, 1, or 2 based on permission
+puts "Stream: #{output.output_stream}"     # :stdout or :stderr
+
+# One call handles everything
+hook.output_and_exit  # Prints JSON to correct stream and exits with correct code
+```
+
+### UserPromptSubmit Hooks
+
+```ruby
+hook = MyPromptHook.new(input_data)
+hook.call
+output = hook.output
+
+# Clean semantic access
+puts "Blocked? #{output.blocked?}"
+puts "Reason: #{output.reason}"
+puts "Context: #{output.additional_context}"
+
+# Automatic execution
+hook.output_and_exit # Handles all the exit logic
+```
+
+### Stop Hooks (Special Logic)
+
+```ruby
+hook = MyStopHook.new(input_data)
+hook.call
+output = hook.output
+
+# Note: Stop hooks have inverted logic - 'decision: block' means "continue working"
+puts "Should continue? #{output.should_continue?}"      # true if decision == 'block'
+puts "Continue instructions: #{output.continue_instructions}"
+
+hook.output_and_exit  # exit 1 for "continue", exit 0 for "stop"
+```
+
+## Merging Multiple Hooks
+
+```ruby
+# OLD WAY: Manual merging with class methods
+result1 = hook1.call
+result2 = hook2.call
+merged_hash = ClaudeHooks::PreToolUse.merge_outputs(result1, result2)
+# ... then manual exit logic
+
+# NEW WAY: Clean object-based merging
+hook1.call
+hook2.call
+merged_output = ClaudeHooks::Output::PreToolUse.merge(
+  hook1.output,
+  hook2.output
+)
+# /!\ Called on the merged output
+merged_output.output_and_exit  # Handles everything automatically
+```
+
+## Simplified Entrypoint Pattern
+
+### For Single Hooks
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+require_relative '../handlers/my_hook'
+
+# Super simple - just 3 lines!
+ClaudeHooks::CLI.entrypoint do |input_data|
+  hook = MyHook.new(input_data)
+  hook.call
+  hook.output_and_exit
+end
+```
+
+### For Multiple Hooks with Merging
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+require_relative '../handlers/hook1'
+require_relative '../handlers/hook2'
+
+ClaudeHooks::CLI.entrypoint do |input_data|
+  hook1 = Hook1.new(input_data)
+  hook2 = Hook2.new(input_data)
+  hook1.call
+  hook2.call
+  
+  merged = ClaudeHooks::Output::PreToolUse.merge(
+    hook1.output,
+    hook2.output
+  )
+  # /!\ Called on the merged output
+  merged.output_and_exit
+end
+```
+
+## All Supported Hook Types
+
+- `ClaudeHooks::Output::UserPromptSubmit`
+- `ClaudeHooks::Output::PreToolUse` 
+- `ClaudeHooks::Output::PostToolUse`
+- `ClaudeHooks::Output::Stop`
+- `ClaudeHooks::Output::SubagentStop`
+- `ClaudeHooks::Output::Notification`
+- `ClaudeHooks::Output::SessionStart`
+- `ClaudeHooks::Output::PreCompact`
+
+Each handles the specific exit code logic and semantic helpers for its hook type.
+
+## Migration Steps
+
+1. **Update your hook handlers** to return `output_data` (most already do)
+2. **Replace manual exit logic** with `hook.output_and_exit` or `output.output_and_exit`
+3. **Use semantic helpers** instead of digging through hash structures
+4. **Use output object merging** instead of class methods
+5. **Enjoy the simplified, cleaner code!**
+
+The old patterns still work for backward compatibility, but the new output objects make everything much cleaner and less error-prone.

data/example_dotclaude/hooks/entrypoints/session_end.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+require 'json'
+require_relative '../handlers/session_end/cleanup_handler'
+require_relative '../handlers/session_end/log_session_stats'
+
+begin
+  # Read input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  # Initialize handlers
+  cleanup_handler = CleanupHandler.new(input_data)
+  log_handler = LogSessionStats.new(input_data)
+
+  # Execute handlers
+  cleanup_handler.call
+  log_handler.call
+
+  # Merge outputs using the SessionEnd output merger
+  merged_output = ClaudeHooks::Output::SessionEnd.merge(
+    cleanup_handler.output,
+    log_handler.output
+  )
+
+  # Output result and exit with appropriate code
+  merged_output.output_and_exit
+
+rescue StandardError => e
+  STDERR.puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 2
+end

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -1,7 +1,13 @@
 #!/usr/bin/env ruby
 
+# Example of the NEW simplified entrypoint pattern using output objects
+# Compare this to the existing user_prompt_submit.rb to see the difference!
+
 require 'claude_hooks'
 require 'json'
+# Require the output classes
+require_relative '../../../lib/claude_hooks/output/base'
+require_relative '../../../lib/claude_hooks/output/user_prompt_submit'
 require_relative '../handlers/user_prompt_submit/append_rules'
 require_relative '../handlers/user_prompt_submit/log_user_prompt'
 
@@ -11,25 +17,24 @@ begin
 
   # Execute all hook scripts
   append_rules = AppendRules.new(input_data)
-  appended_rules_result = append_rules.call
+  append_rules.call
 
   log_user_prompt = LogUserPrompt.new(input_data)
-  log_user_prompt_result = log_user_prompt.call
+  log_user_prompt.call
 
-  # Merge all hook results intelligently using the UserPromptSubmit class method
-  hook_output = ClaudeHooks::UserPromptSubmit.merge_outputs(appended_rules_result, log_user_prompt_result)
+  merged_output = ClaudeHooks::Output::UserPromptSubmit.merge(
+    append_rules.output,
+    log_user_prompt.output
+  )
 
-  # Output final merged result to Claude Code
-  puts JSON.generate(hook_output)
+  merged_output.output_and_exit
 
-  exit 0 # Don't forget to exit with the right exit code (0, 1, 2)
 rescue StandardError => e
-  STDERR.puts "Error in UserPromptSubmit hook: #{e.message} #{e.backtrace.join("\n")}"
-
-  puts JSON.generate({
+  # Same simple error pattern
+  STDERR.puts JSON.generate({
     continue: false,
     stopReason: "Hook execution error: #{e.message} #{e.backtrace.join("\n")}",
     suppressOutput: false
   })
-  exit 1
-end
+  exit 2
+end

data/example_dotclaude/hooks/handlers/session_end/cleanup_handler.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require_relative '../../../../lib/claude_hooks'
+
+class CleanupHandler < ClaudeHooks::SessionEnd
+  def call
+    log "Session ended with reason: #{reason}"
+    
+    case reason
+    when 'clear'
+      log "Performing cleanup after /clear command"
+      cleanup_temp_files
+    when 'logout'
+      log "Performing cleanup after logout"
+      save_session_state
+    when 'prompt_input_exit'
+      log "User exited during prompt input"
+      save_partial_state
+    else
+      log "General session cleanup"
+      general_cleanup
+    end
+    
+    output
+  end
+
+  private
+
+  def cleanup_temp_files
+    log "Cleaning up temporary files for session #{session_id}"
+    # Example cleanup logic
+  end
+
+  def save_session_state
+    log "Saving session state for session #{session_id}"
+    # Example state saving logic
+  end
+
+  def save_partial_state
+    log "Saving partial state for session #{session_id}"
+    # Example partial state saving logic
+  end
+
+  def general_cleanup
+    log "Performing general cleanup for session #{session_id}"
+    # Example general cleanup logic
+  end
+end
+
+# CLI testing support
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(CleanupHandler) do |input_data|
+    input_data['reason'] ||= 'other'
+  end
+end

data/example_dotclaude/hooks/handlers/session_end/log_session_stats.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+
+class LogSessionStats < ClaudeHooks::SessionEnd
+  def call
+    log "Logging session statistics for session #{session_id}"
+    
+    # Generate session statistics
+    stats = gather_session_stats
+    
+    # Log detailed statistics
+    log <<~STATS
+      === Session Statistics ===
+      Session ID: #{session_id}
+      End Reason: #{reason}
+      Duration: #{stats[:duration]}
+      Working Directory: #{cwd}
+      Transcript Path: #{transcript_path}
+      ===========================
+    STATS
+    
+    # Log session summary
+    log format_session_summary(stats)
+    
+    output
+  end
+
+  private
+
+  def gather_session_stats
+    {
+      duration: calculate_session_duration,
+      end_time: Time.now,
+      transcript_size: get_transcript_size
+    }
+  end
+
+  def calculate_session_duration
+    # Example: could read session start time from transcript or file
+    "Unknown (would need session start time)"
+  end
+
+  def get_transcript_size
+    return 0 unless transcript_path && File.exist?(transcript_path)
+    
+    File.size(transcript_path)
+  rescue StandardError => e
+    log "Error getting transcript size: #{e.message}", level: :warn
+    0
+  end
+
+  def format_session_summary(stats)
+    "Session #{session_id} ended (#{reason}): #{stats[:transcript_size]} bytes transcript"
+  end
+end
+
+# CLI testing support
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(LogSessionStats) do |input_data|
+    input_data['reason'] ||= 'other'
+    input_data['transcript_path'] ||= '/tmp/test_transcript'
+  end
+end

data/example_dotclaude/hooks/handlers/user_prompt_submit/append_rules.rb

@@ -18,7 +18,7 @@ class AppendRules < ClaudeHooks::UserPromptSubmit
       log "No rule content found", level: :warn
     end
 
-    output_data
+    output
   end
 
   private

data/example_dotclaude/hooks/handlers/user_prompt_submit/log_user_prompt.rb

@@ -12,10 +12,10 @@ class LogUserPrompt < ClaudeHooks::UserPromptSubmit
 
     log <<~TEXT
       Prompt: #{current_prompt}
-      Logged user prompt to #{log_file_path}
+      Logged user prompt (session: #{session_id})
     TEXT
 
-    nil
+    nil # ignored output
   end
 end
 

data/example_dotclaude/settings.json

@@ -14,6 +14,17 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/entrypoints/session_end.rb"
+          }
+        ]
+      }
     ]
   },
   "env": {

data/lib/claude_hooks/base.rb

@@ -3,6 +3,7 @@
 require 'json'
 require_relative 'configuration'
 require_relative 'logger'
+require_relative 'output/base'
 
 module ClaudeHooks
   # Base class for Claude Code hook scripts
@@ -24,7 +25,7 @@ module ClaudeHooks
       self.class.hook_type
     end
 
-    attr_reader :config, :input_data, :output_data, :logger
+    attr_reader :config, :input_data, :output_data, :output, :logger
     def initialize(input_data = {})
       @config = Configuration
       @input_data = input_data
@@ -33,6 +34,7 @@ module ClaudeHooks
         'stopReason' => '',
         'suppressOutput' => false
       }
+      @output = ClaudeHooks::Output::Base.for_hook_type(hook_type, @output_data)
       @logger = Logger.new(session_id, self.class.name)
 
       validate_input!
@@ -47,6 +49,10 @@ module ClaudeHooks
       JSON.generate(@output_data)
     end
 
+    def output_and_exit
+      @output.output_and_exit
+    end
+    
     # === COMMON INPUT DATA ACCESS ===
 
     def session_id
@@ -105,6 +111,15 @@ module ClaudeHooks
       @output_data['hookSpecificOutput'] = nil
     end
 
+    # System message shown to the user (not to Claude)
+    def system_message!(message)
+      @output_data['systemMessage'] = message
+    end
+
+    def clear_system_message!
+      @output_data.delete('systemMessage')
+    end
+
     # === CONFIG AND UTILITY METHODS ===
 
     def base_dir
@@ -136,29 +151,6 @@ module ClaudeHooks
       @logger.log(message, level: level, &block)
     end
 
-    protected
-
-    # === MERGE HELPER BASE ===
-
-    # Handles common merging logic for all hook types
-    # Subclasses should call super and add their specific logic
-    def self.merge_outputs(*outputs_data)
-      compacted_outputs_data = outputs_data.compact
-      return { 'continue' => true, 'stopReason' => '', 'suppressOutput' => false } if compacted_outputs_data.empty?
-
-      # Initialize merged result with defaults
-      merged = { 'continue' => true, 'stopReason' => '', 'suppressOutput' => false }
-
-      # Apply common merge logic
-      compacted_outputs_data.each do |output|
-        merged['continue'] = false if output['continue'] == false
-        merged['stopReason'] = [merged['stopReason'], output['stopReason']].compact.reject(&:empty?).join('; ')
-        merged['suppressOutput'] = true if output['suppressOutput'] == true
-      end
-
-      merged
-    end
-
     private
 
     def validate_input!

data/lib/claude_hooks/cli.rb

@@ -89,6 +89,78 @@ module ClaudeHooks
         run_hook(hook_class, merged_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
+        
+      rescue StandardError => e
+        STDERR.puts "Hook execution error: #{e.message}"
+        STDERR.puts e.backtrace.join("\n") if e.backtrace
+        
+        error_response = {
+          continue: false,
+          stopReason: "Hook execution error: #{e.message}",
+          suppressOutput: false
+        }
+        response = JSON.generate(error_response)
+        puts response
+        STDERR.puts response
+        exit 1
+      end
+
       private
 
       def read_stdin_input
@@ -111,7 +183,9 @@ module ClaudeHooks
           suppressOutput: false
         }
 
-        puts JSON.generate(error_response)
+        response = JSON.generate(error_response)
+        puts response
+        STDERR.puts response
         exit 1
       end
     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