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.
How to require approval for a skill
1:138 chapters
Anything irreversible waits for a person
2:0910 chapters
Trinity Platform Demo — operator queue & approvals
May 2026
Trinity Roles & Permissions Explained — primary, approvers and where approval requests go
Nov 2026
Concepts
approval (a yes/no or multi-choice decision), question (freeform guidance), alert (acknowledgement only). Created by the agent, consumed by a person.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.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.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.critical, high, medium, low. Affects sort order in the queue.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.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.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_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.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.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
The agent reaches a step that needs authorization.
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.
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.
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).
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.
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).
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.
| Badge | Meaning |
|---|---|
| Changed by the agent | The agent rewrote the item after it was ingested. You are reading the original. |
| Closed by the agent | The agent closed the item on its side; it still waits for you here. |
| Gone from the agent | The agent's file no longer carries the item. |
| Re-used id | The agent used the id again after the item closed; the new entry was not admitted. |
| Unconfirmed | The 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 delivered | Your 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. |
| Waiting | The 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:
OPERATOR_PLATFORM_ALERT_LIFETIME_DAYS). An expired heads-up reads Expired — nobody acted on it.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:
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.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.

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:
- The requester is answered at once with
202andstatus: "pending_approval", arequest_idand 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. - 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 with422 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. - 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. - 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.
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.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:
| Limit | Default | Setting | Refusal |
|---|---|---|---|
| Options per approval (Something else not counted) | 5 | OPERATOR_QUEUE_MAX_OPTIONS | too_many_options |
| Characters per option | 60 | OPERATOR_QUEUE_OPTION_MAX_CHARS | option_too_long |
| Characters in the title | 120 | OPERATOR_QUEUE_ASK_TITLE_MAX_CHARS | title_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 arrivesoperator_queue_responded — when someone decidesoperator_queue_cancelled — when someone cancels itoperator_queue_acknowledged — when the agent confirms it saw the decisionFor Agents
Approvals share the operator-queue API surface:
| Endpoint | Method | Description |
|---|---|---|
| /api/operator-queue | GET | List queue items (filter by type=approval) |
| /api/operator-queue/{id} | GET | Get a single item |
| /api/operator-queue/{id}/respond | POST | Submit 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}/cancel | POST | Cancel 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-cancel | POST | Cancel 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}/readdress | POST | Move 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-queue | POST | Raise 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} | GET | An 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}/withdraw | POST | Withdraw 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} | GET | Items scoped to a specific agent |
| /api/operator-queue/stats | GET | Counts by status, type, priority and agent, over the agents you can access |
| /api/operator-queue/clear-resolved | POST | Hide 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):
| Endpoint | Method | Description |
|---|---|---|
| /api/enterprise/client-portal/asks?agent_name=&include_ended=&chat_id= | GET | Open 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}/answer | POST | Answer 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}/dismiss | POST | End 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}/discuss | POST | Open, 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}/context | GET | Where 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:
| Tool | Description |
|---|---|
| list_operator_queue | List 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_item | Fetch 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
approver and viewer roles are refused until someone fills them; address such an item to primary or operator for now.