@ngockhoale/ukit 2.4.1 → 2.4.2

package/src/core/gatewayResilienceEnv.js

@@ -4,14 +4,24 @@ import os from 'node:os';
 import path from 'node:path';
 
 // Managed defaults that keep Claude Code responsive when it is pointed at a custom
-// gateway (any non-empty ANTHROPIC_BASE_URL). `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='1'`
-// forces streaming mode so the client never falls back to a non-streaming POST that can
-// stall for minutes waiting for the full response. `CLAUDE_STREAM_IDLE_TIMEOUT_MS='600000'`
-// raises Claude Code's internal idle timeout from its default (the gateway-side keep-alive
-// can sit idle longer than the default when the upstream is slow).
+// gateway (any non-empty ANTHROPIC_BASE_URL). Posture since 2.4.2 — "fail fast, recover
+// via non-streaming" — based on 2026-09-16 live probes of the stall-class gateway:
+//   * The gateway buffers entire streams (23 SSE events delivered in ONE body read), so a
+//     long generation is silent until it finishes and Claude Code's stream-idle watchdog
+//     is the only thing that can end the silence. `CLAUDE_STREAM_IDLE_TIMEOUT_MS='120000'`
+//     bounds that dead air to 2 minutes instead of hanging for 10.
+//   * The non-streaming route is HEALTHY on the stall-class gateway (HTTP 200 + valid
+//     Anthropic Message), and a non-streaming POST has no idle watchdog at all — it is the
+//     one request shape that reliably survives a buffered long generation. So the fallback
+//     must stay ENABLED (`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='0'`); disabling it
+//     (the 2.3.16–2.4.1 posture) removed the only recovery path and turned stalls into
+//     silent freezes the user had to interrupt by hand.
 //
 // These are written ONLY when no user-set value already lives in the project's
-// `.claude/settings.json` env block — never clobber, always preserve. Re-running
+// `.claude/settings.json` env block — never clobber, always preserve — EXCEPT for values
+// equal to `GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS` (the shipped defaults of
+// 2.3.16–2.4.1): those were written by UKit itself, so they migrate to the current
+// defaults on the next install instead of being mistaken for user intent. Re-running
 // `ukit install` is a no-op once the keys are in place.
 //
 // Probe order mirrors `templates/.claude/ukit/index/unic-gateway.mjs` (env → project
@@ -21,12 +31,22 @@ import path from 'node:path';
 // is pointed at ANY gateway, so we apply resilience regardless of vendor.
 
 export const GATEWAY_RESILIENCE_ENV_DEFAULTS = Object.freeze({
+  CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '0',
+  CLAUDE_STREAM_IDLE_TIMEOUT_MS: '120000',
+});
+
+// Values shipped as the managed defaults by 2.3.16–2.4.1. A settings env key holding one
+// of these exact values was written by UKit, not by the user, so `applyGatewayResilienceEnv`
+// migrates it to the current default. A user who deliberately tuned a value always uses a
+// non-shipped number (e.g. '300000', '900000') and stays untouched.
+export const GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS = Object.freeze({
   CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1',
   CLAUDE_STREAM_IDLE_TIMEOUT_MS: '600000',
 });
 
 const BASE_URL_ENV_VAR = 'ANTHROPIC_BASE_URL';
 const SETTINGS_RELATIVE_PATH = path.join('.claude', 'settings.json');
+const PROFILE_RELATIVE_PATH = path.join('.claude', 'profile');
 
 function readBaseUrlFromEnvValue(value) {
   return typeof value === 'string' && value.trim().length > 0 ? value : null;
@@ -124,6 +144,7 @@ function backupPathFor(settingsPath) {
  *   applied: string[],
  *   unchanged: string[],
  *   skipped: string[],
+ *   migrated: string[],
  *   changed: boolean,
  *   reason?: string,
  * }>}
