@stigmer/runner 3.32.0 → 3.33.0

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

@@ -0,0 +1,148 @@
+// Covers the native file tools' read of platform content (skills, attached
+// inputs, the approved plan) at `.stigmer/…`, on the backends production
+// builds (`createCasCaptureBackend` + `mountPlatformRoute`, parent and
+// sub-agents alike). The stock virtual-rooted backend refuses to follow the
+// workspace link out of the root; the route mounts the platform dir instead,
+// read-only, on the turns the link exists. What is pinned:
+//  - the stock backend's refusal (why the route exists);
+//  - reads, listings and search through the route, for the shell-capable and
+//    the plan-mode backend, with `execute` kept exactly where it was;
+//  - every mutation through the route refused, and a root delete refused
+//    before it touches the workspace or the platform dir;
+//  - no route on a turn without the link.
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FilesystemBackend, isSandboxBackend } from "deepagents";
+import type { AnyBackendProtocol, BackendProtocolV2 } from "deepagents";
+
+import { createCasCaptureBackend } from "../cas-capture-backend.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import { PLATFORM_ROUTE_PREFIX, PlatformRoutedBackend, mountPlatformRoute } from "../platform-route.js";
+import { LocalWorkspaceBackend } from "../../../shared/workspace/local-backend.js";
+import { ensureStigmerSymlink } from "../../../shared/workspace/stigmer-link.js";
+
+const SKILL = ".stigmer/skills/my-skill/SKILL.md";
+const PLAN = ".stigmer/inputs/notes_ab12cd34.plan.md";
+
+describe("platform route", () => {
+  let workspaceDir: string;
+  let platformDir: string;
+
+  beforeEach(async () => {
+    workspaceDir = await mkdtemp(join(tmpdir(), "platform-route-ws-"));
+    platformDir = await mkdtemp(join(tmpdir(), "platform-route-platform-"));
+    // The same physical writes the skill writer and the attachment resolver
+    // perform, through the platform-routing workspace backend.
+    const writer = new LocalWorkspaceBackend(workspaceDir, platformDir);
+    await writer.writeFile(SKILL, "# My Skill\n\nDo skillful things.\n");
+    await writer.writeFile(PLAN, "# The Approved Plan\n\nStep 1: do the thing.\n");
+    await writeFile(join(workspaceDir, "main.go"), "package main\n");
+  });
+
+  afterEach(async () => {
+    await rm(workspaceDir, { recursive: true, force: true });
+    await rm(platformDir, { recursive: true, force: true });
+  });
+
+  const observer = () => new CasCaptureObserver({ rootDir: workspaceDir, isIgnored: async () => true });
+
+  /** The parent's backend as `turn-setup.ts` builds it: shell-capable, or plan mode's filesystem-only one. */
+  async function productionBackend(mode: "shell" | "plan"): Promise<AnyBackendProtocol> {
+    const workspace = await createCasCaptureBackend({
+      rootDir: workspaceDir,
+      observer: observer(),
+      ...(mode === "shell" ? { shellEnv: {} } : {}),
+    });
+    return mountPlatformRoute(workspace, { workspaceDir, platformDir });
+  }
+
+  function v2(backend: AnyBackendProtocol): BackendProtocolV2 {
+    return backend as BackendProtocolV2;
+  }
+
+  it("the stock virtual-rooted backend refuses a path through the link (why the route exists)", async () => {
+    await ensureStigmerSymlink(workspaceDir, platformDir);
+    const stock = new FilesystemBackend({ rootDir: workspaceDir, virtualMode: true });
+    const result = await stock.read(`/${SKILL}`);
+    expect(result.content).toBeUndefined();
+    expect(result.error).toMatch(/outside root/i);
+  });
+
+  describe.each(["shell", "plan"] as const)("the %s backend with the link", (mode) => {
+    beforeEach(async () => {
+      await ensureStigmerSymlink(workspaceDir, platformDir);
+    });
+
+    it("reads a skill and the approved plan at the paths the prompts name", async () => {
+      const backend = v2(await productionBackend(mode));
+      expect(backend).toBeInstanceOf(PlatformRoutedBackend);
+      expect((await backend.read(`/${SKILL}`)).content).toContain("My Skill");
+      expect((await backend.read(`/${PLAN}`)).content).toContain("The Approved Plan");
+      expect((await backend.read("/main.go")).content, "the workspace is still the default").toContain("package main");
+    });
+
+    it("lists the platform once at the root, and its contents inside the route", async () => {
+      const backend = v2(await productionBackend(mode));
+      const root = (await backend.ls("/")).files ?? [];
+      expect(root.filter((f) => f.path === PLATFORM_ROUTE_PREFIX), "one entry, not two").toHaveLength(1);
+      expect(root.map((f) => f.path)).toContain("/main.go");
+      const inside = (await backend.ls(PLATFORM_ROUTE_PREFIX)).files ?? [];
+      expect(inside.map((f) => f.path).sort()).toEqual(["/.stigmer/inputs/", "/.stigmer/skills/"]);
+    });
+
+    it("finds a skill by glob from the root", async () => {
+      const backend = v2(await productionBackend(mode));
+      const found = (await backend.glob("**/SKILL.md", "/")).files ?? [];
+      expect(found.map((f) => f.path)).toContain(`/${SKILL}`);
+    });
+
+    it("keeps `execute` exactly where the workspace backend had it", async () => {
+      const backend = await productionBackend(mode);
+      expect(isSandboxBackend(backend)).toBe(mode === "shell");
+    });
+
+    it("refuses every mutation of platform content", async () => {
+      const backend = v2(await productionBackend(mode));
+      expect((await backend.write(`${PLATFORM_ROUTE_PREFIX}new.md`, "x")).error).toMatch(/read-only/);
+      expect((await backend.edit(`/${SKILL}`, "My Skill", "Your Skill")).error).toMatch(/read-only/);
+      expect((await backend.delete!(`${PLATFORM_ROUTE_PREFIX}skills`)).error).toMatch(/read-only/);
+      expect(await readFile(join(platformDir, "skills/my-skill/SKILL.md"), "utf8")).toContain("My Skill");
+    });
+
+    it("refuses a root delete before it touches the workspace or the platform dir", async () => {
+      const backend = v2(await productionBackend(mode));
+      expect((await backend.delete!("/")).error).toBeDefined();
+      expect(await readFile(join(workspaceDir, "main.go"), "utf8")).toBe("package main\n");
+      expect(await readFile(join(platformDir, "skills/my-skill/SKILL.md"), "utf8")).toContain("My Skill");
+    });
+  });
+
+  it("mounts nothing on a turn without the link", async () => {
+    const workspace = await createCasCaptureBackend({ rootDir: workspaceDir, observer: observer(), shellEnv: {} });
+    expect(await mountPlatformRoute(workspace, { workspaceDir, platformDir })).toBe(workspace);
+    expect(await mountPlatformRoute(workspace, { workspaceDir, platformDir: undefined })).toBe(workspace);
+  });
+
+  it("mounts nothing when the link points somewhere else", async () => {
+    const other = await mkdtemp(join(tmpdir(), "platform-route-other-"));
+    try {
+      await ensureStigmerSymlink(workspaceDir, other);
+      const workspace = await createCasCaptureBackend({ rootDir: workspaceDir, observer: observer() });
+      expect(await mountPlatformRoute(workspace, { workspaceDir, platformDir })).toBe(workspace);
+    } finally {
+      await rm(other, { recursive: true, force: true });
+    }
+  });
+
+  it("a workspace entry of its own is untouched by the route", async () => {
+    await mkdir(join(workspaceDir, "src"));
+    await writeFile(join(workspaceDir, "src/a.ts"), "export {};\n");
+    await ensureStigmerSymlink(workspaceDir, platformDir);
+    const backend = v2(await productionBackend("shell"));
+    expect((await backend.write("/src/b.ts", "export const b = 1;\n")).error).toBeUndefined();
+    expect(await readFile(join(workspaceDir, "src/b.ts"), "utf8")).toBe("export const b = 1;\n");
+  });
+});

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

