warrant-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code working in this repository. Written in the same spirit as the sibling warrant repo's CLAUDE.md: decisions recorded once so the next session does not re-derive them — or quietly undo them.

Product

warrant-mcp — a policy firewall for agent tool calls. A human writes policy in plain English; Claude compiles it once, off stage into numbered clauses backed by structured rules; deterministic code checks every intended action and refuses what the policy does not allow, citing the governing clause; a Claude Code PreToolUse hook makes that refusal a hard block.

Claude compiles policy. Deterministic code decides. The hook makes a DENY mean the action does not happen.

This is a skeleton by design: two verdicts (ALLOW / DENY), three action kinds, one MCP tool. No payments, no ESCALATE, no UI, no accounts.

Relationship to the warrant repo

C:\Push-to-Prod-2026\warrant is the proven deterministic authorization engine for agentic commerce. It is reference only: read it to understand the model (type-level guarantee, cached replay, clause citation, fail closed). It has never been modified by this project and must not be — verify with git status there, and with its own invariant git diff submission..HEAD -- src/.

What was reused: the thinking. What was deliberately diverged:

	warrant	warrant-mcp	why
compile cache	gitignored	committed	the reviewed cache is the enforceable artifact; a fresh clone must enforce without an API key
compile failure	labelled stub fallback	no fallback, fail loud	a recording must survive an outage; a made-up enforcement policy is worse than none
verdicts	ALLOW / ESCALATE / DENY	ALLOW / DENY only	two values are what make the hook a hard veto

Architecture

• Toolchain — TypeScript strict, no build step for development (--experimental-strip-types, Node ≥ 22.6). erasableSyntaxOnly is load-bearing: source must stay strippable.
• The published package is different, and has to be. Node refuses to strip types under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so an installed copy would not run at all. prepack emits dist/ via tsconfig.build.json and the tarball ships that. Because erasableSyntaxOnly is on, the emit is pure type erasure — there is no transform that could change a verdict. bin/warrant-mcp.mjs runs dist/ when it exists and src/ when it does not, so a checkout and an install behave identically.
• src/engine/ — pure evaluation. No clock, no I/O, no network, no process spawning. Everything arrives as a parameter.
• src/compiler/ — the only place the Anthropic SDK is imported. The server and the hook never import it.
• src/hook/ — pretooluse.ts (the stdin/stdout boundary) plus a pure adapter.ts that maps Claude Code tool calls onto action kinds.
• src/server/ — MCP stdio server (main.ts), pure handler.ts, presentation in present.ts.
• src/record/ — the authorization record. Append-only by convention, not in fact: the only writer appends and nothing enforces it, there is no hash, chain or signature, and anyone who can reach the file can rewrite it. Do not describe it as an audit trail anywhere — README and SECURITY-SURFACE.md §4 both spell out the gap, and they are the wording to match. types.ts is pure (parsing, the policy fingerprint); store.ts is the only writer; observe.ts is what the two boundaries call. Never imported by the engine, handler, hook adapter or presentation — see invariant 6.
• src/report/ — warrant-mcp report, pure: model.ts aggregates, redact.ts is screen safety both ways (rewrite what is private, scan for what is secret), client.ts holds the page's CSS and script as strings, html.ts renders. No clock, no filesystem; src/cli/report.ts is the boundary.
• src/authoring/ — review-time only: rules→English, behaviour-diff corpus, unmapped guidance, CLI phrase parsing. Never imported by the engine, handler or hook.
• src/cli/ — system boundaries: the only files that read the clock, the environment, or spawn anything.
• src/config/ — where things live and how warrant merges into files it does not own. settings.ts is pure JSON merging, so the promise that a user's settings survive is testable without touching a disk.