fix(tools): anchor base_dir at construction so the sandbox cannot move

Addresses the third review round on #6692.

Both remaining findings came from the same habit: storing an unanchored
string and re-resolving it later.

A relative base_dir was kept verbatim and re-resolved against getcwd() on
every call, while the declared file was pinned once at construction. After
a chdir the sandbox root moved but the declared default did not, so one
tool applied two different roots. base_dir is now resolved once — in the
reader's __init__, and via a field_validator on the writer so it also
applies on the model_validate path.

That also covers the serialization concern. model_dump drops the private
pin, and __init__ re-runs on restore, so a relative file_path was
re-anchored against whatever the working directory happened to be at load
time. With base_dir anchored, restore rebuilds the identical pin.

The residual case is a relative file_path with no base_dir, where the
sandbox root is the working directory too — so both move together and the
tool stays self-consistent. Covered by
test_declared_path_survives_a_serialization_round_trip and
test_relative_base_dir_is_anchored_at_construction on both tools.

Also corrects the writer's 'directory' description, README and docs: the
default resolves inside the tool's allowed directory, which is base_dir
when one is set, not always the working directory.

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

Author: joaomdmoura

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

@@ -46,7 +46,7 @@ The agent supplies these at runtime:
 
 - `filename`: The name of the file to write, relative to `directory`. May include subdirectories, which are created if they don't exist.
 - `content`: The text content to write into the file.
-- `directory` (optional): The path to the directory where the file will be created. Defaults to the current working directory. If the directory does not exist, it will be created.
+- `directory` (optional): The path to the directory where the file will be created. A relative path resolves inside the tool's allowed directory — `base_dir` when set, the current working directory otherwise — and defaults to its root. If the directory does not exist, it will be created.
 - `overwrite` (optional): Whether to replace the file when it already exists. Accepts `true`/`false` (also `yes`/`no`, `on`/`off`, `1`/`0`). Defaults to `false`, which reports an error instead of replacing existing content.
 
 You set these when constructing the tool:

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

