@vanillagreen/pi-claude-bridge 1.6.2 → 1.9.0

package/src/index.ts

@@ -1,27 +1,60 @@
-import { calculateCost, type AssistantMessage, type AssistantMessageEventStream, type Context, type Model, type SimpleStreamOptions, type Tool } from "@earendil-works/pi-ai";
+import { 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, type SpawnOptions, type SpawnedProcess } from "@anthropic-ai/claude-agent-sdk";
+import { createSdkMcpServer, query, type EffortLevel, type SDKMessage, type SDKUserMessage, type SettingSource } 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, 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";
-import { PROVIDER_ID, messageContentToText, convertPiMessages } from "./convert.js";
-import { FABLE_FALLBACK_MODEL_ID, FABLE_MODEL_ID, buildModels, fallbackModelForPrimaryModel } from "./models.js";
+import { PROVIDER_ID, messageContentToText } from "./convert.js";
+import { buildModels, fallbackModelForPrimaryModel, modelDisplayName } from "./models.js";
 import { MCP_SERVER_NAME, MCP_TOOL_PREFIX, extractSkillsBlock } from "./skills.js";
-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 { findUnpairedToolUses, summarizeMissingToolNames, type MissingToolResult } from "./tool-pairing-audit.js";
+import { QueryContext, ctx, drainPendingToolCalls, stackDepth, pushContext, popContext, toolCallDrainCause } from "./query-state.js";
 import { loadConfig, normalizeEffortLevel, recordProjectTrust, type Config } from "./config.js";
+import { decideRegistration, hasClaudeCredentials } from "./auth-presence.js";
 import { extractAgentsAppend } from "./agents-md.js";
 import { buildPromptContextAppend } from "./prompt-context.js";
 import { jsonSchemaToZodShape } from "./typebox-to-zod.js";
+import { readFileSync as nodeReadFileSync } from "node:fs";
 import { resolveGetModels } from "./pi-ai-compat.js";
+import { listAccountConnectors, resolveClaudeOAuth } from "./connector-inventory.js";
+// Re-exported from the extension entry point ON PURPOSE. Consuming apps
+// regenerate their vendored package.json with a CLOSED exports map
+// ({".": "./bundle/index.js"}), which makes Node reject BOTH a subpath import
+// and a deep path into the package (ERR_PACKAGE_PATH_NOT_EXPORTED) — verified.
+// So the ./connector-inventory entry point alone does not reach them. Naming
+// these here puts them in bundle/index.js's own export list, which is the one
+// path their existing manifest already allows, and incidentally keeps esbuild
+// from tree-shaking helpers index.ts never calls itself.
+export {
+	connectorServerNamespace,
+	connectorsListUrl,
+	credentialCandidatePaths,
+	listAccountConnectors,
+	resolveClaudeOAuth,
+	type ClaudeOAuthCredentials,
+	type ConnectorEntry,
+	type ConnectorInventory,
+} from "./connector-inventory.js";
+import { debug, diagDump, makeCliDebugOptions, moduleInstanceId } from "./debug.js";
+import { preflightClaudeExecutable, resolveClaudeExecutable, spawnClaudeCodeWithDiagnostics } from "./claude-executable.js";
+import { argKeys, extensionApi, piUI, reportToolResultMismatch, safeNotify, safeToolCallSummary, setExtensionApi, setPiUI, setSharedSession, sharedSession } from "./bridge-state.js";
+import { connectorQueryOptions, connectorWriteModeFor, connectorsEnabledFor } from "./connectors.js";
+import { restoreSharedSessionFromPi, schedulePersistSharedSession, syncSharedSession } from "./session-persistence.js";
+import { STREAM_IDLE_BACKOFF_HINT_MS, activeStreamIdleWatchdogs, buildStreamIdleTimeoutErrorMessage, createStreamIdleWatchdog, formatDurationShort, streamIdleTimeoutMsFromEnv } from "./stream-idle-watchdog.js";
+import { RATE_LIMIT_AUTO_RESUME_EVENT, RATE_LIMIT_TOKEN, formatAllowedRateLimitWarning, formatResetTimestamp, isExtraUsageRequiredMessage, uniqueNonEmptyLines } from "./rate-limit.js";
+import { mapToolArgs } from "./tool-mapping.js";
+import { ensureTurnStarted, finalizeCurrentStream, parsePartialJson, processAssistantMessage, processStreamEvent, updateTurnOutputModel } from "./assistant-stream.js";
+
+// Re-exports: the module decomposition must not change the bundle entry's
+// public surface — unit tests and downstream consumers import these from
+// bundle/index.js.
+export { classifyClaudeExecutableBytes, preflightClaudeExecutable, resolveClaudeExecutable, spawnClaudeCodeWithDiagnostics, wrapClaudeSpawnErrorForSdk, type ClaudeExecutableFileType, type ClaudeExecutablePreflightResult } from "./claude-executable.js";
+export { __testGetBridgeIntegrityState, __testSetBridgeIntegrityState, reportToolResultMismatch } from "./bridge-state.js";
+export { CLAUDE_AI_CONNECTOR_TOOL_PATTERNS, CLAUDE_BRIDGE_TOOL_ISOLATION, CONNECTOR_DISCOVERY_TOOLS, CONNECTOR_WRITE_TOOLS, DISALLOWED_BUILTIN_TOOLS, connectorQueryOptions, connectorWriteDenyHook, connectorWriteModeFor, connectorWriteModeFromEnv, connectorsEnabledFor, connectorsEnabledFromEnv, isConnectorWriteTool, toolIsolationForQuery } from "./connectors.js";
+export { restoreSharedSessionFromPi, shouldRestorePersistedBridgeEntry } from "./session-persistence.js";
+export { DEFAULT_STREAM_IDLE_TIMEOUT_MS, STREAM_IDLE_BACKOFF_HINT_MS, STREAM_IDLE_TIMEOUT_ENV, buildStreamIdleTimeoutErrorMessage, createStreamIdleWatchdog, streamIdleTimeoutMsFromEnv, type StreamIdleTimeoutInfo, type StreamIdleWatchdog, type StreamIdleWatchdogState } from "./stream-idle-watchdog.js";
+export { ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD, formatAllowedRateLimitWarning, formatResetTimestamp, isExtraUsageRequiredMessage, normalizeRateLimitUtilization, uniqueNonEmptyLines } from "./rate-limit.js";
+export { mapToolName } from "./tool-mapping.js";
+export { processAssistantMessage, processStreamEvent } from "./assistant-stream.js";
 
 // Compat (#2): use factory if available (pi-ai ≥0.66), else fall back to constructor (gsd-pi etc.)
 const _piAi = piAi as any;
@@ -31,702 +64,41 @@ const newAssistantMessageEventStream: () => AssistantMessageEventStream =
 		? _piAi.createAssistantMessageEventStream
 		: () => new _piAi.AssistantMessageEventStream();
 
