one-code-extension 0.4.1 → 0.6.0

package/extensions/plan-mode/texts.ts

@@ -0,0 +1,177 @@
+/**
+ * The plan-mode tools' model-facing texts (pure): Claude Code's EnterPlanMode
+ * and ExitPlanMode descriptions and results, with One Code's snake_case tool
+ * names. The plan stays file-based (decisions/modes.md, "Plan mode is
+ * file-based"); only the wording follows Claude Code.
+ */
+
+import type { DescriptionForm } from "../lib/tool-variants.ts";
+
+/**
+ * Claude Code's EnterPlanMode description, which prefers plan mode for any
+ * non-trivial implementation task. Frontier and workhorse models get it.
+ */
+export const ENTER_PLAN_MODE_DESCRIPTION = [
+	"Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.",
+	"",
+	"## When to Use This Tool",
+	"",
+	"**Prefer using enter_plan_mode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:",
+	"",
+	"1. **New Feature Implementation**: Adding meaningful new functionality",
+	"   - Example: \"Add a logout button\" - where should it go? What should happen on click?",
+	"   - Example: \"Add form validation\" - what rules? What error messages?",
+	"",
+	"2. **Multiple Valid Approaches**: The task can be solved in several different ways",
+	"   - Example: \"Add caching to the API\" - could use Redis, in-memory, file-based, etc.",
+	"   - Example: \"Improve performance\" - many optimization strategies possible",
+	"",
+	"3. **Code Modifications**: Changes that affect existing behavior or structure",
+	"   - Example: \"Update the login flow\" - what exactly should change?",
+	"   - Example: \"Refactor this component\" - what's the target architecture?",
+	"",
+	"4. **Architectural Decisions**: The task requires choosing between patterns or technologies",
+	"   - Example: \"Add real-time updates\" - WebSockets vs SSE vs polling",
+	"   - Example: \"Implement state management\" - Redux vs Context vs custom solution",
+	"",
+	"5. **Multi-File Changes**: The task will likely touch more than 2-3 files",
+	"   - Example: \"Refactor the authentication system\"",
+	"   - Example: \"Add a new API endpoint with tests\"",
+	"",
+	"6. **Unclear Requirements**: You need to explore before understanding the full scope",
+	"   - Example: \"Make the app faster\" - need to profile and identify bottlenecks",
+	"   - Example: \"Fix the bug in checkout\" - need to investigate root cause",
+	"",
+	"7. **User Preferences Matter**: The implementation could reasonably go multiple ways",
+	"   - If you would use ask_user_question to clarify the approach, use enter_plan_mode instead",
+	"   - Plan mode lets you explore first, then present options with context",
+	"",
+	"## When NOT to Use This Tool",
+	"",
+	"Only skip enter_plan_mode for simple tasks:",
+	"- Single-line or few-line fixes (typos, obvious bugs, small tweaks)",
+	"- Adding a single function with clear requirements",
+	"- Tasks where the user has given very specific, detailed instructions",
+	"- Pure research/exploration tasks (use the Agent tool instead)",
+	"",
+	"## What Happens in Plan Mode",
+	"",
+	"In plan mode, you'll:",
+	"1. Thoroughly explore the codebase using `find`, `grep`, and read",
+	"2. Understand existing patterns and architecture",
+	"3. Design an implementation approach",
+	"4. Present your plan to the user for approval",
+	"5. Use ask_user_question if you need to clarify approaches",
+	"6. Exit plan mode with exit_plan_mode when ready to implement",
+	"",
+	"## Examples",
+	"",
+	"### GOOD - Use enter_plan_mode:",
+	"User: \"Add user authentication to the app\"",
+	"- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)",
+	"",
+	"User: \"Optimize the database queries\"",
+	"- Multiple approaches possible, need to profile first, significant impact",
+	"",
+	"User: \"Implement dark mode\"",
+	"- Architectural decision on theme system, affects many components",
+	"",
+	"User: \"Add a delete button to the user profile\"",
+	"- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates",
+	"",
+	"User: \"Update the error handling in the API\"",
+	"- Affects multiple files, user should approve the approach",
+	"",
+	"### BAD - Don't use enter_plan_mode:",
+	"User: \"Fix the typo in the README\"",
+	"- Straightforward, no planning needed",
+	"",
+	"User: \"Add a console.log to debug this function\"",
+	"- Simple, obvious implementation",
+	"",
+	"User: \"What files handle routing?\"",
+	"- Research task, not implementation planning",
+	"",
+	"## Important Notes",
+	"",
+	"- This tool REQUIRES user approval - they must consent to entering plan mode",
+	"- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work",
+	"- Users appreciate being consulted before significant changes are made to their codebase",
+	"",
+].join("\n");
+
+/**
+ * One Code's own description for the cheap and tiny tiers. Weak models read a
+ * "prefer plan mode" description as standing policy and planned trivial tasks
+ * (decisions/tools.md, "Weak-model steering"), so this one says most tasks do
+ * not need it.
+ */
+export const ENTER_PLAN_MODE_DESCRIPTION_WEAK =
+	"Enter plan mode: read-only investigation to design an approach before changing anything. Most tasks do not need it.\n" +
+	"For a small or clearly-scoped change, act directly instead. Enter plan mode only for multi-file work whose design is genuinely unclear, or when the user asks for a plan. 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.";
+
+/** The enter_plan_mode description for a description form: Claude Code's short form, ours as the long one. */
+export function enterPlanModeDescription(form: DescriptionForm): string {
+	return form === "long" ? ENTER_PLAN_MODE_DESCRIPTION_WEAK : ENTER_PLAN_MODE_DESCRIPTION;
+}
+
+/** Claude Code's ExitPlanMode description. */
+export const EXIT_PLAN_MODE_DESCRIPTION = [
+	"Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.",
+	"",
+	"## How This Tool Works",
+	"- You should have already written your plan to the plan file specified in the plan mode system message",
+	"- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote",
+	"- This tool simply signals that you're done planning and ready for the user to review and approve",
+	"- The user will see the contents of your plan file when they review it",
+	"",
+	"## When to Use This Tool",
+	"IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.",
+	"",
+	"## Before Using This Tool",
+	"Ensure your plan is complete and unambiguous:",
+	"- If you have unresolved questions about requirements or approach, use ask_user_question first (in earlier phases)",
+	"- Once your plan is finalized, use THIS tool to request approval",
+	"",
+	"**Important:** Do NOT use ask_user_question to ask \"Is this plan okay?\" or \"Should I proceed?\" - that's exactly what THIS tool does. exit_plan_mode inherently requests user approval of your plan.",
+	"",
+	"## Examples",
+	"",
+	"1. Initial task: \"Search for and understand the implementation of vim mode in the codebase\" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.",
+	"2. Initial task: \"Help me implement yank mode for vim\" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.",
+	"3. Initial task: \"Add a new feature to handle user authentication\" - If unsure about auth method (OAuth, JWT, etc.), use ask_user_question first, then use exit plan mode tool after clarifying the approach.",
+	"",
+].join("\n");
+
+/** Claude Code's EnterPlanMode result. */
+const ENTERED_PLAN_MODE = [
+	"Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.",
+	"",
+	"In plan mode, you should:",
+	"1. Thoroughly explore the codebase to understand existing patterns",
+	"2. Identify similar features and architectural approaches",
+	"3. Consider multiple approaches and their trade-offs",
+	"4. Use ask_user_question if you need to clarify the approach",
+	"5. Design a concrete implementation strategy",
+	"6. When ready, use exit_plan_mode to present your plan for approval",
+	"",
+	"Remember: DO NOT write or edit any files yet. This is a read-only exploration and planning phase.",
+].join("\n");
+
+/**
+ * enter_plan_mode's result: Claude Code's text, then the plan file's path so
+ * the model can start writing the plan in the same turn.
+ */
+export function enteredPlanModeText(planFilePath: string): string {
+	return `${ENTERED_PLAN_MODE}\n\nYour plan file is ${planFilePath}, the one file you may write: build your plan there.`;
+}
+
+/** exit_plan_mode's result when the user approves: Claude Code's text, with the plan file's contents. */
+export function approvedPlanText(planFilePath: string, plan: string): string {
+	return `User has approved your plan. You can now start coding. Start with updating your todo list if applicable\n\nYour plan has been saved to: ${planFilePath}\nYou can refer back to it if needed during implementation.\n\n## Approved Plan:\n${plan}`;
+}
+
+/** Claude Code's reminder after the approval: plan mode is over and the plan file stays readable. */
+export function exitedPlanModeText(planFilePath: string): string {
+	return `## Exited Plan Mode\n\nYou have exited plan mode. You can now make edits, run tools, and take actions. The plan file is located at ${planFilePath} if you need to reference it.`;
+}

