@ngockhoale/ukit 2.2.16 → 2.3.1

package/templates/.claude/hooks/context-window-guard.sh

@@ -131,24 +131,14 @@ const estimatedTokens = Math.round(contentChars / CHARS_PER_TOKEN);
 const hardCap = loadHardCap();
 const ratio = estimatedTokens / hardCap;
 
-if (ratio < 0.8) process.exit(0);
-
-const pct = Math.round(ratio * 100);
-const phase = ratio >= 1 ? 'hard' : 'soft';
-
-// Debounce the directive block so it does not re-print in full every single prompt
-// while the phase is unchanged — that would just be more tokens added to the same
-// oversized context it is warning about. Re-arms on phase change (soft -> hard) or
-// after the cooldown, and resets naturally once a real compaction/new session drops
-// the live transcript back under 0.8, since this whole branch exits early above.
+// Debounce/state file shared by the context warning and the gateway model-swap note.
 const GUARD_STATE_PATH = path.join(projectRoot, '.ukit', 'storage', 'cache', 'context-guard-state.json');
-const COOLDOWN_MS = phase === 'hard' ? 3 * 60 * 1000 : 8 * 60 * 1000;
 
 function readGuardState() {
   try {
     return JSON.parse(fs.readFileSync(GUARD_STATE_PATH, 'utf8'));
   } catch {
-    return { lastPhase: null, lastActionAt: 0 };
+    return { lastPhase: null, lastActionAt: 0, lastSwapModel: null, lastSwapNoteAt: 0 };
   }
 }
 
@@ -160,6 +150,68 @@ function writeGuardState(state) {
 }
 
 const guardState = readGuardState();
+let persistedState = { ...guardState };
+
+// ── Gateway model-swap note ──
+// Assistant entries carry the REAL model that served them, so a swapping gateway
+// (the backend alias resolves to a different vendor model, e.g. on limit) is directly
+// visible here. Swapping is ROUTINE on such gateways, not an incident: a swap can
+// look like a short stall (cold prompt cache re-reads the context once) and providers
+// expose slightly different tools. So this is ONE line, cooldown-bounded — never a
+// per-swap directive block — telling the session the only two things that matter:
+// keep working through swaps, and on a tool error after a swap, re-check the tool and
+// call it again instead of stopping. Runs before the ratio early-exit because a swap
+// can happen at any context level.
+const RECENT_MODEL_WINDOW = 40;
+const SWAP_NOTE_COOLDOWN_MS = 60 * 60 * 1000;
+const modelSequence = [];
+for (let i = start; i < lines.length; i += 1) {
+  let entry;
+  try {
+    entry = JSON.parse(lines[i]);
+  } catch {
+    continue;
+  }
+  if (entry?.isSidechain || entry?.type !== 'assistant') continue;
+  const model = entry?.message?.model;
+  if (typeof model === 'string' && model.trim()) modelSequence.push(model.trim());
+}
+const recentModels = modelSequence.slice(-RECENT_MODEL_WINDOW);
+const currentModel = recentModels[recentModels.length - 1] || null;
+let previousModel = null;
+for (let i = recentModels.length - 2; i >= 0; i -= 1) {
+  if (recentModels[i] !== currentModel) {
+    previousModel = recentModels[i];
+    break;
+  }
+}
+const swapDetected = Boolean(currentModel && previousModel);
+if (swapDetected && persistedState.lastSwapModel !== currentModel) {
+  persistedState.lastSwapModel = currentModel;
+  const withinSwapCooldown = (Date.now() - Number(persistedState.lastSwapNoteAt || 0)) < SWAP_NOTE_COOLDOWN_MS;
+  if (!withinSwapCooldown) {
+    persistedState.lastSwapNoteAt = Date.now();
+    writeGuardState(persistedState);
+    process.stdout.write(
+      `UKIT GATEWAY — routine backend model swap ("${currentModel}" after "${previousModel}"): keep working, do not restart or re-plan; if a tool call errors after a swap, re-check the tool (providers differ) and simply call it again — never stop over it.\n`,
+    );
+  } else {
+    writeGuardState(persistedState);
+  }
+}
+
+if (ratio < 0.8) process.exit(0);
+
+const pct = Math.round(ratio * 100);
+const phase = ratio >= 1 ? 'hard' : 'soft';
+
+// Debounce the directive block so it does not re-print in full every single prompt
+// while the phase is unchanged — that would just be more tokens added to the same
+// oversized context it is warning about. Re-arms on phase change (soft -> hard) or
+// after the cooldown, and resets naturally once a real compaction/new session drops
+// the live transcript back under 0.8, since this whole branch exits early above.
+const COOLDOWN_MS = phase === 'hard' ? 3 * 60 * 1000 : 8 * 60 * 1000;
+
 const now = Date.now();
 const withinCooldown = guardState.lastPhase === phase
   && (now - Number(guardState.lastActionAt || 0)) < COOLDOWN_MS;