-// --- Debug logging ---
-// CLAUDE_BRIDGE_DEBUG=1 enables debug logging to ~/.pi/agent/claude-bridge.log
-
-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 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(diagLogPath()), { recursive: true, mode: 0o700 });
-	} catch {
-		// If directory creation fails, debug functions will throw on first use
-	}
-}
-
-// Unique per module evaluation — confirms whether subagents share module state
-const moduleInstanceId = Math.random().toString(36).slice(2, 8);
-
-function debug(...args: unknown[]) {
-	if (!DEBUG) return;
-	const ts = new Date().toISOString();
-	const fmt = (a: unknown): string => {
-		if (typeof a === "string") return a;
-		if (a instanceof Error) return `${a.name}: ${a.message}${a.stack ? "\n" + a.stack : ""}`;
-		return JSON.stringify(a);
-	};
-	const msg = args.map(fmt).join(" ");
-	try { appendFileSync(DEBUG_LOG_PATH, `[${ts}] [${moduleInstanceId}] ${msg}\n`); } catch { /* debug is best effort */ }
-}
-
-function executableFromPath(name: string): string | undefined {
-	const paths = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
-	for (const dir of paths) {
-		const candidate = join(dir, name);
-		try {
-			accessSync(candidate, fsConstants.X_OK);
-			return candidate;
-		} catch {
-			// keep searching
-		}
-	}
-	return undefined;
-}
-
-function resolveClaudeExecutable(configured?: string): string | undefined {
-	const trimmed = configured?.trim();
-	if (trimmed) return trimmed;
-	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
-// Options — see @anthropic-ai/claude-agent-sdk sdk.d.ts:1245 (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;
-function makeCliDebugOptions(tag: string): { debug?: boolean; debugFile?: string; stderr?: (data: string) => void } {
-	if (!DEBUG) return {};
-	const seq = nextCliDebugSeq++;
-	const ts = new Date().toISOString().replace(/[:.]/g, "-");
-	const logDir = join(dirname(DEBUG_LOG_PATH), "cc-cli-logs");
-	try { mkdirSync(logDir, { recursive: true }); } catch { /* ignore */ }
-	const debugFile = join(logDir, `${ts}-${tag}-${seq}.log`);
-	debug(`cli-debug: ${tag} #${seq} → ${debugFile}`);
-	return {
-		debug: true,
-		debugFile,
-		stderr: (data: string) => {
-			for (const line of data.split(/\r?\n/)) {
-				if (line) debug(`[cli-stderr ${tag}#${seq}] ${line}`);
-			}
-		},
-	};
-}
-
-/** Unconditional diagnostic dump — for "should never happen" paths */
-function diagDump(label: string, data: Record<string, unknown>) {
-	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 ---
 
-// Global key to prevent re-registration of the provider across module reloads.
+// Two process-global tokens govern provider registration across module reloads.
+// Extensions like pi-subagents spawn a subagent that loads THIS module again as
+// a fresh (non-primary) instance. Two failure modes must be prevented:
+//   (1) a subagent's registerProvider() overwriting the parent's `streamSimple`
+//       in the shared ModelRegistry — the parent would then deliver tool results
+//       through the subagent's empty-state streamSimple and break tool pairing;
+//   (2) a subagent STEALING registration ownership: if the parent loaded
+//       uncredentialed and the user logged in mid-session, a later subagent load
+//       would see credentialed + no-owner and claim ownership + register ITS
+//       streamSimple, split-braining the shared session/ctx.
 //
-// Extensions like pi-subagents spawn a subagent and it loads this module
-// again. Without this guard, the subagent's call to registerProvider() would
-// overwrite the parent's `streamSimple` function reference in the shared
-// ModelRegistry. When the parent later delivers a tool result, it would call
-// the subagent's `streamSimple` (which has empty state) instead of its own.
+// PRIMARY_INSTANCE_KEY — claimed UNCONDITIONALLY (regardless of credentials) by
+// the first-loaded module instance. ONLY the primary instance may ever
+// register, unregister, or claim the stream guard. Non-primary instances
+// (subagents) always no-op. This is the authority token; it closes (2).
 //
-// By storing the active streamSimple in a Symbol.for() global (shared across all
-// module instances), we ensure only the FIRST instance to register takes effect.
-// Subsequent instances wrap the stored function instead of overwriting it.
+// ACTIVE_STREAM_SIMPLE_KEY — holds the registered instance's `streamSimple`.
+// Only the primary claims it, and only while a registration is live. It doubles
+// as the "already registered" flag (guard === our streamSimple) and the routing
+// target for reentrant subagent calls; it closes (1).
 //
-// On session_shutdown (including /reload), clearSession() resets this so a fresh
-// registration can occur for the next session.
+// Both are released on session_shutdown (incl. /reload) by releaseProviderTokens
+// so the next module load starts clean. See applyProviderRegistration for the
+// state machine and auth-presence.ts/decideRegistration for the pure decision.
+const PRIMARY_INSTANCE_KEY = Symbol.for("claude-bridge:primaryInstance");
 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",
-};
-
 // MODELS is buildModels(getModels("anthropic")) — projection kept in models.js.
 const MODELS = buildModels(getModels("anthropic"));
 
-// Disable Claude Code built-ins in the provider path. Pi owns tool execution;
-// Claude reaches Pi tools through the bridged MCP server instead.
-//
-// `allowedTools` is a permission auto-allow list in the Claude Agent SDK, not a
-// visibility allowlist. Use `tools: []` to remove the built-in tool set, and keep
-// this disallow list as a belt-and-suspenders guard for SDK/CLI built-ins that may
-// otherwise leak into the model context (e.g. TodoWrite, CronList, SendMessage).
-export const DISALLOWED_BUILTIN_TOOLS = [
-	"Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash", "Agent", "Task",
-	"NotebookEdit", "EnterWorktree", "ExitWorktree",
-	"CronList", "CronCreate", "CronDelete", "TeamCreate", "TeamDelete",
-	"TaskOutput", "TaskStop", "SendMessage", "Skill",
-	"TodoRead", "TodoWrite",
-	"ListMcpResources", "ReadMcpResource",
-	"WebFetch", "WebSearch",
-	"AskUserQuestion", "EnterPlanMode", "ExitPlanMode",
-	"ToolSearch", "ScheduleWakeup",
-];
-
-export const CLAUDE_BRIDGE_TOOL_ISOLATION = {
-	tools: [] as string[],
-	disallowedTools: DISALLOWED_BUILTIN_TOOLS,
-	allowedTools: [`mcp__${MCP_SERVER_NAME}__*`],
-} satisfies Pick<NonNullable<Parameters<typeof query>[0]["options"]>, "tools" | "allowedTools" | "disallowedTools">;
-
-// --- Session persistence ---
-
-interface SessionState {
-	sessionId: string;
-	cursor: number;
-	cwd: string;
-	// Force the next syncSharedSession call down the REBUILD path. Set when
-	// pi has mutated its messages array out from under us (compact, tree
-	// navigation) or after an abort left the JSONL in an indeterminate state.
-	// REBUILD wipes and rewrites the file to match pi's current history.
-	needsRebuild?: boolean;
-	// Set ONLY after an abort. The killed CC subprocess may still be flushing
-	// a late "[Request interrupted by user]" record to the session JSONL.
-	// Reusing the same sessionId/path would race that orphan write into our
-	// fresh file and break CC's parent-uuid chain on the next resume. When
-	// this flag is set, REBUILD takes a fresh UUID and skips deleteSession
-	// so the orphan writes land on a dead inode. Compact/tree do NOT set
-	// this — there's no concurrent CC writer during those events, so
-	// in-place rebuild (preserve UUID, deleteSession + createSession) is safe.
-	forceRotate?: boolean;
-}
-
-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 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 90_000;
-export const STREAM_IDLE_BACKOFF_HINT_MS = 60_000;
-export const STREAM_IDLE_TIMEOUT_ENV = "CLAUDE_BRIDGE_STREAM_IDLE_TIMEOUT";
-
-type TimerHandle = ReturnType<typeof setTimeout>;
-
-export interface StreamIdleWatchdogState {
-	activeQuery: unknown | null;
-	currentPiStream: AssistantMessageEventStream | null;
-	turnOutput: AssistantMessage | null;
-	turnSawStreamEvent: boolean;
-	turnStarted: boolean;
-}
-
-export interface StreamIdleTimeoutInfo {
-	idleMs: number;
-	timeoutMs: number;
-}
-
-export interface StreamIdleWatchdog {
-	dispose: () => void;
-	noteChunk: () => void;
-	refresh: () => void;
-	timedOut: () => boolean;
-}
-
-const activeStreamIdleWatchdogs = new WeakMap<QueryContext, StreamIdleWatchdog>();
-
-function parseDurationLiteralMs(value: string, defaultUnit: "ms" | "s" = "s"): number | undefined {
-	const text = value.trim().toLowerCase();
-	if (!text) return undefined;
-	if (["off", "false", "disabled", "disable"].includes(text)) return 0;
-	const match = text.match(/^(\d+(?:\.\d+)?)\s*(ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?)?$/i);
-	if (!match) return undefined;
-	const amount = Number(match[1]);
-	if (!Number.isFinite(amount) || amount < 0) return undefined;
-	const unit = (match[2] ?? defaultUnit).toLowerCase();
-	const multiplier = ["ms", "msec", "msecs", "millisecond", "milliseconds"].includes(unit)
-		? 1
-		: ["s", "sec", "secs", "second", "seconds"].includes(unit)
-			? 1000
-			: ["m", "min", "mins", "minute", "minutes"].includes(unit)
-				? 60_000
-				: undefined;
-	if (multiplier === undefined) return undefined;
-	const ms = Math.round(amount * multiplier);
-	return Number.isFinite(ms) ? ms : undefined;
-}
-
-export function streamIdleTimeoutMsFromEnv(env: NodeJS.ProcessEnv = process.env): number {
-	const raw = env[STREAM_IDLE_TIMEOUT_ENV]?.trim();
-	if (!raw) return DEFAULT_STREAM_IDLE_TIMEOUT_MS;
-	return parseDurationLiteralMs(raw, "s") ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
-}
-
-function formatDurationShort(ms: number): string {
-	if (ms < 180_000 && ms % 1000 === 0) return `${ms / 1000}s`;
-	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
-	if (ms % 1000 === 0) return `${ms / 1000}s`;
-	return `${ms}ms`;
-}
-
-export function buildStreamIdleTimeoutErrorMessage(timeoutMs: number): string {
-	return `Claude Code stream idle timeout after ${formatDurationShort(timeoutMs)} with no assistant/tool output; treating stalled stream as retryable 529 overloaded/rate limit condition. Retry after ${formatDurationShort(STREAM_IDLE_BACKOFF_HINT_MS)}.`;
-}
-
-export function createStreamIdleWatchdog({
-	clearTimer = (timer: TimerHandle) => clearTimeout(timer),
-	getState,
-	now = () => Date.now(),
-	onTimeout,
-	setTimer = (fn: () => void, delayMs: number) => setTimeout(fn, delayMs),
-	timeoutMs,
-}: {
-	clearTimer?: (timer: TimerHandle) => void;
-	getState: () => StreamIdleWatchdogState;
-	now?: () => number;
-	onTimeout: (info: StreamIdleTimeoutInfo) => void;
-	setTimer?: (fn: () => void, delayMs: number) => TimerHandle;
-	timeoutMs: number;
-}): StreamIdleWatchdog {
-	let disposed = false;
-	let lastChunkAt = now();
-	let timer: TimerHandle | null = null;
-	let didTimeout = false;
-
-	const clear = () => {
-		if (!timer) return;
-		try { clearTimer(timer); } catch { /* best effort */ }
-		timer = null;
-	};
-
-	const shouldMonitor = (state: StreamIdleWatchdogState): boolean => Boolean(
-		timeoutMs > 0
-		&& state.activeQuery
-		&& state.currentPiStream
-		&& state.turnOutput
-		&& !state.turnStarted
-		&& !state.turnSawStreamEvent,
-	);
-
-	const schedule = () => {
-		clear();
-		if (disposed || didTimeout || timeoutMs <= 0) return;
-		const state = getState();
-		if (!shouldMonitor(state)) return;
-		const turnStartedAt = typeof state.turnOutput?.timestamp === "number" ? state.turnOutput.timestamp : 0;
-		const idleStartedAt = Math.max(lastChunkAt, turnStartedAt);
-		const idleMs = Math.max(0, now() - idleStartedAt);
-		if (idleMs >= timeoutMs) {
-			didTimeout = true;
-			onTimeout({ idleMs, timeoutMs });
-			return;
-		}
-		timer = setTimer(schedule, Math.max(1, timeoutMs - idleMs));
-		(timer as { unref?: () => void }).unref?.();
-	};
-
-	return {
-		dispose: () => {
-			disposed = true;
-			clear();
-		},
-		noteChunk: () => {
-			lastChunkAt = now();
-			schedule();
-		},
-		refresh: schedule,
-		timedOut: () => didTimeout,
-	};
-}
-
-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);
@@ -798,180 +170,6 @@ function launchExtraUsageHelperIfAllowed(cwd: string, config: Config, reason: st
 	return true;
 }
 
