anymous 1.3.0 → 1.3.2

package/skills/claude-api/shared/models.md

@@ -1,138 +0,0 @@
-# Claude Model Catalog
-
-**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`, or query the Models API directly (see Programmatic Model Discovery below).
-
-## Programmatic Model Discovery
-
-For **live** capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime.
-
-```python
-m = client.models.retrieve("claude-opus-4-8")
-m.id                 # "claude-opus-4-8"
-m.display_name       # "Claude Opus 4.8"
-m.max_input_tokens   # context window (int)
-m.max_tokens         # max output tokens (int)
-
-# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf
-caps = m.capabilities
-caps["image_input"]["supported"]                       # vision
-caps["thinking"]["types"]["adaptive"]["supported"]     # adaptive thinking
-caps["effort"]["max"]["supported"]                     # effort: max (also low/medium/high)
-caps["structured_outputs"]["supported"]
-caps["context_management"]["compact_20260112"]["supported"]
-
-# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data
-[m for m in client.models.list()
- if m.capabilities["thinking"]["types"]["adaptive"]["supported"]
- and m.max_input_tokens >= 200_000]
-```
-
-Top-level fields (`id`, `display_name`, `max_input_tokens`, `max_tokens`) are typed attributes. `capabilities` is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with `supported: true/false` at each leaf, so bracket chains are safe without `.get()` guards. TypeScript SDK: same method names, also auto-paginates on iteration.
-
-### Raw HTTP
-
-```bash
-curl https://api.anthropic.com/v1/models/claude-opus-4-8 \
-  -H "x-api-key: $ANTHROPIC_API_KEY" \
-  -H "anthropic-version: 2023-06-01"
-```
-
-```json
-{
-  "id": "claude-opus-4-8",
-  "display_name": "Claude Opus 4.8",
-  "max_input_tokens": 1000000,
-  "max_tokens": 128000,
-  "capabilities": {
-    "image_input": {"supported": true},
-    "structured_outputs": {"supported": true},
-    "thinking": {"supported": true, "types": {"enabled": {"supported": false}, "adaptive": {"supported": true}}},
-    "effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}},
-    …
-  }
-}
-```
-
-## Current Models (recommended)
-
-| Friendly Name     | Alias (use this)    | Full ID                       | Context        | Max Output | Status |
-|-------------------|---------------------|-------------------------------|----------------|------------|--------|
-| Claude Fable 5    | `claude-fable-5`      | —                             | 1M             | 128K       | Active |
-| Claude Mythos 5   | `claude-mythos-5`     | —                             | 1M             | 128K       | Active (Project Glasswing only) |
-| Claude Opus 5     | `claude-opus-5`       | —                             | 1M             | 128K       | Active |
-| Claude Opus 4.8   | `claude-opus-4-8`   | —                             | 1M             | 128K       | Active |
-| Claude Opus 4.7   | `claude-opus-4-7`   | —                             | 1M             | 128K       | Active |
-| Claude Opus 4.6   | `claude-opus-4-6`   | —                             | 1M             | 128K       | Active |
-| Claude Sonnet 5 | `claude-sonnet-5` | —                         | 1M             | 128K       | Active |
-| Claude Sonnet 4.6 | `claude-sonnet-4-6` | -                             | 1M             | 128K       | Active |
-| Claude Haiku 4.5  | `claude-haiku-4-5`  | `claude-haiku-4-5-20251001`   | 200K           | 64K        | Active |
-
-### Model Descriptions
-- **Claude Fable 5** — Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Same API surface as Opus 4.7/4.8 with one new breaking change: an explicit `thinking: {type: "disabled"}` returns a 400 — omit the `thinking` parameter instead (thinking is always on; the raw chain of thought is never returned — summaries via `display: "summarized"`). Same tokenizer as Opus 4.8 (token counts roughly unchanged vs Opus 4.7/4.8). Safety classifiers may return `stop_reason: "refusal"`. No assistant prefill. Requires 30-day data retention (not available under ZDR). $10/$50 per MTok; 1M context window (default), 128K max output. See `shared/model-migration.md` → Migrating to Claude Fable 5.
-- **Claude Mythos 5** — Same capabilities, pricing, limits, and API behavior as Claude Fable 5; only the model ID differs. Available exclusively through Project Glasswing, where it joins (and succeeds) the invitation-only Claude Mythos Preview (`claude-mythos-preview`). Use it only when the org participates in Project Glasswing; otherwise use claude-fable-5.
-- **Claude Opus 5** — For complex agentic coding and enterprise work; a step-change over Claude Opus 4.8, strongest on deep reasoning, agentic and long-horizon work, and test-time compute scaling, at half the cost of Claude Fable 5 (Claude Fable 5 remains the highest-capability tier). Safety classifiers can return `stop_reason: "refusal"` — handle it before reading `content`. A drop-in upgrade at Opus 4.8's pricing ($5/$25 per MTok) with the same feature set. Thinking is on by default (omitting `thinking` runs adaptive; `{type: "adaptive"}` is equivalent), and `thinking: {type: "disabled"}` is available only at effort `high` or lower — pairing it with `xhigh`/`max` returns a 400. Raw thinking tokens are never returned. Full effort ladder through `max`; 512-token prompt-cache minimum (down from 1024 on Opus 4.8); fast mode on the Claude API only. Elevated cybersecurity safeguards. Separate rate-limit bucket from the combined Opus 4.x pool. 1M context window (default and maximum), 128K max output. See `shared/model-migration.md` → Migrating to Claude Opus 5.
-- **Claude Opus 4.8** — The most capable model in the Opus 4 series — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and `budget_tokens` removed). 1M context window at standard API pricing (no long-context premium). See `shared/model-migration.md` → Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes.
-- **Claude Opus 4.7** — Previous-generation Opus. Highly autonomous; strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and `budget_tokens` removed. 1M context window. See `shared/model-migration.md` → Migrating to Opus 4.7.
-- **Claude Opus 4.6** — Older Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window.
-- **Claude Sonnet 5** — The best combination of speed and intelligence in the Sonnet tier; near-Opus quality on coding and agentic work. Adaptive thinking on by default (omitting `thinking` runs adaptive); manual `budget_tokens` removed; non-default sampling parameters rejected. `effort` supports `low`/`medium`/`high`/`xhigh`/`max`. New tokenizer (~30% more tokens for the same text vs Sonnet 4.6). High-resolution vision (2576px). 1M context window, 128K max output. See `shared/model-migration.md` → Migrating to Claude Sonnet 5.
-- **Claude Sonnet 4.6** — Previous-generation Sonnet. Supports adaptive thinking (recommended). 1M context window. 128K max output tokens.
-- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks.
-
-## Legacy Models (still active)
-
-| Friendly Name     | Alias (use this)    | Full ID                       | Status |
-|-------------------|---------------------|-------------------------------|--------|
-| Claude Opus 4.5   | `claude-opus-4-5`   | `claude-opus-4-5-20251101`    | Active |
-| Claude Opus 4.1   | `claude-opus-4-1`   | `claude-opus-4-1-20250805`    | Deprecated (retires 2026-08-05 — migrate to `claude-opus-5`) |
-| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929`  | Active |
-
-## Deprecated Models (retiring soon)
-
-| Friendly Name     | Alias (use this)    | Full ID                       | Status     | Retires      |
-|-------------------|---------------------|-------------------------------|------------|--------------|
-| Claude Sonnet 4   | `claude-sonnet-4-0` | `claude-sonnet-4-20250514`    | Deprecated | TBD          |
-| Claude Opus 4     | `claude-opus-4-0`   | `claude-opus-4-20250514`      | Deprecated | TBD          |
-| Claude Haiku 3    | —                   | `claude-3-haiku-20240307`     | Deprecated | Apr 19, 2026 |
-
-## Retired Models (no longer available)
-
-| Friendly Name     | Full ID                       | Retired     |
-|-------------------|-------------------------------|-------------|
-| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219`  | Feb 19, 2026 |
-| Claude Haiku 3.5  | `claude-3-5-haiku-20241022`   | Feb 19, 2026 |
-| Claude Opus 3     | `claude-3-opus-20240229`      | Jan 5, 2026 |
-| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022`  | Oct 28, 2025 |
-| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620`  | Oct 28, 2025 |
-| Claude Sonnet 3   | `claude-3-sonnet-20240229`    | Jul 21, 2025 |
-| Claude 2.1        | `claude-2.1`                  | Jul 21, 2025 |
-| Claude 2.0        | `claude-2.0`                  | Jul 21, 2025 |
-
-## Resolving User Requests
-
-When a user asks for a model by name, use this table to find the correct model ID:
-
-| User says...                              | Use this model ID              |
-|-------------------------------------------|--------------------------------|
-| "fable", "most capable model"             | `claude-fable-5`                 |
-| "most powerful"                           | `claude-fable-5`                 |
-| "mythos", "mythos 5"                      | `claude-mythos-5` (Project Glasswing participants only; otherwise use `claude-fable-5`) |
-| "mythos preview"                          | `claude-mythos-5` (successor to `claude-mythos-preview` — see migration guide) |
-| "opus"                                    | `claude-opus-5`                   |
-| "opus 5"                                  | `claude-opus-5`             |
-| "opus 4.8"                                | `claude-opus-4-8`              |
-| "opus 4.7"                                | `claude-opus-4-7`              |
-| "opus 4.6"                                | `claude-opus-4-6`              |
-| "opus 4.5"                                | `claude-opus-4-5`              |
-| "opus 4.1"                                | `claude-opus-4-1` (deprecated, retires 2026-08-05 — suggest `claude-opus-5`) |
-| "opus 4", "opus 4.0"                      | `claude-opus-4-0` (deprecated — suggest `claude-opus-5`) |
-| "sonnet", "balanced"                      | `claude-sonnet-5`           |
-| "sonnet 5"                                | `claude-sonnet-5`           |
-| "sonnet 4.6"                              | `claude-sonnet-4-6`            |
-| "sonnet 4.5"                              | `claude-sonnet-4-5`            |
-| "sonnet 4", "sonnet 4.0"                  | `claude-sonnet-4-0` (deprecated — suggest `claude-sonnet-5`) |
-| "sonnet 3.7"                              | Retired — suggest `claude-sonnet-5` |
-| "sonnet 3.5"                              | Retired — suggest `claude-sonnet-5` |
-| "haiku", "fast", "cheap"                  | `claude-haiku-4-5`             |
-| "haiku 4.5"                               | `claude-haiku-4-5`             |
-| "haiku 3.5"                               | Retired — suggest `claude-haiku-4-5` |
-| "haiku 3"                                 | Deprecated — suggest `claude-haiku-4-5` |

package/skills/claude-api/shared/platform-availability.md

@@ -1,97 +0,0 @@
-# Platform Availability
-
-Which features work on which provider platform. **This table is the single source of truth in this skill** — per-feature sections elsewhere point here instead of restating availability. When writing code for a third-party platform (Bedrock, Vertex, Foundry) or Claude Platform on AWS, check this table first; a feature not supported there means use the first-party Claude API surface or a different approach.
-
-Columns: **1P** = first-party Claude API, **P-AWS** = Claude Platform on AWS (Anthropic-operated, same-day parity), **Bedrock** = Amazon Bedrock, **Vertex** = Google Cloud Vertex AI, **Foundry** = Microsoft Foundry. ✅ = GA, β = beta, ❌ = not supported.
-
-| Feature | 1P | P-AWS | Bedrock | Vertex | Foundry | Notes |
-|---|---|---|---|---|---|---|
-| Messages, streaming, tool use | ✅ | ✅ | ✅ | ✅ | ✅ | Core API |
-| PDF input | ✅ | ✅ | ✅ | ✅ | β | |
-| Structured outputs / strict tool use | ✅ | ✅ | ✅ | ✅ | β | |
-| Adaptive thinking / effort | ✅ | ✅ | ✅ | ✅ | β | |
-| Extended thinking | ✅ | ✅ | ✅ | ✅ | β | |
-| Prompt caching (5m, 1h) | ✅ | ✅ | ✅ | ✅ | β | |
-| Automatic prompt caching | ✅ | ✅ | ❌ | ❌ | β | |
-| Token counting | ✅ | ✅ | ✅ | ✅ | β | |
-| Citations | ✅ | ✅ | ✅ | ✅ | β | |
-| Search results content blocks | ✅ | ✅ | ✅ | ✅ | β | |
-| Fine-grained tool streaming | ✅ | ✅ | ✅ | ✅ | ✅ | |
-| Compaction | β | β | β | β | β | |
-| Context editing | β | β | β | β | β | |
-| Context windows (1M) | ✅ | ✅ | ✅ | ✅ | β | |
-| `inference_geo` (data residency) | ✅ | ✅ | ❌ | ❌ | ❌ | |
-| **Server-side tools** | | | | | | |
-|   Web search | ✅ | ✅ | ❌ | ✅ | β | Vertex: basic `web_search_20250305` only (no `_20260209` dynamic filtering) |
-|   Web fetch | ✅ | ✅ | ❌ | ❌ | β | |
-|   Code execution | ✅ | ✅ | ❌ | ❌ | β | |
-|   Tool search | ✅ | ✅ | ✅ | ✅ | β | Bedrock: InvokeModel API only, not Converse |
-|   Advisor tool | β | β | ❌ | ❌ | ❌ | |
-| **Client-implemented tools** | | | | | | |
-|   Bash, text editor, memory | ✅ | ✅ | ✅ | ✅ | β | |
-|   Computer use | β | β | β | β | β | |
-| **Agentic / orchestration** | | | | | | |
-|   Agent Skills (Messages API) | β | β | ❌ | ❌ | β | |
-|   Programmatic tool calling | ✅ | ✅ | ❌ | ❌ | β | |
-|   MCP connector | β | β | ❌ | ❌ | β | |
-|   Managed Agents | β | β | ❌ | ❌ | ❌ | Foundry ❌ inferred (not in Foundry docs either way) |
-|   Self-hosted sandboxes | β | β | ❌ | ❌ | ❌ | P-AWS: `GET /v1/environments/{id}/work` list endpoint not supported; other work endpoints OK |
-| **API endpoints** | | | | | | |
-|   Message Batches | ✅ | ✅ | ❌ | ❌ | ❌ | |
-|   Files API | β | β | ❌ | ❌ | β | |
-|   Models API | ✅ | ✅ | ❌ | ❌ | ❌ | |
-| **Other** | | | | | | |
-|   Mid-conversation system messages | ✅ | ✅ | ❌ | ❌ | ❌ | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5; not Claude Sonnet 5 |
-|   Server-side `fallbacks` | β | β | ❌ | ❌ | ❌ | `"default"` → beta `server-side-fallback-2026-07-01`; array form → beta `server-side-fallback-2026-06-01` |
-|   Fast mode | β | ❌ | ❌ | ❌ | ❌ | Research preview, beta `fast-mode-2026-02-01`, first-party API only |
-|   Cache diagnostics | β | ❌ | ❌ | ❌ | ❌ | First-party API only |
-|   Task budgets | β | β | ❌ | ❌ | ❌ | Beta header `task-budgets-2026-03-13`; 3P availability not documented — assume unsupported |
-
-<!--
-GROUNDING (reviewer-only; stripped at runtime by processSkillMarkdown).
-All paths are under docker_eval/resources/cdp-skill/public-docs/.
-
-Primary source: build-with-claude/overview.mdx <PlatformAvailability> props
-(claudeApi→1P, claudePlatformAws→P-AWS, bedrock→Bedrock, vertexAi→Vertex,
-azureAi→Foundry; *Beta suffix→β; prop absent→❌). Per-row citations:
-
-  Context windows          ov:44
-  Adaptive thinking        ov:45
-  Batch / Message Batches  ov:46; bed:360; vtx:381; fdy:507
-  Citations                ov:47
-  inference_geo            ov:48
-  Effort                   ov:49
-  Extended thinking        ov:50
-  PDF input                ov:51
-  Search results           ov:52
-  Structured outputs       ov:53
-  Advisor tool             ov:63
-  Code execution           ov:64
-  Web fetch                ov:65
-  Web search               ov:66; agents-and-tools/tool-use/web-search-tool.mdx:41
-  Bash/text-editor/memory  ov:72,75,74
-  Computer use             ov:73
-  Agent Skills             ov:83
-  Fine-grained streaming   ov:84
-  MCP connector            ov:85; agents-and-tools/mcp-connector.mdx:36
-  Programmatic tool call   ov:86
-  Tool search              ov:87; agents-and-tools/tool-use/tool-search-tool.mdx:24-30
-  Compaction               ov:95
-  Context editing          ov:96
-  Automatic caching        ov:97
-  Prompt caching 5m/1h     ov:98,99
-  Token counting           ov:100
-  Files API                ov:108; build-with-claude/files.mdx:17
-  Managed Agents           managed-agents/overview.mdx:11,70-72; bed:360; vtx:381
-  Self-hosted sandboxes    build-with-claude/claude-platform-on-aws.mdx:525,547
-  Mid-convo system msgs    build-with-claude/mid-conversation-system-messages.mdx:15
-  Fast mode                build-with-claude/fast-mode.mdx:23
-  Cache diagnostics        build-with-claude/cache-diagnostics.mdx:15,1379
-  Task budgets             build-with-claude/task-budgets.mdx:15
-  Models API               bed:360; vtx:381; fdy:506
-
-  ov  = build-with-claude/overview.mdx
-  bed = build-with-claude/claude-in-amazon-bedrock.mdx
-  vtx = build-with-claude/claude-on-vertex-ai.mdx
-  fdy = build-with-claude/claude-in-microsoft-foundry.mdx
--->

package/skills/claude-api/shared/prompt-caching.md

@@ -1,235 +0,0 @@
-# Prompt Caching — Design & Optimization
-
-This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the `## Prompt Caching` section in each language's README or single-file doc.
-
-## The one invariant everything follows from
-
-**Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.**
-
-The cache key is derived from the exact bytes of the rendered prompt up to each `cache_control` breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N.
-
-Render order is: `tools` → `system` → `messages`. A breakpoint on the last system block caches both tools and system together.
-
-Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of `cache_control` markers will help.
-
----
-
-## Workflow for optimizing existing code
-
-When asked to add or optimize caching:
-
-1. **Trace the prompt assembly path.** Find where `system`, `tools`, and `messages` are constructed. Identify every input that flows into them.
-2. **Classify each input by stability:**
-   - Never changes → belongs early in the prompt, before any breakpoint
-   - Changes per-session → belongs after the global prefix, cache per-session
-   - Changes per-turn → belongs at the end, after the last breakpoint
-   - Changes per-request (timestamps, UUIDs, random IDs) → **eliminate or move to the very end**
-3. **Check rendered order matches stability order.** Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers.
-4. **Place breakpoints at stability boundaries.** See placement patterns below.
-5. **Audit for silent invalidators.** See anti-patterns table.
-
----
-
-## Placement patterns
-
-### Large system prompt shared across many requests
-
-Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together.
-
-```json
-"system": [
-  {"type": "text", "text": "<large shared prompt>", "cache_control": {"type": "ephemeral"}}
-]
-```
-
-### Multi-turn conversations
-
-Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows.
-
-```json
-// Last content block of the last user turn
-messages[-1].content[-1].cache_control = {"type": "ephemeral"}
-```
-
-### Shared prefix, varying suffix
-
-Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the **shared** portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read.
-
-```json
-"messages": [{"role": "user", "content": [
-  {"type": "text", "text": "<shared context>", "cache_control": {"type": "ephemeral"}},
-  {"type": "text", "text": "<varying question>"}  // no marker — differs every time
-]}]
-```
-
-### Mid-conversation system messages
-
-**Claude Opus 5, Claude Opus 4.8, Claude Fable 5, and Claude Mythos 5; no beta header. Not available on Claude Sonnet 5** — use top-level `system` there. (Sources conflict on Claude Sonnet 5: the model config marks it supported, but every canonical docs page omits it. Treat it as unsupported and catch the 400.) When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as `{"role": "system", "content": "..."}` appended to `messages[]`, rather than editing top-level `system`. Editing top-level `system` changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a `role: "system"` message sits after the history and leaves the cached prefix intact.
-
-```json
-// Top-level system stays byte-identical; new instruction goes after the cached history
-"system": [{"type": "text", "text": "<stable core>", "cache_control": {"type": "ephemeral"}}],
-"messages": [
-  ...history,
-  {"role": "user", "content": "..."},
-  {"role": "system", "content": "Terse mode enabled — keep responses under 40 words."}
-]
-```
-
-This is also the prompt-injection-safe replacement for embedding operator instructions as text inside a user turn (the `<system-reminder>` pattern): both have the same caching profile, but `role: "system"` is the non-spoofable operator channel, whereas text inside user/tool content can be forged by anything that writes to user-visible input.
-
-Must follow a `role: "user"` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]` — use top-level `system` for the initial prompt. Content is text-only. Unsupported models return a 400 (`BadRequestError`: `role 'system' is not supported on this model`); catch that error and fall back to putting the instruction in a user-turn `<system-reminder>` block.
-
-### Prompts that change from the beginning every time
-
-Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding `cache_control` only pays the cache-write premium with zero reads. Leave it off.
-
----
-
-## Architectural guidance
-
-These are the decisions that matter more than marker placement. Fix these first.
-
-**Keep the system prompt frozen.** Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context later in `messages` instead — as a `{"role": "system", ...}` message where supported (see § Mid-conversation system messages above), or as text in a user message otherwise. A message at turn 5 invalidates nothing before turn 5.
-
-**Don't change tools or model mid-conversation.** Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name).
-
-**Fork operations must reuse the parent's exact prefix.** Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds `system` / `tools` / `model` with any difference, it misses the parent's cache entirely. Copy the parent's `system`, `tools`, and `model` verbatim, then append fork-specific content at the end.
-
----
-
-## Silent invalidators
-
-When reviewing code, grep for these inside anything that feeds the prompt prefix:
-
-| Pattern | Why it breaks caching |
-|---|---|
-| `datetime.now()` / `Date.now()` / `time.time()` in system prompt | Prefix changes every request |
-| `uuid4()` / `crypto.randomUUID()` / request IDs early in content | Same — every request is unique |
-| `json.dumps(d)` without `sort_keys=True` / iterating a `set` | Non-deterministic serialization → prefix bytes differ |
-| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing |
-| Conditional system sections (`if flag: system += ...`) | Every flag combination is a distinct prefix |
-| `tools=build_tools(user)` where set varies per user | Tools render at position 0; nothing caches across users |
-
-Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing.
-
----
-
-## API reference
-
-```json
-"cache_control": {"type": "ephemeral"}              // 5-minute TTL (default)
-"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL
-```
-
-- Max **4** `cache_control` breakpoints per request.
-- Goes on any content block: system text blocks, tool definitions, message content blocks (`text`, `image`, `tool_use`, `tool_result`, `document`).
-- Top-level `cache_control` on `messages.create()` auto-places on the last cacheable block — simplest option when you don't need fine-grained placement.
-- Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just `cache_creation_input_tokens: 0`:
-
-| Model | Minimum |
-|---|---:|
-| Claude Opus 5, Claude Fable 5, Claude Mythos 5 | 512 tokens |
-| Opus 4.8, Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.1, Opus 4, Sonnet 4 | 1024 tokens |
-| Opus 4.7, Mythos Preview, Haiku 3.5 | 2048 tokens |
-| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
-
-**The minimum is not monotonic across generations** — 512 on the newest models, but 4096 on Opus 4.6/4.5 and Haiku 4.5. A 3K-token prompt caches on Claude Opus 5, Opus 4.8, and Sonnet 4.5, and silently won't on Opus 4.6 or Haiku 4.5. Claude Opus 5 halves the Opus 4.8 minimum (1024 → 512), so prompts previously too short to cache now create entries with no code change.
-
-These minimums apply on **every** platform where the model is available — the old Amazon Bedrock override for Claude Fable 5 was removed, and no per-platform exception remains.
-
-**Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off.
-
----
-
-## Verifying cache hits
-
-The response `usage` object reports cache activity:
-
-| Field | Meaning |
-|---|---|
-| `cache_creation_input_tokens` | Tokens written to cache this request (you paid the ~1.25× write premium) |
-| `cache_read_input_tokens` | Tokens served from cache this request (you paid ~0.1×) |
-| `input_tokens` | Tokens processed at full price (not cached) |
-
-If `cache_read_input_tokens` is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it.
-
-**`input_tokens` is the uncached remainder only.** Total prompt size = `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. If your agent ran for hours but `input_tokens` shows 4K, the rest was served from cache — check the sum, not the single field.
-
-Language-specific access: `response.usage.cache_read_input_tokens` (Python/TS/Ruby), `$message->usage->cacheReadInputTokens` (PHP), `resp.Usage.CacheReadInputTokens` (Go/C#), `.usage().cacheReadInputTokens()` (Java).
-
----
-
-## Invalidation hierarchy
-
-Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below:
-
-| Change | Tools cache | System cache | Messages cache |
-|---|:---:|:---:|:---:|
-| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ |
-| Model switch | ❌ | ❌ | ❌ |
-| `speed`, web-search, citations toggle | ✅ | ❌ | ❌ |
-| System prompt content | ✅ | ❌ | ❌ |
-| `tool_choice`, images, `thinking` enable/disable | ✅ | ✅ | ❌ |
-| Message content | ✅ | ✅ | ❌ |
-
-Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild.
-
-**Two of these rows have a cache-preserving escape hatch**, each by moving the change out of the top-level request and into a system message inside `messages[]`, after the cached prefix. **Availability differs per row** — the two are not gated together:
-
-| Top-level change that invalidates | Cache-preserving form | Available on |
-|---|---|---|
-| Tool definitions (add/remove) | `tool_addition` / `tool_removal` blocks — see `shared/tool-use-concepts.md` § Mid-conversation tool changes | Claude Opus 5 onward, behind `mid-conversation-tool-changes-2026-07-01` |
-| System prompt content | A `{"role": "system", "content": "…"}` message — see § Mid-conversation system messages above | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 — **already available today**, no beta header |
-
-Model switch has no escape hatch: caches are model-scoped. Keep the main loop on one model and spawn a subagent for cheaper sub-tasks (see `agent-design.md` § Caching for Agents).
-
----
-
-## 20-block lookback window
-
-Each breakpoint walks backward **at most 20 content blocks** to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses.
-
-Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block.
-
----
-
-## Concurrent-request timing
-
-A cache entry becomes readable only after the first response **begins streaming**. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing.
-
-For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote.
-
-## Pre-warming the cache
-
-To eliminate the cache-miss latency on the *first* real request, send a **`max_tokens: 0`** request at startup (or on an interval). The API runs prefill — writing the cache at your `cache_control` breakpoint — and returns immediately with `content: []`, `stop_reason: "max_tokens"`, and a populated `usage` block (zero output tokens billed; normal cache-write charge on `cache_creation_input_tokens`).
-
-**When to pre-warm** — pre-warming trades a cache-write charge *now* for lower TTFT on the *next* real request. It's worth it when all three hold: (a) first-request latency is user-visible (chat/voice/interactive — not background jobs), (b) the shared prefix is large enough that a cold write is noticeably slow, and (c) there's a moment *before* traffic to fire it — app startup, worker boot, post-deploy, start of a scheduled window.
-
-| Skip pre-warming when… | Because |
-|---|---|
-| Traffic is continuous (requests ≤ TTL apart) | The first real request warms the cache and every subsequent one hits it; a separate warm call is a pure extra write |
-| The prefix is small or below the cacheable minimum | The cold-write penalty is negligible |
-| The prefix varies per request/user | Nothing shared to pre-warm |
-| You'd pre-warm many distinct prefixes speculatively | Each is a ~1.25× write; cost can exceed the latency you save |
-
-**Scheduled re-warms:** only needed when traffic has gaps longer than the TTL. If real requests arrive more often than every 5 minutes, they keep the cache warm on their own — don't add an interval re-warm. For bursty traffic with long idle gaps, either re-warm just under the TTL or switch to `ttl: "1h"` and re-warm less often.
-
-```python
-client.messages.create(
-    model="claude-opus-5",
-    max_tokens=0,
-    system=[{
-        "type": "text",
-        "text": SYSTEM_PROMPT,
-        "cache_control": {"type": "ephemeral"},
-    }],
-    messages=[{"role": "user", "content": "warmup"}],
-)
-```
-
-**Breakpoint placement:** put `cache_control` on the **last block shared with the real request** (the system prompt or tool definitions) — **not** on the placeholder user message, and **not** via top-level automatic caching (which would key the cache to the placeholder). The placeholder can be any non-whitespace string; it's read during prefill but never answered.
-
-**Rejected combinations:** `max_tokens: 0` is an `invalid_request_error` with `stream: true`, `thinking.type: "enabled"`, `output_config.format`, `tool_choice` of `{"type":"tool"}` or `{"type":"any"}`, or inside a Message Batches request.
-
-**TTL still applies** — re-warm at least every 5 minutes for the default cache, or use the 1-hour TTL. This replaces the older `max_tokens: 1` workaround (no single-token reply to discard, no output tokens billed, intent is unambiguous).

package/skills/claude-api/shared/token-counting.md

@@ -1,56 +0,0 @@
-# Token Counting
-
-Use the `count_tokens` endpoint (`POST /v1/messages/count_tokens`) for accurate
-token counts against Claude models. Token counts are **model-specific** — pass
-the same model ID you'll use for inference.
-
-**Do not use `tiktoken`.** It's OpenAI's tokenizer. It undercounts Claude
-tokens by ~15–20% on typical text, and by much more on code or non-English
-input. Any estimate from `tiktoken`, `gpt-tokenizer`, or similar is wrong for
-Claude.
-
-## Count a file or string
-
-```python
-from anthropic import Anthropic
-
-client = Anthropic()
-resp = client.messages.count_tokens(
-    model="claude-opus-5",
-    messages=[{"role": "user", "content": open("CLAUDE.md").read()}],
-)
-print(resp.input_tokens)
-```
-
-TypeScript: `await client.messages.countTokens({model, messages})` →
-`.input_tokens`. See `{lang}/claude-api/README.md` for other SDKs.
-
-## CLI
-
-```sh
-ant messages count-tokens --model claude-opus-5 \
-  --message '{role: user, content: "@./CLAUDE.md"}' \
-  --transform input_tokens -r
-```
-
-## Diffing a file across two versions
-
-The endpoint is stateless — count each version separately and subtract:
-
-```python
-from anthropic import Anthropic
-import subprocess
-
-client = Anthropic()
-def count(text: str) -> int:
-    return client.messages.count_tokens(
-        model="claude-opus-5",
-        messages=[{"role": "user", "content": text}],
-    ).input_tokens
-
-before = subprocess.check_output(["git", "show", "HEAD:CLAUDE.md"], text=True)
-after = open("CLAUDE.md").read()
-print(count(after) - count(before))
-```
-
-Full docs: see the Token Counting entry in `shared/live-sources.md`.