@ngockhoale/ukit 1.6.3 → 1.6.5

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# PreToolUse hook: hard-enforce UKit handoff model-tier contract.
+#
+# create (planning) and review must be authored by the strong tier (opus/unic-smart);
+# implement must be authored by at least the code tier (sonnet/unic-code), never lite.
+#
+# Applies identically whether triggered via standalone /ukit:handoff-create,
+# /ukit:handoff-implement, /ukit:handoff-review, or the combined /ukit:handoff-fullstack —
+# the gate is keyed on file content, not on which command was run.
+#
+# Always hard-blocks (exit 2). No advisory/soft mode — the user explicitly asked for
+# strict enforcement of this contract.
+
+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 payload = (() => {
+  try { return JSON.parse(process.env.INPUT || '{}'); } catch { return {}; }
+})();
+const projectRoot = process.env.PROJECT_ROOT;
+const toolName = payload?.tool_name || '';
+const input = payload?.tool_input || {};
+
+function block(message) {
+  process.stderr.write(`BLOCKED (handoff model-tier guard): ${message}\n`);
+  process.exit(2);
+}
+
+function tierOf(model) {
+  if (!model) return null;
+  if (/unic-vision/i.test(model)) return 'vision';
+  if (/opus|unic-smart/i.test(model)) return 'smart';
+  if (/sonnet|unic-code/i.test(model)) return 'code';
+  if (/haiku|unic-lite/i.test(model)) return 'lite';
+  return 'unknown';
+}
+
+const VISION_LANE_MESSAGE =
+  'is a vision capability lane, not a handoff role; use unic-smart for planning/review and unic-code for implementation.';
+
+function extractField(text, name) {
+  const matches = [...text.matchAll(new RegExp(name + ':\\s*(.+)', 'g'))];
+  if (matches.length === 0) return '';
+  return matches[matches.length - 1][1].trim();
+}
+
+if (toolName === 'Write' || toolName === 'Edit') {
+  const filePath = String(input.file_path || '');
+  if (!filePath) process.exit(0);
+
+  const relPath = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+  const isPlan = relPath === 'docs/AI_HANDOFF/PLAN.md';
+  const taskMatch = relPath.match(/^docs\/AI_HANDOFF\/tasks\/(TASK-\d+)\.md$/);
+  if (!isPlan && !taskMatch) process.exit(0);
+
+  const fileExists = fs.existsSync(filePath);
+  const currentContent = fileExists ? fs.readFileSync(filePath, 'utf8') : '';
+
+  function resultingContent() {
+    if (toolName === 'Write') {
+      return typeof input.content === 'string' ? input.content : currentContent;
+    }
+    const oldStr = input.old_string;
+    const newStr = input.new_string;
+    if (typeof oldStr !== 'string' || typeof newStr !== 'string') return currentContent;
+    return input.replace_all
+      ? currentContent.split(oldStr).join(newStr)
+      : currentContent.replace(oldStr, newStr);
+  }
+  const newContent = resultingContent();
+
+  if (isPlan && /## Planner Report/.test(newContent)) {
+    const plannerModel = extractField(newContent, 'PLANNER_MODEL');
+    if (!plannerModel || /^unknown$/i.test(plannerModel)) {
+      block('PLANNER_MODEL missing/unknown in PLAN.md. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) and self-report its model.');
+    }
+    if (tierOf(plannerModel) === 'vision') {
+      block(`PLANNER_MODEL "${plannerModel}" ${VISION_LANE_MESSAGE}`);
+    }
+    if (tierOf(plannerModel) !== 'smart') {
+      block(`PLANNER_MODEL "${plannerModel}" is not strong/opus tier. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart).`);
+    }
+  }
+
+  if (taskMatch) {
+    const taskId = taskMatch[1];
+    const planPath = path.join(projectRoot, 'docs/AI_HANDOFF/PLAN.md');
+
+    const isFreshTaskFile = !fileExists && !/## Executor Report|## Reviewer Verdict/.test(newContent);
+    if (isFreshTaskFile) {
+      const planContent = fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf8') : '';
+      const plannerModel = extractField(planContent, 'PLANNER_MODEL');
+      if (!plannerModel || tierOf(plannerModel) !== 'smart') {
+        block(`Cannot create ${taskId}.md — PLAN.md has no valid smart-tier PLANNER_MODEL yet. Run planning via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) first.`);
+      }
+    }
+
+    if (/## Executor Report/.test(newContent) && !/## Executor Report/.test(currentContent)) {
+      const executorModel = extractField(newContent, 'EXECUTOR_MODEL');
+      if (!executorModel || /^unknown$/i.test(executorModel)) {
+        block(`${taskId}: EXECUTOR_MODEL missing/unknown. Implementation must run via Agent tool subagent_type: "feature-implementer" (sonnet/unic-code) and self-report its model.`);
+      }
+      if (tierOf(executorModel) === 'vision') {
+        block(`${taskId}: EXECUTOR_MODEL "${executorModel}" ${VISION_LANE_MESSAGE}`);
+      }
+      if (tierOf(executorModel) === 'lite') {
+        block(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier. Implementation must run on at least sonnet/unic-code, never haiku/unic-lite.`);
+      }
+    }
+
+    if (/## Reviewer Verdict/.test(newContent) && !/## Reviewer Verdict/.test(currentContent)) {
+      const executorModel = extractField(currentContent, 'EXECUTOR_MODEL') || extractField(newContent, 'EXECUTOR_MODEL');
+      const reviewerModel = extractField(newContent, 'REVIEWER_MODEL');
+      if (!reviewerModel || /^unknown$/i.test(reviewerModel)) {
+        block(`${taskId}: REVIEWER_MODEL missing/unknown. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart) and self-report its model.`);
+      }
+      if (tierOf(reviewerModel) === 'vision') {
+        block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" ${VISION_LANE_MESSAGE}`);
+      }
+      if (tierOf(reviewerModel) !== 'smart') {
+        block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not strong/opus tier. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart).`);
+      }
+      if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
+        block(`${taskId}: REVIEWER_MODEL ("${reviewerModel}") matches EXECUTOR_MODEL — reviewer must differ from executor. Re-run review through a different subagent/model.`);
+      }
+    }
+  }
+  process.exit(0);
+}
+
+if (toolName === 'Bash') {
+  const command = String(input.command || '');
+  if (!/\bgit\s+push\b/.test(command)) process.exit(0);
+
+  const activePath = path.join(projectRoot, 'docs/AI_HANDOFF/ACTIVE.md');
+  const indexPath = path.join(projectRoot, 'docs/AI_HANDOFF/INDEX.md');
+  if (!fs.existsSync(activePath) || !fs.existsSync(indexPath)) process.exit(0); // no handoff cycle here
+
+  const taskIds = [...fs.readFileSync(indexPath, 'utf8').matchAll(/TASK-\d+/g)]
+    .map((m) => m[0])
+    .filter((v, i, a) => a.indexOf(v) === i);
+
+  const problems = [];
+  for (const taskId of taskIds) {
+    const taskPath = path.join(projectRoot, `docs/AI_HANDOFF/tasks/${taskId}.md`);
+    if (!fs.existsSync(taskPath)) continue;
+    const text = fs.readFileSync(taskPath, 'utf8');
+    if (!text.includes('## Reviewer Verdict')) continue; // not yet reviewed, not this push's concern
+
+    const executorModel = extractField(text, 'EXECUTOR_MODEL');
+    const reviewerModel = extractField(text, 'REVIEWER_MODEL');
+
+    if (!executorModel || /^unknown$/i.test(executorModel)) problems.push(`${taskId}: EXECUTOR_MODEL missing/unknown`);
+    else if (tierOf(executorModel) === 'lite') problems.push(`${taskId}: EXECUTOR_MODEL "${executorModel}" is lite tier`);
+
+    if (!reviewerModel || /^unknown$/i.test(reviewerModel)) problems.push(`${taskId}: REVIEWER_MODEL missing/unknown`);
+    else if (tierOf(reviewerModel) !== 'smart') problems.push(`${taskId}: REVIEWER_MODEL "${reviewerModel}" is not opus/unic-smart tier`);
+
+    if (executorModel && reviewerModel && executorModel.toLowerCase() === reviewerModel.toLowerCase()) {
+      problems.push(`${taskId}: REVIEWER_MODEL == EXECUTOR_MODEL`);
+    }
+  }
+
+  if (problems.length > 0) {
+    block(`git push refused — handoff model-tier contract violated:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+  process.exit(0);
+}
+
+process.exit(0);
+NODE
+
+exit $?

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

@@ -0,0 +1,230 @@
+#!/bin/bash
+# PreToolUse hook: hard-enforce the TASK-008 vision-analysis gate.
+#
+# Blocks Edit/Write whenever a pending image marker (written by vision-router.sh via
+# extract-image.mjs --mark-pending) has no matching analyzed-<sha>.json receipt from a
+# vision-capable model. Opposite fail direction from vision-router.sh: that hook fails
+# OPEN (never wedge a prompt); this hook fails CLOSED (a broken gate must not silently
+# permit blind edits). "Fails closed" applies only to this hook's own logic errors — if
+# no pending marker exists at all, it exits 0 immediately, before any other logic. That
+# is >99% of invocations and must stay free.
+#
+# Always hard-blocks (exit 2). No advisory/soft mode — matches handoff-model-guard.sh's
+# posture: the user explicitly asked for strict, mechanical, non-bypassable enforcement.
+# A wrong image analysis yields confidently wrong results, which is worse than no
+# analysis at all.
+#
+# Matcher is Edit|Write ONLY. Never Read/Grep/Glob/Bash — ukit-vision-analyst itself
+# needs Read to see the extracted image and Bash to write its receipt; gating those
+# tools would deadlock the only lane that can clear the gate.
+#
+# Never recomputes a sha. extract-image.mjs (TASK-002) is the single owner of the hash;
+# this hook only matches pending-<sha>.json to analyzed-<sha>.json by filename.
+#
+# Session-scoped and 24h-bounded: a stale marker from another session, or an abandoned
+# session's marker older than 24h, must never permanently block writes.
+
+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 { pathToFileURL } = require('url');
+
+const MARKER_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+
+const payload = (() => {
+  try {
+    const parsed = JSON.parse(process.env.INPUT || '');
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+})();
+
+const projectRoot = process.env.PROJECT_ROOT;
+const toolName = payload?.tool_name || '';
+
+// Gate only Edit|Write. Every other tool (Read, Grep, Glob, Bash, ...) is free — the
+// vision analyst needs Read/Bash to clear this very gate. This check is independent of
+// tool_input shape: the gate never inspects file_path/content, only tool_name.
+if (toolName !== 'Edit' && toolName !== 'Write') {
+  process.exit(0);
+}
+
+const sessionId = (typeof payload.session_id === 'string' && payload.session_id.trim())
+  ? payload.session_id.trim()
+  : 'default';
+
+const sessionDir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'vision', sessionId);
+
+let markerNames = [];
+try {
+  markerNames = fs.readdirSync(sessionDir).filter((name) => /^pending-.+\.json$/.test(name));
+} catch {
+  markerNames = [];
+}
+
+// No pending marker at all: the overwhelmingly common path. Exit 0 immediately, before
+// any config reads, gateway detection, or receipt checks.
+if (markerNames.length === 0) {
+  process.exit(0);
+}
+
+function readJsonSafe(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Best-effort: a receipt whose model equals modelTiers.vision.fallbackModel counts as
+// vision-capable ONLY when unic-gateway.mjs reports unicMode:false (no real UNIC
+// routing, so the analyst actually ran on the fallback model instead of unic-vision).
+// In-process dynamic import — never a subprocess spawn — and never fatal: any failure
+// just means the fallback exception is unavailable and only the literal "unic-vision"
+// model name is accepted, which is the stricter/safer default.
+function loadFallbackModel() {
+  const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
+  const config = readJsonSafe(configPath);
+  const fallback = config?.orchestration?.modelTiers?.vision?.fallbackModel;
+  return typeof fallback === 'string' && fallback.trim() ? fallback.trim() : null;
+}
+
+// Tri-state on purpose: true | false | null(unknown). Returning false on a detection
+// FAILURE would be read as "unicMode is off", which GRANTS the fallback-model exception
+// below — i.e. deleting or breaking one gitignored file would make the gate accept a
+// plain code-tier receipt. Unknown must deny the exception, not grant it.
+async function detectUnicModeSafe() {
+  try {
+    const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
+    if (!fs.existsSync(gatewayPath)) return null;
+    const mod = await import(pathToFileURL(gatewayPath).href);
+    if (typeof mod.detectUnicGateway !== 'function') return null;
+    const result = mod.detectUnicGateway({ rootDir: projectRoot });
+    return !!result?.unicMode;
+  } catch {
+    return null;
+  }
+}
+
+// Anchored, not a substring match: "unic-vision-mini" and "not-unic-vision" are different
+// models and must not inherit the real one's capability by sharing a substring.
+// ukit-vision-analyst's frontmatter pins the exact name `unic-vision`; anything else goes
+// through the fallbackModel path, which requires a positive unicMode:false detection.
+function isVisionCapable(model, fallbackModel, unicModeIsOff) {
+  if (typeof model !== 'string' || !model.trim()) return false;
+  const trimmed = model.trim();
+  if (/^unic-vision$/i.test(trimmed)) return true;
+  if (unicModeIsOff && fallbackModel && trimmed === fallbackModel) return true;
+  return false;
+}
+
+const VALID_STATUSES = new Set(['OK', 'NO_IMAGE', 'UNREADABLE']);
+
+// A receipt whose self-reported model is not vision-capable (unic-code, unic-smart,
+// sonnet, opus, ...) is treated as ABSENT and still blocks — accepting it would make the
+// whole enforcement design theatre. A JSON.parse throw is caught per-receipt and turned
+// into BLOCK, never an accidental skip-through.
+// The gate keys its directory on the hook payload's session_id, but the analyst resolves
+// its own sessionId by discovering the newest transcript. Those agree in the common case
+// and diverge with concurrent sessions on one repo, which would leave the receipt in a
+// sibling directory and hold the gate shut. The sha is content-addressed, so accepting a
+// receipt from any session dir is safe: it still must exist and be vision-capable.
+function findReceipt(sha) {
+  const own = path.join(sessionDir, `analyzed-${sha}.json`);
+  if (fs.existsSync(own)) return own;
+  const visionRoot = path.join(projectRoot, '.ukit', 'storage', 'cache', 'vision');
+  let entries = [];
+  try {
+    entries = fs.readdirSync(visionRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === sessionId) continue;
+    const candidate = path.join(visionRoot, entry.name, `analyzed-${sha}.json`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function checkReceipt(receiptPath, fallbackModel, unicModeIsOff) {
+  if (!receiptPath || !fs.existsSync(receiptPath)) {
+    return { ok: false, reason: 'no analysis receipt found' };
+  }
+  const receipt = readJsonSafe(receiptPath);
+  if (!receipt) {
+    return { ok: false, reason: 'receipt is not valid JSON' };
+  }
+  if (!isVisionCapable(receipt.model, fallbackModel, unicModeIsOff)) {
+    const modelLabel = typeof receipt.model === 'string' && receipt.model.trim() ? receipt.model.trim() : '(missing)';
+    return { ok: false, reason: `receipt model "${modelLabel}" is not vision-capable — treated as absent` };
+  }
+  const status = receipt.status;
+  if (!VALID_STATUSES.has(status)) {
+    return { ok: false, reason: `receipt status "${status}" is not a valid terminal outcome` };
+  }
+  return { ok: true };
+}
+
+(async () => {
+  const now = Date.now();
+  const fallbackModel = loadFallbackModel();
+  const unicMode = await detectUnicModeSafe();
+
+  const unsatisfied = [];
+  for (const markerName of markerNames) {
+    const sha = markerName.replace(/^pending-/, '').replace(/\.json$/, '');
+    const markerPath = path.join(sessionDir, markerName);
+
+    let markerTs = null;
+    const marker = readJsonSafe(markerPath);
+    if (marker && typeof marker.ts === 'number' && Number.isFinite(marker.ts)) {
+      markerTs = marker.ts;
+    }
+    if (markerTs == null) {
+      try {
+        markerTs = fs.statSync(markerPath).mtimeMs;
+      } catch {
+        markerTs = now;
+      }
+    }
+    // Abandoned-session bound: a marker older than 24h can never brick the repo.
+    if (now - markerTs > MARKER_MAX_AGE_MS) continue;
+
+    const receiptPath = findReceipt(sha);
+    const result = checkReceipt(receiptPath, fallbackModel, unicMode === false);
+    if (!result.ok) {
+      unsatisfied.push({ sha, reason: result.reason });
+    }
+  }
+
+  if (unsatisfied.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  const lines = [
+    'BLOCKED (vision gate): image(s) pending analysis — Edit/Write refused.',
+    ...unsatisfied.map((u) => `  - sha ${u.sha}: ${u.reason}`),
+    'unic-code / unic-smart cannot read images on this gateway and must not guess at their',
+    'contents — a wrong image analysis yields confidently wrong results.',
+    'Remedy: delegate to Agent(subagent_type: "ukit-vision-analyst") to analyse the pending',
+    'image(s) first, then retry this edit.',
+  ];
+  process.stderr.write(`${lines.join('\n')}\n`);
+  process.exit(2);
+})().catch((err) => {
+  // A logic error inside this hook's own JS must still fail CLOSED — the opposite fail
+  // direction from vision-router.sh, which fails open unconditionally.
+  process.stderr.write(`BLOCKED (vision gate): internal error, failing closed: ${err?.message ?? err}\n`);
+  process.exit(2);
+});
+NODE
+
+exit $?

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

@@ -0,0 +1,155 @@
+#!/bin/bash
+# UserPromptSubmit hook: detect image input (pasted / local path / URL) and arm the
+# TASK-008 write gate by writing pending-<sha>.json markers via extract-image.mjs.
+#
+# FAILS OPEN, unconditionally: this hook must never block the user's prompt. Any
+# failure (malformed stdin, missing extractor, node crash) degrades to "no hint,
+# no markers" and exit 0. This is the deliberate opposite of the TASK-008 gate,
+# which fails closed on Edit/Write.
+#
+# Detection only — never decodes an image, never writes an image file. Marker
+# writing is delegated entirely to `extract-image.mjs --mark-pending`; this hook
+# never computes a sha itself (PLAN §3.1).
+#
+# Runs on EVERY prompt, 8s budget: one shell-out to extract-image.mjs
+# --detect --mark-pending --json, no decoding.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { pathToFileURL } = require('url');
+
+(async () => {
+  const payload = (() => {
+    try {
+      const parsed = JSON.parse(process.env.INPUT || '');
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+  const projectRoot = process.env.PROJECT_ROOT;
+
+  function extractPromptText(p) {
+    const candidates = [p?.prompt, p?.user_prompt, p?.text];
+    for (const candidate of candidates) {
+      if (typeof candidate === 'string' && candidate.trim()) return candidate;
+    }
+    return '';
+  }
+
+  const promptText = extractPromptText(payload);
+
+  // URL images are checked first and stripped out so the local-path regex never
+  // re-matches the tail of a URL (case c is a hint-only lane — no download here).
+  const URL_IMAGE_RE = /https?:\/\/\S+\.(?:png|jpe?g|gif|webp)\b/gi;
+  const LOCAL_PATH_RE = /\S+\.(?:png|jpe?g|gif|webp|bmp)\b/gi;
+
+  const urlMatches = promptText.match(URL_IMAGE_RE) || [];
+  const textWithoutUrls = promptText.replace(URL_IMAGE_RE, ' ');
+  const localMatches = textWithoutUrls.match(LOCAL_PATH_RE) || [];
+
+  // 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;
+  const extractorPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'extract-image.mjs');
+  if (fs.existsSync(extractorPath)) {
+    const args = [extractorPath, '--detect', '--mark-pending', '--json'];
+    if (typeof payload?.transcript_path === 'string' && payload.transcript_path.trim()) {
+      args.push('--session', payload.transcript_path.trim());
+    }
+    if (typeof payload?.session_id === 'string' && payload.session_id.trim()) {
+      args.push('--session-id', payload.session_id.trim());
+    }
+    for (const ref of [...localMatches, ...urlMatches]) {
+      args.push('--ref', ref);
+    }
+    try {
+      const out = execFileSync('node', args, {
+        cwd: projectRoot,
+        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;
+    } catch (err) {
+      process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})\n`);
+    }
+  }
+
+  // `cases` reflects what the PROMPT mentioned; `armed` reflects what actually got a
+  // pending marker. They differ when a named path does not resolve from the project root
+  // — still worth a hint, but the gate is not armed and must not be claimed to be.
+  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');
+  const armed = markedPasted + markedPath + markedUrl;
+
+  if (cases.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Optional: name the concrete vision model when the UNIC gateway is active
+  // (TASK-003). Never fatal — a missing/broken gateway module just omits the note.
+  let unicNote = '';
+  try {
+    const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
+    if (fs.existsSync(gatewayPath)) {
+      const mod = await import(pathToFileURL(gatewayPath).href);
+      if (typeof mod.detectUnicGateway === 'function') {
+        const result = mod.detectUnicGateway({ rootDir: projectRoot });
+        if (result?.unicMode) {
+          unicNote = `  (UNIC gateway active — ${result.visionModel} routes through it.)`;
+        }
+      }
+    }
+  } catch {
+    unicNote = '';
+  }
+
+  const lines = [
+    `UKIT VISION ROUTE — image input detected (${cases.join(', ')}).`,
+    armed > 0
+      ? 'unic-code / unic-smart cannot read images on this gateway, and Edit/Write is now GATED\nuntil a vision analysis exists. Do this before anything else:'
+      : 'unic-code / unic-smart cannot read images on this gateway. Do this before anything else:',
+    '  1. node .claude/ukit/index/extract-image.mjs --json',
+    '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
+    '     Pass the ABSOLUTE paths from images[].path as text — a subagent does NOT',
+    '     inherit image blocks; it can only Read files.',
+    '  3. Continue the real task using the returned description.',
+  ];
+  if (markedUrl > 0) {
+    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`);
+  process.exit(0);
+})().catch((err) => {
+  process.stderr.write(`vision-router: unexpected error (${err?.message ?? err})\n`);
+  process.exit(0);
+});
+NODE
+
+exit 0

package/templates/.claude/settings.json

@@ -77,6 +77,16 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
+            "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-gate.sh\"",
+            "timeout": 8
           }
         ]
       },
@@ -102,6 +112,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
+            "timeout": 8
           }
         ]
       }
@@ -135,6 +150,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\"",
+            "timeout": 8
           }
         ]
       }