@ngockhoale/ukit 2.4.1 → 2.4.3

package/templates/.claude/hooks/auto-allow-bash.sh

@@ -2,13 +2,58 @@
 # PreToolUse hook: auto-add Bash(<binary>:*) allow rules for frequently used commands.
 # Settings/usage updates run as ONE locked, atomic read-modify-write (see node block).
 
-INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# 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
+# shared cleanup path before the staged payload is removed. A missing
+# 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
+  # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
+  ukit_stage_hook_input 2097152 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+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 safe commands still receive managed metadata.
 if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
   COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
 else
   COMMAND=$(printf '%s' "$INPUT" | node -e '
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (chunk) => chunks.push(chunk));
 process.stdin.on("end", () => {
@@ -67,20 +112,30 @@ MAX_RULES="${CLAUDE_AUTO_ALLOW_MAX_RULES:-150}"
 # stale snapshot and rewrite the whole file, silently dropping each other's allow rules
 # (verified: 30 concurrent invocations kept 26/30 rules and 23/30 usage records). A lost
 # rule means the NEXT invocation of that command prompts for permission again — the agent
-# stalls waiting for a human click. The lock protocol below is protocol-compatible with
-# runtime token-utils withFileLock / src/core/fileOps.js (mkdir-based `<file>.lock`),
-# with the usage file as the single serialization point for both files this hook writes.
+# stalls waiting for a human click. The lock is the shared runtime async-lock utility
+# (TASK-028): protocol-compatible with runtime token-utils withFileLock /
+# src/core/fileOps.js (mkdir-based `<file>.lock` + owner file), with the usage file as
+# the single serialization point for both files this hook writes.
 #
 # Why atomic writes: Claude Code re-reads settings.local.json to decide permissions.
 # A torn/partial write would fail JSON parsing and drop the ENTIRE allow list — every
 # command would prompt. tmp+rename makes readers see old-or-new, never half.
 #
-# Liveness over strictness: if the lock cannot be acquired within maxWaitMs the mutation
-# runs anyway (pre-lock behaviour) — this hook must never hang a PreToolUse chain.
-node -e '
-const crypto = require("crypto");
+# TASK-028 fail-closed policy: the acquisition budget derives from the remaining hook
+# deadline minus a cleanup reserve, capped at a short slice, so a contended lock can
+# never hold this hook near its own deadline. On busy/abort the mutation is SKIPPED —
+# sensitive permission state is never written unlocked, and the command simply falls
+# back to the normal permission prompt (the pre-UKit behaviour, always safe).
+UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node -e '
+// Deadline must exceed the derived lock budget in this block (remaining deadline minus
+// reserve, capped at a short slice) so the watchdog can never fire while the mutation
+// is still legally waiting for the lock.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 8000;
+const LOCK_STARTED_AT = Date.now();
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const fs = require("fs");
 const path = require("path");
+const { pathToFileURL } = require("url");
 
 const settingsPath = process.argv[1];
 const usagePath = process.argv[2];
@@ -116,84 +171,7 @@ function appendAudit(event, payload) {
   fs.appendFileSync(auditPath, JSON.stringify({ ts: nowUtc, event, ...payload }) + "\n");
 }
 
-function isPidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error?.code === "EPERM";
-  }
-}
-
-function readLockOwner(lockPath) {
-  const owner = readJson(path.join(lockPath, "owner"), null);
-  return owner && Number.isInteger(owner.pid) && typeof owner.token === "string"
-    ? owner
-    : null;
-}
-
-async function withLock(lockPath, fn) {
-  const staleMs = 10000;
-  const maxWaitMs = 5000;
-  const startedAt = Date.now();
-  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
-  let held = false;
-  while (!held) {
-    try {
-      fs.mkdirSync(lockPath);
-      try {
-        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
-          pid: process.pid,
-          token: ownerToken,
-          ts: Date.now(),
-        }));
-      } catch (error) {
-        try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
-        } catch {}
-        throw error;
-      }
-      held = true;
-    } catch (error) {
-      if (!error || error.code !== "EEXIST") return fn();
-      try {
-        const stat = fs.statSync(lockPath);
-        if (Date.now() - stat.mtimeMs > staleMs) {
-          const owner = readLockOwner(lockPath);
-          if (!owner || !isPidAlive(owner.pid)) {
-            try {
-              fs.rmSync(lockPath, { recursive: true, force: true });
-              continue;
-            } catch {}
-          }
-        }
-      } catch {}
-      if (Date.now() - startedAt > maxWaitMs) break;
-      await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
-    }
-  }
-  try {
-    return await fn();
-  } finally {
-    if (held) {
-      const owner = readLockOwner(lockPath);
-      if (owner?.token === ownerToken) {
-        try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
-        } catch {}
-      }
-    }
-  }
-}
-
-// The lock directory lives beside the usage file, so its parent must exist BEFORE the
-// lock is taken — a first-ever run in a fresh project would otherwise fail mkdir with
-// ENOENT, fail open, and race.
-fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
-fs.mkdirSync(path.dirname(usagePath), { recursive: true });
-
-withLock(`${usagePath}.lock`, () => {
+async function applyMutation() {
   const settings = readJson(settingsPath, {});
   if (!settings.permissions || typeof settings.permissions !== "object") {
     settings.permissions = {};
@@ -245,7 +223,41 @@ withLock(`${usagePath}.lock`, () => {
     writeJsonAtomic(settingsPath, settings);
   }
   writeJsonAtomic(usagePath, usage);
-}).catch(() => {});
+}
+
+(async () => {
+  // The lock directory lives beside the usage file, so its parent must exist BEFORE
+  // the lock is taken — a first-ever run in a fresh project would otherwise fail
+  // mkdir with ENOENT.
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.mkdirSync(path.dirname(usagePath), { recursive: true });
+
+  const runtimeDir = process.env.UKIT_RUNTIME_DIR || "";
+  const lockModulePath = runtimeDir ? path.join(runtimeDir, "async-lock.mjs") : "";
+  let lockModule = null;
+  if (lockModulePath && fs.existsSync(lockModulePath)) {
+    try {
+      lockModule = await import(pathToFileURL(lockModulePath).href);
+    } catch {
+      lockModule = null;
+    }
+  }
+  if (!lockModule || typeof lockModule.withAsyncLock !== "function") {
+    // Degraded install (runtime module missing): fail closed. Writing permission
+    // state unlocked silently dropped allow rules under concurrency; skipping only
+    // costs the normal permission prompt for this one command.
+    return;
+  }
+  const deadlineMs = lockModule.lockBudgetMs({
+    hookDeadlineMs: HOOK_DEADLINE_MS,
+    startedAt: LOCK_STARTED_AT,
+  });
+  const outcome = await lockModule.withAsyncLock(usagePath, { deadlineMs }, applyMutation);
+  if (!outcome.ok) {
+    // busy or aborted: fail closed — write nothing unlocked, exit 0.
+    return;
+  }
+})().catch(() => {});
 ' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$RULE" "$NOW_UTC" "$MAX_RULES" >/dev/null 2>&1 || true
 
 exit 0

package/templates/.claude/hooks/auto-prune-bash.sh

@@ -14,6 +14,10 @@ fi
 NOW_UTC=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
 node -e '
+// Deadline must exceed the bounded lock wait in this block (maxWaitMs = 5000) so the
+// watchdog can never fire while the mutation is still legally waiting for the lock.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 8000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");

package/templates/.claude/hooks/block-dangerous.sh

@@ -2,13 +2,58 @@
 # PreToolUse hook: Block dangerous bash commands
 # Matched on: Bash
 
-INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# 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
+# shared cleanup path before the staged payload is removed. A missing
+# 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
+  # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
+  ukit_stage_hook_input 2097152 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+INPUT="$(cat "$UKIT_INPUT_FILE")"
 # jq is not installed on stock macOS. Keep jq as the low-latency normal path, but use
 # UKit's required Node runtime as a fallback so its absence cannot silently disable the gate.
 if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
   COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
 else
   COMMAND=$(printf '%s' "$INPUT" | node -e '
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const chunks = [];
 process.stdin.on("data", (chunk) => chunks.push(chunk));
 process.stdin.on("end", () => {

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

@@ -1,21 +1,79 @@
 #!/bin/bash
-# Stop hook: block premature terminal stops while routed completion evidence is missing.
-# ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
+# Stop hook: the ONE Stop delegate (TASK-025). Blocks premature terminal stops while
+# routed completion evidence is missing, and — via stop-coordinator.mjs — merges the
+# task watchdog's budget policy into the same single decision (PLAN §2 H17: both hooks
+# used to block Stop independently).
+#
+# This script is a thin delegate: it stages the hook payload, hands it to
+# .claude/ukit/runtime/stop-coordinator.mjs once, and passes the single decision
+# through. Failure posture:
+#   - coordinator script missing (pre-install tree) → loud advisory release ("ukit install")
+#   - coordinator crashed (non-zero exit)           → fail-closed BLOCK with a fixed,
+#                                                     redacted infrastructure reason;
+#                                                     a crashed gate must not silently
+#                                                     release the stop.
 
-INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# 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
+# shared cleanup path before the staged payload is removed. A missing
+# 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
+  # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
+  ukit_stage_hook_input 2097152 truncate || exit 0
+else
+  # wrapper's own fail-loud behavior below alive.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
+INPUT="$(cat "$UKIT_INPUT_FILE")"
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
+SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/stop-coordinator.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
-  printf '%s\n' '{"systemMessage":"UKit completion gate: runtime script missing — run: ukit install"}'
+  printf '%s\n' '{"systemMessage":"UKit stop coordinator: runtime script missing — run: ukit install"}'
   exit 0
 fi
 
-OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code node "$SCRIPT" --evaluate-stop)
+OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --evaluate-stop)
 STATUS=$?
 
 if [ "$STATUS" -ne 0 ]; then
-  printf '%s\n' '{"systemMessage":"UKit completion gate: runtime script failed — run: ukit install"}'
+  # TASK-025: the Stop coordinator is the fail-closed blocker — a crash must not
+  # release the stop. The reason is a fixed redacted string: crash detail (already
+  # written to stderr by the coordinator) never leaks into the decision.
+  printf '%s\n' '{"decision":"block","reason":"UKit stop coordinator: infrastructure failure while evaluating this stop — the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message."}'
   exit 0
 fi
 

package/templates/.claude/hooks/compress-output.sh

@@ -9,8 +9,55 @@ HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_PATH="$HOOK_DIR/../ukit/runtime/output-compression.mjs"
 
 if [ -f "$SCRIPT_PATH" ]; then
-  INPUT="$(cat)"
-  printf '%s' "$INPUT" | node "$SCRIPT_PATH"
+  # shellcheck source=/dev/null
+  if source "$HOOK_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+  # TASK-019: arm advisory latency telemetry; the finish row is written by the
+  # shared cleanup path before the staged payload is removed. A missing
+  # runtime (pre-install tree) simply leaves telemetry off.
+  source "$HOOK_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+    trap ukit_cleanup_hook_input EXIT
+    # Bounded stdin (H01): compressed tool output can be large, so the staged
+    # file is the transport and the shell var only mirrors the capped payload.
+    ukit_stage_hook_input 33554432 temp-file || exit 0
+  else
+      # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline — `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 33554433 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 33554433 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  if [ "$__ukit_stage_rc" -ne 0 ]; then
+    # Unstaged: the hook cannot inspect this payload.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+  else
+    if [ "$__ukit_size" -gt 33554432 ]; then
+      truncate -s 33554432 "$UKIT_INPUT_FILE" 2>/dev/null
+    fi
+    trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+  fi
+  fi
+  INPUT="$(cat "$UKIT_INPUT_FILE")"
+  printf '%s' "$INPUT" | UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-8000}" node "$SCRIPT_PATH"
   exit $?
 fi
 

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

@@ -29,18 +29,63 @@
 # Config toggle: compact.hardCapBlock (default true). Set to false only to debug this
 # gate itself; it must not become a normal escape hatch.
 
-INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=/dev/null
+if source "$HOOK_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$HOOK_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
+  trap ukit_cleanup_hook_input EXIT
+  # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
+  ukit_stage_hook_input 2097152 truncate || exit 0
+else
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
+    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  fi
+  trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+fi
 
-INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" HOOK_DIR="$HOOK_DIR" node <<'NODE'
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 const fs = require('fs');
 const path = require('path');
 const { pathToFileURL } = require('url');
 
+let rawInput = '';
+try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
 const payload = (() => {
   try {
-    const parsed = JSON.parse(process.env.INPUT || '');
+    const parsed = JSON.parse(rawInput);
     return parsed && typeof parsed === 'object' ? parsed : {};
   } catch {
     return {};
@@ -136,7 +181,10 @@ function readRunCursor() {
   } catch {
     state = mod.buildCompactPressureState(rawState, sessionConfig);
   }
-  const thresholds = mod.buildCompactThresholds(config);
+  // projectRoot is passed explicitly so the cap is negotiated from THIS project's
+  // published capacity record rather than from whatever cwd the host happened to use —
+  // the gate is fail-closed, so it must read the same evidence the guard wrote.
+  const thresholds = mod.buildCompactThresholds({ ...config, projectRoot });
 
   // The grace budget must survive parallel subagents hitting the cap in the same episode.
   // A read-modify-write of one JSON file under-counts (two processes both read used=3 and