Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(tools): name the write-roots escape hatch in file-tool rejections

Yufeng He6e2e978a71af
diff --git a/README.md b/README.md
index 5e2613d3a..eefa4fe89 100644
--- a/README.md
+++ b/README.md
@@ -1095,6 +1095,7 @@ Copy `agent/.env.example` to `agent/.env` and uncomment the provider block you w
| `VIBE_TRADING_ENABLE_SHELL_TOOLS` | No | Explicit opt-in for shell-capable tools in remote API/MCP-SSE style deployments |
| `VIBE_TRADING_ALLOWED_FILE_ROOTS` | No | Extra comma-separated roots for document and broker-journal imports |
| `VIBE_TRADING_ALLOWED_RUN_ROOTS` | No | Extra comma-separated roots for generated-code run directories |
+| `VIBE_TRADING_ALLOWED_WRITE_ROOTS` | No | Extra comma-separated roots the agent may write or edit (e.g. `~/Documents` for report exports) |
| `VIBE_TW_STOCK_DB` | No | Path to a Taiwan-market SQLite snapshot; the read-only `taiwan_stock_data` tool registers only when it is schema-valid |
| `VIBE_TRADING_EXTRA_CORS_ORIGINS` | No | Comma-separated origins **added** to the loopback CORS defaults (`CORS_ORIGINS` replaces them instead) |
| `CONTENT_FILTER_WARNING_THRESHOLD` | No | Content-filter warning ratio threshold (default 0.05 = 5%). When the ratio of LLM responses blocked by content moderation exceeds this, the run card warns you to switch providers. |
diff --git a/agent/.env.example b/agent/.env.example
index 30d18bfce..98fac8c34 100644
--- a/agent/.env.example
+++ b/agent/.env.example
@@ -310,6 +310,10 @@ TUSHARE_TOKEN=your-tushare-token
# Optional run roots for generated-code tools such as write_file/backtest.
# Defaults include agent/runs, ./runs, and ~/.vibe-trading/shadow_runs.
# VIBE_TRADING_ALLOWED_RUN_ROOTS=
+# Optional extra write roots for write_file/edit_file. Defaults cover the run
+# and upload directories only; add e.g. ~/Documents here to let the agent
+# export reports there. Use comma-separated absolute paths.
+# VIBE_TRADING_ALLOWED_WRITE_ROOTS=
# ============================================================================
# Agent Tuning (AgentTuningConfig, optional, defaults are sensible)
diff --git a/agent/src/tools/path_utils.py b/agent/src/tools/path_utils.py
index 1c09fb877..579898dd8 100644
--- a/agent/src/tools/path_utils.py
+++ b/agent/src/tools/path_utils.py
@@ -17,13 +17,13 @@ All helpers raise ``ValueError`` on rejection — callers already expect this.
from __future__ import annotations
-import os
from pathlib import Path
from src.config.accessor import get_env_config
_ALLOWED_FILE_ROOTS_ENV = "VIBE_TRADING_ALLOWED_FILE_ROOTS"
_ALLOWED_RUN_ROOTS_ENV = "VIBE_TRADING_ALLOWED_RUN_ROOTS"
+_ALLOWED_WRITE_ROOTS_ENV = "VIBE_TRADING_ALLOWED_WRITE_ROOTS"
# MCP clients spawn the server themselves, so a shell export never reaches it.
_ENV_SCOPE_HINT = (
@@ -31,6 +31,13 @@ _ENV_SCOPE_HINT = (
"exporting it in a shell does not reach the spawned server."
)
+# The env var that widens each resolve_safe_path purpose; rejections name it
+# so the escape hatch is discoverable from the error itself.
+_PURPOSE_ENV_HINTS = {
+ "write": _ALLOWED_WRITE_ROOTS_ENV,
+ "file": _ALLOWED_FILE_ROOTS_ENV,
+}
+
def _describe_roots(roots: list[Path]) -> str:
"""Render allowed roots as an indented list for a rejection message."""
@@ -144,9 +151,6 @@ def allowed_file_roots() -> list[Path]:
return roots
-_ALLOWED_WRITE_ROOTS_ENV = "VIBE_TRADING_ALLOWED_WRITE_ROOTS"
-
-
def allowed_write_roots() -> list[Path]:
"""Return all roots allowed for file writes and edits."""
raw = get_env_config().api.vibe_trading_allowed_write_roots
@@ -205,6 +209,9 @@ def resolve_safe_path(
"""
_rejects_unc(file_path)
+ hint_env = _PURPOSE_ENV_HINTS.get(purpose)
+ hint = f"\nSet {hint_env} to add a directory. {_ENV_SCOPE_HINT}" if hint_env else ""
+
# Try resolving against run_dir if provided
if run_dir:
try:
@@ -226,7 +233,8 @@ def resolve_safe_path(
if candidate.is_relative_to(root):
return candidate
raise ValueError(
- f"Path {file_path!r} escapes run_dir {run_dir!r} and is not in allowed {purpose} roots."
+ f"Path {file_path!r} escapes run_dir {run_dir!r} and is not in allowed {purpose} roots.\n"
+ f"{_describe_roots(allowed_roots)}{hint}"
) from exc
# If no run_dir, path must resolve inside one of the allowed roots
@@ -236,7 +244,8 @@ def resolve_safe_path(
return candidate
raise ValueError(
- f"run_dir is required to write/edit {file_path!r}, or the path must resolve inside allowed {purpose} roots."
+ f"run_dir is required to write/edit {file_path!r}, or the path must resolve inside allowed {purpose} roots.\n"
+ f"{_describe_roots(allowed_roots)}{hint}"
)
diff --git a/agent/tests/test_file_tool_sandbox_security.py b/agent/tests/test_file_tool_sandbox_security.py
index 9b32de326..01eef9d4b 100644
--- a/agent/tests/test_file_tool_sandbox_security.py
+++ b/agent/tests/test_file_tool_sandbox_security.py
@@ -191,3 +191,43 @@ def test_resolve_safe_path_run_dir_escapes_fallback(tmp_path: Path, monkeypatch)
with pytest.raises(ValueError) as excinfo:
resolve_safe_path("/etc/passwd", str(run_dir), allowed_write_roots(), purpose="write")
assert "escapes run_dir" in str(excinfo.value)
+
+
+def test_write_rejection_names_the_write_roots_env(tmp_path: Path, monkeypatch) -> None:
+ # The escape hatch must be discoverable from the error itself: a model
+ # told only "escapes the workspace" cannot tell the user how to allow
+ # ~/Documents (#1677).
+ monkeypatch.setenv("VIBE_TRADING_ALLOWED_WRITE_ROOTS", str(tmp_path / "elsewhere"))
+ monkeypatch.setenv("VIBE_TRADING_ALLOWED_RUN_ROOTS", str(tmp_path / "runs"))
+
+ body = _body(WriteFileTool().execute(path="/etc/poison.txt", content="x"))
+
+ assert body["status"] == "error"
+ assert "VIBE_TRADING_ALLOWED_WRITE_ROOTS" in body["error"]
+
+
+def test_write_rejection_inside_run_dir_fallback_also_names_env(tmp_path: Path, monkeypatch) -> None:
+ monkeypatch.setenv("VIBE_TRADING_ALLOWED_WRITE_ROOTS", str(tmp_path / "elsewhere"))
+ monkeypatch.setenv("VIBE_TRADING_ALLOWED_RUN_ROOTS", str(tmp_path / "runs"))
+ run_dir = tmp_path / "runs" / "run_1"
+ run_dir.mkdir(parents=True)
+
+ body = _body(
+ WriteFileTool().execute(path="/etc/poison.txt", content="x", run_dir=str(run_dir))
+ )
+
+ assert body["status"] == "error"
+ assert "escapes run_dir" in body["error"]
+ assert "VIBE_TRADING_ALLOWED_WRITE_ROOTS" in body["error"]
+
+
+def test_read_purpose_rejection_names_the_file_roots_env(tmp_path: Path, monkeypatch) -> None:
+ # purpose="file" is the read side (image_vision); it must point at the
+ # read widening knob, not the write one.
+ monkeypatch.setenv("VIBE_TRADING_ALLOWED_FILE_ROOTS", str(tmp_path / "elsewhere"))
+
+ with pytest.raises(ValueError) as excinfo:
+ resolve_safe_path("/etc/passwd", None, allowed_write_roots(), purpose="file")
+
+ assert "VIBE_TRADING_ALLOWED_FILE_ROOTS" in str(excinfo.value)
+ assert "VIBE_TRADING_ALLOWED_WRITE_ROOTS" not in str(excinfo.value)