iosm-cli 0.2.3 → 0.2.4

package/dist/core/tools/task.js

@@ -4,19 +4,26 @@ import { spawnSync } from "node:child_process";
 import { Type } from "@sinclair/typebox";
 import { getTeamRun, updateTeamTaskStatus } from "../agent-teams.js";
 import { buildRetrospectiveDirective, classifyFailureCause, formatFailureCauseCounts, isRetrospectiveRetryable, } from "../failure-retrospective.js";
+import { MAX_ORCHESTRATION_AGENTS, MAX_ORCHESTRATION_PARALLEL, MAX_SUBAGENT_DELEGATE_PARALLEL, MAX_SUBAGENT_DELEGATION_DEPTH, MAX_SUBAGENT_DELEGATIONS_PER_TASK, } from "../orchestration-limits.js";
 const taskSchema = Type.Object({
-    description: Type.String({
-        description: "Short 3-5 word description of what the subagent will do",
-    }),
-    prompt: Type.String({
-        description: "Full task prompt for the subagent",
-    }),
+    description: Type.Optional(Type.String({
+        description: "Optional short 3-5 word description of what the subagent will do. If omitted, it is derived from prompt.",
+    })),
+    task: Type.Optional(Type.String({
+        description: "Legacy alias for prompt. If provided, it is treated as the subagent prompt when prompt is omitted.",
+    })),
+    args: Type.Optional(Type.String({
+        description: "Legacy alias for prompt used by some models. If provided, it is treated as the subagent prompt when prompt/task are omitted.",
+    })),
+    prompt: Type.Optional(Type.String({
+        description: "Optional full task prompt for the subagent. If omitted, the description is used as the prompt.",
+    })),
     agent: Type.Optional(Type.String({
         description: "Optional custom subagent name loaded from .iosm/agents or global agents directory.",
     })),
-    profile: Type.String({
-        description: "Subagent capability profile. Recommended values: explore, plan, iosm, iosm_analyst, iosm_verifier, cycle_planner, full. For custom agents, pass the agent name via `agent`, not `profile`.",
-    }),
+    profile: Type.Optional(Type.String({
+        description: "Optional subagent capability profile. Defaults to full when omitted. Recommended values: explore, plan, iosm, meta, iosm_analyst, iosm_verifier, cycle_planner, full. For custom agents, pass the agent name via `agent`, not `profile`.",
+    })),
     cwd: Type.Optional(Type.String({
         description: "Optional working directory for this subagent. Relative paths are resolved from the current workspace.",
     })),
@@ -40,7 +47,7 @@ const taskSchema = Type.Object({
     })),
     delegate_parallel_hint: Type.Optional(Type.Integer({
         minimum: 1,
-        maximum: 10,
+        maximum: MAX_SUBAGENT_DELEGATE_PARALLEL,
         description: "Optional hint for intra-task delegation fan-out. Higher value allows more delegated subtasks to run in parallel inside a single task execution.",
     })),
 });
@@ -49,6 +56,7 @@ const toolsByProfile = {
     explore: ["read", "grep", "find", "ls"],
     plan: ["read", "bash", "grep", "find", "ls"],
     iosm: ["read", "bash", "edit", "write", "grep", "find", "ls"],
+    meta: ["read", "bash", "edit", "write", "grep", "find", "ls"],
     iosm_analyst: ["read", "bash", "grep", "find", "ls"],
     iosm_verifier: ["read", "bash", "write"],
     cycle_planner: ["read", "bash", "write"],
@@ -59,12 +67,13 @@ const systemPromptByProfile = {
     explore: "You are a fast read-only codebase explorer. Answer concisely. Never write or edit files.",
     plan: "You are a technical architect. Analyze the codebase and produce a clear implementation plan. Do not write or edit files.",
     iosm: "You are an IOSM execution agent. Use IOSM methodology and keep IOSM artifacts synchronized with implementation.",
+    meta: "You are a meta orchestration agent. Your main job is to maximize safe parallel execution through delegates, not to personally do most of the implementation. Start with bounded read-only recon, then form a concrete execution graph: subtasks, delegate subtasks, dependencies, lock domains, and verification steps. The parent agent remains responsible for orchestration and synthesis, so decompose work aggressively instead of collapsing complex work into one worker. For any non-trivial task, orchestration is required: after recon, launch multiple focused delegates instead of continuing manual implementation in the parent agent, avoid direct write/edit work in the parent agent before delegation unless the task is clearly trivial, and do not hand the whole task to one specialist child when independent workstreams exist. If a delegated workstream still contains multiple independent slices, split it again with nested <delegate_task> blocks. Default to aggressive safe parallelism. If the user requested a specific degree of parallelism, honor it when feasible or explain the exact blocker. When delegation is not used for non-trivial work, explain why in one line and include DELEGATION_IMPOSSIBLE. Enforce test verification for code changes, complete only after all delegated branches are resolved, and explicitly justify any no-code path where tests are skipped.",
     iosm_analyst: "You are an IOSM metrics analyst. Analyze .iosm/ artifacts and codebase metrics. Be precise and evidence-based.",
     iosm_verifier: "You are an IOSM verifier. Validate checks and update only required IOSM artifacts with deterministic reasoning.",
     cycle_planner: "You are an IOSM cycle planner. Propose and align cycle goals with measurable outcomes and concrete risks.",
     full: "You are a software engineering agent. Execute the task end-to-end.",
 };
-const writeCapableProfiles = new Set(["full", "iosm_verifier", "cycle_planner"]);
+const writeCapableProfiles = new Set(["full", "meta", "iosm_verifier", "cycle_planner"]);
 const delegationTagName = "delegate_task";
 class Semaphore {
     constructor(limit) {
@@ -121,11 +130,11 @@ class Mutex {
         return !this.locked && this.waiters.length === 0;
     }
 }
-const maxParallelFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_PARALLEL, 20, 1, 20);
+const maxParallelFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_PARALLEL, MAX_ORCHESTRATION_PARALLEL, 1, MAX_ORCHESTRATION_PARALLEL);
 const subagentSemaphore = new Semaphore(maxParallelFromEnv);
