Governing Claude Code with the Axiom guard

Claude Code asks before a tool runs. Axiom answers. A blocked call costs zero tokens because nothing was ever sent — the same property drop-in.md claims for the proxy, applied to the agent writing your code.

.claude/hooks/axiom_guard_hook.py     the hook
.claude/settings.json                 wires it to PreToolUse
.axiom/hook-decisions.jsonl           one line per gated call (gitignored)

It is on for this repo already. Nothing else is required to use it locally.

Two layers, because they catch different things

This is the whole design, and it came out of a measurement rather than a guess:

The gate reads prose. It is very good at an injected instruction and blind to shell semantics — rm -rf / states no intent, it simply is one. A hook wired only to the guard would wave through exactly the Bash calls that matter most, while looking like it was protecting you.

So:

1. Mechanics — local, always on, no network. Explicit rules over the tool's own arguments: recursive deletes rooted at /, piping the network into a shell, writing to block devices, force-push, history rewrites, credential reads, world-writable chmod, apparent secret exfiltration.
2. Intent — the Axiom guard, optional. Natural-language fields only (a Task prompt, fetched web content, file content), classified by the same gate the NodeXLoop runtime uses. Bash is deliberately not sent: a shell command classifies INFORM every time and buys only latency.

Configuration

All optional. Layer 1 works with none of it.

export AXIOM_GUARD_URL=https://firewall.orivael.dev

Measured cost

Per tool call, on this machine:

The 76 ms floor is almost entirely Python interpreter startup, and it is paid on every tool call. That is not nothing; it is the honest price of gating locally.

Why "fail closed" is not the default

Claude Code proceeds with the tool call when a hook times out. So "fail closed" cannot be implemented by hanging — a hook that blocks on an unreachable guard fails open after the timeout, silently, which is the worst of both. The hook therefore decides inside its own budget and applies AXIOM_HOOK_ON_ERROR.

Default allow, because layer 1 has already run and still blocks locally; a network blip should not stop your editor. Set deny if an unchecked Task prompt is unacceptable in your environment — but know that it makes the guard's availability a hard dependency of your editor.

The circuit breaker exists for the same reason. Without it, an outage costs the full timeout on every affected call — 2 092 ms against 206 ms. Paying that once is a blip; paying it on each Task for the length of an outage makes the editor feel broken, and the usual response to that is to disable the hook entirely, which loses layer 1 too.

What it deliberately does not do

It never exits 2. Exit 2 blocks unconditionally and cannot be overridden by the person at the keyboard. A policy hook should state a decision, not seize control — every deny here is a permissionDecision you can override.

It never emits "allow". Saying nothing lets the normal permission flow apply. An explicit allow would override the user's own settings, including ones stricter than these rules.

It is not a sandbox. It reads the arguments of a call before it runs. A sufficiently indirect command (bash -c "$(printf ...)", a script written then executed in two steps) is not caught by pattern rules and never will be. This raises the cost of an accident; it is not a containment boundary.

Known gap in the deployed guard

As of 2026-08-27 the deployed firewall.orivael.dev returns VERIFIED / blocked: false for a textbook prompt injection that the repo's own classifier blocks as DECEIVE. The _evaluate fix in axiom_guard_api.py — domain agents then the ORVL-016 gate — is in the repo but not in the running build.

Layer 2 against that host is therefore weaker than layer 2 against a current build. Layer 1 is unaffected. Redeploy the firewall before relying on the intent check, and re-run the three cases in the table above to confirm.

Tests

tests/test_axiom_guard_hook.py — 50 checks, exercising the hook as a subprocess over its real stdin/stdout contract rather than by importing its functions, because the contract with Claude Code is the part that can silently break.

Most of the file is false positives: git push --force-with-lease is not --force, rm -rf node_modules is not rm -rf /, a quoted rm -rf / inside an echo is not a delete, and a doc named credentials-setup.md is not a credential read. A hook that fires on ordinary work gets switched off within a day, and then it catches nothing at all.