Class: SwarmSDK::V3::Hooks::Context

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

Overview

Read-only context passed to hook blocks

Each hook event type populates a different subset of fields:

| Field | before_ask | after_ask | before_tool | after_tool | on_stop | |—————–|————|———–|————-|————|———| | event | yes | yes | yes | yes | yes | | agent_name | yes | yes | yes | yes | yes | | prompt | yes | yes | - | - | - | | response | - | yes | - | - | yes | | tool_name | - | - | yes | yes | - | | tool_arguments | - | - | yes | yes | - | | tool_result | - | - | - | yes | - |

Hook blocks use convenience methods to return Result objects:

Examples:

Halt processing

before_ask { |ctx| ctx.halt("Not allowed") }

Replace a value

after_tool { |ctx| ctx.replace(sanitize(ctx.tool_result)) }

Continue normally (explicit)

before_tool { |ctx| ctx.continue }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(event:, agent_name:, prompt: nil, response: nil, tool_name: nil, tool_arguments: nil, tool_result: nil) ⇒ Context

Create a new hook context

Parameters:

  • event (Symbol) —

    Event type

  • agent_name (Symbol) —

    Agent identifier

  • prompt (String, nil) (defaults to: nil) —

    User prompt

  • response (RubyLLM::Message, nil) (defaults to: nil) —

    LLM response

  • tool_name (String, nil) (defaults to: nil) —

    Tool name

  • tool_arguments (Hash, nil) (defaults to: nil) —

    Tool arguments

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

    Tool result



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 61

def initialize(event:, agent_name:, prompt: nil, response: nil, tool_name: nil, tool_arguments: nil, tool_result: nil)
  @event = event
  @agent_name = agent_name
  @prompt = prompt
  @response = response
  @tool_name = tool_name
  @tool_arguments = tool_arguments
  @tool_result = tool_result
  freeze
end

Instance Attribute Details

#agent_name ⇒ Symbol (readonly)

Returns Agent name from definition.

Returns:

  • (Symbol) —

    Agent name from definition



35
36
37
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 35

def agent_name
  @agent_name
end

#event ⇒ Symbol (readonly)

Returns Event type (:before_ask, :after_ask, :before_tool, :after_tool, :on_stop).

Returns:

  • (Symbol) —

    Event type (:before_ask, :after_ask, :before_tool, :after_tool, :on_stop)



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

def event
  @event
end

#prompt ⇒ String? (readonly)

Returns User prompt (ask events only).

Returns:

  • (String, nil) —

    User prompt (ask events only)



38
39
40
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 38

def prompt
  @prompt
end

#response ⇒ RubyLLM::Message? (readonly)

Returns LLM response (after_ask and on_stop only).

Returns:

  • (RubyLLM::Message, nil) —

    LLM response (after_ask and on_stop only)



41
42
43
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 41

def response
  @response
end

#tool_arguments ⇒ Hash? (readonly)

Returns Tool call arguments (tool events only).

Returns:

  • (Hash, nil) —

    Tool call arguments (tool events only)



47
48
49
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 47

def tool_arguments
  @tool_arguments
end

#tool_name ⇒ String? (readonly)

Returns Tool name (tool events only).

Returns:

  • (String, nil) —

    Tool name (tool events only)



44
45
46
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 44

def tool_name
  @tool_name
end

#tool_result ⇒ Object? (readonly)

Returns Tool execution result (after_tool only).

Returns:

  • (Object, nil) —

    Tool execution result (after_tool only)



50
51
52
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 50

def tool_result
  @tool_result
end

Instance Method Details

#continue ⇒ Result

Signal to continue normal processing

Examples:

before_ask { |ctx| ctx.continue }

Returns:

  • (Result) —

    A continue result



78
79
80
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 78

def continue
  Result.continue
end

#halt(message = nil) ⇒ Result

Signal to halt processing

Examples:

Block tool execution

before_tool { |ctx| ctx.halt("Tool disabled") }

Abort ask

before_ask { |ctx| ctx.halt }

Parameters:

  • message (String, nil) (defaults to: nil) —

    Optional halt message

Returns:



92
93
94
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 92

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

#replace(value) ⇒ Result

Signal to replace a value

Examples:

Replace prompt

before_ask { |ctx| ctx.replace("Modified: #{ctx.prompt}") }

Replace tool result

after_tool { |ctx| ctx.replace(sanitize(ctx.tool_result)) }

Parameters:

  • value (Object) —

    Replacement value

Returns:

  • (Result) —

    A replace result



106
107
108
 
# File 'lib/swarm_sdk/v3/hooks/context.rb', line 106

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