# 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 | What to accomplish: exact goal, success criteria, expected output format. End with: "Complete ALL assigned work before responding. Your output is final." |
| `briefing` | no | All context the sub-agent needs (IPs, credentials, file paths, prior findings, step-by-step instructions). Sub-agent starts blank — include everything. |
| `profile_id` | no | Which profile to use (`secretary`, `server_admin`, `developer`). Defaults to current session's profile. |
| `system_prompt` | no | Role definition injected on top of the profile's built-in subagent prompt. Use to specialise the agent for this task (e.g. "You are a security auditor. Report findings by severity."). |
| `max_iterations` | no | Tool-call iteration limit (default: 20). |

## Context transfer — automatic

Before spawning, write key working state to your scratchpad `context_transfer` section:
```
scratchpad(op="write", section="context_transfer", content="...")
```
This section is **automatically injected** into the sub-agent at the start of its context.
Use it to pass findings from earlier tool calls or parallel agents without duplicating them in `briefing`.

## Sub-agent tools

Sub-agents receive a focused tool set (not all profile tools — 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.

## Writing a good task + briefing

```json
{
  "task": "Check CPU temperature and memory usage. Return a structured 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 to connect. Check temperature via 'sensors' or /sys/class/thermal. Check memory via 'free -h'.",
  "profile_id": "server_admin"
}
```

## Using system_prompt for role specialisation

```json
{
  "task": "Audit the SSH configuration for security issues.",
  "briefing": "Host: 192.168.1.75, user: gmikcon, password: getroot.",
  "profile_id": "server_admin",
  "system_prompt": "You are a security auditor. For each finding report: setting name, current value, risk level (critical/warning/info), recommended fix."
}
```

## 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 (only context_transfer scratchpad section is passed)
- Use administrative tools: todo, switch_profile, list_profiles, email_manager, delete_tool