chore: import upstream snapshot with attribution

cli-tool/components/skills/development/claude-api/shared/agent-design.md

@@ -0,0 +1,101 @@
+# Agent Design Patterns
+
+This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders.
+
+---
+
+## Model Parameters
+
+| Parameter | When to use it | What to expect |
+| --- | --- | --- |
+| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. |
+| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. |
+
+See `SKILL.md` §Thinking & Effort for model support and parameter details.
+
+---
+
+## Designing Your Tool Surface
+
+### Bash vs. dedicated tools
+
+Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.
+
+A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.
+
+**When to promote an action to a dedicated tool:**
+
+- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not.
+- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant.
+- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
+- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize.
+
+**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.
+
+---
+
+## Anthropic-Provided Tools
+
+| Tool | Side | When to use it | What to expect |
+| --- | --- | --- | --- |
+| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. |
+| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. |
+| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. |
+| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. |
+| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. |
+| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. |
+
+**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest.
+
+---
+
+## Composing Tool Calls: Programmatic Tool Calling
+
+With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.
+
+**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
+
+| When to use it | What to expect |
+| --- | --- |
+| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. |
+
+---
+
+## Scaling the Tool and Instruction Set
+
+| Feature | When to use it | What to expect |
+| --- | --- | --- |
+| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). |
+| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. |
+
+Both patterns keep the fixed context small and load detail on demand.
+
+---
+
+## Long-Running Agents: Managing Context
+
+| Pattern | When to use it | What to expect |
+| --- | --- | --- |
+| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. |
+| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. |
+| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. |
+
+**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.
+
+---
+
+## Caching for Agents
+
+**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.
+
+| Constraint (from `prompt-caching.md`) | Agent-specific workaround |
+| --- | --- |
+| Editing the system prompt mid-session invalidates the cache. | Append a `<system-reminder>` block in the `messages` array instead. The cached prefix stays intact. Claude Code uses this for time updates and mode transitions. |
+| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. |
+| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
+
+For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns.
+
+---
+
+For live documentation on any of these features, see `live-sources.md`.

cli-tool/components/skills/development/claude-api/shared/error-codes.md

@@ -0,0 +1,213 @@
+# HTTP Error Codes Reference
+
+This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders.
+
+## Error Code Summary
+
+| Code | Error Type              | Retryable | Common Cause                         |
+| ---- | ----------------------- | --------- | ------------------------------------ |
+| 400  | `invalid_request_error` | No        | Invalid request format or parameters |
+| 401  | `authentication_error`  | No        | Invalid or missing API key           |
+| 403  | `permission_error`      | No        | API key lacks permission             |
+| 404  | `not_found_error`       | No        | Invalid endpoint or model ID         |
+| 413  | `request_too_large`     | No        | Request exceeds size limits          |
+| 429  | `rate_limit_error`      | Yes       | Too many requests                    |
+| 500  | `api_error`             | Yes       | Anthropic service issue              |
+| 529  | `overloaded_error`      | Yes       | API is temporarily overloaded        |
+
+## Detailed Error Information
+
+### 400 Bad Request
+
+**Causes:**
+
+- Malformed JSON in request body
+- Missing required parameters (`model`, `max_tokens`, `messages`)
+- Invalid parameter types (e.g., string where integer expected)
+- Empty messages array
+- Messages not alternating user/assistant
+
+**Example error:**
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "invalid_request_error",
+    "message": "messages: roles must alternate between \"user\" and \"assistant\""
+  },
+  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
+}
+```
+
+**Fix:** Validate request structure before sending. Check that:
+
+- `model` is a valid model ID
+- `max_tokens` is a positive integer
+- `messages` array is non-empty and alternates correctly
+
+---
+
+### 401 Unauthorized
+
+**Causes:**
+
+- Missing `x-api-key` header or `Authorization` header
+- Invalid API key format
+- Revoked or deleted API key
+
+**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly.
+
+---
+
+### 403 Forbidden
+
+**Causes:**
+
+- API key doesn't have access to the requested model
+- Organization-level restrictions
+- Attempting to access beta features without beta access
+
+**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
+
+---
+
+### 404 Not Found
+
+**Causes:**
+
+- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`)
+- Using deprecated model ID
+- Invalid API endpoint
+
+**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-7`).
+
+---
+
+### 413 Request Too Large
+
+**Causes:**
+
+- Request body exceeds maximum size
+- Too many tokens in input
+- Image data too large
+
+**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
+
+---
+
+### 400 Validation Errors
+
+Some 400 errors are specifically related to parameter validation:
+
+- `max_tokens` exceeds model's limit
+- Invalid `temperature` value (must be 0.0-1.0)
+- `budget_tokens` >= `max_tokens` in extended thinking
+- Invalid tool definition schema
+
+**Model-specific 400s on Opus 4.7:**
+
+- `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference.
+- `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead.
+
+**Common mistake with extended thinking on older models (Opus 4.6 and earlier):**
+
+```
+# Wrong: budget_tokens must be < max_tokens
+thinking: budget_tokens=10000, max_tokens=1000  → Error!
+
+# Correct
+thinking: budget_tokens=10000, max_tokens=16000
+```
+
+---
+
+### 429 Rate Limited
+
+**Causes:**
+
+- Exceeded requests per minute (RPM)
+- Exceeded tokens per minute (TPM)
+- Exceeded tokens per day (TPD)
+
+**Headers to check:**
+
+- `retry-after`: Seconds to wait before retrying
+- `x-ratelimit-limit-*`: Your limits
+- `x-ratelimit-remaining-*`: Remaining quota
+
+**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples.
+
+---
+
+### 500 Internal Server Error
+
+**Causes:**
+
+- Temporary Anthropic service issue
+- Bug in API processing
+
+**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
+
+---
+
+### 529 Overloaded
+
+**Causes:**
+
+- High API demand
+- Service capacity reached
+
+**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
+
+---
+
+## Common Mistakes and Fixes
+
+| Mistake                         | Error            | Fix                                                     |
+| ------------------------------- | ---------------- | ------------------------------------------------------- |
+| `temperature`/`top_p`/`top_k` on Opus 4.7 | 400    | Remove the parameter (see `shared/model-migration.md`)  |
+| `budget_tokens` on Opus 4.7     | 400              | Use `thinking: {type: "adaptive"}`                      |
+| `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens`                  |
+| Typo in model ID                | 404              | Use valid model ID like `claude-opus-4-7`               |
+| First message is `assistant`    | 400              | First message must be `user`                            |
+| Consecutive same-role messages  | 400              | Alternate `user` and `assistant`                        |
+| API key in code                 | 401 (leaked key) | Use environment variable                                |
+| Custom retry needs              | 429/5xx          | SDK retries automatically; customize with `max_retries` |
+
+## Typed Exceptions in SDKs
+
+**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:
+
+| HTTP Code | TypeScript Class                  | Python Class                      |
+| --------- | --------------------------------- | --------------------------------- |
+| 400       | `Anthropic.BadRequestError`       | `anthropic.BadRequestError`       |
+| 401       | `Anthropic.AuthenticationError`   | `anthropic.AuthenticationError`   |
+| 403       | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` |
+| 404       | `Anthropic.NotFoundError`         | `anthropic.NotFoundError`         |
+| 429       | `Anthropic.RateLimitError`        | `anthropic.RateLimitError`        |
+| 500+      | `Anthropic.InternalServerError`   | `anthropic.InternalServerError`   |
+| Any       | `Anthropic.APIError`              | `anthropic.APIError`              |
+
+```typescript
+// ✅ Correct: use typed exceptions
+try {
+  const response = await client.messages.create({...});
+} catch (error) {
+  if (error instanceof Anthropic.RateLimitError) {
+    // Handle rate limiting
+  } else if (error instanceof Anthropic.APIError) {
+    console.error(`API error ${error.status}:`, error.message);
+  }
+}
+
+// ❌ Wrong: don't check error messages with string matching
+try {
+  const response = await client.messages.create({...});
+} catch (error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
+}
+```
+
+All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`).

cli-tool/components/skills/development/claude-api/shared/live-sources.md

@@ -0,0 +1,133 @@
+# Live Documentation Sources
+
+This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.
+
+## When to Use WebFetch
+
+- User explicitly asks for "latest" or "current" information
+- Cached data seems incorrect
+- User asks about features not covered in cached content
+- User needs specific API details or examples
+
+## Claude API Documentation URLs
+
+### Models & Pricing
+
+| Topic           | URL                                                                          | Extraction Prompt                                                               |
+| --------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md`        | "Extract current model IDs, context windows, and pricing for all Claude models" |
+| Migration Guide | `https://platform.claude.com/docs/en/about-claude/models/migration-guide.md` | "Extract breaking changes, deprecated parameters, and per-model migration steps when moving to a newer Claude model" |
+| Pricing         | `https://platform.claude.com/docs/en/pricing.md`                             | "Extract current pricing per million tokens for input and output"               |
+
+### Core Features
+
+| Topic             | URL                                                                          | Extraction Prompt                                                                      |
+| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" |
+| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.7 usage examples"         |
+| Effort Parameter  | `https://platform.claude.com/docs/en/build-with-claude/effort.md`            | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking"        |
+| Tool Use          | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md`  | "Extract tool definition schema, tool_choice options, and handling tool results"       |
+| Streaming         | `https://platform.claude.com/docs/en/build-with-claude/streaming.md`         | "Extract streaming event types, SDK examples, and best practices"                      |
+| Prompt Caching    | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md`    | "Extract cache_control usage, pricing benefits, and implementation examples"           |
+
+### Media & Files
+
+| Topic       | URL                                                                    | Extraction Prompt                                                 |
+| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Vision      | `https://platform.claude.com/docs/en/build-with-claude/vision.md`      | "Extract supported image formats, size limits, and code examples" |
+| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples"         |
+
+### API Operations
+
+| Topic            | URL                                                                         | Extraction Prompt                                                                                       |
+| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results"                                  |
+| Files API        | `https://platform.claude.com/docs/en/build-with-claude/files.md`            | "Extract file upload, download, and referencing in messages, including supported types and beta header" |
+| Token Counting   | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md`   | "Extract token counting API usage and examples"                                                         |
+| Rate Limits      | `https://platform.claude.com/docs/en/api/rate-limits.md`                    | "Extract current rate limits by tier and model"                                                         |
+| Errors           | `https://platform.claude.com/docs/en/api/errors.md`                         | "Extract HTTP error codes, meanings, and retry guidance"                                                |
+
+### Tools
+
+| Topic          | URL                                                                                    | Extraction Prompt                                                                        |
+| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" |
+| Computer Use   | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md`        | "Extract computer use tool setup, capabilities, and implementation examples"             |
+| Bash Tool      | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md`           | "Extract bash tool schema, reference implementation, and security considerations"        |
+| Text Editor    | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md`    | "Extract text editor tool commands, schema, and reference implementation"                |
+| Memory Tool    | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md`         | "Extract memory tool commands, directory structure, and implementation patterns"         |
+| Tool Search    | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md`    | "Extract tool search setup, when to use, and cache interaction"                          |
+| Programmatic Tool Calling | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md` | "Extract PTC setup, script execution model, and tool invocation from code"    |
+| Skills         | `https://platform.claude.com/docs/en/agents-and-tools/skills.md`                       | "Extract skill folder structure, SKILL.md format, and loading behavior"                  |
+
+### Advanced Features
+
+| Topic              | URL                                                                           | Extraction Prompt                                   |
+| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- |
+| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement"                           |
+| Compaction         | `https://platform.claude.com/docs/en/build-with-claude/compaction.md`         | "Extract compaction setup, trigger config, and streaming with compaction"             |
+| Context Editing    | `https://platform.claude.com/docs/en/build-with-claude/context-editing.md`    | "Extract context editing thresholds, what gets cleared, and configuration"            |
+| Citations          | `https://platform.claude.com/docs/en/build-with-claude/citations.md`          | "Extract citation format and implementation"        |
+| Context Windows    | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md`    | "Extract context window sizes and token management" |
+
+### Managed Agents
+
+Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached `shared/managed-agents-*.md` concept files or in `{lang}/managed-agents/README.md`.
+
+| Topic                 | URL                                                                              | Extraction Prompt                                                                               |
+| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Overview              | `https://platform.claude.com/docs/en/managed-agents/overview.md`                 | "Extract the high-level architecture and how agents/sessions/environments/vaults fit together" |
+| Quickstart            | `https://platform.claude.com/docs/en/managed-agents/quickstart.md`               | "Extract the minimal end-to-end agent → environment → session → stream code path"              |
+| Agent Setup           | `https://platform.claude.com/docs/en/managed-agents/agent-setup.md`              | "Extract agent create/update/list-versions/archive lifecycle and parameters"                   |
+| Define Outcomes       | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md`          | "Extract outcome definitions, evaluation hooks, and success criteria configuration"             |
+| Sessions              | `https://platform.claude.com/docs/en/managed-agents/sessions.md`                 | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules"    |
+| Environments          | `https://platform.claude.com/docs/en/managed-agents/environments.md`             | "Extract environment config (cloud/networking), management endpoints, and reuse model"          |
+| Events and Streaming  | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md`     | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns"    |
+| Tools                 | `https://platform.claude.com/docs/en/managed-agents/tools.md`                    | "Extract built-in toolset, custom tool definitions, and tool result wire format"                |
+| Files                 | `https://platform.claude.com/docs/en/managed-agents/files.md`                    | "Extract file upload, mount paths, session resources, and listing/downloading session outputs"  |
+| Permission Policies   | `https://platform.claude.com/docs/en/managed-agents/permission-policies.md`      | "Extract permission policy types (allow/deny/confirm) and per-tool config"                     |
+| Multi-Agent           | `https://platform.claude.com/docs/en/managed-agents/multi-agent.md`              | "Extract multi-agent composition patterns, sub-agent invocation, and result handoff"            |
+| Observability         | `https://platform.claude.com/docs/en/managed-agents/observability.md`            | "Extract logging, tracing, and usage telemetry exposed by managed agents"                       |
+| Webhooks              | `https://platform.claude.com/docs/en/managed-agents/webhooks.md`                 | "Extract webhook endpoint registration, HMAC signature verification, supported event types, and delivery semantics" |
+| GitHub                | `https://platform.claude.com/docs/en/managed-agents/github.md`                   | "Extract github_repository resource shape, multi-repo mounting, and token rotation"             |
+| MCP Connector         | `https://platform.claude.com/docs/en/managed-agents/mcp-connector.md`            | "Extract MCP server declaration on agents and vault-based credential injection at session"     |
+| Vaults                | `https://platform.claude.com/docs/en/managed-agents/vaults.md`                   | "Extract vault create, credential add/rotate, OAuth refresh shape, and archive"                 |
+| Skills                | `https://platform.claude.com/docs/en/managed-agents/skills.md`                   | "Extract skill packaging and loading model for managed agents"                                  |
+| Memory                | `https://platform.claude.com/docs/en/managed-agents/memory.md`                   | "Extract memory resource shape, scoping, and lifecycle"                                         |
+| Onboarding            | `https://platform.claude.com/docs/en/managed-agents/onboarding.md`               | "Extract first-run setup, prerequisites, and account/region requirements"                      |
+| Cloud Containers      | `https://platform.claude.com/docs/en/managed-agents/cloud-containers.md`         | "Extract cloud container runtime, image config, and network/storage knobs"                     |
+| Migration             | `https://platform.claude.com/docs/en/managed-agents/migration.md`                | "Extract migration paths from earlier APIs/preview shapes to GA managed agents"                 |
+
+### Anthropic CLI
+
+The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively.
+
+| Topic         | URL                                                     | Extraction Prompt                                                                                  |
+| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Anthropic CLI | `https://platform.claude.com/docs/en/api/sdks/cli.md`   | "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" |
+
+---
+
+## Claude API SDK Repositories
+
+WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached `{lang}/` skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for `/v1/agents`, `/v1/sessions`, `/v1/environments`, and related resources — search the repo for `BetaManagedAgents`, `beta.agents`, `beta.sessions`, or the equivalent namespace for that language.
+
+| SDK        | URL                                                      | Extraction Prompt                                                                                                       |
+| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Python     | `https://github.com/anthropics/anthropic-sdk-python`     | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" |
+| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" |
+| Java       | `https://github.com/anthropics/anthropic-sdk-java`       | "Extract beta managed-agents classes, builders, and method signatures (`client.beta().agents()`, `BetaManagedAgents*`)" |
+| Go         | `https://github.com/anthropics/anthropic-sdk-go`         | "Extract beta managed-agents types and method signatures (`client.Beta.Agents`, `BetaManagedAgents*` event types)"      |
+| Ruby       | `https://github.com/anthropics/anthropic-sdk-ruby`       | "Extract beta managed-agents methods and parameter shapes (`client.beta.agents`, `client.beta.sessions`)"               |
+| C#         | `https://github.com/anthropics/anthropic-sdk-csharp`     | "Extract beta managed-agents classes and method signatures (NuGet package, `BetaManagedAgents*` types)"                 |
+| PHP        | `https://github.com/anthropics/anthropic-sdk-php`        | "Extract beta managed-agents classes and method signatures (`$client->beta->agents`, `BetaManagedAgents*` params)"      |
+
+---
+
+## Fallback Strategy
+
+If WebFetch fails (network issues, URL changed):
+
+1. Use cached content from the language-specific files (note the cache date)
+2. Inform user the data may be outdated
+3. Suggest they check platform.claude.com or the GitHub repos directly

cli-tool/components/skills/development/claude-api/shared/managed-agents-api-reference.md

