Skip to Content
PlatformHow-to guidesDecide from your inbox

How to decide from your inbox

Use this guide when your twin, a colleague’s hand-off, an approval request or a mention has put something in your inbox. You start with items under “Decisions waiting for you”; you end with each item done and a record written or declined under your own permission, one decision at a time. Deciding needs the write’s own permission (for example evidence.findings.manage for a proposed finding); reading your inbox needs only a signed-in session. Every surface here carries the status word designed until the R3 gates pass.

Silence is always “not approved”. An item you never decide expires after the twin’s expiry_hours (default 72 h) and reads “Expired, nothing written”; the run that filed it stays succeeded, and your twin may re-file it on its next pass. Nothing is auto-resolved.

Prerequisites

  • Items in your inbox: /me/inbox spans every program you belong to; the program home shows the same list filtered to that program; the daily brief (/me/brief and the digest e-mail) links to it.
  • For a proposal, the permission the item names (the card shows it; the button is disabled with the key when you lack it).

Open the inbox

/me/inbox groups items as Signatures, Approvals, Questions, Hand-offs, Mentions, Information, then by program. Each row shows the kind, the record title where the thread rule allows it (otherwise “From a private thread”), the twin that proposed it (“Maya N.’s twin (agent) · scientist”, illustrative), its age and the permission it needs. With focus in the list, j and k move, Enter opens, e opens edit, Esc opens the decline dialog, x toggles selection; the keys are remappable or can be turned off in Settings.

Read the four panes

An item page (/me/inbox/[itemId]) shows Why now (the trigger: “entry EXP-0421 closed”, “SOP-BA-012 v4.0 became effective”), What it read (the run rail: tool calls, sources, documents fetched), What it will write (the proposal with its permission_exercised, sources and citation coverage) and What happens next (the consequence). A proposal whose record changed since it was filed is marked “Changed since proposed” with the diff and cannot be approved as it stands (409 stale_proposal).

Approve, edit then approve, or decline

Approve calls POST /me/inbox/{item_id}/resolve with {decision: "approve"}. The API checks that the item is yours (or routed to you under an active delegation), that you hold the write’s permission and, on a twin run, that you are the bound person; it then recomputes basis_hash, executes the write server-side from the stored arguments, recomputes approved_hash and writes the record and the audit row in one transaction. Edit then approve applies your edits before the hash and the record page later reads “edited before approval” with the diff. Decline needs a reason (“Declining needs a reason; it is stored as evaluation data.”). Nothing here resumes a container: a twin’s proposal is a stored write waiting for your decision.

Resolve a batch by selection

A batch_approval item (at most 10 proposals of one tool and target type) lists each item with an expanded summary and a checkbox. Tick the rows you want, choose Approve selected, and read the confirm sheet “Approve 8 checks with review.sops.manage” before confirming; the request carries items[{tool_call_id, decision, edits?, reason?}]. Every item is checked and audited on its own: one you may not approve fails with batch_item_forbidden while the rest proceed; approved items are written at once; declined items need a reason each; undecided items stay open until expiry and the card then reads “5 approved and written, 5 expired”. There is no “Approve all”. The result is announced (“4 approved, 1 declined”) and focus moves to the next item.

From the phone or the e-mail

The digest e-mail carries the record type, the program name, the id and a link only: no titles, no agent text, no token that acts, no approve-by-reply. The link opens the item after sign-in. At 390 px the inbox is the page: approve, decline with a reason and resolve batch items one at a time (“item k of N”); editing is desktop-only and the button says so; signing works after re-authentication.

Read what changed

The record carries origin = agent and the footer “Proposed by Maya N.’s twin (agent); decided by Maya N. on <date>” (illustrative). Setup › Audit shows the write with actor_kind = agent, interrupt_id, approved_by_user_id, permission_exercised, proposal_hash, approved_hash, twin_id, trigger_id and, for a batch, batch_id. The item is done and the twin panel’s count of accepted, edited or declined proposals moves by one.

Snooze, dismiss, feedback

Snooze (POST .../snooze {until}) hides an item until a time and is audited inbox.snooze; the hourly job un-snoozes it. Dismiss closes information and mention items. Not useful (POST .../feedback) is evaluation data for the twin’s daily evaluation, never a decision. When more than max_open_items (default 20) items are open, your twin stops filing and the brief reads “Filing paused: 23 decisions waiting”; nothing is dropped.

Troubleshooting

SymptomCauseFix
Approve is disabled with a permission keyyou lack the write’s own permissionthe decision belongs to the persona that holds it; send a hand-off instead
403 bound_user_onlyyou opened a colleague’s twin proposal from their threadonly the bound person (or their active delegate, for write approvals) decides; oversight readers read
409 stale_proposalthe record changed since the proposal was filedread the diff; let the twin re-file on its next pass or make the change by hand
422 on declineno reason givenwrite the reason; it is stored as evaluation data
422 on a batcha top-level decision was sent, or items[] on a single proposalbatches take items[]; single proposals take decision
“Filing paused: N decisions waiting”more than max_open_items are opendecide or dismiss items; filing resumes on the next pass

Source: PRODUCT-PLAN.md Part 7 sections 4 (persona inbox, backpressure), 5 (detached interrupts, resolve path, batch resolution, batch card control, mobile and e-mail paths) and 6 (keyboard and accessibility); PRODUCT-CONTRACT.md sections 11.4 and 11.7; api/scripts/designed-routes.json (/me/inbox routes); api/app/services/interrupts.py; api/app/db/models/inbox.py; web/lib/api/types.ts (InboxItemOut, InterruptResolve, InterruptResolveResult); web/lib/content.ts (consoleCopy, inboxKinds, inboxShortcutDefaults); decisions/0022-inbox-escalation-and-delegation.md

Last updated on