pi-subagents 0.40.0 → 0.42.0

package/skills/pi-subagents/references/management-authoring-rpc.md

@@ -135,10 +135,10 @@ fixes worth doing now. Parent agents can also apply the same recipes directly
 with `subagent(...)` when the user describes the workflow in natural language
 instead of invoking a slash command.
 
-Additional user prompt templates can delegate into `pi-subagents` through the native `/prompt-workflow` and `/chain-prompts` commands. This is useful when a slash command should always run through a particular agent or with forked context. Prompt frontmatter can set `subagent`, `model`, `skill`, `cwd`, `worktree`, `fresh`, `fork`, or `inheritContext` for the native adapter.
+Additional user prompt templates can delegate into `pi-subagents` through the native `/prompt-workflow` command. This is useful when a slash command should always run through a particular agent or with forked context. Prompt frontmatter can set `subagent`, `model`, `skill`, `cwd`, `fresh`, `fork`, or `inheritContext` for the native adapter.
 
 ## Extension RPC
 
-Other Pi extensions can call `pi-subagents` through the in-process event bus. The stable v1 channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`. `ping` advertises the exact process-local async completion event as `events.asyncComplete` for RPC-spawn consumers.
+Other Pi extensions can call `pi-subagents` through the in-process event bus. The RPC channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`. `ping` advertises the exact process-local async completion event as `events.asyncComplete` for RPC-spawn consumers.
 
 Methods: `ping`, `status`, `spawn`, `steer`, `interrupt`, `resume`, and `stop`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` is async-only and rejects management actions, `async: false`, or `clarify: true`; it reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and delegates to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.

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

@@ -24,9 +24,7 @@ Agents can use the `subagent(...)` tool directly for execution, management, stat
 Humans often use the slash-command layer instead:
 
 - `/run` — launch a single agent
-- `/chain` — launch a chain of steps
-- `/parallel` — launch top-level parallel tasks
-- `/run-chain` — launch a saved `.chain.md` or `.chain.json` workflow
+- `workflowScript` — the sole public surface for sequence, parallelism, branching, retries, and aggregation
 - `/subagents` — interactive admin for inspecting agents and editing model, thinking, or system prompt
 - `/subagents-stop [run-id]` — stop a current-session top-level async run; opens a selector when no id is given
 - `/subagents-detach [run-id]` — detach an active foreground single-subagent run without terminating its child
@@ -36,7 +34,7 @@ Humans often use the slash-command layer instead:
 - `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
 - `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
 - `/subagents-profiles`, `/subagents-load-profile`, `/subagents-refresh-provider-models`, `/subagents-generate-profiles`, `/subagents-check-profile` — manage model profiles and provider catalogs
-- `/prompt-workflow` and `/chain-prompts` — run prompt templates through native subagent single/chain workflows
+- `/prompt-workflow` — run a prompt template through native single-agent or workflowScript execution
 
 Prefer the tool when you are writing agent logic. Prefer the slash commands when
 you are guiding a human through an interactive flow.
@@ -52,7 +50,7 @@ Packaged prompt shortcuts are also available for repeatable workflows. Treat the
 
 ## Applying Prompt Techniques Without Slash Commands
 
-The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
+The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. For targets outside the parent cwd, include the exact repository, explicit `cwd`, authority boundary, and expected output path in each child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
 
 ### Parallel review technique
 
@@ -94,21 +92,18 @@ Use this when the question needs both external evidence and local implications.
 
 ### Parallel context-build technique
 
-Use this before planning or implementation when a stronger handoff is needed. Run a chain with one parallel step of `context-builder` agents rather than top-level parallel tasks, so relative output files live under the temporary chain directory. Give every task a distinct output path such as `context-build/request-and-scope.md`, `context-build/codebase-and-patterns.md`, and `context-build/validation-and-risks.md`. Choose two or three builders: request/scope, codebase/patterns, and validation/risks. Each builder must read every relevant file needed to understand its slice, follow imports/callers/tests/docs/config, conduct tool-available web research when needed, and include a compact `meta-prompt` section. The parent synthesizes the outputs into important context, recommended next meta-prompt, open questions, assumptions, and artifact paths.
+Use this before planning or implementation when a stronger handoff is needed. Use `workflowScript` with `runs.all` to launch distinct `context-builder` lanes, each with an explicit output path. Give every task a distinct output path such as `context-build/request-and-scope.md`, `context-build/codebase-and-patterns.md`, and `context-build/validation-and-risks.md`. Choose two or three builders: request/scope, codebase/patterns, and validation/risks. Each builder must read every relevant file needed to understand its slice, follow imports/callers/tests/docs/config, conduct tool-available web research when needed, and include a compact `meta-prompt` section. The parent synthesizes the outputs into important context, recommended next meta-prompt, open questions, assumptions, and artifact paths.
 
 Example shape:
 
 ```typescript
