@aibridge/cli 0.3.0 → 0.4.0

package/README.md

@@ -42,6 +42,7 @@ npx -y @aibridge/cli subagent --model xai-grok/grok-4.5 "summarize the architect
 | `aibridge review --model xai-grok/grok-4.5 --out review.md [--plan <plan.md>]` | You want a **different model** to pressure-test the working-tree diff against the plan contract (over-reach is a finding) — or to review the plan itself before implementing |
 | `aibridge subagent --model xai-grok/grok-4.5 "<task>"` | A self-contained task deserves a concurrent delegate, a cross-model second opinion, or a red-team pass |
 | `aibridge image-gen --model openai-codex/gpt-5.6-sol --out out.png "<prompt>"` | You need a real raster image — on a Codex, Antigravity, or Grok seat, with render verification |
+| `aibridge models [--json]` | You need the exact facts for every registered model seat (accepted efforts, image format, pinned model ID) |
 | `aibridge quota` | Two-second check of every backend's remaining quota before you pipeline work |
 | `aibridge runs` | Inspect or watch past delegation runs (`~/.aibridge/runs`) |
 
@@ -63,6 +64,36 @@ Plan files — not their contents — travel between stages, so the loop is near
 - **No API keys.** Delegation runs on the backing CLIs' existing logins, each spending its own quota. (The skill treats a backend that shares your agent's own quota pool as a last resort.)
 - **Models are canonical slugs**: `<vendor>-<cli>/<model>[-<effort>]` — e.g. `xai-grok/grok-4.5`, `google-antigravity/gemini-3.6-flash`, `openai-codex/gpt-5.6-sol-high`, `anthropic-claude/opus-5`. No aliases — not short ones, and not moving vendor aliases like `opus`: every seat pins an exact model version. `aibridge <command> --help` lists every seat.
 
+## Tell your agent when to reach for it
+
+aibridge doesn't decide when to delegate — your agent does, and left alone it will
+mostly keep the work for itself. Put the routing rule in whatever instructions file
+your agent already reads at the start of every session (`AGENTS.md`, `CLAUDE.md`,
+`.cursorrules`, …). Something like:
+
+```markdown
+## Delegation gate — decide before you implement
+
+The moment a task becomes implementation you could fully specify, say the call out
+loud — **solo** or **aibridge** — plus one line of why. Delegating is the default.
+Stay solo only when the edit is smaller than the spec would be, or the work needs
+live judgment, your own session's tools, or tight back-and-forth. Never default to
+solo silently.
+
+Route by size and risk:
+
+- tiny → solo
+- clearly specified and self-contained → `aibridge subagent`
+- large or risky → `aibridge plan` → read and approve the plan file →
+  `aibridge implement` → `aibridge review`
+
+Delegated work is yours to verify: re-run the real gates before trusting a diff.
+Prefer a reviewer from a different model family than whoever implemented.
+```
+
+Tune the seats and thresholds to your own quotas. The value is that the decision is
+explicit and made *before* the work starts, rather than rationalised afterwards.
+
 ## Requirements
 
 - **Node ≥ 24.11**

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as buildContext } from "./context-B6I4QI9z.mjs";
+import { r as runCli, t as buildContext } from "./context-v_ns4n_W.mjs";
 //#region src/cli.ts
 await runCli(buildContext(process), process.argv.slice(2));
 //#endregion

package/dist/{context-B6I4QI9z.mjs → context-v_ns4n_W.mjs}

@@ -10,6 +10,7 @@ import { fetchClaudeQuota } from "@aibridge/driver-claude";
 import * as codex from "@aibridge/driver-codex";
 import { fetchCodexQuota } from "@aibridge/driver-codex";
 import * as grok from "@aibridge/driver-grok";
+import { fetchGrokQuota } from "@aibridge/driver-grok";
 import { runCaptured } from "@aibridge/proc";
 import { randomBytes } from "node:crypto";
 //#region src/models.ts
@@ -23,7 +24,7 @@ const MODELS = {
 			"medium",
 			"high"
 		],
-		brief: "xAI Grok 4.5 via grok CLI — default for plan & review; own xAI login"
+		brief: "xAI Grok 4.5 via grok CLI — own xAI login; ~30 req/min, ~1k msgs/day, single-flight"
 	},
 	"google-antigravity/gemini-3.6-flash": {
 		slug: "google-antigravity/gemini-3.6-flash",
@@ -35,7 +36,15 @@ const MODELS = {
 			"high"
 		],
 		defaultEffort: "high",
-		brief: "Google Gemini 3.6 Flash via agy — default for implement, also image-gen; own Antigravity login"
+		brief: "Google Gemini 3.6 Flash via agy — own Antigravity login; quota shared across all Gemini tiers"
+	},
+	"google-antigravity/gemini-3.1-pro": {
+		slug: "google-antigravity/gemini-3.1-pro",
+		backend: "agy",
+		efforts: ["low", "high"],
+		backendModel: "gemini-3.1-pro",
+		defaultEffort: "high",
+		brief: "Google Gemini 3.1 Pro via agy — own Antigravity login; quota shared across all Gemini tiers"
 	},
 	"google-antigravity/claude-sonnet-4-6": {
 		slug: "google-antigravity/claude-sonnet-4-6",
@@ -68,12 +77,36 @@ const MODELS = {
 			"high",
 			"xhigh"
 		],
-		brief: "OpenAI Codex gpt-5.6-sol via codex CLI"
+		brief: "OpenAI gpt-5.6-sol via codex CLI — frontier agentic coding; own ChatGPT login"
 	},
