Subagents: how Claude Code fans out without losing the plot

Long Claude Code sessions rarely die because the model got dumber. They die because the context filled up with debris: grep output, six files read to answer one question, a build log that mattered exactly once. Everything the agent touches stays in the window and dilutes what comes after. The structural answer in Claude Code isn't a bigger window. It's subagents.

A subagent is a fresh agent loop with its own empty context. The main thread hands it a task in a sentence or two; it burns as many tool calls as it needs (searching, reading, comparing) and only a final report comes back. The fifty files it read live and die in its own window. Your main thread keeps the conclusion, not the file dumps.

How the fan-out works

Mechanically, delegation happens through a task tool: the main agent writes a prompt describing the job, picks an agent type, and waits. The subagent runs to completion and returns exactly one message. Two properties matter.

• Isolation. The subagent's exploration never lands in the main context. A codebase survey that touches forty files costs the main thread one paragraph.
• Parallelism. Independent questions fan out simultaneously: one agent maps the auth flow while another audits test coverage, and the answers arrive together.

The economics follow. The main context pays for a handoff prompt and a report; the messy middle gets billed to a window that is thrown away afterward. This is the orchestrator-worker pattern from agent architecture, packaged into a single tool call: the orchestrator stays coherent by keeping its workers disposable.

Custom agents in .claude/agents

Out of the box you get a general-purpose worker. The real value is in defining your own: each agent is a markdown file in .claude/agents/ with YAML frontmatter (a name, a description, a tool allowlist, optionally a different model).

---
name: code-reviewer
description: Reviews diffs for correctness and convention drift. Use after significant edits.
tools: Read, Grep, Glob
---
You are a strict reviewer. Report issues by file and line, worst first.

A reviewer that physically cannot edit files is a more trustworthy reviewer. A search agent on a fast, cheap model is a better search agent. The description is load-bearing. It's how the main agent decides when to delegate, so write it like an API contract, not a slogan.

A subagent earns its keep by keeping its mess out of your main context.

Where delegation falls apart

The isolation that makes subagents cheap is also their failure mode. A subagent knows only what its prompt says. It has no access to your conversation: the design decision from three turns ago, the constraint mentioned once in passing. Delegate a judgment call that depends on that history and you get back something generic and confidently wrong.

Two more traps I keep seeing. Parallel subagents that write to overlapping files will happily clobber each other — fan out reads, serialize writes. And spawning an agent for a question a single file read would settle is pure overhead: you pay for the handoff, the spin-up, and the latency before any work happens.

My rule after months of running this way: fan out for search, survey, and review; keep edits and decisions in the main thread. If you catch yourself pasting paragraphs of background into a subagent prompt, that's the tell: the task needs shared context, so it belongs upstairs. And once the pattern clicks, it's worth seeing how far it scales. The multi-agent orchestration ideas Claude Code borrows from run a lot deeper than one CLI feature.