> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# wait

> MCP tool that blocks until an agent reaches a target lifecycle phase — useful when coding agents need to wait for spawn or completion events.

Blocks until an [agent](/concepts/agents) reaches a target lifecycle phase. Returns the agent's full status when the phase is reached.

Equivalent to [`murmur wait`](/cli/wait) in the CLI.

When `phase` is omitted, waits until the agent reaches any phase that needs attention (e.g. `task-complete`, `idle`, `failed`). When `phase` is specified, waits for that exact phase.

## Parameters

| Name        | Type   | Required | Description                                                                                                                   |
| ----------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `slug`      | string | yes      | Agent task slug to wait on. Use an absolute path like `/w/workspace/u/account/slug` to target an agent outside your own path. |
| `phase`     | string | no       | Phase to wait for (e.g. `task-complete`, `running`, `idle`). Defaults to any phase needing attention.                         |
| `workspace` | string | no       | Workspace name. Overrides the session default.                                                                                |

## Response

Returns the agent's full status as a JSON object when the target phase is reached. The response format is identical to [`status`](/mcp-server/status).

| Field       | Type    | Description                                                                  |
| ----------- | ------- | ---------------------------------------------------------------------------- |
| `agentId`   | object  | The agent's identity — tenant, account, workspace, slug path.                |
| `phase`     | string  | Current lifecycle phase (e.g. `PHASE_TASK_COMPLETE`).                        |
| `vm`        | object  | VM instance name, project, zone.                                             |
| `vmStopped` | boolean | `true` when the VM is stopped (sleeping).                                    |
| `version`   | string  | The murmur version running on the VM.                                        |
| `progress`  | object  | Latest progress update — label, detail, timestamp.                           |
| `output`    | object  | Agent output — `response` text, `prs` array, `commits` count, `cost` in USD. |

## Examples

### Wait for any phase needing attention

```json theme={null}
{
  "slug": "fix-auth"
}
```

Response:

```json theme={null}
{
  "agentId": {
    "tenant": {"provider": "PROVIDER_GITHUB_OAUTH", "org": "alice"},
    "ownerProvider": "PROVIDER_GITHUB_OAUTH",
    "account": "alice",
    "workspace": "backend",
    "agent": ["fix-auth"]
  },
  "phase": "PHASE_TASK_COMPLETE",
  "output": {"prs": [{"url": "https://github.com/org/repo/pull/42"}], "cost": 1.23}
}
```

### Wait for a specific phase

```json theme={null}
{
  "slug": "fix-auth",
  "phase": "task-complete"
}
```

### Wait on an agent in another workspace

```json theme={null}
{
  "slug": "/w/platform/u/alice/deploy-v2",
  "phase": "idle"
}
```

## Errors

| Code               | Meaning                               | What to do                                                                          |
| ------------------ | ------------------------------------- | ----------------------------------------------------------------------------------- |
| `NOT_FOUND`        | No agent with that slug exists.       | Check the slug. Use [`ls`](/mcp-server/ls) to see running agents.                   |
| `INVALID_ARGUMENT` | Unknown phase value.                  | Check the phase string. Valid values: `task-complete`, `running`, `idle`, `failed`. |
| `UNAUTHENTICATED`  | Identity token is missing or expired. | Check credentials.                                                                  |

## Related

* [`murmur wait`](/cli/wait) — equivalent CLI command
* [`status`](/mcp-server/status) — check agent state without blocking
* [`spawn`](/mcp-server/spawn) — create an agent
* [`ls`](/mcp-server/ls) — list running agents
* [`queue_add`](/mcp-server/queue-add) — send follow-up after wait completes