chainlesschain 0.162.154 → 0.162.155

package/src/lib/ws-rpc-client.js

@@ -0,0 +1,150 @@
+/**
+ * Minimal promise-based WebSocket RPC client for the cc WS server protocol
+ * (auth + id-correlated request/response + fire-hose events). Used by
+ * `cc remote-control` for its in-process loopback HOST connection — the
+ * remote-session registry closes a session when its host disconnects, so the
+ * unified entry keeps this client open for the server's lifetime.
+ *
+ * Protocol notes:
+ *   - every request carries a unique `id`. Flat responses (auth, remote-session-*)
+ *     echo it back as `id`; envelope responses (session-create & friends,
+ *     createCodingAgentEvent) repurpose `id` as a random eventId and carry the
+ *     correlation key in `requestId` — so match `requestId` FIRST, then `id`.
+ *   - the FIRST frame matching a pending key settles that request (fine for
+ *     command/one-shot topics; streaming topics need onEvent, not request()).
+ *   - messages matching no pending key are events → onEvent callbacks.
+ */
+
+import WebSocket from "ws";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export class WsRpcClient {
+  constructor({ url, WebSocketImpl = WebSocket, timeoutMs } = {}) {
+    if (!url) throw new Error("url is required");
+    this.url = url;
+    this.WebSocketImpl = WebSocketImpl;
+    this.timeoutMs = timeoutMs || DEFAULT_TIMEOUT_MS;
+    this.ws = null;
+    this._pending = new Map();
+    this._counter = 0;
+    this._eventHandlers = new Set();
+    this._closed = false;
+  }
+
+  onEvent(handler) {
+    this._eventHandlers.add(handler);
+    return () => this._eventHandlers.delete(handler);
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new this.WebSocketImpl(this.url);
+      this.ws = ws;
+      const onOpen = () => {
+        ws.off?.("error", onError);
+        resolve();
+      };
+      const onError = (err) => {
+        reject(new Error(`WebSocket connect failed: ${err.message || err}`));
+      };
+      ws.once("open", onOpen);
+      ws.once("error", onError);
+      ws.on("message", (data) => this._onMessage(data));
+      ws.on("close", () => this._onClose());
+    });
+  }
+
+  _onMessage(data) {
+    let message;
+    try {
+      message = JSON.parse(data.toString("utf8"));
+    } catch {
+      return; // non-JSON frames are not part of this protocol
+    }
+    const key =
+      message.requestId && this._pending.has(message.requestId)
+        ? message.requestId
+        : message.id && this._pending.has(message.id)
+          ? message.id
+          : null;
+    if (key) {
+      const pending = this._pending.get(key);
+      this._pending.delete(key);
+      clearTimeout(pending.timer);
+      if (message.type === "error") {
+        pending.reject(
+          new Error(
+            message.message ||
+              message.payload?.message ||
+              message.code ||
+              message.payload?.code ||
+              "server error",
+          ),
+        );
+      } else {
+        pending.resolve(message);
+      }
+      return;
+    }
+    for (const handler of this._eventHandlers) {
+      try {
+        handler(message);
+      } catch {
+        // one bad handler must not break the read loop
+      }
+    }
+  }
+
+  _onClose() {
+    this._closed = true;
+    for (const [, pending] of this._pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("connection closed"));
+    }
+    this._pending.clear();
+  }
+
+  /** Send `{id, type, ...payload}` and await the matching response frame. */
+  request(type, payload = {}, { timeoutMs } = {}) {
+    if (this._closed || !this.ws || this.ws.readyState !== this.ws.OPEN) {
+      return Promise.reject(new Error("not connected"));
+    }
+    const id = `rpc-${process.pid}-${++this._counter}`;
+    const frame = { id, type, ...payload };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new Error(`request "${type}" timed out`));
+      }, timeoutMs || this.timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+      this._pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(frame), (err) => {
+        if (err) {
+          this._pending.delete(id);
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  /** Authenticate against a token-protected server. No-op when token is null. */
+  async auth(token) {
+    if (!token) return { success: true, skipped: true };
+    const result = await this.request("auth", { token });
+    if (!result.success) {
+      throw new Error(result.message || "authentication failed");
+    }
+    return result;
+  }
+
+  close() {
+    this._closed = true;
+    try {
+      this.ws?.close();
+    } catch {
+      // already closing
+    }
+  }
+}

package/src/repl/agent-repl.js

@@ -34,6 +34,7 @@ import {
   recordDenial,
   formatDenials,
 } from "../lib/repl-denials.js";
+import { appendRecentDenials } from "../lib/permission-denial-store.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import {
   createSession,
@@ -112,6 +113,7 @@ import {
 } from "./permission-prompt.js";
 import {
   parsePermissionTier,
+  parsePermissionModeArg,
   describeTier,
   nextTier,
 } from "./permission-tier.js";
@@ -154,9 +156,23 @@ let _classifyAllShell = false;
 let _sandbox = null;
 // Bounded log of tool calls the agent was BLOCKED from running this session
 // (shell-policy / ApprovalGate / settings rule / hook). Surfaced by
-// `/permissions denials` (Claude-Code 2.1.193 "recent denials"). In-memory only.
+// `/permissions denials` and mirrored to `cc permissions recent`.
 const _recentDenials = [];
 
+function persistRecentDenial(record, options = {}) {
+  try {
+    appendRecentDenials(record, {
+      sessionId: options.sessionId,
+      permissionMode: options.permissionMode,
+      cwd: options.cwd || process.cwd(),
+      source: "repl",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Fire settings.json Notification hooks (observe-only) — the agent needs the
  * user's attention (e.g. waiting on a permission/risk confirmation). A hook can
@@ -318,7 +334,15 @@ export async function agentLoop(messages, options) {
                 : "",
           });
           if (denial) {
-            recordDenial(options.denialLog, { ...denial, at: Date.now() });
+            const record = { ...denial, at: Date.now() };
+            recordDenial(options.denialLog, record);
+            if (options.persistRecentDenials === true) {
+              persistRecentDenial(record, {
+                sessionId: options.sessionId,
+                permissionMode: options.permissionMode,
+                cwd: options.cwd,
+              });
+            }
           }
         }
         // Parity with Desktop AIChatPage's `Switch to Trusted` button:
@@ -409,10 +433,21 @@ export async function startAgentRepl(options = {}) {
   // the injection after the turn (or as a backstop at the next submit on throw).
   let pendingBtw = [];
   let _btwRestore = null;
-  // Current ApprovalGate session tier (strict|trusted|autopilot), mirrored here
-  // so Shift+Tab can cycle it and `/permissions <tier>` can set it. Kept in sync
-  // with _approvalGate.setSessionPolicy below.
+  // Current permission mode (strict|trusted|autopilot|auto), mirrored here so
+  // Shift+Tab can cycle it and `/permissions <tier>` can set it. Kept in sync
+  // with _approvalGate.setSessionPolicy below. "auto" rides the trusted gate
+  // tier but additionally activates the autoMode.decisions classifier wrapper
+  // (when settings customize it) — gateTierFor() maps mode → real gate tier.
   let _sessionTier = "strict";
+  const gateTierFor = (mode) =>
+    mode === "auto" ? "trusted" : mode === "dontAsk" ? "strict" : mode;
+  // dontAsk (headless parity, interactive form): anything that would prompt
+  // is denied instead — both confirmers below consult this before prompting.
+  const _dontAskActive = () => _sessionTier === "dontAsk";
+  // Resolved autoMode.decisions map (loaded once at startup); null until the
+  // gate is wired. The wrapper is installed only when settings customize the
+  // map, and only bites while _sessionTier === "auto" (isActive predicate).
+  let _autoModeResolved = null;
   const baseUrl = options.baseUrl || "http://localhost:11434";
   const apiKey = options.apiKey || null;
   // Configured vision model (config.llm.visionModel) — used when a turn carries
@@ -558,8 +593,39 @@ export async function startAgentRepl(options = {}) {
     const { getApprovalGate } =
       await import("../lib/session-core-singletons.js");
     _approvalGate = await getApprovalGate();
+    // autoMode.decisions: wrap the gate with the configurable classifier
+    // BEFORE setConfirmer so the wrapper captures the interactive confirmer.
+    // Inactive (delegating) unless the session mode is "auto"; not installed
+    // at all when settings don't customize the map (byte-identical path).
+    try {
+      const {
+        loadAutoModeConfig,
+        resolveAutoModeDecisions,
+        createAutoModeApprovalGate,
+      } = await import("../lib/auto-mode-config.js");
+      _autoModeResolved = resolveAutoModeDecisions(
+        loadAutoModeConfig({ cwd: process.cwd() }).effective,
+      );
+      if (_autoModeResolved.customized) {
+        _approvalGate = createAutoModeApprovalGate(
+          _approvalGate,
+          _autoModeResolved,
+          { isActive: () => _sessionTier === "auto" },
+        );
+      }
+    } catch (_err) {
+      _autoModeResolved = null; // fail to the plain gate tiers
+    }
     if (typeof _approvalGate.setConfirmer === "function") {
       _approvalGate.setConfirmer(async ({ tool, args, riskLevel }) => {
+        if (_dontAskActive()) {
+          process.stdout.write(
+            chalk.yellow(
+              `\n  ✕ denied without asking (dontAsk mode): ${riskLevel || "medium"}-risk ${tool || "run_shell"}${args?.command ? " — " + args.command : ""}\n`,
+            ),
+          );
+          return false;
+        }
         await _fireNotification(
           `Permission needed: ${riskLevel || "medium"}-risk ${tool || "run_shell"}${args?.command ? " — " + args.command : ""}`,
         );
@@ -630,6 +696,14 @@ export async function startAgentRepl(options = {}) {
     // Confirmer is shared by permission `ask` rules AND hook `ask` decisions,
     // so define it unconditionally (a `hook:` rule label flows through too).
     _permissionConfirm = async ({ tool, args, rule, reason }) => {
+      if (_dontAskActive()) {
+        process.stdout.write(
+          chalk.yellow(
+            `\n  ✕ denied without asking (dontAsk mode): ${tool}${rule ? ` (${rule})` : reason ? ` — ${reason}` : ""}\n`,
+          ),
+        );
+        return false;
+      }
       await _fireNotification(
         `Permission needed: ${tool}${rule ? " (" + rule + ")" : ""}`,
       );
@@ -1021,6 +1095,27 @@ export async function startAgentRepl(options = {}) {
               `(mcp__<server>__<tool>)`,
           ),
         );
+        // MCP tool search (context scaling): defer big tool schemas behind the
+        // internal tool_search tool. Below-threshold / disabled → no-op.
+        try {
+          const { maybeApplyToolSearch } =
+            await import("../runtime/mcp-tool-search.js");
+          const ts = maybeApplyToolSearch(_adhocMcp, {
+            model,
+            provider,
+            cwd: process.cwd(),
+          });
+          if (ts) {
+            logger.log(
+              chalk.gray(
+                `MCP: tool search active — ${ts.deferredCount} schema(s) ` +
+                  `deferred (~${ts.savedTokens} tok saved)`,
+              ),
+            );
+          }
+        } catch (_err) {
+          // best-effort — full schemas still work without deferral
+        }
       }
     } catch (mcpErr) {
       logger.log(chalk.yellow(`MCP: --mcp-config failed — ${mcpErr.message}`));
@@ -1045,6 +1140,27 @@ export async function startAgentRepl(options = {}) {
     }
   }
 
+  // --permission-mode for the interactive session (headless parity): manual →
+  // strict, acceptEdits → trusted, bypassPermissions → autopilot, and auto →
+  // trusted tier + the autoMode.decisions classifier. An explicit flag wins
+  // over the bundle's approvalPolicy default. Unknown values are ignored here
+  // (headless validates them; interactively we just keep the default tier).
+  if (options.permissionMode && _approvalGate && sessionId) {
+    const parsed = parsePermissionModeArg(options.permissionMode);
+    if (parsed && typeof _approvalGate.setSessionPolicy === "function") {
+      try {
+        _approvalGate.setSessionPolicy(sessionId, parsed.tier);
+        _sessionTier = parsed.auto
+          ? "auto"
+          : parsed.dontAsk
+            ? "dontAsk"
+            : parsed.tier;
+      } catch (_err) {
+        // Non-critical — keep the default tier
+      }
+    }
+  }
+
   // Phase G #5 — inject top-K memory recall into system prompt for new sessions
   // Skip on resume (existing context already reflects prior work) and when
   // --no-recall-memory is passed.
@@ -1394,7 +1510,9 @@ export async function startAgentRepl(options = {}) {
           sessionId &&
           typeof _approvalGate.setSessionPolicy === "function"
         ) {
-          const next = nextTier(_sessionTier);
+          // "auto" rides the trusted tier, so it cycles as trusted → autopilot
+          // (cycling is also how you exit auto mode without /permissions).
+          const next = nextTier(gateTierFor(_sessionTier));
           try {
             _approvalGate.setSessionPolicy(sessionId, next);
             _sessionTier = next;
@@ -1741,7 +1859,7 @@ export async function startAgentRepl(options = {}) {
         `  ${chalk.cyan("/init")}       Inventory this folder into a cc.md project-memory file (/init [--force])`,
       );
       logger.log(
-        `  ${chalk.cyan("/context")}    Live context-window usage by role`,
+        `  ${chalk.cyan("/context")}    Live context-window usage by role + MCP tool schemas`,
       );
       logger.log(
         `  ${chalk.cyan("/copy")}       Copy last response to clipboard (/copy code → last code block)`,
@@ -2580,6 +2698,48 @@ export async function startAgentRepl(options = {}) {
               : ""
           }`,
         );
+        // MCP tool-schema share of the window (gap-analysis 第二阶段 item 3):
+        // the tools parameter rides along on EVERY request but isn't part of
+        // `messages`, so it's invisible to the role buckets above. Show the
+        // per-server schema cost + tool-search state + optimization advice.
+        if (_adhocMcp?.extraToolDefinitions?.length) {
+          const { describeMcpToolContext } =
+            await import("../runtime/mcp-tool-search.js");
+          const info = describeMcpToolContext(_adhocMcp, {
+            estimate: estimateTokens,
+            model,
+            provider,
+          });
+          if (info) {
+            const ts = info.toolSearch;
+            logger.log(chalk.bold("\nMCP tool schemas (sent every request):"));
+            for (const row of info.servers) {
+              const share = window
+                ? Math.round((row.sentTokens / window) * 100)
+                : 0;
+              logger.log(
+                `  ${row.server.padEnd(16)}${String(row.sentTokens).padStart(7)} tok ${String(share).padStart(3)}%` +
+                  chalk.gray(
+                    `  (${row.tools} tools${
+                      row.deferred ? `, ${row.deferred} deferred` : ""
+                    })`,
+                  ),
+              );
+            }
+            logger.log(
+              `  ${"total".padEnd(16)}${String(info.sentTokens).padStart(7)} tok` +
+                (ts.active
+                  ? chalk.gray(
+                      `  (tool search: ${ts.deferredCount} deferred, ` +
+                        `${ts.loadedCount} loaded, ~${info.savedTokens} tok saved)`,
+                    )
+                  : ""),
+            );
+            for (const line of info.advice) {
+              logger.log(chalk.yellow(`  ⚠ ${line}`));
+            }
+          }
+        }
       } catch (err) {
         logger.error(`/context failed: ${err.message}`);
       }
@@ -3740,17 +3900,22 @@ export async function startAgentRepl(options = {}) {
         // Review what the agent was BLOCKED from running this session
         // (Claude-Code 2.1.193 "recent denials").
         logger.log(formatDenials(_recentDenials));
+        logger.log(
+          chalk.gray(
+            "  Cross-session history (headless + REPL): cc permissions recent",
+          ),
+        );
         prompt();
         return;
       }
       if (arg) {
-        // Set this session's approval tier mid-session (Claude-Code
+        // Set this session's permission mode mid-session (Claude-Code
         // permission-mode / Shift+Tab parity; mirrors `cc session policy --set`).
-        const tier = parsePermissionTier(arg);
-        if (!tier) {
+        const parsed = parsePermissionModeArg(arg);
+        if (!parsed) {
           logger.info(
-            "Usage: /permissions [strict|trusted|autopilot]  " +
-              "(aliases: default · accept-edits · bypass). No arg = show rules.",
+            "Usage: /permissions [strict|trusted|autopilot|auto|dontask]  " +
+              "(aliases: default · manual · accept-edits · bypass). No arg = show rules.",
           );
         } else if (
           !_approvalGate ||
@@ -3762,11 +3927,31 @@ export async function startAgentRepl(options = {}) {
           );
         } else {
           try {
-            _approvalGate.setSessionPolicy(sessionId, tier);
-            _sessionTier = tier;
+            _approvalGate.setSessionPolicy(sessionId, parsed.tier);
+            _sessionTier = parsed.auto
+              ? "auto"
+              : parsed.dontAsk
+                ? "dontAsk"
+                : parsed.tier;
             logger.info(
-              `Approval policy → ${chalk.cyan(tier)} ${chalk.gray(`(${describeTier(tier)})`)}`,
+              `Approval policy → ${chalk.cyan(_sessionTier)} ${chalk.gray(`(${describeTier(_sessionTier)})`)}`,
             );
+            if (parsed.auto) {
+              if (_autoModeResolved?.customized) {
+                const m = _autoModeResolved.map;
+                logger.info(
+                  chalk.gray(
+                    `  autoMode.decisions: low→${m.low.decision} · medium→${m.medium.decision} · high→${m.high.decision}  (cc auto-mode config for sources)`,
+                  ),
+                );
+              } else {
+                logger.info(
+                  chalk.gray(
+                    "  no customized autoMode.decisions in settings — auto behaves like trusted",
+                  ),
+                );
+              }
+            }
           } catch (_err) {
             logger.info("Could not set the approval policy.");
           }
@@ -3785,7 +3970,12 @@ export async function startAgentRepl(options = {}) {
       logger.log(renderPermissions(_permissionRules, { files }));
       logger.log(
         chalk.gray(
-          "  Set tier mid-session: /permissions <strict|trusted|autopilot>",
+          `  Current mode: ${_sessionTier} (${describeTier(_sessionTier)})`,
+        ),
+      );
+      logger.log(
+        chalk.gray(
+          "  Set tier mid-session: /permissions <strict|trusted|autopilot|auto|dontask>",
         ),
       );
       if (_recentDenials.length) {
@@ -4371,6 +4561,8 @@ export async function startAgentRepl(options = {}) {
         checkpointSession: sessionId,
         checkpointMarks: _checkpointMarks,
         denialLog: _recentDenials,
+        persistRecentDenials: true,
+        permissionMode: _sessionTier,
         prepareCall,
         approvalGate: _approvalGate,
         permissionRules: _permissionRules,

package/src/repl/permission-tier.js

@@ -10,6 +10,7 @@ const TIER_ALIASES = {
   // strict — every risky action asks (the default)
   strict: "strict",
   default: "strict",
+  manual: "strict",
   normal: "strict",
   off: "strict",
   // trusted — low/medium-risk auto-approved, high-risk still asks (acceptEdits)
@@ -45,6 +46,32 @@ export function parsePermissionTier(arg) {
     : null;
 }
 
+const AUTO_ALIASES = new Set(["auto", "auto-mode", "automode"]);
+const DONT_ASK_ALIASES = new Set(["dontask", "dont-ask", "noask", "no-ask"]);
+
+/**
+ * Parse a permission-mode argument that may also be `auto` (the configurable
+ * autoMode.decisions classifier) or `dontAsk` (anything that would prompt is
+ * denied instead — headless semantics brought to the interactive session).
+ * Auto rides the trusted gate tier; dontAsk rides strict; the REPL activates
+ * the matching behavior while the mode is engaged.
+ *
+ * @param {string} arg
+ * @returns {{ tier: "strict"|"trusted"|"autopilot", auto: boolean, dontAsk: boolean } | null}
+ */
+export function parsePermissionModeArg(arg) {
+  const a = String(arg == null ? "" : arg)
+    .trim()
+    .toLowerCase();
+  if (AUTO_ALIASES.has(a))
+    return { tier: "trusted", auto: true, dontAsk: false };
+  if (DONT_ASK_ALIASES.has(a)) {
+    return { tier: "strict", auto: false, dontAsk: true };
+  }
+  const tier = parsePermissionTier(a);
+  return tier ? { tier, auto: false, dontAsk: false } : null;
+}
+
 /** One-line description of what a tier auto-approves. */
 export function describeTier(tier) {
   switch (tier) {
@@ -54,6 +81,10 @@ export function describeTier(tier) {
       return "low/medium-risk auto-approved; high-risk still asks";
     case "strict":
       return "every risky action asks";
+    case "auto":
+      return "autoMode.decisions classifier (riskLevel → allow/ask/deny); unconfigured = trusted";
+    case "dontAsk":
+      return "anything that would ask is denied instead (no prompts)";
     default:
       return "";
   }

package/src/runtime/agent-core.js

@@ -64,6 +64,7 @@ import {
   toOllamaMessages,
   imageUrlBlockToAnthropic,
 } from "../lib/image-input.js";
+import { executeToolSearch, gateDeferredMcpCall } from "./mcp-tool-search.js";
 
 /**
  * Names of MCP servers currently mounted by an in-flight run_skill call.
@@ -1439,6 +1440,7 @@ export async function executeTool(name, args, context = {}) {
       additionalDirectories: context.additionalDirectories || null,
       sandbox: context.sandbox || null,
       ruleAllowed,
+      settingsVerdict,
       subAgentDepth: context.subAgentDepth || 0,
       subAgentBudget: context.subAgentBudget || null,
       interactiveApproval: context.interactiveApproval || false,
@@ -2057,6 +2059,7 @@ async function executeToolInner(
     additionalDirectories,
     sandbox,
     ruleAllowed = false,
+    settingsVerdict = null,
     subAgentDepth = 0,
     subAgentBudget = null,
     interactiveApproval = false,
@@ -2338,6 +2341,40 @@ async function executeToolInner(
           : {}),
         ...(classifyAllShell ? { classifyAllShell: true } : {}),
       };
+      // Layer-by-layer explanation chain for a blocked command: which layers
+      // were consulted and what each said (settings rules → shell policy →
+      // approval gate). Attached to denial results so `/permissions denials`
+      // and `cc permissions recent` can explain WHY, not just THAT.
+      const buildPermissionChain = (gated) => {
+        const chain = [
+          {
+            layer: "settings-rules",
+            outcome:
+              settingsVerdict?.decision || (ruleAllowed ? "allow" : "no-match"),
+            rule: settingsVerdict?.rule || null,
+          },
+          {
+            layer: "shell-policy",
+            outcome: shellPolicy?.decision || null,
+            rule: shellPolicy?.ruleId || null,
+            reason: shellPolicy?.reason || null,
+          },
+        ];
+        // A hard shell-policy deny returns before the gate is consulted
+        // (via === "shell-policy") — no approval-gate layer to explain then.
+        if (gated && gated.via !== "shell-policy") {
+          chain.push({
+            layer: "approval-gate",
+            outcome: gated.decision,
+            via: gated.via || null,
+            policy: gated.policy || null,
+            riskLevel: gated.riskLevel || null,
+            rule: gated.gateRule || null,
+            reason: gated.gateReason || null,
+          });
+        }
+        return chain;
+      };
       const override = getRuntimeToolDescriptorByCommand(args.command);
       let shellPolicy;
       let approvalOutcome = null;
@@ -2375,6 +2412,7 @@ async function executeToolInner(
                   : `[ApprovalGate] command denied by the ${tierLabel}approval policy (via ${gated.via}). Retrying the same command will not help — it needs user approval. Tell the user (they can run it themselves, approve it, or relax the policy) and continue with other work.`,
               shellCommandPolicy: shellPolicy,
               approval: approvalOutcome,
+              permissionChain: buildPermissionChain(gated),
             },
             override || runtimeDescriptor,
           );
@@ -2386,6 +2424,7 @@ async function executeToolInner(
             {
               error: `[Shell Policy] ${shellPolicy.reason} This command is blocked by policy and will not run — do not retry it; find another approach.`,
               shellCommandPolicy: shellPolicy,
+              permissionChain: buildPermissionChain(null),
             },
             override || runtimeDescriptor,
           );
@@ -3347,6 +3386,15 @@ async function executeToolInner(
         }
       }
 
+      // Internal tool-search tool (MCP context scaling): resolves deferred
+      // MCP tool schemas from the registry attached at setup time. Read-only,
+      // local — same risk class as list_skills, so no approval gate.
+      if (localToolExecutor?.kind === "tool-search") {
+        return attachDescriptor(
+          executeToolSearch(localToolExecutor.registry, args || {}),
+        );
+      }
+
       if (localToolExecutor?.kind === "mcp") {
         if (!mcpClient || typeof mcpClient.callTool !== "function") {
           return attachDescriptor({
@@ -3354,6 +3402,15 @@ async function executeToolInner(
           });
         }
 
+        // Deferred-schema gate: a direct call to a tool whose schema was never
+        // loaded returns a self-healing error embedding the schema (and marks
+        // it loaded), instead of forwarding likely-malformed arguments to the
+        // server. No-op unless tool search deferred this tool.
+        const deferredGate = gateDeferredMcpCall(name, localToolExecutor);
+        if (deferredGate) {
+          return attachDescriptor(deferredGate);
+        }
+
         try {
           const result = await mcpClient.callTool(
             localToolExecutor.serverName,