feat: add sandbox scope default

docs/gateway/configuration.md

@@ -629,7 +629,7 @@ Default: `~/clawd`.
 ```
 
 If `agent.sandbox` is enabled, non-main sessions can override this with their
-own per-session workspaces under `agent.sandbox.workspaceRoot`.
+own per-scope workspaces under `agent.sandbox.workspaceRoot`.
 
 ### `agent.skipBootstrap`
 
@@ -847,27 +847,30 @@ per session key at a time). Default: 1.
 
 ### `agent.sandbox`
 
-Optional per-session **Docker sandboxing** for the embedded agent. Intended for
-non-main sessions so they cannot access your host system.
+Optional **Docker sandboxing** for the embedded agent. Intended for non-main
+sessions so they cannot access your host system.
 
 Defaults (if enabled):
-- one container per session
+- scope: `"agent"` (one container + workspace per agent)
 - Debian bookworm-slim based image
-- workspace per session under `~/.clawdbot/sandboxes`
+- workspace per agent under `~/.clawdbot/sandboxes`
 - auto-prune: idle > 24h OR age > 7d
 - tools: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn` (deny wins)
 - 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.
+Warning: `scope: "shared"` means a shared container and shared workspace. No
+cross-session isolation. Use `scope: "session"` for per-session isolation.
+
+Legacy: `perSession` is still supported (`true` → `scope: "session"`,
+`false` → `scope: "shared"`).
 
 ```json5
 {
   agent: {
     sandbox: {
       mode: "non-main", // off | non-main | all
-      perSession: true, // recommended for isolation (false = shared container/workspace)
+      scope: "agent", // session | agent | shared (agent is default)
       workspaceRoot: "~/.clawdbot/sandboxes",
       docker: {
         image: "clawdbot-sandbox:bookworm-slim",

docs/gateway/security.md

@@ -140,10 +140,11 @@ We're considering a `readOnlyMode` flag that prevents the AI from:
 Two complementary approaches:
 
 - **Run the full Gateway in Docker** (container boundary): [Docker](/install/docker)
-- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/gateway/configuration)
+- **Tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/gateway/configuration)
 
-Note: to prevent cross-agent access, keep `perSession: true` so each session gets
-its own container + workspace. `perSession: false` shares a single container.
+Note: to prevent cross-agent access, keep `sandbox.scope` at `"agent"` (default)
+or `"session"` for stricter per-session isolation. `scope: "shared"` uses a
+single container/workspace.
 
 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.
 

docs/install/docker.md

@@ -70,25 +70,26 @@ pnpm test:docker:qr
 - Gateway bind defaults to `lan` for container use.
 - The gateway container is the source of truth for sessions (`~/.clawdbot/agents/<agentId>/sessions/`).
 
-## Per-session Agent Sandbox (host gateway + Docker tools)
+## Agent Sandbox (host gateway + Docker tools)
 
 ### What it does
 
 When `agent.sandbox` is enabled, **non-main sessions** run tools inside a Docker
 container. The gateway stays on your host, but the tool execution is isolated:
-- one container per session (hard wall)
-- per-session workspace folder mounted at `/workspace`
+- scope: `"agent"` by default (one container + workspace per agent)
+- scope: `"session"` for per-session isolation
+- per-scope workspace folder mounted at `/workspace`
 - 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.
+Warning: `scope: "shared"` disables cross-session isolation. All sessions share
+one container and one workspace.
 
 ### Default behavior
 
 - Image: `clawdbot-sandbox:bookworm-slim`
-- One container per session
-- Workspace per session under `~/.clawdbot/sandboxes`
+- One container per agent
+- Workspace per agent under `~/.clawdbot/sandboxes`
 - Auto-prune: idle > 24h OR age > 7d
 - Network: `none` by default (explicitly opt-in if you need egress)
 - Default allow: `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`
@@ -101,7 +102,7 @@ share one container and one workspace, so there is no cross-session isolation.
   agent: {
     sandbox: {
       mode: "non-main", // off | non-main | all
-      perSession: true,
+      scope: "agent", // session | agent | shared (agent is default)
       workspaceRoot: "~/.clawdbot/sandboxes",
       docker: {
         image: "clawdbot-sandbox:bookworm-slim",