@stigmer/runner 3.12.3 → 3.12.5

package/src/activities/execute-cursor/skill-resolver.ts

@@ -2,8 +2,8 @@
  * Resolves skill resources and writes them to the platform-managed directory.
  *
  * - Fetches skills via gRPC (by reference)
- * - Writes SKILL.md to .stigmer/skills/{name}/SKILL.md
- * - Downloads and extracts ZIP artifacts (references/, scripts/, etc.)
+ * - Mounts each skill via the shared skill-mount mechanics (SKILL.md +
+ *   extracted artifact, hash-keyed cache — see shared/skill-mount.ts)
  * - Uses a platform-managed directory outside the workspace
  * - Ensures the workspace `.stigmer` symlink (see stigmer-link.ts)
  * - Returns metadata for prompt injection
@@ -17,38 +17,20 @@
  * transfer.
  */
 
-import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
-import { join, dirname } from "node:path";
-import { ConnectError, Code } from "@connectrpc/connect";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
 import type { StigmerClient } from "../../client/stigmer-client.js";
-import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { SkillMetadata } from "./prompt-builder.js";
 import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
-import { extractZipFileEntries } from "../../shared/zip-extract.js";
+import {
+  SKILLS_SUBDIR,
+  mountIsFresh,
+  downloadArtifact,
+  writeSkillMount,
+} from "../../shared/skill-mount.js";
 import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
 
-const SKILLS_SUBDIR = "skills";
-
-/**
- * Marker recording what a skill's mount directory currently holds. Written
- * LAST, after every file of the mount landed — a crash mid-write leaves no
- * marker, so the next execution remounts instead of trusting a partial tree.
- */
-const MOUNT_MARKER_FILE = ".stigmer-mount.json";
-
-interface MountMarker {
-  /** Content-addressed version hash (`Skill.status.version_hash`) of the mounted content. */
-  versionHash: string;
-  /**
-   * Whether the artifact's files are part of the mount. `false` when the
-   * skill has no artifact OR when the download failed and the mount fell
-   * back to SKILL.md only — the latter makes the next execution retry the
-   * download rather than cache the degraded mount.
-   */
-  artifactMounted: boolean;
-}
-
 export interface SkillResolverOptions {
   sessionId: string;
   primaryWorkspaceDir: string;
@@ -145,112 +127,3 @@ export async function resolveSkills(
 
   return results;
 }
-
-/**
- * Whether the mount at `skillDir` already holds this version's content.
- *
- * Fresh means: the marker's hash matches AND the mount isn't a degraded
- * SKILL.md-only fallback when the skill does carry an artifact. Any read or
- * parse failure counts as stale — the remount is the safe default.
- */
-async function mountIsFresh(skillDir: string, versionHash: string, wantsArtifact: boolean): Promise<boolean> {
-  try {
-    const raw = await readFile(join(skillDir, MOUNT_MARKER_FILE), "utf-8");
-    const marker = JSON.parse(raw) as Partial<MountMarker>;
-    return marker.versionHash === versionHash && (marker.artifactMounted === true || !wantsArtifact);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Download a skill artifact's ZIP bytes, transfer lane first (#675).
- *
- * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
- * size; the unary getArtifact response is capped by the server's 10MB gRPC
- * message limit. Servers that predate the lane (and cloud until its sibling
- * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
- * path, which behaves exactly as before for ≤10MB artifacts.
- *
- * Runs only on a mount-cache miss (#672's hash-keyed marker above) — a hit
- * skips the transfer entirely, whichever lane would have carried it.
- *
- * Exported for tests.
- */
-export async function downloadArtifact(
-  client: StigmerClient,
-  artifactStorageKey: string,
-): Promise<Uint8Array | undefined> {
-  let minted;
-  try {
-    minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
-  } catch (err) {
-    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
-      const resp = await client.getSkillArtifact(artifactStorageKey);
-      return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
-    }
-    throw err;
-  }
-
-  const resp = await fetch(minted.url);
-  if (!resp.ok) {
-    throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
-  }
-  const bytes = new Uint8Array(await resp.arrayBuffer());
-  if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
-    throw new Error(
-      `artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`,
-    );
-  }
-  return bytes.length > 0 ? bytes : undefined;
-}
-
-/**
- * (Re)write a skill's mount directory from scratch.
- *
- * The directory is removed first so files deleted between versions don't
- * linger in the mount, then SKILL.md and the artifact files are written, and
- * the marker is stamped LAST (see MOUNT_MARKER_FILE for the crash-safety
- * contract). SKILL.md always comes from `spec.skillMd` — the server's
- * authoritative copy — never from the zip; both the zip's SKILL.md and any
- * stray marker-named entry are excluded from extraction so the mount's
- * ownership of those two files is unconditional.
- */
-async function writeSkillMount(
-  skill: Skill,
-  skillDir: string,
-  artifactBytes: Uint8Array | undefined,
-): Promise<void> {
-  await rm(skillDir, { recursive: true, force: true });
-  await mkdir(skillDir, { recursive: true });
-
-  await writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd, "utf-8");
-
-  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
-  if (artifactMounted) {
-    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
-    for (const entry of entries) {
-      const filePath = join(skillDir, entry.path);
-      await mkdir(dirname(filePath), { recursive: true });
-      await writeFile(filePath, entry.content, "utf-8");
-    }
-  }
-
-  const versionHash = skill.status?.versionHash ?? "";
-  if (versionHash !== "") {
-    const marker: MountMarker = { versionHash, artifactMounted };
-    await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
-  }
-}
-
-/**
- * Clean up platform-managed skill directory for a session.
- */
-export async function cleanupSkills(sessionId: string): Promise<void> {
-  const platformDir = getPlatformDir(sessionId);
-  try {
-    await rm(platformDir, { recursive: true, force: true });
-  } catch {
-    // best-effort
-  }
-}

package/src/activities/execute-deep-agent/__tests__/approval-file-change.test.ts

@@ -81,4 +81,19 @@ describe("captureApprovalArtifacts", () => {
     const { argsPreview } = captureApprovalArtifacts({ toolCallId: "call-1", messages });
     expect(argsPreview).toContain("needle");
   });
+
+  it("returns the redacted args object for stamping the placeholder row (issue #754)", () => {
+    // The interrupt-placeholder ToolCall must carry `args`, not just the
+    // preview string: the row header extracts its filename-first path from
+    // args, so a placeholder without them rendered a pathless "Write" gate.
+    // Redaction posture matches the preview: secret keys never surface.
+    const messages = [
+      aiMessage([
+        { id: "call-1", name: "write_file", args: { file_path: "a.txt", content: "hi", token: "sk-secret" } },
+      ]),
+    ];
+    const { args } = captureApprovalArtifacts({ toolCallId: "call-1", messages });
+
+    expect(args).toEqual({ file_path: "a.txt", content: "hi", token: "[REDACTED]" });
+  });
 });

