claude_hooks 0.1.1

data/lib/claude_hooks/configuration.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ClaudeHooks
+  class Configuration
+    ENV_PREFIX = 'RUBY_CLAUDE_HOOKS_'
+
+    class << self
+      # Load the entire config as a hash (from ENV and optional config file)
+      def config
+        @config ||= load_config
+      end
+
+      # Unmemoize config
+      def reload!
+        @config = nil
+        @base_dir = nil
+        @config_file_path = nil
+      end
+
+      # Get the base directory from ENV or default
+      def base_dir
+        @base_dir ||= begin
+          env_base_dir = ENV["#{ENV_PREFIX}BASE_DIR"]
+          File.expand_path(env_base_dir || '~/.claude')
+        end
+      end
+
+      # Get the full path for a file/directory relative to base_dir
+      def path_for(relative_path)
+        File.join(base_dir, relative_path)
+      end
+
+      # Get the log directory path
+      def logs_directory
+        log_dir = get_config_value('LOG_DIR', 'logDirectory') || 'logs'
+        if log_dir.start_with?('/')
+          log_dir  # Absolute path
+        else
+          path_for(log_dir)  # Relative to base_dir
+        end
+      end
+
+
+      # Get any configuration value by key
+      # First checks ENV with prefix, then config file, then returns default
+      def get_config_value(env_key, config_key = nil, default = nil)
+        # Check environment variable first
+        env_value = ENV["#{ENV_PREFIX}#{env_key}"]
+        return env_value if env_value
+
+        # Check config file using provided key or converted env_key
+        file_key = config_key || env_key_to_config_key(env_key)
+        config_value = config.dig(file_key)
+        return config_value if config_value
+
+        # Return default
+        default
+      end
+
+      # Allow access to any config value using method_missing
+      def method_missing(method_name, *args, &block)
+        # Convert method name to ENV key format (e.g., my_custom_setting -> MY_CUSTOM_SETTING)
+        env_key = method_name.to_s.upcase
+        config_key = method_name.to_s
+
+        value = get_config_value(env_key, config_key)
+        return value unless value.nil?
+
+        super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        # Check if we have a config value for this method
+        env_key = method_name.to_s.upcase
+        config_key = method_name.to_s
+        
+        !get_config_value(env_key, config_key).nil? || super
+      end
+
+      private
+
+      def config_file_path
+        @config_file_path ||= path_for('config/config.json')
+      end
+
+      def load_config
+        # Start with config file
+        file_config = load_config_file
+        
+        # Merge with ENV variables
+        env_config = load_env_config
+        
+        # ENV variables take precedence
+        file_config.merge(env_config)
+      end
+
+      def load_config_file
+        config_file = config_file_path
+
+        if File.exist?(config_file)
+          begin
+            JSON.parse(File.read(config_file))
+          rescue JSON::ParserError => e
+            warn "Warning: Error parsing config file #{config_file}: #{e.message}"
+            {}
+          end
+        else
+          # No config file is fine - we'll use ENV vars and defaults
+          {}
+        end
+      end
+
+      def load_env_config
+        env_config = {}
+        
+        ENV.each do |key, value|
+          next unless key.start_with?(ENV_PREFIX)
+          
+          # Remove prefix and convert to config key format
+          config_key = env_key_to_config_key(key.sub(ENV_PREFIX, ''))
+          env_config[config_key] = value
+        end
+        
+        env_config
+      end
+
+      def env_key_to_config_key(env_key)
+        # Convert SCREAMING_SNAKE_CASE to camelCase
+        # BASE_DIR -> baseDir, LOG_DIR -> logDirectory (with special handling)
+        case env_key
+        when 'LOG_DIR'
+          'logDirectory'
+        when 'BASE_DIR'
+          'baseDir'
+        else
+          # Convert SCREAMING_SNAKE_CASE to camelCase
+          parts = env_key.downcase.split('_')
+          parts.first + parts[1..-1].map(&:capitalize).join
+        end
+      end
+    end
+  end
+end

