Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Guides/Approvals

Approvals

Human-in-the-loop approval gates surfaced through the Operations queue. An agent that needs authorization for a sensitive action parks an approval item and ends its turn; a person approves or rejects it — an operator from the Operations page or the mobile admin, or the Workspace user the agent addressed it to — and the agent reads the decision back and continues.

See it in the product

How to require approval for a skill

1:13
8 chapters

Anything irreversible waits for a person

2:09
10 chapters

Trinity Platform Demo — operator queue & approvals

May 2026

Trinity Roles & Permissions Explained — primary, approvers and where approval requests go

Nov 2026

Concepts

•Queue item — A row in the operator queue. Three request types: approval (a yes/no or multi-choice decision), question (freeform guidance), alert (acknowledgement only). Created by the agent, consumed by a person.
•Options — JSON array of choices for an approval (typically ["approve", "reject"], but agents may define richer sets like ["draft", "send", "discard"]). The decision must be one of them, or the platform's reserved Something else ("(something else)"), which every approval offers and an agent may not list itself.
•Atomic ask — One decision per ask, with a short title and a few short options. The platform enforces the shape on items an agent raises: at most 5 options (Something else not counted), each at most 60 characters, and a title of at most 120 characters. The reasoning belongs in the question and what each option will do belongs in the proposal. See Authoring limits.
•Decision and note — The answer has two parts. The decision (response) is what the agent reads: the chosen option, the typed answer to a question, or acknowledged. The note (response_text) is optional free text riding alongside a decision; it never stands alone. With Something else it is not optional: it is the instruction the agent re-plans from.
•Ask — A queue item addressed to one Workspace user (addressed_to_email). It appears in that person's Workspace, where they answer it, and stays visible to operators in the queue. An item with no addressee is for the operator alone.
•Priority — critical, high, medium, low. Affects sort order in the queue.
•Response window — Optional expires_at. After expiry the item moves to expired; the agent treats that as "not approved — do not proceed". An answer that arrives after the deadline is refused (409 expired), even in the few seconds before the platform sweeps the item.
•Re-ask — An ask that raises again one of the agent's asks that expired, once the agent has new information. It names the expired ask (supersedes_expired), and the Operations cards show the link both ways: Re-ask of … on the new ask, Re-asked as … on the expired one. An expiry means not approved, so repeating an expired ask's exact action without naming it is refused.
•Replace — An agent that needs to change a request it is still waiting on replaces it instead of asking again: it raises the new ask with replaces naming the old one. The old ask ends Replaced by the agent and the new one appears in its place; the cards name each other by request id (Replaces … / Replaced by …) — there is no link that opens the other ask directly. An agent can replace only its own pending asks, never one a person has already answered, and repeating an action that is still pending without replacing it is refused.
•Withdraw — An agent that no longer needs an answer ends its own pending ask with a one-line reason (withdraw_ask) and no successor — the question answered itself, or the action is no longer needed. The ask ends Withdrawn by the agent; the person it was addressed to and the Resolved tab see the reason as history, nothing is asked of anyone, and nobody is woken. An ask a person has already answered or ended cannot be withdrawn — the answer stands.
•Proposal — Optional structured description of the exact action an approval would allow. It is shown read-only, as text, on every card that offers the decision (the Operations card, the mobile admin and the Workspace ask) and stays on the resolved card, so the record says what was decided.
•Aging — A pending item that waits longer than the aging bound (default 24 hours) is marked Waiting on its card, and a queue-file item gets a platform.aging_since timestamp written into the agent's entry. An admin sets the bound in Settings → Access → Operator queue aging bound (hours); 0 turns it off.
•How it ended — Every item ends one of four ways — answered, cancelled, dismissed (the addressee chose not to answer, in the Workspace) or expired — and records who ended it (a person, the timeout, for a platform heads-up the platform itself, or the agent when it replaced or withdrew its own ask), when, and for a cancellation the optional reason the operator gave. The Resolved tab, the mobile admin and the Workspace all show it.
•Unknown outcome — An agent's approval names an action the agent holds, so when it expires unanswered Trinity cannot tell whether the agent went ahead anyway. Such an approval ends Expired — nobody answered in time; whether the action went ahead is unknown on the Resolved tab, the queue detail and the mobile admin, and carries disposition_reason: "outcome_unknown". An expired gated-skill approval never says this: the platform held that action, so nothing ran. Questions and alerts never say it either.

How It Works

1

The agent reaches a step that needs authorization.

2

The agent raises the item with the ask_operator tool and ends its turn — it never waits in-turn for a human. The platform checks the item at once and answers with a receipt: a malformed item is refused with a named reason, and asking again with the same id returns the first receipt instead of a second item.

3

