acp: fail honestly in bridge mode (#41424)

Merged via squash.

Prepared head SHA: b5e6e13afe
Co-authored-by: mbelinky <132747814+mbelinky@users.noreply.github.com>
Co-authored-by: mbelinky <132747814+mbelinky@users.noreply.github.com>
Reviewed-by: @mbelinky

docs.acp.md

@@ -17,6 +17,40 @@ Key goals:
 - Works with existing Gateway session store (list/resolve/reset).
 - Safe defaults (isolated ACP session keys by default).
 
+## Bridge Scope
+
+`openclaw acp` is a Gateway-backed ACP bridge, not a full ACP-native editor
+runtime. It is designed to route IDE prompts into an existing OpenClaw Gateway
+session with predictable session mapping and basic streaming updates.
+
+## Compatibility Matrix
+
+| ACP area                                                              | Status      | Notes                                                                                                            |
+| --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `initialize`, `newSession`, `prompt`, `cancel`                        | Implemented | Core bridge flow over stdio to Gateway chat/send + abort.                                                        |
+| `listSessions`, slash commands                                        | Implemented | Session list works against Gateway session state; commands are advertised via `available_commands_update`.       |
+| `loadSession`                                                         | Partial     | Rebinds the ACP session to a Gateway session key. Stored history is not replayed yet.                            |
+| Prompt content (`text`, embedded `resource`, images)                  | Partial     | Text/resources are flattened into chat input; images become Gateway attachments.                                 |
+| Session modes                                                         | Partial     | `session/set_mode` is supported, but this bridge does not yet expose broader ACP-native mode or config surfaces. |
+| Tool streaming                                                        | Partial     | Tool start and result updates are forwarded, but without ACP-native terminal or richer editor metadata.          |
+| Per-session MCP servers (`mcpServers`)                                | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the OpenClaw gateway or agent instead.     |
+| Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods.                                                          |
+| Client terminal methods (`terminal/*`)                                | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls.                       |
+| Session plans / thought streaming                                     | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates.                         |
+
+## Known Limitations
+
+- `loadSession` rebinds to an existing Gateway session, but it does not replay
+  prior user or assistant history yet.
+- If multiple ACP clients share the same Gateway session key, event and cancel
+  routing are best-effort rather than strictly isolated per client. Prefer the
+  default isolated `acp:<uuid>` sessions when you need clean editor-local
+  turns.
+- Gateway stop states are translated into ACP stop reasons, but that mapping is
+  less expressive than a fully ACP-native runtime.
+- Tool follow-along data is intentionally narrow in bridge mode. The bridge
+  does not yet emit ACP terminals, file locations, or structured diffs.
+
 ## How can I use this
 
 Use ACP when an IDE or tooling speaks Agent Client Protocol and you want it to