Access modes

The three modes

Pick the mode from the access chip in the composer, next to the model and thinking selectors. The choice is remembered and can be changed at any time — including mid-session.

How a tool call is classified

The guard looks at the tool name and sorts each call into one of five kinds. Reads never mutate anything, so they always pass.

The decision for each kind:

There is intentionally no block. The guard prompts rather than silently denying, and a prompt that is dismissed counts as a denial.

Approving a call

When a call needs approval, a compact bar appears above the composer — not a blocking modal — so you can keep reading the transcript. It offers three choices:

• Allow once — run this call, and only this one.
• Always allow this tool — run it and stop asking for the same tool in this mode.
• Deny — refuse the call.

After you answer, focus returns to the composer so you can keep typing. pi blocks one request at a time, so if a dialog or another approval is already open the new request is declined rather than queueing behind a prompt you cannot see.

The always-allow list

Always allow this tool records the exact tool name in ~/.orbit-pi/access-allow.json, keyed by the active mode. Two things follow from that:

• The list is per mode: allowing a tool in Auto-accept edits does not allow it in Supervised.
• It matches on the tool name, not the arguments, so allowing bash lets the agent run any command without asking. Prefer Allow once for one-off commands.

To start asking again, remove the tool from the list for that mode — the file is plain JSON:

{
  "auto-accept-edits": ["bash"],
  "supervised": []
}

Where the mode lives

The active mode is stored in ~/.orbit-pi/access.json:

{ "mode": "auto-accept-edits" }

The guard extension reads that file fresh on every tool call, so changing the mode re-arms sessions that are already running — there is no restart and no per-session copy to update. An unknown or malformed value falls back to the default, so a hand-edited file can never widen access by accident.

Access mode versus workflow mode

These are separate controls and both apply to a session. A workflow mode decides which tools exist at all; the access mode decides which of the remaining ones can run without a prompt.

In Plan and Ask the write tools are removed and bash is gated to a read-only allowlist, so a Supervised Build session and a Plan session differ in what the guard is even asked about.

What it is not

• It is not a sandbox. It is a confirmation guard around tool calls. pi ships no sandbox, and Orbit does not add one. Full access, or an always-allowed bash, gives the agent everything your user account can do.
• The guard has to be installed. Orbit ships it as a pi extension and loads it into every session. If it could not be installed, changing the mode has no effect and the app says so instead of implying it took.
• Dismissing is denying. A prompt that is closed, cancelled, or lost when a session is replaced is treated as a refusal, never as approval.