1---
2name: dispatching-parallel-agents
3description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
4---
5 
6# Dispatching Parallel Agents
7 
8## Overview
9 
10You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
11 
12When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
13 
14**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
15 
16## When to Use
17 
18```dot
19digraph when_to_use {
20    "Multiple failures?" [shape=diamond];
21    "Are they independent?" [shape=diamond];
22    "Single agent investigates all" [shape=box];
23    "One agent per problem domain" [shape=box];
24    "Can they work in parallel?" [shape=diamond];
25    "Sequential agents" [shape=box];
26    "Parallel dispatch" [shape=box];
27 
28    "Multiple failures?" -> "Are they independent?" [label="yes"];
29    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
30    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
31    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
32    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
33}
34```
35 
36**Use when:**
37- 3+ test files failing with different root causes
38- Multiple subsystems broken independently
39- Each problem can be understood without context from others
40- No shared state between investigations
41 
42**Don't use when:**
43- Failures are related (fix one might fix others)
44- Need to understand full system state
45- Agents would interfere with each other
46 
47## The Pattern
48 
49### 1. Identify Independent Domains
50 
51Group failures by what's broken:
52- File A tests: Tool approval flow
53- File B tests: Batch completion behavior
54- File C tests: Abort functionality
55 
56Each domain is independent - fixing tool approval doesn't affect abort tests.
57 
58### 2. Create Focused Agent Tasks
59 
60Each agent gets:
61- **Specific scope:** One test file or subsystem
62- **Clear goal:** Make these tests pass
63- **Constraints:** Don't change other code
64- **Expected output:** Summary of what you found and fixed
65 
66### 3. Dispatch in Parallel
67 
68```typescript
69// In Claude Code / AI environment
70Task("Fix agent-tool-abort.test.ts failures")
71Task("Fix batch-completion-behavior.test.ts failures")
72Task("Fix tool-approval-race-conditions.test.ts failures")
73// All three run concurrently
74```
75 
76### 4. Review and Integrate
77 
78When agents return:
79- Read each summary
80- Verify fixes don't conflict
81- Run full test suite
82- Integrate all changes
83 
84## Agent Prompt Structure
85 
86Good agent prompts are:
871. **Focused** - One clear problem domain
882. **Self-contained** - All context needed to understand the problem
893. **Specific about output** - What should the agent return?
90 
91```markdown
92Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
93 
941. "should abort tool with partial output capture" - expects 'interrupted at' in message
952. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
963. "should properly track pendingToolCount" - expects 3 results but gets 0
97 
98These are timing/race condition issues. Your task:
99 
1001. Read the test file and understand what each test verifies
1012. Identify root cause - timing issues or actual bugs?
1023. Fix by:
103   - Replacing arbitrary timeouts with event-based waiting
104   - Fixing bugs in abort implementation if found
105   - Adjusting test expectations if testing changed behavior
106 
107Do NOT just increase timeouts - find the real issue.
108 
109Return: Summary of what you found and what you fixed.
110```
111 
112## Common Mistakes
113 
114**❌ Too broad:** "Fix all the tests" - agent gets lost
115**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
116 
117**❌ No context:** "Fix the race condition" - agent doesn't know where
118**✅ Context:** Paste the error messages and test names
119 
120**❌ No constraints:** Agent might refactor everything
121**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
122 
123**❌ Vague output:** "Fix it" - you don't know what changed
124**✅ Specific:** "Return summary of root cause and changes"
125 
126## When NOT to Use
127 
128**Related failures:** Fixing one might fix others - investigate together first
129**Need full context:** Understanding requires seeing entire system
130**Exploratory debugging:** You don't know what's broken yet
131**Shared state:** Agents would interfere (editing same files, using same resources)
132 
133## Real Example from Session
134 
135**Scenario:** 6 test failures across 3 files after major refactoring
136 
137**Failures:**
138- agent-tool-abort.test.ts: 3 failures (timing issues)
139- batch-completion-behavior.test.ts: 2 failures (tools not executing)
140- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
141 
142**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
143 
144**Dispatch:**
145```
146Agent 1 → Fix agent-tool-abort.test.ts
147Agent 2 → Fix batch-completion-behavior.test.ts
148Agent 3 → Fix tool-approval-race-conditions.test.ts
149```
150 
151**Results:**
152- Agent 1: Replaced timeouts with event-based waiting
153- Agent 2: Fixed event structure bug (threadId in wrong place)
154- Agent 3: Added wait for async tool execution to complete
155 
156**Integration:** All fixes independent, no conflicts, full suite green
157 
158**Time saved:** 3 problems solved in parallel vs sequentially
159 
160## Key Benefits
161 
1621. **Parallelization** - Multiple investigations happen simultaneously
1632. **Focus** - Each agent has narrow scope, less context to track
1643. **Independence** - Agents don't interfere with each other
1654. **Speed** - 3 problems solved in time of 1
166 
167## Verification
168 
169After agents return:
1701. **Review each summary** - Understand what changed
1712. **Check for conflicts** - Did agents edit same code?
1723. **Run full suite** - Verify all fixes work together
1734. **Spot check** - Agents can make systematic errors
174 
175## Real-World Impact
176 
177From debugging session (2025-10-03):
178- 6 failures across 3 files
179- 3 agents dispatched in parallel
180- All investigations completed concurrently
181- All fixes integrated successfully
182- Zero conflicts between agent changes
183