@ngockhoale/ukit 2.2.2 → 2.2.4

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -1,35 +1,20 @@
-// ukit-bridge.js — omp hook bridge for UKit.
+// ukit-bridge.js — omp extension bridge for UKit.
 //
-// Bridge, don't fork (PLAN.md D1): the 18 `.sh` scripts under
-// `.claude/hooks/` are the single source of truth for hook behaviour across
-// both Claude Code and omp. This module never re-implements their logic in
-// JS. It only:
-//   1. Maps an omp event + tool name onto the ordered list of scripts that
-//      `.claude/settings.json` would have run for the equivalent Claude Code
-//      event (see HOOK_EVENT_MAP, generated by hand from
-//      `templates/.claude/settings.json` — keep them in sync).
-//   2. Builds the same stdin JSON payload the scripts already expect
-//      (hook_event_name, tool_name, tool_input, session_id, cwd, ...).
-//   3. Executes each script via `pi.exec()` (never spawns/copies the script
-//      body) and translates the exit code back into an omp-shaped result.
-//
-// Event NAMES are verified against omp v17.4.2 (2026-08-22): its extension API
-// registers `tool_call`, `tool_result`, `turn_start`, `session_start`,
-// `session.compacting` and `session_compact` exactly as spelled below.
-//
-// `pi.exec`'s argument shape is still unverified — the contract chosen below (see
-// the doc comments on each exported function) is internally consistent and is
-// exercised end-to-end against a fake `pi` in tests/hooks/ompHookBridge.test.js,
-// but nothing here has observed omp actually invoking it.
+// The scripts under `.claude/hooks/` remain the single source of hook behavior.
+// This adapter normalizes omp's v17.4.2 extension events into Claude Code hook
+// payloads, executes the same ordered script chains, and translates only the
+// result fields that omp consumes.
 
+import fs from 'node:fs';
 import path from 'node:path';
