Claude CodeAgents & Subagents

Agents & Subagents

AgentTool

Claude Code can spawn isolated sub-agents with separate token budgets, custom prompts, and optional isolation (worktree or remote). The Agent system enables multi-agent coordination and parallel work.

Agent Input Schema

// AgentTool.tsx input schema
{
  description: string          // 3-5 word task summary
  prompt: string              // Full task instructions
  subagent_type?: string      // Specialized agent selector
  model?: 'sonnet' | 'opus' | 'haiku'
  run_in_background?: boolean
  name?: string               // For multi-agent coordination
  team_name?: string          // Team context
  mode?: PermissionMode       // Override permission level
  isolation?: 'worktree' | 'remote'
  cwd?: string               // Working directory override
}

Execution Modes

Local (in-process)

Runs in LocalAgentTask
Shares parent AppState
Read/write parent filesystem
Token budget tracked separately

Worktree Isolation

Creates git worktree
Isolated git workspace
Temporary branch
Prevents code conflicts

Remote (CCR)

Runs on remote servers
Full isolation from local
Always runs in background
Requires isolation: 'remote'

Zero-Cost Cache Sharing

The most important performance optimization. When spawning subagents, CacheSafeParams are frozen at fork time. If the system prompt bytes are identical, the API returns a prompt cache hit — making forked queries essentially free.

// CacheSafeParams — frozen at fork time
{
  systemPrompt: bytes      // Must match exactly
  userContext: variables    // Working dir, platform, git
  systemContext: resources  // Available tools, MCP
  toolSchema: definitions  // All tool definitions
  thinkingConfig: config   // Thinking mode settings
}

// Result: identical bytes = automatic prompt cache hit
// This enables cheap subagent spawning for:
//   - Post-turn forks (promptSuggestion, summary)
//   - Compact agents (conversation summary)
//   - Skill execution (forked command context)
//   - Speculation (fast hypothetical execution)

Coordinator Mode

Multi-worker orchestration via a central coordinator agent. Workers report results as <task-notification> XML.

// Coordinator workflow:
1. Coordinator receives user task
2. Spawns workers via AgentTool
3. Workers execute independently
4. Results delivered as <task-notification> XML:
   - task-id, status, summary, result, usage
5. Coordinator synthesizes findings
6. Directs next task or reports to user

// Coordinator system prompt covers (~370 lines):
- Phases: research → synthesis → implementation → verification
- Parallelism strategy (when to fork)
- Prompt writing best practices
- Continuation vs. spawn decisions
- Failure handling

Built-in Agent Types

Type	Purpose	Key Capability
`general-purpose`	Default agent for complex tasks	Full tool access
`Explore`	Fast codebase exploration	Search-focused, no write tools
`Plan`	Architecture planning	Design docs, no code changes
`code-review`	PR code review	Read-only analysis
`simplicity-engineer`	Over-engineering review	Complexity analysis
`Custom (.claude/agents/)`	User-defined agents	YAML/MD with frontmatter

Forked Agents (Lightweight)

Lightweight background queries that share the parent's cache. Used for tasks you never see:

extractMemoriesAuto-memory after each query

sessionMemoryPeriodic conversation notes

promptSuggestionNext prompt suggestions

compactionConversation summary

autoDreamBackground memory consolidation

speculationFast hypothetical execution

Coordinator's Golden Rule

"When workers report research findings, you must understand them before directing follow-up work. Read the findings. Identify the approach. Then write a prompt that proves you understood by including specific file paths, line numbers, and exactly what to change."

— coordinator system prompt, line ~180

The coordinator can't just throw tasks at workers blindly — the system prompt explicitly requires it to prove comprehension before delegating. Even AI managers have to actually read the reports.