@gotgenes/pi-permission-system 36.1.0 → 36.2.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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)
 
 

package/docs/configuration.md

@@ -208,7 +208,17 @@ The two OSC forms raise a desktop notification in terminals that implement them;
 
 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 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.

package/package.json

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

package/schemas/permissions.schema.json

@@ -70,7 +70,7 @@
     },
     "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.",
+      "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": {

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

@@ -18,7 +18,10 @@ import {
   renderPromptDialog,
 } from "#src/presentation/dialog-renderer";
 import { fitLinesToWidth } from "#src/presentation/line-fitting";
-import { renderPromptNotification } from "#src/presentation/prompt-notification";
+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";
@@ -60,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`). */
@@ -160,7 +165,7 @@ export function presentInlinePermissionPrompt(
       // human is being asked; a re-render does not come back through here.
       const notification = renderPromptNotification(
         view.promptNotifications,
-        title,
+        view.notice,
       );
       if (notification) {
         tui.terminal.write(notification);

package/src/config/config-schema.ts

@@ -378,7 +378,7 @@ export const unifiedConfigSchema = z
         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.',
+          '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({

package/src/presentation/prompt-notification.ts

@@ -1,41 +1,102 @@
+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]";
 
-/** The OSC 777 title; the body carries the dialog title. */
-const OSC_777_TITLE = "pi";
+/** 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. The message is stripped of control characters, so it cannot
+ * 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[],
-  message: string,
+  notice: PromptNotice,
 ): string {
-  const text = withoutControlCharacters(message);
-  return channels.map((channel) => renderChannel(channel, text)).join("");
+  const clean: PromptNotice = {
+    title: withoutControlCharacters(notice.title),
+    body: withoutControlCharacters(notice.body),
+  };
+  return channels.map((channel) => renderChannel(channel, clean)).join("");
 }
 
 function renderChannel(
   channel: PromptNotificationChannel,
-  text: string,
+  notice: PromptNotice,
 ): string {
   switch (channel) {
     case "bell":
       return BEL;
     case "osc9":
-      return `${OSC}9;${text}${BEL}`;
+      // One field, so the title leads it: it is what names the session.
+      return `${OSC}9;${notice.title}: ${notice.body}${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}`;
+      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)