heyspex 0.1.0 → 0.2.1

package/scripts/claude-hooks/_run.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+// _run.mjs — the single chokepoint every HeySpex Claude Code hook runs through.
+//
+// `.claude/settings.json` never names a hook script directly. It names this
+// shim plus the hook to run:
+//
+//   node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs" wip-checkpoint
+//   node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/_run.mjs" emit-claim-status --event=Stop
+//
+// The shim asks one question — is HeySpex on? — and either exits 0 immediately
+// or hands off to the real hook. One place to reason about, and a hook added
+// tomorrow inherits the off-switch for free.
+//
+// Delegation is a dynamic `import()` in THIS process, not a subprocess, so the
+// hook still owns stdin (Claude Code pipes the event payload there) and still
+// sets this process's exit code. `process.argv` is rewritten first so a hook
+// reading `--event=Stop` sees exactly what it saw before the shim existed.
+//
+// Everything here is fail-open. A shim that throws must never take down a
+// Claude Code session, and it must never be the reason a guardrail silently
+// stops firing — so an unresolvable mode reads as ON, and a genuinely broken
+// hook path reports on stderr and exits 0.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const STATE_DIR = '.' + 'heyspex';
+const HOOK_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HOOK_DIR, '..', '..');
+
+const [target, ...rest] = process.argv.slice(2);
+
+if (!target) {
+  process.stderr.write('[heyspex] _run.mjs: no hook name given\n');
+  process.exit(0);
+}
+
+/**
+ * Resolve the hook to run.
+ *   `wip-checkpoint`               → scripts/claude-hooks/wip-checkpoint.mjs
+ *   `scripts/stamp-provenance.mjs` → <repo>/scripts/stamp-provenance.mjs
+ *
+ * A bare name is constrained to a safe charset and must land inside the hook
+ * directory; a path form is resolved from the repo root and must stay inside
+ * it. Both guards exist so a mangled settings.json can't turn the shim into an
+ * arbitrary-script runner.
+ */
+function resolveHook(name) {
+  const abs = name.includes('/') || name.includes('\\')
+    ? path.resolve(REPO_ROOT, name)
+    : /^[A-Za-z0-9._-]+$/.test(name)
+      ? path.join(HOOK_DIR, name.endsWith('.mjs') ? name : `${name}.mjs`)
+      : null;
+  if (!abs) return null;
+  const inRepo = path.relative(REPO_ROOT, abs);
+  if (inRepo.startsWith('..') || path.isAbsolute(inRepo)) return null;
+  return abs;
+}
+
+// --- the off-switch: see modeOffFromProject() below (project-scoped; must agree with heyspex-mode.mjs resolution order:
+// HEYSPEX_MODE env first, then <project>/.heyspex/mode.json).
+
+// --- hooks the off-switch may NOT silence ---------------------------------
+// The productivity hooks (reminders, injections, checkpoints) exist to help,
+// so a global "HeySpex is off" is the right answer for them. A SECURITY
+// control is different: the mode is decided by a repo file (.heyspex/mode.json)
+// that any agent can write, and nothing guards that file — so sharing the
+// off-switch would mean "write one JSON file, disarm the guard forever"
+// (the disarm chain, C8). Anything named here runs regardless of mode.
+// Each always-on hook keeps its OWN documented escape hatch, and it must be
+// an ENV VAR (HEYSPEX_ENV_VAULT_GUARD_OFF=1 for env-vault-guard;
+// HEYSPEX_RESEARCH_GUARD_OFF=1 for research-method-guard) — a human setting a
+// variable for their session, not a file an agent can create.
+// research-protocol-gate ([[HS-K0ZP]]) joins the set for the same reason as
+// research-method-guard: its whole point is that the agent cannot switch it
+// off. Escape hatch: HEYSPEX_RESEARCH_PROTOCOL_GATE_OFF=1, owner-set, env only.
+// git-identity-guard (owner ruling 2026-09-19, vault lesson
+// when-git-says-author-identity-unknown) has NO escape hatch at all — not
+// even an env var: the owner's own path is `hs source identity set`, typed by
+// a human, so there is nothing a hatch would enable that the sanctioned form
+// does not already do. Agents read git identity; they never write it.
+const ALWAYS_ON = new Set(['env-vault-guard', 'research-method-guard', 'research-protocol-gate', 'git-identity-guard']);
+
+function isAlwaysOn(name) {
+  const base = String(name)
+    .replace(/^.*[\\/]/, '')
+    .replace(/\.mjs$/i, '');
+  return ALWAYS_ON.has(base);
+}
+
+// ── project roots the mode file may live in ─────────────────────────────────
+// `hs mode off` writes <project>/.heyspex/mode.json. In a customer repo whose hooks come from the plugin /
+// node_modules, REPO_ROOT is the package, not the project, so the dev's switch was ignored. Look in the PROJECT
+// first: CLAUDE_PROJECT_DIR, then the hook payload's cwd, then walk up from process.cwd(); REPO_ROOT stays the
+// last resort. HEYSPEX_MODE (env) keeps precedence over every file.
+function projectRoots(payload) {
+  const roots = [];
+  const add = (r) => {
+    if (typeof r === 'string' && r.trim() && !roots.includes(r.trim())) roots.push(r.trim());
+  };
+  add(process.env.CLAUDE_PROJECT_DIR);
+  add(payload?.cwd);
+  try {
+    let d = process.cwd();
+    for (;;) {
+      if (fs.existsSync(path.join(d, '.heyspex', 'mode.json'))) {
+        add(d);
+        break;
+      }
+      const up = path.dirname(d);
+      if (up === d) break;
+      d = up;
+    }
+  } catch { /* ignore */ }
+  add(REPO_ROOT);
+  return roots;
+}
+
+function modeOffFromProject(payload) {
+  try {
+    const raw = String(process.env.HEYSPEX_MODE ?? '').trim().toLowerCase();
+    if (raw) return ['off', '0', 'false', 'disabled', 'disable', 'no'].includes(raw);
+    for (const root of projectRoots(payload)) {
+      const file = path.join(root, '.heyspex', 'mode.json');
+      if (!fs.existsSync(file)) continue;
+      // ANY root saying off wins: the dev's `hs mode off` lives in the project, an older switch in the platform root.
+      if (JSON.parse(fs.readFileSync(file, 'utf8'))?.mode === 'off') return true;
+    }
+  } catch { /* fail-open: on */ }
+  return false;
+}
+
+// ── fail-open, outermost ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]) ─────────────
+// GitHub Copilot turns ANY non-zero hook exit into a deny (and 2 is always a deny with the reason lost), so a
+// crash anywhere - resolution, import, a hook's own async throw - must exit 0. Exit 2 survives only where a hook
+// truly decided "deny" (Claude Code: stderr reason; Copilot: translated to the JSON deny below).
+process.on('uncaughtException', (err) => {
+  try { process.stderr.write(`[heyspex] hook ${target} crashed (failing open): ${err?.message ?? err}\n`); } catch { /* ignore */ }
+  process.exit(0);
+});
+process.on('unhandledRejection', (err) => {
+  try { process.stderr.write(`[heyspex] hook ${target} rejected (failing open): ${err?.message ?? err}\n`); } catch { /* ignore */ }
+  process.exit(0);
+});
+process.on('exit', (code) => {
+  if (code !== 0 && code !== 2) process.exitCode = 0;
+});
+
+function readAll(stream, ms) {
+  return new Promise((resolve) => {
+    let buf = '';
+    const t = setTimeout(() => resolve(buf), ms);
+    t.unref?.();
+    stream.setEncoding('utf8');
+    stream.on('data', (c) => { buf += c; });
+    stream.on('end', () => { clearTimeout(t); resolve(buf); });
+    stream.on('error', () => resolve(buf));
+  });
+}
+
+// ── Copilot helpers (all best-effort; every failure means "run the hook normally") ─────────────────────────────
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// The command text after the shim: `node -e "<bootstrap>" hook [args]` or `node ".../run-hook.mjs" hook [args]`.
+function rowTokens(command) {
+  const c = String(command ?? '');
+  const m = c.match(/^node -e "[^"]*"\s+([\s\S]*)$/) || c.match(/\.mjs"?\s+([\s\S]*)$/);
+  return m ? m[1].trim().split(/\s+/) : [];
+}
+
+/**
+ * The matcher(s) registered for this hook + event, read from the project's Claude settings file and the plugin's
+ * hooks.json. A hook may sit under several matchers; ALL are returned (an unset matcher is ''). null = the hook
+ * is in no row we can read, so no filtering.
+ */
+function matchersForHook(eventName, payload) {
+  const files = [];
+  for (const r of projectRoots(payload)) files.push(path.join(r, '.claude', 'settings.json'));
+  for (const r of [process.env.CLAUDE_PLUGIN_ROOT, process.env.COPILOT_PLUGIN_ROOT, process.env.PLUGIN_ROOT]) {
+    if (r && r.trim()) files.push(path.join(r.trim(), 'hooks', 'hooks.json'));
+  }
+  files.push(path.join(REPO_ROOT, 'plugins', 'heyspex', 'hooks', 'hooks.json'));
+  const want = [target, ...rest].join(' ');
+  const matchers = [];
+  let found = false;
+  for (const file of [...new Set(files)]) {
+    const groups = readJson(file)?.hooks?.[eventName];
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) {
+      for (const h of g?.hooks ?? []) {
+        const t = rowTokens(h?.command);
+        if (t.length && t.join(' ') === want) { found = true; matchers.push(typeof g.matcher === 'string' ? g.matcher : ''); }
+      }
+    }
+  }
+  return found ? matchers : null;
+}
+
+const DEDUPE_WINDOW_MS = 2000;
+
+/**
+ * Double-firing guard. The first run of a key atomically creates a stamp (flag 'wx'); a second run inside 2 s is
+ * a duplicate. The first run stores its final stdout in the stamp so a duplicate replays a DENY instead of
+ * silently allowing. Keyed by (session, event, hook+args, tool, timestamp | input hash, project).
+ */
+function claimDedupe(payload, eventName) {
+  const none = { duplicate: false };
+  try {
+    if (String(process.env.HEYSPEX_COPILOT_DEDUPE_OFF ?? '').trim() === '1') return none;
+    const session = payload.session_id ?? payload.sessionId;
+    if (typeof session !== 'string' || !session) return none;
+    const ident = payload.timestamp !== undefined
+      ? String(payload.timestamp)
+      : crypto.createHash('sha1').update(JSON.stringify([payload.tool_input ?? null, payload.prompt ?? null])).digest('hex');
+    const key = crypto.createHash('sha1')
+      .update(JSON.stringify([session, eventName, target, rest, payload.tool_name ?? '', ident, payload.cwd ?? '']))
+      .digest('hex');
+    const dir = process.env.HEYSPEX_COPILOT_DEDUPE_DIR?.trim() || path.join(os.tmpdir(), 'heyspex-copilot-dedupe');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${key}.json`);
+    const now = Date.now();
+    try {
+      fs.writeFileSync(file, JSON.stringify({ t: now, out: '' }), { flag: 'wx' });
+    } catch (e) {
+      if (e?.code !== 'EEXIST') return none;
+      const prev = readJson(file);
+      if (prev && typeof prev.t === 'number' && now - prev.t >= 0 && now - prev.t < DEDUPE_WINDOW_MS) {
+        return { duplicate: true, replay: typeof prev.out === 'string' ? prev.out : '' };
+      }
+      fs.writeFileSync(file, JSON.stringify({ t: now, out: '' })); // stale stamp: this run owns it
+    }
+    try { // opportunistic cleanup of old stamps
+      for (const f of fs.readdirSync(dir)) {
+        const fp = path.join(dir, f);
+        if (now - fs.statSync(fp).mtimeMs > 60000) fs.rmSync(fp, { force: true });
+      }
+    } catch { /* ignore */ }
+    return { duplicate: false, store: (final) => { if (final) fs.writeFileSync(file, JSON.stringify({ t: now, out: final })); } };
+  } catch {
+    return none;
+  }
+}
+
+/** True exactly once per (project, session): creates <project>/<state dir>/copilot-style-<session>.stamp. */
+function claimSessionStyleStamp(payload) {
+  try {
+    const session = String(payload.session_id ?? payload.sessionId ?? '').replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
+    if (!session) return false;
+    const root = projectRoots(payload).find((r) => { try { return fs.statSync(r).isDirectory(); } catch { return false; } });
+    if (!root) return false;
+    const dir = path.join(root, STATE_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    try { fs.writeFileSync(path.join(dir, `copilot-style-${session}.stamp`), new Date().toISOString(), { flag: 'wx' }); } catch { return false; }
+    try { // drop stamps older than a week
+      for (const f of fs.readdirSync(dir)) {
+        if (f.startsWith('copilot-style-') && f.endsWith('.stamp') && Date.now() - fs.statSync(path.join(dir, f)).mtimeMs > 7 * 86400000) fs.rmSync(path.join(dir, f), { force: true });
+      }
+    } catch { /* ignore */ }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  // stdin is read ONCE here (harness detection and the mode file's project root both need the payload) and
+  // handed on to the hook as a fresh stream, so every hook still reads process.stdin exactly as before.
+  let text = '';
+  try {
+    if (!process.stdin.isTTY) text = await readAll(process.stdin, 4000);
+  } catch { /* ignore */ }
+  let payload = null;
+  try { payload = text.trim() ? JSON.parse(text) : null; } catch { payload = null; }
+
+  if (!isAlwaysOn(target) && modeOffFromProject(payload)) process.exit(0);
+
+  // ── harness detection + the Copilot dialect ──────────────────────────────
+  let harness = 'unknown';
+  let copilot = null;
+  try {
+    const { detectHarness } = await import(pathToFileURL(path.join(REPO_ROOT, 'spexharness', 'src', 'adapters', 'detect-harness.mjs')).href);
+    harness = detectHarness(payload, process.env);
+  } catch { /* no adapter in this install: behave exactly as Claude Code */ }
+
+  if (harness === 'copilot') {
+    try {
+      copilot = await import(pathToFileURL(path.join(REPO_ROOT, 'spexharness', 'src', 'adapters', 'copilot.mjs')).href);
+    } catch {
+      // Copilot denies on exit 2 and on any crash, and without the adapter we cannot speak its dialect: fail OPEN.
+      process.stderr.write(`[heyspex] hook ${target}: Copilot adapter unavailable (failing open)\n`);
+      process.exit(0);
+    }
+  }
+  if (copilot) await copilotBranch(copilot);
+
+  // ── the Copilot branch ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]) ──────────────────────
+  // Everything below runs ONLY when the harness is GitHub Copilot. Guarantees for Copilot, whatever fails:
+  //   * the process exits 0 (Copilot turns ANY non-zero exit into a deny, and 2 loses the reason);
+  //   * stdout is empty (allow) or ONE valid JSON object (a gate's own decision) - never partial / malformed text;
+  //   * a crash, a throwing hook, an unhandled rejection or a bad import is an ALLOW (the _run.mjs handlers above
+  //     exit 0; the exit hook below translates the buffered output).
+  // Behaviors, in order:
+  //   1. opt-out: HEYSPEX_COPILOT_HOOKS_OFF=1 / config agent_behaviors.harness_hooks.copilot.enabled: false
+  //      silences every hook except the ALWAYS_ON security gates.
+  //   2. normalize the payload (camelCase or PascalCase, MCP tool-name spellings -> mcp__heyspex__*).
+  //   3. script-side tool filter: the VS Code Local harness ignores matchers and fires every hook on every tool,
+  //      so the matcher of the registered row (.claude/settings.json or the plugin hooks.json) is re-applied here.
+  //   4. double-firing guard: Copilot CLI loads hooks from the plugin AND .claude/settings.json; a duplicate
+  //      (same session, event, hook, tool, timestamp) inside 2 s exits 0 (replaying a stored decision, if any).
+  //   5. prompt-time context: Copilot DROPS UserPromptSubmit output, so a context-only result prints nothing
+  //      there. SessionStart accepts additionalContext, so ONCE PER SESSION (stamp file under the project's
+  //      state dir) the SessionStart run also emits inject-communication-style's static text as additionalContext.
+  async function copilotBranch(copilot) {
+    if (!isAlwaysOn(target)) {
+      let off = String(process.env.HEYSPEX_COPILOT_HOOKS_OFF ?? '').trim() === '1';
+      if (!off) {
+        try {
+          const { isConfigKeyEnabled } = await import(pathToFileURL(path.join(HOOK_DIR, '_guardrail-loader.mjs')).href);
+          off = !isConfigKeyEnabled('agent_behaviors.harness_hooks.copilot.enabled');
+        } catch { /* config unreadable: stay on */ }
+      }
+      if (off) process.exit(0);
+    }
+    payload = copilot.normalizeCopilotPayload(payload);
+    text = JSON.stringify(payload);
+    const eventName = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : '';
+
+    // (3) script-side tool filter
+    let skip = false;
+    try {
+      if (eventName && typeof payload.tool_name === 'string') {
+        const matchers = matchersForHook(eventName, payload);
+        skip = !!matchers && !copilot.toolMatchesAnyMatcher(matchers, copilot.toolNameCandidates(payload));
+      }
+    } catch { /* lookup failure: run the hook */ }
+    if (skip) process.exit(0);
+
+    // (4) double-firing guard
+    const dedupe = claimDedupe(payload, eventName);
+    if (dedupe.duplicate) {
+      if (dedupe.replay) { try { fs.writeSync(1, dedupe.replay); } catch { /* ignore */ } }
+      process.exit(0);
+    }
+
+    // (5) once-per-session static advisory at SessionStart
+    let extraContext = '';
+    if (eventName === 'SessionStart' && claimSessionStyleStamp(payload)) {
+      try {
+        const mod = await import(pathToFileURL(path.join(HOOK_DIR, 'inject-communication-style.mjs')).href);
+        extraContext = typeof mod.copilotSessionStartText === 'function' ? await mod.copilotSessionStartText() : '';
+      } catch { /* advisory only */ }
+    }
+
+    // Copilot reads ONE top-level {permissionDecision, permissionDecisionReason}; buffer stdout/stderr and
+    // translate at exit: Claude-dialect JSON -> top-level, and a legacy `exit 2 + stderr` deny -> JSON deny, exit 0.
+    let out = '';
+    let err = '';
+    const realStderr = process.stderr.write.bind(process.stderr);
+    process.stdout.write = (chunk, enc, cb) => { out += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'); if (typeof enc === 'function') enc(); else if (typeof cb === 'function') cb(); return true; };
+    process.stderr.write = (chunk, enc, cb) => { err += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'); if (typeof enc === 'function') enc(); else if (typeof cb === 'function') cb(); return true; };
+    process.on('exit', (code) => {
+      process.exitCode = 0; // Copilot: never non-zero, whatever happened
+      let final = '';
+      try {
+        final = out ? copilot.finalizeCopilotStdout(out, eventName) : '';
+        if (code === 2 && !final) final = copilot.denyFromLegacyExit(err);
+        else if (err && code !== 2) realStderr(err);
+        if (extraContext) final = copilot.mergeAdditionalContext(final, extraContext);
+      } catch { final = ''; }
+      try { dedupe.store?.(final); } catch { /* best effort */ }
+      try { if (final) fs.writeSync(1, final); } catch { /* never let the translation break the hook */ }
+    });
+  }
+
+  // hand the (already read) payload on as a fresh stdin
+  if (!process.stdin.isTTY) {
+    try {
+      const { Readable } = await import('node:stream');
+      const fresh = new Readable({ read() {} });
+      if (text) fresh.push(Buffer.from(text, 'utf8'));
+      fresh.push(null);
+      Object.defineProperty(process, 'stdin', { value: fresh, configurable: true });
+    } catch { /* hooks will see an empty stdin and fail open themselves */ }
+  }
+
+  const hookPath = resolveHook(target);
+  if (!hookPath || !fs.existsSync(hookPath)) {
+    process.stderr.write(`[heyspex] _run.mjs: hook not found: ${target}\n`);
+    process.exit(0);
+  }
+
+  // Make the hook believe it was invoked directly.
+  process.argv = [process.argv[0], hookPath, ...rest];
+
+  try {
+    await import(pathToFileURL(hookPath).href);
+  } catch (err) {
+    process.stderr.write(`[heyspex] hook ${target} failed: ${err?.message ?? err}\n`);
+    process.exit(0);
+  }
+}
+
+try {
+  await main();
+} catch (err) {
+  process.stderr.write(`[heyspex] _run.mjs failed (failing open): ${err?.message ?? err}\n`);
+  process.exit(0);
+}

package/scripts/claude-hooks/_transcript-text.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Shared Stop-hook input helpers: read the hook's stdin JSON payload and pull the
+// agent's own last message out of the transcript JSONL. Split out of
+// naughty-list-gate.mjs (its original sole owner) so a second Stop-hook scanner
+// (id-display-format-gate.mjs) doesn't fork a copy of the same 40 lines.
+//
+// DEPENDENCY-FREE, same contract as _guardrail-loader.mjs: every function degrades
+// to null/'' on any read/parse failure rather than throwing, so a caller's own
+// fail-safe wrapper never has to guard against this module misbehaving.
+
+import fs from 'node:fs';
+
+/** Read and parse the hook's stdin JSON payload. Resolves to null on any failure. */
+export async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(buf || ''), 200);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { buf += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); finish(buf); });
+    process.stdin.on('error', () => { clearTimeout(timer); finish(buf); });
+  });
+}
+
+/** Read the last assistant message's text out of a transcript JSONL file. */
+export function lastAssistantText(transcriptPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = raw.split(/\r?\n/).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let evt;
+    try { evt = JSON.parse(lines[i]); } catch { continue; }
+    const msg = evt?.message;
+    const role = msg?.role ?? evt?.role;
+    if (role !== 'assistant') continue;
+    const content = msg?.content;
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+      const text = content
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('\n')
+        .trim();
+      return text || null;
+    }
+    return null;
+  }
+  return null;
+}