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, and a sleeping agent never completes on its own. When wait reports the agent at rest, use queue_add to give it work, which wakes it automatically, or kill to end it. Repeating the same wait 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. The outcome line is one of:

wait ended: target phase <phase> reached
wait ended: agent is terminal (<phase>)
wait ended: turn finished (task-complete) ..., wait ended: agent is at rest (idle, VM running) ..., or wait ended: agent is at rest (sleeping) ...
wait ended: timeout after <n>s ... when timeout_seconds elapses first

The main status fields are:

Field	Type	Description
`agentId`	object	The agent’s identity: `tenant`, `ownerProvider`, `account`, `workspace`, and the `agent` slug path.
`phase`	string	Current lifecycle phase (e.g. `PHASE_TASK_COMPLETE`).
`vmStopped`	boolean	`true` when the VM is stopped (sleeping).
`queue`	object	Every undelivered follow-up. An agent with anything queued is not at rest.
`output`	object	Agent output: `response` text, `prs` array, `cost` in USD, and token counts.

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_APP", "org": "acme"},
    "ownerProvider": "PROVIDER_GITHUB_OAUTH",
    "account": "alice",
    "workspace": "backend",
    "agent": ["fix-auth"]
  },
  "phase": "PHASE_TASK_COMPLETE",
  "output": {"prs": [{"url": "https://github.com/acme/backend/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.
none	`unknown phase "<phase>"`: the `phase` value is not a phase name.	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