Subagents: when to split work and how to keep the parent lean

A subagent is an agent the parent invokes through a tool. It runs autonomously with its own context window and returns a result. Use it to offload context-heavy work, not as a default.

How it works:
1. Define the subagent with its own model, instructions, and tools (usually a narrow, read-oriented set).
2. Expose it to the parent as a tool. The parent calls it like any other tool.
3. The subagent executes independently, then returns. Use toModelOutput to summarize its findings so the parent sees 1,000 tokens, not the 200,000 the subagent consumed.
4. Optionally stream progress to the UI so the wait does not look dead.

Use subagents when:
- tasks require exploring large token volumes (codebase research, doc sweeps)
- independent research can run in parallel (spawn several, synthesize)
- context would otherwise exceed model limits mid-run
- tool access should be isolated by capability (read-only explorer vs file editor vs deploy tools)

Avoid subagents when:
- the task is simple and focused (direct tool calls are cheaper and faster)
- sequential processing suffices (no parallelism win)
- context stays manageable (no offload win)

Rules:
1. Subagents add latency and complexity. Start with the simplest architecture that meets the need; add subagents when measurements (context usage, latency) justify them.
2. Give subagents least-privilege tools. An exploration subagent gets read-only tools; it should not be able to edit or deploy.
3. Summarize aggressively at the boundary. The parent's context is the scarce resource; toModelOutput is how you protect it.
4. Parallel subagents need independent tasks. If they all read the same files, you pay N times the tokens for one insight.
5. Log subagent inputs/outputs at the parent level. Debugging a black-box subagent without its trace is miserable.