Close the omitted-toolName fail-open in the spill URI sandbox

An omitted toolName used to keep the legacy skip, so a future or
out-of-tree caller that forgets the argument would silently skip the
deny. The parameter is now required and the verdict denies when no
tool identity reaches it. Pin the behavior with an omitted-name test,
a gate-level authorize test, and an allowOutside execution test.

Author: TheGreatAxios

src/permission/gate.test.ts

@@ -475,3 +475,38 @@ describe("grant-mismatch asks carry the guard reason as a notice (CL-6824)", ()
     expect(seen).toHaveLength(0);
   });
 });
+
+// Spill URI sandbox (CL-6727): the permission gate denies a non-reader
+// virtual ref at authorize time, mirroring the execution-time middleware
+// deny, while the exempted reader is not denied.
+describe("spill URI sandbox at authorize time (CL-6727)", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "gate-spill-uri-"));
+  const gate = createPermissionGate({
+    approvals: [],
+    interactive: false,
+    skipPermissions: false,
+    reactorGated: false,
+    cwd,
+  });
+
+  test("grep + tool-output:/// is denied at authorize", async () => {
+    const verdict = await gate.authorizeCall({
+      id: "spill-grep",
+      name: "grep",
+      arguments: { pattern: "foo", path: "tool-output:///abc123" },
+    });
+    expect(verdict.effect).toBe("deny");
+    expect(verdict.effect === "deny" ? verdict.reason : "").toMatch(
+      /tool-output/,
+    );
+  });
+
+  test("read_file + the same tool-output:/// URI is not denied", async () => {
+    const verdict = await gate.authorizeCall({
+      id: "spill-read",
+      name: "read_file",
+      arguments: { path: "tool-output:///abc123" },
+    });
+    expect(verdict.effect).not.toBe("deny");
+  });
+});

src/plugins/path-escape-plugin.test.ts

@@ -342,15 +342,24 @@ describe("pathEscapePlugin", () => {
         pathEscapeBlockReason(
           { options: { path: "../secret.txt" } },
           "/project",
+          () => [],
+          "read_file",
         ),
       ).toMatch(/escapes working directory/);
       expect(
-        pathEscapeBlockReason({ filepath: "../secret.txt" }, "/project"),
+        pathEscapeBlockReason(
+          { filepath: "../secret.txt" },
+          "/project",
+          () => [],
+          "read_file",
+        ),
       ).toMatch(/escapes working directory/);
       expect(
         pathEscapeBlockReason(
           { paths: ["src/index.ts", "../secret.txt"] },
           "/project",
+          () => [],
+          "read_file",
         ),
       ).toMatch(/escapes working directory/);
     });
@@ -369,6 +378,8 @@ describe("pathEscapePlugin", () => {
         pathEscapeBlockReason(
           { options: { command: "../secret.txt" } },
           "/project",
+          () => [],
+          "custom_tool",
         ),
       ).toBeUndefined();
     });
@@ -386,7 +397,12 @@ describe("pathEscapePlugin", () => {
         expect(result.isError).toBe(true);
         expect(result.content).toMatch(/escapes working directory/);
         expect(
-          pathEscapeBlockReason({ [key]: "../secret.txt" }, "/project"),
+          pathEscapeBlockReason(
+            { [key]: "../secret.txt" },
+            "/project",
+            () => [],
+            "read_file",
+          ),
         ).toMatch(/escapes working directory/);
       }
     });
@@ -406,7 +422,9 @@ describe("pathEscapePlugin", () => {
       );
       expect(result.isError).not.toBe(true);
       expect(seen()).toEqual(args);
-      expect(pathEscapeBlockReason(args, "/project")).toBeUndefined();
+      expect(
+        pathEscapeBlockReason(args, "/project", () => [], "custom_tool"),
+      ).toBeUndefined();
     });
 
     test("normalizePathArguments shares the plugin rewrite identity", () => {
@@ -513,5 +531,52 @@ describe("pathEscapePlugin", () => {
       );
       expect(blocked.isError).toBe(true);
     });
+
+    test("omitted toolName fails closed on virtual refs", () => {
+      const omitted = undefined as unknown as string;
+      expect(
+        pathEscapeBlockReason(
+          { path: "tool-output:///abc123" },
+          "/project",
+          () => [],
+          omitted,
+        ),
+      ).toMatch(/tool-output/);
+      expect(
+        pathEscapeBlockReason(
+          { path: "archive:///occ-abc" },
+          "/project",
+          () => [],
+          omitted,
+        ),
+      ).toMatch(/archive/);
+    });
+
+    test("allowOutside still denies a non-reader virtual ref at execution", async () => {
+      const plugin = pathEscapePlugin("/project", () => [], {
+        allowOutside: true,
+      });
+      const handler = plugin.middleware
+        ? plugin.middleware(nextHandler)
+        : nextHandler;
+      const spill = await handler(
+        makeCall("grep", {
+          pattern: "foo",
+          path: "tool-output:///abc123",
+        }),
+        new AbortController().signal,
+      );
+      expect(spill.isError).toBe(true);
+      expect(spill.content).toMatch(/tool-output/);
+      const archive = await handler(
+        makeCall("write_file", {
+          path: "archive:///occ-abc",
+          content: "hi",
+        }),
+        new AbortController().signal,
+      );
+      expect(archive.isError).toBe(true);
+      expect(archive.content).toMatch(/archive/);
+    });
   });
 });

