pi-claude-agent-sdk 0.8.3 → 0.8.5

package/README.md

@@ -21,13 +21,13 @@ pi install npm:pi-claude-agent-sdk
 
 ## Provider
 
-Use `/model` to select `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-opus-4-8`, `claude-bridge/claude-opus-4-7`, `claude-bridge/claude-opus-4-6`, `claude-bridge/claude-sonnet-5`, `claude-bridge/claude-sonnet-4-6`, or `claude-bridge/claude-haiku-4-5`.
+Use `/model` to select `claude-bridge/claude-fable-5-1`, `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-opus-4-8`, `claude-bridge/claude-opus-4-7`, `claude-bridge/claude-opus-4-6`, `claude-bridge/claude-sonnet-5`, `claude-bridge/claude-sonnet-4-6`, or `claude-bridge/claude-haiku-4-5`. The `fable` shortcut resolves to Fable 5.1. Fable 5.1 needs Claude Code **2.1.251 or newer** (the SDK's bundled CLI is 2.1.257). If you point `provider.pathToClaudeCodeExecutable` at an older binary, or a later model outruns the bundle, the bridge uses a current `claude` on PATH when it finds one.
 
 Behind the scenes, pi's tools are bridged to Claude Code but it should all work like normal in pi. Bash commands get a 120-second default timeout (matching Claude Code's default) since pi's bash has no timeout by default. Skills in pi are copied over to Claude Code's system prompt so should work as they would with any other pi provider. Steering works mid-turn: a message sent while Claude is running a tool reaches it at that tool boundary, not after the whole turn finishes.
 
 **Authentication:** the bridge requires an Anthropic OAuth credential (or API key) configured in Pi and uses Pi's normal token refresh. Claude Code login and inherited Claude/Anthropic authentication settings are deliberately ignored, so configure Anthropic authentication in Pi before using the provider.
 
-**1M Context:** Opus 5, Opus 4.8, and Opus 4.7 get 1M context by default. Opus 4.6 only gets 1M if you're on a Max plan or pay for Extra Usage. Sonnet 4.6 only gets 1M if you pay for Extra Usage. You will need to set `provider.plan` and/or `provider.longContextExtraUsage` for 1M context in Opus 4.6/Sonnet 4.6 as described in [Configuration](#configuration).
+**1M Context:** Fable 5.1, Fable 5, Opus 5, Opus 4.8, and Opus 4.7 get 1M context by default. Opus 4.6 only gets 1M if you're on a Max plan or pay for Extra Usage. Sonnet 4.6 only gets 1M if you pay for Extra Usage. You will need to set `provider.plan` and/or `provider.longContextExtraUsage` for 1M context in Opus 4.6/Sonnet 4.6 as described in [Configuration](#configuration).
 
 ## Configuration
 
@@ -49,7 +49,7 @@ Config: `~/.pi/agent/claude-bridge.json` (global) or the project Pi config direc
 - `longContextExtraUsage` — set to `true` to enable 1M models that cost money through Extra Usage. It enables Sonnet 4.6 with 1M on every plan and Opus 4.6 with 1M on Pro. Not needed for Opus 4.7 or 4.8.
 - `strictMcpConfig` — block MCP servers from `~/.claude.json` / `.mcp.json` (default `true`). Cloud MCP (Gmail/Drive via claude.ai OAuth) is always blocked.
 - `autoMemoryEnabled` — enable Claude Code's auto-memory system (default `false`)
