# 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.

**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 | 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 as system-level context into the sub-agent. |
| `profile_id` | no | Which profile to use (`secretary`, `server_admin`, `developer`). Defaults to current session's profile. |
| `system_prompt` | no | Role specialisation for this task (e.g. "You are a security auditor. Report findings by severity."). Injected on top of the profile's built-in subagent prompt. |
| `max_iterations` | no | Tool-call iteration limit (default: 20). |

## Sub-agent tools

Sub-agents receive a focused tool set (no todo, switch_profile, email_manager, etc.):

| 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 header tells you how the sub-agent finished:
- `[Sub-agent completed ...]` — finished normally; synthesise the findings.
- `[Sub-agent hit iteration limit ...]` — may be incomplete; note what's missing in your response.

**Never repeat the result header to the user.** Synthesise findings in your own words.

## Example: correct multi-agent execution

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

**Wrong:** `spawn_agent(task="Research X and Y pricing and write a comparison")` — 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. Check memory via 'free -h'.",
  "profile_id": "server_admin",
  "system_prompt": "You are a system metrics collector. Report all values in a structured table."
}
```

## After the result arrives

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

1. Read the result header to know if it completed or hit the limit.
2. Extract key findings and present them clearly to the user.
3. If incomplete, decide: retry with a more focused task, or handle inline.

## What the sub-agent cannot do
- Spawn further sub-agents (recursion is blocked)
- Access your conversation history
- Use administrative tools: todo, switch_profile, list_profiles, email_manager, delete_tool