From e66b433d2f7a0742e490ce16606153631048a617 Mon Sep 17 00:00:00 2001
From: Billard <82095453+iacker@users.noreply.github.com>
Date: Sun, 12 Apr 2026 14:59:21 +0200
Subject: [PATCH] fix(terminal): clarify configured execution environment

---
 tests/tools/test_terminal_tool_description.py | 13 +++++++++++++
 tools/terminal_tool.py                        |  4 ++--
 2 files changed, 15 insertions(+), 2 deletions(-)
 create mode 100644 tests/tools/test_terminal_tool_description.py

diff --git a/tests/tools/test_terminal_tool_description.py b/tests/tools/test_terminal_tool_description.py
new file mode 100644
index 000000000000..95cc413b2be8
--- /dev/null
+++ b/tests/tools/test_terminal_tool_description.py
@@ -0,0 +1,13 @@
+from tools.terminal_tool import TERMINAL_TOOL_DESCRIPTION
+
+
+def test_terminal_tool_description_mentions_configured_environment():
+    assert "configured environment" in TERMINAL_TOOL_DESCRIPTION
+    assert "local machine" in TERMINAL_TOOL_DESCRIPTION
+    assert "Docker container" in TERMINAL_TOOL_DESCRIPTION
+    assert "Linux environment" not in TERMINAL_TOOL_DESCRIPTION
+
+
+def test_terminal_tool_description_scopes_sandbox_warning():
+    assert "sandboxes (when configured)" in TERMINAL_TOOL_DESCRIPTION
+    assert "cloud sandboxes may be cleaned up" not in TERMINAL_TOOL_DESCRIPTION
diff --git a/tools/terminal_tool.py b/tools/terminal_tool.py
index 3dfa786e1ad6..647cc5ae1d4d 100644
--- a/tools/terminal_tool.py
+++ b/tools/terminal_tool.py
@@ -513,7 +513,7 @@ def _transform_sudo_command(command: str | None) -> tuple[str | None, str | None
 
 
 # Tool description for LLM
-TERMINAL_TOOL_DESCRIPTION = """Execute shell commands on a Linux environment. Filesystem usually persists between calls.
+TERMINAL_TOOL_DESCRIPTION = """Execute shell commands in the configured environment (local machine, Docker container, or cloud sandbox depending on setup). Filesystem usually persists between calls.
 
 Do NOT use cat/head/tail to read files — use read_file instead.
 Do NOT use grep/rg/find to search — use search_files instead.
@@ -531,7 +531,7 @@ def _transform_sudo_command(command: str | None) -> tuple[str | None, str | None
 PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL).
 
 Do NOT use vim/nano/interactive tools without pty=true — they hang without a pseudo-terminal. Pipe git output to cat if it might page.
-Important: cloud sandboxes may be cleaned up, idled out, or recreated between turns. Persistent filesystem means files can resume later; it does NOT guarantee a continuously running machine or surviving background processes. Use terminal sandboxes for task work, not durable hosting.
+Important: sandboxes (when configured) may be cleaned up, idled out, or recreated between turns. Persistent filesystem means files can resume later; it does NOT guarantee a continuously running machine or surviving background processes. Use terminal sandboxes for task work, not durable hosting.
 """
 
 # Global state for environment lifecycle management