Permission modes

A permission mode decides which tool calls run without asking and which need your approval. Workspace trust is separate: it controls whether Mercury loads instructions, hooks and other configuration from the opened folder, and it applies the same way in every permission mode, a bypass mode included.

Permission controls

/permissions: Controls which operations run without asking and which ask first.
Shift+Tab: Cycles the permission modes in the carousel order. A step whose mode is unavailable falls through to the next.
Workspace trust: Interactive boot evaluates trust after onboarding and shows the trust dialog whenever the session's starting folder lacks a covering grant. Permission mode does not change this.
--mode <mode>: Selects the permission posture for a session from the command line. --sovereign runs without permission prompts. In mercury run, --allow-sovereign makes that posture available for a later switch. Interactive sessions include Sovereign unless settings or policy disable it. Permission policy and deny rules still apply.

The carousel order is default, implement, apollo, flow, sovereign, then default again. dontAsk sits outside the carousel and is reached through --mode or the saved posture.

Modes

default: Always available. The ask-first answer at the close of an Apollo Mode interview selects it, and each edit then asks for confirmation.
implement: Allows ordinary writes and edits inside the session's starting folder. Outside that folder, Mercury asks for permission. Sensitive files keep their own checks. Entry is always available, and Apollo Mode's build posture uses it when flow is unavailable.
apollo: Always available. The agent interviews the user, writes the specification and presents it for review before a prototype build. It works in the terminal and in an ACP editor, which answers the interview through form elicitation; mercury run does not run interviews. Externally the mode projects as default and is never a bypass posture.
flow: Runs everything Sovereign runs except five things, which ask: privilege escalation; git that publishes or rewrites history; publishing and deploying; deleting or overwriting a path outside the project, its worktrees, this run's scratch and the temp folders; and your own ask rules. Deny rules still refuse, and reads are free everywhere. Broad allow rules for dangerous actions are set aside while Flow is on.
sovereign: The one bypass mode, available when bypass is available on the context. It is turned on by the Boot Menu's Sovereign mode row as standing consent, by the CLI flag or by the session's own choice, and the boot's permission-posture record states which. While it is on, permission cards are bypassed and every action runs as you; capability gates, explicit deny rules and command safety rules still apply, and the amber line under the Boot Menu's Sovereign mode row warns about the mode. mercury health and /health show it as the Sovereign mode row.
dontAsk: Never asks; what would have asked is refused.

/permissions sets the rules for which calls run and which ask first. In settings, guardrails.mode saves the default mode; guardrails.disableSovereignMode and guardrails.disableFlowMode disable those modes. The permission mode row in /config shows the session's mode and the saved default when they differ. After a crash, a session returns with its own permission mode.

Approvals in Flow

Each ask names which of the five it is in one sentence. A yes answers that call; the card's don't-ask-again row saves a permission rule.

Words you type while a permission card waits show on a row beneath the card; while typed words wait, Enter does nothing, 1 approves the card, the card's own decline row (such as 3) declines it, and Backspace edits the words, with a hint row beneath them naming those keys. Changing the permission mode in a daemon-hosted session (Shift+Tab, /permissions or session/set_mode) re-evaluates its waiting permission asks and releases the ones the new mode allows. In an oculus session started from a screen (Sessions), a permission ask or a question waits for the screen without expiry in every permission mode until you answer it or end the session, and MERCURY_PERMISSION_ASK_EXPIRY_MINUTES does not apply to it. In an unattended headless session, an unanswered permission ask is withdrawn on a clock: after ten minutes in Flow and after three in Sovereign (a crewmate's ask ten minutes in every other mode; MERCURY_PERMISSION_ASK_EXPIRY_MINUTES replaces those clocks and 0 disables them). The call is refused with words the model reads, and work that does not depend on it continues.

The five Flow asks

sudo and any other privilege escalation.
Git that publishes or rewrites history: git push in any form, reset --hard, clean -f, branch -D, filter-branch, and gh pr merge, gh release create and their kin.
Publishing and deploying.
Deleting or overwriting a path outside the project, its worktrees, this run's scratch and the temp folders. Reads are free everywhere.
Your own ask rules. Your deny rules refuse, as in Default.

On Windows, Flow also asks before a path on another machine (\\server\share), because the request can send your Windows sign-in to that server.

With no host to answer, one of the five is refused with the same sentence. Everything else runs.

Enter Apollo Mode

In an interactive session, press Shift+Tab until Apollo Mode is selected. The Apollo Mode instructions join the system prompt at the next turn's prompt build, and only the main agent conducts the interview.

Approve an Apollo Mode prototype build

Review the specification summary in the ApolloReview card and select the build answer that matches the edit permissions you want. Mercury leaves Apollo Mode for the chosen build posture and the agent builds the prototype from the specification in one autonomous run.

The review answers have these effects:

Begin the build: Selects flow when it is available, otherwise implement. Edit consent follows the mode.
Ask before each edit: Selects default. The build runs and each edit asks for confirmation.
Ask more questions: Keeps the session and its drafts in Apollo Mode, and the agent resumes the interview.

A review with blockers is informational: the agent resolves the blockers with the user and reviews again. Esc holds the review as a rejection, and the agent waits for the user's word. Project settings cannot suppress the Sovereign-mode consent dialog through guardrails.sovereignConsentSeen. That setting is honored from the user, local, flag and managed policy sources only.

Workspace trust and permissions · Apollo mode · Using Mercury · Hooks