@ngockhoale/ukit 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.3 - 2026-08-26
+
+Sessions were stalling mid-task — the model would read source, then simply stop, with the work half done and nothing wrong upstream. This wave stops treating that as a prompting problem. Instructions asking a model to "continue until the edit is made" are advisory by nature: every hidden backend behind `unic-lite` / `unic-code` / `unic-smart` / `unic-vision` reads them slightly differently, and the ones that read them loosely stall. UKit now records what actually happened — real Edit/Write receipts, real verification exit codes — and enforces completion mechanically at the point of stopping, identically on Claude Code and omp. Nothing in the enforcement path branches on provider branding.
+
+### Fixed
+
+- **Silent stalls were unenforceable, because nothing measured them.** A stop after a read-only pass was indistinguishable from a stop after finished work: both were just the model ending its turn. UKit now keeps a session-scoped execution ledger (`.ukit/storage/cache/exec-ledger/<session>.json`) recording source reads, write attempts and outcomes, and verification commands with their exit codes. A new `Stop` hook (`completion-gate.sh`, and omp's `session_stop`) reads it against the routed contract's `completionEvidence` and blocks a premature stop with the specific missing evidence and a recovery instruction matched to the actual state — no source yet, failed write, no write, failed verification, or no verification each get different guidance. Recovery is capped at 6 continuations, then degrades to a warning, so the gate can never loop.
+- **The omp bridge could exceed omp's own handler budget and freeze the session.** A single `Edit` fired 7 hook scripts as 7 serial `pi.exec` subprocesses at up to 8s each — worst case well past omp's ~30s outer timeout, which surfaces to the user as the session simply hanging. They now run in one bounded `hook-chain-runner.mjs` process: 4s per script, 10s total budget, under a 12s outer timeout. Per-event latency is appended to `.ukit/storage/cache/hook-latency/<session>.jsonl` so hook cost stops being invisible.
+- **omp writes bypassed the safety gates entirely.** omp's `normalizeToolEventInput` emits `path` / `paths`; every UKit hook script reads `file_path`. So `protect-files.sh` and `stale-spec-guard.sh` saw no target on an omp edit and waved it through. The bridge now normalizes `path` / `paths[0]` → `file_path` at the host boundary, without mutating the caller's event.
+- **An unmapped mutation-capable tool failed open and silently.** `mapToolName` returned `null` for any tool not in its table, and the bridge ran an empty script chain — so a host tool that writes files but is not yet mapped skipped every guard with no signal. Such tools are now blocked with a message naming the tool; unmapped read-only tools still pass through.
+- **The ledger CLI silently did nothing under a symlinked project root.** Its main-guard compared `fileURLToPath(import.meta.url)` against `path.resolve(process.argv[1])`. Under macOS `/tmp` → `/private/tmp`, or any symlinked work directory, those differ — so `--record` and `--evaluate-stop` returned exit 0 having done nothing: no receipts, no gate. The whole unit suite stayed green; only a scratch install under `/tmp` exposed it. Both paths are now compared by realpath, covered by `tests/hooks/executionLedgerCli.test.js`.
+- **`.omp/config.yml` documented the model aliases backwards**, calling the UNIC names "LITERAL model names, not aliases". They are stable provider-neutral aliases whose hidden backends change during development — which is precisely why orchestration must not branch on vendor names.
+
+### Added
+
+- **`tests/hooks/executionLedgerCli.test.js`** (4 tests) — drives the real CLI through a symlinked root: receipts get written, a premature stop is blocked, a stop with write + passing verification is allowed, and the continuation cap engages at exactly 6. Verified RED against the pre-fix guard (3 of 4 fail).
+- **Manifest entries and dev-mirror parity for the four new files** — `record-execution.sh`, `completion-gate.sh`, `execution-ledger.mjs`, `hook-chain-runner.mjs`. `templates/.claude/` is gitignored and existing template files were force-added, so new ones are invisible to both git and `npm pack` unless added the same way; verified present in the packed tarball, with hook scripts executable after a real `ukit install`.
+
 ## 2.2.2 - 2026-08-22
 
 Running Claude Code and omp side by side exposed that they were not, in fact, running the same UKit. `CLAUDE.md` and `AGENTS.md` are hand-maintained forks of one instruction set read by different harnesses, and `AGENTS.md` had fallen three minor versions behind — so omp was never told the model-tier table existed. This wave re-unifies them and adds a test that makes the drift impossible to repeat.

package/manifests/platform.full.yaml

@@ -1037,6 +1037,30 @@ items:
     packs:
       - core
 
+  - id: hook-record-execution
+    type: hook
+    sourceTemplate: .claude/hooks/record-execution.sh
+    targetPath: .claude/hooks/record-execution.sh
+    requires:
+      - ukit-runtime-execution-ledger-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-completion-gate
+    type: hook
+    sourceTemplate: .claude/hooks/completion-gate.sh
+    targetPath: .claude/hooks/completion-gate.sh
+    requires:
+      - ukit-runtime-execution-ledger-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-auto-allow-bash
     type: hook
     sourceTemplate: .claude/hooks/auto-allow-bash.sh
@@ -1223,6 +1247,28 @@ items:
     packs:
       - core
 
+  - id: ukit-runtime-execution-ledger-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/execution-ledger.mjs
+    targetPath: .claude/ukit/runtime/execution-ledger.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-runtime-hook-chain-runner-script
+    type: config
+    sourceTemplate: .claude/ukit/runtime/hook-chain-runner.mjs
+    targetPath: .claude/ukit/runtime/hook-chain-runner.mjs
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-runtime-safe-patch-core-script
     type: config
     sourceTemplate: .claude/ukit/runtime/safe-patch-core.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/hooks/completion-gate.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Stop hook: block premature terminal stops while routed completion evidence is missing.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop

package/templates/.claude/hooks/record-execution.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# PostToolUse hook: persist session-scoped source/write/verification receipts.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+
+if [ ! -f "$SCRIPT" ]; then
+  exit 0
+fi
+
+printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --record

package/templates/.claude/settings.json

@@ -139,6 +139,16 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Read|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write",
         "hooks": [
@@ -146,6 +156,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
           }
         ]
       },
