Handoffs

A handoff passes in-flight work (an intent, INT-n) from you to a teammate. They become its owner, and their agent picks it up with the context yours built: the plan, what it claimed, what it changed, what it ran into.

Use it when you're going on leave at the end of a sprint, when the work turned out to belong to someone else's area, or when a teammate is better placed to finish it.

What the teammate gets

The intent keeps its number, status, claims and history; only the owner changes. Comity also opens a direct-message thread from you to them, linked to the intent, with the subject Handoff: INT-n <title>. Its message carries the bundle:

• The intent's plan.
• Its claims: paths, symbols and contracts.
• The files and symbols touched so far.
• Open conflicts with other work.
• The latest status your agent shared.
• Your note, if you wrote one.
• How to continue.

The thread shows up in the dashboard's Messages tab like any direct thread, and either of you can reply in it. See Messaging & channels.

Handing off

Three ways, all doing the same thing.

From your agent

Ask your agent to hand the work off ("hand this off to Jordan, note that the PDF layout is done but the totals are wrong"). It calls the MCP tool intent_handoff:

{ "to": "jordan@acme.com", "note": "PDF layout is done. Totals are off by tax on discounted lines; see the failing test in invoices.test.ts." }

ref defaults to the agent's current intent. intent_close with outcome handoff and handoff_to does the same handoff.

From the CLI

comity handoff @jordan --note "PDF layout is done; totals still wrong"
comity handoff jordan@acme.com --intent INT-12 --yes

@name matches a teammate by name, first name or the part of their email before @. Without --intent, the CLI hands off your only live intent in the current repo. See comity handoff.

From the dashboard

Open the intent in the Work tab, click Hand off…, pick the teammate, add an optional note and click Hand off. The drawer then links to the handoff thread in Messages.

What the teammate's agent sees

At its next tool call or prompt, the recipient's agent gets a Handed off to you section in its Comity context: who handed off which intent, their note, the claims, files and symbols touched, open conflicts, the last status, and how to pick it up. Every new agent session they start shows it again until one of them adopts the intent (for up to 7 days).

Their agent should confirm with them before taking over. To continue, it calls intent_adopt from a session in the intent's repo:

{ "ref": "INT-12" }

That binds the agent's session to the intent: its claims, recorded changes and conflicts become that session's, and the agent carries on from the bundle. If the session had only an auto-drafted intent of its own, that draft is abandoned. A session in another repo is told to adopt it from a session in the intent's repo.

What happens on your side

Your agents' sessions are released from the intent. The work they recorded so far stays with the intent and goes to the teammate with it. If one of your agents keeps editing the same files, Comity now treats that as overlapping the teammate's intent and reports a conflict.

Who can hand off

• Who hands off: the intent's owner, or an org owner or admin.
• Who can receive: a member of the org with the role owner, admin or member. Viewers and billing contacts can't own intents.
• Which intents: live ones (draft, active, blocked, in_review) and expired ones. A handed-off draft stays private: afterwards only the teammate sees it. Closed intents (merged, abandoned) can't be handed off. The dashboard offers Hand off… for declared intents.

API

POST /v1/intents/:ref/handoff

Scope intents:write. Body {to, note?}: to is the teammate's email, note up to 2,000 characters.

curl -X POST https://api.comity.so/v1/intents/INT-12/handoff \
  -H "Authorization: Bearer $COMITY_TOKEN" -H "Content-Type: application/json" \
  -d '{"to": "jordan@acme.com", "note": "PDF layout is done; totals still wrong"}'

Returns {intent, handoff}: the updated intent (now owned by the teammate) and the handoff (id, intent, from, to, note, thread_id, message_id, created_at, adopted_at, and bundle with the snapshot described above). Errors: 400 when the teammate can't own intents, 403 when you are neither the owner nor an admin, 404 for an unknown member, 409 when the intent is closed or they already own it. See the REST API.

Each handoff emits an intent.handed_off event (in webhooks and the audit log) with the repo, intent number, who it went from and to, who did it, and the thread.