@stigmer/runner 3.12.1 → 3.12.3

package/src/middleware/__tests__/tool-intent.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Tool-intent middleware (issue #276): the shell tool's bind-time schema
+ * gains an optional model-authored `description`, execution never sees it,
+ * and the argument survives verbatim into the message history.
+ *
+ * The integration block drives a REAL deepagents graph, because the two
+ * claims that matter most are framework claims: (1) `wrapModelCall` receives
+ * the library's built-in `execute` tool and the clone reaches `bindTools`,
+ * and (2) the original tool's strip-parsing drops the extra argument before
+ * the backend's `execute(command)` runs.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { z } from "zod";
+import { tool } from "@langchain/core/tools";
+import { convertToOpenAITool } from "@langchain/core/utils/function_calling";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent } from "deepagents";
+import {
+  createToolIntentMiddleware,
+  INTENT_ARG,
+  INTENT_ARG_PROMPT,
+} from "../tool-intent.js";
+import { buildSubAgentMiddleware } from "../../activities/execute-deep-agent/subagent-wiring.js";
+import { createCasCaptureBackend } from "../../activities/execute-deep-agent/cas-capture-backend.js";
+import { CasCaptureObserver } from "../../activities/execute-deep-agent/cas-capture-observer.js";
+import {
+  ScriptedModel,
+  type ScriptSelector,
+} from "../../activities/execute-deep-agent/__test-utils__/scripted-model.js";
+
+/** A stand-in for deepagents' `execute` tool: same name, same schema shape. */
+function makeShellTool(executed: string[]) {
+  return tool(
+    async ({ command }: { command: string }) => {
+      executed.push(command);
+      return "ok";
+    },
+    {
+      name: "execute",
+      description: "Run a shell command",
+      schema: z.object({ command: z.string().describe("The shell command to execute") }),
+    },
+  );
+}
+
+function makeReadTool() {
+  return tool(async () => "contents", {
+    name: "read_file",
+    description: "Read a file",
+    schema: z.object({ file_path: z.string() }),
+  });
+}
+
+type BoundSchema = {
+  type?: string;
+  properties?: Record<string, { type?: string; description?: string }>;
+  required?: string[];
+};
+
+function schemaOf(t: unknown): BoundSchema {
+  return (t as { schema: BoundSchema }).schema;
+}
+
+async function runWrap(
+  mw: ReturnType<typeof createToolIntentMiddleware>,
+  tools: unknown[],
+): Promise<unknown[]> {
+  let seen: unknown[] = [];
+  const handler = vi.fn(async (req: { tools?: unknown[] }) => {
+    seen = req.tools ?? [];
+    return new AIMessage({ content: "" });
+  });
+  await mw.wrapModelCall!(
+    { model: {}, messages: [], tools, state: {}, runtime: {} } as never,
+    handler as never,
+  );
+  return seen;
+}
+
+describe("ToolIntentMiddleware (unit)", () => {
+  it("passes a tool-less request through untouched", async () => {
+    const mw = createToolIntentMiddleware();
+    const request = { model: {}, messages: [], state: {}, runtime: {} } as never;
+    const handler = vi.fn(async () => new AIMessage({ content: "" }));
+    await mw.wrapModelCall!(request, handler as never);
+    expect(handler).toHaveBeenCalledWith(request);
+  });
+
+  it("extends the shell tool's bound schema with the optional intent arg", async () => {
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [shell]);
+
+    expect(bound).toHaveLength(1);
+    expect(bound[0]).not.toBe(shell);
+    const schema = schemaOf(bound[0]);
+    expect(schema.properties?.command?.type).toBe("string");
+    expect(schema.properties?.[INTENT_ARG]).toEqual({
+      type: "string",
+      description: INTENT_ARG_PROMPT,
+    });
+    // Optional by construction: required is untouched.
+    expect(schema.required ?? []).not.toContain(INTENT_ARG);
+  });
+
+  it("passes non-shell tools through by reference", async () => {
+    const read = makeReadTool();
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [read, shell]);
+    expect(bound[0]).toBe(read);
+    expect(bound[1]).not.toBe(shell);
+  });
+
+  it("never shadows a real argument named like the intent arg", async () => {
+    const conflicting = tool(async () => "ok", {
+      name: "shell",
+      description: "A shell tool that already has a description arg",
+      schema: z.object({ command: z.string(), [INTENT_ARG]: z.string() }),
+    });
+    const bound = await runWrap(createToolIntentMiddleware(), [conflicting]);
+    expect(bound[0]).toBe(conflicting);
+  });
+
+  it("passes through tools whose schema is not an object schema", async () => {
+    const odd = { name: "bash", description: "odd", schema: 42 };
+    const bound = await runWrap(createToolIntentMiddleware(), [odd]);
+    expect(bound[0]).toBe(odd);
+  });
+
+  it("reuses one clone across model calls (referential stability)", async () => {
+    const mw = createToolIntentMiddleware();
+    const shell = makeShellTool([]);
+    const first = await runWrap(mw, [shell]);
+    const second = await runWrap(mw, [shell]);
+    expect(first[0]).toBe(second[0]);
+  });
+
+  it("emits a non-executable declaration that provider converters accept", async () => {
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [shell]);
+    const declaration = bound[0] as Record<string, unknown>;
+
+    // Deliberately NOT an executable tool — the agent's validation forbids
+    // swapping same-name executable instances, and execution belongs to the
+    // registered original. StructuredToolParams is the sanctioned shape.
+    expect(declaration.invoke).toBeUndefined();
+
+    // The shape every provider's bindTools converts like a structured tool.
+    const openAiTool = convertToOpenAITool(declaration as never) as {
+      function: { name: string; parameters: { properties: Record<string, unknown> } };
+    };
+    expect(openAiTool.function.name).toBe("execute");
+    expect(openAiTool.function.parameters.properties[INTENT_ARG]).toEqual({
+      type: "string",
+      description: INTENT_ARG_PROMPT,
+    });
+    expect(openAiTool.function.parameters.properties.command).toBeDefined();
+  });
+
+  it("is idempotent: an already-extended declaration passes through", async () => {
+    const mw = createToolIntentMiddleware();
+    const shell = makeShellTool([]);
+    const [firstPass] = await runWrap(mw, [shell]);
+    // A second middleware instance (e.g. a sub-agent stack composed over the
+    // same request) must not re-wrap the extended declaration.
+    const [secondPass] = await runWrap(createToolIntentMiddleware(), [firstPass]);
+    expect(secondPass).toBe(firstPass);
+  });
+});
+
+describe("ToolIntentMiddleware (real deepagents graph)", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "tool-intent-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("binds the extended execute schema to the model and strips the arg at execution", async () => {
+    const marker = join(root, "intent-marker.txt");
+    const script: ScriptSelector = () => ({
+      toolCalls: [{
+        name: "execute",
+        args: {
+          command: "echo ran > intent-marker.txt",
+          [INTENT_ARG]: "Write the marker file",
+        },
+        id: "exec_intent_1",
+      }],
+      done: "done",
+    });
+    const model = new ScriptedModel(script);
+
+    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,
+      checkpointer: checkpointer as never,
+      backend,
+      middleware: [createToolIntentMiddleware()],
+    } as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "intent-thread" }, recursionLimit: 50 };
+    await agent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    // (1) The model saw the library's execute tool WITH the intent arg.
+    const boundExecute = model.boundTools.find(
+      (t) => (t as { name?: string }).name === "execute",
+    );
+    expect(boundExecute).toBeDefined();
+    const schema = schemaOf(boundExecute);
+    expect(schema.properties?.[INTENT_ARG]?.description).toBe(INTENT_ARG_PROMPT);
+    expect(schema.properties?.command).toBeDefined();
+    expect(schema.required ?? []).not.toContain(INTENT_ARG);
+
+    // (2) Execution ran the ORIGINAL tool: strip semantics dropped the intent
+    // arg and the command executed normally.
+    expect(await readFile(marker, "utf8")).toBe("ran\n");
+
+    // (3) The intent arg survived verbatim in the message history — the
+    // exact bytes the status builder persists onto ToolCall.args.
+    const state = (await agent.getState(config)) as unknown as {
+      values: { messages: Array<{ tool_calls?: Array<{ name: string; args: Record<string, unknown> }> }> };
+    };
+    const messages = state.values.messages;
+    const toolCall = messages
+      .flatMap((m) => m.tool_calls ?? [])
+      .find((tc) => tc.name === "execute");
+    expect(toolCall).toBeDefined();
+    expect(toolCall!.args[INTENT_ARG]).toBe("Write the marker file");
+    expect(toolCall!.args.command).toBe("echo ran > intent-marker.txt");
+  });
+});
+
+describe("sub-agent stack wiring", () => {
+  it("includes the tool-intent middleware in every sub-agent stack", () => {
+    const stack = buildSubAgentMiddleware({});
+    expect(stack.map((m) => m.name)).toContain("StigmerToolIntentMiddleware");
+  });
+});
+
+describe("wire-contract fixture", () => {
+  it("INTENT_ARG matches the cross-surface fixture key the SDK reads", () => {
+    // The reader side (sdk/react intent-title tests) asserts against the
+    // same file, so the writer and readers cannot drift apart silently.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const fixture = JSON.parse(
+      readFileSync(
+        resolve(here, "../../../../../../test/fixtures/tool-view/intent-title.json"),
+        "utf8",
+      ),
+    ) as { argField: string };
+    expect(INTENT_ARG).toBe(fixture.argField);
+  });
+});

