claude_hooks 0.2.1 → 1.0.2

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

@@ -2,7 +2,8 @@
 
 require 'claude_hooks'
 
-# Hook script that appends rules to user prompt
+# Hook script that appends rules to user prompt as additional context.
+# A great way to make sure specific context is added with each user prompt.
 class AppendRules < ClaudeHooks::UserPromptSubmit
 
   def call
@@ -18,7 +19,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/plugins/README.md

@@ -0,0 +1,175 @@
+# Plugin Hooks Examples
+
+This directory demonstrates how to use the Claude Hooks Ruby DSL when creating plugin hooks for [Claude Code plugins](https://docs.claude.com/en/docs/claude-code/plugins).
+
+## Overview
+
+The Claude Hooks DSL works seamlessly with plugin development! When creating plugins, you can use the exact same Ruby DSL as you would for regular hooks. The only difference is that plugin hooks are referenced through `${CLAUDE_PLUGIN_ROOT}` in the plugin's `hooks/hooks.json` configuration file.
+
+## Benefits of Using This DSL in Plugins
+
+- ✨ **Same powerful abstractions** - All the helper methods, logging, and state management work identically
+- 🔄 **Automatic output handling** - `output_and_exit` manages streams and exit codes correctly
+- 📝 **Built-in logging** - Session-specific logs work out of the box
+- 🛠️ **Configuration access** - Access both plugin and project configurations
+- 🎯 **Type safety** - Strong typed hook classes for each event type
+
+## Example Plugin Structure
+
+```
+my-formatter-plugin/
+├── .claude-plugin/
+│   └── plugin.json           # Plugin metadata
+├── hooks/
+│   ├── hooks.json            # Hook configuration (references scripts)
+│   └── scripts/
+│       └── formatter.rb      # Hook script using ClaudeHooks DSL
+└── README.md
+```
+
+## Example: Code Formatter Plugin
+
+### Plugin Configuration (`hooks/hooks.json`)
+
+```json
+{
+  "description": "Automatic code formatting on file writes",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/formatter.rb",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook Script (`hooks/scripts/formatter.rb`)
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class PluginFormatter < ClaudeHooks::PostToolUse
+  def call
+    log "Plugin formatter executing from: #{ENV['CLAUDE_PLUGIN_ROOT']}"
+
+    # Only format code files
+    file_path = tool_input['file_path']
+    return output unless should_format?(file_path)
+
+    log "Formatting file: #{file_path}"
+
+    # Perform formatting (example)
+    if format_file(file_path)
+      add_additional_context!("File formatted successfully: #{file_path}")
+    else
+      log "Failed to format #{file_path}", level: :warn
+    end
+
+    output
+  end
+
+  private
+
+  def should_format?(file_path)
+    # Example: only format Ruby files
+    file_path.end_with?('.rb')
+  end
+
+  def format_file(file_path)
+    # Your formatting logic here
+    # For example, using rubocop or prettier
+    return true  # Simulated success
+  end
+end
+
+if __FILE__ == $0
+  input_data = JSON.parse(STDIN.read)
+  hook = PluginFormatter.new(input_data)
+  hook.call
+  hook.output_and_exit
+end
+```
+
+## Environment Variables in Plugins
+
+When your hook scripts run as part of a plugin, these environment variables are available:
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_PLUGIN_ROOT` | Absolute path to the plugin directory |
+| `CLAUDE_PROJECT_DIR` | Project root directory (where Claude Code was started) |
+| `RUBY_CLAUDE_HOOKS_*` | All standard configuration environment variables |
+
+### Accessing Plugin Root in Your Hooks
+
+```ruby
+class MyPluginHook < ClaudeHooks::PreToolUse
+  def call
+    # Access plugin root
+    plugin_root = ENV['CLAUDE_PLUGIN_ROOT']
+    log "Plugin root: #{plugin_root}"
+
+    # Load plugin-specific config files
+    plugin_config_path = File.join(plugin_root, 'config', 'settings.json')
+
+    # Your hook logic here
+    output
+  end
+end
+```
+
+## Best Practices for Plugin Hooks
+
+1. **Keep hooks focused** - Each hook should have a single, well-defined purpose
+2. **Use logging extensively** - Helps users debug plugin behavior
+3. **Handle errors gracefully** - Don't crash on unexpected input
+4. **Document environment requirements** - If your plugin needs external tools (rubocop, prettier, etc.)
+5. **Test thoroughly** - Test with various file types and scenarios
+
+## Testing Plugin Hooks Locally
+
+You can test your plugin hooks before publishing:
+
+```bash
+# Test the hook script directly
+echo '{"session_id":"test","transcript_path":"/tmp/test","cwd":"/tmp","hook_event_name":"PostToolUse","tool_name":"Write","tool_input":{"file_path":"test.rb"},"tool_response":{"success":true}}' | CLAUDE_PLUGIN_ROOT=/path/to/plugin ruby hooks/scripts/formatter.rb
+```
+
+Or use the CLI test runner:
+
+```ruby
+#!/usr/bin/env ruby
+require 'claude_hooks'
+
+class PluginFormatter < ClaudeHooks::PostToolUse
+  # ... your implementation ...
+end
+
+if __FILE__ == $0
+  ClaudeHooks::CLI.run_with_sample_data(PluginFormatter) do |input_data|
+    input_data['tool_name'] = 'Write'
+    input_data['tool_input'] = { 'file_path' => 'test.rb' }
+    input_data['tool_response'] = { 'success' => true }
+  end
+end
+```
+
+## Resources
+
+- [Official Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
+- [Plugin Components Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference#hooks)
+- [Hooks API Reference](../../docs/API/)
+- [Claude Hooks Main README](../../README.md)
+
+## Contributing Examples
+
+If you create a plugin using this DSL, consider contributing an example! Open a PR or issue on the [claude_hooks repository](https://github.com/gabriel-dehan/claude_hooks).

data/example_dotclaude/settings.json

@@ -4,6 +4,17 @@
     "allow": []
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/entrypoints/pre_tool_use.rb"
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "matcher": "",
@@ -14,6 +25,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

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