@liustack/modlens 3.5.1 → 3.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 3.7.0 - 2026-08-13
+
+- An image-extension path is now the skill's primary trigger. Transcript forensics on a Claude Code cli session explained why the skill loaded but never fired for a text-only model there: the harness silently swaps a pasted image for a usable `[Image: source: <path>]` line, so no failure ever pushes the model to consult its skill list, and a path in hand makes hand-rolled OCR the path of least resistance (the same model behind OpenCode, where the gateway error "model does not support image input" is loud, found and followed this skill exactly). The description now keys on what the model perceives first: any file path or URL ending in an image extension (.png, .jpg, .jpeg, .webp, .gif, .bmp, .heic) it cannot see behind is a hard trigger, with self-built OCR, PIL, and tesseract explicitly forbidden. Placeholder cues (`[Image #1]`, `[Unsupported Image]`) remain as the second tier.
+- First slice of auto mode (borrowing local harness vision, design in progress): a read-only discovery module probes the four supported harnesses without spending anything, and `doctor` grew an Auto section showing what it found. claude on PATH counts as borrowable (Anthropic's lineup is all multimodal), the codex model catalog is judged by its own `input_modalities`, pi's models-store is crossed with its stored credentials so only borrowable vision counts, and one `opencode models` listing is judged by a builtin vision-pattern table that harness metadata outranks. Results cache to `~/.modlens/auto-cache.json` (6h TTL, doctor always probes fresh). The `auto` config switch parses as a strict boolean and defaults to off; nothing routes through these results yet, so behavior with the switch off (or on) is unchanged from 3.6.0.
+
+## 3.6.0 - 2026-08-13
+
+- The skill now triggers on what a text-only model can actually see. Field testing with DeepSeek behind an Anthropic-compatible gateway showed the old description asking the model to judge "can I see images", the exact self-assessment that fails when a gateway strips images silently, so the skill loaded but never fired. The description now keys on visible evidence: placeholders like `[Image #1]` and `[Unsupported Image]` trigger with a guard check as backup, and a `[Image: source: <path>]` line with no visible image content is a hard trigger, because that line means the harness stored the pasted image on disk and did not deliver it. Newer Claude Code builds write pastes to `~/.claude/image-cache/<session>/` and inject that line from the cli entrypoint (all models get it, vision models also get the real image and are immune to the trigger by the no-visible-content condition; the VSCode entrypoint injects nothing). The skill reads that path directly when it is alive, falls back to `recover-paste` when it is not, and never deletes Claude Code's own cache files.
+- `guards.allowModels`: the guard gains an allowlist mode for the world where most models are multimodal and the text-only ones are the short list. Non-empty means only listed models run the engine and every other identified model is denied. Deny patterns win over allow matches, so a broad allow can have vision variants carved out (`allowModels: ["glm-5.*"]`, `denyModels: ["glm-*v*"]`), and the unknown-model policy is unchanged (fail open unless `denyWhenUnknown`). `config set guards.allowModels` takes a JSON array or comma list, `doctor` reports both lists and flags allowlist mode, the analyze fast gate also refuses an explicit `MODLENS_MODEL` that is off the list, and `configure.md` documents tightly anchored patterns (`deepseek-v4-*`, not `deepseek*`) so a vendor's next multimodal generation falls off the list instead of into it. Configure by what actually reaches the model, not by what it could see: a multimodal model behind an image-stripping gateway still needs modlens.
+
 ## 3.5.1 - 2026-08-13
 
 - `file://` inputs now resolve through Node's `fileURLToPath` instead of hand-stripping the prefix (issue #16). The old unwrap left a leading slash in front of Windows drive letters, so `file:///C:/Temp/shot.png` could resolve against the current working drive as `E:\C:\Temp\shot.png`, and `decodeURI` left reserved escapes such as the `%23` in a `#` filename undecoded. A URL produced by `pathToFileURL()` now round-trips back to the original local path, and a malformed file URL fails with Node's clear error instead of silently resolving to a wrong path. Thanks to @BruceWae for the report and a validated fix branch.

package/dist/main.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import * as fs from "fs";
 import * as path from "path";
 import * as childProcess from "child_process";
-import { spawn } from "child_process";
+import { spawn, execFileSync } from "child_process";
 import * as os from "os";
 import { fileURLToPath } from "url";
 import require$$0$1 from "node:assert";
@@ -28149,13 +28149,19 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
   const config2 = loadConfigFile(configPath);
   if (dottedKey === "provider") {
     config2.provider = value;
+  } else if (dottedKey === "auto") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized !== "true" && normalized !== "false") {
+      throw new Error("auto must be true or false.");
+    }
+    config2.auto = normalized === "true";
   } else if (dottedKey.startsWith("guards.")) {
     setGuardsValue(config2, dottedKey.slice("guards.".length), value);
   } else {
     const dot = dottedKey.indexOf(".");
     if (dot <= 0 || dot === dottedKey.length - 1) {
       throw new Error(
-        `Invalid config key: ${dottedKey}. Use "provider", "guards.<denyModels|denyWhenUnknown>", or "<provider>.<apiKey|baseUrl|model|extraBody>".`
+        `Invalid config key: ${dottedKey}. Use "provider", "auto", "guards.<denyModels|allowModels|denyWhenUnknown>", or "<provider>.<apiKey|baseUrl|model|extraBody>".`
       );
     }
     const providerName = dottedKey.slice(0, dot);
@@ -28190,12 +28196,12 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
   }
 }
 function setGuardsValue(config2, field, value) {
-  if (field === "denyModels") {
+  if (field === "denyModels" || field === "allowModels") {
     if (value.trim() === "") {
-      delete config2.guards?.denyModels;
+      delete config2.guards?.[field];
     } else {
       config2.guards ??= {};
-      config2.guards.denyModels = parseModelList(value);
+      config2.guards[field] = parseModelList(value, `guards.${field}`);
     }
   } else if (field === "denyWhenUnknown") {
     const normalized = value.trim().toLowerCase();
@@ -28205,17 +28211,19 @@ function setGuardsValue(config2, field, value) {
     config2.guards ??= {};
     config2.guards.denyWhenUnknown = normalized === "true";
   } else {
-    throw new Error(`Unknown guards field: ${field}. Use denyModels or denyWhenUnknown.`);
+    throw new Error(
+      `Unknown guards field: ${field}. Use denyModels, allowModels, or denyWhenUnknown.`
+    );
   }
   if (config2.guards && Object.keys(config2.guards).length === 0) {
     delete config2.guards;
   }
 }
-function parseModelList(value) {
+function parseModelList(value, key) {
   if (value.trim().startsWith("[")) {
-    const parsed = parseJsonOrExplain(value, "guards.denyModels");
+    const parsed = parseJsonOrExplain(value, key);
     if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
-      throw new Error("guards.denyModels must be a JSON array of glob strings.");
+      throw new Error(`${key} must be a JSON array of glob strings.`);
     }
     return parsed;
   }
@@ -28655,6 +28663,286 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
     child.on("close", (code) => settle(code));
   });
 }