@@ -206,7 +258,7 @@ if (withinCooldown) {
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Keep concurrency at or below handoff.maxParallelAgents and keep returns short; do not widen the batch while this warning stands.`);
   }
-  writeGuardState({ lastPhase: phase, lastActionAt: now });
+  writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 } else {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
   lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
@@ -215,7 +267,7 @@ if (withinCooldown) {
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);
   }
-  writeGuardState({ lastPhase: phase, lastActionAt: now });
+  writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 }
 
 process.stdout.write(`${lines_out.join('\n')}\n`);

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

@@ -25,6 +25,7 @@ PROTECTED_PATTERNS=(
   ".git/"
   "node_modules/"
   ".claude/settings.local.json"
+  ".ukit/storage/security/"
 )
 
 for pattern in "${PROTECTED_PATTERNS[@]}"; do

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

@@ -0,0 +1,269 @@
+#!/bin/bash
+# PreToolUse (Read|Grep|Bash) + UserPromptSubmit hook: sensitive-data gate.
+#
+# Blocks sensitive data — API keys, private keys, credentials, secret files —
+# from being sent to the AI. Strict by design ("cảnh cực gắt"): mere suspicion
+# of private data blocks the call so the USER decides. Detection covers three
+# egress channels into model context:
+#   1. Read/Grep of secret files (.env*, *.pem, id_rsa, credentials.json, ...)
+#   2. Bash commands that dump secrets (cat .env, bare `env`, curl -u user:pass,
+#      URL-embedded credentials, any high-confidence token in the command text)
+#   3. UserPromptSubmit prompt text containing high-confidence secret patterns
+#
+# FAIL-CLOSED on detection (exit 2). Never echoes the detected value — only a
+# redacted preview plus a truncated sha256 (12 hex chars: enough for the human
+# to verify, not enough for the model to forge an allowlist entry).
+#
+# User escape hatches (explicit human action only):
+#   - security.sensitiveDataGate=false in .ukit/storage/config.json disables the gate
+#   - .ukit/storage/security/allowlist.json { values: [sha256...], paths: [...] }
+#     approves exact secrets / file paths (protect-files.sh blocks model edits there)
+#
+# Fails open only when there is nothing to scan (malformed stdin, no channel):
+# a broken gate must not brick every session, but every real detection blocks.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+
+const payload = (() => {
+  try {
+    const parsed = JSON.parse(process.env.INPUT || '');
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+})();
+
+const projectRoot = process.env.PROJECT_ROOT || process.cwd();
+
+function readJsonSafe(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), null);
+if (config && config.security && config.security.sensitiveDataGate === false) {
+  process.exit(0);
+}
+
+const allowlist = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'security', 'allowlist.json'), null) || {};
+const allowedValueHashes = new Set(
+  Array.isArray(allowlist.values) ? allowlist.values.filter((v) => typeof v === 'string') : [],
+);
+const allowedPaths = Array.isArray(allowlist.paths) ? allowlist.paths.filter((p) => typeof p === 'string') : [];
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function pathAllowed(filePath) {
+  const normalized = String(filePath).replace(/\\/g, '/').trim();
+  let relative = normalized;
+  try {
+    relative = path.relative(projectRoot, normalized);
+  } catch {
+    // keep normalized
+  }
+  return allowedPaths.some((allowed) => allowed === normalized || allowed === relative);
+}
+
+// --- high-confidence secret value patterns (shared by prompt + bash scanning) ---
+const TOKEN_PATTERNS = [
+  { label: 'OpenAI/Anthropic-style API key', re: /\bsk-(?:proj-|ant-|svc-|acct-|admin-)?[A-Za-z0-9_-]{20,}/g },
+  { label: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g },
+  { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/g },
+  { label: 'GitLab token', re: /\bglpat-[A-Za-z0-9_-]{20,}/g },
+  { label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{20,}/g },
+  { label: 'Stripe live key', re: /\b[srp]k_live_[A-Za-z0-9]{20,}/g },
+  { label: 'JWT', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  { label: 'private key block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+  { label: 'bearer token', re: /\bBearer\s+[A-Za-z0-9._+/=-]{20,}/gi },
+];
+
+const ASSIGNMENT_RE = /(^|[^A-Za-z0-9_])(api[_-]?key|apikey|secret[_-]?key|secret|client[_-]?secret|password|passwd|auth[_-]?token|access[_-]?token|token)\s*[:=]\s*["']?([A-Za-z0-9+/_.~-]{16,})/gi;
+
+function scanSecretText(text) {
+  const found = [];
+  for (const { label, re } of TOKEN_PATTERNS) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+      found.push({ label, value: match[0] });
+    }
+  }
+  ASSIGNMENT_RE.lastIndex = 0;
+  let match;
+  while ((match = ASSIGNMENT_RE.exec(text)) !== null) {
+    found.push({ label: `${match[2].toLowerCase()} assignment`, value: match[3] });
+  }
+  return found;
+}
+
+// --- secret file classification ---
+function classifySecretFile(filePath) {
+  if (typeof filePath !== 'string' || !filePath.trim()) return null;
+  const normalized = filePath.replace(/\\/g, '/').trim();
+  const rawBase = normalized.split('/').pop();
+  if (!rawBase) return null;
+  const base = rawBase.toLowerCase();
+  if (base.endsWith('.env.example')) return null;
+  if (base === '.env' || base.startsWith('.env.')) return 'dotenv/secret env file';
+  if (base.endsWith('.pub') || base.endsWith('.public')) return null;
+  if (/^id_(rsa|dsa|ecdsa|ed25519)(\.|$)/.test(base)) return 'SSH private key';
+  if (/\.(pem|key|p12|pfx|keystore|jks)$/.test(base)) return 'key/certificate file';
+  if (/^credentials\.(json|ya?ml|txt|ini)$/.test(base)) return 'credentials file';
+  if (/^service[_-]?account.*\.json$/.test(base)) return 'service-account key file';
+  if (base === '.npmrc' || base === '.netrc' || base === '.htpasswd') return 'credentials file';
+  if (/^secrets?\.(json|ya?ml|txt|ini|env)$/.test(base)) return 'secrets file';
+  if (/(^|\/)\.aws\/credentials$/i.test(normalized)) return 'AWS credentials file';
+  return null;
+}
+
+// --- bash command shapes that dump secrets ---
+const DUMP_VERBS = new Set([
+  'cat', 'head', 'tail', 'less', 'more', 'zless', 'zcat', 'xxd', 'strings',
+  'base64', 'od', 'hexdump', 'bat', 'grep', 'egrep', 'fgrep', 'rg', 'awk', 'sed',
+]);
+
+function scanBashShapes(command) {
+  const found = [];
+  const segments = command.split(/\|\||&&|;|\||\n/);
+  for (const rawSegment of segments) {
+    const segment = rawSegment.trim();
+    if (!segment) continue;
+    const tokens = segment.split(/\s+/);
+    const head = tokens[0].replace(/^["']+|["']+$/g, '');
+
+    if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
+      found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
+      continue;
+    }
+    if (head === 'export' && (tokens[1] === '-p' || tokens[1] === '--print')) {
+      found.push({ label: 'bare `export -p` dumps all environment variables', value: segment });
+      continue;
+    }
+
+    if (DUMP_VERBS.has(head)) {
+      for (const token of tokens.slice(1)) {
+        const cleaned = token.replace(/^["']+|["',:]+$/g, '');
+        const kind = classifySecretFile(cleaned);
+        if (kind && !pathAllowed(cleaned)) {
+          found.push({ label: `${head} reads ${kind}`, value: cleaned, isPath: true });
+        }
+      }
+    }
+
+    if (/(^|\s)(-u|--user)\s+["']?[^\s"':]+:[^\s"']+/.test(segment)) {
+      found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+    }
+    if (/https?:\/\/[^\s/@'"]+:[^\s/@'"]+@/.test(segment)) {
+      found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
+    }
+  }
+  return found;
+}
+
+// --- channel wiring ---
+const event = String(payload.hook_event_name || '');
+const toolName = String(payload.tool_name || '');
+const toolInput = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+
+const textChannels = [];
+const filePathChannels = [];
+let bashCommand = null;
+
+if (event === 'UserPromptSubmit') {
+  const prompt = [payload.prompt, payload.user_prompt, payload.text].find(
+    (candidate) => typeof candidate === 'string' && candidate.trim(),
+  );
+  if (prompt) textChannels.push({ channel: 'prompt', text: prompt });
+} else if (event === 'PreToolUse') {
+  if (toolName === 'Read' && typeof toolInput.file_path === 'string') {
+    filePathChannels.push(toolInput.file_path);
+  } else if (toolName === 'Grep') {
+    if (typeof toolInput.path === 'string' && toolInput.path.trim()) filePathChannels.push(toolInput.path);
+    if (typeof toolInput.pattern === 'string') textChannels.push({ channel: 'grep pattern', text: toolInput.pattern });
+  } else if (toolName === 'Bash' && typeof toolInput.command === 'string') {
+    bashCommand = toolInput.command;
+  }
+} else {
+  process.exit(0);
+}
+
+// --- collect findings ---
+const findings = [];
+
+for (const filePath of filePathChannels) {
+  const kind = classifySecretFile(filePath);
+  if (kind && !pathAllowed(filePath)) {
+    findings.push({ label: `Read of ${kind}`, preview: filePath, hashSource: filePath });
+  }
+}
+
+const seenValues = new Set();
+for (const { channel, text } of textChannels) {
+  for (const finding of scanSecretText(text)) {
+    if (allowedValueHashes.has(sha256(finding.value))) continue;
+    const key = `${channel}:${finding.label}:${finding.value}`;
+    if (seenValues.has(key)) continue;
+    seenValues.add(key);
+    findings.push({ label: `${finding.label} in ${channel}`, value: finding.value });
+  }
+}
+
+if (bashCommand) {
+  for (const finding of scanBashShapes(bashCommand)) {
+    if (finding.isPath) {
+      findings.push({ label: `bash command touches ${finding.label}`, preview: finding.value });
+      continue;
+    }
+    if (allowedValueHashes.has(sha256(finding.value))) continue;
+    findings.push({ label: `${finding.label} in bash command`, value: finding.value });
+  }
+  for (const finding of scanSecretText(bashCommand)) {
+    if (allowedValueHashes.has(sha256(finding.value))) continue;
+    const key = `bash:${finding.label}:${finding.value}`;
+    if (seenValues.has(key)) continue;
+    seenValues.add(key);
+    findings.push({ label: `${finding.label} in bash command`, value: finding.value });
+  }
+}
+
+if (findings.length === 0) {
+  process.exit(0);
+}
+
+// --- block message: redacted previews only, never the secret itself ---
+function describeFinding(finding) {
+  const where = finding.preview
+    ? `${finding.preview}`
+    : `${String(finding.value).slice(0, 3)}…(${String(finding.value).length} chars, sha256 ${sha256(String(finding.value)).slice(0, 12)}…)`;
+  return `  - ${finding.label}: ${where}`;
+}
+
+const lines = [
+  `BLOCKED (sensitive data): ${findings.length} potential secret(s) detected. Nothing was sent to the AI.`,
+  ...findings.map(describeFinding),
+  'This gate is intentionally strict — it blocks on suspicion so the USER decides.',
+  'To proceed, the USER must choose one of:',
+  '  1. Redact the secret (placeholder like <API_KEY>) and retry.',
+  '  2. Approve it explicitly: add the full sha256 (shasum -a 256 of the value) or the file path',
+  '     to .ukit/storage/security/allowlist.json — that file is protected from AI edits.',
+  '  3. Disable the gate: security.sensitiveDataGate=false in .ukit/storage/config.json (not recommended).',
+  'Never repeat or guess the detected value in your reply. Ask the user instead.',
+];
+process.stderr.write(`${lines.join('\n')}\n`);
+process.exit(2);
+NODE
+
+exit $?

package/templates/.claude/hooks/skill-router.sh

@@ -41,6 +41,33 @@ STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 THRESHOLD_SCRIPT="$HOOK_DIR/../ukit/runtime/compact-threshold.mjs"
 
+# Sidechain early-exit: PreToolUse/PostToolUse payloads carry agent_id/agent_type only
+# when the tool call runs INSIDE a subagent (documented marker). A subagent's Edit/Bash
+# must not re-key or re-classify the MAIN request's route — that churn swapped
+# completionEvidence mid-request and made the main Stop gate demand the wrong evidence.
+# Fails OPEN: any parse problem, missing field, or node error falls through to normal
+# routing. Pure-bash pre-check first: the node guard can only match when the literal
+# "agent_id" key appears, so ordinary calls never pay the node spawn.
+case "$INPUT" in
+  *'"agent_id"'*|*'"agent_type"'*)
+    if printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (c) => chunks.push(c));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.exit(payload && typeof payload === "object"
+      && (payload.agent_id || payload.agent_type) ? 0 : 1);
+  } catch {
+    process.exit(1);
+  }
+});
+' >/dev/null 2>&1; then
+      exit 0
+    fi
+    ;;
+esac
+
 INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" STATE_FILE="$STATE_FILE" HOOK_DIR="$HOOK_DIR" node <<'NODE'
 const fs = require('fs');
 const path = require('path');
@@ -2415,6 +2442,10 @@ const { pathToFileURL } = require('url');
     }
 
     ensureDir(statePath);
+    // A no-route prompt (short nudge, informational question) must not wipe the last full
+    // route: completion-gate.sh reads routeSummary/requestKey from this state to decide
+    // whether a Stop is premature. Downgrading to a route-less state here silently disarms
+    // the gate mid-task, so carry the previous route forward until a real route replaces it.
     fs.writeFileSync(statePath, JSON.stringify({
       fingerprint,
       ts: now,
@@ -2422,6 +2453,8 @@ const { pathToFileURL } = require('url');
       activeSkills: [],
       routingContext: compactRoutingContext(routingContext),
       ...(previousContext ? { previousContext: compactPreviousContext(previousContext) } : {}),
+      ...(previous?.routeSummary ? { routeSummary: previous.routeSummary } : {}),
+      ...(previous?.requestKey ? { requestKey: previous.requestKey } : {}),
     }));
     process.exit(0);
   }

package/templates/.claude/hooks/vision-router.sh

@@ -12,6 +12,12 @@
 #
 # Runs on EVERY prompt, 8s budget: one shell-out to extract-image.mjs
 # --detect --mark-pending --json, no decoding.
+#
+# Hint policy (dedup): the full dispatch hint fires ONLY when the extractor armed
+# NEW pending markers this prompt. Mentions whose markers already carry
+# analyzed-<sha>.json receipts are silent — re-hinting a closed, analyzed image on
+# every unrelated prompt is the false-positive loop this version exists to kill.
+# A named path that does not resolve from the project root gets a short note only.
 
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
@@ -81,12 +87,9 @@ const { pathToFileURL } = require('url');
 
   // Shell out to the single owner of image detection + marker writing. Runs on every
   // prompt (cheap: --detect --mark-pending, never decodes). All three input forms are
-  // armed here, not just pasted images: a path or URL that only produced hint text would
-  // leave Edit/Write ungated, which is exactly the "analyse blind" case this cycle exists
-  // to prevent. --ref hashes a local file's bytes / a URL string inside the extractor.
-  let markedPasted = 0;
-  let markedPath = 0;
-  let markedUrl = 0;
+  // armed here, not just pasted images. --ref hashes a local file's bytes / a URL
+  // string inside the extractor.
+  let extractorJson = null;
   const extractorPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'extract-image.mjs');
   if (fs.existsSync(extractorPath)) {
     const args = [extractorPath, '--detect', '--mark-pending', '--json'];
@@ -105,34 +108,50 @@ const { pathToFileURL } = require('url');
         encoding: 'utf8',
         timeout: 6000,
       });
-      const parsed = JSON.parse(out);
-      const images = Array.isArray(parsed?.images) ? parsed.images : [];
-      // Ref markers carry a `source`; pasted ones do not. Counting this way stays correct
-      // when a named path does not exist on disk and the extractor drops it.
-      markedPasted = images.filter((img) => !img?.source).length;
-      markedPath = images.filter((img) => img?.source === 'path').length;
-      markedUrl = images.filter((img) => img?.source === 'url').length;
+      extractorJson = JSON.parse(out);
     } catch (err) {
       process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})\n`);
     }
   }
 
