Class: SwarmSDK::Hooks::Adapter

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/hooks/adapter.rb

Overview

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.

Examples:

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"

Constant Summary collapse

SWARM_LEVEL_EVENTS =

Swarm-level events (only these allowed at swarm.hooks level)

[:swarm_start, :swarm_stop].freeze
AGENT_LEVEL_EVENTS =

Agent-level events (allowed in all_agents.hooks and agent.hooks)

[
  :pre_tool_use,
  :post_tool_use,
  :user_prompt,
  :agent_step,
  :agent_stop,
  :first_message,
  :pre_delegation,
  :post_delegation,
  :context_warning,
].freeze

Class Method Summary collapse

Class Method Details

.apply_agent_hooks(agent, agent_name, hooks_config, swarm_name) ⇒ void

This method returns an undefined value.

Apply agent-specific hooks to an already-initialized agent

This is called during agent initialization for each agent that has hooks configured.

Parameters:

  • agent (AgentChat) —

    Agent instance

  • agent_name (Symbol) —

    Agent name

  • hooks_config (Hash) —

    Hooks configuration from YAML

  • swarm_name (String) —

    Swarm name for environment variables



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/swarm_sdk/hooks/adapter.rb', line 99

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

.apply_hooks(swarm, config) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • swarm (Swarm) —

    Swarm instance to configure

  • config (Configuration) —

    Parsed YAML configuration



79
80
81
82
83
84
85
86
87
88
 
# File 'lib/swarm_sdk/hooks/adapter.rb', line 79

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