mixdog 0.9.2 → 0.9.3

package/src/repl.mjs

@@ -1,16 +1,16 @@
 /**
- * mixdog REPL — styled inline terminal loop over the ported mixdog brain.
+ * mixdog REPL — styled inline terminal loop over the mixdog session runtime.
  *
- * Drives the *ported mixdog brain* through mixdog-session-runtime.mjs:
+ * Drives the session runtime through mixdog-session-runtime.mjs:
  * createSession + askSession own agentLoop/provider/tools/compaction, while
  * this module stays presentation-only: markdown-rendered replies, tool-call
  * cards, a per-turn statusline footer, slash commands, and arrow-key history.
  *
  * Flow:  stdin line → runtime.ask(prompt) → onTextDelta streams tokens to
- *        stdout live → tool calls render as cards → on turn end we re-render
- *        the assistant text as markdown → statusline footer.
+ * stdout live → tool calls render as cards → on turn end we re-render
+ * the assistant text as markdown → statusline footer.
  *
- * STREAMING DECISION (approach (a) from the brief):
+ * STREAMING DECISION:
  *   Live token streaming via onTextDelta conflicts with post-hoc markdown
  *   rendering (you can't style a heading until you've seen the whole line).
  *   We choose: stream raw tokens live so the turn FEELS alive, then on turn

package/src/rules/agent/30-explorer.md

@@ -6,16 +6,13 @@ kind: retrieval
 
 # Role: explorer
 
-Locator only: likely file/symbol/line anchors; no analysis, debugging, decisions,
-or recommendations.
+You are a one-shot locator, not a researcher.
 
-Output only:
-- `path:line — symbol/name — short reason`
-- or `EXPLORATION_FAILED`
-
-No preambles/tool-call preambles, bullets, headings, summaries, code quotes,
-verdicts, or invented coordinates. Weak anchors: `?`.
+Procedure: send ONE turn containing one `grep` (all synonyms in one
+`pattern:[...]`, output_mode content_with_context) plus one `code_graph`
+call. The results contain path:line — answer immediately from them.
+If both miss, answer `EXPLORATION_FAILED`. Do not send a second lookup turn.
 
-One batched lookup turn; first plausible anchor wins. No verification loop,
-synonym sweep, or proof-chasing. Hard stop after 5 tool calls; if uncertain,
-return best weak anchors with `?`.
+Answer format, nothing else:
+- up to 5 lines of `path:line — symbol/name — short reason` (append `?` if weak)
+- or `EXPLORATION_FAILED`

package/src/rules/lead/lead-tool.md

@@ -1,13 +1,17 @@
 # Lead Tool Use
 
-- Lead owns repo-local shell work: git, build, test, run, and verification commands.
+- Lead owns repo-local shell work: run git/build/test/verification commands via
+  `shell` directly; do not delegate them to agents.
 - Use the current project/workspace selected by the session. Only change the work project when the user asks for a different project or a tool call explicitly needs another project root.
-- Use `shell` directly for approved git/build/test/run work; do not delegate those commands to agents.
 - Use `agent` for scoped implementation, research, review, and debugging, not for git commit/push/stash or Ship.
-- Reuse the same agent tag/session for follow-up on the same scope (`send` or
-  `spawn` with the same tag reuses a live session). Spawn a new tag only for a
-  genuinely independent scope.
+- A `send` to a reaped/dead tag auto-respawns a FRESH session under the same
+  tag (result carries `respawned: true`). That worker has no prior session
+  context — treat the message as a cold brief and re-supply anchors
+  (`file:line`) on it or the next send.
 - Briefs: minimum characters, maximum information. Fixed one-line fragment
   fields — `Goal:` `Anchors:` `Allow/Forbid:` `Deliver:` `Verify:` (+`Stop:` for
   heavy-worker). Omit role-known rules (git/preamble bans, output format),
   background, motivation; non-actionable tokens are wasted cost.
+- Bridge language is ALWAYS English: every brief, follow-up `send`, and
+  steering message to an agent is written in English regardless of the
+  user-facing language.

package/src/rules/shared/01-tool.md

@@ -1,6 +1,8 @@
 # Tool Use
 
-- Independent lookups MUST batch in one turn; serialize only when a call needs a prior result.
+- Independent lookups MUST batch in one turn; serialize only when a call needs
+  a prior result. This includes edit loops: batch the post-edit verification
+  read with the next target's lookup instead of emitting single-call turns.
 - Target validity comes first: symbols/callers/deps → `code_graph`; exact text in
   a verified scope → `grep`; unknown path/name → `find`; structure → `glob`;
   dirs → `list`; verified file → `read`; broad unknown with no anchor →
@@ -10,10 +12,14 @@
   `code_graph symbols[]`). Refine from returned paths; do not repeat equivalent
   patterns or scopes.
 - On miss/error, normalize the target once and switch tool; on a plausible hit,
-  stop searching and answer from the framed context. Do not follow
-  `content_with_context` with `read` unless the needed span is not shown.
+  stop searching and answer from the framed context.
+- Lookup budget: retrieval exists to reach the NEXT action (edit, answer,
+  handoff), not to build certainty. One anchor is enough to act on; re-reading
+  or re-grepping an area you already saw this session is waste. When acting
+  and looking are both possible, act.
 - Avoid read fragmentation: `read` uses `offset`/`limit` only. If you need 2+
   spans from one or more known files, make one batched `read` call with
-  `{path,offset,limit}` region objects instead of serial reads.
-- `search`/`web_fetch` for external info; `recall` for history.
+  `{path,offset,limit}` region objects instead of serial reads. Adjacent spans
+  in the same file (within a few hundred lines) are ONE window, not repeated
+  reads.
 - Don't mix `apply_patch` with shell or other state-changing calls in one turn.

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -33,6 +33,47 @@ function mixdogAssetDirs(projectDir, kind) {
     dirs.push(mixdogGlobalDir(kind));
     return dirs;
 }
+/**
+ * Absolute path to the plugin registry file, or null when the data dir is
+ * unresolvable. Included in the skills mtime gate so plugin add/remove
+ * (which rewrites registry.json) invalidates the cached skill list even
+ * when no surviving skills dir got a newer mtime.
+ */
+function pluginRegistryPath() {
+    try {
+        return join(resolvePluginData(), 'plugins', 'registry.json');
+    } catch {
+        return null;
+    }
+}
+/**
+ * Read `<resolvePluginData()>/plugins/registry.json` (safe JSON parse, ignore
+ * errors) and yield `<root>/skills` for each registered plugin whose `root`
+ * exists on disk and has a `skills` subdirectory.
+ */
+function pluginSkillDirs() {
+    const registryPath = pluginRegistryPath();
+    if (!registryPath)
+        return [];
+    let registry;
+    try {
+        registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+    } catch {
+        return [];
+    }
+    if (!registry || !Array.isArray(registry.plugins))
+        return [];
+    const dirs = [];
+    for (const entry of registry.plugins) {
+        const root = entry && typeof entry.root === 'string' ? entry.root : null;
+        if (!root || !existsSync(root))
+            continue;
+        const skillsDir = join(root, 'skills');
+        if (existsSync(skillsDir))
+            dirs.push(skillsDir);
+    }
+    return dirs;
+}
 /**
  * Collect available skills (frontmatter only — token efficient).
  * Full content loaded on demand via loadSkillContent().
@@ -49,6 +90,9 @@ export function collectSkills(cwd) {
     // first, then user-global. When cwd is missing, only the global dir is
     // searched.
     const dirs = mixdogAssetDirs(projectDir, 'skills');
+    // Plugin-provided skills load last so project-local and global mixdog
+    // skill dirs keep precedence; `seen` below dedupes by frontmatter name.
+    dirs.push(...pluginSkillDirs());
     const seen = new Set();
     for (const dir of dirs) {
         if (!existsSync(dir))
@@ -88,6 +132,13 @@ export function collectSkillsCached(cwd) {
     const projectDir = (typeof cwd === 'string' && cwd.length > 0) ? cwd : null;
     // Same mixdog-owned dirs collectSkills() reads, used as the freshness gate.
     const skillsDirs = mixdogAssetDirs(projectDir, 'skills');
+    skillsDirs.push(...pluginSkillDirs());
+    // 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. maxMtimeRecursive stats plain files directly.
+    const registryPath = pluginRegistryPath();
+    if (registryPath)
+        skillsDirs.push(registryPath);
     let mtime;
     const mtimeCached = _mtimeCache.get(key);
     if (mtimeCached && Date.now() - mtimeCached.checkedAt < _MTIME_TTL_MS) {

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -1,4 +1,5 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync } from 'fs';
+import { writeFile } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
@@ -273,7 +274,10 @@ function capMcpOutput(content) {
         const dir = join(tmpdir(), 'mixdog-mcp-output');
         mkdirSync(dir, { recursive: true });
         spillPath = join(dir, `mcp-${Date.now()}-${randomUUID().slice(0, 8)}.txt`);
-        writeFileSync(spillPath, s, 'utf-8');
+        // Fire-and-forget: the spill path is returned to the caller
+        // immediately (below) for later recovery; the write itself must not
+        // block this hot tool-result path.
+        writeFile(spillPath, s, 'utf-8').catch(() => { /* spill best-effort */ });
     } catch { /* spill best-effort */ }
     const spillNote = spillPath
         ? `\n\n... [full output spilled to ${spillPath}] ...`

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

