@vanillagreen/pi-claude-bridge 1.9.0 → 2.0.0

package/src/index.ts

@@ -7,9 +7,11 @@ 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 { extractAllToolResults as _extractAllToolResults, type McpResult } from "./extract-tool-results.js";
-import { QueryContext, ctx, drainPendingToolCalls, stackDepth, pushContext, popContext, toolCallDrainCause } from "./query-state.js";
+import { QueryContext, ctx, drainPendingToolCalls, stackDepth, pushContext, toolCallDrainCause } from "./query-state.js";
+import { teardownQuery } from "./query-teardown.js";
 import { loadConfig, normalizeEffortLevel, recordProjectTrust, type Config } from "./config.js";
-import { decideRegistration, hasClaudeCredentials } from "./auth-presence.js";
+import { hasClaudeCredentials } from "./auth-presence.js";
+import { NATIVE_PROVIDER_UNSUPPORTED_MESSAGE, buildNativeProvider, supportsNativeProvider } from "./native-provider.js";
 import { extractAgentsAppend } from "./agents-md.js";
 import { buildPromptContextAppend } from "./prompt-context.js";
 import { jsonSchemaToZodShape } from "./typebox-to-zod.js";
@@ -25,6 +27,8 @@ import { listAccountConnectors, resolveClaudeOAuth } from "./connector-inventory
 // path their existing manifest already allows, and incidentally keeps esbuild
 // from tree-shaking helpers index.ts never calls itself.
 export {
+	connectorProxyUrl,
+	connectorServerName,
 	connectorServerNamespace,
 	connectorsListUrl,
 	credentialCandidatePaths,
@@ -34,27 +38,31 @@ export {
 	type ConnectorEntry,
 	type ConnectorInventory,
 } from "./connector-inventory.js";
+export { connectorCachePath, connectorCacheScopeKey, readCachedConnectors, writeCachedConnectors } from "./connector-cache.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 { appendIntegrityEntry, argKeys, extensionApi, piUI, reportToolResultMismatch, safeNotify, safeToolCallSummary, setExtensionApi, setPiUI, setSharedSession, sharedSession } from "./bridge-state.js";
+import { connectorMcpServers, connectorQueryOptions, connectorWriteModeFor, connectorsEnabledFor, isChildExecutedTool } from "./connectors.js";
+import { readCachedConnectors, writeCachedConnectors } from "./connector-cache.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 { RATE_LIMIT_AUTO_RESUME_EVENT, RATE_LIMIT_TOKEN, formatAllowedRateLimitWarning, formatResetTimestamp, isExtraUsageRequiredMessage, isUsageLimitMessage, resetTimestampMs, uniqueNonEmptyLines } from "./rate-limit.js";
 import { mapToolArgs } from "./tool-mapping.js";
-import { ensureTurnStarted, finalizeCurrentStream, parsePartialJson, processAssistantMessage, processStreamEvent, updateTurnOutputModel } from "./assistant-stream.js";
+import { ensureTurnStarted, finalizeCurrentStream, finalizeToolUseTurnFromMcpInvocation, noteChildExecutedToolResults, processAssistantMessage, processStreamEvent, scheduleToolUseTurnEnd, 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 { __testGetBridgeIntegrityState, __testSetBridgeIntegrityState, INTEGRITY_CUSTOM_TYPE, appendIntegrityEntry, reportToolResultMismatch } from "./bridge-state.js";
+export { CONNECTOR_CALL_CUSTOM_TYPE, connectorResultByteSize, flushConnectorCallAudit, recordConnectorCallResult, setConnectorCallAuditSink, type ConnectorCallAuditData, type ConnectorCallAuditSink, type ConnectorCallOutcome } from "./connector-audit.js";
+export { CLAUDE_AI_CONNECTOR_TOOL_PATTERNS, connectorMcpServers, connectorDeclarationsDisabled, CLAUDE_BRIDGE_TOOL_ISOLATION, CONNECTOR_DISCOVERY_TOOLS, CONNECTOR_WRITE_TOOLS, DISALLOWED_BUILTIN_TOOLS, connectorQueryOptions, connectorWriteDenyHook, connectorWriteModeFor, connectorWriteModeFromEnv, connectorsEnabledFor, connectorsEnabledFromEnv, isChildExecutedTool, isConnectorWriteTool, toolIsolationForQuery } from "./connectors.js";
 export { restoreSharedSessionFromPi, shouldRestorePersistedBridgeEntry } from "./session-persistence.js";
+export { NATIVE_PROVIDER_UNSUPPORTED_MESSAGE, buildNativeProvider, claudeAuthSourceLabel, supportsNativeProvider } from "./native-provider.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 { ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD, formatAllowedRateLimitWarning, formatResetTimestamp, isExtraUsageRequiredMessage, isUsageLimitMessage, normalizeRateLimitUtilization, resetTimestampMs, uniqueNonEmptyLines } from "./rate-limit.js";
 export { mapToolName } from "./tool-mapping.js";
-export { processAssistantMessage, processStreamEvent } from "./assistant-stream.js";
+export { cancelScheduledToolUseEnd, endToolUseTurn, finalizeToolUseTurnFromMcpInvocation, noteChildExecutedToolResults, processAssistantMessage, processStreamEvent, reapStaleQueuedResults, scheduleToolUseTurnEnd } 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;
@@ -89,7 +97,7 @@ const newAssistantMessageEventStream: () => AssistantMessageEventStream =
 //
 // 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.
+// native (pi >=0.81) upsert flow.
 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");
@@ -111,6 +119,35 @@ function extraUsageAllowed(config: Config): boolean {
 	return config.provider?.allowExtraUsage === true;
 }
 
+// The fastMode setting silently no-ops when Claude Code declines fast mode.
+// Surface the typed fast_mode_disabled_reason (SDK 0.3.219+) once per distinct
+// reason so an enabled-but-inert setting explains itself instead of looking
+// broken. Module-level dedup: the same reason repeats on every init message.
+let lastFastModeDisabledNoticeReason: string | null = null;
+
+const FAST_MODE_DISABLED_REASON_TEXT: Record<string, string> = {
+	disabled_by_env: "disabled by an environment variable",
+	extra_usage_disabled: "extra usage is disabled for this account",
+	free: "not available on the free plan",
+	model_not_allowed: "not available for this model",
+	network_error: "the eligibility check hit a network error",
+	not_first_party: "not available for this account type",
+	preference: "disabled by a Claude Code preference",
+	sdk_opt_in_required: "the SDK opt-in is missing",
+	unknown: "unavailable for an unknown reason",
+};
+
+function noteFastModeDisabledReason(message: unknown, bridgeConfig: Config): void {
+	if (bridgeConfig.provider?.fastMode !== true) return;
+	const reason = (message as { fast_mode_disabled_reason?: unknown }).fast_mode_disabled_reason;
+	// "pending" means the CLI is still deciding — not a verdict worth announcing.
+	if (typeof reason !== "string" || reason === "pending") return;
+	if (reason === lastFastModeDisabledNoticeReason) return;
+	lastFastModeDisabledNoticeReason = reason;
+	const text = FAST_MODE_DISABLED_REASON_TEXT[reason] ?? `unavailable (${reason})`;
+	safeNotify(`Claude bridge: fast mode is enabled in settings but Claude Code declined it — ${text}.`, "warning");
+}
+
 function sdkTextFromMessage(message: SDKMessage): string | undefined {
 	if (message.type === "result") return (message as any).result;
 	if (message.type === "assistant") {
@@ -243,7 +280,7 @@ async function* wrapPromptStream(blocks: ContentBlockParam[]): AsyncIterable<SDK
 // them without activating the extension. `ctx()`, `pushContext()`, `popContext()`
 // are imported at the top of this file.
 
-function resolveMcpTools(context: Context, excludeToolName?: string): {
+export function resolveMcpTools(context: Context, excludeToolName?: string): {
 	mcpTools: Tool[];
 	customToolNameToSdk: Map<string, string>;
 	customToolNameToPi: Map<string, string>;
@@ -256,10 +293,29 @@ function resolveMcpTools(context: Context, excludeToolName?: string): {
 
 	for (const tool of context.tools) {
 		if (tool.name === excludeToolName) continue;
+		// Never re-offer a tool the child owns natively. The claude.ai connector
+		// namespace belongs to the child's own MCP servers, so a Pi tool sitting
+		// on it would be advertised a SECOND time under our prefix — two names
+		// for one capability, and the model picking the wrong one gets a real
+		// `Tool ... not found` from the dispatcher (memsira#320). It would also
+		// be uncallable in any case: a `tool_use` under that namespace is treated
+		// as child-executed and never handed to Pi (isChildExecutedTool), so
+		// filtering here is what makes the two halves agree end to end.
+		if (isChildExecutedTool(tool.name)) {
+			debug(`resolveMcpTools: not re-offering child-native tool ${tool.name}`);
+			continue;
+		}
 		const sdkName = `${MCP_TOOL_PREFIX}${tool.name}`;
 		mcpTools.push(tool);
+		// Case-insensitive aliases mean two tools differing only by case would
+		// silently overwrite each other's mapping — surface it if it ever happens.
+		const lowerName = tool.name.toLowerCase();
+		const collision = customToolNameToSdk.get(lowerName);
+		if (collision !== undefined && collision !== sdkName) {
+			debug(`WARNING: resolveMcpTools lowercase alias collision: ${tool.name} overwrites mapping previously held by ${collision}`);
+		}
 		customToolNameToSdk.set(tool.name, sdkName);
-		customToolNameToSdk.set(tool.name.toLowerCase(), sdkName);
+		customToolNameToSdk.set(lowerName, sdkName);
 		customToolNameToPi.set(sdkName, tool.name);
 		customToolNameToPi.set(sdkName.toLowerCase(), tool.name);
 	}
@@ -267,54 +323,12 @@ 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;
-}
+// finalizeToolUseTurnFromMcpInvocation moved to assistant-stream.ts: it is now
+// the grace-timer ACTION armed by scheduleToolUseTurnEnd rather than an
+// immediate end. The CLI invokes MCP handlers before message_delta arrives on
+// every tool-use turn, and message_delta is what carries the real output-token
+// count — ending the pi stream at handler invocation is what froze pi's
+// per-turn output figures at the message_start placeholders (1–7 tokens).
 
 // 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.
@@ -341,9 +355,25 @@ function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string,
 					turnToolCallIds: queryCtx.turnToolCallIds,
 					turnToolCalls: safeToolCallSummary(queryCtx.turnToolCalls),
 				});
+				appendIntegrityEntry("tool_handler_unmatched", {
+					toolName: tool.name,
+					argKeys: argKeys(mappedArgs),
+					available: claim.available,
+					turnToolCallIds: queryCtx.turnToolCallIds,
+				});
 				return { content: [{ type: "text", text: `Claude bridge internal error: no matching tool_call id for ${tool.name}` }], isError: true } satisfies McpResult;
 			}
-			if (claim.match !== "tool-args" || claim.ambiguous) {
+			if (claim.argsMismatch) {
+				// Claimed anyway (sole same-name candidate) — record the divergence so
+				// a schema/validator drift stays visible without stranding the call.
+				debug(`mcp handler: ${tool.name} [${toolCallId}] claimed sole same-name call despite args mismatch`);
+				diagDump("tool_claim_args_mismatch", {
+					toolName: tool.name,
+					toolCallId,
+					handlerArgKeys: argKeys(mappedArgs),
+					recordedArgKeys: argKeys(queryCtx.turnToolCalls.find((call) => call.id === toolCallId)?.arguments),
+				});
+			} else if (claim.match !== "tool-args" || claim.ambiguous) {
 				debug(`mcp handler: ${tool.name} [${toolCallId}] claimed by ${claim.match}${claim.ambiguous ? " (ambiguous)" : ""}`);
 			}
 			if (toolCallId && queryCtx.pendingResults.has(toolCallId)) {
@@ -354,7 +384,14 @@ function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string,
 				return result;
 			}
 			debug(`mcp handler: ${tool.name} [${toolCallId}] → waiting`);
-			finalizeToolUseTurnFromMcpInvocation(queryCtx, toolCallId, tool.name, mappedArgs);
+			// Don't end the pi turn here — message_delta (real output tokens) and
+			// message_stop are normally milliseconds behind this invocation. Arm the
+			// grace timer instead; it force-finalizes only if they never arrive.
+			scheduleToolUseTurnEnd(
+				queryCtx,
+				() => finalizeToolUseTurnFromMcpInvocation(queryCtx, toolCallId, tool.name, mappedArgs),
+				`mcp-invocation:${tool.name}`,
+			);
 			return new Promise<McpResult>((resolve) => {
 				queryCtx.pendingToolCalls.set(toolCallId, {
 					toolName: tool.name,
@@ -443,20 +480,38 @@ async function consumeQuery(
 				break;
 			case "result":
 				if (!ctx().turnSawStreamEvent && message.subtype === "success") {
-					ensureTurnStarted();
 					const text = message.result || "";
+					// The no-stream-events assistant fallback may have already rendered
+					// this exact text (it does not set turnSawStreamEvent) — re-pushing
+					// it here is the other half of the duplicated-output bug.
+					if (ctx().turnBlocks.some((b: any) => b.type === "text" && b.text === text)) {
+						debug("consumeQuery: result text already rendered by assistant fallback; skipping duplicate");
+						break;
+					}
+					ensureTurnStarted();
 					ctx().turnBlocks.push({ type: "text", text });
 					const idx = ctx().turnBlocks.length - 1;
 					ctx().currentPiStream?.push({ type: "text_start", contentIndex: idx, partial: ctx().turnOutput });
 					ctx().currentPiStream?.push({ type: "text_delta", contentIndex: idx, delta: text, partial: ctx().turnOutput });
 					ctx().currentPiStream?.push({ type: "text_end", contentIndex: idx, content: text, partial: ctx().turnOutput });
-				} else if (message.subtype !== "success" && isExtraUsageRequiredMessage(message)) {
+				} else if (message.subtype !== "success" && (isExtraUsageRequiredMessage(message) || isUsageLimitMessage(message))) {
+					// isUsageLimitMessage matches the CLI's own usage-limit copy (SDK
+					// USAGE_LIMIT_ERROR_PREFIXES) — e.g. a plain "You've hit your weekly
+					// limit" that the extra-usage regex never matched, so those turns
+					// used to end as a silent empty success. The /extra-usage helper and
+					// its hints stay gated on the narrow extra-usage test.
 					const errorLines = Array.isArray((message as any).errors) ? uniqueNonEmptyLines((message as any).errors) : [];
 					const errors = errorLines.length > 0 ? errorLines.join("\n") : String(message.subtype ?? "Claude Code rate limit");
-					const openedExtraUsage = launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "result error");
+					const extraUsage = isExtraUsageRequiredMessage(message);
+					const openedExtraUsage = extraUsage && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "result error");
 					ctx().handledTerminalError = true;
 					ctx().turnOutput.stopReason = "error";
-					ctx().turnOutput.errorMessage = `${errors}${openedExtraUsage ? "\n\nOpened Claude Code /extra-usage helper. Complete billing/admin flow in the browser, then retry the prompt." : "\n\nRun /claude-bridge:extra, or enable Allow extra usage helper in settings."}`;
+					const extraUsageHint = openedExtraUsage
+						? "\n\nOpened Claude Code /extra-usage helper. Complete billing/admin flow in the browser, then retry the prompt."
+						: extraUsage
+							? "\n\nRun /claude-bridge:extra, or enable Allow extra usage helper in settings."
+							: "";
+					ctx().turnOutput.errorMessage = `${errors}${extraUsageHint}`;
 					ctx().currentPiStream?.push({ type: "error", reason: "error", error: ctx().turnOutput });
 					ctx().currentPiStream?.end();
 					ctx().currentPiStream = null;
@@ -465,6 +520,11 @@ async function consumeQuery(
 			case "system":
 				if ((message as any).subtype === "init" && (message as any).session_id) {
 					capturedSessionId = (message as any).session_id;
+					// Also on this message's query context, so the connector-call audit
+					// trail can name the child session that executed a call — including
+					// from the teardown flush, which runs outside this function's scope.
+					queryCtx.childSessionId = capturedSessionId;
+					noteFastModeDisabledReason(message, bridgeConfig);
 				} else if ((message as any).subtype === "model_refusal_fallback") {
 					const originalModel = (message as any).original_model;
 					const fallbackModel = (message as any).fallback_model;
@@ -481,13 +541,17 @@ async function consumeQuery(
 				}
 				break;
 			case "user":
-				break; // SDK echo of user prompt — not needed
+				// Mostly the SDK echoing the prompt back — nothing to render. The one
+				// thing worth reading is a child-executed tool's real result, which
+				// arrives here and nowhere else.
+				noteChildExecutedToolResults(message);
+				break;
 			case "rate_limit_event": {
 				const info = (message as any).rate_limit_info;
 				debug("consumeQuery: rate_limit_event", JSON.stringify(info).slice(0, 300));
 				if (info?.status === "rejected") {
 					const resetsAt = formatResetTimestamp(info.resetsAt);
-					const resetAtMs = typeof info.resetsAt === "string" ? Date.parse(info.resetsAt) : undefined;
+					const resetAtMs = resetTimestampMs(info.resetsAt);
 					const reason = `${info.rateLimitType ?? "unknown"} rate limit`;
 					const launchedExtraUsage = isExtraUsageRequiredMessage(info) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, reason);
 					emitRateLimitEvent({
@@ -532,10 +596,10 @@ function claimPrimaryInstance(): boolean {
 
 // 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.
+// NOTE: this does NOT unregister the provider — pi's provider registry is
+// process-lifetime state that survives module reload; the next loaded instance
+// simply upserts its own provider object over ours (registerNativeProvider is
+// replace-by-id), and logout-hiding is the provider's own auth check.
 function releaseProviderTokens(event: string): void {
 	const g = globalThis as Record<symbol, any>;
 	if (g[ACTIVE_STREAM_SIMPLE_KEY] === streamClaudeAgentSdk) {
@@ -548,61 +612,66 @@ function releaseProviderTokens(event: string): void {
 	}
 }
 
-// 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.
+// Native (pi >=0.81) provider registration. Run at extension load, on every
+// session_start, and at pre-spawn.
 //
-// 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.
+// 2.x registers UNCONDITIONALLY (once primary): credential-driven availability
+// is the provider's own auth.check/resolve reporting configured-ness, so pi
+// hides/shows claude-bridge models itself — the 1.x register/unregister state
+// machine (decideRegistration) is gone. What each trigger does now:
+//   - load: build + register the provider (queued by the loader until bindCore).
+//   - session_start: re-upsert the SAME provider object. registerNativeProvider
+//     is upsert-by-id and kicks pi's model-snapshot/availability refresh, so a
+//     `claude login`/logout since the last session boundary is reflected
+//     deterministically — the same guarantee the 1.x re-check gave — without
+//     depending on pi's own refresh cadence.
+//   - pre-spawn: same re-upsert, from the fail-fast path, so a mid-session
+//     logout also flips availability at first use.
+// Non-primary instances (subagents) never touch registration: pi's native
+// registry REPLACES by id, so an unguarded subagent re-register would swap in
+// its own streamSimple — the exact split-brain the tokens exist to prevent.
+// On a pre-0.81 host the extension declines loudly (once) instead of
+// registering wrongly through the legacy overload.
+let nativeProviderInstance: unknown;
+let notifiedNativeUnsupported = false;
+
 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 (!isPrimary) {
+		debug(`${trigger}: registration noop — non-primary instance (module=${moduleInstanceId})`);
+		return;
+	}
+	if (!supportsNativeProvider(_piAi)) {
+		debug(`${trigger}: host pi-ai lacks createProvider; refusing to register (module=${moduleInstanceId})`);
+		if (!notifiedNativeUnsupported) {
+			notifiedNativeUnsupported = true;
+			safeNotify(NATIVE_PROVIDER_UNSUPPORTED_MESSAGE, "error");
 		}
+		return;
+	}
+	const credentialed = hasClaudeCredentials();
+	debug(`${trigger}: native registration upsert, credentialed=${credentialed} (module=${moduleInstanceId})`);
+	// Start the connector inventory now, not on the first turn: the query path
+	// can only read a synchronous snapshot, so priming here is what gets the
+	// declarations in place before turn 1 (vstack#832). Fire and forget —
+	// registration must not wait on the network. Only worth it when a Claude
+	// account is actually connected.
+	if (credentialed && connectorsEnabledFor(loadConfig(process.cwd()))) primeConnectorServers();
+	// 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 {
+		nativeProviderInstance ??= buildNativeProvider(_piAi, MODELS, streamClaudeAgentSdk as (...args: unknown[]) => unknown);
+		(pi.registerProvider as (provider: unknown) => void)(nativeProviderInstance);
+	} catch (err) {
+		// Self-heal: release ONLY the stream guard we just claimed so a later
+		// re-check retries cleanly. Keep PRIMARY_INSTANCE_KEY: releasing it would
+		// reopen the subagent ownership-steal window.
 		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);
 	}
 }
 
@@ -708,12 +777,12 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// 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).
+	// the logout-visibility window from "next session boundary" to "first use":
+	// if credentials vanished since the last session_start, (a) re-upsert the
+	// provider (primary-only) so pi's availability recompute hides the models,
+	// 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.";
@@ -781,6 +850,10 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// 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);
+	// Declare the account's connected connectors explicitly so `alwaysLoad` can
+	// hold startup until they attach — otherwise the turn-1 manifest is built
+	// before the CLI has fetched them (vstack#832).
+	const connectorServers = enableCloudMcp ? connectorServersSnapshot() : {};
 	const appendSystemPrompt = providerSettings.appendSystemPrompt !== false;
 	const agentsAppend = appendSystemPrompt ? extractAgentsAppend() : undefined;
 	const skillsAppend = appendSystemPrompt ? extractSkillsBlock(context.systemPrompt) : undefined;
@@ -817,9 +890,12 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	const effort = resolveConfiguredEffort(model.id, requestedEffort, providerSettings);
 
 	const extraArgs: Record<string, string | null> = {};
-	if (strictMcpConfigEnabled) extraArgs["strict-mcp-config"] = null;
 	// Opus 4.7 defaults thinking.display to "omitted" (empty thinking text in stream).
 	// Force summarized so thinking_delta events arrive. See anthropics/claude-agent-sdk-python#830.
+	// Deliberately the raw flag, NOT the typed `thinking` option: every non-disabled
+	// ThinkingConfig also emits `--thinking adaptive` or `--max-thinking-tokens`
+	// (verified in sdk.mjs flag mapping), so the typed form cannot set display
+	// without overriding the model's thinking mode alongside our `--effort`.
 	if (effort) extraArgs["thinking-display"] = "summarized";
 	const fallbackModel = fallbackModelForPrimaryModel(model.id);
 
@@ -850,9 +926,12 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			append: systemPromptAppend ? systemPromptAppend : undefined,
 		},
 		extraArgs,
+		...(strictMcpConfigEnabled ? { strictMcpConfig: true } : {}),
 		...(effort ? { effort } : {}),
 		...(settingSources ? { settingSources } : {}),
-		...(mcpServers ? { mcpServers } : {}),
+		...(mcpServers || Object.keys(connectorServers).length > 0
+			? { mcpServers: { ...(mcpServers ?? {}), ...connectorServers } as NonNullable<Parameters<typeof query>[0]["options"]>["mcpServers"] }
+			: {}),
 		...(resumeSessionId ? { resume: resumeSessionId } : {}),
 		...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
 		spawnClaudeCodeProcess: spawnClaudeCodeWithDiagnostics,
@@ -948,10 +1027,15 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		else options.signal.addEventListener("abort", onAbort, { once: true });
 	}
 
-	// Background consumer — runs until query ends
+	// Background consumer — runs until query ends.
+	// The handlers below use the CAPTURED abortCtx, never the live ctx(): the two
+	// only differ while a reentrant (subagent) context is pushed, and a parent
+	// query CAN end in that window (abort, child process death throwing out of
+	// the generator). Live-ctx handlers there mutated the subagent's turn state
+	// and stream and skipped the parent's own teardown entirely.
 	consumeQuery(sdkQuery, customToolNameToPi, model, cwd, bridgeConfig, () => wasAborted)
 		.then(async ({ capturedSessionId }) => {
-			debug(`provider: consumeQuery completed, stopReason=${ctx().turnOutput?.stopReason}, error=${ctx().turnOutput?.errorMessage}, aborted=${wasAborted}`);
+			debug(`provider: consumeQuery completed, stopReason=${abortCtx.turnOutput?.stopReason}, error=${abortCtx.turnOutput?.errorMessage}, aborted=${wasAborted}`);
 			if (streamIdleTimedOut) {
 				abortCtx.deferredUserMessages = [];
 				debug("provider: stream idle timeout already surfaced; skipping normal completion");
@@ -961,22 +1045,22 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			// --- Abort detection in normal completion path ---
 			if (wasAborted || options?.signal?.aborted) {
 				if (sharedSession) setSharedSession({ ...sharedSession, needsRebuild: true, forceRotate: true });
-				ctx().deferredUserMessages = [];
+				abortCtx.deferredUserMessages = [];
 				debug(`provider: abort detected, marked sharedSession needsRebuild + forceRotate`);
-				if (ctx().turnOutput) {
-					ctx().turnOutput.stopReason = "aborted";
-					ctx().turnOutput.errorMessage = "Operation aborted";
+				if (abortCtx.turnOutput) {
+					abortCtx.turnOutput.stopReason = "aborted";
+					abortCtx.turnOutput.errorMessage = "Operation aborted";
 				}
-				ctx().currentPiStream?.push({ type: "error", reason: "aborted", error: ctx().turnOutput! });
-				ctx().currentPiStream?.end();
-				ctx().currentPiStream = null;
+				abortCtx.currentPiStream?.push({ type: "error", reason: "aborted", error: abortCtx.turnOutput! });
+				abortCtx.currentPiStream?.end();
+				abortCtx.currentPiStream = null;
 				return;
 			}
 
 			// --- Capture session ID ---
 			const sessionId = capturedSessionId ?? sharedSession?.sessionId;
 			if (sessionId) {
-				const cursor = Math.max(context.messages.length, ctx().latestCursor, sharedSession?.cursor ?? 0);
+				const cursor = Math.max(context.messages.length, abortCtx.latestCursor, sharedSession?.cursor ?? 0);
 				debug(`provider: query done, session=${sessionId.slice(0, 8)}, cursor=${cursor}`);
 				setSharedSession({ sessionId, cursor, cwd });
 			}
@@ -985,11 +1069,11 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			// Only for outermost queries — reentrant (subagent) queries leave
 			// deferred messages for the parent to handle after it finishes.
 			try {
-				while (ctx().deferredUserMessages.length > 0 && !isReentrant && !wasAborted) {
-					const steerPrompt = ctx().deferredUserMessages.shift()!;
+				while (abortCtx.deferredUserMessages.length > 0 && !isReentrant && !wasAborted) {
+					const steerPrompt = abortCtx.deferredUserMessages.shift()!;
 					debug(`provider: replaying deferred user message: ${steerPrompt.slice(0, 60)}`);
-					ctx().resetTurnState(model);
-					ctx().resetToolTracking();
+					abortCtx.resetTurnState(model);
+					abortCtx.resetToolTracking();
 
 					const resumeId = sharedSession?.sessionId;
 					if (!resumeId) {
@@ -999,7 +1083,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 
 					const contOptions = { ...queryOptions, resume: resumeId, ...makeCliDebugOptions("continuation") };
 					const contQuery = query({ prompt: steerPrompt, options: contOptions });
-					ctx().activeQuery = contQuery;
+					abortCtx.activeQuery = contQuery;
 
 					debug(`provider: continuation query, model=${model.id}, resume=${resumeId.slice(0, 8)}, prompt=${steerPrompt.slice(0, 60)}`);
 
@@ -1018,52 +1102,39 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 				}
 			} finally {
 				// Guarantees restoration even if contQuery() throws synchronously
-				ctx().activeQuery = sdkQuery;
+				abortCtx.activeQuery = sdkQuery;
 			}
 
-			finalizeCurrentStream(ctx().turnOutput?.stopReason);
+			finalizeCurrentStream(abortCtx.turnOutput?.stopReason, abortCtx);
 		})
 		.catch((error) => {
 			debug(`provider: query error, model=${model.id}, aborted=${Boolean(options?.signal?.aborted)}, error=`, error);
-			const suppressDuplicateError = ctx().handledTerminalError || streamIdleTimedOut;
+			const suppressDuplicateError = abortCtx.handledTerminalError || streamIdleTimedOut;
 			const openedExtraUsage = !suppressDuplicateError && isExtraUsageRequiredMessage(error) && launchExtraUsageHelperIfAllowed(cwd, bridgeConfig, "query error");
 			if ((wasAborted || options?.signal?.aborted) && sharedSession) {
 				setSharedSession({ ...sharedSession, needsRebuild: true, forceRotate: true });
 			} else {
 				setSharedSession(null);
 			}
-			ctx().deferredUserMessages = [];
+			abortCtx.deferredUserMessages = [];
 			if (suppressDuplicateError) {
 				debug("provider: suppressing duplicate query error after terminal error was already emitted");
 				return;
 			}
-			if (ctx().turnOutput) {
-				ctx().turnOutput.stopReason = options?.signal?.aborted ? "aborted" : "error";
-				ctx().turnOutput.errorMessage = `${error instanceof Error ? error.message : String(error)}${openedExtraUsage ? "\n\nOpened Claude Code /extra-usage helper. Complete billing/admin flow in the browser, then retry the prompt." : ""}`;
+			if (abortCtx.turnOutput) {
+				abortCtx.turnOutput.stopReason = options?.signal?.aborted ? "aborted" : "error";
+				abortCtx.turnOutput.errorMessage = `${error instanceof Error ? error.message : String(error)}${openedExtraUsage ? "\n\nOpened Claude Code /extra-usage helper. Complete billing/admin flow in the browser, then retry the prompt." : ""}`;
 			}
-			ctx().currentPiStream?.push({ type: "error", reason: (ctx().turnOutput?.stopReason ?? "error") as "aborted" | "error", error: ctx().turnOutput! });
-			ctx().currentPiStream?.end();
-			ctx().currentPiStream = null;
+			abortCtx.currentPiStream?.push({ type: "error", reason: (abortCtx.turnOutput?.stopReason ?? "error") as "aborted" | "error", error: abortCtx.turnOutput! });
+			abortCtx.currentPiStream?.end();
+			abortCtx.currentPiStream = null;
 		})
 		.finally(() => {
 			streamIdleWatchdog?.dispose();
 			activeStreamIdleWatchdogs.delete(abortCtx);
 			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
-			if (ctx().activeQuery === sdkQuery) {
-				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) {
-					popContext();  // merges deferred messages and restores parent
-				} else {
-					ctx().activeQuery = null;
-				}
-			}
+			const cause = toolCallDrainCause({ wasAborted, signalAborted: options?.signal?.aborted, streamIdleTimedOut });
+			teardownQuery(abortCtx, sdkQuery, cause, cwd, isReentrant);
 			sdkQuery.close();
 		});
 
@@ -1106,6 +1177,92 @@ function readCredentialFile(path: string): string | undefined {
 	}
 }
 
+// Connector declarations for the query path (vstack#832), cached per credential
+// scope. The inventory is one HTTPS round trip; doing it per TURN would add that
+// latency to every message, and an account's connector set does not change
+// mid-session. Keyed by CLAUDE_CONFIG_DIR because that is what selects the
+// account — the org UUID in the request path is ignored, so two accounts on one
+// host differ only by which credential directory was read.
+//
+// FAILS OPEN. If credentials or the inventory call fail we return no
+// declarations and the turn proceeds exactly as it does today: connectors may
+// race, which is the bug, but a network blip must not break the turn outright.
+const connectorServerCache = new Map<string, Record<string, unknown>>();
+const connectorServerPending = new Set<string>();
+
+function connectorScopeKey(): string {
+	return process.env.CLAUDE_CONFIG_DIR?.trim() || "<default>";
+}
+
+// Kick off the inventory fetch for the current credential scope. Fire and
+// forget: the query path can only read a SYNCHRONOUS snapshot, because
+// streamClaudeAgentSdk returns a stream and claims the SDK query handle in the
+// same tick — there is no await boundary to hang a fetch on without
+// restructuring abort handling.
+//
+// Primed at provider registration so the result is in hand well before the
+// first turn (the call measured ~400ms against app startup). If a turn arrives
+// first it declares nothing and behaves exactly as it does today — the race is
+// back for that one turn, which is the bug, but never worse than the status quo.
+//
+// FAILS OPEN throughout: no credentials, a failed inventory, or a thrown call
+// all resolve to "declare nothing" rather than breaking the turn.
+export function primeConnectorServers(): void {
+	const key = connectorScopeKey();
+	if (connectorServerCache.has(key) || connectorServerPending.has(key)) return;
+	connectorServerPending.add(key);
+	void (async () => {
+		try {
+			const credentials = resolveClaudeOAuth(readCredentialFile);
+			if (!credentials) {
+				debug("connectors: no OAuth credentials; declaring none");
+				connectorServerCache.set(key, {});
+				return;
+			}
+			const inventory = await listAccountConnectors({ credentials });
+			if (!inventory.ok) {
+				debug(`connectors: inventory failed (${inventory.reason}); declaring none`);
+				connectorServerCache.set(key, {});
+				return;
+			}
+			const servers = connectorMcpServers(inventory);
+			debug(`connectors: declaring ${Object.keys(servers).length} of ${inventory.connectors.length} installed`,
+				Object.keys(servers).join(", ") || "none");
+			connectorServerCache.set(key, servers);
+			// Persist so the NEXT cold process has this synchronously. Priming always
+			// loses the race against turn 1 in its own process; a cache written by an
+			// earlier run is the only thing turn 1 can read in time (vstack#870).
+			if (writeCachedConnectors(inventory.connectors, key)) {
+				debug(`connectors: cached ${inventory.connectors.length} entries`);
+			}
+		} catch (error) {
+			debug("connectors: declaration lookup threw; declaring none", error);
+			connectorServerCache.set(key, {});
+		} finally {
+			connectorServerPending.delete(key);
+		}
+	})();
+}
+
+/** Synchronous snapshot for the query path; `{}` until priming resolves. */
+function connectorServersSnapshot(): Record<string, unknown> {
+	const key = connectorScopeKey();
+	const ready = connectorServerCache.get(key);
+	if (ready) return ready;
+	// Always start (or continue) the live fetch — the cache is a head start, not
+	// a replacement, and the refresh keeps the next process current.
+	primeConnectorServers();
+	// Fall back to the previous run's inventory, read synchronously. This is the
+	// only thing that can populate turn 1 of a cold process, because priming
+	// cannot finish before the first query is built (vstack#870).
+	const cached = readCachedConnectors(key);
+	if (!cached) return {};
+	const servers = connectorMcpServers({ ok: true, complete: true, connectors: cached });
+	if (Object.keys(servers).length === 0) return {};
+	debug(`connectors: turn-1 declarations from cache — ${Object.keys(servers).join(", ")}`);
+	return servers;
+}
+
 // 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.
@@ -1239,10 +1396,11 @@ export default function (pi: ExtensionAPI) {
 
 	// --- Provider ---
 	//
-	// 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).
+	// Native registration (pi >=0.81): register unconditionally; the provider's
+	// own auth check/resolve report whether Claude credentials exist, so pi
+	// hides claude-bridge models while no account is connected and shows them
+	// when one appears. session_start and pre-spawn re-upsert the provider to
+	// force pi's availability recompute at those boundaries.
 	//
 	// applyProviderRegistration also claims the primary-instance token (first
 	// load wins) and enforces the multi-instance guard: a non-primary subagent