-subagent({
-  chain: [{
-    parallel: [
-      { agent: "context-builder", task: "Build request/scope context for: ...", output: "context-build/request-and-scope.md" },
-      { agent: "context-builder", task: "Build codebase/pattern context for: ...", output: "context-build/codebase-and-patterns.md" },
-      { agent: "context-builder", task: "Build validation/risk context for: ...", output: "context-build/validation-and-risks.md" }
-    ]
-  }],
-  context: "fresh"
-})
+subagent({ workflowScript: `
+  const results = await runs.all([
+    { key: "lane-a", agent: "reviewer", task: "Inspect lane A" },
+    { key: "lane-b", agent: "reviewer", task: "Inspect lane B" }
+  ]);
+  return results.map(result => result.output);
+` })
 ```
 
 ### Parallel handoff-plan technique
@@ -118,17 +113,13 @@ Use this when the user needs a solution brief or implementation-ready handoff fr
 Example shape:
 
 ```typescript
-subagent({
-  chain: [
-    { parallel: [
-      { agent: "researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
-      { agent: "context-builder", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
-      { agent: "context-builder", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
-    ] },
-    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and implementation-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
-  ],
-  context: "fresh"
-})
+subagent({ workflowScript: `
+  const results = await runs.all([
+    { key: "lane-a", agent: "reviewer", task: "Inspect lane A" },
+    { key: "lane-b", agent: "reviewer", task: "Inspect lane B" }
+  ]);
+  return results.map(result => result.output);
+` })
 ```
 
 ### Gather-context-and-clarify technique
@@ -149,7 +140,7 @@ Use this when a broad diff has known reviewer findings across several items and
 
 Prefer `async: true`, `context: "fresh"` for planners/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
 
-When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`.
+When one child returns a structured target list, use ordinary JavaScript to validate/filter it and map bounded entries into `runs.all`; do not use the removed chain fanout DSL.
 
 Example shape:
 
@@ -221,12 +212,14 @@ Builtin role agents inherit the current Pi default model unless you override the
 
 A strong subagent prompt usually includes:
 - **Goal**: the concrete outcome the child should produce.
+- **Target**: repository, explicit `cwd`, branch/ref/head, and source seam when the target is not the parent cwd.
+- **Authority boundary**: whether the child may read, edit, commit, push, comment, close, merge, publish, or release. Omit or forbid actions that are not approved.
 - **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved.
 - **Success criteria**: what must be true before the child can finish.
 - **Hard constraints**: true invariants only, such as no edits for review-only tasks, one writer thread, child must not run subagents unless it is an explicitly assigned `tools: subagent` fanout child, or escalation for unapproved decisions.
 - **Validation**: targeted checks to run, or the next-best check when validation is impossible.
-- **Output**: the expected summary shape, artifact path, or finding format.
-- **Stop rules**: when to ask via `intercom`, when to stop after enough evidence, and when not to keep searching.
+- **Output**: the expected summary shape, artifact path, or finding format. Use repo-qualified durable output paths for cross-codebase waves.
+- **Stop rules**: when to ask via `intercom` or `contact_supervisor`, when to stop after enough evidence, and when not to keep searching.
 
 Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell a reviewer to inspect the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell a researcher the retrieval budget: start with broad targeted searches, fetch only the strongest sources, search again only when a required fact is missing, then stop.
 

package/src/agents/agent-management.ts

@@ -46,7 +46,7 @@ interface ManagementParams {
 	action?: string;
 	agent?: string;
 	chainName?: string;
-	agentScope?: string;
+	agentScope?: unknown;
 	config?: unknown;
 }
 
@@ -215,34 +215,54 @@ function skillsWarning(cwd: string, agent: Pick<AgentConfig, "skills" | "skillPa
 }
 
 export function editableAgentConfig(agent: AgentConfig): AgentConfig {
+	const { extensions: _extensions, ...withoutExtensions } = agent;
 	const base = agent.override?.base;
+	const {
+		override: _override,
+		model: _model,
+		fallbackModels: _fallbackModels,
+		thinking: _thinking,
+		systemPromptMode: _systemPromptMode,
+		inheritProjectContext: _inheritProjectContext,
+		inheritSkills: _inheritSkills,
+		defaultContext: _defaultContext,
+		acceptanceRole: _acceptanceRole,
+		disabled: _disabled,
+		systemPrompt: _systemPrompt,
+		skills: _skills,
+		skillPath: _skillPath,
+		tools: _tools,
+		mcpDirectTools: _mcpDirectTools,
+		subagentOnlyExtensions: _subagentOnlyExtensions,
+		completionGuard: _completionGuard,
+		...editable
+	} = withoutExtensions;
 	if (!base) {
 		return {
-			...agent,
-			extensions: agent.extensionsFromDefault ? undefined : agent.extensions ? [...agent.extensions] : undefined,
+			...withoutExtensions,
+			...(agent.extensionsFromDefault ? {} : agent.extensions !== undefined ? { extensions: [...agent.extensions] } : {}),
 		};
 	}
 
 	return {
-		...agent,
-		model: base.model,
-		fallbackModels: base.fallbackModels ? [...base.fallbackModels] : undefined,
-		thinking: base.thinking,
+		...editable,
+		...(base.model !== undefined ? { model: base.model } : {}),
+		...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
+		...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
 		systemPromptMode: base.systemPromptMode,
 		inheritProjectContext: base.inheritProjectContext,
 		inheritSkills: base.inheritSkills,
-		defaultContext: base.defaultContext,
-		acceptanceRole: base.acceptanceRole,
-		disabled: base.disabled,
+		...(base.defaultContext !== undefined ? { defaultContext: base.defaultContext } : {}),
+		...(base.acceptanceRole !== undefined ? { acceptanceRole: base.acceptanceRole } : {}),
+		...(base.disabled !== undefined ? { disabled: base.disabled } : {}),
 		systemPrompt: base.systemPrompt,
-		skills: base.skills ? [...base.skills] : undefined,
-		skillPath: base.skillPath ? [...base.skillPath] : undefined,
-		tools: base.tools ? [...base.tools] : undefined,
-		mcpDirectTools: base.mcpDirectTools ? [...base.mcpDirectTools] : undefined,
-		extensions: base.extensions ? [...base.extensions] : undefined,
-		subagentOnlyExtensions: base.subagentOnlyExtensions ? [...base.subagentOnlyExtensions] : undefined,
-		completionGuard: base.completionGuard,
-		override: undefined,
+		...(base.skills !== undefined ? { skills: [...base.skills] } : {}),
+		...(base.skillPath !== undefined ? { skillPath: [...base.skillPath] } : {}),
+		...(base.tools !== undefined ? { tools: [...base.tools] } : {}),
+		...(base.mcpDirectTools !== undefined ? { mcpDirectTools: [...base.mcpDirectTools] } : {}),
+		...(base.extensions !== undefined ? { extensions: [...base.extensions] } : {}),
+		...(base.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...base.subagentOnlyExtensions] } : {}),
+		...(base.completionGuard !== undefined ? { completionGuard: base.completionGuard } : {}),
 	};
 }
 
@@ -266,6 +286,7 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
 	if (hasKey(cfg, "description")) changed("description");
 	if (hasKey(cfg, "aliases")) changed("alias", "aliases");
 	if (hasKey(cfg, "systemPrompt")) changed("systemPrompt");
+	if (hasKey(cfg, "runner")) changed("runner");
 	if (hasKey(cfg, "model")) changed("model");
 	if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
 	if (hasKey(cfg, "tools")) changed("tools");
@@ -364,7 +385,7 @@ function parseStepList(raw: unknown): { steps?: ChainStepConfig[]; error?: strin
 		if (hasKey(s, "toolBudget")) {
 			const validation = validateToolBudgetConfig(s.toolBudget, `config.steps[${i}].toolBudget`);
 			if (validation.error) return { error: validation.error };
-			step.toolBudget = s.toolBudget as ChainStepConfig["toolBudget"];
+			if (s.toolBudget !== undefined) step.toolBudget = s.toolBudget as ToolBudgetConfig;
 		}
 		steps.push(step);
 	}
@@ -380,18 +401,23 @@ function parseTools(raw: string): { tools?: string[]; mcpDirectTools?: string[]
 			if (direct) mcpDirectTools.push(direct);
 		} else tools.push(item);
 	}
