@stigmer/runner 3.10.0 → 3.11.0

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

@@ -12,14 +12,22 @@
  * 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.
+ *
+ * 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
+ * (shared/attachment-naming.ts) and the rename is disclosed in the prompt's
+ * Input Files section. Only two attachments EXPLICITLY pinning the same
+ * `mountPath` still abort — that is a user contradiction no rename can
+ * honestly resolve.
  */
 
 import { readFile } from "node:fs/promises";
 import { createInflateRaw } from "node:zlib";
-import { basename, posix } from "node:path";
+import { posix } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import type {
   VisionBudget,
   VisionDegradedReason,
@@ -38,9 +46,17 @@ export { MAX_ZIP_FILES, MAX_ZIP_EXTRACTED_SIZE };
 // ── Types ────────────────────────────────────────────────────────────
 
 export interface InjectedFile {
+  /** The final on-disk basename — after any duplicate rename, so it always
+   * agrees with {@link path} and with the vision payload's image label. */
   readonly filename: string;
   readonly path: string;
   readonly sizeBytes: number;
+  /**
+   * The attachment's original filename, present only when a duplicate name
+   * was renamed (shared/attachment-naming.ts) — rendered as disclosure in
+   * the prompt's Input Files section.
+   */
+  readonly renamedFrom?: string;
   /** Present when the attachment was accepted into the turn's vision payload. */
   readonly vision?: VisionImage;
   /**
@@ -257,7 +273,9 @@ export function validateZipForExtraction(
 /**
  * Download, validate, and inject all attachments into the workspace.
  *
- * Performs mount path collision detection before any downloads begin.
+ * Resolves all mount paths before any downloads begin: duplicate
+ * default-derived names are renamed (never fatal — see module doc), and an
+ * explicit-mountPath contradiction throws before any bytes move.
  * On any failure, throws AttachmentInjectionError with an actionable message.
  */
 export async function injectAttachments(opts: InjectAttachmentsOptions): Promise<InjectedFile[]> {
@@ -273,17 +291,24 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
 
   for (const attachment of attachments) {
     const content = await downloadAttachment(attachment, storage, isLocalMode);
-    const mountPath = mountPaths.get(attachment)!;
+    const { path: mountPath, renamedFrom } = mountPaths.get(attachment)!;
 
     if (attachment.extract) {
       const entries = validateZipForExtraction(content, attachment.filename);
       const extracted = await extractZipToWorkspace(
         content, entries, mountPath, backend,
       );
+      // A renamed mount DIR is visible through every extracted path; the
+      // entries themselves were not renamed, so they carry no renamedFrom
+      // (per-file disclosure would misattribute the rename).
       injectedFiles.push(...extracted);
     } else {
       await backend.writeFileBuffer(mountPath, content);
-      const filename = attachment.filename || basename(mountPath);
+      // The final basename is the canonical filename: after a duplicate
+      // rename the original attachment.filename no longer names the file on
+      // disk, and the vision label must match what the prompt lists or the
+      // agent sees two images with one indistinguishable name.
+      const filename = posix.basename(mountPath);
       // The bytes are already in hand for the workspace write — offer them to
       // the vision budget before they go out of scope (the sniff decides
       // eligibility; the budget owns every size/count rule).
@@ -292,6 +317,7 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
         filename,
         path: mountPath,
         sizeBytes: content.length,
+        ...(renamedFrom !== undefined ? { renamedFrom } : {}),
         ...(vision?.kind === "accepted" ? { vision: vision.image } : {}),
         ...(vision?.kind === "degraded" ? { visionDegraded: vision.reason } : {}),
       });
@@ -307,14 +333,24 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
 
 // ── Internal Helpers ─────────────────────────────────────────────────
 
+interface ResolvedMountPath {
+  readonly path: string;
+  /** Present when a default-derived name was uniquified (issue #364). */
+  readonly renamedFrom?: string;
+}
+
 function resolveMountPaths(
   attachments: readonly Attachment[],
-): Map<Attachment, string> {
-  const result = new Map<Attachment, string>();
+): Map<Attachment, ResolvedMountPath> {
+  const result = new Map<Attachment, ResolvedMountPath>();
   const pathToAttachment = new Map<string, Attachment>();
 
+  // Pass 1: explicit mount paths claim their exact targets first. Two
+  // attachments explicitly pinning the SAME path is a user contradiction no
+  // rename can honestly resolve — keep rejecting with the actionable message.
   for (const attachment of attachments) {
-    const mountPath = resolveMountPath(attachment);
+    if (!attachment.mountPath) continue;
+    const mountPath = resolveExplicitMountPath(attachment);
     const existing = pathToAttachment.get(mountPath);
 
     if (existing) {
@@ -326,35 +362,63 @@ function resolveMountPaths(
     }
 
     pathToAttachment.set(mountPath, attachment);
-    result.set(attachment, mountPath);
+    result.set(attachment, { path: mountPath });
+  }
+
+  // Pass 2: default-derived names (`.stigmer/inputs/{filename}`) uniquify
+  // around everything already taken — other defaults AND explicit paths that
+  // landed inside the inputs prefix — instead of failing the execution
+  // (issue #364). The taken-set is seeded with the basenames the explicit
+  // pass claimed directly under the prefix.
+  const takenNames = new Set<string>();
+  for (const path of pathToAttachment.keys()) {
+    if (path.startsWith(`${DEFAULT_INPUTS_PREFIX}/`)) {
+      const rest = path.slice(DEFAULT_INPUTS_PREFIX.length + 1);
+      if (rest.length > 0 && !rest.includes("/")) takenNames.add(rest);
+    }
+  }
+  for (const attachment of attachments) {
+    if (attachment.mountPath) continue;
+    const { name, renamedFrom } = allocateUniqueName(
+      deriveDefaultFilename(attachment),
+      takenNames,
+    );
+    const path = `${DEFAULT_INPUTS_PREFIX}/${name}`;
+    pathToAttachment.set(path, attachment);
+    result.set(
+      attachment,
+      renamedFrom !== undefined ? { path, renamedFrom } : { path },
+    );
   }
 
   return result;
 }
 
-function resolveMountPath(attachment: Attachment): string {
-  if (attachment.mountPath) {
-    const cleaned = attachment.mountPath.replace(/^\/+/, "");
-    if (cleaned.length === 0) {
-      throw new AttachmentInjectionError(
-        attachment.filename,
-        "mountPath resolves to an empty path after removing leading slashes",
-      );
-    }
-    // A caller-supplied mount path is untrusted. Stripping leading slashes does
-    // not stop `..` segments from climbing out of the workspace root on the
-    // non-`.stigmer/` branch (the `.stigmer/`-routed branch is already guarded
-    // by LocalWorkspaceBackend.resolvePath). Reject any path that normalizes to
-    // an escape before it reaches the backend write.
-    if (escapesRoot(cleaned)) {
-      throw new AttachmentInjectionError(
-        attachment.filename,
-        `mount path '${attachment.mountPath}' escapes the workspace root`,
-      );
-    }
-    return cleaned;
+function resolveExplicitMountPath(attachment: Attachment): string {
+  const cleaned = attachment.mountPath.replace(/^\/+/, "");
+  if (cleaned.length === 0) {
+    throw new AttachmentInjectionError(
+      attachment.filename,
+      "mountPath resolves to an empty path after removing leading slashes",
+    );
   }
+  // A caller-supplied mount path is untrusted. Stripping leading slashes does
+  // not stop `..` segments from climbing out of the workspace root on the
+  // non-`.stigmer/` branch (the `.stigmer/`-routed branch is already guarded
+  // by LocalWorkspaceBackend.resolvePath). Reject any path that normalizes to
+  // an escape before it reaches the backend write.
+  if (escapesRoot(cleaned)) {
+    throw new AttachmentInjectionError(
+      attachment.filename,
+      `mount path '${attachment.mountPath}' escapes the workspace root`,
+    );
+  }
+  return cleaned;
+}
 
+// Derives the single-component filename an attachment without an explicit
+// mountPath materializes under (the name that pass 2 uniquifies).
+function deriveDefaultFilename(attachment: Attachment): string {
   const rawName = attachment.filename || deriveFilename(attachment.storageKey);
   if (!rawName) {
     throw new AttachmentInjectionError(
@@ -373,7 +437,7 @@ function resolveMountPath(attachment: Attachment): string {
     );
   }
 
-  return `${DEFAULT_INPUTS_PREFIX}/${filename}`;
+  return filename;
 }
 
 // escapesRoot reports whether a workspace-relative mount path would climb out

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

@@ -30,7 +30,9 @@ export async function resolveEnvironment(
 ): Promise<EnvironmentResult> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this execution's session, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would resolve redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     agentExecutionId: executionId,
   });

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

@@ -32,6 +32,7 @@ import {
 } from "../../shared/workspace/stigmer-link.js";
 import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
+import { formatDatastoreDegradationNotice } from "../../shared/datastore-attachment.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import {
   POLICY_ENGINE_VERSION,
@@ -151,6 +152,25 @@ export function createDeepAgentActivities(config: Config) {
         const initialStatus = shouldSeedFromPersistedTranscript(setup.execution)
           ? seedStatusFromExecution(setup.execution)
           : create(AgentExecutionStatusSchema, {});
+
+        // Datastore degradation disclosure, operator half (issue #325): the
+        // prompt already tells the agent to disclose the outage; this makes
+        // it visible on the execution record without reading a transcript.
+        // Appended to initialStatus BEFORE streaming (not via a status
+        // builder): both the v2 and v3 stream paths construct their own
+        // builder around this same proto and only ever append messages, so
+        // this row survives whichever path runs and rides every persist.
+        if (setup.datastoreToolsMissing.length > 0) {
+          initialStatus.messages.push(create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_SYSTEM,
+            content: formatDatastoreDegradationNotice(
+              setup.agent.spec?.datastoreUsages?.length ?? 0,
+              setup.datastoreToolsMissing,
+            ),
+            timestamp: utcTimestamp(),
+          }));
+        }
+
         const statusBuilder = new StatusBuilder(executionId, initialStatus);
 
         statusBuilder.setApprovalProvider({

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

@@ -26,6 +26,7 @@ import {
   buildImplementPlanDirective,
   findApprovedPlanPath,
 } from "../../shared/implement-plan-prompt.js";
+import type { InjectedFile } from "./attachment-injector.js";
 
 const RESPONSE_RULES = `
 
@@ -99,8 +100,11 @@ export interface PromptBuilderInput {
   containerRoot: string;
   skillsPromptSection: string;
   /**
-   * The `<available_datastores>` section (shared/datastore-attachment.ts
-   * formatDatastoresSection); empty when the agent uses no datastores.
+   * The datastores section (shared/datastore-attachment.ts
+   * formatDatastoresSection): `<available_datastores>` when the connected
+   * record-tool roster is complete, `<unavailable_datastores>` when setup's
+   * reconciliation found record tools missing (issue #325). Empty when the
+   * agent uses no datastores.
    */
   datastoresPromptSection?: string;
   /**
@@ -162,11 +166,10 @@ export interface PromptBuilderInput {
   sessionContext?: string;
 }
 
-export interface InjectedFile {
-  filename: string;
-  path: string;
-  size?: number | null;
-}
+// The prompt renders the injector's own result type — a local structural twin
+// once lived here and silently dropped the size field (`size` vs `sizeBytes`),
+// so the "(N bytes)" annotation never rendered. One type, one truth.
+export type { InjectedFile } from "./attachment-injector.js";
 
 /**
  * Which images ride the user message inline (in send order) and which
@@ -396,7 +399,7 @@ function buildReferencedFilesSection(
 }
 
 function buildInjectedFilesSection(
-  files: InjectedFile[],
+  files: readonly InjectedFile[],
   vision?: VisionPromptInfo,
 ): string {
   let section = "\n\n## Input Files\n\n";
@@ -410,8 +413,15 @@ function buildInjectedFilesSection(
     "Do NOT modify or delete these files.\n\n";
 
   for (const f of files) {
-    const sizeInfo = f.size != null ? ` (${f.size} bytes)` : "";
-    section += `- \`${f.path}\`${sizeInfo}\n`;
+    const sizeInfo = ` (${f.sizeBytes} bytes)`;
+    // A duplicate-renamed file (attachment-naming.ts) discloses its original
+    // name so the agent can connect "the two report.pdfs" in the user's
+    // message to distinct files on disk.
+    const renameInfo =
+      f.renamedFrom !== undefined
+        ? ` (renamed from duplicate '${f.renamedFrom}')`
+        : "";
+    section += `- \`${f.path}\`${sizeInfo}${renameInfo}\n`;
   }
 
   // The vision lines (shared wording, attachment-vision.ts) tell the model

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

@@ -8,7 +8,7 @@
  * the streaming phase needs.
  */
 
-import { createDeepAgent, type FilesystemPermission } from "deepagents";
+import { createDeepAgent } from "deepagents";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
 import { z } from "zod";
@@ -33,11 +33,13 @@ import {
 } from "../../shared/caller-identity.js";
 import { readSessionContext } from "../../shared/session-context.js";
 import { connectMcpServers, type McpConnectionResult } from "../../shared/mcp-manager.js";
-import { resolveMcpServers } from "../../shared/mcp-resolver.js";
+import { mergeMcpServerUsages, resolveMcpServers } from "../../shared/mcp-resolver.js";
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
 import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
 import {
+  DATASTORE_ATTACHMENT_SLUG,
   formatDatastoresSection,
+  missingRecordTools,
   synthesizeDatastoreAttachment,
 } from "../../shared/datastore-attachment.js";
 import {
@@ -56,6 +58,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 { CasCaptureObserver } from "./cas-capture-observer.js";
 import { isGitWorkTree, isPathCapturable } from "../../shared/filereview/git-substrate.js";
 import { deriveCaptureMode } from "../../shared/filereview/capture.js";
@@ -126,6 +129,16 @@ export interface SetupResult {
   readonly session: Session;
   readonly workspaceBackend: WorkspaceBackend;
   readonly mcpConnection: McpConnectionResult | null;
+  /**
+   * Record tools declared via datastore_usages but absent from the connected
+   * stigmer-records roster this turn (issue #325). Empty = healthy (also when
+   * the agent uses no datastores). Non-empty selects the degraded prompt
+   * section in Step 8, and the activity surfaces it to operators as a
+   * MESSAGE_SYSTEM row — the vision-facts pattern: setup computes the honest
+   * struct, the caller discloses. Recomputed every turn, so a healed outage
+   * stops disclosing on the next turn.
+   */
+  readonly datastoreToolsMissing: readonly string[];
   readonly mergedEnvVars: Record<string, string>;
   readonly secretKeys: ReadonlySet<string>;
   readonly modelName: string;
@@ -348,20 +361,36 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         : async () => true,
     });
 
-    // Step 7: Resolve and connect MCP servers
-    const mcpServerUsages = [
-      ...(agent.spec!.mcpServerUsages || []),
-      ...(session.spec!.mcpServerUsages || []),
-    ];
+    // Step 7: Resolve and connect MCP servers. Session-wins-per-slug merge
+    // (the Cursor harness's blueprint semantics, shared so a duplicate slug
+    // resolves identically in both harnesses — one usage per server, whose
+    // enabled_tools is the one the connect-time filter honors).
+    const mcpServerUsages = mergeMcpServerUsages(
+      agent.spec!.mcpServerUsages || [],
+      session.spec!.mcpServerUsages || [],
+    );
     const datastoreUsages = agent.spec!.datastoreUsages || [];
 
     // The synthesized attachments' credential story (DD-006 D4): the
     // exchanged token authenticates the discovery reads per-call (the
     // messaging reach refuses a desktop runner's ambient embedded_runner
     // credential; undefined lets the ambient credential apply). The
-    // attachment header falls back to the ambient credential.
-    const exchangedRunnerToken =
-      await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    // attachment header falls back to the ambient credential. Unlike the
+    // env read (which hard-fails on a broken exchange — secrets are
+    // load-bearing there), this exchange is opportunistic: every consumer
+    // below degrades to an empty answer by contract, and the server
+    // refuses the ambient fallback safely, so a failed exchange must not
+    // kill the run.
+    let exchangedRunnerToken: string | undefined;
+    try {
+      exchangedRunnerToken =
+        await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    } catch (err) {
+      console.warn(
+        "[execute-deep-agent] Scoped-token exchange failed for attachment/discovery " +
+        `reads; degrading to the ambient credential: ${err instanceof Error ? err.message : err}`,
+      );
+    }
     const attachmentCredential = exchangedRunnerToken
       ?? config.stigmerTokenRef?.current
       ?? config.stigmerToken;
@@ -556,6 +585,28 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     }
     timing.mark("inject_attachments");
 
+    // Reconcile the declared datastores against the record tools actually
+    // connected (issue #325): the records roster always serves all five
+    // tools, so any absence means the store is degraded, and the prompt
+    // must say so instead of promising tools the agent does not have. The
+    // connected roster is post-connect truth — when usages exist, MCP
+    // connect always ran above (a thrown connect already failed the run).
+    const datastoreToolsMissing = datastoreUsages.length > 0 && mcpConnection
+      ? missingRecordTools(
+          (mcpConnection.serverToolMap[DATASTORE_ATTACHMENT_SLUG] ?? [])
+            .map((t) => t.name),
+        )
+      : [];
+    if (datastoreToolsMissing.length > 0) {
+      console.warn(
+        `[setup] Datastore record tools degraded: declared ` +
+        `${datastoreUsages.length} datastore usage(s) but the ` +
+        `'${DATASTORE_ATTACHMENT_SLUG}' roster is missing ` +
+        `[${datastoreToolsMissing.join(", ")}] — the prompt discloses the ` +
+        `outage instead of the available-datastores section.`,
+      );
+    }
+
     // Step 8: Build enhanced system prompt
     const systemPrompt = buildEnhancedSystemPrompt({
       instructions,
@@ -563,7 +614,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       containerRoot: workspaceBackend.rootDir,
       skillsPromptSection,
       datastoresPromptSection: datastoreUsages.length > 0
-        ? formatDatastoresSection(datastoreUsages)
+        ? formatDatastoresSection(datastoreUsages, datastoreToolsMissing)
         : undefined,
       // "" (nothing sendable) threads as undefined: the tool alone still
       // serves text sends inside a 24-hour window (DD-006 D6).
@@ -584,8 +635,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // Step 9: Construct the LLM model. Resolution to the provider API id
     // happens inside buildChatModel; modelName stays the registry id for
     // pricing, the native-thinking heuristic, and sub-agent inheritance.
-    const requestTimeoutMs =
-      parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "0") || undefined;
+    // Operator input: only a positive integer means "bound the request" —
+    // unset, non-numeric, zero, and negative all normalize to no bound.
+    const parsedTimeoutMs =
+      Number.parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "", 10);
+    const requestTimeoutMs = parsedTimeoutMs > 0 ? parsedTimeoutMs : undefined;
     const { model } = await buildChatModel({
       modelName,
       proxyEndpoint: config.proxyEndpoint ?? undefined,
@@ -621,12 +675,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // gate. Both flow into sub-agents via the shared config below.
     const leases = deriveActiveLeases(execution);
     const globalBypass = leases.global;
-    const agentOverrides = agent.spec!.mcpServerUsages?.flatMap(
-      u => u.toolApprovalOverrides ?? [],
-    ) ?? [];
+    // Layer-3 overrides ride each resolved server from its (session-wins
+    // merged) usage — see ResolvedMcpServer.toolApprovalOverrides (issue
+    // #349) — so there is no separate override input to pass here.
     const approvalPolicies = mergeApprovalPolicies(
       resolvedMcpServers?.resolvedServers ?? [],
-      agentOverrides,
       leases,
     );
 
@@ -767,6 +820,10 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         // Presence of shellEnv is the shell-capability switch for sub-agent
         // backends too (undefined in plan mode; see buildShellEnv above).
         shellEnv,
+        // Plan mode's deny-all-writes rule, mirrored onto every sub-agent graph
+        // (issue #255) — pre-built CompiledSubAgents never inherit the parent's
+        // permissions, so read-only-by-construction must be baked in here.
+        ...(isPlanMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
       });
       timing.mark("compile_subagents");
     }
@@ -780,16 +837,6 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       responseFormat = jsonSchemaToZod(outputSchema as unknown as Record<string, unknown>);
     }
 
-    // Plan mode is read-only. Deny every filesystem write operation at the tool
-    // level so write_file/edit_file/etc. cannot mutate the workspace — enforcing
-    // the InteractionMode.PLAN contract by construction, not by prompt. Rules are
-    // first-match-wins with a permissive default, so a single deny-all-writes
-    // rule is sufficient. (The Cursor harness enforces plan mode via its prompt
-    // prefix; the native harness enforces it here.)
-    const planModePermissions: FilesystemPermission[] = [
-      { operations: ["write"], paths: ["/**"], mode: "deny" },
-    ];
-
     // File capture point. Apply-then-review is universal (Slice 2b), so the
     // CAS-observing backend: git-tracked edits flow to disk (the turn-boundary
     // git diff is authoritative), and the shared CAS observer records the pre-turn
@@ -810,7 +857,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       middleware: middleware as any,
       subagents: compiledSubagents ?? undefined,
       ...(responseFormat ? { responseFormat } : {}),
-      ...(isPlanMode ? { permissions: planModePermissions } : {}),
+      ...(isPlanMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
     } as Parameters<typeof createDeepAgent>[0]);
 
     // Step 11: Prepare invocation input and config. The conversation catchup
@@ -881,6 +928,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       session,
       workspaceBackend,
       mcpConnection,
+      datastoreToolsMissing,
       mergedEnvVars: envResult.mergedEnvVars,
       secretKeys: envResult.secretKeys,
       modelName,

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

@@ -15,12 +15,15 @@
  *   no approval gate — see deepagents-profiles.ts for the suppression half)
  * - Sub-agent backends are shell-capable outside plan mode (issue #248), mirroring
  *   the parent's backend selection in setup.ts
+ * - Sub-agent graphs carry the parent's filesystem permissions explicitly
+ *   (issue #255): pre-built CompiledSubAgents never inherit them, so plan
+ *   mode's deny-all-writes rule is baked into each graph at compile time
  * - Invalid configurations are logged and skipped (graceful degradation)
  * - Empty subagent list returns null (no subagents configured)
  */
 
 import { createDeepAgent, FilesystemBackend, LocalShellBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT } from "deepagents";
-import type { CompiledSubAgent } from "deepagents";
+import type { 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";
@@ -180,6 +183,18 @@ export interface SubagentTransformOptions {
    * backends, exactly like the parent's backend selection.
    */
   readonly shellEnv?: Record<string, string>;
+  /**
+   * Filesystem permission rules baked into each compiled sub-agent graph,
+   * inherited from the parent's rules in setup.ts (plan mode's deny-all-writes
+   * today). Required because deepagents' parent-permission inheritance covers
+   * only spec-style sub-agents — pre-built CompiledSubAgents bypass it, so
+   * without this a plan-mode sub-agent could still write (issue #255).
+   *
+   * Must not be combined with `shellEnv`: deepagents rejects permissions on an
+   * execution-capable backend (see the cas-capture-backend.ts header). Plan
+   * mode guarantees that by construction — it is the mode that clears shellEnv.
+   */
+  readonly permissions?: FilesystemPermission[];
 }
 
 // =========================================================================
@@ -525,6 +540,8 @@ export async function compileSubagents(
     readonly modelFactory?: (modelName: string) => Promise<BaseChatModel>;
     /** Shell env for `execute`; see {@link SubagentTransformOptions.shellEnv}. */
     readonly shellEnv?: Record<string, string>;
+    /** Per-graph filesystem rules; see {@link SubagentTransformOptions.permissions}. */
+    readonly permissions?: FilesystemPermission[];
   },
 ): Promise<CompiledSubAgent[]> {
   if (transformed.length === 0) return [];
@@ -560,6 +577,9 @@ export async function compileSubagents(
         tools: spec.tools.length > 0 ? spec.tools : undefined,
         middleware: middleware as unknown[],
         backend,
+        // Enforced inside this graph's own filesystem tools — and inherited by
+        // any spec-style sub-agent deepagents auto-injects one level deeper.
+        ...(opts.permissions ? { permissions: opts.permissions } : {}),
       } as Parameters<typeof createDeepAgent>[0]);
 
       const gatedRunnable = gate.wrapRunnable(
@@ -623,6 +643,7 @@ export async function transformAndCompileSubagents(
     costCap,
     modelFactory,
     shellEnv,
+    permissions,
   } = options;
 
   if (subAgents.length === 0 && !workspaceBackend.rootDir) {
@@ -743,6 +764,7 @@ export async function transformAndCompileSubagents(
     casObserver,
     modelFactory,
     shellEnv,
+    permissions,
   });
 
   if (compiled.length === 0) {

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

@@ -9,11 +9,16 @@
  *   bypassed) — installed only when the parent itself is gated
  *   (`approvalGate` present; absent under auto-approve-all)
  * - Shared cost cap view (parent's budget, no reset on sub-agent start)
+ * - Error hints (issue #255): a thrown tool error becomes a recoverable
+ *   ToolMessage exactly as on the parent. Without it, any tool throw — a
+ *   plan-mode permission denial, an MCP hiccup — propagated out of the
+ *   sub-agent graph and killed the whole delegated task, losing all its
+ *   accumulated work, where the parent's identical error is one failed
+ *   tool round the model adapts to.
  *
  * The sub-agent middleware stack does NOT include:
  * - Graceful stop (parent handles STOP signal propagation)
  * - OTel spans (parent's OTel context propagates automatically)
- * - Error hints (applied at tool level, not sub-agent level)
  *
  * Approval-gate note: the gate is what *creates* the LangGraph `interrupt()`.
  * A sub-agent's interrupt does surface at the parent checkpoint and resumes
@@ -31,6 +36,7 @@ import {
   createApprovalGateMiddleware,
   type ApprovalGateConfig,
 } from "../../middleware/approval-gate.js";
+import { createErrorHintsMiddleware } from "../../middleware/error-hints.js";
 
 const SUB_AGENT_ADVISORY_INTERVAL = 30;
 const SUB_AGENT_MAX_ADVISORIES = 4;
@@ -60,9 +66,11 @@ export interface SubAgentMiddlewareOptions {
  *
  * Returns an ordered array mirroring the parent composition:
  * loop detection → execution budget (periodic) → tool truncation →
- * [approval gate] → cost cap view. The gate sits before the cost-cap view so an
- * approval pause happens before budget accounting, matching the parent order
- * (…→ truncation → graceful-stop → approval gate → cost cap …).
+ * [approval gate] → cost cap view → error hints. 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 …),
+ * which keeps the gate's HITL interrupt outside the hints' try/catch.
  */
 export function buildSubAgentMiddleware(
   options: SubAgentMiddlewareOptions = {},
@@ -99,5 +107,7 @@ export function buildSubAgentMiddleware(
     stack.push(options.costCap.forSubAgent());
   }
 
+  stack.push(createErrorHintsMiddleware());
+
   return stack;
 }

package/src/activities/hydrate-workflow-execution.ts

@@ -267,7 +267,9 @@ async function fetchAndFlattenEnv(
 ): Promise<Record<string, unknown>> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this workflow execution, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would hydrate redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     workflowExecutionId: executionId,
   });