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, external (Kimi Code / Hermes / DSH) 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). 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. An external agent (Kimi Code, Hermes, DSH) is the one case where a sensitive file is refused at every level, Full trust included — see Limits and edge cases. 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 and GLM that run through the same path), the external coding agents that use the shared approval channel (Kimi Code, Hermes and DSH — their tool calls now ask you at exactly the level you chose, instead of being waved through), 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.
• A session running on another machine (over SSH) is judged by its folder on THAT machine. "The project" is the folder Claude reports when it starts there, plus that machine's /tmp — never the project folder on your computer, whose paths mean nothing on the remote. Until Omniscio has heard that folder, every write from the remote session asks: unlike a local session, a remote one is never let through on a guess.
• 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. On a Claude session at Full trust this never happens, because the check doesn't run at all; on an external agent (Kimi Code, Hermes, DSH) the check always runs and a sensitive file is refused outright — see the next bullet. (It reads the paths a tool call names, not the text it is about to write, so a note that merely mentions a sensitive filename is not refused.)
• An external agent's approval is the same setting, with two differences you should know. Kimi Code, Hermes and DSH ask you at your level like Claude does, but a sensitive file (SSH keys, credentials, system files) is refused outright at every level — Full trust included — rather than being offered as a card you could click through; an external agent was never granted that bypass. And their cards offer the Agent Access level change but not the fine-grained "commands starting with git" rows, because those rules are read only by the Claude gatekeeper and a rule written there would quietly do nothing.
• If Omniscio genuinely can't tell what an external agent is asking to run, it asks you rather than assuming it is harmless — at Guarded and Autonomous alike. Only Full trust lets an unidentifiable tool call through, which is what makes the card's "Agent Access → Full trust" option an honest one.
• 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. A workflow that an incoming message or email started pins its AI steps the same way — see Workflows, "What an AI step is allowed to do".

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 / classifyAskReason / 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 external-engine adapter (Kimi Code / Hermes / DSH): src/main/services/engines/external-tool-approval.ts (decideExternalToolApproval — floor first, then the same level gate) fed by the ACP frame reader in src/main/services/engines/acp-tool-approval.ts, wired in src/main/services/engines/slim-acp-session-manager.ts. It pushes a reason plus ruleGrants: false so the card offers the level change and no rule rows.
• Out-of-project detection: isWriteOutsideWorkDir (local) and isWriteOutsideRemoteWorkDir (SSH sessions, judged against session.cliReportedCwd, captured from the system/init frame by captureReportedCwd in src/main/process/ndjson-session-capture.ts) in src/main/services/email/email-permission-filter.ts.
• 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 — 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 — the local CLI control server, where this setting is also readable/writable via /settings.