package/extensions/plan-mode/viewer.ts

@@ -6,18 +6,54 @@
  *
  * 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.
+ * must stay readable in full) and then cut ANSI-aware as a guard, and chrome
+ * lines are cut plain-text *before* painting so ANSI escapes never confuse
+ * the width accounting.
  */
 
-import { cutPlainText } from "../lib/tui-render.ts";
+import { cutPlainText, hintLines, truncateLine, wrapProse } from "../lib/tui-render.ts";
+import { keyId } from "../lib/key-input.ts";
 
-/** Hard-wrap plain text to `width` columns, preserving blank lines. */
-export { wrapPlainText as wrapPlanText } from "../lib/tui-render.ts";
+/** Renders Markdown to painted lines at a width (pi-tui's Markdown, which the transcript uses). */
+export type PlanMarkdown = (text: string, width: number) => string[];
+
+/**
+ * The plan's lines at `width`: Markdown rendered the way the transcript renders
+ * assistant text when a renderer is available, else plain text wrapped at word
+ * boundaries. A renderer that throws falls back to the plain wrap, so a
+ * Markdown failure never costs the user the plan.
+ */
+export function planLines(plan: string, width: number, markdown?: PlanMarkdown): string[] {
+	if (markdown) {
+		try {
+			return markdown(plan, width);
+		} catch {
+			// fall through to the plain wrap
+		}
+	}
+	return wrapProse(plan, width);
+}
 
 /** What the dialog resolves to; index into the choices list, or null for cancel. */
 export type PlanChoice = number;
 
