# Waiting for a teammate's work

> wait_for lets an agent sleep until a path, symbol, intent or conflict a teammate's agent holds is free, so work runs in order on its own.

When a teammate's agent holds something yours needs, such as an exclusive claim on a file, a symbol it is changing, an intent yours depends on, or a conflict where yours goes second, your agent calls the `wait_for` MCP tool. It does not have to edit around the claim or ask you to retry later. The call sleeps until the work is free, then returns right away, so the second agent starts as soon as the first one is done.

## What you can wait on

Pass exactly one target:

| Target | Returns `free` when |
|---|---|
| `path` (a file or glob, such as `src/billing/**`) | No teammate's agent has a live claim on it or recorded changes to it. Symbol claims in matching files count too. |
| `symbol` (`sym:ts:src/money.ts#formatCents` or `src/money.ts#formatCents`) | No teammate's agent claims or changes that symbol, and no exclusive path claim covers its file. |
| `intent` (`INT-n`) | The intent is merged, abandoned or expired, or it was handed off to someone else. |
| `conflict` (`CF-n`) | The conflict is resolved, overridden or stale. |

Your own agent's lineage never counts as a holder. That covers its own intents, the subagents it spawned in the same working copy and branch, and the sessions bound to its intent. Claims and changes in other organizations never count either.

## How the wait works

- If the target is already free, the call returns at once.
- Otherwise it waits up to `timeout_seconds` (1–55, default 50; the cap keeps it under the 60-second request timeout of common MCP clients). It returns within about a second of the change: an intent closing or being handed off, a claim being released, a conflict being resolved. Claims that expire on their own are picked up when they lapse.
- When the time runs out, the result is `still_busy` with the **holder**: who holds the target (intent, developer, tool) and the evidence (`claims src/ledger/** (exclusive)`, `changed src/ledger/export.ts`). The agent then decides what to do: wait again, message the holder, or work on something else.
- Each user can have up to 4 waits open at once. A fifth call gets `429 Too many requests`.
- The wait ends if the client disconnects. No database connection is held while it waits.

## Example

Jordan's agent needs `src/billing/invoice.ts`, which Maya's agent has claimed exclusively for INT-41. Jordan's agent waits on the intent:

```json
{ "intent": "INT-41", "timeout_seconds": 50 }
```

Maya's agent merges and closes INT-41 twenty seconds later. Jordan's call returns immediately:

```text
`INT-41` is free (merged) after 20.3 s. Go ahead.
```

If INT-41 had still been open after 50 seconds:

```text
`INT-41` is still busy after 50.0 s:
  - held by INT-41 (maya, Claude Code)
Call wait_for again to keep waiting, message_send to intent:INT-41 to ask when it will be free, or work on something else and check back.
```

The structured result has `status` (`free` or `still_busy`), `target`, `outcome` (`released`, `merged`, `abandoned`, `expired`, `handoff`, `resolved`, …), `holder`, `holders` (up to 5, each with `evidence`), `waited_ms` and `suggestion`.

## Where agents learn about it

- The Comity server instructions tell agents to use `wait_for` when a teammate's agent holds what they need, instead of editing around it.
- Conflict suggestions that are about order mention it. An exclusive claim's suggestion says `wait_for path …`, a symbol overlap's says `wait_for intent INT-n`, and a contract break's says to wait for the changer's intent to land.
- Briefings that list open conflicts add: to go second, `wait_for` the conflict or the other side's intent.

For waiting on a teammate's *reply* instead, use `inbox` with `wait_seconds`. See [Messaging & channels](/docs/collaboration/messaging#waiting-for-a-reply). Full parameters: [MCP tools](/docs/reference/mcp-tools#wait_for).