-	return { tools: tools.length ? tools : undefined, mcpDirectTools: mcpDirectTools.length ? mcpDirectTools : undefined };
+	return {
+		...(tools.length ? { tools } : {}),
+		...(mcpDirectTools.length ? { mcpDirectTools } : {}),
+	};
 }
 
 function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): string | undefined {
 	if (hasKey(cfg, "aliases")) {
-		if (cfg.aliases === false || cfg.aliases === "") target.aliases = undefined;
+		if (cfg.aliases === false || cfg.aliases === "") delete target.aliases;
 		else if (typeof cfg.aliases === "string") {
 			const aliases = parseCsv(cfg.aliases).filter((alias) => alias !== target.name);
-			target.aliases = aliases.length ? aliases : undefined;
+			if (aliases.length) target.aliases = aliases;
+			else delete target.aliases;
 		} else if (Array.isArray(cfg.aliases) && cfg.aliases.every((entry) => typeof entry === "string")) {
 			const aliases = [...new Set(cfg.aliases.map((entry) => entry.trim()).filter(Boolean).filter((alias) => alias !== target.name))];
-			target.aliases = aliases.length ? aliases : undefined;
+			if (aliases.length) target.aliases = aliases;
+			else delete target.aliases;
 		} else return "config.aliases must be a comma-separated string, string array, or false when provided.";
 	}
 	if (hasKey(cfg, "systemPrompt")) {
@@ -399,58 +425,92 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.systemPrompt === "string") target.systemPrompt = cfg.systemPrompt;
 		else return "config.systemPrompt must be a string or false when provided.";
 	}
