fix(tools): make the declared FileReadTool file reachable by agents

Addresses review feedback on #6692.

The constructor-path exemption did not actually work the way an agent
calls the tool. The description only advertises a redacted label (the
basename, when the file sits outside the sandbox), but resolution
required the exact absolute path, so the model's call was sandboxed and
the declared file was never read. Worse, file_path was a required schema
field, so the long-documented "call with no arguments to read the default
file" raised a validation error instead:

    FileReadTool(file_path="/outside/declared.txt")
    .run()                          -> ValueError: validation failed
    .run(file_path="declared.txt")  -> Error: File not found
    .run(file_path="/outside/declared.txt") -> works, but the model was
                                               never told this path

file_path is now optional in the schema, so omitting it reads the default,
and the declared file is addressable by the label the description shows
the model as well as by its real path. Declaring one file still does not
expose its siblings.

The declared path is also pinned to its real path at construction, so a
later chdir cannot silently repoint it at a different file — previously a
relative constructor path re-resolved against the new working directory
on every call.

Also guards the writer's filepath resolution, which could raise
ValueError out of _run for a filename containing a null byte, breaking
the contract of always returning a descriptive string. The directory and
read paths were already guarded.

Adds docstrings to strtobool and both _run methods, corrects an Arabic
tanween spelling and a kaf-as-descriptor calque in the localized read
docs, and regenerates tool.specs.json for the schema change.

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

Author: joaomdmoura

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

@@ -11,7 +11,7 @@ mode: "wide"
     لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل.
 </Note>
 
-تمثل أداة FileReadTool مفهومياً مجموعة من الوظائف ضمن حزمة crewai_tools تهدف إلى تسهيل قراءة الملفات واسترجاع المحتوى. تتضمن هذه المجموعة أدوات لمعالجة ملفات نصية دفعية، وقراءة ملفات التكوين أثناء التشغيل، واستيراد البيانات للتحليلات. تدعم مجموعة متنوعة من صيغ الملفات النصية مثل `.txt` و `.csv` و `.json` وغيرها. يُعاد المحتوى دائماً كنص عادي.
+تمثل أداة FileReadTool مفهوميًا مجموعة من الوظائف ضمن حزمة crewai_tools تهدف إلى تسهيل قراءة الملفات واسترجاع المحتوى. تتضمن هذه المجموعة أدوات لمعالجة ملفات نصية دفعية، وقراءة ملفات التكوين أثناء التشغيل، واستيراد البيانات للتحليلات. تدعم مجموعة متنوعة من صيغ الملفات النصية مثل `.txt` و `.csv` و `.json` وغيرها. يُعاد المحتوى دائمًا نصًا عاديًا.
 
 ## التثبيت
 

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