-  // `cases` reflects what the PROMPT mentioned. Named paths that do not resolve from
-  // the project root still get the unresolved-path note below.
+  // Decide from what the EXTRACTOR did, not from prompt-text regex hits: `written`
+  // markers are genuinely new work; `alreadyAnalyzed` entries are closed cases that
+  // must stay silent. Regex mentions alone no longer trigger the full hint.
+  const images = Array.isArray(extractorJson?.images) ? extractorJson.images : [];
+  const analyzed = Array.isArray(extractorJson?.alreadyAnalyzed) ? extractorJson.alreadyAnalyzed : [];
+  const sessionId = typeof extractorJson?.sessionId === 'string' && extractorJson.sessionId
+    ? extractorJson.sessionId
+    : '';
+  const armedCount = images.length;
+  const armedRefs = new Set(images.filter((img) => typeof img?.ref === 'string').map((img) => img.ref));
+  const analyzedRefs = new Set(analyzed.filter((a) => typeof a?.ref === 'string').map((a) => a.ref));
+  const unresolvedLocal = localMatches.filter(
+    (m) => !armedRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
+  );
   const cases = [];
-  if (markedPasted > 0) cases.push('pasted image');
-  if (localMatches.length > 0) cases.push('local file path');
-  if (urlMatches.length > 0) cases.push('image URL');
-
-  if (cases.length === 0) {
+  if (images.some((img) => !img?.source)) cases.push('pasted image');
+  if (images.some((img) => img?.source === 'path')) cases.push('local file path');
+  if (images.some((img) => img?.source === 'url')) cases.push('image URL');
+
+  if (armedCount === 0) {
+    // No NEW markers. Only speak up when a named path never resolved at all —
+    // an already-analyzed mention is a closed case and stays silent.
+    if (unresolvedLocal.length > 0) {
+      const lines = [
+        `UKIT VISION ROUTE — named image path did not resolve from the project root (${unresolvedLocal[0]}).`,
+        'Nothing was armed for analysis. Resolve the real path or drop the reference;',
+        'never guess at the contents of an image you cannot read.',
+      ];
+      process.stdout.write(`${lines.join('\n')}\n`);
+    }
     process.exit(0);
     return;
   }
 
-  // Only unicMode true or null reach here; off-gateway already exited. Both remaining
-  // cases get the same strict `unic-vision` remedy, so there is no fallback-model branch
-  // to advertise. There must never be one: the analyst self-reports the model it really
-  // ran on, so telling it to claim some other ID is asking it to falsify the receipt.
+  // Only unicMode true or null reach here; off-gateway already exited. There is no
+  // fallback-model branch to advertise. There must never be one: the analyst
+  // self-reports the model it really ran on, so telling it to claim some other ID is
+  // asking it to falsify the receipt.
   let unicNote = '';
   if (unicMode === true) {
     try {
@@ -147,26 +166,33 @@ const { pathToFileURL } = require('url');
     }
   }
 
-  const reasonLine = 'unic-code / unic-smart cannot read images on this gateway — never guess at\nimage contents. Do this before relying on them:';
-  const agentLine = '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]';
+  // Capability-framed, never provider identity: the remedy is "don't guess — use a
+  // verified reader", which holds whether the active model reads images natively or
+  // must hand off to the specialist.
+  const reasonLines = [
+    'Advisory: never guess at image contents. If the active model has VERIFIED native',
+    'vision for these images it may read them directly; otherwise dispatch the specialist',
+    'before relying on them:',
+  ];
 
   const lines = [
-    `UKIT VISION ROUTE — image input detected (${cases.join(', ')}).`,
-    reasonLine,
+    `UKIT VISION ROUTE — new image input detected (${cases.join(', ')}).`,
+    ...reasonLines,
     '  1. node .claude/ukit/index/extract-image.mjs --json',
-    agentLine,
-    '     Pass the ABSOLUTE paths from images[].path as text — a subagent does NOT',
-    '     inherit image blocks; it can only Read files.',
+    '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
+    '     Send the ABSOLUTE paths from images[].path as TEXT (subagents do NOT inherit',
+    '     image blocks; they can only Read files). Include the task envelope: the ORIGINAL',
+    '     user prompt verbatim, the visual question, and the task goal — the analyst must',
+    '     know what the images are FOR.',
+    '  3. Continue the real task using the analyst\'s OBSERVATIONS + INFERENCES.',
   ];
-  lines.push('  3. Continue the real task using the returned description.');
-  if (markedUrl > 0) {
+  if (sessionId) {
+    lines.push(`  Markers armed under sessionId: ${sessionId} (receipts: analyzed-<sha>.json).`);
+  }
+  if (images.some((img) => img?.source === 'url')) {
     lines.push('  Image URL detected: ukit-vision-analyst downloads it with Bash into');
     lines.push('  .ukit/storage/cache/vision/, then Reads the downloaded file.');
   }
-  if (localMatches.length > markedPath) {
-    lines.push('  A named image path did not resolve from the project root — resolve it before');
-    lines.push('  analysing, and do not guess at its contents.');
-  }
   if (unicNote) lines.push(unicNote);
 
   process.stdout.write(`${lines.join('\n')}\n`);

package/templates/.claude/settings.json

@@ -54,7 +54,13 @@
     "PreToolUse": [
       {
         "matcher": "Read|Grep|Glob",
-        "hooks": []
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
+            "timeout": 8
+          }
+        ]
       },
       {
         "matcher": "Edit|Write",
@@ -104,6 +110,11 @@
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",
             "timeout": 8
           },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
@@ -162,6 +173,11 @@
     "UserPromptSubmit": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sensitive-data-guard.sh\"",
+            "timeout": 8
+          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",