@stigmer/runner 3.12.0 → 3.12.1

package/src/activities/execute-deep-agent/__tests__/attachment-injector.test.ts

@@ -1,5 +1,4 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { deflateRawSync } from "node:zlib";
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -15,130 +14,42 @@ import {
 } from "../attachment-injector.js";
 import { mockWorkspaceBackend } from "../../../__test-utils__/mock-workspace.js";
 import { makeInMemoryArtifactStorage } from "../../../__test-utils__/fake-artifact-storage.js";
+import { buildZip, type ZipFixtureFile } from "../../../__test-utils__/zip-fixtures.js";
 import {
   DEEP_AGENT_VISION_PROFILE,
   VisionBudget,
 } from "../../../shared/attachment-vision.js";
 
 // ── ZIP Construction Helpers ─────────────────────────────────────────
+//
+// All archives come from the shared real-shape builder (zip-fixtures.ts):
+// local headers, payloads, central directory, EOCD — the only shape real
+// ZIP writers produce and the shape central-directory parsing requires.
+// The record-form helpers below keep ordinary call sites terse; tests that
+// need streaming or declared-size shapes call buildZip directly.
 
 function makeZip(entries: Record<string, string | Buffer>): Buffer {
-  const parts: Buffer[] = [];
-  const centralDir: Buffer[] = [];
-  let offset = 0;
-
-  for (const [name, content] of Object.entries(entries)) {
-    const nameBytes = Buffer.from(name, "utf-8");
-    const contentBytes = typeof content === "string" ? Buffer.from(content, "utf-8") : content;
-    const compressed = deflateRawSync(contentBytes);
-
-    // Local file header
-    const header = Buffer.alloc(30);
-    header.writeUInt32LE(0x04034b50, 0); // signature
-    header.writeUInt16LE(20, 4);          // version needed
-    header.writeUInt16LE(0, 6);           // flags
-    header.writeUInt16LE(8, 8);           // compression: deflate
-    header.writeUInt16LE(0, 10);          // mod time
-    header.writeUInt16LE(0, 12);          // mod date
-    header.writeUInt32LE(0, 14);          // crc32 (skip for tests)
-    header.writeUInt32LE(compressed.length, 18);  // compressed size
-    header.writeUInt32LE(contentBytes.length, 22); // uncompressed size
-    header.writeUInt16LE(nameBytes.length, 26);    // filename length
-    header.writeUInt16LE(0, 28);                   // extra field length
-
-    parts.push(header, nameBytes, compressed);
-
-    // Central directory entry
-    const cdEntry = Buffer.alloc(46);
-    cdEntry.writeUInt32LE(0x02014b50, 0);
-    cdEntry.writeUInt16LE(20, 4);
-    cdEntry.writeUInt16LE(20, 6);
-    cdEntry.writeUInt16LE(0, 8);
-    cdEntry.writeUInt16LE(8, 10);
-    cdEntry.writeUInt16LE(0, 12);
-    cdEntry.writeUInt16LE(0, 14);
-    cdEntry.writeUInt32LE(0, 16);
-    cdEntry.writeUInt32LE(compressed.length, 20);
-    cdEntry.writeUInt32LE(contentBytes.length, 24);
-    cdEntry.writeUInt16LE(nameBytes.length, 28);
-    cdEntry.writeUInt16LE(0, 30);
-    cdEntry.writeUInt16LE(0, 32);
-    cdEntry.writeUInt16LE(0, 34);
-    cdEntry.writeUInt16LE(0, 36);
-    cdEntry.writeUInt32LE(0, 38);
-    cdEntry.writeUInt32LE(offset, 42);
-    centralDir.push(cdEntry, nameBytes);
-
-    offset += header.length + nameBytes.length + compressed.length;
-  }
-
-  // End of central directory
-  const eocd = Buffer.alloc(22);
-  const cdSize = centralDir.reduce((s, b) => s + b.length, 0);
-  eocd.writeUInt32LE(0x06054b50, 0);
-  eocd.writeUInt16LE(0, 4);
-  eocd.writeUInt16LE(0, 6);
-  eocd.writeUInt16LE(Object.keys(entries).length, 8);
-  eocd.writeUInt16LE(Object.keys(entries).length, 10);
-  eocd.writeUInt32LE(cdSize, 12);
-  eocd.writeUInt32LE(offset, 16);
-  eocd.writeUInt16LE(0, 20);
-
-  return Buffer.concat([...parts, ...centralDir, eocd]);
+  return makeZipWith(entries, { method: "deflated" });
 }
 
 function makeStoredZip(entries: Record<string, Buffer>): Buffer {
-  const parts: Buffer[] = [];
-  let offset = 0;
-
-  for (const [name, content] of Object.entries(entries)) {
-    const nameBytes = Buffer.from(name, "utf-8");
-
-    const header = Buffer.alloc(30);
-    header.writeUInt32LE(0x04034b50, 0);
-    header.writeUInt16LE(20, 4);
-    header.writeUInt16LE(0, 6);
-    header.writeUInt16LE(0, 8);  // stored (no compression)
-    header.writeUInt32LE(content.length, 18);
-    header.writeUInt32LE(content.length, 22);
-    header.writeUInt16LE(nameBytes.length, 26);
-    header.writeUInt16LE(0, 28);
-
-    parts.push(header, nameBytes, content);
-    offset += header.length + nameBytes.length + content.length;
-  }
-
-  // Minimal EOCD
-  const eocd = Buffer.alloc(22);
-  eocd.writeUInt32LE(0x06054b50, 0);
-  eocd.writeUInt16LE(Object.keys(entries).length, 8);
-  eocd.writeUInt16LE(Object.keys(entries).length, 10);
-  eocd.writeUInt32LE(0, 12);
-  eocd.writeUInt32LE(offset, 16);
+  return makeZipWith(entries, { method: "stored" });
+}
 
