@stigmer/runner 3.11.0 → 3.12.0

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

@@ -1,22 +1,36 @@
 import { describe, it, expect } from "vitest";
 import { buildShellEnv, SHELL_ENV_DENYLIST } from "../shell-env.js";
+import { RUNNER_CREDENTIAL_ENV_KEYS } from "../../../shared/runner-credential-keys.js";
 
 describe("buildShellEnv", () => {
-  it("strips runner-internal credentials from the base env", () => {
-    const base = {
-      PATH: "/usr/bin",
-      HOME: "/home/runner",
-      STIGMER_RUNNER_HITL_SECRET: "secret",
-      CURSOR_API_KEY: "cursor-key",
-      STIGMER_TOKEN: "stigmer-token",
-    };
+  it("strips every runner credential from the base env", () => {
+    // Plant a value for every name in the source-of-truth list, so a key
+    // added to runner-credential-keys.ts is covered here automatically.
+    const base: NodeJS.ProcessEnv = { PATH: "/usr/bin", HOME: "/home/runner" };
+    for (const key of RUNNER_CREDENTIAL_ENV_KEYS) {
+      base[key] = `leaked-${key}`;
+    }
 
     const env = buildShellEnv({}, base);
 
     expect(env.PATH).toBe("/usr/bin");
     expect(env.HOME).toBe("/home/runner");
-    for (const key of SHELL_ENV_DENYLIST) {
-      expect(env[key]).toBeUndefined();
+    for (const key of RUNNER_CREDENTIAL_ENV_KEYS) {
+      expect(env[key], `runner credential '${key}' must not reach the shell env`).toBeUndefined();
+    }
+  });
+
+  it("denies the full credential list, not just the original three (issue #385)", () => {
+    // Pins the five names #385 added. The parameterized test above would
+    // pass even if the list regressed to three; this one cannot.
+    for (const key of [
+      "ANTHROPIC_API_KEY",
+      "OPENAI_API_KEY",
+      "STIGMER_AUTH_TOKEN",
+      "ANTHROPIC_FOUNDRY_API_KEY",
+      "AWS_BEARER_TOKEN_BEDROCK",
+    ]) {
+      expect(SHELL_ENV_DENYLIST, `'${key}' must be in the shell denylist`).toContain(key);
     }
   });
 

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

@@ -83,12 +83,10 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
     // 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.
+    // Absolute workspace paths — the canonical shape after enforcement
+    // canonicalization, and what the single-workspace prompt's prose (the
+    // absolute rootDir) steers models toward. The workspace-relative shape
+    // is pinned separately below (issue #429).
     const script: ScriptSelector = () => ({
       toolCalls: [
         { name: "write_file", args: { file_path: join(root, "dist/out.txt"), content: "new file" }, id: "c_write" },
@@ -143,19 +141,20 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
     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.
+  it("relative-path writes are refused by the RULES, and relative reads flow (issue #429)", async () => {
+    // The multi-workspace prompt mandates workspace-relative paths, and
+    // models routinely choose them in single-workspace sessions too. Before
+    // the #429 fix, deepagents' permission canonicalization refused the
+    // shape outright — every relative call, reads included, died with
+    // "path must be absolute" before any rule ran. compileSubagents now
+    // derives a path-normalization shim from the same `permissions` it
+    // bakes into the graph, so the relative shape reaches the rules in
+    // canonical form: writes get the honest plan-mode denial, reads just
+    // work. Read-only-by-construction (issue #255) holds throughout.
     const script: ScriptSelector = () => ({
       toolCalls: [
         { name: "write_file", args: { file_path: "dist/out.txt", content: "new file" }, id: "c_write_rel" },
+        { name: "read_file", args: { file_path: "notes.md" }, id: "c_read_rel" },
       ],
       done: "worker done",
     });
@@ -166,8 +165,14 @@ describe("plan-mode sub-agent filesystem permissions (issue #255)", () => {
       { configurable: { thread_id: "t3" }, recursionLimit: 50 },
     )) as { messages: BaseMessage[] };
 
-    expect(toolResultById(result.messages, "c_write_rel")).toMatch(/path must be absolute/i);
+    const writeResult = toolResultById(result.messages, "c_write_rel");
+    expect(writeResult).toMatch(/permission denied for write/i);
+    expect(writeResult).not.toMatch(/path must be absolute/i);
     await expect(access(join(root, "dist/out.txt"))).rejects.toThrow();
     expect(observer.before.size).toBe(0);
+
+    const readResult = toolResultById(result.messages, "c_read_rel");
+    expect(readResult).toContain("PLAN_MODE_README_TOKEN");
+    expect(readResult).not.toMatch(/path must be absolute/i);
   });
 });

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

@@ -27,6 +27,7 @@ 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 { mintAttachmentDownloadUrl } from "../../shared/attachment-download-urls.js";
 import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import type {
   VisionBudget,
@@ -66,6 +67,17 @@ export interface InjectedFile {
    * Attachments that were never image-shaped carry neither field.
    */
   readonly visionDegraded?: VisionDegradedReason;
+  /**
+   * A download URL for the attachment's stored object, listed in the system
+   * prompt's Input Files section so the agent can hand the file to a tool
+   * whose backend cannot read the sandbox filesystem (issue #532). Minted
+   * whenever the attachment has a `storageKey` and a usable storage; never
+   * present on extracted ZIP entries (no attachment-level object). Absent
+   * when there is nothing to mint or the mint failed (non-fatal — policy,
+   * degrade log, and prompt wording live in
+   * shared/attachment-download-urls.ts).
+   */
+  readonly downloadUrl?: string;
 }
 
 export interface InjectAttachmentsOptions {
@@ -300,7 +312,10 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
       );
       // 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).
+      // (per-file disclosure would misattribute the rename). Extracted
+      // entries also carry no downloadUrl: the stored object is the ZIP, not
+      // any listed file, and a URL to bytes that differ from the listing
+      // would be a false promise.
       injectedFiles.push(...extracted);
     } else {
       await backend.writeFileBuffer(mountPath, content);
@@ -313,6 +328,9 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
       // the vision budget before they go out of scope (the sniff decides
       // eligibility; the budget owns every size/count rule).
       const vision = visionBudget?.offer(filename, attachment.contentType, content);
+      const downloadUrl = await mintAttachmentDownloadUrl(
+        storage, attachment.storageKey, filename,
+      );
       injectedFiles.push({
         filename,
         path: mountPath,
@@ -320,6 +338,7 @@ export async function injectAttachments(opts: InjectAttachmentsOptions): Promise
         ...(renamedFrom !== undefined ? { renamedFrom } : {}),
         ...(vision?.kind === "accepted" ? { vision: vision.image } : {}),
         ...(vision?.kind === "degraded" ? { visionDegraded: vision.reason } : {}),
+        ...(downloadUrl !== undefined ? { downloadUrl } : {}),
       });
     }
   }

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

@@ -32,7 +32,6 @@ 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,
@@ -153,24 +152,6 @@ export function createDeepAgentActivities(config: Config) {
           ? 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/mcp-gate.ts

@@ -17,8 +17,6 @@
 export interface McpToolSources {
   /** Declared MCP server usages (agent spec + session spec). */
   readonly mcpServerUsageCount: number;
-  /** Declared datastore usages (the records attachment, T05). */
-  readonly datastoreUsageCount: number;
   /** Serving proactive-messaging channels (the channels attachment, DD-006). */
   readonly channelMessagingCount: number;
   /** The serving channel id when this session IS a live channel
@@ -30,7 +28,6 @@ export interface McpToolSources {
 export function shouldConnectMcp(sources: McpToolSources): boolean {
   return (
     sources.mcpServerUsageCount > 0 ||
-    sources.datastoreUsageCount > 0 ||
     sources.channelMessagingCount > 0 ||
     sources.conversationChannelId !== undefined
   );

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

@@ -21,6 +21,10 @@ import {
   visionDisclosureLines,
   type NotViewableEntry,
 } from "../../shared/attachment-vision.js";
+import {
+  downloadUrlDisclosureLine,
+  type DownloadUrlKind,
+} from "../../shared/attachment-download-urls.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -99,14 +103,6 @@ export interface PromptBuilderInput {
   provisionResults: ProvisionResult[];
   containerRoot: string;
   skillsPromptSection: string;
-  /**
-   * 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;
   /**
    * The `<available_channel_templates>` section
    * (shared/channel-attachment.ts formatChannelTemplatesSection); absent
@@ -122,6 +118,12 @@ export interface PromptBuilderInput {
    * Rendered inside the Input Files section.
    */
   vision?: VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints (issue #532) — keys
+   * the Input Files section's hand-off wording (attachment-download-urls.ts).
+   * One turn-level fact: all attachments ride the one configured storage.
+   */
+  downloadUrlKind?: DownloadUrlKind;
   /**
    * The execution's interaction mode. PLAN appends the shared plan-mode
    * directive so the model knows the turn's deliverable is a plan document.
@@ -201,10 +203,6 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
     prompt += input.skillsPromptSection;
   }
 
-  if (input.datastoresPromptSection) {
-    prompt += "\n\n" + input.datastoresPromptSection;
-  }
-
   if (input.channelTemplatesPromptSection) {
     prompt += "\n\n" + input.channelTemplatesPromptSection;
   }
@@ -220,7 +218,9 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   }
 
   if (input.injectedFiles.length > 0) {
-    prompt += buildInjectedFilesSection(input.injectedFiles, input.vision);
+    prompt += buildInjectedFilesSection(
+      input.injectedFiles, input.vision, input.downloadUrlKind,
+    );
   }
 
   if (input.senderIdentity) {
@@ -401,6 +401,7 @@ function buildReferencedFilesSection(
 function buildInjectedFilesSection(
   files: readonly InjectedFile[],
   vision?: VisionPromptInfo,
+  downloadUrlKind?: DownloadUrlKind,
 ): string {
   let section = "\n\n## Input Files\n\n";
   section +=
@@ -416,12 +417,23 @@ function buildInjectedFilesSection(
     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.
+    // message to distinct files on disk. A file with a minted download URL
+    // (attachment-download-urls.ts) lists it beside the path for the remote
+    // hand-off story.
     const renameInfo =
       f.renamedFrom !== undefined
         ? ` (renamed from duplicate '${f.renamedFrom}')`
         : "";
-    section += `- \`${f.path}\`${sizeInfo}${renameInfo}\n`;
+    const urlInfo =
+      f.downloadUrl !== undefined ? ` — download URL: ${f.downloadUrl}` : "";
+    section += `- \`${f.path}\`${sizeInfo}${renameInfo}${urlInfo}\n`;
+  }
+
+  // The URL hand-off line (shared wording, attachment-download-urls.ts)
+  // renders only when some listed file actually carries a URL — its wording
+  // keys on what kind of URL the storage backend mints.
+  if (downloadUrlKind !== undefined && files.some((f) => f.downloadUrl !== undefined)) {
+    section += "\n" + downloadUrlDisclosureLine(downloadUrlKind) + "\n";
   }
 
   // The vision lines (shared wording, attachment-vision.ts) tell the model

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

@@ -36,12 +36,6 @@ import { connectMcpServers, type McpConnectionResult } from "../../shared/mcp-ma
 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 {
   discoverChannelMessaging,
   formatChannelTemplatesSection,
@@ -129,16 +123,6 @@ 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;
@@ -369,7 +353,6 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       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
@@ -410,7 +393,6 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     let resolvedMcpServers: Awaited<ReturnType<typeof resolveMcpServers>> | null = null;
     if (shouldConnectMcp({
       mcpServerUsageCount: mcpServerUsages.length,
-      datastoreUsageCount: datastoreUsages.length,
       channelMessagingCount: channelMessaging.length,
       conversationChannelId,
     })) {
@@ -444,25 +426,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         envResult.secretKeys,
       );
 
-      // The datastore records attachment (T05) — injected AFTER resolve +
-      // backfill so the destructiveHint tightener can never gate it; empty
-      // approval maps keep it approval-free by construction (see
-      // shared/datastore-attachment.ts).
-      if (datastoreUsages.length > 0) {
-        const attachment = synthesizeDatastoreAttachment(datastoreUsages, {
-          bridgeEndpoint: config.mcpBridgeEndpoint,
-          credential: attachmentCredential,
-          backendEndpoint: config.stigmerBackendEndpoint,
-        });
-        if (attachment) {
-          backfilledServers = injectSynthesizedAttachment(
-            backfilledServers, attachment, "datastore records",
-          );
-        }
-      }
-
-      // The channel messaging attachment (DD-006 D7/D8) — the records
-      // attachment's twin, injected under the same after-backfill rule.
+      // The channel messaging attachment (DD-006 D7/D8) — injected AFTER
+      // resolve + backfill so the destructiveHint tightener can never gate
+      // it; empty approval maps keep it approval-free by construction.
       if (channelMessaging.length > 0) {
         const attachment = synthesizeChannelAttachment(channelMessaging, {
           bridgeEndpoint: config.mcpBridgeEndpoint,
@@ -477,8 +443,8 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       }
 
       // The conversation participation attachment (DD-008 D-c) — the
-      // third sibling, same after-backfill rule. HTTP-only: synthesize
-      // answers undefined with no bridge endpoint by design (see
+      // channel attachment's sibling, same after-backfill rule. HTTP-only:
+      // synthesize answers undefined with no bridge endpoint by design (see
       // shared/conversation-attachment.ts).
       const conversationAttachment = synthesizeConversationAttachment(conversationChannelId, {
         bridgeEndpoint: config.mcpBridgeEndpoint,
@@ -585,37 +551,12 @@ 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,
       provisionResults,
       containerRoot: workspaceBackend.rootDir,
       skillsPromptSection,
-      datastoresPromptSection: datastoreUsages.length > 0
-        ? formatDatastoresSection(datastoreUsages, datastoreToolsMissing)
-        : undefined,
       // "" (nothing sendable) threads as undefined: the tool alone still
       // serves text sends inside a 24-hour window (DD-006 D6).
       channelTemplatesPromptSection: channelMessaging.length > 0
@@ -625,6 +566,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       workspaceRoot: workspaceBackend.rootDir,
       injectedFiles,
       vision: visionPromptInfo,
+      downloadUrlKind: artifactStorage?.downloadUrlKind,
       interactionMode: execution.spec!.executionConfig?.interactionMode,
       buildFromPlan: execution.spec!.executionConfig?.buildFromPlan,
       contextBridge: readContextBridge(session.spec!.metadata),
@@ -635,17 +577,14 @@ 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.
-    // 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;
+    // The operator's STIGMER_LLM_REQUEST_TIMEOUT_MS bound is applied inside
+    // buildChatModel (#468) — the sub-agent modelFactory below silently
+    // dropped it when each caller parsed the env itself.
     const { model } = await buildChatModel({
       modelName,
       proxyEndpoint: config.proxyEndpoint ?? undefined,
       stigmerToken: config.stigmerToken ?? undefined,
       headerScope: { executionId },
-      timeoutMs: requestTimeoutMs,
     });
     timing.mark("build_model");
 
@@ -655,6 +594,12 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     const execConfig = execution.spec!.executionConfig;
     const isPlanMode = execConfig?.interactionMode === InteractionMode.PLAN;
     const shellEnv = isPlanMode ? undefined : buildShellEnv(envResult.mergedEnvVars);
+    // Plan mode's filesystem permission rules, hoisted once: the parent graph,
+    // every sub-agent graph, AND the path-normalization middleware (issue #429)
+    // all derive from this single value, so a rule-bearing graph can never miss
+    // the shim that keeps prompt-compliant relative paths from dying in rule
+    // validation (`path must be absolute`).
+    const planModePermissions = isPlanMode ? PLAN_MODE_PERMISSIONS : undefined;
 
     const toolServerMap = new Map<string, string>();
     if (mcpConnection) {
@@ -760,6 +705,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       } : null,
       otelSpans: { toolServerMap },
       approvalGate: approvalGateConfig,
+      pathNormalization: planModePermissions
+        ? { rootDir: workspaceBackend.rootDir }
+        : null,
     });
     timing.mark("build_middleware");
 
@@ -823,7 +771,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         // 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 } : {}),
+        // compileSubagents derives each sub-agent's path-normalization shim
+        // from this same value (issue #429).
+        ...(planModePermissions ? { permissions: planModePermissions } : {}),
       });
       timing.mark("compile_subagents");
     }
@@ -857,7 +807,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       middleware: middleware as any,
       subagents: compiledSubagents ?? undefined,
       ...(responseFormat ? { responseFormat } : {}),
-      ...(isPlanMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
+      ...(planModePermissions ? { permissions: planModePermissions } : {}),
     } as Parameters<typeof createDeepAgent>[0]);
 
     // Step 11: Prepare invocation input and config. The conversation catchup
@@ -928,7 +878,6 @@ 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/shell-env.ts

@@ -6,15 +6,14 @@
  * never once at process start.
  */
 
-/** Runner-internal keys that must never reach agent shell commands. */
-export const SHELL_ENV_DENYLIST: readonly string[] = [
-  // Derives HITL approval fingerprints — an agent that reads this could forge receipts.
-  "STIGMER_RUNNER_HITL_SECRET",
-  // Cursor harness credential; shell commands do not need direct Cursor API access.
-  "CURSOR_API_KEY",
-  // Stigmer control-plane auth; shell commands use ExecutionContext overlay instead.
-  "STIGMER_TOKEN",
-];
+import { RUNNER_CREDENTIAL_ENV_KEYS } from "../../shared/runner-credential-keys.js";
+
+/**
+ * Runner-internal keys that must never reach agent shell commands: every
+ * credential the runner holds for its own outbound calls (issue #385). The
+ * names — and the rule for adding one — live in runner-credential-keys.ts.
+ */
+export const SHELL_ENV_DENYLIST: readonly string[] = RUNNER_CREDENTIAL_ENV_KEYS;
 
 /**
  * Build the environment map passed to deepagents' LocalShellBackend.

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

@@ -554,11 +554,17 @@ export async function compileSubagents(
       // Structural coupling (DD-19): a sub-agent gate flows gitignored writes into
       // CAS iff a CAS observer backs that sub-agent's filesystem backend. Deriving
       // both from the same `casObserver` makes "unobserved unreviewable bytes"
-      // impossible by construction.
+      // impossible by construction. Same idiom for path normalization
+      // (issue #429): derived from the same `permissions` baked into the graph
+      // below, so a rule-bearing graph always carries the shim that keeps
+      // prompt-compliant relative paths from dying in rule validation.
       const middleware = buildSubAgentMiddleware({
         costCap: opts.costCap,
         approvalGate: opts.approvalGate,
         captureIgnored: !!opts.casObserver,
+        ...(opts.permissions?.length
+          ? { pathNormalization: { rootDir: opts.workspaceRootDir } }
+          : {}),
       });
 
       const modelName = spec.model ?? opts.parentModelName;

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

@@ -2,6 +2,12 @@
  * 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.
  * - Fresh loop detection (independent cycle tracking)
  * - Fresh tool truncation (same limits as parent)
  * - Periodic execution budget (interval=30, max=4 advisories)
@@ -27,8 +33,13 @@
  * the live HITL bypass this wiring closes.
  */
 
-import type { StigmerMiddleware, ToolTruncationConfig } from "../../middleware/types.js";
+import type {
+  StigmerMiddleware,
+  ToolTruncationConfig,
+  PathNormalizationConfig,
+} from "../../middleware/types.js";
 import type { CostCapMiddleware } from "../../middleware/index.js";
+import { createPathNormalizationMiddleware } from "../../middleware/path-normalization.js";
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
 import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
@@ -59,14 +70,22 @@ export interface SubAgentMiddlewareOptions {
    * unobserved backend would apply unreviewable bytes.
    */
   readonly captureIgnored?: boolean;
+  /**
+   * Workspace-relative path normalization (issue #429). Present iff this
+   * sub-agent's graph carries filesystem permission rules — the caller
+   * derives it from the same `permissions` value it bakes into the graph.
+   */
+  readonly pathNormalization?: PathNormalizationConfig;
 }
 
 /**
  * Build the middleware stack for a single sub-agent.
  *
  * Returns an ordered array mirroring the parent composition:
- * loop detection → execution budget (periodic) → tool truncation →
- * [approval gate] → cost cap view → error hints. The gate sits before the
+ * [path normalization] → loop detection → execution budget (periodic) →
+ * tool truncation → [approval gate] → cost cap view → error hints.
+ * Normalization is outermost so everything downstream observes canonical
+ * 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 …),
@@ -77,6 +96,10 @@ export function buildSubAgentMiddleware(
 ): StigmerMiddleware[] {
   const stack: StigmerMiddleware[] = [];
 
+  if (options.pathNormalization) {
+    stack.push(createPathNormalizationMiddleware(options.pathNormalization));
+  }
+
   stack.push(createLoopDetectionMiddleware({ enabled: true }));
 
   stack.push(createExecutionBudgetMiddleware({

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

@@ -265,11 +265,14 @@ async function fetchAndFlattenEnv(
   client: StigmerClient,
   executionId: string,
 ): 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. A failed exchange throws and
-  // fails the activity: the bootstrap credential no longer decrypts
-  // (stigmer-cloud#218), so proceeding would hydrate redacted placeholders.
+  // The runner acquires a token scoped to this workflow execution so the
+  // server's decrypt gate binds the read: a desktop runner exchanges its
+  // bootstrap credential (#156, hard error on failure — the bootstrap
+  // credential no longer decrypts since stigmer-cloud#218, so proceeding
+  // would hydrate redacted placeholders), and an OSS runner asks the
+  // credential-less best-effort exchange (oss#535 — the OSS server redacts
+  // EC reads by default and mints execution-scoped tokens). No-op for cloud
+  // sandbox runners, whose ambient credential is already scoped.
   const scopedToken = await client.acquireScopedRunnerToken({
     workflowExecutionId: executionId,
   });