@gotgenes/pi-permission-system 36.0.0 → 36.2.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [36.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.1.0...pi-permission-system-v36.2.0) (2026-09-30)
+
+
+### Features
+
+* name the session and the requested tool in prompt notifications ([#996](https://github.com/gotgenes/pi-packages/issues/996)) ([eb49c64](https://github.com/gotgenes/pi-packages/commit/eb49c6494d12749f71130d74b75c578530c89afa)), closes [#996](https://github.com/gotgenes/pi-packages/issues/996)
+
+### Documentation
+
+* describe the session and tool in prompt notifications ([#996](https://github.com/gotgenes/pi-packages/issues/996)) ([c5c74db](https://github.com/gotgenes/pi-packages/commit/c5c74db43235297a39bbe94303225ac50baf0ca4))
+
+## [36.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.0.0...pi-permission-system-v36.1.0) (2026-09-30)
+
+
+### Features
+
+* **pi-permission-system:** ring the terminal when a permission prompt opens ([b92ede8](https://github.com/gotgenes/pi-packages/commit/b92ede819523aa2bd776acb2d2ce6dac11622571)), closes [#906](https://github.com/gotgenes/pi-packages/issues/906)
+
+### Documentation
+
+* **pi-permission-system:** document prompt notifications and the notifier recipe ([9ce9b32](https://github.com/gotgenes/pi-packages/commit/9ce9b32c82cca97c3fa73ff377f5f773673821f7)), closes [#906](https://github.com/gotgenes/pi-packages/issues/906)
+
 ## [36.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.3...pi-permission-system-v36.0.0) (2026-09-29)
 
 

package/README.md

@@ -67,6 +67,7 @@ All permissions use one of three states:
 When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
 In an interactive TUI session the prompt is an inline keybind dialog — `y` approve, `s` approve for this session, `n` deny, `r` deny with a reason — where each hotkey arms and a second press confirms (configurable via `doublePressToConfirm`).
 The hotkeys themselves are remappable through `permissionDialogKeys`, which matters if you type with an input method editor: composition mode swallows letter keys before they reach the terminal, and digits do not.
+Set `promptNotifications` (for example `["bell"]`) and the dialog also rings the terminal as it opens, so a session waiting on you in another tab or pane gets flagged.
 A file-access ask that proves a single direction offers `b` as well, granting the session both directions instead of only the one the gate proved.
 The prompt shows one fact per line — who is asking, the tool, the matched rule, the value being decided — within a row budget, so a large tool input cannot take over the transcript; `Ctrl+O` (`app.tools.expand`) expands it to the complete request.
 See [docs/configuration.md](docs/configuration.md#inline-permission-dialog-tui) for the hotkeys and [docs/session-approvals.md](docs/session-approvals.md) for session-scoped rules and pattern suggestions.

package/config/config.example.json

@@ -12,6 +12,7 @@
     "deny": "n",
     "denyWithReason": "r"
   },
+  "promptNotifications": [],
 
   "forwardingTimeoutMs": 600000,
 

package/docs/configuration.md

@@ -38,6 +38,7 @@ See [migration/0644-project-trust-gating.md](migration/0644-project-trust-gating
 The `permission` object uses deep-shallow merge: string-vs-string replaces; both-object shallow-merges pattern maps; string-vs-object the override wins entirely.
 Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConfirm`, `forwardingTimeoutMs`, `promptMaxRows`, `promptFieldMaxWidth`) use simple replacement.
 `permissionDialogKeys` replaces the whole map rather than merging entry by entry, so the map that was validated is the map that applies.
+`promptNotifications` likewise replaces the whole list, so a project `[]` turns off a global list.
 
 **Invalid higher-precedence scope fails closed.**
 If a non-global scope (project config, global agent frontmatter, or project agent frontmatter) is present but fails to load or validate, it no longer contributes an empty scope that silently inherits the lower scope's rules.
@@ -105,6 +106,7 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 | `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                                                                   |
 | `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                                                            |
 | `permissionDialogKeys`      | —        | Remaps the inline TUI dialog's decision hotkeys (see below). One printable character per decision; omitted decisions keep `y` / `s` / `b` / `n` / `r`.                                                                                       |
+| `promptNotifications`       | `[]`     | Terminal notifications to emit when the inline TUI dialog opens: `"bell"`, `"osc9"`, `"osc777"` (see below). Empty for none.                                                                                                                 |
 | `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose parent is not draining its inbox gives up in ~2 s regardless, whether that parent runs in this process or its own. |
 | `promptMaxRows`             | `24`     | Max rows a permission prompt renders before eliding its evidence. The request's own facts are never elided by this budget; `Ctrl+O` expands the prompt to the complete request.                                                              |
 | `promptFieldMaxWidth`       | `400`    | Max characters of any one field shown in a permission prompt. This is what bounds a single long field (a here-string command, say) that would otherwise fill the prompt through wrapping.                                                    |
@@ -184,6 +186,49 @@ The reason editor is Pi's own line editor, so it behaves like the chat input: pa
 The reason is a single line — a pasted line break becomes a space, and a long reason scrolls sideways rather than growing the dialog.
 `enter` submits it, and `esc` (or `Ctrl+C`) returns to the decision list without denying.
 
+#### Terminal notifications
+
+An ask stops the agent mid-turn, so a session in a background tab or pane can sit waiting without anything telling you.
+Set `promptNotifications` to have the dialog signal the terminal as it opens:
+
+```jsonc
+{
+  "promptNotifications": ["bell", "osc777"]
+}
+```
+
+| Channel    | Writes                                           |
+| ---------- | ------------------------------------------------ |
+| `"bell"`   | BEL, the terminal bell                           |
+| `"osc9"`   | an OSC 9 desktop notification (`ESC ] 9 ;`)      |
+| `"osc777"` | an OSC 777 desktop notification (`ESC ] 777 ;`)  |
+
+The bell is the widest-supported signal: terminals and multiplexers already route it to a sound, a badge, or pane attention (tmux `monitor-bell`, for one).
+The two OSC forms raise a desktop notification in terminals that implement them; which one yours supports is in its documentation, and listing both is harmless, since a terminal ignores an OSC it does not know.
+
+Channels are written in the order listed.
+The list is empty by default, so nothing is emitted until you set it; an unknown channel name is a validation error like any other malformed field.
+The notification names the session and what is being asked, so it tells you which pane to go to.
+Its title is `pi — <session name>`, or `pi — <directory name>` for a session without a name.
+Its body is the dialog title followed by the tool (or, for an ask that is not a tool call, the gate surface) and the requesting agent when there is one:
+
+| Ask                                         | `osc777` title       | `osc777` body                                  |
+| ------------------------------------------- | -------------------- | ---------------------------------------------- |
+| local `bash` ask in session `refactor-auth` | `pi — refactor-auth` | `Permission Required: bash`                    |
+| `read` forwarded from subagent `scout`      | `pi — refactor-auth` | `Permission Required (Subagent): read (scout)` |
+
+OSC 9 has a single text field, so `osc9` writes the title ahead of the body: `pi — refactor-auth: Permission Required: bash`.
+The notification carries labels only, never the command, path, MCP target, or skill being decided, so nothing the request holds lands in your notification history.
+
+The signal fires once per prompt, when the prompt is actually shown.
+A second ask that waits behind an open dialog signals when its own turn comes, and a forwarded subagent ask signals in the parent session that shows it.
+An ask decided without a dialog (by a rule, a session approval, or an authorizer link) emits nothing.
+Only interactive TUI sessions signal; outside interactive mode Pi routes stdout away from the terminal, so there is nothing to ring.
+
+Inside tmux, prefer `"bell"`: tmux passes a BEL through to its own bell handling, but drops OSC notifications unless passthrough is enabled.
+
+To run a program instead (Herdr, `cmux notify`, a push to your phone), write a small extension on the `permissions:ui_prompt` and `permissions:decision` broadcasts; see the [recipe](cross-extension-api.md#recipe-bridging-a-prompt-to-an-external-notifier).
+
 ### What a prompt shows
 
 The prompt renders one fact per line, with the requesting agent (and, for a forwarded subagent ask, its session), the tool, the gate surface, the matched rule, the decision-relevant value, and — for a wrapper such as `xargs` — the command that will actually run.

package/docs/cross-extension-api.md

@@ -516,6 +516,39 @@ pi.events.on("permissions:decision", (raw) => {
 | `confirmation_unavailable`    | State was `ask` but no UI was available — blocked                    |
 | `gate_error`                  | The gate threw, or an escalation failed — blocked, fail-closed       |
 
+### Recipe: bridging a prompt to an external notifier
+
+This extension can ring the terminal itself (`promptNotifications` in [configuration.md](configuration.md#terminal-notifications)).
+Anything beyond that (running a program, reporting to a session manager such as Herdr, calling `cmux notify`, pushing to a phone) belongs in a small extension of your own that listens to the two broadcasts.
+This package does not emit another tool's events itself: an outbound bridge would tie it to that tool's contract, where a listener leaves both sides free to change.
+
+The two channels pair up by `requestId`.
+`permissions:ui_prompt` means the human is being asked right now, and the `permissions:decision` carrying the same `requestId` means that prompt is over, however it ended.
+Track the open ids rather than a counter or a boolean: several prompts can be pending at once (queued in one session, or forwarded from subagents), and a decision for a request that never prompted must not clear anything.
+
+```typescript
+import type {
+  PermissionDecisionEvent,
+  PermissionUiPromptEvent,
+} from "@gotgenes/pi-permission-system";
+
+const open = new Set<string>();
+
+pi.events.on("permissions:ui_prompt", (raw) => {
+  const { requestId } = raw as PermissionUiPromptEvent;
+  if (open.size === 0) markBlocked(); // e.g. herdr:blocked { active: true }
+  open.add(requestId);
+});
+
+pi.events.on("permissions:decision", (raw) => {
+  const { requestId } = raw as PermissionDecisionEvent;
+  if (!open.delete(requestId)) return; // decided without a prompt
+  if (open.size === 0) clearBlocked(); // e.g. herdr:blocked { active: false }
+});
+```
+
+Both events fire on the bus of the session that shows the prompt, including the parent session that shows a forwarded subagent ask, so the listener belongs in whichever session holds the UI.
+
 ---
 
 ## Ready Event

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "36.0.0",
+  "version": "36.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/schemas/permissions.schema.json

@@ -68,6 +68,16 @@
         }
       ]
     },
+    "promptNotifications": {
+      "description": "Terminal notifications to emit when the inline permission dialog opens: bell (BEL), osc9 (OSC 9 notification), osc777 (OSC 777 notification). Omit or leave empty for none. TUI sessions only.",
+      "markdownDescription": "Terminal notifications to emit when the inline permission dialog opens, so a terminal or multiplexer can flag a session waiting on a decision.\n\n- `\"bell\"` writes a BEL — what tmux `monitor-bell` and most terminals react to.\n- `\"osc9\"` writes an OSC 9 desktop notification.\n- `\"osc777\"` writes an OSC 777 desktop notification.\n\nOmit or leave empty for none (the default). Applies to interactive **TUI** sessions only. The notification names the session and the requested tool and agent, never the command, path, or other value being decided.",
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["bell", "osc9", "osc777"]
+      }
+    },
     "forwardingTimeoutMs": {
       "description": "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. Omit to use the default (600000, ten minutes).",
       "markdownDescription": "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds.\n\nOmit to use the default (`600000`, ten minutes). A child whose in-process parent is not draining its inbox at all gives up in a couple of seconds regardless of this value, so lower it only to bound how long you are willing to leave an *unanswered* prompt pending.",

package/src/authority/authorizer.ts

@@ -158,6 +158,10 @@ export function selectAuthorizer(
           dialogs: deps.dialogs,
           getPromptPreferences: deps.getPromptPreferences,
           requestPermissionDecision: deps.requestPermissionDecision,
+          describeSession: () => ({
+            name: ctx.sessionManager.getSessionName(),
+            cwd: ctx.cwd,
+          }),
         }),
         adjudicatesLocally: true,
       };

package/src/authority/local-user-authorizer.ts

@@ -4,6 +4,10 @@ import {
   buildForwardedScopeLabels,
   describeGrantTarget,
 } from "#src/presentation/pattern-suggest";
+import {
+  describePromptNotice,
+  type NotificationSession,
+} from "#src/presentation/prompt-notification";
 import {
   emitUiPromptEvent,
   type PermissionEventBus,
@@ -37,6 +41,8 @@ export interface LocalUserAuthorizerDeps {
   getPromptPreferences: () => PromptPreferences;
   /** Injected for testability; production callers pass the real function. */
   requestPermissionDecision: typeof requestPermissionDecision;
+  /** Read when each prompt opens, so a session named mid-session is picked up. */
+  describeSession: () => NotificationSession;
 }
 
 /**
@@ -77,15 +83,21 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
     emitUiPromptEvent(this.deps.events, buildUiPrompt(details));
+    const title = details.forwarding
+      ? "Permission Required (Subagent)"
+      : "Permission Required";
     return this.deps.requestPermissionDecision(
       {
         mode: this.deps.mode,
         ui: this.deps.ui,
         ...this.deps.getPromptPreferences(),
+        notice: describePromptNotice(
+          title,
+          details.payload.request,
+          this.deps.describeSession(),
+        ),
       },
-      details.forwarding
-        ? "Permission Required (Subagent)"
-        : "Permission Required",
+      title,
       details.payload,
       buildRequestOptions(details),
     );

package/src/authority/permission-prompt-component.ts

@@ -9,6 +9,7 @@ import {
   type KeyId,
   matchesKey,
 } from "@earendil-works/pi-tui";
+import type { PromptNotificationChannel } from "#src/config/config-schema";
 import type { DialogKeyBindings, PromptAction } from "#src/config/dialog-keys";
 import {
   completeViewBudget,
@@ -17,6 +18,10 @@ import {
   renderPromptDialog,
 } from "#src/presentation/dialog-renderer";
 import { fitLinesToWidth } from "#src/presentation/line-fitting";
+import {
+  type PromptNotice,
+  renderPromptNotification,
+} from "#src/presentation/prompt-notification";
 import type { PromptPayload } from "#src/presentation/prompt-payload";
 import { collapsePastedNewlines } from "./bracketed-paste";
 import type { DecisionSource, UserDecisionSurface } from "./decision-source";
@@ -58,6 +63,8 @@ type PromptKeybindings = Pick<KeybindingsManager, "matches">;
 export interface PermissionPromptView extends PromptPreferences {
   mode: ExtensionContext["mode"];
   ui: PermissionPromptUi;
+  /** What the inline dialog's terminal notification says; the fallback ignores it. */
+  notice: PromptNotice;
 }
 
 /** Live prompt-behavior preferences read at prompt time (see `doublePressToConfirm`). */
@@ -67,6 +74,8 @@ export interface PromptPreferences {
   budget: RenderBudget;
   /** The character bound to each decision. */
   dialogKeys: DialogKeyBindings;
+  /** Terminal notifications the inline dialog emits as it opens; empty for none. */
+  promptNotifications: readonly PromptNotificationChannel[];
 }
 
 /**
@@ -151,8 +160,17 @@ export function presentInlinePermissionPrompt(
     keys: view.dialogKeys,
   };
   return view.ui.custom<UnattributedDecision>(
-    (tui, theme, keybindings, done) =>
-      new PermissionPromptComponent(
+    (tui, theme, keybindings, done) => {
+      // The factory runs once, as the dialog mounts, which is the moment the
+      // human is being asked; a re-render does not come back through here.
+      const notification = renderPromptNotification(
+        view.promptNotifications,
+        view.notice,
+      );
+      if (notification) {
+        tui.terminal.write(notification);
+      }
+      return new PermissionPromptComponent(
         theme,
         config,
         title,
@@ -163,7 +181,8 @@ export function presentInlinePermissionPrompt(
           tui.requestRender();
         },
         done,
-      ),
+      );
+    },
     { overlay: false },
   );
 }

package/src/config/config-loader.ts

@@ -198,6 +198,7 @@ function formatConfigIssues(error: ZodError): string[] {
  * - Array fields (piInfrastructureReadPaths) replace the base when present in
  *   the override (override-wins, same as scalars).
  * - `permissionDialogKeys` replaces the base map whole, unlike `shellTools`.
+ * - `promptNotifications` replaces the base list whole, like the arrays.
  */
 // Scalar knobs merged by override-replaces-base; keep in sync with
 // PermissionSystemExtensionConfig booleans (debugLog, permissionReviewLog,
@@ -254,6 +255,15 @@ export function mergeUnifiedConfigs(
     merged.permissionDialogKeys = dialogKeys;
   }
 
+  // promptNotifications: override replaces base, as the string arrays above
+  // do; its own block because a union-keyed write in that loop would have to
+  // satisfy both element types at once.
+  const notifications =
+    override.promptNotifications ?? base.promptNotifications;
+  if (notifications !== undefined) {
+    merged.promptNotifications = notifications;
+  }
+
   // shellTools: shallow-merge by tool name so a project entry overrides a
   // colliding tool's alias but never drops a global entry (a dropped alias is
   // a silent enforcement regression).

package/src/config/config-schema.ts

@@ -291,6 +291,8 @@ const dialogKeysSchema = z
     ],
   });
 
+const promptNotificationChannelSchema = z.enum(["bell", "osc9", "osc777"]);
+
 const shellToolAliasSchema = z
   .strictObject({
     commandArgument: z.string().min(1).meta({
@@ -369,6 +371,16 @@ export const unifiedConfigSchema = z
       default: true,
     }),
     permissionDialogKeys: dialogKeysSchema.optional(),
+    promptNotifications: z
+      .array(promptNotificationChannelSchema)
+      .optional()
+      .meta({
+        description:
+          "Terminal notifications to emit when the inline permission dialog opens: bell (BEL), osc9 (OSC 9 notification), osc777 (OSC 777 notification). Omit or leave empty for none. TUI sessions only.",
+        markdownDescription:
+          'Terminal notifications to emit when the inline permission dialog opens, so a terminal or multiplexer can flag a session waiting on a decision.\n\n- `"bell"` writes a BEL — what tmux `monitor-bell` and most terminals react to.\n- `"osc9"` writes an OSC 9 desktop notification.\n- `"osc777"` writes an OSC 777 desktop notification.\n\nOmit or leave empty for none (the default). Applies to interactive **TUI** sessions only. The notification names the session and the requested tool and agent, never the command, path, or other value being decided.',
+        default: [],
+      }),
     forwardingTimeoutMs: z.number().int().min(1).optional().meta({
       description:
         "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. Omit to use the default (600000, ten minutes).",
@@ -454,6 +466,11 @@ export type ShellToolsConfig = z.infer<typeof shellToolsSchema>;
 /** The raw config file shape after validation (all fields optional). */
 export type UnifiedPermissionConfig = z.infer<typeof unifiedConfigSchema>;
 
+/** One terminal notification the inline dialog emits as it opens. */
+export type PromptNotificationChannel = z.infer<
+  typeof promptNotificationChannelSchema
+>;
+
 /**
  * Derive the published JSON Schema (Draft 2020-12) from the zod source.
  *

package/src/config/extension-config.ts

@@ -9,6 +9,7 @@ import type {
   ShellToolsConfig,
   UnifiedPermissionConfig,
 } from "./config-loader";
+import type { PromptNotificationChannel } from "./config-schema";
 import type { DialogKeyOverrides } from "./dialog-keys";
 
 export const EXTENSION_ID = "pi-permission-system";
@@ -31,6 +32,8 @@ export interface PermissionSystemExtensionConfig {
   reviewLogFieldMaxWidth?: number;
   /** The inline dialog's hotkey bindings, as configured; resolved at prompt time. */
   permissionDialogKeys?: DialogKeyOverrides;
+  /** Terminal notifications the inline dialog emits as it opens; absent means none. */
+  promptNotifications?: PromptNotificationChannel[];
   /** Non-bash tools that carry shell semantics, keyed by tool name. */
   shellTools?: ShellToolsConfig;
   /** Ordered names of registered live-authority chain links to consult before the terminal authorizer. */
@@ -97,6 +100,9 @@ export function normalizePermissionSystemConfig(
   if (raw.permissionDialogKeys !== undefined) {
     result.permissionDialogKeys = raw.permissionDialogKeys;
   }
+  if (raw.promptNotifications !== undefined) {
+    result.promptNotifications = raw.promptNotifications;
+  }
   if (raw.shellTools !== undefined) {
     result.shellTools = raw.shellTools;
   }

package/src/index.ts

@@ -160,6 +160,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       doublePressToConfirm: configStore.current().doublePressToConfirm,
       budget: resolveRenderBudget(configStore.current()),
       dialogKeys: resolveDialogKeys(configStore.current()).keys,
+      promptNotifications: configStore.current().promptNotifications ?? [],
     }),
     requestPermissionDecision,
     forwardingDir: paths.forwardingDir,

package/src/presentation/prompt-notification.ts

@@ -0,0 +1,108 @@
+import { basename } from "node:path";
+import type { PromptNotificationChannel } from "#src/config/config-schema";
+import type { PromptRequestFacts } from "./prompt-payload";
+
+const BEL = "\x07";
+const OSC = "\x1b]";
+
+/** What a prompt notification says: OSC 777 carries both fields. */
+export interface PromptNotice {
+  readonly title: string;
+  readonly body: string;
+}
+
+/** The session facts a notice names, read when the prompt opens. */
+export interface NotificationSession {
+  readonly name: string | undefined;
+  readonly cwd: string;
+}
+
+/** The request facts a notice may name: labels only, never the value. */
+export type NoticeRequestFacts = Pick<
+  PromptRequestFacts,
+  "toolName" | "surface" | "requester"
+>;
+
+/**
+ * What a prompt notification says: which session is waiting, and what is
+ * being asked and by whom.
+ *
+ * Labels only. The request's value (the command, path, MCP target, or skill)
+ * never appears: the OS notification history is a store this package does not
+ * control, outside the owner-only logs and their key-name masking.
+ */
+export function describePromptNotice(
+  dialogTitle: string,
+  request: NoticeRequestFacts,
+  session: NotificationSession,
+): PromptNotice {
+  const label = sessionLabel(session);
+  const subject = askSubject(request);
+  return {
+    title: label ? `pi — ${label}` : "pi",
+    body: subject ? `${dialogTitle}: ${subject}` : dialogTitle,
+  };
+}
+
+/** The session's name, or the name of the directory it runs in, as Pi's own terminal title does. */
+function sessionLabel(session: NotificationSession): string {
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: an empty name is unnamed
+  return session.name || basename(session.cwd);
+}
+
+/** What is asked (the tool, else the gate surface) and by which agent. */
+function askSubject(request: NoticeRequestFacts): string {
+  const what = request.toolName ?? request.surface;
+  const who = request.requester.agentName;
+  if (what && who) return `${what} (${who})`;
+  // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: an empty label names nothing
+  return what || who || "";
+}
+
+/**
+ * The bytes that ask a terminal for attention as a permission dialog opens.
+ *
+ * One sequence per configured channel, in configured order; an empty list
+ * renders nothing. Every field is stripped of control characters, so it cannot
+ * end a sequence early or start another one.
+ */
+export function renderPromptNotification(
+  channels: readonly PromptNotificationChannel[],
+  notice: PromptNotice,
+): string {
+  const clean: PromptNotice = {
+    title: withoutControlCharacters(notice.title),
+    body: withoutControlCharacters(notice.body),
+  };
+  return channels.map((channel) => renderChannel(channel, clean)).join("");
+}
+
+function renderChannel(
+  channel: PromptNotificationChannel,
+  notice: PromptNotice,
+): string {
+  switch (channel) {
+    case "bell":
+      return BEL;
+    case "osc9":
+      // One field, so the title leads it: it is what names the session.
+      return `${OSC}9;${notice.title}: ${notice.body}${BEL}`;
+    case "osc777":
+      return `${OSC}777;notify;${osc777Field(notice.title)};${osc777Field(notice.body)}${BEL}`;
+  }
+}
+
+/** `;` separates OSC 777's fields, so one inside a field would split it. */
+function osc777Field(text: string): string {
+  return text.replaceAll(";", ":");
+}
+
+function withoutControlCharacters(value: string): string {
+  // Code points, not grapheme clusters: a control character is always one.
+  return Array.from(value)
+    .filter((character) => {
+      const code = character.codePointAt(0) ?? 0;
+      return code > 31 && code !== 127;
+    })
+    .join("");
+}