wait_for
Ends an agent turn to wait for a card, merge request, CI pipeline, registration, external event, or manual signal, then resumes the agent when that event occurs.
Instructions
End your turn waiting on an event: another card (on=card), a merge request (on=mr), a CI pipeline or GitHub Actions run (on=pipeline), the runner's merge gate on a reviewed head (on=merge), a runner registration (on=registered), the published moment of an external event (on=time, with event_ref, source and why) or, only on a card a lead labelled wake:manual, a passive wait with no observer and no timer that a new comment or the lead's action ends (on=manual, with note saying why). A GitHub PR merge is on=mr provider=github until=merged (project_path owner/repo, mr_iid the PR number, after_sha the head, after_status opened); on=merge is GitLab only. The server checks the target, records the wait (replacing your previous one on this card), writes the comment and releases your checkout; you are woken when the event happens. A refusal writes nothing. Waiting on another agent's answer is ask_agent; on a person, ask_human.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task_id": "<task_id>",
"on": "<on>"
},
"name": "wait_for"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| on | Yes | What you wait on: card, mr, pipeline, time, merge, registered or manual. Only the fields of that kind are read; after_* and registration* on a kind that does not take them are refused. | |
| why | No | on=time, required: what happens at until_at and why not earlier, 10 to 500 chars. | |
| note | No | Why you wait and what ends the wait; the generated comment shows it whole, the wait itself keeps its first 500 characters. Required for on=manual. | |
| until | No | on=mr: merged, green or changed. on=pipeline: finished, green or changed. | |
| mr_iid | No | on=mr or merge: merge request iid within project_path (not the global id). | |
| source | No | on=time, required: where the event's time is published: an https:// URL, comment:<uuid> or artifact:<uuid> written by someone else. A card is not a source. | |
| task_id | Yes | The card you are working on (UUID or 6-12 hex short id). | |
| turn_id | No | Optional turn id within the session (max 200 chars), copied onto the outcome. | |
| provider | No | on=mr: gitlab or github. on=pipeline: gitlab (default) or github for an Actions run (project_path owner/repo, pipeline_id the run id). on=merge: gitlab only; a GitHub PR merge is on=mr provider=github until=merged. | |
| until_at | No | on=time: when the external event happens, RFC3339 with Z or an offset (2026-10-29T06:00:00Z, 2026-10-29T09:00:00+03:00), 5 minutes to 30 days from now. Not a retry or poll interval: a wait on a card, MR or pipeline waits on that event. | |
| after_sha | No | on=merge, required: full 40 or 64 hex SHA of the reviewed head. on=mr or pipeline, optional baseline: the head SHA you observed. | |
| criterion | No | on=card with target_condition=artifact_published: the result you wait for, as its producer will name it in the evidence (max 500 chars). | |
| event_ref | No | on=time, required: the external event the moment belongs to, e.g. nightly-export (max 500 chars). | |
| session_id | No | Optional runner session id (max 200 chars), copied onto the recorded outcome and wait. | |
| pipeline_id | No | on=pipeline: the pipeline id to wait on. | |
| vcs_link_id | No | on=mr: id of a VCS link of this card. Alternative to provider + project_path + mr_iid. | |
| after_status | No | Baseline status: opened for until=merged; for until=green or changed the pipeline status you observed (running, failed, success, manual, ...). | |
| project_path | No | on=mr, pipeline or merge: project path, e.g. entire-vc/evc-mesh. | |
| registration | No | on=registered: ops-review, gmail, receipt, lifecycle, stall, recovery, queue or native. | |
| required_jobs | No | on=pipeline, or on=mr with until green or changed: job names to read the wait from; omit for the whole pipeline. | |
| target_task_id | No | on=card: the card you wait on. Creates or reuses a blocks dependency on it; the receipt's wait names that edge (dependency_id, dependency_generation) and dependency_owned=true only when this wait created it or took it over from your own earlier wait on this card. An edge someone else made stays theirs (dependency_owned=false), and an operator's later edit of your edge (condition change, confirmed binding) takes it from your wait; the owner-checked delete (expected_generation + expected_owner_wait_id) refuses both with 409. on=manual: optional, must be this card itself. | |
| registration_ref | No | on=registered: ops-review or native: the 64-hex id; gmail: gmr_<12 hex>; receipt, lifecycle, stall, recovery, queue: this card's 8-hex id (may be omitted). | |
| target_condition | No | on=card: what the card must reach: task_done (default), shipped, deployed, accepted or artifact_published (a named result of that card: give criterion; its owner records the evidence). A card closed without that evidence still releases the wait, marked released_by=closure_without_evidence. | |
| after_pipeline_id | No | Baseline of until=green or changed: the pipeline id you observed (on=pipeline: equal to pipeline_id). Send with after_sha and after_status. |