@huseynsnmz/pi-suite 0.2.2 → 0.2.4

package/packages/subscription/src/cc-sessions.ts

@@ -0,0 +1,122 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { assistantBlocks, type TurnMessage, userTurnBlocks } from "./convert.ts";
+
+function projectsRoot(): string {
+	return join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), "projects");
+}
+
+/** Claude Code's per-project session directory: the working directory's realpath, sanitized. */
+export function projectDir(cwd: string): string {
+	let real = cwd;
+	try {
+		real = realpathSync(cwd);
+	} catch {}
+	return join(projectsRoot(), real.replace(/[^a-zA-Z0-9]/g, "-"));
+}
+
+/** Path of a session's transcript, wherever Claude Code filed it. */
+export function sessionFile(cwd: string, sessionId: string): string | undefined {
+	const name = `${sessionId}.jsonl`;
+	const direct = join(projectDir(cwd), name);
+	if (existsSync(direct)) return direct;
+	try {
+		for (const dir of readdirSync(projectsRoot())) {
+			const f = join(projectsRoot(), dir, name);
+			if (existsSync(f)) return f;
+		}
+	} catch {}
+	return undefined;
+}
+
+/**
+ * Legacy-anchor fallback: the uuid of the last transcript entry Claude Code wrote for API
+ * message `messageId` (it stores one entry per content block). New anchors capture this uuid
+ * from the SDK stream instead; this scan serves anchors persisted before that was possible.
+ */
+export function findMessageUuid(cwd: string, sessionId: string, messageId: string): string | undefined {
+	const file = sessionFile(cwd, sessionId);
+	if (!file) return undefined;
+	let uuid: string | undefined;
+	for (const line of readFileSync(file, "utf8").split("\n")) {
+		if (!line.includes(messageId)) continue;
+		try {
+			const e = JSON.parse(line);
+			if (e.type === "assistant" && e.message?.id === messageId && !e.isSidechain) uuid = e.uuid;
+		} catch {}
+	}
+	return uuid;
+}
+
+/**
+ * Write a Claude Code transcript for history that never ran through Claude Code (another
+ * provider's turns, a compacted session, a session from before this extension). Returns the
+ * session id and the uuid to resume at. `messages` must end with an assistant message.
+ */
+export function synthesizeSession(cwd: string, model: string, messages: TurnMessage[]): { sessionId: string; at: string } {
+	const sessionId = randomUUID();
+	const lines: string[] = [];
+	let parent: string | null = null;
+	const now = Date.now();
+	const common = { isSidechain: false, userType: "external", entrypoint: "sdk-cli", cwd, sessionId };
+	// Thinking signatures are only needed (and only checked) inside the trailing tool loop;
+	// earlier thinking is dropped by the API anyway.
+	let lastUserText = -1;
+	messages.forEach((m, i) => {
+		if (m.role === "user") lastUserText = i;
+	});
+	let i = 0;
+	let n = 0;
+	while (i < messages.length) {
+		const uuid = randomUUID();
+		const timestamp = new Date(now - (messages.length - i) * 1000).toISOString();
+		const m = messages[i];
+		if (m.role === "assistant") {
+			const keepThinking = i > lastUserText && m.model === model && (m.api === "claude-agent-sdk" || m.api === "anthropic-messages");
+			const content = assistantBlocks(m as AssistantMessage, keepThinking);
+			lines.push(
+				JSON.stringify({
+					parentUuid: parent,
+					...common,
+					type: "assistant",
+					message: {
+						id: `msg_pi_${(n++).toString(36)}_${sessionId.slice(0, 8)}`,
+						type: "message",
+						role: "assistant",
+						model,
+						content: content.length > 0 ? content : [{ type: "text", text: "(empty)" }],
+						stop_reason: content.some((c) => c.type === "tool_use") ? "tool_use" : "end_turn",
+						stop_sequence: null,
+						usage: { input_tokens: 0, output_tokens: 0 },
+					},
+					uuid,
+					timestamp,
+				}),
+			);
+			i++;
+		} else {
+			let j = i;
+			while (j < messages.length && messages[j].role !== "assistant") j++;
+			const content = userTurnBlocks(messages.slice(i, j));
+			lines.push(
+				JSON.stringify({
+					parentUuid: parent,
+					...common,
+					type: "user",
+					message: { role: "user", content: content.length > 0 ? content : [{ type: "text", text: "(empty)" }] },
+					uuid,
+					timestamp,
+				}),
+			);
+			i = j;
+		}
+		parent = uuid;
+	}
+	mkdirSync(projectDir(cwd), { recursive: true });
+	// The whole conversation, so only you can read it, as with Claude Code's own files.
+	writeFileSync(join(projectDir(cwd), `${sessionId}.jsonl`), `${lines.join("\n")}\n`, { mode: 0o600, flag: "wx" });
+	return { sessionId, at: parent! };
+}

