fix(tools): sandbox FileWriterTool writes and fix file tool rough edges

FileReadTool confined reads to the working directory, but FileWriterTool
only checked that `filename` stayed inside `directory` — and `directory`
itself is an LLM-supplied schema field. An agent could therefore write
anywhere the process had permission to, including ~/.ssh and site-packages,
while the reader refused to read back what the writer had just written.
FileWriterTool was the only filesystem tool in the package that did not go
through validate_file_path; files_compressor_tool validates even its
output path.

Writes are now confined to base_dir (the working directory by default):
the resolved directory must sit inside base_dir, and the resolved file
must sit inside that directory. The pre-existing filename containment
check is kept as-is and still applies even when the unsafe-paths escape
hatch is on, so no existing guarantee is weakened.

Both tools gain a base_dir field so a developer can widen the sandbox
deliberately instead of reaching for the process-wide
CREWAI_TOOLS_ALLOW_UNSAFE_PATHS kill switch. FileReadTool also stops
rejecting a file_path given to its own constructor: that is
developer-declared intent, and declaring one file does not expose its
siblings.

Also fixed:

- FileReadTool scanned the whole file when reading a line window; it now
  stops via islice once the requested lines are collected.
- FileWriterTool._run(**kwargs) made the documented positional call
  signature raise TypeError and turned a missing overwrite into
  "error accessing key". It now takes named parameters in the documented
  (filename, content, directory) order.
- A directory naming an existing file reported "already exists and
  overwrite option was not passed" even with overwrite=True; it now
  explains the real problem.
- Subdirectories inside filename are created, matching what passing
  directory already did.
- Both tools now write and decode UTF-8 by default instead of the
  platform locale encoding, with an encoding field to override. The docs
  already claimed UTF-8 and recommended the writer to Windows users.
- The writer's schema fields had no descriptions for the LLM.
- Docs claimed FileReadTool parses JSON into a dict (it never has),
  shipped a snippet that raised TypeError, and did not mention the path
  sandbox. The writer README also began with a stray "Here's the
  rewritten README" preamble.

BREAKING CHANGE: FileWriterTool no longer writes outside the working
directory. Pass base_dir to authorize a different tree.

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` وغيرها. اعتماداً على نوع الملف، توفر المجموعة وظائف متخصصة، مثل تحويل محتوى JSON إلى قاموس Python لسهولة الاستخدام.
+تمثل أداة FileReadTool مفهومياً مجموعة من الوظائف ضمن حزمة crewai_tools تهدف إلى تسهيل قراءة الملفات واسترجاع المحتوى. تتضمن هذه المجموعة أدوات لمعالجة ملفات نصية دفعية، وقراءة ملفات التكوين أثناء التشغيل، واستيراد البيانات للتحليلات. تدعم مجموعة متنوعة من صيغ الملفات النصية مثل `.txt` و `.csv` و `.json` وغيرها. يُعاد المحتوى دائماً كنص عادي.
 
 ## التثبيت
 

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

@@ -30,7 +30,11 @@ from crewai_tools import FileWriterTool
 file_writer_tool = FileWriterTool()
 
 # Write content to a file in a specified directory
-result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
+result = file_writer_tool.run(
+    filename='example.txt',
+    content='This is a test content.',
+    directory='test_directory',
+)
 print(result)
 ```
 

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

@@ -11,10 +11,12 @@ mode: "wide"
     We are still working on improving tools, so there might be unexpected behavior or changes in the future.
 </Note>
 
-The FileReadTool conceptually represents a suite of functionalities within the crewai_tools package aimed at facilitating file reading and content retrieval. 
-This suite includes tools for processing batch text files, reading runtime configuration files, and importing data for analytics. 
-It supports a variety of text-based file formats such as `.txt`, `.csv`, `.json`, and more. Depending on the file type, the suite offers specialized functionality, 
-such as converting JSON content into a Python dictionary for ease of use.
+The `FileReadTool` reads the contents of a file from the local file system and returns it as text.
+It is useful for batch text file processing, reading runtime configuration files, and importing data for analytics.
+It supports any text-based file format, such as `.txt`, `.csv`, `.json`, and `.md`.
+Content is always returned as plain text — parsing it (for example, `json.loads` on a `.json` file) is up to the agent or your own code.
+
+For large files, `start_line` and `line_count` read just a window of lines instead of loading the whole file.
 
 ## Installation
 
