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 = 
"You are a focused sub-agent. #{COMMUNICATION_INSTRUCTION}\n"

Constants included from SubagentPrompts

Tools::SubagentPrompts::COMMUNICATION_INSTRUCTION, Tools::SubagentPrompts::EXPECTED_DELIVERABLE_PREFIX

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

schema

Constructor Details

#initialize(session:) ⇒ SpawnSubagent

Returns a new instance of SpawnSubagent.

Parameters:

  • session (Session) —

    the parent session spawning the sub-agent



53
54
55
 
# File 'lib/tools/spawn_subagent.rb', line 53

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
  "Spawn a generic sub-agent to work on a task autonomously. " \
    "The sub-agent inherits your conversation context, works independently, " \
    "and its text messages are forwarded to you automatically. " \
    "Address it via @nickname to send follow-up instructions."
end

.input_schema ⇒ Object 



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/tools/spawn_subagent.rb', line 28

def self.input_schema
  {
    type: "object",
    properties: {
      task: {
        type: "string",
        description: "What the sub-agent should do (persisted as its first user message)"
      },
      expected_output: {
        type: "string",
        description: "Description of the expected deliverable"
      },
      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 expected_output]
  }
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”, “expected_output”, and optional “tools”

Returns:

  • (String) —

    confirmation with child session ID and @nickname

  • (Hash{Symbol => String}) —

    with :error key on validation failure



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/tools/spawn_subagent.rb', line 64

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

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

  tools = normalize_tools(input["tools"])

  error = validate_tools(tools)
  return error if error

  child = spawn_child(task, expected_output, 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."
end