fix(tools): keep list_dir off the advertised wire on execute

Promote-on-execute flushed any registered unadvertised name, so a
list_dir call put its schema on the wire until fold. Search already
hides that builtin in favor of glob; dispatch it without advertising.

Author: TheGreatAxios

src/agent/tool-search.test.ts

@@ -684,6 +684,7 @@ describe("promote-on-execute", () => {
         "ran:never",
         "A tool the model never searched for",
       ),
+      stringTool("list_dir", "listed", "list a directory's entries"),
     ];
     const runner = createDynamicToolRunner(tools);
     const advertised = createAdvertisedToolset({
@@ -773,6 +774,18 @@ describe("promote-on-execute", () => {
     expect(promoted).toEqual(["mcp__never__searched"]);
     expect(advertisedNames(advertised, runner)).toContain("mcp__never__searched");
   });
+
+  test("executing list_dir does not join the advertised tail", async () => {
+    const { advertised, promoted, runner } = wirePromoteOnExecute();
+    const before = advertisedNames(advertised, runner);
+    expect(before).not.toContain("list_dir");
+    const result = await dispatch(runner, "list_dir");
+    expect(result.content).toBe("listed");
+    expect(result.isError).toBeUndefined();
+    expect(promoted).toEqual([]);
+    expect(advertisedNames(advertised, runner)).toEqual(before);
+    expect(advertisedNames(advertised, runner)).not.toContain("list_dir");
+  });
 });
 
 describe("advertisedTools", () => {

src/agent/tool-search.ts

@@ -162,7 +162,9 @@ function isAlreadyAdvertised(
 }
 
 // Mounted built-ins that stay off the advertised prefix and off tool_search.
-const UNADVERTISED_MOUNTED_BUILTINS = new Set(["list_dir"]);
+// Promote-on-execute must not flush these onto the wire either — dispatch
+// without advertising. glob is the advertised replacement for list_dir.
+export const UNADVERTISED_MOUNTED_BUILTINS = new Set(["list_dir"]);
 
 // 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

src/exec/runner.test.ts

@@ -244,6 +244,42 @@ describe("exec director allowlist", () => {
     expect(names).not.toContain(OUTSIDE_ALLOW);
   });
 
+  test("the promoter does not commit list_dir onto the advertised wire", () => {
+    const { activated, computeAdvertised, flushPromotions } =
+      createAdvertisedToolset({
+        sessionMode: "orchestrator",
+        toolAvailability: { languageServerAvailable: true },
+        getProvider: () => ({ providerName: "test", model: "test-model" }),
+      });
+    let committed = 0;
+    const promote = createExecToolPromoter({
+      activate: (names) => activated.activate(names),
+      isAllowed: () => true,
+      commitWire: () => {
+        if (flushPromotions()) committed += 1;
+      },
+    });
+    const registry = [
+      {
+        name: "list_dir",
+        description: "list a directory",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "mcp__acme__do",
+        description: "do a thing",
+        inputSchema: { type: "object", properties: {} },
+      },
+    ];
+    promote(["list_dir", "mcp__acme__do"]);
+    expect(activated.has("list_dir")).toBe(false);
+    expect(activated.has("mcp__acme__do")).toBe(true);
+    expect(committed).toBe(1);
+    const names = computeAdvertised(registry).map((d) => d.name);
+    expect(names).not.toContain("list_dir");
+    expect(names).toContain("mcp__acme__do");
+  });
+
   test("skywalker overlay leaves every tool allowed", () => {
     const overlay = resolveExecDirectorOverlay("skywalker");
     expect(isExecOverlayToolAllowed(overlay, OUTSIDE_ALLOW)).toBe(true);
@@ -652,6 +688,7 @@ describe("exec tool call gate and promoter", () => {
         "search and render layout primitives for pages",
       ),
       stringTool("plugin__notes__save", "noted", "Save granola notes"),
+      stringTool("list_dir", "listed", "list a directory's entries"),
       stringTool(submitOutputDefinition.name, "submitted", "submit output"),
     ]);
     const { activated, isAdvertised, computeAdvertised, flushPromotions } =
@@ -760,4 +797,21 @@ describe("exec tool call gate and promoter", () => {
     expect(result.content).toBe("submitted");
     expect(result.isError).toBeUndefined();
   });
+
+  test("executing list_dir does not add it to computeAdvertised", async () => {
+    const { runner, computeAdvertised } = wireExecDiscovery();
+    const before = computeAdvertised(runner.currentDefinitions()).map(
+      (d) => d.name,
+    );
+    expect(before).not.toContain("list_dir");
+    const result = await dispatch(runner, "list_dir");
+    expect(result.content).toBe("listed");
+    expect(result.isError).toBeUndefined();
+    expect(
+      computeAdvertised(runner.currentDefinitions()).map((d) => d.name),
+    ).toEqual(before);
+    expect(
+      computeAdvertised(runner.currentDefinitions()).map((d) => d.name),
+    ).not.toContain("list_dir");
+  });
 });

src/exec/runner.ts

@@ -28,6 +28,7 @@ import {
 import {
   type ActivatedToolTracker,
   type ToolAvailability,
+  UNADVERTISED_MOUNTED_BUILTINS,
 } from "../agent/tool-search.js";
 import { detectLanguageServerAvailable } from "../agent/lsp-availability.js";
 import {
@@ -412,7 +413,11 @@ export function createExecToolPromoter(args: {
   commitWire?: () => void;
 }): (names: string[]) => void {
   return (names) => {
-    if (!args.activate(names.filter((name) => args.isAllowed(name)))) return;
+    const admitted = names.filter(
+      (name) =>
+        args.isAllowed(name) && !UNADVERTISED_MOUNTED_BUILTINS.has(name),
+    );
+    if (!args.activate(admitted)) return;
     args.commitWire?.();
     args.persist?.();
   };

src/session/assemble-runtime.test.ts

@@ -140,6 +140,22 @@ describe("createAdvertisedToolset", () => {
     expect(isAdvertised("mcp__acme__do")).toBe(true);
   });
 
+  test("flushPromotions does not commit unadvertised mounted builtins onto the wire", () => {
+    const { activated, computeAdvertised, flushPromotions } =
+      createAdvertisedToolset(wiring());
+    const registry = [def("read_file"), def("list_dir"), def("mcp__acme__do")];
+    expect(activated.activate(["list_dir"])).toBe(true);
+    expect(flushPromotions()).toBe(false);
+    expect(computeAdvertised(registry).map((d) => d.name)).not.toContain(
+      "list_dir",
+    );
+    expect(activated.activate(["mcp__acme__do"])).toBe(true);
+    expect(flushPromotions()).toBe(true);
+    const names = computeAdvertised(registry).map((d) => d.name);
+    expect(names).not.toContain("list_dir");
+    expect(names).toContain("mcp__acme__do");
+  });
+
   test("pruneIdlePromotions drops execute-promoted schemas and keeps the frozen prefix", () => {
     const { activated, computeAdvertised, flushPromotions, pruneIdlePromotions } =
       createAdvertisedToolset(

src/session/assemble-runtime.ts

@@ -46,6 +46,7 @@ import {
   advertisedTools,
   advertisedToolNamesForSessionMode,
   createActivatedToolTracker,
+  UNADVERTISED_MOUNTED_BUILTINS,
   type ActivatedToolTracker,
   type ToolAvailability,
 } from "../agent/tool-search.js";
@@ -467,6 +468,9 @@ export function createAdvertisedToolset(args: {
     let grew = false;
     for (const name of activated.list()) {
       if (wireActivatedSet.has(name)) continue;
+      // Search hides these; flushing would put the schema on the wire until
+      // fold. Dispatch stays available via intercept without advertising.
+      if (UNADVERTISED_MOUNTED_BUILTINS.has(name)) continue;
       wireActivatedSet.add(name);
       wireActivated.push(name);
       grew = true;

src/tui/dynamic-tool-runner.test.ts

@@ -134,6 +134,31 @@ describe("call gate", () => {
     expect(promoted).toEqual(["mcp__acme__do"]);
     expect(advertised.has("mcp__acme__other")).toBe(false);
   });
+
+  test("list_dir dispatches under a call gate without promoting", async () => {
+    const runner = createDynamicToolRunner([
+      stringTool("read_file", "core"),
+      stringTool("list_dir", "listed"),
+      stringTool("mcp__acme__do", "blind-result"),
+    ]);
+    const advertised = new Set(["read_file"]);
+    const promoted: string[] = [];
+    runner.setCallGate((name) => advertised.has(name));
+    runner.setOnUndeclaredCall((name) => {
+      promoted.push(name);
+      advertised.add(name);
+    });
+
+    const result = await runner.run(
+      { id: "1", name: "list_dir", arguments: {} },
+      new AbortController().signal,
+    );
+    expect(result.content).toBe("listed");
+    expect(result.isError).toBeUndefined();
+    expect(promoted).toEqual([]);
+    expect(advertised.has("list_dir")).toBe(false);
+    expect(advertised.has("mcp__acme__do")).toBe(false);
+  });
 });
 
 describe("mangled dispatch names", () => {

src/tui/dynamic-tool-runner.ts

@@ -13,6 +13,7 @@ import {
 import { resolveRegisteredToolName } from "./resolve-registered-tool-name.js";
 import { stripTerminalControlSequences } from "../util/control-char-strip.js";
 import { prepareDispatchedToolCall } from "../agent/tool-aliases.js";
+import { UNADVERTISED_MOUNTED_BUILTINS } from "../agent/tool-search.js";
 
 // A tool runner whose set of tools can grow after construction. The static
 // createToolRunner freezes its name map at build time, which cannot accommodate
@@ -156,16 +157,21 @@ export function createDynamicToolRunner(
       // then run the call. Search does not pre-promote the match set. If the
       // promoter cannot admit the name (closed overlay, denied family), the
       // gate still fails and the model is pointed at tool_search.
+      // Unadvertised mounted builtins (list_dir) stay off the wire — search
+      // hides them in favor of glob — so intercept dispatches without
+      // flushPromotions rather than advertising until fold.
       if (callGate !== undefined && !callGate(resolved)) {
-        onUndeclaredCall?.(resolved);
-        if (!callGate(resolved)) {
-          return {
-            callId: call.id,
-            content:
-              `Error: ${resolved} is not in the currently advertised tool list. ` +
-              `Call tool_search to find it, then retry the call.`,
-            isError: true,
-          };
+        if (!UNADVERTISED_MOUNTED_BUILTINS.has(resolved)) {
+          onUndeclaredCall?.(resolved);
+          if (!callGate(resolved)) {
+            return {
+              callId: call.id,
+              content:
+                `Error: ${resolved} is not in the currently advertised tool list. ` +
+                `Call tool_search to find it, then retry the call.`,
+              isError: true,
+            };
+          }
         }
       }
       let dispatchCall: ToolCall;