@@ -0,0 +1,372 @@
+# Managed Agents — Endpoint Reference
+
+All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header.
+
+## Beta Headers
+
+```
+anthropic-beta: managed-agents-2026-04-01
+```
+
+The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults,memory_stores}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`.
+
+---
+
+## SDK Method Reference
+
+All resources are under the `beta` namespace. Python and TypeScript share identical method names.
+
+| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) |
+| --- | --- | --- |
+| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` |
+| Agent Versions | `agents.versions.list` | `Agents.Versions.List` |
+| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
+| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
+| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` |
+| Session Threads | `sessions.threads.list` / `retrieve` / `archive`; `sessions.threads.events.list` / `stream` | `Sessions.Threads.List` / `Get` / `Archive`; `Sessions.Threads.Events.List` / `StreamEvents` |
+| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` |
+| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
+| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` / `mcp_oauth_validate` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` / `McpOauthValidate` |
+| Memory Stores | `memory_stores.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `MemoryStores.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
+| Memories | `memory_stores.memories.create` / `retrieve` / `update` / `list` / `delete` | `MemoryStores.Memories.New` / `Get` / `Update` / `List` / `Delete` |
+| Memory Versions | `memory_stores.memory_versions.list` / `retrieve` / `redact` | `MemoryStores.MemoryVersions.List` / `Get` / `Redact` |
+
+**Naming quirks to watch for:**
+- Agents and Session Threads have **no delete** — only `archive`. Archive is **permanent**: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both `delete` and `archive`; Session Resources, Files, Skills, and Memories are `delete`-only; Memory Versions have neither — only `redact`.
+- Session resources use `add` (not `create`).
+- Go's event stream is `StreamEvents` (not `Stream`).
+
+**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`).
+
+**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-7"` — uses `standard` speed) or the full config object (`{id: "claude-opus-4-6", speed: "fast"}`). Note: `speed: "fast"` is only supported on Opus 4.6.
+
+---
+
+## Agents
+
+**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`.
+
+| Method   | Path                                             | Operation        | Description                              |
+| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
+| `GET` | `/v1/agents` | ListAgents | List agents |
+| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration |
+| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details |
+| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration |
+| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
+| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions |
+
+## Sessions
+
+| Method   | Path                                             | Operation        | Description                              |
+| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
+| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) |
+| `POST` | `/v1/sessions` | CreateSession | Create a new session |
+| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details |
+| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title |
+| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session |
+| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session |
+
+## Events
+
+| Method   | Path                                             | Operation        | Description                              |
+| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
+| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) |
+| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) |
+| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE |
+
+## Session Threads
+
+Per-subagent event streams in multiagent sessions. See `shared/managed-agents-multiagent.md`.
+
+| Method   | Path                                             | Operation        | Description                              |
+| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
+| `GET` | `/v1/sessions/{session_id}/threads` | ListThreads | List threads (paginated) |
+| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}` | GetThread | Retrieve one thread (carries `agent` snapshot, `status`, `parent_thread_id`, `stats`, `usage`) |
+| `POST` | `/v1/sessions/{session_id}/threads/{thread_id}/archive` | ArchiveThread | Archive a thread |
+| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}/events` | ListThreadEvents | List past events for one thread (paginated) |
+| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}/stream` | StreamThreadEvents | Stream one thread via SSE (SDK: `threads.events.stream`) |
+
+## Session Resources
+
+| Method   | Path                                                    | Operation        | Description                              |
+| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- |
+| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session |
+| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach `file` or `github_repository` resource (SDK method: `add`, not `create`). `memory_store` resources attach at session-create time only. |
+| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource |
+| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource |
+| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session |
+
+## Environments
+
+| Method   | Path                                                             | Operation            | Description                         |
+| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- |
+| `POST`   | `/v1/environments`                                     | CreateEnvironment    | Create environment                  |
+| `GET`    | `/v1/environments`                                     | ListEnvironments     | List environments                   |
+| `GET`    | `/v1/environments/{environment_id}`                    | GetEnvironment       | Get environment details             |
+| `POST`   | `/v1/environments/{environment_id}`                    | UpdateEnvironment    | Update environment                  |
+| `DELETE` | `/v1/environments/{environment_id}`                    | DeleteEnvironment    | Delete environment. Returns 204. |
+| `POST`   | `/v1/environments/{environment_id}/archive`            | ArchiveEnvironment   | Archive environment. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
+
+## Vaults
+
+Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes.
+
+| Method   | Path                                             | Operation        | Description                              |
+| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
+| `POST`   | `/v1/vaults`                                     | CreateVault      | Create a vault                           |
+| `GET`    | `/v1/vaults`                                     | ListVaults       | List vaults                              |
+| `GET`    | `/v1/vaults/{vault_id}`                          | GetVault         | Get vault details                        |
+| `POST`   | `/v1/vaults/{vault_id}`                          | UpdateVault      | Update vault                             |
+| `DELETE` | `/v1/vaults/{vault_id}`                          | DeleteVault      | Delete vault                             |
+| `POST`   | `/v1/vaults/{vault_id}/archive`                  | ArchiveVault     | Archive vault                            |
+
+## Credentials
+
+Credentials are individual secrets stored inside a vault.
+
+| Method   | Path                                                              | Operation          | Description                  |
+| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- |
+| `POST`   | `/v1/vaults/{vault_id}/credentials`                               | CreateCredential   | Create a credential          |
+| `GET`    | `/v1/vaults/{vault_id}/credentials`                               | ListCredentials    | List credentials in vault    |
+| `GET`    | `/v1/vaults/{vault_id}/credentials/{credential_id}`               | GetCredential      | Get credential metadata      |
+| `POST`   | `/v1/vaults/{vault_id}/credentials/{credential_id}`               | UpdateCredential   | Update credential            |
+| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}`               | DeleteCredential   | Delete credential            |
+| `POST`   | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive`       | ArchiveCredential  | Archive credential           |
+| `POST`   | `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` | McpOauthValidate | Validate an MCP OAuth credential |
+
+## Memory Stores
+
+Workspace-scoped persistent memory that survives across sessions. Attach to a session via a `{"type": "memory_store", "memory_store_id": ...}` entry in `resources[]` (session-create time only). See `shared/managed-agents-memory.md` for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.
+
+| Method   | Path                                             | Operation          | Description                              |
+| -------- | ------------------------------------------------ | ------------------ | ---------------------------------------- |
+| `POST`   | `/v1/memory_stores`                              | CreateMemoryStore  | Create a store (`name`, `description`, `metadata`) |
+| `GET`    | `/v1/memory_stores`                              | ListMemoryStores   | List stores (`include_archived`, `created_at_{gte,lte}`) |
+| `GET`    | `/v1/memory_stores/{memory_store_id}`            | GetMemoryStore     | Get store details                        |
+| `POST`   | `/v1/memory_stores/{memory_store_id}`            | UpdateMemoryStore  | Update store                             |
+| `DELETE` | `/v1/memory_stores/{memory_store_id}`            | DeleteMemoryStore  | Delete store                             |
+| `POST`   | `/v1/memory_stores/{memory_store_id}/archive`    | ArchiveMemoryStore | Archive store. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive. |
+
+## Memories
+
+Individual text documents inside a store (≤ 100KB each). `create` creates at a `path` and returns `409` (`memory_path_conflict_error`, with `conflicting_memory_id`) if the path is occupied; `update` mutates by `mem_...` ID (rename and/or content). Only `update` accepts a `precondition` (`{"type": "content_sha256", "content_sha256": ...}`) — on mismatch returns `409` (`memory_precondition_failed_error`). List endpoints accept `view: "basic"|"full"` (controls whether `content` is populated; `retrieve` defaults to `full`).
+
+| Method   | Path                                                              | Operation      | Description                              |
+| -------- | ----------------------------------------------------------------- | -------------- | ---------------------------------------- |
+| `GET`    | `/v1/memory_stores/{memory_store_id}/memories`                    | ListMemories   | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth`, `order_by`/`order` |
+| `POST`   | `/v1/memory_stores/{memory_store_id}/memories`                    | CreateMemory   | Create at `path` (SDK: `memories.create`); `409 memory_path_conflict_error` if occupied |
+| `GET`    | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | GetMemory      | Read one memory (defaults to `view="full"`) |
+| `PATCH`  | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | UpdateMemory   | Change `content`, `path`, or both by ID; optional `precondition` |
+| `DELETE` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}`        | DeleteMemory   | Delete (optional `expected_content_sha256`) |
+
+## Memory Versions
+
+Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surface. `operation` ∈ `created` / `modified` / `deleted`.
+
+| Method   | Path                                                                          | Operation             | Description                              |
+| -------- | ----------------------------------------------------------------------------- | --------------------- | ---------------------------------------- |
+| `GET`    | `/v1/memory_stores/{memory_store_id}/memory_versions`                         | ListMemoryVersions    | Newest-first; filter by `memory_id`, `operation`, `session_id`, `api_key_id`, `created_at_{gte,lte}` |
+| `GET`    | `/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}`            | GetMemoryVersion      | List fields + full `content`             |
+| `POST`   | `/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact`     | RedactMemoryVersion   | Clear `content`/`content_sha256`/`content_size_bytes`/`path`; preserve actor + timestamps |
+
+## Files
+
+| Method   | Path                                             | Operation        | Description                              |
+| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
+| `POST`   | `/v1/files`                            | UploadFile       | Upload a file                            |
+| `GET`    | `/v1/files`                            | ListFiles        | List files                               |
+| `GET`    | `/v1/files/{file_id}`                  | GetFile          | Get file metadata (SDK method: `retrieve_metadata`) |
+| `GET`    | `/v1/files/{file_id}/content`          | DownloadFile     | Download file content                    |
+| `DELETE` | `/v1/files/{file_id}`                  | DeleteFile       | Delete a file                            |
+
+## Skills
+
+| Method   | Path                                                            | Operation          | Description                  |
+| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- |
+| `POST`   | `/v1/skills`                                          | CreateSkill        | Create a skill               |
+| `GET`    | `/v1/skills`                                          | ListSkills         | List skills                  |
+| `GET`    | `/v1/skills/{skill_id}`                               | GetSkill           | Get skill details            |
+| `DELETE` | `/v1/skills/{skill_id}`                               | DeleteSkill        | Delete a skill               |
+| `POST`   | `/v1/skills/{skill_id}/versions`                      | CreateVersion      | Create skill version         |
+| `GET`    | `/v1/skills/{skill_id}/versions`                      | ListVersions       | List skill versions          |
+| `GET`    | `/v1/skills/{skill_id}/versions/{version}`            | GetVersion         | Get skill version            |
+| `DELETE` | `/v1/skills/{skill_id}/versions/{version}`            | DeleteVersion      | Delete skill version         |
+
+---
+
+## Request/Response Schema Quick Reference
+
+### CreateAgent Request Body
+
+**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session.
+
+```json
+{
+  "name": "string (required, 1-256 chars)",
+  "model": "claude-opus-4-7 (required — bare string, or {id, speed} object)",
+  "description": "string (optional, up to 2048 chars)",
+  "system": "string (optional, up to 100,000 chars)",
+  "tools": [
+    { "type": "agent_toolset_20260401" }
+  ],
+  "skills": [
+    { "type": "anthropic", "skill_id": "xlsx" },
+    { "type": "custom", "skill_id": "skill_abc123", "version": "1" }
+  ],
+  "mcp_servers": [
+    {
+      "type": "url",
+      "name": "github",
+      "url": "https://api.githubcopilot.com/mcp/"
+    }
+  ],
+  "multiagent": {
+    "type": "coordinator",
+    "agents": [
+      "agent_abc123",
+      { "type": "agent", "id": "agent_def456", "version": 4 },
+      { "type": "self" }
+    ]
+  },
+  "metadata": {
+    "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
+  }
+}
+```
+
+> Limits: `tools` max 128, `skills` max 20, `mcp_servers` max 20 (unique names). `multiagent.agents` 1–20 entries (string ID | `{type:"agent",id,version?}` | `{type:"self"}`) — see `shared/managed-agents-multiagent.md`.
+
+### CreateSession Request Body
+
+```json
+{
+  "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
+  "environment_id": "env_abc123 (required)",
+  "title": "string (optional)",
+  "resources": [
+    {
+      "type": "github_repository",
+      "url": "https://github.com/owner/repo (required)",
+      "authorization_token": "ghp_... (required)",
+      "mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
+      "checkout": { "type": "branch", "name": "main" }
+    }
+  ],
+  "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"],
+  "metadata": {
+    "key": "value"
+  }
+}
+```
+
+> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here.
+>
+> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch.
+
+### CreateEnvironment Request Body
+
+```json
+{
+  "name": "string (required)",
+  "description": "string (optional)",
+  "config": {
+    "type": "cloud",
+    "networking": {
+      "type": "unrestricted | limited (union — see SDK types)"
+    },
+    "packages": { }
+  },
+  "metadata": { "key": "value" }
+}
+```
+
+### SendEvents Request Body
+
+```json
+{
+  "events": [
+    {
+      "type": "user.message",
+      "content": [
+        {
+          "type": "text",
+          "text": "Hello"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Define Outcome Event
+
+```json
+{
+  "type": "user.define_outcome",
+  "description": "Build a DCF model for Costco in .xlsx",
+  "rubric": { "type": "file", "file_id": "file_01..." },
+  "max_iterations": 5
+}
+```
+
+> `rubric` is required: `{type: "text", content}` or `{type: "file", file_id}`. `max_iterations` default 3, max 20. Echoed back with `outcome_id` + `processed_at`. See `shared/managed-agents-outcomes.md`.
+
+### Tool Result Event
+
+```json
+{
+  "type": "user.custom_tool_result",
+  "custom_tool_use_id": "sevt_abc123",
+  "content": [{ "type": "text", "text": "Result data" }],
+  "is_error": false
+}
+```
+
+---
+
+## Error Handling
+
+Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`:
+
+```json
+{
+  "type": "error",
+  "error": {
+    "type": "invalid_request_error",
+    "message": "Description of what went wrong"
+  },
+  "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
+}
+```
+
+Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following:
+
+| Status | Error type | Description |
+|---|---|---|
+| 400 | `invalid_request_error` | The request was malformed or missing required parameters |
+| 401 | `authentication_error` | Invalid or missing API key |
+| 403 | `permission_error` | The API key doesn't have permission for this operation |
+| 404 | `not_found_error` | The requested resource doesn't exist |
+| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) |
+| 413 | `request_too_large` | The request body exceeds the maximum allowed size |
+| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing |
+| 500 | `api_error` | An internal server error occurred |
+| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff |
+
+Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests.
+
+---
+
+## Rate Limits
+
+Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.
+
+| Endpoint group | Scope | RPM | Max concurrent |
+|---|---|---|---|
+| Create operations (Agents, Sessions, Vaults) | organization | 60 | — |
+| All other operations (Agents, Sessions, Vaults) | organization | 600 | — |
+| All operations (Environments) | organization | 60 | 5 |
+
+Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits).
+
+When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.

cli-tool/components/skills/development/claude-api/shared/managed-agents-client-patterns.md

@@ -0,0 +1,209 @@
+# Managed Agents — Common Client Patterns
+
+Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
+
+Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents.
+
+---
+
+## 1. Lossless stream reconnect
+
+**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.
+
+**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up.
+
+```ts
+const seenEventIds = new Set<string>()
+const stream = await client.beta.sessions.events.stream(session.id)
+
+// Stream is now open and buffering server-side. Read history first.
+for await (const event of client.beta.sessions.events.list(session.id)) {
+  seenEventIds.add(event.id)
+  handle(event)
+}
+
+// Tail the live stream. Dedupe only gates handle() — terminal checks must run
+// even for already-seen events, or a terminal event that was in the history
+// response gets skipped by `continue` and the loop never exits.
+for await (const event of stream) {
+  if (!seenEventIds.has(event.id)) {
+    seenEventIds.add(event.id)
+    handle(event)
+  }
+  if (event.type === 'session.status_terminated') break
+  if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
+}
+```
+
+---
+
+## 2. `processed_at` — queued vs processed
+
+Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp.
+
+```ts
+for await (const event of stream) {
+  if (event.type === 'user.message') {
+    if (event.processed_at == null) onQueued(event.id)
+    else onProcessed(event.id, event.processed_at)
+  }
+}
+```
+
+Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering).
+
+---
+
+## 3. Interrupt a running session
+
+Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.
+
+```ts
+await client.beta.sessions.events.send(session.id, {
+  events: [{ type: 'user.interrupt' }],
+})
+
+// Drain until the session is truly done — see Pattern 5 for the full gate.
+for await (const event of stream) {
+  if (event.type === 'session.status_terminated') break
+  if (
+    event.type === 'session.status_idle' &&
+    event.stop_reason.type !== 'requires_action'
+  ) break
+}
+```
+
+Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`.
+
+---
+
+## 4. `tool_confirmation` round-trip
+
+When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`.
+
+```ts
+for await (const event of stream) {
+  if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
+    await client.beta.sessions.events.send(session.id, {
+      events: [{
+        type: 'user.tool_confirmation',
+        tool_use_id: event.id,         // not a toolu_ id — use event.id
+        result: 'allow',               // or 'deny'
+        // deny_message: '...',        // optional, only with result: 'deny'
+      }],
+    })
+  }
+}
+```
+
+Key points:
+- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID.
+- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent.
+- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`.
+
+Reference: `tool-permissions.ts`.
+
+---
+
+## 5. Correct idle-break gate
+
+Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`.
+
+```ts
+for await (const event of stream) {
+  handle(event)
+  if (event.type === 'session.status_terminated') break
+  if (event.type === 'session.status_idle') {
+    if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
+    break // end_turn or retries_exhausted — both terminal
+  }
+}
+```
+
+`stop_reason.type` values on `session.status_idle`:
+- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.
+- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state.
+- `end_turn` — normal completion.
+
+---
+
+## 6. Post-idle status-write race
+
+The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running."
+
+Poll before cleanup:
+
+```ts
+let s
+for (let i = 0; i < 10; i++) {
+  s = await client.beta.sessions.retrieve(session.id)
+  if (s.status !== 'running') break
+  await new Promise(r => setTimeout(r, 200))
+}
+if (s?.status !== 'running') {
+  await client.beta.sessions.archive(session.id)
+} // else: still running after 2s — don't archive, let it settle or escalate
+```
+
+---
+
+## 7. Stream-first, then send
+
+Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.
+
+```ts
+const stream = await client.beta.sessions.events.stream(session.id)
+await client.beta.sessions.events.send(session.id, {
+  events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
+})
+for await (const event of stream) { /* ... */ }
+```
+
+The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
+
+---
+
+## 8. File-mount gotchas
+
+**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy.
+
+```ts
+const uploaded = await client.beta.files.upload({ file })
+// uploaded.id         → the original file
+const session = await client.beta.sessions.create({
+  /* ... */
+  resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
+})
+// session.resources[0].file_id !== uploaded.id  ← different IDs
+```
+
+Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`.
+
+---
+
+## 9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools
+
+**Problem:** you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but there is currently no way to set environment variables inside the session container, and vaults currently hold MCP credentials only — they are not exposed to the container's shell. So `curl`, installed CLIs, or SDK clients running via the `bash` tool have no first-class place to read a secret from.
+
+**Solution:** move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits `agent.custom_tool_use`, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key.
+
+```ts
+// Agent template: declare the tool, no credentials
+tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
+
+// Orchestrator: handle the call with host-side creds
+for await (const event of stream) {
+  if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
+    const result = await linear.request(event.input.query, event.input.vars) // host's key
+    await client.beta.sessions.events.send(session.id, {
+      events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
+    })
+  }
+}
+```
+
+Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-side auth or binaries.
+
+**Security note:** this does not expose a public endpoint. `agent.custom_tool_use` arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and `user.custom_tool_result` goes back via `events.send()` under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.
+
+**Do not embed API keys in the system prompt or user messages as a workaround.** Prompts and messages are stored in the session's event history, returned by `events.list()`, and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.

cli-tool/components/skills/development/claude-api/shared/managed-agents-core.md

@@ -0,0 +1,220 @@
+# Managed Agents — Core Concepts
+
+## Architecture
+
+Managed Agents is built around four core concepts:
+
+| Concept | Endpoint | What it is |
+|---|---|---|
+| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. |
+| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. |
+| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. |
+| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. |
+
+```
+                       ┌─────────────────────────────────────┐
+                       │  Anthropic orchestration layer      │
+Agent (config) ───────▶│  (agent loop: Claude + tool calls)  │
+                       └──────────────┬──────────────────────┘
+                                      │ tool calls
+                                      ▼
+Environment (template) ──▶ Container (tool execution workspace)
+                                 │
+                         Session ─┤
+                                 ├── Resources (files, repos, memory stores — attached at startup)
+                                 ├── Vault IDs (MCP credential references)
+                                 └── Conversation (event stream in/out)
+```
+
+> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`.
+
+---
+
+## Session Lifecycle
+
+```
+rescheduling → running ↔ idle → terminated
+```
+
+| Status         | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
+| `running` | Session has starting running, and the Agent is actively doing work. |
+| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
+| `terminated` | Session has terminated, entering an irreversible and unusable state.  |
+
+- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order.
+- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done.
+- Errors surface as `session.error` events in the stream, not as a status value.
+
+### Built-in session features
+
+- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going
+- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost
+- **Extended thinking** — on by default, returned as `agent.thinking` events
+
+### Session operations
+
+| Operation | Notes |
+|---|---|
+| List / fetch | Paginated list or single resource by ID |
+| Update | Only `title` is updatable |
+| Archive | Session becomes **read-only**. Not reversible. |
+| Delete | Permanently deletes session, event history, container, and checkpoints. |
+
+---
+
+## Sessions
+
+A session is a running agent instance inside an environment.
+
+### Session Object
+
+Key fields returned by the API:
+
+| Field           | Type     | Description                                         |
+| --------------- | -------- | --------------------------------------------------- |
+| `type` | string | Always `"session"` |
+| `id` | string | Unique session ID |
+| `title` | string | Human-readable title |
+| `status` | string | `idle`, `running`, `rescheduling`, `terminated` |
+| `created_at` | string | ISO 8601 timestamp |
+| `updated_at` | string | ISO 8601 timestamp |
+| `archived_at` | string | ISO 8601 timestamp (nullable) |
+| `environment_id` | string | Environment ID |
+| `agent` | object | Agent configuration |
+| `resources` | array | Attached files, repos, and memory stores |
+| `metadata` | object | User-provided key-value pairs (max 8 keys) |
+| `usage` | object | Token usage statistics |
+
+### Creating a session
+
+**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it:
+
+```ts
+// 1. Create the agent (reusable, versioned)
+const agent = await client.beta.agents.create(
+  {
+    name: "Coding Assistant",
+    model: "claude-opus-4-7",
+    system: "You are a helpful coding agent.",
+    tools: [{ type: "agent_toolset_20260401"}],
+  },
+);
+
+// 2. Start a session that references it
+const session = await client.beta.sessions.create(
+  {
+    agent: agent.id,  // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
+    environment_id: environmentId,
+    title: "Hello World Session",
+  },
+);
+```
+
+**Session creation parameters:**
+
+| Field           | Type     | Required | Description                                    |
+| --------------- | -------- | -------- | ---------------------------------------------- |
+| `agent`         | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` |
+| `environment_id`| string   | **Yes**  | Environment ID                                 |
+| `title`         | string   | No       | Human-readable name (appears in logs/dashboards) |
+| `resources`     | array    | No       | Files, GitHub repos, or memory stores, attached to the container at startup. Memory stores are session-create-only (not addable via `resources.add()`). |
+| `vault_ids`     | array    | No       | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh. See `shared/managed-agents-tools.md` → Vaults. |
+| `metadata`      | object   | No       | User-provided key-value pairs                  |
+
+**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`):
+
+| Field         | Type     | Required | Description                                    |
+| ------------- | -------- | -------- | ---------------------------------------------- |
+| `name`        | string   | **Yes**  | Human-readable name (1-256 chars)              |
+| `model`       | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. |
+| `system`      | string   | No       | System prompt — defines the agent's behavior (up to 100K chars) |
+| `tools`       | array    | No       | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. |
+| `mcp_servers` | array    | No       | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. |
+| `skills`      | array    | No       | Customized "best-practices" context with progressive disclosure. Max 20. See `shared/managed-agents-tools.md` → Skills. |
+| `description` | string   | No       | Description of the agent (up to 2048 chars)    |
+| `multiagent`  | object   | No       | `{type: "coordinator", agents: [...]}` — roster this agent may delegate to. See `shared/managed-agents-multiagent.md`. |
+| `metadata`    | object   | No       | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) |
+
+---
+
+## Agents
+
+**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.
+
+### Agent Object
+
+The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object.
+
+| Field              | Type     | Required | Description                                        |
+| ------------------ | -------- | -------- | -------------------------------------------------- |
+| `name`             | string   | Yes      | Human-readable name                                |
+| `model`            | string   | Yes      | Claude model ID                                    |
+| `system`           | string   | No       | System prompt                                      |
+| `tools`            | array    | No       | Agent toolset / MCP toolset / custom tools         |
+| `mcp_servers`      | array    | No       | MCP server connections                             |
+| `skills`           | array    | No       | Skill references (max 20)                          |
+| `description`      | string   | No       | Description of the agent                           |
+| `multiagent`       | object   | No       | Coordinator roster — see `shared/managed-agents-multiagent.md` |
+| `metadata`         | object   | No       | Arbitrary key-value pairs                          |
+
+### Lifecycle: create once, run many, update in place
+
+The agent is a **persistent resource**, not a per-run parameter. The intended pattern:
+
+```
+┌─ setup (once) ─────────┐     ┌─ runtime (every invocation) ─┐
+│ agents.create()        │     │ sessions.create(             │
+│   → store agent_id     │ ──→ │   agent={type:..., id: ID}   │
+│     in config/env/db   │     │ )                            │
+└────────────────────────┘     └──────────────────────────────┘
+```
+
+**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.
+
+### Versioning
+
+Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version.
+
+**Why version:**
+- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}`
+- **Safe iteration** — update the agent without breaking sessions already running on the old version
+- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug
+
+**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility.
+
+**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`.
+
+**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update.
+
+### Agent Endpoints
+
+| Operation        | Method   | Path                                  |
+| ---------------- | -------- | ------------------------------------- |
+| Create           | `POST`   | `/v1/agents`                          |
+| List             | `GET`    | `/v1/agents`                          |
+| Get              | `GET`    | `/v1/agents/{id}`                     |
+| Update           | `POST`   | `/v1/agents/{id}`                     |
+| Archive          | `POST`   | `/v1/agents/{id}/archive`             |
+
+> ⚠️ **Archive is permanent.** Archiving makes the agent read-only: existing sessions continue to run, but **new sessions cannot reference it**, and there is no unarchive. Since agents have no `delete`, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.
+
+### Using an Agent in a Session
+
+Reference the agent by string ID (latest version) or by object with an explicit version:
+
+```python
+# String shorthand — uses the agent's latest version
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=environment_id,
+)
+
+# Or pin to a specific version (int)
+session = client.beta.sessions.create(
+    agent={"type": "agent", "id": agent.id, "version": agent.version},
+    environment_id=environment_id,
+)
+```
+

