@ngockhoale/ukit 2.6.10 → 2.7.0

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -44,10 +44,19 @@ source "$HOOK_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   if [ "$__ukit_main_stage_rc" -ne 0 ]; then
     # Infra failure during staging (mktemp/truncate): payload was never
     # inspected — announce the degrade (SPEC §8), never a silent pass.
-    ukit_emit_input_degraded failclosed "context hard-cap gate"
+    # TASK-003: `deny`, not `ask` — ask auto-approves under bypassPermissions.
+    ukit_emit_permission_decision deny "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so context hard-cap gate cannot prove it safe."
+  fi
+  # BUG-C21-01 / TASK-003: degraded input first salvages tool_name — a COMPLETE
+  # recovered name takes the normal verdict path below; an unrecoverable one is
+  # refused with `deny` (never `ask`: bypassPermissions auto-approves ask).
+  if ukit_input_degraded; then
+    if UKIT_SALVAGED_TOOL_NAME="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "tool_name")"; then
+      UKIT_SALVAGE_ACTIVE=1
+    else
+      ukit_emit_permission_decision deny "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound) and the tool name could not be recovered, so context hard-cap gate cannot prove it safe."
+    fi
   fi
-  # BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
-  ukit_input_degraded && ukit_emit_input_degraded failclosed "context hard-cap gate"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -80,17 +89,18 @@ else
     # path's ukit_emit_input_degraded.
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
-    # TASK-223: same emit shape as ukit_emit_permission_decision — exit 0 on the
-    # direct host (non-zero discards stdout there), exit 2 inside the omp chain.
-    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so context hard-cap gate cannot prove it safe. UKit defers this to a human decision."}}'
-    echo "BLOCKED: context hard-cap gate could not inspect a truncated/stalled payload; deferred to human." >&2
+    # TASK-223 + TASK-003: same emit shape as ukit_emit_permission_decision —
+    # exit 0 on the direct host (non-zero discards stdout there), exit 2 inside
+    # the omp chain. `deny`, never `ask`: bypassPermissions auto-approves ask.
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so context hard-cap gate cannot prove it safe."}}'
+    echo "BLOCKED: context hard-cap gate could not inspect a truncated/stalled payload; refused fail-closed." >&2
     if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then exit 2; fi
     exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR" UKIT_SALVAGE_ACTIVE="${UKIT_SALVAGE_ACTIVE:-0}" UKIT_SALVAGED_TOOL_NAME="${UKIT_SALVAGED_TOOL_NAME:-}" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 // SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
 // degrade (fail-open posture kept: still exit 0).
@@ -164,6 +174,14 @@ async function readRunCursor() {
       return {};
     }
   })();
