Record external wait in visible plan
record_external_wait_in_planGeneric factual plan helper for the moment after a domain tool starts asynchronous work and returns a real externalWaitId. Identity and revision come from that stored hook wait; pass externalWaitId instead of copying externalKind, externalId, revisionId, or sourceExternalId. Legacy identity fields are optional assertions and must match the stored record. It turns waitingItemTarget into the waiting row. With an explicit currentItemTarget and no waitingItemTarget or waitingItem, that current unfinished item becomes the waiting row. When both targets name the same unfinished item, that item waits without claiming completion. Otherwise it completes the current launch step, reusing that row's label and completion criteria when waitingItem is omitted, or appends one waiting row only when that future work is not already visible. Both targets are selector objects with type=id/itemId or type=position/position, never bare UUID strings. A current retry or validation row awaiting its own external result must be the waiting target too; do not attach the new wait to a completed parent or an earlier failed attempt. Use the latest returned activePlan IDs/order. waitingItemTarget may identify the same unfinished current row or a later row; omit it when waitingItem defines a new row. If both targets accidentally identify the current row and a complete waitingItem is supplied, the helper safely appends that new row after the current item. It carries the returned facts without matching or interpreting item labels. It does not start, stop, retry, interpret, or otherwise change external work. Do not call it when the domain tool failed or returned no externalWaitId.
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": {
"externalWaitId": "<externalWaitId>"
},
"name": "record_external_wait_in_plan"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| planId | No | Optional plan UUID. In the current conversation, omit planId unless you already have the actual plan id from get_active_plan or a wake message. Never pass a plan item id here; target plan items through target.itemId or target.position. | |
| evidence | No | ||
| externalId | No | Optional assertion against the stored hook identity. Prefer externalWaitId alone. | |
| revisionId | No | ||
| waitingItem | No | Waiting-row fields for a newly inserted row or intentional overrides for a distinct existing waitingItemTarget. When this defines a new row, omit waitingItemTarget. Omit waitingItem when waitingItemTarget already identifies the complete future row. | |
| externalKind | No | Optional assertion against the stored hook identity. Prefer externalWaitId alone. | |
| conversationId | No | Optional conversation UUID. Omit this field to use the current MCP conversation context; never pass placeholders such as `current`. | |
| externalWaitId | Yes | The durable external wait id returned by the same domain-tool result. | |
| sourceExternalId | No | ||
| currentItemTarget | No | A structured target object, never a bare UUID or number. Use {"type":"id","itemId":"<actual item UUID returned by get_active_plan>"} or {"type":"position","position":3}. This identifies the visible plan item advanced by the domain tool. Omit to use the current actionable item. After adding a retry row, use that current retry row, not its completed parent. | |
| waitingItemTarget | No | A structured target object, never a bare UUID or number. Use {"type":"id","itemId":"<actual item UUID returned by get_active_plan>"} or {"type":"position","position":3}. The unfinished item whose completion requires this external result. Omit this selector and waitingItem to reuse an explicitly selected unfinished currentItemTarget as the waiting row. For a current retry/validation row, target that same unfinished row; do not target its completed parent or a previous failed attempt. Otherwise choose a later visible row when the current launch step is complete. Read IDs and order from the latest returned activePlan. Omit when waitingItem defines a new row. | |
| currentItemOutcome | No | ||
| currentItemEvidence | No |