data/lib/claude_hooks/logger.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+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
+      @source = source
+    end
+
+    # Log to session-specific file
+    # Usage:
+    #   log "Simple message"
+    #   log "Debug info", level: :debug
+    def log(message, level: :info)
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+      class_prefix = "[#{timestamp}] [#{level.upcase}] [#{@source}]"
+
+      # For multiline strings, prepend a newline for better formatting
+      if message.include?("\n")
+        log_entry = "#{class_prefix}\n#{message}"
+      else
+        log_entry = "#{class_prefix} #{message}"
+      end
+
+      begin
+        write_to_session_log(log_entry)
+      rescue => e
+        # Fallback to STDERR if file logging fails
+        STDERR.puts log_entry
+        STDERR.puts "Warning: Failed to write to session log: #{e.message}"
+      end
+    end
+
+    private
+
+    # Sanitize session_id to be filesystem-safe
+    def safe_session_id
+      session = @session_id || 'unknown'
+      session.gsub(/[^a-zA-Z0-9\-_]/, '_')
+    end
+
+    # Write log entry to session-specific file
+    def write_to_session_log(log_entry)
+      log_file_path = File.join(
+        Configuration.logs_directory,
+        "hooks",
+        "session-#{safe_session_id}.log"
+      )
+
+      # Ensure log directory exists
+      log_dir = File.dirname(log_file_path)
+      FileUtils.mkdir_p(log_dir) unless Dir.exist?(log_dir)
+
+      # Write to file (thread-safe append mode)
+      File.open(log_file_path, 'a') do |file|
+        file.puts log_entry
+        file.flush  # Ensure immediate write
+      end
+    end
+  end
+end

data/lib/claude_hooks/notification.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class Notification < Base
+    def self.hook_type
+      'Notification'
+    end
+
+    def self.input_fields
+      %w[message]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def message
+      @input_data['message']
+    end
+    alias_method :notification_message, :message
+  end
+end

data/lib/claude_hooks/post_tool_use.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PostToolUse < Base
+    def self.hook_type
+      'PostToolUse'
+    end
+
+    def self.input_fields
+      %w[tool_name tool_input tool_response]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def tool_name
+      @input_data['tool_name']
+    end
+
+    def tool_input
+      @input_data['tool_input']
+    end
+
+    def tool_response
+      @input_data['tool_response']
+    end
+
+    # === OUTPUT DATA HELPERS ===
+
+    def block_tool!(reason = '')
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = reason
+    end
+
+    def approve_tool!(reason = '')
+      @output_data['decision'] = nil
+      @output_data['reason'] = nil
+    end
+
+    # === MERGE HELPER ===
+
+    # Merge multiple PostToolUse hook results intelligently
+    def self.merge_outputs(*outputs_data)
+      merged = super(*outputs_data)
+
+      outputs_data.compact.each do |output|
+        merged['decision'] = 'block' if output['decision'] == 'block'
+        merged['reason'] = [merged['reason'], output['reason']].compact.reject(&:empty?).join('; ')
+      end
+
+      merged
+    end
+  end
+end

data/lib/claude_hooks/pre_compact.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require 'fileutils'
+
+module ClaudeHooks
+  class PreCompact < Base
+    def self.hook_type
+      'PreCompact'
+    end
+
+    def self.input_fields
+      %w[trigger custom_instructions]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def trigger
+      @input_data['trigger']
+    end
+
+    def custom_instructions
+      if trigger == 'manual'
+        @input_data['custom_instructions']
+      else
+        ''
+      end
+    end
+
+    # === UTILITY HELPERS ===
+
+    def backup_transcript!(backup_file_path)
+      unless Dir.exist?(File.dirname(backup_file_path))
+        FileUtils.mkdir_p(File.dirname(backup_file_path))
+      end
+
+      transcript_content = read_transcript
+      File.write(backup_file_path, transcript_content)
+      log "Transcript backed up to: #{backup_file_path}"
+    end
+  end
+end

