Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

ModeWhat happens to a call nothing pre-approved
manualThe human is asked.
acceptEditswrite, edit and notebook_edit inside the workspace roots run; everything else asks.
dontAskDenied, except send_message and board_update. Only other calls that are pre-approved run.
autoThe 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.
afkAFK 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.

  1. 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.

  2. The deterministic floor, in this order:

    • a [permissions] deny rule: denied.
    • an ask rule, a hook’s ask, or an MCP tool its server marked as requiring your approval: asks.
    • protected path: write, edit and notebook_edit on a path with a component named .git, .vscode, .idea, .husky, .fontaine or .claude, or whose file name is .gitconfig, .gitmodules, .bashrc, .bash_profile, .zshrc, .zprofile, .profile, .ripgreprc or .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. In auto the guardian takes the place of the prompt, for a path the file tools can reach.

    A floor outcome that asks is a denial in dontAsk and in headless runs. In auto an ask rule and a server’s approval marker still ask you: no verdict approves them.

    A shell, monitor or powershell call 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 in auto the guardian is told which of those places it names (critical_deletions) and denies it in either profile.

  3. 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. A read, grep or lsp of a secret file does not: it goes on to the allow rules, the hooks and the mode, so manual and acceptEdits ask, dontAsk denies and auto sends 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. lsp has no external route at all: a path outside every root is denied, with the /add-dir hint. skill, ask_user_question, todo_write, models, board_show and the read-only scheduling tools name no path and take this step too. ask_user_question only shows you text and collects your choice, and no mode, auto included, 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. An agent call 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 tools send_message and board_update; board_show is read-only), the spawn runs without the guardian or a prompt, in every mode. worker, fork and any type whose set holds agent, shell, a write tool, a network tool (webfetch, websearch; models is 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. A deny or ask rule on agent and 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, and shell treats 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, glob or grep is not denied here: it falls through to the same steps as any other call nobody pre-approved. An out-of-root write by write, edit or notebook_edit falls 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. In manual and acceptEdits an external write asks (that approval is itself the establishment that you asked for it, and the prompt shows the resolved target’s diff); in auto the guardian decides, allowing it only when your own messages, including what you picked in a question dialog, asked for that write; in dontAsk and 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 the allow_rule or hook tier; it is never audited as read_only_fast_path or tier05, and in auto it never takes the tracked_edit or scratch_write fast 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; shell has 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 in auto. An external path does not become a root: it grants no write reach of its own, no fast path and no instruction-file discovery.

  4. Shell pre-classifier, below.

  5. Allow rules, below.

  6. Edits that skip the guardian (auto only). After the floor and the hooks, a write, edit or notebook_edit call is allowed without a guardian verdict in two cases, and a shell call in a third (shell_edit, below). A file-tool write whose resolved target is inside the session scratch directory is audited as tier = 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 as tier = tracked_edit when 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, /home or /) and any path when git cannot be read (an unparseable repository configuration or index); the auto-memory store and /add-dir roots; the protected paths above; credential files (.env, key files); persistence and code-execution locations (.envrc, .zshenv, .zlogin, .bash_login, .xprofile and similar login files, and anything under a .ssh, .gnupg, .aws, .docker, .kube, .cargo, .config, .local or LaunchAgents directory), 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 a rules directory 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’s core.hooksPath names inside the root), because the next commit or rebase step runs what it says; and every shell command except a shell_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 keeps auto from pausing. Turn them off with auto_tracked_edits, auto_scratch_writes and auto_shell_edits; project scope may only switch them off.

    A shell call is audited as tier = shell_edit when 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_extra entries as the first stage, whose reads pass the same file-read rules, and no credential file;
    • sed -i on Linux (GNU sed) with only d and s commands (no e, w, r, blocks, branches or bracket expressions), on files an edit would change without a verdict;
    • mkdir, and mv of such files onto a path a write would create or overwrite without a verdict, which includes an existing file;
    • rm of such files, with -f and -v only (never -r, -d or a prompt flag), so a directory, a symlink and a missing path still go to the guardian;
    • git add of named files (or -u), git rm and git mv (-f allowed, never -r), git commit without --amend or --no-verify, and git rebase, merge, cherry-pick or revert with --continue, optionally with GIT_EDITOR=true in front; the git steps skip the guardian only when the repository has no installed hook (anything in its hooks directory that is not a .sample file), 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 a write would change without a verdict.

    A deny or ask rule for the edit, write or read of 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, a cd, 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 on edit does not either. acceptEdits is unchanged: a shell command still asks there.

  7. The mode, as in the table above. send_message and board_update come first: they reach only agents of the same tree, whose own calls are gated, so they run in every mode, dontAsk included, with no guardian verdict and no prompt (tier = coordination). draft_bug_report runs the same way (tier = bug_draft): it only writes a redacted draft under the data directory and sends nothing. An agent spawn that did not take step 4 is never judged by the guardian: auto allows it (tier = spawn), manual and acceptEdits ask you and dontAsk denies 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. In auto the mode is the guardian: it answers allow, deny or escalate. An allow runs the call; a deny comes back to the agent as Denied 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, pause auto and 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.

