claude-use 11.39.0 → 11.40.0

package/README.md

@@ -132,6 +132,7 @@ agent-shim model remove <name> [--yes]
 agent-shim model tier <tier> --ref <ref> | --clear
 agent-shim model price <ref> --input <usd> --output <usd> | --clear
 agent-shim model list [--json]
+agent-shim model explain <name>   # which member the virtual model's mode picks now, and why
 agent-shim provider remove <name> [--yes] [--json]
 
 agent-shim rule add <path> [--config-profile <profile>] [--identity <identity>] [--json]

package/dist/cli.cjs

@@ -34636,7 +34636,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "claude-use",
-      version: "11.39.0",
+      version: "11.40.0",
       description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
       license: "MIT",
       author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -35948,6 +35948,7 @@ function createUsageStore(deps) {
       }
       fs26.appendFilePrivate(import_node_path26.default.join(paths.usageLogDir, segmentName(day, deps.pid)), `${JSON.stringify(record2)}
 `);
+      deps.onRecord?.(record2);
       if (record2.identity !== void 0) {
         rewriteSnapshot(record2.identity, (current) => ({ ...current?.providers, [record2.provider]: foldProviderState(current?.providers[record2.provider], record2) }));
       }
@@ -115764,6 +115765,72 @@ function supervisedSessionOf(fs26, paths, sessionId, isRunning) {
   return void 0;
 }
 
