@agent-native/core 0.91.1 → 0.92.0

package/blueprints/action/crud.md

@@ -89,7 +89,7 @@ Read the `actions` skill. The rules that matter most here:
 
 ## Verify
 
-1. `agent-native typecheck` (or `tsgo --noEmit`) passes.
+1. `agent-native typecheck` (or `tsc --noEmit`) passes.
 2. From the agent chat, invoke the new action and confirm structured
    input/output.
 3. From the UI, confirm the `useActionQuery` / `useActionMutation` path works and

package/blueprints/channel/discord.md

@@ -66,7 +66,7 @@ Study the existing adapters as the pattern to copy:
 
 ## Verify
 
-1. `tsgo --noEmit` for `@agent-native/core` passes.
+1. `tsc --noEmit` for `@agent-native/core` passes.
 2. `discord.spec.ts` passes (`vitest --run src/integrations/adapters/discord`).
 3. End-to-end smoke: send a signed test interaction to
    `/_agent-native/integrations/discord/webhook`; confirm a `200` returns

package/blueprints/provider/stripe.md

@@ -79,7 +79,7 @@ The substrate lives in `@agent-native/core/provider-api`:
 
 ## Verify
 
-1. `agent-native typecheck` (or `tsgo --noEmit`) passes.
+1. `agent-native typecheck` (or `tsc --noEmit`) passes.
 2. With a placeholder `STRIPE_SECRET_KEY` set, ask the agent: "list my 5 most
    recent Stripe charges." Confirm it calls `provider-api-catalog` →
    (optionally) `provider-api-docs` → `provider-api-request` against

package/blueprints/sandbox/docker.md

@@ -70,7 +70,7 @@ augment `env` with the parent's environment and never see app secrets.
 
 ## Verify
 
-1. `tsgo --noEmit` for `@agent-native/core` passes.
+1. `tsc --noEmit` for `@agent-native/core` passes.
 2. `docker-adapter.spec.ts` passes.
 3. With Docker available, set `AGENT_NATIVE_SANDBOX=docker` and run a `run-code`
    task that uses `appAction`/`providerFetch` through the loopback bridge;

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2149
-- template files: 4941
+- core files: 2153
+- template files: 5000

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @agent-native/core
 
+## 0.92.0
+
+### Minor Changes
+
+- 680b1eb: Show plain-English thinking in chat, Codex-style tool rows with modal output, and collapse finished work into a "Worked for" summary.
+- 680b1eb: Add `agent-native upgrade` (with `upgrade check` doctor) so older apps can bump `@agent-native/*`, refresh scaffold skills, and verify without inventing core/dispatch patches or overrides. Harden self-modifying-code / AGENTS guidance, discover workspace packages from `pnpm-workspace.yaml`, and ship the `upgrade-agent-native` skill.
+
+### Patch Changes
+
+- 680b1eb: Keep plan-mode blocked tools visible and discoverable as blocked stubs, preload common provider tools in lean agent runs, steer extension edits away from repeated large content scans, and let raw JSON Schema tool inputs recover from common scalar string values without poisoning read-only duplicate caches.
+- 680b1eb: Compact repeated tool-search results and unchanged extension content within a single agent run to preserve context, while keeping schema-including tool searches repeatable when the agent explicitly asks for schemas.
+- 680b1eb: Always register Slack/webhook/email notification channels, prefer delivery-only per-notification webhook URLs, and avoid applying workspace auth headers to override destinations.
+- 680b1eb: Stop rewriting session-replay Meta and ViewportResize dimensions at capture so stored frames stay aligned with the FullSnapshot DOM, while display sizing still clamps extreme aspect ratios.
+- 680b1eb: Render Agent settings sections as polished card surfaces on full settings pages while keeping the sidebar settings panel compact.
+- Updated dependencies [680b1eb]
+  - @agent-native/toolkit@0.4.4
+
+## 0.91.2
+
+### Patch Changes
+
+- 823d635: Add a friendly label for the Calendar `calendar.event-detail.bottom` ExtensionSlot so the empty-slot affordance matches Mail's contact sidebar pattern.
+- 823d635: Surface outbound delivery-queue health on Destinations and add quiet overview shortcuts so cleaned-up overview capabilities stay discoverable without restoring the old dashboard. Localize those overview shortcut and delivery-queue labels across Dispatch locales.
+- 823d635: Attribute recurring job and automation LLM usage to task-specific usage labels.
+- 823d635: Clamp absurd session-replay Meta and ViewportResize dimensions at capture so ultra-wide frames are never stored.
+- 823d635: Align run-slot liveness with the stale reaper and surface repeated heartbeat write failures.
+- 823d635: Upgrade the workspace toolchain to TypeScript 7 (`tsc`) with a side-by-side TypeScript 6 API package for tools that still need programmatic access. Replace `@typescript/native-preview` / `tsgo` with the stable `typescript` 7 release.
+- Updated dependencies [823d635]
+- Updated dependencies [823d635]
+  - @agent-native/toolkit@0.4.3
+
 ## 0.91.1
 
 ### Patch Changes

