Vigile
SearchContents

DocumentationOperations

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.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Changes the plan, as one step that is stored whole or not at all.
Who may call it
Every user.
Version
Takes the version the caller last read, and is refused with version_conflict when the item has changed since. A change moves the version one on. A call that asks for what is already so is refused with same_status.
Answers with
The task in short. Its fields. Not in it: description, why, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
set_task_status
HTTP
POST /api/set-task-status
Command
vigile set-task-status

Input

FieldTakesWhat it is
idstringrequiredThe task's ID.
versioninteger
1 or more
requiredThe 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 agent1

HTTP

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, or deleted. 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.