auto-permission-system 3.6.0 → 3.7.8

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;
+}

package/src/core/policy/paths.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical policy-file locations, shared by both layers. Keeping the strings
+ * here means the file a "remember" writes and the file the trust store keys
+ * can never drift apart.
+ */
+
+import { join } from "node:path";
+
+/** `<cwd>/.pi/sandbox.json` — the project-local policy (ADR-007, ADR-013). */
+export const projectPolicyPath = (cwd: string): string => join(cwd, ".pi", "sandbox.json");
+
+/** `<agentDir>/extensions/sandbox.json` — the global policy (and the persisted mode). */
+export const globalPolicyPath = (agentDir: string): string => join(agentDir, "extensions", "sandbox.json");
+
+/** `<agentDir>/extensions/sandbox.trust.json` — project-policy hashes (ADR-013). */
+export const trustStorePath = (agentDir: string): string => join(agentDir, "extensions", "sandbox.trust.json");

package/src/core/policy/patterns.ts

@@ -1,16 +1,18 @@
 /**
  * Path pattern matching shared by both layers. Pure: no pi, no OS side effects.
+ *
+ * It also owns Layer 1's violation attribution: the evidence patterns that
+ * recognise a refused filesystem access and recover the operand path from a
+ * sandboxed command's output.
  */
 
-// ---------- Layer 1 violation attribution ----------
-
 /**
  * Filesystem-refusal evidence in a sandboxed command's output. Linux
  * bubblewrap reports a write outside `allowWrite` as `EROFS: read-only file
  * system`; macOS sandbox-exec reports the same fence as `Operation not
  * permitted`; EACCES covers a permission-denied variant either can print.
  */
-const FS_BLOCKED_RE = /operation not permitted|EPERM|EACCES|EROFS|read-only file system/i;
+const BLOCKED_ACCESS_RE = /operation not permitted|EPERM|EACCES|EROFS|read-only file system/i;
 
 /**
  * `EROFS` can only come from a modification, so it proves the refused access
@@ -21,7 +23,7 @@ const WRITE_BLOCK_RE = /EROFS|read-only file system/i;
 
 /** True when the output shows the OS sandbox refused a filesystem access. */
 export function isBlockedAccessError(output: string): boolean {
-	return FS_BLOCKED_RE.test(output);
+	return BLOCKED_ACCESS_RE.test(output);
 }
 
 /** True when the refused access was a write (EROFS only happens on a modification). */
@@ -30,56 +32,90 @@ export function isWriteBlockError(output: string): boolean {
 }
 
 /** A shell-name/empty token is not a path; everything else resolves against cwd unless absolute. */
