Skip to content

v1.7 — Provable Hooks

Latest
Latest

Choose a tag to compare

View all tags
@m9751 m9751 released this 07 Jun 18:27
· 1 commit to main since this release
v1.7
bb71798
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's New

v1.7 answers the question v1.6 left open: how do you know your hooks are actually working across runtimes, and what should happen at cold start?

Three new hooks, two new guides, three new incidents.

New hooks

  • examples/hooks/lib/normalize-hook-input.sh — Cross-runtime payload normalization. Hooks written for Claude Code silently bypass on Grok because Grok uses camelCase field names and different tool-name literals. This library normalizes both before your hook logic runs. Source it near the top of any hook that will run on more than one runtime.

  • examples/hooks/startup-gate.sh — SessionStart hook. Checks repo detection, AGENTS.md presence + verification, active plan detection, skills manifest currency, and hook registration gap at every cold start. Writes a drift report to ~/.claude/startup-gate-report.md. Session-lifecycle Phase 1 reads this file. Key lesson: additionalContext is NOT visible to the model on the first turn — always write to a file and read it explicitly.

  • examples/hooks/hook-telemetry-stop.sh — Stop hook. Reads per-hook fire/block breadcrumbs and bulk-INSERTs one row per hook into a configurable telemetry store (AOF_TELEMETRY_URL + AOF_TELEMETRY_KEY env vars). After 2 weeks of deployment you can query which hooks are actually firing.

New guides

  • guides/advanced/silent-failure-discipline.md — Every fail-open hook path must write a tab-separated line to .errors.log. The watchdog (ADR 0012) can only report on what it can see. A full governance audit of 63 hooks (2026-06-07) found ~50 silent fail-opens — the watchdog was effectively blind to all of them. This guide includes the pattern, self-test command, and reason-slug vocabulary.

  • guides/advanced/agents-md-standard.md — Three-level repo governance contract: Level 1 (identity only), Level 2 (identity + routing table), Level 3 (identity + routing + procedures + ADR register). The startup gate checks for AGENTS.md presence; this guide explains what to put in it.

What's deferred to v1.8

  • FORGET mechanism (missing leg of memory integrity — READ + WRITE are built, FORGET is not)
  • distill-memory.py regex fix (silently no-op'ing since ship)
  • AOF self-eval Phase 1 dashboard (harness on main, needs telemetry columns migration)

Upgrading from v1.6

  1. Copy examples/hooks/startup-gate.sh to your hooks directory; register under SessionStart in settings.json
  2. Source lib/normalize-hook-input.sh in any hook that checks tool_name
  3. Set AOF_TELEMETRY_URL + AOF_TELEMETRY_KEY and copy hook-telemetry-stop.sh to enable session telemetry
  4. Run the silent-failure self-test on each of your hooks (see guides/advanced/silent-failure-discipline.md)
  5. Add AGENTS.md to any repo you work in regularly (Level 1 takes 2 minutes)
Assets 2
Loading