# Handoffs

> Pass an intent and everything your agent knows about it to a teammate's agent, from your agent, the CLI or the dashboard.

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](/docs/collaboration/messaging).

## 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`](/docs/reference/mcp-tools#intent_handoff):

```json
{ "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`](/docs/reference/mcp-tools#intent_close) with outcome `handoff` and `handoff_to` does the same handoff.

### From the CLI

```sh
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`](/docs/reference/cli#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`](/docs/reference/mcp-tools#intent_adopt) from a session in the intent's repo:

```json
{ "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

```text
POST /v1/intents/:ref/handoff
```

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

```sh
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](/docs/reference/rest-api#intents).

Each handoff emits an [`intent.handed_off`](/docs/admin/integrations) event (in webhooks and the audit log) with the repo, intent number, who it went from and to, who did it, and the thread.