Agent handoff protocol

Canonical reference for agents that open human_tasks via the dispatcher. Each agent prompt references this doc for the mechanics and keeps only its agent-specific "When to hand off" criteria inline.

Protocol

When you cannot decide from context alone, open a structured human_task and end the turn. The orchestra TUI renders the question as a native picker; the human answers there. The dispatcher then resumes your session with the answer as the next user turn.

1. Build the AskUserQuestion payload

The shape supports 1–4 questions per handoff, each with options that have a short label (1–5 words) and a description. Set multiSelect: true if the human can pick more than one option:

{
  "questions": [
    {
      "question": "Which approach should I take for this change?",
      "header": "Approach",
      "multiSelect": false,
      "options": [
        {"label": "Option A", "description": "Description of A."},
        {"label": "Option B", "description": "Description of B."}
      ]
    }
  ]
}

2. Open the human_task

Pipe the JSON payload on stdin. Replace <agent-name>, <task-id>, and <short-summary> with your actual values:

HT_ID=$(/opt/orchestra/.claude/hooks/human_task_open.sh <agent-name> "$ORCHESTRA_TASK_ID" "<short summary headline>" <<'EOF'
{"questions": [ ... ]}
EOF
)

3. End the turn

End with a short note: "Handed off to a human as $HT_ID. Will resume on resolution."

4. Resume after answer

When you are resumed, your next user message will start with [dispatcher] Human answered human_task <id>: and include each question's answer. Continue toward the original task using those decisions. The dispatcher's resume message is the source of truth — process the answer directly rather than independently re-querying the DB.

Handoff triggers (agent-specific criteria)

Each agent decides when to hand off based on its role. The shared principle across all agents: the agent surfaces ambiguity; the human decides. Agents do not guess, assume, or fill in gaps.

Builder

Principle: The builder does zero thinking — only execution.

Hand off for ANY of these:

• The proposal's implementation_plan is ambiguous or incomplete
• Multiple valid approaches exist and the proposal doesn't specify one
• The change has side effects the proposal didn't anticipate
• The change touches auth, secrets, or security-sensitive paths
• A library, tool, or external dependency choice is needed
• The builder encounters an error it can't resolve after 2 attempts

Proceed without handoff ONLY when:

• The proposal's implementation_plan lists exact files and changes
• The change follows an existing pattern in the codebase
• The implementation is purely mechanical with zero design choices

Developer

Principle: The developer agent does zero thinking — only execution.

Hand off for ANY of these:

Scope & requirements:

• The issue lacks concrete acceptance criteria or is a single sentence
• Multiple valid interpretations of what to build exist
• It's unclear which files, tables, endpoints, or components to touch
• The desired behaviour isn't fully specified

Approach & design:

• Choice between algorithms, data structures, or architectural patterns
• Where to place new code (which module, file, layer)
• Whether to refactor existing code vs. add alongside it
• API contract design (endpoint shape, parameter names, response format)

Risk & impact:

• Data migrations, schema changes, or anything touching the database
• Auth, permissions, or security-related changes
• Changes that could affect other features or teams
• Deleting or modifying code that might be in use
• Performance-sensitive paths

External decisions:

• Library, vendor, or tool choices
• Configuration values, secrets, environment variables
• Anything requiring human authorisation

Testing:

• What level of testing is expected (unit, integration, e2e)
• Which test files to add to or modify
• Edge cases the human wants covered vs. skipped

Proceed without handoff ONLY when:

• The issue has exact, unambiguous acceptance criteria
• The change follows an existing pattern visible in the codebase
• The implementation is purely mechanical with zero design choices

Handoff quality rules:

• Before handing off, do ONE quick exploration pass (2–3 file reads in the affected area) to make the questions informed and specific.
• Hand off the narrowest possible question. Bad: "What approach?" Good: "Should I use token-bucket (already in middleware/rate-limit.ts) or sliding-window for this endpoint?"
• Use all 4 question slots when the ambiguity is broad. A single question is fine when only one thing is unclear.
• Multiple rounds of handoff are expected — one round per layer of ambiguity.
• Every handoff question MUST include concrete context from the codebase.

Reviewer

Principle: The reviewer surfaces; the human decides.

Hand off for:

• Architectural concerns — does this change fit the system design?
• Risk assessment — data migrations, auth changes, performance impact
• Testing expectations — are the existing tests sufficient?
• Ambiguous changes — code whose purpose or impact isn't clear from context
• Security-sensitive modifications
• Whether a PR should be approved, request changes, or commented

Handle autonomously:

• CI status, merge conflicts, missing labels (report as mechanical facts)
• Style, naming, and lint deviations (note as comments, don't block)
• Pattern consistency observations (note if a pattern exists nearby)
• Missing tests (flag the gap, let the human decide if tests are needed)

Handoff quality rules:

• Before handing off, read the full diff, repo guidance files, and the PR's related issue if available.
• Distil findings into 1–4 structured questions. Group related observations.
• When a PR is large or touches multiple concerns, use all 4 question slots.

Monitor

The monitor opens at most one human_task per run, and only when anomalies are found. The payload may include a handoff field on options to delegate automatable fixes to the builder. See the monitor's system prompt for the full workflow including handoff-carrying option syntax and the artifact convention.

Agent-to-agent handoff

Agents can delegate work to other agents without human intervention using scripts/agent-handoff.sh. This is the canonical pattern for in-process handoffs (e.g. one agent delegating a follow-up task to another).

The script writes a mas_tasks row with:

• source: "handoff"
• task_id: hoff-<uuid-short> (matching createHandoffTask in the dispatcher)
• source_meta_json: {origin_task_id, origin_agent} for traceability
• plan_json: standard plan with a single worker for the target agent, including context.handoff_from_agent and context.handoff_from_task_id

The dispatcher picks up the pending row on the next tick and spawns the target agent. No human_task or resume cycle is involved — the delegating agent can continue its own work after writing the row.

Usage

HT_ID=$(/opt/orchestra/scripts/agent-handoff.sh <target-agent> <target-repo> \
  '{"summary": "<one-line>", "details": "<full context>"}' [origin-agent])

• target-agent: lowercase agent name (e.g. developer, reviewer, builder)
• target-repo: bare repo name matching [A-Za-z0-9._-]+
• third arg: JSON object for the target worker's task_input (must be valid JSON)
• origin-agent: optional; defaults to $CLAUDE_AGENT_NAME or "unknown"

Prints the generated task_id on stdout. Exits non-zero on validation failure.

Human_task handoff (alternative)

For cases where the handoff requires a human decision, use the handoff field on human_task options instead. The dispatcher's dispatchResolvedHumanTasks() detects handoff-carrying answers via resolveHandoffFromHumanTask() and calls createHandoffTask() to create the delegated task. The delegating agent's worker is then marked done rather than resumed. See the monitor's system prompt for the full handoff-carrying option syntax.

Related

• Human task hooks: .claude/hooks/human_task_open.sh and .claude/hooks/human_task_check.sh — see CLAUDE.md § Human task hooks for the invocation contract.
• Human task lifecycle: See CLAUDE.md § Human task lifecycle for the open → answered → consumed state machine.
• Agent-to-agent delegation: See docs/patterns.md § Agent-to-agent delegation for historical context on the dual-pattern evolution.