pi-subagents 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-06-19
+
+### Added
+- Added package-provided agent and chain discovery from installed Pi packages and package settings, including read-only management behavior, package source counts in doctor output, nested-cwd project package discovery, and package definitions that remain below user/project overrides. Thanks to Fabian Jocks (@iamfj) for #278.
+- Added `PI_SUBAGENT_EXTRA_AGENT_DIRS` and `PI_INTERCOM_EXTENSION_DIR` overrides so bundled agents and `pi-intercom` can be loaded from read-only package locations. Thanks to David Barroso (@dbarrosop) for #288.
+
+### Fixed
+- Show captured output from failed foreground subagents instead of returning only the failure summary. Thanks to Jürgen Schmied (@jschmied) for #277.
+- Preserve nested fanout child subagent history when building child prompts. Thanks to James Wood (@jamesjwood) for the original #270 fix.
+- Retry Windows atomic JSON renames on transient `EPERM`, `EBUSY`, and `EACCES` failures. Thanks to Wings Butterfly (@wings1848) for #269.
+- Inherit the parent session model for subagents instead of falling back to global settings, including foreground, chain, async chain, async single, and resume/revive paths. Thanks to Rogerio Saulo (@rsaulo) for #266 and Nicolas Marchildon (@elecnix) for the original #283 fix.
+- Avoid duplicate `subagent` tool registration in fanout-authorized child processes. Thanks to Aleksei Gurianov (@Guria) for #279.
+- Hardened the parallel intercom integration test fixture after Windows CI exposed nondeterministic failure ordering.
+
+## [0.28.0] - 2026-06-03
+
+### Added
+- Added foreground-only `timeoutMs`/`maxRuntimeMs` for single, parallel, and chain subagent runs. Timed-out children are soft-interrupted, keep completed sibling/prior results, and return `timedOut: true` with a stable timeout message.
+- Added per-agent `maxExecutionTimeMs` and `maxTokens` resource limits. Foreground and async children stop with a clear `resourceLimitExceeded` result when the configured runtime or observed token budget is reached.
+
+### Changed
+- Strengthened tool and skill guidance so writer subagents launched from plans, specs, issues, or broad fixes proactively use structured `acceptance` instead of burying validation requirements only in task prose.
+
+### Fixed
+- Removed a provider-unfriendly required-only subschema from the public `acceptance` tool schema so Kimi models served through OpenCode Go can load the `subagent` tool, while keeping runtime validation for empty acceptance contracts.
+- Clarified acceptance-report prompts so required evidence like `diff-summary` must be copied into structured JSON fields such as `diffSummary`, not only described in visible prose.
+
 ## [0.27.0] - 2026-05-30
 
 ### Changed

package/README.md

@@ -358,10 +358,11 @@ Agent locations, lowest to highest priority:
 | Scope | Path |
 |-------|------|
 | Builtin | `~/.pi/agent/extensions/subagent/agents/` |
+| Installed package | `package.json` `pi-subagents.agents` or `pi.subagents.agents` |
 | User | `~/.pi/agent/agents/**/*.md` |
 | Project | `.pi/agents/**/*.md` |
 
-Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files do not define agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
+Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files do not define agents. Installed Pi packages can expose agent directories from either `{"pi-subagents":{"agents":["./agents"]}}` or `{"pi":{"subagents":{"agents":["./agents"]}}}` in their package manifest. Package agents load above builtins and below user/project agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
 
 Builtin agents load at the lowest priority, so a user or project agent with the same name overrides them. They do not pin a provider model; they inherit your current Pi default model unless you set `subagents.agentOverrides.<name>.model`. `oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `worker` is the implementation agent for normal tasks and approved oracle handoffs.
 
@@ -496,10 +497,11 @@ Chains are reusable workflows stored separately from agent files. Use `.chain.md
 
 | Scope | Path |
 |-------|------|
