spawn_agent — Manual

What it does

Delegates a focused multi-step sub-task 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.

CRITICAL: spawn_agent is SYNCHRONOUS. It blocks until the sub-agent fully completes (or times out after 5 minutes).

Parameters

Parameter	Required	Description
`task`	yes	Self-contained task description including all context, credentials, expected output format. End with: "Complete ALL assigned work before responding. Your output is final."
`profile_id`	no	Which profile to use (`secretary`, `server_admin`, `developer`). Defaults to current session's profile.
`system_prompt`	no	Custom system prompt injected into the sub-agent on top of the profile's built-in subagent prompt. Use to set a specific role, output format, or constraints for this task.
`max_iterations`	no	Tool-call iteration limit (default: 20).

Context transfer — automatic

Before spawning, write key context to your scratchpad section context_transfer:

scratchpad(op="write", section="context_transfer", content="Host: 192.168.1.75\nUser: gmikcon\n...")

This section is automatically injected into the sub-agent at the start of its context. No need to repeat it in task.

Sub-agent tools

Sub-agents receive a focused tool set (not all profile tools):

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

Result format

The result always starts with a status line:

[STATUS: completed]          ← sub-agent finished normally
[STATUS: limit_reached]      ← hit max_iterations without a final response

Read the status before deciding what to do next. If limit_reached, the partial result may still be useful, or you may need to spawn again with a more focused task.

Writing a good task

Bad:

"Check the server security."

Good:

"Audit SSH configuration on 192.168.1.75 (user: gmikcon, password: getroot). Check: PasswordAuthentication, PermitRootLogin, AllowUsers, Port. Return a list of findings with severity (critical/warning/info) and suggested fix for each. Complete ALL assigned work before responding. Your output is final."

Include:

Exactly what to do (not vague goals)
What to return and in what format
What "done" looks like

Using system_prompt

Use system_prompt to give the sub-agent a specific role or output contract:

{
  "task": "Check CPU temperature and memory usage on the host.",
  "profile_id": "server_admin",
  "system_prompt": "You are a system metrics collector. Report all values in a structured table. Include: metric name, current value, unit, status (ok/warn/crit). No prose."
}

After the result arrives

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

Check [STATUS: ...] first.
Extract key findings and present them clearly to the user.
If limit_reached, decide: retry with a smaller task, or handle inline.

What the sub-agent cannot do

Spawn further sub-agents (recursion is blocked)
Access your conversation history (only context_transfer scratchpad section)
Use administrative tools: todo, switch_profile, list_profiles, reload_tools (except developer), delete_tool, email_manager