@oh-my-pi/pi-coding-agent 11.7.3 → 11.8.1

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## [Unreleased]
 
+## [11.8.1] - 2026-02-10
+
+### Added
+
+- Added current date to system prompt context in YYYY-MM-DD format for date-aware agent reasoning
+- Added file size display in UI when files are skipped due to size limits
+- Added support for gigabyte (GB) file size formatting in truncate utility
+
+### Changed
+
+- Changed skipped file messages to include file size information for better visibility into why files were excluded
+- Changed file processing to skip reading files exceeding 5MB (text) or 25MB (images) and include them as path-only references instead
+- Changed @mention auto-reading to skip files exceeding 5MB (text) or 25MB (images) to prevent out-of-memory issues with large files
+- Clarified that subagents automatically inherit full system prompt including AGENTS.md, context files, and skills — do not repeat project rules or conventions in task context
+- Updated task context guidance to focus on session-specific information subagents lack, eliminating redundant documentation of project constraints already available to them
+- Refined constraints template to emphasize task-specific rules and session decisions rather than global project conventions
+- Expanded anti-patterns section to explicitly flag redundant context that wastes tokens by repeating AGENTS.md rules, project constraints, and tool preferences
+
+### Fixed
+
+- Fixed bash tool hanging when commands spawn background jobs by properly detecting foreground process completion
+- Fixed bash tool occasionally hanging after command completion when background jobs keep stdout/stderr open
+- Fixed crash when auto-reading @mentions for very large files by skipping content injection with an explicit "skipped" note
+- Improved bash tool output draining after foreground completion to reduce tail output truncation
+
+## [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.3",
+	"version": "11.8.1",
 	"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.3",
-		"@oh-my-pi/pi-agent-core": "11.7.3",
-		"@oh-my-pi/pi-ai": "11.7.3",
-		"@oh-my-pi/pi-natives": "11.7.3",
-		"@oh-my-pi/pi-tui": "11.7.3",
-		"@oh-my-pi/pi-utils": "11.7.3",
+		"@oh-my-pi/omp-stats": "11.8.1",
+		"@oh-my-pi/pi-agent-core": "11.8.1",
+		"@oh-my-pi/pi-ai": "11.8.1",
+		"@oh-my-pi/pi-natives": "11.8.1",
+		"@oh-my-pi/pi-tui": "11.8.1",
+		"@oh-my-pi/pi-utils": "11.8.1",
 		"@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/cli/file-processor.ts

