@oh-my-pi/pi-coding-agent 3.15.1 → 3.20.1

package/src/core/session-manager.ts

@@ -1,19 +1,16 @@
 import {
-	appendFileSync,
 	closeSync,
 	createWriteStream,
 	existsSync,
 	fsyncSync,
 	mkdirSync,
 	openSync,
-	readdirSync,
 	readFileSync,
 	readSync,
 	renameSync,
 	statSync,
 	unlinkSync,
 	type WriteStream,
-	writeFileSync,
 } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
@@ -23,13 +20,14 @@ import sharp from "sharp";
 import { getAgentDir as getDefaultAgentDir } from "../config";
 import {
 	type BashExecutionMessage,
+	type CustomMessage,
 	createBranchSummaryMessage,
 	createCompactionSummaryMessage,
-	createHookMessage,
+	createCustomMessage,
 	type HookMessage,
 } from "./messages";
 
-export const CURRENT_SESSION_VERSION = 2;
+export const CURRENT_SESSION_VERSION = 3;
 
 export interface SessionHeader {
 	type: "session";
@@ -75,27 +73,27 @@ export interface CompactionEntry<T = unknown> extends SessionEntryBase {
 	summary: string;
 	firstKeptEntryId: string;
 	tokensBefore: number;
-	/** Hook-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
 	details?: T;
-	/** True if generated by a hook, undefined/false if pi-generated (backward compatible) */
-	fromHook?: boolean;
+	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
+	fromExtension?: boolean;
 }
 
 export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
 	type: "branch_summary";
 	fromId: string;
 	summary: string;
-	/** Hook-specific data (not sent to LLM) */
+	/** Extension-specific data (not sent to LLM) */
 	details?: T;
-	/** True if generated by a hook, false if pi-generated */
-	fromHook?: boolean;
+	/** True if generated by an extension, false if pi-generated */
+	fromExtension?: boolean;
 }
 
 /**
- * Custom entry for hooks to store hook-specific data in the session.
- * Use customType to identify your hook's entries.
+ * Custom entry for extensions to store extension-specific data in the session.
+ * Use customType to identify your extension's entries.
  *
- * Purpose: Persist hook state across session reloads. On reload, hooks can
+ * Purpose: Persist extension state across session reloads. On reload, extensions can
  * scan entries for their customType and reconstruct internal state.
  *
  * Does NOT participate in LLM context (ignored by buildSessionContext).
@@ -122,12 +120,12 @@ export interface TtsrInjectionEntry extends SessionEntryBase {
 }
 
 /**
- * Custom message entry for hooks to inject messages into LLM context.
- * Use customType to identify your hook's entries.
+ * Custom message entry for extensions to inject messages into LLM context.
+ * Use customType to identify your extension's entries.
  *
  * Unlike CustomEntry, this DOES participate in LLM context.
  * The content is converted to a user message in buildSessionContext().
- * Use details for hook-specific metadata (not sent to LLM).
+ * Use details for extension-specific metadata (not sent to LLM).
  *
  * display controls TUI rendering:
  * - false: hidden entirely
@@ -239,8 +237,22 @@ function migrateV1ToV2(entries: FileEntry[]): void {
 	}
 }
 
-// Add future migrations here:
-// function migrateV2ToV3(entries: FileEntry[]): void { ... }
+/** Migrate v2 → v3: rename hookMessage role to custom. Mutates in place. */
+function migrateV2ToV3(entries: FileEntry[]): void {
+	for (const entry of entries) {
+		if (entry.type === "session") {
+			entry.version = 3;
+			continue;
+		}
+
+		if (entry.type === "message") {
+			const msg = entry.message as { role?: string };
+			if (msg.role === "hookMessage") {
+				(entry.message as { role: string }).role = "custom";
+			}
+		}
+	}
+}
 
 /**
  * Run all necessary migrations to bring entries to current version.
@@ -253,7 +265,7 @@ function migrateToCurrentVersion(entries: FileEntry[]): boolean {
 	if (version >= CURRENT_SESSION_VERSION) return false;
 
 	if (version < 2) migrateV1ToV2(entries);
-	// if (version < 3) migrateV2ToV3(entries);
+	if (version < 3) migrateV2ToV3(entries);
 
 	return true;
 }
@@ -380,7 +392,7 @@ export function buildSessionContext(
 			messages.push(entry.message);
 		} else if (entry.type === "custom_message") {
 			messages.push(
-				createHookMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp),
+				createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp),
 			);
 		} else if (entry.type === "branch_summary" && entry.summary) {
 			messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
@@ -438,7 +450,7 @@ function getDefaultSessionDir(cwd: string): string {
 export function loadEntriesFromFile(filePath: string): FileEntry[] {
 	if (!existsSync(filePath)) return [];
 
-	const content = readFileSync(filePath, "utf8");
+	const content = readFileSync(filePath, "utf-8");
 	const entries: FileEntry[] = [];
 	const lines = content.trim().split("\n");
 
@@ -535,10 +547,9 @@ function getSortedSessions(sessionDir: string): RecentSessionInfo[] {
 			return header;
 		};
 
-		return readdirSync(sessionDir)
+		return Array.from(new Bun.Glob("*.jsonl").scanSync(sessionDir))
 			.map((f) => {
 				try {
-					if (!f.endsWith(".jsonl")) return null;
 					const path = join(sessionDir, f);
 					const fd = openSync(path, "r");
 					try {
@@ -927,8 +938,8 @@ export class SessionManager {
 	}
 
 	/** Initialize with a specific session file (used by factory methods) */
