fix(tools): anchor the declared read path to base_dir, not the cwd

Addresses the second round of review feedback on #6692.

The previous commit pinned a relative constructor file_path with
os.path.realpath, which anchors to the working directory, while both
format_path_for_display and validate_file_path anchor a relative path to
base_dir. With the two roots disagreeing, the same relative string meant
two different files — and the tool served the cwd one under a label that
looks like it belongs to the sandbox:

    FileReadTool(file_path="data.txt", base_dir="/allowed")   # cwd=/work
    label advertised to the model -> "data.txt"
    run(file_path="data.txt")     -> contents of /work/data.txt

That reads a file from outside base_dir, so it was a sandbox escape
introduced by the exemption itself, not just a wrong-file bug.

Resolution now goes through a single _resolve_against_base helper that
anchors relative paths exactly the way the sandbox does, so the pinned
path, the advertised label and the containment check all agree. Covered
by test_relative_declared_path_anchors_to_base_dir.

Also softens "always readable" to "always allowed past the containment
check" in the docstring, README and docs, since bypassing containment
does not guarantee the read succeeds — it can still fail on a missing
file, a directory, or permissions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: joaomdmoura

docs/edge/en/tools/file-document/filereadtool.mdx

@@ -68,7 +68,7 @@ You set these when constructing the tool:
 Because the file path is usually chosen by an LLM at runtime, reads are confined to a sandbox:
 
 - Paths supplied at runtime must resolve inside `base_dir`, which defaults to the current working directory. `..` segments and symlinks are resolved before the check, so they cannot be used to escape.
-- A `file_path` passed to the constructor is developer-declared intent, so it is always readable — even outside `base_dir`. It is pinned when the tool is built, so a later change of working directory cannot repoint it, and the agent can address it either by omitting `file_path` or by using the name shown in the tool's description. Declaring one file does not expose its siblings.
+- A `file_path` passed to the constructor is developer-declared intent, so it is always allowed past the containment check — even outside `base_dir`. The read itself can still fail if the file is missing, is a directory, or is not permitted. It is pinned when the tool is built, so a later change of working directory cannot repoint it, and the agent can address it either by omitting `file_path` or by using the name shown in the tool's description. Declaring one file does not expose its siblings.
 
 To let an agent read a directory tree outside the working directory, point `base_dir` at it:
 

lib/crewai-tools/src/crewai_tools/tools/file_read_tool/README.md

@@ -52,7 +52,7 @@ You set these when constructing the tool:
 Because the file path is usually chosen by an LLM at runtime, reads are confined to a sandbox:
 
 - Paths supplied at runtime must resolve inside `base_dir` (the current working directory by default). `..` segments and symlinks are resolved before the check, so they cannot be used to escape.
-- A `file_path` passed to the constructor is developer-declared intent, so it is always readable — even outside `base_dir`. It is pinned when the tool is built, so a later change of working directory cannot repoint it, and the agent can address it either by omitting `file_path` or by using the name shown in the tool's description. Declaring one file does not expose its siblings.
+- A `file_path` passed to the constructor is developer-declared intent, so it is always allowed past the containment check — even outside `base_dir`. The read itself can still fail if the file is missing, is a directory, or is not permitted. It is pinned when the tool is built, so a later change of working directory cannot repoint it, and the agent can address it either by omitting `file_path` or by using the name shown in the tool's description. Declaring one file does not expose its siblings.
 
 To let an agent read a directory tree outside the working directory, point `base_dir` at it:
 

lib/crewai-tools/src/crewai_tools/tools/file_read_tool/file_read_tool.py

@@ -12,6 +12,26 @@
 )
 
 
+def _resolve_against_base(path: str, base_dir: str | None) -> str:
+    """Resolve *path* the way the sandbox does, anchoring relatives to *base_dir*.
+
+    ``validate_file_path`` and ``format_path_for_display`` both join a relative
+    path onto *base_dir* rather than the working directory. Resolution has to
+    agree with them, or the same relative string would mean two different files.
+
+    Args:
+        path: The path to resolve.
+        base_dir: The anchor for relative paths. Defaults to the working directory.
+
+    Returns:
+        The resolved absolute path.
+    """
+    if os.path.isabs(path):
+        return os.path.realpath(path)
+    base = os.path.realpath(base_dir) if base_dir is not None else os.getcwd()
+    return os.path.realpath(os.path.join(base, path))
+
+
 class FileReadToolSchema(BaseModel):
     """Input for FileReadTool."""
 
@@ -46,7 +66,8 @@ class FileReadTool(BaseTool):
     Paths supplied at runtime must resolve inside ``base_dir`` (the current
     working directory by default), since they are typically chosen by an LLM.
     A ``file_path`` given at construction time is developer-declared intent and
-    is always readable, even when it lives outside ``base_dir``. It is pinned at
+    is always allowed past the containment check, even when it lives outside
+    ``base_dir`` (the read itself can still fail). It is pinned at
     construction, so a later chdir cannot repoint it, and it can be addressed
     either by omitting ``file_path`` or by the label shown in the description.
 
