@hank-warren/pi-auto-permissions 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @hank-warren/pi-auto-permissions
 
+## 0.13.0
+
+### Minor Changes
+
+- 488b4bd: Auto Permissions becomes a review-by-default competitor to Claude Code auto mode.
+
+  **Migration note:** a fresh install (or a config with no `rules` key) now runs the built-in default ruleset — deny rules for agent-oversight bypasses and critical-path destruction, guardian review for force pushes, infrastructure destroys, credential access, and the other default groups. `"rules": []` restores the old gate-nothing behavior; an authored `rules` array is unchanged; `"$defaults"` inside an authored array splices the built-ins in.
+
+  New in pi-auto-permissions:
+
+  - `deny` rule level: a hard boundary that outranks every other match and cannot be cleared by `request_override`, `.pi/trusted-ops`, or user approval
+  - Built-in default ruleset (9 groups) active when no `rules` key is authored, with `"$defaults"` splice support
+  - `reviewAllShell`: blanket guardian review for commands no rule matches
+  - `guardianPolicy`: prose trust configuration (environment / allow / softDeny / hardDeny) with four-tier precedence
+  - Session-start trust snapshot: remotes captured once at session start; remotes added mid-session sit outside the trust baseline
+  - Unresolvable destructive targets (`rm -rf "$VAR"` with no visible assignment) get `revise` naming the literal-path fix
+  - Optional two-stage review: a stateless single-token SAFE/REVIEW prefilter (`reviewer.prefilter`) before full review, fail-closed
+  - Delegated (subagent) tasks held to an explicit-intent standard; non-allowlisted custom messages become capped tool-source evidence
+  - Denial ledger (`denials.jsonl`), Recent-denials + Allow-on-retry in `/auto-permissions`, an `auto-permissions:denied` event, and permission overrides that persist across session resume
+  - `/auto-permissions setup`: a wizard that scans the project and recent session command strings (never user messages) and drafts `guardianPolicy.environment` entries plus trusted-ops suggestions
+
+  pi-permission-selector: `OptionSelector` title lines now wrap to the render width instead of overflowing — an unwrapped reviewer-failure detail in the title crashed the whole session under pi-tui's width assertion.
+
+### Patch Changes
+
+- Updated dependencies [488b4bd]
+  - @hank-warren/pi-permission-selector@1.4.1
+
+## 0.12.1
+
+### Patch Changes
+
+- 895b323: Require `@hank-warren/pi-permission-selector` `^1.4.0`, the release where option
+  descriptions wrap instead of being truncated. The old `^1.3.0` range resolved to
+  1.4.0 only on a host that also installed a sibling asking for it; installed on
+  its own, `pi-auto-permissions` could still satisfy the range with 1.3.x and
+  present a silently different selector.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -19,6 +19,23 @@ Pi Auto Permissions pauses configured Bash commands before execution. A guardian
 
 Only user messages can grant permission or impose constraints. The assistant cannot authorize its own command.
 
+The posture is review-by-default: a fresh install ships a live ruleset (deny rules for oversight bypasses and critical-path destruction, guardian review for force pushes, infrastructure destroys, credential access, and the rest of the default groups), prose trust configuration in `guardianPolicy`, a session-start trust snapshot, an optional blanket `reviewAllShell` mode with a cheap prefilter stage, a denial ledger with allow-on-retry, and a setup wizard that drafts the trust config from your project.
+
+## Compared with Claude Code auto mode
+
+The design deliberately mirrors Claude Code's auto mode (default ruleset content, trust tiers, `"$defaults"` splice, session-start remote baseline, two-stage review, denial review) while keeping the pieces pi does better. Honestly stated, both directions:
+
+| | pi-auto-permissions | Claude Code auto mode |
+|---|---|---|
+| **Loop/retry budgets** | Three orthogonal budgets (per-concern, per-gate, streak); the streak resets only when an approval lands on a gate that was actually blocking; persisted across compaction and resume | 3-consecutive/20-total; *any* allowed action resets the consecutive counter, so interleaved reads defeat it; not configurable |
+| **Verdicts and reasons** | `approve`/`revise`/`ask_user`; always a concrete one-sentence reason; `revise` tells the agent exactly how to clear the objection | Deny only; fixed `Blocked by classifier` text in most sessions |
+| **Evidence caching** | Append-only reviewer lineage: full envelope once, deltas after, fingerprint-invalidated | Stage-1→stage-2 prompt cache; no cross-review evidence cache |
+| **Deterministic surface** | Regex gates are testable; the false-positive surface is bounded by the patterns; the guardian runs only after a mechanical match | Prose rules are checkable only by running the classifier |
+| **Evaluation loop** | Labelled evaluation JSONL (three-way user labels, prefilter FNR records) + per-review cost sidecar | `/feedback`; no per-review cost or label surface |
+| **Coverage** | **Bash only.** Edits, writes, fetches, MCP tools, and subagent spawns are ungated (the beyond-bash plan is the named follow-up) | All tool calls Tier 3-reviewed; in-project edits skip review by design |
+| **Sandbox** | None — pair with OS sandboxing for a hard boundary | Integrated sandbox + network-domain review |
+| **Injection posture** | Keeps assistant text and tool-call summaries as (non-authorizing) evidence — better provenance, larger injection surface | Strips assistant text and tool output entirely; input-layer injection probe |
+
 ## Example
 
 Suppose Git commits are globally guarded.
