yanacuti1121 When to Use
- Use when: sending context from orchestrator to sub-agent
- Use when: receiving a sub-agent result and merging it into main context
- Use when: a workflow shows signs of loop, drift, or consensus collapse
- Use when: context window pressure is growing across agent waves
- Do NOT use for: session-level handoff documents — use
handoff - Do NOT use for: planning which agents to run in which order — use
subagent-dependency
The Three Context Failure Modes at Handoff
Understand these before writing any handoff:
| Name | What happens | Signal |
|---|---|---|
| Context Bleed | Downstream agent inherits irrelevant state from upstream work | Agent refers to tasks it wasn't assigned |
| Context Explosion | Recursive history passing grows token count exponentially | 5 agents × 50 messages = 400–500 MB; context fill >80% |
| Context Drift | Agent acts on stale info from an earlier wave | Contradicts a decision made after its context was frozen |
Outgoing Handoff — Compression Protocol
Before passing context to a sub-agent, compress to this format. Anthropic's principle: agents communicate compressed results, not raw context. Target: 1,000–2,000 tokens outgoing, regardless of how much was read.
What to include
## Handoff to [agent-name]
Task: [one sentence — what this agent must do]
Scope: [exact files or directories — no wildcards]
Inputs: [only the findings/outputs directly needed]
Decisions already made: [list — agent must not re-open these]
Must NOT: [explicit list of forbidden actions for this agent]
Expected output format: [exact structure you'll consume]
What to leave out
- Full conversation history from previous waves
- Findings irrelevant to this agent's scope
- Rationale for decisions it didn't make
- Raw tool output — summarize to key facts only
- Anything the receiving agent can read directly from disk
Incoming Result — Freshness Validation
Before merging a sub-agent result into main context:
□ Result references specific files → verify those files still exist and haven't
changed since the sub-agent was dispatched (git diff HEAD since dispatch)
□ Result references a "current state" → confirm that state is still true
□ Result was produced from Wave N-1 → check Wave N hasn't already superseded it
□ Result contradicts another agent's result → flag conflict, do NOT silently merge
If freshness fails: discard the stale result, re-dispatch with corrected context.
Bad Handoff Detection Signals
Monitor for these across agent turns. If triggered, do not continue — apply the response.
| Signal | Definition | Response |
|---|---|---|
| Agent Tennis | Same point disagreed on for 3+ turns, no task progress | Force conflict resolution: state both positions, escalate to human tie-breaker |
| Politeness Spiraling | Agents over-validating each other ("Great point!", "Agreed!") without forward progress | Inject: "Stop validating. State your finding directly." |
| Logic Lock | Consecutive handoff outputs are semantically near-identical (same conclusion, different words) | Trigger Escape Sequence: summarize the loop, break with a forced new constraint |
| Confidence Masking | Sub-agent returns high confidence but finding is unsupported — often from Hallucinated Consensus | Apply gates/anti-fake-pass-gate.md — require Hard Evidence before accepting |
| Recency Drift | Agent's output ignores the original task and addresses only the most recent message | Re-inject the original task spec at the top of the next dispatch |
Escape Sequence (Loop Break)
When Logic Lock or Agent Tennis is confirmed:
- Stop dispatching new agents in the current wave
- Capture: what both/all sides claimed, how many turns it has run
- State explicitly: "This is a Logic Lock at turn N. The constraint preventing resolution is: [X]."
- Either: introduce a new concrete constraint that breaks the symmetry, or escalate to human with the captured summary
Do not attempt to resolve a Logic Lock by re-running the same agents with slightly different prompts.
Output Format — Incoming Result Integration
When merging sub-agent results into main context, structure as:
## Agent Result: [agent-name] — Wave [N]
Status: COMPLETE | STALE | CONFLICT
Freshness: verified | WARNING: [what changed]
### Key findings
[3–5 bullet points max — highest signal only]
### Decisions for main agent
[explicit list of what main agent must now do differently]
### Discarded
[what was in the raw result but is not being carried forward, and why]
Never paste raw sub-agent output directly into main context.
Anti-Fake-Pass Rules
Before claiming a handoff is complete, you MUST confirm:
- Outgoing context compressed to task + scope + inputs only — no full history
- Incoming result freshness validated against current disk state
- No active bad-handoff signal (Agent Tennis, Logic Lock, Confidence Masking)
- Conflicts between agent results flagged explicitly, not silently merged
- If a context failure mode was triggered: named it, applied the response
Reference: docs/multi-agent-failure-modes.md | gates/anti-fake-pass-gate.md