DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS
TASKS·CHAT AND HANDOFF

Chat and handoff

Conversations with Onnie and Tasks are connected, but they're not the same thing. Chat is ephemeral back-and-forth. Tasks are persistent, trackable work items. This page explains when one produces the other, how they stay in sync, and what happens when a Task moves between an agent and a human.

Chat creates Tasks

Not every message in a conversation becomes a Task. Chat is for talking through context, asking questions, and exploring ideas. A Task gets created when there's something discrete to do — something with a start, an end, and accountable ownership.

Onnie creates a Task from chat in two ways:

You ask for it. Say "track this as a task", "create a task for the campaign brief", or use /task in the chat input. Onnie calls create_task, fills the title and body from the conversation context, and drops an inline card into the chat.

Onnie decides to file it. During complex work, the Superagent may decide a sub-task should be tracked separately — particularly when work needs to be assigned to a different bot, scheduled for later, or gated on an approval. It creates the Task directly and references it inline.

In both cases, the Task's created_in_chat_id field records which conversation originated it. You can trace any Task back to the thread where it was born.

What stays in chat and doesn't become a Task: questions, clarifications, short lookups, summaries the agent produces on request, and anything that doesn't need tracking past the end of the conversation.

Task-attached chat

Every Task has at most one chat thread. It's created lazily — the first time you or an agent posts a comment, the thread is created. Before that, the Task has no thread and that's fine.

To find the thread for a Task, open the Task card and look for the Comments or Thread tab. If no comments exist yet, the tab is empty until the first message is posted.

The Task thread serves two purposes that share the same data:

  • Comments — messages you post to the agent, notes from collaborators, and approval decisions.
  • Execution log — messages the agent writes while the Task is running. When a bot dispatches, it reads the entire thread history as context, then appends its own messages as it works.

There is no separate log view. Comments and execution output live in the same stream, ordered by time. When a bot run is in flight, new messages appear as the agent produces them.

The thread is owned by the Task, not by any single conversation. You can have a separate chat with Onnie about a Task (asking "what's the status of X?"), and that conversation does not appear in the Task's thread.

Handoff to a human

A handoff happens when an agent stops work and waits for a person to act. There are two common triggers:

The agent requests approval. A bot can set a Task to awaiting_approval when it has finished its work but the result needs sign-off before the Task closes. The Task card renders Approve and Reject controls in the thread. The assigned agent does not re-dispatch while the Task is in awaiting_approval.

The agent reassigns to a user. A bot can call assign_task with a assignee_user_id to hand the Task directly to a person. When a Task moves from a bot to a user, the dispatch signal is not bumped — the bot stops running on its next natural exit. The Task appears in the human's "My tasks" view.

In either case, the Task thread is the right place to leave context for the incoming person. The agent typically posts a summary comment before stepping aside — "here's what I did, here's what needs your input" — so the handoff is legible without reading the full execution log.

If the agent set status to blocked (for example, because a dependency is missing), that is also effectively a handoff: a human needs to clear the blocker and move the Task back to in_progress.

Handoff back to the agent

Once a human has done their part, work returns to the agent by bumping the dispatch signal. There are several ways this happens:

Approving the Task. Calling engine_comment_on_task with set_decision='approved' moves the Task from awaiting_approval to in_progress, which in turn bumps dispatch_signal_at. The status change is what re-triggers the bot — approval itself is mediated by that transition. The bot picks it up on the next cron tick.

Reassigning to a bot. If the Task was handed to a human and that person wants the agent to continue, reassigning to a bot triggers dispatch immediately via dispatch_signal_at.

Editing the Task body, status, or dates. Changes to assignee, status, body_md, start_at, due_at, or event_at bump dispatch_signal_at. Posting a plain comment alone does not re-trigger the bot — the signal only moves when one of these fields changes.

The bot does not "resume" where it left off — it reads the full state fresh on every dispatch: current body_md, full comment thread, current status, and context from the project and workspace. Anything the human wrote in the thread is visible to the bot on re-entry.

Privacy of chat threads

//NOTE

Task threads are strictly private to the workspace member who owns the session. Administrators do not have access to other users' chat threads or the messages inside them. There is no admin override or "support view" for engine_chats or engine_messages. If you share a Task with a colleague, they see the Task fields (title, status, assignee, etc.) but not the chat thread unless they are the thread owner.

This applies regardless of workspace role. A workspace admin can see Task metadata through normal RLS policies but cannot read another member's Task thread.

If you need to share context from a thread with someone else, copy the relevant content into the Task body or a comment — the body and comments are part of the Task record, not the private chat, and follow the Task's own access rules.