The older route still works for two releases: the agent appends an entry to ~/.trinity/operator-queue.json, and the Operator Queue Sync Service picks it up within 5 seconds. The platform log names each agent still using the file.

4

The item appears on the Operations page under the Needs Response tab with a type pill — Needs approval, Question or Heads up — plus title, question, options, and any context the agent attached. The question renders as markdown; the title, the option labels and the given answer render inline formatting only (bold, code, links). The same rendering applies on the Operations page, the mobile admin and the Workspace. Resolved items (responded, cancelled, expired) move to the Resolved tab. An item addressed to a Workspace user also appears in that person's Workspace (below).

5

A person answers. Only a person can answer or cancel an item — a browser session or a person's own API key; an agent's key is refused. The controls follow the type: for an approval, pick an option, optionally add a note, and click Send; for a question, type an answer and click Send Answer; for an alert, click Got it. Nothing is sent on a single tap of an option.

6

The agent reads the decision with get_my_ask, or in the turn the wake starts (below). For a queue-file item, the decision is also written back into the file within about 5 seconds (running agents only).

7

The agent acts on it. A queue-file item is then marked acknowledged in the file.

When the agent acts on it. By default answering starts one turn immediately and the agent acts on the decision in it (trigger operator_response in Executions) — Wakes when an ask ends is on unless the agent's owner switched it off, after which the answer is read at the start of the agent's next turn (its next scheduled run, loop iteration or message), and an agent with no next turn waits until someone writes to it. A cancellation or a dismissal wakes it too, so it stops waiting for an answer that will not come (trigger operator_ending; one turn per agent however many of its items one sweep ended). An expiry does not wake it: the agent reads "Denied by timeout; do not re-ask the same action without new information." on its next turn. A stopped agent is not woken — its answered ask reads Agent not yet woken and is delivered when the agent next starts. See Wake When an Ask Ends.

The decision must be one the agent offered — or Something else. For an approval that listed options, an answer outside that list is refused with a 422 that names the offered options; matching is exact, so Approve and approve are different answers. The one exception is the reserved (something else): it means none of the options is approved, the agent carries out none of them, and your instruction (required, up to 4000 characters) travels in response_text. It is refused on a question or alert (reserved_value), without an instruction (instruction_required) and on an approval the platform raised itself, such as a skill gate (not_off_menu) — those show no Something else button. Questions, alerts and approvals that offered no options take free text.

When the agent's copy and the queue disagree.For a queue-file item, the platform compares every entry in the agent's file with the queue on each cycle and shows a badge when something is off. A healthy card shows no badge.

BadgeMeaning
Changed by the agentThe agent rewrote the item after it was ingested. You are reading the original.
Closed by the agentThe agent closed the item on its side; it still waits for you here.
Gone from the agentThe agent's file no longer carries the item.
Re-used idThe agent used the id again after the item closed; the new entry was not admitted.
UnconfirmedThe platform could not check the agent's copy — the agent is stopped or unreachable, or its file is unreadable. Hover for the reason and when it was last confirmed.
Answer not deliveredYour answer or cancellation did not reach the agent's file. Hover for why; most causes retry on their own, and an answer to a stopped agent lands when it starts.
WaitingThe item is past the aging bound.

Answering an item marked Changed by the agent or Closed by the agent is refused once (409 item_diverged): the card refreshes and asks you to review it, and the next Sendanswers anyway. The Operations header counts items whose answer did not reach the agent and items the agent closed, and offers one-click cancel of the closed ones. The platform never writes over an agent's queue file it cannot parse, and delivers an answer only into an entry that still matches what you answered.

Platform heads-ups. Trinity itself files items of other types into the same queue — for example a Workspace client rating a response as not useful, or an agent calling a skill that does not exist. These carry no decision; they show Got it only, and acknowledging them sends nothing back to the agent.

Some heads-ups describe a condition rather than an event — for example a subscription running low on headroom, a skills-library URL Trinity refused to adopt, a stale system-agent base image, or an agent's dispatch breaker gone dormant. For those, Trinity keeps one pending row per condition:

•A new reading of the same condition updates the existing row instead of filing another. A card seen more than once reads seen N times · last seen <when>.
•When the condition clears, the platform ends the row itself. The card reads Ended by the platform — the condition cleared.
•A row that nobody acts on expires 14 days after its last reading (OPERATOR_PLATFORM_ALERT_LIFETIME_DAYS). An expired heads-up reads Expired — nobody acted on it.
•After a person ends one, the same reading files nothing for 7 days (OPERATOR_PLATFORM_ALERT_SNOOZE_DAYS), unless its priority rises (for example a headroom warning turning critical).