@@ -7,9 +7,15 @@ import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { isEnoent } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { resolveReadPath } from "../tools/path-utils";
+import { formatSize } from "../tools/truncate";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 
+// Keep CLI startup responsive and avoid OOM when users pass huge files.
+// If a file exceeds these limits, we include it as a path-only <file/> block.
+const MAX_CLI_TEXT_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_CLI_IMAGE_BYTES = 25 * 1024 * 1024; // 25MB
+
 export interface ProcessedFiles {
 	text: string;
 	images: ImageContent[];
@@ -30,6 +36,27 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
 		const absolutePath = path.resolve(resolveReadPath(fileArg, process.cwd()));
 
+		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		try {
+			stat = await fs.stat(absolutePath);
+		} catch (err) {
+			if (isEnoent(err)) {
+				console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+				process.exit(1);
+			}
+			throw err;
+		}
+
+		const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
+		const maxBytes = mimeType ? MAX_CLI_IMAGE_BYTES : MAX_CLI_TEXT_BYTES;
+		if (stat.size > maxBytes) {
+			console.error(
+				chalk.yellow(`Warning: Skipping file contents (too large: ${formatSize(stat.size)}): ${absolutePath}`),
+			);
+			text += `<file name="${absolutePath}">(skipped: too large, ${formatSize(stat.size)})</file>\n`;
+			continue;
+		}
+
 		// Read file, handling not-found gracefully
 		let buffer: Buffer;
 		try {
@@ -45,8 +72,6 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 			continue;
 		}
 
-		const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
-
 		if (mimeType) {
 			// Handle image file
 			const base64Content = buffer.toBase64();

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/modes/utils/ui-helpers.ts

@@ -17,6 +17,7 @@ import { theme } from "../../modes/theme/theme";
 import type { CompactionQueuedMessage, InteractiveModeContext } from "../../modes/types";
 import { type CustomMessage, SKILL_PROMPT_MESSAGE_TYPE, type SkillPromptDetails } from "../../session/messages";
 import type { SessionContext } from "../../session/session-manager";
+import { formatSize } from "../../tools/truncate";
 
 type TextBlock = { type: "text"; text: string };
 
@@ -127,11 +128,17 @@ export class UiHelpers {
 			case "fileMention": {
 				// Render compact file mention display
 				for (const file of message.files) {
-					const suffix = file.image
-						? "(image)"
-						: file.lineCount === undefined
-							? "(unknown lines)"
-							: `(${file.lineCount} lines)`;
+					let suffix: string;
+					if (file.skippedReason === "tooLarge") {
+						const size = typeof file.byteSize === "number" ? formatSize(file.byteSize) : "unknown size";
+						suffix = `(skipped: ${size})`;
+					} else {
+						suffix = file.image
+							? "(image)"
+							: file.lineCount === undefined
+								? "(unknown lines)"
+								: `(${file.lineCount} lines)`;
+					}
 					const text = `${theme.fg("dim", `${theme.tree.last} `)}${theme.fg("muted", "Read")} ${theme.fg(
 						"accent",
 						file.path,

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

@@ -255,6 +255,7 @@ Read `rule://<name>` when working in domain.
 {{/if}}
 
 Current directory: {{cwd}}
+Current date: {{date}}
 
 <north_star>
 Correctness. Usefulness. Fidelity to truth.

package/src/prompts/tools/task.md

@@ -1,13 +1,18 @@
 # Task
 
-Launch subagents to execute parallel, well-scoped tasks with shared, token-efficient context.
+Launch subagents to execute parallel, well-scoped tasks.
 
-Subagents have **zero implicit context** — they see only `context` + `assignment`. Treat every subagent as a senior engineer on day one: technically strong, but unfamiliar with every decision, convention, and file layout you've accumulated.
+## What subagents inherit automatically
+Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. Do NOT repeat project rules, coding conventions, or style guidelines in `context` — they already have them.
 
-Subagents CAN grep the parent conversation file for supplementary details, but CANNOT grep for:
+## What subagents do NOT have
+Subagents have no access to your conversation history. They don't know:
 - Decisions you made but didn't write down
-- Conventions that exist only in your head
-- Which of 50 possible approaches you want
+- Which approach you chose among alternatives
+- What you learned from reading files during this session
+- Requirements the user stated only in conversation
+
+Subagents CAN grep the parent conversation file for supplementary details.
 ---
 
 ## Parameters
@@ -18,9 +23,13 @@ Agent type for all tasks in this batch.
 
 ### `context` (optional — strongly recommended)
 
-Shared background prepended verbatim to every task `assignment`. Common info once; reduces token cost.
+Shared background prepended verbatim to every task `assignment`. Use only for session-specific information subagents lack.
+
+<critical>
+Do NOT include project rules, coding conventions, or style guidelines — subagents already have AGENTS.md and context files in their system prompt. Repeating them wastes tokens.
+</critical>
 
-Use template; omit non-applicable sections.
+Use template; omit non-applicable sections:
 
 ````
 ## Goal
@@ -30,9 +39,8 @@ One sentence: batch accomplishes together.
 Explicitly exclude tempting scope — what tasks must not touch/attempt.
 
 ## Constraints
-- MUST / MUST NOT rules (naming, error handling, banned approaches)
-- Language/framework version requirements
-- What exists vs what to create
+- Task-specific MUST / MUST NOT rules not already in AGENTS.md
+- Decisions made during this session that affect implementation
 
 ## Reference Files
 - `path/to/file.ext` — pattern demo
@@ -47,9 +55,9 @@ Explicitly exclude tempting scope — what tasks must not touch/attempt.
 - Definition of "done" for batch
 - Note: build/test/lint verification happens AFTER all tasks complete — not inside tasks (see below)
 ````
-**Belongs in `context`**: project goal, non-goals, constraints, conventions, reference paths, shared type definitions, API contracts, global acceptance commands — anything 2+ tasks need.
+**Belongs in `context`**: task-specific goal, non-goals, session decisions, reference paths, shared type definitions, API contracts, global acceptance commands — anything 2+ tasks need that isn't already in AGENTS.md.
 **Rule of thumb:** if repeat in 2+ tasks, belongs in `context`.
-**Does NOT belong in `context`**: per-task file lists, one-off requirements (go in `assignment`), structured output format (goes in `schema`).
+**Does NOT belong in `context`**: project rules already in AGENTS.md/context files, per-task file lists, one-off requirements (go in `assignment`), structured output format (goes in `schema`).
 
 ### `tasks` (required)
 
@@ -117,6 +125,10 @@ Use structure every assignment:
 - "Use existing patterns."
 - "Follow conventions."
 - "No WASM."
+**Redundant context** — wastes tokens repeating what subagents already have:
+- Restating AGENTS.md rules (coding style, import conventions, logger usage)
+- Repeating project constraints from context files
+- Listing tool/framework preferences already documented in the repo
 
 If tempted to write above, expand using templates.
 **Output format in prose instead of `schema`** — agent returns null:
@@ -252,7 +264,7 @@ Layered work with dependencies:
 ## Pre-flight checklist
 
 Before calling tool, verify:
-- [ ] `context` includes shared constraints, references, definition of done
+- [ ] `context` includes only session-specific info not already in AGENTS.md/context files
 - [ ] Each `assignment` follows assignment template — not one-liner
 - [ ] Each `assignment` includes edge cases / "don’t break" items
 - [ ] Tasks truly parallel (no hidden dependencies)

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/session/messages.ts

@@ -114,6 +114,10 @@ export interface FileMentionMessage {
 		path: string;
 		content: string;
 		lineCount?: number;
+		/** File size in bytes, if known. */
+		byteSize?: number;
+		/** Why the file contents were omitted from auto-read. */
+		skippedReason?: "tooLarge";
 		image?: ImageContent;
 	}>;
 	timestamp: number;

package/src/system-prompt.ts

@@ -473,6 +473,11 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	const systemPromptCustomization = await loadSystemPromptFiles({ cwd: resolvedCwd });
 
 	const now = new Date();
+	const date = now.toLocaleDateString("en-CA", {
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	});
 	const dateTime = now.toLocaleString("en-US", {
 		weekday: "long",
 		year: "numeric",
@@ -529,6 +534,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 			skills: filteredSkills,
 			preloadedSkills: preloadedSkillContents,
 			rules: rules ?? [],
+			date,
 			dateTime,
 			cwd: resolvedCwd,
 		});
@@ -544,6 +550,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		skills: filteredSkills,
 		preloadedSkills: preloadedSkillContents,
 		rules: rules ?? [],
+		date,
 		dateTime,
 		cwd: resolvedCwd,
 		appendSystemPrompt: resolvedAppendPrompt ?? "",

package/src/tools/truncate.ts

@@ -53,8 +53,10 @@ export function formatSize(bytes: number): string {
 		return `${bytes}B`;
 	} else if (bytes < 1024 * 1024) {
 		return `${(bytes / 1024).toFixed(1)}KB`;
-	} else {
+	} else if (bytes < 1024 * 1024 * 1024) {
 		return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	} else {
+		return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
 	}
 }
 

package/src/utils/file-mentions.ts

@@ -22,6 +22,11 @@ const TRAILING_PUNCTUATION_REGEX = /[)\]}>.,;:!?"'`]+$/;
 const MENTION_BOUNDARY_REGEX = /[\s([{<"'`]/;
 const DEFAULT_DIR_LIMIT = 500;
 
+// Avoid OOM when users @mention very large files. Above these limits we skip
+// auto-reading and only include the path in the message.
+const MAX_AUTO_READ_TEXT_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_AUTO_READ_IMAGE_BYTES = 25 * 1024 * 1024; // 25MB
+
 function isMentionBoundary(text: string, index: number): boolean {
 	if (index === 0) return true;
 	return MENTION_BOUNDARY_REGEX.test(text[index - 1]);
@@ -183,6 +188,15 @@ export async function generateFileMentionMessages(
 
 			const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
 			if (mimeType) {
+				if (stat.size > MAX_AUTO_READ_IMAGE_BYTES) {
+					files.push({
+						path: filePath,
+						content: `(skipped auto-read: too large, ${formatSize(stat.size)})`,
+						byteSize: stat.size,
+						skippedReason: "tooLarge",
+					});
+					continue;
+				}
 				const buffer = await fs.readFile(absolutePath);
 				if (buffer.length === 0) {
 					continue;
@@ -210,6 +224,16 @@ export async function generateFileMentionMessages(
 				continue;
 			}
 
+			if (stat.size > MAX_AUTO_READ_TEXT_BYTES) {
+				files.push({
+					path: filePath,
+					content: `(skipped auto-read: too large, ${formatSize(stat.size)})`,
+					byteSize: stat.size,
+					skippedReason: "tooLarge",
+				});
+				continue;
+			}
+
 			const content = await Bun.file(absolutePath).text();
 			const { output, lineCount } = buildTextOutput(content);
 			files.push({ path: filePath, content: output, lineCount });

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