Shadow Mode and Guardrails

By default Omnodex records what your agents do and flags what looks risky. It never gets in their way. Two more modes let it act on tool calls, and you move between them with one command.

Mode	What happens to a flagged call	Use it for
monitor (default)	Recorded and flagged	Audit and visibility
shadow	Recorded and flagged, plus a note on the finding saying whether Omnodex would have stopped it. The call still runs	Finding out what guardrails would catch, at no cost to your agents
guardrails (Pro)	Stopped, or held for your confirmation, when your settings say so. Everything else runs as usual	Active protection

omnodex enforce shadow
omnodex enforce guardrails
omnodex enforce monitor
omnodex enforce status

Shadow mode is free. Guardrails are part of Omnodex Pro. A first omnodex install offers shadow mode and defaults to yes. Upgrading or reinstalling never changes the mode you already have.

The mode belongs to one Omnodex home. On a Windows machine where agents run both natively and in WSL, each host has its own home and its own mode, so run omnodex enforce on each. See Windows and WSL.

Shadow mode

In shadow mode each finding records what enforcement would have done: what the rule itself suggests, and what your own settings would make of it. In the hosted dashboard, the filter bar gains an Enforcement filter, and Would have blocked narrows everything to those findings. A stat tile counts them.

Run shadow mode for a while before turning guardrails on. The findings it marks are the calls guardrails would have stopped, so you can see whether that would have helped or just got in the way, before you pay for anything.

Guardrails

Guardrails need a Pro or Enterprise plan. omnodex enforce guardrails checks your plan and fetches the guardrails module, a signed and encrypted component that only paid plans can open. Without it, for example after a plan ends, guardrails mode records findings as shadow mode does and stops nothing; omnodex enforce status says why.

In guardrails mode Omnodex checks each tool call against the per-event rules before it runs. When a call matches a rule your settings say to stop, the agent is told why, and what to do instead when the rule has a safer alternative to offer. Most agents then take another route or tell you what happened.

Out of the box, guardrails stops nothing. A rule’s own suggestion only takes effect once the rule ships a safer alternative it can offer the agent. Until then you decide what stops by adding settings (below), so turning guardrails on never starts blocking work you were not expecting.

What each agent does with a held call

Agent	Stop	Hold for confirmation
Claude Code	Call blocked; Claude sees the reason	Claude Code’s own permission prompt, with Omnodex’s reason. In claude -p, where no one can answer, the call is blocked
Codex	Call blocked; Codex sees the reason	Codex cannot prompt from a hook, so the call is blocked and the agent is told to ask you first
Antigravity	Call blocked; the agent sees the reason	Antigravity’s own permission prompt, with Omnodex’s reason, every time
MCP proxy (Cowork Desktop and other proxied clients)	The call never reaches the MCP server; the agent gets an error with the reason	No prompt is available, so the call is stopped and the agent is told to ask you first

Omnodex never approves a call. A call it does not stop goes through your agent’s own permission settings exactly as before.

Coverage follows each agent’s hooks:

• Claude Code: every tool call, built-in tools and MCP tools.
• Codex: shell commands and apply_patch file edits. Codex’s documentation also lists MCP tool calls. Tools that Codex runs remotely, such as web search, are outside its hooks.
• Antigravity: every tool call that reaches its hooks.
• MCP proxy: calls routed through the proxy. Agents that only reach their tools through the proxy, such as Cowork Desktop, are covered this way.

What changes when you turn it on

omnodex enforce guardrails updates the hooks Omnodex installed, and nothing else:

• Claude Code ignores a hook’s answer while the hook runs in the background, so Omnodex’s PreToolUse hook runs in the foreground in this mode, with a 5 second limit after which the call goes ahead.
• Antigravity installs gain a PreToolUse hook, which they otherwise do not have.
• Codex always waits on its hooks, so nothing changes there.

Leaving guardrails puts them back, except in a hooks file that another Omnodex home also uses while that home is in guardrails (see Windows and WSL). Projects you install into later follow the mode you are in. Checking a call adds a few milliseconds, and in guardrails mode the upload to a live dashboard happens after the call instead of before.

When Omnodex cannot check a call

If the rules cannot be loaded, fail, or take too long, the call goes ahead and Omnodex records a risk.enforcement_error event. To stop such calls instead, set on_error to block (see below). The agent is then told that Omnodex could not check the call.

Choosing what stops

Settings live in the enforcement section of omnodex-config.json in your Omnodex home (~/.omnodex by default). A verdict is one of deny (stop the call), confirm (hold it for you) or alert_only (record it and let it run).

{
  "enforcement": {
    "mode": "guardrails",
    "on_error": "allow",
    "severity_defaults": { "CRITICAL": "confirm" },
    "rules": {
      "RULE_SENSITIVE_PATH_READ": "deny",
      "RULE_CWD_BOUNDARY": "alert_only"
    },
    "exceptions": [
      { "rule_id": "RULE_SENSITIVE_PATH_READ", "kind": "allow", "target": { "path": "~/work/app/.env.example" } },
      { "rule_id": "RULE_OUTBOUND_UNKNOWN_IP", "kind": "mute", "target": { "destination": "10.0.4.12" } }
    ],
    "projects": {
      "/home/you/work/scratch": { "rules": { "RULE_SENSITIVE_PATH_READ": "alert_only" } }
    }
  }
}

The most specific setting wins:

1. An exception for the rule and the call’s target: this project’s, then your general ones
2. A verdict for the rule: this project’s, then your general one
3. A verdict for the rule’s severity: this project’s, then your general one
4. The rule’s own suggestion, once the rule has a safer alternative to offer
5. alert_only

Exceptions say a rule never stops a call on a given target. Both kinds keep recording the finding; mute also leaves it out of the shadow-mode filter and counts. A target is one of:

Target	Covers
path	A file, or a folder and everything under it. A leading ~ is your home folder; a relative path is relative to the project
destination	A host and its subdomains
command_prefix	Commands that start with these words

An exception applies only when everything of its kind in the call is covered. Allowing one folder does not allow a call that also reads a file elsewhere. Allowing npm test does not allow npm test && curl ..., or a command with $(...) inside it. Without a target, an exception covers the rule everywhere.

Per-project settings go under projects, keyed by the project’s folder, and apply to sessions inside it.

Shared policy in a repository

A repository can carry its own .omnodex/config.json with an enforcement section, for a team that wants a common policy. It can only make Omnodex stricter: its rules and severity_defaults apply when they stop more than your own settings would, and anything else in it is ignored. A repository is content your agent works on, and it may not be yours, so it can never switch protection off or add exceptions. Those belong in your own omnodex-config.json.

Turning it off

omnodex enforce monitor (or shadow) turns guardrails off. Because that lowers protection, leaving guardrails needs a person at an interactive terminal who types the new mode to confirm, the same as pausing. An agent’s shell tool cannot do it, and Omnodex raises a self-protection alert when an agent edits its configuration.

Pausing recording does not turn guardrails off: calls are still checked, and the pause only keeps them out of the record.

What leaves your machine

On a machine connected to the hosted dashboard, shadow and guardrails modes send per-rule counts of findings that would stop a call: a day, a rule ID, a kind and a number. No paths, commands, hosts or other content. See Data Handling. The note on each finding travels inside your encrypted data like the rest of it.

Next steps

• CLI Commands: the enforce command
• Configuration: every setting
• Risk Library: what each rule looks for