Update plan item
update_plan_itemUpdates one user-visible plan item. The target is required and must be {type:"id", itemId} or {type:"position", position}; ambiguous itemId/position top-level shapes are intentionally not accepted. Use this before or after each major action in a plan-driven task so progress does not stay stuck while work continues. When working in the current conversation, omit conversationId and planId; never pass placeholders such as current, this, or active. If you include conversationId, it must be the real UUID. If you include planId, it must be the plan UUID, not a plan item id. Keep exactly one visible plan item in_progress at a time. Plan items progress in visible order: before marking a later item in_progress, waiting, completed, or blocked, resolve earlier visible items as completed, blocked, skipped, or removed. For ordinary handoffs between existing rows, use update_plan_items with the current item resolved first and the next item started second in the same ordered batch. Never send only the next-item update while another row is in_progress. Completed items are historical attempts: preserve their outcome and use the earliest unresolved row or add_plan_item for new linked follow-up work. Omitting outcome does not clear an existing outcome. If a real attempt finished without satisfying its completion criteria, status="completed" may carry outcome.status="unsuccessful" or outcome.status="partial" and the external result belongs in patch.evidence. Follow-up items reference that item with parentItemId or dependsOnItemIds. Do not copy an external resource status into outcome.status; put external statuses in patch.evidence. Do not target a future position to create the next validation row. update_plan_item only updates existing items; if the relevant domain tool has not returned a new external id yet, execute the active item first instead of creating a waiting validation row. After the relevant domain tool has returned a new external id, use update_plan_item only for the existing current row, then call add_plan_item for the waiting validation row. For external waits, use patch.status="waiting" with patch.waitReason="waiting_for_external_event" and put domain evidence in patch.evidence, for example externalKind and externalId. Use waitReason="waiting_for_user" before asking the user for a decision. External observations from hooks do not update the plan by themselves; when a terminal external observation arrives, explicitly update the plan item if the observation satisfies or changes the completion criteria.
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": {
"target": "<target>",
"patch": "<patch>"
},
"name": "update_plan_item"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| patch | Yes | ||
| 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. | |
| target | Yes | ||
| conversationId | No | Optional conversation UUID. Omit this field to use the current MCP conversation context; never pass placeholders such as `current`. |