01 · Summary
TLDR
Default to structured messages. Promote to tool results when the chain is synchronous and the receiver is itself a tool. Fall back to shared files only when payload size or binary format makes serialization impractical. Never pass raw conversational text - that is always the wrong answer on D1 scenario questions.
02 · The three primitives
Shared files vs structured messages vs tool results
Every subagent handoff in a Claude multi-agent pipeline reduces to one of three primitives. Choose by latency profile, payload shape, and audit requirements.
- Shared files suit large, persistent payloads - for example, artifacts a downstream agent reads at its own pace. They introduce coupling on storage location and require explicit locking or versioning to avoid race conditions between concurrent subagents. Use only when payload size or binary format forces it.
- Structured messages(JSON or typed envelopes passed through an orchestrator or message bus) are the preferred CCA-F default. They keep handoff intent explicit, are inspectable mid-flight, and align with Claude's tool-call / tool-result turn structure. Treat this as the path-of-least-surprise.
- Tool results are the tightest handoff primitive - the calling agent receives a typed result synchronously, making them ideal when the receiving subagent is itself exposed as a tool and the orchestrator needs deterministic chaining.
03 · Decision rule
The decision rule the exam rewards
The CCA-F exam tests this decision explicitly: tool results for tight synchronous chains, structured messages for loose orchestration with audit requirements, and shared files only when payload size or binary format makes serialization impractical.
| Situation | Right primitive | Why |
|---|---|---|
| Subagent exposed as a tool; orchestrator chains synchronously | Tool result | Deterministic, typed return; lowest-latency path; easiest to replay in tests. |
| Asynchronous flow; orchestrator routes between many subagents | Structured message | Inspectable mid-flight; survives orchestrator restarts; clean audit trail. |
| Payload too large or binary for envelopes | Shared file + structured pointer | Storage-mediated; pass the pointer through a structured message, never the file itself. |
| Need to forward conversation context | Extract structured facts first | Raw transcripts leak prompt structure and balloon downstream context. Always wrong on the exam. |
04 · HowTo
How to choose a handoff pattern: a five-step blueprint
- Default to structured messages. Pass typed JSON envelopes through your orchestrator. Each handoff is explicit, inspectable mid-flight, and aligns with Claude's tool-call / tool-result turn structure. Treat this as the safe default for CCA-F.
- Promote to tool results for tight synchronous chains. When the receiving subagent is itself exposed as a tool and the orchestrator needs deterministic chaining, return the handoff as a tool_result block on the calling turn. This is the tightest primitive and the easiest to test.
- Fall back to shared files only for size or format constraints. If the payload is too large or binary (model checkpoints, large CSVs, images), write to shared storage and pass a pointer through a structured message. Require explicit versioning or locking to avoid race conditions between concurrent subagents.
- Never pass raw conversational text as state. Conversational text leaks prompt structure, balloons context, and is explicitly penalized in D1 scenario questions. If you find yourself forwarding a transcript, you have a missing schema - define it before shipping.
- Instrument the handoff. Log every handoff with the producing subagent, receiving subagent, envelope size, and timestamp. The 12% skip-rate problem and silent state-drop bugs both surface from this telemetry, not from prompt review.
05 · Anti-pattern
The anti-pattern to flag
Never pass raw conversational text as state
Passing raw conversational text between subagents as "state" leaks prompt structure into downstream contexts, balloons the receiving subagent's context window, and is explicitly penalized in D1 scenario questions. If you need a downstream agent to act on a conversation, extract the structured facts first and pass those - not the transcript.
06 · FAQ
Frequently asked
What is a subagent state handoff in a Claude multi-agent pipeline?
It is the explicit transfer of state - data, decisions, or intermediate results - from one subagent to another within an orchestrated multi-agent flow. The three primitives are shared files (storage-mediated), structured messages (orchestrator-mediated typed envelopes), and tool results (synchronous tool-call returns).
Which handoff pattern is the CCA-F default?
Structured messages. Typed JSON envelopes passed through the orchestrator or message bus keep handoff intent explicit, are inspectable mid-flight, and align with Claude's tool-call / tool-result turn structure. They are the safest default and the one most CCA-F D1 questions reward.
When should I use tool results instead of structured messages?
Use tool results for tight synchronous chains where the receiving subagent is itself exposed as a tool and the orchestrator needs deterministic chaining. Tool results are the tightest handoff primitive - the calling agent receives a typed result synchronously, which makes the chain easier to test, reason about, and replay.
When are shared files the right choice?
Only when payload size or binary format makes serialization through a message envelope impractical - model checkpoints, large CSVs, images, or other artifacts the downstream agent reads at its own pace. Shared files introduce coupling on storage location and require explicit locking or versioning to avoid race conditions between concurrent subagents. Treat them as the exception, not the rule.
Why is passing raw conversational text between subagents an anti-pattern?
Raw conversational text leaks prompt structure into downstream contexts, balloons the receiving subagent's context window, and is explicitly penalized in D1 scenario questions on the CCA-F. If you need a downstream agent to act on a conversation, extract the structured facts first and pass those - not the transcript.
How does this decision show up on the CCA-F exam?
D1 (Agentic Architectures) questions test the decision rule explicitly: choose tool results for tight synchronous chains, structured messages for loose orchestration with audit requirements, and shared files only when payload size or binary format forces it. Distractors typically suggest sharing transcripts or passing free-form text - those are always wrong.
How should I instrument handoffs for debugging?
Log every handoff with the producing subagent, receiving subagent, envelope size or payload pointer, and timestamp. Most state-handoff bugs (silent drops, 12% skip rates, partial payloads) surface from this telemetry rather than from prompt review. Treat handoff observability the same way you treat tool-call observability.