src/plugins/path-escape-plugin.ts

@@ -51,7 +51,7 @@ function escapeArgs(
   cwd: string,
   rootsProvider: RootsProvider,
   allowOutside: boolean,
-  toolName?: string,
+  toolName: string,
 ): Record<string, unknown> {
   if (!allowOutside) {
     const reason = pathEscapeBlockReason(args, cwd, rootsProvider, toolName);
@@ -72,8 +72,8 @@ function escapeValue(
   cwd: string,
   rootsProvider: RootsProvider,
   allowOutside: boolean,
-  key?: string,
-  toolName?: string,
+  key: string | undefined,
+  toolName: string,
 ): unknown {
   if (typeof value === "string") {
     return key !== undefined && looksLikePath(key)
@@ -154,24 +154,30 @@ const TOOL_OUTPUT_URI_TOOL = "read_file";
 const ARCHIVE_URI_TOOLS = new Set(["read_file", "grep", "search_files"]);
 
 // "skip" when this tool may receive the virtual ref, a block message when it
-// may not, undefined when the value is an ordinary filesystem path. An
-// omitted toolName keeps the legacy skip so direct callers that predate the
-// parameter see no behavior change; the middleware and the permission gate
-// always pass a name.
+// may not, undefined when the value is an ordinary filesystem path. An omitted
+// toolName denies rather than skips: both production callers (the middleware
+// and the permission gate) always pass a name, so an omission is a caller bug
+// and must fail closed instead of silently skipping the deny.
 function virtualRefVerdict(
   value: string,
   toolName: string | undefined,
 ): "skip" | string | undefined {
   if (isToolOutputLike(value)) {
-    if (toolName === undefined || toolName === TOOL_OUTPUT_URI_TOOL) {
+    if (toolName === TOOL_OUTPUT_URI_TOOL) {
       return "skip";
     }
+    if (toolName === undefined) {
+      return `cannot use a tool-output:// URI without a tool identity: ${value}. Use read_file with that URI to read the spilled output instead.`;
+    }
     return `cannot ${toolName} a tool-output:// URI: ${value}. Use read_file with that URI to read the spilled output instead.`;
   }
   if (isArchiveLike(value)) {
-    if (toolName === undefined || ARCHIVE_URI_TOOLS.has(toolName)) {
+    if (toolName !== undefined && ARCHIVE_URI_TOOLS.has(toolName)) {
       return "skip";
     }
+    if (toolName === undefined) {
+      return `cannot use an archive:/// ref without a tool identity: ${value}. Only read_file, grep, and search_files accept archive:/// refs.`;
+    }
     return `cannot ${toolName} an archive:/// ref: ${value}. Only read_file, grep, and search_files accept archive:/// refs.`;
   }
   return undefined;
@@ -184,7 +190,7 @@ export function pathEscapeBlockReason(
   args: Record<string, unknown>,
   cwd: string,
   rootsProvider: RootsProvider = () => [],
-  toolName?: string,
+  toolName: string,
 ): string | undefined {
   return blockReasonFor(args, cwd, rootsProvider, undefined, toolName);
 }
@@ -232,8 +238,8 @@ function blockReasonFor(
   value: unknown,
   cwd: string,
   rootsProvider: RootsProvider,
-  key?: string,
-  toolName?: string,
+  key: string | undefined,
+  toolName: string,
 ): string | undefined {
   if (typeof value === "string") {
     if (key === undefined || !looksLikePath(key)) return undefined;
@@ -272,7 +278,7 @@ function sanitizePath(
   cwd: string,
   rootsProvider: RootsProvider,
   allowOutside: boolean,
-  toolName?: string,
+  toolName: string,
 ): string {
   const verdict = virtualRefVerdict(value, toolName);
   if (verdict === "skip") {