Every platform heads-up now follows this model. Four need a person and never expire: a poisoned execution, a collided Workspace inbox, a gitignore change notice and a Workspace problem report. The platform never ends them; only a person does. See Operating Room.

Permission requests. An agent refused for lacking a permission an admin grants (such as changing another agent's schedules) is told to raise a question whose title includes the permission id, for example schedules.manage. Answering it grants nothing: an admin grants the permission on the agent's Settings tab, where the open requests are listed. See Permissions to Change Itself.

Asks Addressed to a Workspace User

An item raised with ask_operator is addressed by role: primary (the default for approvals and questions) goes to the person assigned as the agent's primary contact, or to the agent's owner when nobody is assigned, and operator (the default for alerts) goes to the operators with no single person. approver and viewer are refused until someone fills those roles. An approver item reaches only the seated approvers who can open the agent (it is shared with them, or they are an admin); when none of them can, the raise is refused with 422 role_cannot_open_agent and nothing is filed, so share the agent with the approver. Only a person seated as approver can answer an approver item: anyone else, an admin included, is refused (403 not_addressee) and may only cancel it. An item raised before the approver's seat was recorded with it stays answerable by anyone with access to the agent. A queue-file entry can instead address an item to one person the agent is shared with by setting addressed_to_email. The address is checked at ingestion against the agent's own roster: someone the agent is not shared with, or a malformed value, turns the item into an ordinary operator ask rather than being refused. The context block of an ask is never shown to the addressee.

A canon role (role:<id>). Where your install provides roles, an ask may name a role from the agent's canon, such as role:finance-lead. It reaches every person seated in that role on the agent's own roster who can open the agent, and nobody else: there is no fallback to the owner or the operators. When it cannot reach anyone, the ask is refused with a 422 that names the role (never a person) and the remedy:

•role_unavailable — roles cannot be answered on this install right now. Address the ask to primary or operator instead.
•role_unassigned — nobody is seated in the role for this agent yet. Ask the agent's owner to seat someone, or address the ask to primary or operator.
•role_cannot_open_agent — the people seated in the role cannot open the agent, so they would never see the ask. Ask the agent's owner to share the agent with them.

Reports and messages cannot be addressed to a role id; they refuse it with invalid_to.

The project (project). Where your install provides projects, an ask raised during a chat or room turn that is on a project may be addressed to: project. The platform reads the project from the turn itself; the agent names no project and no person. The ask goes to one person: the project's steward when the steward is a person who is the project's creator or a member, otherwise the project's creator. That person does not need the agent shared with them: the ask is in their Inbox, marked To you as this project's steward (or creator), and only they can answer it. An admin can still cancel it. If the agent is not shared with them, Discuss is refused (422 not_discussable), because a discussion is a chat with the agent; they answer on the card. When the steward changes, a pending ask moves to whoever it now reaches, and its card names the new reader's seat. When the project is archived or the agent leaves it, the platform ends the agent's pending project asks, and the agent reads them as ended by the platform. There is no fallback to the owner or the operators. An ask that cannot reach anyone is refused with a 422, and nothing is filed:

•project_unavailable — projects are not available on this install. Address the ask to primary or operator.
•not_in_project_turn — the ask was not raised during a chat or room turn on a project this agent works on, for example from a schedule. Address it to primary.
•project_unreachable — neither the steward nor the creator can be reached on this platform. Ask the project's creator to name a steward who is a member.

A credential ask is always addressed to primary; to: project is refused with invalid_to.

When nobody can be reached. If nobody is assigned as primary and the owner has no email address (or the agent has no owner), an ask addressed to primary goes to the operators, and the receipt says resolved: false. When that ask was raised during your chat, the chat shows one muted line where it was asked: the kind of ask, that it went to the operators, why, and that an admin can assign a primary contact in the agent's Access tab. The line never shows what the ask says, because you are not the person it is addressed to. An ask the agent addressed to operator on purpose shows no such line.

A role several people fill. When the role an ask is addressed to resolves to more than one person, the one ask reaches every one of them — it is in each person's Inbox, and the receipt reports resolved: true. The first answer wins: the others see the ask as ended, with Answered · {name} naming who answered it. Dismiss and Discuss are not offered on a shared ask, and the Workspace route refuses both with 422 shared_ask, because one person's dismissal or discussion would end or redirect it for everyone.

When the role changes hands. An ask's audience is worked out when it is raised. When someone else is assigned as the agent's primary contact, the agent's pending asks addressed to primary, and its pending gated-skill approvals, move to whoever fills the role now — or to the operators when nobody does. A pending credential ask moves only to a single new person. An ask the platform addressed to a named person never moves. An answer or cancellation sent from a card that was read before the move is refused with 409 readdressed, so it cannot land on an ask that now waits for someone else.

Who a card waits for. When you try to decide a card that is not addressed to you, the refusal (403 not_addressee) says who it waits for: the seat and, on a gated-skill approval on the Operations page and the mobile admin, the people in it. An ask addressed to a role names only the role, never a person. An admin may still end such a card, but must give a reason (422 reason_required without one), and bulk cancel skips those cards and reports them as skipped_fenced. To move a card instead, an admin can re-run the rule that addressed it, or, for approvals the platform raises itself, take it to the admin seat — POST /api/operator-queue/{id}/readdress (below). There is no way to pick a person by hand.

Asks raised in a room. An ask an agent raises during its turn in a room is addressed as usual, and the room records it: one line when it is raised ({agent} asked: "{title}" — waiting on {who}) and one when it ends. The lines name a person only if they are seated in the room. When the ask is answered, the agent continues in that room — a room turn with the ending, its reply posted there — if the room is open, the agent is still in it and the room is under budget; otherwise it is woken the ordinary way.

What that person sees in the Workspace:

•Every ask waiting on the person is in their Workspace Inbox (the Action tab, which can be narrowed to one agent). An ask raised during a chat turn appears as a tile inside that chat's conversation, placed where it was asked, and you answer it right there; once it has ended it stays in that chat's history as one muted line (kind · title · how it ended · when). An ask raised outside any chat — by a scheduled run, a loop or a gate — appears in no chat, only in the Inbox; your reply to it lands in your Main chat with that agent. Exception: an ask raised from a reminder the agent set during your own session appears as a tile in your Main chat directly. The agent's Work tab (platform users) and Info tab (everyone) carry one line, N asks waiting on you · Open in Inbox, and the agent's rail has an Asks tab listing those asks one per line, newest first — a row opens the ask in the Inbox; with nothing waiting, the tab says so and offers Open the Inbox.
•The sidebar header counts them (N asks are waiting on your answer), and the agent's row carries its own badge — distinct from the unread-replies count, and never hidden behind Show all.
•The controls are the same three as the Operations page: option → optional note (Add a note (optional)…) → Send, or Something else (or start typing with no option picked) → instruction → Send; a typed answer → Send; Got it for an alert.
•Discuss (on an approval or a question) opens a chat with the agent about that ask, titled after it, so you can ask "why?" before you decide. The ask stays pending and is still answered on its own card, which heads that chat. One chat per ask: clicking again shows Continue discussion and reopens the same chat. If you answer after discussing, and the owner has turned on the wake, the agent's result is posted into that discussion chat.
•Dismiss (on an approval or a question) ends the ask without answering it — for an ask that needs no decision. There is no confirmation: the card shows Dismissed — the agent hears nothing until this closes. with an Undo for 5 seconds, then the dismissal is sent. The agent reads it as dismissed with an empty answer and is told not to raise the same ask again straight away; an agent set to wake when its asks end is woken once.
•Answering clears the ask from every count at once, keeps it on the card as Answered by you, and shows a short confirmation: Sent., or Sent — {agent} is picking this up. when the owner has turned on the wake.
•An ask that ended — answered, dismissed, cancelled, replaced or withdrawn by the agent, or expired — stays listed in the Inbox for 7 days with how it ended (by you, by the operator, by the platform, by the agent, or expired) and when, without answer controls. An ask you answered says which way: You approved / You rejected on the card (with Your note: … when you added one), Approved · you / Rejected · you on its row; any other answer is quoted. A withdrawn ask carries the agent's one-line reason under its ending; a replaced one names the ask that replaced it; in the chat that raised it, it stays as a muted line for as long as the queue keeps it. It is not silently removed, and it drops out of the count. The operator's reason for cancelling is never shown to you.
•The Workspace refreshes asks every 20 seconds while the tab is visible. It reads at most 200 asks, pending ones first and the longest-waiting of those first, so a very long queue drops the newest asks, never the ones that have waited longest; a note under the list says so when the cap is reached.
•A credential ask (raised with ask_for_credential) shows a masked secret field instead of an answer box; the value goes to the agent's environment and the ask reads NAME provided. It has no Discuss, and the Operations page cannot answer it — see Credential Management.

An ask is answered through the Workspace's own route (below), which records the answer with the same write-back, audit fields and wake-on-answer behaviour as an operator's. A client whose share was revoked stops seeing the ask.

Workspace Inbox with an agent's approval ask open: the question, the proposed action for each option, the option buttons with Something else, an optional note, and Discuss / Dismiss
An approval waiting in the Workspace Inbox (Action tab), with its proposal and answer controls.

Gated-Skill Approvals

When the owner marks a skill on an agent Requires approval (see Skills and Playbooks), Trinity itself raises the approval. Any request that names the skill — from a person, another agent, a schedule, a channel or a public link — is held before the agent sees it:

  1. The requester is answered at once with 202 and status: "pending_approval", a request_id and a message saying the request is waiting. The UI shows that message instead of an error. A held scheduled run or public-link turn is closed skipped with it; nothing runs yet.
  2. An approval card goes to the approver the gate names — the agent's primary contact, an approver role where the install provides one, or a role from the agent's canon (role:<id>) — but only to the people in that role who can open the agent: a platform account that owns it, has it shared or is an admin, or an email the agent is shared with. The card appears on the Operations page, the mobile admin and each approver's Workspace Inbox. When the role names people but none of them can open the agent, nothing is raised and the request is refused with 422 approver_cannot_open_agent, naming the role and the remedy (share the agent) — never a person; when only some can, the ask goes to those.
  3. Only a person the card is addressed to can approve. In the Workspace, Approve or Reject sends in one click, so type any note first. An admin it is not addressed to can cancel it but never approve it: their Approve is refused on the card (403 not_addressee), and the card shows no controls to anyone who cannot decide — it says who it is waiting on instead (the approvers' names on the Operations page, the role on a Workspace card). There is no Something else. The gate's deadline defaults to 24 hours.
  4. Approve runs the request once, exactly as written, as a new execution. Reject, an expiry or a cancellation runs nothing. The note you type beside Reject is the reason: it is quoted to the requester on one line (up to 500 characters), marked as the approver's words.

The approval card. The same card is drawn on the Operations page, the mobile admin and in the Workspace (the Inbox pane and the chat tile). It shows the Agent that would run the skill; each Skill with its description; the Input — the frozen text Approve runs, folded past a few lines with Show the whole input; Also sent — context lines the agent would also receive, when there are any; Requested by — a person by email (or by username for an account with none, such as the built-in admin), Agent …, A schedule, A messaging-channel user, A public-link visitor, A room conversation, A paid caller or A connector client; when it was Raised; and the Deadline. A person's request sent from the Chat tab or /m with earlier turns as context leads with the message typed that turn as Request, and the whole text follows as Full input, never folded. A viewer who can decide reads Approve runs it once, exactly as written. Reject runs nothing.; anyone else reads Waiting on. Once decided, the card carries the outcome as a badge and a sentence — Approved (the run is starting or in progress), Ran (finished successfully, or did not succeed), Rejected, Expired (an expired approval counts as a rejection: nothing was run), Cancelled, Stale (the skill changed after it was asked), Not run or Not confirmed. The links from this run (the requester's run) and Open the run(the approved run) appear only for a platform user who can open that run's agent — never for a Workspace-only member or an external client.

The approver asking for it. When the approver themselves asks — signed in, or with their own user key — the skill runs at once and is marked Ran without approval. A Workspace session that a trusted backend opened on someone's behalf (a delegate session) does not count: its gated requests wait for approval like anyone else's.

What the requester hears. Notices lead with the outcome in a few words — Approved, now running, Finished successfully, Failed, Cancelled, Rejected, Expired, Not run or Not confirmed— so they read apart even when clipped to two lines.

•An agent that asked through MCP (chat_with_agent, a fan-out) reads pending_approval with the request id and is told not to retry. It then gets a platform task (trigger skill_gate) when the request is decided, and a second one when an approved run ends, naming the execution, its status and a short quote of the run's reply or error (at most 1,000 characters, marked as the run's output). The quote shows whether a run that ended "successful" actually did the work.
•A person gets the same two notices in their Workspace Inbox. A person who decided their own request is not told of that decision. A rejection's notice, to an agent or a person, ends with the approver's reason when one was given (Reason given: “…”).
•An agent that asked while answering a conversation — a Workspace chat, Slack or Telegram — is woken with the ending (rejected, expired, not run, finished or failed), writes its reply, and that reply is posted into the conversation it was answering, like any background completion. In a Workspace chat the message is headed Approval update, not Finished, because the request may have been rejected. The approved, now running wake-up posts nothing there.
•Schedules, channel users, public-link visitors, paid callers and connector keys get only the request id in the immediate answer: if approved, it runs as a new execution on the agent; nothing more is sent.
•No notice names the approver by email: a platform requester sees the approver's display name, everyone else the agent's approver.
•An approved run's result goes back to the Workspace thread or channel conversation the request came from.

