claude_hooks 0.1.1

data/WHY.md

@@ -0,0 +1,65 @@
+# Why is this DSL useful?
+
+When creating fairly complex hook systems for Claude Code it is easy to end up either with:
+- Fairly monolithic scripts that becomes hard to maintain and have to handle complex merging logic for the output.
+- A lot of scripts set up in the `settings.json` that all use the same hook input / output logic that needs to be rewritten multiple times.
+
+Furthermore, Claude's documentation on hooks is a bit hard to navigate and setting up hooks is not necessarily intuitive or straightforward having to play around with STDIN, STDOUT, STDERR, exit codes, etc.
+
+This DSL enables the easy creation of composable, testable handlers that can be easily maintained and reused and is suited for both a monolithic approach (using entrypoints and handlers) or a modular one (using handlers only).
+
+```bash
+# Monolithic approach (Recommended)
+settings.json
+└── [On PreToolUse Hook] -> entrypoints/pre_tool_use.rb
+    ├── calls handlers/pre_tool_use/danger_check.rb
+    ├── calls handlers/pre_tool_use/audit_logger.rb
+    └── calls handlers/pre_tool_use/permission_guard.rb
+
+# Modular approach
+settings.json
+├── [On PreToolUse Hook] -> handlers/pre_tool_use/danger_check.rb
+├── [On PreToolUse Hook] -> handlers/pre_tool_use/audit_logger.rb
+└── [On PreToolUse Hook] -> handlers/pre_tool_use/permission_guard.rb
+```
+
+## For both approaches it will bring
+
+1. Normalized Input/Output handling - input parsing, validation, straightforward output helpers (block_tool!, add_context!).
+
+2. Hook-Specific APIs - 8 different hook types with tailored methods (e.g., ask_for_permission! vs block_tool!) and smart merge logic for combining outputs.
+
+3. Session-Based Logging - Dedicated logger to understand the flow of what happens in Claude Code and write it out to a `session-{session_id}.log` file.
+
+4. Configuration Management - Centralized config and helpers for use across the hook system.
+
+5. Testing Support - Standalone execution mode for individual hook testing and CLI testing with sample JSON input.
+
+
+## For a monolithic approach it will additionally bring
+
+1. Composable Hook Handlers
+For instance, `entrypoints/user_prompt_submit.rb` orchestrates multiple handlers in one place:
+```ruby
+# Add contextual rules
+append_rules_result = AppendRules.new(input_data).call
+# Audit logging
+log_result = LogUserPrompt.new(input_data).call
+
+# Merge outputs to Claude Code
+puts ClaudeHooks::UserPromptSubmit.merge_outputs(append_rules_result, log_result)
+```
+
+2. Intelligent Output Merging
+- Each hook handler can return different decisions (block, context additions, etc.)
+- The framework intelligently merges conflicting decisions (e.g., any handler can block)
+- Combines multiple contexts cleanly
+
+3. Individual Handler Testability
+Each handler can run standalone for testing:
+```ruby
+if __FILE__ == $0
+  hook = AppendRules.new(JSON.parse(STDIN.read))
+  puts hook.stringify_output
+end
+```