@@ -59,7 +76,11 @@ Remove or disable other extensions that gate the same commands to avoid duplicat
 
 ## Define your policy
 
-The extension ships with an empty command policy. Nothing is guarded until you add rules, and commands that do not match a rule run normally.
+The extension ships with a default policy, derived from the mechanically matchable rows of Claude Code auto mode's blocked-by-default list. Out of the box — no config file at all — it denies agent-oversight bypasses and critical-path destruction outright, and sends force pushes, history rewrites, infrastructure destroys, piped remote code execution, credential access, registry overrides, PR merges/self-approvals, and shell writes to protected dotfiles to the guardian. A normal dev session (build, test, commit, push a feature branch) triggers zero gates.
+
+The policy is a list of rules. When your config has no `rules` key at all, the built-in ruleset is active. An authored `rules` array fully replaces the built-ins — unless it splices them back in with the literal string `"$defaults"`, which expands to the built-in ruleset at that position so your entries can sit before or after them. An explicit `"rules": []` gates nothing (the pre-0.13 out-of-box behavior, now an explicit opt-out). Commands that do not match a rule run normally.
+
+The default groups — usable in `.pi/trusted-ops` (guarded rules only) — are `oversight`, `destructive`, `git`, `iac`, `net-exec`, `secrets`, `supply-chain`, `review`, and `protected-paths`. See [`default-rules.ts`](default-rules.ts) for the exact patterns and levels.
 
 Configuration is read before every Bash command from:
 
@@ -69,11 +90,12 @@ $PI_CODING_AGENT_DIR/pi-auto-permissions/config.json
 
 `PI_CODING_AGENT_DIR` defaults to `~/.pi/agent`.
 
