feat(tools): promote discovered tools only on execute

Search returns cards only. A call declares that one name, then dispatches.

Author: TheGreatAxios

src/agent/tool-search.test.ts

@@ -15,8 +15,9 @@ import { advertisedToolName, projectToolDefinition } from "./tool-aliases.js";
 import { canonicalToolName } from "./canonical-tool-name.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 call gate and the next infer's wire set. Shared by the system prompt
+// registered but discovered on demand via tool_search, which returns name +
+// description cards only. A found tool's schema joins the wire when the model
+// actually calls it (promote-on-execute). 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
@@ -202,9 +203,9 @@ export function advertisedTools(
 }
 
 // Tracks which non-built-in tool names the session has activated (via
-// tool_search matches, or a director-side trigger like the lsp hint), in
-// first-activation order. Backed by a Set, so re-activating an already-active
-// name is a no-op — it neither reorders nor duplicates the entry.
+// promote-on-execute of a called name, or a director-side trigger like the
+// lsp hint), in first-activation order. Backed by a Set, so re-activating an
+// already-active name is a no-op — it neither reorders nor duplicates the entry.
 export interface ActivatedToolTracker {
   // Adds any new names and returns whether the set actually changed.
   activate(names: readonly string[]): boolean;
@@ -243,14 +244,19 @@ 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 on the wire until this search promotes them onto the next inference. Core tools (read, bash, 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 a ranked handful of matching names and short descriptions. Matched tools join the next inference tool list — call them on the next turn, not from this result.",
+    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are found here as name + description cards; their schemas join the wire when you actually call them. Core tools (read, bash, 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 surface it there. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get a ranked handful of matching names and short descriptions (default 5, overridable via limit, max 20). Search does not add schemas to the tool list — call a returned name to use it.",
   inputSchema: {
     type: "object",
     properties: {
       query: {
         type: "string",
         description: "A short description of the capability you need.",
       },
+      limit: {
+        type: "number",
+        description:
+          "Max matches to return (default 5, hard cap 20). Override when you need a wider set.",
+      },
     },
     required: ["query"],
   },
@@ -263,16 +269,17 @@ export interface ToolIndex {
 
 // Rank registered tools against name + description via the shared lexical
 // scorer. Already-advertised tools are always callable so they never rank;
-// the allow list (when set) keeps search from promoting outside it.
+// the allow list (when set) keeps search from listing tools outside it.
 export const TOOL_SEARCH_MAX_RESULTS = 5;
+export const TOOL_SEARCH_LIMIT_MAX = 20;
 export const TOOL_SEARCH_SCORE_RATIO = 0.75;
 export const TOOL_SEARCH_DESC_MAX = 160;
 
 export function createToolIndex(
   getDefs: () => readonly ToolDefinition[],
   advertisedNames: readonly string[] = ADVERTISED_TOOL_NAMES,
   // Closed allow list (exec director overlays): when set, the index only
-  // surfaces allowed tools so search cannot promote outside the allow.
+  // surfaces allowed tools so search cannot list names outside the allow.
   allow?: readonly string[] | undefined,
 ): ToolIndex {
   const score = (
@@ -314,10 +321,8 @@ export function createToolIndex(
 }
 
 export interface ToolSearchDeps {
-  search: (query: string) => string[];
+  search: (query: string, limit?: number) => string[];
   lookup: (name: string) => ToolDefinition | undefined;
-  // Promote matches onto the call gate and the next infer's wire set.
-  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
   // below so even a stuck dependency can never hang the call. Omitted callers
@@ -347,7 +352,39 @@ export const TOOL_SEARCH_PENDING_WAIT_MS = 1_000;
 // out-of-band authorization.
 export const TOOL_SEARCH_RECONNECT_WAIT_MS = 500;
 
-const ToolSearchArgs = type({ query: "string" });
+const ToolSearchArgs = type({
+  query: "string",
+  "limit?": "number",
+});
+
+function resolveSearchLimit(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return TOOL_SEARCH_MAX_RESULTS;
+  }
+  const n = Math.trunc(value);
+  if (n < 1) return TOOL_SEARCH_MAX_RESULTS;
+  return Math.min(n, TOOL_SEARCH_LIMIT_MAX);
+}
+
+function parseToolSearchArgs(
+  rawArgs: Record<string, unknown>,
+): { error: string } | { query: string; limit: number } {
+  const parsed = ToolSearchArgs(rawArgs);
+  const queryRaw =
+    parsed instanceof type.errors ? rawArgs.query : parsed.query;
+  if (typeof queryRaw !== "string") {
+    return { error: "Error: tool_search requires query (string)." };
+  }
+  const query = queryRaw.trim();
+  if (query.length === 0) {
+    return { error: "Error: tool_search requires a non-empty query." };
+  }
+  const limit =
+    parsed instanceof type.errors
+      ? TOOL_SEARCH_MAX_RESULTS
+      : resolveSearchLimit(parsed.limit);
+  return { query, limit };
+}
 
 function capDescription(text: string, max = TOOL_SEARCH_DESC_MAX): string {
   const oneLine = text.replace(/\s+/g, " ").trim();
@@ -384,14 +421,10 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
   return stringTool({
     definition: toolSearchDefinition,
     handler: async (rawArgs: Record<string, unknown>): Promise<string> => {
-      const parsed = ToolSearchArgs(rawArgs);
-      if (parsed instanceof type.errors) {
-        return "Error: tool_search requires query (string).";
-      }
-      const query = parsed.query.trim();
-      if (query.length === 0)
-        return "Error: tool_search requires a non-empty query.";
-      let names = deps.search(query);
+      const parsed = parseToolSearchArgs(rawArgs);
+      if ("error" in parsed) return parsed.error;
+      const { query, limit } = parsed;
+      let names = deps.search(query, limit);
       if (names.length === 0 && deps.awaitPendingConnections !== undefined) {
         // Tier 1 — miss while connectors start up: wait briefly, then
         // re-search so late-mounting tools land. The race bounds even a stuck
@@ -400,7 +433,7 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
           deps.awaitPendingConnections,
           deps.pendingWaitMs ?? TOOL_SEARCH_PENDING_WAIT_MS,
         );
-        names = deps.search(query);
+        names = deps.search(query, limit);
         if (
           names.length === 0 &&
           (stillPending ?? 1) > 0 &&
@@ -414,7 +447,7 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
             deps.awaitPendingConnections,
             TOOL_SEARCH_RECONNECT_WAIT_MS,
           );
-          names = deps.search(query);
+          names = deps.search(query, limit);
         }
         if (names.length === 0 && (stillPending ?? 1) > 0) {
           const detail =
@@ -429,14 +462,13 @@ export function createToolSearchTool(deps: ToolSearchDeps): AgentTool {
       if (names.length === 0) {
         return `No tools matched "${query}". Try different keywords describing the capability.`;
       }
-      // Matches open on the call gate and join the next infer's wire set
-      // (promoter flushes at activate). The card is names + capped
-      // descriptions only — full schemas ride the next tools array.
-      deps.promote(names);
+      // Cards only — name + capped description. Search does not open the call
+      // gate or grow the tools array; promote-on-execute declares a name when
+      // the model actually calls it.
       const blocks = names.map((name) =>
         renderToolCard(deps.lookup(name), name),
       );
-      return `Promoted onto the next inference tool list. Call them on the next turn:\n\n${blocks.join("\n")}`;
+      return `Matching tools — call a listed name to use it:\n\n${blocks.join("\n")}`;
     },
   });
 }

src/agent/tool-search.ts

@@ -291,7 +291,7 @@ export interface AgentToolsetArgs {
   /**
    * Closed allow list (exec director overlays). tool_search is mounted only
    * when the allow includes it, and the search index only surfaces allowed
-   * tools so search cannot promote outside the allow. Omit for the product
+   * tools so search cannot list names outside the allow. Omit for the product
    * default (tool_search mounted, index over the live registry).
    */
   toolSearchAllow?: readonly string[];
@@ -378,8 +378,9 @@ export interface AgentToolset {
   // Catalog unshadow can change local → global/none without rebuilding the
   // toolset; connectOne reads this on every late connect.
   setMcpServersSource: (source: "local" | "global" | "none") => void;
-  // Wire the callback the `tool_search` tool invokes to make matched tools
-  // advertised. Set by the runner once the director + reload loop exist.
+  // Wire the session promoter used for promote-on-execute (a registered
+  // undeclared call declares that one name, then dispatches). Set by the
+  // runner once the director + reload loop exist.
   setToolPromoter: (promote: (names: string[]) => void) => void;
   // Session-start skill snapshot shared with the prompt listing.
   skills: SkillSummary[];
@@ -782,11 +783,9 @@ export async function createAgentToolset(
     }),
   ];
 
-  // tool_search ranks over the live runner (set just below) and promotes matches
-  // through a holder the runner wires up once its advertise/reload loop exists.
-  const promoter: { promote: (names: string[]) => void } = {
-    promote: () => undefined,
-  };
+  // tool_search ranks over the live runner (set just below). Matches stay
+  // cards-only; the session promoter (wired once advertise/reload exists)
+  // declares a name when the model actually calls it.
   const runnerHolder: { current?: DynamicToolRunner } = {};
   const toolIndex = createToolIndex(
     () => runnerHolder.current?.currentDefinitions() ?? [],
@@ -795,19 +794,18 @@ export async function createAgentToolset(
   );
   // Closed exec allow lists omit tool_search itself (leaf posture); when the
   // allow excludes it the tool is never mounted, so there is nothing to
-  // search with and nothing the promoter can activate.
+  // search with.
   if (
     args.toolSearchAllow === undefined ||
     args.toolSearchAllow.includes(toolSearchDefinition.name)
   ) {
     baseTools.push(
       createToolSearchTool({
-        search: (query) => toolIndex.search(query),
+        search: (query, limit) => toolIndex.search(query, limit),
         lookup: (name) =>
           runnerHolder.current
             ?.currentDefinitions()
             .find((d) => d.name === name),
-        promote: (names) => promoter.promote(names),
         // Misses wait briefly for in-flight MCP handshakes (bounded, so hung
         // OAuth cannot hang the call) and re-search before answering. Reads the
         // connection map live — declared below, populated by the time any
@@ -1608,7 +1606,7 @@ export async function createAgentToolset(
       mcpServersSource = source;
     },
     setToolPromoter: (promote) => {
-      promoter.promote = promote;
+      dynamicRunner.setOnUndeclaredCall((name) => promote([name]));
     },
     skills,
     ...(fleetRecords !== undefined ? { fleetRecords } : {}),

src/agent/tools.ts

@@ -672,12 +672,12 @@ describe("exec tool call gate and promoter", () => {
         flushPromotions();
       },
     });
+    runner.setOnUndeclaredCall((name) => promote([name]));
     const search = createToolSearchTool({
       search: (query) =>
         createToolIndex(() => runner.currentDefinitions()).search(query),
       lookup: (name) =>
         runner.currentDefinitions().find((d) => d.name === name),
-      promote,
     });
     return {
       runner,
@@ -698,41 +698,57 @@ describe("exec tool call gate and promoter", () => {
     );
   }
 
-  test("tool_search then MCP dispatch with the gate on", async () => {
+  test("search does not change the advertised set", async () => {
     const { runner, search, persistCount, computeAdvertised } =
       wireExecDiscovery();
-    const blocked = await dispatch(runner, "mcp__linear__save_issue");
-    expect(blocked.isError).toBe(true);
-    expect(blocked.content).toContain("tool_search");
+    const before = computeAdvertised(runner.currentDefinitions()).map(
+      (d) => d.name,
+    );
+    expect(before).not.toContain("mcp__linear__save_issue");
 
     if (search.kind !== "string") throw new Error("expected string tool");
     await search.handler({ query: "linear" }, new AbortController().signal);
-    expect(persistCount()).toBe(1);
-
-    const allowed = await dispatch(runner, "mcp__linear__save_issue");
-    expect(allowed.content).toBe("saved");
-    expect(allowed.isError).toBeUndefined();
+    expect(persistCount()).toBe(0);
     expect(
       computeAdvertised(runner.currentDefinitions()).map((d) => d.name),
-    ).toContain("mcp__linear__save_issue");
+    ).toEqual(before);
   });
 
-  test("present and plugin names pass the gate after tool_search promote", async () => {
-    const { runner, search } = wireExecDiscovery();
-    expect((await dispatch(runner, "present")).isError).toBe(true);
-    expect((await dispatch(runner, "plugin__notes__save")).isError).toBe(true);
-
+  test("a subsequent call to a searched-but-not-yet-declared name promotes only that name", async () => {
+    const { runner, search, computeAdvertised } = wireExecDiscovery();
     if (search.kind !== "string") throw new Error("expected string tool");
+    await search.handler({ query: "linear" }, new AbortController().signal);
     await search.handler(
       { query: "render layout" },
       new AbortController().signal,
     );
-    await search.handler(
-      { query: "granola notes" },
-      new AbortController().signal,
+    const afterSearch = computeAdvertised(runner.currentDefinitions()).map(
+      (d) => d.name,
+    );
+    expect(afterSearch).not.toContain("mcp__linear__save_issue");
+    expect(afterSearch).not.toContain("present");
+
+    const allowed = await dispatch(runner, "mcp__linear__save_issue");
+    expect(allowed.content).toBe("saved");
+    expect(allowed.isError).toBeUndefined();
+    const names = computeAdvertised(runner.currentDefinitions()).map(
+      (d) => d.name,
     );
+    expect(names).toContain("mcp__linear__save_issue");
+    expect(names).not.toContain("present");
+    expect(names).not.toContain("plugin__notes__save");
+  });
 
+  test("present and plugin names promote only the called name", async () => {
+    const { runner, computeAdvertised } = wireExecDiscovery();
     expect((await dispatch(runner, "present")).content).toBe("view");
+    expect(
+      computeAdvertised(runner.currentDefinitions()).map((d) => d.name),
+    ).toContain("present");
+    expect(
+      computeAdvertised(runner.currentDefinitions()).map((d) => d.name),
+    ).not.toContain("plugin__notes__save");
+
     expect((await dispatch(runner, "plugin__notes__save")).content).toBe(
       "noted",
     );

src/exec/runner.test.ts

@@ -813,6 +813,7 @@ export async function runExec(config: Config): Promise<ExecResult> {
       computeAdvertised,
       isAdvertised,
       flushPromotions,
+      pruneIdlePromotions,
     } = createAdvertisedToolset({
       sessionMode,
       toolAvailability,
@@ -870,9 +871,9 @@ export async function runExec(config: Config): Promise<ExecResult> {
             ),
           telemetry: liveTelemetry,
           onFolded: () => {
-            // Fold restarts the cached prefix, so catch promotions still
-            // pending. Search already flushed names onto the next infer.
-            if (flushPromotions()) {
+            // Fold restarts the cached prefix — drop idle execute-promoted
+            // schemas rather than carrying them forever.
+            if (pruneIdlePromotions()) {
               directorHolder.instance?.updateToolDefinitions(
                 computeAdvertised(
                   agentToolset.dynamicRunner.currentDefinitions(),
@@ -895,10 +896,9 @@ export async function runExec(config: Config): Promise<ExecResult> {
       evidenceArchiveHolder,
     });
 
-    // tool_search starts as a no-op promoter; without this, the call gate
-    // refuses MCP/present/plugin names the result just told the model to
-    // invoke. Under a closed overlay the promoter only activates allowed
-    // names, so outside-allow tools can never become advertised or callable.
+    // Promote-on-execute: an undeclared registered call declares that one
+    // name, then dispatches. Under a closed overlay the promoter only
+    // activates allowed names, so outside-allow tools stay refused.
     const commitPromotedWire = (): void => {
       if (flushPromotions()) {
         directorHolder.instance?.updateToolDefinitions(