@kal-elsam/kairo-runtime 0.25.0 → 0.26.1

package/CHANGELOG.md

@@ -5,6 +5,35 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.26.1 — 2026-09-19 (Kairo Runtime)
+
+Patch release. Claude model entitlement probe + cache (no routing change yet).
+
+### Added
+
+- Live Claude per-model entitlement probe (`claude -p hi --model … --output-format
+  json`) with fail-closed classification (allowed / denied / unverified) and a
+  `~/.harness/claude-entitlement.json` cache invalidated by subscription type
+  change or a 7-day per-entry TTL. Pure additive — recommendation and automatic
+  pools are unchanged until the next increment wires entitlement into the catalog.
+
+## 0.26.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. ASK is now ready for every real automatic adapter.
+
+### Changed
+
+- ASK can now call OpenCode Go/Zen too — via Kairo's own real,
+  verified read-only agent ("kairo-ask"), idempotently ensured in the
+  user's global `opencode.json` (merged non-destructively). OpenCode's
+  real CLI has no flag-driven read-only mode, so this is what makes a
+  genuinely portable, config-independent guarantee possible. Live-
+  verified: it answers correctly and genuinely refuses to write a file
+  when asked directly.
+- Every real automatic PROJECT TEAM adapter (Codex, Claude, Cursor,
+  OpenCode Go, OpenCode Zen) is now ASK-capable — a role's real
+  assignment routes to ASK regardless of which one it lands on.
+
 ## 0.25.0 — 2026-09-19 (Kairo Runtime)
 
 Minor release. Cursor joins ASK.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "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/conversation/project-strategy.js

@@ -26,10 +26,18 @@ import { computeRoleEvaluations } from "../intelligence/capability-scoring.js";
 // here would be a menu item Kairo can't actually run. Exported: ASK mode's
 // own real-time routing (service.js's planAsk) needs this exact same real
 // constraint when it tries to route a plain question through a PROJECT
