@ngockhoale/ukit 1.6.5 → 1.6.7

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to UKit are documented here.
 
+## 1.6.7 - 2026-08-09
+
+### Fixed
+
+- **`unic-gateway.mjs` `detectUnicGateway()`** is now scoped to Claude Code's own outbound endpoint only (`process.env.ANTHROPIC_BASE_URL`, and the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`). It no longer probes Codex `config.toml`, Kilo `secrets.json`, or `OPENAI_BASE_URL` — those describe a different tool's endpoint and were producing permanent false positives (`unicMode: true` for a plain Claude Code session whenever some other tool on the machine happened to be pointed at the UNIC gateway), which would deadlock Edit/Write on any image-mentioning turn under the vision gate.
+- **`vision-router.sh`** no longer always tells the caller to invoke `Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]`. `unic-vision` is only an invokable model when the UNIC gateway is actually active for this session; the remedy message now branches on `detectUnicGateway()`'s `unicMode`: gateway active keeps today's `unic-vision` text, gateway inactive with a readable `orchestration.modelTiers.vision.fallbackModel` (read from `.ukit/storage/config.json`, the same path `vision-gate.sh` uses) tells the caller to override the model to that fallback and to self-report it in the analyst's receipt, and any missing/broken detection falls back to the strict `unic-vision` text as before. The hook's fail-open contract (never blocks the prompt, always exit 0) is unchanged.
+- **`handoff-model-guard.sh`** no longer re-blocks `git push` forever over a closed, human-approved model-tier exception (a documented `## Model-Tier Guard Override` section with `OVERRIDE_APPROVED_BY: human` now exempts that task from the push-time reviewer/executor tier scan).
+
+## 1.6.6 - 2026-08-03
+
+### Fixed
+
+- **`ensureGitignore`** no longer silently no-ops on a damaged UKit block (missing/duplicate end marker). Marker detection is now a single source of truth (`parseGitignore` + `locateBlock`, exact-line matching, shared with `removeGitignoreBlock`), fixing data loss on substring-collision lines, content between two legitimate blocks, and CRLF round-tripping, while staying idempotent.
+- **Install summary counts** no longer go negative or misattribute a skip. `applyDiffResults` now tracks skips per planned action (`create`/`update`), and `runInstallPipeline` subtracts each skip from its own bucket instead of always assuming `update`.
+- **Runtime config default version** is now read from `package.json` instead of a hardcoded, drifting literal (was stuck at `1.5.2`).
+- **`mergeObjects` (runtime config)** now refuses `__proto__`, `constructor`, and `prototype` keys at every merge depth, closing a prototype-pollution path via a hand-edited `.ukit/storage/config.json`.
+- **`buildInstallPlan`** no longer aborts the entire install when a template is missing for a *non-selected/excluded* item — it skips quietly. A missing template for a *selected* item still fails loudly with a clear error.
+- **`uninstallUkit`** now reports out-of-scope/forged tracked paths on real runs, not only `--dry-run`, while routine link-child paths stay silent.
+
 ## 1.6.5 - 2026-08-02
 
 ### Added

package/package.json

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

package/src/core/applyPlan.js

@@ -15,6 +15,7 @@ function isTccProtectedPath(filePath) {
 export async function applyDiffResults(diffResults, { backupRoot, projectRoot } = {}) {
   const writes = [];
   let skippedUpdates = 0;
+  const skippedByAction = { create: 0, update: 0 };
 
   for (const entry of diffResults) {
     if (entry.action !== 'create' && entry.action !== 'update') {
@@ -36,6 +37,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
             `[UKit] Warning: skipping link update for ${entry.targetPath} — exists as a ${existingKind} (possible user content). Remove it manually if intended.`,
           );
           skippedUpdates += 1;
+          skippedByAction[entry.action] += 1;
           continue;
         }
       }
@@ -47,6 +49,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
             `[UKit] Warning: skipping link creation for ${entry.targetPath} — permission denied. Run 'ukit install' from within the target tool to create it.`,
           );
           skippedUpdates += 1;
