auto-permission-system 3.0.1 → 3.7.8

package/src/core/index.ts

@@ -3,14 +3,18 @@
  * Both layer adapters and the unit tests import from here.
  */
 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

@@ -0,0 +1,26 @@
+/**
+ * Domain pattern matching shared by both layers. Pure: no pi, no OS.
+ *
+ * `hostnameOf` parses a URL to its lowercase host; `domainMatches` implements
+ * the allow-list syntax used by `allowedDomains` / `deniedDomains` / grants:
+ * an exact host, or `*.domain` which also matches the apex. Port suffixes
+ * (`host:443`) are a sandbox-runtime config feature only; this matcher is
+ * hostname-only, which is what both layers store in policy.
+ */
+
+export function hostnameOf(url: string): string | null {
+	try {
+		return new URL(url).hostname.toLowerCase();
+	} catch {
+		return null;
+	}
+}
+
+export function domainMatches(host: string, pattern: string): boolean {
+	const normalizedPattern = pattern.toLowerCase();
+	if (normalizedPattern.startsWith("*.")) {
+		const suffix = normalizedPattern.slice(1);
+		return host === normalizedPattern.slice(2) || host.endsWith(suffix);
+	}
+	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");