Permission Model
Two things decide whether you are asked before a tool runs: the tool's risk tier, and the session's permission mode. Escalations can override both.
Risk tiers
A tier is a property of the tool. It does not change.
| Tier | Prompts? | What it covers | Examples |
|---|---|---|---|
| Safe | Never | Read-only, no side effects | Read, Glob, Grep, WebFetch, Check |
| Mutating | Unless the mode waives it | Changes local state | Write, Edit, MultiEdit, Append, Bash |
| Hard stop | Always | Physical or irreversible effect | EtherCatWriteIo, EtherCatPulseIo, EtherCatGoOperational, ModbusWrite, OpcUaWrite |
The hard-stop tier cannot be waived
A hard-stop tool prompts in every permission mode, including dangerous, and --skip-permissions does not waive it either. That tier is for physical or irreversible effect (a PLC write, a motion command, energising an output) rather than a file write.
This is deliberate and it is the interlock that makes autonomy safe to enable on a machine that can move. Do not design an unattended pipeline that assumes a hard-stop tool will run without a human.
Permission modes
Five modes. Shift+Tab cycles through them in this order, and it works during a turn as well as at the prompt. The active mode is shown under the prompt and in the pinned region while a turn runs.
| Mode | Behaviour |
|---|---|
plan | Read-only. Mutating tools are refused until the agent presents a plan via ExitPlanMode and you approve it. |
manual | Ask before every mutating tool. The default. |
accept edits | Write, Edit, MultiEdit and Append apply without asking, inside the working directory. Bash and unknown tools still ask. |
auto | Nothing routine is asked, inside the working directory. |
dangerous | Every waivable request is approved, including Bash and including paths outside the working directory. Shown in red. |
Setting the mode
| How | Scope |
|---|---|
--mode <mode> | The whole run. Also OASIS_MODE. |
--plan | Shorthand for --mode plan. |
--skip-permissions | Equivalent to starting in dangerous. |
| Shift+Tab | Switches mid-session, including mid-turn. |
/plan on / /plan off | Toggles plan mode specifically. |
The path boundary
Switching mode does not widen where the agent may write. Only dangerous does that.
In accept edits and auto, these always prompt:
- Any path outside the working directory (the sandbox root, set with
--cwd) - Anything under
/etc,/dev,/proc,/sysor/root
So auto means "stop asking me about routine work in this project", not "do anything anywhere". That distinction is the point of the mode.
Escalations
Some individual calls prompt even when the mode would otherwise waive them. An escalation carries a machine-readable pattern, the thing being touched, and a human-readable explanation rendered in the prompt.
| Escalation | Triggers when |
|---|---|
| Write outside the working directory | A file tool resolves to a path outside the sandbox root |
| Sensitive system path | The resolved path is under /etc, /dev, /proc, /sys or /root |
| Fieldbus acquisition | An EtherCAT tool acquires a bus segment |
Escalations exist so that delegating approvals wholesale does not silently delegate the one decision you would have wanted to make.
Choosing a mode
| Situation | Mode |
|---|---|
| Exploring an unfamiliar codebase or device | plan |
| Normal interactive work | manual (default) |
| A refactor you have already scoped | accept edits |
| A long unattended build or test run in a project directory | auto |
| A throwaway container you own entirely | dangerous |
| Anything touching a machine that can move | manual. Note that hard-stop tools will ask regardless |
Background agents
A background agent dispatched with --bg uses the mode set at dispatch. When it meets something it may not do, it does not guess: it stops, saves state, and the session is marked blocked.
# Stops at the first mutating tool and waits for you
oasis-agent --bg -p "run the test suite"
# Runs unattended inside the current directory
oasis-agent --bg --mode auto -p "run the test suite"Pick it up with oasis-agent --resume <id> where there is someone to answer. See Background Agents & Jobs.
Programmatic approval
Over the control protocol, a pending approval arrives as a permission.required event and is answered with a single permission.respond call. The mode can be changed mid-session with permission.setMode. See the OCP Method Reference.