dispatching-parallel-agents

Dispatch parallel agents

Overview

You delegate tasks to specialized agents with isolated contexts. By writing their instructions and context precisely, you can ensure they stay focused and successfully complete the task. They should never inherit your session context or history—you only construct what they need. This also preserves your own context for coordinating the work.

When you encounter multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can be done in parallel.

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

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"];
}

Applies to:

3+ test files fail due to different root causes
Multiple subsystems are each independently broken
Each problem can be understood without depending on the context of other problems
No shared state between investigations

Does not apply to:

Failures are related to each other (fixing one may fix the others)
Need to understand the full system state
Agents would interfere with each other

Pattern

1. Identify independent domains

Group failures by what is 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 will not affect the abort tests.

2. Create focused agent tasks

Each agent gets:

Specific scope: one test file or subsystem
Clear goal: make these tests pass
Constraints: do not modify other code
Expected output: summarize what you found and fixed

3. Dispatch in parallel

// 在 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")
// 三个任务全部并发运行

4. Review and integrate

After the agents return:

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

Agent prompt structure

A good agent prompt should:

Be focused - one clear problem domain
Be self-contained - include all the context needed to understand the problem
Have clear 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

❌ Too broad: "Fix all the tests" - the agent will lose direction ✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope

❌ No context: "Fix the race condition" - the agent does not know where ✅ Context: Paste the error message and test name

❌ No constraints: The agent may refactor everything ✅ Constraints: "Do NOT change production code" or "Fix tests only"

❌ Vague output: "Fix it" - you do not know what was changed ✅ Specific: "Return summary of root cause and changes"

When not to use

Related failures: Fixing one may fix other failures—investigate them together first Full context needed: Understanding the problem requires looking at the entire system Exploratory debugging: You don't yet know what's broken Shared state: Agents will interfere with each other (editing the same files, using the same resources)

Real example from a session

Scenario: After a large refactor, 6 test failures appear across 3 files

Failures:

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

Decision: Independent domains—abort logic, batch completion, and race conditions are separate from each other

Dispatch:

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

Results:

Agent 1: Replace timeouts with event-based waiting
Agent 2: Fix event structure bug (threadId in the wrong place)
Agent 3: Add waiting until async tool execution completes

Integration: All fixes are independent of each other, no conflicts, full suite passes

Time saved: Solve 3 problems in parallel instead of sequentially

Main benefits

Parallelization - Multiple investigations proceed simultaneously
Focus - Each agent has a narrow scope, with less context to track
Independence - Agents don't interfere with each other
Speed - Solve 3 problems in the time it takes to solve 1

Verification