Door one — for your engineers
Nuthatch hangs off a coding agent’s own tool-call boundary and evaluates each attempted write with deterministic rules, before the bytes exist on disk. Every evaluation lands as one receipt in a hash-chained ledger: what was attempted, which control matched, who the actor was, what the verdict was. A model never decides a verdict; it only drafts the human-readable explanation.
Three modes, one file
$ cat .nuthatch/mode
shadow measures and emits nothing. teach turns every finding into an approvable prompt carrying the lesson. enforce acts, with a citable reason. The control pack is the evaluator in all three, so a shadow row and an enforce row are the same measurement with only the verdict gated. The default is shadow, and an absent, unreadable, or garbage mode file resolves to shadow.
Twenty controls, all of them asking
The starter pack carries twenty controls — identifiers in a logger, a credential written to a file, a store read that swallows its failure into an empty list, a permission check that fails open, a raw outbound call off the reviewed transport, an unwitnessed bypass. Every one of them starts at “ask.” Not one of them can deny today. A control earns “deny” by demonstrating a low false-positive rate against accumulated evidence — and the tool that reports which controls have earned it refuses to edit the pack, because flipping a control from asking a human to blocking one has to have a human’s name on it. The pack manifest digests every control module and refuses the whole pack rather than load a tampered one. The starter pack is unsigned today, and every packet says so.
Bypass is witnessed, not prevented
Break-glass demands a written reason of at least forty characters, refuses to arm without a chained receipt of its own, and burns the grant before the bypass applies — one grant at a time, under hard caps on how long it lives and how many times it is used. Bypass is possible and we say so. Every bypass emits a coded event, and every break in the chain is enumerated.
$ …install command arrives with the first published release
Door two — for whoever reads the report
The developer tool is the witness. The thing a non-developer holds is the receipt — and anyone can check it.
An attestation packet names the controls that were in force and the signature state of the pack they came from, the receipt totals, whether the chain and its signed tree heads verify, and every break-glass event rendered individually with its named actor and its stated reason. It closes with a methodology section stating its own limits — including that observations are not blocks, and that this is evidence for conformance, never a compliance certification.
A separate verifier, with no dependencies and no network access, re-checks a packet offline from nothing but a public key and one receipt’s inclusion proof — revealing nothing about any other receipt in the log. The ledger is hash-chained and tamper-evident: a break in the chain is detectable and surfaced. It is designed to be third-party-verifiable, which is a property someone else checks rather than a promise you accept. Both the packet and the verifier are built; publication is roadmap, not shipped.
The three questions, told apart
T0 is decidable from the tool call alone — a secret being written, an identifier key in a logger, a bypass flag. A refusal is legitimate here. T1 needs cached repository context on a strict time budget — does that data-model delegate exist, did this change raise a baseline, is the cited commit really an ancestor — and on timeout it degrades to asking, never to passing. T2 is not decidable in real time by anything. Nuthatch does not judge the content; it forces provenance, and it starts an obligation clock routed to a named human.
dose-gate’s epistemic claim is “this constant came from the registry,” not “this constant is correct.”
What a fresh install does
- mode (default)
- shadow — measures, emits nothing
- modes available
- shadow, teach, enforce
- modes that emit a verdict
- teach (max: ask) · enforce (max: deny)
- controls in core-safety
- 20 — every one at ask; none denies today
- pack signature
- none yet — the pack is unsigned
- trust root
- unpinned — and every verifier says so instead of implying otherwise
- verdicts it can emit
- ask, deny — a frozen list
- hard deadline
- 1500 ms, on an unref’d timer — a stalled check cannot hold a tool call open
- break-glass
- reason of 40+ characters required · 15 min default, 240 max · 1 use default, 5 max
- file contents stored
- none — writes reduce to a sha256 digest and a byte length
- third-party packages
- zero
- network access
- none in the engine, asserted by a source scan
This table is the boundary between what you believe you installed and what you actually installed. A governance tool that overstates its own guarantees is the precise failure it sells protection against.
Zero, or eight hundred and ninety-seven
Same repo, same authors, same discipline. raw-fetch was enforced as a chokepoint from day one and its baseline is 0 sites in 0 files. catch-to-empty was caught after the fact by a ratchet, and its baseline is 897 sites across 171 files. phantom-prisma: 34 delegates, 53 sites, 31 files. Every baselined number is a measurement of what it costs to catch something after it lands. A prevent-rung control has a baseline of zero by construction.
Counts as of the committed baselines in scripts/raw-fetch-baseline.json, scripts/catch-to-empty-baseline.json and scripts/phantom-prisma-baseline.json, read 2026-08-08; regenerate before quoting.
What Nuthatch does not do
- It does not make errors impossible, and it does not stop a model from being wrong. It governs the output boundary, not the model’s reasoning.
- It does not judge whether a dose, a threshold, or a citation is right. It can refuse a magic constant that came from nowhere; it cannot tell you the number is correct.
- It does not catch what never reaches a tool call. A file pulled in by reference produces no event, and a write that arrives as a shell command rather than an edit is measured, not caught.
- It does not block bypass. It witnesses bypass, and it enumerates every break in the chain.
- It does not deny anything by default. All twenty starter controls ask.
- It supports one coding agent — Claude Code — today. Other agent transports are roadmap.
- It is not a compliance certification and it does not make anyone compliant. It produces evidence a third party can check — and a human being still has to read it.
- Its published evidence run is a ~25.5-hour window on our own repository — not fourteen days. The fourteen-day corpus is owed, and no fourteen-day figure gets quoted until a fourteen-day ledger produces one.
Roadmap — stated as roadmap
- Public release of the engine, ledger, verifier and starter pack under Apache-2.0.
- Controls promoted from “ask” to “deny” once each earns it on adjudicated evidence.
- Reconciliation as a coverage claim — every committed change showing its witnesses, and anything unwitnessed flagged on the packet.
- Signing for the starter pack, and a pinned trust root.
- Receipts registering as a Charlie Owl evidence source, so one governance file covers both the algorithms that touch patients and the agents that touch the code.