@@ -111,7 +132,9 @@ def __init__(
         self.base_dir = base_dir
         self.encoding = encoding
         self._declared_realpath = (
-            os.path.realpath(file_path) if file_path is not None else None
+            _resolve_against_base(file_path, base_dir)
+            if file_path is not None
+            else None
         )
         self._declared_label = display_path
 
@@ -136,7 +159,8 @@ def _resolve_path(self, file_path: str) -> str:
         """
         declared = self._declared_realpath
         if declared is not None and (
-            file_path == self._declared_label or os.path.realpath(file_path) == declared
+            file_path == self._declared_label
+            or _resolve_against_base(file_path, self.base_dir) == declared
         ):
             return declared
         return validate_file_path(file_path, self.base_dir)

lib/crewai-tools/tests/file_read_tool_test.py

@@ -275,6 +275,29 @@ def test_declared_relative_path_survives_chdir(tmp_path, monkeypatch):
     assert tool._run(file_path="rel.txt") == "original"
 
 
+def test_relative_declared_path_anchors_to_base_dir(tmp_path, monkeypatch):
+    """A relative declared path must resolve against base_dir, not the cwd.
+
+    The advertised label is built against base_dir, so pinning against the cwd
+    would make the same name mean two different files — and would serve a file
+    from outside base_dir under a label that looks like it is inside.
+    """
+    allowed = tmp_path / "allowed"
+    allowed.mkdir()
+    work = tmp_path / "work"
+    work.mkdir()
+    (allowed / "data.txt").write_text("sandbox file")
+    (work / "data.txt").write_text("cwd file")
+    monkeypatch.chdir(work)
+
+    tool = FileReadTool(file_path="data.txt", base_dir=str(allowed))
+
+    assert tool._declared_label == "data.txt"
+    assert tool._declared_realpath == str(allowed / "data.txt")
+    assert tool.run() == "sandbox file"
+    assert tool.run(file_path="data.txt") == "sandbox file"
+
+
 def test_constructor_path_does_not_widen_the_sandbox(tmp_path, monkeypatch):
     """Declaring one file must not expose its siblings to the LLM."""
     workspace = tmp_path / "workspace"

lib/crewai-tools/tool.specs.json

@@ -9972,7 +9972,7 @@
             "type": "object"
           }
         },
-        "description": "A tool for reading file contents.\n\nThis tool inherits its schema handling from BaseTool to avoid recursive schema\ndefinition issues. The args_schema is set to FileReadToolSchema, whose\nfile_path parameter is optional so the tool's default file can be read by\nomitting it. The schema should not be overridden in the constructor as it\nwould break the inheritance chain and cause infinite loops.\n\nThe tool supports two ways of specifying the file path:\n1. At construction time via the file_path parameter\n2. At runtime via the file_path parameter in the tool's input\n\nPaths supplied at runtime must resolve inside ``base_dir`` (the current\nworking directory by default), since they are typically chosen by an LLM.\nA ``file_path`` given at construction time is developer-declared intent and\nis always readable, even when it lives outside ``base_dir``. It is pinned at\nconstruction, so a later chdir cannot repoint it, and it can be addressed\neither by omitting ``file_path`` or by the label shown in the description.\n\nArgs:\n    file_path (Optional[str]): Path to the file to be read. If provided,\n        this becomes the default file path for the tool.\n    base_dir (Optional[str]): Directory that runtime paths must stay inside.\n        Defaults to the current working directory.\n    encoding (str): Text encoding used to decode the file. Defaults to UTF-8.\n    **kwargs: Additional keyword arguments passed to BaseTool.\n\nExample:\n    >>> tool = FileReadTool(file_path=\"/path/to/file.txt\")\n    >>> content = tool.run()  # Reads /path/to/file.txt\n    >>> content = tool.run(file_path=\"/path/to/other.txt\")  # Reads other.txt\n    >>> content = tool.run(\n    ...     file_path=\"/path/to/file.txt\", start_line=100, line_count=50\n    ... )  # Reads lines 100-149\n    >>> # Widen the sandbox so the agent may read anything under /data:\n    >>> tool = FileReadTool(base_dir=\"/data\")",
+        "description": "A tool for reading file contents.\n\nThis tool inherits its schema handling from BaseTool to avoid recursive schema\ndefinition issues. The args_schema is set to FileReadToolSchema, whose\nfile_path parameter is optional so the tool's default file can be read by\nomitting it. The schema should not be overridden in the constructor as it\nwould break the inheritance chain and cause infinite loops.\n\nThe tool supports two ways of specifying the file path:\n1. At construction time via the file_path parameter\n2. At runtime via the file_path parameter in the tool's input\n\nPaths supplied at runtime must resolve inside ``base_dir`` (the current\nworking directory by default), since they are typically chosen by an LLM.\nA ``file_path`` given at construction time is developer-declared intent and\nis always allowed past the containment check, even when it lives outside\n``base_dir`` (the read itself can still fail). It is pinned at\nconstruction, so a later chdir cannot repoint it, and it can be addressed\neither by omitting ``file_path`` or by the label shown in the description.\n\nArgs:\n    file_path (Optional[str]): Path to the file to be read. If provided,\n        this becomes the default file path for the tool.\n    base_dir (Optional[str]): Directory that runtime paths must stay inside.\n        Defaults to the current working directory.\n    encoding (str): Text encoding used to decode the file. Defaults to UTF-8.\n    **kwargs: Additional keyword arguments passed to BaseTool.\n\nExample:\n    >>> tool = FileReadTool(file_path=\"/path/to/file.txt\")\n    >>> content = tool.run()  # Reads /path/to/file.txt\n    >>> content = tool.run(file_path=\"/path/to/other.txt\")  # Reads other.txt\n    >>> content = tool.run(\n    ...     file_path=\"/path/to/file.txt\", start_line=100, line_count=50\n    ... )  # Reads lines 100-149\n    >>> # Widen the sandbox so the agent may read anything under /data:\n    >>> tool = FileReadTool(base_dir=\"/data\")",
         "properties": {
           "base_dir": {
             "anyOf": [