Skip to content

The agent that grows with you

feat(tools): terminal backends can declare that file tools go through the sandbox

Teknium72fc7dfe9bb9
diff --git a/tests/tools/test_file_tools_confined_backend.py b/tests/tools/test_file_tools_confined_backend.py
new file mode 100644
index 00000000000..0d043cccb00
--- /dev/null
+++ b/tests/tools/test_file_tools_confined_backend.py
@@ -0,0 +1,89 @@
+"""A backend that confines execution keeps the file tools inside it.
+
+The file tools answer reads, writes, patches and searches on the host when the terminal backend runs
+on the host. A backend that subclasses ``LocalEnvironment`` but confines its commands (a bubblewrap
+sandbox: bind mounts, read-only paths, its own ``$TMPDIR``) sets ``uses_host_filesystem = False``, and
+then every file tool goes through ``env.execute`` and sees what the sandbox sees.
+
+The test backend exposes a real directory under a second path, the way a bind mount does: the view
+path exists only for commands it runs, so a tool result that names it came through ``execute``.
+"""
+
+import json
+
+import pytest
+
+from tools import terminal_tool
+from tools.environments.local import LocalEnvironment
+from tools.file_tools import clear_file_ops_cache
+from tools.registry import registry
+
+
+class _MountedViewEnv(LocalEnvironment):
+ """Commands see ``real`` at ``view``; the host sees only ``real``."""
+
+ def __init__(self, view: str, real: str):
+ super().__init__(cwd=real, timeout=30, persistent=False)
+ self._view, self._real = view, real
+
+ def execute(self, command, cwd="", **kwargs):
+ result = super().execute(command.replace(self._view, self._real),
+ cwd=cwd.replace(self._view, self._real), **kwargs)
+ result["output"] = result.get("output", "").replace(self._real, self._view)
+ return result
+
+
+class _ConfinedEnv(_MountedViewEnv):
+ uses_host_filesystem = False
+
+
+def _dispatch(name, task_id, **arguments):
+ return json.loads(registry.dispatch(name, arguments, task_id=task_id))
+
+
+def mounted(tmp_path, monkeypatch, request):
+ """``(env, view, real, task_id)`` with the env active for the task; ``a.txt`` holds two lines."""
+ view, real = tmp_path / "view", tmp_path / "real"
+ real.mkdir()
+ (real / "a.txt").write_text("alpha\nbeta\n", encoding="utf-8")
+ env = request.param(str(view), str(real))
+ task_id = f"confined-{request.node.name}"
+ monkeypatch.setitem(terminal_tool._active_environments, terminal_tool._resolve_container_task_id(task_id), env)
+ yield env, view, real, task_id
+ clear_file_ops_cache()
+ env.cleanup()
+
+
[email protected]("mounted", [_ConfinedEnv], indirect=True)
+def test_confined_backend_runs_every_file_tool_through_execute(mounted):
+ _env, view, real, task = mounted
+
+ read = _dispatch("read_file", task, path=str(view / "a.txt"))
+ assert "alpha" in read.get("content", ""), read
+
+ written = _dispatch("write_file", task, path=str(view / "b.txt"), content="gamma\n")
+ assert "error" not in written, written
+ assert (real / "b.txt").read_text(encoding="utf-8") == "gamma\n"
+
+ patched = _dispatch("patch", task, path=str(view / "a.txt"), old_string="beta", new_string="delta")
+ assert "error" not in patched, patched
+ assert (real / "a.txt").read_text(encoding="utf-8") == "alpha\ndelta\n"
+
+ found = _dispatch("search_files", task, pattern="delta", path=str(view))
+ assert [m["path"] for m in found.get("matches", [])] == [str(view / "a.txt")], found
+
+ assert not view.exists(), "a file tool touched the host path instead of the sandbox"
+
+
[email protected]("mounted", [_MountedViewEnv], indirect=True)
+def test_host_backend_keeps_the_host_fast_path(mounted):
+ _env, view, real, task = mounted
+
+ read = _dispatch("read_file", task, path=str(view / "a.txt"))
+ assert "alpha" not in json.dumps(read), read
+
+ written = _dispatch("write_file", task, path=str(view / "b.txt"), content="gamma\n")
+ assert "error" not in written, written
+ assert (view / "b.txt").read_text(encoding="utf-8") == "gamma\n"
+ assert not (real / "b.txt").exists()
diff --git a/tests/tools/test_tool_result_storage.py b/tests/tools/test_tool_result_storage.py
index de8014cee6b..e0ef3542d28 100644
--- a/tests/tools/test_tool_result_storage.py
+++ b/tests/tools/test_tool_result_storage.py
@@ -422,6 +422,7 @@ class TestSpillover:
from tools.environments.local import LocalEnvironment
env = MagicMock(spec=LocalEnvironment)
+ env.uses_host_filesystem = LocalEnvironment.uses_host_filesystem
content = "y" * 60_000
result = maybe_persist_tool_result(
content=content,
diff --git a/tools/environments/base.py b/tools/environments/base.py
index 7b8e371d2fb..7895a2c803d 100644
--- a/tools/environments/base.py
+++ b/tools/environments/base.py
@@ -248,6 +248,13 @@ def _file_mtime_key(host_path: str) -> tuple[int, int, int, int] | None:
return None
+def env_uses_host_filesystem(env: object) -> bool:
+ """Whether the file tools may touch *env*'s files on the host (``BaseEnvironment.uses_host_filesystem``).
+ Strict ``is True``: an environment without the declaration (``None``, a duck-typed plugin
+ backend, a test double) is not the host."""
+ return getattr(env, "uses_host_filesystem", False) is True
+
+
# ---------------------------------------------------------------------------
# BaseEnvironment
# ---------------------------------------------------------------------------
@@ -268,6 +275,12 @@ class BaseEnvironment(ABC):
# (LocalEnvironment); controller-host facts then describe the execution target.
is_local: bool = False
+ # True when the file tools may read, write, patch and search this backend's files straight on
+ # the host instead of through execute() (only LocalEnvironment). A host backend that confines its
+ # commands (a sandbox hiding paths, mounting them read-only or giving them their own $TMPDIR) sets
+ # it False, so the file tools see exactly what its commands see. Read via env_uses_host_filesystem().
+ uses_host_filesystem: bool = False
+
# Snapshot creation timeout (override for slow cold-starts).
_snapshot_timeout: int = 30
diff --git a/tools/environments/local.py b/tools/environments/local.py
index 6567d0d06dc..7b8edef590c 100644
--- a/tools/environments/local.py
+++ b/tools/environments/local.py
@@ -1013,6 +1013,8 @@ class LocalEnvironment(BaseEnvironment):
# Commands run on the Hermes host itself — controller-side platform behavior
# (macOS TCC pruning, etc.) legitimately applies here.
is_local = True
+ # A subclass that confines its commands (a sandbox) sets this False: see BaseEnvironment.
+ uses_host_filesystem = True
def _additional_profile_scoped_passthrough_names(self) -> tuple[str, ...]:
"""First-party ``BUZZ_*`` names present in the env, excluded from the shared
diff --git a/tools/file_operations.py b/tools/file_operations.py
index efc2aa07e60..f94340c535e 100644
--- a/tools/file_operations.py
+++ b/tools/file_operations.py
@@ -910,15 +910,15 @@ class ShellFileOperations(LintMixin, SearchMixin, FileOperations):
file_size=file_size, file_ends_with_newline=file_ends_with_newline)
def _native_read_enabled(self) -> bool:
- """Whether ``read_file`` and ``search_files`` may bypass the shell: only POSIX + ``LocalEnvironment``
- (file is on this host, path already native; Windows keeps the shell path since
- file_operations holds Git-Bash-style paths there). ``HERMES_NATIVE_FILE_READ=0``
- turns the fast path off."""
+ """Whether ``read_file`` and ``search_files`` may bypass the shell: only POSIX + a backend whose
+ files are the host's (``uses_host_filesystem``: the file is on this host, path already native;
+ Windows keeps the shell path since file_operations holds Git-Bash-style paths there).
+ ``HERMES_NATIVE_FILE_READ=0`` turns the fast path off."""
flag = os.environ.get("HERMES_NATIVE_FILE_READ", "1").strip().lower()
if flag in ("0", "false", "no", "off"):
return False
- # Same "is this env the local host" test the LSP path uses; isinstance is
- # microseconds and self.env is never rebound, so nothing to memoize.
+ # Same "are these the host's files" test the LSP path uses; an attribute read
+ # and self.env is never rebound, so nothing to memoize.
return sys.platform != "win32" and self._lsp_local_only()
def _native_path(self, path: str) -> str:
diff --git a/tools/file_operations_lint.py b/tools/file_operations_lint.py
index 8012415f2d3..26bfd932c62 100644
--- a/tools/file_operations_lint.py
+++ b/tools/file_operations_lint.py
@@ -243,16 +243,11 @@ class LintMixin:
))
def _lsp_local_only(self) -> bool:
- """True iff wired to a local backend. LSP servers run on the host and
- can't see files inside Docker/Modal/SSH/Daytona sandboxes."""
- env = getattr(self, "env", None) # tests may build via __new__ without __init__
- if env is None:
- return False
- try:
- from tools.environments.local import LocalEnvironment
- except Exception:
- return False
- return isinstance(env, LocalEnvironment)
+ """True iff the backend's files are the host's (``uses_host_filesystem``). LSP servers run on
+ the host and can't see files inside Docker/Modal/SSH/Daytona or a confining local sandbox."""
+ from tools.environments.base import env_uses_host_filesystem
+
+ return env_uses_host_filesystem(getattr(self, "env", None)) # tests may build via __new__
def _local_workspace_untrusted(self) -> bool:
"""True iff on a local backend the linter's cwd lies outside every trusted workspace
diff --git a/tools/file_operations_search.py b/tools/file_operations_search.py
index e3186b3f502..496e9d9025d 100644
--- a/tools/file_operations_search.py
+++ b/tools/file_operations_search.py
@@ -60,10 +60,11 @@ _FILENAME_SEARCH_WAIT_SECONDS = 0.05
def _normalized_filename_search_root(env: Any, root: str, fallback_cwd: str) -> str:
"""Normalize a filename-walk root without resolving remote paths locally."""
- from tools.environments.local import LocalEnvironment, _IS_WINDOWS, _msys_to_windows_path
+ from tools.environments.base import env_uses_host_filesystem
+ from tools.environments.local import _IS_WINDOWS, _msys_to_windows_path
cwd = getattr(env, "cwd", None) or fallback_cwd
- if isinstance(env, LocalEnvironment):
+ if env_uses_host_filesystem(env):
if _IS_WINDOWS:
root = _msys_to_windows_path(root)
cwd = _msys_to_windows_path(cwd)
@@ -293,11 +294,13 @@ class SearchMixin:
cached = self._rg_resolution_cache.get(cmd)
if cached:
return cached
- from tools.environments.local import LocalEnvironment, _IS_WINDOWS
+ from tools.environments.base import env_uses_host_filesystem
+ from tools.environments.local import _IS_WINDOWS
- # A local search is Hermes's own work, so it runs the pinned ripgrep, never the
+ # A host search is Hermes's own work, so it runs the pinned ripgrep, never the
# first rg on the terminal PATH, where the user's tools come first.
- bundled = _bundled_rg() if isinstance(self.env, LocalEnvironment) else None
+ on_host = env_uses_host_filesystem(self.env)
+ bundled = _bundled_rg() if on_host else None
if bundled:
self._rg_resolution_cache[cmd] = bundled
return bundled
@@ -309,7 +312,7 @@ class SearchMixin:
self._rg_resolution_cache[cmd] = resolved
return resolved
- if _IS_WINDOWS and isinstance(self.env, LocalEnvironment):
+ if _IS_WINDOWS and on_host:
user_profile = os.environ.get("USERPROFILE") or str(Path.home())
local_app_data = os.environ.get("LOCALAPPDATA")
scoop = os.environ.get("SCOOP") or os.path.join(user_profile, "scoop")
@@ -430,9 +433,9 @@ class SearchMixin:
"""Quote an executable without leaking controller path semantics."""
if re.fullmatch(r"[A-Za-z0-9_.-]+", executable):
return executable
- from tools.environments.local import LocalEnvironment
+ from tools.environments.base import env_uses_host_filesystem
- if isinstance(self.env, LocalEnvironment):
+ if env_uses_host_filesystem(self.env):
return self._escape_native_tool_arg(executable)
return "'" + executable.replace("'", "'\"'\"'") + "'"
@@ -656,9 +659,10 @@ class SearchMixin:
def _is_broad_local_search_root(self, path: str) -> bool:
"""Whether a no-rg LOCAL root (filesystem root, $HOME or an ancestor of it) is
unsafe for recursive find. Controller paths never classify remotes."""
- from tools.environments.local import LocalEnvironment, _IS_WINDOWS, _msys_to_windows_path
+ from tools.environments.base import env_uses_host_filesystem
+ from tools.environments.local import _IS_WINDOWS, _msys_to_windows_path
- if not isinstance(self.env, LocalEnvironment):
+ if not env_uses_host_filesystem(self.env):
return False
def normalized(value: str) -> str:
@@ -908,8 +912,9 @@ class SearchMixin:
"-printf support; install ripgrep 14+ or use order='discovery'."))
return SearchResult(error="File search failed while running bounded find traversal.")
- from tools.environments.local import LocalEnvironment, _IS_WINDOWS, _msys_to_windows_path
- if _IS_WINDOWS and isinstance(self.env, LocalEnvironment):
+ from tools.environments.base import env_uses_host_filesystem
+ from tools.environments.local import _IS_WINDOWS, _msys_to_windows_path
+ if _IS_WINDOWS and env_uses_host_filesystem(self.env):
raw_files = [_msys_to_windows_path(file_path) for file_path in raw_files]
return SearchResult(
files=raw_files[offset:offset + limit], total_count=len(raw_files),
diff --git a/tools/file_tools.py b/tools/file_tools.py
index 5dbdce7479f..553a79d19b5 100644
--- a/tools/file_tools.py
+++ b/tools/file_tools.py
@@ -138,11 +138,9 @@ def _file_ops_uses_host_paths(file_ops) -> bool:
env = getattr(file_ops, "env", None)
if env is None:
return True
- try:
- from tools.environments.local import LocalEnvironment
- except ImportError:
- return True
- return isinstance(env, LocalEnvironment)
+ from tools.environments.base import env_uses_host_filesystem
+
+ return env_uses_host_filesystem(env)
# V4A file headers: group 1 = header prefix, 2 = op, 3 = path. ``\s*`` after
diff --git a/tools/tool_result_storage.py b/tools/tool_result_storage.py
index 8ccf4dd73c1..39407dc51af 100644
--- a/tools/tool_result_storage.py
+++ b/tools/tool_result_storage.py
@@ -182,14 +182,12 @@ def _prune_spillover_once() -> None:
def _is_host_side_env(env) -> bool:
"""True when this process should write the spill file directly: ``env=None`` (no sandbox
- yet) or the local backend. Remote backends resolve ``read_file`` inside the sandbox."""
+ yet) or a backend whose files are the host's. Others resolve ``read_file`` inside the sandbox."""
if env is None:
return True
- try:
- from tools.environments.local import LocalEnvironment
- return isinstance(env, LocalEnvironment)
- except Exception:
- return False
+ from tools.environments.base import env_uses_host_filesystem
+
+ return env_uses_host_filesystem(env)
def _write_to_spillover(content: str, filename: str):
diff --git a/website/docs/developer-guide/terminal-environment-plugin.md b/website/docs/developer-guide/terminal-environment-plugin.md
index a25924fd9c8..324e5e0595c 100644
--- a/website/docs/developer-guide/terminal-environment-plugin.md
+++ b/website/docs/developer-guide/terminal-environment-plugin.md
@@ -134,6 +134,34 @@ interface as `tools.environments.base.BaseEnvironment`:
Subclassing `BaseEnvironment` is recommended (you inherit the shared file-sync
and background-process plumbing) but not required.
+## File tools and the host filesystem
+
+`read_file`, `write_file`, `patch` and `search_files` go through your
+environment's `execute()`, so they see exactly the files your commands see.
+The one exception is an environment that declares
+`uses_host_filesystem = True` (only the built-in `LocalEnvironment` does): there
+the file tools read, write and search the host directly, run the bundled
+ripgrep, stat paths on the host, write oversized tool output straight to
+`~/.hermes/cache/spillover` and enable LSP diagnostics.
+
+A backend that subclasses `LocalEnvironment` to confine its commands (a
+bubblewrap or other host sandbox that hides paths, mounts them read-only or
+gives commands their own `$TMPDIR`) inherits `True` and must turn it off, or
+the file tools bypass the sandbox:
+
+```python
+from tools.environments.local import LocalEnvironment
+
+
+class AcmeJailEnvironment(LocalEnvironment):
+ uses_host_filesystem = False # file tools run inside the jail, via execute()
+```
+
+Leave it unset on backends that don't subclass `LocalEnvironment`; the default
+is `False`. Hermes v0.22.5 and earlier ignore the attribute and use the host
+fast path for every `LocalEnvironment` subclass, so pin `requires_hermes` past
+that.
+
## Images
Your backend reads its own image setting (a `config_schema` key, or a