@ngockhoale/ukit 2.2.16 → 2.3.1

package/templates/.claude/ukit/index/extract-image.mjs

@@ -6,9 +6,10 @@
  * blocks, so pasted images are invisible unless this script first decodes them
  * to disk. This is the single home of the sha256 key: `pending-<sha>` markers
  * (written by --mark-pending) and `<sha>.<ext>` image files (written by a normal
- * extract) MUST agree exactly, or the TASK-008 gate deadlocks forever. Both
- * paths call the same hashPayload() function on the exact base64 string as it
- * appears in the transcript — no trimming, no normalising, no decoding first.
+ * extract) MUST agree exactly, or analysis receipts can never be matched back to
+ * their markers. Both paths call the same hashPayload() function on the exact
+ * base64 string as it appears in the transcript — no trimming, no normalising,
+ * no decoding first.
  *
  * Usage:
  *   node extract-image.mjs [options]
@@ -323,14 +324,23 @@ function main() {
   // A sha with an existing analyzed-<sha>.json receipt is a closed, content-addressed case:
   // identical bytes already produced that analysis, so skipping it loses no information.
   const isAlreadyAnalyzed = (sha) => fs.existsSync(path.join(markerDir, `analyzed-${sha}.json`));
-  const selected = selectImages(blocks, opts.limit).filter((img) => !isAlreadyAnalyzed(img.sha));
-  const refs = resolveRefs(opts.refs).filter((ref) => !isAlreadyAnalyzed(ref.sha));
+  const allSelected = selectImages(blocks, opts.limit);
+  const allRefs = resolveRefs(opts.refs);
+  const selected = allSelected.filter((img) => !isAlreadyAnalyzed(img.sha));
+  const refs = allRefs.filter((ref) => !isAlreadyAnalyzed(ref.sha));
+  // Closed cases reported back so callers (vision-router.sh) can stay silent on them:
+  // a sha with an analyzed-<sha>.json receipt needs no new dispatch, and without this
+  // list the caller cannot tell "already analyzed" from "never resolved".
+  const alreadyAnalyzed = [
+    ...allSelected.filter((img) => isAlreadyAnalyzed(img.sha)).map((img) => ({ sha: img.sha, source: 'pasted' })),
+    ...allRefs.filter((ref) => isAlreadyAnalyzed(ref.sha)).map((ref) => ({ sha: ref.sha, source: ref.source, ref: ref.value })),
+  ];
 
   // --detect is report-only, so it must not short-circuit --mark-pending when both are
   // passed together. vision-router.sh combines them; short-circuiting here would arm
-  // nothing and leave the TASK-008 write gate permanently open.
+  // nothing and leave every image unmarked.
   if (opts.detect && !opts.markPending) {
-    printResult(opts, { imageCount: selected.length + refs.length, sessionId, images: [] });
+    printResult(opts, { imageCount: selected.length + refs.length, sessionId, images: [], alreadyAnalyzed });
     return;
   }
 
@@ -374,7 +384,7 @@ function main() {
       }
     }
     pruneMarkerDirs(outDir);
-    printResult(opts, { imageCount: written.length, sessionId, images: written });
+    printResult(opts, { imageCount: written.length, sessionId, images: written, alreadyAnalyzed });
     return;
   }
 

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