data/claude_hooks.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/claude_hooks/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "claude_hooks"
+  spec.version = ClaudeHooks::VERSION
+  spec.authors = ["Gabriel Dehan"]
+  spec.email = ["dehan.gabriel@gmail.com"]
+
+  spec.summary = "Ruby DSL for creating Claude Code hooks"
+  spec.description = "A Ruby DSL framework for creating Claude Code hooks with composable hook scripts that enable teams to easily implement logging, security checks, and workflow automation."
+  spec.homepage = "https://github.com/gabriel-dehan/claude_hooks"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "json", "~> 2.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+
+# Hook script that appends rules to user prompt
+class AppendRules < ClaudeHooks::UserPromptSubmit
+
+  def call
+    log "Executing AppendRules hook"
+
+    # Read the rule content
+    rule_content = read_rule_content
+
+    if rule_content
+      add_additional_context!(rule_content)
+      log "Successfully added rule content as additional context (#{rule_content.length} characters)"
+    else
+      log "No rule content found", level: :warn
+    end
+
+    output_data
+  end
+
+  private
+
+  def read_rule_content
+    rule_file_path = path_for('rules/post-user-prompt.rule.md')
+
+    if File.exist?(rule_file_path)
+      content = File.read(rule_file_path).strip
+      return content unless content.empty?
+    end
+
+    log "Rule file not found or empty at: #{rule_file_path}", level: :warn
+    log "Base directory: #{base_dir}"
+    nil
+  end
+end
+
+# If this file is run directly (for testing), call the hook script
+if __FILE__ == $0
+  begin
+    require 'json'
+
+    input_data = JSON.parse(STDIN.read)
+    hook = AppendRules.new(input_data)
+    hook.call
+    puts hook.stringify_output
+  rescue JSON::ParserError => e
+    STDERR.puts "Error parsing JSON: #{e.message}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "JSON parsing error in AppendRules: #{e.message}",
+      suppressOutput: false
+    })
+    exit 0
+  rescue StandardError => e
+    STDERR.puts "Error in AppendRules hook: #{e.message}, #{e.backtrace.join("\n")}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "AppendRules execution error: #{e.message}",
+      suppressOutput: false
+    })
+    exit 0
+  end
+end

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+require 'fileutils'
+require 'claude_hooks'
+
+# Example hook module that logs user prompts to a file
+class LogUserPrompt < ClaudeHooks::UserPromptSubmit
+
+  def call
+    log "Executing LogUserPrompt hook"
+
+    # Log the prompt to a file (just as an example)
+    log_file_path = path_for('logs/user_prompts.log')
+    ensure_log_directory_exists
+
+    timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+
+    log <<~TEXT
+      Prompt: #{current_prompt}
+      Logged user prompt to #{log_file_path}
+    TEXT
+
+    nil
+  end
+
+  private
+
+  def ensure_log_directory_exists
+    log_dir = path_for('logs')
+    FileUtils.mkdir_p(log_dir) unless Dir.exist?(log_dir)
+  end
+end
+
+# If this file is run directly (for testing), call the hook
+if __FILE__ == $0
+  begin
+    require 'json'
+
+    hook = LogUserPrompt.new(JSON.parse(STDIN.read))
+    hook.call
+  rescue StandardError => e
+    STDERR.puts "Error in LogUserPrompt hook: #{e.message}, #{e.backtrace.join("\n")}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "LogUserPrompt execution error: #{e.message}",
+      suppressOutput: false
+    })
+    exit 0
+  end
+end

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+require 'json'
+require_relative '../user_prompt_submit/append_rules'
+require_relative '../user_prompt_submit/log_user_prompt'
+
+begin
+  # Read input from stdin
+  input_data = JSON.parse(STDIN.read)
+
+  # Execute all hook scripts
+  append_rules = AppendRules.new(input_data)
+  appended_rules_result = append_rules.call
+
+  log_user_prompt = LogUserPrompt.new(input_data)
+  log_user_prompt_result = 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)
+
+  # Output final merged result to Claude Code
+  puts JSON.generate(hook_output)
+
+  exit 0
+rescue JSON::ParserError => e
+  STDERR.puts "Error parsing JSON: #{e.message}"
+
+  puts JSON.generate({
+    continue: false,
+    stopReason: "Hook JSON parsing error: #{e.message}",
+    suppressOutput: false
+  })
+  exit 1
+rescue StandardError => e
+  STDERR.puts "Error in UserPromptSubmit hook: #{e.message} #{e.backtrace.join("\n")}"
+
+  puts JSON.generate({
+    continue: false,
+    stopReason: "Hook execution error: #{e.message} #{e.backtrace.join("\n")}",
+    suppressOutput: false
+  })
+  exit 1
+end

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+
+# Hook script that appends rules to user prompt
+class AppendRules < ClaudeHooks::UserPromptSubmit
+
+  def call
+    log "Executing AppendRules hook"
+
+    # Read the rule content
+    rule_content = read_rule_content
+
+    if rule_content
+      add_additional_context!(rule_content)
+      log "Successfully added rule content as additional context (#{rule_content.length} characters)"
+    else
+      log "No rule content found", level: :warn
+    end
+
+    output_data
+  end
+
+  private
+
+  def read_rule_content
+    rule_file_path = path_for('rules/post-user-prompt.rule.md')
+
+    if File.exist?(rule_file_path)
+      content = File.read(rule_file_path).strip
+      return content unless content.empty?
+    end
+
+    log "Rule file not found or empty at: #{rule_file_path}", level: :warn
+    log "Base directory: #{base_dir}"
+    nil
+  end
+end
+
+# If this file is run directly (for testing), call the hook script
+if __FILE__ == $0
+  begin
+    require 'json'
+
+    input_data = JSON.parse(STDIN.read)
+    hook = AppendRules.new(input_data)
+    hook.call
+    puts hook.stringify_output
+  rescue JSON::ParserError => e
+    STDERR.puts "Error parsing JSON: #{e.message}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "JSON parsing error in AppendRules: #{e.message}",
+      suppressOutput: false
+    })
+    exit 0
+  rescue StandardError => e
+    STDERR.puts "Error in AppendRules hook: #{e.message}, #{e.backtrace.join("\n")}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "AppendRules execution error: #{e.message}",
+      suppressOutput: false
+    })
+    exit 0
+  end
+end

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+require 'fileutils'
+require 'claude_hooks'
+
+# Example hook module that logs user prompts to a file
+class LogUserPrompt < ClaudeHooks::UserPromptSubmit
+
+  def call
+    log "Executing LogUserPrompt hook"
+
+    # Log the prompt to a file (just as an example)
+    log_file_path = path_for('logs/user_prompts.log')
+    ensure_log_directory_exists
+
+    timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+
+    log <<~TEXT
+      Prompt: #{current_prompt}
+      Logged user prompt to #{log_file_path}
+    TEXT
+
+    nil
+  end
+
+  private
+
+  def ensure_log_directory_exists
+    log_dir = path_for('logs')
+    FileUtils.mkdir_p(log_dir) unless Dir.exist?(log_dir)
+  end
+end
+
+# If this file is run directly (for testing), call the hook
+if __FILE__ == $0
+  begin
+    require 'json'
+
+    hook = LogUserPrompt.new(JSON.parse(STDIN.read))
+    hook.call
+  rescue StandardError => e
+    STDERR.puts "Error in LogUserPrompt hook: #{e.message}, #{e.backtrace.join("\n")}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "LogUserPrompt execution error: #{e.message}",
+      suppressOutput: false
+    })
+    exit 0
+  end
+end

