@gotgenes/pi-permission-system 35.0.3 → 36.1.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** a digit argument no longer withdraws sed's or awk's read claim ([18df901](https://github.com/gotgenes/pi-packages/commit/18df9012843b5811746098bcd106c52d1bc15510)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** **breaking:** a computed argument that may spell an option withdraws find's, fd's, and sort's read claim ([8116d72](https://github.com/gotgenes/pi-packages/commit/8116d725b7d74ec610ef97cfb26e6a2df64a839d)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** a quoted "$@" after a literal withdraws find's, fd's, and sort's read claim ([45da982](https://github.com/gotgenes/pi-packages/commit/45da9825f80ce4fe2955081f2692a1bc678ddb26)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** a quoted indirect expansion after a literal withdraws find's, fd's, and sort's read claim ([dd78839](https://github.com/gotgenes/pi-packages/commit/dd78839f6327e7de51b1024b07ea21653e34b680)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+* **pi-permission-system:** a quoted variable after a literal withdraws find's, fd's, and sort's read claim ([7727223](https://github.com/gotgenes/pi-packages/commit/7727223ec01b5dd0e8560248dd965e7f638930ae)), closes [#992](https://github.com/gotgenes/pi-packages/issues/992)
+
+### Documentation
+
+* **pi-permission-system:** document the computed-word rule for find, fd, and sort ([9f7deb9](https://github.com/gotgenes/pi-packages/commit/9f7deb9ca270a17c99a820f79e40fa64afc444d0))
+* **pi-permission-system:** name a quoted "$@" among the words that split ([1595490](https://github.com/gotgenes/pi-packages/commit/15954901cc61154ad5548f3b5553b60bb48ab4d6))
+* **pi-permission-system:** name an indirect expansion among the words that split ([7d875c3](https://github.com/gotgenes/pi-packages/commit/7d875c37d4130d06ae1969b4739f030b5ce79dd7))
+* **pi-permission-system:** a quoted variable may split, since it may be a nameref ([0df4871](https://github.com/gotgenes/pi-packages/commit/0df4871f2ca42d4df6639f9bcf7d11d0647b3e31))
+
 ## [35.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v35.0.2...pi-permission-system-v35.0.3) (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,39 @@ 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 text is the dialog title (`Permission Required`, or `Permission Required (Subagent)` for a forwarded ask), never the command or path being decided, so nothing from the request 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.
@@ -896,6 +931,10 @@ Three members are read-only **until an argument says otherwise**, and naming one
 
 A long option is matched by any unambiguous abbreviation too (`sort --out=…` withdraws the claim exactly as `--output` does), and a short letter is matched anywhere in a cluster (`-uo`) or with its value attached (`-o/tmp/x`).
 
+An argument whose value only the shell decides withdraws the claim too when it may arrive beginning with `-`, since it could spell any of these options: `$opt`, `"$dir"`, `$(cmd)`, and a leading glob such as `*` all do.
+One whose first character is a literal other than `-` cannot become an option unless it can split into several words, so `find packages/*/docs` and `find . \( -name a \)` still read.
+A variable can split even inside double quotes (`"x$@"` yields one word per positional parameter, and any variable may be a name reference to an array), so `find /src -name "x$y"` withdraws the claim too.
+
 A core word counts only as a **bare basename**.
 `./grep`, `/usr/bin/grep`, and `bin\grep` name programs this audit never saw, so they prove nothing and consult both surfaces.
 

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": "35.0.3",
+  "version": "36.1.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 text is the dialog title, never the request itself.",
+      "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/access-intent/bash/command-effects.ts

@@ -16,7 +16,7 @@ import { sedWithdrawsReadClaim } from "./sed-invocation";
  * without reading the host's path language.
  *
  * A guarded word's claim is withdrawn when an argument names one of its
- * write-capable options, yielding `retracted` rather than a write: the command
+ * write-capable options, or is computed and may arrive as one, yielding `retracted` rather than a write: the command
  * may still only read, so the fail-closed base case is the honest answer and
  * `retracted` is the blame line that says why.
  *
@@ -206,17 +206,27 @@ interface RetractionGuard {
  */
 type ClaimWithdrawal = (argWords: readonly ArgWord[]) => boolean;
 
-/** A withdrawal decided by option spellings alone: any argument naming one. */
+/**
+ * A withdrawal decided by option spellings: any argument naming one.
+ *
+ * A computed argument's value is its unresolved source spelling, not what the
+ * program receives, so it is asked only whether it may arrive beginning with
+ * `-`, the shape every guarded option has.
+ */
 function optionGuard(guard: RetractionGuard): ClaimWithdrawal {
   return (argWords) =>
-    argWords.some(({ value }) => retractsClaim(value, guard));
+    argWords.some((word) =>
+      word.computed ? word.mayLeadWithDash : retractsClaim(word.value, guard),
+    );
 }
 
 /**
  * The guarded words and what withdraws each one's claim.
  *
- * `find`, `fd`, and `sort` are guarded by option spellings alone, chosen
- * because their write options spell identically in GNU and BSD. `sed` needs a
+ * `find`, `fd`, and `sort` are guarded by option spellings, chosen because
+ * their write options spell identically in GNU and BSD; a computed argument
+ * that may lead with `-` withdraws their claim too, since it could spell any
+ * of them. `sed` needs a
  * proof over its script too, since a `w` command writes whatever its options
  * say, and `awk` a proof over its program, since `print >` does the same — so
  * each owns a predicate of its own. `find`'s options are single-dash long

package/src/access-intent/bash/node-text.ts

@@ -44,16 +44,143 @@ export interface ArgWord {
    * expansion, an ANSI-C string — which {@link resolveNodeText} passes through as written.
    */
   readonly computed: boolean;
+  /**
+   * Whether the program may receive this argument, or a word split from it,
+   * beginning with `-` — the shape every option has. Exact for a word that is
+   * not computed; for a computed one, `false` only when a literal leading
+   * character survives every rewrite the shell applies.
+   */
+  readonly mayLeadWithDash: boolean;
 }
 
 /** Read an argument node into the word the program receives. */
 export function readArgWord(node: TSNode): ArgWord {
+  const value = resolveNodeText(node);
+  const computed = hasComputedPart(node) || !isSpelledExactly(node);
   return {
-    value: resolveNodeText(node),
-    computed: hasComputedPart(node) || !isSpelledExactly(node),
+    value,
+    computed,
+    mayLeadWithDash: computed
+      ? mayExpandToDashWord(node)
+      : value.startsWith("-"),
   };
 }
 
+/**
+ * Whether a computed word may reach the program — whole, or as one of the
+ * words the shell splits it into — beginning with `-`.
+ *
+ * Globbing, brace expansion, and escape removal each keep a literal prefix, so
+ * a word whose leading character is a literal other than `-` cannot become an
+ * option; an expansion that can split into several words decides nothing,
+ * since only the first of them carries the prefix.
+ */
+function mayExpandToDashWord(node: TSNode): boolean {
+  return (
+    maySplitIntoWords(node, false) || (leadingCharacterMayBeDash(node) ?? true)
+  );
+}
+
+/** Expansions whose unquoted result the shell splits into words. */
+const WORD_SPLITTING_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+  "command_substitution",
+  "arithmetic_expansion",
+]);
+
+/**
+ * Nodes whose inside is never split into the argument's words: a
+ * single-quoted or ANSI-C string, and a process substitution, whose body
+ * belongs to its own command.
+ */
+const UNSPLIT_TYPES: ReadonlySet<string> = new Set([
+  "raw_string",
+  "ansi_c_string",
+  "process_substitution",
+]);
+
+/**
+ * Whether any expansion in the word may produce more than one word.
+ *
+ * Unquoted, every expansion splits. Inside double quotes a command
+ * substitution or arithmetic expansion is one word, but a parameter expansion
+ * may not be: `$@` and `${arr[@]}` expand to one word per element, an indirect
+ * `${!name}` may name either, and any variable may be a nameref
+ * (`declare -n s='arr[@]'`), with nothing in its own spelling to show it. So
+ * every quoted parameter expansion counts, over-counting a joined `$*`.
+ */
+function maySplitIntoWords(node: TSNode, quoted: boolean): boolean {
+  if (WORD_SPLITTING_TYPES.has(node.type)) {
+    return !quoted || PARAMETER_EXPANSION_TYPES.has(node.type);
+  }
+  if (UNSPLIT_TYPES.has(node.type)) return false;
+  const childrenQuoted = quoted || node.type === "string";
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && maySplitIntoWords(child, childrenQuoted)) return true;
+  }
+  return false;
+}
+
+/** Parameter expansions, which may yield several words even when quoted. */
+const PARAMETER_EXPANSION_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+]);
+
+/**
+ * Whether the first character the word produces may be `-`, or `undefined`
+ * while every part read so far produced nothing (`""`, `''`).
+ *
+ * A part this does not know is non-literal, and so may lead with anything.
+ */
+function leadingCharacterMayBeDash(node: TSNode): boolean | undefined {
+  switch (node.type) {
+    case "word":
+    case "number":
+      return unquotedLiteralMayLeadWithDash(node.text);
+    case "raw_string":
+      return quotedLiteralMayLeadWithDash(node.text.slice(1, -1));
+    case "string_content":
+      return quotedLiteralMayLeadWithDash(node.text);
+    case '"':
+      return undefined;
+    case "process_substitution":
+      // The program receives a `/dev/fd/N` path.
+      return false;
+    case "string":
+    case "concatenation":
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        const lead = child ? leadingCharacterMayBeDash(child) : undefined;
+        if (lead !== undefined) return lead;
+      }
+      return undefined;
+    default:
+      return true;
+  }
+}
+
+/**
+ * An unquoted literal: a leading glob or brace can produce any character, and
+ * an escape yields the character after it.
+ */
+function unquotedLiteralMayLeadWithDash(text: string): boolean | undefined {
+  if (text === "") return undefined;
+  if (text.startsWith("\\")) return text.length < 2 || text[1] === "-";
+  return UNDETERMINED_LEAD.test(text);
+}
+
+/** A leading character that may become, or already is, `-`. */
+const UNDETERMINED_LEAD = /^[-*?[{]/;
+
+/** A quoted literal reaches the program as written. */
+function quotedLiteralMayLeadWithDash(text: string): boolean | undefined {
+  if (text === "") return undefined;
+  return text.startsWith("-");
+}
+
 /**
  * Whether {@link resolveNodeText} returns exactly the string the shell passes.
  *
@@ -72,6 +199,9 @@ function isSpelledExactly(node: TSNode): boolean {
     case "expansion":
       return resolvePlainVariableExpansion(node) !== null;
     case "string":
+    // A digit run is an ordinary word to the shell; the grammar's `10#$x` form
+    // carries an expansion child, which answers for itself.
+    case "number":
       return childrenSpelledExactly(node);
     case "concatenation":
       // The grammar splits `{-i,-n}` into plain words, so the expansion is

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,7 @@ import {
   renderPromptDialog,
 } from "#src/presentation/dialog-renderer";
 import { fitLinesToWidth } from "#src/presentation/line-fitting";
+import { 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";
@@ -67,6 +69,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 +155,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,
+        title,
+      );
+      if (notification) {
+        tui.terminal.write(notification);
+      }
+      return new PermissionPromptComponent(
         theme,
         config,
         title,
@@ -163,7 +176,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 text is the dialog title, never the request itself.',
+        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,47 @@
+import type { PromptNotificationChannel } from "#src/config/config-schema";
+
+const BEL = "\x07";
+const OSC = "\x1b]";
+
+/** The OSC 777 title; the body carries the dialog title. */
+const OSC_777_TITLE = "pi";
+
+/**
+ * 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. The message is stripped of control characters, so it cannot
+ * end a sequence early or start another one.
+ */
+export function renderPromptNotification(
+  channels: readonly PromptNotificationChannel[],
+  message: string,
+): string {
+  const text = withoutControlCharacters(message);
+  return channels.map((channel) => renderChannel(channel, text)).join("");
+}
+
+function renderChannel(
+  channel: PromptNotificationChannel,
+  text: string,
+): string {
+  switch (channel) {
+    case "bell":
+      return BEL;
+    case "osc9":
+      return `${OSC}9;${text}${BEL}`;
+    case "osc777":
+      // `;` separates OSC 777's fields, so one in the body would split it.
+      return `${OSC}777;notify;${OSC_777_TITLE};${text.replaceAll(";", ":")}${BEL}`;
+  }
+}
+
+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("");
+}