-const BRIDGE_SESSION_CUSTOM_TYPE = "claude-bridge-session";
-
-interface PersistedBridgeSessionState extends SessionState {
-	fingerprint: string;
-	piSessionId?: string;
-	updatedAt: string;
-}
-
-function fingerprintMessages(messages: Context["messages"]): string {
-	const normalized = messages.map((message) => {
-		if (message.role === "assistant") {
-			return {
-				role: message.role,
-				provider: (message as AssistantMessage).provider,
-				model: (message as AssistantMessage).model,
-				content: (message as AssistantMessage).content,
-			};
-		}
-		return message;
-	});
-	return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
-}
-
-function readBuiltSessionContext(sessionManager: unknown): { messages: Context["messages"] } | undefined {
-	const built = typeof (sessionManager as any)?.buildSessionContext === "function" ? (sessionManager as any).buildSessionContext() : undefined;
-	return Array.isArray(built?.messages) ? built as { messages: Context["messages"] } : undefined;
-}
-
-function latestPersistedBridgeSession(sessionManager: unknown): PersistedBridgeSessionState | undefined {
-	const entries = typeof (sessionManager as any)?.getEntries === "function" ? (sessionManager as any).getEntries() : [];
-	if (!Array.isArray(entries)) return undefined;
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		if (entry?.type !== "custom" || entry.customType !== BRIDGE_SESSION_CUSTOM_TYPE) continue;
-		const data = entry.data as Partial<PersistedBridgeSessionState> | undefined;
-		if (!data || typeof data.sessionId !== "string" || typeof data.cursor !== "number" || typeof data.cwd !== "string" || typeof data.fingerprint !== "string") continue;
-		return data as PersistedBridgeSessionState;
-	}
-	return undefined;
-}
-
-function claudeSessionExists(sessionId: string, cwd: string): boolean {
-	try {
-		const session = openSession({ sessionId, projectPath: cwd, claudeDir: process.env.CLAUDE_CONFIG_DIR });
-		statSync(session.jsonlPath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function canonicalize(p: string | undefined): string | undefined {
-	if (!p) return undefined;
-	try { return realpathSync.native(p); } catch { return pathResolve(p); }
-}
-
-// Decides whether a persisted bridge-session marker is safe to restore.
-//
-// The fork case is the load-bearing one: pi/core's createBranchedSession copies
-// every non-label entry from root→leaf into the new session file. That includes
-// our claude-bridge-session markers from the parent. Restoring from them would
-// --resume parent's Claude jsonl on the fork's first turn, leaking conversation
-// past the fork point.
-//
-// Returns undefined when the entry is safe to use, or a short rejection reason
-// for diagnostic logging. Old entries without piSessionId always reject, which
-// degrades safely to the rebuild path.
-export function shouldRestorePersistedBridgeEntry(
-	persisted: { piSessionId?: string; cwd: string },
-	currentPiSessionId: string | undefined,
-	currentCwd: string | undefined,
-): string | undefined {
-	if (!persisted.piSessionId) return "missing piSessionId";
-	if (currentPiSessionId && persisted.piSessionId !== currentPiSessionId) {
-		return `piSessionId mismatch (persisted=${persisted.piSessionId} current=${currentPiSessionId})`;
-	}
-	if (currentCwd && canonicalize(persisted.cwd) !== canonicalize(currentCwd)) {
-		return `cwd mismatch (persisted=${persisted.cwd} current=${currentCwd})`;
-	}
-	return undefined;
-}
-
-export function restoreSharedSessionFromPi(ctx: { sessionManager?: unknown; cwd?: string }): void {
-	const persisted = latestPersistedBridgeSession(ctx.sessionManager);
-	if (!persisted) return;
-	const currentPiSessionId = typeof (ctx.sessionManager as any)?.getSessionId === "function" ? (ctx.sessionManager as any).getSessionId() : undefined;
-	const currentCwd = typeof (ctx.sessionManager as any)?.getCwd === "function" ? (ctx.sessionManager as any).getCwd() : ctx.cwd;
-	const rejection = shouldRestorePersistedBridgeEntry(persisted, currentPiSessionId, currentCwd);
-	if (rejection) {
-		debug(`restoreSharedSession: ${rejection} — forcing rebuild`);
-		return;
-	}
-	const built = readBuiltSessionContext(ctx.sessionManager);
-	if (!built) return;
-	const cursor = Math.max(0, Math.min(persisted.cursor, built.messages.length));
-	const fingerprint = fingerprintMessages(built.messages.slice(0, cursor));
-	if (fingerprint !== persisted.fingerprint) {
-		debug(`restoreSharedSession: fingerprint mismatch for ${persisted.sessionId.slice(0, 8)}`);
-		return;
-	}
-	if (!claudeSessionExists(persisted.sessionId, persisted.cwd)) {
-		debug(`restoreSharedSession: Claude session missing for ${persisted.sessionId.slice(0, 8)}`);
-		return;
-	}
-	sharedSession = { sessionId: persisted.sessionId, cursor, cwd: persisted.cwd };
-	debug(`restoreSharedSession: restored ${persisted.sessionId.slice(0, 8)}, cursor=${cursor}`);
-}
-
-function schedulePersistSharedSession(ctxLike?: { sessionManager?: unknown }): void {
-	if (!extensionApi || !sharedSession || !ctxLike?.sessionManager) return;
-	const snapshot = { ...sharedSession };
-	const timer = setTimeout(() => {
-		try {
-			const built = readBuiltSessionContext(ctxLike.sessionManager);
-			if (!built) return;
-			const cursor = Math.max(0, Math.min(snapshot.cursor, built.messages.length));
-			const data: PersistedBridgeSessionState = {
-				...snapshot,
-				cursor,
-				fingerprint: fingerprintMessages(built.messages.slice(0, cursor)),
-				piSessionId: typeof (ctxLike.sessionManager as any)?.getSessionId === "function" ? (ctxLike.sessionManager as any).getSessionId() : undefined,
-				updatedAt: new Date().toISOString(),
-			};
-			extensionApi?.appendEntry(BRIDGE_SESSION_CUSTOM_TYPE, data);
-			debug(`persistSharedSession: saved ${data.sessionId.slice(0, 8)}, cursor=${data.cursor}`);
-		} catch (error) {
-			debug("persistSharedSession failed:", error);
-		}
-	}, 0);
-	timer.unref?.();
-}
-
-// Convert pi messages to Anthropic API format for session import.
-// Lossy: non-Anthropic thinking blocks are dropped (no valid signature). User and
-// tool-result image blocks are preserved when possible. If assistant blocks are
-// otherwise incompatible, convertPiMessages emits a text placeholder so the record
-// sequence stays valid before repairToolPairing runs.
-function convertAndImportMessages(
-	session: ReturnType<typeof createSession>,
-	messages: Context["messages"],
-	customToolNameToSdk?: Map<string, string>,
-	cwd?: string,
-): void {
-	const { anthropicMessages, sanitizedIds } = convertPiMessages(messages, customToolNameToSdk);
-
-	debug(`convertAndImportMessages: ${messages.length} pi msgs → ${anthropicMessages.length} anthropic msgs`);
-	debug(`convertAndImportMessages: imported roles:`, anthropicMessages.map((m, i) => {
-		const c = m.content;
-		if (typeof c === "string") return `[${i}]${m.role}:text`;
-		if (Array.isArray(c)) return `[${i}]${m.role}:${(c).map((b) => b.type).join("+")}`;
-		return `[${i}]${m.role}:?`;
-	}).join(" "));
-	if (sanitizedIds.size > 0) {
-		debug(`convertAndImportMessages: sanitized ${sanitizedIds.size} tool IDs:`,
-			[...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`);
-	}
-	if (repaired.length) session.importMessages(repaired);
-}
-
 // Pi doesn't pass tool results directly — it appends them to the context and calls
 // the provider again. Thin wrapper over extract-tool-results.js that adds per-turn
 // debug logging at the extraction boundary.
@@ -1036,198 +234,6 @@ async function* wrapPromptStream(blocks: ContentBlockParam[]): AsyncIterable<SDK
 	};
 }
 
-
-interface SyncResult {
-	sessionId: string | null;
-}
-
-/**
- * Ensure the shared session has all messages up to (but not including) the last user message.
- * Returns session ID to resume from, or null if no resume needed.
- */
-// Read the session file we just wrote and sanity-check it. Warns instead of
-// throwing — CC may be more tolerant than our checks, so a false positive
-// shouldn't block the user. Pure logic is in session-verify.js; this wrapper
-// fans each warning out to debug log + piUI notify + diagDump.
-function verifyWrittenSession(
-	jsonlPath: string,
-	expectedSessionId: string,
-	expectedRecordCount: number,
-	cwd: string,
-): void {
-	const warnings = _verifyWrittenSession(jsonlPath, expectedSessionId, expectedRecordCount);
-	for (const msg of warnings) {
-		debug(`WARNING session verify: ${msg}`);
-		piUI?.notify(
-			`Session file issue: ${msg}\n` +
-			`cwd=${cwd} realpath=${safeRealpath(cwd)} CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR ?? "(unset)"}\n` +
-			`Please copy and paste this message into a new issue at https://github.com/elidickinson/pi-claude-bridge/issues/new` +
-			(DEBUG ? ` and attach ${DEBUG_LOG_PATH}` : ` (rerun with CLAUDE_BRIDGE_DEBUG=1 to capture a debug log)`),
-			"warning",
-		);
-		diagDump("session_verify_fail", { msg, jsonlPath, cwd, realpath: safeRealpath(cwd), claudeConfigDir: process.env.CLAUDE_CONFIG_DIR ?? null });
-	}
-}
-
-function safeRealpath(p: string): string {
-	try { return realpathSync(p); } catch (e) { return `<failed: ${(e as Error).message}>`; }
-}
-
-// Diagnostic snapshot of where a session file was just written. Catches the
-// class of bugs where pi writes to ~/.claude/projects/<X> but CC SDK reads
-// from ~/.claude/projects/<Y> (symlinks, CLAUDE_CONFIG_DIR, hash mismatch).
-function debugSessionPaths(label: string, cwd: string, jsonlPath: string): void {
-	const realCwd = safeRealpath(cwd);
-	let fileSize: number | null = null;
-	let fileExists = false;
-	try {
-		const st = statSync(jsonlPath);
-		fileExists = true;
-		fileSize = st.size;
-	} catch { /* file may not exist yet */ }
-	debug(`${label}: cwd=${cwd}`);
-	if (realCwd !== cwd) debug(`${label}: realpath(cwd)=${realCwd} (DIFFERS — symlink-resolved path is what CC SDK uses)`);
-	debug(`${label}: jsonlPath=${jsonlPath}`);
-	debug(`${label}: fileExists=${fileExists}${fileSize != null ? ` size=${fileSize}` : ""}`);
-	debug(`${label}: env.CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR ?? "(unset)"} HOME=${process.env.HOME ?? "(unset)"}`);
-}
-
-// Two semantic paths:
-//   REUSE — pi's history is in sync with the existing sharedSession (or drifted
-//     only by the trailing final-assistant message that pi appends after
-//     streamSimple returns, which CC's own persisted session already has).
-//     Returns the existing sessionId. Keeps CC's prompt cache warm.
-//   REBUILD — no session yet, or pi's history has diverged (non-trailing
-//     missed messages, e.g. another provider took a turn). Wipes the existing
-//     session file (if any) and writes a fresh one containing all prior
-//     messages, reusing the same sessionId across rebuilds so UUIDs stay
-//     stable for the lifetime of pi's session.
-//
-// Why a full rebuild rather than patching:
-//   Injecting deltas into an existing session creates a branch that CC's
-//   --resume doesn't follow (documented attempt prior to this). A complete
-//   overwrite at the same path is simpler and correct.
-//
-// Why reuse the sessionId across rebuilds:
-//   CC re-reads the JSONL on every --resume call — no in-process UUID
-//   caching. Validated in tests/exp-session-clear.mjs, including the case
-//   where CC had appended its own tool_use/tool_result records between
-//   rebuilds. Preserving the UUID means stable log correlation across
-//   provider switches and no orphaned session files.
-//
-// Log strings still say "Case 1/2/3/4" so existing diagnostics (int-cache.sh,
-// int-session-resume.mjs) keep grepping the same anchors.
-function syncSharedSession(
-	messages: Context["messages"],
-	cwd: string,
-	customToolNameToSdk?: Map<string, string>,
-	modelId?: string,
-): SyncResult {
-	const priorMessages = messages.slice(0, -1); // everything before the new user prompt
-
-	// REUSE path
-	if (sharedSession && !sharedSession.needsRebuild) {
-		const missed = priorMessages.slice(sharedSession.cursor);
-		const trailingAssistantOnly =
-			missed.length === 1 && (missed[0] as { role?: string }).role === "assistant";
-		if (missed.length === 0 || trailingAssistantOnly) {
-			if (trailingAssistantOnly) {
-				sharedSession = { ...sharedSession, cursor: priorMessages.length, cwd };
-			}
-			debug(`Case 3: ${trailingAssistantOnly ? "advanced cursor past trailing assistant, " : ""}resuming session ${sharedSession.sessionId.slice(0, 8)}, cursor=${sharedSession.cursor}`);
-			debug(`syncResult: path=reuse sessionId=${sharedSession.sessionId} cursor=${sharedSession.cursor}`);
-			return { sessionId: sharedSession.sessionId };
-		}
-	}
-
-	// REBUILD path
-	if (priorMessages.length === 0) {
-		debug(`Case 1: clean start, ${messages.length} total messages`);
-		debug(`syncResult: path=clean-start`);
-		return { sessionId: null };
-	}
-	const previousSessionId = sharedSession?.sessionId;
-	const previousCursor = sharedSession?.cursor ?? 0;
-	// preserveId: rebuild in place (deleteSession + createSession with the
-	// existing UUID), so prompt-cache UUIDs stay stable for log correlation
-	// and for any tools that key off them. Skipped only when there's a
-	// concurrent writer we shouldn't race — see forceRotate docs above.
-	const preserveId = previousSessionId !== undefined && !sharedSession?.forceRotate;
-	if (preserveId) {
-		// Wipe prior jsonl + companion dir (no-op if nothing to wipe).
-		deleteSession(previousSessionId!, cwd, process.env.CLAUDE_CONFIG_DIR);
-	}
-	const session = createSession({
-		projectPath: cwd,
-		claudeDir: process.env.CLAUDE_CONFIG_DIR,
-		...(preserveId ? { sessionId: previousSessionId } : {}),
-		...(modelId ? { model: modelId } : {}),
-	});
-	convertAndImportMessages(session, priorMessages, customToolNameToSdk, cwd);
-	session.save();
-	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
-	sharedSession = { sessionId: session.sessionId, cursor: priorMessages.length, cwd };
-	if (previousSessionId === undefined) {
-		debug(`Case 2: first turn with ${priorMessages.length} prior messages → session ${session.sessionId.slice(0, 8)}, ${session.messages.length} records`);
-	} else if (preserveId) {
-		const missedCount = priorMessages.length - previousCursor;
-		debug(`Case 4: ${missedCount} missed messages, ${priorMessages.length} total → rewrote session ${session.sessionId.slice(0, 8)} (same id), ${session.messages.length} records`);
-	} else {
-		debug(`Case 4 post-abort: ${priorMessages.length} total → new session ${session.sessionId.slice(0, 8)} (was ${previousSessionId.slice(0, 8)}, rotated to avoid race with orphan writer), ${session.messages.length} records`);
-	}
-	debugSessionPaths(`${session.sessionId.slice(0, 8)}`, cwd, session.jsonlPath);
-	debug(`syncResult: path=rebuild sessionId=${session.sessionId} priors=${priorMessages.length} ${previousSessionId === undefined ? "first" : preserveId ? "preserved" : "rotated-post-abort"}`);
-	return { sessionId: session.sessionId };
-}
-
-// --- Provider helpers: tool name mapping ---
-
-export function mapToolName(name: string, customToolNameToPi?: Map<string, string>): string {
-	const normalized = name.toLowerCase();
-	const builtin = SDK_TO_PI_TOOL_NAME[normalized];
-	if (builtin) return builtin;
-	if (customToolNameToPi) {
-		const mapped = customToolNameToPi.get(name) ?? customToolNameToPi.get(normalized);
-		if (mapped) return mapped;
-	}
-	for (const prefix of [
-		MCP_TOOL_PREFIX,
-		`mcp__${MCP_SERVER_NAME.replace(/-/g, "_")}__`,
-		`mcp/${MCP_SERVER_NAME}/`,
-		`mcp/${MCP_SERVER_NAME.replace(/-/g, "_")}/`,
-	]) {
-		if (normalized.startsWith(prefix)) return normalized.slice(prefix.length);
-	}
-	return name;
-}
-
-// Renames for Claude Code SDK param names that differ from pi's native names.
-// Keys not listed here pass through unchanged, so new pi params work automatically.
-const SDK_KEY_RENAMES: Record<string, Record<string, string>> = {
-	read:  { file_path: "path" },
-	write: { file_path: "path" },
-	edit:  { file_path: "path", old_string: "oldText", new_string: "newText", old_text: "oldText", new_text: "newText" },
-};
-
-// Maps SDK tool args to pi tool args via key renaming + pass-through.
-// Pi's own prepareArguments hooks handle any structural transforms (e.g. edit oldText/newText → edits[]).
-function mapToolArgs(
-	toolName: string, args: Record<string, unknown> | undefined,
-): Record<string, unknown> {
-	const input = args ?? {};
-	const renames = SDK_KEY_RENAMES[toolName.toLowerCase()];
-	const result: Record<string, unknown> = {};
-	for (const [key, value] of Object.entries(input)) {
-		const piKey = renames?.[key] ?? key;
-		if (!(piKey in result)) result[piKey] = value; // first alias wins
-	}
-	// Pi bash has no default timeout; add a safety default
-	if (toolName.toLowerCase() === "bash" && result.timeout == null) {
-		result.timeout = 120;
-	}
-	return result;
-}
-
 // --- Provider helpers: tool resolution ---
 
 // --- Provider helpers: tool bridge ---
@@ -1261,6 +267,55 @@ function resolveMcpTools(context: Context, excludeToolName?: string): {
 	return { mcpTools, customToolNameToSdk, customToolNameToPi };
 }
 
+/** Finalizes the current pi turn when the SDK invokes an MCP tool handler
+ *  before emitting `message_stop` or the completed assistant message.
+ *
+ *  Observed with Claude Code under pi 0.80's steer draining (tool result and
+ *  drained steer arrive in one provider call): the NEXT tool turn's tool_use
+ *  streams in, the SDK invokes the MCP handler — and neither terminal event
+ *  ever arrives. The invocation itself proves the assistant turn is committed,
+ *  so end the pi stream here exactly like the `message_stop` path; otherwise
+ *  the handler blocks on a result pi will never deliver (deadlock). No-op when
+ *  the turn already ended (stream null) or the tool call isn't part of the
+ *  currently streamed turn. */
+function finalizeToolUseTurnFromMcpInvocation(
+	queryCtx: QueryContext,
+	toolCallId: string,
+	toolName: string,
+	mappedArgs: Record<string, unknown>,
+): void {
+	if (!queryCtx.currentPiStream || !queryCtx.turnOutput) return;
+	let idx = queryCtx.turnBlocks.findIndex((b: any) => b.type === "toolCall" && b.id === toolCallId);
+	if (idx >= 0) {
+		const block = queryCtx.turnBlocks[idx] as any;
+		if ("partialJson" in block) {
+			// Stream ended before content_block_stop — settle the args from the
+			// partial JSON the same way content_block_stop would have.
+			block.arguments = mapToolArgs(block.name, parsePartialJson(block.partialJson, block.arguments));
+			queryCtx.updateToolCallArgs(block.id, block.arguments);
+			delete block.partialJson;
+			delete block.index;
+			queryCtx.currentPiStream.push({ type: "toolcall_end", contentIndex: idx, toolCall: block, partial: queryCtx.turnOutput });
+		}
+	} else {
+		// The invocation can arrive before the tool_use is streamed at all
+		// (observed after a tool-result+steer provider call reset the turn):
+		// synthesize the toolCall from the claim — the MCP call carries the
+		// authoritative id, name, and arguments.
+		queryCtx.turnBlocks.push({ type: "toolCall", id: toolCallId, name: toolName, arguments: mappedArgs });
+		idx = queryCtx.turnBlocks.length - 1;
+		const block = queryCtx.turnBlocks[idx] as any;
+		queryCtx.currentPiStream.push({ type: "toolcall_start", contentIndex: idx, partial: queryCtx.turnOutput });
+		queryCtx.currentPiStream.push({ type: "toolcall_end", contentIndex: idx, toolCall: block, partial: queryCtx.turnOutput });
+	}
+	queryCtx.turnSawToolCall = true;
+	queryCtx.turnOutput.stopReason = "toolUse";
+	debug(`mcp handler: finalizing tool_use turn from MCP invocation [${toolCallId}] (${toolName}) — SDK invoked the tool before message_stop/assistant message`);
+	queryCtx.currentPiStream.push({ type: "done", reason: "toolUse", message: queryCtx.turnOutput });
+	queryCtx.currentPiStream.end();
+	queryCtx.currentPiStream = null;
+}
+
 // 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 claim their tool_call id by matching the actual MCP call
@@ -1299,6 +354,7 @@ function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string,
 				return result;
 			}
 			debug(`mcp handler: ${tool.name} [${toolCallId}] → waiting`);
+			finalizeToolUseTurnFromMcpInvocation(queryCtx, toolCallId, tool.name, mappedArgs);
 			return new Promise<McpResult>((resolve) => {
 				queryCtx.pendingToolCalls.set(toolCallId, {
 					toolName: tool.name,
@@ -1314,25 +370,11 @@ function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string,
 	return { [MCP_SERVER_NAME]: server };
 }
 
-// --- Usage helpers ---
-
-function updateUsage(output: AssistantMessage, usage: Record<string, number | undefined>, model: Model<any>): void {
-	if (usage.input_tokens != null) output.usage.input = usage.input_tokens;
-	if (usage.output_tokens != null) output.usage.output = usage.output_tokens;
-	if (usage.cache_read_input_tokens != null) output.usage.cacheRead = usage.cache_read_input_tokens;
-	if (usage.cache_creation_input_tokens != null) output.usage.cacheWrite = usage.cache_creation_input_tokens;
-	output.usage.totalTokens = output.usage.input + output.usage.output + output.usage.cacheRead + output.usage.cacheWrite;
-	calculateCost(model, output.usage);
-	const promptTokens = output.usage.input + output.usage.cacheRead + output.usage.cacheWrite;
-	const cachePct = promptTokens > 0 ? Math.round(output.usage.cacheRead / promptTokens * 100) : 0;
-	debug(`usage: in=${output.usage.input} out=${output.usage.output} cacheRead=${output.usage.cacheRead} cacheWrite=${output.usage.cacheWrite} total=${output.usage.totalTokens} cachePct=${cachePct}% model=${model.id}`);
-}
-
 // --- Effort level mapping ---
 // Pi reasoning levels → CC SDK effort levels
 
 const REASONING_TO_EFFORT: Record<string, EffortLevel> = {
-	minimal: "low", low: "low", medium: "medium", high: "high", xhigh: "max",
+	minimal: "low", low: "low", medium: "medium", high: "high", xhigh: "max", max: "max",
 };
 
 function normalizeEffortOverrideModelKey(value: string): string {
@@ -1355,22 +397,6 @@ export function resolveConfiguredEffort(
 	return (normalizeEffortLevel(providerConfig?.forceEffort) as EffortLevel | undefined) ?? reasoningEffort;
 }
 
-// --- Provider helpers: misc ---
-
-function mapStopReason(reason: string | undefined): "stop" | "length" | "toolUse" {
-	switch (reason) {
-		case "tool_use": return "toolUse";
-		case "max_tokens": return "length";
-		case "end_turn": default: return "stop";
-	}
-}
-
-function parsePartialJson(input: string, fallback: Record<string, unknown>): Record<string, unknown> {
-	if (!input) return fallback;
-	try { return JSON.parse(input); } catch { return fallback; }
-}
-
-
 // --- Provider: streaming function ---
 //
 // Push-based streaming with MCP tool bridge:
@@ -1386,279 +412,6 @@ function parsePartialJson(input: string, fallback: Record<string, unknown>): Rec
 // currentPiStream, so any leftover messages hit the `!ctx().currentPiStream` guard
 // in consumeQuery and are skipped before resetTurnState runs.
 
-function ensureTurnStarted(): void {
-	if (!ctx().turnStarted && ctx().currentPiStream && ctx().turnOutput) {
-		ctx().currentPiStream!.push({ type: "start", partial: ctx().turnOutput });
-		ctx().turnStarted = true;
-	}
-}
-
-function finalizeCurrentStream(stopReason?: string): void {
-	if (!ctx().currentPiStream || !ctx().turnOutput) return;
-	debug(`provider: finalizeCurrentStream called, stopReason=${stopReason}, turnOutput=${JSON.stringify({stopReason: ctx().turnOutput!.stopReason, error: ctx().turnOutput!.errorMessage})}`);
-	if (!ctx().turnStarted) ensureTurnStarted();
-	const reason = stopReason === "length" ? "length" : "stop";
-	ctx().currentPiStream!.push({ type: "done", reason, message: ctx().turnOutput });
-	ctx().currentPiStream!.end();
-	ctx().currentPiStream = null;
-}
-
-function updateTurnOutputModel(modelId: unknown): void {
-	const c = ctx();
-	if (typeof modelId !== "string" || !modelId || !c.turnOutput) return;
-	if (c.turnOutput.model === modelId) return;
-	debug(`provider: active Claude model changed ${c.turnOutput.model} -> ${modelId}`);
-	c.turnOutput.model = modelId;
-}
-
-/** 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. */
-export function processStreamEvent(
-	message: SDKMessage,
-	customToolNameToPi: Map<string, string>,
-	model: Model<any>,
-): void {
-	const c = ctx();
-	if (!c.currentPiStream || !c.turnOutput) return;
-	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.resetToolTracking();
-		updateTurnOutputModel(event.message?.model);
-		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 });
-			c.currentPiStream!.push({ type: "text_start", contentIndex: c.turnBlocks.length - 1, partial: c.turnOutput });
-		} else if (event.content_block?.type === "thinking") {
-			c.turnBlocks.push({ type: "thinking", thinking: "", thinkingSignature: "", index: event.index });
-			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;
-			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: mappedName,
-				arguments: (event.content_block.input as Record<string, unknown>) ?? {},
-				partialJson: "", index: event.index,
-			});
-			c.currentPiStream!.push({ type: "toolcall_start", contentIndex: c.turnBlocks.length - 1, partial: c.turnOutput });
-		} else {
-			debug("processStreamEvent: unhandled content_block_start type", event.content_block?.type);
-		}
-		return;
-	}
-
-	if (event?.type === "content_block_delta") {
-		const index = c.turnBlocks.findIndex((b: any) => b.index === event.index);
-		const block = c.turnBlocks[index];
-		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 });
-		} else if (event.delta?.type === "thinking_delta" && block.type === "thinking") {
-			block.thinking += event.delta.thinking;
-			c.currentPiStream!.push({ type: "thinking_delta", contentIndex: index, delta: event.delta.thinking, partial: c.turnOutput });
-		} else if (event.delta?.type === "input_json_delta" && block.type === "toolCall") {
-			block.partialJson += event.delta.partial_json;
-			block.arguments = parsePartialJson(block.partialJson, block.arguments);
-			c.currentPiStream!.push({ type: "toolcall_delta", contentIndex: index, delta: event.delta.partial_json, partial: c.turnOutput });
-		} else if (event.delta?.type === "signature_delta" && block.type === "thinking") {
-			block.thinkingSignature = (block.thinkingSignature ?? "") + event.delta.signature;
-		} else {
-			debug("processStreamEvent: unhandled content_block_delta type", event.delta?.type);
-		}
-		return;
-	}
-
-	if (event?.type === "content_block_stop") {
-		const index = c.turnBlocks.findIndex((b: any) => b.index === event.index);
-		const block = c.turnBlocks[index];
-		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 });
-		} else if (block.type === "thinking") {
-			c.currentPiStream!.push({ type: "thinking_end", contentIndex: index, content: block.thinking, partial: c.turnOutput });
-		} else if (block.type === "toolCall") {
-			c.turnSawToolCall = true;
-			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 });
-		}
-		return;
-	}
-
-	if (event?.type === "message_delta") {
-		c.turnOutput.stopReason = mapStopReason(event.delta?.stop_reason);
-		if (event.usage) updateUsage(c.turnOutput, event.usage, model);
-		return;
-	}
-
-	if (event?.type === "message_stop" && c.turnSawToolCall) {
-		// Tool call complete — end this pi stream. The SDK will still yield an
-		// assistant message for this turn, but currentPiStream=null causes
-		// consumeQuery to skip it. The MCP handler blocks the generator until
-		// pi delivers the tool result via the next streamSimple call.
-		c.turnOutput.stopReason = "toolUse";
-		c.currentPiStream!.push({ type: "done", reason: "toolUse", message: c.turnOutput });
-		c.currentPiStream!.end();
-		c.currentPiStream = null;
-
-		// Cursor is updated by the next streamSimple call (tool result delivery path)
-		// which sets cursor = context.messages.length with the post-tool-result context.
-		return;
-	}
-
-	if (event?.type !== "message_stop" && event?.type !== "ping") {
-		debug("processStreamEvent: unhandled event type", event?.type);
-	}
-}
-
-// The SDK always yields `assistant` messages (completed content blocks) after streaming.
-// When stream_events already delivered the content, this is a no-op. But after
-// resetTurnState (e.g. tool result delivery), if the next turn's assistant message
-// 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 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();
-	const assistantMsg = (message as any).message;
-	if (!assistantMsg?.content) return;
-	updateTurnOutputModel(assistantMsg.model);
-	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) {
-			ensureTurnStarted();
-			c.turnBlocks.push({ type: "text", text: block.text });
-			const idx = c.turnBlocks.length - 1;
-			c.currentPiStream?.push({ type: "text_start", contentIndex: idx, partial: c.turnOutput });
-			c.currentPiStream?.push({ type: "text_delta", contentIndex: idx, delta: block.text, partial: c.turnOutput });
-			c.currentPiStream?.push({ type: "text_end", contentIndex: idx, content: block.text, partial: c.turnOutput });
-		} else if (block.type === "thinking") {
-			ensureTurnStarted();
-			c.turnBlocks.push({ type: "thinking", thinking: block.thinking ?? "", thinkingSignature: block.signature ?? "" });
-			const idx = c.turnBlocks.length - 1;
-			c.currentPiStream?.push({ type: "thinking_start", contentIndex: idx, partial: c.turnOutput });
-			if (block.thinking) c.currentPiStream?.push({ type: "thinking_delta", contentIndex: idx, delta: block.thinking, partial: c.turnOutput });
-			c.currentPiStream?.push({ type: "thinking_end", contentIndex: idx, content: block.thinking ?? "", partial: c.turnOutput });
-		} else if (block.type === "tool_use") {
-			ensureTurnStarted();
-			c.turnSawToolCall = true;
-			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: mappedName,
-				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 });
-		} else if (block.type === "fallback") {
-			updateTurnOutputModel(block.to?.model);
-		} else {
-			debug("processAssistantMessage: unhandled block type", block.type);
-		}
-	}
-	if (assistantMsg.usage && c.turnOutput) updateUsage(c.turnOutput, assistantMsg.usage, model);
-
-	// End the stream on tool_use, same as processStreamEvent's message_stop handler.
-	if (c.turnSawToolCall && c.currentPiStream && c.turnOutput) {
-		c.turnOutput.stopReason = "toolUse";
-		c.currentPiStream.push({ type: "done", reason: "toolUse", message: c.turnOutput });
-		c.currentPiStream.end();
-		c.currentPiStream = null;
-	}
-}
-
 /** Background consumer: iterates the SDK generator, pushing events to currentPiStream.
  *  Runs until the query ends. Per turn, the SDK yields stream_events (deltas), then
  *  an assistant message (completed blocks). On tool_use, the stream is ended by
@@ -1717,8 +470,13 @@ async function consumeQuery(
 					const fallbackModel = (message as any).fallback_model;
 					updateTurnOutputModel(fallbackModel);
 					debug("consumeQuery: model_refusal_fallback", JSON.stringify({ originalModel, fallbackModel }));
-					if (originalModel === FABLE_MODEL_ID && fallbackModel === FABLE_FALLBACK_MODEL_ID) {
-						safeNotify("Claude bridge switched Fable 5 to Opus 4.8 after Claude Code safety fallback.", "info");
+					// Notify only for reroutes we configured, so an unexpected pairing from
+					// Claude Code is still logged above but not announced as one of ours.
+					if (typeof fallbackModel === "string" && typeof originalModel === "string" && fallbackModelForPrimaryModel(originalModel) === fallbackModel) {
+						safeNotify(
+							`Claude bridge switched ${modelDisplayName(originalModel)} to ${modelDisplayName(fallbackModel)} after Claude Code safety fallback.`,
+							"info",
+						);
 					}
 				}
 				break;
@@ -1762,6 +520,92 @@ async function consumeQuery(
 	return { capturedSessionId };
 }
 
+// Claim the primary-instance token for this module instance if unclaimed, and
+// report whether this instance is the primary. First-loaded instance wins,
+// UNCONDITIONALLY (before any credential check), so a later subagent load can
+// never become primary and steal registration ownership.
+function claimPrimaryInstance(): boolean {
+	const g = globalThis as Record<symbol, any>;
+	if (!g[PRIMARY_INSTANCE_KEY]) g[PRIMARY_INSTANCE_KEY] = streamClaudeAgentSdk;
+	return g[PRIMARY_INSTANCE_KEY] === streamClaudeAgentSdk;
+}
+
+// Release both process-global tokens this instance owns. Called on
+// session_shutdown (incl. /reload) so the freshly loaded instance starts clean.
+// NOTE: this does NOT unregister the provider — the ModelRegistry's
+// registeredProviders is a process-lifetime Map that survives module reload, so
+// retraction on logout is handled by applyProviderRegistration's defensive
+// unregister on the next load/session_start, not here.
+function releaseProviderTokens(event: string): void {
+	const g = globalThis as Record<symbol, any>;
+	if (g[ACTIVE_STREAM_SIMPLE_KEY] === streamClaudeAgentSdk) {
+		debug(`${event}: clearing ACTIVE_STREAM_SIMPLE_KEY`);
+		g[ACTIVE_STREAM_SIMPLE_KEY] = undefined;
+	}
+	if (g[PRIMARY_INSTANCE_KEY] === streamClaudeAgentSdk) {
+		debug(`${event}: clearing PRIMARY_INSTANCE_KEY`);
+		g[PRIMARY_INSTANCE_KEY] = undefined;
+	}
+}
+
+// Conditional (un)registration driven by real credential presence + instance
+// primacy. Run at extension load, on every session_start, and at pre-spawn
+// (fail-fast) so a `claude login` / logout is reflected without a /reload.
+//
+// decideRegistration encodes the pure state machine; this wrapper performs the
+// matching token mutations so tokens and registration never diverge:
+//   - register:   claim the stream guard, THEN registerProvider. If register
+//     throws/queue-fails, release the stream guard (but keep primacy) so a
+//     later re-check can retry cleanly (self-healing); errors are swallowed so
+//     a session_start handler can't crash the dispatch.
+//   - unregister: pi.unregisterProvider (idempotent), THEN release the stream
+//     guard if we own it. Defensive even when we never registered — this is the
+//     only retraction path for a stale registration surviving /reload. At LOAD
+//     the SDK's unregister only filters the pending-registration queue and can't
+//     mutate the persistent registry (loader.js), so the effective retraction
+//     lands on the post-load session_start re-check; the load-time call is a
+//     harmless idempotent no-op that also cancels any same-pass queued register.
+// Non-primary instances (subagents) always decide noop and touch nothing.
+function applyProviderRegistration(trigger: string): void {
+	const pi = extensionApi;
+	if (!pi) { debug(`${trigger}: applyProviderRegistration skipped — no extensionApi`); return; }
+	const g = globalThis as Record<symbol, any>;
+	const isPrimary = claimPrimaryInstance();
+	const credentialed = hasClaudeCredentials();
+	const registered = g[ACTIVE_STREAM_SIMPLE_KEY] === streamClaudeAgentSdk;
+	const decision = decideRegistration({ credentialed, isPrimary, registered });
+	debug(`${trigger}: registration decision=${decision} credentialed=${credentialed} isPrimary=${isPrimary} registered=${registered} (module=${moduleInstanceId})`);
+	if (decision === "register") {
+		// Claim ordering: stream guard BEFORE registerProvider so a concurrent
+		// subagent can never observe a registered provider without an owner.
+		g[ACTIVE_STREAM_SIMPLE_KEY] = streamClaudeAgentSdk;
+		try {
+			pi.registerProvider(PROVIDER_ID, {
+				baseUrl: "claude-bridge",
+				apiKey: "not-used",
+				api: "claude-bridge",
+				models: MODELS,
+				// Cast: pi-ai AssistantMessageEventStream diamond dep between pi-coding-agent and pi-agent-core
+				streamSimple: streamClaudeAgentSdk as any,
+			});
+		} catch (err) {
+			// Self-heal: release ONLY the stream guard we just claimed so a later
+			// re-check (primary + credentialed + not-registered → register) retries.
+			// Keep PRIMARY_INSTANCE_KEY: releasing it would reopen the subagent
+			// ownership-steal window, and retry does not need it released.
+			if (g[ACTIVE_STREAM_SIMPLE_KEY] === streamClaudeAgentSdk) g[ACTIVE_STREAM_SIMPLE_KEY] = undefined;
+			debug(`${trigger}: registerProvider threw; released stream guard for retry (kept primary):`, err);
+		}
+	} else if (decision === "unregister") {
+		try {
+			pi.unregisterProvider(PROVIDER_ID);
+		} catch (err) {
+			debug(`${trigger}: unregisterProvider threw (ignored):`, err);
+		}
+		if (g[ACTIVE_STREAM_SIMPLE_KEY] === streamClaudeAgentSdk) g[ACTIVE_STREAM_SIMPLE_KEY] = undefined;
+	}
+}
+
 /** Provider entry point. Pi calls this for each new prompt and each tool result.
  *  Two cases: tool result delivery (active query) or fresh query. */
 function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
