Class: Tools::SpawnSubagent

Inherits:
Base
  • Object
show all
Includes:
SubagentPrompts
Defined in:
lib/tools/spawn_subagent.rb

Overview

Spawns a generic child session that works on a task autonomously. The sub-agent inherits the parent’s viewport context at fork time, runs via AgentRequestJob, and communicates with the parent through natural text messages routed by Events::Subscribers::SubagentMessageRouter.

Nickname assignment is handled by the AnalyticalBrain::Runner which runs synchronously at spawn time — the same brain that manages skills, goals, and workflows for the main session.

For named specialists with predefined prompts and tools, see SpawnSpecialist.

Constant Summary collapse

GENERIC_PROMPT = 
"#{COMMUNICATION_INSTRUCTION}\n"

Constants included from SubagentPrompts

Tools::SubagentPrompts::COMMUNICATION_INSTRUCTION, Tools::SubagentPrompts::FORK_FRAMING_MESSAGE, Tools::SubagentPrompts::IDENTITY_TEMPLATE

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

schema, truncation_threshold

Constructor Details

#initialize(session:) ⇒ SpawnSubagent

Returns a new instance of SpawnSubagent.

Parameters:

  • session (Session) —

    the parent session spawning the sub-agent



46
47
48
 
# File 'lib/tools/spawn_subagent.rb', line 46

def initialize(session:, **)
  @session = session
end

Class Method Details

.description ⇒ Object 



21
22
23
24
25
26
 
# File 'lib/tools/spawn_subagent.rb', line 21

def self.description
  "Task feels like a sidequest or a context-switch? Hand it off. " \
    "Inherits your context; its messages appear in yours. " \
    "Any message containing @nickname is forwarded — " \
    "even casual mentions will wake the sub-agent."
end

.input_schema ⇒ Object 



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/tools/spawn_subagent.rb', line 28

def self.input_schema
  {
    type: "object",
    properties: {
      task: {type: "string"},
      tools: {
        type: "array",
        items: {type: "string"},
        description: "Tool names to grant the sub-agent. " \
          "Omit for all standard tools. Empty array for pure reasoning. " \
          "Valid tools: #{AgentLoop::STANDARD_TOOLS_BY_NAME.keys.join(", ")}"
      }
    },
    required: %w[task]
  }
end

.tool_name ⇒ Object 



19
 
# File 'lib/tools/spawn_subagent.rb', line 19

def self.tool_name = "spawn_subagent"

Instance Method Details

#execute(input) ⇒ String, Hash{Symbol => String}

Creates a child session, runs the analytical brain to assign a nickname, persists the task as a user message, and queues background processing. Returns immediately after brain completes (blocking for ~200ms).

Parameters:

  • input (Hash<String, Object>) —

    with “task” and optional “tools”

Returns:

  • (String) —

    confirmation with child session ID and @nickname

  • (Hash{Symbol => String}) —

    with :error key on validation failure



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/tools/spawn_subagent.rb', line 57

def execute(input)
  task = input["task"].to_s.strip

  return {error: "Task cannot be blank"} if task.empty?

  tools = normalize_tools(input["tools"])

  error = validate_tools(tools)
  return error if error

  child = spawn_child(task, tools)
  nickname = child.name
  "Sub-agent @#{nickname} spawned (session #{child.id}). " \
    "Its messages will appear in your conversation. " \
    "Reply with @#{nickname} to send it instructions — " \
    "any message mentioning @#{nickname} is forwarded, even in narration."
end