feat(sandbox): add sandbox explain inspector

docs/cli/sandbox.md

@@ -1,3 +1,10 @@
+---
+title: Sandbox CLI
+summary: "Manage sandbox containers and inspect effective sandbox policy"
+read_when: "You are managing sandbox containers or debugging sandbox/tool-policy behavior."
+status: active
+---
+
 # Sandbox CLI
 
 Manage Docker-based sandbox containers for isolated agent execution.
@@ -8,6 +15,17 @@ Clawdbot can run agents in isolated Docker containers for security. The `sandbox
 
 ## Commands
 
+### `clawdbot sandbox explain`
+
+Inspect the **effective** sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).
+
+```bash
+clawdbot sandbox explain
+clawdbot sandbox explain --session agent:main:main
+clawdbot sandbox explain --agent work
+clawdbot sandbox explain --json
+```
+
 ### `clawdbot sandbox list`
 
 List all sandbox containers with their status and configuration.
@@ -56,7 +74,7 @@ docker pull clawdbot-sandbox:latest
 docker tag clawdbot-sandbox:latest clawdbot-sandbox:bookworm-slim
 
 # Update config to use new image
-# Edit clawdbot.config.json: agent.sandbox.docker.image
+# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
 
 # Recreate containers
 clawdbot sandbox recreate --all
@@ -65,7 +83,7 @@ clawdbot sandbox recreate --all
 ### After changing sandbox configuration
 
 ```bash
-# Edit clawdbot.config.json: agent.sandbox.*
+# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
 
 # Recreate to apply new config
 clawdbot sandbox recreate --all

docs/docs.json

@@ -29,6 +29,14 @@
       "source": "/cron/",
       "destination": "/cron-jobs"
     },
+    {
+      "source": "/sandbox",
+      "destination": "/gateway/sandbox-vs-tool-policy-vs-elevated"
+    },
+    {
+      "source": "/sandbox/",
+      "destination": "/gateway/sandbox-vs-tool-policy-vs-elevated"
+    },
     {
       "source": "/model",
       "destination": "/models"

docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -0,0 +1,77 @@
+---
+title: Sandbox vs Tool Policy vs Elevated
+summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated bash gates"
+read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
+status: active
+---
+
+# Sandbox vs Tool Policy vs Elevated
+
+Clawdbot has three related (but different) controls:
+
+1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
+2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
+3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is a **bash-only escape hatch** to run on the host when you’re sandboxed.
+
+## Quick debug
+
+Use the inspector to see what Clawdbot is *actually* doing:
+
+```bash
+clawdbot sandbox explain
+clawdbot sandbox explain --session agent:main:main
+clawdbot sandbox explain --agent work
+clawdbot sandbox explain --json
+```
+
+It prints:
+- effective sandbox mode/scope/workspace access
+- whether the session is currently sandboxed (main vs non-main)
+- effective sandbox tool allow/deny (and whether it came from agent/global/default)
+- elevated gates and fix-it key paths
+
+## Sandbox: where tools run
+
+Sandboxing is controlled by `agents.defaults.sandbox.mode`:
+- `"off"`: everything runs on the host.
+- `"non-main"`: only non-main sessions are sandboxed (common “surprise” for groups/channels).
+- `"all"`: everything is sandboxed.
+
+See [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).
+
+## Tool policy: which tools exist/are callable
+
+Two layers matter:
+- **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`
+- **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`
+
+Rules of thumb:
+- `deny` always wins.
+- If `allow` is non-empty, everything else is treated as blocked.
+
+## Elevated: bash-only “run on host”
+
+Elevated does **not** grant extra tools; it only affects `bash`.
+- If you’re sandboxed, `/elevated on` (or `bash` with `elevated: true`) runs on the host.
+- If you’re already running direct, elevated is effectively a no-op (still gated).
+
+Gates:
+- Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)
+- Sender allowlists: `tools.elevated.allowFrom.<provider>` (and optionally `agents.list[].tools.elevated.allowFrom.<provider>`)
+
+See [Elevated Mode](/tools/elevated).
+
+## Common “sandbox jail” fixes
+
+### “Tool X blocked by sandbox tool policy”
+
+Fix-it keys (pick one):
+- Disable sandbox: `agents.defaults.sandbox.mode=off` (or per-agent `agents.list[].sandbox.mode=off`)
+- Allow the tool inside sandbox:
+  - remove it from `tools.sandbox.tools.deny` (or per-agent `agents.list[].tools.sandbox.tools.deny`)
+  - or add it to `tools.sandbox.tools.allow` (or per-agent allow)
+
+### “I thought this was main, why is it sandboxed?”
+
+In `"non-main"` mode, group/channel keys are *not* main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
+

docs/gateway/sandboxing.md

@@ -78,6 +78,10 @@ Tool allow/deny policies still apply before sandbox rules. If a tool is denied
 globally or per-agent, sandboxing doesn’t bring it back.
 
 `tools.elevated` is an explicit escape hatch that runs `bash` on the host.
+
+Debugging:
+- Use `clawdbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
+- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.
 Keep it locked down.
 
 ## Multi-agent overrides

docs/multi-agent-sandbox-tools.md

@@ -19,6 +19,7 @@ This allows you to run multiple agents with different security profiles:
 - Public-facing agents in sandboxes
 
 For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing).
+For debugging “why is this blocked?”, see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) and `clawdbot sandbox explain`.
 
 ---
 

docs/tools/elevated.md

@@ -36,7 +36,7 @@ Note:
 ## Setting a session default
 - Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated on`.
 - Confirmation reply is sent (`Elevated mode enabled.` / `Elevated mode disabled.`).
-- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies `elevated is not available right now.` and does not change session state.
+- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error (runtime sandboxed/direct + failing config key paths) and does not change session state.
 - Send `/elevated` (or `/elevated:`) with no argument to see the current elevated level.
 
 ## Availability + allowlists