+  // TASK-003: on the degraded path the staged prefix cannot parse, so the shell
+  // handed us the salvaged tool_name — reconstruct just enough payload for the
+  // gate's normal verdict.
+  if (process.env.UKIT_SALVAGE_ACTIVE === '1'
+      && typeof process.env.UKIT_SALVAGED_TOOL_NAME === 'string'
+      && process.env.UKIT_SALVAGED_TOOL_NAME) {
+    payload.tool_name = process.env.UKIT_SALVAGED_TOOL_NAME;
+  }
   const toolName = payload?.tool_name || '';
   if (!GATED_TOOLS.has(toolName)) {
     process.exit(0);

package/templates/.claude/hooks/project-important.sh

@@ -6,6 +6,58 @@
 # session. No renderer logic lives here — the shared runtime module renders.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/project-important.mjs"
+UNREADABLE_WARNING='[UKit] PROJECT_IMPORTANT.md was not injected: the file could not be read. Run `ukit doctor`.'
+PROJECT_IMPORTANT_FILE="$PROJECT_ROOT/PROJECT_IMPORTANT.md"
+PROJECT_IMPORTANT_CACHE_DIR="$PROJECT_ROOT/.ukit/storage/cache"
+PROJECT_IMPORTANT_CACHE="$PROJECT_IMPORTANT_CACHE_DIR/project-important.cache"
+
+# Cache invalidation uses both metadata and a cheap content checksum. Metadata
+# avoids reading a stable file twice in the common case, while the checksum
+# catches in-place edits that preserve size and timestamp.
+ukit_pi_fingerprint() {
+  local metadata checksum
+  # GNU coreutils first: it rejects '%m:%z:%i' outright, while BSD stat would
+  # accept the GNU format string and silently print a filesystem summary.
+  metadata="$(/usr/bin/stat -c '%Y:%s:%i' "$PROJECT_IMPORTANT_FILE" 2>/dev/null)"
+  if [ -z "$metadata" ]; then
+    metadata="$(/usr/bin/stat -f '%m:%z:%i' "$PROJECT_IMPORTANT_FILE" 2>/dev/null)"
+  fi
+  [ -n "$metadata" ] || return 1
+  checksum="$(cksum < "$PROJECT_IMPORTANT_FILE" 2>/dev/null)" || return 1
+  [ -n "$checksum" ] || return 1
+  printf '%s|%s' "$metadata" "$checksum"
+}
+
+# Resolve the runtime before consulting the cache. A stale cache must never
+# hide a missing install or renderer, while a valid hit intentionally skips
+# stdin staging: this advisory hook does not inspect its SessionStart payload,
+# and waiting on a producer that holds the pipe open is the stall this hook is
+# being fixed for (auto-prune-bash.sh, wired beside it, never reads stdin either).
+if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' "$UNREADABLE_WARNING"
+  exit 0
+fi
+
+if [ -f "$PROJECT_IMPORTANT_FILE" ] && [ -f "$PROJECT_IMPORTANT_CACHE" ]; then
+  __ukit_pi_key="$(ukit_pi_fingerprint 2>/dev/null)"
+  if [ -n "$__ukit_pi_key" ]; then
+    __ukit_pi_cache="$(cat "$PROJECT_IMPORTANT_CACHE" 2>/dev/null)"
+    # Key on the first line; the rest is the renderer's exact stdout bytes.
+    # Anything malformed (empty, key-only, wrong key) falls through to the
+    # cold path, so a corrupt cache is a re-render, never a wrong answer.
+    if [ "${__ukit_pi_cache%%$'\n'*}" = "$__ukit_pi_key" ] \
+      && [ "$__ukit_pi_cache" != "$__ukit_pi_key" ]; then
+      __ukit_pi_hit="${__ukit_pi_cache#"$__ukit_pi_key"$'\n'}"
+      if [ -n "$__ukit_pi_hit" ]; then
+        printf '%s\n' "$__ukit_pi_hit"
+        exit 0
+      fi
+    fi
+  fi
+fi
+
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 # Arm advisory latency telemetry when available; a missing runtime (pre-install
@@ -60,15 +112,6 @@ else
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
 
-PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/project-important.mjs"
-UNREADABLE_WARNING='[UKit] PROJECT_IMPORTANT.md was not injected: the file could not be read. Run `ukit doctor`.'
-
-if [ ! -f "$SCRIPT" ]; then
-  printf '%s\n' "$UNREADABLE_WARNING"
-  exit 0
-fi
-
 # The wrapped runtime self-arms on UKIT_HOOK_DEADLINE_MS (SCRIPT_ARM/EXIT_ARM),
 # so a wedged read exits 0 inside the deadline instead of orphaning a node child.
 INPUT="$(cat "$UKIT_INPUT_FILE" 2>/dev/null)"
@@ -80,5 +123,23 @@ if [ "$STATUS" -ne 0 ] || [ -z "$OUTPUT" ]; then
   exit 0
 fi
 
+# Cache writes are advisory and atomic. Recompute the key after rendering so a
+# file edit racing the renderer cannot publish bytes under an old fingerprint.
+__ukit_pi_render_key=""
+if [ -f "$PROJECT_IMPORTANT_FILE" ]; then
+  __ukit_pi_render_key="$(ukit_pi_fingerprint 2>/dev/null)"
+fi
+if [ -n "$__ukit_pi_render_key" ]; then
+  if mkdir -p "$PROJECT_IMPORTANT_CACHE_DIR" 2>/dev/null; then
+    __ukit_pi_tmp="$PROJECT_IMPORTANT_CACHE.tmp.$$"
+    if printf '%s\n%s' "$__ukit_pi_render_key" "$OUTPUT" > "$__ukit_pi_tmp" 2>/dev/null \
+      && mv -f "$__ukit_pi_tmp" "$PROJECT_IMPORTANT_CACHE" 2>/dev/null; then
+      :
+    else
+      rm -f "$__ukit_pi_tmp" 2>/dev/null || true
+    fi
+  fi
+fi
+
 printf '%s\n' "$OUTPUT"
 exit 0

package/templates/.claude/hooks/protect-files.sh

@@ -16,10 +16,20 @@ source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   if [ "$__ukit_main_stage_rc" -ne 0 ]; then
     # Infra failure during staging (mktemp/truncate): payload was never
     # inspected — announce the degrade (SPEC §8), never a silent pass.
-    ukit_emit_input_degraded failclosed "protected-file gate"
+    # TASK-003: `deny`, not `ask` — ask auto-approves under bypassPermissions.
+    ukit_emit_permission_decision deny "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so protected-file gate cannot prove it safe."
   fi
-# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
-ukit_input_degraded && ukit_emit_input_degraded failclosed "protected-file gate"
+# BUG-C21-01 / TASK-003: degraded input first attempts a bounded salvage of
+# tool_input.file_path — a COMPLETE recovered path still gets the normal verdict
+# below; an unrecoverable/incomplete one is refused with `deny` (never `ask`:
+# bypassPermissions auto-approves ask on the direct host — review R1-1).
+if ukit_input_degraded; then
+  if UKIT_SALVAGED_FILE_PATH="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "tool_input.file_path")"; then
+    UKIT_SALVAGE_ACTIVE=1
+  else
+    ukit_emit_permission_decision deny "UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound) and the file path could not be recovered, so protected-file gate cannot prove it safe."
+  fi
+fi
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -52,15 +62,21 @@ else
     # path's ukit_emit_input_degraded.
     rm -f "$UKIT_INPUT_FILE"
     UKIT_INPUT_FILE=""
-    # TASK-223: same emit shape as ukit_emit_permission_decision — exit 0 on the
-    # direct host (non-zero discards stdout there), exit 2 inside the omp chain.
-    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so protected-file gate cannot prove it safe. UKit defers this to a human decision."}}'
-    echo "BLOCKED: protected-file gate could not inspect a truncated/stalled payload; deferred to human." >&2
+    # TASK-223 + TASK-003: same emit shape as ukit_emit_permission_decision —
+    # exit 0 on the direct host (non-zero discards stdout there), exit 2 inside
+    # the omp chain. `deny`, never `ask`: bypassPermissions auto-approves ask.
+    printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so protected-file gate cannot prove it safe."}}'
+    echo "BLOCKED: protected-file gate could not inspect a truncated/stalled payload; refused fail-closed." >&2
     if [ -n "${UKIT_HOOK_CHAIN_RUNNER:-}" ]; then exit 2; fi
     exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
+if [ "${UKIT_SALVAGE_ACTIVE:-0}" = "1" ]; then
+  # TASK-003: degraded path already recovered a COMPLETE file_path — skip the
+  # normal extraction (the staged prefix would not parse anyway).
+  FILE_PATH="$UKIT_SALVAGED_FILE_PATH"
+else
 INPUT="$(cat "$UKIT_INPUT_FILE")"
 # jq is absent on stock macOS. Keep jq as the low-latency normal path, but fall back to
 # UKit's required Node runtime so a missing optional binary cannot disable this gate.
@@ -80,6 +96,7 @@ process.stdin.on("end", () => {
 });
 ' 2>/dev/null)
 fi
+fi
 
 if [ -z "$FILE_PATH" ]; then
   exit 0

package/templates/.claude/hooks/sensitive-data-guard.sh

@@ -30,9 +30,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 HOOK_DIR="$SCRIPT_DIR"
 SCRIPT_PATH="$HOOK_DIR/../ukit/runtime/sensitive-value-scanner.mjs"
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-# Bounded stdin (H01) — fail-closed overflow: an oversized payload is REFUSED
-# (silent exit 2, nothing staged, nothing echoed). The gate never truncates
-# unknown overflow and never materializes it in a shell variable.
+# Bounded stdin (H01). TASK-003: staging uses `truncate` so a cut payload can be
+# SALVAGED — when the decision-relevant field is provably complete the guard
+# runs the real scan on it; when it cannot be recovered the gate refuses
+# fail-closed (exit 2 + §8 systemMessage, never `ask`: bypassPermissions
+# auto-approves `ask` on the direct host — review R1-1).
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 # TASK-019: arm advisory latency telemetry; the finish row is written by the
@@ -40,7 +42,7 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 # runtime (pre-install tree) simply leaves telemetry off.
 source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
-  ukit_stage_hook_input 2097152 refuse
+  ukit_stage_hook_input 2097152 truncate
   STAGE_RC=$?
   if [ "$STAGE_RC" -ne 0 ]; then
     # BUG-C21-02: a fail-closed refusal must never be a SILENT block — emit the
@@ -51,6 +53,40 @@ source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
     echo 'BLOCKED (sensitive data gate): payload could not be staged within bounds; never scanned (fail-closed).' >&2
     exit 2
   fi
+  # TASK-003 degraded-path salvage: recover hook_event_name + the channel's
+  # scanned field (prompt for UserPromptSubmit; tool_name + the decision field
+  # for PreToolUse Read/Grep/Bash). Every salvage step must prove its field
+  # COMPLETE; any failure refuses fail-closed — a partial field is never
+  # scanned (a truncated dangerous shape could parse benign = fail-open).
+  if ukit_input_degraded; then
+    __ukit_salvage_fail() {
+      printf '%s\n' '{"systemMessage":"UKit sensitive-data gate blocked this call: the tool-call payload was truncated or stalled during stdin staging and its scanned field could not be recovered intact, so it was never scanned. Fail-closed — reduce the payload or check for a stalled producer."}'
+      echo 'BLOCKED (sensitive data gate): truncated/stalled payload; scanned field unrecoverable — refused fail-closed.' >&2
+      exit 2
+    }
+    UKIT_SALVAGED_EVENT="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "hook_event_name")" || __ukit_salvage_fail
+    UKIT_SALVAGED_TOOL_NAME=""
+    UKIT_SALVAGED_FIELD_NAME=""
+    UKIT_SALVAGED_FIELD_VALUE=""
+    case "$UKIT_SALVAGED_EVENT" in
+      UserPromptSubmit)
+        UKIT_SALVAGED_FIELD_NAME="prompt"
+        UKIT_SALVAGED_FIELD_VALUE="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "prompt")" || __ukit_salvage_fail
+        ;;
+      PreToolUse)
+        UKIT_SALVAGED_TOOL_NAME="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "tool_name")" || __ukit_salvage_fail
+        case "$UKIT_SALVAGED_TOOL_NAME" in
+          Read) UKIT_SALVAGED_FIELD_NAME="file_path" ;;
+          Grep) UKIT_SALVAGED_FIELD_NAME="path" ;;
+          Bash) UKIT_SALVAGED_FIELD_NAME="command" ;;
+          *) __ukit_salvage_fail ;;
+        esac
+        UKIT_SALVAGED_FIELD_VALUE="$(ukit_salvage_tool_field "$UKIT_INPUT_FILE" "tool_input.$UKIT_SALVAGED_FIELD_NAME")" || __ukit_salvage_fail
+        ;;
+      *) __ukit_salvage_fail ;;
+    esac
+    UKIT_SALVAGE_ACTIVE=1
+  fi
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -90,7 +126,7 @@ else
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" SCRIPT_PATH="$SCRIPT_PATH" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" SCRIPT_PATH="$SCRIPT_PATH" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" UKIT_SALVAGE_ACTIVE="${UKIT_SALVAGE_ACTIVE:-0}" UKIT_SALVAGED_EVENT="${UKIT_SALVAGED_EVENT:-}" UKIT_SALVAGED_TOOL_NAME="${UKIT_SALVAGED_TOOL_NAME:-}" UKIT_SALVAGED_FIELD_NAME="${UKIT_SALVAGED_FIELD_NAME:-}" UKIT_SALVAGED_FIELD_VALUE="${UKIT_SALVAGED_FIELD_VALUE:-}" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 // BUG-C21-03 (chosen posture: FAIL-CLOSED, parity with the staging refusal):
 // a wedged scan must never pass an uninspected payload. The deadline emits a