-// TEAM role — a role assigned to, say, opencode-go is a real, valid team
-// assignment, just not one askProvider can call (its real CLI has no
-// portable read-only mode — see quick-ask.js's own askProvider doc).
-export const ASK_SUPPORTED_ADAPTERS = new Set(["codex", "claude", "cursor"]);
+// TEAM role.
+//
+// Pure CAPABILITY (can askProvider invoke this adapter's CLI at all?),
+// never a cost-risk judgment — OpenCode Zen's real PAYG billing risk is
+// deliberately NOT re-litigated here; that's checkCandidate's own job
+// (it hard-excludes opencode-zen unconditionally), and the real
+// eligibility this module receives already reflects that exclusion. Both
+// opencode-go and opencode-zen genuinely run through the same real
+// askOpencode call (Kairo's own read-only agent — see
+// intelligence/opencode-ask-agent.js), same as real execution routing
+// already treats capability and cost-risk as two separate layers.
+export const ASK_SUPPORTED_ADAPTERS = new Set(["codex", "claude", "cursor", "opencode-go", "opencode-zen"]);
 
 /**
  * The Bootstrap Analyst as a temporary, read-only WORKFLOW — deliberately

package/src/global/intelligence/opencode-ask-agent.js

@@ -0,0 +1,74 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+
+// OpenCode's real CLI (`opencode run --help`) has no flag-driven read-only
+// mode — its permission model lives only in opencode.json (verified via
+// its own published schema, https://opencode.ai/config.json, and a real
+// working precedent already present in this machine's own global config:
+// gentle-ai/sdd's "explore" agent, which uses this exact same
+// bash/edit/task/write-deny shape to stay read-only). So a genuinely
+// portable read-only ASK call needs Kairo to own one real agent entry in
+// the user's GLOBAL opencode.json — never per-project (would pollute
+// every repo it touches) — merged in non-destructively and never
+// overwriting anything else already there.
+export const KAIRO_ASK_AGENT_NAME = "kairo-ask";
+
+// No "model" field on purpose — the real model comes from askOpencode's
+// own `--model` CLI flag per call, exactly like askCodex/askClaude/
+// askCursor already do; this agent only ever fixes the PERMISSION shape.
+// No "read" key: the same real, working "explore" agent precedent above
+// carries no explicit "read" entry either — omitted means allowed.
+//
+// Deliberately NO "__managed_by" marker (unlike the sibling "explore"
+// agent's convention this was modeled on) — verified live that it isn't
+// a real AgentConfig property at all: the real opencode.ai/config.json
+// schema never defines it, and a live `opencode run` call with it present
+// failed outright ("Unsupported parameter(s): `__managed_by`" from the
+// real upstream API, which apparently receives it verbatim). Ownership is
+// tracked by the unique key name (KAIRO_ASK_AGENT_NAME) instead.
+export const KAIRO_ASK_AGENT_CONFIG = Object.freeze({
+  description: "Kairo's own real, read-only agent for ASK mode — investigates and answers, never edits, writes, or runs shell commands.",
+  hidden: true,
+  mode: "primary",
+  permission: Object.freeze({ bash: "deny", edit: "deny", task: "deny", write: "deny" })
+});
+
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function resolveOpencodeConfigPath(homeDir = homedir()) {
+  return join(homeDir, ".config", "opencode", "opencode.json");
+}
+
+/**
+ * Idempotently ensures the real, global opencode.json carries Kairo's own
+ * read-only "kairo-ask" agent — merged non-destructively (every other real
+ * key, including every other agent, is preserved byte-for-byte) and only
+ * ever written when actually missing or drifted, never on every call.
+ * A missing config file is created fresh with just $schema + this agent —
+ * never treated as an error (a real, common first-run state).
+ * @param {{homeDir?: string, readFileImpl?: Function, writeAtomicJsonImpl?: Function}} [deps]
+ * @returns {Promise<{changed: boolean, configPath: string}>}
+ */
+export async function ensureKairoAskAgent({
+  homeDir = homedir(), readFileImpl = readFile, writeAtomicJsonImpl = writeAtomicJson
+} = {}) {
+  const configPath = resolveOpencodeConfigPath(homeDir);
+  let config = { $schema: "https://opencode.ai/config.json" };
+  try {
+    const raw = await readFileImpl(configPath, "utf8");
+    config = JSON.parse(raw);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const existing = config.agent?.[KAIRO_ASK_AGENT_NAME];
+  if (deepEqual(existing, KAIRO_ASK_AGENT_CONFIG)) {
+    return { changed: false, configPath };
+  }
+  const updated = { ...config, agent: { ...(config.agent ?? {}), [KAIRO_ASK_AGENT_NAME]: KAIRO_ASK_AGENT_CONFIG } };
+  await writeAtomicJsonImpl(configPath, updated);
+  return { changed: true, configPath };
+}

package/src/global/intelligence/quick-ask.js

@@ -3,6 +3,8 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { buildClaudeExecutionEnv } from "../runtime/execution-adapters/claude.js";
+import { ensureKairoAskAgent, KAIRO_ASK_AGENT_NAME } from "./opencode-ask-agent.js";
+import { toRuntimeModelRef } from "./transport-registry.js";
 
 // A real, read-only question -> answer call — no task, no plan, no
 // approval gate. This spends real provider usage (unlike the zero-cost
@@ -166,6 +168,98 @@ function askCursor({ question, model, cwd, spawn, timeoutMs, env }) {
   });
 }
 