+          skippedByAction[entry.action] += 1;
           continue;
         }
         throw linkError;
@@ -78,6 +81,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
             `[UKit] Warning: skipping backup for ${entry.targetPath} — permission denied.`,
           );
           skippedUpdates += 1;
+          skippedByAction.update += 1;
           continue;
         }
         throw backupError;
@@ -111,6 +115,7 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           `[UKit] Warning: skipping write for ${entry.targetPath} — permission denied (macOS TCC). Run 'ukit install' from within the owning tool to update it.`,
         );
         skippedUpdates += 1;
+        skippedByAction[entry.action] += 1;
         continue;
       }
       throw writeError;
@@ -126,5 +131,5 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
     });
   }
 
-  return { writes, skippedUpdates };
+  return { writes, skippedUpdates, skippedByAction };
 }

package/src/core/buildPlan.js

@@ -101,7 +101,17 @@ export async function buildInstallPlan({
   for (const item of manifest.items) {
     if (!selectedIds.has(item.id) && item.type !== 'link') {
       const sourcePath = safeResolve(templatesRoot, item.sourceTemplate);
-      const stat = await fs.stat(sourcePath);
+      let stat;
+      try {
+        stat = await fs.stat(sourcePath);
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          // An excluded item only contributes an auto-discovery filter, so a
+          // missing source for a pack the user does not have is harmless.
+          continue;
+        }
+        throw error;
+      }
       const sourceDir = (stat.isDirectory() ? sourcePath : path.dirname(sourcePath)) + path.sep;
       excludedSourceDirs.push(sourceDir);
     }
@@ -145,7 +155,11 @@ export async function buildInstallPlan({
           });
           continue;
         }
-        throw error;
+        throw new Error(
+          `Cannot install manifest item "${item.id}": missing or unreadable template `
+            + `"${item.sourceTemplate}".`,
+          { cause: error },
+        );
       }
       if (stat.isDirectory()) {
         const nestedFiles = await walkDirectory(sourcePath);

package/src/core/ensureGitignore.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { escapeRegExp, writeFileAtomic } from './fileOps.js';
+import { writeFileAtomic } from './fileOps.js';
 
 const UKIT_ENTRIES = [
   '.cache/',
@@ -20,6 +20,76 @@ const UKIT_ENTRIES = [
 const MARKER_START = '# UKit generated (do not edit)';
 const MARKER_END = '# /UKit';
 
+/*
+ * Single source of truth for "where is the UKit block in this file".
+ *
+ * Both `ensureGitignore` and `removeGitignoreBlock` go through `parseGitignore`
+ * + `locateBlock`. There is deliberately NO regex/substring notion of a marker
+ * anywhere else in this module — historically the fast path used a substring
+ * regex, the repair path used `line === MARKER`, and the entry guard used
+ * `content.includes(...)`; those three disagreed and silently deleted user
+ * lines that merely *contained* marker-like text.
+ *
+ * Documented behaviour:
+ *  - A marker is ONLY a line that, after stripping a trailing `\r`, is exactly
+ *    equal to MARKER_START / MARKER_END. `# UKit generated (do not edit) v2`
+ *    or a marker with a trailing space is ordinary user content, everywhere.
+ *  - Line endings: the file's *dominant* ending wins (CRLF only if CRLF pairs
+ *    outnumber bare LFs; ties go to LF). A file is only ever rewritten when its
+ *    content actually changes, and a rewrite normalises the whole file to that
+ *    dominant ending — so a mixed-ending file converges after one normalising
+ *    write.
+ *  - Only the FIRST block is managed. Any further marker lines are treated as
+ *    user content so a second, legitimate block — and every user line between
+ *    the two — is never touched.
+ */
+
+/**
+ * Detect the dominant line ending and split into `\r`-free lines.
+ * @param {string} content
+ * @returns {{ eol: string, lines: string[] }}
+ */
+function parseGitignore(content) {
+  const crlfCount = (content.match(/\r\n/g) ?? []).length;
+  const lfCount = (content.match(/\n/g) ?? []).length;
+  const bareLfCount = lfCount - crlfCount;
+  const eol = crlfCount > bareLfCount ? '\r\n' : '\n';
+  const lines = content
+    .split('\n')
+    .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+  return { eol, lines };
+}
+
+/**
+ * Locate the first UKit block at or after `from`, using exact-line equality only.
+ *
+ * The block spans `[startIdx, endIdx]` inclusive. The search for the closing
+ * marker is bounded by the NEXT start marker, so an excision can never run past
+ * a second block. If no end marker exists inside that bound the block is
+ * "unterminated" and ends just before the next start marker (or at EOF).
+ *
+ * @param {string[]} lines `\r`-free lines from {@link parseGitignore}
+ * @param {number} [from]
+ * @returns {{ startIdx: number, endIdx: number, terminated: boolean } | null}
+ */
+function locateBlock(lines, from = 0) {
+  const startIdx = lines.indexOf(MARKER_START, from);
+  if (startIdx === -1) return null;
+
+  const next = lines.indexOf(MARKER_START, startIdx + 1);
+  const bound = next === -1 ? lines.length : next;
+
+  // Last end marker *within the bound* — consumes stray/duplicate end markers
+  // that belong to this damaged block without reaching into the next one.
+  let endIdx = -1;
+  for (let i = startIdx + 1; i < bound; i += 1) {
+    if (lines[i] === MARKER_END) endIdx = i;
+  }
+
+  const terminated = endIdx !== -1;
+  return { startIdx, endIdx: terminated ? endIdx : bound - 1, terminated };
+}
+
 export async function ensureGitignore(projectRoot) {
   const gitignorePath = path.join(projectRoot, '.gitignore');
 
@@ -30,48 +100,60 @@ export async function ensureGitignore(projectRoot) {
     // no .gitignore yet
   }
 
-  const newBlock = [
-    MARKER_START,
-    ...UKIT_ENTRIES,
-    MARKER_END,
-  ].join('\n');
-
-  if (content.includes(MARKER_START)) {
-    // Replace existing UKit block with current entries
-    const blockPattern = new RegExp(
-      `${escapeRegExp(MARKER_START)}[\\s\\S]*?${escapeRegExp(MARKER_END)}`,
-    );
-    const existingBlock = content.match(blockPattern)?.[0];
-    if (existingBlock === newBlock) {
-      return false; // already up to date
+  const { eol, lines } = parseGitignore(content);
+  const blockLines = [MARKER_START, ...UKIT_ENTRIES, MARKER_END];
+  const block = locateBlock(lines);
+
+  let nextLines;
+  if (block) {
+    // Splice the canonical block over the located one, in place. Well-formed,
+    // unterminated and stray-end-marker blocks all take this one path — a
+    // well-formed, current block simply splices to identical content and is
+    // caught by the `next === content` no-op check below, which is what makes
+    // repeated calls converge.
+    nextLines = [
+      ...lines.slice(0, block.startIdx),
+      ...blockLines,
+      ...lines.slice(block.endIdx + 1),
+    ];
+  } else {
+    // No marker block — check if entries are already present as active
+    // (non-comment) lines. Must filter out comment lines to avoid
+    // false-negatives like "# placeholder .claude/ukit/.ukit/" matching the
+    // entry check and incorrectly skipping the block insertion.
+    const activeLines = lines
+      .map((l) => l.trim())
+      .filter((trimmed) => trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!'));
+    const missing = UKIT_ENTRIES.filter((e) => !activeLines.some((l) => l === e));
+    if (missing.length === 0) {
+      return false;
     }
-    const updated = content.replace(blockPattern, newBlock);
-    await writeFileAtomic(gitignorePath, updated);
-    return true;
-  }
 
-  // No marker block — check if entries are already present as active (non-comment) lines.
-  // Must filter out comment lines to avoid false-negatives like "# placeholder .claude/ukit/.ukit/"
-  // matching the entry check and incorrectly skipping the block insertion.
-  const activeLines = content
-    .split('\n')
-    .map((l) => l.trim())
-    .filter((trimmed) => trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!'));
-  const missing = UKIT_ENTRIES.filter((e) => !activeLines.some((l) => l === e));
-  if (missing.length === 0) {
-    return false;
+    // Append the marker block after the existing content.
+    const head = [...lines];
+    while (head.length > 0 && head[head.length - 1].trim() === '') head.pop();
+    nextLines = head.length > 0
+      ? [...head, '', ...blockLines, '']
+      : [...blockLines, ''];
   }
 
-  // Append marker block with missing entries
-  const block = ['', newBlock, ''].join('\n');
-  await writeFileAtomic(gitignorePath, content.trimEnd() + '\n' + block);
+  const next = nextLines.join(eol);
+  if (next === content) {
+    return false; // already up to date
+  }
+  await writeFileAtomic(gitignorePath, next);
   return true;
 }
 
 /**
- * Remove the UKit-managed block from .gitignore.
+ * Remove the UKit-managed block(s) from .gitignore.
  * Called by uninstall to leave the project in a clean state.
- * @returns {boolean} true if the block was found and removed
+ *
+ * Uses the same detection helpers as `ensureGitignore`, so anything
+ * `ensureGitignore` can write (including a CRLF-joined block) is removable, and
+ * a line that merely contains marker-like text is never matched.
+ *
+ * @returns {boolean} true if a block was found and removed
  */
 export async function removeGitignoreBlock(projectRoot) {
   const gitignorePath = path.join(projectRoot, '.gitignore');
@@ -83,35 +165,29 @@ export async function removeGitignoreBlock(projectRoot) {
     return false; // no .gitignore — nothing to remove
   }
 
-  if (!content.includes(MARKER_START)) {
-    return false; // no UKit block present
+  const { eol, lines } = parseGitignore(content);
+
+  let result = lines;
+  let cursor = 0;
+  let removed = false;
+  for (;;) {
+    const block = locateBlock(result, cursor);
+    if (!block) break;
+    removed = true;
+
+    // Drop the blank separator line that ensureGitignore prepended.
+    let from = block.startIdx;
+    if (from > 0 && result[from - 1] === '') from -= 1;
+
+    result = [...result.slice(0, from), ...result.slice(block.endIdx + 1)];
+    cursor = from;
   }
 
-  // Walk lines and excise the block plus any leading blank line that
-  // ensureGitignore appended before the marker.
-  const lines = content.split('\n');
-  const result = [];
-  let inBlock = false;
-
-  for (const line of lines) {
-    if (line === MARKER_START) {
-      inBlock = true;
-      // Remove the blank separator line that ensureGitignore prepended.
-      if (result.length > 0 && result[result.length - 1] === '') {
-        result.pop();
-      }
-      continue;
-    }
-    if (inBlock) {
-      if (line === MARKER_END) {
-        inBlock = false;
-      }
-      continue;
-    }
-    result.push(line);
+  if (!removed) {
+    return false; // no UKit block present
   }
 
-  const joined = result.join('\n').trimEnd();
-  await writeFileAtomic(gitignorePath, joined ? joined + '\n' : '');
+  const joined = result.join(eol).trimEnd();
+  await writeFileAtomic(gitignorePath, joined ? joined + eol : '');
   return true;
 }

package/src/core/runInstallPipeline.js

@@ -53,6 +53,19 @@ function buildTrackedManagedRelativePathSet(plan, projectRoot) {
   );
 }
 
+export function adjustSummaryForSkips(plannedSummary, skippedByAction, skippedUpdates) {
+  if (!skippedUpdates) {
+    return plannedSummary;
+  }
+
+  return {
+    ...plannedSummary,
+    create: plannedSummary.create - (skippedByAction?.create ?? 0),
+    update: plannedSummary.update - (skippedByAction?.update ?? 0),
+    skip: plannedSummary.skip + skippedUpdates,
+  };
+}
+
 function shouldAutoPruneObsoletePath(relativePath) {
   return AUTO_PRUNE_OBSOLETE_PATHS.has(relativePath)
     || AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
@@ -271,7 +284,7 @@ export async function runInstallPipeline({
   const plannedSummary = summarizeDiff(diffResults);
 
   if (!dryRun) {
-    const { writes, skippedUpdates } = await applyDiffResults(diffResults, {
+    const { writes, skippedUpdates, skippedByAction } = await applyDiffResults(diffResults, {
       backupRoot: pathConfig.backupRoot,
       projectRoot: pathConfig.projectRoot,
     });
@@ -291,16 +304,11 @@ export async function runInstallPipeline({
       managedLinkRelativePaths,
     });
 
-    // Adjust summary to reflect link updates that were skipped for safety
-    // (the planned diff counted them as 'update', but apply skipped them).
-    const summary =
-      skippedUpdates > 0
-        ? {
-            ...plannedSummary,
-            update: plannedSummary.update - skippedUpdates,
-            skip: plannedSummary.skip + skippedUpdates,
-          }
-        : plannedSummary;
+    // Adjust summary to reflect entries that were skipped for safety
+    // (the planned diff counted them as 'create'/'update', but apply skipped them).
+    // Subtract from the bucket the skipped entry was actually planned as, so the
+    // adjusted counts never go negative.
+    const summary = adjustSummaryForSkips(plannedSummary, skippedByAction, skippedUpdates);
 
     await writeInstallMetadata({
       installMetaPath: pathConfig.installMetaPath,

package/src/core/runtimeConfig.js

@@ -1,9 +1,15 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { buildRuntimePaths } from './runtimePaths.js';
 
+const require = createRequire(import.meta.url);
+const { version: PACKAGE_VERSION } = require('../../package.json');
+
 const VALID_AGENTS = new Set(['claude-code', 'codex', 'antigravity', 'opencode']);
 
+const BLOCKED_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
 function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -15,6 +21,10 @@ function mergeObjects(base, override) {
 
   const merged = { ...base };
   for (const [key, value] of Object.entries(override)) {
+    if (BLOCKED_MERGE_KEYS.has(key)) {
+      continue;
+    }
+
     const current = merged[key];
     if (isPlainObject(current) && isPlainObject(value)) {
       merged[key] = mergeObjects(current, value);
@@ -49,7 +59,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.5.2',
+    version: PACKAGE_VERSION,
     agent: 'claude-code',
     autonomy: {
       level: 'balanced',

package/src/core/uninstall.js

@@ -124,7 +124,12 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     regularPaths = [stateDir]; // always delete state dir — it's always UKit-owned
     linkPaths = [];
 
-    const skipped = [];
+    // Two arrays for two unrelated meanings: invalidPaths are suspicious (forged
+    // or corrupt metadata pointing outside managed prefixes) and always worth a
+    // warning; linkChildPaths are routine (a tracked file under a tracked link
+    // that gets removed along with its parent) and must never warn.
+    const invalidPaths = [];
+    const linkChildPaths = [];
     const trackedEntries = [];
 
     for (const entry of installData.files) {
@@ -137,7 +142,7 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
 
       const normalizedRelative = normalizeToProjectRelative(projectRoot, absolutePath);
       if (!isAllowedProjectPath(normalizedRelative)) {
-        skipped.push(relPath ?? normalizedRelative ?? absolutePath);
+        invalidPaths.push(relPath ?? normalizedRelative ?? absolutePath);
         continue;
       }
 
@@ -159,15 +164,15 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
       );
 
       if (isUnderTrackedLinkPath) {
-        skipped.push(entry.normalizedRelative);
+        linkChildPaths.push(entry.normalizedRelative);
         continue;
       }
 
       regularPaths.push(entry.absolutePath);
     }
 
-    if (skipped.length > 0 && dryRun) {
-      console.warn('[UKit] Skipping invalid uninstall paths from install metadata:', skipped);
+    if (invalidPaths.length > 0) {
+      console.warn('[UKit] Skipping invalid uninstall paths from install metadata:', invalidPaths);
     }
   } else {
     // Old format (no files list): fall back to hardcoded managed paths.

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

@@ -151,6 +151,12 @@ if (toolName === 'Bash') {
     const text = fs.readFileSync(taskPath, 'utf8');
     if (!text.includes('## Reviewer Verdict')) continue; // not yet reviewed, not this push's concern
 
+    // A documented, human-approved exception (e.g. an opus-tier executor escalation left no
+    // second opus identity free to review it) is a closed, one-time decision — it must not
+    // re-block every future unrelated push forever just because the task file still contains
+    // the exempted model string.
+    if (/## Model-Tier Guard Override/.test(text) && /OVERRIDE_APPROVED_BY:\s*human/i.test(text)) continue;
+
     const executorModel = extractField(text, 'EXECUTOR_MODEL');
     const reviewerModel = extractField(text, 'REVIEWER_MODEL');
 

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

@@ -105,8 +105,17 @@ const { pathToFileURL } = require('url');
     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.
+  // TASK-008: branch the remedy on whether unic-vision is actually invokable for THIS
+  // session. `remedyMode` is tri-state and defaults to the strict/fail-safe variant:
+  //   'gateway'  — unicMode true: today's `unic-vision` text (unchanged).
+  //   'fallback' — unicMode false + a readable orchestration.modelTiers.vision.fallbackModel
+  //                (same config path vision-gate.sh reads, so the advertised model and the
+  //                accepted model never drift): tell the caller to override the model.
+  //   'strict'   — gateway module missing/broken, or unicMode false but fallbackModel is
+  //                unreadable: today's `unic-vision` text (fail-safe default).
+  // Never fatal — any error in this block falls back to 'strict' and no note.
+  let remedyMode = 'strict';
+  let fallbackModel = null;
   let unicNote = '';
   try {
     const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
@@ -115,25 +124,51 @@ const { pathToFileURL } = require('url');
       if (typeof mod.detectUnicGateway === 'function') {
         const result = mod.detectUnicGateway({ rootDir: projectRoot });
         if (result?.unicMode) {
+          remedyMode = 'gateway';
           unicNote = `  (UNIC gateway active — ${result.visionModel} routes through it.)`;
+        } else {
+          const configPath = path.join(projectRoot, '.ukit', 'storage', 'config.json');
+          const configRaw = fs.readFileSync(configPath, 'utf8');
+          const config = JSON.parse(configRaw);
+          const candidate = config?.orchestration?.modelTiers?.vision?.fallbackModel;
+          if (typeof candidate === 'string' && candidate.trim()) {
+            fallbackModel = candidate.trim();
+            remedyMode = 'fallback';
+          }
         }
       }
     }
   } catch {
+    remedyMode = 'strict';
+    fallbackModel = null;
     unicNote = '';
   }
 
+  const isFallback = remedyMode === 'fallback';
+  const reasonLine = isFallback
+    ? (armed > 0
+        ? 'Edit/Write is now GATED until a vision analysis exists. Do this before anything else:'
+        : 'Do this before anything else:')
+    : (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 agentLine = isFallback
+    ? `  2. Agent(subagent_type: "ukit-vision-analyst", model: "${fallbackModel}")`
+    : '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]';
+
   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:',
+    reasonLine,
     '  1. node .claude/ukit/index/extract-image.mjs --json',
-    '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
+    agentLine,
     '     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 (isFallback) {
+    lines.push(`     The analyst must self-report "model": "${fallbackModel}" in its receipt —`);
+    lines.push('     otherwise the gate will reject it.');
+  }
+  lines.push('  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.');

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

@@ -1,39 +1,29 @@
 #!/usr/bin/env node
 /**
- * unic-gateway.mjs (TASK-003)
+ * unic-gateway.mjs (TASK-003, narrowed by TASK-007)
  *
- * Detects whether any locally configured AI tool (Claude Code, Codex, or Kilo Code) is pointed at
- * the UNIC gateway — i.e. its base URL contains "unicjsc.com". Per the user's rule, a hit in ANY
- * tool activates UNIC routing (`unicMode: true`), so the vision lane can pin `unic-vision` when it
- * is available in the Codex model catalog, and fall back safely when it is not.
+ * Detects whether THIS Claude Code session's own outbound endpoint is pointed at the UNIC gateway
+ * — i.e. `ANTHROPIC_BASE_URL` contains "unicjsc.com" — so the vision lane can pin `unic-vision`
+ * when it is available in the Codex model catalog, and fall back safely when it is not.
  *
  * Self-contained: reads only env vars and local files. Does NOT read `.ukit/storage/config.json`,
  * so it has no dependency on TASK-001 and stays usable in Wave 1.
  *
  * Probe order (first hit sets `source`; every hit is recorded in `sources`):
- *   1. process.env.ANTHROPIC_BASE_URL           -> 'env'
- *   2. process.env.OPENAI_BASE_URL              -> 'env'
- *   3. project .claude/settings.json -> env     -> 'claude-settings'
- *   4. ~/.claude/settings.json -> env            -> 'claude-settings'
- *   5. project .codex/config.toml                -> 'codex'
- *   6. ~/.codex/config.toml                       -> 'codex'
- *   7. ~/.kilocode/secrets.json (presence only)   -> 'kilo'
+ *   1. process.env.ANTHROPIC_BASE_URL                        -> 'env'
+ *   2. project .claude/settings.json -> env.ANTHROPIC_BASE_URL -> 'claude-settings'
+ *   3. ~/.claude/settings.json -> env.ANTHROPIC_BASE_URL       -> 'claude-settings'
  *
- * SECURITY (non-negotiable): `~/.kilocode/secrets.json` is a real secrets file. This module only
- * ever tests it for substring presence of "unicjsc.com", then lets the buffer fall out of scope.
- * It never logs, returns, echoes, or otherwise embeds that file's contents anywhere — including in
- * error messages. Nothing derived from that file may appear in this module's output beyond the
- * literal source label "kilo".
- *
- * TOML (deliberate trade-off): no TOML parser dependency is added — repo `dependencies` is
- * `{"yaml":"^2.8.2"}` only, and adding a parser for one `base_url` line fails Simplicity First.
- * Codex config.toml is scanned with a narrow anchored regex that looks for a `base_url = "..."`
- * assignment containing "unicjsc.com" on a single line. It does not attempt real TOML parsing, so
- * exotic quoting/escaping (multi-line strings, unusual escapes) will not match. That degrades to
- * "no hit" (`unicMode: false`), which fails safe rather than throwing or false-negatively passing.
+ * Cross-tool configs are NOT probed. This module is only ever invoked from Claude Code hooks
+ * (vision-router.sh, vision-gate.sh, route-task.mjs) 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 itself is sending requests. Treating them as evidence produced permanent false positives
+ * (any machine with Codex/Kilo pointed at the UNIC gateway would report `unicMode: true` for
+ * every plain Claude Code session, deadlocking Edit/Write on any image-mentioning turn).
  *
  * Contract: this module must NEVER throw and must NEVER exit non-zero, in any case (missing files,
- * malformed JSON/TOML, unreadable paths, etc. all degrade to a clean "no hit").
+ * malformed JSON, unreadable paths, etc. all degrade to a clean "no hit").
  *
  * Test overrides: pass { rootDir, homeDir } directly to detectUnicGateway(), or set the env vars
  * UKIT_TEST_ROOT / UKIT_TEST_HOME (used only when explicit options are not supplied) so tests never
@@ -48,10 +38,6 @@ import { fileURLToPath } from 'node:url';
 const UNIC_TOKEN = 'unicjsc.com';
 const VISION_MODEL_ALIAS = 'unic-vision';
 
-// Narrow, anchored: a `base_url` key assignment whose quoted value contains the UNIC token.
-// See file header "TOML" note for why this is a regex and not a real parser.
-const CODEX_BASE_URL_UNIC_RE = /\bbase_url\s*=\s*(["'])(?:(?!\1)[^\r\n])*unicjsc\.com(?:(?!\1)[^\r\n])*\1/i;
-
 function safeReadFile(filePath) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -87,35 +73,15 @@ function probeEnvVar(name) {
   return typeof value === 'string' && value.includes(UNIC_TOKEN);
 }
 
+// Key-scoped: only the ANTHROPIC_BASE_URL entry of the env block decides Claude Code's own
+// gateway state. A different key (e.g. OPENAI_BASE_URL) parked in the same env block describes
+// some other tool's endpoint and must NOT trip this probe.
 function probeClaudeSettings(filePath) {
   const json = safeReadJson(filePath);
   const envBlock = json && typeof json === 'object' ? json.env : null;
   if (!envBlock || typeof envBlock !== 'object') return false;
-  return Object.values(envBlock).some(
-    (value) => typeof value === 'string' && value.includes(UNIC_TOKEN),
-  );
-}
-
-function probeCodexConfig(filePath) {
-  const raw = safeReadFile(filePath);
-  if (raw == null) return false;
-  return CODEX_BASE_URL_UNIC_RE.test(raw);
-}
-
-/**
- * Presence-only check against a secrets file. Reads the file once, tests for the substring, and
- * returns a boolean. The raw content is never retained, logged, or returned — it falls out of
- * scope as soon as this function returns. A read failure (missing file, permission error, etc.)
- * is swallowed and treated as "no hit"; the error itself is never surfaced (it could, in theory,
- * embed a path — this function does not let it propagate at all).
- */
-function probeKiloSecretsPresence(filePath) {
-  try {
-    const raw = fs.readFileSync(filePath, 'utf8');
-    return raw.includes(UNIC_TOKEN);
-  } catch {
-    return false;
-  }
+  const value = envBlock.ANTHROPIC_BASE_URL;
+  return typeof value === 'string' && value.includes(UNIC_TOKEN);
 }
 
 /**
@@ -141,7 +107,7 @@ function checkCodexVisionAlias(catalogPath) {
 }
 
 /**
- * Runs all seven probes in the documented order and returns the output contract object. Never
+ * Runs all three probes in the documented order and returns the output contract object. Never
  * throws — any unexpected error in an individual probe is contained so the overall result still
  * reflects whatever was determined so far.
  *
@@ -158,12 +124,8 @@ export function detectUnicGateway(options = {}) {
 
   const probes = [
     () => recordHit(probeEnvVar('ANTHROPIC_BASE_URL'), 'env'),
-    () => recordHit(probeEnvVar('OPENAI_BASE_URL'), 'env'),
     () => recordHit(probeClaudeSettings(path.join(rootDir, '.claude', 'settings.json')), 'claude-settings'),
     () => recordHit(probeClaudeSettings(path.join(homeDir, '.claude', 'settings.json')), 'claude-settings'),
-    () => recordHit(probeCodexConfig(path.join(rootDir, '.codex', 'config.toml')), 'codex'),
-    () => recordHit(probeCodexConfig(path.join(homeDir, '.codex', 'config.toml')), 'codex'),
-    () => recordHit(probeKiloSecretsPresence(path.join(homeDir, '.kilocode', 'secrets.json')), 'kilo'),
   ];
   for (const probe of probes) {
     try {

package/templates/CLAUDE.md

@@ -166,7 +166,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**: seeing `unicjsc.com` in **any** tool's base URL — Claude Code env, Claude settings, Codex config, Kilo, or `OPENAI_BASE_URL` — activates UNIC routing.
+- **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 `unic-vision` 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.
 - This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.