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, complete the current item, wait for the successful result, then start the next existing item with a separate update_plan_item call. 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.
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`. |