hookgate 0.0.2 → 0.0.3

package/bin/lib/redact.mjs

@@ -0,0 +1,34 @@
+// State never carries secrets. A command line can hold a token; a tool result can hold
+// a whole .env. Redact before the request, then cap the size — Jev's state limit is
+// 32k tokens and a hook should not be the thing that ships a log file to an API.
+const PATTERNS = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '<redacted:private-key>'],
+  [/\b(sk|rk|pk)[-_](?:live|test|ant|proj)?[-_]?[A-Za-z0-9_-]{16,}/g, '<redacted:key>'],
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, '<redacted:github-token>'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, '<redacted:github-token>'],
+  [/\bAKIA[0-9A-Z]{16}\b/g, '<redacted:aws-key-id>'],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, '<redacted:slack-token>'],
+  [/\bAIza[0-9A-Za-z_-]{30,}\b/g, '<redacted:google-key>'],
+  [/(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{16,}/g, '$1 <redacted>'],
+  [/\b(eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})\b/g, '<redacted:jwt>'],
+  [/(\b[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?)[A-Z0-9_]*\s*[=:]\s*)(["']?)[^\s"'&]{6,}\2/gi, '$1$2<redacted>$2'],
+  [/(--?(?:password|passwd|token|api[-_]?key|secret)[= ])\S+/gi, '$1<redacted>'],
+  [/(https?:\/\/[^\s/@:]+:)[^\s/@]+@/g, '$1<redacted>@'],
+  [/\b[A-Fa-f0-9]{40,}\b/g, '<redacted:hex>'],
+]
+
+export function redact(text) {
+  let out = String(text ?? '')
+  for (const [re, rep] of PATTERNS) out = out.replace(re, rep)
+  return out
+}
+
+export function truncate(text, max) {
+  const s = String(text ?? '')
+  if (s.length <= max) return s
+  const head = Math.floor(max * 0.7)
+  const tail = max - head
+  return `${s.slice(0, head)}\n…[${s.length - max} chars elided by hookgate]…\n${s.slice(-tail)}`
+}
+
+export const prepare = (text, max) => truncate(redact(text), max)

package/bin/lib/report.mjs

@@ -0,0 +1,70 @@
+// `hookgate report`: the README's columns, from the audit log (HG-10), including what
+// the decisions cost (HG-28).
+import { readDecisions } from './store.mjs'
+
+// TypeSafe's published input price, $42 per billion tokens; output is free.
+// One constant, dated, shared with evals/run.mjs — a stale price is a bug.
+export const PRICE_PER_INPUT_TOKEN = 42 / 1e9
+export const PRICE_DATE = '2026-09-22'
+
+const q = (xs, p) => {
+  if (!xs.length) return null
+  const s = [...xs].sort((a, b) => a - b)
+  return s[Math.min(s.length - 1, Math.floor(p * s.length))]
+}
+
+export function summarize(records) {
+  const byGate = {}
+  for (const r of records) {
+    const g = (byGate[r.gate] ??= { total: 0, outcomes: {}, latencies: [], cached: 0, errors: 0, models: new Set(), confidences: [], tokens: 0, judged: 0, unknown: 0 })
+    g.total += 1
+    g.outcomes[r.outcome ?? 'unknown'] = (g.outcomes[r.outcome ?? 'unknown'] ?? 0) + 1
+    if (r.outcome === 'error') g.errors += 1
+    if (r.cached) g.cached += 1
+    else if (typeof r.latencyMs === 'number') g.latencies.push(r.latencyMs)
+    if (r.model) g.models.add(r.model)
+    if (typeof r.confidence === 'number') g.confidences.push(r.confidence)
+    // Judged = a request happened (or a cache hit stood in for one). Skipped, error
+    // and too-long outcomes cost nothing and are not counted here.
+    if (r.model && !r.skipped && r.outcome !== 'error') {
+      g.judged += 1
+      if (typeof r.inputTokens === 'number') g.tokens += r.inputTokens
+      else g.unknown += 1
+    }
+  }
+  return Object.fromEntries(
+    Object.entries(byGate).map(([gate, g]) => [
+      gate,
+      {
+        total: g.total,
+        outcomes: g.outcomes,
+        p50: q(g.latencies, 0.5),
+        p95: q(g.latencies, 0.95),
+        cacheHitRate: g.total ? g.cached / g.total : 0,
+        errors: g.errors,
+        models: [...g.models],
+        askShareAt: Object.fromEntries([0.5, 0.6, 0.7, 0.8, 0.9].map((t) => [t, g.confidences.length ? g.confidences.filter((c) => c < t).length / g.confidences.length : null])),
+        judged: g.judged,
+        inputTokens: g.tokens,
+        tokensUnknown: g.unknown,
+        costTotal: g.tokens * PRICE_PER_INPUT_TOKEN,
+        costPerJudged: g.judged - g.unknown ? (g.tokens * PRICE_PER_INPUT_TOKEN) / (g.judged - g.unknown) : null,
+      },
+    ]),
+  )
+}
+
+export function render(summary) {
+  const lines = []
+  for (const [gate, s] of Object.entries(summary)) {
+    lines.push(`## ${gate} — ${s.total} decisions`)
+    lines.push(`outcomes: ${Object.entries(s.outcomes).map(([k, v]) => `${k} ${v}`).join(' · ')}${s.outcomes.skipped ? ` — ${Math.round((100 * s.outcomes.skipped) / s.total)}% never reached Jev` : ''}`)
+    lines.push(`latency (uncached): p50 ${s.p50 ?? '—'} ms · p95 ${s.p95 ?? '—'} ms · cache hits ${Math.round(s.cacheHitRate * 100)}% · errors ${s.errors}`)
+    if (s.judged) lines.push(`cost: ${s.inputTokens.toLocaleString('en-US')} input tokens over ${s.judged} judged · $${s.costTotal.toFixed(4)} total · ${s.costPerJudged === null ? 'unknown' : `$${s.costPerJudged.toFixed(6)}`} per judged decision at $${(PRICE_PER_INPUT_TOKEN * 1e9).toFixed(0)}/B input tokens (${PRICE_DATE})${s.tokensUnknown ? ` · ${s.tokensUnknown} without usage` : ''}`)
+    lines.push(`share that would be "ask" at threshold: ${Object.entries(s.askShareAt).map(([t, v]) => `${t}→${v === null ? '—' : `${Math.round(v * 100)}%`}`).join('  ')}`)
+    lines.push(`models: ${s.models.join(', ') || '—'}`, '')
+  }
+  return lines.join('\n') || 'no decisions logged yet'
+}
+
+export const report = (dir) => render(summarize(readDecisions(dir)))

package/bin/lib/store.mjs

@@ -0,0 +1,149 @@
+// Everything the plugin remembers lives under the harness's plugin data directory:
+// the audit log (HG-10), the per-session cache (HG-12), the promotion counters (HG-13)
+// and the one-block-per-stop marker. Every write is best-effort — a full disk must
+// not turn into a blocked tool call.
+import { createHash } from 'node:crypto'
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const safe = (fn) => {
+  try {
+    return fn()
+  } catch {
+    return undefined
+  }
+}
+
+export const hash = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16)
+
+// The audit log rotates once at LOG_MAX bytes: decisions.jsonl → decisions.1.jsonl,
+// the previous .1 dropped. Two files bound the disk; `report` reads both.
+export const LOG_MAX = 8 * 1024 * 1024
+
+export function appendDecision(dir, record) {
+  safe(() => {
+    mkdirSync(dir, { recursive: true })
+    const p = join(dir, 'decisions.jsonl')
+    // No exists-then-stat: read the size in one call and let a missing file throw into `safe`.
+    const size = safe(() => statSync(p).size) ?? 0
+    if (size > LOG_MAX) renameSync(p, join(dir, 'decisions.1.jsonl'))
+    appendFileSync(p, `${JSON.stringify(record)}\n`)
+  })
+}
+
+export function readDecisions(dir) {
+  return ['decisions.1.jsonl', 'decisions.jsonl']
+    .map((f) => safe(() => readFileSync(join(dir, f), 'utf8')) ?? '')
+    .flatMap((text) => text.split('\n'))
+    .filter(Boolean)
+    .map((l) => safe(() => JSON.parse(l)))
+    .filter(Boolean)
+}
+
+// Per-session state: cache entries and promotion counters, one JSON file per session.
+export function sessionFile(dir, sessionId) {
+  return join(dir, 'sessions', `${(sessionId || 'no-session').replace(/[^\w-]/g, '_')}.json`)
+}
+
+export function loadSession(dir, sessionId) {
+  return safe(() => JSON.parse(readFileSync(sessionFile(dir, sessionId), 'utf8'))) ?? { cache: {}, prefixes: {}, proposed: [], blockedPrompts: [] }
+}
+
+// Atomic: write beside, then rename, so two hooks racing (parallel tool calls) can
+// lose an update but never leave a torn file. Session files older than SESSION_TTL
+// are pruned on the way, one in ~20 writes.
+export const SESSION_TTL = 7 * 24 * 3600 * 1000
+
+export function saveSession(dir, sessionId, state, now = Date.now()) {
+  safe(() => {
+    const d = join(dir, 'sessions')
+    mkdirSync(d, { recursive: true })
+    const p = sessionFile(dir, sessionId)
+    const tmp = `${p}.${process.pid}.tmp`
+    writeFileSync(tmp, JSON.stringify(state))
+    renameSync(tmp, p)
+    if (Math.random() < 0.05) pruneSessions(dir, now)
+  })
+}
+
+export function pruneSessions(dir, now = Date.now()) {
+  safe(() => {
+    const d = join(dir, 'sessions')
+    for (const f of readdirSync(d)) {
+      const p = join(d, f)
+      if (now - statSync(p).mtimeMs > SESSION_TTL) unlinkSync(p)
+    }
+  })
+}
+
+export function cacheKey(gate, cwd, state) {
+  return hash(`${gate}\n${cwd}\n${JSON.stringify(state)}`)
+}
+
+export function cacheGet(session, key, ttlMs, now = Date.now()) {
+  const e = session.cache?.[key]
+  if (!e) return null
+  if (now - e.at > ttlMs) return null
+  return e
+}
+
+export function cachePut(session, key, value, now = Date.now()) {
+  session.cache ??= {}
+  session.cache[key] = { ...value, at: now }
+  // Keep the file bounded: drop the oldest beyond 500 entries.
+  const keys = Object.keys(session.cache)
+  if (keys.length > 500) for (const k of keys.sort((a, b) => session.cache[a].at - session.cache[b].at).slice(0, keys.length - 500)) delete session.cache[k]
+}
+
+// Promotion (HG-13): count confident, identical decisions per command prefix.
+export function commandPrefix(command) {
+  let s = String(command).trim()
+  // Skip what is not the command: leading VAR=value assignments and `cd <dir> &&` /
+  // `cd <dir>;` hops — 47% of real commands start with a cd, and a promotion rule for
+  // "cd" would be meaningless.
+  for (let guard = 0; guard < 8; guard++) {
+    // `cd X && cmd`, `cd X; cmd` and `cd X⏎cmd` — the last is how most real commands
+    // arrive (9,408 of 12,700 cd-led commands in one maintainer's transcripts).
+    const next = s.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/, '').replace(/^cd\s+(?:"[^"]*"|'[^']*'|\S+)[ \t]*(?:&&|;|\n)\s*/, '')
+    if (next === s) break
+    s = next
+  }
+  const words = s.split(/\s+/)
+  const first = words[0] ?? ''
+  const takesSub = ['git', 'npm', 'npx', 'pnpm', 'yarn', 'docker', 'kubectl', 'gh', 'cargo', 'go', 'make', 'python', 'python3', 'node', 'pip']
+  return takesSub.includes(first) && words[1] && !words[1].startsWith('-') ? `${first} ${words[1]}` : first
+}
+
+// What a promoted rule may cover (HG-24, HG-25). A rule is a prefix, so it covers
+// every command that starts that way: it must only ever be proposed for a command
+// that IS that prefix plus arguments — one simple command, no chaining, no
+// substitution — and never for a program that runs whatever follows.
+const NEVER_PROMOTE = new Set(['python', 'python3', 'node', 'deno', 'bun', 'bash', 'sh', 'zsh', 'fish', 'dash', 'ksh', 'sudo', 'doas', 'su', 'env', 'xargs', 'eval', 'exec', 'source', '.', 'perl', 'ruby', 'php', 'lua', 'osascript', 'nohup', 'time', 'timeout', 'command', 'builtin', 'nice', 'watch', 'caffeinate', 'ssh', 'script', 'expect', 'parallel', 'find'])
+
+export function promotablePrefix(command) {
+  let s = String(command).trim()
+  for (let guard = 0; guard < 8; guard++) {
+    const next = s.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/, '').replace(/^cd\s+(?:"[^"]*"|'[^']*'|\S+)[ \t]*(?:&&|;|\n)\s*/, '')
+    if (next === s) break
+    s = next
+  }
+  // Operators outside quotes make it more than one command: 92.5% of real commands.
+  const unquoted = s.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, '""')
+  if (/&&|\|\||;|\||\n|`|\$\(/.test(unquoted)) return null
+  const prefix = commandPrefix(s)
+  if (!prefix || NEVER_PROMOTE.has(prefix.split(' ')[0])) return null
+  return prefix
+}
+
+export function notePrefix(session, prefix, decision, confidence, cfg) {
+  if (!prefix || !['allow', 'deny'].includes(decision) || confidence < cfg.promote.confidence) return null
+  session.prefixes ??= {}
+  session.proposed ??= []
+  const p = (session.prefixes[prefix] ??= { allow: 0, deny: 0 })
+  p[decision] += 1
+  if (p[decision] >= cfg.promote.after && !session.proposed.includes(prefix)) {
+    session.proposed.push(prefix)
+    return { prefix, decision, count: p[decision] }
+  }
+  return null
+}

package/codex/hooks.json

@@ -0,0 +1,43 @@
+{
+  "description": "hookgate — calibrated gates for Codex CLI. Every handler fails open: no key, no network or an API error means no decision, and Codex's normal approval flow takes over.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/bin/hookgate.mjs\" pre-tool-use",
+            "timeout": 5,
+            "statusMessage": "hookgate: judging the command"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebFetch|WebSearch|Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/bin/hookgate.mjs\" post-tool-use",
+            "timeout": 5,
+            "statusMessage": "hookgate: screening the result for injected instructions"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/bin/hookgate.mjs\" stop",
+            "timeout": 5,
+            "statusMessage": "hookgate: checking the claim of completion"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -5,26 +5,22 @@
       {
         "matcher": "Bash",
         "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs",
-            "args": ["pre-tool-use"],
-            "timeout": 5,
-            "statusMessage": "hookgate: judging the command"
-          }
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs", "args": ["pre-tool-use"], "timeout": 5, "statusMessage": "hookgate: judging the command" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebFetch|WebSearch|Read|Bash",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs", "args": ["post-tool-use"], "timeout": 5, "statusMessage": "hookgate: screening the result for injected instructions" }
         ]
       }
     ],
     "Stop": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs",
-            "args": ["stop"],
-            "timeout": 5,
-            "statusMessage": "hookgate: checking the claim of completion"
-          }
+          { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs", "args": ["stop"], "timeout": 5, "statusMessage": "hookgate: checking the claim of completion" }
         ]
       }
     ]

package/package.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.",
   "type": "module",
   "bin": {
@@ -9,8 +9,11 @@
   "files": [
     "bin",
     "hooks",
+    "codex",
     ".claude-plugin",
+    ".codex-plugin",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -18,7 +21,8 @@
   },
   "scripts": {
     "build:site": "node site/build.mjs",
-    "test": "node bin/hookgate.mjs check",
+    "test": "node bin/hookgate.mjs check && node --test",
+    "scorecard": "node evals/scorecard.mjs",
     "backlog": "node scripts/backlog.mjs check && node scripts/backlog_test.mjs"
   },
   "keywords": [