pi-claude-agent-sdk 0.8.1 → 0.8.2

package/README.md

@@ -6,7 +6,7 @@ Pi extension that integrates Claude Code as a pi model provider via the [Agent S
 
 Use Opus/Sonnet/Haiku as models in pi, with all tool calls flowing through pi's TUI.
 
-**FYI:** Anthropic [announced and then unannounced](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) a change to how you would be billed for tools that use the Agent SDK like this one. As of June 15, 2026 it uses subscription quota just like Claude Code direct does.
+**FYI:** Anthropic [announced and then unannounced](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) a change to how you would be billed for tools that use the Agent SDK like this one. It currently uses your regular subscription quota just like Claude Code.
 
 <p>
 <a href="assets/claude-bridge1.png"><img src="assets/claude-bridge1.png" width="49%"></a>&nbsp;
@@ -47,8 +47,6 @@ Config: `~/.pi/agent/claude-bridge.json` (global) or the project Pi config direc
 `provider`:
 - `plan` (default `"max"`) — Max (or Team Premium/Enterprise). Set to `"pro"` on a Pro plan so Opus 4.6 stays at 200K context. If it's unset, the first interactive session points this out once, then records `startupNoticeShown` (the date, `YYYY-MM-DD`) in the global config so it doesn't nag again.
 - `longContextExtraUsage` — set to `true` to enable 1M models that cost money through Extra Usage. It enables Sonnet 4.6 with 1M on every plan and Opus 4.6 with 1M on Pro. Not needed for Opus 4.7 or 4.8.
-- `appendSystemPrompt` — append pi's project context files (global and ancestor `AGENTS.md` / `CLAUDE.md`) and skills (default `true`)
-- `settingSources` — CC filesystem settings to load; only applied when `appendSystemPrompt: false`
 - `strictMcpConfig` — block MCP servers from `~/.claude.json` / `.mcp.json` (default `true`). Cloud MCP (Gmail/Drive via claude.ai OAuth) is always blocked.
 - `autoMemoryEnabled` — enable Claude Code's auto-memory system (default `false`)
 - `pathToClaudeCodeExecutable` — path to the `claude` binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run. For example, with Nix you can set the binary to e.g. `"/home/you/.nix-profile/bin/claude"`.
@@ -71,3 +69,9 @@ Set `CLAUDE_BRIDGE_DEBUG=1` to enable debug output:
 - **Per-query Claude Code CLI logs** at `~/.pi/agent/cc-cli-logs/<timestamp>-<tag>-<seq>.log` — the CC subprocess's own debug stream, one file per `query()` call. Tags are `provider` (main turn) or `compact-summary`. Useful when a resume fails or CC misbehaves internally — shows the CLI's own view of session loading, API requests, and tool calls.
 
 When filing a bug about a session-resume failure (e.g. "No conversation found"), the most useful attachments are the `syncResult:` lines from the bridge log plus the matching `cc-cli-logs/` file for the failing query.
+
+## Known issues
+
+**Sessions get rebuilt more often than they need to be, and a rebuild is expensive.** The bridge rewrites Claude Code's session from pi's history whenever pi's messages move underneath it — after an abort, `/compact`, tree navigation, or an API error. Measured over this repo's own bridge log, a rebuild boundary loses the prompt cache roughly 58% of the time against 26% for a plain resume, so an abort-heavy session costs noticeably more than a clean one. Aborts alone are 46% of rebuilds.
+
+**Files Claude Code edits are not carried across a rebuild.** CC records the post-edit contents as an `edited_text_file` attachment; those aren't carried, because they hang off a tool-result record rather than a prompt and so have no stable position to restore them to. The edit itself survives — it's in the history as a tool call and its result — so this costs Claude the file snapshot, not the knowledge that it made the change. `@file` expansions *are* carried.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-agent-sdk",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "private": false,
   "description": "Pi extension that uses Claude Code (via Agent SDK) as a model provider.",
   "keywords": [
@@ -41,9 +41,8 @@
   "type": "module",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.141",
-    "@anthropic-ai/sdk": "^0.73.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "cc-session-io": "^0.3.2",
+    "cc-session-io": "^0.4.0",
     "change-case": "^5.4.4"
   },
   "peerDependencies": {
@@ -51,11 +50,12 @@
     "@earendil-works/pi-coding-agent": ">=0.82.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.82.1",
-    "@earendil-works/pi-coding-agent": "^0.82.1",
+    "@anthropic-ai/sdk": "^0.73.0",
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
     "@types/node": "^24.13.2",
     "tsx": "^4.22.4",
-    "typebox": "^1.3.0",
+    "typebox": "^1.3.7",
     "typescript": "^6.0.3"
   },
   "pi": {

package/src/agents-md.ts

@@ -1,14 +1,8 @@
-// Pi owns context-file discovery. Reuse its public loader so Claude receives
-// the same global and hierarchical AGENTS.md/CLAUDE.md instructions as Pi.
-
-import { getAgentDir, loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+// Pi owns context-file discovery; the bridge only formats the list Pi loaded so
+// Claude receives the same instructions, in the same order, that Pi applies.
 
 type ContextFile = { path: string; content: string };
 
-export function extractAgentsAppend(cwd: string = process.cwd()): string | undefined {
-	return formatProjectContext(loadProjectContextFiles({ cwd, agentDir: getAgentDir() }));
-}
-
 export function formatProjectContext(contextFiles: ContextFile[]): string | undefined {
 	if (contextFiles.length === 0) return undefined;
 

package/src/attachments.ts

@@ -0,0 +1,135 @@
+// Carrying Claude Code's own attachments across a session rebuild.
+//
+// CC expands an `@file` mention itself — pi passes `@` through untouched — and
+// writes the expansion as a `type: "attachment"` record in its session file. pi
+// never sees it, so rebuilding a session from pi's history drops the file while
+// keeping the prompt text that referred to it: the model silently loses
+// something it was reasoning about, with nothing logged.
+//
+// Extracted from index.ts so tests can import it without activating the extension.
+
+import type { JsonlRecord, ImportAttachment } from "cc-session-io";
+import { messageContentToText } from "./convert.js";
+
+// Only `@file` expansions are carried. They are the one thing pi genuinely never
+// sees, so a rebuild is the only chance to keep them.
+//
+// `edited_text_file` is deliberately excluded even though it also carries file
+// content. CC writes one after editing a file, and the edit itself is already in
+// pi's history as a tool call and its result, so the attachment duplicates context
+// the rebuild reproduces anyway. It also usually hangs off a *tool result* record
+// rather than a prompt, which has no position in the ordinal scheme below — on
+// real sessions that left 81 of them unresolvable (see
+// diag/attachment-coverage.mjs). Half-carrying a kind is worse than not claiming
+// it: the ones that slipped through would be an arbitrary subset.
+//
+// Everything else CC rewrites every turn (`skill_listing`, `task_reminder`,
+// `agent_listing_delta`, `mcp_instructions_delta`, …) and loses nothing.
+const CONTENT_BEARING = new Set(["file"]);
+
+export type CarriedAttachment = {
+	attachment: { type: string; [key: string]: unknown };
+	/** Position of the parent among the session's text-bearing user records. */
+	userOrdinal: number;
+	/** That record's text, to verify the ordinal still points at the same turn. */
+	parentText: string;
+};
+
+type Rec = Record<string, unknown>;
+
+/** A user record holding a prompt, as opposed to one holding tool results. */
+function userPromptText(record: Rec): string | undefined {
+	if (record.type !== "user") return undefined;
+	const content = (record.message as Rec | undefined)?.content;
+	if (Array.isArray(content) && content.some((b) => (b as Rec)?.type === "tool_result")) return undefined;
+	const text = messageContentToText(content as never);
+	return text ? text : undefined;
+}
+
+/**
+ * Content-bearing attachments in a session, each tagged with where its parent
+ * sits among the text-bearing user records.
+ *
+ * The ordinal is the mapping key rather than the record index: a rebuild does not
+ * reproduce the old record list one-for-one — `importMessages` splits a message
+ * carrying tool results into two records, and CC appends records of its own — but
+ * the sequence of user prompts is the same conversation either way.
+ *
+ * Attachments also chain to one another, so an ordinal is resolved transitively up
+ * the parent links until it reaches a prompt. Most real attachments are
+ * `edited_text_file` records CC writes after editing a file, which have nothing to
+ * do with at-mentions; only their position in the conversation matters here.
+ */
+export function collectCarriedAttachments(records: readonly JsonlRecord[]): CarriedAttachment[] {
+	const ordinalOf = new Map<string, number>();
+	const textOf = new Map<string, string>();
+	let ordinal = 0;
+	const carried: CarriedAttachment[] = [];
+
+	for (const raw of records) {
+		const record = raw as Rec;
+		const prompt = userPromptText(record);
+		if (prompt !== undefined) {
+			ordinalOf.set(record.uuid as string, ordinal++);
+			textOf.set(record.uuid as string, prompt);
+			continue;
+		}
+		if (record.type !== "attachment") continue;
+		const parent = record.parentUuid as string | null;
+		// Attachments chain to each other — a run of them hangs off one prompt, and
+		// 63 of 179 in real sessions parent to another attachment rather than to a
+		// message. Inherit the ordinal so the whole run keys to the prompt that
+		// caused it. Recorded for every attachment, not just the ones carried, since
+		// a content-bearing one can chain off a `skill_listing` we ignore.
+		if (parent === null || !ordinalOf.has(parent)) continue;
+		const inherited = ordinalOf.get(parent)!;
+		ordinalOf.set(record.uuid as string, inherited);
+		textOf.set(record.uuid as string, textOf.get(parent)!);
+
+		const attachment = record.attachment as { type: string; [key: string]: unknown } | undefined;
+		if (!attachment || !CONTENT_BEARING.has(attachment.type)) continue;
+		carried.push({ attachment, userOrdinal: inherited, parentText: textOf.get(parent)! });
+	}
+	return carried;
+}
+
+/**
+ * Resolve each carried attachment to a position in the array about to be
+ * imported — the messages *after* conversion and repair, since that is the index
+ * space `importMessages` reads. Repair is idempotent, so an already-repaired array
+ * passes through its second run unchanged and the indices stay valid.
+ *
+ * Deliberately conservative: attaching a file to the wrong turn tells the model it
+ * saw something at a point it did not, which is worse than the loss this exists to
+ * prevent. So the ordinal has to land on a prompt whose text still matches; any
+ * disagreement is reported and dropped rather than approximated.
+ */
+export function placeCarriedAttachments(
+	carried: readonly CarriedAttachment[],
+	messages: readonly { role: string; content: unknown }[],
+): { attachments: ImportAttachment[]; skipped: string[] } {
+	const prompts: { index: number; text: string }[] = [];
+	messages.forEach((msg, index) => {
+		if (msg.role !== "user") return;
+		if (Array.isArray(msg.content) && msg.content.some((b) => (b as Rec)?.type === "tool_result")) return;
+		const text = messageContentToText(msg.content as never);
+		if (text) prompts.push({ index, text });
+	});
+
+	const attachments: ImportAttachment[] = [];
+	const skipped: string[] = [];
+	for (const item of carried) {
+		const name = String(item.attachment.filename ?? item.attachment.type);
+		const candidate = prompts[item.userOrdinal];
+		if (!candidate) {
+			skipped.push(`${name}: prompt #${item.userOrdinal} is no longer in history`);
+			continue;
+		}
+		if (candidate.text !== item.parentText) {
+			skipped.push(`${name}: prompt #${item.userOrdinal} changed`);
+			continue;
+		}
+		attachments.push({ afterIndex: candidate.index, attachment: item.attachment });
+	}
+	return { attachments, skipped };
+}

package/src/config.ts

@@ -4,7 +4,6 @@
 // unparseable files are ignored (error to console.error, empty object
 // returned) so the extension always starts.
 
-import type { SettingSource } from "@anthropic-ai/claude-agent-sdk";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
@@ -14,8 +13,6 @@ export interface Config {
 	startupNoticeShown?: string;
 	/** Low-level Claude Agent SDK plumbing. Most users won't need these. */
 	provider?: {
-		appendSystemPrompt?: boolean;
-		settingSources?: SettingSource[];
 		strictMcpConfig?: boolean;
 		autoMemoryEnabled?: boolean;
 		pathToClaudeCodeExecutable?: string;
@@ -46,12 +43,26 @@ export function globalConfigPath(): string {
 	return join(getAgentDir(), "claude-bridge.json");
 }
 
-/** Record today's date in the global config so the startup notice shows once. Preserves every other field. */
+/** Record today's date in the global config so the startup notice shows once, preserving every
+ *  other field. Returns the config path for display either way.
+ *
+ *  Parses directly rather than through tryParseJson, which reports an unparseable file as `{}`:
+ *  spreading that would replace a user's whole config with just this marker the first time they
+ *  leave a trailing comma in it. Losing the notice is the cheaper failure, so the write is
+ *  skipped and the notice simply shows again next session. */
 export function markStartupNoticeShown(): string {
 	const path = globalConfigPath();
+	let existing: Partial<Config> = {};
+	if (existsSync(path)) {
+		try {
+			existing = JSON.parse(readFileSync(path, "utf-8"));
+		} catch (e) {
+			console.error(`claude-bridge: leaving ${path} alone, it does not parse: ${e}`);
+			return path;
+		}
+	}
 	// en-CA renders YYYY-MM-DD in local time; toISOString() would report UTC.
-	const today = new Date().toLocaleDateString("en-CA");
-	const next = { ...tryParseJson(path), startupNoticeShown: today };
+	const next = { ...existing, startupNoticeShown: new Date().toLocaleDateString("en-CA") };
 	mkdirSync(dirname(path), { recursive: true });
 	writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
 	return path;

package/src/convert.ts

@@ -108,13 +108,25 @@ function toolResultContent(
 	return blocks;
 }
 
+/** What convertPiMessages discarded, for the debug line in index.ts. */
+export type DroppedContent = {
+	thinking: number;
+	abortedTurns: number;
+	providers: Set<string>;
+	other: Map<string, number>;
+};
+
 /** Convert pi message array to Anthropic API format. */
 export function convertPiMessages(
 	messages: PiMessage[],
 	customToolNameToSdk?: Map<string, string>,
-): { anthropicMessages: SessionMessage[]; sanitizedIds: Map<string, string> } {
+): { anthropicMessages: SessionMessage[]; sanitizedIds: Map<string, string>; dropped: DroppedContent } {
 	const anthropicMessages = [];
 	const sanitizedIds = new Map();
+	// What conversion discarded. Nothing downstream can tell: a stripped thinking
+	// block and a message that never carried one convert to the same thing, so
+	// without this the loss is invisible in the log and in a captured request.
+	const dropped: DroppedContent = { thinking: 0, abortedTurns: 0, providers: new Set(), other: new Map() };
 	// The user message collecting this assistant turn's tool results, if one has
 	// been emitted yet, and the index of the assistant message it belongs to. Both
 	// are cleared at every assistant message — see the toolResult branch.
@@ -138,8 +150,6 @@ export function convertPiMessages(
 				anthropicMessages.push({ role: "user", content: "[empty]" });
 			}
 		} else if (msg.role === "assistant") {
-			turnResults = null;
-			turnAssistantIdx = anthropicMessages.length;
 			const content = Array.isArray(msg.content) ? msg.content : [];
 			const blocks = [];
 			for (const block of content) {
@@ -152,13 +162,39 @@ export function convertPiMessages(
 					const sig = block.thinkingSignature;
 					if (msg.provider === PROVIDER_ID && sig) {
 						blocks.push({ type: "thinking", thinking: block.thinking ?? "", signature: sig });
+					} else {
+						dropped.thinking++;
+						dropped.providers.add(msg.provider ?? "unknown");
 					}
 				} else if (block.type === "toolCall") {
 					const toolName = mapPiToolNameToSdk(block.name, customToolNameToSdk);
 					blocks.push({ type: "tool_use", id: sanitizeToolId(block.id, sanitizedIds), name: toolName, input: block.arguments ?? {} });
+				} else {
+					dropped.other.set(block.type, (dropped.other.get(block.type) ?? 0) + 1);
 				}
 			}
+			// A turn the user aborted before anything streamed carries no content at
+			// all. Standing a placeholder in its place invents a reply the assistant
+			// never made, and because it lands early in the prefix it costs the whole
+			// downstream prompt cache every time the session is rebuilt. Drop it:
+			// Session.importMessages imposes no alternation, and a turn with no blocks
+			// has no tool_use ids needing a synthetic result. Left before the turn
+			// bookkeeping so a stray result still attaches to the last assistant
+			// message actually emitted.
+			//
+			// Do NOT clear turnResults/turnAssistantIdx here. It looks like the tidy
+			// thing to do, but an abort between two parallel results — assistant[X,Y],
+			// R_X, aborted turn, R_Y — would then start a second results message for
+			// R_Y. repairToolPairing consumes both pending ids at the first one, stubs
+			// Y there and drops the real R_Y as unmatched, destroying the parallel
+			// result this merge exists to preserve. unit-import.mjs pins the shape.
+			if (!content.length) { dropped.abortedTurns++; continue; }
+			// Blocks were present but every one was filtered — content really was
+			// dropped here, so keep the slot and say so. Empty content is rejected by
+			// the API, and dropping the message would break tool pairing.
 			if (!blocks.length) blocks.push({ type: "text", text: "[incompatible content omitted]" });
+			turnResults = null;
+			turnAssistantIdx = anthropicMessages.length;
 			anthropicMessages.push({ role: "assistant", content: blocks });
 		} else if (msg.role === "toolResult") {
 			// Pi records one message per tool result, and repairToolPairing only
@@ -200,5 +236,5 @@ export function convertPiMessages(
 		}
 	}
 
-	return { anthropicMessages, sanitizedIds };
+	return { anthropicMessages, sanitizedIds, dropped };
 }

package/src/index.ts

@@ -1,22 +1,26 @@
 import { calculateCost, type AssistantMessage, type AssistantMessageEventStream, type Context, type ImageContent, type Model, type SimpleStreamOptions, type TextContent, type Tool, type UserMessage } from "@earendil-works/pi-ai";
 import * as piAi from "@earendil-works/pi-ai";
 import { getModels } from "@earendil-works/pi-ai/compat";
-import { compact, type CompactionEntry, type ExtensionAPI, type ExtensionContext, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { compact, generateBranchSummary, type BranchSummaryResult, type CompactionEntry, type ExtensionAPI, type ExtensionContext, type ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import { query, type EffortLevel, type SDKMessage, type SettingSource } from "@anthropic-ai/claude-agent-sdk";
 import type { Base64ImageSource, ContentBlockParam } from "@anthropic-ai/sdk/resources";
-import { createSession, deleteSession, repairToolPairing } from "cc-session-io";
+import { createSession, deleteSession, openSession, repairToolPairing } from "cc-session-io";
 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 { applyLongContext, buildModels, claudeCodeModelId, type LongContextSettings } from "./models.js";
-import { MCP_SERVER_NAME, MCP_TOOL_PREFIX, extractSkillsBlock } from "./skills.js";
+import { MCP_SERVER_NAME, MCP_TOOL_PREFIX } 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 { makePromptStream, userMessage, type PromptStream } from "./prompt-stream.js";
 import { claudeCodeSettings, loadConfig, markStartupNoticeShown, type Config } from "./config.js";
-import { extractAgentsAppend } from "./agents-md.js";
+import {
+	projectPromptCapture,
+	PromptCaptures,
+} from "./prompt-capture.js";
+import { collectCarriedAttachments, placeCarriedAttachments, type CarriedAttachment } from "./attachments.js";
 import { createToolServer } from "./mcp-server.js";
 import { CC_CHILD_ENV, resolveClaudeChildEnv, type AnthropicAuthRegistry } from "./child-env.js";
 
@@ -41,6 +45,19 @@ const DIAG_LOG_PATH = join(homedir(), ".pi", "agent", "claude-bridge-diag.log");
 const RECORD_STREAM_PATH = process.env.CLAUDE_BRIDGE_RECORD_STREAM;
 
 
+// Pi owns context files on the provider path, so Claude Code must not load its
+// own on top: otherwise a project CLAUDE.md arrives twice, and the user's
+// ~/.claude/CLAUDE.md — a persona written for a harness that is not the one
+// running — arrives at all, stamped "These instructions OVERRIDE any default
+// behavior" and outranking Pi's own AGENTS.md.
+//
+// Excludes rather than settingSources: the source gate that suppresses CLAUDE.md
+// is the same one that reads settings.json, where Bedrock/Vertex users keep
+// `env` and `apiKeyHelper`. Patterns are matched with picomatch against absolute
+// paths; "**/CLAUDE.md" covers the user, ancestor, project and .claude/ copies,
+// while rules need their own. Managed/policy memory is not excludable by design.
+const CLAUDE_MD_EXCLUDES = ["**/CLAUDE.md", "**/.claude/rules/**"];
+
 // Ensure log directories exist when debug is enabled
 if (DEBUG) {
 	try {
@@ -158,19 +175,43 @@ interface SessionState {
 	forceRotate?: boolean;
 }
 
+/**
+ * Claude Code's `@file` expansions from the session about to be replaced.
+ *
+ * Must be called before `deleteSession`, which wipes the file they live in —
+ * reading after it yields nothing, with no error to notice.
+ */
+function readCarriedAttachments(sessionId: string, cwd: string): CarriedAttachment[] {
+	try {
+		const previous = openSession({ sessionId, projectPath: cwd, claudeDir: process.env.CLAUDE_CONFIG_DIR });
+		return collectCarriedAttachments(previous.records);
+	} catch (error) {
+		// A post-abort rebuild reads a file the killed CC subprocess may have been
+		// midway through writing, and cc-session-io parses each line with a bare
+		// JSON.parse, so a truncated last line throws. Throwing here would turn a
+		// lost attachment into a failed turn; carrying none is exactly what happened
+		// before this existed, so the failure mode is bounded by the status quo.
+		debug(`WARNING: could not read attachments from session ${sessionId.slice(0, 8)}:`, error);
+		return [];
+	}
+}
+
 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).
+// Lossy: only text, thinking and toolCall blocks survive, and thinking only when
+// Claude Code itself minted the signature. An assistant message whose blocks all
+// filter out keeps its slot with a placeholder, since dropping it can create a
+// tool_result with no preceding tool_use. A turn aborted before anything streamed
+// is dropped instead — it never had content, and inventing one diverges from the
+// prefix Claude Code cached.
 function convertAndImportMessages(
 	session: ReturnType<typeof createSession>,
 	messages: Context["messages"],
 	customToolNameToSdk?: Map<string, string>,
+	carried?: readonly CarriedAttachment[],
 ): void {
-	const { anthropicMessages, sanitizedIds } = convertPiMessages(messages, customToolNameToSdk);
+	const { anthropicMessages, sanitizedIds, dropped } = convertPiMessages(messages, customToolNameToSdk);
 
 	debug(`convertAndImportMessages: ${messages.length} pi msgs → ${anthropicMessages.length} anthropic msgs`);
 	debug(`convertAndImportMessages: imported roles:`, anthropicMessages.map((m, i) => {
@@ -179,6 +220,16 @@ function convertAndImportMessages(
 		if (Array.isArray(c)) return `[${i}]${m.role}:${(c).map((b) => b.type).join("+")}`;
 		return `[${i}]${m.role}:?`;
 	}).join(" "));
+	// The roles line above shows only what survived, so a stripped block is
+	// indistinguishable there from one that never existed. Name the losses.
+	const droppedParts = [
+		dropped.thinking ? `${dropped.thinking} thinking (${[...dropped.providers].sort().join(", ")})` : "",
+		dropped.abortedTurns ? `${dropped.abortedTurns} aborted turn(s)` : "",
+		...[...dropped.other].map(([type, n]) => `${n} ${type}`),
+	].filter(Boolean);
+	if (droppedParts.length > 0) {
+		debug(`convertAndImportMessages: dropped ${droppedParts.join(", ")}`);
+	}
 	if (sanitizedIds.size > 0) {
 		debug(`convertAndImportMessages: sanitized ${sanitizedIds.size} tool IDs:`,
 			[...sanitizedIds.entries()].map(([orig, clean]) => orig === clean ? orig : `${orig}→${clean}`).join(", "));
@@ -188,7 +239,21 @@ function convertAndImportMessages(
 	if (repaired.length !== anthropicMessages.length) {
 		debug(`convertAndImportMessages: repairToolPairing ${anthropicMessages.length} → ${repaired.length} msgs`);
 	}
-	if (repaired.length) session.importMessages(repaired);
+	// Placement runs against the repaired array because that is the index space
+	// importMessages reads. Attachments are links in CC's uuid chain, so they have
+	// to be written in order with the messages, not appended afterwards.
+	const placed = carried?.length
+		? placeCarriedAttachments(carried, repaired as unknown as { role: string; content: unknown }[])
+		: undefined;
+	if (placed?.skipped.length) {
+		debug(`convertAndImportMessages: dropped ${placed.skipped.length} carried attachment(s): ${placed.skipped.join("; ")}`);
+	}
+	if (placed?.attachments.length) {
+		debug(`convertAndImportMessages: carrying ${placed.attachments.length} attachment(s) across the rebuild`);
+	}
+	if (repaired.length) {
+		session.importMessages(repaired, placed?.attachments.length ? { attachments: placed.attachments } : undefined);
+	}
 }
 
 // Pi doesn't pass tool results directly — it appends them to the context and calls
@@ -317,6 +382,24 @@ function resultErrorText(message: SDKMessage): string | undefined {
 	return `Claude Code failed: ${result.subtype ?? "unknown result"}`;
 }
 
+/** Name a failure as a rate limit when a rejection preceded it.
+ *
+ *  pi has no typed rate-limit error — `stopReason` is only ever `"error"` and the sole carrier
+ *  is `errorMessage` — so everything that reacts to a rate limit pattern-matches that string:
+ *  pi-subagents gates `fallbackModels` on a 35-pattern list, and key-rotating extensions use
+ *  their own. Claude Code words a subscription limit as "You're out of extra usage · resets
+ *  6:30pm", which matches none of them, so an exhausted quota reads as a fatal error and the
+ *  fallback chain never runs (issue #58).
+ *
+ *  Leading with "Claude rate limit" rather than appending keeps the phrase in any truncated
+ *  render, and avoids the `<tool> failed (exit N):` shape that pi-subagents treats as a tool
+ *  failure and refuses to retry. */
+function describeRateLimitFailure(rejection: { rateLimitType?: string; resetsAt?: number }, failure: string): string {
+	const kind = rejection.rateLimitType ? ` (${rejection.rateLimitType})` : "";
+	const resets = rejection.resetsAt ? ` — resets ${new Date(rejection.resetsAt * 1000).toLocaleTimeString()}` : "";
+	return `Claude rate limit${kind}${resets}: ${failure}`;
+}
+
 function isolatedStreamFn(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
 	const stream = newAssistantMessageEventStream();
 	void runIsolatedSummary(model, context, options, stream);
@@ -576,6 +659,8 @@ function syncSharedSession(
 	// 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;
+	// Before deleteSession — it wipes the file these live in.
+	const carried = previousSessionId !== undefined ? readCarriedAttachments(previousSessionId, cwd) : [];
 	if (preserveId) {
 		// Wipe prior jsonl + companion dir (no-op if nothing to wipe).
 		deleteSession(previousSessionId!, cwd, process.env.CLAUDE_CONFIG_DIR);
@@ -586,17 +671,19 @@ function syncSharedSession(
 		...(preserveId ? { sessionId: previousSessionId } : {}),
 		...(modelId ? { model: modelId } : {}),
 	});
-	convertAndImportMessages(session, priorMessages, customToolNameToSdk);
+	convertAndImportMessages(session, priorMessages, customToolNameToSdk, carried);
 	session.save();
-	verifyWrittenSession(session.jsonlPath, session.sessionId, session.messages.length, cwd);
+	// records, not messages: `messages` filters out the attachment records that
+	// carrying an `@file` expansion across a rebuild writes into the same file.
+	verifyWrittenSession(session.jsonlPath, session.sessionId, session.records.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`);
+		debug(`Case 2: first turn with ${priorMessages.length} prior messages → session ${session.sessionId.slice(0, 8)}, ${session.records.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`);
+		debug(`Case 4: ${missedCount} missed messages, ${priorMessages.length} total → rewrote session ${session.sessionId.slice(0, 8)} (same id), ${session.records.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`);
+		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.records.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"}`);
@@ -614,6 +701,9 @@ export const __test = {
 	getSharedSession() {
 		return sharedSession;
 	},
+	setPiUI(ui: ExtensionUIContext | null) {
+		piUI = ui;
+	},
 	syncSharedSession,
 	extractUserPromptBlocks,
 	consumeQuery,
@@ -623,6 +713,7 @@ export const __test = {
 	drainForAbort,
 	CC_CHILD_ENV,
 	buildMcpServers,
+	branchSummaryOutcome,
 };
 
 // --- Provider helpers: tool name mapping ---
@@ -682,26 +773,73 @@ const activeQueryContexts = new Set<QueryContext>();
 // provider query rather than session_start: the notice persists a flag to the global
 // config, and firing it on startup would write that file for every pi session that
 // merely has this extension installed.
-let planNoticePending = false;
+let pendingNotices: string[] = [];
 
-function showPlanNoticeOnce(): void {
+function showStartupNoticeOnce(): void {
 	// `hasUI` is true in RPC mode too — it means dialogs are possible, not that a
 	// human is watching. Only a terminal user can act on this.
-	if (!planNoticePending || piMode !== "tui") return;
-	planNoticePending = false;
+	if (pendingNotices.length === 0 || piMode !== "tui") return;
+	const notices = pendingNotices;
+	pendingNotices = [];
 	const path = markStartupNoticeShown();
-	piUI?.notify(
-		`pi-claude-agent-sdk: assuming a Max plan. On Pro, set provider.plan to "pro" in ${path} so Opus 4.6 stays at 200K context.`,
-		"info",
+	// pi wraps the whole notify string in the theme's dim foreground; the inner reset
+	// drops back to the terminal default rather than dim, which is fine here.
+	const title = `\x1b[33mWelcome to pi-claude-agent-sdk\x1b[39m — settings live in ${path}`;
+	const bullets = [...notices, "This message only appears once. See README.md for more."].map((n) => `• ${n}`);
+	piUI?.notify([title, ...bullets, "─".repeat(64)].join("\n"), "info");
+}
+
+// Captures of what pi assembled per agent; see src/prompt-capture.ts for why this
+// is keyed rather than held in a single slot.
+const promptCaptures = new PromptCaptures(256, (diagnostic) => {
+	const first = diagnostic.matches[0];
+	debug(
+		`prompt-capture: no match for ${diagnostic.systemPrompt.length}-char system prompt. `
+		+ (first
+			? `closest known (${first.key.length}-char) shares its first ${first.firstDivergent} chars and diverges at offset ${first.firstDivergent}: `
+			  + JSON.stringify(diagnostic.systemPrompt.slice(first.firstDivergent - 40, first.firstDivergent + 60))
+			: "no known captures to compare against."
+		) + ` known keys=${diagnostic.matches.length}`,
+	);
+});
+
+/** Whatever a settled session left behind, named in one greppable line.
+ *
+ *  Every one of these should be empty once the last turn ends, and each is a leak
+ *  that costs something real: a retained context routes a later orphaned tool result
+ *  into the delivery path and returns a stream nobody ends; a pending tool call is an
+ *  MCP handler Claude Code is still waiting on; a live prompt stream is an unresolved
+ *  ack. The activeQueryContexts leak was present on every single happy-path run and
+ *  no test noticed, because nothing asserted that anything ends clean — so assert it
+ *  where the real sessions are, and let diag/audit-warnings.mjs scan for it. */
+function reportLeaks(label: string): void {
+	const pendingCalls = [...activeQueryContexts].reduce((n, c) => n + c.pendingToolCalls.size, 0);
+	const liveStreams = [...activeQueryContexts].filter((c) => c.promptStream !== null).length;
+	if (activeQueryContexts.size === 0 && pendingCalls === 0 && liveStreams === 0) return;
+	debug(
+		`WARNING: ${label} left state behind — contexts=${activeQueryContexts.size} `
+		+ `pendingToolCalls=${pendingCalls} promptStreams=${liveStreams}`,
 	);
 }
 
-// The user's own system prompt customisation (`--system-prompt`,
-// `--append-system-prompt`), captured from before_agent_start. pi's assembled
-// `context.systemPrompt` can't be forwarded wholesale — it describes pi's tools
-// and harness and would fight Claude Code's own preset — but the user's text is
-// theirs and has to reach the model, so it is kept separately.
-let userSystemPrompt: { custom?: string; append?: string } = {};
+/** What pi's branch summary means for the navigation it was asked for.
+ *
+ *  Cancelling on failure matches pi's own path, which rethrows a summary error out
+ *  of the navigation rather than moving without one. Separated from the event
+ *  handler so this decision is testable without a Claude Code subprocess — driving
+ *  `generateBranchSummary` itself would only be testing pi. */
+function branchSummaryOutcome(result: BranchSummaryResult): { cancel: true } | { summary: { summary: string; details: unknown; usage?: BranchSummaryResult["usage"] } } {
+	if (result.aborted) return { cancel: true };
+	if (result.error) throw new Error(result.error);
+	debug(`session_before_tree: takeover complete summaryLen=${result.summary?.length ?? 0}`);
+	return {
+		summary: {
+			summary: result.summary ?? "",
+			details: { readFiles: result.readFiles ?? [], modifiedFiles: result.modifiedFiles ?? [] },
+			usage: result.usage,
+		},
+	};
+}
 
 function contextForToolResults(results: McpResult[]): QueryContext | undefined {
 	for (const result of results) {
@@ -1091,6 +1229,12 @@ async function consumeQuery(
 			logServedContextWindow("result", message, model);
 			resultError = resultErrorText(message);
 			if (resultError !== undefined) {
+				// Consume the rejection alongside the failure it caused, so a later
+				// unrelated failure on this query doesn't inherit the label.
+				if (queryCtx.rateLimitRejection) {
+					resultError = describeRateLimitFailure(queryCtx.rateLimitRejection, resultError);
+					queryCtx.rateLimitRejection = null;
+				}
 				debug(`consumeQuery: error result, subtype=${message.subtype}, error=${resultError}`);
 				if (queryCtx.turnOutput) {
 					queryCtx.turnOutput.stopReason = "error";
@@ -1102,10 +1246,31 @@ async function consumeQuery(
 			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";
+				// Held so the failure Claude Code sends next can be named as a rate limit.
+				queryCtx.rateLimitRejection = info;
+				// The "rate limited" notice below supersedes warnings; re-arm so the next
+				// window's warnings fire even if it opens straight into allowed_warning.
+				queryCtx.lastRateLimitWarnStep = null;
+				queryCtx.lastRateLimitWarnThreshold = undefined;
+				// resetsAt is Unix seconds, not milliseconds.
+				const resetsAt = info.resetsAt ? new Date(info.resetsAt * 1000).toLocaleTimeString() : "unknown";
 				piUI?.notify(`Claude rate limited (${info.rateLimitType ?? "unknown"}) — resets at ${resetsAt}`, "warning");
+			} else if (info?.status === "allowed") {
+				// Back under the threshold (window reset) — re-arm the warning dedupe.
+				queryCtx.lastRateLimitWarnStep = null;
+				queryCtx.lastRateLimitWarnThreshold = undefined;
 			} else if (info?.status === "allowed_warning") {
-				piUI?.notify(`Claude rate limit warning: ${Math.round(info.utilization ?? 0)}% used (${info.rateLimitType ?? ""})`, "warning");
+				// utilization is a fraction (0..1); allowed_warning fires once it crosses surpassedThreshold.
+				const percent = Math.round((info.utilization ?? 0) * 100);
+				// The SDK emits one event per request, so only re-notify when the level
+				// rises past a new 5% step or the threshold changes.
+				const step = Math.floor(percent / 5);
+				const rose = queryCtx.lastRateLimitWarnStep === null || step > queryCtx.lastRateLimitWarnStep;
+				if (rose || info.surpassedThreshold !== queryCtx.lastRateLimitWarnThreshold) {
+					queryCtx.lastRateLimitWarnStep = step;
+					queryCtx.lastRateLimitWarnThreshold = info.surpassedThreshold;
+					piUI?.notify(`Claude rate limit warning: ${percent}% used (${info.rateLimitType ?? ""})`, "warning");
+				}
 			}
 			continue;
 		}
@@ -1251,7 +1416,7 @@ function drainForAbort(c: QueryContext, promptStream: PromptStream): void {
 /** 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 streamClaudeAgentSdk(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
-	showPlanNoticeOnce();
+	showStartupNoticeOnce();
 	const stream = newAssistantMessageEventStream();
 
 	// DEBUG: trace followUp message triggering
@@ -1319,6 +1484,21 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	const queryCtx = isReentrant ? new QueryContext() : ctx();
 	debug(`provider: fresh query setup, isReentrant=${isReentrant}, activeContexts=${activeQueryContexts.size}`);
 
+	// Resolved first: an unaccountable system prompt throws, and doing that before
+	// anything is claimed or reset leaves no half-built query behind — in particular
+	// no stream claimed on the shared context that nobody will ever end.
+	const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context);
+	// Build from what Pi loaded for this run, so `--no-context-files` and
+	// `--no-skills` reach Claude Code by leaving nothing to forward. A sub-agent's
+	// custom override embeds its parent's assembled Pi prompt; recursive projection
+	// replaces that exact inherited prompt with its already-safe portable parts.
+	const promptCapture = promptCaptures.resolveOrDerive(context.systemPrompt);
+	const systemPromptAppend = promptCapture
+		? projectPromptCapture(promptCapture, {
+			skillReadTool: mcpTools.some((tool) => tool.name === "read") ? "mcp" : "none",
+		})
+		: undefined;
+
 	// 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);
@@ -1331,7 +1511,6 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	queryCtx.resetTurnState(model);
 	queryCtx.latestCursor = 0;
 
-	const { mcpTools, customToolNameToSdk, customToolNameToPi } = resolveMcpTools(context);
 	const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
 	// cliModel is the actual id sent to Claude Code (may carry [1m]); model.id is the
 	// pi-registered id. Log cliModel so debug lines reflect what CC actually received.
@@ -1367,24 +1546,12 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		.catch((error) => debug(`provider: initial prompt push rejected:`, error));
 	queryCtx.promptStream = promptStream;
 	const mcpServers = buildMcpServers(mcpTools, queryCtx);
-	const appendSystemPrompt = providerSettings.appendSystemPrompt !== false;
-	const agentsAppend = appendSystemPrompt ? extractAgentsAppend(cwd) : undefined;
-	const skillsAppend = appendSystemPrompt ? extractSkillsBlock(context.systemPrompt) : undefined;
-	// Last, so the user's own instructions win over anything the bridge adds, and
-	// ungated by appendSystemPrompt: that setting suppresses context the bridge
-	// injects on its own, not what the user explicitly asked for.
-	const appendParts = [agentsAppend, skillsAppend, userSystemPrompt.custom, userSystemPrompt.append]
-		.filter((part): part is string => Boolean(part));
-	const systemPromptAppend = appendParts.length > 0 ? appendParts.join("\n\n") : undefined;
 
 	// MCP auto-loading suppression: CC reads MCP servers from ~/.claude.json (top-level
 	// + per-project) and .mcp.json. Since pi executes tools (not CC), those are pure
 	// token overhead. --strict-mcp-config tells the binary to use ONLY mcpServers passed
 	// programmatically and ignore filesystem MCP entries — applied unconditionally because
-	// settingSources=undefined does NOT give isolation (the CC default loads all sources).
-	const settingSources: SettingSource[] | undefined = appendSystemPrompt
-		? undefined
-		: providerSettings.settingSources ?? ["user", "project"];
+	// settingSources is left at CC's default, which loads all sources.
 	const strictMcpConfigEnabled = providerSettings.strictMcpConfig !== false;
 	const claudeExecutable = providerSettings.pathToClaudeCodeExecutable;
 
@@ -1417,14 +1584,26 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 		tools: [],
 		permissionMode: "bypassPermissions",
 		includePartialMessages: true,
-		settings: claudeCodeSettings(providerSettings),
+		// includeGitInstructions:false drops the gitStatus block from the preset.
+		// That block is the trailing suffix of the cached system block, and a
+		// git-state transition (new file, staging, commit) rewrites it — busting
+		// the prompt cache for the whole conversation from there on (see
+		// diag/probe-git-cache.mjs). The bridge re-invokes CC per turn, so this
+		// hit on every transition. Cost here is nil: the setting also strips
+		// CC's git-workflow guidance from its Bash tool prompt, but the provider
+		// path runs CC with `tools: []`, so those definitions never ship.
+		// AskClaude keeps CC's native tools and its guidance — unaffected.
+		settings: {
+			...claudeCodeSettings(providerSettings),
+			claudeMdExcludes: CLAUDE_MD_EXCLUDES,
+			includeGitInstructions: false,
+		},
 		systemPrompt: {
 			type: "preset", preset: "claude_code",
 			append: systemPromptAppend ? systemPromptAppend : undefined,
 		},
 		extraArgs,
 		...(effort ? { effort } : {}),
-		...(settingSources ? { settingSources } : {}),
 		...(mcpServers ? { mcpServers } : {}),
 		...(resumeSessionId ? { resume: resumeSessionId } : {}),
 		...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
@@ -1434,7 +1613,7 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	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=${strictMcpConfigEnabled}`,
+		`ctxFiles=${promptCapture?.contextFiles.length ?? 0} strictMcp=${strictMcpConfigEnabled}`,
 		`prompt=${promptText.slice(0, 60)}${promptBlocks ? " [+images]" : ""}`);
 
 	// Resolve Pi's Anthropic credential before every fresh child. OAuth refresh is
@@ -1543,7 +1722,15 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
 			promptStream.fail(new Error("query ended"));
 			if (queryCtx.promptStream === promptStream) queryCtx.promptStream = null;
-			if (queryCtx.activeQuery === authPending || (sdkQuery && queryCtx.activeQuery === sdkQuery)) {
+			// A later query claiming this context sets activeQuery to its own handle;
+			// null means the .then/.catch above cleared ours and nothing replaced it.
+			// Testing only for `=== sdkQuery` would never fire on the non-reentrant
+			// path, leaving the top-level context in the routing set forever — where a
+			// later orphaned tool result matches its stale turnToolCallIds and takes
+			// the delivery branch, returning a stream nothing ends.
+			// authPending covers the window before Claude Code starts, when sdkQuery
+			// is still null.
+			if (queryCtx.activeQuery === authPending || queryCtx.activeQuery === sdkQuery || queryCtx.activeQuery === null) {
 				queryCtx.releasePendingToolCalls("Query ended");
 				queryCtx.activeQuery = null;
 				activeQueryContexts.delete(queryCtx);
@@ -1572,7 +1759,9 @@ export default function (pi: ExtensionAPI) {
 	};
 	const registeredModels = applyLongContext(MODELS, longContextSettings);
 
-	planNoticePending = config.provider?.plan === undefined && !config.startupNoticeShown;
+	if (!config.startupNoticeShown) {
+		if (config.provider?.plan === undefined) pendingNotices.push('Assuming a Max plan. On Pro, set provider.plan to "pro" so Opus 4.6 stays at 200K context.');
+	}
 
 	// Reset shared session on pi session lifecycle events
 	const clearSession = (event: string) => {
@@ -1601,9 +1790,18 @@ export default function (pi: ExtensionAPI) {
 	// still depends on, so both flags are forwarded as an append.
 	pi.on("before_agent_start", (event) => {
 		const options = event.systemPromptOptions;
-		userSystemPrompt = { custom: options?.customPrompt, append: options?.appendSystemPrompt };
+		const hasRead = !options?.selectedTools || options.selectedTools.includes("read");
+		promptCaptures.record(event.systemPrompt, {
+			custom: options?.customPrompt,
+			append: options?.appendSystemPrompt,
+			contextFiles: options?.contextFiles ?? [],
+			skills: hasRead ? options?.skills ?? [] : [],
+		});
+	});
+	pi.on("session_shutdown", () => {
+		reportLeaks("session_shutdown");
+		clearSession("session_shutdown");
 	});
-	pi.on("session_shutdown", () => clearSession("session_shutdown"));
 
 	pi.on("session_before_compact", async (event, ctx) => {
 		if (ctx.model?.baseUrl !== "claude-bridge") return undefined;
@@ -1654,6 +1852,38 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_compact", (event) => markRebuild(`session_compact:${event.reason}:willRetry=${event.willRetry}`));
 	pi.on("session_tree", () => markRebuild("session_tree"));
 
+	// Branch summarization — rewind or fork-at-point with "summarize" — is the other
+	// place pi asks the model for a summary, and unlike compaction it runs through
+	// the *agent's* stream function (agent-session passes `streamFn:
+	// this.agent.streamFunction`). On a bridge model that reaches this provider
+	// carrying pi's internal summarization prompt, which no `before_agent_start`
+	// ever recorded, so the prompt-capture resolver has nothing to resolve it to.
+	// Take it over the way compaction is taken over: the summary runs as its own
+	// Claude Code subprocess, never touching the live session or the resolver.
+	pi.on("session_before_tree", async (event, ctx) => {
+		if (ctx.model?.baseUrl !== "claude-bridge") return undefined;
+		const { entriesToSummarize, userWantsSummary, customInstructions, replaceInstructions } = event.preparation;
+		if (!userWantsSummary || entriesToSummarize.length === 0) return undefined;
+		debug(`session_before_tree: takeover entries=${entriesToSummarize.length} target=${event.preparation.targetId.slice(0, 8)}`);
+		try {
+			const result = await generateBranchSummary(entriesToSummarize, {
+				model: ctx.model,
+				signal: event.signal,
+				customInstructions,
+				replaceInstructions,
+				streamFn: isolatedStreamFn,
+			});
+			return branchSummaryOutcome(result);
+		} catch (err) {
+			debug("session_before_tree: takeover failed; cancelling navigation", err);
+			ctx.ui?.notify?.(
+				`pi-claude-agent-sdk branch summary failed (${errorMessage(err)}); navigation cancelled.`,
+				"error",
+			);
+			return { cancel: true };
+		}
+	});
+
 	// --- Provider ---
 	//
 	// Guard against re-registration when the module is loaded multiple times

package/src/prompt-capture.ts

@@ -0,0 +1,315 @@
+import type { Skill } from "@earendil-works/pi-coding-agent";
+import { formatProjectContext } from "./agents-md.js";
+import { renderSkillsBlock, type SkillReadTool } from "./skills.js";
+
+// What pi assembled for one agent, kept so the bridge can append only the
+// portable parts after Claude Code's own preset.
+
+export type PromptCaptureInput = {
+	custom?: string;
+	append?: string;
+	contextFiles: { path: string; content: string }[];
+	skills: Skill[];
+};
+
+type InheritedPrompt = {
+	start: number;
+	end: number;
+	parent: PromptCapture;
+};
+
+export type PromptCapture = PromptCaptureInput & {
+	assembledPrompt: string;
+	/** Exact previously assembled prompts embedded in `custom`. */
+	inherited: InheritedPrompt[];
+};
+
+/**
+ * Captures keyed by the fully assembled prompt pi sends to a provider.
+ *
+ * A sub-agent's systemPromptOverride embeds its parent's assembled prompt
+ * verbatim. Pi currently exposes that override as an ordinary custom prompt,
+ * without provenance. Linking exact prior keys recovers the inheritance graph
+ * without recognizing pi prose or sub-agent markers. If pi later exposes an
+ * inherited-system-prompt field, it should replace this inference.
+ */
+export type PromptCaptureDiagnostic = {
+	/** The prompt that matched nothing: the full system prompt is too big to log
+	 *  inline, so a fingerprint plus the closest match's first divergent offset
+	 *  are enough to recognize the pump.
+	 *
+	 *  Closest is by shared prefix — the case that matters here is pi itself
+	 *  rebuilding the prompt outside `before_agent_start` (a changed tool list or
+	 *  fresh resource discovery), which edits near the boundary, and a prefix key
+	 *  gets us to within a handful of characters of where. */
+	systemPrompt: string;
+	matches: { key: string; firstDivergent: number }[];
+};
+
+export class PromptCaptures {
+	private readonly captures = new Map<string, PromptCapture>();
+	/** Invoked with everything that would otherwise be lost when resolution throws,
+	 *  so the bridge can write it to its debug log. Kept off the throw path itself:
+	 *  the resolver is hot and the caller may own a faster sink than string-building.
+	 *
+	 *  Set by the bridge on the shared instance; tests that want the diagnostic can
+	 *  pass one per instance. */
+	private readonly onDiagnose: (diagnostic: PromptCaptureDiagnostic) => void;
+
+	/** Pi rebuilds prompts when tools change, so retain only recent lookup keys.
+	 *  Inheritance edges hold direct references and survive key eviction.
+	 *
+	 *  Set well above any plausible working set because the costs are lopsided: a
+	 *  capture is tens of KB, while evicting one that is still live fails the turn.
+	 *  A parent that fans out to more distinct sub-agent prompts than this before its
+	 *  own next turn would be evicted despite being in use. The bound exists only to
+	 *  cap an extension that rebuilds the prompt every turn, which would otherwise
+	 *  grow keys without limit. */
+	constructor(private readonly limit = 256, onDiagnose?: (diagnostic: PromptCaptureDiagnostic) => void) {
+		this.onDiagnose = onDiagnose ?? (() => {});
+	}
+
+	record(systemPrompt: string, input: PromptCaptureInput): void {
+		const existing = this.captures.get(systemPrompt);
+		const customChanged = existing?.custom !== input.custom;
+		const capture = existing ?? {
+			...input,
+			assembledPrompt: systemPrompt,
+			contextFiles: [],
+			skills: [],
+			inherited: [],
+		};
+
+		capture.custom = input.custom;
+		capture.append = input.append;
+		capture.contextFiles = input.contextFiles.map((file) => ({ ...file }));
+		capture.skills = [...input.skills];
+		if (!existing || customChanged) {
+			capture.inherited = this.findInheritedPrompts(systemPrompt, input.custom);
+		}
+
+		// Mutate an existing node in place so descendants retain a live reference,
+		// then re-insert its key so Map order tracks recency.
+		this.touch(systemPrompt, capture);
+	}
+
+	/** Exact lookup only. Callers serving a query want `resolveOrDerive`. */
+	resolve(systemPrompt?: string): PromptCapture | undefined {
+		if (!systemPrompt) return undefined;
+		const capture = this.captures.get(systemPrompt);
+		if (capture) this.touch(systemPrompt, capture);
+		return capture;
+	}
+
+	/** Recency is by use, not just by record. A parent agent records its prompt once
+	 *  and then only ever resolves it, so counting writes alone ages it out behind the
+	 *  sub-agent prompts churning past it — observed in a real 135-message session,
+	 *  where the parent's own prompt was evicted and its next turn resolved to
+	 *  nothing. */
+	private touch(systemPrompt: string, capture: PromptCapture): void {
+		this.captures.delete(systemPrompt);
+		this.captures.set(systemPrompt, capture);
+		// Trims here, not only in record(): reviving an evicted node re-adds a key that
+		// was not in the map, so without this a run of revivals grows it without bound.
+		for (const key of this.captures.keys()) {
+			if (this.captures.size <= this.limit) break;
+			this.captures.delete(key);
+		}
+	}
+
+	/**
+	 * The capture to project for one query, for both the provider and AskClaude.
+	 *
+	 * An exact key is the normal case. A prompt that only *embeds* known prompts —
+	 * anything that wrapped what Pi assembled after we recorded it — resolves to a
+	 * transient descendant over the whole prompt, so projection swaps each embedded
+	 * capture for its portable parts and carries everything around them through
+	 * unchanged. That surrounding text belongs to whatever did the wrapping, and
+	 * dropping it would be exactly the silent instruction loss this exists to
+	 * prevent. The descendant is not retained — its key is not ours to own.
+	 *
+	 * Throws when a prompt can be accounted for by neither route. Returning an empty
+	 * capture instead would hand Claude Code a turn with none of the user's context
+	 * files, skills, custom prompt or append text, and say so only in a debug line —
+	 * silently discarding policy the user wrote down. A failed turn is recoverable;
+	 * a turn that quietly ignored its instructions is not.
+	 */
+	resolveOrDerive(systemPrompt?: string): PromptCapture | undefined {
+		if (!systemPrompt) return undefined;
+		const exact = this.captures.get(systemPrompt);
+		if (exact) {
+			this.touch(systemPrompt, exact);
+			return exact;
+		}
+
+		// A capture outlives its lookup key: eviction drops the key while inheritance
+		// edges keep the node alive. findInheritedPrompts deliberately skips a node whose
+		// key *is* the prompt, so without this an evicted exact match would derive
+		// nothing and throw. Touching it puts the key back.
+		const revived = this.reachableCaptures().find((node) => node.assembledPrompt === systemPrompt);
+		if (revived) {
+			this.touch(systemPrompt, revived);
+			return revived;
+		}
+
+		const embedded = this.findInheritedPrompts(systemPrompt, systemPrompt);
+		if (embedded.length === 0) {
+			const matches = this.closestKnown(systemPrompt);
+			this.onDiagnose({ systemPrompt, matches });
+			throw new Error(
+				`prompt-capture: no capture for this ${systemPrompt.length}-char system prompt, and it embeds none of the ${this.captures.size} known. `
+				+ `Closest known match diverges at offset ${matches[0]?.firstDivergent ?? "?"} (${matches.length ? matches[0].key.length : 0}-char key). `
+				+ `Claude Code would receive none of this turn's context files, skills or custom instructions. `
+				+ `The usual cause is an extension loaded after claude-bridge that rewrites the system prompt from before_agent_start — `
+				+ `one that wraps it is fine, one that rebuilds or strips it leaves nothing to match. `
+				+ `(Also possible: pi rebuilt the prompt outside before_agent_start — a late-registered tool or fresh resource discovery.)`,
+			);
+		}
+
+		// `custom` is the prompt itself and the edges keep their original offsets, so
+		// projectCustom substitutes the embedded captures in place and preserves every
+		// byte between and around them.
+		return { assembledPrompt: systemPrompt, custom: systemPrompt, contextFiles: [], skills: [], inherited: embedded };
+	}
+
+	get size(): number {
+		return this.captures.size;
+	}
+
+	/** Longest shared-prefix matches, best first, for the throw diagnostic. */
+	private closestKnown(systemPrompt: string): { key: string; firstDivergent: number }[] {
+		let shared = 0;
+		const matches: { key: string; firstDivergent: number }[] = [];
+		for (const key of this.captures.keys()) {
+			const limit = Math.min(key.length, systemPrompt.length);
+			let i = 0;
+			while (i < limit && key.charCodeAt(i) === systemPrompt.charCodeAt(i)) i++;
+			if (i >= shared) {
+				if (i > shared) {
+					shared = i;
+					matches.length = 0;
+				}
+				matches.push({ key, firstDivergent: i });
+			}
+		}
+		return matches;
+	}
+
+	private findInheritedPrompts(systemPrompt: string, custom?: string): InheritedPrompt[] {
+		if (!custom) return [];
+
+		const candidates: Array<InheritedPrompt & { length: number }> = [];
+		for (const parent of this.reachableCaptures()) {
+			const key = parent.assembledPrompt;
+			if (key === systemPrompt || key.length === 0) continue;
+			for (let start = custom.indexOf(key); start !== -1; start = custom.indexOf(key, start + key.length)) {
+				candidates.push({ start, end: start + key.length, length: key.length, parent });
+			}
+		}
+
+		// A grandchild contains both its parent's key and the grandparent key
+		// nested inside it. Keep the longest exact non-overlapping matches.
+		candidates.sort((a, b) => b.length - a.length || a.start - b.start);
+		const selected: InheritedPrompt[] = [];
+		for (const candidate of candidates) {
+			if (selected.some((edge) => candidate.start < edge.end && candidate.end > edge.start)) continue;
+			selected.push({ start: candidate.start, end: candidate.end, parent: candidate.parent });
+		}
+		return selected.sort((a, b) => a.start - b.start);
+	}
+
+	private reachableCaptures(): PromptCapture[] {
+		const result: PromptCapture[] = [];
+		const seen = new Set<PromptCapture>();
+		const visit = (capture: PromptCapture): void => {
+			if (seen.has(capture)) return;
+			seen.add(capture);
+			result.push(capture);
+			for (const edge of capture.inherited) visit(edge.parent);
+		};
+		for (const capture of this.captures.values()) visit(capture);
+		return result;
+	}
+}
+
+export function projectPromptCapture(
+	capture: PromptCapture,
+	options: { skillReadTool: SkillReadTool },
+): string | undefined {
+	return projectCapture(capture, options, new Set());
+}
+
+/** Skills visible through inherited prompts, ancestor first and once per file. */
+export function collectPromptSkills(capture: PromptCapture): Skill[] {
+	const result: Skill[] = [];
+	const seenPaths = new Set<string>();
+	const visited = new Set<PromptCapture>();
+	const visiting = new Set<PromptCapture>();
+
+	const visit = (node: PromptCapture): void => {
+		if (visited.has(node)) return;
+		if (visiting.has(node)) throw new Error("Cyclic prompt inheritance");
+		visiting.add(node);
+		for (const edge of node.inherited) visit(edge.parent);
+		for (const skill of node.skills) {
+			if (skill.disableModelInvocation || seenPaths.has(skill.filePath)) continue;
+			seenPaths.add(skill.filePath);
+			result.push(skill);
+		}
+		visiting.delete(node);
+		visited.add(node);
+	};
+
+	visit(capture);
+	return result;
+}
+
+function projectCapture(
+	capture: PromptCapture,
+	options: { skillReadTool: SkillReadTool },
+	visiting: Set<PromptCapture>,
+): string | undefined {
+	if (visiting.has(capture)) throw new Error("Cyclic prompt inheritance");
+	visiting.add(capture);
+	try {
+		const inheritedSkillPaths = new Set(
+			capture.inherited.flatMap((edge) => collectPromptSkills(edge.parent).map((skill) => skill.filePath)),
+		);
+		const ownSkillPaths = new Set<string>();
+		const ownSkills = capture.skills.filter((skill) => {
+			if (skill.disableModelInvocation || inheritedSkillPaths.has(skill.filePath) || ownSkillPaths.has(skill.filePath)) {
+				return false;
+			}
+			ownSkillPaths.add(skill.filePath);
+			return true;
+		});
+
+		const custom = projectCustom(capture, options, visiting);
+		const parts = [
+			formatProjectContext(capture.contextFiles),
+			renderSkillsBlock(ownSkills, options.skillReadTool),
+			custom,
+			capture.append,
+		].filter((part): part is string => Boolean(part));
+		return parts.length > 0 ? parts.join("\n\n") : undefined;
+	} finally {
+		visiting.delete(capture);
+	}
+}
+
+function projectCustom(
+	capture: PromptCapture,
+	options: { skillReadTool: SkillReadTool },
+	visiting: Set<PromptCapture>,
+): string | undefined {
+	if (!capture.custom || capture.inherited.length === 0) return capture.custom;
+
+	let result = "";
+	let cursor = 0;
+	for (const edge of capture.inherited) {
+		result += capture.custom.slice(cursor, edge.start);
+		result += projectCapture(edge.parent, options, visiting) ?? "";
+		cursor = edge.end;
+	}
+	return result + capture.custom.slice(cursor);
+}

package/src/query-state.ts

@@ -28,6 +28,12 @@ export class QueryContext {
 	turnToolCallIds: string[] = [];
 	/** Streaming-input handle for the active query — how steers reach CC mid-turn. */
 	promptStream: PromptStream | null = null;
+	/** Last rate-limit rejection seen on this query. Claude Code sends it just before the
+	 *  failure it caused, which is the only thing tying the two together. */
+	rateLimitRejection: { rateLimitType?: string; resetsAt?: number } | null = null;
+	/** Highest 5% utilization bucket we notified for, so repeat rate_limit_event spam is suppressed. */
+	lastRateLimitWarnStep: number | null = null;
+	lastRateLimitWarnThreshold: number | undefined;
 
 	// Per-turn (reset together)
 	turnOutput: AssistantMessage | null = null;

package/src/skills.ts

@@ -1,19 +1,15 @@
-// Skills block extraction + MCP naming constants.
-// Extracted from index.ts so tests can import without activating the extension.
+import { formatSkillsForPrompt, type Skill } from "@earendil-works/pi-coding-agent";
 
 export const MCP_SERVER_NAME = "custom-tools";
 export const MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
 
-// Extract skills block from pi's system prompt for forwarding to Claude Code.
-export function extractSkillsBlock(systemPrompt?: string): string | undefined {
-	if (!systemPrompt) return undefined;
-	const startMarker = "The following skills provide specialized instructions for specific tasks.";
-	const endMarker = "</available_skills>";
-	const start = systemPrompt.indexOf(startMarker);
-	if (start === -1) return undefined;
-	const end = systemPrompt.indexOf(endMarker, start);
-	if (end === -1) return undefined;
-	return rewriteSkillsBlock(systemPrompt.slice(start, end + endMarker.length).trim());
+export type SkillReadTool = "mcp" | "native" | "none";
+
+export function renderSkillsBlock(skills: Skill[], readTool: SkillReadTool): string | undefined {
+	if (readTool === "none" || skills.length === 0) return undefined;
+	const block = formatSkillsForPrompt(skills).trim();
+	if (!block) return undefined;
+	return readTool === "mcp" ? rewriteSkillsBlock(block) : block;
 }
 
 export function rewriteSkillsBlock(skillsBlock: string): string {