package/packages/subscription/src/config.ts

@@ -0,0 +1,34 @@
+import { readSection } from "../../../src/settings.ts";
+
+export interface Config {
+	pathToClaudeCodeExecutable?: string;
+	/** "claude" (default): a pi prompt prefix written for Claude. "pi": pi's default prompt. */
+	promptMode?: "claude" | "pi";
+	maxSessions?: number;
+	idleMinutes?: number;
+}
+
+const intIn = (lo: number, hi: number) => (n: unknown): n is number => Number.isInteger(n) && (n as number) >= lo && (n as number) <= hi;
+const validMaxSessions = intIn(1, 16);
+const validIdleMinutes = intIn(1, 24 * 60);
+
+/** Its settings are all conveniences, so broken ones just mean the defaults. */
+function readSaved(agentDir: string): Record<string, unknown> {
+	try {
+		return readSection(agentDir, "subscription");
+	} catch {
+		return {};
+	}
+}
+
+/** Global only: a repository must not choose which program runs, or how many, or how your prompt is built. */
+export function resolveConfig(where: { agentDir: string; env: Record<string, string | undefined> }): Config {
+	const saved = readSaved(where.agentDir);
+	const path = where.env.PI_CLAUDE_SDK_CLAUDE_PATH ?? saved.pathToClaudeCodeExecutable;
+	return {
+		...(typeof path === "string" && path !== "" ? { pathToClaudeCodeExecutable: path } : {}),
+		...(validMaxSessions(saved.maxSessions) ? { maxSessions: saved.maxSessions } : {}),
+		...(validIdleMinutes(saved.idleMinutes) ? { idleMinutes: saved.idleMinutes } : {}),
+		promptMode: where.env.PI_CLAUDE_SDK_PROMPT === "pi" || (where.env.PI_CLAUDE_SDK_PROMPT === undefined && saved.promptMode === "pi") ? "pi" : "claude",
+	};
+}

package/packages/subscription/src/convert.ts

