Delegation ledger

  • Desktop app
  • All plans
View as Markdown

What it does

When one agent hands work to another (typically your project assistant or another coordinating agent), the handover can be put on record as an assignment: the brief, its acceptance criteria, who handed it to whom, and where it stands. The delegate answers through the ledger (accepted, declined, in progress, blocked, submitted with its result and evidence) and the delegator decides (verified, returned, closed). For every open assignment the app computes the delegator's next step by fixed rules, from the state, a check-in clock and the delegate's live console: wait, chase, resume its console, escalate to you, review or close. Agents and your own scripts get the same answer, with no AI call.

Where to find it

No screen of its own. Agents use it through their AgentsRoom tools, and your scripts read it from the Local status API at /v1/assignments. Each assignment travels as agent mail: the brief and the notices are messages of one conversation, readable from the envelope button of the agents' panes (Agent Messaging).

How to use it

  1. Ask your project assistant to hand work to an agent: it delegates through the ledger by default (assignments_create). Any other agent can do the same when you ask it, for example "hand the login bug to the backend agent as an assignment, with acceptance criteria, and follow it up".
  2. The delegate receives the brief by mail, with the assignment id, and answers with assignment_update.
  3. The coordinator reads assignments_list and acts on nextAction. It is told by mail when a result is submitted, when the work is declined and when the delegate is blocked.
  4. To follow it from a script, turn on the local status API and poll /v1/assignments, then route on nextAction and reason:
f=~/.agentsroom/local-api.json
curl -s -H "Authorization: Bearer $(jq -r .token "$f")" "$(jq -r .url "$f")/v1/assignments?project=$PWD" \
  | jq -r '.assignments[] | "\(.nextAction)\t\(.reason)\t\(.delegate.name)\t\(.title)"'

The next step, first match wins:

  • none: verified or closed.
  • review: a result was submitted (decisions_raised when it carries decisions to take).
  • close: the delegate declined it, or is no longer an agent of the project.
  • Blocked on you or on a decision: escalate_to_user. Blocked on something else (a ticket, another assignment, an agent, an outside event): wait, then escalate_to_user once the check-in has passed. Blocked on an assignment that is now finished: chase.
  • Delegate paused by you: escalate_to_user. No console: resume_console. Console restored blank behind a Resume card: resume_console. CLI never started: escalate_to_user. Mid-turn: wait.
  • Console starting, waiting for your answer, declared blocked, rate limited or degraded, or not observed by the window lately: wait, then escalate_to_user once the check-in has passed.
  • Idle: wait until the check-in, then chase. It is escalate_to_user instead when the last notice was refused by the mail limits, when two follow-ups went unanswered (unresponsive), when the brief never reached the delegate's console, or when inter-agent messaging is off.

The check-in clock restarts on any move of the delegate (an update, a progress note, a reply by mail in the assignment's conversation), on each follow-up, and when the work is returned.

Settings

None of its own. It needs Inter-agent messaging (interAgentMessaging, Settings > Agents & AI > Agent behavior): with it off, a new assignment is refused because its brief cannot be sent. Its four tools belong to the Agent Mail family of Settings > AgentsRoom tools (mcpToolToggles), so switching that family off hides them too. The check-in cadence is set per assignment (checkInAfterMinutes, 5 to 1440 minutes, 30 by default).

Agent tools (MCP)

  • assignments_create: hand work to one agent of the project and record it (title, brief, acceptanceCriteria, ticketId, checkInAfterMinutes). The brief is sent through agent mail, under its limits.
  • assignments_list: what the caller handed out, each with nextAction, reason and hint; id returns one in full (brief, criteria, history), delegator: "*" reads the whole project.
  • assignments_mine: what the caller owes, with the brief and its next move (yourMove).
  • assignment_update: one move. Delegate: accepted, rejected (with a reason), in_progress, a progress note, blocked (blockedOn), submitted (result: outcome, summary, evidence, decisions raised). Delegator: verified, returned (saying what is missing), closed, chase, a new checkInAfterMinutes.

agents_ack on a brief also accepts or declines it, and a reply in an assignment's conversation counts as progress (from the delegate) or as a follow-up (from the delegator).

Providers

All providers, no difference.

Mobile

Not on the mobile app: the ledger follows consoles running on this computer. The brief and the notices are ordinary agent mail.

Limits

  • Same project only. Work for another project goes to that project's inbox.
  • An assignment travels as mail, so the send budget, the pause, the conversation limit and the messaging switch apply. A refused notice never undoes the move: it is recorded, and the next step becomes escalate_to_user.
  • Two follow-ups without an answer at most: a third is refused, and the next step goes to you.
  • Records stay on this computer, in the project folder (.agentsroom/agent-mail/assignments/, ignored by git), like the agents' mail.
  • A brief holds up to 5000 characters and 10 acceptance criteria of 200 characters.

Common questions

  • Can a cron job tell me which delegations are stuck without starting an agent? Yes: /v1/assignments?project=<path>&nextAction=escalate_to_user on the local status API.
  • How does the app tell "quiet but working" from "stalled"? From the delegate's live console and the check-in clock: mid-turn means working (wait), idle past the check-in with nothing recorded means stalled (chase).
  • Does my project assistant use it? Yes, by default: it hands work over as assignments, reads their next step with assignments_list and acts on it. An assistant whose role file you edited keeps your text: add the two tools to it yourself.
  • Does the coordinating agent have to remember message ids? No. assignments_list returns everything it handed out, even after a restart or on a new conversation.
  • Can the delegate mark its own work as verified? No. Only the agent that handed it out can verify or return it: the app identifies the caller itself, never from an argument.

Related