+| Installed package | `package.json` `pi-subagents.chains` or `pi.subagents.chains` |
 | User | `~/.pi/agent/chains/**/*.chain.md`, `~/.pi/agent/chains/**/*.chain.json` |
 | Project | `.pi/chains/**/*.chain.md`, `.pi/chains/**/*.chain.json` |
 
-Nested subdirectories are discovered recursively. If both `.chain.md` and `.chain.json` define the same parsed runtime chain name in the same scope, `.chain.json` wins. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
+Nested subdirectories are discovered recursively. Installed Pi packages can expose chain directories from either `{"pi-subagents":{"chains":["./chains"]}}` or `{"pi":{"subagents":{"chains":["./chains"]}}}` in their package manifest. Package chains load below user/project chains. If both `.chain.md` and `.chain.json` define the same parsed runtime chain name in the same scope, `.chain.json` wins. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
 
 Example:
 
@@ -794,7 +796,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `tasks` | array | - | Top-level parallel tasks. Supports `agent`, `task`, `cwd`, `count`, `output`, `outputMode`, `reads`, `progress`, `skill`, `model`, and `acceptance`. |
 | `concurrency` | number | config or `4` | Top-level parallel concurrency. |
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
-| `chain` | array | - | Sequential, static parallel, and dynamic fanout chain steps. Sequential steps and parallel child tasks support `phase`, `label`, `as`, `outputSchema`, and `acceptance` in addition to the usual execution fields. Dynamic fanout uses `expand`, one child `parallel` template, and `collect`; group-level acceptance is not supported because there is no child session to finalize. |
+| `chain` | array | - | Sequential, static parallel, and dynamic fanout chain steps. Steps and chain parallel tasks support `phase`, `label`, `as`, `outputSchema`, and `acceptance` in addition to the usual execution fields. Dynamic fanout uses `expand`, one child `parallel` template, and `collect`. |
 | `context` | `fresh \| fork` | agent default or `fresh` | `fork` creates real branched sessions from the parent leaf. Packaged `planner`, `worker`, and `oracle` default to `fork`. |
 | `chainDir` | string | temp chain dir | Persistent directory for chain artifacts. |
 | `clarify` | boolean | true for chains | Show TUI preview/edit flow. |
@@ -806,7 +808,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `includeProgress` | boolean | false | Include full progress in result. |
 | `share` | boolean | false | Upload session export to GitHub Gist. |
 | `sessionDir` | string | derived | Override session log directory. |
