# 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 by default** — blocks until the sub-agent fully completes or times out (5 minutes hard limit). With `"background": true` the call detaches immediately and returns a `task_id` (`bt-...`); the sub-agent keeps running in isolation — see the `tasks` manual for `list`/`check`/`wait`/`cancel`, and PARALLELISM rules in your persona. Background sub-agents are capped separately (`tasks_max_spawn` per session) and their token usage is reported via `task_update`, not in your turn's token count.

## When to use it — and when not

Use it when a step needs **3+ tool calls to complete as one logical unit**: a research question that takes several searches and reads, an ops task that chains SSH commands, an investigation with an unknown number of steps.

Do **not** use it for a single tool call. If the step is "read this file", "run this test", "check whether the service is up" — call the tool yourself. A sub-agent costs a whole extra agent run and gives you back only its final text.

The sub-agent also gets a **different, narrower tool set** than you have (see [Sub-agent tools](#sub-agent-tools)) and cannot see this conversation. If the step needs a tool the sub-agent will not have, or needs what you have already learned, do it yourself.

## Choosing `profile_id`

**Omit it by default.** The sub-agent then runs as the current session's profile — the right choice for most work, and the one that keeps its tools closest to yours.

Set it to specialise:
- `server_admin` — remote ops over SSH, server state, infrastructure.
- `secretary` — research and writing, web-heavy work.
- `developer` — writing code, including Navi's own MCP servers.

If your plan named a profile for this step, pass that exact id. The profile decides the sub-agent's model, system prompt and available tools — a wrong pick shows up as the sub-agent lacking what it needs.

```json
{"task": "...", "briefing": "..."}                                  // current profile
{"task": "...", "profile_id": "server_admin", "briefing": "..."}    // specialised
```

## 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**). |
| `background` | no | `true` → detach immediately, return `task_id`; result arrives later as a completion note (use `tasks` to check/wait/cancel). |
| `inherit_system_prompt` | no | `true` → the parent profile's full system prompt is the **base layer**, with the sub-agent's own specialisation overlaid on top. Use when the sub-agent must keep the parent's personality, rules and workflow. Default `false`: the sub-agent uses only its own `subagent_system_prompt` and ignores the parent's entirely. |

## 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.10\nUser: ops\nPassword: <ssh-password>\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