@vanillagreen/pi-claude-bridge 1.1.3 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillagreen/pi-claude-bridge",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Pi provider bridge that runs Claude Code through the Claude Agent SDK, with opt-in forwarding for Pi prompt context.",
   "type": "module",
   "keywords": [
@@ -85,6 +85,15 @@
           "category": "Claude Code",
           "apply": "live"
         },
+        {
+          "key": "allowExtraUsage",
+          "label": "Allow extra usage helper",
+          "description": "Allow claude-bridge to launch Claude Code's /extra-usage flow when rate limits require extra usage. Billing/admin approval still happens in Claude's browser page.",
+          "type": "boolean",
+          "default": false,
+          "category": "Claude Code",
+          "apply": "live"
+        },
         {
           "key": "pathToClaudeCodeExecutable",
           "label": "Claude executable path",
@@ -98,7 +107,7 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.2.128",
+    "@anthropic-ai/claude-agent-sdk": "0.2.141",
     "@anthropic-ai/sdk": "^0.73.0",
     "cc-session-io": "^0.3.1",
     "change-case": "^5.4.4"
@@ -108,15 +117,15 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.75.0",
+    "@earendil-works/pi-coding-agent": "^0.75.0",
     "@types/node": "^24.3.0",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=bundle/index.js --external:@earendil-works/pi-ai --external:@earendil-works/pi-coding-agent",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=bundle/index.js --external:@earendil-works/pi-ai --external:@earendil-works/pi-coding-agent",
     "prepack": "npm run build",
     "test:unit": "node --import tsx --test tests/unit-*.mjs",
     "test": "set -a && [ -f .env.test ] && . ./.env.test; set +a && npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs",
@@ -145,6 +154,14 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
   }
 }

package/src/config.ts

