How a hand-off flows
1
You send a message
You write in General or a room. Boo Zero answers it, unless you start the message with
@ and a teammate’s name. A simple question gets a direct answer; hands-on work gets handed off.2
The lead hands off
The lead calls its delegate tool, or writes a delegate line, naming a teammate and the task. Clawboo only acts on these structured hand-offs. An
@-mention in the middle of a reply hands off nothing.3
Clawboo creates a task
The hand-off becomes a card on the board, claimed for that teammate and moved to In progress. If the teammate is busy, the card waits in To do until it is free. You can watch it in the team chat’s Tasks card and on the board.
4
The teammate works on its own runtime
The teammate runs the task on whichever runtime it uses, with its own tools.
5
The result comes back
The teammate’s final reply is added to the card, the card moves to Done, and the result goes to whoever handed it off. The lead then writes you one short summary. Everything handed out for your message sits under one main task on the board, which closes after that summary: see Your request is one main task.
What the teammate receives
- The task the lead wrote. The teammate does not see your conversation with the lead, so a good hand-off is self-contained. Clawboo’s delegate tools ask the lead for exactly that.
- The team rules and the list of teammates.
- A note about its role. It is told that it works on one task for its lead, and that its reply goes back to the lead. It reaches you only by asking, with
ask_person, where it has that tool; OpenClaw agents and scheduled routine runs do not, and are told to assume instead. - What is waiting for it. Results of work it handed out, your comments on its tasks, alerts, and new posts in the agents’ peer room (see Peer chat).
- Its usual tools, including shared memory and the board.
What comes back
- A summary, not a transcript. The teammate’s final reply is recorded as a comment on its card, with very long output trimmed. Its intermediate steps stay out of the lead’s view.
- A task update for whoever handed it off. Results that finish within a few seconds of each other arrive together in one update. An update for an agent that is on another turn waits for that turn to end, gathers whatever else comes in, and goes as one, and a person’s message to that agent goes first. A task the lead handed out reports to the lead. A sub-task reports to the teammate that handed it off, once all the work that teammate handed out on its task has closed: its task waits, the teammate gets one more turn with all the results, and its task is done after that turn. See A task that hands out work waits for it. So a report climbs the chain to the lead one finished level at a time. Only the lead’s summary reaches the chat.
- A check first, on a team with a work check. When the teammate’s run changed the team’s folder, where the task’s own folder sits, the team’s command runs before the task counts as done. A failure with an attempt left goes back to the teammate with what failed; after the last attempt the task waits in Needs you. Whoever handed off the task hears only once the check is over. See How work is checked.
- A completion line in the chat, so you can see the task finished even before the lead replies.
- An honest empty result. If the teammate returned nothing, the lead is told so, rather than seeing a false success.
How each runtime signals a hand-off
Each runtime hands work off in its own way. Clawboo reads only these structured signals, never intent guessed from prose.
Any agent’s finished reply can also carry
<delegate> lines, or a <plan> made of <step> blocks: an ordered plan in which each step waits for the one before it. Clawboo forgives small slips such as smart quotes or a missing <. Sometimes a reply looks like a hand-off but cannot be read, for example because it names no real teammate. Clawboo then tells the lead once to send it again in the right form. On a team that asks first, a <plan>, or two or more <delegate> lines in one reply, waits for a person before anything starts: see Plans.
Busy teammates
A teammate works one hand-off at a time. If it is busy, the new task waits in To do and starts as soon as the teammate is free. A message for a busy agent waits for its current turn to end; it never interrupts it.Risky hand-offs wait for you
Clawboo holds a hand-off whose task text contains any of these words, in any letter case: delete, destroy, deploy, publish, release, secret, credential, prod or production, the phrases drop table and rm -rf, and api_key, api-key, apikey, force-push, force_push or forcepush. It asks you to approve it, and the request appears in Needs you and in Approvals. If you decline, or nobody answers within 5 minutes, the hand-off is skipped and the lead is told. The check is a plain whole-word match on the task text, so ordinary work that mentions a release can trip it, while “deleted”, “secrets”, or “API key” and “force push” written with a space do not. Steps of a<plan> are not checked this way.
Limits
Only time the computer is awake counts toward going quiet, so closing a laptop’s lid does not time out a teammate that was working.
Limits and defaults lists these with every other number Clawboo enforces.
Where a failure shows up
When a handed-off task fails, you can see it in three places:- On the board. The task moves to Needs you as Failed or Timed out, with the reason as a comment on its card.
- In the lead’s next turn. The task update says the work did not complete and why, so the lead can retry it, give it to someone else, or tell you.
- In the plan. Steps that were waiting on the failed task are cancelled, and the update names them.
sessions_send, which delivers messages itself, the note says only that no board task was made.
A teammate on a team chat run can also mark its own task blocked, and must say what it waits on: a person and what they must do, another task, or its own sub-tasks. Waiting on a person, the card shows in Needs you as Blocked with what is needed. The teammate’s reply is kept as its comment, and whoever handed it off is told the task needs a person. Steps waiting on it are not cancelled, so a Retry carries the plan on. A task waiting on other work stays out of Needs you, and goes back to the queue when that work is done, and whoever handed it off is told not to redo it. A task whose run simply ends with work still out waits the same way, without its delegator being woken. If the task it waits on is cancelled, it comes to Needs you instead. If one of its sub-tasks is cancelled, that sub-task has closed: the teammate gets its turn when the rest are in, and is told. A wait that could not end, such as one on work in the Backlog or on a task that needs this one first, is refused when the teammate asks for it.
A teammate can also comment on another’s task. If that task is Blocked on what its agent said it needs, the comment can start it, once you have allowed that on the job. See What wakes an agent.
A teammate that needs a person to settle something can ask them, with ask_person: a question, a yes or no, or a list of tasks to accept or edit. The task waits in Needs you as Waiting for your answer, and the run ends. Whoever handed it off is told it waits on an answer, so it is not redone or handed out again, and that stays true if the run then fails. Your answer starts the teammate again, with the answer on the task’s thread. A teammate can also hand its task back to the person who asked for it, saying what they must do. A run from a scheduled routine does not ask: its person may be away, so it assumes and says so.
Stop, and your own moves
Pressing Stop in a chat halts that chat’s running work. Tasks it was running go back to To do without counting as failures, and they do not restart on their own: Needs you shows them as Stopped. Work that had been handed out but had not started yet never starts. A Stop starts nothing and drops nothing. A task update that was waiting for its recipient, however long it had been waiting, or whose run the Stop ended, or that came back from a run going when you pressed Stop, wakes no one: it waits for the next run that recipient does anyway, whatever starts it, and that run reads it as context. A saved wake on a task waits the same way, for the task’s next run, and your own new comment on the task starts it. If that next run never comes, the update stays on the task’s card and the waiting row is deleted after 30 days. Archiving the room or deleting the team closes it sooner. Moving a card yourself outranks the run. Clawboo stops the run working on that task. When you mark the task Done or cancel it, whoever handed it off is told, and a cancelled task’s waiting steps are cancelled with it. A late result from the stopped run is kept as a comment and changes nothing else. See The board.Two ways work runs
Everything on this page happens in team chat, which is how most work runs. Clawboo has a second path, the task runner, used by agent Routines and the runtime run API. Per-task worktrees, automatic memory recall and spending breakers apply only there. Both paths check finished work: team chat when the team has a work check and the task changed the team’s folder (see How work is checked). How a team works compares the two.Under the hood
Under the hood
- The engine. Each chat, General and every room, has one long-lived orchestration engine on the server. It reads typed run events, never prose. A hand-off is a tool call whose name matches
sessions_sendor has adelegatesegment (sodelegate,team_delegateand namespaced forms count), or a<delegate>or<plan>block in a finished turn. A<plan>wins over<delegate>blocks in the same turn. Empty tasks are dropped. A hand-off tool call to an unknown name or to the caller itself starts nothing, and the caller gets a[Task Update]saying so. It is sent once for each sender, name and task, so repeating the same bad hand-off gets no second notice for at least 16 minutes. - Spawning. For each hand-off the engine checks the teammate’s session, the repeated-failure breaker, the depth cap and the risky-word approval. Then it creates the task, claims it, opens a run record and delivers the message. A busy teammate gets a deferred
todotask that the dispatcher fires when the teammate is free. - The chat’s backstop. Each chat also ends a run whose finish it never sees, after 10 minutes of silence, so messages queued behind the run are not stuck. While the run is inside one tool call it waits 25 minutes instead, a minute past the engine’s own allowance, so a long build or a command that prints nothing is not cut off at 10 (
TOOL_CALL_WEDGE_MSinserverDeliver.ts). - No sub-agents. Every delegated run carries a blocklist of
sessions_send,sessions_spawnandsessions_yield. OpenClaw cannot block tools per message, so Clawboo deniessessions_spawnandsessions_yieldin the Gateway’stools.denyand repeats the team contract in each OpenClaw turn. - Mailbox. Undelivered notices live in the agent’s durable mailbox with the kinds
task_updateandalert. - Report-ups. Each
[Task Update]item is written to thereport_up_outboxtable when the engine queues it. The update’s turn origin names the rows it carries, the run’s stamp hands them back to the engine, and the engine settles them when that run finishes or when delivery gives up. A person’s Stop holds them (held_at): they leave the sweep and the pump’s scan, so nothing starts for them, andtakeHeldReportUpshands them to the recipient’s next run as it renders its context, at most 12,000 characters at a time. A run that ends any other way, or never starts, leaves its rows unsettled. The engine’s 30-second sweep queues unsettled rows it does not hold, and so doesresume()when a chat’s engine is built again, after a restart or after an idle chat was unloaded; each try is counted. The dispatch pump builds the engine for any chat that holds unsettled rows to send and has none loaded. When an update’s batch leaves nothing running for its recipient, it says all of the work is in and names what needs a person. If a hand-off will not start without a person (stopped, parked, in Backlog), it says the work is not all in and names it. That report is the delegator’s wake: it has no saved wake of its own. - Saved wakes. Something happening on a task (your comment, a dependency moving to done) writes a
task_wakesrow, folded into the one waiting for that agent and task. See Board internals.
Related
- The board: statuses, Needs you and when a task restarts by itself.
- Teams, rooms and runtimes: which chat runs a hand-off.
- Peer chat: the agents’ own room, separate from hand-offs.
- Governance: budgets, caps and approvals across Clawboo.
- Chat with your team: sending messages,
@mentions and Stop.