docs: document the new delete filesystem tool [deepagents]

src/oss/deepagents/backends.mdx

@@ -15,10 +15,12 @@ import BackendContextHubPy from '/snippets/code-samples/backend-context-hub-py.m
 import BackendCompositePy from '/snippets/code-samples/backend-composite-py.mdx';
 import BackendCompositeJs from '/snippets/code-samples/backend-composite-js.mdx';
 
-Deep Agents expose a filesystem surface to the agent via tools like `ls`, `read_file`, `write_file`, `edit_file`, `glob`, and `grep`. These tools operate through a pluggable backend. The `read_file` tool natively supports image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) across all backends, returning them as multimodal content blocks.
+:::python
+Deep Agents expose a filesystem surface to the agent via tools like `ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, and `grep`. These tools operate through a pluggable backend. The `read_file` tool natively supports image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) across all backends, returning them as multimodal content blocks.
+:::
 
 :::js
-The `read_file` tool natively supports binary files (images, PDFs, audio, video) across all backends, returning a `ReadResult` with typed `content` and `mimeType`.
+Deep Agents expose a filesystem surface to the agent via tools like `ls`, `read_file`, `write_file`, `edit_file`, `glob`, and `grep`. These tools operate through a pluggable backend. The `read_file` tool natively supports binary files (images, PDFs, audio, video) across all backends, returning a `ReadResult` with typed `content` and `mimeType`.
 :::
 
 Sandboxes and the @[`LocalShellBackend`] also provide an `execute` tool.
@@ -514,6 +516,7 @@ Subclass @[`BackendProtocol`] and implement the following methods:
 | `edit` | `(file_path: str, old_string: str, new_string: str, replace_all: bool) -> EditResult` | Find-and-replace within an existing file. |
 | `glob` | `(pattern: str, path: str | None) -> GlobResult` | Return paths matching a glob pattern. |
 | `grep` | `(pattern: str, path: str | None, glob: str | None) -> GrepResult` | Search file contents for a literal string. |
+| `delete` | `(file_path: str) -> DeleteResult` | Optional. Remove a file or, recursively, a directory. Backends that do not override it inherit a default that raises `NotImplementedError`, and the `delete` tool surfaces that as a "deletion not available" error instead of failing the run. Use `supports_delete()` to check support without triggering it. |
 
 To also support the `execute` tool (running shell commands), implement @[`SandboxBackendProtocol`] instead, which extends `BackendProtocol` with an `execute` method.
 

src/oss/deepagents/code/overview.mdx

@@ -74,7 +74,7 @@ Persistent memory carries context across conversations, customizable skills shap
 
 Deep Agents Code has the following built-in capabilities:
 
-* <Icon icon="file" size={16} /> **File operations** - read, write, and edit files on disk.
+* <Icon icon="file" size={16} /> **File operations** - read, write, edit, and delete files on disk.
 * <Icon icon="terminal" size={16} /> **Shell execution** - execute commands to run tests, build projects, manage dependencies, and interact with version control.
 * <Icon icon="cloud" size={16} /> **[Remote sandboxes](/oss/deepagents/code/remote-sandboxes)** - run agent tools remotely instead of on your local machine.
 * <Icon icon="search" size={16} /> **Web search** - search the web for up-to-date information and documentation. Requires a [Tavily API key](/oss/deepagents/code/configuration#enable-web-search-with-tavily).
@@ -99,6 +99,7 @@ Deep Agents Code has the following built-in capabilities:
     | `read_file` | Read contents of a file; returns multimodal blocks for images, audio, video, and PDFs | - |
     | `write_file` | Create or overwrite a file | Required<sup>1</sup> |
     | `edit_file` | Make targeted edits to existing files | Required<sup>1</sup> |
+    | `delete` | Delete a file, or a directory and its contents recursively | Required<sup>1</sup> |
     | `glob` | Find files matching a pattern | - |
     | `grep` | Search for text patterns across files | - |
     | `execute` | Execute shell commands locally or in a [remote sandbox](/oss/deepagents/code/remote-sandboxes) | Required<sup>1</sup> |

src/oss/deepagents/context-engineering.mdx

@@ -152,7 +152,12 @@ Keep each skill focused on a single workflow or domain; broad or overlapping ski
 
 **Built-in tools** – Middleware that adds harness capabilities (planning, filesystem, subagents) automatically appends tool-specific instructions to the system prompt, creating tool prompts that explain how to use those tools effectively. See [Customization](/oss/deepagents/customization#middleware) for the full list:
 - Planning prompt – Instructions for `write_todos` to maintain a structured task list
+:::python
+- Filesystem prompt – Documentation for `ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, `grep` (and `execute` when using a sandbox backend)
+:::
+:::js
 - Filesystem prompt – Documentation for `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` (and `execute` when using a sandbox backend)
+:::
 - Subagent prompt – Guidance for delegating work with the `task` tool
 - Human-in-the-loop prompt – Usage for pausing at specified tool calls (when `interrupt_on` is set)
 - Local context prompt – Current directory and project info (CLI only)

src/oss/deepagents/frontend/sandbox.mdx

@@ -24,10 +24,22 @@ import FrontendSandboxThreadBackendPy from "/snippets/code-samples/frontend-sand
 
 This setup has three parts:
 
+:::python
+
+1. **Deep agent with a sandbox backend:** The agent gets filesystem tools
+   (`read_file`, `write_file`, `edit_file`, `delete`, `execute`) automatically
+   from the sandbox
+
+:::
+
+:::js
+
 1. **Deep agent with a sandbox backend:** The agent gets filesystem tools
    (`read_file`, `write_file`, `edit_file`, `execute`) automatically from the
    sandbox
 
+:::
+
 :::python
 
 2. **Custom API server** — A FastAPI app exposed via `langgraph.json`'s `http.app`
@@ -797,8 +809,16 @@ Frontend-specific:
 
 - **Persist `threadId` in `sessionStorage`** so page reloads reconnect to the
   same thread and sandbox instead of creating new ones.
+
+:::python
+- **Sync files on every relevant tool call**, not just when the run finishes. Watch for `write_file`, `edit_file`, `delete`, and `execute`
+  tool messages and refresh immediately.
+:::
+:::js
 - **Sync files on every relevant tool call**, not just when the run finishes. Watch for `write_file`, `edit_file`, and `execute`
   tool messages and refresh immediately.
+:::
+
 - **Default to diff view for changed files**. When a user clicks a file that
   was modified by the agent, show the diff first — that's what they care about.
 - **Show compact tool results for read-only operations**. Instead of dumping

src/oss/deepagents/human-in-the-loop.mdx

@@ -72,7 +72,7 @@ You can customize which decisions are available for each tool:
 ```python
 interrupt_on = {
     # Sensitive operations: allow all options
-    "delete_file": {"allowed_decisions": ["approve", "edit", "reject"]},
+    "delete": {"allowed_decisions": ["approve", "edit", "reject"]},
 
     # Moderate risk: approval or rejection only
     "write_file": {"allowed_decisions": ["approve", "reject"]},
@@ -249,7 +249,7 @@ if result.interrupts:  # [!code highlight]
 
     # Provide decisions in the same order as action_requests
     decisions = [
-        {"type": "approve"},  # First tool: delete_file
+        {"type": "approve"},  # First tool: delete
         {
             "type": "reject",
             "message": "User rejected this action. Do not retry this tool call.",
@@ -395,19 +395,17 @@ Each subagent can have its own `interrupt_on` configuration that overrides the m
 ```python
 agent = create_deep_agent(
     model="google_genai:gemini-3.5-flash",
-    tools=[delete_file, read_file],
     interrupt_on={
-        "delete_file": True,
+        "delete": True,
         "read_file": False,
     },
     subagents=[{
         "name": "file-manager",
         "description": "Manages file operations",
         "system_prompt": "You are a file management assistant.",
-        "tools": [delete_file, read_file],
         "interrupt_on": {
             # Override: require approval for reads in this subagent
-            "delete_file": True,
+            "delete": True,
             "read_file": True,  # Different from main agent!
         }
     }],
@@ -820,7 +818,7 @@ Configure different tools based on their risk level:
 ```python
 interrupt_on = {
     # High risk: full control (approve, edit, reject)
-    "delete_file": {"allowed_decisions": ["approve", "edit", "reject"]},
+    "delete": {"allowed_decisions": ["approve", "edit", "reject"]},
     "send_email": {"allowed_decisions": ["approve", "edit", "reject"]},
 
     # Medium risk: no editing allowed

src/oss/deepagents/overview.mdx

@@ -286,16 +286,37 @@ The harness provides a configurable virtual filesystem which can be backed by di
 
 The backends support the following file system operations:
 
+:::python
+
 | Tool | Description |
 | ---- | ----------- |
 | `ls` | List files in a directory with metadata (size, modified time) |
 | `read_file` | Read file contents with line numbers, supports offset/limit for large files. Also supports returning multimodal content blocks for non-text files (images, video, audio, and documents). See supported extensions below. |
 | `write_file` | Create new files |
 | `edit_file` | Perform exact string replacements in files (with global replace mode) |
+| `delete` | Delete a file, or a directory and its contents recursively |
 | `glob` | Find files matching patterns (e.g., `**/*.py`) |
 | `grep` | Search file contents with multiple output modes (files only, content with context, or counts) |
 | `execute` | Run shell commands in the environment (available with [sandbox backends](/oss/deepagents/sandboxes) only) |
 
+<Note>The `delete` tool requires `deepagents>=0.7.0`. Backends that do not implement deletion return a "deletion not available" error instead of the tool succeeding.</Note>
+
+:::
+
+:::js
+
+| Tool | Description |
+| ---- | ----------- |
+| `ls` | List files in a directory with metadata (size, modified time) |
+| `read_file` | Read file contents with line numbers, supports offset/limit for large files. Also supports returning multimodal content blocks for non-text files (images, video, audio, and documents). See supported extensions below. |
+| `write_file` | Create new files |
+| `edit_file` | Perform exact string replacements in files (with global replace mode) |
+| `glob` | Find files matching patterns (e.g., `**/*.py`) |
+| `grep` | Search file contents with multiple output modes (files only, content with context, or counts) |
+| `execute` | Run shell commands in the environment (available with [sandbox backends](/oss/deepagents/sandboxes) only) |
+
+:::
+
 <Accordion title="Supported multimodal file extensions">
 
 | Type | Extensions |
@@ -317,7 +338,7 @@ The backends support the following file system operations:
         "anthropic:claude-sonnet-4-6",
         HarnessProfile(
             excluded_tools=frozenset(
-                {"ls", "read_file", "write_file", "edit_file", "glob", "grep"}
+                {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep"}
             ),
         ),
     )

src/oss/deepagents/permissions.mdx

@@ -36,7 +36,13 @@ Control which files and directories an agent can read or write to using declarat
 </Note>
 :::
 
+:::python
+Permissions only apply to the built-in filesystem tools (`ls`, `read_file`, `glob`, `grep`, `write_file`, `edit_file`, `delete`). Custom tools and MCP tools that access the filesystem are not covered. Permissions also do not apply to [sandbox backends](/oss/deepagents/sandboxes), which support arbitrary command execution via the `execute` tool.
+:::
+
+:::js
 Permissions only apply to the built-in filesystem tools (`ls`, `read_file`, `glob`, `grep`, `write_file`, `edit_file`). Custom tools and MCP tools that access the filesystem are not covered. Permissions also do not apply to [sandbox backends](/oss/deepagents/sandboxes), which support arbitrary command execution via the `execute` tool.
+:::
 
 <Tip>
 Use `permissions` when you need **path-based allow/deny rules** on the built-in filesystem tools. Use [backend policy hooks](/oss/deepagents/backends#add-policy-hooks) when you need custom validation logic (rate limiting, audit logging, content inspection) or need to control custom tools.
@@ -68,7 +74,7 @@ Each `FilesystemPermission` has three fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `operations` | `list["read" \| "write"]` | Operations this rule applies to. `"read"` covers `ls`, `read_file`, `glob`, `grep`. `"write"` covers `write_file`, `edit_file`. |
+| `operations` | `list["read" \| "write"]` | Operations this rule applies to. `"read"` covers `ls`, `read_file`, `glob`, `grep`. `"write"` covers `write_file`, `edit_file`, `delete`. |
 | `paths` | `list[str]` | Glob patterns for matching file paths (e.g., `["/workspace/**"]`). Supports `**` for recursive matching and `{a,b}` for alternation. |
 | `mode` | `"allow" \| "deny" \| "interrupt"` | Whether to allow, deny, or pause for human approval on matching operations. Defaults to `"allow"`. See [Pause for human approval](#pause-for-human-approval). |
 
@@ -100,7 +106,7 @@ Paths must be absolute (start with `/`) and cannot contain `..` or `~`. Invalid
 The `"interrupt"` mode requires `deepagents>=0.6.8`.
 </Note>
 
-Set `mode="interrupt"` to pause for human approval instead of allowing or denying a matching operation outright. When the agent calls a built-in write tool (`write_file`, `edit_file`) on a path that matches an interrupt-mode rule, `create_deep_agent` raises a human-in-the-loop interrupt rather than running the tool, and a reviewer can approve, edit, or reject the call.
+Set `mode="interrupt"` to pause for human approval instead of allowing or denying a matching operation outright. When the agent calls a built-in write tool (`write_file`, `edit_file`, `delete`) on a path that matches an interrupt-mode rule, `create_deep_agent` raises a human-in-the-loop interrupt rather than running the tool, and a reviewer can approve, edit, or reject the call.
 
 ```python
 from deepagents import FilesystemPermission, create_deep_agent
@@ -124,8 +130,12 @@ agent = create_deep_agent(
 
 Interrupt-mode rules are wired into the agent's human-in-the-loop middleware automatically and merge with any `interrupt_on` you pass, so you handle and resume them the same way as tool-call interrupts. See [Human-in-the-loop](/oss/deepagents/human-in-the-loop) for the resume flow.
 
+<Note>
+Deleting a directory is all-or-nothing: `delete` checks the `write` permission on the target and every descendant path, and refuses the entire operation if any of them is denied, rather than removing part of the tree.
+</Note>
+
 <Tip>
-Anchor interrupt patterns with a literal leading segment (for example, `/secrets/**` or `/projects/*/secrets/**`). Bulk tools (`ls`, `glob`, `grep`) fire the interrupt when their search subtree could overlap the rule's anchored prefix, so a fully unanchored pattern like `/**/secrets` conservatively over-fires.
+Anchor interrupt patterns with a literal leading segment (for example, `/secrets/**` or `/projects/*/secrets/**`). Bulk tools (`ls`, `glob`, `grep`, and `delete` on a directory) fire the interrupt when their search subtree could overlap the rule's anchored prefix, so a fully unanchored pattern like `/**/secrets` conservatively over-fires.
 </Tip>
 
 :::

src/oss/deepagents/sandboxes.mdx

@@ -15,7 +15,12 @@ Agents generate code, interact with filesystems, and run shell commands. Because
 
 In Deep Agents, **sandboxes are [backends](/oss/deepagents/backends)** that define the environment where the agent operates. Unlike other backends (State, Filesystem, Store) which only expose file operations, sandbox backends also give the agent an `execute` tool for running shell commands. When you configure a sandbox backend, the agent gets:
 
+:::python
+- All standard filesystem tools (`ls`, `read_file`, `write_file`, `edit_file`, `delete`, `glob`, `grep`)
+:::
+:::js
 - All standard filesystem tools (`ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`)
+:::
 - The `execute` tool for running arbitrary shell commands in the sandbox
 - A secure boundary that protects your host system
 
@@ -307,7 +312,14 @@ See [security considerations](#security-considerations) for how to handle secret
 
 ### The `execute` method
 
-Sandbox backends have a simple architecture: the only method a provider must implement is `execute()`, which runs a shell command and returns its output. Every other filesystem operation (`read`, `write`, `edit`, `ls`, `glob`, `grep`) is built on top of `execute()` by the @[`BaseSandbox`] base class, which constructs scripts and runs them inside the sandbox via `execute()`.
+Sandbox backends have a simple architecture: the only method a provider must implement is `execute()`, which runs a shell command and returns its output.
+
+:::python
+Every other filesystem operation (`read`, `write`, `edit`, `delete`, `ls`, `glob`, `grep`) is built on top of `execute()` by the @[`BaseSandbox`] base class, which constructs scripts and runs them inside the sandbox via `execute()`.
+:::
+:::js
+Every other filesystem operation (`read`, `write`, `edit`, `ls`, `glob`, `grep`) is built on top of `execute()` by the @[`BaseSandbox`] base class, which constructs scripts and runs them inside the sandbox via `execute()`.
+:::
 
 ```mermaid
 graph TB
@@ -542,7 +554,12 @@ If a command produces very large output, the result is automatically saved to a
 
 There are two distinct ways files move in and out of a sandbox, and it's important to understand when to use each:
 
-**Agent filesystem tools**: `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`, and `execute` are the tools the LLM calls during its execution. These go through `execute()` inside the sandbox. The agent uses them to read code, write files, and run commands as part of its task.
+:::python
+**Agent filesystem tools**: `read_file`, `write_file`, `edit_file`, `delete`, `ls`, `glob`, `grep`, `execute` are the tools the LLM calls during its execution. These go through `execute()` inside the sandbox. The agent uses them to read code, write files, and run commands as part of its task.
+:::
+:::js
+**Agent filesystem tools**: `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`, `execute` are the tools the LLM calls during its execution. These go through `execute()` inside the sandbox. The agent uses them to read code, write files, and run commands as part of its task.
+:::
 
 **File transfer APIs**: the `uploadFiles()` and `downloadFiles()` methods that your application code calls. These use the provider's native file transfer APIs (not shell commands) and are designed for moving files between your host environment and the sandbox. Use these to:
 - **Seed the sandbox** with source code, configuration, or data before the agent runs

src/oss/deepagents/tools.mdx

@@ -132,6 +132,25 @@ For detailed configuration options — including stdio servers, OAuth authentica
 
 In addition to the tools you provide, every Deep Agent comes with a built-in set of tools from the harness:
 
+:::python
+
+| Tool | Description |
+| ---- | ----------- |
+| `ls` | List files in a directory |
+| `read_file` | Read file contents (with pagination and multimodal support) |
+| `write_file` | Create new files |
+| `edit_file` | Perform exact string replacements in files |
+| `delete` | Delete a file, or a directory and its contents recursively |
+| `glob` | Find files matching a glob pattern |
+| `grep` | Search file contents |
+| `execute` | Run shell commands (sandbox backends only) |
+| `task` | Spawn a subagent to handle a delegated task |
+| `write_todos` | Manage a structured todo list |
+
+:::
+
+:::js
+
 | Tool | Description |
 | ---- | ----------- |
 | `ls` | List files in a directory |
@@ -144,6 +163,8 @@ In addition to the tools you provide, every Deep Agent comes with a built-in set
 | `task` | Spawn a subagent to handle a delegated task |
 | `write_todos` | Manage a structured todo list |
 
+:::
+
 For a full breakdown of what each built-in tool does, see [Harness overview](/oss/deepagents/overview#execution-environment).
 
 ## Multimodal tool outputs