sphinx-understand 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx-understand",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Outsource your thinking, not your understanding. A comprehension checkpoint for agent-assisted development.",
   "homepage": "https://github.com/parthh01/sphinx#readme",
   "repository": {
@@ -21,11 +21,13 @@
     "test": "node scripts/run-suite.mjs",
     "check": "node --check bin/sphinx.js && node scripts/run-suite.mjs",
     "start": "node bin/sphinx.js",
-    "eval": "node eval/run.js"
+    "eval": "node eval/run.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "files": [
     "bin",
     "src",
+    "scripts/postinstall.js",
     "docs",
     "eval/RESULTS.md",
     "eval/fixtures/known-false-negatives.json",

package/scripts/postinstall.js

@@ -0,0 +1,23 @@
+// Prints a setup hint after `npm install -g`. It changes nothing on the machine.
+// npm 7+ hides lifecycle output, so write to the terminal device directly and
+// stay silent when there is none (CI, Docker, IDEs).
+import { openSync, writeSync, closeSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const env = process.env;
+const global = env.npm_config_global === 'true' || env.npm_config_location === 'global';
+if (global && !(env.CI && !['false', '0'].includes(env.CI))) {
+  const home = env.SPHINX_HOME || path.join(env.SPHINX_USER_HOME || homedir(), '.config', 'sphinx');
+  const setUp = existsSync(path.join(home, 'install.json'));
+  const color = !env.NO_COLOR && env.TERM !== 'dumb';
+  const amber = text => color ? `\x1b[38;5;179m${text}\x1b[0m` : text;
+  const bold = text => color ? `\x1b[1m${text}\x1b[0m` : text;
+  const message = setUp
+    ? `\n  ${amber('sphinx')} updated. Apply it to your Git and agent hooks (your settings are kept):\n\n    ${bold('sphinx install')}\n\n`
+    : `\n  ${amber('sphinx')} is installed. Finish setup to connect Git and your coding agents:\n\n    ${bold('sphinx install')}\n\n`;
+  try {
+    const tty = openSync(process.platform === 'win32' ? 'CON' : '/dev/tty', 'w');
+    try { writeSync(tty, message); } finally { closeSync(tty); }
+  } catch { /* No terminal: nothing to show. */ }
+}

package/src/agent-settings.js

@@ -99,11 +99,9 @@ function assertNoCodexConflict(text, file) {
 }
 
 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',
-  };
+  // A plain command, not an MCP tool call: it needs no MCP connection, so it works
+  // in sessions opened before installation and exits silently when nothing is queued.
+  const handler = { type: 'command', command: sessionHandler.command, 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' }] } },

package/src/agent.js

@@ -1,4 +1,5 @@
 import { constants } from 'node:fs';
+import { browserHandoff } from './lifecycle-integrations.js';
 import { open } from 'node:fs/promises';
 
 /** Session setup only. Git and native lifecycle hooks control the actual checkpoint. */
@@ -12,6 +13,15 @@ export async function agentHook({ agent, event, input = '', env = process.env })
     throw new Error('Agent hook input must be valid JSON.');
   }
   const name = payload?.hook_event_name || event;
+  if (['PostToolUse', 'PostToolUseFailure'].includes(name)) {
+    // Fallback only: Git normally waits in its own hook. Open the browser for a
+    // checkpoint queued by Git, and stay silent when nothing is queued.
+    let notice;
+    try {
+      notice = await browserHandoff({ cwd: typeof payload.cwd === 'string' ? payload.cwd : undefined, host: agent, hostSession: /^[A-Za-z0-9_-]{1,200}$/.test(payload?.session_id || '') ? payload.session_id : undefined, env });
+    } catch { notice = 'Sphinx could not inspect its checkpoint queue. The human can run sphinx doctor and sphinx check in their own terminal. Do not answer for them.'; }
+    return notice ? { exitCode: 0, output: { hookSpecificOutput: { hookEventName: name, additionalContext: notice } } } : { output: null, exitCode: 0 };
+  }
   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,
@@ -30,7 +40,7 @@ export async function agentHook({ agent, event, input = '', env = process.env })
           '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.',
+          'If Git could not keep a questionnaire open, the installed PostToolUse hook opens the same local browser questionnaire after the shell command exits. This fallback does 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.',