@vanillagreen/pi-claude-bridge 1.8.0 → 2.0.0

package/src/session-persistence.ts

@@ -0,0 +1,334 @@
+import { type AssistantMessage, type Context } from "@earendil-works/pi-ai";
+import { createSession, deleteSession, openSession, repairToolPairing } from "cc-session-io";
+import { createHash } from "crypto";
+import { realpathSync, statSync } from "fs";
+import { resolve as pathResolve } from "path";
+import { extensionApi, piUI, reportSyntheticToolResultRepair, setSharedSession, sharedSession, type SessionState } from "./bridge-state.js";
+import { convertPiMessages } from "./convert.js";
+import { DEBUG, DEBUG_LOG_PATH, debug, diagDump } from "./debug.js";
+import { verifyWrittenSession as _verifyWrittenSession } from "./session-verify.js";
+import { findUnpairedToolUses, insertLostToolResultPlaceholders } from "./tool-pairing-audit.js";
+
+// --- Session persistence ---
+
+const BRIDGE_SESSION_CUSTOM_TYPE = "claude-bridge-session";
+
+interface PersistedBridgeSessionState extends SessionState {
+	fingerprint: string;
+	piSessionId?: string;
+	updatedAt: string;
+}
+
+function fingerprintMessages(messages: Context["messages"]): string {
+	const normalized = messages.map((message) => {
+		if (message.role === "assistant") {
+			return {
+				role: message.role,
+				provider: (message as AssistantMessage).provider,
+				model: (message as AssistantMessage).model,
+				content: (message as AssistantMessage).content,
+			};
+		}
+		return message;
+	});
+	return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+}
+
+function readBuiltSessionContext(sessionManager: unknown): { messages: Context["messages"] } | undefined {
+	const built = typeof (sessionManager as any)?.buildSessionContext === "function" ? (sessionManager as any).buildSessionContext() : undefined;
+	return Array.isArray(built?.messages) ? built as { messages: Context["messages"] } : undefined;
+}
+
+function latestPersistedBridgeSession(sessionManager: unknown): PersistedBridgeSessionState | undefined {
+	const entries = typeof (sessionManager as any)?.getEntries === "function" ? (sessionManager as any).getEntries() : [];
+	if (!Array.isArray(entries)) return undefined;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry?.type !== "custom" || entry.customType !== BRIDGE_SESSION_CUSTOM_TYPE) continue;
+		const data = entry.data as Partial<PersistedBridgeSessionState> | undefined;
+		if (!data || typeof data.sessionId !== "string" || typeof data.cursor !== "number" || typeof data.cwd !== "string" || typeof data.fingerprint !== "string") continue;
+		return data as PersistedBridgeSessionState;
+	}
+	return undefined;
+}
+
+function claudeSessionExists(sessionId: string, cwd: string): boolean {
+	try {
+		const session = openSession({ sessionId, projectPath: cwd, claudeDir: process.env.CLAUDE_CONFIG_DIR });
+		statSync(session.jsonlPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function canonicalize(p: string | undefined): string | undefined {
+	if (!p) return undefined;
+	try { return realpathSync.native(p); } catch { return pathResolve(p); }
+}
+
+// Decides whether a persisted bridge-session marker is safe to restore.
+//
+// The fork case is the load-bearing one: pi/core's createBranchedSession copies
+// every non-label entry from root→leaf into the new session file. That includes
+// our claude-bridge-session markers from the parent. Restoring from them would
+// --resume parent's Claude jsonl on the fork's first turn, leaking conversation
+// past the fork point.
+//
+// Returns undefined when the entry is safe to use, or a short rejection reason
+// for diagnostic logging. Old entries without piSessionId always reject, which
+// degrades safely to the rebuild path.
+export function shouldRestorePersistedBridgeEntry(
+	persisted: { piSessionId?: string; cwd: string },
+	currentPiSessionId: string | undefined,
+	currentCwd: string | undefined,
+): string | undefined {
+	if (!persisted.piSessionId) return "missing piSessionId";
+	if (currentPiSessionId && persisted.piSessionId !== currentPiSessionId) {
+		return `piSessionId mismatch (persisted=${persisted.piSessionId} current=${currentPiSessionId})`;
+	}
+	if (currentCwd && canonicalize(persisted.cwd) !== canonicalize(currentCwd)) {
+		return `cwd mismatch (persisted=${persisted.cwd} current=${currentCwd})`;
+	}
+	return undefined;
+}
+
+export function restoreSharedSessionFromPi(ctx: { sessionManager?: unknown; cwd?: string }): void {
+	const persisted = latestPersistedBridgeSession(ctx.sessionManager);
+	if (!persisted) return;
+	const currentPiSessionId = typeof (ctx.sessionManager as any)?.getSessionId === "function" ? (ctx.sessionManager as any).getSessionId() : undefined;
+	const currentCwd = typeof (ctx.sessionManager as any)?.getCwd === "function" ? (ctx.sessionManager as any).getCwd() : ctx.cwd;
+	const rejection = shouldRestorePersistedBridgeEntry(persisted, currentPiSessionId, currentCwd);
+	if (rejection) {
+		debug(`restoreSharedSession: ${rejection} — forcing rebuild`);
+		return;
+	}
+	const built = readBuiltSessionContext(ctx.sessionManager);
+	if (!built) return;
+	const cursor = Math.max(0, Math.min(persisted.cursor, built.messages.length));
+	const fingerprint = fingerprintMessages(built.messages.slice(0, cursor));
+	if (fingerprint !== persisted.fingerprint) {
+		debug(`restoreSharedSession: fingerprint mismatch for ${persisted.sessionId.slice(0, 8)}`);
+		return;
+	}
+	if (!claudeSessionExists(persisted.sessionId, persisted.cwd)) {
+		debug(`restoreSharedSession: Claude session missing for ${persisted.sessionId.slice(0, 8)}`);
+		return;
+	}
+	setSharedSession({ sessionId: persisted.sessionId, cursor, cwd: persisted.cwd });
+	debug(`restoreSharedSession: restored ${persisted.sessionId.slice(0, 8)}, cursor=${cursor}`);
+}
+
+export function schedulePersistSharedSession(ctxLike?: { sessionManager?: unknown }): void {
+	if (!extensionApi || !sharedSession || !ctxLike?.sessionManager) return;
+	const snapshot = { ...sharedSession };
+	const timer = setTimeout(() => {
+		try {
+			const built = readBuiltSessionContext(ctxLike.sessionManager);
+			if (!built) return;
+			const cursor = Math.max(0, Math.min(snapshot.cursor, built.messages.length));
+			const data: PersistedBridgeSessionState = {
+				...snapshot,
+				cursor,
+				fingerprint: fingerprintMessages(built.messages.slice(0, cursor)),
+				piSessionId: typeof (ctxLike.sessionManager as any)?.getSessionId === "function" ? (ctxLike.sessionManager as any).getSessionId() : undefined,
+				updatedAt: new Date().toISOString(),
+			};
+			extensionApi?.appendEntry(BRIDGE_SESSION_CUSTOM_TYPE, data);
+			debug(`persistSharedSession: saved ${data.sessionId.slice(0, 8)}, cursor=${data.cursor}`);
+		} catch (error) {
+			debug("persistSharedSession failed:", error);
+		}
+	}, 0);
+	timer.unref?.();
+}
+
+// Convert pi messages to Anthropic API format for session import.
+// Lossy: non-Anthropic thinking blocks are dropped (no valid signature). User and
+// tool-result image blocks are preserved when possible. If assistant blocks are
+// otherwise incompatible, convertPiMessages emits a text placeholder so the record
+// sequence stays valid before repairToolPairing runs.
+function convertAndImportMessages(
+	session: ReturnType<typeof createSession>,
+	messages: Context["messages"],
+	customToolNameToSdk?: Map<string, string>,
+	cwd?: 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) => 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(", "));
+	}
+	// Pre-repair: pair every orphaned tool_use with an EXPLICIT bridge-authored
+	// error result before cc-session-io's repairToolPairing can backfill its bare
+	// "[no tool result recorded]" placeholder — which the model reads as tool
+	// output and silently reasons on. Ours is is_error and says what to do.
+	// repairToolPairing still runs after (idempotent; finds nothing left).
+	const missingToolResults = findUnpairedToolUses(anthropicMessages);
+	if (missingToolResults.length > 0) insertLostToolResultPlaceholders(anthropicMessages, missingToolResults);
+	const repaired = repairToolPairing(anthropicMessages);
+	if (missingToolResults.length > 0) {
+		reportSyntheticToolResultRepair(missingToolResults, {
+			cwd,
+			messageCount: messages.length,
+			anthropicMessageCount: anthropicMessages.length,
+			sessionId: session.sessionId,
+			jsonlPath: session.jsonlPath,
+		});
+	}
+	if (repaired.length !== anthropicMessages.length) {
+		debug(`convertAndImportMessages: repairToolPairing ${anthropicMessages.length} → ${repaired.length} msgs`);
+	}
+	if (repaired.length) session.importMessages(repaired);
+}
+
+interface SyncResult {
+	sessionId: string | null;
+}
+
+/**
+ * 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 file issue: ${msg}\n` +
+			`cwd=${cwd} realpath=${safeRealpath(cwd)} CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR ?? "(unset)"}\n` +
+			`Please copy and paste this message into a new issue at https://github.com/elidickinson/pi-claude-bridge/issues/new` +
+			(DEBUG ? ` and attach ${DEBUG_LOG_PATH}` : ` (rerun with CLAUDE_BRIDGE_DEBUG=1 to capture a debug log)`),
+			"warning",
+		);
+		diagDump("session_verify_fail", { msg, jsonlPath, cwd, realpath: safeRealpath(cwd), claudeConfigDir: process.env.CLAUDE_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, CLAUDE_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=${cwd}`);
+	if (realCwd !== cwd) debug(`${label}: realpath(cwd)=${realCwd} (DIFFERS — symlink-resolved path is what CC SDK uses)`);
+	debug(`${label}: jsonlPath=${jsonlPath}`);
+	debug(`${label}: fileExists=${fileExists}${fileSize != null ? ` size=${fileSize}` : ""}`);
+	debug(`${label}: env.CLAUDE_CONFIG_DIR=${process.env.CLAUDE_CONFIG_DIR ?? "(unset)"} HOME=${process.env.HOME ?? "(unset)"}`);
+}
+
+// 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.
+export 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
+	if (sharedSession && !sharedSession.needsRebuild) {
+		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) {
+				setSharedSession({ ...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 };
+		}
+	}
+
+	// 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.CLAUDE_CONFIG_DIR);
+	}
+	const session = createSession({
+		projectPath: cwd,
+		claudeDir: process.env.CLAUDE_CONFIG_DIR,
+		...(preserveId ? { sessionId: previousSessionId } : {}),
+		...(modelId ? { model: modelId } : {}),
+	});
+	convertAndImportMessages(session, priorMessages, customToolNameToSdk, cwd);
+	session.save();
+	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
+	setSharedSession({ 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 };
+}

package/src/stream-idle-watchdog.ts

@@ -0,0 +1,134 @@
+import { type AssistantMessage, type AssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { type QueryContext } from "./query-state.js";
+
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 90_000;
+export const STREAM_IDLE_BACKOFF_HINT_MS = 60_000;
+export const STREAM_IDLE_TIMEOUT_ENV = "CLAUDE_BRIDGE_STREAM_IDLE_TIMEOUT";
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface StreamIdleWatchdogState {
+	activeQuery: unknown | null;
+	currentPiStream: AssistantMessageEventStream | null;
+	turnOutput: AssistantMessage | null;
+	turnSawStreamEvent: boolean;
+	turnStarted: boolean;
+}
+
+export interface StreamIdleTimeoutInfo {
+	idleMs: number;
+	timeoutMs: number;
+}
+
+export interface StreamIdleWatchdog {
+	dispose: () => void;
+	noteChunk: () => void;
+	refresh: () => void;
+	timedOut: () => boolean;
+}
+
+export const activeStreamIdleWatchdogs = new WeakMap<QueryContext, StreamIdleWatchdog>();
+
+function parseDurationLiteralMs(value: string, defaultUnit: "ms" | "s" = "s"): number | undefined {
+	const text = value.trim().toLowerCase();
+	if (!text) return undefined;
+	if (["off", "false", "disabled", "disable"].includes(text)) return 0;
+	const match = text.match(/^(\d+(?:\.\d+)?)\s*(ms|msec|msecs|milliseconds?|s|sec|secs|seconds?|m|min|mins|minutes?)?$/i);
+	if (!match) return undefined;
+	const amount = Number(match[1]);
+	if (!Number.isFinite(amount) || amount < 0) return undefined;
+	const unit = (match[2] ?? defaultUnit).toLowerCase();
+	const multiplier = ["ms", "msec", "msecs", "millisecond", "milliseconds"].includes(unit)
+		? 1
+		: ["s", "sec", "secs", "second", "seconds"].includes(unit)
+			? 1000
+			: ["m", "min", "mins", "minute", "minutes"].includes(unit)
+				? 60_000
+				: undefined;
+	if (multiplier === undefined) return undefined;
+	const ms = Math.round(amount * multiplier);
+	return Number.isFinite(ms) ? ms : undefined;
+}
+
+export function streamIdleTimeoutMsFromEnv(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env[STREAM_IDLE_TIMEOUT_ENV]?.trim();
+	if (!raw) return DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+	return parseDurationLiteralMs(raw, "s") ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+}
+
+export function formatDurationShort(ms: number): string {
+	if (ms < 180_000 && ms % 1000 === 0) return `${ms / 1000}s`;
+	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+	if (ms % 1000 === 0) return `${ms / 1000}s`;
+	return `${ms}ms`;
+}
+
+export function buildStreamIdleTimeoutErrorMessage(timeoutMs: number): string {
+	return `Claude Code stream idle timeout after ${formatDurationShort(timeoutMs)} with no assistant/tool output; treating stalled stream as retryable 529 overloaded/rate limit condition. Retry after ${formatDurationShort(STREAM_IDLE_BACKOFF_HINT_MS)}.`;
+}
+
+export function createStreamIdleWatchdog({
+	clearTimer = (timer: TimerHandle) => clearTimeout(timer),
+	getState,
+	now = () => Date.now(),
+	onTimeout,
+	setTimer = (fn: () => void, delayMs: number) => setTimeout(fn, delayMs),
+	timeoutMs,
+}: {
+	clearTimer?: (timer: TimerHandle) => void;
+	getState: () => StreamIdleWatchdogState;
+	now?: () => number;
+	onTimeout: (info: StreamIdleTimeoutInfo) => void;
+	setTimer?: (fn: () => void, delayMs: number) => TimerHandle;
+	timeoutMs: number;
+}): StreamIdleWatchdog {
+	let disposed = false;
+	let lastChunkAt = now();
+	let timer: TimerHandle | null = null;
+	let didTimeout = false;
+
+	const clear = () => {
+		if (!timer) return;
+		try { clearTimer(timer); } catch { /* best effort */ }
+		timer = null;
+	};
+
+	const shouldMonitor = (state: StreamIdleWatchdogState): boolean => Boolean(
+		timeoutMs > 0
+		&& state.activeQuery
+		&& state.currentPiStream
+		&& state.turnOutput
+		&& !state.turnStarted
+		&& !state.turnSawStreamEvent,
+	);
+
+	const schedule = () => {
+		clear();
+		if (disposed || didTimeout || timeoutMs <= 0) return;
+		const state = getState();
+		if (!shouldMonitor(state)) return;
+		const turnStartedAt = typeof state.turnOutput?.timestamp === "number" ? state.turnOutput.timestamp : 0;
+		const idleStartedAt = Math.max(lastChunkAt, turnStartedAt);
+		const idleMs = Math.max(0, now() - idleStartedAt);
+		if (idleMs >= timeoutMs) {
+			didTimeout = true;
+			onTimeout({ idleMs, timeoutMs });
+			return;
+		}
+		timer = setTimer(schedule, Math.max(1, timeoutMs - idleMs));
+		(timer as { unref?: () => void }).unref?.();
+	};
+
+	return {
+		dispose: () => {
+			disposed = true;
+			clear();
+		},
+		noteChunk: () => {
+			lastChunkAt = now();
+			schedule();
+		},
+		refresh: schedule,
+		timedOut: () => didTimeout,
+	};
+}

