Subagent

A subagent is an agent spawned by a parent agent to run a delegated task in its own isolated context window, with its own system prompt, its own tool access, and independent permissions (Claude Code Docs — subagents). The parent invokes it much like a tool and keeps control of the run: the subagent works independently and returns a result, while its intermediate work never enters the parent's context. The mechanism lives in the harness layer, not the model, and it is no longer one vendor's feature: Simon Willison observes that "the subagents pattern is widely supported in coding agents now," with Claude Code, Codex, Gemini CLI, and Mistral Vibe converging on essentially the same shape (Willison, 2026-03-16).

Why it matters

The core value proposition is context isolation. Running tests, fetching documentation, or processing logs can consume significant context; delegated to a subagent, "the verbose output stays in the subagent's context while only the relevant summary returns to your main conversation" (Claude Code Docs — subagents). Subagents thus sit in the same family of context-budget controls as context-compaction and tool-result-clearing: compaction shrinks the parent's history after the fact, delegation keeps the noise out of it in the first place.

The cost side is vendor-acknowledged, not just outside critique. Anthropic's engineering write-up reports that agents use about 4x more tokens than chat interactions, and multi-agent systems about 15x more than chats; its applied guidance separately puts typical multi-agent overhead at 3–10x more tokens than a single-agent approach for equivalent tasks (as of 2026-07-12; Anthropic Engineering, Claude blog). The same guidance says to start with a single agent — "a well-designed single agent with appropriate tools can accomplish far more than many developers expect" — and names exactly three reasons to reach for subagents: context pollution, parallelization of genuinely independent subtasks, and specialization, including tool-set specialization once an agent juggles more than roughly 15–20 tools and its tool selection degrades (as of 2026-07-12; Claude blog).

Model routing makes subagents a direct cost lever. Claude Code documents pinning a cheaper model per subagent (model: haiku) explicitly as cost control, and Codex supports per-agent model and model_reasoning_effort fields (Claude Code Docs — subagents; Codex Docs — subagents). A typical configuration — not a vendor prescription — pins a fast model such as GPT-5.3-Codex-Spark to a read-heavy explorer agent while the parent runs a frontier model like GPT-5.6 Sol or Claude Fable 5 for synthesis and writes.

How it works

Fresh context by default. A subagent starts fresh in its own context window — it does not carry the parent's conversation history, previously invoked skills, or files the parent already read, though the context is not literally empty: the subagent still holds its own system prompt and tool definitions (Claude Code Docs — subagents). Claude Code's documented exception is a fork, which inherits the full parent conversation — trading isolation for continuity and reusing the parent's prompt cache (see prompt-caching) (Claude Code Docs — subagents).

Declarative definition. In Claude Code, subagents are Markdown files with YAML frontmatter (name and description required; optional fields include tools, disallowedTools, model, permissionMode, mcpServers, isolation), stored project-scoped in .claude/agents/ or in the user-level .claude/agents/ directory (Claude Code Docs — subagents). Codex defines custom agents as TOML files in the user-level .codex/agents/ or project-scoped .codex/agents/, with fields such as name, description, developer_instructions, model, and sandbox_mode (Codex Docs — subagents). The Claude Agent SDK defines subagents programmatically via an AgentDefinition object instead of files (Claude Agent SDK Docs — subagents).

Built-ins ship by default. Claude Code includes Explore (read-only, fast codebase search), Plan (research during plan mode), and general-purpose (full tool access, multi-step tasks) (Claude Code Docs — subagents); Codex ships explorer, worker, and default agent types (Codex Docs — subagents).

Nesting and concurrency are bounded. As of 2026-07-12:

Harness	Definition format	Nesting	Concurrency
Claude Code	Markdown + YAML frontmatter	Subagents can spawn subagents since v2.1.172, capped at 5 levels below the main conversation (fixed) — Claude Code Docs	Parallel dispatch supported
Codex CLI	TOML	agents.max_depth default 1 — no recursive spawning — Codex Docs	agents.max_threads default 6 — Codex Docs
Claude Agent SDK	AgentDefinition in code	Subagents can spawn subagents since v2.1.172, capped at 5 levels (omit Agent from tools to prevent) — SDK Docs	Multiple agents per query

Tool restriction is a focus and safety mechanism. Allowlists (tools) and denylists (disallowedTools) let a parent hand a subagent Bash, Read, and Grep while withholding Write and Edit, or scope it to specific MCP servers — keeping a read-only researcher honestly read-only and its tool menu small enough for reliable tool selection (Claude Code Docs — subagents).

The return trip costs context too. Whatever a subagent returns lands in the parent's window, and "running many subagents that each return detailed results can consume significant context" (Claude Code Docs — subagents). Isolation gains are undone by verbose returns, so the delegation prompt should state how compact the answer must be.