cli-tool/components/skills/development/claude-api/shared/managed-agents-environments.md

@@ -0,0 +1,211 @@
+# Managed Agents — Environments & Resources
+
+## Environments
+
+Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.
+
+**Environment names must be unique.** Creating an environment with an existing name returns 409.
+
+### Networking
+
+| Network Policy                  | Description                                                   |
+| ------------------------------- | ------------------------------------------------------------- |
+| `unrestricted`                  | Full egress (except legal blocklist)                          |
+| `package_managers_and_custom`   | Package managers + custom `allowed_hosts`                      |
+
+```json
+{
+  "networking": {
+    "type": "package_managers_and_custom",
+    "allowed_hosts": ["api.example.com"]
+  }
+}
+```
+
+**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. Otherwise the container can't reach them and tools silently fail.
+
+### Creating an environment
+
+The SDK adds `managed-agents-2026-04-01` automatically. TypeScript:
+
+```ts
+const env = await client.beta.environments.create({
+  name: "my_env",
+  config: {
+    type: "cloud",
+    networking: { type: "unrestricted" },
+  },
+});
+```
+
+### Environment CRUD
+
+| Operation        | Method   | Path                                       | Notes |
+| ---------------- | -------- | ------------------------------------------ | ----- |
+| Create           | `POST`   | `/v1/environments`                         | |
+| List             | `GET`    | `/v1/environments`                         | Paginated (`limit`, `after_id`, `before_id`) |
+| Get              | `GET`    | `/v1/environments/{id}`                    | |
+| Update           | `POST`   | `/v1/environments/{id}`                    | Changes apply only to **new** containers; existing sessions keep their original config |
+| Delete           | `DELETE` | `/v1/environments/{id}`                    | Returns 204. |
+| Archive          | `POST`   | `/v1/environments/{id}/archive`            | Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — terminal state. |
+
+---
+
+## Resources
+
+Attach files, GitHub repositories, and memory stores to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported. For `type: "memory_store"` resources (persistent cross-session memory — max 8 per session), see `shared/managed-agents-memory.md`.
+
+### File Uploads (input — host → agent)
+
+Upload a file first via the Files API, then reference by `file_id` + `mount_path`:
+
+```ts
+// 1. Upload
+const file = await client.beta.files.upload({
+  file: fs.createReadStream("data.csv"),
+});
+
+// 2. Attach as a session resource
+const session = await client.beta.sessions.create({
+  agent: agent.id,
+  environment_id: envId,
+  resources: [
+    { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
+  ],
+});
+```
+
+**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths.
+
+### Session outputs (output — agent → host)
+
+The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:
+
+```ts
+// After the turn completes, list output files scoped to this session:
+for await (const f of client.beta.files.list({
+  scope_id: session.id,
+  betas: ["managed-agents-2026-04-01"],
+})) {
+  console.log(f.filename, f.size_bytes);
+  const resp = await client.beta.files.download(f.id);
+  const text = await resp.text();
+}
+```
+
+**Requirements:**
+- The `write` tool (or `bash`) must be enabled for the agent to create output files.
+- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`.
+- The filter parameter is **`scope_id`** (REST query param `?scope_id=<session_id>`). The SDK's files resource auto-adds only the `files-api-2025-04-14` header, so pass `betas: ["managed-agents-2026-04-01"]` explicitly (or both headers on raw HTTP) — without it the API may reject `scope_id` as an unknown field. Requires `@anthropic-ai/sdk` ≥ 0.88.0 / `anthropic` (Python) ≥ 0.92.0 — older versions don't type `scope_id`. The `ant` CLI does **not** expose this flag yet; use the SDK or curl.
+- Pass the session ID returned by `sessions.create()` verbatim (e.g. `sesn_011CZx...`) — the API validates the prefix.
+- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty.
+
+> **Fallback when `scope_id` filtering is unavailable** (older SDK, or endpoint returns an error): send a follow-up `user.message` asking the agent to `read` each file under `/mnt/session/outputs/` and return the contents. The agent streams the file bodies back as `agent.message` text. This works for text files only and costs output tokens — use it to unblock, not as the primary path.
+
+This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.
+
+### GitHub Repositories
+
+Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. Repositories are cached, so future sessions that use the same repository start faster.
+
+Repositories are attached for the lifetime of the session — to change which repositories are mounted, create a new session. You **can** rotate a repository's `authorization_token` on a running session via `client.beta.sessions.resources.update(resource_id, {session_id, authorization_token})`; the resource `id` is returned at session creation and by `resources.list()`.
+
+**Fields:**
+
+| Field | Required | Notes |
+|---|---|---|
+| `type` | ✅ | `"github_repository"` |
+| `url` | ✅ | The GitHub repository URL |
+| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
+| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
+| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. |
+
+**Token permission levels** (fine-grained PATs):
+- `Contents: Read` — clone only
+- `Contents: Read and write` — push changes and create pull requests
+
+**How auth works:** `authorization_token` is never placed inside the container. `git pull` / `git push` and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container — including anything the agent writes — cannot read or exfiltrate it.
+
+> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem + git access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` (authenticated via the git proxy using `authorization_token`) → create PR via the MCP `create_pull_request` tool (authenticated via the vault).
+
+**TypeScript:**
+
+```ts
+// 1. Create the agent — declare GitHub MCP (no auth here)
+const agent = await client.beta.agents.create(
+  {
+    name: 'GitHub Agent',
+    model: 'claude-opus-4-7',
+    mcp_servers: [
+      { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
+    ],
+    tools: [
+      { type: 'agent_toolset_20260401', default_config: { enabled: true } },
+      { type: 'mcp_toolset', mcp_server_name: 'github' },
+    ],
+  },
+);
+
+// 2. Start a session — attach vault for MCP auth + mount the repo
+const session = await client.beta.sessions.create({
+  agent: agent.id,
+  environment_id: envId,
+  vault_ids: [vaultId],  // vault contains the GitHub MCP OAuth credential
+  resources: [
+    {
+      type: 'github_repository',
+      url: 'https://github.com/owner/repo',
+      authorization_token: process.env.GITHUB_TOKEN,  // repo clone token (≠ MCP auth)
+      checkout: { type: 'branch', name: 'main' },
+    },
+  ],
+});
+```
+
+**Python:**
+
+```python
+import os
+
+agent = client.beta.agents.create(
+    name="GitHub Agent",
+    model="claude-opus-4-7",
+    mcp_servers=[{
+        "type": "url",
+        "name": "github",
+        "url": "https://api.githubcopilot.com/mcp/",
+    }],
+    tools=[
+        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
+        {"type": "mcp_toolset", "mcp_server_name": "github"},
+    ],
+)
+
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=env_id,
+    vault_ids=[vault_id],  # vault contains the GitHub MCP OAuth credential
+    resources=[{
+        "type": "github_repository",
+        "url": "https://github.com/owner/repo",
+        "authorization_token": os.environ["GITHUB_TOKEN"],  # repo clone token (≠ MCP auth)
+        "checkout": {"type": "branch", "name": "main"},
+    }],
+)
+```
+
+---
+
+## Files API
+
+Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`.
+
+| Operation        | Method   | Path                                  | SDK |
+| ---------------- | -------- | ------------------------------------- | --- |
+| Upload           | `POST`   | `/v1/files`                           | `client.beta.files.upload({ file })` |
+| List             | `GET`    | `/v1/files?scope_id=...`              | `client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] })` |
+| Get Metadata     | `GET`    | `/v1/files/{id}`                      | `client.beta.files.retrieveMetadata(id)` |
+| Download         | `GET`    | `/v1/files/{id}/content`              | `client.beta.files.download(id)` → `Response` |
+| Delete           | `DELETE` | `/v1/files/{id}`                      | `client.beta.files.delete(id)` |
+
+The `scope_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account.

cli-tool/components/skills/development/claude-api/shared/managed-agents-events.md

@@ -0,0 +1,195 @@
+# Managed Agents — Events & Steering
+
+## Events
+
+### Sending Events
+
+Send events to a session via `POST /v1/sessions/{id}/events`.
+
+| Event Type                | When to Send                                        |
+| ------------------------- | --------------------------------------------------- |
+| `user.message`            | Send a user message |
+| `user.interrupt`          | Interrupt the agent while it's running |
+| `user.tool_confirmation`  | Approve/deny a tool call (when `always_ask` policy) |
+| `user.custom_tool_result` | Provide result for a custom tool call |
+| `user.define_outcome`     | Start a rubric-graded iterate loop — see `shared/managed-agents-outcomes.md` |
+
+### Receiving Events
+
+Three methods:
+
+1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive.
+2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll.
+3. **Webhooks**: Anthropic POSTs session state transitions to your HTTPS endpoint — thin payloads (IDs only), HMAC-signed, Console-registered. See `shared/managed-agents-webhooks.md`.
+
+All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent).
+
+> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely.
+>
+> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem.
+
+### Event Types (Received)
+
+Event types use dot notation, grouped by namespace:
+
+| Event Type | Description |
+| --- | --- |
+| `agent.message` | Agent text output |
+| `agent.thinking` | Extended thinking blocks |
+| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) |
+| `agent.tool_result` | Result from a built-in tool |
+| `agent.mcp_tool_use` | Agent used an MCP tool |
+| `agent.mcp_tool_result` | Result from an MCP tool |
+| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` |
+| `agent.thread_context_compacted` | Conversation context was compacted |
+| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
+| `session.status_running` | Session has starting running, and the Agent is actively doing work. |
+| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
+| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state.  |
+| `session.error` | Error occurred during processing |
+| `span.model_request_start` | Model inference started |
+| `span.model_request_end` | Model inference completed |
+| `span.outcome_evaluation_start` / `_ongoing` / `_end` | Grader progress for outcome-oriented sessions — see `shared/managed-agents-outcomes.md` |
+| `session.thread_created` | Subagent thread spawned (multiagent) — see `shared/managed-agents-multiagent.md` |
+| `session.thread_status_running` / `_idle` / `_rescheduled` / `_terminated` | Subagent thread status transitions (multiagent). `_idle` carries `stop_reason`. |
+| `agent.thread_message_sent` / `_received` | Cross-thread message, carries `to_session_thread_id` / `from_session_thread_id` (multiagent) |
+
+The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`, `user.define_outcome`).
+
+---
+
+## Steering Patterns
+
+Practical patterns for driving a session via the events surface.
+
+### Stream-first ordering
+
+**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
+
+```ts
+// ✅ Correct — stream and send concurrently
+const [response] = await Promise.all([
+  streamEvents(sessionId),   // opens SSE connection
+  sendMessage(sessionId, text),
+]);
+
+// ❌ Wrong — events before stream opens arrive as a single buffered batch
+await sendMessage(sessionId, text);
+const response = await streamEvents(sessionId);
+```
+
+**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward.
+
+### Reconnecting after a dropped stream
+
+**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream.
+
+**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
+
+```python
+def connect_with_consolidation(client, session_id):
+    # 1. Open the SSE stream first
+    stream = client.beta.sessions.events.stream(session_id=session_id)
+
+    # 2. Fetch history to cover any gap
+    history = client.beta.sessions.events.list(
+        session_id=session_id,
+    )
+
+    # 3. Yield history first, then stream — dedupe by event.id
+    seen = set()
+    for ev in history.data:
+        seen.add(ev.id)
+        yield ev
+    for ev in stream:
+        if ev.id not in seen:
+            seen.add(ev.id)
+            yield ev
+```
+
+### Message queuing
+
+**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
+
+```ts
+// All three go into one session; agent processes them in order
+await sendMessage(sessionId, "Summarize the README");
+await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
+await sendMessage(sessionId, "And compare the two");
+// Stream once — agent responds to all three as a coherent turn
+```
+
+Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()`
+
+### Interrupt
+
+An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands:
+
+```ts
+await client.beta.sessions.events.send(sessionId, {
+  events: [{ type: 'interrupt' }],
+});
+```
+
+The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. If an outcome is active, the interrupt also marks `span.outcome_evaluation_end.result: "interrupted"` (see `shared/managed-agents-outcomes.md`).
+
+> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs.
+
+### Event payloads
+
+some events carry useful metadata beyond the status change itself:
+
+`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user.
+```json
+{
+  "id": "sevt_456",
+  "processed_at": "2026-04-07T04:27:43.197Z",
+  "stop_reason": {
+    "event_ids": [
+      "sevt_123"
+    ],
+    "type": "requires_action"
+  },
+  "type": "status_idle"
+}
+```
+
+`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis:
+
+```json
+{
+  "type": "span.model_request_end",
+  "id": "sevt_456",
+  "is_error": false,
+  "model_request_start_id": "sevt_123",
+  "model_usage": {
+    "cache_creation_input_tokens": 0,
+    "cache_read_input_tokens": 6656,
+    "input_tokens": 3571,
+    "output_tokens": 727
+  },
+  "processed_at": "2026-04-07T04:11:32.189Z"
+}
+```
+
+**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed:
+
+```json
+{
+  "id": "sevt_abc123",
+  "processed_at": "2026-03-24T14:05:15.787Z",
+  "type": "agent.thread_context_compacted"
+}
+```
+
+### Archive
+
+When done with a session, archive it to free resources:
+
+```ts
+await client.beta.sessions.archive(sessionId);
+```
+
+> Archiving a **session** is routine cleanup — sessions are per-run and disposable. **Do not generalize this to agents or environments**: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See `shared/managed-agents-overview.md` → Common Pitfalls.
+
+

cli-tool/components/skills/development/claude-api/shared/managed-agents-memory.md

@@ -0,0 +1,197 @@
+# Managed Agents — Memory Stores
+
+> **Public beta.** Memory stores ship under the `managed-agents-2026-04-01` beta header; the SDK sets it automatically on all `client.beta.memory_stores.*` calls. If `client.beta.memory_stores` is missing, upgrade to the latest SDK release.
+
+Sessions are ephemeral by default — when one ends, anything the agent learned is gone. A **memory store** is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via `resources[]`), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.
+
+Every mutation to a memory produces an immutable **memory version** (`memver_...`), giving you an audit trail and point-in-time rollback/redact.
+
+## Object model
+
+| Object | ID prefix | Scope | Notes |
+| --- | --- | --- | --- |
+| Memory store | `memstore_...` | Workspace | Attach to sessions via `resources[]` |
+| Memory | `mem_...` | Store | One text file, addressed by `path` (≤ 100KB each — prefer many small files) |
+| Memory version | `memver_...` | Memory | Immutable snapshot per mutation; `operation` ∈ `created` / `modified` / `deleted` |
+
+## Create a store
+
+`description` is passed to the agent so it knows what the store contains — write it for the model, not for humans.
+
+```python
+store = client.beta.memory_stores.create(
+    name="User Preferences",
+    description="Per-user preferences and project context.",
+)
+print(store.id)  # memstore_01Hx...
+```
+
+Other SDKs: TypeScript `client.beta.memoryStores.create({...})`; Go `client.Beta.MemoryStores.New(ctx, ...)`. See `shared/managed-agents-api-reference.md` → SDK Method Reference for the full per-language table.
+
+Stores support `retrieve` / `update` / `list` (with `include_archived`, `created_at_{gte,lte}` filters) / `delete` / **`archive`**. Archive makes the store read-only — existing session attachments continue, new sessions cannot reference it; no unarchive.
+
+### Seed with content (optional)
+
+Pre-load reference material before any session runs. `memories.create` creates a memory at the given `path`; if a memory already exists there the call returns `409` (`memory_path_conflict_error`, with the `conflicting_memory_id`). The store ID is the first positional argument.
+
+```python
+client.beta.memory_stores.memories.create(
+    store.id,
+    path="/formatting_standards.md",
+    content="All reports use GAAP formatting. Dates are ISO-8601...",
+)
+```
+
+## Attach to a session
+
+Memory stores go in the session's `resources[]` array alongside `file` and `github_repository` resources (see `shared/managed-agents-environments.md` → Resources). Memory stores attach at **session create time only** — `sessions.resources.add()` does not accept `memory_store`.
+
+```python
+session = client.beta.sessions.create(
+    agent=agent.id,
+    environment_id=environment.id,
+    resources=[
+        {
+            "type": "memory_store",
+            "memory_store_id": store.id,
+            "access": "read_write",  # or "read_only"; default is "read_write"
+            "instructions": "User preferences and project context. Check before starting any task.",
+        }
+    ],
+)
+```
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `type` | ✅ | `"memory_store"` |
+| `memory_store_id` | ✅ | `memstore_...` |
+| `access` | — | `"read_write"` (default) or `"read_only"` — enforced at the filesystem level on the mount |
+| `instructions` | — | Session-specific guidance for this store, in addition to the store's `name`/`description`. ≤ 4,096 chars. |
+
+**Max 8 memory stores per session.** Attach multiple when different slices of memory have different owners or lifecycles — e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.
+
+### How the agent sees it (FUSE mount)
+
+Each attached store is mounted in the session container at `/mnt/memory/<store-name>/`. The agent interacts with it using the standard file tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`) — there are no dedicated memory tools. `access: "read_only"` makes the mount read-only at the filesystem level; `"read_write"` allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, `instructions`, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.
+
+Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side `memories.update` calls.
+
+## Manage memories directly (host-side)
+
+Use these for review workflows, correcting bad memories, or seeding stores out-of-band.
+
+### List
+
+Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. `order_by` / `order` sort the result. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only.
+
+```python
+for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
+    if m.type == "memory":
+        print(f"{m.path}  ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
+    else:  # "memory_prefix"
+        print(f"{m.path}/")
+```
+
+### Read
+
+```python
+mem = client.beta.memory_stores.memories.retrieve(memory_id, memory_store_id=store.id)
+print(mem.content)
+```
+
+`retrieve` defaults to `view="full"` (content included); `view` matters mainly on list endpoints.
+
+### Create vs. update
+
+| Operation | Addressed by | Semantics |
+| --- | --- | --- |
+| `memories.create(store_id, path=..., content=...)` | **Path** | Create at `path`. `409` (`memory_path_conflict_error`, includes `conflicting_memory_id`) if the path is already occupied. |
+| `memories.update(mem_id, memory_store_id=..., path=..., content=...)` | **`mem_...` ID** | Mutate existing memory. Change `content`, `path` (rename), or both. Renaming onto an occupied path returns the same `409 memory_path_conflict_error`. |
+
+```python
+mem = client.beta.memory_stores.memories.create(
+    store.id,
+    path="/preferences/formatting.md",
+    content="Always use tabs, not spaces.",
+)
+
+client.beta.memory_stores.memories.update(
+    mem.id,
+    memory_store_id=store.id,
+    path="/archive/2026_q1_formatting.md",  # rename
+)
+```
+
+### Optimistic concurrency (precondition on `update`)
+
+`memories.update` accepts a `precondition` so you can read → modify → write back without clobbering a concurrent writer. The only supported type is `content_sha256`. On mismatch the API returns `409` (`memory_precondition_failed_error`) — re-read and retry against fresh state.
+
+```python
+client.beta.memory_stores.memories.update(
+    mem.id,
+    memory_store_id=store.id,
+    content="CORRECTED: Always use 2-space indentation.",
+    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
+)
+```
+
+### Delete
+
+```python
+client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)
+```
+
+Pass `expected_content_sha256` for a conditional delete.
+
+## Audit and rollback — memory versions
+
+Every mutation creates an immutable `memver_...` snapshot. Versions accumulate for the lifetime of the parent memory; `memories.retrieve` always returns the current head, the version endpoints give you history.
+
+| Operation that triggers it | `operation` field on the version |
+| --- | --- |
+| `memories.create` at a new path | `"created"` |
+| `memories.update` changing `content`, `path`, or both (or an agent-side write to the mount) | `"modified"` |
+| `memories.delete` | `"deleted"` |
+
+Each version also records `created_by` — an actor object with `type` ∈ `session_actor` / `api_actor` / `user_actor` — and, after redaction, `redacted_at` + `redacted_by`.
+
+### List versions
+
+Newest-first, paginated. Filter by `memory_id`, `operation`, `session_id`, `api_key_id`, or `created_at_gte` / `created_at_lte`. Pass `view="full"` to include `content`; default is metadata-only.
+
+```python
+for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
+    print(f"{v.id}: {v.operation}")
+```
+
+### Retrieve a version
+
+```python
+version = client.beta.memory_stores.memory_versions.retrieve(
+    version_id, memory_store_id=store.id
+)
+print(version.content)
+```
+
+### Redact a version
+
+Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears `content`, `content_sha256`, `content_size_bytes`, and `path`; everything else stays. Use for leaked secrets, PII, or user-deletion requests.
+
+```python
+client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)
+```
+
+## Endpoint reference
+
+See `shared/managed-agents-api-reference.md` → Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:
+
+```
+POST   /v1/memory_stores
+POST   /v1/memory_stores/{memory_store_id}/archive
+GET    /v1/memory_stores/{memory_store_id}/memories
+PATCH  /v1/memory_stores/{memory_store_id}/memories/{memory_id}
+GET    /v1/memory_stores/{memory_store_id}/memory_versions
+POST   /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact
+```
+
+For cURL examples and the CLI (`ant beta:memory-stores ...`), WebFetch the Memory URL in `shared/live-sources.md` → Managed Agents.