@@ -1,5 +1,5 @@
 /**
- * Anthropic effort API alignment (Claude Code effort.ts + configureEffortParams).
+ * Anthropic "effort" (extended-thinking budget) request parameter handling.
  */
 
 export const EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'max']);

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

@@ -0,0 +1,93 @@
+// Shared catalog-driven max_tokens resolution for both Anthropic providers
+// (OAuth and API-key). Extracted from anthropic-oauth.mjs so anthropic.mjs
+// (the API-key twin) gets the same sonnet-5+ / haiku fix instead of drifting
+// with its own hardcoded table.
+//
+// Resolution order:
+//   1. MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS env override, if set to a positive
+//      int, wins outright (returned as the safety cap itself).
+//   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].
+//   3. Static per-model table / family heuristic fallback when the catalog
+//      has no entry for this model, also capped at the safety cap.
+
+export const MAX_TOKENS_FLOOR = 8192;
+export const DEFAULT_SAFETY_CAP = 65536;
+const ENV_VAR = 'MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS';
+
+// Per-model max_tokens when the model id is explicitly listed. New models
+// (e.g., Sonnet 4.7) won't match a specific entry and fall through to the
+// family-based heuristic below. Conservative defaults — model may support
+// more but we'd rather stay within safe bounds.
+const MAX_TOKENS = {
+    'claude-opus-4-8': 65536,
+    'claude-opus-4-7': 65536,
+    'claude-opus-4-6': 65536,
+    'claude-sonnet-4-6': 16384,
+    'claude-haiku-4-5-20251001': 8192,
+};
+
+// Strict-positive env override parsing. Invalid values ("0", negatives,
+// garbage, whitespace) are treated as UNSET — not as "use the default cap
+// outright" — so catalog/fallback still decide for low-cap models. Raw env
+// truthiness must never bypass resolution.
+export function envAnthropicMaxOutputOverride() {
+    const raw = process.env[ENV_VAR];
+    if (raw == null || String(raw).trim() === '') return null;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    return Math.floor(n);
+}
+
+export function resolveAnthropicSafetyCap() {
+    return envAnthropicMaxOutputOverride() ?? DEFAULT_SAFETY_CAP;
+}
+
+// Pure lookup over an already-loaded catalog array (disk cache or in-memory
+// mirror) — no I/O, no caching strategy. Callers own how/when the array is
+// loaded/refreshed.
+export function lookupCatalogOutputTokens(models, id) {
+    if (!id || !Array.isArray(models)) return null;
+    const entry = models.find(m => m?.id === id);
+    const out = Number(entry?.outputTokens);
+    return Number.isFinite(out) && out > 0 ? out : null;
+}
+
+// Static per-model table + family heuristic, used when the catalog has no
+// entry for this model id. Sonnet 5+ ships a much larger output budget than
+// the legacy 4.x line (this is the claude-sonnet-5 fix: 16384 was starving
+// visible output once extended thinking ate into the same hard cap). Keep
+// sonnet-4-x conservative at 16384; only bump 5+.
+export function fallbackAnthropicMaxTokens(model) {
+    if (MAX_TOKENS[model]) return MAX_TOKENS[model];
+    const id = String(model || '').toLowerCase();
+    if (id.includes('opus')) return 65536;
+    if (id.includes('fable')) return 65536;
+    const sonnetVersion = id.match(/^claude-sonnet-(\d+)/);
+    if (sonnetVersion) return Number(sonnetVersion[1]) >= 5 ? 65536 : 16384;
+    if (id.includes('sonnet')) return 16384;
+    if (id.includes('haiku')) return 8192;
+    return 8192;
+}
+
+// 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;
+        }
+    }
+    if (Number.isFinite(catalogValue) && catalogValue > 0) {
+        return Math.max(MAX_TOKENS_FLOOR, Math.min(catalogValue, safetyCap));
+    }
+    return Math.min(fallbackAnthropicMaxTokens(model), safetyCap);
+}

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

