Hand-offs and approvals

Work in Raft moves between people and agents through the same tasks and conversations. Every move is written into the timeline as an event line, so the record of who did what stays in one place. When an agent wants to do something it may not do alone, it doesn't ask in prose: it prepares the action as an action card, and a person confirms it. The action runs as that person, and the card stays in the conversation as the record.

When it applies

Any time work changes hands: a task is claimed, released, assigned or moved to another status; an agent asks for permission; an agent finishes; something fails along the way. How tasks are shown is in Tasks; the timeline itself is in Conversation.

Claiming work

A task is claimed by whoever takes it, person or agent, with the same action and the same record.

PageLightDarkBoth

• Record a claim, a release, an assignment and a status change as an event line (SystemMessage): who did it, the verb and the task. "Bugen claimed #25 "Fix onboarding copy"".
• Post those event lines in the task's own thread, not in the channel the task belongs to. The channel stays readable; the people who follow the task's thread see its history.
• Show the task's current state on the message it came from, as the task marker: the status pixel, the task number and the assignee (MessageItem).
• Fold 2 or more event lines in a row into one line with a disclosure ("There are 3 task updates"), as in any conversation (Conversation).

Event lines

An event line isn't a message: nobody wrote it, so it has no avatar or name. It is set in Space Mono, centered between hairlines.

• Name who did it, the verb and the item, in that order.
• Use the task's statuses as they are spelled: moved #25 to In Review.
• Write event lines without a leading emoji: emoji are content, not icons (Iconography). The product's server still writes a pin, a lock or a status emoji at the start of task lines ("claimed", "released", "moved"); the system drops it.

Handing off

A hand-off is one of the moves a task already has. There is no separate hand-off object.

• Agents move their own finished work to In Review, so a person can check it, and to Done only after it is approved. This is the order the Raft agent guide gives every agent.
• Mention the person who has to act next. A mention reaches only people in the place, so the reviewer has to be a member of it.
• Hand a whole session over, not only a task, with "Take over a local session" in the desktop app: it creates a Raft agent in the same project folder and sends it a briefing drawn from a local Claude Code or Codex session. The person reads the briefing before it is sent.

Finishing work

• When an agent finishes, it posts a message that leads with the outcome and links its proof: a pull request, a commit, a file (Writing about agents).
• Link the proof as a link in the message, not as a pasted log. A long report goes into an attached file, with a short summary in the message.
• Then move the task to In Review. The event line follows the message in the task's thread.

Approvals: the agent prepares, a person confirms

An action card is a request for an action the agent may not take alone. The agent fills in the action and attaches the card to its message; a person checks the values and confirms (MessageActionCard).

PageLightDarkBoth

The product ships these actions:

• Title the card with the verb and its object, in sentence case: Create private channel #launch-review, Approve Linear for @bugen.
• Make the confirm button repeat that verb, in Title Case, as the small ink-bordered button (Button with variant="outline" and size="sm"). It is not pink: the screen's one pink button is the composer's send button.
• When the action needs more than a yes, let the button open the ordinary dialog for it, filled in with the agent's values. The person can change them there before anything is created. Don't make the fields on the card editable: the card is a summary.
• Show the values the person needs to check as properties, the agent's reason under Reason, the permissions an app asks for as a scrolling list, and a standing note from Raft as a neutral notice.
• Run the action as the person who confirmed it, with that person's permissions.
• Show no confirm button to someone who may not act. Fold the card and say why under its title: "Join #launch-week to run this.", "You need the Create Agents permission — ask a Server owner or admin to run this."

States

The record afterwards

Nothing about a hand-off is lost when it is over.

• Keep a resolved card in the conversation. Don't delete it or replace it with a message.
• Show the Activity tab to the agent's creator and to admins. Other members see the profile only.

When something fails

Say what failed at the scope it affects, and say it once (Feedback).

• Show the reason only to people who manage the agent. Others see that the agent "encountered an error", because the detail can contain private information.
• Confirm Stop Agent and Restart / Reset with a dialog: both interrupt the agent's work (Feedback).
• Don't put an agent's error in a toast. A toast is for a one-off action with no place of its own; an agent's error lasts until someone fixes it.

What the product doesn't do yet

The component doc for MessageActionCard describes a few things Raft Chat doesn't ship:

• A ghost Edit First button beside the confirm button, and a Decline button with a Declined state. In the product, the creation actions open their dialog from the confirm button, and a card nobody acts on stays waiting.
• A "Needs an admin" status, with a pink pixel, on a waiting card. The product shows no status until something changes.
• A list of waiting cards in Activity. In the product, a waiting card is found in its conversation.
• A toast when the action fails. The product shows the reason in a banner inside the card.

Related

• Tasks: the five statuses and task details.
• Conversation: the timeline, grouping and threads.
• Writing about agents: how event lines and agents' messages are worded.