@vanillagreen/pi-claude-bridge 1.6.2 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillagreen/pi-claude-bridge",
-  "version": "1.6.2",
+  "version": "1.9.0",
   "description": "Pi provider bridge that runs Claude Code through the Claude Agent SDK, with opt-in forwarding for Pi prompt context.",
   "type": "module",
   "keywords": [
@@ -142,8 +142,8 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.158",
-    "@anthropic-ai/sdk": "0.93.0",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.215",
+    "@anthropic-ai/sdk": "^0.112.4",
     "cc-session-io": "^0.3.1",
     "change-case": "^5.4.4"
   },
@@ -152,15 +152,15 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.75.0",
-    "@earendil-works/pi-coding-agent": "^0.75.0",
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
     "@types/node": "^24.3.0",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=bundle/index.js --external:@earendil-works/pi-ai --external:@earendil-works/pi-coding-agent",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=bundle/index.js --external:@earendil-works/pi-ai --external:@earendil-works/pi-coding-agent && esbuild src/connector-inventory.ts --bundle --platform=node --format=esm --target=node22 --outfile=bundle/connector-inventory.js",
     "prepack": "npm run build",
     "test:unit": "node --import tsx --test tests/unit-*.mjs",
     "test": "set -a && [ -f .env.test ] && . ./.env.test; set +a && npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs",
@@ -198,5 +198,9 @@
     "@earendil-works/pi-coding-agent": {
       "optional": true
     }
+  },
+  "exports": {
+    ".": "./bundle/index.js",
+    "./connector-inventory": "./bundle/connector-inventory.js"
   }
 }

package/src/agents-md.ts

@@ -2,20 +2,28 @@
 //
 // Pi uses AGENTS.md for long-lived instructions; Claude Code reads the same
 // content under "# CLAUDE.md". We walk up from cwd looking for AGENTS.md,
-// fall back to ~/.pi/agent/AGENTS.md, and rewrite pi-specific references
+// fall back to <piUserDir>/AGENTS.md (~/.pi/agent/AGENTS.md unless
+// PI_CODING_AGENT_DIR points elsewhere), and rewrite pi-specific references
 // (~/.pi, .pi/, .pi, pi) to their Claude Code equivalents so any paths or
 // references in the file still resolve inside the CC subprocess.
+//
+// In isolated mode (CLAUDE_BRIDGE_ISOLATED=1), all AGENTS.md discovery is
+// disabled. Embedding hosts provide their instruction surface explicitly.
 
 import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
 import { dirname, join, resolve } from "path";
+import { isolatedFromEnv, piUserDir } from "./config.js";
 
-const GLOBAL_AGENTS_PATH = join(homedir(), ".pi", "agent", "AGENTS.md");
+function globalAgentsPath(): string {
+	return join(piUserDir(), "AGENTS.md");
+}
 
 export function resolveAgentsMdPath(): string | undefined {
+	if (isolatedFromEnv()) return undefined;
 	const fromCwd = findAgentsMdInParents(process.cwd());
 	if (fromCwd) return fromCwd;
-	if (existsSync(GLOBAL_AGENTS_PATH)) return GLOBAL_AGENTS_PATH;
+	const globalPath = globalAgentsPath();
+	if (existsSync(globalPath)) return globalPath;
 	return undefined;
 }
 

package/src/assistant-stream.ts

@@ -0,0 +1,307 @@
+import { calculateCost, type AssistantMessage, type Model } from "@earendil-works/pi-ai";
+import { type SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { debug } from "./debug.js";
+import { ctx } from "./query-state.js";
+import { mapToolArgs, mapToolName } from "./tool-mapping.js";
+
+// --- 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}`);
+}
+
+// --- 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";
+	}
+}
+
+export function parsePartialJson(input: string, fallback: Record<string, unknown>): Record<string, unknown> {
+	if (!input) return fallback;
+	try { return JSON.parse(input); } catch { return fallback; }
+}
+
+export function ensureTurnStarted(): void {
+	if (!ctx().turnStarted && ctx().currentPiStream && ctx().turnOutput) {
+		ctx().currentPiStream!.push({ type: "start", partial: ctx().turnOutput });
+		ctx().turnStarted = true;
+	}
+}
+
+export 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;
+}
+
+export 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;
+	}
+}