data/example_dotclaude/settings.json

@@ -0,0 +1,23 @@
+{
+  "includeCoAuthoredBy": false,
+  "permissions": {
+    "allow": []
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/entrypoints/user_prompt_submit.rb"
+          }
+        ]
+      }
+    ]
+  },
+  "env": {
+    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
+    "DISABLE_TELEMETRY": "1"
+  }
+}

data/lib/claude_hooks/base.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'configuration'
+require_relative 'logger'
+
+module ClaudeHooks
+  # Base class for Claude Code hook scripts
+  class Base
+    # Common input fields for all hook types
+    COMMON_INPUT_FIELDS = %w[session_id transcript_path cwd hook_event_name].freeze
+
+    # Override in subclasses to specify hook type
+    def self.hook_type
+      raise NotImplementedError, "Subclasses must define hook_type"
+    end
+
+    # Override in subclasses to specify hook-specific input fields
+    def self.input_fields
+      raise NotImplementedError, "Subclasses must define input_fields"
+    end
+
+    def hook_type
+      self.class.hook_type
+    end
+
+    attr_reader :config, :input_data, :output_data, :logger
+    def initialize(input_data = {})
+      @config = Configuration.config
+      @input_data = input_data
+      @output_data = {
+        'continue' => true,
+        'stopReason' => '',
+        'suppressOutput' => false
+      }
+      @logger = Logger.new(session_id, self.class.name)
+
+      validate_input!
+    end
+
+    # Main execution method - override in subclasses
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+    end
+
+    def stringify_output
+      JSON.generate(@output_data)
+    end
+
+    # === COMMON INPUT DATA ACCESS ===
+
+    def session_id
+      @input_data['session_id'] || 'claude-default-session'
+    end
+
+    def transcript_path
+      @input_data['transcript_path']
+    end
+
+    def cwd
+      @input_data['cwd']
+    end
+
+    def hook_event_name
+      @input_data['hook_event_name'] || @input_data['hookEventName'] || hook_type
+    end
+
+    def read_transcript
+      unless transcript_path && File.exist?(transcript_path)
+        log "Transcript file not found at #{transcript_path}", level: :warn
+        return ''
+      end
+
+      begin
+        File.read(transcript_path)
+      rescue => e
+        log "Error reading transcript file at #{transcript_path}: #{e.message}", level: :error
+        ''
+      end
+    end
+    alias_method :transcript, :read_transcript
+
+    # === COMMON OUTPUT HELPERS ===
+
+    # Allow Claude to continue (default: true)
+    def allow_continue!
+      @output_data['continue'] = true
+    end
+
+    def prevent_continue!(reason)
+      @output_data['continue'] = false
+      @output_data['stopReason'] = reason
+    end
+
+    # Hide stdout from transcript mode (default: false)
+    def suppress_output!
+      @output_data['suppressOutput'] = true
+    end
+
+    def show_output!
+      @output_data['suppressOutput'] = false
+    end
+
+    def clear_specifics!
+      @output_data['hookSpecificOutput'] = nil
+    end
+
+    # === CONFIG AND UTILITY METHODS ===
+
+    def base_dir
+      Configuration.base_dir
+    end
+
+    def path_for(relative_path)
+      Configuration.path_for(relative_path)
+    end
+
+    # Supports both single messages and blocks for multiline logging
+    def log(message = nil, level: :info, &block)
+      @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!
+      expected_fields = COMMON_INPUT_FIELDS + self.class.input_fields
+      missing_fields = expected_fields - @input_data.keys
+
+      unless missing_fields.empty?
+        log "Missing required input fields for #{hook_type}: #{missing_fields.join(', ')}", level: :warn
+      end
+    end
+  end
+end