@@ -156,6 +171,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
+            "timeout": 4
           }
         ]
       }
@@ -181,6 +201,17 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
+            "timeout": 4
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "hooks": [

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LEDGER_VERSION = 1;
+const MAX_RECEIPTS = 24;
+const MAX_CONTINUATIONS = 6;
+const IMPLEMENT_MODES = new Set([
+  'tiny-fix',
+  'local-fix',
+  'local-build',
+  'shared-edit',
+  'find-cause',
+]);
+
+function safeSegment(value) {
+  return String(value || 'default')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 96) || 'default';
+}
+
+function firstDefined(values) {
+  return values.find((value) => value !== undefined && value !== null);
+}
+
+function sessionIdentity(payload = {}) {
+  const sessionId = firstDefined([
+    payload.session_id,
+    payload.sessionId,
+  ]);
+  if (sessionId) return safeSegment(sessionId);
+
+  const transcriptPath = firstDefined([
+    payload.transcript_path,
+    payload.transcriptPath,
+  ]);
+  if (transcriptPath) {
+    return `transcript-${crypto.createHash('sha256').update(String(transcriptPath)).digest('hex').slice(0, 20)}`;
+  }
+  return 'default';
+}
+
+function ledgerPath(projectRoot, payload = {}) {
+  return path.join(
+    projectRoot,
+    '.ukit',
+    'storage',
+    'cache',
+    'exec-ledger',
+    `${sessionIdentity(payload)}.json`,
+  );
+}
+
+async function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+export async function readRouteState(projectRoot) {
+  return readJson(path.join(projectRoot, '.claude', 'ukit', 'skill-router-state.json'), null);
+}
+
+export async function readExecutionLedger(projectRoot, payload = {}) {
+  return readJson(ledgerPath(projectRoot, payload), null);
+}
+
+function explicitError(payload = {}) {
+  return [
+    payload.isError,
+    payload.is_error,
+    payload.tool_output?.isError,
+    payload.tool_output?.is_error,
+    payload.tool_result?.isError,
+    payload.tool_result?.is_error,
+    payload.tool_response?.isError,
+    payload.tool_response?.is_error,
+  ].some((value) => value === true);
+}
+
+function extractExitCode(payload = {}) {
+  const candidates = [
+    payload.tool_output?.exitCode,
+    payload.tool_output?.exit_code,
+    payload.tool_result?.details?.exitCode,
+    payload.tool_result?.details?.exit_code,
+    payload.tool_result?.exitCode,
+    payload.tool_result?.exit_code,
+    payload.tool_response?.exitCode,
+    payload.tool_response?.exit_code,
+    payload.exitCode,
+    payload.exit_code,
+  ];
+  for (const value of candidates) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return null;
+}
+
+function isVerificationCommand(command) {
+  const text = String(command || '').trim();
+  if (!text) return false;
+  return [
+    /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)/i,
+    /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test|lint|typecheck|check|build)(?:\s|$)/i,
+    /(?:^|\s)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$)/i,
+    /(?:^|\s)node\s+--check(?:\s|$)/i,
+  ].some((pattern) => pattern.test(text));
+}
+
+function compactReceipt(receipt) {
+  const compact = {
+    ts: receipt.ts,
+    kind: receipt.kind,
+    success: receipt.success,
+  };
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'error']) {
+    if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
+      compact[key] = receipt[key];
+    }
+  }
+  return compact;
+}
+
+function appendReceipt(receipts, receipt) {
+  return [...(receipts || []), compactReceipt(receipt)].slice(-MAX_RECEIPTS);
+}
+
+function freshLedger(payload, routeState, harness) {
+  return {
+    version: LEDGER_VERSION,
+    sessionKey: sessionIdentity(payload),
+    sessionId: payload.session_id || payload.sessionId || null,
+    transcriptPath: payload.transcript_path || payload.transcriptPath || null,
+    harness,
+    requestKey: routeState?.requestKey || null,
+    routeFingerprint: routeState?.fingerprint || null,
+    sourceSucceeded: false,
+    writeAttempted: false,
+    writeSucceeded: false,
+    verificationAttempted: false,
+    verificationSucceeded: false,
+    verificationFailed: false,
+    receipts: [],
+    blocker: null,
+    continuationCount: 0,
+    updatedAt: Date.now(),
+  };
+}
+
+export async function recordExecutionReceipt({
+  projectRoot,
+  payload = {},
+  toolName = payload.tool_name,
+  harness = 'unknown',
+} = {}) {
+  if (!projectRoot || !toolName) return null;
+  const routeState = await readRouteState(projectRoot);
+  const current = await readExecutionLedger(projectRoot, payload);
+  const ledger = !current || current.requestKey !== (routeState?.requestKey || null)
+    ? freshLedger(payload, routeState, harness)
+    : { ...current, harness: current.harness || harness };
+
+  const failed = explicitError(payload);
+  const exitCode = extractExitCode(payload);
+  const success = !failed && (exitCode === null || exitCode === 0);
+  const toolInput = payload.tool_input || {};
+  const receipt = {
+    ts: Date.now(),
+    toolName,
+    toolUseId: payload.tool_use_id || null,
+    success,
+    exitCode,
+  };
+
+  if (toolName === 'Read' || toolName === 'Grep' || toolName === 'Glob') {
+    receipt.kind = 'source';
+    receipt.file = toolInput.file_path || toolInput.path || null;
+    ledger.sourceSucceeded ||= success;
+  } else if (toolName === 'Edit' || toolName === 'Write') {
+    receipt.kind = 'write';
+    receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
+    ledger.writeAttempted = true;
+    ledger.writeSucceeded ||= success;
+  } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
+    receipt.kind = 'verification';
+    receipt.command = String(toolInput.command || '').trim();
+    ledger.verificationAttempted = true;
+    ledger.verificationSucceeded ||= success;
+    ledger.verificationFailed ||= !success;
+  } else {
+    return ledger;
+  }
+
+  ledger.receipts = appendReceipt(ledger.receipts, receipt);
+  ledger.updatedAt = Date.now();
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), ledger);
+  return ledger;
+}
+
+function requiredEvidence(state = {}) {
+  const routeSummary = state?.routeSummary || {};
+  const contractEvidence = routeSummary.executionContract?.completionEvidence;
+  if (Array.isArray(contractEvidence) && contractEvidence.length > 0) {
+    return [...new Set(contractEvidence)];
+  }
+  return [...new Set(routeSummary.completionState?.missingEvidence || [])];
+}
+
+function evidenceSatisfied(evidence, ledger = {}) {
+  if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
+  if (evidence === 'verification-evidence') return ledger.verificationSucceeded === true;
+  if (evidence === 'impact-evidence') return ledger.sourceSucceeded === true;
+  return false;
+}
+
+function recoveryInstruction(missingEvidence, ledger = {}) {
+  if (missingEvidence.includes('write-evidence')) {
+    if (!ledger.sourceSucceeded) {
+      return 'Pull one bounded indexed source slice, then make the requested Edit/Write in this continuation.';
+    }
+    if (ledger.writeAttempted && !ledger.writeSucceeded) {
+      return 'Recover from the failed mutation using the current error, then retry the smallest correct Edit/Write.';
+    }
+    return 'Make the smallest correct Edit/Write now; do not end after more read-only analysis.';
+  }
+  if (missingEvidence.includes('verification-evidence')) {
+    if (ledger.verificationFailed) {
+      return 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
+    }
+    return 'Run the routed targeted verification now and inspect its result before stopping.';
+  }
+  return 'Complete the current routed milestone before stopping.';
+}
+
+export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
+  const routeSummary = state?.routeSummary || {};
+  const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
+  const evidence = requiredEvidence(state);
+  if (!IMPLEMENT_MODES.has(mode) || evidence.length === 0 || ledger?.blocker) {
+    return { continue: false, missingEvidence: [] };
+  }
+
+  const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
+  const effectiveLedger = sameRequest ? ledger : {};
+  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger));
+  if (missingEvidence.length === 0) {
+    return { continue: false, missingEvidence: [] };
+  }
+
+  const continuationCount = Number(effectiveLedger?.continuationCount || 0);
+  if (continuationCount >= MAX_CONTINUATIONS) {
+    return {
+      continue: false,
+      capped: true,
+      missingEvidence,
+      reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+    };
+  }
+
+  const finalAttempt = continuationCount === MAX_CONTINUATIONS - 1;
+  const instruction = recoveryInstruction(missingEvidence, effectiveLedger);
+  return {
+    continue: true,
+    missingEvidence,
+    reason: [
+      `UKit completion gate: missing ${missingEvidence.join(', ')}.`,
+      instruction,
+      finalAttempt ? 'Final automatic recovery attempt: finish now or report a concrete blocker with its evidence.' : null,
+    ].filter(Boolean).join(' '),
+  };
+}
+
+export async function incrementContinuation(projectRoot, payload = {}, ledger = null) {
+  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
+  const next = {
+    ...current,
+    continuationCount: Number(current.continuationCount || 0) + 1,
+    lastContinuationAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
+  return next;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(String(chunk));
+  return chunks.join('');
+}
+
+async function main() {
+  const payload = JSON.parse((await readStdin()) || '{}');
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+  if (process.argv.includes('--record')) {
+    await recordExecutionReceipt({
+      projectRoot,
+      payload,
+      toolName: payload.tool_name,
+      harness: process.env.UKIT_HARNESS || 'claude-code',
+    });
+    return;
+  }
+  if (process.argv.includes('--evaluate-stop')) {
+    const state = await readRouteState(projectRoot);
+    const ledger = await readExecutionLedger(projectRoot, payload) || {};
+    const result = evaluateCompletion({ state, ledger });
+    if (result.continue) {
+      await incrementContinuation(projectRoot, payload, ledger);
+      process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
+    } else if (result.capped) {
+      process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+    }
+  }
+}
+
+// Compare real paths: a project under a symlinked root (macOS /tmp -> /private/tmp, or a
+// symlinked work directory) makes import.meta.url resolve to the real path while argv[1]
+// keeps the symlinked spelling. Without realpath the guard silently never runs the CLI.
+function isDirectRun() {
+  const argvPath = process.argv[1];
+  if (!argvPath) return false;
+  const selfPath = fileURLToPath(import.meta.url);
+  const resolved = path.resolve(argvPath);
+  if (selfPath === resolved) return true;
+  try {
+    return fsSync.realpathSync(selfPath) === fsSync.realpathSync(resolved);
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectRun()) {
+  main().catch((error) => {
+    process.stderr.write(`[ukit-execution-ledger] ${error?.message || error}\n`);
+    process.exitCode = 1;
+  });
+}

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const FAIL_CLOSED_SCRIPTS = new Set([
+  'protect-files.sh',
+  'stale-spec-guard.sh',
+  'handoff-model-guard.sh',
+  'vision-gate.sh',
+  'context-hardcap-gate.sh',
+  'block-dangerous.sh',
+  'verification-guard.sh',
+]);
+
+const TOTAL_BUDGET_MS = 10000;
+const CHILD_BUDGET_MS = 4000;
+const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+
+function safeName(value) {
+  return String(value || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+}
+
+function recordTiming(projectRoot, payload, timing) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${safeName(payload?.session_id)}.jsonl`);
+    fs.appendFileSync(filePath, `${JSON.stringify(timing)}\n`, 'utf8');
+  } catch {
+    // Timing telemetry is advisory and must never delay or block a tool call.
+  }
+}
+
+function run(payloadText, scriptPaths) {
+  const payload = JSON.parse(payloadText || '{}');
+  const firstScript = scriptPaths[0] || '';
+  const projectRoot = firstScript
+    ? path.resolve(path.dirname(firstScript), '../..')
+    : (payload.cwd || process.cwd());
+  const startedAt = Date.now();
+  const deadline = startedAt + TOTAL_BUDGET_MS;
+  const results = [];
+
+  for (const scriptPath of scriptPaths) {
+    const scriptName = path.basename(scriptPath);
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      results.push({
+        scriptName,
+        code: 1,
+        stdout: '',
+        stderr: `hook chain exceeded its ${TOTAL_BUDGET_MS}ms total budget`,
+        killed: true,
+        elapsedMs: 0,
+      });
+      break;
+    }
+
+    const childStartedAt = Date.now();
+    const result = spawnSync(scriptPath, [], {
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      input: payloadText,
+      encoding: 'utf8',
+      timeout: Math.min(CHILD_BUDGET_MS, remainingMs),
+      maxBuffer: MAX_BUFFER_BYTES,
+    });
+    const code = Number.isFinite(result.status) ? result.status : 1;
+    const killed = Boolean(result.signal || result.error?.code === 'ETIMEDOUT');
+    const stderr = [result.stderr, result.error?.message].filter(Boolean).join('\n');
+    results.push({
+      scriptName,
+      code,
+      stdout: result.stdout || '',
+      stderr,
+      killed,
+      elapsedMs: Date.now() - childStartedAt,
+    });
+
+    if (code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
+      break;
+    }
+  }
+
+  const elapsedMs = Date.now() - startedAt;
+  recordTiming(projectRoot, payload, {
+    ts: Date.now(),
+    hookEvent: payload?.hook_event_name || null,
+    toolName: payload?.tool_name || null,
+    toolUseId: payload?.tool_use_id || null,
+    elapsedMs,
+    budgetMs: TOTAL_BUDGET_MS,
+    scripts: results.map(({ scriptName, code, killed, elapsedMs: scriptElapsedMs }) => ({
+      scriptName,
+      code,
+      killed,
+      elapsedMs: scriptElapsedMs,
+    })),
+  });
+
+  return { results, elapsedMs, budgetMs: TOTAL_BUDGET_MS };
+}
+
+try {
+  const [, , payloadText = '{}', ...scriptPaths] = process.argv;
+  process.stdout.write(JSON.stringify(run(payloadText, scriptPaths)));
+} catch (error) {
+  process.stdout.write(JSON.stringify({
+    results: [],
+    wrapperError: error?.message || String(error),
+  }));
+  process.exitCode = 1;
+}

package/templates/.omp/config.yml

@@ -1,5 +1,6 @@
-# UNIC gateway model names are LITERAL model names, not aliases, and they ship as the
-# installed default. Do NOT substitute sonnet/opus/haiku here. See PLAN.md §3 D15.
+# UNIC gateway model names are stable provider-neutral aliases. Their hidden backend
+# models may change during development; orchestration must not branch on vendor names.
+# Do NOT substitute sonnet/opus/haiku here. See PLAN.md §3 D15.
 #
 # Non-UNIC omp provider? A maintainer edits the three cost tiers to the values in
 # orchestration.modelTiers[*].claudeModel (.ukit/storage/config.json) — currently

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

@@ -1,35 +1,19 @@
-// 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 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 +37,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 +78,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 +90,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 +104,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 +152,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 +160,306 @@ 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).
- */
+const HOOK_CHAIN_TIMEOUT_MS = 12000;
+
 export async function runScriptChain(pi, scripts, payload, { projectRoot }) {
   const invoked = [];
-  const contextParts = [];
-
-  for (const scriptName of scripts) {
-    const scriptPath = path.join(projectRoot, '.claude', 'hooks', scriptName);
-    invoked.push(scriptName);
+  const context = [];
+  if (scripts.length === 0) {
+    return { block: false, context, invoked };
+  }
 
-    let execResult;
-    try {
-      execResult = await pi.exec(scriptPath, { input: JSON.stringify(payload) });
-    } catch (err) {
-      execResult = { code: 1, stdout: '', stderr: err?.message ?? String(err) };
-    }
+  const runnerPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'hook-chain-runner.mjs');
+  const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
+  let execResult;
+  try {
+    execResult = await pi.exec(
+      process.execPath,
+      [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 verdict = translateExecResult(scriptName, execResult);
+  if (execResult?.killed) {
+    const firstGate = scripts.find((scriptName) => FAIL_CLOSED_SCRIPTS.has(scriptName));
+    return firstGate
+      ? {
+          block: true,
+          reason: `${firstGate} hook chain was killed before safety gates completed`,
+          context,
+          invoked,
+        }
+      : { block: false, context, invoked };
+  }
 
-    if (verdict.stdout && verdict.stdout.trim()) {
-      contextParts.push(verdict.stdout.trim());
-    }
+  let chainResult;
+  try {
+    chainResult = JSON.parse(execResult?.stdout || '{}');
+  } catch {
+    chainResult = { results: [], wrapperError: execResult?.stderr || 'invalid hook-chain output' };
+  }
 
-    if (verdict.warning) {
-      pi.logger?.warn?.(verdict.warning);
+  if (chainResult.wrapperError || execResult?.code) {
+    const firstGate = scripts.find((scriptName) => FAIL_CLOSED_SCRIPTS.has(scriptName));
+    if (firstGate) {
+      return {
+        block: true,
+        reason: chainResult.wrapperError || execResult?.stderr || `${firstGate} hook chain failed`,
+        context,
+        invoked,
+      };
     }
+    pi.logger?.warn?.(`[UKit] hook chain failed open: ${chainResult.wrapperError || execResult?.stderr || 'unknown error'}`);
+  }
 
+  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] ?? []) : [];
+}
+
+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 });
 }
 
-/**
- * @param {object} event - { tool, input, sessionId, cwd }
- */
-export async function runToolCall(pi, event, { projectRoot }) {
-  const toolName = mapToolName(event.tool);
-  const scripts = scriptsForToolCall(toolName);
+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,
   });
-  const result = await runScriptChain(pi, scripts, payload, { projectRoot });
+  const result = await runScriptChain(pi, scriptsForToolCall(toolName), 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 }));
 }