@ngockhoale/ukit 2.2.1 → 2.2.3

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

@@ -1,32 +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.
-//
-// omp's own `pi.exec` / `pi.on` argument shapes are UNVERIFIED (omp is not
-// installed in this environment, no source/schema vendored — PLAN.md D7).
-// The internal contract chosen below (see doc comments on each exported
-// function) is a reasonable, internally consistent design; it is exercised
-// end-to-end against a fake `pi` in tests/hooks/ompHookBridge.test.js.
+// 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: {
@@ -50,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) {
@@ -97,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',
@@ -117,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',
@@ -130,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 };
@@ -177,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)`,
@@ -187,150 +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');
 }
 
-/**
- * @param {object} event - { tool, input, sessionId, cwd }
- */
-export async function runToolCall(pi, event, { projectRoot }) {
-  const toolName = mapToolName(event.tool);
-  const scripts = scriptsForToolCall(toolName);
+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,
   });
-  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;
 }
 
-// Must run on EVERY session start, including a post-compact continuation --
-// no "first start only" guard. handoff-resume.sh is idempotent by design
-// (reads + prints the docs/AI_HANDOFF/RUN.md cursor, never advances state),
-// so re-running it on every start is safe and required for the mid-cycle
-// handoff run to resume correctly after a compaction (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;
+}
+
+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;
 }
 
-// ---------------------------------------------------------------------------
-// Default export -- omp hook factory contract: `export default function
-// hook(pi) { pi.on(event, handler) }`.
-// ---------------------------------------------------------------------------
+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,
+  };
+}
+
+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();
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || installedProjectRoot();
 
-  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('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 }));
 }