fix(terminal): clarify configured execution environment

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

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