Omniscio

CLI Pending Actions (approve external AI changes) (part 2)

Part 2 of the CLI Pending Actions page: what happens after you decide — how the session that asked is told your answer, what the queue does when a card is never answered, which settings can never be patched from outside, the note rules, the in-app bypass, and the ready-mint override card.

On this page

What it is

This is part 2 of the CLI Pending Actions (approve external AI changes) page. It covers everything that happens around the approval click rather than the card itself — how the asking session is told your decision, what the queue does when a row is never answered, the settings that can never be changed from outside, the rules around the note that travels with a request, and the one kind of card the app raises itself.

Where to find it

Same inbox, same cards — this part is about the behaviour around them. The note that must accompany an external settings change is attached by the calling AI rather than set anywhere in the app, and the override card for a tagged branch arrives in the same Approvals section as every other row.

How it behaves

The session that asked gets told

When you approve or reject a request a session made, that session is told the outcome — so the agent isn't left guessing. An approval that started nothing says so. When the action was deliberately skipped — a Nighty Tidy re-run refused because a run of that audit is already going, or one refused because tonight's audit spend cap is reached — the notice reads "The user approved … but nothing was started. Reason: …" and the card carries it as its own not-started row, instead of the bare approval sentence that used to read as though the work were under way. If the source session is still live or waiting on you, a short notice appears right in its conversation ("The user approved the request you sent to their inbox — …" / "The user declined …"), rendered as a tagged "injected by Inbox" bubble, and the session wakes so the agent can react to your decision. If that session has already finished (ended, archived, or errored), nothing is injected — Omniscio never resurrects a done session just to deliver a notice. A request with no originating session (a cron-raised card, an outside curl with no session id) simply has no one to notify. One notice per triage sweep, not one per click. When a single session queued several cards, Omniscio holds each decision back while that session still has cards waiting on you, then sends one message covering the whole sweep — “The user approved 3 requests …” with each request listed, and approvals and declines split into their own groups when you did some of each. Deciding the session’s last card is what releases it, so the everyday single-card case still goes out immediately, exactly as before. Approving three cards used to wake the agent three separate times: the first notice starts a turn, so the next two arrived mid-turn and each forced another interruption to learn one thing. If you handle one card and leave the rest sitting, a 30-second backstop sends what you have already decided so nothing is stranded. This is the reverse of the "Generated by ‹session›" line on the card — the loop closes both ways. Only a decision you actually made is reported. When Omniscio applies a request without you seeing it — an action that isn't gated and applies the moment it arrives, or one cleared by an Always allow you set earlier — nothing is announced to the agent as your decision, because you never made one. The notice marks your click, not the app's. Operators can turn it off with the AMC_DISABLE_APPROVAL_DECISION_NOTIFY=1 env var. Single-source-of-truth: invariant I15 in session-provenance-contract.md.

An approved action that a restart cut off

If Omniscio restarts after you approve something but before it finished, it never runs that action again on its own — doing it twice could cost money or cannot be undone. Instead each such action gets its own inbox card that names it ("Did not run after a restart: …" or "Interrupted by a restart: …"), who asked for it and when. An interrupted one may or may not have happened, so the card says to check first. A card raised for a session carries an Open the session button so you can have that session ask again; one with no session says there is nothing to open. An action whose effect is recorded as done raises no card, nor does one that was applied straight away without asking you, and one Omniscio could safely replay simply runs. The cards come from src/main/services/cli/cli-pending-reconcile-dropped-alert.ts, raised by the startup reconcile in cli-pending-dispatcher.ts.

What if I miss the row?

The row stays in the inbox until you approve or reject it. There is no auto-expiry — pending rows live indefinitely. If you forget about them, the queue cap will eventually start blocking new external requests until you triage. The external AI can also cancel its own queued row via DELETE /cli-pending/:id (see omniscio-control skill).

What CAN'T be patched via CLI

The generic settings route does not accept every key. Examples in the current server policy include:

  • cliServerEnabled - the control server's own switch.
  • requireGlobalAuth - an owner-held sign-in setting.
  • pluginSettings - plugin settings use their dedicated route.
  • Secret keys in CLI_SETTINGS_SENSITIVE_KEYS - credentials use their encrypted save routes.

A non-patchable key normally returns HTTP 400. An eligible person-held key with a requesting session can instead raise an owner-decision card. Follow the response for the specific key; these are not all unconditional refusals. The exact list lives in cli-settings-patch-policy.ts, and the card/refusal branch lives in cli-server-settings-routes.ts.

Every CLI settings change must name its session

An external (command-line) settings change has to say which session requested it, by sending its X-AMC-Source-Session-Id. A request that doesn't identify a real session is refused (HTTP 400) before any inbox row is created — so a "Settings change" approval in your inbox always names the agent that asked for it, and you never get an anonymous one. This is a hard rule with no off-switch. (Omniscio's own agents send their id automatically; keyboard-shortcut keys are exempt — they apply immediately and never reach the inbox.)

Attach a reason with X-AMC-Approval-Note (optional)

An external AI attaches a short free-text reason to an approval it creates, by sending an X-AMC-Approval-Note header with the request — e.g. X-AMC-Approval-Note: the user asked to switch to the dark theme. Omniscio stores it on the approval and surfaces it as a labeled Note — the last labeled row of the approval's details, in the same bordered card as its other facts — so you see the concrete change first and why the agent is asking last. It is the agent's stated reason, never Omniscio's verification — the pane still shows the concrete change and which session requested it.