@@ -0,0 +1,161 @@
+import type {
+	AssistantMessage,
+	ImageContent,
+	Message,
+	SystemMessage,
+	TextContent,
+	Tool,
+	ToolResultMessage,
+	TranscriptContext,
+	UserMessage,
+} from "@earendil-works/pi-ai";
+import { getCurrentTools, getInitialSystemMessage, getSystemMessageText, renderSystemMessageUpdate, toToolDeclaration } from "@earendil-works/pi-ai";
+import { sha, stableStringify } from "./util.ts";
+
+export const MCP_SERVER = "pi";
+export const MCP_PREFIX = `mcp__${MCP_SERVER}__`;
+
+/** A transcript message the provider consumes: everything but the leading system message. */
+export type TurnMessage = UserMessage | AssistantMessage | ToolResultMessage | SystemMessage;
+
+export interface Transcript {
+	/** Leading system prompt text; fixed for the lifetime of a Claude Code session. */
+	systemPrompt: string;
+	/** Tools in effect for this request (after every transcript delta). */
+	tools: Tool[];
+	toolsHash: string;
+	messages: TurnMessage[];
+	/** chain[i] identifies the conversation state after messages[0..i). chain[0] is the prompt alone. */
+	chain: string[];
+}
+
+/**
+ * Prepare pi's transcript for Claude Code. Failed or aborted assistant turns are dropped, as pi's
+ * built-in Anthropic provider does, together with tool results that answer their calls.
+ */
+export function readTranscript(context: TranscriptContext): Transcript {
+	const leading = getInitialSystemMessage(context.messages);
+	const systemPrompt = leading ? getSystemMessageText(leading) : "";
+	const tools = getCurrentTools(context.messages).map(toToolDeclaration);
+	const messages: TurnMessage[] = [];
+	const droppedCalls = new Set<string>();
+	for (const m of context.messages) {
+		if (m === leading) continue;
+		if (m.role === "assistant" && (m.stopReason === "error" || m.stopReason === "aborted")) {
+			for (const c of m.content) if (c.type === "toolCall") droppedCalls.add(c.id);
+			continue;
+		}
+		if (m.role === "toolResult" && droppedCalls.has(m.toolCallId)) continue;
+		messages.push(m as TurnMessage);
+	}
+	const chain = [sha(`prompt\0${systemPrompt}`)];
+	for (const m of messages) chain.push(sha(`${chain[chain.length - 1]}\0${fingerprint(m)}`));
+	return { systemPrompt, tools, toolsHash: sha(stableStringify(tools)), messages, chain };
+}
+
+/** Content identity of a message: what the model sees, without timestamps, usage or ids pi adds. */
+export function fingerprint(m: TurnMessage): string {
+	switch (m.role) {
+		case "user":
+			return stableStringify(["u", normContent(m.content)]);
+		case "toolResult":
+			return stableStringify(["r", m.toolCallId, normContent(m.content), !!m.isError]);
+		case "system":
+			return stableStringify(["s", renderSystemMessageUpdate(m)]);
+		case "assistant":
+			return stableStringify([
+				"a",
+				m.content
+					.filter((c) => !(c.type === "text" && c.text.length === 0))
+					.map((c) =>
+						c.type === "text"
+							? ["t", c.text]
+							: c.type === "thinking"
+								? ["k", c.thinking, c.thinkingSignature ?? "", !!c.redacted]
+								: ["c", c.id, c.name, c.arguments],
+					),
+			]);
+	}
+}
+
+function normContent(content: string | (TextContent | ImageContent)[]): unknown {
+	if (typeof content === "string") return [["t", content]];
+	return content.map((c) => (c.type === "text" ? ["t", c.text] : ["i", c.mimeType, sha(c.data)]));
+}
+
+// ---- pi → Anthropic content -------------------------------------------------------------
+
+const ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Anthropic tool_use ids must match ^[a-zA-Z0-9_-]+$; ids from other providers may not. */
+export function toolUseId(id: string): string {
+	return ID_RE.test(id) ? id : `toolu_x${sha(id).slice(0, 24)}`;
+}
+
+export function toImageBlock(c: ImageContent) {
+	return { type: "image" as const, source: { type: "base64" as const, media_type: c.mimeType, data: c.data } };
+}
+
+function userBlocks(content: string | (TextContent | ImageContent)[]): any[] {
+	if (typeof content === "string") return content.length > 0 ? [{ type: "text", text: content }] : [];
+	return content
+		.filter((c) => c.type !== "text" || c.text.length > 0)
+		.map((c) => (c.type === "text" ? { type: "text", text: c.text } : toImageBlock(c)));
+}
+
+export function toolResultBlock(m: ToolResultMessage): any {
+	const content = m.content.map((c) => (c.type === "text" ? { type: "text", text: c.text } : toImageBlock(c)));
+	return {
+		type: "tool_result",
+		tool_use_id: toolUseId(m.toolCallId),
+		content: content.length > 0 ? content : [{ type: "text", text: "(no output)" }],
+		...(m.isError ? { is_error: true } : {}),
+	};
+}
+
+/** A later system message (prompt or section change), delivered as a system reminder in the user turn. */
+export function systemUpdateText(m: SystemMessage): string | undefined {
+	const text = renderSystemMessageUpdate(m).trim();
+	return text ? `<system-reminder>\n${text}\n</system-reminder>` : undefined;
+}
+
+/**
+ * Render consecutive non-assistant messages as one Anthropic user message. Tool results come
+ * first, as the API requires, then reminders and user text in transcript order.
+ */
+export function userTurnBlocks(tail: TurnMessage[]): any[] {
+	const results: any[] = [];
+	const rest: any[] = [];
+	for (const m of tail) {
+		if (m.role === "toolResult") results.push(toolResultBlock(m));
+		else if (m.role === "user") rest.push(...userBlocks(m.content));
+		else if (m.role === "system") {
+			const text = systemUpdateText(m);
+			if (text) rest.push({ type: "text", text });
+		}
+	}
+	return [...results, ...rest];
+}
+
+/** Assistant content for a synthesized Claude Code transcript. */
+export function assistantBlocks(m: AssistantMessage, keepThinking: boolean): any[] {
+	const blocks: any[] = [];
+	for (const c of m.content) {
+		if (c.type === "text") {
+			if (c.text.length > 0) blocks.push({ type: "text", text: c.text });
+		} else if (c.type === "thinking") {
+			if (!keepThinking || !c.thinkingSignature) continue;
+			if (c.redacted) blocks.push({ type: "redacted_thinking", data: c.thinkingSignature });
+			else blocks.push({ type: "thinking", thinking: c.thinking, signature: c.thinkingSignature });
+		} else if (c.type === "toolCall") {
+			blocks.push({ type: "tool_use", id: toolUseId(c.id), name: MCP_PREFIX + c.name, input: c.arguments ?? {} });
+		}
+	}
+	return blocks;
+}
+
+/** Map a tool_use name emitted by Claude back to pi's tool name. */
+export function piToolName(name: string): string {
+	return name.startsWith(MCP_PREFIX) ? name.slice(MCP_PREFIX.length) : name;
+}
+
+export type { Message };

