pi-monofold 0.3.2 → 0.3.3

package/README.md

@@ -20,7 +20,7 @@ See [docs/usage.md](./docs/usage.md) for configuration, commands, agent tools, a
 
 - **Virtual monorepo manifest** — declare workspaces and project workspaces in `.pi/monofold.yaml`
 - **Routed Markdown writes** — route PRDs, progress notes, and other doc types to configured folders
-- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces
+- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces, with bounded previews by default
 - **Capability guard** — block or confirm `read` / `write` / `edit` / `grep` / `find` / `bash` based on workspace tags
 - **Focus presets** — tag-based focus targets for the control workspace
 - **Natural-language commands** — `/monofold:explore`, `/monofold:write`, `/monofold:config`, `/monofold:git`, and more
@@ -104,6 +104,29 @@ Example command flows: [docs/examples.md](./docs/examples.md).
 
 Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Full reference: [docs/usage.md](./docs/usage.md).
 
+## Safe read defaults
+
+`monofold_read` can reach files across multiple configured workspaces. Returning full file bodies or unbounded search/tree output by default would flood the agent chat and can bias later turns. Pi Monofold therefore uses **preview-first, capped-by-default** reads.
+
+| `monofold_read` mode | Default output |
+|----------------------|----------------|
+| **file** | Path, size, line/character counts, modified time, then a bounded preview (first **20** lines, up to **2,000** characters). Files that already fit those bounds are shown in full without a truncation marker. |
+| **search** | Up to **50** match lines and **8,000** characters of ripgrep output. |
+| **tree** | Up to **200** entries; traversal depth is capped at **5**. |
+
+When output is cut, the tool response includes a **`[truncated]`** marker (file mode) or a **`[truncated: …]`** footer (search/tree) that states what was shown and how to request more.
+
+**Request more content intentionally:**
+
+| Goal | `monofold_read` parameters |
+|------|----------------------------|
+| Full file body | `mode: "file"`, `includeContent: true` |
+| Larger bounded file slice | `head`, `tail`, and/or `maxChars` (positive integers) |
+| More search results | Higher `maxMatches` and/or `maxChars`, or a narrower `path` / `query` |
+| Larger directory tree | Higher `maxEntries`, lower `depth`, or a narrower `path` |
+
+Agents should call **`monofold_read`** (not guess at raw Pi `read`). Humans should use **`/monofold:explore`** with natural language. Legacy slash commands such as `/monofold:read` apply the same caps for compatibility but are **not** the preferred human-facing surface—see [docs/usage.md](./docs/usage.md#safe-read-contract-monofold_read).
+
 ## Package contents
 
 ```text

package/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { execFile } from "node:child_process";
-import { access, copyFile, mkdir, readFile, readdir, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
 import {
@@ -12,13 +12,17 @@ import {
   parseFocusPresets,
   warnZeroTargetMatchesForPreset,
 } from "./focus-preset.js";
-import { buildFileReadResponse } from "./file-read-preview.js";
 import {
-  capSearchOutput,
-  capTreeLines,
-  resolveSearchCaps,
-  resolveTreeCaps,
-} from "./read-caps.js";
+  buildMonofoldTree,
+  readMonofoldFile,
+  runMonofoldSearch,
+} from "./monofold-read-ops.js";
+import {
+  clearUnknownPathAllows,
+  loadUnknownPathAllows,
+  rememberUnknownPathAllow,
+  UNKNOWN_PATH_ALLOWS_RELATIVE_PATH,
+} from "./unknown-path-allows.js";
 import { normalizeGuardPath } from "./path-normalize.js";
 import { assertKnownKeys, asStringArray, isRecord, uniqueStrings } from "./validation.js";
 
@@ -688,6 +692,23 @@ function stringFlag(flags: Record<string, string | boolean>, ...names: string[])
   return undefined;
 }
 
+function booleanFlag(flags: Record<string, string | boolean>, ...names: string[]): boolean {
+  for (const name of names) {
+    const value = flags[name];
+    if (value === true || value === "true" || value === "1") return true;
+  }
+  return false;
+}
+
+function numberFlag(flags: Record<string, string | boolean>, label: string, ...names: string[]): number | undefined {
+  const raw = stringFlag(flags, ...names);
+  if (!raw) return undefined;
+  if (!/^[+-]?\d+$/.test(raw)) throw new Error(`${label} must be a number`);
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) throw new Error(`${label} must be a number`);
+  return parsed;
+}
+
 function commandTarget(flags: Record<string, string | boolean>, requireCapabilities?: CapabilityTag[]): TargetInput {
   const workspace = stringFlag(flags, "target", "workspace", "w");
   const tags = stringFlag(flags, "tags", "tag")
@@ -894,39 +915,6 @@ async function buildManifest(loaded: LoadedConfig): Promise<string> {
   return lines.join("\n");
 }
 
-type ShallowTreeBudget = {
-  remaining: number;
-  truncated: boolean;
-};
-
-async function shallowTree(
-  root: string,
-  depth: number,
-  prefix = "",
-  budget?: ShallowTreeBudget,
-): Promise<string[]> {
-  if (depth < 0) return [];
-  if (budget && budget.remaining <= 0) {
-    budget.truncated = true;
-    return [];
-  }
-  const entries = await readdir(path.join(root, prefix), { withFileTypes: true });
-  const lines: string[] = [];
-  for (const entry of entries.filter((e) => !e.name.startsWith(".git") && e.name !== "node_modules")) {
-    if (budget && budget.remaining <= 0) {
-      budget.truncated = true;
-      break;
-    }
-    const rel = normalizeSlashes(path.join(prefix, entry.name));
-    lines.push(entry.isDirectory() ? `${rel}/` : rel);
-    if (budget) budget.remaining -= 1;
-    if (entry.isDirectory() && depth > 0) {
-      lines.push(...(await shallowTree(root, depth - 1, rel, budget)));
-    }
-  }
-  return lines;
-}
-
 function slugify(title: string): string {
   const normalized = title
     .trim()
@@ -976,8 +964,16 @@ async function confirm(ctx: ExtensionContext, title: string, body: string): Prom
 async function maybeBlockUnknown(ctx: ExtensionContext, loaded: LoadedConfig, targetPath: string, action: string) {
   const workspace = findWorkspaceForPath(loaded, targetPath);
   if (workspace) return undefined;
-  const ok = await confirm(ctx, "Unknown Path", `${action} targets an unknown path:\n${targetPath}\nAllow this operation?`);
-  if (!ok) return { block: true, reason: `Unknown Path requires confirmation: ${targetPath}` };
+  const normalized = normalizeGuardPath(path.isAbsolute(targetPath) ? targetPath : path.resolve(loaded.root, targetPath));
+  const storedAllows = await loadUnknownPathAllows(loaded.root);
+  if (storedAllows.has(normalized)) return undefined;
+  if (!ctx.hasUI) return { block: true, reason: `Unknown Path requires confirmation: ${targetPath}` };
+  const choice = await ctx.ui.select(
+    `Unknown Path — ${normalized}`,
+    ["Yes (remember across sessions)", "Yes (just this once)", "No"],
+  );
+  if (!choice || choice === "No") return { block: true, reason: `Unknown Path requires confirmation: ${targetPath}` };
+  if (choice === "Yes (remember across sessions)") await rememberUnknownPathAllow(loaded.root, normalized);
   return undefined;
 }
 
@@ -1112,21 +1108,12 @@ ${manifest}
       if (params.mode === "file") {
         if (!params.path) throw new Error("monofold_read mode=file requires path");
         const filePath = relativePath(workspace, params.path);
-        const [content, fileStat] = await Promise.all([
-          readFile(filePath, "utf8"),
-          stat(filePath),
-        ]);
-        const preview = buildFileReadResponse(
-          content,
-          {
-            includeContent: params.includeContent,
-            maxChars: params.maxChars,
-            head: params.head,
-            tail: params.tail,
-          },
-          { size: fileStat.size, mtime: fileStat.mtime },
-          { relativePath: params.path },
-        );
+        const preview = await readMonofoldFile(filePath, params.path, {
+          includeContent: params.includeContent,
+          maxChars: params.maxChars,
+          head: params.head,
+          tail: params.tail,
+        });
         return {
           content: [{ type: "text", text: preview.text }],
           details: {
@@ -1139,10 +1126,7 @@ ${manifest}
       if (params.mode === "tree") {
         const root = params.path ? relativePath(workspace, params.path) : workspace.resolvedPath;
         const depth = Math.max(0, Math.min(5, params.depth ?? 1));
-        const treeCaps = resolveTreeCaps({ maxEntries: params.maxEntries });
-        const treeBudget: ShallowTreeBudget = { remaining: treeCaps.maxEntries, truncated: false };
-        const rawLines = await shallowTree(root, depth, "", treeBudget);
-        const capped = capTreeLines(rawLines, treeCaps, treeBudget.truncated);
+        const capped = await buildMonofoldTree(root, depth, { maxEntries: params.maxEntries });
         return {
           content: [{ type: "text", text: capped.text }],
           details: {
@@ -1158,17 +1142,11 @@ ${manifest}
       }
       if (params.mode === "search") {
         if (!params.query) throw new Error("monofold_read mode=search requires query");
-        const searchCaps = resolveSearchCaps({ maxMatches: params.maxMatches, maxChars: params.maxChars });
-        const result = await runCommand("rg", ["--line-number", "--hidden", "--glob", "!.git/**", params.query, params.path ?? "."], {
-          cwd: workspace.resolvedPath,
+        const capped = await runMonofoldSearch(runCommand, workspace.resolvedPath, params.query, params.path ?? ".", {
           signal,
-          timeout: 10000,
-          allowExitCodes: [0, 1],
+          maxMatches: params.maxMatches,
+          maxChars: params.maxChars,
         });
-        const rawOutput =
-          result.stdout.trim() ||
-          (result.exitCode !== 0 && result.exitCode !== 1 ? result.stderr.trim() : "");
-        const capped = capSearchOutput(rawOutput, searchCaps);
         return {
           content: [{ type: "text", text: capped.text }],
           details: {
@@ -1330,9 +1308,10 @@ ${manifest}
   };
 
   const readUsage = [
-    "/monofold:tree [path] [--workspace \"Name\"|--workspace #0] [--depth 2]",
-    "/monofold:read file <path> [--workspace \"Name\"|--workspace #0]",
-    "/monofold:search <query> [--workspace \"Name\"|--workspace #0]",
+    "/monofold:read file <path> [--workspace \"Name\"|--workspace #0] [--include-content] [--max-chars N] [--head N] [--tail N]",
+    "/monofold:tree [path] [--workspace \"Name\"|--workspace #0] [--depth 2] [--max-entries N]",
+    "/monofold:search <query> [--workspace \"Name\"|--workspace #0] [--path subdir] [--max-matches N] [--max-chars N]",
+    "Legacy read/search/tree commands return bounded previews by default. Pass --include-content or larger caps intentionally.",
     "Aliases: /monofold_read tree|file|search ...",
   ].join("\n");
 
@@ -1348,8 +1327,17 @@ ${manifest}
         const inputPath = stringFlag(parsed.flags, "path", "p") ?? parsed.positional.slice(1).join(" ");
         if (!inputPath) throw new Error("file mode requires path");
         const filePath = relativePath(workspace, inputPath);
-        const text = await readFile(filePath, "utf8");
-        sendCommandOutput(pi, `monofold:read ${formatWorkspaceLabel(workspace)}:${inputPath}`, text, { workspace, path: inputPath });
+        const preview = await readMonofoldFile(filePath, inputPath, {
+          includeContent: booleanFlag(parsed.flags, "include-content", "includeContent"),
+          maxChars: numberFlag(parsed.flags, "max-chars", "maxChars", "max-chars"),
+          head: numberFlag(parsed.flags, "head", "head"),
+          tail: numberFlag(parsed.flags, "tail", "tail"),
+        });
+        sendCommandOutput(pi, `monofold:read ${formatWorkspaceLabel(workspace)}:${inputPath}`, preview.text, {
+          workspace,
+          path: inputPath,
+          ...preview.details,
+        });
         return;
       }
 
@@ -1358,13 +1346,17 @@ ${manifest}
         const depth = Number.parseInt(stringFlag(parsed.flags, "depth", "d") ?? "1", 10);
         const root = inputPath ? relativePath(workspace, inputPath) : workspace.resolvedPath;
         const treeDepth = Math.max(0, Math.min(5, Number.isFinite(depth) ? depth : 1));
-        const treeCaps = resolveTreeCaps();
-        const treeBudget: ShallowTreeBudget = { remaining: treeCaps.maxEntries, truncated: false };
-        const rawLines = await shallowTree(root, treeDepth, "", treeBudget);
-        const capped = capTreeLines(rawLines, treeCaps, treeBudget.truncated);
+        const capped = await buildMonofoldTree(root, treeDepth, {
+          maxEntries: numberFlag(parsed.flags, "max-entries", "maxEntries", "max-entries"),
+        });
         sendCommandOutput(pi, `monofold:tree ${formatWorkspaceLabel(workspace)}:${inputPath || "."}`, capped.text, {
           workspace,
           path: inputPath || ".",
+          entryCount: capped.entryCount,
+          returnedEntryCount: capped.returnedEntryCount,
+          maxEntries: capped.maxEntries,
+          truncated: capped.truncated,
+          ...(capped.hint ? { hint: capped.hint } : {}),
         });
         return;
       }
@@ -1372,18 +1364,20 @@ ${manifest}
       if (mode === "search" || mode === "grep") {
         const query = stringFlag(parsed.flags, "query", "q") ?? parsed.positional.slice(1).join(" ");
         if (!query) throw new Error("search mode requires query");
-        const result = await runCommand("rg", ["--line-number", "--hidden", "--glob", "!.git/**", query, "."], {
-          cwd: workspace.resolvedPath,
-          timeout: 10000,
-          allowExitCodes: [0, 1],
+        const searchPath = stringFlag(parsed.flags, "path", "p") ?? ".";
+        const capped = await runMonofoldSearch(runCommand, workspace.resolvedPath, query, searchPath, {
+          maxMatches: numberFlag(parsed.flags, "max-matches", "maxMatches", "max-matches"),
+          maxChars: numberFlag(parsed.flags, "max-chars", "maxChars", "max-chars"),
         });
-        const rawOutput =
-          result.stdout.trim() ||
-          (result.exitCode !== 0 && result.exitCode !== 1 ? result.stderr.trim() : "");
-        const capped = capSearchOutput(rawOutput, resolveSearchCaps());
         sendCommandOutput(pi, `monofold:search ${formatWorkspaceLabel(workspace)}:${query}`, capped.text, {
           workspace,
           query,
+          matchCount: capped.matchCount,
+          returnedMatchCount: capped.returnedMatchCount,
+          maxMatches: capped.maxMatches,
+          maxChars: capped.maxChars,
+          truncated: capped.truncated,
+          ...(capped.hint ? { hint: capped.hint } : {}),
         });
         return;
       }
@@ -1585,6 +1579,22 @@ ${manifest}
     }
   };
 
+  const clearUnknownPathAllowsCommand = async (_args: string, ctx: ExtensionCommandContext) => {
+    try {
+      const count = await clearUnknownPathAllows(ctx.cwd);
+      sendCommandOutput(
+        pi,
+        "monofold:clear-unknown-path-allows",
+        count > 0
+          ? `Cleared ${count} remembered unknown path allow${count === 1 ? "" : "s"} from ${UNKNOWN_PATH_ALLOWS_RELATIVE_PATH}`
+          : `No remembered unknown path allows found at ${UNKNOWN_PATH_ALLOWS_RELATIVE_PATH}`,
+        { count, path: UNKNOWN_PATH_ALLOWS_RELATIVE_PATH },
+      );
+    } catch (error) {
+      sendCommandError(pi, "monofold:clear-unknown-path-allows", error, "/monofold:clear-unknown-path-allows");
+    }
+  };
+
   const intentCommand = (intent: IntentCategory) => async (args: string, ctx: ExtensionCommandContext) => {
     const prepared = await prepareIntentConfiguration(ctx);
     if (!prepared) {
@@ -1606,6 +1616,33 @@ ${manifest}
   pi.registerCommand("monofold:git", { description: "Run workspace git workflows via natural-language handoff", handler: intentCommand("Git") });
   pi.registerCommand("monofold:guide", { description: "Conversational guide for Pi Monofold workflows", handler: guideCommand });
   pi.registerCommand("monofold:update", { description: `Migrate and validate ${CONFIG_RELATIVE_PATH}`, handler: updateCommand });
+  pi.registerCommand("monofold:clear-unknown-path-allows", {
+    description: `Clear remembered unknown-path allows stored in ${UNKNOWN_PATH_ALLOWS_RELATIVE_PATH}`,
+    handler: clearUnknownPathAllowsCommand,
+  });
+
+
+  pi.registerCommand("monofold:list", { description: "List configured Pi Monofold workspaces (legacy)", handler: listCommand });
+
+  pi.registerCommand("monofold:tree", {
+    description: "Show a bounded tree for a configured workspace (legacy)",
+    handler: (args, ctx) => readCommand(`tree ${args}`, ctx),
+  });
+
+  pi.registerCommand("monofold:read", { description: "Read, tree, or search a configured workspace with safe defaults (legacy)", handler: readCommand });
+
+  pi.registerCommand("monofold:search", {
+    description: "Search a configured workspace with safe defaults (legacy)",
+    handler: (args, ctx) => readCommand(`search ${args}`, ctx),
+  });
+
+  pi.registerCommand("monofold:add", { description: `Add a workspace to ${CONFIG_RELATIVE_PATH} (legacy)`, handler: addCommand });
+
+  pi.registerCommand("monofold:project-add", {
+    description: "Add a project workspace under a parent workspace (legacy)",
+    handler: projectAddCommand,
+  });
+
 
   const initCommand = async (_args: string, ctx: ExtensionCommandContext) => {
       if (!ctx.hasUI) {

package/monofold-read-ops.ts

@@ -0,0 +1,125 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { buildFileReadResponse, type FileReadOptions } from "./file-read-preview.js";
+import {
+  capSearchOutput,
+  capTreeLines,
+  resolveSearchCaps,
+  resolveTreeCaps,
+  type SearchCapResult,
+  type TreeCapResult,
+} from "./read-caps.js";
+
+export type ShallowTreeBudget = {
+  remaining: number;
+  truncated: boolean;
+};
+
+export type MonofoldFileReadResult = {
+  text: string;
+  details: ReturnType<typeof buildFileReadResponse>["details"];
+};
+
+export type RunCommandFn = (
+  command: string,
+  args: string[],
+  options?: {
+    cwd?: string;
+    timeout?: number;
+    signal?: AbortSignal;
+    allowExitCodes?: Array<number | string>;
+  },
+) => Promise<{ stdout: string; stderr: string; exitCode: number | string | null | undefined }>;
+
+/** Maximum depth allowed for {@link buildMonofoldTree} and shallow tree walks. */
+export const MAX_TREE_DEPTH = 5;
+
+function normalizeSlashes(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+export async function shallowTree(
+  root: string,
+  depth: number,
+  prefix = "",
+  budget?: ShallowTreeBudget,
+): Promise<string[]> {
+  if (depth < 0) return [];
+  if (budget && budget.remaining <= 0) {
+    budget.truncated = true;
+    return [];
+  }
+  const entries = await readdir(path.join(root, prefix), { withFileTypes: true });
+  const lines: string[] = [];
+  for (const entry of entries.filter((e) => e.name !== ".git" && e.name !== "node_modules")) {
+    if (budget && budget.remaining <= 0) {
+      budget.truncated = true;
+      break;
+    }
+    const rel = normalizeSlashes(path.join(prefix, entry.name));
+    lines.push(entry.isDirectory() ? `${rel}/` : rel);
+    if (budget) budget.remaining -= 1;
+    if (entry.isDirectory() && depth > 0) {
+      lines.push(...(await shallowTree(root, depth - 1, rel, budget)));
+    }
+  }
+  return lines;
+}
+
+export async function readMonofoldFile(
+  absolutePath: string,
+  relativePath: string,
+  options: FileReadOptions = {},
+): Promise<MonofoldFileReadResult> {
+  const [content, fileStat] = await Promise.all([readFile(absolutePath, "utf8"), stat(absolutePath)]);
+  const preview = buildFileReadResponse(
+    content,
+    options,
+    { size: fileStat.size, mtime: fileStat.mtime },
+    { relativePath },
+  );
+  return { text: preview.text, details: preview.details };
+}
+
+/**
+ * Build a bounded directory tree for a workspace root.
+ *
+ * @param root - Absolute path to the workspace root.
+ * @param depth - Requested traversal depth; clamped to [0, {@link MAX_TREE_DEPTH}].
+ * @param options - Optional caps such as `maxEntries`.
+ */
+export async function buildMonofoldTree(
+  root: string,
+  depth: number,
+  options?: { maxEntries?: number },
+): Promise<TreeCapResult> {
+  const treeDepth = Math.max(0, Math.min(MAX_TREE_DEPTH, depth));
+  const treeCaps = resolveTreeCaps({ maxEntries: options?.maxEntries });
+  const treeBudget: ShallowTreeBudget = { remaining: treeCaps.maxEntries, truncated: false };
+  const rawLines = await shallowTree(root, treeDepth, "", treeBudget);
+  return capTreeLines(rawLines, treeCaps, treeBudget.truncated);
+}
+
+export async function runMonofoldSearch(
+  runCommand: RunCommandFn,
+  cwd: string,
+  query: string,
+  searchPath = ".",
+  options?: { signal?: AbortSignal; maxMatches?: number; maxChars?: number },
+): Promise<SearchCapResult & { rawOutput: string }> {
+  const searchCaps = resolveSearchCaps({ maxMatches: options?.maxMatches, maxChars: options?.maxChars });
+  const result = await runCommand(
+    "rg",
+    ["--line-number", "--hidden", "--glob", "!.git/**", "--glob", "!.github/**", query, searchPath],
+    {
+      cwd,
+      signal: options?.signal,
+      timeout: 10000,
+      allowExitCodes: [0, 1],
+    },
+  );
+  const rawOutput =
+    result.stdout.trim() || (result.exitCode !== 0 && result.exitCode !== 1 ? result.stderr.trim() : "");
+  const capped = capSearchOutput(rawOutput, searchCaps);
+  return { ...capped, rawOutput };
+}

package/package.json

@@ -11,7 +11,7 @@
   },
   "description": "Pi extension that folds multiple repositories and folders into a guarded virtual monorepo for AI agents.",
   "type": "module",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "pi": {
     "extensions": [
       "./index.ts"
@@ -22,8 +22,10 @@
     "LICENSE",
     "index.ts",
     "path-normalize.ts",
+    "unknown-path-allows.ts",
     "file-read-preview.ts",
     "focus-preset.ts",
+    "monofold-read-ops.ts",
     "read-caps.ts",
     "validation.ts"
   ],

package/unknown-path-allows.ts

@@ -0,0 +1,66 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { normalizeGuardPath } from "./path-normalize.js";
+
+export const UNKNOWN_PATH_ALLOWS_RELATIVE_PATH = path.join(".pi", "monofold-unknown-path-allows.json");
+
+type UnknownPathAllowsFile = {
+  version: 1;
+  paths: string[];
+};
+
+function assertAllowsFile(value: unknown): asserts value is UnknownPathAllowsFile {
+  if (typeof value !== "object" || value === null) throw new Error("unknown path allows file must be an object");
+  if (!("version" in value) || (value as { version?: unknown }).version !== 1) {
+    throw new Error("unknown path allows file requires version: 1");
+  }
+  if (!("paths" in value) || !Array.isArray((value as { paths?: unknown }).paths) || !(value as { paths: unknown[] }).paths.every((item) => typeof item === "string")) {
+    throw new Error("unknown path allows file requires string[] paths");
+  }
+}
+
+export function resolveUnknownPathAllowsPath(root: string): string {
+  return path.join(normalizeGuardPath(root), UNKNOWN_PATH_ALLOWS_RELATIVE_PATH);
+}
+
+export async function loadUnknownPathAllows(root: string): Promise<Set<string>> {
+  const filePath = resolveUnknownPathAllowsPath(root);
+  try {
+    const text = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(text) as unknown;
+    assertAllowsFile(parsed);
+    return new Set(parsed.paths.map((item) => normalizeGuardPath(item)));
+  } catch (error) {
+    const code = typeof error === "object" && error && "code" in error ? (error as { code?: string }).code : undefined;
+    if (code === "ENOENT") return new Set<string>();
+    throw error;
+  }
+}
+
+async function saveUnknownPathAllows(root: string, paths: Set<string>): Promise<void> {
+  const filePath = resolveUnknownPathAllowsPath(root);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const payload: UnknownPathAllowsFile = {
+    version: 1,
+    paths: [...paths].map((item) => normalizeGuardPath(item)).sort(),
+  };
+  await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+export async function rememberUnknownPathAllow(root: string, targetPath: string): Promise<void> {
+  const paths = await loadUnknownPathAllows(root);
+  paths.add(normalizeGuardPath(targetPath));
+  await saveUnknownPathAllows(root, paths);
+}
+
+export async function clearUnknownPathAllows(root: string): Promise<number> {
+  const filePath = resolveUnknownPathAllowsPath(root);
+  const paths = await loadUnknownPathAllows(root);
+  try {
+    await rm(filePath, { force: true });
+  } catch (error) {
+    const code = typeof error === "object" && error && "code" in error ? (error as { code?: string }).code : undefined;
+    if (code !== "ENOENT") throw error;
+  }
+  return paths.size;
+}