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

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

1. Check `[STATUS: ...]` first.
2. Extract key findings and present them clearly to the user.
3. 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