iosm-cli 0.2.0 → 0.2.1

package/dist/core/tools/task.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 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";
 const taskSchema = Type.Object({
     description: Type.String({
         description: "Short 3-5 word description of what the subagent will do",
@@ -13,16 +14,8 @@ const taskSchema = Type.Object({
     agent: Type.Optional(Type.String({
         description: "Optional custom subagent name loaded from .iosm/agents or global agents directory.",
     })),
-    profile: Type.Union([
-        Type.Literal("explore"),
-        Type.Literal("plan"),
-        Type.Literal("iosm"),
-        Type.Literal("iosm_analyst"),
-        Type.Literal("iosm_verifier"),
-        Type.Literal("cycle_planner"),
-        Type.Literal("full"),
-    ], {
-        description: "Subagent capability profile: explore (read-only), plan (read + bash, no edits), iosm (full tools + IOSM methodology), iosm_analyst (read + bash for IOSM artifacts), iosm_verifier (artifact-focused checks), cycle_planner (cycle planning), full (all tools)",
+    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`.",
     }),
     cwd: Type.Optional(Type.String({
         description: "Optional working directory for this subagent. Relative paths are resolved from the current workspace.",
@@ -31,10 +24,10 @@ const taskSchema = Type.Object({
         description: "Optional logical lock key for write serialization (e.g. src/api/**). Agents with the same lock key run write phases sequentially.",
     })),
     run_id: Type.Optional(Type.String({
-        description: "Optional orchestration run id (from /orchestrate). Use with task_id so the team board can track status.",
+        description: "Optional orchestration run id (from /orchestrate or /swarm). Use with task_id so the team board can track status. When omitted, task mode uses an internal run id for shared-memory collaboration within this task execution.",
     })),
     task_id: Type.Optional(Type.String({
-        description: "Optional orchestration task id (for example task_1). Use with run_id to update the team board.",
+        description: "Optional orchestration task id (for example task_1). Use with run_id to update the team board. When omitted, task mode uses an internal task id so task-scoped shared memory still works.",
     })),
     model: Type.Optional(Type.String({
         description: "Optional model override for this subagent (for example anthropic/claude-sonnet-4 or model id).",
@@ -45,6 +38,11 @@ const taskSchema = Type.Object({
     isolation: Type.Optional(Type.Union([Type.Literal("none"), Type.Literal("worktree")], {
         description: "Optional isolation mode. Set to worktree to run this subagent in a temporary git worktree.",
     })),
+    delegate_parallel_hint: Type.Optional(Type.Integer({
+        minimum: 1,
+        maximum: 10,
+        description: "Optional hint for intra-task delegation fan-out. Higher value allows more delegated subtasks to run in parallel inside a single task execution.",
+    })),
 });
 /** Tool names available per profile */
 const toolsByProfile = {
@@ -94,6 +92,9 @@ class Semaphore {
             next();
         }
     }
+    isIdle() {
+        return this.active === 0 && this.queue.length === 0;
+    }
 }
 class Mutex {
     constructor() {
@@ -116,12 +117,19 @@ class Mutex {
             next();
         }
     }
+    isIdle() {
+        return !this.locked && this.waiters.length === 0;
+    }
 }
-const maxParallelFromEnv = Number.parseInt(process.env.IOSM_SUBAGENT_MAX_PARALLEL ?? "4", 10);
-const subagentSemaphore = new Semaphore(Number.isInteger(maxParallelFromEnv) && maxParallelFromEnv > 0 ? Math.min(maxParallelFromEnv, 20) : 4);
+const maxParallelFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_PARALLEL, 20, 1, 20);
+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, 2, 0, 10);
-const maxDelegatedParallelFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_MAX_DELEGATE_PARALLEL, 4, 1, 10);
+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 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);
+const orchestrationDependencyPollMsFromEnv = parseBoundedInt(process.env.IOSM_ORCHESTRATION_DEPENDENCY_POLL_MS, 150, 50, 2_000);
 const maxDelegatedOutputCharsFromEnv = parseBoundedInt(process.env.IOSM_SUBAGENT_DELEGATED_OUTPUT_MAX_CHARS, 6000, 500, 20_000);
 const maxMetaUpdatesPerCheckpoint = parseBoundedInt(process.env.IOSM_SUBAGENT_META_MAX_ITEMS, 5, 1, 20);
 const maxMetaUpdateChars = parseBoundedInt(process.env.IOSM_SUBAGENT_META_MAX_CHARS, 600, 100, 4000);
@@ -133,6 +141,65 @@ 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 deriveAutoDelegateParallelHint(agentName, description, prompt) {
+    if (!shouldAutoDelegateByAgent(agentName))
+        return undefined;
+    const text = `${description}\n${prompt}`.trim();
+    if (!text)
+        return 1;
+    const normalized = text.replace(/\s+/g, " ").trim();
+    const words = normalized.length > 0 ? normalized.split(/\s+/).length : 0;
+    const clauses = normalized
+        .split(/[.;:,\n]+/g)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0).length;
+    const pathLikeMatches = normalized.match(/\b(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\b/g) ?? [];
+    const fileLikeMatches = normalized.match(/\b[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,8}\b/g) ?? [];
+    const listMarkers = text.match(/(?:^|\n)\s*(?:[-*]|\d+[.)])\s+/g)?.length ?? 0;
+    const hasCodeBlock = text.includes("```");
+    let score = 0;
+    if (words >= 40) {
+        score += 2;
+    }
+    else if (words >= 20) {
+        score += 1;
+    }
+    if (clauses >= 5) {
+        score += 2;
+    }
+    else if (clauses >= 3) {
+        score += 1;
+    }
+    if (listMarkers >= 2) {
+        score += 1;
+    }
+    const referenceCount = pathLikeMatches.length + fileLikeMatches.length;
+    if (referenceCount >= 3 || (referenceCount >= 1 && words >= 20)) {
+        score += 1;
+    }
+    if (hasCodeBlock) {
+        score += 1;
+    }
+    if (score >= 6)
+        return 10;
+    if (score >= 5)
+        return 8;
+    if (score >= 4)
+        return 6;
+    if (score >= 3)
+        return 4;
+    if (score >= 2)
+        return 3;
+    if (score >= 1)
+        return 2;
+    return 1;
+}
 function normalizeSpacing(text) {
     return text.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -172,7 +239,16 @@ function isAbortError(error) {
     }
     return false;
 }
-function buildDelegationProtocolPrompt(depthRemaining) {
+function mergeRunStats(base, next) {
+    if (!base && !next)
+        return undefined;
+    return {
+        toolCallsStarted: (base?.toolCallsStarted ?? 0) + (next?.toolCallsStarted ?? 0),
+        toolCallsCompleted: (base?.toolCallsCompleted ?? 0) + (next?.toolCallsCompleted ?? 0),
+        assistantMessages: (base?.assistantMessages ?? 0) + (next?.assistantMessages ?? 0),
+    };
+}
+function buildDelegationProtocolPrompt(depthRemaining, maxDelegations) {
     if (depthRemaining <= 0) {
         return [
             `Delegation protocol: depth limit reached.`,
@@ -180,17 +256,31 @@ function buildDelegationProtocolPrompt(depthRemaining) {
         ].join("\n");
     }
     return [
-        `Delegation protocol (optional): if you discover a concrete follow-up that is better done by a separate specialist, emit up to ${maxDelegationsPerTaskFromEnv} XML block(s):`,
-        `<${delegationTagName} profile="explore|plan|iosm|iosm_analyst|iosm_verifier|cycle_planner|full" 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">`,
+        `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">`,
         "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) {
-    const protocol = buildDelegationProtocolPrompt(depthRemaining);
+function withDelegationPrompt(basePrompt, depthRemaining, maxDelegations) {
+    const protocol = buildDelegationProtocolPrompt(depthRemaining, maxDelegations);
     return `${basePrompt}\n\n${protocol}`;
 }
+function buildSharedMemoryGuidance(runId, taskId) {
+    return [
+        "[SHARED_MEMORY]",
+        `run_id: ${runId}`,
+        `task_id: ${taskId ?? "(none)"}`,
+        "Use shared_memory_write/shared_memory_read to exchange intermediate state across parallel agents and delegates.",
+        "Guidelines:",
+        "- Use scope=run for cross-agent data and scope=task for task-local notes.",
+        "- Keep entries compact and key-based (for example: findings/auth, plan/step-1, risks/session).",
+        "- Read before overwrite when collaborating on the same key.",
+        "[/SHARED_MEMORY]",
+    ].join("\n");
+}
 function parseDelegationRequests(output, maxRequests) {
     const requests = [];
     const warnings = [];
@@ -227,6 +317,7 @@ function parseDelegationRequests(output, maxRequests) {
         requests.push({
             description: (attrs.description ?? `delegated task ${requests.length + 1}`).trim(),
             profile,
+            agent: attrs.agent?.trim() || undefined,
             prompt,
             cwd: attrs.cwd?.trim() || undefined,
             lockKey: attrs.lock_key?.trim() || undefined,
@@ -260,6 +351,15 @@ function getOrCreateWriteLock(cwd) {
     cwdWriteLocks.set(key, created);
     return created;
 }
+function cleanupWriteLock(lockKey) {
+    if (!lockKey)
+        return;
+    const key = getCwdLockKey(lockKey);
+    const existing = cwdWriteLocks.get(key);
+    if (!existing || !existing.isIdle())
+        return;
+    cwdWriteLocks.delete(key);
+}
 function getRunParallelLimit(cwd, runId) {
     const teamRun = getTeamRun(cwd, runId);
     if (!teamRun)
@@ -284,6 +384,91 @@ function getOrCreateOrchestrationSemaphore(cwd, runId) {
     orchestrationSemaphores.set(key, created);
     return created;
 }
+function isTeamTaskTerminal(status) {
+    return status === "done" || status === "error" || status === "cancelled";
+}
+function cleanupOrchestrationSemaphore(cwd, runId) {
+    const prefix = `${path.resolve(cwd).toLowerCase()}::${runId}::`;
+    const run = getTeamRun(cwd, runId);
+    const canDeleteForRun = !run || run.tasks.every((task) => isTeamTaskTerminal(task.status));
+    if (!canDeleteForRun)
+        return;
+    for (const [key, semaphore] of orchestrationSemaphores.entries()) {
+        if (!key.startsWith(prefix))
+            continue;
+        if (!semaphore.isIdle())
+            continue;
+        orchestrationSemaphores.delete(key);
+    }
+}
+function waitForWithAbort(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    if (signal.aborted) {
+        return Promise.reject(new Error("Operation aborted"));
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            reject(new Error("Operation aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function waitForOrchestrationDependencies(input) {
+    const started = Date.now();
+    let lastWaiting = "";
+    while (true) {
+        if (input.signal?.aborted) {
+            throw new Error("Operation aborted");
+        }
+        const run = getTeamRun(input.cwd, input.runId);
+        if (!run) {
+            return;
+        }
+        const current = run.tasks.find((task) => task.id === input.taskId);
+        if (!current) {
+            throw new Error(`Orchestration metadata missing task ${input.taskId} in run ${input.runId}.`);
+        }
+        const dependencies = current.dependsOn ?? [];
+        if (dependencies.length === 0) {
+            return;
+        }
+        const dependencyTasks = dependencies.map((id) => run.tasks.find((task) => task.id === id));
+        const missing = dependencyTasks
+            .map((task, index) => (task ? undefined : dependencies[index]))
+            .filter((value) => typeof value === "string");
+        if (missing.length > 0) {
+            throw new Error(`Orchestration metadata invalid for ${input.taskId}: missing dependency task(s) ${missing.join(", ")}.`);
+        }
+        const failed = dependencyTasks.filter((task) => !!task && (task.status === "error" || task.status === "cancelled"));
+        if (failed.length > 0) {
+            throw new Error(`Blocked by failed dependency: ${failed.map((task) => `${task.id}=${task.status}`).join(", ")}.`);
+        }
+        const pending = dependencyTasks.filter((task) => !!task && task.status !== "done");
+        if (pending.length === 0) {
+            return;
+        }
+        const waitedMs = Date.now() - started;
+        if (waitedMs >= orchestrationDependencyWaitTimeoutMsFromEnv) {
+            throw new Error(`Timed out waiting for dependencies of ${input.taskId}: ${pending
+                .map((task) => `${task.id}=${task.status}`)
+                .join(", ")}.`);
+        }
+        const waiting = pending.map((task) => `${task.id}=${task.status}`).join(", ");
+        if (waiting !== lastWaiting) {
+            lastWaiting = waiting;
+            input.onWaiting?.(waiting);
+        }
+        await waitForWithAbort(orchestrationDependencyPollMsFromEnv, input.signal);
+    }
+}
 function persistSubagentTranscript(input) {
     try {
         const dir = path.join(input.rootCwd, ".iosm", "subagents", "runs");
@@ -408,21 +593,54 @@ export function createTaskTool(cwd, runner, options) {
             "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, }, _signal, onUpdate) => {
+        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) => {
+            const updateTrackedTaskStatus = (status) => {
+                if (!orchestrationRunId || !orchestrationTaskId)
+                    return;
+                updateTeamTaskStatus({
+                    cwd,
+                    runId: orchestrationRunId,
+                    taskId: orchestrationTaskId,
+                    status,
+                });
+            };
             const throwIfAborted = () => {
                 if (_signal?.aborted) {
+                    updateTrackedTaskStatus("cancelled");
                     throw new Error("Operation aborted");
                 }
             };
             const runId = `subagent_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-            const customSubagent = agentName && options?.resolveCustomSubagent ? options.resolveCustomSubagent(agentName) : undefined;
-            if (agentName && !customSubagent) {
-                const available = options?.availableCustomSubagents && options.availableCustomSubagents.length > 0
-                    ? ` Available custom agents: ${options.availableCustomSubagents.join(", ")}.`
-                    : "";
-                throw new Error(`Unknown subagent: ${agentName}.${available}`);
+            const sharedMemoryRunId = orchestrationRunId?.trim() || runId;
+            const sharedMemoryTaskId = orchestrationTaskId?.trim() || runId;
+            const availableCustomNames = options?.availableCustomSubagents ?? [];
+            const resolveCustom = (name) => {
+                if (!name || !options?.resolveCustomSubagent)
+                    return undefined;
+                return options.resolveCustomSubagent(name);
+            };
+            let normalizedAgentName = agentName?.trim() || undefined;
+            let normalizedProfile = profile.trim().toLowerCase();
+            if (!normalizedProfile)
+                normalizedProfile = "full";
+            let customSubagent = resolveCustom(normalizedAgentName);
+            if (normalizedAgentName && !customSubagent) {
+                const available = availableCustomNames.length > 0 ? ` Available custom agents: ${availableCustomNames.join(", ")}.` : "";
+                throw new Error(`Unknown subagent: ${normalizedAgentName}.${available}`);
             }
-            const effectiveProfile = customSubagent?.profile ?? profile;
+            // Recovery path: if model placed a custom agent name into `profile`, remap automatically.
+            if (!customSubagent) {
+                const profileAsAgent = resolveCustom(normalizedProfile);
+                if (profileAsAgent) {
+                    customSubagent = profileAsAgent;
+                    normalizedAgentName = profileAsAgent.name;
+                    normalizedProfile = (profileAsAgent.profile ?? "full").trim().toLowerCase();
+                }
+            }
+            if (!toolsByProfile[normalizedProfile]) {
+                normalizedProfile = "full";
+            }
+            const effectiveProfile = customSubagent?.profile ?? normalizedProfile;
             let tools = customSubagent?.tools
                 ? [...customSubagent.tools]
                 : [...(toolsByProfile[effectiveProfile] ?? toolsByProfile.explore)];
@@ -431,10 +649,22 @@ export function createTaskTool(cwd, runner, options) {
                 tools = tools.filter((tool) => !blocked.has(tool));
             }
             const delegationDepth = maxDelegationDepthFromEnv;
+            const requestedDelegateParallelHint = typeof delegateParallelHint === "number" && Number.isInteger(delegateParallelHint)
+                ? Math.max(1, Math.min(10, delegateParallelHint))
+                : undefined;
+            const autoDelegateParallelHint = requestedDelegateParallelHint === undefined
+                ? deriveAutoDelegateParallelHint(normalizedAgentName, 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));
+            const minDelegationsPreferred = (effectiveDelegateParallelHint ?? 0) >= 2 && effectiveMaxDelegations >= 2
+                ? Math.min(2, effectiveMaxDelegations)
+                : 0;
             const baseSystemPrompt = customSubagent?.systemPrompt ??
                 systemPromptByProfile[effectiveProfile] ??
                 systemPromptByProfile.full;
-            const systemPrompt = withDelegationPrompt(baseSystemPrompt, delegationDepth);
+            const systemPrompt = withDelegationPrompt(baseSystemPrompt, delegationDepth, effectiveMaxDelegations);
             const promptWithInstructions = customSubagent?.instructions && customSubagent.instructions.trim().length > 0
                 ? `${customSubagent.instructions.trim()}\n\nUser task:\n${prompt}`
                 : prompt;
@@ -503,11 +733,57 @@ export function createTaskTool(cwd, runner, options) {
                 let releaseSlot;
                 let releaseWriteLock;
                 let releaseIsolation;
+                const explicitRootLockKey = lockKey?.trim();
                 let subagentCwd = requestedSubagentCwd;
                 let worktreePath;
                 let runStats;
                 try {
                     throwIfAborted();
+                    if (orchestrationRunId && orchestrationTaskId) {
+                        try {
+                            await waitForOrchestrationDependencies({
+                                cwd,
+                                runId: orchestrationRunId,
+                                taskId: orchestrationTaskId,
+                                signal: _signal,
+                                onWaiting: (waiting) => {
+                                    emitProgress({
+                                        kind: "subagent_progress",
+                                        phase: "queued",
+                                        message: `waiting for dependencies: ${waiting}`,
+                                        cwd: requestedSubagentCwd,
+                                        activeTool: undefined,
+                                    });
+                                },
+                            });
+                        }
+                        catch (error) {
+                            if (_signal?.aborted || isAbortError(error)) {
+                                updateTrackedTaskStatus("cancelled");
+                                throw new Error("Operation aborted");
+                            }
+                            const message = error instanceof Error ? error.message : String(error);
+                            const cause = classifyFailureCause(message);
+                            updateTrackedTaskStatus("error");
+                            const details = {
+                                profile: effectiveProfile,
+                                description,
+                                outputLength: 0,
+                                cwd: requestedSubagentCwd,
+                                agent: customSubagent?.name,
+                                lockKey: lockKey?.trim() || undefined,
+                                runId,
+                                taskId: orchestrationTaskId,
+                                model: effectiveModelOverride,
+                                isolation: useWorktree ? "worktree" : "none",
+                                worktreePath,
+                                waitMs: Date.now() - queuedAt,
+                                background: runInBackground,
+                                failureCauses: { [cause]: 1 },
+                            };
+                            throw Object.assign(new Error(`Subagent failed: ${message}`), { details });
+                        }
+                    }
                     const orchestrationSemaphore = orchestrationRunId && orchestrationTaskId
                         ? getOrCreateOrchestrationSemaphore(cwd, orchestrationRunId)
                         : undefined;
@@ -517,20 +793,12 @@ export function createTaskTool(cwd, runner, options) {
                     }
                     releaseSlot = await subagentSemaphore.acquire();
                     throwIfAborted();
-                    if (orchestrationRunId && orchestrationTaskId) {
-                        updateTeamTaskStatus({
-                            cwd,
-                            runId: orchestrationRunId,
-                            taskId: orchestrationTaskId,
-                            status: "running",
-                        });
-                    }
+                    updateTrackedTaskStatus("running");
                     if (writeCapableProfiles.has(effectiveProfile)) {
-                        const explicitLockKey = lockKey?.trim();
                         // Parallel orchestration should remain truly parallel by default.
                         // Serialize write-capable agents only when an explicit lock_key is provided.
-                        if (explicitLockKey) {
-                            const lock = getOrCreateWriteLock(explicitLockKey);
+                        if (explicitRootLockKey) {
+                            const lock = getOrCreateWriteLock(explicitRootLockKey);
                             releaseWriteLock = await lock.acquire();
                         }
                     }
@@ -552,18 +820,115 @@ export function createTaskTool(cwd, runner, options) {
                     let delegatedTasks = 0;
                     let delegatedSucceeded = 0;
                     let delegatedFailed = 0;
+                    let retrospectiveAttempts = 0;
+                    let retrospectiveRecovered = 0;
                     const delegationWarnings = [];
                     const delegatedSections = [];
+                    const failureCauses = {};
                     const delegatedStats = {
                         toolCallsStarted: 0,
                         toolCallsCompleted: 0,
                         assistantMessages: 0,
                     };
+                    const recordFailureCause = (cause) => {
+                        failureCauses[cause] = (failureCauses[cause] ?? 0) + 1;
+                    };
+                    const rootSharedMemoryContext = {
+                        rootCwd: cwd,
+                        runId: sharedMemoryRunId,
+                        taskId: sharedMemoryTaskId,
+                        profile: effectiveProfile,
+                    };
                     try {
+                        const runRootPass = async (runPrompt) => {
+                            let emptyAttempt = 0;
+                            let retrospectiveAttempt = 0;
+                            let mergedStats;
+                            let sessionId;
+                            let promptForAttempt = runPrompt;
+                            while (true) {
+                                try {
+                                    const result = await runner({
+                                        systemPrompt,
+                                        tools,
+                                        prompt: promptForAttempt,
+                                        cwd: subagentCwd,
+                                        modelOverride: effectiveModelOverride,
+                                        sharedMemoryContext: rootSharedMemoryContext,
+                                        signal: _signal,
+                                        onProgress: (progress) => emitProgress(progress),
+                                    });
+                                    throwIfAborted();
+                                    let attemptOutput;
+                                    let attemptStats;
+                                    if (typeof result === "string") {
+                                        attemptOutput = result;
+                                    }
+                                    else {
+                                        attemptOutput = result.output;
+                                        attemptStats = result.stats;
+                                        sessionId = result.sessionId ?? sessionId;
+                                    }
+                                    mergedStats = mergeRunStats(mergedStats, attemptStats);
+                                    if (attemptOutput.trim().length > 0) {
+                                        if (retrospectiveAttempt > 0) {
+                                            retrospectiveRecovered += 1;
+                                        }
+                                        return {
+                                            output: attemptOutput,
+                                            sessionId,
+                                            stats: mergedStats,
+                                        };
+                                    }
+                                    if (emptyAttempt >= emptyOutputRetriesFromEnv) {
+                                        const totalAttempts = emptyAttempt + 1;
+                                        throw new Error(`Subagent returned empty output after ${totalAttempts} attempt${totalAttempts === 1 ? "" : "s"}.`);
+                                    }
+                                    emptyAttempt += 1;
+                                    emitProgress({
+                                        kind: "subagent_progress",
+                                        phase: "running",
+                                        message: `root subagent returned empty output; retry ${emptyAttempt}/${emptyOutputRetriesFromEnv}`,
+                                        cwd: subagentCwd,
+                                        activeTool: undefined,
+                                    });
+                                }
+                                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 = retrospectiveAttempt < retrospectiveRetriesFromEnv && isRetrospectiveRetryable(cause);
+                                    if (!canRetryRetrospective) {
+                                        throw Object.assign(new Error(message), { failureCause: cause });
+                                    }
+                                    retrospectiveAttempt += 1;
+                                    retrospectiveAttempts += 1;
+                                    const directive = buildRetrospectiveDirective({
+                                        cause,
+                                        errorMessage: message,
+                                        attempt: retrospectiveAttempt,
+                                        target: "root",
+                                    });
+                                    promptForAttempt = `${runPrompt}\n\n${directive}`;
+                                    emitProgress({
+                                        kind: "subagent_progress",
+                                        phase: "running",
+                                        message: `root retrospective retry ${retrospectiveAttempt}/${retrospectiveRetriesFromEnv} (${cause})`,
+                                        cwd: subagentCwd,
+                                        activeTool: undefined,
+                                    });
+                                }
+                            }
+                        };
                         const rootMeta = formatMetaCheckpoint(options?.getMetaMessages?.());
+                        const rootSharedMemoryGuidance = buildSharedMemoryGuidance(sharedMemoryRunId, sharedMemoryTaskId);
+                        const rootPromptBase = `${promptWithInstructions}\n\n${rootSharedMemoryGuidance}`;
                         const rootPrompt = rootMeta.section && rootMeta.appliedCount > 0
-                            ? `${promptWithInstructions}\n\n${rootMeta.section}`
-                            : promptWithInstructions;
+                            ? `${rootPromptBase}\n\n${rootMeta.section}`
+                            : rootPromptBase;
                         if (rootMeta.appliedCount > 0) {
                             emitProgress({
                                 kind: "subagent_progress",
@@ -573,25 +938,39 @@ export function createTaskTool(cwd, runner, options) {
                                 activeTool: undefined,
                             });
                         }
-                        const result = await runner({
-                            systemPrompt,
-                            tools,
-                            prompt: rootPrompt,
-                            cwd: subagentCwd,
-                            modelOverride: effectiveModelOverride,
-                            signal: _signal,
-                            onProgress: (progress) => emitProgress(progress),
-                        });
-                        throwIfAborted();
-                        if (typeof result === "string") {
-                            output = result;
+                        const firstPass = await runRootPass(rootPrompt);
+                        output = firstPass.output;
+                        subagentSessionId = firstPass.sessionId;
+                        runStats = firstPass.stats;
+                        let parsedDelegation = parseDelegationRequests(output, delegationDepth > 0 ? effectiveMaxDelegations : 0);
+                        if (minDelegationsPreferred > 0 && parsedDelegation.requests.length < minDelegationsPreferred) {
+                            emitProgress({
+                                kind: "subagent_progress",
+                                phase: "running",
+                                message: `delegation preference unmet (${parsedDelegation.requests.length}/${minDelegationsPreferred}), retrying with stronger split guidance`,
+                                cwd: subagentCwd,
+                                activeTool: undefined,
+                            });
+                            const enforcedPrompt = [
+                                rootPrompt,
+                                "",
+                                "[DELEGATION_ENFORCEMENT]",
+                                `Prefer emitting at least ${minDelegationsPreferred} <delegate_task> blocks for independent sub-work when beneficial.`,
+                                `Target parallel fan-out: up to ${effectiveMaxDelegateParallel}.`,
+                                "If decomposition is not beneficial, you may keep single-agent execution and optionally output one line:",
+                                "DELEGATION_IMPOSSIBLE: <reason>",
+                                "[/DELEGATION_ENFORCEMENT]",
+                            ].join("\n");
+                            const secondPass = await runRootPass(enforcedPrompt);
+                            output = secondPass.output;
+                            subagentSessionId = secondPass.sessionId ?? subagentSessionId;
+                            runStats = secondPass.stats ?? runStats;
+                            parsedDelegation = parseDelegationRequests(output, delegationDepth > 0 ? effectiveMaxDelegations : 0);
                         }
-                        else {
-                            output = result.output;
-                            subagentSessionId = result.sessionId;
-                            runStats = result.stats;
+                        if (minDelegationsPreferred > 0 && parsedDelegation.requests.length < minDelegationsPreferred) {
+                            const impossibleReason = output.match(/^\s*DELEGATION_IMPOSSIBLE\s*:\s*(.+)$/im)?.[1]?.trim() ?? "not provided";
+                            delegationWarnings.push(`Delegation fallback: kept single-agent execution (preferred >=${minDelegationsPreferred} delegates, got ${parsedDelegation.requests.length}). Reason: ${impossibleReason}.`);
                         }
-                        const parsedDelegation = parseDelegationRequests(output, delegationDepth > 0 ? maxDelegationsPerTaskFromEnv : 0);
                         output = parsedDelegation.cleanedOutput;
                         delegationWarnings.push(...parsedDelegation.warnings);
                         const delegateTotal = parsedDelegation.requests.length;
@@ -619,7 +998,7 @@ export function createTaskTool(cwd, runner, options) {
                             emitProgress({
                                 kind: "subagent_progress",
                                 phase: "running",
-                                message: `delegation scheduler: ${delegateTotal} task(s), max parallel ${Math.min(delegateTotal, maxDelegatedParallelFromEnv)}`,
+                                message: `delegation scheduler: ${delegateTotal} task(s), max parallel ${Math.min(delegateTotal, effectiveMaxDelegateParallel)}`,
                                 cwd: subagentCwd,
                                 activeTool: undefined,
                                 delegateTotal,
@@ -628,19 +1007,23 @@ export function createTaskTool(cwd, runner, options) {
                         }
                         const pendingIndices = new Set(Array.from({ length: delegateTotal }, (_v, i) => i));
                         const runningDelegates = new Map();
-                        const maxDelegateParallel = Math.max(1, Math.min(delegateTotal || 1, maxDelegatedParallelFromEnv));
+                        const maxDelegateParallel = Math.max(1, Math.min(delegateTotal || 1, effectiveMaxDelegateParallel));
                         const statusOf = (idx) => delegateItems[idx]?.status ?? "pending";
-                        const markDelegateFailed = (index, message, details) => {
+                        const formatDelegateTarget = (request) => {
+                            const agent = request.agent?.trim();
+                            return agent ? `${agent}/${request.profile}` : request.profile;
+                        };
+                        const markDelegateFailed = (index, message, details, cause) => {
                             const request = parsedDelegation.requests[index];
                             if (delegateItems[index]) {
                                 delegateItems[index].status = "failed";
                             }
                             delegatedFailed += 1;
                             if (details) {
-                                delegationWarnings.push(details);
+                                delegationWarnings.push(cause ? `${details} [cause=${cause}]` : details);
                             }
-                            delegatedSections[index] =
-                                `#### ${index + 1}. ${request.description} (${request.profile})\nERROR: ${message}`;
+                            const causeLabel = cause ? ` [cause=${cause}]` : "";
+                            delegatedSections[index] = `#### ${index + 1}. ${request.description} (${formatDelegateTarget(request)})\nERROR${causeLabel}: ${message}`;
                             emitProgress({
                                 kind: "subagent_progress",
                                 phase: "running",
@@ -657,7 +1040,19 @@ export function createTaskTool(cwd, runner, options) {
                         const runDelegate = async (index) => {
                             throwIfAborted();
                             const request = parsedDelegation.requests[index];
-                            const childProfile = request.profile;
+                            const requestedChildAgent = request.agent?.trim() || undefined;
+                            const childCustomSubagent = resolveCustom(requestedChildAgent);
+                            if (requestedChildAgent && !childCustomSubagent) {
+                                delegationWarnings.push(`Delegated task "${request.description}" requested unknown agent "${requestedChildAgent}". Falling back to profile "${request.profile}".`);
+                            }
+                            const childProfileRaw = childCustomSubagent?.profile ?? request.profile;
+                            const normalizedChildProfile = childProfileRaw.trim().toLowerCase();
+                            const childProfile = normalizedChildProfile && toolsByProfile[normalizedChildProfile]
+                                ? normalizedChildProfile
+                                : "full";
+                            const childProfileLabel = childCustomSubagent?.name
+                                ? `${childCustomSubagent.name}/${childProfile}`
+                                : childProfile;
                             if (delegateItems[index]) {
                                 delegateItems[index].status = "running";
                             }
@@ -670,23 +1065,34 @@ export function createTaskTool(cwd, runner, options) {
                                 delegateIndex: index + 1,
                                 delegateTotal,
                                 delegateDescription: request.description,
-                                delegateProfile: childProfile,
+                                delegateProfile: childProfileLabel,
                                 delegateItems,
                             });
-                            const childTools = [...(toolsByProfile[childProfile] ?? toolsByProfile.explore)];
-                            const childBaseSystemPrompt = systemPromptByProfile[childProfile] ?? systemPromptByProfile.full;
-                            const childSystemPrompt = withDelegationPrompt(childBaseSystemPrompt, Math.max(0, delegationDepth - 1));
-                            const requestedChildCwd = request.cwd ? path.resolve(subagentCwd, request.cwd) : subagentCwd;
+                            let childTools = childCustomSubagent?.tools
+                                ? [...childCustomSubagent.tools]
+                                : [...(toolsByProfile[childProfile] ?? toolsByProfile.explore)];
+                            if (childCustomSubagent?.disallowedTools?.length) {
+                                const blocked = new Set(childCustomSubagent.disallowedTools);
+                                childTools = childTools.filter((tool) => !blocked.has(tool));
+                            }
+                            const childBaseSystemPrompt = childCustomSubagent?.systemPrompt ??
+                                systemPromptByProfile[childProfile] ??
+                                systemPromptByProfile.full;
+                            const childSystemPrompt = withDelegationPrompt(childBaseSystemPrompt, Math.max(0, delegationDepth - 1), effectiveMaxDelegations);
+                            const requestedChildCwd = request.cwd
+                                ? path.resolve(subagentCwd, request.cwd)
+                                : childCustomSubagent?.cwd ?? subagentCwd;
                             if (!existsSync(requestedChildCwd) || !statSync(requestedChildCwd).isDirectory()) {
-                                markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} skipped: missing cwd`, `Delegated task "${request.description}" skipped: cwd does not exist (${requestedChildCwd}).`);
+                                recordFailureCause("dependency_env");
+                                markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} skipped: missing cwd`, `Delegated task "${request.description}" skipped: cwd does not exist (${requestedChildCwd}).`, "dependency_env");
                                 return;
                             }
                             let childReleaseLock;
                             let childReleaseIsolation;
+                            const explicitChildLock = request.lockKey?.trim();
                             let childCwd = requestedChildCwd;
                             try {
                                 throwIfAborted();
-                                const explicitChildLock = request.lockKey?.trim();
                                 if (writeCapableProfiles.has(childProfile) && explicitChildLock) {
                                     const lock = getOrCreateWriteLock(explicitChildLock);
                                     childReleaseLock = await lock.acquire();
@@ -698,9 +1104,14 @@ export function createTaskTool(cwd, runner, options) {
                                     childReleaseIsolation = isolated.cleanup;
                                 }
                                 const delegateMeta = formatMetaCheckpoint(options?.getMetaMessages?.());
-                                const delegatePrompt = delegateMeta.section && delegateMeta.appliedCount > 0
-                                    ? `${request.prompt}\n\n${delegateMeta.section}`
+                                const childPromptWithInstructions = childCustomSubagent?.instructions && childCustomSubagent.instructions.trim().length > 0
+                                    ? `${childCustomSubagent.instructions.trim()}\n\nUser task:\n${request.prompt}`
                                     : request.prompt;
+                                const delegateSharedMemoryGuidance = buildSharedMemoryGuidance(sharedMemoryRunId, sharedMemoryTaskId);
+                                const delegatePromptBase = `${childPromptWithInstructions}\n\n${delegateSharedMemoryGuidance}`;
+                                const delegatePrompt = delegateMeta.section && delegateMeta.appliedCount > 0
+                                    ? `${delegatePromptBase}\n\n${delegateMeta.section}`
+                                    : delegatePromptBase;
                                 if (delegateMeta.appliedCount > 0) {
                                     emitProgress({
                                         kind: "subagent_progress",
@@ -711,41 +1122,118 @@ export function createTaskTool(cwd, runner, options) {
                                         delegateIndex: index + 1,
                                         delegateTotal,
                                         delegateDescription: request.description,
-                                        delegateProfile: childProfile,
+                                        delegateProfile: childProfileLabel,
                                         delegateItems,
                                     });
                                 }
-                                const childResult = await runner({
-                                    systemPrompt: childSystemPrompt,
-                                    tools: childTools,
-                                    prompt: delegatePrompt,
-                                    cwd: childCwd,
-                                    modelOverride: request.model,
-                                    signal: _signal,
-                                    onProgress: (progress) => {
+                                const childModelOverride = request.model?.trim() || childCustomSubagent?.model?.trim() || undefined;
+                                const childSharedMemoryContext = {
+                                    rootCwd: cwd,
+                                    runId: sharedMemoryRunId,
+                                    taskId: sharedMemoryTaskId,
+                                    delegateId: String(index + 1),
+                                    profile: childProfile,
+                                };
+                                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;
+                                            }
+                                            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}: ${progress.message}`,
-                                            cwd: progress.cwd ?? childCwd,
-                                            activeTool: progress.activeTool,
+                                            message: `delegate ${index + 1}/${delegateTotal}: empty output, retry ${childEmptyAttempt}/${emptyOutputRetriesFromEnv}`,
+                                            cwd: childCwd,
+                                            activeTool: undefined,
                                             delegateIndex: index + 1,
                                             delegateTotal,
                                             delegateDescription: request.description,
-                                            delegateProfile: childProfile,
+                                            delegateProfile: childProfileLabel,
                                             delegateItems,
                                         });
-                                    },
-                                });
-                                throwIfAborted();
-                                let childOutput;
-                                let childStats;
-                                if (typeof childResult === "string") {
-                                    childOutput = childResult;
-                                }
-                                else {
-                                    childOutput = childResult.output;
-                                    childStats = childResult.stats;
+                                    }
+                                    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 = `${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,
+                                        });
+                                    }
                                 }
                                 const parsedChildDelegation = parseDelegationRequests(childOutput, 0);
                                 childOutput = parsedChildDelegation.cleanedOutput;
@@ -762,7 +1250,7 @@ export function createTaskTool(cwd, runner, options) {
                                     ? `${normalizedChildOutput.slice(0, Math.max(1, maxDelegatedOutputCharsFromEnv - 3))}...`
                                     : normalizedChildOutput;
                                 delegatedSections[index] =
-                                    `#### ${index + 1}. ${request.description} (${childProfile})\n${childOutputExcerpt}`;
+                                    `#### ${index + 1}. ${request.description} (${childProfileLabel})\n${childOutputExcerpt}`;
                                 emitProgress({
                                     kind: "subagent_progress",
                                     phase: "running",
@@ -772,7 +1260,7 @@ export function createTaskTool(cwd, runner, options) {
                                     delegateIndex: index + 1,
                                     delegateTotal,
                                     delegateDescription: request.description,
-                                    delegateProfile: childProfile,
+                                    delegateProfile: childProfileLabel,
                                     delegateItems,
                                 });
                             }
@@ -781,11 +1269,18 @@ export function createTaskTool(cwd, runner, options) {
                                 if (_signal?.aborted || isAbortError(error)) {
                                     throw new Error("Operation aborted");
                                 }
-                                markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} failed`, message);
+                                const classified = error && typeof error === "object" && "failureCause" in error
+                                    ? error.failureCause
+                                    : classifyFailureCause(message);
+                                if (!(error && typeof error === "object" && "failureCause" in error)) {
+                                    recordFailureCause(classified);
+                                }
+                                markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} failed`, message, classified);
                             }
                             finally {
                                 childReleaseIsolation?.();
                                 childReleaseLock?.();
+                                cleanupWriteLock(explicitChildLock);
                             }
                         };
                         const resolveBlockedByFailedDependencies = () => {
@@ -798,7 +1293,8 @@ export function createTaskTool(cwd, runner, options) {
                                 if (!failedDep)
                                     continue;
                                 pendingIndices.delete(index);
-                                markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} skipped: dependency ${failedDep} failed`, `Delegated task ${index + 1} skipped because dependency ${failedDep} failed.`);
+                                recordFailureCause("logic_error");
+                                markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} skipped: dependency ${failedDep} failed`, `Delegated task ${index + 1} skipped because dependency ${failedDep} failed.`, "logic_error");
                                 changed = true;
                             }
                             return changed;
@@ -836,7 +1332,8 @@ export function createTaskTool(cwd, runner, options) {
                                     for (const index of Array.from(pendingIndices)) {
                                         pendingIndices.delete(index);
                                         const deps = normalizedDependsOn[index] ?? [];
-                                        markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} blocked: unresolved depends_on`, `Delegated task ${index + 1} blocked by unresolved dependencies: ${deps.join(", ") || "unknown"}.`);
+                                        recordFailureCause("logic_error");
+                                        markDelegateFailed(index, `delegate ${index + 1}/${delegateTotal} blocked: unresolved depends_on`, `Delegated task ${index + 1} blocked by unresolved dependencies: ${deps.join(", ") || "unknown"}.`, "logic_error");
                                     }
                                 }
                                 break;
@@ -847,8 +1344,45 @@ export function createTaskTool(cwd, runner, options) {
                     catch (error) {
                         const message = error instanceof Error ? error.message : String(error);
                         if (_signal?.aborted || isAbortError(error)) {
-                            throw new Error("Operation aborted");
+                            recordFailureCause("aborted");
+                            const hasFailureCauses = Object.keys(failureCauses).length > 0;
+                            const details = {
+                                profile: effectiveProfile,
+                                description,
+                                outputLength: 0,
+                                cwd: subagentCwd,
+                                agent: customSubagent?.name,
+                                lockKey: lockKey?.trim() || undefined,
+                                runId,
+                                taskId: orchestrationTaskId,
+                                model: effectiveModelOverride,
+                                isolation: useWorktree ? "worktree" : "none",
+                                worktreePath,
+                                waitMs: Date.now() - queuedAt,
+                                background: runInBackground,
+                                toolCallsStarted: runStats?.toolCallsStarted ?? latestProgress?.toolCallsStarted,
+                                toolCallsCompleted: runStats?.toolCallsCompleted ?? latestProgress?.toolCallsCompleted,
+                                assistantMessages: runStats?.assistantMessages ?? latestProgress?.assistantMessages,
+                                delegatedTasks: delegatedTasks > 0 ? delegatedTasks : undefined,
+                                delegatedSucceeded: delegatedTasks > 0 ? delegatedSucceeded : undefined,
+                                delegatedFailed: delegatedTasks > 0 ? delegatedFailed : undefined,
+                                retrospectiveAttempts: retrospectiveAttempts > 0 ? retrospectiveAttempts : undefined,
+                                retrospectiveRecovered: retrospectiveRecovered > 0 ? retrospectiveRecovered : undefined,
+                                failureCauses: hasFailureCauses ? { ...failureCauses } : undefined,
+                            };
+                            updateTrackedTaskStatus("cancelled");
+                            throw Object.assign(new Error("Operation aborted"), {
+                                details,
+                                failureCause: "aborted",
+                            });
+                        }
+                        const classified = error && typeof error === "object" && "failureCause" in error
+                            ? error.failureCause
+                            : classifyFailureCause(message);
+                        if (!(error && typeof error === "object" && "failureCause" in error)) {
+                            recordFailureCause(classified);
                         }
+                        const hasFailureCauses = Object.keys(failureCauses).length > 0;
                         const details = {
                             profile: effectiveProfile,
                             description,
@@ -869,15 +1403,11 @@ export function createTaskTool(cwd, runner, options) {
                             delegatedTasks: delegatedTasks > 0 ? delegatedTasks : undefined,
                             delegatedSucceeded: delegatedTasks > 0 ? delegatedSucceeded : undefined,
                             delegatedFailed: delegatedTasks > 0 ? delegatedFailed : undefined,
+                            retrospectiveAttempts: retrospectiveAttempts > 0 ? retrospectiveAttempts : undefined,
+                            retrospectiveRecovered: retrospectiveRecovered > 0 ? retrospectiveRecovered : undefined,
+                            failureCauses: hasFailureCauses ? { ...failureCauses } : undefined,
                         };
-                        if (orchestrationRunId && orchestrationTaskId) {
-                            updateTeamTaskStatus({
-                                cwd,
-                                runId: orchestrationRunId,
-                                taskId: orchestrationTaskId,
-                                status: "error",
-                            });
-                        }
+                        updateTrackedTaskStatus("error");
                         throw Object.assign(new Error(`Subagent failed: ${message}`), { details });
                     }
                     const normalizedOutput = output.trim().length > 0 ? output.trim() : "(Subagent completed with no output)";
@@ -890,6 +1420,15 @@ export function createTaskTool(cwd, runner, options) {
                     if (delegationWarnings.length > 0) {
                         finalSections.push(`### Delegation Notes\n${delegationWarnings.map((w) => `- ${w}`).join("\n")}`);
                     }
+                    const failureCauseSummary = formatFailureCauseCounts(failureCauses);
+                    if (retrospectiveAttempts > 0 || failureCauseSummary) {
+                        finalSections.push([
+                            "### Retrospective",
+                            `- attempts: ${retrospectiveAttempts}`,
+                            `- recovered: ${retrospectiveRecovered}`,
+                            `- failure_causes: ${failureCauseSummary || "none"}`,
+                        ].join("\n"));
+                    }
                     const text = finalSections.join("\n\n");
                     emitProgress({
                         kind: "subagent_progress",
@@ -918,6 +1457,7 @@ export function createTaskTool(cwd, runner, options) {
                         isolation: useWorktree ? "worktree" : "none",
                         worktreePath,
                     });
+                    const hasFailureCauses = Object.keys(failureCauses).length > 0;
                     const details = {
                         profile: effectiveProfile,
                         description,
@@ -955,22 +1495,22 @@ export function createTaskTool(cwd, runner, options) {
                         delegatedTasks: delegatedTasks > 0 ? delegatedTasks : undefined,
                         delegatedSucceeded: delegatedTasks > 0 ? delegatedSucceeded : undefined,
                         delegatedFailed: delegatedTasks > 0 ? delegatedFailed : undefined,
+                        retrospectiveAttempts: retrospectiveAttempts > 0 ? retrospectiveAttempts : undefined,
+                        retrospectiveRecovered: retrospectiveRecovered > 0 ? retrospectiveRecovered : undefined,
+                        failureCauses: hasFailureCauses ? { ...failureCauses } : undefined,
                     };
-                    if (orchestrationRunId && orchestrationTaskId) {
-                        updateTeamTaskStatus({
-                            cwd,
-                            runId: orchestrationRunId,
-                            taskId: orchestrationTaskId,
-                            status: "done",
-                        });
-                    }
+                    updateTrackedTaskStatus("done");
                     return { text, details };
                 }
                 finally {
                     releaseIsolation?.();
                     releaseWriteLock?.();
+                    cleanupWriteLock(explicitRootLockKey);
                     releaseSlot?.();
                     releaseRunSlot?.();
+                    if (orchestrationRunId) {
+                        cleanupOrchestrationSemaphore(cwd, orchestrationRunId);
+                    }
                 }
             };
             if (runInBackground) {
@@ -1013,9 +1553,10 @@ export function createTaskTool(cwd, runner, options) {
                         });
                     }
                     catch (error) {
+                        const aborted = isAbortError(error);
                         writeBackgroundRunStatus(cwd, {
                             runId,
-                            status: "error",
+                            status: aborted ? "cancelled" : "error",
                             createdAt: now,
                             finishedAt: new Date().toISOString(),
                             description,