@stigmer/runner 3.12.0 → 3.12.1

package/src/activities/execute-deep-agent/__tests__/subagent-plan-mode-permissions.test.ts

@@ -13,8 +13,8 @@
  * rules (act mode) the same write flows — this change is a plan-mode-only
  * delta.
  *
- * The rule under test is the PRODUCTION constant from
- * shared/plan-mode-permissions.ts (the same one setup.ts applies to both
+ * The rules under test are the PRODUCTION buildPlanModePermissions output
+ * from shared/plan-mode-permissions.ts (the same setup.ts applies to both
  * graph sites), not a test copy, so a change to the plan-mode permission set
  * re-proves sub-agent coverage automatically.
  */
@@ -25,7 +25,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { HumanMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
 
-import { PLAN_MODE_PERMISSIONS } from "../../../shared/plan-mode-permissions.js";
+import { buildPlanModePermissions } from "../../../shared/plan-mode-permissions.js";
 import { CasCaptureObserver } from "../cas-capture-observer.js";
 import { compileSubagents } from "../subagent-transformer.js";
 import { ScriptedModel, type ScriptSelector } from "../__test-utils__/scripted-model.js";
@@ -64,7 +64,7 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
         workspaceRootDir: root,
         casObserver: observer,
         modelFactory: async () => new ScriptedModel(script),
-        ...(planMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
+        ...(planMode ? { permissions: buildPlanModePermissions(root) } : {}),
       },
     );
     expect(compiled).toHaveLength(1);
@@ -175,4 +175,35 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
     expect(readResult).toContain("PLAN_MODE_README_TOKEN");
     expect(readResult).not.toMatch(/path must be absolute/i);
   });
+
+  it("scopes sub-agent reads to the workspace and fills the bare-ls default (issue #528)", async () => {
+    // The read boundary must hold on SUB-AGENT graphs too — they carry their
+    // own rules (issue #255) and their own normalization shim (#429), so a
+    // parent-only fix would leave sub-agents reading anywhere. One turn,
+    // three calls: out-of-root read denied, in-root read flows, bare ls
+    // (whose schema default is the OS root) lists the workspace.
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "read_file", args: { file_path: "/etc/hosts" }, id: "c_read_out" },
+        { name: "read_file", args: { file_path: join(root, "notes.md") }, id: "c_read_in" },
+        { name: "ls", args: {}, id: "c_ls_bare" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t4" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    const outResult = toolResultById(result.messages, "c_read_out");
+    expect(outResult).toMatch(/permission denied for read/i);
+
+    expect(toolResultById(result.messages, "c_read_in")).toContain("PLAN_MODE_README_TOKEN");
+
+    const lsResult = toolResultById(result.messages, "c_ls_bare");
+    expect(lsResult).toContain("notes.md");
+    expect(lsResult).not.toMatch(/permission denied/i);
+  });
 });

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

@@ -5,13 +5,23 @@
  * validates ZIP archives with security guards, and writes files into the
  * workspace via the platform mount namespace (.stigmer/inputs/).
  *
- * Security model: attachments are untrusted user uploads. All ZIP content
- * is validated for path traversal, zip bombs, and format integrity before
- * any extraction occurs.
+ * Security model: attachments are untrusted user uploads. ZIP archives are
+ * parsed from the central directory — the format's authoritative index —
+ * via the shared structural layer (shared/zip-structure.ts; issue #567,
+ * which killed this module's local-header walk: it silently truncated
+ * stored streaming entries and rejected Go-default archives outright).
+ * Every entry is validated for path traversal, zip bombs, and format
+ * integrity BEFORE any extraction occurs, and because the central
+ * directory's sizes are declarations an attacker controls, decompression
+ * re-enforces them: an entry whose actual output disagrees with its
+ * declared size aborts the injection.
  *
  * Error model: fail-hard. Any attachment failure aborts the entire injection
  * and propagates a descriptive error. Attachments are explicit user inputs —
