auto-permission-system 3.6.0 → 3.8.0

package/skills/auto-permission-system/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: auto-permission-system
-description: Use this skill when the user asks about the auto-permission-system extension, security policy configuration, why a tool call was blocked, how to add an allow-list entry, or how to configure sandbox behavior. Covers the two-layer sandbox (OS-level bash sandbox and in-process tool guard), policy file locations and fields, ask-tier prompt options, absolute-deny paths, escape hatches (--yolo, --no-sandbox, /permission-mode → YOLO), the audit log, and common tasks like allowing a new domain or write path.
+description: Use this skill when the user asks about auto-permission-system, security for Pi, permission system for Pi, how to secure Pi, Cloud auto mode for Pi, security policy configuration, why a tool call was blocked, how to add an allow-list entry, or how to configure sandbox behavior. Covers the two-layer sandbox (OS-level bash sandbox and in-process tool guard), policy file locations and fields, Cloud auto mode preset (sandbox.cloud.json), ask-tier prompt options, absolute-deny paths, escape hatches (--yolo, --no-sandbox, /permission-mode → YOLO), the audit log, and common tasks like allowing a new domain or write path.
 ---
 
-# Pi Security — Skill
+# Security for Pi (Pi Permission System) — Skill
 
-Use this skill when the user asks about the auto-permission-system extension, security policy configuration, why a tool call was blocked, how to add an allow-list entry, or how to configure sandbox behavior.
+Use this skill when the user asks about the auto-permission-system extension, security for Pi, permission system for Pi, how to secure Pi, or configuring Cloud auto mode for Pi.
 
 ## What this extension does
 
@@ -19,15 +19,16 @@ Wraps the `bash` tool with `sandbox-exec` (macOS) or `bubblewrap` (Linux). Block
 **Layer 2 — In-process tool guard**
 Hooks `tool_call` for `read`, `grep`, `find`, `ls`, `write`, `edit`, `fetch_content`, `web_search`, `get_search_content`. Applies the same policy file as Layer 1. For `grep`, `find` and `ls` the search root is checked like a `read` path. A `tool_result` hook also removes `grep` output lines from denied files beneath an allowed root (for example a `.env` deep in the tree); approving the root does not approve those files. When a call is blocked, shows an interactive prompt with persistence options.
 
-**Layer 3 — Subagent posture**
-When `ctx.hasUI === false` (subagents, `-p`, JSON mode), applies the `subagent.network` policy: `allow` (default) | `deny` | `research-only`.
+**Layer 3 — Subagent posture & Cloud Auto Mode**
+When `ctx.hasUI === false` (subagents, `-p`, JSON mode, CI/CD runs), applies the `subagent.network` policy: `allow` (default) | `deny` | `research-only`. In Cloud Auto Mode, unapproved prompts fail closed.
 
 ## Policy files
 
 Merged in order (later wins):
 1. `sandbox.default.json` — shipped baseline (`outsideProject.read: "ask"`, full `denyRead`/`denyWrite`, `modelDenyRead`)
-2. `~/.pi/agent/extensions/sandbox.json` — global user policy
-3. `<cwd>/.pi/sandbox.json` — project-local overrides (also written by ask-tier prompts)
+2. `sandbox.cloud.json` — shipped Cloud Auto Mode preset for headless, Docker, and CI/CD runs (`strictAllowlist: true`, `outsideProject.read: "deny"`)
+3. `~/.pi/agent/extensions/sandbox.json` — global user policy
+4. `<cwd>/.pi/sandbox.json` — project-local overrides (also written by ask-tier prompts)
 
 A higher layer only states what it changes; absent keys keep the layer below. A **trusted** project may loosen the baseline; an **untrusted** project may only tighten it (ADR-013). You do not need a global file for good defaults (ADR-016).
 
@@ -50,6 +51,14 @@ A higher layer only states what it changes; absent keys keep the layer below. A
     "denyWrite": [".env", "*.pem"]   // Layer 1 + 2: always blocked
   },
   "subagent": { "network": "allow" },
+  "mcp": {                           // Advanced Secure MCP gate tuning (ADR-032)
+    "allowTools": ["mcp__diffusion_studio__context"],  // exact names that never ask
+    "allowPrefixes": ["mcp__ticktick__get_"],          // name prefixes that never ask
+    "askTools": [],                   // exact names that always ask
+    "trustAnnotations": false,        // true = a server's readOnlyHint allows without asking
+    "allowSimpleUpdates": true,       // narrow field updates skip the ask
+    "askThreshold": 30                // risk score at which a call asks (lower = stricter)
+  },
   "commands": {
     "ask": ["printenv", "env", "/proc/*/environ"]  // bash: ask before these (they can print env tokens)
   },