@@ -31,15 +33,48 @@ To get started with the FileReadTool:
 ```python Code
 from crewai_tools import FileReadTool
 
-# Initialize the tool to read any files the agents knows or lean the path for
+# Initialize the tool to read any file the agent knows or learns the path for
 file_read_tool = FileReadTool()
 
 # OR
 
-# Initialize the tool with a specific file path, so the agent can only read the content of the specified file
+# Initialize with a specific file path, so the agent reads that file by default
 file_read_tool = FileReadTool(file_path='path/to/your/file.txt')
+
+# Read a window of lines (lines 100-149) instead of the whole file
+partial_content = file_read_tool.run(
+    file_path='path/to/your/file.txt',
+    start_line=100,
+    line_count=50,
+)
 ```
 
 ## Arguments
 
-- `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.
+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.
+- `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.
+
+You set these when constructing the tool:
+
+- `file_path`: (Optional) A default file to read when the agent calls the tool with no arguments.
+- `base_dir`: (Optional) The directory that runtime paths must stay inside. Defaults to the current working directory.
+- `encoding`: (Optional) Text encoding used to decode the file. Defaults to `utf-8`.
+
+## Allowed paths
+
+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.
+
+To let an agent read a directory tree outside the working directory, point `base_dir` at it:
+
+```python Code
+# The agent may read anything under /data, and nothing outside it
+file_read_tool = FileReadTool(base_dir='/data')
+```
+
+As a last resort, setting `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` disables path validation. This applies process-wide to every crewai-tools tool, including the SSRF protections on URL-fetching tools, so prefer `base_dir`.

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

@@ -11,7 +11,7 @@ mode: "wide"
 
 The `FileWriterTool` is a component of the crewai_tools package, designed to simplify the process of writing content to files with cross-platform compatibility (Windows, Linux, macOS). 
 It is particularly useful in scenarios such as generating reports, saving logs, creating configuration files, and more. 
-This tool handles path differences across operating systems, supports UTF-8 encoding, and automatically creates directories if they don't exist, making it easier to organize your output reliably across different platforms.
+This tool handles path differences across operating systems, writes UTF-8 by default rather than the platform's locale encoding, and automatically creates directories if they don't exist, making it easier to organize your output reliably across different platforms.
 
 ## Installation
 
@@ -32,15 +32,45 @@ from crewai_tools import FileWriterTool
 file_writer_tool = FileWriterTool()
 
 # Write content to a file in a specified directory
-result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
+result = file_writer_tool.run(
+    filename='example.txt',
+    content='This is a test content.',
+    directory='test_directory',
+)
 print(result)
 ```
 
 ## Arguments
 
-- `filename`: The name of the file you want to create or overwrite.
-- `content`: The content to write into the file.
-- `directory` (optional): The path to the directory where the file will be created. Defaults to the current directory (`.`). If the directory does not exist, it will be created.
+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.
+- `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:
+
+- `base_dir` (optional): The directory that writes must stay inside. Defaults to the current working directory.
+- `encoding` (optional): Text encoding used to write the file. Defaults to `utf-8`.
+
+## Allowed paths
+
+Because both the directory and the filename are usually chosen by an LLM at runtime, writes are confined to a sandbox:
+
+- The resolved `directory` must be inside `base_dir`, which defaults to the current working directory.
+- The resolved file must then be inside that `directory`. `..` segments, absolute paths, and symlinks are resolved before both checks, so they cannot be used to escape.
+
+To let an agent write outside the working directory, point `base_dir` at the target tree:
+
+```python Code
+# The agent may write anywhere under /var/output, and nowhere outside it
+file_writer_tool = FileWriterTool(base_dir='/var/output')
+```
+
+<Note>
+    Previously an absolute `directory` could write anywhere the process had permission to. If you relied on that, set `base_dir` to the tree you want to allow. Setting `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` restores the old behavior, but it applies process-wide to every crewai-tools tool, including the SSRF protections on URL-fetching tools, so prefer `base_dir`.
+</Note>
 
 ## Conclusion
 

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

@@ -13,8 +13,7 @@ mode: "wide"
 
 FileReadTool은 crewai_tools 패키지 내에서 파일 읽기와 콘텐츠 검색을 용이하게 하는 기능 모음입니다.
 이 모음에는 배치 텍스트 파일 처리, 런타임 구성 파일 읽기, 분석을 위한 데이터 가져오기 등 다양한 도구가 포함되어 있습니다.
-`.txt`, `.csv`, `.json` 등 다양한 텍스트 기반 파일 형식을 지원합니다. 파일 유형에 따라 이 모음은
-JSON 콘텐츠를 Python 딕셔너리로 변환하여 사용을 쉽게 하는 등 특화된 기능을 제공합니다.
+`.txt`, `.csv`, `.json` 등 다양한 텍스트 기반 파일 형식을 지원합니다. 콘텐츠는 항상 일반 텍스트로 반환됩니다.
 
 ## 설치
 

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

