pi-subagents 0.21.3 → 0.21.5

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.21.5] - 2026-05-02
+
+### Fixed
+- Show top-level async parallel runs as `parallel` instead of `chain`, with foreground-style running/done wording in widgets and status output, and group running async chain detail by chain step.
+- Scoped `/subagents-status` to async runs launched from the current pi session instead of showing prior or unrelated sessions.
+- Declared the Pi TUI package as a direct dev dependency and added a manifest guard so CI installs do not rely on transitive optional peer dependencies for tests.
+- Made prompt-runtime extension path assertions portable on Windows.
+
+## [0.21.4] - 2026-05-01
+
+### Added
+- Added explicit frontmatter `package` identifiers for agents and saved chains, registering runtime names like `code-analysis.scout` while preserving separate `name` and `package` fields on save.
+- Added recursive subdirectory discovery for user and project agent and chain definitions.
+- Added `outputMode: "inline" | "file-only"` for saved subagent outputs. `inline` remains the default, while `file-only` returns a concise saved-file reference instead of injecting full saved output back into the parent context.
+
+### Fixed
+- Marked Pi runtime peer dependencies as optional so npm package installs do not auto-install duplicate Pi packages or emit unrelated transitive dependency warnings.
+
 ## [0.21.3] - 2026-04-30
 
 ### Fixed

package/README.md

@@ -150,12 +150,14 @@ Use `~/.pi/agent/settings.json` for a user override or `.pi/settings.json` for a
 
 Foreground runs stream progress in the conversation while they run.
 
-Background runs keep working after control returns to you. They show completion notifications and can be inspected with:
+Background runs keep working after control returns to you. They show a compact async widget, send completion notifications, and can be inspected with:
 
 ```text
 /subagents-status
 ```
 
+The status view shows active and recent runs for the current Pi session. Parallel background runs are shown as parallel work, with per-agent progress instead of fake chain steps. Chains with parallel groups keep their grouped shape in both progress and results views, so failed or paused agents stay visible next to completed ones.
+
 You can also ask naturally:
 
 ```text
@@ -298,12 +300,13 @@ Append `[key=value,...]` to an agent name to override defaults for that step:
 | Key | Example | Description |
 |-----|---------|-------------|
 | `output` | `output=context.md` | Write results to a file. For `/chain` and `/parallel`, relative paths live under the chain directory; for `/run`, relative paths resolve against cwd. |
+| `outputMode` | `outputMode=file-only` | Return only a concise file reference for saved output instead of the full saved content. Requires `output`; default is `inline`. |
 | `reads` | `reads=a.md+b.md` | Read files before executing. `+` separates multiple paths. |
 | `model` | `model=anthropic/claude-sonnet-4` | Override model for this step. |
 | `skills` | `skills=planning+review` | Override injected skills. `+` separates multiple skills. |
 | `progress` | `progress` | Enable progress tracking. |
 
-Set `output=false`, `reads=false`, or `skills=false` to disable that behavior explicitly.
+Set `output=false`, `reads=false`, or `skills=false` to disable that behavior explicitly. Do not use `output=false` for file-only returns; use `outputMode=file-only` with an `output` path.
 
 ### Background and forked runs
 
@@ -396,10 +399,10 @@ Agent locations, lowest to highest priority:
 | Scope | Path |
 |-------|------|
 | Builtin | `~/.pi/agent/extensions/subagent/agents/` |
-| User | `~/.pi/agent/agents/{name}.md` |
-| Project | `.pi/agents/{name}.md` |
+| User | `~/.pi/agent/agents/**/*.md` |
+| Project | `.pi/agents/**/*.md` |
 
-Project discovery also reads legacy `.agents/{name}.md` files. If both `.agents/` and `.pi/agents/` define the same project agent, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win name collisions.
+Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files are treated as chains, not 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. `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.
 
