@kal-elsam/kairo-runtime 0.26.1 → 0.28.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.28.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. `/models --verify-access` verifies Claude model entitlement on demand.
+
+### Added
+
+- `/models --verify-access [--refresh]` — sequential, human-triggered Claude
+  entitlement probes with a real cost statement before any spawn. Without
+  `--refresh`, only unverified or TTL-expired models are probed; an all-
+  unverified sweep does not persist evidence.
+- One-line Spanish preflight notice when Claude models still have unverified
+  access (recommendable, never auto-launched).
+
+## 0.27.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. Claude model entitlement now gates PROJECT TEAM pools and routes.
+
+### Changed
+
+- Denied Claude models (e.g. Fable 5.1 on Pro with `credits_required`) are
+  excluded from both the recommendation and automatic execution pools —
+  orthogonal to `accessMode`, so a denied model is never mislabeled "manual".
+- Unverified Claude models stay recommendable but are never auto-launchable.
+- Live entitlement also blocks a persisted project-team assignment whose
+  account access is denied or unverified; `snapshot()` still only reads the
+  disk cache (never probes).
+
 ## 0.26.1 — 2026-09-19 (Kairo Runtime)
 
 Patch release. Claude model entitlement probe + cache (no routing change yet).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/src/global/cockpit/app.js

