docs: expand per-agent sandbox profiles

docs/gateway/configuration.md

@@ -359,6 +359,75 @@ Deterministic match order:
 
 Within each match tier, the first matching entry in `routing.bindings` wins.
 
+#### Per-agent access profiles (multi-agent)
+
+Each agent can carry its own sandbox + tool policy. Use this to mix access
+levels in one gateway:
+- **Full access** (personal agent)
+- **Read-only** tools + workspace
+- **No filesystem access** (messaging/session tools only)
+
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence and
+additional examples.
+
+Full access (no sandbox):
+```json5
+{
+  routing: {
+    agents: {
+      personal: {
+        workspace: "~/clawd-personal",
+        sandbox: { mode: "off" }
+      }
+    }
+  }
+}
+```
+
+Read-only tools + read-only workspace:
+```json5
+{
+  routing: {
+    agents: {
+      family: {
+        workspace: "~/clawd-family",
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          workspaceAccess: "ro"
+        },
+        tools: {
+          allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
+          deny: ["write", "edit", "bash", "process", "browser"]
+        }
+      }
+    }
+  }
+}
+```
+
+No filesystem access (messaging/session tools enabled):
+```json5
+{
+  routing: {
+    agents: {
+      public: {
+        workspace: "~/clawd-public",
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          workspaceAccess: "none"
+        },
+        tools: {
+          allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "whatsapp", "telegram", "slack", "discord", "gateway"],
+          deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
+        }
+      }
+    }
+  }
+}
+```
+
 Example: two WhatsApp accounts → two agents:
 
 ```json5

docs/gateway/security.md

@@ -128,12 +128,13 @@ Consider running your AI on a separate phone number from your personal one:
 - Personal number: Your conversations stay private
 - Bot number: AI handles these, with appropriate boundaries
 
-### 4. Read-Only Mode (Future)
+### 4. Read-Only Mode (Today, via sandbox + tools)
 
-We're considering a `readOnlyMode` flag that prevents the AI from:
-- Writing files outside a sandbox
-- Executing shell commands
-- Sending messages
+You can already build a read-only profile by combining:
+- `sandbox.workspaceAccess: "ro"` (or `"none"` for no workspace access)
+- tool allow/deny lists that block `write`, `edit`, `bash`, `process`, etc.
+
+We may add a single `readOnlyMode` flag later to simplify this configuration.
 
 ## Sandboxing (recommended)
 
@@ -153,6 +154,79 @@ Also consider agent workspace access inside the sandbox:
 
 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.
 
+## Per-agent access profiles (multi-agent)
+
+With multi-agent routing, each agent can have its own sandbox + tool policy:
+use this to give **full access**, **read-only**, or **no access** per agent.
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for full details
+and precedence rules.
+
+Common use cases:
+- Personal agent: full access, no sandbox
+- Family/work agent: sandboxed + read-only tools
+- Public agent: sandboxed + no filesystem/shell tools
+
+### Example: full access (no sandbox)
+
+```json5
+{
+  routing: {
+    agents: {
+      personal: {
+        workspace: "~/clawd-personal",
+        sandbox: { mode: "off" }
+      }
+    }
+  }
+}
+```
+
+### Example: read-only tools + read-only workspace
+
+```json5
+{
+  routing: {
+    agents: {
+      family: {
+        workspace: "~/clawd-family",
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          workspaceAccess: "ro"
+        },
+        tools: {
+          allow: ["read"],
+          deny: ["write", "edit", "bash", "process", "browser"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Example: no filesystem/shell access (provider messaging allowed)
+
+```json5
+{
+  routing: {
+    agents: {
+      public: {
+        workspace: "~/clawd-public",
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          workspaceAccess: "none"
+        },
+        tools: {
+          allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "whatsapp", "telegram", "slack", "discord", "gateway"],
+          deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
+        }
+      }
+    }
+  }
+}
+```
+
 ## What to Tell Your AI
 
 Include security guidelines in your agent's system prompt:

docs/install/docker.md

@@ -86,6 +86,18 @@ container. The gateway stays on your host, but the tool execution is isolated:
 Warning: `scope: "shared"` disables cross-session isolation. All sessions share
 one container and one workspace.
 
+### Per-agent sandbox profiles (multi-agent)
+
+If you use multi-agent routing, each agent can override sandbox + tool settings:
+`routing.agents[id].sandbox` and `routing.agents[id].tools`. This lets you run
+mixed access levels in one gateway:
+- Full access (personal agent)
+- Read-only tools + read-only workspace (family/work agent)
+- No filesystem/shell tools (public agent)
+
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for examples,
+precedence, and troubleshooting.
+
 ### Default behavior
 
 - Image: `clawdbot-sandbox:bookworm-slim`