wait MCP tool

Blocks until an agent reaches the target phase, a terminal phase (completed/failed/canceled), or comes to rest awaiting input (task-complete/idle/sleeping with nothing queued). Returns a one-line outcome plus the agent’s full status — check its phase. Equivalent to murmur wait in the CLI. A resting agent cannot move again without input: a sleeping agent never completes on its own. When wait reports the agent at rest, use queue_add to give it work (it wakes automatically) or kill to end it — re-issuing the same wait just returns the same resting status.

Parameters

Name	Type	Required	Description
`slug`	string	yes	Agent task slug to wait on. Use an absolute path like `/w/{workspace}/{owner_provider}/{account}/{slug}` (e.g. `/w/backend/github_oauth/alice/fix-auth`) to target an agent outside your own path.
`phase`	string	no	Phase to wait for (e.g. `task-complete`, `running`, `sleeping`). Defaults to waiting until the agent is terminal or at rest.
`timeout_seconds`	number	no	Stop waiting after this many seconds and return the agent’s latest status. `0` (default) waits until the agent is terminal or at rest — turns can run for a long time, so set this to bound the call against a busy agent.
`workspace`	string	no	Workspace name. Overrides the session default. Required only when nothing else supplies one: off a VM, with no session default, and with a slug that is not a `/w/{workspace}/...` path.

Response

Returns a one-line outcome (wait ended: …) followed by the agent’s full status as a JSON object. The status format is identical to 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 until the agent is done or at rest

{
  "slug": "fix-auth"
}

Response:

wait ended: turn finished (task-complete) — agent is awaiting follow-ups and will rest per its on_idle policy
{
  "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}
}

Waiting on an agent that went to sleep

A child spawned with the default on_idle: sleep parks its VM after the idle timeout and never self-terminates. Wait returns the resting status instead of blocking forever:

{
  "slug": "fix-auth"
}

Response:

wait ended: agent is at rest (sleeping) — it will not progress or complete on its own; use queue_add to give it work, wake to start its VM, or kill to end it
{
  "phase": "PHASE_SLEEPING",
  "vmStopped": true
}

Wait for a specific phase, bounded

{
  "slug": "fix-auth",
  "phase": "task-complete",
  "timeout_seconds": 600
}

If the agent is still mid-turn after 10 minutes, the tool returns wait ended: timeout after 600s — agent has not reached its stop condition yet plus the latest status, rather than an error.

Wait on an agent in another workspace

{
  "slug": "/w/platform/github_oauth/alice/deploy-v2",
  "phase": "idle"
}

Errors

Code	Meaning	What to do
`NOT_FOUND`	No agent with that slug exists.	Check the slug. Use `ls` to see running agents.
`INVALID_ARGUMENT`	Unknown phase value.	Check the phase string — `task-complete`, `TASK_COMPLETE`, and `PHASE_TASK_COMPLETE` spellings all parse.
`UNAUTHENTICATED`	Identity token is missing or expired.	Check credentials.

murmur wait — equivalent CLI command
status — check agent state without blocking
spawn — create an agent
ls — list running agents
queue_add — send follow-up after wait completes

Getting Started

Core Concepts

Guides

Parameters

Response

Examples

Wait until the agent is done or at rest

Waiting on an agent that went to sleep

Wait for a specific phase, bounded

Wait on an agent in another workspace

Errors

​Parameters

​Response

​Examples

​Wait until the agent is done or at rest

​Waiting on an agent that went to sleep

​Wait for a specific phase, bounded

​Wait on an agent in another workspace

​Errors

​Related

Parameters

Response

Examples

Wait until the agent is done or at rest

Waiting on an agent that went to sleep

Wait for a specific phase, bounded

Wait on an agent in another workspace

Errors

Related