zidane 3.3.6 → 3.4.0

package/README.md

@@ -16,7 +16,7 @@ A small, hookable core with sensible defaults so most consumers don't write a si
 
 - 🧠 **Multi-provider, multi-auth** — Anthropic, OpenAI Codex, OpenRouter, Cerebras, plus a generic `openaiCompat` factory (Baseten, Fireworks, Groq, local servers). OAuth + API key, auto-refreshing tokens. Anthropic accepts opt-in `extraBetas` and `contextManagement` for first-party features.
 - 🪝 **Streaming, hookable turn loop** — text/thinking deltas, tool calls, MCP, sessions, skills, spawn, OAuth, validation, budgets — all observable (and most mutatable) via typed hook events. Per-request `system:transform` hook for runtime-derived prompt sections.
-- 🛠 **Tools first-class** — `shell`, `read_file`, `write_file`, `edit`, `multi_edit`, `glob`, `grep`, `spawn`, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Sequential or parallel, per-call gates (`tool:gate` with writable `block` / `result` / `runToolCounts`), validation auto-coerce (`"true"` → `true`), hallucinated-tool fallback (`tool:unknown`), error rewriting (`tool:error` → `result`).
+- 🛠 **Tools first-class** — `shell`, `read_file`, `write_file`, `edit`, `multi_edit`, `glob`, `grep`, `spawn`, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Sequential or parallel, per-call gates (`tool:gate` with writable `block` / `result` / `runToolCounts`), validation auto-coerce (`"true"` → `true`), hallucinated-tool fallback (`tool:unknown`), error rewriting (`tool:error` → `result`). Optional **progressive disclosure** (`behavior.toolDisclosure: 'lazy'`) hides MCP schemas behind a `tool_search` native tool when context budget matters more than upfront discovery — gated server-side and in-loop so a model can't bypass.
 - ✂️ **Token-aware ergonomics** — paginated reads with a "how to page" footer, 8 KB tail-truncated `shell`, idempotent `write_file`; `outputBytes` surfaced on every tool/MCP hook. `behavior.toolOutputBudget` injects a "summarize" nudge when a turn's outputs exceed the cap; `behavior.toolBudgets` caps per-tool call counts (`'steer'` or `'block'`); `behavior.thinkingDecay` tapers reasoning budget per turn.
 - 🗜 **Context discipline** — auto-injected `cache_control` breakpoints (Anthropic + OpenRouter); server-side compaction via `context-management-2025-06-27` on Anthropic, `behavior.compactStrategy: 'tail'` on everyone else. Per-session `read_file` dedup + opt-in `requireReadBeforeEdit` guard kill stale-content edits; `behavior.dedupTools` generalizes the same pattern to arbitrary tools (`todowrite`, `execute_sql`, …).
 - 🎯 **Reasoning + structured output** — thinking levels (`off` / `minimal` / `low` / `medium` / `high` / `adaptive`) with optional exact budgets; force the final answer to a JSON Schema (Zod v4 interop), no brittle parsing.
@@ -24,8 +24,6 @@ A small, hookable core with sensible defaults so most consumers don't write a si
 - 🧵 **Sub-agents + execution contexts** — delegate to child agents with inherited or overridden preset (child events bubble to the parent); run tools in-process, Docker, or any `SandboxProvider` (E2B / Rivet / custom). Parallel MCP bootstrap with `agent.warmup()` + `eager: true` to hide cold starts.
 - 🧭 **Typed errors + 1000+ tests** — `AgentContextExceededError` / `AgentProviderError` / `AgentAbortedError` instead of sniffing strings. Suite runs in under 2s with mock providers + mock execution contexts, zero API keys.
 
