Mercury CLI
Documentation

Trust and health

Workspace trust and permissions

Workspace configuration can ask Mercury to run things: hooks, helper commands and server configurations live in the folder being opened. Workspace trust is the gate in front of all of it. Until you grant trust for the directory, nothing a workspace configuration file asked for gets to execute. Session permission modes govern tool execution separately from that folder-level grant.

Trust grants

  • Record: A trust grant is a per-directory record persisted in the project records of the global configuration, keyed by normalized path. A grant on a directory covers every descendant.
  • Repository: Inside a repository, the persisted grant root is the project-config path, the git root when one exists, so trusting a repository root covers its subfolders and worktrees without extra records.
  • Home directory: Accepting there keeps the grant in session memory only, because persisting a grant on the home directory would trust everything, forever.
  • Within a session: Trust moves from absent to granted, never the reverse. A mid-session acceptance is picked up immediately.

Interactive boot evaluates trust after onboarding and shows the trust dialog whenever the working directory is not covered by a grant. The permission mode does not change this: a bypass mode affects tool execution, not workspace trust.

Grant trust at boot

To grant trust at boot, follow these steps:

  1. Run mercury in the folder.
  2. Read the trust dialog, which names the directory, asks whether it is a folder you created or trust, and states that Mercury will read, edit and run the files there.
  3. Accept the dialog.

Mercury records the grant, session-only in the home directory and persisted everywhere else, and the workspace configuration can now execute.

Declining exits Mercury. When the directory sits inside a repository, the dialog also states that the grant will cover the whole repository.

Grant trust to a folder directly

To grant trust to a folder directly, follow these steps:

  1. Enter /realms add <path> with the folder's path.

Mercury grants trust to that folder through the /realms surface, which manages trusted project folders.

Before trust is granted

Until trust is granted in an interactive session:

  • Hooks: No hook runs. Every hook execution, for tool events, session events and extension hooks, asks the trust gate first.
  • File suggestions: A configured fileSuggestion command is skipped and the suggestion list stays empty.
  • Project credential helpers: An apiKeyHelper configured in project or project-local settings is declined, and an MCP server headersHelper from project or local scope is not executed.
  • Workspace reads: The instruction-file scan warm-up and the system-context prefetch wait for the verdict.

Headless and SDK sessions have no trust dialog. Trust is implicit in having been embedded, so the hook gate stays open there and project-scope helpers run.

Managed policy

Managed policy settings tighten the hook surface beyond the trust gate.

  • disableAllHooks: In policy settings, disables every hook, managed hooks included.
  • allowManagedHooksOnly: Restricts execution to the hooks the policy settings define. Under managed-only, the file-suggestion command likewise runs only from policy settings.

The same managed-only posture takes effect when non-managed settings disable all hooks while policy settings do not.

  • skipSovereignConsentPrompt: Honoured from the user, local, flag and policy settings sources. The project source is excluded, so a hostile repository cannot pre-accept the Sovereign-mode consent dialog.
  • Permission-posture record: The boot decision writes one record into the project configuration: whether Sovereign mode, the one bypass, is armed; what armed it; whether the consent dialog was shown or suppressed; and whether workspace trust was accepted.
  • Health report: mercury doctor and /health show the record as the Sovereign mode row.
  • Computer access: The Boot Menu's Access type row follows Sovereign mode when unset, full with it on and asks with it off, and a saved value wins either way.

THEMIS

THEMIS is Mercury's deterministic trust machinery: an attack-shape blocklist at the universal tool-execution gate, tamper-evident audit chains, and an HMAC-stamped configuration lockfile with drift detection at boot. Every check is deterministic, and it is on by default.

  • MERCURY_THEMIS=enforce: The default. A blocklist hit is refused at the gate with a typed teaching message, never a prompt.
  • MERCURY_THEMIS=warn: Every signal is audited and surfaced, and nothing is denied.
  • MERCURY_THEMIS=off or 0: Explicit opt-out; no checks run.

An unset or unrecognized value resolves to enforce. The Boot Menu's Run discipline (THEMIS) row cycles the saved level, and /health carries the live row. The blocklist is checked at the one gate every tool execution passes, in every permission mode including the bypass, and it can only add a refusal: the normal permission decision still applies to everything it does not flag. An internal failure degrades to proceed. The checks inspect literal command text and do not defeat an adversary with shell access. mercury themis lock enrols the trust-relevant configuration files, mercury themis verify is the read-only sweep, and mercury themis approve re-stamps the baselines after review.

Permission modes, Hooks, Computer use, Apollo mode, Health check