rivet-dev · NathanFlurry · Mar 3, 2026 · Mar 5, 2026 · Mar 5, 2026 · Mar 6, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -86,6 +86,8 @@
 - Regenerate `docs/openapi.json` when HTTP contracts change.
 - Keep `docs/inspector.mdx` and `docs/sdks/typescript.mdx` aligned with implementation.
 - Append blockers/decisions to `research/acp/friction.md` during ACP work.
+- `docs/agent-capabilities.mdx` lists models/modes/thought levels per agent. Update it when adding a new agent or changing `fallback_config_options`. If its "Last updated" date is >2 weeks old, re-run `cd scripts/agent-configs && npx tsx dump.ts` and update the doc to match. Source data: `scripts/agent-configs/resources/*.json` and hardcoded entries in `server/packages/sandbox-agent/src/router/support.rs` (`fallback_config_options`).
+- Some agent models are gated by subscription (e.g. Claude `opus`). The live report only shows models available to the current credentials. The static doc and JSON resource files should list all known models regardless of subscription tier.
 - TypeScript SDK tests should run against a real running server/runtime over real `/v1` HTTP APIs, typically using the real `mock` agent for deterministic behavior.
 - Do not use Vitest fetch/transport mocks to simulate server functionality in TypeScript SDK tests.
 