-  return Buffer.concat([...parts, eocd]);
+function makeZipWith(
+  entries: Record<string, string | Buffer>,
+  shape: Pick<ZipFixtureFile, "method" | "streaming">,
+): Buffer {
+  const files: ZipFixtureFile[] = Object.entries(entries).map(([name, content]) => ({
+    name,
+    content: typeof content === "string" ? content : new Uint8Array(content),
+    ...shape,
+  }));
+  return Buffer.from(buildZip(files));
 }
 
 function makeDirectoryOnlyZip(): Buffer {
-  const name = "empty_dir/";
-  const nameBytes = Buffer.from(name, "utf-8");
-
-  const header = Buffer.alloc(30);
-  header.writeUInt32LE(0x04034b50, 0);
-  header.writeUInt16LE(20, 4);
-  header.writeUInt16LE(0, 6);
-  header.writeUInt16LE(0, 8);
-  header.writeUInt32LE(0, 18);
-  header.writeUInt32LE(0, 22);
-  header.writeUInt16LE(nameBytes.length, 26);
-  header.writeUInt16LE(0, 28);
-
-  const eocd = Buffer.alloc(22);
-  eocd.writeUInt32LE(0x06054b50, 0);
-  eocd.writeUInt16LE(1, 8);
-  eocd.writeUInt16LE(1, 10);
-
-  return Buffer.concat([header, nameBytes, eocd]);
+  return Buffer.from(buildZip([{ name: "empty_dir/", content: "" }]));
 }
 
 function makeAttachment(overrides: Partial<{
@@ -251,22 +162,7 @@ describe("validateZipForExtraction", () => {
   });
 
   it("rejects null bytes in filenames", () => {
-    const nameWithNull = "file\x00.txt";
-    const nameBytes = Buffer.from(nameWithNull, "utf-8");
-    const content = Buffer.from("test");
-    const compressed = deflateRawSync(content);
-
-    const header = Buffer.alloc(30);
-    header.writeUInt32LE(0x04034b50, 0);
-    header.writeUInt16LE(20, 4);
-    header.writeUInt16LE(0, 6);
-    header.writeUInt16LE(8, 8);
-    header.writeUInt32LE(compressed.length, 18);
-    header.writeUInt32LE(content.length, 22);
-    header.writeUInt16LE(nameBytes.length, 26);
-    header.writeUInt16LE(0, 28);
-
-    const zip = Buffer.concat([header, nameBytes, compressed]);
+    const zip = makeZip({ "file\u0000.txt": "test" });
     expect(() => validateZipForExtraction(zip, "null.zip"))
       .toThrow(/null bytes/);
   });
@@ -305,6 +201,149 @@ describe("validateZipForExtraction", () => {
   });
 });
 
