heyspex 0.1.0 → 0.2.0

package/scripts/claude-hooks/protected-action-intent.mjs

@@ -0,0 +1,221 @@
+// scripts/claude-hooks/protected-action-intent.mjs
+//
+// HS-H8KI-P3TJ (epic HS-GG01-P3TJ): before ANY destructive git command can
+// even get an ASK from git-stash-gate.mjs's runGitDestructiveGate, a written
+// protected-action intent must exist naming the command, what it could break,
+// and which other agents currently hold claims — measured from the claims
+// system (the console's live peer_agents shape), never from agent memory.
+//
+// This module is pure read/validate — no stdout, no process.exit — so it can
+// be unit-tested by import (protected-action-intent.test.mjs) with fixtures
+// written to temp dirs, never the real .heyspex/. git-stash-gate.mjs wires
+// these functions into runGitDestructiveGate.
+//
+// Schema (.heyspex/protected-action-intent.json):
+//   { command, expected_breakage, peers, claim_spec_id, written_at }
+// - valid for INTENT_TTL_MS (10 minutes) from written_at
+// - single-use: consumeIntent() renames it after a decision is reached
+//   (ask OR deny both count as "a decision" — a denied attempt must not let a
+//   later, different command ride the same stale-but-still-fresh intent file)
+// - `peers` MUST be shaped like the claims API's live peer_agents response
+//   (vendor/heyspex-mcp/peer-presence.mjs buildPeerAgentsBlock): an array of
+//   objects, each at least { agent: string, session: string, spec_ids: array }
+//   (extra fields — stage, last_active, files_touched, dirs, dirs_more — are
+//   allowed and passed through untouched, never required).
+// - `command` must match, verbatim (trimmed), the command actually being
+//   gated — an intent written for one command is not license for a different
+//   one, even a same-verb one.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const INTENT_FILE_NAME = 'protected-action-intent.json';
+export const CONSUMED_FILE_NAME = 'protected-action-intent.consumed.json';
+export const INTENT_TTL_MS = 10 * 60 * 1000; // 10 minutes
+export const REQUIRED_FIELDS = ['command', 'expected_breakage', 'peers', 'claim_spec_id', 'written_at'];
+// A written_at more than this far in the future is not a legitimate intent
+// (clock skew tolerance, not a loophole) — it can never itself be "fresh"
+// under the TTL check since nowMs - writtenAtMs would be negative.
+const FUTURE_SKEW_TOLERANCE_MS = 60_000;
+
+export function intentPath(root) {
+  return path.join(root, '.heyspex', INTENT_FILE_NAME);
+}
+
+export function consumedIntentPath(root) {
+  return path.join(root, '.heyspex', CONSUMED_FILE_NAME);
+}
+
+/**
+ * True when `peers` is shaped like the console claims API's live peer_agents
+ * response: an array (possibly empty — "no other live sessions" is a
+ * legitimate, checked result) of objects each carrying at least
+ * `agent` (non-empty string), `session` (non-empty string), and `spec_ids`
+ * (array). Exported for tests.
+ */
+export function isValidPeersShape(peers) {
+  if (!Array.isArray(peers)) return false;
+  return peers.every(
+    (p) =>
+      p !== null &&
+      typeof p === 'object' &&
+      !Array.isArray(p) &&
+      typeof p.agent === 'string' &&
+      p.agent.trim().length > 0 &&
+      typeof p.session === 'string' &&
+      p.session.trim().length > 0 &&
+      Array.isArray(p.spec_ids),
+  );
+}
+
+/**
+ * Validate one parsed intent object's shape + freshness (does NOT check it
+ * against a specific command being run — see readAndValidateIntent for that).
+ * Returns `{ ok: true, intent }` or `{ ok: false, reason }`. Exported for tests.
+ */
+export function validateIntent(intent, { nowMs = Date.now() } = {}) {
+  if (!intent || typeof intent !== 'object' || Array.isArray(intent)) {
+    return { ok: false, reason: 'intent is not an object' };
+  }
+
+  const missing = REQUIRED_FIELDS.filter((f) => !(f in intent));
+  if (missing.length > 0) {
+    return { ok: false, reason: `missing required field(s): ${missing.join(', ')}` };
+  }
+
+  if (typeof intent.command !== 'string' || !intent.command.trim()) {
+    return { ok: false, reason: '"command" must be a non-empty string' };
+  }
+  if (typeof intent.expected_breakage !== 'string' || !intent.expected_breakage.trim()) {
+    return { ok: false, reason: '"expected_breakage" must be a non-empty string' };
+  }
+  if (typeof intent.claim_spec_id !== 'string' || !intent.claim_spec_id.trim()) {
+    return { ok: false, reason: '"claim_spec_id" must be a non-empty string' };
+  }
+  if (typeof intent.written_at !== 'string' || !intent.written_at.trim()) {
+    return { ok: false, reason: '"written_at" must be an ISO timestamp string' };
+  }
+
+  const writtenAtMs = Date.parse(intent.written_at);
+  if (Number.isNaN(writtenAtMs)) {
+    return { ok: false, reason: '"written_at" is not a parseable timestamp' };
+  }
+  if (writtenAtMs > nowMs + FUTURE_SKEW_TOLERANCE_MS) {
+    return { ok: false, reason: '"written_at" is in the future' };
+  }
+  const ageMs = nowMs - writtenAtMs;
+  if (ageMs > INTENT_TTL_MS) {
+    return {
+      ok: false,
+      reason: `intent is stale — written ${Math.round(ageMs / 1000)}s ago, valid for ${INTENT_TTL_MS / 60_000} minutes`,
+    };
+  }
+
+  if (!isValidPeersShape(intent.peers)) {
+    return {
+      ok: false,
+      reason:
+        '"peers" must be an array shaped like the claims API\'s live peer_agents response ' +
+        '(each item: { agent: string, session: string, spec_ids: array, ... }) — absent, ' +
+        'not-an-array, or missing/mis-typed fields on any item are all rejected',
+    };
+  }
+
+  return { ok: true, intent };
+}
+
+/**
+ * Exact-match (trimmed) comparison between the intent's recorded command and
+ * the command actually being gated. Deliberately strict — an intent written
+ * for one command is not license for a different one. Exported for tests.
+ */
+export function commandMatches(intentCommand, actualCommand) {
+  if (typeof intentCommand !== 'string' || typeof actualCommand !== 'string') return false;
+  return intentCommand.trim() === actualCommand.trim() && intentCommand.trim().length > 0;
+}
+
+/**
+ * Read + fully validate the on-disk intent file against the command actually
+ * being gated. Returns `{ ok: true, intent }` or `{ ok: false, reason }`.
+ * Never throws — a missing/corrupt/unreadable file is just "no intent", with
+ * `reason` saying why.
+ */
+export function readAndValidateIntent({ root, command, nowMs = Date.now() }) {
+  let raw;
+  try {
+    raw = fs.readFileSync(intentPath(root), 'utf8');
+  } catch {
+    return { ok: false, reason: 'no intent file found' };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: 'intent file is not valid JSON' };
+  }
+
+  const validated = validateIntent(parsed, { nowMs });
+  if (!validated.ok) return validated;
+
+  if (!commandMatches(validated.intent.command, command)) {
+    return {
+      ok: false,
+      reason: `intent's "command" does not match the command being run (intent names: "${validated.intent.command}")`,
+    };
+  }
+
+  return { ok: true, intent: validated.intent };
+}
+
+/**
+ * Single-use: rename the intent file after a decision is reached (ask OR
+ * deny) so it can never be read again for a subsequent gated command.
+ * Best-effort — a rename failure never blocks the gate's own decision (the
+ * decision has already been made by the time this runs); returns a boolean
+ * so callers/tests can observe it without it ever throwing.
+ */
+export function consumeIntent(root) {
+  try {
+    fs.renameSync(intentPath(root), consumedIntentPath(root));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Denial message for AC1 — names the intent file path and every required field. */
+export function buildNoIntentDenyMessage({ root, reason }) {
+  return (
+    `DENIED — no valid protected-action intent (${reason}). This git command is a PROTECTED action ` +
+    `(protected-shared-actions-gate) and, per HS-H8KI, cannot even be ASKED about without a fresh, ` +
+    `written breakage assessment. Write ${intentPath(root)} first, with these required fields: ` +
+    `${REQUIRED_FIELDS.join(', ')}. "peers" must be the LIVE peer_agents result from the claims API ` +
+    `(the same shape the MCP tools print as PEER AGENTS — array of { agent, session, spec_ids, ... }), ` +
+    `never recalled from memory. "written_at" is an ISO timestamp; the intent is valid for ` +
+    `${INTENT_TTL_MS / 60_000} minutes and single-use. "command" must exactly match the command you ` +
+    `are about to run.`
+  );
+}
+
+/** Ask message for AC2 — surfaces the expected_breakage text and the peer list from the intent. */
+export function buildIntentAskMessage({ intent, baseReason }) {
+  return (
+    `${baseReason} A written protected-action intent is on file (HS-H8KI): expected breakage — ` +
+    `"${intent.expected_breakage}". Peers at claim time (from the claims API, claim_spec_id ` +
+    `${intent.claim_spec_id}): ${JSON.stringify(intent.peers)}. Approving IS the permission.`
+  );
+}
+
+/** Deny message for AC3 — cites the orchestrator's sub-agent lock. */
+export function buildLockDenyMessage(lock) {
+  const who = lock && typeof lock.setBy === 'string' && lock.setBy.trim() ? ` by ${lock.setBy}` : '';
+  const reason = lock && typeof lock.reason === 'string' && lock.reason.trim() ? ` — ${lock.reason}` : '';
+  return (
+    `DENIED — a sub-agent hard lock is set on this session${who}${reason} ` +
+    `(scripts/lib/subagent-git-lock.mjs, orchestrator rule: destructive git is barred for the ` +
+    `duration of delegated sub-agent work). No intent file can override an active lock — deny is ` +
+    `stronger than ask. The orchestrator clears the lock (clearSubagentLock()) when its delegated ` +
+    `work window ends.`
+  );
+}

package/scripts/claude-hooks/research-method-guard.mjs

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+// research-method-guard.mjs — PreToolUse hook that structurally blocks the
+// built-in Claude Code `deep-research-quick|medium|thorough` skills/workflows
+// from firing in this repo. HeySpex's own research method is `/hs-res`
+// (dev-factory/spexcrawl/{spexcrawl-cli,firecrawl-cli,synthesize-cli}.mjs
+// — SpexCrawl via the Companion + Firecrawl-as-permission-only-fallback for
+// gather, DeepSeek for synthesis). Sonnet is a fallback that requires the
+// user's explicit per-run permission granted directly in the current chat,
+// never a silent default ([[research-routing-hard-rule-sonnet]]).
+//
+// The rule already existed TWICE in prose — `.commandcode/skills/hs-res/
+// SKILL.md` "## Hard prohibitions" and the research-routing-hard-rule-sonnet
+// memory decision — and a Claude Code session still called
+// `Skill({ skill: "deep-research-medium" })` → `Workflow(...)` under time
+// pressure. Prose alone does not stop a wrong tool call; this hook does.
+//
+// What is blocked:
+//   - `Skill` calls whose `skill` input is EXACTLY one of deep-research-quick /
+//     deep-research-medium / deep-research-thorough.
+//   - `Workflow` calls whose `name` input is one of those three strings, OR
+//     whose `scriptPath` input CONTAINS one of those three strings as a
+//     substring (catches `.claude/workflows/deep-research-thorough.js` etc,
+//     any launch directory prefix).
+// What is allowed: everything else — `Skill(hs-res)`, any other skill name,
+//   any Workflow launch that doesn't name one of the three forbidden
+//   profiles, and every non-Skill/Workflow tool.
+//
+// This guard is DELIBERATELY narrower and stricter than the pre-existing
+// deep-research-cost-gate.mjs (same `Skill|Workflow` matcher): that gate
+// treats a deep-research launch as costly-but-permittable and only ASKs for
+// approval (plus a grounding check) — it never actually stops the built-in
+// profiles from running once approved. The rule in hs-res/SKILL.md and
+// research-routing-hard-rule-sonnet is "never fall back to these", not "ask
+// first" — so this hook denies outright, no ask, no cost table.
+//
+// Env: HEYSPEX_RESEARCH_GUARD_OFF=1  kill switch — never blocks. An ENV VAR,
+// not a file, mirroring env-vault-guard's HEYSPEX_ENV_VAULT_GUARD_OFF — a
+// file an agent can write is a disarm chain.
+// Stdin: Claude Code hook JSON ({tool_name, tool_input, ...}).
+// Exit 0 = allow. Exit 2 = block (stderr surfaces back to the model) — same
+// mechanism as env-vault-guard.mjs.
+// FAIL-SAFE: any internal error → exit 0 (house style: never strand the agent).
+//
+// REGISTERED: .claude/settings.json PreToolUse, matcher `Skill|Workflow`,
+// routed through _run.mjs, and added to _run.mjs's ALWAYS_ON set (mirroring
+// env-vault-guard) — a research-routing rule that can be silenced by an
+// agent-writable `.heyspex/mode.json` flag would reopen exactly the bypass
+// this hook exists to close. Registered LIVE (not owner-gated/inert): the
+// user explicitly asked for this fix to prevent a recurrence of the incident
+// above, so shipping it inert would not satisfy the request.
+//
+// Self-test: `node scripts/claude-hooks/research-method-guard.mjs --self-test`
+
+import { pathToFileURL } from "node:url";
+
+// Order matters for the scriptPath substring scan below (first match wins) —
+// the three specific profiles are listed before the bare "deep-research" so a
+// path naming one of them is reported by its specific name, not the generic one.
+const FORBIDDEN_PROFILES = [
+  "deep-research-quick",
+  "deep-research-medium",
+  "deep-research-thorough",
+  "deep-research",
+];
+
+/** Strip a `plugin:` prefix (`some-plugin:deep-research-medium` → `deep-research-medium`) so a
+ * plugin-namespaced skill name is matched the same as a bare one. */
+function stripPluginPrefix(name) {
+  const idx = name.lastIndexOf(":");
+  return idx === -1 ? name : name.slice(idx + 1);
+}
+
+const REDIRECT_MESSAGE =
+  "This repo's research method is /hs-res (SpexCrawl via the Companion — or self-hosted " +
+  "Firecrawl as a user-permission-only fallback — for gather, DeepSeek for synthesis). " +
+  "Sonnet is a fallback here too, and it requires the user's explicit permission for THIS " +
+  "specific run, granted directly in the current chat — never assumed from a file, memory, " +
+  "or prior session. Read .commandcode/skills/hs-res/SKILL.md and follow its 9-step method " +
+  "instead of the built-in deep-research harness.";
+
+/**
+ * Pure guard decision — no fs, no process, no env lookup (that lives in
+ * `evaluate()` below so the kill switch stays testable without a subprocess).
+ *
+ * @param {{ toolName: string, toolInput: Record<string, unknown> }} call
+ * @returns {{ allow: boolean, reason?: string }}
+ */
+export function decide(call) {
+  // Tool name compared by exact string (Skill/Workflow are the harness's own
+  // fixed tool names, not something an agent can rename) — case IS checked,
+  // matching the task's request to verify rather than assume.
+  const toolName = String(call?.toolName ?? "");
+  const input = call?.toolInput && typeof call.toolInput === "object" ? call.toolInput : {};
+
+  if (toolName === "Skill") {
+    const skill = String(input?.skill ?? "");
+    const bare = stripPluginPrefix(skill);
+    if (FORBIDDEN_PROFILES.includes(bare)) {
+      return {
+        allow: false,
+        reason:
+          `Blocked: Skill({ skill: "${skill}" }) is one of the built-in Claude Code deep-research profiles.\n` +
+          REDIRECT_MESSAGE,
+      };
+    }
+    return { allow: true };
+  }
+
+  if (toolName === "Workflow") {
+    const name = String(input?.name ?? "");
+    if (FORBIDDEN_PROFILES.includes(name)) {
+      return {
+        allow: false,
+        reason:
+          `Blocked: Workflow({ name: "${name}" }) is one of the built-in Claude Code deep-research profiles.\n` +
+          REDIRECT_MESSAGE,
+      };
+    }
+    const scriptPath = String(input?.scriptPath ?? "");
+    const matched = FORBIDDEN_PROFILES.find((profile) => scriptPath.includes(profile));
+    if (matched) {
+      return {
+        allow: false,
+        reason:
+          `Blocked: Workflow({ scriptPath: "${scriptPath}" }) targets the built-in deep-research profile "${matched}".\n` +
+          REDIRECT_MESSAGE,
+      };
+    }
+    return { allow: true };
+  }
+
+  return { allow: true };
+}
+
+/**
+ * `decide()` plus the kill switch, so the switch is covered by the same
+ * fixture table as the guard logic instead of needing a subprocess spawn.
+ * @param {{ tool_name?: string, tool_input?: Record<string, unknown> }} payload
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function evaluate(payload, env) {
+  if ((env ?? {}).HEYSPEX_RESEARCH_GUARD_OFF === "1") return { allow: true };
+  return decide({ toolName: payload?.tool_name, toolInput: payload?.tool_input ?? {} });
+}
+
+// ---------------------------------------------------------------------------
+
+async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  let buf = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) buf += chunk;
+  if (!buf.trim()) return null;
+  try {
+    return JSON.parse(buf);
+  } catch {
+    return null;
+  }
+}
+
+const SELF_TEST_CASES = [
+  // --- Skill: forbidden profiles → block --------------------------------
+  {
+    tag: "skill-block",
+    name: 'Skill(skill: "deep-research-quick") → block',
+    call: { toolName: "Skill", toolInput: { skill: "deep-research-quick" } },
+    want: false,
+  },
+  {
+    tag: "skill-block",
+    name: 'Skill(skill: "deep-research-medium") → block',
+    call: { toolName: "Skill", toolInput: { skill: "deep-research-medium" } },
+    want: false,
+  },
+  {
+    tag: "skill-block",
+    name: 'Skill(skill: "deep-research-thorough") → block',
+    call: { toolName: "Skill", toolInput: { skill: "deep-research-thorough" } },
+    want: false,
+  },
+  // --- Workflow name: forbidden profiles → block -------------------------
+  {
+    tag: "workflow-name-block",
+    name: 'Workflow(name: "deep-research-quick") → block',
+    call: { toolName: "Workflow", toolInput: { name: "deep-research-quick" } },
+    want: false,
+  },
+  {
+    tag: "workflow-name-block",
+    name: 'Workflow(name: "deep-research-medium") → block',
+    call: { toolName: "Workflow", toolInput: { name: "deep-research-medium" } },
+    want: false,
+  },
+  {
+    tag: "workflow-name-block",
+    name: 'Workflow(name: "deep-research-thorough") → block',
+    call: { toolName: "Workflow", toolInput: { name: "deep-research-thorough" } },
+    want: false,
+  },
+  // --- Workflow scriptPath: forbidden profiles as substring → block ------
+  {
+    tag: "workflow-scriptpath-block",
+    name: "Workflow(scriptPath: .../deep-research-quick.js) → block",
+    call: {
+      toolName: "Workflow",
+      toolInput: { scriptPath: ".claude/workflows/deep-research-quick.js", args: "q" },
+    },
+    want: false,
+  },
+  {
+    tag: "workflow-scriptpath-block",
+    name: "Workflow(scriptPath: .../deep-research-medium.js) → block",
+    call: {
+      toolName: "Workflow",
+      toolInput: { scriptPath: ".claude/workflows/deep-research-medium.js", args: "q" },
+    },
+    want: false,
+  },
+  {
+    tag: "workflow-scriptpath-block",
+    name: "Workflow(scriptPath: .../deep-research-thorough.js) → block",
+    call: {
+      toolName: "Workflow",
+      toolInput: { scriptPath: ".claude/workflows/deep-research-thorough.js", args: "q" },
+    },
+    want: false,
+  },
+  // --- Bare "deep-research" and plugin-prefixed names → block ------------
+  {
+    tag: "skill-block",
+    name: 'Skill(skill: "deep-research") (bare profile) → block',
+    call: { toolName: "Skill", toolInput: { skill: "deep-research" } },
+    want: false,
+  },
+  {
+    tag: "skill-block",
+    name: 'Skill(skill: "some-plugin:deep-research-medium") (plugin-prefixed) → block',
+    call: { toolName: "Skill", toolInput: { skill: "some-plugin:deep-research-medium" } },
+    want: false,
+  },
+  // --- Negative controls: the real /hs-res path and unrelated calls ------
+  {
+    tag: "allow",
+    name: "Skill(skill: hs-res) → allow (the real method)",
+    call: { toolName: "Skill", toolInput: { skill: "hs-res" } },
+    want: true,
+  },
+  {
+    tag: "allow",
+    name: "Skill with an unrelated skill name → allow",
+    call: { toolName: "Skill", toolInput: { skill: "prototype" } },
+    want: true,
+  },
+  {
+    tag: "allow",
+    name: "Workflow with an unrelated name → allow",
+    call: { toolName: "Workflow", toolInput: { name: "some-other-workflow" } },
+    want: true,
+  },
+  {
+    tag: "allow",
+    name: "Workflow with an unrelated scriptPath → allow",
+    call: {
+      toolName: "Workflow",
+      toolInput: { scriptPath: ".claude/workflows/some-other-workflow.js" },
+    },
+    want: true,
+  },
+  {
+    tag: "allow",
+    name: "Workflow with neither name nor scriptPath → allow (nothing to match)",
+    call: { toolName: "Workflow", toolInput: { args: "q" } },
+    want: true,
+  },
+  // --- Unrelated tools pass through untouched -----------------------------
+  {
+    tag: "allow-unrelated-tool",
+    name: "Read tool → allow",
+    call: { toolName: "Read", toolInput: { file_path: "C:/dev-projects/workflow-protocol/README.md" } },
+    want: true,
+  },
+  {
+    tag: "allow-unrelated-tool",
+    name: "Bash tool → allow",
+    call: { toolName: "Bash", toolInput: { command: "npm test" } },
+    want: true,
+  },
+  {
+    tag: "allow-unrelated-tool",
+    name: "Edit tool → allow",
+    call: { toolName: "Edit", toolInput: { file_path: "foo.mjs", old_string: "a", new_string: "b" } },
+    want: true,
+  },
+  // --- Case sensitivity is deliberate: a differently-cased name is NOT a
+  // known forbidden profile string, so it is not matched here. ------------
+  {
+    tag: "case-sensitivity",
+    name: 'Skill(skill: "Deep-Research-Medium") (different case) → allow (exact-match only)',
+    call: { toolName: "Skill", toolInput: { skill: "Deep-Research-Medium" } },
+    want: true,
+  },
+  // --- Malformed / empty input → fail-safe allow --------------------------
+  {
+    tag: "fail-safe",
+    name: "Skill with no skill field → allow",
+    call: { toolName: "Skill", toolInput: {} },
+    want: true,
+  },
+  {
+    tag: "fail-safe",
+    name: "missing toolInput entirely → allow",
+    call: { toolName: "Skill" },
+    want: true,
+  },
+];
+
+// Kill-switch cases run through `evaluate()` (payload + env), not `decide()`.
+const KILL_SWITCH_CASES = [
+  {
+    name: "kill switch ON: Skill(deep-research-medium) → allow (HEYSPEX_RESEARCH_GUARD_OFF=1)",
+    payload: { tool_name: "Skill", tool_input: { skill: "deep-research-medium" } },
+    env: { HEYSPEX_RESEARCH_GUARD_OFF: "1" },
+    want: true,
+  },
+  {
+    name: "kill switch OFF: Skill(deep-research-medium) → block (no env var)",
+    payload: { tool_name: "Skill", tool_input: { skill: "deep-research-medium" } },
+    env: {},
+    want: false,
+  },
+  {
+    name: 'kill switch value "0" does NOT disarm → block',
+    payload: { tool_name: "Skill", tool_input: { skill: "deep-research-medium" } },
+    env: { HEYSPEX_RESEARCH_GUARD_OFF: "0" },
+    want: false,
+  },
+];
+
+function selfTest() {
+  let failed = 0;
+  let total = 0;
+
+  for (const c of SELF_TEST_CASES) {
+    total += 1;
+    const got = decide(c.call);
+    const ok = got.allow === c.want;
+    if (!ok) failed += 1;
+    process.stdout.write(
+      `${ok ? "ok  " : "FAIL"}  [${c.tag}] ${c.name}` +
+        `${ok ? "" : ` → got allow=${got.allow} want=${c.want}`}\n`,
+    );
+  }
+
+  for (const c of KILL_SWITCH_CASES) {
+    total += 1;
+    const got = evaluate(c.payload, c.env);
+    const ok = got.allow === c.want;
+    if (!ok) failed += 1;
+    process.stdout.write(
+      `${ok ? "ok  " : "FAIL"}  [kill-switch] ${c.name}` +
+        `${ok ? "" : ` → got allow=${got.allow} want=${c.want}`}\n`,
+    );
+  }
+
+  process.stdout.write(
+    failed === 0
+      ? `\nresearch-method-guard self-test: ${total} passed\n`
+      : `\n${failed}/${total} FAILED\n`,
+  );
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+async function main() {
+  if (process.argv.includes("--self-test")) return selfTest();
+
+  const payload = await readStdinJson();
+  if (!payload) return;
+  if (payload.hook_event_name && payload.hook_event_name !== "PreToolUse") return;
+
+  const verdict = evaluate(payload, process.env);
+  if (!verdict.allow) {
+    process.stderr.write(`\n[HeySpex research-method guard]\n${verdict.reason}\n`);
+    process.exit(2);
+  }
+}
+
+// Only run the hook entrypoint (including its stdin read) when this file is
+// executed directly — mirrors env-vault-guard.mjs's guard so importing this
+// module (e.g. from a future regression test) never blocks on stdin.
+const isDirectExecution =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectExecution) {
+  main().catch(() => {
+    // Fail-open: never block legitimate work on a hook crash.
+    process.exit(0);
+  });
+}

package/scripts/claude-hooks/research-protocol-gate.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// GENERATED by scripts/generate-hook-shells.mjs (HS-IQBF) — do not hand-edit.
+// This file only wires Claude Code's hook stdin/stdout contract to the
+// spexharness engine port of this gate. To change what this gate DECIDES,
+// edit spexharness/src/gates/research-protocol-gate.mjs. To change the SHAPE of this shell,
+// edit the generator, then rerun: node scripts/generate-hook-shells.mjs
+
+import { runGateAsHook } from '../../spexharness/src/adapters/claude-code.mjs';
+import gate from '../../spexharness/src/gates/research-protocol-gate.mjs';
+
+await runGateAsHook(gate);