+	if (hasKey(cfg, "runner")) {
+		if (cfg.runner === false || cfg.runner === "") delete target.runner;
+		else if (cfg.runner && typeof cfg.runner === "object" && !Array.isArray(cfg.runner)) {
+			const runner = cfg.runner as Record<string, unknown>;
+			if (runner.type === "pi" && Object.keys(runner).every((key) => key === "type")) target.runner = { type: "pi" };
+			else if (runner.type === "external-cli" && typeof runner.command === "string" && runner.command.trim()
+				&& (runner.args === undefined || (Array.isArray(runner.args) && runner.args.every((arg) => typeof arg === "string")))
+				&& (runner.promptDelivery === undefined || runner.promptDelivery === "stdin")
+				&& Object.keys(runner).every((key) => ["type", "command", "args", "promptDelivery"].includes(key))) {
+				const runnerArgs = Array.isArray(runner.args) ? runner.args.filter((arg): arg is string => typeof arg === "string") : undefined;
+				target.runner = { type: "external-cli", command: runner.command.trim(), ...(runnerArgs?.length ? { args: runnerArgs } : {}), ...(runner.promptDelivery ? { promptDelivery: "stdin" } : {}) };
+			} else return "config.runner must be { type: 'pi' } or { type: 'external-cli', command: string, args?: string[], promptDelivery?: 'stdin' }.";
+		} else return "config.runner must be an object, false, or empty string when provided.";
+	}
 	if (hasKey(cfg, "model")) {
-		if (cfg.model === false || cfg.model === "") target.model = undefined;
-		else if (typeof cfg.model === "string") target.model = cfg.model.trim() || undefined;
-		else return "config.model must be a string or false when provided.";
+		if (cfg.model === false || cfg.model === "") delete target.model;
+		else if (typeof cfg.model === "string") {
+			const model = cfg.model.trim();
+			if (model) target.model = model;
+			else delete target.model;
+		} else return "config.model must be a string or false when provided.";
 	}
 	if (hasKey(cfg, "fallbackModels")) {
-		if (cfg.fallbackModels === false || cfg.fallbackModels === "") target.fallbackModels = undefined;
+		if (cfg.fallbackModels === false || cfg.fallbackModels === "") delete target.fallbackModels;
 		else if (typeof cfg.fallbackModels === "string") {
 			const models = parseCsv(cfg.fallbackModels);
-			target.fallbackModels = models.length ? models : undefined;
+			if (models.length) target.fallbackModels = models;
+			else delete target.fallbackModels;
 		} else if (Array.isArray(cfg.fallbackModels)) {
 			const models = cfg.fallbackModels
 				.filter((value): value is string => typeof value === "string")
 				.map((value) => value.trim())
 				.filter(Boolean);
-			target.fallbackModels = models.length ? [...new Set(models)] : undefined;
+			if (models.length) target.fallbackModels = [...new Set(models)];
+			else delete target.fallbackModels;
 		} else return "config.fallbackModels must be a comma-separated string, string array, or false when provided.";
 	}
 	if (hasKey(cfg, "tools")) {
-		if (cfg.tools === false || cfg.tools === "") { target.tools = undefined; target.mcpDirectTools = undefined; }
-		else if (typeof cfg.tools === "string") { const parsed = parseTools(cfg.tools); target.tools = parsed.tools; target.mcpDirectTools = parsed.mcpDirectTools; }
-		else return "config.tools must be a comma-separated string or false when provided.";
+		if (cfg.tools === false || cfg.tools === "") { delete target.tools; delete target.mcpDirectTools; }
+		else if (typeof cfg.tools === "string") {
+			const parsed = parseTools(cfg.tools);
+			if (parsed.tools) target.tools = parsed.tools;
+			else delete target.tools;
+			if (parsed.mcpDirectTools) target.mcpDirectTools = parsed.mcpDirectTools;
+			else delete target.mcpDirectTools;
+		} else return "config.tools must be a comma-separated string or false when provided.";
 	}
 	if (hasKey(cfg, "skills")) {
-		if (cfg.skills === false || cfg.skills === "") target.skills = undefined;
-		else if (typeof cfg.skills === "string") { const skills = parseCsv(cfg.skills); target.skills = skills.length ? skills : undefined; }
-		else return "config.skills must be a comma-separated string or false when provided.";
+		if (cfg.skills === false || cfg.skills === "") delete target.skills;
+		else if (typeof cfg.skills === "string") {
+			const skills = parseCsv(cfg.skills);
+			if (skills.length) target.skills = skills;
+			else delete target.skills;
+		} else return "config.skills must be a comma-separated string or false when provided.";
 	}
 	if (hasKey(cfg, "skillPath")) {
-		if (cfg.skillPath === false || cfg.skillPath === "") target.skillPath = undefined;
-		else if (typeof cfg.skillPath === "string") { const skillPath = parseCsv(cfg.skillPath); target.skillPath = skillPath.length ? skillPath : undefined; }
-		else if (Array.isArray(cfg.skillPath) && cfg.skillPath.every((entry) => typeof entry === "string")) {
+		if (cfg.skillPath === false || cfg.skillPath === "") delete target.skillPath;
+		else if (typeof cfg.skillPath === "string") {
+			const skillPath = parseCsv(cfg.skillPath);
+			if (skillPath.length) target.skillPath = skillPath;
+			else delete target.skillPath;
+		} else if (Array.isArray(cfg.skillPath) && cfg.skillPath.every((entry) => typeof entry === "string")) {
 			const skillPath = [...new Set(cfg.skillPath.map((entry) => entry.trim()).filter(Boolean))];
-			target.skillPath = skillPath.length ? skillPath : undefined;
+			if (skillPath.length) target.skillPath = skillPath;
+			else delete target.skillPath;
 		} else return "config.skillPath must be a comma-separated string, string array, or false when provided.";
 	}
 	if (hasKey(cfg, "extensions")) {
-		if (cfg.extensions === false) target.extensions = undefined;
+		if (cfg.extensions === false) delete target.extensions;
 		else if (cfg.extensions === "") target.extensions = [];
 		else if (typeof cfg.extensions === "string") target.extensions = parseCsv(cfg.extensions);
 		else return "config.extensions must be a comma-separated string, empty string, or false when provided.";
 	}
 	if (hasKey(cfg, "subagentOnlyExtensions")) {
-		if (cfg.subagentOnlyExtensions === false) target.subagentOnlyExtensions = undefined;
+		if (cfg.subagentOnlyExtensions === false) delete target.subagentOnlyExtensions;
 		else if (cfg.subagentOnlyExtensions === "") target.subagentOnlyExtensions = [];
 		else if (typeof cfg.subagentOnlyExtensions === "string") target.subagentOnlyExtensions = parseCsv(cfg.subagentOnlyExtensions);
 		else return "config.subagentOnlyExtensions must be a comma-separated string, empty string, or false when provided.";
 	}
 	if (hasKey(cfg, "thinking")) {
-		if (cfg.thinking === false || cfg.thinking === "") target.thinking = undefined;
-		else if (typeof cfg.thinking === "string") target.thinking = cfg.thinking.trim() || undefined;
-		else return "config.thinking must be a string or false when provided.";
+		if (cfg.thinking === false || cfg.thinking === "") delete target.thinking;
+		else if (typeof cfg.thinking === "string") {
+			const thinking = cfg.thinking.trim();
+			if (thinking) target.thinking = thinking;
+			else delete target.thinking;
+		} else return "config.thinking must be a string or false when provided.";
 	}
 	if (hasKey(cfg, "systemPromptMode")) {
 		if (cfg.systemPromptMode === "append" || cfg.systemPromptMode === "replace") target.systemPromptMode = cfg.systemPromptMode;
@@ -465,30 +525,31 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		target.inheritSkills = cfg.inheritSkills;
 	}
 	if (hasKey(cfg, "defaultContext")) {
-		if (cfg.defaultContext === false || cfg.defaultContext === "") target.defaultContext = undefined;
+		if (cfg.defaultContext === false || cfg.defaultContext === "") delete target.defaultContext;
 		else if (cfg.defaultContext === "fresh" || cfg.defaultContext === "fork") target.defaultContext = cfg.defaultContext;
 		else return "config.defaultContext must be 'fresh', 'fork', or false when provided.";
 	}
 	if (hasKey(cfg, "async")) {
-		if (cfg.async === "") target.defaultAsync = undefined;
+		if (cfg.async === "") delete target.defaultAsync;
 		else if (typeof cfg.async === "boolean") target.defaultAsync = cfg.async;
 		else return "config.async must be a boolean or empty string when provided.";
 	}
 	if (hasKey(cfg, "timeoutMs")) {
-		if (cfg.timeoutMs === false || cfg.timeoutMs === "") target.defaultTimeoutMs = undefined;
+		if (cfg.timeoutMs === false || cfg.timeoutMs === "") delete target.defaultTimeoutMs;
 		else if (typeof cfg.timeoutMs === "number" && Number.isInteger(cfg.timeoutMs) && cfg.timeoutMs > 0) target.defaultTimeoutMs = cfg.timeoutMs;
 		else return "config.timeoutMs must be a positive integer or false when provided.";
 	}
 	if (hasKey(cfg, "turnBudget")) {
-		if (cfg.turnBudget === false || cfg.turnBudget === "") target.defaultTurnBudget = undefined;
+		if (cfg.turnBudget === false || cfg.turnBudget === "") delete target.defaultTurnBudget;
 		else {
 			const resolved = resolveTurnBudgetConfig(cfg.turnBudget, "config.turnBudget");
 			if (resolved.error) return resolved.error;
-			target.defaultTurnBudget = resolved.turnBudget;
+			if (resolved.turnBudget !== undefined) target.defaultTurnBudget = resolved.turnBudget;
+			else delete target.defaultTurnBudget;
 		}
 	}
 	if (hasKey(cfg, "acceptance")) {
-		if (cfg.acceptance === "") target.defaultAcceptance = undefined;
+		if (cfg.acceptance === "") delete target.defaultAcceptance;
 		else {
 			const errors = validateAcceptanceInput(cfg.acceptance, "config.acceptance");
 			if (errors.length > 0) return errors.join(" ");
@@ -496,20 +557,21 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		}
 	}
 	if (hasKey(cfg, "acceptanceRole")) {
-		if (cfg.acceptanceRole === false || cfg.acceptanceRole === "") target.acceptanceRole = undefined;
+		if (cfg.acceptanceRole === false || cfg.acceptanceRole === "") delete target.acceptanceRole;
 		else if (cfg.acceptanceRole === "read-only" || cfg.acceptanceRole === "writer") target.acceptanceRole = cfg.acceptanceRole;
 		else return "config.acceptanceRole must be 'read-only', 'writer', or false when provided.";
 	}
 	if (hasKey(cfg, "output")) {
-		if (cfg.output === false || cfg.output === "") target.output = undefined;
+		if (cfg.output === false || cfg.output === "") delete target.output;
 		else if (typeof cfg.output === "string") target.output = cfg.output;
 		else return "config.output must be a string or false when provided.";
 	}
 	if (hasKey(cfg, "reads")) {
-		if (cfg.reads === false || cfg.reads === "") target.defaultReads = undefined;
+		if (cfg.reads === false || cfg.reads === "") delete target.defaultReads;
 		else if (typeof cfg.reads === "string") {
 			const reads = parseCsv(cfg.reads);
-			target.defaultReads = reads.length ? reads : undefined;
+			if (reads.length) target.defaultReads = reads;
+			else delete target.defaultReads;
 		} else return "config.reads must be a comma-separated string or false when provided.";
 	}
 	if (hasKey(cfg, "progress")) {
@@ -517,7 +579,7 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		target.defaultProgress = cfg.progress;
 	}
 	if (hasKey(cfg, "maxSubagentDepth")) {
-		if (cfg.maxSubagentDepth === false || cfg.maxSubagentDepth === "") target.maxSubagentDepth = undefined;
+		if (cfg.maxSubagentDepth === false || cfg.maxSubagentDepth === "") delete target.maxSubagentDepth;
 		else if (typeof cfg.maxSubagentDepth === "number" && Number.isInteger(cfg.maxSubagentDepth) && cfg.maxSubagentDepth >= 0) {
 			target.maxSubagentDepth = cfg.maxSubagentDepth;
 		} else return "config.maxSubagentDepth must be an integer >= 0 or false when provided.";
@@ -527,13 +589,28 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		target.completionGuard = cfg.completionGuard;
 	}
 	if (hasKey(cfg, "toolBudget")) {
-		if (cfg.toolBudget === false || cfg.toolBudget === "") target.toolBudget = undefined;
+		if (cfg.toolBudget === false || cfg.toolBudget === "") delete target.toolBudget;
 		else {
 			const validation = validateToolBudgetConfig(cfg.toolBudget, "config.toolBudget");
 			if (validation.error) return validation.error;
 			target.toolBudget = cfg.toolBudget as ToolBudgetConfig;
 		}
 	}
+	if (target.runner?.type === "external-cli") {
+		const unsupported = [
+			target.tools?.length || target.mcpDirectTools?.length ? "tools" : undefined,
+			target.model ? "model" : undefined,
+			target.fallbackModels?.length ? "fallbackModels" : undefined,
+			target.thinking ? "thinking" : undefined,
+			target.extensions?.length ? "extensions" : undefined,
+			target.subagentOnlyExtensions?.length ? "subagentOnlyExtensions" : undefined,
+			target.skills?.length || target.skillPath?.length ? "skills" : undefined,
+			target.maxSubagentDepth !== undefined ? "maxSubagentDepth" : undefined,
+			target.completionGuard !== undefined ? "completionGuard" : undefined,
+			target.toolBudget ? "toolBudget" : undefined,
+		].filter((field): field is string => Boolean(field));
+		if (unsupported.length > 0) return `config.runner type 'external-cli' does not support Pi-only fields: ${unsupported.join(", ")}.`;
+	}
 	return undefined;
 }
 
