@oh-my-pi/pi-coding-agent 11.7.2 → 11.8.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [11.8.0] - 2026-02-10
+### Added
+
+- Added `ctx.reload()` method to extension command context to reload extensions, skills, prompts, and themes from disk
+- Added `ctx.ui.pasteToEditor()` method to paste text into the editor with proper handling (e.g., large paste markers in interactive mode)
+- Added extension UI sub-protocol for RPC mode enabling dialog methods (`select`, `confirm`, `input`, `editor`) and fire-and-forget UI methods via client communication
+- Added support for tilde (`~`) expansion in custom skill directory paths
+- Added example extension demonstrating `ctx.reload()` usage with both command and LLM-callable tool patterns
+
+### Changed
+
+- Changed `ctx.hasUI` behavior: now `true` in RPC mode (previously `false`), with dialog methods working via extension UI sub-protocol
+- Changed warning output for invalid CLI arguments to use structured logging instead of console.error
+- Changed help text to indicate command-specific help is available via `<command> --help`
+- Changed tool result event handlers to chain like middleware, allowing each handler to see and modify results from previous handlers with partial patch support
+
+### Fixed
+
+- Fixed archive extraction security vulnerability by validating that extracted paths do not escape the extraction directory
+- Fixed archive format validation to reject unsupported formats before extraction attempt
+- Fixed archive extraction error handling to provide clear error messages on failure
+
 ## [11.7.0] - 2026-02-07
 ### Changed
 

package/docs/extensions.md

