pi-subagents Files

pi-subagents 0.68.0 makes delegation faster, more predictable, and easier to distribute across machines. You can pass reusable JSON inputs into workflows, run children through saved Herdr machines, and ask async agents to checkpoint before deadlines. npm-installed children now start much faster, slow local models respect Pi's HTTP timeout, and local foreground children can use provider-extension models from their parent. Model failures are explicit: each launch uses one resolved model instead of silently switching to another.

Highlights

• Run Pi, Claude Code, Codex, and Cursor subagents on saved remote machines through Herdr.
• Reuse workflow scripts with different JSON inputs, including scheduled runs.
• Start npm-installed children much faster and let slow local models use Pi's configured HTTP timeout.
• Keep local foreground children on the same extension-provided models as their parent without sharing provider state between sessions.
• Ask async agents to checkpoint before a hard deadline, giving long-running work a chance to return useful progress instead of being killed.

Need to know

Full changelog

Added

• Accept bounded JSON args for inline, file-backed, validated, and scheduled workflow scripts. Scripts receive immutable arguments, and schedules retain them for later runs (#2233).
• Left-click the async widget header in mouse-enabled Pi fullscreen mode to fold it into a live status summary and unfold it again, independently of global tool expansion. Progress updates preserve the fold state; run execution and notifications are unchanged. Thanks to @pstanton237 for [#2235].
• Allow agents to declare an inline JSON Schema outputSchema default, with launch objects overriding it and explicit false opting out. Thanks to @peedrr for [#2180].
• Add PI_SUBAGENT_CACHE_RETENTION to set a prompt-cache retention tier for child sessions only, so a parent on the 1h tier can keep children on the cheaper-to-write 5m tier they are too short-lived to benefit from. Unset by default, leaving children on the parent's retention. Spawned children take it through the launch environment; in-process children pin it per request on their own session rather than on shared process state. Thanks to @johnwards for [#2190].
• Add a session-scoped host API for extensions that every native child must load. Required extensions survive agent overrides and nested launches, and child startup fails clearly when one is denied or cannot load. Thanks to @gkoreli for [#2153].
• Run Pi, Claude Code, Codex, and Cursor subagents on another computer by setting machine to a saved Herdr machine.
• Add checkpointBeforeDeadlineMs for async single-agent runs. It asks the child to checkpoint and stop before the hard timeoutMs deadline; without it, timeout behavior is unchanged. Thanks to @freezscholte for [#2141].
• Add subagents.agentExcludeDirs to exclude directory trees from agent discovery, including nested plugin sources and symlink aliases. Thanks to @xarillian for [#2131].

Changed

• Add inspectorOpen and projectOpen to authorityPolicy. Inspector opening remains automatic by default, while project opening now asks for confirmation because it starts Herdr and opens another Pi session. Set "projectOpen": "auto" to restore unprompted project opening. The Fleet TUI is unchanged. Thanks to @kevthedawg for [#2269].
• Ship compiled JavaScript in the npm package so Pi no longer transpiles the extension and detached runner when they load. On the reported cold-start path, the extension entry loaded in about 226 ms instead of 2,831 ms. Thanks to @821869798 for [#2248].

Removed

• Remove fallbackModels, all same-launch model switching (including read-only HTTP 429 continuation), and persistent model exclusions. Retry another model only with a later explicit launch; guarded retained-session compaction recovery may continue once on the already resolved model.
• Drop the bundled @earendil-works/pi-server copy that filled in the dependency Pi 0.85.0 forgot to ship. Background children on a Pi 0.85.0 host now fail to launch with a clear error; upgrade to Pi 0.85.1 or newer, which ships the package itself. Foreground children on 0.85.0 are unaffected.

Fixed

• Preserve the main watchdog's user scope across session compaction while clearing temporary activity state. Thanks to @nimeetshah0 for [#2263].
• Resolve provider-extension models in local, in-process foreground children. Such a child never loads the parent's ambient extensions, so its model runtime only knew Pi's built-in providers and every model from an extension-registered provider failed with Model "…" not found; the child now inherits the providers registered in the parent session before resolving its model. Pane-native remote foreground children continue to use the remote machine's provider discovery and configuration. Builtin agents on such a model no longer need async: true. Thanks to @lallenlowe for [#2274].
• Preserve a readable async result when result indexing or archiving fails, then retry saving it without delivering it twice. Thanks to @shaharmor for [#2267] and [#2266].
• Honor PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT for background children, fixing launches from wrapper installs and other non-standard Pi layouts. Thanks to @Yaphet2015 for [#2254].
• Keep a foreground child's report available when acceptance rejects saved output instead of replacing it with only a file reference. Thanks to @pgoodjohn for [#2255].
• Add the ambient-extension rule to Pi's model-not-found error when a child's model comes from an extension-registered provider that was not loaded for it: a foreground child now reports that agents needing a provider extension's models must run as background children (async: true) or load the extension explicitly through subagentOnlyExtensions/extensions, and a background child launched without the ambient extensions gets the matching remedies. When capabilityCeiling.denyExtensions blocks every extension, both hosts report the policy instead of remedies the ceiling discards. The core error, exit code, and failure detection are unchanged. Thanks to @pwguler for [#2240].
• Remote Herdr bridge discovery no longer blocks the parent session while waiting for the remote Pi to start.
• Recognize Windows Bun virtual entrypoints when launching standalone background children, retaining the existing Linux and npm paths. Windows coverage remains experimental; see docs/standalone-background.md. Thanks to @JohnsonRan for [#2241].
• Keep supervisor progress updates out of parent model turns while still waking for decisions and structured questions. Thanks to @moofone for [#2229] and @dajiaohuang for [#2230].
• Keep routine successful child updates out of parent model turns, and wake the parent when saving an async workflow result fails. Thanks to @moofone for [#2262].
• Start background cleanup, wait reconciliation, and retention timers with the session and clear them during shutdown. Thanks to @freezscholte for [#2244].
• Apply Pi's httpIdleTimeoutMs setting to the detached async runner's HTTP dispatcher on both the Node and standalone binary host launch paths (project .pi/settings.json over ~/.pi/agent/settings.json, 0 disables; an invalid value warns and falls back to 300s). The runner previously kept undici's 300s header/body defaults, so async children against a slow local model were cut at about five minutes while foreground children waited as configured. Thanks to @JordiPosthumus for the incident analysis in [#2199].
• Restore direct parent ownership as the default. The bundled skill delegates only when the operator asks; complexity alone no longer starts child workflows. Thanks to @AlexDochioiu for [#2216].
• Stop external runs from leaving Windows worktrees locked by Git fsmonitor processes after cancellation (#2207 recurrence).
• Include each agent's acceptance policy and role in capabilities: true results. Thanks to @Alice39s for [#2210].
• Recover when a parent workflow's previous checkout directory was removed before another child starts. Thanks to @trewwwsec for [#2211].
• Keep resumed-run startup non-blocking and fail clearly when the runner exits before it is ready. Thanks to @qsgy-edge for [#2219].
• Prefer exact agent names over packaged short-name matches, and never treat home-level agent directories as project configuration. This prevents names such as scout and code-analysis.scout from becoming ambiguous. Thanks to @ton77v for [#2214].
• Avoid Jiti for native async runner startup on supported Node versions. Thanks to @qsgy-edge for [#2220].
• Stop registering and advertising a default global Ctrl+Alt+F Fleet shortcut; /subagents-fleet and FleetView remain available. Thanks to @miaomiaozii for [#2196].
• Require low, medium, or high importance on watchdog findings. Low and medium stay visible to the user without entering model context; high findings still reach the model (#2201).
• Let headless parents and nested coordinators answer blocking child questions without deadlocking shutdown. Thanks to @ProDrifterDK for [#2185].
• Keep nested stop, interrupt, and timeout propagation inside the issuing run's descendant subtree while preserving root-wide controls. Thanks to @freezscholte for [#2243].
• Keep read-only reviews free of implementation acceptance requirements when their topic mentions releases, migrations, or security. Explicit acceptance and write tasks are unchanged. Thanks to @qsgy-edge for [#2191].
• Include async result, output, and structured-output paths in completion notices. Thanks to @peedrr for [#2181].
• Remove one-shot workflow result files and their indexes after successful consumption. Thanks to @peedrr for [#2182].
• Show runtime-registered agents in /subagents while keeping their extension-owned definitions read-only and rejecting collisions with disabled configured agents. Thanks to @mystery4f for [#2169].
• Save readable JSON to configured background output files when a successful child returns structured output without final prose. Thanks to @rtbe for [#2163].
• Surface the provider error text of a failed watchdog review in /subagents-watchdog status Last error (bounded to 600 chars). Previously only stop reason 'error' was recorded, so a watchdog failing every review (rate limit, rejected model, auth) was indistinguishable from a clean one. Thanks to @freezscholte for [#2166].
• Finalize paused async runs after the runner has actually stopped, while keeping them resumable until then. Thanks to @neruok for [#2170].
• Keep explicitly stopped aggregate children non-resumable while allowing completed siblings to resume. Thanks to @freezscholte for [#2242].
• Group workflow children under their status rows without duplicate entries and show reliable completion times. Thanks to @niko-operal for [#2168].
• Refresh external-run activity from stdout, stderr, and Git changes without repeatedly polling Git. Thanks to @DeLuke84 for [#2167].
• Remove expired partial and rejected jobs from the widget while preserving live nested children. Thanks to @ashlineldridge for [#2159].
• Reject unsupported bare acceptance strings at the provider schema boundary while preserving shorthand levels and JSON-encoded acceptance objects. Thanks to @vrolok for [#2152].
• Let Pi finish automatic compaction without an extra extension resume while preserving manual continuation for active async work. Thanks to @mxp7064 for [#2144].
• Preserve wrapped Pi core tools and explicitly requested non-core tools in child launches. Core slots still respect host availability; non-core tools are validated in the child's runtime after ceilings and exclusions (#2132, [#2133], [#2134], [#2135], [#2140]). Thanks to @carlesba for [#2137] and @clementprevot for [#2138].