Skip to main content
The subagent’s report is the only thing the parent receives. Everything else — every search, every file read, every draft — stays inside the subagent. Design the report first and the body second: the body exists to produce the deliverable.

​
The minimum deliverable

The specification recommends a minimum shape:
The rules that make it work:
  • Status first. A parent juggling several subagents triages by status before reading anything else. Two values are enough: completed and blocked.
  • The summary stands alone. Assume the parent reads nothing below it. One paragraph: what was produced and the key outcome.
  • Artifacts are addresses, not contents. Return paths and locations. The parent loads what it needs, when it needs it.
  • Notes carry judgment. Assumptions the subagent made, deviations from the task, and anything the parent should know before acting. Omit the section when it’s empty.
Put the template in the subagent’s body. Subagents pattern-match well against concrete structures — a body that shows the report shape gets that shape back.

​
A worked example

A repo-explorer subagent asked to map how authentication works returns:
The summary is enough to answer the parent’s question. The artifacts tell the parent exactly where to look when it acts. The notes prevent a mistake the parent would otherwise make. Nothing more.

​
Big outputs: write files, return paths

When the deliverable is large — a full report, generated code, a dataset — have the subagent write it to a file and return the path. This keeps the parent’s context small and gives the parent a durable artifact to hand to the next subagent, to the user, or to version control.
Instruct the subagent to make every path absolute or unambiguous, and to verify each artifact exists before reporting it. A path to a file that was never written is the most expensive kind of lie in a report.

​
When blocked

A subagent cannot ask the user for help. Its only recourse is a well-formed blocked report:
What makes a blocked report useful: the reason (one sentence), what is missing, and whether the run left state behind. The parent can then fix the situation and re-delegate, or take over.
Design the body so the subagent records assumptions in Notes rather than blocking on them. Blocked status is for missing resources — credentials, unreachable services, absent files — not for judgment calls.

​
Calibrating detail

When the parent runs several subagents, their reports share one context. Five subagents returning five detailed reports can crowd out the parent’s own reasoning. Keep summaries tight, push detail into artifacts, and let the task the parent sends set the depth — the parent can ask for “a two-sentence summary” or “every finding with file and line” in the delegation. If the report keeps coming back heavier than the parent needs, the fix is in the body’s deliverable section, not in the parent’s reading habits.