@@ -458,6 +461,8 @@ A typical agent looks like this:
 ```yaml
 ---
 name: scout
+# Optional: registers this as code-analysis.scout while preserving name: scout
+package: code-analysis
 description: Fast codebase recon
 tools: read, grep, find, ls, bash, mcp:chrome-devtools
 extensions:
@@ -482,6 +487,7 @@ Important fields:
 
 | Field | Notes |
 |-------|-------|
+| `package` | Optional package identifier. A file with `name: scout` and `package: code-analysis` registers as `code-analysis.scout`; serialization keeps `name` and `package` separate. |
 | `tools` | Builtin tool allowlist. `mcp:` entries select direct MCP tools when `pi-mcp-adapter` is installed. |
 | `extensions` | Omitted means normal extensions; empty means no extensions; comma-separated values allowlist specific extensions. |
 | `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
@@ -530,10 +536,10 @@ Chains are reusable `.chain.md` workflows stored next to agent files.
 
 | Scope | Path |
 |-------|------|
-| User | `~/.pi/agent/agents/{name}.chain.md` |
-| Project | `.pi/agents/{name}.chain.md` |
+| User | `~/.pi/agent/agents/**/*.chain.md` |
+| Project | `.pi/agents/**/*.chain.md` |
 
-Project discovery also reads legacy `.agents/{name}.chain.md` files. If both locations define the same parsed chain name, `.pi/agents/` wins.
+Project discovery also reads legacy `.agents/**/*.chain.md` files. Nested subdirectories are discovered recursively. If both locations define the same parsed runtime chain name, `.pi/agents/` wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
 
 Example:
 
@@ -556,9 +562,9 @@ progress: true
 Create an implementation plan based on {previous}
 ```
 
-Each `## agent-name` section is a step. Config lines such as `output`, `reads`, `model`, `skills`, and `progress` go immediately after the header. A blank line separates config from task text.
+Each `## agent-name` section is a step. Config lines such as `output`, `outputMode`, `reads`, `model`, `skills`, and `progress` go immediately after the header. A blank line separates config from task text.
 
-Chains support three-state behavior: omitted inherits from the agent, a value overrides, and `false` disables.
+For `output`, `reads`, `skills`, and `progress`, chain behavior is three-state: omitted inherits from the agent, a value overrides, and `false` disables.
 
 Create chains from the Agents Manager template picker, save them from the chain-clarify TUI, or write them by hand. Run them with natural language, `/agents`, or:
 
@@ -645,6 +651,7 @@ These are the parameters the LLM passes when it calls the `subagent` tool. Most
 { agent: "worker", task: "refactor auth" }
 { agent: "scout", task: "find todos", maxOutput: { lines: 1000 } }
 { agent: "scout", task: "investigate", output: false }
+{ agent: "scout", task: "write a large report", output: "reports/scout.md", outputMode: "file-only" }
 
 // Forked context
 { agent: "worker", task: "continue this thread", context: "fork" }
@@ -690,10 +697,12 @@ Agent definitions are not loaded into context by default. Management actions let
 { action: "list" }
 { action: "list", agentScope: "project" }
 { action: "get", agent: "scout" }
+{ action: "get", agent: "code-analysis.scout" }
 { action: "get", chainName: "review-pipeline" }
 
 { action: "create", config: {
   name: "Code Scout",
+  package: "code-analysis",
   description: "Scans codebases for patterns and issues",
   scope: "user",
   systemPrompt: "You are a code scout...",
@@ -721,13 +730,13 @@ Agent definitions are not loaded into context by default. Management actions let
   ]
 }}
 
