feat: Add Terminal Attention Notifications for User Alerts (#1052)

packages/cli/src/utils/attentionNotification.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import process from 'node:process';
+
+export enum AttentionNotificationReason {
+  ToolApproval = 'tool_approval',
+  LongTaskComplete = 'long_task_complete',
+}
+
+export interface TerminalNotificationOptions {
+  stream?: Pick<NodeJS.WriteStream, 'write' | 'isTTY'>;
+}
+
+const TERMINAL_BELL = '\u0007';
+
+/**
+ * Grabs the user's attention by emitting the terminal bell character.
+ * This causes the terminal to flash or play a sound, alerting the user
+ * to check the CLI for important events.
+ *
+ * @returns true when the bell was successfully written to the terminal.
+ */
+export function notifyTerminalAttention(
+  _reason: AttentionNotificationReason,
+  options: TerminalNotificationOptions = {},
+): boolean {
+  const stream = options.stream ?? process.stdout;
+  if (!stream?.write || stream.isTTY === false) {
+    return false;
+  }
+
+  try {
+    stream.write(TERMINAL_BELL);
+    return true;
+  } catch (error) {
+    console.warn('Failed to send terminal bell:', error);
+    return false;
+  }
+}