From the Chat tab. A held message and its notice stay in the conversation and are saved with the chat session, so a reload keeps them. Reopening the conversation shows how the request was decided in the notice line, and for a finished run the same text the Inbox notice carries — its status and a short quote of the run's reply or error, so a run that ended success while the agent declined the work reads as such; a cancelled or skipped run reads Cancelled / Skipped. Nothing is pushed to an open tab. Re-sending the same message while it is still waiting returns the same request instead of raising another approval, and held messages are left out of the history later turns send.

Held requests are never replayed. Whatever was decided, a request the gate held or refused — and the platform's notice about it — never reaches a later turn's prompt: in Workspace chats, public links, Telegram groups and rooms as on the Chat tab. People still see both in the conversation. The only way a held request runs is Approve, which runs it once. In a room, the card shows the posts that invoke a gated skill and the requester's latest post, each line prefixed with its sender, and the requester reads A room conversation; a long post by someone else in the room does not make a short request too long for the card.

Refusals. A gated request can also be refused outright, with nothing raised: nobody fills the approver role (422 role_unassigned), the people who fill it cannot open the agent (422 approver_cannot_open_agent — share the agent with them), the skills need different approvers (422 mixed_approvers), the request is too long for the card (422 request_too_long), the skill is missing or ambiguous on the agent (409), too many requests are waiting or arriving (429 approval_queue_full / approval_rate_limited), or the gate settings cannot be read (503 gate_unavailable). Asking again after a decision returns that decision (409 request_<state>), never "pending". A voice call refuses a gated skill and says to ask in chat instead.

