@vanillagreen/pi-claude-bridge 1.1.4 → 1.3.0

package/src/index.ts

@@ -6,7 +6,7 @@ import type { Base64ImageSource, ContentBlockParam, MessageParam } from "@anthro
 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, readFileSync, realpathSync, statSync } from "fs";
+import { accessSync, appendFileSync, chmodSync, 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";
@@ -16,7 +16,8 @@ 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 { findUnpairedToolUses, summarizeMissingToolNames, type MissingToolResult } from "./tool-pairing-audit.js";
+import { loadConfig, normalizeEffortLevel, type Config } from "./config.js";
 import { extractAgentsAppend } from "./agents-md.js";
 import { buildPromptContextAppend } from "./prompt-context.js";
 import { jsonSchemaToZodShape } from "./typebox-to-zod.js";
@@ -33,13 +34,17 @@ const newAssistantMessageEventStream: () => AssistantMessageEventStream =
 
 const DEBUG = process.env.CLAUDE_BRIDGE_DEBUG === "1";
 const DEBUG_LOG_PATH = process.env.CLAUDE_BRIDGE_DEBUG_PATH || join(homedir(), ".pi", "agent", "claude-bridge.log");
-const DIAG_LOG_PATH = join(homedir(), ".pi", "agent", "claude-bridge-diag.log");
+const DEFAULT_DIAG_LOG_PATH = join(homedir(), ".pi", "agent", "claude-bridge-diag.log");
+
+function diagLogPath(): string {
+	return process.env.CLAUDE_BRIDGE_DIAG_PATH || DEFAULT_DIAG_LOG_PATH;
+}
 
 // Ensure log directories exist when debug is enabled
 if (DEBUG) {
 	try {
 		mkdirSync(dirname(DEBUG_LOG_PATH), { recursive: true });
-		mkdirSync(dirname(DIAG_LOG_PATH), { recursive: true });
+		mkdirSync(dirname(diagLogPath()), { recursive: true, mode: 0o700 });
 	} catch {
 		// If directory creation fails, debug functions will throw on first use
 	}
@@ -57,7 +62,7 @@ function debug(...args: unknown[]) {
 		return JSON.stringify(a);
 	};
 	const msg = args.map(fmt).join(" ");
-	appendFileSync(DEBUG_LOG_PATH, `[${ts}] [${moduleInstanceId}] ${msg}\n`);
+	try { appendFileSync(DEBUG_LOG_PATH, `[${ts}] [${moduleInstanceId}] ${msg}\n`); } catch { /* debug is best effort */ }
 }
 
 function executableFromPath(name: string): string | undefined {
@@ -342,10 +347,109 @@ function makeCliDebugOptions(tag: string): { debug?: boolean; debugFile?: string
 
 /** Unconditional diagnostic dump — for "should never happen" paths */
 function diagDump(label: string, data: Record<string, unknown>) {
-	const ts = new Date().toISOString();
-	const entry = { ts, moduleInstanceId, label, ...data };
-	appendFileSync(DIAG_LOG_PATH, JSON.stringify(entry) + "\n");
-	debug(`DIAG: ${label} (see ${DIAG_LOG_PATH})`);
+	try {
+		const ts = new Date().toISOString();
+		const entry = { ts, moduleInstanceId, label, ...data };
+		const path = diagLogPath();
+		try { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); } catch { /* best effort */ }
+		appendFileSync(path, JSON.stringify(entry) + "\n", { mode: 0o600 });
+		try { chmodSync(path, 0o600); } catch { /* best effort */ }
+		debug(`DIAG: ${label} (see ${path})`);
+	} catch (error) {
+		debug(`DIAG FAILED: ${label}`, error);
+	}
+}
+
+function safeNotify(message: string, level: "info" | "warning" | "error" = "warning"): void {
+	try { piUI?.notify(message, level); }
+	catch (error) { debug("notify failed:", error); }
+}
+
+function argKeys(args: Record<string, unknown> | undefined): string[] {
+	return Object.keys(args ?? {}).sort();
+}
+
+function safeToolCallSummary(calls: Array<{ id: string; toolName: string; arguments?: Record<string, unknown> }>): Array<{ id: string; toolName: string; argKeys: string[] }> {
+	return calls.map((call) => ({ id: call.id, toolName: call.toolName, argKeys: argKeys(call.arguments) }));
+}
+
+function compactToolNameSummary(names: Array<{ name: string; count: number }>, limit = 12): string[] {
+	const shown = names.slice(0, limit).map(({ name, count }) => count > 1 ? `${name}×${count}` : name);
+	if (names.length > limit) shown.push(`+${names.length - limit} more`);
+	return shown;
+}
+
+function reportSyntheticToolResultRepair(missing: MissingToolResult[], context: Record<string, unknown>): void {
+	try {
+		if (missing.length === 0) return;
+		const toolNames = summarizeMissingToolNames(missing);
+		const toolNameSummary = compactToolNameSummary(toolNames);
+		const sampledToolCallIds = missing.slice(0, 50).map((item) => item.id);
+		diagDump("repair_tool_pairing_synthetic_results", {
+			count: missing.length,
+			toolNames,
+			sampledToolCallIds,
+			missing: missing.slice(0, 50),
+			...context,
+		});
+		safeNotify(
+			`Claude bridge: ${missing.length} missing tool result(s) repaired with "[no tool result recorded]"` +
+			`${toolNameSummary.length ? ` for ${toolNameSummary.join(", ")}` : ""}. ` +
+			`Real tool output was lost before Claude session import; see ${diagLogPath()}.`,
+			"error",
+		);
+	} catch (error) {
+		debug("reportSyntheticToolResultRepair failed:", error);
+	}
+}
+
+export function reportToolResultMismatch(queryCtx: QueryContext, reason: string, cwd: string | undefined, opts: { forceRotate?: boolean } = {}): boolean {
+	try {
+		if (queryCtx.reportedToolResultMismatch) return false;
+		const progress = queryCtx.toolResultProgress();
+		const hasMismatch = progress.expectedCount > 0
+			? progress.unresolvedIds.length > 0 || progress.waitingCount > 0 || progress.queuedCount > 0 || progress.unmatchedResultCount > 0
+			: progress.waitingCount > 0 || progress.queuedCount > 0 || progress.unmatchedResultCount > 0;
+		if (!hasMismatch) return false;
+		queryCtx.reportedToolResultMismatch = true;
+		if (sharedSession) {
+			sharedSession = { ...sharedSession, needsRebuild: true, ...(opts.forceRotate ? { forceRotate: true } : {}) };
+		}
+		const toolNameSummary = compactToolNameSummary(progress.toolNames);
+		diagDump("tool_result_delivery_mismatch", {
+			reason,
+			cwd,
+			progress,
+			activeQueryExists: queryCtx.activeQuery !== null,
+			sharedSession: sharedSession ? {
+				sessionId: sharedSession.sessionId.slice(0, 8),
+				cursor: sharedSession.cursor,
+				needsRebuild: sharedSession.needsRebuild === true,
+				forceRotate: sharedSession.forceRotate === true,
+			} : null,
+		});
+		safeNotify(
+			`Claude bridge: tool result delivery interrupted during ${reason}; ` +
+			`delivered ${progress.deliveredCount}/${progress.expectedCount}, resolved ${progress.resolvedCount}/${progress.expectedCount}, ` +
+			`waiting=${progress.waitingCount}, queued=${progress.queuedCount}, unmatched=${progress.unmatchedResultCount}` +
+			`${toolNameSummary.length ? `, tools=${toolNameSummary.join(", ")}` : ""}. ` +
+			`Claude session will rebuild before the next turn; see ${diagLogPath()}.`,
+			"error",
+		);
+		return true;
+	} catch (error) {
+		debug("reportToolResultMismatch failed:", error);
+		return false;
+	}
+}
+
+export function __testSetBridgeIntegrityState(state: { ui?: Pick<ExtensionUIContext, "notify"> | null; sharedSession?: SessionState | null }): void {
+	if ("ui" in state) piUI = state.ui as ExtensionUIContext | undefined;
+	if ("sharedSession" in state) sharedSession = state.sharedSession ?? null;
+}
+
+export function __testGetBridgeIntegrityState(): { sharedSession: SessionState | null } {
+	return { sharedSession };
 }
 
 // --- Constants ---
@@ -365,6 +469,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",
@@ -422,6 +527,143 @@ interface SessionState {
 
 let sharedSession: SessionState | null = null;
 let extensionApi: ExtensionAPI | undefined;
+let piUI: ExtensionUIContext | undefined;
+let extraUsageHelperInFlight: Promise<string> | null = null;
+
+const RATE_LIMIT_AUTO_RESUME_EVENT = "vstack:rate-limit";
+const RATE_LIMIT_TOKEN = "\x1b[31m[rate-limit]\x1b[39m";
+
+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);
+}
+
+export function uniqueNonEmptyLines(values: unknown[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const value of values) {
+		const text = typeof value === "string" ? value.trim() : value == null ? "" : String(value).trim();
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		out.push(text);
+	}
+	return out;
+}
+
+export function formatResetTimestamp(value: unknown): string {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
+	if (!Number.isFinite(parsed)) return "unknown";
+	return new Date(parsed).toLocaleString(undefined, {
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		month: "short",
+		second: "2-digit",
+		timeZoneName: "short",
+		year: "numeric",
+	});
+}
+
+export const ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD = 80;
+
+export function normalizeRateLimitUtilization(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+	if (value === 0) return 0;
+	// Claude SDK payloads have appeared as both fractions and percentages.
+	// Exact 1 is unit-ambiguous (1% vs 100%), so do not use it for allowed-warning copy.
+	if (value > 0 && value < 1) return value * 100;
+	if (value > 1 && value <= 100) return value;
+	return undefined;
+}
+
+function rateLimitTypeLabel(value: unknown): string {
+	const text = typeof value === "string" ? value.trim() : "";
+	return text || "unknown";
+}
+
+export function formatAllowedRateLimitWarning(info: { status?: unknown; utilization?: unknown; rateLimitType?: unknown } | null | undefined): string | undefined {
+	if (info?.status !== "allowed_warning") return undefined;
+	const utilization = normalizeRateLimitUtilization(info.utilization);
+	if (utilization === undefined || utilization < ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD) return undefined;
+	return `Claude rate limit warning: nearing ${rateLimitTypeLabel(info.rateLimitType)} limit; check Claude Code /usage for exact utilization.`;
+}
+
+function emitRateLimitEvent(payload: Record<string, unknown>): void {
+	try {
+		extensionApi?.events?.emit?.(RATE_LIMIT_AUTO_RESUME_EVENT, payload);
+	} catch {
+		// Cross-extension broker is best-effort only.
+	}
+}
+
+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";
 
@@ -564,6 +806,7 @@ function convertAndImportMessages(
 	session: ReturnType<typeof createSession>,
 	messages: Context["messages"],
 	customToolNameToSdk?: Map<string, string>,
+	cwd?: string,
 ): void {
 	const { anthropicMessages, sanitizedIds } = convertPiMessages(messages, customToolNameToSdk);
 
@@ -579,7 +822,17 @@ function convertAndImportMessages(
 			[...sanitizedIds.entries()].map(([orig, clean]) => orig === clean ? orig : `${orig}→${clean}`).join(", "));
 	}
 	// Pre-repair for debug logging; importMessages also repairs internally (idempotent).
+	const missingToolResults = findUnpairedToolUses(anthropicMessages);
 	const repaired = repairToolPairing(anthropicMessages);
+	if (missingToolResults.length > 0) {
+		reportSyntheticToolResultRepair(missingToolResults, {
+			cwd,
+			messageCount: messages.length,
+			anthropicMessageCount: anthropicMessages.length,
+			sessionId: session.sessionId,
+			jsonlPath: session.jsonlPath,
+		});
+	}
 	if (repaired.length !== anthropicMessages.length) {
 		debug(`convertAndImportMessages: repairToolPairing ${anthropicMessages.length} → ${repaired.length} msgs`);
 	}
@@ -777,7 +1030,7 @@ function syncSharedSession(
 		...(preserveId ? { sessionId: previousSessionId } : {}),
 		...(modelId ? { model: modelId } : {}),
 	});
