Async Agent Dispatch

Async Agent Dispatch

I. Philosophy

The user's attention is the scarcest resource. Long tasks that block interaction waste it. Background dispatch turns sequential bottlenecks into parallel throughput -- but only if the handoff is clean enough that results integrate without re-explanation.

The key insight is the control plane / data plane separation: the foreground agent manages intent and coordination (control plane), while background agents execute work and produce artifacts (data plane). A clean boundary between them means neither blocks the other.

This is not about making things faster. It is about making long work invisible to the user until results are ready.

II. When to Use

• Task will take more than 2 minutes (large codebase scans, multi-file generation, test suites)
• User needs to continue interacting while work proceeds
• Multiple independent tasks can run in parallel
• Task produces file artifacts that can be read after completion
• Work is well-defined enough to run without mid-task clarification

Do NOT use when:

• Task requires iterative user feedback during execution
• Task is under 2 minutes (overhead of dispatch exceeds benefit)
• Task modifies shared state that the foreground agent also reads
• Results need real-time streaming to the user (use foreground with progress updates)
• Task definition is ambiguous and likely to need clarification

III. Workflow

Step 1: Classify Task Duration

Before dispatching, estimate whether background execution is warranted:

Heuristics for estimation:

• File count * 0.5s per file for read-heavy tasks
• Test count * 2s per test for test suites
• API calls * latency per call for network-bound work

Step 2: Choose Dispatch Mode

Option A: Bash with run_in_background=true Best for: shell commands, build processes, test suites, scripts. The command runs in background and you receive a notification when complete.

Option B: Agent tool (sub-agent) Best for: complex multi-step tasks requiring tool access and judgment. Structure the agent prompt with explicit scope, constraints, and output location.

Option C: Parallel dispatch (multiple background tasks) Best for: independent workstreams that don't share state. Dispatch 2-4 tasks simultaneously. Track each by its output location.

Step 3: Structure the Handoff

Every background dispatch must include these elements:

TASK DESCRIPTION:
  What: [Specific deliverable in 1-2 sentences]
  Scope: [Explicit boundaries -- what IS and IS NOT included]

OUTPUT CONTRACT:
  Location: [Exact file path where results will be written]
  Format: [Expected structure -- JSON, markdown, code files]

SUCCESS CRITERIA:
  - [Measurable criterion 1]
  - [Measurable criterion 2]

TIMEOUT:
  Maximum: [Duration in minutes]

CONSTRAINTS:
  - Do not modify files outside [scope]
  - Do not require user interaction
  - Write all output to [location] before exiting

Critical rule: the output location must be agreed before dispatch. If you don't know where to look for results, the background work is wasted.

Step 4: Monitor Without Polling

After dispatch, do NOT poll in a sleep loop. Instead:

• For Bash run_in_background: you will receive an automatic notification when the command completes. Continue other work in the foreground.
• For Agent sub-tasks: the agent will complete and results will be at the agreed output location. Check only when notified or when the user asks.
• For parallel dispatches: track each task's output path. Check them in order of expected completion time.

Tell the user what was dispatched and when to expect results: "I've dispatched [task] to run in the background. Expected completion: ~[N] minutes. I'll check results when it finishes. In the meantime, what else can I help with?"

Step 5: Collect and Integrate Results

When the background task completes:

1. Read the output at the agreed location
2. Validate against success criteria -- did it produce what was expected?
3. Check for errors -- scan for error markers, incomplete output, or missing files
4. Integrate into main workflow -- summarize results for the user, apply outputs
5. Clean up -- remove temporary files if the task used scratch space

If results are invalid or incomplete:

• Report what succeeded and what failed
• Decide whether to retry (same parameters) or escalate (ask user)
• Never silently swallow a failed background task

IV. Best Practices

1. Write output contracts, not task novels. The background agent needs to know WHERE to put results and WHAT format, not a 500-word backstory.
2. One task, one output location. Never have two background tasks writing to the same file. Use separate output paths and merge in the foreground.
3. Set realistic timeouts. A task that "might take 5 minutes" should have a 10-minute timeout. A task with no timeout can hang forever.
4. Prefer file artifacts over stdout. Background stdout can be lost or truncated. Write results to a file that persists.
5. Keep the foreground agent useful. The whole point is freeing the user's attention. If you dispatch background work and then sit idle waiting, you've gained nothing.

