pi-smart-voice-notify 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.2.3] - 2026-03-13
+
+### Added
+- Integration with `pi-permission-system:permission-request` event channel for permission request notifications
+- Automatic cancellation of permission reminders when approval/denial is received from the permission system
+- Deduplication to prevent duplicate notifications when permission system events precede tool_call events
+- New test coverage for permission system event integration
+
+### Changed
+- Refactored to use shared `toRecord` utility from `pi-permission-system`, removing duplicate implementation
+
+## [0.2.2] - 2026-03-12
+
+### Changed
+- Refactored to use shared `toRecord` utility, removing duplicate implementation
+- Consolidated exports and simplified `index.ts`
+
 ## [0.2.0] - 2026-03-07
 
 ### Added

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 MasuRii
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-voice-notify",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/src/ai-messages.ts

@@ -1,3 +1,4 @@
+import { normalizeFloat } from "./config-store.ts";
 import { getErrorMessage } from "./logging.ts";
 
 export const AI_EVENT_TYPES = [
@@ -134,13 +135,6 @@ function normalizePositiveInt(value: number, fallback: number, min: number, max:
 	return Math.min(max, Math.max(min, Math.round(value)));
 }
 
-function normalizeFloat(value: number, fallback: number, min: number, max: number): number {
-	if (!Number.isFinite(value)) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, value));
-}
-
 function normalizeConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageConfig {
 	return {
 		...DEFAULT_AI_MESSAGE_CONFIG,

package/src/config-store.ts

@@ -265,7 +265,7 @@ export const DEFAULT_CONFIG: VoiceNotifyConfig = {
 	debugLog: false,
 };
 
-function toRecord(value: unknown): Record<string, unknown> {
+export function toRecord(value: unknown): Record<string, unknown> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
 		return {};
 	}
@@ -325,6 +325,13 @@ export function clampNumber(value: unknown, fallback: number, min: number, max:
 	return Math.min(max, Math.max(min, numeric));
 }
 
+export function normalizeFloat(value: number, fallback: number, min: number, max: number): number {
+	if (!Number.isFinite(value)) {
+		return fallback;
+	}
+	return Math.min(max, Math.max(min, value));
+}
+
 function boolOrDefault(value: unknown, fallback: boolean): boolean {
 	if (typeof value === "boolean") {
 		return value;

package/src/desktop-notify.ts

@@ -1,177 +1,171 @@
-type NotificationType = "idle" | "permission" | "question" | "error";
-
-type LinuxUrgency = "low" | "normal" | "critical";
-
-interface DesktopNotificationSupport {
-	supported: boolean;
-	reason?: string;
-}
-
-interface DesktopNotificationRequest {
-	type: NotificationType;
-	message: string;
-	timeoutSeconds: number;
-	debugLog?: boolean;
-}
-
-export interface DesktopNotificationResult {
-	success: boolean;
-	platform: NodeJS.Platform;
-	unsupported?: boolean;
-	error?: string;
-}
-
-interface NotifierLike {
-	notify(
-		options: Record<string, unknown>,
-		callback?: (error: Error | null, response?: unknown, metadata?: unknown) => void,
-	): void;
-}
-
-const TITLES: Record<NotificationType, string> = {
-	idle: "✅ Pi - Task Complete",
-	permission: "⚠️ Pi - Permission Required",
-	question: "❓ Pi - Input Needed",
-	error: "❌ Pi - Error",
-};
-
-const LINUX_URGENCY: Record<NotificationType, LinuxUrgency> = {
-	idle: "normal",
-	permission: "critical",
-	question: "normal",
-	error: "critical",
-};
-
-let notifierPromise: Promise<NotifierLike | null> | null = null;
-
-function getErrorMessage(error: unknown): string {
-	if (error instanceof Error) {
-		return error.message;
-	}
-	return String(error);
-}
-
-function clampTimeoutSeconds(value: number): number {
-	if (!Number.isFinite(value)) {
-		return 5;
-	}
-	return Math.min(60, Math.max(1, Math.trunc(value)));
-}
-
-export function checkDesktopNotificationSupport(platform = process.platform): DesktopNotificationSupport {
-	switch (platform) {
-		case "win32":
-		case "darwin":
-		case "linux":
-			return { supported: true };
-		default:
-			return {
-				supported: false,
-				reason: `Desktop notifications are unsupported on platform '${platform}'.`,
-			};
-	}
-}
-
-function buildNotifierOptions(request: DesktopNotificationRequest): Record<string, unknown> {
-	const timeoutSeconds = clampTimeoutSeconds(request.timeoutSeconds);
-	const baseOptions: Record<string, unknown> = {
-		title: TITLES[request.type],
-		message: request.message,
-		wait: false,
-		timeout: timeoutSeconds,
-	};
-
-	if (process.platform === "linux") {
-		baseOptions.urgency = LINUX_URGENCY[request.type];
-		baseOptions["app-name"] = "Pi Smart Voice Notify";
-	}
-
-	if (process.platform === "win32") {
-		baseOptions.appID = "PiSmartVoiceNotify";
-	}
-
-	if (process.platform === "darwin") {
-		baseOptions.subtitle = "Smart Voice Notify";
-	}
-
-	return baseOptions;
-}
-
-async function getNotifier(): Promise<NotifierLike | null> {
-	if (!notifierPromise) {
-		notifierPromise = import("node-notifier")
-			.then((module) => {
-				const candidate = (module.default ?? module) as { notify?: NotifierLike["notify"] };
-				if (typeof candidate.notify !== "function") {
-					return null;
-				}
-				return { notify: candidate.notify };
-			})
-			.catch(() => null);
-	}
-	return notifierPromise;
-}
-
-export async function sendDesktopNotification(request: DesktopNotificationRequest): Promise<DesktopNotificationResult> {
-	const support = checkDesktopNotificationSupport();
-	if (!support.supported) {
-		return {
-			success: false,
-			platform: process.platform,
-			unsupported: true,
-			error: support.reason,
-		};
-	}
-
-	const notifier = await getNotifier();
-	if (!notifier) {
-		return {
-			success: false,
-			platform: process.platform,
-			error: "node-notifier is not available. Install it in this extension directory.",
-		};
-	}
-
-	const notifyOptions = buildNotifierOptions(request);
-	const timeoutSeconds = clampTimeoutSeconds(request.timeoutSeconds);
-	const callbackTimeoutMs = Math.min(1200, Math.max(250, timeoutSeconds * 1000 + 250));
-
-	return new Promise<DesktopNotificationResult>((resolve) => {
-		let settled = false;
-		const settle = (result: DesktopNotificationResult): void => {
-			if (settled) {
-				return;
-			}
-			settled = true;
-			clearTimeout(safetyTimeout);
-			resolve(result);
-		};
-
-		const safetyTimeout = setTimeout(() => {
-			if (request.debugLog) {
-				// Callback can be dropped by some notifier backends; treat as queued/success.
-			}
-			settle({ success: true, platform: process.platform });
-		}, callbackTimeoutMs);
-
-		try {
-			notifier.notify(notifyOptions, (error) => {
-				if (error) {
-					settle({
-						success: false,
-						platform: process.platform,
-						error: getErrorMessage(error),
-					});
-					return;
-				}
-				settle({ success: true, platform: process.platform });
-			});
-		} catch (error) {
-			settle({
-				success: false,
-				platform: process.platform,
-				error: getErrorMessage(error),
-			});
-		}
-	});
-}
+import type { NotificationType } from "./types.ts";
+import { getErrorMessage } from "./logging.ts";
+
+type LinuxUrgency = "low" | "normal" | "critical";
+
+interface DesktopNotificationSupport {
+	supported: boolean;
+	reason?: string;
+}
+
+interface DesktopNotificationRequest {
+	type: NotificationType;
+	message: string;
+	timeoutSeconds: number;
+	debugLog?: boolean;
+}
+
+export interface DesktopNotificationResult {
+	success: boolean;
+	platform: NodeJS.Platform;
+	unsupported?: boolean;
+	error?: string;
+}
+
+interface NotifierLike {
+	notify(
+		options: Record<string, unknown>,
+		callback?: (error: Error | null, response?: unknown, metadata?: unknown) => void,
+	): void;
+}
+
+const TITLES: Record<NotificationType, string> = {
+	idle: "✅ Pi - Task Complete",
+	permission: "⚠️ Pi - Permission Required",
+	question: "❓ Pi - Input Needed",
+	error: "❌ Pi - Error",
+};
+
+const LINUX_URGENCY: Record<NotificationType, LinuxUrgency> = {
+	idle: "normal",
+	permission: "critical",
+	question: "normal",
+	error: "critical",
+};
+
+let notifierPromise: Promise<NotifierLike | null> | null = null;
+
+function clampTimeoutSeconds(value: number): number {
+	if (!Number.isFinite(value)) {
+		return 5;
+	}
+	return Math.min(60, Math.max(1, Math.trunc(value)));
+}
+
+export function checkDesktopNotificationSupport(platform = process.platform): DesktopNotificationSupport {
+	switch (platform) {
+		case "win32":
+		case "darwin":
+		case "linux":
+			return { supported: true };
+		default:
+			return {
+				supported: false,
+				reason: `Desktop notifications are unsupported on platform '${platform}'.`,
+			};
+	}
+}
+
+function buildNotifierOptions(request: DesktopNotificationRequest): Record<string, unknown> {
+	const timeoutSeconds = clampTimeoutSeconds(request.timeoutSeconds);
+	const baseOptions: Record<string, unknown> = {
+		title: TITLES[request.type],
+		message: request.message,
+		wait: false,
+		timeout: timeoutSeconds,
+	};
+
+	if (process.platform === "linux") {
+		baseOptions.urgency = LINUX_URGENCY[request.type];
+		baseOptions["app-name"] = "Pi Smart Voice Notify";
+	}
+
+	if (process.platform === "win32") {
+		baseOptions.appID = "PiSmartVoiceNotify";
+	}
+
+	if (process.platform === "darwin") {
+		baseOptions.subtitle = "Smart Voice Notify";
+	}
+
+	return baseOptions;
+}
+
+async function getNotifier(): Promise<NotifierLike | null> {
+	if (!notifierPromise) {
+		notifierPromise = import("node-notifier")
+			.then((module) => {
+				const candidate = (module.default ?? module) as { notify?: NotifierLike["notify"] };
+				if (typeof candidate.notify !== "function") {
+					return null;
+				}
+				return { notify: candidate.notify };
+			})
+			.catch(() => null);
+	}
+	return notifierPromise;
+}
+
+export async function sendDesktopNotification(request: DesktopNotificationRequest): Promise<DesktopNotificationResult> {
+	const support = checkDesktopNotificationSupport();
+	if (!support.supported) {
+		return {
+			success: false,
+			platform: process.platform,
+			unsupported: true,
+			error: support.reason,
+		};
+	}
+
+	const notifier = await getNotifier();
+	if (!notifier) {
+		return {
+			success: false,
+			platform: process.platform,
+			error: "node-notifier is not available. Install it in this extension directory.",
+		};
+	}
+
+	const notifyOptions = buildNotifierOptions(request);
+	const timeoutSeconds = clampTimeoutSeconds(request.timeoutSeconds);
+	const callbackTimeoutMs = Math.min(1200, Math.max(250, timeoutSeconds * 1000 + 250));
+
+	return new Promise<DesktopNotificationResult>((resolve) => {
+		let settled = false;
+		const settle = (result: DesktopNotificationResult): void => {
+			if (settled) {
+				return;
+			}
+			settled = true;
+			clearTimeout(safetyTimeout);
+			resolve(result);
+		};
+
+		const safetyTimeout = setTimeout(() => {
+			if (request.debugLog) {
+				// Callback can be dropped by some notifier backends; treat as queued/success.
+			}
+			settle({ success: true, platform: process.platform });
+		}, callbackTimeoutMs);
+
+		try {
+			notifier.notify(notifyOptions, (error) => {
+				if (error) {
+					settle({
+						success: false,
+						platform: process.platform,
+						error: getErrorMessage(error),
+					});
+					return;
+				}
+				settle({ success: true, platform: process.platform });
+			});
+		} catch (error) {
+			settle({
+				success: false,
+				platform: process.platform,
+				error: getErrorMessage(error),
+			});
+		}
+	});
+}

package/src/focus-detect.ts

@@ -1,5 +1,6 @@
 import { exec, type ExecOptionsWithStringEncoding } from "node:child_process";
 import { promisify } from "node:util";
+import { getErrorMessage } from "./logging.ts";
 
 export type LinuxSessionType = "x11" | "wayland" | "unknown";
 
@@ -100,13 +101,6 @@ function emitLog(
 	console.warn("[focus-detect]", message, details);
 }
 
-function errorToString(error: unknown): string {
-	if (error instanceof Error) {
-		return error.message;
-	}
-	return String(error);
-}
-
 export function detectLinuxSessionType(env: NodeJS.ProcessEnv = process.env): LinuxSessionType {
 	const explicit = env.XDG_SESSION_TYPE?.toLowerCase().trim();
 	if (explicit === "x11" || explicit === "wayland") {
@@ -170,7 +164,7 @@ async function runCommand(
 	} catch (error) {
 		emitLog("error", `${label}: command failed`, options, {
 			command,
-			error: errorToString(error),
+			error: getErrorMessage(error),
 		});
 		return null;
 	}
@@ -252,7 +246,7 @@ async function getFocusedWindowWaylandSway(options: FocusDetectOptions): Promise
 		);
 	} catch (error) {
 		emitLog("error", "wayland.sway failed to parse sway tree", options, {
-			error: errorToString(error),
+			error: getErrorMessage(error),
 		});
 		return null;
 	}

package/src/index.test.ts

@@ -26,6 +26,9 @@ type PermissionForwardingWatcherController = ReturnType<PermissionForwardingWatc
 type ForwardedPermissionRequestEvent = Parameters<PermissionForwardingWatcherOptions["onRequest"]>[0];
 type ForwardedPermissionResolutionEvent = Parameters<PermissionForwardingWatcherOptions["onResolve"]>[0];
 type PermissionForwardingWatcherConfig = Parameters<PermissionForwardingWatcherController["start"]>[0];
+type EventBusHandler = (payload: unknown) => void;
+
+const PERMISSION_SYSTEM_EVENT_CHANNEL = "pi-permission-system:permission-request";
 
 const EMPTY_AVAILABILITY: TTSAvailability = {
 	"espeak-ng": false,
@@ -35,9 +38,31 @@ const EMPTY_AVAILABILITY: TTSAvailability = {
 	sapi: false,
 };
 
+class FakeEventBus {
+	private readonly handlers = new Map<string, EventBusHandler[]>();
+
+	public on(channel: string, handler: EventBusHandler): () => void {
+		const existing = this.handlers.get(channel) ?? [];
+		existing.push(handler);
+		this.handlers.set(channel, existing);
+		return () => {
+			const current = this.handlers.get(channel) ?? [];
+			this.handlers.set(channel, current.filter((entry) => entry !== handler));
+		};
+	}
+
+	public emit(channel: string, payload: unknown): void {
+		for (const handler of this.handlers.get(channel) ?? []) {
+			handler(payload);
+		}
+	}
+}
+
 class FakePi {
 	private readonly handlers = new Map<string, EventHandler[]>();
 
+	public readonly events = new FakeEventBus();
+
 	public on(eventName: string, handler: EventHandler): void {
 		const existing = this.handlers.get(eventName) ?? [];
 		existing.push(handler);
@@ -223,6 +248,32 @@ function permissionEvent(toolCallId: string): { block: boolean; reason: string;
 	};
 }
 
+function permissionSystemEvent(
+	state: "waiting" | "approved" | "denied",
+	requestId: string,
+	overrides: Partial<{
+		source: "tool_call" | "skill_input" | "skill_read";
+		message: string;
+		toolCallId: string;
+		toolName: string;
+		skillName: string;
+		path: string;
+		agentName: string | null;
+	}> = {},
+): Record<string, unknown> {
+	return {
+		requestId,
+		state,
+		source: overrides.source ?? "tool_call",
+		message: overrides.message ?? "Current agent requested tool 'write'. Allow this call?",
+		toolCallId: overrides.toolCallId,
+		toolName: overrides.toolName,
+		skillName: overrides.skillName,
+		path: overrides.path,
+		agentName: overrides.agentName ?? null,
+	};
+}
+
 function forwardedPermissionRequest(
 	requestId: string,
 	requesterAgentName = "Delegate Alpha",
@@ -287,6 +338,62 @@ async function tickAndFlush(milliseconds: number): Promise<void> {
 	await flushAsyncWork();
 }
 
+test("permission-system waiting events trigger a permission notification and cancel on resolution", async (t) => {
+	disableFocusDetection(t);
+	useMockClock(t);
+
+	const { ctx, pi, ttsCalls } = createHarness();
+
+	await pi.emit("session_start", {}, ctx);
+	await flushAsyncWork();
+	pi.events.emit(
+		PERMISSION_SYSTEM_EVENT_CHANNEL,
+		permissionSystemEvent("waiting", "permission-wait", {
+			toolCallId: "call-wait",
+			toolName: "write_file",
+		}),
+	);
+	await flushAsyncWork();
+
+	assert.equal(immediateNotificationCalls(ttsCalls).length, 1);
+
+	pi.events.emit(
+		PERMISSION_SYSTEM_EVENT_CHANNEL,
+		permissionSystemEvent("approved", "permission-wait", {
+			toolCallId: "call-wait",
+			toolName: "write_file",
+		}),
+	);
+	await flushAsyncWork();
+	await tickAndFlush(1_000);
+
+	assert.equal(countReminderCalls(ttsCalls), 0);
+});
+
+test("permission-system waiting events do not duplicate a later blocked tool_call notification", async (t) => {
+	disableFocusDetection(t);
+	useMockClock(t);
+
+	const { ctx, pi, ttsCalls } = createHarness();
+
+	await pi.emit("session_start", {}, ctx);
+	await flushAsyncWork();
+	pi.events.emit(
+		PERMISSION_SYSTEM_EVENT_CHANNEL,
+		permissionSystemEvent("waiting", "permission-dedupe", {
+			toolCallId: "call-dedupe",
+			toolName: "write_file",
+		}),
+	);
+	await flushAsyncWork();
+	assert.equal(immediateNotificationCalls(ttsCalls).length, 1);
+
+	await pi.emit("tool_call", permissionEvent("call-dedupe"), ctx);
+	await flushAsyncWork();
+
+	assert.equal(immediateNotificationCalls(ttsCalls).length, 1);
+});
+
 test("tool_execution_start only cancels the resolved permission reminder flow", async (t) => {
 	disableFocusDetection(t);
 	useMockClock(t);

package/src/index.ts

@@ -25,6 +25,7 @@ import {
 	SOUND_LOOPS,
 	STATUS_KEY,
 	summarizeConfig,
+	toRecord,
 	TTS_ENGINE_VALUES,
 	writeConfigToDisk,
 	boolValue,
@@ -102,13 +103,6 @@ function classifyToolResult(
 	return "error";
 }
 
-function toRecord(value: unknown): Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return {};
-	}
-	return value as Record<string, unknown>;
-}
-
 function readBlockedReason(value: unknown): string | null {
 	const record = toRecord(value);
 	const blockValue = record.block;
@@ -252,6 +246,67 @@ function forwardedPermissionReminderKey(requestId: string): ReminderKey {
 		: defaultReminderKey("permission");
 }
 
+const PERMISSION_SYSTEM_EVENT_CHANNEL = "pi-permission-system:permission-request";
+type PermissionSystemEventState = "waiting" | "approved" | "denied";
+type PermissionSystemEventSource = "tool_call" | "skill_input" | "skill_read";
+
+interface PermissionSystemEvent {
+	requestId: string;
+	state: PermissionSystemEventState;
+	source: PermissionSystemEventSource;
+	message: string;
+	toolCallId?: string;
+	toolName?: string;
+	skillName?: string;
+	path?: string;
+	agentName?: string | null;
+}
+
+function normalizeOptionalString(value: unknown): string | undefined {
+	if (typeof value !== "string") {
+		return undefined;
+	}
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function readPermissionSystemEvent(value: unknown): PermissionSystemEvent | null {
+	const record = toRecord(value);
+	const requestId = normalizeOptionalString(record.requestId);
+	const state = normalizeOptionalString(record.state);
+	const source = normalizeOptionalString(record.source);
+	const message = normalizeOptionalString(record.message);
+	if (!requestId || !message) {
+		return null;
+	}
+	if (state !== "waiting" && state !== "approved" && state !== "denied") {
+		return null;
+	}
+	if (source !== "tool_call" && source !== "skill_input" && source !== "skill_read") {
+		return null;
+	}
+
+	return {
+		requestId,
+		state,
+		source,
+		message,
+		toolCallId: normalizeOptionalString(record.toolCallId),
+		toolName: normalizeOptionalString(record.toolName),
+		skillName: normalizeOptionalString(record.skillName),
+		path: normalizeOptionalString(record.path),
+		agentName: typeof record.agentName === "string" ? record.agentName : null,
+	};
+}
+
+function permissionSystemReminderKey(event: PermissionSystemEvent): ReminderKey {
+	if (event.toolCallId) {
+		return permissionReminderKey(event.toolCallId);
+	}
+
+	return `permission:request:${event.requestId}`;
+}
+
 export default function smartVoiceNotifyExtension(
 	pi: ExtensionAPI,
 	dependencies: SmartVoiceNotifyDependencies = {},
@@ -1027,6 +1082,57 @@ export default function smartVoiceNotifyExtension(
 		);
 	};
 
+	pi.events.on(PERMISSION_SYSTEM_EVENT_CHANNEL, (payload: unknown) => {
+		const event = readPermissionSystemEvent(payload);
+		if (!event) {
+			return;
+		}
+		if (!config.enabled || !config.enablePermissionNotification) {
+			return;
+		}
+		if (!activeSessionContext) {
+			logger.debug("permission_system.notification_skipped", {
+				reason: "missing_session_context",
+				requestId: event.requestId,
+				state: event.state,
+				source: event.source,
+			});
+			return;
+		}
+
+		const reminderKey = permissionSystemReminderKey(event);
+		if (event.state === "waiting") {
+			if (event.toolCallId) {
+				pendingPermissionToolCallIds.add(event.toolCallId);
+				rememberScopedToolCallId(event.toolCallId, blockedPermissionToolCallIds);
+			}
+			logger.debug("permission_system.wait_detected", {
+				requestId: event.requestId,
+				toolCallId: event.toolCallId ?? null,
+				toolName: event.toolName ?? null,
+				skillName: event.skillName ?? null,
+				source: event.source,
+			});
+			triggerNotification("permission", activeSessionContext, {
+				reason: event.message,
+				reminderKey,
+			});
+			return;
+		}
+
+		if (event.toolCallId) {
+			pendingPermissionToolCallIds.delete(event.toolCallId);
+		}
+		cancelReminderActivityForKey(reminderKey, "permission_system_wait_resolved", {
+			requestId: event.requestId,
+			toolCallId: event.toolCallId ?? null,
+			toolName: event.toolName ?? null,
+			skillName: event.skillName ?? null,
+			state: event.state,
+			source: event.source,
+		});
+	});
+
 	const applySetting = (draft: VoiceNotifyConfig, id: string, value: string): void => {
 		switch (id) {
 			case "enabled":

package/src/logging.ts

@@ -1,73 +1,73 @@
-import { appendFileSync } from "node:fs";
-
-export function getErrorMessage(error: unknown): string {
-	if (error instanceof Error) {
-		return error.message;
-	}
-	return String(error);
-}
-
-function safeJsonStringify(value: unknown): string {
-	const seen = new WeakSet<object>();
-	return JSON.stringify(value, (_key, currentValue) => {
-		if (currentValue instanceof Error) {
-			return {
-				name: currentValue.name,
-				message: currentValue.message,
-				stack: currentValue.stack,
-			};
-		}
-		if (typeof currentValue === "bigint") {
-			return currentValue.toString();
-		}
-		if (typeof currentValue === "object" && currentValue !== null) {
-			if (seen.has(currentValue)) {
-				return "[Circular]";
-			}
-			seen.add(currentValue);
-		}
-		return currentValue;
-	});
-}
-
-interface LoggerOptions {
-	extensionId: string;
-	debugLogPath: string;
-	isDebugEnabled: () => boolean;
-	ensureDebugDirectory: () => void;
-}
-
-export interface ExtensionLogger {
-	debug: (event: string, details?: Record<string, unknown>) => void;
-	error: (error: unknown) => void;
-}
-
-export function createExtensionLogger(options: LoggerOptions): ExtensionLogger {
-	const { extensionId, debugLogPath, isDebugEnabled, ensureDebugDirectory } = options;
-
-	const debug = (event: string, details: Record<string, unknown> = {}): void => {
-		if (!isDebugEnabled()) {
-			return;
-		}
-
-		try {
-			ensureDebugDirectory();
-			const line = safeJsonStringify({
-				timestamp: new Date().toISOString(),
-				extension: extensionId,
-				event,
-				...details,
-			});
-			appendFileSync(debugLogPath, `${line}\n`, "utf-8");
-		} catch (error) {
-			console.error(`[${extensionId}] Failed to write debug log: ${getErrorMessage(error)}`);
-		}
-	};
-
-	const error = (cause: unknown): void => {
-		debug("runtime.error", { error: cause });
-		console.error(`[${extensionId}] ${getErrorMessage(cause)}`);
-	};
-
-	return { debug, error };
-}
+import { appendFileSync } from "node:fs";
+
+export function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) {
+		return error.message;
+	}
+	return String(error);
+}
+
+function safeJsonStringify(value: unknown): string {
+	const seen = new WeakSet<object>();
+	return JSON.stringify(value, (_key, currentValue) => {
+		if (currentValue instanceof Error) {
+			return {
+				name: currentValue.name,
+				message: currentValue.message,
+				stack: currentValue.stack,
+			};
+		}
+		if (typeof currentValue === "bigint") {
+			return currentValue.toString();
+		}
+		if (typeof currentValue === "object" && currentValue !== null) {
+			if (seen.has(currentValue)) {
+				return "[Circular]";
+			}
+			seen.add(currentValue);
+		}
+		return currentValue;
+	});
+}
+
+interface LoggerOptions {
+	extensionId: string;
+	debugLogPath: string;
+	isDebugEnabled: () => boolean;
+	ensureDebugDirectory: () => void;
+}
+
+export interface ExtensionLogger {
+	debug: (event: string, details?: Record<string, unknown>) => void;
+	error: (error: unknown) => void;
+}
+
+export function createExtensionLogger(options: LoggerOptions): ExtensionLogger {
+	const { extensionId, debugLogPath, isDebugEnabled, ensureDebugDirectory } = options;
+
+	const debug = (event: string, details: Record<string, unknown> = {}): void => {
+		if (!isDebugEnabled()) {
+			return;
+		}
+
+		try {
+			ensureDebugDirectory();
+			const line = safeJsonStringify({
+				timestamp: new Date().toISOString(),
+				extension: extensionId,
+				event,
+				...details,
+			});
+			appendFileSync(debugLogPath, `${line}\n`, "utf-8");
+		} catch (error) {
+			console.error(`[${extensionId}] Failed to write debug log: ${getErrorMessage(error)}`);
+		}
+	};
+
+	const error = (cause: unknown): void => {
+		debug("runtime.error", { error: cause });
+		console.error(`[${extensionId}] ${getErrorMessage(cause)}`);
+	};
+
+	return { debug, error };
+}

package/src/per-project-sound.ts

@@ -14,7 +14,7 @@ const PROJECT_MARKERS = [
 	".pi",
 ] as const;
 
-const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".ogg", ".m4a", ".flac"]);
+export const AUDIO_EXTENSIONS = new Set([".mp3", ".wav", ".ogg", ".m4a", ".flac"]);
 
 export const PROJECT_SOUND_CATEGORIES = ["notification", "alert", "success", "error", "reminder"] as const;
 
@@ -49,11 +49,11 @@ interface ProjectSoundsManifest {
 let activeProjectRoot: string | null = null;
 const projectSoundCache = new Map<string, ProjectSoundContext | null>();
 
-function noop(): void {
+export function noop(): void {
 	// no-op
 }
 
-async function pathExists(pathValue: string): Promise<boolean> {
+export async function pathExists(pathValue: string): Promise<boolean> {
 	try {
 		await access(pathValue, fsConstants.F_OK);
 		return true;
@@ -62,7 +62,7 @@ async function pathExists(pathValue: string): Promise<boolean> {
 	}
 }
 
-async function isDirectory(pathValue: string): Promise<boolean> {
+export async function isDirectory(pathValue: string): Promise<boolean> {
 	try {
 		const stats = await stat(pathValue);
 		return stats.isDirectory();
@@ -71,7 +71,7 @@ async function isDirectory(pathValue: string): Promise<boolean> {
 	}
 }
 
-async function isReadableAudioFile(pathValue: string): Promise<boolean> {
+export async function isReadableAudioFile(pathValue: string): Promise<boolean> {
 	if (!AUDIO_EXTENSIONS.has(extname(pathValue).toLowerCase())) {
 		return false;
 	}
@@ -88,7 +88,7 @@ async function isReadableAudioFile(pathValue: string): Promise<boolean> {
 	}
 }
 
-async function listAudioFiles(directory: string): Promise<string[]> {
+export async function listAudioFiles(directory: string): Promise<string[]> {
 	if (!(await isDirectory(directory))) {
 		return [];
 	}
@@ -110,16 +110,16 @@ async function listAudioFiles(directory: string): Promise<string[]> {
 	return files;
 }
 
-function uniquePaths(paths: string[]): string[] {
+export function uniquePaths(paths: string[]): string[] {
 	return [...new Set(paths.map((entry) => resolve(entry)))];
 }
 
-function normalizeVolume(value: number | undefined): number | undefined {
+export function normalizeVolume(value: number | undefined | null): number | null {
 	if (typeof value !== "number" || Number.isNaN(value)) {
-		return undefined;
+		return null;
 	}
 	const clamped = Math.max(0, Math.min(100, Math.round(value)));
-	return Number.isFinite(clamped) ? clamped : undefined;
+	return Number.isFinite(clamped) ? clamped : null;
 }
 
 async function hasProjectMarker(directory: string): Promise<boolean> {
@@ -240,7 +240,7 @@ async function resolveVolumeByFile(
 	const resolved: Record<string, number> = {};
 	for (const [filePath, rawVolume] of Object.entries(volumeByFile)) {
 		const normalizedVolume = normalizeVolume(rawVolume);
-		if (normalizedVolume === undefined) {
+		if (normalizedVolume === null) {
 			continue;
 		}
 

package/src/permission-forwarding-watcher.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { getErrorMessage } from "./logging.ts";
+import { toRecord } from "./config-store.ts";
 
 export type PermissionForwardingSource = "primary" | "legacy";
 export type ForwardedPermissionResolutionReason = "request_removed" | "watch_disabled" | "watcher_stopped";
@@ -53,13 +54,6 @@ interface TrackedForwardedPermissionRequest extends ForwardedPermissionRequestEv
 	lastSeenAt: number;
 }
 
-function toRecord(value: unknown): Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return {};
-	}
-	return value as Record<string, unknown>;
-}
-
 function normalizeRequestId(value: unknown, filePath: string): string {
 	if (typeof value === "string") {
 		const trimmed = value.trim();

package/src/sound-theme.ts

@@ -4,7 +4,16 @@ import { basename, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getCurrentVolume, playAudio, setVolume } from "./linux.ts";
-import { resolveProjectSoundContext } from "./per-project-sound.ts";
+import {
+	AUDIO_EXTENSIONS,
+	isDirectory as checkIsDirectory,
+	isReadableAudioFile as checkIsReadableAudioFile,
+	listAudioFiles as listProjectAudioFiles,
+	noop,
+	normalizeVolume,
+	resolveProjectSoundContext,
+	uniquePaths,
+} from "./per-project-sound.ts";
 
 export const SOUND_CATEGORIES = ["notification", "alert", "success", "error", "reminder"] as const;
 
@@ -64,7 +73,6 @@ export interface SoundThemeServiceOptions {
 	debugLog?: (message: string) => void;
 }
 
-const SUPPORTED_EXTENSIONS = new Set([".mp3", ".wav", ".ogg", ".m4a", ".flac"]);
 const EVENT_TO_CATEGORY: Record<string, SoundCategory> = {
 	notification: "notification",
 	alert: "alert",
@@ -82,24 +90,7 @@ const DEFAULT_ASSETS_DIRECTORY = fileURLToPath(new URL("../assets", import.meta.
 
 type DebugLog = (message: string) => void;
 
-function noop(): void {
-	// no-op
-}
-
-function normalizeVolume(value: number | undefined | null): number | null {
-	if (typeof value !== "number" || Number.isNaN(value)) {
-		return null;
-	}
-	const clamped = Math.max(0, Math.min(100, Math.round(value)));
-	return Number.isFinite(clamped) ? clamped : null;
-}
-
-function toUniquePaths(paths: string[]): string[] {
-	const normalized = paths.map((value) => resolve(value));
-	return [...new Set(normalized)];
-}
-
-async function pathExists(pathValue: string): Promise<boolean> {
+async function isReadable(pathValue: string): Promise<boolean> {
 	try {
 		await access(pathValue, fsConstants.R_OK);
 		return true;
@@ -108,51 +99,11 @@ async function pathExists(pathValue: string): Promise<boolean> {
 	}
 }
 
-async function isDirectory(pathValue: string): Promise<boolean> {
-	try {
-		const stats = await stat(pathValue);
-		return stats.isDirectory();
-	} catch {
-		return false;
-	}
-}
+const isDirectory = checkIsDirectory;
 
-async function isReadableAudioFile(pathValue: string): Promise<boolean> {
-	if (!SUPPORTED_EXTENSIONS.has(extname(pathValue).toLowerCase())) {
-		return false;
-	}
-	try {
-		const stats = await stat(pathValue);
-		if (!stats.isFile()) {
-			return false;
-		}
-		await access(pathValue, fsConstants.R_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-async function listAudioFiles(directory: string): Promise<string[]> {
-	if (!(await isDirectory(directory))) {
-		return [];
-	}
+const isReadableAudioFile = checkIsReadableAudioFile;
 
-	const entries = await readdir(directory, { withFileTypes: true });
-	const files = entries
-		.filter((entry) => entry.isFile())
-		.map((entry) => join(directory, entry.name))
-		.filter((filePath) => SUPPORTED_EXTENSIONS.has(extname(filePath).toLowerCase()))
-		.sort((left, right) => left.localeCompare(right));
-
-	const validFiles: string[] = [];
-	for (const filePath of files) {
-		if (await isReadableAudioFile(filePath)) {
-			validFiles.push(filePath);
-		}
-	}
-	return validFiles;
-}
+const listAudioFiles = listProjectAudioFiles;
 
 async function resolveSoundReference(reference: string, searchDirectories: string[]): Promise<string | null> {
 	const trimmed = reference.trim();
@@ -192,7 +143,7 @@ async function loadManifest(themeDirectory: string): Promise<ThemeManifest | nul
 	const manifestCandidates = ["theme.json", "sound-theme.json"].map((fileName) => join(themeDirectory, fileName));
 
 	for (const manifestPath of manifestCandidates) {
-		if (!(await pathExists(manifestPath))) {
+		if (!(await isReadable(manifestPath))) {
 			continue;
 		}
 		try {
@@ -213,7 +164,7 @@ async function loadConfigFromFile(configPath: string | undefined): Promise<Sound
 	if (!configPath) {
 		return {};
 	}
-	if (!(await pathExists(configPath))) {
+	if (!(await isReadable(configPath))) {
 		return {};
 	}
 
@@ -299,7 +250,7 @@ async function resolveThemeDirectories(config: SoundThemeConfig, assetsDirectory
 	}
 	directories.push(assetsDirectory);
 
-	const uniqueDirectories = toUniquePaths(directories);
+	const uniqueDirectories = uniquePaths(directories);
 	const existingDirectories: string[] = [];
 	for (const directory of uniqueDirectories) {
 		if (await isDirectory(directory)) {
@@ -414,7 +365,7 @@ export class SoundThemeService {
 				const fromCategoryDirectory = await listAudioFiles(categoryDir);
 				categoryCandidates.push(...fromCategoryDirectory);
 
-				for (const extension of SUPPORTED_EXTENSIONS) {
+				for (const extension of AUDIO_EXTENSIONS) {
 					const directFile = join(directory, `${category}${extension}`);
 					if (await isReadableAudioFile(directFile)) {
 						categoryCandidates.push(directFile);
@@ -422,7 +373,7 @@ export class SoundThemeService {
 				}
 			}
 
-			const uniqueCategoryCandidates = toUniquePaths(categoryCandidates);
+			const uniqueCategoryCandidates = uniquePaths(categoryCandidates);
 			if (uniqueCategoryCandidates.length > 0) {
 				soundsByCategory[category] = uniqueCategoryCandidates;
 				continue;

package/src/tts.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { runAbortableCommand } from "./abortable-command.ts";
+import { normalizeFloat } from "./config-store.ts";
 import { getErrorMessage } from "./logging.ts";
 import type {
 	ConcreteTTSEngine,
@@ -71,13 +72,6 @@ function normalizeRate(value: number, fallback: number, min: number, max: number
 	return Math.min(max, Math.max(min, Math.round(value)));
 }
 
-function normalizeFloat(value: number, fallback: number, min: number, max: number): number {
-	if (!Number.isFinite(value)) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, value));
-}
-
 function mergeConfig(base: TTSConfig, overrides: Partial<TTSConfig>): TTSConfig {
 	return {
 		...base,