baldart 4.86.0 → 4.88.0

package/src/utils/hooks/codex.js

@@ -0,0 +1,360 @@
+/**
+ * Codex hook renderer for `.codex/hooks.json`.
+ *
+ * Sibling of `./claude.js`: same runtime-neutral registry (`./registry.js`),
+ * same call sites (add/update/doctor), a different on-disk target. Codex uses
+ * the SAME hooks schema as Claude Code — verified against the OpenAI Codex
+ * hooks spec (CLI 0.142.5):
+ *
+ *   { "hooks": { "<Event>": [ { "matcher": "<regex?>",
+ *                               "hooks": [ { "type": "command", "command": "…" } ] } ] } }
+ *
+ * Two structural differences drive this renderer:
+ *   1. **No per-entry `id`.** Codex addresses hooks by position and trusts them
+ *      by content hash, and its (Rust/serde) deserializer is unforgiving of
+ *      unknown fields — so we DO NOT stamp an `id` on our entries. Ownership is
+ *      matched by a stable command substring (`def.marker`) instead.
+ *   2. **Hook trust.** A new or changed hook is skipped until the user approves
+ *      it; the approval is recorded in `~/.codex/config.toml` as
+ *      `[hooks.state."<hooks.json abspath>:<event_snake>:<entryIdx>:<hookIdx>"]`
+ *      with a `trusted_hash`. BALDART NEVER writes that trust (faking it would
+ *      defeat the security model) — it only *reads* it so `doctor` can report
+ *      "configured but not trusted" separately from "missing".
+ *
+ * Additive by contract: entries we don't own (Graphify's `graphify hook-check`,
+ * user hooks) are preserved verbatim, in place. We only append our own entries
+ * and reconcile drift on entries carrying our marker.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { defsFor } = require('./registry');
+
+const HOOKS_FILE = path.join('.codex', 'hooks.json');
+
+/** The Codex-runtime hook definitions: `{ id, order, event, matcher?, command, marker }`. */
+const CODEX_HOOKS = defsFor('codex');
+
+// ---------------------------------------------------------------------------
+// hooks.json I/O
+// ---------------------------------------------------------------------------
+
+function hooksPath(cwd = process.cwd()) {
+  return path.join(cwd, HOOKS_FILE);
+}
+
+function readHooks(cwd = process.cwd()) {
+  const full = hooksPath(cwd);
+  if (!fs.existsSync(full)) return { path: full, doc: null, malformed: false };
+  try {
+    const raw = fs.readFileSync(full, 'utf8');
+    if (!raw.trim()) return { path: full, doc: {}, malformed: false };
+    return { path: full, doc: JSON.parse(raw), malformed: false };
+  } catch (_) {
+    return { path: full, doc: null, malformed: true };
+  }
+}
+
+function writeHooks(hooksJsonPath, doc) {
+  fs.mkdirSync(path.dirname(hooksJsonPath), { recursive: true });
+  fs.writeFileSync(hooksJsonPath, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Ownership (by command marker — Codex entries carry no id)
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the first entry/hook pair in `eventList` whose command contains
+ * `def.marker` (our stable ownership substring). Returns index coordinates so
+ * the trust key can be computed. `null` when not registered.
+ */
+function findOwnedEntry(eventList, def) {
+  if (!Array.isArray(eventList)) return null;
+  for (let i = 0; i < eventList.length; i++) {
+    const entry = eventList[i];
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (let j = 0; j < entry.hooks.length; j++) {
+      const h = entry.hooks[j];
+      if (!h || h.type !== 'command' || typeof h.command !== 'string') continue;
+      if (h.command.includes(def.marker)) {
+        return { entryIdx: i, hookIdx: j, entry, hook: h };
+      }
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Trust probe (~/.codex/config.toml)
+// ---------------------------------------------------------------------------
+
+function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+
+/** camelCase event (`PreToolUse`) → snake_case trust-key segment (`pre_tool_use`). */
+function eventSnake(event) {
+  return String(event)
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+/**
+ * Parse `~/.codex/config.toml` and return the Set of `[hooks.state."<key>"]`
+ * keys that carry a `trusted_hash`. Dependency-free (no TOML lib — same
+ * hand-parse posture as codex-agent-transpiler.js). Best-effort: any read/parse
+ * problem yields an empty set (→ "not trusted", the safe report).
+ */
+function readTrustedKeys() {
+  const cfg = path.join(codexHome(), 'config.toml');
+  let raw;
+  try { raw = fs.readFileSync(cfg, 'utf8'); } catch (_) { return new Set(); }
+  const trusted = new Set();
+  // Split into TOML table sections at every line starting with `[`.
+  const lines = raw.split('\n');
+  let curKey = null;
+  let sawHash = false;
+  const flush = () => { if (curKey && sawHash) trusted.add(curKey); };
+  for (const line of lines) {
+    const header = line.match(/^\s*\[hooks\.state\."(.+?)"\]\s*$/);
+    if (header) { flush(); curKey = header[1]; sawHash = false; continue; }
+    if (/^\s*\[/.test(line)) { flush(); curKey = null; sawHash = false; continue; }
+    if (curKey && /^\s*trusted_hash\s*=/.test(line)) sawHash = true;
+  }
+  flush();
+  return trusted;
+}
+
+/** Trust key Codex uses for a hook at a given position in a given hooks.json. */
+function trustKey(hooksJsonAbsPath, event, entryIdx, hookIdx) {
+  return `${hooksJsonAbsPath}:${eventSnake(event)}:${entryIdx}:${hookIdx}`;
+}
+
+// ---------------------------------------------------------------------------
+// Status
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} CodexHookStatus
+ * @property {string} id
+ * @property {string} event
+ * @property {boolean} registered  present (by marker) in .codex/hooks.json
+ * @property {boolean} drift       registered but command differs from expected
+ * @property {boolean} trusted     a trusted_hash entry exists for its position key
+ * @property {string} expected
+ * @property {string} [actual]
+ */
+
+/**
+ * Status of every Codex hook. Pure read. `trusted` reflects presence of a
+ * trust entry at the hook's position key — it does NOT re-verify the hash
+ * (Codex's hash algorithm is unspecified), so a drifted hook may still read
+ * `trusted: true` from a stale entry. `doctor` surfaces this as best-effort.
+ *
+ * @returns {{ malformed: boolean, path: string, hooks: CodexHookStatus[] }}
+ */
+function getStatus(cwd = process.cwd()) {
+  const { path: hooksJsonPath, doc, malformed } = readHooks(cwd);
+  if (malformed) return { malformed: true, path: hooksJsonPath, hooks: [] };
+  const abs = path.resolve(hooksJsonPath);
+  const allHooks = (doc && doc.hooks) || {};
+  const trustedKeys = readTrustedKeys();
+  const hooks = CODEX_HOOKS.map((def) => {
+    const found = findOwnedEntry(allHooks[def.event], def);
+    if (!found) {
+      return { id: def.id, event: def.event, registered: false, drift: false, trusted: false, expected: def.command };
+    }
+    const actual = found.hook.command;
+    const key = trustKey(abs, def.event, found.entryIdx, found.hookIdx);
+    return {
+      id: def.id, event: def.event,
+      registered: true,
+      drift: actual !== def.command,
+      trusted: trustedKeys.has(key),
+      expected: def.command,
+      actual,
+    };
+  });
+  return { malformed: false, path: hooksJsonPath, hooks };
+}
+
+// ---------------------------------------------------------------------------
+// Register (additive, drift-aware, preserves foreign entries)
+// ---------------------------------------------------------------------------
+
+/**
+ * Idempotently register every Codex hook. Foreign entries (Graphify, user
+ * hooks) are never touched. Mirrors `claude.js#registerAll`'s return shape.
+ *
+ * @param {string} [cwd]
+ * @param {{ onDrift?: (info) => Promise<'keep'|'replace'>|('keep'|'replace') }} [options]
+ */
+async function registerAll(cwd = process.cwd(), options = {}) {
+  const onDrift = typeof options.onDrift === 'function' ? options.onDrift : () => 'keep';
+
+  const { path: hooksJsonPath, doc: existing, malformed } = readHooks(cwd);
+  if (malformed) {
+    return { malformed: true, path: hooksJsonPath, created: false, updated: false, results: [] };
+  }
+
+  const wasNew = !existing;
+  const doc = existing && typeof existing === 'object' ? structuredClone(existing) : {};
+  doc.hooks = doc.hooks && typeof doc.hooks === 'object' ? doc.hooks : {};
+
+  const results = [];
+  let modified = false;
+
+  for (const def of CODEX_HOOKS) {
+    const list = Array.isArray(doc.hooks[def.event]) ? doc.hooks[def.event] : [];
+    const found = findOwnedEntry(list, def);
+
+    if (!found) {
+      const entry = { hooks: [{ type: 'command', command: def.command }] };
+      if (def.matcher) entry.matcher = def.matcher;
+      list.push(entry);
+      doc.hooks[def.event] = list;
+      results.push({ id: def.id, status: 'created' });
+      modified = true;
+      continue;
+    }
+
+    if (found.hook.command === def.command) {
+      results.push({ id: def.id, status: 'already' });
+      continue;
+    }
+
+    const decision = await onDrift({
+      id: def.id, event: def.event, matcher: def.matcher,
+      expected: def.command, actual: found.hook.command,
+    });
+    if (decision === 'replace') {
+      const previousCommand = found.hook.command;
+      found.hook.command = def.command;
+      results.push({ id: def.id, status: 'drift-replaced', previousCommand });
+      modified = true;
+    } else {
+      results.push({ id: def.id, status: 'drift-kept', previousCommand: found.hook.command });
+    }
+  }
+
+  if (modified) writeHooks(hooksJsonPath, doc);
+  return {
+    malformed: false, path: hooksJsonPath,
+    created: modified && wasNew, updated: modified && !wasNew, results,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Unregister
+// ---------------------------------------------------------------------------
+
+function unregisterAll(cwd = process.cwd()) {
+  const { path: hooksJsonPath, doc, malformed } = readHooks(cwd);
+  if (malformed || !doc || !doc.hooks) {
+    return { malformed, path: hooksJsonPath, results: CODEX_HOOKS.map((d) => ({ id: d.id, status: 'not-found' })) };
+  }
+  const next = structuredClone(doc);
+  const results = [];
+  let modified = false;
+
+  for (const def of CODEX_HOOKS) {
+    const list = Array.isArray(next.hooks[def.event]) ? next.hooks[def.event] : null;
+    if (!list) { results.push({ id: def.id, status: 'not-found' }); continue; }
+    let removed = false;
+    const filtered = list
+      .map((entry) => {
+        if (!entry || !Array.isArray(entry.hooks)) return entry;
+        const innerKept = entry.hooks.filter((h) => {
+          if (h && h.type === 'command' && typeof h.command === 'string' && h.command.includes(def.marker)) {
+            removed = true; return false;
+          }
+          return true;
+        });
+        if (innerKept.length === 0) return null;
+        return { ...entry, hooks: innerKept };
+      })
+      .filter(Boolean);
+
+    if (removed) {
+      if (filtered.length === 0) delete next.hooks[def.event];
+      else next.hooks[def.event] = filtered;
+      modified = true;
+      results.push({ id: def.id, status: 'removed' });
+    } else {
+      results.push({ id: def.id, status: 'not-found' });
+    }
+  }
+
+  if (next.hooks && Object.keys(next.hooks).length === 0) delete next.hooks;
+  if (modified) writeHooks(hooksJsonPath, next);
+  return { malformed: false, path: hooksJsonPath, results };
+}
+
+// ---------------------------------------------------------------------------
+// Verify
+// ---------------------------------------------------------------------------
+
+/**
+ * Confirms every Codex hook is present (by marker) in `.codex/hooks.json`.
+ * Trust is intentionally NOT part of `ok` — a hook can be correctly configured
+ * yet awaiting the user's one-time Codex trust approval, which BALDART cannot
+ * perform. `untrusted` is reported separately for `doctor` to surface.
+ *
+ * @returns {{ ok: boolean, malformed: boolean, missing: string[], untrusted: string[], path: string }}
+ */
+function verifyAll(cwd = process.cwd()) {
+  const status = getStatus(cwd);
+  if (status.malformed) {
+    return { ok: false, malformed: true, missing: CODEX_HOOKS.map((d) => d.id), untrusted: [], path: status.path };
+  }
+  const missing = status.hooks.filter((h) => !h.registered).map((h) => h.id);
+  const untrusted = status.hooks.filter((h) => h.registered && !h.trusted).map((h) => h.id);
+  return { ok: missing.length === 0, malformed: false, missing, untrusted, path: status.path };
+}
+
+// ---------------------------------------------------------------------------
+// Drift prompt (mirrors claude.js so add/update/doctor can reuse it verbatim)
+// ---------------------------------------------------------------------------
+
+function createDriftPrompt(UI, { autoYes = false } = {}) {
+  if (autoYes) {
+    return async ({ id }) => {
+      UI.warning(`Codex hook drift for \`${id}\` — keeping current command (auto mode). Run \`baldart doctor\` interactively to resolve.`);
+      return 'keep';
+    };
+  }
+  const truncate = (s, n = 70) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+  return async function onDrift({ id, event, expected, actual }) {
+    UI.warning(`Codex hook \`${id}\` (${event}) is registered with a non-default command.`);
+    for (;;) {
+      const choice = await UI.select(
+        `What do you want to do with \`${id}\` in .codex/hooks.json?`,
+        [
+          { name: `Keep current        — leave: ${truncate(actual)}`,   value: 'keep' },
+          { name: `Replace with BALDART — set:  ${truncate(expected)}`, value: 'replace' },
+          { name: `Show full diff and decide`,                          value: 'diff' },
+        ],
+      );
+      if (choice !== 'diff') return choice;
+      console.log(`  expected: ${expected}`);
+      console.log(`  actual:   ${actual}`);
+    }
+  };
+}
+
+module.exports = {
+  HOOKS_FILE,
+  CODEX_HOOKS,
+  hooksPath,
+  getStatus,
+  verifyAll,
+  registerAll,
+  unregisterAll,
+  createDriftPrompt,
+  readTrustedKeys,
+  trustKey,
+  eventSnake,
+};

package/src/utils/hooks/registry.js

@@ -0,0 +1,176 @@
+/**
+ * Runtime-neutral hook registry — S1 (hook-registry split) of the BALDART
+ * cross-tool Codex-parity foundation.
+ *
+ * BALDART ships a small set of *logical* hooks (framework-edit-gate,
+ * agent-discovery-gate, agent-discovery-info, overlay-telemetry). Each logical
+ * hook has a stable, runtime-independent identity (`id`, `order`, `purpose`)
+ * and one binding per runtime that can express it.
+ *
+ *   - **Claude Code** binds via `.claude/settings.json` PreToolUse / SessionStart
+ *     / PostToolUse entries (see `runtimes.claude`).
+ *   - **Codex** binds via `.codex/hooks.json` events (`runtimes.codex`); a hook
+ *     with no `codex` binding is simply not registered on Codex — the renderer
+ *     iterates `defsFor('codex')`, which skips it. Codex uses the SAME hooks
+ *     schema as Claude (`{ hooks: { <Event>: [{ matcher, hooks: [{type,command}] }] } }`,
+ *     verified against the OpenAI Codex hooks spec, CLI 0.142.5) but a DIFFERENT
+ *     event/tool vocabulary (`apply_patch` not `Edit|Write`, session-scoped
+ *     `SessionStart`, no observable `Read`/`Agent` tool) and NO per-entry `id`
+ *     (hooks are addressed by position + trusted by content hash) — so a Codex
+ *     binding carries a `marker` (a stable command substring) for ownership
+ *     matching instead of relying on an `id` field.
+ *
+ * This module is the SINGLE SOURCE of the hook set. Renderers
+ * (`hooks/claude.js`, later `hooks/codex.js`) consume `defsFor(runtime)` and
+ * own only the settings-file schema + I/O for their runtime. Adding a hook is
+ * one entry here; wiring a new runtime is one renderer + one `runtimes.<name>`
+ * binding — never a change to the call sites in add/update/doctor.
+ *
+ * The projection `defsFor('claude')` returns the exact flat shape the Claude
+ * renderer expected before the split (`{ id, order, event, matcher, command,
+ * legacyMatch? }`), so the Claude code path — and its `.claude/settings.json`
+ * output — is byte-for-byte unchanged.
+ */
+
+/**
+ * @typedef {Object} ClaudeBinding
+ * @property {string} event        Claude Code event (`PreToolUse`, `Stop`, `SessionStart`, `PostToolUse`, …)
+ * @property {string} matcher      tool-name regex, or '*' for matcherless events
+ * @property {string} command      shell command Claude Code runs
+ * @property {string} [legacyMatch] substring identifying pre-v3.18 single-hook entries to migrate
+ *
+ * @typedef {Object} CodexBinding
+ * @property {string} event           Codex hook event (`PreToolUse`, `SessionStart`, `PostToolUse`, `Stop`, …)
+ * @property {string} [matcher]       tool/command matcher when the event takes one (omit for matcherless events)
+ * @property {string} command         shell command Codex runs
+ * @property {string} marker          stable command substring identifying BALDART ownership (Codex entries carry no `id`)
+ *
+ * @typedef {Object} HookDef
+ * @property {string} id            stable marker stored in the runtime's settings under the entry
+ * @property {number} order         ascending sort key among BALDART hooks on the same event
+ * @property {string} purpose       one-line human description (docs / doctor labels)
+ * @property {{ claude?: ClaudeBinding, codex?: CodexBinding }} runtimes  per-runtime bindings
+ */
+
+/** @type {HookDef[]} */
+const HOOK_REGISTRY = [
+  {
+    id: 'baldart-framework-edit-gate',
+    order: 100,
+    purpose: 'Block edits/writes that resolve inside .framework/ and carry project-specific contamination.',
+    runtimes: {
+      claude: {
+        event: 'PreToolUse',
+        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+        command: 'node .framework/framework/.claude/hooks/framework-edit-gate.js',
+        legacyMatch: 'framework-edit-gate.js',
+      },
+      // Same script, Codex PreToolUse. Codex normalizes file edits to the
+      // `apply_patch` tool (matcher still accepts Edit|Write), and the script
+      // is runtime-aware (parses the apply_patch envelope). The deny format
+      // (`hookSpecificOutput.permissionDecision`) is identical across runtimes.
+      codex: {
+        event: 'PreToolUse',
+        matcher: 'Edit|Write|apply_patch',
+        command: 'node .framework/framework/.claude/hooks/framework-edit-gate.js',
+        marker: 'framework-edit-gate.js',
+      },
+    },
+  },
+  {
+    // Denies `Agent` tool calls whose subagent_type matches a BALDART agent
+    // name but the consumer's .claude/agents/<name>.md is missing or its
+    // symlink is broken. Mitigates anthropics/claude-code#56869 (silent
+    // sub-agent fallback) and #20931 (broken file-based discovery) for the
+    // filesystem-detectable subset.
+    id: 'baldart-agent-discovery-gate',
+    order: 200,
+    purpose: 'Deny Agent spawns naming a BALDART agent whose definition is missing (no silent fallback).',
+    runtimes: {
+      claude: {
+        event: 'PreToolUse',
+        matcher: 'Agent',
+        command: 'node .framework/framework/.claude/hooks/agent-discovery-gate.js',
+      },
+      // No Codex binding (deliberate): Codex spawns subagents BY NAME, not via
+      // an observable `Agent` PreToolUse tool, and its `SubagentStart` event is
+      // session-scoped with unconfirmed deny semantics. The no-silent-fallback
+      // guarantee is instead enforced Codex-side by the skill preflight (the
+      // /new + /prd Codex runtime modules validate `.codex/agents/<name>.toml`
+      // presence before spawning). See framework/docs/CODEX-HOOKS.md.
+    },
+  },
+  {
+    // Injects an additionalContext warning at session start listing BALDART
+    // agents whose .claude/agents/<name>.md is missing. Best-effort early
+    // signal (Claude Code #10373 may suppress injection on new
+    // conversations) — the blocking counterpart is agent-discovery-gate.
+    id: 'baldart-agent-discovery-info',
+    order: 100,
+    purpose: 'Session-start warning listing BALDART agents whose definition is missing.',
+    runtimes: {
+      claude: {
+        event: 'SessionStart',
+        matcher: '*',
+        command: 'bash .framework/framework/.claude/hooks/agent-discovery-info.sh',
+      },
+      // Codex also has a session-scoped SessionStart event that supports
+      // `additionalContext` injection. Same script, but told to inspect the
+      // Codex agent directory (.codex/agents/*.toml) via --runtime codex.
+      codex: {
+        event: 'SessionStart',
+        command: 'bash .framework/framework/.claude/hooks/agent-discovery-info.sh --runtime codex',
+        marker: 'agent-discovery-info.sh',
+      },
+    },
+  },
+  {
+    // Observation-only telemetry: records every Read of a
+    // `.baldart/overlays/*.md` file to `.baldart/telemetry/overlay-loads.jsonl`.
+    // Measures, objectively, whether skill overlays are actually loaded at
+    // runtime (skill overlays use runtime-concat, which is NOT structurally
+    // enforced — unlike agent/command overlays, which are compile-time merged).
+    // Numerator-only by design: skill invocation is prompt-expansion, not a
+    // tool call, so the denominator is not hook-observable (claude-code #43630,
+    // #22655). bash, not node — it fires on EVERY Read (hottest tool) in the
+    // critical path, so a per-read node cold-start would tax every file read.
+    // Fail-safe — never blocks. See framework/docs/OVERLAY-TELEMETRY.md.
+    id: 'baldart-overlay-telemetry',
+    order: 100,
+    purpose: 'Record every Read of a .baldart/overlays/*.md file (overlay-load telemetry).',
+    runtimes: {
+      claude: {
+        event: 'PostToolUse',
+        matcher: 'Read',
+        command: 'bash .framework/framework/.claude/hooks/overlay-telemetry.sh',
+      },
+      // No Codex binding (deliberate): Codex exposes no reliable file-Read tool
+      // event to hook on (its PreToolUse/PostToolUse matcher surface covers
+      // Bash/apply_patch/Edit/Write/MCP, not a `Read`). Overlay-load telemetry
+      // is observation-only and Claude-only for now. See CODEX-HOOKS.md.
+    },
+  },
+  // Future hooks are appended here as one neutral entry with per-runtime bindings.
+];
+
+/**
+ * Project the neutral registry onto one runtime's flat def shape.
+ *
+ * Returns only the hooks that declare a binding for `runtime`, each flattened
+ * to `{ id, order, ...binding }` — the exact shape a renderer's register /
+ * status / verify loop iterates. Hooks with no binding for `runtime` are
+ * skipped (they are simply unsupported there).
+ *
+ * @param {'claude'|'codex'} runtime
+ * @returns {Array<{ id: string, order: number } & (ClaudeBinding|CodexBinding)>}
+ */
+function defsFor(runtime) {
+  return HOOK_REGISTRY
+    .filter((h) => h.runtimes && h.runtimes[runtime])
+    .map((h) => ({ id: h.id, order: h.order, ...h.runtimes[runtime] }));
+}
+
+module.exports = {
+  HOOK_REGISTRY,
+  defsFor,
+};