mixdog 0.8.0 → 0.9.0

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

@@ -3,18 +3,17 @@
  * for Claude Max subscription access.
  *
  * Raw HTTP + SSE streaming, reuses message/tool conversion patterns
- * from anthropic.mjs. Bridge-trace instrumented.
+ * from anthropic.mjs. agent-trace instrumented.
  */
 import { readFileSync, existsSync, statSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
 import { createServer } from 'http';
 import { randomBytes, createHash } from 'crypto';
 import {
-    traceBridgeFetch,
-    traceBridgeSse,
-    traceBridgeUsage,
-} from '../bridge-trace.mjs';
+    traceAgentFetch,
+    traceAgentSse,
+    traceAgentUsage,
+} from '../agent-trace.mjs';
 import { createAbortController } from '../../../shared/abort-controller.mjs';
 import { writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
@@ -31,12 +30,14 @@ import {
 } from '../stall-policy.mjs';
 import {
     classifyError,
+    midstreamBackoffFor,
     retryAfterMsFromError,
     withRetry,
 } from './retry-classifier.mjs';
 import { buildAnthropicBetaHeaders, supportsAnthropicFastMode } from './anthropic-betas.mjs';
 import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
 import { normalizeContentForAnthropic } from './media-normalization.mjs';
+import { makeInvalidToolArgsMarker } from './openai-compat-stream.mjs';
 
 // --- Model catalog cache helpers ---
 // Disk-backed cache so repeated process starts (cron, tool calls) don't
@@ -45,6 +46,36 @@ const MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
 // SSE progress emits (per-request "Response …" and "Done:" lines). Off by default.
 const SSE_VERBOSE = process.env.MIXDOG_SSE_VERBOSE === '1';
 
+/** Bounded mid-stream SSE retries (transient stream loss); shared with anthropic.mjs. */
+export const ANTHROPIC_MAX_MIDSTREAM_RETRIES = 3;
+
+function formatRetryAfter(ms) {
+    const n = Number(ms);
+    if (!Number.isFinite(n) || n < 0) return '';
+    if (n >= 60_000 && n % 60_000 === 0) return `${Math.round(n / 60_000)}m`;
+    if (n >= 1000) return `${Math.ceil(n / 1000)}s`;
+    return `${Math.ceil(n)}ms`;
+}
+
+function anthropicQuotaError(status, headers, bodyText = '') {
+    const retryAfterMs = retryAfterMsFromError({ headers, response: { headers } });
+    const retryAfter = formatRetryAfter(retryAfterMs);
+    const detail = bodyText ? `: ${String(bodyText).slice(0, 200)}` : '';
+    const retry = retryAfter ? ` retryAfter=${retryAfter}` : '';
+    const err = new Error(`Anthropic OAuth API ${status} quota/rate limit${retry}${detail}`);
+    err.name = 'ProviderQuotaError';
+    err.code = 'PROVIDER_QUOTA';
+    err.httpStatus = status;
+    err.status = status;
+    err.headers = headers;
+    err.response = { status, headers };
+    err.retryAfterMs = retryAfterMs;
+    err.providerQuota = true;
+    err.quotaExceeded = true;
+    err.unsafeToRetry = true;
+    return err;
+}
+
 const _modelCache = makeModelCache({
     fileName: 'anthropic-oauth-models.json',
     ttlMs: MODEL_CACHE_TTL_MS,
@@ -215,10 +246,9 @@ function assertSafeTokenURL(rawURL) {
     }
     return rawURL;
 }
-const TOKEN_URL = assertSafeTokenURL(process.env.ANTHROPIC_OAUTH_TOKEN_URL || 'https://console.anthropic.com/v1/oauth/token');
+const TOKEN_URL = assertSafeTokenURL(process.env.ANTHROPIC_OAUTH_TOKEN_URL || 'https://platform.claude.com/v1/oauth/token');
 const ANTHROPIC_VERSION = '2023-06-01';
 const DEFAULT_CREDENTIALS_PATH = join(resolvePluginData(), 'anthropic-oauth-credentials.json');
-const CLAUDE_CODE_CREDENTIALS_PATH = join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), '.credentials.json');
 const CLAUDE_CODE_CLIENT_ID = process.env.ANTHROPIC_OAUTH_CLIENT_ID || '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 const TOKEN_REFRESH_SKEW_MS = 5 * 60_000;
 const CLAUDE_AI_AUTHORIZE_URL = 'https://claude.com/cai/oauth/authorize';
@@ -235,15 +265,17 @@ const OAUTH_CALLBACK_HOST = 'localhost';
 const OAUTH_CALLBACK_PORT = 54545;
 const OAUTH_CALLBACK_PATH = '/callback';
 const OAUTH_REDIRECT_URI = `http://${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}${OAUTH_CALLBACK_PATH}`;
+const OAUTH_MANUAL_REDIRECT_URI = process.env.ANTHROPIC_OAUTH_MANUAL_REDIRECT_URI || 'https://platform.claude.com/oauth/code/callback';
+const OAUTH_SUCCESS_REDIRECT_URL = process.env.ANTHROPIC_OAUTH_SUCCESS_REDIRECT_URL || 'https://platform.claude.com/oauth/code/success?app=claude-code';
 const OAUTH_LOGIN_TIMEOUT_MS = 5 * 60_000;
 const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
 
-// Anthropic OAuth contract for first-party Claude Code clients.
+// 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
 // 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';