+function denyPatterns(guards) {
+  return stringPatterns(guards?.denyModels);
+}
+function allowPatterns(guards) {
+  return stringPatterns(guards?.allowModels);
+}
+function stringPatterns(raw) {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.filter((pattern) => typeof pattern === "string");
+}
+function globMatch(pattern, value) {
+  const regex = pattern.split(/([*?])/).map((part) => {
+    if (part === "*") {
+      return ".*";
+    }
+    if (part === "?") {
+      return ".";
+    }
+    return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${regex}$`, "i").test(value);
+}
+function evaluateGuard(guards, detection) {
+  const deny = denyPatterns(guards);
+  const allow = allowPatterns(guards);
+  if (!detection.model) {
+    if (guards?.denyWhenUnknown === true) {
+      return {
+        ...detection,
+        guard: "deny",
+        reason: "model unknown and denyWhenUnknown is set"
+      };
+    }
+    return {
+      ...detection,
+      guard: "allow",
+      reason: deny.length === 0 && allow.length === 0 ? "no deny rules configured" : "model unknown, failing open"
+    };
+  }
+  if (deny.length === 0 && allow.length === 0) {
+    return { ...detection, guard: "allow", reason: "no deny rules configured" };
+  }
+  const candidates = [detection.model];
+  if (detection.provider) {
+    candidates.push(`${detection.provider}/${detection.model}`);
+  }
+  const firstMatch = (patterns) => patterns.find((pattern) => candidates.some((candidate) => globMatch(pattern, candidate)));
+  const denied = firstMatch(deny);
+  if (denied) {
+    return {
+      ...detection,
+      guard: "deny",
+      matched: denied,
+      reason: "model has native vision per guards.denyModels"
+    };
+  }
+  if (allow.length > 0) {
+    const allowed = firstMatch(allow);
+    if (allowed) {
+      return {
+        ...detection,
+        guard: "allow",
+        matched: allowed,
+        reason: "model is on guards.allowModels"
+      };
+    }
+    return {
+      ...detection,
+      guard: "deny",
+      reason: "not on guards.allowModels: only listed models run the engine"
+    };
+  }
+  return { ...detection, guard: "allow", reason: "not on the deny list" };
+}
+const VISION_MODEL_PATTERNS = [
+  "claude-*",
+  "gpt-4o*",
+  "gpt-4.1*",
+  "gpt-5*",
+  "o3*",
+  "o4*",
+  "gemini-*",
+  "glm-*v*",
+  "qwen*-vl*",
+  "qwen3.5-plus*",
+  "qwen3.6-plus*",
+  "kimi-k2.5*",
+  "kimi-k2.6*",
+  "kimi-k2.7*",
+  "kimi-k3*",
+  "moonshot-v1-*vision*",
+  "minimax-vl*",
+  "minimax-m3*",
+  "deepseek-vl*",
+  "deepseek-ocr*",
+  "janus*",
+  "pixtral*",
+  "llama-4*",
+  "llama-3.2-*vision*",
+  "grok-4*",
+  "grok-2-vision*",
+  "internvl*"
+];
+function isVisionModel(modelId) {
+  const bare = modelId.includes("/") ? modelId.slice(modelId.lastIndexOf("/") + 1) : modelId;
+  return VISION_MODEL_PATTERNS.some((pattern) => globMatch(pattern, bare));
+}
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1e3;
+const CLI_TIMEOUT_MS = 1e4;
+function defaultRunCli(bin, args, timeoutMs) {
+  return execFileSync(bin, args, { encoding: "utf-8", timeout: timeoutMs, stdio: "pipe" });
+}
+function timed(run) {
+  const start = Date.now();
+  const probe = run();
+  return { ...probe, elapsedMs: Date.now() - start };
+}
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+function probeClaude(env) {
+  return timed(() => {
+    const cliPath = findOnPath("claude", env);
+    if (!cliPath) {
+      return {
+        harness: "claude-code",
+        cliFound: false,
+        visionModels: [],
+        source: "none"
+      };
+    }
+    return {
+      harness: "claude-code",
+      cliFound: true,
+      cliPath,
+      visionModels: ["anthropic/* (all current models)"],
+      source: "builtin-table"
+    };
+  });
+}
+function probeCodex(env, home) {
+  return timed(() => {
+    const cliPath = findOnPath("codex", env);
+    const base = { harness: "codex", cliFound: cliPath !== null };
+    if (!cliPath) {
+      return { ...base, visionModels: [], source: "none" };
+    }
+    const codexHome = path.join(home, ".codex");
+    const loggedIn = fs.existsSync(path.join(codexHome, "auth.json"));
+    try {
+      const toml = fs.readFileSync(path.join(codexHome, "config.toml"), "utf-8");
+      const catalogPath = toml.match(/^model_catalog_json\s*=\s*"([^"]+)"/m)?.[1];
+      if (!catalogPath) {
+        return { ...base, cliPath, loggedIn, visionModels: [], source: "none" };
+      }
+      const catalog = readJson(catalogPath);
+      const vision = (catalog.models ?? []).filter((m) => m.slug && (m.input_modalities ?? []).includes("image")).map((m) => m.slug);
+      return {
+        ...base,
+        cliPath,
+        loggedIn,
+        visionModels: vision,
+        source: "metadata"
+      };
+    } catch (error) {
+      return {
+        ...base,
+        cliPath,
+        loggedIn,
+        visionModels: [],
+        source: "none",
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
+}
+function probePi(env, home) {
+  return timed(() => {
+    const cliPath = findOnPath("pi", env);
+    const base = { harness: "pi", cliFound: cliPath !== null };
+    if (!cliPath) {
+      return { ...base, visionModels: [], source: "none" };
+    }
+    const agentDir = path.join(home, ".pi", "agent");
+    try {
+      const auth = readJson(path.join(agentDir, "auth.json"));
+      const providersWithCreds = new Set(Object.keys(auth));
+      const store = readJson(path.join(agentDir, "models-store.json"));
+      const vision = [];
+      for (const entry of Object.values(store)) {
+        for (const model of entry?.models ?? []) {
+          if (model.id && (model.input ?? []).includes("image") && model.provider && providersWithCreds.has(model.provider)) {
+            vision.push(model.id);
+          }
+        }
+      }
+      return {
+        ...base,
+        cliPath,
+        loggedIn: providersWithCreds.size > 0,
+        visionModels: vision,
+        source: "metadata"
+      };
+    } catch (error) {
+      return {
+        ...base,
+        cliPath,
+        visionModels: [],
+        source: "none",
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
+}
+function probeOpencode(env, runCli) {
+  return timed(() => {
+    const cliPath = findOnPath("opencode", env);
+    const base = { harness: "opencode", cliFound: cliPath !== null };
+    if (!cliPath) {
+      return { ...base, visionModels: [], source: "none" };
+    }
+    try {
+      const listing = runCli(cliPath, ["models"], CLI_TIMEOUT_MS);
+      const vision = listing.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && isVisionModel(line));
+      return { ...base, cliPath, visionModels: vision, source: "builtin-table" };
+    } catch (error) {
+      return {
+        ...base,
+        cliPath,
+        visionModels: [],
+        source: "none",
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
+}
+function readCache(cachePath, ttlMs) {
+  try {
+    const cached = readJson(cachePath);
+    if (!cached.cachedAt || !Array.isArray(cached.probes)) {
+      return null;
+    }
+    if (Date.now() - Date.parse(cached.cachedAt) > ttlMs) {
+      return null;
+    }
+    return cached;
+  } catch {
+    return null;
+  }
+}
+function discoverAuto(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? os.homedir();
+  const cachePath = options.cachePath ?? path.join(home, ".modlens", "auto-cache.json");
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  if (!options.fresh) {
+    const cached = readCache(cachePath, ttlMs);
+    if (cached) {
+      return { probes: cached.probes, cachedAt: cached.cachedAt, fromCache: true };
+    }
+  }
+  const runCli = options.runCli ?? defaultRunCli;
+  const probes = [
+    probeClaude(env),
+    probeCodex(env, home),
+    probeOpencode(env, runCli),
+    probePi(env, home)
+  ];
+  const cachedAt = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify({ cachedAt, probes }, null, 2), {
+      mode: 384
+    });
+  } catch {
+  }
+  return { probes, cachedAt, fromCache: false };
+}
 const HARNESS_BY_BASENAME = {
   claude: "claude-code",
   "claude-code": "claude-code",
@@ -29257,60 +29545,6 @@ function sniffModel(harness, cwd, env, roots = {}) {
     return null;
   }
 }
-function denyPatterns(guards) {
-  const raw = guards?.denyModels;
-  if (!Array.isArray(raw)) {
-    return [];
-  }
-  return raw.filter((pattern) => typeof pattern === "string");
-}
-function globMatch(pattern, value) {
-  const regex = pattern.split(/([*?])/).map((part) => {
-    if (part === "*") {
-      return ".*";
-    }
-    if (part === "?") {
-      return ".";
-    }
-    return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  }).join("");
-  return new RegExp(`^${regex}$`, "i").test(value);
-}
-function evaluateGuard(guards, detection) {
-  const patterns = denyPatterns(guards);
-  if (!detection.model) {
-    if (guards?.denyWhenUnknown === true) {
-      return {
-        ...detection,
-        guard: "deny",
-        reason: "model unknown and denyWhenUnknown is set"
-      };
-    }
-    return {
-      ...detection,
-      guard: "allow",
-      reason: patterns.length === 0 ? "no deny rules configured" : "model unknown, failing open"
-    };
-  }
-  if (patterns.length === 0) {
-    return { ...detection, guard: "allow", reason: "no deny rules configured" };
-  }
-  const candidates = [detection.model];
-  if (detection.provider) {
-    candidates.push(`${detection.provider}/${detection.model}`);
-  }
-  for (const pattern of patterns) {
-    if (candidates.some((candidate) => globMatch(pattern, candidate))) {
-      return {
-        ...detection,
-        guard: "deny",
-        matched: pattern,
-        reason: "model has native vision per guards.denyModels"
-      };
-    }
-  }
-  return { ...detection, guard: "allow", reason: "not on the deny list" };
-}
 function detectActiveModel(options) {
   const env = options.env ?? process.env;
   const envModel = env.MODLENS_MODEL?.trim();
@@ -29340,7 +29574,7 @@ function detectActiveModel(options) {
   return { model: null, source: "none", harness };
 }
 function runGuard(guards, options) {
-  if (denyPatterns(guards).length === 0 && guards?.denyWhenUnknown !== true) {
+  if (denyPatterns(guards).length === 0 && allowPatterns(guards).length === 0 && guards?.denyWhenUnknown !== true) {
     return { model: null, source: "none", guard: "allow", reason: "no deny rules configured" };
   }
   return evaluateGuard(guards, detectActiveModel(options));
@@ -29481,6 +29715,7 @@ function buildDoctorReport(input) {
     harness: { detected: harnessDetection.harness, source: harnessDetection.source },
     guard: {
       rules: denyPatterns(input.config.guards).length,
+      allowRules: allowPatterns(input.config.guards).length,
       denyWhenUnknown: input.config.guards?.denyWhenUnknown ?? false,
       model: guardVerdict.model,
       source: guardVerdict.source,
@@ -29488,7 +29723,13 @@ function buildDoctorReport(input) {
       matched: guardVerdict.matched,
       reason: guardVerdict.reason
     },
-    config: inspectConfigFile(configPath)
+    config: inspectConfigFile(configPath),
+    // doctor is the "what would auto find" view, so it always probes fresh
+    // (and rewrites the cache); regular runs will read the cache instead.
+    auto: {
+      enabled: input.config.auto === true,
+      probes: discoverAuto({ env, fresh: true, ...input.auto }).probes
+    }
   };
 }
 function mark(ok) {
@@ -29530,13 +29771,37 @@ function renderDoctorReport(report) {
   lines.push("");
   lines.push("Guard (should the vision engine run for the active model?)");
   lines.push(
-    `  rules: ${report.guard.rules} deny pattern(s), denyWhenUnknown: ${report.guard.denyWhenUnknown}`
+    `  rules: ${report.guard.rules} deny pattern(s), ${report.guard.allowRules} allow pattern(s)${report.guard.allowRules > 0 ? " (allowlist mode)" : ""}, denyWhenUnknown: ${report.guard.denyWhenUnknown}`
   );
   lines.push(`  active model: ${report.guard.model ?? "unknown"} (via ${report.guard.source})`);
   lines.push(
     `  verdict: ${report.guard.verdict}${report.guard.matched ? ` (matched "${report.guard.matched}")` : ""}, ${report.guard.reason}`
   );
   lines.push("");
+  lines.push("Auto (borrowable local harness vision; off by default)");
+  lines.push(
+    `  enabled: ${report.auto.enabled}${report.auto.enabled ? "" : " (turn on: modlens config set auto true)"}`
+  );
+  for (const probe of report.auto.probes) {
+    if (!probe.cliFound) {
+      lines.push(`  ${probe.harness}: cli not found`);
+      continue;
+    }
+    const parts = [];
+    const shown = probe.visionModels.slice(0, 3).join(", ");
+    parts.push(
+      probe.visionModels.length === 0 ? "no vision models" : `${probe.visionModels.length} vision model(s): ${shown}${probe.visionModels.length > 3 ? ", ..." : ""}`
+    );
+    if (probe.loggedIn !== void 0) {
+      parts.push(probe.loggedIn ? "logged in" : "no credentials found");
+    }
+    parts.push(`via ${probe.source}, ${probe.elapsedMs}ms`);
+    if (probe.error) {
+      parts.push(`error: ${probe.error}`);
+    }
+    lines.push(`  ${probe.harness}: ${parts.join(", ")}`);
+  }
+  lines.push("");
   lines.push("Config file");
   lines.push(`  path: ${report.config.path}`);
   if (report.config.exists) {
@@ -29729,7 +29994,7 @@ function recoverPastedImages(options = {}) {
   return result;
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.5.1");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.7.0");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").option(
   "--extra-body <json>",
   `JSON merged into the API request body, e.g. '{"thinking":{"type":"disabled"}}'`
@@ -29745,9 +30010,10 @@ program.command("analyze", { isDefault: true }).description("Analyze an image in
         cwd: process.cwd(),
         env: process.env
       });
-      if (verdict.guard === "deny" && verdict.matched) {
+      if (verdict.guard === "deny" && verdict.model) {
+        const cause = verdict.matched ? `matches guards.denyModels pattern "${verdict.matched}". A model with native vision should read the image itself.` : "is not on guards.allowModels, which only lets listed models run the engine.";
         throw new Error(
-          `Invocation guard denied this read: active model "${verdict.model}" matches guards.denyModels pattern "${verdict.matched}". A model with native vision should read the image itself. To override, unset MODLENS_MODEL or edit guards in ${CONFIG_PATH}.`
+          `Invocation guard denied this read: active model "${verdict.model}" ${cause} To override, unset MODLENS_MODEL or edit guards in ${CONFIG_PATH}.`
         );
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.5.1",
+  "version": "3.7.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {

package/skills/modlens/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modlens
-description: "Plug-in vision for text-only models. Use whenever the user shares an image (local path, screenshot, photo, chart, document scan, or image URL) and the active model cannot see images or has no vision tool. Before the first read of a session, run `modlens guard`: a deny verdict means the active model has native vision and must read the image itself, not through this skill. Runs the modlens CLI to convert the image into structured JSON evidence: every word transcribed, layout regions, semantics, visual clues. Also use when the user asks how to install, configure, or switch modlens providers (Gemini API key, OpenAI-compatible endpoints, Claude API or Claude Code CLI)."
+description: "Plug-in vision for text-only models. Hard rule: when a file path or URL with an image extension (.png, .jpg, .jpeg, .webp, .gif, .bmp, .heic) appears anywhere in the conversation (typed by the user, injected as a `[Image: source: <path>]` line, or inside a tag) and you cannot see that image's content, run this skill on it before any other approach: no self-built OCR, no PIL, no tesseract. Also triggers on pasted-image placeholders such as `[Image #1]` and `[Unsupported Image]`. If you can actually see the image, do not use this skill. When unsure, run `modlens guard` before the first read of a session: a deny verdict means the active model has native vision and must read the image itself. Runs the modlens CLI to convert the image into structured JSON evidence: every word transcribed, layout regions, semantics, visual clues. Also use when the user asks how to install, configure, or switch modlens providers (Gemini API key, OpenAI-compatible endpoints, Claude API or Claude Code CLI)."
 compatibility: Requires network access and one of node 22+/npx, bun/bunx, or a preinstalled modlens binary on PATH.
 allowed-tools: Bash
 ---
@@ -9,7 +9,8 @@ allowed-tools: Bash
 
 Use this skill when:
 
-- The user provides an image path or image URL and asks anything about it
+- A file path or URL ending in an image extension (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.heic`) appears and you cannot see the image behind it. The path alone is the trigger: hand it to modlens first, do not Read the bytes yourself, do not build your own OCR out of PIL or tesseract
+- A pasted image reaches you only as a placeholder: `[Image #1]`, `[Unsupported Image]`, a `[Image: source: <path>]` line, or an attachment whose content you cannot see
 - The active model has no native vision (text-only model in a coding agent)
 - You need the text inside an image, its layout, or a chart's structure as evidence before reasoning
 - The user asks how to configure modlens, get an API key for it, or switch its provider: follow `references/configure.md` and run the commands for them
@@ -33,11 +34,11 @@ The launcher finds a working way to run modlens and forwards your arguments to i
 
 ### If you cannot run the launcher script
 
-Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.5.1):
+Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.7.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.5.1: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.5.1 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.5.1 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.7.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.7.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.7.0 <args>`.
 4. Otherwise none of these runtimes is here. Tell the user no JavaScript runtime was found and that installing Node 22.13+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the version pin, the compatibility rule, and the diagnostic fields.
@@ -71,14 +72,15 @@ modlens guard --model <your-model-id>
 Pass `--model` with your own model id when you know it (most harnesses state it in your system prompt). Never pass a guess. The verdict weighs three signals, strongest first: the `MODLENS_MODEL` env var, the harness's own session storage (it records the model on every assistant turn, so it outranks your self-report), then your `--model` value.
 
 - `{"guard": "allow"}` (exit 0): proceed with the read.
-- `{"guard": "deny"}` (exit 1) **with a `matched` field**: do not run the engine. The active model is on the user's own deny list of vision-capable models: read the image with your native vision instead.
-- `{"guard": "deny"}` (exit 1) **without `matched`**: the model could not be identified and the user set `denyWhenUnknown`. Do not run the engine, and do not pretend to see the image either. Tell the user the guard could not identify the active model and that `MODLENS_MODEL=<model>` (or `MODLENS_MODEL=none` after fixing the guards config) unblocks it.
+- `{"guard": "deny"}` (exit 1) **with a `model` identified**: do not run the engine. Either the model matched the user's deny list of vision-capable models (a `matched` field names the pattern), or the user runs an allow list of text-only models and this model is not on it. Read the image with your native vision instead.
+- `{"guard": "deny"}` (exit 1) **with `model: null`**: the model could not be identified and the user set `denyWhenUnknown`. Do not run the engine, and do not pretend to see the image either. Tell the user the guard could not identify the active model and that `MODLENS_MODEL=<model>` (or `MODLENS_MODEL=none` after fixing the guards config) unblocks it.
 - Exit 2 is an error: the guard fails open, report the error and proceed.
 
-One check per session is enough, unless the user switches models mid-session: the verdict follows the model, so re-run the guard after a switch. Users enable this with glob patterns of vision-capable model names, and `modlens doctor` shows the rules plus a live evaluation in its Guard section:
+One check per session is enough, unless the user switches models mid-session: the verdict follows the model, so re-run the guard after a switch. Users configure it with glob patterns either way round, a deny list of vision models or an allow list of text-only models (deny wins on overlap, so a vision variant can be carved out of a broad allow). `modlens doctor` shows the rules plus a live evaluation in its Guard section:
 
 ```bash
-modlens config set guards.denyModels '["gemini-3*", "qwen-vl-*"]'
+modlens config set guards.allowModels '["deepseek-v4-*", "glm-5.*"]'   # only these run the engine
+modlens config set guards.denyModels '["glm-*v*", "qwen-vl-*"]'        # never these
 modlens config set guards.denyWhenUnknown true    # optional, default false (fail open)
 ```
 
@@ -110,9 +112,15 @@ Harnesses rarely hand you a clean path. First identify which harness you are in,
 
 - Extract the `path` value from the tag and run modlens on it. Pasted images live in a temp file Codex already created; a stripped image keeps its path tag next to the placeholder. Do NOT use `recover-paste` here: it detects Codex and refuses with this same guidance.
 
-**Claude Code, Pi, or OpenCode** (no path tag anywhere; the image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see):
+**Claude Code with a `[Image: source: <path>]` line in the conversation**:
 
-- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+; Bun cannot load node:sqlite, so if the launcher resolved to bunx, OpenCode recovery needs a real Node install). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
+- Newer Claude Code builds write every pasted image to `~/.claude/image-cache/<session-id>/` and, in the terminal (`cli`) entrypoint, inject that line as a user message. This is undocumented internal behavior (observed on 2.1.201 through 2.1.229; the VSCode and desktop entrypoints do not inject it), so treat it as a shortcut, not a guarantee.
+- If the file at that path exists, run modlens on it directly and skip `recover-paste` entirely. The file is Claude Code's own cache: read it, never delete or move it.
+- If the path is gone (the cache is cleaned after a while) or there is no such line, fall through to the next branch.
+
+**Claude Code, Pi, or OpenCode** (no usable path anywhere; the image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see):
+
+- Whatever a gateway strips from the request, these harnesses persist user messages, image bytes included, in local session storage first: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+; Bun cannot load node:sqlite, so if the launcher resolved to bunx, OpenCode recovery needs a real Node install). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
 - The output is JSON with real file paths, ordered oldest to newest, so the LAST path is the user's most recent paste. Analyze that one first. Entries carry `filename` (the original attachment name) when the harness stored one; if the user's message or an error mentions a filename, match on it.
 - Run every command yourself: `recover-paste`, then `modlens -i <path>` on the recovered file, then answer from the JSON. Never ask the user to run modlens or to relay paths.
 - When the analysis is done, delete the recovered files: they are private copies of the user's pasted images sitting in the temp dir, and nothing cleans them up until the OS does. Remove the recovery output directory (each entry's `path` sits inside it), unless the user asked to keep the files.

package/skills/modlens/references/configure.md

@@ -23,7 +23,8 @@ Everything lives under three top-level keys, all optional. A missing file means
 {
   "provider": "gemini-api",
   "guards": {
-    "denyModels": ["gemini-3*", "qwen-vl-*"],
+    "allowModels": ["deepseek-v4-*", "glm-5.*", "minimax-m2.5*", "qwen3-coder*"],
+    "denyModels": ["glm-*v*", "deepseek-vl*"],
     "denyWhenUnknown": false
   },
   "providers": {
@@ -50,7 +51,11 @@ Field semantics:
 - `provider`: which provider runs when `-p` is not given. Canonical names or aliases both work (`agy`/`antigravity` for `antigravity-cli`, `gemini` for `gemini-api`, `openai-compat` for `openai`, `claude` for `anthropic`, `claude-code` for `claude-cli`). Empty or absent means `antigravity-cli`.
 - `providers.<name>.<field>`: four fields exist, `apiKey`, `baseUrl`, `model`, and `extraBody`. Every provider entry is optional, and every field inside it is optional. Alias keys are read too (settings saved under `gemini` are found when `gemini-api` resolves), with the canonical key winning on conflict.
 - `providers.<name>.extraBody`: a JSON object merged into the request body of the API providers (`gemini-api`, `openai`, `anthropic`), for whatever knobs that vendor has and modlens has no flag for. Turning thinking off is the usual reason, see the section below. Nested objects merge key by key, so adding one knob leaves the rest of that block alone. The fields carrying the image, the prompt, and the schema enforcement are refused with an error naming the field. The two CLI providers take no request body, so a run on `antigravity-cli` or `claude-cli` ignores it and says so in `meta.warnings`.
-- `guards`: the invocation guard, for people who run both text-only and vision-capable models through the same client. `denyModels` is a list of glob patterns (`*` and `?`, case-insensitive, matched against the model name and `provider/model`): when the active model matches one, `modlens guard` answers deny and the skill must not run the engine. `denyWhenUnknown` (default `false`) decides what happens when no signal identifies the active model: `false` proceeds, `true` denies. Set with `modlens config set guards.denyModels '["gemini-3*"]'` (a JSON array or a comma-separated list) and `modlens config set guards.denyWhenUnknown true`. The active model is detected from, strongest first: the `MODLENS_MODEL` env var (`none` means "treat as unknown"), the harness's session storage, the `--model` self-report.
+- `guards`: the invocation guard, for people who run both text-only and vision-capable models through the same client. Both lists hold glob patterns (`*` and `?`, case-insensitive, matched against the model name and `provider/model`), set with `modlens config set guards.denyModels '["gemini-3*"]'` or `guards.allowModels` (a JSON array or a comma-separated list, empty clears). Two ways to express the same intent, pick the shorter list:
+  - `denyModels` alone: everything runs the engine except the listed vision models. Right when text-only models are the majority of what you plug in.
+  - `allowModels` non-empty (allowlist mode): only the listed models run the engine, every other identified model is denied. Right for the actual 2026 landscape, where text-only models are the short list. A deny pattern still wins over an allow match, so a broad allow can have its vision variants carved out, as in the example above: `glm-5.*` allows the text line while `glm-*v*` catches `glm-5v-turbo`. Anchor allow patterns tightly (`deepseek-v4-*`, not `deepseek*`) so a vendor's next multimodal generation falls off the list and steps aside until you have checked it.
+  - List a model by what actually reaches it, not by what it could see: a multimodal model behind a gateway that strips images still needs modlens, and your session transcript records the model name the gateway reports. `modlens doctor`'s Guard section shows the rules and a live verdict for checking the result.
+  - `denyWhenUnknown` (default `false`) decides what happens when no signal identifies the active model, in either mode: `false` proceeds, `true` denies. The active model is detected from, strongest first: the `MODLENS_MODEL` env var (`none` means "treat as unknown"), the harness's session storage, the `--model` self-report.
 - Environment variables override the file for these bindings: `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`. Beyond those, modlens reads `MODLENS_HARNESS` (paste-recovery and guard scope), `MODLENS_MODEL` (guard override, see `guards`), and the fingerprints harnesses inject themselves, which pin the guard's storage lookup to the current session: `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, plus the presence markers harness detection relies on (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_SANDBOX`).
 - Unknown top-level keys and unknown provider names are ignored rather than rejected, so a typo fails quiet: run `modlens doctor` after hand-editing, it shows which file and env values are actually in effect.
 

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.5.1
+- Pinned CLI version: 3.7.0
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.5.1'
+$Pinned = '3.7.0'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.5.1"
+PINNED="3.7.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"