Three separate settings
The permission ceiling in config.json has three independent dimensions, ordered from restrictive to permissive:
| Dimension | Values |
|---|---|
| Approval | ask_every_action, ask_for_risky, never_ask |
| Filesystem | read_only, workspace_write, unrestricted |
| Network | denied, allowed |
When permissions is absent altogether, or there is no configuration file, the ceiling is ask_for_risky, unrestricted, allowed: the agents ask before risky actions and uuldana-cli adds no restriction of its own. When permissions is present, the fields it leaves out mean the strictest value, and the strictest ceiling includes “no network”. No agent’s help lists a flag that enforces that, so a ceiling with "network": "denied" starts none of them. See Configuring agents.
Mapped honestly
The ceiling is what you allow, not what an agent promises. For each agent, uuldana-cli maps the ceiling to flags its own --help lists, and reports honestly what it cannot. Core validation rejects a mapping that is more permissive than requested. When no mode fits inside the ceiling, that entry is not started and uuldana-cli says so. For example, no agent’s help lists a flag that blocks network access, so a ceiling with "network": "denied" skips all of them.
The mapping reads the words of what the help lists. A flag that skips every check means “never ask, no restriction”. A mode flag with named choices is read by the choice: a plan or read-only mode asks about everything and writes nothing, an accept-edits mode asks about risky actions, a default or manual mode asks about everything, and a bypass mode never asks. Sandbox and approval flags with named choices are combined. A choice whose meaning is not clear from its name (for example auto) is left out. A program started with no permission flag is assumed to ask before acting, and uuldana providers marks that as an assumption.
Failover reuses the same ceiling for every run of a session and never raises it. A configuration that becomes stricter after a session began applies to the next run of that session.
Bypass for one run
uuldana --bypass-permissions
uuldana resume --bypass-permissionsThe flag replaces the configured ceiling with “never ask, unrestricted filesystem, network allowed” for that invocation only. The file is not changed. The header shows “PERMISSIONS BYPASSED” for as long as the session runs. Each agent then gets the most permissive flags its help lists. For the four agents tried here, that was the flag that skips every permission check (the one that trusts every tool, for one of them). An agent whose help lists no such flag runs with none, and is only started if its default way of running fits inside the ceiling.
The flag is refused with providers, --version, and --help, which start nothing. resume --bypass-permissions is refused when the saved session has a stricter ceiling, because a ceiling is fixed when a session is created.
Native approvals
In the native terminal interface, approval prompts belong to the provider’s own screen, and you answer them there. Provider-local “allow always” decisions are not transferable to another provider. uuldana-cli never generates an allow decision on your behalf.
What it is not
Permission mapping describes what each agent’s own flags enforce. It is not an operating system sandbox imposed by uuldana-cli, and an approved action in a provider can touch whatever that provider can touch.