Class: SwarmSDK::V3::Hooks::Result

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

Overview

Immutable value object representing the outcome of a hook execution

A Result controls flow after a hook runs. Three actions are possible:

  • continue — proceed normally (default when hook returns nil or non-Result)

  • halt — stop processing; meaning varies by event:

    • ‘before_ask`: returns nil from ask (same as interrupt)

    • ‘before_tool`: returns error string to LLM without executing tool

  • replace — substitute a value:

    • ‘before_ask`: replaces the prompt

    • ‘after_tool`: replaces the tool result

Results are created via factory methods, never directly instantiated by hook authors. Hook blocks return a Result to signal flow control.

Examples:

In a before_ask hook

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

In an after_tool hook

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

Continue (explicit)

before_ask { |ctx| ctx.continue }

Constant Summary collapse

ACTIONS =

Valid result actions

[:continue, :halt, :replace].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#action ⇒ Symbol (readonly)

Returns The action (:continue, :halt, or :replace).

Returns:

  • (Symbol) —

    The action (:continue, :halt, or :replace)



34
35
36
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 34

def action
  @action
end

#value ⇒ Object? (readonly)

Returns Associated value (halt message or replacement value).

Returns:

  • (Object, nil) —

    Associated value (halt message or replacement value)



37
38
39
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 37

def value
  @value
end

Class Method Details

.continue ⇒ Result

Create a continue result (proceed normally)

Examples:

Result.continue

Returns:

  • (Result) —

    A result with action :continue



46
47
48
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 46

def continue
  new(action: :continue)
end

.halt(message = nil) ⇒ Result

Create a halt result (stop processing)

Examples:

With message

Result.halt("Bash disabled for this agent")

Without message

Result.halt

Parameters:

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

    Optional halt message

Returns:

  • (Result) —

    A result with action :halt



60
61
62
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 60

def halt(message = nil)
  new(action: :halt, value: message)
end

.replace(value) ⇒ Result

Create a replace result (substitute a value)

Examples:

Replace prompt

Result.replace("Modified prompt text")

Replace tool result

Result.replace(sanitized_output)

Parameters:

  • value (Object) —

    Replacement value

Returns:

  • (Result) —

    A result with action :replace



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

def replace(value)
  new(action: :replace, value: value)
end

Instance Method Details

#continue? ⇒ Boolean

Whether this result signals to continue normally

Returns:

  • (Boolean) 


82
83
84
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 82

def continue?
  @action == :continue
end

#halt? ⇒ Boolean

Whether this result signals to halt processing

Returns:

  • (Boolean) 


89
90
91
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 89

def halt?
  @action == :halt
end

#replace? ⇒ Boolean

Whether this result signals to replace a value

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/swarm_sdk/v3/hooks/result.rb', line 96

def replace?
  @action == :replace
end