Approval gates

An agent that can write files, run shell commands, and reach the internet needs a place where you say yes. In Atomic Agent that place is the approval gate: before a dangerous tool runs, the runtime classifies what it is about to do and either lets it through or stops and asks you.

How much it asks is one number. agent.approvalLevel runs from 1 (ask about everything) to 5 (ask about nothing), and each step up hands the agent a broader class of actions to take on its own.

Developer Preview

Atomic Agent is a Developer Preview. Category names and level boundaries can still move between releases. Pin a release if you depend on the exact ladder below.

The ladder

The default is level 1. Every gated action prompts you before it happens.

Level	Name	Runs without asking
1	paranoid	Nothing. Every gated action prompts.
2	workspace	File writes, edits, and patches strictly inside the session working directory.
3	home	Adds file writes anywhere under your home directory, moves to Trash, archive extraction, and HTTP requests.
4	operator	Adds guarded shell commands, skill scripts, and process kills.
5	full trust	Everything, including browser navigation to non-web URLs, writes to the agent’s own trust config, and anything the runtime could not categorise.

The ladder is cumulative by construction. The gate asks level >= threshold, so a category that is silent at level 3 is silent at 4 and 5 too — there is no level where something starts asking again.

// <stateDir>/config.json
{
  "agent": {
    "approvalLevel": 2
  }
}

Hardline shell rules are not part of the ladder

The shell command guard runs before the gate and blocks at every level, including 5. Raising approvalLevel never unlocks a command the guard refuses.

Categories

Every call site that asks for approval names one of ten categories. The category decides both the level at which it goes quiet and the label you see in the prompt.

Category	Prompt label	Auto-approves from
fs_write_workspace	file write · workspace	2
fs_write_home	file write · home	3
fs_trash	move to Trash	3
http	HTTP request	3
shell	shell command	4
script	skill script	4
proc_kill	process kill	4
browser_nonweb	browser · non-web URL	5
trust_config	agent trust config	5
other	uncategorised	5

other is the deliberate fallback for anything a call site cannot place precisely. Because it only goes silent at 5, an uncategorised action keeps asking on every level below full trust — the conservative default.

Why trust_config is pinned at 5

trust_config covers writes to the files that hold the ladder itself: config.json (which contains agent.approvalLevel) and .env (which holds API tokens). It is pinned at level 5 because it is the one action that could silently raise the ladder for the next boot. Without the pin, a model running at level 3 or 4 could rewrite its own config to level 5 and escalate itself across a restart.

The prompt has four answers

When the gate stops, the CLI prompt on stderr is not a yes/no. It takes four:

Answer	Effect
y	Approve this one call.
s	Approve, and allow this whole category for the rest of the session.
a	Approve, and allow this shell command shape for the rest of the session.
N	Deny.

Only y and yes count as approval. Anything else — a typo, an empty line, maybe — is a refusal. Denial is the failure mode, which is what you want from a gate.

» approval required for tool: os.fs.write
  kind: file write · home
  reason: write 2.1 KB to ~/notes/plan.md
  affects: /Users/you/notes/plan.md
  approve? [y = approve once, s = allow this kind this session, N = deny]

s and a appear only when the request is grantable. a needs a shell command shape to generalise from, so it shows up on shell requests and not on file writes. And trust_config is never grantable at all — those requests only ever offer y/N, and the prompt says so:

  (trust-config writes are never granted for the session)

That is the grant-side half of the same invariant as the level pin. A broad category grant earlier in the session must not later cover a write to the file that holds the ladder.

Note

Session grants are exactly that — per session. They do not persist to config.json and they vanish when the process exits. To make a relaxation durable, raise agent.approvalLevel deliberately.

Skipping approvals for one run

Every interactive entry point (run, tui, serve) accepts --no-approval, which forces level 5 for that process.

atomic-agent run --no-approval

Caution

--no-approval is one-directional: it can only lower strictness for a single run, never raise it. At level 5 the onApprovalRequest callback never fires, so you also lose the visibility that comes with being asked. Use it for trusted automation, not as a default.

The persisted agent.approvalLevel is the baseline and the flag overrides it for the process. run, tui, and serve all resolve the boot level the same way, so the level you set in config applies consistently across entry points.

Setting the level from the TUI

Unlike --no-approval, which lasts one process, these write the persisted level:

• /privacy level 1..5 sets the ladder directly to that rung.
• /privacy approve on and /privacy approve off are aliases for levels 5 and 1 — kept so older muscle memory and scripts keep working. There is no bare /privacy approve: the verb is deliberately explicit, because on means “run everything without asking”.

Both open the Privacy panel, where 1–5 jump to a level and Left / Right step one rung at a time. See TUI panels for the full key list.

Caution

The Privacy panel applies a level change on the keypress, with no confirmation. Pressing 5 there is the same as running at --no-approval — except it persists, so it also applies to every session after this one.

Approval-gated calls cannot be batched

Atomic Agent lets the model emit several tool calls in one step, executed by resource class. Approval-gated tools are excluded from that: they carry the virtual approval_gated class and are forbidden inside a multi-call batch.

If the model emits one anyway, the runtime does not fail the step. It trims the batch to the first approval-gated call, executes that one, drops the rest, and tells the model what happened in the next step’s prompt so it can re-emit the dropped calls one at a time.

These are the approval-gated tools:

Tool	What it does
os.fs.write	Write a file
os.fs.edit	Edit a file in place
os.fs.patch	Apply a patch
os.fs.trash	Move to Trash
os.fs.archive.extract	Extract an archive
os.shell.run	Run a shell command
os.proc.kill	Kill a process
os.http.request	Issue an HTTP request
skill.run_script	Run a skill script

Read-only counterparts (os.fs.read, os.fs.grep, os.web.fetch, os.git.*, the memory.* recalls) are pure_read and batch freely.

Why serialise them

An approval prompt is a synchronous stop. Running several in parallel would interleave prompts on one terminal and make it ambiguous which answer applied to which call. One gated call per step keeps the question and the answer unambiguous.

The legacy key

Before config v37 the setting was a boolean, agent.approvalRequired. It is migrated automatically:

Legacy value	Becomes
approvalRequired: true	approvalLevel: 1
approvalRequired: false	approvalLevel: 5

The migration runs when the config file is read, and the legacy key is removed from disk afterwards. If a file somehow carries both, agent.approvalLevel wins — an explicit level is never overridden by a stale boolean.

Check your migrated level

A config that carried approvalRequired: false lands on level 5, which approves everything. If you set that flag once for a quick experiment and forgot about it, the migration preserves it faithfully. Run atomic-agent config get after upgrading and confirm the level is what you actually want.

Choosing a level

Level 1 — anything untrusted

The default. Use it when you are exploring, running a new skill, or pointing the agent at code you did not write.

Level 2 — focused project work

The agent edits freely inside the working directory but still asks before touching anything outside it, hitting the network, or running shell.

Level 3 — research and fetching

Adds HTTP and home-directory writes. Good for tasks that read the web and take notes; shell still stops for you.

Level 4-5 — trusted automation

Shell and skill scripts run unattended. Only for workloads and inputs you fully control, ideally in a sandbox.

Related

Why local-first

Every door out of the runtime, and which ones the approval gate stands in front of.

Tools

The full tool catalog, including which verbs are approval-gated.

CLI Reference

--no-approval on run, tui, and serve.

Traces and replay

What the trace records about a turn, including the calls that stopped for approval.