data/lib/claude_hooks/pre_tool_use.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class PreToolUse < Base
+    def self.hook_type
+      'PreToolUse'
+    end
+
+    def self.input_fields
+      %w[tool_name tool_input]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def tool_name
+      @input_data['tool_name']
+    end
+
+    def tool_input
+      @input_data['tool_input']
+    end
+
+    # === OUTPUT DATA HELPERS ===
+
+    def approve_tool!(reason = '')
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'permissionDecision' => 'allow',
+        'permissionDecisionReason' => reason
+      }
+    end
+
+    def block_tool!(reason = '')
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'permissionDecision' => 'deny',
+        'permissionDecisionReason' => reason
+      }
+    end
+
+    def ask_for_permission!(reason = '')
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'permissionDecision' => 'ask',
+        'permissionDecisionReason' => reason
+      }
+    end
+
+    # === MERGE HELPER ===
+
+    # Merge multiple PreToolUse hook results intelligently
+    def self.merge_outputs(*outputs_data)
+      merged = super(*outputs_data)
+
+      # For PreToolUse: deny > ask > allow (most restrictive wins)
+      permission_decision = 'allow'
+      permission_reasons = []
+
+      outputs_data.compact.each do |output|
+        if output.dig('hookSpecificOutput', 'permissionDecision')
+          current_decision = output['hookSpecificOutput']['permissionDecision']
+          case current_decision
+          when 'deny'
+            permission_decision = 'deny'
+          when 'ask'
+            permission_decision = 'ask' unless permission_decision == 'deny'
+          end
+
+          if output['hookSpecificOutput']['permissionDecisionReason']
+            permission_reasons << output['hookSpecificOutput']['permissionDecisionReason']
+          end
+        end
+      end
+
+      unless permission_reasons.empty?
+        merged['hookSpecificOutput'] = {
+          'hookEventName' => hook_type,
+          'permissionDecision' => permission_decision,
+          'permissionDecisionReason' => permission_reasons.join('; ')
+        }
+      end
+
+      merged
+    end
+  end
+end

data/lib/claude_hooks/session_start.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class SessionStart < Base
+    def self.hook_type
+      'SessionStart'
+    end
+
+    def self.input_fields
+      %w[source]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def source
+      @input_data['source']
+    end
+
+    # === OUTPUT DATA HELPERS ===
+
+    def add_additional_context!(context)
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'additionalContext' => context
+      }
+    end
+    alias_method :add_context!, :add_additional_context!
+
+    def empty_additional_context!
+      @output_data['hookSpecificOutput'] = nil
+    end
+
+    # === MERGE HELPER ===
+
+    # Merge multiple SessionStart hook results intelligently
+    def self.merge_outputs(*outputs_data)
+      merged = super(*outputs_data)
+      contexts = []
+
+      outputs_data.compact.each do |output|
+        if output.dig('hookSpecificOutput', 'additionalContext')
+          contexts << output['hookSpecificOutput']['additionalContext']
+        end
+      end
+
+      unless contexts.empty?
+        merged['hookSpecificOutput'] = {
+          'hookEventName' => hook_type,
+          'additionalContext' => contexts.join("\n\n")
+        }
+      end
+
+      merged
+    end
+  end
+end

