docs: explain sandboxed browser control

docs/tools/browser.md

@@ -224,6 +224,13 @@ Flow:
 If the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need `clawdbot browser serve`.
 Use `browser serve` only when the Gateway runs elsewhere (remote mode).
 
+### Sandboxed sessions
+
+If the agent session is sandboxed, the `browser` tool may default to `target="sandbox"` (sandbox browser).
+Chrome extension relay takeover requires host browser control, so either:
+- run the session unsandboxed, or
+- set `agents.defaults.sandbox.browser.allowHostControl: true` and use `target="host"` when calling the tool.
+
 ### Setup
 
 1) Create a profile that uses the extension driver:

docs/tools/chrome-extension.md

@@ -85,6 +85,35 @@ auto-start the local relay server when you use a profile with `driver="extension
 If your Gateway runs on another machine, run `clawdbot browser serve` on the machine that runs Chrome
 (and publish it via Tailscale Serve / TLS). See the section below.
 
+## Sandboxing (tool containers)
+
+If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:
+
+- By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
+- Chrome extension relay takeover requires controlling the **host** browser control server.
+
+Options:
+- Easiest: use the extension from a **non-sandboxed** session/agent.
+- Or allow host browser control for sandboxed sessions:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        browser: {
+          allowHostControl: true
+        }
+      }
+    }
+  }
+}
+```
+
+Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.
+
+Debugging: `clawdbot sandbox explain`
+
 ## Remote Gateway (recommended: Tailscale Serve)
 
 Goal: Gateway runs on one machine, but Chrome runs somewhere else.