@@ -599,6 +676,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
 	if (agent.skillPath?.length) lines.push(`Skill paths: ${agent.skillPath.join(", ")}`);
 	lines.push(`System prompt mode: ${agent.systemPromptMode}`);
+	if (agent.runner) lines.push(`Runner: ${JSON.stringify(agent.runner)}`);
 	lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
 	lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
 	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
@@ -687,7 +765,7 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const proactiveSuggestions = buildProactiveSkillSubagentRecommendationLines({
 		agents,
 		chains,
-		config: ctx.config?.proactiveSkillSubagents,
+		...(ctx.config?.proactiveSkillSubagents !== undefined ? { config: ctx.config.proactiveSkillSubagents } : {}),
 		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
 	});
 	const lines = [
@@ -857,7 +935,15 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	if (isChain) {
 		const parsed = parseStepList(cfg.steps);
 		if (parsed.error) return result(parsed.error, true);
-		const chain: ChainConfig = { name: runtimeName, localName: name, packageName: parsedPackage.packageName, description: cfg.description.trim(), source: scope, filePath: targetPath, steps: parsed.steps! };
+		const chain: ChainConfig = {
+			name: runtimeName,
+			localName: name,
+			...(parsedPackage.packageName !== undefined ? { 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(", ")}.`);
@@ -867,7 +953,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const agent: AgentConfig = {
 		name: runtimeName,
 		localName: name,
-		packageName: parsedPackage.packageName,
+		...(parsedPackage.packageName !== undefined ? { packageName: parsedPackage.packageName } : {}),
 		description: cfg.description.trim(),
 		source: scope,
 		filePath: targetPath,
@@ -898,9 +984,10 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 	const warnings: string[] = [];
 	if (params.agent) {
 		const scopeHint = asDisambiguationScope(params.agentScope);
-		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, scopeHint);
 		if ("content" in targetOrError) return targetOrError;
 		const target = targetOrError;
+		if (target.source !== "user" && target.source !== "project") return result(`Cannot update ${target.source} agent '${target.name}'. Eject it to user or project scope first.`, true);
 		const updated = editableAgentConfig(target);
 		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);
@@ -920,7 +1007,8 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		if (applyError) return result(applyError, true);
 		const preserveFrontmatterFields = preservedAgentFrontmatterFields(target, cfg);
 		updated.localName = newLocalName;
-		updated.packageName = newPackageName;
+		if (newPackageName !== undefined) updated.packageName = newPackageName;
+		else delete updated.packageName;
 		updated.name = buildRuntimeName(newLocalName, newPackageName);
 		if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
 		if (hasKey(cfg, "model")) {
@@ -951,9 +1039,10 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		return result([headline, ...warnings].join("\n"));
 	}
 	const scopeHint = asDisambiguationScope(params.agentScope);
-	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"), ctx.cwd, scopeHint);
 	if ("content" in targetOrError) return targetOrError;
 	const target = targetOrError;
+	if (target.source !== "user" && target.source !== "project") return result(`Cannot update ${target.source} chain '${target.name}'. Eject it to user or project scope first.`, true);
 	const updated: ChainConfig = { ...target, steps: [...target.steps] };
 	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);
@@ -976,7 +1065,8 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 		parsedSteps = parsed.steps!;
 	}
 	updated.localName = newLocalName;
-	updated.packageName = newPackageName;
+	if (newPackageName !== undefined) updated.packageName = newPackageName;
+	else delete updated.packageName;
 	updated.name = buildRuntimeName(newLocalName, newPackageName);
 	if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
 	if (parsedSteps) {
@@ -1002,7 +1092,7 @@ function handleDelete(params: ManagementParams, ctx: ManagementContext): AgentTo
 	if (params.agent && params.chainName) return result("Specify either 'agent' or 'chainName', not both.", true);
 	const scopeHint = asDisambiguationScope(params.agentScope);
 	if (params.agent) {
-		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+		const targetOrError = resolveTarget("agent", params.agent, findAgents(params.agent, ctx.cwd, scopeHint ?? "both"), ctx.cwd, scopeHint);
 		if ("content" in targetOrError) return targetOrError;
 		const target = targetOrError;
 		fs.unlinkSync(target.filePath);
@@ -1011,7 +1101,7 @@ function handleDelete(params: ManagementParams, ctx: ManagementContext): AgentTo
 		if (refs.length) lines.push(`Warning: chains reference deleted agent '${target.name}': ${refs.join(", ")}.`);
 		return result(lines.join("\n"));
 	}
-	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"), ctx.cwd, params.agentScope);
+	const targetOrError = resolveTarget("chain", params.chainName!, findChains(params.chainName!, ctx.cwd, scopeHint ?? "both"), ctx.cwd, scopeHint);
 	if ("content" in targetOrError) return targetOrError;
 	const target = targetOrError;
 	fs.unlinkSync(target.filePath);

package/src/agents/agent-serializer.ts

@@ -1,3 +1,4 @@
+import { stringify as stringifyYaml } from "yaml";
 import type { AgentConfig } from "./agents.ts";
 import { frontmatterNameForConfig } from "./identity.ts";
 
@@ -32,7 +33,10 @@ export const KNOWN_FIELDS = new Set([
 	"maxSubagentDepth",
 	"completionGuard",
 	"toolBudget",
+	"permission",
+	"permissions",
 	"memory",
+	"runner",
 ]);
 
 function joinComma(values: string[] | undefined): string | undefined {
@@ -72,6 +76,14 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 	if (!preservingExistingFrontmatter || preserve("inheritProjectContext")) lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
 	if (!preservingExistingFrontmatter || preserve("inheritSkills")) lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
 	if (config.defaultContext || preserve("defaultContext")) lines.push(`defaultContext: ${config.defaultContext ?? ""}`);
+	if (config.runner || preserve("runner")) {
+		if (config.runner) {
+			lines.push("runner:");
+			for (const line of stringifyYaml(config.runner).trimEnd().split("\n")) lines.push(`  ${line}`);
+		} else {
+			lines.push("runner:");
+		}
+	}
 	if (config.defaultAsync !== undefined || preserve("async")) lines.push(`async: ${config.defaultAsync === undefined ? "" : config.defaultAsync ? "true" : "false"}`);
 	if (config.defaultTimeoutMs !== undefined || preserve("timeoutMs")) lines.push(`timeoutMs: ${config.defaultTimeoutMs ?? ""}`);
 	if (config.defaultTurnBudget || preserve("turnBudget")) lines.push(`turnBudget: ${config.defaultTurnBudget ? JSON.stringify(config.defaultTurnBudget) : ""}`);
@@ -115,6 +127,13 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 	if (config.toolBudget || preserve("toolBudget")) {
 		lines.push(`toolBudget: ${config.toolBudget ? JSON.stringify(config.toolBudget) : ""}`);
 	}
+	if (config.permissions || preserve("permission", "permissions")) {
+		const key = preserve("permission") && !preserve("permissions") ? "permission" : "permissions";
+		lines.push(`${key}:`);
+		if (config.permissions) {
+			for (const line of stringifyYaml(config.permissions).trimEnd().split("\n")) lines.push(`  ${line}`);
+		}
+	}
 
 	if (config.memory) {
 		lines.push("memory:");