Task Agents and Delegation

Your main Claude Code session has one context window. Every tool call, every file read, every conversation turn eats into it. Ask Claude Code to investigate a sprawling auth system and that exploration floods your context with details you only needed for five minutes. They sit there, dead weight, for the rest of the session.

Subagents fix this. They run tasks in their own isolated context and return just the summary you care about.

What Subagents Are

A subagent is a separate Claude Code instance spawned to handle a specific task. Own context window. Own system prompt. Own tool access. It does its work, produces a result, sends it back. The intermediate dead ends never touch your window.

It's like sending a colleague to research something. They come back with a summary, not a recording of every Google search they ran.

You can configure each subagent with a custom system prompt, a specific set of tools (or explicit restrictions), an independent permission mode, and a model override. That last one matters more than you'd think. Running a quick investigation on Haiku costs almost nothing compared to burning Opus tokens on something that just needs to read a few files.

Built-In Agent Types

Claude Code ships with three built-in types.

Explore runs on Haiku with read-only access. Searches your codebase, reads files, traces call chains, can't edit anything. Your go-to for quick investigations.

Plan inherits your current model, also read-only, but built for deeper research. Reach for this when you need Claude Code to think through an approach before you commit to building anything.

General-purpose inherits your model with access to all tools. It can read, write, run commands, everything your main session can do. Just in its own context.

Creating Custom Agents

The built-in agents cover common cases, but custom agents are where it gets fun. You define them as markdown files with YAML frontmatter, stored in .claude/agents/ for project-specific agents or ~/.claude/agents/ for global ones.

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities
model: inherit
tools:
  - Read
  - Glob
  - Grep
disallowedTools:
  - Bash
  - Edit
  - Write
maxTurns: 15
---
 
You are a security-focused code reviewer. Analyze the provided code
for common vulnerabilities: injection attacks, auth bypasses, data
leaks, and insecure defaults. Report findings with severity levels
and specific file locations.

The frontmatter gives you tight control. tools specifies which tools the agent can use. disallowedTools blocks specific ones. model can be sonnet, opus, haiku, or inherit. maxTurns caps conversation turns before the agent must return a result. permissionMode sets the permission tier. And isolation with the worktree option gives the agent its own git worktree so it can make changes without touching your working tree.

Manage your agents with the /agents command inside any Claude Code session.

When to Delegate vs. Just Do It

Not every task needs a subagent. There's real overhead: context setup, clear scoping, and you only get a summary back. For quick edits or straightforward questions, just handle it yourself.

Delegation pays off when tasks are self-contained, generate a lot of intermediate noise, or benefit from running in parallel. Code reviews are the perfect example. The agent reads through dozens of files, reasons about edge cases, and you get a clean report. All that intermediate exploration would've eaten your context for nothing.

Keep things in your main thread when the work is iterative and needs your feedback at each step, when it'd take longer to scope the task than to just do it, or when you need to see the full reasoning chain to trust the output.

Foreground vs. Background Execution

Subagents run in foreground by default. Your session blocks until the result comes back. Simple, and fine when you need the output before moving on.

Background subagents run concurrently. Press Ctrl+B to send a running task to the background, or launch one there from the start. You keep working. When the agent finishes, the result drops into your session. You can kick off a security review, a test suite analysis, and a dependency audit all at once, then collect results as they come in.

Scoping Tasks Effectively

The most common mistake with subagents is vague instructions. "Look at the codebase and find problems" is a guaranteed way to burn turns and get rambling nonsense back.

Compare that with: "Use a subagent to investigate how our authentication system handles token refresh. Check the auth middleware, the token service, and any refresh endpoints. Report which files are involved and whether expired tokens are handled gracefully."

Clear objective. Specific places to look. Defined output format. Tighter scope, better results. Every single time.

Try It: Delegate a Code Review

Pick a file in your project that has some complexity to it. Then ask Claude Code to delegate a review:

# In your Claude Code session, try:
"Use a subagent to review lib/auth.ts for edge cases, error handling gaps, and potential race conditions. Report findings with line numbers."

Watch what happens. Claude Code spawns the subagent, which reads through the file (and possibly related files), reasons about edge cases in its own context, and hands you a focused summary. Your main context stays clean.

Now try creating a custom agent:

mkdir -p .claude/agents

Then add a file called code-reviewer.md:

---
name: code-reviewer
description: Reviews code for bugs, edge cases, and improvements
model: haiku
tools:
  - Read
  - Glob
  - Grep
maxTurns: 10
---
 
Review the specified code thoroughly. Focus on bugs, unhandled edge
cases, error handling gaps, and potential improvements. Be specific
with file paths and line numbers. Keep your report concise.

Now in your Claude Code session, run /agents to see your new agent listed. Ask Claude Code to use it on any file, and notice how running it on Haiku keeps costs low for a task that's read-heavy and doesn't need the most powerful model.

One Limitation Worth Knowing

Subagents can't spawn other subagents. The delegation tree is exactly one level deep. Your main session can spawn as many as you want, sequentially or in parallel, but those subagents can't further delegate. This prevents runaway chains of agents spawning agents, which honestly is a relief.

Recap

• Subagents get their own context windows, keeping your main session clean
• Three built-in types: Explore (Haiku, read-only), Plan (deep research), general-purpose (full tools)
• Custom agents live in .claude/agents/ as markdown with YAML frontmatter
• Delegate noisy, self-contained tasks; keep interactive work in your main thread
• Tight scoping is everything