Class: SwarmSDK::Hooks::Context

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

Overview

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).

Examples:

Access tool call information

context.tool_call.name  # => "Write"
context.tool_call.parameters  # => { file_path: "...", content: "..." }

Modify metadata

context.metadata[:validated] = true
context.metadata[:validation_time] = Time.now

Check event type

if context.tool_event?
  validate_tool_call(context.tool_call)
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(event:, agent_name:, agent_definition: nil, swarm: nil, tool_call: nil, tool_result: nil, delegation_target: nil, delegation_result: nil, metadata: {}) ⇒ Context

Returns a new instance of Context.

Parameters:

  • event (Symbol) —

    The event type triggering this hook

  • agent_name (String, Symbol) —

    Name of the agent

  • agent_definition (SwarmSDK::AgentDefinition, nil) (defaults to: nil) —

    Agent's configuration

  • swarm (SwarmSDK::Swarm, nil) (defaults to: nil) —

    Reference to the swarm (if available)

  • tool_call (ToolCall, nil) (defaults to: nil) —

    Tool call object (for tool events)

  • tool_result (ToolResult, nil) (defaults to: nil) —

    Tool result (for post_tool_use)

  • delegation_target (String, Symbol, nil) (defaults to: nil) —

    Target agent name (for delegation events)

  • delegation_result (Object, nil) (defaults to: nil) —

    Result from delegation (for post_delegation)

  • metadata (Hash) (defaults to: {}) —

    Additional metadata



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/swarm_sdk/hooks/context.rb', line 42

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

Instance Attribute Details

#agent_definition ⇒ Object (readonly)

Returns the value of attribute agent_definition.



30
31
32
 
# File 'lib/swarm_sdk/hooks/context.rb', line 30

def agent_definition
  @agent_definition
end

#agent_name ⇒ Object (readonly)

Returns the value of attribute agent_name.



30
31
32
 
# File 'lib/swarm_sdk/hooks/context.rb', line 30

def agent_name
  @agent_name
end

#delegation_result ⇒ Object

Returns the value of attribute delegation_result.



31
32
33
 
# File 'lib/swarm_sdk/hooks/context.rb', line 31

def delegation_result
  @delegation_result
end

#delegation_target ⇒ Object

Returns the value of attribute delegation_target.



31
32
33
 
# File 'lib/swarm_sdk/hooks/context.rb', line 31

def delegation_target
  @delegation_target
end

#event ⇒ Object (readonly)

Returns the value of attribute event.



30
31
32
 
# File 'lib/swarm_sdk/hooks/context.rb', line 30

def event
  @event
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



30
31
32
 
# File 'lib/swarm_sdk/hooks/context.rb', line 30

def metadata
  @metadata
end

#swarm ⇒ Object (readonly)

Returns the value of attribute swarm.



30
31
32
 
# File 'lib/swarm_sdk/hooks/context.rb', line 30

def swarm
  @swarm
end

#tool_call ⇒ Object

Returns the value of attribute tool_call.



31
32
33
 
# File 'lib/swarm_sdk/hooks/context.rb', line 31

def tool_call
  @tool_call
end

#tool_result ⇒ Object

Returns the value of attribute tool_result.



31
32
33
 
# File 'lib/swarm_sdk/hooks/context.rb', line 31

def tool_result
  @tool_result
end

Instance Method Details

#breakpoint ⇒ void

This method returns an undefined value.

Enter an interactive debugging breakpoint

This method:

  1. Emits a breakpoint_enter event (formatters can pause spinners)
  2. Opens binding.irb for interactive debugging
  3. Emits a breakpoint_exit event (formatters can resume spinners)

Examples:

Use in a hook

hook(:pre_delegation) do |ctx|
  ctx.breakpoint  # Pause execution and inspect context
end



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/swarm_sdk/hooks/context.rb', line 175

def breakpoint
  # Emit breakpoint_enter event
  LogStream.emit(
    type: "breakpoint_enter",
    agent: @agent_name,
    event: @event,
    timestamp: Time.now.utc.iso8601,
  )

  # Enter interactive debugging
  binding.irb # rubocop:disable Lint/Debugger

  # Emit breakpoint_exit event
  LogStream.emit(
    type: "breakpoint_exit",
    agent: @agent_name,
    event: @event,
    timestamp: Time.now.utc.iso8601,
  )
end

#delegation_event? ⇒ Boolean

Check if this is a delegation-related event

Returns:

  • (Boolean) —

    true if event is pre_delegation or post_delegation



74
75
76
 
# File 'lib/swarm_sdk/hooks/context.rb', line 74

def delegation_event?
  [:pre_delegation, :post_delegation].include?(@event)
end

#finish_agent(message) ⇒ Result

Finish the current agent's execution with a final message

Parameters:

  • message (String) —

    Final message from the agent

Returns:

  • (Result) —

    Finish agent result



150
151
152
 
# File 'lib/swarm_sdk/hooks/context.rb', line 150

def finish_agent(message)
  Result.finish_agent(message)
end

#finish_swarm(message) ⇒ Result

Finish the entire swarm execution with a final message

Parameters:

  • message (String) —

    Final message from the swarm

Returns:

  • (Result) —

    Finish swarm result



158
159
160
 
# File 'lib/swarm_sdk/hooks/context.rb', line 158

def finish_swarm(message)
  Result.finish_swarm(message)
end

#halt(message) ⇒ Result

Halt the current operation and return a message

Parameters:

  • message (String) —

    Message to return

Returns:



126
127
128
 
# File 'lib/swarm_sdk/hooks/context.rb', line 126

def halt(message)
  Result.halt(message)
end

#replace(value) ⇒ Result

Replace the current result with a custom value

Parameters:

  • value (Object) —

    Replacement value

Returns:



134
135
136
 
# File 'lib/swarm_sdk/hooks/context.rb', line 134

def replace(value)
  Result.replace(value)
end

#reprompt(prompt) ⇒ Result

Reprompt the agent with a new prompt

Parameters:

  • prompt (String) —

    New prompt

Returns:

  • (Result) —

    Reprompt result



142
143
144
 
# File 'lib/swarm_sdk/hooks/context.rb', line 142

def reprompt(prompt)
  Result.reprompt(prompt)
end

#to_h ⇒ Hash

Convert to hash for logging and debugging

Returns:

  • (Hash) —

    Simplified hash representation of context



109
110
111
112
113
114
115
116
117
 
# File 'lib/swarm_sdk/hooks/context.rb', line 109

def to_h
  {
    event: @event,
    agent_name: @agent_name,
    tool_name: tool_name,
    delegation_target: @delegation_target,
    metadata: @metadata,
  }
end

#tool_event? ⇒ Boolean

Check if this is a tool-related event

Returns:

  • (Boolean) —

    true if event is pre_tool_use or post_tool_use



67
68
69
 
# File 'lib/swarm_sdk/hooks/context.rb', line 67

def tool_event?
  [:pre_tool_use, :post_tool_use].include?(@event)
end

#tool_name ⇒ String?

Get tool name (convenience method)

Returns:

  • (String, nil) —

    Tool name or nil if not a tool event



81
82
83
 
# File 'lib/swarm_sdk/hooks/context.rb', line 81

def tool_name
  tool_call&.name
end

#with(**attributes) ⇒ Context

Create a copy of this context with modified attributes

Useful for chaining hooks that need to pass modified context to subsequent hooks.

Parameters:

  • attributes (Hash) —

    Attributes to override

Returns:

  • (Context) —

    New context with modified attributes



92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/swarm_sdk/hooks/context.rb', line 92

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