one-code-extension 0.1.0

package/extensions/permissions/settings.ts

@@ -0,0 +1,98 @@
+/**
+ * Claude Code settings.json permissions loading/merging/persistence (pure fs).
+ *
+ * Sources, lowest to highest precedence:
+ *   ~/.claude/settings.json          (user)
+ *   <cwd>/.claude/settings.json      (project, checked in)
+ *   <cwd>/.claude/settings.local.json (project, personal)
+ *
+ * allow/deny/ask arrays concatenate across sources; defaultMode from the most
+ * specific source wins. Unknown keys in the files are preserved on write.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { PermissionMode } from "./matcher.ts";
+
+export interface PermissionSettings {
+	allow: string[];
+	deny: string[];
+	ask: string[];
+	defaultMode?: PermissionMode;
+}
+
+interface ClaudeSettingsFile {
+	permissions?: {
+		allow?: string[];
+		deny?: string[];
+		ask?: string[];
+		defaultMode?: string;
+	};
+	[key: string]: unknown;
+}
+
+const MODES: PermissionMode[] = ["default", "acceptEdits", "plan", "bypassPermissions", "dontAsk", "auto"];
+
+/** Display-name aliases Claude Code accepts wherever a mode is named. */
+const MODE_ALIASES: Record<string, PermissionMode> = { manual: "default" };
+
+export function isPermissionMode(value: unknown): value is PermissionMode {
+	return typeof value === "string" && (MODES as string[]).includes(value);
+}
+
+/** A mode value from user input (flag, settings, env), aliases included. */
+export function normalizePermissionMode(value: unknown): PermissionMode | undefined {
+	if (isPermissionMode(value)) return value;
+	return typeof value === "string" ? MODE_ALIASES[value] : undefined;
+}
+
+function readSettingsFile(path: string): ClaudeSettingsFile | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as ClaudeSettingsFile;
+	} catch {
+		return undefined;
+	}
+}
+
+export function settingsPaths(cwd: string, home: string): { user: string; project: string; local: string } {
+	return {
+		user: join(home, ".claude", "settings.json"),
+		project: join(cwd, ".claude", "settings.json"),
+		local: join(cwd, ".claude", "settings.local.json"),
+	};
+}
+
+export function loadPermissionSettings(cwd: string, home: string): PermissionSettings {
+	const paths = settingsPaths(cwd, home);
+	const merged: PermissionSettings = { allow: [], deny: [], ask: [] };
+
+	for (const path of [paths.user, paths.project, paths.local]) {
+		const file = readSettingsFile(path);
+		const perms = file?.permissions;
+		if (!perms) continue;
+		if (Array.isArray(perms.allow)) merged.allow.push(...perms.allow.filter((r) => typeof r === "string"));
+		if (Array.isArray(perms.deny)) merged.deny.push(...perms.deny.filter((r) => typeof r === "string"));
+		if (Array.isArray(perms.ask)) merged.ask.push(...perms.ask.filter((r) => typeof r === "string"));
+		const defaultMode = normalizePermissionMode(perms.defaultMode);
+		// `auto` is honoured from user settings only. Both project files live in the
+		// repository, so accepting it there would let a checked-in file put the
+		// session into auto mode — a repo granting itself the looser mode whose
+		// classifier is what contains it. Claude Code makes the same exclusion.
+		if (defaultMode && !(defaultMode === "auto" && path !== paths.user)) {
+			merged.defaultMode = defaultMode;
+		}
+	}
+
+	return merged;
+}
+
+/** Append an allow rule to a settings file, creating it if needed. */
+export function persistAllowRule(rule: string, filePath: string): void {
+	const file = readSettingsFile(filePath) ?? {};
+	const permissions = (file.permissions ??= {});
+	const allow = (permissions.allow ??= []);
+	if (!allow.includes(rule)) allow.push(rule);
+	mkdirSync(dirname(filePath), { recursive: true });
+	writeFileSync(filePath, `${JSON.stringify(file, null, 2)}\n`);
+}

package/extensions/plan-mode/index.ts

