update_task

Category: tasks
Access: write
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Updates one task or note in place. Only the supplied non-empty fields change, so it is the everyday tool for moving work through status and section, retitling, reprioritizing, rescheduling, or rehoming content across projects.

Arguments

Required: task_id.

Optional: description, due_date, notes, parent_id, priority, project, recurring, reminder_at, section, status, title, type.

task_id: UUID of the task to update (required).
description: New main task/note body.
due_date: YYYY-MM-DD or "CLEAR" to remove.
notes: New auxiliary/internal notes or "CLEAR" to remove.
parent_id: Parent UUID or "CLEAR" to remove. Note: The named parent must be visible to the caller; CLEAR detaches.
priority: low | medium | high | critical.
project: Project tag or "CLEAR" to remove. Note: Moving to a named project or to untagged (CLEAR) each needs the write grant for the destination.
recurring: JSON config or "CLEAR" to remove.
reminder_at: ISO datetime or "CLEAR" to remove.
section: inbox | today | next | someday | waiting.
status: not_started | in_progress | done | archived | cancelled.
title: New title. Note: Empty strings are ignored; only non-empty values are applied, except CLEAR which nulls the field.
type: task | note.

Result

JSON object with updated (the task UUID) and fields (the applied field names plus updated_at).

Boundaries

The target task must be visible under the caller's project grants; anything else answers Task not found, never distinguishing missing from foreign. Project and parent moves are each grant-checked at the destination.

Lifecycle / side effects

Applies the field changes through the canonical mutation path and records an audit/history event. Status moves (including to archived or cancelled) preserve history per the no-delete invariant.

Errors

Missing task_id is rejected by validation. Unknown arguments are rejected (strict validator). Bad enum, date, or recurrence values are rejected. Unknown or out-of-scope tasks and parents answer not-found. A call with no effective fields answers No fields to update. Failures leave nothing half-applied (atomic).

Example

{
  "status": "in_progress",
  "task_id": "<uuid>"
}

Result shape:

{
  "fields": [
    "status",
    "updated_at"
  ],
  "updated": "<uuid>"
}