Subagents
A specialized worker the main conversation spawns to run a side task in its own fresh context window; only a summary returns. The first form of parallelism — still inside one session.
Analogy — handing an intern a self-contained errand: “go read these 50 log files and tell me the one error that matters.” They do the messy work elsewhere; you get the one-line answer, not the 50 files in your lap.
Mechanism
Markdown files with YAML frontmatter. The main conversation reads each subagent’s description,
delegates, and decides what runs next. The subagent works in an isolated window; only its final summary
returns to the caller. Subagents cannot spawn other subagents (no nesting).
--- name: log-triage description: Use proactively to scan logs and report the single root-cause error. tools: Read, Grep, Bash model: haiku isolation: worktree # optional: own git checkout --- You are a log triage specialist. ...
Built-ins, scopes & resumability
Built-ins: Explore (Haiku, read-only search), Plan (read-only, plan mode),
general-purpose (all tools). Scopes by priority: managed > --agents CLI >
.claude/agents/ (project) > ~/.claude/agents/ (user) > plugin. Manage with /agents.
Foreground = blocking; background = concurrent. A subagent can be resumed and retains its history. Transcripts persist separately from the main conversation, so they survive its compaction.
When to reach for it
When not to
Best practices
description (add “use proactively”) — Claude uses it to decide delegation.tools for focus and safety; check project subagents into version control.isolation: worktree when a subagent edits files in parallel with others.