@ngockhoale/ukit 1.6.6 → 1.6.7

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.6.6",
+  "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/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.