- * running with partial inputs produces silently incorrect results.
+ * running with partial inputs produces silently incorrect results. This is
+ * deliberately the OPPOSITE policy from the skill-artifact reader
+ * (shared/zip-extract.ts, non-fatal empty return): skill artifacts were
+ * structurally vouched for by the push gates, attachments never are.
  *
  * Duplicate names are NOT a failure (issue #364): a default-derived mount
  * path that collides is renamed with the platform's `stem-2.ext` semantics
@@ -34,13 +44,17 @@ import type {
   VisionDegradedReason,
   VisionImage,
 } from "../../shared/attachment-vision.js";
+import {
+  EOCD_MIN_SIZE,
+  parseZipStructure,
+  type ZipStructuralEntry,
+} from "../../shared/zip-structure.js";
 
 // ── Constants ────────────────────────────────────────────────────────
 
 const MAX_ZIP_FILES = 1000;
 const MAX_ZIP_EXTRACTED_SIZE = 100 * 1024 * 1024; // 100 MB
 const DEFAULT_INPUTS_PREFIX = ".stigmer/inputs";
-const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
 
 export { MAX_ZIP_FILES, MAX_ZIP_EXTRACTED_SIZE };
 
@@ -132,126 +146,117 @@ export class AttachmentValidationError extends Error {
   }
 }
 