+// ═══════════════════════════════════════════════════════════════════════
+// Central-directory parsing (issue #567)
+// ═══════════════════════════════════════════════════════════════════════
+// The archive shapes the old local-header walk corrupted or rejected:
+// stored streaming entries (silent manifest truncation) and Go-default
+// deflated streaming entries (rejected outright). Sizes come from the
+// central directory — the format's authoritative index — and structural
+// failures are fail-hard, unlike the skill-artifact reader's non-fatal
+// empty return: nothing upstream vouches for an attachment.
+
+describe("validateZipForExtraction — central-directory parsing (issue #567)", () => {
+  it("validates every entry of a stored streaming archive (no silent truncation)", () => {
+    // Method 0 + flag bit 3 + zeroed local sizes: the old walk admitted the
+    // first entry with size 0, landed mid-payload, and quietly dropped the
+    // rest of the manifest.
+    const zip = Buffer.from(buildZip([
+      { name: "first.txt", content: "first file content", streaming: true },
+      { name: "second.txt", content: "second file content", streaming: true },
+    ]));
+
+    const result = validateZipForExtraction(zip, "streamed.zip");
+    expect(result.map((e) => e.relativePath)).toEqual(["first.txt", "second.txt"]);
+    expect(result.map((e) => e.uncompressedSize)).toEqual([
+      "first file content".length,
+      "second file content".length,
+    ]);
+  });
+
+  it("accepts a Go-default archive (deflated streaming entries)", () => {
+    const zip = Buffer.from(buildZip([
+      { name: "main.go", content: "package main", method: "deflated", streaming: true },
+      { name: "go.mod", content: "module example", method: "deflated", streaming: true },
+    ]));
+
+    const result = validateZipForExtraction(zip, "go-built.zip");
+    expect(result.map((e) => e.relativePath)).toEqual(["go.mod", "main.go"]);
+  });
+
+  it("rejects an archive with no central directory (fail-hard, unlike skill extraction)", () => {
+    const zip = Buffer.from(buildZip(
+      [{ name: "a.txt", content: "aaa" }],
+      { omitCentralDirectory: true },
+    ));
+
+    expect(() => validateZipForExtraction(zip, "truncated.zip"))
+      .toThrow(AttachmentValidationError);
+    expect(() => validateZipForExtraction(zip, "truncated.zip"))
+      .toThrow(/not a valid ZIP archive/);
+  });
+
+  it("rejects duplicate entry paths (a contradictory manifest)", () => {
+    const zip = Buffer.from(buildZip([
+      { name: "dup.txt", content: "one" },
+      { name: "dup.txt", content: "two" },
+    ]));
+
+    expect(() => validateZipForExtraction(zip, "dup.zip"))
+      .toThrow(/duplicate entry/);
+  });
+
+  it("locates the central directory behind a trailing archive comment", () => {
+    const zip = Buffer.from(buildZip(
+      [{ name: "a.txt", content: "aaa" }],
+      { comment: "release archive — built by tooling" },
+    ));
+
+    const result = validateZipForExtraction(zip, "commented.zip");
+    expect(result.map((e) => e.relativePath)).toEqual(["a.txt"]);
+  });
+});
+
+describe("injectAttachments — central-directory extraction (issue #567)", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "attachment-cd-"));
+  });
+
+  async function extractArchive(zip: Uint8Array) {
+    const localFile = join(tempDir, "archive.zip");
+    await writeFile(localFile, zip);
+    const backend = mockWorkspaceBackend();
+    const result = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "archive.zip",
+        mountPath: ".stigmer/inputs/archive",
+        extract: true,
+        localPath: localFile,
+      })],
+      storage: makeMockStorage(),
+      isLocalMode: true,
+    });
+    return { backend, result };
+  }
+
+  it("extracts a stored streaming archive completely, contents intact", async () => {
+    const { backend, result } = await extractArchive(buildZip([
+      { name: "first.txt", content: "first file content", streaming: true },
+      { name: "second.txt", content: "second file content", streaming: true },
+    ]));
+
+    expect(result.map((f) => f.path).sort()).toEqual([
+      ".stigmer/inputs/archive/first.txt",
+      ".stigmer/inputs/archive/second.txt",
+    ]);
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/archive/first.txt", Buffer.from("first file content"),
+    );
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/archive/second.txt", Buffer.from("second file content"),
+    );
+  });
+
+  it("extracts a Go-default deflated streaming archive", async () => {
+    const { backend, result } = await extractArchive(buildZip([
+      { name: "src/main.go", content: "package main\n", method: "deflated", streaming: true },
+    ]));
+
+    expect(result).toHaveLength(1);
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/archive/src/main.go", Buffer.from("package main\n"),
+    );
+  });
+
+  it("aborts when an entry inflates past its declared size (crafted archive)", async () => {
+    await expect(extractArchive(buildZip([
+      {
+        name: "bomb.txt",
+        content: "x".repeat(4096),
+        method: "deflated",
+        declaredUncompressedSize: 16,
+      },
+    ]))).rejects.toThrow(AttachmentValidationError);
+  });
+
+  it("aborts when a stored entry's payload disagrees with its declared size", async () => {
+    await expect(extractArchive(buildZip([
+      { name: "short.txt", content: "eleven byte", declaredUncompressedSize: 4096 },
+    ]))).rejects.toThrow(/declare/);
+  });
+});
+
 // ═══════════════════════════════════════════════════════════════════════
 // injectAttachments
 // ═══════════════════════════════════════════════════════════════════════