@@ -19,6 +19,7 @@ import { writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
 import { enrichModels } from './model-catalog.mjs';
 import { makeModelCache } from './model-cache.mjs';
+import { resolveAnthropicMaxTokens } from './anthropic-max-tokens.mjs';
 import { sanitizeToolPairs, sanitizeAnthropicContentPairs } from '../session/context-utils.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
@@ -55,7 +56,7 @@ import { scanLeakedToolCalls, createToolCallDedupe } from './anthropic-leaked-to
 // hammer /v1/models. 24h TTL matches the upstream client cadence.
 const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
 // Bump when the on-disk cache shape changes so stale-shape entries are
-// discarded instead of misread (mirrors openai-oauth's schema-version gate).
+// discarded instead of misread.
 const ANTHROPIC_MODEL_CACHE_SCHEMA_VERSION = 1;
 // SSE progress emits (per-request "Response …" and "Done:" lines). Off by default.
 const SSE_VERBOSE = process.env.MIXDOG_SSE_VERBOSE === '1';
@@ -222,8 +223,7 @@ function _compareVersion(a, b) {
 }
 
 // Newest HIGH-TIER chat model by version, read from the SYNC in-memory catalog
-// mirror. Symmetric with resolveLatestGrokModel / resolveLatestCodexModel.
-// Anthropic ships three families: opus / sonnet / haiku. "Latest" is the
+// mirror. Anthropic ships three families: opus / sonnet / haiku. "Latest" is the
 // highest version across opus + sonnet only — haiku is the cheap tier and is
 // never the flagship default. Returns null until listModels() populates the
 // mirror; callers must warm the catalog (ensureLatestAnthropicModel) when null.
@@ -305,12 +305,11 @@ const OAUTH_SUCCESS_REDIRECT_URL = process.env.ANTHROPIC_OAUTH_SUCCESS_REDIRECT_
 const OAUTH_LOGIN_TIMEOUT_MS = 5 * 60_000;
 const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
 
-// Anthropic OAuth contract for first-party OAuth clients.
-// Opus/Sonnet requests are gated on a specific system-prompt prefix.
-// Mixdog keeps that upstream client contract for OAuth routing. Haiku is not
+// Anthropic OAuth contract for first-party OAuth clients: Opus/Sonnet
+// requests are gated on this exact system-prompt prefix. Haiku is not
 // gated and ignores this prefix.
 const CLAUDE_CODE_SYSTEM_PREFIX = "You are Claude Code, Anthropic's official CLI for Claude.";
-const OAUTH_BETA_HEADERS = 'oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,extended-cache-ttl-2025-04-11,advanced-tool-use-2025-11-20';
+const OAUTH_BETA_HEADERS = 'oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,extended-cache-ttl-2025-04-11';
 const DEFAULT_CLI_VERSION = '2.1.77';
 
 function resolveCliVersion() {
@@ -374,37 +373,6 @@ function buildSystemBlocks(systemMsgs, model, systemTtl, tier3Ttl) {
     return blocks;
 }
 
-// Per-model max_tokens when the model id is explicitly listed. New models
-// (e.g., Sonnet 4.7) won't match a specific entry and fall through to the
-// family-based heuristic below. Conservative defaults — model may support
-// more but we'd rather stay within safe bounds.
-const MAX_TOKENS = {
-    'claude-opus-4-8': 65536,
-    'claude-opus-4-7': 65536,
-    'claude-opus-4-6': 65536,
-    'claude-sonnet-4-6': 16384,
-    'claude-haiku-4-5-20251001': 8192,
-};
-
-// Sanity floor/ceiling for resolveMaxTokens. Catalog-reported outputTokens
-// (from the Anthropic API, cached to disk) can be trusted above these
-// hardcoded fallbacks, but we still clamp to a safety cap so a bad/huge
-// catalog value can't blow the thinking+output budget, and floor so a
-// missing/zero catalog value never degenerates to an unusable cap.
-const MAX_TOKENS_FLOOR = 8192;
-const DEFAULT_SAFETY_CAP = 65536;
-// Parse MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS strictly: only a finite positive
-// number is a valid override. Invalid values ("0", negatives, garbage,
-// whitespace) are treated as unset — NOT as "use the default cap outright" —
-// so resolveMaxTokens still consults catalog/fallback for low-cap models.
-function _envMaxOutputOverride() {
-    const raw = process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS;
-    if (raw == null || String(raw).trim() === '') return null;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0) return null;
-    return Math.floor(n);
-}
-
 // Catalog-reported outputTokens for a model id, read from the in-memory
 // catalog mirror (lazily populated from the disk cache if the mirror hasn't
 // been warmed yet by listModels()). Never throws — any failure just means
@@ -425,37 +393,17 @@ function _catalogOutputTokens(model) {
     }
 }
 
