@ngockhoale/ukit 2.2.14 → 2.2.16

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.16 - 2026-09-06
+
+The vision gate is gone — image work is advisory-routed, never blocked. Since TASK-008, a
+pasted image on the UNIC gateway armed `vision-gate.sh`, which refused every Edit/Write until
+`ukit-vision-analyst` had produced receipts for ALL pending images. In practice this
+repeatedly stranded sessions (receipts that never landed, one stale marker blocking
+unrelated writes), so the maintainer retired the hard block: `vision-gate.sh` and its
+manifest entry `hook-vision-gate` are removed from both the live tree and templates, the omp
+bridge and `hook-chain-runner.mjs` no longer list it, and `vision-router.sh` now says "never
+guess at image contents" instead of claiming edits are GATED. Routing to
+`ukit-vision-analyst` still happens — on this gateway the main tier genuinely cannot read
+images — but nothing blocks while it runs. Supersedes the 2.2.15 escape hatch, which patched
+a message on a gate that no longer exists. Verified: vision-hook, route-vision,
+vision-agent, install-wiring, provision-worktree, and ompHookBridge (52/52) all green.
+(An interim 2026-09-05 patch that added an escape hatch to the block message is included
+here and immediately superseded — the gate itself no longer exists.)
+
 ## 2.2.14 - 2026-09-05
 
 The context hard-cap gate no longer bricks healthy sessions with a phantom token count. The

package/manifests/platform.full.yaml

@@ -1131,19 +1131,6 @@ items:
     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-context-hardcap-gate
     type: hook
     sourceTemplate: .claude/hooks/context-hardcap-gate.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.14",
+  "version": "2.2.16",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -177,8 +177,8 @@ function readRunCursor() {
   process.stderr.write(`${lines.join('\n')}\n`);
   process.exit(2);
 })().catch((err) => {
-  // Unlike vision-gate.sh, a logic error here fails OPEN: this is a backstop on top of
-  // advisory nudges, not a correctness gate — a broken gate must not brick every session.
+  // A logic error here fails OPEN: this is a backstop on top of advisory nudges,
+  // not a correctness gate — a broken gate must not brick every session.
   process.stderr.write(`context-hardcap-gate: internal error, failing open: ${err?.message ?? err}\n`);
   process.exit(0);
 });

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

@@ -1,11 +1,10 @@
 #!/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.
+# UserPromptSubmit hook: detect image input (pasted / local path / URL) and mark it for
+# the vision analyst 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.
+# no markers" and exit 0. Advisory only — nothing is ever blocked.
 #
 # Detection only — never decodes an image, never writes an image file. Marker
 # writing is delegated entirely to `extract-image.mjs --mark-pending`; this hook
@@ -44,7 +43,7 @@ const { pathToFileURL } = require('url');
 
   const promptText = extractPromptText(payload);
 
-  // Tri-state, same contract as vision-gate.sh: true | false | null(unknown).
+  // Tri-state: true | false | null(unknown). Only a positive false short-circuits.
   async function detectUnicModeSafe() {
     try {
       const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
@@ -118,14 +117,12 @@ const { pathToFileURL } = require('url');
     }
   }
 
-  // `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.
+  // `cases` reflects what the PROMPT mentioned. Named paths that do not resolve from
+  // the project root still get the unresolved-path note below.
   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);
@@ -135,8 +132,7 @@ const { pathToFileURL } = require('url');
   // 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 —
-  // which the gate is entitled to reject, and which defeats the point of having a gate.
+  // ran on, so telling it to claim some other ID is asking it to falsify the receipt.
   let unicNote = '';
   if (unicMode === true) {
     try {
@@ -151,9 +147,7 @@ const { pathToFileURL } = require('url');
     }
   }
 
-  const reasonLine = 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:';
+  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]';
 
   const lines = [

package/templates/.claude/settings.json

@@ -84,11 +84,6 @@
             "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
-          },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\"",

package/templates/.claude/ukit/index/provision-worktree.mjs

