@agent-native/core 0.145.3 → 0.145.4

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7850
+- template files: 7851

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -907,14 +907,16 @@ export default createAgentChatPlugin({
   durableBackgroundRuns: true,
   runSoftTimeoutMs: ANALYTICS_BACKGROUND_RUN_SOFT_TIMEOUT_MS,
   runNoProgressTimeoutMs: ANALYTICS_BACKGROUND_RUN_NO_PROGRESS_TIMEOUT_MS,
-  connectorCatalog: [...ANALYTICS_CONNECTOR_CATALOG],
-  externalAgents: {
-    // Keep the direct MCP surface deliberately curated. External agents
-    // should use ask_app by default; cataloged actions are optional stable
-    // semantic reads for callers with an exact, fully known contract. They are
-    // never a fallback for slow or failed delegation.
-    authenticatedReads: "off",
-    writes: "ask_app_only",
+  mcp: {
+    connectorCatalog: [...ANALYTICS_CONNECTOR_CATALOG],
+    externalAgents: {
+      // Keep the direct MCP surface deliberately curated. External agents
+      // should use ask_app by default; cataloged actions are optional stable
+      // semantic reads for callers with an exact, fully known contract. They
+      // are never a fallback for slow or failed delegation.
+      authenticatedReads: "off",
+      writes: "ask_app_only",
+    },
   },
   resolveOrgId: async (event) => {
     const ctx = await getOrgContext(event);

package/corpus/templates/assets/server/plugins/agent-chat.ts

@@ -34,7 +34,7 @@ const INITIAL_TOOL_NAMES = [
 
 export default createAgentChatPlugin({
   appId: "assets",
-  mcpServerInfo: {
+  mcp: {
     title: "Agent-Native Assets",
     description:
       "Create, search, select, and export brand image and video assets from Assets.",

package/corpus/templates/calendar/server/plugins/agent-chat.ts

@@ -90,7 +90,7 @@ export default createAgentChatPlugin({
   // background worker, as content, slides and analytics already do.
   durableBackgroundRuns: true,
   initialToolNames: INITIAL_TOOL_NAMES,
-  connectorCatalog: [...CALENDAR_CONNECTOR_CATALOG],
+  mcp: { connectorCatalog: [...CALENDAR_CONNECTOR_CATALOG] },
   // Enable sandboxed JavaScript execution so Calendar agents can fetch,
   // paginate, and reduce provider data through providerFetch() without us
   // hardcoding one action per Google Calendar / CRM endpoint.

package/corpus/templates/clips/desktop/src/lib/media-capture-constraints.ts

@@ -2,6 +2,7 @@ import {
   chooseFallbackAudioInput,
   enumerateAudioInputDevices,
   isLikelyPhoneMicLabel,
+  normalizedMediaDeviceId,
   type AudioInputFallback,
 } from "../../../shared/media-device-selection";
 
@@ -204,7 +205,27 @@ export async function getAudioStreamWithFallback(
     const stream = await getVoiceFocusedAudioStream(id);
     return id ? stream : replacePhoneDefaultMicIfPossible(stream);
   } catch (err) {
-    if (!isMediaConstraintFailure(err)) throw err;
+    let deviceGone = false;
+    if (id && err instanceof DOMException && err.name === "NotAllowedError") {
+      try {
+        deviceGone = !(await enumerateAudioInputDevices()).some(
+          (device) => normalizedMediaDeviceId(device.deviceId) === id,
+        );
+      } catch (enumerateErr) {
+        console.warn(
+          "[clips-recorder] could not confirm saved mic is still present after NotAllowedError",
+          enumerateErr,
+        );
+        deviceGone = true;
+      }
+    }
+    if (deviceGone) {
+      console.warn(
+        "[clips-recorder] saved mic no longer enumerated after NotAllowedError; falling back",
+        { deviceId: id },
+      );
+    }
+    if (!isMediaConstraintFailure(err) && !deviceGone) throw err;
     if (id) {
       const fallback = await tryFallbackAudioInput(savedLabel, [id]);
       if (fallback) return fallback;

package/corpus/templates/mail/server/plugins/agent-chat.ts

@@ -40,7 +40,7 @@ export default createAgentChatPlugin({
   // background worker, as content, slides and analytics already do.
   durableBackgroundRuns: true,
   initialToolNames: INITIAL_TOOL_NAMES,
-  connectorCatalog: [...MAIL_CONNECTOR_CATALOG],
+  mcp: { connectorCatalog: [...MAIL_CONNECTOR_CATALOG] },
   resolveOrgId: async (event) => {
     const ctx = await getOrgContext(event);
     return ctx.orgId;

package/corpus/templates/plan/server/lib/plan-framework-tools.ts

@@ -0,0 +1,11 @@
+import type { FrameworkToolsConfig } from "@agent-native/core/server";
+
+/**
+ * Framework tool policy shared by Plan's two mounts.
+ *
+ * Plan serves MCP from a dedicated early plugin (`plugins/00-mcp.ts`) rather
+ * than the agent-chat plugin, so the policy has to live somewhere both can
+ * read. Setting it in only one place is how an app ends up advertising a tool
+ * over MCP that its own agent no longer has.
+ */
+export const PLAN_FRAMEWORK_TOOLS: FrameworkToolsConfig = {};

package/corpus/templates/plan/server/plugins/00-mcp.ts

@@ -1,77 +1,16 @@
 import { mountMCP } from "@agent-native/core/mcp";
 import {
+  attachToolSearch,
+  filterFrameworkToolGroups,
   loadActionsFromStaticRegistry,
-  type ActionEntry,
+  resolveFrameworkTools,
 } from "@agent-native/core/server";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { createAutomationToolEntries } from "@agent-native/core/triggers";
 
 import actionsRegistry from "../../.generated/actions-registry.js";
 import { PLAN_CONNECTOR_CATALOG } from "../lib/plan-connector-catalog.js";
-
-const TOOL_SEARCH_ACTION_NAME = "tool-search";
-
-function attachPlanToolSearch(
-  registry: Record<string, ActionEntry>,
-): Record<string, ActionEntry> {
-  const searchableNames = new Set(PLAN_CONNECTOR_CATALOG);
-  registry[TOOL_SEARCH_ACTION_NAME] = {
-    tool: {
-      description:
-        "Discover callable Plan MCP tools by name and description. Omit query to list the visible Plan connector surface; pass query to filter by capability.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: {
-            type: "string",
-            description:
-              "Optional search text, e.g. create plan, share resource, or comments.",
-          },
-          limit: {
-            type: "number",
-            description: "Maximum results to return. Defaults to 8.",
-          },
-        },
-      },
-    },
-    http: false,
-    readOnly: true,
-    run: async (args: { query?: unknown; limit?: unknown } = {}) => {
-      const query = String(args.query ?? "")
-        .trim()
-        .toLowerCase();
-      const rawLimit = Number(args.limit);
-      const limit =
-        Number.isFinite(rawLimit) && rawLimit > 0
-          ? Math.min(Math.floor(rawLimit), 25)
-          : 8;
-      const results = Object.entries(registry)
-        .filter(([name, entry]) => {
-          if (name === TOOL_SEARCH_ACTION_NAME) return false;
-          if (!searchableNames.has(name)) return false;
-          const description = entry.tool.description ?? "";
-          if (!query) return true;
-          return `${name} ${description}`.toLowerCase().includes(query);
-        })
-        .slice(0, query ? limit : 100)
-        .map(([name, entry]) => ({
-          name,
-          description: entry.tool.description ?? name,
-          readOnly: entry.readOnly === true,
-        }));
-
-      return {
-        query,
-        totalTools: Object.keys(registry).filter((name) =>
-          searchableNames.has(name),
-        ).length,
-        count: results.length,
-        results,
-      };
-    },
-  };
-  return registry;
-}
+import { PLAN_FRAMEWORK_TOOLS } from "../lib/plan-framework-tools.js";
 
 function requireMcpOwner(operation: string): string {
   const owner = getRequestUserEmail();
@@ -84,11 +23,29 @@ function requireMcpOwner(operation: string): string {
 }
 
 export default function planMcpPlugin(nitroApp: any) {
-  const actions = attachPlanToolSearch({
-    ...loadActionsFromStaticRegistry(actionsRegistry),
-    ...createAutomationToolEntries(() => requireMcpOwner("manage automations")),
+  // This mount deliberately bypasses the agent-chat plugin so the external
+  // connector does not wait on chat initialization — which means it has to
+  // apply the framework tool policy itself. Reading the same
+  // `PLAN_FRAMEWORK_TOOLS` the chat plugin does is what keeps the two mounts
+  // from disagreeing about which tools exist.
+  const frameworkTools = resolveFrameworkTools({
+    frameworkTools: PLAN_FRAMEWORK_TOOLS,
   });
 
+  const actions = attachToolSearch(
+    filterFrameworkToolGroups(
+      {
+        ...loadActionsFromStaticRegistry(actionsRegistry),
+        ...(frameworkTools.isEnabled("automation")
+          ? createAutomationToolEntries(() =>
+              requireMcpOwner("manage automations"),
+            )
+          : {}),
+      },
+      frameworkTools.disabledGroups,
+    ),
+  );
+
   mountMCP(nitroApp, {
     name: "Plan",
     title: "Agent-Native Plan",

package/corpus/templates/plan/server/plugins/agent-chat.ts

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import actionsRegistry from "../../.generated/actions-registry.js";
 import { PLAN_CONNECTOR_CATALOG } from "../lib/plan-connector-catalog.js";
+import { PLAN_FRAMEWORK_TOOLS } from "../lib/plan-framework-tools.js";
 import { resolvePlanAnonymousOwner } from "../lib/public-plans.js";
 
 const PLAN_BACKGROUND_RUN_SOFT_TIMEOUT_MS = 13 * 60_000;
@@ -130,8 +131,13 @@ const planAgentChatOptions = {
   initialToolNames: INITIAL_TOOL_NAMES,
   anonymousOwner: resolvePlanAnonymousOwner,
   resolveOrgId: async (event) => (await getOrgContext(event)).orgId,
-  connectorCatalog: PLAN_CONNECTOR_CATALOG,
-  disableMcp: true,
+  frameworkTools: PLAN_FRAMEWORK_TOOLS,
+  mcp: {
+    // Plan mounts MCP from a dedicated early plugin (`00-mcp.ts`) so its
+    // external connector does not wait on chat plugin initialization.
+    enabled: false,
+    connectorCatalog: PLAN_CONNECTOR_CATALOG,
+  },
   durableBackgroundRuns: true,
   runSoftTimeoutMs: PLAN_BACKGROUND_RUN_SOFT_TIMEOUT_MS,
 };

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/framework-tools.d.ts

@@ -103,18 +103,50 @@ export interface ResolvedFrameworkTools {
  * "why can't the agent see db-query" report ends up unexplainable.
  */
 export declare function resolveFrameworkTools(input: FrameworkToolsInput | undefined): ResolvedFrameworkTools;
+/**
+ * Which `frameworkTools` switch owns each framework action kit.
+ *
+ * This map is the authority. `ActionEntry.frameworkGroup` is an optional
+ * pre-resolved copy of the same answer, not a requirement: it is stamped only
+ * by `mergeCoreSharingActions`, which runs against the ungated `httpActions`
+ * registry, so for a year every app loading core kits through
+ * `loadActionsFromStaticRegistry` or its own actions directory carried
+ * untagged entries and silently ignored eight of the `frameworkTools`
+ * switches. Resolve by name and the switch works no matter how the action was
+ * registered.
+ *
+ * Membership does two jobs: one filter subtracts a whole kit from every agent
+ * tool surface at once (the plugin spreads these registries at thirteen
+ * composition sites), and it keeps these ~45 schemas out of the DEFAULT
+ * first-request tool list. They stay reachable through `tool-search`.
+ *
+ * Anything absent from this map is always-on and must be listed in
+ * `ALWAYS_ON_CORE_ACTIONS` instead. `action-discovery.spec.ts` fails when a new
+ * core action appears in neither, so "always-on" stays a decision someone made
+ * rather than the default that happens when a map goes un-updated.
+ */
+export declare const CORE_ACTION_GROUPS: Record<string, FrameworkToolGroup>;
 /** Structural view of the one field these helpers read, so tagging utilities
  *  stay free of an import cycle with `ActionEntry`. */
 interface FrameworkGrouped {
     frameworkGroup?: FrameworkToolGroup;
 }
+/**
+ * Which group owns an action, by name first and tag second.
+ *
+ * Name first because the name is present on every registration path, while the
+ * tag is stamped on exactly one — an app is not less entitled to its
+ * `frameworkTools` switches because it loaded core kits from a generated
+ * registry instead of `autoDiscoverActions`.
+ */
+export declare function resolveFrameworkGroup(name: string, entry: FrameworkGrouped | undefined): FrameworkToolGroup | undefined;
 /**
  * Drop every action belonging to a disabled group. Returns the input untouched
  * when nothing is disabled so the default path allocates nothing.
  */
 export declare function filterFrameworkToolGroups<T extends FrameworkGrouped>(actions: Record<string, T>, disabledGroups: ReadonlySet<FrameworkToolGroup>): Record<string, T>;
 /** True for actions the framework contributes rather than the app's own. */
-export declare function isFrameworkGroupedAction(entry: FrameworkGrouped): boolean;
+export declare function isFrameworkGroupedAction(name: string, entry: FrameworkGrouped | undefined): boolean;
 /**
  * Whether a group is live, for prompt builders that only receive the disabled
  * set. Prompt text and tool schemas must agree: a prompt that names a tool the

package/dist/framework-tools.js

@@ -88,6 +88,88 @@ export function resolveFrameworkTools(input) {
         isEnabled: (group) => !disabledGroups.has(group),
     };
 }
+/**
+ * Which `frameworkTools` switch owns each framework action kit.
+ *
+ * This map is the authority. `ActionEntry.frameworkGroup` is an optional
+ * pre-resolved copy of the same answer, not a requirement: it is stamped only
+ * by `mergeCoreSharingActions`, which runs against the ungated `httpActions`
+ * registry, so for a year every app loading core kits through
+ * `loadActionsFromStaticRegistry` or its own actions directory carried
+ * untagged entries and silently ignored eight of the `frameworkTools`
+ * switches. Resolve by name and the switch works no matter how the action was
+ * registered.
+ *
+ * Membership does two jobs: one filter subtracts a whole kit from every agent
+ * tool surface at once (the plugin spreads these registries at thirteen
+ * composition sites), and it keeps these ~45 schemas out of the DEFAULT
+ * first-request tool list. They stay reachable through `tool-search`.
+ *
+ * Anything absent from this map is always-on and must be listed in
+ * `ALWAYS_ON_CORE_ACTIONS` instead. `action-discovery.spec.ts` fails when a new
+ * core action appears in neither, so "always-on" stays a decision someone made
+ * rather than the default that happens when a map goes un-updated.
+ */
+export const CORE_ACTION_GROUPS = {
+    "share-resource": "sharing",
+    "unshare-resource": "sharing",
+    "list-resource-shares": "sharing",
+    "set-resource-visibility": "sharing",
+    "create-agent-resource-link": "sharing",
+    "get-feature-flags": "featureFlags",
+    "list-feature-flags": "featureFlags",
+    "set-feature-flag": "featureFlags",
+    "list-recurring-jobs": "automation",
+    "manage-recurring-job": "automation",
+    "run-automation-now": "automation",
+    "list-automation-runs": "automation",
+    "list-automations": "automation",
+    "manage-automation": "automation",
+    "context-manifest-get": "contextXray",
+    "context-preview-get": "contextXray",
+    "context-pin": "contextXray",
+    "context-evict": "contextXray",
+    "context-restore": "contextXray",
+    "context-report": "contextXray",
+    "get-localization-preference": "localization",
+    "set-localization-preference": "localization",
+    // Profile, credentials, and appearance share one switch: an app that hides
+    // its profile surface from the agent hides password management with it.
+    "get-user-profile": "userProfile",
+    "update-user-profile": "userProfile",
+    "get-auth-methods": "userProfile",
+    "set-password": "userProfile",
+    "change-password": "userProfile",
+    "change-appearance": "userProfile",
+    "list-audit-events": "audit",
+    "get-audit-event": "audit",
+    "export-audit-events": "audit",
+    "create-resource-version": "history",
+    "list-resource-versions": "history",
+    "get-resource-version": "history",
+    "restore-resource-version": "history",
+    "list-resource-history": "history",
+    "list-review-comments": "review",
+    "create-review-comment": "review",
+    "reply-review-comment": "review",
+    "resolve-review-thread": "review",
+    "delete-review-comment": "review",
+    "consume-review-feedback": "review",
+    "get-review-feedback": "review",
+    "set-review-status": "review",
+    "send-review-thread-to-agent": "review",
+};
+/**
+ * Which group owns an action, by name first and tag second.
+ *
+ * Name first because the name is present on every registration path, while the
+ * tag is stamped on exactly one — an app is not less entitled to its
+ * `frameworkTools` switches because it loaded core kits from a generated
+ * registry instead of `autoDiscoverActions`.
+ */
+export function resolveFrameworkGroup(name, entry) {
+    return entry?.frameworkGroup ?? CORE_ACTION_GROUPS[name];
+}
 /**
  * Drop every action belonging to a disabled group. Returns the input untouched
  * when nothing is disabled so the default path allocates nothing.
@@ -95,12 +177,14 @@ export function resolveFrameworkTools(input) {
 export function filterFrameworkToolGroups(actions, disabledGroups) {
     if (disabledGroups.size === 0)
         return actions;
-    return Object.fromEntries(Object.entries(actions).filter(([, entry]) => entry.frameworkGroup === undefined ||
-        !disabledGroups.has(entry.frameworkGroup)));
+    return Object.fromEntries(Object.entries(actions).filter(([name, entry]) => {
+        const group = resolveFrameworkGroup(name, entry);
+        return group === undefined || !disabledGroups.has(group);
+    }));
 }
 /** True for actions the framework contributes rather than the app's own. */
-export function isFrameworkGroupedAction(entry) {
-    return entry.frameworkGroup !== undefined;
+export function isFrameworkGroupedAction(name, entry) {
+    return resolveFrameworkGroup(name, entry) !== undefined;
 }
 /**
  * Whether a group is live, for prompt builders that only receive the disabled

package/dist/mcp/build-server.d.ts

@@ -71,6 +71,21 @@ export interface MCPConfig {
      * a constrained / locked-down mount.
      */
     builtinCrossAppTools?: boolean;
+    /**
+     * `"app"` serves exactly the app's own tool registry, flat: every action the
+     * in-app agent holds, and nothing the in-app agent does not — no cross-app
+     * builtins, no `ask-agent`, no `tool-search`, and no compact/connector
+     * trimming. `connectorCatalog`, the compact default, and the
+     * `--full-catalog` / `AGENT_NATIVE_MCP_FULL_CATALOG` opt-ins are all inert
+     * on this mode; `externalAgents.denyActions` and the OAuth scope filter
+     * still apply, because both are explicit removals rather than tiering.
+     *
+     * The dev-open surface split is deliberately NOT bypassed: an
+     * unauthenticated loopback probe still gets `actions`, not
+     * `productionActions`. Parity is with the app's agent for a real
+     * authenticated caller, not an escalation for anonymous ones.
+     */
+    catalogMode?: "app";
     /**
      * Curated allow-list of action names served to **external connector** clients
      * on a hosted multi-tenant deployment.

package/dist/mcp/build-server.js

@@ -142,6 +142,41 @@ function isActionVisibleForOAuthScope(entry, scopes) {
     const required = entry.readOnly === true ? "mcp:read" : "mcp:write";
     return hasMcpOAuthScope(scopes, required);
 }
+/** Mirrors `TOOL_SEARCH_ACTION_NAME`; not imported, because `agent/tool-search.ts`
+ *  reaches Node-only request context and this module must stay bundleable. */
+const TOOL_SEARCH_TOOL_NAME = "tool-search";
+function withoutToolSearch(actions) {
+    if (!(TOOL_SEARCH_TOOL_NAME in actions))
+        return actions;
+    return Object.fromEntries(Object.entries(actions).filter(([name]) => name !== TOOL_SEARCH_TOOL_NAME));
+}
+/**
+ * Re-point `tool-search` at the surface this caller can actually reach.
+ *
+ * The registry's own entry closes over the app's *whole* action registry, but
+ * `tools/call` accepts only the advertised set — so unscoped it answers with
+ * names that come straight back as "Unknown tool", and its `callable` field
+ * reports plan-mode availability, not that gate. Every template that noticed
+ * worked around it by hand-rolling a narrowed copy; scoping it here is what
+ * makes the trimmed catalog honest without one.
+ */
+function scopeToolSearchToAdvertised(advertised) {
+    const entry = advertised[TOOL_SEARCH_TOOL_NAME];
+    if (!entry)
+        return advertised;
+    return {
+        ...advertised,
+        [TOOL_SEARCH_TOOL_NAME]: {
+            ...entry,
+            // Imported lazily: `agent/tool-search.ts` pulls Node-only request
+            // context, and this module has to stay bundleable for serverless.
+            run: async (args) => {
+                const { searchToolRegistry } = await import("../agent/tool-search.js");
+                return searchToolRegistry(advertised, args ?? {});
+            },
+        },
+    };
+}
 const COMPACT_MCP_APP_CATALOG_BUILTINS = new Set([
     "list_apps",
     "open_app",
@@ -149,9 +184,10 @@ const COMPACT_MCP_APP_CATALOG_BUILTINS = new Set([
     "ask_app_status",
     "create_embed_session",
     // `tool-search` MUST stay in every compact/connector surface: it is how a
-    // compacted client discovers and loads any action on demand, which is what
-    // makes "small catalog by default" safe instead of limiting.
-    "tool-search",
+    // compacted client discovers any action on demand, which is what makes
+    // "small catalog by default" non-opaque. Discovery is not permission — a
+    // searched name still has to be in the advertised set to be callable.
+    TOOL_SEARCH_TOOL_NAME,
 ]);
 function isActionAdvertisedInCompactMcpAppCatalog(name, entry, config) {
     if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name))
@@ -1115,16 +1151,36 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     const baseActions = useFullSurface && config.productionActions
         ? config.productionActions
         : config.actions;
-    const actions = mergeBuiltinTools(config, baseActions, requestMeta);
+    const appCatalog = config.catalogMode === "app";
+    // The app catalog IS a full flat catalog, so the `--full-catalog` opt-ins
+    // have nothing left to escalate — collapsing them here keeps every tier gate
+    // below reading one flag instead of testing `appCatalog` a fifth time.
+    const fullCatalogRequested = !appCatalog && explicitlyRequestsFullMcpCatalog(requestMeta);
+    // `tool-search` earns its place only on a *trimmed* catalog, where it is how
+    // a client reaches an action that was not listed. On a flat catalog — app
+    // mode or the `--full-catalog` opt-in — every tool is already in `tools/list`
+    // beside it, so it can only ever describe its own neighbours while spending
+    // a tool slot and a round trip to do it.
+    const flatCatalog = appCatalog || fullCatalogRequested;
+    // `catalogMode: "app"` asks for parity with the in-app agent, so the cross-app
+    // builtins the MCP layer adds on its own come back off too.
+    const mergedActions = appCatalog
+        ? baseActions
+        : mergeBuiltinTools(config, baseActions, requestMeta);
+    // Strip from `actions`, not just the advertised set: on the full-catalog tier
+    // `actions` IS the callable surface, so filtering only the listing would
+    // leave `tool-search` callable but invisible.
+    const actions = flatCatalog
+        ? withoutToolSearch(mergedActions)
+        : mergedActions;
     const visibleActions = Object.fromEntries(Object.entries(actions).filter(([, entry]) => isActionVisibleForOAuthScope(entry, effectiveIdentity?.oauthScopes)));
-    const fullCatalogRequested = explicitlyRequestsFullMcpCatalog(requestMeta);
     // Compact/connector is the DEFAULT for every caller — hosted connectors,
     // code clients (Claude Code / Cursor / Codex), and the local CLI alike. The
     // full ~105-tool catalog is served only on the explicit opt-in above, so a
     // host can never dump every action schema into one giant tool card. The
     // `mcp:apps` scope still lands on this compact MCP-Apps surface; with no
     // opt-in, everyone else does too.
-    const compactMcpAppCatalog = !fullCatalogRequested;
+    const compactMcpAppCatalog = !appCatalog && !fullCatalogRequested;
     const advertisedActionsBeforeConnector = compactMcpAppCatalog
         ? Object.fromEntries(Object.entries(visibleActions).filter(([name, entry]) => isActionAdvertisedInCompactMcpAppCatalog(name, entry, config)))
         : visibleActions;
@@ -1140,28 +1196,32 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     // authenticated reads from `externalAgents.authenticatedReads: "auto"`.
     // This stays compact by default and keeps db-exec / seed-* / extension /
     // browser-session footguns off the external surface.
-    const connectorCatalogActive = (connectorNames.size > 0 || automaticConnectorPolicyActive) &&
+    const connectorCatalogActive = !appCatalog &&
+        (connectorNames.size > 0 || automaticConnectorPolicyActive) &&
         !fullCatalogRequested;
     // When the connector catalog is active, filter directly from visibleActions
     // rather than advertisedActionsBeforeConnector. This ensures the connector
     // tier is an independent, template-declared surface that doesn't accidentally
     // narrow to just the compact-catalog builtins when shouldUseCompactMcpCatalogByDefault
     // would have activated the compact catalog for the same caller.
-    const advertisedActions = connectorCatalogActive
-        ? Object.fromEntries(Object.entries(visibleActions).filter(([name, entry]) => {
-            if (denyNames.has(name))
-                return false;
-            if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name))
+    const advertisedActionsBeforeToolSearchScope = appCatalog
+        ? Object.fromEntries(Object.entries(visibleActions).filter(([name]) => !denyNames.has(name)))
+        : connectorCatalogActive
+            ? Object.fromEntries(Object.entries(visibleActions).filter(([name, entry]) => {
+                if (denyNames.has(name))
+                    return false;
+                if (COMPACT_MCP_APP_CATALOG_BUILTINS.has(name))
+                    return true;
+                if (!connectorNames.has(name))
+                    return false;
+                if (externalAgentWritesAreAskAppOnly(config) &&
+                    entry.readOnly !== true) {
+                    return false;
+                }
                 return true;
-            if (!connectorNames.has(name))
-                return false;
-            if (externalAgentWritesAreAskAppOnly(config) &&
-                entry.readOnly !== true) {
-                return false;
-            }
-            return true;
-        }))
-        : advertisedActionsBeforeConnector;
+            }))
+            : advertisedActionsBeforeConnector;
+    const advertisedActions = scopeToolSearchToAdvertised(advertisedActionsBeforeToolSearchScope);
     if (fullCatalogRequested) {
         warnFullCatalogServed(Object.keys(advertisedActions).length);
     }
@@ -1389,8 +1449,10 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     annotations,
                 };
             }));
-            if (!compactMcpAppCatalog &&
-                !connectorCatalogActive &&
+            // `ask-agent` is the legacy full-catalog meta-tool; `ask_app` is the
+            // builtin every other tier carries. Gate on the one flag that means
+            // "this caller opted all the way in".
+            if (fullCatalogRequested &&
                 config.askAgent &&
                 hasMcpOAuthScope(effectiveIdentity?.oauthScopes, "mcp:write")) {
                 tools.push({
@@ -1436,7 +1498,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
         return withCallerContext(async () => {
             const { name, arguments: args } = request.params;
             if (name === "ask-agent" && config.askAgent) {
-                if (compactMcpAppCatalog || connectorCatalogActive) {
+                if (!fullCatalogRequested) {
                     return {
                         content: [{ type: "text", text: `Unknown tool: ${name}` }],
                         isError: true,
@@ -1483,12 +1545,14 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     };
                 }
             }
-            // Connector-catalog tier: when active, callableActions === advertisedActions
-            // (the filtered set). Non-listed tools are not callable — mirroring how
-            // compactMcpAppCatalog gates calls on advertisedActions.
-            const callableActions = compactMcpAppCatalog || connectorCatalogActive
-                ? advertisedActions
-                : actions;
+            // Every tier except the explicit full-catalog opt-in treats the
+            // advertised set as the authoritative callable surface: a name that
+            // was not listed is rejected, not merely hidden. Deriving this from
+            // the one opt-in flag rather than re-testing each tier is what keeps a
+            // newly added tier from silently defaulting to "everything callable".
+            const callableActions = fullCatalogRequested
+                ? actions
+                : advertisedActions;
             const entry = callableActions[name];
             if (!entry) {
                 return {