# Subagent Tools

Spawn independent subagent sessions with JIT-generated identities.

**Trigger condition**: a task decomposes into independent subtasks needing multi-step reasoning; you are processing N items with the same operation; or the current agent's identity would work against subtask quality.

---

## subagent_generate

Generate a JIT agent config. No args prints the template. With JSON input, creates the config and prints the agent name.

**Calling convention**:
```
pipe: stages=[
  {tool: "subagent_generate", args: ["JSON_CONFIG"]},
  {tool: "subagent_spawn", args: ["-name", "NAME", "TASK"]}
]
```

JSON_CONFIG fields:

| Field | Required | Description |
|---|---|---|
| `role` | **yes*** | Who this agent is and what it does |
| `roster` | no | Name → task mapping of all peers, `(you)` marking this agent |
| `shared_task` | no | Tracking entry or issue ID |
| `protocol` | no | Coordination mechanics |
| `constraints` | no | Array of constraint strings |
| `name` | no | Config name (default: `jit-<hex>`) |
| `prompt` | **yes*** | Legacy: complete identity as a single string |

*One of `role` or `prompt` required. Prefer `role`.

---

## subagent_spawn

Spawn a session, submit a prompt, return immediately.

**Calling convention**:
```
call_tool: calls=[{tool: "subagent_spawn", args: ["-name", "NAME", "TASK"]}]
call_tool: calls=[{tool: "subagent_spawn", args: ["-name", "NAME", "-agent", "AGENT", "-backend", "B", "-model", "M", "TASK"]}]
```

**Flags**: `-name NAME`, `-agent A`, `-backend B`, `-model M`, `-cwd DIR`.

**Returns**: `session`, `path`, `backend`, `model` as KV lines.

Auto-injects into the prompt: `[parent_session_id=...]`, `[session_id=...]`, and parent plan contents.

---

## Returning results to the parent

Subagents write to `s/{parent_session_id}/prompt` when done:
```
[from={session_id}]
STATUS: done|blocked|partial
SUMMARY: <what was accomplished>
ARTIFACTS: <paths written, omit if none>
OPEN: <unresolved items, omit if none>
```

**Critical**: the parent must NEVER actively wait for results. No `statewait`, no polling. After spawning, continue work or end your turn. Results queue automatically.

---

## Constraints

- **Identity carries coordination, prompt carries task.** Roster/protocol go in the identity. The spawn prompt is purely the task.
- Subagents do not share memory. Pass context explicitly in the seed prompt.
- Names must be globally unique under `s/`. Prefix with parent session ID is automatic.
- For simple delegation with no identity requirements, `subagent_spawn` alone with `-agent` or defaults is fine.