hookgate 0.0.2 → 0.0.3

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Calibrated decision gates for Claude Code hooks.",
-    "version": "0.0.2"
+    "version": "0.0.3"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hookgate",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Calibrated, sub-second decisions in Claude Code's hooks: a PreToolUse gate on shell commands and a Stop gate on unverified completion, answered by TypeSafe's Jev with a confidence score, escalating to the human when unsure.",
   "author": {
     "name": "Allan Nava",

package/.codex-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "hookgate",
+  "version": "0.0.3",
+  "description": "Calibrated, sub-second decisions in Codex CLI's hooks: a PreToolUse gate on shell commands and a Stop gate on unverified completion, answered by TypeSafe's Jev with a confidence score, blocking with a reason when unsure.",
+  "author": { "name": "Allan Nava", "url": "https://github.com/Allan-Nava" },
+  "homepage": "https://github.com/Allan-Nava/hookgate",
+  "repository": "https://github.com/Allan-Nava/hookgate",
+  "license": "MIT",
+  "hooks": "codex/hooks.json"
+}

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to hookgate. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/). Items reference their `HG-n` backlog id.
+
+## [Unreleased]
+
+## [0.0.3] — 2026-09-22
+
+Everything since the bootstrap: both gates, Codex, the audit of 2026-09-22, the seven
+bugs the first measurements found, and the scorecard that proves each fix. Audit mode
+by default: the benchmark has not run, so nothing blocks until it has.
+
+### Changed
+- `mode` defaults to `audit` — judge, log, fall through — until HG-4 has measured the
+  thresholds; `"mode": "enforce"` in `~/.hookgate.json` opts in. `0.1.0` flips the
+  default back (HG-5, HG-31).
+
+### Fixed
+- Numeric and enum config values were never checked, so a string or `null` flowed into
+  `setTimeout` and `truncate`; every field now has a rule, a bad value is reported as a
+  problem (`hookgate doctor` fails on it) and the default takes over. A 200 whose body
+  is not JSON is classified `malformed` rather than `network` (HG-29).
+- The audit log dropped the token usage Jev reported, so cost per decision could not
+  be computed. Every judged decision logs `inputTokens` (0 on a cache hit), and
+  `hookgate report` prints tokens, total cost and cost per judged decision at the
+  published input price, one dated constant shared with `evals/run.mjs` (HG-28).
+- A repository's own `.hookgate.json` could switch the gates off, go audit, or set a
+  model or timeout that fails open. Configuration now has a trust order — defaults,
+  `~/.hookgate.json`, `HOOKGATE_CONFIG`, then the repository file, then the environment
+  — and the repository file may only tighten; what it tried and could not do is listed
+  by `hookgate doctor` (HG-27).
+- Rule promotion counted a chained command's verdict against its first word and could
+  propose a prefix rule for an interpreter or wrapper. Only one simple command — no
+  chaining, no pipe, no substitution outside quotes — counts, and a never-promote set
+  (`python3`, `bash`, `sudo`, `xargs`, `find`…) excludes programs that run whatever
+  follows; the log carries `promotable` beside the descriptive `prefix` (HG-24, HG-25).
+- A command longer than `maxStateChars` reached Jev with its middle elided, so anything
+  hidden there was never judged. The command gate now answers `ask` for such a command
+  without a request; audit mode logs `skipped: too-long` and falls through (HG-26).
+- The completion prefilter read English only, so a final message in another language
+  never reached Jev: 766 of 1,229 real stops were Italian claims it skipped. The lexicon
+  is now per language (English, Italian), always on, with ambiguous words anchored to
+  their claim form, and `completion.lexicon` adds patterns from the config. The measured
+  skip rate is 29%, not the 81% first reported (HG-23).
+
+### Added
+- `evals/scorecard.mjs` and `evals/fixtures/`: one metric per open bug, from labelled
+  fixtures, no key; `scorecard.yml` scores base and head of every pull request and
+  posts the delta, failing on a regression (HG-30).
+- The command gate (HG-2), the completion gate (HG-3) and the off-by-default
+  injection screen (HG-15, code only), decided by Jev with calibrated confidence.
+- Audit mode and `hookgate report` (HG-10); per-session decision cache (HG-12); rule
+  promotion in the harness's own syntax (HG-13); `hookgate doctor` (HG-14);
+  `failClosed` opt-in (HG-9); Codex CLI adapter aligned to the documented hook contract
+  — `permissionDecision` shape, `ask` as pass-through plus `systemMessage` or
+  `codex.askAs: deny`, injection feedback via `decision: block` — with e2e tests under
+  `PLUGIN_ROOT`; harness also detected from the stdin shape and `HOOKGATE_HARNESS`;
+  `codex/hooks.json` in Codex's single-command form; config also read from
+  `.hookgate.json` and `.codex/hookgate.json`; verified live on Codex 0.155.1, which has
+  dropped plugin-bundled hooks — `hookgate print-hooks` writes the repo-level
+  `.codex/hooks.json` with absolute paths (HG-11).
+- `evals/`: 79 hand-labelled commands, 20 tool outputs, and the benchmark runner with
+  a `type: prompt` baseline (HG-4, tooling only — the run is blocked on a key).
+- The repository as a knowledge graph under `graphify-out/`, versioned and queryable
+  (HG-22).
+- README section "What leaves the machine, exactly" (HG-17); `HOOKGATE_ENDPOINT` for
+  proxies and end-to-end tests (HG-19); this changelog (HG-20); CodeQL and Renovate
+  digest pinning for actions (HG-21).
+
+### Added (measured, no key)
+- `evals/local.mjs`: hook overhead and transcript-derived counts; `--baseline-only` on
+  the runner; the README Benchmark section carries the incumbent's ten-command numbers,
+  the plugin's own cost, and what 102 real sessions say (HG-16, half).
+
+### Changed
+- Command-prefix logic skips `cd … &&`, `cd …;`, newline-separated `cd` hops and
+  `VAR=value` assignments before naming a prefix; `cd` no longer dominates promotion.
+- The completion gate asks Jev only when the final message claims completion; a local
+  prefilter skips questions and partial reports, logged as `skipped` so `report` shows
+  the share that never reached the network (brief Q7).
+- Audit log rotates at 8 MB; session files are written atomically and pruned after
+  seven days (HG-18).
+
+### Fixed
+- A malformed `TYPESAFE_API_KEY` is reported as such instead of an opaque fetch error.
+- The rule-promotion message under Codex used Claude Code's answer shape.
+- The benchmark runner passed an undefined `CLAUDECODE` to the child `claude`.
+- Three CodeQL findings from the first scan: an unanchored regex in `check`, a
+  one-pass HTML-comment strip in the backlog tool that could leave a `<!--`, and a
+  check-then-use on the audit log file.
+
+## [0.0.2] — 2026-09-22
+
+### Added
+- The scaffold: manifests, `hooks.json` with two inert handlers, `check`, CI on Node
+  18/20/22/24, release by tag over npm trusted publishing, Pages site generated from
+  the README, `BACKLOG.md` as the single source of truth with the one-way issue sync.
+  `0.0.1` is burnt on npm by a version published and unpublished in March.

