docs: clarify sandbox non-main behavior

docs/gateway/configuration.md

@@ -1473,6 +1473,7 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 
 Fields:
 - `mainKey`: direct-chat bucket key (default: `"main"`). Useful when you want to “rename” the primary DM thread without changing `agentId`.
+  - Sandbox note: `agent.sandbox.mode: "non-main"` uses this key to detect the main session. Any session key that does not match `mainKey` (groups/channels) is sandboxed.
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
 - `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
 - `sendPolicy.rules[]`: match by `provider`, `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.

docs/gateway/sandboxing.md

@@ -31,6 +31,8 @@ Not sandboxed:
 - `"off"`: no sandboxing.
 - `"non-main"`: sandbox only **non-main** sessions (default if you want normal chats on host).
 - `"all"`: every session runs in a sandbox.
+Note: `"non-main"` is based on `session.mainKey` (default `"main"`), not agent id.
+Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.
 
 ## Scope
 `agent.sandbox.scope` controls **how many containers** are created:

docs/gateway/troubleshooting.md

@@ -122,6 +122,19 @@ or state drift because only one workspace is active.
 **Fix:** keep a single active workspace and archive/remove the rest. See
 [Agent workspace](/concepts/agent-workspace#legacy-workspace-folders).
 
+### Main chat running in a sandbox workspace
+
+Symptoms: `pwd` or file tools show `~/.clawdbot/sandboxes/...` even though you
+expected the host workspace.
+
+**Why:** `agent.sandbox.mode: "non-main"` keys off `session.mainKey` (default `"main"`).
+Group/channel sessions use their own keys, so they are treated as non-main and
+get sandbox workspaces.
+
+**Fix options:**
+- If you want host workspaces for an agent: set `routing.agents.<id>.sandbox.mode: "off"`.
+- If you want host workspace access inside sandbox: set `workspaceAccess: "rw"` for that agent.
+
 ### "Agent was aborted"
 
 The agent was interrupted mid-response.