constellai 0.3.0

package/skills/front-end/claude-api/shared/managed-agents-self-hosted-sandboxes.md

@@ -0,0 +1,174 @@
+# Managed Agents — Self-Hosted Sandboxes
+
+With `config.type: "self_hosted"`, the **agent loop stays on Anthropic's orchestration layer** but **tool execution moves to infrastructure you control** — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with `config.type: "cloud"`, where Anthropic runs the container. Connectivity is **outbound-only**: your worker long-polls Anthropic's work queue; Anthropic never dials into your network.
+
+## Flow
+
+```
+1. Create environment:      config: {type: "self_hosted"}        → env_...
+2. Generate environment key (Console, on the environment page)   → sk-ant-oat01-...  as ANTHROPIC_ENVIRONMENT_KEY
+3. Run a worker:            EnvironmentWorker.run()  or  ant beta:worker poll
+4. Sessions reference       environment_id=env_... exactly as for cloud
+```
+
+## Create the environment
+
+```python
+client = anthropic.Anthropic()
+
+environment = client.beta.environments.create(
+    name="self-hosted", config={"type": "self_hosted"}
+)
+```
+
+`{"type": "self_hosted"}` is the entire config — there are no pool, capacity, or networking sub-fields; you control those on your side.
+
+## Run a worker — SDK (primary path)
+
+`EnvironmentWorker` wraps the poll → dispatch → tool-execute loop. `.run()` is the always-on loop; `.run_one()` / `.runOne()` handles one work item (for webhook-driven wake).
+
+**Python — always-on:**
+
+```python
+import asyncio
+import os
+from anthropic import AsyncAnthropic
+from anthropic.lib.environments import EnvironmentWorker
+
+
+async def main() -> None:
+    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
+    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
+    async with AsyncAnthropic(auth_token=environment_key) as client:
+        await EnvironmentWorker(
+            client,
+            environment_id=environment_id,
+            environment_key=environment_key,
+            workdir="/workspace",
+        ).run()
+
+
+asyncio.run(main())
+```
+
+**TypeScript — always-on:**
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
+
+const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
+const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
+const client = new Anthropic({ authToken: environmentKey });
+const ctrl = new AbortController();
+process.once("SIGTERM", () => ctrl.abort());
+
+await new EnvironmentWorker({
+  client,
+  environmentId,
+  environmentKey,
+  workdir: "/workspace",
+  signal: ctrl.signal
+}).run();
+```
+
+**Customizing tools.** `EnvironmentWorker` runs the built-in toolset by default. To add or replace tools, use `AgentToolContext(workdir=, client=, session_id=)` with `beta_agent_toolset(env)` / `betaAgentToolset(env)` and pass the resulting tools to the lower-level `tool_runner()`. Skills attached to the agent are downloaded into `{workdir}/skills/<name>/` before tool calls begin (`AgentToolContext` handles this when given `client` and `session_id`). Downloaded skill files are marked executable automatically by the CLI and SDK; if you implement skills download yourself, you set permissions.
+
+> **Runtime deps:** the SDK helpers require `/bin/bash` at that exact path. The TypeScript SDK additionally requires `unzip`, `tar`, and Node.js 22+. These are resolved at fixed paths and do **not** respect `PATH` overrides.
+
+## Run a worker — `ant` CLI (fixed tools)
+
+The `ant` CLI ships a worker with the fixed built-in toolset (`bash`, `read`, `write`, `edit`, `glob`, `grep`). Install per `shared/anthropic-cli.md`, then:
+
+```sh
+export ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-...
+ant beta:worker poll --environment-id env_... --workdir /workspace
+```
+
+- `--workdir` is the directory tools operate in (default `.`); tool calls are sandboxed to it.
+- `--environment-key` overrides the env var.
+- `--on-work <script>` runs your script per work item (e.g. to spin a fresh container per session — see Container orchestration below).
+- `--unrestricted-paths`, `--max-idle` (default `60s`), `--log-format` — see `ant beta:worker poll --help`.
+- Flags fall back to env vars (`ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_ENVIRONMENT_KEY`).
+- Exits cleanly on SIGTERM/SIGINT after draining in-flight work.
+- **Fixed toolset** — for custom tools, use the SDK worker above.
+
+Inside an `--on-work` container, run `ant beta:worker run --workdir <dir>` as the entrypoint.
+
+## Webhook-driven wake (instead of always-on)
+
+Register a webhook for `session.status_run_started` (see `shared/managed-agents-webhooks.md`), verify the delivery, then drain one work item with `.run_one()`:
+
+```python
+import os
+import anthropic
+from anthropic.lib.environments import EnvironmentWorker
+
+environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
+environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
+client = anthropic.AsyncAnthropic(
+    auth_token=environment_key,
+)  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env for webhooks.unwrap()
+
+
+async def handle(raw: bytes, headers: dict[str, str]) -> dict:
+    event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
+    if event.data.type != "session.status_run_started":
+        return {"status": "ignored"}
+    await EnvironmentWorker(
+        client,
+        environment_id=environment_id,
+        environment_key=environment_key,
+        workdir="/workspace",
+    ).run_one()
+    return {"status": "ok"}
+```
+
+TypeScript: same shape with `client.beta.webhooks.unwrap(body, {headers})` and `new EnvironmentWorker({...}).runOne()`.
+
+## Container orchestration (mid-level)
+
+`EnvironmentWorker.run()` polls and executes tools in the same process. To run each session in its **own** container, use the mid-level poller in a thin orchestrator — Python `client.beta.environments.work.poller(environment_id=, environment_key=, drain=, block_ms=, reclaim_older_than_ms=, auto_stop=)`; TypeScript `new WorkPoller({client, environmentId, environmentKey, autoStop})` from `@anthropic-ai/sdk/helpers/beta/environments` — and, for each yielded `work` item, start a fresh container with these env vars injected, whose entrypoint runs `ant beta:worker run` or an `EnvironmentWorker(...).run_one()`. `block_ms` is 1–999 (or `None` for non-blocking); `reclaim_older_than_ms` re-claims items leased to a dead worker; `drain` stops once the queue is empty; `auto_stop` posts a stop signal after the iterator exits (set `False` when the launched container owns the stop call). **Go's poller has no `auto_stop` opt-out** — it calls `work.Stop` when the handler returns, so block in the handler until the session completes rather than detaching.
+
+| Env var | Value |
+|---|---|
+| `ANTHROPIC_SESSION_ID` | `work.data.id` |
+| `ANTHROPIC_WORK_ID` | `work.id` |
+| `ANTHROPIC_ENVIRONMENT_ID` | `work.environment_id` |
+| `ANTHROPIC_ENVIRONMENT_KEY` | pass through |
+| `ANTHROPIC_BASE_URL` | pass through |
+
+Skip items where `work.data.type != "session"`.
+
+## Monitoring & control
+
+These are **control-plane** calls — authenticate with `x-api-key` (not the environment key); `managed-agents-2026-04-01` beta header. **Call them from outside the worker host** — setting `ANTHROPIC_API_KEY` on the worker host exposes an organization-scoped credential to agent tool calls.
+
+| SDK (`client.beta.environments.work.*`) | REST | CLI | Returns |
+|---|---|---|---|
+| `stats(environment_id)` | `GET /v1/environments/{id}/work/stats` | `ant beta:environments:work stats` | `{type:"work_queue_stats", depth, pending, oldest_queued_at, workers_polling}` |
+| `stop(work_id, environment_id=)` | `POST /v1/environments/{id}/work/{work_id}/stop` | `ant beta:environments:work stop` | `work.state` |
+
+## What changes vs `cloud`
+
+| Concern | `cloud` | `self_hosted` |
+|---|---|---|
+| Container lifecycle, hardening, networking | Anthropic | **You** — run non-root, read-only rootfs, drop caps; egress is whatever your VPC/firewall allows |
+| `file` / `github_repository` resource mounting | Anthropic mounts into the container | **You** — pass pointers via `sessions.create(metadata={...})` and have your orchestrator fetch/clone before dispatch |
+| `memory_store` resources | Supported | **Not yet supported** |
+| Vault `environment_variable` credentials | Supported (substituted at Anthropic-managed egress) | **Not yet supported** — egress is yours, so there's nowhere to substitute the secret. Use MCP credentials or a host-side custom tool (`shared/managed-agents-client-patterns.md` Pattern 9) |
+| Built-in tools | Via `agent_toolset_20260401` | Supplied by your worker (`EnvironmentWorker` default / `beta_agent_toolset(env)` / `ant` CLI fixed set) |
+| Skills download | Automatic | `EnvironmentWorker` / `AgentToolContext` fetch into `{workdir}/skills/` (needs `client` + `session_id`) |
+| Claude Platform on AWS | Supported | **Not available** |
+| SDK worker helpers | All SDKs | **Python, TypeScript, Go only** (`EnvironmentWorker` / poller not in Java, Ruby, PHP, or C#) — use one of those three or the `ant` CLI |
+
+## Credentials
+
+| Credential | Format | Scope |
+|---|---|---|
+| `ANTHROPIC_ENVIRONMENT_KEY` | `sk-ant-oat01-...` | One environment's work queue. Generate in Console ("Generate environment key"). Pass as `auth_token=` / `authToken` on the client **and** as `environment_key=` / `environmentKey` on `EnvironmentWorker`. Store in a secrets manager; rotate on exposure. |
+| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | `whsec_...` | Webhook signature verification (if using webhook-driven wake). The SDK reads this env var automatically for `client.beta.webhooks.unwrap()`. |
+
+## Security — what you own
+
+Container hardening; egress restriction (there is no default); `ANTHROPIC_ENVIRONMENT_KEY` custody and rotation; one workspace + environment per trust boundary when running untrusted code; least-privilege for the tool process; log retention and redaction. **Anthropic cannot**: fast-revoke a leaked environment key, verify your image or supply chain, sandbox tool execution inside your container, or enforce retention after tool output reaches your infrastructure. See the Self-Hosted Sandboxes Security page in `shared/live-sources.md` for the full checklist.

package/skills/front-end/claude-api/shared/managed-agents-tools.md

@@ -0,0 +1,358 @@
+# 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 (for `cloud` envs; for `self_hosted`, **your** worker supplies and runs them — see `shared/managed-agents-self-hosted-sandboxes.md`) | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. |
+| **MCP tools** (`mcp_toolset`) | Anthropic's orchestration layer | 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.
+
+> 💡 **Changing tools/MCP servers on a running session:** `sessions.update()` can replace `agent.tools`, `agent.mcp_servers`, and `vault_ids` while the session is `idle` — a session-local override that doesn't touch the agent object. See `shared/managed-agents-core.md` → Updating the agent configuration mid-session.
+
+**Large MCP tool outputs.** If an MCP tool returns more than **100K tokens**, the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can `read` the full content. No configuration required.
+
+**Invalid vault credentials don't block session creation.** If a vault credential is invalid for a declared MCP server, the session still creates successfully; a `session.error` event describes the MCP auth failure, and auth retries on the next `session.status_idle` → `session.status_running` transition.
+
+> ⚠️ **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 credential store
+
+**Vaults** store credentials that Anthropic manages on your behalf. Two credential categories:
+
+- **MCP credentials** (`mcp_oauth`, `static_bearer`) — keyed by `mcp_server_url`. When the agent connects to a server at that URL, the token is injected automatically. `mcp_oauth` tokens are auto-refreshed via the standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers.
+- **Environment variables** (`environment_variable`) — keyed by `secret_name` (the env var name). The sandbox sees only an **opaque placeholder**; the real secret is substituted into the outbound request **at egress**. Use this for any service that authenticates through an environment variable: CLIs (`aws`, `gcloud`, `stripe`), SDKs, or direct `curl` calls from the `bash` tool.
+
+Secret fields you supply (`token`, `access_token`, `refresh_token`, `client_secret`, `secret_value`) are write-only — never returned in API responses.
+
+#### 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.
+- **Environment-variable credentials** appear in the sandbox as an opaque placeholder; the real value replaces the placeholder at egress, on requests to the credential's allowed hosts only.
+
+**When vault credentials don't fit** (e.g. self-hosted sandboxes — `environment_variable` is not yet supported there), **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 credentials to it (`client.beta.vaults.credentials.create(...)`) — MCP credentials are keyed by MCP server URL; environment-variable credentials by `secret_name`
+3. Reference the vault on session create via `vault_ids: ["vlt_..."]`
+4. Anthropic auto-refreshes OAuth tokens before they expire and substitutes secrets at runtime
+
+**MCP OAuth 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.
+
+**Environment-variable credential shape**:
+
+```json
+{
+  "display_name": "Twilio API key for sandbox",
+  "auth": {
+    "type": "environment_variable",
+    "secret_name": "TWILIO_API_KEY",
+    "secret_value": "sk-your-secret-here",
+    "networking": {
+      "type": "limited",
+      "allowed_hosts": ["api.twilio.com", "*.twilio.com"]
+    }
+  }
+}
+```
+
+`networking.allowed_hosts` controls which outbound hosts the secret can be substituted for — `{"type": "limited", "allowed_hosts": [...]}` or `{"type": "unrestricted"}` if you can't enumerate the domains in advance. Limiting is strongly recommended: it prevents the key from ever being sent to unauthorized hosts.
+
+> ⚠️ **Two networking layers, both required.** `networking.allowed_hosts` on the credential controls which requests *use the secret*, not which requests are *allowed*. The agent must also be able to reach the domain at the **environment level** (`unrestricted`, or the host listed in the environment's `allowed_hosts` — see `shared/managed-agents-environments.md`). A domain missing from either layer means the secret-substituted request fails.
+
+> ⚠️ **Client-side validation caveat.** Substitution happens at egress, not inside the sandbox — clients that validate the credential *format* locally before making a network request (e.g. a CLI that checks the key starts with `sk-`) will see the opaque placeholder and may fail at startup. If a client rejects the credential before any network call, that's why.
+
+> 💡 **Scope the key minimally.** The agent can do anything the key allows; a key with broader permissions than the task needs increases the blast radius if the agent behaves unexpectedly.
+
+**Not supported with self-hosted sandboxes** — `environment_variable` credentials require Anthropic-managed egress. See `shared/managed-agents-self-hosted-sandboxes.md`.
+
+**Constraints (all credential types):**
+
+- **Unique key per vault.** `mcp_server_url` (MCP credentials) and `secret_name` (environment-variable credentials) must be unique among active credentials in a vault; duplicates return a 409.
+- **Keys are immutable.** Secret values and `display_name` can be updated (rotation); to change `mcp_server_url`, `secret_name`, `token_endpoint`, or `client_id`, archive the credential and create a new one. Archiving purges the secret and frees the key for a replacement.
+- **Maximum 20 credentials per vault.**
+- Credentials are stored as provided and **not validated until session runtime** — an invalid credential surfaces as an authentication or downstream error during the session, which is emitted but does not block the session from continuing.
+
+**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-8",
+    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-8",
+    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}`            |
+

package/skills/front-end/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.