+// Same real scrubbing principle as the others — OPENCODE_API_KEY is
+// opencode's own documented real auth env var (types.js's
+// OPENCODE_API_KEY_ENV).
+const OPENCODE_SAFE_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+  "TMPDIR", "TERM", "OPENCODE_API_KEY", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy", "NODE_EXTRA_CA_CERTS"
+]);
+function buildOpencodeExecutionEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of OPENCODE_SAFE_ENV_KEYS) {
+    if (sourceEnv[key] != null && sourceEnv[key] !== "") env[key] = sourceEnv[key];
+  }
+  return env;
+}
+
+/**
+ * OpenCode's real CLI has no flag-driven read-only mode (verified via
+ * `opencode run --help`) — its permission model lives only in
+ * opencode.json, so this always runs against Kairo's own real, verified
+ * read-only agent (see opencode-ask-agent.js's own doc — live-verified
+ * both that it genuinely blocks a real write attempt and that
+ * `--agent`/`--model` compose correctly), ensured to exist in the user's
+ * global config before every call (cheap idempotent check — no real
+ * write unless actually missing or drifted).
+ *
+ * Verified live (`opencode run --agent kairo-ask --format json`): the
+ * real NDJSON stream emits `type: "text"` events carrying the real
+ * answer in `part.text` (possibly across multiple steps — accumulated in
+ * order) and a real `type: "error"` event on failure, both handled
+ * per-line as chunks arrive, mirroring the same idle-reset principle as
+ * every other ask call here.
+ * @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args
+ */
+async function askOpencode({ question, model, cwd, spawn, timeoutMs, env, ensureAgent = ensureKairoAskAgent }) {
+  try {
+    await ensureAgent();
+  } catch (error) {
+    return unknown(`could not ensure Kairo's read-only OpenCode agent: ${error?.message ?? error}`);
+  }
+  const args = ["run", "--agent", KAIRO_ASK_AGENT_NAME, "--format", "json"];
+  if (model) args.push("--model", model);
+  args.push(question);
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn("opencode", args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      resolve(unknown(error?.message ?? error));
+      return;
+    }
+    let buffer = "";
+    const answerParts = [];
+    let realError = null;
+    let stderr = "";
+    let finished = false;
+    const clearIdleTimer = armIdleTimeout(child, timeoutMs, () => finish(unknown(`opencode run idle-timed out after ${timeoutMs}ms with no output`)));
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearIdleTimer();
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+    function handleLine(line) {
+      let parsed;
+      try { parsed = JSON.parse(line); } catch { return; }
+      if (parsed?.type === "text" && typeof parsed?.part?.text === "string") {
+        answerParts.push(parsed.part.text);
+      } else if (parsed?.type === "error") {
+        realError = parsed.error?.data?.message ?? parsed.error?.name ?? "opencode run returned a real error event";
+      }
+    }
+    child.stdout?.on("data", (chunk) => {
+      buffer += String(chunk);
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) if (line.trim()) handleLine(line.trim());
+    });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+    child.once?.("close", (code) => {
+      if (buffer.trim()) handleLine(buffer.trim());
+      if (realError) return finish(unknown(realError));
+      const answer = answerParts.join("").trim();
+      if (!answer) return finish(unknown(stderr.trim() || `opencode run exited ${code} with no real text output`));
+      finish({ status: "answered", answer, error: null });
+    });
+  });
+}
+
 /** @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args */
 async function askCodex({ question, model, cwd, spawn, timeoutMs, env }) {
   let outDir;
@@ -222,24 +316,39 @@ async function askCodex({ question, model, cwd, spawn, timeoutMs, env }) {
 
 /**
  * Asks the given provider a real, read-only question and returns its real
- * answer text. Supports Codex, Claude, and Cursor today; any other
- * provider yields an honest "unsupported" result rather than a guess.
- * OpenCode (Go/Zen) is deliberately excluded — its real CLI has no
- * portable, CLI-flag-driven read-only mode (verified via `opencode run
- * --help`: `--auto` only ever loosens permissions further, never
- * restricts them), so a real read-only call can't be guaranteed safe
- * across different users' local opencode.json permission configs.
+ * answer text — every real automatic PROJECT TEAM adapter today (Codex,
+ * Claude, Cursor, OpenCode Go, OpenCode Zen); any other provider yields
+ * an honest "unsupported" result rather than a guess. OpenCode's real CLI
+ * has no flag-driven read-only mode (verified via `opencode run --help`:
+ * `--auto` only ever loosens permissions further, never restricts them),
+ * so it always runs against Kairo's own real, verified read-only agent
+ * instead (see opencode-ask-agent.js) — a project/user-config-independent
+ * guarantee, never relying on whatever the local opencode.json happens to
+ * already allow.
  * @param {object} args
- * @param {"codex"|"claude"|"cursor"} args.provider
+ * @param {"codex"|"claude"|"cursor"|"opencode-go"|"opencode-zen"} args.provider
  * @param {string} args.question
  * @param {string|null} [args.model]
  * @param {string} args.cwd
  */
 export async function askProvider({
-  provider, question, model = null, cwd, spawn = defaultSpawn, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv = process.env
+  provider, question, model = null, cwd, spawn = defaultSpawn, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv = process.env,
+  ensureOpencodeAskAgent = ensureKairoAskAgent
 }) {
   if (provider === "claude") return askClaude({ question, model, cwd, spawn, timeoutMs, env: buildClaudeExecutionEnv(sourceEnv) });
   if (provider === "codex") return askCodex({ question, model, cwd, spawn, timeoutMs, env: buildCodexExecutionEnv(sourceEnv) });
   if (provider === "cursor") return askCursor({ question, model, cwd, spawn, timeoutMs, env: buildCursorExecutionEnv(sourceEnv) });
+  if (provider === "opencode-go" || provider === "opencode-zen") {
+    // The real catalog stores bare model ids (see opencode-models.js's
+    // normalizeModel) — the CLI needs the real, fully-qualified
+    // "opencode-go/<id>" (or "opencode/<id>" for Zen) ref to
+    // deterministically route to the intended product, exactly like
+    // service.js's executePlan already does for real task execution.
+    const runtimeModel = model ? toRuntimeModelRef(provider === "opencode-go" ? "go" : "zen", model) : null;
+    return askOpencode({
+      question, model: runtimeModel, cwd, spawn, timeoutMs, env: buildOpencodeExecutionEnv(sourceEnv),
+      ensureAgent: ensureOpencodeAskAgent
+    });
+  }
   return { status: "unsupported", answer: null, error: `ASK is not supported for provider "${provider}" yet.` };
 }

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

@@ -0,0 +1,167 @@
+// Disk cache for Claude per-model entitlement probes. Mirrors the
+// artificial-analysis-models.js pattern (read→null on any failure, mkdir +
+// writeAtomicJson, fetchedAt / ageLabel) — not usage-store.js, whose
+// whitelist is for real billing providers.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+import { ENTITLEMENT } from "./claude-model-entitlement.js";
+
+export const DEFAULT_ENTITLEMENT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+function ageLabel(fetchedAtIso, nowMs = Date.now()) {
+  const fetchedAt = new Date(fetchedAtIso ?? "").getTime();
+  if (!Number.isFinite(fetchedAt)) return null;
+  const hours = (nowMs - fetchedAt) / 3_600_000;
+  if (hours < 1) return "<1h";
+  if (hours < 48) return `${Math.round(hours)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+function isPersistableStatus(status) {
+  return status === ENTITLEMENT.ALLOWED || status === ENTITLEMENT.DENIED;
+}
+
+function emptyDoc(subscriptionType, fetchedAt = new Date().toISOString()) {
+  return {
+    subscriptionType: subscriptionType ?? null,
+    fetchedAt,
+    models: Object.create(null)
+  };
+}
+
+/**
+ * @param {string} homeDir
+ * @param {object} [deps]
+ * @returns {Promise<object|null>}
+ */
+export async function readClaudeEntitlementCache(homeDir, deps = {}) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(harnessHomePaths(homeDir).claudeEntitlementPath, "utf8");
+    const doc = JSON.parse(raw);
+    if (!doc || typeof doc !== "object") return null;
+    if (typeof doc.fetchedAt !== "string") return null;
+    if (!doc.models || typeof doc.models !== "object" || Array.isArray(doc.models)) return null;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} homeDir
+ * @param {object} doc
+ * @param {object} [deps]
+ */
+export async function writeClaudeEntitlementCache(homeDir, doc, deps = {}) {
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = harnessHomePaths(homeDir).claudeEntitlementPath;
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, doc);
+}
+
+/**
+ * Pure resolver: map catalog ids → live entitlement view from cache.
+ * Invalidates the entire cache when subscriptionType differs.
+ *
+ * @param {{
+ *   cache: object|null,
+ *   subscriptionType: string|null,
+ *   catalogIds: string[],
+ *   now?: number,
+ *   ttlMs?: number
+ * }} options
+ * @returns {Record<string, { status: string, reason: string|null, age: string|null, probedAt: string|null }>}
+ */
+export function resolveClaudeEntitlements({
+  cache,
+  subscriptionType,
+  catalogIds = [],
+  now = Date.now(),
+  ttlMs = DEFAULT_ENTITLEMENT_TTL_MS
+} = {}) {
+  const usable = cache
+    && typeof cache === "object"
+    && cache.subscriptionType === subscriptionType
+    && cache.models
+    && typeof cache.models === "object"
+    ? cache
+    : null;
+
+  const resolved = Object.create(null);
+  for (const modelId of catalogIds) {
+    const entry = usable?.models?.[modelId] ?? null;
+    if (!entry || !isPersistableStatus(entry.status)) {
+      resolved[modelId] = {
+        status: ENTITLEMENT.UNVERIFIED,
+        reason: null,
+        age: null,
+        probedAt: null
+      };
+      continue;
+    }
+
+    const probedAtMs = new Date(entry.probedAt ?? "").getTime();
+    if (!Number.isFinite(probedAtMs) || now - probedAtMs > ttlMs) {
+      resolved[modelId] = {
+        status: ENTITLEMENT.UNVERIFIED,
+        reason: null,
+        age: ageLabel(entry.probedAt, now),
+        probedAt: entry.probedAt ?? null
+      };
+      continue;
+    }
+
+    resolved[modelId] = {
+      status: entry.status,
+      reason: entry.reason ?? null,
+      age: ageLabel(entry.probedAt, now),
+      probedAt: entry.probedAt
+    };
+  }
+  return resolved;
+}
+
+/**
+ * Merge fresh probe results into a cache doc. Discards status "unknown"
+ * (and unverified) — only allowed/denied evidence is persisted.
+ *
+ * @param {object|null} cache
+ * @param {{ subscriptionType: string|null, catalogIds?: string[], results: Array<{ modelId: string, status: string, reason?: string|null, probedAt?: string }> }} payload
+ */
+export function mergeEntitlementResults(cache, { subscriptionType, results = [] } = {}) {
+  const base = cache
+    && typeof cache === "object"
+    && cache.subscriptionType === subscriptionType
+    && cache.models
+    && typeof cache.models === "object"
+    ? {
+      subscriptionType: cache.subscriptionType,
+      fetchedAt: cache.fetchedAt,
+      models: { ...cache.models }
+    }
+    : emptyDoc(subscriptionType);
+
+  let newestProbedAt = base.fetchedAt;
+  for (const result of results) {
+    if (!result || typeof result.modelId !== "string") continue;
+    if (result.status === "unknown" || !isPersistableStatus(result.status)) continue;
+    const probedAt = typeof result.probedAt === "string"
+      ? result.probedAt
+      : new Date().toISOString();
+    base.models[result.modelId] = {
+      status: result.status,
+      reason: result.reason ?? null,
+      probedAt
+    };
+    if (!newestProbedAt || probedAt > newestProbedAt) newestProbedAt = probedAt;
+  }
+
+  base.fetchedAt = newestProbedAt ?? new Date().toISOString();
+  base.subscriptionType = subscriptionType ?? null;
+  return base;
+}

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

@@ -0,0 +1,185 @@
+// Live per-model Claude entitlement probe. Kept separate from
+// claude-models.js on purpose: that module is sync, free, and pure, and
+// three of its four callers sit on hot paths. This module is the only
+// place that interprets the real `claude -p … --output-format json`
+// response for account access — fail-closed, never inventing allowed.
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { buildClaudeExecutionEnv } from "../runtime/execution-adapters/claude.js";
+
+export const ENTITLEMENT = Object.freeze({
+  ALLOWED: "allowed",
+  DENIED: "denied",
+  UNVERIFIED: "unverified"
+});
+
+const DENIED_ERROR_CODES = new Set(["credits_required"]);
+const DENIED_HTTP_STATUSES = new Set([402, 403, 429]);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const PROBE_ARGS_PREFIX = Object.freeze(["-p", "hi", "--model"]);
+const PROBE_ARGS_SUFFIX = Object.freeze(["--output-format", "json"]);
+
+/**
+ * Pure classifier for a parsed Claude CLI `--output-format json` result.
+ * The only place that interprets the real JSON shape for entitlement.
+ *
+ * @param {object|null|undefined} parsed
+ * @returns {{ status: string, reason: string|null }}
+ */
+export function classifyClaudeEntitlementResponse(parsed) {
+  if (!parsed || typeof parsed !== "object") {
+    return { status: ENTITLEMENT.UNVERIFIED, reason: null };
+  }
+
+  const isError = parsed.is_error === true;
+  const status = parsed.api_error_status;
+  const code = parsed.api_error_code;
+  const message = typeof parsed.result === "string" && parsed.result.trim()
+    ? parsed.result
+    : null;
+
+  if (
+    isError
+    && (DENIED_ERROR_CODES.has(code) || DENIED_HTTP_STATUSES.has(status))
+  ) {
+    return { status: ENTITLEMENT.DENIED, reason: message };
+  }
+
+  if (parsed.is_error === false && (status === null || status === undefined)) {
+    return { status: ENTITLEMENT.ALLOWED, reason: null };
+  }
+
+  return { status: ENTITLEMENT.UNVERIFIED, reason: message };
+}
+
+function probeArgv(modelId) {
+  return [...PROBE_ARGS_PREFIX, modelId, ...PROBE_ARGS_SUFFIX];
+}
+
+function unverifiedResult(modelId, reason = null) {
+  return {
+    modelId,
+    status: ENTITLEMENT.UNVERIFIED,
+    reason: reason == null ? null : String(reason),
+    probedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Probe a single Claude model id via the measured CLI shape.
+ * @param {{ modelId: string, spawn?: typeof defaultSpawn, cwd?: string, env?: NodeJS.ProcessEnv, timeoutMs?: number }} options
+ */
+export async function probeClaudeModelEntitlement({
+  modelId,
+  spawn = defaultSpawn,
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  if (typeof modelId !== "string" || !modelId) {
+    return unverifiedResult(modelId ?? "", "modelId is required");
+  }
+
+  let child;
+  try {
+    child = spawn("claude", probeArgv(modelId), {
+      cwd,
+      env: buildClaudeExecutionEnv(env),
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    return unverifiedResult(modelId, error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const timer = setTimeout(
+      () => finish(unverifiedResult(modelId, `claude entitlement probe timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once?.("error", (error) => finish(unverifiedResult(modelId, error?.message ?? error)));
+    child.once?.("close", (code, signal) => {
+      if (signal) {
+        return finish(unverifiedResult(
+          modelId,
+          `claude entitlement probe was killed by signal ${signal}${stderr ? `: ${stderr.trim()}` : ""}`
+        ));
+      }
+
+      let parsed = null;
+      try {
+        const trimmed = String(stdout ?? "").trim();
+        parsed = trimmed ? JSON.parse(trimmed) : null;
+      } catch {
+        return finish(unverifiedResult(
+          modelId,
+          `claude entitlement probe returned invalid JSON${stderr ? `: ${stderr.trim()}` : ""}`
+        ));
+      }
+
+      const classified = classifyClaudeEntitlementResponse(parsed);
+      // A non-zero exit with a classifiable JSON body still trusts the body —
+      // the measured denied probe exits 0, but broken/unknown shapes stay
+      // unverified regardless of exit code. Never promote a failed spawn to
+      // allowed just because exit was 0 with empty stdout (parsed null →
+      // unverified above).
+      if (classified.status === ENTITLEMENT.ALLOWED && code !== 0) {
+        return finish(unverifiedResult(
+          modelId,
+          `claude entitlement probe exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`
+        ));
+      }
+
+      finish({
+        modelId,
+        status: classified.status,
+        reason: classified.reason,
+        probedAt: new Date().toISOString()
+      });
+    });
+  });
+}
+
+/**
+ * Probe many model ids sequentially (never Promise.all). Caps at maxProbes.
+ * @param {{
+ *   modelIds: string[],
+ *   maxProbes?: number,
+ *   onProgress?: (event: { modelId: string, index: number, total: number, result: object }) => void,
+ *   spawn?: typeof defaultSpawn,
+ *   cwd?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   timeoutMs?: number
+ * }} options
+ */
+export async function probeClaudeModelEntitlements({
+  modelIds = [],
+  maxProbes = 12,
+  onProgress = null,
+  ...probeOpts
+} = {}) {
+  const ids = Array.isArray(modelIds) ? modelIds.slice(0, Math.max(0, maxProbes)) : [];
+  const results = [];
+  for (let index = 0; index < ids.length; index += 1) {
+    const modelId = ids[index];
+    const result = await probeClaudeModelEntitlement({ modelId, ...probeOpts });
+    results.push(result);
+    if (typeof onProgress === "function") {
+      onProgress({ modelId, index, total: ids.length, result });
+    }
+  }
+  return results;
+}

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.25.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.26.1" },
       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.25.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.26.1" },
       capabilities: {}
     });
   });

package/src/global/paths.js

@@ -28,6 +28,7 @@ export function harnessHomePaths(homeDir) {
     worktreesDir: join(root, "worktrees"),
     usageDir: join(root, "usage"),
     modelIntelligencePath: join(root, "model-intelligence.json"),
+    claudeEntitlementPath: join(root, "claude-entitlement.json"),
     huggingfaceLeaderboardPath: join(root, "huggingface-leaderboard.json")
   };
 }