@ashx-j/lunr 0.2.11 → 0.2.13

package/dist/builtin-extensions/pi-subagents/src/runs/foreground/subagent-executor.js

@@ -2,13 +2,12 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { planModeWriteSpawnError, snapshotParentPermissionMode } from "../../../../../core/subagent-permission-inherit.js";
+import { snapshotParentPermissionMode } from "../../../../../core/subagent-permission-inherit.js";
+import { normalizeChildSpec } from "../../shared/child-spec.js";
 import { getArtifactsDir, getProjectChainRunsDir } from "../../shared/artifacts.js";
 import { ChainClarifyComponent } from "./chain-clarify.js";
 import { toModelInfo } from "../../shared/model-info.js";
 import { executeChain } from "./chain-execution.js";
-import { resolveExecutionAgentScope } from "../../agents/agent-scope.js";
-import { handleManagementAction } from "../../agents/agent-management.js";
 import { buildDoctorReport } from "../../extension/doctor.js";
 import { clearPendingForegroundControlNotices } from "../../extension/control-notices.js";
 import { runSync } from "./execution.js";
@@ -33,7 +32,7 @@ import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeSingleOut
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd, sumResultsCost, sumResultsUsage } from "../../shared/utils.js";
 import { DEFAULT_GLOBAL_CONCURRENCY_LIMIT, Semaphore } from "../shared/parallel-utils.js";
 import { attachNestedChildrenToResultChildren, buildSubagentResultIntercomPayload, deliverSubagentIntercomMessageEvent, deliverSubagentResultIntercomEvent, formatSubagentResultReceipt, resolveSubagentResultStatus, stripDetailsOutputsForIntercomReceipt, } from "../../intercom/result-intercom.js";
-import { applySteeringRecoveryAgentConfig, buildRevivedAsyncTask, interruptLiveAsyncResumeTarget, resolveAsyncResumeTarget, resolveAsyncRunLocation } from "../background/async-resume.js";
+import { buildRevivedAsyncTask, interruptLiveAsyncResumeTarget, resolveAsyncResumeTarget, resolveAsyncRunLocation } from "../background/async-resume.js";
 import { deliverInterruptRequest, deliverStopRequest, requestAsyncSteer } from "../background/control-channel.js";
 import { waitForSteeringAction } from "../background/steering.js";
 import { steerAsyncRun } from "./async-steering-action.js";
@@ -591,19 +590,24 @@ function appendStepToAsyncChain(input) {
             details: { mode: "management", results: [] },
         };
     }