-Here is a small starter policy for commits, pushes, and publishing:
+Here is a policy that keeps the defaults and additionally gates commits, pushes, and publishing:
 
 ```json
 {
   "rules": [
+    "$defaults",
     {
       "pattern": "\\bgit\\s+commit\\b",
       "flags": "i",
@@ -103,19 +125,74 @@ Rule fields are:
 
 - `pattern`: JavaScript regular expression source
 - `flags`: optional regular expression flags, defaulting to `i`
-- `level`: `guarded` for guardian review or `convention` for a direct policy block
+- `level`: `guarded` for guardian review, `convention` for an overridable policy block, or `deny` for a hard block
 - `group`: policy group used by trusted-project bypasses
 - `label`: short description shown during review
-- `message`: optional feedback; required for convention rules
+- `message`: optional feedback; required for convention and deny rules
 
 A convention rule blocks directly with its configured feedback instead of asking the guardian. The agent can call `request_override` for a legitimate one-session exception. Overrides require user confirmation and cannot bypass guarded rules.
 
+A deny rule is a hard policy boundary: it blocks immediately with its message, is evaluated before every other level, and nothing lifts it — not `request_override`, not a trusted group, not user approval at a prompt. Reserve it for operations that should never happen in an agent session (disabling agent oversight, deleting critical paths), and use `guarded` where a human judgment call is legitimate.
+
+When several rules match one command, the most severe level wins (deny, then convention, then guarded) regardless of their order in the list.
+
 Set `enabled` to `false` to disable the extension. Invalid configuration fails closed and blocks Bash calls until corrected.
 
+### Review every shell command
+
+Set `"reviewAllShell": true` to review every bash command that matches no rule under a generic `shell command` gate (group `all-shell`), the analogue of Claude Code's `classifyAllShell`. The rules then act as a severity layer on top of blanket coverage: deny rules still block outright, convention rules still block with feedback, and everything else — named by a rule or not — goes to the guardian. The trade is one guardian call per command; pair it with a cheap reviewer model. A command whose matching group is listed in `.pi/trusted-ops` was explicitly waved through and is not re-captured by the blanket gate; trusting `all-shell` itself opts a project out of blanket review while keeping the ruleset live. Loop budgets, lineage caching, and the evaluation log apply to `all-shell` reviews unchanged.
+
+## Define trusted infrastructure
+
+The rules decide *which* commands are reviewed; `guardianPolicy` tells the guardian *how to judge them* against your infrastructure. All four lists are prose — write entries the way you would describe your environment to a new engineer:
+
+```json
+{
+  "guardianPolicy": {
+    "environment": [
+      "Our GitHub orgs nuclearn-ai and hank-warren are trusted source control",
+      "registry.internal.example is our internal package registry"
+    ],
+    "allow": [
+      "Uploading build artifacts to the artifacts.example.com bucket is routine"
+    ],
+    "softDeny": [
+      "Do not run database migrations against staging without being asked"
+    ],
+    "hardDeny": [
+      "Never push code or data to a repository outside our GitHub orgs"
+    ]
+  }
+}
+```
+
+The lists extend the built-in decision table (which stays active) and are appended to the reviewer prompt as a labeled section with explicit precedence:
+
+1. **hardDeny** blocks unconditionally — user intent, permission overrides, and allow entries never clear it.
+2. **softDeny** blocks unless an allow entry covers the action or the user's own message names the exact action and target ("force-push this branch", not "clean up the repo").
+3. **allow** entries are exceptions to softDeny and to the trust boundary: data flow only, never destructive or credential operations on the same infrastructure.
+4. **environment** entries define what "internal" means — a destination nothing names is treated as a potential exfiltration target.
+
+Each list is independent: setting `environment` alone leaves the others intact. Worth filling in, slot by slot: your source control orgs, trusted internal domains, cloud buckets, package registries and mirrors, key internal services — and on the sensitive side, production namespaces, sensitive data locations, and remote targets that should always get a hard look. These sections are appended outside `systemPrompt`, so a customized `systemPromptFile` still receives them, and every entry participates in the reviewer fingerprint, so editing the policy safely invalidates the cached reviewer lineage.
+
+Alongside your configured entries, the guardian always receives a `SESSION ENVIRONMENT` section captured once at session start: the working directory, repository root, and the `git remote -v` baseline. Those remotes are within the session's trust boundary; a remote added or repointed mid-session is not — which pairs with the default `git remote add|set-url` gate rule, giving the guardian a baseline to judge those commands against. In a non-repository directory the section says exactly that, so no repository trust is assumed.
+
+The precedence tiers are prompt-enforced, like Claude Code's own; the mechanically enforced hard boundary is the `deny` rule level.
+
+### `/auto-permissions setup`
+
+The wizard drafts this configuration for you. It scans the current project — git remotes, `AGENTS.md`/`README.md`, lockfiles and the registry hosts inside them — and recent session files under `$PI_CODING_AGENT_DIR/sessions` for **command strings only** (hosts, registries, buckets, CLI names — never user messages, matching Claude Code's privacy line for `/auto-mode-setup`). One model call turns the facts into proposed `guardianPolicy.environment` entries plus suggested `.pi/trusted-ops` groups, rendered for accept-or-discard as a whole. Accepting appends the environment entries through the narrow config writer (nothing else in the file is rewritten); the trusted-ops suggestions are display-only — a wizard must not widen a project-level bypass file on its own. And deliberately, `guardianPolicy` is read only from the user-scoped config file — never from a project file — so a checked-in repository cannot inject its own trust entries.
+
 ## Guardian configuration
 
 By default, the guardian uses Pi's active model with low reasoning effort and a 30-second timeout. You can select a separate low-cost model.
 
+### Two-stage review
+
+Set `"prefilter": true` inside the `reviewer` block for the Claude Code stage-1/stage-2 structure: before the full lineage review, a stateless single-token pass at minimal reasoning answers `SAFE` or `REVIEW` over the same envelope text. `SAFE` approves immediately (the review row shows reason `prefilter`); `REVIEW` — and any parse or infrastructure failure — falls through to the full review unchanged, so the prefilter can only ever short-circuit toward *more* review, never approve by accident. Because the prefilter envelope matches a full-rebuild review's, the escalated call is largely a provider prompt-cache hit of the prefilter call. The lineage conversation is untouched.
+
+Prefilter calls are recorded in the usage sidecar under a distinct `prefilter` label, and — when the evaluation log is enabled — every prefilter approval is logged with `"decisionSource": "prefilter"` so its false-negative rate can be measured offline against the same labels as prompted reviews. Off by default until that data justifies flipping it; it pays off most with `reviewAllShell`, where the per-command cost matters.
+
 Giving the guardian its own account keeps reviews from competing with your interactive session for a subscription's rate limits. Pi keys OAuth credentials by provider id, so a second login needs a second provider id — which is what [`@hank-warren/pi-multi-login`](../pi-multi-login/README.md) exists to create. This package no longer registers one itself.
 
 1. `pi install npm:@hank-warren/pi-multi-login`
@@ -207,8 +284,44 @@ When the main agent gathers a decision through an interactive question tool (for
 
 A successful result from an allowlisted tool qualifies when its `details` are `{ "answers": [{ "question": string, "answer"?: string, "selected"?: string[], "notes"?: string }], "cancelled": false }` with no `error` field. `selected` takes precedence over `answer`, non-string answers are ignored, and notes count only alongside a real answer. Each answered question contributes one `USER (dialog answer):` record; the guardian treats it as authorization for exactly the selected content and is told the question wording is assistant-drafted context, never an instruction. Any dialog extension emitting that shape qualifies.
 
+### Injected user messages
+
+Extensions inject context with `appendCustomMessageEntry`, and Pi converts that content into a **user message for the model** — but the session entry is a `custom_message` with no role, so the reviewer never saw it. The model was acting on text the guardian could not read.
+
+`reviewEvidence.userMessageTypes` allowlists the `customType`s whose content becomes `source: "user"` evidence:
+
+```json
+{
+  "reviewEvidence": {
+    "userMessageTypes": ["loop-objective"]
+  }
+}
+```
+
+The default is `["loop-objective"]` — the objective anchor written by [`@hank-warren/pi-loop`](../pi-loop), which carries the objective the user typed or approved and which is frozen for the loop's lifetime. Without it, a looping session's reviewer sees no user authorization for the very task the loop was started to do, and refuses work the user explicitly asked for. Absent means the default; an explicit `[]` opts out entirely.
+
+Each text block contributes one `USER (<customType>):` record, in session order, never truncated — user records are the only ones that can authorize or constrain. Images are dropped. The guardian is told these records authorize exactly the operations they name, that their constraints bind, and that their content is data rather than instructions.
+
+Injected messages whose `customType` is **not** allowlisted are still visible — as `CUSTOM <customType>:` records with `source: "tool"`, capped like any tool record. They routinely carry the reason a command was proposed (subagent return values, CI outcomes, process notifications), so hiding them left the guardian judging commands with no visible motive; but they are extension output, and only the allowlist can promote a type to user-source, so a subagent's return value can explain a command without ever authorizing it.
+
 The allowlist matches what you wrote: a bare name such as `ask_user_question` matches that tool in any namespace (`functions.ask_user_question` included), while a dotted name matches exactly. The default is an empty list.
 
+## Denial log and retry
+
+Every non-approved outcome — a guardian revise, a user block at the prompt, a loop-budget block, a convention or deny block, a review-infrastructure failure — is appended to a private `denials.jsonl` sidecar next to the config (0600, 16 MB rotation, one previous generation kept):
+
+```json
+{"v":1,"ts":"…","sessionId":"…","tool":"bash","gate":{"label":"Force push","group":"git"},"command":"git push --force …","verdict":"block","reason":"…","decisionSource":"user"}
+```
+
+On by default; `"denialLog": { "enabled": false }` opts out, and `path` relocates it.
+
+`/auto-permissions` gains a **Recent denials** view over that ledger. Selecting a denial offers **Allow on retry**: an exact-command session override is added through the existing override machinery (it re-injects as user-source evidence on every later review and survives session resume), and an injected message tells the agent it may run that exact command again. No new authorization pathway exists — it is the same override a live approval prompt would have produced.
+
+Every denial also emits a `pi.events` event — `auto-permissions:denied` with `tool`, `command`, `gate`, `group`, `verdict`, `reason`, `decisionSource` — the pi-native equivalent of Claude Code's `PermissionDenied` hook, for other extensions to react to. Like that hook, it cannot reverse a denial.
+
+Permission overrides now also persist as custom session entries (the way the loop revise budget does), so a resumed session keeps the user's earlier allow decisions and standing block constraints instead of forgetting them.
+
 ## Prompted-review evaluation log
 
 Auto Permissions can append a private JSONL regression record whenever the guardian asks for confirmation and the user gives explicit feedback:
@@ -305,7 +418,7 @@ git
 gh
 ```
 