For a settings change (PATCH /settings/:key) the note is required and must be concise: an external AI's queued settings change with no note — or with a note over 200 characters — is refused (HTTP 400, nothing queued) so a "Settings change" in your inbox always explains itself in a short one-liner. An over-long note is refused, not silently trimmed — shorten it and retry. There is no off-switch. For every other approval kind (sends, deletes, spawns, tags…) the note is still optional (no note → no Note field) and isn't length-capped beyond a 1024-character safety bound. The note is sanitized and informational only — it never changes what the action does. Your own in-app UI is exempt (a person changing their own setting isn't asked to write a note), and approvals Omniscio raises itself (a cron failure, a budget warning) have no requesting agent, so they carry no note. Single-source-of-truth: approval-note-contract.md.

In-app session bypass

When an in-app Claude Code session (one Omniscio itself spawned) calls PATCH /settings/:key using its own session token, an ordinary patchable key applies inline — no inbox row, no approval prompt. This is intentional: your in-app sessions are already running with your permission, so adding a second layer of approval would be redundant. The bypass only works for the in-app token path; other callers follow your settings-approval preference and grants. The five control-plane keys in NON_TOGGLEABLE_SETTING_KEYS still require the approval path, including for in-app sessions.

The ready mint's override card (2026-09-08)

One row kind is raised by the app itself rather than by an AI: worktree.ready_override — the card titled Approve tag over red evidence. When a session runs the ready mint with an override on a branch whose evidence gate is red — or whose roadmap-claim or tracked-ignored check refuses (those mint-only content checks bind the same card, one card naming every check it waives; the i18n code-proof and the memory-doc cap take no override at all — the auto-lander enforces the i18n proof at land with no waiver, and the memory-doc character cap is advisory only, retired 2026-10-11 with the doc-read card, so nothing about doc size ever blocks a land) — the ready mint refuses (403 override_not_permitted) and raises this card, bound to that branch at that exact commit with the checks being waived and the reason. Approving it is the ONLY way an override can be minted on these checks: a token of any kind — including the global CLI token every session reads — is refused until a person clicks Approve. guard-loosening is stricter still: a branch that loosens a guard or a baseline is human-only (2026-11-06). No automatic approval grants it — not the agent's own --human-override, not the owning session, not the standing auto-approval — and no card is raised for it: the mint refuses 403 override_not_permitted with nothing recorded, and tells the agent to ask the owner in chat as a lettered question naming the guard, then record the owner's exact words with the owner-ready command. An approval a person already gave for that exact commit still counts. The same command re-run then stamps the tag, spending the card once (override-approval: [<id>] rides in the tag), and the auto-lander verifies that card before landing. A new commit needs a new card; rejecting the card is an answer, so no replacement is raised for that commit. Only YOUR rejection counts that way: a card the requesting session withdrew, one cleared without a decision, one that aged out or one the app refused is nobody's answer, so the next --human-override raises a fresh card (before 2026-10-22 any closed card blocked that commit). One red is outside every override: when the evidence names a failing test in a guard security suite (the git-guardrails self-grant, push-approval-grant and overblock suites, or any test titled [SECURITY]), the mint refuses 403 override_cannot_excuse_security_suite and raises no card at all — a security red is a live hole to fix, never debt to approve past, and the auto-lander refuses such an override tag at land too. It never appears in the "Always allow" list — its stand-down is a separate setting, not a CLI approval family.

That setting is autoApproveAgentReadyOverrides (default OFF; Dev Pipeline → Setup → Auto-lander, or PATCH /auto-lander/ready-override-arming with the machine's own full-trust CLI token — PATCH /settings/:key refuses it, and so does a scoped per-session agent token). Turn it ON and the mint approves the card itself instead of waiting for the click, including one that was already sitting pending from before the flip. Everything else holds: the card is still raised, still bound to that branch at that commit with those checks, still consumed once, and the auto-lander still verifies it before landing. An auto-approved row carries an [auto-approved — no human click] marker in its preview text so it is never mistaken for a click, and a card you REJECTED is still refused. If the setting cannot be read the mint refuses and raises the card, so a settings fault can never start auto-approving.

A terminal asking to act as you (2026-10-23)

When you run a repo script in a plain terminal, it has no session to name. If the step it is on needs your identity (reading a crew approval, holding a branch while it is checked), the script raises one card, Let a terminal on this computer act as you, and waits up to five minutes. The card names what the terminal wants to do, and the reason the requesting program gave appears only as a quoted line introduced as The requesting program says and labelled as that program's own words, never in the app's voice, so a forged sentence cannot pass for the app's own; it tells you to approve only if you just ran that command yourself, and "Generated by" reads A terminal on this computer. Approving gives that one terminal 15 minutes on the few steps that accept it. Declining, or leaving the card, stops the script with a plain message, and an unanswered card is withdrawn. If the terminal is closed or the app restarts, the card removes itself within ten minutes or at the next app start, because nothing is left to approve. You can turn this card off in Settings → CLI Control → Approval requirements or with the card's "Always allow"; "Approve all" never approves it, and an agent session is never offered this card. Every approved terminal leaves a lasting record of when it was approved, what it asked to do and in which repository and branch.

The cards themselves — what one looks like and how you answer it — are on the CLI Pending Actions (approve external AI changes) page, and the server these requests arrive on is CLI Control.

Last verified 2026-11-16