pi-subagents 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-06-20
+
+### Added
+- Allow active async chains to accept an `append-step` request that adds one new tail step while the chain is still running.
+- Allow async subagent results to be attached as the root step of a new follow-up chain.
+- Added `subagentOnlyExtensions` so agents can pass selected tool extensions only to spawned subagents without exposing them to the parent agent.
+- Added proactive skill-subagent suggestions to `subagent({ action: "list" })` based on repeatedly configured skill use, while keeping the behavior advisory and opt-out friendly.
+- Added regression coverage for long worker/reviewer chains and parallel -> funnel -> fanout chain flows across foreground and async execution.
+
+### Fixed
+- Interrupt live async children before delivering `resume` follow-up messages so intercom nudges reach workers that are stuck mid-turn more reliably.
+- Reject appended chain steps with duplicate reserved output names or unknown named-output references before they are queued.
+- Ignore legacy `.agents/skills` files during agent discovery so skill definitions are not registered as subagents. Thanks to chyax98 (@chyax98) for #257.
+- Launch detached async runners through Node when Pi itself is not the Node executable. Thanks to Tetsuya.dev (@tetsuya-dev-jp) for #273.
+- Preserve the slash command requester context when bridge requests launch subagents. Thanks to Victor Sumner (@vsumner) for #268.
+- Trim repeated nested `subagent` tool schema descriptions so provider payloads stay compact while retaining top-level parameter guidance. Thanks to Thomas Mustier (@tmustier) for #250.
+
 ## [0.29.0] - 2026-06-19
 
 ### Added

package/README.md

@@ -424,6 +424,7 @@ package: code-analysis
 description: Fast codebase recon
 tools: read, grep, find, ls, bash, mcp:chrome-devtools
 extensions:
+subagentOnlyExtensions: ./tools/child-only-search.ts
 model: claude-haiku-4-5
 fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
 thinking: high
@@ -449,6 +450,7 @@ Important fields:
 | `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. |
+| `subagentOnlyExtensions` | Comma-separated extension paths loaded only in spawned child sessions for this agent. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
 | `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
 | `fallbackModels` | Ordered backup models for provider/model failures such as quota, auth, timeout, or unavailable model. Ordinary task failures do not trigger fallback. |
 | `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. |
@@ -491,6 +493,8 @@ extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts
 
 When `extensions` is present, it takes precedence over extension paths implied by `tools` entries.
 
+Use `subagentOnlyExtensions` when a custom extension tool should exist only inside child sessions. It is scoped by agent config: every run of that agent receives those extension paths, while other agents do not unless they declare the same field. The current model does not have a separate named-subagent audience inside one agent definition.
+
 ## Chain files
 
 Chains are reusable workflows stored separately from agent files. Use `.chain.md` for simple sequential saved chains. Use `.chain.json` when a chain needs dynamic fanout.
@@ -786,7 +790,7 @@ Agent definitions are not loaded into context by default. Management actions let
 |-------|------|---------|-------------|
 | `agent` | string | - | Agent name for single mode, or target for management actions. |
 | `task` | string | - | Task string for single mode. |
-| `action` | string | - | `list`, `get`, `create`, `update`, `delete`, `status`, `interrupt`, `resume`, or `doctor`. |
+| `action` | string | - | `list`, `get`, `create`, `update`, `delete`, `status`, `interrupt`, `resume`, `append-step`, or `doctor`. |
 | `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. |
