MCP Task Orchestrator · Field guidePlate 2 of 10
Every work item with a lifecycle sits in one of five roles. (A schema with lifecycle: none gives its items no role and no transitions.) Agents never edit status directly. They call advance with a trigger, and that call is where the server checks claims, dependencies and required notes.
start passes it. Every move into work, review or terminal except cancel also waits for the item's blockers, and entry into work takes its resource leases. Two triggers are not drawn: complete jumps from queue, work or review straight to terminal and checks the required notes of every phase, and cancel jumps to terminal from any role that is not terminal, blocked included, with no note or dependency check. Ownership and seat checks still apply to every trigger an agent sends, cancel included.A simplified model of the server's rules for one item, using the 4.0 error codes and messages. The gates run in order: transition table, dependencies, notes. Fire triggers in any order, tick the blocker, and read what comes back. The highlighted station above follows along.
type feature-task · no status label
| Trigger | From | To | Gate |
|---|---|---|---|
start | queue, work or review | the next role on the line | Dependencies satisfied, then required notes of the current phase. Entry into work also takes the item's resource leases. |
complete | queue, work or review | terminal | Dependencies satisfied, then required notes of every phase. A blocked item must resume first. |
block / hold | queue, work or review | blocked | No dependency or note check. Invalid from blocked. Saves the previous role and a reason. |
resume | blocked | the saved role | Dependencies satisfied when the saved role is work or review, plus the lease when it is work. Back to queue is not gated. |
cancel | queue, work, review or blocked | terminal | No dependency or note check, but ownership and seat still apply. Sets the status label to cancelled. |
reopen | terminal | queue | No dependency or note check. A terminal parent goes back to work. |
The gates run in a fixed order and the first to fail answers: claim ownership, seat, the table above, dependencies, notes, leases. Entering terminal also clears the item's claim. To see which gate would answer without sending anything, read items_read select="context": gateStatus.canAdvance and, when false, gateStatus.blockedBy (table, dependency, note or lease).
block and hold take a reason: awaiting_decision (with the decisionId of an open decision), dependency, resource or manual (the default). Reads report it, and an awaiting_decision block reports resumable once its decision is no longer pending. Answering a decision never resumes the item: someone still sends resume.
The role is what the server reasons about. Alongside it, each transition sets or clears a status label: display text for people and dashboards. The five roles never change. The labels can be renamed per project.
| Trigger | Default label |
|---|---|
start | in-progress. A start that lands in terminal uses the complete label. |
complete | done |
block | blocked |
hold | none, so the item keeps its label while it enters blocked |
cancel | cancelled, unless you configure another |
resume | none, so the label is cleared |
reopen | none, so the label is cleared unless you configure one |
| a terminal cascade | done (the cascade key) |
| a start or reopen cascade | the start or reopen label |
status_labels: start: "working" complete: "finished" block: "on-hold" cancel: "dropped" cascade: "auto-completed"
An explicit label wins. With none configured, entering blocked keeps the label the item has and any other transition clears it. The label comes back on every transition result and on item queries. Filter and gate on the role. Show the label.
Every failure carries a kind that says whether retrying can help, and a code to branch on. An agent never has to parse the message text.
detail, such as a gate's missing notes or the blockers of a dependency, and a fix sentence for codes that define one. A claim_held error names the item and when the claim expires, never the holder. A gate error does not heal on its own: fill the named note, finish the blocker or resume the item, then send the call again.{
"ok": false,
"error": {
"code": "claim_held",
"kind": "transient",
"message": "...",
"detail": { "itemId": "550e8400-...", "expiresAt": "2026-10-16T13:15:00Z", "retryAfterMs": 420000 },
"fix": "...",
"retryAfterMs": 420000
},
"meta": { "reqId": "..." }
}
A one-element write without atomic that fails answers partial_failure, with this error object at data.results[0].error.
Each element of a write call may carry an idempotencyKey. The server records a committed element for 24 hours per principal and tool and returns its stored result again (replayed: true) instead of running it twice. The same key with a different element is idempotency_mismatch.
No response arrived, such as a timeout: resend with the same key. A committed element is recorded, so the retry returns its stored result. An element that failed with a gate, dependency or other runtime error is not recorded and runs again; only an invalid_request or unknown_parameter rejection is recorded and replayed.