-Group names come from your configured rules. A trusted group bypasses all review for that group, so use it only in projects you control.
+Group names come from your configured rules. A trusted group bypasses guarded review and convention blocks for that group, so use it only in projects you control. Deny rules are never bypassed: `.pi/trusted-ops` is a project-scoped file, and a checked-in file must not be able to disarm a hard policy boundary.
 
 ## Subagent sessions
 
@@ -349,6 +462,8 @@ Pi Auto Permissions is a permission layer for normal agent behavior. It is not a
 
 `reviewEvidence.userAnswerTools` widens what counts as user authorization: any code that can record a tool result under an allowlisted tool name can mint `USER (dialog answer)` evidence. Allowlist only tool names served by extensions you trust.
 
+`reviewEvidence.userMessageTypes` widens it the same way, and is why it is an allowlist rather than "project every injected message": any installed extension can append a custom message under any `customType`, so a blanket rule would let any of them mint user authorization. Allowlist only types written by extensions you trust.
+
 ## License
 
 MIT

package/config-writer.ts

@@ -26,6 +26,12 @@ export interface ReviewerBlock {
 export interface ConfigPatch {
   enabled?: boolean;
   reviewer?: ReviewerBlock;
+  /**
+   * Entries to append to `guardianPolicy.environment` (the setup wizard's
+   * accept path). Deduplicated against what is already there; every other
+   * `guardianPolicy` list and unrelated key is left exactly as written.
+   */
+  appendEnvironment?: string[];
 }
 
 const DEFAULT_INDENT = "  ";
@@ -82,14 +88,36 @@ export function patchAutoPermissionsConfig(
     else merged.enabled = false;
   }
   if (patch.reviewer !== undefined) {
+    // Preserve file-only reviewer keys the menu does not edit (prefilter):
+    // this writer must never silently drop what the human wrote by hand.
+    const existingReviewer = merged.reviewer && typeof merged.reviewer === "object" && !Array.isArray(merged.reviewer)
+      ? merged.reviewer as Record<string, unknown>
+      : {};
     merged.reviewer = {
       provider: patch.reviewer.provider,
       model: patch.reviewer.model,
       reasoningEffort: patch.reviewer.reasoningEffort,
       timeoutMs: patch.reviewer.timeoutMs,
+      ...(existingReviewer.prefilter !== undefined ? { prefilter: existingReviewer.prefilter } : {}),
     };
   }
 
+  if (patch.appendEnvironment !== undefined && patch.appendEnvironment.length > 0) {
+    const policy = merged.guardianPolicy && typeof merged.guardianPolicy === "object" && !Array.isArray(merged.guardianPolicy)
+      ? merged.guardianPolicy as Record<string, unknown>
+      : {};
+    const existingEnvironment = Array.isArray(policy.environment)
+      ? policy.environment.filter((entry): entry is string => typeof entry === "string")
+      : [];
+    policy.environment = [
+      ...new Set([
+        ...existingEnvironment,
+        ...patch.appendEnvironment.map((entry) => entry.trim()).filter(Boolean),
+      ]),
+    ];
+    merged.guardianPolicy = policy;
+  }
+
   const payload = `${JSON.stringify(merged, null, detectIndent(existing))}\n`;
   const temporary = `${path}.${pid}.tmp`;
   mkdirSync(dirname(path), { recursive: true });

package/config.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import type { Gate, GateLevel } from "./gates.js";
+import { DEFAULT_RULES } from "./default-rules.js";
 import { AUTO_PERMISSIONS_SYSTEM_PROMPT } from "./review.js";
 
 export const CONFIG_FILENAME = "pi-auto-permissions/config.json";
@@ -33,12 +34,43 @@ export interface AutoPermissionsConfig {
     model: string;
     reasoningEffort: ReasoningEffort;
     timeoutMs: number;
+    /**
+     * Two-stage review: a stateless single-token SAFE/REVIEW pass at minimal
+     * reasoning before the full lineage review. SAFE approves; REVIEW and
+     * every parse or infrastructure failure fall through to the full review
+     * (fail closed). Opt-in until evaluation-log data justifies default-on;
+     * recommended together with `reviewAllShell`.
+     */
+    prefilter: boolean;
   };
   systemPrompt: string;
   systemPromptSource: SystemPromptSource;
   reviewEvidence: {
     projectInstructions: boolean;
     userAnswerTools: string[];
+    /**
+     * `custom_message` customTypes whose content counts as user-source
+     * evidence.
+     *
+     * Extensions inject context with `appendCustomMessageEntry`, and Pi turns
+     * that content into a user message for the model — but the session entry
+     * is a `custom_message`, not a message with a role, so the evidence
+     * collector never saw it. The model read the text as the user's; the
+     * reviewer read nothing at all.
+     *
+     * pi-loop's objective is the case that matters: user-typed or
+     * user-approved, frozen at start, and the whole reason the session is
+     * doing what it is doing. Reviewing a looping session without it means
+     * refusing work the user explicitly asked for — observed live, on a
+     * `git worktree add` whose objective said "in a worktree branched off
+     * origin/main".
+     *
+     * An allowlist rather than "project every custom message", for the same
+     * reason `userAnswerTools` is one: any installed extension can append a
+     * custom message, and a blanket rule would let any of them mint user
+     * authorization. Naming the types keeps that an explicit choice.
+     */
+    userMessageTypes: string[];
     /** Per-record caps at evidence creation; 0 disables. User records are never truncated. */
     toolRecordMaxChars: number;
     assistantRecordMaxChars: number;
@@ -54,7 +86,37 @@ export interface AutoPermissionsConfig {
     enabled: boolean;
     path: string;
   };
+  /** Every non-approved outcome, for the Recent denials view. Default on. */
+  denialLog: {
+    enabled: boolean;
+    path: string;
+  };
   rules: Gate[];
+  /**
+   * Review every bash command that matches no rule under the generic
+   * `shell command` gate (`ALL_SHELL_GATE`). Default false: the ruleset is
+   * the reviewed surface. The trade is deliberate and mirrors Claude Code's
+   * `classifyAllShell` — full coverage for one guardian call per command.
+   */
+  reviewAllShell: boolean;
+  /**
+   * Prose trust configuration, appended to the reviewer policy prompt as a
+   * labeled section (outside `systemPrompt`, so customized prompt files still
+   * receive it). Entries are natural-language rules — "write them the way you
+   * would describe your infrastructure to a new engineer" — mirroring Claude
+   * Code's `autoMode.environment`/`allow`/`soft_deny`/`hard_deny`.
+   *
+   * Each list is independent: setting one leaves the others (and the built-in
+   * decision table, which stays the default policy) intact. Deliberately
+   * user-scoped-config only — no project-file read — closing by construction
+   * the checked-in-file injection hole CC patched in v2.1.207.
+   */
+  guardianPolicy: {
+    environment: string[];
+    allow: string[];
+    softDeny: string[];
+    hardDeny: string[];
+  };
   ui: {
     enabled: boolean;
     resultDisplayMs: number;
@@ -109,11 +171,13 @@ function compileRule(value: unknown, index: number): Gate {
   const flags = input.flags === undefined ? "i" : input.flags;
   if (typeof flags !== "string") throw new Error(`rules[${index}].flags must be a string`);
   const level: GateLevel = input.level === undefined ? "guarded" : input.level as GateLevel;
-  if (level !== "guarded" && level !== "convention") {
-    throw new Error(`rules[${index}].level must be guarded or convention`);
+  if (level !== "guarded" && level !== "convention" && level !== "deny") {
+    throw new Error(`rules[${index}].level must be guarded, convention, or deny`);
   }
   const message = optionalString(input.message, `rules[${index}].message`);
-  if (level === "convention" && !message) throw new Error(`rules[${index}].message is required for convention rules`);
+  if ((level === "convention" || level === "deny") && !message) {
+    throw new Error(`rules[${index}].message is required for ${level} rules`);
+  }
 
   return {
     pattern: new RegExp(pattern, flags),
@@ -124,6 +188,36 @@ function compileRule(value: unknown, index: number): Gate {
   };
 }
 
+/** The literal a `rules` array uses to splice the built-in ruleset in place. */
+export const DEFAULT_RULES_TOKEN = "$defaults";
+
+/**
+ * Compile an authored `rules` array, splicing `defaults` wherever the literal
+ * string `"$defaults"` appears (mirroring Claude Code's splice semantics: the
+ * built-ins keep updating across releases, and custom entries can sit before
+ * or after them). The token may appear at most once — a second occurrence is
+ * far more likely a copy-paste error than a request for double gating.
+ *
+ * The caller handles the other two shapes: an absent `rules` key means the
+ * defaults are active, and an authored array without the token is a full
+ * replacement (an explicit `[]` gates nothing).
+ */
+export function expandRules(rawRules: readonly unknown[], defaults: readonly Gate[]): Gate[] {
+  const rules: Gate[] = [];
+  let spliced = false;
+  for (let index = 0; index < rawRules.length; index++) {
+    const value = rawRules[index];
+    if (value === DEFAULT_RULES_TOKEN) {
+      if (spliced) throw new Error(`rules may contain "${DEFAULT_RULES_TOKEN}" at most once`);
+      spliced = true;
+      rules.push(...defaults);
+      continue;
+    }
+    rules.push(compileRule(value, index));
+  }
+  return rules;
+}
+
 function resolvePrompt(
   raw: Record<string, unknown>,
   path: string,
@@ -141,6 +235,16 @@ function resolvePrompt(
   return { prompt, source: { kind: "file", path: resolved } };
 }
 
+/**
+ * The one injected message type trusted out of the box.
+ *
+ * pi-loop's kickoff anchor (`LOOP_ANCHOR_MESSAGE_TYPE`), which carries the
+ * objective the user typed or approved. Named as a plain string, the way
+ * `loop-context.ts` names `PI_LOOP_ACTIVE`: no import, no dependency, and no
+ * behaviour at all when pi-loop is not installed.
+ */
+export const DEFAULT_USER_MESSAGE_TYPES = ["loop-objective"] as const;
+
 const EVIDENCE_PRUNING_DEFAULTS = {
   toolRecordMaxChars: 500,
   assistantRecordMaxChars: 1000,
@@ -159,7 +263,12 @@ function resolvePruningKnob(evidence: Record<string, unknown>, name: keyof typeo
 
 function resolveReviewEvidence(raw: Record<string, unknown>): AutoPermissionsConfig["reviewEvidence"] {
   if (raw.reviewEvidence === undefined) {
-    return { projectInstructions: false, userAnswerTools: [], ...EVIDENCE_PRUNING_DEFAULTS };
+    return {
+      projectInstructions: false,
+      userAnswerTools: [],
+      userMessageTypes: [...DEFAULT_USER_MESSAGE_TYPES],
+      ...EVIDENCE_PRUNING_DEFAULTS,
+    };
   }
   if (!raw.reviewEvidence || typeof raw.reviewEvidence !== "object" || Array.isArray(raw.reviewEvidence)) {
     throw new Error("reviewEvidence must be an object");
@@ -172,9 +281,22 @@ function resolveReviewEvidence(raw: Record<string, unknown>): AutoPermissionsCon
   if (!Array.isArray(rawTools) || rawTools.some((tool) => typeof tool !== "string" || !tool.trim())) {
     throw new Error("reviewEvidence.userAnswerTools must be an array of non-empty strings");
   }
+  // Absent means the default, and an explicit empty array means none: a user
+  // who wants the loop objective out of the envelope must be able to say so,
+  // and cannot if omission and `[]` are the same thing.
+  const rawMessageTypes = evidence.userMessageTypes === undefined
+    ? [...DEFAULT_USER_MESSAGE_TYPES]
+    : evidence.userMessageTypes;
+  if (
+    !Array.isArray(rawMessageTypes)
+    || rawMessageTypes.some((type) => typeof type !== "string" || !type.trim())
+  ) {
+    throw new Error("reviewEvidence.userMessageTypes must be an array of non-empty strings");
+  }
   return {
     projectInstructions: evidence.projectInstructions === true,
     userAnswerTools: [...new Set((rawTools as string[]).map((tool) => tool.trim()))],
+    userMessageTypes: [...new Set((rawMessageTypes as string[]).map((type) => type.trim()))],
     toolRecordMaxChars: resolvePruningKnob(evidence, "toolRecordMaxChars"),
     assistantRecordMaxChars: resolvePruningKnob(evidence, "assistantRecordMaxChars"),
     compactionRecordMaxChars: resolvePruningKnob(evidence, "compactionRecordMaxChars"),
@@ -224,6 +346,56 @@ function resolveUsageLog(
   return { enabled, path: isAbsolute(expanded) ? expanded : resolve(dirname(configFilePath), expanded) };
 }
 
+const GUARDIAN_POLICY_KEYS = ["environment", "allow", "softDeny", "hardDeny"] as const;
+
+function resolveGuardianPolicy(raw: Record<string, unknown>): AutoPermissionsConfig["guardianPolicy"] {
+  const empty = { environment: [], allow: [], softDeny: [], hardDeny: [] };
+  if (raw.guardianPolicy === undefined) return empty;
+  if (!raw.guardianPolicy || typeof raw.guardianPolicy !== "object" || Array.isArray(raw.guardianPolicy)) {
+    throw new Error("guardianPolicy must be an object");
+  }
+  const policy = raw.guardianPolicy as Record<string, unknown>;
+  for (const key of Object.keys(policy)) {
+    if (!(GUARDIAN_POLICY_KEYS as readonly string[]).includes(key)) {
+      throw new Error(`guardianPolicy.${key} is not a recognized list (use environment, allow, softDeny, hardDeny)`);
+    }
+  }
+  const resolveList = (key: typeof GUARDIAN_POLICY_KEYS[number]): string[] => {
+    const value = policy[key];
+    if (value === undefined) return [];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim())) {
+      throw new Error(`guardianPolicy.${key} must be an array of non-empty strings`);
+    }
+    return [...new Set((value as string[]).map((entry) => entry.trim()))];
+  };
+  return {
+    environment: resolveList("environment"),
+    allow: resolveList("allow"),
+    softDeny: resolveList("softDeny"),
+    hardDeny: resolveList("hardDeny"),
+  };
+}
+
+function resolveDenialLog(
+  raw: Record<string, unknown>,
+  configFilePath: string,
+): AutoPermissionsConfig["denialLog"] {
+  const defaultPath = resolve(dirname(configFilePath), "denials.jsonl");
+  if (raw.denialLog === undefined) return { enabled: true, path: defaultPath };
+  if (!raw.denialLog || typeof raw.denialLog !== "object" || Array.isArray(raw.denialLog)) {
+    throw new Error("denialLog must be an object");
+  }
+  const denialLog = raw.denialLog as Record<string, unknown>;
+  if (denialLog.enabled !== undefined && typeof denialLog.enabled !== "boolean") {
+    throw new Error("denialLog.enabled must be boolean");
+  }
+  const enabled = denialLog.enabled !== false;
+  const configuredPath = optionalString(denialLog.path, "denialLog.path");
+  if (!configuredPath) return { enabled, path: defaultPath };
+  const expanded = configuredPath.startsWith("~/") ? join(homedir(), configuredPath.slice(2)) : configuredPath;
+  return { enabled, path: isAbsolute(expanded) ? expanded : resolve(dirname(configFilePath), expanded) };
+}
+
 function resolveUi(raw: Record<string, unknown>): AutoPermissionsConfig["ui"] {
   if (raw.ui === undefined) return { enabled: true, resultDisplayMs: 2500, placement: "widget" };
   if (!raw.ui || typeof raw.ui !== "object" || Array.isArray(raw.ui)) {
@@ -266,14 +438,29 @@ function resolveReviewer(raw: Record<string, unknown>): AutoPermissionsConfig["r
   ) {
     throw new Error("reviewer.timeoutMs must be an integer between 1000 and 300000");
   }
-  return { provider, model, reasoningEffort, timeoutMs: Number(timeoutMs) };
+  if (reviewer.prefilter !== undefined && typeof reviewer.prefilter !== "boolean") {
+    throw new Error("reviewer.prefilter must be boolean");
+  }
+  return {
+    provider,
+    model,
+    reasoningEffort,
+    timeoutMs: Number(timeoutMs),
+    prefilter: reviewer.prefilter === true,
+  };
 }
 
 export function loadAutoPermissionsConfig(path = autoPermissionsConfigPath()): AutoPermissionsConfig {
   const raw = readObject(path);
   if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") throw new Error("enabled must be boolean");
+  if (raw.reviewAllShell !== undefined && typeof raw.reviewAllShell !== "boolean") {
+    throw new Error("reviewAllShell must be boolean");
+  }
   if (raw.rules !== undefined && !Array.isArray(raw.rules)) throw new Error("rules must be an array");
-  const customRules = (raw.rules ?? []).map(compileRule);
+  // Absent means the built-in ruleset is active; an authored array replaces it
+  // entirely unless it splices "$defaults" back in; an explicit [] gates
+  // nothing. Existing configs with their own rules keep exactly their rules.
+  const rules = raw.rules === undefined ? [...DEFAULT_RULES] : expandRules(raw.rules, DEFAULT_RULES);
   const prompt = resolvePrompt(raw, path);
 
   return {
@@ -284,7 +471,10 @@ export function loadAutoPermissionsConfig(path = autoPermissionsConfigPath()): A
     reviewEvidence: resolveReviewEvidence(raw),
     evaluationLog: resolveEvaluationLog(raw, path),
     usageLog: resolveUsageLog(raw, path),
-    rules: customRules,
+    denialLog: resolveDenialLog(raw, path),
+    rules,
+    reviewAllShell: raw.reviewAllShell === true,
+    guardianPolicy: resolveGuardianPolicy(raw),
     ui: resolveUi(raw),
   };
 }