hookgate 0.0.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "hookgate",
+  "owner": {
+    "name": "Allan Nava",
+    "url": "https://github.com/Allan-Nava"
+  },
+  "metadata": {
+    "description": "Calibrated decision gates for Claude Code hooks.",
+    "version": "0.0.2"
+  },
+  "plugins": [
+    {
+      "name": "hookgate",
+      "source": "./",
+      "description": "PreToolUse and Stop gates decided by TypeSafe's Jev with calibrated confidence — allow, ask or deny in about 100 ms, fail-open when the API is unreachable."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "hookgate",
+  "version": "0.0.2",
+  "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",
+    "url": "https://github.com/Allan-Nava"
+  },
+  "homepage": "https://github.com/Allan-Nava/hookgate",
+  "repository": "https://github.com/Allan-Nava/hookgate",
+  "license": "MIT",
+  "keywords": [
+    "hooks",
+    "guardrails",
+    "typesafe",
+    "system-one",
+    "calibrated-confidence",
+    "agent-safety"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allan Nava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Allan-Nava/hookgate/main/assets/logo.svg" width="72" height="72" alt="hookgate">
+</p>
+<p align="center">
+  <a href="https://allan-nava.github.io/hookgate/"><img src="https://img.shields.io/badge/docs-allan--nava.github.io%2Fhookgate-2f5d8a?labelColor=1b1a18" alt="Documentation"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2f5d8a?labelColor=1b1a18" alt="MIT licence"></a>
+</p>
+
+# hookgate
+
+**Calibrated, sub-second decisions inside Claude Code's hooks.** A `PreToolUse` gate
+on shell commands and a `Stop` gate on unverified claims of completion, answered by
+[TypeSafe's Jev](https://typesafe.ai/) — a model that returns typed decisions with a
+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.
+
+## Why in the hooks
+
+A coding agent's harness takes hundreds of small decisions per session: is this
+`rm -rf` aimed at the repo or at `~`, does "done, all tests pass" match `git status`,
+should this be allowed, asked about or refused. Today those are taken by a static
+allowlist, by a full LLM call (`type: prompt` hooks — seconds and cents each), or by
+nobody. A System One model is built for exactly this shape: unstructured state in,
+a typed answer plus a calibrated probability out, no text to parse, no hallucination
+to catch. TypeSafe's own [plugin](https://github.com/typesafe-ai/skills) and
+[cookbooks](https://docs.typesafe.ai/cookbooks.md) show how to build *applications*
+on Jev. Nobody has put it inside the agent harness. That is the gap this fills.
+
+## What ships
+
+| 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 |
+
+Thresholds live in `.claude/hookgate.json` and scale with risk, as
+[TypeSafe's confidence guide](https://docs.typesafe.ai/confidence.md) recommends.
+
+**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
+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
+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`.
+
+## 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.
+
+## Two design notes
+
+**Why not teach Jev?** TypeSafe already does, well: official Python and JavaScript
+SDKs, an MIT plugin with the patterns, thirteen cookbooks. Duplicating that would be
+noise. hookgate has one job the harness can feel.
+
+**Why zero dependencies?** A hook starts on every tool call. Start-up cost *is* the
+cost, so there is nothing to install, nothing to resolve, one file to read.
+
+## Prior art
+
+- [typesafe-ai/skills](https://github.com/typesafe-ai/skills) — the official agent
+  skill: API, primitives, patterns. Read it to build with Jev.
+- [Claude Code hooks](https://code.claude.com/docs/en/hooks) — `type: prompt` hooks
+  are the incumbent for judged decisions; this is the faster, calibrated alternative.
+- [qrspi](https://github.com/Allan-Nava/qrspi) — the sibling project this one is
+  modelled on: a Markdown-first plugin, a dependency-free installer, a site generated
+  from the README, releases by tag.
+
+## License
+
+MIT.

package/bin/hookgate.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// hookgate — calibrated decision gates for Claude Code 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 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
+// 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.
+//
+// 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'
+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
+  try {
+    return JSON.parse(s)
+  } catch {
+    return null
+  }
+}
+
+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`)
+  process.exit(0)
+}
+
+// --- check ------------------------------------------------------------------
+
+const HOOK_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'Stop', 'SubagentStop', 'UserPromptSubmit', 'PermissionRequest'])
+
+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 versions = { 'package.json': pkg.version, 'plugin.json': plugin.version, 'marketplace.json': market.metadata?.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 (!(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 (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`)
+      }
+    }
+  }
+  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 (!/fail-open|fails open/i.test(read('README.md'))) fail('README.md must state the fail-open rule')
+
+  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}`)
+}
+
+function help() {
+  console.log(read('bin/hookgate.mjs').split('\n').slice(1, 6).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'))
+}
+
+switch (cmd) {
+  case 'check':
+    check()
+    break
+  case 'pre-tool-use':
+  case 'stop':
+    await handler(cmd)
+    break
+  default:
+    help()
+}

package/hooks/hooks.json

@@ -0,0 +1,32 @@
+{
+  "description": "hookgate — calibrated gates. Every handler fails open: no key, no network or an API error means no decision, and Claude Code's normal permission flow takes over.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs",
+            "args": ["pre-tool-use"],
+            "timeout": 5,
+            "statusMessage": "hookgate: judging the command"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/hookgate.mjs",
+            "args": ["stop"],
+            "timeout": 5,
+            "statusMessage": "hookgate: checking the claim of completion"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "hookgate",
+  "version": "0.0.2",
+  "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": {
+    "hookgate": "bin/hookgate.mjs"
+  },
+  "files": [
+    "bin",
+    "hooks",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build:site": "node site/build.mjs",
+    "test": "node bin/hookgate.mjs check",
+    "backlog": "node scripts/backlog.mjs check && node scripts/backlog_test.mjs"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-code-plugin",
+    "hooks",
+    "guardrails",
+    "typesafe",
+    "system-one",
+    "calibrated-confidence",
+    "agent-safety"
+  ],
+  "author": "Allan Nava (https://github.com/Allan-Nava)",
+  "license": "MIT",
+  "homepage": "https://github.com/Allan-Nava/hookgate",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Allan-Nava/hookgate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Allan-Nava/hookgate/issues"
+  },
+  "devDependencies": {
+    "marked": "^18.0.0"
+  }
+}