@anuma/sdk 6.12.0 → 6.13.0

package/dist/expo/index.cjs

@@ -19670,6 +19670,20 @@ function clientToolToCompletionsFormat(tool) {
 }
 var TOOL_SEARCH_TOOL_TYPE = "tool_search_tool_regex_20251119";
 var TOOL_SEARCH_TOOL_NAME = "tool_search_tool_regex";
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
+function deferFormattingConfig(serverToolsFilter, config) {
+  if (!config?.enabled) return config;
+  const isExplicitList = serverToolsFilter !== void 0 && typeof serverToolsFilter !== "function";
+  return isExplicitList ? void 0 : config;
+}
 function byNameAscending(a, b) {
   if (a.name < b.name) return -1;
   if (a.name > b.name) return 1;
@@ -19996,7 +20010,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -20014,6 +20028,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -21014,7 +21032,11 @@ function useChatStorage(options) {
               cache: serverToolsConfig?.cache
             });
             if (serverToolsConfig?.deferLoading?.enabled) {
-              filteredServerTools2 = allServerTools;
+              filteredServerTools2 = resolveDeferredServerTools(
+                allServerTools,
+                serverToolsFilter,
+                serverToolsConfig.deferLoading
+              );
             } else if (isServerToolsFunction2) {
               if (messageContent.length >= MIN_CONTENT_LENGTH_FOR_TOOLS) {
                 skipUserEmbedding = await embedToolText(
@@ -21073,7 +21095,7 @@ function useChatStorage(options) {
             filteredServerTools2,
             narrowedClientTools2,
             effectiveApiType2,
-            serverToolsConfig?.deferLoading
+            deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
           );
         }
         if (onToolSelection) {
@@ -21286,7 +21308,11 @@ function useChatStorage(options) {
           if ("error" in settledTools) throw settledTools.error;
           const allServerTools = settledTools.tools;
           if (serverToolsConfig?.deferLoading?.enabled && effectiveApiType === "responses") {
-            filteredServerTools = allServerTools;
+            filteredServerTools = resolveDeferredServerTools(
+              allServerTools,
+              serverToolsFilter,
+              serverToolsConfig.deferLoading
+            );
           } else if (isServerToolsFunction) {
             if (contentForStorage.length >= MIN_CONTENT_LENGTH_FOR_TOOLS) {
               const settledEmbedding = await (userMessageEmbeddingPromise ?? embedForToolsSettled(getTokenRef.current));
@@ -21306,7 +21332,7 @@ function useChatStorage(options) {
               filteredServerTools,
               clientTools,
               effectiveApiType,
-              serverToolsConfig?.deferLoading
+              deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
             );
           }
         } catch (error) {
@@ -21347,7 +21373,7 @@ function useChatStorage(options) {
             filteredServerTools,
             narrowedClientTools,
             effectiveApiType,
-            serverToolsConfig?.deferLoading
+            deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
           ) : void 0;
         } catch (error) {
           getLogger().warn("[useChatStorage] client tool filtering failed:", error);

package/dist/expo/index.d.mts

@@ -3308,6 +3308,22 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
 /**
  * A tool set defines a group of tools that work together. When any "anchor"

package/dist/expo/index.d.ts

@@ -3308,6 +3308,22 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
 /**
  * A tool set defines a group of tools that work together. When any "anchor"

package/dist/expo/index.mjs

@@ -9962,6 +9962,20 @@ function clientToolToCompletionsFormat(tool) {
 }
 var TOOL_SEARCH_TOOL_TYPE = "tool_search_tool_regex_20251119";
 var TOOL_SEARCH_TOOL_NAME = "tool_search_tool_regex";
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
+function deferFormattingConfig(serverToolsFilter, config) {
+  if (!config?.enabled) return config;
+  const isExplicitList = serverToolsFilter !== void 0 && typeof serverToolsFilter !== "function";
+  return isExplicitList ? void 0 : config;
+}
 function byNameAscending(a, b) {
   if (a.name < b.name) return -1;
   if (a.name > b.name) return 1;
@@ -10288,7 +10302,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -10306,6 +10320,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -11305,7 +11323,11 @@ function useChatStorage(options) {
               cache: serverToolsConfig?.cache
             });
             if (serverToolsConfig?.deferLoading?.enabled) {
-              filteredServerTools2 = allServerTools;
+              filteredServerTools2 = resolveDeferredServerTools(
+                allServerTools,
+                serverToolsFilter,
+                serverToolsConfig.deferLoading
+              );
             } else if (isServerToolsFunction2) {
               if (messageContent.length >= MIN_CONTENT_LENGTH_FOR_TOOLS) {
                 skipUserEmbedding = await embedToolText(
@@ -11364,7 +11386,7 @@ function useChatStorage(options) {
             filteredServerTools2,
             narrowedClientTools2,
             effectiveApiType2,
-            serverToolsConfig?.deferLoading
+            deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
           );
         }
         if (onToolSelection) {
@@ -11577,7 +11599,11 @@ function useChatStorage(options) {
           if ("error" in settledTools) throw settledTools.error;
           const allServerTools = settledTools.tools;
           if (serverToolsConfig?.deferLoading?.enabled && effectiveApiType === "responses") {
-            filteredServerTools = allServerTools;
+            filteredServerTools = resolveDeferredServerTools(
+              allServerTools,
+              serverToolsFilter,
+              serverToolsConfig.deferLoading
+            );
           } else if (isServerToolsFunction) {
             if (contentForStorage.length >= MIN_CONTENT_LENGTH_FOR_TOOLS) {
               const settledEmbedding = await (userMessageEmbeddingPromise ?? embedForToolsSettled(getTokenRef.current));
@@ -11597,7 +11623,7 @@ function useChatStorage(options) {
               filteredServerTools,
               clientTools,
               effectiveApiType,
-              serverToolsConfig?.deferLoading
+              deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
             );
           }
         } catch (error) {
@@ -11638,7 +11664,7 @@ function useChatStorage(options) {
             filteredServerTools,
             narrowedClientTools,
             effectiveApiType,
-            serverToolsConfig?.deferLoading
+            deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
           ) : void 0;
         } catch (error) {
           getLogger().warn("[useChatStorage] client tool filtering failed:", error);

package/dist/index.cjs

@@ -2293,7 +2293,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -2311,6 +2311,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",

package/dist/index.d.mts

@@ -7900,7 +7900,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -7941,7 +7941,21 @@ declare const DEFAULT_SERVER_TOOLS_MATCH_OPTIONS: ToolMatchOptions;
  * If you need to customize (extra excludes, different limits, opt into
  * tool-set expansion), call `createServerToolsFilter` directly.
  */
-declare const defaultServerToolsFilter: (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
+/**
+ * Type for a server-tools filter — a function that takes prompt embeddings
+ * and the full server tool catalog and returns the names of tools to keep.
+ * Matches `useChatStorage`'s `serverTools` callback signature.
+ */
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for selectServerSideTools
  */

package/dist/index.d.ts

@@ -7900,7 +7900,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -7941,7 +7941,21 @@ declare const DEFAULT_SERVER_TOOLS_MATCH_OPTIONS: ToolMatchOptions;
  * If you need to customize (extra excludes, different limits, opt into
  * tool-set expansion), call `createServerToolsFilter` directly.
  */
-declare const defaultServerToolsFilter: (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
+/**
+ * Type for a server-tools filter — a function that takes prompt embeddings
+ * and the full server tool catalog and returns the names of tools to keep.
+ * Matches `useChatStorage`'s `serverTools` callback signature.
+ */
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for selectServerSideTools
  */

package/dist/index.mjs

@@ -2091,7 +2091,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -2109,6 +2109,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",

package/dist/react/index.cjs

@@ -21700,6 +21700,20 @@ function clientToolToCompletionsFormat(tool) {
 }
 var TOOL_SEARCH_TOOL_TYPE = "tool_search_tool_regex_20251119";
 var TOOL_SEARCH_TOOL_NAME = "tool_search_tool_regex";
+function resolveDeferredServerTools(allServerTools, serverToolsFilter, config) {
+  const allowed = serverToolsFilter === void 0 || typeof serverToolsFilter === "function" ? allServerTools : filterServerTools(allServerTools, [...serverToolsFilter]);
+  const excluded = new Set(config.excludeTools ?? []);
+  if (typeof serverToolsFilter === "function") {
+    for (const name of serverToolsFilter.excludeTools ?? []) excluded.add(name);
+  }
+  if (excluded.size === 0) return allowed;
+  return allowed.filter((tool) => !excluded.has(tool.name));
+}
+function deferFormattingConfig(serverToolsFilter, config) {
+  if (!config?.enabled) return config;
+  const isExplicitList = serverToolsFilter !== void 0 && typeof serverToolsFilter !== "function";
+  return isExplicitList ? void 0 : config;
+}
 function byNameAscending(a, b) {
   if (a.name < b.name) return -1;
   if (a.name > b.name) return 1;
@@ -22026,7 +22040,7 @@ function createServerToolsFilter(options = {}) {
   const exclude = new Set(options.excludeTools ?? []);
   const sets = options.toolSets ?? [];
   const matchOpts = options.matchOptions;
-  return (embeddings, tools) => {
+  const filter = (embeddings, tools) => {
     const matches = findMatchingTools(embeddings, tools, matchOpts);
     if (matches.length === 0) return [];
     const matchedNames = new Set(matches.map((m) => m.tool.name));
@@ -22044,6 +22058,10 @@ function createServerToolsFilter(options = {}) {
     for (const name of exclude) finalNames.delete(name);
     return [...finalNames];
   };
+  return Object.defineProperty(filter, "excludeTools", {
+    value: Object.freeze([...exclude]),
+    enumerable: false
+  });
 }
 var DEFAULT_EXCLUDED_SERVER_TOOLS = [
   "AnumaVisionMCP-anuma_analyze_image",
@@ -22125,7 +22143,8 @@ async function selectServerToolsForPrompt(options) {
     return [];
   }
   if (allServerTools.length === 0) return [];
-  if (deferLoading?.enabled) return allServerTools;
+  if (deferLoading?.enabled)
+    return resolveDeferredServerTools(allServerTools, serverToolsFilter, deferLoading);
   if (typeof serverToolsFilter === "function") {
     if (prompt.length < MIN_CONTENT_LENGTH_FOR_TOOLS) return [];
     let promptEmbedding;
@@ -22556,7 +22575,8 @@ async function previewToolSelection(options) {
           cache: serverToolsConfig?.cache
         });
         const allow = new Set(serverToolsFilter);
-        gatedServerNames = allServerTools.filter((t) => allow.has(t.name)).map((t) => t.name);
+        const gated = allServerTools.filter((t) => allow.has(t.name));
+        gatedServerNames = (serverToolsConfig?.deferLoading?.enabled ? resolveDeferredServerTools(gated, serverToolsFilter, serverToolsConfig.deferLoading) : gated).map((t) => t.name);
       } catch {
       }
     }
@@ -22605,7 +22625,11 @@ async function previewToolSelection(options) {
         cache: serverToolsConfig?.cache
       });
       if (serverToolsConfig?.deferLoading?.enabled) {
-        serverToolNames = allServerTools.map((t) => t.name);
+        serverToolNames = resolveDeferredServerTools(
+          allServerTools,
+          serverToolsFilter,
+          serverToolsConfig.deferLoading
+        ).map((t) => t.name);
       } else if (typeof serverToolsFilter === "function") {
         serverToolNames = serverToolsFilter(promptEmbedding, allServerTools);
       } else {
@@ -23621,7 +23645,11 @@ function useChatStorage(options) {
               cache: serverToolsConfig?.cache
             });
             if (serverToolsConfig?.deferLoading?.enabled) {
-              filteredServerTools2 = allServerTools;
+              filteredServerTools2 = resolveDeferredServerTools(
+                allServerTools,
+                serverToolsFilter,
+                serverToolsConfig.deferLoading
+              );
             } else if (isServerToolsFunction2) {
               if (skipStorageEmbeddings) {
                 const toolNames = serverToolsFilter(skipStorageEmbeddings, allServerTools);
@@ -23662,7 +23690,7 @@ function useChatStorage(options) {
             filteredServerTools2,
             filteredClientTools2,
             effectiveApiType2,
-            serverToolsConfig?.deferLoading
+            deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
           );
         }
         if (onToolSelection) {
@@ -24021,7 +24049,11 @@ function useChatStorage(options) {
         if (allServerTools) {
           try {
             if (serverToolsConfig?.deferLoading?.enabled && effectiveApiType === "responses") {
-              filteredServerTools = allServerTools;
+              filteredServerTools = resolveDeferredServerTools(
+                allServerTools,
+                serverToolsFilter,
+                serverToolsConfig.deferLoading
+              );
             } else if (isServerToolsFunction) {
               if (userMessageEmbeddings) {
                 const toolNames = serverToolsFilter(userMessageEmbeddings, allServerTools);
@@ -24101,7 +24133,7 @@ function useChatStorage(options) {
           filteredServerTools,
           filteredClientTools,
           effectiveApiType,
-          serverToolsConfig?.deferLoading
+          deferFormattingConfig(serverToolsFilter, serverToolsConfig?.deferLoading)
         );
       }
       if (onToolSelection) {

package/dist/react/index.d.mts

@@ -4465,6 +4465,22 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
 /**
  * Result of tool matching with similarity score
@@ -4642,7 +4658,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -4708,13 +4724,21 @@ declare const SERVER_TOOL_DEPENDENCY_SETS: ToolSet[];
  * If you need to customize (extra excludes, different limits, opt into
  * tool-set expansion), call `createServerToolsFilter` directly.
  */
-declare const defaultServerToolsFilter: (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
 /**
  * Type for a server-tools filter — a function that takes prompt embeddings
  * and the full server tool catalog and returns the names of tools to keep.
  * Matches `useChatStorage`'s `serverTools` callback signature.
  */
-type ServerToolsFilterFunction = (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for `selectServerToolsForPrompt`.
  */
@@ -4742,9 +4766,10 @@ interface SelectServerToolsForPromptOptions {
      */
     cache?: ToolsCacheBackend;
     /**
-     * Phase 3 defer-loading. When `enabled`, this helper returns the FULL catalog (skipping semantic/
-     * static filtering) to mirror useChatStorage's responses send path, which swaps in the full catalog
-     * for mergeTools + tool-search. Omit/disabled → today's filtered selection.
+     * Phase 3 defer-loading. When `enabled`, this helper skips SEMANTIC filtering to mirror
+     * useChatStorage's responses send path, which hands the catalog to mergeTools + tool-search. The
+     * caller's unconditional constraints still apply — an explicit static array, and exclusions (see
+     * {@link resolveDeferredServerTools}). Omit/disabled → today's filtered selection.
      */
     deferLoading?: DeferLoadingConfig;
 }

package/dist/react/index.d.ts

@@ -4465,6 +4465,22 @@ interface DeferLoadingConfig {
     enabled: boolean;
     /** Server-tool names to keep non-deferred (besides the tool-search tool), in priority order. */
     hotToolNames: readonly string[];
+    /**
+     * Server-tool names to drop entirely while defer-loading is on.
+     *
+     * Defer widens the per-turn selection to the whole catalog, which also bypasses the `excludeTools`
+     * baked into a caller's semantic filter. A filter built by {@link createServerToolsFilter} tags itself
+     * with its own exclusions and those are honoured automatically — so most callers need nothing here.
+     *
+     * Set this when the filter's tag can't be seen: a hand-written filter, a filter wrapped in a plain
+     * closure (the wrapper drops the tag), or a static-array `serverToolsFilter`. Anything excluded
+     * UNCONDITIONALLY (a tool the app replaces with its own UI, a capability the model already has
+     * natively) belongs in one of the two places, or defer quietly hands it back to the model.
+     *
+     * This list is UNIONED with the filter's own tag, never a replacement for it — so adding one name
+     * here cannot re-admit the tools the filter already excludes.
+     */
+    excludeTools?: readonly string[];
 }
 /**
  * Result of tool matching with similarity score
@@ -4642,7 +4658,7 @@ interface CreateServerToolsFilterOptions {
  * });
  * ```
  */
-declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare function createServerToolsFilter(options?: CreateServerToolsFilterOptions): ServerToolsFilterFunction;
 /**
  * Default exclusions baked into `defaultServerToolsFilter`.
  *
@@ -4708,13 +4724,21 @@ declare const SERVER_TOOL_DEPENDENCY_SETS: ToolSet[];
  * If you need to customize (extra excludes, different limits, opt into
  * tool-set expansion), call `createServerToolsFilter` directly.
  */
-declare const defaultServerToolsFilter: (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+declare const defaultServerToolsFilter: ServerToolsFilterFunction;
 /**
  * Type for a server-tools filter — a function that takes prompt embeddings
  * and the full server tool catalog and returns the names of tools to keep.
  * Matches `useChatStorage`'s `serverTools` callback signature.
  */
-type ServerToolsFilterFunction = (embeddings: number[] | number[][], tools: ServerTool[]) => string[];
+type ServerToolsFilterFunction = ((embeddings: number[] | number[][], tools: ServerTool[]) => string[]) & {
+    /**
+     * The unconditional exclusions this filter applies, exposed by
+     * {@link createServerToolsFilter} so defer-loading can honour them without the caller
+     * repeating the list — see {@link resolveDeferredServerTools}. Absent on a hand-written
+     * filter, or on one wrapped in a plain closure.
+     */
+    readonly excludeTools?: readonly string[];
+};
 /**
  * Options for `selectServerToolsForPrompt`.
  */
@@ -4742,9 +4766,10 @@ interface SelectServerToolsForPromptOptions {
      */
     cache?: ToolsCacheBackend;
     /**
-     * Phase 3 defer-loading. When `enabled`, this helper returns the FULL catalog (skipping semantic/
-     * static filtering) to mirror useChatStorage's responses send path, which swaps in the full catalog
-     * for mergeTools + tool-search. Omit/disabled → today's filtered selection.
+     * Phase 3 defer-loading. When `enabled`, this helper skips SEMANTIC filtering to mirror
+     * useChatStorage's responses send path, which hands the catalog to mergeTools + tool-search. The
+     * caller's unconditional constraints still apply — an explicit static array, and exclusions (see
+     * {@link resolveDeferredServerTools}). Omit/disabled → today's filtered selection.
      */
     deferLoading?: DeferLoadingConfig;
 }