-	convertAndImportMessages(session, priorMessages, customToolNameToSdk);
+	convertAndImportMessages(session, priorMessages, customToolNameToSdk, cwd);
 	session.save();
 	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
 	sharedSession = { sessionId: session.sessionId, cursor: priorMessages.length, cwd };
@@ -851,9 +1104,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>;
@@ -880,28 +1130,50 @@ function resolveMcpTools(context: Context, excludeToolName?: string): {
 
 // Creates an MCP server that bridges pi tools to the SDK. Each tool handler
 // blocks on a Promise until pi delivers the tool result via streamSimple.
-// Handlers are assigned toolCallIds from turnToolCallIds (populated when the SDK
-// emits tool_use blocks). Results are matched by ID, not position.
-// Handlers close over the captured `queryCtx`, ensuring they operate on the
-// correct query's state even across pushContext/popContext calls.
+// Handlers claim their tool_call id by matching the actual MCP call
+// (tool name + arguments) against the recorded tool_use blocks, then results
+// are matched by ID. Handlers close over the captured `queryCtx`, ensuring they
+// operate on the correct query's state even across pushContext/popContext calls.
 function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string, ReturnType<typeof createSdkMcpServer>> | undefined {
 	if (!tools.length) return undefined;
 	const mcpTools = tools.map((tool) => ({
 		name: tool.name,
 		description: tool.description,
 		inputSchema: jsonSchemaToZodShape(tool.parameters),
-		handler: async () => {
-			const toolCallId = queryCtx.turnToolCallIds[queryCtx.nextHandlerIdx++];
-			if (!toolCallId) debug(`WARNING: mcp handler ${tool.name} has no toolCallId (idx=${queryCtx.nextHandlerIdx - 1}, available=${queryCtx.turnToolCallIds.length})`);
+		handler: async (args?: Record<string, unknown>) => {
+			const mappedArgs = mapToolArgs(tool.name, args);
+			const claim = queryCtx.claimToolCall(tool.name, mappedArgs);
+			const toolCallId = claim.toolCallId;
+			if (!toolCallId) {
+				debug(`WARNING: mcp handler ${tool.name} has no toolCallId (available=${claim.available})`);
+				diagDump("tool_handler_unmatched", {
+					toolName: tool.name,
+					argKeys: argKeys(mappedArgs),
+					available: claim.available,
+					turnToolCallIds: queryCtx.turnToolCallIds,
+					turnToolCalls: safeToolCallSummary(queryCtx.turnToolCalls),
+				});
+				return { content: [{ type: "text", text: `Claude bridge internal error: no matching tool_call id for ${tool.name}` }], isError: true } satisfies McpResult;
+			}
+			if (claim.match !== "tool-args" || claim.ambiguous) {
+				debug(`mcp handler: ${tool.name} [${toolCallId}] claimed by ${claim.match}${claim.ambiguous ? " (ambiguous)" : ""}`);
+			}
 			if (toolCallId && queryCtx.pendingResults.has(toolCallId)) {
 				const result = queryCtx.pendingResults.get(toolCallId)!;
 				queryCtx.pendingResults.delete(toolCallId);
+				queryCtx.markToolResultResolved(toolCallId);
 				debug(`mcp handler: ${tool.name} [${toolCallId}] → resolved from queue (${queryCtx.pendingResults.size} remaining)`);
 				return result;
 			}
 			debug(`mcp handler: ${tool.name} [${toolCallId}] → waiting`);
 			return new Promise<McpResult>((resolve) => {
-				queryCtx.pendingToolCalls.set(toolCallId, { toolName: tool.name, resolve });
+				queryCtx.pendingToolCalls.set(toolCallId, {
+					toolName: tool.name,
+					resolve: (result) => {
+						queryCtx.markToolResultResolved(toolCallId);
+						resolve(result);
+					},
+				});
 			});
 		},
 	}));
@@ -930,6 +1202,26 @@ const REASONING_TO_EFFORT: Record<string, EffortLevel> = {
 	minimal: "low", low: "low", medium: "medium", high: "high", xhigh: "max",
 };
 
+function normalizeEffortOverrideModelKey(value: string): string {
+	const key = value.trim().toLowerCase();
+	return key.startsWith(`${PROVIDER_ID}/`) ? key.slice(PROVIDER_ID.length + 1) : key;
+}
+
+export function resolveConfiguredEffort(
+	modelId: string,
+	reasoningEffort: EffortLevel | undefined,
+	providerConfig?: Config["provider"],
+): EffortLevel | undefined {
+	const target = normalizeEffortOverrideModelKey(modelId);
+	for (const [key, rawEffort] of Object.entries(providerConfig?.modelEffortOverrides ?? {})) {
+		const normalizedKey = normalizeEffortOverrideModelKey(key);
+		if (normalizedKey !== "*" && normalizedKey !== target) continue;
+		const effort = normalizeEffortLevel(rawEffort) as EffortLevel | undefined;
+		if (effort) return effort;
+	}
+	return (normalizeEffortLevel(providerConfig?.forceEffort) as EffortLevel | undefined) ?? reasoningEffort;
+}
+
 // --- Provider helpers: misc ---
 
 function mapStopReason(reason: string | undefined): "stop" | "length" | "toolUse" {
@@ -980,24 +1272,28 @@ function finalizeCurrentStream(stopReason?: string): void {
 
 /** Maps Anthropic stream events to pi stream events (text, thinking, toolcall).
  *  On message_stop with tool_use: ends currentPiStream so pi can execute the tool. */
-function processStreamEvent(
+export function processStreamEvent(
 	message: SDKMessage,
 	customToolNameToPi: Map<string, string>,
 	model: Model<any>,
 ): void {
 	const c = ctx();
 	if (!c.currentPiStream || !c.turnOutput) return;
-	c.turnSawStreamEvent = true;
 	const event = (message as SDKMessage & { event: any }).event;
+	if (event?.type === "ping") return;
+	if (event?.type === "message_stop" && !c.turnSawToolCall) {
+		debug("processStreamEvent: ignoring bare message_stop with no streamed content/tool call");
+		return;
+	}
 
 	if (event?.type === "message_start") {
-		c.turnToolCallIds = [];
-		c.nextHandlerIdx = 0;
+		c.resetToolTracking();
 		if (event.message?.usage) updateUsage(c.turnOutput, event.message.usage, model);
 		return;
 	}
 
 	if (event?.type === "content_block_start") {
+		c.turnSawStreamEvent = true;
 		ensureTurnStarted();
 		if (event.content_block?.type === "text") {
 			c.turnBlocks.push({ type: "text", text: "", index: event.index });
@@ -1007,10 +1303,11 @@ function processStreamEvent(
 			c.currentPiStream!.push({ type: "thinking_start", contentIndex: c.turnBlocks.length - 1, partial: c.turnOutput });
 		} else if (event.content_block?.type === "tool_use") {
 			c.turnSawToolCall = true;
-			c.turnToolCallIds.push(event.content_block.id);
+			const mappedName = mapToolName(event.content_block.name, customToolNameToPi);
+			c.recordToolCall(event.content_block.id, mappedName, {});
 			c.turnBlocks.push({
 				type: "toolCall", id: event.content_block.id,
-				name: mapToolName(event.content_block.name, customToolNameToPi),
+				name: mappedName,
 				arguments: (event.content_block.input as Record<string, unknown>) ?? {},
 				partialJson: "", index: event.index,
 			});
@@ -1024,7 +1321,11 @@ function processStreamEvent(
 	if (event?.type === "content_block_delta") {
 		const index = c.turnBlocks.findIndex((b: any) => b.index === event.index);
 		const block = c.turnBlocks[index];
-		if (!block) return;
+		if (!block) {
+			debug("processStreamEvent: ignoring unmatched content_block_delta", event.index);
+			return;
+		}
+		c.turnSawStreamEvent = true;
 		if (event.delta?.type === "text_delta" && block.type === "text") {
 			block.text += event.delta.text;
 			c.currentPiStream!.push({ type: "text_delta", contentIndex: index, delta: event.delta.text, partial: c.turnOutput });
@@ -1046,7 +1347,11 @@ function processStreamEvent(
 	if (event?.type === "content_block_stop") {
 		const index = c.turnBlocks.findIndex((b: any) => b.index === event.index);
 		const block = c.turnBlocks[index];
-		if (!block) return;
+		if (!block) {
+			debug("processStreamEvent: ignoring unmatched content_block_stop", event.index);
+			return;
+		}
+		c.turnSawStreamEvent = true;
 		delete block.index;
 		if (block.type === "text") {
 			c.currentPiStream!.push({ type: "text_end", contentIndex: index, content: block.text, partial: c.turnOutput });
@@ -1057,6 +1362,7 @@ function processStreamEvent(
 			block.arguments = mapToolArgs(
 				block.name, parsePartialJson(block.partialJson, block.arguments),
 			);
+			c.updateToolCallArgs(block.id, block.arguments);
 			delete block.partialJson;
 			c.currentPiStream!.push({ type: "toolcall_end", contentIndex: index, toolCall: block, partial: c.turnOutput });
 		}
@@ -1095,13 +1401,73 @@ function processStreamEvent(
 // arrives before any stream_events, this is the primary content path. Must maintain
 // the same stream lifecycle as processStreamEvent — including ending the stream on
 // tool_use to prevent deadlock with the MCP handler.
-function processAssistantMessage(message: SDKMessage, model: Model<any>, customToolNameToPi: Map<string, string>): void {
+function appendMissingToolUsesFromAssistant(
+	assistantMsg: { content?: Array<any>; usage?: Record<string, number | undefined> },
+	model: Model<any>,
+	customToolNameToPi: Map<string, string>,
+): boolean {
+	const c = ctx();
+	if (!assistantMsg?.content) return false;
+	let sawToolUse = false;
+	for (const block of assistantMsg.content) {
+		if (block.type !== "tool_use") continue;
+		sawToolUse = true;
+		const existingIdx = c.turnBlocks.findIndex((b: any) => b.type === "toolCall" && b.id === block.id);
+		const name = mapToolName(block.name, customToolNameToPi);
+		const mappedArgs = mapToolArgs(name, block.input);
+		c.recordToolCall(block.id, name, mappedArgs);
+		if (existingIdx >= 0) {
+			const existing = c.turnBlocks[existingIdx] as any;
+			existing.name = name;
+			existing.arguments = mappedArgs;
+			c.updateToolCallArgs(block.id, mappedArgs);
+			if ("partialJson" in existing) {
+				delete existing.partialJson;
+				delete existing.index;
+				c.currentPiStream?.push({ type: "toolcall_end", contentIndex: existingIdx, toolCall: existing, partial: c.turnOutput });
+			}
+			continue;
+		}
+
+		ensureTurnStarted();
+		c.turnBlocks.push({
+			type: "toolCall", id: block.id,
+			name,
+			arguments: mappedArgs,
+		});
+		const idx = c.turnBlocks.length - 1;
+		const toolBlock = c.turnBlocks[idx];
+		c.currentPiStream?.push({ type: "toolcall_start", contentIndex: idx, partial: c.turnOutput });
+		c.currentPiStream?.push({ type: "toolcall_end", contentIndex: idx, toolCall: toolBlock as any, partial: c.turnOutput });
+	}
+	if (assistantMsg.usage && c.turnOutput) updateUsage(c.turnOutput, assistantMsg.usage, model);
+	return sawToolUse;
+}
+
+export function processAssistantMessage(message: SDKMessage, model: Model<any>, customToolNameToPi: Map<string, string>): void {
 	const c = ctx();
-	if (c.turnSawStreamEvent) return;
 	const assistantMsg = (message as any).message;
 	if (!assistantMsg?.content) return;
-	c.turnToolCallIds = [];
-	c.nextHandlerIdx = 0;
+	if (c.turnSawStreamEvent) {
+		// Claude Agent SDK can yield the completed assistant message before (or
+		// instead of) a stream_event message_stop for a tool-use turn. Treat that
+		// assistant message as a hard turn boundary so Pi executes the tool calls
+		// and the MCP handlers stay blocked until real tool results are delivered.
+		// Without this fallback, Claude Code can continue internally with empty MCP
+		// results and Pi only sees the real outputs one render cycle later.
+		if (appendMissingToolUsesFromAssistant(assistantMsg, model, customToolNameToPi)) {
+			c.turnSawToolCall = true;
+			if (c.currentPiStream && c.turnOutput) {
+				c.turnOutput.stopReason = "toolUse";
+				c.currentPiStream.push({ type: "done", reason: "toolUse", message: c.turnOutput });
+				c.currentPiStream.end();
+				c.currentPiStream = null;
+				debug("processAssistantMessage boundary: ended streamed tool_use turn from assistant message");
+			}
+		}
+		return;
+	}
+	c.resetToolTracking();
 	debug(`processAssistantMessage fallback: ${assistantMsg.content.length} blocks, types=${assistantMsg.content.map((b: any) => b.type).join(",")}`);
 	for (const block of assistantMsg.content) {
 		if (block.type === "text" && block.text) {
@@ -1121,11 +1487,12 @@ function processAssistantMessage(message: SDKMessage, model: Model<any>, customT
 		} else if (block.type === "tool_use") {
 			ensureTurnStarted();
 			c.turnSawToolCall = true;
-			c.turnToolCallIds.push(block.id);
-			const mappedArgs = mapToolArgs(mapToolName(block.name, customToolNameToPi), block.input);
+			const mappedName = mapToolName(block.name, customToolNameToPi);
+			const mappedArgs = mapToolArgs(mappedName, block.input);
+			c.recordToolCall(block.id, mappedName, mappedArgs);
 			c.turnBlocks.push({
 				type: "toolCall", id: block.id,
-				name: mapToolName(block.name, customToolNameToPi),
+				name: mappedName,
 				arguments: mappedArgs,
 			});
 			const idx = c.turnBlocks.length - 1;
@@ -1156,13 +1523,17 @@ 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;
 
 	for await (const message of sdkQuery) {
 		if (wasAborted()) break;
-		if (!ctx().currentPiStream || !ctx().turnOutput) continue;
+		const queryCtx = ctx();
+		if (!queryCtx.turnOutput) continue;
+		if (!queryCtx.currentPiStream && !(message.type === "assistant" && queryCtx.turnSawToolCall)) continue;
 
 		switch (message.type) {
 			case "stream_event":
@@ -1180,6 +1551,16 @@ 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 errorLines = Array.isArray((message as any).errors) ? uniqueNonEmptyLines((message as any).errors) : [];
+					const errors = errorLines.length > 0 ? errorLines.join("\n") : String(message.subtype ?? "Claude Code rate limit");
+					const openedExtraUsage = launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "result error");
+					ctx().handledTerminalError = true;
+					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":
@@ -1193,10 +1574,25 @@ async function consumeQuery(
 				const info = (message as any).rate_limit_info;
 				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 resetsAt = formatResetTimestamp(info.resetsAt);
+					const resetAtMs = typeof info.resetsAt === "string" ? Date.parse(info.resetsAt) : undefined;
+					const reason = `${info.rateLimitType ?? "unknown"} rate limit`;
+					const launchedExtraUsage = isExtraUsageRequiredMessage(info) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, reason);
+					emitRateLimitEvent({
+						model: model.id,
+						provider: PROVIDER_ID,
+						rateLimitType: info.rateLimitType,
+						reason,
+						resetAt: info.resetsAt,
+						...(Number.isFinite(resetAtMs) ? { resetAtMs } : {}),
+						source: "claude-bridge",
+						status: "rejected",
+					});
+					piUI?.notify(`${RATE_LIMIT_TOKEN} Claude ${reason} hit — resets ${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");
+					const warning = formatAllowedRateLimitWarning(info);
+					if (warning) piUI?.notify(warning, "warning");
+					else debug("consumeQuery: suppressed low/ambiguous allowed_warning rate_limit_event", JSON.stringify(info).slice(0, 300));
 				}
 				break;
 			}
@@ -1219,6 +1615,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 	// DEBUG: trace followUp message triggering
 	const lastMsgRole = context.messages[context.messages.length - 1]?.role;
+	const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
 	debug(`provider: streamClaudeAgentSdk called, activeQuery=${!!ctx().activeQuery}, lastMsgRole=${lastMsgRole}, isReentrant=${ctx().activeQuery !== null}`);
 
 	// --- Tool result delivery ---
@@ -1226,30 +1623,48 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// (everything after the last assistant message) and match against waiting MCP
 	// handlers. Results that arrive before their handler get queued in pendingResults.
 	if (ctx().activeQuery) {
-		ctx().currentPiStream = stream;
-		ctx().resetTurnState(model);
+		const queryCtx = ctx();
+		queryCtx.currentPiStream = stream;
+		queryCtx.resetTurnState(model);
 		const allResults = extractAllToolResults(context);
-		debug(`provider: tool results, ${allResults.length} results, ${ctx().pendingToolCalls.size} waiting handlers, ctx.msgs=${context.messages.length}`);
+		debug(`provider: tool results, ${allResults.length} results, ${queryCtx.pendingToolCalls.size} waiting handlers, ctx.msgs=${context.messages.length}`);
+		const unmatchedResultIds: string[] = [];
 		for (const result of allResults) {
 			const id = result.toolCallId;
-			if (id && ctx().pendingToolCalls.has(id)) {
-				const pending = ctx().pendingToolCalls.get(id)!;
-				ctx().pendingToolCalls.delete(id);
+			if (id && !queryCtx.hasRecordedToolCall(id)) {
+				queryCtx.markToolResultUnmatched(id);
+				unmatchedResultIds.push(id);
+				debug(`ERROR: tool result [${id}] has no registered tool_call id; refusing to queue or deliver`);
+				continue;
+			}
+			queryCtx.markToolResultDelivered(id);
+			if (id && queryCtx.pendingToolCalls.has(id)) {
+				const pending = queryCtx.pendingToolCalls.get(id)!;
+				queryCtx.pendingToolCalls.delete(id);
 				debug(`provider: resolving ${pending.toolName} [${id}]${result.isError ? " (error)" : ""}`, JSON.stringify(result.content).slice(0, 200));
 				pending.resolve(result);
 			} else if (id) {
-				ctx().pendingResults.set(id, result);
-				debug(`provider: queued result [${id}] (${ctx().pendingResults.size} pending)`);
+				queryCtx.pendingResults.set(id, result);
+				debug(`provider: queued result [${id}] (${queryCtx.pendingResults.size} pending)`);
 			} else {
 				debug(`WARNING: tool result without toolCallId, cannot match`);
 			}
-			if (ctx().pendingToolCalls.size > 0 && ctx().pendingResults.size > 0) {
-				debug(`BUG: both maps non-empty! handlers=${ctx().pendingToolCalls.size} results=${ctx().pendingResults.size}`);
+			if (queryCtx.pendingToolCalls.size > 0 && queryCtx.pendingResults.size > 0) {
+				debug(`BUG: both maps non-empty! handlers=${queryCtx.pendingToolCalls.size} results=${queryCtx.pendingResults.size}`);
 			}
 		}
-		if (ctx().pendingToolCalls.size > 0) {
-			debug(`WARNING: ${ctx().pendingToolCalls.size} MCP handlers still waiting after delivering ${allResults.length} results`);
-			piUI?.notify(`Claude bridge: ${ctx().pendingToolCalls.size} tool handler(s) still waiting — provider may be stuck`, "warning");
+		if (unmatchedResultIds.length > 0) {
+			const errorResult: McpResult = {
+				content: [{ type: "text", text: `Claude bridge internal error: ${unmatchedResultIds.length} tool result(s) did not match any registered tool_call id. The turn was stopped to avoid delivering tool output to the wrong call. Unmatched ids: ${unmatchedResultIds.slice(0, 8).join(", ")}${unmatchedResultIds.length > 8 ? ", ..." : ""}` }],
+				isError: true,
+			};
+			for (const pending of queryCtx.pendingToolCalls.values()) pending.resolve(errorResult);
+			queryCtx.pendingToolCalls.clear();
+			reportToolResultMismatch(queryCtx, "unmatched tool result", cwd);
+		}
+		if (queryCtx.pendingToolCalls.size > 0) {
+			debug(`WARNING: ${queryCtx.pendingToolCalls.size} MCP handlers still waiting after delivering ${allResults.length} results`);
+			piUI?.notify(`Claude bridge: ${queryCtx.pendingToolCalls.size} tool handler(s) still waiting — provider may be stuck`, "warning");
 		}
 
 		// Detect user messages (steer/followUp) that pi injected into context
@@ -1269,7 +1684,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		}
 
 		if (sharedSession) sharedSession.cursor = context.messages.length;
-		ctx().latestCursor = Math.max(ctx().latestCursor, context.messages.length);
+		queryCtx.latestCursor = Math.max(queryCtx.latestCursor, context.messages.length);
 		return stream;
 	}
 
@@ -1303,10 +1718,10 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	ctx().pendingResults.clear();
 	ctx().deferredUserMessages = [];
 	ctx().resetTurnState(model);
+	ctx().resetToolTracking();
 	ctx().latestCursor = 0;
 
 	const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context);
-	const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
 	const promptBlocks = extractUserPromptBlocks(context.messages);
 	let promptText = extractUserPrompt(context.messages) ?? "";
 
@@ -1354,10 +1769,11 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// 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).
 	// Fall back to our generic table for older pi-ai or unmapped levels.
-	const effort = options?.reasoning
+	const requestedEffort = options?.reasoning
 		? ((model as any).thinkingLevelMap?.[options.reasoning] as EffortLevel | undefined)
 			?? REASONING_TO_EFFORT[options.reasoning]
 		: undefined;
+	const effort = resolveConfiguredEffort(model.id, requestedEffort, providerSettings);
 
 	const extraArgs: Record<string, string | null> = { model: model.id };
 	if (strictMcpConfigEnabled) extraArgs["strict-mcp-config"] = null;
@@ -1382,6 +1798,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		...CLAUDE_BRIDGE_TOOL_ISOLATION,
 		permissionMode: "bypassPermissions",
 		includePartialMessages: true,
+		...(providerSettings.fastMode ? { settings: { fastMode: true } } : {}),
 		systemPrompt: {
 			type: "preset", preset: "claude_code",
 			append: systemPromptAppend ? systemPromptAppend : undefined,
@@ -1399,7 +1816,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	debug("provider: fresh query",
 		`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}`,
+		`appendSys=${appendSystemPrompt} promptCtx=${promptContextAppend.labels.join(",") || "none"} strictMcp=${strictMcpConfigEnabled} fastMode=${providerSettings.fastMode === true}`,
 		`claudeExec=${claudeExecutablePreflight ? `${claudeExecutablePreflight.fileType}:${claudeExecutablePreflight.path}` : "sdk-default"}`,
 		`prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`);
 
@@ -1421,6 +1838,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		wasAborted = true;
 		// Prevent stale deferred messages from being replayed by parent on pop
 		abortCtx.deferredUserMessages = [];
+		reportToolResultMismatch(abortCtx, "abort", cwd, { forceRotate: true });
 		for (const pending of abortCtx.pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Operation aborted" }] }); }
 		abortCtx.pendingToolCalls.clear();
 		abortCtx.pendingResults.clear();
@@ -1432,7 +1850,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}`);
 
@@ -1467,6 +1885,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 					const steerPrompt = ctx().deferredUserMessages.shift()!;
 					debug(`provider: replaying deferred user message: ${steerPrompt.slice(0, 60)}`);
 					ctx().resetTurnState(model);
+					ctx().resetToolTracking();
 
 					const resumeId = sharedSession?.sessionId;
 					if (!resumeId) {
@@ -1481,7 +1900,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 };
@@ -1502,15 +1921,21 @@ 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 suppressDuplicateError = ctx().handledTerminalError;
+			const openedExtraUsage = !suppressDuplicateError && isExtraUsageRequiredMessage(error) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "query error");
 			if ((wasAborted || options?.signal?.aborted) && sharedSession) {
 				sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
 			} else {
 				sharedSession = null;
 			}
 			ctx().deferredUserMessages = [];
+			if (suppressDuplicateError) {
+				debug("provider: suppressing duplicate query error after terminal error was already emitted");
+				return;
+			}
 			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();
@@ -1519,6 +1944,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		.finally(() => {
 			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
 			if (ctx().activeQuery === sdkQuery) {
+				reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: wasAborted || options?.signal?.aborted });
 				// Drain pending handlers for this query
 				for (const pending of ctx().pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Query ended" }] }); }
 				ctx().pendingToolCalls.clear();
@@ -1536,6 +1962,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) {
@@ -1545,6 +2035,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;
@@ -1589,6 +2080,9 @@ export default function (pi: ExtensionAPI) {
 	// triggers CC's autocompact-thrashing guard (issue #8). Force the next
 	// call down the REBUILD path so CC sees the current history.
 	const markRebuild = (event: string) => {
+		if (ctx().activeQuery) {
+			reportToolResultMismatch(ctx(), event, sharedSession?.cwd ?? process.cwd());
+		}
 		if (sharedSession) {
 			debug(`${event}: marking needsRebuild on session ${sharedSession.sessionId.slice(0, 8)}`);
 			sharedSession = { ...sharedSession, needsRebuild: true };