@raoxxxwq/pi-codebuddy-sdk 0.3.0

package/src/index.ts

@@ -0,0 +1,1979 @@
+import { calculateCost, StringEnum, type AssistantMessage, type AssistantMessageEventStream, type Context, type Model, type SimpleStreamOptions, type Tool } from "@earendil-works/pi-ai";
+import * as piAi from "@earendil-works/pi-ai";
+import { buildSessionContext, compact, keyHint, type CompactionEntry, type ExtensionAPI, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { createSdkMcpServer, query, type Effort, type Message as CbMessage, type UserMessage as CbUserMessage } from "@tencent-ai/agent-sdk";
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { createSession, deleteSession } from "./cb-session-io.js";
+import { appendFileSync, mkdirSync, realpathSync, statSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { PROVIDER_ID, messageContentToText, convertPiMessages } from "./convert.js";
+import { buildModels, codebuddyModelId, FALLBACK_MODELS, rawModelsFromSdk, resolveModel as _resolveModel, type PiModel } from "./models.js";
+import { MCP_SERVER_NAME, MCP_TOOL_PREFIX, buildCodebuddySystemPrompt, enhancePiToolForCodebuddy } from "./skills.js";
+import { verifyWrittenSession as _verifyWrittenSession } from "./session-verify.js";
+import { extractAllToolResults as _extractAllToolResults, type McpResult } from "./extract-tool-results.js";
+import { QueryContext, ctx } from "./query-state.js";
+import { loadConfig, type Config } from "./config.js";
+import { jsonSchemaToZodObject } from "./typebox-to-zod.js";
+import { buildActionSummary, type ToolCallState } from "./askcodebuddy-ui.js";
+import {
+	applyContextWindowCalibrations,
+	buildCalibrationEnvironment,
+	loadCalibrationCache,
+	recordObservedContextWindow,
+	saveCalibrationCache,
+	type CalibrationCache,
+	type CalibrationEnvironment,
+} from "./model-calibration.js";
+import { withSdkGate } from "./sdk-gate.js";
+
+// Compat (#2): use factory if available (pi-ai ≥0.66), else fall back to constructor (gsd-pi etc.)
+const _piAi = piAi as any;
+const newAssistantMessageEventStream: () => AssistantMessageEventStream =
+	typeof _piAi.createAssistantMessageEventStream === "function"
+		? _piAi.createAssistantMessageEventStream
+		: () => new _piAi.AssistantMessageEventStream();
+
+type SdkQueryOptions = NonNullable<Parameters<typeof query>[0]["options"]>;
+type CliDebugOptions = { debug?: boolean; debugFile?: string };
+
+// --- Debug logging ---
+// CODEBUDDY_SDK_DEBUG=1 enables local debug logs (metadata only; paths redacted; no prompt/tool bodies).
+
+const DEBUG = process.env.CODEBUDDY_SDK_DEBUG === "1";
+const DEBUG_LOG_PATH = process.env.CODEBUDDY_SDK_DEBUG_PATH || join(homedir(), ".pi", "agent", "codebuddy-sdk.log");
+const DIAG_LOG_PATH = join(homedir(), ".pi", "agent", "codebuddy-sdk-diag.log");
+const ISSUES_URL = "https://github.com/MuJianxuan/pi-codebuddy-sdk/issues/new";
+
+function redactForLog(value: string): string {
+	const home = homedir();
+	return home && value.includes(home) ? value.split(home).join("~") : value;
+}
+
+function redactLogValue(value: unknown): unknown {
+	if (typeof value === "string") return redactForLog(value);
+	if (Array.isArray(value)) return value.map(redactLogValue);
+	if (value && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value)) out[k] = redactLogValue(v);
+		return out;
+	}
+	return value;
+}
+
+// Ensure log directories exist when debug is enabled
+if (DEBUG) {
+	try {
+		mkdirSync(dirname(DEBUG_LOG_PATH), { recursive: true });
+		mkdirSync(dirname(DIAG_LOG_PATH), { recursive: true });
+	} catch {
+		// If directory creation fails, debug functions will throw on first use
+	}
+}
+
+// Unique per module evaluation — confirms whether subagents share module state
+const moduleInstanceId = Math.random().toString(36).slice(2, 8);
+
+function debug(...args: unknown[]) {
+	if (!DEBUG) return;
+	const ts = new Date().toISOString();
+	const fmt = (a: unknown): string => {
+		if (typeof a === "string") return redactForLog(a);
+		if (a instanceof Error) return redactForLog(`${a.name}: ${a.message}`);
+		return redactForLog(JSON.stringify(a));
+	};
+	const msg = args.map(fmt).join(" ");
+	appendFileSync(DEBUG_LOG_PATH, `[${ts}] [${moduleInstanceId}] ${msg}\n`);
+}
+
+// Per-query CLI debug capture. When CODEBUDDY_SDK_DEBUG=1, ask the CodeBuddy CLI
+// subprocess to write its own debug log locally. We do not forward stderr (may
+// contain prompt or credential hints).
+let nextCliDebugSeq = 1;
+function makeCliDebugOptions(tag: string): { debug?: boolean; debugFile?: string } {
+	if (!DEBUG) return {};
+	const seq = nextCliDebugSeq++;
+	const ts = new Date().toISOString().replace(/[:.]/g, "-");
+	const logDir = join(dirname(DEBUG_LOG_PATH), "cb-cli-logs");
+	try { mkdirSync(logDir, { recursive: true }); } catch { /* ignore */ }
+	const debugFile = join(logDir, `${ts}-${tag}-${seq}.log`);
+	debug(`cli-debug: ${tag} #${seq} → ${redactForLog(debugFile)}`);
+	return { debug: true, debugFile };
+}
+
+/** Diagnostic dump for "should never happen" paths — only when debug is enabled */
+function diagDump(label: string, data: Record<string, unknown>) {
+	if (!DEBUG) return;
+	const ts = new Date().toISOString();
+	const entry = { ts, moduleInstanceId, label, ...redactLogValue(data) as Record<string, unknown> };
+	appendFileSync(DIAG_LOG_PATH, JSON.stringify(entry) + "\n");
+	debug(`DIAG: ${label} (see ${redactForLog(DIAG_LOG_PATH)})`);
+}
+
+// --- Constants ---
+
+// Global key to prevent re-registration of the provider across module reloads.
+//
+// Extensions like pi-subagents spawn a subagent and it loads this module
+// again. Without this guard, the subagent's call to registerProvider() would
+// overwrite the parent's `streamSimple` function reference in the shared
+// ModelRegistry. When the parent later delivers a tool result, it would call
+// the subagent's `streamSimple` (which has empty state) instead of its own.
+//
+// By storing the active streamSimple in a Symbol.for() global (shared across all
+// module instances), we ensure only the FIRST instance to register takes effect.
+// Subsequent instances wrap the stored function instead of overwriting it.
+//
+// On session_shutdown (including /reload), clearSession() resets this so a fresh
+// registration can occur for the next session.
+const ACTIVE_STREAM_SIMPLE_KEY = Symbol.for("codebuddy-sdk:activeStreamSimple");
+
+const SDK_TO_PI_TOOL_NAME: Record<string, string> = {
+	read: "read", write: "write", edit: "edit", bash: "bash",
+};
+
+let MODELS: PiModel[] = buildModels(FALLBACK_MODELS);
+let providerSettings: NonNullable<Config["provider"]> = {};
+let calibrationEnvironment: CalibrationEnvironment = buildCalibrationEnvironment();
+let calibrationCache: CalibrationCache = loadCalibrationCache();
+let calibrationRefreshPending = false;
+
+type ContentBlockParam =
+	| { type: "text"; text: string }
+	| { type: "image"; source: { type: "base64"; media_type: string; data: string } };
+type SettingSource = "user" | "project" | "local";
+
+function resolveModel(input: string) {
+	return _resolveModel(MODELS, input);
+}
+
+function applyModelCalibrations(models: PiModel[]): PiModel[] {
+	return buildModels(applyContextWindowCalibrations(models, calibrationCache, calibrationEnvironment));
+}
+
+function registerCurrentProvider(pi: ExtensionAPI): void {
+	const g = globalThis as Record<symbol, any>;
+	const streamFn = g[ACTIVE_STREAM_SIMPLE_KEY] ?? streamCodebuddySdk;
+	pi.registerProvider(PROVIDER_ID, {
+		name: "CodeBuddy",
+		baseUrl: PROVIDER_ID,
+		apiKey: "not-used",
+		api: "codebuddy-sdk",
+		models: MODELS as any,
+		streamSimple: streamFn as any,
+	});
+}
+
+function scheduleCalibrationRefresh(reason: string): void {
+	calibrationRefreshPending = true;
+	debug(`calibration: scheduled provider refresh (${reason})`);
+	queueMicrotask(() => maybeRefreshProviderRegistration(`microtask:${reason}`));
+}
+
+function maybeRefreshProviderRegistration(reason: string): void {
+	if (!calibrationRefreshPending || !piApi) return;
+	if (activeQueryContexts.size > 0) {
+		debug(`calibration: refresh deferred (${reason}) activeQueries=${activeQueryContexts.size}`);
+		return;
+	}
+	calibrationRefreshPending = false;
+	try {
+		debug(`calibration: refreshing provider registration (${reason}) models=${MODELS.length}`);
+		registerCurrentProvider(piApi);
+	} catch (err) {
+		debug(`calibration: provider refresh failed (${reason})`, err);
+	}
+}
+
+// --- Error handling ---
+
+function errorMessage(err: unknown): string {
+	if (err instanceof Error) return err.message;
+	if (err && typeof err === "object") {
+		const obj = err as Record<string, unknown>;
+		if (typeof obj.message === "string") return obj.message;
+		if (typeof obj.error === "string") return obj.error;
+		try { return JSON.stringify(err); } catch {}
+	}
+	return String(err);
+}
+
+// AskCodebuddy mode presets — controls which CC tools are blocked per mode.
+// Only block tools that can't work (no pi TUI for user interaction).
+// Other CC tools (Agent, SendMessage, RemoteTrigger, Tasks, etc.) are intentionally not blocked.
+const ASKCLAUDE_ALWAYS_BLOCKED = [
+	"AskUserQuestion", "EnterPlanMode", "ExitPlanMode",
+	"ToolSearch", // probes for blocked tools, wastes tokens
+	"ScheduleWakeup", // no harness to fire wakeup from inside a delegated subagent
+];
+const MODE_DISALLOWED_TOOLS: Record<string, string[]> = {
+	full: [
+		...ASKCLAUDE_ALWAYS_BLOCKED,
+	],
+	read: [
+		...ASKCLAUDE_ALWAYS_BLOCKED,
+		"Write", "Edit", "Bash", "NotebookEdit",
+		"EnterWorktree", "ExitWorktree", "CronCreate", "CronDelete", "TeamCreate", "TeamDelete",
+	],
+	none: [
+		...ASKCLAUDE_ALWAYS_BLOCKED,
+		"Read", "Write", "Edit", "Glob", "Grep", "Bash", "Agent",
+		"NotebookEdit", "EnterWorktree", "ExitWorktree",
+		"CronCreate", "CronDelete", "TeamCreate", "TeamDelete",
+		"WebFetch", "WebSearch",
+	],
+};
+
+// --- Session persistence ---
+
+interface SessionState {
+	sessionId: string;
+	cursor: number;
+	cwd: string;
+	// Force the next syncSharedSession call down the REBUILD path. Set when
+	// pi has mutated its messages array out from under us (compact, tree
+	// navigation) or after an abort left the JSONL in an indeterminate state.
+	// REBUILD wipes and rewrites the file to match pi's current history.
+	needsRebuild?: boolean;
+	// Set ONLY after an abort. The killed CC subprocess may still be flushing
+	// a late "[Request interrupted by user]" record to the session JSONL.
+	// Reusing the same sessionId/path would race that orphan write into our
+	// fresh file and break CC's parent-uuid chain on the next resume. When
+	// this flag is set, REBUILD takes a fresh UUID and skips deleteSession
+	// so the orphan writes land on a dead inode. Compact/tree do NOT set
+	// this — there's no concurrent CC writer during those events, so
+	// in-place rebuild (preserve UUID, deleteSession + createSession) is safe.
+	forceRotate?: boolean;
+}
+
+let sharedSession: SessionState | null = null;
+
+// Convert pi messages to Anthropic API format for session import.
+// Lossy: non-Anthropic thinking blocks are dropped (no valid signature), and only
+// text/image/toolCall block types are handled. If all blocks in an assistant message
+// are filtered, the message is dropped — which can create invalid sequences (e.g.
+// two user messages in a row, or tool_result without preceding tool_use).
+function convertAndImportMessages(
+	session: ReturnType<typeof createSession>,
+	messages: Context["messages"],
+	customToolNameToSdk?: Map<string, string>,
+): void {
+	const { anthropicMessages, sanitizedIds } = convertPiMessages(messages, customToolNameToSdk);
+
+	debug(`convertAndImportMessages: ${messages.length} pi msgs → ${anthropicMessages.length} anthropic msgs`);
+	debug(`convertAndImportMessages: imported roles:`, anthropicMessages.map((m, i) => {
+		const c = m.content;
+		if (typeof c === "string") return `[${i}]${m.role}:text`;
+		if (Array.isArray(c)) return `[${i}]${m.role}:${c.map((b: { type?: string }) => b.type).join("+")}`;
+		return `[${i}]${m.role}:?`;
+	}).join(" "));
+	if (sanitizedIds.size > 0) {
+		debug(`convertAndImportMessages: sanitized ${sanitizedIds.size} tool IDs:`,
+			[...sanitizedIds.entries()].map(([orig, clean]) => orig === clean ? orig : `${orig}→${clean}`).join(", "));
+	}
+	if (messages.length) session.importPiMessages(messages);
+}
+
+// Pi doesn't pass tool results directly — it appends them to the context and calls
+// the provider again. Thin wrapper over extract-tool-results.js that adds per-turn
+// debug logging at the extraction boundary.
+function extractAllToolResults(context: Context): McpResult[] {
+	const { results, stopIdx } = _extractAllToolResults(context.messages as unknown as Array<{ role: string; [key: string]: unknown }>);
+	debug(`extractAllToolResults: ${results.length} results from ${context.messages.length} msgs, stopped at index ${stopIdx}`);
+	debug(`extractAllToolResults: all msg roles:`, context.messages.map((m, i) => `[${i}]${m.role}`).join(" "));
+	for (let r = 0; r < results.length; r++) {
+		debug(`extractAllToolResults: result[${r}] id=${results[r].toolCallId}${results[r].isError ? " ERROR" : ""} contentLen=${JSON.stringify(results[r].content).length}`);
+	}
+	return results;
+}
+
+/** Extract the last user message from context as a prompt string. Returns null if last message is not a user message. */
+function extractUserPrompt(messages: Context["messages"]): string | null {
+	const last = messages[messages.length - 1];
+	if (!last || last.role !== "user") return null;
+	if (typeof last.content === "string") return last.content;
+	return messageContentToText(last.content) || "";
+}
+
+/** Extract the last user message as ContentBlockParam[] (preserving images).
+ *  Returns null if no images — caller should fall back to string prompt. */
+function extractUserPromptBlocks(messages: Context["messages"]): ContentBlockParam[] | null {
+	const last = messages[messages.length - 1];
+	if (!last || last.role !== "user") return null;
+	if (typeof last.content === "string") {
+		debug(`extractUserPromptBlocks: content is string (length=${last.content.length})`);
+		return null;
+	}
+	if (!Array.isArray(last.content)) {
+		debug(`extractUserPromptBlocks: content is ${typeof last.content}`);
+		return null;
+	}
+	debug(`extractUserPromptBlocks: ${last.content.length} blocks, types=${last.content.map((b: any) => b.type).join(",")}`);
+	let hasImage = false;
+	const blocks: ContentBlockParam[] = [];
+	for (const block of last.content) {
+		if (block.type === "text" && block.text) {
+			blocks.push({ type: "text", text: block.text });
+		} else if (block.type === "image") {
+			debug(`image block: mimeType=${(block as any).mimeType}, data length=${((block as any).data ?? "").length}, keys=${Object.keys(block).join(",")}`);
+			if (!(block as any).data || !(block as any).mimeType) {
+				debug(`image block missing data or mimeType, skipping`);
+				continue;
+			}
+			hasImage = true;
+			blocks.push({
+				type: "image",
+				source: { type: "base64", media_type: block.mimeType, data: block.data },
+			});
+		}
+	}
+	return hasImage ? blocks : null;
+}
+
+async function* wrapPromptStream(blocks: ContentBlockParam[]): AsyncIterable<CbUserMessage> {
+	yield {
+		type: "user",
+		session_id: "",
+		parent_tool_use_id: null,
+		message: { role: "user", content: blocks as any },
+	};
+}
+
+function newAssistantOutput(model: Model<any>, text: string, stopReason: AssistantMessage["stopReason"], errorMessage?: string): AssistantMessage {
+	return {
+		role: "assistant",
+		content: text ? [{ type: "text", text }] : [],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+		stopReason,
+		...(errorMessage ? { errorMessage } : {}),
+		timestamp: Date.now(),
+	};
+}
+
+function extractIsolatedSummaryPrompt(messages: Context["messages"]): string {
+	if (messages.length !== 1 || messages[0].role !== "user") {
+		throw new Error(
+			`isolatedStreamFn: expected exactly 1 user message, got ${messages.length} ` +
+			`(${messages.map((m) => m.role).join(",")})`,
+		);
+	}
+	const promptText = extractUserPrompt(messages);
+	if (!promptText) throw new Error("isolatedStreamFn: summarization prompt is empty");
+	return promptText;
+}
+
+function resultErrorText(message: CbMessage): string {
+	const result = message as CbMessage & { subtype?: string; errors?: unknown; error?: unknown };
+	if (Array.isArray(result.errors)) return result.errors.map(String).join("\n");
+	if (typeof result.error === "string") return result.error;
+	return `CodeBuddy summary failed: ${result.subtype ?? "unknown result"}`;
+}
+
+function isolatedStreamFn(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
+	const stream = newAssistantMessageEventStream();
+	void runIsolatedSummary(model, context, options, stream);
+	return stream;
+}
+
+async function runIsolatedSummary(
+	model: Model<any>,
+	context: Context,
+	options: SimpleStreamOptions | undefined,
+	stream: AssistantMessageEventStream,
+): Promise<void> {
+	let sdkQuery: ReturnType<typeof query> | undefined;
+	let wasAborted = false;
+	const onAbort = () => {
+		wasAborted = true;
+		void sdkQuery?.interrupt().catch(() => {});
+		try { sdkQuery?.interrupt(); } catch {}
+	};
+
+	try {
+		const promptText = extractIsolatedSummaryPrompt(context.messages);
+		const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
+		const codebuddyExecutable = loadConfig(cwd).provider?.pathToCodebuddyCode;
+		const cliModel = codebuddyModelId(model);
+		debug(`compact summary: spawn model=${cliModel} registeredModel=${model.id} promptLen=${promptText.length}`);
+
+		sdkQuery = query({
+			prompt: promptText,
+			options: {
+				cwd,
+				env: { ...process.env, DISABLE_AUTO_COMPACT: "1" },
+				tools: [],
+				strictMcpConfig: true,
+				settingSources: [] as SettingSource[],
+				persistSession: false,
+				systemPrompt: context.systemPrompt,
+				model: cliModel,
+				maxTurns: 1,
+				...(codebuddyExecutable ? { pathToCodebuddyCode: codebuddyExecutable } : {}),
+				...makeCliDebugOptions("compact-summary"),
+			},
+		});
+
+		if (options?.signal) {
+			if (options.signal.aborted) onAbort();
+			else options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		let assistantText = "";
+		let finalText = "";
+		let errorText: string | undefined;
+		let firstEventLogged = false;
+
+		for await (const message of sdkQuery) {
+			if (!firstEventLogged) {
+				debug(`compact summary: first event type=${message.type}`);
+				firstEventLogged = true;
+			}
+			if (wasAborted) break;
+
+			if (message.type === "assistant") {
+				for (const block of (message as any).message?.content ?? []) {
+					if (block.type === "text" && typeof block.text === "string") assistantText += block.text;
+				}
+			} else if (message.type === "result") {
+				logServedContextWindow("compact summary", message, model);
+				if (message.subtype === "success") {
+					finalText = message.result || assistantText;
+				} else {
+					errorText = resultErrorText(message);
+				}
+			}
+		}
+
+		if (wasAborted) {
+			const output = newAssistantOutput(model, "", "aborted", "Operation aborted");
+			debug("compact summary: aborted");
+			stream.push({ type: "error", reason: "aborted", error: output });
+			stream.end();
+			return;
+		}
+
+		const text = finalText || assistantText;
+		if (errorText || !text.trim()) {
+			const msg = errorText ?? "CodeBuddy summary returned empty text";
+			debug(`compact summary: error ${msg}`);
+			stream.push({ type: "error", reason: "error", error: newAssistantOutput(model, "", "error", msg) });
+			stream.end();
+			return;
+		}
+
+		debug(`compact summary: done textLen=${text.length}`);
+		stream.push({ type: "done", reason: "stop", message: newAssistantOutput(model, text, "stop") });
+		stream.end();
+	} catch (err) {
+		const msg = errorMessage(err);
+		debug("runIsolatedSummary threw; pushing terminal error", err);
+		stream.push({ type: "error", reason: "error", error: newAssistantOutput(model, "", "error", msg) });
+		stream.end();
+	} finally {
+		options?.signal?.removeEventListener("abort", onAbort);
+		try { sdkQuery?.interrupt(); } catch {}
+	}
+}
+
+function reinjectPriorCompactionFileOps(branchEntries: Array<{ type: string; details?: unknown }>, preparation: { fileOps: { read: Set<string>; edited: Set<string> } }): void {
+	const prior = [...branchEntries]
+		.reverse()
+		.find((entry): entry is CompactionEntry => entry.type === "compaction");
+	const details = prior?.details as { readFiles?: unknown; modifiedFiles?: unknown } | undefined;
+	if (!Array.isArray(details?.readFiles) || !Array.isArray(details?.modifiedFiles)) return;
+	for (const file of details.readFiles) preparation.fileOps.read.add(String(file));
+	for (const file of details.modifiedFiles) preparation.fileOps.edited.add(String(file));
+	debug(`compact takeover: re-injected prior file ops read=${details.readFiles.length} modified=${details.modifiedFiles.length}`);
+}
+
+interface SyncResult {
+	sessionId: string | null;
+	preserveSharedSession?: boolean;
+}
+
+/**
+ * Ensure the shared session has all messages up to (but not including) the last user message.
+ * Returns session ID to resume from, or null if no resume needed.
+ */
+// Read the session file we just wrote and sanity-check it. Warns instead of
+// throwing — CC may be more tolerant than our checks, so a false positive
+// shouldn't block the user. Pure logic is in session-verify.js; this wrapper
+// fans each warning out to debug log + piUI notify + diagDump.
+function verifyWrittenSession(
+	jsonlPath: string,
+	expectedSessionId: string,
+	expectedRecordCount: number,
+	cwd: string,
+): void {
+	const warnings = _verifyWrittenSession(jsonlPath, expectedSessionId, expectedRecordCount);
+	for (const msg of warnings) {
+		debug(`WARNING session verify: ${msg}`);
+		piUI?.notify(
+			`Session sync issue: ${msg}. ` +
+			`cwd=${redactForLog(cwd)}` +
+			(DEBUG ? ` (see ${redactForLog(DEBUG_LOG_PATH)})` : ` (set CODEBUDDY_SDK_DEBUG=1 for a local log)`) +
+			`. Report: ${ISSUES_URL}`,
+			"warning",
+		);
+		diagDump("session_verify_fail", { msg, jsonlPath, cwd, realpath: safeRealpath(cwd), codebuddyConfigDir: process.env.CODEBUDDY_CONFIG_DIR ?? null });
+	}
+}
+
+function safeRealpath(p: string): string {
+	try { return realpathSync(p); } catch (e) { return `<failed: ${(e as Error).message}>`; }
+}
+
+// Diagnostic snapshot of where a session file was just written. Catches the
+// class of bugs where pi writes to ~/.claude/projects/<X> but CC SDK reads
+// from ~/.claude/projects/<Y> (symlinks, CODEBUDDY_CONFIG_DIR, hash mismatch).
+function debugSessionPaths(label: string, cwd: string, jsonlPath: string): void {
+	const realCwd = safeRealpath(cwd);
+	let fileSize: number | null = null;
+	let fileExists = false;
+	try {
+		const st = statSync(jsonlPath);
+		fileExists = true;
+		fileSize = st.size;
+	} catch { /* file may not exist yet */ }
+	debug(`${label}: cwd=${redactForLog(cwd)}`);
+	if (realCwd !== cwd) debug(`${label}: realpath(cwd)=${redactForLog(realCwd)} (symlink-resolved)`);
+	debug(`${label}: jsonlPath=${redactForLog(jsonlPath)}`);
+	debug(`${label}: fileExists=${fileExists}${fileSize != null ? ` size=${fileSize}` : ""}`);
+}
+
+// Two semantic paths:
+//   REUSE — pi's history is in sync with the existing sharedSession (or drifted
+//     only by the trailing final-assistant message that pi appends after
+//     streamSimple returns, which CC's own persisted session already has).
+//     Returns the existing sessionId. Keeps CC's prompt cache warm.
+//   REBUILD — no session yet, or pi's history has diverged (non-trailing
+//     missed messages, e.g. another provider took a turn). Wipes the existing
+//     session file (if any) and writes a fresh one containing all prior
+//     messages, reusing the same sessionId across rebuilds so UUIDs stay
+//     stable for the lifetime of pi's session.
+//
+// Why a full rebuild rather than patching:
+//   Injecting deltas into an existing session creates a branch that CC's
+//   --resume doesn't follow (documented attempt prior to this). A complete
+//   overwrite at the same path is simpler and correct.
+//
+// Why reuse the sessionId across rebuilds:
+//   CC re-reads the JSONL on every --resume call — no in-process UUID
+//   caching. Validated in tests/exp-session-clear.mjs, including the case
+//   where CC had appended its own tool_use/tool_result records between
+//   rebuilds. Preserving the UUID means stable log correlation across
+//   provider switches and no orphaned session files.
+//
+// Log strings still say "Case 1/2/3/4" so existing diagnostics (int-cache.sh,
+// int-session-resume.mjs) keep grepping the same anchors.
+function syncSharedSession(
+	messages: Context["messages"],
+	cwd: string,
+	customToolNameToSdk?: Map<string, string>,
+	modelId?: string,
+): SyncResult {
+	const priorMessages = messages.slice(0, -1); // everything before the new user prompt
+
+	// REUSE path
+	//
+	// Guard on priorMessages.length >= cursor: a shorter incoming context cannot
+	// be a continuation of the cached session. This is the general invariant for
+	// pi-side history rewrites such as /compact and session_tree: without it,
+	// missed = [].slice(cursor) can falsely hit REUSE and resume an unrelated
+	// longer CC session. See issue #25.
+	if (sharedSession && !sharedSession.needsRebuild && priorMessages.length >= sharedSession.cursor) {
+		const missed = priorMessages.slice(sharedSession.cursor);
+		const trailingAssistantOnly =
+			missed.length === 1 && (missed[0] as { role?: string }).role === "assistant";
+		if (missed.length === 0 || trailingAssistantOnly) {
+			if (trailingAssistantOnly) {
+				sharedSession = { ...sharedSession, cursor: priorMessages.length, cwd };
+			}
+			debug(`Case 3: ${trailingAssistantOnly ? "advanced cursor past trailing assistant, " : ""}resuming session ${sharedSession.sessionId.slice(0, 8)}, cursor=${sharedSession.cursor}`);
+			debug(`syncResult: path=reuse sessionId=${sharedSession.sessionId} cursor=${sharedSession.cursor}`);
+			return { sessionId: sharedSession.sessionId };
+		}
+	}
+	// Only reachable when needsRebuild is false — user-facing history rewrites
+	// (/compact, session_tree, /new, fork) always set needsRebuild or clear
+	// sharedSession before the next syncSharedSession call. In practice this
+	// fires only for isolated compact-summary subprocesses.
+	if (sharedSession && !sharedSession.needsRebuild && priorMessages.length < sharedSession.cursor) {
+		debug(`Case 1 synthetic: clean start for shorter context, preserving shared session ${sharedSession.sessionId.slice(0, 8)}, cursor=${sharedSession.cursor}`);
+		debug(`syncResult: path=clean-start preserve-shared sessionId=${sharedSession.sessionId} cursor=${sharedSession.cursor}`);
+		return { sessionId: null, preserveSharedSession: true };
+	}
+
+	// REBUILD path
+	if (priorMessages.length === 0) {
+		debug(`Case 1: clean start, ${messages.length} total messages`);
+		debug(`syncResult: path=clean-start`);
+		return { sessionId: null };
+	}
+	const previousSessionId = sharedSession?.sessionId;
+	const previousCursor = sharedSession?.cursor ?? 0;
+	// preserveId: rebuild in place (deleteSession + createSession with the
+	// existing UUID), so prompt-cache UUIDs stay stable for log correlation
+	// and for any tools that key off them. Skipped only when there's a
+	// concurrent writer we shouldn't race — see forceRotate docs above.
+	const preserveId = previousSessionId !== undefined && !sharedSession?.forceRotate;
+	if (preserveId) {
+		// Wipe prior jsonl + companion dir (no-op if nothing to wipe).
+		deleteSession(previousSessionId!, cwd, process.env.CODEBUDDY_CONFIG_DIR);
+	}
+	const session = createSession({
+		projectPath: cwd,
+		codebuddyDir: process.env.CODEBUDDY_CONFIG_DIR,
+		...(preserveId ? { sessionId: previousSessionId } : {}),
+		...(modelId ? { model: modelId } : {}),
+	});
+	convertAndImportMessages(session, priorMessages, customToolNameToSdk);
+	session.save();
+	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
+	sharedSession = { sessionId: session.sessionId, cursor: priorMessages.length, cwd };
+	if (previousSessionId === undefined) {
+		debug(`Case 2: first turn with ${priorMessages.length} prior messages → session ${session.sessionId.slice(0, 8)}, ${session.messages.length} records`);
+	} else if (preserveId) {
+		const missedCount = priorMessages.length - previousCursor;
+		debug(`Case 4: ${missedCount} missed messages, ${priorMessages.length} total → rewrote session ${session.sessionId.slice(0, 8)} (same id), ${session.messages.length} records`);
+	} else {
+		debug(`Case 4 post-abort: ${priorMessages.length} total → new session ${session.sessionId.slice(0, 8)} (was ${previousSessionId.slice(0, 8)}, rotated to avoid race with orphan writer), ${session.messages.length} records`);
+	}
+	debugSessionPaths(`${session.sessionId.slice(0, 8)}`, cwd, session.jsonlPath);
+	debug(`syncResult: path=rebuild sessionId=${session.sessionId} priors=${priorMessages.length} ${previousSessionId === undefined ? "first" : preserveId ? "preserved" : "rotated-post-abort"}`);
+	return { sessionId: session.sessionId };
+}
+
+// @internal
+export const __test = {
+	resetSharedSession() {
+		sharedSession = null;
+	},
+	setSharedSession(state: SessionState | null) {
+		sharedSession = state;
+	},
+	getSharedSession() {
+		return sharedSession;
+	},
+	createDelegationSessionFromContext,
+	buildProviderBoundaryOptions,
+	buildProviderQueryOptions,
+	syncSharedSession,
+};
+
+function createDelegationSessionFromContext(
+	messages: Context["messages"] | undefined,
+	cwd: string,
+	modelId?: string,
+): string | null {
+	if (!messages?.length) return null;
+	const delegationMessages = stripToolHistoryForDelegation(messages);
+	if (!delegationMessages.length) return null;
+	const session = createSession({
+		projectPath: cwd,
+		codebuddyDir: process.env.CODEBUDDY_CONFIG_DIR,
+		...(modelId ? { model: modelId } : {}),
+	});
+	convertAndImportMessages(session, delegationMessages);
+	session.save();
+	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
+	debug(`askCodebuddy: created delegation session ${session.sessionId.slice(0, 8)} records=${session.messages.length}`);
+	return session.sessionId;
+}
+
+function stripToolHistoryForDelegation(messages: Context["messages"]): Context["messages"] {
+	return messages.flatMap((message) => {
+		if (message.role === "toolResult") return [];
+		if (message.role !== "assistant" || !Array.isArray(message.content)) return [message];
+		const content = message.content.filter((block) => block.type !== "toolCall");
+		return content.length ? [{ ...message, content }] : [];
+	}) as Context["messages"];
+}
+
+function buildProviderBoundaryOptions(settings: NonNullable<Config["provider"]>) {
+	const appendSystemPrompt = settings.appendSystemPrompt !== false;
+	const strictMcpConfigEnabled = settings.strictMcpConfig !== false;
+	const extraArgs: Record<string, string | null> = {};
+	if (strictMcpConfigEnabled) extraArgs["strict-mcp-config"] = null;
+	return {
+		appendSystemPrompt,
+		strictMcpConfigEnabled,
+		tools: [] as string[],
+		extraArgs,
+		settingSources: appendSystemPrompt
+			? undefined
+			: settings.settingSources ?? ["user", "project"] as SettingSource[],
+	};
+}
+
+function buildProviderQueryOptions(input: {
+	providerSettings: NonNullable<Config["provider"]>;
+	cliModel: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	systemPrompt?: string;
+	effort?: Effort;
+	mcpServers?: SdkQueryOptions["mcpServers"];
+	resumeSessionId?: string | null;
+	codebuddyExecutable?: string;
+	debugOptions?: CliDebugOptions;
+}): SdkQueryOptions {
+	const boundaryOptions = buildProviderBoundaryOptions(input.providerSettings);
+	return {
+		cwd: input.cwd,
+		env: input.env,
+		tools: boundaryOptions.tools,
+		permissionMode: "bypassPermissions",
+		includePartialMessages: true,
+		systemPrompt: input.systemPrompt,
+		extraArgs: { ...boundaryOptions.extraArgs, model: input.cliModel },
+		...(input.effort ? { effort: input.effort } : {}),
+		...(boundaryOptions.settingSources ? { settingSources: boundaryOptions.settingSources } : {}),
+		...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
+		...(input.resumeSessionId ? { resume: input.resumeSessionId } : {}),
+		...(input.codebuddyExecutable ? { pathToCodebuddyCode: input.codebuddyExecutable } : {}),
+		...(input.debugOptions ?? {}),
+	};
+}
+
+// --- Provider helpers: tool name mapping ---
+
+function mapToolName(name: string, customToolNameToPi?: Map<string, string>): string {
+	const normalized = name.toLowerCase();
+	const builtin = SDK_TO_PI_TOOL_NAME[normalized];
+	if (builtin) return builtin;
+	if (customToolNameToPi) {
+		const mapped = customToolNameToPi.get(name) ?? customToolNameToPi.get(normalized);
+		if (mapped) return mapped;
+	}
+	if (normalized.startsWith(MCP_TOOL_PREFIX)) return name.slice(MCP_TOOL_PREFIX.length);
+	return name;
+}
+
+// Renames for CodeBuddy SDK param names that differ from pi's native names.
+// Keys not listed here pass through unchanged, so new pi params work automatically.
+const SDK_KEY_RENAMES: Record<string, Record<string, string>> = {
+	read:  { file_path: "path" },
+	write: { file_path: "path" },
+	edit:  { file_path: "path", old_string: "oldText", new_string: "newText", old_text: "oldText", new_text: "newText" },
+};
+
+// Maps SDK tool args to pi tool args via key renaming + pass-through.
+// Pi's own prepareArguments hooks handle any structural transforms (e.g. edit oldText/newText → edits[]).
+function mapToolArgs(
+	toolName: string, args: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+	const input = args ?? {};
+	const renames = SDK_KEY_RENAMES[toolName.toLowerCase()];
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(input)) {
+		const piKey = renames?.[key] ?? key;
+		if (!(piKey in result)) result[piKey] = value; // first alias wins
+	}
+	// Pi bash has no default timeout; add a safety default
+	if (toolName.toLowerCase() === "bash" && result.timeout == null) {
+		result.timeout = 120;
+	}
+	return result;
+}
+
+// --- Provider helpers: tool resolution ---
+
+// --- Provider helpers: tool bridge ---
+
+// --- Query state ---
+// QueryContext lives in query-state.js so tests can import it without
+// activating the extension.
+
+// Global (not query state):
+let piUI: ExtensionUIContext | null = null;
+const activeQueryContexts = new Set<QueryContext>();
+
+function contextForToolResults(results: McpResult[]): QueryContext | undefined {
+	for (const result of results) {
+		const id = result.toolCallId;
+		if (!id) continue;
+		for (const queryCtx of activeQueryContexts) {
+			if (queryCtx.pendingToolCalls.has(id) || queryCtx.pendingResults.has(id) || queryCtx.turnToolCallIds.includes(id)) {
+				return queryCtx;
+			}
+		}
+	}
+	return undefined;
+}
+
+function resolveMcpTools(context: Context, excludeToolName?: string): {
+	mcpTools: Tool[];
+	customToolNameToSdk: Map<string, string>;
+	customToolNameToPi: Map<string, string>;
+} {
+	const mcpTools: Tool[] = [];
+	const customToolNameToSdk = new Map<string, string>();
+	const customToolNameToPi = new Map<string, string>();
+
+	if (!context.tools) return { mcpTools, customToolNameToSdk, customToolNameToPi };
+
+	for (const tool of context.tools) {
+		if (tool.name === excludeToolName) continue;
+		const sdkName = `${MCP_TOOL_PREFIX}${tool.name}`;
+		mcpTools.push(enhancePiToolForCodebuddy(tool));
+		customToolNameToSdk.set(tool.name, sdkName);
+		customToolNameToSdk.set(tool.name.toLowerCase(), sdkName);
+		customToolNameToPi.set(sdkName, tool.name);
+		customToolNameToPi.set(sdkName.toLowerCase(), tool.name);
+	}
+
+	return { mcpTools, customToolNameToSdk, customToolNameToPi };
+}
+
+// Creates an MCP server that bridges pi tools to the SDK. Each tool handler
+// blocks on a Promise until pi delivers the tool result via streamSimple.
+// Handlers are assigned toolCallIds from turnToolCallIds (populated when the SDK
+// emits tool_use blocks). Results are matched by ID, not position.
+// Handlers close over the captured `queryCtx`, ensuring they operate on the
+// correct query's state while multiple queries run concurrently.
+function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string, ReturnType<typeof createSdkMcpServer>> | undefined {
+	if (!tools.length) return undefined;
+	const mcpTools = tools.map((tool) => ({
+		name: tool.name,
+		description: tool.description,
+		inputSchema: jsonSchemaToZodObject(tool.parameters),
+		handler: async () => {
+			const toolCallId = queryCtx.turnToolCallIds[queryCtx.nextHandlerIdx++];
+			if (!toolCallId) debug(`WARNING: mcp handler ${tool.name} has no toolCallId (idx=${queryCtx.nextHandlerIdx - 1}, available=${queryCtx.turnToolCallIds.length})`);
+			if (toolCallId && queryCtx.pendingResults.has(toolCallId)) {
+				const result = queryCtx.pendingResults.get(toolCallId)!;
+				queryCtx.pendingResults.delete(toolCallId);
+				debug(`mcp handler: ${tool.name} [${toolCallId}] → resolved from queue (${queryCtx.pendingResults.size} remaining)`);
+				return result;
+			}
+			debug(`mcp handler: ${tool.name} [${toolCallId}] → waiting`);
+			return new Promise<McpResult>((resolve) => {
+				queryCtx.pendingToolCalls.set(toolCallId, { toolName: tool.name, resolve });
+			});
+		},
+	}));
+	const server = createSdkMcpServer({ name: MCP_SERVER_NAME, version: "1.0.0", tools: mcpTools });
+	return { [MCP_SERVER_NAME]: server };
+}
+
+// --- Usage helpers ---
+
+function updateUsage(output: AssistantMessage, usage: Record<string, number | undefined>, model: Model<any>): void {
+	if (usage.input_tokens != null) output.usage.input = usage.input_tokens;
+	if (usage.output_tokens != null) output.usage.output = usage.output_tokens;
+	if (usage.cache_read_input_tokens != null) output.usage.cacheRead = usage.cache_read_input_tokens;
+	if (usage.cache_creation_input_tokens != null) output.usage.cacheWrite = usage.cache_creation_input_tokens;
+	// CodeBuddy may report reasoning/thinking tokens separately, while pi's Usage type does not model that field.
+	const reasoning = usage.reasoning_tokens ?? usage.thinking_tokens;
+	if (reasoning != null) (output.usage as typeof output.usage & { reasoning?: number }).reasoning = reasoning;
+	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;
+	const reasoningText = reasoning != null ? ` reasoning=${reasoning}` : "";
+	debug(`usage: in=${output.usage.input} out=${output.usage.output} cacheRead=${output.usage.cacheRead} cacheWrite=${output.usage.cacheWrite} total=${output.usage.totalTokens}${reasoningText} cachePct=${cachePct}% model=${model.id}`);
+}
+
+// Log the *served* context window reported by an SDK result message
+// (modelUsage[id].contextWindow), which can differ from the window pi
+// registered (model.contextWindow) when the runtime entitlement doesn't
+// match the docs — e.g. bare Opus served 200K on Pro, or [1m] not honored.
+// The result message's modelUsage is otherwise discarded; this makes the
+// gap observable. See issue #18.
+function logServedContextWindow(label: string, message: CbMessage, model: Model<any>): void {
+	const modelUsage = (message as any).modelUsage as Record<string, { contextWindow?: number; maxOutputTokens?: number }> | undefined;
+	if (!modelUsage) return;
+	for (const [k, v] of Object.entries(modelUsage)) {
+		debug(`${label}: served contextWindow=${v.contextWindow ?? "?"} maxOutputTokens=${v.maxOutputTokens ?? "?"} servedModel=${k} registered=${model.contextWindow}`);
+		if (typeof v.contextWindow === "number") observeServedContextWindow(label, k, v.contextWindow, model);
+	}
+}
+
+function observeServedContextWindow(label: string, servedModel: string, observed: number, model: Model<any>): void {
+	if (!Number.isFinite(observed) || observed <= 0) return;
+	try {
+		const previousRegistered = MODELS.find((candidate) => candidate.id === model.id)?.contextWindow;
+		const { changed, floorChanged, record } = recordObservedContextWindow(
+			calibrationCache,
+			model.id,
+			calibrationEnvironment,
+			observed,
+		);
+		if (!changed) return;
+		saveCalibrationCache(calibrationCache);
+		const floor = record.capabilities.contextWindow?.floor;
+		if (floor != null) {
+			MODELS = MODELS.map((candidate) => (
+				candidate.id === model.id
+					? { ...candidate, contextWindow: floor }
+					: candidate
+			));
+		}
+		debug(
+			`calibration: ${label} observed=${observed} floor=${record.capabilities.contextWindow?.floor ?? "?"} ` +
+			`latest=${record.capabilities.contextWindow?.latest ?? "?"} servedModel=${servedModel} registeredBefore=${previousRegistered ?? "?"}`,
+		);
+		if (floorChanged && floor != null && previousRegistered != null && floor !== previousRegistered) {
+			scheduleCalibrationRefresh(`contextWindow:${model.id}`);
+		}
+	} catch (err) {
+		debug(`calibration: failed to persist observed context window for ${model.id}`, err);
+	}
+}
+
+// --- Effort level mapping ---
+// Pi reasoning levels → CC SDK effort levels
+
+const REASONING_TO_EFFORT: Record<string, Effort> = {
+	minimal: "low", low: "low", medium: "medium", high: "high", xhigh: "xhigh",
+};
+
+// --- Provider helpers: misc ---
+
+function mapStopReason(reason: string | undefined): "stop" | "length" | "toolUse" {
+	switch (reason) {
+		case "tool_use": return "toolUse";
+		case "max_tokens": return "length";
+		case "end_turn": default: return "stop";
+	}
+}
+
+function parsePartialJson(input: string, fallback: Record<string, unknown>): Record<string, unknown> {
+	if (!input) return fallback;
+	try { return JSON.parse(input); } catch { return fallback; }
+}
+
+
+// --- Provider: streaming function ---
+//
+// Push-based streaming with MCP tool bridge:
+// 1. streamSimple starts a query() and kicks off consumeQuery() in background
+// 2. consumeQuery() iterates the SDK generator, pushing events to currentPiStream
+// 3. On tool_use: ends the current pi stream, nulls it out. The MCP handler
+//    blocks the generator naturally — no events arrive until resolved.
+// 4. Pi executes the tool, calls streamSimple again. We swap in the new stream,
+//    resolve the MCP handler, and the generator unblocks — events flow to new stream.
+//
+// Note: resetTurnState clears turnSawStreamEvent while the generator may still
+// have queued messages from the previous turn. This is safe because step 3 nulls
+// currentPiStream, so any leftover messages hit the `!ctx().currentPiStream` guard
+// in consumeQuery and are skipped before resetTurnState runs.
+
+const completedStreams = new WeakSet<object>();
+
+function markStreamComplete(stream: AssistantMessageEventStream | null): void {
+	if (stream) completedStreams.add(stream as object);
+}
+
+function claimCurrentPiStream(stream: AssistantMessageEventStream, label: string, c: QueryContext): void {
+	if (c.currentPiStream && !completedStreams.has(c.currentPiStream as object)) {
+		debug(`WARNING: currentPiStream overwritten before terminal event (${label}); activeQuery=${Boolean(c.activeQuery)} pendingHandlers=${c.pendingToolCalls.size}`);
+	}
+	c.currentPiStream = stream;
+}
+
+function ensureTurnStarted(c: QueryContext): void {
+	if (!c.turnStarted && c.currentPiStream && c.turnOutput) {
+		c.currentPiStream!.push({ type: "start", partial: c.turnOutput });
+		c.turnStarted = true;
+	}
+}
+
+function finalizeCurrentStream(c: QueryContext, stopReason?: string): void {
+	if (!c.currentPiStream || !c.turnOutput) return;
+	debug(`provider: finalizeCurrentStream called, stopReason=${stopReason}, outputStop=${c.turnOutput!.stopReason}`);
+	if (!c.turnStarted) ensureTurnStarted(c);
+	const reason = stopReason === "length" ? "length" : "stop";
+	const stream = c.currentPiStream;
+	stream!.push({ type: "done", reason, message: c.turnOutput });
+	markStreamComplete(stream);
+	stream!.end();
+	c.currentPiStream = null;
+}
+
+/** 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. */
+function processStreamEvent(
+	message: CbMessage,
+	customToolNameToPi: Map<string, string>,
+	model: Model<any>,
+	c: QueryContext,
+): void {
+	if (!c.currentPiStream || !c.turnOutput) return;
+	c.turnSawStreamEvent = true;
+	const event = (message as CbMessage & { event: any }).event;
+
+	if (event?.type === "message_start") {
+		c.turnToolCallIds = [];
+		c.nextHandlerIdx = 0;
+		if (event.message?.usage) updateUsage(c.turnOutput, event.message.usage, model);
+		return;
+	}
+
+	if (event?.type === "content_block_start") {
+		ensureTurnStarted(c);
+		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;
+			c.turnToolCallIds.push(event.content_block.id);
+			c.turnBlocks.push({
+				type: "toolCall", id: event.content_block.id,
+				name: mapToolName(event.content_block.name, customToolNameToPi),
+				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) return;
+		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) return;
+		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),
+			);
+			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";
+		const stream = c.currentPiStream;
+		stream!.push({ type: "done", reason: "toolUse", message: c.turnOutput });
+		markStreamComplete(stream);
+		stream!.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 processAssistantMessage(message: CbMessage, model: Model<any>, customToolNameToPi: Map<string, string>, c: QueryContext): void {
+	if (c.turnSawStreamEvent) return;
+	const assistantMsg = (message as any).message;
+	if (!assistantMsg?.content) return;
+	c.turnToolCallIds = [];
+	c.nextHandlerIdx = 0;
+	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);
+			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);
+			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);
+			c.turnSawToolCall = true;
+			c.turnToolCallIds.push(block.id);
+			const mappedArgs = mapToolArgs(mapToolName(block.name, customToolNameToPi), block.input);
+			c.turnBlocks.push({
+				type: "toolCall", id: block.id,
+				name: mapToolName(block.name, customToolNameToPi),
+				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 {
+			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";
+		const stream = c.currentPiStream;
+		stream.push({ type: "done", reason: "toolUse", message: c.turnOutput });
+		markStreamComplete(stream);
+		stream.end();
+		c.currentPiStream = null;
+	}
+}
+
+/** Background consumer: iterates the SDK generator, pushing events to currentPiStream.
+ *  Runs until the query ends. Per turn, the SDK yields stream_events (deltas), then
+ *  an assistant message (completed blocks). On tool_use, the stream is ended by
+ *  whichever path handles it first (processStreamEvent or processAssistantMessage),
+ *  and the MCP handler blocks the generator until pi delivers the tool result. */
+async function consumeQuery(
+	sdkQuery: ReturnType<typeof query>,
+	customToolNameToPi: Map<string, string>,
+	model: Model<any>,
+	wasAborted: () => boolean,
+	queryCtx: QueryContext,
+): Promise<{ capturedSessionId?: string }> {
+	let capturedSessionId: string | undefined;
+
+	for await (const message of sdkQuery) {
+		if (wasAborted()) break;
+		if (!queryCtx.currentPiStream || !queryCtx.turnOutput) continue;
+
+		switch ((message as { type: string }).type) {
+			case "stream_event":
+				processStreamEvent(message, customToolNameToPi, model, queryCtx);
+				break;
+			case "assistant":
+				processAssistantMessage(message, model, customToolNameToPi, queryCtx);
+				break;
+			case "result": {
+				const resultMsg = message as Extract<CbMessage, { type: "result" }>;
+				logServedContextWindow("result", message, model);
+				if (!queryCtx.turnSawStreamEvent && resultMsg.subtype === "success") {
+					ensureTurnStarted(queryCtx);
+					const text = resultMsg.result || "";
+					queryCtx.turnBlocks.push({ type: "text", text });
+					const idx = queryCtx.turnBlocks.length - 1;
+					queryCtx.currentPiStream?.push({ type: "text_start", contentIndex: idx, partial: queryCtx.turnOutput });
+					queryCtx.currentPiStream?.push({ type: "text_delta", contentIndex: idx, delta: text, partial: queryCtx.turnOutput });
+					queryCtx.currentPiStream?.push({ type: "text_end", contentIndex: idx, content: text, partial: queryCtx.turnOutput });
+				}
+				break;
+			}
+			case "system":
+				if ((message as any).subtype === "init" && (message as any).session_id) {
+					capturedSessionId = (message as any).session_id;
+				}
+				break;
+			case "user":
+			case "file-history-snapshot":
+				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 = info.resetsAt ? new Date(info.resetsAt).toLocaleTimeString() : "unknown";
+					piUI?.notify(`CodeBuddy rate limited (${info.rateLimitType ?? "unknown"}) — resets at ${resetsAt}`, "warning");
+				} else if (info?.status === "allowed_warning") {
+					piUI?.notify(`CodeBuddy rate limit warning: ${Math.round(info.utilization ?? 0)}% used (${info.rateLimitType ?? ""})`, "warning");
+				}
+				break;
+			}
+			default:
+				debug("consumeQuery: unhandled SDK message type", message.type);
+				break;
+		}
+	}
+
+	// DEBUG: trace when consumeQuery exits
+	debug(`consumeQuery: for-await loop exited, wasAborted=${wasAborted()}, capturedSessionId=${capturedSessionId?.slice(0, 8) ?? "none"}`);
+
+	return { capturedSessionId };
+}
+
+/** Provider entry point. Pi calls this for each new prompt and each tool result.
+ *  Two cases: tool result delivery (active query) or fresh query. */
+function streamCodebuddySdk(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
+	const stream = newAssistantMessageEventStream();
+
+	// DEBUG: trace followUp message triggering
+	const lastMsgRole = context.messages[context.messages.length - 1]?.role;
+	debug(`provider: streamCodebuddySdk called, activeQuery=${!!ctx().activeQuery}, lastMsgRole=${lastMsgRole}, isReentrant=${ctx().activeQuery !== null}`);
+
+	const activeQuery = ctx().activeQuery !== null;
+	const allResults = activeQueryContexts.size > 0 ? extractAllToolResults(context) : [];
+	const resultCtx = allResults.length > 0 ? contextForToolResults(allResults) : undefined;
+	const isReentrantUserQuery = activeQuery && lastMsgRole === "user" && allResults.length === 0;
+	if (isReentrantUserQuery) {
+		debug(`provider: active query user-only call treated as reentrant fresh query, waitingHandlers=${ctx().pendingToolCalls.size}, ctx.msgs=${context.messages.length}`);
+	}
+
+	// --- Tool result delivery ---
+	// Pi appends tool results to context and calls back. Extract this turn's results
+	// (everything after the last assistant message) and match against waiting MCP
+	// handlers. Results that arrive before their handler get queued in pendingResults.
+	if (resultCtx) {
+		claimCurrentPiStream(stream, "tool-result", resultCtx);
+		resultCtx.resetTurnState(model);
+		debug(`provider: tool results, ${allResults.length} results, ${resultCtx.pendingToolCalls.size} waiting handlers, ctx.msgs=${context.messages.length}`);
+		for (const result of allResults) {
+			const id = result.toolCallId;
+			if (id && resultCtx.pendingToolCalls.has(id)) {
+				const pending = resultCtx.pendingToolCalls.get(id)!;
+				resultCtx.pendingToolCalls.delete(id);
+				debug(`provider: resolving ${pending.toolName} [${id}]${result.isError ? " (error)" : ""} contentLen=${JSON.stringify(result.content).length}`);
+				pending.resolve(result);
+			} else if (id) {
+				resultCtx.pendingResults.set(id, result);
+				debug(`provider: queued result [${id}] (${resultCtx.pendingResults.size} pending)`);
+			} else {
+				debug(`WARNING: tool result without toolCallId, cannot match`);
+			}
+			if (resultCtx.pendingToolCalls.size > 0 && resultCtx.pendingResults.size > 0) {
+				debug(`BUG: both maps non-empty! handlers=${resultCtx.pendingToolCalls.size} results=${resultCtx.pendingResults.size}`);
+			}
+		}
+		if (resultCtx.pendingToolCalls.size > 0) {
+			debug(`WARNING: ${resultCtx.pendingToolCalls.size} MCP handlers still waiting after delivering ${allResults.length} results`);
+			piUI?.notify(`CodeBuddy SDK: ${resultCtx.pendingToolCalls.size} tool handler(s) still waiting — provider may be stuck`, "warning");
+		}
+
+		// Detect user messages (steer/followUp) that pi injected into context
+		// during the active query. This happens when:
+		//   - User sends a steer while a tool is executing; pi drains the steer
+		//     queue at the turn boundary and appends it to context alongside the
+		//     tool result, then calls the provider again.
+		//   - A followUp is delivered between tool-result turns.
+		// The bridge can't forward these mid-query (the SDK query is in progress),
+		// so we save them for replay as continuation queries after consumeQuery ends.
+		if (lastMsgRole === "user") {
+			const userPrompt = extractUserPrompt(context.messages);
+			if (userPrompt) {
+				resultCtx.deferredUserMessages.push(userPrompt);
+				debug(`provider: deferred user message for replay after query (len=${userPrompt.length})`);
+			}
+		}
+
+		if (sharedSession) sharedSession.cursor = context.messages.length;
+		resultCtx.latestCursor = Math.max(resultCtx.latestCursor, context.messages.length);
+		return stream;
+	}
+
+	// --- Orphaned tool result (e.g. user aborted a tool call) ---
+	// The query is gone but pi still delivered the result. Nothing to do — just
+	// emit end_turn so pi waits for the next real user message.
+	const lastMsg = context.messages[context.messages.length - 1];
+	if (lastMsg?.role === "toolResult") {
+		debug(`provider: orphaned tool result after abort, emitting end_turn`);
+		if (sharedSession) sharedSession.cursor = context.messages.length;
+		const c = ctx();  // capture current context for the microtask
+		queueMicrotask(() => {
+			c.resetTurnState(model);
+			stream.push({ type: "done", reason: "stop", message: c.turnOutput });
+			markStreamComplete(stream);
+			stream.end();
+		});
+		return stream;
+	}
+
+	// --- Fresh query ---
+
+	// 1. Determine reentrancy. Reentrant queries get their own QueryContext so
+	//    background subagents can run concurrently with the parent query.
+	const isReentrant = activeQuery;
+	const queryCtx = isReentrant ? new QueryContext() : ctx();
+	debug(`provider: fresh query setup, isReentrant=${isReentrant}, activeContexts=${activeQueryContexts.size}`);
+
+	// 2. Fresh child context — constructor already gave us clean Maps and empty
+	//    arrays. For a reused top-level context, clear explicitly.
+	claimCurrentPiStream(stream, "fresh-query", queryCtx);
+	queryCtx.pendingToolCalls.clear();
+	queryCtx.pendingResults.clear();
+	queryCtx.deferredUserMessages = [];
+	queryCtx.resetTurnState(model);
+	queryCtx.latestCursor = 0;
+
+	const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context, askCodebuddyToolName);
+	const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
+	const syncResult = syncSharedSession(context.messages, cwd, customToolNameToSdk, model.id);
+	const { sessionId: resumeSessionId } = syncResult;
+	const promptBlocks = extractUserPromptBlocks(context.messages);
+	let promptText = extractUserPrompt(context.messages) ?? "";
+
+	// Guard: empty prompt means the last context message isn't a user message.
+	// This should never happen with per-query state — dump diagnostics if it does.
+	if (!promptText && !promptBlocks) {
+		diagDump("empty_prompt", {
+			contextLength: context.messages.length,
+			lastMsgRole: lastMsg?.role,
+			isReentrant,
+			activeQueryContexts: activeQueryContexts.size,
+			activeQueryExists: queryCtx.activeQuery !== null,
+			sharedSession: sharedSession ? { sessionId: sharedSession.sessionId.slice(0, 8), cursor: sharedSession.cursor } : null,
+			messageRoles: context.messages.map((m, i) => `[${i}]${m.role}`).join(" "),
+		});
+		// Recover: use a continuation prompt so the SDK doesn't send an empty text block
+		promptText = "[continue]";
+	}
+
+	const prompt: string | AsyncIterable<CbUserMessage> = promptBlocks
+		? wrapPromptStream(promptBlocks)
+		: promptText;
+	const mcpServers = buildMcpServers(mcpTools, queryCtx);
+	const boundaryOptions = buildProviderBoundaryOptions(providerSettings);
+	const appendSystemPrompt = boundaryOptions.appendSystemPrompt;
+	const systemPrompt = appendSystemPrompt
+		? buildCodebuddySystemPrompt(context.systemPrompt, { availableToolNames: mcpTools.map((tool) => tool.name) })
+		: undefined;
+
+	// Provider Path keeps CodeBuddy inside Pi's tool boundary: no built-in SDK
+	// tools, strict MCP by default, and no filesystem settings while Pi's system
+	// prompt override is active. Current SDK maps settingSources=undefined to
+	// `--setting-sources none`; appendSystemPrompt=false is the compatibility
+	// escape hatch that re-enables user/project settings by default.
+	const codebuddyExecutable = providerSettings.pathToCodebuddyCode;
+
+	// Prefer the model's own thinkingLevelMap when present (pi-ai 0.72+ ships
+	// per-model overrides — e.g. opus-4-7 wants xhigh→xhigh, not xhigh→max).
+	// Fall back to our generic table for older pi-ai or unmapped levels.
+	const effort = options?.reasoning
+		? ((model as any).thinkingLevelMap?.[options.reasoning] as Effort | undefined)
+			?? REASONING_TO_EFFORT[options.reasoning]
+		: undefined;
+
+	// cliModel is the actual id sent to CodeBuddy (may carry [1m]); model.id is the
+	// pi-registered id. Log cliModel so debug lines reflect what CC actually received.
+	const cliModel = codebuddyModelId(model);
+
+	const childEnv = { ...process.env, DISABLE_AUTO_COMPACT: "1" };
+	const queryOptions = buildProviderQueryOptions({
+		providerSettings,
+		cliModel,
+		cwd,
+		env: childEnv,
+		systemPrompt,
+		effort,
+		mcpServers,
+		resumeSessionId,
+		codebuddyExecutable,
+		debugOptions: makeCliDebugOptions("provider"),
+	});
+
+	debug("provider: fresh query",
+		`model=${cliModel} msgs=${context.messages.length} tools=${mcpTools.length}`,
+		`resume=${resumeSessionId?.slice(0, 8) ?? "none"} effort=${effort ?? "default"}`,
+		`appendSys=${appendSystemPrompt} strictMcp=${boundaryOptions.strictMcpConfigEnabled}`,
+		`promptLen=${promptText.length}${promptBlocks ? " [+images]" : ""}`);
+
+	// 3. Start SDK query (wait for model discovery + serialize SDK subprocess access)
+	let wasAborted = false;
+	let sdkQuery: ReturnType<typeof query> | undefined;
+	const abortCtx = queryCtx;
+
+	const requestAbort = () => {
+		void sdkQuery?.interrupt().catch(() => {});
+	};
+	const onAbort = () => {
+		wasAborted = true;
+		abortCtx.deferredUserMessages = [];
+		for (const pending of abortCtx.pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Operation aborted" }] }); }
+		abortCtx.pendingToolCalls.clear();
+		abortCtx.pendingResults.clear();
+		requestAbort();
+	};
+	if (options?.signal) {
+		if (options.signal.aborted) onAbort();
+		else options.signal.addEventListener("abort", onAbort, { once: true });
+	}
+
+	void (async () => {
+		await ensureModelsDiscovered();
+		sdkQuery = query({ prompt, options: queryOptions });
+		queryCtx.activeQuery = sdkQuery;
+		activeQueryContexts.add(queryCtx);
+
+		try {
+			const { capturedSessionId } = await consumeQuery(sdkQuery, customToolNameToPi, model, () => wasAborted, queryCtx);
+			debug(`provider: consumeQuery completed, stopReason=${queryCtx.turnOutput?.stopReason}, error=${queryCtx.turnOutput?.errorMessage}, aborted=${wasAborted}`);
+
+			if (wasAborted || options?.signal?.aborted) {
+				if (sharedSession) sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+				queryCtx.deferredUserMessages = [];
+				debug(`provider: abort detected, marked sharedSession needsRebuild + forceRotate`);
+				if (queryCtx.turnOutput) {
+					queryCtx.turnOutput.stopReason = "aborted";
+					queryCtx.turnOutput.errorMessage = "Operation aborted";
+				}
+				const errStream = queryCtx.currentPiStream;
+				errStream?.push({ type: "error", reason: "aborted", error: queryCtx.turnOutput! });
+				markStreamComplete(errStream);
+				errStream?.end();
+				queryCtx.currentPiStream = null;
+				return;
+			}
+
+			const sessionId = capturedSessionId ?? sharedSession?.sessionId;
+			if (syncResult.preserveSharedSession) {
+				if (capturedSessionId && capturedSessionId !== sharedSession?.sessionId) {
+					deleteSession(capturedSessionId, cwd, process.env.CODEBUDDY_CONFIG_DIR);
+					debug(`provider: query done, deleted ephemeral session ${capturedSessionId.slice(0, 8)} to preserve shared session`);
+				}
+				debug(`provider: query done, ignoring captured session ${capturedSessionId?.slice(0, 8) ?? "none"} to preserve shared session`);
+			} else if (sessionId) {
+				const cursor = Math.max(context.messages.length, queryCtx.latestCursor, sharedSession?.cursor ?? 0);
+				debug(`provider: query done, session=${sessionId.slice(0, 8)}, cursor=${cursor}`);
+				sharedSession = { sessionId, cursor, cwd };
+			}
+
+			while (queryCtx.deferredUserMessages.length > 0 && !isReentrant && !wasAborted) {
+				const steerPrompt = queryCtx.deferredUserMessages.shift()!;
+				debug(`provider: replaying deferred user message (len=${steerPrompt.length})`);
+				queryCtx.resetTurnState(model);
+
+				const resumeId = sharedSession?.sessionId;
+				if (!resumeId) {
+					debug(`WARNING: no session to resume for deferred message, dropping`);
+					break;
+				}
+
+				const contOptions = { ...queryOptions, resume: resumeId, ...makeCliDebugOptions("continuation") };
+				const contQuery = query({ prompt: steerPrompt, options: contOptions });
+				queryCtx.activeQuery = contQuery;
+				debug(`provider: continuation query, model=${cliModel}, resume=${resumeId.slice(0, 8)}, promptLen=${steerPrompt.length}`);
+
+				try {
+					const { capturedSessionId: contSid } = await consumeQuery(contQuery, customToolNameToPi, model, () => wasAborted, queryCtx);
+					const sid = contSid ?? sharedSession?.sessionId;
+					if (sid) sharedSession = { sessionId: sid, cursor: sharedSession?.cursor ?? 0, cwd };
+				} catch (contError) {
+					debug(`provider: continuation query error:`, contError);
+					break;
+				} finally {
+					if (wasAborted || options?.signal?.aborted) {
+						await contQuery.return().catch(() => {});
+					}
+				}
+			}
+
+			if (!isReentrant) {
+				debug("provider: clearing activeQuery before final stream completion");
+				queryCtx.activeQuery = null;
+			}
+			finalizeCurrentStream(queryCtx, queryCtx.turnOutput?.stopReason);
+		} catch (error) {
+			debug(`provider: query error, model=${cliModel}, aborted=${Boolean(options?.signal?.aborted)}, error=`, error);
+			if ((wasAborted || options?.signal?.aborted) && sharedSession) {
+				sharedSession = { ...sharedSession, needsRebuild: true, forceRotate: true };
+			} else {
+				sharedSession = null;
+			}
+			queryCtx.deferredUserMessages = [];
+			if (queryCtx.turnOutput) {
+				queryCtx.turnOutput.stopReason = options?.signal?.aborted ? "aborted" : "error";
+				queryCtx.turnOutput.errorMessage = error instanceof Error ? error.message : String(error);
+			}
+			if (!isReentrant) {
+				for (const pending of queryCtx.pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Query ended" }] }); }
+				queryCtx.pendingToolCalls.clear();
+				queryCtx.pendingResults.clear();
+				queryCtx.activeQuery = null;
+			}
+			const errStream = queryCtx.currentPiStream;
+			errStream?.push({ type: "error", reason: (queryCtx.turnOutput?.stopReason ?? "error") as "aborted" | "error", error: queryCtx.turnOutput! });
+			markStreamComplete(errStream);
+			errStream?.end();
+			queryCtx.currentPiStream = null;
+		} finally {
+			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
+			if (queryCtx.activeQuery === sdkQuery) {
+				for (const pending of queryCtx.pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Query ended" }] }); }
+				queryCtx.pendingToolCalls.clear();
+				queryCtx.pendingResults.clear();
+				queryCtx.activeQuery = null;
+			}
+			activeQueryContexts.delete(queryCtx);
+			maybeRefreshProviderRegistration(`query-finished:${cliModel}`);
+		}
+	})();
+
+	return stream;
+}
+
+// --- AskCodebuddy: prompt and wait ---
+
+async function promptAndWait(
+	prompt: string,
+	mode: "full" | "read" | "none",
+	toolCalls: Map<string, ToolCallState>,
+	signal?: AbortSignal,
+	options?: {
+		systemPrompt?: string;
+		appendSkills?: boolean;
+		onStreamUpdate?: (responseText: string) => void;
+		model?: string;
+		thinking?: string;
+		isolated?: boolean;
+		context?: Context["messages"];
+	},
+): Promise<{ responseText: string; stopReason: string }> {
+	const cwd = process.cwd();
+	const requestedModel = options?.model ?? "opus";
+	const model = resolveModel(requestedModel);
+	const modelId = model?.id ?? requestedModel;
+	const cliModel = model ? codebuddyModelId(model) : modelId;
+
+	// Session resume for shared mode: create a delegation-only session from Pi's
+	// conversation context. Do not reuse or mutate the provider sharedSession;
+	// provider sessions contain Provider Tool Guidance and Pi MCP tool history,
+	// which must not leak into AskCodebuddy's Delegation Path.
+	let resumeSessionId: string | null = null;
+	if (!options?.isolated && options?.context?.length) {
+		resumeSessionId = createDelegationSessionFromContext(options.context, cwd, modelId);
+	}
+
+	// Mode → disallowed tools
+	const disallowedTools = MODE_DISALLOWED_TOOLS[mode] ?? [];
+
+	const askSystemPrompt = options?.systemPrompt
+		? buildCodebuddySystemPrompt(options.systemPrompt, {
+			includeSkills: options.appendSkills !== false,
+			includeToolBridge: false,
+		})
+		: undefined;
+
+	// Effort
+	const effort = options?.thinking && options.thinking !== "off"
+		? REASONING_TO_EFFORT[options.thinking] : undefined;
+
+	const codebuddyExecutable = providerSettings.pathToCodebuddyCode;
+
+	const extraArgs: Record<string, string | null> = {
+		"strict-mcp-config": null,
+		model: cliModel,
+	};
+
+	debug("askCodebuddy:",
+		`mode=${mode} model=${modelId} cliModel=${cliModel} effort=${effort ?? "default"}`,
+		`isolated=${options?.isolated ?? false} resume=${resumeSessionId?.slice(0, 8) ?? "none"}`,
+		`sysPrompt=${Boolean(askSystemPrompt)} promptLen=${prompt.length}`);
+
+	const sdkQuery = query({
+		prompt,
+		options: {
+			cwd,
+			env: { ...process.env, DISABLE_AUTO_COMPACT: "1" },
+			permissionMode: "bypassPermissions",
+			...(disallowedTools.length ? { disallowedTools } : {}),
+			...(effort ? { effort } : {}),
+			systemPrompt: askSystemPrompt,
+			settingSources: ["user", "project"] as SettingSource[],
+			extraArgs,
+			...(resumeSessionId ? { resume: resumeSessionId } : {}),
+			...(options?.isolated ? { persistSession: false } : {}),
+			...(codebuddyExecutable ? { pathToCodebuddyCode: codebuddyExecutable } : {}),
+			...makeCliDebugOptions("askclaude"),
+		},
+	});
+
+	// Abort handling
+	let wasAborted = false;
+	const onAbort = () => {
+		wasAborted = true;
+		sdkQuery.interrupt().catch(() => {});
+	};
+	if (signal?.aborted) { onAbort(); throw new Error("Aborted"); }
+	signal?.addEventListener("abort", onAbort, { once: true });
+
+	let responseText = "";
+	let sdkMessageCount = 0;
+	let textDeltaCount = 0;
+	let resultSubtype: string | undefined;
+
+	try {
+		for await (const message of sdkQuery) {
+			if (wasAborted) break;
+			sdkMessageCount++;
+
+			switch (message.type) {
+				case "stream_event": {
+					const event = (message as CbMessage & { event: any }).event;
+					// Text deltas → accumulate and stream
+					if (event?.type === "content_block_delta" && event.delta?.type === "text_delta") {
+						responseText += event.delta.text;
+						textDeltaCount++;
+						options?.onStreamUpdate?.(responseText);
+					}
+					// Tool call start → track for action summary progress
+					if (event?.type === "content_block_start" && event.content_block?.type === "tool_use") {
+						debug(`askCodebuddy: tool_use start: ${event.content_block.name}`);
+						toolCalls.set(event.content_block.id, {
+							name: mapToolName(event.content_block.name),
+							status: "running",
+						});
+					}
+					break;
+				}
+				case "assistant": {
+					// Update tool calls with full input for action summary
+					for (const block of (message as any).message?.content ?? []) {
+						if (block.type === "tool_use") {
+							toolCalls.set(block.id, {
+								name: mapToolName(block.name),
+								status: "complete",
+								rawInput: block.input,
+							});
+						}
+					}
+					break;
+				}
+				case "result": {
+					resultSubtype = message.subtype;
+					const r = message as any;
+					if (r.usage) {
+						debug(`askCodebuddy: result usage: in=${r.usage.input_tokens} out=${r.usage.output_tokens} cacheRead=${r.usage.cache_read_input_tokens ?? 0} cacheWrite=${r.usage.cache_creation_input_tokens ?? 0} turns=${r.num_turns ?? "?"}`);
+					}
+					if (!responseText && message.subtype === "success" && message.result) {
+						responseText = message.result;
+					}
+					break;
+				}
+			}
+		}
+
+		const stopReason = wasAborted ? "cancelled" : "stop";
+		debug(`askCodebuddy: done`,
+			`stopReason=${stopReason} resultSubtype=${resultSubtype ?? "none"}`,
+			`sdkMessages=${sdkMessageCount} textDeltas=${textDeltaCount} responseLen=${responseText.length}`,
+			`toolCalls=${toolCalls.size}`);
+		return { responseText, stopReason };
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		void sdkQuery.interrupt().catch(() => {});
+	}
+}
+
+// --- Extension registration ---
+
+const DEFAULT_TOOL_DESCRIPTION_FULL = "Delegate to CodeBuddy for a second opinion or analysis (code review, architecture questions, debugging theories), or to autonomously handle a task. Defaults to read-only mode — use full mode when the user wants to delegate a task that requires changes. Prefer to handle straightforward tasks yourself.";
+const DEFAULT_TOOL_DESCRIPTION = "Delegate to CodeBuddy for a second opinion or analysis (code review, architecture questions, debugging theories). Read-only — CodeBuddy can explore the codebase but not make changes. Prefer to handle straightforward tasks yourself.";
+
+const PREVIEW_MAX_CHARS = 1000;
+const PREVIEW_MAX_LINES = 6;
+
+let askCodebuddyToolName = "AskCodebuddy";
+let piApi: ExtensionAPI | null = null;
+let modelsDiscovered = false;
+
+let discoverInFlight: Promise<void> | null = null;
+
+async function discoverModels(pi: ExtensionAPI): Promise<void> {
+	await withSdkGate(async () => {
+		try {
+			const codebuddyExecutable = providerSettings.pathToCodebuddyCode;
+			const q = query({
+				prompt: " ",
+				options: {
+					maxTurns: 0,
+					permissionMode: "bypassPermissions",
+					tools: [],
+					env: { ...process.env, DISABLE_AUTO_COMPACT: "1" },
+					...(codebuddyExecutable ? { pathToCodebuddyCode: codebuddyExecutable } : {}),
+					...makeCliDebugOptions("supported-models"),
+				},
+			});
+			const supported = await q.supportedModels();
+			await q.return().catch(() => {});
+			if (!supported.length) return;
+			MODELS = applyModelCalibrations(rawModelsFromSdk(supported as any));
+			registerCurrentProvider(pi);
+			modelsDiscovered = true;
+			debug(`discoverModels: registered ${MODELS.length} models from SDK`);
+		} catch (err) {
+			debug("discoverModels: failed, using fallback models", err);
+		}
+	});
+}
+
+async function ensureModelsDiscovered(): Promise<void> {
+	if (modelsDiscovered || !piApi) return;
+	discoverInFlight ??= discoverModels(piApi);
+	await discoverInFlight;
+}
+
+export default function (pi: ExtensionAPI) {
+	piApi = pi;
+	const config = loadConfig(process.cwd());
+	debug("loadConfig:", JSON.stringify(config));
+	providerSettings = config.provider ?? {};
+	calibrationEnvironment = buildCalibrationEnvironment(providerSettings.pathToCodebuddyCode);
+	calibrationCache = loadCalibrationCache();
+	MODELS = applyModelCalibrations(buildModels(FALLBACK_MODELS));
+
+	const clearSession = (event: string) => {
+		debug(`${event}: clearing session ${sharedSession?.sessionId?.slice(0, 8) ?? "none"}`);
+		sharedSession = null;
+
+		// Clear the global streamSimple if this instance registered it.
+		// This allows /reload to work — the old instance clears the flag so
+		// the new instance can register fresh without wrapping stale state.
+		const g = globalThis as Record<symbol, any>;
+		if (g[ACTIVE_STREAM_SIMPLE_KEY] === streamCodebuddySdk) {
+			debug(`${event}: clearing ACTIVE_STREAM_SIMPLE_KEY`);
+			g[ACTIVE_STREAM_SIMPLE_KEY] = undefined;
+		}
+	};
+	pi.on("session_start", (event, ctx) => {
+		piUI = ctx.ui;
+		if (event.reason === "new" || event.reason === "resume" || event.reason === "fork") {
+			clearSession(`session_start:${event.reason}`);
+		}
+	});
+	pi.on("session_shutdown", () => clearSession("session_shutdown"));
+
+	pi.on("session_before_compact", async (event, ctx) => {
+		if (ctx.model?.baseUrl !== PROVIDER_ID) return undefined;
+		debug(
+			`session_before_compact: takeover reason=${event.reason} willRetry=${event.willRetry} ` +
+			`isSplitTurn=${event.preparation.isSplitTurn} messages=${event.preparation.messagesToSummarize.length} ` +
+			`turnPrefix=${event.preparation.turnPrefixMessages.length}`,
+		);
+		try {
+			reinjectPriorCompactionFileOps(event.branchEntries, event.preparation);
+			const compaction = await compact(
+				event.preparation,
+				ctx.model,
+				undefined,
+				undefined,
+				event.customInstructions,
+				event.signal,
+				undefined,
+				isolatedStreamFn,
+				undefined,
+			);
+			debug(`session_before_compact: takeover complete summaryLen=${compaction.summary.length}`);
+			return { compaction };
+		} catch (err) {
+			const msg = errorMessage(err);
+			debug("session_before_compact: takeover failed; cancelling to avoid native compact fallback", err);
+			ctx.ui?.notify?.(
+				`CodeBuddy SDK compact failed (${redactForLog(msg)}). Retry, switch model, or reduce context.`,
+				"error",
+			);
+			return { cancel: true };
+		}
+	});
+
+	// pi /compact and session-tree navigation (rewind / fork-at-point /
+	// branch switch) both mutate pi's messages array out from under the
+	// bridge. syncSharedSession's REUSE check would otherwise see
+	// slice(cursor) === [] (or skip entries) and keep --resume'ing a CC
+	// session that no longer matches pi's history. /compact in particular
+	// triggers CC's autocompact-thrashing guard (issue #8). Force the next
+	// call down the REBUILD path so CC sees the current history.
+	const markRebuild = (event: string) => {
+		if (sharedSession) {
+			debug(`${event}: marking needsRebuild on session ${sharedSession.sessionId.slice(0, 8)}`);
+			sharedSession = { ...sharedSession, needsRebuild: true };
+		}
+	};
+	pi.on("session_compact", (event) => markRebuild(`session_compact:${event.reason}:willRetry=${event.willRetry}`));
+	pi.on("session_tree", () => markRebuild("session_tree"));
+
+	// --- Provider ---
+	//
+	// Guard against re-registration when the module is loaded multiple times
+	// (e.g., when spawning subagents). The shared ModelRegistry would otherwise
+	// overwrite the parent's streamSimple, breaking tool result delivery.
+	// See ACTIVE_STREAM_SIMPLE_KEY for the full mechanism.
+
+	const g = globalThis as Record<symbol, any>;
+	if (!g[ACTIVE_STREAM_SIMPLE_KEY]) {
+		// First instance: store our streamSimple and register.
+		g[ACTIVE_STREAM_SIMPLE_KEY] = streamCodebuddySdk;
+		registerCurrentProvider(pi);
+		discoverInFlight = discoverModels(pi);
+	} else {
+		// Subsequent instance (subagent session): skip registration entirely.
+		// The subagent already has access to codebuddy-sdk models via the shared
+		// ModelRegistry from the parent's registration. Calls to those models
+		// route through the parent's streamSimple via reentrant QueryContexts.
+		debug(`provider: skipping re-registration, parent instance active (module=${moduleInstanceId})`);
+	}
+
+	// --- AskCodebuddy tool ---
+
+	const askConf = config.askCodebuddy;
+	const allowFull = askConf?.allowFullMode !== false;
+	const defaultMode = askConf?.defaultMode ?? "read";
+	const defaultIsolated = askConf?.defaultIsolated ?? false;
+	askCodebuddyToolName = askConf?.name ?? "AskCodebuddy";
+
+	const modeValues = allowFull ? ["read", "full", "none"] as const : ["read", "none"] as const;
+	let modeDesc = `"read" (default): questions about the codebase — review, analysis, explain. "none": general knowledge only (no file access).`;
+	if (allowFull) modeDesc += ` "full": allows writing and bash execution (careful: runs without feedback to pi).`;
+
+	if (askConf?.enabled !== false) {
+		const askCodebuddyParams = Type.Object({
+			prompt: Type.String({ description: "The question or task for CodeBuddy. By default Claude sees the full conversation history. Don't research up front, let Claude explore." }),
+			mode: Type.Optional(StringEnum(modeValues, { description: modeDesc })),
+			model: Type.Optional(Type.String({ description: 'Claude model (e.g. "opus", "sonnet", "haiku", or full ID). Defaults to "opus".' })),
+			thinking: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const, { description: "Thinking effort level. Omit to use CodeBuddy's default." })),
+			isolated: Type.Optional(Type.Boolean({ description: "When true, Claude sees only this prompt (clean session). When false (default), Claude sees the full conversation history." })),
+		});
+		pi.registerTool<typeof askCodebuddyParams>({
+			name: askConf?.name ?? "AskCodebuddy",
+			label: askConf?.label ?? "Ask CodeBuddy",
+			description: askConf?.description ?? (allowFull ? DEFAULT_TOOL_DESCRIPTION_FULL : DEFAULT_TOOL_DESCRIPTION),
+			parameters: askCodebuddyParams,
+			renderCall(args, theme) {
+				let text = theme.fg("mdLink", theme.bold("AskCodebuddy "));
+				const mode = args.mode ?? defaultMode;
+				const tags: string[] = [];
+				if (mode !== defaultMode) tags.push(`mode=${mode}`);
+				if (args.model) tags.push(`model=${args.model}`);
+				if (args.thinking) tags.push(`thinking=${args.thinking}`);
+				if (args.isolated) tags.push("isolated");
+				if (tags.length) text += `${theme.fg("accent", `[${tags.join(", ")}]`)} `;
+				const truncated = args.prompt.length > PREVIEW_MAX_CHARS ? args.prompt.substring(0, PREVIEW_MAX_CHARS) : args.prompt;
+				const lines = truncated.split("\n").slice(0, PREVIEW_MAX_LINES);
+				text += theme.fg("muted", `"${lines.join("\n")}"`);
+				if (args.prompt.length > PREVIEW_MAX_CHARS || args.prompt.split("\n").length > PREVIEW_MAX_LINES) text += theme.fg("dim", " …");
+				return new Text(text, 0, 0);
+			},
+			renderResult(result, { expanded, isPartial }, theme) {
+				if (isPartial) {
+					const status = result.content[0]?.type === "text" ? result.content[0].text : "working...";
+					return new Text(theme.fg("mdLink", "◉ CodeBuddy ") + theme.fg("muted", status), 0, 0);
+				}
+
+				const details = result.details as { prompt?: string; executionTime?: number; actions?: string; error?: boolean } | undefined;
+				const body = result.content[0]?.type === "text" ? result.content[0].text : "";
+
+				let text = details?.error
+					? theme.fg("error", "✗ CodeBuddy error")
+					: theme.fg("mdLink", "✓ CodeBuddy");
+
+				if (details?.executionTime) text += ` ${theme.fg("dim", `${(details.executionTime / 1000).toFixed(1)}s`)}`;
+				if (details?.actions) text += ` ${theme.fg("muted", details.actions)}`;
+
+				if (expanded) {
+					if (details?.prompt) text += `\n${theme.fg("dim", `Prompt: ${details.prompt}`)}`;
+					if (details?.prompt && body) text += `\n${theme.fg("dim", "─".repeat(40))}`;
+					if (body) text += `\n${theme.fg("toolOutput", body)}`;
+				} else {
+					const truncated = body.length > PREVIEW_MAX_CHARS ? body.substring(0, PREVIEW_MAX_CHARS) : body;
+					const lines = truncated.split("\n").slice(0, PREVIEW_MAX_LINES);
+					if (lines.length) text += `\n${theme.fg("toolOutput", lines.join("\n"))}`;
+					if (body.length > PREVIEW_MAX_CHARS || body.split("\n").length > PREVIEW_MAX_LINES) text += `\n${theme.fg("dim", `… (${keyHint("app.tools.expand", "to expand")})`)}`;
+
+				}
+
+				return new Text(text, 0, 0);
+			},
+			async execute(_id, params, signal, onUpdate, ctx) {
+				// Guard: circular delegation
+				if (ctx.model?.baseUrl === PROVIDER_ID) {
+					debug("askCodebuddy: blocked circular delegation (active provider is codebuddy-sdk)");
+					return {
+						content: [{ type: "text" as const, text: "Error: AskCodebuddy cannot be used when the active provider is codebuddy-sdk — you're already running through CodeBuddy." }],
+						details: { error: true },
+					};
+				}
+
+				const mode = (params.mode ?? defaultMode) as "full" | "read" | "none";
+				const isolated = params.isolated ?? defaultIsolated;
+				const toolCalls = new Map<string, ToolCallState>();
+				const start = Date.now();
+
+				const progressInterval = setInterval(() => {
+					const elapsed = ((Date.now() - start) / 1000).toFixed(0);
+					const summary = buildActionSummary(toolCalls);
+					const status = summary ? `${elapsed}s — ${summary}` : `${elapsed}s — working...`;
+					onUpdate?.({
+						content: [{ type: "text", text: status }],
+						details: { prompt: params.prompt, executionTime: Date.now() - start },
+					});
+				}, 1000);
+
+				try {
+					const result = await promptAndWait(params.prompt, mode, toolCalls, signal, {
+						systemPrompt: ctx.getSystemPrompt(),
+						appendSkills: askConf?.appendSkills,
+						model: params.model,
+						thinking: params.thinking,
+						isolated,
+						context: isolated ? undefined : buildSessionContext(ctx.sessionManager.getBranch()).messages as Context["messages"],
+					});
+					clearInterval(progressInterval);
+					onUpdate?.({ content: [{ type: "text", text: "" }], details: {} });
+					const executionTime = Date.now() - start;
+					const actions = buildActionSummary(toolCalls);
+
+					const text = actions
+						? `${result.responseText}\n\n[CodeBuddy actions: ${actions}]`
+						: result.responseText;
+					return {
+						content: [{ type: "text" as const, text }],
+						details: { prompt: params.prompt, executionTime, actions },
+					};
+				} catch (err) {
+					clearInterval(progressInterval);
+					debug(`askCodebuddy error: mode=${mode}, model=${params.model ?? "default"}, isolated=${isolated}, elapsed=${((Date.now() - start) / 1000).toFixed(1)}s, error=`, err);
+					const msg = errorMessage(err);
+					return {
+						content: [{ type: "text" as const, text: `Error: ${msg}` }],
+						details: { prompt: params.prompt, executionTime: Date.now() - start, error: true },
+					};
+				}
+			},
+		});
+	}
+}