# Permissions: how Adom Bridge asks you before an AI acts

Adom Bridge lets a cloud AI drive your machine. That is the point of the app, but some actions deserve a checkpoint: anything that runs code, writes or deletes files, edits the registry, kills processes, or types and clicks as you. When a remote AI asks for one of those, Adom Bridge stops and asks you first.

![The Adom Bridge shell approval dialog: the command, the AI's stated reason, and the Approve once / 1 hr / 24 hr / Bypass / Deny buttons](approval-dialog.png)

The principle behind all of it: **the AI can ASK for permission, but only you can GRANT it.** There is no way for the AI to approve itself. It can pop the prompt in front of you, and that is all. Adom Bridge owns every approval decision, in every mode. Nothing else on your machine can grant on your behalf.

## The approval dialog inside the Adom Bridge window

When a remote AI hits the gate, an approval dialog opens inside the Adom Bridge window. It shows the real request, not just a verb name:

- The actual command or file path the AI wants to run.
- The AI's stated reason (see below).
- The working directory the command would run in.

The dialog has five buttons: **Approve once**, **Approve 1 hr**, **Approve 24 hr**, **Bypass Permissions**, and **Deny**. Each button has a hover tooltip, so if you are unsure what one does, rest your pointer on it and a short explanation appears. Nothing runs until you click one.

Alongside the dialog, the taskbar icon flashes so you notice even if the window is buried. If you missed the prompt entirely, the AI can re-surface it and bring the window to the front, but it still cannot decide for you.

## What each button means

- **Approve once**: run this one command only. The very next gated command asks again.
- **Approve 1 hr / Approve 24 hr**: auto-approve the whole gated class for a timed window, so a working session is not interrupted on every command. When the timer expires, prompting resumes on its own.
- **Bypass Permissions**: auto-approve indefinitely, until you turn it off. This is the durable preference, for machines you fully trust the AI on, such as a dedicated work box. The same switch lives in Settings, under Shell Commands, as the Bypass Permissions checkbox.
- **Deny**: refuse this command. The AI is told you said no, and that it should not silently retry.

There is exactly one Bypass button. One grant covers the whole class of gated actions (run code, write files, edit registry, kill processes, synthetic input). You are not approving a single verb, you are opening a window of trust: once for a single command, timed for a session, or durable until revoked.

## The Windows toast

At the same time as the dialog, Adom Bridge fires a Windows toast notification so you can decide without opening the window. The toast is branded **Adom Bridge**, so you always know which app is asking.

Its buttons carry short labels: **Once**, **1 hour**, **24 hours**, **Bypass**, and **Deny**. They mean the same things as the dialog buttons above. The labels are kept short on purpose, because Windows clips long toast button text and offers no place for a hover tooltip (that is why the in-window dialog is where the fuller wording and tooltips live).

Clicking an approve button on the toast resolves the request but does **not** drag the Adom Bridge window to the foreground. You granted from the toast precisely so you would not have to switch away from whatever you were doing, so Adom Bridge stays out of your way.

The dialog, the toast, and (in embedded mode) Hydrogen's prompt are all surfaces for the same one request. The first click on any of them wins, and the others close on their own.

## Running inside Hydrogen (embedded mode)

When Adom Bridge runs embedded inside Hydrogen, approvals work exactly as they do standalone. Adom Bridge still owns the decision, and it still shows its own Adom-Desktop-branded dialog and toast.

In addition, Adom Bridge mirrors the request over to Hydrogen, which can raise its own Hydrogen-Desktop-branded prompt. So for a single request you may see two prompts: one from Adom Bridge, one from Hydrogen. That is intentional. Adom Bridge keeps its own prompt Adom-branded on purpose, so that even while embedded you learn that Adom Bridge is the app doing the work and the app that owns the gate.

Hydrogen stores no approval state of its own. It is only a display surface: your click there is handed straight back to Adom Bridge, which makes the actual decision. A decision on any surface resolves the request, and Adom Bridge then closes its own dialog and asks Hydrogen to close its prompt too, so you never have to dismiss two things.

Whether Adom Bridge is embedded is worked out live each time (Hydrogen present and reachable), never read from a stored setting that could go stale. Hydrogen cannot pre-authorize or force-approve anything. Silencing prompts is your call, made in Adom Bridge with Bypass.

That mirror only happens when Adom Bridge is actually going to ask you. If a grant is already active, Bypass Permissions or a running 1 hour or 24 hour window, Adom Bridge approves the command itself and shows no prompt, so it does not mirror anything to Hydrogen and no Hydrogen dialog appears either. In other words, a grant you gave in Adom Bridge silences both surfaces, not just Adom Bridge's own.

## Why the AI must state a reason, and why you should read it

Every gated request carries a line from the AI, shown as:

> The AI says: "Installing the KiCad CLI so I can export your gerbers"

The AI is required to explain WHY it wants the action, in one plain sentence. A request without one shows "(no reason given)", and a cautious user should decline it: an AI that read the documentation always supplies a reason.

Read the reason, but do not treat it as proof. It is text written by the requester, and the gate exists precisely because that requester might be wrong or manipulated. A persuasive reason is exactly what a compromised agent would write. That is why the prompt always shows the actual command alongside the reason: the command is the ground truth, the reason is context. If the reason and the command do not match, decline.

The request also shows who is asking (the AI thread and container), so if you run several AI threads against one machine you can see which one wants this. That identity is self-reported and shown for information only. It is never used to decide anything on its own.

## What survives a restart, and what does not

Grants live in two places. Most are in memory and vanish when Adom Bridge restarts. Only the Bypass preference is written to disk.

| Grant | Where it lives | Survives restart? |
| --- | --- | --- |
| Once / Deny | In memory, a single decision | No |
| Approve 1 hr / Approve 24 hr | In-memory timer | No |
| Bypass Permissions | On disk in config.json (`shell_auto_approve_permanent`) | Yes (the only durable grant) |

Once and Deny are single decisions and are never remembered. A 1 hour or 24 hour grant is a timer held in memory: it is session-scoped by design, so if Adom Bridge restarts the timed window is gone and prompting resumes. Bypass Permissions is a saved preference, the checkbox under Settings, Shell Commands, so it stays on across restarts until you turn it off. It is the only durable grant.

There is one deliberate exception, and it turns on how the restart happened, not who clicked. Any update that runs through Adom Bridge's own updater, whether it applied on its own overnight or you clicked Install now, hands the remaining timed window forward through a small handoff file that can be read once and expires after 120 seconds. A restart that does not go through the updater, an ordinary reboot, quitting the app, or running the installer .exe by hand, writes no handoff, so the timed window is gone as usual. The point is narrow: updating Adom Bridge should not silently revoke the hour you granted a moment earlier, but a plain restart still resets things, which is what you would expect.

| How the restart happened | Timed 1 hr / 24 hr window | Bypass |
| --- | --- | --- |
| Update through Adom Bridge (auto, or Install now) | Carries across | Survives |
| Reboot, quit, or running the installer .exe yourself | Gone | Survives |

## How to revoke

Any grant can be dropped instantly, at any time:

- **In the app:** Settings, then Shell Commands, then untick Bypass Permissions. This clears the durable grant and any running timer.
- **From a command line:**

  ```bash
  adom-bridge shell_auto_approve '{"duration_secs":0}'
  ```

  Revoking is always allowed, from anywhere, for anyone (including the AI itself). Only granting is restricted to you.

After a revoke, the very next gated command prompts again.

## What is never gated

Read-only actions (screenshots, window lists, status checks, reading UI text) run without prompting. So do commands from software already on your own machine: your local command line, Hydrogen, and installed bridges are trusted because installing them was your decision, and Adom Bridge only listens on localhost, so nothing can reach it over the network. The gate is specifically for the remote cloud AI, the one origin that acts on your machine while you may not be watching.

## The rule to remember

The prompt is the boundary. The AI can knock as loudly as it likes: pop the dialog, fire the toast, flash the taskbar. But the Approve button only works when a human clicks it, and every grant you give can be taken back in one click.