claudecode-omc 5.6.5 → 5.6.7

package/bundled/upstream/anthropic-skills/skills/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.

package/bundled/upstream/anthropic-skills/skills/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,
+)
+```
+

package/bundled/upstream/anthropic-skills/skills/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.