tasks_update
Update a task's fields, append a comment, or upload and attach authorized file references. comment adds a comment without changing other fields. Status transitions to 'done' automatically stamp completed_at. Closing a task (status: 'done') takes a resolution_note — it's persisted as a comment AND included in the resolution email/webhook so the reporter knows what was done. Omitting it when transitioning to done returns a non-blocking suggestions entry asking for a resolution note.
Progress belongs in status_note (and health), not a comment per step. The three fields have distinct jobs: description is the living document (intent and contract, rewritten as the truth changes), status_note is the current state (overwritten each update, so one read tells you where things stand), and comments are append-only EVIDENCE — commit hashes, verification output, links. Appending status as comments is what makes a long-lived task unreadable: the thread renders oldest-first, so a reader meets the superseded version before the live one. Overwriting status_note loses nothing; the old value is kept in the activity log.
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": {
"project_id": "<project_id>",
"task_id": "<task_id>"
},
"name": "tasks_update"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | New subsystem tag, or empty string to clear. | |
| type | No | New type. Empty value leaves the type unchanged. Custom labels are supported. vision — why the organization exists. philosophy — a belief guiding trade-offs, including why it matters. directive — a rule or instruction, including what it supersedes. decision — a steer from the person who owns the project: their words, what it changes, what it replaces, the work it governs. sop — how to carry out a recurring job. spec — what to build and its acceptance criteria. roadmap — direction and outcomes for work ahead. epic — a larger outcome grouping related tasks. task — a concrete piece of current work. bug — behavior that needs correction. report — an observation, incident or customer finding. principle — a reusable rule for making decisions. learning — a lesson supported by experience or evidence. supplier — facts about an external service or supplier. content — a draft or plan for published material. policy — a standing rule governing operations. stance — a position on a subject and its reasoning. When the person who owns the project changes direction, parks or picks something, or overrules a plan, record it as a decision the same day, quoting them. | |
| title | No | New title. | |
| author | No | Optional display label to attribute the comment to (e.g. "ci-bot", "support-agent"). Lets many entities that share one account self-identify on the thread. Only used when `comment` is supplied; defaults to the account. | |
| due_at | No | Unix timestamp (ms), or null to clear. | |
| health | No | Structured progress signal independent of `status`; for example, a task can be in_progress and off_track. Omission means nobody has assessed it, while null clears an existing assessment. | |
| labels | No | Replacement labels list. Completion guidance is explicit-label-only; in v1 requires-deployment is the machine-enforced gate. | |
| status | No | Work records only. New status. 'blocked' represents work awaiting external action; 'needs_review' represents completed work awaiting sign-off. | |
| comment | No | If supplied, appends a comment with this body. | |
| task_id | Yes | The task ID. | |
| assignee | No | New assignee. | |
| priority | No | New priority. | |
| parent_id | No | New parent task ID, or empty string to detach. A task may not be its own parent. | |
| project_id | Yes | Project ID (UUID), subdomain, or slug, resolved server-side; 'default' is the organization's shared task board. | |
| shipped_in | No | The deploy/version in which this work shipped, represented by the deploy object tag such as "v7". It exposes child reports for review-for-closure. An empty string clears it. | |
| waiting_on | No | Explicitly waiting for human input, a product decision, or an external dependency. status_note records what is needed; clear with null or an empty string when resolved. Does not change assignee or status. | |
| attachments | No | Replacement task attachments as sw.fs paths. An empty array clears them. | |
| description | No | New description. | |
| status_note | No | Current state in one short paragraph, overwritten rather than appended as work progresses. Prior values remain in the activity log. The 2000-character cap distinguishes this status line from the living `description`; an empty string clears it. | |
| relationship | No | One typed relationship from this task to another task in the same project. | |
| superseded_by | No | Task ID of the row that replaces this one (a newer spec, a corrected directive). Empty string clears it. | |
| guidance_review | No | Review of the exact current guidance draft, identified by guidance_version.draft.content_revision. Editing and reviewing are separate calls. Records the reviewing account; human approval is separate. Later edits remain drafts against the reviewed version. | |
| resolution_note | No | Short outcome explanation for a task closing with status='done'. It persists as a comment and appears in the resolution notification email and webhook payload. | |
| guidance_context | No | Optional guidance used or a scoped exception, recorded during a normal task update. Older basis remains visible beside current guidance. Exceptions inherit through parent/child links and need reassessment when guidance changes; they do not rewrite the SOP. Links and activity are recorded automatically. | |
| deployment_version | No | Successful production version number of deployment_project_id, verified before task update or closure and available from project_deploys. | |
| upload_attachments | No | Native connector files to upload and append in this call. The top-level array contains authorized file-reference objects identified by openai/fileParams metadata. Each file is stored privately under /tasks/{task_id}/attachments/<name>; saved sw.fs paths are returned and appended. Binary bytes stay outside conversational context, and path/base64 strings are rejected. | |
| deployment_project_id | No | Accessible project whose successful deploy proves the work is live: ID, subdomain, or slug. It may differ from the task-owning project and always does on the deploy-less shared board. The task's project is the default. | |
| remove_relationship_id | No | Identifier of one explicit relationship to delete. A parent_id-backed child_of edge is removed by clearing parent_id instead. |