Omniscio

Settings patch approval (review CLI / AI proposed settings changes before they apply)

When something outside the main UI — usually an AI agent — tries to change one of your Omniscio settings, the change normally waits as a pending approval in your inbox, shown as a plain-language diff of exactly what the patch would do, with the setting's own description and its before and after. You approve to apply it or reject to discard it. A few narrow cases apply at once — any setting changed by a session Omniscio spawned, or a patch that would change nothing — and the whole approval gate is a switch you can turn off.

On this page

What it is

When something outside the main UI tries to change one of your Omniscio settings — typically an AI agent calling the local CLI control server, but also any external script driving the same endpoint — the change normally does not apply immediately. It queues as a pending approval that shows up in your inbox as a "Settings change?" item, and Omniscio renders the diff in plain language so you can see exactly what the patch will do before you click Approve. Reject and the patch is discarded; approve and the change applies. Several narrow exceptions skip the queue — any setting written by an Omniscio-spawned session, a patch that would change nothing, the repository's own setup profile, a keyboard-shortcut or Presentation / Demo-Look toggle, and any action you have marked "always allow". Everything else follows the approval path. An agent is not refused a setting because of what it does: nothing in the app is off-limits to an agent's request. A short list always needs your card, whatever your approval preference: the control-plane toggles and the safety, Lab and feature settings of the Hermes parity work (owner decision 2026-11-03). Only your own click can approve one of those cards, so a chat, Team Chat, an automatic approver and "Approve all" cannot, and a paired phone can reject one but cannot approve a change it is not allowed to make itself. A short set of keys is refused outright because another route owns the effect or you have held it for your own decision: secrets, plugin settings, the PR Janitor pause flag, sign-in, second-factor, network allow-list, paywall and consent-record settings, and the owner-only Pause all testing switch.

The point of the feature is to keep settings-by-API safe. Settings touch the whole app — your theme, your channel adapters, your AI Manager wiring, your Pomodoro defaults. An unaudited path that lets a script overwrite the entire aiManager blob is a foot-cannon; an audited approval pane with a plain-language diff is not.

Where to find it

Where it lives in the UI

A pending settings patch appears as a row in the CLI Pending inbox (toolbar bell → CLI Pending tab, or the right-rail dock). Click the row and the approval pane opens inline. The title is the whole ask — for example "Enable Decks?" — so the body never repeats the setting's name; it shows only what the title can't: a short line of what the setting does — the same plain-English description shown under that setting in Settings, reused so you don't have to know the setting to judge the change — followed by the concrete before/after, and a quiet line at the bottom naming the session that requested the change (clickable, so you can jump back to it). (Essentially every user-facing setting surfaces this "About" line now; a setting only omits it when it has no written description at all, and you still get the before/after either way.) You'll see one of these in the body, depending on what's being patched:

  1. A simple on/off toggle — a plain line like "It's currently off." (the title's "Enable …" / "Disable …" tells you the direction).
  2. A single value changing (for example theme) — the old value, an arrow, and the new value.
  3. A nested object changing some leaves (for example the aiManager blob where only router.enabled flipped) — a "Will change N field(s):" header, one bullet per changed path (router.enabled: No → Yes), and an "(M other fields unchanged)" tail so you can confirm the diff is complete. For settings keyed by an internal id — a per-project or per-provider default model, say — the field name is shown as a human label (Omniscio · Codex), never the raw project UUID or provider slug; a project that no longer exists reads as Unknown project rather than its id.
  4. A no-op patch — the payload happens to match the current value. The pane explicitly says "No effective changes — this patch matches the current value." so you don't reject a harmless re-apply by mistake.
  5. Prior value unavailable — the rare fallback when Omniscio can't reconstruct what the key was before the patch was queued. The pane shows the new value and a hint to open the technical-details expander.

How the title names the setting. A setting's name in the title comes from a short curated list first, then from the setting's own label in Settings, and only then from its key written as words. The curated list exists for settings whose Settings label would read badly after "Turn on": an agent asking to switch the Vault on is titled "Turn on the Vault?" rather than "Turn on Enable Vault?". The Vault's switch (nothariEnabled) is findable in Settings search as kms-enabled, which names that setting so the card can also show its "what it does" line.

How it behaves

A list or an object always shows its real contents

Whatever the setting holds, the pane shows what it actually is — never a placeholder count. A list of branch names reads main, develop, and release; an object reads Primary: red · Secondary: blue; and a setting that stores project references resolves each one to the project's name, so opting a repo into the auto-lander reads (none) → Omniscio · Enabled: on rather than the old, useless (none) → (1-item array).

Three rules keep that honest:

  • Nothing is hidden silently. If a value has more entries than fit, the extras are announced as +3 more — the pane never quietly omits a field you'd be approving.
  • A big value is shortened, not replaced. A large blob is truncated with an ellipsis and still points you at "Show technical details" for the byte-exact payload — you always get a real value plus the escape hatch, never only the escape hatch.
  • Credentials stay masked. A field whose name reads like a secret (an API key, token, password, passphrase) renders as dots. Settings that store credentials can't reach an approval pane at all — this covers a credential tucked inside a larger setting.

If a project reference can't be matched to a name yet (the project list hasn't loaded), it degrades to a labelled id like Project: 4f2c… — still a real value you can act on.