@@ -1861,6 +705,34 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 	// --- Fresh query ---
 
+	// Fail-fast credential re-check (only for a fresh query — NEVER for
+	// tool-result delivery of an in-flight query, handled above, where creds were
+	// valid at start and failing mid-turn would break tool pairing). This bounds
+	// the retraction-latency window from "next session boundary" to "first use":
+	// if credentials vanished since the last session_start, (a) trigger the same
+	// re-evaluation applyProviderRegistration does (primary-only; retracts the
+	// stale registration), and (b) fail this request with a clear, actionable
+	// message instead of letting the SDK spawn die with a generic error. The
+	// check is cheap (existsSync + env reads only, no credential contents).
+	if (!hasClaudeCredentials()) {
+		try { applyProviderRegistration("pre-spawn"); } catch { /* best effort */ }
+		const message = "Claude account not connected — connect an account (or run `claude login`) and retry.";
+		debug(`provider: pre-spawn credential check failed; failing fast: ${message}`);
+		const errorOutput: AssistantMessage = {
+			role: "assistant", content: [],
+			api: model.api, provider: model.provider, model: model.id,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+			stopReason: "error", timestamp: Date.now(),
+			errorMessage: message,
+		};
+		queueMicrotask(() => {
+			stream.push({ type: "error", reason: "error", error: errorOutput });
+			stream.end();
+		});
+		return stream;
+	}
+
 	// 1. Determine reentrancy and push parent context if needed.
 	const isReentrant = ctx().activeQuery !== null;
 	if (isReentrant) pushContext();
