pi-subagents 0.21.2 → 0.21.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [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
+- Debounce foreground `needs_attention` notices, make them non-triggering, and cancel them when the run finishes so stale chain-step alerts do not launch parent turns after completion.
+
 ## [0.21.2] - 2026-04-30
 
 ### Added

package/README.md

@@ -298,12 +298,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 +397,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 +459,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 +485,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 +534,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 +560,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 +649,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 +695,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 +728,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 +746,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 +767,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.2",
+  "version": "0.21.4",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -57,6 +57,20 @@
     "@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"
   },

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
 
@@ -261,6 +263,8 @@ without forcing each step to rediscover everything.
 
 ### Async/background
 
+Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`. Do not end your turn immediately after launching that async child if you promised to keep working; continue the local inspection or other independent work, then check the async run when its result is needed.
+
 ```typescript
 subagent({
   agent: "worker",
@@ -269,6 +273,20 @@ 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
+const run = subagent({
+  agent: "reviewer",
+  task: "Review the current diff for correctness issues. Do not edit files.",
+  async: true,
+  context: "fresh"
+})
+// Continue local inspection, then later call status with the returned id.
+```
+
 Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
 
 Use diagnostics when setup or child startup looks wrong:
@@ -437,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",
@@ -451,7 +470,7 @@ subagent({
 ```typescript
 subagent({
   action: "update",
-  agent: "my-agent",
+  agent: "code-analysis.my-agent",
   config: {
     thinking: "high"
   }
@@ -461,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
 
@@ -476,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
@@ -488,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");