Authoring Limits

Trinity holds items an agent raises to a few hard limits, so that each one is a single decision a person can take at a glance:

LimitDefaultSettingRefusal
Options per approval (Something else not counted)5OPERATOR_QUEUE_MAX_OPTIONStoo_many_options
Characters per option60OPERATOR_QUEUE_OPTION_MAX_CHARSoption_too_long
Characters in the title120OPERATOR_QUEUE_ASK_TITLE_MAX_CHARStitle_too_long
An option that imitates Something else——invalid_options

ask_operator refuses an item over a limit with a 422 that names the code and the limit in force, and nothing is filed. A queue-file entry over a limit is held: it stays pending in the file, no queue row is created, and the file's platform.ingestion block lists its id under invalid_options or invalid_title beside max_options, max_option_chars and max_title_chars. Fix the entry and the next sync admits it. An admin can raise each limit in .env; each has a floor (2 options, 16 characters, a 40-character title).

Volume limits. Each agent may have at most 25 pending items of its own (OPERATOR_QUEUE_MAX_PENDING_PER_AGENT), and may create at most 60 per minute (300 per minute across the fleet). Over a limit, ask_operator answers 429 queue_full or 429 rate_limited; a queue-file entry is held rather than dropped and admitted on a later cycle, and the file's platform.ingestion block says why. Trinity files one queue floodheads-up per episode — a second needs the condition to clear first. Platform heads-ups never count toward an agent's own 25.