@@ -32,7 +32,11 @@ from crewai_tools import FileWriterTool
 file_writer_tool = FileWriterTool()
 
 # Write content to a file in a specified directory
-result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
+result = file_writer_tool.run(
+    filename='example.txt',
+    content='This is a test content.',
+    directory='test_directory',
+)
 print(result)
 ```
 

docs/edge/pt-BR/tools/file-document/filereadtool.mdx

@@ -13,8 +13,7 @@ mode: "wide"
 
 O FileReadTool representa conceitualmente um conjunto de funcionalidades dentro do pacote crewai_tools voltadas para facilitar a leitura e a recuperação de conteúdo de arquivos.
 Esse conjunto inclui ferramentas para processar arquivos de texto em lote, ler arquivos de configuração em tempo de execução e importar dados para análise.
-Ele suporta uma variedade de formatos de arquivo baseados em texto, como `.txt`, `.csv`, `.json` e outros. Dependendo do tipo de arquivo, o conjunto oferece funcionalidades especializadas,
-como converter conteúdo JSON em um dicionário Python para facilitar o uso.
+Ele suporta uma variedade de formatos de arquivo baseados em texto, como `.txt`, `.csv`, `.json` e outros. O conteúdo é sempre retornado como texto simples.
 
 ## Instalação
 

docs/edge/pt-BR/tools/file-document/filewritetool.mdx

@@ -32,7 +32,11 @@ from crewai_tools import FileWriterTool
 file_writer_tool = FileWriterTool()
 
 # Escreva conteúdo em um arquivo em um diretório especificado
-result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory')
+result = file_writer_tool.run(
+    filename='example.txt',
+    content='This is a test content.',
+    directory='test_directory',
+)
 print(result)
 ```
 

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

@@ -2,9 +2,9 @@
 
 ## Description
 
-The FileReadTool is a versatile component of the crewai_tools package, designed to streamline the process of reading and retrieving content from files. It is particularly useful in scenarios such as batch text file processing, runtime configuration file reading, and data importation for analytics. This tool supports various text-based file formats including `.txt`, `.csv`, `.json`, and adapts its functionality based on the file type, for instance, converting JSON content into a Python dictionary for easy use.
+The FileReadTool is a versatile component of the crewai_tools package, designed to streamline the process of reading and retrieving content from files. It is particularly useful in scenarios such as batch text file processing, runtime configuration file reading, and data importation for analytics. This tool supports any text-based file format, including `.txt`, `.csv`, `.json`, and `.md`. Content is always returned as plain text — parsing it (for example, `json.loads` on a `.json` file) is up to the agent or your own code.
 
-The tool also supports reading specific chunks of a file by specifying a starting line and the number of lines to read, which is helpful when working with large files that don't need to be loaded entirely into memory.
+The tool also supports reading specific chunks of a file by specifying a starting line and the number of lines to read, which is helpful when working with large files that don't need to be loaded entirely into memory. Reading a window stops as soon as the requested lines have been collected, so it does not scan the rest of the file.
 
 ## Installation
 
@@ -21,12 +21,12 @@ To get started with the FileReadTool:
 ```python
 from crewai_tools import FileReadTool
 
-# Initialize the tool to read any files the agents knows or lean the path for
+# Initialize the tool to read any file the agent knows or learns the path for
 file_read_tool = FileReadTool()
 
 # OR
 
-# Initialize the tool with a specific file path, so the agent can only read the content of the specified file
+# Initialize the tool with a specific file path, so the agent reads that file by default
 file_read_tool = FileReadTool(file_path='path/to/your/file.txt')
 
 # Read a specific chunk of the file (lines 100-149)
@@ -35,6 +35,30 @@ partial_content = file_read_tool.run(file_path='path/to/your/file.txt', start_li
 
 ## Arguments
 
+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.
 - `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.
+
+You set these when constructing the tool:
+
+- `file_path`: (Optional) A default file to read when the agent calls the tool with no arguments.
+- `base_dir`: (Optional) The directory that runtime paths must stay inside. Defaults to the current working directory.
+- `encoding`: (Optional) Text encoding used to decode the file. Defaults to `utf-8`.
+
+## Allowed paths
+
+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.
+
+To let an agent read a directory tree outside the working directory, point `base_dir` at it:
+
+```python
+# The agent may read anything under /data, and nothing outside it
+file_read_tool = FileReadTool(base_dir='/data')
+```
+
+Setting `CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true` disables path validation, but it applies process-wide to every crewai-tools tool, including the SSRF protections on URL-fetching tools, so prefer `base_dir`.