-
-// ---------------------------------------------------------------------------
-// Event -> script mapping (hand-derived from templates/.claude/settings.json;
-// keep this literally in sync with that file — case 1 in
-// tests/hooks/ompHookBridge.test.js re-parses settings.json and asserts
-// exact equality against this table).
-// ---------------------------------------------------------------------------
+import { fileURLToPath } from 'node:url';
+import {
+  evaluateCompletion,
+  incrementContinuation,
+  readExecutionLedger,
+  readRouteState,
+  recordExecutionReceipt,
+} from '../../../.claude/ukit/runtime/execution-ledger.mjs';
 
 export const HOOK_EVENT_MAP = {
   tool_call: {
@@ -53,38 +38,32 @@ export const HOOK_EVENT_MAP = {
     ],
   },
   tool_result: {
-    'Edit|Write': ['post-edit-verify.sh'],
-    Bash: ['compress-output.sh'],
+    'Read|Grep|Glob': ['record-execution.sh'],
+    'Edit|Write': ['post-edit-verify.sh', 'record-execution.sh'],
+    Bash: ['compress-output.sh', 'record-execution.sh'],
   },
-  turn_start: ['skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
+  before_agent_start: ['skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
   session_start: ['auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh'],
 };
 
-// ---------------------------------------------------------------------------
-// Tool-name mapping (PLAN.md D2).
-//
-// omp's write surface is `edit`, `write`, AND `ast_edit` — `ast_edit` must
-// map to the same `Edit` matcher group as `edit`/`write`, or it silently
-// bypasses protect-files.sh / vision-gate.sh. `eval` is omp's shell-capable
-// tool and must map to `Bash` to hit block-dangerous.sh / verification-guard.sh.
-// Any tool name not in this table maps to `null`, which runs ZERO scripts —
-// it must never silently fall back to Bash or Edit.
-// ---------------------------------------------------------------------------
-
 const TOOL_NAME_MAP = {
   read: 'Read',
+  read_file: 'Read',
   grep: 'Grep',
   glob: 'Glob',
   edit: 'Edit',
   write: 'Write',
   ast_edit: 'Edit',
+  apply_patch: 'Edit',
   eval: 'Bash',
   bash: 'Bash',
+  shell: 'Bash',
 };
 
 export function mapToolName(ompToolName) {
-  return TOOL_NAME_MAP[ompToolName] ?? null;
+  const normalized = String(ompToolName ?? '').trim().toLowerCase().replaceAll('-', '_');
+  return TOOL_NAME_MAP[normalized] ?? null;
 }
 
 function matcherGroupFor(claudeToolName) {
@@ -100,14 +79,6 @@ function matcherGroupFor(claudeToolName) {
   return null;
 }
 
-// ---------------------------------------------------------------------------
-// Fail-direction classification (PLAN.md D3). Not a blanket rule -- each
-// script's own header documents its own fail direction; this table is a
-// transcription of those 18 headers, not an invented policy. Gate scripts
-// fail CLOSED (non-zero/throw => block). Advisory scripts fail OPEN
-// (non-zero/throw => log a warning, never block).
-// ---------------------------------------------------------------------------
-
 export const FAIL_CLOSED_SCRIPTS = new Set([
   'protect-files.sh',
   'stale-spec-guard.sh',
@@ -120,6 +91,7 @@ export const FAIL_CLOSED_SCRIPTS = new Set([
 
 export const ADVISORY_SCRIPTS = new Set([
   'skill-router.sh',
+  'record-execution.sh',
   'auto-allow-bash.sh',
   'pre-edit-backup.sh',
   'vision-router.sh',
@@ -133,46 +105,47 @@ export const ADVISORY_SCRIPTS = new Set([
 ]);
 
 function classifyFailure(scriptName) {
-  if (FAIL_CLOSED_SCRIPTS.has(scriptName)) return 'closed';
-  if (ADVISORY_SCRIPTS.has(scriptName)) return 'open';
-  // Unclassified script (should not happen for the 18 known scripts): fail
-  // open by default rather than blocking on an unknown quantity.
-  return 'open';
+  return FAIL_CLOSED_SCRIPTS.has(scriptName) ? 'closed' : 'open';
+}
+
+function runtimeMetadata(event = {}, context = {}) {
+  const sessionManager = context?.sessionManager;
+  return {
+    sessionId: event.sessionId ?? event.session_id ?? sessionManager?.getSessionId?.(),
+    cwd: context?.cwd ?? event.cwd,
+    transcriptPath: event.transcriptPath ?? event.transcript_path ?? sessionManager?.getSessionFile?.(),
+  };
 }
 
-// ---------------------------------------------------------------------------
-// Payload + result translation.
-// ---------------------------------------------------------------------------
-
-/**
- * Builds the same stdin JSON shape the `.sh` scripts already read via
- * `INPUT=$(cat)`. Fields the caller does not supply are simply omitted --
- * the scripts already degrade gracefully when optional fields (e.g.
- * transcript_path, prompt) are absent (see context-window-guard.sh, which
- * exits 0 immediately when transcript_path is missing).
- */
-function buildHookPayload(hookEventName, { toolName, toolInput, sessionId, cwd, prompt, transcriptPath } = {}) {
+function buildHookPayload(hookEventName, fields = {}) {
   const payload = { hook_event_name: hookEventName };
-  if (toolName !== undefined) payload.tool_name = toolName;
-  if (toolInput !== undefined) payload.tool_input = toolInput;
-  if (sessionId !== undefined) payload.session_id = sessionId;
-  if (cwd !== undefined) payload.cwd = cwd;
-  if (prompt !== undefined) payload.prompt = prompt;
-  if (transcriptPath !== undefined) payload.transcript_path = transcriptPath;
+  const mappings = [
+    ['toolName', 'tool_name'],
+    ['toolInput', 'tool_input'],
+    ['toolOutput', 'tool_output'],
+    ['toolResult', 'tool_result'],
+    ['toolUseId', 'tool_use_id'],
+    ['sessionId', 'session_id'],
+    ['cwd', 'cwd'],
+    ['prompt', 'prompt'],
+    ['transcriptPath', 'transcript_path'],
+    ['source', 'source'],
+  ];
+  for (const [field, payloadField] of mappings) {
+    if (fields[field] !== undefined && fields[field] !== null) {
+      payload[payloadField] = fields[field];
+    }
+  }
   return payload;
 }
 
-/**
- * Translates a single script's `pi.exec` outcome into a bridge-internal
- * verdict. Exit 0 => pass. Exit 2 => this script's own explicit "block"
- * signal, regardless of gate/advisory class (mirrors Claude Code's own
- * "exit 2 = block, stderr = reason" contract). Any other non-zero exit, or
- * a thrown error, is resolved via the script's fail-direction classification.
- */
 function translateExecResult(scriptName, execResult) {
-  const code = execResult?.code ?? 0;
+  const killed = Boolean(execResult?.killed);
+  const code = killed ? 1 : (execResult?.code ?? 0);
   const stdout = execResult?.stdout ?? '';
-  const stderr = execResult?.stderr ?? '';
+  const stderr = killed
+    ? (execResult?.stderr || `${scriptName} was killed before it completed`)
+    : (execResult?.stderr ?? '');
 
   if (code === 0) {
     return { block: false, stdout, stderr };
@@ -180,9 +153,7 @@ function translateExecResult(scriptName, execResult) {
   if (code === 2) {
     return { block: true, reason: stderr || `${scriptName} exited 2 (blocked)`, stdout, stderr };
   }
-
-  const direction = classifyFailure(scriptName);
-  if (direction === 'closed') {
+  if (classifyFailure(scriptName) === 'closed') {
     return {
       block: true,
       reason: stderr || `${scriptName} exited ${code} (failing closed)`,
@@ -190,179 +161,342 @@ function translateExecResult(scriptName, execResult) {
       stderr,
     };
   }
-  return { block: false, warning: `${scriptName} exited ${code} (failing open): ${stderr || 'no stderr'}`, stdout, stderr };
+  return {
+    block: false,
+    warning: `${scriptName} exited ${code} (failing open): ${stderr || 'no stderr'}`,
+    stdout,
+    stderr,
+  };
 }
 
 export { translateExecResult };
 
-// ---------------------------------------------------------------------------
-// Script chain runner -- shared by every event handler below. Keeps the
-// fail-direction / short-circuit / context-accumulation logic in exactly
-// one place.
-// ---------------------------------------------------------------------------
-
-/**
- * Runs `scripts` (basenames under `.claude/hooks/`) in order via
- * `pi.exec(absoluteScriptPath, { input: JSON.stringify(payload) })`,
- * short-circuiting on the first block. Returns
- *   { block, reason?, context, invoked }
- * where `context` is the concatenation of each script's trimmed, non-empty
- * stdout (used by session.compacting / session_start to surface
- * reinject-context.sh / handoff-resume.sh output back to omp).
- */
-export async function runScriptChain(pi, scripts, payload, { projectRoot }) {
-  const invoked = [];
-  const contextParts = [];
+const HOOK_CHAIN_TIMEOUT_MS = 12000;
 
-  for (const scriptName of scripts) {
-    const scriptPath = path.join(projectRoot, '.claude', 'hooks', scriptName);
-    invoked.push(scriptName);
+function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-errors');
+    fs.mkdirSync(dir, { recursive: true });
+    const safeSession = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+    fs.appendFileSync(path.join(dir, `${safeSession}.jsonl`), `${JSON.stringify(diagnostic)}\n`, 'utf8');
+  } catch {
+    // Diagnostics are advisory and must never block or throw.
+  }
+}
 
-    let execResult;
-    try {
-      execResult = await pi.exec(scriptPath, { input: JSON.stringify(payload) });
-    } catch (err) {
-      execResult = { code: 1, stdout: '', stderr: err?.message ?? String(err) };
-    }
+export async function runScriptChain(
+  pi,
+  scripts,
+  payload,
+  { projectRoot, failClosedOnTransportError = false },
+) {
+  const invoked = [];
+  const context = [];
+  if (scripts.length === 0) {
+    return { block: false, context, invoked };
+  }
 
-    const verdict = translateExecResult(scriptName, execResult);
+  const runnerPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'hook-chain-runner.mjs');
+  const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
+  // Do not blindly trust process.execPath: under a Bun-hosted omp, it points at bun, not node.
+  const nodeExecutable = process.env.UKIT_NODE_PATH || process.execPath;
+  const startedAt = Date.now();
+  let execResult;
+  try {
+    execResult = await pi.exec(
+      nodeExecutable,
+      [runnerPath, JSON.stringify(payload), ...scriptPaths],
+      { cwd: projectRoot, timeout: HOOK_CHAIN_TIMEOUT_MS },
+    );
+  } catch (error) {
+    execResult = { code: 1, stdout: '', stderr: error?.message ?? String(error), killed: false };
+  }
+  const elapsedMs = Date.now() - startedAt;
 
-    if (verdict.stdout && verdict.stdout.trim()) {
-      contextParts.push(verdict.stdout.trim());
+  let chainResult = null;
+  let parseError = null;
+  if (!execResult?.killed) {
+    try {
+      chainResult = JSON.parse(execResult?.stdout || '{}');
+    } catch (error) {
+      parseError = error;
     }
+  }
 
-    if (verdict.warning) {
-      pi.logger?.warn?.(verdict.warning);
+  const hasUsableResults = Boolean(chainResult) && Array.isArray(chainResult.results) && chainResult.results.length > 0;
+  const transportFailed = Boolean(execResult?.killed) || Boolean(parseError) || Boolean(chainResult?.wrapperError) || !hasUsableResults;
+
+  if (transportFailed) {
+    // The aggregate runner produced no verifiable per-script verdict. Never relabel this as a
+    // specific fail-closed script's decision -- that script may never have run.
+    const diagnostic = {
+      ts: Date.now(),
+      scripts,
+      killed: Boolean(execResult?.killed),
+      code: execResult?.code ?? null,
+      stdoutLength: (execResult?.stdout || '').length,
+      stderr: execResult?.stderr || '',
+      elapsedMs,
+      nodeExecutable,
+      nodeVersion: process.version,
+      runnerPath,
+      parseError: parseError?.message || null,
+      wrapperError: chainResult?.wrapperError || null,
+    };
+    recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    const reason = `UKit OMP hook runner failed before producing a valid result `
+      + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
+      + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
+      + `See .ukit/storage/cache/hook-errors/.`;
+    if (failClosedOnTransportError) {
+      return { block: true, reason, context, invoked };
     }
+    pi.logger?.warn?.(`[UKit] ${reason}`);
+    return { block: false, context, invoked };
+  }
 
+  for (const item of chainResult.results) {
+    const scriptName = item?.scriptName;
+    if (!scriptName || !scripts.includes(scriptName)) continue;
+    invoked.push(scriptName);
+    const verdict = translateExecResult(scriptName, item);
+    if (verdict.stdout?.trim()) context.push(verdict.stdout.trim());
+    if (verdict.warning) pi.logger?.warn?.(`[UKit] ${verdict.warning}`);
     if (verdict.block) {
-      return { block: true, reason: verdict.reason, context: contextParts.join('\n'), invoked };
+      return { block: true, reason: verdict.reason, context, invoked };
     }
   }
 
-  return { block: false, context: contextParts.join('\n'), invoked };
+  return { block: false, context, invoked };
 }
 
-// ---------------------------------------------------------------------------
-// Event handlers (all exported directly for test import; wired onto `pi.on`
-// by the default export below).
-// ---------------------------------------------------------------------------
-
 function scriptsForToolCall(claudeToolName) {
   const matcherGroup = matcherGroupFor(claudeToolName);
-  if (!matcherGroup) return [];
-  return HOOK_EVENT_MAP.tool_call[matcherGroup] ?? [];
+  return matcherGroup ? (HOOK_EVENT_MAP.tool_call[matcherGroup] ?? []) : [];
 }
 
 function scriptsForToolResult(claudeToolName) {
   const matcherGroup = matcherGroupFor(claudeToolName);
-  // tool_result only has script chains for Edit|Write and Bash.
-  if (matcherGroup !== 'Edit|Write' && matcherGroup !== 'Bash') return [];
-  return HOOK_EVENT_MAP.tool_result[matcherGroup] ?? [];
+  return matcherGroup ? (HOOK_EVENT_MAP.tool_result[matcherGroup] ?? []) : [];
 }
 
-/**
- * @param {object} event - { tool, input, sessionId, cwd }
- */
-export async function runToolCall(pi, event, { projectRoot }) {
-  const toolName = mapToolName(event.tool);
-  const scripts = scriptsForToolCall(toolName);
+function normalizeToolInput(toolName, input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return input ?? {};
+  const normalized = { ...input };
+  if ((toolName === 'Edit' || toolName === 'Write') && !normalized.file_path) {
+    const paths = Array.isArray(normalized.paths) ? normalized.paths.filter(Boolean) : [];
+    normalized.file_path = normalized.path || paths[0] || undefined;
+  }
+  return normalized;
+}
+
+function looksMutationCapable(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return false;
+  const hasTarget = Boolean(input.file_path || input.path || (Array.isArray(input.paths) && input.paths.length));
+  const hasMutation = [
+    'content',
+    'new_string',
+    'old_string',
+    'patch',
+    'replacement',
+    'edits',
+  ].some((key) => input[key] !== undefined);
+  return hasTarget && hasMutation;
+}
+
+function textFromContent(content) {
+  return (Array.isArray(content) ? content : [])
+    .filter((item) => item?.type === 'text' && typeof item.text === 'string')
+    .map((item) => item.text)
+    .join('\n');
+}
+
+function hookContextMessage(content) {
+  return {
+    customType: 'ukit-hook-context',
+    content,
+    display: false,
+  };
+}
+
+function sendContext(pi, context, deliverAs) {
+  const content = context.filter(Boolean).join('\n').trim();
+  if (!content || typeof pi.sendMessage !== 'function') return;
+  pi.sendMessage(hookContextMessage(content), { deliverAs });
+}
+
+export async function runToolCall(pi, event, { projectRoot, context: extensionContext = {} }) {
+  const rawToolName = event.toolName ?? event.tool;
+  const toolName = mapToolName(rawToolName);
+  if (!toolName && looksMutationCapable(event.input)) {
+    return {
+      block: true,
+      reason: `UKit blocked unmapped mutation-capable tool "${rawToolName}"; add a host adapter mapping before retrying.`,
+      context: [],
+      invoked: [],
+      toolName,
+    };
+  }
+
+  const metadata = runtimeMetadata(event, extensionContext);
   const payload = buildHookPayload('PreToolUse', {
     toolName,
-    toolInput: event.input,
-    sessionId: event.sessionId,
-    cwd: event.cwd,
+    toolInput: normalizeToolInput(toolName, event.input),
+    toolUseId: event.toolCallId,
+    ...metadata,
+  });
+  // Only Edit|Write stays fail-closed on a bridge/runner transport failure; Bash and
+  // Read|Grep|Glob fail open so diagnosis/recovery tools are never bricked by a runner outage.
+  const failClosedOnTransportError = matcherGroupFor(toolName) === 'Edit|Write';
+  const result = await runScriptChain(pi, scriptsForToolCall(toolName), payload, {
+    projectRoot,
+    failClosedOnTransportError,
   });
-  const result = await runScriptChain(pi, scripts, payload, { projectRoot });
+  if (!result.block) sendContext(pi, result.context, 'steer');
   return { ...result, toolName };
 }
 
-export async function runToolResult(pi, event, { projectRoot }) {
-  const toolName = mapToolName(event.tool);
-  const scripts = scriptsForToolResult(toolName);
+export async function runToolResult(pi, event, { projectRoot, context: extensionContext = {} }) {
+  const toolName = mapToolName(event.toolName ?? event.tool);
+  const metadata = runtimeMetadata(event, extensionContext);
+  const outputText = textFromContent(event.content);
+  const toolOutput = {
+    ...(event.details && typeof event.details === 'object' ? event.details : {}),
+    output: outputText,
+    stdout: outputText,
+    exitCode: event.details?.exitCode,
+    isError: Boolean(event.isError),
+    details: event.details,
+  };
   const payload = buildHookPayload('PostToolUse', {
     toolName,
-    toolInput: event.input,
-    sessionId: event.sessionId,
-    cwd: event.cwd,
+    toolInput: normalizeToolInput(toolName, event.input),
+    toolOutput,
+    toolResult: {
+      content: event.content,
+      details: event.details,
+      isError: Boolean(event.isError),
+    },
+    toolUseId: event.toolCallId,
+    ...metadata,
   });
-  const result = await runScriptChain(pi, scripts, payload, { projectRoot });
-  return { ...result, toolName };
+  const result = await runScriptChain(pi, scriptsForToolResult(toolName), payload, { projectRoot });
+  try {
+    await recordExecutionReceipt({
+      projectRoot,
+      payload,
+      toolName,
+      harness: 'omp',
+    });
+  } catch (error) {
+    pi.logger?.warn?.(`[UKit] execution receipt failed open: ${error?.message || error}`);
+  }
+
+  const hookOutput = result.context.join('\n').trim();
+  if (!hookOutput) return undefined;
+  if (toolName === 'Bash') {
+    return {
+      content: [{ type: 'text', text: hookOutput }],
+      details: event.details,
+      isError: Boolean(event.isError),
+    };
+  }
+  return {
+    content: [
+      ...(Array.isArray(event.content) ? event.content : []),
+      { type: 'text', text: hookOutput },
+    ],
+    details: event.details,
+    isError: Boolean(event.isError),
+  };
 }
 
-export async function runTurnStart(pi, event, { projectRoot }) {
+export async function runBeforeAgentStart(pi, event, { projectRoot, context: extensionContext = {} }) {
+  const metadata = runtimeMetadata(event, extensionContext);
   const payload = buildHookPayload('UserPromptSubmit', {
-    sessionId: event.sessionId,
-    cwd: event.cwd,
     prompt: event.prompt,
+    ...metadata,
   });
-  return runScriptChain(pi, HOOK_EVENT_MAP.turn_start, payload, { projectRoot });
+  const result = await runScriptChain(pi, HOOK_EVENT_MAP.before_agent_start, payload, { projectRoot });
+  const parts = [...result.context];
+  if (result.block && result.reason) parts.push(result.reason);
+  const content = parts.join('\n').trim();
+  return content ? { message: hookContextMessage(content) } : undefined;
 }
 
-// `session_before_compact`'s CANCEL capability is explicitly out of scope
-// this cycle (PLAN.md Known gaps) -- this bridge does not wire that event.
-export async function runSessionCompacting(pi, event, { projectRoot }) {
-  const payload = buildHookPayload('PreCompact', {
-    sessionId: event.sessionId,
-    cwd: event.cwd,
-    transcriptPath: event.transcriptPath,
-  });
-  return runScriptChain(pi, HOOK_EVENT_MAP['session.compacting'], payload, { projectRoot });
+export async function runSessionCompacting(pi, event, { projectRoot, context: extensionContext = {} }) {
+  const metadata = runtimeMetadata(event, extensionContext);
+  const payload = buildHookPayload('PreCompact', metadata);
+  const result = await runScriptChain(pi, HOOK_EVENT_MAP['session.compacting'], payload, { projectRoot });
+  return result.context.length > 0 ? { context: result.context } : undefined;
 }
 
-// Claude Code's `SessionStart` entry in settings.json carries NO matcher, so it
-// fires on every source including `compact`. Reaching that same behaviour on omp
-// takes two events, not one -- see runSessionCompact below.
-//
-// handoff-resume.sh is idempotent by design (reads + prints the
-// docs/AI_HANDOFF/RUN.md cursor, never advances state), so running this chain
-// more than once in a session is safe (PLAN.md D11).
-export async function runSessionStart(pi, event, { projectRoot }) {
-  const payload = buildHookPayload('SessionStart', {
-    sessionId: event.sessionId,
-    cwd: event.cwd,
-  });
-  return runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+export async function runSessionStart(pi, event, { projectRoot, context: extensionContext = {} }) {
+  const metadata = runtimeMetadata(event, extensionContext);
+  const payload = buildHookPayload('SessionStart', metadata);
+  const result = await runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+  sendContext(pi, result.context, 'nextTurn');
+  return result;
 }
 
-// RESOLVED 2026-08-22 against a real omp v17.4.2 install. PLAN.md D11 carried this
-// as a `TODO(verify)`: "does omp emit `session_start` on a post-compact
-// continuation?" It does not -- and it does not need to, because omp exposes a
-// dedicated post-compaction event instead. Its extension API registers
-// `session_before_compact` -> `session.compacting` -> `session_compact`, the last
-// firing after compaction settles and carrying the resulting `compactionEntry`.
-//
-// Without this handler the omp side lost the whole post-compact chain: the run
-// cursor stayed un-surfaced, compact pressure was never reset, and a mid-cycle
-// handoff silently failed to resume after a compaction -- the exact failure the
-// plan named. Mapping `session_compact` onto the SAME script chain restores
-// parity with Claude Code's matcher-less SessionStart.
-//
-// The payload keeps `hook_event_name: 'SessionStart'` deliberately: the scripts
-// are shared with Claude Code and know that name, and Claude Code reaches them by
-// the same event with `source: "compact"`. Inventing an omp-only event name here
-// would mean forking the scripts, which is what this bridge exists to avoid.
-export async function runSessionCompact(pi, event, { projectRoot }) {
-  const payload = buildHookPayload('SessionStart', {
-    sessionId: event.sessionId,
-    cwd: event.cwd,
-    source: 'compact',
-  });
-  return runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+export async function runSessionCompact(pi, event, { projectRoot, context: extensionContext = {} }) {
+  const metadata = runtimeMetadata(event, extensionContext);
+  const payload = buildHookPayload('SessionStart', { ...metadata, source: 'compact' });
+  const result = await runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+  sendContext(pi, result.context, 'nextTurn');
+  return undefined;
+}
+
+export async function runSessionStop(
+  pi,
+  event,
+  {
+    projectRoot,
+    context: extensionContext = {},
+    state: suppliedState,
+    ledger: suppliedLedger,
+  },
+) {
+  const metadata = runtimeMetadata(event, extensionContext);
+  const payload = buildHookPayload('Stop', metadata);
+  const state = suppliedState ?? await readRouteState(projectRoot);
+  const ledger = suppliedLedger ?? await readExecutionLedger(projectRoot, payload) ?? {};
+  const evaluation = evaluateCompletion({ state, ledger });
+  if (!evaluation.continue) {
+    if (evaluation.capped) pi.logger?.warn?.(`[UKit] ${evaluation.reason}`);
+    return undefined;
+  }
+
+  if (suppliedLedger === undefined) {
+    try {
+      await incrementContinuation(projectRoot, payload, ledger);
+    } catch (error) {
+      pi.logger?.warn?.(`[UKit] continuation bookkeeping failed open: ${error?.message || error}`);
+    }
+  }
+  return {
+    continue: true,
+    additionalContext: evaluation.reason,
+  };
 }
 
-// ---------------------------------------------------------------------------
-// Default export -- omp hook factory contract: `export default function
-// hook(pi) { pi.on(event, handler) }`.
-// ---------------------------------------------------------------------------
+function installedProjectRoot() {
+  const bridgeDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(bridgeDir, '../../..');
+}
 
 export default function hook(pi) {
-  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-  pi.on('tool_call', (event) => runToolCall(pi, event, { projectRoot }));
-  pi.on('tool_result', (event) => runToolResult(pi, event, { projectRoot }));
-  pi.on('turn_start', (event) => runTurnStart(pi, event, { projectRoot }));
-  pi.on('session.compacting', (event) => runSessionCompacting(pi, event, { projectRoot }));
-  pi.on('session_start', (event) => runSessionStart(pi, event, { projectRoot }));
-  pi.on('session_compact', (event) => runSessionCompact(pi, event, { projectRoot }));
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || installedProjectRoot();
+
+  pi.on('tool_call', (event, context) => {
+    return runToolCall(pi, event, { projectRoot, context }).then((result) => (
+      result.block ? { block: true, reason: result.reason } : undefined
+    ));
+  });
+  pi.on('tool_result', (event, context) => runToolResult(pi, event, { projectRoot, context }));
+  pi.on('before_agent_start', (event, context) => runBeforeAgentStart(pi, event, { projectRoot, context }));
+  pi.on('session.compacting', (event, context) => runSessionCompacting(pi, event, { projectRoot, context }));
+  pi.on('session_start', (event, context) => runSessionStart(pi, event, { projectRoot, context }));
+  pi.on('session_compact', (event, context) => runSessionCompact(pi, event, { projectRoot, context }));
+  pi.on('session_stop', (event, context) => runSessionStop(pi, event, { projectRoot, context }));
 }