Tasks

Tasks are durable personal task records stored in Anyy state. They are useful for follow-up work, reminders to the assistant, and lightweight task lists that need to survive the current conversation.

Tasks are not memory. Use memory for stable facts and preferences, and tasks for work items that can be completed, cancelled, blocked, or filtered by due date.

Task Tools

The model-visible task tools live in the tasks toolset:

Tool	Purpose	Policy
task_create	Create a durable task.	Audited config-low change.
task_list	List durable tasks.	Direct read.
task_update	Update task fields.	Audited config-low change.
task_complete	Mark a task complete.	Audited config-low change.

Task tools do not require approval by default, but create, update, and complete are audited as task changes.

Task Fields

A task record can include:

Field	Meaning
title	Required when creating a task.
description	Optional longer task body.
status	pending, in_progress, blocked, completed, or cancelled.
priority	low, normal, high, or urgent.
due_at	Optional RFC3339 due time.
labels	Optional labels for filtering.
metadata	Structured metadata for runtime use.
session_id / turn_id	The session and turn that created or changed the task.

Completed tasks keep completed_at, created_at, and updated_at timestamps.

Create And Update

task_create requires only a title:

{
  "title": "Review the provider fallback config",
  "priority": "high",
  "labels": ["docs", "config"]
}

task_update requires id and at least one field to change:

{
  "id": "task_123",
  "status": "blocked",
  "description": "Waiting for provider credentials."
}

task_complete requires id and can include a short note:

{
  "id": "task_123",
  "note": "Provider fallback behavior was documented."
}

Listing And Filters

task_list can filter by:

Filter	Meaning
status	Return one task status.
include_completed	Include completed tasks; default is false.
priority	Return one priority.
due_before / due_after	Bound due dates.
query	Search task text.
labels	Match labels.
limit	Maximum result count, capped at 50.

Scope

Task tools resolve the current runtime scope from the active session. A channel, TUI, or gateway session sees tasks through the same role/workspace scope rules used by the resident runtime.

If the session scope is unavailable, task operations fail instead of falling back to unscoped writes.

Practical Guidance

• Use tasks for follow-up work, not stable user facts.
• Use due_at only when there is a real date or time; vague urgency belongs in priority or the task description.
• Use labels for reviewable buckets such as docs, ops, or waiting.
• Use cron or reminders when the task must actively run or notify at a time.

For scheduled work, see Cron. For durable preferences and assistant notes, see Persistent Memory.