Bulk Operations

The Operations page offers a per-tab Clear All that hides resolved items, and pending items can be bulk-cancelled. A cancelled item's agent sees it marked cancelled in its queue file on its next turn, and running agents set to wake when their asks end are woken once. Because cancellation can race with a response, submitting a decision — or a cancel — returns 409 if the item left the pendingstate in the meantime (for example, it was cancelled by a bulk operation) — refresh the queue and re-check before retrying.

From a Phone

The mobile admin at /m answers the same queue with the same three controls.

Real-Time Notifications

WebSocket events fired along the way:

•operator_queue_new — when the item arrives
•operator_queue_responded — when someone decides
•operator_queue_cancelled — when someone cancels it
•operator_queue_acknowledged — when the agent confirms it saw the decision

For Agents

Approvals share the operator-queue API surface:

EndpointMethodDescription
/api/operator-queueGETList queue items (filter by type=approval)
/api/operator-queue/{id}GETGet a single item
/api/operator-queue/{id}/respondPOSTSubmit the decision — {response, response_text?, acknowledge_divergence?}. A person only (403 person_required for an agent's or the system key). 422 when an approval's response is not an offered option (response_not_an_offered_option), or is (something else) without an instruction (instruction_required), on a non-approval (reserved_value) or on a gate approval (not_off_menu); 409 when the item is no longer pending, 409 expired past its deadline, 409 item_diverged when the agent changed or closed the item (send again with acknowledge_divergence: true to answer anyway)
/api/operator-queue/{id}/cancelPOSTCancel a pending item — optional {reason} (≤ 500 characters), required (422 reason_required) when an admin ends a card addressed to someone else. A person only; 409 when the item is no longer pending, 409 readdressed when it moved to someone else after you read it
/api/operator-queue/bulk-cancelPOSTCancel listed pending items — {ids, reason?}; returns {cancelled, skipped, skipped_fenced, batch_id} (skipped_fenced: cards addressed to someone else). A person only
/api/operator-queue/{id}/readdressPOSTMove one pending card — {to: rule | admin, reason}. rule re-runs the rule that addressed it; admin takes a platform-raised approval to the admin seat (never a gated-skill approval). An admin, as a person only; the reason is required. 409 audience_unchanged when nothing would move, 409 rule_refused when the rule finds nobody
/api/agents/{name}/operator-queuePOSTRaise an item as the agent itself — {request_id, title, question?, type?, options?, priority?, context?, proposal?, to?, expires_at?, supersedes_expired?, replaces?}, with the agent's own key only (403 agent_identity_required otherwise). 201 with a receipt (the role it went to, never a person's email); 200 with the first receipt when the id was already used; a named 422 for a malformed item or one over the authoring limits (too_many_options, option_too_long, invalid_options, title_too_long), 429 rate_limited or queue_full. An item raised during a Workspace chat turn attaches to that chat
/api/agents/{name}/operator-queue/{request_id}GETAn agent's OWN item by the id it chose — with the agent's own key only (403 agent_identity_required otherwise). How it stands and how it ended, including agent_ending (replaced or withdrawn when the agent ended it itself); no person's email. Still readable after Clear All
/api/agents/{name}/operator-queue/{request_id}/withdrawPOSTWithdraw one of the agent's OWN pending items — {reason} (1–500 characters, whitespace collapsed), with the agent's own key only. 200 with a receipt (status: "withdrawn", or replayed when the agent already withdrew it; a different reason is reported in differs, never applied); 404 ask_not_found for an unknown item, another agent's, a gate's or the platform's; 409 ask_ended when a person answered or ended it first; 422 invalid_reason. A queue-file entry cannot be withdrawn
/api/operator-queue/agents/{name}GETItems scoped to a specific agent
/api/operator-queue/statsGETCounts by status, type, priority and agent, over the agents you can access
/api/operator-queue/clear-resolvedPOSTHide acknowledged, cancelled and expired items — optional {agent_name}; returns {cleared}. Answered items still waiting for the agent to acknowledge them stay listed

