Day 4 Deep Agents: File System & Permission Boundaries for Safe AI Editing

Letting AI modify code risks two problems: it may not see needed files, and it may touch files it shouldn’t. Deep Agents’ file system and permission layer aim to encode read/write boundaries as tool‑level rules rather than merely making the model obedient.

First, the conclusion

Deep Agents’ file capabilities consist of three distinct layers that must not be mixed:

File tools : concrete operations such as ls, read_file, write_file, etc.

Backend : determines where files are actually stored and how they are read or written.

Permissions : specify which paths are allowed for read or write.

Note that FilesystemBackend(root_dir=...) is not a sandbox; permissions govern the file tools, not all shell commands; and writing “do not read secrets” in system_prompt does not constitute a security boundary.

1. The built‑in file tools (six in total)

ls

– list directories (read permission) read_file – read file content (read permission) glob – pattern‑match filenames (read permission) grep – search file content (read permission) write_file – create or overwrite a file (write permission) edit_file – edit an existing file (write permission)

There is no built‑in delete_file. Deleting files must be done via the execute shell command, which requires the backend to support execution and may need sandboxing or manual approval.

2. By default, files are not written to the real disk

All file reads and writes go through a backend. If no backend is specified, Deep Agents uses a virtual file system stored in the agent’s state, so the agent never touches the host’s real disk.

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    # No backend passed – defaults to StateBackend (virtual FS)
)

To write to the local disk, specify a FilesystemBackend with virtual_mode=True:

from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=FilesystemBackend(
        root_dir="/tmp/project",
        virtual_mode=True,
    ),
)

Setting virtual_mode=True makes the virtual path mapping explicit; merely providing root_dir does not create a sandbox, and absolute paths can still resolve to real locations.

3. Permissions are the actual read/write authorisation

The backend decides where files live; permissions decide which paths the agent may operate on. A typical permission configuration looks like this:

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.permissions import FilesystemPermission

permissions = [
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/secrets/**", "/workspace/.env"],
        mode="deny",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/src/**", "/workspace/tests/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=FilesystemBackend(root_dir="/workspace", virtual_mode=True),
    permissions=permissions,
)

This configuration expresses:

Explicitly deny access to secrets and .env files.

Allow read/write under src and tests.

Deny any path not explicitly allowed.

4. Rules to remember

FilesystemPermission

only accepts read or write operations; read covers ls, read_file, glob, grep; write covers write_file, edit_file.

Permissions are evaluated in the order they are declared; the first matching rule wins.

Paths must start with /; patterns using .. or ~ are rejected.

If no rule matches, the default is to allow, so it is advisable to place a catch‑all deny rule at the end.

The permission middleware runs after the model’s reasoning, ensuring that every tool call is subject to the rules.

The most common pitfall is relying on the default “allow” behaviour; a single allow without a fallback deny can unintentionally expose unspecified paths.

5. Sub‑Agent permission inheritance

Sub‑Agents inherit the parent’s permissions and backend by default. If a sub‑Agent defines its own permissions, they replace (not augment) the parent’s rules.

from deepagents.middleware.subagents import SubAgent

reviewer: SubAgent = {
    "name": "code-reviewer",
    "description": "Only reads code, does not modify files.",
    "system_prompt": "You are a code reviewer that only analyses code.",
    "permissions": [
        FilesystemPermission(
            operations=["read"],
            paths=["/workspace/src/**", "/workspace/tests/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
}

This makes it easy to enforce role‑based boundaries, e.g., a main Agent that can read/write code, a reviewer that can only read, and a fixer that can write.

6. Practical ways to secure file permissions

Enable virtual_mode=True when persisting to local disk to make the virtual‑path semantics explicit.

Deny sensitive paths such as .env, secrets/, and .git/ to avoid accidental exposure.

Do not expose node_modules/ or build‑artifact directories to reduce token consumption and search noise.

End the permission list with a catch‑all paths=["/**"], mode="deny" rule.

Restrict sub‑Agents to read‑only when appropriate to shrink responsibilities and risk.

Require separate approval for shell execution because file permissions cannot block arbitrary commands; true isolation needs containers, VMs, or remote sandboxes.

Note that LocalShellBackend is not a sandbox—it can run local shell commands without process isolation. Setting virtual_mode=True only affects file‑tool calls, not shell execution.

My judgment

File permissions are not a complete “anti‑hacker” solution; they mainly prevent an Agent from over‑reaching during normal tasks. In real projects, separate authorisation for source, test, config, log, and build directories is advisable, and secrets such as .env, SSH keys, cloud credentials, or database connection strings should not rely solely on a “don’t read” prompt.

Prompt engineering can reduce model mistakes, but permission rules are what actually stop tools from crossing boundaries.