data/lib/claude_hooks/stop.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class Stop < Base
+    def self.hook_type
+      'Stop'
+    end
+
+    def self.input_fields
+      %w[stop_hook_active]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def stop_hook_active
+      @input_data['stop_hook_active']
+    end
+
+    # === OUTPUT DATA HELPERS ===
+
+    # Block Claude from stopping (force it to continue)
+    def continue_with_instructions!(instructions)
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = instructions
+    end
+    alias_method :block!, :continue_with_instructions!
+
+    # Ensure Claude stops normally (default behavior)
+    def ensure_stopping!
+      @output_data.delete('decision')
+      @output_data.delete('reason')
+    end
+
+    # === MERGE HELPER ===
+
+    # Merge multiple Stop hook results intelligently
+    def self.merge_outputs(*outputs_data)
+      merged = super(*outputs_data)
+
+      # A blocking reason is actually a "continue instructions"
+      blocking_reasons = []
+
+      outputs_data.compact.each do |output|
+        # Handle decision - if any hook says 'block', respect that
+        if output['decision'] == 'block'
+          merged['decision'] = 'block'
+          blocking_reasons << output['reason'] if output['reason'] && !output['reason'].empty?
+        end
+      end
+
+      # Combine all blocking reasons / continue instructions
+      unless blocking_reasons.empty?
+        merged['reason'] = blocking_reasons.join('; ')
+      end
+
+      merged
+    end
+  end
+end

data/lib/claude_hooks/subagent_stop.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'stop'
+
+module ClaudeHooks
+  class SubagentStop < Stop
+    def self.hook_type
+      'SubagentStop'
+    end
+  end
+end

data/lib/claude_hooks/user_prompt_submit.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module ClaudeHooks
+  class UserPromptSubmit < Base
+    def self.hook_type
+      'UserPromptSubmit'
+    end
+
+    def self.input_fields
+      %w[prompt]
+    end
+
+    # === INPUT DATA ACCESS ===
+
+    def prompt
+      @input_data['user_prompt'] || @input_data['prompt']
+    end
+    alias_method :user_prompt, :prompt
+    alias_method :current_prompt, :prompt
+
+    # === OUTPUT DATA HELPERS ===
+
+    def add_additional_context!(context)
+      @output_data['hookSpecificOutput'] = {
+        'hookEventName' => hook_event_name,
+        'additionalContext' => context
+      }
+    end
+    alias_method :add_context!, :add_additional_context!
+
+    def empty_additional_context!
+      @output_data['hookSpecificOutput'] = nil
+    end
+
+    def block_prompt!(reason = '')
+      @output_data['decision'] = 'block'
+      @output_data['reason'] = reason
+    end
+
+    def unblock_prompt!
+      @output_data['decision'] = nil
+      @output_data['reason'] = nil
+    end
+
+    # === MERGE HELPER ===
+
+    # Merge multiple UserPromptSubmit hook results intelligently
+    def self.merge_outputs(*outputs_data)
+      merged = super(*outputs_data)
+      contexts = []
+
+      outputs_data.compact.each do |output|
+        merged['decision'] = 'block' if output['decision'] == 'block'
+        merged['reason'] = [merged['reason'], output['reason']].compact.reject(&:empty?).join('; ')
+
+        if output.dig('hookSpecificOutput', 'additionalContext')
+          contexts << output['hookSpecificOutput']['additionalContext']
+        end
+      end
+
+      unless contexts.empty?
+        merged['hookSpecificOutput'] = {
+          'hookEventName' => hook_type,
+          'additionalContext' => contexts.join("\n\n")
+        }
+      end
+
+      merged
+    end
+  end
+end

data/lib/claude_hooks/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClaudeHooks
+  VERSION = "0.1.1"
+end

data/lib/claude_hooks.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "claude_hooks/version"
+require_relative "claude_hooks/configuration"
+require_relative "claude_hooks/logger"
+require_relative "claude_hooks/base"
+require_relative "claude_hooks/user_prompt_submit"
+require_relative "claude_hooks/pre_tool_use"
+require_relative "claude_hooks/post_tool_use"
+require_relative "claude_hooks/notification"
+require_relative "claude_hooks/stop"
+require_relative "claude_hooks/subagent_stop"
+require_relative "claude_hooks/pre_compact"
+require_relative "claude_hooks/session_start"
+
+module ClaudeHooks
+  class Error < StandardError; end
+end