A duck wearing a helmet

Helmet Duck

Deterministic hooks that block common coding-agent mistakes, in the harness, not in the prompt.

Everything an agent is told is advice, and advice is exactly what an agent skips when it decides it already knows. Helmet Duck is not advice. At each hook event a script, never the model, evaluates a rule, and the harness refuses the action or refuses to let the turn end. Thinking cannot be gated. Its consequences can. It covers the mistakes listed on the What it does page, not every mistake; the risks page says what it misses.

Why it exists

Between June and August 2026 the author spent a large amount of money on coding agents and got no product back. The agents worked from memory instead of reading the tree, appended notes to files they had never opened, committed without running the tests, spawned audits of audits, and asserted every wrong thing with full confidence.

The first version of these hooks went onto his machine on 2026-09-05. The mirror, run on 2026-09-07 over the previous fourteen days of the author's own transcripts, found 353 moments where the machinery caught the agent: 229 failed assertions, 78 gate refusals, 44 syntax errors, 2 denials. Since the hooks went in, 75 of those, 38 of them gate refusals. A catch is a tool result in the agent's own transcript that records one of these; 141 more raised inside test suites are counted apart, because a gate proving itself is not a catch. The number is a dated count, not a rate. Every catch is in a ledger the agent's tools cannot edit.

What a refusal looks like

From a real session. The agent tries to append to a file it never opened; the harness refuses with the gate's fixed words; the agent reads the file; the same append is then allowed.

agent    echo "- verified" >> notes.md
harness  GATE G1: overwrite of /work/notes.md, which was not read this session.
         Read it first (Read tool, or cat/sed -n/grep it), then write.
         Blind edits of existing files are how notes get appended unread.
agent    cat notes.md
agent    echo "- verified" >> notes.md
harness  (allowed: the file was read this session)