Tasks

The six task tools - the dependency-aware ready queue and lease-based claiming that lets parallel agents divide work safely.

Tasks are how agents hand work to each other. A task is ready when it has no unfinished blocker; tasks_ready returns exactly those, so an agent asking "what can I do now?" never has to reason about the dependency graph itself.

How claiming works

Claiming is the concurrency control. Two agents that both see the same ready task will both try to take it, and exactly one wins:

1. tasks_claim atomically moves a ready task to in_progress and stamps a lease (default 900 seconds). The loser gets an error naming the holder.
2. Re-claiming a task you already hold refreshes the lease - that is the heartbeat for long work.
3. An expired lease is reclaimable by id - but the task stays in_progress, so tasks_ready does not show it. Only releasing it (by hand, or by the gardener's session reaper expiring the dead holder's session) sets the status back to open and returns it to the queue. See the two clocks.
4. tasks_release, closing the task (tasks_update to done/dropped), or session_end frees the claim.

A lease is not a lock on the files - it is a coordination signal between cooperating agents. Nothing stops a determined agent from working on a task it did not claim; the point is that well-behaved agents do not collide.

Plan steps are not queue items

A task created with plan=<slug> is a step of a plan, and is excluded from the default tasks_ready and tasks_list. That keeps a twelve-step plan from burying the handful of tasks that are actually loose work. Pass plan=<slug> to either tool to see that plan's steps instead.

Results and refusal modes

Every successful task mutation returns the resulting task row, including its id, status, dependency state, claim holder, and lease fields when present.

An expired claim is not reported as live. Claiming that task by id succeeds at the exact lease boundary, even while its status remains in_progress.

tasks_add

Add a task to the dependency-aware ready queue. depends_on lists task ids that must finish first (done or dropped unblocks); each must exist and must not create a cycle. The task is 'ready' once it has no open/in_progress blocker.

tasks_update

Update a task: change status (open|in_progress|done|dropped), edit title/body, or add dependencies. Moving to done/dropped closes it and unblocks its dependents. A task another session holds via a live claim is locked to its holder: updating it fails with 'already claimed' until the lease lapses or the holder releases it.

tasks_ready

List the actionable (ready) tasks for a project -- open tasks with no unfinished blocker -- oldest first, plus the blocked tasks with their still-open blockers. By default plan-step tasks are excluded; pass plan=<slug> to list that plan's steps instead.

tasks_list

List a project's tasks, optionally filtered by status, newest first. By default plan-step tasks are excluded; pass plan=<slug> to list that plan's steps instead. Pass id=<task id> to load a single task by its globally-unique id (a direct lookup that ignores project/status/plan and needs no session scope).

tasks_claim

Atomically claim a task for the current session, moving it to in_progress with a lease. A refused claim names its cause: held by another live claim ('task already claimed'), waiting on unfinished dependencies ('task blocked', naming the blockers -- finish those first), or already done/dropped ('task closed'). Re-claiming a task you already hold refreshes (heartbeats) the lease; a task whose lease has expired can be reclaimed. Release it with tasks_release or by closing it (tasks_update done/dropped); session_end releases all of a session's claims.

tasks_release

Release a task the current session holds, reopening it (status back to open, claim cleared) so another agent can claim it. Only the current holder may release.