package/corpus/core/blueprints/action/crud.md

@@ -89,7 +89,7 @@ Read the `actions` skill. The rules that matter most here:
 
 ## Verify
 
-1. `agent-native typecheck` (or `tsgo --noEmit`) passes.
+1. `agent-native typecheck` (or `tsc --noEmit`) passes.
 2. From the agent chat, invoke the new action and confirm structured
    input/output.
 3. From the UI, confirm the `useActionQuery` / `useActionMutation` path works and

package/corpus/core/blueprints/channel/discord.md

@@ -66,7 +66,7 @@ Study the existing adapters as the pattern to copy:
 
 ## Verify
 
-1. `tsgo --noEmit` for `@agent-native/core` passes.
+1. `tsc --noEmit` for `@agent-native/core` passes.
 2. `discord.spec.ts` passes (`vitest --run src/integrations/adapters/discord`).
 3. End-to-end smoke: send a signed test interaction to
    `/_agent-native/integrations/discord/webhook`; confirm a `200` returns

package/corpus/core/blueprints/provider/stripe.md

@@ -79,7 +79,7 @@ The substrate lives in `@agent-native/core/provider-api`:
 
 ## Verify
 
-1. `agent-native typecheck` (or `tsgo --noEmit`) passes.
+1. `agent-native typecheck` (or `tsc --noEmit`) passes.
 2. With a placeholder `STRIPE_SECRET_KEY` set, ask the agent: "list my 5 most
    recent Stripe charges." Confirm it calls `provider-api-catalog` →
    (optionally) `provider-api-docs` → `provider-api-request` against

package/corpus/core/blueprints/sandbox/docker.md

@@ -70,7 +70,7 @@ augment `env` with the parent's environment and never see app secrets.
 
 ## Verify
 
-1. `tsgo --noEmit` for `@agent-native/core` passes.
+1. `tsc --noEmit` for `@agent-native/core` passes.
 2. `docker-adapter.spec.ts` passes.
 3. With Docker available, set `AGENT_NATIVE_SANDBOX=docker` and run a `run-code`
    task that uses `appAction`/`providerFetch` through the loopback bridge;

package/corpus/core/docs/content/faq.mdx

