@framers/agentos 0.10.22 → 0.10.24

package/dist/core/llm/providers/implementations/AnthropicProvider.js

@@ -1,14 +1,15 @@
 // File: backend/agentos/core/llm/providers/implementations/AnthropicProvider.ts
-import { stripOpenRouterOnlyParams } from '../openrouter-only-params.js';
+import { stripForeignVendorParams } from '../openrouter-only-params.js';
 import { AnthropicProviderError } from '../errors/AnthropicProviderError.js';
 import { ApiKeyPool } from '../../../providers/ApiKeyPool.js';
-import { resolveThinkingPayload } from '../model-thinking.js';
+import { resolveThinkingOff, resolveThinkingPayload } from '../model-thinking.js';
 import { modelSupportsForcedToolChoice } from '../model-forced-tool-choice.js';
 import { modelSupportsStrictToolUse, toolInputSchemaSupportsStrict, toolInputSchemaWithExplicitNoExtraProps, } from '../model-strict-tool-use.js';
-import { modelSupportsEffort, isEffortLevel } from '../model-effort.js';
+import { resolveAnthropicEffort } from '../model-effort.js';
 import { computeRetryBackoffMs } from './retry-backoff.js';
 import { recordCacheUsage } from './cacheLeakDetector.js';
 import { resolveCacheCapabilities } from '../model-cache-capabilities.js';
+import { redactUrlSecrets } from '../url-secrets.js';
 // Re-export so callers that already reach for Anthropic model-capability
 // predicates (modelSupportsTemperature lives here too) find this one next to
 // it, even though its source of truth is the pure model-forced-tool-choice
@@ -21,11 +22,13 @@ export { modelSupportsForcedToolChoice };
  * Whether the given Claude model id accepts the `temperature` parameter.
  *
  * Anthropic deprecated `temperature` on reasoning-default models. Opus 4.7,
- * Opus 4.8, Opus 5, Opus 5.5, Sonnet 5, Fable 5 and Fable 5.1 reject requests
- * that include it with HTTP 400 "`temperature` is deprecated for this model."
- * Opus 5, Opus 5.5 and Fable 5.1 were live-probed on 2026-09-29. Opus 5.5 and
- * Fable 5.1 match the existing `opus-5` and `fable-5` alternatives because
- * `\b` matches at the hyphen before their trailing version digit.
+ * Opus 4.8, Opus 5, Opus 5.5, Sonnet 5, Sonnet 5.5, Fable 5 and Fable 5.1
+ * reject requests that include it with HTTP 400 "`temperature` is deprecated
+ * for this model." Opus 5, Opus 5.5 and Fable 5.1 were live-probed on
+ * 2026-09-29 and Sonnet 5.5 on 2026-09-30. Opus 5.5, Sonnet 5.5 and Fable 5.1
+ * match the existing `opus-5`, `sonnet-5` and `fable-5` alternatives on
+ * purpose, because `\b` matches at the hyphen before their trailing version
+ * digit.
  * Every earlier Claude model (Opus ≤ 4.6, Sonnet 4.6 and earlier, Haiku) still accepts it.
  * The same family also rejects `top_p` / `top_k`, so {@link buildRequestPayload}
  * gates `top_p` on this predicate too.
@@ -43,8 +46,8 @@ export { modelSupportsForcedToolChoice };
  */
 export function modelSupportsTemperature(modelId) {
     // Reasoning-default models that reject `temperature` (and `top_p` / `top_k`):
-    // Claude Opus 4.7 / 4.8 / 5 / 5.5, Sonnet 5, Fable 5 / 5.1, and any dated
-    // variant. Future reasoning-first siblings get added here as Anthropic
+    // Claude Opus 4.7 / 4.8 / 5 / 5.5, Sonnet 5 / 5.5, Fable 5 / 5.1, and any
+    // dated variant. Future reasoning-first siblings get added here as Anthropic
     // releases them, in lockstep with modelSupportsThinking.
     return !/^claude-(opus-4-(7|8)|opus-5|sonnet-5|fable-5)\b/i.test(modelId);
 }
