assign_task

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

Purpose

Sets who should do a task or note. Assignment is a coordination hint only: the assignee value is stored verbatim and grants nothing, while the calling principal is recorded alongside as shared_by.

Arguments

Required: task_id.

Optional: assignee.

task_id: UUID of the task to assign (required).
assignee: Who should do it (free-form). Note: Free-form verbatim hint, never authority. Empty or omitted unassigns, clearing both assignee and shared_by.

Result

JSON object with task_id, assignee (string or null when unassigned), and shared_by (the calling principal, or null when unassigned).

Boundaries

The caller must reach the task under their project grants; anything else answers Task not found. The assignee value itself is never scope-checked.

Lifecycle / side effects

Applies the assignment through the canonical mutation path and records an audit/history event. Reassigning overwrites the previous hint; unassigning clears both coordination fields while history is preserved.

Errors

Missing task_id is rejected by validation. Unknown arguments are rejected (strict validator). Unknown or out-of-scope tasks answer not-found. Failures leave nothing half-applied (atomic).

Example

{
  "assignee": "fred",
  "task_id": "<uuid>"
}

Result shape:

{
  "assignee": "fred",
  "shared_by": "homer",
  "task_id": "<uuid>"
}