cli-tool/components/skills/development/claude-api/shared/managed-agents-multiagent.md

@@ -0,0 +1,99 @@
+# Managed Agents — Multiagent Sessions
+
+A coordinator agent can delegate to other agents within one session. All agents **share the container and filesystem**; each runs in its own **thread** — a context-isolated event stream with its own conversation history, model, system prompt, tools, MCP servers, and skills (from that agent's own config). Threads are persistent: the coordinator can send a follow-up to a subagent it called earlier and that subagent retains its prior turns.
+
+The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `client.beta.{agents,sessions}.*` calls; no additional header is required for multiagent.
+
+---
+
+## Declare the roster on the coordinator
+
+`multiagent` is a **top-level field** on `agents.create()` / `agents.update()` — **not** a `tools[]` entry. `agents` lists 1–20 roster entries. Nothing changes on `sessions.create()` — the roster is resolved from the coordinator's config.
+
+```python
+orchestrator = client.beta.agents.create(
+    name="Engineering Lead",
+    model="{{OPUS_ID}}",
+    system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.",
+    tools=[{"type": "agent_toolset_20260401"}],
+    multiagent={
+        "type": "coordinator",
+        "agents": [
+            reviewer.id,                                            # bare string — latest version
+            {"type": "agent", "id": test_writer.id, "version": 4},  # pinned version
+            {"type": "self"},                                       # the coordinator itself
+        ],
+    },
+)
+
+session = client.beta.sessions.create(agent=orchestrator.id, environment_id=env.id)
+```
+
+| Roster entry | Shape | Notes |
+|---|---|---|
+| String shorthand | `"agent_abc123"` | References the latest version of a stored agent. |
+| Agent reference | `{type: "agent", id, version?}` | Omit `version` to pin the latest at coordinator save time. |
+| Self | `{type: "self"}` | The coordinator can spawn copies of itself. |
+
+Up to **20 unique agents** in the roster; the coordinator may spawn **multiple copies** of each. **One level of delegation only** — depth > 1 is ignored.
+
+---
+
+## Threads
+
+The session-level event stream is the **primary thread** — it shows the coordinator's trace plus a condensed view of subagent activity (thread status transitions and cross-thread messages, not every subagent tool call). Drill into a specific subagent via the per-thread endpoints:
+
+| Operation | HTTP | SDK (`client.beta.sessions.threads.*`) |
+|---|---|---|
+| List threads | `GET /v1/sessions/{sid}/threads` | `.list(session_id)` |
+| Retrieve one | `GET /v1/sessions/{sid}/threads/{tid}` | `.retrieve(thread_id, session_id=...)` |
+| Archive | `POST /v1/sessions/{sid}/threads/{tid}/archive` | `.archive(thread_id, session_id=...)` |
+| List thread events | `GET /v1/sessions/{sid}/threads/{tid}/events` | `.events.list(thread_id, session_id=...)` |
+| Stream thread events | `GET /v1/sessions/{sid}/threads/{tid}/stream` | `.events.stream(thread_id, session_id=...)` |
+
+Each `SessionThread` carries `id`, `status` (`running` | `idle` | `rescheduling` | `terminated`), `agent` (a resolved snapshot of the agent config — `id`, `name`, `model`, `system`, `tools`, `skills`, `mcp_servers`, `version`), `parent_thread_id` (null for the primary thread, which is included in the list), `archived_at`, and optional `stats`/`usage`. **Session status aggregates thread statuses** — if any thread is `running`, `session.status` is `running`. Max **25 concurrent threads**. When draining a per-thread stream, break on `session.thread_status_idle` (and check its `stop_reason` as you would for the session-level idle).
+
+---
+
+## Multiagent events (on the session stream)
+
+| Event | Payload highlights | Meaning |
+|---|---|---|
+| `session.thread_created` | `session_thread_id`, `agent_name` | A new thread was created. |
+| `session.thread_status_running` | `session_thread_id`, `agent_name` | Thread started activity. |
+| `session.thread_status_idle` | `session_thread_id`, `agent_name`, **`stop_reason`** | Thread is awaiting input. Inspect `stop_reason` (same shape as `session.status_idle.stop_reason`). |
+| `session.thread_status_rescheduled` | `session_thread_id`, `agent_name` | Thread is rescheduling after a retryable error. |
+| `session.thread_status_terminated` | `session_thread_id`, `agent_name` | Thread was archived or hit a terminal error. |
+| `agent.thread_message_sent` | `to_session_thread_id`, `to_agent_name`, `content` | Coordinator sent a follow-up to another thread. |
+| `agent.thread_message_received` | `from_session_thread_id`, `from_agent_name`, `content` | An agent delivered its result to the coordinator. |
+
+---
+
+## Tool permissions and custom tools from subagent threads
+
+When a subagent needs your client (an `always_ask` confirmation, or a custom tool result), the request is **cross-posted to the primary thread** with `session_thread_id` identifying the originating thread — so you only need to watch the session stream. Reply with `user.tool_confirmation` (carrying `tool_use_id`) or `user.custom_tool_result` (carrying `custom_tool_use_id`), and **echo the `session_thread_id` from the originating event** (the SDK param type and docstring expect it). The server also routes by the tool-use ID, so the echo is belt-and-suspenders rather than load-bearing — but include it.
+
+```python
+for event_id in stop.event_ids:
+    pending = events_by_id[event_id]
+    confirmation = {
+        "type": "user.tool_confirmation",
+        "tool_use_id": event_id,
+        "result": "allow",
+    }
+    if pending.session_thread_id is not None:
+        confirmation["session_thread_id"] = pending.session_thread_id
+    client.beta.sessions.events.send(session.id, events=[confirmation])
+```
+
+The same pattern applies to `user.custom_tool_result`.
+
+---
+
+## Pitfalls
+
+- **Don't put the roster on `sessions.create()` or in `tools[]`.** `multiagent` is a top-level agent field; update the coordinator, then start a session that references it.
+- **Don't assume shared context.** Threads share the filesystem but not conversation history or tools. If the coordinator needs a subagent to act on something, it must say so in the delegated message (or write it to disk).
+- **Depth > 1 is ignored.** A subagent's own `multiagent` roster (if any) doesn't cascade — only the session's coordinator delegates.
+
+For per-language bindings beyond Python, WebFetch `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` (see `shared/live-sources.md`).

cli-tool/components/skills/development/claude-api/shared/managed-agents-onboarding.md

@@ -0,0 +1,114 @@
+# Managed Agents — Onboarding Flow
+
+> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.
+
+Use this when a user wants to set up a Managed Agent from scratch. Three steps: **branch on know-vs-explore → configure the template → set up the session**. End by emitting working code.
+
+> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference.
+
+---
+
+Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you.
+
+**What you supply:**
+- **An agent config** — tools, skills, model, system prompt. Reusable and versioned.
+- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents.
+
+Each run of the agent is a **session**.
+
+---
+
+## 1. Know or explore?
+
+Ask the user:
+
+> Do you already know the agent you want to build, or would you like to explore some common patterns first?
+
+### Explore path — show the patterns
+
+Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ.
+
+| Pattern | Trigger | Example |
+|---|---|---|
+| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack | # <------ MC maybe delete?
+| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack | # <------ MC maybe delete?
+| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI |
+| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard |
+
+Ask which shape fits, then continue with the Know path using it as the reference.
+
+### Know path — configure template
+
+Three rounds. Batch the questions in each round; don't ask them one at a time.
+
+**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination):
+
+| Type | What it is | How to guide |
+|---|---|---|
+| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. |
+| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. |
+| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. |
+
+**Round B — Skills, files, and repos.** What the agent has on hand when it starts.
+
+*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 20 per agent.
+- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name.
+- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API.
+
+*GitHub repositories* — any repos the agent needs on-disk? For each:
+- [ ] Repo URL (`https://github.com/org/repo`)
+- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo)
+- [ ] Optional `mount_path` (defaults to `/workspace/<repo-name>`) and `checkout` (branch or SHA)
+
+Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories.
+
+> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool.
+
+*Files* — any local files to seed the session with? For each:
+- [ ] Upload via the Files API → persist `file_id`
+- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only)
+
+Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API.
+
+**Round C — Environment + identity:**
+- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.)
+- [ ] Name?
+- [ ] Job (one or two sentences — becomes the system prompt)?
+- [ ] Model? (default `claude-opus-4-7`)
+
+---
+
+## 2. Set up the session
+
+Per-run. Points at the agent + environment, attaches credentials, kicks off.
+
+**Vault credentials** (if the agent declared MCP servers):
+- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`)
+
+Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See `shared/managed-agents-tools.md` → Vaults.
+
+**Kickoff:**
+- [ ] First message to the agent?
+
+Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope_id: session.id, betas: ["managed-agents-2026-04-01"]})`.
+
+---
+
+## 3. Emit the code
+
+Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks** per language detected (Python/TS/cURL — see SKILL.md → Language Detection):
+
+**Block 1 — Setup (run once, store the IDs):**
+1. `environments.create()` → persist `env_id`
+2. `agents.create()` with everything from §Round A–C → persist `agent_id` and `agent_version`
+
+Label: `# ONE-TIME SETUP — run once, save the IDs to config/.env`
+
+**Block 2 — Runtime (run on every invocation):**
+1. Load `env_id` + `agent_id` from config/env
+2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])`
+3. Open stream, `events.send()` the kickoff, loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`)
+
+> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`.
+
+Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names.

cli-tool/components/skills/development/claude-api/shared/managed-agents-outcomes.md

@@ -0,0 +1,106 @@
+# Managed Agents — Outcomes
+
+An **outcome** elevates a session from *conversation* to *work*: you state what "done" looks like, and the harness runs an iterate → grade → revise loop until the artifact meets the rubric, hits `max_iterations`, or is interrupted. A separate **grader** (independent context window) scores each iteration against your rubric and feeds per-criterion gaps back to the agent.
+
+The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `client.beta.sessions.*` calls; no additional header is required for outcomes.
+
+---
+
+## The `user.define_outcome` event
+
+Outcomes are not a field on `sessions.create()`. You create a normal session, then send a `user.define_outcome` event. The agent starts working on receipt — **do not also send a `user.message`** to kick it off.
+
+```python
+session = client.beta.sessions.create(
+    agent=AGENT_ID,
+    environment_id=ENVIRONMENT_ID,
+    title="Financial analysis on Costco",
+)
+
+client.beta.sessions.events.send(
+    session_id=session.id,
+    events=[
+        {
+            "type": "user.define_outcome",
+            "description": "Build a DCF model for Costco in .xlsx",
+            "rubric": {"type": "text", "content": RUBRIC_MD},
+            # or: "rubric": {"type": "file", "file_id": rubric.id}
+            "max_iterations": 5,  # optional; default 3, max 20
+        }
+    ],
+)
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | `"user.define_outcome"` | |
+| `description` | string | The task. This is what the agent works toward — no separate `user.message` needed. |
+| `rubric` | `{type: "text", content}` \| `{type: "file", file_id}` | **Required.** Markdown with explicit, independently gradeable criteria. Upload once via `client.beta.files.upload(...)` (beta `files-api-2025-04-14`) to reuse across sessions. |
+| `max_iterations` | int | Optional. Default **3**, max **20**. |
+
+The event is echoed back on the stream with a server-assigned `outcome_id` and `processed_at`.
+
+> **Writing rubrics.** Use explicit, gradeable criteria ("CSV has a numeric `price` column"), not vibes ("data looks good") — the grader scores each criterion independently, so vague criteria produce noisy loops. If you don't have a rubric, have Claude analyze a known-good artifact and turn that analysis into one.
+
+---
+
+## Outcome-specific events
+
+These appear on the standard event stream (`sessions.events.stream` / `.list`) alongside the usual `agent.*` / `session.*` events.
+
+| Event | Payload highlights | Meaning |
+|---|---|---|
+| `span.outcome_evaluation_start` | `outcome_id`, `iteration` (0-indexed) | Grader began scoring iteration *N*. |
+| `span.outcome_evaluation_ongoing` | `outcome_id` | Heartbeat while the grader runs. Grader reasoning is opaque — you see *that* it's working, not *what* it's thinking. |
+| `span.outcome_evaluation_end` | `outcome_evaluation_start_id`, `outcome_id`, `iteration`, `result`, `explanation`, `usage` | Grader finished one iteration. `result` drives what happens next (table below). |
+
+### `span.outcome_evaluation_end.result`
+
+| `result` | Next |
+|---|---|
+| `satisfied` | Session → `idle`. Terminal for this outcome. |
+| `needs_revision` | Agent starts another iteration. |
+| `max_iterations_reached` | No further grader cycles. Agent may run one final revision, then session → `idle`. |
+| `failed` | Session → `idle`. Rubric fundamentally doesn't match the task (e.g. description and rubric contradict). |
+| `interrupted` | Only emitted if `_start` had already fired before a `user.interrupt` arrived. |
+
+```json
+{
+  "type": "span.outcome_evaluation_end",
+  "id": "sevt_01jkl...",
+  "outcome_evaluation_start_id": "sevt_01def...",
+  "outcome_id": "outc_01a...",
+  "result": "satisfied",
+  "explanation": "All 12 criteria met: revenue projections use 5 years of historical data, ...",
+  "iteration": 0,
+  "usage": { "input_tokens": 2400, "output_tokens": 350, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 1800 },
+  "processed_at": "2026-03-25T14:03:00Z"
+}
+```
+
+---
+
+## Checking status & retrieving deliverables
+
+**Status** — either watch the stream for `span.outcome_evaluation_end`, or poll the session and read `outcome_evaluations`:
+
+```python
+session = client.beta.sessions.retrieve(session.id)
+for ev in session.outcome_evaluations:
+    print(f"{ev.outcome_id}: {ev.result}")  # outc_01a...: satisfied
+```
+
+**Deliverables** — the agent writes to `/mnt/session/outputs/`. Once idle, fetch via the Files API with `scope_id=session.id`. This is the same session-outputs mechanism documented in `shared/managed-agents-environments.md` → Session outputs (including the dual-beta-header requirement on `files.list`).
+
+---
+
+## Interaction rules & pitfalls
+
+- **One outcome at a time.** Chain by sending the next `user.define_outcome` only after the previous one's terminal `span.outcome_evaluation_end` (`satisfied` / `max_iterations_reached` / `failed` / `interrupted`). The session retains history across chained outcomes.
+- **Steering is allowed but optional.** You *may* send `user.message` events mid-outcome to nudge direction, but the agent already knows to keep working until terminal — don't send "keep going" prompts.
+- **`user.interrupt` pauses the current outcome** — it marks `result: "interrupted"` and leaves the session `idle`, ready for a new outcome or conversational turn.
+- **After terminal, the session is reusable** — continue conversationally or define a new outcome.
+- **Outcome ≠ session-create field.** Don't put `outcome`, `rubric`, or `description` on `sessions.create()` — outcomes are always sent as a `user.define_outcome` event.
+- **Idle-break gate is unchanged.** In your drain loop, keep using `event.type === 'session.status_idle' && event.stop_reason?.type !== 'requires_action'` — do **not** gate on `span.outcome_evaluation_end` alone (on `needs_revision` the session keeps running). See `shared/managed-agents-client-patterns.md` Pattern 5.
+
+For the raw HTTP shapes and per-language SDK bindings beyond Python, WebFetch `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` (see `shared/live-sources.md`).

cli-tool/components/skills/development/claude-api/shared/managed-agents-overview.md

@@ -0,0 +1,67 @@
+# Managed Agents — Overview
+
+Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in.
+
+## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)
+
+**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run.
+
+Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs.
+
+| Step | Call | Frequency |
+|---|---|---|
+| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. |
+| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. |
+
+If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only.
+
+**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`.
+
+**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning.
+
+## Beta Headers
+
+Managed Agents is in beta. The SDK sets required beta headers automatically:
+
+| Beta Header                    | What it enables                                      |
+| ------------------------------ | ---------------------------------------------------- |
+| `managed-agents-2026-04-01`    | Agents, Environments, Sessions, Events, Session Resources, Session Threads, Outcomes, Multiagent, Vaults, Credentials, Memory Stores |
+| `skills-2025-10-02`            | Skills API (for managing custom skill definitions)   |
+| `files-api-2025-04-14`         | Files API for file uploads                           |
+
+**Which beta header goes where:** The SDK sets `managed-agents-2026-04-01` automatically on `client.beta.{agents,environments,sessions,vaults,memory_stores}.*` calls, and `files-api-2025-04-14` / `skills-2025-10-02` automatically on `client.beta.files.*` / `client.beta.skills.*` calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. **Exception — session-scoped file listing:** `client.beta.files.list({scope_id: session.id})` is a Files endpoint that takes a Managed Agents parameter, so it needs **both** headers. Pass `betas: ["managed-agents-2026-04-01"]` explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See `shared/managed-agents-environments.md` → Session outputs.
+
+
+## Reading Guide
+
+| User wants to...                       | Read these files                                        |
+| -------------------------------------- | ------------------------------------------------------- |
+| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code |
+| Understand how the API works           | `shared/managed-agents-core.md`                         |
+| See the full endpoint reference        | `shared/managed-agents-api-reference.md`                |
+| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file |
+| Update/version an agent                | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create |
+| Create a session                       | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` |
+| Configure tools and permissions        | `shared/managed-agents-tools.md`                        |
+| Set up MCP servers                     | `shared/managed-agents-tools.md` (MCP Servers section)  |
+| Stream events / handle tool_use        | `shared/managed-agents-events.md` + language file       |
+| Get notified of session state changes via webhook (no polling) | `shared/managed-agents-webhooks.md` — Console-registered endpoint, HMAC verify, thin payload + fetch |
+| Define an outcome / rubric-graded iterate loop | `shared/managed-agents-outcomes.md` — `user.define_outcome` event, grader, `span.outcome_evaluation_*` events |
+| Coordinate multiple agents / subagents / threads | `shared/managed-agents-multiagent.md` — `multiagent: {type: "coordinator", agents: [...]}` on the agent, session threads, cross-posted tool confirmations |
+| Set up environments                    | `shared/managed-agents-environments.md` + language file |
+| Upload files / attach repos            | `shared/managed-agents-environments.md` (Resources)     |
+| Give agents persistent memory across sessions | `shared/managed-agents-memory.md` — memory stores, `memory_store` session resource, preconditions, versions/redact |
+| Store MCP credentials                  | `shared/managed-agents-tools.md` (Vaults section)       |
+| Call a non-MCP API / CLI that needs a secret | `shared/managed-agents-client-patterns.md` Pattern 9 — no container env vars; vaults are MCP-only; keep the secret host-side via a custom tool |
+
+## Common Pitfalls
+
+- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example.
+- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility.
+- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token.
+- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time.
+- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream.
+- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events.
+- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message.
+- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type.
+- **Archive is permanent on every resource** — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent, environment, or memory store as cleanup — **always confirm with the user before archiving**.

