feat(sandbox): add workspace access mode

docs/gateway/configuration.md

@@ -867,7 +867,10 @@ sessions so they cannot access your host system.
 Defaults (if enabled):
 - scope: `"agent"` (one container + workspace per agent)
 - Debian bookworm-slim based image
-- workspace per agent under `~/.clawdbot/sandboxes`
+- agent workspace access: `workspaceAccess: "none"` (default)
+  - `"none"`: use a per-scope sandbox workspace under `~/.clawdbot/sandboxes`
+  - `"ro"`: keep the sandbox workspace at `/workspace`, and mount the agent workspace read-only at `/agent` (disables `write`/`edit`)
+  - `"rw"`: mount the agent workspace read/write at `/workspace`
 - 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)
@@ -885,6 +888,7 @@ Legacy: `perSession` is still supported (`true` → `scope: "session"`,
     sandbox: {
       mode: "non-main", // off | non-main | all
       scope: "agent", // session | agent | shared (agent is default)
+      workspaceAccess: "none", // none | ro | rw
       workspaceRoot: "~/.clawdbot/sandboxes",
       docker: {
         image: "clawdbot-sandbox:bookworm-slim",
@@ -941,6 +945,8 @@ scripts/sandbox-setup.sh
 Note: sandbox containers default to `network: "none"`; set `agent.sandbox.docker.network`
 to `"bridge"` (or your custom network) if the agent needs outbound access.
 
+Note: inbound attachments are staged into the active workspace at `media/inbound/*`. With `workspaceAccess: "rw"`, that means files are written into the agent workspace.
+
 Build the optional browser image with:
 ```bash
 scripts/sandbox-browser-setup.sh

docs/gateway/security.md

@@ -146,6 +146,11 @@ 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.
 
+Also consider agent workspace access inside the sandbox:
+- `agent.sandbox.workspaceAccess: "none"` (default) keeps the agent workspace off-limits; tools run against a sandbox workspace under `~/.clawdbot/sandboxes`
+- `workspaceAccess: "ro"` mounts the agent workspace read-only at `/agent` (disables `write`/`edit`)
+- `workspaceAccess: "rw"` mounts the agent workspace read/write at `/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.
 
 ## What to Tell Your AI

docs/install/docker.md

@@ -79,8 +79,9 @@ container. The gateway stays on your host, but the tool execution is isolated:
 - scope: `"agent"` by default (one container + workspace per agent)
 - scope: `"session"` for per-session isolation
 - per-scope workspace folder mounted at `/workspace`
+- optional agent workspace access (`agent.sandbox.workspaceAccess`)
 - allow/deny tool policy (deny wins)
-- inbound media is copied into the sandbox workspace (`media/inbound/*`) so tools can read it
+- inbound media is copied into the active sandbox workspace (`media/inbound/*`) so tools can read it (with `workspaceAccess: "rw"`, this lands in the agent workspace)
 
 Warning: `scope: "shared"` disables cross-session isolation. All sessions share
 one container and one workspace.
@@ -89,7 +90,9 @@ one container and one workspace.
 
 - Image: `clawdbot-sandbox:bookworm-slim`
 - One container per agent
-- Workspace per agent under `~/.clawdbot/sandboxes`
+- Agent workspace access: `workspaceAccess: "none"` (default) uses `~/.clawdbot/sandboxes`
+  - `"ro"` keeps the sandbox workspace at `/workspace` and mounts the agent workspace read-only at `/agent` (disables `write`/`edit`)
+  - `"rw"` mounts the agent workspace read/write at `/workspace`
 - 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`
@@ -103,6 +106,7 @@ one container and one workspace.
     sandbox: {
       mode: "non-main", // off | non-main | all
       scope: "agent", // session | agent | shared (agent is default)
+      workspaceAccess: "none", // none | ro | rw
       workspaceRoot: "~/.clawdbot/sandboxes",
       docker: {
         image: "clawdbot-sandbox:bookworm-slim",