The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.pynew file mode 100644index 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.pyindex 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 LocalEnvironmentenv = MagicMock(spec=LocalEnvironment)+ env.uses_host_filesystem = LocalEnvironment.uses_host_filesystemcontent = "y" * 60_000result = maybe_persist_tool_result(content=content,diff --git a/tools/environments/base.py b/tools/environments/base.pyindex 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 = 30diff --git a/tools/environments/local.py b/tools/environments/local.pyindex 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 = Truedef _additional_profile_scoped_passthrough_names(self) -> tuple[str, ...]:"""First-party ``BUZZ_*`` names present in the env, excluded from the shareddiff --git a/tools/file_operations.py b/tools/file_operations.pyindex 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.pyindex 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 workspacediff --git a/tools/file_operations_search.py b/tools/file_operations_search.pyindex e3186b3f502..496e9d9025d 100644--- a/tools/file_operations_search.py+++ b/tools/file_operations_search.py@@ -60,10 +60,11 @@ _FILENAME_SEARCH_WAIT_SECONDS = 0.05def _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_pathcwd = 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 Noneif bundled:self._rg_resolution_cache[cmd] = bundledreturn bundled@@ -309,7 +312,7 @@ class SearchMixin:self._rg_resolution_cache[cmd] = resolvedreturn 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) isunsafe 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 Falsedef 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.pyindex 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*`` afterdiff --git a/tools/tool_result_storage.py b/tools/tool_result_storage.pyindex 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.mdindex 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-syncand 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.+## ImagesYour backend reads its own image setting (a `config_schema` key, or a