-> Upgrading from 2.x? See [`docs/migrate-from-v2.md`](./docs/migrate-from-v2.md) for the full list of behavior changes.
-
 ## Quickstart
 
 ```bash
@@ -77,6 +75,8 @@ createAgent({
     compactStrategy: 'off',          // client-side tail compaction for non-Anthropic providers — 'off' | 'tail' (default: 'off')
     compactThreshold: 131_072,       // bytes threshold that triggers tail compaction (default: 128 KiB)
     compactKeepTurns: 4,             // trailing turns left intact during compaction (default: 4)
+    toolDisclosure: 'eager',         // 'eager' | 'lazy' — hide MCP schemas behind tool_search (default: 'eager')
+    toolSearch: { tool: true, limit: 20 }, // tune the auto-injected tool_search (no-op in eager mode)
   },
   execution: createProcessContext(), // where tools run
   mcpServers: [],                    // MCP tool servers
@@ -744,13 +744,13 @@ const agent = createAgent({
   provider,
   mcpServers: [
     { name: 'fs', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'], bootstrapTimeout: 10_000 },
-    { name: 'api', transport: 'streamable-http', url: 'http://localhost:3002/mcp' },
+    { name: 'api', transport: 'streamable-http', url: 'http://localhost:3002/mcp', disclosure: 'lazy' },
   ],
 })
 ```
 
 MCP servers can live on a preset too (they're just `AgentOptions` fields). Connections are lazy (first `run()`) and reused.
-Set `bootstrapTimeout` to cap how long a slow `connect + listTools` phase can delay the first model request.
+Set `bootstrapTimeout` to cap how long a slow `connect + listTools` phase can delay the first model request. Per-server `disclosure: 'lazy' | 'eager'` overrides the agent-wide `behavior.toolDisclosure` (see [Progressive tool disclosure](#progressive-tool-disclosure)).
 
 ### Hiding bootstrap latency
 
@@ -785,6 +785,48 @@ agent.hooks.hook('mcp:bootstrap:end', (ctx) => {
 
 Use these to attribute cold-start latency per server — the only way to know if a specific MCP (e.g. a remote GitHub MCP) is the one stretching your first `run()`.
 
+## Progressive tool disclosure
+
+When MCP brings hundreds of tools, every turn ships every schema in the tool list. `behavior.toolDisclosure: 'lazy'` flips MCP tools to a name-only catalog in the system prompt and auto-injects a `tool_search` native tool the model uses to load schemas on demand. Native (non-MCP) tools and skill tools are always eager — only MCP tools are eligible for lazy disclosure.
+
+```ts
+const agent = createAgent({
+  ...basic,
+  provider,
+  mcpServers: [
+    { name: 'github', transport: 'stdio', command: 'gh-mcp' },         // 200+ tools
+    { name: 'fs', transport: 'stdio', command: 'fs-mcp', disclosure: 'eager' }, // override per-server
+  ],
+  behavior: {
+    toolDisclosure: 'lazy',
+    toolSearch: { limit: 20 },                  // default cap on results per call
+  },
+})
+```
+
+The catalog appended to the system prompt looks like:
+
+```
+<searchable_tools>
+  <server name="github">
+    <tool name="mcp_github_search_issues">Search GitHub issues by query.</tool>
+    <tool name="mcp_github_create_pr">Open a pull request.</tool>
+    …
+  </server>
+</searchable_tools>
+```
+
+`tool_search` accepts `query` (substring), `names` (explicit), `server` (bulk-unlock one server), and `limit`. Surfaced tools persist for the rest of the run; the loop rebuilds the wire-level tool list each turn so the next provider call advertises them.
+
+Two hard guarantees:
+
+- **Hard gate.** A `tool:gate` middleware refuses dispatch on lazy tools the model hasn't surfaced yet — production providers already enforce this server-side, but the in-loop gate covers custom / mock / lenient providers and any path where a model quotes a name straight from the catalog. Refusal text points the model at `tool_search` so it self-corrects.
+- **Aliasing-safe.** Catalog and `tool_search` results show the **wire** (`toolAliases`-rewritten) name — the only one the provider accepts. The unlock set is keyed by canonical name so dispatch / `session.turns` / hook contexts stay alias-stable.
+
+Cost model: each `tool_search` call appends to the wire-level tool list, advancing the provider's tool-list cache breakpoint. That costs one cache miss per discovery wave; subsequent turns with the same unlocked set hit cache normally. With many lazy tools and few discovery waves, this still beats eager (which always sends every schema) — but it's not a free optimisation.
+
+Opt out via `behavior.toolSearch.tool: false` (the catalog still emits, the call-to-action prose drops). Pre-existing host tool named `tool_search` shadows the auto-injection — see the JSDoc on `behavior.toolSearch` for the host-defined-tool semantics.
+
 ## Skills
 
 Reusable instruction packages following the [Agent Skills](https://agentskills.io/specification) open standard.

package/dist/{agent-LEf7zjw6.d.ts → agent-CMjWCUPr.d.ts}

@@ -208,6 +208,15 @@ interface McpServerConfig {
         description?: string | null;
         inputSchema?: unknown;
     }) => boolean;
+    /**
+     * Per-server override for {@link AgentBehavior.toolDisclosure}. When set,
+     * this server's tools follow this disclosure mode regardless of the
+     * agent-wide default. Useful when one big MCP server (200+ tools) should
+     * stay lazy while smaller servers stay eager.
+     *
+     * Default: inherits from `behavior.toolDisclosure`.
+     */
+    disclosure?: 'eager' | 'lazy';
 }
 type ToolExecutionMode = 'sequential' | 'parallel';
 interface AgentBehavior {
@@ -464,6 +473,61 @@ interface AgentBehavior {
      * Default: `false`.
      */
     elideStaleReads?: boolean;
+    /**
+     * Tool disclosure strategy. Controls whether the model sees every tool's
+     * full `inputSchema` in its tool list every turn ("eager") or whether MCP
+     * tools are advertised as a name+description catalog in the system prompt
+     * and only get full schemas after being surfaced via the `tool_search`
+     * native tool ("lazy" / progressive disclosure).
+     *
+     * Native tools (those passed to `createAgent({ tools })`) and skill tools
+     * are always eager — they are core to the agent and cheap. Only MCP tools
+     * are eligible for lazy disclosure.
+     *
+     * When `'lazy'`, the agent:
+     * - Appends a `<searchable_tools>` section to the system prompt listing
+     *   every MCP tool by `name` + `description` only (no `inputSchema`).
+     * - Auto-injects a `tool_search` native tool (opt out via
+     *   {@link AgentBehavior.toolSearch}) the model uses to load schemas on
+     *   demand. Surfaced tools persist for the rest of the run.
+     * - Rebuilds the wire-level tool list each turn, appending newly-unlocked
+     *   tools at the end so the prefix-cache breakpoint advances cleanly.
+     *
+     * Trade-off: every `tool_search` invocation expands the tool list and
+     * invalidates the tool-list cache breakpoint for one turn. With many
+     * MCP servers, the savings on cold turns (fewer schemas in context) are
+     * substantial; with one tiny MCP server, the overhead may not pay back.
+     *
+     * Default: `'eager'`.
+     */
+    toolDisclosure?: 'eager' | 'lazy';
+    /**
+     * Fine-grained config for the `tool_search` tool auto-injected when
+     * {@link AgentBehavior.toolDisclosure} is `'lazy'`. No-op in eager mode.
+     *
+     * - `tool: false` — opt out of the auto-injection entirely. Use when the
+     *   host wants to ship a custom discovery tool. Note that the catalog
+     *   text drops the call-to-action prose in this case so the model isn't
+     *   pointed at a non-existent tool.
+     * - `limit` — default cap on results returned per `tool_search` call when
+     *   the model omits the parameter. Default: `20`.
+     *
+     * Note on host-defined `tool_search`: a tool the host registers under the
+     * name `tool_search` (or under any alias whose canonical is `tool_search`)
+     * will shadow the auto-injected one — the catalog text will point at the
+     * host's wire name, but driving the unlock flow requires either using
+     * `createToolSearchTool({ catalog, unlocked })` from `tools/tool-search`
+     * (which internally mutates the unlock set) or fully opting out via
+     * `toolSearch.tool: false` and treating discovery as a host-side concern.
+     * A bare host tool that doesn't touch the unlock set will not advance the
+     * lazy disclosure state and the hard gate will keep refusing lazy calls.
+     *
+     * Default: `undefined` (auto-inject with the default limit).
+     */
+    toolSearch?: {
+        tool?: false;
+        limit?: number;
+    };
 }
 /**
  * One block of a multimodal user prompt.

package/dist/{chunk-X3VOTPVM.js → chunk-6STZTA4N.js}

@@ -251,6 +251,15 @@ function installAllowedToolsGate(hooks, state) {
   };
 }
 
+// src/xml.ts
+var RE_AMP = /&/g;
+var RE_LT = /</g;
+var RE_GT = />/g;
+var RE_QUOT = /"/g;
+function escapeXml(str) {
+  return str.replace(RE_AMP, "&amp;").replace(RE_LT, "&lt;").replace(RE_GT, "&gt;").replace(RE_QUOT, "&quot;");
+}
+
 // src/skills/catalog.ts
 function buildCatalog(skills, options = {}) {
   if (skills.length === 0)
@@ -315,13 +324,6 @@ function buildCatalog(skills, options = {}) {
   }
   return parts.join("\n");
 }
-var RE_AMP = /&/g;
-var RE_LT = /</g;
-var RE_GT = />/g;
-var RE_QUOT = /"/g;
-function escapeXml(str) {
-  return str.replace(RE_AMP, "&amp;").replace(RE_LT, "&lt;").replace(RE_GT, "&gt;").replace(RE_QUOT, "&quot;");
-}
 
 // src/skills/discovery.ts
 import { existsSync, readdirSync, readFileSync, statSync } from "fs";
@@ -814,6 +816,7 @@ export {
   isToolAllowedByUnion,
   IMPLICITLY_ALLOWED_SKILL_TOOLS,
   installAllowedToolsGate,
+  escapeXml,
   buildCatalog,
   parseFrontmatter,
   parseSkillFile,

package/dist/{chunk-LIVB5W4B.js → chunk-JCOB6IYO.js}

@@ -1,6 +1,6 @@
 import {
   validateSkillForWrite
-} from "./chunk-X3VOTPVM.js";
+} from "./chunk-6STZTA4N.js";
 
 // src/skills/index.ts
 function defineSkill(config) {

package/dist/{chunk-OAIKGCZX.js → chunk-VTLEPYND.js}

@@ -1,11 +1,12 @@
 import {
   buildCatalog,
   createSkillActivationState,
+  escapeXml,
   installAllowedToolsGate,
   interpolateShellCommands,
   resolveSkills,
   validateResourcePath
-} from "./chunk-X3VOTPVM.js";
+} from "./chunk-6STZTA4N.js";
 import {
   createProcessContext
 } from "./chunk-UD25QF3H.js";
@@ -1202,13 +1203,6 @@ function createSkillsRunScriptTool(options) {
 
 // src/tools/skills-use.ts
 var MAX_RESOURCE_LIST = 50;
-var AMP_RE = /&/g;
-var LT_RE = /</g;
-var GT_RE = />/g;
-var QUOT_RE = /"/g;
-function escapeXml(str) {
-  return str.replace(AMP_RE, "&amp;").replace(LT_RE, "&lt;").replace(GT_RE, "&gt;").replace(QUOT_RE, "&quot;");
-}
 function buildSkillContentWrapper(skill, body) {
   const parts = [];
   parts.push(`<skill_content name="${escapeXml(skill.name)}" spec_version="0.1">`);
@@ -1812,10 +1806,11 @@ async function executeTurn(ctx, turn) {
     sanitizedMessages = applyTailCompaction(sanitizedMessages, threshold, keep);
   }
   const effectiveThinkingBudget = applyThinkingDecay(ctx.thinkingBudget, ctx.thinkingDecay, turn);
+  const formattedTools = ctx.rebuildFormattedTools ? ctx.rebuildFormattedTools() : ctx.formattedTools;
   const streamOptions = {
     model: ctx.model,
     system: ctx.system,
-    tools: ctx.formattedTools,
+    tools: formattedTools,
     messages: sanitizedMessages,
     maxTokens: ctx.maxTokens ?? 16384,
     thinking: ctx.thinking,
@@ -2350,6 +2345,154 @@ function defaultBlockMessage(tool, max) {
   return `Tool '${tool}' has reached its per-run budget of ${max} calls; further invocations are refused.`;
 }
 
+// src/tools/tool-search.ts
+var DEFAULT_LIMIT2 = 20;
+function rankByQuery(catalog, query) {
+  const q = query.trim().toLowerCase();
+  if (!q)
+    return [...catalog];
+  const nameHits = [];
+  const descHits = [];
+  for (const entry of catalog) {
+    if (entry.name.toLowerCase().includes(q))
+      nameHits.push(entry);
+    else if (entry.description.toLowerCase().includes(q))
+      descHits.push(entry);
+  }
+  return [...nameHits, ...descHits];
+}
+function sanitiseSchemaForXml(schemaJson) {
+  return schemaJson.replace(/</g, "\\u003c");
+}
+function formatMatch(entry) {
+  const schema = sanitiseSchemaForXml(JSON.stringify(entry.inputSchema));
+  const serverAttr = entry.server ? ` server="${escapeXml(entry.server)}"` : "";
+  return [
+    `  <tool name="${escapeXml(entry.name)}"${serverAttr}>`,
+    `    <description>${escapeXml(entry.description)}</description>`,
+    `    <input_schema>${schema}</input_schema>`,
+    `  </tool>`
+  ].join("\n");
+}
+function createToolSearchTool(options) {
+  const defaultLimit = options.defaultLimit ?? DEFAULT_LIMIT2;
+  const byName = new Map(options.catalog.map((e) => [e.name, e]));
+  const byServer = /* @__PURE__ */ new Map();
+  for (const entry of options.catalog) {
+    if (!entry.server)
+      continue;
+    const list = byServer.get(entry.server) ?? [];
+    list.push(entry);
+    byServer.set(entry.server, list);
+  }
+  const maxLimit = Math.max(options.catalog.length, 1);
+  return {
+    spec: {
+      name: "tool_search",
+      description: "Discover and load schemas for additional tools listed in <searchable_tools>. Tools listed there are advertised by name + description only \u2014 their input schemas are not loaded into context until you surface them through this tool. Pass `query` for a substring search, `names` to load specific tools, or `server` to load every tool from one MCP server. Returned tools become callable for the rest of this run.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Substring to match against tool name + description (case-insensitive)."
+          },
+          names: {
+            type: "array",
+            items: { type: "string" },
+            description: "Explicit tool names to load (bypasses ranking). Use the names shown in <searchable_tools>."
+          },
+          server: {
+            type: "string",
+            description: "MCP server name \u2014 load every tool from this server."
+          },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            description: `Cap on returned matches. Default: ${defaultLimit}.`
+          }
+        },
+        additionalProperties: false
+      }
+    },
+    async execute(input, ctx) {
+      if (ctx.signal?.aborted)
+        return '<tool_search_results matches="0" aborted="true">Run aborted.</tool_search_results>';
+      const rawQuery = typeof input.query === "string" ? input.query.trim() : void 0;
+      const query = rawQuery || void 0;
+      const namesIn = Array.isArray(input.names) ? input.names.filter((n) => typeof n === "string" && n.length > 0) : void 0;
+      const server = typeof input.server === "string" && input.server.length > 0 ? input.server : void 0;
+      const limitIn = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0 ? Math.floor(input.limit) : defaultLimit;
+      const limit = Math.min(limitIn, maxLimit);
+      if (options.catalog.length === 0)
+        return '<tool_search_results matches="0">No lazy tools registered for this run.</tool_search_results>';
+      const matches = [];
+      const seen = /* @__PURE__ */ new Set();
+      const misses = [];
+      if (namesIn && namesIn.length > 0) {
+        for (const n of namesIn) {
+          if (seen.has(n))
+            continue;
+          const entry = byName.get(n);
+          if (entry) {
+            matches.push(entry);
+            seen.add(n);
+          } else {
+            misses.push(n);
+          }
+        }
+      }
+      if (server) {
+        const list = byServer.get(server) ?? [];
+        for (const entry of list) {
+          if (seen.has(entry.name))
+            continue;
+          matches.push(entry);
+          seen.add(entry.name);
+        }
+      }
+      if (query !== void 0) {
+        for (const entry of rankByQuery(options.catalog, query)) {
+          if (seen.has(entry.name))
+            continue;
+          matches.push(entry);
+          seen.add(entry.name);
+        }
+      }
+      if (!namesIn?.length && !server && query === void 0) {
+        for (const entry of options.catalog) {
+          matches.push(entry);
+          seen.add(entry.name);
+        }
+      }
+      const truncated = matches.length > limit;
+      const shown = truncated ? matches.slice(0, limit) : matches;
+      for (const entry of shown)
+        options.unlocked.add(entry.canonicalName);
+      const parts = [];
+      const queryAttr = query ? ` query="${escapeXml(query)}"` : "";
+      const serverAttr = server ? ` server="${escapeXml(server)}"` : "";
+      parts.push(`<tool_search_results matches="${shown.length}" total="${matches.length}"${queryAttr}${serverAttr}>`);
+      if (shown.length === 0) {
+        parts.push("  No matches. Try a broader query, or omit all parameters to list everything.");
+      } else {
+        for (const entry of shown)
+          parts.push(formatMatch(entry));
+        parts.push("");
+        parts.push("  These tools are now callable. Invoke them by name in subsequent turns.");
+        if (truncated) {
+          parts.push(`  ${matches.length - shown.length} additional matches were truncated \u2014 refine the query or raise \`limit\`.`);
+        }
+      }
+      if (misses.length > 0) {
+        parts.push(`  <misses>${misses.map(escapeXml).join(", ")}</misses>`);
+      }
+      parts.push("</tool_search_results>");
+      return parts.join("\n");
+    }
+  };
+}
+
 // src/agent.ts
 var HOOK_EVENT_NAMES = [
   "system:before",
@@ -2429,9 +2572,103 @@ function resolveBehavior(agentBehavior, runBehavior) {
     requireReadBeforeEdit: runBehavior?.requireReadBeforeEdit ?? agentBehavior?.requireReadBeforeEdit,
     toolBudgets: runBehavior?.toolBudgets ?? agentBehavior?.toolBudgets,
     readLineNumbers: runBehavior?.readLineNumbers ?? agentBehavior?.readLineNumbers,
-    elideStaleReads: runBehavior?.elideStaleReads ?? agentBehavior?.elideStaleReads
+    elideStaleReads: runBehavior?.elideStaleReads ?? agentBehavior?.elideStaleReads,
+    toolDisclosure: runBehavior?.toolDisclosure ?? agentBehavior?.toolDisclosure ?? "eager",
+    toolSearch: runBehavior?.toolSearch ?? agentBehavior?.toolSearch
   };
 }
