@empirical-gauzza/cli 1.0.12 → 1.0.14

package/lib/installers/hooks.js

@@ -1,550 +1,869 @@
-'use strict';
-
-const os = require('os');
-const path = require('path');
-const { log } = require('../ui');
-const { ensureDir, writeFile, readJsonIfExists } = require('../fsUtils');
-const { normalizePluginNames } = require('./nativePlugin');
-
-const CLAUDE_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var spawnSync = require('child_process').spawnSync;
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-// Diagnostic breadcrumb log: this hook's own stdout is only visible to Claude Code's SessionStart
-// machinery, not to a human debugging "did this actually fire" after the fact. Every run appends
-// one line here (bounded — see trimLogIfLarge) regardless of success/failure, so firing can be
-// verified by checking file growth/timestamps after starting or resuming a session, without
-// depending on server-side analytics that don't currently tag hook-originated calls.
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break session start.
-  }
-}
-
-// On Windows, npm's global "empirical" command is a .cmd shim, and .cmd/.bat files can only be
-// executed via the OS shell (cmd.exe), never as a native process — this is an OS constraint, not
-// a Node quirk. But spawnSync's shell:true path joins argv into a single command-line string for
-// cmd.exe to reparse, and Node does not escape special shell characters (spaces, commas, etc.) in
-// that join for you. A --match value like "project context, conventions, recent decisions, user
-// preferences" gets mangled by that reparse, silently truncating the search query and returning
-// far fewer/worse matches than the same query run without a shell in between. The fix: resolve
-// the shim's REAL target (a plain .js file) and invoke that directly via node.exe with shell:false
-// — node.exe is a true native executable, so no shell/reparsing step exists to mangle args.
-function resolveEmpiricalEntryPoint() {
-  if (process.platform !== 'win32') {
-    // POSIX global installs are usually a symlink straight to the JS entry (or a shebang script)
-    // — spawnSync already runs these directly without a shell, so no mangling risk exists there.
-    return null;
-  }
-  try {
-    // Parse the .cmd shim itself rather than hardcoding an npm package scope: the published
-    // package has already been renamed once (was the empirical scope, now a different scope
-    // entirely - the old one is 404 on the registry), so hardcoding either name is a guaranteed
-    // future break. npm-generated shims all reference their target relative to dp0 (the shim's
-    // own directory) as a node_modules-rooted path ending in bin then a .js file - extracting
-    // that pattern works regardless of what the package is scoped or renamed to.
-    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
-    if (where.status !== 0 || !where.stdout) return null;
-    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
-    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
-    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
-    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
-    if (!match) return null;
-    var candidate = path.join(path.dirname(cmdPath), match[1]);
-    return fs.existsSync(candidate) ? candidate : null;
-  } catch (e) {
-    return null;
-  }
-}
-
-function commandExists(cmd) {
-  var probe = process.platform === 'win32'
-    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
-    : spawnSync('which', [cmd], { stdio: 'ignore' });
-  return probe.status === 0;
-}
-
-function runMemoryQuery(args) {
-  var entryPoint = resolveEmpiricalEntryPoint();
-  if (entryPoint) {
-    appendLog('resolved direct entry point: ' + entryPoint);
-    return spawnSync(process.execPath, [entryPoint].concat(args), {
-      encoding: 'utf8',
-      timeout: 10000,
-      shell: false
-    });
-  }
-
-  // Fallback: could not resolve a direct entry point (non-Windows, or resolution failed) — run
-  // the "empirical" command as before. On POSIX this is shell:false and safe. On Windows this is
-  // shell:true and CAN still mangle args as described above; it only triggers if the direct-entry
-  // resolution above failed, so degraded (not absent) results are the acceptable worst case here.
-  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
-  return spawnSync('empirical', args, {
-    encoding: 'utf8',
-    timeout: 10000,
-    shell: process.platform === 'win32'
-  });
-}
-
-function main() {
-  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-
-  if (!commandExists('empirical')) {
-    appendLog('empirical CLI not found on PATH, exiting');
-    process.exit(0);
-  }
-
-  var result = runMemoryQuery([
-    'memory', 'query',
-    '--match', 'project context, conventions, recent decisions, user preferences',
-    '--top-k', '8'
-  ]);
-
-  if (!result || result.status !== 0 || !result.stdout) {
-    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
-    process.exit(0);
-  }
-
-  var results;
-  try {
-    results = JSON.parse(result.stdout);
-  } catch (e) {
-    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
-    process.exit(0);
-  }
-
-  if (!Array.isArray(results) || results.length === 0) {
-    appendLog('memory query returned zero results');
-    process.exit(0);
-  }
-
-  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
-
-  var lines = results.slice(0, 8).map(function (r) {
-    var category = r && r.category ? r.category : 'memory';
-    var summary = r && r.summary ? r.summary : '';
-    return '- [' + category + '] ' + summary;
-  });
-
-  console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
-  process.exit(0);
-}
-
-main();
-`;
-
-// EMPIRICAL_HOOK_STOP_SOURCE: fires once per assistant turn (Claude: Stop; Codex: Stop, turn-
-// scoped per codex-rs/hooks/src/engine/dispatcher.rs; Copilot: agentStop, "the main agent
-// finishes a turn" per GitHub's own hooks reference). This is the write-side counterpart to the
-// SessionStart hook above (which only covers recall, once per session boundary) - deliberately
-// simple: it does NOT parse the transcript to detect whether memory-worthy activity happened
-// this turn (transcript formats differ across all three platforms and getting that heuristic
-// wrong silently - the exact class of bug this session spent hours finding - is worse than an
-// unconditional reminder). It never calls the empirical CLI and makes no network call, so the
-// "wasteful per-turn hook" concern that killed the old per-turn UserPromptSubmit hook (see
-// installClaudeHooks below) does not apply here - this is a single static stdout write.
-// ALWAYS exits 0: per Claude Code's documented Stop hook contract, exit 2 forces the agent to
-// keep responding (a blocking decision) - a bug in a hook that's supposed to be an informational
-// nudge must never be able to trap a session in a forced-continuation loop, so this is
-// unconditional regardless of any error encountered.
-const EMPIRICAL_HOOK_STOP_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break the hook.
-  }
-}
-
-function readStdinPayload() {
-  try {
-    var raw = fs.readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch (e) {
-    return {};
-  }
-}
-
-function main() {
-  var payload = readStdinPayload();
-
-  // Defensive loop guard: if a Stop hook's own forced-continuation output somehow triggers
-  // another Stop event before the agent produces new output, stop_hook_active (Claude's documented
-  // field name for this) prevents a reminder-print-loop. This hook never sets decision:block
-  // itself, but checking costs nothing and protects against any future change that does.
-  if (payload && payload.stop_hook_active === true) {
-    appendLog('stop_hook_active=true, skipping reminder');
-    process.exit(0);
-  }
-
-  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-
-  console.log('[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.');
-  process.exit(0);
-}
-
-main();
-`;
-
-// Claude-only variant of the Stop reminder above. hookSpecificOutput.additionalContext (stdout,
-// exit 0) is Claude Code's non-blocking Stop-hook feedback channel: the text is fed into context
-// and the conversation continues, same outcome the earlier exit-2 approach achieved, but the
-// transcript UI renders it as a plain system reminder instead of a red "Stop hook error" line.
-// EMPIRICAL_HOOK_STOP_SOURCE above still uses plain console.log + exit 0, which Claude Code treats
-// as non-blocking output that's logged but never reaches the model - that was this hook's original
-// bug (fixed for Claude here, unconfirmed/unfixed for Codex/Copilot's own Stop/agentStop semantics).
-const CLAUDE_HOOK_STOP_SOURCE = `#!/usr/bin/env node
-'use strict';
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break the hook.
-  }
-}
-
-function readStdinPayload() {
-  try {
-    var raw = fs.readFileSync(0, 'utf8');
-    return raw ? JSON.parse(raw) : {};
-  } catch (e) {
-    return {};
-  }
-}
-
-function main() {
-  var payload = readStdinPayload();
-
-  // stop_hook_active === true means Claude is re-invoking this hook because a PRIOR Stop hook
-  // (possibly this same one) already surfaced additionalContext and forced a continuation this
-  // turn. additionalContext causes the same forced-continuation behavior decision:block does -
-  // confirmed empirically: without this guard the hook re-fired every ~2-3s in an infinite loop,
-  // since each additionalContext output triggers another Stop event. Must exit 0 with no output
-  // here, unconditionally, or the loop continues.
-  if (payload && payload.stop_hook_active === true) {
-    appendLog('stop_hook_active=true, skipping reminder (already surfaced once this turn)');
-    process.exit(0);
-  }
-
-  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + '), surfacing reminder via additionalContext');
-
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'Stop',
-      additionalContext: '[Empirical] Record memory-worthy work now via empirical-memory skill.'
-    }
-  }) + '\\n');
-  process.exit(0);
-}
-
-main();
-`;
-
-// UserPromptSubmit: fires before each turn is processed (Claude, Codex, and Copilot all support
-// this event under the same name per each platform's docs/source). This is the recall-side
-// counterpart to Stop's write-side reminder - deliberately a STATIC message, not a live
-// `empirical memory query` call: a prior per-turn hook in this codebase was removed for making an
-// unconditional network call on every single prompt (see the comment above installClaudeHooks),
-// and re-adding that cost here on three platforms at once was an explicit no per product decision.
-// The message itself is generated per-install from the actual plugin set being installed, not one
-// fixed string for everyone - e.g. someone who declined empirical-scar-tissue at install time
-// never sees a scar-tissue reminder, since that capability isn't actually available to them.
-function buildPromptReminderMessage(pluginNames) {
-  const names = normalizePluginNames(pluginNames);
-  const lines = [
-    'Before responding: if this task needs prior context (research, debugging, a spec or status update, a handoff), query Empirical memory first via the empirical-memory skill or empirical memory query - do not assume you already have enough context.'
-  ];
-  if (names.includes('empirical-work-history')) {
-    lines.push('If you are picking up previously completed work, check for a recent work-history entry before assuming there is none.');
-  }
-  if (names.includes('empirical-scar-tissue')) {
-    lines.push('Check for scar tissue before repeating a past mistake in this area.');
-  }
-  if (names.includes('empirical-todo')) {
-    lines.push('If there is an open todo for this project, check it before starting new work.');
-  }
-  return '[Empirical reminder] ' + lines.join(' ');
-}
-
-// Builds the full UserPromptSubmit hook script source with the tailored message baked in at
-// generation time (via JSON.stringify, so the message is embedded as a single already-escaped
-// string literal - substituted through `${}`, not written as raw template-literal source text,
-// which is what caused the earlier comment-escaping bug in this same file. Never do the latter).
-function buildUserPromptSubmitHookSource(pluginNames) {
-  const messageLiteral = JSON.stringify(buildPromptReminderMessage(pluginNames));
-  return `#!/usr/bin/env node
-'use strict';
-
-var fs = require('fs');
-var os = require('os');
-var path = require('path');
-
-var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'user-prompt-submit.log');
-var MAX_LOG_BYTES = 200 * 1024;
-
-function appendLog(line) {
-  try {
-    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
-    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
-    var stat = fs.statSync(LOG_PATH);
-    if (stat.size > MAX_LOG_BYTES) {
-      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
-      fs.writeFileSync(LOG_PATH, tail);
-    }
-  } catch (e) {
-    // Diagnostics must never break the hook.
-  }
-}
-
-appendLog('user-prompt-submit hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
-console.log(${messageLiteral});
-process.exit(0);
-`;
-}
-
-function getEmpiricalHooksDir() {
-  return path.join(os.homedir(), '.empirical', 'hooks');
-}
-
-function buildHookCommand(scriptPath) {
-  return `"${process.execPath}" "${scriptPath}"`;
-}
-
-function removeEmpiricalHookEntries(entries, scriptPath) {
-  if (!Array.isArray(entries)) return [];
-  return entries
-    .map((entry) => {
-      if (!entry || !Array.isArray(entry.hooks)) return entry;
-      const filteredHooks = entry.hooks.filter(
-        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
-      );
-      return { ...entry, hooks: filteredHooks };
-    })
-    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
-}
-
-function installClaudeHooks(pluginNames) {
-  const hooksDir = getEmpiricalHooksDir();
-  ensureDir(hooksDir);
-
-  // A prior version of this hook made an unconditional `empirical memory query` network call on
-  // every single prompt and was removed for being wasteful (see git history). This is a
-  // deliberate reintroduction at the SAME script path, but with fundamentally different content:
-  // a static, install-time-generated reminder with no network call at all - the cost concern that
-  // killed the old version does not apply to a plain stdout write.
-  const userPromptScriptPath = path.join(hooksDir, 'claude-user-prompt-submit.js');
-  const sessionStartScriptPath = path.join(hooksDir, 'claude-session-start.js');
-  const stopScriptPath = path.join(hooksDir, 'claude-stop.js');
-  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
-  writeFile(stopScriptPath, CLAUDE_HOOK_STOP_SOURCE);
-  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
-
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-  const settings = readJsonIfExists(settingsPath) || {};
-  if (!settings.hooks || typeof settings.hooks !== 'object') {
-    settings.hooks = {};
-  }
-
-  settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
-  settings.hooks.UserPromptSubmit.push({
-    hooks: [{ type: 'command', command: buildHookCommand(userPromptScriptPath), timeout: 10 }]
-  });
-
-  settings.hooks.SessionStart = removeEmpiricalHookEntries(settings.hooks.SessionStart, sessionStartScriptPath);
-  for (const matcher of ['startup', 'resume', 'compact']) {
-    settings.hooks.SessionStart.push({
-      matcher,
-      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 15 }]
-    });
-  }
-
-  settings.hooks.Stop = removeEmpiricalHookEntries(settings.hooks.Stop, stopScriptPath);
-  settings.hooks.Stop.push({
-    hooks: [{ type: 'command', command: buildHookCommand(stopScriptPath), timeout: 10 }]
-  });
-
-  writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
-  log('  - Claude SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
-}
-
-// Codex CLI ships a real hooks system (confirmed against openai/codex source — codex-rs/hooks,
-// codex-rs/config/src/hook_config.rs — not assumed from docs alone, since third-party writeups
-// disagreed on Windows support). It reads <CODEX_HOME>/hooks.json (JSON, not the config.toml
-// used for MCP/model settings — a separate file, so this never touches config.toml) shaped as
-// { hooks: { SessionStart: [{ matcher, hooks: [{ type: 'command', command, commandWindows,
-// timeout }] }], ... } }. CODEX_HOME defaults to ~/.codex when unset, same convention as
-// ~/.claude for Claude Code.
-function getCodexHomeDir() {
-  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-}
-
-function removeEmpiricalHooksJsonEntries(entries, scriptPath) {
-  if (!Array.isArray(entries)) return [];
-  return entries
-    .map((entry) => {
-      if (!entry || !Array.isArray(entry.hooks)) return entry;
-      const filteredHooks = entry.hooks.filter(
-        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
-      );
-      return { ...entry, hooks: filteredHooks };
-    })
-    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
-}
-
-function installCodexHooks(pluginNames) {
-  const hooksDir = getEmpiricalHooksDir();
-  ensureDir(hooksDir);
-
-  const sessionStartScriptPath = path.join(hooksDir, 'codex-session-start.js');
-  const stopScriptPath = path.join(hooksDir, 'codex-stop.js');
-  const userPromptScriptPath = path.join(hooksDir, 'codex-user-prompt-submit.js');
-  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
-  writeFile(stopScriptPath, EMPIRICAL_HOOK_STOP_SOURCE);
-  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
-
-  const hooksJsonPath = path.join(getCodexHomeDir(), 'hooks.json');
-  const hooksFile = readJsonIfExists(hooksJsonPath) || {};
-  if (!hooksFile.hooks || typeof hooksFile.hooks !== 'object') {
-    hooksFile.hooks = {};
-  }
-
-  hooksFile.hooks.SessionStart = removeEmpiricalHooksJsonEntries(hooksFile.hooks.SessionStart, sessionStartScriptPath);
-  const sessionStartCommand = buildHookCommand(sessionStartScriptPath);
-  for (const matcher of ['startup', 'resume']) {
-    hooksFile.hooks.SessionStart.push({
-      matcher,
-      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommand, timeout: 15 }]
-    });
-  }
-
-  hooksFile.hooks.Stop = removeEmpiricalHooksJsonEntries(hooksFile.hooks.Stop, stopScriptPath);
-  const stopCommand = buildHookCommand(stopScriptPath);
-  hooksFile.hooks.Stop.push({
-    hooks: [{ type: 'command', command: stopCommand, commandWindows: stopCommand, timeout: 10 }]
-  });
-
-  // Confirmed against codex-rs/config/src/hook_config.rs's HookEventsToml serde renames: the
-  // config-file key is PascalCase "UserPromptSubmit", same casing convention as SessionStart/Stop.
-  hooksFile.hooks.UserPromptSubmit = removeEmpiricalHooksJsonEntries(hooksFile.hooks.UserPromptSubmit, userPromptScriptPath);
-  const userPromptCommand = buildHookCommand(userPromptScriptPath);
-  hooksFile.hooks.UserPromptSubmit.push({
-    hooks: [{ type: 'command', command: userPromptCommand, commandWindows: userPromptCommand, timeout: 10 }]
-  });
-
-  writeFile(hooksJsonPath, `${JSON.stringify(hooksFile, null, 2)}\n`);
-  log('  - Codex SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
-}
-
-// GitHub Copilot CLI's hook config is one JSON file per hook under ~/.copilot/hooks/ (any
-// filename — confirmed via GitHub's own docs at docs.github.com/en/copilot/reference/hooks-
-// reference), so unlike Claude/Codex this never needs to merge into a shared file: Empirical
-// owns this file outright and can just overwrite it. Event key for turn-end is "agentStop"
-// ("the main agent finishes a turn" per the same docs) — not "stop"/"Stop" like Claude/Codex.
-// Schema: { version: 1, hooks: { sessionStart: [...], agentStop: [...] } }.
-function installCopilotHooks(pluginNames) {
-  const hooksDir = getEmpiricalHooksDir();
-  ensureDir(hooksDir);
-
-  const sessionStartScriptPath = path.join(hooksDir, 'copilot-session-start.js');
-  const stopScriptPath = path.join(hooksDir, 'copilot-stop.js');
-  const userPromptScriptPath = path.join(hooksDir, 'copilot-user-prompt-submit.js');
-  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
-  writeFile(stopScriptPath, EMPIRICAL_HOOK_STOP_SOURCE);
-  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
-
-  const copilotHooksDir = path.join(os.homedir(), '.copilot', 'hooks');
-  ensureDir(copilotHooksDir);
-
-  // Prior versions of this installer wrote a single-purpose "empirical-session-start.json" —
-  // remove it now that both events live in one unified file, so a stale duplicate registration
-  // never lingers alongside the new one.
-  const legacyHookFilePath = path.join(copilotHooksDir, 'empirical-session-start.json');
-  try {
-    const fs = require('fs');
-    if (fs.existsSync(legacyHookFilePath)) fs.unlinkSync(legacyHookFilePath);
-  } catch (_error) {
-    // best-effort cleanup only
-  }
-
-  const hookFilePath = path.join(copilotHooksDir, 'empirical-hooks.json');
-  const hookFileContent = {
-    version: 1,
-    hooks: {
-      sessionStart: [
-        { type: 'command', command: buildHookCommand(sessionStartScriptPath), timeoutSec: 15 }
-      ],
-      // "userPromptSubmitted" per GitHub's hooks reference ("The user submits a prompt") - not
-      // "userPromptSubmit" (that camelCase spelling is Claude/Codex's convention, not Copilot's).
-      userPromptSubmitted: [
-        { type: 'command', command: buildHookCommand(userPromptScriptPath), timeoutSec: 10 }
-      ],
-      agentStop: [
-        { type: 'command', command: buildHookCommand(stopScriptPath), timeoutSec: 10 }
-      ]
-    }
-  };
-
-  writeFile(hookFilePath, `${JSON.stringify(hookFileContent, null, 2)}\n`);
-  log('  - Copilot SessionStart + userPromptSubmitted + agentStop hooks installed for deterministic memory lookups and reminders.');
-}
-
-module.exports = {
-  CLAUDE_HOOK_SESSION_START_SOURCE,
-  EMPIRICAL_HOOK_STOP_SOURCE,
-  CLAUDE_HOOK_STOP_SOURCE,
-  buildPromptReminderMessage,
-  buildUserPromptSubmitHookSource,
-  getEmpiricalHooksDir,
-  buildHookCommand,
-  removeEmpiricalHookEntries,
-  installClaudeHooks,
-  getCodexHomeDir,
-  removeEmpiricalHooksJsonEntries,
-  installCodexHooks,
-  installCopilotHooks
-};
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log } = require('../ui');
+const { ensureDir, writeFile, readJsonIfExists } = require('../fsUtils');
+const { normalizePluginNames } = require('./nativePlugin');
+
+const CLAUDE_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var spawnSync = require('child_process').spawnSync;
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+// Diagnostic breadcrumb log: this hook's own stdout is only visible to Claude Code's SessionStart
+// machinery, not to a human debugging "did this actually fire" after the fact. Every run appends
+// one line here (bounded — see trimLogIfLarge) regardless of success/failure, so firing can be
+// verified by checking file growth/timestamps after starting or resuming a session, without
+// depending on server-side analytics that don't currently tag hook-originated calls.
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break session start.
+  }
+}
+
+// On Windows, npm's global "empirical" command is a .cmd shim, and .cmd/.bat files can only be
+// executed via the OS shell (cmd.exe), never as a native process — this is an OS constraint, not
+// a Node quirk. But spawnSync's shell:true path joins argv into a single command-line string for
+// cmd.exe to reparse, and Node does not escape special shell characters (spaces, commas, etc.) in
+// that join for you. A --match value like "project context, conventions, recent decisions, user
+// preferences" gets mangled by that reparse, silently truncating the search query and returning
+// far fewer/worse matches than the same query run without a shell in between. The fix: resolve
+// the shim's REAL target (a plain .js file) and invoke that directly via node.exe with shell:false
+// — node.exe is a true native executable, so no shell/reparsing step exists to mangle args.
+function resolveEmpiricalEntryPoint() {
+  if (process.platform !== 'win32') {
+    // POSIX global installs are usually a symlink straight to the JS entry (or a shebang script)
+    // — spawnSync already runs these directly without a shell, so no mangling risk exists there.
+    return null;
+  }
+  try {
+    // Parse the .cmd shim itself rather than hardcoding an npm package scope: the published
+    // package has already been renamed once (was the empirical scope, now a different scope
+    // entirely - the old one is 404 on the registry), so hardcoding either name is a guaranteed
+    // future break. npm-generated shims all reference their target relative to dp0 (the shim's
+    // own directory) as a node_modules-rooted path ending in bin then a .js file - extracting
+    // that pattern works regardless of what the package is scoped or renamed to.
+    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
+    if (where.status !== 0 || !where.stdout) return null;
+    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
+    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
+    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
+    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
+    if (!match) return null;
+    var candidate = path.join(path.dirname(cmdPath), match[1]);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  var probe = process.platform === 'win32'
+    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
+    : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+function runMemoryQuery(args) {
+  var entryPoint = resolveEmpiricalEntryPoint();
+  if (entryPoint) {
+    appendLog('resolved direct entry point: ' + entryPoint);
+    return spawnSync(process.execPath, [entryPoint].concat(args), {
+      encoding: 'utf8',
+      timeout: 10000,
+      shell: false
+    });
+  }
+
+  // Fallback: could not resolve a direct entry point (non-Windows, or resolution failed) — run
+  // the "empirical" command as before. On POSIX this is shell:false and safe. On Windows this is
+  // shell:true and CAN still mangle args as described above; it only triggers if the direct-entry
+  // resolution above failed, so degraded (not absent) results are the acceptable worst case here.
+  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
+  return spawnSync('empirical', args, {
+    encoding: 'utf8',
+    timeout: 10000,
+    shell: process.platform === 'win32'
+  });
+}
+
+function main() {
+  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  if (!commandExists('empirical')) {
+    appendLog('empirical CLI not found on PATH, exiting');
+    process.exit(0);
+  }
+
+  var result = runMemoryQuery([
+    'memory', 'query',
+    '--match', 'project context, conventions, recent decisions, user preferences',
+    '--top-k', '8'
+  ]);
+
+  if (!result || result.status !== 0 || !result.stdout) {
+    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
+    process.exit(0);
+  }
+
+  var results;
+  try {
+    results = JSON.parse(result.stdout);
+  } catch (e) {
+    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+    process.exit(0);
+  }
+
+  if (!Array.isArray(results) || results.length === 0) {
+    appendLog('memory query returned zero results');
+    process.exit(0);
+  }
+
+  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
+
+  var lines = results.slice(0, 8).map(function (r) {
+    var category = r && r.category ? r.category : 'memory';
+    var summary = r && r.summary ? r.summary : '';
+    return '- [' + category + '] ' + summary;
+  });
+
+  console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
+  process.exit(0);
+}
+
+// Hooks must never surface as a hard failure to the host CLI (Codex/Claude/Copilot all render a
+// nonzero exit as a red "hook failed" error) - an uncaught exception anywhere above (e.g. an
+// environment that denies process spawn or fs access, such as Codex's experimental Windows
+// sandbox) must degrade to a silent no-op, not a visible crash.
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// Codex-only variant of the SessionStart hook above. Confirmed live (2026-08-08, via a real
+// `codex exec` run) that Codex requires valid JSON on stdout for a hook's output to actually
+// register/display - plain text (what CLAUDE_HOOK_SESSION_START_SOURCE emits, which Claude Code
+// handles fine) makes Codex report the hook as failed. Uses the same hookSpecificOutput.
+// additionalContext shape Claude's own JSON-output hooks use (see CLAUDE_HOOK_STOP_SOURCE below) -
+// confirmed accepted by Codex's SessionStart handler specifically. Otherwise byte-identical to
+// CLAUDE_HOOK_SESSION_START_SOURCE; keep any future logic changes in sync between the two.
+const CODEX_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var spawnSync = require('child_process').spawnSync;
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'session-start.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break session start.
+  }
+}
+
+function resolveEmpiricalEntryPoint() {
+  if (process.platform !== 'win32') {
+    return null;
+  }
+  try {
+    var where = spawnSync('where', ['empirical.cmd'], { encoding: 'utf8', timeout: 5000, shell: true });
+    if (where.status !== 0 || !where.stdout) return null;
+    var cmdPath = where.stdout.split(/\\r?\\n/).map(function (s) { return s.trim(); }).filter(Boolean)[0];
+    if (!cmdPath || !fs.existsSync(cmdPath)) return null;
+    var cmdContent = fs.readFileSync(cmdPath, 'utf8');
+    var match = cmdContent.match(/"%dp0%\\\\(node_modules\\\\.+?\\.js)"/);
+    if (!match) return null;
+    var candidate = path.join(path.dirname(cmdPath), match[1]);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  var probe = process.platform === 'win32'
+    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
+    : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+function runMemoryQuery(args) {
+  var entryPoint = resolveEmpiricalEntryPoint();
+  if (entryPoint) {
+    appendLog('resolved direct entry point: ' + entryPoint);
+    return spawnSync(process.execPath, [entryPoint].concat(args), {
+      encoding: 'utf8',
+      timeout: 10000,
+      shell: false
+    });
+  }
+
+  appendLog('direct entry point not resolved, falling back to shell invocation (shell=' + (process.platform === 'win32') + ')');
+  return spawnSync('empirical', args, {
+    encoding: 'utf8',
+    timeout: 10000,
+    shell: process.platform === 'win32'
+  });
+}
+
+function main() {
+  appendLog('hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  if (!commandExists('empirical')) {
+    appendLog('empirical CLI not found on PATH, exiting');
+    process.exit(0);
+  }
+
+  var result = runMemoryQuery([
+    'memory', 'query',
+    '--match', 'project context, conventions, recent decisions, user preferences',
+    '--top-k', '8'
+  ]);
+
+  if (!result || result.status !== 0 || !result.stdout) {
+    appendLog('memory query failed or returned no stdout (status=' + (result && result.status) + ', stderr=' + (result && result.stderr ? String(result.stderr).slice(0, 300) : '') + ')');
+    process.exit(0);
+  }
+
+  var results;
+  try {
+    results = JSON.parse(result.stdout);
+  } catch (e) {
+    appendLog('failed to parse memory query stdout as JSON: ' + e.message);
+    process.exit(0);
+  }
+
+  if (!Array.isArray(results) || results.length === 0) {
+    appendLog('memory query returned zero results');
+    process.exit(0);
+  }
+
+  appendLog('memory query returned ' + results.length + ' result(s), injecting into session context');
+
+  var lines = results.slice(0, 8).map(function (r) {
+    var category = r && r.category ? r.category : 'memory';
+    var summary = r && r.summary ? r.summary : '';
+    return '- [' + category + '] ' + summary;
+  });
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: 'Empirical memory context for this session:\\n' + lines.join('\\n')
+    }
+  }));
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// EMPIRICAL_HOOK_STOP_SOURCE: fires once per assistant turn (Claude: Stop; Codex: Stop, turn-
+// scoped per codex-rs/hooks/src/engine/dispatcher.rs; Copilot: agentStop, "the main agent
+// finishes a turn" per GitHub's own hooks reference). This is the write-side counterpart to the
+// SessionStart hook above (which only covers recall, once per session boundary) - deliberately
+// simple: it does NOT parse the transcript to detect whether memory-worthy activity happened
+// this turn (transcript formats differ across all three platforms and getting that heuristic
+// wrong silently - the exact class of bug this session spent hours finding - is worse than an
+// unconditional reminder). It never calls the empirical CLI and makes no network call, so the
+// "wasteful per-turn hook" concern that killed the old per-turn UserPromptSubmit hook (see
+// installClaudeHooks below) does not apply here - this is a single static stdout write.
+// ALWAYS exits 0: per Claude Code's documented Stop hook contract, exit 2 forces the agent to
+// keep responding (a blocking decision) - a bug in a hook that's supposed to be an informational
+// nudge must never be able to trap a session in a forced-continuation loop, so this is
+// unconditional regardless of any error encountered.
+const EMPIRICAL_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  // Defensive loop guard: if a Stop hook's own forced-continuation output somehow triggers
+  // another Stop event before the agent produces new output, stop_hook_active (Claude's documented
+  // field name for this) prevents a reminder-print-loop. This hook never sets decision:block
+  // itself, but checking costs nothing and protects against any future change that does.
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  console.log('[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.');
+  process.exit(0);
+}
+
+// See EMPIRICAL_HOOK_SESSION_START_SOURCE's identical guard above: a crash here must degrade to a
+// silent no-op, never a visible "hook failed" error in the host CLI.
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// Codex-only variant of the Stop reminder above. Confirmed live (2026-08-08, via a real `codex
+// exec` run) that Codex's Stop hook specifically requires a { systemMessage: "..." } JSON shape
+// on stdout - plain text (what EMPIRICAL_HOOK_STOP_SOURCE emits, used by Copilot) makes Codex
+// report the hook as failed. Distinct from Claude's own JSON shape (hookSpecificOutput.
+// additionalContext, see CLAUDE_HOOK_STOP_SOURCE below) - each host has its own schema here.
+const CODEX_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+
+  console.log(JSON.stringify({
+    systemMessage: '[Empirical reminder] Before finishing: if this turn included a completed decision, a corrected mistake, or meaningful work worth remembering, record it now via the empirical-memory skill or \`empirical memory record\` - do not wait to be asked.'
+  }));
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// Claude-only variant of the Stop reminder above. hookSpecificOutput.additionalContext (stdout,
+// exit 0) is Claude Code's non-blocking Stop-hook feedback channel: the text is fed into context
+// and the conversation continues, same outcome the earlier exit-2 approach achieved, but the
+// transcript UI renders it as a plain system reminder instead of a red "Stop hook error" line.
+// EMPIRICAL_HOOK_STOP_SOURCE above still uses plain console.log + exit 0, which Claude Code treats
+// as non-blocking output that's logged but never reaches the model - that was this hook's original
+// bug (fixed for Claude here, unconfirmed/unfixed for Codex/Copilot's own Stop/agentStop semantics).
+const CLAUDE_HOOK_STOP_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'stop.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+function readStdinPayload() {
+  try {
+    var raw = fs.readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function main() {
+  var payload = readStdinPayload();
+
+  // stop_hook_active === true means Claude is re-invoking this hook because a PRIOR Stop hook
+  // (possibly this same one) already surfaced additionalContext and forced a continuation this
+  // turn. additionalContext causes the same forced-continuation behavior decision:block does -
+  // confirmed empirically: without this guard the hook re-fired every ~2-3s in an infinite loop,
+  // since each additionalContext output triggers another Stop event. Must exit 0 with no output
+  // here, unconditionally, or the loop continues.
+  if (payload && payload.stop_hook_active === true) {
+    appendLog('stop_hook_active=true, skipping reminder (already surfaced once this turn)');
+    process.exit(0);
+  }
+
+  appendLog('stop hook fired (pid=' + process.pid + ', platform=' + process.platform + '), surfacing reminder via additionalContext');
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'Stop',
+      additionalContext: '[Empirical] Record memory-worthy work now via empirical-memory skill.'
+    }
+  }) + '\\n');
+  process.exit(0);
+}
+
+// See EMPIRICAL_HOOK_SESSION_START_SOURCE's identical guard: a crash here must degrade to a
+// silent no-op, never a visible "hook failed" error in the host CLI.
+try {
+  main();
+} catch (e) {
+  try { appendLog('uncaught error in main(): ' + (e && e.message)); } catch (_e) { /* best effort */ }
+  process.exit(0);
+}
+`;
+
+// UserPromptSubmit: fires before each turn is processed (Claude, Codex, and Copilot all support
+// this event under the same name per each platform's docs/source). This is the recall-side
+// counterpart to Stop's write-side reminder - deliberately a STATIC message, not a live
+// `empirical memory query` call: a prior per-turn hook in this codebase was removed for making an
+// unconditional network call on every single prompt (see the comment above installClaudeHooks),
+// and re-adding that cost here on three platforms at once was an explicit no per product decision.
+// The message itself is generated per-install from the actual plugin set being installed, not one
+// fixed string for everyone - e.g. someone who declined empirical-scar-tissue at install time
+// never sees a scar-tissue reminder, since that capability isn't actually available to them.
+function buildPromptReminderMessage(pluginNames) {
+  const names = normalizePluginNames(pluginNames);
+  const lines = [
+    'Before responding: if this task needs prior context (research, debugging, a spec or status update, a handoff), query Empirical memory first via the empirical-memory skill or empirical memory query - do not assume you already have enough context.'
+  ];
+  if (names.includes('empirical-work-history')) {
+    lines.push('If you are picking up previously completed work, check for a recent work-history entry before assuming there is none.');
+  }
+  if (names.includes('empirical-scar-tissue')) {
+    lines.push('Check for scar tissue before repeating a past mistake in this area.');
+  }
+  if (names.includes('empirical-todo')) {
+    lines.push('If there is an open todo for this project, check it before starting new work.');
+  }
+  return '[Empirical reminder] ' + lines.join(' ');
+}
+
+// Builds the full UserPromptSubmit hook script source with the tailored message baked in at
+// generation time (via JSON.stringify, so the message is embedded as a single already-escaped
+// string literal - substituted through `${}`, not written as raw template-literal source text,
+// which is what caused the earlier comment-escaping bug in this same file. Never do the latter).
+// `platform`: 'codex' emits Codex's required hookSpecificOutput.additionalContext JSON shape
+// (confirmed live 2026-08-08 via a real `codex exec` run - plain text made Codex report the hook
+// as failed); any other value (default) keeps the original plain console.log for Claude/Copilot,
+// which is confirmed working for both.
+function buildUserPromptSubmitHookSource(pluginNames, platform) {
+  const messageLiteral = JSON.stringify(buildPromptReminderMessage(pluginNames));
+  const outputStatement = platform === 'codex'
+    ? `console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: ${messageLiteral}
+    }
+  }));`
+    : `console.log(${messageLiteral});`;
+  return `#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var LOG_PATH = path.join(os.homedir(), '.empirical', 'hooks', 'user-prompt-submit.log');
+var MAX_LOG_BYTES = 200 * 1024;
+
+function appendLog(line) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    fs.appendFileSync(LOG_PATH, '[' + new Date().toISOString() + '] ' + line + '\\n');
+    var stat = fs.statSync(LOG_PATH);
+    if (stat.size > MAX_LOG_BYTES) {
+      var tail = fs.readFileSync(LOG_PATH, 'utf8').slice(-MAX_LOG_BYTES / 2);
+      fs.writeFileSync(LOG_PATH, tail);
+    }
+  } catch (e) {
+    // Diagnostics must never break the hook.
+  }
+}
+
+// A crash here must degrade to a silent no-op, never a visible "hook failed" error in the host CLI.
+try {
+  appendLog('user-prompt-submit hook fired (pid=' + process.pid + ', platform=' + process.platform + ')');
+  ${outputStatement}
+} catch (e) {
+  try { appendLog('uncaught error: ' + (e && e.message)); } catch (_e) { /* best effort */ }
+}
+process.exit(0);
+`;
+}
+
+function getEmpiricalHooksDir() {
+  return path.join(os.homedir(), '.empirical', 'hooks');
+}
+
+function buildHookCommand(scriptPath) {
+  return `"${process.execPath}" "${scriptPath}"`;
+}
+
+function removeEmpiricalHookEntries(entries, scriptPath) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const filteredHooks = entry.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
+      );
+      return { ...entry, hooks: filteredHooks };
+    })
+    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
+}
+
+function installClaudeHooks(pluginNames) {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  // A prior version of this hook made an unconditional `empirical memory query` network call on
+  // every single prompt and was removed for being wasteful (see git history). This is a
+  // deliberate reintroduction at the SAME script path, but with fundamentally different content:
+  // a static, install-time-generated reminder with no network call at all - the cost concern that
+  // killed the old version does not apply to a plain stdout write.
+  const userPromptScriptPath = path.join(hooksDir, 'claude-user-prompt-submit.js');
+  const sessionStartScriptPath = path.join(hooksDir, 'claude-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'claude-stop.js');
+  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, CLAUDE_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
+
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settings = readJsonIfExists(settingsPath) || {};
+  if (!settings.hooks || typeof settings.hooks !== 'object') {
+    settings.hooks = {};
+  }
+
+  settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command: buildHookCommand(userPromptScriptPath), timeout: 10 }]
+  });
+
+  settings.hooks.SessionStart = removeEmpiricalHookEntries(settings.hooks.SessionStart, sessionStartScriptPath);
+  for (const matcher of ['startup', 'resume', 'compact']) {
+    settings.hooks.SessionStart.push({
+      matcher,
+      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 15 }]
+    });
+  }
+
+  settings.hooks.Stop = removeEmpiricalHookEntries(settings.hooks.Stop, stopScriptPath);
+  settings.hooks.Stop.push({
+    hooks: [{ type: 'command', command: buildHookCommand(stopScriptPath), timeout: 10 }]
+  });
+
+  writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  log('  - Claude SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
+}
+
+// Codex CLI ships a real hooks system (confirmed against openai/codex source — codex-rs/hooks,
+// codex-rs/config/src/hook_config.rs — not assumed from docs alone, since third-party writeups
+// disagreed on Windows support). It reads <CODEX_HOME>/hooks.json (JSON, not the config.toml
+// used for MCP/model settings — a separate file, so this never touches config.toml) shaped as
+// { hooks: { SessionStart: [{ matcher, hooks: [{ type: 'command', command, commandWindows,
+// timeout }] }], ... } }. CODEX_HOME defaults to ~/.codex when unset, same convention as
+// ~/.claude for Claude Code.
+function getCodexHomeDir() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+
+function removeEmpiricalHooksJsonEntries(entries, scriptPath) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const filteredHooks = entry.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
+      );
+      return { ...entry, hooks: filteredHooks };
+    })
+    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
+}
+
+// Codex's Windows sandbox (confirmed via `codex doctor` -> "filesystem sandbox: restricted" and
+// ~/.codex/.sandbox/sandbox.*.log's "processed N write roots (read roots delegated)" / "applying
+// read ACLs" at session start) scopes filesystem access per-session to project-specific roots
+// plus, necessarily, CODEX_HOME itself (Codex reads hooks.json, its state db, and its plugin
+// cache from there on every session regardless of project). The shared `~/.empirical/hooks`
+// directory used by Claude/Copilot is neither - so under this sandbox, node.exe most likely
+// cannot even read a hook script living there, which is why hooks fail identically (exit 1)
+// across SessionStart/UserPromptSubmit/Stop regardless of what each script actually does,
+// including the trivial UserPromptSubmit script that spawns no subprocess at all. Claude Code
+// hooks are unaffected (confirmed working from the shared dir) and Copilot has shown no such
+// failure, so only Codex's copies are relocated here - Claude/Copilot keep using
+// getEmpiricalHooksDir() unchanged.
+function getCodexHooksScriptsDir() {
+  return path.join(getCodexHomeDir(), 'empirical-hooks');
+}
+
+// Confirmed live (2026-08-08, via a real `codex exec` run): Codex's Windows hook launcher fails
+// to parse a quoted executable path (e.g. `"C:\Program Files\nodejs\node.exe" "<script>"`,
+// otherwise a perfectly standard Windows command line - Claude Code and every direct shell/
+// spawnSync invocation handle it fine) and reports the hook as a nonzero-exit failure before any
+// of the script's own JS ever runs. Windows 8.3 short path names never contain spaces, so
+// resolving both the node executable and the script path to their short form and joining them
+// unquoted sidesteps the parser entirely. Computed once at install time (not per hook
+// invocation), so a synchronous shell call here is an acceptable cost.
+function getWindowsShortPath(longPath) {
+  if (process.platform !== 'win32') return null;
+  try {
+    const { execSync } = require('child_process');
+    const out = execSync(`cmd /c for %I in ("${longPath}") do @echo %~sI`, { encoding: 'utf8', timeout: 5000 });
+    const short = out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).pop();
+    const fs = require('fs');
+    return short && fs.existsSync(short) ? short : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// Builds Codex's commandWindows value using short paths so neither the executable nor the script
+// path ever needs quoting. Falls back to the normal quoted buildHookCommand() form if short-path
+// resolution fails for any reason (e.g. 8.3 name generation disabled on that volume) - degraded
+// (same behavior as before this fix) rather than broken.
+function buildCodexWindowsHookCommand(scriptPath) {
+  const shortNode = getWindowsShortPath(process.execPath);
+  const shortScript = getWindowsShortPath(scriptPath);
+  if (shortNode && shortScript) {
+    return `${shortNode} ${shortScript}`;
+  }
+  return buildHookCommand(scriptPath);
+}
+
+function installCodexHooks(pluginNames) {
+  const fs = require('fs');
+  const legacyHooksDir = getEmpiricalHooksDir();
+  const hooksDir = getCodexHooksScriptsDir();
+  ensureDir(hooksDir);
+
+  const sessionStartScriptPath = path.join(hooksDir, 'codex-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'codex-stop.js');
+  const userPromptScriptPath = path.join(hooksDir, 'codex-user-prompt-submit.js');
+  writeFile(sessionStartScriptPath, CODEX_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, CODEX_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames, 'codex'));
+
+  // Best-effort cleanup of the pre-relocation script files/entries at the old shared path, so a
+  // machine that already had Codex hooks installed doesn't end up with both the old (broken
+  // under the sandbox) and new registration firing redundantly.
+  const legacySessionStartScriptPath = path.join(legacyHooksDir, 'codex-session-start.js');
+  const legacyStopScriptPath = path.join(legacyHooksDir, 'codex-stop.js');
+  const legacyUserPromptScriptPath = path.join(legacyHooksDir, 'codex-user-prompt-submit.js');
+  for (const legacyPath of [legacySessionStartScriptPath, legacyStopScriptPath, legacyUserPromptScriptPath]) {
+    try {
+      if (fs.existsSync(legacyPath)) fs.unlinkSync(legacyPath);
+    } catch (_error) {
+      // best-effort cleanup only
+    }
+  }
+
+  const hooksJsonPath = path.join(getCodexHomeDir(), 'hooks.json');
+  const hooksFile = readJsonIfExists(hooksJsonPath) || {};
+  if (!hooksFile.hooks || typeof hooksFile.hooks !== 'object') {
+    hooksFile.hooks = {};
+  }
+
+  hooksFile.hooks.SessionStart = removeEmpiricalHooksJsonEntries(
+    removeEmpiricalHooksJsonEntries(hooksFile.hooks.SessionStart, sessionStartScriptPath),
+    legacySessionStartScriptPath
+  );
+  const sessionStartCommand = buildHookCommand(sessionStartScriptPath);
+  const sessionStartCommandWindows = buildCodexWindowsHookCommand(sessionStartScriptPath);
+  for (const matcher of ['startup', 'resume']) {
+    hooksFile.hooks.SessionStart.push({
+      matcher,
+      hooks: [{ type: 'command', command: sessionStartCommand, commandWindows: sessionStartCommandWindows, timeout: 15 }]
+    });
+  }
+
+  hooksFile.hooks.Stop = removeEmpiricalHooksJsonEntries(
+    removeEmpiricalHooksJsonEntries(hooksFile.hooks.Stop, stopScriptPath),
+    legacyStopScriptPath
+  );
+  const stopCommand = buildHookCommand(stopScriptPath);
+  const stopCommandWindows = buildCodexWindowsHookCommand(stopScriptPath);
+  hooksFile.hooks.Stop.push({
+    hooks: [{ type: 'command', command: stopCommand, commandWindows: stopCommandWindows, timeout: 10 }]
+  });
+
+  // Confirmed against codex-rs/config/src/hook_config.rs's HookEventsToml serde renames: the
+  // config-file key is PascalCase "UserPromptSubmit", same casing convention as SessionStart/Stop.
+  hooksFile.hooks.UserPromptSubmit = removeEmpiricalHooksJsonEntries(
+    removeEmpiricalHooksJsonEntries(hooksFile.hooks.UserPromptSubmit, userPromptScriptPath),
+    legacyUserPromptScriptPath
+  );
+  const userPromptCommand = buildHookCommand(userPromptScriptPath);
+  const userPromptCommandWindows = buildCodexWindowsHookCommand(userPromptScriptPath);
+  hooksFile.hooks.UserPromptSubmit.push({
+    hooks: [{ type: 'command', command: userPromptCommand, commandWindows: userPromptCommandWindows, timeout: 10 }]
+  });
+
+  writeFile(hooksJsonPath, `${JSON.stringify(hooksFile, null, 2)}\n`);
+  log('  - Codex SessionStart + UserPromptSubmit + Stop hooks installed for deterministic memory lookups and reminders.');
+}
+
+// GitHub Copilot CLI's hook config is one JSON file per hook under ~/.copilot/hooks/ (any
+// filename — confirmed via GitHub's own docs at docs.github.com/en/copilot/reference/hooks-
+// reference), so unlike Claude/Codex this never needs to merge into a shared file: Empirical
+// owns this file outright and can just overwrite it. Event key for turn-end is "agentStop"
+// ("the main agent finishes a turn" per the same docs) — not "stop"/"Stop" like Claude/Codex.
+// Schema: { version: 1, hooks: { sessionStart: [...], agentStop: [...] } }.
+function installCopilotHooks(pluginNames) {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  const sessionStartScriptPath = path.join(hooksDir, 'copilot-session-start.js');
+  const stopScriptPath = path.join(hooksDir, 'copilot-stop.js');
+  const userPromptScriptPath = path.join(hooksDir, 'copilot-user-prompt-submit.js');
+  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+  writeFile(stopScriptPath, EMPIRICAL_HOOK_STOP_SOURCE);
+  writeFile(userPromptScriptPath, buildUserPromptSubmitHookSource(pluginNames));
+
+  const copilotHooksDir = path.join(os.homedir(), '.copilot', 'hooks');
+  ensureDir(copilotHooksDir);
+
+  // Prior versions of this installer wrote a single-purpose "empirical-session-start.json" —
+  // remove it now that both events live in one unified file, so a stale duplicate registration
+  // never lingers alongside the new one.
+  const legacyHookFilePath = path.join(copilotHooksDir, 'empirical-session-start.json');
+  try {
+    const fs = require('fs');
+    if (fs.existsSync(legacyHookFilePath)) fs.unlinkSync(legacyHookFilePath);
+  } catch (_error) {
+    // best-effort cleanup only
+  }
+
+  const hookFilePath = path.join(copilotHooksDir, 'empirical-hooks.json');
+  const hookFileContent = {
+    version: 1,
+    hooks: {
+      sessionStart: [
+        { type: 'command', command: buildHookCommand(sessionStartScriptPath), timeoutSec: 15 }
+      ],
+      // "userPromptSubmitted" per GitHub's hooks reference ("The user submits a prompt") - not
+      // "userPromptSubmit" (that camelCase spelling is Claude/Codex's convention, not Copilot's).
+      userPromptSubmitted: [
+        { type: 'command', command: buildHookCommand(userPromptScriptPath), timeoutSec: 10 }
+      ],
+      agentStop: [
+        { type: 'command', command: buildHookCommand(stopScriptPath), timeoutSec: 10 }
+      ]
+    }
+  };
+
+  writeFile(hookFilePath, `${JSON.stringify(hookFileContent, null, 2)}\n`);
+  log('  - Copilot SessionStart + userPromptSubmitted + agentStop hooks installed for deterministic memory lookups and reminders.');
+}
+
+module.exports = {
+  CLAUDE_HOOK_SESSION_START_SOURCE,
+  CODEX_HOOK_SESSION_START_SOURCE,
+  EMPIRICAL_HOOK_STOP_SOURCE,
+  CODEX_HOOK_STOP_SOURCE,
+  CLAUDE_HOOK_STOP_SOURCE,
+  buildPromptReminderMessage,
+  buildUserPromptSubmitHookSource,
+  getEmpiricalHooksDir,
+  buildHookCommand,
+  removeEmpiricalHookEntries,
+  installClaudeHooks,
+  getCodexHomeDir,
+  removeEmpiricalHooksJsonEntries,
+  getCodexHooksScriptsDir,
+  getWindowsShortPath,
+  buildCodexWindowsHookCommand,
+  installCodexHooks,
+  installCopilotHooks
+};