@warlock.js/ai-anthropic 5.25.0 → 5.26.0

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: setup-anthropic
-description: 'Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → thinking budget_tokens, prompt caching via promptCaching + options.cacheControl, cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Triggers: `AnthropicSDK`, `anthropic.model`, `anthropic.count`, `maxTokens`, `reasoning`, `thinking`, `budget_tokens`, `cacheControl`, `promptCaching`, `cachedTokens`, `cacheWriteTokens`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`; "wire claude into warlock agent", "configure anthropic provider", "use claude sonnet", "anthropic gateway baseURL", "claude extended thinking", "anthropic prompt caching cost"; typical import `import { AnthropicSDK } from "@warlock.js/ai-anthropic"`. Skip: embeddings — `@warlock.js/ai-openai/setup-openai/SKILL.md`; sibling adapters `@warlock.js/ai-openai`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `@anthropic-ai/sdk`; Vercel `@ai-sdk/anthropic`.'
+description: 'Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, thinkingMode?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → adaptive thinking + output_config.effort (current/unknown models) or budget_tokens (Haiku 4.5, 4.6 and older; override with thinkingMode), prompt caching via promptCaching + options.cacheControl, cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Triggers: `AnthropicSDK`, `anthropic.model`, `anthropic.count`, `maxTokens`, `reasoning`, `thinking`, `budget_tokens`, `thinkingMode`, `adaptive`, `cacheControl`, `promptCaching`, `cachedTokens`, `cacheWriteTokens`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`; "wire claude into warlock agent", "configure anthropic provider", "use claude sonnet", "anthropic gateway baseURL", "claude extended thinking", "anthropic prompt caching cost"; typical import `import { AnthropicSDK } from "@warlock.js/ai-anthropic"`. Skip: embeddings — `@warlock.js/ai-openai/setup-openai/SKILL.md`; sibling adapters `@warlock.js/ai-openai`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `@anthropic-ai/sdk`; Vercel `@ai-sdk/anthropic`.'
 ---
 
 # `@warlock.js/ai-anthropic`
