pi-subagents 0.82.1 → 0.83.1

package/bundle/{chunk-6XJB7PIX.js → chunk-UYK5MZWE.js}

@@ -39,10 +39,10 @@ import {
   validateModelResponseAliases,
   withWorkflowChildRunModel,
   withWorktreeTransaction
-} from "./chunk-46XKCPJR.js";
+} from "./chunk-RNIZLSEA.js";
 import {
   validateIntercomBridgeConfig
-} from "./chunk-XSWOTIA3.js";
+} from "./chunk-C5P5CHYK.js";
 import {
   stableJsonDigest
 } from "./chunk-7F6RKT6W.js";
@@ -73,12 +73,12 @@ import {
   validateToolBudgetConfig,
   waitForFileSystemRetry,
   writeAtomicJson
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 import {
   DIRS,
   RUNNER_LAUNCHER_NAME_PATTERN,
   TEMP_ROOT_DIR
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import {
   previewDisplayText,
   sanitizeDisplayText,
@@ -88,7 +88,7 @@ import {
   intersectSubagentCapabilityCeilings,
   normalizeCapabilityCeilingAllowedAgents,
   parseSubagentCapabilityCeiling
-} from "./chunk-Z7KVHQHL.js";
+} from "./chunk-QXASAHIA.js";
 
 // src/shared/session-succession.ts
 var SUCCESSION_KEY = /* @__PURE__ */ Symbol.for("pi-subagents.session-succession");
@@ -2850,18 +2850,21 @@ async function protectRetainedWorktreeForResume(manifestPath, runId, childIndex,
     return cwd;
   }), { signal }));
 }