@@ -1902,6 +774,13 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	const mcpServers = buildMcpServers(mcpTools, ctx());
 	const bridgeConfig = loadConfig(cwd);
 	const providerSettings = bridgeConfig.provider ?? {};
+	// Whether to expose the Claude account's claude.ai cloud MCP connectors
+	// (Gmail/Calendar/Drive). Enabled via env or config; drives setting-sources,
+	// tool isolation, and the ENABLE_CLAUDEAI_MCP_SERVERS child-env gate below.
+	const enableCloudMcp = connectorsEnabledFor(bridgeConfig);
+	// Connector WRITE control: read-only by default (writes denied); the one-shot
+	// approved-write executor sets CLAUDE_BRIDGE_CONNECTOR_WRITE=allow / config.
+	const connectorWriteMode = connectorWriteModeFor(bridgeConfig);
 	const appendSystemPrompt = providerSettings.appendSystemPrompt !== false;
 	const agentsAppend = appendSystemPrompt ? extractAgentsAppend() : undefined;
 	const skillsAppend = appendSystemPrompt ? extractSkillsBlock(context.systemPrompt) : undefined;
@@ -1913,9 +792,16 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// SDK uses isolation mode and avoids filesystem settings. If users turn that
 	// off, load user/project settings but pass --strict-mcp-config so Claude Code
 	// ignores auto-discovered filesystem MCP servers while Pi owns tool execution.