@@ -227,6 +227,23 @@ SSE gives same-process writes an immediate path to the browser, and a lightweigh
 
 AI is non-deterministic, so you need conversation flow to give feedback and iterate — not one-shot buttons — and the agent already has your codebase, instructions, skills, and history that an inline call lacks. Routing everything through the agent is also what lets the app be driven from Slack, Telegram, or another agent. See [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
 
+### How do I upgrade an older Agent Native app? {#upgrade-older-app}
+
+Run the supported upgrade path from the app or workspace root:
+
+```bash
+npx @agent-native/core@latest upgrade
+```
+
+That bumps `@agent-native/*` dependencies to `latest`, installs, refreshes
+scaffold skills (`skills update scaffold --project`), and runs typecheck when
+available. Use `upgrade check` first if you want a doctor-only report of
+framework overrides/patches and pending bumps.
+
+Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`,
+or edits under `node_modules/@agent-native/*` (especially core/dispatch). If
+upgrade or typecheck fails, fix app-level code or ask — then re-run upgrade.
+
 ### Why is this a framework and not a library? {#why-framework-not-library}
 
 The shared database, live sync, actions system, and application state only work because they're wired together from the ground up — the UI reacts to agent changes instantly, agents communicate, and the agent understands what the user is looking at. A library gives you pieces; this is an architecture. See [Key Concepts](/docs/key-concepts).

package/corpus/core/docs/content/notifications.mdx

@@ -108,12 +108,18 @@ Severity drives the badge styling in the dropdown and is passed through to chann
 
 ## Built-in channels {#channels}
 
-| Channel   | Delivery                                                  | Requires                                            |
-| --------- | --------------------------------------------------------- | --------------------------------------------------- |
-| `inbox`   | Persists to the `notifications` table; drives the bell UI | Always on — part of the primitive.                  |
-| `webhook` | POST JSON to a configured URL                             | `NOTIFICATIONS_WEBHOOK_URL` env var set at startup. |
-
-The webhook channel resolves `${keys.NAME}` references in both the URL and `NOTIFICATIONS_WEBHOOK_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
+| Channel   | Delivery                                                  | Requires                                                                              |
+| --------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `inbox`   | Persists to the `notifications` table; drives the bell UI | Always on — part of the primitive.                                                    |
+| `email`   | Sends email via Resend/SendGrid                           | Per-notification `metadata.emailRecipients` and/or `NOTIFICATIONS_EMAIL_RECIPIENTS`.  |
+| `slack`   | POST Slack Block Kit JSON to an incoming webhook          | Per-notification `metadata.slackWebhookUrl` and/or `NOTIFICATIONS_SLACK_WEBHOOK_URL`. |
+| `webhook` | POST JSON to a configured URL                             | Per-notification `metadata.webhookUrl` and/or `NOTIFICATIONS_WEBHOOK_URL`.            |
+
+Slack and webhook are always registered. Delivery prefers the per-notification
+metadata URL, then falls back to the matching env var. If neither is set, that
+channel no-ops for the emission.
+
+The webhook and Slack channels resolve `${keys.NAME}` references in both the URL and `NOTIFICATIONS_*_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
 
 <Diagram id="doc-block-1lduyog" title="Channels and severity" summary={"inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."}>
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.91.1",
+  "version": "0.92.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -227,9 +227,9 @@
     "provenance": true
   },
   "scripts": {
-    "build": "tsgo && tsgo -p tsconfig.cli.json && node scripts/finalize-build.mjs && node scripts/check-dist-imports.mjs",
-    "dev": "tsgo --watch",
-    "typecheck": "tsgo --noEmit",
+    "build": "tsc && tsc -p tsconfig.cli.json && node scripts/finalize-build.mjs && node scripts/check-dist-imports.mjs",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
     "test": "vitest --run src --maxWorkers=25%",
     "prepack": "tsx ../../scripts/sync-workspace-core-skills.ts --check && npm run build && cp ../../README.md ./README.md",
     "prepublishOnly": "npm run build"
@@ -367,7 +367,8 @@
     "react-dom": "^19.2.7",
     "react-router": "^8.1.0",
     "tailwindcss": "catalog:",
-    "typescript": "^6.0.3",
+    "typescript": "catalog:",
+    "typescript-7": "catalog:",
     "vite": "catalog:",
     "vitest": "^4.1.5",
     "ws": "^8.18.0"

package/corpus/core/src/agent/production-agent.ts

@@ -824,6 +824,23 @@ function createPlanModeBashAction(entry: ActionEntry): ActionEntry {
   };
 }
 
+function createPlanModeBlockedAction(
+  name: string,
+  entry: ActionEntry,
+  reason?: string,
+): ActionEntry {
+  return {
+    ...entry,
+    allowInPlanMode: false,
+    readOnly: true,
+    tool: {
+      ...entry.tool,
+      description: `${entry.tool.description}\n\nPlan mode blocked: ${reason ?? "not available while planning"}.`,
+    },
+    run: async () => planModeBlockedMessage(name, reason),
+  };
+}
+
 export function createPlanModeActionRegistry(
   actions: Record<string, ActionEntry>,
 ): Record<string, ActionEntry> {
@@ -831,8 +848,22 @@ export function createPlanModeActionRegistry(
 
   for (const [name, entry] of Object.entries(actions)) {
     if (name === TOOL_SEARCH_ACTION_NAME) continue;
-    if (entry.allowInPlanMode === false) continue;
-    if (PLAN_MODE_BLOCKED_READONLY_TOOLS.has(name)) continue;
+    if (entry.allowInPlanMode === false) {
+      filtered[name] = createPlanModeBlockedAction(
+        name,
+        entry,
+        "not available while planning",
+      );
+      continue;
+    }
+    if (PLAN_MODE_BLOCKED_READONLY_TOOLS.has(name)) {
+      filtered[name] = createPlanModeBlockedAction(
+        name,
+        entry,
+        "not available while planning",
+      );
+      continue;
+    }
 
     const allowedActions = PLAN_MODE_ALLOWED_ACTIONS[name];
     if (allowedActions) {
@@ -852,6 +883,12 @@ export function createPlanModeActionRegistry(
 
     if (entry.readOnly === true) {
       filtered[name] = entry;
+    } else {
+      filtered[name] = createPlanModeBlockedAction(
+        name,
+        entry,
+        "write or side-effecting tool",
+      );
     }
   }
 
@@ -965,7 +1002,10 @@ export interface ProductionAgentOptions {
    * only these tool schemas plus `tool-search`; the full action registry remains
    * searchable, and matching tool schemas from `tool-search` results are added
    * to the next model request. This keeps first-token latency low without
-   * forcing rarely used capabilities into every prompt.
+   * forcing rarely used capabilities into every prompt. The framework also
+   * promotes common provider/corpus/code-execution tools when the current
+   * app/mode registry exposes them, so prompts that teach broad integrations do
+   * not describe tools that require an extra discovery turn before use.
    */
   initialToolNames?: string[];
   /**
@@ -2066,6 +2106,7 @@ function isReusableReadOnlyToolResult(part: EngineToolResultPart): boolean {
   const lower = part.content.trim().toLowerCase();
   if (!lower) return false;
   return !(
+    lower.startsWith("invalid action parameters for ") ||
     lower.startsWith("error running ") ||
     lower.includes("run aborted") ||
     lower.includes("tool call timed out") ||
@@ -2151,16 +2192,74 @@ export function actionsToEngineTools(
   return tools;
 }
 
-function filterInitialEngineTools(
+export function filterInitialEngineTools(
   tools: EngineTool[],
   initialToolNames?: string[],
 ): EngineTool[] {
   if (!initialToolNames) return tools;
   const names = new Set(initialToolNames);
   names.add(TOOL_SEARCH_ACTION_NAME);
+  for (const tool of tools) {
+    if (isDefaultLeanInitialToolName(tool.name)) {
+      names.add(tool.name);
+    }
+  }
   return tools.filter((tool) => names.has(tool.name));
 }
 
+const DEFAULT_LEAN_INITIAL_TOOL_NAMES = new Set([
+  // Broad provider/API/corpus primitives should be callable as soon as the
+  // prompt teaches them; waiting for a discovery round-trip caused prod runs to
+  // waste turns on provider work that was described but not loaded.
+  "data-source-status",
+  "provider-api-catalog",
+  "provider-api-docs",
+  "provider-api-request",
+  "provider-corpus-job",
+  "provider-corpus-jobs",
+  "query-staged-dataset",
+  "list-staged-datasets",
+  "delete-staged-dataset",
+  "run-code",
+  "get-code-execution",
+  "list-extensions",
+  "get-extension",
+  "update-extension",
+  "list-extension-history",
+  "get-extension-history-version",
+  // Common first-class integration shortcuts. These are included only when the
+  // current app/mode registry actually exposes them.
+  "bigquery",
+  "search-bigquery-schema",
+  "bigquery-table-info",
+  "ga4",
+  "amplitude",
+  "prometheus",
+  "grafana",
+  "sentry",
+  "stripe",
+  "account-deep-dive",
+  "slack-messages",
+  "hubspot-deals",
+  "hubspot-records",
+  "hubspot-pipelines",
+  "hubspot-metrics",
+  "gong-calls",
+  "github-repo-files",
+  "jira",
+  "jira-search",
+  "gcloud",
+  "notion-search",
+  "pylon-search",
+]);
+
+function isDefaultLeanInitialToolName(name: string): boolean {
+  if (DEFAULT_LEAN_INITIAL_TOOL_NAMES.has(name)) return true;
+  return (
+    name.startsWith("provider-api-") || name.startsWith("provider-corpus-")
+  );
+}
+
 function extractToolSearchResultNames(value: unknown): string[] {
   if (!value || typeof value !== "object") return [];
   const result = value as { query?: unknown; results?: unknown };
@@ -2538,7 +2637,7 @@ type RawJsonSchema = AgentNativeJsonSchema;
 const rawToolInputAjv = new Ajv({
   strict: false,
   allErrors: true,
-  coerceTypes: false,
+  coerceTypes: true,
   useDefaults: false,
   removeAdditional: false,
 });
@@ -3635,47 +3734,6 @@ export async function runAgentLoop(opts: {
         }
       }
 
-      const cacheKey =
-        actionEntry.readOnly === true
-          ? toolCallCacheKey(toolCall.name, toolCall.input)
-          : null;
-      if (cacheKey && readOnlyToolResultCache.has(cacheKey)) {
-        const repeats = (duplicateReadOnlyToolCalls.get(cacheKey) ?? 0) + 1;
-        duplicateReadOnlyToolCalls.set(cacheKey, repeats);
-        const previousResult = readOnlyToolResultCache.get(cacheKey) ?? "";
-        const result =
-          `Skipped duplicate read-only call to ${toolCall.name}: identical input already ran in this turn. ` +
-          `Use the previous result already in the conversation instead of calling this tool again.\n\n` +
-          `Previous result:\n${previousResult}`;
-        send({
-          type: "tool_start",
-          tool: toolCall.name,
-          input: toolCall.input as Record<string, string>,
-        });
-        send({
-          type: "tool_done",
-          tool: toolCall.name,
-          input: toolCall.input as Record<string, unknown>,
-          result,
-          completedSideEffect: false,
-        });
-        recordToolResult(result, false);
-        if (repeats >= 3) {
-          requestedActionStop ??= {
-            message:
-              "I stopped because the agent kept asking for the same read-only context it already had. Please send the request again if you want me to retry from a fresh turn.",
-            errorCode: "duplicate_read_only_tool",
-          };
-        }
-        return {
-          type: "tool-result" as const,
-          toolCallId: toolCall.id,
-          toolName: toolCall.name,
-          toolInput: wireToolInput,
-          content: result,
-        };
-      }
-
       const DEFAULT_TOOL_RESULT_CHARS = 50_000;
       // Default action tools should not undercut durable/background runs. The
       // run-manager still aborts foreground hosted runs around 40s, while
@@ -3912,6 +3970,42 @@ export async function runAgentLoop(opts: {
         };
       }
 
+      const cacheKey =
+        actionEntry.readOnly === true
+          ? toolCallCacheKey(toolCall.name, toolCall.input)
+          : null;
+      if (cacheKey && readOnlyToolResultCache.has(cacheKey)) {
+        const repeats = (duplicateReadOnlyToolCalls.get(cacheKey) ?? 0) + 1;
+        duplicateReadOnlyToolCalls.set(cacheKey, repeats);
+        const previousResult = readOnlyToolResultCache.get(cacheKey) ?? "";
+        const result =
+          `Skipped duplicate read-only call to ${toolCall.name}: identical input already ran in this turn. ` +
+          `Use the previous result already in the conversation instead of calling this tool again.\n\n` +
+          `Previous result:\n${previousResult}`;
+        send({
+          type: "tool_done",
+          tool: toolCall.name,
+          input: toolCall.input as Record<string, unknown>,
+          result,
+          completedSideEffect: false,
+        });
+        recordToolResult(result, false);
+        if (repeats >= 3) {
+          requestedActionStop ??= {
+            message:
+              "I stopped because the agent kept asking for the same read-only context it already had. Please send the request again if you want me to retry from a fresh turn.",
+            errorCode: "duplicate_read_only_tool",
+          };
+        }
+        return {
+          type: "tool-result" as const,
+          toolCallId: toolCall.id,
+          toolName: toolCall.name,
+          toolInput: wireToolInput,
+          content: result,
+        };
+      }
+
       if (
         opts.executionMode === "plan" &&
         !isPlanModeToolCallAllowed(toolCall.name, toolCall.input, actionEntry)

package/corpus/core/src/agent/run-manager.ts

@@ -678,10 +678,31 @@ export function startRun(
 
   // Heartbeat: bump heartbeat_at every 1.5s so watchers can detect a dead
   // producer (process crash, HMR restart, isolate eviction) quickly and
-  // reap the row. Paired with RUN_STALE_MS (6s) — 4x the interval to
+  // reap the row. Paired with RUN_STALE_MS (15s) — 10x the interval to
   // tolerate transient DB slowness without false positives.
+  let consecutiveHeartbeatFailures = 0;
   const heartbeatTimer: ReturnType<typeof setInterval> = setInterval(() => {
-    updateRunHeartbeat(runId).catch(() => {});
+    updateRunHeartbeat(runId)
+      .then(() => {
+        consecutiveHeartbeatFailures = 0;
+      })
+      .catch((error) => {
+        consecutiveHeartbeatFailures += 1;
+        // Swallow routine single-tick blips; escalate once failures approach
+        // the stale window so false-positive stale_run from silent write
+        // failures is diagnosable.
+        if (consecutiveHeartbeatFailures >= 3) {
+          captureError(error, {
+            route: "/_agent-native/agent-chat",
+            tags: {
+              source: "agent-run-manager",
+              phase: "heartbeat",
+              consecutiveFailures: String(consecutiveHeartbeatFailures),
+            },
+            extra: { runId, threadId },
+          });
+        }
+      });
     checkSqlAbort();
     checkNoProgressBackstop();
   }, 1500);

package/corpus/core/src/agent/run-store.ts

@@ -719,7 +719,7 @@ export async function tryClaimRunSlot(
             WHERE thread_id = ?
               AND status = 'running'
               AND ${terminalRunEventExclusionSql()}
-              AND COALESCE(heartbeat_at, started_at) >= ?
+              AND ${livenessBasisSql()} >= ?
             ORDER BY started_at DESC LIMIT 1`,
       args: [threadId, heartbeatCutoff],
     });
@@ -733,7 +733,7 @@ export async function tryClaimRunSlot(
           WHERE thread_id = ?
             AND status = 'running'
             AND ${terminalRunEventExclusionSql()}
-            AND COALESCE(heartbeat_at, started_at) >= ${backgroundAwareStaleCutoffSql()}
+            AND ${livenessBasisSql()} >= ${backgroundAwareStaleCutoffSql()}
           ORDER BY started_at DESC LIMIT 1`,
     args: [threadId, now],
   });

package/corpus/core/src/agent/tool-search.ts

@@ -1,5 +1,6 @@
 import { parseMcpToolName } from "../mcp-client/manager.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
+import { getRequestRunContext } from "../server/request-context.js";
 import type { ActionEntry } from "./production-agent.js";
 
 export const TOOL_SEARCH_ACTION_NAME = "tool-search";
@@ -43,14 +44,14 @@ export function createToolSearchEntry(
   return {
     tool: {
       description:
-        "Discover callable tools/actions, including connected MCP server tools named `mcp__<server>__<tool>`. Call it with NO query to list every available tool by name with a one-line description (cheap — no input schemas) so you can see the full menu of what exists; pass a `query` to find specific tools and get their parameter summaries. Use this whenever you need a capability but aren't sure which tool to call — most tools are not loaded into context up front, so this is how you find and then call them.",
+        "Discover callable tools/actions, including connected MCP server tools named `mcp__<server>__<tool>`. Call it with NO query to list every available tool by name with a one-line description (cheap — no input schemas); names from that menu are not loaded for calling yet, so call tool-search again with a specific query for the tool/capability before invoking it. Use this whenever you need a capability but aren't sure which tool to call — most tools are not loaded into context up front, so this is how you find and then call them.",
       parameters: {
         type: "object",
         properties: {
           query: {
             type: "string",
             description:
-              "What capability to find, e.g. `send slack message`, `create calendar event`, `zapier gmail`, or `browser screenshot`. Omit to list every available tool name (the full menu) with one-line descriptions.",
+              "What capability to find, e.g. `send slack message`, `create calendar event`, `zapier gmail`, or `browser screenshot`. Omit to list every available tool name (the full menu) with one-line descriptions; then call tool-search again with a specific query before calling a tool from that menu.",
           },
           limit: {
             type: "number",
@@ -90,6 +91,8 @@ export function searchToolRegistry(
   query: string;
   totalTools: number;
   count: number;
+  repeated?: boolean;
+  message?: string;
   results: ToolSearchResult[];
 } {
   const query = String(args.query ?? "").trim();
@@ -105,6 +108,33 @@ export function searchToolRegistry(
     options.defaultLimit ?? DEFAULT_LIMIT,
     options.maxLimit ?? MAX_LIMIT,
   );
+  const cacheKey = normalizeToolSearchCacheKey({
+    query,
+    limit,
+    includeSchemas,
+  });
+  const runCtx = getRequestRunContext();
+  const priorSearch = includeSchemas
+    ? undefined
+    : runCtx?.toolSearchReads?.[cacheKey];
+  if (priorSearch) {
+    return {
+      query,
+      totalTools: priorSearch.totalTools,
+      count: priorSearch.resultNames.length,
+      repeated: true,
+      message:
+        "This exact tool-search query already ran in this agent run. Use the previously returned schemas/details instead of searching again.",
+      results: priorSearch.resultNames.map((name) => ({
+        name,
+        kind: parseMcpToolName(name) ? ("mcp" as const) : ("action" as const),
+        score: 0,
+        description:
+          "Already returned by an earlier identical tool-search call.",
+        parameters: [],
+      })),
+    };
+  }
   const queryTokens = tokenize(query);
 
   const candidates: ToolSearchResult[] = [];
@@ -112,6 +142,7 @@ export function searchToolRegistry(
 
   for (const [name, entry] of Object.entries(registry)) {
     if (!entry?.tool || name === TOOL_SEARCH_ACTION_NAME) continue;
+    if (entry.agentTool === false) continue;
     if (name.startsWith("mcp__") && !isMcpToolAllowedForRequest(name)) {
       continue;
     }
@@ -160,7 +191,16 @@ export function searchToolRegistry(
 
   if (listAll) {
     candidates.sort((a, b) => a.name.localeCompare(b.name));
-    return { query, totalTools, count: candidates.length, results: candidates };
+    const result = {
+      query,
+      totalTools,
+      count: candidates.length,
+      message:
+        'Menu mode lists tool names only; it does not load schemas for calling. Before invoking a tool found here, call tool-search again with a specific query such as the tool name or capability (for example, { "query": "hubspot-deals" }).',
+      results: candidates,
+    };
+    rememberToolSearchResult(cacheKey, result);
+    return result;
   }
 
   candidates.sort((a, b) => {
@@ -168,12 +208,39 @@ export function searchToolRegistry(
     return a.name.localeCompare(b.name);
   });
 
-  return {
+  const result = {
     query,
     totalTools,
     count: Math.min(candidates.length, limit),
     results: candidates.slice(0, limit),
   };
+  if (!includeSchemas) rememberToolSearchResult(cacheKey, result);
+  return result;
+}
+
+function normalizeToolSearchCacheKey(options: {
+  query: string;
+  limit: number;
+  includeSchemas: boolean;
+}): string {
+  return JSON.stringify({
+    query: options.query.trim().toLowerCase(),
+    limit: options.limit,
+    includeSchemas: options.includeSchemas,
+  });
+}
+
+function rememberToolSearchResult(
+  cacheKey: string,
+  result: { totalTools: number; results: Array<{ name: string }> },
+) {
+  const runCtx = getRequestRunContext();
+  if (!runCtx) return;
+  const reads = (runCtx.toolSearchReads ??= {});
+  reads[cacheKey] = {
+    totalTools: result.totalTools,
+    resultNames: result.results.map((item) => item.name),
+  };
 }
 
 function truncate(value: string, max: number): string {

package/corpus/core/src/cli/add.ts

@@ -202,7 +202,7 @@ A new **${kind}** integration. ${kindGuidance}
 
 ## Verify
 
-1. \`agent-native typecheck\` (or \`tsgo --noEmit\`) passes.
+1. \`agent-native typecheck\` (or \`tsc --noEmit\`) passes.
 2. Add a focused \`*.spec.ts\` for the new surface and run it.
 3. Exercise the real workflow end to end: invoke the new action from the agent
    chat (and the UI if applicable), and confirm the external call round-trips