package/src/tool-mapping.ts

@@ -0,0 +1,53 @@
+import { MCP_SERVER_NAME, MCP_TOOL_PREFIX } from "./skills.js";
+
+const SDK_TO_PI_TOOL_NAME: Record<string, string> = {
+	read: "read", write: "write", edit: "edit", bash: "bash",
+};
+
+// --- Provider helpers: tool name mapping ---
+
+export 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;
+	}
+	for (const prefix of [
+		MCP_TOOL_PREFIX,
+		`mcp__${MCP_SERVER_NAME.replace(/-/g, "_")}__`,
+		`mcp/${MCP_SERVER_NAME}/`,
+		`mcp/${MCP_SERVER_NAME.replace(/-/g, "_")}/`,
+	]) {
+		if (normalized.startsWith(prefix)) return normalized.slice(prefix.length);
+	}
+	return name;
+}
+
+// Renames for Claude Code 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[]).
+export 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;
+}

package/src/tool-pairing-audit.ts

@@ -52,6 +52,54 @@ export function findUnpairedToolUses(messages: Array<{ role?: string; content?:
 	return missing;
 }
 
+export const LOST_TOOL_RESULT_TEXT =
+	"Claude bridge: the result of this tool call was lost before the session was rebuilt "
+	+ "(the turn was interrupted). Treat the call as failed — it may or may not have executed. "
+	+ "Re-run the tool if its output is still needed.";
+
+/**
+ * Insert explicit, bridge-authored error results for every unpaired tool_use,
+ * IN PLACE, before cc-session-io's repairToolPairing runs.
+ *
+ * repairToolPairing backfills with a bare "[no tool result recorded]" — a
+ * placeholder the model reads as tool OUTPUT and keeps reasoning on (observed:
+ * two bash calls in the 2026-07-28 token test, silently treated as if they had
+ * returned). An is_error result that says what happened and what to do turns a
+ * silent correctness hazard into a recoverable failure.
+ *
+ * Results are prepended to the immediately following user message (tool_result
+ * blocks must lead a user message), or a new user message is inserted when none
+ * follows. `missing` must come from findUnpairedToolUses on the same array.
+ */
+export function insertLostToolResultPlaceholders(
+	messages: Array<{ role?: string; content?: unknown }>,
+	missing: MissingToolResult[],
+): void {
+	const block = (id: string) => ({ type: "tool_result", tool_use_id: id, content: LOST_TOOL_RESULT_TEXT, is_error: true });
+	const byAssistant = new Map<number, MissingToolResult[]>();
+	for (const item of missing) {
+		const group = byAssistant.get(item.assistantIndex) ?? [];
+		group.push(item);
+		byAssistant.set(item.assistantIndex, group);
+	}
+	// Descending order so inserting a new user message never shifts an index a
+	// later (earlier-in-array) group still needs.
+	for (const assistantIndex of [...byAssistant.keys()].sort((a, b) => b - a)) {
+		const group = byAssistant.get(assistantIndex)!;
+		const blocks = group.map((item) => block(item.id));
+		const userIndex = group[0].userIndex;
+		if (userIndex != null && messages[userIndex]?.role === "user") {
+			const user = messages[userIndex] as { role: string; content: unknown };
+			const existing = typeof user.content === "string"
+				? (user.content ? [{ type: "text", text: user.content }] : [])
+				: Array.isArray(user.content) ? user.content : [];
+			user.content = [...blocks, ...existing];
+		} else {
+			messages.splice(assistantIndex + 1, 0, { role: "user", content: blocks });
+		}
+	}
+}
+
 export function summarizeMissingToolNames(missing: MissingToolResult[]): Array<{ name: string; count: number }> {
 	const counts = new Map<string, number>();
 	for (const item of missing) counts.set(item.toolName, (counts.get(item.toolName) ?? 0) + 1);

package/src/typebox-to-zod.ts

@@ -28,9 +28,15 @@ export function jsonSchemaPropertyToZod(prop: Record<string, unknown>): z.ZodTyp
 		}
 		case "object": {
 			if (prop.properties && typeof prop.properties === "object" && !Array.isArray(prop.properties)) {
-				base = z.object(jsonSchemaToZodShape(prop));
-				if (prop.additionalProperties === false) base = (base as z.ZodObject<Record<string, z.ZodTypeAny>>).strict();
-				else if (prop.additionalProperties === true) base = (base as z.ZodObject<Record<string, z.ZodTypeAny>>).passthrough();
+				const obj = z.object(jsonSchemaToZodShape(prop));
+				// JSON Schema's default is PERMISSIVE (additionalProperties omitted
+				// means allowed); zod's default is to silently STRIP unknown keys.
+				// Stripping matters here: the MCP handler compares its validated
+				// input against the raw streamed tool_use input to claim a call id,
+				// so a silently dropped key made the two diverge and the claim fail
+				// (stranding the call — see claimToolCall). Only an explicit
+				// additionalProperties:false may reject/strip.
+				base = prop.additionalProperties === false ? obj.strict() : obj.passthrough();
 			} else {
 				base = z.record(z.string(), z.unknown());
 			}