@vanillagreen/pi-claude-bridge 2.0.0 → 3.2.2

package/src/assistant-stream.ts

@@ -4,17 +4,16 @@ import { appendIntegrityEntry, safeNotify } from "./bridge-state.js";
 import { connectorResultByteSize, recordConnectorCallResult } from "./connector-audit.js";
 import { isChildExecutedTool } from "./connectors.js";
 import { debug, diagDump } from "./debug.js";
-import { ctx, type QueryContext } from "./query-state.js";
+import { ctx, failStrandedToolCall, type QueryContext } 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 {
+function updateUsage(output: AssistantMessage, usage: Record<string, number | undefined>, model: Model<any>, c: QueryContext): void {
 	// Anthropic reports per-message counters and RE-reports them as the message
 	// grows, so the in-flight message's figures are replaced, not added. What is
 	// added is every child message already finished in this Pi turn — see
 	// `turnUsageCarry` in query-state.ts for why a turn can span several.
-	const c = ctx();
 	const current = c.currentMessageUsage;
 	const carry = c.turnUsageCarry;
 	if (usage.input_tokens != null) current.input = usage.input_tokens;
@@ -88,10 +87,28 @@ export function finalizeCurrentStream(stopReason?: string, c: QueryContext = ctx
 const TOOL_USE_END_GRACE_MS = 1500;
 
 /** End the current pi stream as a tool_use turn boundary. Safe to call when the
- *  turn already ended (no-op). */
+ *  turn already ended (no-op). Every end path funnels here, so this is where
+ *  two invariants are enforced by construction (vstack#1469): a block still
+ *  carrying partialJson never ships — Pi executes the done message's content,
+ *  and truncated arguments must never execute — and every call that DOES ship
+ *  is stamped forwarded so no lagging replay can dispatch it again. */
 export function endToolUseTurn(c: QueryContext): void {
 	if (!c.currentPiStream || !c.turnOutput) return;
 	cancelScheduledToolUseEnd(c);
+	const partial = (c.turnOutput.content as Array<any>).filter((b) => b?.type === "toolCall" && "partialJson" in b);
+	if (partial.length > 0) {
+		const calls = partial.map((b) => ({ id: b.id, name: b.name }));
+		debug(`endToolUseTurn: pruning ${partial.length} still-partial tool call(s) — truncated arguments never execute:`, calls.map((entry) => `${entry.name} [${entry.id}]`).join(", "));
+		diagDump("partial_tool_calls_pruned", { count: partial.length, calls });
+		appendIntegrityEntry("partial_tool_calls_pruned", { count: partial.length, calls });
+		c.turnOutput.content = (c.turnOutput.content as Array<any>).filter((b) => !(b?.type === "toolCall" && "partialJson" in b));
+	}
+	// Every tool call Pi is about to execute from this turn is owed a result and
+	// must never be dispatched again: a lagging stream replays the same tool_use
+	// into the NEXT turn, whose per-message dedup cannot see it (vstack#1469).
+	for (const block of c.turnOutput.content as Array<{ type?: string; id?: unknown }>) {
+		if (block?.type === "toolCall" && typeof block.id === "string") c.forwardedToolCallIds.add(block.id);
+	}
 	c.turnOutput.stopReason = "toolUse";
 	c.currentPiStream.push({ type: "done", reason: "toolUse", message: c.turnOutput });
 	c.currentPiStream.end();
@@ -126,36 +143,39 @@ export function scheduleToolUseTurnEnd(c: QueryContext, action: () => void, sour
 }
 
 /**
- * Drop queued tool results that no handler can ever consume again, and say so
- * everywhere it matters. Runs at a child message boundary — by then every
- * handler for the previous message has either resolved (directly or from this
- * queue) or already returned an error, so anything still queued is the real
- * output of a call whose handler gave up. See takeStaleQueuedResults for why
- * leaving them queued poisoned every later mismatch report and forced a
- * session rebuild per turn.
+ * Park queued tool results whose handler has not fired by a child message
+ * boundary, and say so everywhere it matters. The boundary is where stale
+ * entries would start poisoning mismatch reports — but it does NOT prove the
+ * handler gave up: the SDK staggers handler invocations, and in the 2026-08-17
+ * deadlock session three of five parallel handlers fired after this point
+ * (vstack#1469). Parked results stay consumable through
+ * takeQueuedOrParkedResult; one that is never consumed belongs to a call the
+ * SDK abandoned client-side (permission denial), which is exactly what the
+ * notice describes.
  */
 export function reapStaleQueuedResults(c: QueryContext): void {
 	const stale = c.takeStaleQueuedResults();
 	if (stale.length === 0) return;
 	const names = stale.map((entry) => entry.toolName);
-	debug(`reapStaleQueuedResults: dropping ${stale.length} queued tool result(s) with no possible consumer:`, names.join(", "));
-	diagDump("stale_queued_tool_results_dropped", { count: stale.length, stale });
-	appendIntegrityEntry("stale_queued_tool_results_dropped", { count: stale.length, stale });
+	debug(`reapStaleQueuedResults: parked ${stale.length} early tool result(s) awaiting a late handler:`, names.join(", "));
+	diagDump("stale_queued_tool_results_parked", { count: stale.length, stale });
+	appendIntegrityEntry("stale_queued_tool_results_parked", { count: stale.length, stale });
 	safeNotify(
-		`Claude bridge: dropped ${stale.length} tool result(s) whose handler never matched (${names.slice(0, 6).join(", ")}${names.length > 6 ? ", …" : ""}). ` +
-		`The model saw an error for these calls and may retry them.`,
+		`Claude bridge: parked ${stale.length} early tool result(s) whose handler has not arrived (${names.slice(0, 6).join(", ")}${names.length > 6 ? ", …" : ""}). ` +
+		`A late handler can still consume them.`,
 		"warning",
 	);
 }
 
-export function updateTurnOutputModel(modelId: unknown): void {
-	const c = ctx();
+export function updateTurnOutputModel(modelId: unknown, c: QueryContext = ctx()): void {
 	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;
 }
 
+export const FINALIZE_MAX_REARMS = 3;
+
 /** Force-finalizes the current pi turn as a tool_use boundary when its terminal
  *  stream events never arrived (the grace-timer action armed by an MCP handler
  *  invocation — see scheduleToolUseTurnEnd).
@@ -164,29 +184,60 @@ export function updateTurnOutputModel(modelId: unknown): void {
  *  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. */
+ *  so end the pi stream like the `message_stop` path — with this handler's
+ *  schema-validated arguments, never a partial parse — after settling every
+ *  sibling whose handler has fired and giving a merely-lagging stream up to
+ *  FINALIZE_MAX_REARMS extra grace periods for the rest (vstack#1469).
+ *
+ *  The dead-stream guard is a backstop: the grace timer's own stream-identity
+ *  check means this normally never runs after the turn ended. The primary
+ *  recovery for a handler whose call missed its turn is the generation-guarded
+ *  drainStrandedToolCalls at the next provider callback. */
 export function finalizeToolUseTurnFromMcpInvocation(
 	queryCtx: QueryContext,
 	toolCallId: string,
 	toolName: string,
 	mappedArgs: Record<string, unknown>,
+	rearmCount = 0,
 ): void {
-	if (!queryCtx.currentPiStream || !queryCtx.turnOutput) return;
+	if (!queryCtx.currentPiStream || !queryCtx.turnOutput) {
+		// The turn ended without this call. An unforwarded handler here can never
+		// be answered — the yield that could have replayed its call was consumed
+		// against a null stream, and the dead-mark below suppresses any replay
+		// that has not happened yet. Failing it now is what turns the observed
+		// multi-hour session deadlock into one retryable error (vstack#1469).
+		if (failStrandedToolCall(queryCtx, toolCallId)) {
+			debug(`mcp handler: ${toolName} [${toolCallId}] stranded — turn ended before its call reached Pi; resolved with error`);
+			diagDump("tool_handler_stranded", { toolCallId, toolName, site: "finalize-no-stream" });
+			appendIntegrityEntry("tool_handler_stranded", { toolCallId, toolName, site: "finalize-no-stream" });
+		}
+		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));
+			// Stream ended before content_block_stop. The SDK invoked this handler
+			// with the COMPLETE schema-validated input, so the handler's copy is
+			// authoritative — the streamed partial JSON is by definition behind it.
+			// Settling from the partial is what forwarded `{}`-argument calls that
+			// Pi then executed and errored (vstack#1469), exactly the divergence
+			// the synthesize branch below never had.
+			block.arguments = mappedArgs;
 			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 if (queryCtx.forwardedToolCallIds.has(toolCallId) || queryCtx.deadToolCallIds.has(toolCallId)) {
+		// Pi already executed this call in an earlier turn (its result arrives or
+		// sits parked), or the handler was already failed — either way a second
+		// dispatch is the one outcome worse than waiting. Do NOT return: this
+		// firing consumed the stream's only grace timer, so the current turn's own
+		// blocks must still be settled and the turn still ended below, or a turn
+		// that loses its terminal events afterwards has no backstop left and Pi
+		// sits busy until manual abort.
+		debug(`mcp handler: ${toolName} [${toolCallId}] already ${queryCtx.forwardedToolCallIds.has(toolCallId) ? "forwarded" : "dead"} — not re-emitting`);
 	} else {
 		// The invocation can arrive before the tool_use is streamed at all
 		// (observed after a tool-result+steer provider call reset the turn):
@@ -198,6 +249,46 @@ export function finalizeToolUseTurnFromMcpInvocation(
 		queryCtx.currentPiStream.push({ type: "toolcall_start", contentIndex: idx, partial: queryCtx.turnOutput });
 		queryCtx.currentPiStream.push({ type: "toolcall_end", contentIndex: idx, toolCall: block, partial: queryCtx.turnOutput });
 	}
+	// Settle every OTHER still-partial block whose handler has fired: each
+	// waiting handler carries the authoritative args for its own call.
+	for (let i = 0; i < queryCtx.turnBlocks.length; i++) {
+		const sibling = queryCtx.turnBlocks[i] as any;
+		if (sibling.type !== "toolCall" || !("partialJson" in sibling)) continue;
+		const waiting = queryCtx.pendingToolCalls.get(sibling.id);
+		if (!waiting) continue;
+		sibling.arguments = waiting.args;
+		queryCtx.updateToolCallArgs(sibling.id, sibling.arguments);
+		delete sibling.partialJson;
+		delete sibling.index;
+		queryCtx.currentPiStream.push({ type: "toolcall_end", contentIndex: i, toolCall: sibling, partial: queryCtx.turnOutput });
+	}
+	// A block still partial here has NO fired handler: its complete arguments
+	// exist nowhere on this side of the boundary yet. Ending the turn now would
+	// hand Pi truncated arguments to execute — a truncated bash command is not a
+	// hypothetical hazard — so give the lagging stream more grace first.
+	const unsettled = queryCtx.turnBlocks.filter((b: any) => b.type === "toolCall" && "partialJson" in b);
+	if (unsettled.length > 0 && rearmCount < FINALIZE_MAX_REARMS) {
+		debug(`mcp handler: ${unsettled.length} sibling tool call(s) still streaming — re-arming grace (${rearmCount + 1}/${FINALIZE_MAX_REARMS})`);
+		scheduleToolUseTurnEnd(
+			queryCtx,
+			() => finalizeToolUseTurnFromMcpInvocation(queryCtx, toolCallId, toolName, mappedArgs, rearmCount + 1),
+			`finalize-rearm:${toolName}`,
+		);
+		return;
+	}
+	// Grace exhausted with blocks still partial: endToolUseTurn prunes them —
+	// truncated arguments never execute; each pruned call replays complete on
+	// the SDK's assistant yield in a later turn, or its handler eventually
+	// fires and the stranded drain fails it with a retryable error. When the
+	// turn holds NOTHING executable (this call suppressed as forwarded/dead and
+	// no settled siblings), leave the stream to its own terminal events — an
+	// empty tool_use turn would make Pi execute nothing and record an empty
+	// assistant message for it.
+	const executable = queryCtx.turnBlocks.some((b: any) => b.type === "toolCall" && !("partialJson" in b));
+	if (!executable) {
+		debug(`mcp handler: nothing executable in this turn after suppression — leaving the stream to its own terminal events (${toolName} [${toolCallId}])`);
+		return;
+	}
 	queryCtx.turnSawToolCall = true;
 	debug(`mcp handler: finalizing tool_use turn from MCP invocation [${toolCallId}] (${toolName}) — terminal stream events never arrived`);
 	endToolUseTurn(queryCtx);
@@ -209,8 +300,11 @@ export function processStreamEvent(
 	message: SDKMessage,
 	customToolNameToPi: Map<string, string>,
 	model: Model<any>,
+	// The consuming query's CAPTURED context, never the live ctx() (see the C4
+	// note in consumeQuery): a reentrant subagent can be pushed while the parent
+	// iterator is suspended, and live-state reads would hit the wrong query.
+	c: QueryContext = ctx(),
 ): void {
-	const c = ctx();
 	if (!c.currentPiStream || !c.turnOutput) return;
 	const event = (message as SDKMessage & { event: any }).event;
 	if (event?.type === "ping") return;
@@ -228,18 +322,20 @@ export function processStreamEvent(
 		// counters are replaced. No-op on the turn's first, and no-op if this same
 		// message was already declared (see beginChildMessage).
 		c.beginChildMessage(event.message?.id);
-		updateTurnOutputModel(event.message?.model);
-		if (event.message?.usage) updateUsage(c.turnOutput, event.message.usage, model);
+		updateTurnOutputModel(event.message?.model, c);
+		if (event.message?.usage) updateUsage(c.turnOutput, event.message.usage, model, c);
 		return;
 	}
 
 	if (event?.type === "content_block_start") {
 		c.turnSawStreamEvent = true;
-		ensureTurnStarted();
+		ensureTurnStarted(c);
 		// A new block owns this index from here on, so release any child-executed
-		// claim on it. Belt-and-braces against a missed message_start: without this
-		// a stale index could silently swallow a later text block's deltas.
+		// or suppressed claim on it. Belt-and-braces against a missed
+		// message_start: without this a stale index could silently swallow a later
+		// text block's deltas.
 		c.childExecutedStreamIndexes.delete(event.index);
+		c.suppressedStreamIndexes.delete(event.index);
 		if (event.content_block?.type === "tool_use" && isChildExecutedTool(event.content_block.name)) {
 			// The child runs this one itself — mirroring it into the Pi stream would
 			// make Pi's agent loop dispatch a tool it does not have. See
@@ -255,6 +351,24 @@ export function processStreamEvent(
 			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") {
+			const streamedId: unknown = event.content_block.id;
+			if (typeof streamedId === "string" && (c.forwardedToolCallIds.has(streamedId) || c.deadToolCallIds.has(streamedId))) {
+				// A lagging stream replaying a call Pi already executed — or one whose
+				// handler was already failed as stranded — into a later turn. Mirroring
+				// it would make Pi dispatch it a second time (vstack#1469).
+				c.suppressedStreamIndexes.add(event.index);
+				debug(`processStreamEvent: tool_use ${streamedId} already ${c.forwardedToolCallIds.has(streamedId) ? "forwarded" : "dead"} — suppressing duplicate stream block`);
+				return;
+			}
+			if (typeof streamedId === "string" && c.turnBlocks.some((b: any) => b.type === "toolCall" && b.id === streamedId)) {
+				// Same turn, same id: the completed-message yield beat the stream (its
+				// block is already recorded with complete arguments). A second
+				// partialJson copy would ship the id twice in one done message — and
+				// if its stop never arrives, ship it truncated (vstack#1469).
+				c.suppressedStreamIndexes.add(event.index);
+				debug(`processStreamEvent: tool_use ${streamedId} already recorded in this turn — suppressing duplicate stream block`);
+				return;
+			}
 			c.turnSawToolCall = true;
 			const mappedName = mapToolName(event.content_block.name, customToolNameToPi);
 			c.recordToolCall(event.content_block.id, mappedName, {});
@@ -276,7 +390,8 @@ export function processStreamEvent(
 		// them here rather than letting the lookup below miss, so the "unmatched"
 		// warning keeps meaning "something is wrong". Unlike that stale-event case
 		// this IS a live event for the current message, so it still counts as one.
-		if (c.childExecutedStreamIndexes.has(event.index)) {
+		// Suppressed duplicate/dead blocks skip identically.
+		if (c.childExecutedStreamIndexes.has(event.index) || c.suppressedStreamIndexes.has(event.index)) {
 			c.turnSawStreamEvent = true;
 			return;
 		}
@@ -308,7 +423,7 @@ export function processStreamEvent(
 	if (event?.type === "content_block_stop") {
 		// Same as the delta case: the block was never mirrored, so there is nothing
 		// to seal and nothing unmatched about it.
-		if (c.childExecutedStreamIndexes.has(event.index)) {
+		if (c.childExecutedStreamIndexes.has(event.index) || c.suppressedStreamIndexes.has(event.index)) {
 			c.turnSawStreamEvent = true;
 			return;
 		}
@@ -338,7 +453,7 @@ export function processStreamEvent(
 
 	if (event?.type === "message_delta") {
 		c.turnOutput.stopReason = mapStopReason(event.delta?.stop_reason);
-		if (event.usage) updateUsage(c.turnOutput, event.usage, model);
+		if (event.usage) updateUsage(c.turnOutput, event.usage, model, c);
 		return;
 	}
 
@@ -371,9 +486,16 @@ function appendMissingToolUsesFromAssistant(
 	assistantMsg: { content?: Array<any>; usage?: Record<string, number | undefined> },
 	model: Model<any>,
 	customToolNameToPi: Map<string, string>,
+	c: QueryContext,
 ): boolean {
-	const c = ctx();
 	if (!assistantMsg?.content) return false;
+	// With a dead stream, ids are still RECORDED (claims and result matching
+	// need them) but the content is never touched: turnBlocks IS the content
+	// array of a turnOutput that endToolUseTurn already handed Pi BY REFERENCE
+	// in its done event, so a push here appends calls into a delivered message
+	// behind Pi's back — whether Pi's dispatch enumerates before or after the
+	// push is a microtask race (vstack#1469).
+	const streamLive = Boolean(c.currentPiStream && c.turnOutput);
 	let sawToolUse = false;
 	for (const block of assistantMsg.content) {
 		if (block.type !== "tool_use") continue;
@@ -385,11 +507,19 @@ function appendMissingToolUsesFromAssistant(
 			debug(`assistant message: child-executed tool ${block.name} [${block.id}] — not mirrored as a Pi tool call`);
 			continue;
 		}
-		sawToolUse = true;
 		const existingIdx = c.turnBlocks.findIndex((b: any) => b.type === "toolCall" && b.id === block.id);
+		if (existingIdx < 0 && (c.forwardedToolCallIds.has(block.id) || c.deadToolCallIds.has(block.id))) {
+			// Completed-message replay of a call Pi already executed in an earlier
+			// turn (or one already failed as stranded). Not a live Pi turn boundary:
+			// sawToolUse stays false for it, and no block is emitted (vstack#1469).
+			debug(`assistant message: tool_use ${block.id} already ${c.forwardedToolCallIds.has(block.id) ? "forwarded" : "dead"} — skipping duplicate`);
+			continue;
+		}
+		sawToolUse = true;
 		const name = mapToolName(block.name, customToolNameToPi);
 		const mappedArgs = mapToolArgs(name, block.input);
 		c.recordToolCall(block.id, name, mappedArgs);
+		if (!streamLive) continue;
 		if (existingIdx >= 0) {
 			const existing = c.turnBlocks[existingIdx] as any;
 			existing.name = name;
@@ -403,7 +533,7 @@ function appendMissingToolUsesFromAssistant(
 			continue;
 		}
 
-		ensureTurnStarted();
+		ensureTurnStarted(c);
 		c.turnBlocks.push({
 			type: "toolCall", id: block.id,
 			name,
@@ -418,7 +548,7 @@ function appendMissingToolUsesFromAssistant(
 	// message_start placeholder usage (output ≈ 1–7), and once the done event has
 	// delivered turnOutput to pi, overwriting its usage with those placeholders
 	// would corrupt the very figure message_delta got right.
-	if (assistantMsg.usage && c.turnOutput && c.currentPiStream) updateUsage(c.turnOutput, assistantMsg.usage, model);
+	if (assistantMsg.usage && c.turnOutput && c.currentPiStream) updateUsage(c.turnOutput, assistantMsg.usage, model, c);
 	return sawToolUse;
 }
 
@@ -441,8 +571,7 @@ function appendMissingToolUsesFromAssistant(
  * `CustomEntry` (connector-audit.ts) so the Pi session records that the call
  * happened, without a content block Pi's agent loop could try to dispatch.
  */
-export function noteChildExecutedToolResults(message: SDKMessage): void {
-	const c = ctx();
+export function noteChildExecutedToolResults(message: SDKMessage, c: QueryContext = ctx()): void {
 	if (c.childExecutedToolCalls.size === 0) return;
 	const content = (message as SDKMessage & { message?: { content?: unknown } }).message?.content;
 	if (!Array.isArray(content)) return;
@@ -457,11 +586,10 @@ export function noteChildExecutedToolResults(message: SDKMessage): void {
 	}
 }
 
-export function processAssistantMessage(message: SDKMessage, model: Model<any>, customToolNameToPi: Map<string, string>): void {
-	const c = ctx();
+export function processAssistantMessage(message: SDKMessage, model: Model<any>, customToolNameToPi: Map<string, string>, c: QueryContext = ctx()): void {
 	const assistantMsg = (message as any).message;
 	if (!assistantMsg?.content) return;
-	updateTurnOutputModel(assistantMsg.model);
+	updateTurnOutputModel(assistantMsg.model, c);
 	if (c.turnSawStreamEvent) {
 		// The SDK yields the completed assistant message BEFORE the stream's
 		// message_delta/message_stop on every tool-use turn (measured — this is
@@ -472,7 +600,7 @@ export function processAssistantMessage(message: SDKMessage, model: Model<any>,
 		// message_start placeholders (1–7 output tokens per tool turn). The grace
 		// timer force-ends the turn if the terminal events never arrive, so pi
 		// still gets to execute the tools and unblock the MCP handlers.
-		if (appendMissingToolUsesFromAssistant(assistantMsg, model, customToolNameToPi)) {
+		if (appendMissingToolUsesFromAssistant(assistantMsg, model, customToolNameToPi, c)) {
 			c.turnSawToolCall = true;
 			scheduleToolUseTurnEnd(c, () => endToolUseTurn(c), "assistant-boundary");
 		}
@@ -509,7 +637,7 @@ export function processAssistantMessage(message: SDKMessage, model: Model<any>,
 	for (const block of assistantMsg.content) {
 		if (block.type === "text" && block.text) {
 			if (alreadyRendered("text", block.text)) continue;
-			ensureTurnStarted();
+			ensureTurnStarted(c);
 			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 });
@@ -517,7 +645,7 @@ export function processAssistantMessage(message: SDKMessage, model: Model<any>,
 			c.currentPiStream?.push({ type: "text_end", contentIndex: idx, content: block.text, partial: c.turnOutput });
 		} else if (block.type === "thinking") {
 			if (alreadyRendered("thinking", block.thinking ?? "")) continue;
-			ensureTurnStarted();
+			ensureTurnStarted(c);
 			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 });
@@ -531,7 +659,18 @@ export function processAssistantMessage(message: SDKMessage, model: Model<any>,
 				debug(`processAssistantMessage fallback: child-executed tool ${block.name} [${block.id}] — not mirrored as a Pi tool call`);
 				continue;
 			}
-			ensureTurnStarted();
+			if (!c.turnBlocks.some((b: any) => b.type === "toolCall" && b.id === block.id)
+				&& (c.forwardedToolCallIds.has(block.id) || c.deadToolCallIds.has(block.id))) {
+				// A cross-turn replay of a call Pi already executed (or one whose
+				// handler was already failed as stranded). This exact path produced
+				// the observed duplicate dispatches: the completed-message yield lands
+				// in the callback AFTER a grace finalize already ended the call's
+				// turn, and per-message dedup cannot see across turns (vstack#1469).
+				// Not recorded either — a forwarded call must not be claimable again.
+				debug(`processAssistantMessage fallback: tool_use ${block.id} already ${c.forwardedToolCallIds.has(block.id) ? "forwarded" : "dead"} — skipping duplicate`);
+				continue;
+			}
+			ensureTurnStarted(c);
 			c.turnSawToolCall = true;
 			const mappedName = mapToolName(block.name, customToolNameToPi);
 			const mappedArgs = mapToolArgs(mappedName, block.input);
@@ -557,12 +696,12 @@ export function processAssistantMessage(message: SDKMessage, model: Model<any>,
 			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);
+			updateTurnOutputModel(block.to?.model, c);
 		} else {
 			debug("processAssistantMessage: unhandled block type", block.type);
 		}
 	}
-	if (assistantMsg.usage && c.turnOutput) updateUsage(c.turnOutput, assistantMsg.usage, model);
+	if (assistantMsg.usage && c.turnOutput) updateUsage(c.turnOutput, assistantMsg.usage, model, c);
 
 	// End the stream on tool_use. Immediate (no grace deferral) ON PURPOSE: this
 	// branch only runs when NO content blocks streamed for the message, so there

package/src/bridge-commands.ts

@@ -0,0 +1,86 @@
+// The /pi-claude command surface: settings/status UI and the deterministic
+// connector-inventory report. Extracted from index.ts (pure move).
+
+import { type Model } from "@earendil-works/pi-ai";
+import { type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { accountSessionScope, resolveClaudeAccountRouter } from "./account-router.js";
+import { loadConfig } from "./config.js";
+import { listAccountConnectors, resolveClaudeOAuth } from "./connector-inventory.js";
+import { connectorCredentialEnv, readCredentialFile } from "./connector-runtime.js";
+
+const COMMANDS_REGISTERED_KEY = Symbol.for("claude-bridge:commandsRegistered");
+
+function commandCwd(ctx: unknown): string {
+	const value = (ctx as { cwd?: unknown })?.cwd;
+	return typeof value === "string" && value.length > 0 ? value : process.cwd();
+}
+
+async function tryOpenExtensionManagerSettings(ctx: { ui: ExtensionUIContext }): Promise<boolean> {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const openQuickSettings = host[Symbol.for("vstack.pi.extension-manager.open-quick-settings")];
+	if (typeof openQuickSettings !== "function") return false;
+	try {
+		await (openQuickSettings as (ctx: unknown, hint?: string) => Promise<void>)(ctx, "@vanillagreen/pi-claude-bridge");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function showBridgeStatus(ctx: { ui: ExtensionUIContext; cwd?: string }): void {
+	const config = loadConfig(commandCwd(ctx));
+	ctx.ui.notify([
+		`Pi Claude: ${config.enabled === false ? "disabled" : "enabled"}`,
+		"Claude account billing settings (including Extra Usage) are managed in Claude.",
+	].join("\n"), "info");
+}
+
+// Deterministic connector enumeration for the host app (vstack#838). Reports the
+// failure reason rather than an empty list, so "no connectors" and "could not
+// check" stay distinguishable.
+async function reportConnectorInventory(ctx: {
+	ui: ExtensionUIContext;
+	model?: Model<any>;
+	sessionManager?: { getSessionId?: () => string };
+}): Promise<void> {
+	// With a router active, enumerate the CURRENT route's account rather than
+	// whatever the process env points at.
+	const account = ctx.model
+		? resolveClaudeAccountRouter()?.current(ctx.model.id, ctx.sessionManager?.getSessionId?.())
+		: undefined;
+	const credentials = resolveClaudeOAuth(readCredentialFile, connectorCredentialEnv(account ? accountSessionScope(account).claudeConfigDir : undefined));
+	if (!credentials) {
+		ctx.ui.notify("Pi Claude: no Claude OAuth credentials found — cannot enumerate connectors.", "error");
+		return;
+	}
+	const inventory = await listAccountConnectors({ credentials });
+	if (!inventory.ok) {
+		ctx.ui.notify(`Pi Claude: connector enumeration failed — ${inventory.reason}`, "error");
+		return;
+	}
+	if (inventory.connectors.length === 0) {
+		ctx.ui.notify("Pi Claude: this account has no connectors installed.", "info");
+		return;
+	}
+	const names = inventory.connectors.map((c) => c.name).join(", ");
+	ctx.ui.notify(`Pi Claude: ${inventory.connectors.length} connector(s) installed — ${names}`, "info");
+}
+
+export function registerBridgeCommands(pi: ExtensionAPI): void {
+	const guard = pi as unknown as Record<PropertyKey, unknown>;
+	if (guard[COMMANDS_REGISTERED_KEY]) return;
+	guard[COMMANDS_REGISTERED_KEY] = true;
+
+	pi.registerCommand("pi-claude", {
+		description: "Open Pi Claude settings/status",
+		handler: async (args: string, ctx) => {
+			if (args.trim()) ctx.ui.notify("Unknown /pi-claude argument.", "warning");
+			if (await tryOpenExtensionManagerSettings(ctx)) return;
+			showBridgeStatus(ctx);
+		},
+	});
+	pi.registerCommand("pi-claude:connectors", {
+		description: "List the Claude account's installed claude.ai connectors",
+		handler: async (_args: string, ctx) => reportConnectorInventory(ctx),
+	});
+}