@@ -53,7 +53,7 @@ partial_content = file_read_tool.run(
 
 The agent supplies these at runtime:
 
-- `file_path`: The path to the file you want to read. Accepts absolute and relative paths. Ensure the file exists and you have the necessary permissions to access it.
+- `file_path`: (Optional) The path to the file you want to read. Accepts absolute and relative paths. Ensure the file exists and you have the necessary permissions to access it. Omit it to read the default file configured at construction; if there is no default, the tool reports that no path was provided.
 - `start_line`: (Optional) The line number to start reading from (1-indexed). Defaults to `1`.
 - `line_count`: (Optional) The number of lines to read. If omitted, reads from `start_line` to the end of the file.
 
@@ -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`. Declaring one file does not expose its siblings.
+- 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.
 
 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

@@ -37,7 +37,7 @@ partial_content = file_read_tool.run(file_path='path/to/your/file.txt', start_li
 
 The agent supplies these at runtime:
 
-- `file_path`: The path to the file you want to read. It accepts both absolute and relative paths. Ensure the file exists and you have the necessary permissions to access it.
+- `file_path`: (Optional) The path to the file you want to read. It accepts both absolute and relative paths. Ensure the file exists and you have the necessary permissions to access it. Omit it to read the default file configured at construction; if there is no default, the tool reports that no path was provided.
 - `start_line`: (Optional) The line number to start reading from (1-indexed). Defaults to 1 (the first line).
 - `line_count`: (Optional) The number of lines to read. If not provided, reads from the start_line to the end of the file.
 
@@ -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`. Declaring one file does not expose its siblings.
+- 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.
 
 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

@@ -3,7 +3,7 @@
 from typing import Any
 
 from crewai.tools import BaseTool
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, PrivateAttr
 
 from crewai_tools.security.safe_path import (
     format_error_for_display,
@@ -15,7 +15,13 @@
 class FileReadToolSchema(BaseModel):
     """Input for FileReadTool."""
 
-    file_path: str = Field(..., description="Mandatory file full path to read the file")
+    file_path: str | None = Field(
+        None,
+        description=(
+            "Full path of the file to read. Omit it to read the tool's default "
+            "file, which only works when one was configured."
+        ),
+    )
     start_line: int | None = Field(
         1, description="Line number to start reading from (1-indexed)"
     )
@@ -28,9 +34,10 @@ class FileReadTool(BaseTool):
     """A tool for reading file contents.
 
     This tool inherits its schema handling from BaseTool to avoid recursive schema
-    definition issues. The args_schema is set to FileReadToolSchema which defines
-    the required file_path parameter. The schema should not be overridden in the
-    constructor as it would break the inheritance chain and cause infinite loops.
+    definition issues. The args_schema is set to FileReadToolSchema, whose
+    file_path parameter is optional so the tool's default file can be read by
+    omitting it. The schema should not be overridden in the constructor as it
+    would break the inheritance chain and cause infinite loops.
 
     The tool supports two ways of specifying the file path:
     1. At construction time via the file_path parameter
@@ -39,7 +46,9 @@ 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``.
+    is always readable, even when it lives outside ``base_dir``. 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.
 
     Args:
         file_path (Optional[str]): Path to the file to be read. If provided,
@@ -67,6 +76,12 @@ class FileReadTool(BaseTool):
     base_dir: str | None = None
     encoding: str = "utf-8"
 
+    # Pinned at construction so a later chdir cannot change which file the
+    # developer-declared default refers to.
+    _declared_realpath: str | None = PrivateAttr(default=None)
+    # The label the tool's description shows the LLM for the declared file.
+    _declared_label: str | None = PrivateAttr(default=None)
+
     def __init__(
         self,
         file_path: str | None = None,
@@ -84,24 +99,31 @@ def __init__(
             encoding (str): Text encoding used to decode the file.
             **kwargs: Additional keyword arguments passed to BaseTool.
         """
+        display_path = None
         if file_path is not None:
             display_path = format_path_for_display(file_path, base_dir)
             kwargs["description"] = (
-                f"A tool that reads file content. The default file is {display_path}, but you can provide a different 'file_path' parameter to read another file. You can also specify 'start_line' and 'line_count' to read specific parts of the file."
+                f"A tool that reads file content. The default file is {display_path}, which is read when 'file_path' is omitted. You can also provide a different 'file_path' parameter to read another file, and specify 'start_line' and 'line_count' to read specific parts of the file."
             )
 
         super().__init__(**kwargs)
         self.file_path = file_path
         self.base_dir = base_dir
         self.encoding = encoding
+        self._declared_realpath = (
+            os.path.realpath(file_path) if file_path is not None else None
+        )
+        self._declared_label = display_path
 
     def _resolve_path(self, file_path: str) -> str:
         """Resolve *file_path* and confirm the tool is allowed to read it.
 
-        The path declared at construction time is always allowed: the developer
-        named that exact file, and the tool would read it anyway when called
-        with no arguments. Everything else — including any path an LLM picks at
-        runtime — must resolve inside ``base_dir``.
+        The file declared at construction time is always allowed: the developer
+        named it, and the tool reads it anyway when ``file_path`` is omitted. It
+        is addressable both by its real path and by the label the description
+        shows the LLM, since that label is all the model is given. Everything
+        else — including any path an LLM invents at runtime — must resolve
+        inside ``base_dir``.
 
         Args:
             file_path: The path to resolve.
@@ -112,9 +134,11 @@ def _resolve_path(self, file_path: str) -> str:
         Raises:
             ValueError: If the path resolves outside ``base_dir``.
         """
-        resolved = os.path.realpath(file_path)
-        if self.file_path is not None and resolved == os.path.realpath(self.file_path):
-            return resolved
+        declared = self._declared_realpath
+        if declared is not None and (
+            file_path == self._declared_label or os.path.realpath(file_path) == declared
+        ):
+            return declared
         return validate_file_path(file_path, self.base_dir)
 
     def _run(
@@ -123,17 +147,19 @@ def _run(
         start_line: int | None = 1,
         line_count: int | None = None,
     ) -> str:
-        file_path = file_path or self.file_path
+        """Read a file, or a window of its lines, as text."""
         start_line = start_line or 1
         line_count = line_count or None
 
         if file_path is None:
-            return "Error: No file path provided. Please provide a file path either in the constructor or as an argument."
-
-        try:
-            file_path = self._resolve_path(file_path)
-        except ValueError as e:
-            return f"Error: Invalid file path: {e!s}"
+            if self._declared_realpath is None:
+                return "Error: No file path provided. Please provide a file path either in the constructor or as an argument."
+            file_path = self._declared_realpath
+        else:
+            try:
+                file_path = self._resolve_path(file_path)
+            except ValueError as e:
+                return f"Error: Invalid file path: {e!s}"
 
         display_path = format_path_for_display(file_path, self.base_dir)
         try:

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

@@ -12,6 +12,17 @@
 
 
 def strtobool(val: str | bool) -> bool:
+    """Coerce the spellings of true/false an LLM is likely to emit into a bool.
+
+    Args:
+        val: A bool, or one of y/yes/t/true/on/1 and n/no/f/false/off/0.
+
+    Returns:
+        The corresponding boolean.
+
+    Raises:
+        ValueError: If the string is not a recognized boolean spelling.
+    """
     if isinstance(val, bool):
         return val
     val = val.lower()
@@ -82,6 +93,7 @@ def _run(
         directory: str | None = "./",
         overwrite: str | bool = False,
     ) -> str:
+        """Write *content* to *filename*, confined to the tool's sandbox."""
         directory = directory or "./"
 
         try:
@@ -102,7 +114,14 @@ def _run(
         # components, so it is safe on case-insensitive filesystems and avoids
         # the "//" prefix edge case. A filepath that resolves to the directory
         # itself (e.g. an empty filename) is not a valid file target.
-        resolved_filepath = Path(os.path.join(resolved_directory, filename)).resolve()
+        try:
+            resolved_filepath = Path(
+                os.path.join(resolved_directory, filename)
+            ).resolve()
+        except (OSError, ValueError) as e:
+            # e.g. an embedded null byte, which trips the underlying syscall.
+            return f"Error: Invalid file path: {format_error_for_display(e)}"
+
         display_filepath = format_path_for_display(
             str(resolved_filepath), str(resolved_directory)
         )

lib/crewai-tools/tests/file_read_tool_test.py

@@ -230,6 +230,51 @@ def test_constructor_path_outside_working_directory_is_readable(tmp_path, monkey
     assert tool._run(file_path=str(target)) == "declared content"
 
 
+def test_declared_file_is_reachable_the_way_an_agent_calls_it(tmp_path, monkeypatch):
+    """The label in the description must resolve to the declared file.
+
+    The description only shows a redacted label, so that label is all the model
+    has to work with. It has to address the declared file.
+    """
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    monkeypatch.chdir(workspace)
+    target = tmp_path / "declared.txt"
+    target.write_text("declared content")
+
+    tool = FileReadTool(file_path=str(target))
+    label = tool._declared_label
+
+    assert label == "declared.txt"
+    assert label in tool.description
+    # Omitting file_path entirely, and passing the advertised label, both work.
+    assert tool.run() == "declared content"
+    assert tool.run(file_path=label) == "declared content"
+
+
+def test_run_without_file_path_reports_error_when_no_default(tmp_path, monkeypatch):
+    """file_path is optional in the schema, so this must not raise."""
+    monkeypatch.chdir(tmp_path)
+
+    assert "Error: No file path provided" in FileReadTool().run()
+
+
+def test_declared_relative_path_survives_chdir(tmp_path, monkeypatch):
+    """The declared file is pinned at construction, not re-resolved per call."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "rel.txt").write_text("original")
+    nested = tmp_path / "sub"
+    nested.mkdir()
+    (nested / "rel.txt").write_text("a different file")
+
+    tool = FileReadTool(file_path="rel.txt")
+    assert tool._run() == "original"
+
+    monkeypatch.chdir(nested)
+    assert tool._run() == "original"
+    assert tool._run(file_path="rel.txt") == "original"
+
+
 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"
@@ -315,6 +360,14 @@ def test_encoding_is_configurable(tmp_path, monkeypatch):
     assert FileReadTool(encoding="latin-1")._run(file_path="latin.txt") == "café"
 
 
+def test_null_byte_path_returns_error_instead_of_raising(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+
+    result = FileReadTool()._run(file_path="a\x00b.txt")
+
+    assert "Error" in result
+
+
 def test_decode_error_names_the_encoding(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     (tmp_path / "binary.bin").write_bytes(bytes(range(256)))

lib/crewai-tools/tests/tools/test_file_writer_tool.py

@@ -368,6 +368,19 @@ def test_directory_that_is_an_existing_file(tool, temp_env):
     assert "overwrite" not in result
 
 
+@pytest.mark.parametrize(
+    ("filename", "directory"),
+    [("a\x00b.txt", "./"), ("ok.txt", "d\x00ir")],
+)
+def test_null_byte_returns_error_instead_of_raising(tool, filename, directory):
+    """_run's contract is to return a descriptive string for bad input."""
+    result = tool._run(
+        filename=filename, directory=directory, content="x", overwrite=True
+    )
+
+    assert "Error" in result
+
+
 def test_writes_utf8_by_default(tool, temp_env):
     content = "café — 日本語 — 🚀"
     tool._run(filename=temp_env["test_file"], content=content, overwrite=True)