@ngockhoale/ukit 2.6.10 → 2.7.0

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

@@ -14,7 +14,9 @@ import { appendTelemetryRow, TELEMETRY_VERSION } from './hook-telemetry.mjs';
 // disagree. Kept as a per-run resolution (not module constants) so an operator's
 // env change is honored without a reimport.
 import {
+  resolveChainBaseBudgetMs,
   resolveChainBudgetMs,
+  resolveChainCeilingMs,
   resolveChainChildBudgetMs,
 } from './hook-chain-budget.mjs';
 
@@ -28,6 +30,41 @@ const FAIL_CLOSED_SCRIPTS = new Set([
 
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
 
+// TASK-234 review fix (critical): stdin staging must be bounded. The old
+// `fs.readFileSync(0)` blocked until the producer closed the pipe — a stalled
+// producer held the runner until the settings timeout SIGKILLed it, so every
+// fail-closed gate in the chain silently failed OPEN (no verdict emitted).
+// Bound the read: at most MAX_STDIN_BYTES and at most STDIN_STAGE_MS, then
+// mark the payload degraded so children see the same truncated-input contract
+// hook-input.sh gives them (UKIT_INPUT_TRUNCATED=1 → fail-closed gates deny).
+const MAX_STDIN_BYTES = 2 * 1024 * 1024;
+const STDIN_STAGE_MS = Number(process.env.UKIT_HOOK_STDIN_STAGE_MS || 2000);
+
+async function readStdinBounded() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let bytes = 0;
+    let settled = false;
+    const finish = (truncated) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      process.stdin.removeAllListeners();
+      process.stdin.unref?.();
+      resolve({ text: Buffer.concat(chunks).toString('utf8'), truncated });
+    };
+    const timer = setTimeout(() => finish(true), STDIN_STAGE_MS);
+    process.stdin.on('data', (chunk) => {
+      chunks.push(chunk);
+      bytes += chunk.length;
+      if (bytes > MAX_STDIN_BYTES) finish(true);
+    });
+    process.stdin.on('end', () => finish(false));
+    process.stdin.on('error', () => finish(true));
+    process.stdin.resume();
+  });
+}
+
 // TASK-018 failure taxonomy (chain level; distinct from hook-process.mjs's
 // process-level kinds). Overflow, timeout, signal, and exit-code failures are
 // distinct values so downstream consumers never have to guess:
@@ -58,8 +95,24 @@ function recordTiming(projectRoot, payload, timing) {
   // appendTelemetryRow carries the same posture (and the per-session cap).
   appendTelemetryRow(projectRoot, payload?.session_id, timing);
 }
+// TASK-234: a script arg may carry a per-script timeout suffix `<path>:<seconds>`
+// so consolidated settings.json chains keep each hook's original settings.json
+// `timeout` instead of sharing one child budget. The suffix is stripped before
+// the path is used; absent → resolveChainChildBudgetMs() fallback, unchanged.
+// A `:0` or negative suffix is rejected (falls back) — zero would mean "no
+// budget", which silently disables the deadline; that is never a valid hook
+// contract.
+function parseScriptArg(arg) {
+  const match = /^(.*):(\d+(?:\.\d+)?)$/.exec(arg || '');
+  if (!match) return { scriptPath: arg, timeoutMs: null };
+  const seconds = Number(match[2]);
+  if (!Number.isFinite(seconds) || seconds <= 0) return { scriptPath: arg, timeoutMs: null };
+  return { scriptPath: match[1], timeoutMs: Math.round(seconds * 1000) };
+}
 
