Permissions

The permission layer lets you control which tools agents can call. It sits between the agent and tool dispatch — every tool call passes through permission checks before execution.

Three permission levels

Configuration

Permissions are set in walrus.toml under the [permissions] section:

# Global defaults — apply to all agents
[permissions]
bash = "ask"
write = "deny"

# Per-agent overrides
[permissions.researcher]
bash = "deny"
read = "allow"

Resolution order

When an agent calls a tool, the permission is resolved in this order:

1. Agent-specific override — [permissions.<agent-name>] table
2. Global default — top-level [permissions] entry
3. Built-in default — allow

The first match wins. If no entry exists at any level, the tool is allowed.

How ask works

When a tool has ask permission:

1. The current task is set to Blocked status
2. An inbox item is created with the tool name and arguments
3. The agent waits for a response via ClientMessage::Approve
4. The user responds with approved or denied
5. If approved, the tool executes normally; if denied, the agent receives an error

The ask permission only works within a task context. In a direct REPL session (no task), ask falls back to allow.

Sandbox interaction

When the daemon runs in sandbox mode (as the dedicated walrus OS user), OS tools (read, write, edit, bash) bypass permission checks entirely. The OS-level isolation is considered sufficient.

Non-OS tools (memory, skills, MCP, tasks) still respect the permission config in sandbox mode.

What's next

• Sandbox — OS-level isolation with a dedicated user
• Tasks — how ask integrates with task blocking
• Configuration reference — full [permissions] field reference