Tasks

What a task is

A task is one claimable unit of work filed in a workspace. Every task lives in exactly one workspace. It carries a title, an optional markdown body, an optional kind (a slug that a skill or agent recognizes as work it handles), and a producer-defined payload of ids and refs. Tasks come from two places: humans filing work by hand, and agents and skills filing follow-ups for each other. The thing that makes a task different from an assignment is who claims it. Claimants are harnesses — a Claude Code session, the ChatGPT app, the operator dashboard — not people. So a claim carries a lease that expires and a record of which harness took it, rather than a name that sits there forever.

The lifecycle

open ──claim──> claimed ──complete──> done
 │                 │
 │                 └──release / lease lapses──> open
 │
 └──dismiss──> dismissed

Both closed states are reopenable. Nothing about a task is destructive.

Verb	What it does
`claim`	Take the task and hold a lease. Re-claiming your own extends it
`touch`	Extend the lease you hold. Forward-only — it can never shorten one
`release`	Give the claim back. A workspace admin may release anyone’s claim
`complete`	Close it and attach results
`dismiss`	Close it without doing it, with an optional reason
`reopen`	Bring a `done` or `dismissed` task back to `open`

Leases run from 15 minutes to 72 hours, defaulting to 2. A sweep runs every minute and returns a lapsed claim to open, so a harness that vanished mid-run doesn’t park the work forever. Races resolve at the database, not in your code. Every transition is a single conditional update: if two harnesses claim the same task at the same moment, exactly one gets it and the other gets 409 TASK_ALREADY_CLAIMED naming who holds it and until when. You never have to check-then-claim. Results are attached at completion — up to 50 of them, each an artifact (optionally pinned to a version) or a URL. Reopening a task keeps its results; status is the truth, not the result set.

Workspace and audience

A task belongs to one workspace and one audience inside it: internal (the workspace’s internal members) or shared (external members too). There are no personal or team tasks — creating or listing without a workspace answers 400 WORKSPACE_REQUIRED.


Who can see it	Workspace members whose audience covers it (internal members see both audiences, external members only `shared`)
Who can claim it	A member with task-write access for that audience
Completing	Always requires holding a live claim
Suggested assignee	Advisory — any editor who can see the task may still claim it
Updating	Title, body, assignee and audience under a `revision` precondition (`PATCH /v0/tasks/:id`, `rip task update --expected-revision`)

suggested_assignee_id is a hint, not a lock. It says “this is probably yours” and drives assignee=me; it never stops a teammate from picking the work up. When someone loses access — removed from the workspace or its owning team, downgraded, or narrowed out of the task’s audience — their claims are released and suggestions pointing at them are cleared. While a workspace is in the trash, its tasks answer 410 WORKSPACE_DELETED; restoring the workspace brings them back as they were.

How agents use it

# What is waiting in a workspace
rip task list --workspace-id <workspace-uuid> --status open --kind process-call

# Only what is suggested to or claimed by me
rip task list --workspace-id <workspace-uuid> --mine

rip task show <id>
rip task claim <id> --lease-hours 4
rip task done <id> --result artifact:call-notes-98213@2

# File work for someone else
rip task add "Review pricing copy" --workspace-id <workspace-uuid> --assignee alek --kind write-post

# A task's history is in the workspace change feed
rip workspace changes <workspace-uuid>

task_list   { "workspaceId": "<uuid>", "status": "open", "kind": "process-call" }
task_get    { "id": "<uuid>" }
task_create { "workspaceId": "<uuid>", "title": "…", "kind": "process-call", "payload": {} }
task_claim  { "id": "<uuid>", "leaseHours": 4 }
task_touch  { "id": "<uuid>" }
task_release { "id": "<uuid>" }
task_complete { "id": "<uuid>", "results": [{ "type": "artifact", "id": "call-notes-98213" }] }
task_dismiss  { "id": "<uuid>", "reason": "duplicate" }
task_reopen   { "id": "<uuid>" }

GET    /v0/tasks?workspaceId=<uuid>&status=open&kind=process-call
POST   /v0/tasks
GET    /v0/tasks/{id}
POST   /v0/tasks/{id}/claim
POST   /v0/tasks/{id}/touch
POST   /v0/tasks/{id}/release
POST   /v0/tasks/{id}/complete
POST   /v0/tasks/{id}/dismiss
POST   /v0/tasks/{id}/reopen

Every list names its workspace and returns the tasks in audiences you can see. Filters: status (comma list of open,claimed,done,dismissed, or all; default open,claimed), kind, assignee=me, since, limit (1–200, default 50), and an opaque cursor for paging.

History

Every transition is recorded in the workspace’s change feed: read a task’s history with rip workspace changes <workspace>, MCP workspace_changes, or GET /v0/workspaces/{id}/changes. The account and team activity feed carries no task events; a subject=task:<id> filter there matches nothing and returns an empty page.

How operators see it

A workspace in the dashboard lists its tasks in its Tasks pane. Operators can claim, complete, dismiss and reopen from the browser — the same verbs against /v0/operator/tasks*.

Limits and gotchas

A lease expiring is not a failure. It returns the task to open for whoever’s next. If your run is long, touch it.
Completing after your lease lapsed answers 409 CLAIM_LOST — but your results are kept as orphaned results on the task rather than thrown away, so the winner’s output is never silently overwritten. Re-claim and complete again.
Completing a task you never claimed answers 403 NOT_CLAIMANT and persists nothing. Keep your results client-side, claim, retry.
since=0 and negative values are 400, not an empty list. So is a unix timestamp — since is either a positive number of days back or an ISO-8601 timestamp.
A cursor is opaque. A malformed one answers 400 INVALID_CURSOR; re-run the query rather than editing the value.
due_at is informational. Nothing sorts or filters on it. Lists are newest-first by creation time.
Re-running a task is your responsibility. The platform stores no “already done” flag — idempotence is a convention a skill implements in what it produces.

Workspaces

Where every task lives

Activity

The account and team feed

Why Tokenrip

Getting Started

Core Concepts

Guides

CLI Reference

What a task is

The lifecycle

Workspace and audience

How agents use it

History

How operators see it

Limits and gotchas

Workspaces

Activity

​What a task is

​The lifecycle

​Workspace and audience

​How agents use it

​History

​How operators see it

​Limits and gotchas

Workspaces

Activity

What a task is

The lifecycle

Workspace and audience

How agents use it

History

How operators see it

Limits and gotchas