docs: clarify perSession isolation

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