-    const scope = resolveExecutionAgentScope(input.params.agentScope);
-    const discoveredForAppend = input.deps.discoverAgents(input.requestCwd, scope);
-    const agents = discoveredForAppend.agents;
-    const appendWriteSpawnError = planModeWriteSpawnError(snapshotParentPermissionMode(input.deps.state.currentSessionId), collectRequestedAgents(input.params, agents));
-    if (appendWriteSpawnError) {
+    let appendParams;
+    const appendChildRunId = `${resolved.id}-append-${randomUUID().slice(0, 8)}`;
+    try {
+        appendParams = internalizePromptDrivenChildren(input.params, {
+            runId: appendChildRunId,
+            parentMode: snapshotParentPermissionMode(input.deps.state.currentSessionId),
+            dynamicFanoutMaxItems: input.deps.config.chain?.dynamicFanout?.maxItems,
+        }).params;
+    }
+    catch (error) {
         return {
-            content: [{ type: "text", text: appendWriteSpawnError }],
+            content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
             isError: true,
             details: { mode: "management", results: [] },
         };
     }
-    const contextPolicy = resolveExplicitContextPolicy(input.params);
-    const chainSkillInput = normalizeSkillInput(input.params.skill);
+    const contextPolicy = resolveExplicitContextPolicy(appendParams);
+    const chainSkillInput = normalizeSkillInput(appendParams.skill);
     const chainSkills = chainSkillInput === false ? [] : (chainSkillInput ?? []);
     const asyncCtx = {
         pi: input.deps.pi,
@@ -612,13 +616,12 @@ function appendStepToAsyncChain(input) {
         parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
         currentModelProvider: input.ctx.model?.provider,
         currentModel: input.ctx.model,
-        modelScope: discoveredForAppend.modelScope,
+        modelScope: undefined,
     };
     const built = buildAsyncRunnerSteps(resolved.id, {
-        chain: wrapChainTasksForFork(input.params.chain, contextPolicy),
-        task: input.params.task,
+        chain: wrapChainTasksForFork(appendParams.chain, contextPolicy),
+        task: appendParams.task,
         resultMode: "chain",
-        agents,
         ctx: asyncCtx,
         availableModels: input.ctx.modelRegistry.getAvailable().map(toModelInfo),
         cwd: status.cwd ?? input.requestCwd,
@@ -627,6 +630,7 @@ function appendStepToAsyncChain(input) {
         maxSubagentDepth: resolveCurrentMaxSubagentDepth(input.deps.config.maxSubagentDepth),
         waitToolEnabled: input.deps.waitToolEnabled,
         asyncDir: resolved.location.asyncDir,
+        childIdRunId: appendChildRunId,
         validateOutputBindings: false,
     });
     if ("error" in built) {
@@ -947,38 +951,14 @@ async function resumeAsyncRun(input) {
     }
     input.deps.state.currentSessionId = resolveCurrentSessionId(input.ctx.sessionManager);
     const effectiveCwd = target.cwd ?? input.requestCwd;
-    const scope = resolveExecutionAgentScope(input.params.agentScope);
-    const discovered = input.deps.discoverAgents(effectiveCwd, scope);
-    const discoveredAgents = discovered.agents;
-    const modelScope = discovered.modelScope;
+    const modelScope = undefined;
     const sessionName = resolveIntercomSessionTarget(input.deps.pi.getSessionName(), input.ctx.sessionManager.getSessionId());
     const intercomBridge = resolveIntercomBridge({
         config: input.deps.config.intercomBridge,
         context: input.params.context,
         orchestratorTarget: sessionName,
     });
-    const agents = intercomBridge.active
-        ? discoveredAgents.map((agent) => applyIntercomBridgeToAgent(agent, intercomBridge))
-        : discoveredAgents;
     const recoveryDescriptor = "recoveryDescriptor" in target ? target.recoveryDescriptor : undefined;
-    const discoveredAgentConfig = agents.find((agent) => agent.name === target.agent);
-    const agentConfig = discoveredAgentConfig ?? (recoveryDescriptor ? {
-        name: recoveryDescriptor.agent,
-        description: "Persisted async recovery contract",
-        systemPrompt: "",
-        systemPromptMode: recoveryDescriptor.systemPromptMode,
-        inheritProjectContext: recoveryDescriptor.inheritProjectContext,
-        inheritSkills: recoveryDescriptor.inheritSkills,
-        source: "project",
-        filePath: recoveryDescriptor.agentFilePath ?? path.join(recoveryDescriptor.cwd, ".pi-subagents-recovery-agent"),
-    } : undefined);
-    if (!agentConfig) {
-        return {
-            content: [{ type: "text", text: `Unknown agent for resume: ${target.agent}` }],
-            isError: true,
-            details: { mode: "management", results: [] },
-        };
-    }
     if (attachChain) {
         if (target.source !== "async") {
             return {
@@ -1014,7 +994,6 @@ async function resumeAsyncRun(input) {
                 agent: target.agent,
                 label: `Attached ${target.runId}`,
             },
-            agents,
             ctx: {
                 pi: input.deps.pi,
                 cwd: input.requestCwd,
@@ -1056,15 +1035,35 @@ async function resumeAsyncRun(input) {
         return { content: [{ type: "text", text: formatAsyncStartedMessage(lines.join("\n")) }], details: result.details };
     }
     const runId = randomUUID().slice(0, 8);
-    const recoveryAgentConfig = recoveryDescriptor ? applySteeringRecoveryAgentConfig(agentConfig, recoveryDescriptor) : agentConfig;
     const artifactConfig = recoveryDescriptor?.artifactConfig ?? { ...DEFAULT_ARTIFACT_CONFIG, enabled: input.params.artifacts !== false };
     const artifactsDir = recoveryDescriptor?.artifactsDir ?? getArtifactsDir(parentSessionFile, effectiveCwd);
     const availableModels = input.ctx.modelRegistry.getAvailable().map(toModelInfo);
+    let recoverySpec;
+    try {
+        recoverySpec = normalizeChildSpec({
+            task: buildRevivedAsyncTask(target, followUp),
+            description: recoveryDescriptor?.description ?? target.description ?? target.agent,
+            permissions: recoveryDescriptor?.permissions ?? target.permissions ?? "read-only",
+            model: input.params.model ?? recoveryDescriptor?.model ?? target.model,
+            skill: recoveryDescriptor?.skills,
+            cwd: effectiveCwd,
+            output: recoveryDescriptor?.outputPath,
+            outputMode: recoveryDescriptor?.outputMode,
+            acceptance: input.params.acceptance ?? recoveryDescriptor?.acceptance,
+            toolBudget: recoveryDescriptor?.initialToolBudget,
+        }, {
+            parentMode: snapshotParentPermissionMode(input.deps.state.currentSessionId),
+            runId,
+            index: 0,
+            childId: recoveryDescriptor?.childId ?? target.childId ?? `${runId}-0`,
+        });
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
+    }
     const result = executeAsyncSingle(runId, {
-        agent: target.agent,
-        task: buildRevivedAsyncTask(target, followUp),
+        spec: recoverySpec,
         goal: followUp,
-        agentConfig: recoveryAgentConfig,
         ctx: {
             pi: input.deps.pi,
             cwd: input.requestCwd,
@@ -1200,13 +1199,13 @@ async function maybeBuildForegroundIntercomReceipt(input) {
         details: stripDetailsOutputsForIntercomReceipt(input.details),
     };
 }
-function validateExecutionInput(params, agents, hasChain, hasTasks, hasSingle, allowClarifyTaskPrompt) {
+function validateExecutionInput(params, hasChain, hasTasks, hasSingle, allowClarifyTaskPrompt) {
     if (Number(hasChain) + Number(hasTasks) + Number(hasSingle) !== 1) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `Provide exactly one mode. Agents: ${agents.map((a) => a.name).join(", ") || "none"}`,
+                    text: "Provide exactly one mode: { task, description, permissions? }, { tasks: [...] }, or { chain: [...] }.",
                 },
             ],
             isError: true,
@@ -1221,9 +1220,9 @@ function validateExecutionInput(params, agents, hasChain, hasTasks, hasSingle, a
             details: { mode: getRequestedModeLabel(params), results: [] },
         };
     }
-    if (hasSingle && params.agent && !agents.find((agent) => agent.name === params.agent)) {
+    if (hasSingle && !params.description) {
         return {
-            content: [{ type: "text", text: `Unknown agent: ${params.agent}` }],
+            content: [{ type: "text", text: "description is required and must be a concise single-line label (max 80 characters)." }],
             isError: true,
             details: { mode: "single", results: [] },
         };
@@ -1231,9 +1230,9 @@ function validateExecutionInput(params, agents, hasChain, hasTasks, hasSingle, a
     if (hasTasks && params.tasks) {
         for (let i = 0; i < params.tasks.length; i++) {
             const task = params.tasks[i];
-            if (!agents.find((agent) => agent.name === task.agent)) {
+            if (!task.description) {
                 return {
-                    content: [{ type: "text", text: `Unknown agent: ${task.agent} (task ${i + 1})` }],
+                    content: [{ type: "text", text: `description is required (task ${i + 1})` }],
                     isError: true,
                     details: { mode: "parallel", results: [] },
                 };
@@ -1275,11 +1274,18 @@ function validateExecutionInput(params, agents, hasChain, hasTasks, hasSingle, a
         }
         for (let i = 0; i < params.chain.length; i++) {
             const step = params.chain[i];
-            const stepAgents = getStepAgents(step);
-            for (const agentName of stepAgents) {
-                if (!agents.find((a) => a.name === agentName)) {
+            if (!isParallelStep(step) && !isDynamicParallelStep(step) && !step.description) {
+                return {
+                    content: [{ type: "text", text: `description is required (step ${i + 1})` }],
+                    isError: true,
+                    details: { mode: "chain", results: [] },
+                };
+            }
+            if (isParallelStep(step)) {
+                const missing = step.parallel.findIndex((t) => !t.description);
+                if (missing !== -1) {
                     return {
-                        content: [{ type: "text", text: `Unknown agent: ${agentName} (step ${i + 1})` }],
+                        content: [{ type: "text", text: `description is required (step ${i + 1}, parallel task ${missing + 1})` }],
                         isError: true,
                         details: { mode: "chain", results: [] },
                     };
@@ -1319,11 +1325,11 @@ function getRequestedModeLabel(params) {
         return "chain";
     if ((params.tasks?.length ?? 0) > 0)
         return "parallel";
-    if (params.agent)
+    if (params.task)
         return "single";
     return "single";
 }
-function resolveAgentDefaultContextPolicy(params, _agents) {
+function resolveAgentDefaultContextPolicy(params) {
     // lunr: hide fork from the model; force every child to fresh. Fork internals stay.
     return lunrContextPolicy(params);
 }
@@ -1331,23 +1337,6 @@ function resolveExplicitContextPolicy(params) {
     // lunr: `context: "fork"` from the model is coerced to fresh.
     return lunrContextPolicy(params);
 }
-function collectRequestedAgentNames(params) {
-    const names = [];
-    if (params.agent)
-        names.push(params.agent);
-    for (const task of params.tasks ?? [])
-        names.push(task.agent);
-    for (const step of params.chain ?? [])
-        names.push(...getStepAgents(step));
-    return names;
-}
-function collectRequestedAgents(params, agents) {
-    const byName = new Map(agents.map((agent) => [agent.name, agent]));
-    return collectRequestedAgentNames(params).map((name) => {
-        const agent = byName.get(name);
-        return { name, tools: agent?.tools };
-    });
-}
 function shouldForkAgent(contextPolicy, agentName) {
     return contextPolicy.contextForAgent(agentName) === "fork";
 }
@@ -1358,24 +1347,82 @@ function buildRequestedModeError(params, message) {
         details: { mode: getRequestedModeLabel(params), results: [] },
     }, params.context);
 }
-function applySingleAgentLaunchDefaults(params, agents) {
-    if ((params.chain?.length ?? 0) > 0 || (params.tasks?.length ?? 0) > 0 || !params.agent)
-        return params;
-    const agent = agents.find((candidate) => candidate.name === params.agent);
-    if (!agent)
-        return params;
+function runtimeConfigFromChildSpec(spec) {
     return {
-        ...params,
-        ...(params.async === undefined && agent.defaultAsync !== undefined ? { async: agent.defaultAsync } : {}),
-        ...(params.timeoutMs === undefined && params.maxRuntimeMs === undefined && agent.defaultTimeoutMs !== undefined
-            ? { timeoutMs: agent.defaultTimeoutMs }
-            : {}),
-        ...(params.turnBudget === undefined && agent.defaultTurnBudget !== undefined
-            ? { turnBudget: agent.defaultTurnBudget }
-            : {}),
-        ...(params.acceptance === undefined && agent.defaultAcceptance !== undefined
-            ? { acceptance: agent.defaultAcceptance }
-            : {}),
+        name: spec.childId,
+        description: spec.description,
+        model: spec.model,
+        thinking: undefined,
+        systemPromptMode: "append",
+        inheritProjectContext: true,
+        inheritSkills: false,
+        acceptanceRole: spec.effectivePermissions === "read-only" ? "read-only" : "writer",
+        systemPrompt: "",
+        skills: spec.skill === false ? [] : normalizeSkillInput(spec.skill) || undefined,
+        output: typeof spec.output === "string" ? spec.output : undefined,
+        toolBudget: spec.toolBudget,
+    };
+}
+function internalizePromptDrivenChildren(params, options) {
+    const agents = [];
+    let flatIndex = 0;
+    const normalize = (input, defaultTask) => {
+        const spec = normalizeChildSpec(input, {
+            parentMode: options.parentMode,
+            runId: options.runId,
+            index: flatIndex,
+            defaultTask,
+        });
+        agents.push(runtimeConfigFromChildSpec(spec));
+        return { input: { ...input, agent: spec.childId }, spec };
+    };
+    if ((params.tasks?.length ?? 0) > 0) {
+        const tasks = params.tasks.map((task) => {
+            const normalized = normalize(task);
+            flatIndex++;
+            return normalized.input;
+        });
+        return { params: { ...params, tasks }, agents };
+    }
+    if ((params.chain?.length ?? 0) > 0) {
+        const chain = params.chain.map((step) => {
+            if (isParallelStep(step)) {
+                const parallel = step.parallel.map((task) => {
+                    const normalized = normalize(task, flatIndex === 0 ? params.task : "{previous}");
+                    flatIndex++;
+                    return normalized.input;
+                });
+                return { ...step, parallel };
+            }
+            if (isDynamicParallelStep(step)) {
+                const normalized = normalize(step.parallel, "{previous}");
+                const reserved = step.expand.maxItems ?? options.dynamicFanoutMaxItems ?? 1;
+                flatIndex += Math.max(1, reserved);
+                return { ...step, parallel: normalized.input };
+            }
+            const normalized = normalize(step, flatIndex === 0 ? params.task : "{previous}");
+            flatIndex++;
+            return normalized.input;
+        });
+        return { params: { ...params, chain }, agents };
+    }
+    const normalized = normalize({
+        agent: params.agent,
+        task: params.task ?? "",
+        description: params.description,
+        permissions: params.permissions,
+        cwd: params.cwd,
+        model: params.model,
+        tier: params.tier,
+        skill: params.skill,
+        output: params.output,
+        outputMode: params.outputMode,
+        acceptance: params.acceptance,
+        toolBudget: params.toolBudget,
+    });
+    return {
+        params: { ...params, agent: normalized.spec.childId },
+        agents,
     };
 }
 function resolveForegroundTimeout(params) {
@@ -1720,7 +1767,6 @@ function runAsyncPath(data, deps) {
                 }],
             resultMode: "parallel",
             goal: params.tasks[0]?.task ?? "",
-            agents,
             ctx: asyncCtx,
             availableModels,
             cwd: effectiveCwd,
@@ -1757,7 +1803,6 @@ function runAsyncPath(data, deps) {
             chain,
             task: params.task,
             goal: resolveAsyncEventGoal(params.task, rawChain),
-            agents,
             ctx: asyncCtx,
             availableModels,
             cwd: effectiveCwd,
@@ -1803,11 +1848,27 @@ function runAsyncPath(data, deps) {
         const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, a.maxSubagentDepth);
         // lunr: model tiers — explicit model wins; otherwise resolve params.tier via the tier bridge.
         const modelOverride = resolveEffectiveSubagentModel(params.model ?? resolveTierModelOverride(params.tier), a.model, ctx.model, availableModels, currentProvider, { scope: data.modelScope });
-        return executeAsyncSingle(id, {
-            agent: params.agent,
+        const spec = normalizeChildSpec({
             task: shouldForkAgent(contextPolicy, params.agent) ? wrapForkTask(params.task ?? "") : (params.task ?? ""),
+            description: params.description,
+            permissions: params.permissions,
+            model: modelOverride,
+            tier: params.tier,
+            skill: params.skill,
+            cwd: effectiveCwd,
+            output: effectiveOutput,
+            outputMode: effectiveOutputMode,
+            acceptance: params.acceptance,
+            toolBudget: params.toolBudget,
+        }, {
+            parentMode: snapshotParentPermissionMode(deps.state.currentSessionId),
+            runId: id,
+            index: 0,
+            childId: params.agent,
+        });
+        return executeAsyncSingle(id, {
+            spec,
             goal: params.task ?? "",
-            agentConfig: a,
             ctx: asyncCtx,
             availableModels,
             cwd: effectiveCwd,
@@ -1916,7 +1977,6 @@ async function runChainPath(data, deps) {
             chain: asyncChain,
             task: params.task,
             goal: resolveAsyncEventGoal(params.task, rawAsyncChain, firstAgent ? shouldForkAgent(contextPolicy, firstAgent) : false),
-            agents,
             ctx: asyncCtx,
             availableModels: ctx.modelRegistry.getAvailable().map(toModelInfo),
             cwd: effectiveCwd,
@@ -2076,7 +2136,8 @@ async function runForegroundParallelTasks(input) {
         const taskText = injectSingleOutputInstruction(`${readInstructions.prefix}${input.taskTexts[index]}${progressInstructions.suffix}`, outputPath, agentConfig);
         const interruptController = new AbortController();
         if (input.foregroundControl) {
-            input.foregroundControl.currentAgent = task.agent;
+            input.foregroundControl.currentAgent = task.description || task.agent;
+            input.foregroundControl.currentChildId = task.agent;
             input.foregroundControl.currentIndex = index;
             input.foregroundControl.currentActivityState = undefined;
             input.foregroundControl.updatedAt = Date.now();
@@ -2089,7 +2150,18 @@ async function runForegroundParallelTasks(input) {
                 return true;
             };
         }
-        return runSync(input.ctx.cwd, input.agents, task.agent, taskText, {
+        return runSync(input.ctx.cwd, normalizeChildSpec({
+            task: taskText,
+            description: task.description,
+            permissions: task.permissions,
+            model: input.modelOverrides[index] ?? task.model,
+            skill: task.skill,
+            cwd: taskCwd,
+            output: task.output,
+            outputMode: task.outputMode,
+            acceptance: task.acceptance,
+            toolBudget: task.toolBudget,
+        }, { parentMode: snapshotParentPermissionMode(input.ctx.sessionManager.getSessionId() ?? undefined), runId: input.runId, index }), {
             parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
             cwd: taskCwd,
             signal: input.signal,
@@ -2132,7 +2204,8 @@ async function runForegroundParallelTasks(input) {
                     const stepProgress = progressUpdate.details?.progress || [];
                     if (input.foregroundControl && stepProgress.length > 0) {
                         const current = stepProgress[0];
-                        input.foregroundControl.currentAgent = task.agent;
+                        input.foregroundControl.currentAgent = task.description || task.agent;
+                        input.foregroundControl.currentChildId = task.agent;
                         input.foregroundControl.currentIndex = index;
                         input.foregroundControl.currentActivityState = current?.activityState;
                         input.foregroundControl.lastActivityAt = current?.lastActivityAt;
@@ -2227,7 +2300,7 @@ async function runParallelPath(data, deps) {
     // lunr: model tiers — explicit per-task model wins; otherwise resolve task.tier via the tier bridge.
     resolveEffectiveSubagentModel(behaviorOverrides[i]?.model ?? resolveTierModelOverride(task.tier), agentConfigs[i]?.model, ctx.model, availableModels, currentProvider, { scope: data.modelScope }));
     if (params.clarify === true && ctx.hasUI) {
-        const behaviors = agentConfigs.map((c, i) => resolveStepBehavior(c, behaviorOverrides[i]));
+        const behaviors = agentConfigs.map((_c, i) => resolveStepBehavior(behaviorOverrides[i]));
         const availableSkills = discoverAvailableSkills(effectiveCwd);
         const result = await ctx.ui.custom((tui, theme, _kb, done) => new ChainClarifyComponent(tui, theme, agentConfigs, taskTexts, "", undefined, behaviors, availableModels, currentProvider, availableSkills, done, "parallel"), { overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } });
         if (!result || !result.confirmed) {
@@ -2290,7 +2363,6 @@ async function runParallelPath(data, deps) {
                 chain: [{ parallel: parallelTasks, concurrency: parallelConcurrency, worktree: params.worktree }],
                 resultMode: "parallel",
                 goal: taskTexts[0] ?? "",
-                agents,
                 ctx: asyncCtx,
                 availableModels,
                 cwd: effectiveCwd,
@@ -2316,7 +2388,7 @@ async function runParallelPath(data, deps) {
             });
         }
     }
-    const behaviors = agentConfigs.map((config, index) => suppressProgressForReadOnlyTask(resolveStepBehavior(config, behaviorOverrides[index]), taskTexts[index]));
+    const behaviors = agentConfigs.map((_config, index) => suppressProgressForReadOnlyTask(resolveStepBehavior(behaviorOverrides[index]), taskTexts[index]));
     const firstProgressIndex = behaviors.findIndex((behavior) => behavior.progress);
     const liveResults = new Array(tasks.length).fill(undefined);
     const liveProgress = new Array(tasks.length).fill(undefined);
@@ -2478,18 +2550,45 @@ async function runParallelPath(data, deps) {
 async function runSinglePath(data, deps) {
     const { params, effectiveCwd, agents, ctx, signal, runId, sessionDirForIndex, sessionFileForTask, thinkingOverrideForTask, shareEnabled, artifactConfig, artifactsDir, onUpdate, sessionRoot, controlConfig, contextPolicy, } = data;
     const onControlEvent = createForegroundControlNotifier(data, deps);
-    const childIntercomTarget = data.intercomBridge.active ? resolveSubagentIntercomTarget(runId, params.agent, 0) : undefined;
-    const allProgress = [];
-    const allArtifactPaths = [];
-    const agentConfig = agents.find((a) => a.name === params.agent);
-    if (!agentConfig) {
+    let spec;
+    try {
+        spec = normalizeChildSpec({
+            task: params.task,
+            description: params.description,
+            permissions: params.permissions,
+            model: params.model,
+            tier: params.tier,
+            skill: params.skill,
+            cwd: effectiveCwd,
+            output: params.output,
+            outputMode: params.outputMode,
+            acceptance: params.acceptance,
+            toolBudget: params.toolBudget,
+        }, { parentMode: snapshotParentPermissionMode(deps.state.currentSessionId), runId, index: 0 });
+    }
+    catch (error) {
         return {
-            content: [{ type: "text", text: `Unknown agent: ${params.agent}` }],
+            content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
             isError: true,
             details: { mode: "single", results: [] },
         };
     }
-    const effectiveToolBudget = resolveEffectiveToolBudget({ runBudget: data.toolBudget, agentBudget: agentConfig.toolBudget, configBudget: data.configToolBudget });
+    const childIntercomTarget = data.intercomBridge.active ? resolveSubagentIntercomTarget(runId, spec.childId, 0) : undefined;
+    const allProgress = [];
+    const allArtifactPaths = [];
+    const agentConfig = {
+        name: spec.childId,
+        description: spec.description,
+        model: spec.model,
+        output: typeof spec.output === "string" ? spec.output : undefined,
+        toolBudget: spec.toolBudget,
+        skills: spec.skill === false ? [] : undefined,
+        systemPrompt: "",
+        systemPromptMode: "append",
+        inheritProjectContext: true,
+        inheritSkills: false,
+    };
+    const effectiveToolBudget = resolveEffectiveToolBudget({ runBudget: data.toolBudget, agentBudget: spec.toolBudget, configBudget: data.configToolBudget });
     if (effectiveToolBudget.error)
         return toExecutionErrorResult(params, new Error(effectiveToolBudget.error));
     const currentProvider = ctx.model?.provider;
@@ -2504,7 +2603,7 @@ async function runSinglePath(data, deps) {
     const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
     const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
     if (params.clarify === true && ctx.hasUI) {
-        const behavior = resolveStepBehavior(agentConfig, { output: effectiveOutput, skills: skillOverride });
+        const behavior = resolveStepBehavior({ output: effectiveOutput, skills: skillOverride });
         const availableSkills = discoverAvailableSkills(effectiveCwd);
         const result = await ctx.ui.custom((tui, theme, _kb, done) => new ChainClarifyComponent(tui, theme, [agentConfig], [task], task, undefined, [behavior], availableModels, currentProvider, availableSkills, done, "single"), { overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } });
         if (!result || !result.confirmed) {
@@ -2537,10 +2636,8 @@ async function runSinglePath(data, deps) {
                 modelScope: data.modelScope,
             };
             return executeAsyncSingle(id, {
-                agent: params.agent,
-                task: shouldForkAgent(contextPolicy, params.agent) ? wrapForkTask(task) : task,
+                spec: { ...spec, task: shouldForkAgent(contextPolicy, params.agent) ? wrapForkTask(task) : task },
                 goal: task,
-                agentConfig,
                 ctx: asyncCtx,
                 availableModels,
                 cwd: effectiveCwd,
@@ -2549,7 +2646,7 @@ async function runSinglePath(data, deps) {
                 artifactConfig,
                 shareEnabled,
                 sessionRoot,
-                sessionFile: sessionFileForTask(params.agent, 0, modelOverride),
+                sessionFile: sessionFileForTask(spec.childId, 0, modelOverride),
                 skills: skillOverride === false ? [] : skillOverride,
                 output: effectiveOutput,
                 outputMode: effectiveOutputMode,
@@ -2590,7 +2687,8 @@ async function runSinglePath(data, deps) {
     const interruptController = new AbortController();
     const foregroundControl = deps.state.foregroundControls.get(runId);
     if (foregroundControl) {
-        foregroundControl.currentAgent = params.agent;
+        foregroundControl.currentAgent = params.description || params.agent;
+        foregroundControl.currentChildId = params.agent;
         foregroundControl.currentIndex = 0;
         foregroundControl.currentActivityState = undefined;
         foregroundControl.updatedAt = Date.now();
@@ -2607,7 +2705,8 @@ async function runSinglePath(data, deps) {
         ? (update) => {
             if (foregroundControl) {
                 const firstProgress = update.details?.progress?.[0];
-                foregroundControl.currentAgent = params.agent;
+                foregroundControl.currentAgent = params.description || params.agent;
+                foregroundControl.currentChildId = params.agent;
                 foregroundControl.currentIndex = firstProgress?.index ?? 0;
                 foregroundControl.currentActivityState = firstProgress?.activityState;
                 foregroundControl.lastActivityAt = firstProgress?.lastActivityAt;
@@ -2623,16 +2722,16 @@ async function runSinglePath(data, deps) {
         }
         : undefined;
     const deadlineAt = data.deadlineAt ?? (data.timeoutMs !== undefined ? Date.now() + data.timeoutMs : undefined);
-    const r = await runSync(ctx.cwd, agents, params.agent, task, {
+    const r = await runSync(ctx.cwd, { ...spec, task }, {
         parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
         cwd: effectiveCwd,
         signal,
         interruptSignal: interruptController.signal,
-        allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
+        allowIntercomDetach: data.intercomBridge.active,
         intercomEvents: deps.pi.events,
         runId,
         sessionDir: sessionDirForIndex(0),
-        sessionFile: sessionFileForTask(params.agent, 0, modelOverride),
+        sessionFile: sessionFileForTask(spec.childId, 0, modelOverride),
         share: shareEnabled,
         artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
         artifactConfig,
@@ -2760,7 +2859,7 @@ function foregroundCapacityResult(params, inFlight, limit) {
     return {
         content: [{
                 type: "text",
-                text: `Foreground subagent capacity reached (${inFlight}/${limit} running). Wait for a child to finish, use ONE subagent call with tasks: [{agent, task}, …], or set async: true.`,
+                text: `Foreground subagent capacity reached (${inFlight}/${limit} running). Wait for a child to finish, use ONE subagent call with tasks: [{task, description}, …], or set async: true.`,
             }],
         isError: true,
         details: { mode: inferExecutionMode(params), results: [] },
@@ -2768,7 +2867,7 @@ function foregroundCapacityResult(params, inFlight, limit) {
 }
 function omitExecutionModeActionAlias(params) {
     const action = params.action?.toLowerCase();
-    if (action === "single" && (params.agent !== undefined || params.task !== undefined)) {
+    if (action === "single" && params.task !== undefined) {
         const rest = { ...params };
         delete rest.action;
         return rest;
@@ -3007,25 +3106,13 @@ export function createSubagentExecutor(deps) {
                     details: { mode: "management", results: [] },
                 };
             }
-            if (!SUBAGENT_ACTIONS.includes(action)) {
-                return {
-                    content: [{ type: "text", text: `Unknown action: ${action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}` }],
-                    isError: true,
-                    details: { mode: "management", results: [] },
-                };
-            }
-            if (deps.allowMutatingManagementActions === false && MUTATING_MANAGEMENT_ACTIONS.has(action)) {
-                return {
-                    content: [{ type: "text", text: `Action '${action}' is not available from child-safe subagent fanout mode.` }],
-                    isError: true,
-                    details: { mode: "management", results: [] },
-                };
-            }
-            return handleManagementAction(action, paramsWithResolvedCwd, {
-                ...ctx,
-                cwd: requestCwd,
-                config: deps.config,
-            });
+            // Every supported control action returns above. Named-agent CRUD actions are
+            // intentionally absent from SUBAGENT_ACTIONS and have no fallback handler.
+            return {
+                content: [{ type: "text", text: `Unknown action: ${action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}` }],
+                isError: true,
+                details: { mode: "management", results: [] },
+            };
         }
         const { blocked, depth, maxDepth } = checkSubagentDepth(deps.config.maxSubagentDepth);
         if (blocked) {
@@ -3053,21 +3140,32 @@ export function createSubagentExecutor(deps) {
         const configToolBudget = resolveToolBudget(deps.config.toolBudget, "config.toolBudget");
         if (configToolBudget.error)
             return buildRequestedModeError(effectiveParams, configToolBudget.error);
-        const scope = resolveExecutionAgentScope(effectiveParams.agentScope);
         const effectiveCwd = effectiveParams.cwd ?? ctx.cwd;
         const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
         deps.state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
-        const discovered = deps.discoverAgents(effectiveCwd, scope);
-        const discoveredAgents = discovered.agents;
-        const modelScope = discovered.modelScope;
-        effectiveParams = applySingleAgentLaunchDefaults(effectiveParams, discoveredAgents);
+        const runId = randomUUID().slice(0, 8);
+        const parentPermissionMode = snapshotParentPermissionMode(deps.state.currentSessionId);
+        let internalized;
+        try {
+            internalized = internalizePromptDrivenChildren(effectiveParams, {
+                runId,
+                parentMode: parentPermissionMode,
+                dynamicFanoutMaxItems: deps.config.chain?.dynamicFanout?.maxItems,
+            });
+        }
+        catch (error) {
+            return buildRequestedModeError(effectiveParams, error instanceof Error ? error.message : String(error));
+        }
+        effectiveParams = internalized.params;
+        const discoveredAgents = internalized.agents;
+        const modelScope = undefined;
         const foregroundTimeout = resolveForegroundTimeout(effectiveParams);
         if (foregroundTimeout.error)
             return buildRequestedModeError(effectiveParams, foregroundTimeout.error);
         const turnBudget = resolveTurnBudgetConfig(effectiveParams.turnBudget ?? deps.config.turnBudget);
         if (turnBudget.error)
             return buildRequestedModeError(effectiveParams, turnBudget.error);
-        const contextPolicy = resolveAgentDefaultContextPolicy(effectiveParams, discoveredAgents);
+        const contextPolicy = resolveAgentDefaultContextPolicy(effectiveParams);
         effectiveParams = contextPolicy.params;
         const sessionName = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
         const intercomBridge = resolveIntercomBridge({
@@ -3078,25 +3176,20 @@ export function createSubagentExecutor(deps) {
         const agents = intercomBridge.active
             ? discoveredAgents.map((agent) => applyIntercomBridgeToAgent(agent, intercomBridge))
             : discoveredAgents;
-        const runId = randomUUID().slice(0, 8);
         const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
         const nestedParentAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
         const nestedRoute = inheritedNestedRoute ?? createNestedRoute(runId);
         const shareEnabled = effectiveParams.share === true;
         const hasChain = (effectiveParams.chain?.length ?? 0) > 0;
         const hasTasks = (effectiveParams.tasks?.length ?? 0) > 0;
-        const hasSingle = !hasChain && !hasTasks && Boolean(effectiveParams.agent);
+        const hasSingle = !hasChain && !hasTasks && Boolean(effectiveParams.task);
         const allowClarifyTaskPrompt = hasChain
             && effectiveParams.clarify === true
             && ctx.hasUI
             && !(effectiveParams.chain?.some(isParallelStep) ?? false);
-        const validationError = validateExecutionInput(effectiveParams, agents, hasChain, hasTasks, hasSingle, allowClarifyTaskPrompt);
+        const validationError = validateExecutionInput(effectiveParams, hasChain, hasTasks, hasSingle, allowClarifyTaskPrompt);
         if (validationError)
             return validationError;
-        const parentPermissionMode = snapshotParentPermissionMode(deps.state.currentSessionId);
-        const writeSpawnError = planModeWriteSpawnError(parentPermissionMode, collectRequestedAgents(effectiveParams, agents));
-        if (writeSpawnError)
-            return buildRequestedModeError(effectiveParams, writeSpawnError);
         let forkSessionFileForIndex = () => undefined;
         let forkThinkingOverrideForIndex = () => undefined;
         let prepareForkThinking = (_agentName, _index, _modelOverride) => { };
@@ -3225,6 +3318,7 @@ export function createSubagentExecutor(deps) {
                 startedAt: Date.now(),
                 updatedAt: Date.now(),
                 currentAgent: undefined,
+                currentChildId: undefined,
                 currentIndex: undefined,
                 currentActivityState: undefined,
                 nestedRoute,
@@ -3249,13 +3343,20 @@ export function createSubagentExecutor(deps) {
             const errorText = result?.isError
                 ? result.content.find((item) => item.type === "text")?.text
                 : undefined;
-            const agentsForSummary = hasTasks && effectiveParams.tasks
+            const internalChildKeys = hasTasks && effectiveParams.tasks
                 ? effectiveParams.tasks.map((task) => task.agent)
                 : hasChain && effectiveParams.chain
-                    ? effectiveParams.chain.flatMap((step) => isParallelStep(step) ? step.parallel.map((task) => task.agent) : [step.agent])
+                    ? effectiveParams.chain.flatMap((step) => isParallelStep(step)
+                        ? step.parallel.map((task) => task.agent)
+                        : isDynamicParallelStep(step) ? [step.parallel.agent] : [step.agent])
                     : effectiveParams.agent ? [effectiveParams.agent] : [];
-            const leafIntercomTarget = intercomBridge.active && agentsForSummary[0]
-                ? resolveSubagentIntercomTarget(runId, agentsForSummary[0], 0)
+            const childrenForSummary = hasTasks && effectiveParams.tasks
+                ? effectiveParams.tasks.map((task) => task.description || task.agent || "child")
+                : hasChain && effectiveParams.chain
+                    ? effectiveParams.chain.flatMap(getStepAgents)
+                    : [effectiveParams.description || effectiveParams.agent || "child"];
+            const leafIntercomTarget = intercomBridge.active && internalChildKeys[0]
+                ? resolveSubagentIntercomTarget(runId, internalChildKeys[0], 0)
                 : undefined;
             try {
                 writeNestedEvent(inheritedNestedRoute, {
@@ -3275,8 +3376,8 @@ export function createSubagentExecutor(deps) {
                         ownerState: state === "running" ? "live" : "gone",
                         mode: foregroundMode,
                         state,
-                        agent: agentsForSummary[0],
-                        agents: agentsForSummary,
+                        agent: childrenForSummary[0],
+                        agents: childrenForSummary,
                         startedAt: foregroundControl?.startedAt ?? now,
                         ...(state !== "running" ? { endedAt: now } : {}),
                         lastUpdate: now,