Subagent Isolation and Contracts

Subagents are the workhorse of reliable multi-step automation in Codex. Instead of asking one agent to understand everything, decide everything, and change everything, you spawn small, isolated workers that each do one job under tight constraints—and report back in a format you can automatically validate.

This lesson focuses on two foundations:

• Subagent isolation: keep the worker narrowly scoped so it can't roam across the repo or take unintended actions.
• Output contracts: make the worker's response predictable (ideally strict JSON) so you can safely chain steps together.

A subagent is an isolated Codex run created for a single task. The isolation is the point: the subagent is easiest to reason about when it's given a small "world" and a clear objective.

In practice, a good subagent has:

1. A scope ("only analyze this directory")
2. A task ("identify missing unit tests")
3. A policy ("don't apply changes automatically")
4. A contract ("return strict JSON with these fields")

When you keep those explicit, you get runs that are easier to audit, debug, and compose into pipelines.

If you ask an agent to "improve test coverage," it might:

• read far outside the area you intended (because it wants more context),
• make large refactors (because it notices style issues),
• write code when you only wanted a report.

Isolation doesn't magically prevent mistakes, but it limits the blast radius and makes behavior easier to validate. You can treat each subagent like a bounded operation: "it looked only here," "it returned only this shape," "it changed nothing."

That last part is where output contracts become your enforcement mechanism.

Subagents are most useful when their output can be consumed by something else—another step, a script, a CI job, or a human who wants a clean checklist.

Free-form prose is pleasant, but brittle for automation. An output contract is a strict agreement that the subagent will output data in a known structure—typically JSON.

The rule of thumb is simple: if you plan to chain this result into anything, don't accept "helpful explanation." Accept parseable output.

That's why the contract you'll use in this lesson insists on:

• STRICT JSON
• no markdown
• no prose
• exactly one JSON object