+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 DEFAULT_CLI_VERSION = '2.1.77';
 
 function resolveCliVersion() {
@@ -252,23 +284,30 @@ function resolveCliVersion() {
 }
 
 function requiresSystemPrefix(model) {
-    // Opus / Sonnet require the Claude Code system prefix when authenticated
+    // Opus / Sonnet require the OAuth system prefix when authenticated
     // via OAuth. Haiku does not.
     return /^claude-(opus|sonnet)/i.test(String(model || ''));
 }
 
 // OAuth rate-limit pool routing is gated by the server inspecting the first
-// system block. When it reads exactly "You are Claude Code, Anthropic's
-// official CLI for Claude." it routes into the Claude Code pool; any other
+// system block. When it reads exactly the OAuth system prefix string it routes
+// into the first-party OAuth pool; any other
 // content (even the prefix concatenated with extra text in the same block)
 // falls into the standard pool and Opus/Sonnet return 429. Splitting into
 // two blocks — [prefix, rest] — keeps both routing and user instructions.
-function buildSystemBlocks(systemText, model, cacheControl, maxCacheBlocks = 2) {
-    // systemText is an array of strings — each element becomes its own Anthropic
-    // content block with its own cache_control breakpoint (BP1 + BP2).
-    // Invariant: callers must pass an array; scalar strings are not accepted.
-    const texts = Array.isArray(systemText)
-        ? systemText.map(s => typeof s === 'string' ? s.trim() : '').filter(Boolean)
+function buildSystemBlocks(systemMsgs, model, systemTtl, tier3Ttl) {
+    // systemMsgs is an array of { content, cacheTier } — each non-empty element
+    // becomes its own Anthropic content block with its own cache_control
+    // breakpoint. Blocks tagged cacheTier:'tier3' (BP3 sessionMarker) take the
+    // tier3 TTL; every other block (BP1 baseRules / BP2 stableSystem) takes the
+    // system TTL. Invariant: callers must pass an array.
+    const items = Array.isArray(systemMsgs)
+        ? systemMsgs
+            .map(m => ({
+                text: typeof m?.content === 'string' ? m.content.trim() : '',
+                tier: m?.cacheTier === 'tier3' ? 'tier3' : 'system',
+            }))
+            .filter(it => it.text)
         : [];
     const gated = requiresSystemPrefix(model);
 
@@ -276,22 +315,24 @@ function buildSystemBlocks(systemText, model, cacheControl, maxCacheBlocks = 2)
     if (gated) {
         blocks.push({ type: 'text', text: CLAUDE_CODE_SYSTEM_PREFIX });
     }
-    for (let i = 0; i < texts.length; i++) {
-        let body = texts[i];
-        // Strip a duplicated Claude Code prefix from the first block if present.
+    for (let i = 0; i < items.length; i++) {
+        let body = items[i].text;
+        // Strip a duplicated OAuth system prefix from the first block if present.
         if (gated && i === 0 && body.startsWith(CLAUDE_CODE_SYSTEM_PREFIX)) {
             body = body.slice(CLAUDE_CODE_SYSTEM_PREFIX.length).trim();
             if (!body) continue;
         }
-        blocks.push({ type: 'text', text: body });
+        blocks.push({ type: 'text', text: body, _tier: items[i].tier });
     }
-    if (cacheControl) {
-        let remaining = Math.max(0, Math.min(2, Number(maxCacheBlocks) || 0));
-        for (let i = blocks.length - 1; i >= 0 && remaining > 0; i--) {
-            if (blocks[i]?.text === CLAUDE_CODE_SYSTEM_PREFIX) continue;
-            blocks[i] = { ...blocks[i], cache_control: cacheControl };
-            remaining -= 1;
-        }
+    // Apply per-tier cache_control. BP1/BP2 -> systemTtl, BP3 -> tier3Ttl. The
+    // gating prefix block is never cached (Anthropic routes on its exact bytes).
+    // tier3Ttl === null leaves the 3rd block uncached (e.g. maintenance roles).
+    for (const b of blocks) {
+        const tier = b._tier;
+        delete b._tier;
+        if (b.text === CLAUDE_CODE_SYSTEM_PREFIX) continue;
+        const ttl = tier === 'tier3' ? tier3Ttl : systemTtl;
+        if (ttl) b.cache_control = ttl;
     }
     return blocks;
 }
@@ -325,6 +366,18 @@ const EFFORT_BUDGET = {
     max: 32768,
 };
 
+const MIN_THINKING_BUDGET = 1024;
+const THINKING_OUTPUT_RESERVE = 1024;
+
+function clampThinkingBudgetTokens(value, maxTokens) {
+    const desired = Math.floor(Number(value));
+    const max = Math.floor(Number(maxTokens));
+    if (!Number.isFinite(desired) || desired <= 0 || !Number.isFinite(max)) return null;
+    const ceiling = max - THINKING_OUTPUT_RESERVE;
+    if (ceiling < MIN_THINKING_BUDGET) return null;
+    return Math.max(MIN_THINKING_BUDGET, Math.min(desired, ceiling));
+}
+
 // Tracks which unknown effort labels we've already logged so a repeated
 // session-level misconfig doesn't flood stderr with the same warning.
 const _LOGGED_UNKNOWN_EFFORT = new Set();
@@ -345,7 +398,6 @@ function credentialCandidates() {
     const paths = [];
     _pushUnique(paths, process.env.ANTHROPIC_OAUTH_CREDENTIALS_PATH);
     _pushUnique(paths, DEFAULT_CREDENTIALS_PATH);
-    _pushUnique(paths, CLAUDE_CODE_CREDENTIALS_PATH);
     return paths;
 }
 
@@ -385,21 +437,19 @@ function _loadCredentialsFile(path) {
     }
 }
 
-// Cross-process safe write-back. Lockfile (O_EXCL) prevents two refreshers
-// from clobbering each other; atomic rename guarantees readers see either
-// the old or new file, never a half-written one. Used so refresh_token
-// rotation propagates to other readers of the same credentials file instead of
-// leaving them stuck on the previous
-// refresh_token. Mirrors openai-oauth.mjs:saveTokens.
+// Cross-process safe credential save. Lockfile (O_EXCL) prevents two Mixdog
+// refreshers from clobbering each other; atomic rename guarantees readers see
+// either the old or new file, never a half-written one. Used so refresh_token
+// rotation propagates to other Mixdog readers of the same credentials file
+// instead of leaving them stuck on the previous refresh_token.
 function _saveCredentialsFile(path, raw) {
-    // No `secret: true`: this may be an externally-owned credentials file.
-    // Mixdog only writes back the rotated refresh_token and must not rewrite
-    // parent directory permissions.
-    writeJsonAtomicSync(path, raw, { lock: true, fsyncDir: true, mode: 0o600 });
+    // Secret file, not parent-dir ACL mutation. `secret: true` clamps the file
+    // itself on Windows; it deliberately leaves the data dir inheritance alone.
+    writeJsonAtomicSync(path, raw, { lock: true, fsyncDir: true, mode: 0o600, secret: true });
 }
 
-// Cheap stat-only probe so ensureAuth can detect host-rotated credentials
-// (claude login, logout/relogin) without paying a full JSON read every call.
+// Cheap stat-only probe so ensureAuth can detect Mixdog-updated credentials
+// without paying a full JSON read every call.
 function _credentialsMaxMtime() {
     let max = 0;
     for (const p of credentialCandidates()) {
@@ -433,7 +483,7 @@ export function describeAnthropicOAuthCredentials() {
     try {
         const creds = loadCredentials();
         if (!creds?.accessToken) {
-            return { authenticated: false, status: 'Not Set', detail: DEFAULT_CREDENTIALS_PATH };
+            return { authenticated: false, status: 'Not Set', detail: 'Mixdog OAuth credentials' };
         }
         const hasInferenceScope = Array.isArray(creds.scopes) && creds.scopes.includes('user:inference');
         const hasRefresh = Boolean(creds.refreshToken);
@@ -495,7 +545,7 @@ function _scrubTokens(text) {
 
 async function refreshOAuthCredentials(creds) {
     if (!creds?.refreshToken) {
-        throw new Error('Anthropic OAuth refresh token not available. Run /auth anthropic-oauth or /providers in mixdog to re-authenticate.');
+        throw new Error('Anthropic OAuth refresh token not available. Open /providers in mixdog to sign in again.');
     }
 
     const controller = new AbortController();
@@ -541,10 +591,10 @@ async function refreshOAuthCredentials(creds) {
             scopes: Array.isArray(json?.scope) ? json.scope : creds.scopes,
             subscriptionType: creds.subscriptionType,
         };
-        // Persist rotated tokens back so any other reader of the same
-        // credentials file picks up the new refresh_token.
-        // Without this, host's next refresh invalidates our copy and we
-        // loop on invalid_grant.
+        // Persist rotated tokens back so any other Mixdog reader of the same
+        // credentials file picks up the new refresh_token. Without this, a
+        // later process can replay an old single-use refresh token and loop on
+        // invalid_grant.
         if (creds.path && existsSync(creds.path)) {
             try {
                 const raw = JSON.parse(readFileSync(creds.path, 'utf-8'));
@@ -557,8 +607,8 @@ async function refreshOAuthCredentials(creds) {
                 };
                 _saveCredentialsFile(creds.path, raw);
             } catch (err) {
-                process.stderr.write(`[anthropic-oauth] credential write-back failed: ${_scrubTokens(err?.message || String(err)).slice(0, 200)}\n`);
-                throw new Error(`[oauth] credentials write-back failed: ${err?.message ?? String(err)}`);
+                process.stderr.write(`[anthropic-oauth] credential save failed: ${_scrubTokens(err?.message || String(err)).slice(0, 200)}\n`);
+                throw new Error(`[oauth] credentials save failed: ${err?.message ?? String(err)}`);
             }
         }
         return refreshed;
@@ -642,9 +692,11 @@ function _sanitizeInputSchema(schema, toolName) {
         if (addition) description = description ? `${description} ${addition}` : addition;
     }
     const mergedPropsCount = Object.keys(mergedProps).length;
-    process.stderr.write(
-        `[anthropic-oauth-sanitizer] tool="${toolName ?? ''}" compound="${compoundKey}" branches=${Array.isArray(compound) ? compound.length : 0} mergedProps=${mergedPropsCount}\n`
-    );
+    if (process.env.MIXDOG_DEBUG_SESSION_LOG) {
+        process.stderr.write(
+            `[anthropic-oauth-sanitizer] tool="${toolName ?? ''}" compound="${compoundKey}" branches=${Array.isArray(compound) ? compound.length : 0} mergedProps=${mergedPropsCount}\n`
+        );
+    }
     return {
         type: 'object',
         ...(description ? { description } : {}),
@@ -653,11 +705,28 @@ function _sanitizeInputSchema(schema, toolName) {
 }
 
 function toAnthropicTools(tools) {
-    return tools.map(t => ({
-        name: t.name,
-        description: t.description,
-        input_schema: _sanitizeInputSchema(t.inputSchema, t.name),
-    }));
+    return tools.map(t => {
+        const out = {
+            name: t.name,
+            description: t.description,
+            input_schema: _sanitizeInputSchema(t.inputSchema, t.name),
+        };
+        if (t.deferLoading === true || t.defer_loading === true) out.defer_loading = true;
+        return out;
+    });
+}
+function nativeAnthropicTools(opts) {
+    return Array.isArray(opts?.nativeTools)
+        ? opts.nativeTools.filter(t => t && typeof t === 'object')
+        : [];
+}
+function deferredAnthropicTools(activeTools, opts) {
+    if (opts?.session?.deferredNativeTools !== true) return [];
+    const active = new Set((activeTools || []).map((tool) => String(tool?.name || '').trim()).filter(Boolean));
+    const catalog = Array.isArray(opts.session.deferredToolCatalog) ? opts.session.deferredToolCatalog : [];
+    return catalog
+        .filter((tool) => tool?.name && !active.has(String(tool.name)))
+        .map((tool) => ({ ...tool, deferLoading: true }));
 }
 
 function toAnthropicMessages(messages) {
@@ -694,10 +763,15 @@ function toAnthropicMessages(messages) {
 
         if (m.role === 'tool') {
             const last = result[result.length - 1];
+            const refs = Array.isArray(m.nativeToolSearch?.toolReferences)
+                ? m.nativeToolSearch.toolReferences.map((name) => String(name || '').trim()).filter(Boolean)
+                : [];
             const block = {
                 type: 'tool_result',
                 tool_use_id: m.toolCallId || '',
-                content: normalizeContentForAnthropic(m.content),
+                content: refs.length
+                    ? refs.map((name) => ({ type: 'tool_reference', tool_name: name }))
+                    : normalizeContentForAnthropic(m.content),
             };
             if (last?.role === 'user' && Array.isArray(last.content)) {
                 last.content.push(block);
@@ -717,17 +791,15 @@ function toAnthropicMessages(messages) {
 // sanitizeAnthropicContentPairs has already run (and must NOT run again
 // after this), the blocks we mark here are exactly the blocks the provider
 // sees, so the cache breakpoint is stable across turns.
-//   tier3:        the user message whose first text block / string content
-//                 startsWith '<system-reminder>' AND includes BP3_SENTINEL —
-//                 mark its last content block with tier3Ttl.
 //   message-anchor: prefer a safe tool_result tail, then a previous real user
 //                   text turn if another slot remains. Synthetic
 //                   <system-reminder> messages and current pure-text prompts
 //                   are excluded so first-turn prompts do not create a fresh
 //                   BP4 write on every new session.
-// messageTtl === null disables the tail; tier3Ttl === null disables tier3.
+// messageTtl === null disables the tail. BP3 (tier3) now rides a system block,
+// so it is no longer marked here.
 // ANTHROPIC_MSG_SLOTS=0 is honoured upstream by passing messageTtl = null.
-function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_VOLATILE, messageSlots = 1, tier3Ttl = null } = {}) {
+function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_VOLATILE, messageSlots = 1 } = {}) {
     if (!Array.isArray(sanitizedMessages) || sanitizedMessages.length === 0) {
         return sanitizedMessages;
     }
@@ -741,29 +813,20 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
         return '';
     };
     const isSystemReminder = (content) => firstText(content).startsWith('<system-reminder>');
-    const isTier3SystemReminder = (content) => {
-        const text = firstText(content);
-        return text.startsWith('<system-reminder>') && text.includes(BP3_SENTINEL);
-    };
 
     const markLast = (msg, ttl) => {
         if (!msg) return;
         msg.content = appendCacheControl(msg.content, ttl);
     };
     const ttlRank = (ttl) => ttl?.ttl === '1h' ? 2 : 1;
-    const canMarkMessageIdx = (idx, tier3Idx) => {
-        // Anthropic requires 1h cache_control blocks to appear before 5m
-        // blocks. If tier3 is a later 1h marker, do not put a 5m marker before
-        // it. Gateway Anthropic routes set messages:'1h', so this guard mostly
-        // protects raw/default callers.
+    const canMarkMessageIdx = (idx) => {
+        // System-reminder messages (volatileTail / roleSpecific BP4) vary
+        // per-call, so never pin them with a 1h marker. The 1h system blocks
+        // (BP1/BP2/BP3) already satisfy Anthropic's "1h before 5m" ordering.
         if (idx < 0) return false;
         const msg = sanitizedMessages[idx];
         if (ttlRank(messageTtl) > ttlRank(CACHE_TTL_VOLATILE)
-            && isSystemReminder(msg?.content)
-            && !isTier3SystemReminder(msg?.content)) {
-            return false;
-        }
-        if (tier3Idx >= 0 && idx < tier3Idx && ttlRank(messageTtl) < ttlRank(tier3Ttl)) {
+            && isSystemReminder(msg?.content)) {
             return false;
         }
         return true;
@@ -798,29 +861,16 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
         return -1;
     };
 
-    // tier3 — locate the sentinel-tagged system-reminder user message.
-    let tier3MsgIdx = -1;
-    if (tier3Ttl !== null) {
-        for (let i = 0; i < sanitizedMessages.length; i++) {
-            const m = sanitizedMessages[i];
-            if (m?.role === 'user' && isTier3SystemReminder(m.content)) {
-                tier3MsgIdx = i;
-                break;
-            }
-        }
-        if (tier3MsgIdx >= 0) markLast(sanitizedMessages[tier3MsgIdx], tier3Ttl);
-    }
-
     if (messageTtl !== null) {
         const slots = Math.max(0, Math.min(4, Number(messageSlots) || 0));
-        const marked = new Set(tier3MsgIdx >= 0 ? [tier3MsgIdx] : []);
+        const marked = new Set();
         const candidates = [latestToolResultTailIdx(), previousUserTextAnchorIdx()];
         for (const idx of candidates) {
             if (slots <= 0) break;
-            if (idx < 0 || marked.has(idx) || !canMarkMessageIdx(idx, tier3MsgIdx)) continue;
+            if (idx < 0 || marked.has(idx) || !canMarkMessageIdx(idx)) continue;
             markLast(sanitizedMessages[idx], messageTtl);
             marked.add(idx);
-            if (marked.size - (tier3MsgIdx >= 0 ? 1 : 0) >= slots) break;
+            if (marked.size >= slots) break;
         }
     }
 
@@ -832,13 +882,34 @@ function applyAnthropicCacheMarkers(sanitizedMessages, { messageTtl = CACHE_TTL_
 function _captureMidstreamAbort(state, reason) {
     if (!state) return;
     const reasonName = reason?.name || '';
-    if (reasonName === 'BridgeStallAbortError' || reasonName === 'StreamStalledAbortError') {
+    if (reasonName === 'AgentStallAbortError' || reasonName === 'StreamStalledAbortError') {
         state.watchdogAbort = reasonName;
     } else {
         state.userAbort = true;
     }
 }
 
+async function _midstreamSleepWithAbort(ms, signal) {
+    if (!ms) return;
+    if (!signal) {
+        await new Promise((r) => setTimeout(r, ms));
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+            try { signal.removeEventListener('abort', onAbort); } catch {}
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            const reason = signal.reason;
+            reject(reason instanceof Error ? reason : new Error('Anthropic OAuth mid-stream retry backoff aborted'));
+        };
+        if (signal.aborted) { onAbort(); return; }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
 function _statusForAnthropicSseError(type, message) {
     const kind = String(type || '').toLowerCase();
     const text = String(message || '').toLowerCase();
@@ -894,7 +965,7 @@ async function parseSSEStream(response, signal, abortStream, onStreamDelta, onTo
     const resetIdleTimer = () => {
         // OFF by default. When disabled the
         // idle timer never arms, so the stream is never killed on inactivity;
-        // the bridge stall watchdog (600s) remains the dead-stream backstop.
+        // the agent stall watchdog (600s) remains the dead-stream backstop.
         if (!PROVIDER_SSE_IDLE_WATCHDOG_ENABLED) return;
         if (idleTimer) clearTimeout(idleTimer);
         idleTimer = setTimeout(() => {
@@ -975,7 +1046,7 @@ async function parseSSEStream(response, signal, abortStream, onStreamDelta, onTo
                 if (line.startsWith(':')) {
                     // SSE comment frame (Anthropic `:ping` keepalive). The HTML Standard SSE
                     // spec says comments are silently ignored, but we surface them here so
-                    // the bridge-stall-watchdog sees the stream is still alive during Opus
+                    // the agent stall watchdog sees the stream is still alive during Opus
                     // extended-thinking pauses. No content is emitted — this only refreshes
                     // the runtime's lastStreamDeltaAt timestamp.
                     try { onStreamDelta?.(); } catch {}
@@ -1062,15 +1133,15 @@ async function parseSSEStream(response, signal, abortStream, onStreamDelta, onTo
                             // whole tool_call — the loop never saw it and
                             // the assistant turn ended with an unmatched
                             // tool_use id. Wrap the parse so a malformed
-                            // input still produces a tool_call (with empty
-                            // arguments and a logged error) instead of a
-                            // silent drop.
+                            // input still produces a tool_call (with an
+                            // invalid-args marker and a logged error) instead
+                            // of a silent drop or accidental `{}` dispatch.
                             let parsedArgs = {};
                             if (pending.inputJson) {
                                 try { parsedArgs = JSON.parse(pending.inputJson); }
                                 catch (parseErr) {
                                     process.stderr.write(`[anthropic-oauth] tool args JSON.parse failed (id=${pending.id}, name=${pending.name}): ${parseErr?.message || parseErr}\n`);
-                                    parsedArgs = {};
+                                    parsedArgs = makeInvalidToolArgsMarker(pending.inputJson, parseErr instanceof Error ? parseErr.message : String(parseErr));
                                 }
                             }
                             // Tool arguments must be a plain object. Anthropic's
@@ -1189,7 +1260,7 @@ async function parseSSEStream(response, signal, abortStream, onStreamDelta, onTo
  */
 export function _classifyMidstreamError(err, state) {
     if (!state) return null;
-    if ((state.attemptIndex | 0) >= 1) return null;
+    if ((state.attemptIndex | 0) >= ANTHROPIC_MAX_MIDSTREAM_RETRIES) return null;
     if (state.sawCompleted) return null;
     if (!state.sawMessageStart) return null;
     if (state.userAbort) return null;
@@ -1200,9 +1271,9 @@ export function _classifyMidstreamError(err, state) {
     if (status === 401 || status === 403 || status === 429) return null;
 
     const name = err?.name || '';
-    if (name === 'BridgeStallAbortError') return 'bridge_stall';
+    if (name === 'AgentStallAbortError') return 'agent_stall';
     if (name === 'StreamStalledAbortError') return 'stream_stalled';
-    if (state.watchdogAbort === 'BridgeStallAbortError') return 'bridge_stall';
+    if (state.watchdogAbort === 'AgentStallAbortError') return 'agent_stall';
     if (state.watchdogAbort === 'StreamStalledAbortError') return 'stream_stalled';
 
     const code = err?.code || err?.cause?.code || '';
@@ -1232,69 +1303,51 @@ function resolveCacheTtls(opts) {
         return fallback;
     };
     // BP budget (4 total):
-    //   BP1 baseRules    — 1h (shared across ALL roles)
-    //   BP2 roleCatalog  — 1h (shared across ALL roles)
-    //   BP3 tier3        — 1h (sessionMarker: mixdog.md + stable role body)
+    //   BP1 baseRules    — 1h (shared tool policy + compact skill manifest)
+    //   BP2 stableSystem — 1h (role/system rules)
+    //   BP3 tier3        — 1h (sessionMarker: stable memory/meta body)
     //   BP4 messages     — 1h sliding tail (tool_result cache across iter)
     // tools BP is dropped — system BP covers the tools prefix via
     // Anthropic's prompt cache prefix semantics (order: tools → system
     // → messages).
     // tier3 defaults to 1h (stable) — sessionMarker content is stable per
-    // (role, permission, project) tuple and Anthropic only spends the BP
-    // slot when findTier3Index() actually finds a <system-reminder> block,
-    // so this default is free for sessions that don't carry one. Previously
-    // null here meant any caller that skipped smart bridge resolve (CLI,
-    // raw bridge spawn) silently lost the tier3 cache layer even
-    // though their message layout supported it.
+    // memory/meta tuple and the BP slot is only spent when a 3rd
+    // (cacheTier:'tier3') system block is actually present, so this default is
+    // free for sessions that don't carry one. Previously null here meant any
+    // caller that skipped agent runtime resolve (CLI, raw agent spawn)
+    // silently lost the tier3 cache layer even though it supported one.
     return {
-        tools: pick('tools', CACHE_TTL_STABLE),
+        tools: pick('tools', null),
         system: pick('system', CACHE_TTL_STABLE),
         tier3: pick('tier3', CACHE_TTL_STABLE),
         messages: pick('messages', CACHE_TTL_STABLE),
     };
 }
 
-// Tier 3 is injected by session/manager as a user message wrapped in
-// `<system-reminder>` whose body starts with the explicit sentinel
-// `<!-- bp3-sentinel -->` (emitted by collect.mjs:composeSystemPrompt only
-// when stable mixdog.md/role-specific context is present). The sentinel is mandatory:
-// volatileTail (role/permission/taskBrief/memoryRecap) is also wrapped in
-// `<system-reminder>` but varies per-call, so a plain prefix match would
-// pin per-call data to the 1h BP3 slot and explode the cache.
-const BP3_SENTINEL = '<!-- bp3-sentinel -->';
-function findTier3Index(chatMsgs) {
-    for (let i = 0; i < chatMsgs.length; i++) {
-        const m = chatMsgs[i];
-        if (m?.role === 'user' && typeof m.content === 'string'
-            && m.content.startsWith('<system-reminder>')
-            && m.content.includes(BP3_SENTINEL)) {
-            return i;
-        }
-    }
-    return -1;
-}
+// BP3 (tier3) is injected by session/manager as its own `system` role block —
+// the 3rd system block, tagged `cacheTier:'tier3'`. buildSystemBlocks applies
+// the tier3 1h cache_control to that block; BP1/BP2 take the system TTL. No
+// `<system-reminder>` user message / sentinel scan is involved anymore.
 
 function buildRequestBody(messages, model, tools, sendOpts) {
     const systemMsgs = messages.filter(m => m.role === 'system');
     const chatMsgs = messages.filter(m => m.role !== 'system');
-    // Pass each system message text as its own entry so the Anthropic body
-    // gets N separate content blocks — each can have its own BP
-    // independent of the others.
-    const systemTexts = systemMsgs.map(m => m.content);
     const maxTokens = resolveMaxTokens(model);
     const opts = sendOpts || {};
     const ttls = resolveCacheTtls(opts);
-    const systemBlocks = buildSystemBlocks(systemTexts, model, ttls?.system, 2);
+    // Each system message becomes its own Anthropic content block with its own
+    // breakpoint: BP1 baseRules + BP2 stableSystem at ttls.system, BP3
+    // sessionMarker (cacheTier:'tier3') at ttls.tier3.
+    const systemBlocks = buildSystemBlocks(systemMsgs, model, ttls?.system, ttls?.tier3);
 
     // 4-BP budget layout. tools BP is dropped — system BP covers the
     // tools prefix via Anthropic's prompt cache prefix semantics
-    // (order: tools → system → messages). That frees slots for
-    // tier3 + messages-tail.
-    const systemBpUsed = ttls.system ? systemBlocks.filter(b => b.cache_control).length : 0;
+    // (order: tools → system → messages). That frees slots for the
+    // messages-tail. The system blocks now hold BP1/BP2/BP3 (tier3), so the
+    // tier3 breakpoint is accounted for inside systemBpUsed.
+    const systemBpUsed = systemBlocks.filter(b => b.cache_control).length;
     const toolsBpUsed = 0;
-    const tier3Idx = ttls.tier3 ? findTier3Index(chatMsgs) : -1;
-    const tier3BpUsed = tier3Idx >= 0 ? 1 : 0;
-    const usedSlots = toolsBpUsed + systemBpUsed + tier3BpUsed;
+    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
     // so consecutive requests share a breakpoint; a second free slot marks the
@@ -1310,10 +1363,9 @@ function buildRequestBody(messages, model, tools, sendOpts) {
     // marked block. NEVER sanitize again after this (see send path).
     // msgSlots === 0 (ANTHROPIC_MSG_SLOTS=0, or no free slot) → tail disabled.
     const tailTtl = msgSlots > 0 ? ttls.messages : null;
-    const tier3Ttl = tier3Idx >= 0 ? ttls.tier3 : null;
     const anthropicMessages = applyAnthropicCacheMarkers(
         toAnthropicMessages(chatMsgs),
-        { messageTtl: tailTtl, messageSlots: msgSlots, tier3Ttl },
+        { messageTtl: tailTtl, messageSlots: msgSlots },
     );
 
     const body = {
@@ -1325,20 +1377,24 @@ function buildRequestBody(messages, model, tools, sendOpts) {
 
     if (systemBlocks.length) body.system = systemBlocks;
 
-    if (tools?.length) {
+    const nativeTools = nativeAnthropicTools(opts);
+    const deferredTools = deferredAnthropicTools(tools || [], opts);
+    if (tools?.length || nativeTools.length || deferredTools.length) {
         // No cache_control on tools — the systemBase BP already covers the
         // tools prefix via Anthropic's prompt cache prefix semantics (order:
         // tools → system → messages). Placing a separate BP here would waste
         // a slot that's better spent on messages tail.
-        body.tools = toAnthropicTools(tools);
+        body.tools = [...nativeTools, ...toAnthropicTools([...(tools || []), ...deferredTools])];
     }
 
     const thinkingBudgetTokens = Number(opts.thinkingBudgetTokens);
     if (Number.isFinite(thinkingBudgetTokens) && thinkingBudgetTokens > 0) {
-        body.thinking = { type: 'enabled', budget_tokens: Math.floor(thinkingBudgetTokens) };
+        const budgetTokens = clampThinkingBudgetTokens(thinkingBudgetTokens, maxTokens);
+        if (budgetTokens) body.thinking = { type: 'enabled', budget_tokens: budgetTokens };
     } else if (opts.effort) {
         if (EFFORT_BUDGET[opts.effort]) {
-            body.thinking = { type: 'enabled', budget_tokens: EFFORT_BUDGET[opts.effort] };
+            const budgetTokens = clampThinkingBudgetTokens(EFFORT_BUDGET[opts.effort], maxTokens);
+            if (budgetTokens) body.thinking = { type: 'enabled', budget_tokens: budgetTokens };
         } else if (!_LOGGED_UNKNOWN_EFFORT.has(opts.effort)) {
             _LOGGED_UNKNOWN_EFFORT.add(opts.effort);
             try {
@@ -1382,12 +1438,12 @@ export class AnthropicOAuthProvider {
             this.credentials = loadCredentials();
         }
         if (!this.credentials) {
-            throw new Error('Anthropic OAuth credentials not found. Run /auth anthropic-oauth or /providers in mixdog to authenticate.');
+            throw new Error('Anthropic OAuth credentials not found. Open /providers in mixdog to sign in.');
         }
 
-        // Pick up host-rotated tokens the moment the credentials file is
-        // rewritten — without this, a fresh `claude login` is ignored until
-        // the in-memory token's expiry skew triggers a refresh.
+        // Pick up Mixdog-updated tokens the moment the credentials file is
+        // rewritten — without this, a fresh /auth login in another process is
+        // ignored until the in-memory token's expiry skew triggers a refresh.
         const diskMtime = _credentialsMaxMtime();
         if (diskMtime > 0 && diskMtime > (this.credentials.mtimeMs || 0)) {
             const fresh = loadCredentials();
@@ -1439,7 +1495,7 @@ export class AnthropicOAuthProvider {
                     process.stderr.write(`[anthropic-oauth] WARNING: token expiring but no refresh token; using current token until expiry\n`);
                     return latest;
                 }
-                throw new Error('Anthropic OAuth refresh token not available. Run /auth anthropic-oauth or /providers in mixdog to re-authenticate.');
+                throw new Error('Anthropic OAuth refresh token not available. Open /providers in mixdog to sign in again.');
             }
 
             try {
@@ -1466,6 +1522,11 @@ export class AnthropicOAuthProvider {
     }
 
     async send(messages, model, tools, sendOpts) {
+        // Re-warm the kept-alive socket before the turn. preconnect() is a
+        // best-effort no-op while a socket is still hot (TTL gate), but after an
+        // idle gap longer than the keep-alive window it re-opens one in parallel
+        // with auth/body build so the POST below skips the cold TLS handshake.
+        preconnect('https://api.anthropic.com');
         // Defense-in-depth: enforce tool_use / tool_result pairing before
         // the Anthropic API call. The trim.mjs sanitize pass is normally
         // invoked by the budget trimmer in loop.mjs, but dispatches under
@@ -1502,7 +1563,7 @@ export class AnthropicOAuthProvider {
         //       (PROVIDER_HTTP_RESPONSE_TIMEOUT_MS) for a socket that never sends a
         //       first byte (truly wedged),
         //   (b) externalSignal (client disconnect / replaced-by-newer-request), and
-        //   (c) the bridge stall watchdog (STALL_ABORT_S, 600s, progress-based) plus
+        //   (c) the agent stall watchdog (STALL_ABORT_S, 600s, progress-based) plus
         //       the optional SSE idle watchdog for a stream that goes dead mid-flight.
         // totalSignal is therefore a pure pass-through of externalSignal with no timer.
         const totalTimeout = createPassthroughSignal(externalSignal);
@@ -1558,6 +1619,7 @@ export class AnthropicOAuthProvider {
                         'anthropic-beta': buildAnthropicBetaHeaders({
                             base: OAUTH_BETA_HEADERS,
                             fastMode: this.fastModeBetaHeaderLatched,
+                            toolSearch: true,
                         }),
                         'anthropic-dangerous-direct-browser-access': 'true',
                         'user-agent': `claude-cli/${resolveCliVersion()} (external, sdk-cli)`,
@@ -1569,7 +1631,7 @@ export class AnthropicOAuthProvider {
                     dispatcher: getLlmDispatcher(),
                 });
 
-                traceBridgeFetch({
+                traceAgentFetch({
                     sessionId,
                     headersMs: Date.now() - fetchStartedAt,
                     httpStatus: response.status,
@@ -1611,6 +1673,12 @@ export class AnthropicOAuthProvider {
             const status = Number(result?.response?.status || 0);
             const transientStatus = classifyError({ httpStatus: status }) === 'transient';
             if (transientStatus || status === 429) {
+                if (status === 429) {
+                    const quotaText = await result.response.text().catch(() => '');
+                    cleanupCancelHandler(result.cancelHandler);
+                    try { result.controller?.abort?.(); } catch {}
+                    throw anthropicQuotaError(status, result?.response?.headers, this.scrubTokens(quotaText));
+                }
                 const err = new Error(`Anthropic OAuth API ${status}`);
                 err.httpStatus = status;
                 err.status = status;
@@ -1642,9 +1710,9 @@ export class AnthropicOAuthProvider {
                 } catch {}
             },
         });
-        // One retry only: enough to recover transient stream loss without
-        // quietly replaying long-running work multiple times.
-        const MAX_MIDSTREAM_RETRIES = 1;
+        // Bounded mid-stream retries for transient stream loss; jittered backoff
+        // between attempts (see catch branches).
+        const MAX_MIDSTREAM_RETRIES = ANTHROPIC_MAX_MIDSTREAM_RETRIES;
         let firstAttemptError = null;
         let firstAttemptClassifier = null;
 
@@ -1669,6 +1737,10 @@ export class AnthropicOAuthProvider {
                 const safeText = this.scrubTokens(text).slice(0, 200);
                 process.stderr.write(`[anthropic-oauth] API error ${response.status}: ${safeText}\n`);
 
+                if (response.status === 429) {
+                    throw anthropicQuotaError(response.status, response.headers, safeText);
+                }
+
                 // Phase I: on unknown/404 model errors, force a catalog refresh and
                 // retry once. Protects against a silently-rotated model id.
                 const isUnknownModel = response.status === 404
@@ -1717,7 +1789,7 @@ export class AnthropicOAuthProvider {
 
                 const ttftMs = midState.ttftAt ? midState.ttftAt - sseStartedAt : null;
                 const liveModel = result.model || useModel;
-                traceBridgeSse({
+                traceAgentSse({
                     sessionId,
                     sseParseMs: Date.now() - sseStartedAt,
                     ttftMs,
@@ -1726,7 +1798,7 @@ export class AnthropicOAuthProvider {
                     transport: 'sse',
                 });
 
-                traceBridgeUsage({
+                traceAgentUsage({
                     sessionId,
                     iteration,
                     inputTokens: result.usage?.inputTokens || 0,
@@ -1799,6 +1871,7 @@ export class AnthropicOAuthProvider {
                     firstAttemptClassifier = 'empty_stream';
                     try { controller?.abort?.(err); } catch { /* best-effort teardown */ }
                     try { process.stderr.write(`[anthropic-oauth] empty stream (no message_start) — retry ${attemptIndex + 1}/${MAX_MIDSTREAM_RETRIES}\n`); } catch {}
+                    await _midstreamSleepWithAbort(midstreamBackoffFor(attemptIndex + 1), totalSignal);
                     continue;
                 }
                 if (classifyError(err) === 'transient'
@@ -1811,6 +1884,7 @@ export class AnthropicOAuthProvider {
                     try {
                         process.stderr.write(`[anthropic-oauth] transient SSE error — retry ${attemptIndex + 1}/${MAX_MIDSTREAM_RETRIES} (${err?.providerErrorType || err?.message || 'unknown'})\n`);
                     } catch {}
+                    await _midstreamSleepWithAbort(midstreamBackoffFor(attemptIndex + 1), totalSignal);
                     continue;
                 }
                 // Truncated stream (message_start without message_stop): the
@@ -1832,6 +1906,7 @@ export class AnthropicOAuthProvider {
                     firstAttemptClassifier = 'truncated_stream';
                     try { controller?.abort?.(err); } catch { /* best-effort teardown */ }
                     try { process.stderr.write(`[anthropic-oauth] truncated stream — retry ${attemptIndex + 1}/${MAX_MIDSTREAM_RETRIES}\n`); } catch {}
+                    await _midstreamSleepWithAbort(midstreamBackoffFor(attemptIndex + 1), totalSignal);
                     continue;
                 }
                 const classifier = _classifyMidstreamError(err, midState);
@@ -1845,6 +1920,7 @@ export class AnthropicOAuthProvider {
                     try {
                         process.stderr.write(`[anthropic-oauth] mid-stream recovered: retry ${attemptIndex + 1}/${MAX_MIDSTREAM_RETRIES} (cause: ${classifier})\n`);
                     } catch {}
+                    await _midstreamSleepWithAbort(midstreamBackoffFor(attemptIndex + 1), totalSignal);
                     continue;
                 }
                 if (attemptIndex > 0 && firstAttemptError) {
@@ -1982,31 +2058,118 @@ function _oauthParseScopeField(scope) {
     return String(scope || '').split(' ').filter(Boolean);
 }
 
-export async function loginOAuth() {
+function _parseOAuthCodeInput(input) {
+    const value = String(input || '').trim();
+    if (!value) return { code: '', state: '' };
+    try {
+        const url = new URL(value);
+        const code = url.searchParams.get('code') || '';
+        const state = url.searchParams.get('state') || '';
+        if (code || state) return { code, state, redirectUri: `${url.origin}${url.pathname}` };
+    } catch { /* not a URL */ }
+    if (value.includes('#')) {
+        const [code, state] = value.split('#', 2);
+        return { code: String(code || '').trim(), state: String(state || '').trim() };
+    }
+    if (value.includes('code=')) {
+        const params = new URLSearchParams(value.startsWith('?') ? value.slice(1) : value);
+        return { code: params.get('code') || '', state: params.get('state') || '' };
+    }
+    return { code: value, state: '' };
+}
+
+async function exchangeAuthorizationCode({ pkce, code, state, redirectUri }) {
+    const cleanCode = String(code || '').trim();
+    if (!cleanCode) throw new Error('[anthropic-oauth] authorization code is required');
+    const tokenRes = await fetch(TOKEN_URL, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'anthropic-dangerous-direct-browser-access': 'true',
+            'user-agent': `claude-cli/${resolveCliVersion()} (external, sdk-cli)`,
+        },
+        body: JSON.stringify({
+            grant_type: 'authorization_code',
+            code: cleanCode,
+            redirect_uri: redirectUri,
+            client_id: CLAUDE_CODE_CLIENT_ID,
+            code_verifier: pkce.verifier,
+            state,
+        }),
+        redirect: 'error',
+        signal: AbortSignal.timeout(OAUTH_TOKEN_TIMEOUT_MS),
+        dispatcher: getLlmDispatcher(),
+    });
+    if (!tokenRes.ok) {
+        const text = await tokenRes.text().catch(() => '');
+        throw new Error(`[anthropic-oauth] token exchange ${tokenRes.status}: ${_scrubTokens(text).slice(0, 500)}`);
+    }
+    const json = await tokenRes.json();
+    const accessToken = json?.access_token || json?.accessToken;
+    const refreshToken = json?.refresh_token || json?.refreshToken;
+    if (!accessToken || !refreshToken) {
+        throw new Error('[anthropic-oauth] token exchange response missing access_token or refresh_token');
+    }
+    const expiresAt = _normalizeExpiresAt(json?.expires_at ?? json?.expiresAt)
+        || (typeof json?.expires_in === 'number' ? Date.now() + json.expires_in * 1000 : 0);
+    const scopes = _oauthParseScopeField(json?.scope);
+    const credPath = _oauthCredentialsWritePath();
+    let raw = {};
+    if (existsSync(credPath)) {
+        raw = JSON.parse(readFileSync(credPath, 'utf-8'));
+    }
+    const existingOauth = raw.claudeAiOauth || {};
+    raw.claudeAiOauth = {
+        ...existingOauth,
+        accessToken,
+        refreshToken,
+        expiresAt,
+        scopes,
+        subscriptionType: existingOauth.subscriptionType ?? null,
+    };
+    _saveCredentialsFile(credPath, raw);
+    return {
+        path: credPath,
+        accessToken,
+        refreshToken,
+        expiresAt,
+        scopes,
+        subscriptionType: raw.claudeAiOauth.subscriptionType,
+    };
+}
+
+export async function beginOAuthLogin() {
     const pkce = _oauthGeneratePKCE();
     const state = randomBytes(32).toString('base64url');
-    const url = new URL(CLAUDE_AI_AUTHORIZE_URL);
-    url.searchParams.set('code', 'true');
-    url.searchParams.set('client_id', CLAUDE_CODE_CLIENT_ID);
-    url.searchParams.set('response_type', 'code');
-    url.searchParams.set('redirect_uri', OAUTH_REDIRECT_URI);
-    url.searchParams.set('scope', OAUTH_LOGIN_SCOPE);
-    url.searchParams.set('code_challenge', pkce.challenge);
-    url.searchParams.set('code_challenge_method', 'S256');
-    url.searchParams.set('state', state);
-
-    return new Promise((resolve, reject) => {
+    const buildUrl = (redirectUri) => {
+        const url = new URL(CLAUDE_AI_AUTHORIZE_URL);
+        url.searchParams.set('code', 'true');
+        url.searchParams.set('client_id', CLAUDE_CODE_CLIENT_ID);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('redirect_uri', redirectUri);
+        url.searchParams.set('scope', OAUTH_LOGIN_SCOPE);
+        url.searchParams.set('code_challenge', pkce.challenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        url.searchParams.set('state', state);
+        return url;
+    };
+    const url = buildUrl(OAUTH_REDIRECT_URI);
+    const manualUrl = buildUrl(OAUTH_MANUAL_REDIRECT_URI);
+
+    let server = null;
+    let timeout = null;
+    let finish = null;
+    const waitForCallback = new Promise((resolve, reject) => {
         let settled = false;
-        let timeout = null;
-        const settle = (value, error = null) => {
+        finish = (value, error = null) => {
             if (settled) return;
             settled = true;
             if (timeout) clearTimeout(timeout);
-            try { server.close(); } catch { /* already closed */ }
+            try { server?.close(); } catch { /* already closed */ }
             if (error) reject(error);
             else resolve(value);
         };
-        const server = createServer(async (req, res) => {
+        server = createServer(async (req, res) => {
             const u = new URL(req.url || '/', `http://${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}`);
             if (u.pathname !== OAUTH_CALLBACK_PATH) {
                 res.writeHead(404);
@@ -2017,76 +2180,24 @@ export async function loginOAuth() {
             if (!code || u.searchParams.get('state') !== state) {
                 res.writeHead(400);
                 res.end('Invalid');
-                settle(null);
+                finish(null);
                 return;
             }
-            res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end('<html><body><h2>Claude login successful! You can close this tab.</h2></body></html>');
             try {
-                const tokenRes = await fetch(TOKEN_URL, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'anthropic-dangerous-direct-browser-access': 'true',
-                        'user-agent': `claude-cli/${resolveCliVersion()} (external, sdk-cli)`,
-                    },
-                    body: JSON.stringify({
-                        grant_type: 'authorization_code',
-                        code,
-                        redirect_uri: OAUTH_REDIRECT_URI,
-                        client_id: CLAUDE_CODE_CLIENT_ID,
-                        code_verifier: pkce.verifier,
-                        state,
-                    }),
-                    redirect: 'error',
-                    signal: AbortSignal.timeout(OAUTH_TOKEN_TIMEOUT_MS),
-                    dispatcher: getLlmDispatcher(),
-                });
-                if (!tokenRes.ok) {
-                    const text = await tokenRes.text().catch(() => '');
-                    settle(null, new Error(`[anthropic-oauth] token exchange ${tokenRes.status}: ${_scrubTokens(text).slice(0, 500)}`));
-                    return;
-                }
-                const json = await tokenRes.json();
-                const accessToken = json?.access_token || json?.accessToken;
-                const refreshToken = json?.refresh_token || json?.refreshToken;
-                if (!accessToken || !refreshToken) {
-                    settle(null, new Error('[anthropic-oauth] token exchange response missing access_token or refresh_token'));
-                    return;
-                }
-                const expiresAt = _normalizeExpiresAt(json?.expires_at ?? json?.expiresAt)
-                    || (typeof json?.expires_in === 'number' ? Date.now() + json.expires_in * 1000 : 0);
-                const scopes = _oauthParseScopeField(json?.scope);
-                const credPath = _oauthCredentialsWritePath();
-                let raw = {};
-                if (existsSync(credPath)) {
-                    raw = JSON.parse(readFileSync(credPath, 'utf-8'));
-                }
-                const existingOauth = raw.claudeAiOauth || {};
-                raw.claudeAiOauth = {
-                    ...existingOauth,
-                    accessToken,
-                    refreshToken,
-                    expiresAt,
-                    scopes,
-                    subscriptionType: existingOauth.subscriptionType ?? null,
-                };
-                _saveCredentialsFile(credPath, raw);
-                resolve({
-                    path: credPath,
-                    accessToken,
-                    refreshToken,
-                    expiresAt,
-                    scopes,
-                    subscriptionType: raw.claudeAiOauth.subscriptionType,
-                });
+                const tokens = await exchangeAuthorizationCode({ pkce, code, state, redirectUri: OAUTH_REDIRECT_URI });
+                res.writeHead(302, { Location: OAUTH_SUCCESS_REDIRECT_URL });
+                res.end();
+                finish(tokens);
             } catch (err) {
-                settle(null, err instanceof Error ? err : new Error(String(err)));
+                const error = err instanceof Error ? err : new Error(String(err));
+                res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end(`Claude login failed: ${error.message}`);
+                finish(null, error);
             }
         });
-        timeout = setTimeout(() => settle(null), OAUTH_LOGIN_TIMEOUT_MS);
+        timeout = setTimeout(() => finish(null), OAUTH_LOGIN_TIMEOUT_MS);
         server.listen(OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_HOST, async () => {
-            process.stderr.write(`\n[anthropic-oauth] Open this URL to log in with Claude:\n${url.toString()}\n\n`);
+            process.stderr.write(`\n[anthropic-oauth] Open this URL to log in with Claude:\n${url.toString()}\n\nIf the localhost callback cannot complete, open this manual URL and paste the shown code#state:\n${manualUrl.toString()}\n\n`);
             try {
                 const { openInBrowser } = await import('../../../shared/open-url.mjs');
                 openInBrowser(url.toString());
@@ -2094,8 +2205,31 @@ export async function loginOAuth() {
                 process.stderr.write(`[anthropic-oauth] browser open failed: ${String(err?.message || err).slice(0, 200)}\n`);
             }
         });
-        server.on('error', (err) => settle(null, new Error(`[anthropic-oauth] callback server failed on ${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}: ${err?.message || err}`)));
+        server.on('error', (err) => finish(null, new Error(`[anthropic-oauth] callback server failed on ${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}: ${err?.message || err}`)));
     });
+
+    return {
+        provider: 'anthropic-oauth',
+        url: url.toString(),
+        manualUrl: manualUrl.toString(),
+        waitForCallback,
+        completeCode: async (input) => {
+            const parsed = _parseOAuthCodeInput(input);
+            if (parsed.state && parsed.state !== state) throw new Error('[anthropic-oauth] OAuth state mismatch');
+            const redirectUri = parsed.redirectUri || (parsed.state ? OAUTH_MANUAL_REDIRECT_URI : OAUTH_REDIRECT_URI);
+            const tokens = await exchangeAuthorizationCode({ pkce, code: parsed.code, state, redirectUri });
+            finish?.(tokens);
+            return tokens;
+        },
+        cancel: () => {
+            finish?.(null);
+        },
+    };
+}
+
+export async function loginOAuth() {
+    const login = await beginOAuthLogin();
+    return await login.waitForCallback;
 }
 
 // Additive exports for test harnesses.