-	const settingSources: SettingSource[] | undefined = appendSystemPrompt
-		? undefined
-		: providerSettings.settingSources ?? ["user", "project"];
+	// claude.ai cloud MCP connectors only load when Claude Code resolves its
+	// filesystem setting sources. The SDK treats settingSources=undefined as
+	// isolation (no sources), which drops the connectors even with
+	// ENABLE_CLAUDEAI_MCP_SERVERS=1. When connectors are enabled we force the CLI
+	// default source set so Gmail/Calendar/Drive surface.
+	const settingSources: SettingSource[] | undefined = enableCloudMcp
+		? (providerSettings.settingSources ?? ["user", "project", "local"])
+		: appendSystemPrompt
+			? undefined
+			: providerSettings.settingSources ?? ["user", "project"];
 	const strictMcpConfigEnabled = !appendSystemPrompt && providerSettings.strictMcpConfig !== false;
 	const claudeExecutable = resolveClaudeExecutable(providerSettings.pathToClaudeCodeExecutable);
 	const claudeExecutablePreflight = claudeExecutable ? preflightClaudeExecutable(claudeExecutable, cwd) : undefined;
@@ -1947,12 +833,14 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// also autocompact would double-flush the prompt cache and races pi's
 	// threshold with CC's, including CC's anti-thrashing guard (issue #8).
 	// Manual /compact in CC still works (we never invoke it).
