sphinx-understand 0.0.0-stage → 0.1.1

package/src/activation.js

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { access, lstat, mkdir, open, rm, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { spawn, execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { getPaths, readJson, writeJson } from './config.js';
+import { terminalCommand, spawnTerminal, createTerminalEnvironmentBridge, readTerminalEnvironment } from './terminal-launch.js';
+
+const WORKER = fileURLToPath(new URL('./activation-worker.js', import.meta.url));
+const AGENTS = ['codex', 'claude', 'pi', 'cursor', 'opencode'];
+const TOKEN = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const SESSION_ENV = ['CODEX_THREAD_ID', 'CLAUDECODE', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_CODE_ENTRYPOINT', 'PI_SESSION_ID', 'SPHINX_CLAUDE_SESSION', 'SPHINX_CURSOR_SESSION', 'SPHINX_OPENCODE_SESSION'];
+const LABELS = { codex: 'Codex', claude: 'Claude Code', pi: 'Pi', cursor: 'Cursor', opencode: 'OpenCode' };
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const desktop = (env, platform) => !env.SSH_CONNECTION && !env.SSH_TTY && !(env.CI && env.CI !== 'false' && env.CI !== '0') && (platform === 'darwin' || (platform === 'linux' && !!(env.DISPLAY || env.WAYLAND_DISPLAY)));
+const freshEnvironment = env => Object.fromEntries(Object.entries(env).filter(([key]) => !SESSION_ENV.includes(key)));
+const fileFor = (home, token) => path.join(home, 'activations', `${token}.json`);
+
+function clientEnvironment(env) {
+  const fresh = freshEnvironment(env);
+  if (!env.SPHINX_USER_HOME) return fresh;
+  const paths = getPaths(env);
+  return { ...fresh, HOME: paths.userHome, CODEX_HOME: paths.codexHome, CLAUDE_CONFIG_DIR: paths.claudeHome, PI_CODING_AGENT_DIR: path.join(paths.userHome, '.pi', 'agent'), OPENCODE_CONFIG_DIR: path.join(paths.userHome, '.config', 'opencode'), XDG_CONFIG_HOME: path.join(paths.userHome, '.config'), XDG_DATA_HOME: path.join(paths.userHome, '.local', 'share'), XDG_STATE_HOME: path.join(paths.userHome, '.local', 'state'), XDG_CACHE_HOME: path.join(paths.userHome, '.cache') };
+}
+
+async function executable(name, env) {
+  for (const directory of (env.PATH || '').split(path.delimiter)) {
+    if (!directory) continue;
+    const file = path.resolve(directory, name);
+    try { if ((await stat(file)).isFile()) { await access(file, constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+
+async function cursorExecutable(env, platform, findExecutable) {
+  const fromPath = await findExecutable('cursor', env);
+  if (fromPath || platform !== 'darwin') return fromPath;
+  // Use the editor's own launcher when "Install cursor command" was not run.
+  // Test homes must never fall through to the real machine's Applications.
+  const roots = env.SPHINX_USER_HOME ? [path.join(getPaths(env).userHome, 'Applications')] : ['/Applications', path.join(getPaths(env).userHome, 'Applications')];
+  for (const root of roots) {
+    const file = path.join(root, 'Cursor.app', 'Contents', 'Resources', 'app', 'bin', 'code');
+    try { if ((await stat(file)).isFile()) { await access(file, constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+
+async function clientVersion(binary, env) {
+  return new Promise(resolve => {
+    execFile(binary, ['--version'], { env, timeout: 2000, maxBuffer: 4096, encoding: 'utf8' }, (error, stdout) => {
+      if (error) { resolve(null); return; }
+      const match = /^(?:Cursor\s+)?(\d+)\.(\d+)(?:\.(\d+))?(?:[-+][^\s]*)?\s*$/im.exec(stdout);
+      resolve(match ? `${match[1]}.${match[2]}.${match[3] || 0}` : null);
+    });
+  });
+}
+
+async function activationDirectory(home) {
+  const directory = path.join(home, 'activations');
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (info && (info.isSymbolicLink() || !info.isDirectory())) throw new Error('Refusing an unsafe client activation directory.');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  return directory;
+}
+
+/** Instructions stay in the terminal; they are never submitted as a model prompt. */
+export function activationGuidance(agent) {
+  const steps = {
+    codex: 'In Codex, open /hooks to review and trust the Sphinx hooks.',
+    claude: 'Respond to any Claude setup or MCP permission prompts. Use /mcp to inspect Sphinx.',
+    pi: 'Blocking Git checks use a local browser page. Pi dialogs handle fallback checkpoints.',
+    opencode: 'When Git requires a checkpoint, Sphinx serves a local browser questionnaire without moving your coding window.',
+  };
+  return `Sphinx · ${LABELS[agent]}\n${steps[agent]}\nStarting a fresh session in this repository. No prompt has been submitted.\n\n`;
+}
+
+/** Open configured clients only; the caller supplies the installed selection. */
+export async function activateIntegrations({ agents = [], cwd = process.cwd(), env = process.env, platform = process.platform, findExecutable = executable, readClientVersion = clientVersion, launch = spawnTerminal, environmentBridge = createTerminalEnvironmentBridge, timeoutMs = 20000, pollMs = 50, wait = delay } = {}) {
+  if (!Array.isArray(agents) || agents.some(agent => !AGENTS.includes(agent))) throw new Error('Choose codex, claude, pi, cursor, or opencode for activation.');
+  if (typeof cwd !== 'string' || cwd.includes('\0') || !path.isAbsolute(cwd)) throw new Error('Client activation needs an absolute repository directory.');
+  if (!(await stat(cwd)).isDirectory()) throw new Error('Client activation needs an existing directory.');
+  const home = getPaths(env).home;
+  const results = await Promise.all([...new Set(agents)].map(async agent => {
+    const command = agent === 'cursor' ? `cursor --new-window ${quote(cwd)}` : agent;
+    const result = (status, detail) => ({ agent, status, detail, command, cwd });
+    if (env.SPHINX_EVALUATOR === '1') return result('unavailable', 'Client activation is disabled inside an evaluator.');
+    if (!desktop(env, platform)) return result('unavailable', `No local desktop is available. Open a terminal in this repository and run ${command}.`);
+    let binary;
+    try { binary = agent === 'cursor' ? await cursorExecutable(env, platform, findExecutable) : await findExecutable(agent, env); }
+    catch { return result('unavailable', `Could not locate ${LABELS[agent]}. Open it manually in this repository.`); }
+    if (binary && (!path.isAbsolute(binary) || binary.includes('\0'))) return result('unavailable', `Could not locate a valid ${LABELS[agent]} executable.`);
+    if (!binary) return result('unavailable', `${LABELS[agent]} is configured but its executable is not on PATH. Open it manually in this repository.`);
+    if (agent === 'cursor') {
+      // The editor CLI has this spelling; never substitute cursor-agent or agent.
+      try {
+        const version = await readClientVersion(binary, clientEnvironment(env));
+        if (/^\d+\.\d+\.\d+$/.test(version || '')) {
+          const [major, minor] = version.split('.').map(Number);
+          // Hooks first appeared in Cursor 1.7. Passing this floor does not
+          // certify support for every current hook event or verify permissions.
+          if (major < 1 || (major === 1 && minor < 7)) return result('unavailable', `Cursor ${version} predates hook support. Update Cursor, then run sphinx activate --agents cursor.`);
+        }
+        const opened = await launch({ command: binary, args: ['--new-window', cwd], waitForExit: true }, { env: clientEnvironment(env) });
+        return opened ? result('opened', 'Opened a new Cursor editor window. Start a new agent chat there; hook loading and permissions remain controlled by Cursor.') : result('failed', 'Cursor did not accept the window launch. Open the editor manually in this repository.');
+      } catch { return result('failed', 'Cursor could not be opened. Open the editor manually in this repository.'); }
+    }
+    let bridge, recordFile, claimFile;
+    try {
+      await activationDirectory(home);
+      const token = randomUUID();
+      recordFile = fileFor(home, token); claimFile = `${recordFile}.claim`;
+      const terminal = await terminalCommand({ recordFile, token, home, platform, env, findExecutable, workerPath: WORKER });
+      if (!terminal) return result('unavailable', `No supported desktop terminal was found. Open a terminal in this repository and run ${command}.`);
+      bridge = await environmentBridge(clientEnvironment(env), token);
+      await writeJson(recordFile, { version: 1, token, home, agent, command: binary, cwd, envSocket: bridge.socketPath, status: 'starting', createdAt: Date.now() });
+      const accepted = await launch(terminal, { env: clientEnvironment(env) });
+      if (!accepted) return result('failed', `Could not open a terminal for ${LABELS[agent]}. Run ${command} in this repository.`);
+      // Keep the one-shot IPC alive until the worker has received the environment
+      // and its interactive client emits spawn. Never wait for the session to end.
+      const deadline = Date.now() + timeoutMs;
+      do {
+        const current = await readJson(recordFile, null);
+        if (current?.token !== token) return result('failed', `The ${LABELS[agent]} launch could not be confirmed. Open it manually.`);
+        if (current.status === 'opened') return result('opened', agent === 'codex' ? 'Started a fresh Codex session. Open /hooks there to review and trust Sphinx hooks.' : `Started a fresh ${LABELS[agent]} session. Complete any setup or permissions in that terminal.`);
+        if (current.status === 'failed') return result('failed', `${LABELS[agent]} could not start in the terminal. Run ${command} in this repository.`);
+        if (Date.now() >= deadline) break;
+        await wait(Math.min(pollMs, deadline - Date.now()));
+      } while (true);
+      return result('failed', `The terminal opened, but ${LABELS[agent]} startup was not confirmed. Check that terminal or run ${command} manually.`);
+    } catch { return result('failed', `Could not start ${LABELS[agent]}. Run ${command} in this repository.`); }
+    finally {
+      await bridge?.close().catch(() => {});
+      if (recordFile) await rm(recordFile, { force: true }).catch(() => {});
+      if (claimFile) await rm(claimFile, { force: true }).catch(() => {});
+    }
+  }));
+  return { results };
+}
+
+/** Runs in the opened terminal, never in the installing coding-agent session. */
+export async function runActivationTerminal({ recordFile, token, env = process.env, isTTY = !!process.stdin.isTTY, spawnImpl = spawn, write = text => process.stdout.write(text), startupGraceMs = 300 } = {}) {
+  const home = getPaths(env).home;
+  if (!TOKEN.test(token) || recordFile !== fileFor(home, token)) throw new Error('Invalid client activation worker.');
+  await activationDirectory(home);
+  let claim;
+  try { claim = await open(`${recordFile}.claim`, 'wx', 0o600); }
+  catch (error) { if (error.code === 'EEXIST') return { status: 'ignored', code: 1 }; throw error; }
+  try {
+    const record = await readJson(recordFile, null);
+    if (!record || record.version !== 1 || record.token !== token || record.home !== home || !AGENTS.filter(agent => agent !== 'cursor').includes(record.agent) || record.status !== 'starting' || !path.isAbsolute(record.command || '') || record.command.includes('\0') || !path.isAbsolute(record.cwd || '') || record.cwd.includes('\0')) return { status: 'ignored', code: 1 };
+    const status = async value => {
+      // Installation can time out or finish while this worker remains alive.
+      // It owns cleanup; do not recreate an already removed launch record.
+      try {
+        if ((await readJson(recordFile, null))?.token === token) await writeJson(recordFile, { ...record, status: value });
+      } catch { /* The parent reports unconfirmed startup if acknowledgment fails. */ }
+    };
+    if (!isTTY) { await status('failed'); return { status: 'failed', code: 1 }; }
+    let providerEnv;
+    try { providerEnv = await readTerminalEnvironment(record.envSocket, token); }
+    catch { await status('failed'); return { status: 'failed', code: 1 }; }
+    if (!(await readJson(recordFile, null))) return { status: 'ignored', code: 1 };
+    write(activationGuidance(record.agent));
+    let opened = false, stateWrite = Promise.resolve();
+    const code = await new Promise(resolve => {
+      let child, timer;
+      try { child = spawnImpl(record.command, [], { cwd: record.cwd, env: { ...freshEnvironment(env), ...providerEnv, SPHINX_HOME: home }, stdio: 'inherit' }); }
+      catch { stateWrite = status('failed'); resolve(1); return; }
+      child.once('spawn', () => {
+        timer = setTimeout(() => { opened = true; stateWrite = stateWrite.then(() => status('opened')); }, startupGraceMs);
+      });
+      child.once('error', () => { clearTimeout(timer); stateWrite = stateWrite.then(() => status('failed')); resolve(1); });
+      child.once('exit', code => {
+        clearTimeout(timer);
+        if (!opened) stateWrite = stateWrite.then(() => status('failed'));
+        resolve(code ?? 1);
+      });
+    });
+    await stateWrite;
+    return { status: opened ? 'closed' : 'failed', code };
+  } finally {
+    await claim.close();
+    await rm(`${recordFile}.claim`, { force: true }).catch(() => {});
+  }
+}

package/src/agent-settings.js

@@ -0,0 +1,206 @@
+import path from 'node:path';
+import { lstat, readFile, mkdir, writeFile, rename, rm, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+
+const START = '# >>> Sphinx managed MCP server';
+const END = '# <<< Sphinx managed MCP server';
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+async function readText(file) {
+  try {
+    if ((await lstat(file)).isSymbolicLink()) throw new Error(`Refusing to replace symlink: ${file}`);
+    return await readFile(file, 'utf8');
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function parseJson(text, file) {
+  if (text === null) return {};
+  try {
+    const value = JSON.parse(text);
+    if (!value || Array.isArray(value) || typeof value !== 'object') throw new Error();
+    return value;
+  } catch { throw new Error(`Cannot read ${file}: invalid JSON object. Fix the file and try again.`); }
+}
+
+async function writeText(file, text) {
+  if (text === null) { await rm(file, { force: true }); return; }
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const mode = await stat(file).then(s => s.mode & 0o777).catch(() => 0o600);
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { await writeFile(temporary, text, { mode, flag: 'wx' }); await rename(temporary, file); }
+  finally { await rm(temporary, { force: true }); }
+}
+
+// Read TOML key paths without rewriting TOML or interpreting any setting values.
+function keyPath(text) {
+  const keys = []; let position = 0;
+  while (position < text.length) {
+    while (/\s/.test(text[position] || '')) position++;
+    if (text[position] === '"') {
+      const match = text.slice(position).match(/^"(?:[^"\\]|\\.)*"/);
+      if (!match) return null;
+      try { keys.push(JSON.parse(match[0])); } catch { return null; }
+      position += match[0].length;
+    } else if (text[position] === "'") {
+      const end = text.indexOf("'", position + 1); if (end < 0) return null;
+      keys.push(text.slice(position + 1, end)); position = end + 1;
+    } else {
+      const match = text.slice(position).match(/^[\w-]+/); if (!match) return null;
+      keys.push(match[0]); position += match[0].length;
+    }
+    while (/\s/.test(text[position] || '')) position++;
+    if (position === text.length) return keys;
+    if (text[position++] !== '.') return null;
+  }
+  return keys;
+}
+
+function tomlLines(text, file) {
+  let mode = null, line = '', escaped = false;
+  const lines = [];
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i], triple = text.slice(i, i + 3);
+    if (char === '\n') { lines.push(line); line = ''; if (mode === '"' || mode === "'") throw new Error(`Cannot safely update malformed TOML: ${file}`); continue; }
+    if (mode === '"""' || mode === "'''") {
+      if (triple === mode && !escaped) { mode = null; i += 2; }
+      escaped = char === '\\' && !escaped && mode === '"""'; continue;
+    }
+    if (mode) {
+      line += char;
+      if (char === mode && !escaped) mode = null;
+      escaped = char === '\\' && !escaped && mode === '"'; continue;
+    }
+    if (char === '#') { while (i + 1 < text.length && text[i + 1] !== '\n') i++; continue; }
+    if (triple === '"""' || triple === "'''") { mode = triple; line += '""'; i += 2; continue; }
+    if (char === '"' || char === "'") mode = char;
+    line += char;
+  }
+  if (mode) throw new Error(`Cannot safely update malformed TOML: ${file}`);
+  lines.push(line); return lines;
+}
+
+function assertNoCodexConflict(text, file) {
+  let table = [];
+  for (const line of tomlLines(text, file)) {
+    const header = line.match(/^\s*\[\[?(.+?)\]\]?\s*$/);
+    if (header) {
+      table = keyPath(header[1]);
+      if (!table) throw new Error(`Cannot safely inspect TOML table names in ${file}. Configure the Sphinx MCP server manually.`);
+      if (table[0] === 'mcp_servers' && table[1] === 'sphinx') throw new Error(`An existing sphinx MCP server is defined in ${file}. Rename or remove that entry before installing Sphinx.`);
+      continue;
+    }
+    const assignment = line.match(/^\s*((?:"(?:[^"\\]|\\.)*"|'[^']*'|[\w.-]|\s)+)=/);
+    if (!assignment) continue;
+    const keys = keyPath(assignment[1].trim());
+    if (!keys) continue;
+    const full = [...table, ...keys];
+    if (full[0] === 'mcp_servers' && (full.length === 1 || full[1] === 'sphinx')) throw new Error(`An existing or inline MCP definition in ${file} conflicts with sphinx. Move it to separate server tables before installing.`);
+  }
+}
+
+export function nativeHookSpecs(name, sessionHandler) {
+  const handler = {
+    type: 'mcp_tool', server: 'sphinx', tool: 'sphinx_checkpoint',
+    input: { cwd: '${cwd}', host: name, hookEvent: '${hook_event_name}', hostSession: '${session_id}' },
+    timeout: 1800, statusMessage: 'Sphinx understanding check',
+  };
+  return [
+    // Codex uses the handler's statusMessage as its /hooks display name too.
+    { event: 'SessionStart', group: { hooks: [{ ...sessionHandler, statusMessage: 'Sphinx session setup' }] } },
+    { event: 'PostToolUse', group: { matcher: 'Bash', hooks: [handler] } },
+    ...(name === 'claude' ? [{ event: 'PostToolUseFailure', group: { matcher: 'Bash', hooks: [handler] } }] : []),
+  ];
+}
+
+export const installedHookSpecs = installed => installed.hooks || [{ event: 'SessionStart', group: { hooks: [installed.handler] } }];
+
+export function hasHook(document, spec) {
+  return !!document.hooks?.[spec.event]?.some(group => {
+    const { hooks, ...metadata } = group;
+    const { hooks: expected, ...expectedMetadata } = spec.group;
+    return same(metadata, expectedMetadata) && hooks?.some(handler => same(handler, expected[0]));
+  });
+}
+
+export function addHook(document, spec) {
+  document.hooks ??= {}; document.hooks[spec.event] ??= [];
+  if (!hasHook(document, spec)) document.hooks[spec.event].push(spec.group);
+}
+
+export function removeHook(document, spec) {
+  let removed = false;
+  const groups = document.hooks?.[spec.event];
+  if (!Array.isArray(groups)) return false;
+  document.hooks[spec.event] = groups.flatMap(group => {
+    const { hooks, ...metadata } = group;
+    const { hooks: expected, ...expectedMetadata } = spec.group;
+    if (!same(metadata, expectedMetadata) || !Array.isArray(hooks)) return [group];
+    const filtered = hooks.filter(handler => { if (!same(handler, expected[0])) return true; removed = true; return false; });
+    return filtered.length ? [{ ...group, hooks: filtered }] : [];
+  });
+  if (!document.hooks[spec.event].length) delete document.hooks[spec.event];
+  if (!Object.keys(document.hooks).length) delete document.hooks;
+  return removed;
+}
+
+export async function prepareMcp({ name, paths, env, cliPath, previous }) {
+  const file = name === 'codex' ? path.join(paths.codexHome, 'config.toml')
+    : path.join(!env.SPHINX_USER_HOME && env.CLAUDE_CONFIG_DIR ? paths.claudeHome : paths.userHome, '.claude.json');
+  if (previous && previous.file !== file) throw new Error(`The ${name} MCP configuration path changed. Uninstall using the previous environment before reinstalling.`);
+  const before = await readText(file), existed = previous?.existed ?? before !== null;
+  if (name === 'claude') {
+    const document = parseJson(before, file);
+    if (document.mcpServers !== undefined && (!document.mcpServers || Array.isArray(document.mcpServers) || typeof document.mcpServers !== 'object')) throw new Error(`Invalid mcpServers object in ${file}`);
+    const existing = document.mcpServers?.sphinx;
+    if (Object.hasOwn(document.mcpServers || {}, 'sphinx') && (!previous || !same(existing, previous.entry))) throw new Error(`Refusing to replace an existing or edited sphinx MCP server in ${file}. Remove or rename that entry first.`);
+    const entry = { type: 'stdio', command: process.execPath, args: [cliPath, 'mcp'], env: { SPHINX_HOME: paths.home }, timeout: 1800000 };
+    document.mcpServers ??= {}; document.mcpServers.sphinx = entry;
+    return { before, after: `${JSON.stringify(document, null, 2)}\n`, record: { kind: 'json', file, existed, entry } };
+  }
+  let base = before || '';
+  if (previous) {
+    if (base.includes(previous.block)) base = base.replace(previous.block, '');
+    else if (before !== null) throw new Error(`Refusing to replace an edited Sphinx MCP block in ${file}. Uninstall first to preserve your edits.`);
+  }
+  if (base.includes(START) || base.includes(END)) throw new Error(`Untracked Sphinx MCP block in ${file}. Remove or rename it before installing.`);
+  assertNoCodexConflict(base, file);
+  const separator = base ? base.endsWith('\n') ? '\n' : '\n\n' : '';
+  const block = `${separator}${START}\n[mcp_servers.sphinx]\ncommand = ${JSON.stringify(process.execPath)}\nargs = ${JSON.stringify([cliPath, 'mcp'])}\ntool_timeout_sec = 1800\nenv = { SPHINX_HOME = ${JSON.stringify(paths.home)} }\n${END}\n`;
+  return { before, after: base + block, record: { kind: 'toml', file, existed, block } };
+}
+
+export async function commitMcp(plan) {
+  if (await readText(plan.record.file) !== plan.before) throw new Error(`Settings changed during installation: ${plan.record.file}. Retry installation.`);
+  await writeText(plan.record.file, plan.after);
+}
+
+export async function rollbackMcp(plan) {
+  if (await readText(plan.record.file) === plan.after) await writeText(plan.record.file, plan.before);
+}
+
+export async function removeMcp(record) {
+  if (!record) return { removed: false, missing: true };
+  const text = await readText(record.file);
+  if (text === null) return { removed: false, missing: true };
+  if (record.kind === 'toml') {
+    if (!text.includes(record.block)) return { removed: false, edited: true };
+    const after = text.replace(record.block, '');
+    await writeText(record.file, !record.existed && !after.trim() ? null : after);
+  } else {
+    const document = parseJson(text, record.file);
+    if (!same(document.mcpServers?.sphinx, record.entry)) return { removed: false, edited: true };
+    delete document.mcpServers.sphinx;
+    if (!Object.keys(document.mcpServers).length) delete document.mcpServers;
+    await writeText(record.file, !record.existed && !Object.keys(document).length ? null : `${JSON.stringify(document, null, 2)}\n`);
+  }
+  return { removed: true };
+}
+
+export async function inspectMcp(record) {
+  if (!record) return false;
+  try {
+    const text = await readText(record.file);
+    if (text === null) return false;
+    return record.kind === 'toml' ? text.includes(record.block) : same(parseJson(text, record.file).mcpServers?.sphinx, record.entry);
+  } catch { return false; }
+}

package/src/agent.js

@@ -0,0 +1,45 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+
+/** Session setup only. Git and native lifecycle hooks control the actual checkpoint. */
+export async function agentHook({ agent, event, input = '', env = process.env }) {
+  if (env.SPHINX_EVALUATOR === '1') return { output: null, exitCode: 0 };
+  if (!['codex', 'claude'].includes(agent)) throw new Error(`Unsupported agent: ${agent}`);
+  let payload;
+  try {
+    payload = typeof input === 'object' && !Buffer.isBuffer(input) ? input : JSON.parse(String(input || '{}'));
+  } catch {
+    throw new Error('Agent hook input must be valid JSON.');
+  }
+  const name = payload?.hook_event_name || event;
+  if (name !== 'SessionStart') return { output: null, exitCode: 0 };
+  if (agent === 'claude' && env.CLAUDE_ENV_FILE && /^[A-Za-z0-9_-]{1,200}$/.test(payload?.session_id || '')) {
+    // Claude's documented SessionStart environment channel tags later Bash calls,
+    // including `git -C` and `cd`, without reading the command or its output.
+    const file = await open(env.CLAUDE_ENV_FILE, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW || 0), 0o600);
+    try { await file.writeFile(`\nexport SPHINX_CLAUDE_SESSION='${payload.session_id}'\n`); }
+    finally { await file.close(); }
+  }
+  return {
+    exitCode: 0,
+    output: {
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: [
+          'Sphinx is installed to help the human retain understanding of agent-assisted changes.',
+          'Repository branch and event policy lives in .sphinxconfig (with .sphinx.json as a legacy fallback). Use `sphinx status --json` to inspect effective policy and pending assessments; do not change policy to avoid a checkpoint.',
+          'Git deterministically requires a checkpoint when repository policy matches a push or commit. For blocking checkpoints it serves a local browser questionnaire and keeps the original Git operation waiting. On macOS the page opens in the background without activating or minimizing the coding window; other environments print the local URL. After the human passes and Git verifies the exact change and policy, that same operation continues automatically. Do not start a duplicate Git operation while it waits.',
+          'Allow enough shell execution time for the human questionnaire. Sphinx waits up to 25 minutes, but the host may cancel the shell sooner. Keep the original process running using the host\'s supported yielding or background execution; do not terminate or duplicate it while the human answers.',
+          'If a local browser questionnaire is unavailable, the installed PostToolUse / PostToolUseFailure MCP hook offers a native questionnaire after Git exits. These fallback forms do not resume an exited Git process; you do not initiate or conduct the interview.',
+          'Sphinx collects the human\'s answers directly in its local browser page, explicit terminal check, or fallback native forms and grades them using an independent evaluator. Only the outcome is returned to you. Do not relay questions through chat, call sphinx answer/explain/dispute for the human, or open its local URL or automate the questionnaire UI.',
+          'Never answer on the human\'s behalf, fabricate a response, read private Sphinx session files or answer keys, or bypass the Git hook to finish the task.',
+          'Respect .sphinxignore and configured exclusions: do not read excluded files to supplement an assessment or send them to the evaluator.',
+          'The form offers learning, dispute, and pause actions. The human chooses them directly. A paused or cancelled check remains incomplete; do not repeatedly retry the Git operation to force another prompt.',
+          'After a fallback questionnaire passes, verify that the original Git operation has exited with a Sphinx blocking failure before retrying it. Never duplicate a waiting operation or repeat a successful operation. A changed commit or destination may require another assessment. Reopen a paused blocking checkpoint only when the human asks and the previous Git process has exited.',
+          'If neither the local page nor native forms are available, report the integration issue and use sphinx doctor to diagnose it. The human can run sphinx check in their own terminal. Do not substitute a chat-based questionnaire or submit answers yourself.',
+          'The assessment is open-book. Helping the human inspect code is encouraged. The coding agent must not grade the response itself.',
+        ].join('\n'),
+      },
+    },
+  };
+}