@@ -579,6 +579,9 @@ function printRouteState(state) {
   if (state.routeSummary?.executionContract?.modelTier) {
     console.log(`modelTier: ${state.routeSummary.executionContract.modelTier}`);
   }
+  if (state.routeSummary?.tierLane?.instruction) {
+    console.log(`tierLane: ${state.routeSummary.tierLane.instruction}`);
+  }
   if (state.routeSummary?.escalatedTier) {
     console.log(`escalatedTier: ${state.routeSummary.escalatedTier}`);
     if (state.routeSummary.escalationReason) {
@@ -1475,6 +1478,15 @@ function buildRouteSummary({
   const primaryTargets = summarizeCompactList(preview.primaryTargets ?? [], 2);
   const relatedTests = summarizeCompactList(preview.relatedTests ?? [], 2);
   const styleFiles = summarizeCompactList(preview.styleFiles ?? [], 1);
+  // WS-C target-aware evidence: the completion ledger checks impact-evidence against these
+  // files, so carry the full resolver list (target + primaryTargets + relatedTests), bounded
+  // for compact route state. Absent when the route has no indexed context — the ledger then
+  // falls back to its legacy any-read behaviour.
+  const expectedSourceFiles = unique([
+    ...(routingContext.targetFile ? [routingContext.targetFile] : []),
+    ...(preview.primaryTargets ?? []),
+    ...(preview.relatedTests ?? []),
+  ].filter((filePath) => typeof filePath === 'string' && filePath.trim())).slice(0, 8);
   const primaryCommands = unique(verificationRecommendation?.commands ?? []);
   const fallbackCommands = unique(verificationRecommendation?.fallbackCommands ?? []);
   const preferredOrder = unique(
@@ -1497,6 +1509,7 @@ function buildRouteSummary({
     executionCandidates,
   });
   const executionContract = buildExecutionContract(executionMode);
+  const tierLane = buildTierLane({ modelTier: executionContract?.modelTier ?? null });
   const completionState = buildCompletionState({
     executionMode,
     verificationRecommendation,
@@ -1539,8 +1552,10 @@ function buildRouteSummary({
     executionCandidates,
     approachSelector,
     executionContract,
+    tierLane,
     completionState,
     continuationState,
+    ...(expectedSourceFiles.length > 0 ? { expectedSourceFiles } : {}),
     intentMode: routingContext.intentMode ?? null,
     handoffFile,
     delegateHint: delegationRecommendation?.hint ?? null,
@@ -1894,9 +1909,10 @@ function buildExecutionContract(executionMode = null) {
       maxReadPasses: 2,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
-      completionRule: 'require-write',
+      completionRule: 'require-write-and-verification',
       delegationPolicy: 'disallow-by-default',
-      completionEvidence: ['write-evidence'],
+      completionEvidence: ['write-evidence', 'verification-evidence'],
+      postEditReviewPolicy: 'sidecar-non-blocking',
     },
     'find-cause': {
       modelTier: 'code',
@@ -1915,6 +1931,7 @@ function buildExecutionContract(executionMode = null) {
       delegationPolicy: 'allow-qualified-sidecar',
       completionEvidence: ['write-evidence', 'verification-evidence'],
       mirrorConsistencyRequired: true,
+      postEditReviewPolicy: 'sidecar-non-blocking',
     },
     'map-impact': {
       modelTier: 'code',
@@ -2182,10 +2199,36 @@ function applyEscalationToRouteSummary(routeSummary = null, { config = null, tar
     delete routeSummary.escalatedTier;
     delete routeSummary.escalationReason;
   }
+  // Recomputed here (not only in buildRouteSummary) so the lane always reflects the final
+  // tier after escalation, on every path that emits a route summary.
+  routeSummary.tierLane = buildTierLane({
+    modelTier: routeSummary.executionContract?.modelTier ?? null,
+    escalatedTier: escalation?.escalatedTier ?? null,
+  });
 
   return routeSummary;
 }
 
+// WS-E tier-role wiring: a contract tier only takes effect when the executing session hands
+// the work to an agent whose definition binds that tier — otherwise every session behaves as
+// if it only had one model. `code` is the DEFAULT implementation lane, so a code-tier contract
+// produces no instruction (inline execution on a code session is already correct, and silence
+// keeps the hook flow smooth). Labels are stable tier roles (lite/code/smart), never provider
+// or model identity. Vision never appears here — it is a capability lane, not a cost tier.
+function buildTierLane({ modelTier = null, escalatedTier = null } = {}) {
+  const tier = escalatedTier ?? modelTier;
+  if (!tier || tier === 'vision') {
+    return null;
+  }
+  return {
+    tier,
+    defaultLane: tier === 'code',
+    instruction: tier === 'code'
+      ? null
+      : `Hand this task to an agent bound to the ${tier} tier instead of doing it inline, unless this session already runs on the ${tier} tier.`,
+  };
+}
+
 function advanceContinuationState(continuationState = null, previousContinuationState = null, thresholds = null) {
   if (!continuationState || typeof continuationState !== 'object') {
     return continuationState;
@@ -2875,6 +2918,14 @@ function compactRouteSummary(routeSummary = null) {
     completionState: routeSummary.completionState ?? null,
     continuationState: routeSummary.continuationState ?? null,
     delegateHint: routeSummary.delegateHint ?? null,
+    // WS-E tier-role binding: consumers need the hand-off instruction, not just the raw tier.
+    ...(routeSummary.tierLane ? { tierLane: routeSummary.tierLane } : {}),
+    // WS-C target-aware evidence: the completion ledger reads these from the PERSISTED route
+    // state — without this spread the CLI path never delivers them and the gate falls back
+    // to legacy any-read behaviour.
+    ...(Array.isArray(routeSummary.expectedSourceFiles) && routeSummary.expectedSourceFiles.length > 0 ? {
+      expectedSourceFiles: routeSummary.expectedSourceFiles,
+    } : {}),
     nextActionType: routeSummary.nextActionType ?? null,
     nextActionCommand: routeSummary.nextActionCommand ?? null,
     helperHint: routeSummary.helperHint ?? null,

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 const LEDGER_VERSION = 1;
 const MAX_RECEIPTS = 24;
+const MAX_SOURCE_FILES = 16;
 const MAX_CONTINUATIONS = 6;
 const IMPLEMENT_MODES = new Set([
   'tiny-fix',
@@ -130,7 +131,7 @@ function compactReceipt(receipt) {
     kind: receipt.kind,
     success: receipt.success,
   };
-  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'error']) {
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error']) {
     if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
       compact[key] = receipt[key];
     }
@@ -138,10 +139,81 @@ function compactReceipt(receipt) {
   return compact;
 }
 
+/**
+ * Target-aware matching between a receipt's file and a routed expected file. Both sides
+ * may disagree about absolute vs relative spelling (hook payloads carry absolute paths,
+ * the router carries repo-relative ones), so exact equality, path-suffix, and bare-name
+ * matches all count.
+ */
+function fileMatchesExpected(receiptFile, expectedFile) {
+  if (!receiptFile || !expectedFile) return false;
+  const receipt = String(receiptFile).replace(/\\/g, '/').replace(/^\.\//, '');
+  const expected = String(expectedFile).replace(/\\/g, '/').replace(/^\.\//, '');
+  if (receipt === expected) return true;
+  if (receipt.endsWith(`/${expected}`) || expected.endsWith(`/${receipt}`)) return true;
+  if (!expected.includes('/')) {
+    const base = receipt.split('/').pop();
+    return base === expected;
+  }
+  return false;
+}
+
+function matchesRoutedCommand(command, routedCommand) {
+  const receipt = String(command || '').trim();
+  const routed = String(routedCommand || '').trim();
+  if (!receipt || !routed) return false;
+  return receipt === routed || receipt.startsWith(routed) || routed.startsWith(receipt);
+}
+
+function routedVerificationCommands(routeSummary = {}) {
+  const preferred = Array.isArray(routeSummary?.preferredOrder) ? routeSummary.preferredOrder : [];
+  const primary = Array.isArray(routeSummary?.primaryCommands) ? routeSummary.primaryCommands : [];
+  return preferred.length > 0 ? preferred : primary;
+}
+
 function appendReceipt(receipts, receipt) {
   return [...(receipts || []), compactReceipt(receipt)].slice(-MAX_RECEIPTS);
 }
 
+// A re-key within the same logical request must not drop the evidence the request
+// already produced — that turned one finished task into a cap-exhausted forced stop.
+// A genuinely different prompt keeps a clean slate so old work never satisfies a new
+// request's completion gate.
+function carriedEvidenceLedger(fresh, current) {
+  if (!current || !fresh.promptKey || !current.promptKey || current.promptKey !== fresh.promptKey) {
+    return fresh;
+  }
+  return {
+    ...fresh,
+    sourceSucceeded: fresh.sourceSucceeded || current.sourceSucceeded === true,
+    // targeted-verification evidence (2.3.0) must survive the same re-key carry as the
+    // coarse flags, or the stricter gates re-demand evidence mid-request — the exact
+    // stall this carry exists to prevent.
+    targetedVerificationSucceeded: fresh.targetedVerificationSucceeded
+      || current.targetedVerificationSucceeded === true,
+    sourceFiles: [...new Set([...(current.sourceFiles || []), ...(fresh.sourceFiles || [])])]
+      .slice(-MAX_SOURCE_FILES),
+    writeAttempted: fresh.writeAttempted || current.writeAttempted === true,
+    writeSucceeded: fresh.writeSucceeded || current.writeSucceeded === true,
+    verificationAttempted: fresh.verificationAttempted || current.verificationAttempted === true,
+    verificationSucceeded: fresh.verificationSucceeded || current.verificationSucceeded === true,
+    verificationFailed: fresh.verificationFailed || current.verificationFailed === true,
+    receipts: [...(current.receipts || [])].slice(-MAX_RECEIPTS),
+  };
+}
+
+// The router rebuilds requestKey per tool call (commandText/targetFile are part of the
+// key), so requestKey changes mid-request on every verification command — and a subagent's
+// Edit can additionally re-classify executionMode/taskType for the same user prompt. The
+// logical request identity is therefore the prompt text alone: hash it so completion
+// evidence survives any re-key/re-route within one request without leaking across requests.
+// States with no recorded prompt text get no identity and never carry evidence.
+function evidencePromptKey(routeState) {
+  const promptText = String(routeState?.routingContext?.lastExplicitUserPromptText || '').trim();
+  if (!promptText) return null;
+  return `prompt-${crypto.createHash('sha256').update(promptText).digest('hex').slice(0, 20)}`;
+}
+
 function freshLedger(payload, routeState, harness) {
   return {
     version: LEDGER_VERSION,
@@ -150,8 +222,10 @@ function freshLedger(payload, routeState, harness) {
     transcriptPath: payload.transcript_path || payload.transcriptPath || null,
     harness,
     requestKey: routeState?.requestKey || null,
+    promptKey: evidencePromptKey(routeState),
     routeFingerprint: routeState?.fingerprint || null,
     sourceSucceeded: false,
+    sourceFiles: [],
     writeAttempted: false,
     writeSucceeded: false,
     verificationAttempted: false,
@@ -175,7 +249,7 @@ export async function recordExecutionReceipt({
   const routeState = await readRouteState(projectRoot);
   const current = await readExecutionLedger(projectRoot, payload);
   const ledger = !current || current.requestKey !== (routeState?.requestKey || null)
-    ? freshLedger(payload, routeState, harness)
+    ? carriedEvidenceLedger(freshLedger(payload, routeState, harness), current)
     : { ...current, harness: current.harness || harness };
 
   const failed = explicitError(payload);
@@ -194,6 +268,9 @@ export async function recordExecutionReceipt({
     receipt.kind = 'source';
     receipt.file = toolInput.file_path || toolInput.path || null;
     ledger.sourceSucceeded ||= success;
+    if (success && receipt.file) {
+      ledger.sourceFiles = [...new Set([...(ledger.sourceFiles || []), receipt.file])].slice(-MAX_SOURCE_FILES);
+    }
   } else if (toolName === 'Edit' || toolName === 'Write') {
     receipt.kind = 'write';
     receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
@@ -202,6 +279,17 @@ export async function recordExecutionReceipt({
   } else if (toolName === 'Bash' && isVerificationCommand(toolInput.command)) {
     receipt.kind = 'verification';
     receipt.command = String(toolInput.command || '').trim();
+    // WS-C routed-verification receipt: a command counts as "targeted" when it matches the
+    // routed plan (preferredOrder / primaryCommands). Off-plan verification still records
+    // as broad — counted only when the route carried no commands at all.
+    const routedCommands = routedVerificationCommands(routeState?.routeSummary);
+    if (routedCommands.length > 0) {
+      const matched = routedCommands.find((cmd) => matchesRoutedCommand(receipt.command, cmd));
+      receipt.scope = matched ? 'targeted' : 'broad';
+      if (receipt.scope === 'targeted') {
+        ledger.targetedVerificationSucceeded ||= success;
+      }
+    }
     ledger.verificationAttempted = true;
     ledger.verificationSucceeded ||= success;
     ledger.verificationFailed ||= !success;
@@ -224,30 +312,66 @@ function requiredEvidence(state = {}) {
   return [...new Set(routeSummary.completionState?.missingEvidence || [])];
 }
 
-function evidenceSatisfied(evidence, ledger = {}) {
+function evidenceSatisfied(evidence, ledger = {}, routeSummary = {}) {
   if (evidence === 'write-evidence') return ledger.writeSucceeded === true;
-  if (evidence === 'verification-evidence') return ledger.verificationSucceeded === true;
-  if (evidence === 'impact-evidence') return ledger.sourceSucceeded === true;
+  if (evidence === 'verification-evidence') {
+    // WS-C: when the route names concrete verification commands, only a receipt that ran
+    // one of them counts — an unrelated `yarn test` no longer satisfies the gate.
+    const routedCommands = routedVerificationCommands(routeSummary);
+    if (routedCommands.length > 0) {
+      return ledger.targetedVerificationSucceeded === true;
+    }
+    return ledger.verificationSucceeded === true;
+  }
+  if (evidence === 'impact-evidence') {
+    // WS-C: when the route names expected source files, a read must cover one of them —
+    // ANY read (e.g. docs) no longer satisfies the impact-evidence gate.
+    const expectedFiles = Array.isArray(routeSummary?.expectedSourceFiles)
+      ? routeSummary.expectedSourceFiles
+      : [];
+    if (expectedFiles.length > 0) {
+      const readFiles = Array.isArray(ledger.sourceFiles) ? ledger.sourceFiles : [];
+      return readFiles.some((file) => expectedFiles.some((expected) => fileMatchesExpected(file, expected)));
+    }
+    return ledger.sourceSucceeded === true;
+  }
   return false;
 }
 
-function recoveryInstruction(missingEvidence, ledger = {}) {
+function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}) {
+  let instruction = null;
   if (missingEvidence.includes('write-evidence')) {
     if (!ledger.sourceSucceeded) {
-      return 'Pull one bounded indexed source slice, then make the requested Edit/Write in this continuation.';
+      instruction = 'Pull one bounded indexed source slice, then make the requested Edit/Write in this continuation.';
+    } else if (ledger.writeAttempted && !ledger.writeSucceeded) {
+      instruction = 'Recover from the failed mutation using the current error, then retry the smallest correct Edit/Write.';
+    } else {
+      instruction = 'Make the smallest correct Edit/Write now; do not end after more read-only analysis.';
     }
-    if (ledger.writeAttempted && !ledger.writeSucceeded) {
-      return 'Recover from the failed mutation using the current error, then retry the smallest correct Edit/Write.';
+  } else if (missingEvidence.includes('verification-evidence')) {
+    if (ledger.verificationFailed) {
+      instruction = 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
+    } else {
+      const routedCommands = routedVerificationCommands(routeSummary);
+      if (routedCommands.length > 0 && ledger.verificationSucceeded && !ledger.targetedVerificationSucceeded) {
+        instruction = `Verification ran but did not match the routed plan (${routedCommands.slice(0, 3).join('; ')}). Run one of those and inspect its result before stopping.`;
+      } else {
+        instruction = 'Run the routed targeted verification now and inspect its result before stopping.';
+      }
     }
-    return 'Make the smallest correct Edit/Write now; do not end after more read-only analysis.';
   }
-  if (missingEvidence.includes('verification-evidence')) {
-    if (ledger.verificationFailed) {
-      return 'Use the latest failed verification output, fix the failure, and rerun targeted verification.';
+  // WS-C: the target hint travels with the reason whenever impact evidence is missing and
+  // the route names expected files — it must survive branch precedence above.
+  if (missingEvidence.includes('impact-evidence')) {
+    const expectedFiles = Array.isArray(routeSummary?.expectedSourceFiles) ? routeSummary.expectedSourceFiles : [];
+    if (expectedFiles.length > 0 && !expectedFiles.some(
+      (expected) => (ledger.sourceFiles || []).some((file) => fileMatchesExpected(file, expected))
+    )) {
+      const hint = `Read the routed target files (${expectedFiles.slice(0, 3).join(', ')}) — reads of unrelated files do not count as impact evidence.`;
+      instruction = instruction ? `${instruction} ${hint}` : hint;
     }
-    return 'Run the routed targeted verification now and inspect its result before stopping.';
   }
-  return 'Complete the current routed milestone before stopping.';
+  return instruction ?? 'Complete the current routed milestone before stopping.';
 }
 
 export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
@@ -263,7 +387,7 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
 
   const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
   const effectiveLedger = sameRequest ? ledger : {};
-  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger));
+  const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger, routeSummary));
   if (missingEvidence.length === 0) {
     return { continue: false, notify: false, missingEvidence: [] };
   }
@@ -278,7 +402,15 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     };
   }
 
-  const continuationCount = Number(effectiveLedger?.continuationCount || 0);
+  // Continuation attempts only make sense within the request that minted them: a new
+  // routed request in the same session must start with a fresh budget, otherwise a cap
+  // exhausted on task A suppresses recovery for task B.
+  const staleContinuations = effectiveLedger?.continuationRequestKey
+    && state?.requestKey
+    && effectiveLedger.continuationRequestKey !== state.requestKey;
+  const continuationCount = staleContinuations
+    ? 0
+    : Number(effectiveLedger?.continuationCount || 0);
   if (continuationCount >= MAX_CONTINUATIONS) {
     if (effectiveLedger?.notified === true) {
       return {
@@ -300,7 +432,7 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   }
 
   const finalAttempt = continuationCount === MAX_CONTINUATIONS - 1;
-  const instruction = recoveryInstruction(missingEvidence, effectiveLedger);
+  const instruction = recoveryInstruction(missingEvidence, effectiveLedger, routeSummary);
   return {
     continue: true,
     missingEvidence,
@@ -312,11 +444,18 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   };
 }
 
-export async function incrementContinuation(projectRoot, payload = {}, ledger = null) {
+export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null) {
   const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
+  // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
+  // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
+  // persist says 7) and the next request inherits a nearly exhausted budget.
+  const stale = requestKey
+    && current?.continuationRequestKey
+    && current.continuationRequestKey !== requestKey;
   const next = {
     ...current,
-    continuationCount: Number(current.continuationCount || 0) + 1,
+    continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
+    ...(requestKey ? { continuationRequestKey: requestKey } : {}),
     lastContinuationAt: Date.now(),
     updatedAt: Date.now(),
   };
@@ -354,12 +493,31 @@ async function main() {
     const state = await readRouteState(projectRoot);
     const ledger = await readExecutionLedger(projectRoot, payload) || {};
     const result = evaluateCompletion({ state, ledger });
+
+    // Claude Code invokes Stop again after a Stop hook blocks the first stop. Re-blocking
+    // that recovery turn creates a self-sustaining loop, so let it end normally instead.
+    // If work still lacks evidence, surface the recovery reason to the user rather than
+    // silently ending after the automatic continuation.
+    if (payload.stop_hook_active === true) {
+      if (result.continue || result.capped || result.notify) {
+        const recoveryReason = result.reason
+          || 'UKit completion gate reached its continuation limit; unfinished work was not retried again.';
+        process.stdout.write(`${JSON.stringify({
+          systemMessage: `UKit stopped automatic recovery after one continuation: ${recoveryReason}`,
+        })}\n`);
+      }
+      return;
+    }
+
     if (result.continue) {
       if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
-      else await incrementContinuation(projectRoot, payload, ledger);
+      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null);
       process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
-    } else if (result.capped) {
+    } else if (result.capped || result.notify) {
+      // Non-blocking endings (non-gated modes, or cap reached after the final notice) must
+      // still tell the user what is unfinished — a silent end is indistinguishable from a stall.
       process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+      process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
     }
   }
 }

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

@@ -38,7 +38,11 @@ function run(payloadText, scriptPaths) {
     ? path.resolve(path.dirname(firstScript), '../..')
     : (payload.cwd || process.cwd());
   const startedAt = Date.now();
-  const deadline = startedAt + TOTAL_BUDGET_MS;
+  // The chain budget must always be able to run EVERY child at its full per-child
+  // budget — a fixed total silently starves later scripts once a chain grows
+  // (UserPromptSubmit now carries 4 hooks). The floor keeps short chains at 10s.
+  const totalBudgetMs = Math.max(TOTAL_BUDGET_MS, scriptPaths.length * CHILD_BUDGET_MS);
+  const deadline = startedAt + totalBudgetMs;
   const results = [];
 
   for (const scriptPath of scriptPaths) {
@@ -49,7 +53,7 @@ function run(payloadText, scriptPaths) {
         scriptName,
         code: 1,
         stdout: '',
-        stderr: `hook chain exceeded its ${TOTAL_BUDGET_MS}ms total budget`,
+        stderr: `hook chain exceeded its ${totalBudgetMs}ms total budget`,
         killed: true,
         elapsedMs: 0,
       });
@@ -89,7 +93,7 @@ function run(payloadText, scriptPaths) {
     toolName: payload?.tool_name || null,
     toolUseId: payload?.tool_use_id || null,
     elapsedMs,
-    budgetMs: TOTAL_BUDGET_MS,
+    budgetMs: totalBudgetMs,
     scripts: results.map(({ scriptName, code, killed, elapsedMs: scriptElapsedMs }) => ({
       scriptName,
       code,
@@ -98,7 +102,7 @@ function run(payloadText, scriptPaths) {
     })),
   });
 
-  return { results, elapsedMs, budgetMs: TOTAL_BUDGET_MS };
+  return { results, elapsedMs, budgetMs: totalBudgetMs };
 }
 
 try {

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

@@ -20,7 +20,7 @@ import {
 
 export const HOOK_EVENT_MAP = {
   tool_call: {
-    'Read|Grep|Glob': [],
+    'Read|Grep|Glob': ['sensitive-data-guard.sh'],
     'Edit|Write': [
       'protect-files.sh',
       'stale-spec-guard.sh',
@@ -32,6 +32,7 @@ export const HOOK_EVENT_MAP = {
     Bash: [
       'auto-allow-bash.sh',
       'block-dangerous.sh',
+      'sensitive-data-guard.sh',
       'handoff-model-guard.sh',
       'context-hardcap-gate.sh',
     ],
@@ -41,7 +42,7 @@ export const HOOK_EVENT_MAP = {
     'Edit|Write': ['post-edit-verify.sh', 'record-execution.sh'],
     Bash: ['compress-output.sh', 'record-execution.sh'],
   },
-  before_agent_start: ['skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
+  before_agent_start: ['sensitive-data-guard.sh', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
   session_start: ['auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh'],
 };
@@ -84,6 +85,7 @@ export const FAIL_CLOSED_SCRIPTS = new Set([
   'handoff-model-guard.sh',
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
+  'sensitive-data-guard.sh',
 ]);
 
 export const ADVISORY_SCRIPTS = new Set([
@@ -168,7 +170,15 @@ function translateExecResult(scriptName, execResult) {
 
 export { translateExecResult };
 
-const HOOK_CHAIN_TIMEOUT_MS = 12000;
+// Mirrors hook-chain-runner.mjs's TOTAL/CHILD budget constants: the exec timeout must
+// exceed the runner's own chain budget (max(10s, scripts×4s)) plus parse margin, or the
+// bridge orphans the runner mid-chain once a chain grows past 2 scripts.
+const HOOK_CHAIN_BASE_BUDGET_MS = 10000;
+const HOOK_CHAIN_CHILD_BUDGET_MS = 4000;
+function chainExecTimeoutMs(scriptCount) {
+  const budget = Math.max(HOOK_CHAIN_BASE_BUDGET_MS, scriptCount * HOOK_CHAIN_CHILD_BUDGET_MS);
+  return Math.min(30000, budget + 2000);
+}
 
 function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
   try {
@@ -226,7 +236,7 @@ export async function runScriptChain(
     execResult = await pi.exec(
       nodeExecutable,
       [runnerPath, JSON.stringify(payload), ...scriptPaths],
-      { cwd: projectRoot, timeout: HOOK_CHAIN_TIMEOUT_MS },
+      { cwd: projectRoot, timeout: chainExecTimeoutMs(scripts.length) },
     );
   } catch (error) {
     execResult = { code: 1, stdout: '', stderr: error?.message ?? String(error), killed: false };
@@ -515,7 +525,7 @@ export async function runSessionStop(
   if (suppliedLedger === undefined) {
     try {
       if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger);
-      else await incrementContinuation(projectRoot, payload, ledger);
+      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null);
     } catch (error) {
       pi.logger?.warn?.(`[UKit] continuation bookkeeping failed open: ${error?.message || error}`);
     }

package/templates/AGENTS.md

@@ -206,10 +206,10 @@ This is internal orchestration — end users do not need to know about tiers, th
 
 ### Vision lane (capability, not a cost tier)
 
-`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
+`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. Whether a mapping can read images is a capability fact, not a provider fact: a mapping that has not **verified** native vision must never guess at image contents — choose native-first when verified, otherwise route to the specialist.
 
 - **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
-- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on the vision lane before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
+- **Advisory routing (no hard block)**: when an image reaches the prompt, the vision router reminds the session to have `ukit-vision-analyst` analyse it before relying on its contents. Edits are **never blocked** — correctness relies on the model routing images to the analyst instead of guessing.
 - This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
 
 ## Session Start — OpenCode

package/templates/CLAUDE.md

@@ -206,7 +206,7 @@ This is internal orchestration — end users do not need to know about tiers, th
 
 ### Vision lane (capability, not a cost tier)
 
-`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
+`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. Whether a mapping can read images is a capability fact, not a provider fact: a mapping that has not **verified** native vision must never guess at image contents — choose native-first when verified, otherwise route to the specialist.
 
 - **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
 - **Advisory routing (no hard block)**: when an image reaches the prompt, the vision router reminds the session to have `ukit-vision-analyst` analyse it before relying on its contents. Edits are **never blocked** — correctness relies on the model routing images to the analyst instead of guessing.