@coderifts/agent-hooks 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "agent-hooks",
+  "version": "0.2.0",
+  "description": "Ask CodeRifts before Claude Code writes a contract artifact (OpenAPI, AsyncAPI, GraphQL, protobuf, MCP manifest).",
+  "author": {
+    "name": "CodeRifts",
+    "email": "peter@coderifts.com"
+  },
+  "homepage": "https://coderifts.com",
+  "repository": "https://github.com/coderifts/agent-hooks",
+  "license": "MIT",
+  "keywords": [
+    "coderifts",
+    "pretooluse",
+    "contract-change",
+    "openapi",
+    "hooks"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.2.0 — 2026-09-13
+
+**(a) New host.** Claude Code PreToolUse adapter. Same `gate.js`; new stdin envelope.
+
+**(b) Rename.** npm package is `@coderifts/agent-hooks` (was `@coderifts/openclaw-plugin`).
+The package is no longer one host's plugin: OpenClaw and Claude Code share `gate.js`,
+and a Docker `before:exec` adapter is measured but not shipped. The Claude marketplace
+plugin id is `agent-hooks`, not `contract-gate` — that name is the GitHub Action
+(`coderifts/contract-gate`). `@coderifts/agent-guard` remains the wrapWithGuard library.
+
+### Added
+
+- `claude-code/hook.mjs`: maps Write/Edit/MultiEdit stdin JSON onto `createGate`, then:
+  - CONTINUE → exit 0, empty stdout (never `permissionDecision: allow`)
+  - REQUEST_APPROVAL / keyless analyze → JSON `ask`
+  - STOP → JSON `deny` (reason still carries Does not prove)
+  - unreachable / unreadable / throw / bad stdin → **exit 2 + stderr** because Claude Code command hooks are fail-open on timeout, exit 1, and missing scripts
+- Plugin wiring: `hooks/hooks.json` (`timeout: 8` **seconds**), `.claude-plugin/plugin.json`, copyable `claude-code/settings.snippet.json`, `claude-code/marketplace-entry.json` for the existing `coderifts` marketplace
+- Adapter tests (`test/claude-hook.test.js`) and pack coverage for the adapter file
+
+### Limits (named, not silent)
+
+- **Host timeout fail-open.** Hook config `timeout` is seconds (default 600). We set 8, above the gate's 5000 ms, so a slow CodeRifts answer becomes exit 2 from us. If `node` hangs past 8 s, Claude Code **still lets the tool run**. This cannot be fixed in the hook.
+- **Bash hole.** Matcher is `Write|Edit|MultiEdit`. A shell command that writes `openapi.yaml` (`cat > …`, `tee`, …) is not seen. Parsing those commands is not a gate; the README says so.
+
+## 0.1.1 — 2026-09-13
+
+**0.1.0 was broken.** `npm pack` / `openclaw plugins install` shipped a tarball
+without `gate.js`. `index.js` imports `./gate.js`, so the installed plugin failed
+to load (`Cannot find module './gate.js'`). The 14 in-repo tests imported from
+the checkout, not from the packed tarball, and did not catch this.
+
+### Fixed
+
+- Include `gate.js` in `package.json` `"files"`.
+- Add a pack-then-install test (`test/pack.test.js`) that fails if any relative
+  import of the packed `index.js` is missing from the tarball.
+- Declare `openclaw` as a peerDependency (`>=2026.6.35`, optional so npm does
+  not fetch the host as a nested install). Without the peer, `npm install` of
+  0.1.0 was silent about a missing host.
+- Add `openclaw.build.openclawVersion` (`2026.6.35`) — ClawHub `package publish`
+  rejects external code plugins that omit it.
+
+## 0.1.0 — 2026-09-13
+
+Initial release. **Do not use.** The published tarball omitted `gate.js`.
+Use 0.1.1.

package/README.md

@@ -0,0 +1,146 @@
+# CodeRifts agent hooks (`@coderifts/agent-hooks`)
+
+Asks CodeRifts before an agent writes a contract artifact — an OpenAPI, AsyncAPI, GraphQL,
+protobuf or MCP manifest file. **Hosts today:** OpenClaw `before_tool_call` and Claude Code
+`PreToolUse`. **Not built:** the Docker MCP Gateway `before:exec` interceptor — that path
+was measured (empty stdout = pass, CallToolResult JSON = block, HTTP 4xx empty = fail-open)
+and has no adapter in this package yet.
+
+This is the host-adapter package. It is not `@coderifts/agent-guard` (the wrapWithGuard
+library) and not `coderifts/contract-gate` (the GitHub Action). The npm name used to be
+`@coderifts/openclaw-plugin`; that name is wrong now that more than one host is wired.
+
+The same `gate.js` drives every host. The gate makes no policy decisions of its own. It
+recognises the file, sends the before/after to CodeRifts, and maps the answer back.
+Everything it cannot map, it puts to a human.
+
+## What it does
+
+| CodeRifts `execution_action` | OpenClaw | Claude Code PreToolUse |
+| --- | --- | --- |
+| `CONTINUE`, `CONTINUE_WITH_MONITORING` | pass through | exit 0, empty stdout (never `allow`) |
+| `REQUEST_APPROVAL` | `requireApproval` | JSON `permissionDecision: "ask"` |
+| `STOP` | `block`, with the reason and its limits | JSON `permissionDecision: "deny"` |
+| anything else, or no answer | `requireApproval` | **exit 2 + stderr** (host is fail-open) |
+
+## What it does not do
+
+- **It does not gate what it does not recognise.** A tool call writing `README.md` passes untouched.
+  The recognised set is a short, explicit list in `gate.js`; a gate that guesses at every file either
+  blocks documentation or waves through a schema.
+- **It does not turn a risk number into a verdict.** Without an API key CodeRifts answers in
+  `analyze` mode, which returns `authorization_effect: "NONE"` and `may_execute: false` — risk
+  information and no decision. The gate reports that and asks a human. It never reads a high score
+  as a block or a low one as a pass.
+- **It does not lock the file.** The bytes checked are the bytes in the tool params at the moment of
+  the call. Nothing here holds them between the answer and the write.
+
+Every refusal says so in its own text, so an agent reading the transcript can see how far the answer
+reaches:
+
+```
+CodeRifts refused this contract change.
+Reason: endpoint_removed — ENDPOINT_REMOVAL
+Proves: the change set as this call would leave it was refused by CodeRifts under operation "tool_call".
+Does not prove:
+  - that the bytes finally written are the bytes checked — nothing here locks the file between this answer and the write
+  - that the other tool calls in this run were checked — each call is judged alone
+  - that a contract artifact this gate does not recognise was seen at all
+```
+
+## Fail-closed
+
+If CodeRifts is unreachable, times out, or answers something the gate cannot read, the result is
+not a pass. Not knowing is not permission.
+
+The gate's own budget defaults to 5000 ms.
+
+On **OpenClaw**, that is well under the host's 15000 ms `before_tool_call` budget, so a slow
+answer becomes a readable approval request, not an opaque host denial. The host is fail-closed.
+
+On **Claude Code**, the host is **fail-open**: a timed-out command hook, exit 1, invalid JSON,
+or a missing script lets the tool run. The adapter therefore maps those failures to **exit 2**.
+The hook entry sets `"timeout": 8` (**seconds** — Claude Code's unit, not milliseconds) so the
+gate's 5000 ms abort can finish first. If `node` itself hangs past 8 s, Claude Code still
+lets the write through. That host behaviour cannot be fixed in this package.
+
+## What this gate does not see (Claude Code)
+
+The Claude Code matcher is `Write|Edit|MultiEdit`. A contract file written by a **shell
+command** (`cat > openapi.yaml`, `tee`, `python -c "open(...)"`, …) does not go through
+those tools, so this hook never runs. Parsing Bash to guess destination paths is not a
+gate — it would miss more than it caught. Treat a shell-written schema as unchecked.
+
+Does not prove:
+  - that a contract artifact written via Bash or PowerShell was seen at all
+
+## Configuration
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "coderifts-contract-gate": {
+        "config": {
+          "apiKey": "...",
+          "endpoint": "https://app.coderifts.com/mcp",
+          "timeoutMs": 5000,
+          "operation": "tool_call"
+        }
+      }
+    }
+  }
+}
+```
+
+`apiKey` is optional in the schema and load-bearing in practice: **without it there is no decision.**
+`preflight_mode=authorize` requires a verified issuer, so an unkeyed gate runs in `analyze` mode and
+every gated call ends at a human. That is safe and it is noisy; the key is what makes it useful.
+
+There is no setting that makes an unanswered call pass. That absence is the design.
+
+## Hook placement
+
+Registered on `before_tool_call` at `priority: 100`. OpenClaw runs handlers in descending priority
+and keeps only the **first** `requireApproval`, so a gate that runs late can have its question
+dropped by an earlier plugin. A `block` is sticky and survives regardless of order.
+
+## Install — OpenClaw
+
+```bash
+openclaw plugins install @coderifts/agent-hooks
+```
+
+(OpenClaw still records the plugin under the runtime id `coderifts-contract-gate` — that is
+the OpenClaw config key, not the GitHub Action.)
+
+## Install — Claude Code
+
+Copy `claude-code/settings.snippet.json` into `.claude/settings.json` (or merge the
+`hooks` key), after `npm install @coderifts/agent-hooks`. Optional env:
+`CODERIFTS_API_KEY`, `CODERIFTS_ENDPOINT`, `CODERIFTS_TIMEOUT_MS` (milliseconds, gate
+budget; default 5000).
+
+Plugin shape (for the existing `coderifts` marketplace): `.claude-plugin/plugin.json` +
+`hooks/hooks.json`. Add `claude-code/marketplace-entry.json` to
+`coderifts/api-governance` `.claude-plugin/marketplace.json` `plugins` array — that
+catalog today lists only `api-governance`. Then:
+
+```bash
+claude plugin marketplace update coderifts
+claude plugin install agent-hooks@coderifts
+```
+
+Do not use `permissionDecision: allow` for CONTINUE. Empty exit 0 leaves the normal
+permission prompt in place.
+
+## Test
+
+```bash
+npm test
+```
+
+`npm test` includes a pack-then-install case. In-repo imports cannot see a
+`files` allowlist that dropped a relative module — that is how 0.1.0 shipped
+without `gate.js`. The pack test also requires `claude-code/hook.mjs`. Do not
+skip it.

package/claude-code/hook.mjs

@@ -0,0 +1,119 @@
+/**
+ * Claude Code PreToolUse adapter. Translates the host's stdin JSON into the
+ * OpenClaw-shaped event `createGate` already understands, then maps the three
+ * gate results onto the Claude Code contract (measured 2026-09-13):
+ *
+ *   undefined           → exit 0, empty stdout (NOT permissionDecision allow)
+ *   requireApproval     → JSON ask  (named CodeRifts decision)
+ *   block               → JSON deny (reason includes Does not prove)
+ *   transport/parse/throw → exit 2 + stderr  (the host is fail-open otherwise)
+ *
+ * `gate.js` is untouched. This file only remaps envelopes.
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createGate } from "../gate.js";
+
+/** Claude Code Write/Edit/MultiEdit → the path/content keys `resolveTarget` reads. */
+export const CLAUDE_TOOL_SHAPES = Object.freeze({
+  Write: { path: "file_path", content: "content" },
+  Edit: { path: "file_path", content: "new_string" },
+  MultiEdit: { path: "file_path", content: "content" },
+});
+
+const ASK_TITLES = new Set([
+  "CodeRifts asks for approval",
+  "CodeRifts returned analysis, not authorization",
+]);
+
+function emptyPass() {
+  return { exitCode: 0, stdout: "", stderr: "" };
+}
+
+function jsonDecision(permissionDecision, reason) {
+  return {
+    exitCode: 0,
+    stdout:
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision,
+          permissionDecisionReason: reason,
+        },
+      }) + "\n",
+    stderr: "",
+  };
+}
+
+function failClosed(message) {
+  return { exitCode: 2, stdout: "", stderr: String(message).trim() + "\n" };
+}
+
+export function configFromEnv(env = process.env) {
+  const timeoutRaw = env.CODERIFTS_TIMEOUT_MS;
+  const timeoutMs = timeoutRaw === undefined || timeoutRaw === "" ? undefined : Number(timeoutRaw);
+  return {
+    apiKey: env.CODERIFTS_API_KEY || undefined,
+    endpoint: env.CODERIFTS_ENDPOINT || undefined,
+    timeoutMs: Number.isFinite(timeoutMs) ? timeoutMs : undefined,
+    operation: env.CODERIFTS_OPERATION || undefined,
+    toolShapes: CLAUDE_TOOL_SHAPES,
+  };
+}
+
+export function mapGateResult(result) {
+  if (result === undefined) return emptyPass();
+  if (result?.block) {
+    return jsonDecision("deny", result.blockReason ?? "CodeRifts refused this contract change.");
+  }
+  const approval = result?.requireApproval;
+  if (approval) {
+    const reason = approval.description ?? approval.title ?? "CodeRifts asks for a human.";
+    if (ASK_TITLES.has(approval.title)) return jsonDecision("ask", reason);
+    return failClosed(reason);
+  }
+  return failClosed("CodeRifts gate returned a shape this adapter does not map. Not knowing is not permission.");
+}
+
+export async function runClaudeHook(stdinText, { env = process.env, deps } = {}) {
+  let payload;
+  try {
+    payload = JSON.parse(stdinText);
+  } catch (err) {
+    return failClosed(`CodeRifts Claude hook: stdin was not JSON (${err?.message ?? err}).`);
+  }
+  if (!payload || typeof payload !== "object") {
+    return failClosed("CodeRifts Claude hook: stdin JSON was not an object.");
+  }
+
+  const event = {
+    toolName: payload.tool_name,
+    params: payload.tool_input ?? {},
+  };
+
+  try {
+    const gate = createGate(configFromEnv(env), deps);
+    const result = await gate(event);
+    return mapGateResult(result);
+  } catch (err) {
+    return failClosed(
+      `CodeRifts Claude hook failed before a decision (${String(err?.message ?? err)}). Not knowing is not permission.`,
+    );
+  }
+}
+
+async function main() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString("utf8");
+  const out = await runClaudeHook(raw);
+  if (out.stdout) process.stdout.write(out.stdout);
+  if (out.stderr) process.stderr.write(out.stderr);
+  process.exit(out.exitCode);
+}
+
+const invokedDirectly =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+if (invokedDirectly) {
+  main();
+}

package/claude-code/marketplace-entry.json

@@ -0,0 +1,18 @@
+{
+  "name": "agent-hooks",
+  "source": {
+    "source": "github",
+    "repo": "coderifts/agent-hooks"
+  },
+  "description": "Host adapters for CodeRifts: Claude Code PreToolUse asks before Write/Edit of OpenAPI, AsyncAPI, GraphQL, protobuf, or MCP manifest files. Not the GitHub Action (coderifts/contract-gate) and not the guard library (@coderifts/agent-guard).",
+  "version": "0.2.0",
+  "author": {
+    "name": "CodeRifts",
+    "email": "peter@coderifts.com"
+  },
+  "homepage": "https://coderifts.com",
+  "repository": "https://github.com/coderifts/agent-hooks",
+  "license": "MIT",
+  "keywords": ["coderifts", "pretooluse", "openapi", "hooks"],
+  "category": "development"
+}

package/claude-code/settings.snippet.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 8,
+            "command": "node",
+            "args": [
+              "${CLAUDE_PROJECT_DIR}/node_modules/@coderifts/agent-hooks/claude-code/hook.mjs"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/gate.js

@@ -0,0 +1,263 @@
+/**
+ * The gate itself, with no OpenClaw imports, so it can be exercised directly.
+ *
+ * `index.js` is the OpenClaw entry; everything decidable lives here.
+ */
+
+import { readFile } from "node:fs/promises";
+
+/**
+ * Path suffix -> the `type` the CodeRifts change-set surface expects.
+ *
+ * Deliberately a short, explicit list. A gate that tries to recognise every contract artifact ends
+ * up guessing, and a gate that guesses either blocks documentation or waves through a schema. What
+ * is not on this list is not gated — and the approval text says so, so nobody reads a CONTINUE as
+ * "the whole change was checked".
+ */
+export const ARTIFACT_TYPES = Object.freeze([
+  [/(^|\/)openapi[^/]*\.(ya?ml|json)$/i, "openapi"],
+  [/(^|\/)swagger[^/]*\.(ya?ml|json)$/i, "openapi"],
+  [/(^|\/)asyncapi[^/]*\.(ya?ml|json)$/i, "asyncapi"],
+  [/\.graphql$|\.gql$/i, "graphql"],
+  [/\.proto$/i, "protobuf"],
+  [/(^|\/)(mcp|tools)\.(wire\.v1\.)?json$/i, "mcp"],
+]);
+
+/** Tools whose params carry a path and a new file body. */
+export const DEFAULT_TOOL_SHAPES = Object.freeze({
+  write_file: { path: "path", content: "content" },
+  create_file: { path: "path", content: "content" },
+  edit_file: { path: "path", content: "content" },
+  str_replace_editor: { path: "path", content: "new_str" },
+});
+
+export function classifyPath(p) {
+  for (const [re, type] of ARTIFACT_TYPES) if (re.test(p)) return type;
+  return null;
+}
+
+/**
+ * What this gate proves, and what it does not. Carried on EVERY refusal.
+ *
+ * An agent that reads "DENIED" and nothing else learns only that something said no. These lines are
+ * the difference between a policy engine's verdict and a reviewable one: they tell the agent — and
+ * the human reading the transcript — exactly how far the answer reaches.
+ */
+export const DOES_NOT_PROVE = Object.freeze([
+  "that the bytes finally written are the bytes checked — nothing here locks the file between this answer and the write",
+  "that the other tool calls in this run were checked — each call is judged alone",
+  "that a contract artifact this gate does not recognise was seen at all",
+]);
+
+/**
+ * What the answer actually establishes. The verb has to match the verdict: a refusal was refused, an
+ * approval request was NOT — writing "refused" on an approval would be the gate overstating its own
+ * answer in the one sentence meant to bound it.
+ */
+const proves = (op, verb) =>
+  `Proves: the change set as this call would leave it was ${verb} by CodeRifts under operation "${op}".`;
+
+const limits = () => DOES_NOT_PROVE.map((l) => `  - ${l}`).join("\n");
+
+/** Build the refusal text an agent will actually read. */
+export function blockText(op, why) {
+  return [
+    `CodeRifts refused this contract change.`,
+    why ? `Reason: ${why}` : null,
+    proves(op, "refused"),
+    `Does not prove:`,
+    limits(),
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/** One JSON-RPC POST. No session handshake, no SDK — measured to be all the surface needs. */
+async function askCodeRifts({ endpoint, apiKey, timeoutMs, operation, artifact }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+    if (apiKey) headers["X-API-Key"] = apiKey;
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "preflight_change_set",
+          arguments: {
+            // authorize is the only mode that carries a decision. Without a key the server answers
+            // authorization_requires_issuer, so an unkeyed gate asks in analyze mode and then has
+            // to fall to approval — see decide().
+            preflight_mode: apiKey ? "authorize" : "analyze",
+            context: { operation },
+            artifacts: [artifact],
+          },
+        },
+      }),
+    });
+    if (!res.ok) return { kind: "unreachable", detail: `HTTP ${res.status}` };
+    const env = await res.json();
+    if (env.error) return { kind: "unusable", detail: env.error.message ?? "JSON-RPC error" };
+    const text = env?.result?.content?.[0]?.text;
+    if (typeof text !== "string") return { kind: "unusable", detail: "no content in response" };
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      return { kind: "unusable", detail: "response was not JSON" };
+    }
+    if (body?.error) return { kind: "unusable", detail: body.message ?? body.error };
+    return { kind: "ok", body };
+  } catch (err) {
+    const aborted = err?.name === "AbortError";
+    return { kind: "unreachable", detail: aborted ? `no answer within ${timeoutMs}ms` : String(err?.message ?? err) };
+  }
+}
+
+/** Ask for a human, always with a reason. Never `{}`. */
+const ask = (title, description) => ({
+  requireApproval: {
+    title,
+    description,
+    severity: "warning",
+    // Explicit "deny", not because it is honoured everywhere — on current OpenClaw unresolved
+    // approvals always deny and this field is deprecated — but because on the extended-stable line
+    // it is still read, and "allow" there would be a genuine fail-open.
+    timeoutBehavior: "deny",
+  },
+});
+
+/**
+ * Turn one CodeRifts answer into one OpenClaw hook result.
+ *
+ * The three shapes are the host's, measured: `undefined` passes, `{block, blockReason}` refuses,
+ * `{requireApproval}` asks. There is no fourth, and no default pass.
+ */
+export function decide(outcome, { operation, path }) {
+  if (outcome.kind === "unreachable") {
+    return ask(
+      "CodeRifts did not answer",
+      `${path} is a contract artifact and CodeRifts could not be reached (${outcome.detail}). ` +
+        `No decision was obtained, and not knowing is not permission.`,
+    );
+  }
+  if (outcome.kind === "unusable") {
+    return ask(
+      "CodeRifts answer could not be read",
+      `${path} is a contract artifact and CodeRifts replied with something this gate cannot interpret ` +
+        `(${outcome.detail}). No decision was obtained, and not knowing is not permission.`,
+    );
+  }
+
+  const body = outcome.body;
+
+  // The analyze path says so about itself. Reading its risk number as a verdict would be this
+  // plugin inventing a policy engine, which is the one thing it must not do.
+  if (body.authorization_effect === "NONE" || body.may_execute === false && !body.execution_action) {
+    return ask(
+      "CodeRifts returned analysis, not authorization",
+      `${path} is a contract artifact. Without an API key CodeRifts answers in analyze mode ` +
+        `(authorization_effect=${String(body.authorization_effect)}, may_execute=${String(body.may_execute)}), ` +
+        `which carries risk information and no decision` +
+        (body.risk_score !== undefined ? ` (risk_score ${body.risk_score}` +
+          (Array.isArray(body.patterns) && body.patterns.length ? `, ${body.patterns.join(", ")}` : "") + `)` : "") +
+        `. Configure apiKey to get a decision; until then every gated call asks.`,
+    );
+  }
+
+  switch (body.execution_action) {
+    case "CONTINUE":
+    case "CONTINUE_WITH_MONITORING":
+      return undefined;
+    case "REQUEST_APPROVAL":
+      return ask(
+        "CodeRifts asks for approval",
+        `${path} — CodeRifts returned ${body.execution_action} for operation "${operation}"` +
+          (body.risk_score !== undefined ? `, risk_score ${body.risk_score}` : "") +
+          (Array.isArray(body.patterns) && body.patterns.length ? `, ${body.patterns.join(", ")}` : "") +
+          `.\n${proves(operation, "put to a human")}\nDoes not prove:\n${limits()}`,
+      );
+    case "STOP":
+      return {
+        block: true,
+        blockReason: blockText(
+          operation,
+          [
+            body.decision_basis?.rule_ids?.join(", "),
+            Array.isArray(body.patterns) && body.patterns.length ? body.patterns.join(", ") : null,
+          ]
+            .filter(Boolean)
+            .join(" — ") || undefined,
+        ),
+      };
+    default:
+      return ask(
+        "CodeRifts returned an action this gate does not know",
+        `${path} — execution_action was ${JSON.stringify(body.execution_action)}. ` +
+          `An unrecognised action is not a pass.`,
+      );
+  }
+}
+
+/**
+ * Resolve the file this tool call would write, if any.
+ *
+ * `derivedPaths` is the host's own hint and is documented as best-effort, so it is used to widen the
+ * search, never to replace reading `params`.
+ */
+export function resolveTarget(event, shapes) {
+  const shape = shapes[event.toolName];
+  const fromParams = shape ? event.params?.[shape.path] : undefined;
+  const candidates = [fromParams, ...(event.derivedPaths ?? [])].filter((p) => typeof p === "string" && p);
+  for (const p of candidates) {
+    const type = classifyPath(p);
+    if (type) return { path: p, type, content: shape ? event.params?.[shape.content] : undefined };
+  }
+  return null;
+}
+
+/** The handler, with its I/O injected so a test can drive it without a network or a disk. */
+export function createGate(config = {}, deps = {}) {
+  const endpoint = config.endpoint ?? "https://app.coderifts.com/mcp";
+  const apiKey = config.apiKey;
+  const timeoutMs = config.timeoutMs ?? 5000;
+  const operation = config.operation ?? "tool_call";
+  const shapes = { ...DEFAULT_TOOL_SHAPES, ...(config.toolShapes ?? {}) };
+  const call = deps.askCodeRifts ?? askCodeRifts;
+  const read = deps.readFile ?? ((p) => readFile(p, "utf8"));
+
+  return async function beforeToolCall(event) {
+    const target = resolveTarget(event, shapes);
+    // Not a contract artifact this gate recognises. Staying out of the way is not a fail-open: the
+    // gate never claimed this call, and DOES_NOT_PROVE says as much on every refusal it does make.
+    if (!target) return undefined;
+    if (typeof target.content !== "string") {
+      return ask(
+        "CodeRifts gate could not read the proposed change",
+        `${target.path} is a contract artifact, but this gate could not find the new content in the ` +
+          `params of "${event.toolName}". It will not pass a change it has not seen.`,
+      );
+    }
+
+    let before = "";
+    try {
+      before = await read(target.path);
+    } catch {
+      before = ""; // A new file. An empty "before" is a real change set, not a missing one.
+    }
+
+    const outcome = await call({
+      endpoint,
+      apiKey,
+      timeoutMs,
+      operation,
+      artifact: { id: target.path, type: target.type, before, after: target.content },
+    });
+    return decide(outcome, { operation, path: target.path });
+  };
+}

package/hooks/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Ask CodeRifts before Write/Edit of a contract artifact. Host timeout is 8s (seconds). Gate budget is 5000ms. If this process hangs past the host timeout, Claude Code fail-opens — named in the README.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 8,
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/claude-code/hook.mjs"]
+          }
+        ]
+      }
+    ]
+  }
+}

package/index.js

@@ -0,0 +1,57 @@
+/**
+ * CodeRifts contract gate for OpenClaw.
+ *
+ * MEASURED SHAPE (openclaw 2026.6.35 installed, main source read 2026-09-13):
+ *
+ *   api.on("before_tool_call", handler, { priority })
+ *     handler(event, ctx) -> undefined | { params } | { block, blockReason } | { requireApproval }
+ *
+ *   Handlers run sequentially in DESCENDING priority; same priority keeps registration order. The
+ *   first `block: true` stops the chain. `block` is sticky, so an earlier plugin passing the call
+ *   through does NOT stop this one from refusing. The FIRST `requireApproval` wins, so if another
+ *   plugin already asked, ours is dropped — our `block` still applies.
+ *
+ *   The host declares before_tool_call fail-closed (failurePolicyByHook) with a 15000ms budget, and
+ *   a thrown handler error is NOT swallowed: it propagates and the tool call fails. Verified live
+ *   against the host's own hook runner, all eight cases.
+ *
+ * PRIORITY 100 is deliberate. This gate wants to run before a plugin that might request approval
+ * for its own reasons, because only the first requireApproval survives the merge, and a refusal
+ * that names the contract change is more useful to a human than one that does not.
+ */
+
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createGate } from "./gate.js";
+
+export default definePluginEntry({
+  id: "coderifts-contract-gate",
+  name: "CodeRifts contract gate",
+  register(api) {
+    // api.pluginConfig, NOT api.config. Measured: `api.config` is the whole OpenClaw config
+    // snapshot; ours is `plugins.entries.<id>.config`. Reading the wrong one is silent — apiKey
+    // would simply never be found, and the gate would run unkeyed forever while looking configured.
+    const gate = createGate(api.pluginConfig ?? {});
+    api.on(
+      "before_tool_call",
+      async (event) => {
+        try {
+          return await gate(event);
+        } catch (err) {
+          // Never throw out of the handler. The host would turn this into an opaque tool failure;
+          // an approval request with a reason is the same safety with a readable cause.
+          return {
+            requireApproval: {
+              title: "CodeRifts gate failed",
+              description:
+                `The contract gate raised an error before it could reach a decision ` +
+                `(${String(err?.message ?? err)}). Not knowing is not permission.`,
+              severity: "warning",
+              timeoutBehavior: "deny",
+            },
+          };
+        }
+      },
+      { priority: 100 },
+    );
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "coderifts-contract-gate",
+  "name": "CodeRifts contract gate",
+  "description": "Ask CodeRifts before an agent writes a contract artifact.",
+  "version": "0.2.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "CodeRifts API key. WITHOUT IT THE GATE CANNOT OBTAIN A DECISION: the keyless path returns risk information only (authorization_effect NONE, may_execute false), so every gated call falls to approval."
+      },
+      "endpoint": {
+        "type": "string",
+        "description": "CodeRifts MCP endpoint. Default https://app.coderifts.com/mcp"
+      },
+      "timeoutMs": {
+        "type": "number",
+        "description": "Budget for the CodeRifts call. Default 5000. Keep it well under the host's 15000ms before_tool_call budget so a slow answer becomes a named approval request rather than an opaque host denial."
+      },
+      "operation": {
+        "type": "string",
+        "description": "context.operation sent with the change set. Default tool_call."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@coderifts/agent-hooks",
+  "version": "0.2.0",
+  "description": "Ask CodeRifts before an agent writes a contract artifact (OpenClaw before_tool_call and Claude Code PreToolUse).",
+  "license": "MIT",
+  "homepage": "https://github.com/coderifts/agent-hooks#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coderifts/agent-hooks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/coderifts/agent-hooks/issues"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "files": [
+    "index.js",
+    "gate.js",
+    "openclaw.plugin.json",
+    "README.md",
+    "CHANGELOG.md",
+    "claude-code/hook.mjs",
+    "claude-code/settings.snippet.json",
+    "claude-code/marketplace-entry.json",
+    "hooks/hooks.json",
+    ".claude-plugin/plugin.json"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.6.35"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": ["./index.js"],
+    "compat": {
+      "pluginApi": ">=2026.6.35"
+    },
+    "build": {
+      "openclawVersion": "2026.6.35"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}