spawn_agent — Manual

What it does

Delegates EXACTLY ONE step of your plan to an isolated agent instance with its own tool-calling loop and a clean context window. Returns the sub-agent's complete final response as a tool result.

One plan step = one spawn_agent call. If your plan has three AGENT steps, make three separate calls.

SYNCHRONOUS — blocks until the sub-agent fully completes or times out (5 minutes hard limit).

Parameters

Parameter	Required	Description
`task`	yes	Goal for this one step, success criteria, expected output format. End with: "Complete ALL assigned work before responding. Your output is final."
`briefing`	no	Credentials, IPs, file paths, constraints, step-by-step instructions — injected into the sub-agent's system prompt as `## Task context`.
`profile_id`	no	Which profile to use (`secretary`, `server_admin`, `developer`). Defaults to current session's profile.
`system_prompt`	no	Role specialisation injected into the sub-agent's system prompt between the executor persona and the briefing (e.g. "You are a security auditor. Report findings by severity.").
`max_iterations`	no	Tool-call iteration limit (default: 40).

Sub-agent system prompt structure

The sub-agent receives a completely separate system prompt — no persona, no orchestrator instructions, no available-profiles block. It is built from up to three parts (separated by ---):

1. profile.subagent_system_prompt   ← focused executor persona (from subagent_system_prompt.txt)
2. system_prompt param              ← role specialisation (if provided)
3. ## Task context\n\n{briefing}    ← credentials, instructions (if briefing provided)

Fallback: if the profile has no subagent_system_prompt.txt, uses profile.system_prompt.

Sub-agent tools

Sub-agents receive a dedicated, focused tool set (defined in subagent_tools in profile config):

Profile	Sub-agent tools
`secretary`	scratchpad, reflect, mcp:navi-web:web_search, mcp:navi-web:web_view, mcp:navi-web:http_request, filesystem, code_exec, image_view, memory, share_file, weather
`server_admin`	scratchpad, reflect, mcp:navi-web:web_search, mcp:navi-web:http_request, filesystem, code_exec, terminal, ssh_exec, image_view, share_file
`developer`	scratchpad, reflect, mcp:navi-web:web_search, mcp:navi-web:web_view, mcp:navi-web:http_request, filesystem, code_exec, terminal, image_view, reload_tools, test_tool, share_file

spawn_agent is always excluded — recursion is impossible.

Result format

The result always starts with a header visible only to you (never repeat it to the user):

[Sub-agent completed ...] — finished normally; synthesise the findings.
[Sub-agent hit iteration limit ...] — may be incomplete; note what's missing.

Multi-agent execution pattern

Plan step 2 → AGENT  →  spawn_agent(task="Research pricing for X ...", briefing="...")
Plan step 3 → AGENT  →  spawn_agent(task="Research pricing for Y ...", briefing="...")
Plan step 4 → SELF   →  synthesise both results, write final answer

Wrong: spawn_agent(task="Research X and Y and compare") — two steps, one call.

Full example

{
  "task": "Check CPU temperature and memory usage. Return a table: metric, value, unit, status (ok/warn/crit). Complete ALL assigned work before responding. Your output is final.",
  "briefing": "Host: 192.168.1.75\nUser: gmikcon\nPassword: getroot\nUse ssh_exec. Check temperature via 'sensors' or /sys/class/thermal/thermal_zone*/temp (divide by 1000). Check memory via 'free -h'.",
  "profile_id": "server_admin",
  "system_prompt": "You are a system metrics collector. Report all values in a structured table with columns: metric, value, unit, status."
}

After the result arrives

The user cannot see sub-agent output — present findings yourself.

If "hit iteration limit" — note what is missing in your response.
Synthesise key findings in your own words.
If result is insufficient, spawn again with a more focused task.

What the sub-agent cannot do

Spawn further sub-agents (recursion blocked)
Access conversation history (only context from the current call)
Use: todo, switch_profile, list_profiles, email_manager, delete_tool, list_tools, tool_manual