@@ -7,7 +7,7 @@
  *   - .claude/      -> REAL COPY preserving file modes (never a symlink: a worktree
  *                      edit must not write through into the live main-tree mirror).
  *                      Mode preservation matters: every .claude/hooks/*.sh is 755 and
- *                      tests/handoff/cycle4/vision-gate.test.mjs asserts the exec bit.
+ *                      tests/handoff/cycle7/provision-worktree.test.mjs asserts the exec bit.
  *   - .ukit/storage/config.json -> copy
  *   - .cache/index/             -> copy
  *

package/templates/.claude/ukit/index/unic-gateway.mjs

@@ -22,7 +22,7 @@
  * Every probe here is scoped to what changes the CALLING
  * runtime's OWN outbound endpoint — same rule that already governs probes 1-3. Cross-tool
  * configs are NOT probed. This module is only ever invoked from Claude Code / omp hooks
- * (vision-router.sh, vision-gate.sh, route-task.mjs, and the omp bridge) to gate what THIS
+ * (vision-router.sh, route-task.mjs, and the omp bridge) to gate what THIS
  * session does — a Codex `config.toml` `base_url`, a Kilo `secrets.json` endpoint, or an
  * `OPENAI_BASE_URL` env var describe a completely different tool's outbound endpoint and say
  * nothing about where Claude Code or omp itself is sending requests. Treating them as evidence

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

@@ -8,7 +8,6 @@ const FAIL_CLOSED_SCRIPTS = new Set([
   'protect-files.sh',
   'stale-spec-guard.sh',
   'handoff-model-guard.sh',
-  'vision-gate.sh',
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
 ]);

package/templates/.omp/README.md

@@ -62,14 +62,14 @@ One source of truth, two runtimes — fix a hook once and both runtimes get the
 Two things worth knowing:
 
 **Tool names are mapped explicitly, never guessed.** omp's write surface is `edit`, `write` *and*
-`ast_edit`; all three map to the `Edit` group, or `ast_edit` would slip past `protect-files.sh` and
-`vision-gate.sh`. `eval` maps to `Bash` so it still hits `block-dangerous.sh`. Anything not in the
+`ast_edit`; all three map to the `Edit` group, or `ast_edit` would slip past `protect-files.sh`.
+`eval` maps to `Bash` so it still hits `block-dangerous.sh`. Anything not in the
 table maps to nothing and runs zero scripts — it never falls back to `Bash` or `Edit`.
 
 **Failure direction is per-script, transcribed from each script's own header — not a blanket rule.**
 
 - *Fail closed* (a crash or non-zero exit blocks the action): `protect-files.sh`,
-  `stale-spec-guard.sh`, `handoff-model-guard.sh`, `vision-gate.sh`, `context-hardcap-gate.sh`,
+  `stale-spec-guard.sh`, `handoff-model-guard.sh`, `context-hardcap-gate.sh`,
   `block-dangerous.sh`, `verification-guard.sh`. These are gates; a broken gate must not open.
 - *Fail open* (a crash logs a warning and the action proceeds): the advisory scripts —
   routing, backups, output compression, context reinjection, pressure reset, handoff resume.

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

@@ -27,7 +27,6 @@ export const HOOK_EVENT_MAP = {
       'pre-edit-backup.sh',
       'skill-router.sh',
       'handoff-model-guard.sh',
-      'vision-gate.sh',
       'context-hardcap-gate.sh',
     ],
     Bash: [
@@ -83,7 +82,6 @@ export const FAIL_CLOSED_SCRIPTS = new Set([
   'protect-files.sh',
   'stale-spec-guard.sh',
   'handoff-model-guard.sh',
-  'vision-gate.sh',
   'context-hardcap-gate.sh',
   'block-dangerous.sh',
 ]);

package/templates/CLAUDE.md

@@ -209,7 +209,7 @@ This is internal orchestration — end users do not need to know about tiers, th
 `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.
 
 - **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.
 
 ## Skills

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