Session Permission Modes and Filesystem Boundaries
Learn how session permission modes define filesystem boundaries and exec escalation reviewers, and which modes require operator.admin or operator.write. Essential for operators configuring gateway sessions.
Read this when
- Choosing a permission mode for an agent session
- Understanding who reviews an exec escalation
- Comparing session permissions with sandbox and tool policy
Session permission modes define two things for a given session: where its filesystem boundary sits, and who gets to review exec escalations. The boundary is represented by the session's canonical sessionRoot, and the mode dictates what actions are permitted either inside or beyond it.
| Mode | Filesystem access | Exec escalation reviewer |
|---|---|---|
read-only | Reads allowed under sessionRoot; mutation tools are not included | None; exec is refused |
guarded | Reads and writes allowed under sessionRoot | A human, following the allowlist fast path |
workspace | Reads and writes allowed under sessionRoot | LLM review, with a human as fallback |
full | Filesystem access is unrestricted | None |
The full mode depends on operator.admin. All other modes depend on operator.write.
Session root and defaults
When the session is created, the Gateway logs sessionRoot. If an explicit working directory is provided, it becomes the root once canonical path resolution completes. In the absence of an explicit working directory, the session falls back to the canonical workspace of the selected agent.
For managed worktree sessions, the worktree checkout serves as sessionRoot. A nested working directory continues to act as the runtime cwd, meaning relative paths begin there, even though filesystem containment spans the entire checkout.
When no mode is specified, a new managed worktree session defaults to workspace. For other sessions lacking a recorded mode, the existing config-driven behavior remains in effect.
Policy precedence and clamping
When a session mode is set explicitly, it overrides the session's legacy execSecurity and execAsk overrides. If the mode is left unset, those fields, along with the standard global or per-agent configuration, keep functioning as they always have.
An explicit full mode serves as the admin-authorized exception to host approval-file floors: its OpenClaw exec policy stays at full with approvals turned off. Approval-file floors continue to tighten config-driven exec policy, legacy session overrides, unset modes, and every mode that is not full. Sandbox restrictions and tool allow/deny policy operate independently, and a harness may clamp an unsupported mode to a compatible, safer policy tuple. Codex also keeps honoring externally enforced requirements.toml constraints.
For details on the independent sandbox, tool-policy, and elevated-exec controls, refer to Sandbox vs tool policy vs elevated.