+/**
+ * The approval through a plain select, for RPC: its `custom()` resolves
+ * undefined (findings §8), which read as "dismissed" and rejected every plan.
+ * The plan rides in the title; a reply that is no choice is a dismissal.
+ */
+export async function selectPlanChoice(
+	ui: { select(title: string, options: string[], opts?: { signal?: AbortSignal }): Promise<string | undefined> },
+	plan: string,
+	path: string,
+	choices: string[],
+	signal?: AbortSignal,
+): Promise<PlanChoice | null> {
+	const label = await ui.select(`Plan (${path}):\n\n${plan}\n\nApprove the plan?`, choices, { signal });
+	const index = signal?.aborted || label === undefined ? -1 : choices.indexOf(label);
+	return index >= 0 ? index : null;
+}
+
 export type ViewerKey =
 	| { kind: "scroll"; delta: number }
 	| { kind: "choice"; delta: number }
@@ -32,33 +68,29 @@ export type ViewerKey =
  * classifier model is reachable).
  */
 export function decodeViewerKey(data: string, page: number): ViewerKey | undefined {
-	switch (data) {
-		case "\x1b[A":
-		case "\x1bOA":
+	const id = keyId(data);
+	switch (id) {
+		case "up":
 			return { kind: "scroll", delta: -1 };
-		case "\x1b[B":
-		case "\x1bOB":
+		case "down":
 			return { kind: "scroll", delta: 1 };
-		case "\x1b[5~":
+		case "pageUp":
 			return { kind: "scroll", delta: -page };
-		case "\x1b[6~":
+		case "pageDown":
 			return { kind: "scroll", delta: page };
-		case "\x1b[D":
-		case "\x1bOD":
+		case "left":
 			return { kind: "choice", delta: -1 };
-		case "\x1b[C":
-		case "\x1bOC":
-		case "\t":
+		case "right":
+		case "tab":
 			return { kind: "choice", delta: 1 };
-		case "\r":
-		case "\n":
+		case "enter":
 			return { kind: "confirm" };
-		case "\x1b":
-		case "\x03": // ctrl+c — same intent as escape while the dialog is focused
+		case "escape":
+		case "ctrl+c": // same intent as escape while the dialog is focused
 			return { kind: "cancel" };
 		default:
-			if (data.length === 1 && data >= "1" && data <= "9") {
-				return { kind: "pick", index: Number(data) - 1 };
+			if (id && id.length === 1 && id >= "1" && id <= "9") {
+				return { kind: "pick", index: Number(id) - 1 };
 			}
 			return undefined;
 	}
@@ -90,7 +122,7 @@ export function initialPlanChoice(options: readonly { mode?: string; restore?: b
 export type Paint = (color: string, text: string) => string;
 
 export interface PlanViewerView {
-	/** Pre-wrapped plain-text plan lines (wrapPlanText output for this width). */
+	/** The plan's lines for this width (planLines output: painted Markdown or plain wrapped text). */
 	lines: string[];
 	offset: number;
 	choice: PlanChoice;
@@ -103,18 +135,20 @@ export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: numb
 	const maxVisible = view.maxVisible ?? 12;
 	// Cut plain text before painting so escapes never enter the width math.
 	const cut = (line: string) => cutPlainText(line, width);
-	const rule = paint("dim", "─".repeat(Math.max(0, Math.min(width, 72))));
+	const rule = paint("dim", "─".repeat(Math.max(0, width)));
 	const pickHint = view.choices.length > 1 ? `1-${view.choices.length} pick · ` : "";
 
 	const out: string[] = [];
 	out.push("");
 	out.push(paint("accent", cut("Approve this plan?")));
-	out.push(paint("dim", cut(`↑/↓ scroll · ←/→ switch choice · ${pickHint}enter confirm · esc keep planning`)));
+	// Each hint sits beside what its keys move: scrolling above the plan, choosing under the choices.
+	out.push(paint("dim", cut("↑/↓ scroll the plan")));
 	out.push(rule);
 
+	// Plan lines may arrive painted (Markdown), so the guard cut is ANSI-aware.
 	const offset = clampOffset(view.offset, view.lines.length, maxVisible);
 	for (const line of view.lines.slice(offset, offset + maxVisible)) {
-		out.push(cut(line));
+		out.push(truncateLine(line, width));
 	}
 	if (view.lines.length > maxVisible) {
 		const last = Math.min(view.lines.length, offset + maxVisible);
@@ -128,6 +162,37 @@ export function renderPlanViewer(view: PlanViewerView, paint: Paint, width: numb
 			index === view.choice ? paint("accent", cut(`❯ ${numbered}`)) : cut(`  ${numbered}`),
 		);
 	}
+	// The keys wrap at their separators on a narrow terminal, so "esc cancel" is never cut.
+	out.push(...hintLines(`←/→ choose · ${pickHint}enter confirm · esc cancel`, width).map((line) => paint("dim", line)));
 	out.push("");
 	return out;
 }
+
+/** The question the keep-planning choice asks (Claude Code's placeholder, naming the agent). */
+export const KEEP_PLANNING_QUESTION = "Tell the agent what to change";
+
+/** How the approval ended: an approving choice, or a rejection carrying the user's words when they gave some. */
+export type PlanDecision = { kind: "approve"; index: PlanChoice } | { kind: "reject"; feedback?: string };
+
+/**
+ * The approval flow, as in Claude Code: keeping planning asks what to change,
+ * and those words go back to the model, which keeps planning. A blank answer
+ * returns to the dialog (Claude Code ignores Enter on an empty "keep planning"
+ * input). Esc on the dialog or on the question rejects without words, which
+ * stops the turn. The option without a mode is the keep-planning one.
+ */
+export async function runPlanApproval(
+	options: readonly { mode?: string }[],
+	showDialog: () => Promise<PlanChoice | null>,
+	askFeedback: () => Promise<string | undefined>,
+	signal?: AbortSignal,
+): Promise<PlanDecision> {
+	for (;;) {
+		const choice = await showDialog();
+		if (choice == null || signal?.aborted) return { kind: "reject" };
+		if (options[choice]?.mode) return { kind: "approve", index: choice };
+		const feedback = await askFeedback();
+		if (feedback === undefined || signal?.aborted) return { kind: "reject" };
+		if (feedback.trim()) return { kind: "reject", feedback: feedback.trim() };
+	}
+}

package/extensions/plugins/counts.ts

@@ -48,9 +48,9 @@ export async function fetchInstallCounts(root: string, now: Date = new Date()):
 	if (cached) return cached;
 
 	try {
-		const response = await fetchWithTimeout(INSTALL_COUNTS_URL, FETCH_TIMEOUT_MS);
-		if (!response.ok) return undefined;
-		const counts = (await response.json()) as CountsCache["counts"];
+		const counts = await fetchWithTimeout(INSTALL_COUNTS_URL, FETCH_TIMEOUT_MS, async (response) =>
+			response.ok ? ((await response.json()) as CountsCache["counts"]) : undefined,
+		);
 		if (!Array.isArray(counts)) return undefined;
 		writeJsonAtomic(join(root, CACHE_FILE), { version: 1, fetchedAt: now.toISOString(), counts } satisfies CountsCache);
 		return toMap(counts);

package/extensions/plugins/index.ts

@@ -16,14 +16,17 @@
  * ~/.claude is read-only here, always.
  */
 
-import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { promisify } from "node:util";
+import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readFavorites, toggleFavorite } from "../lib/favorites.ts";
+import { announceArgumentHint, type CommandHint, frontmatterCommandHint } from "../lib/argument-hints.ts";
 import { MCP_STATUS_CHANNEL, MCP_STATUS_REQUEST_CHANNEL, type McpStatusEvent } from "../lib/mcp-status.ts";
+import { canShowCustomUi, notifyOrPrint, notifyRpcReadOnly } from "../lib/headless-output.ts";
+import { createUserMessageSender, sessionOutlivesTurn } from "../lib/notifications.ts";
+import { ONE_SHOT_COMMAND_FAILED_CHANNEL } from "../lib/interrupt.ts";
 import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
 import { setOverride } from "../lib/plugin-overrides.ts";
 import { pathWithinBase, pluginRoot } from "../lib/plugin-root.ts";
@@ -62,13 +65,15 @@ import { decodePanelKey } from "./panel/keys.ts";
 import { type DiscoverDetail, renderPanel, type PanelPaint } from "./panel/render.ts";
 import { buildDiscoverRows, buildInstalledRows, buildMarketplaceRows, type DiscoverRow } from "./panel/rows.ts";
 import { applyPanelKey, initialPanelState, type PanelEffect, type PanelView } from "./panel/state.ts";
-import { findShellPlaceholders, replaceShellPlaceholders, substituteArguments } from "./template.ts";
+import { expandTemplate, runPlaceholderCommand } from "./shell-expand.ts";
+import { watchPermissionBridge } from "../permissions/subagent-gate.ts";
+import { followWorkCwd } from "../lib/worktree-channel.ts";
 import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
+import { promptCommandText } from "../skill/invoke.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 
-const run = promisify(execFile);
-const SHELL_TIMEOUT_MS = 30_000;
 
 // The panel is a bounded dock like Claude Code's /plugins, NOT a full-screen
 // takeover: it swaps the editor container and leaves the transcript visible
@@ -76,36 +81,6 @@ const SHELL_TIMEOUT_MS = 30_000;
 // terminals still shrink to fit. ~6 discover rows show at this cap.
 const PANEL_MAX_HEIGHT = 22;
 
-async function expandTemplate(body: string, args: string, cwd: string, persist?: { dir: string; name: 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, index) => {
-			let text: string;
-			try {
-				const { stdout, stderr } = await run(command, {
-					cwd,
-					shell: true,
-					timeout: SHELL_TIMEOUT_MS,
-					maxBuffer: 2 * 1024 * 1024,
-				});
-				text = (stdout || stderr || "").trim();
-			} catch (error) {
-				const detail = error as { stdout?: string; stderr?: string; message?: string };
-				text = (detail.stdout || detail.stderr || detail.message || "command failed").trim();
-			}
-			// A `!`command's output (a `git diff` of a large change) lands in the
-			// user turn bounded only by maxBuffer — persist it past the cap so the
-			// model gets a preview plus the path, never a wall of text (review L3).
-			outputs.set(command, persist ? persistIfLarge(text, { dir: persist.dir, id: `plugin-cmd-${persist.name}-${index}` }) : text);
-		}),
-	);
-	return replaceShellPlaceholders(withArgs, outputs);
-}
-
 /** An empty discovery result — the fallback when a scan throws. */
 function emptyDiscovered(): DiscoveredPlugins {
 	return {
@@ -136,6 +111,9 @@ function safeDiscover(roots: ReturnType<typeof defaultDiscoverRoots>): Discovere
 }
 
 export default function pluginsExtension(pi: ExtensionAPI) {
+	const sendUserMessage = createUserMessageSender(pi);
+	const getPermissionBridge = watchPermissionBridge(pi);
+	const workCwd = followWorkCwd(pi.events);
 	// False once the session is replaced: a panel action still awaiting then
 	// throws on its first pi.* call, which is expected and not an error to show.
 	const alive = sessionAlive(pi);
@@ -155,7 +133,7 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 				plugins.plugins.find((p) => p.name === command.plugin);
 			if (!plugin) continue;
 			registeredCommands.add(command.name);
-			registerPluginCommand(pi, plugin, command.name, command.path);
+			registerPluginCommand(pi, plugin, command.name, command.path, sendUserMessage, getPermissionBridge, workCwd);
 		}
 	};
 
@@ -183,7 +161,7 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 		panelOpen = true;
 		let restartNotice = false;
 		try {
-			await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+			await panelUi(pi.events, ctx.ui).custom<null>((tui, theme, _keybindings, done) => {
 				const paint: PanelPaint = {
 					fg: safeThemePaint(theme),
 					bold: safeThemeBold(theme),
@@ -522,10 +500,11 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 	registerLocalCommand(pi, "plugins", {
 		description: "Browse, install, and manage Claude Code-compatible plugins and marketplaces",
 		handler: async (args, ctx) => {
-			if (ctx.hasUI) {
+			if (canShowCustomUi(ctx)) {
 				await openPanel(ctx);
 				return;
 			}
+			notifyRpcReadOnly(ctx, "/plugins", "install or manage plugins and marketplaces");
 			// Non-interactive fallback: the old text listing.
 			if (discovered.plugins.length === 0) {
 				ctx.ui.notify("No plugins installed.", "info");
@@ -547,34 +526,73 @@ export default function pluginsExtension(pi: ExtensionAPI) {
 	});
 }
 
-function registerPluginCommand(pi: ExtensionAPI, plugin: Plugin, name: string, path: string): void {
+function registerPluginCommand(pi: ExtensionAPI, plugin: Plugin, name: string, path: string, sendUserMessage: ReturnType<typeof createUserMessageSender>, getPermissionBridge: ReturnType<typeof watchPermissionBridge>, workCwd: (sessionCwd: string) => string): void {
 	let description = `Command from the ${plugin.name} plugin`;
-	let argumentHint: string | undefined;
+	let argumentHint: CommandHint | undefined;
 	try {
 		const { frontmatter } = parseFrontmatterLoosely(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"];
+		argumentHint = frontmatterCommandHint(frontmatter);
 	} catch {
 		// Fall back to the generic description.
 	}
 
+	if (argumentHint) announceArgumentHint(pi, name, argumentHint);
 	pi.registerCommand(name, {
-		description: argumentHint ? `${description} (${argumentHint})` : description,
+		description: argumentHint?.hint ? `${description} (${argumentHint.hint})` : description,
 		handler: async (args, ctx) => {
+			// Registered commands cannot be removed from pi. Resolve their live
+			// owner and path on invocation, after toggles, updates or a cwd change.
+			const current = safeDiscover(defaultDiscoverRoots(getAgentDir(), ctx.cwd));
+			const command = current.commands.find((entry) => entry.name === name);
+			const plugin = command && current.enabledPlugins.find((entry) =>
+				entry.name === command.plugin && dirname(command.path) === join(entry.path, "commands"),
+			);
+			if (!command || !plugin) {
+				notifyOrPrint(ctx, `/${name} is unavailable in this project. Enable or reinstall its plugin in /plugins, then retry.`, "error");
+				if (!sessionOutlivesTurn(ctx.mode)) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
+				return;
+			}
+			const path = command.path;
 			let body: string;
 			try {
 				const parsed = parseFrontmatterLoosely(readFileSync(path, "utf-8")) as { body: string };
 				body = parsed.body;
 			} catch (error) {
-				ctx.ui.notify(`Could not read ${path}: ${(error as Error).message}`, "error");
+				notifyOrPrint(ctx, `Could not read ${path}: ${(error as Error).message}. Restore the command file or reinstall the ${plugin.name} plugin, then retry.`, "error");
+				// A one-shot run must not exit 0 for a command that never ran (exit/index.ts).
+				if (!sessionOutlivesTurn(ctx.mode)) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
+				return;
+			}
+			// A `!`command's output (a `git diff` of a large change) lands in the
+			// user turn: persist it past the cap so the model gets a preview plus
+			// the path, never a wall of text (review L3).
+			const dir = sessionResultsDir(ctx);
+			const runId = randomUUID();
+			let expanded: string;
+			try {
+				// Placeholders run where the session works: an entered worktree, not the checkout it left.
+				expanded = await expandTemplate(body, args, workCwd(ctx.cwd), {
+					// A unique id per run: the directory is shared across sessions and processes.
+					persist: (text, index) => persistIfLarge(text, { dir, id: `plugin-cmd-${name}-${runId}-${index}` }),
+					run: async (command, cwd) => {
+						const decide = getPermissionBridge();
+						if (!decide) throw new Error("The permission gate is unavailable. Load the permissions extension before running shell placeholders.");
+						const decision = await decide({ toolName: "bash", input: { command }, cwd, model: ctx.model });
+						if (decision?.block) throw new Error(`Shell placeholder blocked: ${decision.reason}`);
+						return runPlaceholderCommand(command, cwd);
+					},
+				});
+			} catch (error) {
+				notifyOrPrint(ctx, `Could not expand /${name}: ${(error as Error).message}`, "error");
+				if (!sessionOutlivesTurn(ctx.mode)) pi.events.emit(ONE_SHOT_COMMAND_FAILED_CHANNEL, {});
 				return;
 			}
-			const expanded = await expandTemplate(body, args, ctx.cwd, { dir: sessionResultsDir(ctx), name });
 			recordUsage(pluginRoot(getAgentDir()), "command", name);
 			// Deliver as a user turn, which is how Claude Code runs a command template.
-			pi.sendUserMessage(expanded);
+			await sendUserMessage(ctx, promptCommandText(name, args.trim(), expanded));
 		},
 	});
 }

package/extensions/plugins/install/install.ts

@@ -18,6 +18,7 @@ import { gitClone, gitHeadSha } from "../marketplace/git.ts";
 import type { MarketplaceEntry } from "../marketplace/types.ts";
 import { addInstalledPlugin, installedEntry, removeInstalledPlugin } from "./registry.ts";
 import { pluginCacheDir, versionedCachePath, withinBase } from "./paths.ts";
+import { loadInstalledPlugins, validPluginName } from "../../lib/plugins.ts";
 
 export interface InstallResult {
 	id: string;
@@ -82,6 +83,7 @@ export async function installPlugin(
 	contentRoot: string | undefined,
 ): Promise<InstallResult> {
 	const id = `${entry.name}@${marketplaceName}`;
+	if (validPluginName(entry.name) !== entry.name) throw new Error(`${id}: invalid plugin name — refusing to install`);
 	const raw = entry.raw;
 	if (raw.dependencies !== undefined) {
 		throw new Error(`${id}: plugin dependencies are not supported yet — install the dependencies manually first`);
@@ -99,6 +101,9 @@ export async function installPlugin(
 		}
 		sourceDir = resolve(contentRoot, source);
 		if (!existsSync(sourceDir)) throw new Error(`${id}: source path "${source}" does not exist in the marketplace`);
+		if (!withinBase(realpathSync(contentRoot), realpathSync(sourceDir))) {
+			throw new Error(`${id}: source path "${source}" escapes the marketplace directory through a symlink — refusing to install`);
+		}
 	} else if (source.source === "github" || source.source === "url" || source.source === "git-subdir") {
 		if (source.sha) {
 			throw new Error(`${id}: commit-sha pinning is not supported yet — use a ref (branch/tag) instead`);
@@ -121,6 +126,10 @@ export async function installPlugin(
 			rmSync(temp, { recursive: true, force: true });
 			throw new Error(`${id}: "${source.source === "git-subdir" ? source.path : url}" has no content at the expected path`);
 		}
+		if (source.source === "git-subdir" && !withinBase(realpathSync(cloneDir), realpathSync(sourceDir))) {
+			rmSync(temp, { recursive: true, force: true });
+			throw new Error(`${id}: git-subdir path "${source.path}" escapes the repository through a symlink — refusing to install`);
+		}
 	} else {
 		throw new Error(`${id}: source kind "${(source as { source: string }).source}" is not supported`);
 	}
@@ -137,6 +146,13 @@ export async function installPlugin(
 		if (!withinBase(pluginCacheBase, installPath)) {
 			throw new Error(`${id}: computed install path "${installPath}" escapes the plugin cache directory — refusing to install`);
 		}
+		// Sanitization is lossy (a.b and a-b share a cache segment). Never
+		// replace files that another registered plugin still owns.
+		if (existsSync(installPath)) {
+			const target = realpathSync(installPath);
+			const owner = loadInstalledPlugins(root).find((plugin) => plugin.id !== id && realpathSync(plugin.path) === target);
+			if (owner) throw new Error(`${id}: cache path "${installPath}" is already owned by ${owner.id} — refusing to overwrite it`);
+		}
 		copyIntoCache(sourceDir, installPath);
 		const now = new Date().toISOString();
 		addInstalledPlugin(root, id, {

package/extensions/plugins/marketplace/sync.ts

@@ -46,9 +46,15 @@ function cloneUrl(source: MarketplaceSource): string | undefined {
 const FETCH_TIMEOUT_MS = 10_000;
 
 async function fetchManifestJson(url: string): Promise<unknown> {
-	const response = await fetchWithTimeout(url, FETCH_TIMEOUT_MS, { headers: { "user-agent": "one-code-plugins" } });
-	if (!response.ok) throw new Error(`HTTP ${response.status}`);
-	return await response.json();
+	return fetchWithTimeout(
+		url,
+		FETCH_TIMEOUT_MS,
+		async (response) => {
+			if (!response.ok) throw new Error(`HTTP ${response.status}`);
+			return (await response.json()) as unknown;
+		},
+		{ init: { headers: { "user-agent": "one-code-plugins" } } },
+	);
 }
 
 /**

package/extensions/plugins/marketplace/types.ts

@@ -8,6 +8,8 @@
  * entry never blanks the rest of the marketplace.
  */
 
+import { validPluginName } from "../../lib/plugins.ts";
+
 export type MarketplaceSource =
 	| { source: "github"; repo: string; ref?: string }
 	| { source: "git"; url: string; ref?: string }
@@ -81,7 +83,7 @@ export function parseMarketplaceManifest(raw: unknown): { manifest?: Marketplace
 
 	const plugins: MarketplaceEntry[] = [];
 	for (const [index, entry] of raw.plugins.entries()) {
-		if (!isRecord(entry) || typeof entry.name !== "string" || entry.name.length === 0 || entry.name.includes(" ")) {
+		if (!isRecord(entry) || typeof entry.name !== "string" || validPluginName(entry.name) !== entry.name) {
 			errors.push(`plugins[${index}]: missing or invalid "name" — entry skipped`);
 			continue;
 		}