@@ -796,7 +800,7 @@ Agent definitions are not loaded into context by default. Management actions let
 | `tasks` | array | - | Top-level parallel tasks. Supports `agent`, `task`, `cwd`, `count`, `output`, `outputMode`, `reads`, `progress`, `skill`, `model`, and `acceptance`. |
 | `concurrency` | number | config or `4` | Top-level parallel concurrency. |
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
-| `chain` | array | - | Sequential, static parallel, and dynamic fanout chain steps. Steps and chain parallel tasks support `phase`, `label`, `as`, `outputSchema`, and `acceptance` in addition to the usual execution fields. Dynamic fanout uses `expand`, one child `parallel` template, and `collect`. |
+| `chain` | array | - | Sequential, static parallel, and dynamic fanout chain steps. Steps and chain parallel tasks support `phase`, `label`, `as`, `outputSchema`, and `acceptance` in addition to the usual execution fields. Dynamic fanout uses `expand`, one child `parallel` template, and `collect`. With `action: "append-step"`, pass exactly one step to append to a running async chain. |
 | `context` | `fresh \| fork` | agent default or `fresh` | `fork` creates real branched sessions from the parent leaf. Packaged `planner`, `worker`, and `oracle` default to `fork`. |
 | `chainDir` | string | temp chain dir | Persistent directory for chain artifacts. |
 | `clarify` | boolean | true for chains | Show TUI preview/edit flow. |
@@ -827,6 +831,7 @@ subagent({ action: "interrupt", id: "<nested-run-id>" })
 subagent({ action: "resume", id: "<run-id>", message: "follow-up question" })
 subagent({ action: "resume", id: "<run-id>", index: 1, message: "follow-up for child 2" })
 subagent({ action: "resume", id: "<nested-run-id>", message: "follow-up for a nested child" })
+subagent({ action: "append-step", id: "<run-id>", chain: [{ agent: "worker", task: "Continue from {previous}" }] })
 subagent({ action: "doctor" })
 ```
 
@@ -834,6 +839,8 @@ subagent({ action: "doctor" })
 
 `resume` sends the follow-up directly when an async child is still reachable over intercom. After completion, it revives the child by starting a new async child from the stored child session file. Multi-child async runs and remembered foreground single, parallel, or chain runs can be revived by passing `index` to choose the child. Nested runs can be resumed by nested id when their live route or persisted session metadata is available. Revive starts a new child process from the old session context; it does not restart the same OS process, and it requires the chosen child to have a persisted `.jsonl` session file.
 
+`append-step` accepts exactly one sequential, static parallel, or dynamic fanout chain step for a top-level async chain whose status is still `running`. The step is persisted in the run directory and becomes eligible only after the chain's already-queued steps finish; completed, failed, paused, foreground, single, and top-level parallel runs reject appends.
+
 ## Worktree isolation
 
 Parallel agents can clobber each other if they edit the same checkout. `worktree: true` gives each parallel child its own git worktree branched from `HEAD`.

package/package.json

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

package/skills/pi-subagents/SKILL.md

@@ -20,6 +20,7 @@ Use this skill when the parent orchestrator needs to launch a specialized subage
 - **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
 - **Recon and planning**: use `scout` or `context-builder`, then `planner`
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
+- **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
 - **Long-running work**: launch async/background runs and inspect them later
 - **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
 - **Agent authoring**: create, update, or override agents and chains for a project
@@ -55,6 +56,30 @@ The prompt templates in `prompts/` encode workflows the parent agent can run on
 
 Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
 
+### Proactive skill-specialist technique
+
+Use this when `{ action: "list" }` reports proactive skill subagent suggestions and the user's task would benefit from perspectives the parent regularly uses. These suggestions are conservative: a skill is recommended only when it is available and referenced repeatedly by configured agents or saved chains. Treat the list as an opt-in hint for the current task, not a command to always fan out.
+
+Default guardrails:
+- Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap.
+- Prefer `context: "fresh"` and include only the files, diff, plan, URL, or request details each child needs. Use forked context only when private/session history is essential and appropriate to share.
+- Use read-only agents for analysis/review unless implementation was explicitly requested; do not create several writers in the same worktree.
+- Skip proactive skill subagents for tiny questions, direct commands, highly private requests, or when the user asks not to delegate.
+- Make cost and concurrency visible by using an ordinary `subagent(...)` call rather than hidden/background automation.
+
+Example shape:
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "reviewer", task: "Apply the available 'deslop' skill to review the current diff for concrete cleanup findings only. Do not modify files.", skill: "deslop" },
+    { agent: "reviewer", task: "Apply the available 'accessibility' skill to review the UI changes for concrete issues only. Do not modify files.", skill: "accessibility" }
+  ],
+  context: "fresh",
+  concurrency: 2
+})
+```
+
 ### Review-loop technique
 
 Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background chain when the workflow is known, or continue with explicit follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless the user explicitly wants the foreground clarify UI. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no blockers or fixes worth doing now, remaining feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.