-const maxDelegationDepthFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATION_DEPTH, 1, 0, 3);
-const maxDelegationsPerTaskFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATIONS_PER_TASK, 10, 0, 10);
-const maxDelegatedParallelFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATE_PARALLEL, 10, 1, 10);
+const maxDelegationDepthFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATION_DEPTH, 1, 0, MAX_SUBAGENT_DELEGATION_DEPTH);
+const maxDelegationsPerTaskFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATIONS_PER_TASK, MAX_SUBAGENT_DELEGATIONS_PER_TASK, 0, MAX_SUBAGENT_DELEGATIONS_PER_TASK);
+const maxDelegatedParallelFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATE_PARALLEL, MAX_SUBAGENT_DELEGATE_PARALLEL, 1, MAX_SUBAGENT_DELEGATE_PARALLEL);
 const emptyOutputRetriesFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_EMPTY_OUTPUT_RETRIES, 1, 0, 2);
 const retrospectiveRetriesFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_RETRO_RETRIES, 1, 0, 1);
 const orchestrationDependencyWaitTimeoutMsFromEnv = parseBoundedInt(process.env.IOSM_ORCHESTRATION_DEPENDENCY_WAIT_TIMEOUT_MS, 120_000, 5_000, 900_000);
@@ -141,14 +150,21 @@ function parseBoundedInt(raw, fallback, min, max) {
         return fallback;
     return Math.max(min, Math.min(max, parsed));
 }
