docs: clarify perSession isolation

CHANGELOG.md

@@ -70,6 +70,7 @@
 - Model: avoid duplicate `missing (missing)` auth labels in `/model` list output.
 - Auth: when `openai` has no API key but Codex OAuth exists, suggest `openai-codex/gpt-5.2` vs `OPENAI_API_KEY`.
 - Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding.
+- Docs: clarify per-session sandbox isolation and `perSession` sharing risks.
 - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments.
 - Sandbox: enable session tools in sandboxed sessions with spawned-only visibility by default (opt-in `agent.sandbox.sessionToolsVisibility = "all"`).
 - Control UI: show a reading indicator bubble while the assistant is responding.

docs/configuration.md

@@ -859,12 +859,15 @@ Defaults (if enabled):
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
 
+Warning: `perSession: false` means a shared container and shared workspace. No
+cross-session isolation.
+
 ```json5
 {
   agent: {
     sandbox: {
       mode: "non-main", // off | non-main | all
-      perSession: true,
+      perSession: true, // recommended for isolation (false = shared container/workspace)
       workspaceRoot: "~/.clawdbot/sandboxes",
       docker: {
         image: "clawdbot-sandbox:bookworm-slim",

docs/docker.md

@@ -81,6 +81,9 @@ container. The gateway stays on your host, but the tool execution is isolated:
 - allow/deny tool policy (deny wins)
 - inbound media is copied into the sandbox workspace (`media/inbound/*`) so tools can read it
 
+Warning: setting `perSession: false` disables per-session isolation. All sessions
+share one container and one workspace, so there is no cross-session isolation.
+
 ### Default behavior
 
 - Image: `clawdbot-sandbox:bookworm-slim`

docs/security.md

@@ -141,6 +141,9 @@ Two complementary approaches:
 - **Run the full Gateway in Docker** (container boundary): https://docs.clawd.bot/docker
 - **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): https://docs.clawd.bot/configuration
 
+Note: to prevent cross-agent access, keep `perSession: true` so each session gets
+its own container + workspace. `perSession: false` shares a single container.
+
 Important: `agent.elevated` is an explicit escape hatch that runs bash on the host. Keep `agent.elevated.allowFrom` tight and don’t enable it for strangers.
 
 ## What to Tell Your AI