ADR-0010: Permission rules
Records how the harness decides whether a tool call runs: the modes, the rule syntax, where rules come from and which one wins, and what is audited.
Status: accepted (2026-11-01); amended 2026-11-02 with the dangerous-call pass and saved answers.
Context
The harness (M6) lets a local model read and write files, run
commands, fetch URLs and start background jobs and agents. A small model
makes mistakes and can be steered by the text it reads (a file, a web
page, a tool's output), so what it may do must be decided outside the
model, before each call, by rules the user can read and edit. Users of
other agent harnesses already write rules as Tool(pattern)
(Bash(git status:*), Read(./src/**)), with
deny taking precedence; following that form keeps existing habits and
examples valid.
Decision
- Decisions. Every tool call gets one of
allow(runs),ask(the user confirms, once or for the rest of the session) ordeny(refused; the model receives the refusal as the tool's result and may try something else). - Rule syntax. A rule is
ToolorTool(pattern):Toolalone matches every call of that tool;*matches every tool.Bash(pattern): the command line, after the harness splits it at;,&&,||,|and newlines; every part must match for the call to match an allow rule, and any part matching a deny rule denies the call.prefix:*matches the prefix followed by a word boundary or the end (git log:*matchesgit log -3, notgit logout); anything else matches the whole part exactly.Read(pattern),Write(pattern),Edit(pattern): gitignore-style globs (*,**,?,[...]) over the path made absolute and normalized (.and..resolved, symbolic links followed):/pathfrom the filesystem root,~/pathfrom the home directory,./pathor a relative path from the project root. A path outside the project and its added directories needs an explicit allow rule.WebFetch(domain:host): the host and its subdomains.- Other tools (agents, jobs, skills, tools of MCP servers as
mcp__server__tool) take an exact name or aprefix*pattern on their main argument, named in each tool's definition.
- Rule sources, from highest to lowest: managed
settings (a system file the user cannot override), command-line options,
the project's local settings (
.oklm/settings.local.json, not committed), the project's settings (.oklm/settings.json), the user's settings (~/.config/oklm/settings.json,%APPDATA%\oklmon Windows). Each holdsallow,askanddenylists. - Precedence.
denybeatsask, which beatsallow, whatever the sources: a deny anywhere cannot be lifted by an allow elsewhere. A managed setting may additionally forbid the lower sources from adding allow rules. A call that no rule matches is decided by the mode. - Modes, chosen per session (
--mode) and switchable during it:default: unmatched calls ask, except reads inside the project.accept-edits: file edits inside the project are allowed too.plan: only reading tools run; edits, commands and jobs are denied until the user accepts the plan.bypass: unmatched calls are allowed; deny rules still apply. Refused when the sandbox (ADR-0011) is not available, unless the user opts in deliberately with--dangerously-skip-permissions(oklm_perms_allow_unsafe_bypass), which runs it unconfined behind a louder banner; disabled by a managed setting in any case.
- Dangerous calls. After the rules and the mode, one pass checks the call against a dangerous-pattern list (commands that destroy trees, disks, history or remote state, run as another user, run downloads, expose services; writes to the system, the user's keys and startup files, OKLM's own settings, the repository's hooks). A match turns an allow into an ask in every mode, bypass included; it never turns a deny into anything else. The list is built in and extended in code by integrations; settings cannot shorten it. A dangerous call offers no "always".
- Answers kept. "Always" adds the rules the question
named: each simple command exactly, or the path relative to the project.
The terminal saves them to
.oklm/settings.local.json(a local rule), so they last beyond the session and stay out of the committed settings. - Audit. Every decision is appended to the session's
audit log, one JSON line: time, session, tool, arguments (secrets the
rules name are masked), decision, the rule and source that decided it
(or the mode), and for
askthe user's answer. The log is written before the tool runs and is append-only for the harness;oklm auditlists and filters it.
Consequences
Rules are plain text the user can review, and deny-wins makes adding
a safety rule safe at any level. Splitting compound commands and
normalizing paths is the harness's job and must be tested against
evasions (quoting, $(...), symbolic links,
..); a command the splitter cannot parse is treated as
unmatched and asks. Rules restrict what the harness lets the model do;
they do not confine the processes it starts, which is the sandbox's
role.