ToolSpecifierMatches
shellwords, 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, lspa gitignore-style path pattern: src/**, ~/.aws/**, //etc/hoststhe 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
webfetchdomain:example.com or domain:*.example.comthe URL’s host; *. matches subdomains only
websearchnonethe 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>__*nonethe registered tool name
agent, skillthe agent type or skill nameexact name
monitorwords, as for shellthe 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_resourcenonethe tool name

Deny and ask rules fail toward matching; allow rules fail toward not matching:

  • A shell deny or ask rule matches when its words appear contiguously anywhere in the parsed command, so shell(git push) also stops ls && git push and sudo 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 shell allow 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 leading cd <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 read deny rule also keeps a file out of the instruction files the system prompt is built from, so a rule that stops the agent reading secrets/** stops CLAUDE.md from importing it too.
  • A bare websearch rule also governs the provider’s own search: while a deny or ask rule covers websearch, or a pre_tool_use hook could (it has no matcher, its matcher names websearch, or its matcher cannot be read), it is not offered to the model, and in manual, acceptEdits and dontAsk it is offered only when an allow rule exists. In auto and afk it is offered otherwise, unless the denial breaker has paused auto: 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 webfetch never 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] allow in 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. powershell is a rule by itself; powershell(Get-ChildItem *) is a configuration error. A bare shell deny or ask rule also covers powershell, so a blanket prohibition cannot be stepped around by switching language; a shell(git push) rule does not match a powershell call, and an allow rule covers only the tool it names. In auto a bare powershell allow is set aside, as a bare shell allow is.
  • Remove-Item targets reach the guardian. A powershell call 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 as critical_deletions, as for shell. 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 a Set-Location or cd, 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-tools as allows for the turn, after the floor, deny and ask rules and hooks. Its wildcard shell rules (Bash(git *), a bare Bash) are not allows in any mode: they reach the guardian as an active_skill line (see the guardian’s request), while your own shell(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 through shell only, including commands formed from arguments the model passed to the skill tool, so a subagent whose tools are only powershell has nothing to run them with. A restriction that names shell, such as shell(git *), does not constrain powershell; name powershell to 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.

CommandAllowed flagsValues checked as in-scope paths
ls-a -A -l -h -1 -d -t -r -S -Fpositionals
pwdnone
wc-l -w -c -mpositionals
file-b -i --mime --mime-type --brief -m FILE --magic-file FILEpositionals and the -m value
cat-n -b -spositionals
head, tail-n N -c N -q -vpositionals
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 FILEpositionals 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 FILEpositionals and file values
git statusnone
git diff--cached, --stagedpath positionals
git log-n N, --max-count=N
git show--stat<rev> or <rev>:<path> (path part checked)
git ls-filesnone
git branch-a, -r, -v, -vv
git rev-parsenoneHEAD 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.