Subagents and delegation
A subagent is a second agent, with its own context window, its own instructions, and usually a restricted set of tools. The main agent hands it a task and gets back a result.
The real reason to use one
The point is context isolation, not parallelism.
Searching a large codebase might read forty files to find three relevant ones. If the main agent does that, all forty are now in its context, crowding out the work. If a subagent does it, only the answer comes back.
That is the pattern: expensive exploration with a small answer.
Good candidates
Search and research. "Find every place we validate an email address." Reads a lot, returns a list.
Review. A reviewer with read only tools and a checklist, returning findings. Isolation also helps here, because a fresh context is not attached to the code it just wrote.
Anything with a big intermediate. Parsing a large log, scanning dependencies, summarising a long document.
Bad candidates
Work needing the full conversation. If the subagent needs everything the main agent knows, you pay to transfer it and gain nothing.
Tightly coupled edits. Two agents editing overlapping files produce conflicts that neither can see.
Trivial tasks. Spinning up a subagent to read one file costs more than reading it.
Give them fewer tools, not more
A reviewer that can edit files will edit files. A researcher that can push commits eventually will.
Restricting tools is the cheapest reliability improvement available. It removes whole categories of mistake rather than instructing against them.
The handoff is the hard part
A subagent starts cold. It has your task description and nothing else.
Vague: "review the auth changes."
Workable: "review src/auth/session.ts and src/auth/tokens.ts for security issues, focusing on token expiry and session fixation. Report file and line for each finding. Do not edit anything."
Every assumption you leave implicit gets re-derived, usually wrongly.
Watch the cost
Subagents multiply token usage. Each carries its own system prompt and tool definitions before doing any work.
For a task with a large intermediate and a small answer, that trade is clearly worth it. For a task where the intermediate is already small, it is pure overhead. The token cost calculator makes that concrete.
Templates
The templates section has subagent definitions for code review, research, security auditing, and several other roles, including the allowed tool lists.