From d38a8d707619bcada6907d023f961052637e821b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 23:17:02 +0100
Subject: [PATCH] docs: clarify elevated sandbox behavior

---
 docs/tools/bash.md     | 2 +-
 docs/tools/elevated.md | 6 ++++++
 docs/tools/index.md    | 2 +-
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/tools/bash.md b/docs/tools/bash.md
index 73106a1e5..89b094dc8 100644
--- a/docs/tools/bash.md
+++ b/docs/tools/bash.md
@@ -17,7 +17,7 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 - `yieldMs` (default 10000): auto-background after delay
 - `background` (bool): background immediately
 - `timeout` (seconds, default 1800): kill on expiry
-- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- `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.
 
 ## Examples
diff --git a/docs/tools/elevated.md b/docs/tools/elevated.md
index eb22ddd91..30275081b 100644
--- a/docs/tools/elevated.md
+++ b/docs/tools/elevated.md
@@ -7,6 +7,7 @@ read_when:
 
 ## What it does
 - Elevated mode allows the bash tool to run with elevated privileges when the feature is available and the sender is approved.
+- **Optional for sandboxed agents**: elevated only changes behavior when the agent is running in a sandbox. If the agent already runs unsandboxed, elevated is effectively a no-op.
 - Directive forms: `/elevated on`, `/elevated off`, `/elev on`, `/elev off`.
 - Only `on|off` are accepted; anything else returns a hint and does not change state.
 
@@ -16,8 +17,13 @@ read_when:
 - **Inline directive**: `/elevated on` inside a message applies to that message only.
 - **Groups**: In group chats, elevated directives are only honored when the agent is mentioned.
 - **Host execution**: elevated runs `bash` on the host (bypasses sandbox).
+- **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.
 
+## 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.
+
 ## Resolution order
 1. Inline directive on the message (applies only to that message).
 2. Session override (set by sending a directive-only message).
diff --git a/docs/tools/index.md b/docs/tools/index.md
index 7f9b2402c..28ce0dbf7 100644
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -36,7 +36,7 @@ Core parameters:
 - `yieldMs` (auto-background after timeout, default 10000)
 - `background` (immediate background)
 - `timeout` (seconds; kills the process if exceeded, default 1800)
-- `elevated` (bool; run on host if elevated mode is enabled/allowed)
+- `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.
 
 Notes: