feat(sdk): add tools allowlist to FilesystemMiddleware

[Nishitha M (imnishitha)]

Summary

• Adds a tools allowlist to FilesystemMiddleware. The default keeps all tools enabled; passing an explicit set restricts the model to only those tools.
• The system prompt dynamically reflects which tools are actually visible — a tool not in the allowlist is omitted from the prompt entirely, so the model is never told about tools it can't use.
• The allowlist can only narrow the tool set, never widen it. Some tools depend on backend capabilities that the allowlist can't override: execute is only available on sandbox backends, and delete is only available on backends that support deletion. Listing either against a backend that can't serve it is a no-op — the tool is silently filtered out, same as before this PR.
• tools is threaded through create_deep_agent, so the main agent and the general-purpose subagent respect it automatically when you pass a FilesystemMiddleware(tools=...) instance via middleware=. Declarative subagents use their own FilesystemMiddleware spec independently — include one in that subagent's middleware to restrict it.
• read_file cannot be excluded — passing a tools list without it raises ValueError at construction time.
• User-provided (non-filesystem) tools are never affected by the tools list.

How the allowlist interacts with create_deep_agent

create_deep_agent builds separate FilesystemMiddleware instances internally: one for the main agent, one for the general-purpose subagent, and one per declarative subagent. The SDK uses name-based middleware merging — when you pass a FilesystemMiddleware(tools=...) instance via middleware=, it replaces the default FS middleware in-place on the main agent's stack. The general-purpose subagent inherits it too, because its base stack has a FilesystemMiddleware slot with the same .name.

Declarative subagents are different: each has its own independent base stack and only picks up the restriction if you include a FilesystemMiddleware(tools=...) in that subagent's own middleware spec. By design — declarative subagents often need different (broader or narrower) tool sets than the parent.

A single middleware=[FilesystemMiddleware(backend=backend, tools=...)] argument covers the main agent and GP subagent in one shot; declarative subagents require per-subagent opt-in.

Replacing the default FS middleware

Passing your own FilesystemMiddleware instance via middleware= replaces the SDK's default entirely — it is a whole-object swap, not a field-level merge. The default instance was pre-configured with backend, custom_tool_descriptions, and _permissions from the top-level create_deep_agent arguments; any parameter you omit on your own instance falls back to the constructor default, not to what create_deep_agent would have used.

For example, if you set permissions= on create_deep_agent, you must repeat permissions= on your FilesystemMiddleware instance or the rules won't apply.

User-provided tools

The allowlist only governs the eight built-in filesystem tool names (ls, read_file, write_file, edit_file, delete, glob, grep, execute). Any tool whose name isn't in that set passes through untouched — so you can safely layer filesystem restrictions on top of an agent that also has custom domain-specific tools without those tools disappearing.

Motivation

Gives callers explicit control over which filesystem tools are exposed. New tools added to FilesystemMiddleware in the future are automatically hidden from restricted agents without requiring config updates.

Example

# Read-only agent: write, edit, delete, and execute are never shown
agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[
        FilesystemMiddleware(
            backend=backend,
            tools={"read_file", "ls", "glob", "grep"},
        )
    ],
)

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[corridor-security]

Security Issues

• Tool authorization bypass via subagents
  Top-level disable_tools is not propagated to declarative subagents. If an application disables dangerous filesystem tools such as execute, write_file, or delete on the main agent, a user or prompt-injected model can delegate work to a subagent whose middleware is initialized without those disabled tools and regain access to the prohibited capability.

Recommendations

• Combine the parent disable_tools set with any subagent-specific disables when constructing subagent middleware, so subagents can only further restrict tools and cannot re-enable tools disabled at the parent agent level.

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

[ccurme (ccurme)]

can we add at least one minimal end-to-end test in tests/test_end_to_end.py demonstrating how the system prompt is changed, and spying on the request to demonstrate that disabled tools are not there?

[codspeed-hq]

Merging this PR will improve performance by 23.48%

⚡ 1 improved benchmark
✅ 20 untouched benchmarks
⏩ 79 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	WallTime	test_filesystem_init	490.4 µs	397.1 µs	+23.48%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing nm/disable-tools (455dbbd) with main (9eb736b)}

Footnotes

1. 79 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