pi-claude-agent-sdk 0.7.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,114 @@
+# pi-claude-agent-sdk
+
+[![npm version](https://img.shields.io/npm/v/pi-claude-agent-sdk)](https://www.npmjs.com/package/pi-claude-agent-sdk)
+
+Pi extension that integrates Claude Code via the [Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript). Forked from [pi-claude-bridge](https://github.com/elidickinson/pi-claude-bridge) by Eli Dickinson, which was based initially on [claude-agent-sdk-pi](https://github.com/prateekmedia/claude-agent-sdk-pi) by Prateek Sunal. Adds streaming, MCP tool bridging, custom pi tool bridging, session resume/persistence, context sync, thinking support, skills forwarding, and the AskClaude tool.
+
+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. As of June 15, 2026 it uses subscription quota just like Claude Code direct does.
+
+<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-agent-sdk
+```
+
+## Provider
+
+Use `/model` to select `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-opus-4-8`, `claude-bridge/claude-opus-4-7`, `claude-bridge/claude-opus-4-6`, `claude-bridge/claude-sonnet-5`, `claude-bridge/claude-sonnet-4-6`, or `claude-bridge/claude-haiku-4-5`.
+
+Behind the scenes, pi's tools are bridged to Claude Code but it should all work like normal in pi. Bash commands get a 120-second default timeout (matching Claude Code's default) since pi's bash has no timeout by default. Skills in pi are copied over to Claude Code's system prompt so should work as they would with any other pi provider. Steering works mid-turn: a message sent while Claude is running a tool reaches it at that tool boundary, not after the whole turn finishes.
+
+**1M Context:** Opus 5, Opus 4.8, and Opus 4.7 get 1M context by default. Opus 4.6 only gets 1M if you're on a Max plan or pay for Extra Usage. Sonnet 4.6 only gets 1M if you pay for Extra Usage. You will need to set `provider.plan` and/or `provider.longContextExtraUsage` for 1M context in Opus 4.6/Sonnet 4.6 as described in [Configuration](#configuration).
+
+## AskClaude Tool
+
+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"
+- "Find all the places in the codebase that handle auth"
+
+You could also create skills or add something to AGENTS.md to e.g. "Always call Ask Claude to review complicated feature implementations before considering the task complete."
+
+### 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 `true`)
+- `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"` for Max (or Team Premium/Enterprise) to enable Opus 4.6 with 1M 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"`.
+
+
+**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.
+
+## Tests
+
+`npm run test:unit` for offline tests (`tests/unit-*.mjs`: queue, import, skills). 
+
+`npm test` for the full suite, which adds integration tests that hit APIs (`tests/int-*.{sh,mjs}`: smoke, multi-turn, cache, session-resume, session-rebuild, tool-message). Set `CLAUDE_BRIDGE_TESTING_ALT_MODEL` in `.env.test` for the alt-provider smoke test (e.g. `openrouter/z-ai/glm-4.7-flash`).
+
+Integration tests spawn real `pi` and Claude Code subprocesses, so they need write access to `~/.claude` for CC's session state — a sandbox that blocks it makes the next turn's `--resume` fail with `No conversation found with session ID`. The RPC harness probes for this at startup and fails fast.
+
+## Debugging
+
+Set `CLAUDE_BRIDGE_DEBUG=1` to enable debug output:
+
+- **Bridge log** at `~/.pi/agent/claude-bridge.log` — every provider call, session sync decision, tool result delivery, and CC's stderr. Override location with `CLAUDE_BRIDGE_DEBUG_PATH`.
+- **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 `askclaude` (sub-delegation). 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.
+
+## Maintenance
+
+After a Claude Code release, review `MODE_DISALLOWED_TOOLS` in `src/index.ts` — it gates which CC tools the AskClaude subagent may invoke per mode (`read` / `full` / `none`). Add new agentic tools (PlanMode, Task spawning, etc.) to the appropriate mode lists if they shouldn't be available to subagents.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "pi-claude-agent-sdk",
+  "version": "0.7.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",
+  "contributors": [
+    "Evan Verma"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pi-pod/pi-claude-agent-sdk.git"
+  },
+  "homepage": "https://github.com/pi-pod/pi-claude-agent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/pi-pod/pi-claude-agent-sdk/issues"
+  },
+  "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 && npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs",
+    "test:usage": "tests/usage-test.sh",
+    "typecheck": "tsc --noEmit"
+  },
+  "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",
+    "change-case": "^5.4.4",
+    "typebox": "^1.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.82.1",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
+    "@earendil-works/pi-tui": ">=0.82.1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.82.1",
+    "@earendil-works/pi-coding-agent": "^0.82.1",
+    "@earendil-works/pi-tui": "^0.82.1",
+    "@types/node": "^24.13.2",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/agents-md.ts

@@ -0,0 +1,20 @@
+// 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";
+
+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;
+
+	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-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/config.ts

@@ -0,0 +1,78 @@
+// User-facing extension config. Loaded once at extension registration from
+// the global agent dir (getAgentDir(), e.g. ~/.pi/agent/claude-bridge.json)
+// and the project Pi config directory, project overriding global. Missing or
+// 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";
+
+export interface Config {
+	/** Date (YYYY-MM-DD) the one-time startup notice was shown. Written by the extension, not the user. */
+	startupNoticeShown?: string;
+	askClaude?: {
+		enabled?: boolean;
+		name?: string;
+		label?: string;
+		description?: string;
+		defaultMode?: "full" | "read" | "none";
+		defaultIsolated?: boolean;
+		allowFullMode?: boolean;
+		appendSkills?: boolean;
+	};
+	/** Low-level Claude Agent SDK plumbing. Most users won't need these. */
+	provider?: {
+		appendSystemPrompt?: boolean;
+		settingSources?: SettingSource[];
+		strictMcpConfig?: boolean;
+		autoMemoryEnabled?: boolean;
+		pathToClaudeCodeExecutable?: string;
+		// Subscription plan tier. Setting to "max" enables Opus 4.6 at 1M context
+		plan?: "pro" | "max";
+		// Set to true to opt into metered 1M context usage ("extra usage" in
+		// Anthropic billing). Enables Sonnet 4.6 [1m] on every plan and Opus 4.6
+		// [1m] on Pro.
+		longContextExtraUsage?: boolean;
+	};
+}
+
+export function tryParseJson(path: string): Partial<Config> {
+	if (!existsSync(path)) return {};
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch (e) {
+		console.error(`claude-bridge: failed to parse ${path}: ${e}`);
+		return {};
+	}
+}
+
+export function claudeCodeSettings(provider: Config["provider"] = {}): { autoMemoryEnabled: boolean } {
+	return { autoMemoryEnabled: provider.autoMemoryEnabled ?? false };
+}
+
+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. */
+export function markStartupNoticeShown(): string {
+	const path = globalConfigPath();
+	// 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 };
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+	return path;
+}
+
+export function loadConfig(cwd: string): Config {
+	const global = tryParseJson(globalConfigPath());
+	const project = tryParseJson(join(cwd, CONFIG_DIR_NAME, "claude-bridge.json"));
+	return {
+		startupNoticeShown: project.startupNoticeShown ?? global.startupNoticeShown,
+		askClaude: { ...global.askClaude, ...project.askClaude },
+		provider: { ...global.provider, ...project.provider },
+	};
+}

package/src/convert.ts

@@ -0,0 +1,186 @@
+// Pure pi→Anthropic message conversion helpers.
+// Extracted so they can be tested without pulling in the full extension runtime.
+
+import type { Message as PiMessage } from "@earendil-works/pi-ai";
+import type { Message as SessionMessage } from "cc-session-io";
+import { pascalCase } from "change-case";
+import { MCP_TOOL_PREFIX } from "./skills.js";
+
+export const PROVIDER_ID = "claude-bridge";
+
+// Pi tool names under Claude Code's builtin names. Only ever correct on the
+// AskClaude path, where CC runs its own tools — see mapPiToolNameToSdk.
+export const PI_TO_SDK_TOOL_NAME: Record<string, string> = {
+	read: "Read", write: "Write", edit: "Edit", bash: "Bash",
+};
+
+export function sanitizeToolId(id: string, cache: Map<string, string>): string {
+	const existing = cache.get(id);
+	if (existing) return existing;
+	const clean = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+	cache.set(id, clean);
+	return clean;
+}
+
+/** A pi tool name as the name a rebuilt transcript has to call it by.
+ *
+ *  Whether a map is passed is what distinguishes the two query shapes, because
+ *  they need opposite answers:
+ *
+ *  - **With a map — the provider path.** The query runs `tools: []`, so every
+ *    tool Claude can call is a pi tool served over MCP, and its name is
+ *    `mcp__custom-tools__<pi name>` by construction (resolveMcpTools). The map
+ *    is consulted first only because it carries the served tool's exact casing.
+ *    A name it lacks is a tool pi ran that we do not serve now — AskClaude,
+ *    excluded on purpose, or an extension since disabled — and naming that after
+ *    a Claude Code builtin would tell the model a builtin it cannot call is
+ *    available and was already used. That is the prompt condition behind the
+ *    phantom-call deadlock fixed in 122914dd, and the read direction refuses the
+ *    same names for the same reason (piToolNameFor in index.ts).
+ *  - **Without a map — the AskClaude path.** CC runs its own tools there, so
+ *    builtin names are real, matching mapToolName in the other direction.
+ */
+export function mapPiToolNameToSdk(name: string, customToolNameToSdk?: Map<string, string>): string {
+	if (!name) return "";
+	const normalized = name.toLowerCase();
+	// Pi history holds pi tool names. Our own SDK prefix can only reach here by
+	// feeding already-converted names back through the conversion, and prefixing
+	// twice invents a tool nobody serves.
+	if (normalized.startsWith(MCP_TOOL_PREFIX)) {
+		throw new Error(`mapPiToolNameToSdk: "${name}" is already an SDK tool name — pi history holds pi tool names`);
+	}
+	if (!customToolNameToSdk) return PI_TO_SDK_TOOL_NAME[normalized] ?? pascalCase(name);
+	return customToolNameToSdk.get(name) ?? customToolNameToSdk.get(normalized) ?? `${MCP_TOOL_PREFIX}${name}`;
+}
+
+export function messageContentToText(
+	content: string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts = [];
+	let hasText = false;
+	for (const block of content) {
+		if (block.type === "text" && block.text) { parts.push(block.text); hasText = true; }
+		else if (block.type !== "text" && block.type !== "image") { parts.push(`[${block.type}]`); }
+	}
+	return hasText ? parts.join("\n") : "";
+}
+
+// Tool results are flattened to text, which is how Claude Code stores most of
+// them. Images are the exception: they have no text form, so a result carrying
+// one keeps the block array shape instead (also what CC writes for screenshots).
+function toolResultContent(
+	content: string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+): string | Array<Record<string, unknown>> {
+	if (typeof content === "string" || !Array.isArray(content)) return messageContentToText(content) || "";
+	const images = content.filter((b) => b.type === "image" && b.data && b.mimeType);
+	if (!images.length) return messageContentToText(content) || "";
+	const blocks: Array<Record<string, unknown>> = [];
+	for (const block of content) {
+		if (block.type === "text" && block.text) blocks.push({ type: "text", text: block.text });
+		else if (block.type === "image" && block.data && block.mimeType) {
+			blocks.push({ type: "image", source: { type: "base64", media_type: block.mimeType, data: block.data } });
+		} else if (block.type !== "text" && block.type !== "image") {
+			// Same marker messageContentToText leaves for unrecognized blocks, so the
+			// text and image paths describe an extension's output the same way.
+			blocks.push({ type: "text", text: `[${block.type}]` });
+		}
+	}
+	return blocks;
+}
+
+/** Convert pi message array to Anthropic API format. */
+export function convertPiMessages(
+	messages: PiMessage[],
+	customToolNameToSdk?: Map<string, string>,
+): { anthropicMessages: SessionMessage[]; sanitizedIds: Map<string, string> } {
+	const anthropicMessages = [];
+	const sanitizedIds = 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.
+	let turnResults: { role: "user"; content: Array<Record<string, unknown>> } | null = null;
+	let turnAssistantIdx: number | null = null;
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			if (typeof msg.content === "string") {
+				anthropicMessages.push({ role: "user", content: msg.content || "[empty]" });
+			} else if (Array.isArray(msg.content)) {
+				const parts = [];
+				for (const block of msg.content) {
+					if (block.type === "text" && block.text) parts.push({ type: "text", text: block.text });
+					else if (block.type === "image" && block.data && block.mimeType) {
+						parts.push({ type: "image", source: { type: "base64", media_type: block.mimeType, data: block.data } });
+					}
+				}
+				anthropicMessages.push({ role: "user", content: parts.length ? parts : "[image]" });
+			} else {
+				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) {
+				if (block.type === "text" && block.text) {
+					blocks.push({ type: "text", text: block.text });
+				} else if (block.type === "thinking") {
+					// Only replay thinking Claude Code itself produced. A signature minted
+					// by any other provider — including pi's own Anthropic provider — is
+					// not ours to hand back, and Anthropic rejects ones it can't verify.
+					const sig = block.thinkingSignature;
+					if (msg.provider === PROVIDER_ID && sig) {
+						blocks.push({ type: "thinking", thinking: block.thinking ?? "", signature: sig });
+					}
+				} 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 ?? {} });
+				}
+			}
+			if (!blocks.length) blocks.push({ type: "text", text: "[incompatible content omitted]" });
+			anthropicMessages.push({ role: "assistant", content: blocks });
+		} else if (msg.role === "toolResult") {
+			// Pi records one message per tool result, and repairToolPairing only
+			// pairs results that share the user message directly after their
+			// assistant message. Split across messages, the second and later results
+			// match no pending tool_use id: they are dropped and replaced with a
+			// synthetic "[no tool result recorded]", so every rebuild silently
+			// destroyed the output of parallel tool calls. Session.importMessages
+			// applies the repair itself, so this cannot be opted out of by skipping
+			// our own call. (Claude Code's live writer splits a turn across records
+			// — one per content block, one per result — so the single-message shape
+			// is repairToolPairing's requirement, not a copy of CC's own layout;
+			// tests/int-cc-contracts.mjs pins both facts.)
+			//
+			// Collecting into the turn's first result message rather than the
+			// immediately preceding one also handles a steer landing mid-execution,
+			// which pi records between the results (see extractAllToolResults).
+			// The results also have to sit *directly* after their assistant message:
+			// repairToolPairing consumes the turn's pending ids at the first user
+			// message that follows it, so a steer arriving before the first result —
+			// what any steer during a slow first tool looks like — would otherwise
+			// take the stubs and strand every real result behind it.
+			//
+			// Both hoists reorder the steer against wall-clock: Claude sees results
+			// that were still running when the steer arrived. Claude Code normalizes
+			// to the same order — it records a mid-turn steer as an `attachment`, and
+			// reorderAttachmentsForAPI (claude-code-rip src/utils/messages.ts:1481)
+			// bubbles attachments up to the nearest assistant or tool_result message
+			// and re-inserts them after it. The on-disk form differs, the order does not.
+			const block = { type: "tool_result", tool_use_id: sanitizeToolId(msg.toolCallId, sanitizedIds), content: toolResultContent(msg.content), is_error: msg.isError };
+			if (turnResults) {
+				turnResults.content.push(block);
+			} else {
+				turnResults = { role: "user", content: [block] };
+				// A result with no assistant message before it is malformed history;
+				// appending keeps it in order for repairToolPairing to discard.
+				anthropicMessages.splice(turnAssistantIdx === null ? anthropicMessages.length : turnAssistantIdx + 1, 0, turnResults);
+			}
+		}
+	}
+
+	return { anthropicMessages, sanitizedIds };
+}

package/src/extract-tool-results.ts

@@ -0,0 +1,47 @@
+// Tool-result extraction: walks the context tail to collect this turn's
+// tool results. Pi appends results to context and calls the provider again;
+// this scrapes them back out. Walks past user messages (steer/followUp) that
+// pi may inject between toolResults. Stops at the nearest assistant message
+// (turn boundary).
+// Extracted from index.ts so tests can import without activating the extension.
+
+export type McpContent = Array<
+	| { type: "text"; text: string }
+	| { type: "image"; data: string; mimeType: string }
+>;
+
+export interface McpResult {
+	content: McpContent;
+	isError?: boolean;
+	toolCallId?: string;
+	[key: string]: unknown;
+}
+
+export function toolResultToMcpContent(
+	content: string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+): McpContent {
+	if (typeof content === "string") return [{ type: "text", text: content || "" }];
+	if (!Array.isArray(content)) return [{ type: "text", text: "" }];
+	const blocks: McpContent = [];
+	for (const block of content) {
+		if (block.type === "text" && block.text) blocks.push({ type: "text", text: block.text });
+		else if (block.type === "image" && block.data && block.mimeType) blocks.push({ type: "image", data: block.data, mimeType: block.mimeType });
+	}
+	return blocks.length ? blocks : [{ type: "text", text: "" }];
+}
+
+// Returns { results, stopIdx } so callers can log the walk boundary.
+export function extractAllToolResults(
+	messages: Array<{ role: string; content?: unknown; toolCallId?: string; isError?: boolean; [key: string]: unknown }>,
+): { results: McpResult[]; stopIdx: number } {
+	const results: McpResult[] = [];
+	let stopIdx = -1;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "toolResult") {
+			results.unshift({ content: toolResultToMcpContent(msg.content as string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>), isError: msg.isError, toolCallId: msg.toolCallId });
+		} else if (msg.role === "assistant") { stopIdx = i; break; }
+		// user messages: skip (steer/followUp injected mid-tool-execution)
+	}
+	return { results, stopIdx };
+}