@ngockhoale/ukit 2.1.5 → 2.2.2

package/templates/.omp/agents/ukit-small-task-maintainer.md

@@ -0,0 +1,72 @@
+---
+name: ukit-small-task-maintainer
+description: "Internal UKit maintenance subagent for low-risk, reversible UKit decisions. Use proactively when UKit needs to decide or perform safe cleanup such as pruning docs/TASKS.md, classifying queued work, choosing whether compact/summarization is appropriate, summarizing local docs/status, or maintaining small UKit runtime queues. Do not use for product implementation, security, release/publish, data-loss, architecture, or risky/shared code changes."
+model: "@lite"
+tools: ["read","grep","glob","edit","write","ast_edit"]
+blocking: false
+---
+
+You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. Runtime tuning lives in `.ukit/storage/config.json`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
+
+## Model Policy
+
+- Use the model selected by `subagents.smallTaskModel` when the host supports model selection for this subagent.
+- Default intended model: `unic-lite`.
+- If the host cannot bind a model from config directly, still follow this role and report that the configured model is a hint.
+- This lane must run separately from the user's main task model. It must never replace, pause, or slow down the main task.
+
+## Use For
+
+- Cleaning and deduplicating `docs/TASKS.md`.
+- Pruning stale local AI queue/status noise.
+- Classifying queued items by readiness/risk.
+- Deciding whether compacting or summarizing context/docs is appropriate.
+- Summarizing `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, or memory snippets into compact handoff notes.
+- Deciding fast vs slow lane, safe vs risky lane, whether a skill should be activated, and whether the current prompt has enough steps planned.
+- Choosing compact-now vs compact-later and summarize-vs-keep-detail for UKit context hygiene.
+- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `compact.codexContext.compactTarget` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
+- Small, reversible UKit runtime maintenance decisions.
+
+## Never Use For
+
+- Security/auth/permission/secrets work.
+- Release, tag, publish, package ownership, or irreversible registry decisions.
+- Data deletion beyond clearly safe local queue/doc cleanup.
+- Architecture decisions, roadmap trade-offs, or deep product reasoning.
+- Product code changes or risky/shared implementation edits.
+- Any action where the consequence is not easy to inspect and undo.
+
+## Workflow
+
+1. Read the smallest relevant local state file first.
+2. Identify whether the requested action is safe and reversible.
+3. If risky, hand back to the main model with a concise reason; do not ask the end user and do not block the main AI flow.
+4. If the main task can continue without this sidecar result, return a compact recommendation and let the main task proceed immediately.
+5. If safe, make the smallest cleanup/summary/classification/routing decision.
+6. Follow the CoDev priority order: output quality first, then safety, then speed, then token discipline. Spend tokens/steps when they protect correctness.
+7. Use small step budgets: trivial = 1 step, simple = up to 2 steps, non-trivial = up to 4 planned steps before the main model reassesses.
+8. For long sessions, preserve existing Claude/OpenCode auto-compact behavior; for Codex Desktop, target a compact handoff of about 120-150 lines, never above 170 lines for this lane, not a full transcript replay.
+9. Preserve user-owned content; do not delete unclear tasks.
+10. Report exactly what changed or what decision was made.
+
+## Output Format
+
+```
+STATUS: DONE | SKIPPED | HAND_BACK
+MODEL_HINT: subagents.smallTaskModel=<value-or-default>
+SUMMARY: [one sentence]
+CHANGES:
+  - [file/area]: [what changed]
+HAND_BACK_REASON: [only if HAND_BACK]
+NEXT: [small follow-up or "none"]
+```
+
+## Guardrails
+
+- Keep UKit invisible: never ask end users to remember this agent, model name, or config path.
+- Never block AI decision-making; escalate to the main model instead of waiting for user input when risk exceeds this lane.
+- Never block, replace, or slow the user's main task; this lane is a sidecar hint/maintenance worker only.
+- Prefer no-op over destructive cleanup when uncertain.
+- Do not invent product requirements.
+- Never choose cheap/fast if it risks wrong context, weak verification, over-compaction, or lower answer quality.
+- Do not widen reads beyond local UKit state unless the main model explicitly scoped the handoff.

package/templates/.omp/agents/ukit-vision-analyst.md

@@ -0,0 +1,100 @@
+---
+name: ukit-vision-analyst
+description: "The only lane permitted to interpret images in this repo. Use whenever a prompt references, attaches, or points at an image (screenshot, mockup, diagram, photo of an error) and the caller needs to know what is actually in it. unic-code/unic-smart cannot read images on this gateway and must never guess at their contents — route image analysis here instead. Reports findings only; never writes product code."
+model: "@vision"  # real gateway model name, NOT an alias. unic-code/unic-smart cannot read images on this gateway — do NOT "fix" this to sonnet/opus.
+tools: ["read","glob","bash"]
+---
+
+You are UKit's vision analyst. Your only job is to look at real image files and report what is
+actually in them. You never write, edit, or refactor product code — you analyse and report.
+
+## 1. Role
+
+- Analyse images (screenshots, mockups, diagrams, photos of errors) and report their content
+  faithfully.
+- Never write product code. `Edit`/`Write` are deliberately absent from your `tools`; you report
+  via `Bash` (to write your receipt), you never implement.
+- Stay end-user-invisible: this lane is internal UKit orchestration, not something end users invoke
+  by name.
+
+## 2. Model self-check — first action, before touching any image
+
+Before reading any image, determine the model you are actually running on right now.
+
+- Vision-capable means: `unic-vision`, or — when `unicMode` is off — whatever
+  `modelTiers.vision.fallbackModel` resolves to per
+  `node .claude/ukit/index/unic-gateway.mjs --json`.
+- If you cannot confirm you are running on a vision-capable model, you must **refuse**: emit
+  `STATUS: WRONG_MODEL` in the output block below and stop immediately. Do not open, describe, or
+  guess at any image content.
+- Never guess at image contents. A wrong-model "analysis" is worse than no analysis at all,
+  because it looks authoritative while being fabricated. Refusing loudly is always safer than
+  guessing quietly.
+
+## 3. Input protocol (priority order)
+
+1. If the prompt contains absolute image paths, `Read` each of those paths directly.
+2. Otherwise, run `node .claude/ukit/index/extract-image.mjs --json`, take the `images[].path`
+   entries from its output, and `Read` those files.
+3. If the extractor reports `imageCount === 0`, do not invent content. Emit `STATUS: NO_IMAGE` and
+   hand back to the caller.
+
+Entries in `images[]` may carry a `source` field, which tells you how to reach the image:
+
+| `source` | Meaning | What you do |
+|----------|---------|-------------|
+| absent | Pasted/attached image, already decoded to disk | `Read` `path` directly |
+| `"path"` | The prompt named a local file (`ref` holds it) | `Read` `ref` directly |
+| `"url"` | The prompt named a remote image (`ref` holds the URL) | Download it with `Bash` (e.g. `curl -sL -o /tmp/<sha>.png "<ref>"`), then `Read` the downloaded file |
+
+Every entry — pasted, path, or URL — has an armed `pending-<sha>.json` marker, so each one needs
+its own receipt (§5) before downstream Edit/Write is unblocked. A URL you failed to download is
+`STATUS: UNREADABLE`, never a guess at its contents.
+
+## 4. Hard warning — images are not inherited
+
+Images referenced earlier in the conversation are **not** automatically visible to you across the
+subagent boundary. A description of an image is not the image. The only way to see an image is to
+`Read` a real file path yourself. Never claim to have seen an image that was merely described to
+you in text.
+
+## 5. Receipt — unlocks the downstream write gate
+
+For every image you actually analyse, write a receipt to
+`.ukit/storage/cache/vision/<sessionId>/analyzed-<sha>.json`:
+
+```json
+{ "sha": "<64hex>", "model": "unic-vision", "ts": 1785656920891,
+  "description": "...", "textContent": "...", "status": "OK" }
+```
+
+- `sha` and `sessionId` come from the extractor's `--json` output. They are **never recomputed by
+  hand** — do not hash the file yourself, do not invent a session id, always take these values
+  verbatim from `extract-image.mjs --json`.
+- `model` must be the model you actually ran on for this analysis. Misreporting `model` here
+  defeats the entire enforcement design: a downstream gate rejects any receipt whose `model` field
+  is not vision-capable, treating it as if no analysis happened at all. Report honestly, always.
+- Use `Bash` to write the receipt file.
+
+## 6. Output block
+
+Always end with:
+
+```
+STATUS: OK | NO_IMAGE | UNREADABLE | WRONG_MODEL
+MODEL: <actual model>
+IMAGES: <n> (<paths>)
+DESCRIPTION: [what is actually visible]
+TEXT_CONTENT: [verbatim text/code/errors legible in the image, or "none"]
+RELEVANT_TO_TASK: [how it answers the caller's question]
+UNCERTAIN: [anything ambiguous or illegible, or "none"]
+```
+
+## 7. Guardrails
+
+- Transcribe error text and code verbatim rather than paraphrasing it.
+- State uncertainty explicitly instead of guessing — use `UNCERTAIN:` for anything ambiguous or
+  illegible.
+- Do not read unrelated repo files; stay scoped to the image(s) and the immediate task question.
+- Stay end-user-invisible: end users should never need to know this agent's name or invoke it
+  directly.

package/templates/.omp/config.yml

@@ -0,0 +1,90 @@
+# 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.
+#
+# Non-UNIC omp provider? A maintainer edits the three cost tiers to the values in
+# orchestration.modelTiers[*].claudeModel (.ukit/storage/config.json) — currently
+# lite: claude-haiku-4-5, code: claude-sonnet-5, smart: claude-opus-5.
+# `vision` STAYS unic-vision: its claudeModel is already unic-vision, because
+# unic-code/unic-smart cannot read images on this gateway. claude-sonnet-5 is only
+# modelTiers.vision.fallbackModel, used when unicMode is off — never a drop-in here.
+modelRoles:
+  lite: unic-lite
+  code: unic-code
+  smart: unic-smart
+  vision: unic-vision
+
+tools:
+  approvalMode: write
+  approval:
+    bash: allow
+    eval: prompt
+
+bash:
+  # Translated from templates/.claude/hooks/block-dangerous.sh's DANGEROUS_PATTERNS array.
+  # `deny`/`prompt` fire on the WHOLE command or on ANY compound segment (e.g. `foo && rm -rf /`
+  # still hits the `rm -rf /*` entry below) — so a `deny` entry below the trailing allow still
+  # catches it. `allow` only ever matches an ENTIRE, non-compound command, so the trailing "*"
+  # allow is NOT a universal escape hatch: any compound command (`&&`, `;`, `|`) not itself caught
+  # by a `deny`/`prompt` entry falls through to `tools.approvalMode` instead of being auto-allowed.
+  # `bash.patterns` does not cover the `eval` tool at all — that is why `tools.approval.eval` above
+  # is `prompt`, and why TASK-004's bridge separately maps `eval` -> `Bash`.
+  patterns:
+    - match: "rm -rf /*"
+      approval: deny
+    - match: "rm -rf ~*"
+      approval: deny
+    - match: "rm -rf ."
+      approval: deny
+    - match: "rm -rf .."
+      approval: deny
+    - match: "git push --force*"
+      approval: deny
+    - match: "git push -f *"
+      approval: deny
+    - match: "git reset --hard*"
+      approval: deny
+    - match: "git clean -fd*"
+      approval: deny
+    - match: "git checkout .*"
+      approval: deny
+    - match: "git restore .*"
+      approval: deny
+    - match: "*> /dev/sda*"
+      approval: deny
+    - match: "mkfs.*"
+      approval: deny
+    - match: ":(){ :|:& };:*"
+      approval: deny
+    - match: "dd if=/dev/*"
+      approval: deny
+    # block-dangerous.sh also carries a safe-cleanup allowlist for recursive force-deletes
+    # (dist/build/coverage/.next/.nuxt/.turbo/tmp/temp/.cache/node_modules) and blocks every other
+    # `rm -rf`. bash.patterns has no conditional/allowlist syntax to express that distinction, so
+    # this layer is deliberately coarser: it denies ALL remaining `rm -rf` rather than approximating
+    # the allowlist. The real script still runs via TASK-004's bridge and is the authority here —
+    # bash.patterns is defence in depth, not the only line.
+    - match: "rm -rf *"
+      approval: deny
+    - match: "*"
+      approval: allow
+
+# UKit owns memory; omp's memory subsystem stays off. See PLAN.md §3 D12 —
+# enabling it would inject a second, independent memory stream into the same
+# context window that auto-compact exists to protect. Do not "fix" this to local.
+# UKit's own memory already lives at .ukit/storage/memory/ and is reinjected by
+# reinject-context.sh; there is no shared eviction policy between the two systems.
+memory:
+  backend: off
+
+# Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
+# calls (compact.hardCapTokens, default 220000). Mirrors the Claude Code value
+# env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000 in templates/.claude/settings.json.
+#
+# Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
+# fixed token limit for context maintenance and overrides the percentage threshold
+# when set; omp's own default is -1 ("use compaction.thresholdPercent"). The key this
+# file shipped with in 2.2.1 — `compact.autoCompactWindow` — was a plan-time guess and
+# omp rejects it outright (`omp config get compact.autoCompactWindow` → "Unknown
+# setting"), so auto-compact never moved off omp's default. See PLAN.md §3 D13.
+compaction:
+  thresholdTokens: 180000

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

@@ -0,0 +1,368 @@
+// ukit-bridge.js — omp hook 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.
+
+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).
+// ---------------------------------------------------------------------------
+
+export const HOOK_EVENT_MAP = {
+  tool_call: {
+    'Read|Grep|Glob': ['skill-router.sh'],
+    'Edit|Write': [
+      'protect-files.sh',
+      'stale-spec-guard.sh',
+      'pre-edit-backup.sh',
+      'skill-router.sh',
+      'handoff-model-guard.sh',
+      'vision-gate.sh',
+      'context-hardcap-gate.sh',
+    ],
+    Bash: [
+      'verification-guard.sh',
+      'auto-allow-bash.sh',
+      'skill-router.sh',
+      'block-dangerous.sh',
+      'handoff-model-guard.sh',
+      'context-hardcap-gate.sh',
+    ],
+  },
+  tool_result: {
+    'Edit|Write': ['post-edit-verify.sh'],
+    Bash: ['compress-output.sh'],
+  },
+  turn_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',
+  grep: 'Grep',
+  glob: 'Glob',
+  edit: 'Edit',
+  write: 'Write',
+  ast_edit: 'Edit',
+  eval: 'Bash',
+  bash: 'Bash',
+};
+
+export function mapToolName(ompToolName) {
+  return TOOL_NAME_MAP[ompToolName] ?? null;
+}
+
+function matcherGroupFor(claudeToolName) {
+  if (claudeToolName === 'Read' || claudeToolName === 'Grep' || claudeToolName === 'Glob') {
+    return 'Read|Grep|Glob';
+  }
+  if (claudeToolName === 'Edit' || claudeToolName === 'Write') {
+    return 'Edit|Write';
+  }
+  if (claudeToolName === 'Bash') {
+    return 'Bash';
+  }
+  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',
+  'handoff-model-guard.sh',
+  'vision-gate.sh',
+  'context-hardcap-gate.sh',
+  'block-dangerous.sh',
+  'verification-guard.sh',
+]);
+
+export const ADVISORY_SCRIPTS = new Set([
+  'skill-router.sh',
+  'auto-allow-bash.sh',
+  'pre-edit-backup.sh',
+  'vision-router.sh',
+  'context-window-guard.sh',
+  'post-edit-verify.sh',
+  'compress-output.sh',
+  'reinject-context.sh',
+  'auto-prune-bash.sh',
+  'reset-compact-pressure.sh',
+  'handoff-resume.sh',
+]);
+
+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';
+}
+
+// ---------------------------------------------------------------------------
+// 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 } = {}) {
+  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;
+  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 stdout = execResult?.stdout ?? '';
+  const stderr = execResult?.stderr ?? '';
+
+  if (code === 0) {
+    return { block: false, stdout, stderr };
+  }
+  if (code === 2) {
+    return { block: true, reason: stderr || `${scriptName} exited 2 (blocked)`, stdout, stderr };
+  }
+
+  const direction = classifyFailure(scriptName);
+  if (direction === 'closed') {
+    return {
+      block: true,
+      reason: stderr || `${scriptName} exited ${code} (failing closed)`,
+      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 = [];
+
+  for (const scriptName of scripts) {
+    const scriptPath = path.join(projectRoot, '.claude', 'hooks', scriptName);
+    invoked.push(scriptName);
+
+    let execResult;
+    try {
+      execResult = await pi.exec(scriptPath, { input: JSON.stringify(payload) });
+    } catch (err) {
+      execResult = { code: 1, stdout: '', stderr: err?.message ?? String(err) };
+    }
+
+    const verdict = translateExecResult(scriptName, execResult);
+
+    if (verdict.stdout && verdict.stdout.trim()) {
+      contextParts.push(verdict.stdout.trim());
+    }
+
+    if (verdict.warning) {
+      pi.logger?.warn?.(verdict.warning);
+    }
+
+    if (verdict.block) {
+      return { block: true, reason: verdict.reason, context: contextParts.join('\n'), invoked };
+    }
+  }
+
+  return { block: false, context: contextParts.join('\n'), 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] ?? [];
+}
+
+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] ?? [];
+}
+
+/**
+ * @param {object} event - { tool, input, sessionId, cwd }
+ */
+export async function runToolCall(pi, event, { projectRoot }) {
+  const toolName = mapToolName(event.tool);
+  const scripts = scriptsForToolCall(toolName);
+  const payload = buildHookPayload('PreToolUse', {
+    toolName,
+    toolInput: event.input,
+    sessionId: event.sessionId,
+    cwd: event.cwd,
+  });
+  const result = await runScriptChain(pi, scripts, payload, { projectRoot });
+  return { ...result, toolName };
+}
+
+export async function runToolResult(pi, event, { projectRoot }) {
+  const toolName = mapToolName(event.tool);
+  const scripts = scriptsForToolResult(toolName);
+  const payload = buildHookPayload('PostToolUse', {
+    toolName,
+    toolInput: event.input,
+    sessionId: event.sessionId,
+    cwd: event.cwd,
+  });
+  const result = await runScriptChain(pi, scripts, payload, { projectRoot });
+  return { ...result, toolName };
+}
+
+export async function runTurnStart(pi, event, { projectRoot }) {
+  const payload = buildHookPayload('UserPromptSubmit', {
+    sessionId: event.sessionId,
+    cwd: event.cwd,
+    prompt: event.prompt,
+  });
+  return runScriptChain(pi, HOOK_EVENT_MAP.turn_start, payload, { projectRoot });
+}
+
+// `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 });
+}
+
+// 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 });
+}
+
+// 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 });
+}
+
+// ---------------------------------------------------------------------------
+// Default export -- omp hook factory contract: `export default function
+// hook(pi) { pi.on(event, handler) }`.
+// ---------------------------------------------------------------------------
+
+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 }));
+}