Handoffs

A handoff records that ownership is moving. It answers the questions a vague “you can take it from here” never does: what is in scope, where the work stands, what remains, what is uncertain, and who is receiving it.

Handoffs work for an individual moving between agents or sessions, and for a team passing work between people. A team is not required.

A good handoff is what lets the next agent act rather than interrogate you. The sender defines the boundary and finish line, ContextStream preserves the working evidence, and the receiving agent can choose the next relevant lookup inside that assignment.

What a useful handoff contains

Write the summary for someone arriving cold. “Tests still fail” is not enough. Name which tests, what changed, what you already tried, and the evidence behind the current theory.

A handoff another reviewer can accept

You have changed the token-refresh coordinator and want a fresh reviewer to take over without editing production code. A useful handoff says:

• Scope: the coordinator, request wrapper, and two rotation tests; no deployment or unrelated auth cleanup;
• Current state: concurrent refreshes now share one in-flight request; the normal and invalid-token tests pass;
• Remaining failure: the clock-skew test fails when the old token expires during the retry;
• Evidence: the exact failure, the auth-refresh sequence diagram, and the decision that requires a bounded retry;
• Tried already: extending the token lifetime hid the failure and was reverted because it did not model production;
• Open question: should retry eligibility use the original request time or the refresh completion time?
• Next steps: review the race, verify both rotation tests, inspect the security boundary, and report findings without changing production code;
• Finish line: an accepted review with any regression filed as a linked ticket.

The recipient can accept that responsibility, inspect the attached records, and complete the handoff when the review is delivered. If the scope changes from review to implementation, update the handoff rather than letting the assignment drift only in chat.

The handoff lifecycle

A handoff can move through five states:

1. Draft — still being assembled.
2. Pending — ready and waiting for the recipient.
3. Accepted — the recipient has taken ownership.
4. Completed — the transferred work is finished.
5. Cancelled — the transfer no longer applies.

That lifecycle is why a handoff is not just a note. You can list what is waiting, see what was accepted, and close or cancel it without losing the history.

Handing work to another agent

An agent recipient can be a coder, explorer, planner, reviewer, or lead. The handoff says what role should take over; the context bundle supplies the working material.

Be explicit about the finish line:

handoff the remaining auth work to a reviewer:
check the clock-skew fix, verify the two rotation tests, and report any
security regression without changing production code

This is useful even when you are the only human involved. It gives a fresh agent a bounded assignment and leaves an inspectable record of the transfer.

Handoffs and capsules are different

A handoff is the workflow record. It has a sender, recipient, status, scope, open questions, next steps, and artifacts.

A capsule is the portable context bundle. It can carry selected decisions, lessons, documents, code context, and session material behind a controlled link.

Use both when the recipient is genuinely taking over and needs the underlying context. Use a handoff alone when the summary and linked workspace records are enough. Use a capsule alone when someone only needs to inspect context and is not accepting ownership.

Handoffs, tickets, and plans

These can be linked, but they are not substitutes:

• A plan explains the goal and ordered work.
• A ticket tracks one active work item through its lifecycle.
• A handoff records a transfer of responsibility.

For a large transfer, link the plan and open tasks. For a production incident, link the incident, the relevant runbook, and the current timeline. The handoff then becomes the front door instead of a second copy of all the detail.

Receiving and finishing one

Ask what is pending for you, inspect the open questions and attached context, then accept it when you are actually taking responsibility. If the scope is unclear, update the record before work starts so the clarification survives the conversation.

Complete the handoff when the transferred responsibility is finished—not merely when you have read it. If the work returns to the sender or becomes irrelevant, cancel it and say why in the summary.

Personal and shared boundaries

The handoff stays inside its workspace and project access boundary. A personal handoff can help you move work between your own sessions or agents. A shared handoff can target a workspace member.

Adding a capsule does not erase those boundaries. External-agent and public links have their own expiry, redaction, code-inclusion, and revocation policy. Review that policy before sending sensitive context outside the workspace.

For a client-facing incident transfer, prepare a smaller external package: customer-visible status, impact, next action, and expected update time. Exclude environment values, credentials, internal customer IDs, raw debug logs, internal-only tickets, and unrelated customer context. The internal handoff can retain the operational detail; the external capsule should contain only what its recipient needs.

If it doesn't work

The recipient sees the handoff but cannot continue. The summary is too thin or the necessary artifacts were not attached. Add the failed approaches, current evidence, exact next step, and a capsule if the context is large.

A person is not available as a recipient. Confirm they belong to the workspace and that you are working in the intended account mode.

The linked capsule no longer opens. It may have expired, reached its use limit, or been revoked. The handoff record remains; create a new scoped share if access is still appropriate.

Old pending handoffs are piling up. Accept, complete, or cancel them. A pending handoff should represent a real transfer waiting on someone.

Next

• Sharing context with a link
• Plans and tasks
• Tickets and operational tracking
• How the agent partnership works