Permission modes
A permission mode is the overall stance a session takes before any rule is consulted. It answers one question: when no rule says otherwise, should Syntic Code run a tool call, ask you, or refuse it? You can change the mode at any time, and your permission rules keep applying on top of it.
The six modes
Every screen uses the same name for a mode: the footer, Shift+Tab, /status, /config and /permissions. Settings files and flags take the value in the second column.
| Mode (on screen) | Value in settings and flags | Runs without asking | Asks first |
|---|---|---|---|
| default | default (also manual) | Read-only tools: reading, searching, listing | Anything that changes something |
| auto-edit | acceptEdits | Read-only tools, plus file edits in your working folders | Shell commands, other tools, and edits to protected paths |
| plan | plan | Read-only tools | Nothing: changes are refused |
| auto | auto | Routine work, after a risk review | Anything on the auto mode checklist |
| bypass | bypass | Everything except deny rules | Only the checks that always ask |
| don’t-ask | dontAsk | Only what an allow rule covers | Nothing: the rest is refused quietly |
Values ignore case, dashes and underscores, so accept-edits and dont-ask work too. The older spelling bypassPermissions is accepted and rewritten to bypass when settings are migrated. An unknown value falls back to default rather than breaking the file.
The edit tools that auto-edit covers are Edit, Write, MultiEdit, NotebookEdit and the patch and file-creation tools.
Which mode a session starts in
Syntic Code picks the first of these that applies:
- A flag on the command line:
--permission-mode <mode>, or--dangerously-skip-permissionsfor bypass. - The
SYNTIC_PERMISSION_MODEenvironment variable. permissionMode(orpermissions.defaultMode) in a settings file.- In an interactive session in a trusted folder with nothing chosen anywhere: auto-edit.
- Otherwise: default.
On a fresh install, first-run setup writes "permissionMode": "auto" to your user settings, unless you already picked a mode or auto mode is turned off. It tells you that routine work will run without prompts and that sensitive actions still need your OK.
A repository cannot pick a permissive mode for you. When a project’s .syntic/settings.json or .syntic/settings.local.json sets permissionMode to auto or bypass, that value is dropped and your own choice applies.
Switch modes during a session
| How | Effect |
|---|---|
Shift+Tab | Steps through default, auto-edit, plan and auto. Bypass joins the rotation only if you started in it or passed --allow-dangerously-skip-permissions. |
/plan | Toggles plan mode. /plan <task> switches and sends the task in one go. |
/permissions | Shows the active mode with your rules. |
/config | Changes the saved starting mode. |
The footer always shows the mode in force. When a mode in the rotation is switched off by policy, Shift+Tab skips it and tells you once why.
If an approval prompt is open when you move to a more permissive mode, the waiting call is checked again and runs straight away when the new mode allows it.
Common setups
| You want to | Use |
|---|---|
| Approve every change yourself | default |
| Let the agent edit freely while you review shell commands | auto-edit |
| Explore an unfamiliar codebase or design a change first | plan |
| Work through a long task with few interruptions | auto |
| Run a script or CI job with a fixed list of allowed tools | don’t-ask, plus allow rules |
| Run in a throwaway container or VM with no prompts at all | bypass |
Auto-edit
Auto-edit is the everyday choice for many people: edits inside your working folders land without a prompt, and you still see every shell command before it runs. Deny and ask rules keep working. Edits to sensitive files still ask, as described under Protected paths.
Plan mode
Plan mode is for thinking before doing. The agent reads, searches and proposes, while anything that could change files or run side effects is refused whatever the rules say.
When the plan is ready, the agent presents it and you decide:
- Approve to leave plan mode and start work. The session moves to auto-edit.
- Keep planning to send feedback and get a revised plan.
With "showClearContextOnPlanAccept": true, approving also offers to clear the conversation and start fresh from the plan alone, which is useful when the exploration filled a lot of context. Plans are saved as files in plansDirectory (by default ~/.syntic/plans).
To start every session in plan mode, set "permissionMode": "plan" in your settings.
Auto mode
Auto mode lets routine development run without prompts and still stops for anything with real consequences. Each call passes through these steps in order:
- Deny rules, plan-mode refusals and ask rules, as in every mode.
- Auto mode’s own rule lists, if any are set (
autoMode.allow,soft_deny,hard_deny). - A quick review by a small model, which judges the call against a short safety policy and any plain-language rules you wrote.
- A fixed checklist of high-impact actions that always asks.
The review fails safe. If the reviewer cannot be reached, takes longer than 20 seconds, or gives an unclear answer, you are asked; in a non-interactive run the call is refused. Read-only calls, edits inside the project and calls an allow pattern names skip the review. You can turn the review off with "autoMode": { "review": false } in your user settings or SYNTIC_AUTO_MODE_REVIEW=0; the checklist still applies.
Browser and computer-control tools are never approved by auto mode on its own. They ask unless an allow rule names them.
How to write auto mode rules, and how organizations set them for everyone, is covered on Configure auto mode.
What auto mode always stops for
These checks are built in. No rule, hook, setting or review result can switch them off:
| Reason shown | Examples |
|---|---|
| Deletes data beyond normal project edits | rm -rf aimed outside the project, or at the project folder itself |
| Changes files outside the project | Writing, moving or changing permissions outside your working folders (temp folders are fine) |
| Touches a credential file | ~/.ssh, ~/.kube, .env, key and certificate files outside the project |
| Runs with administrator rights | sudo, doas, su |
| Changes system security settings or services | Firewall changes, system services, installing a crontab |
| May send secrets off this machine | A network command combined with an environment dump or secret-looking variables |
| Reads or changes a credential store | Keychain, password manager and cloud credential commands |
| Runs a destructive database operation | DROP, TRUNCATE, a DELETE with no condition, database resets |
| Deploys or changes infrastructure | Applying infrastructure plans, kubectl apply against a non-local cluster, production deploys (full list) |
| Publishes a package or release | npm publish, cargo publish, docker push, creating a release |
| Pushes to or changes a remote repository | git push (the prompt names the remote and branch), editing remotes |
| May make a purchase or payment | Commands aimed at payment APIs |
| Cannot be undone | git reset --hard, git clean -f, formatting a disk |
| Changes Syntic’s own permission settings | Edits to permissions, autoMode, sandbox or hooks |
| Runs code it downloads first | `curl … |
The checks read commands the way a shell would, through sh -c, eval, aliases and wrappers. They are broad on purpose: a false alarm costs you one question.
Don’t-ask
Don’t-ask never shows a prompt. A call runs only if an allow rule covers it; everything else is refused, and the agent is told why so it can try another way. Ask rules refuse too, since there is nobody to ask. This suits scripts and pipelines:
syntic -p "run the test suite and summarize failures" \
--permission-mode dontAsk \
--allowed-tools "Read,Grep,Glob,Bash(cargo test:*)"Bypass
Bypass switches the permission prompts off. Deny rules still refuse, the checks no mode skips still ask, and catastrophic commands are still refused. Use it only where a mistake cannot hurt: a disposable container, a scratch VM, a sandboxed CI runner.
| Way in | Notes |
|---|---|
syntic --dangerously-skip-permissions | Starts in bypass for this run. |
syntic --allow-dangerously-skip-permissions | Adds bypass to the Shift+Tab rotation without starting in it. |
--permission-mode bypass | Same as the first flag. |
Turn modes off
Any settings file can switch auto or bypass mode off. Once one file does, no other file can switch it back on:
{ "permissions": { "disableAutoMode": "disable", "disableBypassPermissionsMode": "disable" } }SYNTIC_DISABLE_BYPASS_PERMISSIONS=1 blocks bypass for every run on a machine. If the mode you are in becomes disallowed (for example after a settings file reloads), the session drops to default and tells you. Administrators usually set these in managed settings.
Protected paths
Auto-edit lets edits through without a prompt, but some files change what runs on your machine the next time a shell, git, an editor or a coding tool starts. Edits to these always ask, even in auto-edit:
| Kind | Examples |
|---|---|
| Shell startup files | .bashrc, .zshrc, .profile, .zshenv and similar |
| Version control internals | Anything under .git/, git config files |
| Agent and editor config | .syntic/, .syntic.json, .mcp.json, .vscode/, .idea/, .devcontainer/ |
| Hooks that run on their own | .envrc, .husky/, .githooks/, pre-commit config |
| Credentials | .env files (but not .env.example and other templates), .netrc, .npmrc, .pypirc, .git-credentials, SSH keys, *.pem, *.key, *.p12 and other key stores |
| Credential folders | ~/.ssh, cloud tool credential folders, ~/.gnupg, ~/.kube, ~/.docker, and secret folders under ~/.config |
| Programs that start by themselves | macOS launch agents and daemons, ~/.config/autostart, ~/.config/systemd, Cargo config |
The check also catches disguised spellings of these paths and follows symbolic links, so a link inside the project that points at your shell profile still asks. Worktrees under .syntic/worktrees/ are treated as ordinary source.
Checks no mode skips
A few checks ask in every mode, even bypass, and even when an allow rule matches:
- a shell command that the command-safety check rates as critical;
- a command too long to show you properly in a prompt;
- with
permissions.blockReadsOutsideWorkingDirectorieson, a command that may read outside your working folders.
Catastrophic commands, such as a recursive delete of a system folder, are refused outright.
Non-interactive runs
In a -p run there is nobody to answer a prompt. Anything that would ask is refused instead, and the agent is told why. Pick the mode and rules for a script up front; see Headless runs.
Related pages
- Permission rules: allow, ask and deny patterns.
- Configure auto mode: auto mode rule lists and the review.
- Folder trust: what an untrusted folder cannot do.
- Shell sandbox: an operating-system fence around commands.