@ngockhoale/ukit 2.2.12 → 2.2.16

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

@@ -1,230 +0,0 @@
-#!/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;
-  }
-}
-
-// 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.
-// Only reached when unicMode is true or unknown — off-gateway sessions already exited
-// above — so `unic-vision` is the only model that can legitimately clear the gate here.
-function isVisionCapable(model) {
-  if (typeof model !== 'string' || !model.trim()) return false;
-  return /^unic-vision$/i.test(model.trim());
-}
-
-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) {
-  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)) {
-    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 unicMode = await detectUnicModeSafe();
-
-  // The gate exists because the UNIC gateway BLINDS the model: unic-code/unic-smart
-  // cannot see images there, so an unanalysed image means guessing. Off the gateway
-  // Claude reads images natively and there is nothing left to enforce.
-  //
-  // This early exit is what makes the gate satisfiable at all off-gateway. The previous
-  // design tried to cover this case by accepting a receipt whose model string equalled
-  // modelTiers.vision.fallbackModel — but the analyst's frontmatter pins `unic-vision`,
-  // so off-gateway it runs on whatever model is actually available and self-reports THAT.
-  // A hardcoded fallback ID could never match it, so no valid receipt was reachable and
-  // one pasted screenshot hard-blocked Edit/Write for the rest of the session.
-  //
-  // Only a POSITIVE false stands the gate down. null (detection failed) still enforces:
-  // breaking one gitignored file must not be a bypass.
-  if (unicMode === false) {
-    process.exit(0);
-  }
-
-  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);
-    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 $?