perf(tools): hold promoted tools off the wire until a safe boundary

Activating a tool mid-session used to grow the advertised set on the next turn, re-prefilling the provider's cached prompt prefix. Promotion now opens only the call gate, so the model can invoke the tool at once, while the wire set stays byte-identical until rotation, compaction, or session start commits it.

Author: TheGreatAxios

src/agent/director.ts

@@ -62,7 +62,6 @@ const logger = getLogger([LOG_NAMESPACE_ROOT, "agent", "director"]);
 // otherwise invisible — it shows up only as a billing and latency spike a turn
 // later. Hashed rather than logged verbatim: MCP tool descriptions are
 // arbitrary-length, server-supplied text and do not belong in the log stream.
-// See CL-7868.
 function toolSetDigest(tools: readonly ToolDefinition[]): string {
   const shape = tools.map((t) => `${t.name}:${t.description ?? ""}`).join("|");
   return createHash("sha256").update(shape).digest("hex").slice(0, 12);

src/agent/tool-search.ts

@@ -8,7 +8,8 @@ import { sessionModeEnablesSubAgents } from "../config/session-mode.js";
 
 // Tools whose full schema is always advertised to the model. Everything else is
 // registered but discovered on demand via tool_search, which promotes matches
-// onto the advertised set and the call gate. Shared by the system prompt and
+// onto the call gate at once; the full schema joins the wire set at the next
+// cache-safe boundary. Shared by the system prompt and
 // the advertised-set gate so the two never drift.
 //
 // `present` is deliberately absent: most sessions never render a view, and at
@@ -142,10 +143,11 @@ export const ADVERTISED_TOOL_NAMES: readonly string[] = [
 
 // Project the live tool registry onto the advertised set: the fixed built-in
 // prefix (its order never changes — this is what keeps the provider cache
-// prefix stable) followed by session-activated tools (MCP or otherwise) in
-// first-activation order. The wire array is byte-stable turn to turn until a
-// discovery appends a new name, at which point it grows once and then holds
-// steady again. `activated` is expected to already be deduped/ordered (see
+// prefix stable) followed by wire-committed tools (MCP or otherwise) in
+// first-commit order. The wire array is byte-stable turn to turn: callers pass
+// only names committed via flushPromotions at a cache-safe boundary, never the
+// live activation list, so a mid-session discovery cannot append here.
+// `activated` is expected to already be deduped/ordered (see
 // `createActivatedToolTracker`), but names are deduped again here defensively
 // so a caller passing raw matches still can't reorder or duplicate an entry.
 export function advertisedTools(
@@ -209,7 +211,7 @@ export function createActivatedToolTracker(): ActivatedToolTracker {
 export const toolSearchDefinition: ToolDefinition = {
   name: "tool_search",
   description:
-    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are not advertised until this search promotes them onto the wire. Core tools (read_file, run_shell, web_fetch, web_search, spawn_agent, …) are already on the wire — do not tool_search for them. wait_agents is mounted on exec-primary runs only, so it is not on the wire elsewhere and this search cannot promote it there. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get matching tools' names, descriptions, and input schemas. Matched tools are promoted and callable on return — invoke them directly, no separate load step.",
+    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are not callable until this search promotes them. Core tools (read_file, run_shell, web_fetch, web_search, spawn_agent, …) are already on the wire — do not tool_search for them. wait_agents is mounted on exec-primary runs only, so it is not on the wire elsewhere and this search cannot promote it there. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get matching tools' names, descriptions, and input schemas. Matched tools are promoted and callable on return — invoke them directly, no separate load step.",
   inputSchema: {
     type: "object",
     properties: {
@@ -283,9 +285,9 @@ export function createToolIndex(
 export interface ToolSearchDeps {
   search: (query: string) => string[];
   lookup: (name: string) => ToolDefinition | undefined;
-  // Promote matches onto the advertised set and the call gate so the model can
-  // invoke them this turn. The next inference also declares them on the wire
-  // for strict providers.
+  // Promote matches onto the call gate so the model can invoke them this turn
+  // from the result card's schema. Wire declaration follows at the next
+  // cache-safe boundary (compaction fold), never mid-thread.
   promote: (names: string[]) => void;
   // Resolves to the remaining in-flight MCP handshake count after waiting up
   // to `timeoutMs`. The toolset bounds its own wait; the handler re-races
@@ -374,12 +376,12 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
       if (names.length === 0) {
         return `No tools matched "${query}". Try different keywords describing the capability.`;
       }
-      // Matches are promoted into the advertised set so the next inference
-      // declares them on the wire — required for strict providers (e.g. the grok
-      // Responses API) where a model cannot call a tool that was never declared.
-      // The tool result below still carries name, description, AND input schema
-      // so the model can shape arguments this same turn, before the promoted
-      // definition round-trips through the next infer call.
+      // Matches open on the call gate at once; the full schema joins the wire
+      // declarations at the next cache-safe boundary (compaction fold), never
+      // mid-thread, so the provider's cached prefix stays byte-stable. The
+      // tool result below still carries name, description, AND input schema
+      // so the model can shape arguments and call this same turn, before the
+      // promoted definition is declared on the wire.
       deps.promote(names);
       const blocks = names.map((name) =>
         renderToolCard(deps.lookup(name), name),

src/director.test.ts

@@ -1,10 +1,6 @@
 import { describe, test, expect } from "bun:test";
 import { createChatDirector, askOperatorDefinition } from "./agent/director.js";
 import { createAgentToolset } from "./agent/tools.js";
-import {
-  advertisedTools,
-  createActivatedToolTracker,
-} from "./agent/tool-search.js";
 import { createAdvertisedToolset } from "./session/assemble-runtime.js";
 import { createPermissionGate } from "./permission/gate.js";
 import {
@@ -1146,12 +1142,13 @@ describe("updateToolDefinitions rewrites infer tools", () => {
     expect(JSON.stringify(after)).toBe(JSON.stringify(before));
   });
 
-  // CL-7868: the provider cache is a prefix cache keyed on the tools array,
-  // so a tool_search turn that promotes a genuinely new tool must not reshape
-  // the wire set mid-session. The call gate opens (the model invokes the tool
-  // from the search result's schema) while the advertised array holds steady
-  // until the next cache-safe boundary.
-  test("a tool_search turn promoting a genuinely new tool leaves the wire byte-identical", async () => {
+  // CL-7868 (direction A): the provider cache is a prefix cache keyed on the
+  // tools array, so a tool_search turn that promotes a genuinely new tool must
+  // not reshape the wire set mid-session. The call gate opens (the model
+  // invokes the tool from the search result's schema) while the advertised
+  // array holds steady; the growth event lands at the next cache-safe
+  // boundary (compaction fold), appended after the untouched fixed prefix.
+  test("a tool_search turn promoting a genuinely new tool leaves the wire byte-identical until the fold commits it", async () => {
     const linearTool = {
       name: "mcp__linear__list_issues",
       description: "list issues",
@@ -1188,19 +1185,47 @@ describe("updateToolDefinitions rewrites infer tools", () => {
     );
 
     // tool_search matched a genuinely new tool: the runner opens the call
-    // gate and refreshes the director exactly as it does today.
-    advertised.activated.activate(["mcp__linear__list_issues"]);
+    // gate (activation); the per-turn wire recompute deliberately ignores it.
+    expect(advertised.activated.activate(["mcp__linear__list_issues"])).toBe(
+      true,
+    );
     director.updateToolDefinitions(
       advertised.computeAdvertised(toolset.dynamicRunner.currentDefinitions()),
     );
 
+    // Mid-session the wire is byte-identical — the hot prefix never grows —
+    // while the gate is open so the model can invoke the match from the
+    // result card's schema.
     const after = await firstInferTools(
       director,
       makeMessageReceivedEvent("continue"),
     );
     expect(JSON.stringify(after)).toBe(JSON.stringify(before));
     expect(advertised.isAdvertised("mcp__linear__list_issues")).toBe(true);
 
+    // Cache-safe boundary (compaction fold): the pending promotion commits and
+    // the next turn declares it after the untouched fixed prefix.
+    expect(advertised.flushPromotions()).toBe(true);
+    director.updateToolDefinitions(
+      advertised.computeAdvertised(toolset.dynamicRunner.currentDefinitions()),
+    );
+    const folded = await firstInferTools(
+      director,
+      makeMessageReceivedEvent("after fold"),
+    );
+    const foldedNames = (folded as { name: string }[]).map((t) => t.name);
+    expect(foldedNames).toContain("mcp__linear__list_issues");
+    const beforeNames = (before as { name: string }[])
+      .map((t) => t.name)
+      .filter((n) => n !== "submit_output");
+    const foldedPrefix = foldedNames.filter(
+      (n) => n !== "submit_output" && n !== "mcp__linear__list_issues",
+    );
+    expect(foldedPrefix).toEqual(beforeNames);
+    expect(foldedNames.indexOf("mcp__linear__list_issues")).toBe(
+      beforeNames.length,
+    );
+
     await toolset.dispose();
   });
 
@@ -1224,12 +1249,13 @@ describe("updateToolDefinitions rewrites infer tools", () => {
     expect(inferToolNames(inferAction)).toContain("submit_output");
   });
 
-  // End-to-end: tool_search matches an MCP tool, the runner's promote wiring
-  // (mirrored here via createActivatedToolTracker + updateToolDefinitions) grows
-  // the wire set once with the tool's full definition, and it then holds steady.
-  // On a strict provider, a model can only call a tool
-  // that was actually declared on the wire, so promotion must land here.
-  test("a tool_search match is on the wire on the next turn, then the array holds stable", async () => {
+  // End-to-end: tool_search matches an MCP tool; the runner's gate-only promote
+  // wiring (mirrored here via createAdvertisedToolset + updateToolDefinitions)
+  // keeps it off the wire the next turn — the hot prefix stays byte-identical
+  // while the gate lets the model call it from the result card. The fold
+  // commits the pending promotion with the tool's full definition, appended
+  // after the untouched fixed prefix, and the array then holds steady.
+  test("a tool_search match stays off the wire until the fold, then holds stable", async () => {
     const linearTool = {
       name: "mcp__linear__list_issues",
       description: "list issues",
@@ -1249,10 +1275,14 @@ describe("updateToolDefinitions rewrites infer tools", () => {
       { kind: "string", definition: linearTool, handler: async () => "ok" },
     ]);
 
-    const activated = createActivatedToolTracker();
+    const advertised = createAdvertisedToolset({
+      sessionMode: "orchestrator",
+      toolAvailability: { languageServerAvailable: false },
+      getProvider: () => ({ providerName: "openai", model: "gpt-5" }),
+    });
     const computeAdvertised = (
       all: ReturnType<typeof toolset.dynamicRunner.currentDefinitions>,
-    ) => advertisedTools(all, activated.list());
+    ) => advertised.computeAdvertised(all);
     const director = createChatDirector(
       "base-prompt",
       computeAdvertised(toolset.dynamicRunner.currentDefinitions()),
@@ -1268,17 +1298,34 @@ describe("updateToolDefinitions rewrites infer tools", () => {
     expect(beforeNames).not.toContain("mcp__linear__list_issues");
     const beforeJson = JSON.stringify(before);
 
-    // Simulate the runner's promoteTools: tool_search matched this tool, so it
-    // is activated and the director's tool set is updated for the next infer.
-    activated.activate(["mcp__linear__list_issues"]);
+    // Simulate the runner's gate-only promoter plus its boundary wire push:
+    // the gate opens but the wire recompute is byte-identical until the fold.
+    advertised.activated.activate(["mcp__linear__list_issues"]);
     director.updateToolDefinitions(
       computeAdvertised(toolset.dynamicRunner.currentDefinitions()),
     );
 
-    const after = await firstInferTools(
+    const gated = await firstInferTools(
       director,
       makeMessageReceivedEvent("continue"),
     );
+    expect((gated as { name: string }[]).map((t) => t.name)).not.toContain(
+      "mcp__linear__list_issues",
+    );
+    expect(JSON.stringify(gated)).toBe(beforeJson);
+
+    // Simulate the compaction fold: commit the pending promotion, push the
+    // refreshed set, and the tool is declared — appended after the fixed
+    // built-in prefix, which survives untouched ahead of it.
+    advertised.flushPromotions();
+    director.updateToolDefinitions(
+      computeAdvertised(toolset.dynamicRunner.currentDefinitions()),
+    );
+
+    const after = await firstInferTools(
+      director,
+      makeMessageReceivedEvent("after fold"),
+    );
     const afterTools = after as { name: string }[];
     const afterNames = afterTools.map((t) => t.name);
     expect(afterNames).toContain("mcp__linear__list_issues");

src/exec/runner.test.ts

@@ -63,19 +63,15 @@ describe("exec director allowlist", () => {
   test("promote cannot make an outside-allow tool callable under explorer", () => {
     const overlay = resolveExecDirectorOverlay("explorer");
     expect(isExecOverlayToolAllowed(overlay, OUTSIDE_ALLOW)).toBe(false);
-    const { activated, computeAdvertised, isAdvertised } =
-      createAdvertisedToolset({
-        sessionMode: "orchestrator",
-        toolAvailability: { languageServerAvailable: true },
-        getProvider: () => ({ providerName: "test", model: "test-model" }),
-        builtInPrefix: overlay.advertisedAllow,
-      });
+    const { activated, isAdvertised } = createAdvertisedToolset({
+      sessionMode: "orchestrator",
+      toolAvailability: { languageServerAvailable: true },
+      getProvider: () => ({ providerName: "test", model: "test-model" }),
+      builtInPrefix: overlay.advertisedAllow,
+    });
     const promote = createExecToolPromoter({
       activate: (names) => activated.activate(names),
       isAllowed: (name) => isExecOverlayToolAllowed(overlay, name),
-      currentDefinitions: () => [],
-      computeAdvertised,
-      updateDirectorTools: () => undefined,
     });
     promote([OUTSIDE_ALLOW]);
     expect(activated.has(OUTSIDE_ALLOW)).toBe(false);
@@ -85,28 +81,39 @@ describe("exec director allowlist", () => {
     ).toBe(false);
   });
 
-  test("the promoter gates allow itself — a raw activate caller gets no bypass", () => {
+  test("the promoter gates allow itself and leaves the wire set for the fold", () => {
     const overlay = resolveExecDirectorOverlay("explorer");
-    const { activated, computeAdvertised } = createAdvertisedToolset({
-      sessionMode: "orchestrator",
-      toolAvailability: { languageServerAvailable: true },
-      getProvider: () => ({ providerName: "test", model: "test-model" }),
-      builtInPrefix: overlay.advertisedAllow,
-    });
-    let advertisedCount = 0;
+    const { activated, computeAdvertised, flushPromotions } =
+      createAdvertisedToolset({
+        sessionMode: "orchestrator",
+        toolAvailability: { languageServerAvailable: true },
+        getProvider: () => ({ providerName: "test", model: "test-model" }),
+        builtInPrefix: overlay.advertisedAllow,
+      });
     const promote = createExecToolPromoter({
       activate: (names) => activated.activate(names),
       isAllowed: (name) => isExecOverlayToolAllowed(overlay, name),
-      currentDefinitions: () => [],
-      computeAdvertised,
-      updateDirectorTools: () => {
-        advertisedCount += 1;
-      },
     });
+    const registry = [
+      {
+        name: "read_file",
+        description: "read a file",
+        inputSchema: { type: "object", properties: {} },
+      },
+    ];
+    const before = JSON.stringify(computeAdvertised(registry));
+    // A raw activate caller gets no bypass: outside-allow names never open the
+    // gate, while the allowed match opens it at once.
     promote([OUTSIDE_ALLOW, "read_file"]);
     expect(activated.has(OUTSIDE_ALLOW)).toBe(false);
     expect(activated.has("read_file")).toBe(true);
-    expect(advertisedCount).toBe(1);
+    // Gate-only: the wire recompute ignores the fresh activation, so the
+    // provider's cached prefix holds until the fold commits it.
+    expect(JSON.stringify(computeAdvertised(registry))).toBe(before);
+    expect(flushPromotions()).toBe(true);
+    expect(computeAdvertised(registry).map((d) => d.name)).toContain(
+      "read_file",
+    );
   });
 
   test("skywalker overlay leaves every tool allowed", () => {

src/exec/runner.ts

@@ -48,7 +48,6 @@ import type {
   ContextStore,
   InferenceSource,
   InboundMessage,
-  ToolDefinition,
 } from "@intx/types/runtime";
 import { OPERATOR_ORIGINATED_FLAG } from "../agent/message-provenance.js";
 import { loadAgentProfiles } from "../agent/profiles.js";
@@ -403,14 +402,14 @@ export function createExecToolCallGate(
 export function createExecToolPromoter(args: {
   activate: (names: readonly string[]) => boolean;
   isAllowed: (name: string) => boolean;
-  currentDefinitions: () => readonly ToolDefinition[];
-  computeAdvertised: (all: readonly ToolDefinition[]) => ToolDefinition[];
-  updateDirectorTools: (defs: ToolDefinition[]) => void;
   persist?: () => void;
 }): (names: string[]) => void {
   return (names) => {
+    // Gate-only, like the TUI promoteTools: activation lets the model invoke
+    // the match from the result card's schema at once, while the schema joins
+    // the wire set at the next cache-safe boundary (compaction fold) so the
+    // provider's cached prefix never grows mid-thread (CL-7868).
     if (!args.activate(names.filter((name) => args.isAllowed(name)))) return;
-    args.updateDirectorTools(args.computeAdvertised(args.currentDefinitions()));
     args.persist?.();
   };
 }
@@ -818,6 +817,7 @@ export async function runExec(config: Config): Promise<ExecResult> {
       activated: activatedToolNames,
       computeAdvertised,
       isAdvertised,
+      flushPromotions,
     } = createAdvertisedToolset({
       sessionMode,
       toolAvailability,
@@ -879,6 +879,17 @@ export async function runExec(config: Config): Promise<ExecResult> {
             return tools.length > 0 ? { activatedTools: tools } : undefined;
           },
           telemetry: liveTelemetry,
+          onFolded: () => {
+            // A fold restarts the provider's cached prefix anyway: commit
+            // mid-session promotions so the next turn declares them.
+            if (flushPromotions()) {
+              directorHolder.instance?.updateToolDefinitions(
+                computeAdvertised(
+                  agentToolset.dynamicRunner.currentDefinitions(),
+                ),
+              );
+            }
+          },
         }),
       onBuilt: (agent, storage) => {
         currentAgent = agent;
@@ -895,11 +906,6 @@ export async function runExec(config: Config): Promise<ExecResult> {
       createExecToolPromoter({
         activate: (names) => activatedToolNames.activate(names),
         isAllowed: (name) => isExecOverlayToolAllowed(overlay, name),
-        currentDefinitions: () =>
-          agentToolset.dynamicRunner.currentDefinitions(),
-        computeAdvertised,
-        updateDirectorTools: (defs) =>
-          directorHolder.instance?.updateToolDefinitions(defs),
         persist: () => {
           void persist("running");
         },