V. Quality Checklist

• Task duration estimated and classified (foreground vs background)
• Dispatch mode selected (Bash background, Agent sub-task, or parallel)
• Handoff includes: task description, output location, format, success criteria, timeout
• Output location is a specific file path, not "somewhere"
• User is informed of what was dispatched and expected completion time
• No polling loops -- using notification-based monitoring
• Results validated against success criteria after completion
• Errors surfaced to user, not silently swallowed
• Temporary files cleaned up

VI. Common Pitfalls

• Dispatching tasks that need clarification. If the task definition is fuzzy, the background agent will either guess wrong or stall. Get clarity BEFORE dispatch.
• Polling in a sleep loop. while true; do sleep 5; check; done wastes cycles and context. Use run_in_background and wait for notification.
• Shared state conflicts. Two agents writing to the same file or modifying the same codebase region will corrupt each other's work. Partition clearly.
• Forgetting to check results. Dispatching is only half the job. If you never read the output, the background work was pointless.
• Over-parallelizing. 2-4 parallel tracks are manageable. 8+ create coordination overhead that exceeds the parallelism benefit. The Solo Operator Focus Theorem applies.
• No timeout. A background task without a timeout is a resource leak. Always set one.

VII. Example

Scenario: User asks to run a full test suite (estimated 5 minutes) while continuing to work on a new feature.

Step 1: Classify -- 5 minutes, clearly background territory.

Step 2: Dispatch mode -- Bash with run_in_background=true (it's a shell command).

Step 3: Handoff:

# Dispatch: run test suite in background
cd /project && npm test > /tmp/test-results-2026-04-06.log 2>&1
# run_in_background=true, timeout=600000

Output contract: /tmp/test-results-2026-04-06.log, plain text test output.

Step 4: Tell user: "Test suite dispatched to background. Expected ~5 minutes. I'll report results when it finishes. What would you like to work on?"

Step 5: On completion notification, read log, report: "Tests complete: 408 passed, 2 failed. Failures in auth.test.ts lines 45 and 82 -- both related to the token refresh change from yesterday."

VIII. Related Skills

• parallel-tracks -- Splits large tasks into independent tracks (complements dispatch)
• handoff-protocol -- Structures context transfer between agents
• granular-visibility -- Progress tracking patterns for long-running work
• background-agent-parallelism seed -- Long ops as background, short as foreground
• async-sandbox-dispatch seed -- Control plane / data plane separation pattern

Output

• Dispatch mode decision (Bash background, Agent sub-task, or parallel tracks) with rationale
• Completed handoff block: task description, output contract (exact file path + format), success criteria, timeout
• User-facing status message confirming what was dispatched and expected completion time
• Result validation report after background task completes: success/failure against criteria, errors surfaced, temporary files cleaned up

Examples

Scenario 1: "Run the full test suite while we keep working on the auth feature." → Task classified as 5-minute background (Bash mode); dispatched with run_in_background=true, output to /tmp/test-results-2026-04-08.log, timeout 600s; user informed; on completion, results read and failures reported with file and line numbers.

Scenario 2: "Normalize all 47 community skills while I plan the next phase." → Task classified as 10+ minutes (Agent sub-task mode); split into 3 parallel agents (groups of ~16 skills each) each writing to a separate output path; main thread plans Phase 4; results merged and validated after all 3 complete.

Edge Cases

• Task definition is ambiguous at dispatch time: do not dispatch; get clarity first — a background agent that guesses wrong produces unusable output and cannot ask mid-task
• Background task completes but output file is missing or empty: do not silently accept; report the failure, check the exit code, and decide whether to retry with the same parameters or escalate
• User asks to check background task status before notification arrives: do not poll in a sleep loop; tell the user the task is still running and you will report when notified

Anti-Patterns

• Dispatching a task under 30 seconds to background — dispatch overhead exceeds the task duration; just run it inline
• Not specifying an exact output file path before dispatch — "output it somewhere" means the foreground agent cannot find results
• Running a polling loop (while true; do sleep 5; check; done) instead of waiting for run_in_background notification — wastes context and cycles
• Dispatching more than 4 parallel agents at once — coordination overhead exceeds parallelism benefit past that threshold
• Silently swallowing a failed background task — always surface errors to the user with what succeeded and what failed