What happens
Guardrail turns the command, arguments, working directory, paths, environment policy, execution mode, and workflow settings into a normalized contract.
Paths resolve in the current project context and unordered allowlists are sorted before stable JSON hashing. The result is deterministic for the same normalized contract — not a promise that different machines share absolute paths.
Stable contract serializationWhat happens
The execution contract records the exact command, arguments, working directory, readable and writable paths, environment policy, child-process policy, network policy, timeout, and update policy.
When you acknowledge a manifest, you acknowledge those bound fields. A later change becomes drift and must be reviewed again.
Explicit execution boundary
What happens
Guardrail computes risk independently. You may declare a level — but if the engine computes higher, the engine wins. Risk can only escalate.
RED requires strong interactive confirmation. The operator must type APPROVE; normal command arguments cannot self-approve delegated execution.
What happens
On the first interactive guardrail run -- npm test, Guardrail shows the candidate contract and risk assessment. Type APPROVE in a real TTY to continue.
The acknowledged manifest is stored locally. A repeated exact contract can reuse it; changed bound fields require another explicit review.
guardrail approve <request-id> is the compatibility path for a queued delegated MCP approval request, not the normal command-run flow.
Explicit operator acknowledgementWhat happens
On reuse, Guardrail rebuilds the normalized contract and compares it with the acknowledged manifest. An exact contract match can run; a compared contract difference returns Exit 12.
No silent pass-through. No "close enough." In non-interactive/CI mode there is no prompt — drift is a build failure.
Any compared manifest difference is drift. Interactive mode can present the new contract for approval; non-interactive mode returns Exit 12 without prompting.
Fail ClosedExit 12 on drift| Change | Result |
|---|---|
| New flag added | ■ BLOCKED |
| New env var | ■ BLOCKED |
| Binary name changed | ■ BLOCKED |
| New target / host | ■ BLOCKED |
| Risk assessment changed | ▲ REVIEW |
| Mode → shell | ■ BLOCKED |
| Argument removed | ■ DRIFT |
| Exact normalized contract | ✓ ALLOWED |
What happens
Workflows can return structured issues and accept bounded update proposals. Guardrail re-validates every delta and rejects cumulative widening outside the approved contract.
For delegated MCP work, agents start with grant status, then describe or prepare a recipe/template. Unpinned execution needs host form approval or an already approved request ID.
Hosts without elicitation support fail closed. The operator can always rerun explicitly when a genuinely wider contract is intended.
Bounded proposals, fail-closed executionWhat happens
Command and workflow events are written as structured JSONL in .guardrail/audit.jsonl by default.
Each entry contains prev_hash, payload_hash, and entry_hash. guardrail audit verify detects local edits or broken linkage.
Use guardrail audit query for trace, manifest, event, and time filters. The local chain is inspectable evidence, not an externally anchored immutable ledger.
Total Memory and Telemetry