swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/hooks/adapter.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Translates YAML hooks configuration to Ruby hooks
+    #
+    # Adapter bridges the gap between declarative YAML hooks (shell commands)
+    # and SwarmSDK's internal hook system. It creates hooks that execute
+    # shell commands and translate exit codes to Result objects.
+    #
+    # ## YAML Hooks are YAML-Only
+    #
+    # Hooks are a **YAML-only feature** designed for users who want Claude Code-style
+    # shell command hooks. Users of the Ruby API should use hooks directly.
+    #
+    # ## Swarm-Level vs Agent-Level
+    #
+    # - **Swarm-level**: Only `swarm_start` and `swarm_stop` (lifecycle hooks)
+    # - **Agent-level**: All other events (per-agent or all_agents)
+    # - **all_agents**: Hooks applied as swarm defaults to all agents
+    #
+    # ## Event Naming
+    #
+    # Uses snake_case to match internal hook events directly (no translation):
+    # - `pre_tool_use` → :pre_tool_use
+    # - `swarm_start` → :swarm_start
+    # - etc.
+    #
+    # @example YAML configuration
+    #   swarm:
+    #     hooks:
+    #       swarm_start:
+    #         - hooks:
+    #             - type: command
+    #               command: "echo 'Starting swarm'"
+    #
+    #     all_agents:
+    #       hooks:
+    #         pre_tool_use:
+    #           - matcher: "Write|Edit"
+    #             hooks:
+    #               - type: command
+    #                 command: "rubocop --stdin"
+    #
+    #     agents:
+    #       backend:
+    #         hooks:
+    #           pre_tool_use:
+    #             - matcher: "Bash"
+    #               hooks:
+    #                 - type: command
+    #                   command: "python validate_bash.py"
+    class Adapter
+      # Swarm-level events (only these allowed at swarm.hooks level)
+      SWARM_LEVEL_EVENTS = [:swarm_start, :swarm_stop].freeze
+
+      # Agent-level events (allowed in all_agents.hooks and agent.hooks)
+      AGENT_LEVEL_EVENTS = [
+        :pre_tool_use,
+        :post_tool_use,
+        :user_prompt,
+        :agent_step,
+        :agent_stop,
+        :first_message,
+        :pre_delegation,
+        :post_delegation,
+        :context_warning,
+      ].freeze
+
+      class << self
+        # Apply hooks from YAML configuration to swarm
+        #
+        # This is called automatically by Swarm.load after creating the swarm instance.
+        # It translates YAML hooks into hooks that execute shell commands.
+        #
+        # @param swarm [Swarm] Swarm instance to configure
+        # @param config [Configuration] Parsed YAML configuration
+        # @return [void]
+        def apply_hooks(swarm, config)
+          # 1. Apply swarm-level hooks (from swarm.hooks)
+          apply_swarm_hooks(swarm, config.swarm_hooks) if config.swarm_hooks&.any?
+
+          # 2. Apply all_agents hooks (as swarm defaults)
+          apply_all_agents_hooks(swarm, config.all_agents_hooks) if config.all_agents_hooks&.any?
+
+          # 3. Store agent hooks for later application (after agents are initialized)
+          store_agent_hooks(config)
+        end
+
+        # Apply agent-specific hooks to an already-initialized agent
+        #
+        # This is called during agent initialization for each agent that has hooks configured.
+        #
+        # @param agent [AgentChat] Agent instance
+        # @param agent_name [Symbol] Agent name
+        # @param hooks_config [Hash] Hooks configuration from YAML
+        # @param swarm_name [String] Swarm name for environment variables
+        # @return [void]
+        def apply_agent_hooks(agent, agent_name, hooks_config, swarm_name)
+          return unless hooks_config&.any?
+
+          hooks_config.each do |event_name, hook_defs|
+            event_symbol = event_name.to_sym
+            validate_agent_event!(event_symbol)
+
+            # Each hook def can have optional matcher
+            Array(hook_defs).each do |hook_def|
+              matcher = hook_def[:matcher] || hook_def["matcher"]
+              hook = create_hook_callback(hook_def, event_symbol, agent_name, swarm_name)
+              agent.add_hook(event_symbol, matcher: matcher, &hook)
+            end
+          end
+        end
+
+        private
+
+        # Apply swarm-level hooks (swarm_start, swarm_stop)
+        #
+        # @param swarm [Swarm] Swarm instance
+        # @param hooks_config [Hash] Hooks configuration
+        def apply_swarm_hooks(swarm, hooks_config)
+          hooks_config.each do |event_name, hook_defs|
+            event_symbol = event_name.to_sym
+            validate_swarm_event!(event_symbol)
+
+            # Each hook def is a direct hash with type, command, timeout
+            Array(hook_defs).each do |hook_def|
+              hook = create_swarm_hook_callback(hook_def, event_symbol, swarm.name)
+              swarm.add_default_callback(event_symbol, &hook)
+            end
+          end
+        end
+
+        # Apply all_agents hooks as swarm defaults
+        #
+        # @param swarm [Swarm] Swarm instance
+        # @param hooks_config [Hash] Hooks configuration
+        def apply_all_agents_hooks(swarm, hooks_config)
+          hooks_config.each do |event_name, hook_defs|
+            event_symbol = event_name.to_sym
+            validate_agent_event!(event_symbol)
+
+            # Each hook def can have optional matcher
+            Array(hook_defs).each do |hook_def|
+              matcher = hook_def[:matcher] || hook_def["matcher"]
+              hook = create_all_agents_hook_callback(hook_def, event_symbol, swarm.name)
+              swarm.add_default_callback(event_symbol, matcher: matcher, &hook)
+            end
+          end
+        end
+
+        # Store agent hooks in Configuration for later application
+        #
+        # @param config [Configuration] Configuration instance
+        def store_agent_hooks(config)
+          # Agent hooks are already stored in AgentDefinition
+          # They'll be applied during agent initialization
+        end
+
+        # Create a hook for agent-level hooks
+        #
+        # @param hook_def [Hash] Hook definition from YAML
+        # @param event_symbol [Symbol] Event type
+        # @param agent_name [Symbol, String] Agent name
+        # @param swarm_name [String] Swarm name
+        # @return [Proc] Hook callback
+        def create_hook_callback(hook_def, event_symbol, agent_name, swarm_name)
+          # Support both string and symbol keys (YAML may be symbolized)
+          command = hook_def[:command] || hook_def["command"]
+          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+
+          lambda do |context|
+            input_json = build_input_json(context, event_symbol, agent_name)
+            ShellExecutor.execute(
+              command: command,
+              input_json: input_json,
+              timeout: timeout,
+              agent_name: agent_name,
+              swarm_name: swarm_name,
+              event: event_symbol,
+            )
+          end
+        end
+
+        # Create a hook for all_agents hooks
+        #
+        # @param hook_def [Hash] Hook definition from YAML
+        # @param event_symbol [Symbol] Event type
+        # @param swarm_name [String] Swarm name
+        # @return [Proc] Hook callback
+        def create_all_agents_hook_callback(hook_def, event_symbol, swarm_name)
+          # Support both string and symbol keys (YAML may be symbolized)
+          command = hook_def[:command] || hook_def["command"]
+          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+
+          lambda do |context|
+            # Agent name comes from context
+            agent_name = context.agent_name
+            input_json = build_input_json(context, event_symbol, agent_name)
+            ShellExecutor.execute(
+              command: command,
+              input_json: input_json,
+              timeout: timeout,
+              agent_name: agent_name,
+              swarm_name: swarm_name,
+              event: event_symbol,
+            )
+          end
+        end
+
+        # Create a hook for swarm-level hooks
+        #
+        # @param hook_def [Hash] Hook definition from YAML
+        # @param event_symbol [Symbol] Event type
+        # @param swarm_name [String] Swarm name
+        # @return [Proc] Hook callback
+        def create_swarm_hook_callback(hook_def, event_symbol, swarm_name)
+          # Support both string and symbol keys (YAML may be symbolized)
+          command = hook_def[:command] || hook_def["command"]
+          timeout = hook_def[:timeout] || hook_def["timeout"] || ShellExecutor::DEFAULT_TIMEOUT
+
+          lambda do |context|
+            input_json = build_swarm_input_json(context, event_symbol, swarm_name)
+            ShellExecutor.execute(
+              command: command,
+              input_json: input_json,
+              timeout: timeout,
+              agent_name: nil,
+              swarm_name: swarm_name,
+              event: event_symbol,
+            )
+          end
+        end
+
+        # Build JSON input for agent-level hook scripts
+        #
+        # @param context [Context] Hook context
+        # @param event_symbol [Symbol] Event type
+        # @param agent_name [Symbol, String] Agent name
+        # @return [Hash] JSON input for hook script
+        def build_input_json(context, event_symbol, agent_name)
+          base = {
+            event: event_symbol.to_s,
+            agent: agent_name.to_s,
+          }
+
+          # Add event-specific data
+          case event_symbol
+          when :pre_tool_use
+            base.merge(
+              tool: context.tool_call.name,
+              parameters: context.tool_call.parameters,
+            )
+          when :post_tool_use
+            # In post_tool_use, we only have tool_result, not tool_call
+            # Need to extract tool info from metadata or tool_result
+            base.merge(
+              result: context.tool_result.content,
+              success: context.tool_result.success?,
+              tool_call_id: context.tool_result.tool_call_id,
+            )
+          when :pre_delegation
+            base.merge(
+              delegation_target: context.delegation_target,
+              task: context.metadata[:task],
+            )
+          when :post_delegation
+            base.merge(
+              delegation_target: context.delegation_target,
+              task: context.metadata[:task],
+              result: context.delegation_result,
+            )
+          when :user_prompt
+            base.merge(
+              prompt: context.metadata[:prompt],
+              message_count: context.metadata[:message_count],
+            )
+          when :agent_step
+            base.merge(
+              content: context.metadata[:content],
+              tool_calls: context.metadata[:tool_calls],
+              finish_reason: context.metadata[:finish_reason],
+              usage: context.metadata[:usage],
+            )
+          when :agent_stop
+            base.merge(
+              content: context.metadata[:content],
+              finish_reason: context.metadata[:finish_reason],
+              usage: context.metadata[:usage],
+            )
+          when :first_message
+            base.merge(prompt: context.metadata[:prompt])
+          when :context_warning
+            base.merge(
+              threshold: context.metadata[:threshold],
+              percentage: context.metadata[:percentage],
+              tokens_used: context.metadata[:tokens_used],
+              tokens_remaining: context.metadata[:tokens_remaining],
+            )
+          else
+            base
+          end
+        end
+
+        # Build JSON input for swarm-level hook scripts
+        #
+        # @param context [Context] Hook context
+        # @param event_symbol [Symbol] Event type
+        # @param swarm_name [String] Swarm name
+        # @return [Hash] JSON input for hook script
+        def build_swarm_input_json(context, event_symbol, swarm_name)
+          base = {
+            event: event_symbol.to_s,
+            swarm: swarm_name,
+          }
+
+          case event_symbol
+          when :swarm_start, :first_message
+            base.merge(prompt: context.metadata[:prompt])
+          when :swarm_stop
+            base.merge(
+              success: context.metadata[:success],
+              duration: context.metadata[:duration],
+              total_cost: context.metadata[:total_cost],
+              total_tokens: context.metadata[:total_tokens],
+            )
+          else
+            base
+          end
+        end
+
+        # Validate swarm-level event
+        #
+        # @param event [Symbol] Event to validate
+        # @raise [ConfigurationError] if event invalid for swarm level
+        def validate_swarm_event!(event)
+          return if SWARM_LEVEL_EVENTS.include?(event)
+
+          raise ConfigurationError,
+            "Invalid swarm-level hook event: #{event}. " \
+              "Only #{SWARM_LEVEL_EVENTS.join(", ")} are allowed at swarm.hooks level. " \
+              "Use all_agents.hooks or agent.hooks for other events."
+        end
+
+        # Validate agent-level event
+        #
+        # @param event [Symbol] Event to validate
+        # @raise [ConfigurationError] if event invalid for agent level
+        def validate_agent_event!(event)
+          return if AGENT_LEVEL_EVENTS.include?(event)
+
+          raise ConfigurationError,
+            "Invalid agent-level hook event: #{event}. " \
+              "Valid events: #{AGENT_LEVEL_EVENTS.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/context.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Rich context object passed to hook callbacks
+    #
+    # Provides hooks with comprehensive access to:
+    # - Agent information (name, definition)
+    # - Tool call details (for tool-related events)
+    # - Delegation details (for delegation events)
+    # - Swarm context (access to other agents, configuration)
+    # - Metadata (arbitrary additional data)
+    #
+    # The context is read-write, allowing hooks to modify data
+    # (e.g., add metadata, modify tool parameters).
+    #
+    # @example Access tool call information
+    #   context.tool_call.name  # => "Write"
+    #   context.tool_call.parameters  # => { file_path: "...", content: "..." }
+    #
+    # @example Modify metadata
+    #   context.metadata[:validated] = true
+    #   context.metadata[:validation_time] = Time.now
+    #
+    # @example Check event type
+    #   if context.tool_event?
+    #     validate_tool_call(context.tool_call)
+    #   end
+    class Context
+      attr_reader :event, :agent_name, :agent_definition, :swarm, :metadata
+      attr_accessor :tool_call, :tool_result, :delegation_target, :delegation_result
+
+      # @param event [Symbol] The event type triggering this hook
+      # @param agent_name [String, Symbol] Name of the agent
+      # @param agent_definition [SwarmSDK::AgentDefinition, nil] Agent's configuration
+      # @param swarm [SwarmSDK::Swarm, nil] Reference to the swarm (if available)
+      # @param tool_call [ToolCall, nil] Tool call object (for tool events)
+      # @param tool_result [ToolResult, nil] Tool result (for post_tool_use)
+      # @param delegation_target [String, Symbol, nil] Target agent name (for delegation events)
+      # @param delegation_result [Object, nil] Result from delegation (for post_delegation)
+      # @param metadata [Hash] Additional metadata
+      def initialize(
+        event:,
+        agent_name:,
+        agent_definition: nil,
+        swarm: nil,
+        tool_call: nil,
+        tool_result: nil,
+        delegation_target: nil,
+        delegation_result: nil,
+        metadata: {}
+      )
+        @event = event
+        @agent_name = agent_name
+        @agent_definition = agent_definition
+        @swarm = swarm
+        @tool_call = tool_call
+        @tool_result = tool_result
+        @delegation_target = delegation_target
+        @delegation_result = delegation_result
+        @metadata = metadata
+      end
+
+      # Check if this is a tool-related event
+      #
+      # @return [Boolean] true if event is pre_tool_use or post_tool_use
+      def tool_event?
+        [:pre_tool_use, :post_tool_use].include?(@event)
+      end
+
+      # Check if this is a delegation-related event
+      #
+      # @return [Boolean] true if event is pre_delegation or post_delegation
+      def delegation_event?
+        [:pre_delegation, :post_delegation].include?(@event)
+      end
+
+      # Get tool name (convenience method)
+      #
+      # @return [String, nil] Tool name or nil if not a tool event
+      def tool_name
+        tool_call&.name
+      end
+
+      # Create a copy of this context with modified attributes
+      #
+      # Useful for chaining hooks that need to pass modified context
+      # to subsequent hooks.
+      #
+      # @param attributes [Hash] Attributes to override
+      # @return [Context] New context with modified attributes
+      def with(**attributes)
+        Context.new(
+          event: attributes[:event] || @event,
+          agent_name: attributes[:agent_name] || @agent_name,
+          agent_definition: attributes[:agent_definition] || @agent_definition,
+          swarm: attributes[:swarm] || @swarm,
+          tool_call: attributes[:tool_call] || @tool_call,
+          tool_result: attributes[:tool_result] || @tool_result,
+          delegation_target: attributes[:delegation_target] || @delegation_target,
+          delegation_result: attributes[:delegation_result] || @delegation_result,
+          metadata: attributes[:metadata] || @metadata.dup,
+        )
+      end
+
+      # Convert to hash for logging and debugging
+      #
+      # @return [Hash] Simplified hash representation of context
+      def to_h
+        {
+          event: @event,
+          agent_name: @agent_name,
+          tool_name: tool_name,
+          delegation_target: @delegation_target,
+          metadata: @metadata,
+        }
+      end
+
+      # Convenience methods for creating Results
+      # These allow hooks to use `halt("message")` instead of `SwarmSDK::Hooks::Result.halt("message")`
+
+      # Halt the current operation and return a message
+      #
+      # @param message [String] Message to return
+      # @return [Result] Halt result
+      def halt(message)
+        Result.halt(message)
+      end
+
+      # Replace the current result with a custom value
+      #
+      # @param value [Object] Replacement value
+      # @return [Result] Replace result
+      def replace(value)
+        Result.replace(value)
+      end
+
+      # Reprompt the agent with a new prompt
+      #
+      # @param prompt [String] New prompt
+      # @return [Result] Reprompt result
+      def reprompt(prompt)
+        Result.reprompt(prompt)
+      end
+
+      # Finish the current agent's execution with a final message
+      #
+      # @param message [String] Final message from the agent
+      # @return [Result] Finish agent result
+      def finish_agent(message)
+        Result.finish_agent(message)
+      end
+
+      # Finish the entire swarm execution with a final message
+      #
+      # @param message [String] Final message from the swarm
+      # @return [Result] Finish swarm result
+      def finish_swarm(message)
+        Result.finish_swarm(message)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/definition.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Represents a single hook configuration
+    #
+    # A hook definition includes:
+    # - Event type (when to trigger)
+    # - Optional matcher (regex for tool names)
+    # - Priority (execution order)
+    # - Proc to execute
+    #
+    # @example Create a hook definition
+    #   definition = SwarmSDK::Hooks::Definition.new(
+    #     event: :pre_tool_use,
+    #     matcher: "Write|Edit",
+    #     priority: 10,
+    #     proc: ->(ctx) { validate_code(ctx.tool_call) }
+    #   )
+    class Definition
+      attr_reader :event, :matcher, :priority, :proc
+
+      # @param event [Symbol] Event type (e.g., :pre_tool_use)
+      # @param matcher [String, Regexp, nil] Optional regex pattern for tool names
+      # @param priority [Integer] Execution priority (higher = earlier)
+      # @param proc [Proc, Symbol] Hook proc or named hook symbol
+      def initialize(event:, matcher: nil, priority: 0, proc:)
+        @event = event
+        @matcher = compile_matcher(matcher)
+        @priority = priority
+        @proc = proc
+      end
+
+      # Check if this hook should execute for a given tool name
+      #
+      # @param tool_name [String] Name of the tool being called
+      # @return [Boolean] true if hook should execute
+      def matches?(tool_name)
+        return true if @matcher.nil? # No matcher = matches everything
+
+        @matcher.match?(tool_name)
+      end
+
+      # Check if this hook uses a named reference
+      #
+      # @return [Boolean] true if proc is a symbol (named hook)
+      def named_hook?
+        @proc.is_a?(Symbol)
+      end
+
+      # Resolve the actual proc, looking up named hooks if needed
+      #
+      # @param registry [Registry] Registry to lookup named hooks
+      # @return [Proc] The actual proc to execute
+      # @raise [ArgumentError] if named hook not found
+      def resolve_proc(registry)
+        return @proc unless named_hook?
+
+        resolved = registry.get(@proc)
+        raise ArgumentError, "Named hook :#{@proc} not found in registry" unless resolved
+
+        resolved
+      end
+
+      private
+
+      # Compile matcher string/regexp into regexp
+      #
+      # @param matcher [String, Regexp, nil] Matcher pattern
+      # @return [Regexp, nil] Compiled regex or nil
+      def compile_matcher(matcher)
+        return if matcher.nil?
+        return matcher if matcher.is_a?(Regexp)
+
+        # Convert string to regex, treating it as a pattern with | for OR
+        Regexp.new(matcher)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/hooks/error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Hooks
+    # Error raised by callbacks to block execution
+    #
+    # This error provides context about which hook failed and includes
+    # the execution context for debugging and error handling.
+    #
+    # @example Raise a hook error to block execution
+    #   raise SwarmSDK::Hooks::Error.new(
+    #     "Validation failed: invalid syntax",
+    #     hook_name: :validate_code,
+    #     context: context
+    #   )
+    class Error < StandardError
+      attr_reader :hook_name, :context
+
+      # @param message [String] Error message
+      # @param hook_name [Symbol, String, nil] Name of the hook that failed
+      # @param context [Context, nil] Execution context when error occurred
+      def initialize(message, hook_name: nil, context: nil)
+        super(message)
+        @hook_name = hook_name
+        @context = context
+      end
+    end
+  end
+end