Subagent Best Practices
Auto-inject when: User mentions "subagent", "Task tool", "spawn agent", "parallel"
⛔ HARD STOP: No Claude Subagents
NEVER use Claude models (Haiku, Sonnet, Opus) as subagents.
| ❌ FORBIDDEN | ✅ ALLOWED |
|---|---|
model="haiku" | model omitted (default) |
model="sonnet" | general-purpose agent |
model="opus" | MiniMax, GLM, Kimi K2.5 |
Preferred subagents: Kimi K2.5 (complex), GLM (creative), MiniMax (fast)
Enforced: .claude/settings.local.json deny rules
Two-Tier Model
| Tier | Role | Does | Doesn't |
|---|---|---|---|
| Claude | Orchestrator | Reason, decide, write code | Explore, bulk read |
| Subagent | Worker | Explore, research, batch ops | Make final decisions |
See .claude/roles/ROLES.md for full details.
Provider Selection
| Task | Provider |
|---|---|
| Complex reasoning | Kimi K2.5 |
| Vision (batch) | Kimi K2.5 |
| Creative | GLM-4.7 |
| Fast/simple | MiniMax |
See /skill delegation for full matrix.
Subagent Prompt Template
code
You are tasked with:
{Specific subtask description}
Search scope: {directories/files}
Output format: {table/list/JSON}
Return ONLY the requested output, nothing else.
Parallel Execution
Launch independent tasks in single message:
code
Task(prompt="Research X") ←─┐ Task(prompt="Research Y") ←─┼─ Same message = parallel Task(prompt="Research Z") ←─┘
Don't chain sequentially when parallel is possible.
Background Execution (Token Suspension)
For tasks >30 seconds: Use run_in_background=true + end turn.
| Execution Mode | Token Cost | UX |
|---|---|---|
| Blocking | High (Claude waits) | Seamless |
| Background + continue | Medium | Seamless |
| Background + end turn | Low | Requires re-prompt |
Fire-and-Retrieve Pattern
code
1. Task(prompt="...", run_in_background=true) → gets task_id 2. Claude ends turn: "Dispatched. Say 'continue' for results." 3. User prompts → TaskOutput(task_id="...", block=true) 4. Claude synthesizes
Why it saves tokens: Ending Claude's turn stops the token meter. Subagent tokens are 50x cheaper than Claude tokens.
Quick Checklist
Before spawning:
- • Can I decompose into independent chunks?
- • Clear deliverables defined?
- • Right provider for task type?
When spawning:
- • Specific prompt with scope
- • Single message for parallel tasks
- • No Claude models
After results:
- • Aggregate without re-running
- • Claude makes final decision
[Opus 4.5 - 2026-01-29]