@stigmer/runner 3.1.12 → 3.1.14

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

@@ -0,0 +1,291 @@
+/**
+ * Shell `execute` tool approval gating and general-purpose sub-agent gating.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { HumanMessage } from "@langchain/core/messages";
+import { Command, MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent } from "deepagents";
+import { createApprovalGateMiddleware } from "../../../middleware/approval-gate.js";
+import { createCasCaptureBackend } from "../cas-capture-backend.js";
+import { CasCaptureObserver } from "../cas-capture-observer.js";
+import {
+  registerStigmerDeepagentsProfiles,
+  resetStigmerDeepagentsProfilesForTests,
+} from "../deepagents-profiles.js";
+import {
+  ScriptedModel,
+  readPendingInterrupts,
+  type ScriptSelector,
+} from "../__test-utils__/scripted-model.js";
+import { compileSubagents, type TransformedSubagent } from "../subagent-transformer.js";
+
+describe("native harness shell execute approval", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "shell-gate-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("interrupts before execute runs and resumes after approval", async () => {
+    const marker = join(root, "shell-marker.txt");
+    const script: ScriptSelector = () => ({
+      toolCalls: [{
+        name: "execute",
+        args: { command: `echo ran > shell-marker.txt` },
+        id: "exec_1",
+      }],
+      done: "shell done",
+    });
+
+    const observer = new CasCaptureObserver({
+      rootDir: root,
+      isIgnored: async () => false,
+    });
+    const backend = await createCasCaptureBackend({
+      rootDir: root,
+      observer,
+      shellEnv: {},
+    });
+
+    const checkpointer = new MemorySaver();
+    const agent = await createDeepAgent({
+      model: new ScriptedModel(script),
+      checkpointer: checkpointer as never,
+      backend,
+      middleware: [
+        createApprovalGateMiddleware({ policies: new Map(), toolServerMap: new Map() }),
+      ],
+    } as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "shell-thread" }, recursionLimit: 50 };
+
+    await agent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    const pending = readPendingInterrupts(await agent.getState(config) as never);
+    expect(pending.length).toBeGreaterThanOrEqual(1);
+    expect(pending[0].toolName).toBe("execute");
+    await expect(readFile(marker, "utf8")).rejects.toThrow();
+
+    const resumeDict: Record<string, { action: string }> = {};
+    for (const p of pending) resumeDict[p.interruptId] = { action: "approve" };
+
+    await agent.invoke(new Command({ resume: resumeDict }), config);
+
+    expect(await readFile(marker, "utf8")).toBe("ran\n");
+  });
+});
+
+describe("sub-agent shell capability", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "sa-shell-cap-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * Compile a sub-agent and capture the tool names deepagents actually binds to
+   * its model — the filesystem middleware filters `execute` out of the model's
+   * tool list when the backend is not sandbox-capable, so the bound set is the
+   * authoritative observable for shell capability.
+   */
+  async function boundToolNamesFor(shellEnv: Record<string, string> | undefined) {
+    let bound: string[] = [];
+    const script: ScriptSelector = (toolNames) => {
+      if (toolNames.length > 0) bound = toolNames;
+      return { toolCalls: [], done: "ok" };
+    };
+
+    const compiled = await compileSubagents(
+      [{ name: "worker", description: "test worker", systemPrompt: "work", tools: [] }],
+      {
+        parentModelName: "claude-sonnet-4-6",
+        workspaceRootDir: root,
+        shellEnv,
+        modelFactory: async () => new ScriptedModel(script),
+      },
+    );
+    expect(compiled).toHaveLength(1);
+
+    await compiled[0].runnable.invoke(
+      { messages: [new HumanMessage({ content: "go" })] },
+      { configurable: { thread_id: "t1" }, recursionLimit: 50 },
+    );
+    return bound;
+  }
+
+  it("binds execute when shellEnv is present (non-plan mode)", async () => {
+    expect(await boundToolNamesFor({})).toContain("execute");
+  });
+
+  it("omits execute when shellEnv is absent (plan mode)", async () => {
+    expect(await boundToolNamesFor(undefined)).not.toContain("execute");
+  });
+});
+
+describe("general-purpose sub-agent gating", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "gp-gate-"));
+    registerStigmerDeepagentsProfiles();
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+    resetStigmerDeepagentsProfilesForTests();
+  });
+
+  it("gates execute inside a compiled general-purpose sub-agent", async () => {
+    const marker = join(root, "gp-shell-marker.txt");
+    // Role selection: only the SUB-AGENT is shell-capable in this test (the
+    // parent gets a non-shell backend below), so `execute` in the bound tool
+    // set uniquely identifies the sub-agent's turn.
+    const roleScript: ScriptSelector = (toolNames) =>
+      toolNames.includes("execute")
+        ? {
+            toolCalls: [{
+              name: "execute",
+              args: { command: "echo gp > gp-shell-marker.txt" },
+              id: "gp_exec_1",
+            }],
+            done: "gp done",
+          }
+        : {
+            toolCalls: [{
+              name: "task",
+              args: { description: "run shell", subagent_type: "general-purpose" },
+              id: "task_1",
+            }],
+            done: "parent done",
+          };
+
+    const gpSpec: TransformedSubagent = {
+      name: "general-purpose",
+      description: "Gated general-purpose test double",
+      systemPrompt: "Run the delegated task.",
+      tools: [],
+    };
+
+    const compiled = await compileSubagents([gpSpec], {
+      parentModelName: "claude-sonnet-4-6",
+      workspaceRootDir: root,
+      approvalGate: { policies: new Map(), toolServerMap: new Map() },
+      shellEnv: {},
+      modelFactory: async () => new ScriptedModel(roleScript),
+    });
+    expect(compiled).toHaveLength(1);
+
+    const observer = new CasCaptureObserver({
+      rootDir: root,
+      isIgnored: async () => false,
+    });
+    // Non-shell parent backend: keeps `execute` out of the parent's tool set so
+    // the role script above delegates instead of running the command itself.
+    const parentBackend = await createCasCaptureBackend({
+      rootDir: root,
+      observer,
+    });
+
+    const checkpointer = new MemorySaver();
+    const parent = await createDeepAgent({
+      model: new ScriptedModel(roleScript),
+      checkpointer: checkpointer as never,
+      backend: parentBackend,
+      subagents: compiled,
+    } as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "gp-thread" }, recursionLimit: 50 };
+    await parent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    const pending = readPendingInterrupts(await parent.getState(config) as never);
+    expect(pending.some((p) => p.toolName === "execute")).toBe(true);
+    await expect(readFile(marker, "utf8")).rejects.toThrow();
+  });
+});
+
+describe("registerStigmerDeepagentsProfiles", () => {
+  beforeEach(() => {
+    resetStigmerDeepagentsProfilesForTests();
+    registerStigmerDeepagentsProfiles();
+  });
+
+  afterEach(() => {
+    resetStigmerDeepagentsProfilesForTests();
+  });
+
+  /**
+   * deepagents resolves harness profiles from the model's provider, and for a
+   * model INSTANCE the provider comes from the class name (ChatAnthropic /
+   * ChatOpenAI — see getModelProvider in deepagents). Production models always
+   * come from buildChatModel and are one of those two classes; a bare
+   * ScriptedModel resolves NO provider, so the suppression profile would never
+   * match it. Masquerading as ChatAnthropic exercises the exact production
+   * resolution path.
+   */
+  class ScriptedAnthropicModel extends ScriptedModel {
+    static override lc_name(): string {
+      return "ChatAnthropic";
+    }
+  }
+
+  it("prevents deepagents from auto-injecting an ungated general-purpose sub-agent", async () => {
+    const root = await mkdtemp(join(tmpdir(), "gp-profile-"));
+    try {
+      const observer = new CasCaptureObserver({
+        rootDir: root,
+        isIgnored: async () => false,
+      });
+      const backend = await createCasCaptureBackend({
+        rootDir: root,
+        observer,
+        shellEnv: {},
+      });
+
+      const script: ScriptSelector = () => ({
+        toolCalls: [{
+          name: "task",
+          args: { description: "delegate", subagent_type: "general-purpose" },
+          id: "task_1",
+        }],
+        done: "done",
+      });
+
+      // No `subagents` supplied: without the profile suppression deepagents
+      // would inject its own ungated general-purpose sub-agent here.
+      const agent = await createDeepAgent({
+        model: new ScriptedAnthropicModel(script),
+        backend,
+      } as Parameters<typeof createDeepAgent>[0]);
+
+      // With the injection suppressed, the scripted `task` delegation has no
+      // general-purpose target. Depending on the runtime's tool-error handling
+      // that surfaces either as a rejected invoke or as an error ToolMessage —
+      // both prove the delegation target does not exist.
+      let outcome: string;
+      try {
+        const result = await agent.invoke(
+          { messages: [new HumanMessage({ content: "go" })] },
+          { recursionLimit: 20 },
+        ) as { messages: unknown[] };
+        outcome = JSON.stringify(result.messages);
+      } catch (err) {
+        outcome = String(err);
+      }
+      expect(outcome).toMatch(/allowed types/i);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -53,10 +53,11 @@ function mockMcpUsage(slug: string): McpServerUsage {
 // =========================================================================
 
 describe("BUILTIN_SUBAGENT_TYPES", () => {
-  it("contains explore and shell", () => {
+  it("contains explore, shell, and general-purpose", () => {
     expect(BUILTIN_SUBAGENT_TYPES.has("explore")).toBe(true);
     expect(BUILTIN_SUBAGENT_TYPES.has("shell")).toBe(true);
-    expect(BUILTIN_SUBAGENT_TYPES.size).toBe(2);
+    expect(BUILTIN_SUBAGENT_TYPES.has("general-purpose")).toBe(true);
+    expect(BUILTIN_SUBAGENT_TYPES.size).toBe(3);
   });
 });
 
@@ -70,13 +71,14 @@ describe("createBuiltinSubagents", () => {
     expect(result).toEqual([]);
   });
 
-  it("creates explore and shell subagents when workspace exists", () => {
+  it("creates explore, shell, and general-purpose subagents when workspace exists", () => {
     const result = createBuiltinSubagents(true);
-    expect(result).toHaveLength(2);
+    expect(result).toHaveLength(3);
 
     const names = result.map((r) => r.name);
     expect(names).toContain("explore");
     expect(names).toContain("shell");
+    expect(names).toContain("general-purpose");
   });
 
   it("explore has read-only prompt with strict boundaries", () => {
@@ -470,6 +472,7 @@ describe("transformAndCompileSubagents", () => {
     const names = result!.map((r) => r.name);
     expect(names).toContain("explore");
     expect(names).toContain("shell");
+    expect(names).toContain("general-purpose");
 
     logSpy.mockRestore();
   });

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

@@ -1,6 +1,5 @@
 /**
- * A capture-mode `FilesystemBackend` that observes gitignored file mutations for
- * CAS review (design docs 08/11/12; the `.gitignored` half of apply-then-review).
+ * CAS-capturing deepagents backends for the native harness.
  *
  * WHY A BACKEND WRAPPER, NOT THE APPROVAL GATE
  * --------------------------------------------
@@ -12,24 +11,24 @@
  * escape review under auto-approve-all. Observing at the backend keeps CAS
  * capture gate-independent, so it is symmetric with the git-tracked path.
  *
- * THIS CLASS IS A THIN ADAPTER
- * ----------------------------
- * All capture state and logic live in the shared {@link CasCaptureObserver} (one
- * per turn). The parent graph and every sub-agent graph are each handed a backend
- * pointing at the SAME observer, so their gitignored writes compose into one CAS
- * change set with race-free first-touch-wins (see the observer's docs). This
- * backend only forwards the mutation point to the observer before delegating to
- * the base `FilesystemBackend`.
+ * SHELL VS PLAN MODE
+ * ------------------
+ * Outside plan mode the harness uses {@link CasCaptureShellBackend} (deepagents
+ * LocalShellBackend + CAS observation) so the `execute` tool is available and
+ * approval-gated. Plan mode keeps {@link CasCaptureFilesystemBackend} because
+ * deepagents rejects filesystem `permissions` combined with an execution-capable
+ * backend — plan mode is read-only by construction, so no shell tool there.
  *
  * deepagents mutates only via `write` (create/overwrite) and `edit` (modify);
  * there is no backend delete/rename, so this observes CREATE and MODIFY. A
  * gitignored delete can only arrive via shell, which stays on the approval gate.
  *
  * @since File-Change HITL Redesign (Phase 3 — CAS deep-agent wiring); sub-agent
- * gitignored capture parity (Session 26, DD-19)
+ * gitignored capture parity (Session 26, DD-19); shell restore (issue #248)
  */
 
-import { FilesystemBackend } from "deepagents";
+import { FilesystemBackend, LocalShellBackend } from "deepagents";
+import type { LocalShellBackendOptions } from "deepagents";
 import type { CasCaptureObserver } from "./cas-capture-observer.js";
 
 export type { CasBeforeMap } from "./cas-capture-observer.js";
@@ -38,13 +37,36 @@ type FilesystemBackendOptions = NonNullable<
   ConstructorParameters<typeof FilesystemBackend>[0]
 >;
 
+type CasCaptureDeps = { readonly observer: CasCaptureObserver };
+
 export class CasCaptureFilesystemBackend extends FilesystemBackend {
   private readonly observer: CasCaptureObserver;
 
-  constructor(
-    options: FilesystemBackendOptions,
-    deps: { readonly observer: CasCaptureObserver },
+  constructor(options: FilesystemBackendOptions, deps: CasCaptureDeps) {
+    super(options);
+    this.observer = deps.observer;
+  }
+
+  override async write(filePath: string, content: string) {
+    await this.observer.recordBefore(filePath);
+    return super.write(filePath, content);
+  }
+
+  override async edit(
+    filePath: string,
+    oldString: string,
+    newString: string,
+    replaceAll?: boolean,
   ) {
+    await this.observer.recordBefore(filePath);
+    return super.edit(filePath, oldString, newString, replaceAll);
+  }
+}
+
+export class CasCaptureShellBackend extends LocalShellBackend {
+  private readonly observer: CasCaptureObserver;
+
+  constructor(options: LocalShellBackendOptions, deps: CasCaptureDeps) {
     super(options);
     this.observer = deps.observer;
   }
@@ -64,3 +86,35 @@ export class CasCaptureFilesystemBackend extends FilesystemBackend {
     return super.edit(filePath, oldString, newString, replaceAll);
   }
 }
+
+export type CasCaptureBackend = CasCaptureFilesystemBackend | CasCaptureShellBackend;
+
+export interface CreateCasCaptureBackendOptions {
+  readonly rootDir: string;
+  readonly observer: CasCaptureObserver;
+  /** When set, builds a shell-capable backend with this env for `execute`. */
+  readonly shellEnv?: Record<string, string>;
+}
+
+/**
+ * Construct the CAS-observing backend for a deepagents agent graph.
+ *
+ * Shell-capable when `shellEnv` is provided; otherwise filesystem-only (plan mode).
+ * Shell backends honor LocalShellBackend's documented initialize contract.
+ */
+export async function createCasCaptureBackend(
+  options: CreateCasCaptureBackendOptions,
+): Promise<CasCaptureBackend> {
+  const { rootDir, observer, shellEnv } = options;
+
+  if (shellEnv !== undefined) {
+    const backend = new CasCaptureShellBackend(
+      { rootDir, env: shellEnv },
+      { observer },
+    );
+    await backend.initialize();
+    return backend;
+  }
+
+  return new CasCaptureFilesystemBackend({ rootDir }, { observer });
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Stigmer-specific deepagents harness profile registrations.
+ *
+ * deepagents 1.10.x auto-injects a built-in `general-purpose` sub-agent into
+ * every `createDeepAgent()` call unless the caller supplies one with that name.
+ * The injected sub-agent carries only deepagents' built-in middleware — not our
+ * approval gate — so it is an ungated write/edit path today and would be an
+ * ungated `execute` path with a shell backend.
+ *
+ * Registrations merge additively with deepagents' built-in prompt profiles, so
+ * disabling auto-injection here does not alter model prompt overlays.
+ */
+
+import { registerHarnessProfile } from "deepagents";
+
+const PROVIDERS_WITH_GP_SUPPRESSION = ["anthropic", "openai"] as const;
+
+let registered = false;
+
+/** Idempotent: safe to call from runner boot and from tests. */
+export function registerStigmerDeepagentsProfiles(): void {
+  if (registered) return;
+  registered = true;
+
+  for (const provider of PROVIDERS_WITH_GP_SUPPRESSION) {
+    registerHarnessProfile(provider, {
+      generalPurposeSubagent: { enabled: false },
+    });
+  }
+}
+
+/** Test-only: reset the once guard so profile registration can be re-exercised. */
+export function resetStigmerDeepagentsProfilesForTests(): void {
+  registered = false;
+}

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

@@ -29,7 +29,8 @@ import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
 import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { WorkspaceBackend, ProvisionResult } from "../../shared/workspace/types.js";
-import { CasCaptureFilesystemBackend } from "./cas-capture-backend.js";
+import { createCasCaptureBackend } from "./cas-capture-backend.js";
+import { buildShellEnv } from "./shell-env.js";
 import { CasCaptureObserver } from "./cas-capture-observer.js";
 import { isGitWorkTree, isPathCapturable } from "../../shared/filereview/git-substrate.js";
 import { deriveCaptureMode } from "../../shared/filereview/capture.js";
@@ -400,6 +401,8 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     await ensurePricingLoaded();
     const pricing = getModelPricing(modelName);
     const execConfig = execution.spec!.executionConfig;
+    const isPlanMode = execConfig?.interactionMode === InteractionMode.PLAN;
+    const shellEnv = isPlanMode ? undefined : buildShellEnv(envResult.mergedEnvVars);
 
     const toolServerMap = new Map<string, string>();
     if (mcpConnection) {
@@ -538,6 +541,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
             stigmerToken: config.stigmerToken ?? undefined,
             headerScope: { executionId },
           })).model,
+        // Presence of shellEnv is the shell-capability switch for sub-agent
+        // backends too (undefined in plan mode; see buildShellEnv above).
+        shellEnv,
       });
     }
 
@@ -556,7 +562,6 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // 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 isPlanMode = execConfig?.interactionMode === InteractionMode.PLAN;
     const planModePermissions: FilesystemPermission[] = [
       { operations: ["write"], paths: ["/**"], mode: "deny" },
     ];
@@ -567,10 +572,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // bytes of every CAS-owned path — .gitignored paths in a git work tree, all
     // touched paths in a non-git one — so the boundary can capture them into CAS.
     // It is gate-independent, so it holds even under the global bypass.
-    const fileBackend = new CasCaptureFilesystemBackend(
-      { rootDir: workspaceBackend.rootDir },
-      { observer: casObserver },
-    );
+    const fileBackend = await createCasCaptureBackend({
+      rootDir: workspaceBackend.rootDir,
+      observer: casObserver,
+      shellEnv,
+    });
     const agentGraph = await createDeepAgent({
       model,
       checkpointer: checkpointer as any,

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

@@ -0,0 +1,42 @@
+/**
+ * Shell environment for the native harness `execute` tool.
+ *
+ * Per-execution snapshot: runner-manager rotates `STIGMER_TOKEN` in
+ * `process.env` at runtime, so this must run inside setup for each execution,
+ * 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",
+];
+
+/**
+ * Build the environment map passed to deepagents' LocalShellBackend.
+ *
+ * Base: runner process env minus {@link SHELL_ENV_DENYLIST}, then overlay
+ * {@link mergedEnvVars} (ExecutionContext wins on conflict).
+ */
+export function buildShellEnv(
+  mergedEnvVars: Readonly<Record<string, string>>,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const deny = new Set(SHELL_ENV_DENYLIST);
+  const env: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (deny.has(key) || value === undefined) continue;
+    env[key] = value;
+  }
+
+  for (const [key, value] of Object.entries(mergedEnvVars)) {
+    env[key] = value;
+  }
+
+  return env;
+}