@@ -0,0 +1,209 @@
+/**
+ * plan-mode extension — Claude Code's EnterPlanMode / ExitPlanMode tools,
+ * file-based: the plan lives at ~/.one-code/plans/<slug>.md, the one path plan
+ * mode may write. The path is announced to the model in an every-turn reminder
+ * and to the permissions extension over the event bus, and exit_plan_mode
+ * reads the file rather than taking the plan as a parameter.
+ *
+ * Mode state is owned by the permissions extension; this extension requests
+ * changes over MODE_CHANNEL and reacts to transitions it observes on
+ * PERMISSION_STATUS_CHANNEL (which fires on every setMode). Plan-file
+ * allocation happens lazily in before_agent_start — the one hook that covers
+ * all three ways into plan mode (the tool, ctrl+q, defaultMode: "plan") and
+ * runs after every extension's session_start, so restoring a previous path
+ * from the session branch can never race a fresh allocation.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { oneCodeStateDir } from "../lib/paths.ts";
+import { REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { ccToolRenderers, safeThemePaint } from "../lib/tui-render.ts";
+import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
+import { buildPlanModeReminder } from "./reminder.ts";
+import { randomSlug } from "./slug.ts";
+import { clampOffset, decodeViewerKey, type PlanChoice, renderPlanViewer, wrapPlanText } from "./viewer.ts";
+
+export const MODE_CHANNEL = "one-code:set-permission-mode";
+/** Announces plan mode's one writable file; the permissions matcher consumes it. */
+export const PLAN_FILE_CHANNEL = "one-code:plan-file-path";
+/** Session entry type persisting the allocated path across resume/branch. */
+const PLAN_FILE_ENTRY = "plan-mode-file";
+
+const PLANS_DIR = () => join(oneCodeStateDir(), "plans");
+
+export default function planModeExtension(pi: ExtensionAPI) {
+	let currentMode = "default";
+	let planFilePath: string | undefined;
+
+	/** Restore the branch's plan file, else allocate a fresh slug. */
+	const ensurePlanFile = (ctx: ExtensionContext): string => {
+		if (planFilePath) return planFilePath;
+
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type !== "custom" || entry.customType !== PLAN_FILE_ENTRY) continue;
+			const path = (entry.data as { path?: unknown } | undefined)?.path;
+			if (typeof path === "string") planFilePath = path;
+		}
+		if (planFilePath) return planFilePath;
+
+		let path = join(PLANS_DIR(), `${randomSlug()}.md`);
+		for (let attempt = 0; attempt < 5 && existsSync(path); attempt++) {
+			path = join(PLANS_DIR(), `${randomSlug()}.md`);
+		}
+		planFilePath = path;
+		pi.appendEntry(PLAN_FILE_ENTRY, { path });
+		return path;
+	};
+
+	/** Re-announce path + reminder; every-turn re-emits replace by key. */
+	const refresh = (ctx: ExtensionContext) => {
+		const path = ensurePlanFile(ctx);
+		pi.events.emit(PLAN_FILE_CHANNEL, { path });
+		pi.events.emit(REMINDER_CHANNEL, {
+			text: buildPlanModeReminder({ filePath: path, fileExists: existsSync(path) }),
+			scope: "every-turn",
+			key: "permission-mode",
+		});
+	};
+
+	pi.events.on(PERMISSION_STATUS_CHANNEL, (data) => {
+		const status = data as PermissionStatus;
+		if (typeof status?.mode === "string") currentMode = status.mode;
+	});
+
+	pi.on("before_agent_start", (_event, ctx) => {
+		if (currentMode === "plan") refresh(ctx);
+	});
+
+	pi.registerTool({
+		name: "enter_plan_mode",
+		label: "Enter plan mode",
+		...ccToolRenderers("Enter plan mode"),
+		description:
+			"Enter plan mode for tasks that need investigation and design before changing anything. In plan mode only read-only tools are available, plus one writable file: the plan file whose path you are told, where you build the plan incrementally. Use for non-trivial multi-file work; skip it for simple direct changes.",
+		promptSnippet: "Switch to read-only planning before non-trivial changes",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			pi.events.emit(MODE_CHANNEL, { mode: "plan" });
+			// setMode fires synchronously over the status channel, so currentMode
+			// is already "plan"; announce the file in the tool result too so the
+			// model can start writing this same turn.
+			const path = ensurePlanFile(ctx);
+			refresh(ctx);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Entered plan mode. Only read-only tools are available, except for your plan file at ${path} — build your plan there incrementally, then call exit_plan_mode to request approval.`,
+					},
+				],
+				details: { planFilePath: path },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "exit_plan_mode",
+		label: "Exit plan mode",
+		...ccToolRenderers("Exit plan mode"),
+		description:
+			"Signal that planning is complete and ask the user to approve the plan. Takes no parameters: the plan is read from the plan file named in the plan-mode reminder, which you must have written before calling this. The user reviews that file's contents.",
+		promptSnippet: "Present your plan file for user approval",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			// Guard the out-of-sequence call: without this, a cold exit_plan_mode
+			// (never entered plan mode) allocates a fresh empty plan file and blames
+			// "the plan file is empty" — a plausible but wrong cause a weak model
+			// then chases. The real fix is to enter plan mode first.
+			if (currentMode !== "plan") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "Not in plan mode, so there is no plan to approve. Call enter_plan_mode first, build the plan in the file it names, then call exit_plan_mode.",
+						},
+					],
+					details: {},
+					isError: true,
+				};
+			}
+			const path = ensurePlanFile(ctx);
+			const plan = existsSync(path) ? readFileSync(path, "utf8") : "";
+			if (!plan.trim()) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No plan to approve: ${path} is missing or empty. Write your plan there first, then call exit_plan_mode again.`,
+						},
+					],
+					details: { planFilePath: path },
+					isError: true,
+				};
+			}
+
+			if (!ctx.hasUI) {
+				pi.events.emit(MODE_CHANNEL, { mode: "default" });
+				return {
+					content: [
+						{ type: "text", text: "Non-interactive session: plan recorded and plan mode exited. Proceed." },
+					],
+					details: { plan, approved: true },
+				};
+			}
+
+			const choice = await ctx.ui.custom<PlanChoice | null>((tui, theme, _keybindings, done) => {
+				const paint = safeThemePaint(theme);
+				const maxVisible = 12;
+				let offset = 0;
+				let selected: PlanChoice = 0;
+				let lineCount = 0;
+				return {
+					render: (width: number) => {
+						const lines = wrapPlanText(plan, Math.max(10, width - 1));
+						lineCount = lines.length;
+						offset = clampOffset(offset, lineCount, maxVisible);
+						return renderPlanViewer({ lines, offset, choice: selected, maxVisible }, paint, width);
+					},
+					handleInput: (data: string) => {
+						const key = decodeViewerKey(data, maxVisible);
+						if (!key) return;
+						if (key.kind === "cancel") return done(null);
+						if (key.kind === "confirm") return done(selected);
+						if (key.kind === "pick") return done(key.index);
+						if (key.kind === "scroll") offset = clampOffset(offset + key.delta, lineCount, maxVisible);
+						else if (key.kind === "choice") selected = (((selected + key.delta) % 3) + 3) % 3 as PlanChoice;
+						tui.requestRender();
+					},
+					invalidate: () => {},
+				};
+			});
+
+			if (choice === 0 || choice === 1) {
+				pi.events.emit(MODE_CHANNEL, { mode: choice === 1 ? "acceptEdits" : "default" });
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Plan approved by the user. You may now implement it. The approved plan stays at ${path} for reference.`,
+						},
+					],
+					details: { plan, approved: true },
+				};
+			}
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: "The user did not approve the plan. Stay in plan mode; refine the plan file based on their feedback.",
+					},
+				],
+				details: { plan, approved: false },
+			};
+		},
+	});
+}

package/extensions/plan-mode/reminder.ts

@@ -0,0 +1,33 @@
+/**
+ * Plan-mode reminder text (pure). Byte-identical for a given state so the
+ * every-turn re-emit replaces the queue entry with the same string except when
+ * the state genuinely changed (file created, different path).
+ *
+ * Mirrors Claude Code's plan-mode system message: the plan lives in a file the
+ * model builds incrementally — the one writable path in plan mode — and
+ * exit_plan_mode reads that file rather than taking the plan as a parameter.
+ */
+
+export interface PlanReminderState {
+	filePath: string;
+	fileExists: boolean;
+}
+
+export function buildPlanModeReminder({ filePath, fileExists }: PlanReminderState): string {
+	const fileLine = fileExists
+		? `Continue building your plan at ${filePath} with the write/edit tools — edit it incrementally rather than rewriting it from scratch.`
+		: `No plan file exists yet — create it at ${filePath} with the write tool. Build the plan there incrementally as you investigate; do not present the plan as chat text.`;
+
+	return [
+		`Plan mode is active. You may only use read-only tools; edit and write are blocked everywhere except one file. ${fileLine}`,
+		"",
+		"Workflow:",
+		'1. Explore: delegate broad reconnaissance to `subagent` with `agent: "explore"` (up to 3 in parallel) rather than reading everything yourself.',
+		'2. Design: delegate the implementation strategy to `subagent` with `agent: "plan"` once exploration has mapped the ground.',
+		"3. Review the critical files yourself, and call `ask_user_question` for any decision you cannot make on the user's behalf.",
+		`4. Write the final plan to ${filePath}: a Context section explaining why, your recommended approach (not several options), the critical files named, existing utilities to reuse, and a verification section.`,
+		"5. Call `exit_plan_mode` to ask the user to approve the plan. It reads the plan file directly — you do not pass the plan as a parameter.",
+		"",
+		"End every plan-mode turn with either `ask_user_question` or `exit_plan_mode`. Never ask for plan approval in chat text.",
+	].join("\n");
+}

package/extensions/plan-mode/slug.ts

@@ -0,0 +1,28 @@
+/**
+ * Three-word plan-file slugs (pure), Claude Code style: `now-snoopy-tome`.
+ * Collision handling lives in index.ts — it needs the filesystem, this doesn't.
+ */
+
+const WORDS = [
+	"amber", "arrow", "aspen", "atlas", "badge", "basil", "beacon", "birch",
+	"bloom", "breeze", "brisk", "cedar", "chalk", "cliff", "clover", "coral",
+	"crane", "crisp", "delta", "drift", "dune", "ember", "fable", "fern",
+	"flint", "gale", "glade", "grove", "harbor", "hazel", "heron", "ivory",
+	"jade", "juniper", "keel", "kite", "lark", "ledge", "linen", "lunar",
+	"maple", "marsh", "meadow", "mesa", "mist", "moss", "north", "oak",
+	"olive", "onyx", "opal", "orchard", "otter", "pebble", "pine", "plume",
+	"prairie", "quill", "reef", "ridge", "river", "robin", "rowan", "sable",
+	"sage", "shale", "shore", "slate", "snug", "spark", "spruce", "starling",
+	"stone", "summit", "swift", "thorn", "tide", "timber", "tome", "trail",
+	"tundra", "umber", "vale", "vesper", "violet", "wander", "willow", "wren",
+];
+
+/** Three distinct words joined by `-`. Inject `rng` for deterministic tests. */
+export function randomSlug(rng: () => number = Math.random): string {
+	const picked: string[] = [];
+	while (picked.length < 3) {
+		const word = WORDS[Math.floor(rng() * WORDS.length) % WORDS.length];
+		if (!picked.includes(word)) picked.push(word);
+	}
+	return picked.join("-");
+}

package/extensions/plan-mode/viewer.ts

@@ -0,0 +1,124 @@
+/**
+ * Plan-approval viewer (pure): key decoding, wrapping, and rendering for the
+ * scrollable dialog exit_plan_mode shows. The thin ctx.ui.custom component in
+ * index.ts owns nothing but mutable state and repaint calls — same split as
+ * auto-mode's model picker.
+ *
+ * Every rendered line must stay within the width given: pi-tui crashes the
+ * whole app on an overwide line. Content is wrapped (not truncated — a plan
+ * must stay readable in full), and chrome lines are cut plain-text *before*
+ * painting so ANSI escapes never confuse the width accounting.
+ */
+
+export const PLAN_CHOICES = ["Approve — manual approvals", "Approve — auto-accept edits", "Keep planning"] as const;
+
+/** What the dialog resolves to; index into PLAN_CHOICES, or null for cancel. */
+export type PlanChoice = 0 | 1 | 2;
+
+export type ViewerKey =
+	| { kind: "scroll"; delta: number }
+	| { kind: "choice"; delta: number }
+	| { kind: "pick"; index: PlanChoice }
+	| { kind: "confirm" }
+	| { kind: "cancel" };
+
+/** Decode a raw terminal chunk; `page` is the scroll step for PgUp/PgDn. */
+export function decodeViewerKey(data: string, page: number): ViewerKey | undefined {
+	switch (data) {
+		case "\x1b[A":
+		case "\x1bOA":
+			return { kind: "scroll", delta: -1 };
+		case "\x1b[B":
+		case "\x1bOB":
+			return { kind: "scroll", delta: 1 };
+		case "\x1b[5~":
+			return { kind: "scroll", delta: -page };
+		case "\x1b[6~":
+			return { kind: "scroll", delta: page };
+		case "\x1b[D":
+		case "\x1bOD":
+			return { kind: "choice", delta: -1 };
+		case "\x1b[C":
+		case "\x1bOC":
+		case "\t":
+			return { kind: "choice", delta: 1 };
+		case "\r":
+		case "\n":
+			return { kind: "confirm" };
+		case "\x1b":
+		case "\x03": // ctrl+c — same intent as escape while the dialog is focused
+			return { kind: "cancel" };
+		case "1":
+		case "2":
+		case "3":
+			return { kind: "pick", index: (Number(data) - 1) as PlanChoice };
+		default:
+			return undefined;
+	}
+}
+
+/** Hard-wrap plain text to `width` columns, preserving blank lines. */
+export function wrapPlanText(text: string, width: number): string[] {
+	const columns = Math.max(1, width);
+	const out: string[] = [];
+	for (const raw of text.replace(/\r\n/g, "\n").split("\n")) {
+		const chars = [...raw];
+		if (chars.length === 0) {
+			out.push("");
+			continue;
+		}
+		for (let i = 0; i < chars.length; i += columns) {
+			out.push(chars.slice(i, i + columns).join(""));
+		}
+	}
+	return out;
+}
+
+export function clampOffset(offset: number, total: number, visible: number): number {
+	return Math.max(0, Math.min(offset, Math.max(0, total - visible)));
+}
+
+export type Paint = (color: string, text: string) => string;
+
+export interface PlanViewerView {
+	/** Pre-wrapped plain-text plan lines (wrapPlanText output for this width). */
+	lines: string[];
+	offset: number;
+	choice: PlanChoice;
+	maxVisible?: number;
+}
+
+export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: number): string[] {
+	const maxVisible = view.maxVisible ?? 12;
+	// Cut plain text before painting so escapes never enter the width math.
+	const cut = (line: string) => {
+		const chars = [...line];
+		return chars.length > width ? `${chars.slice(0, Math.max(0, width - 1)).join("")}…` : line;
+	};
+	const rule = paint("dim", "─".repeat(Math.max(0, Math.min(width, 72))));
+
+	const out: string[] = [];
+	out.push("");
+	out.push(paint("accent", cut("Approve this plan?")));
+	out.push(paint("dim", cut("↑/↓ scroll · ←/→ switch choice · 1-3 pick · enter confirm · esc keep planning")));
+	out.push(rule);
+
+	const offset = clampOffset(view.offset, view.lines.length, maxVisible);
+	for (const line of view.lines.slice(offset, offset + maxVisible)) {
+		out.push(cut(line));
+	}
+	if (view.lines.length > maxVisible) {
+		const last = Math.min(view.lines.length, offset + maxVisible);
+		out.push(paint("dim", cut(`lines ${offset + 1}–${last} of ${view.lines.length}`)));
+	}
+	out.push(rule);
+
+	for (const [index, label] of PLAN_CHOICES.entries()) {
+		const numbered = `${index + 1}. ${label}`;
+		out.push(
+			index === view.choice ? paint("accent", cut(`❯ ${numbered}`)) : cut(`  ${numbered}`),
+		);
+	}
+	out.push("");
+	return out;
+}

package/extensions/plugins/index.ts

@@ -0,0 +1,115 @@
+/**
+ * plugins extension — Claude Code plugin support.
+ *
+ * Reads `~/.claude/plugins/installed_plugins.json`, then publishes each
+ * plugin's resources so the other extensions can use them:
+ *
+ *   agents/      → the subagent tool, as `<plugin>:<agent>`
+ *   skills/      → the skill tool, as `<plugin>:<skill>`
+ *   commands/    → slash commands, as `/<plugin>:<command>`
+ *   .mcp.json    → the MCP client
+ *
+ * Everything is namespaced the way Claude Code namespaces it, so two plugins can
+ * both ship a `commit` command. This extension only owns the slash commands and
+ * the `/plugins` listing; the other consumers call `discoverPlugins()` for
+ * themselves, because module state is not shared between extension files.
+ */
+
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { discoverPlugins, type Plugin } from "../lib/plugins.ts";
+import { findShellPlaceholders, replaceShellPlaceholders, substituteArguments } from "./template.ts";
+
+const run = promisify(execFile);
+const SHELL_TIMEOUT_MS = 30_000;
+
+async function expandTemplate(body: string, args: string, cwd: string): Promise<string> {
+	const withArgs = substituteArguments(body, args);
+	const commands = [...new Set(findShellPlaceholders(withArgs))];
+	if (commands.length === 0) return withArgs;
+
+	const outputs = new Map<string, string>();
+	await Promise.all(
+		commands.map(async (command) => {
+			try {
+				const { stdout, stderr } = await run(command, {
+					cwd,
+					shell: true,
+					timeout: SHELL_TIMEOUT_MS,
+					maxBuffer: 2 * 1024 * 1024,
+				});
+				outputs.set(command, (stdout || stderr || "").trim());
+			} catch (error) {
+				const detail = error as { stdout?: string; stderr?: string; message?: string };
+				outputs.set(command, (detail.stdout || detail.stderr || detail.message || "command failed").trim());
+			}
+		}),
+	);
+	return replaceShellPlaceholders(withArgs, outputs);
+}
+
+export default function pluginsExtension(pi: ExtensionAPI) {
+	const claudeDir = join(os.homedir(), ".claude");
+	const discovered = discoverPlugins(claudeDir);
+
+	for (const command of discovered.commands) {
+		const plugin = discovered.plugins.find((p) => p.name === command.plugin);
+		if (plugin) registerPluginCommand(pi, plugin, command.name, command.path);
+	}
+
+	pi.registerCommand("plugins", {
+		description: "List installed Claude Code plugins and what they contribute",
+		handler: async (_args, ctx) => {
+			if (discovered.plugins.length === 0) {
+				ctx.ui.notify("No Claude Code plugins installed (~/.claude/plugins/installed_plugins.json).", "info");
+				return;
+			}
+			const lines = discovered.plugins.map((plugin) => {
+				const summary = discovered.byPlugin.get(plugin.name);
+				const parts: string[] = [];
+				if (summary?.agents) parts.push("agents");
+				if (summary?.skills) parts.push(`${summary.skills} skill${summary.skills === 1 ? "" : "s"}`);
+				if (summary?.commands) parts.push(`${summary.commands} command${summary.commands === 1 ? "" : "s"}`);
+				if (summary?.mcp) parts.push("mcp");
+				return `${plugin.name}${plugin.version && plugin.version !== "unknown" ? ` ${plugin.version}` : ""} — ${parts.join(", ") || "nothing usable"}`;
+			});
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}
+
+function registerPluginCommand(pi: ExtensionAPI, plugin: Plugin, name: string, path: string): void {
+	let description = `Command from the ${plugin.name} plugin`;
+	let argumentHint: string | undefined;
+	try {
+		const { frontmatter } = parseFrontmatter(readFileSync(path, "utf-8")) as {
+			frontmatter?: Record<string, unknown>;
+		};
+		if (typeof frontmatter?.description === "string") description = frontmatter.description;
+		if (typeof frontmatter?.["argument-hint"] === "string") argumentHint = frontmatter["argument-hint"];
+	} catch {
+		// Fall back to the generic description.
+	}
+
+	pi.registerCommand(name, {
+		description: argumentHint ? `${description} (${argumentHint})` : description,
+		handler: async (args, ctx) => {
+			let body: string;
+			try {
+				const parsed = parseFrontmatter(readFileSync(path, "utf-8")) as { body: string };
+				body = parsed.body;
+			} catch (error) {
+				ctx.ui.notify(`Could not read ${path}: ${(error as Error).message}`, "error");
+				return;
+			}
+			const expanded = await expandTemplate(body, args, ctx.cwd);
+			// Deliver as a user turn, which is how Claude Code runs a command template.
+			pi.sendUserMessage(expanded);
+		},
+	});
+}

package/extensions/plugins/template.ts

@@ -0,0 +1,42 @@
+/**
+ * Claude Code command-template expansion (pure apart from the shell hook).
+ *
+ * A command markdown file has frontmatter (`description`, `allowed-tools`,
+ * `argument-hint`) and a body that may contain:
+ *   $ARGUMENTS, $1, $2, $@   — the invocation's arguments
+ *   !`shell command`          — replaced with that command's output
+ *
+ * The `!` form is why plugin commands like `commit` work: the template gathers
+ * git status and diff before the model sees the prompt.
+ */
+
+export interface CommandTemplate {
+	description?: string;
+	argumentHint?: string;
+	allowedTools?: string;
+	body: string;
+}
+
+export function substituteArguments(body: string, args: string): string {
+	const parts = args.trim().length > 0 ? args.trim().split(/\s+/) : [];
+	return body
+		.replace(/\$ARGUMENTS\b/g, args.trim())
+		.replace(/\$@/g, args.trim())
+		.replace(/\$(\d+)/g, (_match, index) => parts[Number(index) - 1] ?? "");
+}
+
+/** Finds each !`command` occurrence so the caller can run them. */
+export function findShellPlaceholders(body: string): string[] {
+	const found: string[] = [];
+	const pattern = /!`([^`]+)`/g;
+	let match = pattern.exec(body);
+	while (match) {
+		found.push(match[1]);
+		match = pattern.exec(body);
+	}
+	return found;
+}
+
+export function replaceShellPlaceholders(body: string, outputs: Map<string, string>): string {
+	return body.replace(/!`([^`]+)`/g, (_match, command: string) => outputs.get(command) ?? "");
+}

package/extensions/search-tools/tools.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure tier → tool-surface policy: which of pi's inactive built-in search
+ * tools should be active for a given prompt tier.
+ */
+
+import type { PromptTier } from "../lib/model-tier.ts";
+
+/** pi built-ins that exist in the registry but are not active by default. */
+export const SEARCH_TOOLS = ["grep", "find", "ls"] as const;
+
+/**
+ * Returns the active-tool list adjusted for the tier: mid/low gain the search
+ * tools (deduped, appended in a stable order), frontier loses them (Claude
+ * Code's frontier surface has no dedicated search tools). Order of the
+ * existing names is preserved so the rebuilt system prompt stays byte-stable.
+ */
+export function withSearchTools(active: string[], tier: PromptTier): string[] {
+	if (tier === "frontier") {
+		const drop = new Set<string>(SEARCH_TOOLS);
+		return active.filter((name) => !drop.has(name));
+	}
+	const present = new Set(active);
+	return [...active, ...SEARCH_TOOLS.filter((name) => !present.has(name))];
+}