mixdog 1.2.3 → 1.2.4

package/src/runtime/agent/orchestrator/providers/opencode-go-gemini.mjs

@@ -23,7 +23,14 @@ import { reloadProviderApiKey, resolveProviderApiKey } from '../../../shared/pro
 const PROVIDER = 'opencode-go';
 
 /** The generateContent request body for a built Gemini request. */
-export function openCodeGoGeminiBody({ contents, systemInstruction, geminiTools, toolConfig, generationConfig, safetySettings }) {
+export function openCodeGoGeminiBody({
+  contents,
+  systemInstruction,
+  geminiTools,
+  toolConfig,
+  generationConfig,
+  safetySettings,
+}) {
   return {
     contents,
     ...(systemInstruction ? { systemInstruction: { parts: [{ text: systemInstruction }] } } : {}),
@@ -84,7 +91,11 @@ export class OpenCodeGoGeminiEngine extends GeminiProvider {
   }
 
   async _openGatewayStream(url, body, opts, attemptSignal) {
-    const openFirstByte = createTimeoutSignal(attemptSignal, GEMINI_FIRST_BYTE_TIMEOUT_MS, 'OpenCode Go Gemini first byte');
+    const openFirstByte = createTimeoutSignal(
+      attemptSignal,
+      GEMINI_FIRST_BYTE_TIMEOUT_MS,
+      'OpenCode Go Gemini first byte'
+    );
     let res;
     try {
       res = await this._fetch(url, {

package/src/runtime/agent/orchestrator/providers/opencode-go.mjs

@@ -162,7 +162,10 @@ export class OpenCodeGoProvider {
       this.gemini = new OpenCodeGoGeminiEngine({
         ...this.config,
         baseURL: this.openai.baseURL,
-        extraHeaders: { ...(OPENAI_COMPAT_PRESETS['opencode-go'].extraHeaders || {}), ...(this.config.extraHeaders || {}) },
+        extraHeaders: {
+          ...(OPENAI_COMPAT_PRESETS['opencode-go'].extraHeaders || {}),
+          ...(this.config.extraHeaders || {}),
+        },
       });
     }
     return this.gemini;

package/src/runtime/agent/orchestrator/providers/openrouter.mjs

@@ -69,7 +69,6 @@ export class OpenRouterProvider extends WireGatewayProvider {
     );
     // The roster's output ceiling is `top_provider.max_completion_tokens`.
     const fetchItems = this.openai._fetchModelItems.bind(this.openai);
-    this.openai._fetchModelItems = async (options) =>
-      (await fetchItems(options)).map(withTopProviderOutputCeiling);
+    this.openai._fetchModelItems = async (options) => (await fetchItems(options)).map(withTopProviderOutputCeiling);
   }
 }

package/src/runtime/agent/orchestrator/providers/provider-error-kind.mjs

@@ -517,7 +517,10 @@ const IN_FLIGHT_BUDGET_MAX_WAIT_MS = 60_000;
 function inFlightAdviceMs(err) {
   const advised = retryAfterMsFromError(err);
   if (advised != null) return advised;
-  for (const [name, unitMs] of [['retry-after-ms', 1], ['retry-after', 1000]]) {
+  for (const [name, unitMs] of [
+    ['retry-after-ms', 1],
+    ['retry-after', 1000],
+  ]) {
     const value = errorHeaderValue(err, name);
     const n = Number(value);
     if (value != null && String(value).trim() !== '' && Number.isFinite(n) && n >= 0) return n * unitMs;
@@ -650,7 +653,6 @@ export function providerErrorKind(err, options = {}) {
   // Validated account-pool evidence and boundary-stamped re-auth decide first.
   if (err.quotaExhausted && typeof err.quotaExhausted === 'object') return describe('quota_exhausted');
   if (chain.some((item) => item?.reauthRequired === true)) return describe('auth');
-
   if (isInFlightBudget402(chain, status, inFlightAdviceMs(err))) return describe('transient', IN_FLIGHT_BUDGET);
   // Every other 402 is a billing refusal, whatever generic retryable code
   // (server_error, rate_limit_exceeded) its body also carries.
@@ -661,8 +663,7 @@ export function providerErrorKind(err, options = {}) {
   // generic rate-limit code or status; they never turn an overload (or a more
   // specific refusal) into quota.
   const quotaFlagged =
-    options.quotaFlags !== false &&
-    chain.some((item) => item?.providerQuota === true || item?.quotaExceeded === true);
+    options.quotaFlags !== false && chain.some((item) => item?.providerQuota === true || item?.quotaExceeded === true);
   if (quotaFlagged && (!kind || kind === 'rate_limited')) kind = 'quota_exhausted';
   // Wordings, for untyped errors only (a typed code always decides).
   const text = options.text !== false && (!kind || kind === 'invalid_request') ? messageOf(err, chain) : '';

package/src/runtime/agent/orchestrator/providers/registry.mjs

@@ -24,7 +24,7 @@ const signatures = new Map();
 // preservation guard and the getProvider self-heal read it through these two
 // helpers so "usable right now" and "genuinely gone" are answered identically
 // in both places.
-const OAUTH_PROVIDER_NAMES = new Set([
+export const OAUTH_PROVIDER_NAMES = new Set([
   'anthropic-oauth',
   'openai-oauth',
   'grok-oauth',
@@ -498,6 +498,14 @@ export function providerInputExcludesCache(name) {
 export function providerNativePdf(name) {
   return providerTakesNativePdf(providers.get(String(name || '').toLowerCase()));
 }
+/**
+ * Whether the named provider's adapter declares `consumesReadWindows`: it
+ * needs the structured clip report of read results. A pure lookup; a proxy
+ * stand-in carries the PC adapter's declared trait.
+ */
+export function providerConsumesReadWindows(name) {
+  return providers.get(String(name || '').toLowerCase())?.consumesReadWindows === true;
+}
 export function getAllProviders() {
   // Defensive copy — callers must not mutate the live registry or retain
   // stale entries across re-init (initProviders rebuilds the map in place).

package/src/runtime/agent/orchestrator/providers/retry-classification.mjs

@@ -476,7 +476,8 @@ export function isContextOverflowError(err, _depth = 0) {
   const sizeTyped =
     typeof err === 'object' &&
     boundedCauseChain(err).some(
-      (item) => item && typeof item === 'object' && providerErrorKind(item, { text: false }).kind === REQUEST_TOO_LARGE_KIND
+      (item) =>
+        item && typeof item === 'object' && providerErrorKind(item, { text: false }).kind === REQUEST_TOO_LARGE_KIND
     );
   const patterns = sizeTyped ? TOKEN_CONTEXT_OVERFLOW_PATTERNS : CONTEXT_OVERFLOW_PATTERNS;
   const msg = (typeof err === 'string' ? err : err?.message) || '';

package/src/runtime/agent/orchestrator/providers/wire-gateway.mjs

@@ -15,7 +15,9 @@ import { resolveWireRoute, sendOnRoute } from './wire-route.mjs';
 function hasFileIdImage(value, depth = 0) {
   if (!value || typeof value !== 'object' || depth > 6) return false;
   if (Array.isArray(value)) return value.some((entry) => hasFileIdImage(entry, depth + 1));
-  const fileId = value.type === 'input_image' ? value.file_id : value.type === 'image' && value.source?.type === 'file' ? value.source.file_id : null;
+  let fileId = null;
+  if (value.type === 'input_image') fileId = value.file_id;
+  else if (value.type === 'image' && value.source?.type === 'file') fileId = value.source.file_id;
   if (typeof fileId === 'string' && fileId) return true;
   return hasFileIdImage(value.content, depth + 1);
 }
@@ -32,9 +34,12 @@ function hasFileIdImage(value, depth = 0) {
  */
 export function gatewayMessagesOpts(config, model, messages, opts) {
   const out = { ...(opts || {}) };
-  const ceiling = Math.floor(Number(typeof config?.modelMaxOutputTokens === 'function' ? config.modelMaxOutputTokens(model) : 0));
+  const ceiling = Math.floor(
+    Number(typeof config?.modelMaxOutputTokens === 'function' ? config.modelMaxOutputTokens(model) : 0)
+  );
   if (ceiling > 0 && out.modelMaxOutputTokens === undefined) out.modelMaxOutputTokens = ceiling;
-  if (typeof config?.messagesEffortProjection === 'function') out.messagesEffortProjection = config.messagesEffortProjection;
+  if (typeof config?.messagesEffortProjection === 'function')
+    out.messagesEffortProjection = config.messagesEffortProjection;
   if (config?.fileIdImageBeta && hasFileIdImage(messages)) {
     out.requestHeaders = { 'anthropic-beta': config.fileIdImageBeta, ...(out.requestHeaders || {}) };
   }
@@ -115,7 +120,9 @@ export class WireGatewayProvider {
 
   // The model's output ceiling: the gateway roster, else the shared catalog.
   _modelMaxOutputTokens(model) {
-    const declared = Number(this.getCachedModelInfo(model)?.outputTokens ?? getModelMetadataSync(model, this.name)?.outputTokens);
+    const declared = Number(
+      this.getCachedModelInfo(model)?.outputTokens ?? getModelMetadataSync(model, this.name)?.outputTokens
+    );
     return Number.isFinite(declared) && declared > 0 ? declared : null;
   }
 

package/src/runtime/agent/orchestrator/providers/wire-route.mjs

@@ -157,7 +157,7 @@ const NATIVE_DEFERRED_FAMILY = Object.freeze({ messages: 'anthropic', responses:
  * verified support, or a wire with no native contract (Chat, Gemini).
  */
 export function nativeDeferredFamilyForRoute(provider, route) {
-  if (!route || route.nativeDeferredTools !== true) return '';
+  if (route?.nativeDeferredTools !== true) return '';
   const name = String(provider || '')
     .trim()
     .toLowerCase();
@@ -220,7 +220,11 @@ export function resolveWireRoute(
     if (known === false) return unknown();
     // The wire a pre-table session started on, while the model still offers
     // it; otherwise the fresh resolution below (never an unadvertised wire).
-    const legacyWire = profile.legacy({ model: id, catalogWire: usable(catalogWire) ? catalogWire : null, endpoints: advertised });
+    const legacyWire = profile.legacy({
+      model: id,
+      catalogWire: usable(catalogWire) ? catalogWire : null,
+      endpoints: advertised,
+    });
     if (usable(legacyWire)) return route(legacyWire, 'legacy');
   }
   if (override && usable(override)) return route(override, 'override');
@@ -255,7 +259,8 @@ export async function sendWireRoute(provider, model, tools, sendOpts, messages =
 // 403), quota / billing (402, 429) and server errors never qualify.
 const ENDPOINT_STATUSES = new Set([405, 501]);
 const REJECTION_STATUSES = new Set([400, 404, 415, 422]);
-const ENDPOINT_WORDS = /\b(?:endpoints?|routes?)\b|\/(?:v1\/)?(?:messages|responses|chat\/completions)\b|chat completions/i;
+const ENDPOINT_WORDS =
+  /\b(?:endpoints?|routes?)\b|\/(?:v1\/)?(?:messages|responses|chat\/completions)\b|chat completions/i;
 const UNSUPPORTED_WORDS =
   /\bunsupported\b|not (?:be )?(?:supported|available|served|implemented)|(?:does not|doesn't|do not|don't) (?:support|serve)|only (?:available|supported|served)|wrong endpoint|use (?:the )?\/?(?:v1\/)?(?:messages|responses|chat\/completions)\b/i;
 // A typed code / type that names an auth, quota, billing or parameter failure
@@ -507,6 +512,11 @@ export async function pinSessionWireRoute(session, provider) {
   // The route changed while resolving: the newer route pins on its own turn.
   if (session.provider !== providerName || session.model !== model) return null;
   const nativeDeferred = !answered && wireSupportsNativeDeferredTools(providerName, route.wire);
-  session.wireRoute = { provider: providerName, model, ...route, ...(nativeDeferred ? { nativeDeferredTools: true } : {}) };
+  session.wireRoute = {
+    provider: providerName,
+    model,
+    ...route,
+    ...(nativeDeferred ? { nativeDeferredTools: true } : {}),
+  };
   return session.wireRoute;
 }

package/src/runtime/agent/orchestrator/providers/xai-tool-search.fixtures.mjs

@@ -106,8 +106,16 @@ export function serverSearchEvents(model = 'grok-4') {
 }
 
 export const SESSION_TOOLS = [
-  { name: 'Read', description: 'Read a file', inputSchema: { type: 'object', properties: { path: { type: 'string' } } } },
-  { name: 'load_tool', description: 'Load tools', inputSchema: { type: 'object', properties: { names: { type: 'array' } } } },
+  {
+    name: 'Read',
+    description: 'Read a file',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+  },
+  {
+    name: 'load_tool',
+    description: 'Load tools',
+    inputSchema: { type: 'object', properties: { names: { type: 'array' } } },
+  },
 ];
 export const DEFERRED_TOOLS = [
   ...SESSION_TOOLS,
@@ -168,7 +176,11 @@ export async function captureBodies(history, tools, { config = {}, opts = {} } =
   await sendXaiResponses(http.provider, history, 'grok-4', tools, { sessionId: 'sess-1', ...opts });
   const before = ws.bodies.length;
   const socket = xaiProvider(config);
-  await sendXaiResponsesWebSocket(socket.provider, history, 'grok-4', tools, { sessionId: 'sess-1', iteration: 1, ...opts });
+  await sendXaiResponsesWebSocket(socket.provider, history, 'grok-4', tools, {
+    sessionId: 'sess-1',
+    iteration: 1,
+    ...opts,
+  });
   return { http: http.requests[0], ws: ws.bodies[before] };
 }
 

package/src/runtime/agent/orchestrator/runtime-core/ask-user-tool-defs.mjs

@@ -6,7 +6,8 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
   {
     name: 'ask_user',
     title: 'Ask User',
-    trigger: 'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat.',
+    trigger:
+      'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat.',
     description:
       'Ask the user multiple-choice questions and wait. Only while planning, for a decision only the user can make with clear options; open questions, minor choices and plan approval go in chat. Do not repeat the options in your message.',
     annotations: {
@@ -92,7 +93,10 @@ export function validateAskUserQuestions(args) {
       if (labels.has(option.label)) throw new Error(`${at} has duplicate option label "${option.label}"`);
       labels.add(option.label);
     }
-    if (q.recommended != null && (!Number.isInteger(q.recommended) || q.recommended < 0 || q.recommended >= q.options.length)) {
+    if (
+      q.recommended != null &&
+      (!Number.isInteger(q.recommended) || q.recommended < 0 || q.recommended >= q.options.length)
+    ) {
       throw new Error(`${at} recommended must be an index below ${q.options.length}`);
     }
   });

package/src/runtime/agent/orchestrator/runtime-core/config-helpers.mjs

@@ -189,18 +189,20 @@ const AUTO_CLEAR_DEFAULT_IDLE_MS = 60 * 60 * 1000;
 // rewrite the accumulated tail. Anthropic agent tails are 5m and compact once
 // expired; their terminal reap keeps this 1h window so a completed agent stays
 // reusable. Gemini, xAI and Mistral
-// caches run ~1h, Groq's implicit cache persists ~2h, OpenAI/DeepSeek
-// key-prefix/implicit caches persist far longer (~24h), and OpenAI OAuth
-// (Codex backend) guarantees a 30-minute minimum prompt-cache TTL on
-// GPT-5.6+ models (prompt_cache_options.ttl=30m, refreshed on use), so the
-// sweep matches that window to avoid clearing a still-warm cache.
+// caches run ~1h, Groq's implicit cache persists ~2h, and DeepSeek's
+// implicit cache is evicted after "a few hours to a few days" (kept at 24h).
+// OpenAI (direct and OAuth/Codex) guarantees a 30-minute minimum prompt-cache
+// TTL on GPT-5.6+ (refreshed on use; no 24h retention there), so the sweep
+// matches that window. Older OpenAI models that still take
+// prompt_cache_retention='24h' are not distinguished: these call sites only
+// know the provider, not the model, so 30m applies to the whole provider.
 // Unknown/unrecognized providers fall back to the 'default' 1h entry.
 const AUTO_CLEAR_PROVIDER_IDLE_MS = Object.freeze({
   anthropic: 60 * 60 * 1000,
   'anthropic-oauth': 60 * 60 * 1000,
   gemini: 60 * 60 * 1000,
   groq: 2 * 60 * 60 * 1000,
-  openai: 24 * 60 * 60 * 1000,
+  openai: 30 * 60 * 1000,
   deepseek: 24 * 60 * 60 * 1000,
   xai: 60 * 60 * 1000,
   'openai-oauth': 30 * 60 * 1000,

package/src/runtime/agent/orchestrator/runtime-core/deferred-tool-availability.mjs

@@ -8,7 +8,10 @@ export function sessionAllowlistExcludes(session, name) {
 
 /** The session's denied tools name `name`. */
 export function sessionDisallows(session, name) {
-  return Array.isArray(session?.disallowedTools) && session.disallowedTools.some((denied) => lowerName(denied) === lowerName(name));
+  return (
+    Array.isArray(session?.disallowedTools) &&
+    session.disallowedTools.some((denied) => lowerName(denied) === lowerName(name))
+  );
 }
 
 /**

package/src/runtime/agent/orchestrator/runtime-core/goal-store.mjs

@@ -86,7 +86,7 @@ export function createGoalStore(ctx) {
     }
   };
 
-  const commit = async (sessionId, goal) => {
+  const commit = async (sessionId, goal, { isCurrent, accept } = {}) => {
     const id = assertSessionId(sessionId);
     const previous = goal ? readRecord(id).goal : null;
     let committedGoal = null;
@@ -101,7 +101,35 @@ export function createGoalStore(ctx) {
           ? previous.revision + Number(revisionStateKey(previous) !== revisionStateKey(committedGoal))
           : 1;
     }
-    await storage.write(id, { version: GOAL_FILE_VERSION, goal: committedGoal });
+    const rollback = async () => {
+      try {
+        await storage.write(id, { version: GOAL_FILE_VERSION, goal: previous });
+      } catch (error) {
+        error.quotaResumeRollbackFailed = true;
+        throw error;
+      }
+      ctx.deadlines.armDeadline(id);
+    };
+    try {
+      await storage.write(id, { version: GOAL_FILE_VERSION, goal: committedGoal });
+    } catch (error) {
+      if (isCurrent || accept) await rollback();
+      throw error;
+    }
+    if (isCurrent || accept) {
+      let accepted = false;
+      let admissionError = null;
+      try {
+        accepted = (!isCurrent || isCurrent()) && (!accept || accept() === true);
+      } catch (error) {
+        admissionError = error;
+      }
+      if (!accepted) {
+        await rollback();
+        if (admissionError) throw admissionError;
+        return null;
+      }
+    }
     ctx.deadlines.armDeadline(id);
     emit(id);
     return publicGoal(committedGoal, now());

package/src/runtime/agent/orchestrator/runtime-core/goal-turns.mjs

@@ -171,8 +171,9 @@ export function createGoalTurnLifecycle(ctx) {
     // A quota resume revives exactly the Goal its failure suspended, and only
     // while that Goal is still waiting on the limit: a Goal the user paused,
     // stopped, replaced or completed meanwhile stays as it is.
-    reactivateUsageLimited(sessionId, goalId) {
+    reactivateUsageLimited(sessionId, goalId, options = {}) {
       return withMutation(sessionId, async (id) => {
+        if (options.isCurrent && !options.isCurrent()) return null;
         const goal = readRecord(id).goal;
         if (!goal || goal.archivedAt || goal.id !== clean(goalId) || goal.status !== 'usage_limited') return null;
         try {
@@ -180,7 +181,7 @@ export function createGoalTurnLifecycle(ctx) {
         } catch {
           return null;
         }
-        return commit(id, goal);
+        return commit(id, goal, options);
       });
     },
     continuation(sessionId, { agentStatus = null } = {}) {

package/src/runtime/agent/orchestrator/runtime-core/orchestration.mjs

@@ -5,9 +5,10 @@ const BATCHING = {
 self-contained supporting work, one agent per role; batch related tasks
 rather than splitting them for parallelism.`,
   balanced: `Delegate independent work by coherent feature or module, one agent per
-scope. Batch related tasks within the same change scope rather than
-splitting every file or step.`,
-  swarm: `Delegate every independent scope to its own agent. Treat disjoint file or
+scope; a scope is one verifiable deliverable. Batch related tasks within the
+same change scope rather than splitting every file or step.`,
+  swarm: `Delegate every independent scope to its own agent; a scope is one
+verifiable deliverable, not a bundle of steps. Treat disjoint file or
 module sets as independent and merge scopes only on a true output
 dependency. Prefer parallel scopes over sequential slices in one agent.`,
 };
@@ -38,6 +39,10 @@ scopes does not change this.
 
 Dispatch all ready independent scopes in one turn. Only a scope that requires
 another's output waits. Brief each agent as the Lead rules describe.
+A running agent receives only changes within its own scope; a new independent
+need goes to a new agent. When scopes touch the same file, name one owner for
+that file in each brief. Agents run only the checks covering their own change;
+Lead runs the full suite once after integration.
 Use only available agents; when none fits a role, Lead does that work itself
 and never changes settings to enable one. If the reviewer is disabled or
 unavailable, Lead alone reviews the result against the approved scope and

package/src/runtime/agent/orchestrator/runtime-core/skill-tool-loading.mjs

@@ -59,7 +59,9 @@ export function loadSkillToolDependencies(envelope, session, mode) {
           `Required tools loaded: ${direct.join(', ')}. Their full definitions are available on your next request; use them directly without load_tool.`,
         ]
       : []),
-    ...(direct.length && isToolBridgeEnabled(session) ? [`Required tools available directly: ${direct.join(', ')}.`] : []),
+    ...(direct.length && isToolBridgeEnabled(session)
+      ? [`Required tools available directly: ${direct.join(', ')}.`]
+      : []),
     ...(bridged.length
       ? [
           `Required tools available through call_tool: ${bridged.join(', ')}. Read a definition with load_tool, then run it with call_tool {name, arguments}.`,

package/src/runtime/agent/orchestrator/runtime-core/tool-bridge-contract.mjs

@@ -0,0 +1,6 @@
+export const BRIDGE_NAME_MAX_CHARS = 256;
+const META_NAMES = new Set(['load_tool', 'call_tool', 'tool_search']);
+
+export function isBridgeMetaTool(name) {
+  return typeof name === 'string' && META_NAMES.has(name.toLowerCase());
+}

package/src/runtime/agent/orchestrator/runtime-core/tool-bridge.mjs

@@ -7,6 +7,7 @@
 // execution permission; continuation tokens only carry a position and grant
 // no authority.
 import { createHash } from 'node:crypto';
+import { BRIDGE_NAME_MAX_CHARS, isBridgeMetaTool } from './tool-bridge-contract.mjs';
 import { clean } from './session-text.mjs';
 import { isDeferredToolAvailable } from './deferred-tool-availability.mjs';
 import {
@@ -26,16 +27,13 @@ export { isToolBridgeEnabled } from './tool-exposure.mjs';
 
 export const BRIDGE_LOAD_TOOL_NAME = 'load_tool';
 export const BRIDGE_CALL_TOOL_NAME = 'call_tool';
-// Names call_tool may never target and search never lists.
-const BRIDGE_META_TOOL_NAMES = new Set(['load_tool', 'call_tool', 'tool_search']);
-
 const DESCRIBE_MAX_NAMES = 8;
 // Most definitions one request resolves to: every name an alias of the widest
 // alias. A token naming more was not issued by this tool.
 const MAX_ALIAS_MEMBERS = Math.max(1, ...Object.values(DEFERRED_SELECT_ALIASES).map((members) => members.length));
 
 export const BRIDGE_LIMITS = Object.freeze({
-  nameMaxChars: 256,
+  nameMaxChars: BRIDGE_NAME_MAX_CHARS,
   continuationMaxChars: 4096,
   continuationMaxTargets: DESCRIBE_MAX_NAMES * MAX_ALIAS_MEMBERS,
   describeMaxNames: DESCRIBE_MAX_NAMES,
@@ -300,7 +298,7 @@ function searchKeywords(session, keywords, mode, available) {
         const name = clean(tool?.name);
         return (
           !eagerNames.has(name) &&
-          !BRIDGE_META_TOOL_NAMES.has(name.toLowerCase()) &&
+          !isBridgeMetaTool(name) &&
           toolSearchMatches(tool, keyword) &&
           !bridgeBlockReason(session, tool, mode, eagerNames)
         );
@@ -343,17 +341,19 @@ function largestChunk(text, offset, buildPage) {
 }
 
 export function describeBridgeTools(session, args = {}, { mode } = {}) {
+  const syntaxHint = ' Use load_tool {"names":["exact_tool_name"]}; the required key is names, not name.';
   const invalid = unknownKeysError(args, DESCRIBE_KEYS, BRIDGE_LOAD_TOOL_NAME);
   if (invalid) {
     const hint = isPlainObject(args) && 'query' in args ? ' Pass exact names; the deferred tool list names them.' : '';
-    return bridgeError(invalid.error.code, `${invalid.error.message}${hint}`);
+    return bridgeError(invalid.error.code, `${invalid.error.message}${hint}${syntaxHint}`);
   }
   // A continuation token resumes an earlier request. It travels alone: names
   // is split exactly as for a lookup, and a token beside any other value is
   // refused rather than read as a missing name.
   const raw = args.names;
-  const strings =
-    typeof raw === 'string' ? [raw] : Array.isArray(raw) && raw.every((item) => typeof item === 'string') ? raw : [];
+  let strings = [];
+  if (typeof raw === 'string') strings = [raw];
+  else if (Array.isArray(raw) && raw.every((item) => typeof item === 'string')) strings = raw;
   let continuation = null;
   if (strings.some((item) => item.includes(BRIDGE_CONTINUATION_PREFIX))) {
     if (strings.length !== 1 || !CONTINUATION_TOKEN_PATTERN.test(strings[0])) {
@@ -375,7 +375,7 @@ export function describeBridgeTools(session, args = {}, { mode } = {}) {
     if (!names) {
       return bridgeError(
         'INVALID_ARGUMENTS',
-        `names must be 1-${BRIDGE_LIMITS.describeMaxNames} exact tool names of at most ${BRIDGE_LIMITS.nameMaxChars} characters.`
+        `names must be 1-${BRIDGE_LIMITS.describeMaxNames} exact tool names of at most ${BRIDGE_LIMITS.nameMaxChars} characters.${syntaxHint}`
       );
     }
     ({ targets, missing, blocked } = resolveDescribeTargets(session, names, mode, available));
@@ -478,7 +478,7 @@ export function resolveBridgeTarget(session, rawName) {
   if (!name || name.length > BRIDGE_LIMITS.nameMaxChars) {
     return bridgeError('INVALID_ARGUMENTS', `name must be 1-${BRIDGE_LIMITS.nameMaxChars} characters.`);
   }
-  if (BRIDGE_META_TOOL_NAMES.has(name.toLowerCase())) {
+  if (isBridgeMetaTool(name)) {
     return bridgeError('BRIDGE_RECURSION', `call_tool cannot run the bridge tool "${name}"; call it directly.`);
   }
   const eager = lookupByName(Array.isArray(session?.tools) ? session.tools : [], name);

package/src/runtime/agent/orchestrator/runtime-core/tool-catalog.mjs

@@ -800,7 +800,9 @@ function pendingAndFailedMcpServers(mcpStatus) {
  */
 function resolvableCatalog(session) {
   const union = deferredCatalogUnion(session);
-  return filterSessionToolPolicy(union.length ? union : Array.isArray(session?.tools) ? session.tools : [], session);
+  let tools = union;
+  if (!union.length) tools = Array.isArray(session?.tools) ? session.tools : [];
+  return filterSessionToolPolicy(tools, session);
 }
 
 // Pure loader. Input is exact deferred-tool names/aliases; output reports

package/src/runtime/agent/orchestrator/runtime-core/tool-defs.mjs

@@ -67,14 +67,14 @@ export const SESSION_TOOL = {
   annotations: {
     title: 'Session',
     readOnlyHint: false,
-    destructiveHint: false,
+    destructiveHint: true,
     idempotentHint: false,
     openWorldHint: false,
     agentHidden: true,
   },
-  trigger: 'Session status, rename the title, compact, fork into a new session, switch Project, worktrees.',
+  trigger: 'Session lookup/control, title, compact, fork, Project and worktrees.',
   description:
-    'Manage the current session. status shows session id, title, Project and model; rename sets the session title; compact runs after this turn ends; fork copies this conversation into a new session. set-project switches the active Project; list-projects returns the registered projects (name, path); a project name instead of a path → list-projects first, then set-project with the matching path, ask only if several match. path must be an existing directory. A shell-local cd does not change the Project. Worktree actions act on this session’s git worktree only when the user explicitly asks.',
+    'Inspect sessions or control another by exact ID, never a guessed one. send acknowledges queue intake, not completion. Cancel/delete and worktree actions require the user’s request. Other actions affect only the current session.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -82,6 +82,11 @@ export const SESSION_TOOL = {
         type: 'string',
         enum: [
           'status',
+          'list',
+          'read',
+          'send',
+          'cancel',
+          'delete',
           'rename',
           'compact',
           'fork',
@@ -95,14 +100,47 @@ export const SESSION_TOOL = {
           'prune-worktrees',
         ],
         description:
-          'status (default without path) shows the session; rename sets title; compact schedules a compaction right after this turn; fork creates a new session copying this conversation (returns its sessionId; this session stays current); set-project switches to path; list-projects returns registered projects; favorite/archive set this session’s sidebar flag to value; merge-worktree merges this session’s worktree into the project folder’s checked-out branch, remove-worktree deletes it (returning to the project folder; call again if it reports WORKTREE_REMOVAL_INCOMPLETE); list-worktrees lists every managed worktree and who retains it; prune-worktrees removes clean, merged ones no session retains.',
+          'status defaults to current; list pages sessions; read returns latest items; send queues prompt; cancel stops the turn; delete removes the session. compact runs after this turn; fork copies it without switching. merge-worktree merges into the Project’s checked-out branch; remove-worktree returns to the Project (repeat on WORKTREE_REMOVAL_INCOMPLETE); list-worktrees includes retaining sessions; prune-worktrees removes only clean, merged, unretained worktrees.',
+      },
+      title: { type: 'string', description: 'rename: new current-session title.' },
+      session_id: {
+        type: 'string',
+        description:
+          'ID from list; required for read/send/cancel/delete, optional for status. send/cancel/delete cannot target the caller.',
+      },
+      prompt: { type: 'string', description: 'send: message to enqueue; loads a cold session.' },
+      limit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 100,
+        description:
+          'list/read: maximum rows, default 25. Output: 8KiB per page, 12KiB for initial read tail; follow nextOffset/nextTextOffset for more.',
+      },
+      cursor: { type: 'string', description: 'list: returned nextCursor.' },
+      offset: {
+        type: 'integer',
+        minimum: 0,
+        description:
+          'read: newest items to skip, default 0 (tail). Use nextOffset for older pages; appends/rewinds shift positions.',
+      },
+      text_offset: {
+        type: 'integer',
+        minimum: 0,
+        description: 'read: UTF-16 text position from nextTextOffset; requires offset, limit:1, item_id.',
+      },
+      item_id: {
+        type: 'string',
+        description: 'read: returned item id; rejects a shifted position instead of reading another item.',
+      },
+      path: {
+        type: 'string',
+        description:
+          'Existing directory; implies set-project. Resolve names with list-projects first. Shell cd does not switch Project.',
       },
-      title: { type: 'string', description: 'rename: the new session title.' },
-      path: { type: 'string', description: 'Existing directory to switch to (implies action=set-project).' },
-      compact: { type: 'boolean', description: 'fork: compact the copied conversation.' },
+      compact: { type: 'boolean', description: 'fork: compact the copy.' },
       force: {
         type: 'boolean',
-        description: 'remove-worktree: delete even with uncommitted or unmerged work (only when the user says so).',
+        description: 'remove-worktree: allow uncommitted/unmerged work only when explicitly requested.',
       },
       value: { type: 'boolean', description: 'favorite/archive: on or off.' },
     },

package/src/runtime/agent/orchestrator/runtime-core/workflow.mjs

@@ -7,6 +7,7 @@ import { normalizeEffortInput } from './effort.mjs';
 import { isLikelyRawModelId } from './config-helpers.mjs';
 import { configuredAgentRouteCandidates } from '../../../shared/agent-route-config.mjs';
 import { normalizeContextTokens } from '../../../shared/llm/default-context-window.mjs';
+import { canonicalRouteProvider, normalizeRouteChain } from '../../../shared/model-route-chain.mjs';
 import { normalizeAgentId, normalizeWorkflowId } from './workflow-ids.mjs';
 import { createWorkflowPacks } from './workflow/packs.mjs';
 import { createWorkflowAgents } from './workflow/agents.mjs';
@@ -38,12 +39,6 @@ const WEB_SEARCH_PROVIDER_FAMILIES = new Map([
 ]);
 export const WEB_SEARCH_DEFAULT_PROVIDER = 'default';
 export const WEB_SEARCH_DEFAULT_MODEL = 'default';
-const WEB_SEARCH_PROVIDER_ALIASES = Object.freeze({
-  'openai-api': 'openai',
-  'xai-api': 'xai',
-  'gemini-api': 'gemini',
-  'anthropic-api': 'anthropic',
-});
 
 export function workflowPresetId(slot) {
   return `workflow-${slot}`;
@@ -121,8 +116,7 @@ export function createWorkflowHelpers({ rootDir, dataDir, readMarkdownDocument,
 }
 
 export function normalizeWebSearchProviderId(provider) {
-  const id = clean(provider);
-  return WEB_SEARCH_PROVIDER_ALIASES[id] || id;
+  return canonicalRouteProvider(provider);
 }
 
 export function isDefaultWebSearchRouteConfig(routeLike = {}) {
@@ -141,6 +135,10 @@ export function isWebSearchCapableProvider(provider) {
 }
 
 export function normalizeWebSearchRouteConfig(routeLike, fallback = {}) {
+  return normalizeRouteChain(routeLike, normalizeWebSearchRouteLeaf, fallback);
+}
+
+function normalizeWebSearchRouteLeaf(routeLike, fallback = {}) {
   const provider = normalizeWebSearchProviderId(routeLike?.provider || fallback.provider);
   const model = clean(routeLike?.model || fallback.model);
   if (!provider || !model) return null;
@@ -178,6 +176,10 @@ export function webSearchRouteOrDefault(...routeLikes) {
 }
 
 export function normalizeWorkflowRoute(routeLike, fallback = {}) {
+  return normalizeRouteChain(routeLike, normalizeWorkflowRouteLeaf, fallback);
+}
+
+function normalizeWorkflowRouteLeaf(routeLike, fallback = {}) {
   const provider = clean(routeLike?.provider) || clean(fallback.provider);
   const model = clean(routeLike?.model) || clean(fallback.model);
   if (!provider || !model) return null;