From 5ddb9994767bcd5ff69eb5babec4949eea00f372 Mon Sep 17 00:00:00 2001
From: Nathan Flurry <git@nathanflurry.com>
Date: Thu, 29 Jan 2026 08:43:58 -0800
Subject: [PATCH] docs: clarify universal schema support vs native agent
 capabilities

---
 README.md                    | 29 +++++++++++++++++------------
 docs/agent-compatibility.mdx | 31 +++++++++++++++++--------------
 2 files changed, 34 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 247aa19..238335a 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,9 @@
 
 [Documentation](https://sandboxagent.dev/docs) — [Discord](https://rivet.dev/discord)
 
-## Agent Compatibility
+## Universal Schema Support
+
+Which agent features are normalized into the universal event schema. All agents have full native capabilities; this shows what's exposed via the API.
 
 | Feature | [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) | [Codex](https://github.com/openai/codex) | [OpenCode](https://github.com/opencode-ai/opencode) | [Amp](https://ampcode.com) |
 |---------|:-----------:|:-----:|:--------:|:---:|
@@ -25,17 +27,20 @@
 | Text Messages | ✓ | ✓ | ✓ | ✓ |
 | Tool Calls | ✓ | ✓ | ✓ | ✓ |
 | Tool Results | ✓ | ✓ | ✓ | ✓ |
-| Questions (HITL) | ✓ | | ✓ | |
-| Permissions (HITL) | ✓ | | ✓ | |
-| Images | | ✓ | ✓ | |
-| File Attachments | | ✓ | ✓ | |
-| Session Lifecycle | | ✓ | ✓ | |
-| Error Events | | ✓ | ✓ | ✓ |
-| Reasoning/Thinking | | ✓ | | |
-| Command Execution | | ✓ | | |
-| File Changes | | ✓ | | |
-| MCP Tools | | ✓ | | |
-| Streaming Deltas | ✓ | ✓ | ✓ | |
+| Questions (HITL) | ✓ | ○ | ✓ | ○ |
+| Permissions (HITL) | ✓ | ○ | ✓ | ○ |
+| Images | ○ | ✓ | ✓ | ○ |
+| File Attachments | ○ | ✓ | ✓ | ○ |
+| Session Lifecycle | ○ | ✓ | ✓ | ○ |
+| Error Events | ○ | ✓ | ✓ | ✓ |
+| Reasoning/Thinking | ○ | ✓ | | |
+| Command Execution | ○ | ✓ | | |
+| File Changes | ○ | ✓ | | |
+| MCP Tools | ○ | ✓ | | |
+| Streaming Deltas | ✓ | ✓ | ✓ | ○ |
+
+- ✓ = Supported in universal schema
+- ○ = Supported by agent, schema support in progress
 
 Want support for another agent? [Open an issue](https://github.com/rivet-dev/sandbox-agent/issues/new) to request it.
 
diff --git a/docs/agent-compatibility.mdx b/docs/agent-compatibility.mdx
index e4e37be..6c92367 100644
--- a/docs/agent-compatibility.mdx
+++ b/docs/agent-compatibility.mdx
@@ -1,10 +1,10 @@
 ---
-title: "Agent Compatibility"
-description: "Feature support across coding agents."
+title: "Universal Schema Support"
+description: "Which agent features are exposed through the universal API."
 icon: "table"
 ---
 
-The universal API normalizes different coding agents into a consistent interface. Each agent has different native capabilities; the daemon fills gaps with synthetic events where possible.
+The universal API normalizes different coding agents into a consistent interface. All agents have full native capabilities; this page shows what's exposed via the sandbox-agent API.
 
 ## Feature Matrix
 
@@ -14,17 +14,20 @@ The universal API normalizes different coding agents into a consistent interface
 | Text Messages | ✓ | ✓ | ✓ | ✓ |
 | Tool Calls | ✓ | ✓ | ✓ | ✓ |
 | Tool Results | ✓ | ✓ | ✓ | ✓ |
-| Questions (HITL) | ✓ | | ✓ | |
-| Permissions (HITL) | ✓ | | ✓ | |
-| Images | | ✓ | ✓ | |
-| File Attachments | | ✓ | ✓ | |
-| Session Lifecycle | | ✓ | ✓ | |
-| Error Events | | ✓ | ✓ | ✓ |
-| Reasoning/Thinking | | ✓ | | |
-| Command Execution | | ✓ | | |
-| File Changes | | ✓ | | |
-| MCP Tools | | ✓ | | |
-| Streaming Deltas | ✓ | ✓ | ✓ | |
+| Questions (HITL) | ✓ | ○ | ✓ | ○ |
+| Permissions (HITL) | ✓ | ○ | ✓ | ○ |
+| Images | ○ | ✓ | ✓ | ○ |
+| File Attachments | ○ | ✓ | ✓ | ○ |
+| Session Lifecycle | ○ | ✓ | ✓ | ○ |
+| Error Events | ○ | ✓ | ✓ | ✓ |
+| Reasoning/Thinking | ○ | ✓ | | |
+| Command Execution | ○ | ✓ | | |
+| File Changes | ○ | ✓ | | |
+| MCP Tools | ○ | ✓ | | |
+| Streaming Deltas | ✓ | ✓ | ✓ | ○ |
+
+- ✓ = Supported in universal schema
+- ○ = Supported by agent, schema support in progress
 
 ## Feature Descriptions