/agent — Spawn subagents

What it does

The Agent tool spawns independent subagents to handle tasks in parallel. Each subagent is a fresh Claude instance with full tool access—it can read files, grep the codebase, explore architecture, design implementations, or run any other task you'd normally do yourself. Subagents run concurrently, so you can fan out ten independent searches or designs without waiting for them to finish sequentially.

When to use it

Use subagents for parallel work on independent problems. Common patterns:

• Exploration: "Find where auth is handled" + "Find where payments are handled" → run both at once instead of serial searches
• Code review dimensions: Split review across bug-hunt, performance, and security agents—each works independently and reports findings
• Multi-angle research: Different agents search by filename, by keyword, by entity type—blind to what others find, so you get broader coverage
• Architecture planning: Hand an Explore agent a quick "find all API routes" while a Plan agent designs the implementation

Explore agent is fastest for locating code—it's read-only and specialized for grep + file scans. Plan agent is for design decisions. General-purpose agent handles anything else.

Don't use subagents for sequential work where B depends on A's output—that's waterfall, not parallelism. Use them when you have N independent tasks and want them all done at once.

Try it yourself

Open the terminal and spawn two parallel subagents: one to explore your project structure, another to list recent commits. Use the Agent tool twice in a single tool-call block—they'll run concurrently. See how long it takes versus running them back-to-back yourself.

Gotchas

Context isolation cuts both ways. Each subagent starts fresh—no memory of prior conversation context or findings from other agents. If agent A finds something critical, you must summarize it in the prompt to agent B, not assume they'll know. This is a feature for independence but requires you to weave context together.

Parallel calls have overhead. Spawning ten agents takes ~200–500ms per agent just to initialize. For quick one-shot tasks (grep a filename), serial is faster. Parallelism wins when each agent's work takes 10+ seconds—the overhead is amortized.

Worktree isolation is expensive. If you pass isolation: 'worktree', each agent gets its own git checkout to avoid file conflicts. This buys safety but adds disk overhead and setup time. Only use it when agents are mutating files in parallel and would step on each other.

Subagents don't inherit your session model override. If you're in /fast mode and spawn a subagent without specifying model, it uses the default (Haiku), not Opus. Explicitly set model: 'opus' if you need it.

Result filtering is your job. Parallel agents might error or return null. Check for .filter(Boolean) before using results—don't assume all calls succeeded.