@@ -35,23 +35,23 @@ const proxied = new AnthropicSDK({
 ## Producing a model
 
 ```ts
-anthropic.model({ name: "claude-sonnet-4-6" })                  // common case
-anthropic.model({ name: "claude-haiku-4-5", temperature: 0.2 }) // sampling controls
-anthropic.model({ name: "claude-opus-4-7", maxTokens: 8192 })   // raise the cap
+anthropic.model({ name: "claude-sonnet-4-6" }); // common case
+anthropic.model({ name: "claude-haiku-4-5", temperature: 0.2 }); // sampling controls
+anthropic.model({ name: "claude-opus-4-7", maxTokens: 8192 }); // raise the cap
 ```
 
 ## Capabilities — what's auto-set
 
-| Flag | Default |
-| --- | --- |
-| `structuredOutput` | `true` (via Anthropic's native `output_config.format`) |
-| `vision` | Inferred from model name. `true` for Claude 3 / 3.5 / 3.7 / 4 family; `false` for pre-3 and unknown. |
-| `reasoning` | `true` — every modern Claude model accepts extended thinking. Override with `reasoning: false` for legacy/proxied targets that reject the `thinking` param. |
-| `promptCaching` | `true` — the adapter places `cache_control` breakpoints and reports both cache reads (`Usage.cachedTokens`) and writes (`Usage.cacheWriteTokens`). |
-| `pdf` | `true` — the Messages API accepts PDF/document content blocks on vision-capable models. |
-| `audio` | absent (`false`) — Anthropic has no audio-input block, so the agent rejects audio attachments upfront. |
+| Flag               | Default                                                                                                                                                                                                  |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `structuredOutput` | `true` (via Anthropic's native `output_config.format`)                                                                                                                                                   |
+| `vision`           | Inferred from model name. `true` for Claude 3 / 3.5 / 3.7 / 4 and Claude 5-series (`claude-opus-5*`, `claude-sonnet-5*`, `claude-fable-5*`, `claude-mythos-5*`); `false` for pre-3 and unknown ids.      |
+| `reasoning`        | `true` — forwarded in the shape the model accepts (see [Extended thinking](#extended-thinking-reasoning)). Override with `reasoning: false` for legacy/proxied targets that reject the `thinking` param. |
+| `promptCaching`    | `true` — the adapter places `cache_control` breakpoints and reports both cache reads (`Usage.cachedTokens`) and writes (`Usage.cacheWriteTokens`).                                                       |
+| `pdf`              | `true` — the Messages API accepts PDF/document content blocks on vision-capable models.                                                                                                                  |
+| `audio`            | absent (`false`) — Anthropic has no audio-input block, so the agent rejects audio attachments upfront.                                                                                                   |
 
-Explicit config always wins (`structuredOutput`, `vision`, `reasoning`).
+Explicit config always wins (`structuredOutput`, `vision`, `reasoning`, `thinkingMode`).
 
 ## Pricing & cost
 
@@ -62,7 +62,7 @@ Pricing is opt-in. Supply USD-per-million-token rates and every report this SDK'
 const anthropic = new AnthropicSDK({
   apiKey,
   pricing: {
-    "claude-haiku-4-5":  { input: 1, output: 5,  cachedInput: 0.1 },
+    "claude-haiku-4-5": { input: 1, output: 5, cachedInput: 0.1 },
     "claude-sonnet-4-6": { input: 3, output: 15, cachedInput: 0.3 },
   },
 });
@@ -77,11 +77,11 @@ Resolution at `model()` time: per-model `pricing` > SDK registry entry for that
 
 Every `ModelResponse.usage` (and the streaming terminal `done`) is normalized to the neutral `Usage` shape. Anthropic reports `input_tokens` / `output_tokens` separately with no pre-summed total, so `total` is computed (`input + output`). The two cache channels are surfaced only when non-zero:
 
-| Neutral field | Anthropic source | Meaning / billing |
-| --- | --- | --- |
-| `usage.cachedTokens` | `cache_read_input_tokens` | Subset of input served from the prompt cache. Bills at `cachedInput` (falls back to `input` when unset). |
-| `usage.cacheWriteTokens` | `cache_creation_input_tokens` | Input tokens **written** to the cache on this call (the ~1.25x write surcharge). Bills at `cachedOutput` when set. |
-| `usage.reasoningTokens` | — *(not reported separately)* | Anthropic bills extended-thinking tokens **inside** `output_tokens`, so this stays unset — populating it would double-count against `output`. |
+| Neutral field            | Anthropic source              | Meaning / billing                                                                                                                             |
+| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `usage.cachedTokens`     | `cache_read_input_tokens`     | Subset of input served from the prompt cache. Bills at `cachedInput` (falls back to `input` when unset).                                      |
+| `usage.cacheWriteTokens` | `cache_creation_input_tokens` | Input tokens **written** to the cache on this call (the ~1.25x write surcharge). Bills at `cachedOutput` when set.                            |
+| `usage.reasoningTokens`  | — _(not reported separately)_ | Anthropic bills extended-thinking tokens **inside** `output_tokens`, so this stays unset — populating it would double-count against `output`. |
 
 In streaming, `cachedTokens` / `cacheWriteTokens` are seeded from `message_start` and then **overwritten by the cumulative counts on `message_delta`** when those are present and non-zero, so the terminal `done` carries the final tally.
 
@@ -89,7 +89,9 @@ In streaming, `cachedTokens` / `cacheWriteTokens` are seeded from `message_start
 
 Unlike OpenAI, Anthropic **requires** `max_tokens` on every request. Resolution: per-call `options.maxTokens` > `config.maxTokens` > **default `4096`**. A caller who never sets a cap still gets a complete answer instead of a 400.
 
-With extended thinking enabled and no explicit cap, the adapter reserves answer room: `max_tokens = thinking budget + 4096`. An explicit `maxTokens` must be greater than the thinking budget or the call throws before it reaches Anthropic.
+With extended thinking enabled and no explicit cap, the adapter reserves answer room in both modes: `max_tokens = thinking budget + 4096`. In budget mode an explicit `maxTokens` must be greater than `budget_tokens` or the call throws before it reaches Anthropic.
+
+**Tiny caps + adaptive thinking:** thinking tokens count inside `max_tokens`, so a very small cap can be spent entirely on thinking. Live check: Sonnet 5.5 with `maxTokens: 60` returned `finishReason: "length"` and empty content. For tiny outputs give thinking room (raise `maxTokens`) or turn reasoning off (`reasoning: false` on the model, or no `options.reasoning`).
 
 ## System prompt
 
@@ -108,31 +110,70 @@ When the agent passes `responseSchema` and the model is `structuredOutput`-capab
 
 ## Extended thinking (reasoning)
 
-When the model is `reasoning`-capable (default `true`) and the agent passes `options.reasoning`, the adapter forwards Anthropic extended thinking as `thinking: { type: "enabled", budget_tokens }`:
+When the model is `reasoning`-capable (default `true`) and the agent passes `options.reasoning`, the adapter forwards Anthropic thinking in one of two shapes, chosen per model (`thinkingMode`):
+
+| Mode         | Models (inferred from the name)                                                                                                 | Wire shape                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `"adaptive"` | Current Claude models — Opus 4.7 / 4.8 / 5 / 5.5, Sonnet 5 / 5.5, Fable 5 / 5.1 — **and any id the adapter does not recognise** | `thinking: { type: "adaptive" }` + `output_config.effort` |
+| `"budget"`   | Haiku 4.5, Opus 4.6, Sonnet 4.6, and every older model (Claude 3.x, 4.0 / 4.1 / 4.5, 2, instant)                                | `thinking: { type: "enabled", budget_tokens }`            |
+
+Adaptive models reject `budget_tokens` with a 400, so the shape matters.
+
+- **Adaptive:** `reasoning.effort` (`"low" | "medium" | "high"`) → `output_config.effort` of the same name. With only `reasoning.maxTokens` set, effort is `"medium"`; `maxTokens` then only sizes the reserved `max_tokens` room, it is not sent as a budget.
+- **Budget:** `reasoning.maxTokens` → `budget_tokens` verbatim; `reasoning.effort` → a tiered budget (`1024` / `4096` / `12000`) when no `maxTokens` is given. Any resolved budget is floored at Anthropic's `1024` minimum.
+- `reasoning` with neither `effort` nor `maxTokens`, or `effort: "none"`, emits nothing.
 
-- `reasoning.maxTokens` → `budget_tokens` verbatim.
-- `reasoning.effort` (`"low" | "medium" | "high"`) → a tiered budget (`1024` / `4096` / `12000`) when no explicit `maxTokens` is given.
-- Any resolved budget is floored at Anthropic's `1024`-token minimum.
-- `reasoning` with neither `effort` nor `maxTokens` emits nothing.
+### `thinkingMode` override
 
-Because Anthropic 400s when `thinking` is combined with an explicit `temperature`, the adapter **drops `temperature`** for that request (thinking pins sampling to the default). Set `reasoning: false` on the model config to suppress the param entirely for proxied/legacy targets.
+`anthropic.model({ name, thinkingMode: "adaptive" | "budget" })` beats the name-based detection. Use it when the id does not look like an Anthropic id: region-prefixed / Bedrock-style ids (`us.anthropic.claude-…`) and custom or gateway ids are _unrecognised_, so they default to adaptive. If they front an older model (Haiku 4.5, 4.6 or earlier) set `thinkingMode: "budget"`. It can also move Opus/Sonnet 4.6 onto adaptive. The `AnthropicThinkingMode` type is exported.
 
 ```ts
-await agent.execute("Prove it.", { reasoning: { effort: "high" } });   // budget_tokens: 12000
-await model.complete(messages, { reasoning: { maxTokens: 8000 } });     // budget_tokens: 8000
+import { AnthropicSDK, type AnthropicThinkingMode } from "@warlock.js/ai-anthropic";
+
+const anthropic = new AnthropicSDK({ apiKey: process.env.ANTHROPIC_API_KEY! });
+
+const mode: AnthropicThinkingMode = "budget";
+
+anthropic.model({ name: "claude-opus-5-5" }); // adaptive (detected)
+anthropic.model({ name: "claude-haiku-4-5" }); // budget (detected)
+anthropic.model({ name: "us.anthropic.claude-haiku-4-5", thinkingMode: mode }); // region-prefixed id of an older model
+anthropic.model({ name: "claude-sonnet-4-6", thinkingMode: "adaptive" }); // opt 4.6 into adaptive
+```
+
+### Temperature
+
+`temperature` is **not sent** to models after Opus 4.6 (adaptive mode) — they reject any non-default value with a 400. It is also dropped on any request that enables thinking, since Anthropic 400s on thinking plus an explicit temperature. So it is forwarded only in budget mode on requests without thinking; `thinkingMode` decides this too. Set `reasoning: false` on the model config to suppress the thinking param entirely for proxied/legacy targets.
+
+```ts
+await agent.execute("Prove it.", { reasoning: { effort: "high" } });
+// adaptive model: thinking { type: "adaptive" }, output_config.effort "high"
+// budget model:   thinking { type: "enabled", budget_tokens: 12000 }
+await model.complete(messages, { reasoning: { maxTokens: 8000 } });
+// adaptive model: effort "medium"; budget model: budget_tokens 8000
 ```
 
 When a thinking-enabled response also makes tool calls, its signed `thinking` and `redacted_thinking` blocks are retained in each call's `providerMetadata.anthropic.thinkingBlocks`. The adapter replays those opaque blocks automatically on the next assistant turn, preserving Anthropic's required signatures; application code should leave that metadata intact when persisting message history.
 
 ## Prompt caching (`cache_control`)
 
+Caching is opt-in: `model({ promptCaching: true })` sends request-level
+`cache_control: { type: "ephemeral" }` when a call has no explicit
+`options.cacheControl.breakpoints`. Anthropic then marks the last cacheable
+block itself, caching the longest reusable request prefix (including growing
+message history). A caller-supplied breakpoint remains authoritative, so its
+request has no top-level automatic marker.
+
+Set `promptCacheTtl: "1h"` on the model to apply a one-hour TTL to automatic
+caching and emitted explicit markers. Omit it (or use `"5m"`) for Anthropic's
+default five-minute TTL; the one-hour cache has a higher write cost.
+
 Two independent breakpoint sites, both reported back via `usage.cachedTokens` / `usage.cacheWriteTokens`:
 
-- **Tools** — set `model({ promptCaching: true })` to mark the *last* tool definition with `cache_control: ephemeral`. One breakpoint caches the whole tool prefix; off by default since a write costs ~1.25x and only pays off across multiple trips.
-- **System prompt** — a per-call `options.cacheControl.breakpoints >= 1` emits the system prompt as a `TextBlockParam` carrying `cache_control: ephemeral` (the longest stable prefix on a turn). Without the hint the system prompt stays a plain string (uncached), so a one-shot call never pays the write surcharge. No system prompt → no block.
+- **Tools** — set `model({ promptCaching: true })` to mark the _last_ tool definition with `cache_control: ephemeral`. One breakpoint caches the whole tool prefix; off by default since a write costs ~1.25x and only pays off across multiple trips.
+- **System prompt** — a per-call `options.cacheControl.breakpoints >= 1` emits the system prompt as a `TextBlockParam` carrying `cache_control: ephemeral` (the longest stable prefix on a turn). Without the hint the system prompt stays a plain string with no marker of its own, but with `promptCaching: true` the automatic request-level marker still caches the longest reusable prefix, system prompt included (a live check read back 10,090 cached tokens of a large system prompt on the second call). With `promptCaching` off and no hint, nothing is cached, so a one-shot call never pays the write surcharge. A system prompt with per-turn placeholders changes the prefix each turn: write surcharge, no reads. No system prompt → no block.
 
 ```ts
-await agent.execute("…", { cacheControl: { breakpoints: 1 } });  // cache the system prefix
+await agent.execute("…", { cacheControl: { breakpoints: 1 } }); // cache the system prefix
 ```
 
 ## Multipart messages (vision)
@@ -169,7 +210,7 @@ Raw SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy.
 ## Token counting
 
 ```ts
-await anthropic.count("some text")  // approximate heuristic, offline
+await anthropic.count("some text"); // approximate heuristic, offline
 ```
 
 ## No embeddings

package/llms.txt

@@ -6,4 +6,4 @@
 
 ## Skills
 
-- [setup-anthropic](@warlock.js/ai-anthropic/setup-anthropic/SKILL.md): Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → thinking budget_tokens, prompt caching via promptCaching + options.cacheControl, cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Triggers: `AnthropicSDK`, `anthropic.model`, `anthropic.count`, `maxTokens`, `reasoning`, `thinking`, `budget_tokens`, `cacheControl`, `promptCaching`, `cachedTokens`, `cacheWriteTokens`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`; "wire claude into warlock agent", "configure anthropic provider", "use claude sonnet", "anthropic gateway baseURL", "claude extended thinking", "anthropic prompt caching cost"; typical import `import { AnthropicSDK } from "@warlock.js/ai-anthropic"`. Skip: embeddings — `@warlock.js/ai-openai/setup-openai/SKILL.md`; sibling adapters `@warlock.js/ai-openai`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `@anthropic-ai/sdk`; Vercel `@ai-sdk/anthropic`.
+- [setup-anthropic](@warlock.js/ai-anthropic/setup-anthropic/SKILL.md): Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, thinkingMode?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → adaptive thinking + output_config.effort (current/unknown models) or budget_tokens (Haiku 4.5, 4.6 and older; override with thinkingMode), prompt caching via promptCaching + options.cacheControl, cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Triggers: `AnthropicSDK`, `anthropic.model`, `anthropic.count`, `maxTokens`, `reasoning`, `thinking`, `budget_tokens`, `thinkingMode`, `adaptive`, `cacheControl`, `promptCaching`, `cachedTokens`, `cacheWriteTokens`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`; "wire claude into warlock agent", "configure anthropic provider", "use claude sonnet", "anthropic gateway baseURL", "claude extended thinking", "anthropic prompt caching cost"; typical import `import { AnthropicSDK } from "@warlock.js/ai-anthropic"`. Skip: embeddings — `@warlock.js/ai-openai/setup-openai/SKILL.md`; sibling adapters `@warlock.js/ai-openai`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `@anthropic-ai/sdk`; Vercel `@ai-sdk/anthropic`.

package/package.json

@@ -14,13 +14,13 @@
     "url": "https://github.com/warlockjs/ai-anthropic"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.25.0"
+    "@warlock.js/ai": "5.26.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.96.0",
-    "@warlock.js/logger": "5.25.0"
+    "@anthropic-ai/sdk": "^0.129.0",
+    "@warlock.js/logger": "5.26.0"
   },
-  "version": "5.25.0",
+  "version": "5.26.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/README.md

@@ -6,4 +6,4 @@ Per-task skills. All cross-references use the form `@warlock.js/<pkg>/<skill>/SK
 
 ### [`setup-anthropic/`](./setup-anthropic/SKILL.md)
 
-Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → thinking budget_tokens, prompt caching via promptCaching + options.cacheControl with cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Load when wiring a Claude-backed model into a @warlock.js agent.
+Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, thinkingMode?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → adaptive thinking + output_config.effort (current/unknown models) or budget_tokens (Haiku 4.5, 4.6 and older; override with thinkingMode), prompt caching via promptCaching + options.cacheControl with cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Load when wiring a Claude-backed model into a @warlock.js agent.

package/skills/setup-anthropic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-anthropic
-description: 'Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → thinking budget_tokens, prompt caching via promptCaching + options.cacheControl, cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Triggers: `AnthropicSDK`, `anthropic.model`, `anthropic.count`, `maxTokens`, `reasoning`, `thinking`, `budget_tokens`, `cacheControl`, `promptCaching`, `cachedTokens`, `cacheWriteTokens`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`; "wire claude into warlock agent", "configure anthropic provider", "use claude sonnet", "anthropic gateway baseURL", "claude extended thinking", "anthropic prompt caching cost"; typical import `import { AnthropicSDK } from "@warlock.js/ai-anthropic"`. Skip: embeddings — `@warlock.js/ai-openai/setup-openai/SKILL.md`; sibling adapters `@warlock.js/ai-openai`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `@anthropic-ai/sdk`; Vercel `@ai-sdk/anthropic`.'
+description: 'Wire @warlock.js/ai-anthropic — new AnthropicSDK({apiKey, baseURL?, provider?}) for Claude, .model({name, vision?, structuredOutput?, reasoning?, thinkingMode?, promptCaching?, maxTokens?}). System-prompt hoisting, max_tokens required (default 4096), extended thinking via options.reasoning → adaptive thinking + output_config.effort (current/unknown models) or budget_tokens (Haiku 4.5, 4.6 and older; override with thinkingMode), prompt caching via promptCaching + options.cacheControl, cost-truth usage (cachedTokens/cacheWriteTokens), no first-party embeddings. Triggers: `AnthropicSDK`, `anthropic.model`, `anthropic.count`, `maxTokens`, `reasoning`, `thinking`, `budget_tokens`, `thinkingMode`, `adaptive`, `cacheControl`, `promptCaching`, `cachedTokens`, `cacheWriteTokens`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`; "wire claude into warlock agent", "configure anthropic provider", "use claude sonnet", "anthropic gateway baseURL", "claude extended thinking", "anthropic prompt caching cost"; typical import `import { AnthropicSDK } from "@warlock.js/ai-anthropic"`. Skip: embeddings — `@warlock.js/ai-openai/setup-openai/SKILL.md`; sibling adapters `@warlock.js/ai-openai`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `@anthropic-ai/sdk`; Vercel `@ai-sdk/anthropic`.'
 ---
 
 # `@warlock.js/ai-anthropic`
@@ -27,23 +27,23 @@ const proxied = new AnthropicSDK({
 ## Producing a model
 
 ```ts
-anthropic.model({ name: "claude-sonnet-4-6" })                  // common case
-anthropic.model({ name: "claude-haiku-4-5", temperature: 0.2 }) // sampling controls
-anthropic.model({ name: "claude-opus-4-7", maxTokens: 8192 })   // raise the cap
+anthropic.model({ name: "claude-sonnet-4-6" }); // common case
+anthropic.model({ name: "claude-haiku-4-5", temperature: 0.2 }); // sampling controls
+anthropic.model({ name: "claude-opus-4-7", maxTokens: 8192 }); // raise the cap
 ```
 
 ## Capabilities — what's auto-set
 
-| Flag | Default |
-| --- | --- |
-| `structuredOutput` | `true` (via Anthropic's native `output_config.format`) |
-| `vision` | Inferred from model name. `true` for Claude 3 / 3.5 / 3.7 / 4 family; `false` for pre-3 and unknown. |
-| `reasoning` | `true` — every modern Claude model accepts extended thinking. Override with `reasoning: false` for legacy/proxied targets that reject the `thinking` param. |
-| `promptCaching` | `true` — the adapter places `cache_control` breakpoints and reports both cache reads (`Usage.cachedTokens`) and writes (`Usage.cacheWriteTokens`). |
-| `pdf` | `true` — the Messages API accepts PDF/document content blocks on vision-capable models. |
-| `audio` | absent (`false`) — Anthropic has no audio-input block, so the agent rejects audio attachments upfront. |
+| Flag               | Default                                                                                                                                                                                                  |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `structuredOutput` | `true` (via Anthropic's native `output_config.format`)                                                                                                                                                   |
+| `vision`           | Inferred from model name. `true` for Claude 3 / 3.5 / 3.7 / 4 and Claude 5-series (`claude-opus-5*`, `claude-sonnet-5*`, `claude-fable-5*`, `claude-mythos-5*`); `false` for pre-3 and unknown ids.      |
+| `reasoning`        | `true` — forwarded in the shape the model accepts (see [Extended thinking](#extended-thinking-reasoning)). Override with `reasoning: false` for legacy/proxied targets that reject the `thinking` param. |
+| `promptCaching`    | `true` — the adapter places `cache_control` breakpoints and reports both cache reads (`Usage.cachedTokens`) and writes (`Usage.cacheWriteTokens`).                                                       |
+| `pdf`              | `true` — the Messages API accepts PDF/document content blocks on vision-capable models.                                                                                                                  |
+| `audio`            | absent (`false`) — Anthropic has no audio-input block, so the agent rejects audio attachments upfront.                                                                                                   |
 
-Explicit config always wins (`structuredOutput`, `vision`, `reasoning`).
+Explicit config always wins (`structuredOutput`, `vision`, `reasoning`, `thinkingMode`).
 
 ## Pricing & cost
 
@@ -54,7 +54,7 @@ Pricing is opt-in. Supply USD-per-million-token rates and every report this SDK'
 const anthropic = new AnthropicSDK({
   apiKey,
   pricing: {
-    "claude-haiku-4-5":  { input: 1, output: 5,  cachedInput: 0.1 },
+    "claude-haiku-4-5": { input: 1, output: 5, cachedInput: 0.1 },
     "claude-sonnet-4-6": { input: 3, output: 15, cachedInput: 0.3 },
   },
 });
@@ -69,11 +69,11 @@ Resolution at `model()` time: per-model `pricing` > SDK registry entry for that
 
 Every `ModelResponse.usage` (and the streaming terminal `done`) is normalized to the neutral `Usage` shape. Anthropic reports `input_tokens` / `output_tokens` separately with no pre-summed total, so `total` is computed (`input + output`). The two cache channels are surfaced only when non-zero:
 
-| Neutral field | Anthropic source | Meaning / billing |
-| --- | --- | --- |
-| `usage.cachedTokens` | `cache_read_input_tokens` | Subset of input served from the prompt cache. Bills at `cachedInput` (falls back to `input` when unset). |
-| `usage.cacheWriteTokens` | `cache_creation_input_tokens` | Input tokens **written** to the cache on this call (the ~1.25x write surcharge). Bills at `cachedOutput` when set. |
-| `usage.reasoningTokens` | — *(not reported separately)* | Anthropic bills extended-thinking tokens **inside** `output_tokens`, so this stays unset — populating it would double-count against `output`. |
+| Neutral field            | Anthropic source              | Meaning / billing                                                                                                                             |
+| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `usage.cachedTokens`     | `cache_read_input_tokens`     | Subset of input served from the prompt cache. Bills at `cachedInput` (falls back to `input` when unset).                                      |
+| `usage.cacheWriteTokens` | `cache_creation_input_tokens` | Input tokens **written** to the cache on this call (the ~1.25x write surcharge). Bills at `cachedOutput` when set.                            |
+| `usage.reasoningTokens`  | — _(not reported separately)_ | Anthropic bills extended-thinking tokens **inside** `output_tokens`, so this stays unset — populating it would double-count against `output`. |
 
 In streaming, `cachedTokens` / `cacheWriteTokens` are seeded from `message_start` and then **overwritten by the cumulative counts on `message_delta`** when those are present and non-zero, so the terminal `done` carries the final tally.
 
@@ -81,7 +81,9 @@ In streaming, `cachedTokens` / `cacheWriteTokens` are seeded from `message_start
 
 Unlike OpenAI, Anthropic **requires** `max_tokens` on every request. Resolution: per-call `options.maxTokens` > `config.maxTokens` > **default `4096`**. A caller who never sets a cap still gets a complete answer instead of a 400.
 
-With extended thinking enabled and no explicit cap, the adapter reserves answer room: `max_tokens = thinking budget + 4096`. An explicit `maxTokens` must be greater than the thinking budget or the call throws before it reaches Anthropic.
+With extended thinking enabled and no explicit cap, the adapter reserves answer room in both modes: `max_tokens = thinking budget + 4096`. In budget mode an explicit `maxTokens` must be greater than `budget_tokens` or the call throws before it reaches Anthropic.
+
+**Tiny caps + adaptive thinking:** thinking tokens count inside `max_tokens`, so a very small cap can be spent entirely on thinking. Live check: Sonnet 5.5 with `maxTokens: 60` returned `finishReason: "length"` and empty content. For tiny outputs give thinking room (raise `maxTokens`) or turn reasoning off (`reasoning: false` on the model, or no `options.reasoning`).
 
 ## System prompt
 
@@ -100,31 +102,70 @@ When the agent passes `responseSchema` and the model is `structuredOutput`-capab
 
 ## Extended thinking (reasoning)
 
-When the model is `reasoning`-capable (default `true`) and the agent passes `options.reasoning`, the adapter forwards Anthropic extended thinking as `thinking: { type: "enabled", budget_tokens }`:
+When the model is `reasoning`-capable (default `true`) and the agent passes `options.reasoning`, the adapter forwards Anthropic thinking in one of two shapes, chosen per model (`thinkingMode`):
+
+| Mode         | Models (inferred from the name)                                                                                                 | Wire shape                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `"adaptive"` | Current Claude models — Opus 4.7 / 4.8 / 5 / 5.5, Sonnet 5 / 5.5, Fable 5 / 5.1 — **and any id the adapter does not recognise** | `thinking: { type: "adaptive" }` + `output_config.effort` |
+| `"budget"`   | Haiku 4.5, Opus 4.6, Sonnet 4.6, and every older model (Claude 3.x, 4.0 / 4.1 / 4.5, 2, instant)                                | `thinking: { type: "enabled", budget_tokens }`            |
+
+Adaptive models reject `budget_tokens` with a 400, so the shape matters.
+
+- **Adaptive:** `reasoning.effort` (`"low" | "medium" | "high"`) → `output_config.effort` of the same name. With only `reasoning.maxTokens` set, effort is `"medium"`; `maxTokens` then only sizes the reserved `max_tokens` room, it is not sent as a budget.
+- **Budget:** `reasoning.maxTokens` → `budget_tokens` verbatim; `reasoning.effort` → a tiered budget (`1024` / `4096` / `12000`) when no `maxTokens` is given. Any resolved budget is floored at Anthropic's `1024` minimum.
+- `reasoning` with neither `effort` nor `maxTokens`, or `effort: "none"`, emits nothing.
 
-- `reasoning.maxTokens` → `budget_tokens` verbatim.
-- `reasoning.effort` (`"low" | "medium" | "high"`) → a tiered budget (`1024` / `4096` / `12000`) when no explicit `maxTokens` is given.
-- Any resolved budget is floored at Anthropic's `1024`-token minimum.
-- `reasoning` with neither `effort` nor `maxTokens` emits nothing.
+### `thinkingMode` override
 
-Because Anthropic 400s when `thinking` is combined with an explicit `temperature`, the adapter **drops `temperature`** for that request (thinking pins sampling to the default). Set `reasoning: false` on the model config to suppress the param entirely for proxied/legacy targets.
+`anthropic.model({ name, thinkingMode: "adaptive" | "budget" })` beats the name-based detection. Use it when the id does not look like an Anthropic id: region-prefixed / Bedrock-style ids (`us.anthropic.claude-…`) and custom or gateway ids are _unrecognised_, so they default to adaptive. If they front an older model (Haiku 4.5, 4.6 or earlier) set `thinkingMode: "budget"`. It can also move Opus/Sonnet 4.6 onto adaptive. The `AnthropicThinkingMode` type is exported.
 
 ```ts
-await agent.execute("Prove it.", { reasoning: { effort: "high" } });   // budget_tokens: 12000
-await model.complete(messages, { reasoning: { maxTokens: 8000 } });     // budget_tokens: 8000
+import { AnthropicSDK, type AnthropicThinkingMode } from "@warlock.js/ai-anthropic";
+
+const anthropic = new AnthropicSDK({ apiKey: process.env.ANTHROPIC_API_KEY! });
+
+const mode: AnthropicThinkingMode = "budget";
+
+anthropic.model({ name: "claude-opus-5-5" }); // adaptive (detected)
+anthropic.model({ name: "claude-haiku-4-5" }); // budget (detected)
+anthropic.model({ name: "us.anthropic.claude-haiku-4-5", thinkingMode: mode }); // region-prefixed id of an older model
+anthropic.model({ name: "claude-sonnet-4-6", thinkingMode: "adaptive" }); // opt 4.6 into adaptive
+```
+
+### Temperature
+
+`temperature` is **not sent** to models after Opus 4.6 (adaptive mode) — they reject any non-default value with a 400. It is also dropped on any request that enables thinking, since Anthropic 400s on thinking plus an explicit temperature. So it is forwarded only in budget mode on requests without thinking; `thinkingMode` decides this too. Set `reasoning: false` on the model config to suppress the thinking param entirely for proxied/legacy targets.
+
+```ts
+await agent.execute("Prove it.", { reasoning: { effort: "high" } });
+// adaptive model: thinking { type: "adaptive" }, output_config.effort "high"
+// budget model:   thinking { type: "enabled", budget_tokens: 12000 }
+await model.complete(messages, { reasoning: { maxTokens: 8000 } });
+// adaptive model: effort "medium"; budget model: budget_tokens 8000
 ```
 
 When a thinking-enabled response also makes tool calls, its signed `thinking` and `redacted_thinking` blocks are retained in each call's `providerMetadata.anthropic.thinkingBlocks`. The adapter replays those opaque blocks automatically on the next assistant turn, preserving Anthropic's required signatures; application code should leave that metadata intact when persisting message history.
 
 ## Prompt caching (`cache_control`)
 
+Caching is opt-in: `model({ promptCaching: true })` sends request-level
+`cache_control: { type: "ephemeral" }` when a call has no explicit
+`options.cacheControl.breakpoints`. Anthropic then marks the last cacheable
+block itself, caching the longest reusable request prefix (including growing
+message history). A caller-supplied breakpoint remains authoritative, so its
+request has no top-level automatic marker.
+
+Set `promptCacheTtl: "1h"` on the model to apply a one-hour TTL to automatic
+caching and emitted explicit markers. Omit it (or use `"5m"`) for Anthropic's
+default five-minute TTL; the one-hour cache has a higher write cost.
+
 Two independent breakpoint sites, both reported back via `usage.cachedTokens` / `usage.cacheWriteTokens`:
 
-- **Tools** — set `model({ promptCaching: true })` to mark the *last* tool definition with `cache_control: ephemeral`. One breakpoint caches the whole tool prefix; off by default since a write costs ~1.25x and only pays off across multiple trips.
-- **System prompt** — a per-call `options.cacheControl.breakpoints >= 1` emits the system prompt as a `TextBlockParam` carrying `cache_control: ephemeral` (the longest stable prefix on a turn). Without the hint the system prompt stays a plain string (uncached), so a one-shot call never pays the write surcharge. No system prompt → no block.
+- **Tools** — set `model({ promptCaching: true })` to mark the _last_ tool definition with `cache_control: ephemeral`. One breakpoint caches the whole tool prefix; off by default since a write costs ~1.25x and only pays off across multiple trips.
+- **System prompt** — a per-call `options.cacheControl.breakpoints >= 1` emits the system prompt as a `TextBlockParam` carrying `cache_control: ephemeral` (the longest stable prefix on a turn). Without the hint the system prompt stays a plain string with no marker of its own, but with `promptCaching: true` the automatic request-level marker still caches the longest reusable prefix, system prompt included (a live check read back 10,090 cached tokens of a large system prompt on the second call). With `promptCaching` off and no hint, nothing is cached, so a one-shot call never pays the write surcharge. A system prompt with per-turn placeholders changes the prefix each turn: write surcharge, no reads. No system prompt → no block.
 
 ```ts
-await agent.execute("…", { cacheControl: { breakpoints: 1 } });  // cache the system prefix
+await agent.execute("…", { cacheControl: { breakpoints: 1 } }); // cache the system prefix
 ```
 
 ## Multipart messages (vision)
@@ -161,7 +202,7 @@ Raw SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy.
 ## Token counting
 
 ```ts
-await anthropic.count("some text")  // approximate heuristic, offline
+await anthropic.count("some text"); // approximate heuristic, offline
 ```
 
 ## No embeddings