pi-subagents 0.82.1 → 0.83.0

package/bundle/preflight.js

@@ -2,22 +2,22 @@ import {
   buildEffectiveSystemPrompt,
   canPreferForkFromSnapshot,
   resolveSubagentLaunchContext
-} from "./chunk-GJECHSAR.js";
-import "./chunk-PLCCBLPY.js";
+} from "./chunk-HLE22FSH.js";
+import "./chunk-Y3I6H6DV.js";
 import {
   loadConfig
-} from "./chunk-UCPP4GNU.js";
+} from "./chunk-RZJN63GU.js";
 import {
   nestedResultsPath,
   processTerminalCandidatePath,
   processTerminalPath,
   resultFilePath
-} from "./chunk-46XKCPJR.js";
+} from "./chunk-5ESXK62X.js";
 import {
   applyIntercomBridgeToAgent,
   resolveIntercomBridge,
   validateIntercomBridgeConfig
-} from "./chunk-XSWOTIA3.js";
+} from "./chunk-MHX22USZ.js";
 import {
   AGENT_DEFINITION_PROJECTION_VERSION,
   resolveLaunchBinding,
@@ -26,7 +26,7 @@ import {
 import {
   applyThinkingSuffix,
   resolvePiLaunchToolPlan
-} from "./chunk-4SDU2BZX.js";
+} from "./chunk-CSSZRTKY.js";
 import {
   assertRequiredChildExtensionsAdmitted,
   resolveRequiredChildExtensions
@@ -34,7 +34,7 @@ import {
 import {
   getArtifactPaths,
   getArtifactsDir
-} from "./chunk-5TYMSZX3.js";
+} from "./chunk-VTMNBPCQ.js";
 import {
   assertClaudeCodeModelScope,
   assertThinkingWithinCeiling,
@@ -61,12 +61,12 @@ import {
   resolveSkillsWithFallback,
   resolveStepBehavior,
   unknownAgentDiagnosticContext
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-7F5SK2U3.js";
 import {
   DIRS,
   SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
   TEMP_ROOT_DIR
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
 import {
   capabilityCeilingAgentRestrictionMessage,

package/bundle/project-panes.js

@@ -8,11 +8,11 @@ import {
   openProjectPane,
   projectPaneBindingPath,
   readProjectPaneBinding
-} from "./chunk-52UBALJL.js";
+} from "./chunk-WG2OTTAK.js";
 import "./chunk-7J4ZXMY7.js";
-import "./chunk-5TYMSZX3.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-VTMNBPCQ.js";
+import "./chunk-7F5SK2U3.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
 import "./chunk-Z7KVHQHL.js";
 export {

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 |
 |---|---|---|

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
@@ -440,16 +455,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/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). |

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "pi-subagents",
-  "version": "0.82.1",
+  "version": "0.83.0",
   "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.js

@@ -6,7 +6,7 @@ import { mergeAgentsForScope } from "./agent-selection.js";
 import { discoverAvailableSkills, resolveSkills } from "./skills.js";
 import { buildProactiveSkillSubagentRecommendationLines, } from "./proactive-skills.js";
 import { parseFrontmatter, parseUnquotedList } from "./frontmatter.js";
-import { resolveEffectiveThinking, toModelInfo } from "../shared/model-info.js";
+import { resolveEffectiveThinking, THINKING_LEVELS, toModelInfo } from "../shared/model-info.js";
 import { resolveSubagentModelOverride } from "../runs/shared/model-resolution.js";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.js";
 import { formatReviewGateLabel, validateAcceptanceInput } from "../runs/shared/acceptance.js";
@@ -279,11 +279,8 @@ export function preservedAgentFrontmatterFields(agent, cfg) {
         changed("subagentOnlyExtensions");
     if (hasKey(cfg, "mutationTools"))
         changed("mutationTools");
-    if (hasKey(cfg, "thinking")) {
+    if (hasKey(cfg, "thinking"))
         changed("thinking");
-        if (cfg.thinking === "off")
-            fields.add("thinking");
-    }
     if (hasKey(cfg, "systemPromptMode")) {
         changed("systemPromptMode");
         fields.add("systemPromptMode");
@@ -528,17 +525,14 @@ function applyAgentConfig(target, cfg) {
             return "config.mutationTools must be a comma-separated string, empty string, or false when provided.";
     }
     if (hasKey(cfg, "thinking")) {
-        if (cfg.thinking === false || cfg.thinking === "")
+        const thinking = typeof cfg.thinking === "string" ? cfg.thinking.trim() : cfg.thinking;
+        const level = THINKING_LEVELS.find((candidate) => candidate === thinking);
+        if (thinking === false || thinking === "")
             delete target.thinking;
-        else if (typeof cfg.thinking === "string") {
-            const thinking = cfg.thinking.trim();
-            if (thinking)
-                target.thinking = thinking;
-            else
-                delete target.thinking;
-        }
+        else if (level)
+            target.thinking = level;
         else
-            return "config.thinking must be a string or false when provided.";
+            return `config.thinking must be one of ${THINKING_LEVELS.join(", ")}, or false when provided.`;
     }
     if (hasKey(cfg, "systemPromptMode")) {
         if (cfg.systemPromptMode === "append" || cfg.systemPromptMode === "replace")

package/src/agents/agent-serializer.js

@@ -91,9 +91,8 @@ export function serializeAgent(config, options = {}) {
         lines.push(`model: ${config.model ?? ""}`);
     if (config.fast === true || preserve("fast"))
         lines.push(`fast: ${config.fast === undefined ? "" : config.fast ? "true" : "false"}`);
-    if ((config.thinking && (config.thinking !== "off" || preserve("thinking"))) || (!config.thinking && preserve("thinking"))) {
+    if (config.thinking || preserve("thinking"))
         lines.push(`thinking: ${config.thinking ?? ""}`);
-    }
     if (!preservingExistingFrontmatter || preserve("systemPromptMode"))
         lines.push(`systemPromptMode: ${config.systemPromptMode}`);
     if (!preservingExistingFrontmatter || preserve("inheritProjectContext"))

package/src/agents/agents.js

@@ -28,6 +28,7 @@ import { parseMemoryFrontmatter } from "./agent-memory.js";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.js";
 import { validatePermissionRules } from "../runs/shared/permissions.js";
 import { parseThinkingLevel } from "../shared/thinking-ceiling.js";
+import { THINKING_LEVELS } from "../shared/model-info.js";
 import { assertJsonSchemaObject } from "../runs/shared/structured-output.js";
 import { normalizeCapabilityCeilingAllowedAgents } from "../runs/shared/capability-ceiling.js";
 export function defaultSystemPromptMode(name) {
@@ -39,6 +40,14 @@ export function defaultInheritProjectContext(name) {
 export function defaultInheritSkills() {
     return false;
 }
+/** Every field an `agentOverrides` entry may set; the Record type keeps it equal to BuiltinAgentOverrideConfig. */
+const BUILTIN_OVERRIDE_FIELDS = {
+    description: true, advertise: true, machine: true, output: true, outputMode: true, defaultReads: true, model: true,
+    defaultProvider: true, fast: true, thinking: true, systemPromptMode: true, inheritProjectContext: true,
+    inheritGlobalContext: true, inheritSkills: true, defaultContext: true, acceptanceRole: true, disabled: true,
+    systemPrompt: true, skills: true, tools: true, excludeTools: true, allowNestedSubagents: true, allowedAgents: true,
+    extensions: true, subagentOnlyExtensions: true, mutationTools: true, toolBudget: true,
+};
 const EMPTY_SUBAGENT_SETTINGS = { overrides: {}, providerOverrides: {} };
 const agentFrontmatterFields = new WeakMap();
 const AGENT_SOURCE_PRIORITY = {
@@ -763,6 +772,12 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
     if (Object.hasOwn(input, "launcher")) {
         throw new Error(`Builtin override '${name}' in '${filePath}' sets 'launcher', which settings overrides do not support; set 'launcher' in a user agent file instead.`);
     }
+    for (const key of Object.keys(input)) {
+        if (Object.hasOwn(BUILTIN_OVERRIDE_FIELDS, key))
+            continue;
+        const suggestion = closestMatch(key, Object.keys(BUILTIN_OVERRIDE_FIELDS));
+        throw new Error(`Builtin override '${name}' in '${filePath}' has unknown field '${key}'.${suggestion ? ` Did you mean '${suggestion}'?` : ""}`);
+    }
     const override = {};
     if ("description" in input) {
         if (typeof input.description === "string" && input.description.trim()) {
@@ -805,10 +820,11 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
             throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'fast'; expected a boolean.`);
     }
     if ("thinking" in input) {
-        if (typeof input.thinking === "string" || input.thinking === false)
-            override.thinking = input.thinking;
+        const level = THINKING_LEVELS.find((candidate) => candidate === input.thinking);
+        if (level !== undefined || input.thinking === false)
+            override.thinking = level ?? false;
         else
-            throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'thinking'; expected a string or false.`);
+            throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'thinking'; expected one of ${THINKING_LEVELS.join(", ")}, or false.`);
     }
     if ("systemPromptMode" in input) {
         if (input.systemPromptMode === "append" || input.systemPromptMode === "replace") {

package/src/api/background-work.d.ts

@@ -4,14 +4,13 @@ export interface BackgroundWorkItem {
     id: string;
     sessionId: string;
 }
-export interface BackgroundWorkReconcileContext {
-    sessionId: string;
-    nowMs: number;
-}
 export interface BackgroundWorkListContext {
     sessionId: string;
+    /** Every form the current session is known by: its file path when it has one, and `getSessionId()`. Includes `sessionId`. */
+    sessionIds: readonly string[];
     nowMs: number;
 }
+export type BackgroundWorkReconcileContext = BackgroundWorkListContext;
 export interface BackgroundWorkProvider {
     name: string;
     listActiveWork(context?: BackgroundWorkListContext): readonly BackgroundWorkItem[];
@@ -34,5 +33,9 @@ export declare function registerBackgroundWorkProvider(provider: BackgroundWorkP
 export declare function listBackgroundWorkProviders(): readonly BackgroundWorkProvider[];
 /** Read validated provider wake channels without reconciling or listing work. */
 export declare function listBackgroundWorkWakeChannels(): readonly string[];
-/** Reconcile and snapshot active provider work owned by one exact Pi session. */
-export declare function snapshotBackgroundWork(sessionId: string, nowMs?: number): BackgroundWorkSnapshot;
+/**
+ * Reconcile and snapshot active provider work owned by one exact Pi session.
+ * `sessionIds` lists that session's identity forms; the first is passed to
+ * providers as `sessionId`, and items keyed by any of them are kept.
+ */
+export declare function snapshotBackgroundWork(sessionIds: readonly string[], nowMs?: number): BackgroundWorkSnapshot;

package/src/api/background-work.js

@@ -4,7 +4,7 @@ const MAX_PROVIDER_NAME_LENGTH = 128;
 const MAX_PROVIDERS = 100;
 const MAX_ITEM_ID_LENGTH = 256;
 /**
- * A Pi session id is the session file path, which routinely exceeds a short
+ * A session can be identified by its file path, which routinely exceeds a short
  * identity budget in nested worktrees, so it is bounded like the other paths.
  */
 const MAX_SESSION_ID_LENGTH = 4_096;
@@ -120,22 +120,29 @@ export function listBackgroundWorkWakeChannels() {
     }
     return [...channels];
 }
-/** Reconcile and snapshot active provider work owned by one exact Pi session. */
-export function snapshotBackgroundWork(sessionId, nowMs = Date.now()) {
-    validateString(sessionId, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH);
+/**
+ * Reconcile and snapshot active provider work owned by one exact Pi session.
+ * `sessionIds` lists that session's identity forms; the first is passed to
+ * providers as `sessionId`, and items keyed by any of them are kept.
+ */
+export 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 === undefined)
+        throw new Error("Background-work snapshot needs at least one session id.");
     const providers = listBackgroundWorkProviders();
     const items = [];
     const identities = 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)}`, { cause: error });
         }
         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)}`, { cause: error });
@@ -153,7 +160,7 @@ export 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)
+            if (accepted.includes(item.sessionId))
                 items.push({ provider: provider.name, ...item });
         });
     }

package/src/extension/index.js

@@ -566,8 +566,11 @@ export default function registerSubagentExtension(pi) {
     // Pi sends custom messages to the model as plain user messages, so every model-visible
     // pi-subagents message is wrapped in a marker naming its source. The marker depends only on
     // the message, so history renders the same bytes every turn and cached prefixes stay valid.
+    // It runs on context_with_system, not context: Pi treats any change a context handler makes
+    // to the message list as a rewritten conversation and folds every mid-conversation system
+    // message into the leading one, which misses the prompt cache on every later turn.
     const markedMessageTypes = new Set([...SUBAGENT_MESSAGE_TYPES, "subagent-compaction-resume", SLASH_RESULT_TYPE, SLASH_TEXT_RESULT_TYPE, ADMIN_MESSAGE_TYPE]);
-    pi.on("context", (event) => {
+    pi.on("context_with_system", (event) => {
         const messages = [];
         for (const message of event.messages) {
             if (message.role !== "custom" || !markedMessageTypes.has(message.customType)) {

package/src/extension/public-execution.d.ts

@@ -57,8 +57,8 @@ export type PublicSubagentExecutionNormalization<T> = {
 /** A workflow value containing "/" or "\" is a script path; named workflow resource names contain neither. */
 export declare function isWorkflowScriptPath(workflow: string): boolean;
 /**
- * Model tool calls supply script text only through workflow: true (the reply block) or a script path.
- * workflowScript remains the internal carrier for slash, prompt-workflow, scheduled, RPC, and named-resource launches.
+ * Model tool calls supply script text through workflow: true (the reply block), a script path, or options.script,
+ * which flattenSubagentToolOptions lowers to workflowScript, the internal carrier for every other launch path too.
  */
 export declare function removedModelWorkflowFieldError(params: object): string | undefined;
 export declare function validateWorkflowCapacityOverrides(params: PublicSubagentExecutionParams): string | undefined;

package/src/extension/public-execution.js

@@ -7,8 +7,8 @@ export function isWorkflowScriptPath(workflow) {
     return workflow.includes("/") || workflow.includes("\\");
 }
 /**
- * Model tool calls supply script text only through workflow: true (the reply block) or a script path.
- * workflowScript remains the internal carrier for slash, prompt-workflow, scheduled, RPC, and named-resource launches.
+ * Model tool calls supply script text through workflow: true (the reply block), a script path, or options.script,
+ * which flattenSubagentToolOptions lowers to workflowScript, the internal carrier for every other launch path too.
  */
 export function removedModelWorkflowFieldError(params) {
     if (Object.hasOwn(params, "workflowScript"))
@@ -56,7 +56,7 @@ export function normalizePublicSubagentExecution(params, options = {}) {
         return { ok: false, error: "workflow must be true (the ```js workflow block in this reply), a script path containing '/', or a named workflow resource.", mode: "workflow" };
     }
     const hasNamedWorkflow = typeof workflow === "string" && !isWorkflowScriptPath(workflow);
-    // workflowScript is the internal script carrier; model tool calls cannot set it.
+    // workflowScript is the internal script carrier; model tool calls set it only through options.script.
     if (workflow !== undefined && params.workflowScript !== undefined) {
         return { ok: false, error: "workflow cannot be combined with an internal workflowScript.", mode: "workflow" };
     }

package/src/extension/reply-workflow-script.js

@@ -2,10 +2,9 @@ const WORKFLOW_FENCE = /^```(?:js|javascript) workflow[ \t]*$/;
 const PLAIN_JS_FENCE = /^```(?:js|javascript)[ \t]*$/;
 const OPEN_FENCE = /^(`{3,}|~{3,})/;
 const CLOSE_FENCE = /^(`{3,}|~{3,})[ \t]*$/;
-// Claude 5.x (Opus 5.5, Sonnet 5.5, Fable 5.1) text written after a tool call in the same turn reaches the session only as a
-// server summary, which drops fenced blocks (pi-claude-bridge#35); retrying the block fails again.
-const SUMMARY_NOTE = "On some models, text written after a tool call in the same turn reaches the session only as a summary without code blocks, so for the rest of this turn write the script to a file and pass its path, such as workflow: \"./script.js\".";
-const FILE_FALLBACK = `If the block is in your reply: ${SUMMARY_NOTE}`;
+// Through the Claude Agent SDK (pi-claude-bridge#35), text written after a tool call in the same turn reaches the session
+// only as a server summary, which drops fenced blocks; retrying the block fails again. Tool arguments arrive intact.
+const SUMMARY_NOTE = "On some hosts, text written after a tool call in the same turn reaches the session only as a summary without code blocks, so for the rest of this turn pass the script's source as a tool argument: options: { script: \"...\" } in place of workflow: true, with the call's other fields unchanged.";
 /**
  * Pi persists the whole assistant message before running its tool calls, so the
  * message that issued this subagent call is on the branch and carries the script.
@@ -40,7 +39,7 @@ function scriptFromReply(content) {
     const blocks = tagged.length > 0 ? tagged : plain.length === 1 ? plain : [];
     if (blocks.length !== 1) {
         const untagged = tagged.length === 0 && plain.length > 1 ? ` This reply has ${plain.length} untagged js blocks; open the script's block with the line "\`\`\`js workflow".` : "";
-        return { error: `workflow: true needs one fenced block in the same reply as the tool call, opened with the exact line "\`\`\`js workflow" and closed with "\`\`\`"; found ${tagged.length}.${untagged} ${FILE_FALLBACK}` };
+        return { error: `workflow: true needs one fenced block in the same reply as the tool call, opened with the exact line "\`\`\`js workflow" and closed with "\`\`\`"; found ${tagged.length}.${untagged} If the block is in your reply: ${SUMMARY_NOTE}` };
     }
     const script = blocks[0];
     if (!script.trim())

package/src/extension/rpc.js

@@ -5,7 +5,7 @@ import { deliverAsyncRunStop } from "../runs/foreground/async-stop-action.js";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
 import { resolveCurrentSessionId } from "../shared/session-identity.js";
 import { ownerSessionIds, ownsRun } from "../runs/shared/run-ownership.js";
-import { DIRS, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_PROCESS_TERMINAL_EVENT, SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, } from "../shared/types.js";
+import { DIRS, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_ASYNC_STARTED_EVENT, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_JOBS_CHANGED_EVENT, SUBAGENT_PROCESS_TERMINAL_EVENT, SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, } from "../shared/types.js";
 import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.js";
 import { readStatus } from "../shared/utils.js";
 import { SubagentFlatParams } from "./schemas.js";
@@ -336,8 +336,10 @@ function pingData(ctx, options) {
             request: SUBAGENT_RPC_REQUEST_EVENT,
             replyPrefix: SUBAGENT_RPC_REPLY_EVENT_PREFIX,
             asyncComplete: SUBAGENT_ASYNC_COMPLETE_EVENT,
+            asyncStarted: SUBAGENT_ASYNC_STARTED_EVENT,
             childStatus: SUBAGENT_CHILD_STATUS_EVENT,
             processTerminal: SUBAGENT_PROCESS_TERMINAL_EVENT,
+            jobsChanged: SUBAGENT_JOBS_CHANGED_EVENT,
         },
         session: sessionData(ctx),
     };

package/src/extension/subagent-options.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { Compile } from "typebox/compile";
+import { Value } from "typebox/value";
 import { closestMatch } from "../shared/edit-distance.js";
 import { removedModelWorkflowFieldError } from "./public-execution.js";
 import { SUBAGENT_OPTION_KEYS, SubagentOptionParams, createSubagentParamsSchema } from "./schemas.js";
@@ -22,6 +23,15 @@ export function flattenSubagentToolOptions(params, disabled) {
     const removedField = removedModelWorkflowFieldError(options);
     if (removedField)
         throw new Error(removedField);
+    // options.script carries script text as a tool argument for hosts that drop the reply's ```js block (SUMMARY_NOTE).
+    const { script, ...rest } = options;
+    if (script !== undefined) {
+        if (typeof script !== "string" || !script.trim())
+            throw new Error("subagent: options.script must be the workflow script's source text.");
+        if (topLevel.workflow !== undefined)
+            throw new Error("subagent: options.script replaces workflow; pass only one of them.");
+        return { ...flattenSubagentToolOptions({ ...topLevel, options: rest }, disabled), workflowScript: script };
+    }
     const entries = Object.entries(options);
     const enabledKeys = SUBAGENT_OPTION_KEYS.filter((key) => !disabled?.params.has(key));
     const unknown = entries.map(([key]) => key).filter((key) => !optionKeys.has(key));
@@ -40,12 +50,15 @@ export function flattenSubagentToolOptions(params, disabled) {
     const disabledKey = entries.find(([key]) => disabled?.params.has(key))?.[0];
     if (disabledKey)
         throw new Error(`subagent option 'options.${disabledKey}' is disabled by config ${disabled.params.get(disabledKey)}.`);
-    if (!optionsValidator.Check(options)) {
-        const errors = [...optionsValidator.Errors(options)].slice(0, 4).map((error) => `options${error.instancePath.replaceAll("/", ".")} ${error.message}`);
+    // Pi converts only the declared top-level parameters ("true" -> true); `options` is an untyped bag in the
+    // tool schema, so its values get the same conversion here. Some providers send nested scalars as strings.
+    const converted = Value.Convert(SubagentOptionParams, structuredClone(options));
+    if (!optionsValidator.Check(converted)) {
+        const errors = [...optionsValidator.Errors(converted)].slice(0, 4).map((error) => `options${error.instancePath.replaceAll("/", ".")} ${error.message}`);
         throw new Error(`subagent: ${errors.join("; ")}.`);
     }
-    const conflicts = entries.filter(([key, value]) => topLevel[key] !== undefined && !isDeepStrictEqual(topLevel[key], value)).map(([key]) => `'${key}'`);
+    const conflicts = Object.entries(converted).filter(([key, value]) => topLevel[key] !== undefined && !isDeepStrictEqual(topLevel[key], value)).map(([key]) => `'${key}'`);
     if (conflicts.length > 0)
         throw new Error(`subagent: ${conflicts.join(", ")} given both at the top level and in options with different values; give each once.`);
-    return { ...topLevel, ...options };
+    return { ...topLevel, ...converted };
 }

package/src/runs/background/async-execution.js

@@ -13,7 +13,7 @@ import { childCacheRetentionEnv } from "../../shared/child-cache-retention.js";
 import { buildEffectiveSystemPrompt } from "../shared/effective-system-prompt.js";
 import { currentCompletionOwnerId } from "../../shared/completion-owner.js";
 import { planChildLaunch, projectChainOutputSchemas, resolveStepBehavior, suppressProgressForReadOnlyTask } from "../shared/child-launch-plan.js";
-import { formatHerdrMachineRunnerUnsupported, resolveMachinePlacement } from "../shared/herdr-machine.js";
+import { formatHerdrMachineRunnerUnsupported, PLACED_RESTORE_UNSUPPORTED, resolveMachinePlacement } from "../shared/herdr-machine.js";
 import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/child-tool-plan.js";
 import { assertClaudeCodeModelScope, isClaudeCodeAdapterId, resolveClaudeCodeOverride } from "../shared/claude-code-adapter.js";
 import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.js";
@@ -1612,6 +1612,9 @@ export function executeAsyncSingle(id, params) {
     const machineUnsupported = formatHerdrMachineRunnerUnsupported({ machine: requestedMachine, agentName: agentConfig.name, runnerType: agentConfig.runner?.type, adapter: agentConfig.runner?.type === "external-cli" ? agentConfig.runner.adapter : undefined, worktree: params.worktree });
     if (machineUnsupported)
         return formatAsyncStartError("single", machineUnsupported);
+    // Refuse before the runner starts; the placed launch would refuse only after the run exists.
+    if (requestedMachine && params.revivalLease)
+        return formatAsyncStartError("single", PLACED_RESTORE_UNSUPPORTED);
     const resolvedLauncher = resolveAgentRunnerLauncher(agentConfig, ctx.runnerLaunchers, requestedMachine);
     if (resolvedLauncher.error)
         return formatAsyncStartError("single", resolvedLauncher.error);

package/src/runs/background/async-job-tracker.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { renderWidget, widgetRenderKey } from "../../tui/render.js";
 import { formatControlNoticeMessage } from "../shared/subagent-control.js";
-import { DIRS, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_STEERING_NOTICE_EVENT, WIDGET_ANIMATION_INTERVAL_MS, } from "../../shared/types.js";
+import { DIRS, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_JOBS_CHANGED_EVENT, SUBAGENT_STEERING_NOTICE_EVENT, WIDGET_ANIMATION_INTERVAL_MS, } from "../../shared/types.js";
 import { readStatus, resolveWatchPath } from "../../shared/utils.js";
 import { normalizeParallelGroups } from "./parallel-groups.js";
 import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.js";
@@ -63,6 +63,7 @@ export function createAsyncJobTracker(pi, state, asyncDirRoot, options = {}) {
     };
     const rerenderWidget = (ctx, jobs = Array.from(state.asyncJobs.values())) => {
         options.onJobsChanged?.();
+        pi.events.emit(SUBAGENT_JOBS_CHANGED_EVENT, { version: 1 });
         if (state.widgetsSuspended)
             return;
         renderWidget(ctx, options.widgetEnabled === false ? [] : jobs, options.widgetCollapsed, options.widgetLayout);

package/src/runs/background/auto-drain.js

@@ -1,6 +1,5 @@
-import { snapshotBackgroundWork } from "../../api/background-work.js";
 import { listAsyncRuns } from "./async-status.js";
-import { waitForSubagents, waitRunScopes } from "./subagent-wait.js";
+import { backgroundWorkForSession, waitForSubagents, waitRunScopes } from "./subagent-wait.js";
 export const DEFAULT_AUTO_DRAIN_TIMEOUT_MS = 30 * 60 * 1000;
 function resultText(value) {
     return value.content.map((part) => part.type === "text" ? part.text : "").join(" ").trim();
@@ -14,7 +13,7 @@ function hasOutstandingWork(deps, sessionId, nowMs, observation) {
         includeNested: false,
     }, observation?.status));
     const detachedForeground = [...(deps.state.foregroundRuns?.values() ?? [])].some((run) => run.sessionId === sessionId && run.children.some((child) => child.status === "detached"));
-    return asyncRuns.length > 0 || snapshotBackgroundWork(sessionId, nowMs).items.length > 0 || detachedForeground;
+    return asyncRuns.length > 0 || backgroundWorkForSession(deps, nowMs).items.length > 0 || detachedForeground;
 }
 /** Drain all work owned by the current headless session, including work added while draining. */
 export async function drainOutstandingWork(deps, observation) {

package/src/runs/background/fleet-view.js

@@ -164,7 +164,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 === undefined ? "" : ` ${stringifyJsonPreview(entry.args)}`}]` });
+            parts.push({ role, kind: "toolCall", name, text: `[tool: ${name}${entry.arguments === undefined ? "" : ` ${stringifyJsonPreview(entry.arguments)}`}]` });
             continue;
         }
         if (entry.type === "toolResult" || entry.type === "tool_result") {