Below the body, the collapsed-by-default "Show technical details" expander reveals the full raw JSON payload — but only when it adds something. For a simple on/off or single-value change (which the body already shows in full) the drawer is hidden, because the raw {"value": true, "priorValue": false} is just developer noise. It stays available for nested or large payloads, where you might want to inspect or copy a value verbatim.

How the diff stays trustworthy

When a PATCH /settings/<key> request arrives at the local CLI control server (running on 127.0.0.1:19519 by default), the server snapshots the current value of settings[key] before it queues the pending row. That snapshot — the priorValue — is stored alongside the new value inside the pending row's payload. When you later open the approval pane, the diff is computed between that frozen priorValue and the proposed new value, not between live state and the proposed value.

That ordering matters: between the moment the CLI client submitted the request and the moment you click the approval, some other surface in the app might mutate the same setting. If the diff compared the proposed value to live state, it would look wrong — the approval pane would show a confusing "change" that no longer reflects what the script intended. Snapshotting at queue time keeps the diff time-correct.

Keys that store sensitive material (credentials, encryption keys, anything denylisted) never reach the snapshot path — they are rejected earlier in the same handler, before the pending row is created.

What can trigger one

Any caller that hits PATCH /settings/<key> on the local CLI control server can queue a settings-patch approval. In practice that means:

  • AI agents running on your machine that have been granted CLI access and want to adjust an Omniscio setting on your behalf.
  • Plugins or recipes that call the CLI server during their own workflow.
  • External scripts — curl, automation runners, anything you've authorized with a bearer token.

The CLI server enforces bearer-token auth on the patch endpoint, so a random local process can't queue patches without the token. Endpoints that apply immediately vs route through this approval queue are listed in the CLI server gating table; for an external caller settings patches sit on the approval-required side.