package/src/activities/execute-deep-agent/__tests__/cas-capture-backend.test.ts

@@ -124,6 +124,81 @@ describe("CasCaptureShellBackend (shell + CAS adapter)", () => {
   });
 });
 
+/**
+ * The issue #754 regression pins: the backends are virtual-rooted, so a
+ * leading-"/" tool path resolves INSIDE the workspace — never onto the host
+ * filesystem — and the CAS observer sees it under the same key the
+ * turn-boundary capture and InlinePublisher resolve. Before the fix, an
+ * absolute `write_file("/tmp/x")` landed in the REAL /tmp: outside the
+ * workspace, outside CAS capture, outside the file_review ledger — an
+ * auto-approved, unreviewed host write.
+ */
+describe("virtual-root confinement (issue #754)", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "cas-virtual-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  function makeBackend(): { backend: CasCaptureFilesystemBackend; observer: CasCaptureObserver } {
+    // Non-git shape: the observer owns EVERY touched path (setup.ts wires
+    // isIgnored to always-true when there is no git work tree).
+    const observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+    const backend = new CasCaptureFilesystemBackend(
+      { rootDir: root, virtualMode: true },
+      { observer },
+    );
+    return { backend, observer };
+  }
+
+  it("an absolute write resolves inside the workspace, never onto the host", async () => {
+    const { backend, observer } = makeBackend();
+    const hostPath = `/tmp/stigmer-754-escape-${Date.now()}.txt`;
+
+    await backend.write(hostPath, "confined");
+
+    // Landed under the workspace root, keyed workspace-relative for capture…
+    expect(await readFile(join(root, hostPath.slice(1)), "utf8")).toBe("confined");
+    expect(observer.before.get(hostPath.slice(1))).toBeNull();
+    // …and the REAL host path was never touched.
+    await expect(readFile(hostPath, "utf8")).rejects.toThrow();
+  });
+
+  it("reads resolve inside the workspace — '/etc/hosts' is the workspace's, not the host's", async () => {
+    const { backend } = makeBackend();
+
+    const result = await backend.read("/etc/hosts");
+
+    // The workspace has no etc/hosts: the honest not-found, never host bytes.
+    expect(JSON.stringify(result)).toMatch(/not found|no such file/i);
+    expect(JSON.stringify(result)).not.toContain("localhost");
+  });
+
+  it("traversal is rejected at resolution", async () => {
+    const { backend } = makeBackend();
+
+    const result = await backend.write("../escape.txt", "nope");
+
+    expect((result as { error?: string }).error).toMatch(/traversal/i);
+    await expect(readFile(join(root, "..", "escape.txt"), "utf8")).rejects.toThrow();
+  });
+
+  it("the shell variant is confined identically", async () => {
+    const observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+    const backend = await createCasCaptureBackend({ rootDir: root, observer, shellEnv: {} });
+    const hostPath = `/tmp/stigmer-754-shell-escape-${Date.now()}.txt`;
+
+    await backend.write(hostPath, "confined");
+
+    expect(await readFile(join(root, hostPath.slice(1)), "utf8")).toBe("confined");
+    await expect(readFile(hostPath, "utf8")).rejects.toThrow();
+  });
+});
+
 describe("plan-mode filesystem backend", () => {
   it("is not sandbox-capable", async () => {
     const root = await mkdtemp(join(tmpdir(), "cas-plan-"));

package/src/activities/execute-deep-agent/__tests__/hitl-reject.test.ts

@@ -42,6 +42,7 @@ vi.mock("@temporalio/activity", () => ({
     current: () => ({
       cancellationSignal: new AbortController().signal,
       heartbeat: vi.fn(),
+      info: { taskQueue: "test-queue" },
     }),
   },
   CancelledFailure: class CancelledFailure extends Error {},

package/src/activities/execute-deep-agent/__tests__/hitl-resume-approve-all.test.ts

@@ -53,6 +53,7 @@ vi.mock("@temporalio/activity", () => ({
       // on it, which a bare `{ aborted: false }` stub cannot satisfy.
       cancellationSignal: new AbortController().signal,
       heartbeat: vi.fn(),
+      info: { taskQueue: "test-queue" },
     }),
   },
   CancelledFailure: class CancelledFailure extends Error {},

package/src/activities/execute-deep-agent/__tests__/hitl-resume-history.test.ts

@@ -46,6 +46,7 @@ vi.mock("@temporalio/activity", () => ({
       // on it, which a bare `{ aborted: false }` stub cannot satisfy.
       cancellationSignal: new AbortController().signal,
       heartbeat: vi.fn(),
+      info: { taskQueue: "test-queue" },
     }),
   },
   CancelledFailure: class CancelledFailure extends Error {},

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

@@ -12,6 +12,7 @@ vi.mock("@temporalio/activity", () => ({
       // on it, which a bare `{ aborted: false }` stub cannot satisfy.
       cancellationSignal: new AbortController().signal,
       heartbeat: vi.fn(),
+      info: { taskQueue: "test-queue" },
     }),
   },
   CancelledFailure: class CancelledFailure extends Error {},

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

@@ -1,25 +1,25 @@
 /**
  * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that
  * a plan-mode PARENT graph accepts workspace-relative paths (issue #429) and
- * scopes reads to the workspace (issue #528).
+ * confines every read to the workspace (issues #528, #754).
  *
  * 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. #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.
+ * relative paths to VIRTUAL-absolute at our seam, before enforcement sees
+ * them. The read boundary #528 built out of rules is structural since #754:
+ * the backend is virtual-rooted, so every expressible path resolves inside
+ * the workspace — an out-of-root name is simply nonexistent, and the
+ * `.stigmer` symlink keeps platform-dir reads addressable in-root.
  *
  * 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
- * 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.
+ * the PRODUCTION buildMiddlewareStack (pathNormalization present on every
+ * graph) + the CAS capture backend + the PRODUCTION 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.
  *
  * The sub-agent twin of this contract is pinned in
  * subagent-plan-mode-permissions.test.ts (issue #255 wiring).
@@ -65,7 +65,7 @@ async function buildPlanModeParent(
     checkpointer: new MemorySaver() as never,
     backend,
     middleware: middleware as never[],
-    permissions: buildPlanModePermissions(root),
+    permissions: buildPlanModePermissions(),
   } as Parameters<typeof createDeepAgent>[0]);
 }
 
@@ -222,7 +222,11 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
     )) as { messages: BaseMessage[] };
   }
 
-  it("denies an out-of-root absolute read — the exposure #429 deliberately preserved is closed", async () => {
+  it("an out-of-root absolute read cannot reach the bytes — the name resolves in-workspace and finds nothing", async () => {
+    // Pre-#754 this was a rule-based denial; the boundary is structural now:
+    // the virtual root makes the outside path unaddressable, so the honest
+    // answer is not-found. The security property — the bytes never cross —
+    // is what this test pins.
     const result = await invokeOnce(
       () => ({
         toolCalls: [
@@ -234,7 +238,7 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
     );
 
     const readResult = toolResultById(result.messages, "c_read_out");
-    expect(readResult).toMatch(/permission denied for read/i);
+    expect(readResult).toMatch(/not found|no such file/i);
     expect(readResult).not.toContain("OUT_OF_ROOT_SECRET_TOKEN");
   });
 
@@ -269,9 +273,9 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
   });
 
   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.
+    // The tool's schema default is "/" — which under the virtual root IS the
+    // workspace root (pre-#754 it was the OS root and the middleware had to
+    // fill the omission), so the model's first listing just works.
     const result = await invokeOnce(
       () => ({
         toolCalls: [{ name: "ls", args: {}, id: "c_ls_bare" }],
@@ -287,7 +291,8 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
 
   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).
+    // (schema default "/" + the legacy backend's literal pass-through);
+    // under the virtual root the default itself means the workspace.
     const result = await invokeOnce(
       () => ({
         toolCalls: [
@@ -303,7 +308,11 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
     expect(grepResult).not.toMatch(/permission denied/i);
   });
 
-  it("an explicit ls of '/' is denied honestly — not silently redirected to the workspace", async () => {
+  it("an explicit ls of '/' lists the workspace root — '/' MEANS the workspace in the virtual dialect", async () => {
+    // Deliberate reversal of the pre-#754 pin ("denied honestly"): back then
+    // "/" named the OS root, so denial was the honest answer. Under the
+    // virtual root "/" IS the workspace root — the model asked for the
+    // workspace and gets it.
     const result = await invokeOnce(
       () => ({
         toolCalls: [{ name: "ls", args: { path: "/" }, id: "c_ls_slash" }],
@@ -312,9 +321,9 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
       "t_ls_slash",
     );
 
-    expect(toolResultById(result.messages, "c_ls_slash")).toMatch(
-      /permission denied for read on \//i,
-    );
+    const lsResult = toolResultById(result.messages, "c_ls_slash");
+    expect(lsResult).toContain("src");
+    expect(lsResult).not.toMatch(/permission denied/i);
   });
 
   it("writes stay denied everywhere — the read-allow rule admits reads only", async () => {
@@ -333,12 +342,12 @@ describe("plan-mode workspace read boundary (issue #528)", () => {
   });
 });
 
-describe("plan-mode read boundary with a glob-special workspace root (issue #528)", () => {
+describe("plan-mode boundary with a glob-special workspace root (issues #528/#754)", () => {
   // 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.
+  // the root — names like "My (work) [v2]" are legal there. Pre-#754 the
+  // read-allow rule embedded the root as a glob and needed escapeGlobLiteral
+  // to survive such names; the rules no longer embed the root at all, so
+  // this suite now pins that special-character roots just work.
   let base: string;
   let root: string;
   let observer: CasCaptureObserver;
@@ -363,7 +372,7 @@ describe("plan-mode read boundary with a glob-special workspace root (issue #528
     )) as { messages: BaseMessage[] };
   }
 
-  it("in-root reads work, absolute and relative alike; out-of-root reads stay denied", async () => {
+  it("in-root reads work, absolute and relative alike; host files stay unreachable", async () => {
     const result = await invokeOnce(
       () => ({
         toolCalls: [
@@ -378,6 +387,10 @@ describe("plan-mode read boundary with a glob-special workspace root (issue #528
 
     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);
+    // "/etc/hosts" names the WORKSPACE's etc/hosts, which doesn't exist —
+    // the host file is structurally unaddressable.
+    const outResult = toolResultById(result.messages, "c_out");
+    expect(outResult).toMatch(/not found|no such file/i);
+    expect(outResult).not.toContain("localhost");
   });
 });

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

@@ -411,6 +411,58 @@ describe("buildEnhancedSystemPrompt", () => {
     });
   });
 
+  describe("declared preferences", () => {
+    const base = {
+      instructions: "Test",
+      provisionResults: [],
+      containerRoot: "",
+      skillsPromptSection: "",
+      workspaceFileRefs: [],
+      workspaceRoot: "",
+      injectedFiles: [],
+    };
+
+    it("appends the preferences with per-scope attribution (every-turn injection)", () => {
+      const prompt = buildEnhancedSystemPrompt({
+        ...base,
+        declaredPreferences: {
+          orgContext: "We deploy to us-east-1.",
+          userContext: "Keep answers terse.",
+        },
+      });
+
+      expect(prompt).toContain("## Declared preferences");
+      expect(prompt).toContain("Declared by the organization:\nWe deploy to us-east-1.");
+      expect(prompt).toContain("Declared by the user:\nKeep answers terse.");
+      expect(prompt).toContain("Do not repeat them back");
+    });
+
+    it("omits the section when the execution carries no preferences", () => {
+      const prompt = buildEnhancedSystemPrompt(base);
+
+      expect(prompt).not.toContain("## Declared preferences");
+    });
+
+    it("places platform-declared preferences after the sender, before the embedder's session context (DD-002 D3)", () => {
+      const prompt = buildEnhancedSystemPrompt({
+        ...base,
+        senderIdentity: { value: "15550001111", kind: "whatsapp_phone" },
+        declaredPreferences: { orgContext: "We deploy to us-east-1." },
+        sessionContext: "Role: platform admin",
+        contextBridge: "User: hi\nAssistant: hello",
+      });
+
+      const sender = prompt.indexOf("## Conversation sender");
+      const preferences = prompt.indexOf("## Declared preferences");
+      const context = prompt.indexOf("## Session context");
+      const bridge = prompt.indexOf("## Previous conversation context");
+      expect(sender).toBeGreaterThan(-1);
+      expect(preferences).toBeGreaterThan(sender);
+      expect(context).toBeGreaterThan(preferences);
+      expect(bridge).toBeGreaterThan(context);
+    });
+  });
+
   describe("plan mode", () => {
     const base = {
       instructions: "Test",

package/src/activities/execute-deep-agent/__tests__/sequential-gate-resume.test.ts

@@ -55,6 +55,7 @@ vi.mock("@temporalio/activity", () => ({
       // on it, which a bare `{ aborted: false }` stub cannot satisfy.
       cancellationSignal: new AbortController().signal,
       heartbeat: vi.fn(),
+      info: { taskQueue: "test-queue" },
     }),
   },
   CancelledFailure: class CancelledFailure extends Error {},

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

@@ -64,7 +64,7 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
         workspaceRootDir: root,
         casObserver: observer,
         modelFactory: async () => new ScriptedModel(script),
-        ...(planMode ? { permissions: buildPlanModePermissions(root) } : {}),
+        ...(planMode ? { permissions: buildPlanModePermissions() } : {}),
       },
     );
     expect(compiled).toHaveLength(1);
@@ -176,12 +176,14 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
     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.
+  it("confines sub-agent reads to the workspace; the bare-ls default lists it (issues #528/#754)", async () => {
+    // The boundary must hold on SUB-AGENT graphs too — they carry their own
+    // rules (issue #255), their own normalization shim (#429), and their own
+    // virtual-rooted backend (#754), so a parent-only fix would leave
+    // sub-agents reading anywhere. One turn, three calls: a host-file read
+    // resolves in-workspace and finds nothing, an in-root read flows, a bare
+    // ls (schema default "/", the workspace root in the virtual dialect)
+    // lists the workspace.
     const script: ScriptSelector = () => ({
       toolCalls: [
         { name: "read_file", args: { file_path: "/etc/hosts" }, id: "c_read_out" },
@@ -198,7 +200,8 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
     )) as { messages: BaseMessage[] };
 
     const outResult = toolResultById(result.messages, "c_read_out");
-    expect(outResult).toMatch(/permission denied for read/i);
+    expect(outResult).toMatch(/not found|no such file/i);
+    expect(outResult).not.toContain("localhost");
 
     expect(toolResultById(result.messages, "c_read_in")).toContain("PLAN_MODE_README_TOKEN");
 

package/src/activities/execute-deep-agent/approval-file-change.ts

@@ -18,9 +18,19 @@
 export interface ApprovalCaptureResult {
   /** Sanitized JSON args preview, omitted when there are no args to show. */
   readonly argsPreview?: string;
+  /**
+   * The secret-redacted args object, for stamping `ToolCall.args` on the
+   * interrupt-placeholder row. Without it the placeholder carried ONLY the
+   * preview string, so every args-driven UI read — the row header's
+   * filename-first path above all — rendered nothing for a pending gate
+   * (issue #754). Redacted (never raw): the placeholder must not widen the
+   * exposure the preview sanitizer bounds.
+   */
+  readonly args?: Record<string, unknown>;
 }
 
 import { sanitizeArgsPreview } from "./status-builder-shared.js";
+import { redactSensitiveArgs } from "../../shared/args-preview.js";
 
 /**
  * Correlate a gated `tool_call_id` to its arguments by scanning graph-state
@@ -76,5 +86,5 @@ export function captureApprovalArtifacts(opts: {
   if (!args || Object.keys(args).length === 0) return {};
 
   const argsPreview = sanitizeArgsPreview(args) || undefined;
-  return { argsPreview };
+  return { argsPreview, args: redactSensitiveArgs(args) };
 }

package/src/activities/execute-deep-agent/cas-capture-backend.ts

@@ -25,8 +25,25 @@
  * records its before-bytes at authorization time instead (`captureDeleteBefore`,
  * issue #303). A delete via shell (`rm`) stays on the approval gate as always.
  *
+ * VIRTUAL ROOT — THE ONE PATH DIALECT (issue #754)
+ * ------------------------------------------------
+ * Every backend here is constructed with `virtualMode: true`: a leading "/"
+ * denotes the WORKSPACE ROOT, traversal (`..`, `~`) is rejected, and every
+ * resolution stays inside `rootDir` by construction. This is the same dialect
+ * the rest of the harness already speaks — the system prompt's path-resolution
+ * directive, `resolveWorkspacePath(..., virtualRoot=true)` in the CAS observer
+ * and turn-boundary capture, `InlinePublisher.normalizePath`, and the approval
+ * gate's capturability checks. Before this flag, deepagents' legacy default
+ * passed absolute paths through to the REAL filesystem: a `write_file("/tmp/x")`
+ * escaped the session workspace onto the host AND escaped review entirely
+ * (auto-approved as capture-mode flow, but the observer/boundary/publisher all
+ * looked inside the workspace and found nothing). Read-side, the same legacy
+ * pass-through was why plan mode needed rule-based read fencing at all. Do not
+ * remove this flag: workspace confinement is structural, not policy.
+ *
  * @since File-Change HITL Redesign (Phase 3 — CAS deep-agent wiring); sub-agent
- * gitignored capture parity (Session 26, DD-19); shell restore (issue #248)
+ * gitignored capture parity (Session 26, DD-19); shell restore (issue #248);
+ * virtual-root confinement (issue #754)
  */
 
 import { FilesystemBackend, LocalShellBackend } from "deepagents";
@@ -111,12 +128,12 @@ export async function createCasCaptureBackend(
 
   if (shellEnv !== undefined) {
     const backend = new CasCaptureShellBackend(
-      { rootDir, env: shellEnv },
+      { rootDir, virtualMode: true, env: shellEnv },
       { observer },
     );
     await backend.initialize();
     return backend;
   }
 
-  return new CasCaptureFilesystemBackend({ rootDir }, { observer });
+  return new CasCaptureFilesystemBackend({ rootDir, virtualMode: true }, { observer });
 }