dispatching-parallel-agents

name	dispatching-parallel-agents
description	Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies

Dispatching Parallel Agents

Core principle: dispatch one agent per independent problem domain. Let them work concurrently.

⚠️ Cost awareness: Parallel agents consume significantly more tokens than sequential approaches (often 10-15× more). Each agent loads its own full context. Use parallel dispatch only when the speed gain justifies the cost.

When to Use

• 3+ test files failing with different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from others
• No shared state between investigations

Prefer Sequential When

• Failures may be related (fixing one might fix others)
• Full system context is needed
• Agents would edit the same files

The Pattern

1. Identify Independent Domains

Group failures by what's broken:

• File A tests: Tool approval flow
• File B tests: Batch completion behavior
• File C tests: Abort functionality

Each domain is independent - fixing tool approval doesn't affect abort tests.

2. Create Focused Agent Tasks

Each agent gets:

• Specific scope: One test file or subsystem
• Clear goal: Make these tests pass
• Constraints: Don't change other code
• Expected output: Summary of what you found and fixed

3. Dispatch in Parallel

// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

4. Review and Integrate

When agents return:

• Read each summary
• Verify fixes don't conflict
• Run full test suite
• Integrate all changes

Agent Prompt Structure

Good agent prompts are:

1. Focused - One clear problem domain
2. Self-contained - All context needed to understand the problem
3. Specific about output - What should the agent return?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

Prompt Quality Checklist

Quality	Bad	Good
Scope	"Fix all the tests"	"Fix agent-tool-abort.test.ts"
Context	"Fix the race condition"	Paste error messages and test names
Constraints	(none — agent refactors everything)	"Fix tests only, no production code changes"
Output	"Fix it"	"Return summary of root cause and changes"

Verification

After agents return:

1. Review each summary — understand what changed
2. Check for conflicts — did agents edit the same code?
3. Run full suite — verify all fixes work together
4. Spot-check — agents can make systematic errors

Advanced Patterns (2026)

Fan-Out / Fan-In (Scatter-Gather)

Dispatch N agents for the same question with different strategies, then merge results:

Agent A: "Search codebase for usages of deprecated API"
Agent B: "Search git history for when API was introduced"
Agent C: "Search docs for migration guide"
→ Merge: synthesize findings into migration plan

DAG-Based Orchestration

For tasks with partial dependencies, model as a directed acyclic graph:

Agent A (research) ──→ Agent C (implement)
Agent B (design)   ──→ Agent C (implement)
                       Agent C ──→ Agent D (verify)

Inter-Agent Communication

• MCP (Model Context Protocol): Standard protocol for tool and resource access across agents
• A2A (Agent-to-Agent): Emerging protocol for cross-platform agent messaging
• Shared filesystem: Simplest approach — agents write results to agreed-upon paths

Stop Conditions

Always define stop conditions for parallel dispatches:

• Max runtime: Kill agents that exceed time budget
• Budget cap: Halt when cumulative token spend exceeds threshold
• Conflict detection: Stop if two agents modify the same file
• Quality gate: Verify each agent's output before accepting