-{ action: "update", agent: "scout", config: { model: "openai/gpt-4o" } }
+{ action: "update", agent: "code-analysis.scout", config: { model: "openai/gpt-4o" } }
 { action: "update", chainName: "review-pipeline", config: { steps: [...] } }
 { action: "delete", agent: "scout" }
 { action: "delete", chainName: "review-pipeline" }
 ```
 
-`create` uses `config.scope`, not `agentScope`. `update` and `delete` use `agentScope` only when the same name exists in multiple scopes. To clear optional string fields, set them to `false` or `""`.
+`create` uses `config.scope`, not `agentScope`. `config.name` is the local frontmatter name; optional `config.package` registers the runtime name as `{package}.{name}` and is saved as separate `name` and `package` frontmatter. `update` and `delete` use the runtime name and `agentScope` only when the same runtime name exists in multiple scopes. To clear optional string fields, including `package`, set them to `false` or `""`.
 
 ### Parameter reference
 
@@ -739,9 +748,10 @@ Agent definitions are not loaded into context by default. Management actions let
 | `chainName` | string | - | Chain name for management actions. |
 | `config` | object/string | - | Agent or chain config for create/update. |
 | `output` | `string \| false` | agent default | Override single-agent output file. |
+| `outputMode` | `"inline" \| "file-only"` | `inline` | Return saved output inline or as a concise saved-file reference. `file-only` requires an `output` path. |
 | `skill` | `string \| string[] \| false` | agent default | Override skills or disable all. |
 | `model` | string | agent default | Override model. |
-| `tasks` | array | - | Top-level parallel tasks. Supports `agent`, `task`, `cwd`, `count`, `output`, `reads`, `progress`, `skill`, and `model`. |
+| `tasks` | array | - | Top-level parallel tasks. Supports `agent`, `task`, `cwd`, `count`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. |
 | `concurrency` | number | config or `4` | Top-level parallel concurrency. |
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
 | `chain` | array | - | Sequential and parallel chain steps. |
@@ -759,7 +769,9 @@ Agent definitions are not loaded into context by default. Management actions let
 
 `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.
 
-Sequential and parallel chain tasks accept `agent`, `task`, `cwd`, `output`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`.
+Use `outputMode: "file-only"` when a saved output may be large and the parent only needs a pointer. The returned text is a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Failed runs and save errors still return normal inline output for debugging. In chains, later `{previous}` steps receive the same compact reference when the prior step used file-only mode.
+
+Sequential and parallel chain tasks accept `agent`, `task`, `cwd`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`.
 
 Status and control actions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.21.3",
+  "version": "0.21.5",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -57,12 +57,27 @@
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*"
   },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-agent-core": {
+      "optional": true
+    },
+    "@mariozechner/pi-ai": {
+      "optional": true
+    },
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    },
+    "@mariozechner/pi-tui": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "typebox": "^1.1.24"
   },
   "devDependencies": {
     "@mariozechner/pi-agent-core": "^0.65.0",
     "@mariozechner/pi-ai": "^0.65.0",
-    "@mariozechner/pi-coding-agent": "^0.65.0"
+    "@mariozechner/pi-coding-agent": "^0.65.0",
+    "@mariozechner/pi-tui": "^0.65.2"
   }
 }

package/skills/pi-subagents/SKILL.md

@@ -178,16 +178,18 @@ agent with the same name only when you want a substantially different agent.
 ## Discovery and Scope Rules
 
 Agent files can live in:
-- `~/.pi/agent/agents/*.md` — user scope
-- `.pi/agents/*.md` — canonical project scope
-- legacy `.agents/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
+- `~/.pi/agent/agents/**/*.md` — user scope
+- `.pi/agents/**/*.md` — canonical project scope
+- legacy `.agents/**/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
 
 Chains live in:
-- `~/.pi/agent/agents/*.chain.md`
-- `.pi/agents/*.chain.md`
-- legacy `.agents/*.chain.md`
+- `~/.pi/agent/agents/**/*.chain.md`
+- `.pi/agents/**/*.chain.md`
+- legacy `.agents/**/*.chain.md`
 
-Precedence is:
+Discovery is recursive. `.chain.md` files are chains, not agents. Agents and chains can set optional frontmatter `package: code-analysis`; `name: scout` plus `package: code-analysis` registers as runtime name `code-analysis.scout` while serialization keeps `name` and `package` separate.
+
+Precedence is by parsed runtime name:
 1. project scope
 2. user scope
 3. builtin agents
@@ -241,7 +243,7 @@ subagent({
 })
 ```
 
-Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file.
+Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file. For large saved outputs, set `outputMode: "file-only"` together with an `output` path. The parent result then contains only a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` instead of the full saved content. Do not use `output: false` for this; `output: false` means no file output. Failed runs and save errors still return inline details for debugging.
 
 ### Chain execution
 
