Subagent Design and Context Passing

What a subagent actually returns to its caller, how much context it should get, and why isolation is the default, not the exception.

Agentic Architecture·Lesson 3 of 6·8 min

A subagent is not a shared thread with the orchestrator — it's a separate agentic loop with its own context window, invoked for a bounded task, that reports a result back. Two design decisions dominate whether a subagent architecture works well: how much context the subagent receives on the way in, and how much it returns on the way out.

What goes back to the parent

When a parent agent invokes a subagent, it does not receive the subagent's full transcript — the intermediate tool calls, the reasoning, the false starts. It receives a final result: a distilled answer to the question or task it was given. This matters architecturally because it's what makes subagents useful for context management. If the parent absorbed every subagent's full internal transcript, you'd gain nothing over just doing the work in the parent's own context — you'd just be paying more calls to reach the same context bloat.

This also means subagent design is partly a prompt-engineering problem for the return value. A subagent that returns "done, see above" is useless to a parent that never sees "above." A well-designed subagent is instructed to produce a self-contained final summary: what it did, what it found, and any caveats — because that summary, and nothing else, is what the orchestrator has to work with afterward.

Context isolation on the way in

The complementary decision is what the subagent receives when it's invoked. The default should be context isolation: give the subagent only what it needs for its specific subtask, not the orchestrator's entire history. Dumping the full parent context into every subagent call defeats much of the purpose of decomposing the task in the first place — you're back to one giant context, just split across multiple calls that each pay for the same tokens.

Isolation also has a quality benefit beyond token cost: a subagent handed a narrow, well-scoped brief tends to stay focused on its task, while a subagent handed the entire conversation history has to figure out which parts are relevant to it, which invites drift and irrelevant tangents in its output.

The skill here is judging what "only what it needs" actually means for a given subtask. Too little context and the subagent can't do its job or has to re-derive things the parent already knows. Too much and you've reintroduced the bloat isolation was supposed to prevent. The right amount is usually: the specific subtask description, any directly relevant facts or file contents, and explicit output-format expectations — not the full chat log that led to this point.

Exam trap A question describes a subagent invocation where the orchestrator forwards its entire conversation history "to be safe" and asks whether this is good practice. It is not, even though it feels safer. The correct answer favors deliberately scoped context passing — the exam is testing whether you understand that more context is not free and that isolation is a design principle, not a corner case to handle only when tokens run low.

Scenario: An orchestrator is researching a technical question and dispatches a subagent to read and summarize a 40-page specification document. The subagent should be given the document (or a path to it) and a specific question to answer, not the orchestrator's prior five conversation turns about an unrelated part of the project. When the subagent finishes, it should return a short, self-contained answer to the specific question — not a transcript of every section it read along the way.

Naming and describing subagents

In systems where an orchestrator chooses which subagent to invoke, the subagent's name and description function as its interface. The orchestrator picks a subagent the same way it picks a tool: based on a short description of what it does and when to use it. A vague description ("helper agent") gives the orchestrator nothing to route on and leads to the wrong subagent being picked, or the orchestrator falling back to doing the work itself. A specific description ("reviews code diffs for security vulnerabilities; does not check style or performance") lets the orchestrator dispatch correctly without inspecting the subagent's internals.

This matters more as the number of available subagents grows. With two or three subagents, ambiguity is survivable. With a dozen, overlapping or vague descriptions cause the orchestrator to misroute tasks in ways that are hard to debug after the fact, because the failure looks like a bad result rather than an obviously wrong routing decision.

Single-responsibility subagents

A subagent that tries to do several unrelated things is harder to prompt well, harder to test, and harder for an orchestrator to route to correctly. The same single-responsibility instinct that applies to functions in regular software applies here: a subagent scoped to "run tests and interpret failures" is easier to reason about and reuse than one scoped to "handle all quality assurance," which quietly expands to include linting, security scanning, and documentation review over time. Keep subagent scope narrow enough that its name alone tells you what it does and, just as importantly, what it doesn't do.

Exam trap A question describes a single subagent handling several unrelated responsibilities (say, code review, deployment, and documentation generation) and frames this as efficient because it avoids the overhead of multiple invocations. The exam expects you to flag this as a design smell — a narrowly scoped subagent per responsibility is easier to test, describe accurately for routing, and reason about when something goes wrong, and the overhead of an extra invocation is rarely the dominant cost compared to the debugging cost of an overloaded subagent.

Try it

In Claude Code or via the API, set up a small orchestrator-subagent pair: have a parent prompt dispatch a subagent with only a narrow, specific instruction and a single relevant file, then print exactly what comes back to the parent. Compare that against giving the same subagent your full running conversation as context, and notice how the final summary changes in focus and length.