@@ -127,6 +163,22 @@ const payload = (() => {
   }
 })();
 
+// TASK-003: on the degraded path the staged prefix cannot parse, so the shell
+// handed us the provably-COMPLETE salvaged fields — reconstruct just enough
+// payload for the normal channel scan below.
+if (process.env.UKIT_SALVAGE_ACTIVE === '1' && process.env.UKIT_SALVAGED_EVENT) {
+  payload.hook_event_name = process.env.UKIT_SALVAGED_EVENT;
+  if (process.env.UKIT_SALVAGED_EVENT === 'PreToolUse' && process.env.UKIT_SALVAGED_TOOL_NAME) {
+    payload.tool_name = process.env.UKIT_SALVAGED_TOOL_NAME;
+    payload.tool_input = {};
+    if (process.env.UKIT_SALVAGED_FIELD_NAME) {
+      payload.tool_input[process.env.UKIT_SALVAGED_FIELD_NAME] = process.env.UKIT_SALVAGED_FIELD_VALUE;
+    }
+  } else if (process.env.UKIT_SALVAGED_EVENT === 'UserPromptSubmit') {
+    payload.prompt = process.env.UKIT_SALVAGED_FIELD_VALUE;
+  }
+}
+
 const projectRoot = process.env.PROJECT_ROOT || process.cwd();
 
 async function readJsonSafe(filePath, fallback) {

package/templates/.claude/hooks/session-episode.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# session-episode.sh — SessionEnd hook: append a session episode to memory v2.
+#
+# Contract (SPEC §7b, TASK-231):
+#   * ALWAYS exits 0 — a session must never be blocked from ending.
+#   * No decision JSON — UKIT_HOOK_CHAIN_RUNNER-safe.
+#   * Runs `ukit memory episode` ONLY when
+#     .ukit/storage/config.json → learning.episodes.autoWrite === true
+#     (read defensively — the namespace may not exist yet) AND `ukit` resolves
+#     on PATH. Episode writes dedupe on meta.ledgerKey, so double-invocation is
+#     harmless.
+#   * Exports UKIT_SESSION_ID from the stdin payload's session_id so the CLI
+#     resolves the same exec-ledger file the session wrote.
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+CONFIG_FILE="$PROJECT_ROOT/.ukit/storage/config.json"
+
+# Bounded stdin read (existing hook style): cap +1 byte in background so a
+# producer that never closes the pipe cannot park the session teardown.
+UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-episode-in.XXXXXX")" || exit 0
+if [ -e /dev/fd/0 ]; then
+  exec 8<&0
+  head -c 65537 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  UKIT_HEAD_PID=$!
+  # UKIT_HOOK_STAGE_MS:-2000 — bounded wait for the staged payload.
+  ( sleep 2; kill "$UKIT_HEAD_PID" 2>/dev/null ) &
+  UKIT_WATCH_PID=$!
+  wait "$UKIT_HEAD_PID" 2>/dev/null
+  kill "$UKIT_WATCH_PID" 2>/dev/null
+fi
+
+# Gate + session extraction in one bounded node step; all failures → exit 0.
+# UKIT_HOOK_DEADLINE_MS:-5000 — keeps the registered 8s timeout comfortably
+# above stage (2s) + deadline (5s) + margin (1s).
+node -e '
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 5000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+
+const inputFile = process.argv[1];
+const configPath = process.argv[2];
+const projectRoot = process.argv[3];
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+let payload = {};
+try {
+  const raw = fs.readFileSync(inputFile, "utf8");
+  payload = JSON.parse(raw || "{}") || {};
+} catch {}
+
+const config = readJson(configPath) || {};
+if (config?.learning?.episodes?.autoWrite !== true) process.exit(0);
+
+const probe = spawnSync("ukit", ["--version"], {
+  shell: true, stdio: "ignore", timeout: 2000,
+});
+if (probe.error || probe.status === null || probe.status === undefined) process.exit(0);
+
+const sessionId = typeof payload.session_id === "string" && payload.session_id.trim()
+  ? payload.session_id.trim()
+  : null;
+
+spawnSync("ukit", ["memory", "episode"], {
+  shell: true,
+  stdio: "ignore",
+  timeout: 4000,
+  cwd: projectRoot,
+  env: sessionId
+    ? { ...process.env, UKIT_SESSION_ID: sessionId }
+    : process.env,
+});
+' "$UKIT_INPUT_FILE" "$CONFIG_FILE" "$PROJECT_ROOT" 2>/dev/null || true
+
+rm -f "$UKIT_INPUT_FILE" 2>/dev/null || true
+exit 0

package/templates/.claude/settings.json

@@ -57,8 +57,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\":8",
+            "timeout": 18
           }
         ]
       },
