gsd-pi 2.50.0 → 2.51.0-dev.7d435fe

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -607,6 +607,25 @@ export interface ModelSelectEvent {
 // User Bash Events
 // ============================================================================
 
+/**
+ * Fired before the bash tool executes a shell command.
+ * Extensions can return a transformed command string.
+ * All registered handlers are called in order; each receives the output of the previous.
+ */
+export interface BashTransformEvent {
+	type: "bash_transform";
+	/** The command string about to be executed */
+	command: string;
+	/** Current working directory */
+	cwd: string;
+}
+
+/** Result from bash_transform event handler */
+export interface BashTransformEventResult {
+	/** Replacement command string. If omitted or empty, the original command is used. */
+	command?: string;
+}
+
 /** Fired when user executes a bash command via ! or !! prefix */
 export interface UserBashEvent {
 	type: "user_bash";
@@ -846,6 +865,7 @@ export type ExtensionEvent =
 	| ToolExecutionUpdateEvent
 	| ToolExecutionEndEvent
 	| ModelSelectEvent
+	| BashTransformEvent
 	| UserBashEvent
 	| InputEvent
 	| ToolCallEvent
@@ -1027,6 +1047,7 @@ export interface ExtensionAPI {
 	on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
 	on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;
 	on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): void;
+	on(event: "bash_transform", handler: ExtensionHandler<BashTransformEvent, BashTransformEventResult>): void;
 	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
 	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
 	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;

package/packages/pi-coding-agent/src/core/extensions/wrapper.ts

@@ -44,6 +44,15 @@ export function wrapToolWithExtensions<T>(tool: AgentTool<any, T>, runner: Exten
 			signal?: AbortSignal,
 			onUpdate?: AgentToolUpdateCallback<T>,
 		) => {
+			// For bash tool calls, let extensions transform the command before execution
+			if (tool.name === "bash" && runner.hasHandlers("bash_transform")) {
+				const input = params as { command?: string; cwd?: string };
+				if (typeof input.command === "string") {
+					const transformed = await runner.emitBashTransform(input.command, input.cwd ?? "");
+					params = { ...params, command: transformed };
+				}
+			}
+
 			// Emit tool_call event - extensions can block execution
 			if (runner.hasHandlers("tool_call")) {
 				try {

package/packages/pi-coding-agent/src/core/model-registry.ts

@@ -4,6 +4,7 @@
 
 import {
 	type Api,
+	applyCapabilityPatches,
 	type AssistantMessageEventStream,
 	type Context,
 	getApiProvider,
@@ -304,7 +305,10 @@ export class ModelRegistry {
 			}
 		}
 
-		this.models = combined;
+		// Apply capability patches so custom/discovered/extension models get
+		// capabilities (supportsXhigh, supportsServiceTier, etc.) that the
+		// static pi-ai registry applies at module load for built-in models.
+		this.models = applyCapabilityPatches(combined);
 	}
 
 	/** Load built-in models and apply provider/model overrides */
@@ -748,6 +752,9 @@ export class ModelRegistry {
 					this.models = config.oauth.modifyModels(this.models, cred);
 				}
 			}
+
+			// Ensure newly added extension models get capability patches
+			this.models = applyCapabilityPatches(this.models);
 		} else if (config.baseUrl) {
 			// Override-only: update baseUrl/headers for existing models
 			const resolvedHeaders = resolveHeaders(config.headers);
@@ -808,8 +815,8 @@ export class ModelRegistry {
 			}
 		}
 
-		// Convert and merge discovered models
-		this.discoveredModels = this.convertDiscoveredModels(results);
+		// Convert and merge discovered models, then apply capability patches
+		this.discoveredModels = applyCapabilityPatches(this.convertDiscoveredModels(results));
 		return results;
 	}
 

package/packages/pi-coding-agent/src/core/package-manager.ts

@@ -1701,9 +1701,18 @@ export class DefaultPackageManager implements PackageManager {
 			);
 		}
 		{
+			// Ecosystem skills (~/.agents/skills/) take priority over legacy config-dir skills.
+			// Skip legacy dir entirely when migration has completed (marker file present).
+			const legacySkillsMigrated =
+				resolve(userDirs.skills) !== resolve(userAgentsSkillsDir) &&
+				existsSync(join(userDirs.skills, ".migrated-to-agents"));
+			const legacyUserSkillEntries =
+				!legacySkillsMigrated && userSubdirs.has("skills")
+					? collectAutoSkillEntries(userDirs.skills)
+					: [];
 			const skillEntries = [
-				...(userSubdirs.has("skills") ? collectAutoSkillEntries(userDirs.skills) : []),
 				...collectAutoSkillEntries(userAgentsSkillsDir),
+				...legacyUserSkillEntries,
 			];
 			if (skillEntries.length > 0) {
 				addResources("skills", skillEntries, userMetadata, userOverrides.skills, globalBaseDir);

package/packages/pi-coding-agent/src/core/skills.ts

@@ -2,10 +2,28 @@ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "f
 import ignore from "ignore";
 import { homedir } from "os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "path";
-import { CONFIG_DIR_NAME, getAgentDir } from "../config.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
 import { toPosixPath } from "../utils/path-display.js";
 import type { ResourceDiagnostic } from "./diagnostics.js";
+import { CONFIG_DIR_NAME } from "../config.js";
+
+/**
+ * The standard ecosystem skills directory used by skills.sh and the
+ * Agent Skills standard.  All agents share this location for globally
+ * installed skills.
+ */
+export const ECOSYSTEM_SKILLS_DIR = join(homedir(), ".agents", "skills");
+
+/**
+ * The standard project-level skills directory (`.agents/skills/` relative to cwd).
+ */
+export const ECOSYSTEM_PROJECT_SKILLS_DIR = ".agents";
+
+/**
+ * Legacy skills directory (~/.gsd/agent/skills/ or ~/.pi/agent/skills/).
+ * Read as a fallback so existing installs don't lose skills before migration runs.
+ */
+const LEGACY_SKILLS_DIR = join(homedir(), CONFIG_DIR_NAME, "agent", "skills");
 
 /** Max name length per spec */
 const MAX_NAME_LENGTH = 64;
@@ -331,7 +349,7 @@ function escapeXml(str: string): string {
 export interface LoadSkillsOptions {
 	/** Working directory for project-local skills. Default: process.cwd() */
 	cwd?: string;
-	/** Agent config directory for global skills. Default: ~/.pi/agent */
+	/** @deprecated Skills now use ~/.agents/skills/ exclusively. This option is ignored. */
 	agentDir?: string;
 	/** Explicit skill paths (files or directories) */
 	skillPaths?: string[];
@@ -357,10 +375,7 @@ function resolveSkillPath(p: string, cwd: string): string {
  * Returns skills and any validation diagnostics.
  */
 export function loadSkills(options: LoadSkillsOptions = {}): LoadSkillsResult {
-	const { cwd = process.cwd(), agentDir, skillPaths = [], includeDefaults = true } = options;
-
-	// Resolve agentDir - if not provided, use default from config
-	const resolvedAgentDir = agentDir ?? getAgentDir();
+	const { cwd = process.cwd(), skillPaths = [], includeDefaults = true } = options;
 
 	const skillMap = new Map<string, Skill>();
 	const realPathSet = new Set<string>();
@@ -404,12 +419,22 @@ export function loadSkills(options: LoadSkillsOptions = {}): LoadSkillsResult {
 	}
 
 	if (includeDefaults) {
-		addSkills(loadSkillsFromDirInternal(join(resolvedAgentDir, "skills"), "user", true));
-		addSkills(loadSkillsFromDirInternal(resolve(cwd, CONFIG_DIR_NAME, "skills"), "project", true));
+		// Primary: ~/.agents/skills/ — the industry-standard skills.sh location
+		addSkills(loadSkillsFromDirInternal(ECOSYSTEM_SKILLS_DIR, "user", true));
+		// Primary project: .agents/skills/ — standard project-level location
+		addSkills(loadSkillsFromDirInternal(resolve(cwd, ECOSYSTEM_PROJECT_SKILLS_DIR, "skills"), "project", true));
+
+		// Legacy fallback: read skills from ~/.gsd/agent/skills/ so existing
+		// installs keep working until the one-time migration in resource-loader
+		// copies them to ~/.agents/skills/. Skip if migration has completed.
+		const legacyMigrated = existsSync(join(LEGACY_SKILLS_DIR, ".migrated-to-agents"));
+		if (LEGACY_SKILLS_DIR !== ECOSYSTEM_SKILLS_DIR && existsSync(LEGACY_SKILLS_DIR) && !legacyMigrated) {
+			addSkills(loadSkillsFromDirInternal(LEGACY_SKILLS_DIR, "user", true));
+		}
 	}
 
-	const userSkillsDir = join(resolvedAgentDir, "skills");
-	const projectSkillsDir = resolve(cwd, CONFIG_DIR_NAME, "skills");
+	const userSkillsDir = ECOSYSTEM_SKILLS_DIR;
+	const projectSkillsDir = resolve(cwd, ECOSYSTEM_PROJECT_SKILLS_DIR, "skills");
 
 	const isUnderPath = (target: string, root: string): boolean => {
 		const normalizedRoot = resolve(root);

package/packages/pi-coding-agent/src/core/slash-commands.ts

@@ -37,5 +37,6 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{ name: "reload", description: "Reload extensions, skills, prompts, and themes" },
 	{ name: "thinking", description: "Set thinking level (off/minimal/low/medium/high/xhigh)" },
 	{ name: "edit-mode", description: "Toggle edit mode (standard/hashline)" },
+	{ name: "terminal", description: "Run a shell command directly (e.g. /terminal ping -c3 1.1.1.1)" },
 	{ name: "quit", description: "Quit pi" },
 ];

package/packages/pi-coding-agent/src/core/tools/bash-spawn-windows.test.ts

@@ -0,0 +1,101 @@
+/**
+ * bash-spawn-windows.test.ts — Regression test for Windows spawn EINVAL.
+ *
+ * Verifies that bash tool spawn options disable `detached: true` on Windows
+ * to prevent EINVAL errors in ConPTY / VSCode terminal contexts.
+ *
+ * Background:
+ *   On Windows, `spawn()` with `detached: true` sets the
+ *   CREATE_NEW_PROCESS_GROUP flag in CreateProcess.  In certain terminal
+ *   contexts (VSCode integrated terminal, ConPTY, Windows Terminal) this
+ *   flag conflicts with the parent process group and causes a synchronous
+ *   EINVAL from libuv.  The bg-shell extension already guards against this
+ *   with `detached: process.platform !== "win32"` (process-manager.ts);
+ *   this test ensures all other spawn sites are aligned.
+ *
+ * See: gsd-build/gsd-2#XXXX
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+
+// Verify the spawn option pattern used across the codebase.
+// This is a static/structural test — it reads the source files and asserts
+// they use the platform-guarded detached flag.
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const SPAWN_FILES = [
+	join(__dirname, "bash.ts"),
+	join(__dirname, "..", "bash-executor.ts"),
+	join(__dirname, "..", "..", "utils", "shell.ts"),
+];
+
+test("spawn calls use platform-guarded detached flag (no unconditional detached: true)", () => {
+	for (const file of SPAWN_FILES) {
+		const content = readFileSync(file, "utf-8");
+		const lines = content.split("\n");
+
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i]!;
+			// Skip comments
+			if (line.trim().startsWith("//") || line.trim().startsWith("*")) continue;
+			// Check for unconditional `detached: true`
+			if (/detached:\s*true\b/.test(line)) {
+				assert.fail(
+					`${file}:${i + 1} has unconditional 'detached: true' — ` +
+					`must use 'detached: process.platform !== "win32"' ` +
+					`to prevent EINVAL on Windows (ConPTY / VSCode terminal)`,
+				);
+			}
+		}
+	}
+});
+
+test("killProcessTree does not use detached: true for taskkill on Windows", () => {
+	const shellFile = join(__dirname, "..", "..", "utils", "shell.ts");
+	const content = readFileSync(shellFile, "utf-8");
+
+	// Find the taskkill spawn call and ensure it doesn't have detached: true
+	const taskkillRegion = content.match(/spawn\("taskkill"[\s\S]*?\}\)/);
+	if (taskkillRegion) {
+		assert.ok(
+			!/detached:\s*true/.test(taskkillRegion[0]),
+			"taskkill spawn should not use detached: true — " +
+			"it can cause EINVAL on Windows and is unnecessary for a utility process",
+		);
+	}
+});
+
+// Smoke test: spawn with platform-guarded detached flag actually works
+test("spawn with detached: process.platform !== 'win32' succeeds", async () => {
+	const { promise, resolve, reject } = Promise.withResolvers<void>();
+
+	const child = spawn(
+		process.platform === "win32" ? "cmd" : "sh",
+		process.platform === "win32" ? ["/c", "echo ok"] : ["-c", "echo ok"],
+		{
+			detached: process.platform !== "win32",
+			stdio: ["ignore", "pipe", "pipe"],
+		},
+	);
+
+	let output = "";
+	child.stdout?.on("data", (d: Buffer) => { output += d.toString(); });
+	child.on("error", reject);
+	child.on("close", (code) => {
+		try {
+			assert.equal(code, 0, "spawn should succeed");
+			assert.ok(output.trim().includes("ok"), `Expected 'ok' in output, got: ${output}`);
+			resolve();
+		} catch (e) {
+			reject(e);
+		}
+	});
+
+	await promise;
+});

package/packages/pi-coding-agent/src/core/tools/bash.ts

@@ -158,9 +158,13 @@ const defaultBashOperations: BashOperations = {
 				return;
 			}
 
+			// On Windows, detached: true sets CREATE_NEW_PROCESS_GROUP which can
+			// cause EINVAL in VSCode/ConPTY terminal contexts.  The bg-shell
+			// extension already guards this (process-manager.ts); align here.
+			// Process-tree cleanup uses taskkill /F /T on Windows regardless.
 			const child = spawn(shell, [...args, command], {
 				cwd,
-				detached: true,
+				detached: process.platform !== "win32",
 				env: env ?? getShellEnv(),
 				stdio: ["ignore", "pipe", "pipe"],
 			});

package/packages/pi-coding-agent/src/index.ts

@@ -125,6 +125,8 @@ export type {
 	TurnStartEvent,
 	UserBashEvent,
 	UserBashEventResult,
+	BashTransformEvent,
+	BashTransformEventResult,
 	WidgetPlacement,
 	WriteToolCallEvent,
 } from "./core/extensions/index.js";
@@ -219,6 +221,8 @@ export {
 } from "./core/settings-manager.js";
 // Skills
 export {
+	ECOSYSTEM_SKILLS_DIR,
+	ECOSYSTEM_PROJECT_SKILLS_DIR,
 	formatSkillsForPrompt,
 	getLoadedSkills,
 	type LoadSkillsFromDirOptions,
@@ -310,8 +314,11 @@ export {
 	type RpcClientOptions,
 	type RpcEventListener,
 	type RpcCommand,
+	type RpcInitResult,
+	type RpcProtocolVersion,
 	type RpcResponse,
 	type RpcSessionState,
+	type RpcV2Event,
 } from "./modes/index.js";
 // RPC JSONL utilities
 export { attachJsonlLineReader, serializeJsonLine } from "./modes/rpc/jsonl.js";

package/packages/pi-coding-agent/src/main.ts

@@ -419,11 +419,13 @@ export async function main(args: string[]) {
 		additionalPromptTemplatePaths: firstPass.promptTemplates,
 		additionalThemePaths: firstPass.themes,
 		noExtensions: firstPass.noExtensions,
-		noSkills: firstPass.noSkills,
-		noPromptTemplates: firstPass.noPromptTemplates,
-		noThemes: firstPass.noThemes,
+		noSkills: firstPass.noSkills || firstPass.bare,
+		noPromptTemplates: firstPass.noPromptTemplates || firstPass.bare,
+		noThemes: firstPass.noThemes || firstPass.bare,
 		systemPrompt: firstPass.systemPrompt,
 		appendSystemPrompt: firstPass.appendSystemPrompt,
+		// --bare: suppress CLAUDE.md/AGENTS.md ancestor walk
+		...(firstPass.bare ? { agentsFilesOverride: () => ({ agentsFiles: [] }) } : {}),
 	});
 	await resourceLoader.reload();
 	time("resourceLoader.reload");

package/packages/pi-coding-agent/src/modes/index.ts

@@ -6,4 +6,11 @@ export { InteractiveMode, type InteractiveModeOptions } from "./interactive/inte
 export { type PrintModeOptions, runPrintMode } from "./print-mode.js";
 export { type ModelInfo, RpcClient, type RpcClientOptions, type RpcEventListener } from "./rpc/rpc-client.js";
 export { runRpcMode } from "./rpc/rpc-mode.js";
-export type { RpcCommand, RpcResponse, RpcSessionState } from "./rpc/rpc-types.js";
+export type {
+	RpcCommand,
+	RpcInitResult,
+	RpcProtocolVersion,
+	RpcResponse,
+	RpcSessionState,
+	RpcV2Event,
+} from "./rpc/rpc-types.js";

package/packages/pi-coding-agent/src/modes/interactive/components/footer.ts

@@ -221,8 +221,9 @@ export class FooterComponent implements Component {
 				.sort(([a], [b]) => a.localeCompare(b))
 				.map(([, text]) => sanitizeStatusText(text));
 			const statusLine = sortedStatuses.join(" ");
-			// Truncate to terminal width with dim ellipsis for consistency with footer style
-			lines.push(truncateToWidth(statusLine, width, theme.fg("dim", "...")));
+			// Match the rest of the footer styling: extension statuses should render
+			// in the same dim color as pwd/stats, with a dim ellipsis on truncation.
+			lines.push(truncateToWidth(theme.fg("dim", statusLine), width, theme.fg("dim", "...")));
 		}
 
 		return lines;

package/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts

@@ -150,7 +150,6 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & {
 									content: [{ type: "text", text: "Web search disabled (offline mode)" }],
 									isError: false,
 								});
-								host.pendingTools.delete(content.toolUseId);
 							} else {
 								const searchContent = content.content;
 								const isError = searchContent && typeof searchContent === "object" && "type" in (searchContent as any) && (searchContent as any).type === "web_search_tool_result_error";
@@ -158,7 +157,6 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & {
 									content: [{ type: "text", text: host.formatWebSearchResult(searchContent) }],
 									isError: !!isError,
 								});
-								host.pendingTools.delete(content.toolUseId);
 							}
 						}
 					}

package/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts

@@ -1989,6 +1989,7 @@ export class InteractiveMode {
 			handleDebugCommand: () => this.handleDebugCommand(),
 			shutdown: () => this.shutdown(),
 			executeCompaction: (instructions, isAuto) => this.executeCompaction(instructions, isAuto),
+			handleBashCommand: (command, options) => this.handleBashCommand(command, options?.excludeFromContext, options?.displayCommand, options?.loginShell),
 		};
 	}
 
@@ -3647,8 +3648,9 @@ export class InteractiveMode {
 		}
 	}
 
-	private async handleBashCommand(command: string, excludeFromContext = false): Promise<void> {
+	private async handleBashCommand(command: string, excludeFromContext = false, displayCommand?: string, loginShell?: boolean): Promise<void> {
 		const extensionRunner = this.session.extensionRunner;
+		const label = displayCommand || command;
 
 		// Emit user_bash event to let extensions intercept
 		const eventResult = extensionRunner
@@ -3665,7 +3667,7 @@ export class InteractiveMode {
 			const result = eventResult.result;
 
 			// Create UI component for display
-			this.bashComponent = new BashExecutionComponent(command, this.ui, excludeFromContext);
+			this.bashComponent = new BashExecutionComponent(label, this.ui, excludeFromContext);
 			if (this.session.isStreaming) {
 				this.pendingMessagesContainer.addChild(this.bashComponent);
 				this.pendingBashComponents.push(this.bashComponent);
@@ -3693,7 +3695,7 @@ export class InteractiveMode {
 
 		// Normal execution path (possibly with custom operations)
 		const isDeferred = this.session.isStreaming;
-		this.bashComponent = new BashExecutionComponent(command, this.ui, excludeFromContext);
+		this.bashComponent = new BashExecutionComponent(label, this.ui, excludeFromContext);
 
 		if (isDeferred) {
 			// Show in pending area when agent is streaming
@@ -3714,7 +3716,7 @@ export class InteractiveMode {
 						this.ui.requestRender();
 					}
 				},
-				{ excludeFromContext, operations: eventResult?.operations },
+				{ excludeFromContext, operations: eventResult?.operations, loginShell },
 			);
 
 			if (this.bashComponent) {

package/packages/pi-coding-agent/src/modes/interactive/slash-command-handlers.ts

@@ -104,6 +104,9 @@ export interface SlashCommandContext {
 
 	// For compaction
 	executeCompaction(customInstructions?: string, isAuto?: boolean): Promise<unknown>;
+
+	// Bash execution
+	handleBashCommand(command: string, options?: { excludeFromContext?: boolean; displayCommand?: string; loginShell?: boolean }): Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -220,6 +223,18 @@ export async function dispatchSlashCommand(
 		await ctx.shutdown();
 		return true;
 	}
+	if (text === "/terminal" || text.startsWith("/terminal ")) {
+		const command = text.startsWith("/terminal ") ? text.slice(10).trim() : "";
+		if (!command) {
+			ctx.showWarning("Usage: /terminal <command>  (e.g. /terminal ping -c3 1.1.1.1)");
+			return true;
+		}
+		// Run in the user's login shell ($SHELL -l -c) so PATH additions
+		// and env vars from shell profiles (.zprofile/.profile) are available.
+		// Note: shell aliases are not loaded (requires -i which has side effects).
+		await ctx.handleBashCommand(command, { loginShell: true });
+		return true;
+	}
 
 	return false;
 }

package/packages/pi-coding-agent/src/modes/interactive/theme/themes.ts

@@ -113,6 +113,7 @@ const light: ThemeJson = {
 		green: "#588458",
 		red: "#aa5555",
 		yellow: "#9a7326",
+		warning: "#7a5a00",
 		mediumGray: "#6c6c6c",
 		dimGray: "#767676",
 		lightGray: "#b0b0b0",
@@ -130,7 +131,7 @@ const light: ThemeJson = {
 		borderMuted: "lightGray",
 		success: "green",
 		error: "red",
-		warning: "yellow",
+		warning: "warning",
 		muted: "mediumGray",
 		dim: "dimGray",
 		text: "",

package/packages/pi-coding-agent/src/modes/rpc/rpc-client.ts

@@ -11,7 +11,7 @@ import type { SessionStats } from "../../core/agent-session.js";
 import type { BashResult } from "../../core/bash-executor.js";
 import type { CompactionResult } from "../../core/compaction/index.js";
 import { attachJsonlLineReader, serializeJsonLine } from "./jsonl.js";
-import type { RpcCommand, RpcResponse, RpcSessionState, RpcSlashCommand } from "./rpc-types.js";
+import type { RpcCommand, RpcInitResult, RpcResponse, RpcSessionState, RpcSlashCommand } from "./rpc-types.js";
 
 // ============================================================================
 // Types
@@ -398,6 +398,59 @@ export class RpcClient {
 		return this.getData<{ commands: RpcSlashCommand[] }>(response).commands;
 	}
 
+	/**
+	 * Send a UI response to a pending extension_ui_request.
+	 * Fire-and-forget — no request/response correlation.
+	 */
+	sendUIResponse(id: string, response: { value?: string; values?: string[]; confirmed?: boolean; cancelled?: boolean }): void {
+		if (!this.process?.stdin) {
+			throw new Error("Client not started");
+		}
+		this.process.stdin.write(serializeJsonLine({
+			type: "extension_ui_response",
+			id,
+			...response,
+		}));
+	}
+
+	/**
+	 * Initialize a v2 protocol session. Must be sent as the first command.
+	 * Returns the negotiated protocol version, session ID, and server capabilities.
+	 */
+	async init(options?: { clientId?: string }): Promise<RpcInitResult> {
+		const response = await this.send({ type: "init", protocolVersion: 2, clientId: options?.clientId });
+		return this.getData<RpcInitResult>(response);
+	}
+
+	/**
+	 * Request a graceful shutdown of the agent process.
+	 * Waits for the response before the process exits.
+	 */
+	async shutdown(): Promise<void> {
+		await this.send({ type: "shutdown" });
+		// Wait for process to exit after shutdown acknowledgment
+		if (this.process) {
+			await new Promise<void>((resolve) => {
+				const timeout = setTimeout(() => {
+					this.process?.kill("SIGKILL");
+					resolve();
+				}, 5000);
+				this.process?.on("exit", () => {
+					clearTimeout(timeout);
+					resolve();
+				});
+			});
+		}
+	}
+
+	/**
+	 * Subscribe to specific event types (v2 only).
+	 * Pass ["*"] to receive all events, or a list of event type strings to filter.
+	 */
+	async subscribe(events: string[]): Promise<void> {
+		await this.send({ type: "subscribe", events });
+	}
+
 	// =========================================================================
 	// Helpers
 	// =========================================================================