phronesis 1.0.0 → 1.1.0

package/src/compile.js

@@ -15,22 +15,45 @@ import { existsSync } from 'node:fs';
 import { readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import fse from 'fs-extra';
 import {
-  DEFAULT_DOMAIN,
   compileAccept,
   compileReject,
   digestFile,
   readEvents,
+  resolveDomain,
   resolveInstall,
   resumeCompileAccept,
 } from '@phronesis/core';
 
-export async function runCompileAccept({ draftPath, session, surface, dir } = {}) {
+export async function runCompileAccept({ draftPath, session, surface, dir, reviewedDigest } = {}) {
   if (!draftPath) {
     console.error('compile accept: name the <draft_path> to promote (a .phronesis/drafts/… candidate).');
     process.exitCode = 1;
     return null;
   }
   try {
+    // --reviewed-digest (Fable F1b): re-hash the draft IN THIS CHILD, immediately before compileAccept,
+    // and refuse if the current bytes differ from the bytes the operator reviewed — closing the
+    // engine→child spawn-window byte race at the true promotion boundary. Backward-compatible: absent →
+    // no check (a bare `compile accept` is unchanged).
+    if (typeof reviewedDigest === 'string' && reviewedDigest !== '') {
+      const installed = resolveInstall({ dir, cwd: process.cwd() });
+      if (installed.error) {
+        console.error(installed.error);
+        process.exitCode = 1;
+        return null;
+      }
+      let current = null;
+      try {
+        current = await digestFile(join(installed.root, draftPath));
+      } catch {
+        current = null;
+      }
+      if (current === null || current !== reviewedDigest) {
+        console.error('compile accept: this draft changed since it was reviewed (reviewed content_digest mismatch) — not promoted; re-review.');
+        process.exitCode = 1;
+        return null;
+      }
+    }
     // actor is NOT threaded — accept events are operator-driven by contract (the core
     // hard-sets it). The approval signal still travels on PHRONESIS_APPROVAL_SOURCE.
     const result = await compileAccept({
@@ -207,13 +230,35 @@ function remainingDrafts(journal) {
   return journal.planned.filter((d) => !journal.cursors[d]?.accepted?.done);
 }
 
+// The reviewed-manifest digest binding (Codex R5 F1): true iff the draft's CURRENT bytes still equal
+// the operator-reviewed digest persisted in the journal. Enforced at EVERY accept — the initial loop
+// AND resume — so a re-draft after the manifest check (or across a crash) can never promote unreviewed
+// bytes. Backward-compatible: a journal with no reviewed digest for this path (plain approve-all) → true.
+async function reviewedDigestOk(installRoot, journal, draftRel) {
+  const reviewed = journal.reviewed_digests?.[draftRel];
+  if (reviewed === undefined) return true;
+  let current = null;
+  try {
+    current = await digestFile(join(installRoot, draftRel));
+  } catch {
+    current = null;
+  }
+  return current !== null && current === reviewed;
+}
+
 export async function runCompileReview({
-  domain = DEFAULT_DOMAIN,
+  domain,
   dir,
   session,
   surface = 'cli',
   rationale,
   approveAll = false,
+  // --approve-only <comma-list|array>: bind approve-all to a caller-reviewed SUBSET of the batch-
+  // eligible drafts (the drafts an operator actually saw + confirmed), so a draft that becomes
+  // eligible AFTER the review but before promotion is NOT swept in. This is a subset FILTER on which
+  // eligible drafts promote — it does NOT change batch-eligibility (digest-match + suspicious-excluded
+  // stay exactly as classifyDrafts/security.md define them). Absent → promote all eligible (unchanged).
+  approveOnly,
   resume = false,
   json = false,
   now,
@@ -233,16 +278,84 @@ export async function runCompileReview({
 
   if (resume) return resumeReview({ installRoot, session, surface, json, now });
 
-  const draftRels = await listPendingDrafts(installRoot, domain);
-  const { eligible, excluded } = await classifyDrafts(installRoot, draftRels);
+  // core-0061 D4: review is a domain-scoped verb; resolve through the shared resolver so a
+  // single-domain install (whatever its slug) reviews the right drafts and a multi-domain
+  // install refuses rather than guessing. No --domain + cwd not inside a domain → sole
+  // registered domain wins; several registered → refuse and list.
+  let resolvedDomain;
+  try {
+    const registry = JSON.parse(await readFile(join(installRoot, '.phronesis', 'registry.json'), 'utf8'));
+    resolvedDomain = resolveDomain({ installRoot, registry, domain, cwd: process.cwd() });
+  } catch (err) {
+    console.error(`compile review: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+
+  const draftRels = await listPendingDrafts(installRoot, resolvedDomain);
+  const classified = await classifyDrafts(installRoot, draftRels);
+  let eligible = classified.eligible;
+  const { excluded } = classified;
 
   if (!approveAll) {
-    const plan = { domain, batch_eligible: eligible, individual_review: excluded };
+    // The plan surfaces the FULL eligible set (the caller reviews it); --approve-only applies only to
+    // the approve-all promotion below.
+    const plan = { domain: resolvedDomain, batch_eligible: eligible, individual_review: excluded };
     if (json) console.log(JSON.stringify(plan, null, 2));
     else printPlan(plan);
     return plan;
   }
 
+  // Bind the promotion to the caller's reviewed subset (never a super-set of what they confirmed). Each
+  // --approve-only entry is a path OR a `path=digest` manifest entry:
+  //   - path binding: an eligible draft NOT in the reviewed set is skipped (reported in not_reviewed),
+  //     never swept in.
+  //   - digest binding (Codex R4 F1): a manifest digest must equal the draft's CURRENT bytes, so a
+  //     same-path RE-DRAFT (new bytes + a fresh matching candidate — which classifyDrafts still calls
+  //     eligible) is dropped to digest_mismatch and never promoted. Fail-closed: unreadable / missing /
+  //     mismatched digest excludes it. This binds promoted BYTES to the bytes the operator reviewed.
+  // A path in --approve-only that is no longer classifyDrafts-eligible (digest-vs-candidate / suspicious
+  // / gone) already sits in `excluded`.
+  let notReviewed = [];
+  let digestMismatch = [];
+  // The operator-reviewed digest per path (from a `path=digest` manifest). Hoisted so it can be
+  // PERSISTED in the journal and re-enforced at every accept, incl. across a crash/resume (Codex R5 F1).
+  const digestByPath = new Map();
+  if (approveOnly !== undefined) {
+    const only = new Set();
+    for (const entry of (Array.isArray(approveOnly) ? approveOnly : String(approveOnly).split(',')).map((s) => String(s).trim()).filter(Boolean)) {
+      // path or path=digest. Paths contain '/', digests are hex — split on the LAST '='.
+      const eq = entry.lastIndexOf('=');
+      if (eq > 0) {
+        only.add(entry.slice(0, eq));
+        digestByPath.set(entry.slice(0, eq), entry.slice(eq + 1));
+      } else {
+        only.add(entry);
+      }
+    }
+    notReviewed = eligible.filter((d) => !only.has(d));
+    eligible = eligible.filter((d) => only.has(d));
+    if (digestByPath.size > 0) {
+      const kept = [];
+      for (const draftRel of eligible) {
+        const expected = digestByPath.get(draftRel);
+        if (expected === undefined) {
+          kept.push(draftRel); // a path-only entry (no byte binding requested)
+          continue;
+        }
+        let current = null;
+        try {
+          current = await digestFile(join(installRoot, draftRel));
+        } catch {
+          current = null;
+        }
+        if (current !== null && current === expected) kept.push(draftRel);
+        else digestMismatch.push({ draftRel, reason: 'draft bytes changed since the operator reviewed them (reviewed-manifest content_digest mismatch) — re-review' });
+      }
+      eligible = kept;
+    }
+  }
+
   // Never overwrite an existing batch journal with a fresh approve-all. A COMPLETED batch clears
   // its journal (below), so a journal present here means a prior batch crashed/failed mid-way and
   // still holds the ONLY recovery receipt for its half-moved drafts (their intent + status
@@ -280,9 +393,9 @@ export async function runCompileReview({
     return null;
   }
   if (!eligible.length) {
-    const out = { batch_id: null, accepted: [], excluded };
+    const out = { batch_id: null, accepted: [], excluded, not_reviewed: notReviewed, digest_mismatch: digestMismatch };
     if (json) console.log(JSON.stringify(out, null, 2));
-    else console.log(`compile review: no batch-eligible drafts under ${domain} (${excluded.length} routed to individual review).`);
+    else console.log(`compile review: no batch-eligible drafts under ${resolvedDomain} in the reviewed set (${excluded.length} individual review; ${notReviewed.length} not reviewed; ${digestMismatch.length} reviewed-bytes changed).`);
     return out;
   }
 
@@ -291,7 +404,11 @@ export async function runCompileReview({
   // Record the batch's start time (created_ts) so resume's out-of-band check can tell THIS batch's
   // terminal events from a STALE prior review of the same — REUSED — draft path (Codex round-3 F2;
   // the resumable-mutation rule: reconcile by recorded identity, never a non-unique key like a path).
-  const journal = { batch_id: batchId, rationale, domain, session, surface, created_ts: (now || new Date()).toISOString(), planned: [...eligible], cursors: {} };
+  // Persist the operator-reviewed digest for each planned draft, so the binding survives a crash and
+  // is re-enforced on resume (Codex R5 F1). Empty for a plain approve-all (backward-compatible).
+  const reviewed_digests = {};
+  for (const p of eligible) if (digestByPath.has(p)) reviewed_digests[p] = digestByPath.get(p);
+  const journal = { batch_id: batchId, rationale, domain: resolvedDomain, session, surface, created_ts: (now || new Date()).toISOString(), planned: [...eligible], reviewed_digests, cursors: {} };
   await writeJournal(installRoot, journal);
 
   const accepted = [];
@@ -310,6 +427,13 @@ export async function runCompileReview({
       failed.push({ draftRel, error: `draft changed since classification — not promoted (${reason})` });
       continue;
     }
+    // Reviewed-digest binding, re-enforced immediately before THIS accept (Codex R5 F1): a draft
+    // re-drafted AFTER the up-front manifest check (a fresh clean candidate — so classifyDrafts above
+    // passes) must not promote bytes the operator never reviewed. Fail-closed on any difference.
+    if (!(await reviewedDigestOk(installRoot, journal, draftRel))) {
+      failed.push({ draftRel, error: 'draft bytes changed since the operator reviewed them (reviewed-manifest content_digest mismatch) — not promoted; re-review' });
+      continue;
+    }
     const recordBoundary = makeRecordBoundary(installRoot, draftRel, journal);
     try {
       const r = await compileAccept({
@@ -334,7 +458,7 @@ export async function runCompileReview({
 
   const remaining = remainingDrafts(journal);
   if (!remaining.length) await clearJournal(installRoot);
-  const out = { batch_id: batchId, rationale, accepted, failed, excluded, remaining };
+  const out = { batch_id: batchId, rationale, accepted, failed, excluded, remaining, not_reviewed: notReviewed, digest_mismatch: digestMismatch };
   if (json) console.log(JSON.stringify(out, null, 2));
   else printReviewResult(out);
   if (failed.length) process.exitCode = 1;
@@ -435,6 +559,13 @@ async function resumeReview({ installRoot, session, surface, json, now }) {
           failed.push({ draftRel, error: 'no longer provably clean on resume (L4) — routed to individual review' });
           continue;
         }
+        // Reviewed-digest binding, re-enforced on RESUME too (Codex R5 F1): a draft re-drafted between
+        // the crash and this resume (a fresh clean candidate — so L4 above passes) must not promote
+        // bytes the operator never reviewed. The reviewed digest was persisted in the journal.
+        if (!(await reviewedDigestOk(installRoot, journal, draftRel))) {
+          failed.push({ draftRel, error: 'draft bytes changed since the operator reviewed them (reviewed-manifest content_digest mismatch) — not promoted; re-review' });
+          continue;
+        }
         const r = await compileAccept({
           dir: installRoot,
           cwd: process.cwd(),

package/src/doctor.js

@@ -24,9 +24,10 @@ import { resolveInstall, resolveHooks, RE_SLUG, validateScheduleRegistry, schedu
 import { registryJson } from './layout.js';
 import { skillsStatusReport } from './skills.js';
 import { codexAdapterReport } from './adapter.js';
+import { inspectLauncher } from './launcher.js';
 
 // The fixed check id set (D6) — the --json contract asserts on exactly these.
-export const DOCTOR_CHECK_IDS = ['install_root', 'domain', 'skills', 'hooks', 'adapter_codex', 'user_profile', 'pending_drafts', 'schedule'];
+export const DOCTOR_CHECK_IDS = ['install_root', 'launcher', 'domain', 'skills', 'hooks', 'adapter_codex', 'user_profile', 'pending_drafts', 'schedule', 'provider'];
 
 function isExecutable(p) {
   try {
@@ -51,7 +52,7 @@ function isFileParseableJson(p) {
 
 // Build the structured doctor report — PURE w.r.t. the install (read-only). Returns the D6 shape:
 // { root, checks:[{ id, status, detail }], summary:{ ok, warn, fail }, exit }.
-export async function doctorReport({ dir } = {}) {
+export async function doctorReport({ dir, home, pathEnv } = {}) {
   const checks = [];
   const add = (id, status, detail) => checks.push({ id, status, detail });
   // Run a check body; turn ANY throw into a check of `failClass` (never a crash — F2/F3).
@@ -73,6 +74,11 @@ export async function doctorReport({ dir } = {}) {
   const root = installed.root;
   add('install_root', 'ok', root);
 
+  // launcher (change 0065 D7) — inspect the managed dispatcher + manifest and PATH without
+  // executing ANY candidate. A broken/absent launcher disables external automation but does not
+  // corrupt the workspace itself, so it is WARN-level; doctor remains a report, never a fixer.
+  await guarded('launcher', 'warn', () => launcherHealth({ home, pathEnv }));
+
   // Shared registry read — a present-but-corrupt registry.json (resolveInstall passes on existence)
   // fails the registry-derived checks, never crashes (F3).
   let registry = null;
@@ -143,9 +149,33 @@ export async function doctorReport({ dir } = {}) {
   // hard contract check lives. Read-only (validateScheduleRegistry + scheduleStaleness are pure).
   await guarded('schedule', 'warn', () => scheduleHealth(root));
 
+  // provider (change 0050) — read out the model-routing block (active provider + per-tier ids) so
+  // the model-swap surface is visible in the health overview. Non-secret POINTERS only: doctor never
+  // reads or prints key material (keys are app-side; invariant #4 / change 0051). Absent or malformed
+  // is WARN, never fail — routing config is optional and pre-0050 installs are valid without it.
+  await guarded('provider', 'warn', () => providerRouting(root));
+
   return finalize(root, checks);
 }
 
+function launcherHealth({ home, pathEnv } = {}) {
+  const report = inspectLauncher({ ...(home === undefined ? {} : { home }), ...(pathEnv === undefined ? {} : { pathEnv }) });
+  const pathDetail = report.pathCandidate
+    ? `PATH probe: ${report.pathCandidate}`
+    : 'PATH probe: no executable phronesis found';
+  if (!report.compliant) {
+    return [
+      'warn',
+      `${report.issues.map((issue) => issue.detail).join('; ')}; ${pathDetail}`,
+    ];
+  }
+  const m = report.manifest;
+  return [
+    'ok',
+    `managed dispatcher + launcher.env valid (owner=${m.PHR_BACKEND}, version=${m.PHR_VERSION}, generation=${m.PHR_GENERATION}); target + runtime current; ${pathDetail}`,
+  ];
+}
+
 function finalize(root, checks) {
   const summary = { ok: 0, warn: 0, fail: 0 };
   for (const c of checks) summary[c.status] += 1;
@@ -251,6 +281,37 @@ function gitignoreCoversState(root) {
   }
 }
 
+async function providerRouting(root) {
+  const cfgPath = join(root, '.phronesis', 'config.json');
+  if (!existsSync(cfgPath)) {
+    return ['warn', 'no .phronesis/config.json — model-routing provider block not configured (change 0050)'];
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+  } catch (err) {
+    return ['warn', `.phronesis/config.json unreadable (${err.message}) — provider routing not shown`];
+  }
+  const p = cfg && typeof cfg === 'object' ? cfg.provider : null;
+  if (!p || typeof p !== 'object' || typeof p.id !== 'string' || typeof p.model !== 'string') {
+    return ['warn', 'provider routing block absent or malformed (expected provider.id + provider.model) — change 0050'];
+  }
+  // Non-secret pointers only — never keys (keys are app-side; invariant #4 / change 0051).
+  const tiers =
+    p.tiers && typeof p.tiers === 'object'
+      ? p.tiers
+      : p.perProvider && typeof p.perProvider === 'object' && p.perProvider[p.id]
+        ? p.perProvider[p.id]
+        : null;
+  const tierStr = tiers
+    ? ['standard', 'large', 'frontier', 'utility']
+        .filter((k) => typeof tiers[k] === 'string')
+        .map((k) => `${k}=${tiers[k]}`)
+        .join(', ') || '(no per-tier ids)'
+    : '(no per-tier ids configured)';
+  return ['ok', `active provider: ${p.id}; model: ${p.model}; tiers: ${tierStr}`];
+}
+
 async function pendingDrafts(root) {
   const base = join(root, '.phronesis', 'drafts');
   if (!existsSync(base)) return ['ok', 'no pending compile drafts'];

package/src/hook.js

@@ -0,0 +1,312 @@
+// `phronesis hook <event> --surface <surface>` — the single resolved executable interface
+// used by every emitted hook script (change 0065 D2). Surface scripts only resolve one CLI
+// binary and hand stdin through; JSON parsing, install discovery, core calls, and output shaping
+// live here inside the runtime carried by the managed launcher.
+
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import {
+  abandonActiveSkillInvocation,
+  appendEvent,
+  beginSkillInvocation,
+  completeActiveSkillInvocation,
+  refreshActiveContext,
+  resolveInstall,
+  runContextRelevanceGuard,
+  sweepStaleSkillInvocation,
+  sweepStatus,
+} from '@phronesis/core';
+import { collectHooksDueCheck, meshZeroWarningMessage } from './hooks.js';
+import { launcherPaths } from './launcher.js';
+
+export const HOOK_EVENTS = Object.freeze([
+  'recall-guard',
+  'session-start',
+  'session-sweep',
+  'session-sweep-subagent',
+  'session-sweep-precompact',
+  'skill-lifecycle',
+  'compile-active-context',
+]);
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function parseInput(raw) {
+  try {
+    const parsed = JSON.parse(String(raw ?? ''));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function markerExists(root) {
+  return Boolean(root) && existsSync(join(root, '.phronesis', 'registry.json'));
+}
+
+// Preserve the old surface resolution order: a validated Codex-provided root, then a validated
+// Claude project root, then nearest-marker walk-up from cwd. A bad hint never overrides a real
+// install discoverable from cwd.
+function hookInstallRoot() {
+  for (const candidate of [process.env.PHRONESIS_DIR, process.env.CLAUDE_PROJECT_DIR]) {
+    if (markerExists(candidate)) return realpathOr(candidate);
+  }
+  const installed = resolveInstall({ cwd: process.cwd() });
+  return installed.root || null;
+}
+
+function realpathOr(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function safeSurface(value) {
+  const clean = String(value || 'claude-code').replace(/[^a-z0-9-]/g, '');
+  return clean || 'claude-code';
+}
+
+function actor() {
+  return process.env.PHRONESIS_ACTOR || 'agent';
+}
+
+function modelFacingPhronesis() {
+  const managedPath = launcherPaths({ home: homedir() }).dispatcher;
+  try {
+    const state = lstatSync(managedPath);
+    if (state.isFile() && !state.isSymbolicLink() && (state.mode & 0o111) !== 0) {
+      return managedPath;
+    }
+  } catch {
+    // A missing or unreadable managed slot falls back to the PATH-resolved command.
+  }
+  return 'phronesis';
+}
+
+export function domainFromCwd(root, cwd) {
+  if (!root || !cwd) return undefined;
+  const rel = relative(realpathOr(root), realpathOr(cwd));
+  const parts = rel.split(sep);
+  return parts[0] === 'domains' && parts[1] ? parts[1] : undefined;
+}
+
+function writeJson(value) {
+  process.stdout.write(JSON.stringify(value));
+}
+
+async function recallGuard({ input, installRoot, surface }) {
+  const session = typeof input?.session_id === 'string' ? input.session_id : '';
+  const prompt = typeof input?.prompt === 'string' ? input.prompt : '';
+  if (!session || !prompt || !installRoot) return;
+  try {
+    const eventCwd = typeof input.cwd === 'string' ? input.cwd : process.cwd();
+    const result = await runContextRelevanceGuard({
+      installRoot,
+      cwd: process.cwd(),
+      prompt,
+      session,
+      surface,
+      actor: actor(),
+      domain: domainFromCwd(installRoot, eventCwd),
+      env: process.env,
+    });
+    if (result?.fired === true && typeof result.packet === 'string' && result.packet.trim()) {
+      writeJson({
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: result.packet,
+        },
+      });
+    }
+  } catch {
+    // Recall is add-only. A malformed prompt or broken guard degrades quietly, matching the
+    // previous adapter's guarded node process and never blocking prompt submission.
+  }
+}
+
+async function sessionStart({ input, installRoot, surface }) {
+  const session = typeof input?.session_id === 'string' ? input.session_id : '';
+  if (!session || !installRoot) return;
+
+  try {
+    await sweepStaleSkillInvocation({ installRoot, session });
+  } catch (err) {
+    console.error(`hook session-start: ${err.message}`);
+  }
+  try {
+    await appendEvent({
+      installRoot,
+      type: 'session.start',
+      session_id: session,
+      actor: actor(),
+      surface,
+      payload: { surface },
+    });
+  } catch (err) {
+    console.error(`hook session-start: ${err.message}`);
+  }
+  try {
+    const due = await collectHooksDueCheck({ installRoot, session, actor: actor(), surface });
+    if (!due.output) return;
+    if (surface === 'codex') {
+      writeJson({
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          additionalContext: due.output,
+        },
+      });
+    } else {
+      process.stdout.write(`${due.output}\n`);
+    }
+  } catch (err) {
+    console.error(`hook session-start: ${err.message}`);
+  }
+}
+
+async function completeLifecycle({ installRoot, session, input, boundaryEvent, surface }) {
+  try {
+    const hookInput = { ...(input || {}) };
+    if (!hookInput.hook_event_name) hookInput.hook_event_name = boundaryEvent;
+    const result = await completeActiveSkillInvocation({
+      installRoot,
+      session,
+      hookInput,
+      reason: boundaryEvent,
+      surface,
+    });
+    if (result?.warning) writeJson({ systemMessage: meshZeroWarningMessage(result.warning) });
+  } catch (err) {
+    console.error(`hook session-sweep: ${err.message}`);
+  }
+}
+
+function sweepReminder(session, installRoot, phronesis) {
+  return `Phronesis sweep reminder: context is about to compact. Review the conversation for unstored decisions, people, and commitments — emit *.candidate events / run the action types, then mark the sweep: "${phronesis}" event emit session.end --session ${session} --dir ${installRoot} --payload '{"sweep":{"candidates":N}}' (candidates 0 = honest negative).`;
+}
+
+function sweepBlock(session, installRoot, phronesis) {
+  return {
+    decision: 'block',
+    reason:
+      `Phronesis capture sweep (session ${session}): before ending, review this conversation for anything that should have been stored — decisions made, people/context learned, commitments given. ` +
+      `Emit a typed candidate for each ("${phronesis}" event emit decision.candidate|person.candidate|commitment.candidate --session ${session} --dir ${installRoot} --payload ...) and/or run the matching action types ("${phronesis}" act ... --dir ${installRoot}). ` +
+      `Then mark the sweep — honestly, 0 candidates is a valid answer: "${phronesis}" event emit session.end --session ${session} --dir ${installRoot} --payload '{"sweep":{"candidates":N}}'. After the marker is emitted, stop again.`,
+  };
+}
+
+async function sessionSweep({ event, input, installRoot, surface }) {
+  const session = typeof input?.session_id === 'string' ? input.session_id : '';
+  if (!session || !installRoot) return;
+
+  if (event === 'session-sweep-subagent') {
+    await completeLifecycle({ installRoot, session, input, boundaryEvent: 'SubagentStop', surface });
+    return;
+  }
+
+  let swept = false;
+  try {
+    swept = (await sweepStatus({ installRoot, session })).swept;
+  } catch {
+    // A failed status read is conservatively pending, matching the old shell `if` branch.
+  }
+  // Preserve the old branch order: an already-swept PreCompact is silent, while a pending
+  // PreCompact emits its reminder before the Stop loop guard is considered.
+  if (swept) {
+    if (event === 'session-sweep') {
+      await completeLifecycle({ installRoot, session, input, boundaryEvent: 'Stop', surface });
+    }
+    return;
+  }
+  if (event === 'session-sweep-precompact') {
+    const phronesis = modelFacingPhronesis();
+    const reminder = sweepReminder(session, installRoot, phronesis);
+    if (surface === 'codex') writeJson({ systemMessage: reminder });
+    else process.stdout.write(`${reminder}\n`);
+    return;
+  }
+  if (input.stop_hook_active === true) {
+    await completeLifecycle({ installRoot, session, input, boundaryEvent: 'Stop', surface });
+    return;
+  }
+  const phronesis = modelFacingPhronesis();
+  process.stdout.write(`${JSON.stringify(sweepBlock(session, installRoot, phronesis))}\n`);
+}
+
+async function skillLifecycle({ input, installRoot, surface, mode }) {
+  if (!installRoot || (mode !== 'start' && mode !== 'abandon')) return;
+  try {
+    if (mode === 'start') {
+      await beginSkillInvocation({ installRoot, hookInput: input || {}, surface });
+    } else {
+      await abandonActiveSkillInvocation({
+        installRoot,
+        hookInput: input || {},
+        reason: 'StopFailure',
+        surface,
+      });
+    }
+  } catch (err) {
+    console.error(`hook skill-lifecycle: ${err.message}`);
+  }
+}
+
+async function compileActiveContext({ input, installRoot }) {
+  const path = typeof input?.payload?.path === 'string' ? input.payload.path : '';
+  const parts = path.split('/');
+  const domain = parts[0] === 'domains' && parts[1] ? parts[1] : '';
+  if (!domain || !installRoot) return;
+  try {
+    const registry = JSON.parse(readFileSync(join(installRoot, '.phronesis', 'registry.json'), 'utf8'));
+    if (!Array.isArray(registry.domains) || !registry.domains.includes(domain)) return;
+    await refreshActiveContext({ installRoot, domain });
+  } catch (err) {
+    console.error(`hook compile-active-context: ${err.message}`);
+  }
+}
+
+export async function runHook({ event, surface: surfaceArg, mode } = {}) {
+  const surface = safeSurface(surfaceArg);
+  const input = parseInput(await readStdin());
+  const installRoot = hookInstallRoot();
+
+  if (!HOOK_EVENTS.includes(event)) {
+    console.error(`hook: unknown event "${event || ''}" (expected: ${HOOK_EVENTS.join(' | ')}).`);
+    process.exitCode = 1;
+    return null;
+  }
+  if (!installRoot && event !== 'recall-guard') {
+    console.error(`hook ${event}: no phronesis install found from ${process.cwd()}`);
+  }
+
+  switch (event) {
+    case 'recall-guard':
+      await recallGuard({ input, installRoot, surface });
+      break;
+    case 'session-start':
+      await sessionStart({ input, installRoot, surface });
+      break;
+    case 'session-sweep':
+    case 'session-sweep-subagent':
+    case 'session-sweep-precompact':
+      await sessionSweep({ event, input, installRoot, surface });
+      break;
+    case 'skill-lifecycle':
+      await skillLifecycle({ input, installRoot, surface, mode });
+      break;
+    case 'compile-active-context':
+      await compileActiveContext({ input, installRoot });
+      break;
+  }
+
+  // Surface hooks are non-blocking by contract. Valid events always exit 0 even when an internal
+  // best-effort operation reported an error on stderr.
+  process.exitCode = 0;
+  return { event, surface };
+}