Agents: Mental Model

A subagent is a separate Claude instance with its own context window, spawned by the parent conversation via the Agent tool. The parent pauses (foreground) or continues (background) while the subagent runs autonomously. When finished, only the subagent's final message returns to the parent. Everything else — intermediate tool calls, file reads, reasoning — is discarded.

The Lifecycle

Three phases define every subagent invocation:

1. Spawn — Claude calls the Agent tool with a prompt string and optional configuration (agent type, model, background flag). The subagent receives only this prompt plus its own system prompt and basic environment info (working directory, OS). Parent conversation history does not transfer.
2. Execute — The subagent runs autonomously: reading files, searching code, running commands, making edits. All intermediate work stays inside the subagent's context window. Auto-compaction triggers at ~95% capacity by default.
3. Return — The subagent's final message returns verbatim to the parent as the Agent tool result. The parent may summarize this in its response. All intermediate context is gone.

What the Agent tool call looks like internally:

// Foreground — parent blocks until the subagent returns
Agent({
  prompt: "Analyze src/auth/ for JWT expiration vulnerabilities...",
  agent: "Explore"      // Optional. Uses built-in Explore agent.
})
 
// Background — parent continues working
Agent({
  prompt: "Run the full test suite and report failures...",
  background: true
})
 
// Custom agent — references a YAML definition from .claude/agents/
Agent({
  prompt: "Implement the new /api/users endpoint...",
  agent: "api-developer" // Matches .claude/agents/api-developer.md
})

The prompt string is the only channel from parent to subagent. File paths, error messages, architectural decisions, constraints — everything the subagent needs must be in that string.

Context Isolation: What Crosses the Boundary

CLAUDE.md is the notable exception — it loads additively through the normal message flow even when the agent's system prompt replaces the default. This means project conventions reach subagents automatically.

The 5 Built-in Agent Types

The Explore agent is the workhorse for context gathering. Haiku keeps costs low — a full codebase scan on Explore costs a fraction of the same work on Opus. Use it aggressively for file discovery before committing to an implementation agent.

Permission Inheritance

Subagents inherit the parent conversation's permission context, with layered overrides:

• bypassPermissions in parent — Takes precedence unconditionally. Cannot be overridden by subagent frontmatter.
• auto mode in parent — Subagent inherits auto mode. Its own permissionMode frontmatter is ignored.
• Background subagents — Permissions are pre-approved before launch. Anything not pre-approved is auto-denied at runtime. No interactive prompts.

Known issue: user-level permissions from ~/.claude/settings.json under permissions.allow may not be inherited by subagents (GitHub #18950). If a subagent fails on a permission you've already granted globally, this is likely the cause.

Tool Inheritance

By default, subagents inherit all tools from the main conversation, including MCP tools. Two frontmatter fields control this:

# Allowlist: only these tools are available
tools: Read, Grep, Glob, Bash
 
# Denylist: remove these from the inherited set
disallowedTools: Write, Edit

When both are set, disallowedTools applies first, then tools resolves against the remaining pool.

The Agent(worker, researcher) syntax in tools controls which subagents a --agent session can spawn — it has no effect on subagents spawned by the parent conversation.

Worktree Isolation

Setting isolation: worktree creates a temporary git worktree at .claude/worktrees/[name]/ with its own branch. The subagent gets a completely isolated copy of the repository.

---
name: experimental-refactor
description: Attempts risky refactoring in an isolated worktree
isolation: worktree
tools: Read, Edit, Write, Bash, Grep, Glob
---

Cleanup rules:

• No changes made — Worktree and branch auto-removed when session ends
• Changes exist — Claude prompts you to keep or remove
• Orphaned worktrees (from crashes) — Cleaned at startup if older than cleanupPeriodDays (default: 30), with no uncommitted changes, no untracked files, and no unpushed commits
• Non-git VCS — Configure WorktreeCreate and WorktreeRemove hooks for SVN, Perforce, or Mercurial

The CLI also supports claude --worktree <name> (or -w <name>) to start an entire session in an isolated worktree — useful for parallel feature development without subagents.

# Start a full Claude Code session in a worktree
claude --worktree feature-auth-refactor
 
# Short form
claude -w feature-auth-refactor
 
# The worktree is created at .claude/worktrees/feature-auth-refactor/
# with its own branch: claude/worktree/feature-auth-refactor
 
# List active worktrees
git worktree list
 
# Clean up after merging
git worktree remove .claude/worktrees/feature-auth-refactor
git branch -d claude/worktree/feature-auth-refactor

Resource Model

Each subagent consumes tokens independently. The cost equation is straightforward:

There is no per-agent cost breakdown or trace view. This is a known observability gap — you cannot currently see how many tokens each subagent consumed.

Subagent Scopes: Where Definitions Live

Higher-priority scopes override lower ones when names collide. Project-level (.claude/agents/) is the most common placement for team-shared agent definitions.

A typical project agent directory:

.claude/agents/
├── code-reviewer.md          # Read-only review with checklist output
├── api-developer.md          # Implements endpoints following team conventions
├── test-writer.md            # Generates tests for modified code
└── explorer.md               # Deep codebase analysis (Haiku, read-only)

Load agents from a custom path for a single session:

claude --agents ./my-agents/

The No-Nesting Rule

Subagents cannot spawn other subagents. This is an architectural constraint preventing infinite recursion and runaway costs. The workarounds:

• Chain subagents from the main conversation — pass results from subagent A to subagent B
• Use skills for multi-step orchestration within the main conversation
• Use agent teams when you need true peer-to-peer coordination with file locking

This constraint shapes how you design delegation. Deep task hierarchies must flatten into sequential or parallel dispatch from a single parent.