@@ -518,6 +518,30 @@ describe("transformAndCompileSubagents", () => {
     warnSpy.mockRestore();
   });
 
+  it("a sub-agent name declared twice resolves to the later declaration", async () => {
+    // deepagents refuses duplicate sub-agent names and would fail the turn;
+    // the runner keeps the behaviour agents were written against.
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const result = await transformAndCompileSubagents({
+      ...baseOptions,
+      subAgents: [
+        mockSubAgentProto({ name: "reviewer", description: "The first reviewer." }),
+        mockSubAgentProto({ name: "reviewer", description: "The later reviewer." }),
+      ],
+    } as Parameters<typeof transformAndCompileSubagents>[0]);
+
+    expect(result).not.toBeNull();
+    const reviewers = result!.filter((r) => r.name === "reviewer");
+    expect(reviewers).toHaveLength(1);
+    expect(reviewers[0].description).toBe("The later reviewer.");
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("declared more than once"));
+
+    logSpy.mockRestore();
+    warnSpy.mockRestore();
+  });
+
   it("gracefully handles transform failures for individual subagents", async () => {
     const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});

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

@@ -230,21 +230,26 @@ describe("middleware stack ordering in createDeepAgent", () => {
 
   it("places SummarizationMiddleware before custom middleware", () => {
     /**
-     * Verified by reading createDeepAgent source (index.js lines 8165-8173):
+     * Verified by reading createDeepAgent's source (deepagents 1.14.1,
+     * `src/agent.ts`, the `coreMiddleware` / `tailMiddleware` pair merged by
+     * `mergeMiddlewareStack`):
      *
-     *   const middleware = [
-     *     todoMiddleware,
+     *   [
      *     ...skillsMiddleware,
      *     fsMiddleware,
      *     subagentMiddleware,
-     *     summarizationMiddleware,   // <-- position 4 (0-indexed)
+     *     summarizationMiddleware,
      *     patchToolCallsMiddleware,
      *     ...asyncSubAgents,
      *     ...customMiddleware,       // <-- Stigmer's stack goes here
+     *     ...profile extraMiddleware,
      *     ...cacheMiddleware,
      *     ...memory,
      *     ...interruptOn,
-     *   ];
+     *   ]
+     *
+     * (a custom middleware named like a default replaces it in place; no
+     * Stigmer middleware shares a default's name).
      *
      * This means summarization's wrapModelCall runs before Stigmer's
      * cost-cap wrapModelCall, so:
@@ -279,13 +284,14 @@ describe("middleware stack ordering in createDeepAgent", () => {
 
   it("creates SummarizationMiddleware with the same backend passed to createDeepAgent", () => {
     /**
-     * Verified from source (index.js line 8162):
+     * Verified from source (deepagents 1.14.1 `src/agent.ts`):
      *   createSummarizationMiddleware({ backend })
      *
      * The `backend` variable is the same one received in createDeepAgent params.
      * This means summarization uses the same StateBackend instance, so
      * offloaded conversation history is stored in LangGraph state which
-     * the HttpCheckpointSaver persists to MongoDB via the proxy.
+     * the checkpoint saver persists (in cloud, the HttpCheckpointSaver
+     * through the proxy's checkpoint store).
      */
     const backend = new StateBackend();
 
@@ -300,13 +306,14 @@ describe("middleware stack ordering in createDeepAgent", () => {
 
   it("resolves summarization model from the agent model (no explicit model option)", () => {
     /**
-     * Verified from source (index.js lines 4067, 8114):
+     * Verified from source (deepagents 1.14.1 `src/agent.ts` and
+     * `src/middleware/summarization.ts`):
      *
      *   createSummarizationMiddleware({ backend })
      *   // No `model` option passed
      *
      *   // Inside wrapModelCall:
-     *   const resolvedModel = request.model ?? await getChatModel();
+     *   const resolvedModel = requestModel ?? (await getChatModel());
      *
      * Since no model option is provided, the middleware uses request.model
      * which is the same ChatAnthropic instance from turn-setup.ts with the

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

@@ -19,11 +19,16 @@
  * deepagents rejects filesystem `permissions` combined with an execution-capable
  * backend — plan mode is read-only by construction, so no shell tool there.
  *
- * deepagents mutates only via `write` (create/overwrite) and `edit` (modify);
- * there is no backend delete/rename, so this observes CREATE and MODIFY. A
- * delete-category tool consequently cannot be observed here — the approval gate
- * records its before-bytes at authorization time instead (`captureDeleteBefore`,
- * issue #303). A delete via shell (`rm`) stays on the approval gate as always.
+ * The observed mutations are `write` (create, or since deepagents 1.12 a
+ * whole-file overwrite — `recordBefore` reads the existing bytes either way)
+ * and `edit` (modify), so this observes CREATE and MODIFY. deepagents 1.13
+ * added a recursive backend `delete` and a `delete` tool over it; the native
+ * harness does not expose that tool (`deepagents-profiles.ts`), and these
+ * backends refuse a backend delete outright, so a graph whose model no profile
+ * resolves cannot delete a subtree behind the observer's back. Deleting stays
+ * on the shell (`rm`), which the approval gate holds as always, and a
+ * delete-category tool from elsewhere has its before-bytes recorded by the gate
+ * at authorization time (`captureDeleteBefore`, issue #303).
  *
  * VIRTUAL ROOT — THE ONE PATH DIALECT (issue #754)
  * ------------------------------------------------
@@ -47,7 +52,7 @@
  */
 
 import { FilesystemBackend, LocalShellBackend } from "deepagents";
-import type { LocalShellBackendOptions } from "deepagents";
+import type { DeleteResult, LocalShellBackendOptions } from "deepagents";
 import type { CasCaptureObserver } from "./cas-capture-observer.js";
 
 export type { CasBeforeMap } from "./cas-capture-observer.js";
@@ -58,6 +63,12 @@ type FilesystemBackendOptions = NonNullable<
 
 type CasCaptureDeps = { readonly observer: CasCaptureObserver };
 
+function refusedDelete(filePath: string): DeleteResult {
+  return {
+    error: `Error: deleting '${filePath}' through the file tools is not available; use the shell (rm)`,
+  };
+}
+
 export class CasCaptureFilesystemBackend extends FilesystemBackend {
   private readonly observer: CasCaptureObserver;
 
@@ -80,6 +91,10 @@ export class CasCaptureFilesystemBackend extends FilesystemBackend {
     await this.observer.recordBefore(filePath);
     return super.edit(filePath, oldString, newString, replaceAll);
   }
+
+  override async delete(filePath: string): Promise<DeleteResult> {
+    return refusedDelete(filePath);
+  }
 }
 
 export class CasCaptureShellBackend extends LocalShellBackend {
@@ -104,6 +119,10 @@ export class CasCaptureShellBackend extends LocalShellBackend {
     await this.observer.recordBefore(filePath);
     return super.edit(filePath, oldString, newString, replaceAll);
   }
+
+  override async delete(filePath: string): Promise<DeleteResult> {
+    return refusedDelete(filePath);
+  }
 }
 
 export type CasCaptureBackend = CasCaptureFilesystemBackend | CasCaptureShellBackend;

package/src/activities/execute-deep-agent/deepagents-profiles.ts

@@ -1,19 +1,34 @@
 /**
  * Stigmer-specific deepagents harness profile registrations.
  *
- * deepagents 1.10.x auto-injects a built-in `general-purpose` sub-agent into
- * every `createDeepAgent()` call unless the caller supplies one with that name.
- * The injected sub-agent carries only deepagents' built-in middleware — not our
- * approval gate — so it is an ungated write/edit path today and would be an
- * ungated `execute` path with a shell backend.
+ * Two defaults of deepagents' `createDeepAgent()` are turned off for every
+ * provider the runner builds a model for:
  *
- * Registrations merge additively with deepagents' built-in prompt profiles, so
- * disabling auto-injection here does not alter model prompt overlays.
+ * - The auto-injected `general-purpose` sub-agent. It carries only
+ *   deepagents' built-in middleware — not our approval gate — so it would be
+ *   an ungated write/edit path, and an ungated `execute` path with a shell
+ *   backend. The runner compiles its own gated `general-purpose` instead
+ *   (`subagent-transformer.ts`).
+ * - The built-in `delete` tool (deepagents 1.13+), a recursive delete through
+ *   the backend. The CAS capture backends observe `write` and `edit` only, so
+ *   a directory delete would lose the before-bytes file review needs for the
+ *   gitignored files beneath it. Deleting stays where it has always been on
+ *   this harness: `rm` through the approval-gated shell. Excluding the tool
+ *   here means the filesystem middleware never builds it, on the parent and
+ *   on every sub-agent (1.14 resolves the profile per sub-agent model); the
+ *   capture backends refuse a backend delete as well, for a graph whose model
+ *   no profile resolves (`cas-capture-backend.ts`).
+ *
+ * Registrations merge additively with deepagents' built-in model profiles, so
+ * neither exclusion alters the model prompt overlays.
  */
 
 import { registerHarnessProfile } from "deepagents";
 
-const PROVIDERS_WITH_GP_SUPPRESSION = ["anthropic", "openai"] as const;
+const PROVIDERS_WITH_STIGMER_PROFILE = ["anthropic", "openai"] as const;
+
+/** Built-in tools the native harness never exposes; see the header. */
+export const EXCLUDED_BUILTIN_TOOLS: readonly string[] = ["delete"];
 
 let registered = false;
 
@@ -22,9 +37,10 @@ export function registerStigmerDeepagentsProfiles(): void {
   if (registered) return;
   registered = true;
 
-  for (const provider of PROVIDERS_WITH_GP_SUPPRESSION) {
+  for (const provider of PROVIDERS_WITH_STIGMER_PROFILE) {
     registerHarnessProfile(provider, {
       generalPurposeSubagent: { enabled: false },
+      excludedTools: [...EXCLUDED_BUILTIN_TOOLS],
     });
   }
 }

package/src/activities/execute-deep-agent/platform-route.ts

@@ -0,0 +1,134 @@
+/**
+ * The platform's read-only `.stigmer/` mount inside the native agent's
+ * virtual filesystem.
+ *
+ * WHY A ROUTE, NOT THE SYMLINK
+ * ----------------------------
+ * Platform content — resolved skills, attached inputs, the approved plan —
+ * lives in the session's platform dir, outside the workspace, and reaches the
+ * agent at `.stigmer/…` (`shared/workspace/stigmer-link.ts`). The Cursor SDK
+ * and the shell follow the workspace's `.stigmer` symlink to it. The native
+ * file tools cannot: deepagents (since 1.14) resolves every path of a
+ * `virtualMode` backend to its REAL location and refuses one that lands
+ * outside the root ("Path '…' resolves outside root directory",
+ * `FilesystemBackend.assertRealPathWithinRoot`), and every backend the native
+ * harness builds is virtual-rooted (`cas-capture-backend.ts`, issue #754).
+ * Turning that confinement off would reopen the escape it closes, so the
+ * platform dir is mounted instead through deepagents' own router,
+ * `CompositeBackend`, at exactly the prefix the prompts name.
+ *
+ * WHY READ-ONLY
+ * -------------
+ * Nothing legitimately writes platform content from a turn: inputs are
+ * presented as read-only and plan mode denies every write. A writable mount
+ * would also be dangerous and unreviewed: `CompositeBackend.delete` fans a
+ * delete out to every route beneath its target, so a delete of `/` or of
+ * `/.stigmer` would empty the platform dir, and a routed write would reach
+ * the platform dir without passing the CAS observer that file review reads.
+ * Every mutation through the mount therefore fails, which also makes the
+ * composite refuse any fan-out that touches it.
+ *
+ * WHEN IT IS MOUNTED
+ * ------------------
+ * On the turns where the workspace link points at the platform dir — the
+ * turns whose skill or attachment phase made it — so what the agent can
+ * reach is exactly what the link exposes to the shell on the same turn.
+ * The link itself stays: shell commands (a skill's own scripts among them)
+ * run in the workspace and resolve `.stigmer/…` through it.
+ */
+
+import { CompositeBackend, FilesystemBackend } from "deepagents";
+import type {
+  AnyBackendProtocol,
+  DeleteResult,
+  EditResult,
+  FileUploadResponse,
+  LsResult,
+  WriteResult,
+} from "deepagents";
+import { STIGMER_LOCAL_STATE_DIR, stigmerSymlinkPointsAt } from "../../shared/workspace/stigmer-link.js";
+
+/** The route prefix, with the trailing slash `CompositeBackend` needs to match `/.stigmer/x` but never `/.stigmerx`. */
+export const PLATFORM_ROUTE_PREFIX = `/${STIGMER_LOCAL_STATE_DIR}/`;
+
+function readOnly(routedPath: string): string {
+  const agentPath = `${PLATFORM_ROUTE_PREFIX.slice(0, -1)}${routedPath}`;
+  return (
+    `Error: '${agentPath}' is platform content (skills, attached inputs, the approved plan) ` +
+    "and is read-only; write your own files in the workspace"
+  );
+}
+
+/** The platform dir, virtual-rooted like every native backend, refusing every mutation. */
+export class PlatformContentBackend extends FilesystemBackend {
+  constructor(platformDir: string) {
+    super({ rootDir: platformDir, virtualMode: true });
+  }
+
+  override async write(filePath: string): Promise<WriteResult> {
+    return { error: readOnly(filePath) };
+  }
+
+  override async edit(filePath: string): Promise<EditResult> {
+    return { error: readOnly(filePath) };
+  }
+
+  override async delete(filePath: string): Promise<DeleteResult> {
+    return { error: readOnly(filePath) };
+  }
+
+  override async uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]> {
+    return files.map(([path]) => ({ path, error: "permission_denied" }));
+  }
+}
+
+/**
+ * The workspace backend with the platform mounted at {@link PLATFORM_ROUTE_PREFIX}.
+ *
+ * One behaviour differs from the stock router: listing `/`. The composite
+ * adds each route to the root listing, and the workspace backend already
+ * lists `.stigmer/` by following the link, so the stock listing names the
+ * same directory twice; the root listing is de-duplicated by path.
+ */
+export class PlatformRoutedBackend extends CompositeBackend {
+  override async ls(path: string): Promise<LsResult> {
+    const result = await super.ls(path);
+    if (path !== "/" || !result.files) return result;
+    const seen = new Set<string>();
+    return {
+      ...result,
+      files: result.files.filter((entry) => {
+        if (seen.has(entry.path)) return false;
+        seen.add(entry.path);
+        return true;
+      }),
+    };
+  }
+}
+
+export interface PlatformRouteOptions {
+  /** The workspace root the backend is rooted at (where the link lives). */
+  readonly workspaceDir: string;
+  /** The session's platform dir; absent when the session has none. */
+  readonly platformDir: string | undefined;
+}
+
+/**
+ * Mount the platform route over `backend` when this turn exposes platform
+ * content; otherwise hand `backend` back unchanged. `execute` and the
+ * sandbox identity stay the workspace backend's (`CompositeBackend` delegates
+ * both to its default), so a shell-capable graph keeps its `execute` tool and
+ * a plan-mode graph stays without one.
+ */
+export async function mountPlatformRoute(
+  backend: AnyBackendProtocol,
+  options: PlatformRouteOptions,
+): Promise<AnyBackendProtocol> {
+  const { workspaceDir, platformDir } = options;
+  if (platformDir === undefined || !(await stigmerSymlinkPointsAt(workspaceDir, platformDir))) {
+    return backend;
+  }
+  return new PlatformRoutedBackend(backend, {
+    [PLATFORM_ROUTE_PREFIX]: new PlatformContentBackend(platformDir),
+  });
+}

package/src/activities/execute-deep-agent/subagent-transformer.ts

@@ -23,7 +23,7 @@
  */
 
 import { createDeepAgent, FilesystemBackend, LocalShellBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT } from "deepagents";
-import type { CompiledSubAgent, FilesystemPermission } from "deepagents";
+import type { AnyBackendProtocol, CompiledSubAgent, FilesystemPermission } from "deepagents";
 import type { StructuredTool } from "@langchain/core/tools";
 import type { RunnableConfig } from "@langchain/core/runnables";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
@@ -33,6 +33,7 @@ import type { SubAgent, McpServerUsage } from "@stigmer/protos/ai/stigmer/agenti
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
 import type { ApprovalGateConfig } from "../../middleware/approval-gate.js";
 import { createCasCaptureBackend } from "./cas-capture-backend.js";
+import { mountPlatformRoute } from "./platform-route.js";
 import type { CasCaptureObserver } from "./cas-capture-observer.js";
 import type { CostAdvisoryMiddleware, StigmerMiddleware } from "../../middleware/index.js";
 import { createThinkTool, createWebFetchTool, type GuardPosture } from "../../tools/index.js";
@@ -472,9 +473,23 @@ export function modelHasNativeThinking(modelId: string): boolean {
  *
  * Every variant is virtual-rooted (`virtualMode: true`) like the parent's —
  * see the cas-capture-backend.ts header (issue #754): workspace confinement
- * is structural on every graph, sub-agents included.
+ * is structural on every graph, sub-agents included. Every variant also gets
+ * the parent's read-only `.stigmer/` platform mount (`platform-route.ts`), so
+ * a sub-agent reads its skills where its prompt says they are.
  */
 async function buildSubagentBackend(opts: {
+  readonly workspaceRootDir: string;
+  readonly platformDir?: string;
+  readonly casObserver?: CasCaptureObserver;
+  readonly shellEnv?: Record<string, string>;
+}): Promise<AnyBackendProtocol> {
+  return mountPlatformRoute(await buildSubagentWorkspaceBackend(opts), {
+    workspaceDir: opts.workspaceRootDir,
+    platformDir: opts.platformDir,
+  });
+}
+
+async function buildSubagentWorkspaceBackend(opts: {
   readonly workspaceRootDir: string;
   readonly casObserver?: CasCaptureObserver;
   readonly shellEnv?: Record<string, string>;
@@ -516,6 +531,8 @@ export async function compileSubagents(
     readonly approvalGate?: ApprovalGateConfig | null;
     readonly parentModelName: string;
     readonly workspaceRootDir: string;
+    /** The session's platform dir, mounted read-only at `.stigmer/` (`platform-route.ts`). */
+    readonly platformDir?: string;
     /** Shared CAS observer (capture mode only); see {@link SubagentTransformOptions.casObserver}. */
     readonly casObserver?: CasCaptureObserver;
     readonly modelFactory?: (modelName: string) => Promise<BaseChatModel>;
@@ -697,11 +714,27 @@ export async function transformAndCompileSubagents(
     }
   }
 
-  // Step 3: Merge built-ins with transformed (proto overrides take precedence)
-  const protoNames = new Set(transformed.map((t) => t.name));
+  // Step 3: Merge built-ins with transformed (proto overrides take precedence).
+  // Names are unique by the time deepagents sees them: since 1.14 it refuses
+  // a duplicate sub-agent name and fails the turn, where it used to let the
+  // later one win. Nothing upstream of the runner validates the names, so the
+  // runner keeps the behaviour agents were written against — a later
+  // declaration overrides an earlier one of the same name, as a proto
+  // definition overrides a built-in.
+  const declared = new Map<string, TransformedSubagent>();
+  for (const spec of transformed) {
+    if (declared.has(spec.name)) {
+      console.warn(
+        `[subagent-transformer] Sub-agent name '${spec.name}' is declared more than once. ` +
+        "The later declaration overrides the earlier one.",
+      );
+      declared.delete(spec.name);
+    }
+    declared.set(spec.name, spec);
+  }
   const allSpecs = [
-    ...builtins.filter((b) => !protoNames.has(b.name)),
-    ...transformed,
+    ...builtins.filter((b) => !declared.has(b.name)),
+    ...declared.values(),
   ];
 
   if (allSpecs.length === 0) {
@@ -715,6 +748,7 @@ export async function transformAndCompileSubagents(
     approvalGate,
     parentModelName,
     workspaceRootDir: workspaceBackend.rootDir,
+    platformDir: workspaceBackend.platformDir,
     casObserver,
     modelFactory,
     shellEnv,

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -2,12 +2,10 @@
  * Sub-agent middleware composition for ExecuteDeepAgent.
  *
  * Each sub-agent gets its own middleware stack with:
- * - Path normalization (issue #429), FIRST and only on permission-rule-
- *   bearing graphs (plan mode) — workspace-relative paths are rewritten to
- *   workspace-absolute before deepagents' permission validation refuses
- *   them, exactly as on the parent. `compileSubagents` derives it from the
- *   same `permissions` option it bakes into the graph, keeping the rules
- *   and their normalization shim coupled.
+ * - Path normalization (issue #429), FIRST, on every graph since issue #754
+ *   — workspace-relative paths are rewritten to the virtual root's dialect
+ *   before deepagents' permission validation and the backend see them,
+ *   exactly as on the parent (`compileSubagents` always passes it).
  * - Fresh loop detection (independent cycle tracking)
  * - Tool intent (issue #276) — the shell tool's bind-time schema gains the
  *   optional model-authored `description`, so sub-agent shell rows carry
@@ -94,7 +92,7 @@ export interface SubAgentMiddlewareOptions {
  * workspace-absolute paths (matching the parent). The gate sits before the
  * cost-cap view so an approval pause happens before budget accounting, and
  * error hints come after the gate — both matching the parent order
- * (…→ truncation → graceful-stop → approval gate → cost cap → error hints …),
+ * (…→ truncation → approval gate → cost cap → error hints …),
  * which keeps the gate's HITL interrupt outside the hints' try/catch.
  */
 export function buildSubAgentMiddleware(

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

@@ -39,8 +39,12 @@
  * sub-agent's rows carry none on either harness today (#1133), and one
  * handler set would otherwise stamp them as a side effect.
  *
- * The scope, in LangGraph 1.3.2's grammar (mirrors deepagents'
- * `createSubagentTransformer`): the root's model events arrive under
+ * The scope, in LangGraph's v3 grammar (read at @langchain/langgraph 1.3.2,
+ * and unchanged at 1.4.18 — the delegation, to-do, tool-call, structured-
+ * output and approval-resume streams were recorded on both and compared;
+ * deepagents' own `createSubagentTransformer`, which this once mirrored, left
+ * with deepagents 1.14 and langchain's `createAgent` registers its
+ * successor): the root's model events arrive under
  * `["model_request:<uuid>"]` and its tool events under `["tools:<uuid>"]`
  * (one segment); a `task` tool start at that depth opens a sub-agent, and
  * the segment it arrived under is the prefix every event of that sub-agent's