Claude Code: Agents & Subagents

what a subagent actually is

A subagent is a separate Claude session with its own context window, its own system prompt, and its own (often restricted) set of tools and permissions. It doesn't share your conversation history — it only knows what's in its own prompt — and it returns just a summary to the main conversation, not everything it read along the way. That's the whole point: research that would otherwise flood your main context (log dumps, dozens of speculative file reads) happens in a window that gets thrown away once the summary comes back.

built-in agent types

Type	Model	Tools	For
Explore	inherits from main session (capped at Opus)	read-only	fast codebase search — file/symbol discovery, not analysis
Plan	inherits from main session	read-only	research during plan mode, kept out of the main (still read-only) context
general-purpose	inherits from main session	everything a subagent can access	complex, multi-step tasks needing both research and changes
statusline-setup	Sonnet	restricted	invoked automatically by `/statusline`
claude-code-guide	Haiku	restricted	invoked automatically for questions about Claude Code itself

Explore and Plan deliberately skip loading CLAUDE.md and git status, to keep pure research cheap and fast — every other subagent, built-in or custom, loads both, same as the main session.

writing a custom subagent

A subagent is a markdown file with YAML frontmatter — easiest to have Claude write for you ("create a personal code-improver subagent that scans files for readability issues, read-only, use Sonnet"), but the shape is simple enough to hand-write directly.


---
name: code-improver
description: Scans files and suggests improvements for readability, performance,
  and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Location	Scope
`.claude/agents/`	this project only — commit it so the team shares the same subagent
`~/.claude/agents/`	every project on your machine

when delegating actually helps

Situation	Why delegate
Broad, open-ended search ("where is X handled in this codebase?")	keeps dozens of speculative file reads out of your main context, which stays reserved for the actual work
Independent, parallelizable subtasks	several agents can run at once instead of serially
A long-running background task	you keep working while it runs, instead of blocking on it
A quick, narrow lookup with a known target	don't delegate — a direct file read or targeted search is faster and cheaper than spinning up an agent

writing a prompt an agent can actually use

The single biggest mistake: writing a terse instruction as if the agent shares your context. It doesn't. A good agent prompt includes what you're trying to accomplish and why, what you've already ruled out, and enough background that the agent can make reasonable judgment calls on anything you didn't spell out explicitly — the same "goal, not just the step" habit from Effective Prompting, just more important here since there's no back-and-forth to fill gaps later.

foreground vs background

An agent can run in the foreground (you wait for its result before continuing — use this when the next step depends on its findings) or the background (you keep working, and get notified when it finishes — use this for anything independent of what you're doing right now). Don't fabricate or guess at a background agent's results before it actually reports back.

restricting or disabling subagents

To stop Claude from delegating to any subagent at all, deny the underlying Agent tool itself via permission rules. To remove just a specific built-in type, deny that type by name the same way — useful if a project's work is narrow enough that automatic delegation gets in the way more than it helps.

reference

code.claude.com — subagents

Agents & Subagents