package/src/middleware/approval-gate.ts

@@ -88,10 +88,11 @@ export interface ApprovalGateConfig {
    * `write`/`delete` whose target path is capturable (git-tracked — see
    * {@link isCapturablePath}) FLOWS instead of interrupting: the edit is reviewed
    * post-hoc as a captured `FileChangeSet`, not gated before it runs. A gitignored
-   * path is NOT capturable, so it stays gated (the git substrate cannot capture or
-   * revert it) — the exact twin of the Cursor hook's `__stigmer_is_gitignored`
-   * allow-branch. `shell` and MCP tools are never bypassed by this flag. Off (the
-   * default) keeps the classic true-pause gate for every mutation.
+   * path is NOT capturable by the git substrate, so it stays gated unless
+   * {@link captureIgnored} routes it into CAS capture — the exact twin of the
+   * Cursor hook's `__stigmer_is_gitignored` allow-branch. `shell` and MCP tools
+   * are never bypassed by this flag. Off (the default) keeps the classic
+   * true-pause gate for every mutation.
    */
   readonly fileCaptureMode?: boolean;
   /**
@@ -107,12 +108,12 @@ export interface ApprovalGateConfig {
    * instead of the interrupt gate, applying the DD-E secret gate. When off, a
    * gitignored path stays on the interrupt gate exactly as before.
    *
-   * TRUE ONLY FOR THE PARENT GATE. Sub-agents build their own plain filesystem
-   * backends, which the CAS observer does not wrap, so flowing their gitignored
-   * edits would apply unobserved, unreviewable bytes. `buildSubAgentMiddleware`
-   * therefore forces this to false for sub-agent gates — it must NOT be inherited
-   * as true. (Sub-agent git-tracked edits are still captured by the turn-boundary
-   * git diff, which is backend-agnostic.)
+   * True only for gates whose backend a CAS observer wraps: the parent gate
+   * always (setup.ts), and — since DD-19 — sub-agent gates too, because
+   * `compileSubagents` gives every sub-agent a CAS-observing backend wired to
+   * the SAME shared observer and `buildSubAgentMiddleware` then inherits this
+   * config verbatim. A gate over an UNOBSERVED backend must keep this false:
+   * flowing its gitignored edits would apply unobserved, unreviewable bytes.
    */
   readonly captureIgnored?: boolean;
   /**
@@ -122,6 +123,20 @@ export interface ApprovalGateConfig {
    * secret; the CONTENT never leaves the workspace). Absent ⇒ nothing recorded.
    */
   readonly recordBlockedSecret?: (rawPath: string) => void;
+  /**
+   * Capture a file's pre-delete bytes into the CAS observer so a CAS-owned
+   * (gitignored / non-git) DELETE can flow under {@link captureIgnored} and be
+   * reviewed post-hoc exactly like a write (issue #303) — the delete twin of the
+   * backend's `recordBefore` write observation. A delete is the one mutation the
+   * backend cannot observe (deepagents has no backend delete method to wrap), so
+   * the gate captures at authorization time instead: the file's bytes are still
+   * on disk here, and the turn boundary then reads after=null and authors a
+   * `FILE_CHANGE_KIND_DELETE` with the same discard-restores contract.
+   *
+   * Absent ⇒ deletes keep today's interrupt-gate behavior (fail-closed: a delete
+   * we cannot capture cannot be reviewed, so it must be approved up front).
+   */
+  readonly captureDeleteBefore?: (rawPath: string) => Promise<void>;
   /**
    * Unattended approval mode (ExecutionConfig.approval_mode = UNATTENDED):
    * the creating surface — a messaging channel, a guest share — has no
@@ -213,22 +228,39 @@ export function createApprovalGateMiddleware(
             emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
             return await handler(request);
           }
-          // Gitignored path. Only the PARENT gate (captureIgnored) routes it into
-          // CAS capture; sub-agent gates fall through to the interrupt gate below,
-          // exactly as before (their backends are not CAS-observed).
+          // Gitignored / non-git path: a gate whose backend the shared CAS
+          // observer wraps (captureIgnored — the parent gate, and sub-agent
+          // gates since DD-19) routes it into CAS capture; any other gate falls
+          // through to the interrupt gate below.
           if (config.captureIgnored) {
-            if (isSecretLikePath(path)) {
-              // DD-E fail-closed: a secret-like gitignored edit is NEVER applied
-              // and NEVER captured. Record it so the turn boundary authors a
-              // DIFF_UNREVIEWABLE entry (blocking approval); nothing is written.
-              config.recordBlockedSecret?.(path);
-              return secretBlockToolMessage(toolName, path, toolCall.id);
-            }
             if (category === "write") {
+              if (isSecretLikePath(path)) {
+                // DD-E fail-closed: a secret-like gitignored WRITE is NEVER
+                // applied and NEVER captured — its content must not surface
+                // anywhere, approval prompt included. Record it so the turn
+                // boundary authors a DIFF_UNREVIEWABLE entry (blocking
+                // approval); nothing is written.
+                config.recordBlockedSecret?.(path);
+                return secretBlockToolMessage(toolName, path, toolCall.id);
+              }
               // Non-secret gitignored write/edit: flows (apply-then-review). The
               // CAS observer already holds its before-bytes and the turn boundary
-              // captures it into CAS. (A gitignored delete has no backend capture
-              // path, so it falls through to the interrupt gate.)
+              // captures it into CAS.
+              emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
+              return await handler(request);
+            }
+            if (category === "delete" && config.captureDeleteBefore && !isSecretLikePath(path)) {
+              // Non-secret CAS-owned delete: capture the before-bytes NOW (the
+              // one moment they still exist on disk — no backend delete method
+              // to observe them), then flow. The turn boundary reads after=null
+              // and authors a reviewable, restorable DELETE entry (issue #303).
+              //
+              // A SECRET-LIKE delete deliberately falls through to the interrupt
+              // gate instead: unlike a write, its args expose no secret content,
+              // so a human may safely approve it — but its before-bytes must
+              // never enter CAS, so it cannot flow. (This also aligns the twins:
+              // the Cursor hook routes secret deletes to its deny-gate.)
+              await config.captureDeleteBefore(path);
               emitExecutionReceipt(config, toolCall, serverSlug, category, "auto_approve", "file_capture");
               return await handler(request);
             }
@@ -244,8 +276,10 @@ export function createApprovalGateMiddleware(
       // continues) exactly like the capture-mode secret block — a secret write is
       // never applied or persisted in ANY mode. Placed AFTER the capture block so
       // capture-mode paths stay byte-identical (a capturable write already flowed;
-      // a captureIgnored gitignored secret is already blocked). Deletes carry no
-      // content and stay on the deny-gate. recordBlockedSecret is a no-op unless a
+      // a captureIgnored gitignored secret write is already blocked). A delete
+      // carries no content, so a secret-like delete needs no hard-block: it stays
+      // on the interrupt gate below, where a human may still approve it (its
+      // bytes are simply never captured). recordBlockedSecret is a no-op unless a
       // turn boundary reads it (the git-no-storage case, where it authors a
       // content-less DIFF_UNREVIEWABLE).
       if (!serverSlug && category === "write") {

package/src/middleware/index.ts

@@ -9,11 +9,12 @@
  *      workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always)
- *   3. Tool truncation (always)
- *   4. Graceful stop (always, inert until activated)
- *   5. Cost cap (conditional: only when maxCostUsd > 0)
- *   6. Error hints (always)
- *   7. OTel spans (always, no-op when OTel not configured)
+ *   3. Tool intent (always — bind-time shell schema extension, issue #276)
+ *   4. Tool truncation (always)
+ *   5. Graceful stop (always, inert until activated)
+ *   6. Cost cap (conditional: only when maxCostUsd > 0)
+ *   7. Error hints (always)
+ *   8. OTel spans (always, no-op when OTel not configured)
  */
 
 import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
@@ -21,6 +22,7 @@ import type { GracefulStopMiddleware } from "./graceful-stop.js";
 import { createPathNormalizationMiddleware } from "./path-normalization.js";
 import { createLoopDetectionMiddleware } from "./loop-detection.js";
 import { createExecutionBudgetMiddleware } from "./execution-budget.js";
+import { createToolIntentMiddleware } from "./tool-intent.js";
 import { createToolTruncationMiddleware } from "./tool-truncation.js";
 import { createGracefulStopMiddleware } from "./graceful-stop.js";
 import { createApprovalGateMiddleware } from "./approval-gate.js";
@@ -51,6 +53,8 @@ export function buildMiddlewareStack(
 
   stack.push(createExecutionBudgetMiddleware(config.executionBudget));
 
+  stack.push(createToolIntentMiddleware());
+
   stack.push(createToolTruncationMiddleware(config.toolTruncation));
 
   const gracefulStop = createGracefulStopMiddleware();

package/src/middleware/otel-spans.ts

@@ -2,7 +2,8 @@
  * OpenTelemetry spans and metrics middleware for deep-agent execution.
  *
  * Creates stigmer.llm.call and stigmer.mcp.tool_call spans with
- * attributes matching the Go workflow-runner schema (pkg/otel/spans.go).
+ * attributes matching the span schema inherited from the retired Go
+ * workflow-runner (kept stable so dashboards survived the migration).
  * Also records metrics (histograms + counters) for aggregate dashboards.
  *
  * Graceful no-op when no TracerProvider/MeterProvider is configured.

package/src/middleware/tool-intent.ts

@@ -0,0 +1,174 @@
+/**
+ * Tool-intent middleware — model-authored intent titles for shell tool calls
+ * (issue #276).
+ *
+ * The thread UI titles every shell row with the bare category label ("Shell");
+ * only the model knows *why* it is running a command, so a host-side rename
+ * can never close that gap. This middleware lets the model author the title:
+ * at model-call time it presents a schema-extended clone of the shell tool
+ * that adds one optional `description` argument. The model fills it in, the
+ * argument rides the tool call's args verbatim through checkpoints and the
+ * persisted ToolCall proto (no new state, no proto change), and the React SDK
+ * renders it as the row title with the command as secondary text.
+ *
+ * Why this seam:
+ * - The `execute` tool is owned by the deepagents library; its schema is not
+ *   ours to edit. `wrapModelCall` is the framework's intended point for
+ *   reshaping the model-visible tool list — langchain's own llmToolSelector
+ *   middleware swaps `request.tools` through exactly this hook.
+ * - Execution is untouched by construction: the agent's ToolNode is built
+ *   once from the ORIGINAL tools, and the original schema parses with strip
+ *   semantics, so the extra argument is dropped before the backend's
+ *   `execute(command)` ever runs. Approval fingerprints are equally
+ *   unaffected (`description` is not a salient arg field).
+ * - The argument name deliberately matches the Cursor harness, whose built-in
+ *   Shell tool already carries a model-authored `description` — both
+ *   harnesses converge on one wire key and the SDK reads a single field.
+ *
+ * The swapped-in declaration is a `StructuredToolParams` object — langchain's
+ * first-class shape for a non-executable, bind-time-only tool definition
+ * ("the most minimal interface … to be passed to a LLM for tool calling").
+ * A same-name RUNNABLE replacement is rejected by the agent's wrapModelCall
+ * validation (it would threaten ToolNode execution identity); a params
+ * object is exactly the declaration-without-execution the validation exists
+ * to protect, and the graph keeps executing the untouched original. Schema
+ * extension happens at the JSON-schema level via @langchain/core's interop
+ * serializer — the runner's zod (v3) must never construct fields inside the
+ * library's zod (v4) schema object.
+ */
+
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool } from "../shared/tool-kind.js";
+import type { StigmerMiddleware } from "./types.js";
+
+/**
+ * The wire name of the intent argument. Shared with the Cursor harness's
+ * built-in Shell tool and read by the SDK's tool presentation layer — the
+ * three surfaces must agree on this key.
+ */
+export const INTENT_ARG = "description";
+
+/**
+ * The behavior-shaping prompt for the intent argument (owner-approved
+ * wording, issue #276). This is prompt engineering, not documentation:
+ * changing it changes what the model writes into every shell row title.
+ */
+export const INTENT_ARG_PROMPT =
+  "A short present-tense phrase describing what this command does and why, " +
+  "shown to the user as the title of this action (5-10 words, e.g. " +
+  "'Run unit tests for the parser'). Do not restate the command syntax.";
+
+/** Structural shape of a bindable structured tool, checked at runtime. */
+interface StructuredToolLike {
+  readonly name: string;
+  readonly description: string;
+  readonly schema: unknown;
+}
+
+function isStructuredToolLike(candidate: unknown): candidate is StructuredToolLike {
+  if (candidate == null || typeof candidate !== "object") return false;
+  const t = candidate as Record<string, unknown>;
+  return (
+    typeof t.name === "string" &&
+    typeof t.description === "string" &&
+    "schema" in t
+  );
+}
+
+interface JsonObjectSchema {
+  readonly type: "object";
+  readonly properties?: Record<string, unknown>;
+  readonly [key: string]: unknown;
+}
+
+function isJsonObjectSchema(schema: unknown): schema is JsonObjectSchema {
+  return (
+    schema != null &&
+    typeof schema === "object" &&
+    (schema as Record<string, unknown>).type === "object"
+  );
+}
+
+/**
+ * Returns a bind-time `StructuredToolParams` declaration for `original`
+ * whose schema carries the optional intent argument, or `original` itself
+ * when the tool is not a shell tool, is not schema-extendable, or already
+ * defines an argument with that name (a real argument must never be
+ * shadowed by presentation metadata).
+ *
+ * Unexpected schemas pass through unchanged on purpose: a missing intent
+ * title degrades to today's rendering, while a mangled schema would break
+ * the tool for the whole execution.
+ */
+function maybeExtendShellTool(original: unknown): unknown {
+  if (!isStructuredToolLike(original)) return original;
+  if (classifyTool(original.name) !== ToolKind.SHELL) return original;
+
+  let jsonSchema: unknown;
+  try {
+    jsonSchema = toJsonSchema(original.schema as Parameters<typeof toJsonSchema>[0]);
+  } catch {
+    return original;
+  }
+  if (!isJsonObjectSchema(jsonSchema)) return original;
+
+  const properties = jsonSchema.properties ?? {};
+  if (INTENT_ARG in properties) return original;
+
+  // A plain frozen declaration, deliberately NOT an executable tool: the
+  // graph's ToolNode executes the ORIGINAL registered tool (it is built from
+  // the registered tools, not from the model request), and the agent's
+  // wrapModelCall validation only forbids swapping same-name EXECUTABLE
+  // instances. `isStructuredToolParams` recognizes this shape, so every
+  // provider's bindTools converts it exactly like a structured tool.
+  return Object.freeze({
+    name: original.name,
+    description: original.description,
+    schema: {
+      ...jsonSchema,
+      properties: {
+        ...properties,
+        [INTENT_ARG]: { type: "string", description: INTENT_ARG_PROMPT },
+      },
+    },
+  });
+}
+
+/**
+ * Creates the middleware. Install on the parent stack AND on every sub-agent
+ * stack (subagent-wiring.ts) — sub-agent shell rows render in the same
+ * thread and must carry the same titles.
+ */
+export function createToolIntentMiddleware(): StigmerMiddleware {
+  // One clone per original tool instance: repeated model calls (and repeated
+  // turns on the same graph) bind a referentially stable clone instead of
+  // re-serializing the schema every round.
+  const cloneCache = new WeakMap<object, unknown>();
+
+  const extendCached = (candidate: unknown): unknown => {
+    if (candidate == null || typeof candidate !== "object") return candidate;
+    const cached = cloneCache.get(candidate);
+    if (cached !== undefined) return cached;
+    const extended = maybeExtendShellTool(candidate);
+    cloneCache.set(candidate, extended);
+    return extended;
+  };
+
+  return {
+    name: "StigmerToolIntentMiddleware",
+    async wrapModelCall(request, handler) {
+      const tools = request.tools;
+      if (!tools || tools.length === 0) return handler(request);
+
+      let changed = false;
+      const mapped = tools.map((t) => {
+        const extended = extendCached(t);
+        if (extended !== t) changed = true;
+        return extended;
+      });
+
+      return handler(changed ? { ...request, tools: mapped } : request);
+    },
+  };
+}

package/src/runner-manager.ts

@@ -703,6 +703,7 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     { createCursorActivities },
     { createDeepAgentActivities },
     { createEnsureThreadActivities },
+    { createGenerateSessionSubjectActivities },
     { createClassifyToolApprovalsActivities },
     { createDiscoverMcpServerActivities },
     { createEvaluateExpressionsActivities },
@@ -721,6 +722,7 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     import("./activities/execute-cursor/index.js"),
     import("./activities/execute-deep-agent/index.js"),
     import("./activities/ensure-thread.js"),
+    import("./activities/generate-session-subject.js"),
     import("./activities/classify-tool-approvals.js"),
     import("./activities/discover-mcp-server.js"),
     import("./activities/evaluate-expressions.js"),
@@ -741,6 +743,7 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     ...createCursorActivities(config),
     ...createDeepAgentActivities(config),
     ...createEnsureThreadActivities(),
+    ...createGenerateSessionSubjectActivities(config),
     ...createClassifyToolApprovalsActivities(config),
     ...createDiscoverMcpServerActivities(config),
     ...createEvaluateExpressionsActivities(),

package/src/runner.ts

@@ -407,6 +407,7 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     { createCursorActivities },
     { createDeepAgentActivities },
     { createEnsureThreadActivities },
+    { createGenerateSessionSubjectActivities },
     { createClassifyToolApprovalsActivities },
     { createDiscoverMcpServerActivities },
     { createEvaluateExpressionsActivities },
@@ -425,6 +426,7 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     import("./activities/execute-cursor/index.js"),
     import("./activities/execute-deep-agent/index.js"),
     import("./activities/ensure-thread.js"),
+    import("./activities/generate-session-subject.js"),
     import("./activities/classify-tool-approvals.js"),
     import("./activities/discover-mcp-server.js"),
     import("./activities/evaluate-expressions.js"),
@@ -445,6 +447,7 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     ...createCursorActivities(config),
     ...createDeepAgentActivities(config),
     ...createEnsureThreadActivities(),
+    ...createGenerateSessionSubjectActivities(config),
     ...createClassifyToolApprovalsActivities(config),
     ...createDiscoverMcpServerActivities(config),
     ...createEvaluateExpressionsActivities(),

package/src/shared/__tests__/attachment-vision.test.ts

@@ -291,6 +291,10 @@ describe("VisionBudget — size and count budgets", () => {
   });
 
   it("ships the production constants agreed in T04 (raw bytes)", () => {
+    // Also the ADVERTISED == ENFORCED drift alarm (stigmer/stigmer#365):
+    // the registry document advertises these exact values in its
+    // `limits.vision` block, pinned by the cloud codec's own test. If this
+    // fails, the budget changed on one side only — update both together.
     expect(MAX_VISION_IMAGE_BYTES).toBe(3 * 1024 * 1024);
     expect(MAX_VISION_TOTAL_BYTES).toBe(4 * 1024 * 1024);
     expect(MAX_VISION_IMAGES).toBe(10);