fix(tools): contain file read/write/edit to workspace root by default

[Jiangrong-W]

Summary

• What problem does this PR solve? The built-in file tools (read_file, write_file, edit_file) resolved a model-/LLM-supplied path to an absolute host path and then read or wrote it directly. Workspace containment was only enforced inside the is_docker_sandbox_active() branch (which calls validate_sandbox_path). The Docker sandbox is disabled by default (SandboxSettings.enabled = False), so in the default, unsandboxed configuration nothing kept these tools inside the repository root. A prompt-injected or mistaken model could therefore escape the workspace via an absolute path or .. traversal:

  • read_file is read-only, so PermissionChecker.evaluate auto-allows it after only the credential denylist / optional path rules — out-of-workspace reads of arbitrary UTF-8 host files succeeded with no prompt.
  • write_file / edit_file are gated by a permission prompt and edit-diff approval in the interactive UI, but the shipped non-interactive runners (run_task_worker, used for background teammates spawned with --task-worker, and run_print_mode) install a permission callback that always returns True and pass no edit_approval_prompt. On that auto-approved path, out-of-workspace writes and edits also succeeded.

  Affected sites (decisive sink per path):

  • read_file — src/openharness/tools/file_read_tool.py:52 (raw = path.read_bytes())
  • write_file — src/openharness/tools/file_write_tool.py:59 (path.write_text(arguments.content, encoding=\"utf-8\"))
  • edit_file — src/openharness/tools/file_edit_tool.py (path.write_text(updated, ...), both the sandbox and non-sandbox branches)

• What changed? Workspace containment is now enforced for read_file, write_file, and edit_file before any read or write, independent of the Docker sandbox and independent of the approval path, by reusing the repo's existing path-boundary check:

  • Added validate_workspace_path(path, cwd, metadata) in src/openharness/sandbox/path_validator.py — the always-on counterpart to validate_sandbox_path, which it reuses for the actual containment check (real-path resolution + ancestor check, already rejecting absolute-outside paths, .. escapes, and symlink escapes). Exported from src/openharness/sandbox/__init__.py.
  • Each file tool calls validate_workspace_path(...) right after path resolution. For write_file / edit_file the check runs before both the approval branch and the auto-approve branch, so it fails closed before the user is ever prompted and also holds on the interactive path.
  • Added FilesystemSettings (restrict_to_workspace: bool = True, allow_paths: list[str] = []) on Settings.filesystem (src/openharness/config/settings.py), surfaced into the engine tool_metadata in src/openharness/ui/runtime.py (including the task-worker and print-mode runtimes, so the auto-approve paths inherit containment).

  Containment is on by default and security-positive: out-of-workspace reads, writes, and edits are denied by default. It is backward compatible — no public API signature changes, validate_sandbox_path is untouched, the new helper is additive, and tools called without metadata (e.g. in tests) default to containment-on. Operators who need to reach outside the repository can opt out per session with filesystem.restrict_to_workspace = false, or scope extra roots with filesystem.allow_paths. In-workspace edits keep the existing approval-prompt behavior.

Validation

• uv run ruff check src tests scripts
• uv run pytest -q
• cd frontend/terminal && npx tsc --noEmit (if frontend touched)

Test summary (added with this change, covering both affected tools):

• tests/test_tools/test_file_tool_containment.py — read_file scope (5 tests): rejects absolute-outside, rejects .. escape, allows in-workspace, honors restrict_to_workspace=False opt-out, honors allow_paths extra root.
• tests/test_tools/test_file_write_containment.py — write_file / edit_file scope (10 tests): rejects .. escape and absolute-outside on the headless auto-approve path, rejects an escape even when an approval callback is set (and asserts the callback is never invoked — fails closed), plus in-workspace, opt-out, and allow_paths allow-cases for both tools.

Both new suites fail on the base commit (the escapes succeed) and pass after this change:

tests/test_tools/test_file_tool_containment.py .....                     [ 33%]
tests/test_tools/test_file_write_containment.py ..........               [100%]
15 passed

Run together with the adjacent tool / sandbox / config suites it is regression-clean (137 passed, 1 skipped). uv run ruff check passes on every file touched here. The frontend was not modified, so the TypeScript check has nothing to run for this PR. The full uv run pytest -q suite is left for a maintainer's green CI run.

Notes

• Related issue: Fixes [Bug]: Built-in file tools (read/write/edit) are not contained to the workspace root by default #310
• Follow-up work: None required. The change is self-contained. A short Unreleased entry could optionally be added to CHANGELOG.md to record the default-on workspace containment for the built-in file tools.