@viniciosrab/pi-claude-bridge 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli Dickinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# pi-claude-bridge
+
+> **Fork note.** `@viniciosrab/pi-claude-bridge` is an automated mirror of [`pi-claude-bridge`](https://www.npmjs.com/package/pi-claude-bridge) by Eli Dickinson ([elidickinson/pi-claude-bridge](https://github.com/elidickinson/pi-claude-bridge)), rebuilt for each upstream release with one addition: the `provider.loadClaudeSettings` option ([upstream PR #142](https://github.com/elidickinson/pi-claude-bridge/pull/142)). Versions match upstream. Licensed MIT; original copyright and credit belong to Eli Dickinson. Fork: [viniciosrab/pi-claude-bridge](https://github.com/viniciosrab/pi-claude-bridge).
+
+[![npm version](https://img.shields.io/npm/v/@viniciosrab/pi-claude-bridge)](https://www.npmjs.com/package/@viniciosrab/pi-claude-bridge)
+
+Pi extension that integrates Claude Code via the [Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript). Originally based on [claude-agent-sdk-pi](https://github.com/prateekmedia/claude-agent-sdk-pi) by Prateek Sunal.
+
+1. **Provider** — Use Opus/Sonnet/Haiku as models in pi, with all tool calls flowing through pi's TUI
+2. **AskClaude tool** — Delegate tasks or questions to Claude Code when using another provider
+
+
+**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;
+<a href="assets/claude-bridge2.png"><img src="assets/claude-bridge2.png" width="49%"></a>
+</p>
+
+## Install
+
+```
+pi install npm:pi-claude-bridge
+```
+
+Requires pi 0.86.1 or newer.
+
+## Provider
+
+Use `/model` to select any Claude model in pi-ai's catalog, e.g. `claude-bridge/claude-fable-5-1`, `claude-bridge/claude-opus-5`, or `claude-bridge/claude-haiku-4-5`.
+
+Behind the scenes, pi's tools are bridged to Claude Code but everything works like normal in pi. Bash commands get Claude Code's 120-second default timeout since pi's bash has none. Skills are forwarded to Claude Code's system prompt, and steering mid-turn reaches Claude at the next tool boundary.
+
+The model list comes from pi-ai's Anthropic catalog automatically — when pi-ai adds a new Claude model, it appears in `/model` after updating the package, no bridge update needed. Dated snapshot ids (e.g. `claude-opus-4-5-20251101`) are not shown.
+
+**1M Context:** Fable 5/5.1, Opus 5.5/5/4.8/4.7, and Sonnet 5 get 1M context. Opus 4.6 gets 1M only on a Max plan or with Extra Usage, and Sonnet 4.6 only with Extra Usage — set `provider.plan` and/or `provider.longContextExtraUsage` as described in [Configuration](#configuration).
+
+## AskClaude Tool
+
+Opt-in: set `askClaude.enabled` to `true` (see [Configuration](#configuration)). Available when using any non-claude-bridge provider. Pi's LLM can delegate tasks to Claude Code and wait for it to answer a question or perform a task. Examples of how to use:
+
+- "Ask Claude to plan a fix"
+- "If you get stuck, ask claude for help"
+- "Ask claude to review the plan in @foo.md, implement it, then ask an isolated=true claude to review the implementation"
+- "Ask claude to poke holes in this theory"
+
+Delegated calls don't read global `CLAUDE.md` files or Claude Code's skill listing, and always get Claude Code's own system prompt.
+
+### Parameters
+
+- **`prompt`** — the question or task for Claude Code
+- **`mode`** — `read` (default, read files and search/fetch on web), `none`, or `full` (read+write+bash, disable this mode with `allowFullMode: false` in config)
+- **`model`** — `opus` (default), `sonnet`, `haiku`, or a full model ID
+- **`thinking`** — effort level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`
+- **`isolated`** — when `true`, Claude gets a clean session with no conversation history (default: `false`)
+
+## Configuration
+
+Config: `~/.pi/agent/claude-bridge.json` (global) or the project Pi config directory, usually `.pi/claude-bridge.json` (project; merged over global).
+
+```json
+{
+  "askClaude": {
+    "enabled": true,
+    "allowFullMode": true,
+    "defaultIsolated": false,
+    "description": "Custom tool description override"
+  },
+  "provider": {
+    "plan": "max",
+    "longContextExtraUsage": false,
+    "strictMcpConfig": true,
+    "pathToClaudeCodeExecutable": "/home/you/.nix-profile/bin/claude"
+  }
+}
+```
+
+`askClaude`:
+- `enabled` — register the AskClaude tool (default `false`). If it's unset, the startup notice below points this out once.
+- `name` — override the tool's pi-side name (default `"AskClaude"`)
+- `label` — override the TUI label (default `"Ask Claude Code"`)
+- `description` — override the tool description. Default when `allowFullMode: true`: *"Delegate to Claude Code for a second opinion or analysis (code review, architecture questions, debugging theories), or to autonomously handle a task. Defaults to read-only mode — use full mode when the user wants to delegate a task that requires changes. Prefer to handle straightforward tasks yourself."*
+- `defaultMode` — `"read"` (default), `"none"`, or `"full"`
+- `defaultIsolated` — start each call in a fresh session (default `false`)
+- `allowFullMode` — allow `mode: "full"`; set `false` to lock it out
+- `appendSkills` — forward pi's skills block into the system prompt (default `true`)
+
+`provider`:
+- `plan` (default `"pro"`) — set to `"max"` if you have a Max (or Team Premium/Enterprise) Anthropic plan. This enables Opus with 1M context.
+- `longContextExtraUsage` — set to `true` to enable 1M context models even if they cost money through Extra Usage on your plan. 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.
+- `forceTwoHundredK` — array of model ids to pin to 200K context (bare id, no `[1m]` suffix). Use if pi-ai declares a model at 1M but Claude Code won't serve it on your plan.
+- `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`)
+- `loadClaudeSettings` — load Claude Code's user/project/local settings in the provider's Claude Code subprocess (default `true`). Set `false` to skip them: settings-sourced hooks and plugins no longer run on every turn, which can noticeably cut tokens and latency when you have many configured. It also drops settings-sourced `env` and `apiKeyHelper`, so keep the default if you rely on those (e.g. Bedrock/Vertex setup in `settings.json`). OAuth login, pi tools and extensions are unaffected. Applies only to the provider path; AskClaude always loads settings.
+- `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"`.
+
+
+**Startup notice:** the first session lists `provider.plan` and `askClaude.enabled` if unset, then records `startupNoticeShown` in the global config so it doesn't nag again.
+
+**Extension providers and models.json:** pi's `modelOverrides` in `~/.pi/agent/models.json` do not currently apply to extension-registered providers (like claude-bridge). Overriding `contextWindow` or other fields requires editing `src/models.ts` directly — to pin a model to 200K, use `provider.forceTwoHundredK` instead.
+
+## Tests
+
+`npm run test:unit` for offline tests. `npm test` adds integration tests that hit APIs; set `CLAUDE_BRIDGE_TESTING_ALT_MODEL` in `.env.test` for the alt-provider smoke test.
+
+Integration tests spawn real `pi` and Claude Code subprocesses and need write access to `~/.claude` — a sandbox that blocks it makes `--resume` fail with `No conversation found with session ID`.
+
+## Debugging
+
+Set `CLAUDE_BRIDGE_DEBUG=1` to enable debug output:
+
+- **Bridge log** at `~/.pi/agent/claude-bridge.log` — provider calls, session sync decisions, tool results, CC stderr. Override location with `CLAUDE_BRIDGE_DEBUG_PATH`.
+- **Per-query CC CLI logs** at `~/.pi/agent/cc-cli-logs/<timestamp>-<tag>-<seq>.log` — the subprocess's own debug stream; tag is `provider` or `askclaude`. Shows CC's 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.
+
+## Compatibility with other extensions
+
+Other extensions can change the system prompt. When the result still contains pi's built-in system prompt text, or the two documentation paths that Anthropic looks for (`docs/custom-provider.md` in the same prompt with `docs/packages.md`), the bridge stops the turn instead of sending it, since Anthropic may otherwise bill these requests as Extra Usage. Fix the source extension before retrying; `CLAUDE_BRIDGE_DEBUG=1` writes the full prompt to `~/.pi/agent/claude-bridge.log` when this happens.
+
+### Using claude bridge with @gotgenes/pi-subagents
+
+Requires the following in `~/.pi/agent/subagents.json`:
+
+```json
+{"promptInheritance": {"claude-bridge": "portable"}}
+```
+
+## Known issues
+
+**A session rebuild re-sends the whole conversation.** The bridge rewrites Claude Code's session from pi's history whenever the two diverge — after an abort, `/compact`, tree navigation, an API error, or on returning to a session — and the next request usually misses the prompt cache for everything past the system prompt. Abort-heavy sessions cost noticeably more.
+
+**Files Claude Code edits are not carried across a rebuild.** The edit itself survives in the history as a tool call and result — what's lost is the post-edit file snapshot. `@file` expansions *are* carried.
+
+**System prompt changes mid-session may not reach the model.** The bridge keeps Claude Code's default prompt recording: project context (AGENTS.md/CLAUDE.md), skills, and extension-written instructions are captured on the first request and reused on resume. This keeps the cached prefix stable, but later changes may not take effect until a rebuild or compaction. Start a new session if updated instructions must take effect immediately.
+
+**Exported Anthropic environment variables override the Claude Code child (issue #107).** An exported `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, or `ANTHROPIC_AUTH_TOKEN` redirects Claude Code to that gateway and every turn fails with its auth error. Unset them for the pi process.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@viniciosrab/pi-claude-bridge",
+  "version": "0.9.0",
+  "private": false,
+  "description": "Pi extension that uses Claude Code (via Agent SDK) as a model provider and adds an AskClaude tool.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "claude-code",
+    "claude-agent-sdk"
+  ],
+  "author": "Eli Dickinson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viniciosrab/pi-claude-bridge.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "assets"
+  ],
+  "scripts": {
+    "test:unit": "node --import tsx --import ./tests/lib/setup.mjs --test tests/unit-*.mjs",
+    "test": "set -a && [ -f .env.test ] && . .env.test; set +a; CLAUDE_BRIDGE_TEST_LOG_DIR=$(mktemp -d); export CLAUDE_BRIDGE_TEST_LOG_DIR; npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs && node tests/lib/check-deadlock-logs.mjs \"$CLAUDE_BRIDGE_TEST_LOG_DIR\"",
+    "test:usage": "tests/usage-test.sh",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.280",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cc-session-io": "^0.4.0",
+    "change-case": "^5.4.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.86.1",
+    "@earendil-works/pi-coding-agent": ">=0.86.1",
+    "@earendil-works/pi-tui": ">=0.86.1",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.124.0",
+    "@earendil-works/pi-ai": "^0.87.1",
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1",
+    "@types/node": "^24.13.2",
+    "tsx": "^4.22.4",
+    "typebox": "^1.3.7",
+    "typescript": "^6.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "homepage": "https://github.com/viniciosrab/pi-claude-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/viniciosrab/pi-claude-bridge/issues"
+  }
+}

package/src/agents-md.ts

@@ -0,0 +1,14 @@
+// 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 formatProjectContext(contextFiles: ContextFile[]): string | undefined {
+	if (contextFiles.length === 0) return undefined;
+
+	let prompt = "<project_context>\n\nProject-specific instructions and guidelines:\n\n";
+	for (const { path, content } of contextFiles) {
+		prompt += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
+	}
+	return `${prompt}</project_context>`;
+}

package/src/askclaude-schema.ts

@@ -0,0 +1,92 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { Config } from "./config.js";
+
+export type AskClaudeMode = "full" | "read" | "none";
+
+export interface AskClaudeDefaults {
+	mode: AskClaudeMode;
+	isolated: boolean;
+	allowFull: boolean;
+}
+
+const PACKAGE_DEFAULT_MODE: AskClaudeMode = "read";
+const PACKAGE_DEFAULT_ISOLATED = false;
+
+export function resolveAskClaudeDefaults(conf: Config["askClaude"]): AskClaudeDefaults {
+	const rawAllowFull: unknown = conf?.allowFullMode;
+	const allowFull = rawAllowFull == null ? true : rawAllowFull === true;
+	const configuredMode: unknown = conf?.defaultMode;
+	const mode = configuredMode == null
+		? PACKAGE_DEFAULT_MODE
+		: configuredMode === "full" || configuredMode === "read" || configuredMode === "none"
+			? configuredMode
+			// Unrecognized value: the most restrictive mode, not the package default.
+			: "none";
+	return { mode: !allowFull && mode === "full" ? PACKAGE_DEFAULT_MODE : mode, isolated: conf?.defaultIsolated ?? PACKAGE_DEFAULT_ISOLATED, allowFull };
+}
+
+export function resolveAskClaudeMode(mode: unknown, defaults: AskClaudeDefaults): AskClaudeMode {
+	const resolved = mode === undefined ? defaults.mode : mode;
+	if (resolved !== "full" && resolved !== "read" && resolved !== "none") throw new Error(`Invalid AskClaude mode: ${String(resolved)}`);
+	if (resolved === "full" && !defaults.allowFull) throw new Error("AskClaude full mode is disabled.");
+	return resolved;
+}
+
+function modeDescription(defaults: AskClaudeDefaults): string {
+	const mark = (mode: AskClaudeMode) => (mode === defaults.mode ? " (default)" : "");
+	const parts = [
+		`"read"${mark("read")}: questions about the codebase — review, analysis, explain.`,
+		`"none"${mark("none")}: general knowledge only (no file access).`,
+	];
+	if (defaults.allowFull) {
+		parts.push(`"full"${mark("full")}: allows writing and bash execution (careful: runs without feedback to pi).`);
+	}
+	return parts.join(" ");
+}
+
+export function buildAskClaudeParams(defaults: AskClaudeDefaults) {
+	const visibility = defaults.isolated
+		? "By default Claude sees only this prompt (isolated session)."
+		: "By default Claude sees the full conversation history.";
+	const trueDefault = defaults.isolated ? " (default)" : "";
+	const falseDefault = defaults.isolated ? "" : " (default)";
+	const modeValues: readonly AskClaudeMode[] = defaults.allowFull ? ["read", "full", "none"] : ["read", "none"];
+	return Type.Object({
+		prompt: Type.String({ description: `The question or task for Claude Code. ${visibility} Don't research up front, let Claude explore.` }),
+		mode: Type.Optional(StringEnum(modeValues, { description: modeDescription(defaults) })),
+		model: Type.Optional(Type.String({ description: 'Claude model (e.g. "opus", "sonnet", "haiku", or full ID). Defaults to "opus".' })),
+		thinking: Type.Optional(StringEnum(["off", "minimal", "low", "medium", "high", "xhigh"] as const, { description: "Thinking effort level. Omit to use Claude Code's default." })),
+		isolated: Type.Optional(Type.Boolean({ description: `When true${trueDefault}, Claude sees only this prompt (clean session). When false${falseDefault}, Claude sees the full conversation history.` })),
+	});
+}
+
+export function askClaudeToolDescription(defaults: AskClaudeDefaults, override?: string | null): string {
+	if (override != null) return override;
+	const suffix = " Prefer to handle straightforward tasks yourself.";
+	if (!defaults.allowFull) {
+		const middle = defaults.mode === "none"
+			? 'Defaults to no file access — pass mode "read" to let Claude Code explore the codebase; it can never make changes.'
+			: "Read-only — Claude Code can explore the codebase but not make changes.";
+		return `Delegate to Claude Code for a second opinion or analysis (code review, architecture questions, debugging theories). ${middle}${suffix}`;
+	}
+	const middle = defaults.mode === "full"
+		? 'Defaults to full mode — Claude Code writes files and runs bash without feedback to pi; pass mode "read" to keep it to exploration.'
+		: defaults.mode === "none"
+			? 'Defaults to no file access — pass mode "read" to let Claude Code explore the codebase, or "full" for a task that requires changes.'
+			: "Defaults to read-only mode — use full mode when the user wants to delegate a task that requires changes.";
+	return `Delegate to Claude Code for a second opinion or analysis (code review, architecture questions, debugging theories), or to autonomously handle a task. ${middle}${suffix}`;
+}
+
+export function askClaudeCallTags(
+	args: { mode?: AskClaudeMode; model?: string; thinking?: string; isolated?: boolean },
+	defaults: AskClaudeDefaults,
+): string[] {
+	const tags: string[] = [];
+	const mode = args.mode ?? defaults.mode;
+	if (mode !== PACKAGE_DEFAULT_MODE || (args.mode !== undefined && args.mode !== defaults.mode)) tags.push(`mode=${mode}`);
+	if (args.model) tags.push(`model=${args.model}`);
+	if (args.thinking) tags.push(`thinking=${args.thinking}`);
+	if ((args.isolated ?? defaults.isolated) !== PACKAGE_DEFAULT_ISOLATED) tags.push("isolated");
+	return tags;
+}

package/src/askclaude-ui.ts

@@ -0,0 +1,90 @@
+// Status-line rendering helpers for the AskClaude tool.
+//
+// While Claude Code runs inside an AskClaude call, the pi TUI can't surface
+// each tool_use individually — there's only one status row for the whole
+// delegation. These helpers shape a tool_use record into a short, path-aware
+// label (e.g. "Read(src/foo.ts)", "Bash(git log --oneline…)") and collapse
+// runs of the same tool so the line doesn't flicker. Used only by
+// promptAndWait; the provider path exposes tools directly through pi's TUI
+// and doesn't need this.
+
+export interface ToolCallState {
+	name: string;
+	status: string;
+	rawInput?: unknown;
+}
+
+export function extractPath(rawInput: unknown): string | undefined {
+	if (!rawInput || typeof rawInput !== "object") return undefined;
+	const input = rawInput as Record<string, unknown>;
+	if (typeof input.file_path === "string") return input.file_path;
+	if (typeof input.path === "string") return input.path;
+	if (typeof input.command === "string") return input.command.substring(0, 80);
+	return undefined;
+}
+
+export function shortPath(p: string): string {
+	const cwd = process.cwd();
+	if (p.startsWith(cwd + "/")) return p.slice(cwd.length + 1);
+	if (p.startsWith("/")) {
+		const parts = p.split("/");
+		if (parts.length > 3) return parts.slice(-2).join("/");
+	}
+	return p;
+}
+
+export function formatToolAction(tc: ToolCallState): string | undefined {
+	const path = extractPath(tc.rawInput);
+	const verb = tc.name.toLowerCase().split(/\s/)[0];
+	if (verb === "read" || verb === "readfile") {
+		return path ? `Read(${shortPath(path)})` : "Read";
+	} else if (verb === "glob") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const pat = typeof input?.pattern === "string" ? input.pattern.slice(0, 40) : "";
+		return pat ? `Glob(${pat})` : "Glob";
+	} else if (verb === "edit" || verb === "write" || verb === "writefile" || verb === "multiedit") {
+		return path ? `Edit(${shortPath(path)})` : "Edit";
+	} else if (verb === "bashoutput") {
+		return undefined; // redundant with preceding Bash call
+	} else if (verb === "bash" || verb === "terminal") {
+		return path ? `Bash(${path})` : "Bash";
+	} else if (verb === "agent") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		return `Agent(${String(input?.description ?? "").slice(0, 40)})`;
+	} else if (verb === "grep") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const pat = typeof input?.pattern === "string" ? input.pattern.slice(0, 40) : "";
+		return pat ? `Grep(${pat})` : "Grep";
+	} else if (verb === "skill") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const name = typeof input?.skill === "string" ? input.skill.slice(0, 40) : "";
+		return name ? `Skill(${name})` : "Skill";
+	} else if (verb === "todowrite" || verb === "taskcreate" || verb === "taskupdate") {
+		const todos = Array.isArray((tc.rawInput as any)?.todos) ? (tc.rawInput as any).todos : [];
+		const current = todos.find((t: any) => t.status === "in_progress") ?? todos.find((t: any) => t.status === "pending");
+		const label = current ? String(current.content ?? "").slice(0, 40) : "";
+		return label || undefined;
+	} else if (verb === "askclaude") {
+		// Recursive — don't show AskClaude in its own action summary
+		return undefined;
+	}
+	return tc.name;
+}
+
+export function buildActionSummary(calls: Map<string, ToolCallState>): string {
+	const parts: string[] = [];
+	let prevVerb = "";
+	for (const [, tc] of calls) {
+		const action = formatToolAction(tc);
+		if (!action) continue;
+		const verb = tc.name.toLowerCase().split(/\s/)[0];
+		// Collapse consecutive calls to the same tool — keep only the latest
+		if (verb === prevVerb) {
+			parts[parts.length - 1] = action;
+		} else {
+			parts.push(action);
+		}
+		prevVerb = verb;
+	}
+	return parts.join("; ");
+}

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 };
+}