@@ -258,7 +258,7 @@ export async function runCockpitApp({
       // blocks with no indication of which command produced which one.
       pushTranscript("user", task);
       if (command === "/help") {
-        pushTranscript("kairo", "Shift+Tab cycles ASK/PLAN/AGENT · /project interactive overlay (or analyze/analyst/approve/refresh/status/cursor exhausted|available subcommands for scripted use) · /plan <task> force a plan · /usage automatic-provider status (Codex/Claude/Go) · /providers all connections incl. Zen/Cursor (manual) · /models CAPABILITY + EFFICIENT picks (--evidence for raw metrics) · /why eligibility detail · /clear · /quit");
+        pushTranscript("kairo", "Shift+Tab cycles ASK/PLAN/AGENT · /project interactive overlay (or analyze/analyst/approve/refresh/status/cursor exhausted|available subcommands for scripted use) · /plan <task> force a plan · /usage automatic-provider status (Codex/Claude/Go) · /providers all connections incl. Zen/Cursor (manual) · /models CAPABILITY + EFFICIENT picks (--evidence for raw metrics; --verify-access [--refresh] for Claude entitlement) · /why eligibility detail · /clear · /quit");
       } else if (command === "/usage") {
         for (const line of view.usageLines()) pushTranscript("kairo", line);
       } else if (command === "/providers") {
@@ -271,8 +271,38 @@ export async function runCockpitApp({
         // the plain-language why (capability, efficient alternative,
         // fallback), never raw metrics/percentages/ids/sources. Those
         // stay behind the explicit --evidence flag for technical audit.
-        const flag = task.slice(command.length).trim();
-        const explainLines = flag === "--evidence" ? view.aiTeamDetailLines() : view.modelsExplainLines();
+        // --verify-access [--refresh] is the only path that spawns Claude
+        // entitlement probes (never on snapshot / first poll).
+        const flags = new Set(task.slice(command.length).trim().split(/\s+/).filter(Boolean));
+        if (flags.has("--verify-access")) {
+          const refresh = flags.has("--refresh");
+          editor.disableSubmit = true;
+          editor.setText("");
+          return runAction("Verifying Claude model access", async () => {
+            const summary = await service.verifyClaudeEntitlements({
+              cwd,
+              refresh,
+              beforeProbe: ({ costStatement }) => {
+                pushTranscript("kairo", costStatement);
+              },
+              onProgress: ({ modelId, index, total }) => {
+                view.beginAction(`Verifying Claude access (${index + 1}/${total}): ${modelId}`);
+              }
+            });
+            const allowed = summary.results.filter((r) => r.status === "allowed").length;
+            const denied = summary.results.filter((r) => r.status === "denied").length;
+            const unverified = summary.results.filter((r) => r.status === "unverified").length;
+            if (summary.probed.length === 0) {
+              pushTranscript("kairo", "Claude access already verified for the current catalog (use --refresh to re-probe).");
+            } else {
+              pushTranscript(
+                "kairo",
+                `Claude access check: ${summary.probed.length} probed · ${allowed} allowed · ${denied} denied · ${unverified} unverified${summary.persisted ? " · cache updated" : " · cache unchanged"}.`
+              );
+            }
+          }).finally(() => { editor.disableSubmit = false; });
+        }
+        const explainLines = flags.has("--evidence") ? view.aiTeamDetailLines() : view.modelsExplainLines();
         for (const line of explainLines) pushTranscript("kairo", line);
       } else if (command === "/why") {
         // Drill-down for FIT: which providers were excluded and the exact
@@ -318,6 +348,9 @@ export async function runCockpitApp({
           return runAction("Analyzing project locally (read-only)", async () => {
             const preflight = await service.preflightProject({ cwd });
             view.pendingProjectAnalysis = preflight;
+            if (preflight.unverifiedClaudeNotice) {
+              pushTranscript("kairo", preflight.unverifiedClaudeNotice);
+            }
             if (!preflight.alternatives.length) {
               pushTranscript("kairo", "No real Project Analyst candidate is available right now (ASK only supports Codex/Claude today).");
               return;

package/src/global/cockpit/project-overlay.js

@@ -160,6 +160,9 @@ export class ProjectOverlay {
     this.view.beginAction("Reading project evidence locally");
     try {
       this.preflight = await this.service.preflightProject({ cwd: this.cwd });
+      if (this.preflight.unverifiedClaudeNotice) {
+        this.onNarrate?.(this.preflight.unverifiedClaudeNotice);
+      }
       const models = this.preflight.analystCatalog?.models ?? [];
       if (!models.length) {
         this.state = S.NO_ANALYST;

package/src/global/conversation/bootstrap-analyzer-adapters.js

@@ -39,6 +39,7 @@ import {
 } from "./codex-sandbox.js";
 import { verifyClaudeSubscriptionAuth as defaultVerifyClaudeSubscriptionAuth } from "../runtime/execution-adapters/claude.js";
 import { readClaudeModels as defaultReadClaudeModels } from "../observability/claude-models.js";
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
 import { readCursorModels as defaultReadCursorModels } from "../observability/cursor-models.js";
 import { probeCursorAuth as defaultProbeCursorAuth } from "../observability/cursor-auth.js";
 import {
@@ -114,6 +115,18 @@ export function createClaudeBootstrapAnalyzerAdapter({ modelId, deps = {} } = {}
         if (!known) {
           return { eligible: false, reason: `"${modelId}" is not in Claude's documented model catalog.`, isolation: "unverified", canaryTested: false };
         }
+        // Live per-model entitlement (when the caller supplies it) — denied
+        // siblings fail with the real CLI reason, never a silent pass after
+        // the documented-catalog check. Missing map/key does not invent denial.
+        const entitlement = deps.modelEntitlement?.[modelId];
+        if (entitlement?.status === ENTITLEMENT.DENIED) {
+          return {
+            eligible: false,
+            reason: entitlement.reason ?? `"${modelId}" is denied by Claude account entitlement.`,
+            isolation: "unverified",
+            canaryTested: false
+          };
+        }
       }
       return { eligible: true, isolation: "restricted", canaryTested: true };
     },

package/src/global/conversation/project-router.js

@@ -19,6 +19,8 @@
 // persisted, not recomputed) — this module only checks whether that
 // persisted candidate is STILL real-eligible right now.
 
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
+
 /**
  * Whether Kairo can launch an automatic run against this real candidate
  * right now — reads model-candidate-catalog.js's own `accessMode`
@@ -39,16 +41,46 @@ export const PROJECT_ROUTE_DECISION = {
   WAIT_FOR_PROJECT_TEAM: "WAIT_FOR_PROJECT_TEAM"
 };
 
+const ROUTABLE_ENTITLEMENTS = new Set([ENTITLEMENT.ALLOWED, ENTITLEMENT.NOT_APPLICABLE]);
+
 function assignmentRef(model, assignmentSource) {
   if (!model) return null;
   return { provider: model.adapterId, model, assignmentSource };
 }
 
-/** A real candidate is only ever offered as `suggestedAlternative` when it's currently automatically-executable — the same bar ROUTED itself requires. Never suggests another manual-only or currently-ineligible provider; honestly null instead. */
-function routableAlternative(model, eligibility) {
+/**
+ * Live entitlement gate: only when `modelEntitlement[modelId]` is PRESENT
+ * and status is denied or unverified. Missing key (empty `{}`) keeps
+ * existing callers/tests green — no gate.
+ * @param {object} model
+ * @param {Record<string, {status?: string, reason?: string|null}>} modelEntitlement
+ * @returns {{status: string, reason: string|null}|null}
+ */
+function blockingEntitlement(model, modelEntitlement) {
+  const entry = modelEntitlement?.[model?.modelId];
+  if (!entry || typeof entry !== "object") return null;
+  if (entry.status === ENTITLEMENT.DENIED || entry.status === ENTITLEMENT.UNVERIFIED) {
+    return {
+      status: entry.status,
+      reason: entry.reason == null ? null : String(entry.reason)
+    };
+  }
+  return null;
+}
+
+/**
+ * Fallback may only be suggested when it is currently automatically
+ * executable AND its entitlement is allowed/not_applicable — or the key
+ * is missing (default ok). Denied/unverified fallbacks stay null.
+ */
+function routableAlternative(model, eligibility, modelEntitlement = {}) {
   if (!model) return null;
   if (!isAutomatic(model)) return null;
   if (eligibility[model.adapterId]?.ok !== true) return null;
+  const entry = modelEntitlement?.[model.modelId];
+  if (entry && typeof entry === "object" && !ROUTABLE_ENTITLEMENTS.has(entry.status)) {
+    return null;
+  }
   return { provider: model.adapterId, model };
 }
 
@@ -80,6 +112,10 @@ function blocked(role, strategyFingerprint, why, { blockedAssignment = null, sug
  *    MANUAL_HANDOFF, still naming the real model/provider so the caller
  *    can show a concrete handoff ("Continue in Cursor with <model>"),
  *    never a bare "not supported".
+ * 3.5 Live model entitlement (when `modelEntitlement[modelId]` is present
+ *    and status is denied or unverified) -> WAIT_FOR_PROJECT_TEAM with
+ *    blockedAssignment naming the real CLI reason when available.
+ *    Empty `{}` skips this gate.
  * 4. The assigned provider isn't currently eligible (quota/availability
  *    changed since the strategy was approved) -> WAIT_FOR_PROJECT_TEAM,
  *    with `blockedAssignment` naming the real unavailable model/reason and
@@ -103,9 +139,12 @@ function blocked(role, strategyFingerprint, why, { blockedAssignment = null, sug
  * @param {Record<string, {ok: boolean, reason?: string}>} [args.eligibility] -
  *   CURRENT provider eligibility — may have changed since the strategy was
  *   built/approved.
+ * @param {Record<string, {status?: string, reason?: string|null}>} [args.modelEntitlement] -
+ *   live per-model Claude entitlement map (modelId → {status, reason}).
+ *   Empty `{}` (default) does not gate — keeps pre-entitlement callers green.
  * @returns {{decision: "ROUTED"|"MANUAL_HANDOFF"|"WAIT_FOR_PROJECT_TEAM", role: string, provider: string|null, model: object|null, assignmentSource: string|null, strategyFingerprint: string|null, blockedAssignment: {provider: string, model: object, assignmentSource: string}|null, suggestedAlternative: {provider: string, model: object}|null, why: string}}
  */
-export function resolveProjectRoute({ role, strategy, eligibility = {} }) {
+export function resolveProjectRoute({ role, strategy, eligibility = {}, modelEntitlement = {} }) {
   const strategyFingerprint = strategy?.profileFingerprint ?? null;
 
   if (!strategy) {
@@ -133,9 +172,25 @@ export function resolveProjectRoute({ role, strategy, eligibility = {} }) {
     };
   }
 
+  const entitlementBlock = blockingEntitlement(model, modelEntitlement);
+  if (entitlementBlock) {
+    const reason = entitlementBlock.reason
+      ?? (entitlementBlock.status === ENTITLEMENT.DENIED
+        ? "account entitlement denied"
+        : "account entitlement unverified");
+    const suggestedAlternative = routableAlternative(fallback, eligibility, modelEntitlement);
+    const why = suggestedAlternative
+      ? `${model.displayName ?? model.modelId} is not currently entitled (${reason}) — no automatic substitution; confirm the suggested alternative for ${role} before proceeding.`
+      : `${model.displayName ?? model.modelId} is not currently entitled (${reason}) — no automatic alternative is available for ${role} right now.`;
+    return blocked(role, strategyFingerprint, why, {
+      blockedAssignment: assignmentRef(model, assignmentSource),
+      suggestedAlternative
+    });
+  }
+
   if (eligibility[model.adapterId]?.ok !== true) {
     const reason = eligibility[model.adapterId]?.reason ?? "unknown reason";
-    const suggestedAlternative = routableAlternative(fallback, eligibility);
+    const suggestedAlternative = routableAlternative(fallback, eligibility, modelEntitlement);
     const why = suggestedAlternative
       ? `${model.adapterId} is not currently eligible (${reason}) — no automatic substitution; confirm the suggested alternative for ${role} before proceeding.`
       : `${model.adapterId} is not currently eligible (${reason}) — no automatic alternative is available for ${role} right now.`;

package/src/global/conversation/service.js

@@ -39,6 +39,17 @@ import { readProviderUsage, writeProviderUsage } from "../runtime/usage-store.js
 import { resolveProjectRoute } from "./project-router.js";
 import { readArtificialAnalysisModels } from "../observability/artificial-analysis-models.js";
 import { readHuggingFaceLeaderboard } from "../observability/huggingface-leaderboard.js";
+import {
+  DEFAULT_ENTITLEMENT_TTL_MS,
+  mergeEntitlementResults,
+  readClaudeEntitlementCache,
+  resolveClaudeEntitlements,
+  writeClaudeEntitlementCache
+} from "../observability/claude-entitlement-store.js";
+import {
+  ENTITLEMENT,
+  probeClaudeModelEntitlements
+} from "../observability/claude-model-entitlement.js";
 import {
   annotateWithRegistryEvidence, bestEfficientModelPerRoleGlobal, bestModelPerRole, bestModelPerRoleGlobal, buildAiTeam,
   buildEfficientTeam, scoreAvailableModels, summarizeCatalogCoverage
@@ -59,6 +70,35 @@ export const CONVERSATION_SCHEMA = "kairo.conversation/v1";
 // 30s default.
 const BOOTSTRAP_ANALYST_TIMEOUT_MS = 180_000;
 
+/** Max Claude entitlement probes per `/models --verify-access` sweep. */
+const CLAUDE_ENTITLEMENT_MAX_PROBES = 12;
+
+/**
+ * Cost statement printed before any Claude entitlement spawn. Economy is
+ * measured: denied probes cost $0; allowed ones about one cent each.
+ * @param {{ pendingCount?: number }} [options]
+ */
+export function buildClaudeEntitlementVerifyCostStatement({ pendingCount = 0 } = {}) {
+  const n = Math.max(0, Number(pendingCount) || 0);
+  if (n <= 0) {
+    return "No Claude models need access verification right now (denied probes cost $0; allowed ones about one cent each).";
+  }
+  return `About to verify ${n} Claude model${n === 1 ? "" : "s"}: models your plan denies cost $0; allowed ones cost about one cent each.`;
+}
+
+/**
+ * One-line preflight notice when unverified Claude models exist.
+ * @param {number} count
+ */
+export function buildUnverifiedClaudePreflightNotice(count) {
+  const n = Math.max(0, Number(count) || 0);
+  return `${n} modelos de Claude tienen acceso sin verificar — se pueden recomendar pero nunca lanzar automáticamente. Corré /models --verify-access para verificar (los que tu plan deniega cuestan $0; los permitidos, alrededor de un centavo cada uno).`;
+}
+
+function isPersistableEntitlementStatus(status) {
+  return status === ENTITLEMENT.ALLOWED || status === ENTITLEMENT.DENIED;
+}
+
 function publicPlan(record, execution = null) {
   const status = record.status ?? record;
   return {
@@ -299,6 +339,11 @@ export function createConversationService(deps = {}) {
   // disk (no network call) but still shouldn't re-scan on every 2s poll.
   const huggingFaceLeaderboardTtlMs = deps.huggingFaceLeaderboardTtlMs ?? 6 * 60 * 60_000;
   const telemetryTtlMs = deps.telemetryTtlMs ?? 30_000;
+  // Claude entitlement disk cache is stable for days; subscription auth is
+  // a real CLI spawn (~10s) — cache both so snapshot() polls never re-probe
+  // per-model entitlement (that lives behind /models --verify-access).
+  const claudeEntitlementCacheTtlMs = deps.claudeEntitlementCacheTtlMs ?? 600_000;
+  const claudeSubscriptionAuthTtlMs = deps.claudeSubscriptionAuthTtlMs ?? 10_000;
   const now = deps.now ?? (() => Date.now());
 
   // Shared TTL + in-flight-dedupe cache for both provider usage probes:
@@ -341,6 +386,22 @@ export function createConversationService(deps = {}) {
   const readOpenCodeUsageCached = createCachedProbe(readOpenCodeUsageImpl, opencodeUsageTtlMs);
   const readOpenCodeGoCached = createCachedProbe(readOpenCodeGoImpl, opencodeGoUsageTtlMs);
   const readOpenCodeStatsCached = createCachedProbe(readOpenCodeStatsImpl, opencodeUsageTtlMs);
+  const readClaudeEntitlementCacheImpl = deps.readClaudeEntitlementCache ?? readClaudeEntitlementCache;
+  const writeClaudeEntitlementCacheImpl = deps.writeClaudeEntitlementCache ?? writeClaudeEntitlementCache;
+  const mergeEntitlementResultsImpl = deps.mergeEntitlementResults ?? mergeEntitlementResults;
+  const probeClaudeModelEntitlementsImpl = deps.probeClaudeModelEntitlements ?? probeClaudeModelEntitlements;
+  const readClaudeEntitlementCacheCached = createCachedProbe(
+    () => readClaudeEntitlementCacheImpl(homeDir), claudeEntitlementCacheTtlMs
+  );
+  // Auth spawn is slow; never re-run on every poll. Failures cache as null
+  // so resolveClaudeEntitlements treats subscription as mismatched/absent.
+  const verifyClaudeSubscriptionAuthCached = createCachedProbe(async () => {
+    try {
+      return await verifyClaudeSubscriptionAuthImpl({});
+    } catch {
+      return null;
+    }
+  }, claudeSubscriptionAuthTtlMs);
 
   async function executionFor(projectRoot, taskId) {
     const link = await readExecution(projectRoot, taskId);
@@ -459,11 +520,13 @@ export function createConversationService(deps = {}) {
       // explicit /project analyze or /project refresh.
       result.projectStrategy = await readProjectStrategyImpl(homeDir, projectRoot);
       if (enableProviderProbes) {
-        const [codexCatalog, opencodeGoCatalog, cursorCatalog, aa] = await Promise.all([
+        const [codexCatalog, opencodeGoCatalog, cursorCatalog, aa, entitlementCache, claudeAuth] = await Promise.all([
           readCodexModelsCached(projectRoot, { cwd: projectRoot }),
           readOpenCodeGoModelsCached("global", {}),
           readCursorModelsCached(projectRoot, { cwd: projectRoot }),
-          readArtificialAnalysisModelsCached("global", {})
+          readArtificialAnalysisModelsCached("global", {}),
+          readClaudeEntitlementCacheCached("global", {}),
+          verifyClaudeSubscriptionAuthCached("global", {})
         ]);
         // Same eligibility policy the execution/ask router uses, with one
         // deliberate exception: opencode-go is allowed here even without
@@ -489,6 +552,14 @@ export function createConversationService(deps = {}) {
           if (check.ok) candidates.push(adapterId);
         }
         const claudeCatalog = readClaudeModelsImpl();
+        // Cache-only resolve — never probeClaudeModelEntitlement* from snapshot().
+        const claudeEntitlement = resolveClaudeEntitlements({
+          cache: entitlementCache,
+          subscriptionType: claudeAuth?.subscriptionType ?? null,
+          catalogIds: (claudeCatalog.models ?? []).map((m) => m.id),
+          now: now(),
+          ttlMs: deps.claudeEntitlementTtlMs ?? DEFAULT_ENTITLEMENT_TTL_MS
+        });
         const catalogsByAdapter = {
           codex: codexCatalog?.models ?? [],
           claude: claudeCatalog.models,
@@ -515,7 +586,8 @@ export function createConversationService(deps = {}) {
         // exact same real provider catalogs scoredAllRaw itself came from.
         const completeCandidateCatalog = buildCompleteCandidateCatalog(
           Object.keys(catalogsByAdapter).map((adapterId) => ({ adapterId, models: catalogsByAdapter[adapterId] ?? [] })),
-          aa.models
+          aa.models,
+          { modelEntitlement: claudeEntitlement }
         );
         // The Recommendation Pool: scoredAllRaw joined with its real
         // identity, with genuinely superseded generations excluded —
@@ -606,6 +678,8 @@ export function createConversationService(deps = {}) {
           status: aa.status, source: aa.source, age: aa.age,
           models: annotateWithRegistryEvidence(scored, registry), roles: bestModelPerRole(scored),
           eligibility, coverage, unscoredModels,
+          // Resolved Claude per-model entitlement (cache-only; never probed here).
+          claudeEntitlement,
           // BEST FIT GLOBAL / EFFICIENT GLOBAL: the honest, uncoordinated
           // per-role winner — never cedes a role for portfolio diversity,
           // family concentration, or provider distribution (see
@@ -781,11 +855,96 @@ export function createConversationService(deps = {}) {
       const projectRoot = await root(cwd);
       const profile = await computeProjectProfileImpl({ cwd: projectRoot });
       const snap = await this.snapshot({ cwd: projectRoot });
-      const { scoredAll = [], eligibility = {}, registry = null, providerCapacity = null, unscoredModels = [] } = snap.modelIntelligence ?? {};
-      const candidates = { scoredAll, eligibility, registry, providerCapacity };
+      const { scoredAll = [], eligibility = {}, registry = null, providerCapacity = null, unscoredModels = [], claudeEntitlement = {} } = snap.modelIntelligence ?? {};
+      const candidates = { scoredAll, eligibility, registry, providerCapacity, claudeEntitlement };
       const alternatives = computeBootstrapAnalystAlternatives(candidates);
       const analystCatalog = computeBootstrapAnalystCatalog({ ...candidates, unscoredModels });
-      return { profile, alternatives, candidates, analystCatalog, projectRoot };
+      const unverifiedCount = Object.values(claudeEntitlement).filter(
+        (entry) => entry?.status === ENTITLEMENT.UNVERIFIED
+      ).length;
+      const unverifiedClaudeNotice = unverifiedCount > 0
+        ? buildUnverifiedClaudePreflightNotice(unverifiedCount)
+        : null;
+      return { profile, alternatives, candidates, analystCatalog, projectRoot, unverifiedClaudeNotice };
+    },
+    /**
+     * `/models --verify-access [--refresh]`: the only service path that
+     * spawns `probeClaudeModelEntitlements`. Without refresh, only
+     * unverified / TTL-expired catalog ids are probed; with refresh, every
+     * catalog id is probed (still capped at maxProbes=12). Persist only when
+     * at least one allowed/denied result exists — an all-unverified sweep
+     * never invents evidence on disk.
+     *
+     * @param {object} args
+     * @param {string} args.cwd
+     * @param {boolean} [args.refresh]
+     * @param {(info: { pendingCount: number, pendingIds: string[], costStatement: string }) => (void|Promise<void>)} [args.beforeProbe]
+     *   Called after the probe set is known and BEFORE any spawn — app.js
+     *   prints the cost statement here.
+     * @param {(info: { modelId: string, index: number, total: number, result: object }) => void} [args.onProgress]
+     */
+    async verifyClaudeEntitlements({ cwd, refresh = false, beforeProbe = null, onProgress = null } = {}) {
+      const projectRoot = cwd ? await root(cwd) : null;
+      const catalog = readClaudeModelsImpl();
+      const catalogIds = (catalog.models ?? []).map((m) => m.id).filter(Boolean);
+      let auth = null;
+      try {
+        auth = await verifyClaudeSubscriptionAuthImpl({});
+      } catch {
+        auth = null;
+      }
+      const subscriptionType = auth?.subscriptionType ?? null;
+      const cache = await readClaudeEntitlementCacheImpl(homeDir);
+      const nowMs = now();
+      const ttlMs = deps.claudeEntitlementTtlMs ?? DEFAULT_ENTITLEMENT_TTL_MS;
+      const resolved = resolveClaudeEntitlements({
+        cache,
+        subscriptionType,
+        catalogIds,
+        now: nowMs,
+        ttlMs
+      });
+      const pendingIds = (refresh
+        ? catalogIds
+        : catalogIds.filter((id) => resolved[id]?.status === ENTITLEMENT.UNVERIFIED)
+      ).slice(0, CLAUDE_ENTITLEMENT_MAX_PROBES);
+      const costStatement = buildClaudeEntitlementVerifyCostStatement({ pendingCount: pendingIds.length });
+      if (typeof beforeProbe === "function") {
+        await beforeProbe({ pendingCount: pendingIds.length, pendingIds, costStatement });
+      }
+      if (pendingIds.length === 0) {
+        return {
+          probed: [],
+          results: [],
+          costStatement,
+          persisted: false,
+          pendingCount: 0,
+          refresh: Boolean(refresh),
+          subscriptionType
+        };
+      }
+      const results = await probeClaudeModelEntitlementsImpl({
+        modelIds: pendingIds,
+        maxProbes: CLAUDE_ENTITLEMENT_MAX_PROBES,
+        cwd: projectRoot ?? process.cwd(),
+        onProgress
+      });
+      const hasPersistable = results.some((result) => isPersistableEntitlementStatus(result?.status));
+      let persisted = false;
+      if (hasPersistable) {
+        const merged = mergeEntitlementResultsImpl(cache, { subscriptionType, results });
+        await writeClaudeEntitlementCacheImpl(homeDir, merged);
+        persisted = true;
+      }
+      return {
+        probed: pendingIds,
+        results,
+        costStatement,
+        persisted,
+        pendingCount: pendingIds.length,
+        refresh: Boolean(refresh),
+        subscriptionType
+      };
     },
     /**
      * `/project analyst quality|efficient --confirm` (ANALYZING -> SUGGESTED):
@@ -826,7 +985,8 @@ export function createConversationService(deps = {}) {
           modelId: analyst.model.modelId,
           deps: {
             askProvider: askProviderImpl, runCodexSandboxedBootstrap: runCodexSandboxedBootstrapImpl, isolationDeps: codexIsolationDeps,
-            verifyClaudeSubscriptionAuth: verifyClaudeSubscriptionAuthImpl, readClaudeModels: readClaudeModelsImpl
+            verifyClaudeSubscriptionAuth: verifyClaudeSubscriptionAuthImpl, readClaudeModels: readClaudeModelsImpl,
+            modelEntitlement: candidates?.claudeEntitlement ?? {}
           }
         });
         const eligibility = await adapter.checkEligibility();
@@ -1007,7 +1167,8 @@ export function createConversationService(deps = {}) {
       const strategy = await readProjectStrategyImpl(homeDir, projectRoot);
       const snap = await this.snapshot({ cwd: projectRoot });
       const eligibility = snap.modelIntelligence?.eligibility ?? {};
-      return resolveProjectRoute({ role, strategy, eligibility });
+      const modelEntitlement = snap.modelIntelligence?.claudeEntitlement ?? {};
+      return resolveProjectRoute({ role, strategy, eligibility, modelEntitlement });
     },
     /**
      * Read-only preview of what executePlan would do right now.

package/src/global/intelligence/model-candidate-catalog.js

@@ -31,8 +31,11 @@
 // anything downstream just because its lineage couldn't be determined.
 
 import { matchArtificialAnalysisScore } from "./model-intelligence.js";
+import { ENTITLEMENT } from "../observability/claude-model-entitlement.js";
 
 /**
+ * @typedef {"allowed"|"denied"|"unverified"|"not_applicable"} ModelEntitlementStatus
+ *
  * @typedef {object} ModelCandidateIdentity
  * @property {string} candidateKey - `${adapterId}::${modelId}`, this catalog's stable identity key.
  * @property {string} modelId - the exact provider-reported id — what scoring/execution actually use, never the cleaned name.
@@ -40,6 +43,8 @@ import { matchArtificialAnalysisScore } from "./model-intelligence.js";
  * @property {string} rawDisplayName - the provider's own displayName, completely unmodified — the real evidence modelName was derived from. Whatever stripDisplayVariant peeled off (effort/context/privacy tokens) to produce modelName is still visible here, never a separate field: /models --evidence's own "technical detail" is just this string.
  * @property {string} adapterId - "codex" | "claude" | "cursor" | "opencode-go".
  * @property {"automatic"|"manual"} accessMode - whether Kairo can actually launch this candidate itself right now, or whether it's a real, recommendable option the human runs manually (Cursor's own "auto" router model always; OpenCode Zen always, pending its own Go/Zen billing-attribution proof — see this module's own doc). Named Cursor and OpenCode Go models are automatic.
+ * @property {ModelEntitlementStatus} entitlement - orthogonal to accessMode. Codex/Cursor/OpenCode Go/Zen are `not_applicable` (their catalog IS access proof). Claude comes from the live entitlement map, or `unverified` when that map has no entry.
+ * @property {string|null} entitlementReason - real CLI/reason string when entitlement is denied/unverified with a message; otherwise null.
  * @property {"scored"|"partial"|"unscored"} evidenceStatus - "scored": AA matched this exact model AND reports at least one of intelligenceIndex/codingIndex. "partial": AA matched it but both composite indices are null (real match, thin evidence). "unscored": no confident AA match at all. Never role-specific — see this module's own doc for why.
  * @property {string|null} lineageKey - real, recognized model family/lineage (see LINEAGE_PARSERS) — null when the modelId doesn't match any recognized, conservative pattern. Never guessed.
  * @property {number|null} generation - a real, comparable version number within that lineage — null whenever lineageKey is null.
@@ -47,6 +52,39 @@ import { matchArtificialAnalysisScore } from "./model-intelligence.js";
  * @property {{inputPerMTok: number, outputPerMTok: number}|null} resourceCost - real, provider-reported cost, when the provider actually reports one (OpenCode Go today) — never estimated or carried over from a different model.
  */
 
+const AUTOMATIC_ENTITLEMENTS = new Set([ENTITLEMENT.ALLOWED, ENTITLEMENT.NOT_APPLICABLE]);
+
+/**
+ * Resolves per-model entitlement orthogonal to accessMode.
+ * Non-Claude adapters: not_applicable (catalog presence is access proof).
+ * Claude: from deps.modelEntitlement[modelId], or unverified when missing.
+ * @param {string} adapterId
+ * @param {string} modelId
+ * @param {Record<string, {status?: string, reason?: string|null}>} [modelEntitlement]
+ * @returns {{entitlement: ModelEntitlementStatus, entitlementReason: string|null}}
+ */
+function resolveEntitlement(adapterId, modelId, modelEntitlement = {}) {
+  if (adapterId !== "claude") {
+    return { entitlement: ENTITLEMENT.NOT_APPLICABLE, entitlementReason: null };
+  }
+  const entry = modelEntitlement[modelId];
+  if (!entry || typeof entry !== "object") {
+    return { entitlement: ENTITLEMENT.UNVERIFIED, entitlementReason: null };
+  }
+  const status = entry.status;
+  if (
+    status === ENTITLEMENT.ALLOWED
+    || status === ENTITLEMENT.DENIED
+    || status === ENTITLEMENT.UNVERIFIED
+  ) {
+    return {
+      entitlement: status,
+      entitlementReason: entry.reason == null ? null : String(entry.reason)
+    };
+  }
+  return { entitlement: ENTITLEMENT.UNVERIFIED, entitlementReason: null };
+}
+
 // Real variant tokens observed across the four live provider catalogs
 // this session audited (Cursor's 223-model catalog especially — the only
 // source that embeds these directly into displayName text, with no
@@ -332,16 +370,18 @@ function resolveResourceCost(rawModel) {
  * @param {{id: string, displayName?: string}} rawModel
  * @param {Array<object>} aaModels
  * @param {(modelId: string, aaModels: Array<object>) => object|null} matcher
+ * @param {Record<string, {status?: string, reason?: string|null}>} [modelEntitlement]
  * @returns {ModelCandidateIdentity}
  */
-function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher) {
+function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher, modelEntitlement = {}) {
   const modelId = rawModel.id;
   const rawDisplayName = rawModel.displayName ?? modelId;
+  const { entitlement, entitlementReason } = resolveEntitlement(adapterId, modelId, modelEntitlement);
 
   if (adapterId === "cursor" && modelId === "auto") {
     return {
       candidateKey: `${adapterId}::${modelId}`, modelId, modelName: "Cursor Auto", rawDisplayName,
-      adapterId, accessMode: "manual", evidenceStatus: "unscored",
+      adapterId, accessMode: "manual", entitlement, entitlementReason, evidenceStatus: "unscored",
       lineageKey: null, generation: null, lifecycle: "unknown", resourceCost: null
     };
   }
@@ -351,7 +391,8 @@ function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher) {
   const lineage = resolveLineage(modelId);
   return {
     candidateKey: `${adapterId}::${modelId}`, modelId, modelName, rawDisplayName,
-    adapterId, accessMode: resolveAccessMode(adapterId, modelId), evidenceStatus: resolveEvidenceStatus(matched),
+    adapterId, accessMode: resolveAccessMode(adapterId, modelId), entitlement, entitlementReason,
+    evidenceStatus: resolveEvidenceStatus(matched),
     // lifecycle is resolved in a second pass (applyLifecycle, called from
     // buildCompleteCandidateCatalog) once the WHOLE catalog is known —
     // "superseded" is a statement about this candidate relative to its
@@ -372,16 +413,22 @@ function buildCandidateIdentity(adapterId, rawModel, aaModels, matcher) {
  *   same shape model-intelligence.js's scoreAvailableModels takes, e.g.
  *   `[{ adapterId: "codex", models: readCodexModels().models }, ...]`.
  * @param {Array<object>} aaModels - readArtificialAnalysisModels().models
- * @param {{matchArtificialAnalysisScore?: (modelId: string, aaModels: Array<object>) => object|null}} [deps] -
+ * @param {{
+ *   matchArtificialAnalysisScore?: (modelId: string, aaModels: Array<object>) => object|null,
+ *   modelEntitlement?: Record<string, {status?: string, reason?: string|null}>
+ * }} [deps] -
  *   injectable for tests; defaults to model-intelligence.js's real export.
+ *   `modelEntitlement` is Claude-only live entitlement (allowed/denied/unverified);
+ *   missing keys leave Claude as unverified. Non-Claude adapters ignore it.
  * @returns {Array<ModelCandidateIdentity>}
  */
 export function buildCompleteCandidateCatalog(providerCatalogs, aaModels, deps = {}) {
   const matcher = deps.matchArtificialAnalysisScore ?? matchArtificialAnalysisScore;
+  const modelEntitlement = deps.modelEntitlement ?? {};
   const catalog = [];
   for (const { adapterId, models } of providerCatalogs) {
     for (const rawModel of models ?? []) {
-      catalog.push(buildCandidateIdentity(adapterId, rawModel, aaModels, matcher));
+      catalog.push(buildCandidateIdentity(adapterId, rawModel, aaModels, matcher, modelEntitlement));
     }
   }
   return applyLifecycle(catalog);
@@ -435,11 +482,20 @@ export function buildRecommendationPool(scoredAll, completeCatalog) {
     // never excludes: an un-joined candidate is treated as lineage-
     // unknown, exactly like any other real unrecognized lineage.
     if (identity?.lifecycle === "superseded") continue;
+    // Denied entitlement is the same class as superseded: never recommend.
+    // Unverified Claude stays recommendable (human can still pick it);
+    // only automatic launch excludes it (see buildAutomaticExecutionPool).
+    if (identity?.entitlement === ENTITLEMENT.DENIED) continue;
+    const fallbackEntitlement = scored.adapterId === "claude"
+      ? ENTITLEMENT.UNVERIFIED
+      : ENTITLEMENT.NOT_APPLICABLE;
     pool.push({
       ...scored,
       candidateKey,
       modelName: identity?.modelName ?? scored.displayName ?? scored.modelId,
       accessMode: identity?.accessMode ?? "manual",
+      entitlement: identity?.entitlement ?? fallbackEntitlement,
+      entitlementReason: identity?.entitlementReason ?? null,
       evidenceStatus: identity?.evidenceStatus ?? "scored",
       lineageKey: identity?.lineageKey ?? null,
       generation: identity?.generation ?? null,
@@ -459,16 +515,22 @@ export function buildRecommendationPool(scoredAll, completeCatalog) {
  * ModelCandidateIdentity's own doc) AND real,
  * current eligibility (adapter availability, quota, launchability — the
  * exact same `eligibility` object checkCandidate/execution-router.js
- * already compute, reused here rather than reimplemented). Never
- * mutates or filters the Recommendation Pool itself — a manual-only real
- * recommendation (Cursor, say) stays fully visible there; a caller that
- * wants to actually RUN a task must separately produce a real
- * "Continue in Cursor"-style handoff for it, never a silent fallback to
- * a different, automatically-launchable model the human didn't ask for.
+ * already compute, reused here rather than reimplemented) AND entitlement
+ * in {allowed, not_applicable} — denied and unverified Claude never
+ * auto-launch. Never mutates or filters the Recommendation Pool itself —
+ * a manual-only real recommendation (Cursor, say) stays fully visible
+ * there; a caller that wants to actually RUN a task must separately
+ * produce a real "Continue in Cursor"-style handoff for it, never a
+ * silent fallback to a different, automatically-launchable model the
+ * human didn't ask for.
  * @param {Array<RecommendationPoolCandidate>} recommendationPool
  * @param {Record<string, {ok: boolean, reason?: string}>} eligibility - checkCandidate() results per adapterId.
  * @returns {Array<RecommendationPoolCandidate>}
  */
 export function buildAutomaticExecutionPool(recommendationPool, eligibility) {
-  return recommendationPool.filter((candidate) => candidate.accessMode === "automatic" && eligibility[candidate.adapterId]?.ok === true);
+  return recommendationPool.filter((candidate) => (
+    candidate.accessMode === "automatic"
+    && eligibility[candidate.adapterId]?.ok === true
+    && AUTOMATIC_ENTITLEMENTS.has(candidate.entitlement)
+  ));
 }

package/src/global/observability/claude-model-entitlement.js

@@ -10,7 +10,9 @@ import { buildClaudeExecutionEnv } from "../runtime/execution-adapters/claude.js
 export const ENTITLEMENT = Object.freeze({
   ALLOWED: "allowed",
   DENIED: "denied",
-  UNVERIFIED: "unverified"
+  UNVERIFIED: "unverified",
+  // Non-Claude providers: their live/documented catalog IS access proof.
+  NOT_APPLICABLE: "not_applicable"
 });
 
 const DENIED_ERROR_CODES = new Set(["credits_required"]);

package/src/global/observability/codex-models.js

@@ -89,7 +89,7 @@ export async function readCodexModels({
     child.once?.("close", () => { if (!finished) finish(unknown("codex app-server closed before model list")); });
 
     writeRequest(child, 1, "initialize", {
-      clientInfo: { name: "kairo", title: "Kairo", version: "0.26.1" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.28.0" },
       capabilities: {}
     });
   });

package/src/global/observability/codex-usage.js

@@ -151,7 +151,7 @@ export async function readCodexUsage({
     child.once?.("close", () => { if (!finished) finish(unknown("codex app-server closed before rate limits")); });
 
     writeRequest(child, 1, "initialize", {
-      clientInfo: { name: "kairo", title: "Kairo", version: "0.26.1" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.28.0" },
       capabilities: {}
     });
   });