cli-tool/components/skills/development/claude-api/shared/managed-agents-tools.md

@@ -0,0 +1,315 @@
+# Managed Agents — Tools & Skills
+
+## Tools
+
+### Server tools vs client tools
+
+| Type | Who runs it | How it works |
+|---|---|---|
+| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Anthropic, on the session's container | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. |
+| **MCP tools** (`mcp_toolset`) | Anthropic, on the session's container | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. |
+| **Custom tools** | **You** — your application handles the call and returns results | Agent emits a `agent.custom_tool_use` event, session goes `idle`, you send back a `user.custom_tool_result` event. |
+
+**Recommendation:** Enable all prebuilt tools via `agent_toolset_20260401`, then disable individually as needed.
+
+**Versioning:** The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence `_20260401`) so you always know exactly what you're getting.
+
+### Agent Toolset
+
+The `agent_toolset_20260401` provides these built-in tools:
+
+| Tool                   | Description                              |
+| ---------------------- | ---------------------------------------- |
+| `bash` | Execute bash commands in a shell session |
+| `read` | Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks |
+| `write` | Write a file to the local filesystem |
+| `edit` | Perform string replacement in a file |
+| `glob` | Fast file pattern matching using glob patterns |
+| `grep` | Text search using regex patterns |
+| `web_fetch` | Fetch content from a URL |
+| `web_search` | Search the web for information |
+
+Enable the full toolset:
+
+```json
+{
+  "tools": [
+    { "type": "agent_toolset_20260401" }
+  ]
+}
+```
+
+### Per-Tool Configuration
+
+Override defaults for individual tools. This example enables everything except bash:
+
+```json
+{
+  "tools": [
+    {
+      "type": "agent_toolset_20260401",
+      "default_config": { "enabled": true },
+      "configs": [
+        { "name": "bash", "enabled": false }
+      ]
+    }
+  ]
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `type` | ✅ | `"agent_toolset_20260401"` |
+| `default_config` | ❌ | Applied to all tools. `{ "enabled": bool, "permission_policy": {...} }` |
+| `configs` | ❌ | Per-tool overrides: `[{ "name": "...", "enabled": bool, "permission_policy": {...} }]` |
+
+### Permission Policies
+
+Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools.
+
+| Policy | Behavior |
+|---|---|
+| `always_allow` | Tool executes automatically (default) |
+| `always_ask` | Session emits `session.status_idle` and pauses until you send a `tool_confirmation` event |
+
+```json
+{
+  "type": "agent_toolset_20260401",
+  "default_config": {
+    "enabled": true,
+    "permission_policy": { "type": "always_allow" }
+  },
+  "configs": [
+    { "name": "bash", "permission_policy": { "type": "always_ask" } }
+  ]
+}
+```
+
+**Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event:
+
+```json
+{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
+{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
+```
+
+The optional `message` on a deny is delivered to the agent so it can adjust its approach.
+
+To enable only specific tools, flip the default off and opt-in per tool:
+
+```json
+{
+  "tools": [
+    {
+      "type": "agent_toolset_20260401",
+      "default_config": { "enabled": false },
+      "configs": [
+        { "name": "bash", "enabled": true },
+        { "name": "read", "enabled": true }
+      ]
+    }
+  ]
+}
+```
+
+### Custom Tools (Client-Side)
+
+Custom tools are executed by **your application**, not Anthropic. The flow:
+
+1. Agent decides to use the tool → session emits a `agent.custom_tool_use` event with inputs
+2. Session goes `idle` waiting for you
+3. Your application executes the tool
+4. You send back a `user.custom_tool_result` event with the output
+5. Session resumes `running`
+
+No permission policy needed — you're the one executing.
+
+```json
+{
+  "tools": [
+    {
+      "type": "custom",
+      "name": "get_weather",
+      "description": "Fetch current weather for a city.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "city": { "type": "string", "description": "City name" }
+        },
+        "required": ["city"]
+      }
+    }
+  ]
+}
+```
+
+### MCP Servers
+
+MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). **Configuration is split across agent and vault:**
+
+1. **Agent creation** declares which servers to connect to (`type`, `name`, `url` — no auth). The agent's `mcp_servers` array has no auth field.
+2. **Vault** stores the OAuth credentials. Attach via `vault_ids` on session create.
+
+This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL.
+
+**Agent side — declare servers (no auth):**
+
+| Field | Required | Description |
+|---|---|---|
+| `type` | ✅ | `"url"` |
+| `name` | ✅ | Unique name — referenced by `mcp_toolset.mcp_server_name` |
+| `url` | ✅ | The MCP server's endpoint URL (Streamable HTTP transport) |
+
+```json
+{
+  "mcp_servers": [
+    { "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" }
+  ],
+  "tools": [
+    { "type": "mcp_toolset", "mcp_server_name": "linear" }
+  ]
+}
+```
+
+**Session side — attach vault:**
+
+```json
+{
+  "agent": "agent_abc123",
+  "environment_id": "env_abc123",
+  "vault_ids": ["vlt_abc123"]
+}
+```
+
+> 💡 **Per-tool enablement (empirical):** `mcp_toolset` has been observed accepting `default_config: {enabled: false}` + `configs: [{name, enabled: true}]` for an allowlist pattern. The API ref shows only the minimal `{type, mcp_server_name}` form.
+
+> ⚠️ **MCP auth tokens ≠ REST API tokens.** Hosted MCP servers (`mcp.notion.com`, `mcp.linear.app`, etc.) typically require **OAuth bearer tokens**, not the service's native API keys. A Notion `ntn_` integration token authenticates against Notion's REST API but will **not** work as a vault credential for the Notion MCP server. These are different auth systems.
+
+### Vaults — the MCP credential store
+
+**Vaults** store OAuth credentials (access token + refresh token) that Anthropic auto-refreshes on your behalf via standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers in the launch SDK.
+
+#### Credentials and the sandbox
+
+Vaults store credentials; those credentials **never enter the sandbox**. This is a deliberate security boundary — code running in the sandbox (including anything the agent writes) cannot read or exfiltrate a vaulted credential, even under prompt injection. Instead, credentials are injected by Anthropic-side proxies **after** a request leaves the sandbox:
+
+- **MCP tool calls** are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
+- **Git operations on attached GitHub repositories** (`git pull`, `git push`, GitHub REST calls) are routed through a git proxy that injects the `github_repository` resource's `authorization_token` the same way.
+
+**Not yet supported:** running other authenticated CLIs (e.g. `aws`, `gcloud`, `stripe`) directly inside the sandbox. There is currently no way to set container environment variables or expose vault credentials to arbitrary processes. If you need one of these today:
+
+- **Prefer an MCP server** for that service if one exists — it gets the same vault-backed injection.
+- **Otherwise, register a custom tool:** the agent emits `agent.custom_tool_use`, your orchestrator (which already holds the credential) executes the call and returns `user.custom_tool_result` over the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. See `shared/managed-agents-client-patterns.md` → Pattern 9.
+
+**Do not put API keys in the system prompt or user messages as a workaround** — they persist in the session's event history.
+
+> Formerly known internally as TATs (Tool/Tenant Access Tokens).
+
+**Flow:**
+
+1. Create a vault (`client.beta.vaults.create(...)`) — one per tenant/user, or one shared, depending on your model
+2. Add MCP credentials to it (`client.beta.vaults.credentials.create(...)`) — each credential is tied to one MCP server URL
+3. Reference the vault on session create via `vault_ids: ["vlt_..."]`
+4. Anthropic auto-refreshes tokens before they expire; the agent uses the current access token when calling MCP tools
+
+**Credential shape**:
+
+```json
+{
+  "display_name": "Notion (workspace-foo)",
+  "auth": {
+    "type": "mcp_oauth",
+    "mcp_server_url": "https://mcp.notion.com/mcp",
+    "access_token": "<current access token>",
+    "expires_at": "2026-04-02T14:00:00Z",
+    "refresh": {
+      "refresh_token": "<refresh token>",
+      "client_id": "<your OAuth client_id>",
+      "token_endpoint": "https://api.notion.com/v1/oauth/token",
+      "token_endpoint_auth": { "type": "none" }
+    }
+  }
+}
+```
+
+The `refresh` block is what enables auto-refresh — `token_endpoint` is where Anthropic posts the `refresh_token` grant. `token_endpoint_auth` is a discriminated union:
+
+| `type` | Shape | Use when |
+|---|---|---|
+| `"none"` | `{type: "none"}` | Public OAuth client (no secret) |
+| `"client_secret_basic"` | `{type: "client_secret_basic", client_secret: "..."}` | Confidential client, secret via HTTP Basic auth |
+| `"client_secret_post"` | `{type: "client_secret_post", client_secret: "..."}` | Confidential client, secret in request body |
+
+Omit `refresh` entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access.
+
+> 💡 **Getting an OAuth token.** How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the `refresh.token_endpoint` from there.
+
+**Scoping:** Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. `vault_ids` can be set at session **create** time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected").
+
+---
+
+## Skills
+
+Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
+
+Two types — both work the same way; the agent automatically uses them when relevant to the task at hand:
+
+| Type | What it is |
+|---|---|
+| **Pre-built Anthropic skills** | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. `xlsx`). |
+| **Custom skills** | Skills you've created in your organization via the Skills API. Reference by `skill_id` + optional `version`. |
+
+**Max 20 skills per agent.** Agent creation uses `managed-agents-2026-04-01`; the separate Skills API (for managing custom skill definitions) uses `skills-2025-10-02`.
+
+### Enabling skills on a session
+
+Skills are attached to the **agent** definition via `agents.create()`:
+
+```ts
+const agent = await client.beta.agents.create(
+  {
+    name: "Financial Agent",
+    model: "claude-opus-4-7",
+    system: "You are a financial analysis agent.",
+    skills: [
+      { type: "anthropic", skill_id: "xlsx" },
+      { type: "custom", skill_id: "skill_abc123", version: "latest" },
+    ],
+  }
+);
+```
+
+Python:
+
+```python
+agent = client.beta.agents.create(
+    name="Financial Agent",
+    model="claude-opus-4-7",
+    system="You are a financial analysis agent.",
+    skills=[
+        {"type": "anthropic", "skill_id": "xlsx"},
+        {"type": "custom", "skill_id": "skill_abc123", "version": "latest"},
+    ]
+)
+```
+
+**Skill reference fields:**
+
+| Field | Anthropic skill | Custom skill |
+|---|---|---|
+| `type` | `"anthropic"` | `"custom"` |
+| `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) |
+| `version` | — | `"latest"` or a specific version number |
+
+### Skills API
+
+| Operation             | Method   | Path                                            |
+| --------------------- | -------- | ----------------------------------------------- |
+| Create Skill          | `POST`   | `/v1/skills`                                    |
+| List Skills           | `GET`    | `/v1/skills`                                    |
+| Get Skill             | `GET`    | `/v1/skills/{id}`                               |
+| Delete Skill          | `DELETE` | `/v1/skills/{id}`                               |
+| Create Version        | `POST`   | `/v1/skills/{id}/versions`                      |
+| List Versions         | `GET`    | `/v1/skills/{id}/versions`                      |
+| Get Version           | `GET`    | `/v1/skills/{id}/versions/{version}`            |
+| Delete Version        | `DELETE` | `/v1/skills/{id}/versions/{version}`            |
+

cli-tool/components/skills/development/claude-api/shared/managed-agents-webhooks.md