package/src/auth-presence.ts

@@ -0,0 +1,158 @@
+// --- Claude credential presence (availability honesty) ---
+//
+// The bridge may only advertise claude-bridge models when the machine actually
+// has Claude credentials the Claude Agent SDK can authenticate with. Otherwise
+// pi's ModelRegistry.hasConfiguredAuth() would treat the dummy `apiKey:
+// "not-used"` as "configured" and the provider would look connected while every
+// request fails at spawn time.
+//
+// This module answers two pure questions used to gate registration:
+//   1. hasClaudeCredentials() — are real credentials present RIGHT NOW?
+//   2. decideRegistration()   — given credential presence + the primary-instance
+//      / stream-guard tokens, should we register / unregister / do nothing?
+//
+// SECURITY: this module only ever checks for the EXISTENCE of credentials — a
+// file's presence, an env var being non-empty, a settings key being a non-empty
+// string. It NEVER opens or logs `.credentials.json`, and where it must parse
+// `settings.json` (for apiKeyHelper) it reads only whether the key is a
+// non-empty string and never logs its value. Credential CONTENTS are never read
+// or logged.
+
+import { existsSync, readFileSync } from "fs";
+import { homedir, platform as osPlatform } from "os";
+import { join } from "path";
+
+/**
+ * Resolve the Claude config directory the same way the bundled cc-session-io
+ * (getClaudeDir) and Claude Code itself resolve it: an explicit
+ * CLAUDE_CONFIG_DIR wins, otherwise ~/.claude.
+ *
+ * Deliberate divergence from cc-session-io's plain `env ?? default`: we treat a
+ * SET-BUT-EMPTY/whitespace CLAUDE_CONFIG_DIR as unset and fall back to ~/.claude
+ * (an empty string would otherwise resolve credential probes to the process cwd
+ * root). The returned value is trimmed so downstream joins never carry stray
+ * whitespace.
+ */
+export function resolveClaudeConfigDir(env: NodeJS.ProcessEnv = process.env): string {
+	const configured = env.CLAUDE_CONFIG_DIR;
+	if (typeof configured === "string" && configured.trim().length > 0) return configured.trim();
+	return join(homedir(), ".claude");
+}
+
+function nonEmptyEnv(value: string | undefined): boolean {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+// Matches how Claude Code interprets its boolean provider-routing env flags:
+// only "1" / "true" (case-insensitive) enable them.
+function envTruthy(value: string | undefined): boolean {
+	const v = value?.trim().toLowerCase();
+	return v === "1" || v === "true";
+}
+
+/**
+ * True when `${configDir}/settings.json` exists, parses as JSON, and carries a
+ * non-empty `apiKeyHelper` string (an enterprise/custom auth command that
+ * produces a key). Parse/read errors are tolerated as "not present". The helper
+ * VALUE is never logged — only its presence/non-emptiness is used.
+ */
+function hasApiKeyHelper(configDir: string): boolean {
+	try {
+		const settingsPath = join(configDir, "settings.json");
+		if (!existsSync(settingsPath)) return false;
+		const parsed = JSON.parse(readFileSync(settingsPath, "utf8")) as { apiKeyHelper?: unknown };
+		return typeof parsed?.apiKeyHelper === "string" && parsed.apiKeyHelper.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * True when real Claude credentials are present in any location the Claude Agent
+ * SDK would authenticate from, WITHOUT reading credential contents. Checked in
+ * cheap-first order:
+ *   - env: non-empty CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY /
+ *     ANTHROPIC_AUTH_TOKEN, or any truthy cloud-provider routing flag the Claude
+ *     Code SDK recognizes — CLAUDE_CODE_USE_BEDROCK / _VERTEX / _FOUNDRY /
+ *     _ANTHROPIC_AWS / _MANTLE (such routing needs no local key file);
+ *   - `.credentials.json` in the resolved config dir (existence only — the file
+ *     is never opened; written mode 0600 by `claude login`);
+ *   - `settings.json` apiKeyHelper (presence only — see hasApiKeyHelper).
+ *
+ * PLATFORM ASYMMETRY: on macOS the `claude` CLI stores OAuth tokens in the login
+ * Keychain, NOT in `.credentials.json`, so file-absence is NOT evidence of
+ * logged-out and we cannot cheaply/safely probe the Keychain here. On darwin,
+ * when no other signal is present, we default to credentialed=true — preserving
+ * the pre-fix "always available" behavior for Mac subscription users. Honesty
+ * enforcement therefore applies on Linux/Windows, where `.credentials.json`
+ * existence is an observable, truthful proxy (empirically, `claude auth logout`
+ * unlinks it).
+ */
+export function hasClaudeCredentials(
+	env: NodeJS.ProcessEnv = process.env,
+	platform: NodeJS.Platform = osPlatform(),
+): boolean {
+	if (nonEmptyEnv(env.CLAUDE_CODE_OAUTH_TOKEN)) return true;
+	if (nonEmptyEnv(env.ANTHROPIC_API_KEY)) return true;
+	if (nonEmptyEnv(env.ANTHROPIC_AUTH_TOKEN)) return true;
+	if (envTruthy(env.CLAUDE_CODE_USE_BEDROCK)) return true;
+	if (envTruthy(env.CLAUDE_CODE_USE_VERTEX)) return true;
+	if (envTruthy(env.CLAUDE_CODE_USE_FOUNDRY)) return true;
+	if (envTruthy(env.CLAUDE_CODE_USE_ANTHROPIC_AWS)) return true;
+	if (envTruthy(env.CLAUDE_CODE_USE_MANTLE)) return true;
+
+	const configDir = resolveClaudeConfigDir(env);
+	if (existsSync(join(configDir, ".credentials.json"))) return true;
+	if (hasApiKeyHelper(configDir)) return true;
+
+	if (platform === "darwin") return true;
+
+	return false;
+}
+
+/**
+ * Snapshot of the inputs to a registration decision.
+ *
+ * The bridge keeps two process-global tokens (Symbol.for): a PRIMARY-instance
+ * token, claimed unconditionally by the first-loaded module instance, and the
+ * stream-guard token holding the registered instance's streamSimple. ONLY the
+ * primary instance may ever register/unregister or claim the stream guard — this
+ * prevents a subagent module reload (a fresh, non-primary instance) from
+ * stealing ownership and registering ITS streamSimple, which would split-brain
+ * the shared session/ctx and break tool-result delivery.
+ */
+export interface RegistrationState {
+	/** Does the machine have Claude credentials right now? */
+	credentialed: boolean;
+	/** Is THIS module instance the primary (first-loaded) instance? */
+	isPrimary: boolean;
+	/** Has this instance already registered (owns the stream guard)? */
+	registered: boolean;
+}
+
+export type RegistrationDecision = "register" | "unregister" | "noop";
+
+/**
+ * Pure decision for extension load, every session_start re-check, and the
+ * pre-spawn fail-fast path.
+ *
+ * Rules:
+ *   - Not the primary instance                    → NOOP (never touch registration).
+ *   - Primary + credentialed + not registered     → REGISTER (claim guard + register).
+ *   - Primary + credentialed + already registered → NOOP.
+ *   - Primary + uncredentialed                    → UNREGISTER (defensive).
+ *
+ * The uncredentialed primary always returns UNREGISTER rather than NOOP:
+ * pi.unregisterProvider is idempotent ("Has no effect if the provider was never
+ * registered"), and a defensive call is the ONLY way to retract a registration
+ * that survived a /reload — the ModelRegistry's registeredProviders is a
+ * process-lifetime Map and module reload does NOT clear it. (At extension-load
+ * time this defensive unregister only filters the pending-registration queue and
+ * cannot mutate the persistent registry; the authoritative retraction happens on
+ * the post-load session_start re-check — see applyProviderRegistration.)
+ */
+export function decideRegistration(state: RegistrationState): RegistrationDecision {
+	if (!state.isPrimary) return "noop";
+	if (state.credentialed) return state.registered ? "noop" : "register";
+	return "unregister";
+}