-async function run(payloadText, scriptPaths) {
+async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
+  const parsedArgs = scriptArgs.map(parseScriptArg);
+  const scriptPaths = parsedArgs.map((a) => a.scriptPath);
   const payload = JSON.parse(payloadText || '{}');
   const firstScript = scriptPaths[0] || '';
   const projectRoot = firstScript
@@ -71,13 +124,41 @@ async function run(payloadText, scriptPaths) {
   // (UserPromptSubmit now carries 4 hooks). The floor keeps short chains at 10s,
   // and TASK-018's explicit ceiling stops the per-chain growth from running away.
   // Resolved per run (not at import) so an env change takes effect immediately.
-  const childBudgetMs = resolveChainChildBudgetMs();
-  const totalBudgetMs = resolveChainBudgetMs(scriptPaths.length);
+  const defaultChildBudgetMs = resolveChainChildBudgetMs();
+  const childBudgetsMs = parsedArgs.map((a) => a.timeoutMs ?? defaultChildBudgetMs);
+  // TASK-234: with per-script budgets the total must cover the SUM of declared
+  // budgets (not count × shared fallback) or a 6-hook Edit chain would be capped
+  // below its own scripts' combined timeouts. When EVERY script declares a
+  // budget the declared sum IS the inner budget — the count×fallback floor
+  // would otherwise exceed the registered outer timeout (PostToolUse Edit|Write:
+  // 3×12s=36s inner vs 34s outer → host kills the runner mid-chain). Mixed
+  // chains keep the floor so undeclared scripts still get the fallback.
+  const declaredTotalMs = childBudgetsMs.reduce((sum, ms) => sum + ms, 0);
+  const allDeclared = parsedArgs.every((a) => a.timeoutMs != null);
+  // TASK-234 review fix (important): the ceiling bounds FALLBACK-driven growth,
+  // never the declared contract — a 52s ceiling clamping a 63s declared sum
+  // starves the last fail-closed gate (context-hardcap-gate) and turns a legal
+  // edit into a block. Only EXPLICIT `:N` budgets raise the ceiling floor —
+  // fallback-filled budgets must not, or bare bridge chains would bypass the
+  // ceiling entirely (ompHookBridge TASK-018 pins that bound).
+  const explicitDeclaredMs = parsedArgs.reduce((sum, a) => sum + (a.timeoutMs ?? 0), 0);
+  const ceilingMs = Math.max(
+    resolveChainCeilingMs(),
+    resolveChainBaseBudgetMs(),
+    explicitDeclaredMs,
+  );
+  const totalBudgetMs = Math.min(
+    allDeclared
+      ? declaredTotalMs
+      : Math.max(resolveChainBudgetMs(scriptPaths.length), declaredTotalMs),
+    ceilingMs,
+  );
   const deadline = startedAt + totalBudgetMs;
   const results = [];
   let budgetExhausted = false;
 
-  for (const scriptPath of scriptPaths) {
+  for (let scriptIndex = 0; scriptIndex < scriptPaths.length; scriptIndex++) {
+    const scriptPath = scriptPaths[scriptIndex];
     const scriptName = path.basename(scriptPath);
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0) {
@@ -97,9 +178,9 @@ async function run(payloadText, scriptPaths) {
     const childStartedAt = Date.now();
     const result = await runHookProcess({
       command: scriptPath,
+      deadlineMs: Math.min(childBudgetsMs[scriptIndex], remainingMs),
       args: [],
       input: payloadText,
-      deadlineMs: Math.min(childBudgetMs, remainingMs),
       maxBuffer: MAX_BUFFER_BYTES,
       cwd: projectRoot,
       // TASK-223 (HK-401): mark chain-spawned children so their structured
@@ -109,7 +190,10 @@ async function run(payloadText, scriptPaths) {
       env: {
         ...process.env,
         CLAUDE_PROJECT_DIR: projectRoot,
-        UKIT_HOOK_CHAIN_RUNNER: '1',
+        // TASK-234: the marker selects the omp structured-decision contract
+        // (ask + exit 2). Under --emit-verdict the runner replays the direct
+        // Claude contract (deny + exit 0), so children must NOT see it.
+        ...(chainMarker ? { UKIT_HOOK_CHAIN_RUNNER: '1' } : {}),
       },
     });
     const failureKind = chainFailureKind(result);
@@ -139,6 +223,15 @@ async function run(payloadText, scriptPaths) {
     }
   }
 
+  // TASK-234 review fix (critical): a mid-chain break (killed advisory, budget
+  // exhausted, or a fail-closed non-zero) leaves later scripts unrun. When any
+  // of those unrun scripts is fail-closed, the chain must fail CLOSED — the old
+  // per-script path ran every hook independently, so a timed-out advisory never
+  // skipped a gate. `skippedFailClosed` carries that signal to the verdict.
+  const skippedFailClosed = scriptPaths
+    .slice(results.length)
+    .some((p) => FAIL_CLOSED_SCRIPTS.has(path.basename(p)));
+
   const elapsedMs = Date.now() - startedAt;
   // TASK-019: versioned rows shared with direct hooks. `outcome` reuses this
   // runner's own failure taxonomy — the aggregate of the worst child result —
@@ -165,23 +258,137 @@ async function run(payloadText, scriptPaths) {
     })),
   });
 
-  return { results, elapsedMs, budgetMs: totalBudgetMs, budgetExhausted };
+  return { results, elapsedMs, budgetMs: totalBudgetMs, budgetExhausted, skippedFailClosed };
 }
 
 try {
-  const [, , payloadArg = '{}', ...scriptPaths] = process.argv;
+  let argv = process.argv.slice(2);
+  // TASK-234: `--emit-verdict` adapts the runner for Claude Code settings.json
+  // hooks, where the command's own stdout/exit-code IS the verdict — not the
+  // JSON aggregate the omp bridge parses. In this mode the runner replays the
+  // last executed script's stdout verbatim and maps the chain outcome onto the
+  // single-command contract: exit 0 normally; exit 2 + the child's stderr when
+  // a child blocked (code 2) or a FAIL_CLOSED script could not produce a
+  // verdict (killed/error/budget-exhausted). Non-fail-closed transport failures
+  // stay fail-open (exit 0), matching today's per-script behavior where a
+  // timed-out advisory hook never blocks the call.
+  const emitVerdict = argv[0] === '--emit-verdict';
+  if (emitVerdict) argv = argv.slice(1);
+  const [payloadArg = '{}', ...scriptPaths] = argv;
   // The bridge passes the payload as a temp file (`@path`) when it can: argv is capped
   // (~256KB per arg on macOS) and PostToolUse Bash payloads embed whole tool outputs.
   // A leading '@' cannot occur in raw JSON, so the two forms are unambiguous.
+  // '-' reads the payload from stdin — the form Claude Code hook commands use.
   let payloadText = payloadArg;
-  if (payloadArg.startsWith('@')) {
+  let stdinTruncated = false;
+  if (payloadArg === '-') {
+    const staged = await readStdinBounded();
+    payloadText = staged.text;
+    stdinTruncated = staged.truncated;
+  } else if (payloadArg.startsWith('@')) {
     try {
       payloadText = fs.readFileSync(payloadArg.slice(1), 'utf8');
     } catch {
       payloadText = '{}';
     }
   }
-  process.stdout.write(JSON.stringify(await run(payloadText, scriptPaths)));
+  // A truncated stdin means the payload was never fully read — the same
+  // degraded contract hook-input.sh enforces (uninspected input must never be
+  // treated as a clean scan). Children stage their own stdin and cannot see
+  // the runner's truncation, so the runner owns the degraded verdict: when the
+  // chain carries a fail-closed gate, emit deny now instead of letting gates
+  // pass on a payload they never fully received.
+  if (stdinTruncated) {
+    const hasFailClosed = scriptPaths.some((p) =>
+      FAIL_CLOSED_SCRIPTS.has(path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, ''))));
+    if (hasFailClosed) {
+      const deny = JSON.stringify({
+        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 the fail-closed gate chain cannot prove it safe.',
+        },
+      });
+      if (emitVerdict) {
+        process.stdout.write(deny);
+        process.exitCode = 0;
+      } else {
+        process.stdout.write(JSON.stringify({
+          results: [],
+          wrapperError: 'stdin staging truncated — fail-closed chain refused',
+          stdinTruncated: true,
+        }));
+        process.exitCode = 2;
+      }
+      process.exit(emitVerdict ? 0 : 2);
+    }
+  }
+  const chain = await run(payloadText, scriptPaths, { chainMarker: !emitVerdict });
+  if (!emitVerdict) {
+    process.stdout.write(JSON.stringify(chain));
+  } else {
+    // TASK-234: a script that emits a hookSpecificOutput decision JSON owns the
+    // verdict even when it exits 0 (the direct Claude contract: deny + exit 0
+    // still blocks). The first decision wins, matching per-script semantics
+    // where each hook's output is its own verdict and a deny short-circuits.
+    const decisionResult = chain.results.find((r) =>
+      typeof r.stdout === 'string' && r.stdout.includes('"hookSpecificOutput"'));
+    const last = decisionResult ?? chain.results[chain.results.length - 1];
+
+    // TASK-234 review fix (critical): context stdout must be REPLAYED, not
+    // dropped. SessionStart/UserPromptSubmit hooks emit plain-text context
+    // (PROJECT_IMPORTANT mandate, skill-router guidance) — replaying only the
+    // decision owner's or last script's stdout loses every earlier emission.
+    // Concatenate every script's non-decision stdout in order, then append the
+    // decision JSON last so the verdict still parses.
+    const contextStdout = chain.results
+      .filter((r) => r !== decisionResult && r !== last && typeof r.stdout === 'string' && r.stdout.length > 0)
+      .map((r) => r.stdout)
+      .join('');
+
+    // TASK-234 review fix (critical): a mid-chain break that skipped a
+    // fail-closed gate must fail CLOSED — the old per-script path ran every
+    // hook independently, so a killed advisory never skipped a gate.
+    if (chain.skippedFailClosed) {
+      if (contextStdout) process.stdout.write(contextStdout);
+      const skipped = scriptPaths
+        .slice(chain.results.length)
+        .map((p) => path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, '')))
+        .filter((name) => FAIL_CLOSED_SCRIPTS.has(name))
+        .join(', ');
+      process.stderr.write(`UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`);
+      process.exitCode = 2;
+    } else if (!last) {
+      // No script ran at all (empty chain or budget spent before the first
+      // child). With fail-closed scripts declared in the chain this must not
+      // fail open.
+      const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, ''))));
+      if (hasFailClosed) {
+        process.stderr.write('UKit hook chain produced no verdict — fail-closed gate did not run\n');
+        process.exitCode = 2;
+      }
+    } else {
+      const lastIsFailClosed = FAIL_CLOSED_SCRIPTS.has(last.scriptName);
+      const lastFailedToVerdict = last.killed || last.failureKind === 'error' || last.failureKind === 'budget-exhausted';
+      if (last.code === 2) {
+        if (contextStdout) process.stdout.write(contextStdout);
+        if (last.stdout) process.stdout.write(last.stdout);
+        if (last.stderr) process.stderr.write(last.stderr);
+        process.exitCode = 2;
+      } else if (lastIsFailClosed && lastFailedToVerdict) {
+        if (contextStdout) process.stdout.write(contextStdout);
+        if (last.stderr) process.stderr.write(last.stderr);
+        else process.stderr.write(`UKit fail-closed hook ${last.scriptName} could not produce a verdict (${last.failureKind})\n`);
+        process.exitCode = 2;
+      } else {
+        if (contextStdout) process.stdout.write(contextStdout);
+        if (last.stdout) process.stdout.write(last.stdout);
+        if (last.stderr) process.stderr.write(last.stderr);
+        process.exitCode = last.code === 0 ? 0 : (lastIsFailClosed ? 2 : 0);
+      }
+    }
+  }
 } catch (error) {
   process.stdout.write(JSON.stringify({
     results: [],

package/templates/.claude/ukit/runtime/hook-input.sh

@@ -169,6 +169,125 @@ ukit_emit_input_degraded() {
   exit 0
 }
 
+# TASK-003 (salvage verdicts from truncated payloads): when the staged payload
+# is flagged truncated/stalled, a gated hook may still recover a DECISION-RELEVANT
+# field if that field's value is provably COMPLETE — the closing quote AND a
+# following `,`/`}` boundary must appear before the cut. Anything else (cut
+# inside the string, EOF right after the quote, malformed prefix, missing key)
+# is unrecoverable: callers map that to `deny`, never `ask` (bypassPermissions
+# auto-approves `ask` on the direct host = gates silently skipped).
+#
+# Contract:
+#   ukit_salvage_tool_field <json-file> <dotted-field>
+#     stdout: the decoded string value (single line may contain \n escapes
+#             decoded — the value itself is written raw)
+#     exit 0 — field recovered AND proven complete
+#     exit 3 — unrecoverable / incomplete / malformed / non-string value
+#   Budget: UKIT_SALVAGE_BUDGET_MS (default 3000) bounds the node process; the
+#   file is already capped by staging (≤2MiB), so no unbounded reads.
+#   Single string fields only — this is a salvage step, not a JSON repairer.
+ukit_salvage_tool_field() {
+  UKIT_SALVAGE_FILE="$1" UKIT_SALVAGE_FIELD="$2" \
+  UKIT_SALVAGE_BUDGET_MS="${UKIT_SALVAGE_BUDGET_MS:-3000}" node <<'UKIT_SALVAGE_NODE'
+const budget = Number.parseInt(process.env.UKIT_SALVAGE_BUDGET_MS || '3000', 10) || 3000;
+setTimeout(() => process.exit(3), budget).unref();
+const fs = require('fs');
+const fail = () => process.exit(3);
+let data;
+try {
+  data = fs.readFileSync(process.env.UKIT_SALVAGE_FILE || '', 'utf8');
+} catch {
+  fail();
+}
+const dotted = String(process.env.UKIT_SALVAGE_FIELD || '').split('.').filter(Boolean);
+if (!data || data[0] !== '{' || dotted.length === 0 || dotted.length > 4) fail();
+
+const isWs = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r';
+const skipWs = (s, i) => { while (i < s.length && isWs(s[i])) i += 1; return i; };
+// End index of the string literal starting at `start` (which must be `"`), or -1
+// when the string is cut before its closing quote.
+const scanStringEnd = (s, start) => {
+  for (let i = start + 1; i < s.length; i += 1) {
+    const c = s[i];
+    if (c === '\\') { i += 1; continue; }
+    if (c === '"') return i;
+  }
+  return -1;
+};
+// Closing brace matching the `{` at `open` (string-aware), or -1 if unclosed.
+const matchBrace = (s, open) => {
+  let depth = 0;
+  for (let i = open; i < s.length; i += 1) {
+    const c = s[i];
+    if (c === '"') {
+      const end = scanStringEnd(s, i);
+      if (end === -1) return -1;
+      i = end;
+      continue;
+    }
+    if (c === '{') depth += 1;
+    else if (c === '}') {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+};
+// Find `"key"` used as an object key inside region [lo, hi); returns the index
+// of its `:` or -1. A bare `"key"` inside a string value cannot produce this
+// shape (its quotes are escaped), and non-key uses lack the `:` — both are
+// skipped by scanning forward.
+const findKey = (s, key, lo, hi) => {
+  const needle = `"${key}"`;
+  let pos = s.indexOf(needle, lo);
+  while (pos !== -1 && pos < hi) {
+    const colon = skipWs(s, pos + needle.length);
+    if (colon < hi && colon < s.length && s[colon] === ':') {
+      const prev = pos - 1;
+      const pc = prev >= 0 ? s[prev] : '';
+      if (prev < 0 || pc === '{' || pc === ',' || isWs(pc)) return colon;
+    }
+    pos = s.indexOf(needle, pos + 1);
+  }
+  return -1;
+};
+
+let regionLo = 0;
+let regionHi = data.length;
+for (let k = 0; k < dotted.length; k += 1) {
+  const colon = findKey(data, dotted[k], regionLo, regionHi);
+  if (colon === -1) fail();
+  const vstart = skipWs(data, colon + 1);
+  if (vstart >= data.length) fail();
+  const last = k === dotted.length - 1;
+  const c = data[vstart];
+  if (!last) {
+    if (c !== '{') fail();
+    const close = matchBrace(data, vstart);
+    // An unclosed parent object still bounds the search to what arrived; the
+    // leaf's own boundary proof below decides completeness.
+    regionLo = vstart + 1;
+    regionHi = close === -1 ? data.length : close;
+    continue;
+  }
+  if (c !== '"') fail(); // string fields only
+  const end = scanStringEnd(data, vstart);
+  if (end === -1) fail(); // cut inside the value — never trust a partial field
+  const after = skipWs(data, end + 1);
+  if (after >= data.length) fail(); // closed quote but no boundary proof — err closed
+  const boundary = data[after];
+  if (boundary !== ',' && boundary !== '}') fail();
+  try {
+    process.stdout.write(JSON.parse(data.slice(vstart, end + 1)));
+  } catch {
+    fail();
+  }
+  process.exit(0);
+}
+fail();
+UKIT_SALVAGE_NODE
+}
+
 ukit_cleanup_hook_input() {
   # TASK-019: emit the telemetry finish marker while the staged payload file
   # still exists (its mtime is the envelope start). Strictly advisory — the

package/templates/.omp/config.yml

@@ -15,10 +15,37 @@ modelRoles:
   vision: unic-vision
 
 tools:
-  approvalMode: write
+  # TASK-009 / SPEC FR-003: the unattended approval surface is pinned HERE —
+  # `approvalMode: yolo` plus all ten `tools.approval.*: allow`. The product
+  # source of truth is `orchestration.permissionMode: unattended`
+  # (.ukit/storage/config.json, written by TASK-008); this map is its omp-side
+  # rendering so installed projects run prompt-free out of the box.
+  # This SUPERSEDES the TASK-006/C34 omission decision (approvalMode left absent
+  # so the end user's global/runtime mode won): an interactive global would
+  # silently downgrade a shipped install to prompting, contradicting the
+  # unattended contract — the project-level pin is now required, not optional.
+  # `approvalMode: yolo` VERIFIED against omp v17.4.2 (2026-08-22) — same
+  # docContracts allowlist citation as compaction.thresholdTokens below.
+  # Safety under yolo is unchanged: the bash.patterns deny set below, the
+  # TASK-004 hook-bridge deny chain, and this approval map still gate dangerous
+  # ops — `allow` removes interactive prompts, not the deny checks.
+  # Residual risk: yolo + all-allow IS dangerously autonomous and is a
+  # deliberate, user-chosen posture (unattended mode). `eval` stays `allow`
+  # (was `prompt` pre-TASK-001): bash.patterns never covers the eval tool, but
+  # the TASK-004 bridge maps `eval` -> `Bash`, so every eval call is gated by
+  # the same block-dangerous chain as a bash command.
+  approvalMode: yolo
   approval:
     bash: allow
-    eval: prompt
+    eval: allow
+    task: allow
+    read: allow
+    grep: allow
+    write: allow
+    edit: allow
+    lsp: allow
+    browser: allow
+    computer: allow
 
 bash:
   # Translated from templates/.claude/hooks/block-dangerous.sh's DANGEROUS_PATTERNS array.
@@ -27,8 +54,9 @@ bash:
   # catches it. `allow` only ever matches an ENTIRE, non-compound command, so the trailing "*"
   # allow is NOT a universal escape hatch: any compound command (`&&`, `;`, `|`) not itself caught
   # by a `deny`/`prompt` entry falls through to `tools.approvalMode` instead of being auto-allowed.
-  # `bash.patterns` does not cover the `eval` tool at all — that is why `tools.approval.eval` above
-  # is `prompt`, and why TASK-004's bridge separately maps `eval` -> `Bash`.
+  # `bash.patterns` does not cover the `eval` tool at all — that is why TASK-004's bridge
+  # separately maps `eval` -> `Bash`, and why `tools.approval.eval: allow` above does NOT
+  # weaken eval safety: eval stays gated by the bridge's Bash chain (TASK-001).
   patterns:
     - match: "rm -rf /*"
       approval: deny

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

@@ -294,10 +294,18 @@ function translateExecResult(scriptName, execResult) {
   if (code === 2) {
     const structured = parseStructuredDecision(stdout);
     if (structured?.permissionDecision === 'ask') {
+      const askBase = structured.reason || stderr || `${scriptName} requires a human decision`;
+      // omp has no native `ask` — hook() converts this to a block. A bare
+      // "defers to a human" reason dead-ended under YOLO, so the reason must
+      // name the cause class + the recovery action and the chain must surface
+      // a display:true note (done in runScriptChain) so a deliberate block is
+      // distinguishable from a stall.
       return {
         block: false,
         ask: true,
-        reason: structured.reason || stderr || `${scriptName} requires a human decision`,
+        reason: `${askBase} [UKit ask→block: omp has no native "ask", so this gate decision was surfaced as a block. `
+          + 'Recovery: if the cause was an oversized or truncated payload, shrink the payload or re-send it; '
+          + 'if the gate is asking for a decision, decide explicitly — answer the question and re-send the call.]',
         stdout,
         stderr,
       };
@@ -628,6 +636,9 @@ export async function runScriptChain(
       return { block: true, reason: verdict.reason, context, invoked };
     }
     if (verdict.ask) {
+      // The block must be user-visible, not just model-visible — a deliberate
+      // ask→block has to be distinguishable from a silent stall.
+      sendContext(pi, [`[UKit] Gate asks for a human decision — the call was blocked: ${verdict.reason}`], 'nextTurn', { display: true });
       return { block: false, ask: true, reason: verdict.reason, context, invoked };
     }
   }

package/templates/AGENTS.md

@@ -26,6 +26,14 @@
 <!-- RULE: EXEC-04 -->
 - **Every stop says why — no silent idle.** Turns ending on a user-only action open with `WAITING ON YOU: <command/action>` plus a one-shot wakeup (~20-30 min) when available — an ended turn cannot observe external changes, so without it idle looks identical to a stall. Report any error verbatim the same turn.
 
+## Stall & Wait Reporting
+<!-- RULE: STALL-01 -->
+- Announce long waits as they happen: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface any API/tool error **verbatim** in the same turn, and name network/API as the suspect on long stalls — **never blame UKit**. This guidance makes the model's side of a wait visible; it cannot detect a stall inside the host's own request loop.
+<!-- RULE: STALL-02 -->
+- Every stop still says why (Execution Contract EXEC-04) — the stall rules above extend it, they do not replace it.
+<!-- RULE: STALL-03 -->
+- **Conditional workaround only:** fall back to one tool call per assistant message ONLY when malformed/concatenated tool-input errors are observed or the harness version is known-affected — otherwise keep using legitimate parallel calls; serializing healthy hosts contradicts batching guidance.
+
 ## Long-Run Continuity
 <!-- RULES: LONG-01 LONG-02 -->
 - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest into `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Only then compact.
@@ -69,8 +77,8 @@ For any task needing code context:
 
 ## UKit v{{ukit.version}} Shared Runtime
 - Runtime state lives in `.ukit/storage/`; `.ukit/storage/config.json` holds runtime toggles (compact, token pipeline, router, memory, validation, Safe Patch).
-- Reuse `.ukit/storage/memory/` + `ukit memory recall "<current task>"` before asking users to restate decisions; inspect via `ukit status` / `ukit memory export`.
-- Route memory: `.claude/ukit/skill-router-state.json` — reuse compact `previous-context`/`recent-output` first. Cache state: `.ukit/storage/cache/output-history.json`, tee/. Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
+- Reuse `.ukit/storage/memory/` + `ukit memory recall "<current task>"` before asking users to restate decisions; `ukit memory learn` surfaces pending proposals, `ukit memory promote` writes approved rules to MEMORY.md, `ukit memory episode` records session episodes; inspect via `ukit status` / `ukit memory export`.
+- Route memory: `.claude/ukit/skill-router-state.json` — reuse compact `previous-context`/`recent-output` first. Cache state: `.ukit/storage/cache/output-history.json`, `retriever-lanes.jsonl`, `tee/`. Lifecycle hooks all degrade to exit 0 (SessionEnd `session-episode.sh` auto-writes episodes; full map: `docs/UKIT_INTERNALS.md`). Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Prompt Caching
 <!-- RULES: CTX-01 CTX-02 CTX-03 CTX-04 CTX-05 CTX-06 CTX-07 CTX-08 CTX-09 CTX-10 -->
@@ -84,9 +92,7 @@ For any task needing code context:
 
 ## Handoff Quality Gate — OPT-IN
 <!-- RULE: HAND-01 -->
-CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
-
-Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
+CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên. Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 <!-- RULE: BUDGET-01 -->
@@ -99,14 +105,10 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 - `docs/STATUS.md` captures compact current state — not source truth, never replaces source/index-first investigation.
 - "What next?"/"continue" → `next-step` with a freshness cue; after meaningful work → `update-status`. `docs/TASKS.md` is the local AI task queue — prefer `Ready for AI`. Detail: `docs/UKIT_INTERNALS.md`.
 
-## Small-Task Maintainer (internal)
+## Subagent Lanes (internal)
 <!-- RULE: SUBAG-02 -->
 - The `ukit-small-task-maintainer` subagent (`subagents.smallTaskModel`, default `unic-lite`) handles safe/reversible UKit chores as a sidecar lane — never block or slow the user task; risky work hands back to the main model. Detail: `docs/UKIT_INTERNALS.md`.
-
-## Post-Edit Sidecar Review (internal)
 - When routed state's `routeSummary.line` carries `review=code-reviewer(diff)`, launch `code-reviewer` in background (`smart` tier) **only after** write + verification evidence; findings advisory — never block the reported completion. Detail: `docs/UKIT_INTERNALS.md`.
-
-## Selective Subagent Policy (internal only)
 <!-- RULE: SUBAG-01 -->
 - Direct execution is default for trivial/simple work; delegate only on meaningful context shrink or parallel gains (noisy side lanes, 3+ independent failures, batch plans). Never ask end users to name agents or remember agent commands.
 
@@ -114,6 +116,16 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 <!-- RULE: AUTO-01 -->
 - `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more), `vibecode` (one prompt to a finished result; the gate stops only on completion evidence, a genuine blocker, or a dangerous-command decision). End users should not need to change it.
 
+## Unattended Completion Loop
+<!-- RULE: UNATTENDED-01 -->
+- Under `orchestration.permissionMode: unattended` there is no human in the loop — the loop is UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny decision.
+<!-- RULE: UNATTENDED-02 -->
+- `maxAttemptsPerFailure: 5` per failing verification, `maxRecoveryStrategies: 3` distinct fix strategies before reassessing — retry the same edit, fix the cause differently, then reduce scope/approach; do not loop one strategy.
+<!-- RULE: UNATTENDED-03 -->
+- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, and ambiguity are NOT blockers — they feed FIX.
+<!-- RULE: UNATTENDED-04 -->
+- A deny (hook/gate/permission) never becomes a question: pick the next safer alternative that satisfies the intent and record the substitution. Never emit "do you want me to…" — decide and proceed.
+
 ## 3-Tier Model Routing
 <!-- RULES: TIER-01 TIER-02 -->
 **Internal orchestration only — end users still just use natural language. No new commands.**

package/templates/CLAUDE.md

@@ -26,6 +26,14 @@
 <!-- RULE: EXEC-04 -->
 - **Every stop says why — no silent idle.** Turns ending on a user-only action open with `WAITING ON YOU: <command/action>` plus a one-shot wakeup (~20-30 min) when available — an ended turn cannot observe external changes, so without it idle looks identical to a stall. Report any error verbatim the same turn.
 
+## Stall & Wait Reporting
+<!-- RULE: STALL-01 -->
+- Announce long waits as they happen: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface any API/tool error **verbatim** in the same turn, and name network/API as the suspect on long stalls — **never blame UKit**. This guidance makes the model's side of a wait visible; it cannot detect a stall inside the host's own request loop.
+<!-- RULE: STALL-02 -->
+- Every stop still says why (Execution Contract EXEC-04) — the stall rules above extend it, they do not replace it.
+<!-- RULE: STALL-03 -->
+- **Conditional workaround only:** fall back to one tool call per assistant message ONLY when malformed/concatenated tool-input errors are observed or the harness version is known-affected — otherwise keep using legitimate parallel calls; serializing healthy hosts contradicts batching guidance.
+
 ## Long-Run Continuity
 <!-- RULES: LONG-01 LONG-02 -->
 - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest into `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Only then compact.
@@ -69,8 +77,8 @@ For any task needing code context:
 
 ## UKit v{{ukit.version}} Shared Runtime
 - Runtime state lives in `.ukit/storage/`; `.ukit/storage/config.json` holds runtime toggles (compact, token pipeline, router, memory, validation, Safe Patch).
-- Reuse `.ukit/storage/memory/` + `ukit memory recall "<current task>"` before asking users to restate decisions; inspect via `ukit status` / `ukit memory export`.
-- Route memory: `.claude/ukit/skill-router-state.json` — reuse compact `previous-context`/`recent-output` first. Cache state: `.ukit/storage/cache/output-history.json`, tee/. Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
+- Reuse `.ukit/storage/memory/` + `ukit memory recall "<current task>"` before asking users to restate decisions; `ukit memory learn` surfaces pending proposals, `ukit memory promote` writes approved rules to MEMORY.md, `ukit memory episode` records session episodes; inspect via `ukit status` / `ukit memory export`.
+- Route memory: `.claude/ukit/skill-router-state.json` — reuse compact `previous-context`/`recent-output` first. Cache state: `.ukit/storage/cache/output-history.json`, `retriever-lanes.jsonl`, `tee/`. Lifecycle hooks all degrade to exit 0 (SessionEnd `session-episode.sh` auto-writes episodes; full map: `docs/UKIT_INTERNALS.md`). Missing/corrupt runtime or old `ukit/` root → rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Prompt Caching
 <!-- RULES: CTX-01 CTX-02 CTX-03 CTX-04 CTX-05 CTX-06 CTX-07 CTX-08 CTX-09 CTX-10 -->
@@ -84,9 +92,7 @@ For any task needing code context:
 
 ## Handoff Quality Gate — OPT-IN
 <!-- RULE: HAND-01 -->
-CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
-
-Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
+CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên. Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
 <!-- RULE: BUDGET-01 -->
@@ -99,14 +105,10 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 - `docs/STATUS.md` captures compact current state — not source truth, never replaces source/index-first investigation.
 - "What next?"/"continue" → `next-step` with a freshness cue; after meaningful work → `update-status`. `docs/TASKS.md` is the local AI task queue — prefer `Ready for AI`. Detail: `docs/UKIT_INTERNALS.md`.
 
-## Small-Task Maintainer (internal)
+## Subagent Lanes (internal)
 <!-- RULE: SUBAG-02 -->
 - The `ukit-small-task-maintainer` subagent (`subagents.smallTaskModel`, default `unic-lite`) handles safe/reversible UKit chores as a sidecar lane — never block or slow the user task; risky work hands back to the main model. Detail: `docs/UKIT_INTERNALS.md`.
-
-## Post-Edit Sidecar Review (internal)
 - When routed state's `routeSummary.line` carries `review=code-reviewer(diff)`, launch `code-reviewer` in background (`smart` tier) **only after** write + verification evidence; findings advisory — never block the reported completion. Detail: `docs/UKIT_INTERNALS.md`.
-
-## Selective Subagent Policy (internal only)
 <!-- RULE: SUBAG-01 -->
 - Direct execution is default for trivial/simple work; delegate only on meaningful context shrink or parallel gains (noisy side lanes, 3+ independent failures, batch plans). Never ask end users to name agents or remember agent commands.
 
@@ -114,6 +116,16 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 <!-- RULE: AUTO-01 -->
 - `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more), `vibecode` (one prompt to a finished result; the gate stops only on completion evidence, a genuine blocker, or a dangerous-command decision). End users should not need to change it.
 
+## Unattended Completion Loop
+<!-- RULE: UNATTENDED-01 -->
+- Under `orchestration.permissionMode: unattended` there is no human in the loop — the loop is UNDERSTAND → PLAN → IMPLEMENT → VERIFY → FIX → REVERIFY → COMPLETE. A turn ends only on COMPLETE evidence, a real external blocker, or a deny decision.
+<!-- RULE: UNATTENDED-02 -->
+- `maxAttemptsPerFailure: 5` per failing verification, `maxRecoveryStrategies: 3` distinct fix strategies before reassessing — retry the same edit, fix the cause differently, then reduce scope/approach; do not loop one strategy.
+<!-- RULE: UNATTENDED-03 -->
+- BLOCKED only on true external blockers: missing credentials, dead service, unreachable network/API. Test failures, lint errors, review findings, and ambiguity are NOT blockers — they feed FIX.
+<!-- RULE: UNATTENDED-04 -->
+- A deny (hook/gate/permission) never becomes a question: pick the next safer alternative that satisfies the intent and record the substitution. Never emit "do you want me to…" — decide and proceed.
+
 ## 3-Tier Model Routing
 <!-- RULES: TIER-01 TIER-02 -->
 **Internal orchestration only — end users still just use natural language. No new commands.**