@@ -0,0 +1,110 @@
+# Managed Agents — Webhooks
+
+Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are **thin** (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.
+
+> **Direction matters.** This page covers *Anthropic → you* notifications about session/vault state. It does **not** cover *third-party → you* webhooks that *trigger* a session (e.g. a GitHub push handler that calls `sessions.create()`) — that's ordinary application code on your side with no Anthropic-specific wire format.
+
+---
+
+## Register an endpoint (Console only)
+
+Console → **Manage → Webhooks**. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.
+
+| Field | Constraint |
+|---|---|
+| URL | HTTPS on port 443, publicly resolvable hostname |
+| Event types | Subscribe per `data.type` — you only receive subscribed types (plus test events) |
+| Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |
+
+---
+
+## Verify the signature
+
+Every delivery is HMAC-signed. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`.
+
+```python
+import anthropic
+from flask import Flask, request
+
+client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
+app = Flask(__name__)
+
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        event = client.beta.webhooks.unwrap(
+            request.get_data(as_text=True),
+            headers=dict(request.headers),
+        )
+    except Exception:
+        return "invalid signature", 400
+
+    if event.id in seen_event_ids:  # dedupe retries — id is per-event, not per-delivery
+        return "", 204
+    seen_event_ids.add(event.id)
+
+    match event.data.type:
+        case "session.status_idled":
+            session = client.beta.sessions.retrieve(event.data.id)
+            notify_user(session)
+        case "vault_credential.refresh_failed":
+            alert_oncall(event.data.id)
+
+    return "", 204
+```
+
+Pass the **raw request body** to `unwrap()` — frameworks that re-serialize JSON (Express `.json()`, Flask `.get_json()`) change the bytes and break the MAC. For other languages, look up the `beta.webhooks.unwrap` binding in the SDK repo (`shared/live-sources.md`); don't hand-roll verification.
+
+---
+
+## Payload envelope
+
+```json
+{
+  "type": "event",
+  "id": "event_01ABC...",
+  "created_at": "2026-03-18T14:05:22Z",
+  "data": {
+    "type": "session.status_idled",
+    "id": "session_01XYZ...",
+    "organization_id": "8a3d2f1e-...",
+    "workspace_id": "c7b0e4d9-..."
+  }
+}
+```
+
+Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to acknowledge. `created_at` is when the *state transition* happened, not when the webhook fired.
+
+---
+
+## Supported `data.type` values
+
+| `data.type` | Fires when |
+|---|---|
+| `session.status_scheduled` | Session created and ready to accept events |
+| `session.status_run_started` | Agent execution kicked off (every transition to `running`) |
+| `session.status_idled` | Agent awaiting input (tool approval, custom tool result, or next message) |
+| `session.status_terminated` | Session hit a terminal error |
+| `session.thread_created` | Multiagent: coordinator opened a new subagent thread |
+| `session.thread_idled` | Multiagent: a subagent thread is waiting for input |
+| `session.outcome_evaluation_ended` | Outcome grader finished one iteration |
+| `vault.archived` | Vault was archived |
+| `vault.created` | Vault was created |
+| `vault.deleted` | Vault was deleted |
+| `vault_credential.archived` | Vault credential was archived |
+| `vault_credential.created` | Vault credential was created |
+| `vault_credential.deleted` | Vault credential was deleted |
+| `vault_credential.refresh_failed` | MCP OAuth vault credential failed to refresh |
+
+> These are **webhook** `data.type` values — a separate namespace from SSE event types (`session.status_idle`, `span.outcome_evaluation_end`, etc. in `shared/managed-agents-events.md`). Don't reuse SSE constants in webhook handlers.
+
+---
+
+## Delivery behavior & pitfalls
+
+- **No ordering guarantee.** `session.status_idled` may arrive before `session.outcome_evaluation_ended` even if the evaluation finished first. Sort by envelope `created_at` if order matters.
+- **Retries carry the same `event.id`.** At least one retry on non-2xx. Dedupe on `event.id`.
+- **3xx is failure.** Redirects are not followed — update the URL in Console if your endpoint moves.
+- **Auto-disable** after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
+- **Thin payload is intentional.** Don't expect `stop_reason`, `outcome_evaluations`, credential secrets, etc. on the webhook body — fetch the resource.

cli-tool/components/skills/development/claude-api/shared/model-migration.md

@@ -0,0 +1,779 @@
+# Model Migration Guide
+
+How to move existing code to newer Claude models. Covers breaking changes, deprecated parameters, and drop-in replacements for retired models.
+
+For the latest, authoritative version (with code samples in every supported language), WebFetch the **Migration Guide** URL from `shared/live-sources.md`. Use this file for the consolidated, skill-resident reference; fall back to the live docs whenever a model launch or breaking change may have shifted the picture.
+
+**This file is large.** Use the section names below to jump (or `Grep` this file for the heading text). Read Step 0 and Step 1 first — they apply to every migration. Then read only the per-target section for the model you are migrating to.
+
+| Section | When you need it |
+|---|---|
+| Step 0: Confirm the migration scope | Always — before any edits |
+| Step 1: Classify each file | Always — decides whether to swap, add-alongside, or skip |
+| Per-SDK Syntax Reference | Translate the Python examples in this guide to TypeScript / Go / Ruby / Java / C# / PHP |
+| Destination Models / Retired Model Replacements | Picking a target model |
+| Breaking Changes by Source Model | Migrating to Opus 4.6 / Sonnet 4.6 |
+| Migrating to Opus 4.7 | Migrating to Opus 4.7 (breaking changes, silent defaults, behavioral shifts) |
+| Opus 4.7 Migration Checklist | The required vs optional items for 4.7, tagged `[BLOCKS]` / `[TUNE]` |
+| Verify the Migration | After edits — runtime spot-check |
+
+**TL;DR:** Change the model ID string. If you were using `budget_tokens`, switch to `thinking: {type: "adaptive"}`. If you were using assistant prefills, they 400 on both Opus 4.6 and Sonnet 4.6 — switch to one of the prefill replacements (most often `output_config.format`; see the table in Breaking Changes by Source Model). If you're moving from Sonnet 4.5 to Sonnet 4.6, set `effort` explicitly — 4.6 defaults to `high`. Remove the `effort-2025-11-24` and `fine-grained-tool-streaming-2025-05-14` beta headers (GA on 4.6); remove `interleaved-thinking-2025-05-14` once you're on adaptive thinking (keep it only while using the transitional `budget_tokens` escape hatch). Then drop back from `client.beta.messages.create` to `client.messages.create`. Dial back any aggressive "CRITICAL: YOU MUST" tool instructions; 4.6 follows the system prompt much more closely.
+
+---
+
+## Step 0: Confirm the migration scope
+
+**Before any Write, Edit, or MultiEdit call, confirm the scope.** If the user's request does not explicitly name a single file, a specific directory, or an explicit file list, **ask first — do not start editing**. This is non-negotiable: even imperative-sounding requests like "migrate my codebase", "move my project to X", "upgrade to Sonnet 4.6", or bare "migrate to Opus 4.7" leave the scope ambiguous and require a clarifying question. Phrases like "my project", "my code", "my codebase", "the whole thing", "everywhere", or "across the repo" are **ambiguous, not directive** — they tell you *what* to do but not *where*. Ask before doing.
+
+Offer the common scopes explicitly and wait for the answer before touching any file:
+
+1. The entire working directory
+2. A specific subdirectory (e.g. `src/`, `app/`, `services/billing/`)
+3. A specific file or a list of files
+
+Surface this as a single clarifying question so the user can answer in one turn. **Proceed without asking only when the scope is already unambiguous** — the user named an exact file ("migrate `extract.py` to Sonnet 4.6"), pointed at a specific directory ("migrate everything under `services/billing/` to Opus 4.6"), listed specific files ("update `a.py` and `b.py`"), or already answered the scope question in an earlier turn. If you can answer the question "which files is this change going to touch?" with a precise list from the prompt alone, proceed. If not, ask.
+
+**Worked example.** If the user says *"Move my project to Opus 4.6. I want adaptive thinking everywhere it makes sense."* you do not know whether "my project" means the whole working directory, just `src/`, just the production code, or something else — the `everywhere` makes the intent clear (update every call site *within scope*) but the scope itself is still not defined. Do not start editing. Respond with:
+
+> Before I start editing, can you confirm the scope? I can migrate:
+> 1. Every `.py` file in the working directory
+> 2. Just the files under `src/` (production code)
+> 3. A specific subdirectory or list of files you name
+>
+> Which one?
+
+Then wait for the answer. The same applies to *"Migrate to Opus 4.7"* and bare *"Help me upgrade to Sonnet 4.6"* — ask before editing.
+
+**Sizing the scope question (large repos).** Before asking, get a per-directory count so the user can pick concretely:
+
+```sh
+rg -l "<old-model-id>" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn
+```
+
+Present the breakdown in your scope question (e.g. *"Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"*). Also confirm `git status` is clean before surveying — unexpected modifications mean a concurrent process; stop and investigate before proceeding.
+
+---
+
+## Step 1: Classify each file
+
+Not every file that contains the old model ID is a **caller** of the API. Before editing, classify each file into one of these buckets — the right action differs:
+
+| # | Bucket | What it looks like | Action |
+|---|---|---|---|
+| 1 | **Calls the API/SDK** | `client.messages.create(model=…)`, `anthropic.Anthropic()`, request payloads | Swap the model ID **and** apply the breaking-change checklist for the target version (below). |
+| 2 | **Defines or serves the model** | Model registries, OpenAPI specs, routing/queue configs, model-policy enums, generated catalogs | The old entry **stays** (the model is still served). Ask whether to (a) add the new model alongside, (b) leave alone, or (c) retire the old model — never blind-replace. **If you can't ask, default to (a): add the new model alongside and flag it** — replacing would de-register a model that's still in production. |
+| 3 | **References the ID as an opaque string** | UI fallback constants, capability-gate substring checks, generic test fixtures, label parsers, env defaults | Usually swap the string and verify any parser/regex/substring match handles the new ID — but check the sub-cases below first. |
+| 4 | **Suffixed variant ID** | `claude-<model>-<suffix>` like `-fast`, `-1024k`, `-200k`, `[1m]`, dated snapshots | These are deployment/routing identifiers, not the public model ID. **Do not assume a new-model equivalent exists.** Verify in the registry first; if absent, leave the string alone and flag it. |
+
+**Bucket 3 sub-cases — before swapping a string reference, check:**
+
+- **Capability gate** (e.g. `if 'opus-4-6' in model_id:` enables a feature) → **add the new ID alongside**, don't replace. The old model is still served and still has the capability, so replacing would silently disable the feature for any old-model traffic that still flows through. If you know no old-model traffic will hit this gate (single-caller codebase fully migrating), replacing is fine; if unsure, add alongside.
+- **Registry-assert test** (e.g. `assert "claude-X" in supported_models`, `test_X_has_N_clusters`) → **add an assertion for the new model alongside; keep the old one.** The old model is still served, so its assertion stays valid — but the registry should also include the new model, so assert that too. Heuristic: if the test references multiple model versions in a list, it's a registry test; if one model in a struct compared only to itself, it's a generic fixture.
+- **Frozen / generated snapshot** → **regenerate**, don't hand-edit.
+- **Coupled to a definer** (e.g. an integration test that passes model authorization via a shared `conftest` seed list, or asserts on a billing-tier / rate-limit-group enum or a generated SKU/pricing catalog) → **verify the definer has a new-model entry first.** If not, add a seed entry (reusing the nearest existing tier as a placeholder); if you can't confidently do that, ask the user how to populate the definer. **Do not skip the test.** Swapping without populating the definer will make the test fail at runtime.
+
+When migrating tests specifically: breaking parameters (`temperature`, `top_p`, `budget_tokens`) are usually absent — test fixtures rarely set sampling params on placeholder models. The breaking-change scan is still required, but expect mostly clean results.
+
+**Find intentionally-flagged sync points first.** Many codebases tag spots that must change at every model launch with comment markers like `MODEL LAUNCH`, `KEEP IN SYNC`, `@model-update`, or similar. Grep for whatever convention the repo uses *before* the broad model-ID grep — those markers point at the load-bearing changes.
+
+---
+
+## Per-SDK Syntax Reference
+
+Code examples in this guide are Python. **The same fields exist in every official Anthropic SDK** — Stainless generates all 7 from the same OpenAPI spec, so JSON field names map 1:1 with only case-convention differences. Use the rows below to translate the Python examples to the SDK you are migrating.
+
+> **Verify type and method names against the SDK source before writing them into customer code.** WebFetch the relevant repository from the SDK source-code table in `shared/live-sources.md` (one row per SDK) and confirm the exact symbol — particularly for typed SDKs (Go, Java, C#) where union/builder names can differ from the JSON shape. Do not guess type names that aren't in the table below or in `<lang>/claude-api/README.md`.
+
+
+### `thinking` — `budget_tokens` → adaptive
+
+| SDK | Before | After |
+|---|---|---|
+| Python | `thinking={"type": "enabled", "budget_tokens": N}` | `thinking={"type": "adaptive"}` |
+| TypeScript | `thinking: { type: 'enabled', budget_tokens: N }` | `thinking: { type: 'adaptive' }` |
+| Go | `Thinking: anthropic.ThinkingConfigParamOfEnabled(N)` | `Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{}}` |
+| Ruby | `thinking: { type: "enabled", budget_tokens: N }` | `thinking: { type: "adaptive" }` |
+| Java | `.thinking(ThinkingConfigEnabled.builder().budgetTokens(N).build())` | `.thinking(ThinkingConfigAdaptive.builder().build())` |
+| C# | `Thinking = new ThinkingConfigEnabled { BudgetTokens = N }` | `Thinking = new ThinkingConfigAdaptive()` |
+| PHP | `thinking: ['type' => 'enabled', 'budget_tokens' => N]` | `thinking: ['type' => 'adaptive']` |
+
+### Sampling parameters — `temperature` / `top_p` / `top_k`
+
+(Remove the field entirely on Opus 4.7; on Claude 4.x keep at most one of `temperature` or `top_p`.)
+
+| SDK | Field(s) to remove |
+|---|---|
+| Python | `temperature=…`, `top_p=…`, `top_k=…` |
+| TypeScript | `temperature: …`, `top_p: …`, `top_k: …` |
+| Go | `Temperature: anthropic.Float(…)`, `TopP: anthropic.Float(…)`, `TopK: anthropic.Int(…)` |
+| Ruby | `temperature: …`, `top_p: …`, `top_k: …` |
+| Java | `.temperature(…)`, `.topP(…)`, `.topK(…)` |
+| C# | `Temperature = …`, `TopP = …`, `TopK = …` |
+| PHP | `temperature: …`, `topP: …`, `topK: …` |
+
+### Prefill replacement — structured outputs via `output_config.format`
+
+| SDK | Remove (last assistant turn) | Add |
+|---|---|---|
+| Python | `{"role": "assistant", "content": "…"}` | `output_config={"format": {"type": "json_schema", "schema": SCHEMA}}` |
+| TypeScript | `{ role: 'assistant', content: '…' }` | `output_config: { format: { type: 'json_schema', schema: SCHEMA } }` |
+| Go | trailing `anthropic.MessageParam{Role: "assistant", …}` | `OutputConfig: anthropic.OutputConfigParam{Format: anthropic.JSONOutputFormatParam{…}}` |
+| Ruby | `{ role: "assistant", content: "…" }` | `output_config: { format: { type: "json_schema", schema: SCHEMA } }` |
+| Java | trailing `Message.builder().role(ASSISTANT)…` | `.outputConfig(OutputConfig.builder().format(JsonOutputFormat.builder()…build()).build())` |
+| C# | trailing `new Message { Role = "assistant", … }` | `OutputConfig = new OutputConfig { Format = new JsonOutputFormat { … } }` |
+| PHP | trailing `['role' => 'assistant', 'content' => '…']` | `outputConfig: ['format' => ['type' => 'json_schema', 'schema' => $SCHEMA]]` |
+
+### `thinking.display` — opt back into summarized reasoning (Opus 4.7)
+
+| SDK | Add |
+|---|---|
+| Python | `thinking={"type": "adaptive", "display": "summarized"}` |
+| TypeScript | `thinking: { type: 'adaptive', display: 'summarized' }` |
+| Go | `Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized}}` |
+| Ruby | `thinking: { type: "adaptive", display: "summarized" }` (or `display_:` when constructing the model class directly) |
+| Java | `.thinking(ThinkingConfigAdaptive.builder().display(ThinkingConfigAdaptive.Display.SUMMARIZED).build())` |
+| C# | `Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }` |
+| PHP | `thinking: ['type' => 'adaptive', 'display' => 'summarized']` |
+
+For any field not in these tables, the JSON key in the Python example translates directly: `snake_case` for Python/TypeScript/Ruby, `camelCase` named args for PHP, `PascalCase` struct fields for Go/C#, `camelCase` builder methods for Java.
+
+---
+
+## Explain every change you make
+
+Migration edits often look arbitrary to a user who hasn't read the release notes — a removed `temperature`, a deleted prefill, a rewritten system-prompt sentence. **For each edit, tell the user what you changed and why**, tied to the specific API or behavioral change that motivates it. Do this in your summary as you work, not just at the end.
+
+Be especially explicit about **system-prompt edits**. Users are rightly protective of their prompts, and prompt-tuning changes are judgment calls (not hard API requirements). For any prompt edit:
+
+- Quote the before and after text.
+- State the behavioral shift that motivates it (e.g. *"Opus 4.7 calibrates response length to task complexity, so I added an explicit length instruction"*, or *"4.6 follows instructions more literally, so 'CRITICAL: YOU MUST use the search tool' will now overtrigger — softened to 'Use the search tool when…'"*).
+- Make clear which prompt edits are **optional tuning** (tone, length, subagent guidance) versus which code edits are **required to avoid a 400** (sampling params, `budget_tokens`, prefills). Never present an optional prompt change as mandatory.
+
+If you're applying several prompt-tuning edits at once, offer them as a short list the user can accept or decline item-by-item rather than silently rewriting their system prompt.
+
+---
+
+## Before You Migrate
+
+1. **Confirm the target model ID.** Use only the exact strings from `shared/models.md` — do not append date suffixes to aliases (`claude-opus-4-6`, not `claude-opus-4-6-20251101`). Guessing an ID will 404.
+2. **Check which features your code uses** with this checklist:
+   - `thinking: {type: "enabled", budget_tokens: N}` → migrate to adaptive thinking on Opus 4.6 / Sonnet 4.6 (still functional but deprecated)
+   - Assistant-turn prefills (`messages` ending with `role: "assistant"`) → must change on Opus 4.6 / Sonnet 4.6 (returns 400)
+   - `output_format` parameter on `messages.create()` → must change on all models (deprecated API-wide)
+   - `max_tokens > ~16000` → must stream on any model (above ~16K risks SDK HTTP timeouts). When streaming, Sonnet 4.6 / Haiku 4.5 cap at 64K and Opus 4.6 caps at 128K
+   - Beta headers `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14` → GA on 4.6, remove them and switch from `client.beta.messages.create` to `client.messages.create`
+   - Moving Sonnet 4.5 → Sonnet 4.6 with no `effort` set → 4.6 defaults to `high`, which may change your latency/cost profile
+   - System prompts with `CRITICAL`, `MUST`, `If in doubt, use X` language → likely to overtrigger on 4.6 (see Prompt-Behavior Changes)
+   - Coming from 3.x / 4.0 / 4.1: also check sampling params (`temperature` + `top_p`), tool versions (`text_editor_20250728`), `refusal` + `model_context_window_exceeded` stop reasons, trailing-newline tool-param handling
+3. **Test on a single request first.** Run one call against the new model, inspect the response, then roll out.
+
+---
+
+## Destination Models (recommended targets)
+
+| If you're on…                         | Migrate to         | Why                                               |
+| ------------------------------------- | ------------------ | ------------------------------------------------- |
+| Opus 4.6                              | `claude-opus-4-7`  | Most capable model; adaptive thinking only; high-res vision; see Migrating to Opus 4.7 |
+| Opus 4.0 / 4.1 / 4.5 / Opus 3         | `claude-opus-4-6`  | Most intelligent 4.x before 4.7; adaptive thinking; 128K output |
+| Sonnet 4.0 / 4.5 / 3.7 / 3.5          | `claude-sonnet-4-6`| Best speed / intelligence balance; adaptive thinking; 64K output |
+| Haiku 3 / 3.5                         | `claude-haiku-4-5` | Fastest and most cost-effective                   |
+
+Default to the latest Opus for the caller's tier unless they explicitly chose otherwise. If you're moving from Opus 4.5 or older directly to Opus 4.7, apply the 4.6 migration first, then layer the Opus 4.7 changes on top (see Migrating to Opus 4.7 below).
+
+---
+
+## Retired Model Replacements
+
+These models return 404 — update immediately:
+
+| Retired model                 | Retired       | Drop-in replacement  |
+| ----------------------------- | ------------- | -------------------- |
+| `claude-3-7-sonnet-20250219`  | Feb 19, 2026  | `claude-sonnet-4-6`  |
+| `claude-3-5-haiku-20241022`   | Feb 19, 2026  | `claude-haiku-4-5`   |
+| `claude-3-opus-20240229`      | Jan 5, 2026   | `claude-opus-4-7`    |
+| `claude-3-5-sonnet-20241022`  | Oct 28, 2025  | `claude-sonnet-4-6`  |
+| `claude-3-5-sonnet-20240620`  | Oct 28, 2025  | `claude-sonnet-4-6`  |
+| `claude-3-sonnet-20240229`    | Jul 21, 2025  | `claude-sonnet-4-6`  |
+| `claude-2.1`, `claude-2.0`    | Jul 21, 2025  | `claude-sonnet-4-6`  |
+
+## Deprecated Models (retiring soon)
+
+| Model                         | Retires       | Replacement          |
+| ----------------------------- | ------------- | -------------------- |
+| `claude-3-haiku-20240307`     | Apr 19, 2026  | `claude-haiku-4-5`   |
+| `claude-opus-4-20250514`      | June 15, 2026 | `claude-opus-4-7`    |
+| `claude-sonnet-4-20250514`    | June 15, 2026 | `claude-sonnet-4-6`  |
+
+---
+
+## Breaking Changes by Source Model
+
+### Migrating from Sonnet 4.5 to Sonnet 4.6 (effort default change)
+
+Sonnet 4.5 had no `effort` parameter; Sonnet 4.6 defaults to `high`. If you just switch the model string and do nothing else, you may see noticeably higher latency and token usage. Set `effort` explicitly.
+
+**Recommended starting points:**
+
+| Workload                                          | Start at       | Notes                                                                                                    |
+| ------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
+| Chat, classification, content generation          | `low`          | With `thinking: {"type": "disabled"}` you'll see similar or better performance vs. Sonnet 4.5 no-thinking |
+| Most applications (balanced)                      | `medium`       | The default sweet spot for quality vs. cost                                                              |
+| Agentic coding, tool-heavy workflows              | `medium`       | Pair with adaptive thinking and a generous `max_tokens` (up to 64K with streaming — Sonnet 4.6's ceiling) |
+| Autonomous multi-step agents, long-horizon loops  | `high`         | Scale down to `medium` if latency/tokens become a concern                                                 |
+| Computer-use agents                               | `high` + adaptive | Sonnet 4.6's best computer-use accuracy is on adaptive + high                                          |
+
+For non-thinking chat workloads specifically:
+
+```python
+client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=8192,
+    thinking={"type": "disabled"},
+    output_config={"effort": "low"},
+    messages=[{"role": "user", "content": "..."}],
+)
+```
+
+**When to use Opus 4.6 instead:** hardest and longest-horizon problems — large code migrations, deep research, extended autonomous work. Sonnet 4.6 wins on fast turnaround and cost efficiency.
+
+### Migrating to Opus 4.6 / Sonnet 4.6 (from any older model)
+
+**1. Manual extended thinking is deprecated — use adaptive thinking.**
+
+`thinking: {type: "enabled", budget_tokens: N}` (manual extended thinking with a fixed token budget) is deprecated on Opus 4.6 and Sonnet 4.6. Replace it with `thinking: {type: "adaptive"}`, which lets Claude decide when and how much to think. Adaptive thinking also enables interleaved thinking automatically (no beta header needed).
+
+```python
+# Old (still works on older models, deprecated on 4.6)
+response = client.messages.create(
+    model="claude-sonnet-4-5",
+    max_tokens=16000,
+    thinking={"type": "enabled", "budget_tokens": 8000},
+    messages=[...]
+)
+
+# New (Opus 4.6 / Sonnet 4.6)
+response = client.messages.create(
+    model="claude-opus-4-6",  # or "claude-sonnet-4-6"
+    max_tokens=16000,
+    thinking={"type": "adaptive"},
+    output_config={"effort": "high"},  # optional: low | medium | high | max
+    messages=[...]
+)
+```
+
+Adaptive thinking is the long-term target, and on internal evaluations it outperforms manual extended thinking. Move when you can.
+
+**Transitional escape hatch:** manual extended thinking is still *functional* on Opus 4.6 and Sonnet 4.6 (deprecated, will be removed in a future release). If you need a hard ceiling while migrating — for example, to bound token spend on a runaway workload before you've tuned `effort` — you can keep `budget_tokens` around alongside an explicit `effort` value, then remove it in a follow-up. `budget_tokens` must be strictly less than `max_tokens`:
+
+```python
+# Transitional only — deprecated, plan to remove
+client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=16384,
+    thinking={"type": "enabled", "budget_tokens": 8192},  # must be < max_tokens
+    output_config={"effort": "medium"},
+    messages=[...],
+)
+```
+
+If the user asks for a "thinking budget" on 4.6, the preferred answer is `effort` — use `low`, `medium`, `high`, or `max` (Opus-tier only — not Sonnet or Haiku) rather than a token count.
+
+**2. Effort parameter (Opus 4.5, Opus 4.6, Sonnet 4.6 only).**
+
+Controls thinking depth and overall token spend. Goes inside `output_config`, not top-level. Default is `high`. `max` is Opus-tier only (Opus 4.6 and later — not Sonnet or Haiku). Errors on Sonnet 4.5 and Haiku 4.5.
+
+```python
+output_config={"effort": "medium"}  # often the best cost / quality balance
+```
+
+### Migrating to the 4.6 family (Opus 4.6 and Sonnet 4.6)
+
+**3. Assistant-turn prefills return 400 (Opus 4.6 and Sonnet 4.6).**
+
+Prefilled responses on the final assistant turn are no longer supported on either Opus 4.6 or Sonnet 4.6 — both return a 400. Adding assistant messages *elsewhere* in the conversation (e.g., for few-shot examples) still works. Pick the replacement that matches what the prefill was doing:
+
+| Prefill was used for                               | Replacement                                                                                                                               |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Forcing JSON / YAML / schema output                | `output_config.format` with a `json_schema` — see example below                                                                           |
+| Forcing a classification label                     | Tool with an enum field containing valid labels, or structured outputs                                                                    |
+| Skipping preambles (`Here is the summary:\n`)      | System prompt instruction: *"Respond directly without preamble. Do not start with phrases like 'Here is...' or 'Based on...'."*           |
+| Steering around bad refusals                       | Usually no longer needed — 4.6 refuses far more appropriately. Plain user-turn prompting is sufficient.                                   |
+| Continuing an interrupted response                 | Move continuation into the user turn: *"Your previous response was interrupted and ended with `[last text]`. Continue from there."*     |
+| Injecting reminders / context hydration            | Inject into the user turn instead. For complex agent harnesses, expose context via a tool call or during compaction.                      |
+
+```python
+# Old (fails on Opus 4.6 / Sonnet 4.6) — prefill forcing JSON shape
+messages=[
+    {"role": "user", "content": "Extract the name."},
+    {"role": "assistant", "content": "{\"name\": \""},
+]
+
+# New — structured outputs replace the prefill
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    output_config={"format": {"type": "json_schema", "schema": {...}}},
+    messages=[{"role": "user", "content": "Extract the name."}],
+)
+```
+
+**4. Stream for `max_tokens > ~16K` (all models); Opus 4.6 alone reaches 128K.**
+
+Non-streaming requests hit SDK HTTP timeouts at high `max_tokens`, regardless of model — stream for anything above ~16K output. The streamable ceiling differs by model: Sonnet 4.6 and Haiku 4.5 cap at 64K, and Opus 4.6 alone goes up to 128K.
+
+```python
+with client.messages.stream(model="claude-opus-4-6", max_tokens=64000, ...) as stream:
+    message = stream.get_final_message()
+```
+
+**5. Tool-call JSON escaping may differ (Opus 4.6 and Sonnet 4.6).**
+
+Both 4.6 models can produce tool call `input` fields with Unicode or forward-slash escaping. Always parse with `json.loads()` / `JSON.parse()` — never raw-string-match the serialized input.
+
+### All models
+
+**6. `output_format` → `output_config.format` (API-wide).**
+
+The old top-level `output_format` parameter on `messages.create()` is deprecated. Use `output_config.format` instead. This is not 4.6-specific — applies to every model.
+
+---
+
+## Beta Headers to Remove on 4.6
+
+Several beta headers that were required on 4.5 are now GA on 4.6 and should be removed. Leaving them in is harmless but misleading; removing them also lets you move from `client.beta.messages.create(...)` back to `client.messages.create(...)`.
+
+| Header                                    | Status on 4.6                                              | Action                                                  |
+| ----------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `effort-2025-11-24`                       | Effort parameter is GA                                     | Remove                                                  |
+| `fine-grained-tool-streaming-2025-05-14`  | GA                                                         | Remove                                                  |
+| `interleaved-thinking-2025-05-14`         | Adaptive thinking enables interleaved thinking automatically | Remove when using adaptive thinking; still functional on Sonnet 4.6 *with* manual extended thinking, but that path is deprecated |
+| `token-efficient-tools-2025-02-19`        | Built in to all Claude 4+ models                           | Remove (no effect)                                      |
+| `output-128k-2025-02-19`                  | Built in to Claude 4+ models                               | Remove (no effect)                                      |
+
+Once you remove all of these and finish moving to adaptive thinking, you can switch the SDK call site from the beta namespace back to the regular one:
+
+```python
+# Before
+response = client.beta.messages.create(
+    model="claude-opus-4-5",
+    betas=["interleaved-thinking-2025-05-14", "effort-2025-11-24"],
+    ...
+)
+
+# After
+response = client.messages.create(
+    model="claude-opus-4-6",
+    thinking={"type": "adaptive"},
+    output_config={"effort": "high"},
+    ...
+)
+```
+
+---
+
+## Additional Changes When Coming from 3.x / 4.0 / 4.1 → 4.6
+
+If you're jumping from Opus 4.1, Sonnet 4, Sonnet 3.7, or an older Claude 3.x model directly to 4.6, apply everything above *plus* the items in this section. Users already on Opus 4.5 / Sonnet 4.5 can skip this.
+
+**1. Sampling parameters: `temperature` OR `top_p`, not both.**
+
+Passing both will error on every Claude 4+ model:
+
+```python
+# Old (3.x only — errors on 4+)
+client.messages.create(temperature=0.7, top_p=0.9, ...)
+
+# New
+client.messages.create(temperature=0.7, ...)  # or top_p, not both
+```
+
+**2. Update tool versions.**
+
+Legacy tool versions are not supported on 4+. **Both the `type` and the `name` field change** — `text_editor_20250728` and `str_replace_based_edit_tool` are a pair; updating one without the other 400s. Also remove the `undo_edit` command from your text-editor integration:
+
+| Old                                               | New                                                     |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| `text_editor_20250124` + `str_replace_editor`     | `text_editor_20250728` + `str_replace_based_edit_tool`  |
+| `code_execution_*` (earlier versions)             | `code_execution_20250825`                               |
+| `undo_edit` command                               | *(no longer supported — delete call sites)*             |
+
+```python
+# Before
+tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
+
+# After — BOTH fields change
+tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
+```
+
+**3. Handle the `refusal` stop reason.**
+
+Claude 4+ can return `stop_reason: "refusal"` on the response. If your code only handles `end_turn` / `tool_use` / `max_tokens`, add a branch:
+
+```python
+if response.stop_reason == "refusal":
+    # Surface the refusal to the user; do not retry with the same prompt
+    ...
+```
+
+**4. Handle the `model_context_window_exceeded` stop reason (4.5+).**
+
+Distinct from `max_tokens`: it means the model hit the *context window* limit, not the requested output cap. Handle both:
+
+```python
+if response.stop_reason == "model_context_window_exceeded":
+    # Context window exhausted — compact or split the conversation
+    ...
+elif response.stop_reason == "max_tokens":
+    # Requested output cap hit — retry with higher max_tokens or stream
+    ...
+```
+
+**5. Trailing newlines preserved in tool call string parameters (4.5+).**
+
+4.5 and 4.6 preserve trailing newlines that older models stripped. If your tool implementations do exact string matching against tool-call `input` values (e.g., `if name == "foo"`), verify they still match when the model sends `"foo\n"`. Normalizing with `.rstrip()` on the receiving side is usually the simplest fix.
+
+**6. Haiku: rate limits reset between generations.**
+
+Haiku 4.5 has its own rate-limit pool separate from Haiku 3 / 3.5. If you're ramping traffic as you migrate, check your tier's Haiku 4.5 limits at [API rate limits](https://platform.claude.com/docs/en/api/rate-limits) — a quota that comfortably served Haiku 3.5 traffic may need a tier bump for the same volume on 4.5.
+
+---
+
+## Prompt-Behavior Changes (Opus 4.5 / 4.6, Sonnet 4.6)
+
+These don't break your code, but prompts that worked on 4.5-and-earlier may over- or under-trigger on 4.6. Tune as needed.
+
+**1. Aggressive instructions cause overtriggering.** Opus 4.5 and 4.6 follow the system prompt much more closely than earlier models. Prompts written to *overcome* the old reluctance are now too aggressive:
+
+| Before (worked on 4.0 / 4.5)                | After (use on 4.6)                        |
+| ------------------------------------------- | ----------------------------------------- |
+| `CRITICAL: You MUST use this tool when...`  | `Use this tool when...`                   |
+| `Default to using [tool]`                   | `Use [tool] when it would improve X`      |
+| `If in doubt, use [tool]`                   | *(delete — no longer needed)*             |
+
+If the model is now overtriggering a tool or skill, the fix is almost always to dial back the language, not to add more guardrails.
+
+**2. Overthinking and excessive exploration (Opus 4.6).** At higher `effort` settings, Opus 4.6 explores more before answering. If that burns too many thinking tokens, lower `effort` first (`medium` is often the sweet spot) before adding prose instructions to constrain reasoning.
+
+**3. Overeager subagent spawning (Opus 4.6).** Opus 4.6 has a strong preference for delegating to subagents. If you see it spawning a subagent for something a direct `grep` or `read` would solve, add guidance: *"Use subagents only for parallel or independent workstreams. For single-file reads or sequential operations, work directly."*
+
+**4. Overengineering (Opus 4.5 / 4.6).** Both models may add extra files, abstractions, or defensive error handling beyond what was asked. If you want minimal changes, prompt for it explicitly: *"Only make changes directly requested. Don't add helpers, abstractions, or error handling for scenarios that can't happen."*
+
+**5. LaTeX math output (Opus 4.6).** Opus 4.6 defaults to LaTeX (`\frac{}{}`, `$...$`) for math and technical content. If you need plain text, instruct it explicitly: *"Format all math as plain text — no LaTeX, no `$`, no `\frac{}{}`. Use `/` for division and `^` for exponents."*
+
+**6. Skipped verbal summaries (4.6 family).** The 4.6 models are more concise and may skip the summary paragraph after a tool call, jumping straight to the next action. If you rely on those summaries for visibility, add: *"After completing a task that involves tool use, provide a brief summary of what you did."*
+
+**7. "Think" as a trigger word (Opus 4.5 with thinking disabled).** When `thinking` is off, Opus 4.5 is particularly sensitive to the word *think* and may reason more than you want. Use `consider`, `evaluate`, or `reason through` instead.
+
+---
+
+## Model-ID Rename Quick Reference
+
+| Old string (migration source)  | New string         |
+| ------------------------------ | ------------------ |
+| `claude-opus-4-6`              | `claude-opus-4-7`  |
+| `claude-opus-4-5`              | `claude-opus-4-7`  |
+| `claude-opus-4-1`              | `claude-opus-4-7`  |
+| `claude-opus-4-0`              | `claude-opus-4-7`  |
+| `claude-sonnet-4-5`            | `claude-sonnet-4-6`|
+| `claude-sonnet-4-0`            | `claude-sonnet-4-6`|
+
+Older aliases (`claude-opus-4-5`, `claude-sonnet-4-5`, `claude-opus-4-1`, etc.) are still active and can be pinned if you need time before upgrading — see `shared/models.md` for the full legacy list.
+
+---
+
+## Migration Checklist
+
+Every item is tagged: **`[BLOCKS]`** items cause a 400 error, infinite loop, silent timeout, or wrong tool selection if missed — apply these as code edits, not as suggestions. **`[TUNE]`** items are quality/cost adjustments.
+
+For each file that calls `messages.create()` / equivalent SDK method:
+
+- [ ] **[BLOCKS]** Update the `model=` string to the new alias
+- [ ] **[BLOCKS]** Replace `budget_tokens` with `thinking={"type": "adaptive"}` (deprecated on Opus 4.6 / Sonnet 4.6)
+- [ ] **[BLOCKS]** Move `format` from top-level `output_format` into `output_config.format`
+- [ ] **[BLOCKS]** Remove any assistant-turn prefills if targeting Opus 4.6 or Sonnet 4.6 (see the prefill replacement table)
+- [ ] **[BLOCKS]** Switch to streaming if `max_tokens > ~16000` (otherwise SDK HTTP timeout)
+- [ ] **[TUNE]** Set `output_config={"effort": "..."}` explicitly — especially when moving Sonnet 4.5 → Sonnet 4.6 (4.6 defaults to `high`)
+- [ ] **[TUNE]** Remove GA beta headers: `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `token-efficient-tools-2025-02-19`, `output-128k-2025-02-19`; remove `interleaved-thinking-2025-05-14` once on adaptive thinking
+- [ ] **[TUNE]** Switch `client.beta.messages.create(...)` → `client.messages.create(...)` once all betas are removed
+- [ ] **[TUNE]** Review system prompt for aggressive tool language (`CRITICAL:`, `MUST`, `If in doubt`) and dial it back
+
+**Extra items when coming from 3.x / 4.0 / 4.1:**
+- [ ] **[BLOCKS]** Remove either `temperature` or `top_p` (passing both 400s on Claude 4+)
+- [ ] **[BLOCKS]** Update text-editor tool `type` to `text_editor_20250728`
+- [ ] **[BLOCKS]** Update text-editor tool `name` to `str_replace_based_edit_tool` — **changing only the `type` and keeping `name: "str_replace_editor"` returns a 400**
+- [ ] **[BLOCKS]** Update code-execution tool to `code_execution_20250825`
+- [ ] **[BLOCKS]** Delete any `undo_edit` command call sites
+- [ ] **[TUNE]** Add handling for `stop_reason == "refusal"`
+- [ ] **[TUNE]** Add handling for `stop_reason == "model_context_window_exceeded"` (4.5+)
+- [ ] **[TUNE]** Verify tool-param string matching tolerates trailing newlines (preserved on 4.5+)
+- [ ] **[TUNE]** If moving to Haiku 4.5: review rate-limit tier (separate pool from Haiku 3.x)
+
+**Verification:**
+- [ ] Run one test request and inspect `response.stop_reason`, `response.usage`, and whether tool-use / thinking behavior matches expectations
+
+For cached prompts: the render order and hash inputs did not change, so existing `cache_control` breakpoints keep working. However, **changing the model string invalidates the existing cache** — the first request on the new model will write the cache fresh.
+
+---
+
+## Migrating to Opus 4.7
+
+> **Model ID `claude-opus-4-7` is authoritative as written here.** When the user asks to migrate to Opus 4.7, write `model="claude-opus-4-7"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`.
+
+Claude Opus 4.7 is our most capable generally available model to date. It is highly autonomous and performs exceptionally well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks. This section summarizes everything new at launch. It is layered on top of the 4.6 migration above — if the caller is jumping from Opus 4.5 or older, apply the 4.6 changes first, then apply this section.
+
+**TL;DR for someone already on Opus 4.6:** update the model ID to `claude-opus-4-7`, strip any remaining `budget_tokens` and sampling parameters (both 400 on Opus 4.7), give `max_tokens` extra headroom and re-baseline with `count_tokens()` against the new model, opt back into `thinking.display: "summarized"` if reasoning is surfaced to users, and re-tune `effort` — it matters more on 4.7 than on any prior Opus.
+
+### Breaking changes (will 400 on Opus 4.7)
+
+**Extended thinking removed.**
+
+`thinking: {type: "enabled", budget_tokens: N}` is no longer supported on Claude Opus 4.7 or later models and returns a 400 error. Switch to adaptive thinking (`thinking: {type: "adaptive"}`) and use the effort parameter to control thinking depth. Adaptive thinking is **off by default** on Claude Opus 4.7: requests with no `thinking` field run without thinking, matching Opus 4.6 behavior. Set `thinking: {type: "adaptive"}` explicitly to enable it.
+
+```python
+# Before (Opus 4.6)
+client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=64000,
+    thinking={"type": "enabled", "budget_tokens": 32000},
+    messages=[{"role": "user", "content": "..."}],
+)
+
+# After (Opus 4.7)
+client.messages.create(
+    model="claude-opus-4-7",
+    max_tokens=64000,
+    thinking={"type": "adaptive"},
+    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
+    messages=[{"role": "user", "content": "..."}],
+)
+```
+
+If the caller wasn't using extended thinking, no change is required — thinking is off by default, or can be set explicitly with `thinking={"type": "disabled"}`.
+
+Delete `budget_tokens` plumbing entirely. For the replacement `effort` value, see **Choosing an effort level on Opus 4.7** below — there is no exact 1:1 mapping from `budget_tokens`.
+
+**Sampling parameters removed.**
+
+The `temperature`, `top_p`, and `top_k` parameters are no longer accepted on Claude Opus 4.7. Requests that include them return a 400 error. Remove these fields from your request payloads. Prompting is the recommended way to guide model behavior on Claude Opus 4.7. If you were using `temperature = 0` for determinism, note that it never guaranteed identical outputs on prior models.
+
+```python
+# Before — errors on Opus 4.7
+client.messages.create(temperature=0.7, top_p=0.9, ...)
+
+# After
+client.messages.create(...)  # no sampling params
+```
+
+- **If the intent was determinism** — use `effort: "low"` with a tighter prompt.
+- **If the intent was creative variance** — the prompt replacement depends on the use case; **ask the user** how they want variance elicited. If you can't ask, add a use-case-appropriate instruction along the lines of *"choose something off-distribution and interesting"* — e.g. for text generation, *"Vary your phrasing and structure across responses"*; for frontend/design, use the propose-4-directions approach under **Design and frontend coding** below.
+
+### Choosing an effort level on Opus 4.7
+
+`budget_tokens` controlled how much to *think*; `effort` controls how much to think *and* act, so there is no exact 1:1 mapping. **Use `xhigh` for best results in coding and agentic use cases, and a minimum of `high` for most intelligence-sensitive use cases.** Experiment with other levels to further tune token usage and intelligence:
+
+| Level | Use when | Notes |
+| --- | --- | --- |
+| `max` | Intelligence-demanding tasks worth testing at the ceiling | Can deliver gains in some use cases but may show diminishing returns from increased token usage; can be prone to overthinking |
+| `xhigh` | **Most coding and agentic use cases** | The best setting for these; used as the default in Claude Code |
+| `high` | Intelligence-sensitive use cases generally | Balances token usage and intelligence; recommended minimum for most intelligence-sensitive work |
+| `medium` | Cost-sensitive use cases that need to reduce token usage while trading off intelligence | |
+| `low` | Short, scoped tasks and latency-sensitive workloads that are not intelligence-sensitive | |
+
+### Silent default changes (no error, but behavior differs)
+
+**Thinking content omitted by default.**
+
+Thinking blocks still appear in the response stream on Claude Opus 4.7, but their `thinking` field is empty unless you explicitly opt in. This is a silent change from Claude Opus 4.6, where the default was to return summarized thinking text. To restore summarized thinking content on Claude Opus 4.7, set `thinking.display` to `"summarized"`. **The block-field name is unchanged** — it is still `block.thinking` on a `thinking`-type block; do not rename it.
+
+**Detect this:** any code that reads `block.thinking` (or equivalent) from a `thinking`-type block and renders it in a UI, log, or trace. **The fix is the request parameter, not the response handling** — add `display: "summarized"` to the `thinking` parameter:
+
+```python
+thinking={"type": "adaptive", "display": "summarized"}  # "display" is new on Opus 4.7; values: "omitted" (default) | "summarized"
+```
+
+The default is `"omitted"` on Claude Opus 4.7. If thinking content was never surfaced anywhere, no change needed. If your product streams reasoning to users, the new default appears as a long pause before output begins; set `display: "summarized"` to restore visible progress during thinking.
+
+**Updated token counting.**
+
+Claude Opus 4.7 and Claude Opus 4.6 count tokens differently. The same input text produces a higher token count on Claude Opus 4.7 than on Claude Opus 4.6, and `/v1/messages/count_tokens` will return a different number of tokens for Claude Opus 4.7 than it did for Claude Opus 4.6. The token efficiency of Claude Opus 4.7 can vary by workload shape. Prompting interventions, `task_budget`, and `effort` can help control costs and ensure appropriate token usage. Keep in mind that these controls may trade off model intelligence. **Update your `max_tokens` parameters to give additional headroom, including compaction triggers.** Claude Opus 4.7 provides a 1M context window at standard API pricing with no long-context premium.
+
+What else to check:
+
+- Client-side token estimators (tiktoken-style approximations) calibrated against 4.6
+- Cost calculators that multiply tokens by a fixed per-token rate
+- Rate-limit retry thresholds keyed to measured token counts
+
+Re-baseline by re-running `client.messages.count_tokens()` against `claude-opus-4-7` on a representative sample of the caller's prompts. Do not apply a blanket multiplier. For cost-sensitive workloads, consider reducing `effort` by one level (e.g. `high` → `medium`). For agentic loops, consider adopting Task Budgets (below).
+
+### New feature: Task Budgets (beta)
+
+Opus 4.7 introduces **task budgets** — tell Claude how many tokens it has for a full agentic loop (thinking + tool calls + final output). The model sees a running countdown and uses it to prioritize work and wrap up gracefully as the budget is consumed.
+
+This is a **suggestion the model is aware of**, not a hard cap. It is distinct from `max_tokens`, which remains the enforced per-response limit and is *not* surfaced to the model. Use `task_budget` when you want the model to self-moderate; use `max_tokens` as a hard ceiling to cap usage.
+
+Requires beta header `task-budgets-2026-03-13`:
+
+```python
+client.beta.messages.create(
+    betas=["task-budgets-2026-03-13"],
+    model="claude-opus-4-7",
+    max_tokens=64000,
+    thinking={"type": "adaptive"},
+    output_config={
+        "effort": "high",
+        "task_budget": {"type": "tokens", "total": 128000},
+    },
+    messages=[...],
+)
+```
+
+Set a generous budget for open-ended agentic tasks and tighten it for latency-sensitive ones. **Minimum `task_budget.total` is 20,000 tokens.** If the budget is too restrictive for the task, the model may complete it less thoroughly, referencing its budget as the constraint. **Do not add `task_budget` during a migration unless you are sure the budget value is right** — if you can run the workload and measure, do so; otherwise ask the user for the value rather than guessing. This is the primary lever for offsetting the token-counting shift on agentic workloads.
+
+### Capability improvements
+
+**High-resolution vision.** Opus 4.7 is the first Claude model with high-resolution image support. Maximum image resolution is **2576 pixels on the long edge** (up from 1568px on Opus 4.6 and prior). This unlocks gains on vision-heavy workloads, especially computer use and screenshot/artifact/document understanding. Coordinates returned by the model now map 1:1 to actual image pixels, so no scale-factor math is needed.
+
+High-res support is **automatic on Opus 4.7** — no beta header, no client-side opt-in required. The model accepts larger inputs and returns pixel-accurate coordinates out of the box.
+
+**Token cost.** Full-resolution images on Opus 4.7 can use up to ~3× more image tokens than on prior models (up to ~4784 tokens per image, vs. the previous ~1,600-token cap). If the extra fidelity isn't needed, downsample client-side before sending to control cost — but **do not add downsampling by default during a migration**. If you're not sure whether the pipeline needs the fidelity, ask the user rather than guessing. Use `count_tokens()` on representative images on Opus 4.7 to re-baseline before reacting to any measured cost shift.
+
+Beyond resolution, Opus 4.7 also improves on low-level perception (pointing, measuring, counting) and natural-image bounding-box localization and detection.
+
+**Knowledge work.** Meaningful gains on tasks where the model visually verifies its own output — `.docx` redlining, `.pptx` editing, and programmatic chart/figure analysis (e.g. pixel-level data transcription via image-processing libraries). If prompts have scaffolding like *"double-check the slide layout before returning"*, try removing it and re-baselining.
+
+**Memory.** Opus 4.7 is better at writing and using file-system-based memory. If an agent maintains a scratchpad, notes file, or structured memory store across turns, that agent should improve at jotting down notes to itself and leveraging its notes in future tasks.
+
+**User-facing progress updates.** Opus 4.7 provides more regular, higher-quality interim updates during long agentic traces. If the system prompt has scaffolding like *"After every 3 tool calls, summarize progress"*, try removing it to avoid excessive user-facing text. If the length or contents of Opus 4.7's updates are not well-calibrated to your use case, explicitly describe what these updates should look like in the prompt and provide examples.
+
+### Real-time cybersecurity safeguards
+
+Requests that involve prohibited or high-risk topics may lead to refusals.
+
+### Fast Mode: not available on Opus 4.7
+
+Opus 4.7 does not have a Fast Mode variant. **Opus 4.6 Fast remains supported**. Only surface this if the caller's code actually uses a Fast Mode model string (e.g. `claude-opus-4-6-fast`); if the word "fast" does not appear in the code, say nothing about Fast Mode.
+
+When you see `model="claude-opus-4-6-fast"` (or similar), **the migration edit is**:
+
+```python
+# Opus 4.7 has no Fast Mode — keeping on 4.6 Fast (caller's choice to switch to standard Opus 4.7).
+model="claude-opus-4-6-fast",
+```
+
+That is: leave the model string **unchanged**, add the comment above it, and tell the user their two options — (a) stay on Opus 4.6 Fast, which remains supported, or (b) move latency-tolerant traffic to standard Opus 4.7 for the intelligence gain. Do **not** rewrite the model string to `claude-opus-4-7` yourself; that silently trades latency for intelligence, which is the caller's decision.
+
+### Behavioral shifts (prompt-tunable)
+
+These don't break anything, but prompts tuned for Opus 4.6 may land differently. Opus 4.7 is more steerable than 4.6, so small prompt nudges usually close the gap.
+
+**More literal instruction following.** Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6, particularly at lower effort levels. It will not silently generalize an instruction from one item to another, and it will not infer requests you didn't make. The upside of this literalism is precision and less thrash. It generally performs better for API use cases with carefully tuned prompts, structured extraction, and pipelines where you want predictable behavior. A prompt and harness review may be especially helpful for migration to Claude Opus 4.7.
+
+**Verbosity calibrates to task complexity.** Opus 4.7 scales response length to how complex it judges the task to be, rather than defaulting to a fixed verbosity — shorter answers on simple lookups, much longer on open-ended analysis. If the product depends on a particular length or style, tune the prompt explicitly. To reduce verbosity:
+
+> *"Provide concise, focused responses. Skip non-essential context, and keep examples minimal."*
+
+If you see specific kinds of over-verbosity (e.g. over-explaining), add instructions targeting those. Positive examples showing the desired level of concision tend to be more effective than negative examples or instructions telling the model what not to do. Do **not** assume existing "be concise" instructions should be removed — test first.
+
+**Tone and writing style.** Opus 4.7 is more direct and opinionated, with less validation-forward phrasing and fewer emoji than Opus 4.6's warmer style. As with any new model, prose style on long-form writing may shift. If the product relies on a specific voice, re-evaluate style prompts against the new baseline. If a warmer or more conversational voice is wanted, specify it:
+
+> *"Use a warm, collaborative tone. Acknowledge the user's framing before answering."*
+
+**`effort` matters more than on any prior Opus.** Opus 4.7 respects `effort` levels more strictly, especially at the low end. At `low` and `medium` it scopes work to what was asked rather than going above and beyond — good for latency and cost, but on moderate tasks at `low` there is some risk of under-thinking.
+
+- If shallow reasoning shows up on complex problems, raise `effort` to `high` or `xhigh` rather than prompting around it.
+- If `effort` must stay `low` for latency, add targeted guidance: *"This task involves multi-step reasoning. Think carefully through the problem before responding."*
+- **At `xhigh` or `max`, set a large `max_tokens`** so the model has room to think and act across tool calls and subagents. Start at 64K and tune from there. (`xhigh` is a new effort level on Opus 4.7, between `high` and `max`.)
+
+Adaptive-thinking triggering is also steerable. If the model thinks more often than wanted — which can happen with large or complex system prompts — add: *"Thinking adds latency and should only be used when it will meaningfully improve answer quality — typically for problems that require multi-step reasoning. When in doubt, respond directly."*
+
+**Uses tools less often by default.** Opus 4.7 tends to use tools less often than 4.6 and to use reasoning more. This produces better results in most cases, but for products that rely on tools (search/retrieval, function-calling, computer-use steps), it can drop tool-use rate. Two levers:
+
+- **Raise `effort`** — `high` or `xhigh` show substantially more tool usage in agentic search and coding, and are especially useful for knowledge work.
+- **Prompt for it** — be explicit in tool descriptions or the system prompt about when and how to use the tool, and encourage the model to err on the side of using it more often:
+
+> *"When the answer depends on information not present in the conversation, you MUST call the `search` tool before answering — do not answer from prior knowledge."*
+
+**Fewer subagents by default.** Opus 4.7 tends to spawn fewer subagents than 4.6. This is steerable — give explicit guidance on when delegation is desirable. For a coding agent, for example:
+
+> *"Do NOT spawn a subagent for work you can complete directly in a single response (e.g. refactoring a function you can already see). Spawn multiple subagents in the same turn when fanning out across items or reading multiple files."*
+
+**Design and frontend coding.** Opus 4.7 has stronger design instincts than 4.6, with a consistent default house style: warm cream/off-white backgrounds (around `#F4F1EA`), serif display type (Georgia, Fraunces, Playfair), italic word-accents, and a terracotta/amber accent. This reads well for editorial, hospitality, and portfolio briefs, but will feel off for dashboards, dev tools, fintech, healthcare, or enterprise apps — and it appears in slide decks as well as web UIs.
+
+The default is persistent. Generic instructions ("don't use cream," "make it clean and minimal") tend to shift the model to a different fixed palette rather than producing variety. Two approaches work reliably:
+
+1. **Specify a concrete alternative.** The model follows explicit specs precisely — give exact hex values, typefaces, and layout constraints.
+2. **Have the model propose options before building.** This breaks the default and gives the user control:
+
+   > *"Before building, propose 4 distinct visual directions tailored to this brief (each as: bg hex / accent hex / typeface — one-line rationale). Ask the user to pick one, then implement only that direction."*
+
+If the caller previously relied on `temperature` for design variety, use approach (2) — it produces meaningfully different directions across runs.
+
+Opus 4.7 also requires less frontend-design prompting than previous models to avoid generic "AI slop" aesthetics. Where earlier models needed a lengthy anti-slop snippet, Opus 4.7 generates distinctive, creative frontends with a much shorter nudge. This snippet works well alongside the variety approaches above:
+
+> *"NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white or dark backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Use unique fonts, cohesive colors and themes, and animations for effects and micro-interactions."*
+
+**Interactive coding products.** Opus 4.7's token usage and behavior can differ between autonomous, asynchronous coding agents with a single user turn and interactive, synchronous coding agents with multiple user turns. Specifically, it tends to use more tokens in interactive settings, primarily because it reasons more after user turns. This can improve long-horizon coherence, instruction following, and coding capabilities in long interactive coding sessions, but also comes with more token usage. To maximize both performance and token efficiency in coding products, use `effort: "xhigh"` or `"high"`, add autonomous features (like an auto mode), and reduce the number of human interactions required from users.
+
+When limiting required user interactions, specify the task, intent, and relevant constraints upfront in the first human turn. Well-specified, clear, and accurate task descriptions upfront help maximize autonomy and intelligence while minimizing extra token usage after user turns — because Opus 4.7 is more autonomous than prior models, this usage pattern helps to maximize performance. In contrast, ambiguous or underspecified prompts conveyed progressively over multiple user turns tend to reduce token efficiency and sometimes performance.
+
+**Code review.** Opus 4.7 is meaningfully better at finding bugs than prior models, with both higher recall and precision. However, if a code-review harness was tuned for an earlier model, it may initially show *lower* recall — this is likely a harness effect, not a capability regression. When a review prompt says "only report high-severity issues," "be conservative," or "don't nitpick," Opus 4.7 follows that instruction more faithfully than earlier models did: it investigates just as thoroughly, identifies the bugs, and then declines to report findings it judges to be below the stated bar. Precision rises, but measured recall can fall even though underlying bug-finding has improved.
+
+Recommended prompt language:
+
+> *"Report every issue you find, including ones you are uncertain about or consider low-severity. Do not filter for importance or confidence at this stage — a separate verification step will do that. Your goal here is coverage: it is better to surface a finding that later gets filtered out than to silently drop a bug. For each finding, include your confidence level and an estimated severity so a downstream filter can rank them."*
+
+This can be used without an actual second step, but moving confidence filtering out of the finding step often helps. If the harness has a separate verification/dedup/ranking stage, tell the model explicitly that its job at the finding stage is coverage, not filtering. If single-pass self-filtering is wanted, be concrete about the bar rather than using qualitative terms like "important" — e.g. *"report any bugs that could cause incorrect behavior, a test failure, or a misleading result; only omit nits like pure style or naming preferences."* Iterate on prompts against a subset of evals to validate recall or F1 gains.
+
+**Computer use.** Computer use works across resolutions up to the new 2576px / 3.75MP maximum. Sending images at **1080p** provides a good balance of performance and cost. For particularly cost-sensitive workloads, **720p** or **1366×768** are lower-cost options with strong performance. Test to find the ideal settings for the use case; experimenting with `effort` can also help tune behavior.
+
+---
+
+## Opus 4.7 Migration Checklist
+
+Every item is tagged: **`[BLOCKS]`** items cause a 400 error, infinite loop, silent truncation, or empty output if missed — apply these as code edits, not as suggestions. **`[TUNE]`** items are quality/cost adjustments — surface them to the user as recommendations.
+
+`[BLOCKS]` items prefixed with **"If…"** or **"At…"** are conditional. Before working through the list, **scan the file** for the conditions: does it surface thinking text to a UI/log? Does it set `output_config.effort` to `"x-high"` or `"max"`? Is it a security workload? Is it a multi-turn agentic loop? Apply only the items whose condition matches.
+
+- [ ] **[BLOCKS]** Replace `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}` + `output_config.effort`; delete `budget_tokens` plumbing entirely
+- [ ] **[BLOCKS]** Strip `temperature`, `top_p`, `top_k` from request construction
+- [ ] **[BLOCKS]** If thinking content is surfaced to users or stored in logs: add `thinking.display: "summarized"` (otherwise the rendered text is empty)
+- [ ] **[BLOCKS]** At `output_config.effort` of `xhigh` or `max`: set `max_tokens` ≥ 64000 (otherwise output truncates mid-thought)
+- [ ] **[TUNE]** Give `max_tokens` and compaction triggers extra headroom; re-run `count_tokens()` against `claude-opus-4-7` on representative prompts to re-baseline (no blanket multiplier)
+- [ ] **[TUNE]** Re-baseline cost and rate-limit dashboards *before* reacting to measured shifts
+- [ ] **[TUNE]** Re-evaluate `effort` per route — use `xhigh` for coding/agentic and a minimum of `high` for most intelligence-sensitive work; it matters more on 4.7 than any prior Opus
+- [ ] **[TUNE]** Multi-turn agentic loops: adopt the API-native Task Budgets (`output_config.task_budget`, beta `task-budgets-2026-03-13`, minimum 20k tokens) — this is for capping *cumulative* spend across a loop; per-turn depth is `effort`
+- [ ] **[TUNE]** Check for ambiguous or underspecified instructions that relied on 4.6 generalizing intent, and update them to be clearer or more precise — 4.7 follows them literally
+- [ ] **[TUNE]** Tool-use workloads: add explicit when/how-to-use guidance to tool descriptions (4.7 reaches for tools less often)
+- [ ] **[TUNE]** Verbosity: test existing length instructions before changing them — 4.7 calibrates length to task complexity, so tune for the desired output rather than assuming a direction
+- [ ] **[TUNE]** Remove forced-progress-update scaffolding (*"after every N tool calls…"*)
+- [ ] **[TUNE]** Remove knowledge-work verification scaffolding (*"double-check the slide layout…"*) and re-baseline
+- [ ] **[TUNE]** Add tone instruction if a warmer / more conversational voice is needed; re-evaluate style prompts on writing-heavy routes
+- [ ] **[TUNE]** Subagent tool present: add explicit spawn / don't-spawn guidance
+- [ ] **[TUNE]** Frontend/design output: specify a concrete palette/typeface, or have the model propose 4 visual directions before building (the default cream/serif house style is persistent)
+- [ ] **[TUNE]** Interactive coding products: use `effort: "xhigh"` or `"high"`, add autonomous features (e.g. an auto mode) to reduce human interactions, and specify task/intent/constraints upfront in the first turn
+- [ ] **[TUNE]** Code-review harnesses: remove or loosen "only report high-severity" / "be conservative" filters and have the model report every finding with confidence + severity; move filtering to a downstream step (4.7 follows severity filters more literally, which can depress measured recall)
+- [ ] **[TUNE]** Vision-heavy pipelines (screenshots, charts, document understanding): leave images at native resolution up to 2576px long edge for the accuracy gain; remove any scale-factor math from coordinate handling (coords are now 1:1 with pixels). No beta header / opt-in needed — high-res is automatic on Opus 4.7.
+- [ ] **[TUNE]** Computer-use pipelines: send screenshots at 1080p for a good performance/cost balance (720p or 1366×768 for cost-sensitive workloads); experiment with `effort` to tune behavior
+- [ ] **[TUNE]** Cost-sensitive image pipelines: full-res images on 4.7 use up to ~4784 tokens vs ~1,600 on prior models (~3×). Downsampling client-side before upload avoids the increase, but **do not downsample by default** — if you're unsure whether fidelity is needed, ask the user. Re-baseline with `count_tokens()` on representative images before reacting to cost shifts.
+
+---
+
+## Verify the Migration
+
+After updating, spot-check that the new model is actually being used. Replace `YOUR_TARGET_MODEL` with the model string you migrated to (e.g. `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`) and keep the assertion prefix in sync:
+
+```python
+YOUR_TARGET_MODEL = "claude-opus-4-7"  # or "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"
+response = client.messages.create(model=YOUR_TARGET_MODEL, max_tokens=64, messages=[...])
+assert response.model.startswith(YOUR_TARGET_MODEL), response.model
+```
+
+For rate-limit headroom changes, pricing, or capability deltas (vision, structured outputs, effort support), query the Models API:
+
+```python
+m = client.models.retrieve(YOUR_TARGET_MODEL)
+m.max_input_tokens, m.max_tokens
+m.capabilities["effort"]["max"]["supported"]
+```
+
+See `shared/models.md` for the full capability lookup pattern.

