deepagents 0.3.7a1__tar.gz → 0.3.8__tar.gz

{deepagents-0.3.7a1 → deepagents-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents
-Version: 0.3.7a1
+Version: 0.3.8
 Summary: General purpose 'deep agent' with sub-agent spawning, todo list capabilities, and mock file system. Built on LangGraph.
 License: MIT
 Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview

{deepagents-0.3.7a1 → deepagents-0.3.8}/deepagents/backends/filesystem.py

@@ -31,6 +31,39 @@ class FilesystemBackend(BackendProtocol):
     Files are accessed using their actual filesystem paths. Relative paths are
     resolved relative to the current working directory. Content is read/written
     as plain text, and metadata (timestamps) are derived from filesystem stats.
+
+    !!! warning "Security Warning"
+
+        This backend grants agents direct filesystem read/write access. Use with
+        caution and only in appropriate environments.
+
+        **Appropriate use cases:**
+
+        - Local development CLIs (coding assistants, development tools)
+        - CI/CD pipelines (see security considerations below)
+
+        **Inappropriate use cases:**
+
+        - Web servers or HTTP APIs - use `StateBackend`, `StoreBackend`, or
+            `SandboxBackend` instead
+
+        **Security risks:**
+
+        - Agents can read any accessible file, including secrets (API keys,
+            credentials, `.env` files)
+        - Combined with network tools, secrets may be exfiltrated via SSRF attacks
+        - File modifications are permanent and irreversible
+
+        **Recommended safeguards:**
+
+        1. Enable Human-in-the-Loop (HITL) middleware to review sensitive operations
+        2. Exclude secrets from accessible filesystem paths (especially in CI/CD)
+        3. Use `SandboxBackend` for production environments requiring filesystem
+            interaction
+        4. **Always** use `virtual_mode=True` with `root_dir` to enable path-based
+            access restrictions (blocks `..`, `~`, and absolute paths outside root).
+            Note that the default (`virtual_mode=False`) provides no security even with
+            `root_dir` set.
     """
 
     def __init__(
@@ -44,14 +77,29 @@ class FilesystemBackend(BackendProtocol):
         Args:
             root_dir: Optional root directory for file operations.
 
-                If provided, all file paths will be resolved relative to this directory.
-                If not provided, uses the current working directory.
-            virtual_mode: Enables sandboxed operation where all paths are treated as
-                virtual paths rooted at `root_dir`.
+                - If not provided, defaults to the current working directory.
+                - When `virtual_mode=False` (default): Only affects relative path
+                    resolution. Provides **no security** - agents can access any file
+                    using absolute paths or `..` sequences.
+                - When `virtual_mode=True`: All paths are restricted to this
+                    directory with traversal protection enabled.
+
+            virtual_mode: Enable path-based access restrictions.
+
+                When `True`, all paths are treated as virtual paths anchored to
+                `root_dir`. Path traversal (`..`, `~`) is blocked and all resolved paths
+                are verified to remain within `root_dir`.
+
+                When `False` (default), **no security is provided**:
+
+                - Absolute paths (e.g., `/etc/passwd`) bypass `root_dir` entirely
+                - Relative paths with `..` can escape `root_dir`
+                - Agents have unrestricted filesystem access
+
+                **Security note:** `virtual_mode=True` provides path-based access
+                control, not process isolation. It restricts which files can be
+                accessed via paths, but does not sandbox the Python process itself.
 
-                Path traversal (using `..` or `~`) is disallowed and all resolved paths
-                must remain within the root directory. When `False` (default), absolute
-                paths are allowed as-is and relative paths resolve under cwd.
             max_file_size_mb: Maximum file size in megabytes for operations like
                 grep's Python fallback search.
 

{deepagents-0.3.7a1 → deepagents-0.3.8}/deepagents/graph.py

@@ -5,7 +5,6 @@ from typing import Any
 
 from langchain.agents import create_agent
 from langchain.agents.middleware import HumanInTheLoopMiddleware, InterruptOnConfig, TodoListMiddleware
-from langchain.agents.middleware.summarization import SummarizationMiddleware
 from langchain.agents.middleware.types import AgentMiddleware
 from langchain.agents.structured_output import ResponseFormat
 from langchain.chat_models import init_chat_model
@@ -26,6 +25,7 @@ from deepagents.middleware.memory import MemoryMiddleware
 from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
 from deepagents.middleware.skills import SkillsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
+from deepagents.middleware.summarization import SummarizationMiddleware
 
 BASE_AGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools."
 
@@ -38,7 +38,7 @@ def get_default_model() -> ChatAnthropic:
     """
     return ChatAnthropic(
         model_name="claude-sonnet-4-5-20250929",
-        max_tokens=20000,
+        max_tokens=20000,  # type: ignore[call-arg]
     )
 
 
@@ -63,11 +63,14 @@ def create_deep_agent(
 ) -> CompiledStateGraph:
     """Create a deep agent.
 
-    Deep agents require a LLM that supports tool calling.
+    !!! warning "Deep agents require a LLM that supports tool calling!"
 
-    This agent will by default have access to a tool to write todos (`write_todos`),
-    seven file and execution tools: `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`,
-    and a tool to call subagents (`task`).
+    By default, this agent has access to the following tools:
+
+    - `write_todos`: manage a todo list
+    - `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`: file operations
+    - `execute`: run shell commands
+    - `task`: call subagents
 
     The `execute` tool allows running shell commands if the backend implements `SandboxBackendProtocol`.
     For non-sandbox backends, the `execute` tool will return an error message.
@@ -82,10 +85,14 @@ def create_deep_agent(
 
             In addition to custom tools you provide, deep agents include built-in tools for planning,
             file management, and subagent spawning.
-        system_prompt: The additional instructions the agent should have.
-
-            Will go in the system prompt. Can be a string or a `SystemMessage`.
-        middleware: Additional middleware to apply after standard middleware.
+        system_prompt: Custom system instructions to prepend before the base deep agent
+            prompt.
+
+            If a string, it's concatenated with the base prompt.
+        middleware: Additional middleware to apply after the standard middleware stack
+            (`TodoListMiddleware`, `FilesystemMiddleware`, `SubAgentMiddleware`,
+            `SummarizationMiddleware`, `AnthropicPromptCachingMiddleware`,
+            `PatchToolCallsMiddleware`).
         subagents: The subagents to use.
 
             Each subagent should be a `dict` with the following keys:
@@ -142,9 +149,17 @@ def create_deep_agent(
     ):
         trigger = ("fraction", 0.85)
         keep = ("fraction", 0.10)
+        truncate_args_settings = {
+            "trigger": ("fraction", 0.85),
+            "keep": ("fraction", 0.10),
+        }
     else:
         trigger = ("tokens", 170000)
         keep = ("messages", 6)
+        truncate_args_settings = {
+            "trigger": ("messages", 20),
+            "keep": ("messages", 20),
+        }
 
     # Build middleware stack for subagents (includes skills if provided)
     subagent_middleware: list[AgentMiddleware] = [
@@ -160,9 +175,11 @@ def create_deep_agent(
             FilesystemMiddleware(backend=backend),
             SummarizationMiddleware(
                 model=model,
+                backend=backend,
                 trigger=trigger,
                 keep=keep,
                 trim_tokens_to_summarize=None,
+                truncate_args_settings=truncate_args_settings,
             ),
             AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
             PatchToolCallsMiddleware(),
@@ -190,9 +207,11 @@ def create_deep_agent(
             ),
             SummarizationMiddleware(
                 model=model,
+                backend=backend,
                 trigger=trigger,
                 keep=keep,
                 trim_tokens_to_summarize=None,
+                truncate_args_settings=truncate_args_settings,
             ),
             AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
             PatchToolCallsMiddleware(),

{deepagents-0.3.7a1 → deepagents-0.3.8}/deepagents/middleware/__init__.py

@@ -1,9 +1,10 @@
-"""Middleware for the DeepAgent."""
+"""Middleware for the agent."""
 
 from deepagents.middleware.filesystem import FilesystemMiddleware
 from deepagents.middleware.memory import MemoryMiddleware
 from deepagents.middleware.skills import SkillsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
+from deepagents.middleware.summarization import SummarizationMiddleware
 
 __all__ = [
     "CompiledSubAgent",
@@ -12,4 +13,5 @@ __all__ = [
     "SkillsMiddleware",
     "SubAgent",
     "SubAgentMiddleware",
+    "SummarizationMiddleware",
 ]

{deepagents-0.3.7a1 → deepagents-0.3.8}/deepagents/middleware/filesystem.py

@@ -20,8 +20,9 @@ from langgraph.types import Command
 from typing_extensions import TypedDict
 
 from deepagents.backends import StateBackend
+from deepagents.backends.composite import CompositeBackend
 from deepagents.backends.protocol import (
-    BACKEND_TYPES as BACKEND_TYPES,  # Re-export for backwards compatibility
+    BACKEND_TYPES as BACKEND_TYPES,  # Re-export type here for backwards compatibility
     BackendProtocol,
     EditResult,
     SandboxBackendProtocol,
@@ -154,19 +155,16 @@ class FilesystemState(AgentState):
     """Files in the filesystem."""
 
 
-LIST_FILES_TOOL_DESCRIPTION = """Lists all files in the filesystem, filtering by directory.
+LIST_FILES_TOOL_DESCRIPTION = """Lists all files in a directory.
 
-Usage:
-- The path parameter must be an absolute path, not a relative path
-- The list_files tool will return a list of all files in the specified directory.
-- This is very useful for exploring the file system and finding the right file to read or edit.
-- You should almost ALWAYS use this tool before using the Read or Edit tools."""
+This is useful for exploring the filesystem and finding the right file to read or edit.
+You should almost ALWAYS use this tool before using the read_file or edit_file tools."""
+
+READ_FILE_TOOL_DESCRIPTION = """Reads a file from the filesystem.
 
-READ_FILE_TOOL_DESCRIPTION = """Reads a file from the filesystem. You can access any file directly by using this tool.
-Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
 
 Usage:
-- The file_path parameter must be an absolute path, not a relative path
 - By default, it reads up to 100 lines starting from the beginning of the file
 - **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
   - First scan: read_file(path, limit=100) to see file structure
@@ -182,61 +180,46 @@ Usage:
 EDIT_FILE_TOOL_DESCRIPTION = """Performs exact string replacements in files.
 
 Usage:
-- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
-- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
-- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
-- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance."""
+- You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
+- When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
+- ALWAYS prefer editing existing files over creating new ones.
+- Only use emojis if the user explicitly requests it."""
 
 
 WRITE_FILE_TOOL_DESCRIPTION = """Writes to a new file in the filesystem.
 
 Usage:
-- The file_path parameter must be an absolute path, not a relative path
-- The content parameter must be a string
 - The write_file tool will create the a new file.
-- Prefer to edit existing files over creating new ones when possible."""
-
+- Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.
+"""
 
 GLOB_TOOL_DESCRIPTION = """Find files matching a glob pattern.
 
-Usage:
-- The glob tool finds files by matching patterns with wildcards
-- Supports standard glob patterns: `*` (any characters), `**` (any directories), `?` (single character)
-- Patterns can be absolute (starting with `/`) or relative
-- Returns a list of absolute file paths that match the pattern
+Supports standard glob patterns: `*` (any characters), `**` (any directories), `?` (single character).
+Returns a list of absolute file paths that match the pattern.
 
 Examples:
 - `**/*.py` - Find all Python files
 - `*.txt` - Find all text files in root
 - `/subdir/**/*.md` - Find all markdown files under /subdir"""
 
-GREP_TOOL_DESCRIPTION = """Search for a pattern in files.
+GREP_TOOL_DESCRIPTION = """Search for a text pattern across files.
 
-Usage:
-- The grep tool searches for text patterns across files
-- The pattern parameter is the text to search for (literal string, not regex)
-- The path parameter filters which directory to search in (default is the current working directory)
-- The glob parameter accepts a glob pattern to filter which files to search (e.g., `*.py`)
-- The output_mode parameter controls the output format:
-  - `files_with_matches`: List only file paths containing matches (default)
-  - `content`: Show matching lines with file path and line numbers
-  - `count`: Show count of matches per file
+Searches for literal text (not regex) and returns matching files or content based on output_mode.
 
 Examples:
 - Search all files: `grep(pattern="TODO")`
 - Search Python files only: `grep(pattern="import", glob="*.py")`
 - Show matching lines: `grep(pattern="error", output_mode="content")`"""
 
-EXECUTE_TOOL_DESCRIPTION = """Executes a given command in the sandbox environment with proper handling and security measures.
+EXECUTE_TOOL_DESCRIPTION = """Executes a shell command in an isolated sandbox environment.
 
+Usage:
+Executes a given command in the sandbox environment with proper handling and security measures.
 Before executing the command, please follow these steps:
-
 1. Directory Verification:
    - If the command will create new directories or files, first use the ls tool to verify the parent directory exists and is the correct location
    - For example, before running "mkdir foo/bar", first use ls to check that "foo" exists and is the intended parent directory
-
 2. Command Execution:
    - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
    - Examples of proper quoting:
@@ -246,9 +229,7 @@ Before executing the command, please follow these steps:
      - python /path/with spaces/script.py (incorrect - will fail)
    - After ensuring proper quoting, execute the command
    - Capture the output of the command
-
 Usage notes:
-  - The command parameter is required
   - Commands run in an isolated sandbox environment
   - Returns combined stdout/stderr output with exit code
   - If the output is very large, it may be truncated
@@ -323,7 +304,10 @@ def _ls_tool_generator(
     """
     tool_description = custom_description or LIST_FILES_TOOL_DESCRIPTION
 
-    def sync_ls(runtime: ToolRuntime[None, FilesystemState], path: str) -> str:
+    def sync_ls(
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Absolute path to the directory to list. Must be absolute, not relative."],
+    ) -> str:
         """Synchronous wrapper for ls tool."""
         resolved_backend = _get_backend(backend, runtime)
         validated_path = _validate_path(path)
@@ -332,7 +316,10 @@ def _ls_tool_generator(
         result = truncate_if_too_long(paths)
         return str(result)
 
-    async def async_ls(runtime: ToolRuntime[None, FilesystemState], path: str) -> str:
+    async def async_ls(
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Absolute path to the directory to list. Must be absolute, not relative."],
+    ) -> str:
         """Asynchronous wrapper for ls tool."""
         resolved_backend = _get_backend(backend, runtime)
         validated_path = _validate_path(path)
@@ -365,10 +352,10 @@ def _read_file_tool_generator(
     tool_description = custom_description or READ_FILE_TOOL_DESCRIPTION
 
     def sync_read_file(
-        file_path: str,
+        file_path: Annotated[str, "Absolute path to the file to read. Must be absolute, not relative."],
         runtime: ToolRuntime[None, FilesystemState],
-        offset: int = DEFAULT_READ_OFFSET,
-        limit: int = DEFAULT_READ_LIMIT,
+        offset: Annotated[int, "Line number to start reading from (0-indexed). Use for pagination of large files."] = DEFAULT_READ_OFFSET,
+        limit: Annotated[int, "Maximum number of lines to read. Use for pagination of large files."] = DEFAULT_READ_LIMIT,
     ) -> str:
         """Synchronous wrapper for read_file tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -383,10 +370,10 @@ def _read_file_tool_generator(
         return result
 
     async def async_read_file(
-        file_path: str,
+        file_path: Annotated[str, "Absolute path to the file to read. Must be absolute, not relative."],
         runtime: ToolRuntime[None, FilesystemState],
-        offset: int = DEFAULT_READ_OFFSET,
-        limit: int = DEFAULT_READ_LIMIT,
+        offset: Annotated[int, "Line number to start reading from (0-indexed). Use for pagination of large files."] = DEFAULT_READ_OFFSET,
+        limit: Annotated[int, "Maximum number of lines to read. Use for pagination of large files."] = DEFAULT_READ_LIMIT,
     ) -> str:
         """Asynchronous wrapper for read_file tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -424,8 +411,8 @@ def _write_file_tool_generator(
     tool_description = custom_description or WRITE_FILE_TOOL_DESCRIPTION
 
     def sync_write_file(
-        file_path: str,
-        content: str,
+        file_path: Annotated[str, "Absolute path where the file should be created. Must be absolute, not relative."],
+        content: Annotated[str, "The text content to write to the file. This parameter is required."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> Command | str:
         """Synchronous wrapper for write_file tool."""
@@ -450,8 +437,8 @@ def _write_file_tool_generator(
         return f"Updated file {res.path}"
 
     async def async_write_file(
-        file_path: str,
-        content: str,
+        file_path: Annotated[str, "Absolute path where the file should be created. Must be absolute, not relative."],
+        content: Annotated[str, "The text content to write to the file. This parameter is required."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> Command | str:
         """Asynchronous wrapper for write_file tool."""
@@ -499,12 +486,12 @@ def _edit_file_tool_generator(
     tool_description = custom_description or EDIT_FILE_TOOL_DESCRIPTION
 
     def sync_edit_file(
-        file_path: str,
-        old_string: str,
-        new_string: str,
+        file_path: Annotated[str, "Absolute path to the file to edit. Must be absolute, not relative."],
+        old_string: Annotated[str, "The exact text to find and replace. Must be unique in the file unless replace_all is True."],
+        new_string: Annotated[str, "The text to replace old_string with. Must be different from old_string."],
         runtime: ToolRuntime[None, FilesystemState],
         *,
-        replace_all: bool = False,
+        replace_all: Annotated[bool, "If True, replace all occurrences of old_string. If False (default), old_string must be unique."] = False,
     ) -> Command | str:
         """Synchronous wrapper for edit_file tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -527,12 +514,12 @@ def _edit_file_tool_generator(
         return f"Successfully replaced {res.occurrences} instance(s) of the string in '{res.path}'"
 
     async def async_edit_file(
-        file_path: str,
-        old_string: str,
-        new_string: str,
+        file_path: Annotated[str, "Absolute path to the file to edit. Must be absolute, not relative."],
+        old_string: Annotated[str, "The exact text to find and replace. Must be unique in the file unless replace_all is True."],
+        new_string: Annotated[str, "The text to replace old_string with. Must be different from old_string."],
         runtime: ToolRuntime[None, FilesystemState],
         *,
-        replace_all: bool = False,
+        replace_all: Annotated[bool, "If True, replace all occurrences of old_string. If False (default), old_string must be unique."] = False,
     ) -> Command | str:
         """Asynchronous wrapper for edit_file tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -577,7 +564,11 @@ def _glob_tool_generator(
     """
     tool_description = custom_description or GLOB_TOOL_DESCRIPTION
 
-    def sync_glob(pattern: str, runtime: ToolRuntime[None, FilesystemState], path: str = "/") -> str:
+    def sync_glob(
+        pattern: Annotated[str, "Glob pattern to match files (e.g., '**/*.py', '*.txt', '/subdir/**/*.md')."],
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Base directory to search from. Defaults to root '/'."] = "/",
+    ) -> str:
         """Synchronous wrapper for glob tool."""
         resolved_backend = _get_backend(backend, runtime)
         infos = resolved_backend.glob_info(pattern, path=path)
@@ -585,7 +576,11 @@ def _glob_tool_generator(
         result = truncate_if_too_long(paths)
         return str(result)
 
-    async def async_glob(pattern: str, runtime: ToolRuntime[None, FilesystemState], path: str = "/") -> str:
+    async def async_glob(
+        pattern: Annotated[str, "Glob pattern to match files (e.g., '**/*.py', '*.txt', '/subdir/**/*.md')."],
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Base directory to search from. Defaults to root '/'."] = "/",
+    ) -> str:
         """Asynchronous wrapper for glob tool."""
         resolved_backend = _get_backend(backend, runtime)
         infos = await resolved_backend.aglob_info(pattern, path=path)
@@ -617,11 +612,14 @@ def _grep_tool_generator(
     tool_description = custom_description or GREP_TOOL_DESCRIPTION
 
     def sync_grep(
-        pattern: str,
+        pattern: Annotated[str, "Text pattern to search for (literal string, not regex)."],
         runtime: ToolRuntime[None, FilesystemState],
-        path: str | None = None,
-        glob: str | None = None,
-        output_mode: Literal["files_with_matches", "content", "count"] = "files_with_matches",
+        path: Annotated[str | None, "Directory to search in. Defaults to current working directory."] = None,
+        glob: Annotated[str | None, "Glob pattern to filter which files to search (e.g., '*.py')."] = None,
+        output_mode: Annotated[
+            Literal["files_with_matches", "content", "count"],
+            "Output format: 'files_with_matches' (file paths only, default), 'content' (matching lines with context), 'count' (match counts per file).",
+        ] = "files_with_matches",
     ) -> str:
         """Synchronous wrapper for grep tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -632,11 +630,14 @@ def _grep_tool_generator(
         return truncate_if_too_long(formatted)  # type: ignore[arg-type]
 
     async def async_grep(
-        pattern: str,
+        pattern: Annotated[str, "Text pattern to search for (literal string, not regex)."],
         runtime: ToolRuntime[None, FilesystemState],
-        path: str | None = None,
-        glob: str | None = None,
-        output_mode: Literal["files_with_matches", "content", "count"] = "files_with_matches",
+        path: Annotated[str | None, "Directory to search in. Defaults to current working directory."] = None,
+        glob: Annotated[str | None, "Glob pattern to filter which files to search (e.g., '*.py')."] = None,
+        output_mode: Annotated[
+            Literal["files_with_matches", "content", "count"],
+            "Output format: 'files_with_matches' (file paths only, default), 'content' (matching lines with context), 'count' (match counts per file).",
+        ] = "files_with_matches",
     ) -> str:
         """Asynchronous wrapper for grep tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -666,9 +667,6 @@ def _supports_execution(backend: BackendProtocol) -> bool:
     Returns:
         True if the backend supports execution, False otherwise.
     """
-    # Import here to avoid circular dependency
-    from deepagents.backends.composite import CompositeBackend
-
     # For CompositeBackend, check the default backend
     if isinstance(backend, CompositeBackend):
         return isinstance(backend.default, SandboxBackendProtocol)
@@ -693,7 +691,7 @@ def _execute_tool_generator(
     tool_description = custom_description or EXECUTE_TOOL_DESCRIPTION
 
     def sync_execute(
-        command: str,
+        command: Annotated[str, "Shell command to execute in the sandbox environment."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> str:
         """Synchronous wrapper for execute tool."""
@@ -726,7 +724,7 @@ def _execute_tool_generator(
         return "".join(parts)
 
     async def async_execute(
-        command: str,
+        command: Annotated[str, "Shell command to execute in the sandbox environment."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> str:
         """Asynchronous wrapper for execute tool."""
@@ -766,6 +764,37 @@ def _execute_tool_generator(
     )
 
 
+# Tools that should be excluded from the large result eviction logic.
+#
+# This tuple contains tools that should NOT have their results evicted to the filesystem
+# when they exceed token limits. Tools are excluded for different reasons:
+#
+# 1. Tools with built-in truncation (ls, glob, grep):
+#    These tools truncate their own output when it becomes too large. When these tools
+#    produce truncated output due to many matches, it typically indicates the query
+#    needs refinement rather than full result preservation. In such cases, the truncated
+#    matches are potentially more like noise and the LLM should be prompted to narrow
+#    its search criteria instead.
+#
+# 2. Tools with problematic truncation behavior (read_file):
+#    read_file is tricky to handle as the failure mode here is single long lines
+#    (e.g., imagine a jsonl file with very long payloads on each line). If we try to
+#    truncate the result of read_file, the agent may then attempt to re-read the
+#    truncated file using read_file again, which won't help.
+#
+# 3. Tools that never exceed limits (edit_file, write_file):
+#    These tools return minimal confirmation messages and are never expected to produce
+#    output large enough to exceed token limits, so checking them would be unnecessary.
+TOOLS_EXCLUDED_FROM_EVICTION = (
+    "ls",
+    "glob",
+    "grep",
+    "read_file",
+    "edit_file",
+    "write_file",
+)
+
+
 TOOL_GENERATORS = {
     "ls": _ls_tool_generator,
     "read_file": _read_file_tool_generator,
@@ -814,8 +843,9 @@ class FilesystemMiddleware(AgentMiddleware):
     """Middleware for providing filesystem and optional execution tools to an agent.
 
     This middleware adds filesystem tools to the agent: `ls`, `read_file`, `write_file`,
-    `edit_file`, `glob`, and `grep`. Files can be stored using any backend that implements
-    the `BackendProtocol`.
+    `edit_file`, `glob`, and `grep`.
+
+    Files can be stored using any backend that implements the `BackendProtocol`.
 
     If the backend implements `SandboxBackendProtocol`, an `execute` tool is also added
     for running shell commands.
@@ -836,8 +866,6 @@ class FilesystemMiddleware(AgentMiddleware):
         tool_token_limit_before_evict: Token limit before evicting a tool result to the
             filesystem.
 
-            Defaults to 20,000 tokens.
-
             When exceeded, writes the result using the configured backend and replaces it
             with a truncated preview and file reference.
 
@@ -1070,6 +1098,7 @@ class FilesystemMiddleware(AgentMiddleware):
         processed_message = ToolMessage(
             content=replacement_text,
             tool_call_id=message.tool_call_id,
+            name=message.name,
         )
         return processed_message, result.files_update
 
@@ -1128,6 +1157,7 @@ class FilesystemMiddleware(AgentMiddleware):
         processed_message = ToolMessage(
             content=replacement_text,
             tool_call_id=message.tool_call_id,
+            name=message.name,
         )
         return processed_message, result.files_update
 
@@ -1247,7 +1277,7 @@ class FilesystemMiddleware(AgentMiddleware):
         Returns:
             The raw ToolMessage, or a pseudo tool message with the ToolResult in state.
         """
-        if self.tool_token_limit_before_evict is None or request.tool_call["name"] in TOOL_GENERATORS:
+        if self.tool_token_limit_before_evict is None or request.tool_call["name"] in TOOLS_EXCLUDED_FROM_EVICTION:
             return handler(request)
 
         tool_result = handler(request)
@@ -1267,7 +1297,7 @@ class FilesystemMiddleware(AgentMiddleware):
         Returns:
             The raw ToolMessage, or a pseudo tool message with the ToolResult in state.
         """
-        if self.tool_token_limit_before_evict is None or request.tool_call["name"] in TOOL_GENERATORS:
+        if self.tool_token_limit_before_evict is None or request.tool_call["name"] in TOOLS_EXCLUDED_FROM_EVICTION:
             return await handler(request)
 
         tool_result = await handler(request)