Approval Modes

Every tool call the engine wants to make goes through an approval gate. The approval mode controls how strict that gate is. There are three modes: Default, Auto-edit, and Force.

The active mode is shown in the status bar at all times. See Status Bar Anatomy for how the mode segment and the · FORCE badge render.

The three modes

Default

Every tool call that touches the filesystem, runs a shell command, makes a network request, or performs any other side effect shows an interactive approval card in the transcript. You see what the tool wants to do and choose to allow or deny before the engine proceeds.

This is the mode you use when you want to stay in control of every action. It is also the safe starting point for unfamiliar codebases or tasks where the scope of changes is not yet clear.

Auto-edit

File read and write operations are approved automatically. Shell execution and network requests still show the interactive approval card.

Use Auto-edit when you trust the editing work but still want to gate network and shell activity. It reduces interruptions for tasks that are primarily reading and editing files.

Force

All tool calls are approved without prompting. The engine runs the full agent loop without stopping for any confirmation.

When Force mode is active, the status bar shows · FORCE in warning color after the mode label so the state is never ambiguous at a glance.

Force mode removes all interactive gates

In Force mode the engine can read files, write files, run shell commands, and make network requests without asking. Use it only for tasks and environments where you have reviewed what the agent will do and are comfortable with unsupervised execution. There is no per-call confirmation to catch an unexpected action mid-run.

Cycling modes interactively

In the Workspace, Shift+Tab cycles through the three modes in order:

Default  →  Auto-edit  →  Force  →  Default  →  …

The mode label in the status bar updates immediately on each press. A brief flash in the composer area confirms the transition (approximately 0.5 seconds at the default render rate).

Shift+Tab overrides the global “previous surface” binding while the Workspace has focus, so it cycles modes rather than switching tabs.

You can also switch mode with the /mode slash command, which opens the same cycle interactively.

Setting mode at boot

Config file

Set the default mode for all sessions in your config:

[default]
approval_mode = "auto_edit"   # "default" | "auto_edit" | "force"

The value is read at startup. You can still cycle modes interactively during the session; the config value is the starting point, not a lock.

—force flag

Passing --force at the command line overrides the mode to Force for the entire run and adds the · FORCE badge to the status bar:

wayland-core --force "Refactor all the error types in src/"

--force has two aliases that work identically:

wayland-core --yolo "..."
wayland-core --dangerously-skip-permissions "..."

The flag is read from Cli at main.rs:247-248 and passed into the TUI engine at boot. The badge is rendered by the status bar widget when app.config.force is true (statusbar.rs:196-204).

—auto-approve flag

--auto-approve skips the confirmation prompt for tool calls but is distinct from --force. The mode label in the status bar reflects the configured approval_mode value; --auto-approve does not change it to Force or add the · FORCE badge.

What each mode gates

Action	Default	Auto-edit	Force
File reads	Approved	Auto-approved	Auto-approved
File writes and edits	Approval card	Auto-approved	Auto-approved
Shell execution	Approval card	Approval card	Auto-approved
Network requests	Approval card	Approval card	Auto-approved

“Approval card” means the tool call pauses and shows an interactive card in the transcript. You press y (or a) to allow, n to deny. On multi-card approval queues, A approves all remaining cards and N denies all remaining cards without showing each individually.

Approval scope in Default and Auto-edit

When you approve a tool call in Default or Auto-edit mode, you can choose the scope of that approval:

• Once: allows this single call, then reverts to prompting.
• Always (tool-name scope): allows every future call to the same tool by name for the rest of the session without prompting again.
• Always (prefix scope): allows every future call whose tool name matches a prefix, for broader patterns.

The ToolApprovalManager reaps stale Always entries after 300 seconds of inactivity (TTL reaper). Scope choices are not persisted across sessions; they apply only to the current run.

Relationship between —force and the mode cycle

--force at boot and the interactive mode cycle are independent mechanisms that interact in a defined way:

• --force sets app.config.force = true and adds the · FORCE badge. This flag is immutable for the session.
• The interactive mode cycle (Shift+Tab) changes app.mode among Default, Auto-edit, and Force. This change is visible in the mode label but does not clear the · FORCE badge.
• When --force is active, the mode cycle still works. You can cycle to Default from the status bar’s perspective, but the · FORCE badge remains and the underlying force flag stays set. The effective behavior remains Force regardless of what the mode label shows.

In practice: if you start with --force, the mode cycle is cosmetic for that session. The badge is the authoritative indicator that all gates are open.

Force mode in one-shot and headless runs

--force applies in all three run modes, not just the TUI:

# One-shot
wayland-core --force "Run the test suite and fix any failures"

# Headless JSON-stream
wayland-core --force --json-stream

In headless JSON-stream mode there is no status bar, but the config_changed event the host receives at startup reflects the force state, so a host application can observe the mode.

Next

• TUI Tour
• Status Bar Anatomy
• Plan Mode
• Bash Isolation