[PR] Pi: opt-in structured acp_delegate notification envelope for third-party UIs

docs/configuration.md

@@ -916,6 +916,7 @@ Top-level keys that control how the proxy listens and behaves globally.
       "reviewer": { "model": "anthropic/claude-sonnet-4-5", "thinkingLevel": "high" }
     },
     "notifyIfRead": "skip",      // "skip" — no completion nudge if the model already read the result file
+    "notifyStructured": false,   // true — notices become typed custom messages carrying a versioned details envelope (runId/status + launch provenance) for third-party UIs; model-visible text unchanged (#5750)
     "fleetShortcut": "ctrl+alt+d", // "" disables the keyboard shortcut (/acp-fleet still works)
     "prompt": null,              // replace (string) or remove (null) the ACP_DELEGATE NOTIFICATIONS appendix
     "debug": false               // debug events in ~/.pi/acp.log, scoped to sub-agents

docs/configuration.zh-CN.md

@@ -910,6 +910,7 @@
       "reviewer": { "model": "anthropic/claude-sonnet-4-5", "thinkingLevel": "high" }
     },
     "notifyIfRead": "skip",      // "skip" —— 模型已读结果文件则不再补发完成通知
+    "notifyStructured": false,   // true —— 通知改为带版本化 details 信封（runId/状态+发起溯源）的类型化消息，供第三方 UI 使用；模型可见文本不变（#5750）
     "fleetShortcut": "ctrl+alt+d", // "" 关闭快捷键（/acp-fleet 仍可用）
     "prompt": null,              // 替换（字符串）或移除（null）ACP_DELEGATE NOTIFICATIONS 附录
     "debug": false               // ~/.pi/acp.log 调试事件，仅限子代理子系统

pi-subagents/README.md

@@ -87,6 +87,7 @@ or object form:
     "asyncTimeoutMinutes": 30,
     "thinkingLevel": "medium",
     "notifyIfRead": "skip",
+    "notifyStructured": false,
     "displayUsage": "separate",
     "forceEnable": false,
     "fleetShortcut": "ctrl+alt+d",
@@ -112,6 +113,7 @@ or object form:
 | `delegate.thinkingLevel` | string | unset | Global default thinking level (off\|minimal\|low\|medium\|high\|xhigh\|max). Priority: per-call > role > global > Pi default. |
 | `delegate.agents` | object | unset | Per-role defaults: `{ "<role>": { "model": "provider/id", "thinkingLevel": "…" } }`. Invalid models fall back to the parent model with a warning (never fail). |
 | `delegate.notifyIfRead` | `"skip" \| "always"` | `"skip"` | Skip the completion notification when the model already read the result file after the run finished. |
+| `delegate.notifyStructured` | boolean | `false` | Deliver notifications as typed custom messages carrying a versioned `details` envelope (runId/status/agent + launch provenance: originToolCallId/sourceSessionId), so third-party UIs tie each notice to its launching turn without parsing prose (#5750). Model-visible text and steer delivery are unchanged; hosts without `sendMessage` fall back to plain text automatically. |
 | `delegate.fleetShortcut` | string | `"ctrl+alt+d"` | TUI shortcut for the fleet inspector. `""` disables keyboard registration (`/acp-fleet` still works). Moved off `ctrl+alt+f`, which pi-subagents also claims (#412). |
 | `delegatePrompt` | string \| null | built-in | Replace (string) or remove (`null`) the `ACP_DELEGATE NOTIFICATIONS` system-prompt appendix. |
 | `debug` | boolean | `false` | Debug-level events in `~/.pi/acp.log` (shared with billion-context-pi). Env `ACP_DEBUG=1` too. |

pi-subagents/README.zh-CN.md

@@ -90,6 +90,7 @@ pi install npm:billion-context-pi-subagents
     "asyncTimeoutMinutes": 30,
     "thinkingLevel": "medium",
     "notifyIfRead": "skip",
+    "notifyStructured": false,
     "displayUsage": "separate",
     "forceEnable": false,
     "fleetShortcut": "ctrl+alt+d",
@@ -115,6 +116,7 @@ pi install npm:billion-context-pi-subagents
 | `delegate.thinkingLevel` | string | unset | 全局默认思考级别（off\|minimal\|low\|medium\|high\|xhigh\|max）。优先级：单次调用 > 角色 > 全局 > Pi 默认值。 |
 | `delegate.agents` | object | unset | 按角色设置默认值：`{ "<role>": { "model": "provider/id", "thinkingLevel": "…" } }`。无效模型回退到父模型并给出警告（不会导致失败）。 |
 | `delegate.notifyIfRead` | `"skip" \| "always"` | `"skip"` | 若模型在运行结束后已读取结果文件，则跳过完成通知。 |
+| `delegate.notifyStructured` | boolean | `false` | 将通知投递为带版本化 `details` 信封（runId/状态/agent + 发起溯源：originToolCallId/sourceSessionId）的类型化自定义消息，供第三方 UI 无需解析措辞即可把每条通知归属到发起轮次（#5750）。模型可见文本与 steer 投递不变；宿主无 `sendMessage` 时自动回退纯文本。 |
 | `delegate.fleetShortcut` | string | `"ctrl+alt+d"` | fleet 检查器的 TUI 快捷键。`""` 禁用键盘注册（`/acp-fleet` 仍然可用）。已从 `ctrl+alt+f` 移开，因为 pi-subagents 也占用了该组合键（#412）。 |
 | `delegatePrompt` | string \| null | built-in | 替换（字符串）或移除（`null`）系统提示词附录中的 `ACP_DELEGATE NOTIFICATIONS` 部分。 |
 | `debug` | boolean | `false` | 在 `~/.pi/acp.log` 中记录调试级别事件（与 billion-context-pi 共享）。也可通过环境变量 `ACP_DEBUG=1` 开启。 |

pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "billion-context-pi-subagents",
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"description": "acp_delegate sub-agent tools for the Pi coding agent — split out of billion-context-pi (#612); vendored in-repo (#2384).",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

pi-subagents/src/config.ts

@@ -83,6 +83,14 @@ export interface DelegateConfig {
    *  saw the result, so re-injecting it would only waste context.
    *  "always" — always inject the notification (previous behavior). */
   notifyIfRead?: "skip" | "always";
+  /** Deliver delegate notifications as a typed custom message that carries a
+   *  versioned `details` envelope (runId/status/agent plus launch provenance:
+   *  originToolCallId/sourceSessionId) alongside the SAME model-visible text.
+   *  Lets third-party UIs tie a notice to its launching turn without parsing
+   *  prose. Default: false — plain user-message delivery (byte-identical to
+   *  before). When true but the host lacks ExtensionAPI.sendMessage, delivery
+   *  falls back to the plain path automatically. See #5750. */
+  notifyStructured?: boolean;
   /** Keybinding for the interactive TUI shortcut that opens the acp_delegate
    *  fleet inspector (live list + transcript). Default: "ctrl+alt+d". Set to
    *  "" (empty string) to disable keyboard registration entirely — the
@@ -114,6 +122,9 @@ export interface DelegatePolicy {
   /** Whether to suppress the completion notification when the model already
    *  read the result file after the run finished. Always resolved ("skip" default). */
   notifyIfRead: "skip" | "always";
+  /** Whether notifications go out as a typed custom message with a versioned
+   *  details envelope (default false = plain user-message delivery). */
+  notifyStructured: boolean;
   /** Resolved TUI shortcut for the fleet inspector ("" = registration disabled). */
   fleetShortcut: string;
 }
@@ -128,6 +139,7 @@ export const DEFAULT_DELEGATE_POLICY: DelegatePolicy = {
   asyncTimeoutMs: 30 * 60_000,
   maxConcurrent: Infinity,
   notifyIfRead: "skip",
+  notifyStructured: false,
   fleetShortcut: DEFAULT_FLEET_SHORTCUT,
 };
 
@@ -183,7 +195,7 @@ export function resolveDelegate(adapter: SubagentsAdapterConfig): DelegatePolicy
       hint: "no-output watchdog is off; hung async runs must be cancelled manually via acp_delegate_cancel",
     });
   }
-  return { enabled, forceEnable, displayUsage, maxDepth, syncTimeoutMs, idleMs, asyncTimeoutMs, maxConcurrent, thinkingLevel: cfg.thinkingLevel, agents: cfg.agents, notifyIfRead: cfg.notifyIfRead ?? "skip", fleetShortcut: resolveFleetShortcut(cfg.fleetShortcut) };
+  return { enabled, forceEnable, displayUsage, maxDepth, syncTimeoutMs, idleMs, asyncTimeoutMs, maxConcurrent, thinkingLevel: cfg.thinkingLevel, agents: cfg.agents, notifyIfRead: cfg.notifyIfRead ?? "skip", notifyStructured: cfg.notifyStructured === true, fleetShortcut: resolveFleetShortcut(cfg.fleetShortcut) };
 }
 
 /** Resolve the fleet-inspector TUI shortcut: a string passes through verbatim