OKLMdocumentation v1.0.3
On this page

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) or deny (refused; the model receives the refusal as the tool's result and may try something else).
  • Rule syntax. A rule is Tool or Tool(pattern):
    • Tool alone 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:* matches git log -3, not git 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): /path from the filesystem root, ~/path from the home directory, ./path or 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 a prefix* 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%\oklm on Windows). Each holds allow, ask and deny lists.
  • Precedence. deny beats ask, which beats allow, 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 ask the user's answer. The log is written before the tool runs and is append-only for the harness; oklm audit lists 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.