swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/hooks/executor.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Executes hooks with proper chaining, error handling, and logging
+    #
+    # The executor:
+    # - Chains multiple hooks for the same event
+    # - Handles errors and blocking (via Error or Result.halt)
+    # - Respects matcher patterns (only runs matching hooks)
+    # - Logs execution for debugging
+    # - Returns Result indicating action to take
+    #
+    # @example Execute hooks
+    #   executor = SwarmSDK::Hooks::Executor.new(registry, logger)
+    #   context = SwarmSDK::Hooks::Context.new(...)
+    #   result = executor.execute(event: :pre_tool_use, context: context, hooks: agent_hooks)
+    #   if result.halt?
+    #     # Handle halt
+    #   elsif result.replace?
+    #     # Use replacement value
+    #   end
+    class Executor
+      # @param registry [Registry] Hook registry for resolving named hooks
+      # @param logger [Logger, nil] Logger for debugging (optional)
+      def initialize(registry, logger: nil)
+        @registry = registry
+        @logger = logger || Logger.new(nil) # Null logger if not provided
+      end
+
+      # Execute all hooks for an event
+      #
+      # Execution order:
+      # 1. Swarm-level defaults (from registry)
+      # 2. Agent-specific hooks
+      # 3. Within each group, by priority (highest first)
+      #
+      # Hooks must return:
+      # - Result - to control execution flow (halt, replace, reprompt, continue)
+      # - nil - treated as continue with unmodified context
+      #
+      # @param event [Symbol] Event type
+      # @param context [Context] Context to pass to hooks
+      # @param callbacks [Array<Definition>] Agent-specific hooks
+      # @return [Result] Result indicating action and value
+      # @raise [Error] If a hook raises an error
+      def execute(event:, context:, callbacks: [])
+        # Combine swarm defaults and agent hooks
+        all_hooks = @registry.get_defaults(event) + callbacks
+
+        # Filter by matcher (for tool events)
+        if context.tool_event? && context.tool_name
+          all_hooks = all_hooks.select { |hook| hook.matches?(context.tool_name) }
+        end
+
+        # Execute hooks in order
+        all_hooks.each do |hook_def|
+          result = execute_single(hook_def, context)
+
+          # Only Result controls flow - nil means continue
+          next unless result.is_a?(Result)
+
+          # Early return for control flow actions
+          return result if result.halt? || result.replace? || result.reprompt? || result.finish_agent? || result.finish_swarm?
+
+          # Update context if continue with modified context
+          context = result.value if result.continue? && result.value.is_a?(Context)
+        end
+
+        # All hooks executed successfully - continue with final context
+        Result.continue(context)
+      rescue Error => e
+        # Re-raise with context for better error messages
+        @logger.error("Hook blocked execution: #{e.message}")
+        raise
+      rescue StandardError => e
+        # Wrap unexpected errors
+        @logger.error("Hook failed unexpectedly: #{e.class} - #{e.message}")
+        @logger.error(e.backtrace.join("\n"))
+        raise Error.new(
+          "Hook failed: #{e.message}",
+          context: context,
+        )
+      end
+
+      # Execute a single hook
+      #
+      # @param hook_def [Definition] Hook to execute
+      # @param context [Context] Current context
+      # @return [Result, nil] Result from hook (Result or nil)
+      # @raise [Error] If hook execution fails
+      def execute_single(hook_def, context)
+        proc = hook_def.resolve_proc(@registry)
+
+        @logger.debug("Executing hook for #{context.event} (agent: #{context.agent_name})")
+
+        # Execute hook with context as parameter
+        # Users can access convenience methods via context parameter:
+        #   hook(:event) { |ctx| ctx.halt("msg") }
+        # This preserves lexical scope and access to surrounding instance variables
+        proc.call(context)
+      rescue Error
+        # Pass through blocking errors
+        raise
+      rescue StandardError => e
+        # Wrap other errors with context and detailed debugging
+        hook_name = hook_def.named_hook? ? hook_def.proc : "anonymous"
+
+        # Log detailed error info for debugging
+        @logger.error("=" * 80)
+        @logger.error("HOOK EXECUTION ERROR")
+        @logger.error("  Hook: #{hook_name}")
+        @logger.error("  Event: #{context.event}")
+        @logger.error("  Agent: #{context.agent_name}")
+        @logger.error("  Proc class: #{proc.class}")
+        @logger.error("  Proc arity: #{proc.arity} (expected: 1 for |context|)")
+        @logger.error("  Error: #{e.class.name}: #{e.message}")
+        @logger.error("  Backtrace:")
+        e.backtrace.first(15).each { |line| @logger.error("    #{line}") }
+        @logger.error("=" * 80)
+
+        raise Error.new(
+          "Hook #{hook_name} failed: #{e.message}",
+          hook_name: hook_name,
+          context: context,
+        )
+      end
+
+      # Execute hooks and return result safely (without raising)
+      #
+      # This is a convenience method that catches Error and converts it
+      # to a halt result, making it easier to use in control flow.
+      #
+      # @param event [Symbol] Event type
+      # @param context [Context] Context to pass to hooks
+      # @param callbacks [Array<Definition>] Agent-specific hooks
+      # @return [Result] Result from hooks
+      def execute_safe(event:, context:, callbacks: [])
+        execute(event: event, context: context, callbacks: callbacks)
+      rescue Error => e
+        @logger.warn("Execution blocked by hook: #{e.message}")
+        Result.halt(e.message)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/registry.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Central registry for managing named hooks and swarm-level defaults
+    #
+    # The Registry stores:
+    # - Named hooks that can be referenced by symbol in YAML or code
+    # - Swarm-level default hooks that apply to all agents
+    #
+    # @example Register a named hook
+    #   registry = SwarmSDK::Hooks::Registry.new
+    #   registry.register(:validate_code) do |context|
+    #     raise SwarmSDK::Hooks::Error, "Invalid code" unless valid?(context.tool_call)
+    #   end
+    #
+    # @example Add swarm-level default
+    #   registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |context|
+    #     puts "Tool #{context.tool_call.name} called by #{context.agent_name}"
+    #   end
+    class Registry
+      # Available hook event types
+      VALID_EVENTS = [
+        # Swarm lifecycle events
+        :swarm_start,       # When Swarm.execute is called (before first user message)
+        :swarm_stop,        # When Swarm.execute completes (after execution)
+        :first_message,     # When first user message is sent to swarm (Swarm.execute)
+
+        # Agent/LLM events
+        :user_prompt,       # Before sending user message to LLM
+        :agent_step,        # After agent makes intermediate response with tool calls
+        :agent_stop,        # After agent completes with final response (no more tool calls)
+
+        # Tool events
+        :pre_tool_use,      # Before tool execution (can block/modify)
+        :post_tool_use,     # After tool execution
+
+        # Delegation events
+        :pre_delegation,    # Before delegating to another agent
+        :post_delegation,   # After delegation completes
+
+        # Context events
+        :context_warning, # When context usage crosses threshold
+      ].freeze
+
+      def initialize
+        @named_hooks = {} # { hook_name: proc }
+        @defaults = Hash.new { |h, k| h[k] = [] } # { event_type: [Definition, ...] }
+      end
+
+      # Register a named hook that can be referenced elsewhere
+      #
+      # @param name [Symbol] Unique name for this hook
+      # @param block [Proc] Hook implementation
+      # @raise [ArgumentError] if name already registered or invalid
+      #
+      # @example
+      #   registry.register(:log_tool_use) { |ctx| puts "Tool: #{ctx.tool_call.name}" }
+      def register(name, &block)
+        raise ArgumentError, "Hook name must be a symbol" unless name.is_a?(Symbol)
+        raise ArgumentError, "Hook #{name} already registered" if @named_hooks.key?(name)
+        raise ArgumentError, "Block required" unless block
+
+        @named_hooks[name] = block
+      end
+
+      # Get a named hook by symbol
+      #
+      # @param name [Symbol] Hook name
+      # @return [Proc, nil] The hook proc or nil if not found
+      def get(name)
+        @named_hooks[name]
+      end
+
+      # Add a swarm-level default hook
+      #
+      # These hooks apply to all agents unless overridden at agent level.
+      #
+      # @param event [Symbol] Event type (must be in VALID_EVENTS)
+      # @param matcher [String, Regexp, nil] Optional regex pattern to match tool names
+      # @param priority [Integer] Execution priority (higher runs first)
+      # @param block [Proc] Hook implementation
+      # @raise [ArgumentError] if event invalid or block missing
+      #
+      # @example Add default logging
+      #   registry.add_default(:pre_tool_use) { |ctx| log(ctx) }
+      #
+      # @example Add validation for specific tools
+      #   registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |ctx|
+      #     validate_tool_call(ctx.tool_call)
+      #   end
+      def add_default(event, matcher: nil, priority: 0, &block)
+        validate_event!(event)
+        raise ArgumentError, "Block required" unless block
+
+        definition = Definition.new(
+          event: event,
+          matcher: matcher,
+          priority: priority,
+          proc: block,
+        )
+
+        @defaults[event] << definition
+        @defaults[event].sort_by! { |d| -d.priority } # Higher priority first
+      end
+
+      # Get all default hooks for an event type
+      #
+      # @param event [Symbol] Event type
+      # @return [Array<Definition>] List of hook definitions
+      def get_defaults(event)
+        @defaults[event]
+      end
+
+      # Get all registered named hook names
+      #
+      # @return [Array<Symbol>] List of hook names
+      def named_hooks
+        @named_hooks.keys
+      end
+
+      # Check if a hook name is registered
+      #
+      # @param name [Symbol] Hook name
+      # @return [Boolean] true if registered
+      def registered?(name)
+        @named_hooks.key?(name)
+      end
+
+      private
+
+      # Validate event type
+      #
+      # @param event [Symbol] Event to validate
+      # @raise [ArgumentError] if event invalid
+      def validate_event!(event)
+        return if VALID_EVENTS.include?(event)
+
+        raise ArgumentError, "Invalid event type: #{event}. Valid types: #{VALID_EVENTS.join(", ")}"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/result.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Result object returned by hooks to control execution flow
+    #
+    # Hooks can return a Result to:
+    # - Continue normal execution (default)
+    # - Halt execution and return an error/message
+    # - Replace a value (e.g., tool result, delegation result)
+    # - Reprompt the agent with a new prompt
+    # - Finish the current agent's execution (agent scope)
+    # - Finish the entire swarm execution (swarm scope)
+    #
+    # @example Continue normal execution (default)
+    #   SwarmSDK::Hooks::Result.continue
+    #
+    # @example Halt execution with error message
+    #   SwarmSDK::Hooks::Result.halt("Validation failed: invalid input")
+    #
+    # @example Replace tool result
+    #   SwarmSDK::Hooks::Result.replace("Custom tool result")
+    #
+    # @example Reprompt agent with modified prompt
+    #   SwarmSDK::Hooks::Result.reprompt("Modified task: #{original_task}")
+    #
+    # @example Finish current agent with message
+    #   SwarmSDK::Hooks::Result.finish_agent("Agent task completed")
+    #
+    # @example Finish entire swarm with message
+    #   SwarmSDK::Hooks::Result.finish_swarm("All tasks complete!")
+    class Result
+      attr_reader :action, :value
+
+      # Valid actions that control execution flow
+      VALID_ACTIONS = [:continue, :halt, :replace, :reprompt, :finish_agent, :finish_swarm].freeze
+
+      # @param action [Symbol] Action to take (:continue, :halt, :replace, :reprompt)
+      # @param value [Object, nil] Associated value (context for :continue, message for :halt, etc.)
+      def initialize(action:, value: nil)
+        unless VALID_ACTIONS.include?(action)
+          raise ArgumentError, "Invalid action: #{action}. Valid actions: #{VALID_ACTIONS.join(", ")}"
+        end
+
+        @action = action
+        @value = value
+      end
+
+      # Check if this result indicates halting execution
+      #
+      # @return [Boolean] true if action is :halt
+      def halt?
+        @action == :halt
+      end
+
+      # Check if this result provides a replacement value
+      #
+      # @return [Boolean] true if action is :replace
+      def replace?
+        @action == :replace
+      end
+
+      # Check if this result requests reprompting
+      #
+      # @return [Boolean] true if action is :reprompt
+      def reprompt?
+        @action == :reprompt
+      end
+
+      # Check if this result continues normal execution
+      #
+      # @return [Boolean] true if action is :continue
+      def continue?
+        @action == :continue
+      end
+
+      # Check if this result finishes the current agent
+      #
+      # @return [Boolean] true if action is :finish_agent
+      def finish_agent?
+        @action == :finish_agent
+      end
+
+      # Check if this result finishes the entire swarm
+      #
+      # @return [Boolean] true if action is :finish_swarm
+      def finish_swarm?
+        @action == :finish_swarm
+      end
+
+      class << self
+        # Create a result that continues normal execution
+        #
+        # @param context [Context, nil] Updated context (optional)
+        # @return [Result] Result with continue action
+        def continue(context = nil)
+          new(action: :continue, value: context)
+        end
+
+        # Create a result that halts execution
+        #
+        # @param message [String] Error or halt message
+        # @return [Result] Result with halt action
+        def halt(message)
+          new(action: :halt, value: message)
+        end
+
+        # Create a result that replaces a value
+        #
+        # @param value [Object] Replacement value
+        # @return [Result] Result with replace action
+        def replace(value)
+          new(action: :replace, value: value)
+        end
+
+        # Create a result that reprompts the agent
+        #
+        # @param prompt [String] New prompt to send to agent
+        # @return [Result] Result with reprompt action
+        def reprompt(prompt)
+          new(action: :reprompt, value: prompt)
+        end
+
+        # Create a result that finishes the current agent
+        #
+        # Exits the agent's chat loop and returns the message as the agent's
+        # final response. If this agent was delegated to, control returns to
+        # the calling agent. The swarm continues if there's more work.
+        #
+        # @param message [String] Final message from the agent
+        # @return [Result] Result with finish_agent action
+        def finish_agent(message)
+          new(action: :finish_agent, value: message)
+        end
+
+        # Create a result that finishes the entire swarm
+        #
+        # Immediately exits the Swarm.execute() loop and returns the message
+        # as the final Result#output. All agent execution stops and the user
+        # receives this message.
+        #
+        # @param message [String] Final message from the swarm
+        # @return [Result] Result with finish_swarm action
+        def finish_swarm(message)
+          new(action: :finish_swarm, value: message)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/shell_executor.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "timeout"
+
+module SwarmSDK
+  module Hooks
+    # Executes shell command hooks with JSON I/O and exit code handling
+    #
+    # ShellExecutor runs external shell commands (defined in YAML hooks) and
+    # converts their exit codes to Result objects that control execution flow.
+    #
+    # ## Exit Code Behavior (following Claude Code convention)
+    #
+    # - **0**: Success - continue execution (Result.continue)
+    # - **2**: Block with error feedback to LLM (Result.halt)
+    # - **Other**: Non-blocking error - log warning and continue (Result.continue)
+    #
+    # ## JSON I/O Format
+    #
+    # **stdin (to hook script)**:
+    # ```json
+    # {
+    #   "event": "pre_tool_use",
+    #   "agent": "backend",
+    #   "tool": "Write",
+    #   "parameters": { "file_path": "api.rb", "content": "..." }
+    # }
+    # ```
+    #
+    # **stdout (from hook script)**:
+    # ```json
+    # {
+    #   "success": false,
+    #   "error": "Validation failed: syntax error"
+    # }
+    # ```
+    #
+    # @example Execute a validation hook
+    #   result = SwarmSDK::Hooks::ShellExecutor.execute(
+    #     command: "python scripts/validate.py",
+    #     input_json: { event: "pre_tool_use", tool: "Write", parameters: {...} },
+    #     timeout: 10,
+    #     agent_name: :backend,
+    #     swarm_name: "Dev Team"
+    #   )
+    #   # => Result (continue or halt based on exit code)
+    class ShellExecutor
+      DEFAULT_TIMEOUT = 60
+
+      class << self
+        # Execute a shell command hook
+        #
+        # @param command [String] Shell command to execute
+        # @param input_json [Hash] JSON data to provide on stdin
+        # @param timeout [Integer] Timeout in seconds (default: 60)
+        # @param agent_name [Symbol, String, nil] Agent name for environment variables
+        # @param swarm_name [String, nil] Swarm name for environment variables
+        # @param event [Symbol] Event type for context-aware behavior
+        # @return [Result] Result based on exit code (continue or halt)
+        def execute(command:, input_json:, timeout: DEFAULT_TIMEOUT, agent_name: nil, swarm_name: nil, event: nil)
+          # Build environment variables
+          env = build_environment(agent_name: agent_name, swarm_name: swarm_name)
+
+          # Execute command with JSON stdin and timeout
+          stdout, stderr, status = Timeout.timeout(timeout) do
+            Open3.capture3(
+              env,
+              command,
+              stdin_data: JSON.generate(input_json),
+            )
+          end
+
+          # Handle exit code per Claude Code convention (context-aware)
+          result = handle_exit_code(status.exitstatus, stdout, stderr, event)
+
+          # Emit log event for hook execution
+          case status.exitstatus
+          when 0
+            # Success - log stdout/stderr
+            emit_hook_log(
+              event: event,
+              agent_name: agent_name,
+              command: command,
+              exit_code: status.exitstatus,
+              success: true,
+              stdout: stdout,
+              stderr: stderr,
+            )
+          when 2
+            # Blocking error - always log stderr
+            emit_hook_log(
+              event: event,
+              agent_name: agent_name,
+              command: command,
+              exit_code: status.exitstatus,
+              success: false,
+              stderr: stderr,
+              blocked: true,
+            )
+          else
+            # Non-blocking error - log stderr
+            emit_hook_log(
+              event: event,
+              agent_name: agent_name,
+              command: command,
+              exit_code: status.exitstatus,
+              success: false,
+              stderr: stderr,
+              blocked: false,
+            )
+          end
+
+          result
+        rescue Timeout::Error
+          emit_hook_log(
+            event: event,
+            agent_name: agent_name,
+            command: command,
+            exit_code: nil,
+            success: false,
+            stderr: "Timeout after #{timeout}s",
+          )
+          # Don't block on timeout - log and continue
+          Result.continue
+        rescue StandardError => e
+          emit_hook_log(
+            event: event,
+            agent_name: agent_name,
+            command: command,
+            exit_code: nil,
+            success: false,
+            stderr: e.message,
+          )
+          # Don't block on errors - log and continue
+          Result.continue
+        end
+
+        private
+
+        # Build environment variables for hook execution
+        #
+        # @param agent_name [Symbol, String, nil] Agent name
+        # @param swarm_name [String, nil] Swarm name
+        # @return [Hash] Environment variables
+        def build_environment(agent_name:, swarm_name:)
+          {
+            "SWARM_SDK_PROJECT_DIR" => Dir.pwd,
+            "SWARM_SDK_AGENT_NAME" => agent_name.to_s,
+            "SWARM_SDK_SWARM_NAME" => swarm_name.to_s,
+            "PATH" => ENV.fetch("PATH", ""),
+          }
+        end
+
+        # Handle exit code and return appropriate Result
+        #
+        # @param exit_code [Integer] Process exit code
+        # @param stdout [String] Standard output
+        # @param stderr [String] Standard error
+        # @param event [Symbol] Hook event type
+        # @return [Result] Result based on exit code
+        def handle_exit_code(exit_code, stdout, stderr, event)
+          case exit_code
+          when 0
+            # Success - continue execution
+            # For user_prompt and swarm_start: return stdout to be shown to agent
+            if [:user_prompt, :swarm_start].include?(event) && !stdout.strip.empty?
+              # Return Result with stdout that will be appended to prompt
+              Result.replace(stdout.strip)
+            else
+              # Normal success
+              Result.continue
+            end
+          when 2
+            # Blocking error - behavior depends on event type
+            handle_exit_code_2(event, stdout, stderr)
+          else
+            # Non-blocking error - continue (stderr logged above)
+            Result.continue
+          end
+        end
+
+        # Handle exit code 2 (blocking error)
+        #
+        # @param event [Symbol] Hook event type
+        # @param _stdout [String] Standard output (unused)
+        # @param stderr [String] Standard error
+        # @return [Result] Result based on event type
+        def handle_exit_code_2(event, _stdout, stderr)
+          error_msg = stderr.strip
+
+          case event
+          when :pre_tool_use
+            # Block tool call, show stderr to agent (stderr already logged above)
+            Result.halt(error_msg)
+          when :post_tool_use
+            # Tool already ran, show stderr to agent (stderr already logged above)
+            Result.halt(error_msg)
+          when :user_prompt
+            # Block prompt processing, erase prompt
+            # stderr is logged (above) for user to see, but NOT shown to agent
+            # Return empty halt (prompt is erased, no message to agent)
+            Result.halt("")
+          when :agent_stop
+            # Block stoppage, show stderr to agent (stderr already logged above)
+            Result.halt(error_msg)
+          when :context_warning, :swarm_start, :swarm_stop
+            # N/A - stderr logged above, don't halt
+            Result.continue
+          else
+            # Default: halt with stderr
+            Result.halt(error_msg)
+          end
+        end
+
+        # Emit hook execution log entry
+        #
+        # @param event [Symbol] Hook event type
+        # @param agent_name [String, Symbol, nil] Agent name
+        # @param command [String] Shell command executed
+        # @param exit_code [Integer, nil] Process exit code
+        # @param success [Boolean] Whether execution succeeded
+        # @param stdout [String, nil] Standard output
+        # @param stderr [String, nil] Standard error
+        # @param blocked [Boolean] Whether execution was blocked (exit code 2)
+        def emit_hook_log(event:, agent_name:, command:, exit_code:, success:, stdout: nil, stderr: nil, blocked: false)
+          # Only emit if LogStream is enabled (has emitter)
+          return unless LogStream.enabled?
+
+          log_entry = {
+            type: "hook_executed",
+            hook_event: event&.to_s, # Which hook event triggered this (pre_tool_use, swarm_start, etc.)
+            agent: agent_name,
+            command: command,
+            exit_code: exit_code,
+            success: success,
+          }
+
+          # Add stdout if present (exit code 0)
+          log_entry[:stdout] = stdout.strip if stdout && !stdout.strip.empty?
+
+          # Add stderr if present (any exit code)
+          log_entry[:stderr] = stderr.strip if stderr && !stderr.strip.empty?
+
+          # Add blocked flag for exit code 2
+          log_entry[:blocked] = true if blocked
+
+          LogStream.emit(**log_entry)
+        end
+      end
+    end
+  end
+end