-| `acceptance` | object | omitted | Explicit acceptance contract. When present, the child gets a structured contract, then the runtime continues the same session for a bounded self-review/repair loop before evaluating acceptance. |
+| `acceptance` | string/object/false | inferred | Override the run's inferred acceptance gates. Use `"auto"`, `"attested"`, `"checked"`, `"verified"`, `"reviewed"`, or `{ level: "none", reason: "..." }`. |
 
 `context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or the branched child session cannot be created. It never silently downgrades to `fresh`. In multi-agent runs, if any requested agent has `defaultContext: fork` and the launch omits `context`, the whole invocation uses forked context; pass `context: "fresh"` when you intentionally want a fresh run.
 
@@ -989,34 +991,33 @@ Async runs write:
 
 ## Acceptance Gates
 
-`acceptance` is an explicit contract. Omit it for lightweight runs. Set it on single runs, top-level parallel task items, sequential chain steps, static parallel task items, and dynamic fanout child templates when the child must prove the work meets concrete criteria. Do not set it on static parallel groups or dynamic fanout aggregate groups; those groups do not own a same-session child turn.
-
-If you are coming from Codex Goals, `acceptance` is the subagent equivalent for one delegated run. When a user says `/goal`, “goal”, “active goal”, “continue until evidence says done”, or “verify against a goal”, translate that into an acceptance contract: `criteria` are the target, `evidence` and `verify` are proof, `stopRules` are constraints, and `maxFinalizationTurns` is the bounded loop budget.
+Every run resolves an effective acceptance policy. Callers may omit `acceptance` for the inferred default, or set it on single runs, top-level parallel task items, chain steps, static parallel tasks, and dynamic fanout templates.
 
 ```ts
 {
   agent: "worker",
   task: "Implement the fix",
   acceptance: {
+    level: "verified",
     criteria: ["Patch the bug without widening scope"],
     evidence: ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"],
-    verify: [{ id: "focused", command: "npm test", timeoutMs: 120000 }],
-    maxFinalizationTurns: 3
+    verify: [{ id: "focused", command: "npm test", timeoutMs: 120000 }]
   }
 }
 ```
 
-When `acceptance` is present, the initial child prompt includes a standardized acceptance section and asks for a fenced `acceptance-report` JSON block. After the child’s initial completion, the runtime continues the same persisted child session with an acceptance finalization prompt. The child can repair omissions in that same session, then must return the final `acceptance-report`. Missing or malformed finalization reports reject the run when the loop limit is reached.
+Accepted levels are `auto`, `none`, `attested`, `checked`, `verified`, and `reviewed`. `acceptance: "auto"` is the default. Read-only reviewer/scout tasks infer lightweight attestation, normal writer tasks infer checked evidence, and async/risky/dynamic writer contexts infer a reviewed gate. To disable gates, prefer `{ level: "none", reason: "..." }`.
 
-Public acceptance config is evidence-driven. There is no public `level` field and no `acceptance: "checked"` shorthand. Runtime provenance is derived from what actually happened:
+Acceptance provenance is stored separately from child prose:
 
-- `attested`: the child returned a structured acceptance report.
-- `checked`: runtime structural checks passed, such as required criteria, required evidence, and no staged files.
+- `claimed`: child finished but did not provide structured evidence.
+- `attested`: child returned a structured acceptance report.
+- `checked`: runtime structural checks passed, such as required evidence and no staged files.
 - `verified`: configured runtime verification commands passed. Child-reported command success does not count.
 - `reviewed`: an independent reviewer result is present.
-- `rejected`: attestation, structural checks, verification, review, or finalization failed.
+- `rejected`: attestation, structural checks, verification, or review failed.
 
-Self-review finalization never counts as `reviewed`, and it never counts as `verified` unless configured runtime verification commands actually pass. The visible child output remains the initial answer; finalization reports and residual risks are stored in the acceptance ledger and async/status details.
+For `attested` or stricter levels, the child prompt includes a standardized acceptance section and asks for a fenced `acceptance-report` JSON block. Explicit failed gates fail the run. Inferred gates are persisted for observability without breaking older calls that omit `acceptance`.
 
 ## Live progress
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/pi-subagents/SKILL.md

@@ -692,9 +692,7 @@ clarify → validation contract → planner → async worker → parallel async
 
 The validation contract defines acceptance before code is written: expected behavior, acceptance checks, commands or user flows to exercise, and evidence the worker should return. Keep it lightweight for small tasks, but make it explicit enough that reviewers and validators are checking the intended outcome rather than the worker’s own assumptions.
 
-Use the structured `acceptance` field when the run should carry an explicit acceptance contract. If omitted, the run stays lightweight. When present, acceptance is object-only: define concrete `criteria`, required `evidence`, optional runtime `verify` commands, optional independent `review`, and optionally `maxFinalizationTurns`. The runtime continues the same child session for a bounded self-review/repair loop before evaluating the final report, so set `acceptance` on single runs, sequential chain steps, parallel task items, and dynamic fanout child templates, not on static parallel or dynamic fanout groups. Do not call a run reviewed just because the worker says it is done; reviewed means a reviewer gate returned a result. Child-reported command success is evidence, not runtime verification.
-
-Goal-style requests map to `acceptance`. If the user says `/goal`, “goal”, “active goal”, “continue until evidence says done”, or “verify against a goal” for a subagent run, create an explicit run-scoped acceptance contract: `criteria` for the target, `evidence` and `verify` for proof, `stopRules` for constraints, and `maxFinalizationTurns` for the bounded loop budget.
+Use the structured `acceptance` field when the run should carry an explicit acceptance contract. If omitted, subagents infer an effective acceptance policy from role, mode, and risk. Use `level: "checked"` for ordinary writer evidence gates, `level: "verified"` when the runtime should run explicit validation commands, and `level: "reviewed"` only when an independent reviewer result is expected. Do not call a run reviewed just because the worker says it is done; reviewed means a reviewer gate returned a result. Child-reported command success is evidence, not runtime verification.
 
 The first `worker` implements the approved plan. The parent continues with independent inspection or validation prep while it runs, not parallel edits to the same worktree. When the async worker completes, treat its handoff as the transition into review, not as final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Parallel reviewers inspect the resulting diff from fresh context. Validators check behavior with the best available evidence: commands, tests, browser/CLI interaction, screenshots, logs, or manual reproduction notes. The final `worker` applies synthesized review fixes in forked context, then the parent looks over the final diff before completing. The parent may launch these steps as an initial async chain when the workflow is already clear, or as follow-up subagent runs after each async completion. Initial chains should pass `async: true` so the main chat is unblocked; avoid `clarify: true` unless the user asked for foreground clarification. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
 
@@ -723,9 +721,8 @@ subagent({
   agent: "worker",
   task: "Implement the approved feature.\n\nClarified requirements:\n- ...\n\nPlan: see ~/Documents/docs/...-plan.md\n\nValidation contract:\n- ...\n\nReturn a handoff with changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises/new risks, and decisions needing parent approval.",
   acceptance: {
-    criteria: ["Implement the approved feature without widening scope"],
-    evidence: ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"],
-    maxFinalizationTurns: 3
+    level: "checked",
+    evidence: ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"]
   },
   async: true
 })

package/src/agents/agent-management.ts

@@ -78,8 +78,8 @@ function parsePackageConfig(value: unknown): { packageName?: string; error?: str
 	return parsePackageName(value, "config.package");
 }
 
-function allAgents(d: { builtin: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): AgentConfig[] {
-	return [...d.builtin, ...d.user, ...d.project];
+function allAgents(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): AgentConfig[] {
+	return [...d.builtin, ...d.package, ...d.user, ...d.project];
 }
 
 function availableNames(cwd: string, kind: "agent" | "chain"): string[] {
@@ -116,6 +116,10 @@ function nameExistsInScope(cwd: string, scope: ManagementScope, name: string, ex
 	return false;
 }
 
+function isMutableSource(source: AgentSource): source is ManagementScope {
+	return source === "user" || source === "project";
+}
+
 function unknownChainAgents(cwd: string, steps: ChainStepConfig[]): string[] {
 	const d = discoverAgentsAll(cwd);
 	const known = new Set(allAgents(d).map((a) => a.name));
@@ -327,10 +331,10 @@ function resolveTarget<T extends { source: AgentSource; filePath: string }>(
 	cwd: string,
 	scopeHint?: string,
 ): T | AgentToolResult<Details> {
-	const mutable = matches.filter((m) => m.source !== "builtin");
+	const mutable = matches.filter((m): m is T & { source: ManagementScope } => isMutableSource(m.source));
 	if (mutable.length === 0) {
 		if (matches.length > 0) {
-			return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' is builtin and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`, true);
+			return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' is read-only and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`, true);
 		}
 		const available = availableNames(cwd, kind);
 		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${available.join(", ") || "none"}.`, true);
@@ -442,9 +446,9 @@ function formatChainDetail(chain: ChainConfig): string {
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
-	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === "package" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const agents = scopedAgents.filter((a) => !a.disabled);
-	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const chains = d.chains.filter((c) => scope === "both" || c.source === "package" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const diagnostics = d.chainDiagnostics.filter((entry) => scope === "both" || entry.source === scope);
 	const lines = [
 		"Executable agents:",

package/src/agents/agent-selection.ts

@@ -5,10 +5,12 @@ export function mergeAgentsForScope(
 	userAgents: AgentConfig[],
 	projectAgents: AgentConfig[],
 	builtinAgents: AgentConfig[] = [],
+	packageAgents: AgentConfig[] = [],
 ): AgentConfig[] {
 	const agentMap = new Map<string, AgentConfig>();
 
 	for (const agent of builtinAgents) agentMap.set(agent.name, agent);
+	for (const agent of packageAgents) agentMap.set(agent.name, agent);
 
 	if (scope === "both") {
 		for (const agent of userAgents) agentMap.set(agent.name, agent);

package/src/agents/agents.ts

@@ -2,6 +2,7 @@
  * Agent discovery and configuration
  */
 
+import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -17,7 +18,7 @@ export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./
 
 export type AgentScope = "user" | "project" | "both";
 
-export type AgentSource = "builtin" | "user" | "project";
+export type AgentSource = "builtin" | "package" | "user" | "project";
 type SystemPromptMode = "append" | "replace";
 export type AgentDefaultContext = "fresh" | "fork";
 
@@ -141,7 +142,7 @@ export interface ChainConfig {
 }
 
 export interface ChainDiscoveryDiagnostic {
-	source: "user" | "project";
+	source: AgentSource;
 	filePath: string;
 	error: string;
 }
@@ -155,6 +156,259 @@ function getUserChainDir(): string {
 	return path.join(getAgentDir(), "chains");
 }
 
+interface PackageSubagentPaths {
+	agents: string[];
+	chains: string[];
+}
+
+let cachedGlobalNpmRoot: string | null = null;
+
+function readJsonFileBestEffort(filePath: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch {
+		// Installed package scans are opportunistic; bad third-party manifests
+		// should not break local agent discovery.
+		return null;
+	}
+}
+
+function readOptionalJsonFile(filePath: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch (error) {
+		const code = typeof error === "object" && error !== null && "code" in error
+			? (error as { code?: unknown }).code
+			: undefined;
+		if (code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+function isSafePackagePath(value: string): boolean {
+	return value.length > 0
+		&& !path.isAbsolute(value)
+		&& value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+
+function parseNpmPackageName(source: string): string | undefined {
+	const spec = source.slice(4).trim();
+	if (!spec) return undefined;
+	const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
+	const packageName = match?.[1] ?? spec;
+	return isSafePackagePath(packageName) ? packageName : undefined;
+}
+
+function stripGitRef(repoPath: string): string {
+	const atIndex = repoPath.indexOf("@");
+	const hashIndex = repoPath.indexOf("#");
+	const refIndex = [atIndex, hashIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];
+	return refIndex === undefined ? repoPath : repoPath.slice(0, refIndex);
+}
+
+function parseGitPackagePath(source: string): { host: string; repoPath: string } | undefined {
+	const spec = source.slice(4).trim();
+	if (!spec) return undefined;
+
+	let host = "";
+	let repoPath = "";
+	const scpLike = spec.match(/^git@([^:]+):(.+)$/);
+	if (scpLike) {
+		host = scpLike[1] ?? "";
+		repoPath = scpLike[2] ?? "";
+	} else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec)) {
+		try {
+			const url = new URL(spec);
+			host = url.hostname;
+			repoPath = url.pathname.replace(/^\/+/, "");
+		} catch {
+			return undefined;
+		}
+	} else {
+		const slashIndex = spec.indexOf("/");
+		if (slashIndex < 0) return undefined;
+		host = spec.slice(0, slashIndex);
+		repoPath = spec.slice(slashIndex + 1);
+	}
+
+	const normalizedPath = stripGitRef(repoPath).replace(/\.git$/, "").replace(/^\/+/, "");
+	if (!host || !isSafePackagePath(host) || !isSafePackagePath(normalizedPath) || normalizedPath.split(/[\\/]/).length < 2) {
+		return undefined;
+	}
+	return { host, repoPath: normalizedPath };
+}
+
+function resolveSettingsPackageRoot(source: string, baseDir: string): string | undefined {
+	const trimmed = source.trim();
+	if (!trimmed) return undefined;
+	if (trimmed.startsWith("git:")) {
+		const parsed = parseGitPackagePath(trimmed);
+		return parsed ? path.join(baseDir, "git", parsed.host, parsed.repoPath) : undefined;
+	}
+	if (trimmed.startsWith("npm:")) {
+		const packageName = parseNpmPackageName(trimmed);
+		return packageName ? path.join(baseDir, "npm", "node_modules", packageName) : undefined;
+	}
+	const normalized = trimmed.startsWith("file:") ? trimmed.slice(5) : trimmed;
+	if (normalized === "~") return os.homedir();
+	if (normalized.startsWith("~/")) return path.join(os.homedir(), normalized.slice(2));
+	if (path.isAbsolute(normalized)) return normalized;
+	if (normalized === "." || normalized === ".." || normalized.startsWith("./") || normalized.startsWith("../")) {
+		return path.resolve(baseDir, normalized);
+	}
+	return undefined;
+}
+
+function getGlobalNpmRoot(): string | null {
+	if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
+	try {
+		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
+		return cachedGlobalNpmRoot;
+	} catch {
+		cachedGlobalNpmRoot = "";
+		return null;
+	}
+}
+
+function stringArray(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
+}
+
+function extractSubagentPathsFromPackageRoot(packageRoot: string): PackageSubagentPaths {
+	const packageJsonPath = path.join(packageRoot, "package.json");
+	const pkg = readJsonFileBestEffort(packageJsonPath);
+	if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return { agents: [], chains: [] };
+
+	const roots: Record<string, unknown>[] = [];
+	const piSubagents = (pkg as { "pi-subagents"?: unknown })["pi-subagents"];
+	if (piSubagents && typeof piSubagents === "object" && !Array.isArray(piSubagents)) {
+		roots.push(piSubagents as Record<string, unknown>);
+	}
+
+	const pi = (pkg as { pi?: unknown }).pi;
+	if (pi && typeof pi === "object" && !Array.isArray(pi)) {
+		const subagents = (pi as { subagents?: unknown }).subagents;
+		if (subagents && typeof subagents === "object" && !Array.isArray(subagents)) {
+			roots.push(subagents as Record<string, unknown>);
+		}
+	}
+
+	const agents: string[] = [];
+	const chains: string[] = [];
+	for (const root of roots) {
+		for (const entry of stringArray(root.agents)) agents.push(path.resolve(packageRoot, entry));
+		for (const entry of stringArray(root.chains)) chains.push(path.resolve(packageRoot, entry));
+	}
+	return { agents, chains };
+}
+
+function collectPackageRootsFromNodeModules(nodeModulesDir: string): string[] {
+	const roots: string[] = [];
+	if (!fs.existsSync(nodeModulesDir)) return roots;
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(nodeModulesDir, { withFileTypes: true });
+	} catch {
+		return roots;
+	}
+
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+		if (entry.name.startsWith("@")) {
+			const scopeDir = path.join(nodeModulesDir, entry.name);
+			let scopeEntries: fs.Dirent[];
+			try {
+				scopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const scopeEntry of scopeEntries) {
+				if (scopeEntry.name.startsWith(".")) continue;
+				if (!scopeEntry.isDirectory() && !scopeEntry.isSymbolicLink()) continue;
+				roots.push(path.join(scopeDir, scopeEntry.name));
+			}
+			continue;
+		}
+
+		roots.push(path.join(nodeModulesDir, entry.name));
+	}
+	return roots;
+}
+
+function collectSettingsPackageRoots(settingsFile: string, baseDir: string): string[] {
+	const settings = readOptionalJsonFile(settingsFile);
+	if (!settings || typeof settings !== "object" || Array.isArray(settings)) return [];
+	const packages = (settings as { packages?: unknown }).packages;
+	if (!Array.isArray(packages)) return [];
+
+	const roots: string[] = [];
+	for (const entry of packages) {
+		const packageSource = typeof entry === "string"
+			? entry
+			: typeof entry === "object" && entry !== null && typeof (entry as { source?: unknown }).source === "string"
+				? (entry as { source: string }).source
+				: undefined;
+		if (!packageSource) continue;
+		const packageRoot = resolveSettingsPackageRoot(packageSource, baseDir);
+		if (packageRoot) roots.push(packageRoot);
+	}
+	return roots;
+}
+
+function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolean; includeProject: boolean } = { includeUser: true, includeProject: true }): PackageSubagentPaths {
+	const agentDir = getAgentDir();
+	const projectRoot = findNearestProjectRoot(cwd) ?? cwd;
+	const packageRoots = [
+		projectRoot,
+	];
+
+	if (options.includeProject) {
+		packageRoots.push(
+			...collectPackageRootsFromNodeModules(path.join(projectRoot, ".pi", "npm", "node_modules")),
+			...collectSettingsPackageRoots(path.join(projectRoot, ".pi", "settings.json"), path.join(projectRoot, ".pi")),
+		);
+	}
+
+	if (options.includeUser) {
+		packageRoots.push(
+			...collectPackageRootsFromNodeModules(path.join(agentDir, "npm", "node_modules")),
+			...collectSettingsPackageRoots(path.join(agentDir, "settings.json"), agentDir),
+		);
+	}
+
+	if (options.includeUser) {
+		const globalRoot = getGlobalNpmRoot();
+		if (globalRoot) packageRoots.push(...collectPackageRootsFromNodeModules(globalRoot));
+	}
+
+	const seenRoots = new Set<string>();
+	const seenAgents = new Set<string>();
+	const seenChains = new Set<string>();
+	const agents: string[] = [];
+	const chains: string[] = [];
+	for (const packageRoot of packageRoots) {
+		const resolvedRoot = path.resolve(packageRoot);
+		if (seenRoots.has(resolvedRoot)) continue;
+		seenRoots.add(resolvedRoot);
+		const paths = extractSubagentPathsFromPackageRoot(resolvedRoot);
+		for (const agentDir of paths.agents) {
+			if (seenAgents.has(agentDir)) continue;
+			seenAgents.add(agentDir);
+			agents.push(agentDir);
+		}
+		for (const chainDir of paths.chains) {
+			if (seenChains.has(chainDir)) continue;
+			seenChains.add(chainDir);
+			chains.push(chainDir);
+		}
+	}
+	return { agents, chains };
+}
+
 function splitToolList(rawTools: string[] | undefined): { tools?: string[]; mcpDirectTools?: string[] } {
 	const mcpDirectTools: string[] = [];
 	const tools: string[] = [];
@@ -706,7 +960,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	return agents;
 }
 
-function loadChainsFromDir(dir: string, source: "user" | "project"): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
+function loadChainsFromDir(dir: string, source: AgentSource): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
 	const chains = new Map<string, ChainConfig>();
 	const diagnostics: ChainDiscoveryDiagnostic[] = [];
 
@@ -768,6 +1022,22 @@ function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; pref
 }
 const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
 
+export const EXTRA_AGENT_DIRS_ENV = "PI_SUBAGENT_EXTRA_AGENT_DIRS";
+
+// Additional read-only directories to scan for agent definitions, supplied by the
+// launcher via PI_SUBAGENT_EXTRA_AGENT_DIRS (PATH-style, split on os/path delimiter).
+// Lets a hermetic wrapper (e.g. a Nix-store install) expose bundled agents without
+// copying or symlinking them into the writable agent dir. Loaded as "user" source,
+// at lower precedence than agents the user placed in their own agent dir.
+function extraUserAgentDirs(): string[] {
+	const raw = process.env[EXTRA_AGENT_DIRS_ENV];
+	if (!raw) return [];
+	return raw
+		.split(path.delimiter)
+		.map((dir) => dir.trim())
+		.filter((dir) => dir.length > 0);
+}
+
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
 	const userDirOld = path.join(getAgentDir(), "agents");
 	const userDirNew = path.join(os.homedir(), ".agents");
@@ -776,6 +1046,10 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
 	const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
+	const packageSubagentPaths = collectPackageSubagentPaths(cwd, {
+		includeUser: scope !== "project",
+		includeProject: scope !== "user",
+	});
 
 	const builtinAgents = applyBuiltinOverrides(
 		loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"),
@@ -785,12 +1059,14 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 		projectSettingsPath,
 	);
 
+	const userAgentsExtra = scope === "project" ? [] : extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user"));
 	const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
 	const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
-	const userAgents = [...userAgentsOld, ...userAgentsNew];
+	const userAgents = [...userAgentsExtra, ...userAgentsOld, ...userAgentsNew];
 
 	const projectAgents = scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project"));
-	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents)
+	const packageAgents = packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package"));
+	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
 		.filter((agent) => agent.disabled !== true);
 
 	return { agents, projectAgentsDir };
@@ -798,6 +1074,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 
 export function discoverAgentsAll(cwd: string): {
 	builtin: AgentConfig[];
+	package: AgentConfig[];
 	user: AgentConfig[];
 	project: AgentConfig[];
 	chains: ChainConfig[];
@@ -818,6 +1095,7 @@ export function discoverAgentsAll(cwd: string): {
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = readSubagentSettings(userSettingsPath);
 	const projectSettings = readSubagentSettings(projectSettingsPath);
+	const packageSubagentPaths = collectPackageSubagentPaths(cwd);
 
 	const builtin = applyBuiltinOverrides(
 		loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"),
@@ -827,9 +1105,17 @@ export function discoverAgentsAll(cwd: string): {
 		projectSettingsPath,
 	);
 	const user = [
+		...extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user")),
 		...loadAgentsFromDir(userDirOld, "user"),
 		...loadAgentsFromDir(userDirNew, "user"),
 	];
+	const packageMap = new Map<string, AgentConfig>();
+	for (const dir of packageSubagentPaths.agents) {
+		for (const agent of loadAgentsFromDir(dir, "package")) {
+			if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
+		}
+	}
+	const packageAgents = Array.from(packageMap.values());
 	const projectMap = new Map<string, AgentConfig>();
 	for (const dir of projectDirs) {
 		for (const agent of loadAgentsFromDir(dir, "project")) {
@@ -839,6 +1125,15 @@ export function discoverAgentsAll(cwd: string): {
 	const project = Array.from(projectMap.values());
 
 	const chainMap = new Map<string, ChainConfig>();
+	const packageChainDiagnostics: ChainDiscoveryDiagnostic[] = [];
+	const packageChainMap = new Map<string, ChainConfig>();
+	for (const dir of packageSubagentPaths.chains) {
+		const loaded = loadChainsFromDir(dir, "package");
+		packageChainDiagnostics.push(...loaded.diagnostics);
+		for (const chain of loaded.chains) {
+			if (!packageChainMap.has(chain.name)) packageChainMap.set(chain.name, chain);
+		}
+	}
 	const projectChainDiagnostics: ChainDiscoveryDiagnostic[] = [];
 	for (const dir of projectChainDirs) {
 		const loaded = loadChainsFromDir(dir, "project");
@@ -849,15 +1144,17 @@ export function discoverAgentsAll(cwd: string): {
 	}
 	const userChains = loadChainsFromDir(userChainDir, "user");
 	const chains = [
+		...Array.from(packageChainMap.values()),
 		...userChains.chains,
 		...Array.from(chainMap.values()),
 	];
 	const chainDiagnostics = [
+		...packageChainDiagnostics,
 		...userChains.diagnostics,
 		...projectChainDiagnostics,
 	];
 
 	const userDir = process.env.PI_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
 
-	return { builtin, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
+	return { builtin, package: packageAgents, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
 }