Agents & Parallelism

Each subagent spawned via the Task tool starts with a blank context. Four parallel subagents give you 800k tokens of simultaneous attention. Context multiplication is the primary value — not just task delegation.

Without the skills: field in agent YAML frontmatter, the subagent discovers skills on-demand, wasting turns and tokens on context loading before doing any actual work.

Interactive permissions granted during a session don't propagate to spawned subagents. Without PreToolUse hooks auto-approving tools in the subagent definition, they interrupt repeatedly.

Claude Code has a hard 10-concurrent-subagent limit. The entire current batch must complete before the next batch starts. Structure task decomposition to optimize for batches of ≤10 independent units.

When Claude spawns a blocking subagent, Ctrl+B moves it to the background. Monitor with /tasks. This turns Claude Code from turn-based into a parallel development environment without any config change.

Set this env var to run all subagents on Haiku while your main session uses Sonnet or Opus. Subagents do focused, bounded work and rarely need the frontier model.

Setting this creates a fresh git worktree for the agent's work. Changes don't affect your working branch unless explicitly merged. Essential for risky automated refactors — the worktree is disposable.

Every file read, tool call, and reasoning step inside a subagent stays within its context window. Design subagents to return concise, structured summaries — verbose final outputs bloat the parent context.

If you open the same session ID in two terminals, messages interleave and the conversation becomes unusable. For parallel work from the same starting point, always use --fork-session.

Unlike some frameworks that auto-delegate, Codex requires explicit instruction to use subagent workflows. Each subagent does its own model and tool work — always opt-in per-task.

Each custom agent in config.toml specifies its own model, model_reasoning_effort, and sandbox_mode. A read-only mapper uses a mini model. A debugger uses the full frontier model.

The IDE Extension does not yet show subagent output inline. If you're using VSCode/Cursor and expecting to monitor subagents inline, you're looking at the wrong surface — use the app or CLI.

Redirect to a shared volume in team environments so agent job outputs are inspectable by other team members or downstream pipeline steps.

Codex CLI can start as a long-running MCP server process. The Agents SDK calls it as a tool — enabling multi-agent orchestration where a GPT-5 orchestrator delegates file editing and code execution to Codex.

The orchestrator should verify that required output files physically exist before advancing to the next agent. Don't trust 'I finished' — verify /design/design_spec.md exists. File existence is the tamper-proof gate.

The --attempts flag (1–4) tells Codex cloud to generate multiple independent solutions. For ambiguous tasks where the first solution might not be optimal, best-of-N improves quality at modest extra cost.

The orchestrator plans and delegates with minimal tool permissions. Execution subagents have the full tool surface for their domain. This prevents an orchestrator bug from causing broad damage.

The Codex TypeScript SDK uses persistent threads. Call thread.run('next prompt') to continue without re-sending history. Resume past threads by thread ID. Far more efficient than reconstructing full history.

Controls how many levels of subagents can spawn subagents. Default max = 1. Increase carefully — each depth level multiplies token cost and makes debugging exponentially harder.

Context pollution = irrelevant data filling context early. Context rot = context becoming stale and misleading later. Solution: isolated context windows per subagent and curated summary-only handoffs.