package/packages/subscription/src/index.ts

@@ -0,0 +1,69 @@
+import { appendFileSync } from "node:fs";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir, getDocsPath, getExamplesPath, getReadmePath } from "@earendil-works/pi-coding-agent";
+import { EXTRA_USAGE_NO, EXTRA_USAGE_QUESTION, EXTRA_USAGE_YES } from "./billing.ts";
+import { resolveConfig } from "./config.ts";
+import { anthropicChatModels, claudeModels } from "./models.ts";
+import { applyClaudePrompt } from "./prompt.ts";
+import { API, ClaudeSdkProvider } from "./provider.ts";
+
+export const PROVIDER = "claude-sdk";
+
+/**
+ * pi extension: Claude models through the Claude Agent SDK, authenticated by the local Claude
+ * Code login (Pro/Max subscription). pi keeps its own agent loop, tools, prompt and compaction;
+ * Claude Code is used only as the authenticated model transport.
+ */
+export default function (pi: ExtensionAPI) {
+	const config = resolveConfig({ agentDir: getAgentDir(), env: process.env });
+	const debugPath = process.env.PI_CLAUDE_SDK_DEBUG;
+	let session: ExtensionContext | undefined;
+	const provider = new ClaudeSdkProvider({
+		// With nobody to ask, as in `pi -p` or a subagent, it stops rather than spend your money.
+		confirmExtraUsage: async (_info, signal) => {
+			if (!session?.hasUI) return false;
+			return (await session.ui.select(EXTRA_USAGE_QUESTION, [EXTRA_USAGE_NO, EXTRA_USAGE_YES], { signal })) === EXTRA_USAGE_YES;
+		},
+		pathToClaudeCodeExecutable: config.pathToClaudeCodeExecutable,
+		...(config.maxSessions ? { maxSessions: config.maxSessions } : {}),
+		...(config.idleMinutes ? { idleMs: config.idleMinutes * 60_000 } : {}),
+		debug: debugPath ? (msg) => appendFileSync(debugPath, `${new Date().toISOString()} ${msg}\n`) : undefined,
+	});
+
+	const register = (models = claudeModels()) =>
+		pi.registerProvider(PROVIDER, {
+			name: "Claude (subscription via Agent SDK)",
+			// Claude Code authenticates itself; pi only needs a non-empty key to treat the provider as configured.
+			apiKey: "claude-code-login",
+			api: API as any,
+			baseUrl: "claude-agent-sdk://local",
+			models,
+			streamSimple: provider.streamSimple,
+		});
+	register();
+
+	// Pick up Claude models newer than the bundled snapshot from pi's own catalog.
+	let refreshed = false;
+	pi.on("session_start", (_event, ctx) => {
+		session = ctx;
+		if (refreshed) return;
+		refreshed = true;
+		try {
+			const live = anthropicChatModels(ctx.modelRegistry.getAll());
+			const known = new Set(claudeModels().map((m) => m.id));
+			if (live.some((m) => !/-\d{8}$/.test(m.id) && !known.has(m.id))) register(claudeModels(live));
+		} catch {
+			// The snapshot stays registered.
+		}
+	});
+
+	const docs = { readme: getReadmePath(), docs: getDocsPath(), examples: getExamplesPath() };
+	pi.on("before_agent_start", (event, ctx) => applyClaudePrompt(event, ctx.model, config.promptMode ?? "claude", docs));
+
+	const shutdown = () => provider.shutdown();
+	process.once("exit", shutdown);
+	pi.on("session_shutdown", () => {
+		session = undefined;
+		process.off("exit", shutdown);
+		shutdown();
+	});
+}

