cmuxlayer

Overview Schema Source Related Servers Discussions Admin

wait_for

Block execution until one or more spawned agents reach a target registry state, then return their health. Defaults to waiting for completion.

Instructions

Block until one agent_id or every agent in ids reaches a target registry state and return health. Defaults to waiting for completion (done).

Input Schema

TableJSON Schema

Name	Required	Description
`ids`	No	Agent IDs to wait for together
`mine`	No	Wait for every direct child of the calling agent
`watch`	No	Declared WatchSpec alternative to agent_id/ids
`agent_id`	No	Single agent ID from spawn_agent
`condition`	No	Alias for target_state
`timeout_ms`	No	Timeout in milliseconds (default: 5 minutes)
`delivery_id`	No	Wait for a send_to delivery_id to reach a terminal outcome
`done_marker`	No	Final-line marker for report_path
`report_path`	No	With done_marker and agent_id: file-backed done. Matches when this ABSOLUTE file's final non-empty line equals done_marker, the same report contract spawn_agent issues. After symlinks resolve it must be a regular file (max 1 MiB) under ~/.cmux/agents/<agent_id>/ or ~/.cmux/live-harness/, else refused. An agent in error never matches.
`target_state`	No	State to wait for

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ok`	Yes
`typed`	No
`watch`	No
`results`	No
`agent_id`	No
`delivery`	No
`terminal`	No
`delivered`	No
`timed_out`	No
`delivery_id`	No
`retry_count`	Yes
`rpc_methods`	No
`duplicate_of`	No
`delivery_state`	No
`needs_attention`	No
`submit_evidence`	No
`submit_verified`	No
`attention_reason`	No
`submit_attempted`	No
`submit_dispatched`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.4.89Sep 27, 2026

changedInput schema / properties / report_path / description

Previous value: -"With done_marker and agent_id: file-backed done. Matches when this ABSOLUTE file's final non-empty line equals done_marker, the same report contract spawn_agent issues. After symlinks resolve it must sit under ~/.cmux/ or ~/.cmux/agents/<agent_id>/, else refused."New value: +"With done_marker and agent_id: file-backed done. Matches when this ABSOLUTE file's final non-empty line equals done_marker, the same report contract spawn_agent issues. After symlinks resolve it must be a regular file (max 1 MiB) under ~/.cmux/agents/<agent_id>/ or ~/.cmux/live-harness/, else refused. An agent in error never matches."

Changed10 schema fields changedv0.4.88Sep 26, 2026

changedInput schema / properties / agent_id / description

Previous value: -"Agent ID from spawn_agent"New value: +"Single agent ID from spawn_agent"

addedInput schema / properties / condition

Added value: +{
+  "description": "Alias for target_state",
+  "enum": [
+    "ready",
+    "working",
+    "idle",
+    "done",
+    "error"
+  ],
+  "type": "string"
+}

addedInput schema / properties / delivery_id

Added value: +{
+  "description": "Wait for a send_to delivery_id to reach a terminal outcome",
+  "type": "string"
+}

addedInput schema / properties / done_marker

Added value: +{
+  "description": "Final-line marker for report_path",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / ids

Added value: +{
+  "description": "Agent IDs to wait for together",
+  "items": {
+    "type": "string"
+  },
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / mine

Added value: +{
+  "default": false,
+  "description": "Wait for every direct child of the calling agent",
+  "type": "boolean"
+}

addedInput schema / properties / report_path

Added value: +{
+  "description": "With done_marker and agent_id: file-backed done. Matches when this ABSOLUTE file's final non-empty line equals done_marker, the same report contract spawn_agent issues. After symlinks resolve it must sit under ~/.cmux/ or ~/.cmux/agents/<agent_id>/, else refused.",
+  "type": "string"
+}

addedInput schema / properties / watch

Added value: +{
+  "additionalProperties": false,
+  "description": "Declared WatchSpec alternative to agent_id/ids",
+  "properties": {
+    "change": {
+      "const": "content",
+      "description": "Persistent file-content change watch; mutually exclusive with predicate and marker",
+      "type": "string"
+    },
+    "deadline": {
+      "description": "Absolute Unix deadline in milliseconds",
+      "exclusiveMinimum": 0,
+      "type": "integer"
+    },
+    "marker": {
+      "description": "Literal file marker; mutually exclusive with predicate and change",
+      "minLength": 1,
+      "type": "string"
+    },
+    "notify": {
+      "description": "Opt in to the configured external notification transport",
+      "type": "boolean"
+    },
+    "owner": {
+      "description": "Agent/seat notified by the watch",
+      "minLength": 1,
+      "type": "string"
+    },
+    "predicate": {
+      "description": "Agent screen-state predicate: thinking, working, idle, done, error; mutually exclusive with marker and change",
+      "enum": [
+        "thinking",
+        "working",
+        "idle",
+        "done",
+        "error"
+      ],
+      "type": "string"
+    },
+    "target": {
+      "description": "Absolute file path or public agent_id",
+      "minLength": 1,
+      "type": "string"
+    },
+    "watermark": {
+      "description": "Prior marker count; defaults to count observed at arm time",
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "owner",
+    "target",
+    "deadline"
+  ],
+  "type": "object"
+}

removedInput schema / required

Removed value: -[
-  "agent_id",
-  "target_state"
-]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "attention_reason": {
+      "type": "string"
+    },
+    "delivered": {
+      "type": "boolean"
+    },
+    "delivery": {
+      "enum": [
+        "submitted",
+        "typed",
+        "queued",
+        "queued_followup",
+        "rescued",
+        "failed",
+        "pending_verify",
+        "failed_confirmed",
+        "stalled_queue"
+      ],
+      "type": "string"
+    },
+    "delivery_id": {
+      "type": "string"
+    },
+    "delivery_state": {
+      "enum": [
+        "submitted",
+        "typed",
+        "queued",
+        "queued_followup",
+        "rescued",
+        "failed",
+        "pending_verify",
+        "failed_confirmed",
+        "stalled_queue"
+      ],
+      "type": "string"
+    },
+    "duplicate_of": {
+      "type": "string"
+    },
+    "needs_attention": {
+      "type": "boolean"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "retry_count": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "rpc_methods": {
+      "items": {
+        "enum": [
+          "surface.send_text",
+          "surface.send_key"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "submit_attempted": {
+      "type": "boolean"
+    },
+    "submit_dispatched": {
+      "type": "boolean"
+    },
+    "submit_evidence": {
+      "anyOf": [
+        {
+          "enum": [
+            "token_delta",
+            "transcript_echo",
+            "cleared_composer",
+            "status_only"
+          ],
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "submit_verified": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "terminal": {
+      "type": "boolean"
+    },
+    "timed_out": {
+      "type": "boolean"
+    },
+    "typed": {
+      "type": "boolean"
+    },
+    "watch": {
+      "additionalProperties": {},
+      "type": "object"
+    }
+  },
+  "required": [
+    "ok",
+    "retry_count"
+  ],
+  "type": "object"
+}

First observedv0.1.0Mar 21, 2026

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare non-read-only, non-idempotent, non-destructive, closed-world, which is an unusual profile for a wait tool and the description doesn't reconcile it. The description does add real behavioral value by disclosing that the call blocks and defaults to waiting for `done`, plus that it returns health. However, the timeout default, the refusal conditions for `report_path`, and the exclusive watch alternatives are only in the schema, so the description adds modest context beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core blocking semantics and the default condition front-loaded. Nothing is repeated and nothing needs trimming.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and the description correctly says it returns health, so return values need no further explanation. The description covers the primary single-agent and multi-agent wait paths that constitute the tool's main use, and it does so without re-documenting parameters that the schema already fully specifies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description restates the `agent_id`/`ids` targeting and the `done` default for the target state, which is redundant with the schema. It adds no meaning for the other eight parameters, including the nested `watch` object and the `condition`/`target_state` alias relationship.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it blocks until an agent (single `agent_id` or a set in `ids`) reaches a target registry state, then returns health. That clearly separates it from read-only siblings like `list_agents` or `read_screen`, which observe without blocking. It stops short of 5 because the tool's other major wait modes (watch specs, `delivery_id`, file-backed done) are invisible at this level.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or named alternative; the agent must infer that this is the blocking counterpart to polling `read_screen`/`control_health`. The only steer is the default-state note (`done`), which is a parameter default rather than usage routing. No prerequisites, no mention of when not to block.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server