@@ -120,6 +120,11 @@ def __init__(
             encoding (str): Text encoding used to decode the file.
             **kwargs: Additional keyword arguments passed to BaseTool.
         """
+        # Anchor base_dir once, so the sandbox root cannot move under a later
+        # chdir while the declared file stays pinned to its original location.
+        if base_dir is not None:
+            base_dir = os.path.realpath(base_dir)
+
         display_path = None
         if file_path is not None:
             display_path = format_path_for_display(file_path, base_dir)

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

@@ -33,7 +33,7 @@ The agent supplies these at runtime:
 
 - `filename`: The name of the file to write, relative to `directory`. May include subdirectories, which are created if they don't exist.
 - `content`: The text content to write into the file.
-- `directory` (optional): The path to the directory where the file will be created. Defaults to the current working directory. If the directory does not exist, it will be created.
+- `directory` (optional): The path to the directory where the file will be created. A relative path resolves inside the tool's allowed directory — `base_dir` when set, the current working directory otherwise — and defaults to its root. If the directory does not exist, it will be created.
 - `overwrite` (optional): Whether to replace the file when it already exists. Accepts `true`/`false` (also `yes`/`no`, `on`/`off`, `1`/`0`). Defaults to `false`, which reports an error instead of replacing existing content.
 
 You set these when constructing the tool:

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

@@ -2,7 +2,7 @@
 from pathlib import Path
 
 from crewai.tools import BaseTool
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 from crewai_tools.security.safe_path import (
     format_error_for_display,
@@ -47,8 +47,9 @@ class FileWriterToolInput(BaseModel):
     directory: str | None = Field(
         "./",
         description=(
-            "Directory to write the file into. Created if it does not exist. "
-            "Defaults to the current working directory."
+            "Directory to write the file into. A relative path resolves inside "
+            "the tool's allowed directory, and defaults to its root. Created if "
+            "it does not exist."
         ),
     )
     overwrite: str | bool = Field(
@@ -86,6 +87,12 @@ class FileWriterTool(BaseTool):
     base_dir: str | None = None
     encoding: str = "utf-8"
 
+    @field_validator("base_dir")
+    @classmethod
+    def _anchor_base_dir(cls, value: str | None) -> str | None:
+        """Resolve base_dir once so a later chdir cannot move the sandbox."""
+        return os.path.realpath(value) if value is not None else None
+
     def _run(
         self,
         filename: str,

lib/crewai-tools/tests/file_read_tool_test.py

@@ -298,6 +298,48 @@ def test_relative_declared_path_anchors_to_base_dir(tmp_path, monkeypatch):
     assert tool.run(file_path="data.txt") == "sandbox file"
 
 
+def test_relative_base_dir_is_anchored_at_construction(tmp_path, monkeypatch):
+    """A relative base_dir must not follow a later chdir.
+
+    Otherwise the sandbox root moves while the declared file stays pinned, and
+    the tool applies two different roots.
+    """
+    monkeypatch.chdir(tmp_path)
+    allowed = tmp_path / "allowed"
+    allowed.mkdir()
+    (allowed / "data.txt").write_text("sandbox file")
+    nested = tmp_path / "sub"
+    nested.mkdir()
+
+    tool = FileReadTool(base_dir="allowed")
+    assert tool.base_dir == str(allowed)
+
+    monkeypatch.chdir(nested)
+    assert tool._run(file_path="data.txt") == "sandbox file"
+
+
+def test_declared_path_survives_a_serialization_round_trip(tmp_path, monkeypatch):
+    """model_dump drops private attrs, so the pin must be rebuilt on restore."""
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    monkeypatch.chdir(workspace)
+    allowed = tmp_path / "allowed"
+    allowed.mkdir()
+    (allowed / "data.txt").write_text("sandbox file")
+
+    tool = FileReadTool(file_path="data.txt", base_dir=str(allowed))
+    restored = FileReadTool.model_validate(tool.model_dump())
+
+    assert restored._declared_realpath == tool._declared_realpath
+    assert restored.run() == "sandbox file"
+
+    # A chdir between dump and restore must not repoint the declared file.
+    nested = workspace / "sub"
+    nested.mkdir()
+    monkeypatch.chdir(nested)
+    assert FileReadTool.model_validate(tool.model_dump()).run() == "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/tests/tools/test_file_writer_tool.py

@@ -301,6 +301,37 @@ def test_base_dir_anchors_relative_directories(temp_env):
         shutil.rmtree(outside_dir, ignore_errors=True)
 
 
+def test_relative_base_dir_is_anchored_at_construction(temp_env, monkeypatch):
+    """A relative base_dir must not follow a later chdir."""
+    allowed = os.path.join(temp_env["temp_dir"], "allowed")
+    os.makedirs(allowed)
+    nested = os.path.join(temp_env["temp_dir"], "sub")
+    os.makedirs(nested)
+
+    scoped = FileWriterTool(base_dir="allowed")
+    assert scoped.base_dir == os.path.realpath(allowed)
+
+    monkeypatch.chdir(nested)
+    result = scoped._run(filename="x.txt", content="written", overwrite=True)
+
+    assert "successfully written" in result
+    assert read_file(os.path.join(allowed, "x.txt")) == "written"
+
+
+def test_base_dir_survives_a_serialization_round_trip(temp_env):
+    outside = tempfile.mkdtemp()
+    try:
+        restored = FileWriterTool.model_validate(
+            FileWriterTool(base_dir=outside).model_dump()
+        )
+        assert restored.base_dir == os.path.realpath(outside)
+        assert "successfully written" in restored._run(
+            filename="x.txt", directory=outside, content="written", overwrite=True
+        )
+    finally:
+        shutil.rmtree(outside, ignore_errors=True)
+
+
 def test_base_dir_still_blocks_escapes(temp_env):
     """base_dir moves the sandbox; it does not remove it."""
     allowed_dir = tempfile.mkdtemp()

lib/crewai-tools/tool.specs.json

@@ -10143,7 +10143,7 @@
               }
             ],
             "default": "./",
-            "description": "Directory to write the file into. Created if it does not exist. Defaults to the current working directory.",
+            "description": "Directory to write the file into. A relative path resolves inside the tool's allowed directory, and defaults to its root. Created if it does not exist.",
             "title": "Directory"
           },
           "filename": {