@esso0428/pi-subagents 0.17.20 → 0.17.22

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.22] - 2026-10-01
+
+### Changed
+- **Clarified the wait-group result retrieval flow**: background and wait-group completion notifications, the `Agent` tool description, prompt guidelines, and background spawn results now instruct the parent agent to call `get_subagent_result` once per completed task ID with `wait` omitted or `false`. This restores Pi's native expandable `Get Subagent Result` tool-result UI without reintroducing blocking waits, since custom `sendMessage` notifications cannot render native tool-result cards.
+
+## [0.17.21] - 2026-10-01
+
+### Fixed
+- **Marked child subagent sessions as forked extension lifecycles** so startup-only UI/theme extensions do not treat in-process child agents as a fresh interactive app launch and clear or rewrite the parent TUI.
+
 ## [0.17.20] - 2026-10-01
 
 ### Changed

package/README.md

@@ -91,7 +91,7 @@ Agent({
 })
 ```
 
-`subagent_wait_group` supports `create`, `update`, and `seal`. A sealed group sends one notification after every member reaches a terminal state (`completed`, `steered`, `error`, `stopped`, or `aborted`). If `wait: true` is used without `wait_group`, the extension creates and seals a one-agent implicit group.
+`subagent_wait_group` supports `create`, `update`, and `seal`. A sealed group sends one notification after every member reaches a terminal state (`completed`, `steered`, `error`, `stopped`, or `aborted`). If `wait: true` is used without `wait_group`, the extension creates and seals a one-agent implicit group. After a completion notification, call `get_subagent_result` once per completed task ID with `wait` omitted or `false` to render native expandable result cards without blocking.
 
 ### Scheduling
 
@@ -435,7 +435,7 @@ Check status and retrieve results from a background agent.
 | `wait` | boolean | no | Deprecated compatibility flag; never blocks |
 | `verbose` | boolean | no | Include full conversation log |
 
-`get_subagent_result` never blocks. If an agent is still running or queued, the tool returns the current status immediately; wait for the background or wait-group completion notification for the expandable final output.
+`get_subagent_result` never blocks. If an agent is still running or queued, the tool returns the current status immediately. After a background or wait-group completion notification, call it with `wait` omitted or `false` to retrieve the final output through Pi's native expandable tool-result UI.
 
 ### `steer_subagent`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.20",
+  "version": "0.17.22",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/agent-runner.ts

@@ -806,6 +806,10 @@ export async function runAgent(
     model,
     tools: sessionTools,
     resourceLoader: loader,
+    // Child subagent sessions run inside the parent Pi process; they are not a
+    // fresh interactive app startup. Mark their extension lifecycle as a fork so
+    // startup-only UI/theme extensions do not clear or rewrite the parent TUI.
+    sessionStartEvent: { type: "session_start", reason: "fork" },
     ...(trackedWriteTool && { customTools: [trackedWriteTool as any] }),
   };
   if (sessionExcludeTools) {

package/src/index.ts

@@ -321,6 +321,10 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  const resultRetrievalInstruction =
+    "Next action: call get_subagent_result once for each <task-id> above, with wait omitted or false, " +
+    "to render native expandable Get Subagent Result tool output. Do not pass wait:true.";
+
   // ---- Individual nudge helper (async join mode) ----
   function emitIndividualNudge(record: AgentRecord) {
     if (record.resultConsumed) return;  // re-check at send time
@@ -330,7 +334,7 @@ export default function (pi: ExtensionAPI) {
 
     pi.sendMessage<NotificationDetails>({
       customType: "subagent-notification",
-      content: notification + footer,
+      content: `${notification + footer}\n\n${resultRetrievalInstruction}`,
       display: true,
       details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
     }, { deliverAs: "followUp", triggerTurn: true });
@@ -370,7 +374,7 @@ export default function (pi: ExtensionAPI) {
 
         pi.sendMessage<NotificationDetails>({
           customType: "subagent-notification",
-          content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+          content: `Background agent group completed: ${label}\n\n${notifications}\n\n${resultRetrievalInstruction}`,
           display: true,
           details,
         }, { deliverAs: "followUp", triggerTurn: true });
@@ -408,7 +412,7 @@ export default function (pi: ExtensionAPI) {
 
       pi.sendMessage<NotificationDetails>({
         customType: "subagent-notification",
-        content: `Background agent wait group completed: ${summary} (group ${groupId}).${consumedNote}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+        content: `Background agent wait group completed: ${summary} (group ${groupId}).${consumedNote}\n\n${notifications}\n\n${resultRetrievalInstruction}`,
         display: true,
         details,
       }, { deliverAs: "followUp", triggerTurn: true });
@@ -900,6 +904,7 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 - Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
 - Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
 - For nonblocking grouped notification, set wait: true with run_in_background: true. Omit wait_group for a one-agent implicit group, or create an explicit group with subagent_wait_group and seal it (or set wait_group_done: true on the final Agent call).
+- When a background or wait-group completion notification arrives, call get_subagent_result once per completed task-id with wait omitted or false before summarizing if the user needs the outputs. This preserves native expandable Get Subagent Result UI without blocking.
 - Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
 - Use steer_subagent to send mid-run messages to a running background agent.
@@ -980,6 +985,7 @@ Terse command-style prompts produce shallow, generic work.
       "For broad codebase exploration or research, spawn Agent with an appropriate subagent_type (e.g. Explore). Otherwise use direct tools (read, grep, find) when the target is already known.",
       "When an agent runs in the background, you will be notified on completion — do not poll or sleep waiting for it. Continue with other work instead.",
       "For a nonblocking grouped notification, use wait: true with run_in_background: true; create/update/seal explicit groups with subagent_wait_group.",
+      "When a background or wait-group completion notification arrives, call get_subagent_result once per completed task-id with wait omitted or false before summarizing if the user needs the outputs; this preserves native expandable result UI without blocking.",
       "Trust but verify: an agent's summary describes intent, not outcome. When an agent writes or edits code, check the actual changes before reporting work as done.",
     ],
     parameters: Type.Object({
@@ -1447,7 +1453,7 @@ Terse command-style prompts produce shallow, generic work.
             ? `\nWait group: ${effectiveWaitGroupId}${implicitWaitGroupId || waitGroupDone ? " (sealed)" : " (open — seal it with subagent_wait_group)"}.\n` +
               `You will receive one grouped notification when the sealed wait group completes.\n`
             : `\nYou will be notified when this agent completes.\n`) +
-          `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
+          `After the completion notification, call get_subagent_result with wait omitted or false to render native expandable results; use steer_subagent to send messages while it is running.\n` +
           `Do not duplicate this agent's work.`,
           { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
         );