claudecode-omc 5.1.0 → 5.3.0

package/bundled/upstream/anthropic-skills/skills/claude-api/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: claude-api
+description: "Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK. DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks."
+license: Complete terms in LICENSE.txt
+---
+
+# Building LLM-Powered Applications with Claude
+
+This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation.
+
+## Defaults
+
+Unless the user requests otherwise:
+
+For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string `claude-opus-4-6`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events
+
+---
+
+## Language Detection
+
+Before reading code examples, determine which language the user is working in:
+
+1. **Look at project files** to infer the language:
+
+   - `*.py`, `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → **Python** — read from `python/`
+   - `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` → **TypeScript** — read from `typescript/`
+   - `*.js`, `*.jsx` (no `.ts` files present) → **TypeScript** — JS uses the same SDK, read from `typescript/`
+   - `*.java`, `pom.xml`, `build.gradle` → **Java** — read from `java/`
+   - `*.kt`, `*.kts`, `build.gradle.kts` → **Java** — Kotlin uses the Java SDK, read from `java/`
+   - `*.scala`, `build.sbt` → **Java** — Scala uses the Java SDK, read from `java/`
+   - `*.go`, `go.mod` → **Go** — read from `go/`
+   - `*.rb`, `Gemfile` → **Ruby** — read from `ruby/`
+   - `*.cs`, `*.csproj` → **C#** — read from `csharp/`
+   - `*.php`, `composer.json` → **PHP** — read from `php/`
+
+2. **If multiple languages detected** (e.g., both Python and TypeScript files):
+
+   - Check which language the user's current file or question relates to
+   - If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?"
+
+3. **If language can't be inferred** (empty project, no source files, or unsupported language):
+
+   - Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP
+   - If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language."
+
+4. **If unsupported language detected** (Rust, Swift, C++, Elixir, etc.):
+
+   - Suggest cURL/raw HTTP examples from `curl/` and note that community SDKs may exist
+   - Offer to show Python or TypeScript examples as reference implementations
+
+5. **If user needs cURL/raw HTTP examples**, read from `curl/`.
+
+### Language-Specific Feature Support
+
+| Language   | Tool Runner | Agent SDK | Notes                                 |
+| ---------- | ----------- | --------- | ------------------------------------- |
+| Python     | Yes (beta)  | Yes       | Full support — `@beta_tool` decorator |
+| TypeScript | Yes (beta)  | Yes       | Full support — `betaZodTool` + Zod    |
+| Java       | Yes (beta)  | No        | Beta tool use with annotated classes  |
+| Go         | Yes (beta)  | No        | `BetaToolRunner` in `toolrunner` pkg  |
+| Ruby       | Yes (beta)  | No        | `BaseTool` + `tool_runner` in beta    |
+| cURL       | N/A         | N/A       | Raw HTTP, no SDK features             |
+| C#         | No          | No        | Official SDK                          |
+| PHP        | Yes (beta)  | No        | `BetaRunnableTool` + `toolRunner()`   |
+
+---
+
+## Which Surface Should I Use?
+
+> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration.
+
+| Use Case                                        | Tier            | Recommended Surface       | Why                                     |
+| ----------------------------------------------- | --------------- | ------------------------- | --------------------------------------- |
+| Classification, summarization, extraction, Q&A  | Single LLM call | **Claude API**            | One request, one response               |
+| Batch processing or embeddings                  | Single LLM call | **Claude API**            | Specialized endpoints                   |
+| Multi-step pipelines with code-controlled logic | Workflow        | **Claude API + tool use** | You orchestrate the loop                |
+| Custom agent with your own tools                | Agent           | **Claude API + tool use** | Maximum flexibility                     |
+| AI agent with file/web/terminal access          | Agent           | **Agent SDK**             | Built-in tools, safety, and MCP support |
+| Agentic coding assistant                        | Agent           | **Agent SDK**             | Designed for this use case              |
+| Want built-in permissions and guardrails        | Agent           | **Agent SDK**             | Safety features included                |
+
+> **Note:** The Agent SDK is for when you want built-in file/web/terminal tools, permissions, and MCP out of the box. If you want to build an agent with your own tools, Claude API is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution).
+
+### Decision Tree
+
+```
+What does your application need?
+
+1. Single LLM call (classification, summarization, extraction, Q&A)
+   └── Claude API — one request, one response
+
+2. Does Claude need to read/write files, browse the web, or run shell commands
+   as part of its work? (Not: does your app read a file and hand it to Claude —
+   does Claude itself need to discover and access files/web/shell?)
+   └── Yes → Agent SDK — built-in tools, don't reimplement them
+       Examples: "scan a codebase for bugs", "summarize every file in a directory",
+                 "find bugs using subagents", "research a topic via web search"
+
+3. Workflow (multi-step, code-orchestrated, with your own tools)
+   └── Claude API with tool use — you control the loop
+
+4. Open-ended agent (model decides its own trajectory, your own tools)
+   └── Claude API agentic loop (maximum flexibility)
+```
+
+### Should I Build an Agent?
+
+Before choosing the agent tier, check all four criteria:
+
+- **Complexity** — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF")
+- **Value** — Does the outcome justify higher cost and latency?
+- **Viability** — Is Claude capable at this task type?
+- **Cost of error** — Can errors be caught and recovered from? (tests, review, rollback)
+
+If the answer is "no" to any of these, stay at a simpler tier (single call or workflow).
+
+---
+
+## Architecture
+
+Everything goes through `POST /v1/messages`. Tools and output constraints are features of this single endpoint — not separate APIs.
+
+**User-defined tools** — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually.
+
+**Server-side tools** — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in `tools`, Claude runs code automatically). Computer use can be server-hosted or self-hosted.
+
+**Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`.
+
+**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting, and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests.
+
+---
+
+## Current Models (cached: 2026-02-17)
+
+| Model             | Model ID            | Context        | Input $/1M | Output $/1M |
+| ----------------- | ------------------- | -------------- | ---------- | ----------- |
+| Claude Opus 4.6   | `claude-opus-4-6`   | 200K (1M beta) | $5.00      | $25.00      |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00      | $15.00      |
+| Claude Haiku 4.5  | `claude-haiku-4-5`  | 200K           | $1.00      | $5.00       |
+
+**ALWAYS use `claude-opus-4-6` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours.
+
+**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-5`, never `claude-sonnet-4-5-20250514` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself.
+
+A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that.
+
+**Live capability lookup:** The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (`client.models.retrieve(id)` / `client.models.list()`) — see `shared/models.md` for the field reference and capability-filter examples.
+
+---
+
+## Thinking & Effort (Quick Reference)
+
+**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Opus 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` and do NOT switch to an older model.**
+
+**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Use `low` for subagents or simple tasks; `max` for the deepest reasoning.
+
+**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead.
+
+**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.6 with adaptive thinking instead.
+
+---
+
+## Compaction (Quick Reference)
+
+**Beta, Opus 4.6 and Sonnet 4.6.** For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`.
+
+**Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state.
+
+See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full docs via WebFetch in `shared/live-sources.md`.
+
+---
+
+## Prompt Caching (Quick Reference)
+
+**Prefix match.** Any byte change anywhere in the prefix invalidates everything after it. Render order is `tools` → `system` → `messages`. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last `cache_control` breakpoint.
+
+**Top-level auto-caching** (`cache_control: {type: "ephemeral"}` on `messages.create()`) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache.
+
+**Verify with `usage.cache_read_input_tokens`** — if it's zero across repeated requests, a silent invalidator is at work (`datetime.now()` in system prompt, unsorted JSON, varying tool set).
+
+For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read `shared/prompt-caching.md`. Language-specific syntax: `{lang}/claude-api/README.md` (Prompt Caching section).
+
+---
+
+## Reading Guide
+
+After detecting the language, read the relevant files based on what the user needs:
+
+### Quick Task Reference
+
+**Single text classification/summarization/extraction/Q&A:**
+→ Read only `{lang}/claude-api/README.md`
+
+**Chat UI or real-time response display:**
+→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md`
+
+**Long-running conversations (may exceed context window):**
+→ Read `{lang}/claude-api/README.md` — see Compaction section
+
+**Prompt caching / optimize caching / "why is my cache hit rate low":**
+→ Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section)
+
+**Function calling / tool use / agents:**
+→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md`
+
+**Batch processing (non-latency-sensitive):**
+→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md`
+
+**File uploads across multiple requests:**
+→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md`
+
+**Agent with built-in tools (file/web/terminal):**
+→ Read `{lang}/agent-sdk/README.md` + `{lang}/agent-sdk/patterns.md`
+
+### Claude API (Full File Reference)
+
+Read the **language-specific Claude API folder** (`{language}/claude-api/`):
+
+1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling.
+2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations.
+3. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs).
+4. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally.
+5. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost.
+6. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading.
+7. **`shared/prompt-caching.md`** — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache.
+8. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling.
+9. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation.
+
+> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed.
+
+### Agent SDK
+
+Read the **language-specific Agent SDK folder** (`{language}/agent-sdk/`). Agent SDK is available for **Python and TypeScript only**.
+
+1. **`{language}/agent-sdk/README.md`** — Installation, quick start, built-in tools, permissions, MCP, hooks.
+2. **`{language}/agent-sdk/patterns.md`** — Custom tools, hooks, subagents, MCP integration, session resumption.
+3. **`shared/live-sources.md`** — WebFetch URLs for current Agent SDK docs.
+
+---
+
+## When to Use WebFetch
+
+Use WebFetch to get the latest documentation when:
+
+- User asks for "latest" or "current" information
+- Cached data seems incorrect
+- User asks about features not covered here
+
+Live documentation URLs are in `shared/live-sources.md`.
+
+## Common Pitfalls
+
+- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating.
+- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` (deprecated on both Opus 4.6 and Sonnet 4.6). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong.
+- **Opus 4.6 prefill removed:** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead.
+- **`max_tokens` defaults:** Don't lowball `max_tokens` — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to `~16000` (keeps responses under SDK HTTP timeouts). For streaming requests, default to `~64000` (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (`~256`), cost caps, or deliberately short outputs.
+- **128K output tokens:** Opus 4.6 supports up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`.
+- **Tool call JSON parsing (Opus 4.6):** Opus 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input.
+- **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific.
+- **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces.
+- **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety.
+- **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text.

package/bundled/upstream/anthropic-skills/skills/claude-api/csharp/claude-api.md

@@ -0,0 +1,402 @@
+# Claude API — C#
+
+> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation.
+
+## Installation
+
+```bash
+dotnet add package Anthropic
+```
+
+## Client Initialization
+
+```csharp
+using Anthropic;
+
+// Default (uses ANTHROPIC_API_KEY env var)
+AnthropicClient client = new();
+
+// Explicit API key (use environment variables — never hardcode keys)
+AnthropicClient client = new() {
+    ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
+};
+```
+
+---
+
+## Basic Message Request
+
+```csharp
+using Anthropic.Models.Messages;
+
+var parameters = new MessageCreateParams
+{
+    Model = Model.ClaudeOpus4_6,
+    MaxTokens = 16000,
+    Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }]
+};
+var response = await client.Messages.Create(parameters);
+
+// ContentBlock is a union wrapper. .Value unwraps to the variant object,
+// then OfType<T> filters to the type you want. Or use the TryPick* idiom
+// shown in the Thinking section below.
+foreach (var text in response.Content.Select(b => b.Value).OfType<TextBlock>())
+{
+    Console.WriteLine(text.Text);
+}
+```
+
+---
+
+## Streaming
+
+```csharp
+using Anthropic.Models.Messages;
+
+var parameters = new MessageCreateParams
+{
+    Model = Model.ClaudeOpus4_6,
+    MaxTokens = 64000,
+    Messages = [new() { Role = Role.User, Content = "Write a haiku" }]
+};
+
+await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters))
+{
+    if (streamEvent.TryPickContentBlockDelta(out var delta) &&
+        delta.Delta.TryPickText(out var text))
+    {
+        Console.Write(text.Text);
+    }
+}
+```
+
+**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`.
+
+---
+
+## Thinking
+
+**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think.
+
+```csharp
+using Anthropic.Models.Messages;
+
+var response = await client.Messages.Create(new MessageCreateParams
+{
+    Model = Model.ClaudeOpus4_6,
+    MaxTokens = 16000,
+    // ThinkingConfigParam? implicitly converts from the concrete variant classes —
+    // no wrapper needed.
+    Thinking = new ThinkingConfigAdaptive(),
+    Messages =
+    [
+        new() { Role = Role.User, Content = "Solve: 27 * 453" },
+    ],
+});
+
+// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union.
+foreach (var block in response.Content)
+{
+    if (block.TryPickThinking(out ThinkingBlock? t))
+    {
+        Console.WriteLine($"[thinking] {t.Thinking}");
+    }
+    else if (block.TryPickText(out TextBlock? text))
+    {
+        Console.WriteLine(text.Text);
+    }
+}
+```
+
+> **Deprecated:** `new ThinkingConfigEnabled { BudgetTokens = N }` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above.
+
+Alternative to `TryPick*`: `.Select(b => b.Value).OfType<ThinkingBlock>()` (same LINQ pattern as the Basic Message example).
+
+---
+
+## Tool Use
+
+### Defining a tool
+
+`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`.
+
+```csharp
+using System.Text.Json;
+using Anthropic.Models.Messages;
+
+var parameters = new MessageCreateParams
+{
+    Model = Model.ClaudeSonnet4_6,
+    MaxTokens = 16000,
+    Tools = [
+        new Tool {
+            Name = "get_weather",
+            Description = "Get the current weather in a given location",
+            InputSchema = new() {
+                Properties = new Dictionary<string, JsonElement> {
+                    ["location"] = JsonSerializer.SerializeToElement(
+                        new { type = "string", description = "City name" }),
+                },
+                Required = ["location"],
+            },
+        },
+    ],
+    Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }],
+};
+```
+
+Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion).
+
+See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern.
+### Converting response content to the follow-up assistant message
+
+When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path).
+
+```csharp
+using Anthropic.Models.Messages;
+
+Message response = await client.Messages.Create(parameters);
+
+// No .ToParam() — reconstruct per variant. Implicit conversions from each
+// *Param type to ContentBlockParam mean no explicit wrapper.
+List<ContentBlockParam> assistantContent = [];
+List<ContentBlockParam> toolResults = [];
+foreach (ContentBlock block in response.Content)
+{
+    if (block.TryPickText(out TextBlock? text))
+    {
+        assistantContent.Add(new TextBlockParam { Text = text.Text });
+    }
+    else if (block.TryPickThinking(out ThinkingBlock? thinking))
+    {
+        // Signature MUST be preserved — the API rejects tampering
+        assistantContent.Add(new ThinkingBlockParam
+        {
+            Thinking = thinking.Thinking,
+            Signature = thinking.Signature,
+        });
+    }
+    else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
+    {
+        assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
+    }
+    else if (block.TryPickToolUse(out ToolUseBlock? toolUse))
+    {
+        // ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it
+        assistantContent.Add(new ToolUseBlockParam
+        {
+            ID = toolUse.ID,
+            Name = toolUse.Name,
+            Input = toolUse.Input,
+        });
+        // Execute the tool; collect ONE result per tool_use block — the API
+        // rejects the follow-up if any tool_use ID lacks a matching tool_result.
+        string result = ExecuteYourTool(toolUse.Name, toolUse.Input);
+        toolResults.Add(new ToolResultBlockParam
+        {
+            ToolUseID = toolUse.ID,
+            Content = result,
+        });
+    }
+}
+
+// Follow-up: prior messages + assistant echo + user tool_result(s)
+List<MessageParam> followUpMessages =
+[
+    .. parameters.Messages,
+    new() { Role = Role.Assistant, Content = assistantContent },
+    new() { Role = Role.User, Content = toolResults },
+];
+```
+
+`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts.
+
+---
+
+## Context Editing / Compaction (Beta)
+
+**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`:
+
+```csharp
+using Anthropic.Models.Beta.Messages;
+using NonBeta = Anthropic.Models.Messages;  // only if you also need non-beta types
+// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed)
+```
+
+
+`BetaMessage.Content` is `IReadOnlyList<BetaContentBlock>` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block:
+
+```csharp
+using Anthropic.Models.Beta.Messages;
+
+var betaParams = new MessageCreateParams   // no Beta prefix — one of only 2 unprefixed
+{
+    Model = Model.ClaudeOpus4_6,
+    MaxTokens = 16000,
+    Betas = ["compact-2026-01-12"],
+    ContextManagement = new BetaContextManagementConfig
+    {
+        Edits = [new BetaCompact20260112Edit()],
+    },
+    Messages = messages,
+};
+BetaMessage resp = await client.Beta.Messages.Create(betaParams);
+
+foreach (BetaContentBlock block in resp.Content)
+{
+    if (block.TryPickCompaction(out BetaCompactionBlock? compaction))
+    {
+        // Content is nullable — compaction can fail server-side
+        Console.WriteLine($"compaction summary: {compaction.Content}");
+    }
+}
+
+// Context-edit metadata lives on a separate nullable field
+if (resp.ContextManagement is { } ctx)
+{
+    foreach (var edit in ctx.AppliedEdits)
+        Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens");
+}
+
+// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list
+// union). It implicit-converts from List<BetaContentBlockParam>, NOT from the
+// response's IReadOnlyList<BetaContentBlock>. Convert each block:
+List<BetaContentBlockParam> paramBlocks = [];
+foreach (var b in resp.Content)
+{
+    if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text });
+    else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content });
+    // ... other variants as needed
+}
+messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks });
+```
+
+All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`.
+
+**`BetaToolUseBlock.Input` is `IReadOnlyDictionary<string, JsonElement>`** — index by key then call the `JsonElement` extractor:
+
+```csharp
+if (block.TryPickToolUse(out BetaToolUseBlock? tu))
+{
+    int a = tu.Input["a"].GetInt32();
+    string s = tu.Input["name"].GetString()!;
+}
+```
+
+---
+
+## Effort Parameter
+
+Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum<string, Effort>` has an implicit conversion from the enum, so assign `Effort.High` directly.
+
+```csharp
+OutputConfig = new OutputConfig { Effort = Effort.High },
+```
+
+Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control.
+
+---
+
+## Prompt Caching
+
+`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List<TextBlockParam>`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List<TextBlockParam>` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`.
+
+```csharp
+System = new List<TextBlockParam> {
+    new() {
+        Text = longSystemPrompt,
+        CacheControl = new CacheControlEphemeral(),  // auto-sets Type = "ephemeral"
+    },
+},
+```
+
+Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`.
+
+Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`.
+
+---
+
+## Token Counting
+
+```csharp
+MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams {
+    Model = Model.ClaudeOpus4_6,
+    Messages = [new() { Role = Role.User, Content = "Hello" }],
+});
+long tokens = result.InputTokens;
+```
+
+`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters.
+
+---
+
+## Structured Output
+
+```csharp
+OutputConfig = new OutputConfig {
+    Format = new JsonOutputFormat {
+        Schema = new Dictionary<string, JsonElement> {
+            ["type"] = JsonSerializer.SerializeToElement("object"),
+            ["properties"] = JsonSerializer.SerializeToElement(
+                new { name = new { type = "string" } }),
+            ["required"] = JsonSerializer.SerializeToElement(new[] { "name" }),
+        },
+    },
+},
+```
+
+`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`.
+
+---
+
+## PDF / Document Input
+
+`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`.
+
+```csharp
+new MessageParam {
+    Role = Role.User,
+    Content = new List<ContentBlockParam> {
+        new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } },
+        new TextBlockParam { Text = "Summarize this PDF" },
+    },
+}
+```
+
+---
+
+## Server-Side Tools
+
+Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set `name`/`type`. All implicit-convert to `ToolUnion`.
+
+```csharp
+Tools = [
+    new WebSearchTool20260209(),
+    new ToolBash20250124(),
+    new ToolTextEditor20250728(),
+    new CodeExecutionTool20260120(),
+],
+```
+
+Also available: `WebFetchTool20260209`, `MemoryTool20250818`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`.
+
+---
+
+## Files API (Beta)
+
+Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`.
+
+```csharp
+using Anthropic.Models.Beta.Files;
+using Anthropic.Models.Beta.Messages;
+
+FileMetadata meta = await client.Beta.Files.Upload(
+    new FileUploadParams { File = File.OpenRead("doc.pdf") });
+
+// Referencing the uploaded file requires Beta message types:
+new BetaRequestDocumentBlock {
+    Source = new BetaFileDocumentSource { FileID = meta.ID },
+}
+```
+
+The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`.