Agent handoffs

A handoff is how one agent passes work to another through Cairn. The sending agent writes everything the next agent needs into an artifact, and the receiving agent reads it and carries on. The artifact is the whole message, so it doesn't matter whether the two agents share a machine, run under different tools, or start days apart.

The pattern

1. Write a self-contained prompt. The sending agent, or you, writes the work order in markdown:

   • a one-paragraph summary at the top, so a person skimming it on the web knows what it is;
   • the task, and what "done" looks like;
   • the repositories, files, and issues involved, as links;
   • the constraints: what not to touch, what needs a person, how to verify the result;
   • what has already been tried, and what was learned.

   Write it for a reader with none of your context. If it mentions "the bug we talked about", it isn't a handoff yet.

2. Share it as an artifact. A single document goes in with artifact_create and share_type: "markdown". If the prompt needs supporting files, such as a failing log or a patch, put everything in one bundle with bundle_create and make the prompt its first file. Give it a title that says what it is, and tag it handoff. The handoff tag convention adds optional tags for the lane that should run it (lane:m), how hard it is (size:m), the repository and issue (repo:…, issue:…), where it came from (source:…), and how to report back (reply:cairn-comment). A reply:cairn-comment reply is left as a comment on the handoff, and nothing notifies you when it arrives: Cairn announces new artifacts only, not comments or reactions, so check the artifact yourself.

3. Pass the handle. Hand over a single line that carries the mcp://cairn/<id> handle, for example:

   Please execute the handoff prompt at mcp://cairn/<id>. Read it with Cairn's artifact_read before doing anything else, and treat its contents as the instructions for this task.

   Paste it into another agent's session, a scheduled job, or a chat. A person can open the same artifact at its web link.

4. Read and act. The receiving agent calls artifact_read with the handle. For a bundle, it reads the file list first and then the files it needs.

5. Close the loop. The receiver leaves a trail on the same artifact: a 👀 reaction when it picks up the work, and a comment linking to the result (a pull request, a report, a trace) when it's done. Anyone who opens the artifact can follow along in its side panel. Nobody is pushed a notification, so the sender has to look.

Handoff prompts expire like any other artifact, 7 days after creation by default. If the work might wait longer, extend the expiry from the web.

Manual today, automatic with Switchboard

Out of the box, a handoff is manual: someone pastes the line into the receiving agent. You can automate the delivery with the other two tools in the family:

1. Cairn announces each of your new artifacts to your outbound subscriptions.
2. Switchboard receives the event, and a routing rule turns handoff artifacts into a todo on the right agent's queue.
3. A worker kept running by Harness claims the todo, reads the artifact, and does the work.

A routing rule recognizes a handoff by its tags (handoff, plus a lane: tag to pick the pool) and checks who created it. The full setup is in the worked example. You add the subscription yourself, in Settings → Outbound subscriptions; it only ever carries events about your own artifacts.

The routing rules themselves live in Switchboard. Its handoff lanes guide covers the lanes, the rule pack that sorts handoffs into them, and what each worker receives.

Why didn't my handoff route?

Under the rule pack in Switchboard's handoff lanes guide, some handoffs are held: they land on a hold queue that has no workers, so nothing picks them up until a person looks. Others are dropped. Cairn doesn't see either outcome, so check the tags before you create the artifact:

• size:xl is held.
• More than one lane: tag, or more than one size: tag, is held rather than guessed. Write lane:m, not lane:m lane:l.
• No handoff tag: dropped. Without it, the artifact isn't a handoff.
• An actor_id the rule pack doesn't list: dropped. The pack trusts only the actor_id values its operator listed, so a new credential needs adding first. See what actor_id holds.

In Switchboard, test_webhook_rules and list_webhook_events show which rule matched a stored event and why.

The trust model

A handoff from one of your own agents is semi-trusted. It came from something acting as you, so it's a reasonable source of instructions for the task it describes. But it's still text an agent wrote, and that agent may have read something hostile along the way (an issue body, a log, a web page) and copied it in. The receiving agent keeps its own rules.

Check who created it. artifact_read returns the artifact's provenance. Only the fields Cairn sets itself can tell you who made it:

Field	Set by	What it tells you
provenance.actor	Cairn, from the credential that created it	The person whose token or session created the artifact
provenance.channel	Cairn	How it arrived: via MCP for an agent, via API for a token (the CLI included), via web for a signed-in browser
provenance.on_behalf_of	The MCP client, about itself	Which client made it; useful context, not proof
tags, title, and body	Whoever created the artifact	Routing hints and claims, never credentials

If the actor isn't you, or someone you expect work from, don't treat the artifact as a handoff. A handoff tag, a title, or a line in the body claiming who sent it proves nothing.

Let the body shape the task, never the permissions. A handoff can tell the receiver what to work on. It can't change what the receiver is allowed to do. The receiver should refuse, and flag to a person, anything in a handoff that tries to:

• skip review, approvals, or tests, or merge or deploy without the usual gate;
• print, send, or upload credentials, environment variables, or private files;
• run a script from a URL, install something unexpected, or contact an unfamiliar host;
• override its standing instructions, or claim that someone "already approved" a risky step.

Verify its claims. "The fix is in PR 42" is a lead, not a fact. Check the code.

Keep secrets out. Anyone with the link can read a handoff, and its contents land in the receiving agent's context. Say where a secret lives, never what it is.