@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/dist/runs/foreground/subagent-executor.js

@@ -0,0 +1,442 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveExecutionAgentScope } from "../../agents/agent-scope.js";
+import { handleManagementAction } from "../../agents/agent-management.js";
+import { buildDoctorReport } from "../../extension/doctor.js";
+import { providerQualifiedModelId, toModelInfo } from "../../shared/model-info.js";
+import { resolveModelCandidate } from "../shared/model-fallback.js";
+import { getArtifactsDir } from "../../shared/artifacts.js";
+import { collectInvocationAgentNames, isParallelStep, isDynamicParallelStep, } from "../../shared/settings.js";
+import { buildFlatAgentNameResolver, createPerAgentForkContextResolver, invocationUsesForkContext, resolveAgentContext, validateForkContextModelPolicy, } from "../../shared/agent-context-policy.js";
+import { resolveCurrentSessionId } from "../../shared/session-identity.js";
+import { resolveExecutionCwd } from "../../shared/execution-cwd.js";
+import { resolveIntercomBridge, resolveIntercomSessionTarget, resolveOrchestratorIntercomTarget } from "../../intercom/intercom-bridge.js";
+import { resolveControlConfig } from "../shared/subagent-control.js";
+import { createNestedRoute, resolveInheritedNestedRouteFromEnv } from "../shared/nested-events.js";
+import { resolveSubagentRunId } from "../background/run-id-resolver.js";
+import { inspectSubagentStatus } from "../background/run-status.js";
+import { applyForceTopLevelAsyncOverride } from "../background/top-level-async.js";
+import { queryLiveIntercomHealth, queryLiveIntercomStatus } from "../../intercom/live-intercom.js";
+import { saveQuestionOwner } from "../shared/supervisor-questions.js";
+import { buildWorkflowGraphSnapshot, workflowAgentNodes } from "../shared/workflow-graph.js";
+import { ownedRunList, ownedRunStatusResult, ownedRunView, rememberOwnedRun, resolveOwnedRun, workflowChildren } from "../shared/run-records.js";
+import { ownedHistoryQuery } from "../shared/run-history-queries.js";
+import { cancelSupervisorInput, controlSupervisorQuestion, projectSupervisorQuestions } from "./question-control.js";
+import {} from "../../agents/agents.js";
+import { SUBAGENT_ACTIONS, checkSubagentDepth, } from "../../shared/types.js";
+import { resolveAsyncExecutionMode, } from "./subagent-params.js";
+import { MUTATING_MANAGEMENT_ACTIONS, extendAsyncTimeoutResult, interruptAsyncRun, interruptNestedRun, nestedResolutionScopeForExecutor, nudgeSubagentRun, rememberedForegroundStatusResult, resolveRememberedForegroundRun, resolveRequestedCwd, resumeAsyncRun, } from "./foreground-control.js";
+import { buildRequestedModeError, normalizeRepeatedParallelCounts, normalizeRoleForegroundTimeout, resolveForegroundTimeoutMs, toExecutionErrorResult, validateExecutionInput, withForkContext, } from "./execution-input.js";
+import { runAsyncPath } from "./run-async-path.js";
+import { clarifyInvocation } from "./clarify-invocation.js";
+import { waitForOwnedRun } from "./wait-run.js";
+export { normalizeSubagentParamsLike, resolveAsyncExecutionMode } from "./subagent-params.js";
+export { writeAsyncInterruptRequest } from "./foreground-control.js";
+export function createSubagentExecutor(deps) {
+    const execute = async (_id, params, signal, onUpdate, ctx, executionCwd) => {
+        const needsExecutionCwd = !params.action || params.cwd !== undefined || ["list", "get", "create", "update", "delete", "doctor"].includes(params.action);
+        const invocationCwd = needsExecutionCwd ? executionCwd ?? resolveExecutionCwd(deps.pi, ctx) : ctx.cwd;
+        await deps.ensureSessionState?.(ctx);
+        if (needsExecutionCwd)
+            deps.state.baseCwd = invocationCwd;
+        deps.state.foregroundRuns ??= new Map();
+        const requestCwd = resolveRequestedCwd(invocationCwd, params.cwd);
+        const paramsWithResolvedCwd = params.cwd === undefined ? params : { ...params, cwd: requestCwd };
+        if (params.action) {
+            if (params.action === "review") {
+                try {
+                    if (!(params.id ?? params.runId) || (params.decision !== "accepted" && params.decision !== "needs_changes"))
+                        throw new Error("action='review' requires id and decision ('accepted' or 'needs_changes').");
+                    const run = resolveOwnedRun(deps.state, (params.id ?? params.runId));
+                    if (!run)
+                        throw new Error("Run not found in this parent session.");
+                    if (ownedRunView(run, deps.state).state === "live")
+                        throw new Error("The run is still live. Use nudge for guidance, or stop it before reviewing its result.");
+                    const reviewed = { ...run, review: { decision: params.decision, ...(params.message ? { message: params.message } : {}), reviewedAt: Date.now() } };
+                    rememberOwnedRun(deps.state, reviewed);
+                    const result = ownedRunStatusResult(reviewed, deps.state, undefined, { childSafe: Boolean(nestedResolutionScopeForExecutor(deps)) });
+                    return { ...result, content: [{ type: "text", text: `Saved parent review for ${run.runId}: ${params.decision}.\nThe review note is parent-only and was not sent to the child. Put actionable instructions in ${deps.allowMutatingManagementActions === false && deps.config.compactChildTools === false ? "subagent resume/nudge" : "agent_runs continue/nudge"}. No work started.` }] };
+                }
+                catch (error) {
+                    return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
+                }
+            }
+            if (params.action === "history" || params.action === "search") {
+                try {
+                    return await ownedHistoryQuery(deps.state, params, signal);
+                }
+                catch (error) {
+                    return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
+                }
+            }
+            if (params.action === "questions" || params.action === "answer") {
+                return controlSupervisorQuestion({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
+            }
+            if (params.action === "doctor") {
+                let currentSessionFile = null;
+                let currentSessionId = deps.state.currentSessionId;
+                let sessionError;
+                try {
+                    currentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+                    currentSessionId = ctx.sessionManager.getSessionId();
+                }
+                catch (error) {
+                    sessionError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+                }
+                let orchestratorTarget;
+                try {
+                    const fallbackTarget = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
+                    orchestratorTarget = resolveOrchestratorIntercomTarget(deps.pi.events, fallbackTarget);
+                }
+                catch { }
+                const { connection } = await queryLiveIntercomStatus(deps.pi.events);
+                return {
+                    content: [{
+                            type: "text",
+                            text: buildDoctorReport({
+                                cwd: requestCwd,
+                                nativeSessionCwd: ctx.cwd,
+                                config: deps.config,
+                                state: deps.state,
+                                requestedSessionDir: paramsWithResolvedCwd.sessionDir,
+                                currentSessionFile,
+                                currentSessionId,
+                                orchestratorTarget,
+                                connection,
+                                sessionError,
+                                projectTrusted: ctx.isProjectTrusted(),
+                                expandTilde: deps.expandTilde,
+                            }),
+                        }],
+                    details: { mode: "management", results: [] },
+                };
+            }
+            if (params.action === "status") {
+                const targetRunId = paramsWithResolvedCwd.id ?? paramsWithResolvedCwd.runId;
+                if (!targetRunId && !params.dir && deps.state.ownedRuns && deps.allowMutatingManagementActions !== false) {
+                    try {
+                        return await ownedRunList(deps.state, { ...params, signal });
+                    }
+                    catch (error) {
+                        return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
+                    }
+                }
+                let includeRunHeader = true;
+                if (targetRunId) {
+                    try {
+                        includeRunHeader = Boolean(params.dir) || !resolveOwnedRun(deps.state, targetRunId);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+                    }
+                }
+                let inspected = inspectSubagentStatus({ ...paramsWithResolvedCwd, action: "status" }, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps), includeRunHeader });
+                const targets = inspected.details.intercomTargets ?? [];
+                if (!inspected.isError && targets.length) {
+                    const intercomHealth = await queryLiveIntercomHealth(deps.pi.events, targets);
+                    if (intercomHealth.size)
+                        inspected = inspectSubagentStatus({ ...paramsWithResolvedCwd, action: "status" }, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps), intercomHealth, includeRunHeader });
+                }
+                if (targetRunId && inspected.isError && inspected.content[0]?.type === "text" && inspected.content[0].text.startsWith("Async run not found.")) {
+                    try {
+                        const remembered = resolveRememberedForegroundRun(targetRunId, deps.state);
+                        if (remembered)
+                            return rememberedForegroundStatusResult(remembered, Boolean(nestedResolutionScopeForExecutor(deps)));
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+                    }
+                }
+                if (!targetRunId && !params.dir && deps.allowMutatingManagementActions !== false) {
+                    const foreground = [...(deps.state.foregroundRuns?.values() ?? [])]
+                        .sort((a, b) => b.updatedAt - a.updatedAt)
+                        .map((run) => rememberedForegroundStatusResult(run));
+                    if (foreground.length) {
+                        inspected = {
+                            ...inspected,
+                            content: [...foreground.flatMap((result) => result.content), ...inspected.content],
+                            details: {
+                                ...inspected.details,
+                                managementControls: [...foreground.flatMap((result) => result.details.managementControl ? [result.details.managementControl] : []), ...(inspected.details.managementControls ?? [])],
+                            },
+                        };
+                    }
+                }
+                return inspected;
+            }
+            if (params.action === "nudge") {
+                return nudgeSubagentRun({ params: paramsWithResolvedCwd, deps, ctx });
+            }
+            if (params.action === "resume") {
+                return resumeAsyncRun({ params: paramsWithResolvedCwd, requestCwd, ctx, deps });
+            }
+            if (params.action === "extend") {
+                const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+                let resolved;
+                if (targetRunId) {
+                    try {
+                        resolved = resolveSubagentRunId(targetRunId, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps) });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+                    }
+                }
+                return extendAsyncTimeoutResult(deps.state, resolved?.id ?? targetRunId, paramsWithResolvedCwd.extendMs ?? paramsWithResolvedCwd.timeoutMs ?? paramsWithResolvedCwd.maxRuntimeMs ?? 0);
+            }
+            if (params.action === "interrupt") {
+                const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+                let resolved;
+                if (targetRunId) {
+                    try {
+                        resolved = resolveSubagentRunId(targetRunId, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps) });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+                    }
+                }
+                if (resolved?.kind === "nested")
+                    return interruptNestedRun(resolved, paramsWithResolvedCwd.index);
+                const asyncInterruptResult = interruptAsyncRun(deps.state, resolved?.kind === "async" ? resolved.id : targetRunId, paramsWithResolvedCwd.index);
+                if (asyncInterruptResult)
+                    return asyncInterruptResult;
+                return {
+                    content: [{ type: "text", text: "No interrupt-capable run found in this session." }],
+                    isError: true,
+                    details: { mode: "management", results: [] },
+                };
+            }
+            if (!SUBAGENT_ACTIONS.includes(params.action)) {
+                return {
+                    content: [{ type: "text", text: `Unknown action: ${params.action}. Valid: ${SUBAGENT_ACTIONS.join(", ")}` }],
+                    isError: true,
+                    details: { mode: "management", results: [] },
+                };
+            }
+            if (deps.allowMutatingManagementActions === false && MUTATING_MANAGEMENT_ACTIONS.has(params.action)) {
+                return {
+                    content: [{ type: "text", text: `Action '${params.action}' is not available from child-safe subagent fanout mode.` }],
+                    isError: true,
+                    details: { mode: "management", results: [] },
+                };
+            }
+            return handleManagementAction(params.action, paramsWithResolvedCwd, { ...ctx, cwd: requestCwd });
+        }
+        const { blocked, depth, maxDepth } = checkSubagentDepth(deps.config.maxSubagentDepth);
+        if (blocked) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Nested subagent call blocked (depth=${depth}, max=${maxDepth}). ` +
+                            "You are running at the maximum subagent nesting depth. " +
+                            "Complete your current task directly without delegating to further subagents.",
+                    },
+                ],
+                isError: true,
+                details: { mode: "single", results: [] },
+            };
+        }
+        const normalized = normalizeRepeatedParallelCounts(paramsWithResolvedCwd);
+        if (normalized.error)
+            return normalized.error;
+        const normalizedParams = normalized.params;
+        let effectiveParams = applyForceTopLevelAsyncOverride(normalizedParams, depth, deps.config.forceTopLevelAsync === true);
+        const scope = resolveExecutionAgentScope(effectiveParams.agentScope);
+        const effectiveCwd = effectiveParams.cwd ?? invocationCwd;
+        const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+        deps.state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+        const inheritedModel = providerQualifiedModelId(ctx.model?.provider, ctx.model?.id);
+        const discoveredAgents = deps.discoverAgents(effectiveCwd, scope, { projectTrusted: ctx.isProjectTrusted() }).agents
+            .map((agent) => agent.model || !inheritedModel ? agent : { ...agent, model: inheritedModel });
+        const invocationAgentNames = collectInvocationAgentNames(effectiveParams);
+        const invocationContext = invocationUsesForkContext(effectiveParams.context, invocationAgentNames, discoveredAgents)
+            ? "fork"
+            : undefined;
+        const fallbackTarget = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
+        const orchestratorTarget = resolveOrchestratorIntercomTarget(deps.pi.events, fallbackTarget);
+        const intercomBridge = resolveIntercomBridge(orchestratorTarget);
+        const runId = randomUUID();
+        const agentNameAtIndex = buildFlatAgentNameResolver(effectiveParams);
+        const resolveContextForAgent = (agentName) => resolveAgentContext(effectiveParams.context, agentName, discoveredAgents);
+        const resolveContextForIndex = (index) => resolveContextForAgent(agentNameAtIndex(index ?? 0));
+        const agents = discoveredAgents.map((agent) => ({ ...agent, defaultContext: resolveContextForAgent(agent.name) }));
+        const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
+        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 allowClarifyTaskPrompt = hasChain
+            && effectiveParams.clarify === true
+            && ctx.hasUI
+            && !(effectiveParams.chain?.some(isParallelStep) ?? false);
+        const validationError = validateExecutionInput(effectiveParams, agents, hasChain, hasTasks, hasSingle, allowClarifyTaskPrompt);
+        if (validationError)
+            return validationError;
+        if (invocationContext === "fork") {
+            let availableModels;
+            try {
+                availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
+            }
+            catch (error) {
+                return toExecutionErrorResult(effectiveParams, error, invocationContext);
+            }
+            const forkModelPolicyError = validateForkContextModelPolicy(effectiveParams, discoveredAgents, (model) => resolveModelCandidate(model, availableModels, ctx.model?.provider));
+            if (forkModelPolicyError) {
+                return toExecutionErrorResult(effectiveParams, new Error(forkModelPolicyError), invocationContext);
+            }
+        }
+        try {
+            const clarified = await clarifyInvocation({ params: effectiveParams, agents, ctx, cwd: effectiveCwd, runId });
+            if (!clarified)
+                return { content: [{ type: "text", text: "Cancelled" }], details: { mode: hasChain ? "chain" : hasTasks ? "parallel" : "single", results: [] } };
+            effectiveParams = clarified;
+        }
+        catch (error) {
+            return toExecutionErrorResult(effectiveParams, error, invocationContext);
+        }
+        if (signal?.aborted)
+            return toExecutionErrorResult(effectiveParams, new Error("Subagent cancelled before launch."), invocationContext);
+        let sessionFileForIndex = () => undefined;
+        let forkSessionFileForAgentIndex = () => undefined;
+        try {
+            const forkContextResolver = createPerAgentForkContextResolver(ctx.sessionManager, resolveContextForIndex, {
+                resolveContextForAgentIndex: (agentName) => resolveContextForAgent(agentName),
+            });
+            sessionFileForIndex = forkContextResolver.sessionFileForIndex;
+            forkSessionFileForAgentIndex = forkContextResolver.sessionFileForAgentIndex;
+        }
+        catch (error) {
+            return toExecutionErrorResult(effectiveParams, error, invocationContext);
+        }
+        const asyncMode = resolveAsyncExecutionMode(effectiveParams, deps.asyncByDefault);
+        const backgroundRequestedWhileClarifying = (hasChain || hasTasks) && asyncMode.backgroundRequestedWhileClarifying;
+        const effectiveAsync = asyncMode.effectiveAsync;
+        const foregroundTimeout = resolveForegroundTimeoutMs(effectiveParams);
+        if (foregroundTimeout.error)
+            return buildRequestedModeError(effectiveParams, foregroundTimeout.error);
+        if (effectiveAsync && foregroundTimeout.timeoutMs !== undefined) {
+            return buildRequestedModeError(effectiveParams, "timeoutMs/maxRuntimeMs only applies to foreground subagent runs. Set async:false or use action:'interrupt' for background runs.");
+        }
+        if (!effectiveAsync)
+            foregroundTimeout.timeoutMs = normalizeRoleForegroundTimeout(effectiveParams, foregroundTimeout.timeoutMs);
+        const controlConfig = resolveControlConfig(deps.config.control, effectiveParams.control);
+        const artifactsEnabled = effectiveParams.artifacts !== false;
+        const artifactsDir = effectiveAsync ? deps.tempArtifactsDir : getArtifactsDir(parentSessionFile);
+        let sessionRoot;
+        if (effectiveParams.sessionDir) {
+            sessionRoot = path.resolve(deps.expandTilde(effectiveParams.sessionDir));
+        }
+        else {
+            const baseSessionRoot = deps.config.defaultSessionDir
+                ? path.resolve(deps.expandTilde(deps.config.defaultSessionDir))
+                : deps.getSubagentSessionRoot(parentSessionFile);
+            sessionRoot = path.join(baseSessionRoot, runId);
+        }
+        try {
+            fs.mkdirSync(sessionRoot, { recursive: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toExecutionErrorResult(effectiveParams, new Error(`Failed to create session directory '${sessionRoot}': ${message}`), invocationContext);
+        }
+        const sessionDirForIndex = (idx) => path.join(sessionRoot, `run-${idx ?? 0}`);
+        const childSessionFileForIndex = (idx) => sessionFileForIndex(idx) ?? path.join(sessionDirForIndex(idx), "session.jsonl");
+        const childSessionFileForAgentIndex = (agentName, idx) => forkSessionFileForAgentIndex(agentName, idx) ?? path.join(sessionDirForIndex(idx), "session.jsonl");
+        const workflowGraph = effectiveParams.chain ? buildWorkflowGraphSnapshot({ runId, steps: effectiveParams.chain }) : undefined;
+        const assignmentNodes = workflowGraph && workflowAgentNodes(workflowGraph);
+        const onUpdateWithContext = (r) => {
+            const owned = deps.state.ownedRuns?.get(runId);
+            if (owned && r.details.workflowGraph)
+                rememberOwnedRun(deps.state, { ...owned, children: workflowChildren(owned.children, r.details.workflowGraph) });
+            onUpdate?.(withForkContext(r, invocationContext));
+        };
+        const assignments = effectiveParams.tasks ?? effectiveParams.chain?.flatMap((step) => isParallelStep(step) ? step.parallel : isDynamicParallelStep(step) ? [step.parallel] : [step])
+            ?? [{ agent: effectiveParams.agent, task: effectiveParams.task, label: effectiveParams.label }];
+        saveQuestionOwner(runId, ctx.sessionManager.getSessionId());
+        const execData = {
+            params: effectiveParams,
+            effectiveCwd,
+            ctx,
+            signal,
+            onUpdate: onUpdateWithContext,
+            agents,
+            runId,
+            shareEnabled,
+            sessionRoot,
+            sessionDirForIndex,
+            sessionFileForIndex: childSessionFileForIndex,
+            sessionFileForAgentIndex: childSessionFileForAgentIndex,
+            artifactsEnabled,
+            artifactsDir,
+            backgroundRequestedWhileClarifying,
+            effectiveAsync,
+            ...(foregroundTimeout.timeoutMs !== undefined ? { foregroundTimeoutMs: foregroundTimeout.timeoutMs } : {}),
+            controlConfig,
+            intercomBridge,
+            nestedRoute,
+        };
+        try {
+            const result = runAsyncPath(execData, deps);
+            if (!result)
+                throw new Error("Invalid subagent execution mode.");
+            if (result.isError)
+                return withForkContext(result, invocationContext);
+            rememberOwnedRun(deps.state, {
+                runId, ownerSessionId: ctx.sessionManager.getSessionId(), rootRunId: runId,
+                source: "async", mode: hasChain ? "chain" : hasTasks ? "parallel" : "single",
+                cwd: effectiveCwd, task: effectiveParams.task ?? effectiveParams.tasks?.map((task) => task.task).join("\n") ?? "Delegated workflow",
+                asyncDir: result.details.asyncDir, pid: result.details.asyncPid ?? deps.state.asyncJobs.get(runId)?.pid,
+                startedAt: Date.now(), children: assignments.map(({ agent, task, label }, index) => ({ agent, index, task, label, ...(assignmentNodes?.[index] ? { workflowNodeId: assignmentNodes[index].id } : {}) })),
+            });
+            if (!effectiveAsync && result.details.asyncId) {
+                return withForkContext(await waitForOwnedRun({ id: runId, deps, ctx, signal, onUpdate: onUpdateWithContext,
+                    cancelNewRun: !effectiveAsync, executionResult: true, includeProgress: effectiveParams.includeProgress }), invocationContext);
+            }
+            return withForkContext(result, invocationContext);
+        }
+        catch (error) {
+            const result = toExecutionErrorResult(effectiveParams, error, invocationContext);
+            const owned = deps.state.ownedRuns?.get(runId);
+            if (owned)
+                rememberOwnedRun(deps.state, { ...owned, error: result.content.filter((part) => part.type === "text").map((part) => part.text).join("\n") });
+            return result;
+        }
+    };
+    return { execute: async (...args) => {
+            const [id, params, signal, onUpdate, ctx, executionCwd] = args;
+            const waiting = params.async === false && (params.action === "resume" || params.action === "answer");
+            const before = waiting ? new Set(deps.state.ownedRuns?.keys()) : undefined;
+            let result = await execute(id, params, signal, onUpdate, ctx, executionCwd);
+            // Launch/answer receipts and claims are saved before waiting; execution failure must not undo a successful launch.
+            if (waiting && !result.isError) {
+                const question = result.details.questions?.find((question) => question.delivery || question.state === "answer_pending");
+                const id = result.details.asyncId ?? result.details.managementControl?.runId ?? question?.delivery?.runId ?? question?.runId ?? params.id ?? params.runId;
+                const index = result.details.asyncId || question?.delivery?.kind === "revive" ? 0
+                    : result.details.managementControl?.nextActions.find((action) => action.index !== undefined)?.index ?? question?.index ?? params.index;
+                if (id)
+                    return waitForOwnedRun({ id, index, deps, ctx, signal, onUpdate, cancelNewRun: params.async === false && !before?.has(id) && deps.state.ownedRuns?.has(id), executionResult: true, includeProgress: params.includeProgress });
+            }
+            if (args[1].action === "interrupt")
+                return cancelSupervisorInput(result, args[1], args[4].sessionManager.getSessionId(), deps.pi.events);
+            if (args[1].action !== "status" || result.details.runList)
+                return result;
+            const requested = args[1].id ?? args[1].runId;
+            if (requested && !args[1].dir) {
+                try {
+                    const owned = resolveOwnedRun(deps.state, requested);
+                    if (owned)
+                        result = ownedRunStatusResult(owned, deps.state, result, { full: args[1].full, childSafe: Boolean(nestedResolutionScopeForExecutor(deps)) });
+                }
+                catch (error) {
+                    return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: { mode: "management", results: [] } };
+                }
+            }
+            return projectSupervisorQuestions(result, args[1], args[4].sessionManager.getSessionId(), Boolean(nestedResolutionScopeForExecutor(deps)));
+        } };
+}

package/dist/runs/foreground/subagent-params.js

@@ -0,0 +1,165 @@
+import {} from "../../agents/agents.js";
+import { materializeAgentDefaultOutputPath, normalizeSingleOutputOverride } from "../shared/single-output.js";
+import {} from "../../shared/settings.js";
+import {} from "../../shared/types.js";
+export function maxParallelTasksMessage(maxParallelTasks) {
+    return `Max ${maxParallelTasks} tasks. Split the batch into smaller parallel calls or raise parallel.maxTasks in ~/.pi/agent/extensions/subagent/config.json.`;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTaskParamLike(value) {
+    return isRecord(value) && typeof value.agent === "string";
+}
+function isDynamicParallelStepLike(value) {
+    return isRecord(value)
+        && isRecord(value.expand)
+        && isRecord(value.parallel)
+        && typeof value.parallel.agent === "string"
+        && isRecord(value.collect)
+        && typeof value.collect.as === "string";
+}
+function isParallelStepLike(value) {
+    return isRecord(value) && Array.isArray(value.parallel) && value.parallel.every(isTaskParamLike);
+}
+function isSequentialStepLike(value) {
+    return isRecord(value) && typeof value.agent === "string";
+}
+function isChainStepLike(value) {
+    if (!isRecord(value))
+        return false;
+    return isDynamicParallelStepLike(value) || isParallelStepLike(value) || isSequentialStepLike(value);
+}
+export function resolveAsyncExecutionMode(params, asyncByDefault) {
+    const hasForegroundTimeout = params.timeoutMs !== undefined || params.maxRuntimeMs !== undefined;
+    const requestedAsync = params.async ?? (hasForegroundTimeout ? false : asyncByDefault);
+    return {
+        effectiveAsync: requestedAsync && params.clarify !== true,
+        backgroundRequestedWhileClarifying: params.async === true && params.clarify === true,
+    };
+}
+function stringValue(params, key) {
+    const value = params[key];
+    return typeof value === "string" ? value : undefined;
+}
+function booleanValue(params, key) {
+    const value = params[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+function numberValue(params, key) {
+    const value = params[key];
+    return typeof value === "number" ? value : undefined;
+}
+function contextValue(params) {
+    const value = params.context;
+    return value === "fresh" || value === "fork" ? value : undefined;
+}
+function outputModeValue(params) {
+    const value = params.outputMode;
+    return value === "inline" || value === "file-only" ? value : undefined;
+}
+function outputValue(params) {
+    const value = params.output;
+    return typeof value === "string" || typeof value === "boolean" ? value : undefined;
+}
+export function usesAgentDefaultOutput(output) {
+    return output === undefined || output === true || output === "true";
+}
+export function resolveTopLevelOutputOverride(params) {
+    const effectiveOutput = usesAgentDefaultOutput(params.requestedOutput)
+        ? normalizeSingleOutputOverride(true, params.agentDefaultOutput)
+        : normalizeSingleOutputOverride(params.requestedOutput, params.agentDefaultOutput);
+    if (!usesAgentDefaultOutput(params.requestedOutput))
+        return effectiveOutput;
+    return materializeAgentDefaultOutputPath({
+        output: effectiveOutput,
+        artifactsDir: params.artifactsDir,
+        runId: params.runId,
+        agent: params.agent,
+        index: params.index,
+    });
+}
+function skillValue(params) {
+    const value = params.skill;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+}
+function maxOutputValue(params) {
+    const value = params.maxOutput;
+    if (!isRecord(value))
+        return undefined;
+    return {
+        ...(typeof value.bytes === "number" ? { bytes: value.bytes } : {}),
+        ...(typeof value.lines === "number" ? { lines: value.lines } : {}),
+    };
+}
+function isControlConfig(value) {
+    return isRecord(value);
+}
+function isAcceptanceInput(value) {
+    return isRecord(value);
+}
+export function normalizeSubagentParamsLike(params) {
+    const normalized = {
+        action: stringValue(params, "action"),
+        id: stringValue(params, "id"),
+        runId: stringValue(params, "runId"),
+        questionId: stringValue(params, "questionId"),
+        decision: params.decision === "accepted" || params.decision === "needs_changes" ? params.decision : undefined,
+        offset: numberValue(params, "offset"),
+        limit: numberValue(params, "limit"),
+        cursor: stringValue(params, "cursor"),
+        sort: ["attention", "newest", "oldest", "relevance"].includes(String(params.sort)) ? params.sort : undefined,
+        state: ["live", "completed", "failed", "blocked", "paused", "unknown"].includes(String(params.state)) ? params.state : undefined,
+        text: stringValue(params, "text"),
+        query: stringValue(params, "query"),
+        before: numberValue(params, "before"),
+        full: booleanValue(params, "full"),
+        dir: stringValue(params, "dir"),
+        index: numberValue(params, "index"),
+        agent: stringValue(params, "agent"),
+        task: stringValue(params, "task"),
+        label: stringValue(params, "label"),
+        message: stringValue(params, "message"),
+        concurrency: numberValue(params, "concurrency"),
+        timeoutMs: numberValue(params, "timeoutMs"),
+        maxRuntimeMs: numberValue(params, "maxRuntimeMs"),
+        extendMs: numberValue(params, "extendMs"),
+        worktree: booleanValue(params, "worktree"),
+        context: contextValue(params),
+        async: booleanValue(params, "async"),
+        clarify: booleanValue(params, "clarify"),
+        share: booleanValue(params, "share"),
+        control: isControlConfig(params.control) ? params.control : undefined,
+        sessionDir: stringValue(params, "sessionDir"),
+        cwd: stringValue(params, "cwd"),
+        maxOutput: maxOutputValue(params),
+        artifacts: booleanValue(params, "artifacts"),
+        includeProgress: booleanValue(params, "includeProgress"),
+        progress: booleanValue(params, "progress"),
+        model: stringValue(params, "model"),
+        skill: skillValue(params),
+        output: outputValue(params),
+        outputMode: outputModeValue(params),
+        outputSchema: isRecord(params.outputSchema) ? params.outputSchema : undefined,
+        agentScope: stringValue(params, "agentScope"),
+        chainName: stringValue(params, "chainName"),
+        config: params.config,
+        chainDir: stringValue(params, "chainDir"),
+        acceptance: isAcceptanceInput(params.acceptance) ? params.acceptance : undefined,
+    };
+    if (params.tasks !== undefined) {
+        if (!Array.isArray(params.tasks) || !params.tasks.every(isTaskParamLike)) {
+            throw new Error("tasks must be an array of task objects with an agent.");
+        }
+        normalized.tasks = params.tasks;
+    }
+    if (params.chain !== undefined) {
+        if (!Array.isArray(params.chain) || !params.chain.every(isChainStepLike)) {
+            throw new Error("chain must contain valid sequential, parallel, or dynamic fanout steps.");
+        }
+        normalized.chain = params.chain;
+    }
+    return normalized;
+}