Permissions for programs
A program that runs Syntic Code has no one at the keyboard to answer a permission question. This page explains how to decide, before the run starts, what the agent may do, and what happens when it asks for something that was not allowed.
The permission engine is the same one the interactive CLI uses. The full model is on Permission modes and Permission rules.
Questions in a run
When a tool call needs approval and no rule settles it, a non-interactive run (-p, or a stream-json session) refuses the call instead of waiting. The agent is told the call was refused and carries on with another approach.
A program can answer these questions itself. In a stream-json run started with --permission-prompt-tool stdio, each call that needs approval is sent to the program as a can_use_tool control request, and the call waits for the answer: {"behavior":"allow"}, or {"behavior":"deny","message":"..."}. Any other answer, or stdin closing, counts as a denial. --permission-prompt-tool can instead name an MCP tool, such as mcp__approvals__check, which gets the same question and returns the same answer. Deny rules, plan mode and the other checks still run first, so the program is asked only about calls a person would otherwise approve. --permission-prompts none refuses every question without asking.
Set the mode for the run
--permission-mode sets the mode for a single run. The values are the same as in settings files.
--permission-mode | What runs without a question | What a run refuses |
|---|---|---|
default | Read-only tools: reading, searching, listing. | Anything that changes something. |
acceptEdits | Read-only tools and file edits inside your working folders. | Shell commands and other tools, unless an allow rule covers them. |
plan | Read-only tools. | All changes. |
auto | Routine work, after the automatic risk review. | Anything on the auto mode checklist. |
dontAsk | Only what an allow rule covers. | Everything else, quietly. |
bypass | Everything except deny rules. | Nothing, apart from the checks that always ask. |
bypass is also set by --dangerously-skip-permissions. Use it only in throwaway environments such as a disposable container. Deny rules still apply.
syntic -p "fix the failing unit tests" --permission-mode acceptEditsAllow and deny specific tools
Two flags narrow a single run:
| Flag | Effect |
|---|---|
--allowed-tools <rules> | These tools and commands run without asking. |
--disallowed-tools <rules> | These are refused for this run. |
--tools <list> offers only the named built-in tools for the run; --tools "" turns them all off.
Rules use the same pattern syntax as the permissions section of a settings file. A command rule can name a prefix, such as Bash(npm test:*).
syntic -p "fix the failing unit tests" \
--permission-mode acceptEdits \
--allowed-tools "Bash(npm test:*)" \
--disallowed-tools "Bash(git push:*)"How the rules combine
Three rule lists are checked before the mode is consulted:
- deny always wins. No mode, flag or hook can allow a call that a deny rule refuses.
- ask always asks. In a run there is no one to ask, so the call is refused. An ask rule also wins over a matching allow rule.
- allow runs the call without asking.
Put the rules in a settings file, or pass them on the command line for one run. A deny rule from any source is kept, so a program cannot remove one that an administrator has set.
Changed calls are checked again
A PreToolUse hook can rewrite a tool’s input before it runs. When it does, the changed call goes through the whole decision again: deny, ask and allow rules, the mode, and the tool’s own input checks. If the new input is refused, the call does not run.
Untrusted folders
Syntic Code does not trust a project folder until someone accepts it. In a run that starts in an untrusted folder, project settings, hooks, MCP servers and agents are not loaded, and the run prints a note when the folder has project configuration. Trust is set per folder in the interactive CLI. See Folder trust.
Choosing a setup
| Program | Suggested setup |
|---|---|
| A read-only review or report | --permission-mode plan, with --disallowed-tools "Write,Edit,Bash" added to block changes. |
| A fix that should edit and run tests | --permission-mode acceptEdits with --allowed-tools for the test command. |
| A job that must never change files | --permission-mode dontAsk with no allow rules for edits. |
Bypass mode runs everything except deny rules. Do not use it on a machine that holds credentials you would not give the agent directly.
Related pages
- Scripting and CI for every run option.
- Hooks for programs for checks that run around each tool call.
- Secure deployment for locking these choices down across a team.