| 1 | # Permission presets |
| 2 | |
| 3 | Reasonix uses one permission preset for every execution surface: Desktop, CLI, |
| 4 | Serve, ACP, bots, automations, and subagents. Collaboration mode (Normal, Plan, |
| 5 | or Goal) controls how work advances; the permission preset controls the enforced |
| 6 | filesystem and process boundary. |
| 7 | |
| 8 | | Preset | Filesystem boundary | Approval behavior | |
| 9 | | --- | --- | --- | |
| 10 | | **Read only** (`read-only`) | Workspace and session files are mounted read only. | Reads run directly. Writes and unknown external side effects require an exact one-time or session grant. | |
| 11 | | **Workspace write** (`workspace-write`) | The workspace and session-private temporary directory are writable. | Default. Ordinary commands, pipes, command substitution, inline Python/Node, builds, and tests run without syntax-based prompts while they remain inside the boundary. | |
| 12 | | **Full access** (`danger-full-access`) | Commands use the normal host path as the current OS user; Reasonix filesystem and network sandboxing are disabled. | Ordinary `ask` fallbacks are skipped. Explicit host `deny` rules still apply before launch, but Reasonix does not constrain the launched process. | |
| 13 | |
| 14 | - **Collaboration mode** (Normal / Plan / Goal) decides how Reasonix advances the task. There is no automatic task mode or selectable quality floor. Verification obligations come from real tool actions, project rules, task risk, and explicit user requirements. |
| 15 | - **Permission preset** decides the enforced filesystem and process boundary and when exact grants are requested. |
| 16 | |
| 17 | macOS enforces restricted presets with Seatbelt and Linux uses bubblewrap. If |
| 18 | the required backend cannot start there, restricted presets fail closed; |
| 19 | Reasonix never offers to silently rerun the command without isolation. Windows |
| 20 | has no OS-level shell sandbox: restricted presets still confine Reasonix file |
| 21 | tools and request exact grants, but shell commands run as the current OS user. |
| 22 | |
| 23 | ## Approval scope |
| 24 | |
| 25 | An approval card offers at most three decisions: |
| 26 | |
| 27 | 1. **Allow once** — authorize only this request ID. |
| 28 | 2. **Allow for this session** — reuse the displayed canonical directory, |
| 29 | command prefix, server capability, or operation target until the session ends. |
| 30 | 3. **Deny** — reject the call and return the denial to the model. |
| 31 | |
| 32 | There is no permanent approval action. Session grants are held in memory, do not |
| 33 | cross restarts or forks, and can be inspected and revoked. Changing presets or |
| 34 | revoking a grant advances the permission revision. Preset changes and approval |
| 35 | commits are serialized, so an approval that commits first remains valid while a |
| 36 | reply from an older committed revision is rejected. |
| 37 | |
| 38 | Ordinary command failures, HTTP errors, timeouts, and application exceptions are |
| 39 | tool errors. They do not create permission prompts. A retry may request |
| 40 | `sandbox_permissions` only after the host records a real sandbox denial, and |
| 41 | the retry must carry the matching `denial_id` and a justification. |
| 42 | |
| 43 | ## CLI |
| 44 | |
| 45 | New sessions default to workspace write: |
| 46 | |
| 47 | ```sh |
| 48 | reasonix --permission-mode read-only |
| 49 | reasonix --permission-mode workspace-write |
| 50 | reasonix --permission-mode danger-full-access |
| 51 | reasonix run --permission-mode workspace-write "run the tests" |
| 52 | ``` |
| 53 | |
| 54 | In the interactive CLI, `Shift+Tab` cycles Read only → Workspace write → |
| 55 | YOLO → Plan, and `Ctrl+Y` toggles YOLO directly. Both shortcuts |
| 56 | apply the canonical `danger-full-access` preset when they enter YOLO. Legacy saved values are migrated |
| 57 | conservatively: `ask` becomes read only, and `auto` or `yolo` becomes workspace |
| 58 | write. Legacy values never enable full access. |
| 59 | |
| 60 | ## Remote compatibility |
| 61 | |
| 62 | Serve advertises `permission-presets-v1` and its real enforcement capability. |
| 63 | An older remote without that capability remains available for history viewing, |
| 64 | but execution and permission changes are disabled until the remote is upgraded. |
| 65 |