@@ -77,17 +80,22 @@ export function normalizeCacheDiagnostics(diagnostics) {
 /**
  * Static catalog of well-known Anthropic models and their metadata.
  *
- * Pricing verified against anthropic.com/pricing on 2026-04-16 (USD per 1M tokens).
- * Update when Anthropic publishes new rate cards.
+ * Prices are USD per 1M tokens, verified against Anthropic's pricing page and
+ * model pages on 2026-09-30. A cache hit costs 0.1x the input price except
+ * where a row sets `pricePer1MTokensCacheRead`: Opus 5.5 (0.05x) and Fable 5.1
+ * (0.025x) differ, and Fable 5 states its standard 0.1x rate explicitly so
+ * the Fable 5.1 rate is not mistaken for it. Cache writes cost 1.25x the input
+ * price at the 5-minute TTL and 2x at the 1-hour TTL on every model; see
+ * {@link estimateAnthropicCostUSD}.
  *
  * `outputTokenLimit` is the model's real max output ceiling, surfaced via
- * getModelInfo for callers that want to size requests. It is informational —
- * NOT the per-request default: when a caller omits `maxTokens`, the request
- * falls back to `config.defaultMaxTokens`, not this value — but a per-call
- * `maxTokens` IS clamped to it via {@link clampAnthropicMaxTokens}. Anthropic
- * specs: Fable 5 = 128K output / 1M context, Opus 5 / 4.x = 128K output / 1M
- * context, Sonnet 5 / 4.6 = 128K output / 1M context, Sonnet 4.5 = 64K / 200K,
- * Haiku 4.5 = 64K output / 200K.
+ * getModelInfo for callers that want to size requests. It is informational,
+ * not the per-request default: when a caller omits `maxTokens`, the request
+ * falls back to `config.defaultMaxTokens`, but a per-call `maxTokens` is
+ * clamped to it via {@link clampAnthropicMaxTokens}. Anthropic's limits:
+ * Opus 5.5, Opus 5, Opus 4.6-4.8, Fable 5.1, Fable 5, Sonnet 5.5, Sonnet 5 and
+ * Sonnet 4.6 take 128K output with a 1M context; Opus 4.5, Sonnet 4.5 and
+ * Haiku 4.5 take 64K output with a 200K context.
  */
 const ANTHROPIC_MODELS = [
     {
@@ -100,6 +108,8 @@ const ANTHROPIC_MODELS = [
         outputTokenLimit: 128000,
         pricePer1MTokensInput: 4,
         pricePer1MTokensOutput: 20,
+        // Cache hits and refreshes bill at 0.05x the input price.
+        pricePer1MTokensCacheRead: 0.2,
         supportsStreaming: true,
         status: 'active',
     },
@@ -113,6 +123,8 @@ const ANTHROPIC_MODELS = [
         outputTokenLimit: 128000,
         pricePer1MTokensInput: 10,
         pricePer1MTokensOutput: 50,
+        // Cache hits and refreshes bill at 0.025x the input price.
+        pricePer1MTokensCacheRead: 0.25,
         supportsStreaming: true,
         status: 'active',
     },
@@ -126,6 +138,8 @@ const ANTHROPIC_MODELS = [
         outputTokenLimit: 128000,
         pricePer1MTokensInput: 10,
         pricePer1MTokensOutput: 50,
+        // The standard 0.1x rate. Fable 5.1's 0.025x does not apply to Fable 5.
+        pricePer1MTokensCacheRead: 1,
         supportsStreaming: true,
         status: 'active',
     },
@@ -181,6 +195,35 @@ const ANTHROPIC_MODELS = [
         supportsStreaming: true,
         status: 'active',
     },
+    {
+        // The dated id is the canonical row: the bare alias `claude-opus-4-5`
+        // resolves to it through the prefix fallback in resolveModelCatalogEntry,
+        // as `claude-haiku-4-5` resolves to the dated Haiku row.
+        modelId: 'claude-opus-4-5-20251101',
+        providerId: 'anthropic',
+        displayName: 'Claude Opus 4.5',
+        description: 'Legacy Opus, still served. Superseded by Claude Opus 5.5.',
+        capabilities: ['chat', 'tool_use', 'vision_input'],
+        contextWindowSize: 200000,
+        outputTokenLimit: 64000,
+        pricePer1MTokensInput: 5,
+        pricePer1MTokensOutput: 25,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'claude-sonnet-5-5',
+        providerId: 'anthropic',
+        displayName: 'Claude Sonnet 5.5',
+        description: 'Current Sonnet for everyday coding, agent and enterprise work; adaptive thinking on by default.',
+        capabilities: ['chat', 'tool_use', 'vision_input'],
+        contextWindowSize: 1000000,
+        outputTokenLimit: 128000,
+        pricePer1MTokensInput: 2,
+        pricePer1MTokensOutput: 10,
+        supportsStreaming: true,
+        status: 'active',
+    },
     {
         modelId: 'claude-sonnet-5',
         providerId: 'anthropic',
@@ -189,13 +232,14 @@ const ANTHROPIC_MODELS = [
         capabilities: ['chat', 'tool_use', 'vision_input'],
         contextWindowSize: 1000000,
         outputTokenLimit: 128000,
-        // Sticker rates ($2/$10 intro pricing runs through 2026-08-31 —
-        // meter at sticker so cost rollups stay conservative). Absent from
-        // this table the model priced as costUSD undefined, which turned
-        // the 2026-07-20..26 quota-outage fallback traffic (thousands of
-        // sonnet-5 leg calls/day) into unmetered spend.
-        pricePer1MTokensInput: 3,
-        pricePer1MTokensOutput: 15,
+        // $2/$10 is the standard price: Anthropic kept its launch pricing and
+        // cancelled the increase to $3/$15 scheduled for 2026-09-01 (pricing
+        // page, 2026-09-30). The row must stay in this table: without it the
+        // model prices as costUSD undefined, which turned the 2026-07-20..26
+        // quota-outage fallback traffic (thousands of sonnet-5 leg calls a day)
+        // into unmetered spend.
+        pricePer1MTokensInput: 2,
+        pricePer1MTokensOutput: 10,
         supportsStreaming: true,
         status: 'active',
     },
@@ -293,9 +337,10 @@ export function clampAnthropicMaxTokens(modelId, requested) {
  * Resolves a caller-supplied model id to its ANTHROPIC_MODELS catalog row.
  * Exact id match wins; otherwise a dated snapshot (`claude-sonnet-5-20260101`)
  * or bare alias is matched by prefix — the SAME resolution the max-tokens
- * clamp uses, shared so pricing and clamping can never disagree about which
- * row a model id means (estimateCost's exact-only match priced every dated
- * snapshot id as costUSD undefined: unmetered spend).
+ * clamp uses, shared so pricing ({@link estimateAnthropicCostUSD}) and
+ * clamping can never disagree about which row a model id means (an
+ * exact-only match prices every dated snapshot id as costUSD undefined:
+ * unmetered spend).
  *
  * The longest catalog id that prefixes `modelId` wins. Catalog ids nest:
  * `claude-opus-5` is a prefix of `claude-opus-5-5`. A first-match scan makes
@@ -315,9 +360,13 @@ export function resolveAnthropicModelEntry(modelId) {
  * @param catalog Model rows to search, in any order.
  * @param modelId Caller-supplied model id, bare or dated.
  * @returns The exact row, else the row with the longest id that prefixes
- *   `modelId`, else the first row whose id starts with `modelId`.
+ *   `modelId`, else the first row whose id starts with `modelId`. An empty id
+ *   resolves to nothing: every catalog id starts with `''`, so the last rule
+ *   would otherwise price a response with no model echo as the first row.
  */
 export function resolveModelCatalogEntry(catalog, modelId) {
+    if (!modelId)
+        return undefined;
     const exact = catalog.find((m) => m.modelId === modelId);
     if (exact)
         return exact;
@@ -329,9 +378,64 @@ export function resolveModelCatalogEntry(catalog, modelId) {
     }
     return longest ?? catalog.find((m) => m.modelId.startsWith(modelId));
 }
+/**
+ * Estimates the USD cost of one Anthropic Messages API call from its usage.
+ *
+ * | Tokens | Price |
+ * | --- | --- |
+ * | `input_tokens` | the input price |
+ * | `cache_read_input_tokens` | the row's `pricePer1MTokensCacheRead`, else 0.1x the input price |
+ * | 5-minute cache writes | 1.25x the input price |
+ * | 1-hour cache writes | 2x the input price |
+ * | `output_tokens` | the output price |
+ *
+ * `input_tokens` excludes cached tokens, so the input components add up
+ * without double counting. The 1-hour share of the writes comes from
+ * `cache_creation.ephemeral_1h_input_tokens`: a response without that split
+ * is priced as 5-minute writes only, and a 1-hour count above the write total
+ * is capped at the total.
+ *
+ * @param modelId Model id, bare or dated, resolved with
+ *   {@link resolveAnthropicModelEntry}.
+ * @param usage Token counts from the response.
+ * @returns The cost in USD, or `undefined` when the catalog has no price for
+ *   the model (unknown, empty or unpriced id).
+ */
+export function estimateAnthropicCostUSD(modelId, usage) {
+    const info = resolveAnthropicModelEntry(modelId);
+    const inputPrice = info?.pricePer1MTokensInput;
+    const outputPrice = info?.pricePer1MTokensOutput;
+    if (!inputPrice || !outputPrice)
+        return undefined;
+    const cacheReadPrice = info?.pricePer1MTokensCacheRead ?? inputPrice * 0.1;
+    const split = usage.cache_creation ?? undefined;
+    const written = usage.cache_creation_input_tokens
+        ?? ((split?.ephemeral_5m_input_tokens ?? 0) + (split?.ephemeral_1h_input_tokens ?? 0));
+    const writtenOneHour = Math.min(Math.max(split?.ephemeral_1h_input_tokens ?? 0, 0), written);
+    // Tokens times USD per 1M tokens: the sum is in millionths of a dollar.
+    const microDollars = usage.input_tokens * inputPrice
+        + (usage.cache_read_input_tokens ?? 0) * cacheReadPrice
+        + (written - writtenOneHour) * inputPrice * 1.25
+        + writtenOneHour * inputPrice * 2
+        + usage.output_tokens * outputPrice;
+    return microDollars / 1000000;
+}
 // ---------------------------------------------------------------------------
 // Provider implementation
 // ---------------------------------------------------------------------------
+/** Keys of warnings already printed by {@link warnOnce}. */
+const warnedKeys = new Set();
+/**
+ * Prints `message` once per process for `key`, so a setting applied to every
+ * request (thinking off on an always-on model, a capped effort) warns once
+ * rather than on every call.
+ */
+function warnOnce(key, message) {
+    if (warnedKeys.has(key))
+        return;
+    warnedKeys.add(key);
+    console.warn(message);
+}
 /**
  * @class AnthropicProvider
  * @implements {IProvider}
@@ -427,7 +531,10 @@ export class AnthropicProvider {
      * @param {ModelCompletionOptions} options - Completion options. `maxTokens` is strongly
      *   recommended; defaults to {@link AnthropicProviderConfig.defaultMaxTokens} if omitted.
      * @returns {Promise<ModelCompletionResponse>} A normalized completion response.
-     * @throws {AnthropicProviderError} On authentication, validation, or network errors.
+     * @throws {AnthropicProviderError} On authentication, validation, or network
+     *   errors, and with code `content_filter` when the model refuses
+     *   (`stop_reason: 'refusal'`); partial output from a refused turn is
+     *   discarded.
      */
     async generateCompletion(modelId, messages, options) {
         this.ensureInitialized();
@@ -442,8 +549,8 @@ export class AnthropicProvider {
         if (this.config.streamCompletions === false) {
             const payload = this.buildRequestPayload(modelId, messages, options, false);
             const apiResponse = await this.makeApiRequest('/v1/messages', 'POST', payload, options.requestTimeout);
-            this.recordCacheLeakSample(modelId, payload, apiResponse);
-            return this.mapResponseToCompletion(apiResponse, structuredOutputName);
+            this.recordCacheLeakSample(modelId, payload, apiResponse, options.cache === false);
+            return this.mapResponseToCompletion(apiResponse, structuredOutputName, modelId);
         }
         // Default: ride the SSE path so parseSseStream's idle watchdog bounds
         // mid-body stalls. A non-streaming POST cannot tell a hung connection
@@ -454,8 +561,8 @@ export class AnthropicProvider {
         // let the caller (or the retry loop below) recover in seconds.
         const payload = this.buildRequestPayload(modelId, messages, options, true);
         const apiResponse = await this.streamMessagesToResponse(payload, options.requestTimeout);
-        this.recordCacheLeakSample(modelId, payload, apiResponse);
-        return this.mapResponseToCompletion(apiResponse, structuredOutputName);
+        this.recordCacheLeakSample(modelId, payload, apiResponse, options.cache === false);
+        return this.mapResponseToCompletion(apiResponse, structuredOutputName, modelId);
     }
     /**
      * Feed one request's cache usage to the leak detector (see
@@ -464,9 +571,12 @@ export class AnthropicProvider {
      * 256 chars of the system prompt, read from the just-built payload so it
      * reflects what actually went to the wire. Fail-open by construction.
      *
+     * @param cacheOptOut True when the caller turned caching off for this
+     *   request (`options.cache === false`). Its uncached input is deliberate,
+     *   so the detector does not count it toward the `unmarked` warning.
      * @private
      */
-    recordCacheLeakSample(modelId, payload, apiResponse) {
+    recordCacheLeakSample(modelId, payload, apiResponse, cacheOptOut = false) {
         try {
             const system = payload.system;
             // Bound both branches to the 256-char callsite-identity window the
@@ -483,6 +593,7 @@ export class AnthropicProvider {
                 uncachedInputTokens: apiResponse.usage?.input_tokens ?? 0,
                 cacheReadTokens: apiResponse.usage?.cache_read_input_tokens ?? 0,
                 cacheCreationTokens: apiResponse.usage?.cache_creation_input_tokens ?? 0,
+                ...(cacheOptOut ? { cacheOptOut: true } : {}),
             });
         }
         catch {
@@ -564,6 +675,11 @@ export class AnthropicProvider {
      * {@link mapResponseToCompletion} stays the single mapping path
      * (structured output, stop reasons, cost, thinking blocks).
      *
+     * A refusal returns normally with `stop_reason: 'refusal'` and its
+     * `stop_details`, even when it cut a tool_use input off mid-JSON:
+     * {@link mapResponseToCompletion} raises it as a content-policy error, and
+     * a transport error here would be retried instead.
+     *
      * @throws {AnthropicProviderError} `STREAM_ERROR_EVENT` on an SSE error
      *   event, `STREAM_INCOMPLETE` when the stream ends before `message_delta`
      *   or a tool_use input JSON is truncated, plus whatever
@@ -574,10 +690,12 @@ export class AnthropicProvider {
         let id = `anthropic-stream-${Date.now()}`;
         let model = '';
         let stopReason = null;
+        let stopDetails;
         let inputTokens = 0;
         let outputTokens = 0;
         let cacheCreationTokens;
         let cacheReadTokens;
+        let cacheCreationSplit;
         let diagnostics;
         let sawMessageDelta = false;
         const blocks = new Map();
@@ -597,6 +715,8 @@ export class AnthropicProvider {
                     inputTokens = event.message.usage?.input_tokens ?? 0;
                     cacheCreationTokens = event.message.usage?.cache_creation_input_tokens;
                     cacheReadTokens = event.message.usage?.cache_read_input_tokens;
+                    // The 5m/1h split of the cache writes prices the 1h share at 2x.
+                    cacheCreationSplit = event.message.usage?.cache_creation;
                     // Cache diagnostics ride message_start in streaming responses.
                     diagnostics = event.message.diagnostics;
                     break;
@@ -647,6 +767,7 @@ export class AnthropicProvider {
                 case 'message_delta': {
                     sawMessageDelta = true;
                     stopReason = (event.delta.stop_reason ?? null);
+                    stopDetails = event.delta.stop_details ?? stopDetails;
                     // Anthropic reports the cumulative output total here — latest wins.
                     outputTokens = event.usage?.output_tokens ?? outputTokens;
                     break;
@@ -663,6 +784,9 @@ export class AnthropicProvider {
             throw new AnthropicProviderError('Stream ended before message_delta — response incomplete (connection dropped mid-message).', 'STREAM_INCOMPLETE');
         }
         const content = Array.from(blocks.entries())
+            // A refusal can cut a tool input off mid-JSON. The refused turn is
+            // discarded whole, so its tool calls are dropped rather than parsed.
+            .filter(([, block]) => stopReason !== 'refusal' || block.type !== 'tool_use')
             .sort((a, b) => a[0] - b[0])
             .map(([, block]) => {
             if (block.type === 'tool_use') {
@@ -691,11 +815,13 @@ export class AnthropicProvider {
             model,
             stop_reason: stopReason,
             stop_sequence: null,
+            ...(stopDetails !== undefined && { stop_details: stopDetails }),
             usage: {
                 input_tokens: inputTokens,
                 output_tokens: outputTokens,
                 ...(cacheCreationTokens !== undefined && { cache_creation_input_tokens: cacheCreationTokens }),
                 ...(cacheReadTokens !== undefined && { cache_read_input_tokens: cacheReadTokens }),
+                ...(cacheCreationSplit != null && { cache_creation: cacheCreationSplit }),
             },
             ...(diagnostics !== undefined && { diagnostics }),
         };
@@ -718,7 +844,10 @@ export class AnthropicProvider {
      * @param {ChatMessage[]} messages - Conversation messages.
      * @param {ModelCompletionOptions} options - Completion options.
      * @returns {AsyncGenerator<ModelCompletionResponse>} Incremental response chunks.
-     * @throws {AnthropicProviderError} On connection or stream errors.
+     * @throws {AnthropicProviderError} On connection errors, and with code
+     *   `content_filter` when the model refuses (`stop_reason: 'refusal'`),
+     *   before or after text has streamed. Other stream errors end the stream
+     *   with an error chunk.
      */
     async *generateCompletionStream(modelId, messages, options) {
         this.ensureInitialized();
@@ -737,6 +866,8 @@ export class AnthropicProvider {
         let outputTokens = 0;
         let cacheCreationTokens;
         let cacheReadTokens;
+        /** The 5m/1h split of the cache writes, reported on message_start. */
+        let cacheCreationSplit;
         /**
          * Cache-diagnostics verdict, delivered ONLY on message_start (no later
          * SSE event repeats it). `undefined` = the API sent none (not opted in);
@@ -779,6 +910,7 @@ export class AnthropicProvider {
                         // accumulate path at streamToCompletion does the same).
                         cacheCreationTokens = event.message.usage?.cache_creation_input_tokens;
                         cacheReadTokens = event.message.usage?.cache_read_input_tokens;
+                        cacheCreationSplit = event.message.usage?.cache_creation;
                         // Cache diagnostics ride message_start in streaming responses
                         // (mirrors the streamToCompletion aggregate path).
                         streamDiagnostics = event.message.diagnostics;
@@ -894,8 +1026,14 @@ export class AnthropicProvider {
                             // Cache-aware like the non-streaming path: input_tokens
                             // excludes cached tokens, so dropping the cache counts here
                             // undercosted every streamed turn once automatic caching
-                            // landed (reads 0.10x + writes 1.25x are real spend).
-                            costUSD: this.estimateCost(inputTokens, outputTokens, modelId, cacheReadTokens, cacheCreationTokens),
+                            // landed (cache reads and writes are real spend).
+                            costUSD: estimateAnthropicCostUSD(modelId, {
+                                input_tokens: inputTokens,
+                                output_tokens: outputTokens,
+                                cache_read_input_tokens: cacheReadTokens,
+                                cache_creation_input_tokens: cacheCreationTokens,
+                                cache_creation: cacheCreationSplit,
+                            }),
                             ...(cacheCreationTokens !== undefined && {
                                 cacheCreationInputTokens: cacheCreationTokens,
                             }),
@@ -925,7 +1063,14 @@ export class AnthropicProvider {
                                     cache_read_input_tokens: cacheReadTokens,
                                 }),
                             },
-                        });
+                        }, options.cache === false);
+                        // A refusal ends the turn unsuccessfully, whatever streamed before
+                        // it. Anthropic's contract is to discard the partial output; a
+                        // final chunk would let the caller keep it as the answer and run
+                        // tool calls parsed out of it.
+                        if (event.delta.stop_reason === 'refusal') {
+                            throw this.refusalError(modelId, event.delta.stop_details, accumulatedContent, usage);
+                        }
                         yield {
                             id: responseId,
                             object: 'chat.completion.chunk',
@@ -974,6 +1119,12 @@ export class AnthropicProvider {
             }
         }
         catch (streamError) {
+            // A refusal propagates as a thrown content-policy error, as
+            // GeminiProvider's safety block does, so the fallback chain can act on
+            // it instead of reading an error chunk.
+            if (streamError instanceof AnthropicProviderError && streamError.code === 'content_filter') {
+                throw streamError;
+            }
             const message = streamError instanceof Error ? streamError.message : 'Anthropic stream processing error';
             console.error(`AnthropicProvider stream error for model ${modelId}:`, message);
             yield {
@@ -1234,14 +1385,39 @@ export class AnthropicProvider {
             delete payload.temperature;
             delete payload.top_p;
         }
+        // --- Thinking off (options.thinking === false) ---
+        // Leaving the field out keeps the model's default, which is thinking ON
+        // for Opus 5 and Sonnet 5+, so turning it off takes the model's own
+        // shape. Some models accept that shape only at effort high or below; the
+        // effort block below caps it there.
+        let thinkingOffEffortCap;
+        if (!thinkingResolved && options.thinking === false) {
+            const off = resolveThinkingOff(modelId);
+            if (off.kind === 'send') {
+                payload.thinking = off.thinking;
+                thinkingOffEffortCap = off.maxEffort;
+            }
+            else if (off.kind === 'always_on') {
+                warnOnce(`thinking-always-on:${modelId}`, `[agentos] AnthropicProvider: thinking cannot be turned off on ${modelId}; the request runs ` +
+                    `with adaptive thinking. Lower options.effort to reduce it.`);
+            }
+        }
         // --- Effort (output_config.effort) ---
         // Reasoning depth + token-spend control on effort-capable Claude models
         // (Opus 4.5+/Sonnet 4.6/Fable/Mythos). Independent of thinking + tool_choice
-        // — it rides on output_config. Dropped on unsupported models OR invalid
-        // values so an out-of-range effort can never 400 the request.
-        if (options.effort && isEffortLevel(options.effort) && modelSupportsEffort(modelId)) {
+        // — it rides on output_config. Dropped on unsupported models or invalid
+        // values, and lowered to a level the model takes, so an out-of-range
+        // effort never returns 400 (see resolveAnthropicEffort).
+        let effort = resolveAnthropicEffort(modelId, options.effort);
+        if (thinkingOffEffortCap && (effort === 'xhigh' || effort === 'max')) {
+            warnOnce(`thinking-off-effort:${modelId}`, `[agentos] AnthropicProvider: ${modelId} turns thinking off only at effort ` +
+                `${thinkingOffEffortCap} or below; sending effort '${thinkingOffEffortCap}' ` +
+                `instead of '${effort}'.`);
+            effort = thinkingOffEffortCap;
+        }
+        if (effort) {
             const oc = payload.output_config ?? {};
-            payload.output_config = { ...oc, effort: options.effort };
+            payload.output_config = { ...oc, effort };
         }
         // --- Cache diagnostics (beta cache-diagnosis-2026-04-07) ---
         // Opt-in observability: the API compares this request against the one
@@ -1332,8 +1508,9 @@ export class AnthropicProvider {
             payload.tool_choice = { type: 'tool', name: sf.tool.name };
         }
         // Pass through any custom model params — minus OpenRouter's routing
-        // controls, which only OpenRouter's body accepts (a fallback leg reuses
-        // the same params object across hosts; see openrouter-only-params).
+        // controls and Gemini's request fields, which only those vendors' bodies
+        // accept (a fallback leg reuses the same params object across hosts; see
+        // openrouter-only-params).
         //
         // This runs BEFORE the forced tool_choice reconciliation below so that a
         // `tool_choice` injected through customModelParams is reconciled too —
@@ -1348,7 +1525,7 @@ export class AnthropicProvider {
         let customSystemOverride = false;
         let customMessagesOverride = false;
         {
-            const passthrough = stripOpenRouterOnlyParams(options.customModelParams);
+            const passthrough = stripForeignVendorParams(options.customModelParams);
             if (passthrough) {
                 customSystemOverride = Object.prototype.hasOwnProperty.call(passthrough, 'system');
                 customMessagesOverride = Object.prototype.hasOwnProperty.call(passthrough, 'messages');
@@ -1372,7 +1549,10 @@ export class AnthropicProvider {
         {
             const tc = payload.tool_choice;
             if (tc && (tc.type === 'any' || tc.type === 'tool')) {
-                const thinkingActive = Boolean(payload.thinking);
+                // Only a thinking-on shape conflicts with a forced tool_choice; the
+                // off shapes (disabled, between_tools) do not.
+                const thinkingType = payload.thinking?.type;
+                const thinkingActive = thinkingType === 'adaptive' || thinkingType === 'enabled';
                 const modelRejectsForced = !modelSupportsForcedToolChoice(modelId);
                 if (thinkingActive || modelRejectsForced) {
                     const reason = thinkingActive
@@ -1756,6 +1936,30 @@ export class AnthropicProvider {
                     }],
             };
         }
+        // --- Assistant text turn that carries thinking ---
+        // A session transcript records a final answer's signed thinking; it
+        // replays verbatim ahead of the answer's content, like a tool turn's.
+        // The content converts exactly as it would without thinking, so text
+        // parts keep their cache_control breakpoints. For models that do not
+        // retain prior thinking, the caller strips it from every assistant turn
+        // but the last one before this runs.
+        if (msg.role === 'assistant' && msg.thinkingBlocks?.length) {
+            const rest = this.toAnthropicMessage({ ...msg, thinkingBlocks: undefined });
+            const restContent = rest.content;
+            const blocks = Array.isArray(restContent)
+                ? restContent
+                : typeof restContent === 'string' && restContent
+                    ? [{ type: 'text', text: restContent }]
+                    : [];
+            // An answer with no content keeps the plain shape: Anthropic rejects an
+            // assistant turn that holds only thinking.
+            if (blocks.length === 0)
+                return rest;
+            const thinking = msg.thinkingBlocks.map((tb) => tb.type === 'thinking'
+                ? { type: 'thinking', thinking: tb.thinking, signature: tb.signature }
+                : { type: 'redacted_thinking', data: tb.data });
+            return { role: 'assistant', content: [...thinking, ...blocks] };
+        }
         // --- Multimodal content (vision) ---
         if (Array.isArray(msg.content)) {
             const anthropicContent = [];
@@ -1865,15 +2069,43 @@ export class AnthropicProvider {
      * the stop reason from Anthropic's vocabulary to IProvider conventions.
      *
      * @param {AnthropicMessagesResponse} apiResponse - Raw Anthropic response.
+     * @param structuredOutputName - Name of the forced structured-output tool,
+     *   whose input becomes the message content.
+     * @param requestedModelId - The model the request named. Prices the call
+     *   when the response carries no model echo.
      * @returns {ModelCompletionResponse} Normalized completion response.
+     * @throws {AnthropicProviderError} With code `content_filter` when the model
+     *   refused (`stop_reason: 'refusal'`), whether or not it wrote any output
+     *   first.
      * @private
      */
-    mapResponseToCompletion(apiResponse, structuredOutputName) {
+    mapResponseToCompletion(apiResponse, structuredOutputName, requestedModelId) {
+        const pricedModelId = apiResponse.model || requestedModelId || '';
         // Collect text content
         const textParts = apiResponse.content
             .filter(block => block.type === 'text' && block.text)
             .map(block => block.text);
         let fullText = textParts.join('');
+        const usage = {
+            promptTokens: apiResponse.usage.input_tokens,
+            completionTokens: apiResponse.usage.output_tokens,
+            totalTokens: apiResponse.usage.input_tokens + apiResponse.usage.output_tokens,
+            costUSD: estimateAnthropicCostUSD(pricedModelId, apiResponse.usage),
+            cacheCreationInputTokens: apiResponse.usage.cache_creation_input_tokens,
+            cacheReadInputTokens: apiResponse.usage.cache_read_input_tokens,
+            // Anthropic's input_tokens EXCLUDES cache reads/writes; the
+            // provider-independent inclusive input total adds them back
+            // (OpenAI/OpenRouter report prompt_tokens already inclusive).
+            inclusiveInputTokens: apiResponse.usage.input_tokens
+                + (apiResponse.usage.cache_read_input_tokens ?? 0)
+                + (apiResponse.usage.cache_creation_input_tokens ?? 0),
+        };
+        // A refused turn is discarded whole, even when the model wrote text or
+        // tool_use blocks before refusing, so it never reaches tool-call mapping
+        // and the caller can never run a tool from it.
+        if (apiResponse.stop_reason === 'refusal') {
+            throw this.refusalError(pricedModelId, apiResponse.stop_details, fullText, usage);
+        }
         // Collect tool_use blocks and convert to OpenAI-style tool_calls
         const toolCalls = apiResponse.content
             .filter(block => block.type === 'tool_use')
@@ -1913,20 +2145,6 @@ export class AnthropicProvider {
         }
         const hasToolCalls = toolCalls.length > 0;
         const finishReason = this.mapStopReason(apiResponse.stop_reason);
-        const usage = {
-            promptTokens: apiResponse.usage.input_tokens,
-            completionTokens: apiResponse.usage.output_tokens,
-            totalTokens: apiResponse.usage.input_tokens + apiResponse.usage.output_tokens,
-            costUSD: this.estimateCost(apiResponse.usage.input_tokens, apiResponse.usage.output_tokens, apiResponse.model, apiResponse.usage.cache_read_input_tokens, apiResponse.usage.cache_creation_input_tokens),
-            cacheCreationInputTokens: apiResponse.usage.cache_creation_input_tokens,
-            cacheReadInputTokens: apiResponse.usage.cache_read_input_tokens,
-            // Anthropic's input_tokens EXCLUDES cache reads/writes; the
-            // provider-independent inclusive input total adds them back
-            // (OpenAI/OpenRouter report prompt_tokens already inclusive).
-            inclusiveInputTokens: apiResponse.usage.input_tokens
-                + (apiResponse.usage.cache_read_input_tokens ?? 0)
-                + (apiResponse.usage.cache_creation_input_tokens ?? 0),
-        };
         const choice = {
             index: 0,
             message: {
@@ -1955,7 +2173,14 @@ export class AnthropicProvider {
      * - `end_turn` → `"stop"` (natural completion)
      * - `tool_use` → `"tool_calls"` (model wants to invoke tools)
      * - `max_tokens` → `"length"` (hit token limit)
+     * - `model_context_window_exceeded` → `"length"` (output cut off at the
+     *   context window)
      * - `stop_sequence` → `"stop"` (hit a caller-specified stop sequence)
+     * - `refusal` → `"content_filter"`, the name GeminiProvider and
+     *   OpenAIProvider use. Both response paths raise a refusal as an error
+     *   before a finish reason is reported; the mapping keeps the vocabulary
+     *   complete.
+     * - anything else (such as `pause_turn`) passes through unchanged.
      *
      * @param {string | null} stopReason - Anthropic's stop_reason value.
      * @returns {string} Normalized finish reason.
@@ -1966,10 +2191,32 @@ export class AnthropicProvider {
             case 'end_turn': return 'stop';
             case 'tool_use': return 'tool_calls';
             case 'max_tokens': return 'length';
+            case 'model_context_window_exceeded': return 'length';
             case 'stop_sequence': return 'stop';
+            case 'refusal': return 'content_filter';
             default: return stopReason ?? 'stop';
         }
     }
+    /**
+     * The error a refused turn raises. Code `content_filter` is what
+     * `isContentPolicyRefusal` recognizes, so the generateText and streamText
+     * fallback chains act on it, and the provider-health registry does not
+     * count it as a provider failure. The message carries no HTTP status or
+     * rate-limit wording, which retry classifiers grep for.
+     *
+     * @param modelId Model that refused.
+     * @param stopDetails The response's `stop_details`, kept verbatim.
+     * @param partialText Text the model wrote before refusing, discarded as an
+     *   answer but kept for diagnostics.
+     * @param usage Tokens the refused call consumed.
+     * @returns An error with code `content_filter` and Anthropic error type
+     *   `refusal`.
+     * @private
+     */
+    refusalError(modelId, stopDetails, partialText, usage) {
+        const category = stopDetails?.category;
+        return new AnthropicProviderError(`Claude declined the request on ${modelId || 'the requested model'} (stop_reason refusal${category ? `, category ${category}` : ''}).`, 'content_filter', undefined, 'refusal', { stopReason: 'refusal', stopDetails: stopDetails ?? null, partialText, usage });
+    }
     /**
      * Assembles completed tool calls from the streaming accumulator.
      *
@@ -1989,53 +2236,6 @@ export class AnthropicProvider {
             },
         }));
     }
-    /**
-     * Estimates USD cost for a given model and token counts.
-     *
-     * Looks up pricing from the static model catalog. Returns undefined
-     * if the model is not found in the catalog.
-     *
-     * @param {number} inputTokens - Number of input tokens.
-     * @param {number} outputTokens - Number of output tokens.
-     * @param {string} modelId - Model identifier for pricing lookup.
-     * @returns {number | undefined} Estimated cost in USD.
-     * @private
-     */
-    /**
-     * Estimate cost in USD for a completion, including Anthropic's prompt-
-     * caching tier pricing.
-     *
-     * Anthropic billing tiers (as of 2025):
-     *   input_tokens            × 1.00 × base input rate  (non-cached input)
-     *   cache_read_input_tokens × 0.10 × base input rate  (cache hit)
-     *   cache_creation_input_tokens × 1.25 × base input rate  (5-min TTL write)
-     *   output_tokens           × 1.00 × base output rate
-     *
-     * The API's `input_tokens` field already EXCLUDES cached tokens, so we
-     * sum three separate components for total input cost. Previous
-     * implementation used only `input_tokens` × rate, which happened to
-     * be correct for the non-cached portion but hid cache creation cost
-     * and ignored cache read cost entirely — meaning reported costUSD
-     * was always BELOW true billed amount whenever caching was active.
-     *
-     * 1-hour TTL cache-creation rate is 2× the base input rate, not 1.25×.
-     * We can't tell which TTL was used from the response, so we assume
-     * the default 5-minute tier. For long-lived cached contexts the
-     * reported cost will under-estimate by the 0.75× difference on
-     * creation tokens (minor; mostly one-shot at run start).
-     */
-    estimateCost(inputTokens, outputTokens, modelId, cacheReadTokens, cacheCreationTokens) {
-        const info = resolveAnthropicModelEntry(modelId);
-        if (!info?.pricePer1MTokensInput || !info?.pricePer1MTokensOutput)
-            return undefined;
-        const inputPrice = info.pricePer1MTokensInput;
-        const outputPrice = info.pricePer1MTokensOutput;
-        const nonCachedInput = (inputTokens / 1000000) * inputPrice;
-        const cachedRead = ((cacheReadTokens ?? 0) / 1000000) * inputPrice * 0.10;
-        const cachedCreate = ((cacheCreationTokens ?? 0) / 1000000) * inputPrice * 1.25;
-        const output = (outputTokens / 1000000) * outputPrice;
-        return nonCachedInput + cachedRead + cachedCreate + output;
-    }
     /**
      * Builds an abort chunk for early stream termination.
      *
@@ -2175,7 +2375,9 @@ export class AnthropicProvider {
                     lastError = new AnthropicProviderError(`Request timed out after ${effRequestTimeout}ms.`, 'REQUEST_TIMEOUT');
                 }
                 else {
-                    lastError = new AnthropicProviderError(error instanceof Error ? error.message : 'Network or unknown error', 'NETWORK_ERROR');
+                    // fetch names the URL (credentials included) when it rejects one,
+                    // and quotes a header value it rejects, which carries the key.
+                    lastError = new AnthropicProviderError(redactUrlSecrets(error instanceof Error ? error.message : 'Network or unknown error', this.config.baseURL, [apiKey]), 'NETWORK_ERROR');
                 }
                 if (attempt === this.config.maxRetries - 1)
                     break;
@@ -2264,7 +2466,9 @@ export class AnthropicProvider {
             clearTimeout(timeoutId);
             if (error instanceof AnthropicProviderError)
                 throw error;
-            throw new AnthropicProviderError(error instanceof Error ? error.message : 'Failed to connect to Anthropic stream.', 'STREAM_CONNECTION_FAILED');
+            // Masked like makeApiRequest's network failures: fetch's rejection
+            // can name a credential-bearing base URL or quote the key header.
+            throw new AnthropicProviderError(redactUrlSecrets(error instanceof Error ? error.message : 'Failed to connect to Anthropic stream.', this.config.baseURL, [apiKey]), 'STREAM_CONNECTION_FAILED');
         }
     }
     /**
@@ -2365,9 +2569,14 @@ export class AnthropicProvider {
             /* diagnostics must never break the request path */
         }
     }
-    /** True when the request enables extended thinking or replays thinking blocks. */
+    /**
+     * True when the request enables extended thinking or replays thinking
+     * blocks. `{ type: 'disabled' }` turns thinking off; `between_tools` still
+     * returns thinking blocks between tool calls, so it counts.
+     */
     payloadUsesThinking(body) {
-        if (body.thinking != null)
+        const thinkingType = body.thinking?.type;
+        if (body.thinking != null && thinkingType !== 'disabled')
             return true;
         const messages = body.messages;
         if (!Array.isArray(messages))