@@ -583,6 +583,11 @@ pi.on("tool_call", async (event, ctx) => {
 
 Fired after tool executes. **Can modify result.**
 
+`tool_result` handlers chain like middleware:
+- Handlers run in extension load order
+- Each handler sees the latest result after previous handler changes
+- Handlers can return partial patches (`content`, `details`, or `isError`); omitted fields keep their current values
+
 ```typescript
 pi.on("tool_result", async (event, ctx) => {
   // event.toolName, event.toolCallId, event.input
@@ -609,7 +614,7 @@ UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
 
 ### ctx.hasUI
 
-`false` in print mode (`-p`), JSON mode, and RPC mode. UI methods become no-ops, so check before prompting.
+`false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client. Some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
 
 ### ctx.cwd
 
@@ -704,6 +709,62 @@ const result = await ctx.navigateTree("entry-id-456", {
 });
 ```
 
+### ctx.reload()
+
+Run the same reload flow as `/reload`.
+
+```typescript
+pi.registerCommand("reload-runtime", {
+  description: "Reload extensions, skills, prompts, and themes",
+  handler: async (_args, ctx) => {
+    await ctx.reload();
+    return;
+  },
+});
+```
+
+Important behavior:
+- `await ctx.reload()` emits `session_shutdown` for the current extension runtime
+- It then reloads resources and emits `session_start` (and `resources_discover` with reason `"reload"`) for the new runtime
+- The currently running command handler still continues in the old call frame
+- Code after `await ctx.reload()` still runs from the pre-reload version
+- Code after `await ctx.reload()` must not assume old in-memory extension state is still valid
+- After the handler returns, future commands/events/tool calls use the new extension version
+
+For predictable behavior, treat reload as terminal for that handler (`await ctx.reload(); return;`).
+
+Tools run with `ExtensionContext`, so they cannot call `ctx.reload()` directly. Use a command as the reload entrypoint, then expose a tool that queues that command as a follow-up user message.
+
+Example tool the LLM can call to trigger reload:
+
+```typescript
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("reload-runtime", {
+    description: "Reload extensions, skills, prompts, and themes",
+    handler: async (_args, ctx) => {
+      await ctx.reload();
+      return;
+    },
+  });
+
+  pi.registerTool({
+    name: "reload_runtime",
+    label: "Reload Runtime",
+    description: "Reload extensions, skills, prompts, and themes",
+    parameters: Type.Object({}),
+    async execute() {
+      pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
+      return {
+        content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }],
+      };
+    },
+  });
+}
+```
+
 ## ExtensionAPI Methods
 
 ### pi.on(event, handler)
@@ -1111,6 +1172,9 @@ ctx.ui.setTitle("omp - my-project");
 ctx.ui.setEditorText("Prefill text");
 const current = ctx.ui.getEditorText();
 
+// Paste into editor (triggers paste handling, including collapse for large content)
+ctx.ui.pasteToEditor("pasted content");
+
 // Custom editor component
 ctx.ui.setEditorComponent((tui, theme, keybindings) => new MyEditor(tui, theme, keybindings)); // EditorComponent
 ctx.ui.setEditorComponent(undefined); // Restore default
@@ -1147,7 +1211,7 @@ The callback receives:
 - `keybindings` - Keybindings manager for resolving bindings
 - `done(value)` - Call to close component and return value
 
-See [tui.md](tui.md) for the full component API and [examples/extensions/](../examples/extensions/) for working examples (todo.ts, tools.ts).
+See [tui.md](tui.md) for the full component API and [examples/extensions/](../examples/extensions/) for working examples (todo.ts, tools.ts, reload-runtime.ts).
 
 ### Message Rendering
 

package/docs/rpc.md

@@ -686,6 +686,42 @@ Response:
 
 Returns an error if the name is empty.
 
+## Extension UI (stdout)
+
+In RPC mode, extensions receive an [`ExtensionUIContext`](./extensions.md#custom-ui) backed by an extension UI sub-protocol.
+When an extension calls a dialog or UI method, the agent emits an `extension_ui_request` JSON line on stdout. The host must
+respond by writing an `extension_ui_response` JSON line on stdin.
+
+If a dialog request includes a `timeout` field, the agent auto-resolves it with a default value when the timeout expires.
+The host does not need to track or enforce timeouts.
+
+Example request (stdout):
+
+```json
+{ "type": "extension_ui_request", "id": "req-123", "method": "confirm", "title": "Confirm", "message": "Continue?", "timeout": 30000 }
+```
+
+Example response (stdin):
+
+```json
+{ "type": "extension_ui_response", "id": "req-123", "confirmed": true }
+```
+
+### Unsupported / degraded UI methods
+
+Some `ExtensionUIContext` methods are not supported or degraded in RPC mode because they require direct TUI access:
+
+- `custom()` returns `undefined`
+- `setWorkingMessage()`, `setFooter()`, `setHeader()`, `setEditorComponent()`, `setToolsExpanded()` are no-ops
+- `getEditorText()` returns `""`
+- `getToolsExpanded()` returns `false`
+- `setWidget()` only supports `string[]` (factory functions/components are ignored)
+- `getAllThemes()` returns `[]`
+- `getTheme()` returns `undefined`
+- `setTheme()` returns `{ success: false, error: "Theme switching not supported in RPC mode" }`
+
+Note: `ctx.hasUI` is `true` in RPC mode because dialog and fire-and-forget UI methods are functional via this sub-protocol.
+
 ## Events
 
 Events are streamed to stdout as JSON lines during agent operation. Events do NOT include an `id` field (only responses do).

package/examples/extensions/reload-runtime.ts

@@ -0,0 +1,37 @@
+/**
+ * Reload Runtime Extension
+ *
+ * Demonstrates ctx.reload() from ExtensionCommandContext and an LLM-callable
+ * tool that queues a follow-up command to trigger reload.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+	// Command entrypoint for reload.
+	// Treat reload as terminal for this handler.
+	pi.registerCommand("reload-runtime", {
+		description: "Reload extensions, skills, prompts, and themes",
+		handler: async (_args, ctx) => {
+			await ctx.reload();
+			return;
+		},
+	});
+
+	// LLM-callable tool. Tools get ExtensionContext, so they cannot call ctx.reload() directly.
+	// Instead, queue a follow-up user command that executes the command above.
+	pi.registerTool({
+		name: "reload_runtime",
+		label: "Reload Runtime",
+		description: "Reload extensions, skills, prompts, and themes",
+		parameters: Type.Object({}),
+		async execute() {
+			pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
+			return {
+				content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }],
+				details: {},
+			};
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "11.7.2",
+	"version": "11.8.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -90,12 +90,12 @@
 		"@mozilla/readability": "0.6.0",
 		"@oclif/core": "^4.8.0",
 		"@oclif/plugin-autocomplete": "^3.2.40",
-		"@oh-my-pi/omp-stats": "11.7.2",
-		"@oh-my-pi/pi-agent-core": "11.7.2",
-		"@oh-my-pi/pi-ai": "11.7.2",
-		"@oh-my-pi/pi-natives": "11.7.2",
-		"@oh-my-pi/pi-tui": "11.7.2",
-		"@oh-my-pi/pi-utils": "11.7.2",
+		"@oh-my-pi/omp-stats": "11.8.0",
+		"@oh-my-pi/pi-agent-core": "11.8.0",
+		"@oh-my-pi/pi-ai": "11.8.0",
+		"@oh-my-pi/pi-natives": "11.8.0",
+		"@oh-my-pi/pi-tui": "11.8.0",
+		"@oh-my-pi/pi-utils": "11.8.0",
 		"@sinclair/typebox": "^0.34.48",
 		"ajv": "^8.17.1",
 		"chalk": "^5.6.2",

package/src/cli/args.ts

@@ -2,6 +2,7 @@
  * CLI argument parsing and help display
  */
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { logger } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { APP_NAME, CONFIG_DIR_NAME } from "../config";
 import { BUILTIN_TOOLS } from "../tools";
@@ -115,11 +116,10 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 				if (name in BUILTIN_TOOLS) {
 					validTools.push(name);
 				} else {
-					console.error(
-						chalk.yellow(
-							`Warning: Unknown tool "${name}". Valid tools: ${Object.keys(BUILTIN_TOOLS).join(", ")}`,
-						),
-					);
+					logger.warn("Unknown tool passed to --tools", {
+						tool: name,
+						validTools: Object.keys(BUILTIN_TOOLS),
+					});
 				}
 			}
 			result.tools = validTools;
@@ -128,11 +128,10 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			if (isValidThinkingLevel(level)) {
 				result.thinking = level;
 			} else {
-				console.error(
-					chalk.yellow(
-						`Warning: Invalid thinking level "${level}". Valid values: ${VALID_THINKING_LEVELS.join(", ")}`,
-					),
-				);
+				logger.warn("Invalid thinking level passed to --thinking", {
+					level,
+					validThinkingLevels: [...VALID_THINKING_LEVELS],
+				});
 			}
 		} else if (arg === "--print" || arg === "-p") {
 			result.print = true;
@@ -245,7 +244,8 @@ ${chalk.bold("Available Tools (all enabled by default):")}
 export function printHelp(): void {
 	process.stdout.write(
 		`${chalk.bold(APP_NAME)} - AI coding assistant\n\n` +
-			`Run ${APP_NAME} --help for full command and option details.\n\n` +
+			`Run ${APP_NAME} --help for full command and option details.\n` +
+			`Run ${APP_NAME} <command> --help for command-specific help.\n\n` +
 			`${getExtraHelpText()}\n`,
 	);
 }

package/src/extensibility/extensions/runner.ts

@@ -138,6 +138,7 @@ const noOpUIContext: ExtensionUIContext = {
 	setTitle: () => {},
 	custom: async () => undefined as never,
 	setEditorText: () => {},
+	pasteToEditor: () => {},
 	getEditorText: () => "",
 	editor: async () => undefined,
 	setEditorComponent: () => {},
@@ -166,6 +167,7 @@ export class ExtensionRunner {
 	private branchHandler: BranchHandler = async () => ({ cancelled: false });
 	private navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
 	private switchSessionHandler: SwitchSessionHandler = async () => ({ cancelled: false });
+	private reloadHandler: () => Promise<void> = async () => {};
 	private shutdownHandler: ShutdownHandler = () => {};
 	private commandDiagnostics: Array<{ type: string; message: string; path: string }> = [];
 
@@ -212,6 +214,7 @@ export class ExtensionRunner {
 			this.branchHandler = commandContextActions.branch;
 			this.navigateTreeHandler = commandContextActions.navigateTree;
 			this.switchSessionHandler = commandContextActions.switchSession;
+			this.reloadHandler = commandContextActions.reload;
 			this.getContextUsageFn = commandContextActions.getContextUsage;
 			this.compactFn = commandContextActions.compact;
 		}
@@ -405,6 +408,7 @@ export class ExtensionRunner {
 			branch: entryId => this.branchHandler(entryId),
 			navigateTree: (targetId, options) => this.navigateTreeHandler(targetId, options),
 			switchSession: sessionPath => this.switchSessionHandler(sessionPath),
+			reload: () => this.reloadHandler(),
 			compact: instructionsOrOptions => this.compactFn(instructionsOrOptions),
 		};
 	}

package/src/extensibility/extensions/types.ts

@@ -112,6 +112,14 @@ export interface ExtensionUIContext {
 	/** Set the text in the core input editor. */
 	setEditorText(text: string): void;
 
+	/**
+	 * Paste text into the core input editor.
+	 *
+	 * Interactive mode should route through the editor's paste handling (e.g. large paste markers).
+	 * Non-interactive modes may fall back to replacing the editor text.
+	 */
+	pasteToEditor(text: string): void;
+
 	/** Get the current text from the core input editor. */
 	getEditorText(): string;
 
@@ -220,6 +228,9 @@ export interface ExtensionCommandContext extends ExtensionContext {
 	/** Switch to a different session file. */
 	switchSession(sessionPath: string): Promise<{ cancelled: boolean }>;
 
+	/** Reload the current session/runtime state. */
+	reload(): Promise<void>;
+
 	/** Compact the session context (interactive mode shows UI). */
 	compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
 }
@@ -1008,6 +1019,7 @@ export interface ExtensionCommandContextActions {
 	navigateTree: (targetId: string, options?: { summarize?: boolean }) => Promise<{ cancelled: boolean }>;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
 	switchSession: (sessionPath: string) => Promise<{ cancelled: boolean }>;
+	reload: () => Promise<void>;
 }
 
 /** Full runtime = state + actions. */

package/src/extensibility/skills.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import { logger } from "@oh-my-pi/pi-utils";
 import { skillCapability } from "../capability/skill";
@@ -316,7 +317,17 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 
 	// Process custom directories - scan directly without using full provider system
 	const allCustomSkills: Array<{ skill: Skill; path: string }> = [];
-	const customScanResults = await Promise.all(customDirectories.map(dir => scanDirectoryForSkills(dir)));
+	const customScanResults = await Promise.all(
+		customDirectories.map(dir => {
+			let resolved = dir;
+			if (resolved.startsWith("~/")) {
+				resolved = path.join(os.homedir(), resolved.slice(2));
+			} else if (resolved === "~") {
+				resolved = os.homedir();
+			}
+			return scanDirectoryForSkills(resolved);
+		}),
+	);
 	for (const customSkills of customScanResults) {
 		for (const s of customSkills.skills) {
 			if (matchesIgnorePatterns(s.name)) continue;

package/src/modes/controllers/extension-ui-controller.ts

@@ -47,6 +47,9 @@ export class ExtensionUiController {
 			setTitle: title => setTerminalTitle(title),
 			custom: (factory, _options) => this.showHookCustom(factory),
 			setEditorText: text => this.ctx.editor.setText(text),
+			pasteToEditor: text => {
+				this.ctx.editor.handleInput(`\x1b[200~${text}\x1b[201~`);
+			},
 			getEditorText: () => this.ctx.editor.getText(),
 			editor: (title, prefill) => this.showHookEditor(title, prefill),
 			get theme() {
@@ -138,6 +141,13 @@ export class ExtensionUiController {
 		const commandActions: ExtensionCommandContextActions = {
 			getContextUsage: () => this.ctx.session.getContextUsage(),
 			waitForIdle: () => this.ctx.session.agent.waitForIdle(),
+			reload: async () => {
+				await this.ctx.session.reload();
+				this.ctx.chatContainer.clear();
+				this.ctx.renderInitialMessages();
+				await this.ctx.reloadTodos();
+				this.ctx.showStatus("Reloaded session");
+			},
 			newSession: async options => {
 				// Stop any loading animation
 				if (this.ctx.loadingAnimation) {
@@ -319,6 +329,16 @@ export class ExtensionUiController {
 		const commandActions: ExtensionCommandContextActions = {
 			getContextUsage: () => this.ctx.session.getContextUsage(),
 			waitForIdle: () => this.ctx.session.agent.waitForIdle(),
+			reload: async () => {
+				if (this.ctx.isBackgrounded) {
+					return;
+				}
+				await this.ctx.session.reload();
+				this.ctx.chatContainer.clear();
+				this.ctx.renderInitialMessages();
+				await this.ctx.reloadTodos();
+				this.ctx.showStatus("Reloaded session");
+			},
 			newSession: async options => {
 				if (this.ctx.isBackgrounded) {
 					return { cancelled: true };
@@ -436,6 +456,7 @@ export class ExtensionUiController {
 			setTitle: () => {},
 			custom: async () => undefined as never,
 			setEditorText: () => {},
+			pasteToEditor: () => {},
 			getEditorText: () => "",
 			editor: async () => undefined,
 			get theme() {

package/src/modes/print-mode.ts

@@ -114,6 +114,9 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 					const success = await session.switchSession(sessionPath);
 					return { cancelled: !success };
 				},
+				reload: async () => {
+					await session.reload();
+				},
 				compact: async instructionsOrOptions => {
 					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
 					const options =

package/src/modes/rpc/rpc-mode.ts

@@ -227,6 +227,11 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 			return undefined as never;
 		}
 
+		pasteToEditor(text: string): void {
+			// Paste handling not supported in RPC mode - falls back to setEditorText
+			this.setEditorText(text);
+		}
+
 		setEditorText(text: string): void {
 			// Fire and forget - host can implement editor control
 			this.output({
@@ -379,6 +384,9 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 					const success = await session.switchSession(sessionPath);
 					return { cancelled: !success };
 				},
+				reload: async () => {
+					await session.reload();
+				},
 				compact: async instructionsOrOptions => {
 					const instructions = typeof instructionsOrOptions === "string" ? instructionsOrOptions : undefined;
 					const options =

package/src/prompts/system/system-prompt.md

@@ -166,12 +166,11 @@ Continue non-destructively; someone's work may live there.
 {{#if rules.length}}
    - Rule applies? Read first.
 {{/if}}
-     Skip only when single-file, ≤3 edits, requirements explicit.
+   - Skip only when single-file, ≤3 edits, requirements explicit.
 1. Plan if task has weight: 3–7 bullets, no more.
-2. Before each tool call: state intent in one sentence.
-3. After each tool call: interpret, decide, move; no echo.
-4. Requirements conflict/unclear: if genuinely blocked **ONLY AFTER** exhausting your exploration with tools/context/files, ask.
-5. If requested change includes refactor: remove now-unused elements; note removals.
+2. After each tool call: interpret, decide, move; no echo.
+3. Requirements conflict/unclear: if genuinely blocked **ONLY AFTER** exhausting your exploration with tools/context/files, ask.
+4. If requested change includes refactor: remove now-unused elements; note removals.
 
 ## Verification
 - Prefer external proof: tests, linters, type checks, repro steps.

package/src/session/agent-session.ts

@@ -225,6 +225,7 @@ const noOpUIContext: ExtensionUIContext = {
 	setTitle: () => {},
 	custom: async () => undefined as never,
 	setEditorText: () => {},
+	pasteToEditor: () => {},
 	getEditorText: () => "",
 	editor: async () => undefined,
 	get theme() {
@@ -1436,6 +1437,9 @@ export class AgentSession {
 				const success = await this.switchSession(sessionPath);
 				return { cancelled: !success };
 			},
+			reload: async () => {
+				await this.reload();
+			},
 			getSystemPrompt: () => this.systemPrompt,
 		};
 	}
@@ -3334,6 +3338,18 @@ Be thorough - include exact file paths, function names, error messages, and tech
 	// Session Management
 	// =========================================================================
 
+	/**
+	 * Reload the current session from disk.
+	 *
+	 * Intended for extension commands and headless modes to re-read the current session
+	 * file and re-emit session_switch hooks.
+	 */
+	async reload(): Promise<void> {
+		const sessionFile = this.sessionFile;
+		if (!sessionFile) return;
+		await this.switchSession(sessionFile);
+	}
+
 	/**
 	 * Switch to a different session file.
 	 * Aborts current operation, loads messages, restores model/thinking.

package/src/utils/tools-manager.ts

@@ -203,12 +203,24 @@ async function downloadTool(tool: ToolName, signal?: AbortSignal): Promise<strin
 	const tmp = await TempDir.create("@omp-tools-extract-");
 
 	try {
-		if (assetName.endsWith(".tar.gz") || assetName.endsWith(".zip")) {
+		if (!assetName.endsWith(".tar.gz") && !assetName.endsWith(".zip")) {
+			throw new Error(`Unsupported archive format: ${assetName}`);
+		}
+
+		try {
 			const archive = new Bun.Archive(await Bun.file(archivePath).arrayBuffer());
 			const files = await archive.files();
+			const extractRoot = path.resolve(tmp.path());
+
 			for (const [filePath, file] of files) {
-				await Bun.write(path.join(tmp.path(), filePath), file);
+				const outputPath = path.resolve(extractRoot, filePath);
+				if (!outputPath.startsWith(extractRoot + path.sep)) {
+					throw new Error(`Archive entry escapes extraction dir: ${filePath}`);
+				}
+				await Bun.write(outputPath, file);
 			}
+		} catch (err) {
+			throw new Error(`Failed to extract ${assetName}: ${err instanceof Error ? err.message : String(err)}`);
 		}
 
 		// Find the binary in extracted files