-function resolveRetainedWorktreeCwd(manifestPath, runId, childIndex) {
+function resolveRetainedWorktreeCwd(manifestPath, runId, childIndex, recordedWorktreePath) {
   const manifest = readParallelHandoffManifest(manifestPath);
-  if (!manifest) return void 0;
-  if (manifest.runId !== runId) throw new Error(`Managed worktree handoff belongs to run '${manifest.runId}', not '${runId}'.`);
-  const match = manifest.groups.flatMap((group) => group.children.map((child) => ({ group, child }))).find(({ child }) => child.index === childIndex);
-  if (!match) return void 0;
+  if (manifest && manifest.runId !== runId) throw new Error(`Managed worktree handoff belongs to run '${manifest.runId}', not '${runId}'.`);
+  const match = manifest?.groups.flatMap((group) => group.children.map((child) => ({ group, child }))).find(({ child }) => child.index === childIndex);
+  if (!manifest || !match) {
+    if (recordedWorktreePath) throw new Error(`Async run '${runId}' child ${childIndex} ran in managed worktree ${recordedWorktreePath}, but its handoff has no resumable record yet. Retry after the run settles; if it already ended, inspect ${manifestPath}.`);
+    return void 0;
+  }
   const cleanup = match.group.cleanup.tasks.find((task) => task.index === match.child.taskIndex);
   if (!cleanup) throw new Error(`Async run '${runId}' child ${childIndex} has no managed worktree cleanup record.`);
   const relativeCwd = path5.relative(resolveExistingPath(match.group.repoRoot), resolveExistingPath(manifest.cwd));
   if (path5.isAbsolute(relativeCwd) || relativeCwd === ".." || relativeCwd.startsWith(`..${path5.sep}`)) throw new Error(`Async run '${runId}' has an invalid managed worktree cwd.`);
   const requiredCwd = path5.join(cleanup.path, relativeCwd);
   if (cleanup.worktreeRemoved || cleanup.branchRemoved) throw new Error(`Async run '${runId}' required managed worktree was removed: ${requiredCwd}`);
+  if (cleanup.reason?.includes("pending durable handoff capture")) throw new Error(`Async run '${runId}' child ${childIndex} is still finalizing its managed worktree: ${requiredCwd}. Retry after the run settles; if it already ended, inspect ${manifestPath}.`);
   let worktreeRoot = "";
   let resolvedRequiredCwd = "";
   try {
@@ -3813,7 +3816,8 @@ function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
   const requireSessionFile = options.requireSessionFile ?? true;
   const location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
   if (!location.asyncDir && !location.resultPath) {
-    throw new Error("Async run not found. Provide id or dir.");
+    const requested = params.id ?? params.runId;
+    throw new Error(requested ? `Async run not found for '${requested}'.` : "Async run not found. Provide id or dir.");
   }
   const reconciliation = location.asyncDir ? reconcileAsyncRun(location.asyncDir, { resultsDir, kill: deps.kill, now: deps.now }) : void 0;
   const status = reconciliation?.status ?? null;
@@ -3913,7 +3917,7 @@ function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
   const stepThinking = statusSteps[index]?.thinking ?? resultSteps[index]?.thinking ?? (stepCount === 1 ? result?.thinking : void 0);
   const thinkingCeiling = statusSteps[index]?.thinkingCeiling ?? (stepCount === 1 ? recoveryDescriptor?.thinkingCeiling : void 0);
   const capabilityCeiling = mode === "workflow" ? intersectSubagentCapabilityCeilings(status?.admissionCapabilityCeiling, result?.admissionCapabilityCeiling) : intersectSubagentCapabilityCeilings(status?.capabilityCeiling, statusSteps[index]?.capabilityCeiling, result?.capabilityCeiling, resultSteps[index]?.capabilityCeiling);
-  const managedWorktreeCwd = location.asyncDir ? resolveRetainedWorktreeCwd(parallelHandoffPath(location.asyncDir), runId, index) : void 0;
+  const managedWorktreeCwd = location.asyncDir ? resolveRetainedWorktreeCwd(parallelHandoffPath(location.asyncDir), runId, index, statusSteps[index]?.worktreePath) : void 0;
   const resumeCwd = validateResumeCwd(runId, managedWorktreeCwd ?? status?.cwd ?? result?.cwd ?? recoveryDescriptor?.cwd);
   return {
     kind: "revive",

package/bundle/{chunk-4SDU2BZX.js → chunk-V2BZYLEP.js}

@@ -7,15 +7,15 @@ import {
   getAgentDir,
   getConfigDirName,
   getProjectConfigDir
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 import {
   TEMP_ROOT_DIR
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import {
   capabilityCeilingAgentRestrictionSources,
   intersectSubagentCapabilityCeilings,
   isAgentAllowedByCapabilityCeiling
-} from "./chunk-Z7KVHQHL.js";
+} from "./chunk-QXASAHIA.js";
 
 // src/runs/shared/child-tool-plan.ts
 import { createHash as createHash2 } from "node:crypto";

package/bundle/{chunk-FXUXCX2K.js → chunk-VLFZIN6D.js}

@@ -13,7 +13,7 @@ import {
   summarizeContextModes,
   utf8Tail,
   workflowPreflightLaneForRuntimeKey
-} from "./chunk-6XJB7PIX.js";
+} from "./chunk-UYK5MZWE.js";
 import {
   assertSafeNestedId,
   checkRecordedPidLiveness,
@@ -32,11 +32,11 @@ import {
   updateActiveRunIndex,
   validateModelResponseAliases,
   writeAsyncResultFile
-} from "./chunk-46XKCPJR.js";
+} from "./chunk-RNIZLSEA.js";
 import {
   deliverStopRequest,
   stopInboxClosedPath
-} from "./chunk-OYF6AFDY.js";
+} from "./chunk-F4ASL6OV.js";
 import {
   SUBAGENT_STOPPED_MESSAGE,
   formatDuration,
@@ -47,10 +47,10 @@ import {
   validateAcceptanceInput,
   writeAtomicJson,
   writePrivateAtomicJson
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 import {
   DIRS
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import {
   safeTerminalText,
   truncateDisplayText
@@ -292,7 +292,7 @@ function sessionMessageParts(record) {
     }
     if (entry.type === "toolCall" || entry.type === "tool_call") {
       const name = typeof entry.name === "string" ? entry.name : typeof entry.toolName === "string" ? entry.toolName : "tool";
-      parts.push({ role, kind: "toolCall", name, text: `[tool: ${name}${entry.args === void 0 ? "" : ` ${stringifyJsonPreview(entry.args)}`}]` });
+      parts.push({ role, kind: "toolCall", name, text: `[tool: ${name}${entry.arguments === void 0 ? "" : ` ${stringifyJsonPreview(entry.arguments)}`}]` });
       continue;
     }
     if (entry.type === "toolResult" || entry.type === "tool_result") {

package/bundle/{chunk-N2BN7BF5.js → chunk-XA3DY6UG.js}

@@ -104,14 +104,16 @@ function listBackgroundWorkWakeChannels() {
   }
   return [...channels];
 }
-function snapshotBackgroundWork(sessionId, nowMs = Date.now()) {
-  validateString(sessionId, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH);
+function snapshotBackgroundWork(sessionIds, nowMs = Date.now()) {
+  const accepted = [...new Set(sessionIds.map((value) => validateString(value, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH)))];
+  const sessionId = accepted[0];
+  if (sessionId === void 0) throw new Error("Background-work snapshot needs at least one session id.");
   const providers = listBackgroundWorkProviders();
   const items = [];
   const identities = /* @__PURE__ */ new Set();
   for (const provider of providers) {
     try {
-      provider.reconcile?.({ sessionId, nowMs });
+      provider.reconcile?.({ sessionId, sessionIds: [...accepted], nowMs });
     } catch (error) {
       throw new Error(
         `Background-work provider '${provider.name}' reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -120,7 +122,7 @@ function snapshotBackgroundWork(sessionId, nowMs = Date.now()) {
     }
     let active;
     try {
-      active = provider.listActiveWork({ sessionId, nowMs });
+      active = provider.listActiveWork({ sessionId, sessionIds: [...accepted], nowMs });
     } catch (error) {
       throw new Error(
         `Background-work provider '${provider.name}' listActiveWork failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -140,7 +142,7 @@ function snapshotBackgroundWork(sessionId, nowMs = Date.now()) {
         throw new Error(`Background-work provider '${provider.name}' returned duplicate item '${item.id}' for session '${item.sessionId}'.`);
       }
       identities.add(identity);
-      if (item.sessionId === sessionId) items.push({ provider: provider.name, ...item });
+      if (accepted.includes(item.sessionId)) items.push({ provider: provider.name, ...item });
     });
   }
   return {

package/bundle/{chunk-PBK2I7WY.js → chunk-YXFJVCOL.js}

@@ -1,13 +1,13 @@
 import {
   isTrustedRecordedSessionFile,
   resolveSubagentRunId
-} from "./chunk-FXUXCX2K.js";
+} from "./chunk-VLFZIN6D.js";
 import {
   agentStreamOptions,
   opencodeSessionHeaders,
   ownsRun,
   resolveAsyncResumeTarget
-} from "./chunk-6XJB7PIX.js";
+} from "./chunk-UYK5MZWE.js";
 import {
   currentCompletionOwnerId,
   listMissions,
@@ -16,12 +16,12 @@ import {
   reconcileAsyncRun,
   resolveAuthorityDecision,
   resolveMissionStoreLocation
-} from "./chunk-46XKCPJR.js";
+} from "./chunk-RNIZLSEA.js";
 import {
   deliverInterruptRequest,
   queueRevivalBrief,
   requestAsyncSteer
-} from "./chunk-OYF6AFDY.js";
+} from "./chunk-F4ASL6OV.js";
 import {
   formatShellCommand
 } from "./chunk-7J4ZXMY7.js";
@@ -32,10 +32,10 @@ import {
   tryLease,
   writeAtomicJson,
   writePrivateAtomicJson
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 import {
   DIRS
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import {
   previewDisplayText,
   safeTerminalText

package/bundle/{chunk-4Y2ROR7L.js → chunk-ZVOAMTUQ.js}

@@ -1,6 +1,6 @@
 import {
   buildWorkflowChatProgressRows
-} from "./chunk-FXUXCX2K.js";
+} from "./chunk-VLFZIN6D.js";
 import {
   aggregateStepStatus,
   contextModeBadge,
@@ -25,13 +25,13 @@ import {
   projectWorkflowChecklist,
   withCachedUiContext,
   workflowGraphStageNodes
-} from "./chunk-6XJB7PIX.js";
+} from "./chunk-UYK5MZWE.js";
 import {
   flatToLogicalStepIndex,
   formatWorkflowJsonPreview,
   hostStepReportName,
   hostStepVerdictLabel
-} from "./chunk-46XKCPJR.js";
+} from "./chunk-RNIZLSEA.js";
 import {
   snapshotExternalRuns
 } from "./chunk-UKG4V45O.js";
@@ -49,12 +49,12 @@ import {
   getSingleResultOutput,
   shortenPath,
   unresolvedChildWatchdogBlockers
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 import {
   MAX_WIDGET_JOBS,
   WIDGET_ANIMATION_INTERVAL_MS,
   WIDGET_KEY
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import {
   previewDisplayText,
   sanitizeDisplayText,

package/bundle/control-channel.js

@@ -1,11 +1,11 @@
 import {
   requestAsyncStop
-} from "./chunk-OYF6AFDY.js";
+} from "./chunk-F4ASL6OV.js";
 import "./chunk-NIXWDZZV.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-LNRJCP2Y.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
-import "./chunk-Z7KVHQHL.js";
+import "./chunk-QXASAHIA.js";
 export {
   requestAsyncStop
 };

package/bundle/index.js

@@ -17,7 +17,7 @@ function readInstalledPackageVersion() {
 var loadedPackageVersion = readInstalledPackageVersion();
 
 // index.ts
-var registerExtension = process.env[HERDR_PI_MODE_ENV] === "1" ? (await import("./chunk-JYUKW2SY.js")).default : process.env.PI_SUBAGENT_CHILD === "1" ? void 0 : (await import("./chunk-IVAE5Z6Q.js")).default;
+var registerExtension = process.env[HERDR_PI_MODE_ENV] === "1" ? (await import("./chunk-AHIFYGR3.js")).default : process.env.PI_SUBAGENT_CHILD === "1" ? void 0 : (await import("./chunk-5YIITCPD.js")).default;
 function registerSubagentExtension(pi) {
   const installedVersion = readInstalledPackageVersion();
   if (installedVersion !== loadedPackageVersion) {

package/bundle/intercom-bridge.js

@@ -1,11 +1,11 @@
 import {
   resolveIntercomSessionTarget
-} from "./chunk-XSWOTIA3.js";
+} from "./chunk-C5P5CHYK.js";
 import "./chunk-7F6RKT6W.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-LNRJCP2Y.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
-import "./chunk-Z7KVHQHL.js";
+import "./chunk-QXASAHIA.js";
 export {
   resolveIntercomSessionTarget
 };

package/bundle/preflight.js

@@ -2,22 +2,22 @@ import {
   buildEffectiveSystemPrompt,
   canPreferForkFromSnapshot,
   resolveSubagentLaunchContext
-} from "./chunk-GJECHSAR.js";
-import "./chunk-PLCCBLPY.js";
+} from "./chunk-SSG7IEP5.js";
+import "./chunk-LFDBD4PW.js";
 import {
   loadConfig
-} from "./chunk-UCPP4GNU.js";
+} from "./chunk-QP5ZWNIS.js";
 import {
   nestedResultsPath,
   processTerminalCandidatePath,
   processTerminalPath,
   resultFilePath
-} from "./chunk-46XKCPJR.js";
+} from "./chunk-RNIZLSEA.js";
 import {
   applyIntercomBridgeToAgent,
   resolveIntercomBridge,
   validateIntercomBridgeConfig
-} from "./chunk-XSWOTIA3.js";
+} from "./chunk-C5P5CHYK.js";
 import {
   AGENT_DEFINITION_PROJECTION_VERSION,
   resolveLaunchBinding,
@@ -26,7 +26,7 @@ import {
 import {
   applyThinkingSuffix,
   resolvePiLaunchToolPlan
-} from "./chunk-4SDU2BZX.js";
+} from "./chunk-V2BZYLEP.js";
 import {
   assertRequiredChildExtensionsAdmitted,
   resolveRequiredChildExtensions
@@ -34,7 +34,7 @@ import {
 import {
   getArtifactPaths,
   getArtifactsDir
-} from "./chunk-5TYMSZX3.js";
+} from "./chunk-D3JAFGMO.js";
 import {
   assertClaudeCodeModelScope,
   assertThinkingWithinCeiling,
@@ -61,17 +61,17 @@ import {
   resolveSkillsWithFallback,
   resolveStepBehavior,
   unknownAgentDiagnosticContext
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-LNRJCP2Y.js";
 import {
   DIRS,
   SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
   TEMP_ROOT_DIR
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
 import {
   capabilityCeilingAgentRestrictionMessage,
   intersectSubagentCapabilityCeilings
-} from "./chunk-Z7KVHQHL.js";
+} from "./chunk-QXASAHIA.js";
 
 // src/api/preflight.ts
 import * as fs from "node:fs";

package/bundle/project-panes.js

@@ -8,13 +8,13 @@ import {
   openProjectPane,
   projectPaneBindingPath,
   readProjectPaneBinding
-} from "./chunk-52UBALJL.js";
+} from "./chunk-2DHZTCOL.js";
 import "./chunk-7J4ZXMY7.js";
-import "./chunk-5TYMSZX3.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-D3JAFGMO.js";
+import "./chunk-LNRJCP2Y.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
-import "./chunk-Z7KVHQHL.js";
+import "./chunk-QXASAHIA.js";
 export {
   PROJECT_PANES_API_VERSION,
   PROJECT_PANE_TRUST_STATUS,

package/bundle/shared-types.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_FORK_PREAMBLE,
   wrapForkTask
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 export {
   DEFAULT_FORK_PREAMBLE,
   wrapForkTask

package/docs/configuration.md

@@ -124,7 +124,7 @@ Pi records each tool definition and prompt section a session declares, and decla
 { "disabledFeatures": ["watchdog", "panes", "preflight", "lane-metadata", "gates"] }
 ```
 
-Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features, and `{ action: "guide", options: { topic: "tool-reference" } }` starts with a notice listing what is disabled. Custom tool descriptions are not changed. Nothing is disabled by default, and the default schema and description are unchanged. An unknown or duplicate feature name fails config loading rather than silently re-enabling every feature.
+Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features. Every `{ action: "guide" }` response starts with a notice: a topic lists what is disabled, and a section points to the `tool-reference` topic for that list. With `workflow-scripts` disabled, the notice also says to use the top-level `tasks` or `chain` fields instead. Custom tool descriptions are not changed. Nothing is disabled by default, and the default schema and description are unchanged. An unknown or duplicate feature name fails config loading rather than silently re-enabling every feature.
 
 | Feature | Parameters removed | Actions rejected |
 |---|---|---|
@@ -202,7 +202,18 @@ With `"summary"`, a tool result looks like this:
 
 Set to `false` to register none of the pi-subagents slash commands (`/run`, `/subagents`, `/subagents-fleet`, `/subagents-watchdog`, `/prompt-workflow`, and the rest) and no [`foregroundDetachShortcut`](#foregrounddetachshortcut). The `subagent` tool, RPC, the async widget, and the extension's other features are unchanged. Prompt templates whose frontmatter has `chain:` launch through `/prompt-workflow`, so they stop working too. Defaults to `true`. Restart Pi or run `/reload` after changing it.
 
-The package's prompt shortcuts, such as `/parallel-review` and `/review-loop`, are Pi prompt templates, not commands, so this setting leaves them alone. Pi's package filter removes them: `{ "packages": [{ "source": "npm:pi-subagents", "prompts": [] }] }` in Pi's `settings.json`, or `pi config`.
+The package's prompt shortcuts, such as `/parallel-review` and `/review-loop`, are Pi prompt templates, not commands, so this setting leaves them alone. The same goes for its skills (`pi-subagents` and `council-mode`) and built-in agents. To turn them off, use Pi's package filter for prompts and skills and `disableBuiltins` for the agents, in Pi's `settings.json`. This turns off every prompt, the `council-mode` skill and every built-in agent:
+
+```json
+{
+  "packages": [
+    { "source": "npm:pi-subagents", "prompts": [], "skills": ["!council-mode"] }
+  ],
+  "subagents": { "disableBuiltins": true }
+}
+```
+
+A `!` entry such as `"!review-loop.md"` drops one file, and `[]` drops all of that type. `subagents.agentOverrides.<name>.disabled: true` turns off one built-in agent instead of all of them ([agents.md](agents.md)). `pi config` toggles the package's prompts and skills interactively.
 
 ## `foregroundDetachShortcut`
 

package/docs/extension-api.md

@@ -129,6 +129,7 @@ Method notes:
 Capability advertisements on `ping`:
 
 - `events.asyncComplete` — exact process-local completion correlation after RPC `spawn`.
+- `events.jobsChanged`, `events.asyncStarted`, `events.childStatus`, `events.processTerminal` — the event names a host can listen to instead of polling `status` (see [Refresh a host view without polling](#refresh-a-host-view-without-polling)).
 - `managementActions` — exact schedule management actions accepted by RPC `manage`.
 - `launchResolvedExtensions` — the optional launch-resolved extension projection in status details.
 - `runtimeAcknowledgedExtensions` — the optional child-runtime acknowledgement projection and event name.
@@ -141,6 +142,20 @@ Capability advertisements on `ping`:
 
 Structured delegation progress updates carry `runId` as soon as foreground execution allocates it, so a caller can retain the package-owned revival target even if its own tool turn is interrupted before the terminal response. Foreground `details.results[]` rows also include a numeric `index` that is unique within the run and stable across partial progress snapshots and the final result; use `(runId, index)` instead of row position to correlate single, counted parallel, and chain children.
 
+### Refresh a host view without polling
+
+A host that shows background subagent activity (an editor panel, a footer, a status bar) can read `status` when something changed instead of on a timer:
+
+1. Subscribe to the names under `ping.events`: `jobsChanged`, `asyncStarted`, `childStatus`, `asyncComplete`, and `processTerminal`.
+2. Read `status` once, when the host starts or reconnects. Events are not replayed after a host restart, and subscribing first means a change during that read still triggers another one.
+3. When any of the events fires, read `status` again. Events can arrive in bursts and can repeat, so coalesce them in the host, for example one `status` read per 250 ms, and keep a refresh that arrives while a read is in flight for after it ends.
+
+`subagent:jobs-changed` carries only `{ version: 1 }`. It fires whenever the parent's background job view changes: a run starts, moves to another step (no other event reports a chain or parallel run's step changes), reports new activity (a tool, a turn, tokens, or output), finishes, or is cleared from the widget. While a child streams output this can be about once per second per run. Starts and finishes fire right away; step and activity changes fire when the parent next reads the run's status file, which on macOS is a check every 5 seconds. It fires only in sessions with a UI, which covers interactive and RPC mode; print mode (`pi -p`) and SDK embeddings without a UI do not get it. It fires even when the async widget is turned off.
+
+Foreground children are not background jobs. Their progress arrives as updates to the parent's `subagent` tool call (Pi's `tool_execution_update` events), with the `details.results[]` rows described above.
+
+To rebuild what ran in a session after a reload, read the records the session file already holds: the `subagent` tool result's `details.results[]` for foreground runs and the `subagent-notify` message's `details.runs[]` for background runs (see [Host session lifetime and completion wakes](#host-session-lifetime-and-completion-wakes)). The `cost` method returns per-child rows built from the same records.
+
 ### Direct async launch correlation
 
 Direct async runs retain their originating `toolCallId` in status and result
@@ -415,6 +430,8 @@ const restriction = registerSubagentCapabilityCeiling({
 // restriction.dispose() removes only this provider's registration.
 ```
 
+Register with **`ctx.sessionManager.getSessionId()`**; a ceiling registered by session file path does not apply.
+
 Semantics:
 
 - Active registrations intersect their `allowedTools` and `allowedAgents` sets and OR `denyExtensions`.
@@ -440,16 +457,16 @@ const dispose = registerBackgroundWorkProvider({
   name: "my-background-extension",
   wakeChannels: ["my-extension:job-finished"],
   listActiveWork: (context) => jobs
-    .filter((job) => job.status === "running" && (!context || job.ownerSessionId === context.sessionId))
+    .filter((job) => job.status === "running" && (!context || context.sessionIds.includes(job.ownerSessionId)))
     .map((job) => ({ id: job.id, sessionId: job.ownerSessionId })),
-  reconcile: ({ sessionId, nowMs }) => reconcileJobs(sessionId, nowMs),
+  reconcile: ({ sessionIds, nowMs }) => reconcileJobs(sessionIds, nowMs),
 });
 ```
 
 Semantics:
 
-- Each item needs a stable provider-local ID and the exact Pi session ID that owns it. `bg_wait` captures those identities rather than a count, so one job finishing while another starts still satisfies first-completion waits without losing the replacement.
-- `listActiveWork` receives an optional `{ sessionId, nowMs }` context during snapshots. Providers can use `sessionId` to avoid scanning unrelated work; existing zero-argument `() => items` providers continue to work, and returned items are still validated and filtered to the exact requested session.
+- Each item needs a stable provider-local ID and the session that owns it, as either `ctx.sessionManager.getSessionId()` or the session file path (`ctx.sessionManager.getSessionFile()`); both are accepted. `bg_wait` captures those identities rather than a count, so one job finishing while another starts still satisfies first-completion waits without losing the replacement.
+- `listActiveWork` receives an optional `{ sessionId, sessionIds, nowMs }` context during snapshots, and `reconcile` receives the same fields. `sessionIds` holds every form of the current session (its file path when it has one, and its session id); `sessionId` is the first of them. Providers can use them to avoid scanning unrelated work; existing zero-argument `() => items` providers continue to work, and returned items are still validated and filtered to the current session. Each provider is called once per snapshot.
 - It filters snapshots to the active session, fails closed if a provider disappears while its work is tracked, and surfaces malformed snapshots or provider errors with provider context.
 - Wake channels only shorten polling; validated snapshots remain authoritative.
 - Providers share a registry through `Symbol.for("pi-subagents.background-work.v1")`, allowing independently loaded extension modules to meet in one Pi process.

package/docs/missions.md

@@ -13,6 +13,8 @@ Missions are durable wrappers around runs. The noun map:
 
 Ordinary workflow launches create one enclosing mission by default, with detailed JSON records under `~/.pi/agent/missions/projects/<project-hash>/` linking objectives, run ids, lifecycle status, decisions, artifact paths, and delivery receipts. Workflow children do not create separate missions. Each workflow child attempt is stored in the enclosing mission with its stable workflow key, run id when known, agent, task metadata, timestamps, session and artifact paths, and latest status heartbeat.
 
+A finished run completes a mission you asked for with `mission` or `missionId` only when its result was accepted. If the run, or any workflow child in the mission, ends with acceptance `review-required`, `rejected`, `claimed`, or `pending`, the mission stays `waiting` and `mission.show` lists each child's acceptance status. Check the result and close the mission with `mission.close`. A `gate` or `acceptance.verify` command lets the runtime accept the result, except for writer runs: they require a review by default and stay `review-required` without one. When the command is enough proof, use `acceptance: { level: "verified", verify: [{ id: "check", command: "..." }], review: { required: false } }` instead of `gate`. Missions made by default for ordinary launches still complete when their run finishes.
+
 Records created under the old default `<project>/.pi/subagents/missions` stay on disk. Continue them by setting `missions.directory` to that path for the project or by copying the record into the new agent-dir project store. There is no automatic migration.
 
 Behavior:

package/docs/observability.md

@@ -334,6 +334,7 @@ Async events:
 
 - `subagent:async-started`
 - `subagent:async-complete`
+- `subagent:jobs-changed` (see [extension-api.md](extension-api.md#refresh-a-host-view-without-polling))
 
 For regular async starts, the `subagent:async-started` payload includes redacted `task` and `goal` prompt fields. Async workflow script roots emit the same event with `mode: "workflow"` after their initial `status.json` is durable; workflow roots can omit `task`, and any included prompt fields are redacted. Their keyed children are then announced dynamically through `subagent:child-status`. Companion UI extensions can combine those hints with the authoritative live lifecycle artifacts under `asyncDir` without scraping terminal output.
 

package/docs/tool-reference.md

@@ -110,7 +110,7 @@ The `subagent` tool schema lists `agent`, `task`, `workflow`, `args`, `async`, `
 | `options.checkpointBeforeDeadlineMs` | number | none | Async single-agent runs only. The runner requests that the child "checkpoint and stop" this many milliseconds before the run deadline (finish the current tool call, report changed files, build/test state, remaining work, commit/PR state; start no new work). This best-effort steer uses the normal steering lifecycle at the next tool boundary, so the receipt is visible in status and events; the ordinary deadline kill still applies. Precedence: call value → config `checkpointBeforeDeadlineMs`. Disarmed when the deadline leaves under one second before the checkpoint. |
 | `options.toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`: `hard` is a positive integer and `soft`, if set, is a positive integer no greater than `hard`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, and accepts either a nonempty array of tool names or `"*"` for every tool call. Final assistant text is never blocked. |
 | `options.usageBudget` | object | none | Optional root-only reported-usage budget `{ tokens?: { soft?, hard }, costUsd?: { soft?, hard } }`. Include at least one metric; each `hard` must be positive and each optional `soft` positive and no greater than its `hard`. Soft limits are status-only. Hard limits prevent later child launches after reported usage is reconciled; already-running children are not stopped and no reservations are made. |
-| `options.extensionBindings` | object | none | Child-only plain JSON keyed by namespaces like `package.name/1` (positive version): at most 16 namespaces, nesting depth 16, 256 total object properties, and 16 KiB of canonical UTF-8 JSON. Native Pi launches only; external runners and retained resumes reject it. |
+| `options.extensionBindings` | object | none | Child-only plain JSON keyed by namespaces like `package.name/1` (positive version): at most 16 namespaces, nesting depth 16, 256 total object properties, and 16 KiB of canonical UTF-8 JSON. Native Pi launches only; external runners and retained resumes reject it. A child's extensions read it as canonical JSON from `PI_SUBAGENT_EXTENSION_BINDINGS` in their factory or `session_start`; a foreground child sees it only until its session has started, after which the parent's environment is restored. |
 | `options.preflight` | object | none | Advisory lane hints for raw scripts (`workflow: true` or a script path) only; not accepted with named workflows or direct children. See [bounded workflows](workflows.md#opt-in-bounded-workflows). |
 | `cwd` | string | runtime cwd | Override working directory. With `machine`, the directory on that machine. |
 | `options.machine` | string | - | Herdr saved machine (label or profile id) for external-cli agents; see [agents.md](agents.md#running-external-cli-agents-on-a-herdr-saved-machine). |
@@ -344,7 +344,7 @@ subagent({ action: "doctor" })
 - `view: "transcript"` tails the selected run's live `output-<index>.log` or persisted session transcript, with `lines` capped at 500.
 - Nested status shows the root/parent path, nested children, session/artifact paths when known, and nested control commands.
 - Inside child-safe fanout mode, bare `status` requires an id when no local foreground run is active, so children cannot enumerate unrelated top-level async runs.
-- Bare `interrupt` still targets only the visible top-level run; interrupting a nested run requires its explicit nested id.
+- `interrupt` requires an id, like `stop`, `steer`, and `resume`; for a nested run, pass its nested id.
 
 ### Command controls
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "pi-subagents",
-  "version": "0.82.1",
+  "version": "0.83.1",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/pi-subagents/SKILL.md

@@ -48,12 +48,12 @@ needs.
 Use a script when later steps depend on earlier results, or for keyed,
 retried, aggregated, or resumed children. Write one ```` ```js workflow ````
 block in the reply and call `subagent({ workflow: true })` in the same reply.
-For a long script, or when a `workflow: true` call reports the block missing,
-write it to a file and pass `workflow: "./path.js"`. On Claude 5.x models (Opus
-5.5, Sonnet 5.5, Fable 5.1), use the file whenever the turn already made a tool
-call: text after one reaches the session as a summary without the block. Calls in one reply run at
-the same time, so write the file in one reply and `validate` or launch it in
-the next.
+For a long script, write it to a file and pass `workflow: "./path.js"`; calls in
+one reply run at the same time, so write the file in one reply and `validate` or
+launch it in the next. When a `workflow: true` call reports the block missing,
+pass the source as `options: { script: "..." }` in place of `workflow: true` for
+the rest of the turn: on some hosts, text after a tool call reaches the session
+as a summary without the block.
 
 ```js workflow
 const scan = await runs.run("scan", { label: "Map auth flow", agent: "scout", task: "..." });

package/src/agents/agent-management.d.ts

@@ -6,7 +6,7 @@ import { type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
 type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & {
     model?: ExtensionContext["model"];
     config?: ExtensionConfig;
-    currentSessionId?: string;
+    piSessionId?: string;
     runtimeAgentOwner?: RuntimeAgentOwner;
     onAgentsChanged?: () => void;
     discoverAgentsAll?: typeof discoverAgentsAll;