@ngockhoale/ukit 1.6.4 → 1.6.5

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to UKit are documented here.
 
+## 1.6.5 - 2026-08-02
+
+### Added
+
+- **Enforced `unic-vision` image lane.** Images are now mechanically routed to a vision-capable model instead of being guessed at by `unic-code`/`unic-smart`, which cannot read images on the UNIC gateway.
+  - `.claude/ukit/index/extract-image.mjs` — decodes pasted images out of the session transcript to disk (a spawned subagent receives text only and does not inherit image blocks), and writes content-addressed `pending-<sha>.json` markers. Single owner of the sha256; both the marker and the image filename come from the same hash.
+  - `.claude/hooks/vision-router.sh` (`UserPromptSubmit`) — detects all three input forms (pasted, local path, image URL) and arms a marker for each. Fails OPEN: a failure here degrades to no hint and no markers, never a wedged prompt.
+  - `.claude/hooks/vision-gate.sh` (`PreToolUse`, `Edit|Write` only) — hard-blocks the write (exit 2) until an `analyzed-<sha>.json` receipt exists whose self-reported model is vision-capable. A receipt from `unic-code`, `unic-smart`, `sonnet`, or `opus` is treated as ABSENT and still blocks. Fails CLOSED, and gateway detection that is missing or broken DENIES the fallback-model exception rather than granting it. `Read`/`Grep`/`Glob`/`Bash` are never gated — the vision analyst needs them to clear the gate.
+  - `ukit-vision-analyst` agent — pinned to `unic-vision`, the only lane permitted to interpret images. Reports findings only; it has no `Edit`/`Write`.
+  - `.claude/ukit/index/unic-gateway.mjs` — detects a `unicjsc.com` gateway across Claude Code env, Codex config, Kilo config, and `OPENAI_BASE_URL`. Only ever tests for substring presence; never reads credential file contents into output.
+
+### Changed
+
+- `orchestration.escalation` now has real consumers. `route-task.mjs` reads `debugLoopThreshold`, `tierOrder`, and `cap` from config instead of hardcoded literals, and emits `escalatedTier` alongside `modelTier` — one rung up, capped at `smart`. The same literals remain as fallbacks, so projects that never opted in behave identically.
+- `orchestration.modelTiers` documents all four UNIC models. `vision` is a capability lane orthogonal to the lite/code/smart cost tiers, never a fourth tier, and is stripped from any configured `tierOrder`.
+- `handoff-model-guard.sh`: `tierOf()` hardened against vision/unknown model names.
+
 ## 1.6.4 - 2026-07-27
 
 ### Added

package/manifests/platform.full.yaml

@@ -819,6 +819,17 @@ items:
     packs:
       - core
 
+  - id: agent-ukit-vision-analyst
+    type: agent
+    sourceTemplate: .claude/agents/ukit-vision-analyst.md
+    targetPath: .claude/agents/ukit-vision-analyst.md
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: command-handoff-create
     type: command
     sourceTemplate: .claude/commands/ukit/handoff-create.md
@@ -1037,6 +1048,32 @@ items:
     packs:
       - core
 
+  - id: hook-vision-router
+    type: hook
+    sourceTemplate: .claude/hooks/vision-router.sh
+    targetPath: .claude/hooks/vision-router.sh
+    requires:
+      - ukit-index-extract-image-script
+      - ukit-index-unic-gateway-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: hook-vision-gate
+    type: hook
+    sourceTemplate: .claude/hooks/vision-gate.sh
+    targetPath: .claude/hooks/vision-gate.sh
+    requires:
+      - ukit-index-extract-image-script
+      - ukit-index-unic-gateway-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-compress-output
     type: hook
     sourceTemplate: .claude/hooks/compress-output.sh
@@ -1266,6 +1303,26 @@ items:
     packs:
       - core
 