-	const childEnv = { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: "0", DISABLE_AUTO_COMPACT: "1" };
+	// When connectors are enabled, allow claude.ai cloud MCP servers so the
+	// authenticated account's Gmail/Calendar/Drive tools load. Default stays "0".
+	const childEnv = { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: enableCloudMcp ? "1" : "0", DISABLE_AUTO_COMPACT: "1" };
 	const queryOptions: NonNullable<Parameters<typeof query>[0]["options"]> = {
 		cwd,
 		model: model.id,
 		env: childEnv,
-		...CLAUDE_BRIDGE_TOOL_ISOLATION,
+		...connectorQueryOptions(enableCloudMcp, connectorWriteMode),
 		permissionMode: "bypassPermissions",
 		includePartialMessages: true,
 		...(fallbackModel ? { fallbackModel } : {}),
@@ -1975,7 +863,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"}`,
 		`fallback=${fallbackModel ?? "none"}`,
-		`appendSys=${appendSystemPrompt} promptCtx=${promptContextAppend.labels.join(",") || "none"} strictMcp=${strictMcpConfigEnabled} fastMode=${providerSettings.fastMode === true}`,
+		`appendSys=${appendSystemPrompt} promptCtx=${promptContextAppend.labels.join(",") || "none"} strictMcp=${strictMcpConfigEnabled} fastMode=${providerSettings.fastMode === true} connectors=${enableCloudMcp}`,
 		`claudeExec=${claudeExecutablePreflight ? `${claudeExecutablePreflight.fileType}:${claudeExecutablePreflight.path}` : "sdk-default"}`,
 		`prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`);
 
@@ -2009,7 +897,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 				streamIdleTimedOut = true;
 				abortCtx.deferredUserMessages = [];
 				abortCtx.handledTerminalError = true;
