@ngockhoale/ukit 2.2.3 → 2.2.5

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.5 - 2026-08-27
+
+Follow-up to the user's report that UKit had become too heavy-handed: too many hook scripts firing per tool call, too much blocking, and a concrete false-positive in the destructive-command gate itself. This wave trims default hook wiring and fixes the false positive, while explicitly preserving `rm`/destructive-command protection as instructed.
+
+### Changed
+
+- **`PreToolUse:Bash` now runs 4 hook scripts instead of 6.** `verification-guard.sh` was removed from the default Bash chain (both `.claude/settings.json` copies, the omp bridge's `HOOK_EVENT_MAP`/`FAIL_CLOSED_SCRIPTS`, and `hook-chain-runner.mjs`'s own classification). Its hard-block path is gated behind `UKIT_VERIFICATION_GUARD_ENFORCE=1`, unset by default, so it was pure per-call overhead (a full `node` spawn) for zero present safety value. The script and its standalone tests are untouched — still shippable, opt-in.
+- **`PreToolUse:Read|Grep|Glob` no longer runs `skill-router.sh`.** Automatic skill activation still runs on `UserPromptSubmit` and `Edit|Write`, where a skill choice actually matters; it no longer re-evaluates on every read-only tool call. Traded away: skill-router no longer sees "which files were Read/Grep'd" as mid-task evidence — only the original prompt and Edit/Write targets.
+
+### Fixed
+
+- **`block-dangerous.sh` misidentified dangerous *text* as a dangerous *command*.** Both its per-pattern denylist and its `rm` handling matched against the entire raw command string with no awareness of shell quoting, so `grep -rn "rm -rf" .` or `echo "rm -rf /tmp/foo"` — which merely mention the text — were blocked as if they executed it. Quoted spans are now scrubbed before matching, but only when the command's own invoked program is a pure text tool (`grep|egrep|fgrep|rg|ag|awk|sed|echo|printf|cat`) and it does not pipe into a shell/eval sink (`| bash|sh|zsh|eval|xargs`), since `echo "rm -rf /" | bash` really does execute the quoted text. Every other command shape is scanned exactly as strictly as before.
+- **`rm -rf ./dist` (and other allowlisted safe-cleanup targets with a `./` prefix) was blocked as an "unsafe delete target."** The unsafe-target check ran before the safe-cleanup allowlist check and its pattern misfired on the literal `./` prefix. Reordered so the allowlist is checked first; genuinely risky targets like `rm -rf ../important` still block.
+
+### Added
+
+- **11 regression tests** in `tests/hooks/blockDangerous.test.js` covering the false-positive fix, the closed shell-pipe escape hatch, the `./dist` allowlist fix, and all pre-existing destructive-command blocks (`rm -rf /`, `rm -rf ~`, `rm -rf .`, `rm -rf ../important`, `git push --force`, `git reset --hard`).
+
+## 2.2.4 - 2026-08-27
+
+Follow-up to 2.2.3's hook-chain collapse: a real omp session on a CloudMounter/FUSE-mounted project reported every tool call — including harmless `echo`, `pwd`, `ls`, and `Edit` — failing with `invalid hook-chain output`, and in one case `protect-files.sh hook chain was killed before safety gates completed`, despite `protect-files.sh` itself passing trivially. The bridge was misattributing any aggregate-runner transport failure to the first fail-closed script in the chain, whether or not that script ever ran.
+
+### Fixed
+
+- **Outer transport failures no longer impersonate a specific safety gate.** `runScriptChain` in `ukit-bridge.js` treated a killed/timed-out `pi.exec`, empty stdout, or malformed JSON from `hook-chain-runner.mjs` as proof that the chain's first fail-closed script (e.g. `protect-files.sh`) had failed — without verifying that script ever ran. It now distinguishes "the runner returned a verifiable per-script result" from "the runner itself failed before producing one," and on the latter reports the real failure (killed/code/elapsedMs/runtime) instead of a fabricated gate name. Diagnostics are appended to `.ukit/storage/cache/hook-errors/<session>.jsonl`.
+- **Bash and Read/Grep/Glob no longer fail closed on a bridge/runner outage.** Only `Edit`/`Write` chains still block when the runner can't produce a verdict, since those guard file mutation. Ordinary shell commands and read-only tools now fail open (with a logged warning), so a runner-level hiccup can no longer brick command execution or diagnosis tools.
+- **`process.execPath` is no longer trusted blindly for the runner subprocess.** The bridge resolves `process.env.UKIT_NODE_PATH || process.execPath` and records the resolved runtime in the failure diagnostic, so a Bun-hosted omp launching the Node-only runner under the wrong binary is now visible instead of silently assumed.
+
+### Added
+
+- **6 regression tests** in `tests/hooks/ompHookBridge.test.js` (`case 13`) covering a killed outer exec, malformed stdout, a non-zero exit with empty stdout before any script ran, fail-open behavior for Bash and Read chains under the same failures, and `UKIT_NODE_PATH` override.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "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/block-dangerous.sh

