set_task_status
Change a task's status: draft, open, in_progress, paused, in_review, done or cancelled. Use in_progress only while implementation is actively under way. When implementation is complete, use in_review through review, merge, release and post-release verification, including after review ends. Use done only once the outcome is shipped and verified, and paused when work stops unfinished. Moves the rules do not allow are refused, and the error says what is in the way and what to do. A task container cannot be cancelled while it contains tasks in_progress or in_review at any depth; finish them or remove the contains links first. A task cannot be started or marked done while something it depends on is unfinished. Starting an unassigned task assigns it to you; only an assignee may start assigned work, so taking it over requires changing its assigned-to link first. A task already in progress cannot be started again, so two agents cannot take the same task.
- It
- Changes the plan, as one step that is stored whole or not at all.
- Who may call it
- Every user.
- Version
- Takes the
versionthe caller last read, and is refused withversion_conflictwhen the item has changed since. A change moves the version one on. A call that asks for what is already so is refused withsame_status. - Answers with
- The task in short. Its fields. Not in it:
description,why,links,timeline,created_at,created_by,updated_atandunchanged_since.gethas those. - MCP tool
set_task_status- HTTP
POST /api/set-task-status- Command
vigile set-task-status
Input
| Field | Takes | What it is | |
|---|---|---|---|
id | string | required | The task's ID. |
version | integer 1 or more | required | The version of the item you last read. The call fails with a conflict if the item changed since. |
status | "draft" | "open" | "in_progress" | "paused" | "in_review" | "done" | "cancelled" | required |
A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --id.
Example
The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.
Command line
vigile set-task-status --id WEB-005 --version 1 --status in_progress --as agent1HTTP
curl -s http://127.0.0.1:8700/api/set-task-status \
-H 'content-type: application/json' \
-d '{"id":"WEB-005","version":1,"status":"in_progress"}'MCP tool call
{
"name": "set_task_status",
"arguments": { "id": "WEB-005", "version": 1, "status": "in_progress" }
}The answer
{
"kind": "task",
"id": "WEB-005",
"title": "Total is wrong when a coupon is applied twice",
"type": "bug",
"status": "in_progress",
"priority": 9,
"value": null,
"size": null,
"version": 2,
"contained_in": ["WEB", "WEB-001"],
"depends_on": [],
"assigned_to": ["agent1"],
"is_assigned": true,
"is_next": false,
"is_waiting": false,
"waiting_for": [],
"has_problems": false
}
This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.
A call that is refused
vigile set-task-status --id WEB-004 --version 1 --status in_progress --as agent1
{
"error": {
"code": "rule_violation",
"message": "Task WEB-004 cannot be started: it is waiting for a dependency to finish.",
"rule": "unfinished_dependencies",
"blocking": [
{
"kind": "task",
"id": "WEB-003",
"title": "Payment form takes a card",
"status": "in_progress"
}
],
"actions": [
"Finish or cancel the items it depends on.",
"Or call remove_link with type \"depends on\" if the dependency no longer applies.",
"Or call list_next_tasks to pick work that can start now."
]
}
}
What it answers
The task in short, with its new status and its version, one higher. In the example the task was assigned to nobody, so starting it assigned it to the caller: assigned_to now names agent1.
Rules
- The move has to be one the table of moves allows.
- A task cannot be moved to the status it already has. For
in_progress, the refusal tells a second agent that the task is in progress, and whether it is assigned to that agent, to others or to nobody. - A task cannot be started or marked done while something it depends on is unfinished.
- A task cannot be marked done while it contains unfinished tasks, at any depth.
- A task cannot be started by someone it is not assigned to, while it is assigned to anyone.
- A task cannot be cancelled while it contains tasks in progress or in review, at any depth.
- Starting a task that is assigned to nobody assigns it to whoever starts it.
- A group does not close by itself when its tasks are done: someone sets it to done.
- Every status a task goes through is kept in its timeline, with when and by whom.
Errors
version_conflict: the task changed since it was read. The error holds it as it is now, in short.rule_violation:same_status,status_move_not_allowed,unfinished_dependencies,unfinished_contents,assigned_to_other,active_contents, ordeleted. Each names actions that would resolve it; some also name the items in the way.invalid_input: a status that is none of the seven.not_found: no task has that ID.
See also
Statuses and the rules of moving explains the rules. list_next_tasks lists what can be started.