+// src/selection/targetStore.ts
+init_read();
+
+// src/selection/signals.ts
+function targetOf(record2) {
+  return record2.model === void 0 ? void 0 : `${record2.provider}/${record2.model}`;
+}
+function median(values) {
+  if (values.length === 0) {
+    return void 0;
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  const above = sorted[middle];
+  const below = sorted[middle - 1];
+  return sorted.length % 2 === 0 && above !== void 0 && below !== void 0 ? (above + below) / 2 : sorted[middle];
+}
+var OBSERVATION_WINDOW = 20;
+function observeRecord(observations, record2) {
+  const target = targetOf(record2);
+  if (target === void 0) {
+    return new Map(observations);
+  }
+  const kept = [...observations.get(target) ?? [], record2].slice(-OBSERVATION_WINDOW);
+  return new Map(observations).set(target, kept);
+}
+function observationOf(records) {
+  const completed = records.filter((record2) => record2.outcome === "completed");
+  const latencies = completed.map((record2) => record2.latencyMs);
+  const usage = records.flatMap((record2) => record2.usage === void 0 ? [] : [record2.usage]);
+  const input2 = usage.reduce((sum, entry) => sum + (entry.inputTokens ?? 0), 0);
+  const output2 = usage.reduce((sum, entry) => sum + (entry.outputTokens ?? 0), 0);
+  const cacheRead = usage.reduce((sum, entry) => sum + (entry.cacheReadInputTokens ?? 0), 0);
+  return {
+    latencyMs: median(latencies),
+    successRate: records.length === 0 ? void 0 : completed.length / records.length,
+    tokenMix: input2 + output2 + cacheRead === 0 ? void 0 : { input: input2, output: output2, cacheRead }
+  };
+}
+function blendedPricePerMTok(prices, mix) {
+  const total = mix.input + mix.output + mix.cacheRead;
+  if (total === 0) {
+    return void 0;
+  }
+  return (prices.input * mix.input + prices.output * mix.output) / total;
+}
+
+// src/selection/targetStore.ts
+var SEED_LOOKBACK_RECORDS = 500;
+function createTargetObservationStore(fs26, paths) {
+  let observations = /* @__PURE__ */ new Map();
+  const seeded = readUsageLog(fs26, paths.usageLogDir, {}).records.slice(-SEED_LOOKBACK_RECORDS);
+  for (const record2 of seeded) {
+    observations = observeRecord(observations, record2);
+  }
+  return {
+    observe: (record2) => {
+      observations = observeRecord(observations, record2);
+    },
+    observation: (target) => {
+      const records = observations.get(target);
+      return records === void 0 ? void 0 : observationOf(records);
+    }
+  };
+}
+
 // src/update/commands.ts
 var import_node_fs14 = __toESM(require("node:fs"), 1);
 var import_node_os7 = __toESM(require("node:os"), 1);
@@ -131323,6 +131390,39 @@ function createPassthroughRoute(name, target) {
 // src/frontdoor/providerRoute.ts
 init_conditions();
 init_quotaFacts();
+init_modelsStore();
+
+// src/selection/candidates.ts
+var WINDOW_PERIOD_HOURS = { fiveHour: 5, sevenDay: 168, extraUsage: 168 };
+function candidateOf(ref, order, facts, isCurrent) {
+  const present = Object.entries(facts.quota ?? {}).map(([name, window]) => ({ name, ...window }));
+  const available = present.every((window) => window.remaining > 0);
+  const remainingAllowance = present.length === 0 ? void 0 : Math.min(...present.map((window) => window.remaining));
+  const hoursToReset = present.length === 0 ? void 0 : Math.min(...present.map((window) => window.hoursUntilReset));
+  const pressure = present.length === 0 ? void 0 : Math.max(
+    ...present.map((window) => {
+      const period = WINDOW_PERIOD_HOURS[window.name] ?? Number.NaN;
+      return period > 0 && window.hoursUntilReset > 0 ? window.remaining / (window.hoursUntilReset / period) : Number.NaN;
+    })
+  );
+  return {
+    ref,
+    order,
+    available,
+    ...remainingAllowance === void 0 ? {} : { remainingAllowance },
+    ...hoursToReset === void 0 ? {} : { hoursToReset },
+    ...pressure === void 0 || Number.isNaN(pressure) ? {} : { pressure },
+    // Feasibility at the observed burn needs a burn rate no signal yet carries, so an available candidate counts as feasible and the run-dry projection waits on one.
+    feasible: available,
+    ...facts.observation?.latencyMs === void 0 ? {} : { latencyMs: facts.observation.latencyMs },
+    ...facts.observation?.successRate === void 0 ? {} : { successRate: facts.observation.successRate },
+    ...facts.price === void 0 || facts.observation?.tokenMix === void 0 ? {} : { pricePerMTok: blendedPricePerMTok(facts.price, facts.observation.tokenMix) },
+    isCurrent
+  };
+}
+
+// src/frontdoor/providerRoute.ts
+init_engine();
 init_route();
 var import_node_stream3 = require("node:stream");
 
@@ -131412,22 +131512,43 @@ function scopeSessionProviderPath(request7) {
   }
   return { ...request7, url: `${PROVIDER_PATH_PREFIX}${encodeURIComponent(request7.session.provider)}${request7.url}` };
 }
-function resolveModelTarget(model, models, includeUnqualified) {
-  if (models === void 0) {
-    return model.includes("/") && !model.startsWith("acct:") ? model.split("/")[0] : void 0;
+function resolveRoutedModel(model, providerName, session, includeUnqualified, deps, memory, rotations) {
+  const models = deps.models?.();
+  const qualified = model.includes("/") && !model.startsWith("acct:") ? model : void 0;
+  if (qualified !== void 0) {
+    const [provider2, ...rest2] = qualified.split("/");
+    const named = rest2.join("/");
+    return provider2 === void 0 || named === "" ? void 0 : { provider: provider2, model: named, ref: qualified };
   }
-  if (model.includes("/") && !model.startsWith("acct:")) {
-    return model.split("/")[0];
+  const virtual = models?.virtual?.[model];
+  if (virtual === void 0 || !includeUnqualified) {
+    return void 0;
   }
-  if (!includeUnqualified) {
+  const members2 = expandMembers(model, models).filter((member) => !member.startsWith("acct:") && !member.startsWith("family:"));
+  if (members2.length === 0) {
     return void 0;
   }
-  const virtual = models.virtual?.[model];
-  const first = virtual?.members.find((member) => !member.startsWith("acct:") && !member.startsWith("family:"));
-  if (first === void 0) {
+  const snapshot = deps.usageSnapshotOf?.(session.identity);
+  const current = memory.get(session.sessionId ?? "");
+  const candidates = members2.map((ref, order) => {
+    const [provider2] = ref.split("/");
+    const facts = quotaFactsOf(snapshot?.providers[provider2 ?? ""]?.rateLimit?.unified, Date.now());
+    return candidateOf(ref, order, {
+      quota: facts,
+      ...deps.observations?.(ref) === void 0 ? {} : { observation: deps.observations(ref) },
+      ...models?.prices?.[ref] === void 0 ? {} : { price: models.prices[ref] }
+    }, ref === current);
+  });
+  const evaluated = candidates.map((candidate) => ({ candidate, capabilities: { vision: true, tools: true, thinking: true } }));
+  const rotation = rotations.get(model) ?? 0;
+  rotations.set(model, rotation + 1);
+  const selection = selectMember(virtual.mode, evaluated, { rotation });
+  if (selection.ref === void 0) {
     return void 0;
   }
-  return first.includes("/") ? first.split("/")[0] : resolveModelTarget(first, models, true);
+  const [provider, ...rest] = selection.ref.split("/");
+  const chosen = rest.join("/");
+  return provider === void 0 || chosen === "" ? void 0 : { provider, model: chosen, ref: selection.ref };
 }
 function resolveAccountTarget(model, models) {
   if (model.startsWith("acct:")) {
@@ -131444,6 +131565,8 @@ function createProviderRouteResolver(deps) {
   const oauthRoute = createPassthroughRoute("anthropic", { baseUrl: `https://${CONNECT_INTERCEPT_HOST}:${String(HTTPS_PORT)}`, stripPrefix: void 0, headroomUpstream: void 0 });
   const antigravityQuotaSources = /* @__PURE__ */ new Map();
   const antigravityRoutingMemory = /* @__PURE__ */ new Map();
+  const routingMemory = /* @__PURE__ */ new Map();
+  const rotations = /* @__PURE__ */ new Map();
   const memoryFor = (provider) => {
     const existing = antigravityRoutingMemory.get(provider);
     if (existing !== void 0) {
@@ -131605,10 +131728,12 @@ function createProviderRouteResolver(deps) {
       }
       const routesByName = (isRouter || current.session.routeByName) && !isRcSelfHostPath(path65);
       if (routesByName) {
-        const scan2 = await scanRequestHead(current, false);
-        if (scan2.replayed !== void 0) {
-          replay = scan2.replayed;
+        const scan2 = await scanRequestHead(current, true);
+        if (scan2.replayed === void 0) {
+          const resolution = resolve2(current);
+          return resolution.ok && replay !== void 0 ? { ok: true, route: servingRewritten(resolution.route, { ...replay, url: current.url }), request: { ...replay, url: current.url } } : resolution.ok ? serveScoped(resolution) : resolution;
         }
+        replay = scan2.replayed;
         const account = scan2.model === void 0 ? void 0 : resolveAccountTarget(scan2.model, deps.models?.());
         if (account !== void 0) {
           const sessionId = current.session.sessionId ?? "";
@@ -131619,18 +131744,29 @@ function createProviderRouteResolver(deps) {
             message: moved ? `model "${account.model}" runs under identity "${account.identity}"; this session is being moved there and will resume with it` : `model "${account.model}" runs under identity "${account.identity}", which needs a relaunch this session cannot make; start it there with: claude @${account.identity} --resume`
           };
         }
-        const target = scan2.model === void 0 ? void 0 : resolveModelTarget(scan2.model, deps.models?.(), isRouter || current.session.routeByName && providerName !== void 0);
-        if (target === providerName) {
+        const routed = scan2.model === void 0 ? void 0 : resolveRoutedModel(scan2.model, providerName, current.session, isRouter || providerName !== void 0, deps, routingMemory, rotations);
+        const requested = scan2.model;
+        if (routed !== void 0) {
+          routingMemory.set(current.session.sessionId ?? "", routed.ref);
+          if (requested !== void 0 && routed.provider === providerName && routed.model === requested) {
+            const resolution2 = resolve2(current);
+            return resolution2.ok ? { ok: true, route: servingRewritten(resolution2.route, { ...replay, url: current.url }), request: { ...replay, url: current.url } } : resolution2;
+          }
+          if (requested !== void 0 && routed.model !== requested) {
+            const rewritten = (scan2.text ?? "").replace(new RegExp('"model":\\s*"' + requested.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + '"'), '"model":"' + routed.model + '"');
+            const headers = Object.fromEntries(Object.entries(replay.headers).filter(([name]) => name.toLowerCase() !== "content-length"));
+            replay = { ...replay, headers, body: import_node_stream3.Readable.from([Buffer.from(rewritten, "utf8")]) };
+          }
+          if (routed.provider !== providerName) {
+            const scopedPrefix = providerName === void 0 ? void 0 : `${PROVIDER_PATH_PREFIX}${encodeURIComponent(providerName)}`;
+            const rest2 = scopedPrefix !== void 0 && path65.startsWith(scopedPrefix) ? path65.slice(scopedPrefix.length) : path65;
+            const query2 = current.url.includes("?") ? current.url.slice(current.url.indexOf("?")) : "";
+            const carried = replay;
+            current = { ...current, url: `${PROVIDER_PATH_PREFIX}${encodeURIComponent(routed.provider)}${rest2}${query2}`, body: carried.body, headers: carried.headers };
+            continue;
+          }
           const resolution = resolve2(current);
-          return resolution.ok && replay !== void 0 ? { ok: true, route: servingRewritten(resolution.route, { ...replay, url: current.url }), request: { ...replay, url: current.url } } : resolution.ok ? serveScoped(resolution) : resolution;
-        }
-        if (target !== void 0) {
-          const scopedPrefix = providerName === void 0 ? void 0 : `${PROVIDER_PATH_PREFIX}${encodeURIComponent(providerName)}`;
-          const rest2 = scopedPrefix !== void 0 && path65.startsWith(scopedPrefix) ? path65.slice(scopedPrefix.length) : path65;
-          const query2 = current.url.includes("?") ? current.url.slice(current.url.indexOf("?")) : "";
-          const carried = scan2.replayed ?? current;
-          current = { ...current, url: `${PROVIDER_PATH_PREFIX}${encodeURIComponent(target)}${rest2}${query2}`, body: carried.body, headers: carried.headers };
-          continue;
+          return resolution.ok ? { ok: true, route: servingRewritten(resolution.route, { ...replay, url: current.url }), request: { ...replay, url: current.url } } : resolution;
         }
       }
       if (routes === void 0 || routes.length === 0) {
@@ -134701,67 +134837,6 @@ function createRealQuotaRefresher(params) {
 
 // src/frontdoor/commands.ts
 init_store2();
-
-// src/selection/targetStore.ts
-init_read();
-
-// src/selection/signals.ts
-function targetOf(record2) {
-  return record2.model === void 0 ? void 0 : `${record2.provider}/${record2.model}`;
-}
-function median(values) {
-  if (values.length === 0) {
-    return void 0;
-  }
-  const sorted = [...values].sort((left, right) => left - right);
-  const middle = Math.floor(sorted.length / 2);
-  const above = sorted[middle];
-  const below = sorted[middle - 1];
-  return sorted.length % 2 === 0 && above !== void 0 && below !== void 0 ? (above + below) / 2 : sorted[middle];
-}
-var OBSERVATION_WINDOW = 20;
-function observeRecord(observations, record2) {
-  const target = targetOf(record2);
-  if (target === void 0) {
-    return new Map(observations);
-  }
-  const kept = [...observations.get(target) ?? [], record2].slice(-OBSERVATION_WINDOW);
-  return new Map(observations).set(target, kept);
-}
-function observationOf(records) {
-  const completed = records.filter((record2) => record2.outcome === "completed");
-  const latencies = completed.map((record2) => record2.latencyMs);
-  const usage = records.flatMap((record2) => record2.usage === void 0 ? [] : [record2.usage]);
-  const input2 = usage.reduce((sum, entry) => sum + (entry.inputTokens ?? 0), 0);
-  const output2 = usage.reduce((sum, entry) => sum + (entry.outputTokens ?? 0), 0);
-  const cacheRead = usage.reduce((sum, entry) => sum + (entry.cacheReadInputTokens ?? 0), 0);
-  return {
-    latencyMs: median(latencies),
-    successRate: records.length === 0 ? void 0 : completed.length / records.length,
-    tokenMix: input2 + output2 + cacheRead === 0 ? void 0 : { input: input2, output: output2, cacheRead }
-  };
-}
-
-// src/selection/targetStore.ts
-var SEED_LOOKBACK_RECORDS = 500;
-function createTargetObservationStore(fs26, paths) {
-  let observations = /* @__PURE__ */ new Map();
-  const seeded = readUsageLog(fs26, paths.usageLogDir, {}).records.slice(-SEED_LOOKBACK_RECORDS);
-  for (const record2 of seeded) {
-    observations = observeRecord(observations, record2);
-  }
-  return {
-    observe: (record2) => {
-      observations = observeRecord(observations, record2);
-    },
-    observation: (target) => {
-      const records = observations.get(target);
-      return records === void 0 ? void 0 : observationOf(records);
-    }
-  };
-}
-
-// src/frontdoor/commands.ts
 function respawnInvocation(paths) {
   const env = {};
   for (const [name, value2] of Object.entries({ ...process.env, AGENT_SHIM_HOME: paths.root })) {
@@ -134846,6 +134921,7 @@ function realFrontDoorSupervisorPorts(paths) {
       appendLog(paths, `frontdoor ${String(process.pid)}: ${line}`);
     }
   });
+  const observations = createTargetObservationStore(realFarmFs, paths);
   const routingSnapshots = /* @__PURE__ */ new Map();
   const rcControlToken = (0, import_node_crypto25.randomUUID)();
   const resolveRoute = rcObservingResolver(
@@ -134861,6 +134937,7 @@ function realFrontDoorSupervisorPorts(paths) {
       credentials: { ...realCredentialPort, cache: realCredentialCacheEnv(paths) },
       usageSnapshotOf: (identity) => identity === void 0 ? void 0 : routingSnapshots.get(identity) ?? readUsageSnapshot(realFarmFs, paths.usageSnapshotsDir, identity),
       // An `acct:` model member is served by relaunch: the door leaves a move request for the session's supervisor (found across every pool's registry, since the door does not know which pool launched the session) and answers the request with what is happening. A session nothing supervises gets the message naming the command to run instead.
+      observations: (target) => observations.observation(target),
       accountMoves: (sessionId, to2, model) => {
         if (supervisedSessionOf(realFarmFs, paths, sessionId, realIsProcessRunning) === void 0) {
           return false;
@@ -134884,6 +134961,9 @@ function realFrontDoorSupervisorPorts(paths) {
     publish: (snapshot) => {
       routingSnapshots.set(snapshot.identity, snapshot);
       usagePublisher.publish(snapshot);
+    },
+    onRecord: (record2) => {
+      observations.observe(record2);
     }
   });
   const quotaRefresher = createRealQuotaRefresher({ paths, store: usageStore, log });
@@ -135501,7 +135581,8 @@ function enrichStatuslinePayload(params) {
     sevenDayResetAt: void 0,
     providerQuotaWindows: [],
     quotaFamilies: [],
-    headroom: params.headroom
+    headroom: params.headroom,
+    routedTarget: params.routedTarget
   };
   if (params.snapshot !== void 0) {
     const scopedName = providerScopedState(params.snapshot, params.providerName, params.env.AGENT_SHIM_PROVIDER);
@@ -135575,6 +135656,9 @@ function providerScopedState(snapshot, providerName, providerDisplayName) {
   return void 0;
 }
 
+// src/statusline/commands.ts
+init_read();
+
 // src/statusline/ansi.ts
 var ESCAPE_CHAR_CODE = 27;
 var ESCAPE = String.fromCharCode(ESCAPE_CHAR_CODE);
@@ -135866,6 +135950,9 @@ function renderStatuslineBlock(summary, view, terminalWidth, nowMs) {
     const account = [summary.providerAccountEmail, summary.providerPlan].filter((part) => part !== void 0);
     header.push(account.length > 0 ? `${summary.provider} \xB7 ${account.join(" \xB7 ")}` : summary.provider);
   }
+  if (summary.routedTarget !== void 0) {
+    header.push(`via ${summary.routedTarget}`);
+  }
   const loginPlan = summary.provider === void 0 ? summary.loginPlan ?? accountPlanLabel(summary) : void 0;
   const loginOrgName = summary.loginOrganizationType === "claude_team" || summary.loginOrganizationType === "claude_enterprise" ? summary.loginOrganizationName : void 0;
   const loginParts = [summary.loginAccountEmail, loginOrgName, loginPlan].filter((part) => part !== void 0);
@@ -135969,6 +136056,7 @@ async function readAllStdin() {
     process.stdin.resume();
   });
 }
+var ROUTED_TARGET_LOOKBACK_MS = 36e5;
 function registerStatuslineCommand(program2, deps) {
   withExamples(
     program2.command("statusline").description("Serve as a statusline entrypoint: read the client's stdin payload, add the identity's live provider, account and usage windows under an agent_shim key, then run the renderer named in AGENT_SHIM_STATUSLINE_CMD or print the built-in line.").action(async () => {
@@ -136015,7 +136103,19 @@ function registerStatuslineCommand(program2, deps) {
       const target = headroomTargetOf(process.env, socketTarget === void 0 || socketTarget.refused !== void 0 ? void 0 : socketTarget.socketPath);
       const sessionId = headroomSessionIdOf(payload, process.env);
       const headroom = target === void 0 || sessionId === void 0 ? void 0 : await fetchHeadroomSessionStats(realHeadroomGet, target, sessionId);
-      const { payload: enriched, summary } = enrichStatuslinePayload({ payload, env: process.env, snapshot, account, providerName, nowMs, headroom });
+      const sessionHeader = /x-agent-shim-session:\s*([A-Za-z0-9@._-]+)/i.exec(process.env.ANTHROPIC_CUSTOM_HEADERS ?? "")?.[1];
+      let routedTarget;
+      if (sessionHeader !== void 0) {
+        try {
+          const last = readUsageLog(realFarmFs, deps.paths.usageLogDir, { sinceMs: nowMs - ROUTED_TARGET_LOOKBACK_MS }).records.filter((record2) => record2.sessionId === sessionHeader).at(-1);
+          if (last?.model !== void 0 && last.provider !== providerName) {
+            routedTarget = `${last.provider}/${last.model}`;
+          }
+        } catch {
+          routedTarget = void 0;
+        }
+      }
+      const { payload: enriched, summary } = enrichStatuslinePayload({ payload, env: process.env, snapshot, account, providerName, nowMs, headroom, routedTarget });
       const renderer = process.env.AGENT_SHIM_STATUSLINE_CMD;
       if (renderer !== void 0 && renderer !== "") {
         const child = (0, import_node_child_process7.spawn)("/bin/sh", ["-c", renderer], { stdio: ["pipe", "inherit", "inherit"] });
@@ -147539,6 +147639,52 @@ function sameFamilyOtherVersion(a10, b) {
 
 // src/models.ts
 init_modelsStore();
+init_realPorts();
+init_read();
+init_quotaFacts();
+init_engine();
+function providerQuotaOf(paths) {
+  const newest = /* @__PURE__ */ new Map();
+  for (const name of realFarmFs.readdir(paths.usageSnapshotsDir)) {
+    if (!name.endsWith(".json")) {
+      continue;
+    }
+    const identity = name.slice(0, -".json".length);
+    const snapshot = readUsageSnapshot(realFarmFs, paths.usageSnapshotsDir, identity);
+    if (snapshot === void 0) {
+      continue;
+    }
+    for (const provider of Object.keys(snapshot.providers)) {
+      const known = newest.get(provider);
+      if (known === void 0 || snapshot.updatedAt.localeCompare(known.updatedAt) > 0) {
+        newest.set(provider, snapshot);
+      }
+    }
+  }
+  return (provider) => {
+    const snapshot = newest.get(provider);
+    return snapshot === void 0 ? {} : quotaFactsOf(snapshot.providers[provider]?.rateLimit?.unified, Date.now());
+  };
+}
+function explainVirtualModel(paths, name) {
+  const models = readModels(paths);
+  const definition = models?.virtual?.[name];
+  if (definition === void 0) {
+    throw new UsageError(`No virtual model named "${name}".`);
+  }
+  const quotaOf = providerQuotaOf(paths);
+  const observations = createTargetObservationStore(realFarmFs, paths);
+  const candidates = expandMembers(name, models).filter((member) => !member.startsWith("acct:") && !member.startsWith("family:")).map((ref, order) => {
+    const [provider] = ref.split("/");
+    return candidateOf(ref, order, { quota: quotaOf(provider ?? ""), ...observations.observation(ref) === void 0 ? {} : { observation: observations.observation(ref) }, ...models?.prices?.[ref] === void 0 ? {} : { price: models.prices[ref] } }, false);
+  });
+  const evaluated = candidates.map((candidate) => ({ candidate, capabilities: { vision: true, tools: true, thinking: true } }));
+  const selection = selectMember(definition.mode, evaluated, {});
+  console.log(`${name} (${definition.mode}) chooses ${selection.ref ?? "nothing"}:`);
+  for (const line of selection.reasons) {
+    console.log(`  ${line}`);
+  }
+}
 function providerModels(paths) {
   return listProviders(paths).flatMap((entry) => {
     const catalogue = parseCatalogueCache(realFsPort.readFileUtf8(catalogueCachePath(paths, entry.name)));
@@ -147573,6 +147719,12 @@ function matchModels(models) {
 function registerModelsCommand(program2, deps) {
   const { paths } = deps;
   const modelsCommand = program2.command("model").description("Define and inspect the models the providers offer and the virtual models chosen among them.");
+  withExamples(
+    modelsCommand.command("explain <name>").description("Show which member a virtual model's mode picks over the live signals, and why each candidate stands where it does.").action((name) => {
+      explainVirtualModel(paths, name);
+    }),
+    ["agent-shim model explain fast"]
+  );
   withExamples(modelsCommand, ["agent-shim model match", "agent-shim model add fast --mode soonest-reset --member z/glm-5.3 --member m/MiniMax-M3"]);
   withExamples(
     modelsCommand.command("match").description("List every model every provider offers, grouped into the ones that are the same model across providers, with the pairs that are merely similar named beside them.").option("--json", "Print the match as JSON."),

package/dist/index.cjs

@@ -3106,7 +3106,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "claude-use",
-      version: "11.39.0",
+      version: "11.40.0",
       description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
       license: "MIT",
       author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -6063,6 +6063,7 @@ function createUsageStore(deps) {
       }
       fs13.appendFilePrivate(import_node_path20.default.join(paths.usageLogDir, segmentName(day, deps.pid)), `${JSON.stringify(record)}
 `);
+      deps.onRecord?.(record);
       if (record.identity !== void 0) {
         rewriteSnapshot(record.identity, (current) => ({ ...current?.providers, [record.provider]: foldProviderState(current?.providers[record.provider], record) }));
       }

package/dist/index.mjs

@@ -3082,7 +3082,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "claude-use",
-      version: "11.39.0",
+      version: "11.40.0",
       description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
       license: "MIT",
       author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -6038,6 +6038,7 @@ function createUsageStore(deps) {
       }
       fs13.appendFilePrivate(path20.join(paths.usageLogDir, segmentName(day, deps.pid)), `${JSON.stringify(record)}
 `);
+      deps.onRecord?.(record);
       if (record.identity !== void 0) {
         rewriteSnapshot(record.identity, (current) => ({ ...current?.providers, [record.provider]: foldProviderState(current?.providers[record.provider], record) }));
       }