Permissions
Every tool call crosses one permission pipeline before the tool runs. The pipeline decides from structured facts about the call (the tool, its risk class, the parsed shell command, the resolved paths), never from a pattern over raw arguments. A denial goes back to the model as the tool result and the run goes on.
Modes
The session mode is set by [permissions] default_mode or --permission-mode, and in the
terminal UI Shift+Tab cycles it. afk is also a valid default_mode
and --permission-mode (--afk is shorthand for the latter), and the last stop of the cycle. With neither set, the terminal UI starts in auto and a headless
run (fontaine -p) starts in manual, as Claude Code’s -p starts in default.
| Mode | What happens to a call nothing pre-approved |
|---|---|
manual | The human is asked. |
acceptEdits | write, edit and notebook_edit inside the workspace roots run; everything else asks. |
dontAsk | Denied, except send_message and board_update. Only other calls that are pre-approved run. |
auto | The guardian decides: allow, deny with a reason, or ask you. Edits to any file in the primary root and file-tool writes into scratch, every agent spawn and the coordination tools send_message and board_update (step 7 below), skip it. |
afk | AFK mode: decides exactly as auto does, and every outcome that would ask you is a denial instead. It is a valid default_mode (user file and --settings only, as auto) and --permission-mode; --afk is shorthand for --permission-mode afk, and the last stop of the Shift+Tab cycle enters it. |
In the terminal UI, /permissions shows the mode and the effective rules with the scope each came
from, including session and always grants; in auto it marks the broad allow rules that mode sets
aside.
There is no bypass mode. The deterministic floor below applies in every mode, and no mode, flag or
allow rule reaches past it. In a headless run (fontaine -p) nothing can ask, so every call that
would ask is denied instead; see Headless runs.
AFK mode is the mode after auto in the Shift+Tab cycle (or --permission-mode afk). While it is on,
nothing can ask either, so the same conversion applies in the terminal UI: each would-prompt
outcome (an ask rule, the floor, the mode’s approval, a hook’s ask, a guardian or composition
escalate, the paused breaker) is a denial that keeps its tier and rule and ends in guidance to
finish the allowed work or stop and report, and the guardian-unavailable dialog is skipped. It
grants nothing and changes no decision that would have been made without it.
The pipeline
A call goes through these steps in order and the first one that decides wins.
A call from an agent the session no longer knows (its id was never registered, or it or an ancestor has been released) is denied in every mode before step 1: no hook or guardian sees it.
-
Hooks. Pre-tool-use hooks may deny, ask, allow or rewrite the call’s arguments; every later step judges the rewritten call. Deny beats ask beats allow. A hook that fails, times out or answers something unreadable decides nothing. Hooks are configured under
[[hooks.*]]; see User hooks. -
The deterministic floor, in this order:
- a
[permissions] denyrule: denied. - an
askrule, a hook’s ask, or an MCP tool its server marked as requiring your approval: asks. - protected path:
write,editandnotebook_editon a path with a component named.git,.vscode,.idea,.husky,.fontaineor.claude, or whose file name is.gitconfig,.gitmodules,.bashrc,.bash_profile,.zshrc,.zprofile,.profile,.ripgreprcor.mcp.json, in any workspace root or the home directory, asks; so does any path under Fontaine’s own config or data directory (the auto-memory store is the one gated location under the data directory that is also reachable as a workspace root, and it takes this check like any other). Matching is on resolved path components, so separators and, on Windows and macOS, case do not matter. Inautothe guardian takes the place of the prompt, for a path the file tools can reach.
A floor outcome that asks is a denial in
dontAskand in headless runs. Inautoanaskrule and a server’s approval marker still ask you: no verdict approves them.A
shell,monitororpowershellcall that deletes the file system root, a top-level directory, your home directory, a workspace root or a parent of one is not a floor outcome: it goes on like any other shell call, and inautothe guardian is told which of those places it names (critical_deletions) and denies it in either profile. - a
-
Read-only fast path. A read-only tool (
read,ls,glob,grep,lsp) whose paths all resolve inside a workspace root runs. Symlinks are resolved first. Aread,greporlspof a secret file does not: it goes on to the allow rules, the hooks and the mode, somanualandacceptEditsask,dontAskdenies andautosends it to the guardian. The label alone earns nothing: a path outside the roots does not qualify, and an external read never takes this step.lsphas no external route at all: a path outside every root is denied, with the/add-dirhint.skill,ask_user_question,todo_write,models,board_showand the read-only scheduling tools name no path and take this step too.ask_user_questiononly shows you text and collects your choice, and no mode,autoincluded, ever answers it: the answer comes from you or, in a headless run, from nobody (the model is told to use its best judgment). Your answers, both the options you pick and the text you type, count as intent for the guardian, read with the question they answer. Anagentcall whose child can only read takes this step too: Fontaine computes the child’s toolset, and when every tool in it is read-only (plus the coordination toolssend_messageandboard_update;board_showis read-only), the spawn runs without the guardian or a prompt, in every mode.worker,forkand any type whose set holdsagent,shell, a write tool, a network tool (webfetch,websearch;modelsis read-only, so a custom type whose tools hold it still qualifies, and the built-in types do not include it) or an MCP tool do not qualify. Adenyoraskrule onagentand a hook still act first, and each call the child makes goes through the whole pipeline. A spawn of any other type is handled at step 7. The scratch directory is an ordinary root (see Tools): this step and the floor treat a path in it like one in the workspace, andshelltreats it like any root: read-only commands whose operands are inside it take the pre-classifier fast path, and other commands go through the guardian as usual.An out-of-root read by
read,ls,globorgrepis not denied here: it falls through to the same steps as any other call nobody pre-approved. An out-of-root write bywrite,editornotebook_editfalls through the same way — adjudicated, not automatically allowed. After the hooks, the target is resolved once — symlinks followed — and that resolved absolute path is what the approval prompt, the guardian and the execution all use, so retargeting a symlink mid-decision cannot redirect an approved call, and deny and ask rules still match the path as written. InmanualandacceptEditsan external write asks (that approval is itself the establishment that you asked for it, and the prompt shows the resolved target’s diff); inautothe guardian decides, allowing it only when your own messages, including what you picked in a question dialog, asked for that write; indontAskand in headless runs it is denied unless an allow rule or hook already covers it. An allow rule or a hook written for the resolved path runs it at theallow_ruleorhooktier; it is never audited asread_only_fast_pathortier05, and inautoit never takes thetracked_editorscratch_writefast paths: the fast paths require a path the scope can place. Malformed arguments (a missing or non-string path) are an immediate argument error after the floor: never a prompt, never the guardian. Execution uses one unconfined fallback instance per tool, reached only after the gate allows the call — read-only for the four read tools, a write fallback for the three write tools;shellhas no such route (see Tools). A protected path outside the roots (a shell rc file,~/.ssh/authorized_keys) is handled by the floor like an in-root one: it asks in the asking modes and reaches the guardian inauto. An external path does not become a root: it grants no write reach of its own, no fast path and no instruction-file discovery. -
Shell pre-classifier, below.
-
Allow rules, below.
-
Edits that skip the guardian (
autoonly). After the floor and the hooks, awrite,editornotebook_editcall is allowed without a guardian verdict in two cases, and ashellcall in a third (shell_edit, below). A file-tool write whose resolved target is inside the session scratch directory is audited astier = scratch_write; a shell command that touches scratch is not a file-tool call and goes to the guardian. An edit inside the primary workspace root is audited astier = tracked_editwhen the target is any file in that root or a path under it that does not exist yet, whether or not git tracks it: workspace files are assumed to be backed up, so tracking makes no difference inside the root. Symlinks are resolved first, so a link is judged by its target. These go to the guardian as before: a path in a root that holds your home directory (the root is$HOME,/homeor/) and any path when git cannot be read (an unparseable repository configuration or index); the auto-memory store and/add-dirroots; the protected paths above; credential files (.env, key files); persistence and code-execution locations (.envrc,.zshenv,.zlogin,.bash_login,.xprofileand similar login files, and anything under a.ssh,.gnupg,.aws,.docker,.kube,.cargo,.config,.localorLaunchAgentsdirectory), which a shell, direnv, a service manager or cargo runs later; instruction files (FONTAINE.md,FONTAINE.local.md,CLAUDE.md,CLAUDE.local.md,AGENTS.md), anything under arulesdirectory and anything under.github, because an edit there changes later decisions or what CI runs; hook-runner configuration (.pre-commit-config.yaml,lefthook.yml,.lefthook.yml, anything under.githooks/and the directory the repository’score.hooksPathnames inside the root), because the next commit or rebase step runs what it says; and every shell command except ashell_edit. A request in your own message that names an excluded file clears the guardian’s soft deny for it.@imported files are not excluded. All three allows end a run of consecutive guardian denials, so routine work between denials keepsautofrom pausing. Turn them off withauto_tracked_edits,auto_scratch_writesandauto_shell_edits; project scope may only switch them off.A
shellcall is audited astier = shell_editwhen Fontaine can parse the whole command and every part of it is one of these, with every path it touches inside the primary root (the call’s working directory too):- a read-only command of the pre-classifier’s set, or one of your
allow_extraentries as the first stage, whose reads pass the same file-read rules, and no credential file; sed -ion Linux (GNU sed) with onlydandscommands (noe,w,r, blocks, branches or bracket expressions), on files aneditwould change without a verdict;mkdir, andmvof such files onto a path awritewould create or overwrite without a verdict, which includes an existing file;rmof such files, with-fand-vonly (never-r,-dor a prompt flag), so a directory, a symlink and a missing path still go to the guardian;git addof named files (or-u),git rmandgit mv(-fallowed, never-r),git commitwithout--amendor--no-verify, andgit rebase,merge,cherry-pickorrevertwith--continue, optionally withGIT_EDITOR=truein front; the git steps skip the guardian only when the repository has no installed hook (anything in its hooks directory that is not a.samplefile), because a hook can run files edited in the same call;;,&&,||and!between them, a pipe of read-only commands, and output redirects or a non-expanding heredoc into a file awritewould change without a verdict.
A deny or ask rule for the
edit,writeorreadof any of those paths, an agent type that may not use the tool, or a pre-tool-use hook scoped to a file tool sends the whole call to the guardian instead, as does anything the parser cannot read in full (a substitution, a loop, acd, a background job, an input redirect). Hooks on file tools do not run for a shell edit, so a post-tool-use hook such as a formatter oneditdoes not either.acceptEditsis unchanged: a shell command still asks there. - a read-only command of the pre-classifier’s set, or one of your
-
The mode, as in the table above.
send_messageandboard_updatecome first: they reach only agents of the same tree, whose own calls are gated, so they run in every mode,dontAskincluded, with no guardian verdict and no prompt (tier = coordination).draft_bug_reportruns the same way (tier = bug_draft): it only writes a redacted draft under the data directory and sends nothing. Anagentspawn that did not take step 4 is never judged by the guardian:autoallows it (tier = spawn),manualandacceptEditsask you anddontAskdenies it. Every call the child makes is gated on its own, and the child’s mode is never looser than its parent’s, so judging the spawn’s prompt would repeat that coverage. Inautothe mode is the guardian: it answers allow, deny or escalate. An allow runs the call; a deny comes back to the agent asDenied by guardian: [Rule] explanation; an escalate asks you with the guardian’s explanation (and is a denial in a headless run). Three denials in a row, or twenty in a session, pauseautoand prompting resumes until you approve a call.
Every decision is appended to the audit log (<data dir>/audit/<session id>.jsonl, readable by the
current user only) before anything else sees it: the time, session, agent id and, for a subagent, its agent_name, the tool-call id, the
tool, a SHA-256 digest of the arguments (never the arguments), the tier that decided, the
decision (allow, deny or prompt), the rule and its source, and the latency. A human’s answer
to a prompt adds a second record with tier = human. The same record is projected to the
tool_decision telemetry event and to the headless gate_decision event, so the three agree. The
tier is one of deny_rule, ask_rule, protected_path, hook,
read_only_fast_path, tracked_edit, scratch_write, shell_edit, tier05, spawn, coordination, allow_rule, mode, screen,
guardian, dont_ask, human, guardian_off (the escape hatch was on),
afk (a temperature stop denied the call, or the record is an AFK toggle), bug_draft (a
draft_bug_report call) and bug_report (you filed a report with /bug). A record also has an
afk flag, and converted when a prompt nobody could answer became a denial; see
AFK mode. A guardian decision also records the guardian model and profile, its
verdict, confidence, the narrower call it said it would allow instead (instead, when it named one), whether the verdict came from the cache, how long the guardian took, the
verdict_transport it was asked on (tool, a forced submit call, or schema, for an Ollama
model with no tool support; see Models with no tool
support) and, when it failed closed, the reason (error,
timeout, unparseable, low_confidence, unavailable or not_signed_in). With a
composition configured, the record also carries
screen_risk, screen_allow_risk and screen_steering (the reads named stop, allow and
steering), screen_scores (every other read, by name), screen_model (the model id a hosted
read’s server resolved, such as typesafe/jev-1.14-20261014, with no account prefix; the
<account>/<model> label for a read that did not answer), screen_latency_ms and
screen_outcome, and a call the composition escalated, denied or allowed has tier = screen and
the deciding node as its rule (decision = prompt or deny for an escalation, deny for a
denial, allow for an allow). A composition that fails (a script error, a timeout, no verdict) is
a guardian denial with a fail_closed_reason. When an enforcing composition settles a call while
the guardian request that raced it is still pending, the record also carries
guardian_dropped_input_tokens, an estimate of that request’s input, with
guardian_dropped_provider, guardian_dropped_model and guardian_dropped_priced. They are
projected onto tool_decision as guardian.dropped_input_tokens, guardian.dropped_provider,
guardian.dropped_model and guardian.dropped_priced; see Telemetry.
A host as the human channel
In Agent SDK mode a canUseTool callback is the human channel. It is asked only
where the terminal UI would show an approval prompt, so after the hooks, the floor, the rules, the
mode and the guardian; a floor or guardian denial never reaches it. It never offers Allow-always, so
a host cannot persist a rule: an answer can add session allow rules and change the mode, nothing
else. A changed input is judged again from the start. Each decision’s audit record names the
channel (human_channel), next to the unchanged headless flag.
Background jobs and monitors
shell is judged when it is called; a command that later moves to the background, or that was
started with run_in_background, is not asked about again. job_output is read-only and names no
path, so it takes the fast path. job_cancel is an arbitrary tool that can only signal a process
or stop a subagent this session started, by id. monitor is an arbitrary tool with shell’s command analysis: the
destructive class, the critical_deletions fact and shell deny and ask rules (and hook matchers) cover
it, so a shell(git push) deny also stops a monitor that runs git push. An allow rule does not
cross over: shell(...) allows are for shell only, and the read-only pre-classifier never
allows a monitor by itself, so allow one with monitor(tail *) or let the guardian judge it. In
auto, monitor with no specifier is a broad allow like shell, and is set aside.
Task boards
With [agents] teams on (the default) the task boards add two tools. board_show is read-only and names no path, so it takes the read-only fast path in every
mode. board_update is a coordination tool like send_message: it writes only the session’s own
tasks.json and runs your task_created and task_completed hooks, so in every mode it runs at tier = coordination with
no guardian verdict and no prompt. A deny or ask rule naming board_update (a hook too) runs
first in every mode. It has no fast path and no specifier. Waking an idle agent
with send_message is likewise unjudged, and each call the woken agent makes passes the
whole pipeline. So in manual, acceptEdits and dontAsk agents can message and wake each other
without a prompt to you; spend is bounded only by the session and subagent budgets, which are
unset by default. A subagent type holding board_show or board_update can still take the read-only
spawn fast path when the rest of its tools are read-only.
The advisor
The advisor tool is an arbitrary tool with no exemption: it sends the
conversation and a question the model wrote to a second model, possibly on another account. The
floor, your rules and hooks run first as for any tool, then the mode’s path: in auto the guardian
judges the call, in manual you are asked and the prompt shows the question in full, and in
dontAsk it is denied. A headless -p run defaults to manual, so it needs
allow = ["advisor"] under [permissions] or auto mode. An allow rule in your user settings is
the way to use it without prompts. Only the main conversation has the tool.
Scheduled prompts
cron_create is an arbitrary tool, and always a destructive call for the guardian (so a low-confidence allow is denied), even though it touches no file: it plants model-written text
that will later run as a turn with nobody typing anything. In auto the guardian judges the call,
in manual you are asked, and the floor (a deny or ask rule naming cron_create, or a hook)
runs first as for any tool. cron_jobs, cron_delete and schedule_wakeup are read-only: they
list or cancel scheduled tasks, or re-time the prompt you gave a self-paced /loop, and name no
path.
A task that comes due runs as a turn the harness starts, framed by a note saying it is a scheduled
task and not you. It is never recorded as a user message, so it cannot add to what the guardian
takes as your intent; the intent stays what you typed, including the /loop line that started a
loop. The text of a task the model scheduled also passes through the tool-result scanner before the
model reads it. Calls the task’s turn makes go through the same pipeline as any other. /clear
cancels every scheduled task, because it drops the intent they were scheduled under. See
Scheduled prompts.
A goal turn is a harness turn in the same way: the evaluator’s reason and the goal’s
condition arrive behind a note saying they are not you and do not widen what you asked, no goal turn
is recorded as a user message, and only the /goal line you typed counts as your intent. The
evaluator’s reason passes through the tool-result scanner first. A goal does not change the mode,
and its calls go through the same pipeline.
Your own shell commands
A command you run in the terminal UI with ! is your own action, not a tool call: it bypasses the
pipeline above, including the floor and the guardian, and runs as you. It is still recorded. The
audit log gets one record with tier = human, decision = allow, rule = user_shell, tool = shell and agent_id = user, and the session ledger gets a user_shell record. See
Shell commands.
Rewinding
/rewind restores files from the copies write and edit saved. Like a !
command it is your own action, taken in the terminal: it does not pass through the pipeline above,
and the model has no tool that can request it. Because it writes on your behalf it checks each path
against the workspace roots and refuses symbolic links, and it never touches the memory directory.
Rules
[permissions] deny, ask and allow (and --disallowed-tools / --allowed-tools) share one
grammar: Tool or Tool(specifier). A bare tool name matches every call of the tool.
| Tool | Specifier | Matches |
|---|---|---|
shell | words, optionally ending in *: shell(git push), shell(npm run test *) | the parsed command line; quoting keeps a word whole; no wildcard inside a word |
read, edit, write, notebook_edit, ls, glob, grep, lsp | a gitignore-style path pattern: src/**, ~/.aws/**, //etc/hosts | the resolved path; relative patterns anchor at each workspace root, ~/ at your home (a deny or ask rule with ~/ matches everything when no home directory can be found; an allow rule matches nothing), // at the file system root |
webfetch | domain:example.com or domain:*.example.com | the URL’s host; *. matches subdomains only |
websearch | none | the tool name; the destination is the configured backend, not a host the model picks, so domain: does not apply |
mcp__<server>, mcp__<server>__<tool>, mcp__<server>__* | none | the registered tool name |
agent, skill | the agent type or skill name | exact name |
monitor | words, as for shell | the parsed command line, as for shell; a shell deny or ask rule covers monitor too, an allow rule does not |
send_message, board_update, board_show, ask_user_question, todo_write, models, tool_search, advisor, cron_create, cron_jobs, cron_delete, schedule_wakeup, job_output, job_cancel, list_mcp_resources, read_mcp_resource | none | the tool name |
Deny and ask rules fail toward matching; allow rules fail toward not matching:
- A
shelldeny or ask rule matches when its words appear contiguously anywhere in the parsed command, soshell(git push)also stopsls && git pushandsudo git push -f. A command that does not parse, or that puts an expansion where the command name goes, matches every rule whose first word it contains. - A
shellallow rule matches only one simple command whose words are all literal and whose words equal the rule (or start with it, for a trailing*). One leadingcd <dir> &&is tolerated when<dir>is a literal path inside the workspace roots: the rule then judges the command after it. Other chains, pipes, redirections, substitutions, globs and variables never match. Per-subcommand rules as Claude Code has them are not offered. - Path deny and ask rules match the path as written and the resolved path, so a symlink into a denied path is denied. Path allow rules match only the resolved path, so an allow on a symlinked alias does not apply.
- A
readdeny rule also keeps a file out of the instruction files the system prompt is built from, so a rule that stops the agent readingsecrets/**stopsCLAUDE.mdfrom importing it too. - A bare
websearchrule also governs the provider’s own search: while adenyoraskrule coverswebsearch, or apre_tool_usehook could (it has nomatcher, itsmatchernameswebsearch, or its matcher cannot be read), it is not offered to the model, and inmanual,acceptEditsanddontAskit is offered only when anallowrule exists. Inautoandafkit is offered otherwise, unless the denial breaker has pausedauto: it is then withheld from the next turn (the turn that trips the breaker keeps it until it ends) and returns on the next turn after you approve a call. Because it runs inside the model’s response, an offered provider search is checked once, when the request is built, not per query. A mode switch or a new rule takes effect on the next turn, so tightening the mode mid-turn (Shift+Tab, or the fallback when the guardian is unavailable) leaves the provider’s search attached until that turn ends; see Web search. - A
webfetchnever follows a redirect to another host: the redirect is returned to the model and a follow-up fetch is judged on its own host.
An invalid rule is a configuration error (exit code 2) naming the file and key. Rules from the
shared project file may only tighten (deny, ask); allow comes from the user file, an
untracked settings.local.toml and the command line. A plugin’s manifest may add
deny and ask rules only. The audit log and the gate_decision event name the scope that
contributed a rule, for example shell(rm) [user]; a plugin rule reads [plugin].
Allow rules
An allow rule acts after the floor and never past it: a deny, ask or protected-path
outcome stands whatever allow says. The floor does not look at what a shell command deletes, so an
allow rule that matches rm -rf / approves it, as it approves any call it matches. A matching allow rule skips the
prompt in manual and acceptEdits, pre-approves in dontAsk, and skips the guardian in auto.
While auto is on, broad code-execution allow rules are suspended: a bare shell or agent,
and shell(<entry>) or shell(<entry> *) for sh, bash, zsh, python, node,
ruby, perl, deno, bun, cargo run, npm run, npm exec, npx, bunx, pnpm, yarn, make, eval,
exec, xargs, env, sudo, doas, the interpreters awk, gawk, mawk, nawk, php, lua, luajit, tclsh and wish, the Windows shells pwsh, powershell and cmd, and the launchers timeout, nohup, setsid, nice, stdbuf, chroot, command, busybox, ionice, watch and flock. A wildcard rule is suspended whenever it can match something an entry covers: an interpreter counts by its program alone, so shell(python -c *),
shell(/usr/bin/python3 *) and shell(python3.12 *) are suspended too, and so are shell(cargo *) and shell(npm *), which reach cargo run and npm run. shell(cargo test *) stays. A call they would have approved goes to the guardian instead (a bare agent rule changes nothing, since a spawn is not guardian-judged).
Narrower rules such as shell(npm test) stay. The terminal UI lists the suspended rules when you
enter auto, and a headless run lists them in the init event; leaving auto restores them. A
pre_tool_use hook’s allow follows the same test on the hook’s matcher.
The approval prompt can create allow rules:
- Allow once runs this call.
- Allow session adds the rule shown in the prompt for the rest of the session. It is recorded in the session ledger and never written to disk.
- Always allow appends the same rule to
[permissions] allowin your user settings file, keeping the file’s comments and layout, and applies it at once.
The diff an edit, write or notebook_edit prompt shows is display-only: it is not sent to the guardian, hooks,
telemetry or the ledger, and it changes no decision.
The proposed rule is the narrowest that covers the call: the exact command words for shell, the
resolved absolute path for a file tool, the host for webfetch. Prompts that the floor forced, and
shell calls that are not one literal simple command, offer only allow once and deny, because no
allow rule can act there.
PowerShell
On Windows the powershell tool is an arbitrary tool whose commands are never read in advance:
the shell pre-classifier below handles POSIX only and never allows a
PowerShell command. Without an allow rule or hook, every call prompts in manual and reaches the
guardian in auto.
- Rules name the tool whole.
powershellis a rule by itself;powershell(Get-ChildItem *)is a configuration error. A bareshelldeny or ask rule also coverspowershell, so a blanket prohibition cannot be stepped around by switching language; ashell(git push)rule does not match apowershellcall, and an allow rule covers only the tool it names. Inautoa barepowershellallow is set aside, as a bareshellallow is. Remove-Itemtargets reach the guardian. Apowershellcall whose deleter (Remove-Item,ri,rm,rmdir,rd,del,erase) names a drive root, a top-level directory, your home directory, a workspace root or a parent of one by a literal path carries it to the guardian ascritical_deletions, as forshell. The scan is a token reader, not a PowerShell parser: the home forms (~,$HOME,$env:USERPROFILE) are resolved (variables in a single-quoted word are literal text), but any other variable, a cmd-style%VAR%, a subexpression, a wildcard, targets piped in, a relative target after aSet-Locationorcd, a nested interpreter or a computed command name adds nothing, and the guardian reads the command itself. Targets on other providers (HKLM:,Env:,Cert:) are not file deletes and are left to the guardian.- Trusted skills. A plugin skill you trusted lends its specific
allowed-toolsas allows for the turn, after the floor, deny and ask rules and hooks. Its wildcard shell rules (Bash(git *), a bareBash) are not allows in any mode: they reach the guardian as anactive_skillline (see the guardian’s request), while your ownshell(git *)allow rule stays an allow. Skills in your own skills directory keep lending all their rules. Neither goes to a subagent. - Skills and restrictions. A skill’s
!lines run throughshellonly, including commands formed from arguments the model passed to theskilltool, so a subagent whose tools are onlypowershellhas nothing to run them with. A restriction that namesshell, such asshell(git *), does not constrainpowershell; namepowershellto allow or forbid it.
The shell pre-classifier
A small set of read-only commands runs without a prompt when the call is one simple command made of
literal words, parsed by a real shell parser, with every path inside the workspace roots. The
call’s cwd (the directory the shell was left in by an earlier call when the call names none) is
resolved first, and a cwd outside the roots disqualifies the call. Anything not
fully understood falls through to the next step: a chain, pipe, redirection, background marker,
substitution, variable, tilde, glob, brace pattern or assignment prefix.
| Command | Allowed flags | Values checked as in-scope paths |
|---|---|---|
ls | -a -A -l -h -1 -d -t -r -S -F | positionals |
pwd | none | |
wc | -l -w -c -m | positionals |
file | -b -i --mime --mime-type --brief -m FILE --magic-file FILE | positionals and the -m value |
cat | -n -b -s | positionals |
head, tail | -n N -c N -q -v | positionals |
rg | -i -s -S -n -N -H -w -x -F -v -c -l -A N -B N -C N -m N -t TYPE -T TYPE --hidden --no-heading -f FILE --file FILE --ignore-file FILE | positionals and file values |
grep | -i -n -v -w -x -F -E -c -l -L -H -h -o -q -s -r -A N -B N -C N -f FILE --file FILE | positionals and file values |
git status | none | |
git diff | --cached, --staged | path positionals |
git log | -n N, --max-count=N | |
git show | --stat | <rev> or <rev>:<path> (path part checked) |
git ls-files | none | |
git branch | -a, -r, -v, -vv | |
git rev-parse | none | HEAD only |
git tag | -l, -n N |
Any other flag, any --flag=value whose flag is not listed, and any short-flag cluster with an
unlisted letter falls through. ls -la is accepted as -l -a. A value-taking short flag takes an
attached value (-n5) or, as the last letter of a cluster, the next word (-nA 3). Numbers must
parse as integers. Excluded on purpose: tail -f, file -f, rg --pre, rg -z, rg -L,
rg -g, grep -R and grep --exclude-from, because they run programs, follow links or read
indirectly. Supported git subcommands are executed through gix with isolated, strict
configuration, so repository-controlled helpers (fsmonitor, filter drivers, gpg.program) cannot
run. Every other git subcommand, including git push, git clean, and any flag not listed
above, falls through.
[shell_preclassifier] allow_extra adds commands to the set: a command (make) or a command subcommand pair (cargo metadata). It is accepted from user-trust scopes only, an extra entry
takes no flags (any flag falls through), and its positional words must be in-scope paths. A grant
from the prompt never extends the set.
Each word of the command that could be a path
(including the value of --flag=value), as written and resolved against the call’s cwd (the shell’s current directory when it names none), is checked
against the read deny and ask rules, and against the ls or grep rules for those commands. A
deny match denies the call and an ask match asks, so deny = ["read(.env)"] also stops cat .env. Only the words written in the command are
checked: files a recursive search reaches under a directory (grep -r KEY .) are not checked
one by one. read deny rules are not a containment boundary for shell; use a shell deny or
ask rule, or the protected paths. The same calls are held to the restrictions of the agent type
that runs the command (disallowed and only entries on read, ls and grep), so a
disallowed: ["read(secrets/**)"] agent cannot cat secrets/key either.
A pre_tool_use hook whose matcher names read, ls or grep is not run on these
synthesized calls, so it takes every pre-classified shell read off the tier05 fast path instead:
the call goes on to the allow rules and the mode. Such reads need an allow rule in dontAsk
mode, prompt in manual mode and go to the guardian in auto.
A word that names a secret file (cat .env,
grep -f.env x; ls only lists names and is exempt) is not pre-classified: the call falls
through to the allow rules, the hooks and the mode. An allow rule restores the skip only when
every secret operand is covered by a rule of its own, so allow = ["read(.env)"] covers cat .env
but allow = ["read(README.md)"] does not cover cat .env README.md; the call is then audited
with tier = allow_rule. Secret-name matching always ignores case, while rule matching follows
the file system (on Linux read(.env) does not cover .ENV), and a read rule matches the
resolved path, so a symlink to .env needs an allow naming the file it resolves to. Files that a
recursive search reaches (grep -r KEY ., or the grep tool over a directory, including its
hidden and glob options) are not checked one by one. grep’s pattern operand is treated as a
path, so grep .env README.md may ask or be judged: this errs toward caution.
A pre-classified call is audited with tier = tier05. In auto these calls, the read-only
fast path (a read-only spawn included; a secret file read is not part of it), every other agent spawn, the coordination tools and the tracked and scratch edits are the only guardian skips earned without a grant of yours; an out-of-scope read such
as ls ../, anything the pre-classifier cannot fully parse, and every MCP tool go to the guardian.