@@ -271,6 +273,8 @@ subagent({
 })
 ```
 
+File-only output mode also works for async single runs, top-level parallel task items, sequential chain steps, and chain parallel task items. In chains, `{previous}` receives the compact saved-file reference when the prior step used file-only mode.
+
 For review fanout where the parent continues a local audit:
 
 ```typescript
@@ -451,6 +455,7 @@ subagent({
   action: "create",
   config: {
     name: "my-agent",
+    package: "code-analysis",
     description: "Project-specific implementation helper",
     systemPrompt: "Your system prompt here.",
     systemPromptMode: "replace",
@@ -465,7 +470,7 @@ subagent({
 ```typescript
 subagent({
   action: "update",
-  agent: "my-agent",
+  agent: "code-analysis.my-agent",
   config: {
     thinking: "high"
   }
@@ -475,13 +480,13 @@ subagent({
 ### Delete an agent
 
 ```typescript
-subagent({ action: "delete", agent: "my-agent" })
+subagent({ action: "delete", agent: "code-analysis.my-agent" })
 ```
 
 Use management actions when the system needs to create or edit subagents on
 demand without dropping into raw file editing.
 
-Management actions create or update user/project agent files. For small builtin changes such as a model swap, prefer `/agents` builtin overrides or `subagents.agentOverrides` in settings.
+Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and chain steps. For small builtin changes such as a model swap, prefer `/agents` builtin overrides or `subagents.agentOverrides` in settings.
 
 ## Creating and Editing Agents by File
 
@@ -490,6 +495,7 @@ A minimal agent file looks like this:
 ```markdown
 ---
 name: my-agent
+package: code-analysis
 description: What this agent does
 model: openai-codex/gpt-5.4
 thinking: high
@@ -502,7 +508,7 @@ inheritSkills: false
 Your system prompt here.
 ```
 
-That is only a starting point. Common optional fields include:
+That is only a starting point. Omit `package` for the traditional unqualified runtime name. Common optional fields include:
 - `defaultProgress`
 - `defaultReads`
 - `output`

package/src/agents/agent-management.ts

@@ -12,6 +12,9 @@ import {
 	defaultInheritSkills,
 	defaultSystemPromptMode,
 	discoverAgentsAll,
+	buildRuntimeName,
+	frontmatterNameForConfig,
+	parsePackageName,
 } from "./agents.ts";
 import { serializeAgent } from "./agent-serializer.ts";
 import { serializeChain } from "./chain-serializer.ts";
@@ -71,6 +74,10 @@ function sanitizeName(name: string): string {
 	return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
 }
 
+function parsePackageConfig(value: unknown): { packageName?: string; error?: string } {
+	return parsePackageName(value, "config.package");
+}
+
 function allAgents(d: { builtin: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): AgentConfig[] {
 	return [...d.builtin, ...d.user, ...d.project];
 }
@@ -167,6 +174,10 @@ function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: strin
 			else if (typeof s.output === "string") step.output = s.output;
 			else return { error: `config.steps[${i}].output must be a string or false.` };
 		}
+		if (hasKey(s, "outputMode")) {
+			if (s.outputMode === "inline" || s.outputMode === "file-only") step.outputMode = s.outputMode;
+			else return { error: `config.steps[${i}].outputMode must be 'inline' or 'file-only'.` };
+		}
 		if (hasKey(s, "reads")) {
 			if (s.reads === false) step.reads = false;
 			else if (Array.isArray(s.reads)) step.reads = s.reads.filter((v): v is string => typeof v === "string").map((v) => v.trim()).filter(Boolean);
@@ -336,6 +347,10 @@ function renamePath(
 function formatAgentDetail(agent: AgentConfig): string {
 	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
 	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
+	if (agent.packageName) {
+		lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
+		lines.push(`Package: ${agent.packageName}`);
+	}
 	if (agent.model) lines.push(`Model: ${agent.model}`);
 	if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
 	if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
@@ -356,13 +371,19 @@ function formatAgentDetail(agent: AgentConfig): string {
 }
 
 function formatChainDetail(chain: ChainConfig): string {
-	const lines: string[] = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`, "", "Steps:"];
+	const lines: string[] = [`Chain: ${chain.name} (${chain.source})`, `Path: ${chain.filePath}`, `Description: ${chain.description}`];
+	if (chain.packageName) {
+		lines.push(`Local name: ${frontmatterNameForConfig(chain)}`);
+		lines.push(`Package: ${chain.packageName}`);
+	}
+	lines.push("", "Steps:");
 	for (let i = 0; i < chain.steps.length; i++) {
 		const s = chain.steps[i]!;
 		lines.push(`${i + 1}. ${s.agent}`);
 		if (s.task.trim()) lines.push(`   Task: ${s.task}`);
 		if (s.output === false) lines.push("   Output: false");
 		else if (s.output) lines.push(`   Output: ${s.output}`);
+		if (s.outputMode) lines.push(`   Output mode: ${s.outputMode}`);
 		if (s.reads === false) lines.push("   Reads: false");
 		else if (Array.isArray(s.reads) && s.reads.length > 0) lines.push(`   Reads: ${s.reads.join(", ")}`);
 		if (s.model) lines.push(`   Model: ${s.model}`);
@@ -430,6 +451,9 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	if (typeof cfg.description !== "string" || !cfg.description.trim()) return result("config.description is required and must be a non-empty string.", true);
 	const name = sanitizeName(cfg.name);
 	if (!name) return result("config.name is invalid after sanitization. Use letters, numbers, spaces, or hyphens.", true);
+	const parsedPackage = parsePackageConfig(cfg.package);
+	if (parsedPackage.error) return result(parsedPackage.error, true);
+	const runtimeName = buildRuntimeName(name, parsedPackage.packageName);
 	const scopeRaw = cfg.scope ?? "user";
 	if (scopeRaw !== "user" && scopeRaw !== "project") return result("config.scope must be 'user' or 'project'.", true);
 	const scope = scopeRaw as ManagementScope;
@@ -437,23 +461,25 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const d = discoverAgentsAll(ctx.cwd);
 	const targetDir = scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
 	fs.mkdirSync(targetDir, { recursive: true });
-	if (nameExistsInScope(ctx.cwd, scope, name)) return result(`Name '${name}' already exists in ${scope} scope. Use update instead.`, true);
-	const targetPath = path.join(targetDir, isChain ? `${name}.chain.md` : `${name}.md`);
+	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
+	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);
 	if (fs.existsSync(targetPath)) return result(`File already exists at ${targetPath} but is not a valid ${isChain ? "chain" : "agent"} definition. Remove or rename it first.`, true);
 	const warnings: string[] = [];
-	if (!isChain && d.builtin.some((a) => a.name === name)) warnings.push(`Note: this shadows the builtin agent '${name}'.`);
+	if (!isChain && d.builtin.some((a) => a.name === runtimeName)) warnings.push(`Note: this shadows the builtin agent '${runtimeName}'.`);
 	if (isChain) {
 		const parsed = parseStepList(cfg.steps);
 		if (parsed.error) return result(parsed.error, true);
-		const chain: ChainConfig = { name, description: cfg.description.trim(), source: scope, filePath: targetPath, steps: parsed.steps! };
+		const chain: ChainConfig = { name: runtimeName, localName: name, packageName: parsedPackage.packageName, description: cfg.description.trim(), source: scope, filePath: targetPath, steps: parsed.steps! };
 		fs.writeFileSync(targetPath, serializeChain(chain), "utf-8");
 		const missing = unknownChainAgents(ctx.cwd, chain.steps);
 		if (missing.length) warnings.push(`Warning: chain steps reference unknown agents: ${missing.join(", ")}.`);
 		warnings.push(...chainStepWarnings(ctx, chain.steps));
-		return result([`Created chain '${name}' at ${targetPath}.`, ...warnings].join("\n"));
+		return result([`Created chain '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
 	}
 	const agent: AgentConfig = {
-		name,
+		name: runtimeName,
+		localName: name,
+		packageName: parsedPackage.packageName,
 		description: cfg.description.trim(),
 		source: scope,
 		filePath: targetPath,
@@ -471,7 +497,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const sw = skillsWarning(ctx.cwd, agent.skills);
 	if (sw) warnings.push(sw);
 	fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
-	return result([`Created agent '${name}' at ${targetPath}.`, ...warnings].join("\n"));
+	return result([`Created agent '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
 }
 
 export function handleUpdate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
@@ -491,14 +517,22 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		const oldName = target.name;
 		if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
 		if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
-		let newName: string | undefined;
+		let newLocalName = target.localName ?? frontmatterNameForConfig(target);
 		if (hasKey(cfg, "name")) {
-			newName = sanitizeName(cfg.name as string);
-			if (!newName) return result("config.name is invalid after sanitization.", true);
+			newLocalName = sanitizeName(cfg.name as string);
+			if (!newLocalName) return result("config.name is invalid after sanitization.", true);
+		}
+		let newPackageName = target.packageName;
+		if (hasKey(cfg, "package")) {
+			const parsedPackage = parsePackageConfig(cfg.package);
+			if (parsedPackage.error) return result(parsedPackage.error, true);
+			newPackageName = parsedPackage.packageName;
 		}
 		const applyError = applyAgentConfig(updated, cfg);
 		if (applyError) return result(applyError, true);
-		if (newName !== undefined) updated.name = newName;
+		updated.localName = newLocalName;
+		updated.packageName = newPackageName;
+		updated.name = buildRuntimeName(newLocalName, newPackageName);
 		if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
 		if (hasKey(cfg, "model")) {
 			const mw = modelWarning(ctx, updated.model);
@@ -535,10 +569,16 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 	const oldName = target.name;
 	if (hasKey(cfg, "name") && (typeof cfg.name !== "string" || !cfg.name.trim())) return result("config.name must be a non-empty string when provided.", true);
 	if (hasKey(cfg, "description") && (typeof cfg.description !== "string" || !cfg.description.trim())) return result("config.description must be a non-empty string when provided.", true);
-	let newName: string | undefined;
+	let newLocalName = target.localName ?? frontmatterNameForConfig(target);
 	if (hasKey(cfg, "name")) {
-		newName = sanitizeName(cfg.name as string);
-		if (!newName) return result("config.name is invalid after sanitization.", true);
+		newLocalName = sanitizeName(cfg.name as string);
+		if (!newLocalName) return result("config.name is invalid after sanitization.", true);
+	}
+	let newPackageName = target.packageName;
+	if (hasKey(cfg, "package")) {
+		const parsedPackage = parsePackageConfig(cfg.package);
+		if (parsedPackage.error) return result(parsedPackage.error, true);
+		newPackageName = parsedPackage.packageName;
 	}
 	let parsedSteps: ChainStepConfig[] | undefined;
 	if (hasKey(cfg, "steps")) {
@@ -546,7 +586,9 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		if (parsed.error) return result(parsed.error, true);
 		parsedSteps = parsed.steps!;
 	}
-	if (newName !== undefined) updated.name = newName;
+	updated.localName = newLocalName;
+	updated.packageName = newPackageName;
+	updated.name = buildRuntimeName(newLocalName, newPackageName);
 	if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
 	if (parsedSteps) {
 		updated.steps = parsedSteps;

package/src/agents/agent-serializer.ts

@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
 import type { AgentConfig } from "./agents.ts";
+import { frontmatterNameForConfig } from "./identity.ts";
 
 export const KNOWN_FIELDS = new Set([
 	"name",
+	"package",
 	"description",
 	"tools",
 	"model",
@@ -30,7 +32,8 @@ function joinComma(values: string[] | undefined): string | undefined {
 export function serializeAgent(config: AgentConfig): string {
 	const lines: string[] = [];
 	lines.push("---");
-	lines.push(`name: ${config.name}`);
+	lines.push(`name: ${frontmatterNameForConfig(config)}`);
+	if (config.packageName) lines.push(`package: ${config.packageName}`);
 	lines.push(`description: ${config.description}`);
 
 	const tools = [

package/src/agents/agents.ts

@@ -6,10 +6,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { OutputMode } from "../shared/types.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain } from "./chain-serializer.ts";
 import { mergeAgentsForScope } from "./agent-selection.ts";
 import { parseFrontmatter } from "./frontmatter.ts";
+import { buildRuntimeName, parsePackageName } from "./identity.ts";
+export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -66,6 +69,8 @@ interface BuiltinAgentOverrideInfo {
 
 export interface AgentConfig {
 	name: string;
+	localName?: string;
+	packageName?: string;
 	description: string;
 	tools?: string[];
 	mcpDirectTools?: string[];
@@ -102,6 +107,7 @@ export interface ChainStepConfig {
 	agent: string;
 	task: string;
 	output?: string | false;
+	outputMode?: OutputMode;
 	reads?: string[] | false;
 	model?: string;
 	skills?: string[] | false;
@@ -110,6 +116,8 @@ export interface ChainStepConfig {
 
 export interface ChainConfig {
 	name: string;
+	localName?: string;
+	packageName?: string;
 	description: string;
 	source: AgentSource;
 	filePath: string;
@@ -505,26 +513,34 @@ export function removeBuiltinAgentOverride(cwd: string, name: string, scope: "us
 	return filePath;
 }
 
-function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
-	const agents: AgentConfig[] = [];
-
-	if (!fs.existsSync(dir)) {
-		return agents;
-	}
+function listMarkdownFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
+	const files: string[] = [];
+	if (!fs.existsSync(dir)) return files;
 
 	let entries: fs.Dirent[];
 	try {
-		entries = fs.readdirSync(dir, { withFileTypes: true });
+		entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
 	} catch {
-		return agents;
+		return files;
 	}
 
 	for (const entry of entries) {
-		if (!entry.name.endsWith(".md")) continue;
-		if (entry.name.endsWith(".chain.md")) continue;
+		const filePath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...listMarkdownFilesRecursive(filePath, predicate));
+			continue;
+		}
 		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+		if (!predicate(entry.name)) continue;
+		files.push(filePath);
+	}
+	return files;
+}
 
-		const filePath = path.join(dir, entry.name);
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+
+	for (const filePath of listMarkdownFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
@@ -538,6 +554,12 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			continue;
 		}
 
+		const localName = frontmatter.name;
+		const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
+		if (parsedPackage.error) continue;
+		const packageName = parsedPackage.packageName;
+		const runtimeName = buildRuntimeName(localName, packageName);
+
 		const rawTools = frontmatter.tools
 			?.split(",")
 			.map((t) => t.trim())
@@ -573,12 +595,12 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			? "replace"
 			: frontmatter.systemPromptMode === "append"
 				? "append"
-				: defaultSystemPromptMode(frontmatter.name);
+				: defaultSystemPromptMode(localName);
 		const inheritProjectContext = frontmatter.inheritProjectContext === "true"
 			? true
 			: frontmatter.inheritProjectContext === "false"
 				? false
-				: defaultInheritProjectContext(frontmatter.name);
+				: defaultInheritProjectContext(localName);
 		const inheritSkills = frontmatter.inheritSkills === "true"
 			? true
 			: frontmatter.inheritSkills === "false"
@@ -606,7 +628,9 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
 
 		agents.push({
-			name: frontmatter.name,
+			name: runtimeName,
+			localName,
+			packageName,
 			description: frontmatter.description,
 			tools: tools.length > 0 ? tools : undefined,
 			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
@@ -640,22 +664,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 function loadChainsFromDir(dir: string, source: AgentSource): ChainConfig[] {
 	const chains: ChainConfig[] = [];
 
-	if (!fs.existsSync(dir)) {
-		return chains;
-	}
-
-	let entries: fs.Dirent[];
-	try {
-		entries = fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return chains;
-	}
-
-	for (const entry of entries) {
-		if (!entry.name.endsWith(".chain.md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
-
-		const filePath = path.join(dir, entry.name);
+	for (const filePath of listMarkdownFilesRecursive(dir, (fileName) => fileName.endsWith(".chain.md"))) {
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");