-function toAbsPath(raw: string, cwd: string, home: string): string | undefined {
-	let token = raw.trim().replace(/[.,;]+$/, "");
+function toAbsolutePath(rawToken: string, cwd: string, home: string): string | undefined {
+	let token = rawToken.trim().replace(/[.,;]+$/, "");
 	if (!token || /^(bash|sh|zsh)$/.test(token)) return undefined;
 	if (token === "~" || token.startsWith("~/")) token = home + token.slice(1);
-	const abs = token.startsWith("/") ? token : `${cwd.replace(/\/+$/, "")}/${token}`;
-	return normalizeAbs(abs);
+	const absolute = token.startsWith("/") ? token : `${cwd.replace(/\/+$/, "")}/${token}`;
+	return normalizeAbs(absolute);
+}
+
+/**
+ * Strip the diagnostic lead-in that precedes an unquoted operand so the whole
+ * operand survives (`open /path with spaces/file` -> `/path with spaces/file`).
+ * Handles the `[pid:...]` prefix runtimes print before errno-style messages and
+ * the coreutils verbs (`cannot touch`, `cannot remove`, ...).
+ */
+function stripErrnoLeadIn(text: string): string {
+	const withoutPidPrefix = text.replace(/^\[[^\]]*\]\s*/, "");
+	return withoutPidPrefix
+		.replace(/^bwrap:\s*/i, "")
+		.replace(/^(?:open|cannot (?:touch|remove|create|open|stat|access)|(?:can't|failed to) create file|touch|creat|unlink|mkdir|rmdir|rename)\s+/i, "")
+		.trim();
+}
+
+/**
+ * Whether a recovered operand really names a file. Operation words that appear
+ * in diagnostics (`socket`, `display`, `failed`, `Failed to open socket`) are
+ * not paths; a path either is rooted, contains a separator, or carries an
+ * extension. A candidate with whitespace must contain a separator, so a
+ * sentence like `. socket() failed` is rejected while `Crash Reports/x.dmp`
+ * (an unquoted path with a space) is kept.
+ */
+function looksLikePath(token: string): boolean {
+	if (!token) return false;
+	if (/\s/.test(token)) return token.includes("/");
+	if (token.startsWith("/") || token.startsWith("~")) return true;
+	if (token.startsWith(".")) return true;
+	return token.includes("/") || token.includes(".");
 }
 
 /**
- * The path a sandboxed bash command was refused, from its error output, as
- * an absolute path. Handles `tool: ./rel: Operation not permitted`, quoted
- * paths (`cannot touch 'x.pem'`), `~/…` and absolute paths, plus the
- * errno-style forms that put the path *after* the error text
+ * The path a sandboxed bash command was refused, from its error output, as an
+ * absolute path. Handles `tool: ./rel: Operation not permitted`, quoted paths
+ * (`cannot touch 'x.pem'`), `~/…` and absolute paths, plus the errno-style
+ * forms that put the path *after* the error text
  * (`EROFS: read-only file system, open '/abs/path'`,
- * `[Errno 30] Read-only file system: '/abs/path'`). Relative paths resolve
- * against the command's working directory, never against `/`.
+ * `[Errno 30] Read-only file system: '/abs/path'`). A path with spaces keeps
+ * its spaces (`open /…/Crash Reports/new/x.dmp`) while operation words
+ * (`socket`, `display`) are not mistaken for files. A `bwrap: Can't create
+ * file <path>` line is the OS sandbox failing to build its own mount mask, but
+ * its path is still recovered so the caller can report it as a setup problem.
+ * Relative paths resolve against the command's working directory, never
+ * against `/`.
  */
 export function extractBlockedPath(output: string, cwd: string, home: string): string | undefined {
-	for (const line of output.split("\n").reverse()) {
-		const m = FS_BLOCKED_RE.exec(line);
-		if (!m) continue;
-		// errno-style messages (Node, Python, coreutils) put the operand in
-		// quotes, usually after the error token: take the last quoted token.
-		const quoted = [...line.matchAll(/['"“‘`]([^'"”’`]+)['"”’`]/g)].map((q) => q[1] as string);
-		const quotedPath = quoted.length ? toAbsPath(quoted[quoted.length - 1] as string, cwd, home) : undefined;
+	for (const line of [...output.split("\n")].reverse()) {
+		const match = BLOCKED_ACCESS_RE.exec(line);
+		if (!match) continue;
+		const quotedTokens = [...line.matchAll(/['"“‘`]([^'"”’`]+)['"”’`]/g)].map((quote) => quote[1] as string);
+		const quotedPath = toAbsolutePath(quotedTokens.at(-1) ?? "", cwd, home);
 		if (quotedPath) return quotedPath;
-		// The segment right before the error text, e.g. "grep: ./.env: Operation…" → "./.env".
-		const before = line.slice(0, m.index).replace(/[\s:]+$/, "");
-		const segment = before.split(/:\s+/).pop() ?? "";
-		const token = toAbsPath(segment.split(/\s+/).pop() ?? "", cwd, home);
-		if (token) return token;
+		const beforeError = line.slice(0, match.index).replace(/[\s:]+$/, "");
+		const candidate = stripErrnoLeadIn(beforeError.split(/:\s+/).pop() ?? "");
+		if (!looksLikePath(candidate)) continue;
+		const resolved = toAbsolutePath(candidate, cwd, home);
+		if (resolved) return resolved;
 	}
 	return undefined;
 }
 
-export function normalizeAbs(p: string): string {
-	const out: string[] = [];
-	for (const part of p.split("/")) {
+/** Collapse `.` and `..` segments to a canonical absolute path (no filesystem access). */
+export function normalizeAbs(path: string): string {
+	const parts: string[] = [];
+	for (const part of path.split("/")) {
 		if (!part || part === ".") continue;
-		if (part === "..") out.pop();
-		else out.push(part);
+		if (part === "..") parts.pop();
+		else parts.push(part);
 	}
-	return `/${out.join("/")}`;
+	return `/${parts.join("/")}`;
 }
 
 /** A folder Layer 1 may offer as a one-click write grant: never `/`, the home folder, or anything above it. */
-export function isSafeFolderGrant(dir: string, home: string): boolean {
-	const d = normalizeAbs(dir);
-	const h = normalizeAbs(home);
-	return d !== "/" && d !== h && !h.startsWith(`${d}/`);
+export function isSafeFolderGrant(directory: string, home: string): boolean {
+	const normalizedDirectory = normalizeAbs(directory);
+	const normalizedHome = normalizeAbs(home);
+	return normalizedDirectory !== "/" && normalizedDirectory !== normalizedHome && !normalizedHome.startsWith(`${normalizedDirectory}/`);
 }
 
 /**
@@ -88,26 +124,26 @@ export function isSafeFolderGrant(dir: string, home: string): boolean {
  * `.` is the project root, anything else matches the basename (glob allowed).
  */
 export function matchesPolicyPattern(absPath: string, pattern: string, cwd: string, home: string): boolean {
-	let p = pattern;
-	if (p === "~") p = home;
-	else if (p.startsWith("~/")) p = `${home}/${p.slice(2)}`;
-	const ci = process.platform === "darwin" ? "i" : "";
-	const glob = (s: string) => {
-		const body = s
+	let expandedPattern = pattern;
+	if (expandedPattern === "~") expandedPattern = home;
+	else if (expandedPattern.startsWith("~/")) expandedPattern = `${home}/${expandedPattern.slice(2)}`;
+	const caseInsensitiveFlag = process.platform === "darwin" ? "i" : "";
+	const compileGlob = (source: string): RegExp => {
+		const body = source
 			.replace(/[.+^${}()|[\]\\]/g, "\\$&")
 			.split("**")
 			.map((part) => part.replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]"))
 			.join(".*");
-		return new RegExp(`^${body}$`, ci);
+		return new RegExp(`^${body}$`, caseInsensitiveFlag);
 	};
-	if (p === ".") return absPath === cwd || absPath.startsWith(`${cwd}/`);
-	if (p.startsWith("/")) {
-		if (p.includes("*")) return glob(p).test(absPath);
-		return absPath === p || absPath.startsWith(`${p}/`);
+	if (expandedPattern === ".") return absPath === cwd || absPath.startsWith(`${cwd}/`);
+	if (expandedPattern.startsWith("/")) {
+		if (expandedPattern.includes("*")) return compileGlob(expandedPattern).test(absPath);
+		return absPath === expandedPattern || absPath.startsWith(`${expandedPattern}/`);
 	}
-	const base = absPath.slice(absPath.lastIndexOf("/") + 1);
-	if (p.includes("*")) return glob(p).test(base);
-	return ci ? base.toLowerCase() === p.toLowerCase() : base === p;
+	const basename = absPath.slice(absPath.lastIndexOf("/") + 1);
+	if (expandedPattern.includes("*")) return compileGlob(expandedPattern).test(basename);
+	return caseInsensitiveFlag ? basename.toLowerCase() === expandedPattern.toLowerCase() : basename === expandedPattern;
 }
 
 /**
@@ -121,5 +157,5 @@ export function matchesPolicyPattern(absPath: string, pattern: string, cwd: stri
  * are passed through unchanged.
  */
 export function toSandboxPatterns(patterns: readonly string[]): string[] {
-	return patterns.map((p) => (p === "." || p.includes("/") || p.startsWith("~") ? p : `**/${p}`));
+	return patterns.map((pattern) => (pattern === "." || pattern.includes("/") || pattern.startsWith("~") ? pattern : `**/${pattern}`));
 }

package/src/core/policy/{files.ts → policy-file.ts}

@@ -1,3 +1,8 @@
+/**
+ * Reading and updating a policy file in place. Shared by both layers so the
+ * parse guard and the mode write cannot drift.
+ */
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { normalizeMode, type PermissionMode } from "./mode";
@@ -16,8 +21,8 @@ export function policyFileError(path: string): string | null {
 	try {
 		JSON.parse(readFileSync(path, "utf-8"));
 		return null;
-	} catch (e) {
-		return e instanceof Error ? e.message : String(e);
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
 	}
 }
 
@@ -30,15 +35,15 @@ export function readPolicyForUpdate(path: string): Record<string, unknown> {
 	if (!existsSync(path)) return {};
 	try {
 		return JSON.parse(readFileSync(path, "utf-8"));
-	} catch (e) {
-		throw new Error(`refusing to overwrite ${path}: it does not parse as JSON (${e instanceof Error ? e.message : e})`);
+	} catch (error) {
+		throw new Error(`refusing to overwrite ${path}: it does not parse as JSON (${error instanceof Error ? error.message : error})`);
 	}
 }
 
 /**
  * Set `mode` in a policy file in place, preserving its other fields (ADR-018).
- * Used by `/permission-mode` and the Shift+S shortcut. Creates the file when it
- * is absent; refuses to overwrite one that does not parse.
+ * Used by `/permission-mode` and the Shift+S shortcut. Creates the file when
+ * it is absent; refuses to overwrite one that does not parse.
  */
 export function setPolicyMode(path: string, mode: PermissionMode): void {
 	const policy = readPolicyForUpdate(path);

package/src/core/policy/subagent.ts

@@ -0,0 +1,11 @@
+/**
+ * Layer 3 vocabulary: the `subagent.network` posture (ADR-005). Pure.
+ */
+
+/** Erasable enum for `subagent.network`. */
+export const SubagentNetwork = {
+	Allow: "allow",
+	Deny: "deny",
+	ResearchOnly: "research-only",
+} as const;
+export type SubagentNetwork = (typeof SubagentNetwork)[keyof typeof SubagentNetwork];