-function _fallbackMaxTokens(model) {
-    if (MAX_TOKENS[model]) return MAX_TOKENS[model];
-    const id = String(model || '').toLowerCase();
-    if (id.includes('opus')) return 65536;
-    if (id.includes('fable')) return 65536;
-    // Sonnet 5+ ships a much larger output budget than the legacy 4.x line
-    // (this is the claude-sonnet-5 fix: 16384 was starving visible output
-    // once extended thinking ate into the same hard cap). Keep sonnet-4-x
-    // conservative at 16384; only bump 5+.
-    const sonnetVersion = id.match(/^claude-sonnet-(\d+)/);
-    if (sonnetVersion) return Number(sonnetVersion[1]) >= 5 ? 65536 : 16384;
-    if (id.includes('sonnet')) return 16384;
-    if (id.includes('haiku')) return 8192;
-    return 8192;
-}
-
-// resolveMaxTokens: catalog-driven max_tokens for a model id.
+// resolveMaxTokens: catalog-driven max_tokens for a model id. Thin wrapper
+// around the shared anthropic-max-tokens helper (also used by the API-key
+// twin in anthropic.mjs) — this provider supplies its own in-memory-mirror-
+// first catalog lookup strategy.
 //   1. MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS env override, if set, wins outright.
 //   2. Catalog outputTokens (trusted over hardcoded heuristics when present),
 //      clamped to [MAX_TOKENS_FLOOR, safetyCap].
 //   3. Static MAX_TOKENS table / family heuristic fallback when the catalog
 //      has no entry for this model, also clamped to the safety cap.
 function resolveMaxTokens(model) {
-    const envOverride = _envMaxOutputOverride();
-    if (envOverride != null) return envOverride;
-    const safetyCap = DEFAULT_SAFETY_CAP;
-    const catalogValue = _catalogOutputTokens(model);
-    if (catalogValue != null) {
-        return Math.max(MAX_TOKENS_FLOOR, Math.min(catalogValue, safetyCap));
-    }
-    return Math.min(_fallbackMaxTokens(model), safetyCap);
+    return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokens });
 }
 
 const MIN_THINKING_BUDGET = 1024;