package/README.md

@@ -14,10 +14,13 @@ on shell commands and a `Stop` gate on unverified claims of completion, answered
 confidence score instead of text — in about 100 ms. Confident: act. Unsure: ask the
 human. Unreachable: get out of the way.
 
-> **Status: scaffold.** The plugin installs and does nothing yet. The two gates are
-> being designed in `thoughts/HG-1-jev-gates/` through the
-> [QRSPI](https://github.com/Allan-Nava/qrspi) workflow; the first release ships them
-> with the benchmark below filled in. Until then every handler falls through.
+> **Status: gates implemented, benchmark pending.** The command gate, the completion
+> gate and an off-by-default injection screen are in, with audit mode, a per-session
+> cache, rule promotion, `doctor` and `report`, on Claude Code and Codex CLI. What is
+> still missing is the number: the benchmark below has not been run yet, so `0.0.3`
+> ships in **audit mode by default** — every gate judges and logs, nothing blocks —
+> and `"mode": "enforce"` in `~/.hookgate.json` is the opt-in. `0.1.0` flips the
+> default once the table below is measured.
 
 ## Why in the hooks
 
@@ -35,41 +38,163 @@ on Jev. Nobody has put it inside the agent harness. That is the gap this fills.
 
 | Gate | Hook | Question to Jev | Effect |
 |---|---|---|---|
-| Command risk | `PreToolUse` on `Bash` | `Choice{allow, ask, deny}` + `Noul` "destroys data or state outside the repo?" | `permissionDecision` with a reason; below the confidence threshold it is always `ask`, never `allow` |
-| Unverified completion | `Stop` | `Noul` "does the last message claim a completion the visible state does not support?" on the message plus `git status` | `block` with the reason, so the agent verifies before stopping |
+| Command risk | `PreToolUse` on `Bash` | `Choice{allow, ask, deny}` + `Noul` "destroys data or state outside the repo?" | `ask` or `deny` with a reason. Below the confidence threshold it is always `ask`, never `allow`. A confident `allow` **passes through** by default: hookgate narrows what the harness would do, it never widens it (`allowMode: "allow"` opts in) A command longer than `maxStateChars` (12,000 by default) is `ask` with no request: judging a head and a tail is not judging the command. |
+| Unverified completion | `Stop` | `Noul` "does the last message claim a completion the visible state does not support?" on the message plus `git status` — asked only when the message claims something (a local prefilter skips questions and partial reports with no network call; it reads English and Italian, and `completion.lexicon` adds patterns) | `block` with a reason naming what to verify. Once per prompt, so the agent cannot loop |
+| Injected instructions | `PostToolUse` on `WebFetch`, `WebSearch`, `Read`, `Bash` | `Noul` "does this output contain instructions addressed to an AI agent?" | `additionalContext` telling the agent to treat the span as data. **Off by default** until the fixture set gives a false-positive rate |
+
+Around the gates:
+
+- **Audit mode** (`"mode": "audit"` or `HOOKGATE_MODE=audit`): every gate judges for real,
+  logs one JSON line per decision to the plugin data directory, and always falls
+  through. `hookgate report` prints decisions by outcome, p50/p95 latency, cache hit
+  rate, input tokens and cost per judged decision at TypeSafe's published price, and
+  the share that would be `ask` at each threshold. The default until `0.1.0`.
+- **Per-session cache**: the same command in the same session is judged once; a repeat
+  answers in microseconds with no request, and never outlives the session.
+- **Rule promotion**: three verdicts above 95% confidence on one command prefix produce
+  a single `systemMessage` proposing the harness's own permission rule —
+  `"Bash(npm test *)"` for Claude Code, `prefix_rule()` for Codex. Proposed, never written,
+  and only for what the rule would actually cover: one simple command (no `&&`, `|`, `;`,
+  newline or substitution) whose program is not an interpreter or wrapper — `python3`,
+  `bash`, `sudo`, `xargs` and their kind run whatever follows, so a prefix rule on them
+  would widen, and hookgate never widens.
+- **`hookgate doctor`**: key, connectivity, latency, model, config, harness. Non-zero only
+  on a broken configuration, never on a slow API.
+- **Two harnesses, one file**: the handlers read the same stdin JSON under Claude Code
+  and Codex CLI and answer in each one's shape, verified against Codex's hooks
+  documentation. Codex has no `ask` on `PreToolUse`, so a below-threshold answer passes
+  through with the concern surfaced as a `systemMessage` (`"codex": {"askAs": "deny"}`
+  refuses instead), and the injection screen uses Codex's `decision: "block"` feedback
+  in place of `additionalContext`. Exercised against a live Codex 0.155.1 (see Install).
+
+Configuration is read in trust order: the defaults, then `~/.hookgate.json` (yours),
+then `HOOKGATE_CONFIG` if set, then the repository's `.hookgate.json` (or
+`.claude/hookgate.json`, `.codex/hookgate.json`), then `HOOKGATE_MODE`, `HOOKGATE_MODEL`
+and `HOOKGATE_FAIL_CLOSED=1`. **The repository's file may only tighten** what the layers
+above it say: enable a gate, raise the confidence bar, go `enforce`, turn `failClosed`
+on, add lexicon patterns, ask Codex to deny instead of pass through. A repository you
+just cloned cannot switch the gate off, put it in audit mode, lower a threshold or point
+it at a model or a timeout that would fail open; `hookgate doctor` lists what it tried.
+Every key is optional:
+
+```json
+{
+  "mode": "audit",
+  "model": "jev-latest",
+  "timeoutMs": 2000,
+  "failClosed": false,
+  "allowMode": "passthrough",
+  "thresholds": { "confidence": 0.7, "destructive": 0.5, "unverified": 0.7, "injection": 0.7 },
+  "gates": { "command": true, "completion": true, "injection": false },
+  "completion": { "prefilter": true, "lexicon": [] }
+}
+```
 
