Dispatch Parallel Agents

Overview

When to Use

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

• 3 or more test files failing due to different root causes
• Multiple subsystems broken independently
• Each problem can be understood without context from other problems
• No shared state between investigations

• Failures are related (fixing one may fix others)
• Full system state understanding is required
• Agents will interfere with each other

Patterns

1. Identify Independent Domains

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

2. Create Targeted Agent Tasks

• Specific Scope: One test file or subsystem
• Clear Goal: Pass these tests
• Constraints: Do not change other code
• Expected Output: A summary of what you found and fixed

3. Parallel Dispatch

// 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

• Read each summary
• Verify fixes do not conflict
• Run the full test suite
• Integrate all changes

Agent Prompt Structure

1. Focused - One clear problem domain
2. Self-Contained - All context needed to understand the problem
3. Specific 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.

Common Mistakes

When Not to Use

Real-World Session Example

• agent-tool-abort.test.ts: 3 failures (timing issues)
• batch-completion-behavior.test.ts: 2 failures (tools not executing)
• tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

• Agent 1: Replaced timeouts with event-based waiting
• Agent 2: Fixed event structure bug (threadId in wrong place)
• Agent 3: Added waiting for async tool execution completion

Key Benefits

1. Parallelization - Multiple investigations happen simultaneously
2. Focus - Each agent has a narrow scope with less context to track
3. Independence - Agents don't interfere with each other
4. Speed - Solve 3 problems in the time of 1

Validation

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

Real-World Impact

• 6 failures across 3 files
• 3 agents dispatched in parallel
• All investigations completed simultaneously
• All fixes successfully integrated
• Zero conflicts between agent changes