-	"anthropic-claude/sonnet-5": {
-		slug: "anthropic-claude/sonnet-5",
+	"openai-codex/gpt-5.6-terra": {
+		slug: "openai-codex/gpt-5.6-terra",
+		backend: "codex",
+		backendModel: "gpt-5.6-terra",
+		efforts: [
+			"low",
+			"medium",
+			"high",
+			"xhigh"
+		],
+		brief: "OpenAI gpt-5.6-terra via codex CLI — balanced, everyday coding; own ChatGPT login"
+	},
+	"openai-codex/gpt-5.6-luna": {
+		slug: "openai-codex/gpt-5.6-luna",
+		backend: "codex",
+		backendModel: "gpt-5.6-luna",
+		efforts: [
+			"low",
+			"medium",
+			"high",
+			"xhigh"
+		],
+		brief: "OpenAI gpt-5.6-luna via codex CLI — fast and affordable coding; own ChatGPT login"
+	},
+	"anthropic-claude/fable-5": {
+		slug: "anthropic-claude/fable-5",
 		backend: "claude",
-		backendModel: "claude-sonnet-5",
+		backendModel: "claude-fable-5",
 		efforts: [
 			"low",
 			"medium",
@@ -81,12 +114,13 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		brief: "Claude Sonnet 5 via claude CLI — bills your Claude subscription"
+		defaultEffort: "high",
+		brief: "Claude Fable 5 via claude CLI — hardest, longest-running work; bills the claude CLI subscription"
 	},
 	"anthropic-claude/opus-5": {
 		slug: "anthropic-claude/opus-5",
 		backend: "claude",
-		backendModel: "claude-opus-5",
+		backendModel: "claude-opus-5[1m]",
 		efforts: [
 			"low",
 			"medium",
@@ -95,12 +129,12 @@ const MODELS = {
 			"max"
 		],
 		defaultEffort: "high",
-		brief: "Claude Opus 5 via claude CLI (default effort: high) — bills subscription"
+		brief: "Claude Opus 5, 1M context via claude CLI — everyday complex work; bills the claude CLI subscription"
 	},
-	"anthropic-claude/opus-5-1m": {
-		slug: "anthropic-claude/opus-5-1m",
+	"anthropic-claude/sonnet-5": {
+		slug: "anthropic-claude/sonnet-5",
 		backend: "claude",
-		backendModel: "claude-opus-5[1m]",
+		backendModel: "claude-sonnet-5",
 		efforts: [
 			"low",
 			"medium",
@@ -108,8 +142,20 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		defaultEffort: "high",
-		brief: "Claude Opus 5, 1M context via claude CLI — long-context work; bills subscription"
+		brief: "Claude Sonnet 5 via claude CLI — routine work; bills the claude CLI subscription"
+	},
+	"anthropic-claude/haiku-4-5": {
+		slug: "anthropic-claude/haiku-4-5",
+		backend: "claude",
+		backendModel: "claude-haiku-4-5-20251001",
+		efforts: [
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		brief: "Claude Haiku 4.5 via claude CLI — quick answers; bills the claude CLI subscription"
 	}
 };
 const IMAGE_GEN_FORMATS = /* @__PURE__ */ new Map([
@@ -209,6 +255,7 @@ const DRIVERS = {
 	grok: {
 		probe: () => grok.probe(),
 		run: (task) => grok.run(task),
+		quota: () => grok.fetchGrokQuota(),
 		generateImage: (req) => grok.generateImage(req)
 	},
 	codex: {
@@ -488,8 +535,17 @@ function evaluateCodexPreflight(snapshot) {
 	};
 	return { ok: true };
 }
+function evaluateGrokPreflight(snapshot) {
+	if (snapshot.usedPercent !== void 0 && snapshot.usedPercent >= 100) return {
+		ok: false,
+		message: "grok credit quota exhausted",
+		resetAt: snapshot.periodEnd
+	};
+	return { ok: true };
+}
 async function preflightModel(resolved) {
 	if (resolved.spec.backend === "codex") return preflightCodex();
+	if (resolved.spec.backend === "grok") return preflightGrok();
 	if (resolved.spec.backend !== "agy") return { ok: true };
 	try {
 		return evaluateAgyPreflight(await fetchAgyQuota(), backendModelId(resolved));
@@ -510,6 +566,16 @@ async function preflightCodex() {
 		};
 	}
 }
+async function preflightGrok() {
+	try {
+		return evaluateGrokPreflight(await fetchGrokQuota());
+	} catch (err) {
+		return {
+			ok: true,
+			warning: `quota preflight failed (${err.message}); proceeding`
+		};
+	}
+}
 function formatReset$1(resetTime) {
 	if (!resetTime) return "-";
 	const ms = new Date(resetTime).getTime() - Date.now();
@@ -744,6 +810,70 @@ const implement = buildCommand({
 	}
 });
 //#endregion
+//#region src/commands/models/impl.ts
+const BACKEND_DISPLAY_NAMES = {
+	grok: "grok (Grok CLI)",
+	agy: "agy (Antigravity)",
+	codex: "codex (Codex CLI)",
+	claude: "claude (Claude Code CLI)"
+};
+function modelsImpl(flags) {
+	const specs = Object.values(MODELS);
+	if (flags.json) {
+		const jsonOutput = specs.map((spec) => ({
+			slug: spec.slug,
+			backend: spec.backend,
+			backendModel: spec.backendModel,
+			efforts: spec.efforts ? [...spec.efforts] : [],
+			defaultEffort: spec.defaultEffort ?? null,
+			image: imageFormatFor({
+				spec,
+				effort: void 0
+			}) ?? null,
+			brief: spec.brief
+		}));
+		this.process.stdout.write(`${JSON.stringify(jsonOutput)}\n`);
+		return;
+	}
+	const backends = [];
+	for (const spec of specs) if (!backends.includes(spec.backend)) backends.push(spec.backend);
+	let firstBackend = true;
+	for (const backend of backends) {
+		if (!firstBackend) this.process.stdout.write("\n");
+		firstBackend = false;
+		this.process.stdout.write(`=== ${BACKEND_DISPLAY_NAMES[backend]} ===\n`);
+		const backendSpecs = specs.filter((spec) => spec.backend === backend);
+		for (const spec of backendSpecs) {
+			this.process.stdout.write(`  ${spec.slug}\n`);
+			const segments = [];
+			if (spec.efforts) {
+				const formattedEfforts = spec.efforts.map((e) => e === spec.defaultEffort ? `${e}*` : e).join(" | ");
+				segments.push(`efforts: ${formattedEfforts}`);
+			}
+			const img = imageFormatFor({
+				spec,
+				effort: void 0
+			});
+			segments.push(`image: ${img ?? "—"}`);
+			segments.push(`id: ${spec.backendModel}`);
+			this.process.stdout.write(`    ${segments.join(" · ")}\n`);
+			this.process.stdout.write(`    ${spec.brief}\n`);
+		}
+	}
+	if (specs.some((spec) => spec.defaultEffort !== void 0)) this.process.stdout.write("\n* = effort used when the slug has no -<effort> suffix\n");
+}
+//#endregion
+//#region src/commands/models/command.ts
+const models = buildCommand({
+	func: modelsImpl,
+	parameters: { flags: { json: {
+		kind: "boolean",
+		withNegated: false,
+		brief: "Emit the registry as JSON"
+	} } },
+	docs: { brief: "List every model seat in the registry (slug, efforts, image format)" }
+});
+//#endregion
 //#region src/commands/plan/impl.ts
 function countOpenQuestions(markdown) {
 	const headingIdx = markdown.search(/^## Open questions[ \t]*$/m);
@@ -905,6 +1035,17 @@ function formatReset(resetTime) {
 	const rel = mins < 60 ? `${mins}m` : `${Math.floor(mins / 60)}h${mins % 60}m`;
 	return `${new Date(resetTime).toLocaleTimeString()} (in ${rel})`;
 }
+function renderGrok(ctx, snapshot) {
+	ctx.process.stdout.write("=== grok (xAI) — used this period ===\n");
+	ctx.process.stdout.write(`${"PERIOD".padEnd(10)} ${"USED".padEnd(10)} RESET\n`);
+	const usedPctStr = snapshot.usedPercent !== void 0 ? `${snapshot.usedPercent}%` : "?";
+	const periodStr = snapshot.periodType ?? "-";
+	ctx.process.stdout.write(`${periodStr.padEnd(10)} ${usedPctStr.padEnd(10)} ${formatReset(snapshot.periodEnd)}\n`);
+	if (snapshot.products.length > 0) {
+		const prods = snapshot.products.map((p) => `${p.product} ${p.usedPercent}%`).join(" · ");
+		ctx.process.stdout.write(`  ${prods}\n`);
+	}
+}
 function renderAgy(ctx, snapshot) {
 	ctx.process.stdout.write("=== agy (Antigravity) — remaining per model group ===\n");
 	for (const group of snapshot.groups) {
@@ -934,14 +1075,16 @@ function renderSection(ctx, result, title, render) {
 	else ctx.process.stdout.write(`=== ${title} ===\nunavailable: ${result.reason.message}\n`);
 }
 async function quotaImpl(flags) {
-	const [agy, codex, claude] = await Promise.allSettled([
+	const [grok, agy, codex, claude] = await Promise.allSettled([
+		fetchGrokQuota(),
 		fetchAgyQuota(),
 		fetchCodexQuota(),
 		fetchClaudeQuota()
 	]);
-	const allFailed = agy.status === "rejected" && codex.status === "rejected" && claude.status === "rejected";
+	const allFailed = grok.status === "rejected" && agy.status === "rejected" && codex.status === "rejected" && claude.status === "rejected";
 	if (flags.json) {
 		this.process.stdout.write(`${JSON.stringify({
+			grok: grok.status === "fulfilled" ? grok.value : { error: String(grok.reason) },
 			agy: agy.status === "fulfilled" ? agy.value : { error: String(agy.reason) },
 			codex: codex.status === "fulfilled" ? codex.value : { error: String(codex.reason) },
 			claude: claude.status === "fulfilled" ? claude.value : { error: String(claude.reason) }
@@ -949,6 +1092,8 @@ async function quotaImpl(flags) {
 		if (allFailed) this.process.exitCode = 1;
 		return;
 	}
+	renderSection(this, grok, "grok (xAI)", renderGrok);
+	this.process.stdout.write("\n");
 	renderSection(this, agy, "agy (Antigravity)", renderAgy);
 	this.process.stdout.write("\n");
 	renderSection(this, codex, "codex (ChatGPT)", renderCodex);
@@ -964,8 +1109,10 @@ const quota = buildCommand({
 		brief: "Emit the raw snapshot as JSON"
 	} } },
 	docs: {
-		brief: "Show agy / codex / claude quota with reset times",
+		brief: "Show grok / agy / codex / claude quota with reset times",
 		fullDescription: [
+			"grok: reads ~/.grok/auth.json and asks the xAI billing endpoint for the",
+			"weekly credit usage percentage and per-product split.",
 			"agy: reads its cached OAuth token (~/.gemini/antigravity-cli/) and asks the",
 			"Cloud Code API for per-model remaining quota. EXHAUSTED means agy turns on",
 			"that model fail with an empty answer until the reset time.",
@@ -1390,8 +1537,8 @@ const fullDescription = [
 	"",
 	"Available models (canonical slug):",
 	...listModelHelpLines(),
-	"Recommended first choice: xai-grok/grok-4.5 (off-budget). The claude-backend slugs are FALLBACKS for",
-	"when the off-budget CLIs are quota-exhausted — they bill your Claude subscription."
+	"Recommended first choice: xai-grok/grok-4.5. Whichever seat runs on the same provider as the",
+	"agent you orchestrate from is your last resort — it spends the pool you are already burning."
 ].join("\n");
 const subagent = buildCommand({
 	func: subagent$1,
@@ -1465,9 +1612,10 @@ const app = buildApplication(buildRouteMap({
 		subagent,
 		"image-gen": imageGen,
 		runs,
-		quota
+		quota,
+		models
 	},
-	docs: { brief: "Bridge tasks to non-Claude AI CLIs — a plan → implement → review workflow, task delegation, and image generation (codex / agy / grok seats)." }
+	docs: { brief: "Bridge tasks to the other AI CLIs on this machine — a plan → implement → review workflow, task delegation, and image generation (codex / agy / grok seats)." }
 }), {
 	name: "aibridge",
 	versionInfo: { currentVersion: version },

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { CommandContext } from "@stricli/core";
 import { AgyQuotaSnapshot } from "@aibridge/driver-agy";
 import { ClaudeQuotaSnapshot } from "@aibridge/driver-claude";
 import { CodexQuotaSnapshot } from "@aibridge/driver-codex";
+import { GrokQuotaSnapshot } from "@aibridge/driver-grok";
 //#region src/context.d.ts
 interface LocalContext extends CommandContext {
   /** Full Node process — satisfies stricli WritableStreams + exitCode/env/cwd used by impls. */
@@ -21,7 +22,7 @@ declare function runCli(ctx: LocalContext, argv: readonly string[]): Promise<voi
  * Models are registered by canonical, provider-qualified slug —
  * `<vendor>-<cli>/<model>[-<effort>]`, e.g. `openai-codex/gpt-5.6-sol-high`.
  * Canonical slugs only — no short aliases, by design. That holds on both sides:
- * `backendModel` is a pinned model id (`claude-opus-5`), never a moving vendor
+ * `backendModel` is a pinned model id (`claude-sonnet-5`), never a moving vendor
  * alias (`opus`), so a seat never silently changes model under you.
  */
 type Backend = 'agy' | 'claude' | 'codex' | 'grok';
@@ -77,7 +78,7 @@ type DelegationResult = {
   readonly message: string;
   readonly exitCode: number | null;
 };
-type QuotaSnapshot = AgyQuotaSnapshot | CodexQuotaSnapshot | ClaudeQuotaSnapshot;
+type QuotaSnapshot = AgyQuotaSnapshot | CodexQuotaSnapshot | ClaudeQuotaSnapshot | GrokQuotaSnapshot;
 interface ImageGenRequest {
   readonly prompt: string;
   readonly workDir: string;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { S as supportsImageGen, _ as backendModelId, a as readRunLogs, b as listModelHelpLines, c as evaluateCodexPreflight, d as renderPreflightRefusal, f as delegate, g as MODELS, h as positiveIntSeconds, i as listRuns, l as preflightCodex, m as nonEmptyPrompt, n as app, o as startRun, p as getDriver, r as runCli, s as evaluateAgyPreflight, t as buildContext, u as preflightModel, v as formatImageGenModelError, x as resolveModel, y as formatUnknownModelError } from "./context-B6I4QI9z.mjs";
+import { S as supportsImageGen, _ as backendModelId, a as readRunLogs, b as listModelHelpLines, c as evaluateCodexPreflight, d as renderPreflightRefusal, f as delegate, g as MODELS, h as positiveIntSeconds, i as listRuns, l as preflightCodex, m as nonEmptyPrompt, n as app, o as startRun, p as getDriver, r as runCli, s as evaluateAgyPreflight, t as buildContext, u as preflightModel, v as formatImageGenModelError, x as resolveModel, y as formatUnknownModelError } from "./context-v_ns4n_W.mjs";
 export { MODELS, app, backendModelId, buildContext, delegate, evaluateAgyPreflight, evaluateCodexPreflight, formatImageGenModelError, formatUnknownModelError, getDriver, listModelHelpLines, listRuns, nonEmptyPrompt, positiveIntSeconds, preflightCodex, preflightModel, readRunLogs, renderPreflightRefusal, resolveModel, runCli, startRun, supportsImageGen };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibridge/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI that bridges tasks to AI CLIs on your machine (plan / implement / review / subagent / image-gen)",
   "type": "module",
   "license": "MIT",
@@ -35,11 +35,11 @@
   ],
   "dependencies": {
     "@stricli/core": "1.3.0",
-    "@aibridge/proc": "0.3.0",
-    "@aibridge/driver-agy": "0.3.0",
-    "@aibridge/driver-grok": "0.3.0",
-    "@aibridge/driver-codex": "0.3.0",
-    "@aibridge/driver-claude": "0.3.0"
+    "@aibridge/proc": "0.4.0",
+    "@aibridge/driver-grok": "0.4.0",
+    "@aibridge/driver-agy": "0.4.0",
+    "@aibridge/driver-codex": "0.4.0",
+    "@aibridge/driver-claude": "0.4.0"
   },
   "devDependencies": {
     "tsdown": "0.22.14"

package/src/app.ts

@@ -2,6 +2,7 @@ import { createRequire } from 'node:module';
 import { buildApplication, buildRouteMap, run } from '@stricli/core';
 import { imageGen } from './commands/image-gen/command.ts';
 import { implement } from './commands/implement/command.ts';
+import { models } from './commands/models/command.ts';
 import { plan } from './commands/plan/command.ts';
 import { quota } from './commands/quota/command.ts';
 import { review } from './commands/review/command.ts';
@@ -14,7 +15,7 @@ const require = createRequire(import.meta.url);
 const { version } = require('../package.json') as { version: string };
 
 const BRIEF =
-  'Bridge tasks to non-Claude AI CLIs — a plan → implement → review workflow, task delegation, and image generation (codex / agy / grok seats).';
+  'Bridge tasks to the other AI CLIs on this machine — a plan → implement → review workflow, task delegation, and image generation (codex / agy / grok seats).';
 
 const routes = buildRouteMap({
   routes: {
@@ -25,6 +26,7 @@ const routes = buildRouteMap({
     'image-gen': imageGen,
     runs,
     quota,
+    models,
   },
   docs: {
     brief: BRIEF,

package/src/commands/models/command.ts

@@ -0,0 +1,18 @@
+import { buildCommand } from '@stricli/core';
+import modelsImpl from './impl.ts';
+
+export const models = buildCommand({
+  func: modelsImpl,
+  parameters: {
+    flags: {
+      json: {
+        kind: 'boolean',
+        withNegated: false,
+        brief: 'Emit the registry as JSON',
+      },
+    },
+  },
+  docs: {
+    brief: 'List every model seat in the registry (slug, efforts, image format)',
+  },
+});

package/src/commands/models/impl.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import type { LocalContext } from '../../context.ts';
+import { MODELS } from '../../models.ts';
+import modelsImpl from './impl.ts';
+
+function createTestContext() {
+  let stdoutText = '';
+  const fakeProcess = {
+    stdout: {
+      write(chunk: string | Uint8Array) {
+        stdoutText += chunk.toString();
+        return true;
+      },
+    },
+    stderr: {
+      write() {
+        return true;
+      },
+    },
+    exitCode: 0,
+  } as unknown as NodeJS.Process;
+
+  return {
+    ctx: { process: fakeProcess } as LocalContext,
+    getStdout: () => stdoutText,
+  };
+}
+
+describe('modelsImpl', () => {
+  it('--json emits parseable JSON with one entry per key of MODELS, with seven documented fields', () => {
+    const { ctx, getStdout } = createTestContext();
+    modelsImpl.call(ctx, { json: true });
+
+    const raw = getStdout();
+    const data = JSON.parse(raw);
+
+    expect(Array.isArray(data)).toBe(true);
+    expect(data.length).toBe(Object.keys(MODELS).length);
+
+    for (const item of data) {
+      expect(item).toHaveProperty('slug');
+      expect(item).toHaveProperty('backend');
+      expect(item).toHaveProperty('backendModel');
+      expect(item).toHaveProperty('efforts');
+      expect(item).toHaveProperty('defaultEffort');
+      expect(item).toHaveProperty('image');
+      expect(item).toHaveProperty('brief');
+      expect(Object.keys(item)).toHaveLength(7);
+    }
+  });
+
+  it('reports efforts: ["low", "high"] and defaultEffort: "high" for gemini-3.1-pro in JSON', () => {
+    const { ctx, getStdout } = createTestContext();
+    modelsImpl.call(ctx, { json: true });
+
+    const data = JSON.parse(getStdout());
+    const geminiPro = data.find(
+      (item: { slug: string }) => item.slug === 'google-antigravity/gemini-3.1-pro',
+    );
+    expect(geminiPro).toBeDefined();
+    expect(geminiPro.efforts).toEqual(['low', 'high']);
+    expect(geminiPro.defaultEffort).toBe('high');
+  });
+
+  it('reports backendModel and image correctly for opus-5 and gpt-5.6-sol in JSON', () => {
+    const { ctx, getStdout } = createTestContext();
+    modelsImpl.call(ctx, { json: true });
+
+    const data = JSON.parse(getStdout());
+    const opus = data.find((item: { slug: string }) => item.slug === 'anthropic-claude/opus-5');
+    expect(opus).toBeDefined();
+    expect(opus.backendModel).toBe('claude-opus-5[1m]');
+    expect(opus.image).toBeNull();
+
+    const sol = data.find((item: { slug: string }) => item.slug === 'openai-codex/gpt-5.6-sol');
+    expect(sol).toBeDefined();
+    expect(sol.image).toBe('png');
+  });
+
+  it('human output (no --json) contains every slug in MODELS', () => {
+    const { ctx, getStdout } = createTestContext();
+    modelsImpl.call(ctx, { json: false });
+
+    const output = getStdout();
+    for (const slug of Object.keys(MODELS)) {
+      expect(output).toContain(slug);
+    }
+  });
+});

package/src/commands/models/impl.ts

@@ -0,0 +1,71 @@
+import type { LocalContext } from '../../context.ts';
+import { type Backend, imageFormatFor, MODELS } from '../../models.ts';
+
+export interface ModelsFlags {
+  readonly json: boolean;
+}
+
+const BACKEND_DISPLAY_NAMES: Record<Backend, string> = {
+  grok: 'grok (Grok CLI)',
+  agy: 'agy (Antigravity)',
+  codex: 'codex (Codex CLI)',
+  claude: 'claude (Claude Code CLI)',
+};
+
+export default function modelsImpl(this: LocalContext, flags: ModelsFlags): void {
+  const specs = Object.values(MODELS);
+
+  if (flags.json) {
+    const jsonOutput = specs.map(spec => ({
+      slug: spec.slug,
+      backend: spec.backend,
+      backendModel: spec.backendModel,
+      efforts: spec.efforts ? [...spec.efforts] : [],
+      defaultEffort: spec.defaultEffort ?? null,
+      image: imageFormatFor({ spec, effort: undefined }) ?? null,
+      brief: spec.brief,
+    }));
+    this.process.stdout.write(`${JSON.stringify(jsonOutput)}\n`);
+    return;
+  }
+
+  const backends: Backend[] = [];
+  for (const spec of specs) {
+    if (!backends.includes(spec.backend)) {
+      backends.push(spec.backend);
+    }
+  }
+
+  let firstBackend = true;
+  for (const backend of backends) {
+    if (!firstBackend) {
+      this.process.stdout.write('\n');
+    }
+    firstBackend = false;
+
+    this.process.stdout.write(`=== ${BACKEND_DISPLAY_NAMES[backend]} ===\n`);
+    const backendSpecs = specs.filter(spec => spec.backend === backend);
+    for (const spec of backendSpecs) {
+      this.process.stdout.write(`  ${spec.slug}\n`);
+
+      const segments: string[] = [];
+      if (spec.efforts) {
+        const formattedEfforts = spec.efforts
+          .map(e => (e === spec.defaultEffort ? `${e}*` : e))
+          .join(' | ');
+        segments.push(`efforts: ${formattedEfforts}`);
+      }
+      const img = imageFormatFor({ spec, effort: undefined });
+      segments.push(`image: ${img ?? '—'}`);
+      segments.push(`id: ${spec.backendModel}`);
+
+      this.process.stdout.write(`    ${segments.join(' · ')}\n`);
+      this.process.stdout.write(`    ${spec.brief}\n`);
+    }
+  }
+
+  const hasDefaultEffort = specs.some(spec => spec.defaultEffort !== undefined);
+  if (hasDefaultEffort) {
+    this.process.stdout.write('\n* = effort used when the slug has no -<effort> suffix\n');
+  }
+}

package/src/commands/quota/command.ts

@@ -2,6 +2,8 @@ import { buildCommand } from '@stricli/core';
 import quotaImpl from './impl.ts';
 
 const fullDescription = [
+  'grok: reads ~/.grok/auth.json and asks the xAI billing endpoint for the',
+  'weekly credit usage percentage and per-product split.',
   'agy: reads its cached OAuth token (~/.gemini/antigravity-cli/) and asks the',
   'Cloud Code API for per-model remaining quota. EXHAUSTED means agy turns on',
   'that model fail with an empty answer until the reset time.',
@@ -24,7 +26,7 @@ export const quota = buildCommand({
     },
   },
   docs: {
-    brief: 'Show agy / codex / claude quota with reset times',
+    brief: 'Show grok / agy / codex / claude quota with reset times',
     fullDescription,
   },
 });

package/src/commands/quota/impl.ts

@@ -1,6 +1,7 @@
 import { type AgyQuotaSnapshot, fetchAgyQuota } from '@aibridge/driver-agy';
 import { type ClaudeQuotaSnapshot, fetchClaudeQuota } from '@aibridge/driver-claude';
 import { type CodexQuotaSnapshot, fetchCodexQuota } from '@aibridge/driver-codex';
+import { fetchGrokQuota, type GrokQuotaSnapshot } from '@aibridge/driver-grok';
 import type { LocalContext } from '../../context.ts';
 
 export interface QuotaFlags {
@@ -17,6 +18,20 @@ function formatReset(resetTime: string | undefined): string {
   return `${new Date(resetTime).toLocaleTimeString()} (in ${rel})`;
 }
 
+function renderGrok(ctx: LocalContext, snapshot: GrokQuotaSnapshot): void {
+  ctx.process.stdout.write('=== grok (xAI) — used this period ===\n');
+  ctx.process.stdout.write(`${'PERIOD'.padEnd(10)} ${'USED'.padEnd(10)} RESET\n`);
+  const usedPctStr = snapshot.usedPercent !== undefined ? `${snapshot.usedPercent}%` : '?';
+  const periodStr = snapshot.periodType ?? '-';
+  ctx.process.stdout.write(
+    `${periodStr.padEnd(10)} ${usedPctStr.padEnd(10)} ${formatReset(snapshot.periodEnd)}\n`,
+  );
+  if (snapshot.products.length > 0) {
+    const prods = snapshot.products.map(p => `${p.product} ${p.usedPercent}%`).join(' · ');
+    ctx.process.stdout.write(`  ${prods}\n`);
+  }
+}
+
 function renderAgy(ctx: LocalContext, snapshot: AgyQuotaSnapshot): void {
   ctx.process.stdout.write('=== agy (Antigravity) — remaining per model group ===\n');
   for (const group of snapshot.groups) {
@@ -75,19 +90,24 @@ function renderSection<T>(
 }
 
 export default async function quotaImpl(this: LocalContext, flags: QuotaFlags): Promise<void> {
-  const [agy, codex, claude] = await Promise.allSettled([
+  const [grok, agy, codex, claude] = await Promise.allSettled([
+    fetchGrokQuota(),
     fetchAgyQuota(),
     fetchCodexQuota(),
     fetchClaudeQuota(),
   ]);
 
   const allFailed =
-    agy.status === 'rejected' && codex.status === 'rejected' && claude.status === 'rejected';
+    grok.status === 'rejected' &&
+    agy.status === 'rejected' &&
+    codex.status === 'rejected' &&
+    claude.status === 'rejected';
 
   if (flags.json) {
     this.process.stdout.write(
       `${JSON.stringify(
         {
+          grok: grok.status === 'fulfilled' ? grok.value : { error: String(grok.reason) },
           agy: agy.status === 'fulfilled' ? agy.value : { error: String(agy.reason) },
           codex: codex.status === 'fulfilled' ? codex.value : { error: String(codex.reason) },
           claude: claude.status === 'fulfilled' ? claude.value : { error: String(claude.reason) },
@@ -100,6 +120,8 @@ export default async function quotaImpl(this: LocalContext, flags: QuotaFlags):
     return;
   }
 
+  renderSection(this, grok, 'grok (xAI)', renderGrok);
+  this.process.stdout.write('\n');
   renderSection(this, agy, 'agy (Antigravity)', renderAgy);
   this.process.stdout.write('\n');
   renderSection(this, codex, 'codex (ChatGPT)', renderCodex);

package/src/commands/subagent/command.ts

@@ -8,8 +8,8 @@ const fullDescription = [
   '',
   'Available models (canonical slug):',
   ...listModelHelpLines(),
-  'Recommended first choice: xai-grok/grok-4.5 (off-budget). The claude-backend slugs are FALLBACKS for',
-  'when the off-budget CLIs are quota-exhausted — they bill your Claude subscription.',
+  'Recommended first choice: xai-grok/grok-4.5. Whichever seat runs on the same provider as the',
+  'agent you orchestrate from is your last resort — it spends the pool you are already burning.',
 ].join('\n');
 
 export const subagent = buildCommand({

package/src/driver.ts

@@ -1,6 +1,7 @@
 import type { AgyQuotaSnapshot } from '@aibridge/driver-agy';
 import type { ClaudeQuotaSnapshot } from '@aibridge/driver-claude';
 import type { CodexQuotaSnapshot } from '@aibridge/driver-codex';
+import type { GrokQuotaSnapshot } from '@aibridge/driver-grok';
 import type { Effort } from './models.ts';
 
 export type Availability =
@@ -28,7 +29,11 @@ export type DelegationResult =
       readonly exitCode: number | null;
     };
 
-export type QuotaSnapshot = AgyQuotaSnapshot | CodexQuotaSnapshot | ClaudeQuotaSnapshot;
+export type QuotaSnapshot =
+  | AgyQuotaSnapshot
+  | CodexQuotaSnapshot
+  | ClaudeQuotaSnapshot
+  | GrokQuotaSnapshot;
 
 export interface ImageGenRequest {
   readonly prompt: string;

package/src/drivers.ts

@@ -15,6 +15,7 @@ const agyDriver: AgentCliDriver = {
 const grokDriver: AgentCliDriver = {
   probe: () => grok.probe(),
   run: task => grok.run(task),
+  quota: () => grok.fetchGrokQuota(),
   generateImage: req => grok.generateImage(req),
 };
 

package/src/models.ts

@@ -4,7 +4,7 @@
  * Models are registered by canonical, provider-qualified slug —
  * `<vendor>-<cli>/<model>[-<effort>]`, e.g. `openai-codex/gpt-5.6-sol-high`.
  * Canonical slugs only — no short aliases, by design. That holds on both sides:
- * `backendModel` is a pinned model id (`claude-opus-5`), never a moving vendor
+ * `backendModel` is a pinned model id (`claude-sonnet-5`), never a moving vendor
  * alias (`opus`), so a seat never silently changes model under you.
  */
 
@@ -31,7 +31,7 @@ export const MODELS: Record<string, ModelSpec> = {
     backend: 'grok',
     backendModel: 'grok-4.5',
     efforts: ['low', 'medium', 'high'],
-    brief: 'xAI Grok 4.5 via grok CLI — default for plan & review; own xAI login',
+    brief: 'xAI Grok 4.5 via grok CLI — own xAI login; ~30 req/min, ~1k msgs/day, single-flight',
   },
   'google-antigravity/gemini-3.6-flash': {
     slug: 'google-antigravity/gemini-3.6-flash',
@@ -40,7 +40,17 @@ export const MODELS: Record<string, ModelSpec> = {
     efforts: ['low', 'medium', 'high'],
     defaultEffort: 'high',
     brief:
-      'Google Gemini 3.6 Flash via agy — default for implement, also image-gen; own Antigravity login',
+      'Google Gemini 3.6 Flash via agy — own Antigravity login; quota shared across all Gemini tiers',
+  },
+  'google-antigravity/gemini-3.1-pro': {
+    slug: 'google-antigravity/gemini-3.1-pro',
+    backend: 'agy',
+    // agy exposes only -high and -low for this class — there is no medium tier.
+    efforts: ['low', 'high'],
+    backendModel: 'gemini-3.1-pro',
+    defaultEffort: 'high',
+    brief:
+      'Google Gemini 3.1 Pro via agy — own Antigravity login; quota shared across all Gemini tiers',
   },
   'google-antigravity/claude-sonnet-4-6': {
     slug: 'google-antigravity/claude-sonnet-4-6',
@@ -68,30 +78,53 @@ export const MODELS: Record<string, ModelSpec> = {
     backend: 'codex',
     backendModel: 'gpt-5.6-sol',
     efforts: ['low', 'medium', 'high', 'xhigh'],
-    brief: 'OpenAI Codex gpt-5.6-sol via codex CLI',
+    brief: 'OpenAI gpt-5.6-sol via codex CLI — frontier agentic coding; own ChatGPT login',
   },
-  'anthropic-claude/sonnet-5': {
-    slug: 'anthropic-claude/sonnet-5',
+  'openai-codex/gpt-5.6-terra': {
+    slug: 'openai-codex/gpt-5.6-terra',
+    backend: 'codex',
+    backendModel: 'gpt-5.6-terra',
+    efforts: ['low', 'medium', 'high', 'xhigh'],
+    brief: 'OpenAI gpt-5.6-terra via codex CLI — balanced, everyday coding; own ChatGPT login',
+  },
+  'openai-codex/gpt-5.6-luna': {
+    slug: 'openai-codex/gpt-5.6-luna',
+    backend: 'codex',
+    backendModel: 'gpt-5.6-luna',
+    efforts: ['low', 'medium', 'high', 'xhigh'],
+    brief: 'OpenAI gpt-5.6-luna via codex CLI — fast and affordable coding; own ChatGPT login',
+  },
+  'anthropic-claude/fable-5': {
+    slug: 'anthropic-claude/fable-5',
     backend: 'claude',
-    backendModel: 'claude-sonnet-5',
+    backendModel: 'claude-fable-5',
     efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-    brief: 'Claude Sonnet 5 via claude CLI — bills your Claude subscription',
+    defaultEffort: 'high',
+    brief:
+      'Claude Fable 5 via claude CLI — hardest, longest-running work; bills the claude CLI subscription',
   },
   'anthropic-claude/opus-5': {
     slug: 'anthropic-claude/opus-5',
     backend: 'claude',
-    backendModel: 'claude-opus-5',
+    backendModel: 'claude-opus-5[1m]',
     efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
     defaultEffort: 'high',
-    brief: 'Claude Opus 5 via claude CLI (default effort: high) — bills subscription',
+    brief:
+      'Claude Opus 5, 1M context via claude CLI — everyday complex work; bills the claude CLI subscription',
+  },
+  'anthropic-claude/sonnet-5': {
+    slug: 'anthropic-claude/sonnet-5',
+    backend: 'claude',
+    backendModel: 'claude-sonnet-5',
+    efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+    brief: 'Claude Sonnet 5 via claude CLI — routine work; bills the claude CLI subscription',
   },
-  'anthropic-claude/opus-5-1m': {
-    slug: 'anthropic-claude/opus-5-1m',
+  'anthropic-claude/haiku-4-5': {
+    slug: 'anthropic-claude/haiku-4-5',
     backend: 'claude',
-    backendModel: 'claude-opus-5[1m]',
+    backendModel: 'claude-haiku-4-5-20251001',
     efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-    defaultEffort: 'high',
-    brief: 'Claude Opus 5, 1M context via claude CLI — long-context work; bills subscription',
+    brief: 'Claude Haiku 4.5 via claude CLI — quick answers; bills the claude CLI subscription',
   },
 } as const satisfies Record<string, ModelSpec>;
 

package/src/quotaPreflight.test.ts

@@ -1,8 +1,13 @@
 import assert from 'node:assert/strict';
 import type { AgyQuotaSnapshot } from '@aibridge/driver-agy';
 import type { CodexQuotaSnapshot } from '@aibridge/driver-codex';
+import type { GrokQuotaSnapshot } from '@aibridge/driver-grok';
 import { test } from 'vitest';
-import { evaluateAgyPreflight, evaluateCodexPreflight } from './quotaPreflight.ts';
+import {
+  evaluateAgyPreflight,
+  evaluateCodexPreflight,
+  evaluateGrokPreflight,
+} from './quotaPreflight.ts';
 
 test('evaluateAgyPreflight: exhausted model returns ok:false with resetTime', () => {
   const snapshot: AgyQuotaSnapshot = {
@@ -176,3 +181,43 @@ test('evaluateCodexPreflight: healthy (77% used) returns ok:true', () => {
 
   assert.deepEqual(result, { ok: true });
 });
+
+test('evaluateGrokPreflight: usedPercent at 100 refuses with resetAt', () => {
+  const snapshot: GrokQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    periodType: 'weekly',
+    periodStart: '2024-01-01T00:00:00Z',
+    periodEnd: '2024-01-08T00:00:00Z',
+    usedPercent: 100,
+    products: [],
+    onDemandUsedCents: undefined,
+    onDemandCapCents: undefined,
+    prepaidBalanceCents: undefined,
+  };
+
+  const result = evaluateGrokPreflight(snapshot);
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'grok credit quota exhausted',
+    resetAt: '2024-01-08T00:00:00Z',
+  });
+});
+
+test('evaluateGrokPreflight: healthy (17% used) returns ok:true', () => {
+  const snapshot: GrokQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    periodType: 'weekly',
+    periodStart: '2024-01-01T00:00:00Z',
+    periodEnd: '2024-01-08T00:00:00Z',
+    usedPercent: 17,
+    products: [],
+    onDemandUsedCents: undefined,
+    onDemandCapCents: undefined,
+    prepaidBalanceCents: undefined,
+  };
+
+  const result = evaluateGrokPreflight(snapshot);
+
+  assert.deepEqual(result, { ok: true });
+});

package/src/quotaPreflight.ts

@@ -1,5 +1,6 @@
 import { type AgyQuotaSnapshot, fetchAgyQuota, findModelQuota } from '@aibridge/driver-agy';
 import { type CodexQuotaSnapshot, fetchCodexQuota } from '@aibridge/driver-codex';
+import { fetchGrokQuota, type GrokQuotaSnapshot } from '@aibridge/driver-grok';
 import { backendModelId, type ResolvedModel } from './models.ts';
 
 export type PreflightVerdict =
@@ -51,11 +52,27 @@ export function evaluateCodexPreflight(snapshot: CodexQuotaSnapshot): PreflightV
   return { ok: true };
 }
 
+export function evaluateGrokPreflight(snapshot: GrokQuotaSnapshot): PreflightVerdict {
+  if (snapshot.usedPercent !== undefined && snapshot.usedPercent >= 100) {
+    return {
+      ok: false,
+      message: 'grok credit quota exhausted',
+      resetAt: snapshot.periodEnd,
+    };
+  }
+
+  return { ok: true };
+}
+
 export async function preflightModel(resolved: ResolvedModel): Promise<PreflightVerdict> {
   if (resolved.spec.backend === 'codex') {
     return preflightCodex();
   }
 
+  if (resolved.spec.backend === 'grok') {
+    return preflightGrok();
+  }
+
   if (resolved.spec.backend !== 'agy') {
     return { ok: true };
   }
@@ -83,6 +100,18 @@ export async function preflightCodex(): Promise<PreflightVerdict> {
   }
 }
 
+export async function preflightGrok(): Promise<PreflightVerdict> {
+  try {
+    const snapshot = await fetchGrokQuota();
+    return evaluateGrokPreflight(snapshot);
+  } catch (err) {
+    return {
+      ok: true,
+      warning: `quota preflight failed (${(err as Error).message}); proceeding`,
+    };
+  }
+}
+
 function formatReset(resetTime: string | undefined): string {
   if (!resetTime) return '-';
   const ms = new Date(resetTime).getTime() - Date.now();