one-code-extension 0.4.1 → 0.5.0

package/extensions/lib/side-call-cache.ts

@@ -0,0 +1,124 @@
+/**
+ * Anthropic cache placement for standalone side calls. pi-ai marks the final
+ * user question, which means every different question writes a fresh cache
+ * entry. Move that marker onto the preceding conversation message instead,
+ * without changing any message text. Call this from an `anthropic-messages`
+ * payload hook, or an `openai-completions` one: Chat Completions carries the
+ * same `cache_control` markers when the model takes Anthropic's format
+ * (OpenRouter's `anthropic/*`), and has none to move otherwise.
+ */
+
+/** The APIs whose standalone side-call payload this placement applies to. */
+export const SIDE_CALL_CACHE_APIS: ReadonlySet<string> = new Set(["anthropic-messages", "openai-completions"]);
+
+/** Anthropic permits at most four cache-control markers per request. */
+export const MAX_SIDE_CALL_CACHE_MARKERS = 4;
+
+type WireRecord = Record<string, unknown>;
+
+/**
+ * Move pi-ai's final-question cache marker to the last preceding message and
+ * remove the earliest markers past Anthropic's four-marker limit. Unsupported
+ * payload shapes are left unchanged rather than being normalised.
+ */
+export function cacheSideCallConversation(payload: unknown): void {
+	if (!isRecord(payload) || !Array.isArray(payload.messages)) return;
+	const messages = payload.messages;
+	const questionIndex = messages.length - 1;
+	const question = asMessage(messages[questionIndex]);
+	if (!question || question.role !== "user") return;
+	const questionBlocks = blocks(question.content);
+	const sourceIndex = questionBlocks.findLastIndex((block) => block.cache_control !== undefined);
+	if (sourceIndex === -1) return;
+
+	const target = precedingCacheableBlock(messages, questionIndex);
+	if (!target) return;
+	const marker = questionBlocks[sourceIndex].cache_control;
+	const nextQuestionBlocks = [...questionBlocks];
+	const { cache_control: _, ...unmarked } = questionBlocks[sourceIndex];
+	nextQuestionBlocks[sourceIndex] = unmarked;
+	const nextTargetBlocks = [...target.blocks];
+	nextTargetBlocks[target.blockIndex] = { ...target.blocks[target.blockIndex], cache_control: marker };
+	const nextMessages = [...messages];
+	nextMessages[questionIndex] = { ...question, content: nextQuestionBlocks };
+	nextMessages[target.messageIndex] = { ...target.message, content: nextTargetBlocks };
+	payload.messages = nextMessages;
+	capMarkers(payload);
+}
+
+interface Target {
+	messageIndex: number;
+	message: WireRecord;
+	blocks: WireRecord[];
+	blockIndex: number;
+}
+
+/** The last prior wire block Anthropic accepts as a message cache breakpoint. */
+function precedingCacheableBlock(messages: unknown[], questionIndex: number): Target | undefined {
+	for (let messageIndex = questionIndex - 1; messageIndex >= 0; messageIndex--) {
+		const message = asMessage(messages[messageIndex]);
+		if (!message) continue;
+		// pi-ai keeps earlier user text as a string, only converting the final
+		// marked message to blocks. Convert this target exactly as pi-ai does so
+		// the newest conversation turn, rather than an older block message, gets
+		// the cache boundary. The text itself remains byte-for-byte unchanged.
+		// Chat Completions also sends assistant and tool text as strings; an
+		// empty one (a tool-call-only reply) cannot carry a marker, as in pi-ai.
+		if (typeof message.content === "string") {
+			if (message.content.length === 0) continue;
+			return { messageIndex, message, blocks: [{ type: "text", text: message.content }], blockIndex: 0 };
+		}
+		const content = blocks(message.content);
+		const blockIndex = content.findLastIndex(isCacheableBlock);
+		if (blockIndex !== -1) return { messageIndex, message, blocks: content, blockIndex };
+	}
+	return undefined;
+}
+
+function asMessage(value: unknown): WireRecord | undefined {
+	return isRecord(value) && typeof value.role === "string" ? value : undefined;
+}
+
+function blocks(value: unknown): WireRecord[] {
+	return Array.isArray(value) && value.every(isRecord) ? value : [];
+}
+
+/** This is pi-ai's own list from its Anthropic message converter. */
+function isCacheableBlock(block: WireRecord): boolean {
+	return (
+		block.type === "text" ||
+		block.type === "image" ||
+		block.type === "tool_result" ||
+		block.type === "tool_addition" ||
+		block.type === "tool_removal"
+	);
+}
+
+/** Drop the earliest actual Anthropic markers in wire order: tools, system, messages. */
+function capMarkers(payload: WireRecord): void {
+	const markers = [
+		...topLevelMarkers(payload.tools),
+		...topLevelMarkers(payload.system),
+		...messageMarkers(payload.messages),
+	];
+	for (const marker of markers.slice(0, Math.max(0, markers.length - MAX_SIDE_CALL_CACHE_MARKERS))) delete marker.cache_control;
+}
+
+/** Tool definitions and top-level system blocks can each carry one marker. */
+function topLevelMarkers(value: unknown): WireRecord[] {
+	return Array.isArray(value) ? value.filter((entry): entry is WireRecord => isRecord(entry) && entry.cache_control !== undefined) : [];
+}
+
+/** Only a message content block is an Anthropic conversation marker. Never inspect block payloads. */
+function messageMarkers(value: unknown): WireRecord[] {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((message) => (isRecord(message) ? blocks(message.content).filter((block) => block.cache_control !== undefined) : []));
+}
+
+function isRecord(value: unknown): value is WireRecord {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+
+/** The conversation cache placement a side call passes to `runSideCall` (`side-call-run.ts`). */
+export const CONVERSATION_CACHE_PLACEMENT = { apis: SIDE_CALL_CACHE_APIS, place: cacheSideCallConversation } as const;

package/extensions/lib/side-call-run.ts

@@ -0,0 +1,96 @@
+/**
+ * One standalone side call: a single `completeSimple` request outside the main
+ * agent loop, shared by `/btw`, the recap and the web_fetch reader. The
+ * auto-mode classifier has its own transport and stays out of this.
+ *
+ * Every side call takes the same steps: splice the provider's base URL from the
+ * resolved auth into the model, combine the caller's abort signal with a
+ * per-attempt timeout, key the request to the session (`<session id>:<kind>`,
+ * stable across calls, so the provider's prompt cache is reused), apply the
+ * caller's cache placement on the APIs it covers, log the attempt
+ * (`CC_SIDE_CALL_LOG`), retry with thinking on when the model cannot disable
+ * it, and report usage for the footer cost. The request on the wire is exactly
+ * what each extension built inline before (`side-call-run-wire.test.ts`).
+ *
+ * Kept apart from `side-call.ts`, which stays free of runtime pi imports for
+ * the pure prompt modules that use it.
+ */
+
+import { type Api, type AssistantMessage, type Context, cleanupSessionResources, type Model, type SimpleStreamOptions, type ThinkingLevel } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { withReasoningFallback } from "./model-policy.ts";
+import { SIDE_CALL_KINDS, type SideCallLogContext, logSideCallUsage } from "./side-call-usage.ts";
+
+/** A payload hook that places cache breakpoints, and the APIs whose payload shape it handles. */
+export interface SideCallCachePlacement {
+	apis: ReadonlySet<string>;
+	place: (payload: unknown) => void;
+}
+
+export interface SideCallRun {
+	/** Names the call in the cache key and the side-call log. */
+	kind: SideCallLogContext["kind"];
+	model: Model<Api>;
+	/** The model registry's resolved auth for `model` (the caller handles a failed lookup). */
+	auth: { apiKey?: string; headers?: SimpleStreamOptions["headers"]; env?: Record<string, string>; baseUrl?: string };
+	/** The session's id; the call's cache key is `<sessionId>:<kind>`. */
+	sessionId: string;
+	context: Context;
+	signal?: AbortSignal;
+	/** Applies to each attempt on its own, so a reasoning retry gets a full timeout. */
+	timeoutMs: number;
+	maxTokens: number;
+	/** Cache placement for the payload; none leaves pi-ai's own markers. */
+	cache?: SideCallCachePlacement;
+	/** Per-session memo of a model's required thinking level (`withReasoningFallback`). */
+	learnedReasoning?: Map<string, ThinkingLevel>;
+	/** Each attempt's usage, for the footer's all-in cost. */
+	onUsage: (usage: unknown) => void;
+}
+
+type SideCallKind = SideCallLogContext["kind"];
+
+/** A side call's cache key, which pi-ai also takes as its `sessionId`. */
+function sideCallKey(sessionId: string, kind: SideCallKind): string {
+	return `${sessionId}:${kind}`;
+}
+
+/**
+ * Close what pi-ai holds open under a session's side-call keys, every kind's
+ * (a key never used costs nothing). On openai-codex it keeps one WebSocket per
+ * `sessionId` with a 5-minute idle timer holding the process, and pi's own
+ * dispose closes only the session's id, so a `pi -p` run waited out the timer
+ * after its answer (findings §59). Every extension that runs a side call calls
+ * it as the session ends, so a new kind is released with no further change.
+ */
+export function releaseSideCalls(sessionId: string): void {
+	for (const kind of SIDE_CALL_KINDS) cleanupSessionResources(sideCallKey(sessionId, kind));
+}
+
+/** Run the side call and return the final reply; a provider failure is in its `stopReason`, as with `completeSimple`. */
+export async function runSideCall(run: SideCallRun): Promise<AssistantMessage> {
+	const { kind, model, auth, context } = run;
+	const sessionId = sideCallKey(run.sessionId, kind);
+	const target = auth.baseUrl ? ({ ...model, baseUrl: auth.baseUrl } as Model<Api>) : model;
+	const onPayload = run.cache?.apis.has(model.api) ? run.cache.place : undefined;
+	return withReasoningFallback(
+		model,
+		async (reasoning) => {
+			const timeout = AbortSignal.timeout(run.timeoutMs);
+			const reply = await completeSimple(target, context, {
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				env: auth.env,
+				signal: run.signal ? AbortSignal.any([run.signal, timeout]) : timeout,
+				maxTokens: run.maxTokens,
+				sessionId,
+				...(onPayload ? { onPayload } : {}),
+				...(reasoning ? { reasoning } : {}),
+			});
+			logSideCallUsage({ kind, model, sessionId, system: context.systemPrompt ?? "", messages: context.messages }, reply);
+			return reply;
+		},
+		run.learnedReasoning,
+		run.onUsage,
+	);
+}

package/extensions/lib/side-call-usage.ts

@@ -0,0 +1,38 @@
+/** Opt-in side-call cache evidence, independent of the provider's transport. */
+import { appendFileSync } from "node:fs";
+
+/** Every side-call kind; releaseSideCalls closes each one's pi-ai key. */
+export const SIDE_CALL_KINDS = ["reader", "btw", "recap"] as const;
+
+export interface SideCallLogContext {
+	kind: (typeof SIDE_CALL_KINDS)[number];
+	model: { provider: string; id: string; api: string };
+	sessionId: string;
+	system: string;
+	messages: readonly unknown[];
+}
+
+/**
+ * CC_SIDE_CALL_LOG names a JSONL file containing prompt text and normalized
+ * usage, never credentials or response text. Like CC_AUTO_MODE_LOG, this is
+ * explicitly opt-in and never read back. Log every completed provider attempt,
+ * including reasoning retries; a probe must not mistake an error for a hit.
+ */
+export function logSideCallUsage(call: SideCallLogContext, reply: { usage?: unknown; stopReason: string }): void {
+	const path = process.env.CC_SIDE_CALL_LOG;
+	if (!path) return;
+	try {
+		appendFileSync(path, `${JSON.stringify({
+			kind: call.kind,
+			model: `${call.model.provider}/${call.model.id}`,
+			api: call.model.api,
+			sessionId: call.sessionId,
+			system: call.system,
+			messages: call.messages,
+			usage: reply.usage,
+			stopReason: reply.stopReason,
+		})}\n`);
+	} catch {
+		// A diagnostic log that cannot be written must not fail a side call.
+	}
+}

package/extensions/lib/side-call.ts

@@ -40,6 +40,18 @@ export function trimToTurnBoundary<T extends { role: string }>(messages: readonl
 	return start === -1 ? [] : messages.slice(start);
 }
 
+/**
+ * The conversation without pi's `system` transcript messages, for a capture of
+ * the `context` event. pi 0.86 hands `context` handlers a leading system message
+ * holding pi's own default prompt sections and every full tool schema; a side
+ * call that forwarded it had pi-ai replay those into its system prompt and tools
+ * (over the stubs), and it shifted every role-by-index comparison. pi 0.87 strips
+ * system messages before `context` handlers run, so there this is a no-op.
+ */
+export function withoutSystemMessages<T extends { role: string }>(messages: readonly T[]): T[] {
+	return messages.filter((message) => message.role !== "system");
+}
+
 /** The placeholder left in a message whose only content was an image we removed. */
 export const IMAGE_OMITTED_TEXT = "[image omitted]";
 
@@ -55,7 +67,7 @@ export const IMAGE_OMITTED_TEXT = "[image omitted]";
  * placeholder text block, so it stays a valid turn on strict providers. Purely
  * structural (any `{ role, content }` message) to stay free of runtime pi
  * imports; assistant messages carry no images and pass through untouched.
- * See `docs/decisions/model-policy.md`.
+ * See `working-docs/decisions/model-policy.md`.
  */
 export function stripImageBlocks<M extends { role: string; content: unknown }>(messages: readonly M[]): M[] {
 	return messages.map((message) => {

package/extensions/lib/single-flight.ts

@@ -0,0 +1,18 @@
+/**
+ * One in-flight run per key (pure): a call while a run for its key is pending
+ * shares that run's promise instead of starting another; once it settles, the
+ * next call starts fresh. Used where two overlapping callers would otherwise
+ * both pass an "is it there yet?" check across an await and duplicate work
+ * that must happen once (a language server spawn, a consent dialog).
+ */
+export function singleFlight<T>(): (key: string, run: () => Promise<T>) => Promise<T> {
+	const pending = new Map<string, Promise<T>>();
+	return (key, run) => {
+		let current = pending.get(key);
+		if (!current) {
+			current = run().finally(() => pending.delete(key));
+			pending.set(key, current);
+		}
+		return current;
+	};
+}

package/extensions/lib/skill-body.ts

@@ -0,0 +1,42 @@
+/**
+ * Skills whose body is generated, not read from their SKILL.md: Claude Code's
+ * `/loop` builds a different prompt per argument shape (findings §21). The
+ * skill extension emits a `SkillBodyQuery` on SKILL_BODY_CHANNEL before it
+ * delivers a skill; the extension that owns the skill fills `body`
+ * synchronously, and the SKILL.md body is the fallback.
+ *
+ * A fired scheduled prompt that is a slash command (`/loop check the deploy`,
+ * `/babysit-prs`) runs the way Claude Code runs it, as if typed: the
+ * background extension emits a `SlashExpandQuery` on SLASH_EXPAND_CHANNEL
+ * and the skill extension fills `expanded` with the skill's block.
+ *
+ * Pure: no pi imports.
+ */
+
+export const SKILL_BODY_CHANNEL = "one-code:skill-body";
+export const SLASH_EXPAND_CHANNEL = "one-code:slash-expand";
+
+export interface SkillBodyQuery {
+	/** The skill's name. */
+	skill: string;
+	/** Its SKILL.md, so a provider answers only for its own file. */
+	path: string;
+	args: string;
+	cwd: string;
+	/** Set by the provider; the arguments are then part of it. */
+	body?: string;
+}
+
+export interface SlashExpandQuery {
+	/** The fired prompt, starting with `/`. */
+	text: string;
+	cwd: string;
+	/** Set by the skill extension when the command is a skill. */
+	expanded?: string;
+}
+
+/** `/name rest` split, or undefined when `text` is not a slash command. */
+export function parseSlashCommand(text: string): { name: string; args: string } | undefined {
+	const match = /^\/([^\s/][^\s]*)(?:\s+([\s\S]*))?$/.exec(text.trim());
+	return match ? { name: match[1], args: (match[2] ?? "").trim() } : undefined;
+}

package/extensions/lib/skill-scan.ts

@@ -3,22 +3,26 @@
  * command registration (pure fs). (The /plugins Installed tab builds its rows
  * from discoverPlugins directly and no longer calls this.)
  *
- * Scans the SAME directories claude-compat feeds to pi, in pi's order —
- * `~/.claude/skills`, `~/.agents/skills`, `<cwd>/.claude/skills`,
- * `<cwd>/.agents/skills`, `<agentDir>/skills`, then the bundled catalog last
- * (so it loses a name collision, as it does in pi) — and merges the plugin
- * skills the caller resolved. Rows carry the SKILL.md path (for the ~token
+ * Scans the SAME directories pi loads, in pi's order — `<agentDir>/skills`
+ * (pi's own), then the ones claude-compat feeds it: `~/.claude/skills`,
+ * `~/.agents/skills`, `<cwd>/.claude/skills`, `<cwd>/.agents/skills`, and the
+ * bundled catalog last — and merges the plugin skills the caller resolved.
+ * As in pi, a name loads once (the first wins, so the bundled catalog loses a
+ * collision) and a file reached twice through a link counts once, so the
+ * banner, `/skills` and `/doctor` count the skills pi actually loads. Rows carry the SKILL.md path (for the ~token
  * size estimate) and the scope used by skill-overrides keys. Before the first
  * turn this scan is the only skill list One Code has (pi resolves skills per
  * turn), so a root missing here is a skill with no `/name` command at startup.
  */
 
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { PluginSkill } from "./plugins.ts";
 import type { SkillScope } from "./skill-overrides.ts";
-import { claudeUserDir } from "./paths.ts";
+import { claudeSourcesOn, projectConfigDir, userConfigDir } from "./config-mode.ts";
+import { claudeUserDir, isPathAtOrUnder, tryRealpath } from "./paths.ts";
+import { parseFrontmatterLoosely } from "./frontmatter.ts";
 
 /** The skill catalog shipped in this package: `<package>/skills` (Claude Code's self-contained built-in skills). */
 export const BUNDLED_SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
@@ -31,16 +35,38 @@ export interface ScannedSkill {
 
 /**
  * The one scope-classification rule for a skill path — user skills live under
- * `~/.claude/skills` AND `<agentDir>/skills`; everything else is project
+ * `~/.claude/skills`, `~/.agents/skills` and `<agentDir>/skills`; everything else is project
  * scope. Both the scanner and the skill extension classify through this, so a
  * skill never shows different scopes in /plugins vs the skill tool.
  */
 export function scopeForPath(path: string, home: string, agentDir: string): SkillScope {
-	if (path.startsWith(join(claudeUserDir(home), "skills")) || path.startsWith(join(agentDir, "skills"))) return "user";
-	return "project";
+	const roots = [join(claudeUserDir(home), "skills"), join(home, ".agents", "skills"), join(agentDir, "skills")];
+	return roots.some((root) => isPathAtOrUnder(path, root)) ? "user" : "project";
 }
 
-function scanDir(dir: string, scope: SkillScope, into: Map<string, ScannedSkill>): void {
+/**
+ * The skill folders One Code adds to pi's own (`<agentDir>/skills`, which pi
+ * scans itself), in load order: Claude Code's two only in Claude-compatible
+ * mode (lib/config-mode.ts), the cross-tool `.agents` pair in both. `claudeDir`
+ * defaults to `~/.claude` (`CLAUDE_CONFIG_DIR`); `~/.agents` is never moved.
+ */
+export function skillSourceDirs(cwd: string, home: string, claudeDir: string = claudeUserDir(home)): Array<{ dir: string; scope: SkillScope }> {
+	const claude = claudeSourcesOn();
+	const dirs: Array<{ dir: string; scope: SkillScope } | false> = [
+		claude && { dir: join(claudeDir, "skills"), scope: "user" },
+		{ dir: join(home, ".agents", "skills"), scope: "user" },
+		claude && { dir: join(cwd, ".claude", "skills"), scope: "project" },
+		{ dir: join(cwd, ".agents", "skills"), scope: "project" },
+	];
+	return dirs.filter((d): d is { dir: string; scope: SkillScope } => d !== false);
+}
+
+/** The prompt-template folders: `~/.claude/commands` and `.claude/commands`, or their `.onecode` twins in independent mode. */
+export function commandDirs(cwd: string, home: string, claudeDir: string = claudeUserDir(home)): string[] {
+	return [join(claudeSourcesOn() ? claudeDir : userConfigDir(home), "commands"), join(projectConfigDir(cwd), "commands")];
+}
+
+function scanDir(dir: string, scope: SkillScope, into: Map<string, ScannedSkill>, seenFiles: Set<string>): void {
 	if (!existsSync(dir)) return;
 	let entries: string[];
 	try {
@@ -51,9 +77,18 @@ function scanDir(dir: string, scope: SkillScope, into: Map<string, ScannedSkill>
 	for (const entry of entries) {
 		const skillFile = join(dir, entry, "SKILL.md");
 		// existsSync follows symlinked skill directories, which isDirectory() would miss.
-		if (existsSync(skillFile) && !into.has(`${scope}:${entry}`)) {
-			into.set(`${scope}:${entry}`, { name: entry, path: skillFile, scope });
+		if (!existsSync(skillFile)) continue;
+		let name = entry;
+		try {
+			const declared = parseFrontmatterLoosely(readFileSync(skillFile, "utf-8")).frontmatter.name;
+			if (typeof declared === "string" && declared) name = declared;
+		} catch {
+			continue;
 		}
+		const real = tryRealpath(skillFile) ?? skillFile;
+		if (into.has(name) || seenFiles.has(real)) continue;
+		seenFiles.add(real);
+		into.set(name, { name, path: skillFile, scope });
 	}
 }
 
@@ -65,12 +100,10 @@ export function scanSkills(
 	bundledSkillsDir?: string,
 ): ScannedSkill[] {
 	const skills = new Map<string, ScannedSkill>();
-	scanDir(join(claudeUserDir(home), "skills"), "user", skills);
-	scanDir(join(home, ".agents", "skills"), "user", skills);
-	scanDir(join(cwd, ".claude", "skills"), "project", skills);
-	scanDir(join(cwd, ".agents", "skills"), "project", skills);
-	scanDir(join(agentDir, "skills"), "user", skills);
-	if (bundledSkillsDir) scanDir(bundledSkillsDir, scopeForPath(bundledSkillsDir, home, agentDir), skills);
+	const seenFiles = new Set<string>();
+	scanDir(join(agentDir, "skills"), "user", skills, seenFiles);
+	for (const { dir, scope } of skillSourceDirs(cwd, home)) scanDir(dir, scope, skills, seenFiles);
+	if (bundledSkillsDir) scanDir(bundledSkillsDir, scopeForPath(bundledSkillsDir, home, agentDir), skills, seenFiles);
 	for (const skill of pluginSkills) {
 		skills.set(`plugin:${skill.name}`, { name: skill.name, path: skill.path, scope: "plugin" });
 	}
@@ -80,14 +113,20 @@ export function scanSkills(
 /**
  * Names of the `.claude/commands` prompt templates (`<name>.md`) pi will expose
  * as `/<name>` — the same dirs claude-compat feeds pi (`~/.claude/commands`,
- * `<cwd>/.claude/commands`) plus pi's own `<agentDir>/prompts`. pi resolves
+ * `<cwd>/.claude/commands`, or their `.onecode` twins in independent mode)
+ * plus pi's own `<agentDir>/prompts`. pi resolves
  * templates per turn, after `session_start`, so a bare skill command registered
  * then would silently shadow a same-named template for the whole session;
  * this pre-scan lets the registration skip those names.
  */
 export function promptTemplateNames(cwd: string, home: string, agentDir: string): string[] {
-	const names = new Set<string>();
-	for (const dir of [join(claudeUserDir(home), "commands"), join(cwd, ".claude", "commands"), join(agentDir, "prompts")]) {
+	return [...new Set(promptTemplateFiles(cwd, home, agentDir).map((file) => file.name))];
+}
+
+/** Every prompt-template file pi will resolve, with the command name each gives. */
+export function promptTemplateFiles(cwd: string, home: string, agentDir: string): { name: string; path: string }[] {
+	const files: { name: string; path: string }[] = [];
+	for (const dir of [...commandDirs(cwd, home), join(agentDir, "prompts")]) {
 		if (!existsSync(dir)) continue;
 		let entries: string[];
 		try {
@@ -95,9 +134,9 @@ export function promptTemplateNames(cwd: string, home: string, agentDir: string)
 		} catch {
 			continue;
 		}
-		for (const entry of entries) if (entry.endsWith(".md")) names.add(entry.slice(0, -3));
+		for (const entry of entries) if (entry.endsWith(".md")) files.push({ name: entry.slice(0, -3), path: join(dir, entry) });
 	}
-	return [...names];
+	return files;
 }
 
 /** Rough token estimate from the SKILL.md byte size (~4 bytes/token). */

package/extensions/lib/spill-file.ts

@@ -0,0 +1,140 @@
+/**
+ * Keep pi's foreground shell spill file readable.
+ *
+ * When a foreground `bash` or `powershell` run prints more than pi keeps, pi
+ * writes the whole output to `<os.tmpdir()>/pi-<shell>-<16 hex>.log` and ends
+ * the text with `[… Full output: <path>]`, on success and on a failure: a
+ * non-zero exit is an error result from pi 0.99 on and a thrown error before
+ * it, and a timeout or an abort is always thrown. `os.tmpdir()` is outside
+ * every root the permission gate treats as readable, so the "full output is
+ * one read away" promise held only where outside reads skip the gate. So the
+ * file is moved into the session's persisted-results dir (a readable root)
+ * and the path in the text is rewritten to match.
+ *
+ * Only a file pi produced is moved: the path must sit directly in the temp
+ * dir and carry pi's name shape, so a command that prints a look-alike line
+ * cannot make the harness move some other file.
+ *
+ * The output is also cut Claude Code's way instead of pi's. pi
+ * keeps the last 2,000 lines or 50 KB and drops the head, so a batched
+ * command lost its first commands' output. Claude Code keeps the head: the
+ * whole output up to its inline cap, past it the persisted block naming the
+ * file, with the first 2 KB as the preview. pi's spill file holds the whole
+ * output, so the block names it and nothing is copied.
+ */
+
+import { copyFileSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { persistedFilePreview, persistIfLarge } from "./persisted-output.ts";
+
+const MARKER = "Full output: ";
+const PI_SPILL_NAME = /^pi-[a-z]+-[0-9a-f]{16}\.log$/;
+/** The note pi ends a cut output with: `\n\n[Showing lines …` or `\n\n[Showing last …`. */
+const PI_NOTE = "\n\n[Showing ";
+/** pi's status after the output of a run that did not exit 0. */
+const PI_STATUS = /(?:^|\n\n)Command (?:exited with code -?\d+|timed out after \S+ seconds|aborted|terminated without an exit code)$/;
+
+/** How a shell's output is cut: whole up to `inlineMax` bytes, past it persisted as `<id>.txt` when pi did not spill it. */
+export interface OutputBound {
+	inlineMax: number;
+	id: string;
+}
+
+/** The spill path pi named at the end of `text`, when it is one pi produced in `tmp`. Pure. */
+export function piSpillPath(text: string, tmp: string = tmpdir()): string | undefined {
+	const at = text.lastIndexOf(MARKER);
+	if (at === -1) return undefined;
+	const close = text.indexOf("]", at + MARKER.length);
+	if (close === -1) return undefined;
+	const path = text.slice(at + MARKER.length, close);
+	if (!PI_SPILL_NAME.test(basename(path))) return undefined;
+	if (resolve(dirname(path)) !== resolve(tmp)) return undefined;
+	return path;
+}
+
+/** Move `from` into `dir`, keeping its name; the new path, or undefined when it could not move. */
+function moveInto(from: string, dir: string): string | undefined {
+	const to = join(dir, basename(from));
+	try {
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+		try {
+			renameSync(from, to);
+		} catch {
+			// A different filesystem: copy, then drop the original.
+			copyFileSync(from, to);
+			unlinkSync(from);
+		}
+		return to;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * `text` with its spill file moved and pi's tail cut replaced by Claude
+ * Code's head-first one. A spill file that cannot be moved keeps pi's text;
+ * one that cannot be read, or a text not in pi's shape, keeps pi's text with
+ * only the path rewritten.
+ */
+export function boundSpillIn(text: string, resultsDir: string, bound: OutputBound, failed = true, tmp: string = tmpdir()): string {
+	// pi appends a status only to a run that did not exit 0; a successful
+	// command's own last line can look like one.
+	const status = failed ? PI_STATUS.exec(text) : null;
+	const end = status ? status.index : text.length;
+	const output = text.slice(0, end);
+	const from = piSpillPath(output, tmp);
+	if (!from) return persistIfLarge(output, { dir: resultsDir, id: bound.id, maxBytes: bound.inlineMax }) + text.slice(end);
+	const to = moveInto(from, resultsDir);
+	if (!to) return text;
+	// pi's note ends the output; anything else keeps pi's text.
+	const whole = output.includes(PI_NOTE) && output.endsWith(`${from}]`) ? wholeOutput(to, bound.inlineMax) : undefined;
+	return whole === undefined ? text.split(from).join(to) : whole + text.slice(end);
+}
+
+/** The spill file inline while it fits `inlineMax`, past it the persisted block; undefined when unreadable. */
+function wholeOutput(path: string, inlineMax: number): string | undefined {
+	try {
+		return statSync(path).size <= inlineMax ? readFileSync(path, "utf8") : persistedFilePreview(path);
+	} catch {
+		return undefined;
+	}
+}
+
+type TextResult = { content: Array<{ type: string; text?: string }>; details?: unknown };
+
+/**
+ * Run a foreground shell execute and keep its spill file readable: on a
+ * returned result the text and `details.fullOutputPath` are rewritten, and a
+ * thrown error is rethrown with its message rewritten, the output cut
+ * Claude Code's way (`bound`).
+ */
+export async function keepSpillReadable<R extends TextResult>(run: () => Promise<R>, resultsDir: string, bound: OutputBound): Promise<R> {
+	const rewrite = (text: string, failed: boolean) => boundSpillIn(text, resultsDir, bound, failed);
+	let result: R;
+	try {
+		result = await run();
+	} catch (error) {
+		if (error instanceof Error) {
+			const message = rewrite(error.message, true);
+			if (message !== error.message) {
+				const moved = new Error(message);
+				moved.stack = error.stack;
+				throw moved;
+			}
+		}
+		throw error;
+	}
+	const details = result.details as { fullOutputPath?: unknown } | undefined;
+	const text = result.content.find((block) => block.type === "text" && typeof block.text === "string");
+	if (!text?.text) return result;
+	const rewritten = rewrite(text.text, (result as { isError?: boolean }).isError === true);
+	if (rewritten === text.text) return result;
+	const from = piSpillPath(text.text);
+	const to = from ? join(resultsDir, basename(from)) : undefined;
+	return {
+		...result,
+		content: result.content.map((block) => (block === text ? { ...block, text: rewritten } : block)),
+		details: details && typeof details === "object" && to ? { ...details, fullOutputPath: to } : result.details,
+	};
+}