claudecode-omc 5.11.0 → 5.12.0

package/bundled/upstream/anthropic-skills/skills/claude-api/python/claude-api/README.md

@@ -11,10 +11,12 @@ pip install anthropic
 ```python
 import anthropic
 
-# Default (uses ANTHROPIC_API_KEY env var)
+# Default — resolves credentials from the environment:
+# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
+# Prefer this for local dev; don't hardcode a key.
 client = anthropic.Anthropic()
 
-# Explicit API key
+# Explicit API key (only when you must inject a specific key)
 client = anthropic.Anthropic(api_key="your-api-key")
 
 # Async client
@@ -23,6 +25,67 @@ async_client = anthropic.AsyncAnthropic()
 
 ---
 
+## Client Configuration
+
+### Per-request overrides
+
+Use `with_options()` to override client settings for a single call without mutating the client:
+
+```python
+client.with_options(timeout=5.0, max_retries=5).messages.create(
+    model="claude-opus-4-8",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+### Timeouts
+
+Default request timeout is 10 minutes. Pass a float (seconds) or an `httpx.Timeout` for granular control. On timeout the SDK raises `anthropic.APITimeoutError` (and retries per `max_retries`).
+
+```python
+import httpx
+
+client = anthropic.Anthropic(timeout=20.0)
+client = anthropic.Anthropic(
+    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
+)
+```
+
+### Retries
+
+The SDK auto-retries connection errors, 408, 409, 429, and ≥500 with exponential backoff (default 2 retries). Set `max_retries` on the client or via `with_options()`; `max_retries=0` disables.
+
+### Async performance (aiohttp backend)
+
+For high-concurrency async workloads, install `anthropic[aiohttp]` and pass `DefaultAioHttpClient` instead of the default httpx backend:
+
+```python
+from anthropic import AsyncAnthropic, DefaultAioHttpClient
+
+async with AsyncAnthropic(http_client=DefaultAioHttpClient()) as client:
+    ...
+```
+
+### Custom HTTP client (proxy, base URL)
+
+Use `DefaultHttpxClient` / `DefaultAsyncHttpxClient` — not raw `httpx.Client` — so the SDK's default timeouts and connection limits are preserved:
+
+```python
+from anthropic import Anthropic, DefaultHttpxClient
+
+client = Anthropic(
+    base_url="http://my.test.server.example.com:8083",  # or ANTHROPIC_BASE_URL env var
+    http_client=DefaultHttpxClient(proxy="http://my.test.proxy.example.com"),
+)
+```
+
+### Logging
+
+Set `ANTHROPIC_LOG=debug` (or `info`) to enable SDK logging via the standard `logging` module.
+
+---
+
 ## Basic Message Request
 
 ```python
@@ -53,6 +116,23 @@ response = client.messages.create(
 )
 ```
 
+### Mid-conversation system messages (beta, model-gated)
+
+For operator instructions that arrive mid-conversation (mode switches, injected state), append `{"role": "system", ...}` to `messages` instead of editing top-level `system` — this preserves the cached prefix and carries operator authority. Must follow a user message; cannot be `messages[0]`. Unsupported models return a 400 (`role 'system' is not supported on this model`). See `shared/prompt-caching.md` for when to use this vs. top-level `system`.
+
+```python
+response = client.messages.create(
+    model=MODEL_ID,  # must support mid-conversation system messages
+    max_tokens=16000,
+    system=[{"type": "text", "text": STABLE_SYSTEM, "cache_control": {"type": "ephemeral"}}],
+    messages=history + [
+        {"role": "user", "content": user_message},
+        {"role": "system", "content": "Terse mode enabled — keep responses under 40 words."},
+    ],
+    extra_headers={"anthropic-beta": "mid-conversation-system-2026-04-07"},
+)
+```
+
 ---
 
 ## Vision (Images)
@@ -170,11 +250,11 @@ If `cache_read_input_tokens` is zero across repeated identical-prefix requests,
 
 ## Extended Thinking
 
-> **Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Opus 4.8 and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
+> **Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is removed on Fable 5, Opus 4.8, and 4.7 (400 if sent); deprecated on Opus 4.6 and Sonnet 4.6.
 > **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
 
 ```python
-# Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
+# Fable 5 / Opus 4.8 / 4.7 / 4.6: adaptive thinking (recommended)
 response = client.messages.create(
     model="claude-opus-4-8",
     max_tokens=16000,
@@ -222,6 +302,31 @@ except anthropic.APIConnectionError:
 
 ---
 
+## Response Helpers
+
+Every response object exposes `_request_id` (populated from the `request-id` header) — log it when reporting failures to Anthropic. Despite the underscore prefix, this property is public.
+
+```python
+message = client.messages.create(...)
+print(message._request_id)       # req_018EeWyXxfu5pfWkrYcMdjWG
+print(message.to_json())          # serialize the Pydantic model
+print(message.to_dict())          # plain dict
+```
+
+To access raw headers or other response metadata, use `.with_raw_response`:
+
+```python
+raw = client.messages.with_raw_response.create(
+    model="claude-opus-4-8",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(raw.headers.get("request-id"))
+message = raw.parse()  # the Message object messages.create() would have returned
+```
+
+---
+
 ## Multi-Turn Conversations
 
 The API is stateless — send the full conversation history each time.
@@ -268,14 +373,15 @@ response2 = conversation.send("What's my name?")  # Claude remembers "Alice"
 
 **Rules:**
 
-- Messages must alternate between `user` and `assistant`
+- Consecutive same-role messages are allowed — the API combines them into a single turn
 - First message must be `user`
+- `role: "system"` messages are allowed mid-conversation under the `mid-conversation-system-2026-04-07` beta on supporting models — see § Mid-conversation system messages above
 
 ---
 
 ### Compaction (long conversations)
 
-> **Beta, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
+> **Beta, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
 
 ```python
 import anthropic
@@ -320,7 +426,17 @@ The `stop_reason` field in the response indicates why the model stopped generati
 | `stop_sequence` | Hit a custom stop sequence |
 | `tool_use` | Claude wants to call a tool — execute it and continue |
 | `pause_turn` | Model paused and can be resumed (agentic flows) |
-| `refusal` | Claude refused for safety reasons — output may not match your schema |
+| `refusal` | Claude refused for safety reasons — check `stop_details` |
+
+### Structured Stop Details
+
+When `stop_reason` is `"refusal"`, the response includes a `stop_details` object with structured information about the refusal:
+
+```python
+if response.stop_reason == "refusal" and response.stop_details:
+    print(f"Category: {response.stop_details.category}")   # "cyber" | "bio" | None
+    print(f"Explanation: {response.stop_details.explanation}")
+```
 
 ---
 

package/bundled/upstream/anthropic-skills/skills/claude-api/python/claude-api/batches.md

@@ -100,6 +100,19 @@ print(f"Status: {cancelled.processing_status}")  # "canceling"
 
 ---
 
+## List Batches (auto-pagination)
+
+Iterating the return value of any `list()` call auto-paginates across all pages — do not index into `.data` if you want the full set:
+
+```python
+for batch in client.messages.batches.list(limit=20):
+    print(batch.id, batch.processing_status)
+```
+
+For manual control, use `first_page.has_next_page()` / `first_page.get_next_page()` / `first_page.next_page_info()`; `first_page.data` holds the current page's items and `first_page.last_id` is the cursor.
+
+---
+
 ## Batch with Prompt Caching
 
 ```python

package/bundled/upstream/anthropic-skills/skills/claude-api/python/claude-api/files-api.md

@@ -16,14 +16,18 @@ The Files API uploads files for use in Messages API requests. Reference files vi
 
 ## Upload a File
 
+The `file` argument accepts a `(filename, content, content_type)` tuple, a `pathlib.Path` (or any `PathLike` — read for you, async-safe with `AsyncAnthropic`), or an open binary file object.
+
 ```python
 import anthropic
+from pathlib import Path
 
 client = anthropic.Anthropic()
 
 uploaded = client.beta.files.upload(
     file=("report.pdf", open("report.pdf", "rb"), "application/pdf"),
 )
+# or: client.beta.files.upload(file=Path("report.pdf"))
 print(f"File ID: {uploaded.id}")
 print(f"Size: {uploaded.size_bytes} bytes")
 ```
@@ -87,9 +91,10 @@ response = client.beta.messages.create(
 
 ### List Files
 
+Iterate the list result directly — the SDK auto-paginates across all pages. Only use `.data` if you want the first page only.
+
 ```python
-files = client.beta.files.list()
-for f in files.data:
+for f in client.beta.files.list():
     print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")
 ```
 

package/bundled/upstream/anthropic-skills/skills/claude-api/python/claude-api/streaming.md

@@ -24,13 +24,29 @@ async with async_client.messages.stream(
         print(text, end="", flush=True)
 ```
 
+### Low-level: `stream=True`
+
+`messages.stream()` (above) is the recommended helper — it accumulates state and exposes `text_stream` / `get_final_message()`. If you only need the raw event iterator and want lower memory use, pass `stream=True` to `messages.create()` instead:
+
+```python
+for event in client.messages.create(
+    model="claude-opus-4-8",
+    max_tokens=64000,
+    messages=[{"role": "user", "content": "Write a story"}],
+    stream=True,
+):
+    print(event.type)
+```
+
+No final-message accumulation is done for you in this form.
+
 ---
 
 ## Handling Different Content Types
 
 Claude may return text, thinking blocks, or tool use. Handle each appropriately:
 
-> **Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
+> **Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead.
 
 ```python
 with client.messages.stream(
@@ -160,3 +176,4 @@ except anthropic.APIStatusError as e:
 3. **Track token usage** — The `message_delta` event contains usage information
 4. **Use timeouts** — Set appropriate timeouts for your application
 5. **Default to streaming** — Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events
+6. **Large `max_tokens` without streaming raises `ValueError`** — The SDK refuses non-streaming requests it estimates will exceed ~10 minutes (idle connections drop). Pass `stream=True` / use `messages.stream()`, or explicitly override `timeout`, to suppress the guard.

package/bundled/upstream/anthropic-skills/skills/claude-api/python/managed-agents/README.md

@@ -15,10 +15,12 @@ pip install anthropic
 ```python
 import anthropic
 
-# Default (uses ANTHROPIC_API_KEY env var)
+# Default — resolves credentials from the environment:
+# ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
+# Prefer this for local dev; don't hardcode a key.
 client = anthropic.Anthropic()
 
-# Explicit API key
+# Explicit API key (only when you must inject a specific key)
 client = anthropic.Anthropic(api_key="your-api-key")
 ```
 
@@ -129,7 +131,7 @@ client.beta.sessions.events.send(
 import json
 
 # Stream-first: open stream, then send while stream is live
-with client.beta.sessions.stream(
+with client.beta.sessions.events.stream(
     session_id=session.id,
 ) as stream:
     client.beta.sessions.events.send(
@@ -140,7 +142,7 @@ with client.beta.sessions.stream(
         ...  # process events
 
 # Standalone stream iteration:
-with client.beta.sessions.stream(
+with client.beta.sessions.events.stream(
     session_id=session.id,
 ) as stream:
     for event in stream:
@@ -150,7 +152,7 @@ with client.beta.sessions.stream(
                     print(block.text, end="", flush=True)
         elif event.type == "agent.custom_tool_use":
             # Custom tool invocation — session is now idle
-            print(f"\nCustom tool call: {event.tool_name}")
+            print(f"\nCustom tool call: {event.name}")
             print(f"Input: {json.dumps(event.input)}")
             # Send result back (see below)
         elif event.type == "session.status_idle":
@@ -210,7 +212,7 @@ def run_custom_tool(tool_name: str, tool_input: dict) -> str:
 def run_session(client, session_id: str):
     """Stream events and handle custom tool calls."""
     while True:
-        with client.beta.sessions.stream(
+        with client.beta.sessions.events.stream(
             session_id=session_id,
         ) as stream:
             tool_calls = []
@@ -232,7 +234,7 @@ def run_session(client, session_id: str):
         # Process custom tool calls
         results = []
         for call in tool_calls:
-            result = run_custom_tool(call.tool_name, call.input)
+            result = run_custom_tool(call.name, call.input)
             results.append({
                 "type": "user.custom_tool_result",
                 "custom_tool_use_id": call.id,

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

@@ -111,3 +111,30 @@ message = client.messages.create(
 For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block.
 
 Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`.
+
+---
+
+## Stop Details
+
+When `stop_reason` is `:refusal`, the response includes structured `stop_details`:
+
+```ruby
+if message.stop_reason == :refusal && message.stop_details
+  puts "Category: #{message.stop_details.category}"     # :cyber, :bio, or nil
+  puts "Explanation: #{message.stop_details.explanation}"
+end
+```
+
+---
+
+## Error Type
+
+`APIStatusError` exposes a `.type` field for programmatic error classification:
+
+```ruby
+begin
+  client.messages.create(...)
+rescue Anthropic::APIStatusError => e
+  puts e.type  # :rate_limit_error, :overloaded_error, etc.
+end
+```

package/bundled/upstream/anthropic-skills/skills/claude-api/shared/agent-design.md

@@ -90,7 +90,7 @@ Both patterns keep the fixed context small and load detail on demand.
 
 | 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. |
+| Editing the system prompt mid-session invalidates the cache. | Append a `{"role": "system", ...}` message to `messages[]` instead (beta, on supporting models — see `prompt-caching.md` § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a `<system-reminder>` text block in the user turn. |
 | 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. |
 

package/bundled/upstream/anthropic-skills/skills/claude-api/shared/anthropic-cli.md

@@ -0,0 +1,246 @@
+# Anthropic CLI (`ant`)
+
+The `ant` CLI exposes every Claude API resource as a shell subcommand. Compared to `curl`: request bodies are built from typed flags or piped YAML instead of hand-written JSON, `@path` inlines file contents into any string field, `--transform` extracts fields with a GJSON path (no `jq`), list endpoints auto-paginate (cap total results with `--max-items N`; `--limit` only sets the server page size), and the `beta:` prefix auto-sets the right `anthropic-beta` header.
+
+## When to use the CLI vs the SDK
+
+**CLI for the control plane, SDK for the data plane.** Agents and environments are relatively static resources you define, configure, and debug with `ant` — check the YAML into your repo, apply from CI, inspect from a terminal. Sessions are dynamic and driven by your application through the SDK — create per task, stream events, react to tool calls, integrate into your product. Both hit the same API; the split is about where the call lives, not what's possible.
+
+| | Control plane → `ant` | Data plane → SDK |
+|---|---|---|
+| Resources | agents, environments, skills, vaults, files | sessions, events |
+| Cadence | Once per deploy / ad-hoc | Every task / every turn |
+| Lives in | `*.yaml` in your repo + CI + terminal | Application code |
+| Typical calls | `create < agent.yaml`, `update --version N`, `list`, `retrieve`, `archive`, `--debug` | `sessions.create()`, `events.stream()`, `events.send()` |
+
+## Install and auth
+
+```sh
+# macOS
+brew install anthropics/tap/ant
+xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"
+
+# Linux / WSL — pick the release from github.com/anthropics/anthropic-cli/releases
+curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_$(uname -s | tr A-Z a-z)_$(uname -m | sed -e s/x86_64/amd64/ -e s/aarch64/arm64/).tar.gz" \
+  | sudo tar -xz -C /usr/local/bin ant
+
+# Or from source (Go 1.22+)
+go install github.com/anthropics/anthropic-cli/cmd/ant@latest
+```
+
+**Auth** — the CLI resolves credentials the same way the SDKs do (first match wins): explicit flags, then `ANTHROPIC_API_KEY`, then `ANTHROPIC_AUTH_TOKEN`, then the `ANTHROPIC_PROFILE`-selected or active profile, then Workload Identity Federation env vars, then the default profile on disk. Override the host with `ANTHROPIC_BASE_URL` or `--base-url`.
+
+- **API key**: set `ANTHROPIC_API_KEY` in the environment.
+- **OAuth profile** (no static key to manage): `ant auth login` opens a browser, exchanges for a short-lived token, and stores a profile under `$ANTHROPIC_CONFIG_DIR` (default `~/.config/anthropic/` on Linux/macOS, `%APPDATA%\Anthropic` on Windows — `configs/<profile>.json` for settings, `credentials/<profile>.json` for tokens). Subsequent `ant` (and SDK) calls pick it up automatically — a bare `Anthropic()` client works after login, but scripts that read `ANTHROPIC_API_KEY` directly do not. Claude Code and the Claude Agent SDK honor the same profile resolution. `ant auth status` shows which credential source and profile won (it reports status only — don't script against its exit code as a health check); `ant auth logout` clears the active profile (`--all` for every profile). On a remote host without a browser, `ant auth login --no-browser` prints the authorize URL and accepts the code back in the terminal.
+- **Non-interactive workloads** (CI, servers, containers): interactive login is for development on your own machine — use Workload Identity Federation instead (see the authentication docs via `shared/live-sources.md`).
+
+> **The #1 auth trap:** profiles are only consulted when no API key is set. A stale exported `ANTHROPIC_API_KEY` silently overrides every profile — requests hit whatever org/workspace that key is scoped to. `ant auth status` shows which source won; unset the key (or per-command: `env -u ANTHROPIC_API_KEY ant …`) before relying on a profile. Truly **unset** it — an empty `ANTHROPIC_API_KEY=""` still wins its precedence slot and authenticates with an empty key. The same shadowing applies in reverse to Claude Code: after `ant auth login`, Claude Code may warn about an auth conflict between the profile and its own `/login` credential — keep one (use the profile and `/logout` in Claude Code, or `ant auth logout` to keep Claude Code's own login).
+
+**Named profiles** — an interactive-login token is bound to a single org+workspace, and the API only shows resources belonging to that workspace. If an agent, session, or file you created "disappears", the usual cause is a token scoped to a different workspace than the one that created it (`ant auth status` shows the active workspace). Multi-workspace work means one profile per workspace:
+
+```sh
+ant auth login --profile <name>                  # creates the profile if it doesn't exist; org/workspace picker in browser
+ant auth login --profile <name> --workspace-id wrkspc_01...   # bind directly, skip the picker
+ant profile activate <name>                      # switch the default profile
+ant --profile <name> models list                 # one-off; equivalent: ANTHROPIC_PROFILE=<name> ant models list
+ant profile list                                 # inspect
+ant profile set workspace_id wrkspc_01... --profile <name>    # edit config keys (workspace_id, base_url, organization_id, …)
+```
+
+`ant profile set` edits an existing profile's config — it never creates one, and it does **not** rebind already-issued credentials; run `ant auth login` again under that profile to mint a token for the new target. Pointing `ANTHROPIC_PROFILE` at a profile that doesn't exist is an error, not a fall-through. Refresh tokens eventually hard-expire (they don't slide with use) — when a previously working profile starts failing auth, re-run `ant auth login` before debugging anything else.
+
+**Scopes** — a profile's OAuth scope set is requested at login (`--scope`) and persists on the profile (`scope` is also a `profile set` config key; like other config edits, changing it requires a fresh `ant auth login` to take effect). Privileged scopes — e.g. `org:admin` for organization-administration endpoints — are **not** in the default scope set: pass the full set you want explicitly (`ant auth login --profile admin --scope "... org:admin"`), and the server grants a privileged scope only if your role actually has it. Because the scope set rides on every token the profile mints, keep privileged work on a dedicated profile (`admin` vs `default`) and do day-to-day inference on the unprivileged one, switching with `--profile`/`ANTHROPIC_PROFILE`. Check `ant auth login --help` for the current scope list, and `ant auth status` to see what the active token carries.
+
+To hand the active credential to a subprocess or raw-HTTP script:
+
+```sh
+# Bare access token — for curl's Authorization header
+curl https://api.anthropic.com/v1/messages \
+  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: oauth-2025-04-20" \
+  -H "content-type: application/json" \
+  -d '{"model": "claude-opus-4-8", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
+
+# .env format — sets ANTHROPIC_AUTH_TOKEN (and ANTHROPIC_BASE_URL if the profile has one).
+# Output is bare KEY=value (no `export`), so use `set -a` to auto-export for child processes:
+set -a; eval "$(ant auth print-credentials --env)"; set +a
+python my_script.py   # SDK picks up ANTHROPIC_AUTH_TOKEN
+```
+
+OAuth tokens go on `Authorization: Bearer` (not `x-api-key:`) **plus the `anthropic-beta: oauth-2025-04-20` header** — converting a raw curl/httpx script from an API key is a header change, not a key swap. The beta header requirement is endpoint-dependent (some endpoints happen to work without it; `/v1/messages` does not) — always send it so requests don't break when you switch endpoints. The token is short-lived and not auto-refreshed when passed via env var, so re-run `print-credentials` before it expires for long-running scripts (`print-credentials` itself refreshes the token if needed). If both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are set, the SDKs send both and the API rejects the request — unset `ANTHROPIC_API_KEY` before `eval`ing the `--env` output.
+
+**Foot-gun:** `ant auth print-credentials` with **no flags** prints the entire credentials JSON, not the bare token — putting that in an `Authorization` header yields an empty response or HTTP/2 protocol error. Always use `--access-token` for headers (it always reads the named/active profile; a set `ANTHROPIC_API_KEY` doesn't override credential printing).
+
+## Command structure
+
+```
+ant <resource>[:<subresource>] <action> [flags]
+```
+
+Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under `beta:` — the CLI auto-sends the right `anthropic-beta` header, so don't pass it yourself unless overriding with `--beta <header>`. For self-hosted environments, `ant beta:worker poll/run` and `ant beta:environments:work stats/stop` drive and monitor the work queue — see `shared/managed-agents-self-hosted-sandboxes.md`.
+
+```sh
+ant models list
+ant messages create --model claude-opus-4-8 --max-tokens 1024 --message '{role: user, content: "Hello"}'
+ant beta:agents retrieve --agent-id agent_01...
+ant beta:sessions:events list --session-id session_01...
+```
+
+`ant --help` lists resources; append `--help` to any subcommand for its flags.
+
+## Global flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--format` | `auto` (default: pretty if TTY, compact if piped), `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` (interactive TUI) |
+| `--transform` | GJSON path applied to the response (per-item on list endpoints). Not applied when `--format raw`. |
+| `-r`, `--raw-output` | If the transformed result is a string, print it without quotes (jq semantics). Pair with `--transform` for scalar capture. |
+| `--max-items` | Cap total results returned from auto-paginating list endpoints (distinct from `--limit`, which is the server page size). |
+| `--format-error` / `--transform-error` | Same as `--format`/`--transform`, applied to error responses. `-r` does not apply to the error path — use `--format-error yaml` for unquoted error scalars. |
+| `--base-url` | Override API host |
+| `--debug` | Print full HTTP request + response to stderr (API key redacted) |
+
+## Output — `--transform` + `--format`
+
+`--transform` takes a [GJSON path](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). On list endpoints it runs **per item**, not on the envelope.
+
+```sh
+ant beta:agents list --transform '{id,name,model}' --format jsonl
+```
+
+**Extract a scalar for shell use:** pair `--transform` with `-r` (`--raw-output` — prints strings unquoted, jq-style):
+
+```sh
+AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-4-6}' \
+  --transform id -r)
+```
+
+## Input — flags, stdin, `@file`
+
+**Flags** — scalar fields map directly. Structured fields accept relaxed-YAML syntax (unquoted keys) or strict JSON. Repeatable flags build arrays (each `--tool`, `--event`, `--message` appends one element):
+
+```sh
+ant beta:agents create \
+  --name "Research Agent" \
+  --model '{id: claude-opus-4-8}' \
+  --tool '{type: agent_toolset_20260401}' \
+  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'
+```
+
+**Stdin** — pipe a full JSON or YAML body. Merged with flags; flags win on conflict (for array fields, any flag **replaces** the stdin array entirely — it does not append). Quote the heredoc delimiter (`<<'YAML'`) to disable shell expansion inside the body:
+
+```sh
+ant beta:agents create <<'YAML'
+name: Research Agent
+model: claude-opus-4-8
+system: |
+  You are a research assistant. Cite sources for every claim.
+tools:
+  - type: agent_toolset_20260401
+YAML
+```
+
+**`@file` references** — inline a file's contents into any string-valued field. Inside structured flag values, quote the path. Binary files are auto-base64'd; force with `@file://` (text) or `@data://` (base64). Escape a literal leading `@` as `\@`.
+
+```sh
+ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-4-6}' --system @./prompts/researcher.txt
+
+ant messages create --model claude-opus-4-8 --max-tokens 1024 \
+  --message '{role: user, content: [
+    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
+    {type: text, text: "Extract the text from this scanned document."}
+  ]}' \
+  --transform 'content.0.text' -r
+```
+
+Flags that natively take a file path (e.g. `--file` on `beta:files upload`) accept a bare path without `@`.
+
+## Version-controlled Managed Agents resources
+
+This is the recommended flow for defining agents and environments — check the YAML into your repo and sync via `create` (first time) / `update` (thereafter). See `shared/managed-agents-core.md` for the field reference.
+
+```yaml
+# summarizer.agent.yaml
+name: Summarizer
+model: claude-sonnet-4-6
+system: |
+  You are a helpful assistant that writes concise summaries.
+tools:
+  - type: agent_toolset_20260401
+```
+
+```sh
+# Create (once) — capture the ID
+AGENT_ID=$(ant beta:agents create < summarizer.agent.yaml --transform id -r)
+
+# Update (CI) — needs ID + current version (optimistic lock)
+ant beta:agents update --agent-id "$AGENT_ID" --version 1 < summarizer.agent.yaml
+```
+
+Same pattern for environments (`ant beta:environments create|update < env.yaml`), then start a session with both IDs:
+
+```sh
+ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENV_ID" --title "Task"
+ant beta:sessions:events send --session-id "$SID" \
+  --event '{type: user.message, content: [{type: text, text: "Summarize X"}]}'
+ant beta:sessions:events list --session-id "$SID" --transform 'content.0.text' -r
+ant beta:sessions:events stream --session-id "$SID"   # live event stream
+```
+
+### Interactive session loop (stream-before-send)
+
+`ant beta:sessions:events stream` only delivers events emitted *after* the stream opens — so open it **before** sending the kickoff to avoid missing early events. Use process substitution to hold the stream on a file descriptor, send, then read:
+
+```sh
+exec {stream}< <(ant beta:sessions:events stream --session-id "$SID" \
+  --transform '{type,text:content.#(type=="text").text,err:error.message}' --format yaml)
+
+ant beta:sessions:events send --session-id "$SID" > /dev/null <<'YAML'
+events:
+  - type: user.message
+    content:
+      - type: text
+        text: Summarize the repo README
+YAML
+
+type=
+while IFS= read -r -u "$stream" line; do
+  case "$line" in
+    type:\ session.status_idle) break ;;
+    type:\ session.error)
+      IFS= read -r -u "$stream" next || next=
+      case "$next" in err:\ *) msg=${next#err: } ;; *) msg=unknown ;; esac
+      printf '\n[Error: %s]\n' "$msg"; break ;;
+    type:\ *) type=${line#type: } ;;
+    text:*)
+      [[ $type == agent.message ]] || continue
+      val=${line#text: }
+      case "$val" in '|-'|'|') ;; *) printf '%s' "$val" ;; esac ;;
+    \ \ *)
+      if [[ $type == agent.message ]]; then printf '%s\n' "${line#  }"; fi ;;
+  esac
+done
+exec {stream}<&-
+```
+
+This works for interactive exploration and demos. For application code that needs to react to `agent.tool_use` / `agent.custom_tool_use` events, reconnect after drops, or dedup against `events.list`, use the SDK — see `shared/managed-agents-client-patterns.md`.
+
+## Scripting patterns
+
+`--transform id -r` on a list endpoint emits one bare ID per line — compose with `xargs`, or use `--max-items N` to bound the result set without piping through `head`:
+
+```sh
+FIRST=$(ant beta:agents list --transform id -r --max-items 1)
+ant beta:agents:versions list --agent-id "$FIRST" --transform '{version,created_at}' --format jsonl
+```
+
+Error shaping mirrors the success path (note: `-r` does not apply to error output — use `--format-error yaml` for an unquoted scalar here):
+
+```sh
+ant beta:agents retrieve --agent-id bogus --transform-error error.message --format-error yaml 2>&1
+```
+
+Shell completion: `ant @completion {zsh|bash|fish|powershell}`.
+
+For the full, always-current reference (including per-endpoint flags), WebFetch the **Anthropic CLI** URL in `shared/live-sources.md`.