What Mergen does not do
A note for skeptical security and platform engineers. Every limit below is real today. If one of them changes, this page changes in the same release.
Mergen sits between an AI agent and the tool calls it makes, and returns PASS, HOLD or BLOCK before the call runs. That is a narrow job. This page is the boundary of it: where the guarantee is weaker than "blocked before it ran," when enforcement is off, and which threats we do not claim to stop.
1. Not every IDE can be blocked before the write
How strong the guarantee is depends on what the IDE lets a hook do.
| Where the agent runs | What Mergen can do |
|---|---|
| Claude Code, Windsurf | True pre-execution block: the tool call never runs |
| Codex CLI | Pre-execution block, but only after you trust the hook inside Codex (/hooks); not yet observed in a live session |
| Cursor shell commands | True pre-execution block |
| Cursor file edits | Detect and revert: the edit lands on disk for a moment, then Mergen restores the file |
| VS Code (any agent) | Detect and revert, same as Cursor edits |
| Your shell, CI | zsh in enforce mode blocks before the command runs; zsh advise mode, bash and fish warn only. CI is covered only for commands run through mergen-server gate-check |
Detect and revert is not blocking. Anything that acts on the file in the moment between the write and the revert (a file watcher, a hot reload, a build that was already running) sees the bad content.
Not covered at all: an agent or tool that does not go through one of
the hooks above, and anything a person runs in a terminal without shell
integration. That includes tools an agent calls through an MCP server
(a database, GitHub, Kubernetes or filesystem server you connected):
the hooks review shell commands and file edits only, so an MCP tool call
runs unreviewed and unrecorded. mergen doctor shows which surfaces on your machine are
actually protected.
2. Enforcement can be off, and we tell you when
- The gate is not running. By default a hook that finds no Mergen
server lets the call run (
MERGEN_GATE_AVAILABILITY_MODE=fail-open). Set it tofail-closedon shared machines, CI, or anywhere an agent should not run unchecked. WithMERGEN_GATE_AUTOSTART=true, Mergen first tries to start the gate. A gate that is running but too slow to answer, or that refuses the call, blocks it: fail-open covers only a gate that is not answering at all. - Internal faults (a malformed rule, an exception during evaluation) fail closed and block.
- Panic bypass. An operator can turn enforcement off for a bounded time. Every call during it is recorded. An agent cannot turn it on.
- Free plan limit. Past 1,000 protected calls in a month on the Free
plan, enforcement pauses: calls are not evaluated at all, including
destructive ones, until the month resets or you upgrade.
MERGEN_FREE_CAP_MODE=protectkeeps full evaluation on regardless.
3. It is not a sandbox, and not a boundary against your own machine
- A command that passes runs with your user's permissions. Mergen decides whether it runs; it does not contain what it does once running.
- The agent runs as you, so it can read and write the same files Mergen
uses. Mergen detects and repairs tampering with its hard safety rules on
every load, records every repair, and holds an agent that reads its
secrets or removes its hooks. That makes tampering visible; it does not
make it impossible. For a real boundary, deploy the managed, root-owned
hook and policy files (
sudo mergen interception deploy claudeorcursor) and keepMERGEN_POLICY_SIGNING_SECRETout of the agent's reach. - A user-level hook file (for example
~/.cursor/hooks.json) can be removed by the agent.mergen doctorreports it when that happens.
4. It judges actions, not prompts or answers
- Mergen does not read the model's prompt or its output. A prompt injection matters to Mergen only when it turns into a tool call, and then the call is judged like any other.
- It does not control what the agent sends to its model provider. Files the agent reads become part of its context; Mergen can hold the read of a credential file, but it is not a data-loss-prevention layer for model traffic.
- It does not review code for correctness. The edit gate looks for a fixed set of risky changes in a diff (new secrets, removed tests or CI checks, weakened auth, sensitive config, and a few more). Everything else in the edit is not judged.
5. Deterministic means it can be wrong in predictable ways
- Shell is parsed, not run. Some values only exist at runtime. Where the gate cannot prove what a command does, it judges what it can prove and leans toward asking a person rather than passing.
- One edit is half a refactor. Moving a test or an auth check looks the same as deleting it when you see one edit at a time. Those detectors ask (HOLD) instead of blocking, and some newer detectors only log until their measured accuracy earns them a stronger setting.
- The benchmark is a regression bar, not a proof. On the published corpus the full gate stopped every attack and none of the benign agent calls, with no open gaps. That corpus is curated. New evasions are added to it when found; it does not cover every input an attacker can invent.
- Holds cost time. A wrong HOLD is friction, not safety. If Mergen
stops something it should not have, run
mergen report fp --last: we fix the detector, not the wording.
6. What Mergen never does
- Machine-learned or statistical signals never block or pass a call on their own. They can only ask a person (HOLD).
- An approval in one repository never authorizes the same command in another.
- Your plan never changes a verdict. Paid plans add delivery and integrations, not safety, with the one exception of the Free limit above.
- Your code, commands and verdicts are evaluated on your machine. No verdict depends on reaching our servers.
The maintainers, October 2026