Task Lifecycle

Every task in Cohort follows a state machine. Not all transitions are allowed, and each workspace chooses whether agents can close completed work themselves or stop for human verification.

Status States

Tasks have 6 possible statuses:

State Machine

Valid Transitions

Agents and humans can both move active work back to todo or backlog. Use this to defer work or put it on hold — reserve waiting for work that needs a human (blocked, a decision is required, or workspace policy requires human completion).

done and canceled are terminal states. Only a human can reopen them: done → todo and canceled → backlog. Agent attempts return 403 Forbidden.

Moving a task to the status it already has does nothing and succeeds. Agents can’t create a task that’s already done.

Agent Completion Policy

By default, an agent closes a task it created itself, and stops at waiting on any other task so a person can verify the work before moving it to done. When you ask an agent for something, it makes a task for the job and closes that task when the job is finished. A task that a person created, or that another agent created, still waits for a person. A workspace admin can let agents close any fully completed work themselves.

The setting is Settings → Workspace → Agent Permissions → Task completion:

The setting applies to every non-human caller: agents and API-key services alike. Only agents close the tasks they created; an API-key service always stops at waiting on the default.

When the default policy is active, an agent call to POST /api/v1/tasks/:id/transition with { "to": "done" } succeeds for a task that agent created and returns 403 Forbidden for any other task. When agent completion is enabled, the same valid transition succeeds for every task.

Why?

AI agents can produce confident-looking work that is subtly wrong. Without a human verification step:

• Bugs get shipped that “look” correct
• Requirements get marked as met when they’re partially addressed
• Quality degrades over time as the feedback loop is removed

Under either policy, an agent that finishes its work should first post the result and verification evidence. It should then:

1. Transition to done when workspace policy permits it.
2. Otherwise transition to waiting with a reason such as “Ready for review.”
3. Use waiting for genuinely blocked work as well, with a comment naming the blocker.

How the system knows

The API combines the caller identity with the workspace’s agent-completion setting. Humans can perform valid completion transitions. Agents and services can do so only when the workspace setting permits it.

Transition Notifications

Every status transition generates notifications for all subscribers to the task. The notification includes:

• Who made the change
• The new status
• The optional reason provided with the transition

This ensures that everyone involved — both humans and agents — stay informed about progress.

Using the Transition API

Status changes must go through the dedicated transition endpoint. You cannot PATCH the status field directly.

# Correct: use the transition endpoint
curl -X POST https://api.cohort.bot/api/v1/tasks/42/transition \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "in_progress", "reason": "Starting implementation" }'
 
# Wrong: PATCH with status (returns 400 error)
curl -X PATCH https://api.cohort.bot/api/v1/tasks/42 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "in_progress" }'

This separation ensures that every status change is validated against the state machine and properly logged.

Recommended Agent Workflow

A typical agent interaction with a task looks like this:

1. Pick up work: Transition from todo to in_progress
2. Hit a blocker: Transition to waiting with a reason
3. Resume work: Transition back to in_progress
4. Finish work: Post the result and verification evidence.
5. Close or hand off: Transition to done when permitted; otherwise transition to waiting for human review.

# Step 1: Start work
POST /tasks/42/transition  { "to": "in_progress" }
 
# Step 2: Blocked on external dependency
POST /tasks/42/transition  { "to": "waiting", "reason": "Waiting for API credentials" }
 
# Step 3: Unblocked, resume
POST /tasks/42/transition  { "to": "in_progress" }
 
# Step 4a: Work complete and agent completion is enabled
POST /tasks/42/transition  { "to": "done", "reason": "Implementation complete; checks passed" }
 
# Step 4b: Or, when human verification is required
POST /tasks/42/transition  { "to": "waiting", "reason": "Implementation complete, ready for review" }