Asks addressed to a Workspace user are read and answered as that user, under the Workspace prefix (a Workspace session token or a platform JWT; agent keys are refused):

EndpointMethodDescription
/api/enterprise/client-portal/asks?agent_name=&include_ended=&chat_id=GETOpen asks addressed to the caller, optionally narrowed to one agent; include_ended=true adds the ones that ended in the last 7 days; chat_id returns the asks raised during a turn of that chat, plus the ask that chat discusses, ended ones included with no 7-day limit. Each carries kind, title, question, options, proposal, expires_at, status (pending, answered, dismissed, cancelled or expired), ended_at / ended_by (you, operator, platform or timeout), the chat_id it belongs to, raised_in_turn (whether a chat turn raised it), discussion_chat_id (the chat that discusses it, once opened), answer / answer_note (your own answer and note, only on an ask you answered), agent_ending / ending_reason (replaced or withdrawn when the agent ended it, with the agent's reason for a withdraw only) and gate (the platform's view of a gated-skill approval — the skills, who asked, who it waits on, whether you may decide, how it ended)
/api/enterprise/client-portal/asks/{id}/answerPOSTAnswer one — {response, response_text?}. A person only: the platform's system key gets 403 person_required. Returns the ask with status: "answered" and resume_requested (whether answering started a turn). 422 empty_answer / response_not_an_offered_option / instruction_required / reserved_value / not_off_menu; 409 expired; a missing or not-yours ask is a uniform 404
/api/enterprise/client-portal/asks/{id}/dismissPOSTEnd an ask without answering it. A person only; 60 per minute. Returns the ask with status: "dismissed"; an ask that already ended comes back as it stands with a 200
/api/enterprise/client-portal/asks/{id}/discussPOSTOpen, or continue, the chat that discusses this ask — {chat_id, agent_name, title, created, ask} (created: false when it continued an earlier one). A person only; 30 per minute. 422 not_discussable for an alert; 409 already_resolved when the ask ended before a chat was opened
/api/enterprise/client-portal/asks/{id}/contextGETWhere the ask came from (its chat, and the three messages before it when the chat is yours), the run that raised it (schedule, loop, turn, …), and your recent answers to this agent. No cost and no execution id. 120 per minute

See the Operating Room doc for the full queue model.

MCP Tools

Agents can inspect the queue and resolve a pending item programmatically:

