@ian-pascoe/pi-guardian 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# Pi Guardian
+
+`@ian-pascoe/pi-guardian` gates a Pi agent's tool calls before they run. Routine calls run at once; risky ones go to a separate reviewer model, the Guardian, which judges the call's risk against the user's authorization. A fixed Decision Table turns that judgment into an allowed call or a binding Rejection.
+
+Requires Node `>=22.19.0` and Pi `>=0.99.0`.
+
+> **Guardian is a safety net, not a sandbox.** An allowed call runs with your full privileges, a reviewer model can be wrong or manipulated, and other extensions can still act on their own. Keep backups and review what agents do.
+
+## Install
+
+```bash
+pi install npm:@ian-pascoe/pi-guardian
+# or from this checkout
+pi -e ./packages/pi-guardian/src/index.ts
+```
+
+**Install Guardian last.** Pi runs `tool_call` handlers in extension load order, and an extension loaded after Guardian can rewrite a call's arguments after Guardian reviewed them. Guardian detects this after the call runs (see [Limitations](#limitations)).
+
+Guardian is **enabled by default** and reviews with the session's current model unless `model` is set. Without a usable model, every call that needs review is a Review Failure.
+
+**Choose a small, fast Guardian model with thinking off.** Every Reviewed Call waits for its review, and a large session model makes that slow and costly: in live use, Claude Opus took 6 to 17 s and about $0.27 per review, while `anthropic/claude-haiku-4-5` with `thinkingLevel: "off"` took about 1.4 s and $0.05. Set both in `/guardian` (Model, thinking level) or in settings, as in the [example](#settings). While `model` is unset, Guardian shows a one-time notice at session start, and `/guardian status` marks the model as inherited from the session.
+
+## How a call is judged
+
+Every `tool_call`, including calls a tool issues itself (such as a `codemode` script's calls, which carry `parentToolCallId`), resolves to one Tool Policy:
+
+1. the configured `tools.<name>` setting, if any;
+2. else the built-in default:
+   - `allow`: `read`, `grep`, `find`, `ls`, `codemode`, `tool_search`, `todo`, `web_search`, and Context Management's `context_notes`, `context_history`, and `context_rollover`, which only touch the session's own notes, journal, and handoff;
+   - `edit` and `write`: `allow`, unless the target is a **Sensitive Path** or the call shares its assistant message's tool batch with a call that is not allowed without review (Pi may run them in parallel, and that call could replace the target with a link first); either is reviewed;
+   - `bash`: `allow` only for a **Safe Command**, otherwise reviewed;
+   - `terminal_start`, `terminal_send`, and `powershell`: reviewed;
+3. else the tool's `readOnlyHint: true` annotation (as reported by `pi.getAllTools()`) allows it, unless it also declares `openWorldHint: true`;
+4. else the call is reviewed.
+
+`deny` blocks the call without a model call. `review` sends it to a Guardian Review. A nested call is judged by its own Tool Policy; the issuing call is shown to the Guardian as context only.
+
+While Guardian's settings cannot be read (invalid `guardian` settings or an unreadable session), every call except the built-in `read`, `grep`, `find`, and `ls` is a Review Failure: the unreadable settings may have held `deny` or `review` rules, so neither they nor the built-in defaults apply. The footer shows `guardian: settings error`, and the error is reported when the session starts and in each blocked call's reason.
+
+**Sensitive Paths** are judged after resolving `~`, `..`, `@`, `file://`, and symlinks (including dangling ones), on both the lexical and the resolved path:
+
+- anything outside the working directory, and **every** path when the working directory is the home directory, an ancestor of it, or `/`;
+- persistence and credential locations under the home directory wherever the workspace is: shell startup files (`.bashrc`, `.bash_profile`, `.profile`, `.zshrc`, `.zprofile`, `.zshenv`, and similar), `.ssh`, `.gnupg`, `.aws`, `.azure`, `.config` (including fish and systemd user units), `.local/bin`, `Library/LaunchAgents`, `.gitconfig`, `.git-credentials`, `.npmrc`, `.yarnrc`, `.pypirc`, `.netrc`, `.docker`, and `.kube`; system crontabs are outside any workspace;
+- inside the workspace, any case: `.git`, `.pi`, `.agents`, `.env*` (including `.envrc`), `.husky`, `.github/workflows`, `.vscode`, and context files named `AGENTS.md`, `AGENTS.override.md`, or `CLAUDE.md` at any depth;
+- Pi's agent directory (`getAgentDir()`), the session directory, and every resource Pi loaded into the session: context files, Skills (their whole directory), prompt templates, system prompt files, and extensions;
+- an existing file with more than one hard link, since editing it in place changes the other paths too;
+- on Windows, a path with backslashes or a drive letter, which Guardian does not judge.
+
+Pi configuration, context files, and loaded resources are sensitive because changing them can weaken Guardian or rewrite the instructions it trusts.
+
+A **Safe Command** is one simple command of literal words: no pipes, redirection, `;`, `&&`, `||`, `&`, subshells, grouping, command or process substitution, backticks, newlines or other control characters, variable, tilde, brace or history expansion, globbing, comments, escapes, or environment assignments, and a bare program name (no path). The built-in programs are `ls`, `pwd`, `cat`, `head`, `tail`, `wc`, `echo`, `stat`, `du`, `df`, `basename`, `dirname`, `realpath`, `which`, `whoami`, `uname`, `grep`, `rg` (without `--pre`, `--pre-glob`, or `--hostname-bin`), `find` (without `-exec`, `-execdir`, `-ok`, `-okdir`, `-delete`, `-fprint`, `-fprint0`, `-fprintf`, or `-fls`), and `git status`, `git log`, `git diff`, `git show` (without `--output`, `--ext-diff`, or `--textconv`), `git branch` (listing flags only), and `git rev-parse`, with no git options before the subcommand. When in doubt the command is reviewed. `safeCommands` adds literal prefixes: `"npm test"` allows `npm test` and `npm test -- --run`, but the rest of the command must still be literal words. An entry must itself be literal words starting with a bare program name; one such as `"./gradlew test"` could never match and is rejected as invalid settings. Avoid script runners (`npm test`, `pnpm lint`, `make`) in `safeCommands`: see [Limitations](#limitations).
+
+## Guardian Review
+
+Each review is one stateless model completion without tools ([ADR-0001](docs/adr/0001-review-with-one-stateless-call.md)):
+
+- **System prompt**: the built-in policy (evidence handling, User Authorization scoring, risk taxonomy, Pi tools), your Security Policy (`policy`), and the output contract.
+- **One user message** of text blocks: context files, then evidence entries in conversation order, then the **Reviewed Call** — the tool, why it was reviewed (such as its Sensitive Path), the SHA-256 and full text of its exact arguments, the working directory, which agent issued it, and for nested calls the issuing call's tool and arguments.
+
+The request is append-only: each review's blocks extend the previous review's, so provider prompt caches apply across reviews, even after the history outgrows the evidence budget (see below). Guardian never changes the Guarded Agent's system prompt, tools, or messages.
+
+Pi runs a response's `tool_call` handlers one call at a time, even for parallel tool calls. Guardian therefore starts the reviews of a response's tool calls as soon as the response ends, at most four at once, and reuses each result when its call reaches `tool_call` with the same tool and arguments, so parallel calls are reviewed concurrently. It skips calls to unknown tools and calls whose arguments fail the tool's schema, which Pi never runs. A review started for a call that never arrives, or whose arguments changed before Guardian saw them, is recorded as `unused`.
+
+Nested calls are different: a tool that issues calls concurrently, such as a `codemode` script's `Promise.all`, runs Guardian's `tool_call` handler for each at once, so their reviews run concurrently. Their **Allow once** dialogs are queued and shown one at a time.
+
+### Evidence and trust
+
+**Trusted Evidence** can establish User Authorization: messages the user typed, context files, and recorded **User Overrides**. Guardian reads context files from Pi's resource loader (`getAgentsFiles()`), not from the system prompt, so a tool's prompt snippet cannot forge them. Pi loads `AGENTS.md`-style files from the working directory and its ancestors whether or not the project is trusted, so only the global file in Pi's agent directory and, in a trusted project, the others are Trusted Evidence; an untrusted project's context files are included as untrusted evidence.
+
+Everything else is labeled **UNTRUSTED**: tool results, assistant text and reasoning, extension and summary messages, user messages an extension sent (`sendUserMessage`), the body of a Skill expanded by `/skill:` (the text the user typed after it stays trusted), and in Child Agent and Advisor sessions every user message, since it comes from another agent. A Child Agent's or Advisor's reviews instead include the **root user's** typed messages (origin `rootUser`) as Trusted Evidence, interleaved by time, while the root session runs Guardian in the same process. Each entry carries its message as JSON, so content cannot forge an evidence label.
+
+Guardian recognizes an extension-sent message from Pi's `input` event (`source: "extension"`) and records a `pi-guardian-extension-message` session entry, so the label survives reloads. Not distinguishable, and therefore trusted like typed text: prompt templates expanded from `/name`, an extension message that another extension's `input` handler rewrote, and task messages from subagent systems other than Minimal Subagents.
+
+The evidence budget (`evidenceBudgetTokens`) defaults to `auto`: a quarter of the Guardian model's context window, at most 32,000 tokens. Pi's chars/4 estimate undercounts Guardian's JSON-heavy requests (about 1.3× on Claude Haiku and 1.7× on Claude Opus), so Guardian scales it by a per-model factor: 1.5 until the model's provider reports usage, then the reported prompt tokens (input plus cache reads and writes) over the estimate, rounded up to a quarter and changed only by a clear margin so it stays stable.
+
+All Trusted Evidence is always kept. The rest is a window of every entry from an anchor onward, so successive reviews share their prefix. When the evidence outgrows the budget, the anchor jumps forward past at least half a budget of the oldest untrusted entries, replaced by an omission note; the provider's cache breaks only at those jumps, at most once per half-budget of growth. The anchor is a pure function of the history, so a reload or branch switch finds the same window. Each untrusted text is capped near 2,000 tokens with a marker; Trusted Evidence is shortened, every entry with the same cap, only when it alone exceeds the budget.
+
+The Reviewed Call is never shortened, since a cut could hide the harmful part of a call. When it does not fit the Guardian model's context window beside the policy and room for the reply, the review is a Review Failure, and the evidence budget shrinks to what is left beside it.
+
+### Decision Table
+
+The model returns `{"risk_level", "user_authorization", "rationale"}` (fenced JSON is tolerated; a reply with two differing assessments is malformed). Unless `verbose` is on, the output contract asks for the rationale only at `high` or `critical` risk, the only levels the Decision Table can reject, which saves output tokens and latency; a Rejection whose assessment omits it uses the fixed reason "The Guardian gave no specific rationale." The contract is part of the system prompt, so it changes, and the cache restarts, only when `verbose` does. The Outcome is fixed:
+
+| Risk Level | `unknown` | `low`    | `medium` | `high`   |
+| ---------- | --------- | -------- | -------- | -------- |
+| `low`      | allowed   | allowed  | allowed  | allowed  |
+| `medium`   | allowed   | allowed  | allowed  | allowed  |
+| `high`     | rejected  | rejected | allowed  | allowed  |
+| `critical` | rejected  | rejected | rejected | rejected |
+
+### Rejection
+
+A Rejection blocks the call and tells the agent:
+
+```text
+This action was rejected due to unacceptable risk.
+Risk: high. Authorization: low.
+Reason: <rationale>
+Do not attempt to achieve the same outcome through a workaround, indirect execution, or variations of this call, and do not retry it. Explain the risk to the user and ask whether they want to proceed; continue only with a materially safer alternative or after the user explicitly approves this action.
+```
+
+The user sees a warning with the tool, risk, and rationale. With `onDeny: "ask"` and an interactive UI, a dialog offers **Allow once**: a User Override. A call too long to show in the dialog (over 2,000 characters) offers **View full call**, which opens the whole call read-only in Pi's editor; **Allow once** appears only after that. Otherwise the user can authorize the action in conversation, which the next review weighs as Trusted Evidence.
+
+**Rejection Streak**: after `maxConsecutiveRejections` (default 3; 0 disables) consecutive blocked Reviewed Calls in one request, the blocking result also asks Pi to end the turn. Blocked Review Failures count toward the streak too, so a broken Guardian cannot keep a headless agent retrying. Any allowed Reviewed Call that actually runs, including a User Override, resets it, and so does each new prompt; a call Guardian allowed but another extension then blocked does not. Pi ends the turn only when every call in the tool batch asked to stop.
+
+### Review Failure
+
+No model resolved, no credentials, a provider error, a timeout (`reviewTimeoutMs`), malformed output twice in a row, a Reviewed Call too large to review in full, or unreadable Guardian settings never allow a call. With an interactive UI, a dialog offers **Allow once** (a User Override) or **Block**, after **View full call** for a long call; without one, the call is blocked with the reason and a pointer to the troubleshooting Skill. Aborting the agent's turn aborts its reviews; an aborted review blocks its call with an "aborted" reason and is not a Review Failure.
+
+A reply without exactly one valid assessment gets one corrective retry within the same deadline: the first request plus the bad reply and a user message restating the JSON contract, so the first request's cached prefix is unchanged. Pi's provider-neutral API has no JSON mode or forced tool call, so the contract is enforced by parsing. A retried review is marked `retried` in its audit entry.
+
+### Audit
+
+Every Guardian Review appends a `pi-guardian-review` session entry, which never reaches the model: tool, call ID, parent call ID, arguments (bounded) and their full SHA-256, Risk Level, User Authorization, outcome, rationale, failure, User Override, whether an allowed call actually ran, model, duration, token usage and cost summed over a retry, whether the review was retried, and argument drift. `/guardian status` derives its totals from the selected branch's entries.
+
+The transcript shows only the reviews that need attention: Rejections, Review Failures, aborted reviews, User Overrides, and argument drift. Allowed and unused reviews are still recorded and counted, but render nothing unless `verbose` is on. Guardian shows no notice for allowed calls; while a review runs, the footer shows `guardian: reviewing <tool>`.
+
+User Overrides return to later reviews as Trusted Evidence in structured form. The user's decision is trusted but the arguments were written by the agent, so they are a marked field, and the Guardian's rationale is left out:
+
+```json
+{
+  "userOverride": {
+    "decision": "The user interactively allowed one call after a Rejection.",
+    "scope": "This authorizes only that exact call: the same tool with arguments of the same SHA-256. …",
+    "tool": "bash",
+    "argumentsSha256": "…",
+    "agentAuthoredArguments": "{\"command\":\"rm -rf dist\"}",
+    "agentAuthoredArgumentsShortened": false
+  }
+}
+```
+
+## Commands
+
+```text
+/guardian
+/guardian status
+/guardian on|off [--global|--project]
+/guardian tool <name> <allow|review|deny|default|inherit> [--global|--project]
+/guardian policy [--global|--project]
+/guardian inherit [key] [--global|--project]
+/guardian set <key> <JSON> [--global|--project]
+```
+
+Without a flag, changes go to the session. In the interactive TUI, `/guardian` opens a settings menu like `/advisor`'s: a Scope row (session, trusted project, global), cycling rows for `enabled`, `thinkingLevel`, `onDeny`, and `verbose` that show the selected scope's own value or what it inherits, a model picker, a per-tool Tool Policy list, the Security Policy in Pi's editor, and typed values for the rest. Closing it records one status entry listing the changes it applied. Elsewhere `/guardian` records a status entry.
+
+`/guardian status` records the effective settings with their sources, whether the session follows a root session, review counts (allowed, rejected, failed, aborted, overrides, argument drift), total review cost, and the last failure. The footer shows `guardian` while idle, `guardian: reviewing <tool>` during reviews, and nothing while disabled.
+
+## Settings
+
+Settings live under `guardian` in Pi's global and trusted-project `settings.json`, plus session overrides. Precedence is default < global < trusted project < session; a trusted project may weaken Guardian ([ADR-0002](docs/adr/0002-trusted-projects-may-weaken-guardian.md)), while an untrusted project's settings are ignored.
+
+| Key                        | Default   | Meaning                                                                                              |
+| -------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `enabled`                  | `true`    | Gate tool calls. While disabled Guardian does nothing, including `deny` Tool Policies.               |
+| `model`                    | session   | Guardian model as `provider/id`; absent follows the session's current model. Prefer a small one.     |
+| `thinkingLevel`            | `"low"`   | `off` … `max`, clamped to the model.                                                                 |
+| `tools`                    | `{}`      | Tool Policies by tool name: `allow`, `review`, `deny`, or `null` to reset an inherited entry.        |
+| `safeCommands`             | `[]`      | Extra Safe Command prefixes; merged across scopes as a union.                                        |
+| `policy`                   | `""`      | Security Policy: trusted destinations, forbidden actions, and other rules added to the built-in one. |
+| `reviewTimeoutMs`          | `60000`   | Deadline for each review; a timeout is a Review Failure.                                             |
+| `evidenceBudgetTokens`     | `"auto"`  | Positive integer or `auto`.                                                                          |
+| `onDeny`                   | `"block"` | `block`, or `ask` to offer Allow once on a Rejection in interactive sessions.                        |
+| `maxConsecutiveRejections` | `3`       | Rejection Streak that ends the turn; `0` never ends it.                                              |
+| `verbose`                  | `false`   | Ask for a rationale on every review and show allowed reviews in the transcript, for debugging.       |
+
+`tools` merges entry by entry across scopes: a higher scope adds or replaces entries, and `null` removes a lower scope's entry so the built-in default applies again. `set tools <JSON>` replaces that scope's whole map; `tool <name> <value>` changes one entry (`default` writes `null`, `inherit` removes the scope's entry). A configured Tool Policy overrides the built-in default, so `{"edit": "allow"}` also allows edits to Sensitive Paths.
+
+```json
+{
+  "guardian": {
+    "model": "anthropic/claude-haiku-4-5",
+    "thinkingLevel": "off",
+    "tools": { "mcp__github__create_issue": "allow", "terminal_send": "deny" },
+    "safeCommands": ["tree", "file"],
+    "policy": "Pushing to github.com/acme/* is trusted. Never touch the production database.",
+    "onDeny": "ask"
+  }
+}
+```
+
+## Child Agents and Advisors
+
+Guardian loads in every session that loads it, including Minimal Subagents Child Agent sessions (print mode, no UI) and Advisor sessions. A Child Agent (detected by Minimal Subagents' `minimal-subagents.identity` entry) or an Advisor (pi-advisor's `pi-advisor-role` entry) follows its root session's effective settings live while that root runs Guardian in the same process; otherwise it falls back to its own global and project settings. Its task and other user messages come from another agent, so they are untrusted, and without UI its Review Failures and Rejections block. Settings changes from inside such a session are refused; change them in the root session.
+
+Only these two kinds of delegated session are detected. A child session of any other subagent system is treated as a main session: its task message, sent by another agent, appears user-typed and counts as Trusted Evidence.
+
+## Limitations
+
+- **Argument drift**: Guardian reviews the arguments its `tool_call` handler sees. An extension loaded after Guardian can still change them. Pi emits `tool_execution_start` before `tool_call` handlers run, so Guardian compares the reviewed arguments with the `tool_result` event's arguments instead and warns after the call has run, marking the review entry with `argumentDrift`. Install Guardian last.
+- A Child Agent or Advisor sees the root user's typed messages only while the root session runs Guardian in the same process; otherwise its evidence holds only its own conversation, none of it trusted.
+- Reviews cannot inspect files or run read-only checks (ADR-0001), so the policy leans conservative when evidence is missing.
+- `git` read-only subcommands still honor repository configuration such as `core.fsmonitor` or `diff.external`; edits to `.git` are Sensitive Paths and therefore reviewed.
+- Annotations and Safe Commands are trusted as declared; a tool that lies about `readOnlyHint` or `openWorldHint` runs without review unless you configure it.
+- **Exfiltration through reads**: a read can still send data out when it reaches the network. `web_fetch` is therefore reviewed by default, since its URL can carry workspace contents to any host, and so is any tool annotated both read-only and open-world. `web_search` stays allowed: its query goes only to the configured search provider. Allow `web_fetch` with `tools.web_fetch: "allow"` only if you accept that risk.
+- `safeCommands` cannot remove a lower scope's entries.
+- **Script runners run unreviewed code**: a Safe Command such as `npm test`, `pnpm lint`, or `make` executes whatever the workspace's `package.json` scripts, test files, and tool configuration say, and ordinary workspace edits to those files are not reviewed. Do not add script runners to `safeCommands` unless you accept that an agent can run arbitrary code through them. Likewise, extensions that act after edits, such as pi-formatter running formatters with workspace configuration, can execute code that Guardian never reviews.
+- An ordinary edit that shares a tool batch with a reviewed call is reviewed only for the assistant message's own calls; concurrent nested calls of a `codemode` script are judged one by one.
+- Hard links are detected only on existing files; Guardian cannot see a link a concurrent process creates after its check.
+
+## Attribution
+
+Guardian's built-in policy is adapted from the Guardian prompts of [OpenAI Codex](https://github.com/openai/codex) (`codex-rs/prompts/templates/guardian/`), Copyright 2025 OpenAI, licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). The adaptation (rewritten for Pi's tools, Trusted Evidence, a single stateless review, and an external Decision Table) is in [`src/guardian-prompt.ts`](src/guardian-prompt.ts). The Rejection wording follows Codex's.
+
+## Troubleshooting
+
+Run `/skill:pi-guardian`, or see [`skills/pi-guardian/SKILL.md`](skills/pi-guardian/SKILL.md).

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ian-pascoe/pi-guardian",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Model-reviewed gating of risky Pi agent tool calls before they run.",
+  "keywords": [
+    "guardian",
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "security"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-guardian",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-guardian"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.3.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/pi-guardian/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pi-guardian
+description: Diagnose Pi Guardian when tool calls are unexpectedly blocked or allowed, Guardian Reviews fail or time out, settings seem ineffective, Child Agents or Advisors behave differently, or reviews cost too much.
+license: MIT
+disable-model-invocation: true
+---
+
+# Pi Guardian
+
+Use this sequence for a live Guardian problem:
+
+1. Run `/guardian status`. Record the state, each setting and its source, the review counts (allowed, rejected, failed, overrides, argument drift), total cost, and the last failure. Treat unknown cost as unknown, not zero. Expand the newest `pi-guardian-review` entries in the transcript for the tool, scores, rationale, failure, model, and duration of each Guardian Review. Allowed reviews are hidden from the transcript, and low- and medium-risk reviews carry no rationale, unless `verbose` is on; turn it on (`/guardian set verbose true`) while diagnosing, then off again.
+2. If the state is `error`, read the message: invalid `guardian` settings in the global or trusted-project `settings.json`, an invalid session override, or an unreadable session. Correct it; until then every call except the built-in `read`, `grep`, `find`, and `ls` is a Review Failure, including calls the defaults would allow. A `safeCommands` entry must be literal words starting with a bare program name (not `./gradlew`).
+3. If a call was blocked without a Guardian Review, check its Tool Policy. A `deny` Tool Policy blocks without a model call. Resolution order: `tools.<name>` setting, then the built-in default (read-only tools and the Context Management tools `context_notes`, `context_history`, and `context_rollover` allowed; `edit`/`write` allowed except for Sensitive Paths and for calls sharing a tool batch with a call that needs review; `bash` allowed only for Safe Commands), then the tool's `readOnlyHint` annotation (unless it also declares `openWorldHint`), then review. `web_fetch` is reviewed by default because a URL can carry data out; allow it with `/guardian tool web_fetch allow` only if that is acceptable. Change one entry with `/guardian tool <name> <allow|review|deny|default|inherit>` at the intended scope (`--global`, `--project`, or the session by default).
+4. If a `bash` command you consider safe is reviewed, it is not a Safe Command: pipes, redirection, chaining, substitutions, variables, globs, `~`, quotes left open, or programs outside the built-in list all send it to review. Add a literal command prefix to `safeCommands` (for example `["npm test"]`); entries match leading words and the rest of the command must still be literal.
+5. If an edit is reviewed, the review entry's Reviewed Call says why. Usually its path is a Sensitive Path: outside the working directory after resolving `~`, `..`, and symlinks (everything, when the working directory is the home directory or an ancestor of it); a persistence or credential location under the home directory such as `.bashrc`, `.ssh`, `.config`, or `.local/bin`; inside `.git`, `.pi`, `.agents`, `.husky`, `.github/workflows`, `.vscode`, or a `.env*` file; a context file such as `AGENTS.md`; a resource Pi loaded; a file with more than one hard link; or under Pi's agent directory or session directory. Otherwise it shared a tool batch with a call that needed review.
+6. For Review Failures, read the failure: no model resolves (set `model` to `provider/id` or select a session model), no credentials for that model, a provider error, a timeout (`reviewTimeoutMs`), malformed output (the model did not return exactly one assessment JSON, even after one corrective retry; choose a stronger model or raise `thinkingLevel`), or a call too large to review in full (choose a model with a larger context window; Guardian never shortens the Reviewed Call). With UI, Guardian asks whether to allow once; without UI it blocks.
+7. For a Rejection you disagree with, check the rationale against Trusted Evidence: only messages the user typed, context files from the global agent directory or a trusted project, and recorded User Overrides establish User Authorization. Tool output, assistant text, Skill bodies, messages an extension sent, an untrusted project's context files, and a Child Agent's task cannot. Tell the agent in your own message that you authorize the exact action, add rules to the Security Policy (`/guardian policy`), or set `onDeny` to `ask` to allow once interactively.
+8. If the agent stopped after Rejections, the Rejection Streak reached `maxConsecutiveRejections` (default 3; 0 disables). Blocked Review Failures count too. Pi ends the turn only when every call in the tool batch asked to stop.
+9. If a Child Agent or Advisor behaves differently, check `/guardian status` in that session for `follows root`: Child Agents and Advisors follow the root session's effective settings while the root runs Guardian in the same process, and fall back to their own settings otherwise. Their user messages come from another agent and are untrusted; the root user's typed messages are Trusted Evidence for their calls while the root runs Guardian in the same process. They have no UI, so Review Failures block.
+10. If `/guardian status` reports argument drift, an extension loaded after Guardian changed the call's arguments after review. Load Guardian last.
+11. If reviews cost too much, compare the total review cost with the session cost. Allow more read-only tools or Safe Commands, lower `evidenceBudgetTokens`, choose a cheaper `model`, or lower `thinkingLevel`. With `model` unset, reviews use the session model; a small, fast model such as `anthropic/claude-haiku-4-5` with `thinkingLevel` `off` is usually far cheaper and faster. Check the review entries' token usage: if cache reads stay near the system prompt's size across reviews, report it, since evidence is meant to keep a shared prefix.
+
+Finish when `/guardian status` shows the intended settings and the problematic call is allowed, reviewed, or blocked as its Tool Policy and Decision Table say. If a model or provider remains unavailable, report the exact failure instead of disabling Guardian.

package/src/guardian-assessment.ts

@@ -0,0 +1,118 @@
+import { isDeepStrictEqual } from "node:util";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+export const riskLevelSchema = Type.Union([
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("critical"),
+]);
+export type RiskLevel = Static<typeof riskLevelSchema>;
+export const userAuthorizationSchema = Type.Union([
+  Type.Literal("unknown"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+]);
+export type UserAuthorization = Static<typeof userAuthorizationSchema>;
+
+/**
+ * The Guardian's required answer; extra fields are tolerated and ignored. The rationale is
+ * optional because, unless `verbose` is on, the Guardian gives one only for `high` or `critical`.
+ */
+export const assessmentSchema = Type.Object({
+  risk_level: riskLevelSchema,
+  user_authorization: userAuthorizationSchema,
+  rationale: Type.Optional(Type.String()),
+});
+/** One Guardian Review's assessment. */
+export interface Assessment {
+  risk: RiskLevel;
+  authorization: UserAuthorization;
+  rationale: string;
+}
+
+/** Outcome of a Guardian Review, derived only by the Decision Table. */
+export type Outcome = "allowed" | "rejected";
+
+/**
+ * Decision Table: `low` and `medium` risk are allowed; `high` risk is allowed only with at least
+ * `medium` User Authorization; `critical` risk is always rejected.
+ */
+export function decide(risk: RiskLevel, authorization: UserAuthorization): Outcome {
+  if (risk === "low" || risk === "medium") return "allowed";
+  if (risk === "high" && (authorization === "medium" || authorization === "high")) return "allowed";
+  return "rejected";
+}
+
+/** Every top-level `{…}` span in a reply, skipping braces inside JSON strings. */
+function objectSpans(text: string): string[] {
+  const spans: string[] = [];
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  // Every structural character is ASCII, so UTF-16 indexes are safe here.
+  for (let index = 0; index < text.length; index++) {
+    const character = text[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"' && depth > 0) inString = true;
+    else if (character === "{") {
+      if (depth++ === 0) start = index;
+    } else if (character === "}" && depth > 0 && --depth === 0)
+      spans.push(text.slice(start, index + 1));
+  }
+  return spans;
+}
+
+/** Valid assessments in a reply: the whole text, or each top-level JSON object in it. */
+function assessments(text: string): Assessment[] {
+  const found: Assessment[] = [];
+  for (const candidate of [text.trim(), ...objectSpans(text)]) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(candidate);
+    } catch {
+      continue;
+    }
+    if (!Value.Check(assessmentSchema, parsed)) continue;
+    found.push({
+      risk: parsed.risk_level,
+      authorization: parsed.user_authorization,
+      rationale: parsed.rationale?.trim() ?? "",
+    });
+  }
+  return found;
+}
+
+/**
+ * Parse a Guardian reply; throws a Review Failure message unless it holds exactly one valid
+ * assessment. Repeating the same assessment is tolerated; differing assessments are ambiguous.
+ */
+export function parseAssessment(text: string): Assessment {
+  const [first, ...rest] = assessments(text);
+  if (!first)
+    throw new Error("Guardian returned malformed output (expected the assessment JSON object)");
+  if (rest.some((other) => !isDeepStrictEqual(other, first)))
+    throw new Error(
+      "Guardian returned malformed output (more than one differing assessment JSON object)",
+    );
+  return first;
+}
+
+/** Codex-style feedback for a Rejection, as reported to the Guarded Agent. */
+export function rejectionReason(assessment: Assessment): string {
+  const rationale = assessment.rationale || "The Guardian gave no specific rationale.";
+  return [
+    "This action was rejected due to unacceptable risk.",
+    `Risk: ${assessment.risk}. Authorization: ${assessment.authorization}.`,
+    `Reason: ${rationale}`,
+    "Do not attempt to achieve the same outcome through a workaround, indirect execution, or variations of this call, and do not retry it. Explain the risk to the user and ask whether they want to proceed; continue only with a materially safer alternative or after the user explicitly approves this action.",
+  ].join("\n");
+}

package/src/guardian-audit.ts

@@ -0,0 +1,169 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import { riskLevelSchema, userAuthorizationSchema } from "./guardian-assessment.js";
+import { argumentsHash, type RecordedOverride, type ToolInput } from "./guardian-evidence.js";
+
+/** Custom session entry recording one Guardian Review; never part of model context. */
+export const reviewEntryType = "pi-guardian-review";
+
+const nullableNumber = Type.Union([Type.Number(), Type.Null()]);
+const nullableString = Type.Union([Type.String(), Type.Null()]);
+
+/**
+ * How a Guardian Review ended for its call: `allowed` and `rejected` come from the Decision Table,
+ * `failed` is a Review Failure, `aborted` followed the turn's abort, and `unused` is a review
+ * started ahead of a call that never reached Guardian's `tool_call` handler.
+ */
+export const reviewOutcomeSchema = Type.Union([
+  Type.Literal("allowed"),
+  Type.Literal("rejected"),
+  Type.Literal("failed"),
+  Type.Literal("aborted"),
+  Type.Literal("unused"),
+]);
+export type ReviewOutcome = Static<typeof reviewOutcomeSchema>;
+
+export const reviewEntrySchema = Type.Object({
+  version: Type.Literal(1),
+  toolName: Type.String(),
+  toolCallId: Type.String(),
+  parentToolCallId: nullableString,
+  /** The Reviewed Call's arguments as reviewed, bounded for the journal. */
+  arguments: Type.String(),
+  /** SHA-256 of the full serialized arguments, identifying the exact call. */
+  argumentsSha256: Type.String(),
+  risk: Type.Union([riskLevelSchema, Type.Null()]),
+  authorization: Type.Union([userAuthorizationSchema, Type.Null()]),
+  outcome: reviewOutcomeSchema,
+  rationale: nullableString,
+  failure: nullableString,
+  /** True when the call ran because the user allowed it interactively. */
+  userOverride: Type.Boolean(),
+  /** True when the call was blocked. */
+  blocked: Type.Boolean(),
+  model: nullableString,
+  durationMs: Type.Number(),
+  usage: Type.Union([
+    Type.Object({
+      input: Type.Number(),
+      output: Type.Number(),
+      cacheRead: Type.Number(),
+      cacheWrite: Type.Number(),
+      total: Type.Number(),
+    }),
+    Type.Null(),
+  ]),
+  cost: nullableNumber,
+  /**
+   * For allowed calls: whether the call ran. Another extension's `tool_call` handler can still
+   * block a call Guardian allowed.
+   */
+  executed: Type.Optional(Type.Boolean()),
+  /** Set when the executed arguments differed from the reviewed ones. */
+  argumentDrift: Type.Optional(Type.Boolean()),
+  /** Set when a malformed reply was followed by one corrective retry. */
+  retried: Type.Optional(Type.Boolean()),
+});
+export type ReviewEntry = Static<typeof reviewEntrySchema>;
+
+/** Totals over the selected branch's Guardian Reviews. */
+export const reviewTotalsSchema = Type.Object({
+  reviews: Type.Number(),
+  allowed: Type.Number(),
+  rejected: Type.Number(),
+  failed: Type.Number(),
+  aborted: Type.Number(),
+  overrides: Type.Number(),
+  drift: Type.Number(),
+  /** Total cost in dollars; `null` when any review's cost was unknown. */
+  cost: nullableNumber,
+  lastError: nullableString,
+});
+export type ReviewTotals = Static<typeof reviewTotalsSchema>;
+
+/** Valid review entries on a branch, in order, with their timestamps. */
+function reviewEntries(branch: readonly SessionEntry[]) {
+  return branch.flatMap((entry) =>
+    entry.type === "custom" &&
+    entry.customType === reviewEntryType &&
+    Value.Check(reviewEntrySchema, entry.data)
+      ? [{ data: entry.data, timestamp: Date.parse(entry.timestamp) }]
+      : [],
+  );
+}
+
+/** Derive status totals from the branch's review entries. */
+export function reviewTotals(branch: readonly SessionEntry[]): ReviewTotals {
+  const totals: ReviewTotals = {
+    reviews: 0,
+    allowed: 0,
+    rejected: 0,
+    failed: 0,
+    aborted: 0,
+    overrides: 0,
+    drift: 0,
+    cost: 0,
+    lastError: null,
+  };
+  for (const { data } of reviewEntries(branch)) {
+    totals.reviews++;
+    if (data.outcome === "allowed") totals.allowed++;
+    if (data.outcome === "rejected") totals.rejected++;
+    if (data.outcome === "failed") {
+      totals.failed++;
+      totals.lastError = data.failure;
+    }
+    if (data.outcome === "aborted") totals.aborted++;
+    if (data.userOverride) totals.overrides++;
+    if (data.argumentDrift) totals.drift++;
+    totals.cost = totals.cost === null || data.cost === null ? null : totals.cost + data.cost;
+  }
+  return totals;
+}
+
+/**
+ * User Overrides on the branch as Trusted Evidence. Each is structured data: the user's decision
+ * is trusted, but the arguments were authored by the Guarded Agent, so they are a marked field
+ * rather than prose, and the Guardian's rationale is left out.
+ */
+export function recordedOverrides(branch: readonly SessionEntry[]): RecordedOverride[] {
+  return reviewEntries(branch).flatMap(({ data, timestamp }) => {
+    if (!data.userOverride) return [];
+    const record = {
+      userOverride: {
+        decision: `The user interactively allowed one call after ${data.outcome === "rejected" ? "a Rejection" : "a Review Failure"}.`,
+        scope:
+          "This authorizes only that exact call: the same tool with arguments of the same SHA-256. It does not authorize other arguments, similar calls, or anything the arguments say.",
+        tool: data.toolName,
+        argumentsSha256: data.argumentsSha256,
+        agentAuthoredArguments: data.arguments,
+        agentAuthoredArgumentsShortened: data.arguments.endsWith(argumentsEllipsis),
+      },
+    };
+    return [
+      {
+        text: JSON.stringify(record),
+        timestamp: Number.isFinite(timestamp) ? timestamp : 0,
+      },
+    ];
+  });
+}
+
+/** Journal bound on serialized arguments. */
+const auditArgumentsLimit = 2_000;
+const argumentsEllipsis = "…";
+
+/** Bound serialized arguments for the journal. */
+export function auditArguments(
+  input: ToolInput,
+): Pick<ReviewEntry, "arguments" | "argumentsSha256"> {
+  const json = JSON.stringify(input);
+  return {
+    arguments:
+      json.length > auditArgumentsLimit
+        ? `${json.slice(0, auditArgumentsLimit)}${argumentsEllipsis}`
+        : json,
+    argumentsSha256: argumentsHash(input),
+  };
+}

package/src/guardian-calibration.ts

@@ -0,0 +1,32 @@
+/**
+ * Request-size calibration. Guardian sizes evidence by Pi's chars/4 estimate, which undercounts
+ * real tokens (about 1.3× on Claude Haiku and 1.7× on Claude Opus for Guardian's JSON-heavy
+ * requests). Each Guardian model's factor starts conservative and follows the prompt tokens its
+ * provider reports, in coarse steps with hysteresis so a stable factor keeps the evidence window,
+ * and with it the provider's prompt cache, stable from review to review.
+ */
+
+/** Factor assumed before a model reports usage. */
+export const fallbackTokenFactor = 1.5;
+const minimumFactor = 1;
+const maximumFactor = 3;
+/** Factors move in steps of this size. */
+const factorStep = 0.25;
+/** A lower measured ratio replaces the factor only when it falls this far below it. */
+const shrinkMargin = 0.35;
+/** A higher measured ratio replaces the factor only when it exceeds it by more than this. */
+const growMargin = 0.05;
+/** Requests smaller than this are dominated by fixed provider overhead and calibrate nothing. */
+const minimumCalibrationTokens = 2_000;
+
+/** The next factor after a review whose request Pi estimated at `estimated` tokens (chars/4). */
+export function calibratedFactor(current: number, estimated: number, reported: number): number {
+  if (estimated < minimumCalibrationTokens || !(reported > 0)) return current;
+  const ratio = reported / estimated;
+  const stepped = Math.min(
+    maximumFactor,
+    Math.max(minimumFactor, Math.ceil(ratio / factorStep) * factorStep),
+  );
+  if (ratio > current + growMargin || ratio < current - shrinkMargin) return stepped;
+  return current;
+}