@@ -14,6 +14,7 @@ export interface Config {
 	/** Low-level Claude Agent SDK plumbing. Most users won't need these. */
 	provider?: {
 		appendSystemPrompt?: boolean;
+		allowExtraUsage?: boolean;
 		settingSources?: SettingSource[];
 		strictMcpConfig?: boolean;
 		pathToClaudeCodeExecutable?: string;
@@ -111,6 +112,8 @@ function managerToConfig(raw: SettingsRecord): Partial<Config> {
 
 	const appendSystemPrompt = boolFrom(raw, "appendSystemPrompt");
 	if (appendSystemPrompt !== undefined) provider.appendSystemPrompt = appendSystemPrompt;
+	const allowExtraUsage = boolFrom(raw, "allowExtraUsage");
+	if (allowExtraUsage !== undefined) provider.allowExtraUsage = allowExtraUsage;
 	const strictMcpConfig = boolFrom(raw, "strictMcpConfig");
 	if (strictMcpConfig !== undefined) provider.strictMcpConfig = strictMcpConfig;
 	const claudePath = stringFrom(raw, "pathToClaudeCodeExecutable");

package/src/index.ts

@@ -1,11 +1,12 @@
 import { calculateCost, getModels, type AssistantMessage, type AssistantMessageEventStream, type Context, type Model, type SimpleStreamOptions, type Tool } from "@earendil-works/pi-ai";
 import * as piAi from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
-import { createSdkMcpServer, query, type EffortLevel, type SDKMessage, type SDKUserMessage, type SettingSource } from "@anthropic-ai/claude-agent-sdk";
+import { createSdkMcpServer, query, type EffortLevel, type SDKMessage, type SDKUserMessage, type SettingSource, type SpawnOptions, type SpawnedProcess } from "@anthropic-ai/claude-agent-sdk";
 import type { Base64ImageSource, ContentBlockParam, MessageParam } from "@anthropic-ai/sdk/resources";
 import { createSession, deleteSession, openSession, repairToolPairing } from "cc-session-io";
+import { spawn as spawnProcess } from "child_process";
 import { createHash } from "crypto";
-import { accessSync, appendFileSync, constants as fsConstants, mkdirSync, realpathSync, statSync } from "fs";
+import { accessSync, appendFileSync, constants as fsConstants, mkdirSync, readFileSync, realpathSync, statSync } from "fs";
 import { resolve as pathResolve } from "path";
 import { homedir } from "os";
 import { delimiter, dirname, join } from "path";
@@ -15,7 +16,7 @@ import { MCP_SERVER_NAME, MCP_TOOL_PREFIX, extractSkillsBlock } from "./skills.j
 import { verifyWrittenSession as _verifyWrittenSession } from "./session-verify.js";
 import { extractAllToolResults as _extractAllToolResults, type McpResult } from "./extract-tool-results.js";
 import { QueryContext, ctx, stackDepth, pushContext, popContext } from "./query-state.js";
-import { loadConfig } from "./config.js";
+import { loadConfig, type Config } from "./config.js";
 import { extractAgentsAppend } from "./agents-md.js";
 import { buildPromptContextAppend } from "./prompt-context.js";
 import { jsonSchemaToZodShape } from "./typebox-to-zod.js";
@@ -79,6 +80,240 @@ function resolveClaudeExecutable(configured?: string): string | undefined {
 	return executableFromPath("claude") ?? executableFromPath("claude-code");
 }
 
+export type ClaudeExecutableFileType = "elf" | "mach-o" | "pe" | "shebang-script" | "empty" | "unknown";
+
+export interface ClaudeExecutablePreflightResult {
+	path: string;
+	realPath: string;
+	cwd: string;
+	realCwd: string;
+	fileType: ClaudeExecutableFileType;
+}
+
+function errnoValue(err: unknown): string | number | undefined {
+	return typeof (err as NodeJS.ErrnoException)?.errno === "number" ? (err as NodeJS.ErrnoException).errno : undefined;
+}
+
+function syscallValue(err: unknown): string | undefined {
+	return typeof (err as NodeJS.ErrnoException)?.syscall === "string" ? (err as NodeJS.ErrnoException).syscall : undefined;
+}
+
+function pathValue(err: unknown): string | undefined {
+	const value = (err as NodeJS.ErrnoException)?.path;
+	return typeof value === "string" ? value : undefined;
+}
+
+function codeValue(err: unknown, fallback: string): string {
+	const value = (err as NodeJS.ErrnoException)?.code;
+	return typeof value === "string" ? value : fallback;
+}
+
+function displayValue(value: unknown): string {
+	return value === undefined || value === null || value === "" ? "<none>" : String(value);
+}
+
+function makeClaudePreflightError(
+	summary: string,
+	details: { code: string; errno?: string | number; syscall?: string; path: string; cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string; cause?: unknown },
+): Error & NodeJS.ErrnoException & { cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string } {
+	const detail = [
+		`code=${details.code}`,
+		`errno=${displayValue(details.errno)}`,
+		`syscall=${displayValue(details.syscall)}`,
+		`path=${details.path}`,
+		`cwd=${details.cwd}`,
+		...(details.fileType ? [`fileType=${details.fileType}`] : []),
+		...(details.realPath ? [`realPath=${details.realPath}`] : []),
+	].join(" ");
+	const error = new Error(`${summary} (${detail})`) as Error & NodeJS.ErrnoException & { cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string };
+	error.name = "ClaudeExecutablePreflightError";
+	error.code = details.code;
+	if (details.errno !== undefined) error.errno = typeof details.errno === "number" ? details.errno : Number(details.errno);
+	if (details.syscall) error.syscall = details.syscall;
+	error.path = details.path;
+	error.cwd = details.cwd;
+	if (details.fileType) error.fileType = details.fileType;
+	if (details.realPath) error.realPath = details.realPath;
+	if (details.cause !== undefined) (error as Error & { cause?: unknown }).cause = details.cause;
+	return error;
+}
+
+export function classifyClaudeExecutableBytes(bytes: Uint8Array): ClaudeExecutableFileType {
+	if (bytes.length === 0) return "empty";
+	if (bytes.length >= 2 && bytes[0] === 0x23 && bytes[1] === 0x21) return "shebang-script";
+	if (bytes.length >= 4 && bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46) return "elf";
+	if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) return "pe";
+	if (bytes.length >= 4) {
+		const magic = bytes[0] * 0x1000000 + bytes[1] * 0x10000 + bytes[2] * 0x100 + bytes[3];
+		if (
+			magic === 0xfeedface ||
+			magic === 0xfeedfacf ||
+			magic === 0xcefaedfe ||
+			magic === 0xcffaedfe ||
+			magic === 0xcafebabe ||
+			magic === 0xbebafeca
+		) return "mach-o";
+	}
+	return "unknown";
+}
+
+export function preflightClaudeExecutable(path: string, cwd: string): ClaudeExecutablePreflightResult {
+	let realCwd = cwd;
+	try {
+		const cwdStat = statSync(cwd);
+		if (!cwdStat.isDirectory()) {
+			throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not a directory.", {
+				code: "ENOTDIR",
+				syscall: "chdir",
+				path: cwd,
+				cwd,
+			});
+		}
+		accessSync(cwd, fsConstants.X_OK);
+		realCwd = realpathSync(cwd);
+	} catch (err) {
+		if ((err as Error).name === "ClaudeExecutablePreflightError") throw err;
+		throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not reachable before spawning Claude Code.", {
+			code: codeValue(err, "EACCES"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? cwd,
+			cwd,
+			cause: err,
+		});
+	}
+
+	let realPath = path;
+	try {
+		const stat = statSync(path);
+		if (!stat.isFile()) {
+			throw makeClaudePreflightError("Claude Code executable preflight failed: resolved path is not a file.", {
+				code: "EACCES",
+				syscall: "exec",
+				path,
+				cwd,
+			});
+		}
+		accessSync(path, fsConstants.X_OK);
+		realPath = realpathSync(path);
+	} catch (err) {
+		if ((err as Error).name === "ClaudeExecutablePreflightError") throw err;
+		throw makeClaudePreflightError("Claude Code executable preflight failed: cannot access resolved executable before spawning Claude Code.", {
+			code: codeValue(err, "ENOENT"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? path,
+			cwd,
+			cause: err,
+		});
+	}
+
+	let fileType: ClaudeExecutableFileType;
+	try {
+		fileType = classifyClaudeExecutableBytes(readFileSync(realPath).subarray(0, 16));
+	} catch (err) {
+		throw makeClaudePreflightError("Claude Code executable preflight failed: cannot read executable header before spawning Claude Code.", {
+			code: codeValue(err, "EACCES"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? realPath,
+			cwd,
+			realPath,
+			cause: err,
+		});
+	}
+
+	if (!["elf", "mach-o", "pe", "shebang-script"].includes(fileType)) {
+		throw makeClaudePreflightError("Claude Code executable preflight failed: executable header is not an ELF, Mach-O, PE, or shebang script.", {
+			code: "ENOEXEC",
+			syscall: "exec",
+			path,
+			cwd,
+			fileType,
+			realPath,
+		});
+	}
+
+	return { path, realPath, cwd, realCwd, fileType };
+}
+
+function envFlagEnabled(value: string | undefined): boolean {
+	return value === "1" || value?.toLowerCase() === "true";
+}
+
+export function wrapClaudeSpawnErrorForSdk(err: Error, options: SpawnOptions): Error & NodeJS.ErrnoException & { cwd: string; originalCode?: string; originalMessage?: string } {
+	const originalCode = codeValue(err, "SPAWN_ERROR");
+	const originalMessage = err.message;
+	const spawnPath = pathValue(err) ?? options.command;
+	const cwd = options.cwd ?? process.cwd();
+	const detail = [
+		`code=${originalCode}`,
+		`errno=${displayValue(errnoValue(err))}`,
+		`syscall=${displayValue(syscallValue(err))}`,
+		`path=${spawnPath}`,
+		`cwd=${cwd}`,
+		`command=${options.command}`,
+	].join(" ");
+	const wrapped = new Error(`Claude Code spawn failed: ${originalMessage} (${detail})`) as Error & NodeJS.ErrnoException & { cwd: string; originalCode?: string; originalMessage?: string };
+	wrapped.name = "ClaudeSpawnDiagnosticError";
+	// The SDK special-cases code === ENOENT and replaces the message with its
+	// generic "native binary not found" text. Preserve the original code in the
+	// message/originalCode while using a bridge code so the SDK surfaces context.
+	wrapped.code = originalCode === "ENOENT" ? "CLAUDE_BRIDGE_SPAWN_FAILED" : originalCode;
+	wrapped.originalCode = originalCode;
+	wrapped.originalMessage = originalMessage;
+	const errno = errnoValue(err);
+	if (errno !== undefined) wrapped.errno = typeof errno === "number" ? errno : Number(errno);
+	const syscall = syscallValue(err);
+	if (syscall) wrapped.syscall = syscall;
+	wrapped.path = spawnPath;
+	wrapped.cwd = cwd;
+	// Do not set `cause` here: the listener copies these structured fields back
+	// onto the original Error. A cause reference to that same object would become
+	// `err.cause === err`, making JSON.stringify throw on a circular structure.
+	// originalMessage plus code/errno/syscall/path/cwd preserve the useful data.
+	return wrapped;
+}
+
+export function spawnClaudeCodeWithDiagnostics(options: SpawnOptions): SpawnedProcess {
+	const pipeStderr = DEBUG || envFlagEnabled(options.env.DEBUG_CLAUDE_AGENT_SDK);
+	const child = spawnProcess(options.command, options.args, {
+		cwd: options.cwd,
+		env: options.env,
+		signal: options.signal,
+		stdio: ["pipe", "pipe", pipeStderr ? "pipe" : "ignore"],
+		windowsHide: true,
+	});
+	if (pipeStderr) {
+		child.stderr?.on("data", (data) => {
+			for (const line of data.toString().split(/\r?\n/)) {
+				if (line) debug(`[cli-stderr spawn] ${line}`);
+			}
+		});
+	}
+	child.prependListener("error", (err) => {
+		const originalStack = err.stack;
+		const wrapped = wrapClaudeSpawnErrorForSdk(err, options);
+		Object.assign(err, wrapped);
+		err.name = wrapped.name;
+		err.message = wrapped.message;
+		// Keep V8's stack from the actual Node spawn failure, not the wrapper
+		// construction site. Diagnostic fields above remain enumerable and
+		// JSON-serializable; stack stays the spawn-time breadcrumb for operators.
+		if (originalStack) err.stack = originalStack;
+	});
+	return {
+		stdin: child.stdin,
+		stdout: child.stdout,
+		get killed() { return child.killed; },
+		get exitCode() { return child.exitCode; },
+		kill: child.kill.bind(child),
+		on: child.on.bind(child),
+		once: child.once.bind(child),
+		off: child.off.bind(child),
+	};
+}
+
 // 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
@@ -130,6 +365,7 @@ function diagDump(label: string, data: Record<string, unknown>) {
 // On session_shutdown (including /reload), clearSession() resets this so a fresh
 // registration can occur for the next session.
 const ACTIVE_STREAM_SIMPLE_KEY = Symbol.for("claude-bridge:activeStreamSimple");
+const COMMANDS_REGISTERED_KEY = Symbol.for("claude-bridge:commandsRegistered");
 
 const SDK_TO_PI_TOOL_NAME: Record<string, string> = {
 	read: "read", write: "write", edit: "edit", bash: "bash",
@@ -187,6 +423,82 @@ interface SessionState {
 
 let sharedSession: SessionState | null = null;
 let extensionApi: ExtensionAPI | undefined;
+let piUI: ExtensionUIContext | undefined;
+let extraUsageHelperInFlight: Promise<string> | null = null;
+
+export function isExtraUsageRequiredMessage(value: unknown): boolean {
+	let text: string;
+	if (typeof value === "string") text = value;
+	else if (value instanceof Error) text = value.message;
+	else {
+		try { text = JSON.stringify(value ?? ""); }
+		catch { text = String(value); }
+	}
+	return /extra[-\s]?usage|overage|extra usage billing|extra usage credits|1M context/i.test(text);
+}
+
+function extraUsageAllowed(config: Config): boolean {
+	return config.provider?.allowExtraUsage === true;
+}
+
+function sdkTextFromMessage(message: SDKMessage): string | undefined {
+	if (message.type === "result") return (message as any).result;
+	if (message.type === "assistant") {
+		const content = (message as any).message?.content;
+		if (!Array.isArray(content)) return undefined;
+		return content
+			.map((block) => block?.type === "text" && typeof block.text === "string" ? block.text : "")
+			.filter(Boolean)
+			.join("\n");
+	}
+	return undefined;
+}
+
+async function runExtraUsageHelper(cwd: string, config = loadConfig(cwd)): Promise<string> {
+	const providerSettings = config.provider ?? {};
+	const claudeExecutable = resolveClaudeExecutable(providerSettings.pathToClaudeCodeExecutable);
+	if (claudeExecutable) preflightClaudeExecutable(claudeExecutable, cwd);
+
+	const helperQuery = query({
+		prompt: "/extra-usage",
+		options: {
+			cwd,
+			env: { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: "0", DISABLE_AUTO_COMPACT: "1" },
+			maxTurns: 1,
+			...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
+			spawnClaudeCodeProcess: spawnClaudeCodeWithDiagnostics,
+			...makeCliDebugOptions("extra-usage"),
+		},
+	});
+	const outputs: string[] = [];
+	try {
+		for await (const message of helperQuery) {
+			const text = sdkTextFromMessage(message)?.trim();
+			if (text && outputs[outputs.length - 1] !== text) outputs.push(text);
+		}
+	} finally {
+		helperQuery.close();
+	}
+	return outputs.join("\n").trim() || "Claude Code /extra-usage completed.";
+}
+
+function launchExtraUsageHelperIfAllowed(cwd: string, config: Config, reason: string): boolean {
+	if (!extraUsageAllowed(config)) return false;
+	if (extraUsageHelperInFlight) return true;
+	extraUsageHelperInFlight = runExtraUsageHelper(cwd, config)
+		.then((message) => {
+			piUI?.notify(`Claude extra usage helper: ${message}`, "info");
+			return message;
+		})
+		.catch((error) => {
+			const message = error instanceof Error ? error.message : String(error);
+			piUI?.notify(`Claude extra usage helper failed after ${reason}: ${message}`, "error");
+			throw error;
+		})
+		.finally(() => { extraUsageHelperInFlight = null; });
+	void extraUsageHelperInFlight.catch(() => {});
+	return true;
+}
 
 const BRIDGE_SESSION_CUSTOM_TYPE = "claude-bridge-session";
 
@@ -616,9 +928,6 @@ function mapToolArgs(
 // them without activating the extension. `ctx()`, `pushContext()`, `popContext()`
 // are imported at the top of this file.
 
-// Global (not query state):
-let piUI: ExtensionUIContext | null = null;
-
 function resolveMcpTools(context: Context, excludeToolName?: string): {
 	mcpTools: Tool[];
 	customToolNameToSdk: Map<string, string>;
@@ -921,6 +1230,8 @@ async function consumeQuery(
 	sdkQuery: ReturnType<typeof query>,
 	customToolNameToPi: Map<string, string>,
 	model: Model<any>,
+	cwd: string,
+	bridgeConfig: Config,
 	wasAborted: () => boolean,
 ): Promise<{ capturedSessionId?: string }> {
 	let capturedSessionId: string | undefined;
@@ -945,6 +1256,14 @@ async function consumeQuery(
 					ctx().currentPiStream?.push({ type: "text_start", contentIndex: idx, partial: ctx().turnOutput });
 					ctx().currentPiStream?.push({ type: "text_delta", contentIndex: idx, delta: text, partial: ctx().turnOutput });
 					ctx().currentPiStream?.push({ type: "text_end", contentIndex: idx, content: text, partial: ctx().turnOutput });
+				} else if (message.subtype !== "success" && isExtraUsageRequiredMessage(message)) {
+					const errors = Array.isArray((message as any).errors) ? (message as any).errors.join("\n") : message.subtype;
+					const openedExtraUsage = launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "result error");
+					ctx().turnOutput.stopReason = "error";
+					ctx().turnOutput.errorMessage = `${errors}${openedExtraUsage ? "\n\nOpened Claude Code /extra-usage helper. Complete billing/admin flow in the browser, then retry the prompt." : "\n\nRun /claude-bridge:extra, or enable Allow extra usage helper in settings."}`;
+					ctx().currentPiStream?.push({ type: "error", reason: "error", error: ctx().turnOutput });
+					ctx().currentPiStream?.end();
+					ctx().currentPiStream = null;
 				}
 				break;
 			case "system":
@@ -959,7 +1278,9 @@ async function consumeQuery(
 				debug("consumeQuery: rate_limit_event", JSON.stringify(info).slice(0, 300));
 				if (info?.status === "rejected") {
 					const resetsAt = info.resetsAt ? new Date(info.resetsAt).toLocaleTimeString() : "unknown";
-					piUI?.notify(`Claude rate limited (${info.rateLimitType ?? "unknown"}) — resets at ${resetsAt}`, "warning");
+					const reason = `${info.rateLimitType ?? "unknown"} rate limit`;
+					const launchedExtraUsage = isExtraUsageRequiredMessage(info) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, reason);
+					piUI?.notify(`Claude rate limited (${reason}) — resets at ${resetsAt}${launchedExtraUsage ? "; opened /extra-usage helper" : ""}`, "warning");
 				} else if (info?.status === "allowed_warning") {
 					piUI?.notify(`Claude rate limit warning: ${Math.round(info.utilization ?? 0)}% used (${info.rateLimitType ?? ""})`, "warning");
 				}
@@ -1072,7 +1393,6 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 	const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context);
 	const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
-	const { sessionId: resumeSessionId } = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
 	const promptBlocks = extractUserPromptBlocks(context.messages);
 	let promptText = extractUserPrompt(context.messages) ?? "";
 
@@ -1114,6 +1434,8 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		: providerSettings.settingSources ?? ["user", "project"];
 	const strictMcpConfigEnabled = !appendSystemPrompt && providerSettings.strictMcpConfig !== false;
 	const claudeExecutable = resolveClaudeExecutable(providerSettings.pathToClaudeCodeExecutable);
+	const claudeExecutablePreflight = claudeExecutable ? preflightClaudeExecutable(claudeExecutable, cwd) : undefined;
+	const { sessionId: resumeSessionId } = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
 
 	// 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).
@@ -1156,6 +1478,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		...(mcpServers ? { mcpServers } : {}),
 		...(resumeSessionId ? { resume: resumeSessionId } : {}),
 		...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
+		spawnClaudeCodeProcess: spawnClaudeCodeWithDiagnostics,
 		...makeCliDebugOptions("provider"),
 	};
 
@@ -1163,6 +1486,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		`model=${model.id} msgs=${context.messages.length} tools=${mcpTools.length}`,
 		`resume=${resumeSessionId?.slice(0, 8) ?? "none"} effort=${effort ?? "default"}`,
 		`appendSys=${appendSystemPrompt} promptCtx=${promptContextAppend.labels.join(",") || "none"} strictMcp=${strictMcpConfigEnabled}`,
+		`claudeExec=${claudeExecutablePreflight ? `${claudeExecutablePreflight.fileType}:${claudeExecutablePreflight.path}` : "sdk-default"}`,
 		`prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`);
 
 	// 3. Start SDK query and claim it for this context
@@ -1194,7 +1518,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	}
 
 	// Background consumer — runs until query ends
-	consumeQuery(sdkQuery, customToolNameToPi, model, () => wasAborted)
+	consumeQuery(sdkQuery, customToolNameToPi, model, cwd, bridgeConfig, () => wasAborted)
 		.then(async ({ capturedSessionId }) => {
 			debug(`provider: consumeQuery completed, stopReason=${ctx().turnOutput?.stopReason}, error=${ctx().turnOutput?.errorMessage}, aborted=${wasAborted}`);
 
@@ -1243,7 +1567,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 					debug(`provider: continuation query, model=${model.id}, resume=${resumeId.slice(0, 8)}, prompt=${steerPrompt.slice(0, 60)}`);
 
 					try {
-						const { capturedSessionId: contSid } = await consumeQuery(contQuery, customToolNameToPi, model, () => wasAborted);
+						const { capturedSessionId: contSid } = await consumeQuery(contQuery, customToolNameToPi, model, cwd, bridgeConfig, () => wasAborted);
 						const sid = contSid ?? sharedSession?.sessionId;
 						if (sid) {
 							sharedSession = { sessionId: sid, cursor: sharedSession?.cursor ?? 0, cwd };
@@ -1264,6 +1588,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		})
 		.catch((error) => {
 			debug(`provider: query error, model=${model.id}, aborted=${Boolean(options?.signal?.aborted)}, error=`, error);
+			const openedExtraUsage = isExtraUsageRequiredMessage(error) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "query error");
 			if ((wasAborted || options?.signal?.aborted) && sharedSession) {
 				sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
 			} else {
@@ -1272,7 +1597,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			ctx().deferredUserMessages = [];
 			if (ctx().turnOutput) {
 				ctx().turnOutput.stopReason = options?.signal?.aborted ? "aborted" : "error";
-				ctx().turnOutput.errorMessage = error instanceof Error ? error.message : String(error);
+				ctx().turnOutput.errorMessage = `${error instanceof Error ? error.message : String(error)}${openedExtraUsage ? "\n\nOpened Claude Code /extra-usage helper. Complete billing/admin flow in the browser, then retry the prompt." : ""}`;
 			}
 			ctx().currentPiStream?.push({ type: "error", reason: (ctx().turnOutput?.stopReason ?? "error") as "aborted" | "error", error: ctx().turnOutput! });
 			ctx().currentPiStream?.end();
@@ -1298,6 +1623,70 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	return stream;
 }
 
+function commandCwd(ctx: unknown): string {
+	const value = (ctx as { cwd?: unknown })?.cwd;
+	return typeof value === "string" && value.length > 0 ? value : process.cwd();
+}
+
+async function tryOpenExtensionManagerSettings(ctx: { ui: ExtensionUIContext }): Promise<boolean> {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const openQuickSettings = host[Symbol.for("vstack.pi.extension-manager.open-quick-settings")];
+	if (typeof openQuickSettings !== "function") return false;
+	try {
+		await (openQuickSettings as (ctx: unknown, hint?: string) => Promise<void>)(ctx, "@vanillagreen/pi-claude-bridge");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function showBridgeStatus(ctx: { ui: ExtensionUIContext; cwd?: string }): void {
+	const config = loadConfig(commandCwd(ctx));
+	ctx.ui.notify([
+		`Claude bridge: ${config.enabled === false ? "disabled" : "enabled"}`,
+		`Extra usage auto-helper: ${extraUsageAllowed(config) ? "on" : "off"} (settings)`,
+		`Use /claude-bridge:extra to run Claude Code /extra-usage now.`,
+	].join("\n"), "info");
+}
+
+function registerBridgeCommands(pi: ExtensionAPI): void {
+	const guard = pi as unknown as Record<PropertyKey, unknown>;
+	if (guard[COMMANDS_REGISTERED_KEY]) return;
+	guard[COMMANDS_REGISTERED_KEY] = true;
+
+	const runExtraUsage = async (ctx: { ui: ExtensionUIContext; cwd?: string }) => {
+		const cwd = commandCwd(ctx);
+		if (extraUsageHelperInFlight) {
+			ctx.ui.notify("Claude extra usage helper already running.", "info");
+			await extraUsageHelperInFlight.catch(() => undefined);
+			return;
+		}
+		try {
+			ctx.ui.notify("Claude extra usage helper starting…", "info");
+			extraUsageHelperInFlight = runExtraUsageHelper(cwd)
+				.finally(() => { extraUsageHelperInFlight = null; });
+			const message = await extraUsageHelperInFlight;
+			ctx.ui.notify(`Claude extra usage helper: ${message}`, "info");
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Claude extra usage helper failed: ${message}`, "error");
+		}
+	};
+
+	pi.registerCommand("claude-bridge", {
+		description: "Open Claude bridge settings/status",
+		handler: async (args: string, ctx) => {
+			if (args.trim()) ctx.ui.notify("Unknown /claude-bridge argument. Use /claude-bridge:extra to run Claude Code /extra-usage.", "warning");
+			if (await tryOpenExtensionManagerSettings(ctx)) return;
+			showBridgeStatus(ctx);
+		},
+	});
+	pi.registerCommand("claude-bridge:extra", {
+		description: "Run Claude Code /extra-usage through claude-bridge",
+		handler: async (_args: string, ctx) => runExtraUsage(ctx),
+	});
+}
+
 // --- Extension registration ---
 
 export default function (pi: ExtensionAPI) {
@@ -1307,6 +1696,7 @@ export default function (pi: ExtensionAPI) {
 
 	const config = loadConfig(process.cwd());
 	debug("loadConfig:", JSON.stringify(config));
+	registerBridgeCommands(pi);
 	if (config.enabled === false) {
 		debug("provider: disabled by configuration");
 		return;