@@ -9,6 +9,22 @@ if [ -z "$COMMAND" ]; then
   exit 0
 fi
 
+# A command like `grep "rm -rf" file.sh` or `echo "rm -rf /"` merely mentions the
+# text of a dangerous pattern as data — it does not execute it. Naively substring-matching
+# the raw command line false-positives on any search/print of that text. Scrub quoted
+# spans before pattern-matching, but ONLY when the invoked command is a pure text tool
+# AND its output cannot reach a shell (no piping into bash/sh/zsh/eval/xargs), since
+# `echo "rm -rf /" | bash` really does execute the quoted text.
+SAFE_TEXT_CMD_REGEX='^(grep|egrep|fgrep|rg|ag|awk|sed|echo|printf|cat)$'
+PIPE_TO_SHELL_REGEX='\|[[:space:]]*(bash|sh|zsh|eval|xargs)([[:space:]]|$)'
+
+CMD_HEAD=$(echo "$COMMAND" | sed -E 's/^[[:space:]]*//' | awk '{print $1}' | xargs -I{} basename {} 2>/dev/null)
+
+SCAN_COMMAND="$COMMAND"
+if echo "$CMD_HEAD" | grep -qE "$SAFE_TEXT_CMD_REGEX" && ! echo "$COMMAND" | grep -qE "$PIPE_TO_SHELL_REGEX"; then
+  SCAN_COMMAND=$(printf '%s' "$COMMAND" | sed -E "s/'[^']*'/'Q'/g; s/\"[^\"]*\"/\"Q\"/g")
+fi
+
 # Dangerous patterns to block
 DANGEROUS_PATTERNS=(
   "rm -rf /"
@@ -27,24 +43,26 @@ DANGEROUS_PATTERNS=(
 )
 
 for pattern in "${DANGEROUS_PATTERNS[@]}"; do
-  if echo "$COMMAND" | grep -qE "$pattern"; then
+  if echo "$SCAN_COMMAND" | grep -qE "$pattern"; then
     echo "BLOCKED: Dangerous command detected matching pattern '$pattern'. This command could cause irreversible damage. Ask the user to run it manually if truly needed." >&2
     exit 2
   fi
 done
 
 # Handle rm commands: allow safe cleanup targets, block risky recursive force-deletes
-if echo "$COMMAND" | grep -qE "(^|[;&|[:space:]])rm([[:space:]]|$)"; then
-  if echo "$COMMAND" | grep -qE "rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r|--recursive\s+--force|--force\s+--recursive|--recursive\s+-f|-f\s+--recursive)"; then
+if echo "$SCAN_COMMAND" | grep -qE "(^|[;&|[:space:]])rm([[:space:]]|$)"; then
+  if echo "$SCAN_COMMAND" | grep -qE "rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r|--recursive\s+--force|--force\s+--recursive|--recursive\s+-f|-f\s+--recursive)"; then
     SAFE_DELETE_REGEX='(^|[[:space:]])(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/|[[:space:]]|$)'
     UNSAFE_TARGET_REGEX='(^|[[:space:]])(/|~|\.\.?($|/)|\.($|/))'
 
-    if echo "$COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
+    # Check the allowlist first: `./dist` legitimately contains a leading "./" that would
+    # otherwise be mistaken for a bare current-directory target by UNSAFE_TARGET_REGEX below.
+    if echo "$SCAN_COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
+      :
+    elif echo "$SCAN_COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
       echo "BLOCKED: Unsafe delete target detected. Refusing recursive force-delete." >&2
       exit 2
-    fi
-
-    if ! echo "$COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
+    else
       echo "BLOCKED: 'rm -rf' is only auto-allowed for safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules)." >&2
       exit 2
     fi

package/templates/.claude/settings.json

@@ -54,13 +54,7 @@
     "PreToolUse": [
       {
         "matcher": "Read|Grep|Glob",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
-            "timeout": 8
-          }
-        ]
+        "hooks": []
       },
       {
         "matcher": "Edit|Write",
@@ -105,21 +99,11 @@
       {
         "matcher": "Bash",
         "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\"",
-            "timeout": 8
-          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\"",
             "timeout": 8
           },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
-            "timeout": 8
-          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",

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

@@ -11,7 +11,6 @@ const FAIL_CLOSED_SCRIPTS = new Set([
   'vision-gate.sh',
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
-  'verification-guard.sh',
 ]);
 
 const TOTAL_BUDGET_MS = 10000;

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

@@ -5,6 +5,7 @@
 // payloads, executes the same ordered script chains, and translates only the
 // result fields that omp consumes.
 
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -17,7 +18,7 @@ import {
 
 export const HOOK_EVENT_MAP = {
   tool_call: {
-    'Read|Grep|Glob': ['skill-router.sh'],
+    'Read|Grep|Glob': [],
     'Edit|Write': [
       'protect-files.sh',
       'stale-spec-guard.sh',
@@ -28,9 +29,7 @@ export const HOOK_EVENT_MAP = {
       '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',
@@ -85,7 +84,6 @@ export const FAIL_CLOSED_SCRIPTS = new Set([
   'vision-gate.sh',
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
-  'verification-guard.sh',
 ]);
 
 export const ADVISORY_SCRIPTS = new Set([
@@ -172,7 +170,23 @@ export { translateExecResult };
 
 const HOOK_CHAIN_TIMEOUT_MS = 12000;
 
-export async function runScriptChain(pi, scripts, payload, { projectRoot }) {
+function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
+  try {
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-errors');
+    fs.mkdirSync(dir, { recursive: true });
+    const safeSession = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+    fs.appendFileSync(path.join(dir, `${safeSession}.jsonl`), `${JSON.stringify(diagnostic)}\n`, 'utf8');
+  } catch {
+    // Diagnostics are advisory and must never block or throw.
+  }
+}
+
+export async function runScriptChain(
+  pi,
+  scripts,
+  payload,
+  { projectRoot, failClosedOnTransportError = false },
+) {
   const invoked = [];
   const context = [];
   if (scripts.length === 0) {
@@ -181,50 +195,64 @@ export async function runScriptChain(pi, scripts, payload, { projectRoot }) {
 
   const runnerPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'hook-chain-runner.mjs');
   const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
+  // Do not blindly trust process.execPath: under a Bun-hosted omp, it points at bun, not node.
+  const nodeExecutable = process.env.UKIT_NODE_PATH || process.execPath;
+  const startedAt = Date.now();
   let execResult;
   try {
     execResult = await pi.exec(
-      process.execPath,
+      nodeExecutable,
       [runnerPath, JSON.stringify(payload), ...scriptPaths],
       { cwd: projectRoot, timeout: HOOK_CHAIN_TIMEOUT_MS },
     );
   } catch (error) {
     execResult = { code: 1, stdout: '', stderr: error?.message ?? String(error), killed: false };
   }
+  const elapsedMs = Date.now() - startedAt;
 
-  if (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 };
-  }
-
-  let chainResult;
-  try {
-    chainResult = JSON.parse(execResult?.stdout || '{}');
-  } catch {
-    chainResult = { results: [], wrapperError: execResult?.stderr || 'invalid hook-chain output' };
+  let chainResult = null;
+  let parseError = null;
+  if (!execResult?.killed) {
+    try {
+      chainResult = JSON.parse(execResult?.stdout || '{}');
+    } catch (error) {
+      parseError = error;
+    }
   }
 
-  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,
-      };
+  const hasUsableResults = Boolean(chainResult) && Array.isArray(chainResult.results) && chainResult.results.length > 0;
+  const transportFailed = Boolean(execResult?.killed) || Boolean(parseError) || Boolean(chainResult?.wrapperError) || !hasUsableResults;
+
+  if (transportFailed) {
+    // The aggregate runner produced no verifiable per-script verdict. Never relabel this as a
+    // specific fail-closed script's decision -- that script may never have run.
+    const diagnostic = {
+      ts: Date.now(),
+      scripts,
+      killed: Boolean(execResult?.killed),
+      code: execResult?.code ?? null,
+      stdoutLength: (execResult?.stdout || '').length,
+      stderr: execResult?.stderr || '',
+      elapsedMs,
+      nodeExecutable,
+      nodeVersion: process.version,
+      runnerPath,
+      parseError: parseError?.message || null,
+      wrapperError: chainResult?.wrapperError || null,
+    };
+    recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    const reason = `UKit OMP hook runner failed before producing a valid result `
+      + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
+      + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
+      + `See .ukit/storage/cache/hook-errors/.`;
+    if (failClosedOnTransportError) {
+      return { block: true, reason, context, invoked };
     }
-    pi.logger?.warn?.(`[UKit] hook chain failed open: ${chainResult.wrapperError || execResult?.stderr || 'unknown error'}`);
+    pi.logger?.warn?.(`[UKit] ${reason}`);
+    return { block: false, context, invoked };
   }
 
-  for (const item of chainResult.results ?? []) {
+  for (const item of chainResult.results) {
     const scriptName = item?.scriptName;
     if (!scriptName || !scripts.includes(scriptName)) continue;
     invoked.push(scriptName);
@@ -314,7 +342,13 @@ export async function runToolCall(pi, event, { projectRoot, context: extensionCo
     toolUseId: event.toolCallId,
     ...metadata,
   });
-  const result = await runScriptChain(pi, scriptsForToolCall(toolName), payload, { projectRoot });
+  // Only Edit|Write stays fail-closed on a bridge/runner transport failure; Bash and
+  // Read|Grep|Glob fail open so diagnosis/recovery tools are never bricked by a runner outage.
+  const failClosedOnTransportError = matcherGroupFor(toolName) === 'Edit|Write';
+  const result = await runScriptChain(pi, scriptsForToolCall(toolName), payload, {
+    projectRoot,
+    failClosedOnTransportError,
+  });
   if (!result.block) sendContext(pi, result.context, 'steer');
   return { ...result, toolName };
 }