-	private async _initSessionFile(sessionFile: string): Promise<void> {
-		await this.setSessionFile(sessionFile);
+	private _initSessionFile(sessionFile: string): void {
+		this.setSessionFile(sessionFile);
 	}
 
 	/** Initialize with a new session (used by factory methods) */
@@ -937,23 +948,25 @@ export class SessionManager {
 	}
 
 	/** Switch to a different session file (used for resume and branching) */
-	async setSessionFile(sessionFile: string): Promise<void> {
-		await this._closePersistWriter();
+	setSessionFile(sessionFile: string): void {
+		void this._closePersistWriter();
 		this.persistError = undefined;
 		this.persistErrorReported = false;
 		this.sessionFile = resolve(sessionFile);
 		if (existsSync(this.sessionFile)) {
-			this.fileEntries = loadEntriesFromFile(this.sessionFile);
-			const header = this.fileEntries.find((e) => e.type === "session") as SessionHeader | undefined;
-			this.sessionId = header?.id ?? nanoid();
-			this.sessionTitle = header?.title;
-
-			if (migrateToCurrentVersion(this.fileEntries)) {
-				await this._rewriteFile();
-			}
+			void (async () => {
+				this.fileEntries = await loadEntriesFromFile(this.sessionFile!);
+				const header = this.fileEntries.find((e) => e.type === "session") as SessionHeader | undefined;
+				this.sessionId = header?.id ?? nanoid();
+				this.sessionTitle = header?.title;
+
+				if (migrateToCurrentVersion(this.fileEntries)) {
+					await this._rewriteFile();
+				}
 
-			this._buildIndex();
-			this.flushed = true;
+				this._buildIndex();
+				this.flushed = true;
+			})();
 		} else {
 			this._newSessionSync();
 		}
@@ -1178,7 +1191,7 @@ export class SessionManager {
 							fileHeader.title = title;
 							lines[0] = JSON.stringify(fileHeader);
 							const tempPath = join(resolve(sessionFile, ".."), `.${basename(sessionFile)}.${nanoid(6)}.tmp`);
-							writeFileSync(tempPath, lines.join("\n"));
+							await Bun.write(tempPath, lines.join("\n"));
 							const fd = openSync(tempPath, "r");
 							try {
 								fsyncSync(fd);
@@ -1265,7 +1278,7 @@ export class SessionManager {
 	 * so it is easier to find them.
 	 * These need to be appended via appendCompaction() and appendBranchSummary() methods.
 	 */
-	appendMessage(message: Message | HookMessage | BashExecutionMessage): string {
+	appendMessage(message: Message | CustomMessage | HookMessage | BashExecutionMessage): string {
 		const entry: SessionMessageEntry = {
 			type: "message",
 			id: generateId(this.byId),
@@ -1314,7 +1327,7 @@ export class SessionManager {
 		firstKeptEntryId: string,
 		tokensBefore: number,
 		details?: T,
-		fromHook?: boolean,
+		fromExtension?: boolean,
 	): string {
 		const entry: CompactionEntry<T> = {
 			type: "compaction",
@@ -1325,13 +1338,13 @@ export class SessionManager {
 			firstKeptEntryId,
 			tokensBefore,
 			details,
-			fromHook,
+			fromExtension,
 		};
 		this._appendEntry(entry);
 		return entry.id;
 	}
 
-	/** Append a custom entry (for hooks) as child of current leaf, then advance leaf. Returns entry id. */
+	/** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
 	appendCustomEntry(customType: string, data?: unknown): string {
 		const entry: CustomEntry = {
 			type: "custom",
@@ -1346,11 +1359,11 @@ export class SessionManager {
 	}
 
 	/**
-	 * Append a custom message entry (for hooks) that participates in LLM context.
+	 * Append a custom message entry (for extensions) that participates in LLM context.
 	 * @param customType Hook identifier for filtering on reload
 	 * @param content Message content (string or TextContent/ImageContent array)
 	 * @param display Whether to show in TUI (true = styled display, false = hidden)
-	 * @param details Optional hook-specific metadata (not sent to LLM)
+	 * @param details Optional extension-specific metadata (not sent to LLM)
 	 * @returns Entry id
 	 */
 	appendCustomMessageEntry<T = unknown>(
@@ -1589,7 +1602,7 @@ export class SessionManager {
 	 * Same as branch(), but also appends a branch_summary entry that captures
 	 * context from the abandoned conversation path.
 	 */
-	branchWithSummary(branchFromId: string | null, summary: string, details?: unknown, fromHook?: boolean): string {
+	branchWithSummary(branchFromId: string | null, summary: string, details?: unknown, fromExtension?: boolean): string {
 		if (branchFromId !== null && !this.byId.has(branchFromId)) {
 			throw new Error(`Entry ${branchFromId} not found`);
 		}
@@ -1602,7 +1615,7 @@ export class SessionManager {
 			fromId: branchFromId ?? "root",
 			summary,
 			details,
-			fromHook,
+			fromExtension,
 		};
 		this._appendEntry(entry);
 		return entry.id;
@@ -1646,9 +1659,11 @@ export class SessionManager {
 		}
 
 		if (this.persist) {
-			appendFileSync(newSessionFile, `${JSON.stringify(header)}\n`);
+			const file = Bun.file(newSessionFile);
+			const writer = file.writer();
+			writer.write(`${JSON.stringify(header)}\n`);
 			for (const entry of pathWithoutLabels) {
-				appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);
+				writer.write(`${JSON.stringify(entry)}\n`);
 			}
 			// Write fresh label entries at the end
 			const lastEntryId = pathWithoutLabels[pathWithoutLabels.length - 1]?.id || null;
@@ -1663,11 +1678,12 @@ export class SessionManager {
 					targetId,
 					label,
 				};
-				appendFileSync(newSessionFile, `${JSON.stringify(labelEntry)}\n`);
+				writer.write(`${JSON.stringify(labelEntry)}\n`);
 				pathEntryIds.add(labelEntry.id);
 				labelEntries.push(labelEntry);
 				parentId = labelEntry.id;
 			}
+			writer.end();
 			this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
 			this.sessionId = newSessionId;
 			this._buildIndex();
@@ -1714,13 +1730,13 @@ export class SessionManager {
 	 */
 	static async open(path: string, sessionDir?: string): Promise<SessionManager> {
 		// Extract cwd from session header if possible, otherwise use process.cwd()
-		const entries = loadEntriesFromFile(path);
+		const entries = await loadEntriesFromFile(path);
 		const header = entries.find((e) => e.type === "session") as SessionHeader | undefined;
 		const cwd = header?.cwd ?? process.cwd();
 		// If no sessionDir provided, derive from file's parent directory
 		const dir = sessionDir ?? resolve(path, "..");
 		const manager = new SessionManager(cwd, dir, true);
-		await manager._initSessionFile(path);
+		manager._initSessionFile(path);
 		return manager;
 	}
 
@@ -1729,12 +1745,12 @@ export class SessionManager {
 	 * @param cwd Working directory
 	 * @param sessionDir Optional session directory. If omitted, uses default (~/.omp/agent/sessions/<encoded-cwd>/).
 	 */
-	static async continueRecent(cwd: string, sessionDir?: string): Promise<SessionManager> {
+	static continueRecent(cwd: string, sessionDir?: string): SessionManager {
 		const dir = sessionDir ?? getDefaultSessionDir(cwd);
 		const mostRecent = findMostRecentSession(dir);
 		const manager = new SessionManager(cwd, dir, true);
 		if (mostRecent) {
-			await manager._initSessionFile(mostRecent);
+			manager._initSessionFile(mostRecent);
 		} else {
 			manager._initNewSession();
 		}
@@ -1758,13 +1774,11 @@ export class SessionManager {
 		const sessions: SessionInfo[] = [];
 
 		try {
-			const files = readdirSync(dir)
-				.filter((f) => f.endsWith(".jsonl"))
-				.map((f) => join(dir, f));
+			const files = Array.from(new Bun.Glob("*.jsonl").scanSync(dir)).map((f) => join(dir, f));
 
 			for (const file of files) {
 				try {
-					const content = readFileSync(file, "utf8");
+					const content = readFileSync(file, "utf-8");
 					const lines = content.trim().split("\n");
 					if (lines.length === 0) continue;
 

package/src/core/settings-manager.ts

@@ -42,6 +42,16 @@ export interface TerminalSettings {
 	showImages?: boolean; // default: true (only relevant if terminal supports images)
 }
 
+export interface ImageSettings {
+	autoResize?: boolean; // default: true (resize images to 2000x2000 max for better model compatibility)
+}
+
+export type NotificationMethod = "bell" | "osc99" | "osc9" | "auto" | "off";
+
+export interface NotificationSettings {
+	onComplete?: NotificationMethod; // default: "auto"
+}
+
 export interface ExaSettings {
 	enabled?: boolean; // default: true (master toggle for all Exa tools)
 	enableSearch?: boolean; // default: true (search, deep, code, crawl)
@@ -81,6 +91,15 @@ export interface TtsrSettings {
 	repeatGap?: number; // default: 10
 }
 
+export interface VoiceSettings {
+	enabled?: boolean; // default: false
+	transcriptionModel?: string; // default: "whisper-1"
+	transcriptionLanguage?: string; // optional language hint (e.g., "en")
+	ttsModel?: string; // default: "gpt-4o-mini-tts"
+	ttsVoice?: string; // default: "alloy"
+	ttsFormat?: "wav" | "mp3" | "opus" | "aac" | "flac"; // default: "wav"
+}
+
 export type StatusLineSegmentId =
 	| "pi"
 	| "model"
@@ -125,7 +144,9 @@ export interface Settings {
 	/** Model roles map: { default: "provider/modelId", small: "provider/modelId", ... } */
 	modelRoles?: Record<string, string>;
 	defaultThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
-	queueMode?: "all" | "one-at-a-time";
+	steeringMode?: "all" | "one-at-a-time";
+	followUpMode?: "all" | "one-at-a-time";
+	queueMode?: "all" | "one-at-a-time"; // legacy
 	interruptMode?: "immediate" | "wait";
 	theme?: string;
 	symbolPreset?: SymbolPreset; // default: uses theme's preset or "unicode"
@@ -135,11 +156,13 @@ export interface Settings {
 	hideThinkingBlock?: boolean;
 	shellPath?: string; // Custom shell path (e.g., for Cygwin users on Windows)
 	collapseChangelog?: boolean; // Show condensed changelog after update (use /changelog for full)
-	hooks?: string[]; // Array of hook file paths
-	customTools?: string[]; // Array of custom tool file paths
+	doubleEscapeAction?: "branch" | "tree"; // Action for double-escape with empty editor (default: "tree")
+	extensions?: string[]; // Array of extension file paths
 	skills?: SkillsSettings;
 	commands?: CommandsSettings;
 	terminal?: TerminalSettings;
+	images?: ImageSettings;
+	notifications?: NotificationSettings;
 	enabledModels?: string[]; // Model patterns for cycling (same format as --models CLI flag)
 	exa?: ExaSettings;
 	bashInterceptor?: BashInterceptorSettings;
@@ -147,6 +170,7 @@ export interface Settings {
 	lsp?: LspSettings;
 	edit?: EditSettings;
 	ttsr?: TtsrSettings;
+	voice?: VoiceSettings;
 	disabledProviders?: string[]; // Discovery provider IDs that are disabled
 	disabledExtensions?: string[]; // Individual extension IDs that are disabled (e.g., "skill:commit")
 	statusLine?: StatusLineSettings; // Status line configuration
@@ -232,13 +256,24 @@ export class SettingsManager {
 		}
 		try {
 			const content = readFileSync(path, "utf-8");
-			return JSON.parse(content);
+			const settings = JSON.parse(content);
+			return SettingsManager.migrateSettings(settings as Record<string, unknown>);
 		} catch (error) {
 			console.error(`Warning: Could not read settings file ${path}: ${error}`);
 			return {};
 		}
 	}
 
+	/** Migrate old settings format to new format */
+	private static migrateSettings(settings: Record<string, unknown>): Settings {
+		// Migrate queueMode -> steeringMode
+		if ("queueMode" in settings && !("steeringMode" in settings)) {
+			settings.steeringMode = settings.queueMode;
+			delete settings.queueMode;
+		}
+		return settings as Settings;
+	}
+
 	private loadProjectSettings(): Settings {
 		if (!this.cwd) return {};
 
@@ -253,7 +288,7 @@ export class SettingsManager {
 			}
 		}
 
-		return merged;
+		return SettingsManager.migrateSettings(merged as Record<string, unknown>);
 	}
 
 	/** Apply additional overrides on top of current settings */
@@ -315,12 +350,21 @@ export class SettingsManager {
 		return { ...this.settings.modelRoles };
 	}
 
-	getQueueMode(): "all" | "one-at-a-time" {
-		return this.settings.queueMode || "one-at-a-time";
+	getSteeringMode(): "all" | "one-at-a-time" {
+		return this.settings.steeringMode || "one-at-a-time";
 	}
 
-	setQueueMode(mode: "all" | "one-at-a-time"): void {
-		this.globalSettings.queueMode = mode;
+	setSteeringMode(mode: "all" | "one-at-a-time"): void {
+		this.globalSettings.steeringMode = mode;
+		this.save();
+	}
+
+	getFollowUpMode(): "all" | "one-at-a-time" {
+		return this.settings.followUpMode || "one-at-a-time";
+	}
+
+	setFollowUpMode(mode: "all" | "one-at-a-time"): void {
+		this.globalSettings.followUpMode = mode;
 		this.save();
 	}
 
@@ -441,21 +485,12 @@ export class SettingsManager {
 		this.save();
 	}
 
-	getHookPaths(): string[] {
-		return [...(this.settings.hooks ?? [])];
-	}
-
-	setHookPaths(paths: string[]): void {
-		this.globalSettings.hooks = paths;
-		this.save();
-	}
-
-	getCustomToolPaths(): string[] {
-		return [...(this.settings.customTools ?? [])];
+	getExtensionPaths(): string[] {
+		return [...(this.settings.extensions ?? [])];
 	}
 
-	setCustomToolPaths(paths: string[]): void {
-		this.globalSettings.customTools = paths;
+	setExtensionPaths(paths: string[]): void {
+		this.globalSettings.extensions = paths;
 		this.save();
 	}
 
@@ -504,6 +539,30 @@ export class SettingsManager {
 		this.save();
 	}
 
+	getNotificationOnComplete(): NotificationMethod {
+		return this.settings.notifications?.onComplete ?? "auto";
+	}
+
+	setNotificationOnComplete(method: NotificationMethod): void {
+		if (!this.globalSettings.notifications) {
+			this.globalSettings.notifications = {};
+		}
+		this.globalSettings.notifications.onComplete = method;
+		this.save();
+	}
+
+	getImageAutoResize(): boolean {
+		return this.settings.images?.autoResize ?? true;
+	}
+
+	setImageAutoResize(enabled: boolean): void {
+		if (!this.globalSettings.images) {
+			this.globalSettings.images = {};
+		}
+		this.globalSettings.images.autoResize = enabled;
+		this.save();
+	}
+
 	getEnabledModels(): string[] | undefined {
 		return this.settings.enabledModels;
 	}
@@ -737,6 +796,34 @@ export class SettingsManager {
 		this.save();
 	}
 
+	getVoiceSettings(): Required<VoiceSettings> {
+		return {
+			enabled: this.settings.voice?.enabled ?? false,
+			transcriptionModel: this.settings.voice?.transcriptionModel ?? "whisper-1",
+			transcriptionLanguage: this.settings.voice?.transcriptionLanguage ?? "",
+			ttsModel: this.settings.voice?.ttsModel ?? "tts-1",
+			ttsVoice: this.settings.voice?.ttsVoice ?? "alloy",
+			ttsFormat: this.settings.voice?.ttsFormat ?? "wav",
+		};
+	}
+
+	setVoiceSettings(settings: VoiceSettings): void {
+		this.globalSettings.voice = { ...this.globalSettings.voice, ...settings };
+		this.save();
+	}
+
+	getVoiceEnabled(): boolean {
+		return this.settings.voice?.enabled ?? false;
+	}
+
+	setVoiceEnabled(enabled: boolean): void {
+		if (!this.globalSettings.voice) {
+			this.globalSettings.voice = {};
+		}
+		this.globalSettings.voice.enabled = enabled;
+		this.save();
+	}
+
 	// ═══════════════════════════════════════════════════════════════════════════
 	// Status Line Settings
 	// ═══════════════════════════════════════════════════════════════════════════
@@ -857,4 +944,13 @@ export class SettingsManager {
 		this.globalSettings.statusLine.showHookStatus = show;
 		this.save();
 	}
+
+	getDoubleEscapeAction(): "branch" | "tree" {
+		return this.settings.doubleEscapeAction ?? "tree";
+	}
+
+	setDoubleEscapeAction(action: "branch" | "tree"): void {
+		this.globalSettings.doubleEscapeAction = action;
+		this.save();
+	}
 }

package/src/core/system-prompt.ts

@@ -77,9 +77,12 @@ const toolDescriptions: Record<ToolName, string> = {
 	ls: "List directory contents",
 	lsp: "PREFERRED for semantic code queries: go-to-definition, find-all-references, hover (type info), call hierarchy. Returns precise, deterministic results. Use BEFORE grep for symbol lookups.",
 	notebook: "Edit Jupyter notebook cells",
+	output: "Output structured data to the user (bypasses tool result formatting)",
 	task: "Spawn a sub-agent to handle complex tasks",
 	web_fetch: "Fetch and render URLs into clean text for LLM consumption",
 	web_search: "Search the web for information",
+	report_finding: "Report a finding during code review",
+	submit_review: "Submit the final code review with all findings",
 };
 
 /**
@@ -231,6 +234,8 @@ export interface BuildSystemPromptOptions {
 	customPrompt?: string;
 	/** Tools to include in prompt. Default: [read, bash, edit, write] */
 	selectedTools?: ToolName[];
+	/** Extra tool descriptions to include in prompt (non built-in tools). */
+	extraToolDescriptions?: Array<{ name: string; description: string }>;
 	/** Text to append to system prompt. */
 	appendSystemPrompt?: string;
 	/** Skills settings for discovery. */
@@ -250,6 +255,7 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 	const {
 		customPrompt,
 		selectedTools,
+		extraToolDescriptions = [],
 		appendSystemPrompt,
 		skillsSettings,
 		cwd,
@@ -304,6 +310,12 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 			}
 		}
 
+		// Append custom tool descriptions if provided
+		if (extraToolDescriptions.length > 0) {
+			prompt += "\n\n# Additional Tools\n\n";
+			prompt += extraToolDescriptions.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
+		}
+
 		// Append git context if in a git repo
 		const gitContext = loadGitContext(resolvedCwd);
 		if (gitContext) {
@@ -335,7 +347,12 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 
 	// Build tools list based on selected tools
 	const tools = selectedTools || (["read", "bash", "edit", "write"] as ToolName[]);
-	const toolsList = tools.map((t) => `- ${t}: ${toolDescriptions[t]}`).join("\n");
+	const builtInToolsList = tools.map((t) => `- ${t}: ${toolDescriptions[t]}`).join("\n");
+	const extraToolsList =
+		extraToolDescriptions.length > 0
+			? extraToolDescriptions.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n")
+			: "";
+	const toolsList = [builtInToolsList, extraToolsList].filter(Boolean).join("\n");
 
 	// Generate anti-bash rules (returns null if not applicable)
 	const antiBashSection = generateAntiBashRules(tools);
@@ -413,6 +430,12 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		}
 	}
 
+	// Append custom tool descriptions if provided
+	if (extraToolDescriptions.length > 0) {
+		prompt += "\n\n# Additional Tools\n\n";
+		prompt += extraToolDescriptions.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
+	}
+
 	// Append git context if in a git repo
 	const gitContext = loadGitContext(resolvedCwd);
 	if (gitContext) {

package/src/core/terminal-notify.ts

@@ -0,0 +1,37 @@
+export type NotificationProtocol = "bell" | "osc99" | "osc9";
+
+export function detectNotificationProtocol(): NotificationProtocol {
+	const termProgram = process.env.TERM_PROGRAM?.toLowerCase() || "";
+	const term = process.env.TERM?.toLowerCase() || "";
+
+	if (process.env.KITTY_WINDOW_ID || termProgram === "kitty") {
+		return "osc99";
+	}
+
+	if (process.env.GHOSTTY_RESOURCES_DIR || termProgram === "ghostty" || term.includes("ghostty")) {
+		return "osc9";
+	}
+
+	if (process.env.WEZTERM_PANE || termProgram === "wezterm") {
+		return "osc9";
+	}
+
+	if (process.env.ITERM_SESSION_ID || termProgram === "iterm.app") {
+		return "osc9";
+	}
+
+	return "bell";
+}
+
+export function sendNotification(protocol: NotificationProtocol, message: string): void {
+	const payload =
+		protocol === "osc99" ? `\x1b]99;;${message}\x1b\\` : protocol === "osc9" ? `\x1b]9;${message}\x1b\\` : "\x07";
+
+	process.stdout.write(payload);
+}
+
+export function isNotificationSuppressed(): boolean {
+	const value = process.env.OMP_NOTIFICATIONS?.trim().toLowerCase();
+	if (!value) return false;
+	return value === "off" || value === "0" || value === "false";
+}