package/packages/subscription/src/mcp.ts

@@ -0,0 +1,78 @@
+// The little of MCP that Claude Code needs to see pi's tools: the Agent SDK hands this object a
+// transport and passes JSON-RPC through it. The MCP SDK would bring a web server and more to do this.
+import type { Tool } from "@earendil-works/pi-ai";
+
+export interface ToolResult {
+	content: unknown[];
+	isError?: boolean;
+}
+
+interface Transport {
+	onmessage?: (message: JsonRpc) => void;
+	start(): Promise<void>;
+	send(message: unknown): Promise<void>;
+	close(): Promise<void>;
+}
+
+interface JsonRpc {
+	id?: string | number;
+	method?: string;
+	params?: { protocolVersion?: string; _meta?: Record<string, unknown> };
+}
+
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+
+export class ToolServer {
+	readonly #tools: unknown[];
+	readonly #call: (toolUseId: string | undefined) => Promise<ToolResult>;
+	#transport: Transport | undefined;
+
+	constructor(name: string, tools: readonly Tool[], call: (toolUseId: string | undefined) => Promise<ToolResult>) {
+		this.name = name;
+		this.#call = call;
+		this.#tools = tools.map((tool) => ({
+			name: tool.name,
+			description: tool.description,
+			inputSchema: { type: "object", ...(JSON.parse(JSON.stringify(tool.parameters ?? {})) as object) },
+		}));
+	}
+
+	readonly name: string;
+
+	async connect(transport: Transport): Promise<void> {
+		this.#transport = transport;
+		transport.onmessage = (message) => void this.#handle(message);
+		await transport.start();
+	}
+
+	async close(): Promise<void> {
+		await this.#transport?.close();
+	}
+
+	async #handle(message: JsonRpc): Promise<void> {
+		// A notification has no id and wants no answer.
+		if (message.id === undefined) return;
+		const answer = await this.#answer(message);
+		await this.#transport?.send({ jsonrpc: "2.0", id: message.id, ...answer }).catch(() => undefined);
+	}
+
+	async #answer(message: JsonRpc): Promise<{ result: unknown } | { error: { code: number; message: string } }> {
+		switch (message.method) {
+			case "initialize":
+				return { result: { protocolVersion: message.params?.protocolVersion, capabilities: { tools: {} }, serverInfo: { name: this.name, version: "1.0.0" } } };
+			case "ping":
+				return { result: {} };
+			case "tools/list":
+				return { result: { tools: this.#tools } };
+			case "tools/call":
+				try {
+					return { result: await this.#call(message.params?._meta?.["claudecode/toolUseId"] as string | undefined) };
+				} catch (error) {
+					return { error: { code: INTERNAL_ERROR, message: (error as Error).message } };
+				}
+			default:
+				return { error: { code: METHOD_NOT_FOUND, message: `Unknown method ${message.method}` } };
+		}
+	}
+}

package/packages/subscription/src/models.ts

@@ -0,0 +1,65 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { CATALOG } from "./catalog.ts";
+
+type ProviderChatModelConfig = Extract<ProviderModelConfig, { reasoning: boolean }>;
+type CatalogModel = Pick<Model<Api>, "id" | "name" | "reasoning" | "input" | "cost" | "contextWindow" | "maxTokens" | "thinkingLevelMap">;
+
+/**
+ * Chat models offered through Claude Code. Limits, prices and thinking levels come from pi's
+ * Anthropic catalog: a snapshot at load (so `--model` works at startup), refreshed from pi's live
+ * registry once a session starts (see index.ts). Dated aliases are skipped; Claude Code resolves
+ * the undated ids itself.
+ */
+export function claudeModels(source: readonly CatalogModel[] = CATALOG as unknown as CatalogModel[]): ProviderChatModelConfig[] {
+	return source
+		.filter((m) => !/-\d{8}$/.test(m.id))
+		.map((m) => ({
+			id: m.id,
+			name: `${m.name} (Claude subscription)`,
+			reasoning: m.reasoning,
+			input: m.input,
+			cost: m.cost,
+			contextWindow: m.contextWindow,
+			maxTokens: m.maxTokens,
+			...(m.thinkingLevelMap ? { thinkingLevelMap: m.thinkingLevelMap } : {}),
+			// No promptCache: Claude Code already writes one-hour cache entries, and pi's cache
+			// warmer (a one-token replay of an earlier request) cannot be expressed through it.
+		}));
+}
+
+/** pi's Anthropic models that can back this provider. */
+export function anthropicChatModels(models: readonly (CatalogModel & { provider: string; type?: string })[]): CatalogModel[] {
+	return models.filter((m) => m.provider === "anthropic" && (m.type === undefined || m.type === "chat"));
+}
+
+export type ThinkingOption = { type: "adaptive"; display: "summarized" } | { type: "disabled" } | { type: "enabled"; budgetTokens: number; display: "summarized" };
+
+const EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+
+/**
+ * Map a pi thinking level to Agent SDK thinking options. pi resolves the level through the
+ * model's thinkingLevelMap before it reaches the provider, so the value is already the
+ * provider-native effort when the model declares one.
+ */
+export function thinkingOptions(
+	level: string | undefined,
+	hasLevelMap: boolean,
+): { thinking: ThinkingOption; effort?: "low" | "medium" | "high" | "xhigh" | "max" } {
+	if (!level || level === "off") return { thinking: { type: "disabled" } };
+	if (hasLevelMap) {
+		const effort = EFFORTS.has(level) ? (level as any) : level === "minimal" ? "low" : "medium";
+		return { thinking: { type: "adaptive", display: "summarized" }, effort };
+	}
+	// Budget-based models (e.g. Haiku 4.5).
+	const budgets: Record<string, number> = { minimal: 1024, low: 2048, medium: 8192, high: 16384, xhigh: 32000, max: 48000 };
+	return { thinking: { type: "enabled", budgetTokens: budgets[level] ?? 8192, display: "summarized" } };
+}
+
+/** A budget counts toward the output cap, so the cap grows to fit it, as in pi's Anthropic provider, up to what the model allows. */
+export function fitThinking(thinking: ThinkingOption, maxTokens: number, modelMax: number): { thinking: ThinkingOption; maxOutputTokens: number } {
+	if (thinking.type !== "enabled") return { thinking, maxOutputTokens: maxTokens };
+	const maxOutputTokens = Math.min(maxTokens + thinking.budgetTokens, modelMax);
+	const budgetTokens = maxOutputTokens > thinking.budgetTokens ? thinking.budgetTokens : Math.max(1024, maxOutputTokens - 1024);
+	return { thinking: { ...thinking, budgetTokens }, maxOutputTokens };
+}

package/packages/subscription/src/prompt.ts

@@ -0,0 +1,57 @@
+import type { BeforeAgentStartEvent } from "@earendil-works/pi-coding-agent";
+
+export type PromptMode = "claude" | "pi";
+type PromptOptions = BeforeAgentStartEvent["systemPromptOptions"];
+export interface DocPaths {
+	readme: string;
+	docs: string;
+	examples: string;
+}
+
+/**
+ * pi's prompt prefix rewritten for Claude. pi drops its own tools, rules and docs sections when a
+ * custom prefix is set, so this renders them itself: every selected tool and every guideline pi or
+ * another extension contributed. Context files, skills and the working directory stay pi's.
+ */
+export function claudePreamble(o: PromptOptions, docs: DocPaths): string {
+	const tools = o.selectedTools.filter((name) => o.toolSnippets[name]).map((name) => `- ${name}: ${o.toolSnippets[name]}`);
+	const guidelines = new Set<string>();
+	const searchTools = ["grep", "find", "ls"].some((t) => o.selectedTools.includes(t));
+	if (o.selectedTools.includes("bash") && !searchTools) guidelines.add("Use bash for file discovery and search (ls, rg, find).");
+	for (const name of o.selectedTools) for (const g of o.toolGuidelines[name] ?? []) guidelines.add(g.trim());
+	for (const g of o.promptGuidelines) guidelines.add(g.trim());
+	guidelines.delete("");
+
+	return `You are Claude, working as a coding agent in pi, a terminal coding harness. You help the user by reading files, running commands, and editing code in their project.
+
+Tools:
+${tools.length > 0 ? tools.join("\n") : "(none)"}
+Other tools may be available; their definitions describe them.
+
+How to work:
+- Understand before you change: read the relevant code and search the project before editing. Don't guess file contents or APIs.
+- Make independent tool calls in parallel, such as reading several files at once. Sequence only calls that depend on each other.
+- Change existing files with targeted edits rather than rewrites. Create files only when the task needs them.
+- Stay within the request: no unrequested features, refactors, or comments.
+- Verify: run the project's tests, type checker, or the program itself when they exist, and fix what fails. If you can't verify, say so.
+- Report faithfully: never claim that something passed, ran, or exists unless you saw it.
+- If the request is ambiguous in a way that changes the result, ask. Otherwise state your assumption and proceed.
+- Be concise. Lead with the outcome and show file paths clearly.${guidelines.size > 0 ? `\n\nGuidelines:\n${[...guidelines].map((g) => `- ${g}`).join("\n")}` : ""}
+
+Questions about pi itself (extensions, skills, settings, its SDK): read ${docs.readme}, the docs in ${docs.docs} and the examples in ${docs.examples} first.`;
+}
+
+/**
+ * before_agent_start: give Claude models the Claude prefix. A user's own SYSTEM.md (customPrompt)
+ * always wins, and other providers keep pi's default prompt.
+ */
+export function applyClaudePrompt(
+	event: { systemPromptOptions: PromptOptions },
+	model: { provider: string } | undefined,
+	mode: PromptMode,
+	docs: DocPaths = { readme: "README.md", docs: "docs", examples: "examples" },
+): void {
+	if (mode !== "claude" || model?.provider !== "claude-sdk") return;
+	if (event.systemPromptOptions.customPrompt) return;
+	event.systemPromptOptions.customPrompt = claudePreamble(event.systemPromptOptions, docs);
+}