Boundaries and misconceptions

A subagent is not a handoff. The OpenAI Agents SDK models delegation as a handoff: handoff() "always transfers control to the specific agent you passed in," which takes over the run and sees the conversation, optionally filtered (OpenAI Agents SDK Docs — handoffs). A subagent call is architecturally different — the parent stays in control and receives a return value, like a tool call. Cross-vendor material that conflates the two misleads about who owns the conversation after delegation.

A subagent pipeline is not a team of specialists. Anthropic's own guidance warns against problem-centric decomposition — one subagent plans, one implements, one tests, one reviews — because each handoff loses fidelity and the system becomes "a telephone game" (Claude blog). Cognition demonstrated the underlying failure concretely: two subagents building parts of a Flappy Bird clone in parallel produced visually and functionally incompatible pieces, because "actions carry implicit decisions, and conflicting decisions carry bad results" (Cognition — Don't Build Multi-Agents). Split by independent subtask, not by pipeline role.

Isolation cuts both ways. A fresh context means the subagent starts blind: it does not know what the parent already tried, decided, or ruled out, and Claude Code's Explore and Plan built-ins skip CLAUDE.md and git status entirely by design (Claude Code Docs — subagents). Any constraint the parent needs honored must be restated in the delegation prompt — a context-engineering obligation the pattern creates rather than removes.

Delegation does not add safety by itself. In Claude Code, a parent session running in bypassPermissions or acceptEdits forces that permission mode onto its subagents, and it cannot be overridden to something safer at the subagent level (Claude Code Docs — subagents). A subagent's tool allowlist is not a substitute for the parent session's permission discipline.

The design space is contested, not settled. Cognition's 2025 position argued against parallel multi-agent systems for coding, prescribing a single-threaded agent and reserving subagents mainly for read-only question answering (Cognition — Don't Build Multi-Agents). Roughly ten months later the same company narrowed the claim: most parallel-multi-agent ideas still see little real adoption, but a "single writer" pattern — several agents contribute analysis, exactly one is allowed to write at a time — works in production (Cognition — What's Actually Working). Treat categorical "always/never" positions here as provisional.

In practice

Anthropic's Research feature is the canonical production deployment of the orchestrator-worker shape: a lead agent plans, spawns 3–5 subagents in parallel for complex queries — each with its own context window, tools, and exploration trajectory — and synthesizes their findings (Anthropic Engineering). The lead agent's own prompt embeds a scaling heuristic: one agent with 3–10 tool calls for simple fact-finding, 2–4 subagents with 10–15 calls each for comparisons, 10+ subagents for the most complex research (as of 2026-07-12, per the system write-up). On Anthropic's internal research eval, the multi-agent system (Claude Opus 4 lead, Claude Sonnet 4 subagents) outperformed single-agent Claude Opus 4 by 90.2%, token usage alone explained 80% of the eval's variance, and two-level parallelization cut research time by up to 90% for complex queries (all as of 2026-07-12; Anthropic Engineering). These numbers come from a search-and-research workload; nothing in the primary sources claims they generalize to coding, where both Anthropic and Cognition caution that decomposition is riskier (Claude blog; Cognition — Don't Build Multi-Agents).

For coding, the working patterns are narrower. Cognition cites Claude Code itself as an example of restraint — it "deliberately avoids parallel subagents, instead using them only for answering questions" (Cognition — Don't Build Multi-Agents). Under the single-writer rule, Cognition self-reports that a dedicated code-review subagent loop catches roughly 2 bugs per PR, about 58% of them rated severe (single-source, Cognition's own product data, as of 2026-07-12; Cognition — What's Actually Working) — a subagent instance of the broader evaluator-optimizer pattern, and a delegation-based alternative to peer-style multi-agent-debate. For parallel writers, Claude Code's isolation: worktree field gives a subagent its own git worktree — a filesystem boundary instead of prompt discipline (Claude Code Docs — subagents).

Codex CLI subagents are generally available — Willison's independent write-up dates the GA to 2026-03-16 and describes the implementation as "very similar to the Claude Code implementation" (Willison, 2026-03-16; Codex Docs — subagents). One residual rule from the primary sources: do not delegate latency-sensitive quick tasks — "subagents start fresh and may need time to gather context," a ramp-up cost the main conversation has already paid (Claude Code Docs — subagents).

Related

• agent-harness — the layer that implements spawning, isolation, and result return; subagents are a harness feature, not a model capability.
• context-compaction, tool-result-clearing — sibling context-budget techniques that operate on the parent's own window instead of delegating.
• context-rot — the context degradation that delegation keeps out of the parent's window by moving noisy work off the main thread.
• swe-agent — a well-documented agent scaffold useful as a contrast point when deciding whether a task needs delegation at all.
• goal-mode — a technique for framing the objective a delegated agent receives.