@stigmer/runner 3.10.0 → 3.11.0

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

@@ -600,24 +600,97 @@ describe("injectAttachments", () => {
     expect(Buffer.compare(writtenBuffer, binaryContent)).toBe(0);
   });
 
-  it("detects mount path collision before any downloads", async () => {
+  it("uniquifies duplicate default-derived filenames instead of failing (issue #364)", async () => {
+    const contentA = Buffer.from("first");
+    const contentB = Buffer.from("second");
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/data.csv", contentA);
+    await storage.upload("attachments/b/data.csv", contentB);
+
+    const backend = mockWorkspaceBackend();
+
+    const result = await injectAttachments({
+      backend,
+      attachments: [
+        makeAttachment({ filename: "data.csv", storageKey: "attachments/a/data.csv" }),
+        makeAttachment({ filename: "data.csv", storageKey: "attachments/b/data.csv" }),
+      ],
+      storage,
+      isLocalMode: false,
+    });
+
+    // Both files land, both downloads run — the execution is never burned
+    // over a mechanically resolvable name.
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({
+      filename: "data.csv",
+      path: ".stigmer/inputs/data.csv",
+    });
+    expect(result[0].renamedFrom).toBeUndefined();
+    // The rename follows the platform's stem-2.ext semantics and carries the
+    // disclosure payload for the prompt.
+    expect(result[1]).toMatchObject({
+      filename: "data-2.csv",
+      path: ".stigmer/inputs/data-2.csv",
+      renamedFrom: "data.csv",
+    });
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/data.csv", contentA,
+    );
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(
+      ".stigmer/inputs/data-2.csv", contentB,
+    );
+  });
+
+  it("rejects two attachments explicitly pinning the same mountPath (a user contradiction)", async () => {
     const backend = mockWorkspaceBackend();
     const storage = makeMockStorage();
 
     await expect(injectAttachments({
       backend,
       attachments: [
-        makeAttachment({ filename: "data.csv", storageKey: "key1" }),
-        makeAttachment({ filename: "data.csv", storageKey: "key2" }),
+        makeAttachment({ filename: "a.csv", storageKey: "key1", mountPath: "inputs/data.csv" }),
+        makeAttachment({ filename: "b.csv", storageKey: "key2", mountPath: "inputs/data.csv" }),
       ],
       storage,
       isLocalMode: false,
     })).rejects.toThrow(/collides with/);
 
-    // Verify no downloads were attempted
+    // The contradiction is detected before any downloads
     expect(storage.download).not.toHaveBeenCalled();
   });
 
+  it("default-derived names dodge an explicit mountPath already inside the inputs prefix", async () => {
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/pinned", Buffer.from("pinned"));
+    await storage.upload("attachments/b/report.pdf", Buffer.from("derived"));
+
+    const backend = mockWorkspaceBackend();
+
+    const result = await injectAttachments({
+      backend,
+      attachments: [
+        // Listed AFTER the default-derived attachment: explicit paths claim
+        // first regardless of order, so the default still dodges.
+        makeAttachment({ filename: "report.pdf", storageKey: "attachments/b/report.pdf" }),
+        makeAttachment({
+          filename: "report.pdf",
+          storageKey: "attachments/a/pinned",
+          mountPath: ".stigmer/inputs/report.pdf",
+        }),
+      ],
+      storage,
+      isLocalMode: false,
+    });
+
+    const byPath = new Map(result.map((f) => [f.path, f]));
+    expect(byPath.get(".stigmer/inputs/report.pdf")?.renamedFrom).toBeUndefined();
+    expect(byPath.get(".stigmer/inputs/report-2.pdf")).toMatchObject({
+      filename: "report-2.pdf",
+      renamedFrom: "report.pdf",
+    });
+  });
+
   it("derives filename from storageKey when filename is empty", async () => {
     const content = Buffer.from("fallback");
     const localFile = join(tempDir, "fallback.txt");
@@ -662,7 +735,7 @@ describe("injectAttachments", () => {
     expect(result[0].path).toBe("workspace/input.csv");
   });
 
-  it("error message includes attachment filename and actionable suggestion", async () => {
+  it("explicit-collision error names both attachments and stays actionable", async () => {
     const backend = mockWorkspaceBackend();
     const storage = makeMockStorage();
 
@@ -670,8 +743,8 @@ describe("injectAttachments", () => {
       await injectAttachments({
         backend,
         attachments: [
-          makeAttachment({ filename: "first.csv" }),
-          makeAttachment({ filename: "first.csv", storageKey: "key2" }),
+          makeAttachment({ filename: "first.csv", mountPath: "inputs/shared.csv" }),
+          makeAttachment({ filename: "second.csv", storageKey: "key2", mountPath: "inputs/shared.csv" }),
         ],
         storage,
         isLocalMode: false,
@@ -680,7 +753,7 @@ describe("injectAttachments", () => {
     } catch (err) {
       expect(err).toBeInstanceOf(AttachmentInjectionError);
       const injErr = err as AttachmentInjectionError;
-      expect(injErr.attachmentFilename).toBe("first.csv");
+      expect(injErr.attachmentFilename).toBe("second.csv");
       expect(injErr.message).toContain("first.csv");
       expect(injErr.message).toContain("mountPath");
     }
@@ -860,6 +933,35 @@ describe("injectAttachments — vision selection", () => {
     expect(injected.visionDegraded).toBe("type_mismatch");
   });
 
+  it("labels a duplicate-renamed image's vision payload with the on-disk name", async () => {
+    // Coherence pin: the prompt lists the renamed path and the vision
+    // disclosure lists image filenames — if the offer used the original
+    // attachment.filename, the agent would see two images with one
+    // indistinguishable name.
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/photo.png", PNG_BYTES);
+    await storage.upload("attachments/b/photo.png", PNG_BYTES);
+
+    const injected = await injectAttachments({
+      backend,
+      attachments: [
+        makeAttachment({ filename: "photo.png", storageKey: "attachments/a/photo.png", contentType: "image/png" }),
+        makeAttachment({ filename: "photo.png", storageKey: "attachments/b/photo.png", contentType: "image/png" }),
+      ],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected[0].vision?.filename).toBe("photo.png");
+    expect(injected[1]).toMatchObject({
+      filename: "photo-2.png",
+      renamedFrom: "photo.png",
+    });
+    expect(injected[1].vision?.filename).toBe("photo-2.png");
+  });
+
   it("never offers an extract archive to the budget — extracted files carry no vision fields", async () => {
     // A PNG inside a ZIP has no attachment-level bytes; the archive rides the
     // normal extraction story with no vision involvement or disclosure.

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

@@ -0,0 +1,104 @@
+/**
+ * Datastore degradation disclosure, activity half (issue #325).
+ *
+ * The activity appends the operator-facing MESSAGE_SYSTEM notice to
+ * `initialStatus.messages` BEFORE streaming (index.ts) — deliberately not
+ * through a status builder, because the v2 and v3 stream paths each
+ * construct their own builder around that same proto. These tests pin the
+ * property that push site depends on: BOTH builders preserve pre-seeded
+ * messages (ExecutionState only appends; index rebuilds touch runtime
+ * tool-call state, and a MESSAGE_SYSTEM row carries no tool calls), so
+ * the notice survives whichever stream version runs and rides every
+ * persist. The prompt half (section selection) is pinned in
+ * shared/__tests__/datastore-attachment.test.ts.
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  EXPECTED_RECORD_TOOLS,
+  formatDatastoreDegradationNotice,
+} from "../../../shared/datastore-attachment.js";
+import { StatusBuilder } from "../status-builder.js";
+import { V3StatusBuilder } from "../v3-status-builder.js";
+import { normalize } from "../v3-protocol-normalizer.js";
+import {
+  resetSeq,
+  makeMessageStart,
+  makeMessageFinish,
+  makeTextDelta,
+} from "../__test-utils__/v3-event-fixtures.js";
+
+beforeEach(() => resetSeq());
+
+/** initialStatus as index.ts shapes it when setup reports missing tools. */
+function statusWithDegradationNotice(): AgentExecutionStatus {
+  const status = create(AgentExecutionStatusSchema, {});
+  status.messages.push(create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_SYSTEM,
+    content: formatDatastoreDegradationNotice(1, [...EXPECTED_RECORD_TOOLS]),
+    timestamp: "2026-08-11T00:00:00.000Z",
+  }));
+  return status;
+}
+
+describe("datastore degradation notice survives streaming (issue #325)", () => {
+  it("v2 StatusBuilder preserves the pre-seeded notice through a streamed turn", () => {
+    const initialStatus = statusWithDegradationNotice();
+    const sb = new StatusBuilder("exec-1", initialStatus);
+
+    sb.processEvent({
+      event: "on_chat_model_stream",
+      run_id: "run-1",
+      data: { chunk: { content: "I cannot reach the datastore right now." } },
+    });
+    sb.processEvent({ event: "on_chat_model_end", run_id: "run-1", data: {} });
+
+    const messages = sb.currentStatus.messages;
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+    expect(messages[0].type).toBe(MessageType.MESSAGE_SYSTEM);
+    expect(messages[0].content).toContain("0/5 record tools connected");
+    expect(messages[0].content).toContain("declared 1 datastore(s)");
+  });
+
+  it("v3 V3StatusBuilder preserves the pre-seeded notice through a streamed turn", () => {
+    const initialStatus = statusWithDegradationNotice();
+    const sb = new V3StatusBuilder("exec-1", initialStatus);
+
+    const protocolEvents = [
+      makeMessageStart("run-1"),
+      makeTextDelta("run-1", "I cannot reach the datastore right now."),
+      makeMessageFinish("run-1"),
+    ];
+    for (const raw of protocolEvents) {
+      for (const e of normalize(raw)) {
+        sb.processEvent(e);
+      }
+    }
+
+    const messages = sb.currentStatus.messages;
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+    expect(messages[0].type).toBe(MessageType.MESSAGE_SYSTEM);
+    expect(messages[0].content).toContain("0/5 record tools connected");
+  });
+
+  it("both builders share the initialStatus proto, so the append needs no builder", () => {
+    // The push-site contract itself: mutating initialStatus.messages is
+    // visible through whichever builder wraps it.
+    const initialStatus = create(AgentExecutionStatusSchema, {});
+    const sb = new StatusBuilder("exec-1", initialStatus);
+    initialStatus.messages.push(create(AgentMessageSchema, {
+      type: MessageType.MESSAGE_SYSTEM,
+      content: formatDatastoreDegradationNotice(2, ["delete_record"]),
+      timestamp: "2026-08-11T00:00:00.000Z",
+    }));
+    expect(sb.currentStatus.messages).toHaveLength(1);
+    expect(sb.currentStatus.messages[0].content).toContain(
+      "4/5 record tools connected",
+    );
+  });
+});

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

@@ -184,6 +184,7 @@ function fakeHttpRejectSetup(): SetupResult {
     session: { spec: { workspaceEntries: [] } },
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-reject-http" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",
@@ -219,6 +220,7 @@ function fakeMemoryRejectSetup(): SetupResult {
     session: { spec: { workspaceEntries: [] } },
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-reject-mem" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -264,6 +264,7 @@ function fakeDurableResumeSetup(): SetupResult {
     // path shared across files would serialize parallel test workers for real.
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-hitl-approve-all" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -219,6 +219,7 @@ function fakeDurableResumeSetup(): SetupResult {
     // path shared across files would serialize parallel test workers for real.
     workspaceBackend: { rootDir: "/tmp/stigmer-test-ws-hitl-history" },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -142,6 +142,10 @@ describe("buildEnhancedSystemPrompt", () => {
   });
 
   it("includes injected files section with size info", () => {
+    // The section renders the injector's own result type (sizeBytes). A local
+    // structural twin with a `size` field used to live in the prompt builder,
+    // and production wiring silently dropped the size — this pin holds the
+    // real field name so that drift class cannot return.
     const prompt = buildEnhancedSystemPrompt({
       instructions: "Test",
       provisionResults: [],
@@ -150,15 +154,40 @@ describe("buildEnhancedSystemPrompt", () => {
       workspaceFileRefs: [],
       workspaceRoot: "/workspace",
       injectedFiles: [
-        { filename: "data.csv", path: ".stigmer/inputs/data.csv", size: 1024 },
-        { filename: "notes.md", path: ".stigmer/inputs/notes.md", size: null },
+        { filename: "data.csv", path: ".stigmer/inputs/data.csv", sizeBytes: 1024 },
+        { filename: "notes.md", path: ".stigmer/inputs/notes.md", sizeBytes: 12 },
       ],
     });
 
     expect(prompt).toContain("## Input Files");
     expect(prompt).toContain("`.stigmer/inputs/data.csv` (1024 bytes)");
-    expect(prompt).toContain("`.stigmer/inputs/notes.md`");
-    expect(prompt).not.toContain("null");
+    expect(prompt).toContain("`.stigmer/inputs/notes.md` (12 bytes)");
+  });
+
+  it("discloses a duplicate-renamed injected file's original name", () => {
+    const prompt = buildEnhancedSystemPrompt({
+      instructions: "Test",
+      provisionResults: [],
+      containerRoot: "",
+      skillsPromptSection: "",
+      workspaceFileRefs: [],
+      workspaceRoot: "/workspace",
+      injectedFiles: [
+        { filename: "report.pdf", path: ".stigmer/inputs/report.pdf", sizeBytes: 10 },
+        {
+          filename: "report-2.pdf",
+          path: ".stigmer/inputs/report-2.pdf",
+          sizeBytes: 20,
+          renamedFrom: "report.pdf",
+        },
+      ],
+    });
+
+    expect(prompt).toContain(
+      "`.stigmer/inputs/report-2.pdf` (20 bytes) (renamed from duplicate 'report.pdf')",
+    );
+    // The first file keeps a clean entry — no disclosure noise.
+    expect(prompt).toContain("`.stigmer/inputs/report.pdf` (10 bytes)\n");
   });
 
   it("produces a git repo description for git workspace entries", () => {
@@ -361,7 +390,7 @@ describe("buildEnhancedSystemPrompt", () => {
     const planFile = {
       filename: "plan.md",
       path: ".stigmer/inputs/plan.md",
-      size: 1024,
+      sizeBytes: 1024,
     };
 
     it("appends the implement-plan directive pointing at the injected plan", () => {

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

@@ -196,6 +196,7 @@ function fakeMemoryGateSetup(opts: {
       readFile: vi.fn(async () => ""),
     },
     mcpConnection: null,
+    datastoreToolsMissing: [],
     mergedEnvVars: {},
     secretKeys: new Set<string>(),
     modelName: "claude-sonnet",

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

@@ -0,0 +1,173 @@
+/**
+ * End-to-end proof (real deepagents + LangGraph runtime, no LLM/network) that a
+ * plan-mode SUB-AGENT is read-only BY CONSTRUCTION (issue #255).
+ *
+ * The parent graph receives PLAN_MODE_PERMISSIONS in setup.ts, but deepagents'
+ * parent-permission inheritance covers only spec-style sub-agents — our
+ * pre-built CompiledSubAgents bypass `normalizeSubagentSpec` entirely, so
+ * `compileSubagents` must bake the rules into each sub-agent graph itself.
+ * These tests exercise that exact wiring with NO approval gate installed (the
+ * auto-approve-all shape): any denial must come from the permission rules
+ * alone, proving plan mode's "read-only by construction, not by gate"
+ * contract at the sub-agent level. A contrast case pins that without the
+ * 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
+ * graph sites), not a test copy, so a change to the plan-mode permission set
+ * re-proves sub-agent coverage automatically.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, readFile, writeFile, access } from "node:fs/promises";
+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 { CasCaptureObserver } from "../cas-capture-observer.js";
+import { compileSubagents } from "../subagent-transformer.js";
+import { ScriptedModel, type ScriptSelector } from "../__test-utils__/scripted-model.js";
+
+const SEEDED_CONTENT = "PLAN_MODE_README_TOKEN: hello from the seeded file";
+
+describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
+  let root: string;
+  let observer: CasCaptureObserver;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "sa-plan-"));
+    await mkdir(join(root, "dist"), { recursive: true });
+    await writeFile(join(root, "notes.md"), SEEDED_CONTENT);
+    // Everything is gitignored from the observer's view — the strictest case:
+    // every write would be CAS-observed if it ever reached the backend.
+    observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => true });
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * Compile a worker through the production path with NO approval gate, so the
+   * permission rules are the only thing standing between the model and the
+   * filesystem. `permissions` present = the plan-mode wiring under test;
+   * absent = the act-mode contrast.
+   */
+  async function compileWorker(script: ScriptSelector, planMode: boolean) {
+    const compiled = await compileSubagents(
+      [{ name: "worker", description: "test worker", systemPrompt: "do the work", tools: [] }],
+      {
+        approvalGate: null,
+        parentModelName: "test-model",
+        workspaceRootDir: root,
+        casObserver: observer,
+        modelFactory: async () => new ScriptedModel(script),
+        ...(planMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
+      },
+    );
+    expect(compiled).toHaveLength(1);
+    return compiled[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);
+  }
+
+  it("denies write_file and edit_file at the tool level, while read_file still works", async () => {
+    // One turn, three tool calls: both mutation tools must be denied by the
+    // permission rules; the read must pass through untouched (the deny rule
+    // covers the `write` operation class only).
+    // Real absolute workspace paths, as production models use (the prompt's
+    // file tree is absolute, and the tools' contract says absolute). With
+    // permission rules present this is also the only shape that reaches the
+    // rules at all: enforcePermission's canonicalization refuses relative
+    // paths with a validation error before any rule or backend runs — a
+    // different denial, but still nothing written.
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
+        { name: "edit_file", args: { file_path: join(root, "notes.md"), old_string: "hello", new_string: "HACKED" }, id: "c_edit" },
+        { name: "read_file", args: { file_path: join(root, "notes.md") }, id: "c_read" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t1" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    // Both mutations denied with deepagents' permission error, and nothing on disk:
+    // the new file was never created and the seeded file is byte-identical.
+    expect(toolResultById(result.messages, "c_write")).toMatch(/permission denied for write/i);
+    expect(toolResultById(result.messages, "c_edit")).toMatch(/permission denied for write/i);
+    await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
+    expect(await readFile(join(root, "notes.md"), "utf8")).toBe(SEEDED_CONTENT);
+
+    // The read flowed: its result carries the seeded content, not a denial.
+    const readResult = toolResultById(result.messages, "c_read");
+    expect(readResult).toContain("PLAN_MODE_README_TOKEN");
+    expect(readResult).not.toMatch(/permission denied/i);
+
+    // The denial fired INSIDE the tool handler, before any backend was reached:
+    // the CAS observer (which records pre-write bytes on the backend's write/edit
+    // seams) saw neither mutation.
+    expect(observer.before.size).toBe(0);
+  });
+
+  it("act-mode contrast: without the permissions option the same write lands (zero-delta outside plan mode)", async () => {
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, false);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t2" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    expect(toolResultById(result.messages, "c_write")).not.toMatch(/permission denied/i);
+    expect(await readFile(join(root, "dist/out.txt"), "utf8")).toBe("new file");
+    // And the backend WAS reached this time — the observer recorded a write.
+    // (Key shape is DD-19 territory, deliberately not pinned here.)
+    expect(observer.before.size).toBe(1);
+  });
+
+  it("relative-path mutations are refused too — by validation, before the rules", async () => {
+    // The native prompt steers models to workspace-relative paths, but
+    // deepagents' permission canonicalization accepts only absolute ones, so
+    // with rules present a relative-path call fails validation before any
+    // rule (or backend) runs. Read-only still holds — nothing is written —
+    // but the model sees "path must be absolute", not "permission denied",
+    // and prompt-compliant relative READS degrade the same way. That
+    // relative-vs-absolute friction is a pre-existing parent-plan-mode
+    // behavior, tracked as issue #429; this pins that the sub-agent's
+    // read-only contract survives it.
+    const script: ScriptSelector = () => ({
+      toolCalls: [
+        { name: "write_file", args: { file_path: "dist/out.txt", content: "new file" }, id: "c_write_rel" },
+      ],
+      done: "worker done",
+    });
+
+    const worker = await compileWorker(script, true);
+    const result = (await worker.runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t3" }, recursionLimit: 50 },
+    )) as { messages: BaseMessage[] };
+
+    expect(toolResultById(result.messages, "c_write_rel")).toMatch(/path must be absolute/i);
+    await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
+    expect(observer.before.size).toBe(0);
+  });
+});

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

@@ -7,10 +7,11 @@ describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
     const stack = buildSubAgentMiddleware();
 
-    expect(stack).toHaveLength(3);
+    expect(stack).toHaveLength(4);
     expect(stack[0].name).toBe("LoopDetectionMiddleware");
     expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
     expect(stack[2].name).toBe("ToolTruncationMiddleware");
+    expect(stack[3].name).toBe("ErrorHintsMiddleware");
   });
 
   it("includes cost cap view when parent cost cap is provided", () => {
@@ -24,8 +25,9 @@ describe("buildSubAgentMiddleware", () => {
 
     const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack[3].name).toBe("CostCapSubAgentView");
+    expect(stack[4].name).toBe("ErrorHintsMiddleware");
   });
 
   it("sub-agent cost cap view shares parent state", () => {
@@ -75,8 +77,8 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate
-    expect(stack).toHaveLength(4);
+    // loop, budget, truncation, approval gate, error hints
+    expect(stack).toHaveLength(5);
     expect(stack[3].name).toBe("ApprovalGateMiddleware");
     expect(stack[3].wrapToolCall).toBeDefined();
   });
@@ -84,7 +86,7 @@ describe("buildSubAgentMiddleware", () => {
   it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
     const stack = buildSubAgentMiddleware({ approvalGate: null });
 
-    expect(stack).toHaveLength(3);
+    expect(stack).toHaveLength(4);
     expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
   });
 
@@ -102,10 +104,13 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, cost cap view
-    expect(stack).toHaveLength(5);
+    // loop, budget, truncation, approval gate, cost cap view, error hints.
+    // Hints AFTER the gate matches the parent nesting: the gate's HITL
+    // interrupt stays outside the hints' try/catch (issue #255).
+    expect(stack).toHaveLength(6);
     expect(stack[3].name).toBe("ApprovalGateMiddleware");
     expect(stack[4].name).toBe("CostCapSubAgentView");
+    expect(stack[5].name).toBe("ErrorHintsMiddleware");
   });
 
   // captureIgnored is the structural coupling that makes sub-agent gitignored