The exceptions that do NOT queue. The queue is the default, not an absolute — these narrow cases apply without a card:

  • An in-app session's change. A session Omniscio itself spawned, holding the in-app session key, writing any setting it is allowed to touch is applied at once through the same apply path the UI uses — no inbox row is created. This includes guards and arming switches. The always-card settings are the exception: they raise a card here too.
  • A patch that changes nothing. If the proposed value already equals the current one, the handler answers {queued: false, applied: false, reason: 'no-effective-change'} and creates no row at all — a no-op never becomes an inbox item (see the limits below).
  • The repository's own setup profile. npm run setup on a fresh install applies its exact, compiled, non-secret team profile directly, so broad permissions are never active while their matching guardrails wait in the queue.
  • Keyboard-shortcut settings. A patch that only rebinds or toggles a global hotkey applies at once — a benign personal preference, the same trust level as the always-instant /keybindings/* route.
  • Presentation mode and Demo Look. presentationModeEnabled and demoLookEnabled apply at once, so a user trapped behind either screen can exit through the CLI without an approval card they cannot see.
  • An "always allow this action" grant. If you have marked an action kind as always-allow, its patches skip the queue, except for the always-card settings.
  • When the gate itself is off. The whole approval boundary is the "Approval requirements" switch in Settings → CLI Control (default on); turning a family's queue off makes its external patches apply at once, exactly as an approved one would. While it is off, every setting an outside caller may touch applies inline with no card — the switch is global.

Every switch that stops ALL landing must name WHY. Three settings do, and all three are the same event: the landing master switch (autoLanderSupervisorEnabled), the auto-lander's own master gate (autoLanderEnabled), and the Dev Pipeline panel (devPipelinePanelEnabled) while autoLanderEnabled is unset — with autoLanderEnabled never set, the lander follows the panel. A patch that turns any of them off must carry a fault field naming the lander fault it is answering — failing-land, bad-merge-on-master or incident. A request that names none, or puts something else there (a "restart the lander" ask included), is refused with a 400 before any approval row is created, and the refusal names the road that actually recovers the Lander V3 child — POST /lander-v3/runtime/restart-from-master (npm run lander-v3:restart) — plus what to do when that child cannot be recovered: report it to the crew lead. It never points an agent at restarting the app itself, which is the owner's to do. A stop that does name a fault still queues its card as any other patch does, and the switch's own history records that fault as the reason — under the setting's own name for the two levers that are not registry switches. A whole-file settings backup that would carry one of these stops is refused too, because a backup has no field for a fault. This is the one place an off switch is not a general-purpose lever: it is for landing that is broken, never for wanting a fresh process. Your own toggle in Settings goes round the CLI entirely and is unchanged.

The agent gets a one-click link to the approval. When the patch queues, the CLI create response now carries an omniscio://inbox/item/<id> deep link straight to this approval — so instead of telling you to "go find it in your inbox," the agent can hand you a clickable "approve this" link. If you open the approval via that link, approving or rejecting it returns you to the session that requested it; resolving the same approval the normal way in the inbox just moves to the next approval. This applies to every agent-queued approval, not just settings patches. See deep-links.md.

A whole list cannot delete rows the writer never read

A list-valued setting (an array — alertSessionRoutes, the quick-email recipients, the approved-sender list) is saved as a WHOLE list, so a writer that read the list, edited its own row and wrote it back carries an older copy of everything else with it. When a second writer does the same thing ten minutes later, its copy is missing the first writer's row, and the save deletes it with no error on either side. Two small rules close that:

  • GET /settings/<key> returns a revision for a list value — an opaque short string for exactly the list it just handed back.
  • PATCH /settings/<key> accepts that value back as expectedRevision. If the stored list has moved since that read, the patch answers 409 CONFLICT and nothing is saved; the message tells the writer to read the list again and send its new revision. An add or an edit needs no revision — the revision is only what proves a read.
  • A write that would DELETE a stored row is refused when it carries no revision. The error names the rows it would have removed, and the writer either keeps them or reads the list first and sends the revision it read. This is the default-safe half: a writer that never read the current list cannot delete a row it does not know about. A list whose rows were all replaced deliberately still saves — once, with the revision.

Only the CLI settings route is guarded this way, because it is the road that ships whole lists; the desktop's own list editors already persist one row at a time, and a queued patch is re-checked against the live value when it is approved (see "How it behaves" above), so one that has drifted is refused rather than applied.

The 50,000-character technical-details cap

The "Show technical details" expander has a hard cap of 50,000 characters on inline <pre> rendering. The realistic worst case it was sized for is an aiManager patch carrying both value and priorValue (a roughly 45 KB twin payload); that fits inline with a max-h-64 overflow-auto scroll region without freezing the renderer. Larger payloads render a "(too large to display inline)" stub above the toggle. If you need to inspect a giant payload byte-for-byte, copy it out via the CLI server or the database; the cap exists specifically to keep the renderer responsive on mobile, where multi-megabyte <pre> blocks can lock the device.

Limits and edge cases

  • Approvals are persistent. They survive an Omniscio restart. If you don't decide today, the row is still there tomorrow.
  • Rejecting is final. A rejected patch is discarded; the CLI client gets back a rejection on its long poll (or, if it timed out, the next GET /settings/<key> reflects the unchanged state). To re-propose the same change the script has to queue a new patch.
  • A patch that matches the current value does not queue. The handler compares the proposed value against the queue-time snapshot and, when they are equal, answers {queued: false, applied: false, reason: 'no-effective-change'} and creates no inbox row — a no-op is dropped rather than shown. (The pane still knows how to render a no-op — Branch 4 above — for a queued row whose value happens to match by the time you review it.)
  • Some keys are refused, not queued. Secrets, pluginSettings, prJanitorPaused, paywall levers, consent records and the control server's own switch answer 400 with the route that owns the effect; pauseAllTesting is refused to everything except the full-trust CLI key; a land data-safety standard can only be made stricter. Nothing else is refused (contract invariant every-setting-is-agent-controllable).
  • The owner-held settings become a person-only card instead. Sign-in, second factor, mobile device approval, trusted sheets, the agent-email domain allow-list and the other owner-held keys are no longer a flat 400 for an agent: any caller that proves its session (its own agent or in-app key) or names a live session (the full-trust key with X-AMC-Source-Session-Id) gets a settings.person_held_patch card (202) and must send an X-AMC-Approval-Note. Only your click in the app applies it, and a card whose setting changed after it was raised is refused at approval rather than overwriting the newer value. A caller naming no live session still gets the 400. Rules: ask-full-power-approvals-contract.md person-held-settings-are-cards.
  • Schema validation happens before the snapshot. If the patch's value doesn't pass the settings schema, the CLI client gets back a 400 immediately and no row is queued — the snapshot path is only entered for payloads that would, if approved, apply cleanly.
  • cli-pending-actions.md — the CLI Pending inbox surface that hosts settings patches alongside every other approvable CLI action.
  • deep-links.md — the omniscio://inbox/item/<id> link the agent receives in the create response; opening it and resolving the approval returns you to the requesting session.
  • share-cli.md — the CLI control server's authentication, bearer token rotation, and the broader endpoint map.

Last verified 2026-11-13