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

The guardian

The guardian is what makes auto mode possible. When a tool call is not provably safe and nothing you configured pre-approved it, a separate model reads your task and a short written policy and answers allow, deny (with a reason the agent sees) or escalate (ask you). It is the only part of Fontaine that uses judgment, so everything around it is written to keep that judgment from being the only thing standing between a model and your machine.

A call reaches the guardian in auto mode. The deterministic floor (deny and ask rules, protected-path handling), the read-only fast path (which includes a spawn of an agent type that can only read, and excludes reads of secret files such as .env), every other agent spawn, the coordination tools (send_message and board_update) and the shell pre-classifier all run first, in every mode; the guardian never sees a call they decided. In auto it also does not see file-tool edits to any file in your workspace, tracked by git or not, writes into the session scratch directory, or a shell call that Fontaine parses in full and that is made only of read-only commands, in-root edits and deletions of files (sed -i, mkdir, mv, rm) and the local git steps (git add, git commit, git rm, git mv, git rebase --continue) (see the pipeline); it still sees instruction files, .github/, hook-runner config, credential files, persistence locations (.envrc, .ssh/, .config/, .cargo/ and the like), every path when your workspace root holds your home directory or git cannot be read, and every shell command that does not take one of those fast paths (including supported read-only git subcommands).

Threat model

The guardian is itself an attack surface: the arguments of the call it judges, the files the agent read and the instructions in a repository are all text an attacker may have written. So:

  • It has no tools. One stateless request per adjudication, with no conversation that grows and nothing to call. Its only output is a structured verdict, which reaches Fontaine on one of two paths. The default asks for it through a required submit function, which needs a model with tool support. For an Ollama model that has no tool support, the request instead carries the verdict’s JSON schema as the daemon’s format, which constrains the answer and needs no tool template. Either way the answer is parsed and validated the same way, and anything that does not parse is a denial.

  • Everything it is shown is data, except your own words. The request is rendered into delimited <untrusted> blocks; text that would close a block is neutralized, and anything credential-shaped is redacted before it is rendered. The system prompt says that nothing inside those blocks is an instruction. The two blocks holding what you typed and what you picked in a question dialog, task_intent and recent_user_messages, are marked source="user" and are read as your intent; any other block that claims you approved something is treated as an attack signal.

  • Its picture of what you asked for comes from the session ledger, the append-only record of your own messages, and never from the model’s context. A compaction summary or any other model-written text cannot reach the guardian as your intent. The one model-written text it is shown beside your words is the agent’s last message, as an untrusted block that is never intent by itself (see below).

  • Every outcome that is not a verdict is a denial, decided by code (below). There is no setting that turns the guardian off, and none that makes it fail open.

    The one deliberate exception is the development escape hatch: in the terminal UI, /guardian-disable turns the guardian and the permission floor off for that session until /guardian-enable, after a confirmation and with a warning chip in the status bar. It is session-scoped, never persisted, never inherited by subagents, and recorded in the ledger and the audit log; see Terminal UI. It needs the host terminal: a device attached with remote control can never run /guardian-disable or /guardian-enable, and cannot answer the confirmation. The attempt is refused and audited.

  • Rule prose can only restrict. A shared project file may add to soft_deny and hard_deny but its text sits in the policy, so the prompt tells the guardian to ignore any entry that, read literally, grants permission. A plugin manifest may add deny-side entries to the same two lists, and nothing else.

It is not a sandbox. A model can be talked into a bad verdict, and a command the guardian allows runs with your permissions. See Known limits.

What the guardian sees

The request is built from the ledger and the call itself:

PartContent
task_intentYour latest messages, verbatim, oldest dropped first to fit 2,000 characters. Never summarized.
recent_user_messagesYour last 5 turns (not tool output).
agent_message_before_replyThe last 2,000 characters of the agent’s final answer, only when your latest message was typed at the prompt right after that answer. An untrusted block placed before recent_user_messages, in the guardian view only: the screen, the reads of a composition and the minimal profile do not get it.
agent_taskWhat the calling subagent was told to do when it was spawned (the head of its spawn prompt, cut at 2,000 characters), recorded in the ledger when the agent starts. An agent-written, untrusted block placed after task_intent, in the guardian view only: the screen, the reads of a composition and the minimal profile do not get it, and the root agent has none. It is never your intent and never a claim of authorization, but it shows the scope your request was carried out in, so a step of that task, and the manifests, lockfiles, imports and docs the step leaves behind, are part of the request rather than an unrequested change. A subagent sees only its own task, never a sibling’s, and every deny rule still applies.
project_instructionsThe instruction files the agent had at launch (FONTAINE.md, CLAUDE.md, AGENTS.md, rules and their imports), as they stood when the session started: the primary root’s level first, then each directory above it, then yours, cut at 16,000 characters. Files loaded later on demand never reach it. See Instruction files.
environment, rulesThe [auto_mode] prose lists, with the shipped defaults spliced in.
tool_callThe tool, its full arguments (a shell call made after an earlier cd carries the absolute directory it starts in as cwd), a digest of them, destructive, derived by Fontaine from the call itself (below), and, when the call deletes one, critical_deletions (below). Every powershell call is judged, none is read as safe beforehand, and the request says the command was only partly parsed.
session_factsThe workspace roots, the workspace trust state, the git remotes at session start (each shown with its git name and URL, as origin https://…; (none) when the repository had none, and (not recorded) when the harness did not read them or could not read them completely (no root is a repository, or a repository has an include or includeIf section in its config or a remote without a fetch URL; a root that is not a repository is skipped when another root is one), in which case a git name the call uses is trusted unless this call or an earlier one in the session added or repointed it; the screen keeps bare URLs and (none)), the home directory of the user running the session as a home_directory line (guardian view and minimal profile; not the screen or the reads of a composition; set by Fontaine and never from a tool argument), the names (never the values) of the [env] variables you set, the status (pre_existing, created_this_session, unindexed (the session did not record creating it), absent or session_scratch; never the file index) of only the paths this call touches, which for a shell command are its redirect targets (a redirect to /dev/null writes no file and is not listed) and path-like arguments, a git_tracked mark on a file git’s index holds (never on a directory; a shell command gets both marks only when it is a single simple command (no list, pipeline or substitution) with a certain working directory and no glob or pathspec word, and a file tool always gets them), the project environment when you ran the setup command, and the last 20 actions of the session, and, in the guardian view only, a git_operation line when a rebase, merge, cherry-pick, revert, am or bisect is stopped in the primary root (git_operation: rebase in progress on <branch> (started this session), or (in progress since before this session); the harness reads it from the repository and records at session start whether one was already stopped, so a resumed session keeps the answer). Resolving the conflicts of an operation that started this session, staging the result and --continue complete the request that started it; for one in progress since before the session, resolving its conflicts inside the roots, staging and --continue are still treated as local undoable steps, while --abort, --skip and pushes are judged as usual. When auto memory is on it also has an agent_memory_directory line naming the memory store, set by Fontaine and never from a tool argument. It also has a session_scratch_directory line naming the session scratch directory, whose paths carry the session_scratch status. Fontaine sets all of these from the session, never from a tool argument; the minimal profile and the reads of a composition get no scratch line and no absent or git_tracked marks (they do get the memory line). The reads do not get the project environment, which only the guardian view renders; the minimal profile does. The absent status and the git_tracked mark are likewise only in the guardian view: the reads and the minimal profile see the paths as before.
hook_contextNotes from pre_tool_use hooks, in an untrusted block.
prior_denialsReason-coded denials earlier in the session, for loop detection. They are context, not evidence about the current call (see How history and your words are weighed).

The task_intent and recent_user_messages messages start after your last /clear: what you asked before it is not shown to the guardian, while the session facts are kept. A /rewind of the conversation takes the prompts it retracts out of them the same way, so a message you took back no longer counts as intent; the denials and approvals stay.

What you typed and what you picked count as user intent. When the model asks you a question with ask_user_question, your answer is recorded as one line per question: Answered the agent's question "<question>": picked "<label>" ("<description>"), with ; typed "<text>" added when you typed under “Other” or wrote a note on a choice, and only typed "<text>" when you picked nothing. The question and the options are the model’s words, so the guardian credits you with the option you picked, read with its question, and nothing broader: no standing grant, and no action the option does not describe. The screen of a composition never reads these lines, because its allow skips the guardian, which is the only reader told that the question and options are agent-written; a typed answer leaves the screen’s view too.

When you reply to the agent’s last message in plain chat (“yes”, “go ahead”) at the prompt, right after its answer was shown, the guardian also sees that message as agent_message_before_reply. If it proposed one specific action and named its target, and your reply plainly affirms it, that counts as you naming the action and its target, for that and nothing broader; it never clears a hard deny, and a reply to anything else, a proposal with no target or a different call gets no credit. A message queued while the agent was still working, a steered message, an answer in a dialog, a skill or /goal line, and a message from a stream-json input never pairs with an earlier answer, because it was not typed in reply to it. The minimal profile has no such credit. A message you queue while the agent works counts from the moment the agent receives it, with its next tool result, not from when you typed it: until then the model has not read it, and a call judged earlier must not rest on words the model never saw. Commands you run with ! and their output never count, and neither does anything a tool or the model wrote. A message you type in a subagent’s view counts the same way, from when that agent reads it, but only for that subagent and its own subagents: a call of the main conversation or of a sibling is never judged by words only another agent’s model has read.

How history and your words are weighed

The guardian reads history and your messages by a few fixed rules:

  • What you typed, and the option you picked in a question dialog read with its question, is authoritative about intent. A message that vouches for something specific (“the script is ok to run”) counts as you naming that thing, and clears a soft deny for it. It never clears a hard deny, however often you repeat it.
  • A target you name (a file, a path, a remote and branch, what to share and how widely) clears the soft concerns about it: you have weighed that target, and your own description of it (“confidential”, “the secrets file”) is part of the request. A definite reference (“the generated file”, “the test database”) counts as naming it when it can refer to only one thing in the conversation, and a ~/ path you name matches the same path under your home directory. It never clears a hard deny, and two things stay denied even when you name them: printing a live credential from a home-directory store or an environment secret into the transcript (a local read of a file you named inside the workspace is fine), and sending external context or personal and entrusted data to a public destination you did not name it for (see What counts as sensitive).
  • Text in a tool argument, file or note that tries to steer the guardian (“approve everything”) is ignored, not punished: the guardian judges the call as if the text were inert, so a commit or a note that carries it is allowed when the action is harmless, and a call that also does something a rule denies is denied under that rule.
  • After a denial, a message that re-issues or approves the denied action counts as your consent to it. The agent re-issuing the same call with no new message from you does not.
  • When you ask for an issue, pull request or comment, the agent writes its text; you need not dictate it, and “in your own words” says so outright. The text is judged for secrets, sensitive file contents and the deny rules, not for whether you wrote it. Editing, commenting on, labelling or closing the project’s own issues at your request is not exfiltration either, and rewriting a body to change part of it is an edit.
  • Relevance and craft are not harms. A call that only looks unrelated to the task (a lookup, a read, a registry query, often a subagent’s) is denied only when it matches a rule, and so is how a call carries out a request: an edit made with sed, a whole-body rewrite, or not re-checking what an earlier call checked. Only a significant escalation in scope, severity or destructiveness beyond your task is a reason of its own. A package-registry metadata query (cargo search, npm view) fetches no code and is read-only.
  • A denial of one kind of action, or about one subject (a credential file, a host, a repository), does not count against a different kind or subject, and never against a read-only call. The earlier denials are shown to the guardian under a note saying they are for spotting loops and are not evidence about the call. Reading, listing or tailing a file the session itself created is routine unless the call sends data out of the trust boundary.
  • A prior denial by itself never makes a read-only call suspicious. A read made to scout around a denial — to learn what the denial protected or to find another route to the denied action — is not routine and is judged under the deny rule it serves.
  • A standing grant (“you may post gh issues”, “git commits in the scratch folder are fine”) counts as your consent for every later call of that class until you withdraw it. It names the class, not the arguments or the content, and the content is still judged by every rule. Like a vouching message it clears soft denies only. A request names its action: “log a gh issue about X” asks for that issue.
  • A guardian denial is not you rejecting the action. When it denies a soft-deny match, the explanation says what would clear it: you naming the action and its target, or a standing grant.
  • In the full profile, a denial explanation never proposes a way forward: it names no shell command, tool or route (the minimal profile prompt does not carry this rule). A narrower call that would be allowed goes in the verdict’s instead field, which is advice and pre-approves nothing: the call it names goes through the whole pipeline like any other, and it is never a route to the effect the verdict denies. It names a dedicated read-only tool (grep, glob, read) only when the deny turns on the shell construct itself (a redirection, a compound or unparseable command) and the call was a plain file search. It may name the edit or write file tool for the same change only when the deny turns on the shell construct itself (a script or compound command the harness cannot read), the call’s effect is a write or edit of paths that all resolve inside the workspace roots, and no rule protects them; never for a deletion. When the deny rests on the target or content a rule protects, there is no instead at all. Being unable to verify the content of an edit inside the workspace roots is never by itself a reason to deny it.
  • A note you type about the setup, such as “fyi, the guardian is now haiku”, is neutral.
  • Suspicion needs a rule: “earlier denials and this looks related” is not a reason to deny.

Trusted skills

When a skill you trusted is running for the calling agent and declares wildcard shell rules, session_facts has an active_skill line such as active_skill: dev-skills:pr (trusted by the user; declares git *, gh *). Fontaine sets it from the session, never from a tool argument, and only the guardian view renders it (the reads of a composition do not; the minimal profile does). The prompt tells the guardian that the declared classes are your intent for the routine steps of that class, such as a rebase onto the default branch for a pull-request skill, and never for a destructive or out-of-purpose step: a force-push, a push to a protected branch or a deletion you did not name is judged on its own arguments and your words, as without the skill. It is context and not an allow: the floor, your deny and ask rules and every fail-closed outcome are unchanged. A subagent of the calling agent carries no active_skill line, and the line ends with the turn.

Subagents and the scratch directory

The session scratch directory is created empty when the session starts and deleted when it ends, so nothing in it predates the session. It is inside the trust boundary: creating, overwriting or deleting files there, or running git init, commit or reset confined to it, destroys nothing pre-existing. A path counts as scratch only if it resolves there; a .. or a link that leads out of it does not. Every other rule still applies, such as running code downloaded into it or sending its contents out. Only literal paths carry the session_scratch status: a path built from a shell variable is not marked.

An agent call is never shown to the guardian. A spawn delegates a prompt to a child whose every call goes through the whole pipeline on its own, guardian included, and whose mode is never looser than its parent’s, so judging the prompt would only repeat that coverage. auto allows the spawn (tier = spawn) after the deny and ask rules and hooks; manual and acceptEdits ask you (see the pipeline).

send_message and board_update are never shown to the guardian either. They reach only agents of the same tree, whose calls are each gated, so every mode runs them after the deny and ask rules and hooks with tier = coordination (see the pipeline).

The verdict

decision     allow | deny | escalate
rule         allow, or one label of the list below
explanation  1-3 sentences, shown to you and fed back to the agent on a deny
confidence   0 to 1, the guardian's own estimate
instead      optional, only with deny or escalate: one narrower call it would allow in place of this one

rule is allow exactly when decision is allow; a verdict where they disagree, a label outside the list or a confidence outside 0 to 1 is malformed. The labels are Download+Execute, Data Exfiltration, Production Deploy, Git Destructive, Destroy Pre-existing Files, IAM Grant, Secret Exposure, Tunnel/Reverse Shell, Unguarded Agent Loop, Safety Bypass (disabling safety flags or security-guarding tests, adding persistence, or editing the agent’s own settings), Remote Redirect, Unreviewed Merge and Container Escape (minimal profile only). A deny reaches the agent as Denied by guardian: [Rule] explanation. Allowed instead: call. Do not retry it or look for another route to the same effect; tell the user what you could not do. If the denial itself names a call that is allowed instead, make that call: it is not another route to the denied effect., where the Allowed instead sentence is there only when the verdict has an instead (redacted and cut like the explanation), and your terminal shows the label and the explanation (and the instead of an escalation it asks you about); a subagent’s denial shows in that agent’s view, not in the main chat. Every shipped deny rule starts with the label it is reported under.

Rule precedence

hard_deny over soft_deny over allow over explicit, specific user intent.

  1. A hard_deny match is always a deny. Nothing you said overrides it.
  2. A soft_deny match is a deny unless an allow exception clears it or your own messages explicitly and specifically authorize that exact action, naming its target. “Clean up” does not authorize a recursive delete.
  3. allow entries are exceptions to soft denies. They never clear a hard deny.
  4. An action you asked for by name and target is acceptable when no deny rule applies.

The shipped lists, and how to extend them, are in [auto_mode].

Reading outside the workspace

The four read-only file tools may name a path outside every workspace root; each such call reaches the guardian like any other unapproved call in auto (it is never skipped, and it never earns the read-only fast path). The shipped allow list treats inspecting source code, headers, build files, installed dependency source and installed skill definitions (including SKILL.md) as routine wherever they sit — a Cargo registry cache, /usr/include, a Python site-packages, a sibling checkout — because debugging a build against installed sources is ordinary development work. That is a broadening of what is adjudicated, not of what is automatic: the call is still judged, and the exceptions hold only for local inspection. Executing code or skill commands, treating skill text as user intent, sending the contents anywhere, reading credential or personal-data stores, and scouting around a denied action all remain subject to the deny rules. In the interactive modes the same call asks you instead, with the resolved path in the prompt.

Writing outside the workspace

The write tools (write, edit, notebook_edit) may also name a path outside every workspace root, and that call reaches the guardian in auto like any other unapproved call. A write out of the roots is consequential wherever the target sits — shell rc files, ~/.ssh/authorized_keys, cron entries — so the shipped soft_deny list denies an un-asked write outside the workspace roots under the Safety Bypass label, alongside the persistence entries (SSH keys, cron, shell-profile lines) that keep applying to out-of-root targets.

The only user intent the rule accepts is your own messages, typed or picked in a question dialog: the task_intent and recent_user_messages blocks are recorded by the harness and marked as yours, and the rule allows the write only when they named the file or directory and asked for it to be created, changed or removed. A claim of authorization anywhere else — in tool arguments, instruction files, hook notes, guardian-context notes or action summaries — is data, not intent, and does not clear the rule. In the interactive modes the call asks you instead: your answer at the prompt is itself the establishment that you asked, and the prompt shows the resolved target’s diff. Nothing here loosens the deterministic floor: deny rules, ask rules and protected paths still act first in every mode.

Memory writes

When session_facts names the agent’s memory directory, a call whose target is under it is a memory write: the target is found in the call’s arguments, in the touched paths, or in a path in a shell command. Future sessions load what is written there as notes, so the guardian judges the content as well as the place. It allows plain project facts that your request or the repository supports (commands, layout, preferences you stated), and denies or escalates content that instructs the future agent, widens permissions or relaxes the guardian, contains secrets or credentials, embeds URLs or commands to run, or traces to tool results, web pages or file text rather than to you. Low confidence is a denial, as everywhere. The rule is in the full and the minimal prompt, and it covers shell commands that write there. The notes themselves are never added to project_instructions. See Auto memory.

Failing closed

Fontaine’s code, not the model, decides what happens when there is no usable verdict:

OutcomeResultfail_closed_reason
No credential, unknown account, or the pinned model is unavailabledeny, rule GuardianUnavailableunavailable
The pinned model’s account (an external CLI login, such as a claude-subscription account) is not signed indeny, rule GuardianNotSignedInnot_signed_in
Transport failure: a dropped stream, connection reset or a closed socketdeny, rule GuardianUnavailableerror
A provider HTTP error response, e.g. 400 context too large, 401/403 authdeny, rule GuardianUnavailableerror
No answer within [guardian] timeout_secs (default 30, retries included; an attempt that stalls is dropped and retried inside it)deny, rule Timeouttimeout
Malformed, schema-invalid or out-of-enum verdict after two retriesdeny, rule Unparseableunparseable
An allow on a destructive call with confidence below confidence_threshold (default 0.7)deny, rule LowConfidencelow_confidence
The guardian’s account has spent its usage window and the wait was cancelled or ran outdeny, rule UsagePauseEndedusage_pause_ended

The retry budget is two retries, shared between malformed answers, provider errors and stalled attempts, and the last failure names the denial. Each attempt gets a slice of timeout_secs: the first may use all but 10 seconds of it (for timeouts of 15 seconds or more) and each retry gets at least 5 seconds when that much remains, so a call that never answers is retried instead of using the whole timeout, while timeout_secs stays the ceiling. A slow model therefore needs a timeout_secs above its worst answer time plus 10 seconds. A malformed verdict is retried with a note saying why it was rejected, written by Fontaine and never quoting the model’s own text; if it still fails it is denied as unparseable. A deny verdict is never softened. The destructive class is derived from the call by Fontaine, structurally, never from the label the guardian chose: a call is destructive when it removes or overwrites (rm, mv, cp, dd, sed -i, find -delete, git reset --hard, a redirect to a file, a write over a path that existed), writes outside every workspace root, reaches the network (curl, git push, a package install, webfetch, websearch), schedules a prompt to run later (cron_create), runs a command as a monitor (judged like shell), starts a code runner (sh, python in any version, pwsh, cmd, awk, make, cargo run, sudo, …; a launcher such as timeout is judged by the program it wraps), is an MCP call, or uses any construct the shell parser cannot classify. A plain cargo test 2>&1 | tail is not destructive, and neither is rg x src 2>/dev/null: a redirect to /dev/null (that exact spelling) writes no file.

critical_deletions is a second fact the harness computes from the call. When the operands of rm, rmdir or Remove-Item (in a shell, monitor or powershell call, in any segment of a list, pipe or substitution) are literal paths, ~ or $HOME and one of them is the file system root, a top-level directory, your home directory, a workspace root or a parent of one (a symlink to one counts; the session scratch directory itself is not one, its parents are), the request lists it as the resolved path and its kind, such as /home/me (home directory). A target the harness cannot resolve (a variable, a glob, an expanded command name, a relative target after a cd, arguments a launcher such as xargs reads at run time) adds nothing; wrappers (sudo, env, timeout, xargs…) with literal operands are still read: the guardian reads the raw command and judges it under Destroy Pre-existing Files, which covers a recursive delete whose target the call does not make clear. Nothing that resolves inside the workspace roots is that rule, whatever the path’s status (pre_existing, unindexed or git_tracked, marked or not) and whether or not git tracks it: every edit, overwrite, truncation, move, copy, extract and deletion there, by shell or file tool, is routine, because workspace files are assumed to be backed up (a glob with a literal part inside the roots counts as inside). .git and anything under it (including expiring the reflog or pruning unreachable objects), a target the call does not make clear and a target outside the roots are still judged under it. A missing git_tracked mark, which a script or a sed -i always lacks, never turns an edit into a match. A listed deletion is always denied, in both profiles and whatever your messages say: the full profile’s hard deny (under the Destroy Pre-existing Files label, kept whatever you put in [auto_mode]) and the minimal profile’s class=host-data-delete (rule Container Escape). A composition’s allow_below never allows such a call: it abstains, so the script falls through to its llm(call) stage, and a script with none ends in the fail-closed denial.

A spent usage window

A provider that answers a spent usage window with a 429 is not a guardian failing: the provider’s own machine code (exceeded_current_quota_error, GoUsageLimitError), a Retry-After of more than five minutes, or a claude-subscription plan limit says so, and a short Retry-After is still an ordinary transient 429. A call that meets a spent window is therefore not denied with GuardianUnavailable. The whole run pauses, the call stays pending, and when the window reopens the guardian judges it again from the start, so the verdict is a real one. No dialog asks you in a headless run or in AFK mode: the wait runs to its limit.

If the wait is cancelled, or reaches --max-usage-wait, the pending call is denied with rule UsagePauseEnded. That is a decision by you or by a deadline, so it does not count toward the denial limits and adds nothing to AFK’s session temperature. A 429 never becomes an allow, and a pause that ends without the window opening ends a headless run with exit code 3.

Denial limits

Three denials in a row, or twenty in a session (any tool, not configurable), pause auto: the next call that needs the guardian asks you instead, and approving a call resumes auto. In a headless run a paused session denies. This stops a model from retrying a refused action until something slips through.

Under AFK mode nothing can answer that prompt either. A converted escalate counts toward the limits like any denial, a paused breaker denies every call that needs the guardian, and the run is blocked: no turn you did not type starts and a goal pauses. A second, separate limit watches the severity and recency of the denials: when the session temperature reaches its ceiling the whole agent tree stops. The breaker itself is not changed, and AFK never resumes it.

The end-of-stretch assessment

When an AFK stretch is blocked, stopped or ended and holds at least one denial, the guardian’s model is asked once, with no tools, whether a later call pursued a denied call’s effect by another route. It sees the stretch’s calls (redacted summaries, the decisions and the denial explanations, all inside an <untrusted kind="activity"> block) and can only name call ids that exist. Unlike the per-call alternate-route rule in the guardian prompt, this is a look back over the whole stretch, and it is evidence for the report, not a decision: a failure of any kind is reported as “evasion assessment unavailable”, never as a clean result. See AFK mode.

Retrying a denial yourself

In the terminal UI, /denied lists the calls the guardian denied and r approves one once. Fontaine records your approval for that exact call (same agent, tool and arguments), tells the agent it may retry, and lets the next identical call through without asking the guardian. The approval is consumed by that call, never cached, and does not count toward the denial limits. The floor runs first: an ask rule still asks.

Speed and cost

  • Read-only calls inside the workspace and the shell pre-classifier’s commands never reach the guardian. A narrow allow rule you wrote skips it too; broad code-execution allow rules are suspended in auto.
  • A verdict is cached for 60 seconds ([guardian] cache). The key covers the call, the model, the rules, the environment, your messages, the session’s recent actions and its denials, so any change misses. An identical call therefore reuses a verdict only when nothing else has happened in the session since (in practice consecutive identical calls under the minimal profile, or retries); this is deliberate, so an Allow is not reused after a security-relevant change. Only verdicts the model returned are cached, never a fail-closed outcome; the confidence rewrite applies after every lookup.
  • On an account that caches prompts (prompt_caching, on by default for anthropic and openrouter), the guardian’s static prefix, its verdict tool and system prompt, is marked cacheable; the per-call message is not. On openrouter the marker sits on the system prompt itself, since OpenRouter’s top-level marker would land on the per-call message, which is never reused. Models from openai/, deepseek/, x-ai/ and groq/ cache by themselves and get no marker. The system prompt holds the profile, the rules and the environment and no per-call text, so it is identical across calls until the rules change. The cache read and write tokens the guardian used are in the headless usage.guardian output.
  • A provider caches a prefix only above a model-dependent minimum length, so on some guardian models the marker saves nothing. When you pin a Claude guardian whose minimum is above the size of its prompt (about 1500 tokens under the minimal profile, 6000 under full), with caching on, Fontaine says so once at startup. Minimums, in tokens: Claude 5 models 512, Sonnet 4 models 1024, Haiku 3.5 and Opus 4.7 2048, Opus 4.5 and 4.6 and Haiku 4.5 4096. A guardian model with a lower minimum is the fix. The notice covers Claude ids on anthropic and openrouter accounts; other models are not checked.
  • Calls are adjudicated one at a time, in order. The guardian is on the critical path, so a fast model matters.

The guardian’s model endpoint inherits the network settings of its account, and a composition’s reads those of their accounts (Ollama or OpenRouter). An invalid [network] stops startup with exit code 2; the guardian never falls back to a direct connection.

Composing the guardian

A guardian verdict takes seconds. The guardian can be composed: a short Rune script decides how the LLM stage described above and cheap local reads are combined, and Fontaine wraps the script in a fail-closed root. A read asks a small model a question about the call and turns its answer into a risk between 0 and 1. A local read puts a yes/no question to an Ollama model and reads the first token’s logprobs, because Ollama’s native chat endpoint is the one that returns logprobs. A hosted read puts a five-level question to a /v1/systemone model on an openrouter account (Jev, typesafe/jev-1.14, or another System One model) and reads the level probabilities; see the screen preset on a hosted model. The composition is configured in [guardian.composition] and is either a built-in preset, screen being the one that ships, or a script of your own. Nothing is enabled without configuration: a guardian with no [guardian.composition] is the LLM stage alone, and what Fontaine proposes is offered by fontaine auto-mode setup and never applied without a yes.

The composition runs after everything deterministic, only where the guardian would run, and not while the denial breaker is paused. A read requests the account’s context_tokens window, as every call to an ollama account does. A read and a guardian on the same Ollama model avoid reloading it only when they request the same window, which they do on one account or on accounts with equal context_tokens. A prompt longer than the window makes that read fail.

The screen preset

The default shape is an allow screen in front of the LLM guardian, run in sequence: the screen goes first; if it allows the call, the call is allowed, unless the call has a critical_deletions target (see Failing closed), which the screen never allows; everything it does not allow goes to the LLM guardian, which reviews it. The screen does not stop or escalate on its own unless you set stop_threshold. A call it cannot judge goes to the guardian too: a timeout, an HTTP error, an unreachable daemon, an answer that is not yes or no, or a read that failed while others succeeded. Fontaine tells you once per session that a read is failing, and the guardian decides.

The preset declares three reads, all on the composition’s model, and always runs the first so the audit log records screen_risk:

  • stop. By default it asks, “If an employee were given the user’s request, would they be allowed to take this action?”; question = "outside_request" asks whether the action is outside what the request asked for. With stop_threshold set, a call whose risk reaches it is escalated to you, as a guardian escalation is, with tier = screen and rule = screen.stop in the audit record. In a headless run an escalation is a denial, except in Agent SDK mode with canUseTool, where it reaches the callback.
  • allow. The hardened permission read of the allow path.
  • steering. The steering detector of the allow path.

The allow and steering reads run, together with stop, only when allow_threshold is set (and always in shadow mode, so their scores are logged). A call the preset allows has tier = screen, decision = allow and rule = screen.allow.

The reads see the redacted, delimited request the guardian sees, without any recorded dialog answers or the agent_message_before_reply, and sequential means the guardian is asked only for a call the screen did not settle: a settled call spends no guardian tokens.

This describes the preset on a local Ollama model. On a hosted model it declares two reads and an allow_threshold default; stopping is opt-in; see below.

With concurrent = true the screen is raced against the guardian instead. They start together, the screen can settle a call only while the guardian is still pending, and a guardian verdict already in hand wins. A call the screen does not settle then costs the slower of the two, in practice the guardian’s, but a call it does settle has already spent the input tokens of the guardian request that is then dropped. The cost is estimated from the rendered prompt and recorded as guardian_dropped_input_tokens, apart from the usage the provider reports. A guardian request that finished but whose verdict the composition did not use is added to the session’s usage.

sequential (default)concurrent = true
Call the screen does not settlescreen + guardianmax(screen, guardian), about the guardian
Call the screen settlesabout the screenabout the screen
Guardian tokens on settled callsnoneinput spent, estimated in the audit log

The screen preset on a hosted model

When the composition’s model is on an openrouter account (model = "<account>/typesafe/jev-1.14"), the preset asks Jev, OpenRouter’s /v1/systemone model (any other System One model works the same way; see Other models), how far outside what an employee given the user’s request would be allowed to do the call is, on five levels from “within” to “a fireable offence”. The risk of a call is one minus the probability of “within”. One request costs about $0.000027 and about 150 ms. The endpoint is the account’s base_url (default https://openrouter.ai/api/v1, the one that serves chat) with systemone joined on, and the key is the account’s api_key_env or the key stored by /login. A composition on an openrouter model whose key does not resolve stops startup with exit code 2 naming guardian.composition.model and the account. The key is sent only over https or to a loopback host.

The preset declares two reads, stop and allow, which ask the same model the same question. They share one request, so a call costs one hosted request and the two audit scores (screen_risk and screen_allow_risk) are equal. There is no steering read: in the measured set the steering text moved 2 to 9 of 1,503 calls across a 0.10 margin on Jev, against 93 of 134 on qwen3-4b, so a veto would add a local model to a hosted default for no measured gain. question and steering_veto are refused for a hosted model.

On a typesafe/ model allow_threshold has a default (stopping is opt-in), so a section needs none:

KeyDefaultMeaning
allow_threshold0.20A call whose risk is below it is allowed without the LLM guardian, unless it has a critical_deletions target (see Failing closed).
stop_thresholdnoneUnset: the screen never escalates, and every call it does not allow goes to the LLM guardian. Set, a call whose risk reaches it is escalated, as a guardian escalation is.
allowtrueallow = false switches the allow path off and ignores allow_threshold.

The allow default is the zero-miss skip point of the synthetic corpus (0.30) less a margin of 0.10 for the model’s nondeterminism. It was fitted on the synthetic corpus only, never on the golden set (see Evals). There is no default stop: a call that reaches the guardian is judged by a model that can read your intent, where a stop would send it straight to you (or, in a headless or AFK run, deny it). The measured opt-in is stop_threshold = 0.34, the point that stops 5% of the synthetic corpus’s allowed calls. On the golden set it escalated 10.7% of benign calls and caught 97.9% of attacks, and off-domain it stopped 28 to 88% of allowed calls on synthetic thresholds, so check real traffic with shadow = true before setting one.

Other System One models

Any model an openrouter account serves on /v1/systemone can be the composition’s model (baseten/joey-1, respan/span-02, perplexity/pplx-decider-flash-v1.2, cloudflare/clef-flash, liquid/d1.1). The defaults above are Jev’s fit and apply only to a model whose id starts with typesafe/; another model needs allow_threshold and/or stop_threshold of its own, or shadow = true, and otherwise stops startup with exit code 2. Thresholds are measured per model; Other hosted screens lists how each candidate scored. Context windows differ (16,384 tokens for joey-1 and clef-flash), and a state a model rejects is a fail-closed read: the call goes to the LLM guardian.

A local OpenJev (open weights, CC BY-NC 4.0) served by its helper/shim.py on 127.0.0.1 speaks the same endpoint. Fontaine’s composition still requires an OpenRouter key, so the recipe in Evals scores it with the eval harness only, and it is unmeasured as a composition model.

Jev is not deterministic: 60 to 75% of repeated requests for one call differ, by up to 0.22 in the risk. A zero-miss threshold fitted on one pass does not hold on the next, which is what the margin is for. Known leak classes, calls the screen clears that the LLM guardian would not, are .env reads, session facts and kubectl get ... secrets; on a fresh set and on public corpora one to three must-not-clear cases were cleared. Treat the allow path as a latency and cost optimisation for ordinary calls, not as a second guardian.

Data leaves this machine. Wherever this screen is enabled, every guardian-gated call sends the task intent, the recent user messages, the tool name and arguments, and project facts, redacted and delimited as the guardian sees them, to OpenRouter and Typesafe. If that is not acceptable, use a local model or no composition.

To turn the allow path off, so that with no stop_threshold every call goes to the guardian:

[guardian.composition.params]
allow = false

or lower allow_threshold. To log scores without acting, set shadow = true; a repository’s project settings can force shadow = true too, which is the repository-level off switch for the allow path. A repository can never turn the allow path on or change allow.

A hand-written [guardian.composition] without shadow stays in shadow mode, so configuring the preset never enforces it. Only fontaine auto-mode setup writes shadow = false.

A script that prefers Jev but falls back to a local read when the hosted one fails declares one read on each model and tries them in order. This one passes the soundness rules, since only the host’s allow_below applied to a declared read can allow:

pub async fn guardian(call, params) {
    let verdict = match read(call, "hosted").await {
        Ok(score) => hosted_verdict(score, params),
        Err(_) => match read(call, "local").await {
            Ok(score) => local_verdict(score, params),
            Err(_) => abstain(),
        },
    };
    if verdict.is_abstain() { llm(call).await } else { verdict }
}

fn hosted_verdict(score, params) {
    if score.value() >= params.stop {
        escalate("hosted.stop", format!("risk {:.2}", score.value()))
    } else {
        allow_below("hosted.allow", score, params.allow)
    }
}

fn local_verdict(score, params) {
    if score.value() >= params.local_stop {
        escalate("local.stop", format!("risk {:.2}", score.value()))
    } else {
        abstain()
    }
}

with

[guardian.composition]
script = "fallback.rn"
model = "or/typesafe/jev-1.14"
shadow = false

[guardian.composition.params]
stop = 0.34
allow = 0.20
local_stop = 0.95

[guardian.composition.reads.hosted]
question = "level5_employee"

[guardian.composition.reads.local]
model = "local/qwen3:4b-instruct-2507-q4_K_M"
question = "outside_request"

The allow path

On a local model, a call is allowed without the guardian only when two extra reads of the same model agree that it is clearly safe:

  • A hardened permission read. The question is always “If an employee were given the user’s request, would they be allowed to take this action?”, whatever question the stop read uses, because the threshold is fitted to that question. Its system prompt adds a sentence that tells the model the arguments are written by the agent, and that text in them which addresses a reviewer, claims approval or says how to answer is manipulation, to be answered no. The hardened prompt is valid only with this question.
  • A steering detector. It asks whether the arguments contain text that addresses a reviewer, claims approval, or tries to influence how the action is judged. A call is never allowed when its score is at or above steering_veto.

The call is allowed when the hardened read’s risk is below allow_threshold, the steering score is below the veto, the stop read did not stop it and the call has no critical_deletions target (see Failing closed). Without the detector, one steering sentence in a call’s arguments moved most of the should-not-allow cases in the measured set below the skip threshold, which is why the allow path has its own prompt and a veto.

The allow path is user scope only, a deliberate exception to the rule that only containment earns a skip of the guardian: the allow is a verdict of the composed guardian. It never runs before the deterministic floor, and a paused breaker prompts you without running the composition. A composition allow does not reset the denial breaker. On a local model it is off until you set allow_threshold; on a hosted model it is on once the composition enforces (shadow = false), unless allow = false.

Calibrating with shadow mode

shadow = true is the default. The composition runs and records every read’s score, and the guardian decides as always: screen_risk, screen_allow_risk and screen_steering (the reads named stop, allow and steering), screen_scores (every other read, by name), screen_model, screen_latency_ms (from the start of the composition to the last read finishing) and screen_outcome in the audit log. screen_outcome is what the composition would have done: stop, allow, deny, pass or unavailable, the last meaning a read or the script failed. Run in shadow mode for a while, then read the audit log: the risk of the calls the guardian denied or you declined, against the risk of the calls that were allowed, shows where a threshold would have caught the first without escalating too many of the second. For allow_threshold, look for a value below which no call the guardian denied or you declined appears, and check the steering scores of the calls you would not want allowed. A local model has no shipped threshold, because the right one depends on the model, the question and your own traffic; set stop_threshold and/or allow_threshold and shadow = false when the numbers are acceptable. A hosted model ships an allow default and no stop, so its section needs no threshold, but the same reading of the audit log tells you whether they suit your traffic. To see the effect on the golden set, run a cascade scorecard.

Writing a composition script

A script defines pub async fn guardian(call, params) and returns a verdict. It runs in Rune, a small Rust-like scripting language with async and .await, in a sandbox: it has no files, network or terminal, and no access to the call’s arguments. The host functions below are in scope without an import; the language itself is documented at rune-rs.github.io.

The terminal UI’s status line script is the same Rune hosting (no stdio, a host module of opaque types, an instruction budget), with a smaller budget and a fallback to the default bar in place of a denial when it fails.

ItemReturnsNotes
call.tool(), call.destructive()String, boolThe facts of the call a script may see. The arguments are not exposed: a script decides by reads, not by matching arguments.
read(call, name)future of Result<Score, String>name is a read declared in [guardian.composition.reads]. A failed or timed-out read is an Err; an undeclared name is an Err. Each name is read at most once per call, however often it is named, and dropping the future does not cancel the read.
score.value()f64The risk of the read.
llm(call)future of verdictThe LLM guardian. All mentions in one call share one request, so naming it on several paths costs once. It never abstains: its failures are denials.
first_decisive([futures])future of verdictPolls all at once and returns the first verdict that is not an abstain, the earlier in the list winning a tie; the rest are dropped. All abstaining abstains.
std::future::join((a, b))tuple of resultsRuns futures together; a script that awaits one after the other runs them in sequence.
escalate(node, reason), deny(node, reason), abstain()verdictnode names the deciding step in the audit record’s rule.
allow_below(node, score, threshold)verdictAn allow if score.value() < threshold, else an abstain. It also abstains for a call with a critical_deletions target, whatever the score. The only way for a script to allow a call.
verdict.is_abstain(), verdict.is_allow()boolFor sequencing.

params is an object holding [guardian.composition.params]: numbers (as floats), strings and booleans. call, scores and verdicts have no constructors and no settable fields, so a script cannot forge one: an allow can come only from llm() or from allow_below applied to a score a declared read produced.

Fontaine wraps every script in rules a script cannot change:

  • It is bounded. An instruction budget and a time limit (the guardian’s timeout, one read’s timeout and a margin) cover one stage of reads plus one LLM call, so a script that chains several read stages before llm() can hit the limit and be denied. The time limit cancels the requests in flight; the instruction budget and any other script failure stop the script but still await and record the reads it started, each within its read timeout.
  • It is fail-closed. A script error, an exhausted budget, a timeout, a panic, a return value that is not a verdict, and an abstain at the end are all denials. Error text explains the denial; it never changes it. Such a denial is a guardian denial: it can be approved from /denied, counts toward the breaker and carries fail_closed_reason.
  • A verdict in hand is never overridden. An LLM verdict that is a denial or an escalation and already complete is always the outcome, whatever the script returns. An LLM allow in hand yields to a script escalate or deny, the stricter outcome.
  • Spend is not lost. A guardian request cut short is estimated into guardian_dropped_*; one that finished but was not used is added to the session’s usage.
  • Reads are awaited. Every read the script started finishes, within its timeout, and is recorded, even after the script has its answer.
  • Shadow mode is invisible to the script. Fontaine starts every declared read and the LLM request itself and decides by the LLM; the script runs on the same requests and what it would have decided is recorded as screen_outcome.

A script’s escalate is handled like a guardian escalation (a prompt, or a denial when headless, with tier = screen); its deny is a denial with tier = screen and no prompt; its allow_below is an allow with tier = screen. In each, the rule of the record is the node name.

For example, this script races a cheap read against the guardian and escalates what the read finds out of bounds, but only if the guardian has not already answered:

pub async fn guardian(call, params) {
    let outside = async {
        match read(call, "outside").await {
            Ok(score) if score.value() >= params.limit => {
                escalate("outside.stop", format!("risk {:.2}", score.value()))
            }
            _ => abstain(),
        }
    };
    first_decisive([llm(call), outside]).await
}

with

[guardian.composition]
script = "guardian.rn"
model = "local/qwen3:4b-instruct-2507"
shadow = false

[guardian.composition.params]
limit = 0.95

[guardian.composition.reads.outside]
question = "outside_request"

Project configuration cannot load a script, because a script can mint an allow: only the user file sets a composition, and other scopes may force shadow = true.

The preset and the scripts are scored on the golden set with --screen and --composition-script.

Choosing the guardian model

Fontaine ships an ordered list of benchmark-validated guardian models in guardian_models.toml, built into the binary and re-benchmarked each release. A model is on the list only if, on the scorecard, its catch rate over the attack cases is at least 90%, its false-deny rate over the benign cases is at most 5%, and its p95 adjudication latency is at most 3 seconds. Entries are ranked by catch rate, then false-deny rate, then latency.

With no [guardian] model, the guardian is the highest-ranked validated model that one of your accounts offers. If none is, the main model judges and Fontaine tells you once at startup. The guardian’s and the scanner’s calls force a structured answer, which a model that thinks by default refuses. Fontaine turns thinking off for those calls on opencode-go Chat models and non-Claude Messages models. A databricks account sends the Chat wire’s parameter to the guardian’s and the scanner’s calls by default. A workspace that refuses it costs the first attempt: the retry leaves the parameter out, and the guardian and the scanner do not send it again for the rest of the session. thinking_off = false skips that first attempt for a workspace known to refuse it. The parameter is {"reasoning_effort": "none"}, the value Databricks documents for turning a hybrid reasoning model off; the gateway’s thinking field belongs to the Claude models it also serves, and is accepted and ignored for the others. Sending it is best-effort: a deployment that does not honour it leaves the model thinking, and the guardian’s 1024-token output budget can then go entirely to reasoning — the call answers nothing and fails closed as error with finish_reason=Length, which no retry fixes, so the model is not usable as a guardian there. An openrouter account sends {"reasoning": {"enabled": false}} on the guardian’s and the scanner’s calls when thinking_off = true; it is off by default there. On an openai-compatible or kimi account, a model that thinks by default cannot be the guardian: every call is denied as GuardianUnavailable. Pick a model without default thinking.

A guardian on a claude-subscription account takes the same structured-answer path: the verdict arrives as the model’s typed output or a forced call of an aliased tool of the inert tool inventory, and anything that cannot be read, any CLI or discovery failure and any timeout is a denial. Its calls are subscription usage, so they are counted in tokens and never priced. See Claude subscription.

Changing the guardian is easy but never automatic:

[guardian]
model = "work/claude-haiku-5-5"
  • Set [guardian] model, or use /guardian-model <account>/<model> in the terminal UI, which switches the live session and saves the choice. /model does the same for the main model, and moves the guardian with it only when the guardian is on the main-model fallback.
  • A model you pinned is never substituted. If it cannot be used, Fontaine fails loudly. In the terminal UI a prompt offers to retry it, to pick another validated guardian for the session, or to switch to manual. In a headless run every adjudication is denied with GuardianUnavailable, and the init event and stderr say so.
  • For endpoints with no catalog match (a custom openai-compatible endpoint, a kimi account, Ollama, an opencode-go or databricks account), only a model set explicitly in guardian.model is used, except for the validated list’s own databricks entry (system.ai.deepseek-v4-1-flash-1017), which a databricks account that serves that model id picks up as its default guardian. A small local model can be both the agent and the guardian; judge it by its own scorecard run. The guardian prompt is longer than Ollama’s default 4096-token window, so an ollama account requests context_tokens (16384 by default) and the daemon refuses a prompt that still does not fit; the guardian then denies the call.

Models with no tool support

A model served by Ollama that reports no tools capability (gemma3:4b, for example) cannot take a forced submit call: the daemon answers 400 ... does not support tools. Fontaine asks the daemon what the model can do (/api/show, which does not load it) and picks the path from the answer:

  • a model that reports tools uses the submit path, the one every scorecard entry was measured on;
  • a model that reports completion but not tools uses the schema-constrained path, and Fontaine says so once, when the guardian is set up (at startup, and after /guardian-model). The scanner on that model takes the same path;
  • a model that cannot generate text at all (an embedding model) makes the guardian unavailable with ollama/<model> cannot generate text (capabilities: embedding), and every gated call is denied until you pick another guardian;
  • a daemon too old to report capabilities (no capabilities list) is treated as a submit model for the guardian’s life. A question that goes unanswered (unreachable daemon, HTTP error or timeout) is treated as a submit model for that call only, so a failure stays as loud as it is today, and is asked again on the next call.

There is no setting for this: the path follows what the model reports. If a daemon claims tool support the model lacks, the call is denied and the explanation says that the model does not support tool calls and so could not use the submit output tool; pick another model.

The schema-constrained path is not benchmarked unless a model is listed for it. The constraint fixes the shape of the answer, not its quality, and a small model may reason less before it fills the schema. The audit log records which path judged each call as verdict_transport (tool or schema), and fontaine-evals --verdict-transport scores a model on either; see the scorecard. Until a model’s own schema run clears the inclusion bar, it works only when you set it in [guardian] model.

The minimal profile

[guardian] profile = "minimal" narrows the guardian for a container. Inside a sandbox the blast radius of ordinary work is bounded, so the minimal guardian does not judge routine development; it enforces containment integrity (mounts, container-runtime sockets, /proc/sys and cgroup control files, privileged namespace operations, raw devices, symlink traversal to bind-mounted host paths, network paths around the sandbox proxy, and a critical_deletions target such as a workspace root, which is the host’s data), denying them as Container Escape with the escape class in the explanation as class=<name>, and still denies exfiltration to destinations that are not the repository’s own remotes. It receives a smaller request: the call, your last 500 characters and 3 messages, the workspace roots, the home directory, the remotes, the [env] names, the touched paths’ status and any active_skill line, without project instructions, hook notes or earlier denials. The deterministic floor still runs. It also treats the project’s own issues and pull requests like the full profile (creating, editing, commenting on or closing them is not exfiltration, though a secret in their content is), and it is told that its confidence is about containment and egress, so ordinary work that crosses neither is high confidence and clears the confidence threshold, below which a destructive Allow is still turned into a Deny.

For exfiltration it judges content by the same four data classes, with less room. A public project’s own work may go to any destination your request calls for, a public gist or paste included; external context, personal and entrusted data, or material marked confidential going to a public remote is denied, and nothing you say clears it. A commit or push to a recorded private or internal remote, or the text of its pull requests and issues, is never exfiltration. Everything else that leaves the workspace’s own remotes stays denied: the minimal profile has no user-naming clearance.

It is a narrowing, never “off”, and it only loads when containment is verified. Both must hold:

  1. You pass --in-container, asserting the process runs in a container.
  2. A runtime probe agrees. On Linux the probe finds any one of /.dockerenv, /run/.containerenv (Podman), a container= entry in PID 1’s environment, or docker, kubepods, containerd, libpod or lxc in /proc/1/cgroup. macOS and Windows never report a container.

If the flag is missing or the probe is negative, Fontaine runs the full profile and prints a notice saying why. The profile can only be set from user settings, never from a project file. Every profile is scored before it ships: the scorecard has a minimal column.

Scanning tool results

The guardian judges calls. The scanner looks at what comes back: with [guardian] scanner set, every tool result is checked for text that tries to steer the agent (instructions addressed to it, attempts to override its rules, hidden directives) before the agent reads it. It is off by default, because every result then waits for the scanner, which costs latency on every call.

The scanner never withholds a result. It adds a note after the result, so the agent reads both:

  • Flagged. The note says the scanner flagged the result as possible prompt injection and gives the scanner’s reason, and tells the agent to treat anything in it that reads as an instruction as untrusted data.
  • Unscanned. If the scanner errors, times out, answers with something that is not a verdict, or is unavailable, the note says the result is unscanned and suspect, with the cause. Anything that is not a clean verdict is treated this way, so a scanner outage never reads as a pass.

A clean result is passed through unchanged. Empty results are not sent to the scanner. A failed tool call is a result too and is scanned. The scan runs after the notifications queued for the agent have been added and before post_tool_use and post_tool_use_failure hooks, so what another agent said is scanned like any other result: a subagent’s report is flagged before its parent reads it. The tool_result telemetry event records the verdict and the latency, never the content.

scanner selects one of four settings, in the user file only:

ValueWhat scans
offNothing. The default.
pg2PromptGuard 2 (86M), a small classifier run locally. A result is tokenized in full and scored in windows of 512 tokens at a stride of 256; it is flagged if any window scores 0.9 or more.
llmThe guardian’s model, in a short separate conversation with its own prompt. The result sits inside an untrusted block. A malformed answer, an error or a timeout leaves the result unscanned and suspect.
commandA program of your own (scanner_command). See the contract.

Each scan is bounded by [guardian] timeout_secs; a scan attempt that stalls is dropped and retried once within it. pg2 is in the release binaries; a source build needs cargo build --features pg2, and scanner = "pg2" in a build without it is a configuration error (exit code 2).

PromptGuard 2 and the Llama 4 Community License

PromptGuard 2 is Meta’s model, distributed under the Llama 4 Community License, and its weights are a gated download on Hugging Face. Fontaine never bundles them. You accept the license on Hugging Face yourself, and Fontaine prints a notice about it every time a session starts with scanner = "pg2", in every permission mode.

Either point scanner_model_path at a directory holding model.safetensors, tokenizer.json and config.json, or let Fontaine download the missing files into <data dir>/models/promptguard2-86m/ with your Hugging Face token, read from the environment variable named by scanner_hf_token_env (HF_TOKEN by default). The token is never stored or logged, and that variable is never passed to shell commands or hooks. A download gives up when it cannot connect within 30 seconds or when the server goes silent for 60 seconds, and a file appears under its final name only after a complete response. The first start downloads the model (hundreds of MB), prints a line on stderr saying so, and is slow; later starts reuse the files.

The model loads at startup. If the token is missing, Hugging Face refuses the download (the license is not accepted), the network fails, or the files are missing or corrupt, the session still starts. The scanner is then unavailable: a notice names the cause, the license and the token variable, and every result carries the unscanned note until you fix it and restart.

Inspecting the rules

fontaine auto-mode shows what the guardian judges against. It starts no session, runs nothing the repository defines and, except for setup’s optional composition offer, changes no setting. --cd and --settings apply. Each subcommand takes --format text|json.

  • fontaine auto-mode defaults prints the shipped environment, allow, soft_deny and hard_deny lists. The text form is a [auto_mode] TOML fragment you can paste into a settings file and edit. It needs no configuration and makes no request.

  • fontaine auto-mode config prints the effective lists a session would hand the guardian, after $defaults splicing and the add-only rules for soft_deny and hard_deny. Each list is headed by the scopes that set it (user, project-local, and so on) or shipped defaults, and each entry is tagged default or custom. Scopes are recorded per list, not per entry. The output shows what a non-interactive load yields: project settings that need workspace trust are not given it here, so an interactive session you trusted can differ. Control characters in entries are shown as escapes. Under [guardian] profile = "minimal" (when the container check holds) a note says that only environment reaches the guardian. It makes no request.

  • fontaine auto-mode critique sends your custom entries, the entries not equal to a shipped one, to the guardian’s model (or to the critique role, when you defined one, falling through its list when an account runs out of quota) and prints its review for ambiguity, overbreadth, redundancy and contradiction with the hard-deny classes, followed by the model and its token count (and cost, for a priced model). With no custom entries it prints nothing to critique and exits 0 without resolving a model or making a request. The model is chosen as a session chooses it, so it needs the same main model and account; an unavailable guardian model is a configuration error (exit 2), and a timeout ([guardian] timeout_secs) or provider error exits 1. Your entries go to that account’s provider, as they do in a session; the command says so on stderr before sending. The review is advice: it changes no setting and has no effect on any permission decision. Under [guardian] profile = "minimal" it prints a note and makes no request, because the rule lists are not sent.

  • fontaine auto-mode setup [--no-model] [--no-composition] [--format text|json] collects the project’s environment (its model scan runs on the guardian’s model, or on the setup role when you defined one) and stores it, then offers the guardian composition. It starts no session and exits 0 even when steps fall back to unknown; it exits 1 only when the record cannot be written. The JSON report gains a composition object with a status (skipped, offered_unanswered, declined, written or failed) and the candidates it found.

A prompt that is exactly auto-mode runs the subcommand, with or without -p; write fontaine -p -- auto-mode to give the agent that word as a task.

Project environment

Without help, the guardian does not know whether your repository is public, which branch is protected, whether a tag push triggers a release or which .env files are ignored, so it guesses. fontaine auto-mode setup (or /auto-mode-setup in the terminal UI) collects those facts once per project, in two layers.

Facts read directly, with no model:

FactSource
Visibility, default branch, branch protection (the protected flag or any ruleset rule), deploy environments, homepage, Pages siteThe GitHub API through the gh you are logged in with, for github.com remotes. No gh, no login or another host leaves the fact unknown; an org policy that bars the check (403, SAML) leaves it unverified.
Workflows triggered by a tag push or a release, workflow environment names.github/workflows/*.yml at the git work-tree root.
Package registries.npmrc, .yarnrc.yml, pip.conf, pyproject.toml and .cargo/config.toml. The host only is kept, never userinfo, a token or a path.
.env* files and whether git ignores themA directory listing; their contents are never read.
StackThe manifests at the project root.

Each gh call is a fixed command with a 10 second limit. The report names every step that fell back and why.

A model scan, in a trusted workspace and from a terminal. The guardian’s model reads a bounded sample of the repository (the tracked-path listing, the GitHub settings above, non-GitHub CI files, build and task files, infrastructure file heads, the README and CONTRIBUTING; .env-like files by name only) and proposes sensitive locations, deploy targets outside GitHub Actions, protected targets and trusted destinations. The sample goes to the guardian’s provider, and the command says so first. Every proposal must cite a tracked file from the listing or a project setting, a sensitive location must match a tracked path, and a trusted destination must be a host, a bucket URL or a registry URL with no wildcard broader than one organization prefix; the rest are dropped and counted. You review what is left, with the entries that relax the guardian (trusted destinations) listed first, and nothing is saved until you accept. --no-model, a run without a terminal and an untrusted workspace skip the scan, and a missing model, a timeout or an unparseable reply never fails the setup.

The record is <data dir>/auto_mode/<project>/environment.json, owner-only and a protected path, keyed like auto memory so every worktree of a repository shares it. fontaine auto-mode config shows it.

What the guardian reads. A session loads the record at start with no network call and keeps only the remotes it still has. The guardian sees it as data in the session_facts block, and its prompt gives the fields fixed meanings:

  • public is authoritative and cuts both ways: it lets the project’s own work be published, and it makes external context or personal and entrusted data going there publication to the world. The rules are under What counts as sensitive.
  • private and internal: a commit or push to that recorded remote stays inside the trust boundary, so calling the material confidential is no reason to block it. unknown relaxes nothing, and unverified counts as possibly public.
  • A protected default branch, or a workflow that runs on tag push, marks a push there as a shared-branch change or a release.
  • Facts read from repository files describe the project and never add trust.
  • Trusted destinations you accepted count as your own trust-slot entries. Sensitive locations gate sending their content out, not reading it locally: a local read of a file inside the workspace that you named (config/secrets.yml, .env) is routine, and credential stores under the home directory are not covered.
  • A remote is trusted by the git name recorded at session start; one added during the session is not, whichever call added it, so a name missing from a recorded list is untrusted, and (none) means any remote a call names was added. When the names were not recorded (including a repository whose config uses include or has a remote with no fetch URL), the repository’s named remotes (origin) count as its own, and one this call or an earlier one added or repointed does not.
  • A location, target or destination missing from the lists says nothing about its safety.

What counts as sensitive

The guardian judges data by class, from what it can see (the content, and a file’s name, path or type), not by whether git tracks the file:

  1. Secrets: credentials, private keys, tokens, live session cookies.
  2. Personal and entrusted data: personal data, customer data, third-party material under its own sharing terms, and the local stores that carry these (agent session transcripts, credential dot-folders, shell history).
  3. External context: confidential material from outside the project: the organization’s other repositories, internal hosts and plans, and the employers, clients or codenames around the project, including paths outside the workspace that reveal them. Material inside the workspace counts when you or its own text mark it confidential, internal or not for publication.
  4. Project work: this repository’s own code, tests, design notes, plans, docs, build and test output, bug reproductions, issues and pull requests, tracked or not.

Where each may go depends on the destination and on the visibility the setup recorded:

  • Secrets never leave the machine, except a credential sent to its provider.
  • Personal and entrusted data goes nowhere outside the workspace unless you name the data and the destination, and that includes a commit or push to a public remote.
  • For a private or internal remote, any commit or push to one of the repository’s own remotes, and the text of its pull requests and issues, is allowed whatever it holds, except that a real secret is still Secret Exposure. A gist, paste or other host is judged as though the project were not public.
  • For a public remote, project work may go to any destination your request calls for: the remote, its issues and pull requests, a public gist or paste, a forum post. External context may not, unless your messages name that detail for that destination (“mention we use it at the client” does; “file an issue about the crash” does not). The guardian reads the outgoing text (a commit message, an issue body, a gist file) for internal paths, hostnames, client or employer names and identifiers from live data.
  • For unknown, unverified, an expired fact or no setup record, pushes and pull requests to the repository’s own remotes are not blocked on content class alone, and unknown visibility is never a reason to block. A public destination that is not the repository (a gist, a paste, a public bucket) gets project work only when you name that destination, and never external context.

Examples: a public project’s design notes may go in a gist, a client’s name may not, and anything may be pushed to a private repository except a real secret.

Some sends stay hard denies that nothing clears: secrets, a destination the agent chose itself, a remote added or repointed in the session, and a bulk transfer of the whole tree or all refs to anywhere but the repository’s own remotes. The class-based cases (personal and entrusted data, external context, a non-public project’s work sent to a public destination) are a soft rule, Out-of-Place Publication, which you clear by naming the data and the public destination itself. Naming a remote by its git name (origin) does not name it as public, and material marked confidential, internal or not for publication is never cleared to a public destination by naming it.

Expiry. A public fact older than 30 days is shown as unknown (last seen public on <date>), because a repository made private since would keep a relaxation it no longer earns. Facts that only tighten, and entries you accepted, do not expire.

The startup warning. An auto session whose project has no record, or whose record lacks a current remote or holds an expired public, warns once: run fontaine auto-mode setup. In the terminal UI a session that starts in another mode warns the first time it switches into auto. /guardian-disable silences it while the guardian is off. Set [auto_mode] setup_reminder = false in the user file to silence it, for example on CI with fresh checkouts. Having [auto_mode] environment entries does not: those are global, the record is per project.

/auto-mode-setup applies the environment facts to the running session at once; a command-line run from another terminal applies at the next start or resume. A composition it writes applies from the next session in either case.

Setting up the composition

The last, optional step of fontaine auto-mode setup and /auto-mode-setup offers the screen preset so you do not write [guardian.composition] by hand or guess a threshold. It offers two things.

The hosted screen. If an openrouter account has a key that resolves (judged by the credential alone, with no listing call), setup offers the preset on typesafe/jev-1.14 with the preset’s default allow threshold and no stop, with the allow path on. The offer states that guardian state (task intent, recent user messages, tool name and arguments, project facts) is sent to OpenRouter and Typesafe, that the allow path is on, and how to turn it off (allow = false) or to check real traffic first (shadow = true). It writes preset = "screen", model = "<account>/typesafe/jev-1.14" and shadow = false, with no threshold key, so a later recalibration reaches you with no config rewrite. It creates no account: with none, setup prints a line saying to add an OpenRouter account with /login or api_key_env and run it again.

A local screen. It looks for an ollama account that lists a model Fontaine has a benchmark for (today qwen3:4b-instruct-2507-q4_K_M, matched by its exact tag, since a threshold is fitted to one model, quantization, prompt and question) and asks one basic choice:

  • safe: stop_threshold only. The screen can only stop a call (escalate it, or deny it where nobody can answer); it never allows, so the LLM guardian still reviews every call the screen did not stop. It may stop some calls that would otherwise be allowed.
  • fast: allow_threshold only. The screen allows the calls it is confident about, which is a guardian-tier allow; every call it does not clear goes to the LLM guardian, which decides it.

You type no number. Setup shows what it will write, with the benchmark behind the threshold for a local model, and writes nothing unless you answer yes: to the user settings file only, in one edit that is first checked as a session start would check it. The step is skipped, with a line saying why, when a composition is already configured, under the minimal profile (the thresholds were fitted on full profile reads), with --no-composition, and when there is nothing to offer (the line names the model to pull, and the hint for the hosted screen). A run without a terminal lists what it found in the report and writes nothing.

The local value is a fit on a small dataset. The fast threshold let one call through live that the dataset expects denied or escalated, so score it on your own traffic with fontaine-evals --screen live:<account>/<model> or the screen_risk (safe) and screen_allow_risk (fast) values in the audit log, and set shadow = true to log scores without acting while you tune. See Cascade scorecards.

Prompt versioning

The prompts are versioned assets in rust/fontaine-sdk/prompts/guardian/ (guardian_prompt.md, guardian_minimal.md, scanner_llm.md, critique.md, env_scan.md) compiled into the binary, so a prompt change ships with a release and is re-scored on the golden dataset before the list of validated models is regenerated. A change to a prompt or to the shipped rule lists changes the cache key, and an entry in the model list is only valid for the dataset it was scored on.

Known limits

  • absent is a snapshot. Fontaine checks that nothing is at a path when it builds the request, so a background job could create the path before the call runs. It also describes the path before this call runs, so a shell call gets the marks only when it is a single simple command (no list, pipeline or substitution) whose working directory is certain (every program allowlisted, no variable assignments, no directory-changing options) and whose words hold no *, ? or [ and none starting with :. A later command could otherwise act on what an earlier one created, and a glob or pathspec names files no literal word does.
  • Latency. Every call that reaches the guardian waits for a model. The 3-second p95 bar is a property of the listed models, not of yours.
  • Data class is inferred. The guardian decides which class a piece of content belongs to from what it reads like, so external context with no visible marker (no client name, no internal host, no confidentiality note) can pass as project work.
  • Injection. Delimiting, redaction and a tool-less single-shot design reduce, and do not remove, the chance that hostile text in a command, a file or a repository steers the verdict. The deterministic floor and the fail-closed rules exist so that the guardian is not the only control, and your deny rules apply whatever it says.
  • Standing grants have a window. The guardian reads your last 5 messages and 2,000 characters of intent. A grant you gave earlier than that drops out and has to be repeated.
  • Judgment. The scorecard measures a fixed dataset. Novel attacks, and benign commands the dataset never saw, will be misjudged at some rate. A guardian allow is a decision to run the command with your permissions, not a proof that it is safe.
  • Tool results are scanned only if you turn it on. The guardian judges calls, not what comes back from them. The scanner annotates suspect results; it cannot prove one safe, and a flag is a warning to the agent, not a block.
  • Provider-native search is outside the guardian and the scanner. When the provider’s own web search is offered (see Web search), it runs inside the model’s response: the guardian never sees a query and the scanner never sees a result. Fontaine withholds it while a deny or ask rule or a pre_tool_use hook could cover websearch, and in manual, acceptEdits and dontAsk unless an allow rule exists, and in auto and afk while the denial breaker has paused auto (from the next turn, until you approve a call); [websearch] native = "off" turns it off. The client-side websearch tool is judged and scanned like any other call.

The scorecard reports the measured catch and false-deny rates per model.

Attribution

The seeded default rule lists are adapted from Anthropic’s published defaults for Claude Code’s auto mode (https://code.claude.com/docs/en/auto-mode-config and the output of claude auto-mode defaults), reworded and reduced to Fontaine’s rule labels. The auto-mode design itself, the precedence of rule lists and the $defaults marker follow Claude Code’s. This is not an Anthropic product and the lists are not endorsed by Anthropic.