Fix misleading terminal tool description for Windows users

tests/tools/test_tool_description_sandbox.py

@@ -0,0 +1,22 @@
+from tools.terminal_tool import TERMINAL_TOOL_DESCRIPTION
+from tools.code_execution_tool import build_execute_code_schema
+
+
+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
+
+
+def test_execute_code_schema_scopes_sandbox_warning():
+    """execute_code schema should not unconditionally claim cloud sandbox usage."""
+    schema = build_execute_code_schema()
+    description = schema["description"]
+    assert "Sandboxes (when configured)" in description
+    assert "cloud sandbox" not in description

tools/code_execution_tool.py

@@ -1526,6 +1526,9 @@ def build_execute_code_schema(enabled_sandbox_tools: set = None,
         f"Available via `from hermes_tools import ...`:\n\n"
         f"{tool_lines}\n\n"
         "Limits: 5-minute timeout, 50KB stdout cap, max 50 tool calls per script. "
+        "terminal() is foreground-only (no background or pty). "
+        "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.\n\n"
         "terminal() is foreground-only (no background or pty).\n\n"
         f"{cwd_note}\n\n"
         "Print your final result to stdout. Use Python stdlib (json, re, math, csv, "

tools/terminal_tool.py

@@ -510,7 +510,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.
@@ -528,6 +528,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: 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