@@ -492,8 +440,8 @@ function credentialCandidates() {
 // Fallback expiry from the access_token's JWT `exp` claim (epoch ms) when the
 // credentials file carries no explicit expiresAt — without it expiresAt stays 0,
 // which ensureAuth reads as "never expires", disabling proactive refresh. Claude
-// OAuth tokens are opaque so this returns 0 and the file's expiresAt governs; kept
-// for parity with the other OAuth providers. JWT `exp` is epoch SECONDS (RFC 7519).
+// OAuth tokens are opaque so this returns 0 and the file's expiresAt governs.
+// JWT `exp` is epoch SECONDS (RFC 7519).
 function _expiryFromAccessToken(token) {
     try {
         const parts = String(token || '').split('.');
@@ -718,7 +666,7 @@ export class ReauthRequired extends Error {
     }
 }
 
-// --- Message conversion (mirrors anthropic.mjs) ---
+// --- Message conversion ---
 
 function withCacheControl(block, ttl = CACHE_TTL_VOLATILE) {
     if (!block || typeof block !== 'object' || block.cache_control) return block;
@@ -1068,7 +1016,8 @@ async function parseSSEStream(response, signal, abortStream, onStreamDelta, onTo
 
     // Synthesize + dispatch a recovered leaked call exactly like the native
     // content_block_stop path (push into toolCalls, flag state, eager
-    // onToolCall). A generated id mirrors the `toolu_`-prefixed native shape.
+    // onToolCall). A generated id uses the same `toolu_`-prefixed shape as
+    // Anthropic's native tool-call ids.
     const dispatchLeakedCall = (recovered) => {
         let args = recovered?.arguments;
         if (args === null || typeof args !== 'object' || Array.isArray(args)) args = {};
@@ -1790,6 +1739,11 @@ export class AnthropicOAuthProvider {
         if (body.speed === 'fast') {
             this.fastModeBetaHeaderLatched = true;
         }
+        // advanced-tool-use-2025-11-20 beta is only needed when this request
+        // actually carries deferred (defer_loading) tools — gate the header on
+        // that instead of sending it unconditionally on every request.
+        const hasDeferredTools = Array.isArray(body.tools)
+            && body.tools.some((t) => t && t.defer_loading === true);
         // Known tool names for the leaked-tool-call guard in parseSSEStream:
         // recovered leaked calls are only synthesized when they name a tool
         // actually offered to this request (native + lowered). Derived from the
@@ -1866,7 +1820,7 @@ export class AnthropicOAuthProvider {
                         'anthropic-beta': buildAnthropicBetaHeaders({
                             base: OAUTH_BETA_HEADERS,
                             fastMode: this.fastModeBetaHeaderLatched,
-                            toolSearch: true,
+                            toolSearch: hasDeferredTools,
                             effort: shouldIncludeEffortBeta(useModel, opts),
                         }),
                         'anthropic-dangerous-direct-browser-access': 'true',

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

@@ -22,6 +22,8 @@ import {
 } from './anthropic-effort.mjs';
 import { normalizeContentForAnthropic } from './media-normalization.mjs';
 import { enrichModels } from './model-catalog.mjs';
+import { makeModelCache } from './model-cache.mjs';
+import { resolveAnthropicMaxTokens } from './anthropic-max-tokens.mjs';
 import { getLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
 
 const require = createRequire(import.meta.url);
@@ -159,14 +161,49 @@ function _normalizeAnthropicModel(raw, provider = 'anthropic') {
 }
 // Family-based heuristic so new model ids (including custom user-configured
 // ones) resolve a sensible max_tokens without requiring a code change.
+// The API-key provider has no catalog cache of its own — it reads the same
+// anthropic-oauth-models.json disk cache (read-only) that the OAuth provider
+// maintains. Both providers hit the same Anthropic /v1/models catalog, so a
+// per-model outputTokens entry is valid regardless of which auth path wrote
+// it. If this provider is ever run standalone without the OAuth provider
+// ever having populated the cache, loadSync() simply returns null and we
+// fall through to the shared static heuristic in anthropic-max-tokens.mjs.
+const ANTHROPIC_OAUTH_MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
+const _sharedOAuthModelCache = makeModelCache({
+    fileName: 'anthropic-oauth-models.json',
+    ttlMs: ANTHROPIC_OAUTH_MODEL_CACHE_TTL_MS,
+    version: 1,
+});
+
+// In-memory mirror populated by this provider's own listModels() fetch.
+// API-key-only installs never have the OAuth provider write the shared disk
+// cache, so without this mirror catalog outputTokens would stay invisible to
+// resolveMaxTokens until an OAuth session runs. listModels() results flow in
+// here (memory only — the disk cache stays OAuth-owned/read-only for us).
+let _apiKeyCatalogMirror = null;
+
+function _catalogOutputTokensFromSharedCache(model) {
+    if (!model) return null;
+    try {
+        const models = Array.isArray(_apiKeyCatalogMirror)
+            ? _apiKeyCatalogMirror
+            : _sharedOAuthModelCache.loadSync();
+        if (!Array.isArray(models)) return null;
+        const entry = models.find(m => m?.id === model);
+        const out = Number(entry?.outputTokens);
+        return Number.isFinite(out) && out > 0 ? out : null;
+    } catch {
+        return null;
+    }
+}
+
 function resolveMaxTokens(model) {
-    const id = String(model || '').toLowerCase();
-    if (id.includes('opus')) return 32768;
-    if (id.includes('sonnet')) return 16384;
-    if (id.includes('haiku')) return 8192;
-    return 8192;
+    return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokensFromSharedCache });
 }
 
+// Test-only escape hatch for scripts/anthropic-maxtokens-test.mjs.
+export const _test = { resolveMaxTokens };
+
 const MIN_THINKING_BUDGET = 1024;
 const THINKING_OUTPUT_RESERVE = 1024;
 
@@ -464,8 +501,7 @@ export class AnthropicProvider {
         const usedSlots = toolsBpUsed + systemBpUsed;
         // Env override for BP strategy. ANTHROPIC_MSG_SLOTS=0 disables
         // message caching entirely. Any value >=1 first marks the previous
-        // user text turn; a second free slot marks the tail. Mirrors
-        // anthropic-oauth.mjs for twin parity.
+        // user text turn; a second free slot marks the tail.
         const msgSlotsCap = Number.parseInt(process.env.ANTHROPIC_MSG_SLOTS, 10);
         const defaultMsgSlots = Math.max(0, 4 - usedSlots);
         const msgSlots = ttls.messages
@@ -826,6 +862,9 @@ export class AnthropicProvider {
                 .map((m) => _normalizeAnthropicModel(m, this.name))
                 .filter(Boolean);
             const enriched = await enrichModels(normalized);
+            // Feed the resolver-visible mirror so API-key-only installs get
+            // catalog outputTokens without depending on the OAuth disk cache.
+            if (enriched.length) _apiKeyCatalogMirror = enriched.slice();
             return enriched.length ? enriched : MODELS;
         }
         catch (err) {

package/src/runtime/agent/orchestrator/providers/api-usage.mjs

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { updateJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
 import { getAgentApiKey, getOpenAIUsageSessionKey } from '../../../shared/config.mjs';
+import { num, round } from './lib/usage-primitives.mjs';
 
 const CACHE_FILE = 'api-usage-cache.json';
 const LIVE_TTL_MS = 5 * 60_000;
@@ -10,19 +11,6 @@ const STALE_TTL_MS = 60 * 60_000;
 const DISK_JSON_MEMORY_TTL_MS = 1000;
 let diskJsonCache = { at: 0, file: '', value: null };
 
-function num(value, fallback = null) {
-  if (value === null || value === undefined || value === '') return fallback;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : fallback;
-}
-
-function round(value, digits = 4) {
-  const n = Number(value);
-  if (!Number.isFinite(n)) return null;
-  const scale = 10 ** digits;
-  return Math.round(n * scale) / scale;
-}
-
 function cachePath() {
   return join(resolvePluginData(), CACHE_FILE);
 }

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

@@ -33,7 +33,7 @@ const DEFAULT_MODEL = MODELS[0].id;
 // VERSION-based (parse gemini-X.Y) rather than release-date based.
 const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
 // Bump when the on-disk cache shape changes so stale-shape entries are
-// discarded instead of misread (mirrors openai-oauth's schema-version gate).
+// discarded instead of misread.
 const GEMINI_MODEL_CACHE_SCHEMA_VERSION = 1;
 
 // De-dupes concurrent force-refreshes so they share one HTTP round-trip,

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

@@ -114,7 +114,7 @@ export function normalizeGrokModelId(id) {
 }
 const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
 // Bump when the on-disk cache shape changes so stale-shape entries are
-// discarded instead of misread (mirrors openai-oauth's schema-version gate).
+// discarded instead of misread.
 const GROK_MODEL_CACHE_SCHEMA_VERSION = 1;
 const DISCOVERY_TIMEOUT_MS = 15_000;
 const TOKEN_TIMEOUT_MS = 30_000;

package/src/runtime/agent/orchestrator/providers/lib/usage-primitives.mjs

@@ -0,0 +1,32 @@
+// Shared numeric/string primitives for provider usage-accounting modules.
+//
+// These are byte-for-byte identical helpers that were duplicated across
+// api-usage.mjs, oauth-usage.mjs and opencode-go-usage.mjs. Extracting them
+// here is behavior-preserving: each exported function reproduces the exact
+// logic of the copies it replaces.
+//
+// NOTE ON `num`: api-usage.mjs and oauth-usage.mjs use the guarded variant
+// below (treats null/undefined/'' as the fallback before Number()).
+// opencode-go-usage.mjs uses an *unguarded* variant (Number('') === 0), which
+// is observably different, so it keeps its own local `num` and is NOT wired to
+// this module.
+
+export function num(value, fallback = null) {
+  if (value === null || value === undefined || value === '') return fallback;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export function round(value, digits = 4) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  const scale = 10 ** digits;
+  return Math.round(n * scale) / scale;
+}
+
+// cleanString (oauth-usage.mjs) and clean (opencode-go-usage.mjs) were
+// identical: trim strings, coerce empties/non-strings to null.
+export function cleanString(value) {
+  const s = typeof value === 'string' ? value.trim() : '';
+  return s || null;
+}