Skip to content
ActiveCLI

Permission modes

How much a session may do without asking first is a closed set of named modes rather than a string, because each one has to survive two translations — into the flag a CLI is spawned with, and back out of what the CLI reports about itself — and a bare string would let the two drift apart silently.

Mode What it allows
plan Plan only: propose, never edit.
ask_before_edit Ask before every edit.
auto_edit Edits go through; other tools still ask.
auto Decide autonomously.
bypass Ask for nothing at all.

Fixed at spawn

Section titled “Fixed at spawn”

--permission-mode is a spawn-time flag with no documented way to change it in place, so a mode change is a respawn. A host asks before sending, and on true stops this session and starts a new one with resume: true:

command.session?.requiresRestartFor(PermissionMode.AUTO_EDIT);  // boolean

Driving it through Command needs none of that: setting permissions and calling send() replaces the process when it has to. See Nothing runs until send().

The CLI announces its mode using the same vocabulary it was spawned with — on system/init at spawn, and again on system/status when it changes the mode itself, which is how an approved plan leaving plan mode becomes observable without inspecting the tool call.

Hyphens and underscores are both accepted

Section titled “Hyphens and underscores are both accepted”

Permission names accept hyphens and underscores both. The canonical spelling uses underscores because that is what the CLI’s transcripts carry, but ask-before-edit is what a caller writing TypeScript reaches for, and refusing one spelling of an unambiguous name helps nobody.

command.setPermissions('ask-before-edit');  // ok
command.setPermissions('ask_before_edit');  // ok, same mode
command.setPermissions('yolo');             // throws: Unknown permission mode: yolo

Why an unknown name throws

Section titled “Why an unknown name throws”

Silently running under a different mode than the caller asked for is the kind of mistake that ends in edits nobody approved, which is why that last line throws.

Where to go next

Section titled “Where to go next”