fix(permissions): deny forged read_file cursors for outside-root paths

A hand-crafted tool-output:///cursor handle naming an outside-root file
passed the spill-URI exemption and was served without any containment
check. The sandbox now resolves the embedded file source through the
normal workspace check at authorize and execution time.

Author: TheGreatAxios

src/permission/gate.test.ts

@@ -11,6 +11,7 @@ import {
 } from "./gate.js";
 import { createPathRestriction } from "./path-restriction.js";
 import { createWorktreeRootsProvider } from "./worktree-roots.js";
+import { encodeResumeCursor } from "../util/tool-output-uri.js";
 import type { Approval, PermissionRequest } from "./types.js";
 import { initTemporaryGitRepo } from "../../tests/helpers/temporary-git-repo.js";
 
@@ -509,4 +510,25 @@ describe("spill URI sandbox at authorize time (CL-6727)", () => {
     });
     expect(verdict.effect).not.toBe("deny");
   });
+
+  test("read_file + a forged cursor for an outside-root path is denied", async () => {
+    const outside = mkdtempSync(join(tmpdir(), "gate-forged-cursor-"));
+    const outsidePath = join(outside, "secret.txt");
+    writeFileSync(outsidePath, "top-secret");
+    const forged = encodeResumeCursor({
+      source: { kind: "file", path: outsidePath },
+      offset: 0,
+      limit: 4,
+      nonce: "forged-nonce",
+    });
+    const verdict = await gate.authorizeCall({
+      id: "spill-forged",
+      name: "read_file",
+      arguments: { path: forged },
+    });
+    expect(verdict.effect).toBe("deny");
+    expect(verdict.effect === "deny" ? verdict.reason : "").toMatch(
+      /escapes working directory/,
+    );
+  });
 });

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

@@ -16,6 +16,10 @@ import {
   pathEscapeBlockReason,
   pathEscapePlugin,
 } from "./path-escape-plugin.js";