package/src/agents/agent-management.ts

@@ -19,11 +19,14 @@ import {
 import { serializeAgent } from "./agent-serializer.ts";
 import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
 import { discoverAvailableSkills } from "./skills.ts";
-import type { Details } from "../shared/types.ts";
+import {
+	buildProactiveSkillSubagentRecommendationLines,
+} from "./proactive-skills.ts";
+import type { Details, ExtensionConfig } from "../shared/types.ts";
 
 type ManagementAction = "list" | "get" | "create" | "update" | "delete";
 type ManagementScope = "user" | "project";
-type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry">;
+type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { config?: ExtensionConfig };
 
 interface ManagementParams {
 	action?: string;
@@ -273,6 +276,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		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;
+		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;
@@ -385,6 +394,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
 	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
+	if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
@@ -450,6 +460,12 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const agents = scopedAgents.filter((a) => !a.disabled);
 	const chains = d.chains.filter((c) => scope === "both" || c.source === "package" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const diagnostics = d.chainDiagnostics.filter((entry) => scope === "both" || entry.source === scope);
+	const proactiveSuggestions = buildProactiveSkillSubagentRecommendationLines({
+		agents,
+		chains,
+		config: ctx.config?.proactiveSkillSubagents,
+		discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
+	});
 	const lines = [
 		"Executable agents:",
 		...(agents.length
@@ -458,6 +474,7 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),
+		...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
 		...(diagnostics.length ? ["", "Chain diagnostics:", ...diagnostics.map((entry) => `- ${entry.filePath}: ${entry.error}`)] : []),
 	];
 	return result(lines.join("\n"));

package/src/agents/agent-serializer.ts

@@ -16,6 +16,7 @@ export const KNOWN_FIELDS = new Set([
 	"skill",
 	"skills",
 	"extensions",
+	"subagentOnlyExtensions",
 	"output",
 	"defaultReads",
 	"defaultProgress",
@@ -59,6 +60,10 @@ export function serializeAgent(config: AgentConfig): string {
 		const extensionsValue = joinComma(config.extensions);
 		lines.push(`extensions: ${extensionsValue ?? ""}`);
 	}
+	if (config.subagentOnlyExtensions !== undefined) {
+		const subagentOnlyExtensionsValue = joinComma(config.subagentOnlyExtensions);
+		lines.push(`subagentOnlyExtensions: ${subagentOnlyExtensionsValue ?? ""}`);
+	}
 
 	if (config.output) lines.push(`output: ${config.output}`);
 

package/src/agents/agents.ts

@@ -47,6 +47,7 @@ export interface BuiltinAgentOverrideBase {
 	skills?: string[];
 	tools?: string[];
 	mcpDirectTools?: string[];
+	subagentOnlyExtensions?: string[];
 	completionGuard?: boolean;
 }
 
@@ -62,6 +63,7 @@ interface BuiltinAgentOverrideConfig {
 	systemPrompt?: string;
 	skills?: string[] | false;
 	tools?: string[] | false;
+	subagentOnlyExtensions?: string[] | false;
 	completionGuard?: boolean;
 }
 
@@ -90,6 +92,7 @@ export interface AgentConfig {
 	filePath: string;
 	skills?: string[];
 	extensions?: string[];
+	subagentOnlyExtensions?: string[];
 	output?: string;
 	defaultReads?: string[];
 	defaultProgress?: boolean;
@@ -457,6 +460,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		skills: agent.skills ? [...agent.skills] : undefined,
 		tools: agent.tools ? [...agent.tools] : undefined,
 		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
+		subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : undefined,
 		completionGuard: agent.completionGuard,
 	};
 }
@@ -476,6 +480,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
 		...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
 		...(override.tools !== undefined ? { tools: override.tools === false ? false : [...override.tools] } : {}),
+		...(override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {}),
 		...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
 	};
 }
@@ -635,6 +640,9 @@ function parseBuiltinOverrideEntry(
 	const tools = parseOverrideStringArrayOrFalse(input.tools, { filePath, name, field: "tools" });
 	if (tools !== undefined) override.tools = tools;
 
+	const subagentOnlyExtensions = parseOverrideStringArrayOrFalse(input.subagentOnlyExtensions, { filePath, name, field: "subagentOnlyExtensions" });
+	if (subagentOnlyExtensions !== undefined) override.subagentOnlyExtensions = subagentOnlyExtensions;
+
 	return Object.keys(override).length > 0 ? override : undefined;
 }
 
@@ -693,6 +701,9 @@ function applyBuiltinOverride(
 		next.tools = tools;
 		next.mcpDirectTools = mcpDirectTools;
 	}
+	if (override.subagentOnlyExtensions !== undefined) {
+		next.subagentOnlyExtensions = override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions];
+	}
 	if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
 
 	return next;
@@ -733,7 +744,7 @@ function applyBuiltinOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "completionGuard">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "subagentOnlyExtensions" | "completionGuard">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -751,6 +762,9 @@ export function buildBuiltinOverrideConfig(
 	const baseTools = joinToolList(base);
 	const draftTools = joinToolList(draft);
 	if (!arraysEqual(draftTools, baseTools)) override.tools = draftTools ? [...draftTools] : false;
+	if (!arraysEqual(draft.subagentOnlyExtensions, base.subagentOnlyExtensions)) {
+		override.subagentOnlyExtensions = draft.subagentOnlyExtensions ? [...draft.subagentOnlyExtensions] : false;
+	}
 	if ((draft.completionGuard !== false) !== (base.completionGuard !== false)) {
 		override.completionGuard = draft.completionGuard !== false;
 	}
@@ -830,10 +844,23 @@ function listFilesRecursive(dir: string, predicate: (fileName: string) => boolea
 	return files;
 }
 
+function isLegacyAgentSkillPath(rootDir: string, filePath: string): boolean {
+	const relative = path.relative(rootDir, filePath);
+	const parts = relative.split(path.sep).map((part) => part.toLowerCase());
+	if (path.basename(rootDir).toLowerCase() === ".agents") {
+		parts.unshift(".agents");
+	}
+	return parts.some((part, index) => part === ".agents" && parts[index + 1] === "skills");
+}
+
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
 	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
+		if (isLegacyAgentSkillPath(dir, filePath)) {
+			continue;
+		}
+
 		let content: string;
 		try {
 			content = fs.readFileSync(filePath, "utf-8");
@@ -912,6 +939,13 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 				.map((e) => e.trim())
 				.filter(Boolean);
 		}
+		let subagentOnlyExtensions: string[] | undefined;
+		if (frontmatter.subagentOnlyExtensions !== undefined) {
+			subagentOnlyExtensions = frontmatter.subagentOnlyExtensions
+				.split(",")
+				.map((e) => e.trim())
+				.filter(Boolean);
+		}
 
 		const extraFields: Record<string, string> = {};
 		for (const [key, value] of Object.entries(frontmatter)) {
@@ -944,6 +978,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			filePath,
 			skills: skills && skills.length > 0 ? skills : undefined,
 			extensions,
+			subagentOnlyExtensions,
 			output: frontmatter.output,
 			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,
 			defaultProgress: frontmatter.defaultProgress === "true",

package/src/agents/proactive-skills.ts

@@ -0,0 +1,191 @@
+import type { AgentConfig, ChainConfig, ChainStepConfig } from "./agents.ts";
+import type { ProactiveSkillSubagentsConfig } from "../shared/types.ts";
+
+const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
+const DEFAULT_MIN_REFERENCES = 2;
+const DEFAULT_MAX_RECOMMENDATIONS = 3;
+const DEFAULT_PREFERRED_AGENT = "reviewer";
+const FALLBACK_AGENT_ORDER = ["reviewer", "context-builder", "delegate"];
+const MAX_RECOMMENDATION_CAP = 5;
+
+export interface ResolvedProactiveSkillSubagentsConfig {
+	enabled: boolean;
+	minReferences: number;
+	maxRecommendations: number;
+	preferredAgent: string;
+}
+
+export interface ProactiveSkillSubagentRecommendation {
+	skill: string;
+	agent: string;
+	references: number;
+	sources: string[];
+	description?: string;
+	reason: string;
+}
+
+export interface AvailableSkill {
+	name: string;
+	description?: string;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isInteger(value) || !Number.isFinite(value) || value < 1) return undefined;
+	return value;
+}
+
+export function resolveProactiveSkillSubagentsConfig(
+	config?: ProactiveSkillSubagentsConfig | false,
+): ResolvedProactiveSkillSubagentsConfig {
+	if (config === false) {
+		return {
+			enabled: false,
+			minReferences: DEFAULT_MIN_REFERENCES,
+			maxRecommendations: DEFAULT_MAX_RECOMMENDATIONS,
+			preferredAgent: DEFAULT_PREFERRED_AGENT,
+		};
+	}
+
+	const maxRecommendations = positiveInteger(config?.maxRecommendations) ?? DEFAULT_MAX_RECOMMENDATIONS;
+	return {
+		enabled: config?.enabled ?? true,
+		minReferences: positiveInteger(config?.minReferences) ?? DEFAULT_MIN_REFERENCES,
+		maxRecommendations: Math.min(maxRecommendations, MAX_RECOMMENDATION_CAP),
+		preferredAgent: typeof config?.preferredAgent === "string" && config.preferredAgent.trim()
+			? config.preferredAgent.trim()
+			: DEFAULT_PREFERRED_AGENT,
+	};
+}
+
+function normalizeSkillNames(value: unknown): string[] {
+	if (value === false || value === true || value === undefined || value === null) return [];
+	if (Array.isArray(value)) {
+		return [...new Set(value.filter((entry): entry is string => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean))];
+	}
+	if (typeof value === "string") {
+		return [...new Set(value.split(",").map((entry) => entry.trim()).filter(Boolean))];
+	}
+	return [];
+}
+
+function collectStepSkills(step: ChainStepConfig, out: Set<string>): void {
+	for (const skill of normalizeSkillNames(step.skills ?? (step as { skill?: unknown }).skill)) {
+		out.add(skill);
+	}
+
+	const parallel = step.parallel;
+	if (!parallel) return;
+	if (Array.isArray(parallel)) {
+		for (const child of parallel) {
+			if (child && typeof child === "object" && !Array.isArray(child)) {
+				collectStepSkills(child as ChainStepConfig, out);
+			}
+		}
+		return;
+	}
+	if (typeof parallel === "object") {
+		collectStepSkills(parallel as ChainStepConfig, out);
+	}
+}
+
+function chooseRecommendationAgent(agents: AgentConfig[], preferredAgent: string): string | undefined {
+	const enabled = agents.filter((agent) => !agent.disabled);
+	if (enabled.some((agent) => agent.name === preferredAgent)) return preferredAgent;
+	for (const name of FALLBACK_AGENT_ORDER) {
+		if (enabled.some((agent) => agent.name === name)) return name;
+	}
+	return enabled[0]?.name;
+}
+
+function addSource(counts: Map<string, Set<string>>, skill: string, source: string): void {
+	if (skill === SUBAGENT_ORCHESTRATION_SKILL) return;
+	const sources = counts.get(skill) ?? new Set<string>();
+	sources.add(source);
+	counts.set(skill, sources);
+}
+
+export function recommendProactiveSkillSubagents(input: {
+	agents: AgentConfig[];
+	chains?: ChainConfig[];
+	availableSkills?: AvailableSkill[];
+	config?: ProactiveSkillSubagentsConfig | false;
+}): ProactiveSkillSubagentRecommendation[] {
+	const config = resolveProactiveSkillSubagentsConfig(input.config);
+	if (!config.enabled) return [];
+
+	const agent = chooseRecommendationAgent(input.agents, config.preferredAgent);
+	if (!agent) return [];
+
+	const availableByName = input.availableSkills
+		? new Map(input.availableSkills.map((skill) => [skill.name, skill]))
+		: undefined;
+	const counts = new Map<string, Set<string>>();
+
+	for (const candidate of input.agents) {
+		if (candidate.disabled) continue;
+		for (const skill of candidate.skills ?? []) {
+			addSource(counts, skill, `agent:${candidate.name}`);
+		}
+	}
+
+	for (const chain of input.chains ?? []) {
+		const chainSkills = new Set<string>();
+		for (const step of chain.steps) {
+			collectStepSkills(step, chainSkills);
+		}
+		for (const skill of chainSkills) {
+			addSource(counts, skill, `chain:${chain.name}`);
+		}
+	}
+
+	return [...counts.entries()]
+		.filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)))
+		.map(([skill, sources]) => ({
+			skill,
+			agent,
+			references: sources.size,
+			sources: [...sources].sort((a, b) => a.localeCompare(b)),
+			description: availableByName?.get(skill)?.description,
+			reason: `referenced by ${sources.size} configured agents/chains`,
+		}))
+		.sort((a, b) => b.references - a.references || a.skill.localeCompare(b.skill))
+		.slice(0, config.maxRecommendations);
+}
+
+export function formatProactiveSkillSubagentRecommendations(
+	recommendations: ProactiveSkillSubagentRecommendation[],
+): string[] {
+	if (recommendations.length === 0) return [];
+	return [
+		"Proactive skill subagent suggestions:",
+		...recommendations.map((recommendation) => {
+			const sampleSources = recommendation.sources.slice(0, 3).join(", ");
+			const extra = recommendation.sources.length > 3 ? `, +${recommendation.sources.length - 3} more` : "";
+			const description = recommendation.description ? ` - ${recommendation.description}` : "";
+			return `- ${recommendation.skill} via ${recommendation.agent} (${recommendation.reason}; ${sampleSources}${extra})${description}`;
+		}),
+		"Guardrails: use these for broad tasks where a skill-specialist pass is useful; keep fanout small, use fresh context unless private/session context is explicitly needed, and skip when the user asks for a direct answer.",
+	];
+}
+
+export function buildProactiveSkillSubagentRecommendationLines(input: {
+	agents: AgentConfig[];
+	chains?: ChainConfig[];
+	config?: ProactiveSkillSubagentsConfig | false;
+	discoverAvailableSkills: () => AvailableSkill[];
+}): string[] {
+	if (!resolveProactiveSkillSubagentsConfig(input.config).enabled) return [];
+	let availableSkills: AvailableSkill[];
+	try {
+		availableSkills = input.discoverAvailableSkills();
+	} catch {
+		availableSkills = [];
+	}
+	return formatProactiveSkillSubagentRecommendations(recommendProactiveSkillSubagents({
+		agents: input.agents,
+		chains: input.chains,
+		availableSkills,
+		config: input.config,
+	}));
+}