ToolDescription
list_operator_queueList queue items, broad or filtered by agent_name. Returns count, total, has_more, next_cursor and next_offset; page with cursor="start", then cursor=next_cursor until has_more is false. null means not verified
get_operator_queue_itemFetch a single item by id
respond_to_operator_queue(item_id, response, response_text?, acknowledge_divergence?)Submit the decision for a pending item, with a person's own API key — the same rules as the respond route: response must be an offered option or (something else) with the instruction in response_text, an item that is no longer pending (or past its deadline, or changed by the agent without acknowledge_divergence) returns a structured error, and an agent's key is refused
ask_operator(request_id, title, …)The calling agent raises an item as itself and gets a receipt: whether it was created or replayed, the role it went to, and wakes_on_ending (whether the agent will be woken when the item ends). expires_at needs a timezone and must be at least 15 minutes out; a re-ask names the expired item in supersedes_expired; replaces names one of the agent's own pending items, which ends as replaced when the new one is created (409 replaces_ended if a person answered first, 409 already_pending if the same action is still pending and not replaced). to names a role (primary, approver, viewer, operator), a canon role (role:<id>) or project — see Asks addressed to a Workspace user. The tool description carries five authoring rules — one decision per ask, a one-line title, options that name the choice only, few options, and context written for people — and the authoring limits are enforced. A refusal comes back as {success: false, status, code, message}. Acts as the agent the key belongs to — there is no agent parameter
get_my_ask(request_id)The calling agent reads back one of its own items by the id it chose: status, the answer, and how it ended (disposition — answered, cancelled, dismissed or expired — disposed_at, disposed_by, and disposition_reason: the operator's cancel reason, the agent's own withdraw reason, or outcome_unknown on an expired approval; agent_ending says which ending the agent authored, replaced or withdrawn). Acts as the agent the key belongs to — there is no agent parameter
withdraw_ask(request_id, reason)The calling agent ends one of its own pending items that no longer needs an answer, with a one-line reason and no successor — for an approval, a question or an alert. The person asked sees the reason as history. Idempotent by request_id; refusals come back as {success: false, status, code, message} — 409 ask_ended (a person answered or ended it first, or it expired — read the answer with get_my_ask), 404 ask_not_found (not one of its own asks), 422 invalid_reason (blank, or over 500 characters). Acts as the agent the key belongs to — there is no agent parameter
ask_for_credential(name, why)The calling agent asks the person in the current conversation for a secret by name. The person types it into a masked field in their Workspace; it is stored in the agent's environment and the agent is told only that it was provided. Refused with no_person when no single person can be named, with role_cannot_open_agent when neither the primary contact nor the owner can open the agent in their Workspace, and with invalid_credential_name for a malformed or reserved name

Agent-scoped API keys see only items for the calling agent itself plus agents it has been explicitly permitted to access. Answering and cancelling are a person's act: an agent's own key — or the system key — is refused (403 person_required), so an agent can never approve its own request. The two endings an agent can author are replacing one of its own pending items with a newer one (replaces) and withdrawing one it no longer needs answered (withdraw_ask); both are refused once a person has answered (409 replaces_ended / 409 ask_ended). The platform tells every agent to withdraw what is moot rather than let it expire, and the Execution Context's list of pending asks says so when it carries one the agent raised. Only a person (a browser session or the person's own API key) reads a whole queue row. An agent's key, the system key and other machine keys get the row without any person's identity — no answerer's email, no addressee, no name of who ended it — and never see the platform's heads-ups about a person (such as a Workspace client's complaint). The answer written back into a queue file carries response, response_text and responded_at, not who answered. Every turn's Execution Context also lists the agent's items that ended in the last 24 hours (ids, how and when — no text), so an agent that slept through an ending still learns of it, and the items it is still waiting on (oldest first, at most 8), so a scheduled run does not ask again what is already pending.

Limitations

•An ending wakes the agent only when its owner has turned the wake on; otherwise it waits for the agent's next turn. A stopped agent is never woken (the skip is recorded in the audit log); it reads the ending when it next runs. If the agent has neither a schedule nor a heartbeat, the agent is expected to say in the request how it should be re-triggered.
•The wake is a per-agent switch, never per request — an agent cannot decide that ending its request costs someone a turn. Only the agent's owner or an admin can change the switch, and an agent's own key is refused.
•A wake that fails after the ending was recorded shows as a failed execution and an audit entry on the operator side; the Workspace confirmation reports the intent to start work, not its outcome. A wake that was due when the platform restarted — for an answer, a cancellation or a dismissal — is offered again once the platform is back, one turn per running agent; an expiry still wakes nothing.
•Items the platform raises itself (heads-ups, alarms) never wake an agent, and neither does cancelling an item the agent had already closed on its side.
•The approver and viewer roles are refused until someone fills them; address such an item to primary or operator for now.
•Ephemeral agents keep raising items through the queue file until they get the native path.

See Also

•Operations Page — The unified fleet-operations view where approvals surface (Needs Response / Notifications / Resolved tabs).
•Mobile Admin — Answering the queue from a phone.
•Workspace — Where an addressed ask reaches its person.
•Agent Configuration — The per-agent wake switch.
•Scheduling — Automated triggers that often request approval before destructive actions.