-- `pathToClaudeCodeExecutable` — path to the `claude` binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run. For example, with Nix you can set the binary to e.g. `"/home/you/.nix-profile/bin/claude"`.
+- `pathToClaudeCodeExecutable` — path to the `claude` binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run, or to pin a specific CLI. For example, with Nix you can set the binary to e.g. `"/home/you/.nix-profile/bin/claude"`.
 
 **Extension providers and models.json:** pi's `modelOverrides` in `~/.pi/agent/models.json` do not currently apply to extension-registered providers (like claude-bridge). Overriding `contextWindow` or other fields requires editing `src/models.ts` directly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-agent-sdk",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "private": false,
   "description": "Pi extension that uses Claude Code (via Agent SDK) as a model provider.",
   "keywords": [
@@ -40,7 +40,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.141",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.257",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cc-session-io": "^0.4.0",
     "change-case": "^5.4.4"
@@ -50,7 +50,7 @@
     "@earendil-works/pi-coding-agent": ">=0.82.1"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.73.0",
+    "@anthropic-ai/sdk": "^0.93.0",
     "@earendil-works/pi-ai": "^0.83.0",
     "@earendil-works/pi-coding-agent": "^0.83.0",
     "@types/node": "^24.13.2",

package/src/claude-executable.ts

@@ -0,0 +1,149 @@
+// Pick a Claude Code CLI that can actually serve the selected model.
+// The Agent SDK bundles its own binary (`claudeCodeVersion` in its package.json).
+// Some models (Fable 5.1) 400 against an older CLI; when the bundle is below
+// the model's minimum we use a current `claude` on PATH, matching what the
+// README already told people to set via pathToClaudeCodeExecutable.
+
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join } from "node:path";
+import { minClaudeCodeVersionForModel } from "./models.js";
+
+const require = createRequire(import.meta.url);
+
+export type ClaudeVersion = { major: number; minor: number; patch: number };
+
+export type ClaudeExecutableSource = "configured" | "bundled" | "path";
+
+export type ClaudeExecutableResolution = {
+	/** Absolute path for the SDK, or undefined to use the bundled CLI. */
+	path?: string;
+	source: ClaudeExecutableSource;
+	/** Set when no available CLI meets the model's minimum version. */
+	error?: string;
+};
+
+export type ClaudeExecutableDeps = {
+	bundledVersion?: () => ClaudeVersion | undefined;
+	findOnPath?: () => string | undefined;
+	readVersion?: (executable: string) => ClaudeVersion | undefined;
+};
+
+const versionCache = new Map<string, ClaudeVersion | undefined>();
+
+export function parseClaudeVersion(text: string): ClaudeVersion | undefined {
+	const match = text.match(/(\d+)\.(\d+)\.(\d+)/);
+	if (!match) return undefined;
+	return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function formatClaudeVersion(version: ClaudeVersion): string {
+	return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+export function compareClaudeVersion(a: ClaudeVersion, b: ClaudeVersion): number {
+	return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+export function readBundledClaudeCodeVersion(): ClaudeVersion | undefined {
+	try {
+		// The SDK does not export ./package.json; read the file next to its entry.
+		const pkgPath = join(dirname(require.resolve("@anthropic-ai/claude-agent-sdk")), "package.json");
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { claudeCodeVersion?: string };
+		return parseClaudeVersion(pkg.claudeCodeVersion ?? "");
+	} catch {
+		return undefined;
+	}
+}
+
+export function findExecutableOnPath(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const pathEnv = env.PATH ?? env.Path;
+	if (!pathEnv) return undefined;
+	const exts = process.platform === "win32"
+		? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+		: [""];
+	const names = process.platform === "win32" && !exts.some((ext) => name.toUpperCase().endsWith(ext.toUpperCase()))
+		? [name, ...exts.map((ext) => name + ext)]
+		: [name];
+	for (const dir of pathEnv.split(delimiter)) {
+		if (!dir) continue;
+		for (const candidateName of names) {
+			const candidate = join(dir, candidateName);
+			try {
+				accessSync(candidate, constants.X_OK);
+				return candidate;
+			} catch {}
+		}
+	}
+	return undefined;
+}
+
+export function readClaudeCliVersion(executable: string): ClaudeVersion | undefined {
+	if (versionCache.has(executable)) return versionCache.get(executable);
+	try {
+		const result = spawnSync(executable, ["--version"], {
+			encoding: "utf8",
+			timeout: 8000,
+			env: process.env,
+			windowsHide: true,
+		});
+		const version = parseClaudeVersion(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+		versionCache.set(executable, version);
+		return version;
+	} catch {
+		versionCache.set(executable, undefined);
+		return undefined;
+	}
+}
+
+function tooOldError(modelId: string, min: ClaudeVersion, found: string): string {
+	return `${modelId} requires Claude Code ${formatClaudeVersion(min)} or newer (${found}). Install a current claude on PATH, or set provider.pathToClaudeCodeExecutable in ~/.pi/agent/claude-bridge.json.`;
+}
+
+export function resolveClaudeCodeExecutable(
+	modelId: string,
+	configured?: string,
+	deps: ClaudeExecutableDeps = {},
+): ClaudeExecutableResolution {
+	const bundledVersion = deps.bundledVersion ?? readBundledClaudeCodeVersion;
+	const findOnPath = deps.findOnPath ?? (() => findExecutableOnPath("claude"));
+	const readVersion = deps.readVersion ?? readClaudeCliVersion;
+	const minText = minClaudeCodeVersionForModel(modelId);
+	const min = minText ? parseClaudeVersion(minText) : undefined;
+
+	if (configured) {
+		if (min) {
+			const version = readVersion(configured);
+			if (version && compareClaudeVersion(version, min) < 0) {
+				return {
+					source: "configured",
+					error: tooOldError(modelId, min, `provider.pathToClaudeCodeExecutable is ${formatClaudeVersion(version)} at ${configured}`),
+				};
+			}
+		}
+		return { path: configured, source: "configured" };
+	}
+
+	if (!min) return { source: "bundled" };
+
+	const bundled = bundledVersion();
+	if (bundled && compareClaudeVersion(bundled, min) >= 0) {
+		return { source: "bundled" };
+	}
+
+	const pathClaude = findOnPath();
+	if (pathClaude) {
+		const version = readVersion(pathClaude);
+		if (version && compareClaudeVersion(version, min) >= 0) {
+			return { path: pathClaude, source: "path" };
+		}
+	}
+
+	if (bundled) {
+		return { source: "bundled", error: tooOldError(modelId, min, `bundled CLI is ${formatClaudeVersion(bundled)}`) };
+	}
+
+	// Bundle version unknown and PATH missing/unreadable: let the SDK try.
+	return { source: "bundled" };
+}

package/src/convert.ts

@@ -116,10 +116,16 @@ export type DroppedContent = {
 	other: Map<string, number>;
 };
 
-/** Convert pi message array to Anthropic API format. */
+/** Convert pi message array to Anthropic API format.
+ *
+ *  `dropThinking` strips every thinking block, including ones we minted. Fable 5.1
+ *  binds thinking to the conversation prefix, so a rebuild that keeps the blocks
+ *  and rewrites system/tools is a 400. Removing a leading run of thinking is the
+ *  documented-safe alternative. */
 export function convertPiMessages(
 	messages: PiMessage[],
 	customToolNameToSdk?: Map<string, string>,
+	dropThinking = false,
 ): { anthropicMessages: SessionMessage[]; sanitizedIds: Map<string, string>; dropped: DroppedContent } {
 	const anthropicMessages = [];
 	const sanitizedIds = new Map();
@@ -160,7 +166,7 @@ export function convertPiMessages(
 					// by any other provider — including pi's own Anthropic provider — is
 					// not ours to hand back, and Anthropic rejects ones it can't verify.
 					const sig = block.thinkingSignature;
-					if (msg.provider === PROVIDER_ID && sig) {
+					if (!dropThinking && msg.provider === PROVIDER_ID && sig) {
 						blocks.push({ type: "thinking", thinking: block.thinking ?? "", signature: sig });
 					} else {
 						dropped.thinking++;

package/src/index.ts

@@ -9,7 +9,7 @@ import { appendFileSync, mkdirSync, realpathSync, statSync } from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
 import { PROVIDER_ID, messageContentToText, convertPiMessages } from "./convert.js";
-import { applyLongContext, buildModels, claudeCodeModelId, type LongContextSettings } from "./models.js";
+import { adaptiveThinkingAlwaysOn, applyLongContext, buildModels, claudeCodeModelId, thinkingBoundToPrefix, type LongContextSettings } from "./models.js";
 import { MCP_SERVER_NAME, MCP_TOOL_PREFIX } from "./skills.js";
 import { verifyWrittenSession as _verifyWrittenSession } from "./session-verify.js";
 import { extractAllToolResults as _extractAllToolResults, type McpResult } from "./extract-tool-results.js";
@@ -24,6 +24,7 @@ import {
 import { collectCarriedAttachments, placeCarriedAttachments, type CarriedAttachment } from "./attachments.js";
 import { createToolServer } from "./mcp-server.js";
 import { CC_CHILD_ENV, resolveClaudeChildEnv, type AnthropicAuthRegistry } from "./child-env.js";
+import { resolveClaudeCodeExecutable } from "./claude-executable.js";
 
 // Compat (#2): use factory if available (pi-ai ≥0.66), else fall back to constructor (gsd-pi etc.)
 const _piAi = piAi as any;
@@ -87,7 +88,7 @@ function debug(...args: unknown[]) {
 // Per-query CLI debug capture. When CLAUDE_BRIDGE_DEBUG=1, ask the Claude Code
 // CLI subprocess to write its own debug log to a file we choose, and also
 // forward its stderr into our debug stream. Drops straight into the real SDK's
-// Options — see @anthropic-ai/claude-agent-sdk sdk.d.ts:1245 (debug, debugFile,
+// Options — see @anthropic-ai/claude-agent-sdk sdk.d.ts:2091 (debug, debugFile,
 // stderr). Without this, CC's internal view of the world is invisible to us
 // and "No conversation found" / empty-error reports are unactionable.
 let nextCliDebugSeq = 1;
@@ -215,8 +216,9 @@ function convertAndImportMessages(
 	messages: Context["messages"],
 	customToolNameToSdk?: Map<string, string>,
 	carried?: readonly CarriedAttachment[],
+	dropThinking = false,
 ): void {
-	const { anthropicMessages, sanitizedIds, dropped } = convertPiMessages(messages, customToolNameToSdk);
+	const { anthropicMessages, sanitizedIds, dropped } = convertPiMessages(messages, customToolNameToSdk, dropThinking);
 
 	debug(`convertAndImportMessages: ${messages.length} pi msgs → ${anthropicMessages.length} anthropic msgs`);
 	debug(`convertAndImportMessages: imported roles:`, anthropicMessages.map((m, i) => {
@@ -429,7 +431,9 @@ async function runIsolatedSummary(
 		const promptText = extractIsolatedSummaryPrompt(context.messages);
 		const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
 		const compactProviderSettings = loadConfig(cwd).provider;
-		const claudeExecutable = compactProviderSettings?.pathToClaudeCodeExecutable;
+		const claudeExecutableResolution = resolveClaudeCodeExecutable(model.id, compactProviderSettings?.pathToClaudeCodeExecutable);
+		if (claudeExecutableResolution.error) throw new Error(claudeExecutableResolution.error);
+		const claudeExecutable = claudeExecutableResolution.path;
 		const cliModel = claudeCodeModelId(model, longContextSettings);
 		debug(`compact summary: spawn model=${cliModel} registeredModel=${model.id} promptLen=${promptText.length}`);
 		const childEnv = await resolveClaudeChildEnv(piModelRegistry);
@@ -676,7 +680,7 @@ function syncSharedSession(
 		...(preserveId ? { sessionId: previousSessionId } : {}),
 		...(modelId ? { model: modelId } : {}),
 	});
-	convertAndImportMessages(session, priorMessages, customToolNameToSdk, carried);
+	convertAndImportMessages(session, priorMessages, customToolNameToSdk, carried, thinkingBoundToPrefix(modelId ?? ""));
 	session.save();
 	// records, not messages: `messages` filters out the attachment records that
 	// carrying an `@file` expansion across a rebuild writes into the same file.
@@ -1491,6 +1495,19 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	const queryCtx = isReentrant ? new QueryContext() : ctx();
 	debug(`provider: fresh query setup, isReentrant=${isReentrant}, activeContexts=${activeQueryContexts.size}`);
 
+	// Fail before claiming a stream if this model needs a newer CLI than we have.
+	const claudeExecutableResolution = resolveClaudeCodeExecutable(model.id, providerSettings.pathToClaudeCodeExecutable);
+	if (claudeExecutableResolution.error) {
+		debug(`provider: ${claudeExecutableResolution.error}`);
+		stream.push({ type: "error", reason: "error", error: newAssistantOutput(model, "", "error", claudeExecutableResolution.error) });
+		stream.end();
+		return stream;
+	}
+	const claudeExecutable = claudeExecutableResolution.path;
+	if (claudeExecutableResolution.source === "path") {
+		debug(`provider: using PATH claude ${claudeExecutable} (bundled CLI is too old for ${model.id})`);
+	}
+
 	// Resolved first: an unaccountable system prompt throws, and doing that before
 	// anything is claimed or reset leaves no half-built query behind — in particular
 	// no stream claimed on the shared context that nobody will ever end.
@@ -1560,7 +1577,6 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// programmatically and ignore filesystem MCP entries — applied unconditionally because
 	// settingSources is left at CC's default, which loads all sources.
 	const strictMcpConfigEnabled = providerSettings.strictMcpConfig !== false;
-	const claudeExecutable = providerSettings.pathToClaudeCodeExecutable;
 
 	// Prefer the model's own thinkingLevelMap when present (pi-ai 0.72+ ships
 	// per-model overrides — e.g. opus-4-7 wants xhigh→xhigh, not xhigh→max).
@@ -1574,7 +1590,9 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	if (strictMcpConfigEnabled) extraArgs["strict-mcp-config"] = null;
 	// Opus 4.7 defaults thinking.display to "omitted" (empty thinking text in stream).
 	// Force summarized so thinking_delta events arrive. See anthropics/claude-agent-sdk-python#830.
-	if (effort) extraArgs["thinking-display"] = "summarized";
+	// Fable 5 / 5.1 always think and also default to omitted, even when we pass no effort
+	// (CC then uses the model default, high).
+	if (effort || adaptiveThinkingAlwaysOn(model.id)) extraArgs["thinking-display"] = "summarized";
 
 	// Suppress claude.ai cloud MCP servers (Figma/Canva/etc. auto-discovered via OAuth
 	// when the user is logged into Anthropic). These are a separate code path from

package/src/models.ts

@@ -2,14 +2,42 @@
 // `resolveModel` returns the first partial match, so `opus` resolves to the first-listed opus entry.
 // Extracted from index.ts so tests can import without activating the extension.
 
-export const MODEL_IDS_IN_ORDER = ["claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-4-5"];
+export const MODEL_IDS_IN_ORDER = ["claude-fable-5-1", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6", "claude-haiku-4-5"];
+
+const TWO_HUNDRED_K_CONTEXT = 200_000;
+const ONE_M_CONTEXT = 1_000_000;
+
+/** Catalog stubs for IDs Claude Code already serves that the installed pi-ai has
+ *  not listed yet. Prefer pi-ai when it has the entry. Fable 5.1 shipped
+ *  2026-09-01; pi-ai 0.84.4 (2026-08-28) does not include it. */
+export const FALLBACK_MODELS: Record<string, {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: string[];
+	contextWindow: number;
+	maxTokens: number;
+	thinkingLevelMap?: Record<string, string | null>;
+}> = {
+	"claude-fable-5-1": {
+		id: "claude-fable-5-1",
+		name: "Claude Fable 5.1",
+		reasoning: true,
+		input: ["text", "image"],
+		contextWindow: ONE_M_CONTEXT,
+		maxTokens: 128_000,
+		// Same shape as pi-ai's claude-fable-5: adaptive thinking, xhigh visible.
+		thinkingLevelMap: { off: null, xhigh: "xhigh", max: "max" },
+	},
+};
 
 // Project pi-ai's model entries down to the fields pi's registerProvider expects,
-// and keep MODEL_IDS_IN_ORDER ordering. IDs missing from pi-ai are silently dropped.
-// Context-dependent display labels are applied after plan/long-context config is known.
+// and keep MODEL_IDS_IN_ORDER ordering. IDs missing from pi-ai are silently dropped
+// unless FALLBACK_MODELS has a stub. Context-dependent display labels are applied
+// after plan/long-context config is known.
 export function buildModels<T extends { id: string; [key: string]: any }>(piAiModels: T[]) {
 	return MODEL_IDS_IN_ORDER
-		.map((id) => piAiModels.find((m) => m.id === id))
+		.map((id) => piAiModels.find((m) => m.id === id) ?? FALLBACK_MODELS[id])
 		.filter((m) => m != null)
 		// Forward thinkingLevelMap so pi-ai's per-model overrides (e.g. opus-4-8
 		// mapping xhigh→xhigh and max→max) are visible to the effort lookup.
@@ -32,9 +60,6 @@ export type ClaudeCodeRuntimeModel = {
 	contextWindow: number;
 };
 
-const TWO_HUNDRED_K_CONTEXT = 200_000;
-const ONE_M_CONTEXT = 1_000_000;
-
 // Measured Claude Agent SDK subscription/OAuth behavior. Do not infer this from
 // pi-ai's advertised contextWindow: bare Opus 4.7 serves 1M, bare Opus 4.8 does
 // not, and [1m] entitlement differs by model. See diag/CONTEXT-SIZE.md.
@@ -53,6 +78,11 @@ export function resolveClaudeCodeRuntimeModel(modelId: string, settings: LongCon
 				contextWindow: useOneM ? ONE_M_CONTEXT : TWO_HUNDRED_K_CONTEXT,
 			};
 		}
+		case "claude-fable-5-1":
+			// 1M is the default and the maximum, billed at standard rates across the
+			// whole window (no Extra Usage). CC still takes the [1m] suffix to request
+			// that window, same as Fable 5 / Opus 5.
+			return { cliModelId: "claude-fable-5-1[1m]", contextWindow: ONE_M_CONTEXT };
 		case "claude-fable-5":
 			return { cliModelId: "claude-fable-5[1m]", contextWindow: ONE_M_CONTEXT };
 		case "claude-sonnet-5":
@@ -74,9 +104,35 @@ export function claudeCodeModelId(model: { id: string }, settings: LongContextSe
 	return resolveClaudeCodeRuntimeModel(model.id, settings).cliModelId;
 }
 
+/** Adaptive thinking is always on. `thinking: enabled` with budget_tokens and
+ *  `disabled` both 400; omit thinking or send adaptive. `thinking.display`
+ *  defaults to omitted, so the stream has no thinking text unless we ask. */
+export function adaptiveThinkingAlwaysOn(modelId: string): boolean {
+	return modelId === "claude-fable-5-1" || modelId.startsWith("claude-fable-5-1[")
+		|| modelId === "claude-fable-5" || modelId.startsWith("claude-fable-5[");
+}
+
+/** Fable 5.1 binds each thinking block to the conversation prefix. Replaying a
+ *  block after a rebuild (new system prompt or tools) 400s with "The block is
+ *  bound to a different conversation". Resume is fine; rebuilds must drop
+ *  thinking. https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#editing-earlier-turns-invalidates-thinking-blocks */
+export function thinkingBoundToPrefix(modelId: string): boolean {
+	return modelId === "claude-fable-5-1" || modelId.startsWith("claude-fable-5-1[");
+}
+
+/** Minimum Claude Code CLI version that will accept this model. Undefined
+ *  means the SDK's bundled CLI is fine. Fable 5.1 400s on 2.1.141 with
+ *  "version 2.1.251 or newer is required". */
+export function minClaudeCodeVersionForModel(modelId: string): string | undefined {
+	if (modelId === "claude-fable-5-1" || modelId.startsWith("claude-fable-5-1[")) return "2.1.251";
+	return undefined;
+}
+
 export function resolveModel<T extends { id: string }>(models: T[], input: string): T | undefined {
 	const lower = input.toLowerCase();
-	return models.find((m) => m.id === lower || m.id.includes(lower));
+	// Exact match first: otherwise `claude-fable-5` would hit `claude-fable-5-1`
+	// via includes() when the newer id is listed first for the `fable` shortcut.
+	return models.find((m) => m.id === lower) ?? models.find((m) => m.id.includes(lower));
 }
 
 // Produce the model metadata registered with pi. The registered contextWindow must