package/src/extension/fanout-child.ts

@@ -156,7 +156,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		label: "Subagent",
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
-			"Allowed management/control actions: list, get, status, interrupt, resume, doctor.",
+			"Allowed management/control actions: list, get, status, interrupt, resume, append-step, doctor.",
 			"Agent config mutation actions create, update, and delete are blocked in this mode.",
 		].join("\n"),
 		parameters: SubagentParams,

package/src/extension/index.ts

@@ -393,6 +393,7 @@ EXECUTION (use exactly ONE mode):
 • CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
 • Optional context: { context: "fresh" | "fork" } (default: if any requested agent has defaultContext: "fork", the whole invocation uses fork; otherwise "fresh"; inspect agent defaults via { action: "list" })
+• If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
 
 CHAIN TEMPLATE VARIABLES (use in task strings):
 • {task} - The original task/request from the user
@@ -412,7 +413,8 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 CONTROL:
 • { action: "status", id: "..." } - inspect an async/background run by id or prefix
 • { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
-• { action: "resume", id: "...", message: "...", index?: 0 } - follow up with a live async child or revive a completed async/foreground child from its session
+• { action: "resume", id: "...", message: "...", index?: 0 } - interrupt then follow up with a live async child, or revive a completed async/foreground child from its session
+• { action: "append-step", id: "...", chain: [{agent:"agent-c", task:"Use {previous}"}] } - append one step to the tail of a running async chain
 
 DIAGNOSTICS:
 • { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,

package/src/extension/schemas.ts

@@ -5,6 +5,31 @@
 import { Type } from "typebox";
 import { SUBAGENT_ACTIONS } from "../shared/types.ts";
 
+function keepTopLevelParameterDescriptions<T>(schema: T): T {
+	return pruneNestedDescriptions(schema, []) as T;
+}
+
+function pruneNestedDescriptions(value: unknown, path: string[]): unknown {
+	if (!value || typeof value !== "object") return value;
+
+	const result = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
+	for (const key of Reflect.ownKeys(value)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (!descriptor) continue;
+		if (key === "description" && !isTopLevelParameterDescription(path)) continue;
+		if ("value" in descriptor) {
+			const nextPath = typeof key === "string" ? [...path, key] : path;
+			descriptor.value = pruneNestedDescriptions(descriptor.value, nextPath);
+		}
+		Object.defineProperty(result, key, descriptor);
+	}
+	return result;
+}
+
+function isTopLevelParameterDescription(path: string[]): boolean {
+	return path.length === 2 && path[0] === "properties";
+}
+
 const SkillOverride = Type.Unsafe({
 	anyOf: [
 		{ type: "array", items: { type: "string" } },
@@ -233,7 +258,7 @@ const ControlOverrides = Type.Object({
 	})),
 });
 
-export const SubagentParams = Type.Object({
+const SubagentParamsSchema = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
 	// Management action (when present, tool operates in management mode)
@@ -242,10 +267,10 @@ export const SubagentParams = Type.Object({
 		description: "Management/control action. Omit for execution mode."
 	})),
 	id: Type.Optional(Type.String({
-		description: "Run id or prefix for action='status', action='interrupt', or action='resume'."
+		description: "Run id or prefix for action='status', action='interrupt', action='resume', or action='append-step'."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for action='interrupt' or action='resume'. Defaults to the most recently active controllable run for interrupt. Prefer id for new calls."
+		description: "Target run ID for action='interrupt', action='resume', or action='append-step'. Defaults to the most recently active controllable run for interrupt. Prefer id for new calls."
 	})),
 	dir: Type.Optional(Type.String({
 		description: "Async run directory for action='status' or action='resume'."
@@ -262,7 +287,7 @@ export const SubagentParams = Type.Object({
 			{ type: "object", additionalProperties: true },
 			{ type: "string" },
 		],
-		description: "Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
+		description: "Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), subagentOnlyExtensions (comma-separated child-only extension paths), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
 	})),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
@@ -271,7 +296,7 @@ export const SubagentParams = Type.Object({
 			"Prevents filesystem conflicts. Requires clean git state. " +
 			"Per-worktree diffs included in output."
 	})),
-	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. Use {task}, {previous}, {chain_dir} in task templates." })),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. With action='append-step', provide exactly one step to append to an active async chain; it can use {previous}, {chain_dir}, and existing {outputs.name} references." })),
 	context: Type.Optional(Type.String({
 		enum: ["fresh", "fork"],
 		description: "'fresh' or 'fork' to branch from parent session. If omitted, any requested agent with defaultContext: 'fork' makes the whole invocation forked; otherwise the default is 'fresh'.",
@@ -302,3 +327,5 @@ export const SubagentParams = Type.Object({
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
 	acceptance: Type.Optional(AcceptanceOverride),
 });
+
+export const SubagentParams = keepTopLevelParameterDescriptions(SubagentParamsSchema);