-// ── ZIP Validation (pure function) ───────────────────────────────────
+// ── ZIP Validation (pure functions) ──────────────────────────────────
 
 /**
  * Validate a ZIP archive for safe extraction. Returns the manifest of
  * file entries (directories excluded) if the archive passes all checks.
  *
  * Security checks enforced:
- * 1. Valid ZIP format (local file header signature present)
+ * 1. Valid ZIP format (readable central directory; fail-hard, see module doc)
  * 2. No absolute paths (entries starting with / or \)
  * 3. No path traversal (.. components)
  * 4. No null bytes in filenames
- * 5. Non-empty archive (at least one file entry)
- * 6. File count within limits (max 1000)
- * 7. Total uncompressed size within limits (max 100 MB)
+ * 5. No duplicate entry paths (a contradictory manifest)
+ * 6. Only supported compression methods (stored, deflate) — checked here
+ *    so an unsupported entry can never abort extraction after earlier
+ *    entries were already written
+ * 7. Non-empty archive (at least one file entry)
+ * 8. File count within limits (max 1000)
+ * 9. Total declared uncompressed size within limits (max 100 MB) —
+ *    declarations are re-enforced against actual output at decompression
  */
 export function validateZipForExtraction(
   zipData: Buffer,
   sourceFilename: string,
 ): ZipEntryInfo[] {
-  if (zipData.length < 4) {
+  return parseAndValidateZip(zipData, sourceFilename).map(
+    ({ relativePath, uncompressedSize }) => ({ relativePath, uncompressedSize }),
+  );
+}
+
+/**
+ * A validated file entry, still carrying its payload slice. Validation and
+ * extraction share these records — parsing happens exactly once, so "the
+ * manifest promised a file extraction cannot find" is unrepresentable
+ * (the old two-walker design silently skipped such entries).
+ */
+interface ValidatedZipEntry extends ZipEntryInfo {
+  readonly compressionMethod: number;
+  readonly compressedData: Uint8Array;
+}
+
+function parseAndValidateZip(
+  zipData: Buffer,
+  sourceFilename: string,
+): ValidatedZipEntry[] {
+  if (zipData.length < EOCD_MIN_SIZE) {
     throw new AttachmentValidationError(
       sourceFilename,
       "not a valid ZIP archive (file too small)",
     );
   }
 
-  const view = new DataView(zipData.buffer, zipData.byteOffset, zipData.byteLength);
-  const firstSignature = view.getUint32(0, true);
-
-  if (firstSignature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) {
+  let structural: ZipStructuralEntry[];
+  try {
+    structural = parseZipStructure(zipData);
+  } catch (err) {
     throw new AttachmentValidationError(
       sourceFilename,
-      "not a valid ZIP archive (invalid header signature)",
+      `not a valid ZIP archive (${err instanceof Error ? err.message : String(err)})`,
     );
   }
 
-  const entries: ZipEntryInfo[] = [];
+  const entries: ValidatedZipEntry[] = [];
+  const seenPaths = new Set<string>();
   let totalUncompressed = 0;
-  let offset = 0;
-
-  while (offset < zipData.length - 4) {
-    const signature = view.getUint32(offset, true);
-    if (signature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) break;
 
-    if (offset + 30 > zipData.length) {
+  for (const entry of structural) {
+    if (entry.name.includes("\u0000")) {
       throw new AttachmentValidationError(
         sourceFilename,
-        "not a valid ZIP archive (truncated local file header)",
+        "contains a filename with null bytes and cannot be safely extracted",
       );
     }
 
-    const compressionMethod = view.getUint16(offset + 8, true);
-    const compressedSize = view.getUint32(offset + 18, true);
-    const uncompressedSize = view.getUint32(offset + 22, true);
-    const fileNameLength = view.getUint16(offset + 26, true);
-    const extraFieldLength = view.getUint16(offset + 28, true);
+    if (entry.isDirectory) continue;
 
-    const fileNameStart = offset + 30;
-    const fileNameEnd = fileNameStart + fileNameLength;
-
-    if (fileNameEnd > zipData.length) {
+    if (entry.name.startsWith("/") || entry.name.startsWith("\\")) {
       throw new AttachmentValidationError(
         sourceFilename,
-        "not a valid ZIP archive (truncated filename)",
+        `contains an absolute path entry and cannot be safely extracted: ${entry.name}`,
       );
     }
 
-    const fileNameBytes = zipData.subarray(fileNameStart, fileNameEnd);
-
-    for (let i = 0; i < fileNameBytes.length; i++) {
-      if (fileNameBytes[i] === 0x00) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          "contains a filename with null bytes and cannot be safely extracted",
-        );
-      }
+    if (hasPathTraversal(entry.name)) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains a path traversal entry and cannot be safely extracted: ${entry.name}`,
+      );
     }
 
-    const fileName = new TextDecoder().decode(fileNameBytes);
-
-    const isDirectory = fileName.endsWith("/");
-
-    if (!isDirectory) {
-      if (fileName.startsWith("/") || fileName.startsWith("\\")) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          `contains an absolute path entry and cannot be safely extracted: ${fileName}`,
-        );
-      }
-
-      if (hasPathTraversal(fileName)) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          `contains a path traversal entry and cannot be safely extracted: ${fileName}`,
-        );
-      }
-
-      entries.push({ relativePath: fileName, uncompressedSize });
-      totalUncompressed += uncompressedSize;
+    if (seenPaths.has(entry.name)) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `contains duplicate entry '${entry.name}' and cannot be safely extracted`,
+      );
     }
+    seenPaths.add(entry.name);
 
-    const dataStart = fileNameStart + fileNameLength + extraFieldLength;
-
-    // Handle data descriptor (bit 3 of general purpose flag)
-    const generalFlags = view.getUint16(offset + 6, true);
-    let dataSize = compressedSize;
-
-    if ((generalFlags & 0x08) !== 0 && compressedSize === 0) {
-      // Data descriptor follows compressed data — scan for next header
-      // This is a simplified approach; for untrusted inputs we require
-      // sizes in the local header. Reject archives that use streaming.
-      if (!isDirectory && compressionMethod !== 0) {
-        throw new AttachmentValidationError(
-          sourceFilename,
-          "uses streaming (data descriptors without sizes) which is not supported for security validation",
-        );
-      }
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `entry '${entry.name}' uses unsupported compression method ${entry.compressionMethod}`,
+      );
     }
 
-    offset = dataStart + dataSize;
+    entries.push({
+      relativePath: entry.name,
+      uncompressedSize: entry.uncompressedSize,
+      compressionMethod: entry.compressionMethod,
+      compressedData: entry.compressedData,
+    });
+    totalUncompressed += entry.uncompressedSize;
   }
 
   if (entries.length === 0) {
@@ -306,9 +311,9 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
     const { path: mountPath, renamedFrom } = mountPaths.get(attachment)!;
 
     if (attachment.extract) {
-      const entries = validateZipForExtraction(content, attachment.filename);
+      const entries = parseAndValidateZip(content, attachment.filename);
       const extracted = await extractZipToWorkspace(
-        content, entries, mountPath, backend,
+        entries, mountPath, backend, attachment.filename,
       );
       // A renamed mount DIR is visible through every extracted path; the
       // entries themselves were not renamed, so they carry no renamedFrom
@@ -524,20 +529,16 @@ async function downloadAttachment(
 }
 
 async function extractZipToWorkspace(
-  zipData: Buffer,
-  entries: readonly ZipEntryInfo[],
+  entries: readonly ValidatedZipEntry[],
   mountDir: string,
   backend: WorkspaceBackend,
+  sourceFilename: string,
 ): Promise<InjectedFile[]> {
   const cleanMountDir = mountDir.replace(/\/+$/, "");
   const injected: InjectedFile[] = [];
-  const parsedEntries = parseZipFileData(zipData);
 
   for (const entry of entries) {
-    const fileData = parsedEntries.get(entry.relativePath);
-    if (!fileData) continue;
-
-    const content = await decompressEntry(fileData);
+    const content = await decompressEntry(entry, sourceFilename);
     const targetPath = `${cleanMountDir}/${entry.relativePath}`;
 
     await backend.writeFileBuffer(targetPath, content);
@@ -551,63 +552,66 @@ async function extractZipToWorkspace(
   return injected;
 }
 
-interface RawZipEntry {
-  compressedData: Buffer;
-  compressionMethod: number;
-}
-
-function parseZipFileData(zipData: Buffer): Map<string, RawZipEntry> {
-  const result = new Map<string, RawZipEntry>();
-  const view = new DataView(zipData.buffer, zipData.byteOffset, zipData.byteLength);
-  let offset = 0;
-
-  while (offset < zipData.length - 4) {
-    const signature = view.getUint32(offset, true);
-    if (signature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) break;
-
-    const compressionMethod = view.getUint16(offset + 8, true);
-    const compressedSize = view.getUint32(offset + 18, true);
-    const fileNameLength = view.getUint16(offset + 26, true);
-    const extraFieldLength = view.getUint16(offset + 28, true);
-
-    const fileNameStart = offset + 30;
-    const fileName = new TextDecoder().decode(
-      zipData.subarray(fileNameStart, fileNameStart + fileNameLength),
-    );
-
-    const dataStart = fileNameStart + fileNameLength + extraFieldLength;
-    const compressedData = zipData.subarray(dataStart, dataStart + compressedSize);
-
-    if (!fileName.endsWith("/")) {
-      result.set(fileName, {
-        compressedData: Buffer.from(compressedData),
-        compressionMethod,
-      });
-    }
-
-    offset = dataStart + compressedSize;
-  }
-
-  return result;
-}
+/**
+ * Decompress a validated entry, enforcing its declared uncompressed size.
+ *
+ * The size cap in parseAndValidateZip budgets *declared* sizes, which the
+ * archive author controls — a crafted archive can declare 1 KB and inflate
+ * to gigabytes. Enforcement is therefore two-sided and fail-hard: inflation
+ * aborts the moment output exceeds the declaration, and an undershoot (or a
+ * stored payload whose length disagrees) fails too, because a manifest that
+ * misdescribes its own contents is exactly the corrupt-input class this
+ * module must never extract from.
+ */
+async function decompressEntry(
+  entry: ValidatedZipEntry,
+  sourceFilename: string,
+): Promise<Buffer> {
+  const declared = entry.uncompressedSize;
 
-async function decompressEntry(entry: RawZipEntry): Promise<Buffer> {
   if (entry.compressionMethod === 0) {
-    return entry.compressedData;
+    if (entry.compressedData.length !== declared) {
+      throw new AttachmentValidationError(
+        sourceFilename,
+        `entry '${entry.relativePath}' payload is ${entry.compressedData.length} bytes ` +
+        `but the archive declares ${declared} — corrupt or crafted archive`,
+      );
+    }
+    return Buffer.from(entry.compressedData);
   }
 
-  if (entry.compressionMethod === 8) {
-    return new Promise<Buffer>((resolve, reject) => {
-      const inflate = createInflateRaw();
-      const chunks: Buffer[] = [];
-      inflate.on("data", (chunk: Buffer) => chunks.push(chunk));
-      inflate.on("end", () => resolve(Buffer.concat(chunks)));
-      inflate.on("error", reject);
-      inflate.end(entry.compressedData);
+  // Deflate — the only other method parseAndValidateZip admits.
+  return new Promise<Buffer>((resolve, reject) => {
+    const inflate = createInflateRaw();
+    const chunks: Buffer[] = [];
+    let produced = 0;
+    inflate.on("data", (chunk: Buffer) => {
+      produced += chunk.length;
+      if (produced > declared) {
+        inflate.destroy();
+        reject(new AttachmentValidationError(
+          sourceFilename,
+          `entry '${entry.relativePath}' decompresses past its declared size of ` +
+          `${declared} bytes — corrupt or crafted archive`,
+        ));
+        return;
+      }
+      chunks.push(chunk);
     });
-  }
-
-  throw new Error(`Unsupported ZIP compression method: ${entry.compressionMethod}`);
+    inflate.on("end", () => {
+      if (produced !== declared) {
+        reject(new AttachmentValidationError(
+          sourceFilename,
+          `entry '${entry.relativePath}' decompressed to ${produced} bytes ` +
+          `but the archive declares ${declared} — corrupt or crafted archive`,
+        ));
+        return;
+      }
+      resolve(Buffer.concat(chunks));
+    });
+    inflate.on("error", reject);
+    inflate.end(Buffer.from(entry.compressedData));
+  });
 }
 
 function hasPathTraversal(filePath: string): boolean {

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

@@ -251,7 +251,17 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   // reads. (PLAN and build_from_plan are mutually exclusive in practice —
   // the build turn is always an Agent-mode execution.)
   if (input.interactionMode === InteractionMode.PLAN) {
-    prompt += "\n\n## Plan mode\n\n" + PLAN_MODE_DIRECTIVE;
+    // The read-boundary sentence is native-harness-only, appended OUTSIDE the
+    // shared directive: PLAN_MODE_DIRECTIVE also serves the Cursor harness,
+    // which has no tool-level read boundary — there the sentence would be
+    // false. Here it is enforced fact (shared/plan-mode-permissions.ts,
+    // issue #528), stated so the model doesn't burn rounds probing paths the
+    // rules will refuse.
+    prompt +=
+      "\n\n## Plan mode\n\n" +
+      PLAN_MODE_DIRECTIVE +
+      "\n- File reads are limited to your workspace (including its " +
+      "`.stigmer/` directory); paths outside it are refused.";
   }
 
   if (input.buildFromPlan) {

package/src/activities/execute-deep-agent/setup.ts

@@ -52,7 +52,7 @@ import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { WorkspaceBackend, ProvisionResult } from "../../shared/workspace/types.js";
 import { createCasCaptureBackend } from "./cas-capture-backend.js";
 import { buildShellEnv } from "./shell-env.js";
-import { PLAN_MODE_PERMISSIONS } from "../../shared/plan-mode-permissions.js";
+import { buildPlanModePermissions } from "../../shared/plan-mode-permissions.js";
 import { CasCaptureObserver } from "./cas-capture-observer.js";
 import { isGitWorkTree, isPathCapturable } from "../../shared/filereview/git-substrate.js";
 import { deriveCaptureMode } from "../../shared/filereview/capture.js";
@@ -598,8 +598,12 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // every sub-agent graph, AND the path-normalization middleware (issue #429)
     // all derive from this single value, so a rule-bearing graph can never miss
     // the shim that keeps prompt-compliant relative paths from dying in rule
-    // validation (`path must be absolute`).
-    const planModePermissions = isPlanMode ? PLAN_MODE_PERMISSIONS : undefined;
+    // validation (`path must be absolute`). Built from the same rootDir the
+    // backends and the shim resolve against, so the workspace read boundary
+    // (issue #528) and the paths it must admit agree by construction.
+    const planModePermissions = isPlanMode
+      ? buildPlanModePermissions(workspaceBackend.rootDir)
+      : undefined;
 
     const toolServerMap = new Map<string, string>();
     if (mcpConnection) {

package/src/middleware/__tests__/path-normalization.test.ts

@@ -104,9 +104,35 @@ describe("createPathNormalizationMiddleware", () => {
     expect(args.file_path).toBe("/etc/hosts");
   });
 
-  it("leaves an omitted base path (backend default) alone", async () => {
-    const args = await argsSeenByHandler("ls", {});
-    expect(args.path).toBeUndefined();
+  it("supplies the workspace root when the base path is omitted on ls/glob/grep", async () => {
+    // Deliberate reversal of the original #429 pin ("leaves an omitted base
+    // path alone"): the tools' schema default is "/" — the OS ROOT under the
+    // legacy backend — applied inside the tool AFTER this seam, so under the
+    // #528 workspace read boundary an untouched omission would deny the bare
+    // first listing. The middleware fills the omission with the root it
+    // already knows.
+    for (const tool of ["ls", "glob", "grep"]) {
+      const args = await argsSeenByHandler(tool, { pattern: "TOKEN" });
+      expect(args.path).toBe(ROOT);
+      expect(args.pattern).toBe("TOKEN");
+    }
+  });
+
+  it("does not fill an omitted file_path on the file tools", async () => {
+    // An absent file_path is a genuine model error — the tool's own input
+    // validation gives the better message than any path this seam could invent.
+    const args = await argsSeenByHandler("read_file", {});
+    expect(args.file_path).toBeUndefined();
+  });
+
+  it("leaves an explicit '/' untouched on the dir tools — the rules answer it honestly", async () => {
+    // The model asked for the OS root; under plan mode's read boundary the
+    // honest answer is the rules' denial, not silently substituted workspace
+    // contents (the #429 never-convert-a-refusal-into-an-allowance doctrine).
+    for (const tool of ["ls", "glob", "grep"]) {
+      const args = await argsSeenByHandler(tool, { path: "/" });
+      expect(args.path).toBe("/");
+    }
   });
 
   it("never touches tools outside the built-in filesystem set", async () => {

package/src/middleware/path-normalization.ts

@@ -1,6 +1,6 @@
 /**
  * Workspace-relative path normalization for permission-rule-bearing graphs
- * (issue #429).
+ * (issues #429, #528).
  *
  * deepagents' permission enforcement canonicalizes tool-call paths BEFORE any
  * rule or backend runs, and its validation refuses non-absolute paths — on
@@ -20,13 +20,26 @@
  * resolves relative paths under the workspace root, so act mode keeps a
  * byte-zero delta.
  *
+ * It also supplies the workspace root when `ls`/`glob`/`grep` are called
+ * with NO path argument (issue #528). Those tools' schema default is "/" —
+ * the OS ROOT under the legacy backend — and the default is applied inside
+ * the tool, after this seam, so under the workspace read boundary a bare
+ * first `ls` would otherwise die with `permission denied for read on /`
+ * (the same first-turn degradation class #429 fixed). An EXPLICIT "/" is
+ * deliberately NOT rewritten: the model asked for the OS root, and the
+ * honest answer under plan mode's read boundary is the rules' denial —
+ * silently substituting workspace contents would be an answer to a
+ * different question.
+ *
  * Invariant — nothing becomes newly reachable: only paths whose resolution
  * stays INSIDE the workspace root are rewritten. Escaping relatives (`../x`)
  * and `~`-carrying paths are left raw so today's validation refusal keeps
  * speaking (a naive join would resolve `..` away and smuggle an out-of-root
  * read past validation), and absolute paths pass through byte-untouched.
  * The middleware converts false errors into correct behavior — never a
- * refusal into an allowance the rules didn't decide.
+ * refusal into an allowance the rules didn't decide. (The absent-path
+ * injection honors the same line: it narrows the tool's own OS-root default
+ * to the workspace, granting nothing the rules would refuse.)
  *
  * Tool matching is by bare built-in name, the house doctrine (an MCP server
  * is not expected to shadow a built-in name — see shared/tool-kind.ts); the
@@ -41,9 +54,8 @@ import type { StigmerMiddleware } from "./types.js";
 
 /**
  * The path-bearing argument of each deepagents built-in filesystem tool.
- * `ls`/`glob`/`grep` take a base directory `path` (defaulting to "/" when
- * omitted — absolute, so untouched here); the file tools take `file_path`.
- * Confirmed against the installed deepagents' tool definitions.
+ * `ls`/`glob`/`grep` take a base directory `path`; the file tools take
+ * `file_path`. Confirmed against the installed deepagents' tool definitions.
  */
 const PATH_ARG_BY_TOOL: ReadonlyMap<string, string> = new Map([
   ["ls", "path"],
@@ -54,6 +66,15 @@ const PATH_ARG_BY_TOOL: ReadonlyMap<string, string> = new Map([
   ["edit_file", "file_path"],
 ]);
 
+/**
+ * The tools whose path argument is optional with an OS-root ("/") schema
+ * default. When the model omits it, this middleware supplies the workspace
+ * root instead (issue #528). The file tools are deliberately excluded: an
+ * absent `file_path` is a genuine model error, and the tool's own input
+ * validation gives the better message.
+ */
+const DIR_DEFAULTING_TOOLS: ReadonlySet<string> = new Set(["ls", "glob", "grep"]);
+
 export interface PathNormalizationConfig {
   /** The workspace root the graph's filesystem backend resolves against. */
   readonly rootDir: string;
@@ -108,6 +129,22 @@ export function createPathNormalizationMiddleware(
       if (!argKey) return handler(request);
 
       const raw = request.toolCall.args[argKey];
+
+      // Absent base directory on ls/glob/grep: the middleware sees the
+      // model's raw args, BEFORE the tool's zod parse applies the "/"
+      // (OS root) schema default — so the omission must be filled here,
+      // where the workspace root is known. An explicit "/" is not this
+      // case and flows through to an honest rule denial (header doctrine).
+      if (raw == null && DIR_DEFAULTING_TOOLS.has(request.toolCall.name)) {
+        return handler({
+          ...request,
+          toolCall: {
+            ...request.toolCall,
+            args: { ...request.toolCall.args, [argKey]: rootDir },
+          },
+        });
+      }
+
       if (typeof raw !== "string") return handler(request);
 
       const normalized = normalizeWorkspacePathArg(raw, rootDir);