-				if (sharedSession) sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+				if (sharedSession) setSharedSession({ ...sharedSession, needsRebuild: true, forceRotate: true });
 				const errorMessage = buildStreamIdleTimeoutErrorMessage(timeoutMs);
 				debug("provider: stream idle timeout", `model=${model.id}`, `timeout=${timeoutMs}`, `idle=${idleMs}`);
 				emitRateLimitEvent({
@@ -2050,8 +938,8 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		// 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();
+		const drained = drainPendingToolCalls(abortCtx, "abort");
+		if (drained > 0) debug(`provider: abort drained ${drained} waiting MCP handler(s) as errors`);
 		abortCtx.pendingResults.clear();
 		requestAbort();
 	};
@@ -2072,7 +960,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 			// --- Abort detection in normal completion path ---
 			if (wasAborted || options?.signal?.aborted) {
-				if (sharedSession) sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+				if (sharedSession) setSharedSession({ ...sharedSession, needsRebuild: true, forceRotate: true });
 				ctx().deferredUserMessages = [];
 				debug(`provider: abort detected, marked sharedSession needsRebuild + forceRotate`);
 				if (ctx().turnOutput) {
@@ -2090,7 +978,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			if (sessionId) {
 				const cursor = Math.max(context.messages.length, ctx().latestCursor, sharedSession?.cursor ?? 0);
 				debug(`provider: query done, session=${sessionId.slice(0, 8)}, cursor=${cursor}`);
-				sharedSession = { sessionId, cursor, cwd };
+				setSharedSession({ sessionId, cursor, cwd });
 			}
 
 			// --- Replay deferred user messages as continuation queries ---
@@ -2119,7 +1007,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 						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 };
+							setSharedSession({ sessionId: sid, cursor: sharedSession?.cursor ?? 0, cwd });
 						}
 					} catch (contError) {
 						debug(`provider: continuation query error:`, contError);
@@ -2140,9 +1028,9 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			const suppressDuplicateError = ctx().handledTerminalError || streamIdleTimedOut;
 			const openedExtraUsage = !suppressDuplicateError && isExtraUsageRequiredMessage(error) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "query error");
 			if ((wasAborted || options?.signal?.aborted) && sharedSession) {
-				sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+				setSharedSession({ ...sharedSession, needsRebuild: true, forceRotate: true });
 			} else {
-				sharedSession = null;
+				setSharedSession(null);
 			}
 			ctx().deferredUserMessages = [];
 			if (suppressDuplicateError) {
@@ -2162,10 +1050,12 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			activeStreamIdleWatchdogs.delete(abortCtx);
 			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
 			if (ctx().activeQuery === sdkQuery) {
-				reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: wasAborted || options?.signal?.aborted || streamIdleTimedOut });
-				// Drain pending handlers for this query
-				for (const pending of ctx().pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Query ended" }] }); }
-				ctx().pendingToolCalls.clear();
+				const cause = toolCallDrainCause({ wasAborted, signalAborted: options?.signal?.aborted, streamIdleTimedOut });
+				reportToolResultMismatch(ctx(), "query teardown", cwd, { forceRotate: cause !== "query-end" });
+				// Drain pending handlers for this query as errors naming the cause —
+				// their results are never coming.
+				const drained = drainPendingToolCalls(ctx(), cause);
+				if (drained > 0) debug(`provider: query teardown drained ${drained} waiting MCP handler(s) as errors (cause=${cause})`);
 				ctx().pendingResults.clear();
 
 				if (isReentrant) {
@@ -2206,6 +1096,38 @@ function showBridgeStatus(ctx: { ui: ExtensionUIContext; cwd?: string }): void {
 	].join("\n"), "info");
 }
 
+// Read a credential file, treating any read error as "absent" — a missing or
+// unreadable candidate must fall through to the next one, not abort resolution.
+function readCredentialFile(path: string): string | undefined {
+	try {
+		return nodeReadFileSync(path, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+// Deterministic connector enumeration for the host app (vstack#838). Reports the
+// failure reason rather than an empty list, so "no connectors" and "could not
+// check" stay distinguishable.
+async function reportConnectorInventory(ctx: { ui: ExtensionUIContext }): Promise<void> {
+	const credentials = resolveClaudeOAuth(readCredentialFile);
+	if (!credentials) {
+		ctx.ui.notify("Claude bridge: no Claude OAuth credentials found — cannot enumerate connectors.", "error");
+		return;
+	}
+	const inventory = await listAccountConnectors({ credentials });
+	if (!inventory.ok) {
+		ctx.ui.notify(`Claude bridge: connector enumeration failed — ${inventory.reason}`, "error");
+		return;
+	}
+	if (inventory.connectors.length === 0) {
+		ctx.ui.notify("Claude bridge: this account has no connectors installed.", "info");
+		return;
+	}
+	const names = inventory.connectors.map((c) => c.name).join(", ");
+	ctx.ui.notify(`Claude bridge: ${inventory.connectors.length} connector(s) installed — ${names}`, "info");
+}
+
 function registerBridgeCommands(pi: ExtensionAPI): void {
 	const guard = pi as unknown as Record<PropertyKey, unknown>;
 	if (guard[COMMANDS_REGISTERED_KEY]) return;
@@ -2242,12 +1164,16 @@ function registerBridgeCommands(pi: ExtensionAPI): void {
 		description: "Run Claude Code /extra-usage through claude-bridge",
 		handler: async (_args: string, ctx) => runExtraUsage(ctx),
 	});
+	pi.registerCommand("claude-bridge:connectors", {
+		description: "List the Claude account's installed claude.ai connectors",
+		handler: async (_args: string, ctx) => reportConnectorInventory(ctx),
+	});
 }
 
 // --- Extension registration ---
 
 export default function (pi: ExtensionAPI) {
-	extensionApi = pi;
+	setExtensionApi(pi);
 	// Disable non-essential Claude Code traffic (update checks, MCP registry, telemetry)
 	process.env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
 
@@ -2259,23 +1185,18 @@ export default function (pi: ExtensionAPI) {
 		return;
 	}
 
-	// Reset shared session on pi session lifecycle events
+	// Reset shared (Claude) conversation state on pi session lifecycle events.
+	// Registration tokens are managed separately by applyProviderRegistration
+	// (load / session_start / pre-spawn) and releaseProviderTokens (shutdown), so
+	// a mid-session credential flip is handled while token ownership is intact.
 	const clearSession = (event: string) => {
 		debug(`${event}: clearing session ${sharedSession?.sessionId?.slice(0, 8) ?? "none"}`);
-		sharedSession = null;
-
-		// Clear the global streamSimple if this instance registered it.
-		// This allows /reload to work — the old instance clears the flag so
-		// the new instance can register fresh without wrapping stale state.
-		const g = globalThis as Record<symbol, any>;
-		if (g[ACTIVE_STREAM_SIMPLE_KEY] === streamClaudeAgentSdk) {
-			debug(`${event}: clearing ACTIVE_STREAM_SIMPLE_KEY`);
-			g[ACTIVE_STREAM_SIMPLE_KEY] = undefined;
-		}
+		setSharedSession(null);
 	};
+
 	pi.on("session_start", (event, ctx) => {
 		recordProjectTrust(ctx);
-		piUI = ctx.ui;
+		setPiUI(ctx.ui);
 		if (event.reason === "new" || event.reason === "resume" || event.reason === "fork") {
 			clearSession(`session_start:${event.reason}`);
 		}
@@ -2284,8 +1205,14 @@ export default function (pi: ExtensionAPI) {
 		// them would --resume the parent's Claude jsonl and leak conversation past the
 		// fork point. Letting the first fork turn rebuild is the correct path.
 		if (event.reason === "startup" || event.reason === "resume") restoreSharedSessionFromPi(ctx);
+		// Live availability flip: re-evaluate credential presence every
+		// session_start so login/logout since load is reflected without /reload.
+		applyProviderRegistration(`session_start:${event.reason}`);
+	});
+	pi.on("session_shutdown", () => {
+		clearSession("session_shutdown");
+		releaseProviderTokens("session_shutdown");
 	});
-	pi.on("session_shutdown", () => clearSession("session_shutdown"));
 	pi.on("message_end", (event, ctx) => {
 		const message = (event as { message?: AssistantMessage }).message;
 		if (message?.role === "assistant" && message.provider === PROVIDER_ID) schedulePersistSharedSession(ctx);
@@ -2304,7 +1231,7 @@ export default function (pi: ExtensionAPI) {
 		}
 		if (sharedSession) {
 			debug(`${event}: marking needsRebuild on session ${sharedSession.sessionId.slice(0, 8)}`);
-			sharedSession = { ...sharedSession, needsRebuild: true };
+			setSharedSession({ ...sharedSession, needsRebuild: true });
 		}
 	};
 	pi.on("session_compact", () => markRebuild("session_compact"));
@@ -2312,30 +1239,14 @@ export default function (pi: ExtensionAPI) {
 
 	// --- Provider ---
 	//
-	// Guard against re-registration when the module is loaded multiple times
-	// (e.g., when spawning subagents). The shared ModelRegistry would otherwise
-	// overwrite the parent's streamSimple, breaking tool result delivery.
-	// See ACTIVE_STREAM_SIMPLE_KEY for the full mechanism.
-
-	const g = globalThis as Record<symbol, any>;
-	if (!g[ACTIVE_STREAM_SIMPLE_KEY]) {
-		// First instance: store our streamSimple and register.
-		g[ACTIVE_STREAM_SIMPLE_KEY] = streamClaudeAgentSdk;
-		pi.registerProvider(PROVIDER_ID, {
-			baseUrl: "claude-bridge",
-			apiKey: "not-used",
-			api: "claude-bridge",
-			models: MODELS,
-			// Cast: pi-ai AssistantMessageEventStream diamond dep between pi-coding-agent and pi-agent-core
-			streamSimple: streamClaudeAgentSdk as any,
-		});
-	} else {
-		// Subsequent instance (subagent session): skip registration entirely.
-		// The subagent already has access to claude-bridge models via the shared
-		// ModelRegistry from the parent's registration. Calls to those models
-		// will route through the parent's streamSimple via the reentrant
-		// QueryContext stack mechanism.
-		debug(`provider: skipping re-registration, parent instance active (module=${moduleInstanceId})`);
-	}
-
+	// Register the provider ONLY when real Claude credentials are present, so
+	// claude-bridge models are never advertised as available/selectable when a
+	// request would fail at spawn time (pi's ModelRegistry.hasConfiguredAuth()
+	// treats the dummy apiKey as "configured", so the gate must live here).
+	//
+	// applyProviderRegistration also claims the primary-instance token (first
+	// load wins) and enforces the multi-instance guard: a non-primary subagent
+	// reload always no-ops, so it never overwrites the parent's streamSimple nor
+	// steals ownership. See PRIMARY_INSTANCE_KEY / ACTIVE_STREAM_SIMPLE_KEY.
+	applyProviderRegistration("load");
 }