Subagent Delegation
Relevant source files
The following files were used as context for generating this wiki page:
Subagent delegation is a mechanism where a primary agent session spawns specialized, independent agents to perform specific tasks. This architecture ensures that complex operations like codebase exploration, architectural design, and code review are handled by agents with focused contexts or specialized models. The primary agent remains the "lead," coordinating these delegates and reconciling their outputs into a final plan or implementation.
The system enforces boundaries on delegation to maintain predictability and avoid infinite loops. Delegates inherit the parent's environment but operate within defined roles, such as Explore, Plan, or general-purpose.
Sources: CLAUDE.md:214-239, skills/improve-codebase-architecture/INTERFACE-DESIGN.md:16-36
Delegation Architecture and Roles
The Agent tool facilitates the creation of sub-agents. Every delegation must specify a subagent_type and optionally a model. If the model is omitted, delegates inherit the parent session's model via a proxy or gateway.
Core Sub-agent Types
| Subagent Type | Purpose | Behavior |
|---|---|---|
Explore | Codebase search and discovery | Invokes codebase-design and identifies deepening opportunities. |
Plan | Planning-input work | Gathers constraints and explores design alternatives. |
general-purpose | Standard tasks | Used for general assistance or when specialized roles do not fit. |
Sources: CLAUDE.md:214-222, skills/execution-planning/SKILL.md:120-130
Coordination Flow
The project follows a "fan-in" pattern for delegation. Every spawned delegate must return its findings before the lead agent proceed to authoring a final design or plan. The lead agent owns the final design and reconciles inputs from all delegates.
The diagram shows the parallel execution of delegates and the mandatory reconciliation step before the lead agent finalizes work.
Sources: CLAUDE.md:231-236, skills/improve-codebase-architecture/INTERFACE-DESIGN.md:38-46
Specialized Delegation Scenarios
Architectural Interface Design
When exploring refactoring opportunities, the system spawns 3+ parallel sub-agents to generate "radically different" interfaces. Each agent receives a unique design constraint to ensure a broad exploration of the solution space.
- Agent 1: Minimize interface entry points.
- Agent 2: Maximize flexibility and extension support.
- Agent 3: Optimize for the most common caller.
- Agent 4: Design around ports and adapters.
Sources: skills/improve-codebase-architecture/INTERFACE-DESIGN.md:21-36
Independent Code Review
The code-review skill forks a fresh, independent sub-agent. This delegate is pinned to a specific model (claude-fable-5-1) and runs in the lead's checkout but without access to the lead's active workflow ledger. This ensures a "fresh-context" review.
The sequence diagram illustrates the isolation of the review sub-agent and the structured return of findings.
Sources: skills/code-review/SKILL.md:10-58, skills/repo-production-workflow/SKILL.md:144-170
Codex Advisor Consults
The Codex Advisor serves as a high-tier advisor transport. It is treated as a trusted delegate. For phased consults (preflight or final review), it is isolated and evidence-only, meaning it cannot invoke tools or skills and must rely solely on the provided context packet.
Sources: skills/codex-advisor/scripts/ask-codex-advisor.sh:1-40, skills/repo-production-workflow/SKILL.md:58-81
Constraints and Invariants
To maintain system integrity, delegated agents are subject to strict invariants:
- Inheritance: Delegates inherit the
CLAUDE_CODE_SUBAGENT_MODELenvironment variable if set, which force-overrides themodelparameter. - Concurrency Limits: Build, typecheck, or proof commands should not run concurrently with a delegated agent unless explicitly requested by the user.
- Isolation: A sub-agent cannot "self-review" its parent's context-laden work; a fresh agent must be spawned for a true second opinion.
- No Mutation: Review delegates are permitted to read source and run tests but are strictly forbidden from editing candidate source, merging, or mutating the active workflow ledger.
Sources: CLAUDE.md:223-239, skills/code-review/SKILL.md:14-19
Implementation Procedure
Delegation is typically handled via shell scripts or internal tool calls. For example, the ask-codex-advisor.sh script manages the transport to the advisor delegate.
# Example of advisor delegation script parameters
usage() {
printf 'Usage: %s --slug <name> [--phase preflight-advice|final-review] [--cwd path] -- "question"\n' "$0"
}
Sources: skills/codex-advisor/scripts/ask-codex-advisor.sh:6-14
Subagent delegation in this project serves as a strategy to decompose complex engineering tasks into verifiable, specialized sub-tasks, ensuring that the lead agent remains focused on high-level design and coordination.