@vanillagreen/pi-claude-bridge 1.8.0 → 2.0.0

package/src/models.ts

@@ -3,15 +3,19 @@
 // Extracted from index.ts so tests can import without activating the extension.
 
 export const FABLE_MODEL_ID = "claude-fable-5";
+// Opus 4.8 is both a selectable model and the safety-fallback target for the two
+// primaries whose classifiers can decline a turn (Fable 5, Opus 5).
 export const FABLE_FALLBACK_MODEL_ID = "claude-opus-4-8";
+export const OPUS_5_MODEL_ID = "claude-opus-5";
 export const SONNET_5_MODEL_ID = "claude-sonnet-5";
 
 export function fallbackModelForPrimaryModel(modelId: string): string | undefined {
-	return modelId === FABLE_MODEL_ID ? FABLE_FALLBACK_MODEL_ID : undefined;
+	return modelId === FABLE_MODEL_ID || modelId === OPUS_5_MODEL_ID ? FABLE_FALLBACK_MODEL_ID : undefined;
 }
 
 export const MODEL_IDS_IN_ORDER = [
 	FABLE_MODEL_ID,
+	OPUS_5_MODEL_ID,
 	FABLE_FALLBACK_MODEL_ID,
 	"claude-opus-4-7",
 	"claude-opus-4-6",
@@ -40,6 +44,15 @@ const FALLBACK_MODELS: Record<string, BridgeModelMetadata> = {
 		contextWindow: 1000000,
 		maxTokens: 128000,
 	},
+	[OPUS_5_MODEL_ID]: {
+		id: OPUS_5_MODEL_ID,
+		name: "Claude Opus 5",
+		reasoning: true,
+		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
+		input: ["text", "image"],
+		contextWindow: 1000000,
+		maxTokens: 128000,
+	},
 	[FABLE_FALLBACK_MODEL_ID]: {
 		id: FABLE_FALLBACK_MODEL_ID,
 		name: "Claude Opus 4.8",
@@ -53,12 +66,20 @@ const FALLBACK_MODELS: Record<string, BridgeModelMetadata> = {
 		id: SONNET_5_MODEL_ID,
 		name: "Claude Sonnet 5",
 		reasoning: true,
+		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
 		input: ["text", "image"],
 		contextWindow: 1000000,
 		maxTokens: 128000,
 	},
 };
 
+// Human label for the safety-fallback notice. Every id that participates in a
+// fallbackModelForPrimaryModel pairing has an entry above; the raw id is the
+// last-resort label so an unmapped pairing still reads sensibly.
+export function modelDisplayName(modelId: string): string {
+	return FALLBACK_MODELS[modelId]?.name ?? modelId;
+}
+
 // Project pi-ai's model entries down to the fields pi's registerProvider expects,
 // keep MODEL_IDS_IN_ORDER ordering, and fill bridge-owned future IDs when pi-ai
 // has not shipped metadata for them yet. Unknown missing IDs are still dropped.

package/src/native-provider.ts

@@ -0,0 +1,89 @@
+// Native pi >=0.81 provider construction (bridge 2.x).
+//
+// Bridge 1.x could not register unconditionally: pi's legacy
+// ModelRegistry.hasConfiguredAuth() treated the dummy `apiKey: "not-used"` as
+// "configured", so the models looked connected while every request failed at
+// spawn. 1.x therefore gated register/unregister on real credential presence
+// (decideRegistration). The native Provider form inverts that: the provider is
+// ALWAYS registered, and `auth.apiKey.check/resolve` report configured-ness
+// from the same existence-only probes, so pi itself hides claude-bridge models
+// while no Claude credentials are present and shows them when they appear.
+//
+// What the native form does NOT change (see DEVELOPMENT.md "Provider
+// registration"): the process-global primary-instance/stream-guard tokens stay
+// (pi's registerNativeProvider is replace-by-id, so an unguarded subagent
+// re-registration would still swap in its own streamSimple), and the pre-spawn
+// credential fail-fast in streamSimple stays (a mid-session logout must fail
+// the turn with an actionable message even if the picker snapshot is stale).
+//
+// SECURITY: like auth-presence.ts, this module only reports credential
+// EXISTENCE. resolve() hands pi the same dummy key the legacy config carried —
+// the Claude Code subprocess does its own authentication; pi never needs a
+// real secret, so none is read or exposed.
+
+import { hasClaudeCredentials } from "./auth-presence.js";
+import { PROVIDER_ID } from "./convert.js";
+
+export const NATIVE_PROVIDER_UNSUPPORTED_MESSAGE =
+	"Claude bridge 2.x requires pi >= 0.81 (native provider API). Upgrade the host pi, or pin @vanillagreen/pi-claude-bridge@1.x.";
+
+/** pi-ai gained createProvider in 0.81 alongside the object-form
+ *  registerProvider; its presence is the capability signal for both. */
+export function supportsNativeProvider(piAi: unknown): boolean {
+	return typeof (piAi as { createProvider?: unknown })?.createProvider === "function";
+}
+
+/** Auth source label for pi's status UI, chosen by the same existence-only
+ *  probes hasClaudeCredentials uses. Never reads credential contents. */
+export function claudeAuthSourceLabel(env: NodeJS.ProcessEnv = process.env): string {
+	if (env.CLAUDE_CODE_OAUTH_TOKEN?.trim()) return "CLAUDE_CODE_OAUTH_TOKEN";
+	if (env.ANTHROPIC_API_KEY?.trim()) return "ANTHROPIC_API_KEY";
+	if (env.ANTHROPIC_AUTH_TOKEN?.trim()) return "ANTHROPIC_AUTH_TOKEN";
+	return "Claude Code login";
+}
+
+/**
+ * Build the Provider object for pi.registerProvider(provider).
+ *
+ * `piAi` is the HOST's pi-ai namespace (the bundle externalizes it), passed in
+ * rather than imported so a pre-0.81 host fails the supportsNativeProvider()
+ * check with a clear message instead of crashing module load on a missing
+ * named export. `env` is bindable for tests; the credential probes themselves
+ * run at check/resolve CALL time, so a login/logout between calls is seen.
+ */
+export function buildNativeProvider(
+	piAi: unknown,
+	models: Array<Record<string, unknown>>,
+	streamSimple: (...args: unknown[]) => unknown,
+	env: NodeJS.ProcessEnv = process.env,
+): unknown {
+	if (!supportsNativeProvider(piAi)) throw new Error(NATIVE_PROVIDER_UNSUPPORTED_MESSAGE);
+	// The legacy config path stamped provider/api/baseUrl onto each model during
+	// composition; createProvider passes models through verbatim, so stamp here.
+	const stamped = models.map((model) => ({ api: "claude-bridge", baseUrl: "claude-bridge", provider: PROVIDER_ID, ...model }));
+	// The Claude Code subprocess router IS the implementation for both stream
+	// entry points — there is no raw-API shape to dispatch to.
+	const streams = {
+		stream: streamSimple,
+		streamSimple,
+	};
+	return (piAi as { createProvider: (input: unknown) => unknown }).createProvider({
+		id: PROVIDER_ID,
+		name: "Claude (Claude Code)",
+		baseUrl: "claude-bridge",
+		auth: {
+			apiKey: {
+				name: "Claude Code credentials",
+				// check() exists so pi's availability pass never has to call
+				// resolve(): both are existence-only, but check is the documented
+				// side-effect-free probe.
+				check: async () => (hasClaudeCredentials(env) ? { type: "api_key" as const, source: claudeAuthSourceLabel(env) } : undefined),
+				resolve: async () => (hasClaudeCredentials(env)
+					? { auth: { apiKey: "not-used" }, source: claudeAuthSourceLabel(env) }
+					: undefined),
+			},
+		},
+		models: stamped,
+		api: streams,
+	});
+}

package/src/query-state.ts

@@ -14,6 +14,60 @@ export interface PendingToolCall {
 	resolve: (result: McpResult) => void;
 }
 
+// Why pending MCP handlers were drained without a real tool result. A drained
+// handler is waiting on a result pi will now never deliver, so the drain must
+// resolve as an error — never as a successful result whose text merely says the
+// turn died, which a consumer cannot tell apart from a tool that genuinely
+// returned that string. The cause is carried because an abort, an idle timeout,
+// and a plain end-with-stragglers are different things to act on.
+export type ToolCallDrainCause = "abort" | "stream-idle-timeout" | "query-end";
+
+const DRAIN_CAUSE_TEXT: Record<ToolCallDrainCause, string> = {
+	"abort": "the turn was aborted",
+	"stream-idle-timeout": "the Claude Code stream went idle and the turn timed out",
+	"query-end": "the query ended",
+};
+
+export function interruptedToolCallResult(cause: ToolCallDrainCause): McpResult {
+	return {
+		content: [{ type: "text", text: `Claude bridge: ${DRAIN_CAUSE_TEXT[cause]} before this tool call's result was delivered. The call did not complete and produced no output.` }],
+		isError: true,
+	};
+}
+
+// Precedence matches the forceRotate expression at the query-teardown site: an
+// explicit abort (pi's signal or our own abort handler) outranks a stream-idle
+// timeout, which outranks a plain end with stragglers.
+export function toolCallDrainCause(flags: { wasAborted?: boolean; signalAborted?: boolean; streamIdleTimedOut?: boolean }): ToolCallDrainCause {
+	if (flags.wasAborted || flags.signalAborted) return "abort";
+	if (flags.streamIdleTimedOut) return "stream-idle-timeout";
+	return "query-end";
+}
+
+/** Resolves every handler still waiting on `queryCtx` with an error result naming
+ *  `cause`, clears the map, and returns how many were drained. Scoped to the one
+ *  context it is given — never touches a sibling or parent query's handlers. */
+export function drainPendingToolCalls(queryCtx: QueryContext, cause: ToolCallDrainCause): number {
+	const drained = queryCtx.pendingToolCalls.size;
+	if (drained === 0) return 0;
+	const result = interruptedToolCallResult(cause);
+	for (const pending of queryCtx.pendingToolCalls.values()) pending.resolve(result);
+	queryCtx.pendingToolCalls.clear();
+	return drained;
+}
+
+/** One connector call's audit state for the life of a query. `recorded` means an
+ *  entry for it has already been appended (or attempted), so neither a re-yielded
+ *  result nor the teardown flush can record it twice. */
+export interface ConnectorCallAuditState {
+	name: string;
+	/** The child session that issued it, captured when the call was seen — a
+	 *  continuation query gets a new one, and a call is audited against the session
+	 *  that actually made it. */
+	childSessionId?: string;
+	recorded: boolean;
+}
+
 export interface TurnToolCallRecord {
 	id: string;
 	toolName: string;
@@ -25,6 +79,12 @@ export interface ClaimedToolCall {
 	match: "tool-args" | "tool-name" | "none";
 	ambiguous: boolean;
 	available: number;
+	/** True when the claim went through the sole-same-name fallback even though
+	 *  the recorded call had (different) arguments. Recorded args come from the
+	 *  raw streamed input while the handler receives the MCP server's
+	 *  schema-validated copy, so a benign divergence (stripped unknown key,
+	 *  applied default) must not strand the call — but it is worth a diagnostic. */
+	argsMismatch?: boolean;
 }
 
 export interface ToolResultProgress {
@@ -90,6 +150,16 @@ export class QueryContext {
 	pendingResults = new Map<string, McpResult>();
 	turnToolCallIds: string[] = [];
 	turnToolCalls: TurnToolCallRecord[] = [];
+	/**
+	 * id → Pi tool name for every tool call this QUERY recorded, across all child
+	 * messages. Deliberately NOT cleared by resetToolTracking: per-message tracking
+	 * resets at every message boundary, but `pendingResults` is query-scoped, so a
+	 * result stranded there outlives the message that named it. Without this map a
+	 * teardown report can only say "1 queued" with empty toolNames and 0/0
+	 * counters — which is exactly the unactionable record the 2026-07-28 diag log
+	 * showed. Bounded by the number of tool calls in one query.
+	 */
+	queryToolNames = new Map<string, string>();
 	claimedToolCallIds = new Set<string>();
 	deliveredToolResultIds = new Set<string>();
 	resolvedToolResultIds = new Set<string>();
@@ -97,6 +167,83 @@ export class QueryContext {
 	reportedToolResultMismatch = false;
 	deferredUserMessages: string[] = [];
 	handledTerminalError = false;
+	/** Armed grace timer for ending a tool_use turn whose terminal stream events
+	 *  (message_delta/message_stop) never arrive. The normal path ends the turn at
+	 *  message_stop, AFTER message_delta delivered the real output-token count;
+	 *  this is the deadlock backstop for streams that go silent instead. Managed
+	 *  by schedule/cancelToolUseTurnEnd in assistant-stream.ts. */
+	scheduledToolUseEnd: { stream: unknown; timer: ReturnType<typeof setTimeout> } | null = null;
+
+	// Tool calls the CHILD executes itself (claude.ai connectors — see
+	// isChildExecutedTool). Deliberately NOT in turnToolCalls/turnToolCallIds:
+	// those track calls Pi owes a result for, and Pi owes nothing here. Kept only
+	// so the child's real result can be recognized when it comes back on the SDK's
+	// `user` message, and so the streamed block's deltas can be skipped silently
+	// instead of logging as "unmatched" (which reads like a bug).
+	/** tool_use id → raw SDK tool name. */
+	childExecutedToolCalls = new Map<string, string>();
+	/**
+	 * The same calls, for the connector-call audit trail (see connector-audit.ts).
+	 *
+	 * Query-scoped and deliberately NOT cleared by resetToolTracking: that runs at
+	 * every child message boundary, and a call issued in one child message is only
+	 * reconciled after that message ends. Clearing it there would make an abandoned
+	 * call unrecordable at teardown — which is the one case the trail exists for.
+	 */
+	connectorCallAudit = new Map<string, ConnectorCallAuditState>();
+	/** Claude Code session id for this query, from the SDK's `system` init message.
+	 *  Undefined until it arrives; the audit trail omits the field rather than
+	 *  guessing. */
+	childSessionId: string | undefined;
+	/** Anthropic content-block indexes of the current assistant message that carry
+	 *  a child-executed tool_use. Scoped to one message: cleared at message_start,
+	 *  and an index is released as soon as a new block starts there. */
+	childExecutedStreamIndexes = new Set<number>();
+
+	// Usage accounting for a Pi turn that spans SEVERAL child assistant messages.
+	//
+	// Every child message is a separate billed API call, and each reports its own
+	// counters — `message_start`/`message_delta` REPLACE rather than accumulate. A
+	// Pi turn used to end at the first tool call, so one Pi message meant one child
+	// message and replacing was right. A turn containing a child-executed connector
+	// call now keeps running across the child's follow-up messages, so replacing
+	// would silently drop everything the earlier ones billed (measured: 55,685
+	// cache-write tokens lost on a single connector turn).
+	//
+	// So: `turnUsageCarry` holds the totals of the child messages already COMPLETE
+	// in this Pi turn, `currentMessageUsage` holds the one in flight, and the Pi
+	// message reports their sum. Summing is the correct model for input and cache
+	// too — each call bills its own.
+	turnUsageCarry = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+	currentMessageUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+	/** Anthropic id of the child message `currentMessageUsage` describes. */
+	currentMessageId: string | undefined;
+
+	/**
+	 * Declare which child message the following usage belongs to, banking the
+	 * previous one's counters into the turn total.
+	 *
+	 * Keyed on the MESSAGE ID rather than on the call site, because both paths
+	 * that see a message boundary can fire for the SAME message: `message_start`
+	 * arrives on the stream, and the SDK then yields that message again in
+	 * completed form. Banking per call site double-counted whenever the completed
+	 * copy took the no-stream-events branch — which it does whenever a message
+	 * produced no content blocks, since `turnSawStreamEvent` only tracks those.
+	 *
+	 * With no id on either side (older/streamless shapes) this degrades to
+	 * banking on every call, which is what each caller means when it cannot
+	 * prove otherwise.
+	 */
+	beginChildMessage(messageId?: unknown): void {
+		const id = typeof messageId === "string" && messageId.length > 0 ? messageId : undefined;
+		if (id !== undefined && id === this.currentMessageId) return; // same message
+		this.turnUsageCarry.input += this.currentMessageUsage.input;
+		this.turnUsageCarry.output += this.currentMessageUsage.output;
+		this.turnUsageCarry.cacheRead += this.currentMessageUsage.cacheRead;
+		this.turnUsageCarry.cacheWrite += this.currentMessageUsage.cacheWrite;
+		this.currentMessageUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+		this.currentMessageId = id;
+	}
 
 	// Per-turn (reset together)
 	turnOutput: AssistantMessage | null = null;
@@ -121,6 +268,17 @@ export class QueryContext {
 		this.turnSawStreamEvent = false;
 		this.turnSawToolCall = false;
 		this.handledTerminalError = false;
+		// A new pi message means the previous turn's stream is done with; an armed
+		// end-timer for it must not fire into the new turn's state.
+		if (this.scheduledToolUseEnd) {
+			clearTimeout(this.scheduledToolUseEnd.timer);
+			this.scheduledToolUseEnd = null;
+		}
+		// Usage accounting IS per-Pi-message, so it resets with the message it
+		// describes — unlike tool-call tracking below.
+		this.turnUsageCarry = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+		this.currentMessageUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+		this.currentMessageId = undefined;
 		// Tool-call tracking is NOT reset here — it persists across the
 		// tool-result delivery callback for the same assistant message. New
 		// assistant messages call resetToolTracking() explicitly.
@@ -134,10 +292,32 @@ export class QueryContext {
 		this.resolvedToolResultIds.clear();
 		this.unmatchedToolResultIds.clear();
 		this.reportedToolResultMismatch = false;
+		this.childExecutedToolCalls.clear();
+		this.childExecutedStreamIndexes.clear();
+	}
+
+	/** Note a tool_use the child runs itself. `streamIndex` is present only on the
+	 *  streamed path, where later deltas/stops for that block must be skipped. */
+	noteChildExecutedToolCall(id: string | undefined, rawName: string, streamIndex?: number): void {
+		if (id) {
+			this.childExecutedToolCalls.set(id, rawName);
+			// Both emission paths can see the same call (streamed block, then the
+			// SDK's completed copy), so never overwrite an existing audit state —
+			// that would resurrect one already recorded.
+			if (!this.connectorCallAudit.has(id)) {
+				this.connectorCallAudit.set(id, {
+					name: rawName,
+					...(this.childSessionId ? { childSessionId: this.childSessionId } : {}),
+					recorded: false,
+				});
+			}
+		}
+		if (typeof streamIndex === "number") this.childExecutedStreamIndexes.add(streamIndex);
 	}
 
 	recordToolCall(id: string | undefined, toolName: string, args: Record<string, unknown> = {}): void {
 		if (!id) return;
+		this.queryToolNames.set(id, toolName);
 		if (!this.turnToolCallIds.includes(id)) this.turnToolCallIds.push(id);
 		const existing = this.turnToolCalls.find((call) => call.id === id);
 		if (existing) {
@@ -166,22 +346,57 @@ export class QueryContext {
 		let match: ClaimedToolCall["match"] = "none";
 		let ambiguous = false;
 
+		let argsMismatch = false;
 		if (exact.length > 0) {
 			chosen = exact[0];
 			match = "tool-args";
 			ambiguous = exact.length > 1;
-		} else if (byName.length === 1 && !hasRecordedArgs(byName[0].arguments)) {
-			// The SDK can invoke the MCP handler after content_block_start but
-			// before input_json_delta/content_block_stop finalizes arguments.
-			// Falling back to the sole same-name, argument-less call preserves that
-			// race without ever claiming a different tool type.
+		} else if (byName.length === 1) {
+			// A single unclaimed call of this tool type is the only call this
+			// handler can possibly belong to, so claim it even when the recorded
+			// arguments differ. Two known benign sources of divergence:
+			//   - the SDK can invoke the handler after content_block_start but
+			//     before input_json_delta/content_block_stop finalizes arguments,
+			//     so the record still holds a partial parse;
+			//   - the handler receives the MCP server's schema-VALIDATED copy of
+			//     the input (zod may strip unknown keys or apply defaults) while
+			//     the record holds the raw streamed input.
+			// Refusing here stranded the call outright: the handler errored into
+			// the child while pi's real result sat queued forever (diag log
+			// 2026-07-28, `edit` with argKeys [edits, path] on both sides). A
+			// same-type sole-candidate claim is strictly safer than that. With
+			// SEVERAL same-name candidates and no exact match we still refuse —
+			// cross-pairing two live calls is the one outcome worse than failing.
 			chosen = byName[0];
 			match = "tool-name";
+			argsMismatch = hasRecordedArgs(byName[0].arguments);
 		}
 
 		if (!chosen) return { match: "none", ambiguous: false, available: unclaimed.length };
 		this.claimedToolCallIds.add(chosen.id);
-		return { toolCallId: chosen.id, match, ambiguous, available: unclaimed.length };
+		return { toolCallId: chosen.id, match, ambiguous, available: unclaimed.length, ...(argsMismatch ? { argsMismatch } : {}) };
+	}
+
+	/**
+	 * Drain results still queued in `pendingResults` and report what was dropped.
+	 *
+	 * Called at a child MESSAGE boundary (message_start / the no-stream-events
+	 * assistant fallback): by then the child has necessarily received every tool
+	 * result for the previous message — a handler that matched resolved its result
+	 * directly or from this queue, and one that never matched already returned an
+	 * error. Whatever is still queued therefore belongs to a call whose handler
+	 * gave up, and no consumer will ever come for it. Left in place, each entry
+	 * poisons every later mismatch report for the whole query (queued>0 with 0/0
+	 * counters and no tool names) and forces a session rebuild per turn.
+	 */
+	takeStaleQueuedResults(): Array<{ id: string; toolName: string }> {
+		if (this.pendingResults.size === 0) return [];
+		const stale = [...this.pendingResults.keys()].map((id) => ({
+			id,
+			toolName: this.queryToolNames.get(id) ?? "unknown",
+		}));
+		this.pendingResults.clear();
+		return stale;
 	}
 
 	markToolResultDelivered(id: string | undefined): void {
@@ -210,9 +425,21 @@ export class QueryContext {
 		const unresolvedIds = expectedIds.filter((id) => !this.resolvedToolResultIds.has(id));
 		const affectedIds = new Set([...missingDeliveredIds, ...unresolvedIds, ...waitingIds, ...queuedIds, ...unmatchedResultIds]);
 		const counts = new Map<string, number>();
-		for (const call of this.turnToolCalls) {
-			if (affectedIds.size > 0 && !affectedIds.has(call.id)) continue;
-			counts.set(call.toolName, (counts.get(call.toolName) ?? 0) + 1);
+		if (affectedIds.size > 0) {
+			// Name the affected ids from the query-scoped map, not just this
+			// message's records: a queued straggler from an earlier child message is
+			// exactly the case a mismatch report exists for, and this message's
+			// turnToolCalls no longer knows it.
+			for (const id of affectedIds) {
+				const name = this.queryToolNames.get(id)
+					?? this.turnToolCalls.find((call) => call.id === id)?.toolName
+					?? "unknown";
+				counts.set(name, (counts.get(name) ?? 0) + 1);
+			}
+		} else {
+			for (const call of this.turnToolCalls) {
+				counts.set(call.toolName, (counts.get(call.toolName) ?? 0) + 1);
+			}
 		}
 		return {
 			expectedIds,
@@ -256,6 +483,30 @@ export function popContext(): void {
 	_ctx = contextStack.pop()!;
 }
 
+/** Pop the context that belongs to ONE specific query, wherever it sits.
+ *
+ *  The common case is `target === ctx()` and this is exactly popContext(). The
+ *  reason this exists: a reentrant parent query can end ABNORMALLY (abort, child
+ *  process death) while its own subagent's context is still pushed above it. A
+ *  bare popContext() there would discard the live grandchild's context and
+ *  merge the wrong deferred messages. Instead, splice `target` out of the stack
+ *  and hand its deferred messages to its own parent (the element below it), so
+ *  the still-live contexts above keep their positions and later pops restore
+ *  the correct lineage. Returns false when `target` is nowhere in the state —
+ *  already popped — so callers can treat that as "someone else tore this down". */
+export function popContextFor(target: QueryContext): boolean {
+	if (_ctx === target) {
+		popContext();
+		return true;
+	}
+	const idx = contextStack.indexOf(target);
+	if (idx < 0) return false;
+	const parent = idx > 0 ? contextStack[idx - 1] : undefined;
+	parent?.deferredUserMessages.push(...target.deferredUserMessages);
+	contextStack.splice(idx, 1);
+	return true;
+}
+
 // Test-only: drop all state so test files can start from a clean module.
 // Not called from production.
 export function resetStack(): void {

package/src/query-teardown.ts

@@ -0,0 +1,45 @@
+// End-of-query teardown, extracted from streamClaudeAgentSdk's .finally so it
+// operates on the ONE context captured at query start — never the live ctx().
+// The two only differ while a reentrant (subagent) context is pushed, which is
+// exactly when a parent query ending abnormally (abort, child process death)
+// used to run this against the subagent's state: the parent's drain, audit
+// flush, and activeQuery clear were skipped, leaking its pending MCP handlers.
+
+import { reportToolResultMismatch } from "./bridge-state.js";
+import { flushConnectorCallAudit } from "./connector-audit.js";
+import { debug } from "./debug.js";
+import { drainPendingToolCalls, popContextFor, type QueryContext, type ToolCallDrainCause } from "./query-state.js";
+
+/** Tear down `queryCtx` after its SDK query settled. No-ops when the query is
+ *  no longer the context's active one (a continuation replaced it, or teardown
+ *  already ran). Returns true when teardown actually ran. */
+export function teardownQuery(
+	queryCtx: QueryContext,
+	sdkQuery: unknown,
+	cause: ToolCallDrainCause,
+	cwd: string,
+	isReentrant: boolean,
+): boolean {
+	if (queryCtx.activeQuery !== sdkQuery) return false;
+	reportToolResultMismatch(queryCtx, "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(queryCtx, cause);
+	if (drained > 0) debug(`provider: query teardown drained ${drained} waiting MCP handler(s) as errors (cause=${cause})`);
+	queryCtx.pendingResults.clear();
+
+	// Same idea for calls the CHILD owned: one whose result never came back
+	// is recorded as unobserved rather than left silent, so an answer in the
+	// transcript is never the only evidence a connector call was made.
+	const unobserved = flushConnectorCallAudit(queryCtx, cause);
+	if (unobserved > 0) debug(`provider: query teardown recorded ${unobserved} connector call(s) with no observed result (cause=${cause})`);
+
+	if (isReentrant) {
+		// Merges deferred messages and restores/repairs the stack. popContextFor
+		// (not popContext): a live subagent context may sit above this one.
+		if (!popContextFor(queryCtx)) debug("provider: query teardown found context already popped; skipping pop");
+	} else {
+		queryCtx.activeQuery = null;
+	}
+	return true;
+}

package/src/rate-limit.ts

@@ -0,0 +1,95 @@
+import { USAGE_LIMIT_ERROR_PREFIXES } from "@anthropic-ai/claude-agent-sdk";
+
+export const RATE_LIMIT_AUTO_RESUME_EVENT = "vstack:rate-limit";
+export const RATE_LIMIT_TOKEN = "\x1b[31m[rate-limit]\x1b[39m";
+
+// The SDK export is @alpha — degrade to "no match" (pre-0.3.220 behavior) if a
+// future release drops it, instead of crashing message classification.
+const USAGE_LIMIT_PREFIXES: readonly string[] = Array.isArray(USAGE_LIMIT_ERROR_PREFIXES as unknown)
+	? USAGE_LIMIT_ERROR_PREFIXES
+	: [];
+
+function coerceMessageText(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (value instanceof Error) return value.message;
+	try { return JSON.stringify(value ?? ""); }
+	catch { return String(value); }
+}
+
+/** Narrow test: this message is about EXTRA usage specifically — the paid
+ *  beyond-plan pool the /extra-usage helper flow can enable. */
+export function isExtraUsageRequiredMessage(value: unknown): boolean {
+	return /extra[-\s]?usage|overage|extra usage billing|extra usage credits|1M context/i.test(coerceMessageText(value));
+}
+
+/** Broad test: any "a usage limit was genuinely reached" message, matched
+ *  against the CLI's own copy (SDK `USAGE_LIMIT_ERROR_PREFIXES`, e.g. "You've
+ *  hit your weekly limit…"). Substring rather than prefix match because the
+ *  text usually arrives embedded in a result payload's errors array. */
+export function isUsageLimitMessage(value: unknown): boolean {
+	const text = coerceMessageText(value);
+	return USAGE_LIMIT_PREFIXES.some((prefix) => text.includes(prefix));
+}
+
+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;
+}
+
+/** Epoch milliseconds from an SDK reset timestamp, or undefined.
+ *  `SDKRateLimitInfo.resetsAt` is a bare number in epoch SECONDS (measured:
+ *  treating it as ms rendered "resets Jan 21, 1970" for a Jul 2026 reset).
+ *  The unit is undocumented, so detect by magnitude — epoch seconds stay below
+ *  1e12 until the year 33658, epoch ms passed 1e12 in 2001 — and accept ISO
+ *  strings for older payloads. */
+export function resetTimestampMs(value: unknown): number | undefined {
+	let parsed = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
+	if (!Number.isFinite(parsed)) return undefined;
+	if (typeof value === "number" && Math.abs(parsed) < 1e12) parsed *= 1000;
+	return parsed;
+}
+
+export function formatResetTimestamp(value: unknown): string {
+	const parsed = resetTimestampMs(value);
+	if (parsed === undefined) 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.`;
+}