@@ -67,33 +67,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/stale-spec-guard.sh\"",
-            "timeout": 11
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-edit-backup.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
-            "timeout": 20
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/stale-spec-guard.sh\":11 \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-edit-backup.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\":20 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\":8",
+            "timeout": 73
           }
         ]
       },
@@ -102,33 +77,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\"",
-            "timeout": 15
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\":15 \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\":8",
+            "timeout": 65
           }
         ]
       }
@@ -139,8 +89,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\":8",
+            "timeout": 18
           }
         ]
       },
@@ -149,18 +99,8 @@
         "hooks": [
           {
             "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": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\":8",
+            "timeout": 34
           }
         ]
       },
@@ -169,13 +109,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\"",
-            "timeout": 12
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\":8",
+            "timeout": 30
           }
         ]
       }
@@ -185,23 +120,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
-            "timeout": 20
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\"",
-            "timeout": 12
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\"",
-            "timeout": 10
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\":20 \"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-window-guard.sh\":10",
+            "timeout": 60
           }
         ]
       }
@@ -211,8 +131,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\":8",
+            "timeout": 18
           }
         ]
       }
@@ -222,8 +142,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reinject-context.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/reinject-context.sh\":8",
+            "timeout": 18
           }
         ]
       }
@@ -233,23 +153,19 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\"",
-            "timeout": 8
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\"",
-            "timeout": 12
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\"",
-            "timeout": 12
-          },
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/project-important.sh\":8 \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\":12 \"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\":8",
+            "timeout": 50
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-resume.sh\"",
-            "timeout": 8
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-episode.sh\":8",
+            "timeout": 18
           }
         ]
       }

package/templates/.claude/ukit/index/route-task.mjs

@@ -3793,6 +3793,12 @@ function buildRouteAuditEntry({ route = null, state = null } = {}) {
     }),
     targetFile: route?.routingContext?.targetFile ?? null,
     taskType: routingContext.taskType ?? null,
+    // FR-202a (TASK-228): active-skill ids for phase-2 skill-accuracy roll-ups.
+    // Telemetry only — deliberately excluded from dedupeKey/fingerprint inputs.
+    skillIds: (route?.activeSkills ?? state?.activeSkills ?? [])
+      .map((s) => s?.id)
+      .filter(Boolean)
+      .slice(0, 8),
     executionMode: routeSummary.executionMode ?? null,
     competingMode: routeSummary?.approachSelector?.competingMode ?? null,
     competingScoreGap: routeSummary?.approachSelector?.competingScoreGap ?? null,