@@ -162,6 +183,7 @@ export async function applyGatewayResilienceEnv({
         applied: [],
         unchanged: [],
         skipped: [],
+        migrated: [],
         changed: false,
         reason: `failed to read settings: ${error?.message ?? String(error)}`,
       };
@@ -180,6 +202,7 @@ export async function applyGatewayResilienceEnv({
         applied: [],
         unchanged: [],
         skipped: [],
+        migrated: [],
         changed: false,
         reason: `failed to parse settings JSON: ${error?.message ?? String(error)}`,
       };
@@ -204,6 +227,7 @@ export async function applyGatewayResilienceEnv({
   const applied = [];
   const unchanged = [];
   const skipped = [];
+  const migrated = [];
   let mutated = false;
 
   for (const [key, defaultValue] of Object.entries(GATEWAY_RESILIENCE_ENV_DEFAULTS)) {
@@ -218,6 +242,18 @@ export async function applyGatewayResilienceEnv({
       unchanged.push(key);
       continue;
     }
+    // A value equal to a previously-shipped UKit default was written by UKit itself —
+    // migrate it to the current default instead of treating it as user intent.
+    if (
+      typeof currentValue === 'string' &&
+      currentValue === GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS[key]
+    ) {
+      settings.env[key] = defaultValue;
+      applied.push(key);
+      migrated.push(key);
+      mutated = true;
+      continue;
+    }
     // User owns a non-default value — never touch it.
     skipped.push(key);
   }
@@ -228,6 +264,7 @@ export async function applyGatewayResilienceEnv({
       applied,
       unchanged,
       skipped,
+      migrated,
       changed: false,
     };
   }
@@ -243,6 +280,7 @@ export async function applyGatewayResilienceEnv({
     applied,
     unchanged,
     skipped,
+    migrated,
     changed: true,
   };
 }
@@ -271,7 +309,11 @@ export function formatGatewayResilienceReport(report) {
   );
 
   for (const key of report.applied || []) {
-    lines.push(`  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])} (applied)`);
+    const legacyValue = GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS[key];
+    const migrated = (report.migrated || []).includes(key) && legacyValue !== undefined;
+    lines.push(
+      `  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])}${migrated ? ` (migrated from previous UKit default ${JSON.stringify(legacyValue)})` : ' (applied)'}`,
+    );
   }
   for (const key of report.unchanged || []) {
     lines.push(`  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])} (already set)`);
@@ -290,3 +332,90 @@ export function formatGatewayResilienceReport(report) {
 
   return lines;
 }
+
+/**
+ * Advisory presence scan of the per-profile settings files under
+ * `<homeDir>/.claude/profile/`. A session launched with
+ * `--settings ~/.claude/profile/<name>.json` bypasses `~/.claude/settings.json` entirely, so
+ * a managed resilience key can be absent exactly where it matters while every other check
+ * reports green. This is the delivery-gap detector for that hole.
+ *
+ * Presence-check only — never a value-check. After the documented posture flip the values
+ * are user/machine-owned (a profile may legitimately hold a legacy `'1'`/`'600000'` pair or a
+ * tuned number), so "is the key present" is the whole contract and no value is compared
+ * against `GATEWAY_RESILIENCE_ENV_DEFAULTS`.
+ *
+ * Only regular files ending in `.json` are scanned (sorted by name); decoys that live in the
+ * real profile dir — backups like `x.json.bak-20260916`, `notes.sh`, and subdirectories — are
+ * ignored, and the scan is not recursive. An absent profile directory is not an error: it
+ * resolves `{ scanned: [], compliant: true }` so a machine that never used profiles stays
+ * quiet. Never throws: an unreadable directory, unreadable file, or invalid JSON is
+ * reflected in the per-file result instead of propagating.
+ *
+ * @param {{ homeDir?: string, profileDir?: string|null, keys?: string[]|null }} [options]
+ * @returns {Promise<{ profileDir: string, scanned: Array<{ file: string, validJson: boolean, hasEnvBlock: boolean, missing: string[] }>, compliant: boolean }>}
+ */
+export async function scanProfileResilienceEnv({
+  homeDir = os.homedir(),
+  profileDir = null,
+  keys = null,
+} = {}) {
+  const resolvedProfileDir = profileDir || path.join(homeDir, PROFILE_RELATIVE_PATH);
+  const managedKeys = Array.isArray(keys) && keys.length > 0
+    ? keys
+    : Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS);
+
+  const emptyResult = { profileDir: resolvedProfileDir, scanned: [], compliant: true };
+
+  let entries;
+  try {
+    entries = await fs.readdir(resolvedProfileDir, { withFileTypes: true });
+  } catch {
+    // Absent (ENOENT) or unreadable (EACCES) profile dir — nothing to warn about.
+    return emptyResult;
+  }
+
+  const jsonFiles = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort();
+
+  if (jsonFiles.length === 0) {
+    return emptyResult;
+  }
+
+  const scanned = [];
+  for (const name of jsonFiles) {
+    const file = path.join(resolvedProfileDir, name);
+    let raw;
+    try {
+      raw = await fs.readFile(file, 'utf8');
+    } catch {
+      scanned.push({ file, validJson: false, hasEnvBlock: false, missing: [...managedKeys] });
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      scanned.push({ file, validJson: false, hasEnvBlock: false, missing: [...managedKeys] });
+      continue;
+    }
+
+    const envBlock = parsed?.env;
+    const hasEnvBlock =
+      Boolean(envBlock) && typeof envBlock === 'object' && !Array.isArray(envBlock);
+    const missing = hasEnvBlock
+      ? managedKeys.filter((key) => !(key in envBlock))
+      : [...managedKeys];
+
+    scanned.push({ file, validJson: true, hasEnvBlock, missing });
+  }
+
+  return {
+    profileDir: resolvedProfileDir,
+    scanned,
+    compliant: scanned.every((entry) => entry.missing.length === 0),
+  };
+}

package/src/index/buildIndex.js

@@ -36,12 +36,15 @@ const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
 const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.sql', '.json', '.yaml', '.yml', '.md', '.sh']);
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+// Bumped only when the snapshot shape itself changes; consumers must reject
+// snapshots from a different version instead of trusting unknown fields.
+export const DISCOVERY_SNAPSHOT_VERSION = 1;
 const INDEX_PARSE_BATCH_SIZE = 8;
 const CALL_IGNORE_WORDS = new Set([
   'if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof',
 ]);
 
-export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
+export async function buildCodeIndex({ rootDir = process.cwd(), discoverySnapshot = null } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const indexDir = getIndexDir(absoluteRoot);
 
@@ -55,7 +58,14 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     previousCodeFileRecords.map((item) => [item.filePath, { mtimeMs: Number(item.mtimeMs ?? -1), size: Number(item.size ?? -1) }]),
   );
 
-  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
+  // Reuse the caller's discovery snapshot when it describes exactly this root
+  // under the current schema and snapshot version; anything else (foreign root,
+  // stale schema, wrong shape) is rejected and the repository is rediscovered
+  // once here. This is what keeps a stale-check + rebuild refresh at a single
+  // enumeration instead of two.
+  const discoveredFiles = isDiscoverySnapshotUsable(discoverySnapshot, absoluteRoot)
+    ? discoverySnapshot.files
+    : await discoverProjectFiles(absoluteRoot);
   const sourceFingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
   const styleFilePaths = discoveredFiles
     .map((entry) => {
@@ -1071,6 +1081,27 @@ async function discoverProjectFiles(rootDir) {
   return collectFiles([rootDir]);
 }
 
+function createDiscoverySnapshot(rootDir, files, fingerprint) {
+  // Frozen: the snapshot must stay byte-stable between the staleness inspection
+  // and the build that consumes it, and callers must not mutate shared state.
+  return Object.freeze({
+    snapshotVersion: DISCOVERY_SNAPSHOT_VERSION,
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    rootDir,
+    fingerprint,
+    files: Object.freeze(files.slice()),
+  });
+}
+
+function isDiscoverySnapshotUsable(discoverySnapshot, absoluteRoot) {
+  return Boolean(discoverySnapshot)
+    && discoverySnapshot.snapshotVersion === DISCOVERY_SNAPSHOT_VERSION
+    && discoverySnapshot.schemaVersion === INDEX_SCHEMA_VERSION
+    && typeof discoverySnapshot.rootDir === 'string'
+    && path.resolve(discoverySnapshot.rootDir) === absoluteRoot
+    && Array.isArray(discoverySnapshot.files);
+}
+
 function runGit(rootDir, args) {
   const result = spawnSync('git', args, {
     cwd: rootDir,
@@ -1810,36 +1841,55 @@ export async function getIndexArtifactGeneratedAt({
   return parseArtifactGeneratedAt(artifact);
 }
 
-export async function isIndexStale({
-  rootDir = process.cwd(),
-  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
-  now = Date.now(),
-  generatedAtMs = null,
-} = {}) {
+async function evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot }) {
   const absoluteRoot = path.resolve(rootDir);
   const metaArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta);
   const effectiveGeneratedAtMs = Number.isFinite(generatedAtMs)
     ? generatedAtMs
     : parseArtifactGeneratedAt(metaArtifact);
-  if (effectiveGeneratedAtMs === null) {
-    return true;
-  }
 
-  if (typeof maxAgeMs !== 'number' || Number.isNaN(maxAgeMs) || maxAgeMs < 0) {
-    return true;
-  }
+  const staleWithoutEnumeration = effectiveGeneratedAtMs === null
+    || typeof maxAgeMs !== 'number'
+    || Number.isNaN(maxAgeMs)
+    || maxAgeMs < 0
+    || (now - effectiveGeneratedAtMs) >= maxAgeMs
+    || !metaArtifact?.sourceFingerprint;
 
-  if ((now - effectiveGeneratedAtMs) >= maxAgeMs) {
-    return true;
+  // Legacy boolean callers (query-index, triage, verify-context) stop here and
+  // let buildCodeIndex do its own discovery when a rebuild is needed.
+  if (staleWithoutEnumeration && !enumerateForSnapshot) {
+    return { stale: true, snapshot: null };
   }
 
-  if (!metaArtifact?.sourceFingerprint) {
-    return true;
-  }
+  // Exactly one enumeration per inspection. In the refresh flow this snapshot is
+  // handed to buildCodeIndex, so stale-check + rebuild enumerates the repository
+  // once instead of twice.
+  const discoveredFiles = await discoverProjectFiles(absoluteRoot);
+  const fingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
 
-  const currentSourceFingerprint = createSourceFingerprint(
-    absoluteRoot,
-    await discoverProjectFiles(absoluteRoot),
-  );
-  return !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, currentSourceFingerprint);
+  return {
+    stale: staleWithoutEnumeration
+      ? true
+      : !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, fingerprint),
+    snapshot: createDiscoverySnapshot(absoluteRoot, discoveredFiles, fingerprint),
+  };
+}
+
+export async function inspectIndexStaleness({
+  rootDir = process.cwd(),
+  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+  generatedAtMs = null,
+} = {}) {
+  return evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot: true });
+}
+
+export async function isIndexStale({
+  rootDir = process.cwd(),
+  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+  generatedAtMs = null,
+} = {}) {
+  const { stale } = await evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, enumerateForSnapshot: false });
+  return stale;
 }

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

@@ -2,13 +2,32 @@
 # 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
+  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): bounded inline staging keeps the
+  # wrapper's own fail-loud/advisory behavior below alive.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
+  cat >/dev/null 2>&1
+  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -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", () => {
@@ -78,6 +97,10 @@ MAX_RULES="${CLAUDE_AUTO_ALLOW_MAX_RULES:-150}"
 # 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 '
+// 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/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,32 @@
 # 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
+  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): bounded inline staging keeps the
+  # wrapper's own fail-loud/advisory behavior below alive.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
+  cat >/dev/null 2>&1
+  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -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

@@ -2,7 +2,24 @@
 # 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.
 
-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
+  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): bounded inline staging keeps the
+  # wrapper's own fail-loud/advisory behavior below alive.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
+  cat >/dev/null 2>&1
+  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -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"
 
@@ -11,7 +28,7 @@ if [ ! -f "$SCRIPT" ]; then
   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

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

@@ -9,8 +9,23 @@ 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
+    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): bounded inline staging keeps the
+    # wrapper's own fail-loud/advisory behavior below alive.
+    UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+    head -c 33554433 > "$UKIT_INPUT_FILE" 2>/dev/null
+    cat >/dev/null 2>&1
+    truncate -s 33554432 "$UKIT_INPUT_FILE" 2>/dev/null
+    trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
+  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,37 @@
 # 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
+  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): bounded inline staging keeps the
+  # advisory/fail-open behavior below alive with a capped payload file.
+  UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
+  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
+  cat >/dev/null 2>&1
+  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -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 {};