# 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

```json
{
  "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.

1. If "hit iteration limit" — note what is missing in your response.
2. Synthesise key findings in your own words.
3. 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