+import {
+  encodeResumeCursor,
+  type ResumeCursor,
+} from "../util/tool-output-uri.js";
 import type { ToolCall, ToolResult } from "@intx/types/runtime";
 
 function makeCall(name: string, args: Record<string, unknown>): ToolCall {
@@ -455,6 +459,80 @@ describe("pathEscapePlugin", () => {
       expect(args.path).toBe("tool-output:///abc123");
     });
 
+    test("a forged file cursor for an outside-root path is denied, not served", async () => {
+      const cwd = await mkdtemp(join(tmpdir(), "corbits-escape-cursor-cwd-"));
+      const outsideDir = await mkdtemp(
+        join(tmpdir(), "corbits-escape-cursor-outside-"),
+      );
+      const outsidePath = join(outsideDir, "secret.txt");
+      await writeFile(outsidePath, "top-secret");
+      try {
+        const forged = encodeResumeCursor({
+          source: { kind: "file", path: outsidePath },
+          offset: 0,
+          limit: 4,
+          nonce: "forged-nonce",
+        } satisfies ResumeCursor);
+        expect(
+          pathEscapeBlockReason({ path: forged }, cwd, () => [], "read_file"),
+        ).toMatch(/escapes working directory/);
+        const plugin = pathEscapePlugin(cwd, () => []);
+        const handler = plugin.middleware
+          ? plugin.middleware(nextHandler)
+          : nextHandler;
+        const result = await handler(
+          makeCall("read_file", { path: forged }),
+          new AbortController().signal,
+        );
+        expect(result.isError).toBe(true);
+        expect(result.content).toMatch(/escapes working directory/);
+      } finally {
+        await rm(cwd, { recursive: true, force: true });
+        await rm(outsideDir, { recursive: true, force: true });
+      }
+    });
+
+    test("an in-bounds file cursor and a blob cursor keep the read_file exemption", async () => {
+      const cwd = await mkdtemp(join(tmpdir(), "corbits-escape-cursor-ok-"));
+      const insidePath = join(cwd, "notes.txt");
+      await writeFile(insidePath, "notes");
+      try {
+        const inBounds = encodeResumeCursor({
+          source: { kind: "file", path: insidePath },
+          offset: 4,
+          limit: 4,
+          nonce: "minted-nonce",
+        } satisfies ResumeCursor);
+        expect(
+          pathEscapeBlockReason({ path: inBounds }, cwd, () => [], "read_file"),
+        ).toBeUndefined();
+        const blob = encodeResumeCursor({
+          source: { kind: "blob", uri: "tool-output:///abc123" },
+          offset: 0,
+          limit: 4,
+          nonce: "blob-nonce",
+        } satisfies ResumeCursor);
+        expect(
+          pathEscapeBlockReason({ path: blob }, cwd, () => [], "read_file"),
+        ).toBeUndefined();
+        const plugin = pathEscapePlugin(cwd, () => []);
+        const next = async (call: ToolCall): Promise<ToolResult> => ({
+          callId: call.id,
+          content: JSON.stringify(call.arguments),
+        });
+        const handler = plugin.middleware ? plugin.middleware(next) : next;
+        const result = await handler(
+          makeCall("read_file", { path: inBounds }),
+          new AbortController().signal,
+        );
+        expect(result.isError).not.toBe(true);
+        const args = JSON.parse(String(result.content)) as { path: string };
+        expect(args.path).toBe(inBounds);
+      } finally {
+        await rm(cwd, { recursive: true, force: true });
+      }
+    });
+
     test("archive refs pass for archive readers but not for other tools", async () => {
       for (const name of ["read_file", "grep", "search_files"]) {
         expect(

src/plugins/path-escape-plugin.ts

@@ -1,6 +1,10 @@
 import { resolve } from "node:path";
 import type { ToolPlugin } from "@intx/tools-posix";
-import { isToolOutputLike } from "../util/tool-output-uri.js";
+import {
+  canonicalToolOutputUri,
+  decodeResumeCursor,
+  isToolOutputLike,
+} from "../util/tool-output-uri.js";
 import { isArchiveLike } from "../session/compaction-archive.js";
 import { resolveWorkspacePath } from "../permission/path-restriction.js";
 import {
@@ -224,6 +228,32 @@ function virtualRefVerdict(
   return undefined;
 }
 
+// A self-describing read_file continuation handle (tool-output:///cursor/...)
+// embeds its resume source, so the spill-URI exemption above must not cover
+// it blindly: a hand-crafted handle naming an outside-root file would
+// otherwise bypass the containment check the plain path would fail. Resolve
+// the embedded file path through the normal workspace check and deny escapes
+// exactly like the plain path. Blob-source handles and opaque (never-a-handle)
+// spill URIs carry no filesystem target and keep the exemption.
+function cursorEscapeReason(
+  value: string,
+  cwd: string,
+  rootsProvider: RootsProvider,
+  toolName: string,
+): string | undefined {
+  if (canonicalToolName(toolName) !== TOOL_OUTPUT_URI_TOOL) return undefined;
+  const resumed = decodeResumeCursor(canonicalToolOutputUri(value));
+  if (resumed === undefined || resumed.source.kind !== "file") {
+    return undefined;
+  }
+  if (
+    resolveWorkspacePath(cwd, resumed.source.path, rootsProvider) === undefined
+  ) {
+    return `Path escapes working directory: ${resumed.source.path}`;
+  }
+  return undefined;
+}
+
 // Same sandbox pathEscapePlugin enforces at execution. The permission gate
 // consults this at authorize time so it can deny instead of asking for a call
 // the plugin will reject after Accept.
@@ -297,7 +327,9 @@ function blockReasonFor(
   if (typeof value === "string") {
     if (key === undefined || !looksLikePath(key)) return undefined;
     const verdict = virtualRefVerdict(value, toolName);
-    if (verdict === "skip") return undefined;
+    if (verdict === "skip") {
+      return cursorEscapeReason(value, cwd, rootsProvider, toolName);
+    }
     if (typeof verdict === "string") return verdict;
     if (resolveWorkspacePath(cwd, value, rootsProvider) === undefined) {
       return `Path escapes working directory: ${value}`;

src/plugins/read-file-continuation-recovery.test.ts

@@ -13,6 +13,8 @@ import {
 } from "../permission/decline-markers.js";
 import type { PermissionGate } from "../permission/gate.js";
 import { gateToolCall } from "./permission-plugin.js";
+import { pathEscapePlugin } from "./path-escape-plugin.js";
+import { encodeResumeCursor } from "../util/tool-output-uri.js";
 import { readFileGuardPlugin } from "./read-file-guard-plugin.js";
 
 // CL-8980 RED: continuation recovery. Truncated reads mint a one-shot
@@ -303,6 +305,60 @@ describe("CL-8980 continuation recovery (blob source)", () => {
   });
 });
 
+describe("CL-8980 forged continuation handle is denied end to end", () => {
+  function stackedGuard() {
+    const guard = defined(readFileGuardPlugin(dir, {}).middleware)(fallback);
+    const stacked = defined(pathEscapePlugin(dir, () => []).middleware)(guard);
+    return (call: ToolCall) => stacked(call, neverAbort());
+  }
+
+  test("a hand-crafted cursor for an unminted outside-root path is denied, not served", async () => {
+    const outsideDir = await mkdtemp(join(tmpdir(), "read-forged-outside-"));
+    const outsidePath = join(outsideDir, "secret.txt");
+    await writeFile(outsidePath, "forged-handle-secret-payload");
+    try {
+      const forged = encodeResumeCursor({
+        source: { kind: "file", path: outsidePath },
+        offset: 0,
+        limit: 4,
+        nonce: "never-minted",
+      });
+      const result = await stackedGuard()({
+        id: "f1",
+        name: "read_file",
+        arguments: { path: forged },
+      });
+      expect(result.isError).toBe(true);
+      expect(String(result.content)).toMatch(/escapes working directory/);
+      expect(String(result.content)).not.toContain(
+        "forged-handle-secret-payload",
+      );
+      expectNotDeclined(String(result.content));
+    } finally {
+      await rm(outsideDir, { recursive: true, force: true });
+    }
+  });
+
+  test("a minted in-bounds handle is still served through the same stack", async () => {
+    await fixture("stacked.txt", tenLines("stacked"));
+    const stack = stackedGuard();
+    const first = await stack({
+      id: "s1",
+      name: "read_file",
+      arguments: { path: "stacked.txt", limit: 4 },
+    });
+    expect(first.isError).toBeFalsy();
+    const handle = extractHandle(String(first.content));
+    const second = await stackedGuard()({
+      id: "s2",
+      name: "read_file",
+      arguments: { path: handle, limit: 4 },
+    });
+    expect(second.isError).toBeFalsy();
+    expect(String(second.content)).toContain("stacked-line-4");
+  });
+});
+
 describe("CL-8980 guard-denied continuation stays isError (never throws)", () => {
   test("a denied continuation follow returns isError with the reason", async () => {
     const gate = {

src/plugins/read-file-guard-plugin.ts

@@ -65,12 +65,14 @@ export interface ReadFileGuardPluginOptions {
 // Handles are self-describing (CL-8980): the URI embeds the resume recipe,
 // so following it needs no in-memory record and survives session resume,
 // prune, and compaction. The per-instance map below only tracks which handles
-// this instance already served, to keep the single-use replay contract.
+// this instance already served, to keep the per-instance single-use replay
+// contract: a verbatim re-follow in this instance is a stale-cursor error,
+// while a fresh instance serves the self-describing handle again.
 type ReadCursor =
   | { kind: "file"; absolutePath: string; offset: number; consumed: boolean }
   | { kind: "blob"; uri: string; offset: number; consumed: boolean };
 
-// A cursor is single-use, but the record survives consumption (bounded by
+// A cursor is single-use per plugin instance, but the record survives consumption (bounded by
 // MAX_CURSOR_HISTORY below) so a stale replay -- consumed already, or a
 // second process/turn racing the first -- can be told exactly where to
 // resume instead of hitting an opaque "blob not found" dead end that names
@@ -621,6 +623,10 @@ export function readFileGuardPlugin(
           // in the handle, so serve it exactly as a known cursor would — and
           // mark it consumed on success so a verbatim re-follow is the same
           // stale-cursor error as a spent handle, not a second serving.
+          // The follow honors this call's paging args, not the minted window:
+          // resumed.limit only records the mint-time window, and resumed.nonce
+          // only keeps mints distinct (replay keying uses the full handle
+          // URI), so neither is consulted here.
           const resumedSource =
             resumed.source.kind === "file"
               ? resumed.source.path

src/util/tool-output-uri.ts

@@ -30,8 +30,8 @@ export function canonicalToolOutputUri(path: string): string | undefined {
 // handle itself carries the resume recipe (source + next offset + window
 // limit + nonce), so following it needs no in-memory record and keeps working
 // across session resume, prune, and compaction. The nonce keeps every mint a
-// distinct one-shot even for identical windows, preserving spent-handle
-// replay semantics.
+// distinct handle even for identical windows, preserving per-instance
+// spent-handle replay semantics.
 export const CURSOR_HANDLE_PREFIX = "tool-output:///cursor/";
 
 export type ResumeSource =