Delegation vs handoff
Two tools move work to a different agent, and they are not interchangeable.
task | agent_handoff | |
|---|---|---|
| Runs in | A child session | The same session |
| Result flows | Backwards, to the caller | Forwards — the caller's turn ends |
| Who stays responsible | The caller | The receiver |
| Context the target sees | Only the brief you write | The whole transcript |
| Eligible targets | subagent and all agents | primary and all agents |
| Available when | Always | Only with a harness selected |
Delegation — task
The caller spawns a child, the child works in its own session with its own context, and its final answer comes back as a tool result. The caller reads it and carries on.
This is the right shape when the work is a question with an answer: search this codebase, research this API, review this diff. The child's context stays out of the parent's, which is the point — a broad exploration that would have cost the parent 40,000 tokens of file dumps costs it one paragraph.
Because the child sees only the brief, the brief has to stand alone. Name paths, name the question, say what a good answer looks like.
Sub-agents cannot themselves delegate, and cannot hand off: a delegated turn belongs to the parent that asked for it.
Handoff — agent_handoff
The caller writes a short directive and ends its turn; the next agent picks up in the same session, reading everything that came before it. One transcript, one worktree, one run-lock — a single Stop cancels the whole chain.
agent_handoff({ to_agent: "review", summary: "…", next_steps: "…" })Because the receiver already has the full transcript, summary is a directive — "what I did, what's left" — not a context transplant.
This is the right shape when the work is a stage with a successor: the plan is written and someone should build it; the build is done and someone should test it. Nobody needs the result back, because nobody is waiting.
Handoff is only armed when a harness is selected for the conversation. With none selected the tool isn't even offered to the model.
Choosing
Ask who needs the answer.
- You need it back to keep going →
task. - Nobody needs it back; the next stage just needs to start → handoff, which means a harness.
A long pipeline built out of task calls forces one agent to hold the whole project in context and stay responsible for every stage of it. That is exactly the load a chain is designed to remove.
Next
- Harnesses — the chain that drives handoffs without the model having to call the tool.