cli-tool/components/skills/development/claude-api/shared/models.md

@@ -0,0 +1,121 @@
+# 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-7")
+m.id                 # "claude-opus-4-7"
+m.display_name       # "Claude Opus 4.7"
+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-7 \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01"
+```
+
+```json
+{
+  "id": "claude-opus-4-7",
+  "display_name": "Claude Opus 4.7",
+  "max_input_tokens": 200000,
+  "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 Opus 4.7   | `claude-opus-4-7`   | —                             | 1M             | 128K       | Active |
+| Claude Opus 4.6   | `claude-opus-4-6`   | —                             | 1M             | 128K       | Active |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | -                             | 1M             | 64K        | Active |
+| Claude Haiku 4.5  | `claude-haiku-4-5`  | `claude-haiku-4-5-20251001`   | 200K           | 64K        | Active |
+
+### Model Descriptions
+- **Claude Opus 4.7** — The most capable Claude model to date — highly autonomous, strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and `budget_tokens` are removed. 1M context window at standard API pricing (no long-context premium) — see `shared/model-migration.md` → Migrating to Opus 4.7 for breaking changes.
+- **Claude Opus 4.6** — Previous-generation Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window.
+- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window. 64K 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`    | Active |
+| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929`  | Active |
+| Claude Sonnet 4   | `claude-sonnet-4-0` | `claude-sonnet-4-20250514`    | Active |
+| Claude Opus 4     | `claude-opus-4-0`   | `claude-opus-4-20250514`      | Active |
+
+## Deprecated Models (retiring soon)
+
+| Friendly Name     | Alias (use this)    | Full ID                       | Status     | Retires      |
+|-------------------|---------------------|-------------------------------|------------|--------------|
+| 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              |
+|-------------------------------------------|--------------------------------|
+| "opus", "most powerful"                   | `claude-opus-4-7`              |
+| "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`              |
+| "opus 4", "opus 4.0"                      | `claude-opus-4-0`              |
+| "sonnet", "balanced"                      | `claude-sonnet-4-6`            |
+| "sonnet 4.6"                              | `claude-sonnet-4-6`            |
+| "sonnet 4.5"                              | `claude-sonnet-4-5`            |
+| "sonnet 4", "sonnet 4.0"                  | `claude-sonnet-4-0`            |
+| "sonnet 3.7"                              | Retired — suggest `claude-sonnet-4-5` |
+| "sonnet 3.5"                              | Retired — suggest `claude-sonnet-4-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` |

cli-tool/components/skills/development/claude-api/shared/prompt-caching.md

@@ -0,0 +1,171 @@
+# 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
+]}]
+```
+
+### 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 as a user or assistant message later in `messages`. 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 |
+|---|---:|
+| Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
+| Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens |
+| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens |
+
+A 3K-token prompt caches on Sonnet 4.5 but silently won't on Opus 4.7.
+
+**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.
+
+---
+
+## 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.

cli-tool/components/skills/development/claude-api/shared/tool-use-concepts.md

@@ -0,0 +1,327 @@
+# Tool Use Concepts
+
+This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`.
+
+## User-Defined Tools
+
+### Tool Definition Structure
+
+> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support.
+
+Each tool requires a name, description, and JSON Schema for its inputs:
+
+```json
+{
+  "name": "get_weather",
+  "description": "Get current weather for a location",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "location": {
+        "type": "string",
+        "description": "City and state, e.g., San Francisco, CA"
+      },
+      "unit": {
+        "type": "string",
+        "enum": ["celsius", "fahrenheit"],
+        "description": "Temperature unit"
+      }
+    },
+    "required": ["location"]
+  }
+}
+```
+
+**Best practices for tool definitions:**
+
+- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`)
+- Write detailed descriptions — Claude uses these to decide when to use the tool
+- Include descriptions for each property
+- Use `enum` for parameters with a fixed set of values
+- Mark truly required parameters in `required`; make others optional with defaults
+
+---
+
+### Tool Choice Options
+
+Control when Claude uses tools:
+
+| Value                             | Behavior                                      |
+| --------------------------------- | --------------------------------------------- |
+| `{"type": "auto"}`                | Claude decides whether to use tools (default) |
+| `{"type": "any"}`                 | Claude must use at least one tool             |
+| `{"type": "tool", "name": "..."}` | Claude must use the specified tool            |
+| `{"type": "none"}`                | Claude cannot use tools                       |
+
+Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.
+
+---
+
+### Tool Runner vs Manual Loop
+
+**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details.
+
+**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`.
+
+**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically.
+
+```python
+# Handle pause_turn in your agentic loop
+if response.stop_reason == "pause_turn":
+    messages = [
+        {"role": "user", "content": user_query},
+        {"role": "assistant", "content": response.content},
+    ]
+    # Make another API request — server resumes automatically
+    response = client.messages.create(
+        model="claude-opus-4-7", messages=messages, tools=tools
+    )
+```
+
+Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons`
+
+> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution.
+
+---
+
+### Handling Tool Results
+
+When Claude uses a tool, the response contains a `tool_use` block. You must:
+
+1. Execute the tool with the provided input
+2. Send the result back in a `tool_result` message
+3. Continue the conversation
+
+**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.
+
+**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message.
+
+---
+
+## Server-Side Tools: Code Execution
+
+The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.
+
+### Key Facts
+
+- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
+- No internet access (fully sandboxed)
+- Python 3.11 with data science libraries pre-installed
+- Containers persist for 30 days and can be reused across requests
+- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization
+
+### Tool Definition
+
+The tool requires no schema — just declare it in the `tools` array:
+
+```json
+{
+  "type": "code_execution_20260120",
+  "name": "code_execution"
+}
+```
+
+Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files).
+
+### Pre-installed Python Libraries
+
+- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels
+- **Visualization**: matplotlib, seaborn
+- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
+- **Math**: sympy, mpmath
+- **Utilities**: tqdm, python-dateutil, pytz, sqlite3
+
+Additional packages can be installed at runtime via `pip install`.
+
+### Supported File Types for Upload
+
+| Type   | Extensions                         |
+| ------ | ---------------------------------- |
+| Data   | CSV, Excel (.xlsx/.xls), JSON, XML |
+| Images | JPEG, PNG, GIF, WebP               |
+| Text   | .txt, .md, .py, .js, etc.          |
+
+### Container Reuse
+
+Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests.
+
+### Response Structure
+
+The response contains interleaved text and tool result blocks:
+
+- `text` — Claude's explanation
+- `server_tool_use` — What Claude is doing
+- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure)
+- `text_editor_code_execution_tool_result` — File operation results
+
+> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.
+
+---
+
+## Server-Side Tools: Web Search and Web Fetch
+
+Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.
+
+### Tool Definitions
+
+```json
+[
+  { "type": "web_search_20260209", "name": "web_search" },
+  { "type": "web_fetch_20260209", "name": "web_fetch" }
+]
+```
+
+### Dynamic Filtering (Opus 4.7 / Opus 4.6 / Sonnet 4.6)
+
+The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header.
+
+```json
+{
+  "tools": [
+    { "type": "web_search_20260209", "name": "web_search" },
+    { "type": "web_fetch_20260209", "name": "web_fetch" }
+  ]
+}
+```
+
+Without dynamic filtering, the previous `web_search_20250305` version is also available.
+
+> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model.
+
+---
+
+## Server-Side Tools: Programmatic Tool Calling
+
+With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again.
+
+Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling`
+
+---
+
+## Server-Side Tools: Tool Search
+
+The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents).
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool`
+
+---
+
+## Skills
+
+Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a `SKILL.md` file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/skills`
+
+---
+
+## Tool Use Examples
+
+You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use`
+
+---
+
+## Server-Side Tools: Computer Use
+
+Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side).
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview`
+
+---
+
+## Context Editing
+
+Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable.
+
+For full documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing`
+
+---
+
+## Client-Side Tools: Memory
+
+The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.
+
+### Key Facts
+
+- Client-side tool — you control storage via your implementation
+- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename`
+- Operates on files in a `/memories` directory
+- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend
+
+> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.
+
+For full implementation examples, use WebFetch:
+
+- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md`
+
+---
+
+## Structured Outputs
+
+Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.
+
+Two features are available:
+
+- **JSON outputs** (`output_config.format`): Control Claude's response format
+- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas
+
+**Supported models:** Claude Opus 4.7, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
+
+> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter.
+
+### JSON Schema Limitations
+
+**Supported:**
+
+- Basic types: object, array, string, integer, number, boolean, null
+- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def`
+- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`
+- `additionalProperties: false` (required for all objects)
+
+**Not supported:**
+
+- Recursive schemas
+- Numerical constraints (`minimum`, `maximum`, `multipleOf`)
+- String constraints (`minLength`, `maxLength`)
+- Complex array constraints
+- `additionalProperties` set to anything other than `false`
+
+The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.
+
+### Important Notes
+
+- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
+- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema.
+- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`.
+- **Incompatible with**: Citations (returns 400 error), message prefilling.
+- **Works with**: Batches API, streaming, token counting, extended thinking.
+
+---
+
+## Tips for Effective Tool Use
+
+1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools
+2. **Use specific tool names**: `get_current_weather` is better than `weather`
+3. **Validate inputs**: Always validate tool inputs before execution
+4. **Handle errors gracefully**: Return informative error messages so Claude can adapt
+5. **Limit tool count**: Too many tools can confuse the model — keep the set focused
+6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios
+
+For detailed tool use documentation, use WebFetch:
+
+- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview`