mixdog 0.9.19 → 0.9.21

package/src/session-runtime/session-turn-api.mjs

@@ -0,0 +1,274 @@
+import { clean } from './session-text.mjs';
+import { envFlag } from './env.mjs';
+import { normalizeToolMode } from './effort.mjs';
+import {
+  toolRow,
+  toolSearchMatches,
+  sortedNamesByMeasuredUsage,
+  selectDeferredTools,
+} from './tool-catalog.mjs';
+
+// Turn execution (ask) + session-manage/tool-surface/agent surfaces. Extracted
+// verbatim from the runtime API object; stateless helpers are imported directly
+// and the runtime injects live getters/setters for the mutable session/mode/
+// turn-counter/transcript-writer locals plus the closure callbacks.
+export function createSessionTurnApi(deps) {
+  const {
+    getSession, setSession, getCurrentCwd, getMode, setMode,
+    getActiveTurnCount, setActiveTurnCount, isFirstTurnCompleted, setFirstTurnCompleted,
+    getCodeGraphFirstTurnPrewarmDone, setCodeGraphFirstTurnPrewarmDone, codeGraphPrewarmLazy,
+    getRemoteEnabled, getCloseRequested,
+    getPendingSessionReset, setPendingSessionReset,
+    getTranscriptWriter, getTwKey, getLastAppendedAssistant, setLastAppendedAssistant,
+    scheduleCodeGraphPrewarm, refreshSessionForCwdIfNeeded, createCurrentSession,
+    ensureRemoteTranscriptWriter, channelsEnabled, invokeChannelStart, channels,
+    hooks, hookCommonPayload, mgr, notifyFnForSession, bootProfile,
+    scheduleProviderWarmup, scheduleProviderModelWarmup, invalidateContextStatusCache,
+    agentTool, recreateCurrentSessionIfReady, invalidatePreSessionToolSurface,
+    activeToolSurface, applyResolvedCwd, resolveCwdPath, agentStatusState, notificationListeners,
+  } = deps;
+  return {
+    async ask(prompt, options = {}) {
+      setActiveTurnCount(getActiveTurnCount() + 1);
+      // Lazy code-graph prewarm: kick off the build ONCE, on the first real
+      // turn, so a likely code lookup hits a warm cache.
+      if (codeGraphPrewarmLazy && !getCodeGraphFirstTurnPrewarmDone()) {
+        setCodeGraphFirstTurnPrewarmDone(true);
+        scheduleCodeGraphPrewarm(0, 'first-turn');
+      }
+      const startedAt = Date.now();
+      try {
+        await refreshSessionForCwdIfNeeded('cwd-change');
+        if (!getSession()?.id) await createCurrentSession('turn');
+        // Remote outbound: ensure a transcript writer bound to the current
+        // session.id + cwd. Gated on remoteEnabled so non-remote sessions write nothing.
+        if (getRemoteEnabled()) {
+          setLastAppendedAssistant('');
+          const prevKey = getTwKey();
+          ensureRemoteTranscriptWriter();
+          if (getTwKey() && getTwKey() !== prevKey && channelsEnabled() && !envFlag('MIXDOG_DISABLE_CHANNEL_START')) {
+            void invokeChannelStart()
+              .then(() => {
+                if (!getRemoteEnabled() || getCloseRequested()) return undefined;
+                return channels.execute('activate_channel_bridge', { active: true });
+              })
+              .catch((error) => bootProfile('channels:turn-rebind-failed', { error: error?.message || String(error) }));
+          }
+        }
+        const session0 = getSession();
+        hooks.emit('turn:start', { sessionId: session0.id, prompt, cwd: getCurrentCwd() });
+        // UserPromptSubmit: a hook FAILURE must not block the turn, but blocked===true MUST throw.
+        let promptDispatch = null;
+        try {
+          promptDispatch = await hooks.dispatch('UserPromptSubmit', hookCommonPayload({ session_id: session0.id, prompt }));
+        } catch { /* hook failure never blocks the turn */ }
+        if (promptDispatch?.blocked === true) {
+          throw new Error(`prompt blocked by hook: ${promptDispatch.reason || ''}`);
+        }
+        const hookContext = Array.isArray(promptDispatch?.additionalContext)
+          ? promptDispatch.additionalContext.join('\n\n')
+          : String(promptDispatch?.additionalContext || '');
+        const turnContext = [options.context || '', hookContext]
+          .map((part) => String(part || '').trim())
+          .filter(Boolean)
+          .join('\n\n');
+        const result = await mgr.askSession(
+          session0.id,
+          prompt,
+          turnContext || null,
+          async (iter, calls) => {
+            for (const call of calls || []) {
+              hooks.emit('tool:planned', {
+                sessionId: session0.id,
+                name: call?.name || 'tool',
+                callId: call?.id || null,
+              });
+              if (getRemoteEnabled() && getTranscriptWriter()) {
+                try { getTranscriptWriter().appendToolUse(call?.name, call?.input ?? call?.arguments); }
+                catch (error) { process.stderr.write(`mixdog: transcript-writer: onToolCall failed: ${error?.message || error}\n`); }
+              }
+            }
+            if (typeof options.onToolCall === 'function') {
+              return await options.onToolCall(iter, calls);
+            }
+            return undefined;
+          },
+          getCurrentCwd(),
+          options.prefetch || null,
+          {
+            onTextDelta: options.onTextDelta,
+            onReasoningDelta: options.onReasoningDelta,
+            onAssistantText: (text) => {
+              if (getRemoteEnabled() && getTranscriptWriter()) {
+                try {
+                  const value = typeof text === 'string' ? text : (text == null ? '' : String(text));
+                  if (value.trim()) {
+                    getTranscriptWriter().appendAssistant(value);
+                    setLastAppendedAssistant(value);
+                  }
+                }
+                catch (error) { process.stderr.write(`mixdog: transcript-writer: onAssistantText failed: ${error?.message || error}\n`); }
+              }
+              return options.onAssistantText?.(text);
+            },
+            onUsageDelta: options.onUsageDelta,
+            onToolResult: (message) => {
+              if (getRemoteEnabled() && getTranscriptWriter()) {
+                try {
+                  const tur = message?.toolUseResult;
+                  if (tur && (tur.oldString != null || tur.newString != null)) {
+                    getTranscriptWriter().appendToolResult({ oldString: tur.oldString ?? '', newString: tur.newString ?? '' });
+                  }
+                } catch (error) { process.stderr.write(`mixdog: transcript-writer: onToolResult failed: ${error?.message || error}\n`); }
+              }
+              return options.onToolResult?.(message);
+            },
+            onToolApproval: options.onToolApproval,
+            onCompactEvent: options.onCompactEvent,
+            onStageChange: options.onStageChange,
+            onStreamDelta: options.onStreamDelta,
+            drainSteering: options.drainSteering,
+            onSteerMessage: options.onSteerMessage,
+            notifyFn: notifyFnForSession(session0.id),
+          },
+        );
+        setSession(mgr.getSession(session0.id) || getSession());
+        if (getRemoteEnabled() && getTranscriptWriter()) {
+          try {
+            const finalText = result?.content != null ? String(result.content) : '';
+            if (finalText.trim() && finalText !== getLastAppendedAssistant()) {
+              getTranscriptWriter().appendAssistant(finalText);
+              setLastAppendedAssistant(finalText);
+            }
+          } catch (error) {
+            process.stderr.write(`mixdog: transcript-writer: final append failed: ${error?.message || error}\n`);
+          }
+        }
+        hooks.emit('turn:end', { sessionId: session0.id, elapsedMs: Date.now() - startedAt });
+        try {
+          await hooks.dispatch('Stop', hookCommonPayload({ session_id: session0.id }));
+        } catch { /* best-effort: Stop hook must never break the turn */ }
+        return { result, session: getSession() };
+      } catch (error) {
+        hooks.emit('turn:error', { sessionId: getSession()?.id || null, elapsedMs: Date.now() - startedAt, error: error?.message || String(error) });
+        try {
+          const msg = String(error?.message || error || '').toLowerCase();
+          const errorType = /rate.?limit|429|too many requests/.test(msg) ? 'rate_limit'
+            : /overloaded|529/.test(msg) ? 'overloaded'
+            : /authenticat|unauthorized|401|invalid.*api.?key/.test(msg) ? 'authentication_failed'
+            : /server.?error|5\d\d|internal error/.test(msg) ? 'server_error'
+            : 'unknown';
+          void hooks.dispatch('StopFailure', hookCommonPayload({ session_id: getSession()?.id || null, error_type: errorType }));
+        } catch { /* best-effort: StopFailure hook must never break teardown */ }
+        throw error;
+      } finally {
+        setActiveTurnCount(Math.max(0, getActiveTurnCount() - 1));
+        if (!isFirstTurnCompleted()) {
+          setFirstTurnCompleted(true);
+          scheduleProviderWarmup();
+          scheduleProviderModelWarmup();
+        }
+      }
+    },
+    async clear(options = {}) {
+      const session = getSession();
+      if (!session?.id) return false;
+      const cleared = await mgr.clearSessionMessages(session.id, options);
+      if (!cleared) return false;
+      setSession(typeof cleared === 'object' ? cleared : (mgr.getSession(session.id) || session));
+      if (options.recoverAgent === true) {
+        try { agentTool.recoverWorkers?.({ clientHostPid: getSession()?.clientHostPid || process.pid }); } catch {}
+      }
+      invalidateContextStatusCache();
+      return true;
+    },
+    // session_manage tool handoff: the engine polls this at turn end and, if
+    // set, runs the same clear path the idle auto-clear uses. One-shot read.
+    consumePendingSessionReset() {
+      const pending = getPendingSessionReset();
+      setPendingSessionReset(null);
+      if (!pending) return null;
+      const session = getSession();
+      // Session changed since scheduling (resume / new session) — drop it.
+      if (!session?.id || pending.sessionId !== session.id) return null;
+      return pending.action;
+    },
+    async compact(options = {}) {
+      const session = getSession();
+      if (!session?.id) return null;
+      if (getActiveTurnCount() > 0) {
+        return { changed: false, reason: 'compact skipped: turn in progress' };
+      }
+      // Manual compact bypasses loop.mjs, so its PreCompact/PostCompact never
+      // fire here — dispatch them explicitly via the session-property hooks.
+      try { await session.preCompactHook?.({ trigger: 'manual' }); }
+      catch { /* best-effort: PreCompact hook must never break manual compact */ }
+      const result = await mgr.compactSessionMessages(session.id);
+      try { await session.postCompactHook?.({ trigger: 'manual' }); }
+      catch { /* best-effort: PostCompact hook must never break manual compact */ }
+      setSession(mgr.getSession(session.id) || session);
+      if (options.recoverAgent === true) {
+        try { agentTool.recoverWorkers?.({ clientHostPid: getSession()?.clientHostPid || process.pid }); } catch {}
+      }
+      invalidateContextStatusCache();
+      return result;
+    },
+    async setToolMode(nextMode) {
+      const mode = normalizeToolMode(nextMode);
+      setMode(mode);
+      invalidatePreSessionToolSurface();
+      const session = getSession();
+      if (session?.id) mgr.closeSession(session.id, 'cli-mode-switch');
+      await recreateCurrentSessionIfReady();
+      return mode;
+    },
+    agentStatus() {
+      return agentStatusState();
+    },
+    agentControl(args = {}) {
+      const session = getSession();
+      const callerSessionId = session?.id || null;
+      return agentTool.execute(args, {
+        callerCwd: getCurrentCwd(),
+        invocationSource: 'user-command',
+        callerSessionId,
+        clientHostPid: session?.clientHostPid || process.pid,
+        notifyFn: notifyFnForSession(callerSessionId),
+      });
+    },
+    onNotification(listener) {
+      if (typeof listener !== 'function') return () => {};
+      notificationListeners.add(listener);
+      return () => notificationListeners.delete(listener);
+    },
+    toolsStatus(query = '') {
+      const surface = activeToolSurface();
+      const catalog = Array.isArray(surface?.deferredToolCatalog)
+        ? surface.deferredToolCatalog
+        : (Array.isArray(surface?.tools) ? surface.tools : []);
+      const activeNames = new Set((surface?.tools || []).map((tool) => tool?.name).filter(Boolean));
+      const needle = clean(query).toLowerCase();
+      const rows = catalog.map((tool) => toolRow(tool, activeNames)).filter((row) => row.name);
+      const tools = needle
+        ? rows.filter((row) => toolSearchMatches(row, needle))
+        : rows;
+      return {
+        mode: getMode(),
+        count: rows.length,
+        activeCount: rows.filter((row) => row.active).length,
+        tools,
+        activeTools: sortedNamesByMeasuredUsage(activeNames),
+        discoveredTools: sortedNamesByMeasuredUsage(surface?.deferredDiscoveredTools || []),
+      };
+    },
+    selectTools(names) {
+      const list = Array.isArray(names) ? names : String(names || '').split(/[,\s]+/);
+      const result = selectDeferredTools(activeToolSurface(), list, getMode());
+      return { ...result, status: this.toolsStatus() };
+    },
+    setCwd(path) {
+      applyResolvedCwd(resolveCwdPath(path));
+      return getCurrentCwd();
+    },
+  };
+}

package/src/session-runtime/tool-catalog.mjs

@@ -98,56 +98,6 @@ const DEFERRED_SELECT_ALIASES = {
   code: ['code_graph'],
   shell: ['shell', 'task'],
 };
-const TOOL_SEARCH_SAFE_AUTO_ALIASES = new Set([
-  'shell',
-  'web',
-  'search',
-  'agent',
-  'memory',
-]);
-const TOOL_SEARCH_AMBIGUOUS_AUTO_QUERIES = new Set([
-  'status',
-  'state',
-  'info',
-  'list',
-  'show',
-  'config',
-]);
-const TOOL_SEARCH_STOP_WORDS = new Set([
-  'a',
-  'an',
-  'and',
-  'are',
-  'as',
-  'for',
-  'from',
-  'how',
-  'i',
-  'in',
-  'is',
-  'me',
-  'need',
-  'of',
-  'on',
-  'please',
-  'the',
-  'to',
-  'tool',
-  'tools',
-  'use',
-  'using',
-  'with',
-]);
-const TOOL_SEARCH_ROW_ALIASES = Object.freeze({
-  agent: ['delegate', 'subagent', 'worker', 'parallel agent', 'background agent', 'reviewer', 'explorer'],
-  cwd: ['cwd', 'working directory', 'current directory', 'project root', 'folder'],
-  memory: ['save memory', 'store memory', 'delete memory', 'forget memory', 'memory status'],
-  recall: ['recall', 'previous work', 'past work', 'prior context', 'history', 'resume context'],
-  search: ['web search', 'internet search', 'current info', 'latest info', 'online search', 'docs search'],
-  shell: ['run command', 'execute command', 'terminal', 'powershell', 'bash', 'run tests', 'test command', 'build command', 'npm', 'node', 'git'],
-  task: ['background task', 'async task', 'wait task', 'cancel task', 'task status'],
-  web_fetch: ['fetch url', 'fetch page', 'open url', 'web page', 'read url', 'docs page'],
-});
 
 export function toolKind(tool) {
   const name = clean(tool?.name);
@@ -326,189 +276,14 @@ function toolSearchNativePayload(catalog, names, provider = '') {
   };
 }
 
-function toolSearchTokens(value) {
-  return (clean(value).toLowerCase().match(/[a-z0-9_.-]+/g) || [])
-    .map((token) => token.replace(/[-.]+/g, '_'))
-    .filter(Boolean);
-}
-
-function toolSearchMeaningfulTokens(value) {
-  return toolSearchTokens(value).filter((token) => !TOOL_SEARCH_STOP_WORDS.has(token));
-}
-
-function toolSearchText(row) {
-  const text = `${row.name} ${String(row.name || '').replace(/_/g, ' ')} ${row.kind} ${row.description} ${row.active ? 'active' : 'deferred'}`;
-  return `${text} ${text.replace(/[-.]+/g, '_')}`.toLowerCase();
-}
-
-function toolSearchRowAliases(name) {
-  return TOOL_SEARCH_ROW_ALIASES[clean(name)] || [];
-}
-
-function toolSearchRank(row, query) {
-  const raw = clean(query).toLowerCase();
-  if (!raw) return { score: 0, reasons: [] };
-  const name = clean(row?.name).toLowerCase();
-  const prettyName = name.replace(/_/g, ' ');
-  const haystack = toolSearchText(row);
-  const aliases = toolSearchRowAliases(name);
-  const aliasText = aliases.join(' ').toLowerCase();
-  const queryTokens = toolSearchMeaningfulTokens(raw);
-  const nameTokens = new Set(toolSearchTokens(`${name} ${prettyName}`));
-  const aliasTokens = new Set(toolSearchTokens(aliasText));
-  let score = 0;
-  const reasons = [];
-  if (raw === name || raw === prettyName) {
-    score += 120;
-    reasons.push('exact-name');
-  }
-  if (aliases.some((alias) => raw === alias || raw === alias.replace(/[_-]+/g, ' '))) {
-    score += 100;
-    reasons.push('exact-alias');
-  }
-  // Stop-word-only queries (e.g. "tool", "to") have zero meaningful tokens.
-  // Without an exact name/alias hit, they must not fall through to the raw
-  // substring/haystack checks below — every row description likely contains
-  // "tool" somewhere, producing a noisy pseudo-match list instead of "no
-  // results". Exact name/alias matches stay intact even when the name is
-  // itself a stop word.
-  if (!queryTokens.length && !reasons.length) {
-    return { score: 0, reasons: [] };
-  }
-  if (haystack.includes(raw)) {
-    score += 34;
-    reasons.push('phrase');
-  }
-  for (const alias of aliases) {
-    const normalizedAlias = alias.toLowerCase();
-    if (normalizedAlias && raw.includes(normalizedAlias)) {
-      score += 58;
-      reasons.push('alias-phrase');
-      break;
-    }
-  }
-  let matchedTokens = 0;
-  for (const token of queryTokens) {
-    if (nameTokens.has(token) || name.includes(token)) {
-      score += 24;
-      matchedTokens += 1;
-      continue;
-    }
-    if (aliasTokens.has(token) || aliasText.includes(token)) {
-      score += 18;
-      matchedTokens += 1;
-      continue;
-    }
-    if (haystack.includes(token)) {
-      score += 7;
-      matchedTokens += 1;
-    }
-  }
-  if (queryTokens.length && matchedTokens === queryTokens.length) {
-    score += Math.min(18, queryTokens.length * 6);
-    reasons.push('all-tokens');
-  }
-  if (clean(row?.kind).toLowerCase() === raw) score += 10;
-  if (score > 0) score += Math.min(6, Math.floor(measuredToolUsage(name) / 150));
-  return { score, reasons };
-}
-
+// Plain case-insensitive substring filter over name + description. No scores,
+// no aliases, no auto-selection: tool_search only lists and (via select)
+// loads. Empty query matches every row.
 export function toolSearchMatches(row, query) {
   const raw = clean(query).toLowerCase();
   if (!raw) return true;
-  return toolSearchRank(row, raw).score > 0;
-}
-
-function rankedToolSearchRows(rows, query) {
-  const raw = clean(query).toLowerCase();
-  if (!raw) return rows;
-  return rows
-    .map((row) => {
-      const ranked = toolSearchRank(row, raw);
-      return { ...row, score: ranked.score, reasons: ranked.reasons };
-    })
-    .filter((row) => row.score > 0)
-    .sort((a, b) => {
-      if (b.score !== a.score) return b.score - a.score;
-      if (a.active !== b.active) return a.active ? 1 : -1;
-      if (b.usage !== a.usage) return b.usage - a.usage;
-      return String(a.name).localeCompare(String(b.name));
-    });
-}
-
-function isAsciiWordChar(ch) {
-  return !!ch && /[A-Za-z0-9]/.test(ch);
-}
-
-// Matches `phrase` inside `text` at a word boundary. ASCII letters/digits on
-// either side of the match block it (so "webhook" does not match "web" and
-// "prune" does not match "run"); non-ASCII characters (e.g. Korean, where
-// words are not space-separated) never count as word chars, so Korean
-// substring phrases keep matching as before.
-function phraseMatchesAsWords(text, phrase) {
-  if (!phrase) return false;
-  let idx = text.indexOf(phrase);
-  while (idx !== -1) {
-    const before = idx > 0 ? text[idx - 1] : '';
-    const after = idx + phrase.length < text.length ? text[idx + phrase.length] : '';
-    if (!isAsciiWordChar(before) && !isAsciiWordChar(after)) return true;
-    idx = text.indexOf(phrase, idx + 1);
-  }
-  return false;
-}
-
-function queryHasAnyPhrase(query, phrases) {
-  const text = clean(query).toLowerCase().replace(/[_-]+/g, ' ');
-  return phrases.some((phrase) => phraseMatchesAsWords(text, phrase));
-}
-
-const TOOL_SEARCH_AUTO_CATEGORY_BRANCHES = [
-  {
-    names: ['memory'],
-    phrases: ['save memory', 'store memory', 'delete memory', 'forget memory', 'memory status', '기억 저장', '메모리 저장'],
-  },
-  {
-    names: ['shell', 'task'],
-    phrases: ['run', 'execute', 'test', 'tests', 'build', 'terminal', 'command', 'powershell', 'bash', 'shell', 'npm', 'node', 'git', '실행', '테스트', '빌드', '터미널', '쉘'],
-  },
-  {
-    names: ['search', 'web_fetch'],
-    phrases: ['web', 'internet', 'online', 'current info', 'latest', 'news', 'browse', 'docs', 'documentation', '웹', '인터넷', '최신', '뉴스', '문서'],
-  },
-  {
-    names: ['recall'],
-    phrases: ['recall', 'remember', 'memory previous', 'previous', 'history', 'past', 'prior', 'earlier', 'resume', '이전', '기억', '히스토리'],
-  },
-  {
-    names: ['agent'],
-    phrases: ['delegate', 'subagent', 'worker', 'parallel agent', 'background agent', 'reviewer', 'explorer', '에이전트', '워커', '병렬'],
-  },
-  {
-    names: ['cwd'],
-    phrases: ['working directory', 'project root', 'current directory', 'cwd'],
-  },
-];
-
-function autoToolSelectionNames(query, rows) {
-  const raw = clean(query).toLowerCase();
-  if (!raw || TOOL_SEARCH_AMBIGUOUS_AUTO_QUERIES.has(raw)) return [];
-  if (TOOL_SEARCH_SAFE_AUTO_ALIASES.has(raw) && DEFERRED_SELECT_ALIASES[raw]) {
-    return DEFERRED_SELECT_ALIASES[raw];
-  }
-  const matchedBranches = TOOL_SEARCH_AUTO_CATEGORY_BRANCHES.filter((branch) =>
-    queryHasAnyPhrase(raw, branch.phrases)
-  );
-  if (matchedBranches.length === 1) return matchedBranches[0].names;
-  // Ambiguous (0 or 2+ category branches matched): never auto-load a
-  // category's tools off a possibly-wrong guess. Fall through to the ranked
-  // exact-name/alias path below; that path returns [] on its own when there
-  // is no exact match, so an ambiguous query still safely resolves to [].
-  const ranked = rankedToolSearchRows(rows, raw);
-  const top = ranked[0];
-  if (!top) return [];
-  const reasons = new Set(top.reasons || []);
-  if (reasons.has('exact-name') || reasons.has('exact-alias')) return [top.name];
-  return [];
+  const haystack = `${clean(row?.name)} ${clean(row?.description)}`.toLowerCase();
+  return haystack.includes(raw);
 }
 
 function expandSelectionNames(names) {
@@ -694,39 +469,18 @@ export function renderToolSearch(args = {}, session, mode = 'full') {
   const forcedSelectedNames = explicitSelectedNames.length ? explicitSelectedNames : querySelectedNames;
   const query = querySelectedNames.length ? '' : rawQuery.toLowerCase();
   const limit = Math.max(1, Math.min(50, Number(args.limit) || 20));
-  const initialActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
-  const initialRows = catalog.map((tool) => toolRow(tool, initialActiveNames)).filter((row) => row.name);
-  const autoSelectedNames = (!forcedSelectedNames.length && query)
-    ? autoToolSelectionNames(query, initialRows)
-    : [];
-  const selectedNames = forcedSelectedNames.length ? forcedSelectedNames : autoSelectedNames;
-  let toolSelection = selectedNames.length ? selectDeferredTools(session, selectedNames, mode) : null;
-  let selectionMode = forcedSelectedNames.length ? 'select' : (autoSelectedNames.length ? 'auto' : null);
-  let nextActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
-  let rows = catalog.map((tool) => toolRow(tool, nextActiveNames)).filter((row) => row.name);
-  let matches = query
-    ? rankedToolSearchRows(rows, query)
-    : rows;
-  // Query hits must become loadable without a second explicit select turn:
-  // if the query produced ranked matches but the forced/auto path above
-  // loaded nothing (no exact-name/alias/category hit), fall back to
-  // auto-loading the ranked match names themselves (deferred/non-active
-  // only, capped at `limit`). Ambiguous queries stay excluded so a guess
-  // never silently loads a wrong category.
-  const STRONG_MATCH_REASONS = new Set(['exact-name', 'exact-alias', 'alias-phrase', 'phrase', 'all-tokens']);
-  const isStrongMatch = (row) => row.score >= 24 || (row.reasons || []).some((reason) => STRONG_MATCH_REASONS.has(reason));
-  const queryLoadedNothing = !toolSelection
-    || (!toolSelection.added.length && !toolSelection.already.length);
-  if (query && !TOOL_SEARCH_AMBIGUOUS_AUTO_QUERIES.has(query) && matches.length && queryLoadedNothing) {
-    const fallbackNames = matches.filter((row) => !row.active && isStrongMatch(row)).map((row) => row.name).slice(0, limit);
-    if (fallbackNames.length) {
-      toolSelection = selectDeferredTools(session, fallbackNames, mode);
-      selectionMode = 'query';
-      nextActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
-      rows = catalog.map((tool) => toolRow(tool, nextActiveNames)).filter((row) => row.name);
-      matches = query ? rankedToolSearchRows(rows, query) : rows;
-    }
-  }
+  // Explicit loader only: select names/aliases (or query "select:a,b") load
+  // deferred tools. A plain query is a case-insensitive substring filter over
+  // name+description for listing — it never loads. No scores, no ranking, no
+  // category auto-load: deferred tools are called directly (they auto-promote
+  // via deferred call-through) and are advertised in the system-prompt manifest.
+  const toolSelection = forcedSelectedNames.length
+    ? selectDeferredTools(session, forcedSelectedNames, mode)
+    : null;
+  const selectionMode = forcedSelectedNames.length ? 'select' : null;
+  const nextActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
+  const rows = catalog.map((tool) => toolRow(tool, nextActiveNames)).filter((row) => row.name);
+  const matches = query ? rows.filter((row) => toolSearchMatches(row, query)) : rows;
   const selected = toolSelection
     ? {
         mode: selectionMode,
@@ -743,6 +497,6 @@ export function renderToolSearch(args = {}, session, mode = 'full') {
     matches: matches.slice(0, limit),
     activeTools: sortedNamesByMeasuredUsage(nextActiveNames),
     discoveredTools: sortedNamesByMeasuredUsage(session?.deferredDiscoveredTools || []),
-    note: 'query ranks matches and auto-loads high-confidence deferred tools, including ranked search hits (deferred, non-active) up to limit; already-loaded/discovered tools are re-surfaced on re-selection; select exact tool names, or query select:a,b, to force load.',
+    note: 'Deferred tools listed in the system-prompt manifest can be called directly by name (they auto-load on first call). This tool only lists (query = case-insensitive substring over name+description; never loads) or loads exact tools when you pass select names/aliases or query "select:a,b".',
   }, null, 2);
 }

package/src/session-runtime/tool-defs.mjs

@@ -13,11 +13,11 @@ export const TOOL_SEARCH_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  description: 'Search deferred tools; confident queries load matches.',
+  description: 'List deferred tools by name+description substring, or load exact tools via select. Deferred tools can also be called directly by name.',
   inputSchema: {
     type: 'object',
     properties: {
-      query: { type: 'string', description: 'Search text; confident hits load. select:a,b forces exact names.' },
+      query: { type: 'string', description: 'Case-insensitive substring filter over deferred tool name+description (lists only, no load). Use select:a,b to load exact names.' },
       select: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: 'Force exact tool names.' },
       limit: { type: 'number', description: 'Max matches.' },
     },