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/inboxspans every program you belong to; the program home shows the same list filtered to that program; the daily brief (/me/briefand thedigeste-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
| Symptom | Cause | Fix |
|---|---|---|
| Approve is disabled with a permission key | you lack the write’s own permission | the decision belongs to the persona that holds it; send a hand-off instead |
403 bound_user_only | you opened a colleague’s twin proposal from their thread | only the bound person (or their active delegate, for write approvals) decides; oversight readers read |
409 stale_proposal | the record changed since the proposal was filed | read the diff; let the twin re-file on its next pass or make the change by hand |
422 on decline | no reason given | write the reason; it is stored as evaluation data |
422 on a batch | a top-level decision was sent, or items[] on a single proposal | batches take items[]; single proposals take decision |
| “Filing paused: N decisions waiting” | more than max_open_items are open | decide or dismiss items; filing resumes on the next pass |
Related
- How to enable your twin.
- How to delegate while away.
- Console reference for the batch card and the resolve path.
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