@@ -88,7 +97,7 @@ A **network** (domain) ask keeps the same rows, but the *unanswered* default fli
 
 For a Layer 1 bash **write** blocked after the command already ran, `yes — this once` re-runs the command once with the offending path's parent folder allowed for that invocation only (never saved); the same folder is not offered again within that invocation, and `denyWrite` still wins over the grant. The block is recognized from the error output either way it is reported — `EPERM`/`Operation not permitted` on macOS, `EROFS`/`Read-only file system` on Linux (ADR-022) — and a refused write is never offered as a read grant. If the output never names the operand, there is nothing to attribute and no prompt, so the command is simply refused.
 
-Every prompt waits **15 seconds** by default and shows it live as `Default: … (Ns)` under the body. For file reads/writes no answer means the safe default: **block / deny**, and Esc blocks. For a network ask, an unanswered countdown means **allow once** (Esc still denies) — ADR-024. In the TUI the `Default:` line disappears as soon as you press ↑/↓ and the timer restarts, so the hint never competes with an active choice (ADR-031).
+Every prompt waits **15 seconds** by default and shows it live as `Default: … (Ns)` under the body. For file reads/writes no answer means the safe default: **block / deny**, and Esc blocks. For a network ask, an unanswered countdown means **allow once** (Esc still denies) — ADR-024. In the TUI the `Default:` line disappears as soon as you press ↑/↓ and the timer restarts, so the hint never competes with an active choice (ADR-031). The prompt is keyboard-only (ADR-036): ↑/↓ move the highlight, Enter selects, Esc cancels — a mouse click or wheel over the prompt does nothing.
 
 The same options apply to a bash command whose network request reaches a host outside `allowedDomains` (ADR-023), with the countdown default and live footer from ADR-024/ADR-031: `No` / `Yes, just this once` / `Yes, all in group for this session` / `Yes, always…`, and an untouched countdown counts as allow-once. Because the sandbox proxy asks per connection, `Allow (default)` covers that bash command rather than one connection — redirects and parallel connections to the same host do not re-prompt. A host in `deniedDomains`, or `network.strictAllowlist: true`, is blocked outright: the prompt never appears. A remembered host is written to `overrides.allowDomains` and takes effect immediately, so the waiting request completes without a retry. Prompts from both layers are serialized through one queue (`src/ui/ask-flow.ts`), so two unknown hosts cannot replace each other's selector and hang the waiting connection.
 
@@ -103,7 +112,7 @@ The same options apply to a bash command whose network request reaches a host ou
 - **`default`** (shipped) — rules only. No content inspection.
 - **`advanced-secure`** (recommended) — adds secret/credential detection, and **only adds asks or blocks** (never loosens):
   - file reads whose name looks like a credential store ask before the read;
-  - risky `mcp__<server>__<tool>` calls ask before they run;
+  - risky `mcp__<server>__<tool>` calls ask before they run. The gate ignores the `mcp__<server>__` namespace, takes the operation from the head verb of the name (or the first verb of the description), and asks for destructive names, mutating names (`update_*`, `create_*`, `run_*`, `evaluate_*`), and destructive arguments (SQL `DELETE`/`UPDATE` without `WHERE`, `rm -rf`, `*` targets, HTTP `DELETE`, production targets). A documented tool with an unclassified name (`context`, `capture`, `logs`) does not ask; a tool with **no description** counts as opaque and does. Tune it under `mcp` in `sandbox.json` (ADR-032): `allowTools` / `allowPrefixes` skip asks, `askTools` forces them, `trustAnnotations` lets a server's `readOnlyHint` allow the call, `askThreshold` moves the score line (default 30). An untrusted project file may only tighten it (add `askTools`, lower `askThreshold`, turn `allowSimpleUpdates`/`trustAnnotations` off).
   - before any tool/command/file output reaches the model, a secret-like hit shows the file and each detected line as `lineNo: text`, with two choices — **No, keep private** or **Yes, allow**. No, keep private withholds the output and tells the model it was withheld because it may contain sensitive information (not a failure, not an empty result).
 
 Switch with `/permission-mode`; all three modes are saved to the global `sandbox.json` and reflected in the footer's sandbox chip (`Sandbox: 🧠 N domains, M paths` for advanced-secure, `Sandbox: 🔒 …` for default). An untrusted project may move the mode **up** (toward stricter), never down: it cannot turn on YOLO or turn off Advanced Secure. The third choice, **YOLO**, disables every layer; the chip reads `⚠️ YOLO — all security layers disabled` until you pick another mode (ADR-020).