package/src/activities/execute-deep-agent/__tests__/plan-mode-path-normalization.test.ts

@@ -1,19 +1,23 @@
 /**
  * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that
- * a plan-mode PARENT graph accepts workspace-relative paths (issue #429).
+ * a plan-mode PARENT graph accepts workspace-relative paths (issue #429) and
+ * scopes reads to the workspace (issue #528).
  *
- * Before the fix, deepagents' permission enforcement canonicalized every
+ * Before the #429 fix, deepagents' permission enforcement canonicalized every
  * filesystem tool-call path BEFORE any rule ran and refused non-absolute
  * shapes, so on a rule-bearing graph a workspace-relative call — reads
  * included — died with `path must be absolute` instead of just working. The
  * path-normalization middleware (middleware/path-normalization.ts) rewrites
  * relative paths to workspace-absolute at our seam, before enforcement sees
- * them.
+ * them. #528 then made the workspace the READ boundary (owner ruling): the
+ * rules deny out-of-root reads, the middleware fills the ls/glob/grep
+ * omitted-path case (whose schema default is the OS root), and the
+ * `.stigmer` symlink keeps platform-dir reads in-root as path strings.
  *
  * The graph here is composed exactly the way setup.ts composes the parent:
  * the PRODUCTION buildMiddlewareStack (pathNormalization present, the
  * rule-bearing shape) + the CAS capture backend + the PRODUCTION
- * PLAN_MODE_PERMISSIONS constant. These tests are also the empirical proof
+ * buildPlanModePermissions rules. These tests are also the empirical proof
  * that langchain's wrapToolCall seam delivers rewritten args to the tool —
  * if it did not, the relative read below could never succeed.
  *
@@ -22,20 +26,56 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtemp, mkdir, rm, readFile, writeFile, access } from "node:fs/promises";
+import { mkdtemp, mkdir, rm, readFile, writeFile, access, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { HumanMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
 import { MemorySaver } from "@langchain/langgraph";
 import { createDeepAgent } from "deepagents";
 
-import { PLAN_MODE_PERMISSIONS } from "../../../shared/plan-mode-permissions.js";
+import { buildPlanModePermissions } from "../../../shared/plan-mode-permissions.js";
 import { buildMiddlewareStack } from "../../../middleware/index.js";
 import { createCasCaptureBackend } from "../cas-capture-backend.js";
 import { CasCaptureObserver } from "../cas-capture-observer.js";
 import { ScriptedModel, type ScriptSelector } from "../__test-utils__/scripted-model.js";
 
 const SEEDED_CONTENT = "PLAN_MODE_README_TOKEN: hello from the seeded file";
+const OUTSIDE_CONTENT = "OUT_OF_ROOT_SECRET_TOKEN: must never cross the boundary";
+const PLATFORM_CONTENT = "PLATFORM_SKILL_TOKEN: reached through the .stigmer symlink";
+
+/**
+ * Build a plan-mode parent graph the way setup.ts does: the production
+ * middleware stack with pathNormalization set (derived, like the graph's
+ * permissions, from the plan-mode rules), a filesystem-only CAS capture
+ * backend (no shellEnv — plan mode clears it), and the production
+ * buildPlanModePermissions rules on the graph.
+ */
+async function buildPlanModeParent(
+  root: string,
+  observer: CasCaptureObserver,
+  script: ScriptSelector,
+) {
+  const { middleware } = buildMiddlewareStack({
+    approvalGate: null,
+    pathNormalization: { rootDir: root },
+  });
+  const backend = await createCasCaptureBackend({ rootDir: root, observer });
+  return createDeepAgent({
+    model: new ScriptedModel(script),
+    checkpointer: new MemorySaver() as never,
+    backend,
+    middleware: middleware as never[],
+    permissions: buildPlanModePermissions(root),
+  } as Parameters<typeof createDeepAgent>[0]);
+}
+
+function toolResultById(messages: BaseMessage[], toolCallId: string): string {
+  const match = messages.find(
+    (m): m is ToolMessage => m instanceof ToolMessage && m.tool_call_id === toolCallId,
+  );
+  expect(match, `expected a tool result for call '${toolCallId}'`).toBeDefined();
+  return typeof match!.content === "string" ? match!.content : JSON.stringify(match!.content);
+}
 
 describe("plan-mode parent path normalization (issue #429)", () => {
   let root: string;
@@ -52,38 +92,8 @@ describe("plan-mode parent path normalization (issue #429)", () => {
     await rm(root, { recursive: true, force: true });
   });
 
-  /**
-   * Build a parent graph the way setup.ts does in plan mode: the production
-   * middleware stack with pathNormalization set (derived, like the graph's
-   * permissions, from the plan-mode rules), a filesystem-only CAS capture
-   * backend (no shellEnv — plan mode clears it), and PLAN_MODE_PERMISSIONS
-   * on the graph.
-   */
-  async function buildPlanModeParent(script: ScriptSelector) {
-    const { middleware } = buildMiddlewareStack({
-      approvalGate: null,
-      pathNormalization: { rootDir: root },
-    });
-    const backend = await createCasCaptureBackend({ rootDir: root, observer });
-    return createDeepAgent({
-      model: new ScriptedModel(script),
-      checkpointer: new MemorySaver() as never,
-      backend,
-      middleware: middleware as never[],
-      permissions: PLAN_MODE_PERMISSIONS,
-    } as Parameters<typeof createDeepAgent>[0]);
-  }
-
-  function toolResultById(messages: BaseMessage[], toolCallId: string): string {
-    const match = messages.find(
-      (m): m is ToolMessage => m instanceof ToolMessage && m.tool_call_id === toolCallId,
-    );
-    expect(match, `expected a tool result for call '${toolCallId}'`).toBeDefined();
-    return typeof match!.content === "string" ? match!.content : JSON.stringify(match!.content);
-  }
-
   async function invokeOnce(script: ScriptSelector, threadId: string) {
-    const agent = await buildPlanModeParent(script);
+    const agent = await buildPlanModeParent(root, observer, script);
     return (await agent.invoke(
       { messages: [new HumanMessage({ content: "go" })] },
       { configurable: { thread_id: threadId }, recursionLimit: 50 },
@@ -172,3 +182,202 @@ describe("plan-mode parent path normalization (issue #429)", () => {
     expect(lsResult).not.toMatch(/path must be absolute/i);
   });
 });
+
+describe("plan-mode workspace read boundary (issue #528)", () => {
+  let root: string;
+  let outside: string;
+  let platform: string;
+  let observer: CasCaptureObserver;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "plan-bound-"));
+    outside = await mkdtemp(join(tmpdir(), "plan-outside-"));
+    platform = await mkdtemp(join(tmpdir(), "plan-platform-"));
+
+    await mkdir(join(root, "src"), { recursive: true });
+    await writeFile(join(root, "src/notes.md"), SEEDED_CONTENT);
+    await writeFile(join(outside, "secret.txt"), OUTSIDE_CONTENT);
+
+    // The production shape from shared/workspace/stigmer-link.ts: the
+    // platform dir lives OUTSIDE the workspace, reached through an in-root
+    // symlink — its path STRINGS are in-root, which is what the rules match.
+    await mkdir(join(platform, "skills"), { recursive: true });
+    await writeFile(join(platform, "skills/guide.md"), PLATFORM_CONTENT);
+    await symlink(platform, join(root, ".stigmer"));
+
+    observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+    await rm(platform, { recursive: true, force: true });
+  });
+
+  async function invokeOnce(script: ScriptSelector, threadId: string) {
+    const agent = await buildPlanModeParent(root, observer, script);
+    return (await agent.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: threadId }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+  }
+
+  it("denies an out-of-root absolute read — the exposure #429 deliberately preserved is closed", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "read_file", args: { file_path: join(outside, "secret.txt") }, id: "c_read_out" },
+        ],
+        done: "done",
+      }),
+      "t_read_out",
+    );
+
+    const readResult = toolResultById(result.messages, "c_read_out");
+    expect(readResult).toMatch(/permission denied for read/i);
+    expect(readResult).not.toContain("OUT_OF_ROOT_SECRET_TOKEN");
+  });
+
+  it("lists the workspace root itself — {root}/** admits the root, not just its subtree", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [{ name: "ls", args: { path: root }, id: "c_ls_root" }],
+        done: "done",
+      }),
+      "t_ls_root",
+    );
+
+    const lsResult = toolResultById(result.messages, "c_ls_root");
+    expect(lsResult).toContain("src");
+    expect(lsResult).not.toMatch(/permission denied/i);
+  });
+
+  it("reads platform-dir material through the .stigmer symlink — in-root strings, out-of-root bytes", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "read_file", args: { file_path: join(root, ".stigmer/skills/guide.md") }, id: "c_read_skill" },
+        ],
+        done: "done",
+      }),
+      "t_read_skill",
+    );
+
+    const readResult = toolResultById(result.messages, "c_read_skill");
+    expect(readResult).toContain("PLATFORM_SKILL_TOKEN");
+    expect(readResult).not.toMatch(/permission denied/i);
+  });
+
+  it("a bare ls (no path argument) lists the workspace, not the OS root", async () => {
+    // The tool's schema default is "/" — the OS root — applied inside the
+    // tool, after the middleware seam. The middleware fills the omission
+    // with the workspace root, so the model's first listing just works.
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [{ name: "ls", args: {}, id: "c_ls_bare" }],
+        done: "done",
+      }),
+      "t_ls_bare",
+    );
+
+    const lsResult = toolResultById(result.messages, "c_ls_bare");
+    expect(lsResult).toContain("src");
+    expect(lsResult).not.toMatch(/permission denied/i);
+  });
+
+  it("a bare grep (no path argument) searches the workspace, not the whole filesystem", async () => {
+    // Pre-#528, a bare grep recursively scanned the ENTIRE OS filesystem
+    // (schema default "/" + the legacy backend's literal pass-through).
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "grep", args: { pattern: "PLAN_MODE_README_TOKEN" }, id: "c_grep_bare" },
+        ],
+        done: "done",
+      }),
+      "t_grep_bare",
+    );
+
+    const grepResult = toolResultById(result.messages, "c_grep_bare");
+    expect(grepResult).toContain("notes.md");
+    expect(grepResult).not.toMatch(/permission denied/i);
+  });
+
+  it("an explicit ls of '/' is denied honestly — not silently redirected to the workspace", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [{ name: "ls", args: { path: "/" }, id: "c_ls_slash" }],
+        done: "done",
+      }),
+      "t_ls_slash",
+    );
+
+    expect(toolResultById(result.messages, "c_ls_slash")).toMatch(
+      /permission denied for read on \//i,
+    );
+  });
+
+  it("writes stay denied everywhere — the read-allow rule admits reads only", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "write_file", args: { file_path: join(root, "src/out.txt"), content: "x" }, id: "c_write_in" },
+        ],
+        done: "done",
+      }),
+      "t_write_in",
+    );
+
+    expect(toolResultById(result.messages, "c_write_in")).toMatch(/permission denied for write/i);
+    await expect(access(join(root, "src/out.txt"))).rejects.toThrow();
+  });
+});
+
+describe("plan-mode read boundary with a glob-special workspace root (issue #528)", () => {
+  // Desktop localPath workspaces use the user's real project directory AS
+  // the root — names like "My (work) [v2]" are legal there. This suite pins
+  // escapeGlobLiteral against deepagents' real matcher end-to-end: without
+  // escaping, the read-allow rule would silently never match and every
+  // plan-mode read in such a workspace would be denied.
+  let base: string;
+  let root: string;
+  let observer: CasCaptureObserver;
+
+  beforeEach(async () => {
+    base = await mkdtemp(join(tmpdir(), "plan-glob-"));
+    root = join(base, "My (work) [v2]");
+    await mkdir(join(root, "src"), { recursive: true });
+    await writeFile(join(root, "src/notes.md"), SEEDED_CONTENT);
+    observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+  });
+
+  afterEach(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+
+  async function invokeOnce(script: ScriptSelector, threadId: string) {
+    const agent = await buildPlanModeParent(root, observer, script);
+    return (await agent.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: threadId }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+  }
+
+  it("in-root reads work, absolute and relative alike; out-of-root reads stay denied", async () => {
+    const result = await invokeOnce(
+      () => ({
+        toolCalls: [
+          { name: "read_file", args: { file_path: join(root, "src/notes.md") }, id: "c_abs" },
+          { name: "read_file", args: { file_path: "src/notes.md" }, id: "c_rel" },
+          { name: "read_file", args: { file_path: "/etc/hosts" }, id: "c_out" },
+        ],
+        done: "done",
+      }),
+      "t_glob_root",
+    );
+
+    expect(toolResultById(result.messages, "c_abs")).toContain("PLAN_MODE_README_TOKEN");
+    expect(toolResultById(result.messages, "c_rel")).toContain("PLAN_MODE_README_TOKEN");
+    expect(toolResultById(result.messages, "c_out")).toMatch(/permission denied for read/i);
+  });
+});

package/src/activities/execute-deep-agent/__tests__/prompt-builder.test.ts

@@ -422,14 +422,19 @@ describe("buildEnhancedSystemPrompt", () => {
       injectedFiles: [],
     };
 
-    it("appends the shared plan-mode directive as the final section", () => {
+    it("appends the shared plan-mode directive plus the native-only read-boundary line as the final section", () => {
       const prompt = buildEnhancedSystemPrompt({
         ...base,
         interactionMode: InteractionMode.PLAN,
       });
 
       expect(prompt).toContain("## Plan mode");
-      expect(prompt.endsWith(PLAN_MODE_DIRECTIVE)).toBe(true);
+      expect(prompt).toContain(PLAN_MODE_DIRECTIVE);
+      // The read boundary (issue #528) is enforced only on the native
+      // harness, so its sentence rides OUTSIDE the shared directive — after
+      // it, still in the plan-mode section.
+      expect(prompt.endsWith("paths outside it are refused.")).toBe(true);
+      expect(PLAN_MODE_DIRECTIVE).not.toContain("File reads are limited");
     });
 
     it("omits the directive for Agent mode", () => {