diff --git a/docs/agent-capabilities.mdx b/docs/agent-capabilities.mdx
@@ -0,0 +1,127 @@
+---
+title: "Agent Capabilities"
+description: "Models, modes, and thought levels supported by each agent."
+---
+
+Capabilities are subject to change as the agents are updated. See [Agent Sessions](/agent-sessions) for full session configuration API details.
+
+
+<Info>
+    _Last updated: March 5th, 2026. See [Generating a live report](#generating-a-live-report) for up-to-date reference._
+</Info>
+
+## Claude
+
+| Category | Values |
+|----------|--------|
+| **Models** | `default`, `sonnet`, `opus`, `haiku` |
+| **Modes** | `default`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions` |
+| **Thought levels** | Unsupported |
+
+### Configuring Effort Level For Claude
+
+Claude does not natively support changing effort level after a session starts, so configure it in the filesystem before creating the session.
+
+```ts
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { SandboxAgent } from "sandbox-agent";
+
+const cwd = "/path/to/workspace";
+await mkdir(path.join(cwd, ".claude"), { recursive: true });
+await writeFile(
+  path.join(cwd, ".claude", "settings.json"),
+  JSON.stringify({ effortLevel: "high" }, null, 2),
+);
+
+const sdk = await SandboxAgent.connect({ baseUrl: "http://127.0.0.1:2468" });
+await sdk.createSession({
+  agent: "claude",
+  sessionInit: { cwd, mcpServers: [] },
+});
+```
+
+<Accordion title="Supported file locations (highest precedence last)">
+
+1. `~/.claude/settings.json`
+2. `<session cwd>/.claude/settings.json`
+3. `<session cwd>/.claude/settings.local.json`
+
+</Accordion>
+
+## Codex
+
+| Category | Values |
+|----------|--------|
+| **Models** | `gpt-5.3-codex` (default), `gpt-5.3-codex-spark`, `gpt-5.2-codex`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1-codex-mini` |
+| **Modes** | `read-only` (default), `auto`, `full-access` |
+| **Thought levels** | `low`, `medium`, `high` (default), `xhigh` |
+
+## OpenCode
+
+| Category | Values |
+|----------|--------|
+| **Models** | See below |
+| **Modes** | `build` (default), `plan` |
+| **Thought levels** | Unsupported |
+
+<Accordion title="See all models">
+
+| Provider | Models |
+|----------|--------|
+| **Anthropic** | `anthropic/claude-3-5-haiku-20241022`, `anthropic/claude-3-5-haiku-latest`, `anthropic/claude-3-5-sonnet-20240620`, `anthropic/claude-3-5-sonnet-20241022`, `anthropic/claude-3-7-sonnet-20250219`, `anthropic/claude-3-7-sonnet-latest`, `anthropic/claude-3-haiku-20240307`, `anthropic/claude-3-opus-20240229`, `anthropic/claude-3-sonnet-20240229`, `anthropic/claude-haiku-4-5`, `anthropic/claude-haiku-4-5-20251001`, `anthropic/claude-opus-4-0`, `anthropic/claude-opus-4-1`, `anthropic/claude-opus-4-1-20250805`, `anthropic/claude-opus-4-20250514`, `anthropic/claude-opus-4-5`, `anthropic/claude-opus-4-5-20251101`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-0`, `anthropic/claude-sonnet-4-20250514`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-sonnet-4-5-20250929` |
+| **OpenAI** | `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.2`, `openai/gpt-5.2-codex`, `openai/gpt-5.3-codex` |
+| **Cerebras** | `cerebras/gpt-oss-120b`, `cerebras/qwen-3-235b-a22b-instruct-2507`, `cerebras/zai-glm-4.7` |
+| **OpenCode Zen** | `opencode/big-pickle`, `opencode/claude-3-5-haiku`, `opencode/claude-haiku-4-5`, `opencode/claude-opus-4-1`, `opencode/claude-opus-4-5`, `opencode/claude-opus-4-6`, `opencode/claude-sonnet-4`, `opencode/claude-sonnet-4-5`, `opencode/gemini-3-flash`, `opencode/gemini-3-pro` (default), `opencode/glm-4.6`, `opencode/glm-4.7`, `opencode/gpt-5`, `opencode/gpt-5-codex`, `opencode/gpt-5-nano`, `opencode/gpt-5.1`, `opencode/gpt-5.1-codex`, `opencode/gpt-5.1-codex-max`, `opencode/gpt-5.1-codex-mini`, `opencode/gpt-5.2`, `opencode/gpt-5.2-codex`, `opencode/kimi-k2`, `opencode/kimi-k2-thinking`, `opencode/kimi-k2.5`, `opencode/kimi-k2.5-free`, `opencode/minimax-m2.1`, `opencode/minimax-m2.1-free`, `opencode/trinity-large-preview-free` |
+
+</Accordion>
+
+## Cursor
+
+| Category | Values |
+|----------|--------|
+| **Models** | See below |
+| **Modes** | Unsupported |
+| **Thought levels** | Unsupported |
+
+<Accordion title="See all models">
+
+| Group | Models |
+|-------|--------|
+| **Auto** | `auto` |
+| **Composer** | `composer-1.5`, `composer-1` |
+| **GPT-5.3 Codex** | `gpt-5.3-codex`, `gpt-5.3-codex-low`, `gpt-5.3-codex-high`, `gpt-5.3-codex-xhigh`, `gpt-5.3-codex-fast`, `gpt-5.3-codex-low-fast`, `gpt-5.3-codex-high-fast`, `gpt-5.3-codex-xhigh-fast` |
+| **GPT-5.2** | `gpt-5.2`, `gpt-5.2-high`, `gpt-5.2-codex`, `gpt-5.2-codex-low`, `gpt-5.2-codex-high`, `gpt-5.2-codex-xhigh`, `gpt-5.2-codex-fast`, `gpt-5.2-codex-low-fast`, `gpt-5.2-codex-high-fast`, `gpt-5.2-codex-xhigh-fast` |
+| **GPT-5.1** | `gpt-5.1-high`, `gpt-5.1-codex-max`, `gpt-5.1-codex-max-high` |
+| **Claude** | `opus-4.6-thinking` (default), `opus-4.6`, `opus-4.5`, `opus-4.5-thinking`, `sonnet-4.5`, `sonnet-4.5-thinking` |
+| **Other** | `gemini-3-pro`, `gemini-3-flash`, `grok` |
+
+</Accordion>
+
+## Amp
+
+| Category | Values |
+|----------|--------|
+| **Models** | `amp-default` |
+| **Modes** | `default`, `bypass` |
+| **Thought levels** | Unsupported |
+
+## Pi
+
+| Category | Values |
+|----------|--------|
+| **Models** | `default` |
+| **Modes** | Unsupported |
+| **Thought levels** | Unsupported |
+
+## Generating a live report
+
+Requires a running Sandbox Agent server. `--endpoint` defaults to `http://127.0.0.1:2468`.
+
+```bash
+sandbox-agent api agents report
+```
+
+<Note>
+    The live report reflects what the agent adapter returns for the current credentials. Some models may be gated by subscription (e.g. Claude's `opus` requires a paid plan) and will not appear in the report if the credentials don't have access.
+</Note>
diff --git a/docs/agent-sessions.mdx b/docs/agent-sessions.mdx
@@ -82,6 +82,49 @@ if (sessions.items.length > 0) {
 }
 ```
 
+## Configure model, mode, and thought level
+
+Set the model, mode, or thought level on a session at creation time or after:
+
+```ts
+// At creation time
+const session = await sdk.createSession({
+  agent: "codex",
+  model: "gpt-5.3-codex",
+  mode: "plan",
+  thoughtLevel: "high",
+});
+```
+
+```ts
+// After creation
+await session.setModel("gpt-5.2-codex");
+await session.setMode("build");
+await session.setThoughtLevel("medium");
+```
+
+Query available modes:
+
+```ts
+const modes = await session.getModes();
+console.log(modes?.currentModeId, modes?.availableModes);
+```
+
+### Advanced config options
+
+For config options beyond model, mode, and thought level, use `getConfigOptions` to discover what the agent supports and `setConfigOption` to set any option by ID:
+
+```ts
+const options = await session.getConfigOptions();
+for (const opt of options) {
+  console.log(opt.id, opt.category, opt.type);
+}
+```
+
+```ts
+await session.setConfigOption("some-agent-option", "value");
+```
+
 ## Destroy a session
 
 ```ts

diff --git a/docs/cli.mdx b/docs/cli.mdx
@@ -167,6 +167,65 @@ Shared option:
 
 ```bash
 sandbox-agent api agents list [--endpoint <URL>]
+sandbox-agent api agents report [--endpoint <URL>]
 sandbox-agent api agents install <AGENT> [--reinstall] [--endpoint <URL>]
 ```
 
+#### api agents list
+
+List all agents and their install status.
+
+```bash
+sandbox-agent api agents list
+```
+
+#### api agents report
+
+Emit a JSON report of available models, modes, and thought levels for every agent. Calls `GET /v1/agents?config=true` and groups each agent's config options by category.
+
+```bash
+sandbox-agent api agents report --endpoint http://127.0.0.1:2468 | jq .
+```
+
+Example output:
+
+```json
+{
+  "generatedAtMs": 1740000000000,
+  "endpoint": "http://127.0.0.1:2468",
+  "agents": [
+    {
+      "id": "claude",
+      "installed": true,
+      "models": {
+        "currentValue": "default",
+        "values": [
+          { "value": "default", "name": "Default" },
+          { "value": "sonnet", "name": "Sonnet" },
+          { "value": "opus", "name": "Opus" },
+          { "value": "haiku", "name": "Haiku" }
+        ]
+      },
+      "modes": {
+        "currentValue": "default",
+        "values": [
+          { "value": "default", "name": "Default" },
+          { "value": "acceptEdits", "name": "Accept Edits" },
+          { "value": "plan", "name": "Plan" },
+          { "value": "dontAsk", "name": "Don't Ask" },
+          { "value": "bypassPermissions", "name": "Bypass Permissions" }
+        ]
+      },
+      "thoughtLevels": { "values": [] }
+    }
+  ]
+}
+```
+
+See [Agent Capabilities](/agent-capabilities) for a full reference of supported models, modes, and thought levels per agent.
+
+#### api agents install
+
+```bash
+sandbox-agent api agents install codex --reinstall
+```
diff --git a/docs/docs.json b/docs/docs.json
@@ -94,6 +94,7 @@
 					{
 						"group": "Reference",
 						"pages": [
+							"agent-capabilities",
 							"cli",
 							"inspector",
 							"opencode-compatibility",

diff --git a/docs/sdk-overview.mdx b/docs/sdk-overview.mdx
@@ -100,6 +100,25 @@ await restored.prompt([{ type: "text", text: "Continue from previous context." }
 await sdk.destroySession(restored.id);
 ```
 
+## Session configuration
+
+Set model, mode, or thought level at creation or on an existing session:
+
+```ts
+const session = await sdk.createSession({
+  agent: "codex",
+  model: "gpt-5.3-codex",
+});
+
+await session.setModel("gpt-5.2-codex");
+await session.setMode("plan");
+
+const options = await session.getConfigOptions();
+const modes = await session.getModes();
+```
+
+See [Agent Sessions](/agent-sessions) for full details on config options and error handling.
+
 ## Events
 
 Subscribe to live events:
@@ -171,13 +190,3 @@ Parameters:
 - `headers` (optional): Additional request headers
 - `fetch` (optional): Custom fetch implementation used by SDK HTTP and ACP calls
 
-## Types
-
-```ts
-import type {
-  AgentInfo,
-  HealthResponse,
-  SessionEvent,
-  SessionRecord,
-} from "sandbox-agent";
-```