pi-subagents 0.69.0 → 0.70.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## [Unreleased]
 
+## [0.70.0] - 2026-09-19
+
+### Highlights
+
+- Control which extensions children load and which agents descendants may launch without widening their permissions.
+- Background workflows remain visible and recoverable through detaches, interruptions, restarts, and supervisor handoffs.
+- Invalid workflows, unsafe worktree launches, and blocked tool budgets now fail earlier with clearer results.
+- Linked worktrees, Windows supervisor polling, source-layout runners, and Orca progress tabs are more reliable.
+
+### Added
+
+- Add `subagents.defaultSubagentOnlyExtensions` for loading shared child-only extensions without disabling ambient extension discovery. Thanks to [@Shujakuinkuraudo](https://github.com/Shujakuinkuraudo) for #2284.
+- Allow agent frontmatter and `subagents.agentOverrides.<name>.allowedAgents` to restrict which canonical agents a child may launch without granting delegation or widening capability ceilings. Thanks to [@shkrabov](https://github.com/shkrabov) for #2312.
+
+### Changed
+
+- Document `/subagent-cost` as the combined accounting view for parent and asynchronous child usage. Thanks to [@swarajban](https://github.com/swarajban) for #2313.
+
+### Fixed
+
+- Wake root `bg_wait` calls when an owned nested child is waiting on `contact_supervisor`. Thanks to [@geril07](https://github.com/geril07) for #2344.
+- Keep explicitly detached workflow children visible, preserve their result lookup after the coordinator exits, and avoid treating launch receipts as completed results. Thanks to [@shaharmor](https://github.com/shaharmor) for #2299.
+- Settle interrupted, stopped, or timed-out background runs even when child session creation hangs. Thanks to [@onorua](https://github.com/onorua) for #2320.
+- Prevent concurrent workflow observers from overwriting retained-session startup confirmation and stranding resumed children. Thanks to [@luigiplr](https://github.com/luigiplr) for #2292.
+- Let children use the tools declared by their own agent configuration instead of incorrectly narrowing them to the parent's `--tools` selection. Thanks to [@carlesba](https://github.com/carlesba) for #2289.
+- Report foreground hard tool-budget blocks as `tool_budget_exhausted`, including calls blocked before execution starts. Thanks to [@kylerberry](https://github.com/kylerberry) for #2302.
+- Keep permission forwarding scoped to the validated launch parent instead of sharing an identity between independent root sessions. Thanks to [@kasumikira](https://github.com/kasumikira) for #2321.
+- Reject malformed inline and file-backed workflow scripts before creating asynchronous run state or launching children. Thanks to [@rtbe](https://github.com/rtbe) for #2309.
+- Reject direct asynchronous managed-worktree launches from a dirty source before creating run state or returning a receipt. Thanks to [@rtbe](https://github.com/rtbe) for #2311.
+- Avoid rejecting keyed property access after a mutable `runs.all(...)` result binding is reassigned.
+- Report useful rooted field paths for failed structured-output `if`/`then`/`else` schemas while preserving root `$defs`. Thanks to [@peedrr](https://github.com/peedrr) for #2317.
+- Give the bundled reviewer a bounded, read-only view of staged, unstaged, and untracked working-tree changes from its launch `HEAD`. Thanks to [@nateberkopec](https://github.com/nateberkopec) for #2306.
+- Show the correct child transcript when inspecting an indexed asynchronous workflow step. Thanks to [@swarajban](https://github.com/swarajban) for #2304.
+- Reconcile foreground and background child usage from terminal session messages when live usage events are missing or incomplete. Thanks to [@riique](https://github.com/riique) for #2295 and #2296.
+- Keep project-scoped agent memory stable across linked Git worktrees. Thanks to [@freezscholte](https://github.com/freezscholte) for #2293.
+- Keep Fleet workflow coverage stable during heartbeat, counter, and token updates without resetting an unchanged layout. Thanks to [@swarajban](https://github.com/swarajban) for #2305.
+- Continue supervisor polling on Windows when a temporary channel directory disappears during a scan. Thanks to [@asher-aqi](https://github.com/asher-aqi) for #2303.
+- Keep source-layout asynchronous runners on native Node TypeScript when child extensions are configured, with consistent peer-module resolution. Thanks to [@qsgy-edge](https://github.com/qsgy-edge) for #2314.
+- Make Orca progress tabs work under `fish`. Thanks to [@yourfriendaaron](https://github.com/yourfriendaaron) for #2294.
+- Prevent publishing the TypeScript source checkout directly to npm; only the compiled package is publishable. Thanks to [@niko-operal](https://github.com/niko-operal) for #2300.
+
 ## [0.69.0] - 2026-09-18
 
 ### Highlights

package/agents/reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: reviewer
 description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
-tools: read, grep, find, ls, contact_supervisor
+tools: read, grep, find, ls, watchdog_diff, contact_supervisor
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -53,7 +53,8 @@ Review a PR or issue by understanding the context, then verifying:
 - Start from the exact diff and named source seam for code-behavior review. Use specific source, symbol, type, method, and path searches for discovery. Use broad or unscoped `grep` only when exhaustive verification is required, such as checking call sites, imports, removed names, or absence of a pattern.
 - Read the relevant files first. Read plan and progress when the task supplies them.
 - Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
-- Do not use shell commands or write files. Report any test or Git command that a supervisor must run.
+- Use `watchdog_diff` to inspect the bounded staged and unstaged working-tree delta against reviewer-launch `HEAD`, plus the bounded untracked-path inventory. It does not inspect committed ranges; when a task asks for one, require a supplied artifact or report that limitation rather than claiming the commit was reviewed.
+- Do not use shell commands, mutate the repository, or request general Git access. Report any test command that a supervisor must run.
 - Do not invent issues. Only report problems you can justify from evidence.
 - Prefer small corrective edits over broad rewrites.
 - If everything looks good, say so plainly.

package/docs/agents.md

@@ -321,12 +321,13 @@ completionGuard: false
 interactive: true
 maxSubagentDepth: 1
 allowNestedSubagents: true
+allowedAgents: scout, reviewer
 ---
 
 Your system prompt goes here.
 ```
 
-Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `defaultReads`, `skill`/`skills`, `skillPath`, `extensions`, and `subagentOnlyExtensions`:
+Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `allowedAgents`, `defaultReads`, `skill`/`skills`, `skillPath`, `extensions`, and `subagentOnlyExtensions`:
 
 ```yaml
 tools:
@@ -344,6 +345,7 @@ Field notes:
 | `tools` | Strict child tool allowlist. Named extension tools must also have their provider loaded. `mcp:` entries select direct MCP tools when `pi-mcp-adapter` is installed. |
 | `excludeTools` | Optional child tool deny-list applied after normal tool resolution. With an explicit `tools` allowlist, matching names are removed; when `tools` is omitted, the names are excluded from the child session's default tool set. Unknown names are ignored by Pi without making the agent definition invalid. |
 | `allowNestedSubagents` | Set `true` to authorize the child-safe nested `subagent` runtime without making omitted `tools` an allowlist. Inherited depth and capability ceilings remain authoritative. |
+| `allowedAgents` | Restricts which canonical, case-sensitive agent names this agent may launch. Omitted adds no restriction; an empty list denies every descendant launch. This only narrows an existing nesting grant: `tools: subagent` or `allowNestedSubagents: true` is still required. Inherited/runtime allowlists are intersected and cannot be widened. |
 | `extensions` | Omitted means a background child loads the parent's ambient extensions; empty means no ambient extensions; list values load exactly those extensions. Foreground children never load ambient extensions, so for them only listed values apply. |
 | `subagentOnlyExtensions` | Extension paths loaded only in this agent's child sessions. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
 | `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
@@ -392,6 +394,7 @@ This is independent of Pi's own parent/session/project memory system and writes
 How it works:
 
 - On each run, the first 200 lines of `MEMORY.md` in the resolved memory directory are injected into the child system prompt, so the agent can recall accumulated role notes such as threat-model entries, release gotchas, or verified commands.
+- Project memory resolves to the main checkout from standard linked Git worktrees whose metadata lives under `<main>/.git/worktrees/`, so isolated children share one durable role memory and worktree cleanup does not remove it. Custom `--separate-git-dir` layouts keep their current project-root behavior because Git does not retain a safely verifiable main-checkout path there.
 - Agents with write tools (`edit`, `write`, or `bash`, or no `tools` allowlist at all) are told they may append concise dated entries to the file.
 - Agents without write tools receive a read-only memory block and are not instructed to edit it. A read-only reviewer can recall prior notes without gaining write capability.
 - The memory directory is never created eagerly. The agent's own `write` tool creates it (and `MEMORY.md`) on the first persist.
@@ -433,6 +436,7 @@ How `tools` behaves:
 - `tools` present: regular tool names become an explicit allowlist.
 - `tools:` empty: the child session gets no tools.
 - `allowNestedSubagents: true`: explicitly enables child-safe nested fanout without turning omitted `tools` into an allowlist. Depth and inherited capability ceilings still apply.
+- `allowedAgents: scout, reviewer`: if nesting is separately enabled, restricts this agent's descendant launches to those names. `allowedAgents:` denies all descendants and omission is unrestricted except for inherited/runtime policy.
 
 `excludeTools` is applied after this resolution. It can narrow an explicit `tools` allowlist or, when `tools` is omitted, remove names from Pi's default builtin tool set. Runtime-injected tools are excluded only when their exact names are listed. An empty `excludeTools` list has no effect.
 
@@ -475,7 +479,7 @@ When `extensions` is present, normal discovered extensions are disabled. The lis
 
 Use `subagentOnlyExtensions` when a custom extension tool should exist only inside child sessions. It is scoped by agent config: every run of that agent receives those extension paths, while other agents do not unless they declare the same field. The current model does not have a separate named-subagent audience inside one agent definition.
 
-To apply the same `extensions` allowlist to every agent that does not declare its own, set `subagents.defaultExtensions` in user or project settings (see [configuration.md](configuration.md)).
+To apply a shared extension policy to every agent that does not declare its own, set `subagents.defaultExtensions` for an ambient-disabling allowlist or `subagents.defaultSubagentOnlyExtensions` for child-only paths that preserve ambient discovery (see [configuration.md](configuration.md)).
 
 Before the first model turn, the child runtime compares every explicit tool name with Pi's final filtered registry. A missing provider fails the run with the unavailable names and concrete `subagentOnlyExtensions`/`extensions` guidance, instead of letting a direct or chained child silently continue without its requested tools.
 

package/docs/configuration.md

@@ -2,7 +2,7 @@
 
 `pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`. This page lists every key, plus the environment variables and the settings-file keys that affect config resolution.
 
-Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, and `allow: ["inherit"]` permits the current parent model. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
+Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `defaultSubagentOnlyExtensions`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, and `allow: ["inherit"]` permits the current parent model. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
 
 ## Project root resolution (settings)
 

package/docs/extension-api.md

@@ -329,7 +329,7 @@ Identity:
 Results:
 
 - Result mode is explicit. Text remains literal even when it looks like JSON. Structured mode returns the separately captured, schema-validated JSON value.
-- Terminal usage reports input, output, cache-read, cache-write, cost, turns, tool calls, and duration alongside the effective model and thinking level when known.
+- Terminal usage reports input, output, cache-read, cache-write, cost, turns, tool calls, and duration alongside the effective model and thinking level when known. Native child totals are reconciled per attempt from post-prompt session messages: complete persisted fields replace live aggregates, while incomplete fields retain them.
 
 Live update events are bounded progress snapshots, not patches, so consumers should replace the prior snapshot rather than merge it as a delta. Structured delegation coalesces heartbeats whose delegation-visible progress and recent output are unchanged; a duration-only heartbeat therefore does not produce another update. The terminal response remains authoritative for the complete result, error, and final usage details.
 

package/docs/models.md

@@ -158,7 +158,9 @@ Project settings win over user settings. Use `agentOverrides.<name>.extensions`
 }
 ```
 
-A non-array value, an array containing a non-string entry, or an empty/whitespace-only string raises a settings error naming `defaultExtensions` and the offending settings file, matching the validation pattern used by `defaultModel` and `defaultThinking`.
+Set `subagents.defaultSubagentOnlyExtensions` to give agents without a `subagentOnlyExtensions` field a shared child-only extension list while preserving ambient extension discovery. An empty array is an explicit empty default but, unlike `defaultExtensions: []`, does not disable ambient extensions. An agent's frontmatter list (including `[]`) suppresses the default; user and then project `agentOverrides.<name>.subagentOnlyExtensions` replace it or clear it with `false`. Lists are not combined.
+
+The two defaults resolve independently, with an explicitly present project value winning over the user value. If both are set, `defaultExtensions` still disables ambient discovery and the child-only paths are loaded alongside its allowlist. Both reject non-arrays, non-string or blank entries with an error naming the setting and source file. Extension paths execute trusted code, so use project defaults only for trusted repositories and extensions.
 
 ## Inspecting the live mapping
 

package/docs/observability.md

@@ -27,6 +27,12 @@ subagent({ action: "status", id: "..." })      // one run
 
 Or ask naturally: "Show me the current async runs."
 
+### Usage and cost accounting
+
+Run `/subagent-cost` for the parent session's combined parent and child token usage and cost. It includes completed async workflow children when their persisted receipts and metadata remain available. Missing child metadata is reported as unavailable when the receipt identifies that child. If the workflow receipt itself is missing, unreadable, invalid, or non-terminal, affected children can be omitted from the total without an unavailable count, so treat the result as a lower bound when run artifacts are unavailable.
+
+Pi's built-in session totals do not automatically include child usage delivered only by an async completion notification. Those notifications are custom messages, and Pi's public custom-message API does not carry accounted usage. `/subagent-cost` is therefore the supported accounting view for async child usage; do not infer child totals from Pi's footer or `/session` alone.
+
 The under-editor async widget gives a short view while work runs. Its expand key follows your Pi keybinding:
 
 ```text

package/docs/watchdog.md

@@ -181,3 +181,5 @@ Values are `allow`, `ask`, and `deny`. Agent rules override global ones, omitted
 `ask` pauses that exact tool call and sends a bounded, redacted preview to a one-call arbiter owned by the child watchdog, using the configured child-watchdog model. The arbiter returns only `approve` or `deny` and does not notify the parent. A disabled watchdog, missing model/auth, timeout, malformed response, or runtime error denies the call with a clear error. Requests and decisions are written to bounded audit JSONL. `contact_supervisor` and the optional `pi-intercom` extension are never permission-gated.
 
 Bash is always passed through; bash rules are rejected. Use `pi-guard` for command-level policy. Children are pi sessions inside the parent process (foreground) or the detached runner process (background), not separate `pi` binaries, so there is no per-child command wrapper; load `pi-guard` into a child through the agent's `extensions` or `subagentOnlyExtensions`, and background children also pick it up as an ambient extension. External CLI profiles are opaque processes, so native permissions cannot intercept their tools; launches with effective `ask` or `deny` rules are rejected for external CLI agents.
+
+Detached runners receive `PI_SUBAGENT_PARENT_SESSION` from their exact launch and retain it for that dedicated process. Root and in-process foreground hosts do not publish a global parent identity because multiple Pi sessions can share a host. Environment-only permission extensions therefore cannot safely forward foreground `ask` requests; that path remains unsupported until the extension accepts a session-scoped target. Native child permissions are unaffected.

package/docs/workflows.md

@@ -51,6 +51,10 @@ Workflow-level child controls default onto each `runs.run`/`runs.all` launch; ex
 
 Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
 
+Omitting a child's `async` preserves awaited final-result semantics, even if the child runs in the background. Explicit child `async: true` intentionally returns after launch: its receipt has `state: "running"`, `ok: false`, an empty `output`, and no completion error or final `outputReference`. `ok` confirms successful child completion, not successful dispatch. Use `runId` and `asyncDir` to inspect the running child; `artifactPaths` may include runtime directories and is not a list of final reports. Reusing the same workflow key returns the same receipt, not a refreshed result.
+
+A workflow can finish dispatch while these children remain running. Its summary and child rows identify that distinction, and launch receipts do not generate child-completion notices. Consume the later child result before treating its work or report as complete.
+
 Validate a script without launching children:
 
 ```js
@@ -292,7 +296,7 @@ subagent({ workflowScript: `
 ` });
 ```
 
-The workflow trace records the run completions and steering receipt. Scripts still never see raw async directories, inbox paths, or session files. If the keyed child is terminal, stale, or has no live route when `runs.steer` runs, the receipt reports `missed` or `failed` and the script can decide whether to continue.
+The workflow trace records the run completions and steering receipt. Scripts cannot access the filesystem or control inboxes; returned run and artifact references are data only. If the keyed child is terminal, stale, or has no live route when `runs.steer` runs, the receipt reports `missed` or `failed` and the script can decide whether to continue.
 
 Use named outputs when later workflow steps need structured data or durable references:
 
@@ -521,7 +525,7 @@ If messages do not show up, run `/subagents-doctor`. Advanced users can tune the
 
 Subagents can call `subagent` only when their resolved builtin tools explicitly include `subagent`. That is meant for delegated fanout agents, not ordinary worker/reviewer children. A depth guard prevents unbounded nesting.
 
-By default, nesting is limited to two levels: main session → subagent → sub-subagent. Deeper calls are blocked with guidance to complete the current task directly. Nested runs appear in the parent status widget and `status` output as a tree, and `status`, `interrupt`, and `resume` can target a nested run by its id.
+By default, nesting is limited to two levels: main session → subagent → sub-subagent. Deeper calls are blocked with guidance to complete the current task directly. Nested runs appear in the parent status widget and `status` output as a tree, and `status`, `interrupt`, and `resume` can target a nested run by its id. Coordinator completion and widget cleanup retain descendant lookup authority in the owning parent session; they do not grant access to another session or outside a child's authorized subtree.
 
 Configure the limit with:
 

package/index.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function registerSubagentExtension(pi: ExtensionAPI): void;
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAUpE,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAExE"}

package/index.js

@@ -0,0 +1,10 @@
+import { HERDR_PI_MODE_ENV } from "./src/runs/shared/herdr-pi-protocol.js";
+const registerExtension = process.env[HERDR_PI_MODE_ENV] === "1"
+    ? (await import("./src/extension/herdr-pi-bridge.js")).default
+    : process.env.PI_SUBAGENT_CHILD === "1"
+        ? undefined
+        : (await import("./src/extension/index.js")).default;
+export default function registerSubagentExtension(pi) {
+    registerExtension?.(pi);
+}
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAE3E,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG;IAC/D,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,oCAAoC,CAAC,CAAC,CAAC,OAAO;IAC9D,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG;QACvC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC,CAAC,OAAO,CAAC;AAEtD,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,EAAgB;IACjE,iBAAiB,EAAE,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}

package/package.json

@@ -1,27 +1,10 @@
 {
+  "type": "module",
   "name": "pi-subagents",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
-  "type": "module",
-  "exports": {
-    ".": "./index.ts",
-    "./background-work": "./src/api/background-work.ts",
-    "./external-job-provider": "./src/api/external-job-provider.ts",
-    "./external-runs": "./src/api/external-runs.ts",
-    "./agents": "./src/api/agents.ts",
-    "./delegation": "./src/api/delegation.ts",
-    "./capability-ceiling": "./src/api/capability-ceiling.ts",
-    "./workflow-resources": "./src/api/workflow-resources.ts",
-    "./required-child-extensions": "./src/api/required-child-extensions.ts",
-    "./preflight": "./src/api/preflight.ts",
-    "./control-channel": "./src/api/control-channel.ts",
-    "./intercom-bridge": "./src/api/intercom-bridge.ts",
-    "./child-tool-plan": "./src/api/child-tool-plan.ts",
-    "./shared-types": "./src/api/shared-types.ts",
-    "./project-panes": "./src/api/project-panes.ts"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nicobailon/pi-subagents.git"
@@ -30,48 +13,15 @@
   "bugs": {
     "url": "https://github.com/nicobailon/pi-subagents/issues"
   },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
-    "subagents",
-    "ai",
-    "agents",
-    "cli"
-  ],
   "bin": {
     "pi-subagents": "install.mjs"
   },
-  "files": [
-    "index.ts",
-    "src/**/*.ts",
-    "*.mjs",
-    "agents/",
-    "skills/**/*",
-    "prompts/**/*",
-    "docs/**/*",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "build:pkg": "node scripts/build-package.mjs",
-    "pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
-    "typecheck": "tsc --noEmit",
-    "test": "npm run test:unit",
-    "test:unit": "node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
-    "test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
-    "test:all": "npm run test:unit && npm run test:integration"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "skills": [
-      "./skills"
-    ],
-    "prompts": [
-      "./prompts"
-    ]
+  "dependencies": {
+    "acorn": "8.18.0",
+    "jiti": "2.7.0",
+    "typebox": "1.1.38",
+    "undici": "8.10.0",
+    "yaml": "2.8.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -93,21 +43,87 @@
       "optional": true
     }
   },
-  "dependencies": {
-    "acorn": "8.18.0",
-    "jiti": "2.7.0",
-    "typebox": "1.1.38",
-    "undici": "8.10.0",
-    "yaml": "2.8.3"
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "subagents",
+    "ai",
+    "agents",
+    "cli"
+  ],
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./background-work": {
+      "types": "./src/api/background-work.d.ts",
+      "default": "./src/api/background-work.js"
+    },
+    "./external-job-provider": {
+      "types": "./src/api/external-job-provider.d.ts",
+      "default": "./src/api/external-job-provider.js"
+    },
+    "./external-runs": {
+      "types": "./src/api/external-runs.d.ts",
+      "default": "./src/api/external-runs.js"
+    },
+    "./agents": {
+      "types": "./src/api/agents.d.ts",
+      "default": "./src/api/agents.js"
+    },
+    "./delegation": {
+      "types": "./src/api/delegation.d.ts",
+      "default": "./src/api/delegation.js"
+    },
+    "./capability-ceiling": {
+      "types": "./src/api/capability-ceiling.d.ts",
+      "default": "./src/api/capability-ceiling.js"
+    },
+    "./workflow-resources": {
+      "types": "./src/api/workflow-resources.d.ts",
+      "default": "./src/api/workflow-resources.js"
+    },
+    "./required-child-extensions": {
+      "types": "./src/api/required-child-extensions.d.ts",
+      "default": "./src/api/required-child-extensions.js"
+    },
+    "./preflight": {
+      "types": "./src/api/preflight.d.ts",
+      "default": "./src/api/preflight.js"
+    },
+    "./control-channel": {
+      "types": "./src/api/control-channel.d.ts",
+      "default": "./src/api/control-channel.js"
+    },
+    "./intercom-bridge": {
+      "types": "./src/api/intercom-bridge.d.ts",
+      "default": "./src/api/intercom-bridge.js"
+    },
+    "./child-tool-plan": {
+      "types": "./src/api/child-tool-plan.d.ts",
+      "default": "./src/api/child-tool-plan.js"
+    },
+    "./shared-types": {
+      "types": "./src/api/shared-types.d.ts",
+      "default": "./src/api/shared-types.js"
+    },
+    "./project-panes": {
+      "types": "./src/api/project-panes.d.ts",
+      "default": "./src/api/project-panes.js"
+    }
   },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.81.0",
-    "@earendil-works/pi-ai": "0.81.0",
-    "@earendil-works/pi-tui": "0.81.0",
-    "@oxlint/plugins": "1.80.0",
-    "@types/node": "24.13.3",
-    "oxlint": "1.80.0",
-    "typescript": "5.9.3",
-    "@earendil-works/pi-coding-agent": "file:./test/fixtures/pi-coding-agent-shim"
+  "pi": {
+    "extensions": [
+      "./index.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
   }
 }

package/runner-peer-loader.mjs

@@ -2,8 +2,6 @@ import { pathToFileURL } from "node:url";
 
 let aliases = {};
 let nativeRunner = false;
-let compiledRunner = false;
-let packageRootUrl;
 const redirected = new Set([
 	"@earendil-works/pi-tui",
 ]);
@@ -11,14 +9,13 @@ const redirected = new Set([
 export function initialize(data) {
 	aliases = data?.aliases ?? {};
 	nativeRunner = data?.nativeRunner === true;
-	compiledRunner = data?.compiledRunner === true;
-	packageRootUrl = data?.packageRootUrl;
 }
 
 export function resolve(specifier, context, nextResolve) {
-	const packageImport = typeof packageRootUrl === "string" && context.parentURL?.startsWith(packageRootUrl) === true;
-	if (nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier]) {
-		return nextResolve(pathToFileURL(aliases[specifier]).href, context);
+	const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
+	if (alias) {
+		const target = pathToFileURL(alias).href;
+		return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
 	}
 	return nextResolve(specifier, context);
 }

package/runner-peer-preload.mjs

@@ -3,9 +3,6 @@ import { pathToFileURL } from "node:url";
 
 const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
 const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
-const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
-// Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
-const packageRootUrl = new URL("./", import.meta.url).href;
 const redirected = new Set([
 	"@earendil-works/pi-tui",
 ]);
@@ -13,9 +10,10 @@ const redirected = new Set([
 if (typeof nodeModule.registerHooks === "function") {
 	nodeModule.registerHooks({
 		resolve(specifier, context, nextResolve) {
-			const packageImport = context.parentURL?.startsWith(packageRootUrl) === true;
-			if ((nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier])) {
-				return nextResolve(pathToFileURL(aliases[specifier]).href, context);
+			const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
+			if (alias) {
+				const target = pathToFileURL(alias).href;
+				return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
 			}
 			try {
 				return nextResolve(specifier, context);
@@ -27,6 +25,6 @@ if (typeof nodeModule.registerHooks === "function") {
 	});
 } else {
 	nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
-		data: { aliases, nativeRunner, compiledRunner, packageRootUrl },
+		data: { aliases, nativeRunner },
 	});
 }

package/skills/pi-subagents/references/prompting-and-roles.md

@@ -186,7 +186,7 @@ and user/project agents override builtins with the same name.
 | `oracle` | Rare hard-decision/root-cause escalation | top-reasoning critic tier, bounded read-only; high thinking escalation only | Advisory trajectory review, not routine code review |
 | `advisor` | Compatibility alias for `oracle` | top-reasoning critic tier, bounded read-only; high thinking escalation only | Same advisory escalation role as `oracle` |
 
-Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
+Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Agents without the corresponding field follow `subagents.defaultExtensions` or the ambient-preserving `subagents.defaultSubagentOnlyExtensions` when set.
 
 Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. The table records recommended tier routing, not shipped hard defaults; explicit run, user, or project settings still win. Keep the parent/orchestrator on the ordinary strong default model unless parent/user policy says otherwise. Override builtin defaults before copying full agent files when a small tweak is enough.
 
@@ -294,6 +294,6 @@ If a provider rejects model IDs with thinking suffixes, use
 builtin thinking defaults globally. A higher-precedence per-agent `thinking`
 override can opt one builtin back in or replace custom-agent frontmatter thinking.
 
-Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. A matching override replaces custom-agent frontmatter for that field.
+Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Set `subagents.defaultSubagentOnlyExtensions` to add shared child-only paths without disabling ambient discovery. For either field, explicit frontmatter suppresses the default and a matching override replaces or false-clears it; lists are not combined.
 
 Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.

package/src/agents/advertised-agent-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
+import type { AgentConfig } from "./agents.ts";
+export declare function buildAdvertisedAgentPrompt(agents: readonly AgentConfig[], capabilityCeiling?: ResolvedSubagentCapabilityCeiling): string | undefined;
+export declare function appendAdvertisedAgentPrompt(systemPrompt: string, advertisedPrompt: string | undefined): string;
+export declare function appendAdvertisedAgentPrompt(systemPrompt: string[], advertisedPrompt: string | undefined): string[];
+export declare function appendAdvertisedAgentPrompt(systemPrompt: undefined, advertisedPrompt: string | undefined): string | undefined;
+export declare function appendAdvertisedAgentPrompt(systemPrompt: string | string[] | undefined, advertisedPrompt: string | undefined): string | string[] | undefined;
+//# sourceMappingURL=advertised-agent-prompt.d.ts.map

package/src/agents/advertised-agent-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertised-agent-prompt.d.ts","sourceRoot":"","sources":["../../../src/agents/advertised-agent-prompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,sCAAsC,CAAC;AAE9F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAwB/C,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,iBAAiB,CAAC,EAAE,iCAAiC,GACnD,MAAM,GAAG,SAAS,CA2BpB;AAED,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAChH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAAC;AACpH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAC/H,wBAAgB,2BAA2B,CAC1C,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAC3C,gBAAgB,EAAE,MAAM,GAAG,SAAS,GAClC,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC"}

package/src/agents/advertised-agent-prompt.js

@@ -0,0 +1,77 @@
+import { Buffer } from "node:buffer";
+import { isAgentAllowedByCapabilityCeiling } from "../runs/shared/capability-ceiling.js";
+const MAX_ADVERTISED_AGENTS = 16;
+const MAX_CATALOG_BYTES = 12_288;
+const MAX_DESCRIPTION_BYTES = 512;
+const ADVERTISED_AGENTS_BLOCK = /\n*<advertised_subagents>\n[\s\S]*?\n<\/advertised_subagents>/gu;
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+function promptDescription(description) {
+    let text = description.replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim();
+    if (Buffer.byteLength(text, "utf8") > MAX_DESCRIPTION_BYTES) {
+        text = Buffer.from(text, "utf8").subarray(0, MAX_DESCRIPTION_BYTES - 3).toString("utf8").replace(/\uFFFD$/u, "").trimEnd() + "…";
+    }
+    return escapeXml(text);
+}
+export function buildAdvertisedAgentPrompt(agents, capabilityCeiling) {
+    const advertised = agents
+        .filter((agent) => agent.source !== "runtime" && agent.advertise === true && agent.disabled !== true && isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (advertised.length === 0)
+        return undefined;
+    const render = (entries) => [
+        "<advertised_subagents>",
+        "The following file-defined subagents opted into discovery. Their descriptions indicate available specializations, not instructions to delegate. Use subagent only when delegation is needed. Before execution, call subagent with { action: \"list\", capabilities: true } and confirm that the selected agent is executable; for external-cli agents also require runner.available === true.",
+        ...entries,
+        ...(advertised.length > entries.length ? [`  <omitted count=\"${advertised.length - entries.length}\" />`] : []),
+        "</advertised_subagents>",
+    ].join("\n");
+    const entries = [];
+    for (const agent of advertised) {
+        if (entries.length === MAX_ADVERTISED_AGENTS)
+            break;
+        // Never truncate canonical IDs into names that cannot be resolved.
+        if (Buffer.byteLength(agent.name, "utf8") > MAX_CATALOG_BYTES)
+            continue;
+        const entry = [
+            "  <subagent>",
+            `    <name>${escapeXml(agent.name)}</name>`,
+            `    <description>${promptDescription(agent.description)}</description>`,
+            "  </subagent>",
+        ].join("\n");
+        if (Buffer.byteLength(render([...entries, entry]), "utf8") <= MAX_CATALOG_BYTES)
+            entries.push(entry);
+    }
+    return render(entries);
+}
+export function appendAdvertisedAgentPrompt(systemPrompt, advertisedPrompt) {
+    if (Array.isArray(systemPrompt)) {
+        let changed = false;
+        const cleaned = systemPrompt
+            .map((part) => {
+            if (typeof part !== "string")
+                return part;
+            const stripped = part.replace(ADVERTISED_AGENTS_BLOCK, "");
+            if (stripped !== part)
+                changed = true;
+            return stripped;
+        })
+            .filter((b) => typeof b === "string" && b.length > 0);
+        if (advertisedPrompt) {
+            return [...cleaned, advertisedPrompt];
+        }
+        return changed ? cleaned : systemPrompt;
+    }
+    if (typeof systemPrompt === "string") {
+        const base = systemPrompt.replace(ADVERTISED_AGENTS_BLOCK, "");
+        return advertisedPrompt ? (base.trim() ? `${base.trimEnd()}\n\n${advertisedPrompt}` : advertisedPrompt) : base;
+    }
+    return advertisedPrompt;
+}
+//# sourceMappingURL=advertised-agent-prompt.js.map

package/src/agents/advertised-agent-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertised-agent-prompt.js","sourceRoot":"","sources":["../../../src/agents/advertised-agent-prompt.ts"],"names":[],"mappings":"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"}