create-byan-agent 2.25.0 → 2.26.0

package/install/templates/.claude/hooks/autobench-stop-guard.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — BYAN Auto-Benchmark end-of-turn guard.
+ *
+ * Goal : when the assistant's finished message presents a CHOICE between
+ * options (a fork) but did NOT emit a BYAN-BENCH marker, the agent skipped the
+ * benchmark doctrine. The hook blocks ONCE to force exactly one regeneration in
+ * which the agent re-presents the fork as the compact benchmark table and emits
+ * the marker. It never loops : a block-token keyed on the message content makes
+ * the second pass non-blocking by construction.
+ *
+ * Shipped DISARMED (approach C) : the hook observes and ledgers every turn but
+ * does not block until explicitly armed (enforcement.armed in the config —
+ * config-only, set via the YAML + byan-sync-rules, no loose flag file). Day one
+ * is zero noise / zero latency; the net is pre-built but inert until the user
+ * opts in. A disarmed turn that WOULD have fired is recorded as
+ * observed-disarmed-fork so arming later is an informed decision.
+ *
+ * Detection is ARTIFACT-primary with a regex fallback. The decision order :
+ *   1. MARKER   : a BYAN-BENCH:done|skip marker -> satisfied (the agent already
+ *                 benchmarked, or deliberately skipped a degenerate fork).
+ *   2. NEVER    : y/n confirms and destructive prompts are exempt — we never
+ *                 benchmark "proceed?" or "rm -rf".
+ *   3. ESCAPE   : the session flag (.byan-autobench/off) or the cross-session
+ *                 config opt-out suppresses all blocking.
+ *   4. DISARMED : not armed -> observe + ledger, never block (the default).
+ *   5. BLOCKED  : a block-token for this turn already exists -> the regen pass,
+ *                 do not block again.
+ *   6. FORK     : a fork is present when an AskUserQuestion tool_use artifact is
+ *                 in the finished turn (the unambiguous, primary signal). The
+ *                 choice-language regex is only a LAST-RESORT fallback for
+ *                 inline-prose forks that never called the tool.
+ *
+ * Honest ceiling (GH #28273) : the Stop hook is REACTIVE. It cannot intercept
+ * before the message is displayed; it can only force a regeneration after the
+ * fact. The proactive half is the doctrine the agent self-applies. This hook is
+ * the safety net, not a pre-display filter.
+ *
+ * Non-blocking on any IO/parse error : the hook never traps a turn it cannot
+ * read. Every invocation appends one fire/miss line to the ledger.
+ */
+
+'use strict';
+
+const {
+  loadAutobenchConfig,
+  escapeHatchActive,
+  isArmed,
+  readBlockToken,
+  writeBlockToken,
+  appendLedger,
+  extractLastAssistantText,
+  extractLastAssistantContent,
+  hasChoiceArtifact,
+  turnHash,
+  readStdin,
+  parseJson,
+} = require('./lib/autobench-runtime');
+
+// Reconstruct a RegExp from a {source, flags} config pair. Returns null on a
+// malformed pattern so a single bad config entry never throws the whole hook.
+function compileRegex(spec) {
+  if (!spec || typeof spec.source !== 'string') return null;
+  try {
+    return new RegExp(spec.source, spec.flags || '');
+  } catch {
+    return null;
+  }
+}
+
+function countMatches(text, re) {
+  if (!re) return 0;
+  // A global regex is required to count; clone with the g flag if absent.
+  const g = re.flags.includes('g') ? re : new RegExp(re.source, re.flags + 'g');
+  const m = text.match(g);
+  return m ? m.length : 0;
+}
+
+function anyRegexMatches(text, specs) {
+  if (!Array.isArray(specs)) return false;
+  return specs.some((spec) => {
+    const re = compileRegex(spec);
+    return Boolean(re) && re.test(text);
+  });
+}
+
+// Evaluate the choice-language signals with their per-signal thresholds.
+// A signal fires when : (min_matches present -> >= that many matches) OR
+// (requires_candidates present -> the signal matches AND >= N candidate tokens
+// co-occur) OR (a plain match otherwise).
+function hasChoiceLanguage(text, config) {
+  const specs = (config && config.choice_language) || [];
+  const candidateRe = compileRegex(config && config.candidate_token);
+  const candidateCount = candidateRe ? countMatches(text, candidateRe) : 0;
+
+  return specs.some((spec) => {
+    const re = compileRegex(spec);
+    if (!re) return false;
+
+    if (typeof spec.min_matches === 'number') {
+      return countMatches(text, re) >= spec.min_matches;
+    }
+    if (typeof spec.requires_candidates === 'number') {
+      return re.test(text) && candidateCount >= spec.requires_candidates;
+    }
+    return re.test(text);
+  });
+}
+
+function hasMarker(text, config) {
+  const spec = config && config.marker_patterns && config.marker_patterns.any;
+  const re = compileRegex(spec);
+  return Boolean(re) && re.test(text);
+}
+
+function hasNeverListed(text, config) {
+  return anyRegexMatches(text, config && config.never_list);
+}
+
+// Parse the marker fields (g1/g2/scope) for the ledger. Best-effort : a marker
+// without fields still satisfies; the fields only enrich the audit trail.
+function readMarkerFields(text, config) {
+  const fields = (config && config.marker_fields) || {};
+  const out = {};
+  const g1 = compileRegex(fields.g1);
+  const g2 = compileRegex(fields.g2);
+  const scope = compileRegex(fields.scope);
+  let m;
+  if (g1 && (m = text.match(g1))) out.g1 = Number(m[1]);
+  if (g2 && (m = text.match(g2))) out.g2 = Number(m[1]);
+  if (scope && (m = text.match(scope))) out.scope = m[1];
+  return out;
+}
+
+function markerKind(text, config) {
+  const mp = (config && config.marker_patterns) || {};
+  const doneRe = compileRegex(mp.done);
+  const skipRe = compileRegex(mp.skip);
+  if (doneRe && doneRe.test(text)) return 'done';
+  if (skipRe && skipRe.test(text)) return 'skip';
+  return null;
+}
+
+/**
+ * Pure decision. No IO, no clock — fully unit-testable.
+ *
+ * Inputs : lastAssistantText (the finished prose), artifact (true when an
+ * AskUserQuestion tool_use was in the finished turn — the caller computes this
+ * from the raw content so the decision stays pure), armed (the enforcement gate),
+ * config, escapeHatch, blocked.
+ *
+ * Detection is ARTIFACT-primary : a real fork is present when the artifact is
+ * there OR, as a last-resort fallback, when the choice-language regex matches
+ * inline prose. block is true IFF a fork is present AND no marker AND not
+ * never-listed AND escape-hatch inactive AND ARMED AND not already blocked.
+ *
+ * Returns { block, reason?, ledger } where ledger is the audit record.
+ */
+function decideBench({ lastAssistantText, artifact, armed, config, escapeHatch, blocked }) {
+  const text = lastAssistantText || '';
+
+  const marker = hasMarker(text, config);
+  const neverHit = hasNeverListed(text, config);
+  const choiceLang = hasChoiceLanguage(text, config);
+  const hasArtifact = artifact === true;
+  // ARTIFACT-primary : the structural AskUserQuestion tool_use is the unambiguous
+  // fork signal. The lexical regex is only the fallback for prose forks that
+  // never called the tool.
+  const fork = hasArtifact || choiceLang;
+  const detection = hasArtifact ? 'artifact' : choiceLang ? 'regex-fallback' : null;
+  const armedOn = armed === true;
+
+  const ledger = { neverHit, choiceLang, artifact: hasArtifact, marker, detection, armed: armedOn };
+
+  if (marker) {
+    const kind = markerKind(text, config);
+    Object.assign(ledger, readMarkerFields(text, config));
+    ledger.event = kind === 'skip' ? 'satisfied-skip' : 'satisfied-marker';
+    return { block: false, ledger };
+  }
+  if (neverHit) {
+    ledger.event = 'satisfied-never';
+    return { block: false, ledger };
+  }
+  if (escapeHatch) {
+    ledger.event = 'satisfied-escape';
+    return { block: false, ledger };
+  }
+  if (!armedOn) {
+    // DISARMED by default (approach C) : never block. Record whether a fork WOULD
+    // have fired, so arming later is data-informed, not a blind flip.
+    ledger.event = fork ? 'observed-disarmed-fork' : 'observed-disarmed';
+    return { block: false, ledger };
+  }
+  if (blocked) {
+    // The regen pass : we already blocked this exact content once.
+    ledger.event = 'satisfied-already-blocked';
+    return { block: false, ledger };
+  }
+  if (!fork) {
+    ledger.event = 'no-choice';
+    return { block: false, ledger };
+  }
+
+  // A genuine miss while ARMED : the agent offered a fork without benchmarking it.
+  const reason =
+    (config && config.banners && config.banners.stop_block) ||
+    'Auto-benchmark: you presented a choice without a BYAN-BENCH marker. Re-present it as the compact benchmark table and emit the marker.';
+  ledger.event = 'fired-block';
+  return { block: true, reason, ledger };
+}
+
+if (require.main === module) {
+  (async () => {
+    // Wrap everything : the hook must NEVER trap a turn it cannot read.
+    try {
+      const config = loadAutobenchConfig();
+      const payload = parseJson(await readStdin());
+      const lastAssistantText = extractLastAssistantText(payload);
+      // ARTIFACT-primary signal : read the RAW last-assistant content (the block
+      // array extractLastAssistantText flattens away) so the structural
+      // AskUserQuestion tool_use is visible to the decision.
+      const artifact = hasChoiceArtifact(extractLastAssistantContent(payload));
+
+      const hash = turnHash(lastAssistantText);
+      const escapeHatch = escapeHatchActive(config);
+      const armed = isArmed(config);
+      // Loop-guard : the content-hash block token is primary; stop_hook_active is
+      // an additional belt from the runtime (a prior Stop hook already blocked
+      // this turn), so we never depend on it alone.
+      const blocked = readBlockToken(hash) || payload.stop_hook_active === true;
+
+      const decision = decideBench({ lastAssistantText, artifact, armed, config, escapeHatch, blocked });
+
+      // Audit trail : one JSONL line per invocation. turnHash is content-only;
+      // any timestamp/session comes from the environment, kept out of the pure
+      // decision so it stays deterministic.
+      appendLedger(
+        {
+          turnHash: hash,
+          event: decision.ledger.event,
+          g1: decision.ledger.g1,
+          g2: decision.ledger.g2,
+          scope: decision.ledger.scope,
+          neverHit: decision.ledger.neverHit,
+          choiceLang: decision.ledger.choiceLang,
+          artifact: decision.ledger.artifact,
+          detection: decision.ledger.detection,
+          armed: decision.ledger.armed,
+          marker: decision.ledger.marker,
+          ts: process.env.BYAN_HOOK_TS || undefined,
+          session: process.env.CLAUDE_SESSION_ID || undefined,
+        },
+        config
+      );
+
+      if (!decision.block) {
+        process.stdout.write(JSON.stringify({ continue: true }));
+        process.exit(0);
+      }
+
+      // Block-once : write the token BEFORE emitting the block so the
+      // regenerated turn (same content if the agent fails to fix) is exempt.
+      writeBlockToken(hash);
+      process.stdout.write(
+        JSON.stringify({ decision: 'block', reason: decision.reason, systemMessage: decision.reason })
+      );
+      process.exit(2);
+    } catch {
+      // Last-resort net : on any unexpected failure, let the turn end.
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    }
+  })();
+}
+
+module.exports = {
+  decideBench,
+  hasChoiceLanguage,
+  hasMarker,
+  hasNeverListed,
+  markerKind,
+  readMarkerFields,
+  compileRegex,
+  countMatches,
+};

package/install/templates/.claude/hooks/fact-check-absolutes.js

@@ -16,33 +16,8 @@
  * (not documentation).
  */
 
-const fs = require('fs');
 const path = require('path');
-
-const ABSOLUTES = [
-  /\btoujours\b/i,
-  /\bjamais\b/i,
-  /\bforc[eé]ment\b/i,
-  /\bobviously\b/i,
-  /\balways\b/i,
-  /\bnever\b/i,
-  /\bclearly\b/i,
-  /\bundoubtedly\b/i,
-  /\bfaster than\b/i,
-  /\bbetter than\b/i,
-  /\bplus rapide que\b/i,
-  /\bmeilleur que\b/i,
-];
-
-const SOURCE_MARKERS = [
-  /\bRFC\s*\d+/i,
-  /\bCVE-\d{4}-\d+/i,
-  /https?:\/\//,
-  /\[CLAIM\s+L[1-5]\]/i,
-  /\[FACT\s+USER-VERIFIED/i,
-  /\bsource\s*:/i,
-  /_byan\/knowledge\/sources\.md/,
-];
+const { stripNonClaimZones, findUnsourced } = require('./lib/fact-check-core');
 
 const DOC_EXTS = ['.md', '.mdx', '.rst', '.txt'];
 
@@ -65,24 +40,6 @@ function isExemptPath(filePath) {
   return EXEMPT_PATH_PATTERNS.some((re) => re.test(filePath));
 }
 
-// Strip content that cannot be a claim :
-//   - fenced code blocks ``` ... ```
-//   - inline backticks `...`
-//   - block quotes (lines starting with >)
-//   - regex / array syntax that contains the word as a token
-function stripNonClaimZones(text) {
-  if (!text) return '';
-  return text
-    // Fenced code blocks
-    .replace(/```[\s\S]*?```/g, '')
-    // Inline code
-    .replace(/`[^`\n]+`/g, '')
-    // Markdown block quotes
-    .replace(/^> .*$/gm, '')
-    // Lines that look like list of patterns (e.g. "- toujours")
-    .replace(/^[\s-]*['"]?\b(toujours|jamais|forc[eé]ment|obviously|always|never|clearly|undoubtedly)\b['"]?/gim, '');
-}
-
 function readStdin() {
   return new Promise((resolve) => {
     if (process.stdin.isTTY) return resolve('');
@@ -107,23 +64,6 @@ function extractText(toolName, input) {
   return '';
 }
 
-function findUnsourced(text) {
-  if (!text) return null;
-  for (const re of ABSOLUTES) {
-    const match = text.match(re);
-    if (!match) continue;
-    const idx = match.index || 0;
-    const windowStart = Math.max(0, idx - 240);
-    const windowEnd = Math.min(text.length, idx + match[0].length + 240);
-    const ctx = text.slice(windowStart, windowEnd);
-    const hasSource = SOURCE_MARKERS.some((sm) => sm.test(ctx));
-    if (!hasSource) {
-      return { absolute: match[0], context: text.slice(Math.max(0, idx - 80), idx + 80) };
-    }
-  }
-  return null;
-}
-
 (async () => {
   const raw = await readStdin();
   let payload = {};

package/install/templates/.claude/hooks/fact-check-claims.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — fact-check conversation claims (non-blocking).
+ *
+ * The PreToolUse twin (fact-check-absolutes.js) only fires when the agent
+ * WRITES an unsourced absolute into a doc file. This hook covers the other,
+ * more frequent surface : an unsourced absolute spoken in the assistant's
+ * final turn text. It NUDGES (systemMessage, continue) and never blocks —
+ * spoken claims are noisier than written docs, so a block would trap
+ * legitimate hypotheses/quotes. Same detection engine (fact-check-core).
+ */
+
+'use strict';
+
+const { stripNonClaimZones, findUnsourced } = require('./lib/fact-check-core');
+const { extractLastAssistantText } = require('./lib/transcript-read');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+// Pure decision — no IO. Returns { nudge:false } or { nudge:true, absolute, context }.
+function decideClaim({ lastAssistantText }) {
+  const text = stripNonClaimZones(lastAssistantText || '');
+  const hit = findUnsourced(text);
+  if (!hit) return { nudge: false };
+  return { nudge: true, absolute: hit.absolute, context: hit.context };
+}
+
+function nudgeMessage(hit) {
+  return [
+    `BYAN fact-check : unsourced absolute "${hit.absolute}" in this turn.`,
+    `Context : ...${hit.context}...`,
+    `Consider a source (RFC, CVE, URL, [CLAIM L<n>]) or hedge ("often", "in my tests", "tends to"). Advisory — not blocking.`,
+  ].join('\n');
+}
+
+if (require.main === module) {
+  (async () => {
+    let payload = {};
+    try {
+      const raw = await readStdin();
+      payload = raw ? JSON.parse(raw) : {};
+    } catch {
+      payload = {};
+    }
+
+    let decision = { nudge: false };
+    try {
+      decision = decideClaim({ lastAssistantText: extractLastAssistantText(payload) });
+    } catch {
+      decision = { nudge: false };
+    }
+
+    if (decision.nudge) {
+      process.stdout.write(JSON.stringify({ systemMessage: nudgeMessage(decision), continue: true }));
+    } else {
+      process.stdout.write(JSON.stringify({ continue: true }));
+    }
+  })();
+}
+
+module.exports = { decideClaim, nudgeMessage };

package/install/templates/.claude/hooks/fd-response-check.js

@@ -15,6 +15,10 @@
 
 const fs = require('fs');
 const path = require('path');
+// Shared transcript reader — the real Stop payload has no inline transcript
+// (last_assistant_message + transcript_path JSONL). Without it this hook read an
+// empty turn and never enforced the [FD:PHASE] header live.
+const { extractLastAssistantText } = require('./lib/transcript-read');
 
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const statePath = path.join(projectDir, '_byan-output', 'fd-state.json');
@@ -38,55 +42,42 @@ function readState() {
   }
 }
 
-function extractLastAssistantText(payload) {
-  if (!payload || typeof payload !== 'object') return '';
-  const tx = payload.transcript || payload.messages || [];
-  if (!Array.isArray(tx)) return '';
-  for (let i = tx.length - 1; i >= 0; i--) {
-    const m = tx[i];
-    if (m && m.role === 'assistant') {
-      if (typeof m.content === 'string') return m.content;
-      if (Array.isArray(m.content)) {
-        return m.content
-          .map((c) => (typeof c === 'object' && c.text ? c.text : ''))
-          .join(' ');
-      }
-    }
-  }
-  return '';
-}
+// Pure decision : returns { block, reason? }. No IO — unit-testable.
+function decideFdResponse({ state, lastAssistantText }) {
+  if (!state || ['COMPLETED', 'ABORTED'].includes(state.phase)) return { block: false };
 
-(async () => {
-  const state = readState();
-  if (!state || ['COMPLETED', 'ABORTED'].includes(state.phase)) {
-    process.stdout.write(JSON.stringify({ continue: true }));
-    process.exit(0);
-  }
+  const expected = `[FD:${state.phase}]`;
+  const text = lastAssistantText || '';
+  // Empty text (cannot read the turn) degrades to allow — never trap a turn we
+  // cannot inspect. A present header satisfies.
+  if (!text || text.includes(expected)) return { block: false };
 
-  const raw = await readStdin();
-  let payload = {};
-  try {
-    payload = raw ? JSON.parse(raw) : {};
-  } catch {
-    payload = {};
-  }
+  const reason = `FD active (phase=${state.phase}) but your last response did not include the required header "${expected}". Reformulate your answer starting with ${expected} to confirm you are operating in the correct phase. If you wanted to exit or change phase, call byan_fd_advance first.`;
+  return { block: true, reason };
+}
 
-  const text = extractLastAssistantText(payload);
-  const expected = `[FD:${state.phase}]`;
+if (require.main === module) {
+  (async () => {
+    const state = readState();
+    const raw = await readStdin();
+    let payload = {};
+    try {
+      payload = raw ? JSON.parse(raw) : {};
+    } catch {
+      payload = {};
+    }
 
-  if (!text || text.includes(expected)) {
-    process.stdout.write(JSON.stringify({ continue: true }));
-    process.exit(0);
-  }
+    const decision = decideFdResponse({ state, lastAssistantText: extractLastAssistantText(payload) });
+    if (!decision.block) {
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    }
 
-  const reason = `FD active (phase=${state.phase}) but your last response did not include the required header "${expected}". Reformulate your answer starting with ${expected} to confirm you are operating in the correct phase. If you wanted to exit or change phase, call byan_fd_advance first.`;
+    process.stdout.write(
+      JSON.stringify({ decision: 'block', reason: decision.reason, systemMessage: decision.reason })
+    );
+    process.exit(2);
+  })();
+}
 
-  process.stdout.write(
-    JSON.stringify({
-      decision: 'block',
-      reason,
-      systemMessage: reason,
-    })
-  );
-  process.exit(2);
-})();
+module.exports = { decideFdResponse, extractLastAssistantText };

package/install/templates/.claude/hooks/inject-soul.js

@@ -1,7 +1,14 @@
 #!/usr/bin/env node
 /**
- * SessionStart hook — loads BYAN soul/tao/soul-memory and injects them
- * into the session's initial context via additionalContext.
+ * SessionStart hook — loads BYAN soul + soul-memory and injects them into
+ * the session's initial context via additionalContext. Tao is intentionally
+ * NOT bundled here: inject-tao.js injects the full tao on every
+ * UserPromptSubmit (including the first), so duplicating it at SessionStart
+ * would double-spend ~15 KB per session for no gain.
+ *
+ * Also resets the per-session mid-session-nudge one-shot marker so the
+ * soul-memory-triggers nudge is per-session (not per-lifetime). Without
+ * this reset the one-shot marker, once written, silences the nudge forever.
  *
  * Safe: missing files are skipped silently, script always exits 0.
  */
@@ -9,44 +16,76 @@
 const fs = require('fs');
 const path = require('path');
 
-const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
 // Gen3 puts BYAN's soul files under _byan/agent/byan/; Gen2 keeps them at the
 // _byan/ root. Prefer Gen3 when present, fall back to Gen2 (self-contained so
 // the hook never depends on a require that could fail).
-function soulFile(label) {
+function soulFile(projectDir, label) {
   const g3 = path.join(projectDir, '_byan', 'agent', 'byan', `${label}.md`);
   const g2 = path.join(projectDir, '_byan', `${label}.md`);
   return fs.existsSync(g3) ? g3 : g2;
 }
 
-const files = [
-  { label: 'soul', path: soulFile('soul') },
-  { label: 'tao', path: soulFile('tao') },
-  { label: 'soul-memory', path: soulFile('soul-memory') },
-];
+// Same resolution as soul-memory-triggers.js: Gen3 _byan/memoire/ first, Gen2
+// _byan/_memory/ fallback. Kept in sync by hand (hooks avoid shared requires).
+function nudgeMarkerPath(projectDir) {
+  const memoireDir = path.join(projectDir, '_byan', 'memoire');
+  const memoryDir = fs.existsSync(memoireDir)
+    ? memoireDir
+    : path.join(projectDir, '_byan', '_memory');
+  return path.join(memoryDir, '.soul-memory-nudge-sent');
+}
 
-const chunks = [];
-for (const f of files) {
+// Reset the one-shot nudge marker at session start so the mid-session
+// soul-memory nudge can fire once per session instead of once per lifetime.
+function resetNudgeMarker(projectDir) {
   try {
-    if (fs.existsSync(f.path)) {
-      const content = fs.readFileSync(f.path, 'utf8').trim();
-      if (content.length > 0) {
-        chunks.push(`=== BYAN ${f.label.toUpperCase()} (${path.relative(projectDir, f.path)}) ===\n${content}`);
-      }
-    }
+    fs.rmSync(nudgeMarkerPath(projectDir), { force: true });
+    return true;
   } catch {
-    // Ignore read errors — hook must never block session start.
+    return false;
   }
 }
 
-const additionalContext =
-  chunks.length > 0
+function buildAdditionalContext(projectDir) {
+  const files = [
+    { label: 'soul', path: soulFile(projectDir, 'soul') },
+    { label: 'soul-memory', path: soulFile(projectDir, 'soul-memory') },
+  ];
+
+  const chunks = [];
+  for (const f of files) {
+    try {
+      if (fs.existsSync(f.path)) {
+        const content = fs.readFileSync(f.path, 'utf8').trim();
+        if (content.length > 0) {
+          chunks.push(
+            `=== BYAN ${f.label.toUpperCase()} (${path.relative(projectDir, f.path)}) ===\n${content}`
+          );
+        }
+      }
+    } catch {
+      // Ignore read errors — hook must never block session start.
+    }
+  }
+
+  return chunks.length > 0
     ? `BYAN Soul System (loaded at session start):\n\n${chunks.join('\n\n')}`
     : '';
+}
 
-if (additionalContext) {
-  process.stdout.write(JSON.stringify({ systemMessage: additionalContext }));
-} else {
-  process.stdout.write('{}');
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  resetNudgeMarker(projectDir);
+  const additionalContext = buildAdditionalContext(projectDir);
+  if (additionalContext) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
+      })
+    );
+  } else {
+    process.stdout.write('{}');
+  }
 }
+
+module.exports = { soulFile, nudgeMarkerPath, resetNudgeMarker, buildAdditionalContext };