---
title: Agent Permission Level (choose how much agents can do before Omniscio asks you)
---

# Agent Permission Level (choose how much agents can do before Omniscio asks you)

## What it is

Omniscio runs agents in the background, unattended. Left to itself, an agent would edit files and run commands without ever asking — which is fast but gives it a lot of freedom. **Agent Permission Level** is a single setting that lets you decide how much freedom your Claude and Codex sessions get before Omniscio stops and asks for your approval (Codex maps each level to its closest built-in policy — see [Which agents it controls](#which-agents-it-controls)). It has four levels, from most cautious to most trusting:

- **Read-only** — the agent can read your files and propose changes, but it asks you before writing any file or running any command. Maximum control.
- **Guarded** _(the default for new installs)_ — the agent automatically makes file edits **inside your project**, but asks you before running a shell command, editing its own config files (`.claude/`, `.git/`, `CLAUDE.md`, and similar), or writing a file **outside** the project folder.
- **Autonomous** — the agent automatically makes edits and runs commands inside the project; it only asks before writing files outside the project.
- **Full trust** — the agent does everything on its own, with no permission prompts at all — sensitive files included. Full trust means literally never ask.

Below Full trust (Read-only, Guarded, Autonomous), Omniscio **always** asks before an agent touches a genuinely sensitive file (SSH keys, cloud credentials, system files like `/etc/passwd`, shell startup files). **Full trust is the deliberate exception** — it auto-approves everything, sensitive files included, because "full trust" means literally never ask. One rule never relaxes at any level: sessions started by an inbound email are locked down harder (they can't perform risky operations at all), and — as a second guard for that same untrusted-inbound case — an email-triggered session keeps the sensitive-file prompt even under Full trust.

## Where to find it

### Where it lives in the UI

You choose your level in two places:

1. **During onboarding** — a step called **"Agent Access"** (in the personalize part of setup, right before the theme picker) shows the four levels as cards. It starts on **Guarded**; tap a different card to change it.
2. **Any time afterward** — **Settings → Workflow**, a dropdown labelled **"Agent Permission Level"**, sitting just above the "Auto-Approve Plans" and "Auto-Approve Config File Writes" toggles. Each option spells out what it does; pick one and it applies immediately.

When a level makes Omniscio pause for your approval, the session turns amber ("Needs You") and a small card appears with **Allow** / **Deny** buttons. The card now tells you _why_ it's asking and _what_ it's asking about — for a command it shows the actual command line (e.g. "Claude wants to run a command: `npm run build`"), and approving it runs that exact command.

Once you **Allow** or **Deny** and the session has nothing else pending, Omniscio moves you straight to the next session that needs you — the **same** way sending a reply does, following your **Post-send navigation** setting (Settings → Sessions → "After I send a message…"). If the agent has stacked several commands on one session, you're shown the next one first and only move on once they're all handled — so triaging approvals flows exactly like triaging replies.

## How it behaves

### New installs vs. existing installs

The default is deliberately different depending on whether Omniscio is new to you:

- **A brand-new install** starts on **Guarded**, so a first-time user isn't handing an agent full freedom before they understand it.
- **An install that already exists** (you've onboarded before) is pinned to **Full trust** the first time it starts up after this feature ships — so your running agents keep behaving exactly as they did, with no sudden wave of approval prompts. You can switch yourself to a stricter level whenever you like in Settings; nothing forces you to.

This "keep existing users where they were" migration runs exactly once and never overrides a level you later choose yourself.

### Which agents it controls

This setting governs **Claude Code sessions** (and the Claude-compatible engines like DeepSeek, Kimi, and GLM that run through the same path) and, since 2026-09-23, **new Codex sessions**. **Cursor** and **Gemini** keep their own permission systems: Cursor decides permissions server-side in your Cursor account, and Gemini manages its own approvals.

Codex has its own built-in permission system, so Omniscio picks the Codex policy closest to your level:

| Your level | What a new Codex session does |
| --- | --- |
| Read-only, Guarded | Full machine access, but asks before every command or file edit |
| Autonomous | Works freely inside the project folder, internet included (`npm install`, `git push`); asks only before writing outside it |
| Full trust | Full machine access, never asks |

- **Codex can have its own level.** Settings → Accounts → Codex → **Codex permission level** defaults to **Follow Agent Permission Level**. Pick another option there to run Codex at a different level from your Claude sessions.
- **Upgrading switches the old default once.** An install still on Codex's old default (**Ask before every command**) moves to **Follow Agent Permission Level** the first time the new version starts. A different Codex level you picked on purpose is kept.
- **Changes apply to new Codex sessions only.** A Codex session keeps the policy it started with.
- **Claude-only protections stay Claude-only.** The sensitive-file check and the approval card's "always allow" options don't apply to Codex, because Codex answers its own approval requests.

### Limits and edge cases

- **Guarded is deliberately chatty for command-heavy work.** Because it asks before _every_ shell command, an agent that runs a lot of commands will generate a lot of approval prompts. That's the point of the tier — control — and it's why command-light first-time use fits Guarded while power users tend to pick Autonomous or Full trust.
- **The two "Auto-Approve" toggles still apply on top.** "Auto-Approve Config File Writes" can still force config prompts at the more trusting levels; "Auto-Approve Plans" is a separate thing (it governs plan-mode approval, not tool permissions) and this setting doesn't change it.
- **Reads are always fine at Guarded** — including reading a config file. Guarded only asks before _changing_ config, not before looking at it.
- **If Omniscio can't tell where the project folder is** (a rare session with no resolved working directory), an out-of-project write can't be judged, so it's allowed rather than blocked — Omniscio never blocks work just because it's unsure. Below Full trust, the sensitive-file protection still applies.
- **The sensitive-file check reads the whole command, so it can misfire below Full trust.** It scans a shell command word by word, which means a command that merely _mentions_ a sensitive path — a `git commit` message that talks about `~/.bashrc`, for example — can raise the prompt even though nothing touches that file. At Full trust this never happens, because the check doesn't run at all.
- **A session can be pinned stricter than your global level.** The Chief of Staff (Simple Mode) session and the guided app tour run at **Guarded** on purpose, so they keep the sensitive-file prompt even when you're on Full trust. A pin can only ever make a session more cautious, never less.

## For agents

### Where to inspect this in the source

- **The setting + default:** `agentPermissionLevel` on `SessionBehaviorSettings` (default `'guarded'`) in `src/shared/types/settings/session-behavior-settings.ts`, validated in `src/shared/ipc-schemas/settings/session-behavior-settings.ts`.
- **The decision logic:** `decidePermissionByLevel` / `classifyToolAction` / `normalizeAgentPermissionLevel` in `src/main/process/ndjson-permission-handler.ts` — pure functions, applied by `processPermissionRequest` after the email floor and (below Full trust only) the dangerous-path net.
- **The existing-install migration:** `src/main/services/config-store/migrations/migrate-agent-permission-level-existing-users.ts`.
- **UI:** the Settings dropdown in `src/renderer/src/features/settings/sections/workflow/WorkflowSettings-definitions.ts`; the onboarding step in `src/renderer/src/features/onboarding/steps/AgentAccessStep.tsx`.
- **Contract:** `.claude/memory/contracts/agent-permission-level-contract.md` is the present-tense source of truth and lists every test that locks an invariant — read it before changing any of the above.

## Related

### Related pages

- [settings-patch-approval.md](settings-patch-approval.md) — how an _external_ caller (CLI/agent) proposing a settings change is queued for your approval; distinct from this in-session tool-permission gate.
- [share-cli.md](share-cli.md) — the local CLI control server, where this setting is also readable/writable via `/settings`.