Agent Orchestration Protocol

Reusable protocol for dispatching, monitoring, and recovering from subagent failures in Claude Code. Follow this protocol for all subagent dispatch operations.

1. Pre-Flight Checklist

Before dispatching any subagent (Task tool or TeamCreate teammate), verify all items:

Tool Capability Match

Rule: If the task requires ANY write/edit/bash operation, the agent type MUST have that tool. Dispatching an Explore agent for a write task is a guaranteed failure.

File Access

• • All input files exist — verify with Glob before dispatch
• • Output directories exist — create with mkdir -p if needed
• • No path references outside the working directory tree
• • Large files identified — pass specific line ranges, not "read the whole file"

Prompt Self-Containment

• • Task description includes ALL necessary context
• • No references to "above", "earlier", "the conversation" — agents start fresh
• • File paths are absolute, not relative
• • Expected output format stated explicitly
• • Output contract requirement included (see Section 4)

Timeout Budget

Rule: Always set max_turns. Unbounded agents are the primary cause of timeout failures.

2. Retry Policy

Maximum 2 retries per agent (3 total attempts). Each retry escalates prompt specificity.

Attempt Progression

Attempt 1: Original dispatch
    | failure
Attempt 2: Diagnose -> revise prompt
    | failure
Attempt 3: Maximum specificity, simplest agent type
    | failure
ABSORB: Lead agent performs the work inline

Retry Strategy by Failure Type

Retry Rules

1. •Diagnose before retrying. Read the agent's output to understand WHY it failed. Never retry blindly with the same prompt.
2. •Escalate specificity. Each retry should inline more context — file contents, explicit instructions, concrete examples.
3. •Downgrade agent type on permission failures. If a specialized agent lacks tools, retry with general-purpose.
4. •Non-retriable failures skip straight to ABSORB. Don't waste tokens on failures that won't resolve with prompt changes.
5. •ABSORB means the lead does the work. The lead agent has full conversation context and user-granted permissions that subagents lack.

3. Fallback Strategy: Parallel to Sequential

Trigger Condition

failure_rate = (failed agents after retries) / (total dispatched agents)

If failure_rate > 50% -> SWITCH TO SEQUENTIAL MODE

Decision Flow

After collecting all parallel results and applying retry policy:

• •failure_rate > 50%: Keep successful results. Log the failure. Execute remaining tasks sequentially AS LEAD. Do NOT dispatch new agents.
• •failure_rate <= 50%: Keep successful results. Lead absorbs each failed task inline.

Why Lead Executes Sequentially

When >50% of parallel agents fail, the cause is usually systemic — permission model mismatch, wrong path assumptions, or context only the lead has. Re-dispatching agents into the same broken environment wastes tokens.

Logging

When fallback triggers, inform the user:

Parallel dispatch: {success_count}/{total} succeeded.
Switching to sequential execution for remaining {remaining_count} tasks.
Reason: {brief diagnosis of common failure pattern}

4. Output Contract

Every subagent MUST write a structured JSON status file as its last action before returning.

File Location

/tmp/claude-agents/<task-id>.json

Create /tmp/claude-agents/ via mkdir -p before dispatching any agents.

Core principle: Missing status file = implicit failure, triggering the retry policy. The status file is the source of truth — not the agent's prose response.

For the full JSON schema, field definitions, and the prompt template to include in dispatches, consult references/full-protocol.md.

5. Team Swarm Protocol

Extends sections 1-4 for TeamCreate-based multi-agent coordination.

Team Lifecycle

1. TeamCreate          -> create team + shared task list
2. TaskCreate (xN)     -> populate work items with dependencies
3. Task tool (xN)      -> spawn teammates with team_name
4. TaskUpdate          -> assign tasks to teammates
5. Monitor             -> read status files + idle notifications
6. SendMessage         -> coordinate, unblock, reassign
7. shutdown_request    -> graceful teammate shutdown
8. TeamDelete          -> clean up team + task directories

File Conflict Prevention

This is the #1 source of swarm failures:

For detailed team pre-flight checks, teammate dispatch rules, and shutdown sequence, consult references/full-protocol.md.

6. Common Failure Modes

Additional Resources

Reference Files

For detailed schemas, templates, and the complete protocol:

• •references/full-protocol.md — Complete output contract schema, field definitions, and prompt template for including in agent dispatches
• •references/dispatch-template.md — Copy-paste pre-flight checklist and dispatch template for quick use during agent orchestration