13 Permissions

13 Permissions

Source: docs/design/13-permissions.md

Principle

Soft + hard isolation: path gateway for file tools; sandbox for shell; explicit grants for anything beyond defaults.

Default reach

Workdir (if bound), system/toolchain dirs read-only allowlist, never the app data directory (D36).

Grants (D37)

Granted to the requesting Bot, valid in the current conversation; once (single tool call + absolute TTL) or for the rest of the conversation; revocable anytime. Revoke interrupts affected running tasks (permission_revoked).

Flows

File overreach → approval card. Shell → sandbox with live rules. Uns sandboxed execution → every time confirm (D38). Git remote → confirm (D31). Sandbox unavailable → per-command confirm mode (D39) with optional read-only command allowlist (D40).

External agents (D72)

Agent-native tools run in the agent’s own sandbox; permission requests map to agent_tool cards. Never bypass; agents without OS sandbox confirm every command. Not implemented.

Unattended mode (D41)

After danger acknowledgment, pending confirms auto-approve with full audit; optional timed off. Fail-closed: unsandboxed commands that cannot be statically proven off the app data dir are auto-denied. Profile changes never auto-approve (D99).

Approval dedupe & receipts (D78)

Same tool+args already completed on the task chain may skip or annotate cards; unknown prior outcome → card and no unattended auto-approve; user denial → no card. Cards carry payloadHash (stale → APPROVAL_STALE) and execution receipts.