@@ -143,6 +152,13 @@ Without restarting, `/permission-mode` → **YOLO** turns every layer off in one
 
 **Allow writes to a new path** — same pattern with `allowWrite`.
 
+**Allow an MCP tool** — in Advanced Secure mode, a `mcp__<server>__<tool>` call that keeps asking can be allowed without weakening anything else:
+```json
+// ~/.pi/agent/extensions/sandbox.json  (global)
+{ "mcp": { "allowPrefixes": ["mcp__ticktick__get_"], "allowTools": ["mcp__diffusion_studio__export"] } }
+```
+`allowTools` matches exact names, `allowPrefixes` matches the start (case-insensitive). Detected destructive calls still ask unless an exact `allowTools` entry names them. `"trustAnnotations": true` lets servers that mark a tool `readOnlyHint` skip the ask, and a project's `mcp` file may only tighten (add `askTools`, lower `askThreshold`, turn `allowSimpleUpdates`/`trustAnnotations` off) until you trust it.
+
 **View recent blocks** — run `/security` and read the audit section, or:
 ```bash
 tail -20 ~/.pi/agent/audit.log | python3 -m json.tool

package/src/core/grep-filter.ts

@@ -3,7 +3,7 @@
  * `path-N- text` for a context line. The separator is the same on both sides
  * of the line number, which keeps paths containing `-` or `:` parseable.
  */
-const GREP_LINE = /^(.+?)([:-])(\d+)\2 /;
+const GREP_LINE_RE = /^(.+?)([:-])(\d+)\2 /;
 
 export interface GrepFilterResult {
 	text: string;
@@ -20,26 +20,26 @@ export interface GrepFilterResult {
  * per path.
  */
 export function filterGrepOutput(text: string, isDenied: (printedPath: string) => boolean): GrepFilterResult {
-	const cache = new Map<string, boolean>();
+	const deniedByPath = new Map<string, boolean>();
 	const removedFiles = new Set<string>();
 	let removedLines = 0;
-	const kept: string[] = [];
+	const keptLines: string[] = [];
 	for (const line of text.split("\n")) {
-		const m = GREP_LINE.exec(line);
-		if (m) {
-			const file = m[1];
-			let denied = cache.get(file);
+		const match = GREP_LINE_RE.exec(line);
+		if (match) {
+			const printedPath = match[1];
+			let denied = deniedByPath.get(printedPath);
 			if (denied === undefined) {
-				denied = isDenied(file);
-				cache.set(file, denied);
+				denied = isDenied(printedPath);
+				deniedByPath.set(printedPath, denied);
 			}
 			if (denied) {
 				removedLines++;
-				removedFiles.add(file);
+				removedFiles.add(printedPath);
 				continue;
 			}
 		}
-		kept.push(line);
+		keptLines.push(line);
 	}
-	return { text: kept.join("\n"), removedLines, removedFiles: [...removedFiles] };
+	return { text: keptLines.join("\n"), removedLines, removedFiles: [...removedFiles] };
 }

package/src/core/index.ts

@@ -5,13 +5,16 @@
 export * from "./policy/defaults";
 export * from "./policy/domains";
 export * from "./policy/default-file";
-export * from "./policy/files";
+export * from "./policy/policy-file";
 export * from "./policy/merge";
 export * from "./policy/mode";
+export * from "./policy/overrides";
+export * from "./policy/paths";
 export * from "./policy/patterns";
 export * from "./policy/classify";
 export * from "./policy/commands";
 export * from "./policy/fence";
+export * from "./policy/subagent";
 export * from "./grep-filter";
 export * from "./trust";
 export * from "./user-named";

package/src/core/policy/classify.ts

@@ -1,6 +1,18 @@
+/**
+ * The filesystem slice both layers read, plus the outside-project boundary
+ * (ADR-012) it is enforced through. Pure: no pi, no OS side effects.
+ */
+
 import { matchesPolicyPattern } from "./patterns";
 
-/** The filesystem slice both layers read, with the Layer-2-only fields. */
+/** Erasable enum for `filesystem.outsideProject.read`. */
+export const ReadPosture = {
+	Allow: "allow",
+	Ask: "ask",
+	Deny: "deny",
+} as const;
+export type ReadPosture = (typeof ReadPosture)[keyof typeof ReadPosture];
+
 export interface FilesystemPolicy {
 	denyRead: readonly string[];
 	allowWrite: readonly string[];
@@ -8,23 +20,23 @@ export interface FilesystemPolicy {
 	allowRead?: readonly string[];
 	/** Paths that prompt on read instead of being hard-denied (ADR-019). */
 	askRead?: readonly string[];
-	/** Reads outside the project: "allow" (default), "ask" or "deny" (ADR-012). */
-	outsideProject?: { read?: "allow" | "ask" | "deny"; allowRead?: string[] };
+	/** Reads outside the project: `allow` (default), `ask` or `deny` (ADR-012). */
+	outsideProject?: { read?: ReadPosture; allowRead?: string[] };
 }
 
-export function outsideProjectMode(fs: FilesystemPolicy): "allow" | "ask" | "deny" {
-	return fs.outsideProject?.read ?? "allow";
+export function outsideProjectMode(filesystem: FilesystemPolicy): ReadPosture {
+	return filesystem.outsideProject?.read ?? ReadPosture.Allow;
 }
 
 /**
  * Whether `absPath` is an outside-the-project read the policy wants to gate:
  * outside cwd, not under an allowWrite / allowRead / outsideProject.allowRead
- * root, and mode !== "allow". Pure; mirrors Layer 2's outsideProjectReason for
+ * root, and mode !== `allow`. Pure; mirrors Layer 2's outsideProjectReason for
  * callers (and tests) that cannot import security-guard.ts.
  */
-export function outsideProjectReadDenied(absPath: string, cwd: string, home: string, fs: FilesystemPolicy): boolean {
-	if (outsideProjectMode(fs) === "allow") return false;
+export function outsideProjectReadDenied(absPath: string, cwd: string, home: string, filesystem: FilesystemPolicy): boolean {
+	if (outsideProjectMode(filesystem) === ReadPosture.Allow) return false;
 	if (absPath === cwd || absPath.startsWith(`${cwd}/`)) return false;
-	const allowed = [...fs.allowWrite, ...(fs.allowRead ?? []), ...(fs.outsideProject?.allowRead ?? [])];
-	return !allowed.some((pat) => matchesPolicyPattern(absPath, pat, cwd, home));
+	const allowed = [...filesystem.allowWrite, ...(filesystem.allowRead ?? []), ...(filesystem.outsideProject?.allowRead ?? [])];
+	return !allowed.some((pattern) => matchesPolicyPattern(absPath, pattern, cwd, home));
 }

package/src/core/policy/commands.ts

@@ -1,19 +1,21 @@
-/** Commands/paths that can print secrets and must ask first (ADR-017). Pure. */
+/**
+ * Commands/paths that can print secrets and must ask first (ADR-017). Pure.
+ */
 
 import { resolve } from "node:path";
 import { shellSegments, shellTokens } from "./fence";
 import { matchesPolicyPattern, normalizeAbs } from "./patterns";
 
 /** Expand a leading `~`, then resolve relative to cwd. Returns null for non-paths. */
-function asAbsolute(token: string, cwd: string, home: string): string | null {
-	const t = token.trim();
-	if (!t || t.startsWith("-")) return null;
-	let p = t;
-	if (p === "~") p = home;
-	else if (p.startsWith("~/")) p = `${home}/${p.slice(2)}`;
-	else if (!p.startsWith("/") && !p.startsWith("./") && !p.startsWith("../") && !p.includes("/")) return null;
-	const abs = p.startsWith("/") ? p : resolve(cwd, p);
-	return normalizeAbs(abs);
+function asAbsolutePath(rawToken: string, cwd: string, home: string): string | null {
+	const token = rawToken.trim();
+	if (!token || token.startsWith("-")) return null;
+	let path = token;
+	if (path === "~") path = home;
+	else if (path.startsWith("~/")) path = `${home}/${path.slice(2)}`;
+	else if (!path.startsWith("/") && !path.startsWith("./") && !path.startsWith("../") && !path.includes("/")) return null;
+	const absolute = path.startsWith("/") ? path : resolve(cwd, path);
+	return normalizeAbs(absolute);
 }
 
 /**
@@ -22,18 +24,18 @@ function asAbsolute(token: string, cwd: string, home: string): string | null {
  * path token in the command, so a read of the per-process environ file is
  * caught whatever command performs it.
  */
-export function matchedAskCommands(command: string, ask: readonly string[], cwd: string, home: string): string[] {
+export function matchedAskCommands(command: string, askEntries: readonly string[], cwd: string, home: string): string[] {
 	const found = new Set<string>();
-	if (!ask.length) return [];
+	if (!askEntries.length) return [];
 	for (const segment of shellSegments(command)) {
 		const tokens = shellTokens(segment);
 		const head = (tokens[0] ?? "").split("/").pop() ?? "";
-		for (const entry of ask) {
+		for (const entry of askEntries) {
 			if (!entry) continue;
 			if (entry.includes("/") || entry.startsWith("~")) {
 				for (const raw of tokens.slice(1)) {
-					const abs = asAbsolute(raw, cwd, home);
-					if (abs && matchesPolicyPattern(abs, entry, cwd, home)) found.add(`${head} ${raw}`.trim());
+					const absolute = asAbsolutePath(raw, cwd, home);
+					if (absolute && matchesPolicyPattern(absolute, entry, cwd, home)) found.add(`${head} ${raw}`.trim());
 				}
 			} else if (head === entry) {
 				found.add(entry);

package/src/core/policy/default-file.ts

@@ -4,8 +4,8 @@
  * global/project files tune it on top.
  *
  * Robust by design: if the file is missing or unparseable the caller falls back
- * to the constants in `defaults.ts`, so a broken package layout never leaves the
- * sandbox wide open.
+ * to the constants in `defaults.ts`, so a broken package layout never leaves
+ * the sandbox wide open.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -14,13 +14,13 @@ import { fileURLToPath } from "node:url";
 
 /** Walk up from this module looking for the file the package ships. */
 function findDefaultFile(): string | null {
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (let i = 0; i < 6; i++) {
-		const candidate = join(dir, "sandbox.default.json");
+	let directory = dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 6; depth++) {
+		const candidate = join(directory, "sandbox.default.json");
 		if (existsSync(candidate)) return candidate;
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
+		const parent = dirname(directory);
+		if (parent === directory) break;
+		directory = parent;
 	}
 	return null;
 }
@@ -37,7 +37,6 @@ export function loadDefaultPolicy(): Record<string, unknown> | null {
 			const parsed = JSON.parse(readFileSync(path, "utf-8"));
 			if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) resolved = parsed;
 		} catch {
-			/* fall back to the caller's constants */
 		}
 	}
 	cached = resolved;

package/src/core/policy/defaults.ts

@@ -8,3 +8,12 @@
 export const DEFAULT_DENY_READ = ["~/.ssh", "~/.aws", "~/.gnupg", "~/.pi/agent"];
 export const DEFAULT_ALLOW_WRITE = [".", "/tmp"];
 export const DEFAULT_DENY_WRITE = [".env", ".env.*", "*.pem", "*.key"];
+
+/** Domains every install may reach without a prompt; the shipped baseline adds more. */
+export const BUILTIN_NETWORK_ALLOWED = [
+	"npmjs.org", "*.npmjs.org",
+	"registry.npmjs.org", "registry.yarnpkg.com",
+	"pypi.org", "*.pypi.org",
+	"github.com", "*.github.com",
+	"api.github.com", "raw.githubusercontent.com",
+];

package/src/core/policy/domains.ts

@@ -17,10 +17,10 @@ export function hostnameOf(url: string): string | null {
 }
 
 export function domainMatches(host: string, pattern: string): boolean {
-	const p = pattern.toLowerCase();
-	if (p.startsWith("*.")) {
-		const suffix = p.slice(1); // ".npmjs.org"
-		return host === p.slice(2) || host.endsWith(suffix);
+	const normalizedPattern = pattern.toLowerCase();
+	if (normalizedPattern.startsWith("*.")) {
+		const suffix = normalizedPattern.slice(1);
+		return host === normalizedPattern.slice(2) || host.endsWith(suffix);
 	}
-	return host === p;
+	return host === normalizedPattern;
 }

package/src/core/policy/fence.ts

@@ -1,9 +1,12 @@
+/**
+ * Layer 1's pre-flight path scan (ADR-015) and the `filesystem` block handed
+ * to sandbox-runtime. Pure: no pi, no OS side effects.
+ */
+
 import { existsSync } from "node:fs";
 import { dirname } from "node:path";
 import { matchesPolicyPattern, normalizeAbs, toSandboxPatterns } from "./patterns";
-import { type FilesystemPolicy, outsideProjectMode, outsideProjectReadDenied } from "./classify";
-
-// ---------- Layer 1 pre-flight ask (ADR-015) ----------
+import { ReadPosture, outsideProjectMode, outsideProjectReadDenied, type FilesystemPolicy } from "./classify";
 
 /**
  * Commands whose positional arguments are read targets. Layer 1's pre-flight
@@ -19,16 +22,16 @@ const READ_COMMANDS = new Set([
 
 /** Split a shell command on the operators that start a new simple command. */
 export function shellSegments(command: string): string[] {
-	return command.split(/\s*(?:;|&&|\|\||\||\n)\s*/).map((s) => s.trim()).filter(Boolean);
+	return command.split(/\s*(?:;|&&|\|\||\||\n)\s*/).map((segment) => segment.trim()).filter(Boolean);
 }
 
 /** Tokenize one segment, dropping the quotes around fully quoted words. */
 export function shellTokens(segment: string): string[] {
-	const out: string[] = [];
-	const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
-	let m: RegExpExecArray | null;
-	while ((m = re.exec(segment))) out.push(m[1] ?? m[2] ?? m[3] ?? "");
-	return out;
+	const tokens: string[] = [];
+	const tokenPattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
+	let match: RegExpExecArray | null;
+	while ((match = tokenPattern.exec(segment))) tokens.push(match[1] ?? match[2] ?? match[3] ?? "");
+	return tokens;
 }
 
 /** Expand a leading `~`; other tokens are returned as-is. */
@@ -40,9 +43,9 @@ function expandHomeToken(token: string, home: string): string {
 
 /**
  * Absolute paths named by read-like segments of a bash command. Best-effort:
- * only read-like heads, only tokens that exist on disk. Bare names count (`.env`
- * has no slash); the caller's pattern match decides. Obfuscated reads are not
- * returned — the OS fence covers those.
+ * only read-like heads, only tokens that exist on disk. Bare names count
+ * (`.env` has no slash); the caller's pattern match decides. Obfuscated reads
+ * are not returned — the OS fence covers those.
  */
 function readPathCandidates(
 	command: string,
@@ -56,21 +59,21 @@ function readPathCandidates(
 		const head = (tokens[0] ?? "").split("/").pop() ?? "";
 		if (!READ_COMMANDS.has(head)) continue;
 		for (const raw of tokens.slice(1)) {
-			const t = raw.trim();
-			if (!t || t.startsWith("-") || /^[a-z][a-z0-9+.-]*:\/\//i.test(t)) continue;
-			const expanded = expandHomeToken(t, home);
-			const abs = expanded.startsWith("/")
+			const token = raw.trim();
+			if (!token || token.startsWith("-") || /^[a-z][a-z0-9+.-]*:\/\//i.test(token)) continue;
+			const expanded = expandHomeToken(token, home);
+			const absolute = expanded.startsWith("/")
 				? normalizeAbs(expanded)
 				: normalizeAbs(`${cwd.replace(/\/+$/, "")}/${expanded}`);
-			if (exists(abs)) found.add(abs);
+			if (exists(absolute)) found.add(absolute);
 		}
 	}
 	return [...found];
 }
 
 /** Never a hard `denyRead` match, whatever the caller asks about. */
-function notDenied(abs: string, cwd: string, home: string, fs: FilesystemPolicy): boolean {
-	return !fs.denyRead.some((pat) => matchesPolicyPattern(abs, pat, cwd, home));
+function notDenied(absPath: string, cwd: string, home: string, filesystem: FilesystemPolicy): boolean {
+	return !filesystem.denyRead.some((pattern) => matchesPolicyPattern(absPath, pattern, cwd, home));
 }
 
 /**
@@ -81,11 +84,13 @@ export function outsideProjectReadCandidates(
 	command: string,
 	cwd: string,
 	home: string,
-	fs: FilesystemPolicy,
+	filesystem: FilesystemPolicy,
 	exists: (path: string) => boolean = existsSync,
+	resolvePath: (absPath: string) => string = (absPath) => absPath,
 ): string[] {
-	return readPathCandidates(command, cwd, home, exists).filter(
-		(abs) => notDenied(abs, cwd, home, fs) && outsideProjectReadDenied(abs, cwd, home, fs),
+	const candidates = new Set(readPathCandidates(command, cwd, home, exists).map(resolvePath));
+	return [...candidates].filter(
+		(absPath) => notDenied(absPath, cwd, home, filesystem) && outsideProjectReadDenied(absPath, cwd, home, filesystem),
 	);
 }
 
@@ -94,13 +99,15 @@ export function askReadCandidates(
 	command: string,
 	cwd: string,
 	home: string,
-	fs: FilesystemPolicy,
+	filesystem: FilesystemPolicy,
 	exists: (path: string) => boolean = existsSync,
+	resolvePath: (absPath: string) => string = (absPath) => absPath,
 ): string[] {
-	const ask = fs.askRead ?? [];
-	if (!ask.length) return [];
-	return readPathCandidates(command, cwd, home, exists).filter(
-		(abs) => notDenied(abs, cwd, home, fs) && ask.some((pat) => matchesPolicyPattern(abs, pat, cwd, home)),
+	const askReadPatterns = filesystem.askRead ?? [];
+	if (!askReadPatterns.length) return [];
+	const candidates = new Set(readPathCandidates(command, cwd, home, exists).map(resolvePath));
+	return [...candidates].filter(
+		(absPath) => notDenied(absPath, cwd, home, filesystem) && askReadPatterns.some((pattern) => matchesPolicyPattern(absPath, pattern, cwd, home)),
 	);
 }
 
@@ -117,20 +124,20 @@ export function askReadCandidates(
  * `outsideProject` never reached Layer 1 at all and `bash` read anything.
  */
 export function sandboxFilesystem(
-	fs: FilesystemPolicy,
-	opts: { cwd: string; home: string },
+	filesystem: FilesystemPolicy,
+	options: { cwd: string; home: string },
 ): { denyRead: string[]; allowRead: string[]; allowWrite: string[]; denyWrite: string[] } {
-	const denyRead = toSandboxPatterns(fs.denyRead);
-	const allowRead = toSandboxPatterns(fs.allowRead ?? []);
-	if (outsideProjectMode(fs) !== "allow") {
-		for (const fence of [opts.home, dirname(opts.cwd)]) {
+	const denyRead = toSandboxPatterns(filesystem.denyRead);
+	const allowRead = toSandboxPatterns(filesystem.allowRead ?? []);
+	if (outsideProjectMode(filesystem) !== ReadPosture.Allow) {
+		for (const fence of [options.home, dirname(options.cwd)]) {
 			if (fence && fence !== "/" && !denyRead.includes(fence)) denyRead.push(fence);
 		}
-		const grants = [opts.cwd, ...fs.allowWrite, ...(fs.outsideProject?.allowRead ?? [])];
+		const grants = [options.cwd, ...filesystem.allowWrite, ...(filesystem.outsideProject?.allowRead ?? [])];
 		for (const grant of grants) {
-			const p = toSandboxPatterns([grant])[0];
-			if (!allowRead.includes(p)) allowRead.push(p);
+			const pattern = toSandboxPatterns([grant])[0];
+			if (!allowRead.includes(pattern)) allowRead.push(pattern);
 		}
 	}
-	return { denyRead, allowRead, allowWrite: [...fs.allowWrite], denyWrite: toSandboxPatterns(fs.denyWrite) };
+	return { denyRead, allowRead, allowWrite: [...filesystem.allowWrite], denyWrite: toSandboxPatterns(filesystem.denyWrite) };
 }

package/src/core/policy/merge.ts

@@ -8,9 +8,9 @@
  * trust.ts) is the tighten-only merge for an untrusted project.
  */
 
-const isPlainObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const isPlainObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
 
-const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
+const stringList = (value: unknown): string[] => (Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : []);
 
 /**
  * Overlay `top` onto `base`. Object keys merge shallowly; `overrides` is
@@ -18,22 +18,22 @@ const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is
  * base value. Absent keys keep the base, so a layer only states what it changes.
  */
 export function overlayPolicy<T extends object>(base: T, top: Partial<T>): T {
-	const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+	const merged: Record<string, unknown> = { ...(base as Record<string, unknown>) };
 	for (const [key, value] of Object.entries(top as Record<string, unknown>)) {
 		if (value === undefined) continue;
-		const existing = out[key];
+		const existing = merged[key];
 		if (key === "overrides" && isPlainObject(value)) {
-			const b = isPlainObject(existing) ? existing : {};
-			out[key] = {
-				allowRead: [...strings(b.allowRead), ...strings(value.allowRead)],
-				allowWrite: [...strings(b.allowWrite), ...strings(value.allowWrite)],
-				allowDomains: [...strings(b.allowDomains), ...strings(value.allowDomains)],
+			const baseOverrides = isPlainObject(existing) ? existing : {};
+			merged[key] = {
+				allowRead: [...stringList(baseOverrides.allowRead), ...stringList(value.allowRead)],
+				allowWrite: [...stringList(baseOverrides.allowWrite), ...stringList(value.allowWrite)],
+				allowDomains: [...stringList(baseOverrides.allowDomains), ...stringList(value.allowDomains)],
 			};
 		} else if (isPlainObject(value) && isPlainObject(existing)) {
-			out[key] = { ...existing, ...value };
+			merged[key] = { ...existing, ...value };
 		} else {
-			out[key] = value;
+			merged[key] = value;
 		}
 	}
-	return out as T;
+	return merged as T;
 }

package/src/core/policy/mode.ts

@@ -3,24 +3,33 @@
  * downgrades a rule. Pure.
  *
  * `yolo` is the weakest tier: every layer is off. `MODE_ORDER` is weakest →
- * strictest, which is what the untrusted-project merge uses to decide whether a
- * project file may change `mode` (it may only move up).
+ * strictest, which is what the untrusted-project merge uses to decide whether
+ * a project file may change `mode` (it may only move up).
  */
 
-export type PermissionMode = "yolo" | "default" | "advanced-secure";
+/**
+ * Erasable enum: named constants whose runtime values are the JSON strings, so
+ * config files keep working. Node's type stripping cannot run a TS `enum`.
+ */
+export const PermissionMode = {
+	Yolo: "yolo",
+	Default: "default",
+	AdvancedSecure: "advanced-secure",
+} as const;
+export type PermissionMode = (typeof PermissionMode)[keyof typeof PermissionMode];
 
-export const DEFAULT_MODE: PermissionMode = "default";
+export const DEFAULT_MODE: PermissionMode = PermissionMode.Default;
 
 /** Weakest → strictest. Used by the untrusted-project tighten-only merge. */
-export const MODE_ORDER: readonly PermissionMode[] = ["yolo", "default", "advanced-secure"];
+export const MODE_ORDER: readonly PermissionMode[] = [PermissionMode.Yolo, PermissionMode.Default, PermissionMode.AdvancedSecure];
 
 /** Anything that is not one of the known modes resolves to the default. */
 export function normalizeMode(value: unknown): PermissionMode {
-	return value === "advanced-secure" || value === "yolo" ? value : DEFAULT_MODE;
+	return value === PermissionMode.AdvancedSecure || value === PermissionMode.Yolo ? value : DEFAULT_MODE;
 }
 
 export function modeLabel(mode: PermissionMode): string {
-	if (mode === "advanced-secure") return "Advanced Secure";
-	if (mode === "yolo") return "YOLO";
+	if (mode === PermissionMode.AdvancedSecure) return "Advanced Secure";
+	if (mode === PermissionMode.Yolo) return "YOLO";
 	return "Default";
 }

package/src/core/policy/overrides.ts

@@ -0,0 +1,56 @@
+/**
+ * Persisted ask-tier overrides (ADR-007). Both layers write the same policy
+ * file from their "remember" branch, so the read-modify-write lives here once:
+ * appending a grant must preserve the other override kinds and every
+ * hand-written key, and a trusted project file must stay trusted after its own
+ * grant is written.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { readPolicyForUpdate } from "./policy-file";
+import { recordProjectTrust } from "../trust";
+
+/** Erasable enum for the three additive grant lists in `overrides`. */
+export const OverrideKind = {
+	AllowRead: "allowRead",
+	AllowWrite: "allowWrite",
+	AllowDomains: "allowDomains",
+} as const;
+export type OverrideKind = (typeof OverrideKind)[keyof typeof OverrideKind];
+
+/** Erasable enum for where a grant is written. */
+export const GrantScope = {
+	Cwd: "cwd",
+	Global: "global",
+} as const;
+export type GrantScope = (typeof GrantScope)[keyof typeof GrantScope];
+
+type OverrideLists = Partial<Record<OverrideKind, string[]>>;
+
+/**
+ * Append `value` to `overrides[kind]` in `path`, preserving every other key.
+ * Returns the path written. Throws when the file does not parse, so a
+ * hand-written policy is never overwritten blind.
+ */
+export function addOverride(path: string, kind: OverrideKind, value: string): string {
+	const existing = readPolicyForUpdate(path) as { overrides?: OverrideLists };
+	const overrides = existing.overrides ?? {};
+	const list = overrides[kind] ?? [];
+	if (!list.includes(value)) list.push(value);
+	overrides[kind] = list;
+	existing.overrides = overrides;
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(existing, null, 2)}\n`);
+	return path;
+}
+
+/**
+ * `addOverride` for a trusted project file: record the new content hash, so the
+ * grant write itself does not invalidate the trust that allowed it (ADR-013).
+ */
+export function addProjectOverride(projectPath: string, storePath: string, kind: OverrideKind, value: string): string {
+	const path = addOverride(projectPath, kind, value);
+	recordProjectTrust(projectPath, storePath);
+	return path;
+}