From dc1992cbb56a6af2a120a23a1eeaf07505500a05 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 23:18:09 +0100
Subject: [PATCH] docs: note elevated no-op when unsandboxed

---
 docs/gateway/sandboxing.md | 1 +
 docs/tools/bash.md         | 1 +
 docs/tools/elevated.md     | 4 ++++
 docs/tools/index.md        | 1 +
 4 files changed, 7 insertions(+)

diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md
index f17dfc27f..a064d72d1 100644
--- a/docs/gateway/sandboxing.md
+++ b/docs/gateway/sandboxing.md
@@ -24,6 +24,7 @@ Not sandboxed:
 - The Gateway process itself.
 - Any tool explicitly allowed to run on the host (e.g. `agent.elevated`).
   - **Elevated bash runs on the host and bypasses sandboxing.**
+  - If sandboxing is off, `agent.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).
 
 ## Modes
 `agent.sandbox.mode` controls **when** sandboxing is used:
diff --git a/docs/tools/bash.md b/docs/tools/bash.md
index 89b094dc8..3c2aef6bc 100644
--- a/docs/tools/bash.md
+++ b/docs/tools/bash.md
@@ -19,6 +19,7 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 - `timeout` (seconds, default 1800): kill on expiry
 - `elevated` (bool): run on host if elevated mode is enabled/allowed (only changes behavior when the agent is sandboxed)
 - Need a real TTY? Use the tmux skill.
+Note: `elevated` is ignored when sandboxing is off (bash already runs on the host).
 
 ## Examples
 
diff --git a/docs/tools/elevated.md b/docs/tools/elevated.md
index 30275081b..482341f54 100644
--- a/docs/tools/elevated.md
+++ b/docs/tools/elevated.md
@@ -20,6 +20,10 @@ read_when:
 - **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `bash` runs.
 - **Tool policy still applies**: if `bash` is denied by tool policy, elevated cannot be used.
 
+Note:
+- Sandbox on: `/elevated on` runs that `bash` command on the host.
+- Sandbox off: `/elevated on` does not change execution (already on host).
+
 ## When elevated matters
 - Only impacts `bash` when the agent is running sandboxed (it drops the sandbox for that command).
 - For unsandboxed agents, elevated does not change execution; it only affects gating, logging, and status.
diff --git a/docs/tools/index.md b/docs/tools/index.md
index 28ce0dbf7..5aa543123 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -44,6 +44,7 @@ Notes:
 - Use `process` to poll/log/write/kill/clear background sessions.
 - If `process` is disallowed, `bash` runs synchronously and ignores `yieldMs`/`background`.
 - `elevated` is gated by `agent.elevated` (global sender allowlist) and runs on the host.
+- `elevated` only changes behavior when the agent is sandboxed (otherwise it’s a no-op).
 
 ### `process`
 Manage background bash sessions.