Permissions & Sandbox

Permissions & Sandbox — Title: Permissions & Sandbox

# Permissions & Sandbox

## Agent mode

| Mode | Description |
|---|---|
| `build` | full access — the agent can read, write, edit files, run bash (subject to per-tool permissions) |
| `plan` | read-only — every write-capable tool is forced to `deny` |

Switch with `/agent`. In `plan` mode, the following overrides apply on top of the default permissions:

```python
PLAN_PERMS = {
    "bash":        "deny",
    "write":       "deny",
    "extract":     "deny",
    "edit":        "deny",
    "apply_patch": "deny",
}

Permission levels

Each tool has one of three levels:

Level	Meaning
allow	runs immediately, no confirmation
ask	asks for confirmation before running
deny	not allowed to run

Default permissions (build mode)

DEFAULT_PERMS = {
    "bash":        "ask",     # the only tool defaulting to "ask" — can run arbitrary commands
    "write":       "allow",
    "extract":     "allow",
    "edit":        "allow",
    "apply_patch": "allow",
    "read":        "allow",
    "glob":        "allow",
    "grep":        "allow",
    "webfetch":    "allow",
    "websearch":   "allow",
    "todowrite":   "allow",
    "todoread":    "allow",
    "question":    "allow",
    "task":        "allow",
    "skill":       "allow",
    "lsp":         "allow",
}

Changing permissions

/perm <tool> <level>     # e.g. /perm bash allow
/perms                   # view current permissions

Per-session sandbox

Each session runs in its own isolated working directory (project_dir), initialized and enforced by 04_agent_cache.py:

• _sandbox_init(conn, sid, project_dir_str) — called at session start to restore or initialize the sandbox.
  • is_placeholder=True: no file has been written yet — tools_fs doesn't fully enforce sandbox reads yet (the AI can read the existing project).
  • is_placeholder=False: after the first write, the sandbox is fully enforced — flips from placeholder to a real sandbox.
• _resolve_to_sandbox(path) — normalizes any relative/absolute path to inside the sandbox.
• _check_sandbox_read(path) — blocks reads of files outside the sandbox once enforcement is active.

View the current sandbox with:

/sandbox

Related

• Tools and their default permissions by category: Agent Tools
• All slash commands for managing permissions/sandbox: Slash Commands