feat(sdk): add permissions system for filesystem access control

[Nick Hollon (nick-hollon-lc)]

Examples

Read-only agent (no writes anywhere):

agent = create_deep_agent(
    permissions=[
        FilesystemPermission(operations=["write"], paths=["/**"], mode="deny"),
    ]
)

Sandbox the agent to a workspace directory:

agent = create_deep_agent(
    permissions=[
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/**"], mode="allow"),
        FilesystemPermission(operations=["read", "write"], paths=["/**"], mode="deny"),
    ]
)

Protect examples while allowing broad access:

agent = create_deep_agent(
    permissions=[
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/.env", "/workspace/examples/**"], mode="deny"),
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/**"], mode="allow"),
    ]
)

Subagent with tighter permissions than the parent:

agent = create_deep_agent(
    permissions=[
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/**"], mode="allow"),
        FilesystemPermission(operations=["read", "write"], paths=["/**"], mode="deny"),
    ],
    subagents=[
        {
            "name": "auditor",
            "description": "Read-only code reviewer",
            "system_prompt": "Review the code for issues.",
            "permissions": [
                FilesystemPermission(operations=["write"], paths=["/**"], mode="deny"),
                FilesystemPermission(operations=["read"], paths=["/workspace/**"], mode="allow"),
                FilesystemPermission(operations=["read"], paths=["/**"], mode="deny"),
            ],
        }
    ],
)

What it enforces

• Pre-check: blocks calls to the six built-in filesystem tools (ls, read_file, glob, grep, write_file, edit_file) when the canonicalized path matches a deny rule. Paths are resolved via validate_path() to prevent traversal bypasses.
• Post-filter: after execution, filters denied paths out of ls, glob, and grep results using ToolMessage.artifact (the structured backend result object), then rebuilds the content string.
• Rule evaluation: first-match-wins in declaration order; permissive default (allow if no rule matches).
• Subagent inheritance: subagents inherit the parent's permissions by default. A subagent can specify its own permissions field, which replaces the parent's rules entirely.
• PermissionMiddleware is placed last in the middleware stack so it sees all tools (including those injected by other middleware).

What it does not enforce

• execute tool: shell commands can trivially bypass filesystem restrictions. Rather than silently failing, the middleware raises NotImplementedError at init if the backend supports execution.
• User-provided or MCP tools: only the six built-in filesystem tool names are intercepted. Custom tools that access the filesystem are not covered.
• Tool-level permissions: an earlier iteration explored ToolPermission rules but they were deferred — pattern-matching tool arguments with globs is unsafe for shell commands and type coercion of non-string args is a footgun.

[Hunter Lovell (hntrl)]

nice work!

[Hunter Lovell (hntrl)]

would our guidance be to just remove the tool entirely? (e.g. configurability)

[Nick Hollon (nick-hollon-lc)]

not sure i totally uderstand this question. just an example of disabling a tool completely here

[Hunter Lovell (hntrl)]

is this just intended for pattern matching on basic tool call args? What happens if I have a tool schema thats not just dict[str, str]?

[Nick Hollon (nick-hollon-lc)]

yeah just for basic args. it will stringify the arg before attempting the comparison

[Sydney Runkle (sydney-runkle)]

excited about this!! great work, approving pending comments are addressed

fast follows -- return ToolMessage from all filesystem tools + status of error instead of just error strings for relevant cases

figure out what we're doing for ToolPermissions + execute stuff

[Eugene Yurtsev (eyurtsev)]

OK this looks pretty good!

• minor refactor with respect to permission.py file (merge it with middleware)
• pr description