+function resolveServerForTool(toolName, servers) {
+  if (!servers || servers.length === 0)
+    return void 0;
+  let best;
+  let bestLen = -1;
+  for (const server of servers) {
+    const prefix = `mcp_${server.name}_`;
+    if (toolName.startsWith(prefix) && server.name.length > bestLen) {
+      best = server;
+      bestLen = server.name.length;
+    }
+  }
+  return best;
+}
+function partitionToolDisclosure(toolsBySpecName, mcpToolNames, servers, globalMode, toolAliases) {
+  const eagerCanonicalNames = /* @__PURE__ */ new Set();
+  const lazyCanonicalNames = /* @__PURE__ */ new Set();
+  const lazyEntries = [];
+  function wireFor(canonical) {
+    const aliased = toolAliases?.[canonical];
+    return typeof aliased === "string" && aliased.length > 0 ? aliased : canonical;
+  }
+  for (const [canonicalName, def] of Object.entries(toolsBySpecName)) {
+    if (!mcpToolNames.has(canonicalName)) {
+      eagerCanonicalNames.add(canonicalName);
+      continue;
+    }
+    const server = resolveServerForTool(canonicalName, servers);
+    const mode = server?.disclosure ?? globalMode;
+    if (mode === "lazy") {
+      lazyCanonicalNames.add(canonicalName);
+      lazyEntries.push({
+        name: wireFor(canonicalName),
+        canonicalName,
+        description: def.spec.description || "",
+        inputSchema: def.spec.inputSchema ?? { type: "object", properties: {} },
+        ...server ? { server: server.name } : {}
+      });
+    } else {
+      eagerCanonicalNames.add(canonicalName);
+    }
+  }
+  return { eagerCanonicalNames, lazyCanonicalNames, lazyEntries };
+}
+function buildSearchableCatalog(entries, options) {
+  const byServer = /* @__PURE__ */ new Map();
+  const ungrouped = [];
+  for (const entry of entries) {
+    if (!entry.server) {
+      ungrouped.push(entry);
+      continue;
+    }
+    const list = byServer.get(entry.server) ?? [];
+    list.push(entry);
+    byServer.set(entry.server, list);
+  }
+  const serverNames = [...byServer.keys()].sort();
+  const parts = [];
+  if (options.discoveryToolName) {
+    parts.push(
+      "The following tools are available but their input schemas are NOT loaded in your context.",
+      `Call the \`${options.discoveryToolName}\` tool to load schemas before invoking them. Surfaced tools persist for the rest of the run.`,
+      ""
+    );
+  }
+  parts.push("<searchable_tools>");
+  for (const server of serverNames) {
+    parts.push(`  <server name="${escapeXml(server)}">`);
+    for (const entry of byServer.get(server))
+      parts.push(`    <tool name="${escapeXml(entry.name)}">${escapeXml(entry.description)}</tool>`);
+    parts.push("  </server>");
+  }
+  for (const entry of ungrouped)
+    parts.push(`  <tool name="${escapeXml(entry.name)}">${escapeXml(entry.description)}</tool>`);
+  parts.push("</searchable_tools>");
+  return parts.join("\n");
+}
+function installLazyDisclosureGate(hooks, lazyCanonicalNames, unlocked, discoveryToolName) {
+  if (lazyCanonicalNames.size === 0)
+    return () => {
+    };
+  return hooks.hook("tool:gate", (ctx) => {
+    if (ctx.block)
+      return;
+    if (!lazyCanonicalNames.has(ctx.name))
+      return;
+    if (unlocked.has(ctx.name))
+      return;
+    ctx.block = true;
+    ctx.reason = discoveryToolName ? `Tool "${ctx.name}" is listed in <searchable_tools> but its schema has not been loaded. Call the \`${discoveryToolName}\` tool with names: ["${ctx.name}"] first, then re-issue the call.` : `Tool "${ctx.name}" is listed in <searchable_tools> but its schema has not been loaded.`;
+  });
+}
 function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager }) {
   const hooks = createHooks();
   const executionContext = execution ?? createProcessContext();
@@ -2557,7 +2794,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
     const thinking = options.thinking ?? "off";
     const model = options.model ?? provider.meta.defaultModel;
     const resolvedBehavior = resolveBehavior(agentBehavior, options.behavior);
-    const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget, compactStrategy, compactThreshold, compactKeepTurns, thinkingDecay, dedupTools, toolBudgets, elideStaleReads } = resolvedBehavior;
+    const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget, compactStrategy, compactThreshold, compactKeepTurns, thinkingDecay, dedupTools, toolBudgets, elideStaleReads, toolDisclosure, toolSearch } = resolvedBehavior;
     let system = options.system || agentSystem || "You are a helpful assistant.";
     if (skillsCatalog) {
       system = `${system}
@@ -2565,6 +2802,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 ${skillsCatalog}`;
     }
     const runBaseTools = options.tools !== void 0 ? options.tools : mcpConnection ? { ...sourceTools, ...mcpConnection.tools } : sourceTools;
+    const mcpToolNames = options.tools === void 0 && mcpConnection ? new Set(Object.keys(mcpConnection.tools)) : /* @__PURE__ */ new Set();
     const shouldInjectSkillTools = options.tools === void 0 && !!resolvedSkills && resolvedSkills.length > 0 && skillsConfig?.tool !== false;
     const mergedWithSkills = shouldInjectSkillTools ? {
       // Auto-injected first so agent + MCP tools can override by name.
@@ -2584,19 +2822,51 @@ ${skillsCatalog}`;
       }),
       ...runBaseTools
     } : runBaseTools;
-    const tools = {};
+    const toolsPreSearch = {};
     for (const tool of Object.values(mergedWithSkills)) {
-      tools[tool.spec.name] = tool;
+      toolsPreSearch[tool.spec.name] = tool;
+    }
+    const disclosure = partitionToolDisclosure(toolsPreSearch, mcpToolNames, mcpServers, toolDisclosure, toolAliases);
+    const unlocked = new Set(disclosure.eagerCanonicalNames);
+    const hostDefinedToolSearch = !!toolsPreSearch.tool_search;
+    const shouldInjectToolSearch = disclosure.lazyEntries.length > 0 && toolSearch?.tool !== false && !hostDefinedToolSearch;
+    let tools = toolsPreSearch;
+    if (shouldInjectToolSearch) {
+      const toolSearchTool = createToolSearchTool({
+        catalog: disclosure.lazyEntries,
+        unlocked,
+        ...toolSearch?.limit !== void 0 ? { defaultLimit: toolSearch.limit } : {}
+      });
+      tools = { ...toolsPreSearch, [toolSearchTool.spec.name]: toolSearchTool };
+      unlocked.add(toolSearchTool.spec.name);
+    }
+    const discoveryToolName = shouldInjectToolSearch ? "tool_search" : hostDefinedToolSearch ? toolAliases?.tool_search ?? "tool_search" : null;
+    if (disclosure.lazyEntries.length > 0) {
+      system = `${system}
+
+${buildSearchableCatalog(disclosure.lazyEntries, { discoveryToolName })}`;
     }
     const aliasMaps = buildAliasMaps(toolAliases, Object.keys(tools));
-    const toolSpecs = Object.values(tools).map(
-      (t) => ({
-        name: aliasMaps.aliasByCanonical.get(t.spec.name) ?? t.spec.name,
-        description: t.spec.description || "",
-        inputSchema: t.spec.inputSchema
-      })
+    const uninstallLazyDisclosureGate = installLazyDisclosureGate(
+      hooks,
+      disclosure.lazyCanonicalNames,
+      unlocked,
+      discoveryToolName
     );
-    const formattedTools = toolSpecs.length > 0 ? provider.formatTools(toolSpecs) : [];
+    function buildFormattedTools() {
+      const specs = [];
+      for (const t of Object.values(tools)) {
+        if (!unlocked.has(t.spec.name))
+          continue;
+        specs.push({
+          name: aliasMaps.aliasByCanonical.get(t.spec.name) ?? t.spec.name,
+          description: t.spec.description || "",
+          inputSchema: t.spec.inputSchema
+        });
+      }
+      return specs.length > 0 ? provider.formatTools(specs) : [];
+    }
+    const formattedTools = buildFormattedTools();
     const turns = [];
     const isResume = session && session.turns.length > 0 && (session.runs.length > 0 || !options.prompt);
     if (isResume) {
@@ -2685,6 +2955,7 @@ ${skillsCatalog}`;
         agentBehavior: resolvedBehavior,
         tools,
         formattedTools,
+        rebuildFormattedTools: disclosure.lazyEntries.length > 0 ? buildFormattedTools : void 0,
         aliasMaps,
         model,
         system,
@@ -2756,6 +3027,7 @@ ${skillsCatalog}`;
       uninstallAllowedToolsGate();
       uninstallDedupTools();
       uninstallToolBudgets();
+      uninstallLazyDisclosureGate();
       unregisterSpawnHook();
       unregisterSessionSync?.();
       for (const unregister of perRunUnregisters)
@@ -3200,6 +3472,7 @@ export {
   createSkillsReadTool,
   createSkillsRunScriptTool,
   createSkillsUseTool,
+  createToolSearchTool,
   createAgent,
   edit,
   glob,

package/dist/{chunk-CZQGCVMH.js → chunk-WE4C6AQE.js}

@@ -6,7 +6,7 @@ import {
   readFile,
   shell,
   writeFile
-} from "./chunk-OAIKGCZX.js";
+} from "./chunk-VTLEPYND.js";
 
 // src/presets/basic.ts
 var basicTools = { shell, readFile, writeFile, listFiles, edit, multiEdit };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { d as AgentHooks } from './agent-LEf7zjw6.js';
-export { ab as ActivationVia, ac as ActiveSkill, A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, ad as DeactivationReason, ae as FileMapAdapter, af as FileMapStoreOptions, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, ag as OpenAICompatAuthHeader, ah as OpenAICompatHttpError, ai as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, aj as SkillActivationState, ak as SkillActivationStateOptions, J as SkillConfig, al as SkillDiagnostic, K as SkillResource, am as SkillSource, L as SkillsConfig, N as SpawnHookContext, Q as StreamCallbacks, T as StreamHookContext, U as StreamOptions, V as ThinkingLevel, W as ToolCall, X as ToolContext, Y as ToolDef, Z as ToolExecutionMode, _ as ToolHookContext, $ as ToolMap, a0 as ToolResult, a1 as ToolResultContent, a2 as ToolResultImageContent, a3 as ToolResultTextContent, a4 as ToolSpec, a5 as TurnFinishReason, a6 as TurnResult, a7 as TurnUsage, an as anthropic, ao as autoDetectAndConvert, ap as cerebras, aq as classifyOpenAICompatError, ar as connectMcpServers, as as createAgent, at as createFileMapStore, au as createMemoryStore, av as createRemoteStore, aw as createSession, ax as createSkillActivationState, ay as fromAnthropic, az as fromOpenAI, aA as loadSession, aB as mapOAIFinishReason, a8 as matchesContextExceeded, aC as normalizeMcpBlocks, aD as normalizeMcpServers, aE as openai, aF as openaiCompat, aG as openrouter, aH as resultToString, aI as toAnthropic, aJ as toOpenAI, aK as toTypedError, a9 as toolOutputByteLength, aa as toolResultToText } from './agent-LEf7zjw6.js';
+import { d as AgentHooks } from './agent-CMjWCUPr.js';
+export { ab as ActivationVia, ac as ActiveSkill, A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, ad as DeactivationReason, ae as FileMapAdapter, af as FileMapStoreOptions, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, ag as OpenAICompatAuthHeader, ah as OpenAICompatHttpError, ai as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, aj as SkillActivationState, ak as SkillActivationStateOptions, J as SkillConfig, al as SkillDiagnostic, K as SkillResource, am as SkillSource, L as SkillsConfig, N as SpawnHookContext, Q as StreamCallbacks, T as StreamHookContext, U as StreamOptions, V as ThinkingLevel, W as ToolCall, X as ToolContext, Y as ToolDef, Z as ToolExecutionMode, _ as ToolHookContext, $ as ToolMap, a0 as ToolResult, a1 as ToolResultContent, a2 as ToolResultImageContent, a3 as ToolResultTextContent, a4 as ToolSpec, a5 as TurnFinishReason, a6 as TurnResult, a7 as TurnUsage, an as anthropic, ao as autoDetectAndConvert, ap as cerebras, aq as classifyOpenAICompatError, ar as connectMcpServers, as as createAgent, at as createFileMapStore, au as createMemoryStore, av as createRemoteStore, aw as createSession, ax as createSkillActivationState, ay as fromAnthropic, az as fromOpenAI, aA as loadSession, aB as mapOAIFinishReason, a8 as matchesContextExceeded, aC as normalizeMcpBlocks, aD as normalizeMcpServers, aE as openai, aF as openaiCompat, aG as openrouter, aH as resultToString, aI as toAnthropic, aJ as toOpenAI, aK as toTypedError, a9 as toolOutputByteLength, aa as toolResultToText } from './agent-CMjWCUPr.js';
 export { createDockerContext, createProcessContext } from './contexts.js';
 export { S as SandboxProvider, c as createSandboxContext } from './sandbox-CLghrTLi.js';
 export { C as ContextCapabilities, a as ContextType, E as ExecResult, b as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-vA1a_ZX7.js';
 export { Preset, basic, basicTools, definePreset } from './presets.js';
 export { IMPLICITLY_ALLOWED_SKILL_TOOLS, SkillValidationIssue, SkillValidationResult, SourcedScanPath, buildCatalog, defineSkill, discoverSkills, installAllowedToolsGate, interpolateShellCommands, isToolAllowedByUnion, matchesAllowedTool, parseAllowedToolPattern, parseSkillFile, resolveSkills, validateResourcePath, validateSkillForWrite, validateSkillName, writeSkillToDisk, writeSkillsToDisk } from './skills.js';
-export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-CVxdV6Tq.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-C4Ucr2wT.js';
+export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-6oJKUjk_.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-BWV_pCdO.js';
 import { Hookable } from 'hookable';
 import '@modelcontextprotocol/sdk/client/index.js';
 

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   defineSkill
-} from "./chunk-LIVB5W4B.js";
+} from "./chunk-JCOB6IYO.js";
 import {
   anthropic,
   cerebras,
@@ -11,7 +11,7 @@ import {
   basicTools,
   basic_default,
   definePreset
-} from "./chunk-CZQGCVMH.js";
+} from "./chunk-WE4C6AQE.js";
 import {
   createAgent,
   createInteractionTool,
@@ -24,7 +24,7 @@ import {
   grep,
   multiEdit,
   validateToolArgs
-} from "./chunk-OAIKGCZX.js";
+} from "./chunk-VTLEPYND.js";
 import {
   IMPLICITLY_ALLOWED_SKILL_TOOLS,
   buildCatalog,
@@ -42,7 +42,7 @@ import {
   validateSkillName,
   writeSkillToDisk,
   writeSkillsToDisk
-} from "./chunk-X3VOTPVM.js";
+} from "./chunk-6STZTA4N.js";
 import {
   createDockerContext,
   createProcessContext,

package/dist/mcp.d.ts

@@ -1,4 +1,4 @@
 import '@modelcontextprotocol/sdk/client/index.js';
 import 'hookable';
-export { M as McpConnection, p as McpServerConfig, ar as connectMcpServers, aC as normalizeMcpBlocks, aD as normalizeMcpServers, aH as resultToString } from './agent-LEf7zjw6.js';
+export { M as McpConnection, p as McpServerConfig, ar as connectMcpServers, aC as normalizeMcpBlocks, aD as normalizeMcpServers, aH as resultToString } from './agent-CMjWCUPr.js';
 import './types-vA1a_ZX7.js';

package/dist/presets.d.ts

@@ -1,4 +1,4 @@
-import { Y as ToolDef, e as AgentOptions } from './agent-LEf7zjw6.js';
+import { Y as ToolDef, e as AgentOptions } from './agent-CMjWCUPr.js';
 import 'hookable';
 import './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/presets.js

@@ -2,9 +2,9 @@ import {
   basicTools,
   basic_default,
   definePreset
-} from "./chunk-CZQGCVMH.js";
-import "./chunk-OAIKGCZX.js";
-import "./chunk-X3VOTPVM.js";
+} from "./chunk-WE4C6AQE.js";
+import "./chunk-VTLEPYND.js";
+import "./chunk-6STZTA4N.js";
 import "./chunk-UD25QF3H.js";
 import "./chunk-7GQ7P6DM.js";
 import "./chunk-JH6IAAFA.js";

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-export { j as AnthropicParams, k as CerebrasParams, ag as OpenAICompatAuthHeader, ah as OpenAICompatHttpError, ai as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, w as Provider, x as ProviderCapabilities, Q as StreamCallbacks, U as StreamOptions, W as ToolCall, a0 as ToolResult, a4 as ToolSpec, a6 as TurnResult, an as anthropic, ap as cerebras, aq as classifyOpenAICompatError, aB as mapOAIFinishReason, aE as openai, aF as openaiCompat, aG as openrouter } from './agent-LEf7zjw6.js';
+export { j as AnthropicParams, k as CerebrasParams, ag as OpenAICompatAuthHeader, ah as OpenAICompatHttpError, ai as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, w as Provider, x as ProviderCapabilities, Q as StreamCallbacks, U as StreamOptions, W as ToolCall, a0 as ToolResult, a4 as ToolSpec, a6 as TurnResult, an as anthropic, ap as cerebras, aq as classifyOpenAICompatError, aB as mapOAIFinishReason, aE as openai, aF as openaiCompat, aG as openrouter } from './agent-CMjWCUPr.js';
 import 'hookable';
 import './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/session/sqlite.d.ts

@@ -1,4 +1,4 @@
-import { H as SessionStore } from '../agent-LEf7zjw6.js';
+import { H as SessionStore } from '../agent-CMjWCUPr.js';
 import 'hookable';
 import '../types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-export { o as CreateSessionOptions, ae as FileMapAdapter, af as FileMapStoreOptions, R as RemoteStoreOptions, S as Session, z as SessionContentBlock, B as SessionData, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, ao as autoDetectAndConvert, at as createFileMapStore, au as createMemoryStore, av as createRemoteStore, aw as createSession, ay as fromAnthropic, az as fromOpenAI, aA as loadSession, aI as toAnthropic, aJ as toOpenAI } from './agent-LEf7zjw6.js';
+export { o as CreateSessionOptions, ae as FileMapAdapter, af as FileMapStoreOptions, R as RemoteStoreOptions, S as Session, z as SessionContentBlock, B as SessionData, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, ao as autoDetectAndConvert, at as createFileMapStore, au as createMemoryStore, av as createRemoteStore, aw as createSession, ay as fromAnthropic, az as fromOpenAI, aA as loadSession, aI as toAnthropic, aJ as toOpenAI } from './agent-CMjWCUPr.js';
 import 'hookable';
 import './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/{skills-use-CVxdV6Tq.d.ts → skills-use-6oJKUjk_.d.ts}

@@ -1,4 +1,4 @@
-import { Y as ToolDef, J as SkillConfig, aj as SkillActivationState, d as AgentHooks } from './agent-LEf7zjw6.js';
+import { Y as ToolDef, J as SkillConfig, aj as SkillActivationState, d as AgentHooks } from './agent-CMjWCUPr.js';
 import { Hookable } from 'hookable';
 
 /**

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
-import { d as AgentHooks, aj as SkillActivationState, J as SkillConfig, am as SkillSource, al as SkillDiagnostic, L as SkillsConfig } from './agent-LEf7zjw6.js';
-export { ab as ActivationVia, ac as ActiveSkill, ad as DeactivationReason, ak as SkillActivationStateOptions, K as SkillResource, ax as createSkillActivationState } from './agent-LEf7zjw6.js';
+import { d as AgentHooks, aj as SkillActivationState, J as SkillConfig, am as SkillSource, al as SkillDiagnostic, L as SkillsConfig } from './agent-CMjWCUPr.js';
+export { ab as ActivationVia, ac as ActiveSkill, ad as DeactivationReason, ak as SkillActivationStateOptions, K as SkillResource, ax as createSkillActivationState } from './agent-CMjWCUPr.js';
 import { Hookable } from 'hookable';
 import { b as ExecutionContext, c as ExecutionHandle } from './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/skills.js

@@ -1,6 +1,6 @@
 import {
   defineSkill
-} from "./chunk-LIVB5W4B.js";
+} from "./chunk-JCOB6IYO.js";
 import {
   IMPLICITLY_ALLOWED_SKILL_TOOLS,
   buildCatalog,
@@ -21,7 +21,7 @@ import {
   validateSkillName,
   writeSkillToDisk,
   writeSkillsToDisk
-} from "./chunk-X3VOTPVM.js";
+} from "./chunk-6STZTA4N.js";
 import "./chunk-LNN5UTS2.js";
 export {
   IMPLICITLY_ALLOWED_SKILL_TOOLS,

package/dist/tools.d.ts

@@ -1,7 +1,7 @@
-export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-CVxdV6Tq.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-C4Ucr2wT.js';
-import { Y as ToolDef } from './agent-LEf7zjw6.js';
-export { X as ToolContext, $ as ToolMap } from './agent-LEf7zjw6.js';
+export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-6oJKUjk_.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-BWV_pCdO.js';
+import { Y as ToolDef } from './agent-CMjWCUPr.js';
+export { X as ToolContext, $ as ToolMap } from './agent-CMjWCUPr.js';
 import 'hookable';
 import './presets.js';
 import './types-vA1a_ZX7.js';
@@ -13,6 +13,68 @@ declare const readFile: ToolDef;
 
 declare const shell: ToolDef;
 
+/**
+ * `tool_search` — progressive tool disclosure.
+ *
+ * Counterpart to `skills_use` for the MCP tool surface: the catalog (name +
+ * description) lives in the system prompt; full `inputSchema` payloads load
+ * lazily through this tool. After a successful match, the matched tools'
+ * canonical names are added to the per-run "unlocked" set and become callable
+ * immediately (the loop rebuilds `formattedTools` before the next provider
+ * request, advertising the unlocked tools to the provider).
+ *
+ * Aliasing: the tool advertises and matches on the **wire** (alias-rewritten)
+ * name — the only name the model ever sees. Internally each lazy entry also
+ * carries its `canonicalName`, which is what gets added to the `unlocked` set
+ * (the loop's tool registry is keyed by canonical name).
+ *
+ * Result shape: structured pseudo-XML wrapping a JSON `inputSchema` payload.
+ * The schema is inlined verbatim (NOT XML-escaped) so the model can reuse it
+ * directly when constructing arguments — escaping the JSON would force the
+ * model to mentally un-escape `"` etc. when reasoning about field types.
+ */
+
+interface LazyToolEntry {
+    /**
+     * Wire name (after `toolAliases` rewrite). What the model sees in the
+     * catalog, what `tool_search` matches against, and what the provider's
+     * tool list will carry once the entry is unlocked.
+     */
+    name: string;
+    /**
+     * Canonical (registry-key) name used for unlock-set membership and for the
+     * loop's `ctx.tools[name]` dispatch lookup. Equal to `name` when no alias
+     * is configured for this tool.
+     */
+    canonicalName: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** Source MCP server, when applicable. Used for `server`-bulk unlock. */
+    server?: string;
+}
+interface ToolSearchToolOptions {
+    /**
+     * Snapshot of every lazy tool the model can discover. Built once per run by
+     * the agent — the tool closes over this array and never mutates it.
+     */
+    catalog: readonly LazyToolEntry[];
+    /**
+     * Mutable per-run set of unlocked **canonical** tool names. The tool adds
+     * matches in place; the loop reads the set when rebuilding the wire-level
+     * tool list. Keyed by canonical (not wire) so dispatch lookups stay
+     * alias-stable.
+     */
+    unlocked: Set<string>;
+    /** Default cap on returned matches when the model omits `limit`. */
+    defaultLimit?: number;
+}
+/**
+ * Factory for `tool_search`. Auto-injected by the agent when
+ * `behavior.toolDisclosure === 'lazy'` and at least one MCP tool is in the
+ * registry. Opt out via `behavior.toolSearch.tool === false`.
+ */
+declare function createToolSearchTool(options: ToolSearchToolOptions): ToolDef;
+
 /**
  * Write a file, with an idempotency signal when the content is unchanged.
  *
@@ -30,4 +92,4 @@ declare const shell: ToolDef;
  */
 declare const writeFile: ToolDef;
 
-export { ToolDef, listFiles, readFile, shell, writeFile };
+export { type LazyToolEntry, ToolDef, type ToolSearchToolOptions, createToolSearchTool, listFiles, readFile, shell, writeFile };

package/dist/tools.js

@@ -4,6 +4,7 @@ import {
   createSkillsRunScriptTool,
   createSkillsUseTool,
   createSpawnTool,
+  createToolSearchTool,
   edit,
   glob,
   grep,
@@ -13,8 +14,8 @@ import {
   shell,
   validateToolArgs,
   writeFile
-} from "./chunk-OAIKGCZX.js";
-import "./chunk-X3VOTPVM.js";
+} from "./chunk-VTLEPYND.js";
+import "./chunk-6STZTA4N.js";
 import "./chunk-UD25QF3H.js";
 import "./chunk-7GQ7P6DM.js";
 import "./chunk-JH6IAAFA.js";
@@ -25,6 +26,7 @@ export {
   createSkillsRunScriptTool,
   createSkillsUseTool,
   createSpawnTool,
+  createToolSearchTool,
   edit,
   glob,
   grep,

package/dist/types.d.ts

@@ -1,7 +1,7 @@
-export { A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, d as AgentHooks, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, l as ChildRunStats, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, J as SkillConfig, K as SkillResource, L as SkillsConfig, N as SpawnHookContext, Q as StreamCallbacks, T as StreamHookContext, U as StreamOptions, V as ThinkingLevel, W as ToolCall, X as ToolContext, Y as ToolDef, Z as ToolExecutionMode, _ as ToolHookContext, $ as ToolMap, a0 as ToolResult, a1 as ToolResultContent, a2 as ToolResultImageContent, a3 as ToolResultTextContent, a4 as ToolSpec, a5 as TurnFinishReason, a6 as TurnResult, a7 as TurnUsage, a8 as matchesContextExceeded, a9 as toolOutputByteLength, aa as toolResultToText } from './agent-LEf7zjw6.js';
+export { A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, d as AgentHooks, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, l as ChildRunStats, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, J as SkillConfig, K as SkillResource, L as SkillsConfig, N as SpawnHookContext, Q as StreamCallbacks, T as StreamHookContext, U as StreamOptions, V as ThinkingLevel, W as ToolCall, X as ToolContext, Y as ToolDef, Z as ToolExecutionMode, _ as ToolHookContext, $ as ToolMap, a0 as ToolResult, a1 as ToolResultContent, a2 as ToolResultImageContent, a3 as ToolResultTextContent, a4 as ToolSpec, a5 as TurnFinishReason, a6 as TurnResult, a7 as TurnUsage, a8 as matchesContextExceeded, a9 as toolOutputByteLength, aa as toolResultToText } from './agent-CMjWCUPr.js';
 export { C as ContextCapabilities, a as ContextType, E as ExecResult, b as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-vA1a_ZX7.js';
 export { S as SandboxProvider } from './sandbox-CLghrTLi.js';
 export { Preset } from './presets.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult } from './validation-C4Ucr2wT.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult } from './validation-BWV_pCdO.js';
 import 'hookable';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/{validation-C4Ucr2wT.d.ts → validation-BWV_pCdO.d.ts}

@@ -1,4 +1,4 @@
-import { X as ToolContext, Y as ToolDef, h as AgentStats, l as ChildRunStats } from './agent-LEf7zjw6.js';
+import { X as ToolContext, Y as ToolDef, h as AgentStats, l as ChildRunStats } from './agent-CMjWCUPr.js';
 import { Preset } from './presets.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "3.3.6",
+  "version": "3.4.0",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,