-function shouldAutoDelegateByAgent(agentName) {
-    if (!agentName)
-        return false;
-    const normalized = agentName.trim().toLowerCase();
-    return normalized.includes("orchestrator");
+function shouldAutoDelegate(input) {
+    const profile = input.profile?.trim().toLowerCase();
+    if (profile === "meta")
+        return true;
+    const hostProfile = input.hostProfile?.trim().toLowerCase();
+    if (hostProfile === "meta")
+        return true;
+    const agentName = input.agentName?.trim().toLowerCase();
+    return !!agentName && agentName.includes("orchestrator");
 }
-function deriveAutoDelegateParallelHint(agentName, description, prompt) {
-    if (!shouldAutoDelegateByAgent(agentName))
+function deriveAutoDelegateParallelHint(profile, agentName, hostProfile, description, prompt) {
+    const normalizedProfile = profile?.trim().toLowerCase();
+    const isMetaProfile = normalizedProfile === "meta";
+    const isMetaHost = hostProfile?.trim().toLowerCase() === "meta";
+    if (!shouldAutoDelegate({ profile: normalizedProfile, agentName, hostProfile }))
         return undefined;
     const text = `${description}\n${prompt}`.trim();
     if (!text)
@@ -186,6 +202,10 @@ function deriveAutoDelegateParallelHint(agentName, description, prompt) {
     if (hasCodeBlock) {
         score += 1;
     }
+    if ((isMetaProfile || isMetaHost) && score > 0) {
+        // Meta profile is intentionally parallel-biased for non-trivial work.
+        score += 1;
+    }
     if (score >= 6)
         return 10;
     if (score >= 5)
@@ -203,6 +223,40 @@ function deriveAutoDelegateParallelHint(agentName, description, prompt) {
 function normalizeSpacing(text) {
     return text.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
 }
+function deriveTaskDescriptionFromPrompt(prompt) {
+    const firstMeaningfulLine = prompt
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line.length > 0) ?? "Run subtask";
+    const normalized = firstMeaningfulLine
+        .replace(/^[-*]\s+/, "")
+        .replace(/^\d+[.)]\s+/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (normalized.length <= 80) {
+        return normalized;
+    }
+    return `${normalized.slice(0, 77).trimEnd()}...`;
+}
+function normalizeTaskPayload(input) {
+    const rawDescription = input.description?.trim();
+    const rawTask = input.task?.trim();
+    const rawArgs = input.args?.trim();
+    const rawPrompt = input.prompt?.trim() || rawTask || rawArgs;
+    if (rawDescription && rawPrompt) {
+        return { description: rawDescription, prompt: rawPrompt };
+    }
+    if (rawDescription) {
+        return { description: rawDescription, prompt: rawDescription };
+    }
+    if (rawPrompt) {
+        return {
+            description: deriveTaskDescriptionFromPrompt(rawPrompt),
+            prompt: rawPrompt,
+        };
+    }
+    throw new Error('Task tool requires at least one of "description", "task", "args", or "prompt".');
+}
 function cloneDelegateItems(items) {
     return items ? items.map((item) => ({ ...item })) : undefined;
 }
@@ -248,26 +302,43 @@ function mergeRunStats(base, next) {
         assistantMessages: (base?.assistantMessages ?? 0) + (next?.assistantMessages ?? 0),
     };
 }
-function buildDelegationProtocolPrompt(depthRemaining, maxDelegations) {
+function buildDelegationProtocolPrompt(depthRemaining, maxDelegations, minDelegationsPreferred = 0) {
     if (depthRemaining <= 0) {
         return [
             `Delegation protocol: depth limit reached.`,
             `Do not emit <${delegationTagName}> blocks.`,
         ].join("\n");
     }
+    if (minDelegationsPreferred > 0) {
+        const required = Math.min(Math.max(1, minDelegationsPreferred), maxDelegations);
+        return [
+            `Delegation protocol (required for this run): emit at least ${required} XML block(s) when the assigned work still contains independent slices.`,
+            `For broad audit, implementation, or verification tasks, split by subsystem, file family, or verification stream instead of producing one monolithic answer.`,
+            `<${delegationTagName} profile="explore|plan|iosm|meta|iosm_analyst|iosm_verifier|cycle_planner|full" agent="optional custom subagent name" description="short title" cwd="optional relative path" lock_key="optional lock key" model="optional model override" isolation="none|worktree" depends_on="optional indices like 1|3">`,
+            "Detailed delegated task prompt",
+            `</${delegationTagName}>`,
+            `Keep a brief coordinator note outside the blocks, but do not collapse the full workload into one monolithic answer.`,
+            `If safe decomposition is truly impossible, output exactly one line: DELEGATION_IMPOSSIBLE: <precise reason>.`,
+            `When shared_memory tools are available, exchange intermediate state through shared_memory_write/shared_memory_read instead of repeating large context.`,
+        ].join("\n");
+    }
     return [
         `Delegation protocol (optional): if you discover concrete independent follow-ups, emit up to ${maxDelegations} XML block(s):`,
-        `<${delegationTagName} profile="explore|plan|iosm|iosm_analyst|iosm_verifier|cycle_planner|full" agent="optional custom subagent name" description="short title" cwd="optional relative path" lock_key="optional lock key" model="optional model override" isolation="none|worktree" depends_on="optional indices like 1|3">`,
+        `<${delegationTagName} profile="explore|plan|iosm|meta|iosm_analyst|iosm_verifier|cycle_planner|full" agent="optional custom subagent name" description="short title" cwd="optional relative path" lock_key="optional lock key" model="optional model override" isolation="none|worktree" depends_on="optional indices like 1|3">`,
         "Detailed delegated task prompt",
         `</${delegationTagName}>`,
         `Only emit blocks when necessary. Keep normal analysis/answer text outside those blocks.`,
         `When shared_memory tools are available, exchange intermediate state through shared_memory_write/shared_memory_read instead of repeating large context.`,
     ].join("\n");
 }
-function withDelegationPrompt(basePrompt, depthRemaining, maxDelegations) {
-    const protocol = buildDelegationProtocolPrompt(depthRemaining, maxDelegations);
+function withDelegationPrompt(basePrompt, depthRemaining, maxDelegations, minDelegationsPreferred = 0) {
+    const protocol = buildDelegationProtocolPrompt(depthRemaining, maxDelegations, minDelegationsPreferred);
     return `${basePrompt}\n\n${protocol}`;
 }
+function withSubagentInstructions(basePrompt, instructions) {
+    const trimmed = instructions?.trim();
+    return trimmed ? `${basePrompt}\n\n${trimmed}` : basePrompt;
+}
 function buildSharedMemoryGuidance(runId, taskId) {
     return [
         "[SHARED_MEMORY]",
@@ -368,9 +439,9 @@ function getRunParallelLimit(cwd, runId) {
         return 1;
     const maxParallel = teamRun.maxParallel;
     if (!Number.isInteger(maxParallel) || !maxParallel || maxParallel < 1) {
-        return Math.max(1, Math.min(teamRun.agents, 20));
+        return Math.max(1, Math.min(teamRun.agents, MAX_ORCHESTRATION_AGENTS));
     }
-    return Math.max(1, Math.min(maxParallel, 20));
+    return Math.max(1, Math.min(maxParallel, MAX_ORCHESTRATION_PARALLEL));
 }
 function getOrCreateOrchestrationSemaphore(cwd, runId) {
     const limit = getRunParallelLimit(cwd, runId);
@@ -587,13 +658,13 @@ export function createTaskTool(cwd, runner, options) {
         label: "task",
         description: "Launch a specialized subagent to handle a subtask in isolation. " +
             "Use for: codebase exploration (profile=explore), architectural planning (profile=plan), " +
-            "IOSM artifact analysis (profile=iosm_analyst/iosm_verifier/cycle_planner), or end-to-end implementation (profile=full). " +
+            "IOSM artifact analysis (profile=iosm_analyst/iosm_verifier/cycle_planner), orchestration-first execution (profile=meta), or end-to-end implementation (profile=full). " +
             "Set cwd to isolate subagents into different project areas when orchestrating parallel work. " +
             "The subagent runs to completion and returns its full text output. " +
             "It may request bounded follow-up delegation via <delegate_task> blocks that are executed by the parent task tool." +
             customAgentsSnippet,
         parameters: taskSchema,
-        execute: async (_toolCallId, { description, prompt, agent: agentName, profile, cwd: targetCwd, lock_key: lockKey, run_id: orchestrationRunId, task_id: orchestrationTaskId, model: requestedModel, background, isolation, delegate_parallel_hint: delegateParallelHint, }, _signal, onUpdate) => {
+        execute: async (_toolCallId, { description: rawDescription, task: rawTask, args: rawArgs, prompt: rawPrompt, agent: agentName, profile, cwd: targetCwd, lock_key: lockKey, run_id: orchestrationRunId, task_id: orchestrationTaskId, model: requestedModel, background, isolation, delegate_parallel_hint: delegateParallelHint, }, _signal, onUpdate) => {
             const updateTrackedTaskStatus = (status) => {
                 if (!orchestrationRunId || !orchestrationTaskId)
                     return;
@@ -610,6 +681,12 @@ export function createTaskTool(cwd, runner, options) {
                     throw new Error("Operation aborted");
                 }
             };
+            const { description, prompt } = normalizeTaskPayload({
+                description: rawDescription,
+                task: rawTask,
+                args: rawArgs,
+                prompt: rawPrompt,
+            });
             const runId = `subagent_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
             const sharedMemoryRunId = orchestrationRunId?.trim() || runId;
             const sharedMemoryTaskId = orchestrationTaskId?.trim() || runId;
@@ -620,10 +697,9 @@ export function createTaskTool(cwd, runner, options) {
                 return options.resolveCustomSubagent(name);
             };
             let normalizedAgentName = agentName?.trim() || undefined;
-            let normalizedProfile = profile.trim().toLowerCase();
-            if (!normalizedProfile)
-                normalizedProfile = "full";
             let customSubagent = resolveCustom(normalizedAgentName);
+            let normalizedProfile = profile?.trim().toLowerCase() || customSubagent?.profile?.trim().toLowerCase() || "full";
+            const normalizedHostProfile = options?.getHostProfileName?.()?.trim().toLowerCase() ?? options?.hostProfileName?.trim().toLowerCase();
             if (normalizedAgentName && !customSubagent) {
                 const available = availableCustomNames.length > 0 ? ` Available custom agents: ${availableCustomNames.join(", ")}.` : "";
                 throw new Error(`Unknown subagent: ${normalizedAgentName}.${available}`);
@@ -650,24 +726,32 @@ export function createTaskTool(cwd, runner, options) {
             }
             const delegationDepth = maxDelegationDepthFromEnv;
             const requestedDelegateParallelHint = typeof delegateParallelHint === "number" && Number.isInteger(delegateParallelHint)
-                ? Math.max(1, Math.min(10, delegateParallelHint))
+                ? Math.max(1, Math.min(MAX_SUBAGENT_DELEGATE_PARALLEL, delegateParallelHint))
                 : undefined;
             const autoDelegateParallelHint = requestedDelegateParallelHint === undefined
-                ? deriveAutoDelegateParallelHint(normalizedAgentName, description, prompt)
+                ? deriveAutoDelegateParallelHint(effectiveProfile, normalizedAgentName, normalizedHostProfile, description, prompt)
                 : undefined;
-            const effectiveDelegateParallelHint = requestedDelegateParallelHint ?? autoDelegateParallelHint;
-            const effectiveMaxDelegations = Math.max(0, Math.min(maxDelegationsPerTaskFromEnv, effectiveDelegateParallelHint ?? maxDelegationsPerTaskFromEnv));
-            const effectiveMaxDelegateParallel = Math.max(1, Math.min(maxDelegatedParallelFromEnv, effectiveDelegateParallelHint ?? maxDelegatedParallelFromEnv));
+            let effectiveDelegateParallelHint = requestedDelegateParallelHint ?? autoDelegateParallelHint;
+            const effectiveDelegationDepth = effectiveProfile === "meta" || normalizedHostProfile === "meta" || normalizedAgentName?.toLowerCase().includes("orchestrator")
+                ? Math.max(delegationDepth, 2)
+                : delegationDepth;
+            let effectiveMaxDelegations = Math.max(0, Math.min(maxDelegationsPerTaskFromEnv, effectiveDelegateParallelHint ?? maxDelegationsPerTaskFromEnv));
+            let effectiveMaxDelegateParallel = Math.max(1, Math.min(maxDelegatedParallelFromEnv, effectiveDelegateParallelHint ?? maxDelegatedParallelFromEnv));
+            const preferredDelegationFloor = effectiveProfile === "meta" || normalizedHostProfile === "meta" ? 3 : 2;
+            const applyMetaDelegationFloor = requestedDelegateParallelHint === undefined &&
+                (effectiveProfile === "meta" || normalizedHostProfile === "meta");
+            if (applyMetaDelegationFloor) {
+                effectiveMaxDelegations = Math.max(effectiveMaxDelegations, Math.min(maxDelegationsPerTaskFromEnv, preferredDelegationFloor));
+                effectiveMaxDelegateParallel = Math.max(effectiveMaxDelegateParallel, Math.min(maxDelegatedParallelFromEnv, preferredDelegationFloor));
+            }
             const minDelegationsPreferred = (effectiveDelegateParallelHint ?? 0) >= 2 && effectiveMaxDelegations >= 2
-                ? Math.min(2, effectiveMaxDelegations)
+                ? Math.min(preferredDelegationFloor, effectiveMaxDelegations, effectiveDelegateParallelHint ?? preferredDelegationFloor)
                 : 0;
-            const baseSystemPrompt = customSubagent?.systemPrompt ??
+            const baseSystemPrompt = withSubagentInstructions(customSubagent?.systemPrompt ??
                 systemPromptByProfile[effectiveProfile] ??
-                systemPromptByProfile.full;
-            const systemPrompt = withDelegationPrompt(baseSystemPrompt, delegationDepth, effectiveMaxDelegations);
-            const promptWithInstructions = customSubagent?.instructions && customSubagent.instructions.trim().length > 0
-                ? `${customSubagent.instructions.trim()}\n\nUser task:\n${prompt}`
-                : prompt;
+                systemPromptByProfile.full, customSubagent?.instructions);
+            const systemPrompt = withDelegationPrompt(baseSystemPrompt, effectiveDelegationDepth, effectiveMaxDelegations, minDelegationsPreferred);
+            const promptWithInstructions = prompt;
             const effectiveModelOverride = requestedModel?.trim() || customSubagent?.model?.trim() || undefined;
             const requestedBackground = background === true || customSubagent?.background === true;
             const trackedOrchestrationRun = orchestrationRunId && orchestrationTaskId ? getTeamRun(cwd, orchestrationRunId) : undefined;
@@ -850,6 +934,7 @@ export function createTaskTool(cwd, runner, options) {
                                 try {
                                     const result = await runner({
                                         systemPrompt,
+                                        profileName: effectiveProfile,
                                         tools,
                                         prompt: promptForAttempt,
                                         cwd: subagentCwd,
@@ -942,7 +1027,7 @@ export function createTaskTool(cwd, runner, options) {
                         output = firstPass.output;
                         subagentSessionId = firstPass.sessionId;
                         runStats = firstPass.stats;
-                        let parsedDelegation = parseDelegationRequests(output, delegationDepth > 0 ? effectiveMaxDelegations : 0);
+                        let parsedDelegation = parseDelegationRequests(output, effectiveDelegationDepth > 0 ? effectiveMaxDelegations : 0);
                         if (minDelegationsPreferred > 0 && parsedDelegation.requests.length < minDelegationsPreferred) {
                             emitProgress({
                                 kind: "subagent_progress",
@@ -965,7 +1050,7 @@ export function createTaskTool(cwd, runner, options) {
                             output = secondPass.output;
                             subagentSessionId = secondPass.sessionId ?? subagentSessionId;
                             runStats = secondPass.stats ?? runStats;
-                            parsedDelegation = parseDelegationRequests(output, delegationDepth > 0 ? effectiveMaxDelegations : 0);
+                            parsedDelegation = parseDelegationRequests(output, effectiveDelegationDepth > 0 ? effectiveMaxDelegations : 0);
                         }
                         if (minDelegationsPreferred > 0 && parsedDelegation.requests.length < minDelegationsPreferred) {
                             const impossibleReason = output.match(/^\s*DELEGATION_IMPOSSIBLE\s*:\s*(.+)$/im)?.[1]?.trim() ?? "not provided";
@@ -1037,6 +1122,128 @@ export function createTaskTool(cwd, runner, options) {
                                 delegateItems,
                             });
                         };
+                        const executeNestedDelegates = async (requests, parentCwd, depthRemaining, lineage) => {
+                            if (requests.length === 0 || depthRemaining <= 0) {
+                                return { sections: [], warnings: [] };
+                            }
+                            const nestedWarnings = [];
+                            const sections = [];
+                            for (const [nestedIndex, nestedRequest] of requests.entries()) {
+                                const requestLabel = `${lineage}${nestedIndex + 1}`;
+                                const requestedNestedAgent = nestedRequest.agent?.trim() || undefined;
+                                const nestedCustomSubagent = resolveCustom(requestedNestedAgent);
+                                if (requestedNestedAgent && !nestedCustomSubagent) {
+                                    nestedWarnings.push(`Nested delegated task "${nestedRequest.description}" requested unknown agent "${requestedNestedAgent}". Falling back to profile "${nestedRequest.profile}".`);
+                                }
+                                const nestedProfileRaw = nestedCustomSubagent?.profile ?? nestedRequest.profile;
+                                const normalizedNestedProfile = nestedProfileRaw.trim().toLowerCase();
+                                const nestedProfile = normalizedNestedProfile && toolsByProfile[normalizedNestedProfile]
+                                    ? normalizedNestedProfile
+                                    : "full";
+                                const nestedProfileLabel = nestedCustomSubagent?.name
+                                    ? `${nestedCustomSubagent.name}/${nestedProfile}`
+                                    : nestedProfile;
+                                let nestedTools = nestedCustomSubagent?.tools
+                                    ? [...nestedCustomSubagent.tools]
+                                    : [...(toolsByProfile[nestedProfile] ?? toolsByProfile.explore)];
+                                if (nestedCustomSubagent?.disallowedTools?.length) {
+                                    const blocked = new Set(nestedCustomSubagent.disallowedTools);
+                                    nestedTools = nestedTools.filter((tool) => !blocked.has(tool));
+                                }
+                                const nestedBaseSystemPrompt = withSubagentInstructions(nestedCustomSubagent?.systemPrompt ??
+                                    systemPromptByProfile[nestedProfile] ??
+                                    systemPromptByProfile.full, nestedCustomSubagent?.instructions);
+                                const nestedSystemPrompt = withDelegationPrompt(nestedBaseSystemPrompt, Math.max(0, depthRemaining - 1), effectiveMaxDelegations);
+                                const requestedNestedCwd = nestedRequest.cwd
+                                    ? path.resolve(parentCwd, nestedRequest.cwd)
+                                    : nestedCustomSubagent?.cwd ?? parentCwd;
+                                if (!existsSync(requestedNestedCwd) || !statSync(requestedNestedCwd).isDirectory()) {
+                                    recordFailureCause("dependency_env");
+                                    delegatedFailed += 1;
+                                    delegatedTasks += 1;
+                                    sections.push(`###### ${requestLabel}. ${nestedRequest.description} (${nestedProfileLabel})\nERROR [cause=dependency_env]: nested delegate skipped: missing cwd`);
+                                    continue;
+                                }
+                                let nestedReleaseLock;
+                                let nestedReleaseIsolation;
+                                let nestedCwd = requestedNestedCwd;
+                                try {
+                                    if (writeCapableProfiles.has(nestedProfile) && nestedRequest.lockKey?.trim()) {
+                                        const lock = getOrCreateWriteLock(nestedRequest.lockKey.trim());
+                                        nestedReleaseLock = await lock.acquire();
+                                    }
+                                    if (nestedRequest.isolation === "worktree") {
+                                        const isolated = provisionWorktree(cwd, requestedNestedCwd, `${runId}_nested_${requestLabel.replace(/\./g, "_")}`);
+                                        nestedCwd = isolated.runCwd;
+                                        nestedReleaseIsolation = isolated.cleanup;
+                                    }
+                                    const nestedPromptWithInstructions = nestedRequest.prompt;
+                                    const nestedSharedMemoryGuidance = buildSharedMemoryGuidance(sharedMemoryRunId, sharedMemoryTaskId);
+                                    const nestedPrompt = `${nestedPromptWithInstructions}\n\n${nestedSharedMemoryGuidance}`;
+                                    const nestedModelOverride = nestedRequest.model?.trim() || nestedCustomSubagent?.model?.trim() || undefined;
+                                    const nestedSharedMemoryContext = {
+                                        rootCwd: cwd,
+                                        runId: sharedMemoryRunId,
+                                        taskId: sharedMemoryTaskId,
+                                        delegateId: requestLabel,
+                                        profile: nestedProfile,
+                                    };
+                                    const nestedResult = await runner({
+                                        systemPrompt: nestedSystemPrompt,
+                                        profileName: nestedProfile,
+                                        tools: nestedTools,
+                                        prompt: nestedPrompt,
+                                        cwd: nestedCwd,
+                                        modelOverride: nestedModelOverride,
+                                        sharedMemoryContext: nestedSharedMemoryContext,
+                                        signal: _signal,
+                                        onProgress: (progress) => {
+                                            emitProgress({
+                                                kind: "subagent_progress",
+                                                phase: "running",
+                                                message: `delegate ${requestLabel}: ${progress.message}`,
+                                                cwd: progress.cwd ?? nestedCwd,
+                                                activeTool: progress.activeTool,
+                                            });
+                                        },
+                                    });
+                                    throwIfAborted();
+                                    let nestedOutput = typeof nestedResult === "string" ? nestedResult : nestedResult.output;
+                                    const nestedStats = typeof nestedResult === "string" ? undefined : nestedResult.stats;
+                                    delegatedTasks += 1;
+                                    delegatedSucceeded += 1;
+                                    delegatedStats.toolCallsStarted += nestedStats?.toolCallsStarted ?? 0;
+                                    delegatedStats.toolCallsCompleted += nestedStats?.toolCallsCompleted ?? 0;
+                                    delegatedStats.assistantMessages += nestedStats?.assistantMessages ?? 0;
+                                    const parsedNestedDelegation = parseDelegationRequests(nestedOutput, depthRemaining > 1 ? effectiveMaxDelegations : 0);
+                                    nestedOutput = parsedNestedDelegation.cleanedOutput;
+                                    nestedWarnings.push(...parsedNestedDelegation.warnings.map((warning) => `Nested child ${requestLabel}: ${warning}`));
+                                    let nestedSection = `###### ${requestLabel}. ${nestedRequest.description} (${nestedProfileLabel})\n${nestedOutput.trim() || "(no output)"}`;
+                                    if (parsedNestedDelegation.requests.length > 0 && depthRemaining > 1) {
+                                        const deeper = await executeNestedDelegates(parsedNestedDelegation.requests, nestedCwd, depthRemaining - 1, `${requestLabel}.`);
+                                        nestedWarnings.push(...deeper.warnings);
+                                        if (deeper.sections.length > 0) {
+                                            nestedSection = `${nestedSection}\n\n##### Nested Delegated Subtasks\n\n${deeper.sections.join("\n\n")}`;
+                                        }
+                                    }
+                                    sections.push(nestedSection);
+                                }
+                                catch (error) {
+                                    const message = error instanceof Error ? error.message : String(error);
+                                    const cause = classifyFailureCause(message);
+                                    recordFailureCause(cause);
+                                    delegatedTasks += 1;
+                                    delegatedFailed += 1;
+                                    sections.push(`###### ${requestLabel}. ${nestedRequest.description} (${nestedProfileLabel})\nERROR [cause=${cause}]: ${message}`);
+                                }
+                                finally {
+                                    nestedReleaseIsolation?.();
+                                    nestedReleaseLock?.();
+                                    cleanupWriteLock(nestedRequest.lockKey?.trim());
+                                }
+                            }
+                            return { sections, warnings: nestedWarnings };
+                        };
                         const runDelegate = async (index) => {
                             throwIfAborted();
                             const request = parsedDelegation.requests[index];
@@ -1075,10 +1282,15 @@ export function createTaskTool(cwd, runner, options) {
                                 const blocked = new Set(childCustomSubagent.disallowedTools);
                                 childTools = childTools.filter((tool) => !blocked.has(tool));
                             }
-                            const childBaseSystemPrompt = childCustomSubagent?.systemPrompt ??
+                            const childBaseSystemPrompt = withSubagentInstructions(childCustomSubagent?.systemPrompt ??
                                 systemPromptByProfile[childProfile] ??
-                                systemPromptByProfile.full;
-                            const childSystemPrompt = withDelegationPrompt(childBaseSystemPrompt, Math.max(0, delegationDepth - 1), effectiveMaxDelegations);
+                                systemPromptByProfile.full, childCustomSubagent?.instructions);
+                            const childAutoDelegateParallelHint = deriveAutoDelegateParallelHint(childProfile, requestedChildAgent, normalizedHostProfile, request.description, request.prompt);
+                            const childMinDelegationsPreferred = Math.max(0, effectiveDelegationDepth - 1) > 0 &&
+                                (childAutoDelegateParallelHint ?? 0) >= 2
+                                ? Math.min(preferredDelegationFloor, effectiveMaxDelegations, childAutoDelegateParallelHint ?? preferredDelegationFloor)
+                                : 0;
+                            const childSystemPrompt = withDelegationPrompt(childBaseSystemPrompt, Math.max(0, effectiveDelegationDepth - 1), effectiveMaxDelegations, childMinDelegationsPreferred);
                             const requestedChildCwd = request.cwd
                                 ? path.resolve(subagentCwd, request.cwd)
                                 : childCustomSubagent?.cwd ?? subagentCwd;
@@ -1104,9 +1316,7 @@ export function createTaskTool(cwd, runner, options) {
                                     childReleaseIsolation = isolated.cleanup;
                                 }
                                 const delegateMeta = formatMetaCheckpoint(options?.getMetaMessages?.());
-                                const childPromptWithInstructions = childCustomSubagent?.instructions && childCustomSubagent.instructions.trim().length > 0
-                                    ? `${childCustomSubagent.instructions.trim()}\n\nUser task:\n${request.prompt}`
-                                    : request.prompt;
+                                const childPromptWithInstructions = request.prompt;
                                 const delegateSharedMemoryGuidance = buildSharedMemoryGuidance(sharedMemoryRunId, sharedMemoryTaskId);
                                 const delegatePromptBase = `${childPromptWithInstructions}\n\n${delegateSharedMemoryGuidance}`;
                                 const delegatePrompt = delegateMeta.section && delegateMeta.appliedCount > 0
@@ -1136,108 +1346,153 @@ export function createTaskTool(cwd, runner, options) {
                                 };
                                 let childOutput = "";
                                 let childStats;
-                                let childEmptyAttempt = 0;
-                                let childRetrospectiveAttempt = 0;
-                                let childPromptForAttempt = delegatePrompt;
-                                while (true) {
-                                    try {
-                                        const childResult = await runner({
-                                            systemPrompt: childSystemPrompt,
-                                            tools: childTools,
-                                            prompt: childPromptForAttempt,
-                                            cwd: childCwd,
-                                            modelOverride: childModelOverride,
-                                            sharedMemoryContext: childSharedMemoryContext,
-                                            signal: _signal,
-                                            onProgress: (progress) => {
-                                                emitProgress({
-                                                    kind: "subagent_progress",
-                                                    phase: "running",
-                                                    message: `delegate ${index + 1}/${delegateTotal}: ${progress.message}`,
-                                                    cwd: progress.cwd ?? childCwd,
-                                                    activeTool: progress.activeTool,
-                                                    delegateIndex: index + 1,
-                                                    delegateTotal,
-                                                    delegateDescription: request.description,
-                                                    delegateProfile: childProfileLabel,
-                                                    delegateItems,
-                                                });
-                                            },
-                                        });
-                                        throwIfAborted();
-                                        let attemptOutput;
-                                        let attemptStats;
-                                        if (typeof childResult === "string") {
-                                            attemptOutput = childResult;
-                                        }
-                                        else {
-                                            attemptOutput = childResult.output;
-                                            attemptStats = childResult.stats;
-                                        }
-                                        childStats = mergeRunStats(childStats, attemptStats);
-                                        if (attemptOutput.trim().length > 0) {
-                                            childOutput = attemptOutput;
-                                            if (childRetrospectiveAttempt > 0) {
-                                                retrospectiveRecovered += 1;
+                                const runChildPass = async (runPrompt) => {
+                                    let childEmptyAttempt = 0;
+                                    let childRetrospectiveAttempt = 0;
+                                    let childPromptForAttempt = runPrompt;
+                                    while (true) {
+                                        try {
+                                            const childResult = await runner({
+                                                systemPrompt: childSystemPrompt,
+                                                profileName: childProfile,
+                                                tools: childTools,
+                                                prompt: childPromptForAttempt,
+                                                cwd: childCwd,
+                                                modelOverride: childModelOverride,
+                                                sharedMemoryContext: childSharedMemoryContext,
+                                                signal: _signal,
+                                                onProgress: (progress) => {
+                                                    emitProgress({
+                                                        kind: "subagent_progress",
+                                                        phase: "running",
+                                                        message: `delegate ${index + 1}/${delegateTotal}: ${progress.message}`,
+                                                        cwd: progress.cwd ?? childCwd,
+                                                        activeTool: progress.activeTool,
+                                                        delegateIndex: index + 1,
+                                                        delegateTotal,
+                                                        delegateDescription: request.description,
+                                                        delegateProfile: childProfileLabel,
+                                                        delegateItems,
+                                                    });
+                                                },
+                                            });
+                                            throwIfAborted();
+                                            let attemptOutput;
+                                            let attemptStats;
+                                            if (typeof childResult === "string") {
+                                                attemptOutput = childResult;
                                             }
-                                            break;
-                                        }
-                                        if (childEmptyAttempt >= emptyOutputRetriesFromEnv) {
-                                            const totalAttempts = childEmptyAttempt + 1;
-                                            throw new Error(`delegate ${index + 1}/${delegateTotal} returned empty output after ${totalAttempts} attempt${totalAttempts === 1 ? "" : "s"}.`);
-                                        }
-                                        childEmptyAttempt += 1;
-                                        emitProgress({
-                                            kind: "subagent_progress",
-                                            phase: "running",
-                                            message: `delegate ${index + 1}/${delegateTotal}: empty output, retry ${childEmptyAttempt}/${emptyOutputRetriesFromEnv}`,
-                                            cwd: childCwd,
-                                            activeTool: undefined,
-                                            delegateIndex: index + 1,
-                                            delegateTotal,
-                                            delegateDescription: request.description,
-                                            delegateProfile: childProfileLabel,
-                                            delegateItems,
-                                        });
-                                    }
-                                    catch (error) {
-                                        if (_signal?.aborted || isAbortError(error)) {
-                                            throw new Error("Operation aborted");
+                                            else {
+                                                attemptOutput = childResult.output;
+                                                attemptStats = childResult.stats;
+                                            }
+                                            childStats = mergeRunStats(childStats, attemptStats);
+                                            if (attemptOutput.trim().length > 0) {
+                                                if (childRetrospectiveAttempt > 0) {
+                                                    retrospectiveRecovered += 1;
+                                                }
+                                                return attemptOutput;
+                                            }
+                                            if (childEmptyAttempt >= emptyOutputRetriesFromEnv) {
+                                                const totalAttempts = childEmptyAttempt + 1;
+                                                throw new Error(`delegate ${index + 1}/${delegateTotal} returned empty output after ${totalAttempts} attempt${totalAttempts === 1 ? "" : "s"}.`);
+                                            }
+                                            childEmptyAttempt += 1;
+                                            emitProgress({
+                                                kind: "subagent_progress",
+                                                phase: "running",
+                                                message: `delegate ${index + 1}/${delegateTotal}: empty output, retry ${childEmptyAttempt}/${emptyOutputRetriesFromEnv}`,
+                                                cwd: childCwd,
+                                                activeTool: undefined,
+                                                delegateIndex: index + 1,
+                                                delegateTotal,
+                                                delegateDescription: request.description,
+                                                delegateProfile: childProfileLabel,
+                                                delegateItems,
+                                            });
                                         }
-                                        const message = error instanceof Error ? error.message : String(error);
-                                        const cause = classifyFailureCause(message);
-                                        recordFailureCause(cause);
-                                        const canRetryRetrospective = childRetrospectiveAttempt < retrospectiveRetriesFromEnv &&
-                                            isRetrospectiveRetryable(cause);
-                                        if (!canRetryRetrospective) {
-                                            throw Object.assign(new Error(message), { failureCause: cause });
+                                        catch (error) {
+                                            if (_signal?.aborted || isAbortError(error)) {
+                                                throw new Error("Operation aborted");
+                                            }
+                                            const message = error instanceof Error ? error.message : String(error);
+                                            const cause = classifyFailureCause(message);
+                                            recordFailureCause(cause);
+                                            const canRetryRetrospective = childRetrospectiveAttempt < retrospectiveRetriesFromEnv &&
+                                                isRetrospectiveRetryable(cause);
+                                            if (!canRetryRetrospective) {
+                                                throw Object.assign(new Error(message), { failureCause: cause });
+                                            }
+                                            childRetrospectiveAttempt += 1;
+                                            retrospectiveAttempts += 1;
+                                            const directive = buildRetrospectiveDirective({
+                                                cause,
+                                                errorMessage: message,
+                                                attempt: childRetrospectiveAttempt,
+                                                target: "delegate",
+                                            });
+                                            childPromptForAttempt = `${runPrompt}\n\n${directive}`;
+                                            emitProgress({
+                                                kind: "subagent_progress",
+                                                phase: "running",
+                                                message: `delegate ${index + 1}/${delegateTotal}: retrospective retry ${childRetrospectiveAttempt}/${retrospectiveRetriesFromEnv} (${cause})`,
+                                                cwd: childCwd,
+                                                activeTool: undefined,
+                                                delegateIndex: index + 1,
+                                                delegateTotal,
+                                                delegateDescription: request.description,
+                                                delegateProfile: childProfileLabel,
+                                                delegateItems,
+                                            });
                                         }
-                                        childRetrospectiveAttempt += 1;
-                                        retrospectiveAttempts += 1;
-                                        const directive = buildRetrospectiveDirective({
-                                            cause,
-                                            errorMessage: message,
-                                            attempt: childRetrospectiveAttempt,
-                                            target: "delegate",
-                                        });
-                                        childPromptForAttempt = `${delegatePrompt}\n\n${directive}`;
-                                        emitProgress({
-                                            kind: "subagent_progress",
-                                            phase: "running",
-                                            message: `delegate ${index + 1}/${delegateTotal}: retrospective retry ${childRetrospectiveAttempt}/${retrospectiveRetriesFromEnv} (${cause})`,
-                                            cwd: childCwd,
-                                            activeTool: undefined,
-                                            delegateIndex: index + 1,
-                                            delegateTotal,
-                                            delegateDescription: request.description,
-                                            delegateProfile: childProfileLabel,
-                                            delegateItems,
-                                        });
                                     }
+                                };
+                                childOutput = await runChildPass(delegatePrompt);
+                                let parsedChildDelegation = parseDelegationRequests(childOutput, effectiveDelegationDepth > 1 ? effectiveMaxDelegations : 0);
+                                if (childMinDelegationsPreferred > 0 &&
+                                    parsedChildDelegation.requests.length < childMinDelegationsPreferred) {
+                                    emitProgress({
+                                        kind: "subagent_progress",
+                                        phase: "running",
+                                        message: `delegate ${index + 1}/${delegateTotal}: nested delegation preference unmet (${parsedChildDelegation.requests.length}/${childMinDelegationsPreferred}), retrying with stronger split guidance`,
+                                        cwd: childCwd,
+                                        activeTool: undefined,
+                                        delegateIndex: index + 1,
+                                        delegateTotal,
+                                        delegateDescription: request.description,
+                                        delegateProfile: childProfileLabel,
+                                        delegateItems,
+                                    });
+                                    const enforcedChildPrompt = [
+                                        delegatePrompt,
+                                        "",
+                                        "[DELEGATION_ENFORCEMENT]",
+                                        `This delegated workstream must emit at least ${childMinDelegationsPreferred} <delegate_task> blocks for independent sub-work when beneficial.`,
+                                        `Target parallel fan-out: up to ${Math.min(effectiveMaxDelegateParallel, effectiveMaxDelegations)}.`,
+                                        "For broad audits or implementations, split by subsystem / file cluster / verification stream instead of doing everything in one pass.",
+                                        "If safe decomposition is impossible, output exactly one line:",
+                                        "DELEGATION_IMPOSSIBLE: <reason>",
+                                        "[/DELEGATION_ENFORCEMENT]",
+                                    ].join("\n");
+                                    childOutput = await runChildPass(enforcedChildPrompt);
+                                    parsedChildDelegation = parseDelegationRequests(childOutput, effectiveDelegationDepth > 1 ? effectiveMaxDelegations : 0);
+                                }
+                                if (childMinDelegationsPreferred > 0 &&
+                                    parsedChildDelegation.requests.length < childMinDelegationsPreferred) {
+                                    const impossibleReason = childOutput.match(/^\s*DELEGATION_IMPOSSIBLE\s*:\s*(.+)$/im)?.[1]?.trim() ??
+                                        "not provided";
+                                    delegationWarnings.push(`Child ${index + 1}: delegation fallback (preferred >=${childMinDelegationsPreferred}, got ${parsedChildDelegation.requests.length}). Reason: ${impossibleReason}.`);
                                 }
-                                const parsedChildDelegation = parseDelegationRequests(childOutput, 0);
                                 childOutput = parsedChildDelegation.cleanedOutput;
                                 delegationWarnings.push(...parsedChildDelegation.warnings.map((warning) => `Child ${index + 1}: ${warning}`));
+                                let nestedSection = "";
+                                if (parsedChildDelegation.requests.length > 0 && effectiveDelegationDepth > 1) {
+                                    const nested = await executeNestedDelegates(parsedChildDelegation.requests, childCwd, effectiveDelegationDepth - 1, `${index + 1}.`);
+                                    delegationWarnings.push(...nested.warnings);
+                                    if (nested.sections.length > 0) {
+                                        nestedSection = `\n\n##### Nested Delegated Subtasks\n\n${nested.sections.join("\n\n")}`;
+                                    }
+                                }
                                 delegatedSucceeded += 1;
                                 if (delegateItems[index]) {
                                     delegateItems[index].status = "done";
@@ -1250,7 +1505,7 @@ export function createTaskTool(cwd, runner, options) {
                                     ? `${normalizedChildOutput.slice(0, Math.max(1, maxDelegatedOutputCharsFromEnv - 3))}...`
                                     : normalizedChildOutput;
                                 delegatedSections[index] =
-                                    `#### ${index + 1}. ${request.description} (${childProfileLabel})\n${childOutputExcerpt}`;
+                                    `#### ${index + 1}. ${request.description} (${childProfileLabel})\n${childOutputExcerpt}${nestedSection}`;
                                 emitProgress({
                                     kind: "subagent_progress",
                                     phase: "running",