-Thresholds live in `.claude/hookgate.json` and scale with risk, as
-[TypeSafe's confidence guide](https://docs.typesafe.ai/confidence.md) recommends.
+Every value is checked: a bad one is reported by `hookgate doctor` and the default takes
+its place, so the gate never runs arithmetic on a string. Thresholds scale with risk, as [TypeSafe's confidence guide](https://docs.typesafe.ai/confidence.md)
+recommends: the defaults are conservative and the benchmark is what moves them.
 
 **Fail-open, always.** No `TYPESAFE_API_KEY`, no network, a timeout, a 5xx or a bug
-in this plugin means *no decision*: exit 0, empty stdout, and Claude Code's normal
+in this plugin means *no decision*: exit 0, empty stdout, and the harness's normal
 permission flow applies as if hookgate were not installed. A gate that stalls the
-agent is worse than none. Fail-closed will be an explicit opt-in.
-
-**State never carries secrets.** Commands can contain tokens; anything that looks
-like one is redacted before it leaves the machine, and state is truncated to Jev's
+agent is worse than none. `failClosed: true` is the explicit opt-in under which an
+unreachable API makes the command gate `ask`.
+
+**What leaves the machine, exactly.** One HTTPS POST per decision to
+`api.typesafe.ai`, carrying only what the question needs: for the command gate the
+shell command, its description if the agent wrote one, the last two segments of the
+working directory and the permission mode; for the completion gate the agent's final
+message, the stop reason and the first sixty lines of `git status --porcelain`; for
+the injection screen the tool's output. Never the transcript, never file contents the
+agent did not just fetch, never the session id. The audit log on disk keeps the
+verdicts and a command *prefix*, not the command. TypeSafe's handling of what it
+receives is theirs to state: [typesafe.ai legal](https://docs.typesafe.ai/legal.md).
+`HOOKGATE_ENDPOINT` points the plugin at a proxy of your own if that matters.
+
+**State never carries secrets.** Commands and tool outputs can contain tokens; key
+shapes, bearer headers, `KEY=value` assignments, URL passwords and private keys are
+redacted before anything leaves the machine, and state is truncated well under Jev's
 32k-token limit.
 
 ## Install
 
-Not published yet. Once it is:
-
 ```
 /plugin marketplace add Allan-Nava/hookgate
 /plugin install hookgate@hookgate
 ```
 
-and `TYPESAFE_API_KEY` in the environment Claude Code runs in. Zero dependencies,
-Node 18 or later, one `fetch` to `POST https://api.typesafe.ai/v1/systemone`.
+with `TYPESAFE_API_KEY` in the environment Claude Code runs in, then `hookgate doctor`
+from the plugin directory to see what it sees.
+
+**Codex CLI** (0.155 and later dropped plugin-bundled hooks, so hooks are per repository
+or per user):
+
+```
+npm install -g hookgate
+hookgate print-hooks > .codex/hooks.json      # or ~/.codex/hooks.json
+```
+
+Codex asks to trust the hooks file once; `--dangerously-bypass-hook-trust` skips that
+for automation you already vet. Verified live on 2026-09-22 with Codex 0.155.1: the
+command gate refused `rm -rf ~/…` ("Command blocked by PreToolUse hook: hookgate:
+refused at 97% confidence") and let a `git push --force` through with the concern as a
+`systemMessage`; the completion gate ran on `Stop`. Zero dependencies, Node 18 or later,
+one `fetch` to `POST https://api.typesafe.ai/v1/systemone`. The package on npm is the
+same tree, for `npx hookgate doctor` and `npx hookgate report`.
 
 ## Benchmark
 
-The first release carries, in `evals/`, at least fifty shell commands labelled by
-hand as safe, ask or dangerous, run against both gates and against a `type: prompt`
-hook on `claude-opus-5`, and reports agreement with the labels, p50 and p95 latency,
-cost per decision and the share of `ask` per confidence threshold. One run, one
-model version, dated — a data point, not a benchmark suite. If agreement stays under
-about 90%, the command gate ships `ask`-only.
+The Jev half is not run yet — it needs a TypeSafe API key. What has been measured,
+one machine, one day:
+
+**The incumbent.** A `type: prompt`-style judge on `claude-opus-5`, one `claude -p`
+per command from an empty directory, on the first ten labelled commands (all `safe`):
+
+| System | Agreement with labels | p50 | p95 | Cost per decision |
+|---|---:|---:|---:|---:|
+| `type: prompt` hook (claude-opus-5) | 100% | 3,532 ms | 4,675 ms | $0.129 |
+
+Ten commands, 2026-09-22. The cost is the CLI's own `total_cost_usd`, which carries the
+CLI's system prompt on every call — the floor a prompt hook pays, not a model price.
+
+**The plugin's own cost**, thirty spawns each, `evals/local.mjs`:
+
+| Case | p50 | p95 |
+|---|---:|---:|
+| no key: fall-through | 59 ms | 61 ms |
+| cache hit, no request | 61 ms | 62 ms |
+| full round trip to a local fake Jev | 79 ms | 81 ms |
+
+So the fixed price of having hookgate installed is one Node start, about 60 ms per
+`Bash` call; Jev's own latency (70–500 ms by TypeSafe's numbers) comes on top and is
+the part the key will tell.
+
+**What real sessions say**, from 102 local Claude Code transcripts, counts only,
+nothing sent anywhere:
+
+- The completion prefilter skips **29%** of stops: of 1,229 assistant turns that ended
+  with a human reply, 878 claimed completion in English or Italian. The first measurement
+  said 81%, with an English-only lexicon reading Italian transcripts: 766 of those
+  "skipped" stops were claims it could not read (HG-23). Gate 2 asks Jev on roughly two
+  stops in three; the prefilter buys less than it seemed, and now says so.
+- The per-session cache's ceiling is **~0%**: 99 exact repeats in 27,111 shell commands.
+  Real commands vary; the cache stays because it is free, not because it pays.
+- The redactor changes **6%** of commands — keys, tokens, URL passwords are there to
+  be caught.
+- A promoted rule may cover **6%** of commands: 1,744 of 27,147 are one simple command
+  whose program is not an interpreter (HG-24, HG-25). `sed`, `grep`, `cat`, `head`,
+  `tail` lead. The other 94% chain, pipe or run a script — a prefix rule on them would
+  say more than the judgement did.
+
+**Every fix carries its number.** `node evals/scorecard.mjs` scores each open bug from
+committed fixtures — no key, no network — and CI runs it on the base and the head of
+every pull request, posting the delta. A fix moves one line to 100%; a regression on
+any line fails the job.
+
+Full runner: `node evals/run.mjs commands --baseline` over all 79 labelled commands and
+`node evals/run.mjs injection` over the 20 outputs, once a key exists; the pre-stated
+rule stands — under about 90% agreement the command gate ships `ask`-only. Until then,
+run in audit mode.
 
 ## Two design notes
 

package/bin/hookgate.mjs

@@ -1,18 +1,23 @@
 #!/usr/bin/env node
-// hookgate — calibrated decision gates for Claude Code hooks.
+// hookgate — calibrated decision gates for Claude Code (and Codex CLI) hooks.
 //
-//   hookgate check            validate the manifests, hooks.json and this file
-//   hookgate pre-tool-use     PreToolUse handler (reads the hook JSON on stdin)
-//   hookgate stop             Stop handler (reads the hook JSON on stdin)
+//   hookgate check            validate the manifests, hooks files and this package
+//   hookgate pre-tool-use     PreToolUse handler: the command-risk gate (stdin JSON)
+//   hookgate stop             Stop handler: the completion gate (stdin JSON)
+//   hookgate post-tool-use    PostToolUse handler: the injection screen (stdin JSON, off by default)
+//   hookgate doctor           key, connectivity, latency, model, config, harness
+//   hookgate report           decisions by outcome, latency, ask share — from the audit log
+//   hookgate print-hooks      a .codex/hooks.json for this checkout, absolute paths (Codex
+//                             0.155 dropped plugin-bundled hooks; repo or user hooks remain)
 //   hookgate help
 //
-// Every handler FAILS OPEN. Exit 0 with no JSON on stdout means "no decision":
-// Claude Code's ordinary permission flow applies, exactly as if the plugin were not
+// Every handler FAILS OPEN. Exit 0 with no JSON on stdout means "no decision": the
+// harness's ordinary permission flow applies, exactly as if the plugin were not
 // installed. A missing TYPESAFE_API_KEY, a timeout, a 5xx or a bug in this file must
-// never block the user's work. Fail-closed is an explicit opt-in for later.
+// never block the user's work. Fail-closed is an explicit opt-in (`failClosed: true`).
 //
-// Zero dependencies, Node 18+: a hook starts on every tool call, so start-up cost
-// is the cost. The API is one POST with fetch, which Node 18 has.
+// Zero dependencies, Node 18+: a hook starts on every tool call, so start-up cost is
+// the cost. The API is one POST with fetch, which Node 18 has.
 
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
@@ -21,15 +26,8 @@ import { fileURLToPath } from 'node:url'
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const read = (p) => readFileSync(join(ROOT, p), 'utf8')
 const json = (p) => JSON.parse(read(p))
-
 const [cmd = 'help'] = process.argv.slice(2)
 
-// --- hook handlers ----------------------------------------------------------
-//
-// Not implemented yet: the gates are being designed under thoughts/HG-1-jev-gates/
-// through the QRSPI workflow. Until then both handlers fall through — the plugin is
-// installable and inert, which is what fail-open means.
-
 async function readStdin() {
   let s = ''
   for await (const chunk of process.stdin) s += chunk
@@ -42,58 +40,84 @@ async function readStdin() {
 
 async function handler(name) {
   const input = await readStdin()
-  if (!input || !process.env.TYPESAFE_API_KEY) process.exit(0)
-  process.stderr.write(`hookgate: ${name} gate not implemented yet — falling through\n`)
+  if (!input) process.exit(0)
+  try {
+    const { preToolUse, stop, postToolUse } = await import('./lib/handlers.mjs')
+    const fn = { 'pre-tool-use': preToolUse, stop, 'post-tool-use': postToolUse }[name]
+    const out = await fn(input)
+    if (out) process.stdout.write(`${JSON.stringify(out)}\n`)
+  } catch (e) {
+    // The last line of defence: a bug here is a debug-log line, not a blocked agent.
+    process.stderr.write(`hookgate: ${name} failed open: ${e.message}\n`)
+  }
   process.exit(0)
 }
 
-// --- check ------------------------------------------------------------------
-
 const HOOK_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'Stop', 'SubagentStop', 'UserPromptSubmit', 'PermissionRequest'])
+const HANDLERS = new Set(['pre-tool-use', 'stop', 'post-tool-use'])
+
+function checkHooksFile(path, rootVar, fail) {
+  const hooks = json(path)
+  for (const [event, entries] of Object.entries(hooks.hooks ?? {})) {
+    if (!HOOK_EVENTS.has(event)) fail(`${path}: unknown event ${event}`)
+    for (const entry of entries) {
+      for (const h of entry.hooks ?? []) {
+        if (h.type !== 'command') fail(`${path} ${event}: only command hooks are used here (got ${h.type})`)
+        // Claude Code takes command + args; Codex documents a single command string.
+        const handler = Array.isArray(h.args) ? h.args[0] : h.command.split(/\s+/).at(-1)
+        const bin = Array.isArray(h.args) ? h.command : h.command.replace(/^node\s+"?/, '').replace(/"?\s+\S+$/, '')
+        if (bin !== `${rootVar}/bin/hookgate.mjs`) fail(`${path} ${event}: command must run ${rootVar}/bin/hookgate.mjs, got ${h.command}`)
+        if (!HANDLERS.has(handler)) fail(`${path} ${event}: the command must end in a handler this file implements, got ${handler}`)
+        if (typeof h.timeout !== 'number' || h.timeout > 10) fail(`${path} ${event}: timeout must be set and at most 10 s — a gate that stalls the agent is worse than none`)
+      }
+    }
+  }
+  if (!hooks.hooks?.PreToolUse?.some((e) => e.matcher === 'Bash')) fail(`${path}: the PreToolUse gate must match Bash`)
+  if (!hooks.hooks?.Stop) fail(`${path}: the Stop gate is missing`)
+  return hooks
+}
 
 function check() {
   const errors = []
   const fail = (m) => errors.push(m)
-
   const pkg = json('package.json')
   const plugin = json('.claude-plugin/plugin.json')
   const market = json('.claude-plugin/marketplace.json')
+  const codex = json('.codex-plugin/plugin.json')
 
-  const versions = { 'package.json': pkg.version, 'plugin.json': plugin.version, 'marketplace.json': market.metadata?.version }
+  const versions = { 'package.json': pkg.version, 'plugin.json': plugin.version, 'marketplace.json': market.metadata?.version, 'codex plugin.json': codex.version }
   if (new Set(Object.values(versions)).size !== 1) fail(`versions differ: ${JSON.stringify(versions)}`)
-  if (pkg.name !== 'hookgate' || plugin.name !== 'hookgate') fail('package.json and plugin.json must both be named hookgate')
+  if (pkg.name !== 'hookgate' || plugin.name !== 'hookgate' || codex.name !== 'hookgate') fail('package.json, plugin.json and .codex-plugin/plugin.json must all be named hookgate')
   if (!(market.plugins ?? []).some((p) => p.name === 'hookgate' && p.source === './')) fail('marketplace.json must list the hookgate plugin with source "./"')
-  if (!/github\.com[/:]Allan-Nava\/hookgate/.test(pkg.repository?.url ?? '')) fail('package.json#repository must name the GitHub repo')
+  if (!/^(?:git\+)?https:\/\/github\.com\/Allan-Nava\/hookgate(?:\.git)?$/.test(pkg.repository?.url ?? '')) fail('package.json#repository must be the GitHub repo URL, exactly')
   if (pkg.dependencies && Object.keys(pkg.dependencies).length) fail('no runtime dependencies — a hook runs on every tool call')
-  for (const f of ['bin', 'hooks', '.claude-plugin', 'README.md', 'LICENSE']) if (!pkg.files?.includes(f)) fail(`package.json#files is missing ${f}`)
-
-  const hooks = json('hooks/hooks.json')
-  for (const [event, entries] of Object.entries(hooks.hooks ?? {})) {
-    if (!HOOK_EVENTS.has(event)) fail(`hooks.json: unknown event ${event}`)
-    for (const entry of entries) {
-      for (const h of entry.hooks ?? []) {
-        if (h.type !== 'command') fail(`${event}: only command hooks are used here (got ${h.type})`)
-        if (h.command !== '${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs') fail(`${event}: command must be \${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs, got ${h.command}`)
-        if (!Array.isArray(h.args) || !['pre-tool-use', 'stop'].includes(h.args[0])) fail(`${event}: args must name a handler this file implements`)
-        if (typeof h.timeout !== 'number' || h.timeout > 10) fail(`${event}: timeout must be set and at most 10 s — a gate that stalls the agent is worse than none`)
-      }
-    }
+  for (const f of ['bin', 'hooks', 'codex', '.claude-plugin', '.codex-plugin', 'README.md', 'CHANGELOG.md', 'LICENSE']) if (!pkg.files?.includes(f)) fail(`package.json#files is missing ${f}`)
+
+  const claude = checkHooksFile('hooks/hooks.json', '${CLAUDE_PLUGIN_ROOT}', fail)
+  const codexHooks = checkHooksFile('codex/hooks.json', '${PLUGIN_ROOT}', fail)
+  const handlersOf = (h) => Object.values(h.hooks).flatMap((es) => es.flatMap((e) => e.hooks.map((x) => (Array.isArray(x.args) ? x.args[0] : x.command.split(/\s+/).at(-1))))).sort().join(',')
+  if (handlersOf(claude) !== handlersOf(codexHooks)) fail('hooks/hooks.json and codex/hooks.json must register the same handlers')
+
+  for (const f of ['README.md', 'CONTRIBUTING.md', 'CLAUDE.md', 'LICENSE', 'BACKLOG.md', 'ROADMAP.md', 'CHANGELOG.md']) if (!existsSync(join(ROOT, f))) fail(`${f} is missing`)
+  if (existsSync(join(ROOT, 'CHANGELOG.md'))) {
+    const log = read('CHANGELOG.md')
+    if (!/^## \[Unreleased\]/m.test(log)) fail('CHANGELOG.md needs an [Unreleased] section — the release bump renames it')
+    if (!log.includes(`## [${pkg.version}]`) && pkg.version !== '0.0.0') fail(`CHANGELOG.md has no section for ${pkg.version}`)
   }
-  if (!hooks.hooks?.PreToolUse?.some((e) => e.matcher === 'Bash')) fail('hooks.json: the PreToolUse gate must match Bash')
-
-  for (const f of ['README.md', 'CONTRIBUTING.md', 'CLAUDE.md', 'LICENSE']) if (!existsSync(join(ROOT, f))) fail(`${f} is missing`)
+  if (!/what leaves the machine/i.test(read('README.md'))) fail('README.md must state what leaves the machine')
   if (!/fail-open|fails open/i.test(read('README.md'))) fail('README.md must state the fail-open rule')
+  for (const m of ['bin/lib/config.mjs', 'bin/lib/gates.mjs', 'bin/lib/handlers.mjs', 'bin/lib/harness.mjs', 'bin/lib/jev.mjs', 'bin/lib/redact.mjs', 'bin/lib/store.mjs', 'bin/lib/report.mjs', 'bin/lib/doctor.mjs']) if (!existsSync(join(ROOT, m))) fail(`${m} is missing`)
 
   if (errors.length) {
     for (const e of errors) console.error(`✗ ${e}`)
     process.exit(1)
   }
-  const n = Object.values(hooks.hooks).reduce((a, es) => a + es.reduce((b, e) => b + e.hooks.length, 0), 0)
-  console.log(`ok — ${n} hooks, manifests in sync at ${pkg.version}`)
+  const n = Object.values(claude.hooks).reduce((a, es) => a + es.reduce((b, e) => b + e.hooks.length, 0), 0)
+  console.log(`ok — ${n} hooks, two harnesses, manifests in sync at ${pkg.version}`)
 }
 
 function help() {
-  console.log(read('bin/hookgate.mjs').split('\n').slice(1, 6).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'))
+  console.log(read('bin/hookgate.mjs').split('\n').slice(1, 10).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'))
 }
 
 switch (cmd) {
@@ -102,8 +126,30 @@ switch (cmd) {
     break
   case 'pre-tool-use':
   case 'stop':
+  case 'post-tool-use':
     await handler(cmd)
     break
+  case 'doctor': {
+    const { doctor } = await import('./lib/doctor.mjs')
+    const { lines, broken } = await doctor()
+    console.log(`hookgate doctor\n${lines.join('\n')}`)
+    process.exit(broken ? 1 : 0)
+    break
+  }
+  case 'print-hooks': {
+    const tpl = json('codex/hooks.json')
+    const bin = join(ROOT, 'bin', 'hookgate.mjs')
+    for (const entries of Object.values(tpl.hooks)) for (const e of entries) for (const h of e.hooks) h.command = h.command.replace('${PLUGIN_ROOT}/bin/hookgate.mjs', bin)
+    tpl.description = `hookgate — calibrated gates for Codex CLI, pointing at ${bin}. Save as .codex/hooks.json in the repository (or ~/.codex/hooks.json) and trust it when Codex asks.`
+    console.log(JSON.stringify(tpl, null, 2))
+    break
+  }
+  case 'report': {
+    const { report } = await import('./lib/report.mjs')
+    const { dataDir } = await import('./lib/harness.mjs')
+    console.log(report(dataDir()))
+    break
+  }
   default:
     help()
 }