mixdog 1.2.2 → 1.2.3

package/src/runtime/agent/orchestrator/context/deferred-tools.mjs

@@ -1,5 +1,6 @@
 // Deferred-pool and MCP-instruction manifests injected into BP2.
 import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
+import { isToolBridgeEnabled, TOOL_BRIDGE_GUIDANCE } from '../runtime-core/tool-exposure.mjs';
 
 export function compactPromptManifestText(value, max = 250) {
   const text = String(value || '')
@@ -13,7 +14,10 @@ export function compactPromptManifestText(value, max = 250) {
   return `${cut.replace(/[\s,.;:!?/-]+$/, '')}...`;
 }
 
-const DEFERRED_TOOLS_BLOCK_RE = /(\n\n---\n*)?<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>\s*/gi;
+// The native deferred-pool manifest and the static bridge guidance occupy the
+// same BP2 slot: one replaces the other when the exposure changes.
+const DEFERRED_TOOLS_BLOCK_RE =
+  /(\n\n---\n*)?<(available-deferred-tools|tool-bridge)>[\s\S]*?<\/(?:available-deferred-tools|tool-bridge)>\s*/gi;
 const MCP_INSTRUCTIONS_BLOCK_RE = /(\n\n---\n*)?<mcp-instructions>[\s\S]*?<\/mcp-instructions>\s*/gi;
 // Tool and MCP server names enter the manifests only as plain identifiers
 // (no markup can be smuggled into the prompt through a name).
@@ -47,6 +51,7 @@ function hasDeferredToolManifestBlock(text) {
   const raw = String(text || '');
   return (
     /<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>/i.test(raw) ||
+    /<tool-bridge>[\s\S]*?<\/tool-bridge>/i.test(raw) ||
     /<mcp-instructions>[\s\S]*?<\/mcp-instructions>/i.test(raw)
   );
 }
@@ -173,11 +178,17 @@ function deferredManifestEntries(session, pool) {
 }
 
 function composeDeferredBp2Manifest(session, pool) {
+  // Bridge exposure gets the native roster and MCP instructions (the pool is
+  // already limited to what the session's policy lets it run), followed by
+  // the static bridge guidance. A tool-free bridge session gets nothing.
+  const bridge = isToolBridgeEnabled(session);
+  if (bridge && !(session.tools || []).some((tool) => tool?.name === 'call_tool')) return '';
   const parts = [];
   const deferredManifest = buildDeferredToolManifest(deferredManifestEntries(session, pool));
   if (deferredManifest) parts.push(deferredManifest);
   const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool, session.deferredToolCatalog);
   if (mcpManifest) parts.push(mcpManifest);
+  if (bridge) parts.push(TOOL_BRIDGE_GUIDANCE);
   return parts.join('\n\n');
 }
 
@@ -186,12 +197,20 @@ function markDeferredBp2Applied(session) {
   delete session.deferredToolBp1Applied;
 }
 
+// Replace, never mutate: session-store delta saves treat stable message
+// references as an unchanged prefix, so a rewritten prompt block must be a
+// fresh object for the next save to persist it.
+function setSystemContent(session, index, content) {
+  const message = session.messages[index];
+  if (message.content !== content) session.messages[index] = { ...message, content };
+}
+
 function clearDeferredManifestBlocks(session) {
-  for (const message of session.messages) {
+  session.messages.forEach((message, index) => {
     if (message?.role === 'system' && typeof message.content === 'string') {
-      message.content = stripDeferredToolManifestBlock(message.content);
+      setSystemContent(session, index, stripDeferredToolManifestBlock(message.content));
     }
-  }
+  });
   session.messages = session.messages.filter(
     (message) => message?.role !== 'system' || String(message.content || '').trim()
   );
@@ -214,15 +233,15 @@ function writeDeferredManifestAt(session, idx, manifest, rebuild) {
   for (let i = 0; i < session.messages.length; i++) {
     if (i === idx || session.messages[i]?.role !== 'system' || typeof session.messages[i].content !== 'string')
       continue;
-    session.messages[i].content = stripDeferredToolManifestBlock(session.messages[i].content);
+    setSystemContent(session, i, stripDeferredToolManifestBlock(session.messages[i].content));
   }
   const raw = typeof session.messages[idx].content === 'string' ? session.messages[idx].content : '';
   if (rebuild && hasDeferredToolManifestBlock(raw)) {
-    session.messages[idx].content = rebuildDeferredToolManifestBlock(raw, manifest);
+    setSystemContent(session, idx, rebuildDeferredToolManifestBlock(raw, manifest));
     return;
   }
   const base = stripDeferredToolManifestBlock(raw);
-  session.messages[idx].content = base ? `${base}\n\n---\n\n${manifest}` : manifest;
+  setSystemContent(session, idx, base ? `${base}\n\n---\n\n${manifest}` : manifest);
 }
 
 /**

package/src/runtime/agent/orchestrator/context/skill-catalog.mjs

@@ -1,9 +1,10 @@
 // Skill discovery, cache, resource loading, envelopes, manifests, and the
 // Skill meta-tool.
 
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, readdirSync, statSync, watch as watch_ } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { maxMtimeRecursive, mtimeSignatureRecursive } from '../cache-mtime.mjs';
+import { maxMtimeRecursive, mtimeSignatureRecursive, mtimeSignatureText } from '../cache-mtime.mjs';
 import { mixdogHome, resolvePluginData, mixdogRoot } from '../../../shared/plugin-paths.mjs';
 import { PLUGIN_MANIFEST_FILES, pluginSkillsRoots } from '../../../shared/plugin-manifest.mjs';
 import {
@@ -257,6 +258,31 @@ export function isSkillDisabled(name, config = null, skills = null) {
   return Boolean(skill && missingFeature(skill, featureConfig(config)));
 }
 
+/**
+ * `enabled` for every skill of one collectSkillsCached() snapshot, exactly as
+ * `!(isSkillDisabled(name, config, skills) || skillMissingFeature(name, config,
+ * skills))` per skill — but with ONE config read, one disabled-name set and one
+ * name index for the whole list instead of three config reads and a linear
+ * lookup per skill (the status listing blocked the event loop on them).
+ */
+export function skillEnabledFlags(skills, config = null) {
+  const list = Array.isArray(skills) ? skills : [];
+  const cfg = config || loadConfig({ secrets: false });
+  const disabled = getDisabledSkillNameSet(cfg);
+  const features = featureConfig(cfg);
+  const byKey = new Map();
+  for (const entry of list) {
+    const key = normalizeSkillNameKey(entry.name);
+    if (!byKey.has(key)) byKey.set(key, entry);
+  }
+  return list.map((entry) => {
+    const key = normalizeSkillNameKey(entry.name);
+    const skill = byKey.get(key);
+    if (key && !followsBuiltinFeature(skill) && disabled.has(key)) return false;
+    return !(skill && missingFeature(skill, features));
+  });
+}
+
 /** The built-in feature a skill needs that is not active, or null. */
 export function skillMissingFeature(name, config = null, skills = null) {
   const skill = findCachedSkillByKey(normalizeSkillNameKey(name), skills);
@@ -303,6 +329,81 @@ export function collectPromptSkillsCached(cwd, config = null) {
 // --- Global skill cache (mtime-based) ---
 const _skillsCache = new Map();
 
+// Change watchers over the recursive skill roots. Re-walking every skill
+// folder (one stat per entry) on every status/prompt read blocked the event
+// loop for tens to hundreds of ms with a large skill set. A root whose
+// recursive watcher has reported nothing since its last walk reuses that
+// walk's signature text instead; any event, watcher error or explicit
+// invalidation re-walks it. A watched root is trusted only once an event-loop
+// turn has passed since its walk.
+// Freshness contract: every write made through the app (addSkill, saveSkill,
+// setDisabledSkills, reloadSkills, settings/plugin mutations, peer-runtime
+// announcements) calls invalidateSkillsCache synchronously, which drops every
+// watch, so the very next read re-walks and is exact. A passive edit made
+// outside the app is eventually consistent: it is seen once the watcher
+// delivers its event (watcher latency), or at the next explicit invalidation.
+// Roots that cannot be watched (missing, or unsupported by the platform) and
+// every plain-file gate path are stat'ed on every call as before.
+const _ROOT_WATCH_LIMIT = 64;
+const _rootWatches = new Map(); // root -> { watcher, dirty, text, settled }
+
+function _closeRootWatch(root) {
+  const watch = _rootWatches.get(root);
+  if (!watch) return;
+  _rootWatches.delete(root);
+  try {
+    watch.watcher.close();
+  } catch {
+    /* already closed */
+  }
+}
+
+function _closeAllRootWatches() {
+  for (const root of [..._rootWatches.keys()]) _closeRootWatch(root);
+}
+
+function _openRootWatch(root) {
+  let isDir = false;
+  try {
+    isDir = statSync(root).isDirectory();
+  } catch {
+    return null;
+  }
+  if (!isDir) return null;
+  if (_rootWatches.size >= _ROOT_WATCH_LIMIT) _closeAllRootWatches();
+  const watch = { watcher: null, dirty: true, text: null, settled: false };
+  try {
+    // A change anywhere below drops the root's reused walk; the watcher is
+    // closed with it (a re-walk re-opens one), so a churning folder never
+    // keeps a handle on directories being deleted.
+    watch.watcher = watch_(root, { recursive: true, persistent: false }, () => _closeRootWatch(root));
+    watch.watcher.on('error', () => _closeRootWatch(root));
+  } catch {
+    return null;
+  }
+  _rootWatches.set(root, watch);
+  return watch;
+}
+
+/** Signature text of one recursive gate root (see mtimeSignatureText). */
+function _rootSignatureText(root) {
+  const current = _rootWatches.get(root);
+  if (current && !current.dirty && current.settled) return current.text;
+  // Open the watcher BEFORE the walk: a change racing the walk then either
+  // shows in it or arrives as an event that drops the reused text.
+  const watch = current || _openRootWatch(root);
+  const text = mtimeSignatureText([root]);
+  if (watch && _rootWatches.get(root) === watch) {
+    watch.text = text;
+    watch.dirty = false;
+    watch.settled = false;
+    setImmediate(() => {
+      if (_rootWatches.get(root) === watch && watch.text === text) watch.settled = true;
+    }).unref?.();
+  }
+  return text;
+}
+
 export function collectSkillsCached(cwd) {
   if (skillsDisabled()) return [];
   void cwd;
@@ -313,12 +414,15 @@ export function collectSkillsCached(cwd) {
   skillsDirs.push(...pluginSkillDirs().map(({ dir }) => dir), ...builtinSkillDirs());
   // registry.json itself gates plugin add/remove: removal deletes the
   // plugin's skills dir (so no dir mtime advances), but saveRegistry()
-  // always rewrites this file. mtimeSignatureRecursive stats plain files directly.
+  // always rewrites this file. It is a plain file: stat'ed directly.
   const registryPath = pluginRegistryPath();
-  if (registryPath) skillsDirs.push(registryPath);
-  // Exact, un-timed gate: stat every call. The shallow watch list covers
-  // manifest edits and skill roots that do not exist yet.
-  const signature = `${mtimeSignatureRecursive(skillsDirs)}|${mtimeSignatureRecursive(pluginShallowWatchPaths(), 0)}`;
+  // Exact gate: unwatched roots and plain files are stat'ed every call; a
+  // watched root reuses its last walk only while its watcher stayed quiet.
+  // The shallow watch list covers manifest edits and skill roots that do not
+  // exist yet.
+  const rootTexts = skillsDirs.map((dir) => _rootSignatureText(dir));
+  if (registryPath) rootTexts.push(mtimeSignatureText([registryPath]));
+  const signature = `${createHash('sha1').update(rootTexts.join('\n')).digest('hex')}|${mtimeSignatureRecursive(pluginShallowWatchPaths(), 0)}`;
   const entry = _skillsCache.get(key);
   if (entry && entry.signature === signature) {
     return entry.value;
@@ -331,6 +435,7 @@ export function collectSkillsCached(cwd) {
 export function invalidateSkillsCache(cwd) {
   void cwd;
   _skillsCache.clear();
+  _closeAllRootWatches();
 }
 
 /**

package/src/runtime/agent/orchestrator/providers/anthropic-api-request.mjs

@@ -16,10 +16,12 @@ import { fastModeAvailable } from './anthropic-fast-mode.mjs';
 import { applyAnthropicEffortToBody, shouldIncludeEffortBeta } from './anthropic-effort.mjs';
 import { isCustomProviderName, resolveCustomReasoning } from './custom-reasoning.mjs';
 import {
+  anthropicThinkingActive,
   applyAnthropicCacheMarkers,
   clampAnthropicThinkingBudget as clampThinkingBudgetTokens,
   resolveAnthropicCacheTtls as resolveCacheTtls,
   resolveAnthropicMessageCacheSlots,
+  sharedCachePrefixBoundary,
   toAnthropicToolChoice,
 } from './lib/anthropic-request-utils.mjs';
 import {
@@ -54,17 +56,21 @@ export async function buildAnthropicApiRequest({
   opts,
   fastModeLatched,
   modelInfo = null,
+  // The Claude id a gateway slug stands for (OpenRouter `anthropic/claude-opus-4.8`
+  // → `claude-opus-4.8`): the output cap and the thinking/effort shape are read
+  // from it, while the wire still names `useModel`.
+  capabilityModel = useModel,
+  // A gateway-supplied output limit for the model; wins over the Anthropic catalog.
+  modelMaxOutputTokens = opts?.modelMaxOutputTokens ?? null,
 }) {
   // A user-defined provider's reasoning comes from its own model row only:
   // the global by-model-id capability index and the Claude-id ladders are
   // first-party knowledge and must not leak onto (or from) a custom endpoint.
   const isCustom = isCustomProviderName(name);
-  const maxTokens = resolveMaxTokens(useModel);
-  const effortProjection = projectEffortConfiguration(messages, name, useModel, {
-    ...config,
-    ...opts,
-    disableBetaHeaders: config?.disableBetaHeaders,
-  });
+  const maxTokens = resolveMaxTokens(capabilityModel, { modelMaxOutputTokens });
+  const effortOptions = { ...config, ...opts, disableBetaHeaders: config?.disableBetaHeaders };
+  const gatewayEffort = typeof config?.messagesEffort === 'function' ? config.messagesEffort(opts) : null;
+  const effortProjection = projectEffortConfiguration(messages, name, useModel, effortOptions);
   const ttls = resolveCacheTtls(opts);
 
   const systemMsgs = messages.filter((m) => m.role === 'system');
@@ -73,20 +79,29 @@ export async function buildAnthropicApiRequest({
   // (cacheTier:'tier3') at ttls.tier3 — each its own system content block.
   const systemBlocks = buildSystemBlocks(systemMsgs, ttls.system, ttls.tier3);
 
-  // Message-tail cache budget (4-BP layout + ANTHROPIC_MSG_SLOTS) is
-  // shared with anthropic-oauth — see resolveAnthropicMessageCacheSlots.
-  const messageCacheSlots = resolveAnthropicMessageCacheSlots(systemBlocks, ttls);
   // Tools are resolved BEFORE the messages: the lowering needs the final
   // tool list to drop tool_reference blocks whose tool no longer ships
   // in this request (otherwise the API rejects the whole turn).
-  const requestTools = requestAnthropicTools(tools, chatMsgs, opts);
+  const requestTools = requestAnthropicTools(tools, chatMsgs, opts, name);
+  // Message-tail cache budget (4-BP layout + ANTHROPIC_MSG_SLOTS) is
+  // shared with anthropic-oauth — see resolveAnthropicMessageCacheSlots.
+  const messageCacheSlots = resolveAnthropicMessageCacheSlots(systemBlocks, ttls, { tools: requestTools });
   // Build → sanitize (once, inside toAnthropicMessages) → mark. Markers
   // are applied to the FINAL sanitized array by invariant, so block
   // drops / inserts / reorders performed by the sanitizer can never move
   // or delete a marked block. NEVER sanitize again after this.
+  const lowerHistory = (history, projection) =>
+    lowerAnthropicEffortHistory(
+      history.filter((m) => m.role !== 'system'),
+      (segment) => toAnthropicMessages(segment, requestTools, name),
+      projection
+    );
   const anthropicMessages = applyAnthropicCacheMarkers(
-    lowerAnthropicEffortHistory(chatMsgs, (segment) => toAnthropicMessages(segment, requestTools), effortProjection),
-    messageCacheSlots
+    lowerHistory(chatMsgs, effortProjection),
+    messageCacheSlots,
+    sharedCachePrefixBoundary(messages, opts, (prefix) =>
+      lowerHistory(prefix, projectEffortConfiguration(prefix, name, useModel, effortOptions))
+    )
   );
 
   const params = {
@@ -108,10 +123,9 @@ export async function buildAnthropicApiRequest({
   // tool_choice only when tools are actually present (Anthropic rejects
   // tool_choice without tools). 'none' rides the hard-cap final turn to
   // forbid tool USE while keeping the tools prefix stable for cache reuse.
-  if (params.tools) {
-    const toolChoice = toAnthropicToolChoice(opts.toolChoice);
-    if (toolChoice) params.tool_choice = toolChoice;
-  }
+  // The key is reserved here (wire key order) and resolved once thinking is
+  // known: forced any/tool is invalid while thinking is enabled.
+  if (params.tools) params.tool_choice = undefined;
   const hasDeferredTools = Array.isArray(params.tools) && params.tools.some((tool) => tool?.defer_loading === true);
   // Known tool names for the shared parseSSEStream leaked-tool-call guard
   // (same guard fixes both Anthropic providers). Recovered leaked calls
@@ -129,16 +143,30 @@ export async function buildAnthropicApiRequest({
     });
     if (fields.thinking) params.thinking = fields.thinking;
     if (fields.output_config) params.output_config = { ...(params.output_config || {}), ...fields.output_config };
-  } else {
+  } else if (gatewayEffort !== 'none') {
+    // A gateway's own reasoning control (`messagesEffort`) replaces the turn
+    // effort; 'none' sends no thinking at all.
+    const turnOpts = effortProjection ? { ...opts, effort: effortProjection.initialEffort } : opts;
     applyAnthropicEffortToBody(params, {
-      model: useModel,
-      opts: effortProjection ? { ...opts, effort: effortProjection.initialEffort } : opts,
+      model: capabilityModel,
+      opts: gatewayEffort ? { ...turnOpts, effort: gatewayEffort } : turnOpts,
       maxTokens,
       clampThinkingBudgetTokens,
       logTag: name,
       progressUpdates: config?.disableBetaHeaders !== true,
     });
   }
+  if (params.tools) {
+    const toolChoice = toAnthropicToolChoice(opts.toolChoice, {
+      thinking: anthropicThinkingActive(params),
+      disableParallelToolUse: opts.disableParallelToolUse === true,
+      // A gateway that cannot honour disable_parallel_tool_use declares so.
+      supportsDisableParallelToolUse: config?.supportsDisableParallelToolUse !== false,
+      onThinkingConflict: opts.toolChoiceThinkingConflict,
+    });
+    if (toolChoice) params.tool_choice = toolChoice;
+    else delete params.tool_choice;
+  }
   // Fast mode → speed: "fast" on models Anthropic marks as speed-capable.
   // Suppressed while the fast capacity pool is cooling down.
   let fastLatched = fastModeLatched;
@@ -169,7 +197,7 @@ export async function buildAnthropicApiRequest({
         fastMode: fastLatched,
         toolSearch: hasDeferredTools,
         // Custom: the beta follows the resolver's output, not the model id.
-        effort: isCustom ? Boolean(params.output_config?.effort) : shouldIncludeEffortBeta(useModel, opts),
+        effort: isCustom ? Boolean(params.output_config?.effort) : shouldIncludeEffortBeta(capabilityModel, opts),
         serverFallback: params.fallbacks === 'default',
         thinkingDisplayUpdates: params.thinking?.display === 'updates',
       }),

package/src/runtime/agent/orchestrator/providers/anthropic-error-contract.mjs

@@ -25,9 +25,11 @@ const STATUS_ERROR_TYPE = new Map([
   [401, 'authentication_error'],
   [403, 'permission_error'],
   [404, 'not_found_error'],
+  [409, 'conflict_error'],
   [413, REQUEST_TOO_LARGE],
   [429, 'rate_limit_error'],
   [500, 'api_error'],
+  [504, 'timeout_error'],
   [529, 'overloaded_error'],
 ]);
 

package/src/runtime/agent/orchestrator/providers/anthropic-max-tokens.mjs

@@ -4,10 +4,10 @@
 //
 // Resolution order:
 //   1. MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS env override, if set to a positive
-//      int, wins outright (returned as the safety cap itself).
+//      int, wins, capped by the known model maximum when there is one.
 //   2. Catalog outputTokens for the model id (trusted over hardcoded
 //      heuristics when present — the API reports real per-model limits),
-//      clamped to [MAX_TOKENS_FLOOR, safetyCap].
+//      clamped to safetyCap (never raised: a declared limit is a ceiling).
 //   3. The shared model catalog's outputTokens for the model (cached roster /
 //      LiteLLM / models.dev), same clamp.
 //   4. The pre-catalog family limits for a model no catalog describes, else
@@ -62,21 +62,28 @@ function sharedCatalogOutputTokens(model) {
 // catalogLookup(model) -> number|null. Providers supply their own strategy
 // for sourcing the catalog array (in-memory mirror + disk fallback for OAuth,
 // plain disk read for the API-key twin — see anthropic.mjs).
-export function resolveAnthropicMaxTokens(model, { catalogLookup } = {}) {
-  const envOverride = envAnthropicMaxOutputOverride();
-  if (envOverride != null) return envOverride;
-  const safetyCap = DEFAULT_SAFETY_CAP;
-  let catalogValue = null;
-  if (typeof catalogLookup === 'function') {
-    try {
-      catalogValue = catalogLookup(model);
-    } catch {
-      catalogValue = null;
+//
+// `modelMaxOutputTokens` (number|null): a gateway-supplied model limit. When
+// positive it takes precedence over every catalog lookup. A declared model
+// maximum is a ceiling: it is never raised to the floor, and the env override
+// is capped by it.
+export function resolveAnthropicMaxTokens(model, { catalogLookup, modelMaxOutputTokens = null } = {}) {
+  const isLimit = (value) => Number.isFinite(value) && value > 0;
+  let declared = Number(modelMaxOutputTokens);
+  if (!isLimit(declared)) {
+    declared = null;
+    if (typeof catalogLookup === 'function') {
+      try {
+        declared = catalogLookup(model);
+      } catch {
+        declared = null;
+      }
     }
+    if (!isLimit(declared)) declared = sharedCatalogOutputTokens(model);
   }
-  if (!(Number.isFinite(catalogValue) && catalogValue > 0)) catalogValue = sharedCatalogOutputTokens(model);
-  if (Number.isFinite(catalogValue) && catalogValue > 0) {
-    return Math.max(MAX_TOKENS_FLOOR, Math.min(catalogValue, safetyCap));
-  }
-  return Math.min(fallbackAnthropicMaxTokens(model), safetyCap);
+  declared = isLimit(declared) ? Math.floor(declared) : null;
+  const envOverride = envAnthropicMaxOutputOverride();
+  if (envOverride != null) return declared == null ? envOverride : Math.min(envOverride, declared);
+  if (declared != null) return Math.min(declared, DEFAULT_SAFETY_CAP);
+  return Math.min(fallbackAnthropicMaxTokens(model), DEFAULT_SAFETY_CAP);
 }

package/src/runtime/agent/orchestrator/providers/anthropic-messages.mjs

@@ -131,8 +131,8 @@ function _catalogOutputTokensFromSharedCache(model) {
   }
 }
 
-export function resolveMaxTokens(model) {
-  return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokensFromSharedCache });
+export function resolveMaxTokens(model, { modelMaxOutputTokens = null } = {}) {
+  return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokensFromSharedCache, modelMaxOutputTokens });
 }
 
 // Test-only escape hatch for the provider contract scripts
@@ -144,11 +144,12 @@ export const _test = {
   sanitizeInputSchema: (schema, toolName) => sanitizeAnthropicInputSchema(schema, toolName, 'anthropic'),
 };
 
-function deferredAnthropicTools(activeTools, messages, opts) {
-  return sharedDeferredAnthropicTools(activeTools, messages, opts, 'anthropic');
+function deferredAnthropicTools(activeTools, messages, opts, provider = 'anthropic') {
+  return sharedDeferredAnthropicTools(activeTools, messages, opts, provider);
 }
-export function requestAnthropicTools(tools, messages, opts) {
-  return sharedRequestAnthropicTools(tools, messages, opts, 'anthropic');
+// `provider`: the engine's name (a gateway Messages engine runs under its gateway's).
+export function requestAnthropicTools(tools, messages, opts, provider = 'anthropic') {
+  return sharedRequestAnthropicTools(tools, messages, opts, provider);
 }
 // Test-only: expose the lowering so the steering-provenance test can assert
 // the API-key provider keeps steering-tagged user turns distinct (mirrors

package/src/runtime/agent/orchestrator/providers/anthropic-oauth-client-version.mjs

@@ -10,7 +10,7 @@ import { createNpmVersionSource, maxSemver } from './npm-cli-version.mjs';
 // source release just to advance the user-agent version.
 // Claude Opus 5.5 requires 2.1.280 or newer. The release workflow raises this
 // to the published CLI version (scripts/sync-client-version-floors.mjs).
-export const DEFAULT_CLI_VERSION = '2.1.300';
+export const DEFAULT_CLI_VERSION = '2.1.301';
 export const CLAUDE_CLI_NPM_PACKAGE = '@anthropic-ai/claude-code';
 
 const CACHE_SCHEMA_VERSION = 1;

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -55,6 +55,7 @@ import { applyAnthropicEffortToBody, shouldIncludeEffortBeta } from './anthropic
 import { ANTHROPIC_EFFORT_LEVELS, withEffortRejectionFallback } from './effort-rejection.mjs';
 import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
 import {
+  anthropicThinkingActive,
   applyAnthropicCacheMarkers,
   clampAnthropicThinkingBudget as clampThinkingBudgetTokens,
   deferredAnthropicTools as sharedDeferredAnthropicTools,
@@ -62,6 +63,7 @@ import {
   resolveAnthropicCacheTtls as resolveCacheTtls,
   resolveAnthropicMessageCacheSlots,
   sanitizeAnthropicInputSchema,
+  sharedCachePrefixBoundary,
   toAnthropicMessages,
   toAnthropicToolChoice,
 } from './lib/anthropic-request-utils.mjs';
@@ -168,8 +170,8 @@ function buildSystemBlocks(systemMsgs, systemTtl, tier3Ttl) {
 //      clamped to [MAX_TOKENS_FLOOR, safetyCap].
 //   3. Shared model catalog outputTokens, then the floor, when the live
 //      roster has no entry for this model.
-function resolveMaxTokens(model) {
-  return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokens });
+function resolveMaxTokens(model, { modelMaxOutputTokens = null } = {}) {
+  return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokens, modelMaxOutputTokens });
 }
 
 // --- Message conversion ---
@@ -191,8 +193,8 @@ function requestAnthropicTools(tools, messages, opts) {
 function buildRequestBody(messages, model, tools, sendOpts) {
   const systemMsgs = messages.filter((m) => m.role === 'system');
   const chatMsgs = messages.filter((m) => m.role !== 'system');
-  const maxTokens = resolveMaxTokens(model);
   const opts = sendOpts || {};
+  const maxTokens = resolveMaxTokens(model, { modelMaxOutputTokens: opts.modelMaxOutputTokens });
   const effortProjection = projectEffortConfiguration(messages, 'anthropic-oauth', model, opts);
   const ttls = resolveCacheTtls(opts);
   // Each system message becomes its own Anthropic content block with its own
@@ -202,18 +204,27 @@ function buildRequestBody(messages, model, tools, sendOpts) {
 
   // Message-tail cache budget (4-BP layout + ANTHROPIC_MSG_SLOTS) is shared
   // with anthropic.mjs — see resolveAnthropicMessageCacheSlots.
-  const messageCacheSlots = resolveAnthropicMessageCacheSlots(systemBlocks, ttls);
   // Tools are resolved BEFORE the messages: the lowering needs the final
   // tool list to drop tool_reference blocks whose tool no longer ships in
   // this request (otherwise the API rejects the whole turn).
   const requestTools = requestAnthropicTools(tools, chatMsgs, opts);
+  const messageCacheSlots = resolveAnthropicMessageCacheSlots(systemBlocks, ttls, { tools: requestTools });
   // Build → sanitize (once, inside toAnthropicMessages) → mark. Markers are
   // applied to the FINAL sanitized array by invariant, so block drops /
   // inserts / reorders performed by the sanitizer can never move or delete a
   // marked block. NEVER sanitize again after this (see send path).
+  const lowerHistory = (history, projection) =>
+    lowerAnthropicEffortHistory(
+      history.filter((m) => m.role !== 'system'),
+      (segment) => toAnthropicMessages(segment, requestTools),
+      projection
+    );
   const anthropicMessages = applyAnthropicCacheMarkers(
-    lowerAnthropicEffortHistory(chatMsgs, (segment) => toAnthropicMessages(segment, requestTools), effortProjection),
-    messageCacheSlots
+    lowerHistory(chatMsgs, effortProjection),
+    messageCacheSlots,
+    sharedCachePrefixBoundary(messages, opts, (prefix) =>
+      lowerHistory(prefix, projectEffortConfiguration(prefix, 'anthropic-oauth', model, opts))
+    )
   );
 
   const body = {
@@ -238,10 +249,8 @@ function buildRequestBody(messages, model, tools, sendOpts) {
   // tool_choice only when tools are actually present (Anthropic rejects
   // tool_choice without tools). 'none' rides the hard-cap final turn to
   // forbid tool USE while keeping the tools prefix stable for cache reuse.
-  if (body.tools) {
-    const toolChoice = toAnthropicToolChoice(opts.toolChoice);
-    if (toolChoice) body.tool_choice = toolChoice;
-  }
+  // Key reserved for wire order; resolved after thinking is applied.
+  if (body.tools) body.tool_choice = undefined;
 
   applyAnthropicEffortToBody(body, {
     model,
@@ -252,6 +261,16 @@ function buildRequestBody(messages, model, tools, sendOpts) {
     progressUpdates: true,
   });
 
+  if (body.tools) {
+    const toolChoice = toAnthropicToolChoice(opts.toolChoice, {
+      thinking: anthropicThinkingActive(body),
+      disableParallelToolUse: opts.disableParallelToolUse === true,
+      onThinkingConflict: opts.toolChoiceThinkingConflict,
+    });
+    if (toolChoice) body.tool_choice = toolChoice;
+    else delete body.tool_choice;
+  }
+
   // Skipped while the fast capacity pool is in cooldown (or permanently
   // unavailable) so a drained pool is not re-probed every turn.
   if (opts.fast === true && supportsAnthropicFastMode(model) && fastModeAvailable()) {

package/src/runtime/agent/orchestrator/providers/anthropic-sse-turn/turn-blocks.mjs

@@ -36,6 +36,20 @@ export function createTurnBlocks() {
   const appendText = (index, chunk) => {
     text.set(index, (text.get(index) || '') + (chunk || ''));
   };
+  // Per-index citations of a text block (content_block_start `citations` plus
+  // streamed citations_delta), replayed verbatim on the text block they cite.
+  const citations = new Map();
+  const appendCitation = (index, citation) => {
+    if (!citation || typeof citation !== 'object') return;
+    if (!text.has(index)) text.set(index, '');
+    let copy;
+    try {
+      copy = structuredClone(citation);
+    } catch {
+      copy = { ...citation };
+    }
+    citations.set(index, [...(citations.get(index) || []), copy]);
+  };
   // Client tool_use blocks that were actually dispatched, kept for the same
   // ordered replay list (deduped/skipped calls are intentionally absent).
   const clientToolUse = new Map();
@@ -61,7 +75,11 @@ export function createTurnBlocks() {
     ...thinking.entries(),
     ...[...text.entries()].map(([index, value]) => [
       index,
-      { type: 'text', text: typeof value === 'string' ? value : '' },
+      {
+        type: 'text',
+        text: typeof value === 'string' ? value : '',
+        ...(citations.get(index)?.length ? { citations: citations.get(index) } : {}),
+      },
     ]),
     ...completedNativeBlocks(),
     ...clientToolUse.entries(),
@@ -105,6 +123,7 @@ export function createTurnBlocks() {
     pendingToolInputs,
     clientToolUse,
     appendText,
+    appendCitation,
     toolInputInFlight,
     orderedThinkingBlocks,
     orderedAssistantBlocks,

package/src/runtime/agent/orchestrator/providers/anthropic-sse-turn/turn-events/content-block-delta.mjs

@@ -88,14 +88,27 @@ export function createContentBlockDelta({ turn, blocks, state, leak, relayText,
     progress('tool');
   };
 
-  return (index, delta) => {
+  const stampTtft = () => {
+    if (state && !state.ttftAt) state.ttftAt = Date.now();
+  };
+
+  const onContentBlockDelta = (index, delta) => {
     if (delta?.type) turn.contentBlockTypes.add(delta.type);
     // Time-to-first-token: stamp the first content delta (text / thinking /
     // tool input_json) exactly once so the SSE trace can separate first-byte
     // latency from total stream/generation time.
-    if (state && !state.ttftAt) state.ttftAt = Date.now();
+    stampTtft();
     if (delta?.type === 'text_delta') onTextDelta(index, delta.text);
+    if (delta?.type === 'citations_delta') blocks.appendCitation(index, delta.citation);
     if (delta?.type === 'thinking_delta' || delta?.type === 'signature_delta') onThinkingDelta(index, delta);
     if (delta?.type === 'input_json_delta') onInputJsonDelta(index, delta.partial_json);
   };
+  // A text block may open with non-empty `text` on content_block_start: it is
+  // model output and takes the same path as a text_delta (live relay, leak
+  // guard, returned content, ordered replay copy).
+  onContentBlockDelta.seedText = (index, initialText) => {
+    stampTtft();
+    onTextDelta(index, initialText);
+  };
+  return onContentBlockDelta;
 }