@liustack/modlens 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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.
+
 ## 3.5.0 - 2026-08-12
 
 - The CLI no longer prints a `node:sqlite` ExperimentalWarning on every start. Bundling undici had hoisted its lazy `require('node:sqlite')` (for a cache store nothing here uses) into a top-level import. The build now keeps that require a runtime call.

package/dist/main.js

@@ -5,6 +5,7 @@ import * as path from "path";
 import * as childProcess from "child_process";
 import { spawn } from "child_process";
 import * as os from "os";
+import { fileURLToPath } from "url";
 import require$$0$1 from "node:assert";
 import require$$1 from "node:net";
 import require$$2 from "node:http";
@@ -28154,7 +28155,7 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
     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", "guards.<denyModels|allowModels|denyWhenUnknown>", or "<provider>.<apiKey|baseUrl|model|extraBody>".`
       );
     }
     const providerName = dottedKey.slice(0, dot);
@@ -28189,12 +28190,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();
@@ -28204,17 +28205,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;
   }
@@ -28526,8 +28529,7 @@ function resolveInput(input) {
     return { source: trimmed, kind: "remote" };
   }
   if (/^file:\/\//i.test(trimmed)) {
-    const localPath = decodeURI(trimmed.replace(/^file:\/\//i, ""));
-    return { source: path.resolve(localPath), kind: "local" };
+    return { source: path.resolve(fileURLToPath(trimmed)), kind: "local" };
   }
   return { source: path.resolve(trimmed), kind: "local" };
 }
@@ -29258,7 +29260,12 @@ function sniffModel(harness, cwd, env, roots = {}) {
   }
 }
 function denyPatterns(guards) {
-  const raw = guards?.denyModels;
+  return stringPatterns(guards?.denyModels);
+}
+function allowPatterns(guards) {
+  return stringPatterns(guards?.allowModels);
+}
+function stringPatterns(raw) {
   if (!Array.isArray(raw)) {
     return [];
   }
@@ -29277,7 +29284,8 @@ function globMatch(pattern, value) {
   return new RegExp(`^${regex}$`, "i").test(value);
 }
 function evaluateGuard(guards, detection) {
-  const patterns = denyPatterns(guards);
+  const deny = denyPatterns(guards);
+  const allow = allowPatterns(guards);
   if (!detection.model) {
     if (guards?.denyWhenUnknown === true) {
       return {
@@ -29289,25 +29297,41 @@ function evaluateGuard(guards, detection) {
     return {
       ...detection,
       guard: "allow",
-      reason: patterns.length === 0 ? "no deny rules configured" : "model unknown, failing open"
+      reason: deny.length === 0 && allow.length === 0 ? "no deny rules configured" : "model unknown, failing open"
     };
   }
-  if (patterns.length === 0) {
+  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}`);
   }
-  for (const pattern of patterns) {
-    if (candidates.some((candidate) => globMatch(pattern, candidate))) {
+  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: "deny",
-        matched: pattern,
-        reason: "model has native vision per guards.denyModels"
+        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" };
 }
@@ -29340,7 +29364,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 +29505,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,
@@ -29530,7 +29555,7 @@ 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(
@@ -29729,7 +29754,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.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.6.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 +29770,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.0",
+  "version": "3.6.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. Use whenever an image is in play and you cannot see its content: the user gives an image path, screenshot, photo, chart, document scan, or image URL, or a pasted image appears only as a placeholder such as `[Image #1]`, `[Unsupported Image]`, or an attachment you cannot view. Hard rule: a `[Image: source: <path>]` line with no visible image content means the harness stored the pasted image at that path and did not deliver it to you; run modlens on that path directly. 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
 ---
@@ -10,6 +10,7 @@ allowed-tools: Bash
 Use this skill when:
 
 - The user provides an image path or image URL and asks anything about it
+- 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.0):
+Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.6.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.5.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.5.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.5.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.6.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.6.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.6.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.0
+- Pinned CLI version: 3.6.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.0'
+$Pinned = '3.6.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.0"
+PINNED="3.6.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"