What a task is
A task is one piece of work in a workspace. Every task lives in exactly one workspace. It carries atitle, an optional markdown body (the brief), two free tags (type and step), its labels, a producer-defined payload of ids, and its links: the files and pages the work uses and what came of it. It names who it is for, who reviews it, who created it and who completed it.
A task is the record of the work. The ask, its files, every review round, every message in its thread, the action and the result stay on one task, and its timeline tells the story in order.
Tags and labels
Two tags let a workspace’s agents run their own workflow on top of tasks. Tokenrip stores them, filters on them and never interprets them, except on a task of a job with task definitions, where they are the job’s own types and steps.
Both use the same grammar: lowercase letters, digits,
- and _, starting with a letter or a digit, at most 64 characters. Set them when you create a task and change or clear them (null) with an update. type can also be given on a new proposal or report, or on a proposal for a task that has none. Tokenrip changes step only when an approval applies a then (below), fills it under a job with task definitions, or clears it when the task closes. List and start filter on both. The old field kind is refused as an unknown field (INVALID_FIELD), with type among the accepted fields.
A step says where open work stands: To do at step draft, Doing at step draft, In review at step draft. A closed task has no step. Complete and cancel clear it (the change feed’s task.completed and task.cancelled record the step it was at), a report is born Done without one, and an update that names a step on a Done or Cancelled task is refused INVALID_FIELD on step: reopen it first. A reopened task goes back to To do with no step, except a proposal cancelled In review, whose new round restores the step it was proposed at.
Labels are your person’s own words for grouping work: client:acme, campaign.q4, urgent. Where a task has one type and one step, it holds a set of labels, at most 20. A label is lowercase letters, digits, -, _, : and ., starting with a letter or a digit, at most 64 characters; Tokenrip reserves no prefix and never interprets them. Set them when you create a task or report one, and change them on an update with addLabels and removeLabels (more than 20 is refused with INVALID_FIELD on labels). Every task read carries labels, sorted. The list’s labels filter takes a comma list and returns the tasks with all of them (labels=client:acme,campaign.q4). Labels gate nothing.
A task may also name the job it serves: standing work in the workspace, such as founder-posts. Pass the job’s name as job when you create, report or propose a new task, set it on an update (null clears it), filter the list with job=<name>, and start the job’s next task by tags with job and step. Every task read carries job as { id, name }, or null. The job must be live: an unknown or archived name is refused with INVALID_FIELD on job.
Under a job with task definitions, a task’s type is one of the job’s types (filled when there is only one) and its step one of its definition’s steps (the first main step when none is given); another word is refused with INVALID_FIELD and the valid values in available. Reading the task, or starting it, carries its workflow: the step it is at, that step’s instructions and the next main step (Get Task).
Three ways in
- Ask. A person or an agent files a task, for a person or for one agent, optionally with a reviewer, tags, links and a parent task. The assignee is advisory: any editor who can see the task may start it.
- Propose. Before an agent acts outside the workspace (a post, an email, a booking), it proposes the action: the exact draft, the approve verb (“Post”, “Send”), optionally the files the draft is made of and the step an approval should move it to. The task waits In review for its reviewer. A proposal can also go on an existing task, to send a draft for review.
- Report. Work worth knowing that needed no approval is reported: a task born Done, with its result and result links. Later results go on the same task. Something you did outside Tokenrip is an output, not a report: record it on its task when it has one and on its own when it doesn’t. Don’t create a task only to record that something happened.
The lifecycle
Every write is recorded in the workspace’s change feed. Creating, editing, proposing, deciding and a new report take
why; moving a task along (start, stop, complete, cancel, reopen, a move in the queue) and a later result take it optionally, since the move records its own reason.
Rounds
Each proposal opens a round. A round is written when it opens and once more when it closes, and never otherwise. It records:- The proposal: its number (1, 2, … per task), the task’s
stepat the time, the proposer (a person or one agent), the approve verb,then, and the draft: text of at most 64,000 characters and up to 10 artifact versions (draftArtifacts), either, both or neither. - The decision: the verdict, when, by whom (or by which instructions version), the
thenit applied, any edits, and the comment posted with it.
Responses carry the task’s
latestRound (whole on a read of one task, { number, verdict } in lists) and its approvedRound: the round being carried out, with its final material, final.text and final.artifacts (per part, the approver’s edit, else the draft). Carry out exactly approvedRound.final. Get Task adds any earlier round whole with round=<n>.
Deciding a round
Every decision names the revision the decider read (
expectedRevision). A proposal replaced meanwhile bumped the revision, so the old decision is refused CONFLICT; a round already decided is refused TASK_NOT_IN_REVIEW, which carries task: its status and who it waits on now. decline and the old skip are refused, naming cancel: to say no, cancel the task (task_cancel, rip task cancel). The round closes cancelled, decided by whoever cancelled, and the reason is the task’s cancel reason.
A person’s saved edit. A person reviewing in the dashboard can edit the draft’s text and save it before deciding. The saved edit stays on the open round, so it is there when they come back, and every reader sees it as latestRound.savedEdit ({ text, savedBy, savedAt }, or null); rip task show prints it under Saved edit. An approval with no edits.text carries out the saved edit; one with its own edits.text carries out that text instead.
Sending back, withdrawing, cancelling or proposing again drops it. Only people save edits, in their own browser: an agent deciding a review sends its edit with the decision.
The versions a round uses
A draft names artifact versions, so the reviewer sees exactly what was proposed even after the file changes. Each draft artifact is linked to the task as context, and the versions a round names (its draft’s, and an approver’s edits) are kept for as long as the task exists, whatever the file’s history setting:- A whole-file update, an edit or an append that replaces a version in use keeps it.
- Keeping the last n versions and pruning skip versions in use; prune reports how many it kept as
keptInUse. - Deleting a version in use is refused
409 VERSION_IN_USE, naming thetaskandround. - Purging the artifact for good releases them; the round then reads the file as gone.
base: the same file in the latest earlier round at the same step. Diff with baseVersionId shows what changed since the last draft (rip artifact diff --version-id <v> --base <base>; rip task show <id> --round <n> prints the command).
Limits
A task holds at most 50 rounds (409 TOO_MANY_ROUNDS), so two agents cannot send a task back and forth forever. A proposer holds at most 200 open proposals per workspace (409 TOO_MANY_PROPOSALS).
Who it is for, and who reviews it
Every role on a task is a principal: a person (an account acting as itself) or one agent (one key on a person’s account). Responses nameassignee, reviewer, createdBy, completedBy, a round’s proposedBy and decidedBy, and a message’s author the same way:
agent is null for the person. agent.id is the agent’s handle in this workspace: name that agent in any task input as agent:<handle>, with a handle from the workspace load’s agents. You can also name yourself as me, an agent by its key id (agent:<key id>), and your own agents by name (agent:<name>); a refusal lists in details.candidates who you can name. agent.name is sent only for an agent on your own account; everyone else reads it by its person and harness (“alek’s agent · Codex”). mine means the principal is on your account, isCaller that it is exactly you. Key ids never appear.
- Assignee. A person: the task is theirs, and their own agents may pick it up. An agent: the task is that agent’s. Empty: anyone’s. Proposing never changes it.
- Reviewer. A person, an agent, or empty (any person who can edit tasks). It is the task’s reviewer when one is set; otherwise the one the proposer names; otherwise, for an agent’s proposal, the agent’s own person. A person’s proposal with no reviewer is unaddressed: any other person who can edit tasks may decide it. The reviewer may be the assignee, and is never the proposer of the open round (
400 INVALID_REVIEWER).
Nobody decides their own proposal. A person decides only from their own browser session: a browser an agent’s sign-in link signed in is refused
LINK_SESSION_FORBIDDEN. Anyone else is refused REVIEW_NOT_YOURS, which names the reviewer.
Whose turn it is
Every task response says two things for whoever reads it, worked out by the server: who the task waits on, and what the reader can do with it now.waitsOn.you is true when that is you. moves lists the verbs open to you now (start, stop, complete, cancel, reopen, propose, decide, report); a viewer gets none. A move that is refused carries the same two facts in task, so a refusal says who to ask rather than leaving you to try the next verb. Get Task has the fields.
What is my turn? List tasks with waiting=me (rip task list --waiting, task_list with waiting: "me"): the tasks that wait on you, approved work first, then reviews, then To do tasks for you. It is the list the workspace load gives under waiting, without loading the workspace.
Handing on. Who a task is for is also whose turn it is while it is To do, so the move that ends your part can say who is next:
- Stop takes
assignee(a person, an agent, ornullfor anyone) and acomment. The task goes back to To do for them, they are notified, and it shows in theirwaiting=me. Withoutassignee, it stays for whoever it was for. - A proposal’s next step can name who takes it:
thenAssigneebesidethen. When the proposal is approved, the task is at that step for them. The reviewer may change or clear the name when approving. With no name, the step is for whoever starts it.
Links
A task has onelinks array. Each link has a role and points at an artifact in the task’s workspace (optionally at a version) or at a URL:
A link input is
{ artifact, version? } (the artifact by id or page URL; a version page’s URL names that version; version is a number or a version id) or { url } (at most 255 characters). A link reads back as { id, role, artifact: { id, title, type, mimeType, version } | null, url, addedAt }. An artifact must live in the task’s workspace and, on a shared task, be shared (400 INVALID_LINKS); one in the trash is refused 410 DELETED and left out of reads until it is restored. A version is a pointer, not a use: if that version is deleted later, the link reads the file’s current version. Each target appears once per role (a target already linked is left as it is), at most 50 per call and 100 per role per task.
A task’s files
The task read (GET /v0/tasks/:id, task_get, rip task show) also lists files: every file the task links or names in a round, once, with how the task relates to it. made means the task proposed the file as new: a round names it at version 1 and that version was written by the round’s proposer. result means a result link names it. otherTasks counts the other tasks you can read that use the file, and onlyThisTask is true when no other task uses it at all. A file that is made and onlyThisTask was made for this task. When a task is cancelled, those files can go to the trash; after it is completed, they can move to the folder your workspace keeps finished work in. A file another task uses, and a result, stay where they are. Files in the trash are not listed.
The other way round, a workspace file lists its tasks: GET /v0/artifacts/:id, artifact_get and rip artifact get carry tasks (at most 20, open ones first in queue order, then finished ones, the latest first, each with made and result) and tasksTotal for a member of the workspace. The dashboard shows them as In N tasks beside the file’s folder.
The task’s thread
Each task has a thread of messages: markdown of at most 8,000 characters, a question, a requested change or an answer. A thread is not a status channel: the task’s own state already says where the work stands. The workspace’s chat is for everything that is not about one task (Threads and messages).- Who posts: anyone who can read the task, any role, viewers included.
- Who changes one: only its writer: the same agent key, or the person who typed it in the browser (never their agents’ messages). Anyone else is refused
403 MESSAGE_NOT_YOURS. An edit replaces the text and marks it edited; a delete removes the text for good and leaves a deleted marker at its position. - With a move: propose and decide take an optional
comment, posted in the thread in the same write, so nobody can take the task between a decision and its notes. A send back requires one. - No email. Messages land in the task’s timeline and the workspace change feed (
message.posted,message.updated,message.deleted); the event never carries the text. A message needs nowhy; one sent is accepted, not recorded.
rip message post --task-id <id>, rip message read --task-id <id>, rip message update <id>, rip message delete <id>. MCP: message_post, message_read, message_update, message_delete with taskId.
The timeline
A task’s timeline is its story, newest first. Get Task returns the newest 30 entries astimeline: { entries, nextCursor }; pass nextCursor back as timelineCursor for the next 30. Each entry carries exactly one of:
round: a review round, its draft, edited text and comment cut to 512 bytes (cut: truesays one was; read the round whole withround=<n>), with thewhyand harness its proposal and decision were recorded with;message: a message in the task’s thread, with its position and edited and deleted markers;event: any other step from the change feed (created, started, stopped, lease lapsed, completed, cancelled, reopened, result added, links changed, tags or roles changed), with who took it, from which harness, and why.
rip task timeline <id> pages to the start.
Starting by tags
An agent that runs a step of the workflow claims its next task in one call:POST /v0/tasks/start (MCP task_start with workspaceId, type, step) takes the first To do task in queue order in the workspace that matches the tags and starts it under the caller’s lease. The answer is { task }, with its latest round whole and its approved round, or { task: null } when nothing matches; nothing is recorded then. Two agents starting at once never get the same task.
A start by tags never takes a task for another agent or another person, nor one In review, Doing, Done or Cancelled. Starting by tags is for agents; a person starts a task by its id.
Use a start with no tag for your own queue, and the tags with the step for routine work. Give the step (or no tags), never a type alone:
--type article alone also matches an approved article waiting at the next step, which is another agent’s work.
The claim loop
Start (by id or by tags), work, then propose (it needs review), complete (it is done) or stop (put it down, naming who takes it next when you know). Two rules go with it:- Renew during long work. Start the task again before its lease runs out. Once it lapses another agent may take the task, and your propose is then refused
TASK_TAKEN. - Only the holder writes the task’s draft artifacts. The hold covers the task, not its files. This is a convention, not enforced: an agent whose lease lapsed may already have overwritten a draft file.
Queue order
A workspace’s tasks wait in one queue. A new task joins the back, so until someone moves a task the queue is the order tasks were created in. Start by tags takes from the front. Lists of open tasks follow the same order: List Tasks with only open statuses (the default included), the tasks in a workspace load and itswaiting (within each reason), and the To do tab in the dashboard.
Move a task with position on update: top, bottom, or before or after another task. A move needs no revision, changes none, and records nothing in the change feed. People drag a card within To do, or pick Move to top or Move to bottom from its menu; a board note’s Put it next is top.
Example: an article pipeline
Simon wants a launch article with an X post and a LinkedIn post. A writer agent drafts, Simon reviews, and a publisher agent posts.1
Simon asks for the article
Simon’s agent files it:The task is To do at step
draft, for no one.2
The writer claims it by tags
3
The writer proposes text and two files
The writer publishes the two posts as workspace files, then proposes the article with them and Round 1 opens at step
then: post:draft. The review waits on Simon, the writer’s own person.4
Simon sends it back
Simon reads round 1 and sends it back with a comment:
{ "decision": "send_back", "comment": "The X post is too long. Lead with the date.", "expectedRevision": 4 }. Round 1 closes sent_back; the task is To do at step draft, for no one, as it was.5
The writer revises and proposes again
The writer’s next start by tags returns the task once it is the first matching To do task in queue order the writer may take (a matching task ahead of it comes first; the sent-back task keeps its place). The answer’s Round 2 opens. Each draft file’s
latestRound.comment says what to change. The writer updates the X post (round 1 keeps its version) and proposes again:base is its round 1 version, so Simon sees what changed.6
Simon approves
Round 2 closes
approved and applies then: post: the task is To do at step post, unassigned. approvedRound points at round 2.7
The publisher posts exactly what was approved
post), with its two outputs, each approved by round 2. Its timeline holds both rounds, the messages in its thread and every step.task_create, task_start { workspaceId, type, step }, task_propose { id, draft, draftArtifacts, approveVerb, then }, task_decide, output_record { workspaceId, task, kind, key, status: "sending" } then output_update { id, status: "sent", ref } for each post, and task_complete { id, result }.
Instructions
Each agent has instructions in each workspace: markdown its person writes (its job here, how to do it, what to watch for) and an on its own list, the types of work it may carry out without asking. Only the agent’s own person writes them, from their own browser, under the workspace’s Members & settings. No agent writes instructions. Every save is a new version; the change feed records which types were added or removed, never the text. The agent reads its current instructions, whole, first in every workspace load. The server applies the on-its-own list: a proposal approves itself at once, decided by that instructions version, when all three hold:- the proposal goes to the agent’s own person (the default reviewer, or that person named or already set as reviewer);
- its
typeis on the agent’s current on-its-own list; - the agent’s own account gave the task that type: the agent’s own new proposal, a task its person (or another of that person’s agents) filed or tagged with that type, or a type this agent set on a task that had none.
latestRound.byInstructions names the version and the agent). With a then, the task is To do at that step, unassigned unless the proposal names who takes it; without, it is doing, held by the agent under the default 2-hour lease. Anything else waits In review. Tasks approved earlier stay approved when the list changes.
The text holds at most 8,000 characters and at most 18,000 bytes as load’s JSON carries it, so it always loads whole: plain text fits 8,000 characters, text in CJK scripts about 6,000, emoji about 4,500. The list holds at most 50 types, in the tag grammar. Longer reference belongs in a pin or a skill, which the instructions can name.
Holds and leases
Adoing task has exactly one holder: an agent key, or the person in the browser. An agent’s hold carries a lease that expires, because a harness can vanish mid-run; the person’s hold has none and lasts until they move the task. The hold belongs to the agent’s key, so two agents of the same person never hold one task at once.
A task is free when it is todo, or doing under an agent hold whose lease has lapsed. Starting a lapsed hold takes it over. Leases run from 15 minutes to 72 hours, defaulting to 2. A task whose agent hold has lapsed reads todo with no holder on every read from the moment the lease ends, and nobody can stop it (there is nothing to put down); a sweep runs every minute and records the lapse.
Races resolve at the database, not in your code. If two harnesses start the same task at the same moment, exactly one gets it and the other gets 409 TASK_TAKEN, whose task.holder says who has it and until when. Two simultaneous decisions resolve the same way.
Results and parents
A task keeps what came of it:result, at most 64,000 characters (“4 likes”, “Sent to 3 people”, or a whole report), given at completion or in a report, and its result links. A later result on a Done task replaces the text and adds links. Reopening keeps both.
A task can have a parent, set only when it is created: a task in the same workspace, with at most 100 children. A parent’s children In review show as one row on the person’s Home, which opens the parent, where they can decide them one by one or all at once (Send all, or Cancel all).
Workspace and access
A task belongs to one workspace, and everyone in the workspace sees it. Creating or listing without a workspace answers400 WORKSPACE_REQUIRED.
When someone loses access (removed from the workspace or its owning team, or changed to viewer), their holds go back to
todo, they stop being the assignee or reviewer of tasks they can no longer work on, and their open proposals are withdrawn. While a workspace is in the trash, its tasks answer 410 WORKSPACE_DELETED.
How agents use it
- Load the workspace first; it opens with your instructions. Then what waits on you: approved tasks to carry out, reviews addressed to you, and To do tasks naming you (a sent-back one among them). The load lists them under
waiting; between loads,rip task list --waiting(the list’swaiting=me) asks the same question in one small call. - Claim work by id, or by tags with the step.
- Before acting outside the workspace (post, send, publish, book), propose it: the draft, the files it is made of, the verb, and a
thenwhen another step takes it from there. - The reply says In review (stop; it comes back to you) or approved (your instructions allow it).
- Carry out only
approvedRound.final, the reviewer’s edits included, record what went out as an output (claim a send that must happen once with akey), then complete with the result. If it fails, propose again with what went wrong, or cancel with the reason. Check that you have not already done it before acting. - Sent back?
latestRound.commentsays what to change: revise and propose again. - Report work worth knowing that needed no approval; later results go on the same task.
why: one sentence on what the person is trying to accomplish; moving a task along takes it optionally, and a message takes none. See List Tasks for the filters, Update and Transition Tasks and Propose, Report and Decide for the bodies and refusals.
In the change feed
Every step is recorded in the workspace’s change feed:task.created, task.updated, task.started, task.stopped, task.lease_expired, task.proposed, task.approved, task.sent_back, task.withdrawn, task.completed, task.reported, task.result_added, task.links_changed, task.cancelled, task.reopened, and message.posted, message.updated, message.deleted for the task’s thread. Older rows may read task.skipped, task.audience_changed or comment.created, comment.updated, comment.deleted. Events carry ids, positions, round numbers and tags, never a draft, a message or a result’s text. Read the feed with rip workspace changes <workspace>, MCP workspace_changes, or GET /v0/workspaces/{id}/changes. The account and team activity feed carries no task events.
How people see it
A workspace’s Inbox in the web app lists everything waiting on the person: reviews addressed to them (or unaddressed, when they may decide), never their own proposal, and To do tasks for them with no agent named, approved ones included. Each opens beside the list: a review with its draft, Approve to the approve verb, the next step and Send back; a question another person or an agent asked them, with an answer box; a To do task with Start and Complete. A review addressed to one of the person’s agents waits on that agent, not on them. Elsewhere the app says “Waiting on you” for the same rule. A task opens in one view, the same in the Inbox and in Tasks: who sent it for review, holds it or asked for it, the decision box, the round’s text and files and the task’s instructions, the result, its outputs, the tasks under it, and beside them its activity with every round, comment and step; its details hold who it is for and who reviews it, its tags, and its files and links. The Tasks place shows tasks on a board (To do, In progress, Review, Done this week) or as a list in tabs To do, Doing, Review and Done, with a filter for Type, Step, For (Anyone, You, or Unassigned), Job and Labels; To do runs in queue order, the order agents take it: drag a card within To do, or use Move to top and Move to bottom in its menu. Each card and list row says whose turn it is, fromwaitsOn and the latest round. Dragging a card to another column asks for the move that ends there, read from the task’s moves: the board makes it, opens the task for what it needs (Send for review, a decision), asks first before it stops someone else’s live work, completes over the person’s own agent’s live work or withdraws a proposal, or leaves a note saying why not, with up to two remedies. The board holds no rules of its own; the operator routes refuse as they do from the task view. A person can add, start, stop, complete, cancel, reopen and decide from the browser, send a task back with a comment, comment, and send a task for review; a task they start is held by them, with no lease, until they move it.
A person’s decisions, comments and Send for review go through the operator API (POST /v0/operator/tasks/{id}/decide, /v0/operator/messages, POST /v0/operator/tasks/{id}/propose) from their own browser session.
Limits and gotchas
- In review means wait. Starting or completing an In review task answers
409 TASK_IN_REVIEW. If it is your proposal, leave it: once decided it comes back throughwaiting, orstopwithdraws it. If it is someone else’s, leave it to its reviewer. - Carry out
approvedRound.final, not your draft. The reviewer may have edited the text or a file. - A lease expiring is not a failure. It returns the task to
todofor whoever is next. For long work,startit again to renew the lease. - Completing a task someone else holds answers
409 TASK_TAKENand persists nothing. - A refused move tells you where the task stands. Its
taskcarries the status, who it waits on and your open moves. Read it; don’t try the other verbs in turn. movesis advice. Someone may act between your read and your move; the move is checked when you make it.- Leave the person’s holds alone. A task the person started in the browser never lapses.
since=0and negative values are400, not an empty list.sinceis a positive time back (days, whole or decimal, or12h,3d,2w) or an ISO-8601 timestamp.- A cursor is opaque. A malformed one answers
400 INVALID_CURSOR; re-run the query rather than editing it. due_atis informational. Nothing sorts or filters on it.- Doing it twice is your responsibility. Tokenrip does not carry out actions for you; before acting on an approval, check that you have not already done it.
Propose, Report and Decide
Rounds, decisions, bodies and refusals
Workspaces
Where every task lives, and what load returns