+  - id: ukit-index-unic-gateway-script
+    type: config
+    sourceTemplate: .claude/ukit/index/unic-gateway.mjs
+    targetPath: .claude/ukit/index/unic-gateway.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: ukit-index-extract-image-script
+    type: config
+    sourceTemplate: .claude/ukit/index/extract-image.mjs
+    targetPath: .claude/ukit/index/extract-image.mjs
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-route-task-script
     type: config
     sourceTemplate: .claude/ukit/index/route-task.mjs
@@ -1274,6 +1331,8 @@ items:
       - ukit-index-core-lib
       - ukit-index-cache-utils-script
       - ukit-index-route-catalog-script
+      - ukit-index-unic-gateway-script
+      - ukit-index-extract-image-script
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/runtimeConfig.js

@@ -164,6 +164,24 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
           delegationPolicy: 'allow-review-sidecar',
         },
       },
+      modelTiers: {
+        lite: { claudeModel: 'claude-haiku-4-5', genericModel: 'unic-lite' },
+        code: { claudeModel: 'claude-sonnet-4-6', genericModel: 'unic-code' },
+        smart: { claudeModel: 'claude-opus-4-6', genericModel: 'unic-smart' },
+        vision: {
+          claudeModel: 'unic-vision',
+          genericModel: 'unic-vision',
+          fallbackModel: 'claude-sonnet-4-6',
+          capabilityTier: true,
+          note: 'Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off.',
+        },
+      },
+      escalation: {
+        enabled: true,
+        debugLoopThreshold: 2,
+        tierOrder: ['lite', 'code', 'smart'],
+        cap: 'smart',
+      },
     },
     memory: {
       enabled: true,
@@ -196,6 +214,14 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       enabled: true,
       smallTaskModel: 'unic-lite',
       smallTaskAgent: 'ukit-small-task-maintainer',
+      visionEnabled: true,
+      visionModel: 'unic-vision',
+      visionAgent: 'ukit-vision-analyst',
+      visionCacheDir: '.ukit/storage/cache/vision',
+      visionMaxImages: 3,
+      visionMaxBytes: 10_485_760,
+      visionRetain: 20,
+      visionSessionTtlHours: 24,
       smallTaskUseCases: [
         'task-cleanup',
         'compact-decision',

package/templates/.claude/agents/ukit-vision-analyst.md

@@ -0,0 +1,101 @@
+---
+name: ukit-vision-analyst
+description: "The only lane permitted to interpret images in this repo. Use whenever a prompt references, attaches, or points at an image (screenshot, mockup, diagram, photo of an error) and the caller needs to know what is actually in it. unic-code/unic-smart cannot read images on this gateway and must never guess at their contents — route image analysis here instead. Reports findings only; never writes product code."
+model: unic-vision  # real gateway model name, NOT an alias. unic-code/unic-smart cannot read images on this gateway — do NOT "fix" this to sonnet/opus.
+color: magenta
+tools: ["Read", "Glob", "Bash"]
+---
+
+You are UKit's vision analyst. Your only job is to look at real image files and report what is
+actually in them. You never write, edit, or refactor product code — you analyse and report.
+
+## 1. Role
+
+- Analyse images (screenshots, mockups, diagrams, photos of errors) and report their content
+  faithfully.
+- Never write product code. `Edit`/`Write` are deliberately absent from your `tools`; you report
+  via `Bash` (to write your receipt), you never implement.
+- Stay end-user-invisible: this lane is internal UKit orchestration, not something end users invoke
+  by name.
+
+## 2. Model self-check — first action, before touching any image
+
+Before reading any image, determine the model you are actually running on right now.
+
+- Vision-capable means: `unic-vision`, or — when `unicMode` is off — whatever
+  `modelTiers.vision.fallbackModel` resolves to per
+  `node .claude/ukit/index/unic-gateway.mjs --json`.
+- If you cannot confirm you are running on a vision-capable model, you must **refuse**: emit
+  `STATUS: WRONG_MODEL` in the output block below and stop immediately. Do not open, describe, or
+  guess at any image content.
+- Never guess at image contents. A wrong-model "analysis" is worse than no analysis at all,
+  because it looks authoritative while being fabricated. Refusing loudly is always safer than
+  guessing quietly.
+
+## 3. Input protocol (priority order)
+
+1. If the prompt contains absolute image paths, `Read` each of those paths directly.
+2. Otherwise, run `node .claude/ukit/index/extract-image.mjs --json`, take the `images[].path`
+   entries from its output, and `Read` those files.
+3. If the extractor reports `imageCount === 0`, do not invent content. Emit `STATUS: NO_IMAGE` and
+   hand back to the caller.
+
+Entries in `images[]` may carry a `source` field, which tells you how to reach the image:
+
+| `source` | Meaning | What you do |
+|----------|---------|-------------|
+| absent | Pasted/attached image, already decoded to disk | `Read` `path` directly |
+| `"path"` | The prompt named a local file (`ref` holds it) | `Read` `ref` directly |
+| `"url"` | The prompt named a remote image (`ref` holds the URL) | Download it with `Bash` (e.g. `curl -sL -o /tmp/<sha>.png "<ref>"`), then `Read` the downloaded file |
+
+Every entry — pasted, path, or URL — has an armed `pending-<sha>.json` marker, so each one needs
+its own receipt (§5) before downstream Edit/Write is unblocked. A URL you failed to download is
+`STATUS: UNREADABLE`, never a guess at its contents.
+
+## 4. Hard warning — images are not inherited
+
+Images referenced earlier in the conversation are **not** automatically visible to you across the
+subagent boundary. A description of an image is not the image. The only way to see an image is to
+`Read` a real file path yourself. Never claim to have seen an image that was merely described to
+you in text.
+
+## 5. Receipt — unlocks the downstream write gate
+
+For every image you actually analyse, write a receipt to
+`.ukit/storage/cache/vision/<sessionId>/analyzed-<sha>.json`:
+
+```json
+{ "sha": "<64hex>", "model": "unic-vision", "ts": 1785656920891,
+  "description": "...", "textContent": "...", "status": "OK" }
+```
+
+- `sha` and `sessionId` come from the extractor's `--json` output. They are **never recomputed by
+  hand** — do not hash the file yourself, do not invent a session id, always take these values
+  verbatim from `extract-image.mjs --json`.
+- `model` must be the model you actually ran on for this analysis. Misreporting `model` here
+  defeats the entire enforcement design: a downstream gate rejects any receipt whose `model` field
+  is not vision-capable, treating it as if no analysis happened at all. Report honestly, always.
+- Use `Bash` to write the receipt file.
+
+## 6. Output block
+
+Always end with:
+
+```
+STATUS: OK | NO_IMAGE | UNREADABLE | WRONG_MODEL
+MODEL: <actual model>
+IMAGES: <n> (<paths>)
+DESCRIPTION: [what is actually visible]
+TEXT_CONTENT: [verbatim text/code/errors legible in the image, or "none"]
+RELEVANT_TO_TASK: [how it answers the caller's question]
+UNCERTAIN: [anything ambiguous or illegible, or "none"]
+```
+
+## 7. Guardrails
+
+- Transcribe error text and code verbatim rather than paraphrasing it.
+- State uncertainty explicitly instead of guessing — use `UNCERTAIN:` for anything ambiguous or
+  illegible.
+- Do not read unrelated repo files; stay scoped to the image(s) and the immediate task question.
+- Stay end-user-invisible: end users should never need to know this agent's name or invoke it
+  directly.

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

@@ -32,12 +32,16 @@ function block(message) {
 
 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 '';
@@ -74,6 +78,9 @@ if (toolName === 'Write' || toolName === 'Edit') {
     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).`);
     }
@@ -97,6 +104,9 @@ if (toolName === 'Write' || toolName === 'Edit') {
       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.`);
       }
@@ -108,6 +118,9 @@ if (toolName === 'Write' || toolName === 'Edit') {
       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).`);
       }

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 $?