@nexrall/code-core 1.4.66 → 1.4.67

package/dist/agent/subTask.js

@@ -0,0 +1,713 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSubTask = runSubTask;
+const worktree_1 = require("./worktree");
+const types_1 = require("../types");
+const agentTypes_1 = require("./agentTypes");
+const skills_1 = require("./skills");
+const rules_1 = require("../permissions/rules");
+const agentRegistry_1 = require("./agentRegistry");
+const memory_1 = require("./memory");
+const modelCatalogue_1 = require("./modelCatalogue");
+const hooks_1 = require("./hooks");
+const compaction_1 = require("./compaction");
+const iterationPolicy_1 = require("./iterationPolicy");
+const subTaskSupport_1 = require("./subTaskSupport");
+let _subTaskCounter = 0; // unique per-process id → per-sub-agent todo scope
+async function runSubTask(input, options, agentTypes, 
+// Set to true at the moment an agent loop actually STARTS, so the caller can refund the
+// session slot it claimed for a spawn that turned out never to run.
+//
+// An out-param rather than a discriminated return type on purpose: every one of this
+// function's ~8 early returns is a non-start, and several are far from the top. Enumerating
+// them in the caller would be a list to forget to update; flipping one flag at the single
+// point of no return cannot go stale, and a path added later is a non-start by default.
+started, 
+// Seam: the recursive entry point (loop.ts's runAgentLoop), injected so this module never imports loop.ts.
+runChild) {
+    const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
+    if (!prompt)
+        return { error: 'task tool requires a non-empty prompt' };
+    // The scope of the frame DOING the spawning — i.e. the owner of any resumable id this call
+    // produces, and the identity checked when resuming one. 'root' is the main agent.
+    const agentScope = options._agentScope ?? 'root';
+    const depth = options._depth ?? 0;
+    const depthLimit = (0, subTaskSupport_1.resolveMaxSubagentDepth)(options.workDir ? (0, rules_1.loadSettings)(options.workDir).raw : {});
+    if (depth >= depthLimit) {
+        return { error: (0, subTaskSupport_1.noSpawnReason)('depth', depthLimit) };
+    }
+    // NOTE: the session budget is claimed at the DISPATCH SITE, not here — runSubTask runs
+    // inside the concurrency limiter, so claiming here would make a doomed spawn wait behind
+    // running siblings before being told no. See the `name === 'task'` branch in runAgentLoop.
+    // Resolve an optional custom agent type (subagent_type).
+    //
+    // `agentTypes` is a snapshot taken once at the top of runAgentLoop, before the
+    // model said anything. That made "write .nexrall/agents/x.md, then use it"
+    // impossible within a single turn: the file existed on disk, but this lookup
+    // consulted a list captured before it was written, and the model was told the
+    // agent did not exist — which reads as "creating it failed".
+    //
+    // So on a MISS ONLY, re-read from disk before giving up. The hit path (every
+    // normal call) still costs zero syscalls, and the miss path costs ~4 mostly-
+    // ENOENT stats — against a sub-agent that is about to run for seconds to
+    // minutes. Note runAgentLoop re-reads for the sub-agent anyway, so the old
+    // behaviour was already inconsistent: fresh for the child, stale for the lookup.
+    // ── Resolve a resume target ─────────────────────────────────────────────────
+    //
+    // `resume_agent_id` continues a previous sub-agent. The stored transcript
+    // carries the agent's NAME, and that name — not the one the model passed — is
+    // what gets authorised below.
+    //
+    // This matters because an id would otherwise be a permanent capability: deny
+    // `task(explorer)` today and a model holding yesterday's explorer id could
+    // still resume it, with the deny rule looking like it was applied. Re-deriving
+    // the name from storage also stops a mismatched `subagent_type` from being
+    // used to launder a denied agent under an allowed name.
+    const resumeId = typeof input.resume_agent_id === 'string' ? input.resume_agent_id.trim() : '';
+    const resumed = resumeId ? (0, agentRegistry_1.getAgent)(resumeId) : undefined;
+    // OWNERSHIP, in addition to the deny-rule re-authorisation below.
+    //
+    // Re-deriving the agent NAME from storage stops an id laundering a denied agent, but it
+    // says nothing about WHO may use the id. The registry is one flat process-global Map, so a
+    // nested sub-agent could name an id it was never given and read another agent's entire
+    // unredacted transcript, or overwrite it. Harmless while sub-agents were leaves (only the
+    // main agent ever held an id); live once they can spawn.
+    //
+    // Reported as "expired" rather than "not yours": a distinct message would confirm the id
+    // exists, turning the error into an oracle for enumerating other frames' agents.
+    if (resumed && !(0, agentRegistry_1.canResume)(resumed, agentScope, options.sessionId)) {
+        return {
+            error: `No resumable sub-agent with id "${resumeId}" is available to this run. Start a fresh ` +
+                'sub-task with a self-contained prompt instead.',
+        };
+    }
+    if (resumeId && !resumed) {
+        return {
+            error: `No resumable sub-agent with id "${resumeId}". Ids live only for the current session and the ` +
+                'oldest are dropped when too many accumulate, so this one has expired or never existed. ' +
+                'Start a fresh sub-task with a self-contained prompt instead.',
+        };
+    }
+    const requestedType = resumed
+        ? (resumed.agentName ?? '')
+        : (typeof input.subagent_type === 'string' ? input.subagent_type : '');
+    // ── Enforce `deny: ["task(<name>)"]` ─────────────────────────────────────────
+    //
+    // This is the load-bearing check; filtering the catalogue in runAgentLoop only
+    // stops the agent being SUGGESTED. It must run BEFORE resolution, because the
+    // reload-on-miss path below deliberately re-reads from disk UNFILTERED — a
+    // denied agent is absent from the snapshot, would therefore "miss", and would
+    // then be found by that reload and run. Denying by omission is not denying.
+    //
+    // Phrased as a policy refusal, not "unknown type": the model must not respond
+    // by trying to create the agent file it thinks is missing.
+    // Evaluated UNCONDITIONALLY, with 'general-purpose' standing in for an unnamed dispatch.
+    //
+    // This used to be `if (requestedType)`, which meant an unnamed spawn skipped the rule
+    // entirely: `deny: ["task(general-purpose)"]` matched the named form and returned null for
+    // the unnamed one. Omitting the field was therefore a bypass for the single most
+    // privileged variant — an unnamed sub-task has no allowlist of its own, so before the
+    // parent-intersection it received FULL access, exactly what such a rule is written to stop.
+    //
+    // The substitution is also the honest model rather than a patch: an unnamed sub-task IS
+    // general-purpose behaviourally (that is what naming it accomplished in the first place),
+    // so a rule about that agent should govern both spellings. A bare `deny: ["task"]` already
+    // caught both and is unaffected.
+    const denyKey = requestedType || 'general-purpose';
+    const decision = (0, rules_1.evaluatePermission)((0, rules_1.loadSettings)(options.workDir).permissions, 'task', { subagent_type: denyKey }, options.workDir);
+    if (decision === 'deny') {
+        return {
+            error: `The sub-agent "${denyKey}" is disabled by a permission rule in this project ` +
+                `(permissions.deny in settings.json). This is a deliberate policy choice, not a missing file — ` +
+                'do not create it and do not retry. Do the work yourself, or use a different sub-agent.',
+        };
+    }
+    // An unnamed dispatch IS general-purpose (the tool schema says so): same role prompt,
+    // same "your final message is your report" instructions, same deny rule (denyKey above).
+    let agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType || 'general-purpose');
+    let knownTypes = agentTypes;
+    if (requestedType && !agent) {
+        // Same `extra` list the top-of-run snapshot used (see runAgentLoop) — otherwise a
+        // programmatically-registered agent (registerAgentType()) would resolve on the FIRST
+        // call in a turn (present in the snapshot) but "miss" on this reload path, since it was
+        // never written to disk for loadAgentTypes to rediscover.
+        knownTypes = (0, agentTypes_1.loadAgentTypesWithWarnings)(options.workDir, options._extraAgentTypes ?? []).types;
+        agent = (0, agentTypes_1.findAgentType)(knownTypes, requestedType);
+    }
+    if (requestedType && !agent) {
+        const known = knownTypes.map((a) => a.name).join(', ') || '(none defined)';
+        return {
+            error: `Unknown subagent_type "${requestedType}". Available types: ${known}.\n` +
+                'If you just created .nexrall/agents/' + requestedType + '.md, make sure the write finished in an ' +
+                'EARLIER tool call than this one — a file written in the same batch may not be on disk yet.',
+        };
+    }
+    // A custom agent's persona is delivered through the project-instructions
+    // channel (authoritative in the system prompt), layered above the project's
+    // own nexrall.md so it keeps project conventions.
+    // ── Per-agent memory (`memory:` frontmatter) ────────────────────────────────
+    //
+    // When an agent declares a memory scope, its own notes from previous runs are
+    // injected ahead of its role prompt, and it gains ONE extra tool to append to them.
+    //
+    // Claude Code implements the equivalent by auto-enabling Read/Write/Edit "regardless
+    // of what the tools allowlist says". We deliberately do NOT copy that: silently
+    // widening a declared allowlist is fail-OPEN, and this repo already fixed the
+    // mirror-image bug (an unparseable agent file used to receive FULL access). So the
+    // grant here is a single purpose-built tool that can only ever touch this agent's
+    // own notes file — declaring `memory:` cannot hand anything write access to the repo.
+    const memoryScope = agent?.memory;
+    const agentMemoryNotes = agent && memoryScope
+        ? (0, memory_1.agentMemoryPreamble)(agent.name, memoryScope, options.workDir)
+        : '';
+    // `lightPrompt` agents skip the project's nexrall.md — see AgentType.lightPrompt for
+    // why. The role prompt and any private notes still apply; only the (potentially very
+    // large) project instruction file is dropped.
+    //
+    // Composed from the PROJECT's instructions (`_projectNexrallMd`), never from the
+    // parent's own composite prompt: a grandchild used to inherit its parent's role
+    // ("# Sub-agent role: general-purpose … make the changes") on top of its own
+    // ("explorer … you NEVER modify files"), plus the parent's private memory notes.
+    const projectMd = options._projectNexrallMd ?? options.nexrallMd ?? '';
+    const inheritedMd = agent?.lightPrompt ? '' : projectMd;
+    // `skills:` — preload those skills' instructions (raw body: no !`cmd` expansion runs
+    // just because an agent was spawned). A missing name is stated, not silently dropped.
+    let preloadedSkills = '';
+    if (agent?.skills?.length) {
+        const known = (0, skills_1.loadSkillsWithWarnings)(options.workDir, options._extraSkills ?? []).skills;
+        preloadedSkills = agent.skills.map((n) => {
+            const sk = (0, skills_1.findSkill)(known, n);
+            return sk ? `# Preloaded skill: ${sk.name}\n${sk.body.trim()}` : `# Preloaded skill: ${n}\n(not found in this project — ignore)`;
+        }).join('\n\n');
+    }
+    // Shared-before-specific order: the project's nexrall.md (usually the largest part, and
+    // identical for every non-lightPrompt sibling) goes first; per-agent parts (preamble,
+    // role, skills, private notes) follow — last, where they also carry the most weight
+    // with the model. With the role first, two agents diverged at the first line of this
+    // block. HONEST SCOPE: this only buys cache reuse where everything BEFORE the block
+    // already matches — same tool list and same prompt flags (so e.g. two custom agents
+    // with equal `tools:`, on prefix-cached providers). Types with different allowlists
+    // diverge earlier, at the tools array, whatever the order here. It costs nothing, and
+    // tool enforcement never depended on prompt order (see the allowlist below).
+    const subNexrallMd = [
+        inheritedMd,
+        subTaskSupport_1.SUBAGENT_PREAMBLE,
+        agent ? `# Sub-agent role: ${agent.name}\n${agent.prompt}` : '',
+        preloadedSkills,
+        agentMemoryNotes,
+    ].filter(Boolean).join('\n\n---\n\n');
+    // Optional tool allowlist — deny anything outside it for this sub-agent.
+    //
+    // A refusal here is reported through `deniedReason` rather than the generic
+    // "Permission denied by user", which was actively misleading: the user denied
+    // nothing, and a model told that will re-ask for approval instead of noticing
+    // that the agent's own allowlist (often a typo'd tool name) is what stopped it.
+    // ── The child's allowlist is INTERSECTED with the parent's ──────────────────
+    //
+    // A child's own definition can only ever NARROW what its parent had, never widen it.
+    // Without this, nesting is a privilege-escalation ladder: a read-only agent (planner, or any
+    // user-defined reviewer) has no write_file, but `general-purpose` declares no `tools:` at all (= full access),
+    // so a read-only agent could delegate to an unrestricted one and edit the repo through
+    // it. The user's "this agent cannot write" would silently mean "cannot write directly".
+    //
+    // This was unreachable while sub-agents were leaves — nobody but the (unrestricted) main
+    // agent could spawn. Turning nesting on is what makes it live, so the intersection ships
+    // in the same change rather than as a follow-up.
+    //
+    // `null` still means "no allowlist", but only when BOTH sides say so: an unrestricted
+    // parent spawning general-purpose stays unrestricted (today's behaviour at depth 1),
+    // while a restricted parent yields a restricted child no matter what the child declares.
+    // Sticky for the same reason the allowlist intersects: inherited OR own, never shed.
+    const testFilesOnly = !!agent?.testFilesOnly || !!options._testFilesOnly;
+    const allowed = (0, subTaskSupport_1.intersectAllowlists)(agent?.tools ? new Set(agent.tools) : null, options._allowedTools);
+    // The ONE capability `memory:` grants. Added to the allowlist rather than bypassing
+    // it, so the allowlist stays the single source of truth for what this agent can do.
+    if (allowed && memoryScope)
+        allowed.add(iterationPolicy_1.AGENT_MEMORY_TOOL);
+    // `disallowedTools` (Claude Code) — inherited like the allowlist: a child can only add
+    // to its ancestors' refusals, never shed them.
+    const disallowed = new Set([...(options._disallowedTools ?? []), ...(agent?.disallowedTools ?? [])]);
+    if (allowed)
+        for (const t of disallowed)
+            allowed.delete(t);
+    // `mcpServers` — narrows, inherited like the tool allowlist.
+    let mcpAllow = options._mcpServerAllowlist;
+    if (agent?.mcpServers) {
+        const own = new Set(agent.mcpServers);
+        mcpAllow = mcpAllow ? new Set([...mcpAllow].filter((x) => own.has(x))) : own;
+    }
+    // Time spent waiting on a human (permission prompt) is not a stall.
+    let waitingOnUser = 0;
+    const gatedPermission = async (req) => {
+        // Guard against the tool being reachable without a declared scope — e.g. an agent
+        // that lists it in `tools:` by hand, or a general-purpose sub-task with no
+        // allowlist at all (`allowed === null` permits everything).
+        if (req.tool === iterationPolicy_1.AGENT_MEMORY_TOOL && !(agent && memoryScope)) {
+            throw new subTaskSupport_1.ToolNotAllowedError(`\`${iterationPolicy_1.AGENT_MEMORY_TOOL}\` is only available to a sub-agent whose definition declares a ` +
+                '`memory:` scope (project, user or local). Report anything worth remembering in your final ' +
+                'message instead — the main agent decides what to persist.');
+        }
+        // `task` is answered by the same predicate that decides whether the tool was sent in
+        // the first place, so the gate cannot disagree with the prompt.
+        //
+        // This was briefly an UNCONDITIONAL refusal, which was correct only while the depth
+        // ceiling was hard-coded to 1 (every gated run was a leaf by definition). With nesting
+        // configurable that shortcut becomes a real bug: a depth-1 agent under
+        // `maxSubagentDepth: 3` would be handed the tool by the backend and then refused here.
+        // Fail-closed, so it would have looked like a mysterious dead end rather than a crash.
+        //
+        // Two distinct reasons, two distinct messages — a depth ceiling is raisable, an agent
+        // definition withholding `task` is not, and a refusal that lies about which one applies
+        // makes the model either give up early or hunt for an escape hatch.
+        if (req.tool === 'task' && !(0, subTaskSupport_1.canSpawnSubAgents)(depth + 1, allowed ?? undefined, depthLimit)) {
+            // `depth + 1`, not `depth`: this closure gates the CHILD's tool calls, and the child
+            // runs one level below the `depth` in scope here (which belongs to its parent). Using
+            // `depth` would evaluate the parent's right to spawn — permitting one level too many.
+            throw new subTaskSupport_1.ToolNotAllowedError(allowed && !allowed.has('task')
+                ? (0, subTaskSupport_1.noSpawnReason)('denied')
+                : (0, subTaskSupport_1.noSpawnReason)('depth', depthLimit));
+        }
+        if (allowed && !allowed.has(req.tool)) {
+            throw new subTaskSupport_1.ToolNotAllowedError(
+            // `agent?.name`, NOT `agent!.name`. The non-null assertion held only while `allowed`
+            // was derived solely from `agent?.tools` (non-null allowlist ⇒ named agent). The
+            // parent-intersection broke that invariant: a RESTRICTED parent dispatching `task`
+            // with no subagent_type yields a non-null inherited allowlist with `agent`
+            // undefined, and this line then threw a TypeError instead of ToolNotAllowedError —
+            // which the dispatch site does not recognise, so it laundered the refusal into the
+            // generic "Permission denied by user" this very message exists to avoid.
+            `The "${agent?.name ?? 'general-purpose'}" sub-agent is not allowed to use \`${req.tool}\` — it is not in that agent's ` +
+                'tool allowlist. This is a restriction of the agent definition, NOT a user decision: do not ask ' +
+                'for approval, use one of the tools you do have, or report back that the task needs a different agent.');
+        }
+        // Path-scoped write restriction — see allowsTestOnlyWrite for the reasoning and its
+        // known limit. Applies when THIS agent declares it OR any ancestor did: like the tool
+        // allowlist above, a restriction can only ever be narrowed by nesting, never shed.
+        // Without the inherited half, a test-only agent could delegate to an unrestricted agent and
+        // have production source written on its behalf.
+        if (mcpAllow && req.tool.includes('__') && !mcpAllow.has(req.tool.split('__')[0])) {
+            throw new subTaskSupport_1.ToolNotAllowedError(`The "${agent?.name ?? 'general-purpose'}" sub-agent may only use tools from these MCP servers: ` +
+                `${[...mcpAllow].join(', ') || '(none)'}. \`${req.tool}\` is from another server — use a different tool or report back.`);
+        }
+        if (disallowed.has(req.tool)) {
+            throw new subTaskSupport_1.ToolNotAllowedError(`The "${agent?.name ?? 'general-purpose'}" sub-agent may not use \`${req.tool}\` (disallowedTools in its ` +
+                'definition). This is a restriction of the agent definition, NOT a user decision — use another tool or report back.');
+        }
+        if (req.tool === 'memory_write') {
+            throw new subTaskSupport_1.ToolNotAllowedError('Sub-agents cannot write the shared memory store. Put anything worth remembering in your final report — ' +
+                'the main agent decides what to persist.');
+        }
+        if (testFilesOnly && !(0, compaction_1.allowsTestOnlyWrite)(req.tool, req.input)) {
+            throw new subTaskSupport_1.ToolNotAllowedError(`The "${agent?.name ?? 'general-purpose'}" sub-agent may only write to TEST files, so ` +
+                `\`${req.tool}\` was refused for this path. Do not try to work around it: if production ` +
+                'code must change, say so in your report instead.');
+        }
+        // An agent writing its OWN notes (declared `memory:`) is answered here, not by the
+        // ancestors: their gates refuse agent_memory_write unless THEY declared a scope, so a
+        // memory agent spawned by general-purpose could never write. The tool can only touch
+        // this agent's own notes file, so there is nothing for anyone above to approve.
+        if (req.tool === iterationPolicy_1.AGENT_MEMORY_TOOL && agent && memoryScope)
+            return true;
+        waitingOnUser++;
+        try {
+            // Say WHICH sub-agent is asking (the innermost one wins as the request bubbles up).
+            const description = typeof input.description === 'string' ? input.description : undefined;
+            return await options.requestPermission({
+                ...req,
+                agent: req.agent ?? { name: agent?.name ?? 'general-purpose', ...(description ? { description } : {}) },
+            });
+        }
+        finally {
+            waitingOnUser--;
+            bumpProgress();
+        }
+    };
+    // ── Resume: continue a previous sub-agent instead of starting cold ──────────
+    //
+    // The new prompt is appended as another user turn to the stored transcript, so
+    // the agent keeps every file it read and every conclusion it reached. Without
+    // this, "now also check the auth path" means re-describing the entire job and
+    // re-reading everything — the most common and most expensive kind of waste in
+    // a delegated workflow.
+    const subMessages = resumed
+        ? [...resumed.messages, { role: 'user', content: [{ type: 'text', text: prompt }] }]
+        : [{ role: 'user', content: [{ type: 'text', text: prompt }] }];
+    // A dedicated abort signal for this sub-agent, distinct from the parent's own
+    // options.abortSignal (user hit Ctrl+C). Set to true either when the parent
+    // aborts OR when the stall timeout below fires, whichever happens first —
+    // runAgentLoop already checks abortSignal.aborted at every iteration boundary,
+    // so this is enough to make it stop promptly without a forceful kill.
+    const subAbort = { aborted: false };
+    const subtaskTimeoutMs = (0, subTaskSupport_1.resolveSubtaskTimeoutMs)((0, rules_1.loadSettings)(options.workDir).raw);
+    // ── Stall watchdog, NOT a total-runtime deadline ─────────────────────────────
+    //
+    // This used to be a single setTimeout armed once and never refreshed. Its own
+    // comment called it a "stalled-agent cutoff", but it measured TOTAL LIFETIME: a
+    // sub-agent working hard and calling a tool every few seconds was killed at ten
+    // minutes exactly like one that had hung. That is not a hypothetical — auditing a
+    // handful of 600-2800 line files legitimately exceeds it, and when it fired the
+    // parent got back a fragment ("I'll start by reading the files…") after paying for
+    // 23 tool calls, then typically re-ran the whole thing.
+    //
+    // The main loop already draws this distinction correctly (client.ts's heartbeat vs
+    // progress watchdogs, where only real events bump lastProgressAt). Sub-agents now do
+    // too: the clock resets on every completed tool round, so the cap means "no progress
+    // for N minutes" — which is what catches a genuine hang — while useful work can run
+    // as long as it keeps being useful.
+    //
+    // `stalled` is tracked separately from `subAbort.aborted` because the parent's Ctrl+C
+    // also sets the latter, and the two must be reported differently.
+    let lastProgressAt = Date.now();
+    let stalled = false;
+    const bumpProgress = () => { lastProgressAt = Date.now(); };
+    const stallWatchdog = setInterval(() => {
+        if (waitingOnUser > 0) {
+            lastProgressAt = Date.now();
+            return;
+        }
+        if (Date.now() - lastProgressAt > subtaskTimeoutMs) {
+            stalled = true;
+            subAbort.aborted = true;
+        }
+    }, 1000);
+    // Mirror the parent's own abort into the sub-agent's signal so Ctrl+C during
+    // a running sub-task still stops it (previously this worked implicitly by
+    // sharing the same object via `...options` — now that we own a distinct
+    // object we must forward it explicitly).
+    const parentAbortPoll = setInterval(() => {
+        if (options.abortSignal?.aborted)
+            subAbort.aborted = true;
+    }, 250);
+    // ── Worktree isolation (`isolation: "worktree"` on the call or in the definition) ──
+    // A fresh worktree per spawn, like Claude Code: the child's writes, bash cwd and git
+    // commands are confined to it (worktreeEnforcement), and it is removed afterwards
+    // unless the child actually changed something.
+    let isoState;
+    if (input.isolation === 'worktree' || agent?.isolation === 'worktree') {
+        const created = (0, worktree_1.createWorktree)(options.workDir);
+        if (!created.ok || !created.state) {
+            clearInterval(stallWatchdog);
+            clearInterval(parentAbortPoll);
+            return {
+                error: `Could not create an isolated worktree for this sub-agent: ${created.error ?? 'unknown error'}. ` +
+                    'Run it without isolation, or fix the repository state first.',
+            };
+        }
+        isoState = created.state;
+    }
+    const childWorkDir = isoState?.worktreePath ?? options.workDir;
+    // Claude Code's Explore/Plan skip git status; so do lightPrompt agents here. An
+    // isolated child is told where it actually is.
+    let childEnv = options.env;
+    if (childEnv && agent?.lightPrompt) {
+        const { gitStatus: _s, gitDiff: _d, recentCommits: _c, ...rest } = childEnv;
+        childEnv = rest;
+    }
+    if (childEnv && isoState)
+        childEnv = { ...childEnv, cwd: isoState.worktreePath, gitBranch: isoState.branch ?? childEnv.gitBranch };
+    // Per-sub-agent accounting, reported in its tool result (Claude Code shows the same).
+    const subStartedAt = Date.now();
+    let subToolCalls = 0;
+    let subTokens = 0;
+    let subCost = 0;
+    let childStop = null;
+    let childNotice = null;
+    let childVerifications = [];
+    const finalize = (r) => {
+        let isoNote = '';
+        if (isoState) {
+            if ((0, worktree_1.worktreeHasWork)(isoState)) {
+                isoNote = `\n[isolated worktree: this sub-agent's changes are in ${isoState.worktreePath}` +
+                    `${isoState.branch ? ` (branch ${isoState.branch})` : ''} — NOT in the main checkout. Review them, then merge or discard.]`;
+            }
+            else {
+                (0, worktree_1.removeWorktree)(isoState, { force: true });
+            }
+            isoState = undefined;
+        }
+        const stats = `[sub-agent stats: ${subToolCalls} tool call(s) · ${(0, subTaskSupport_1.formatTokenCount)(subTokens)} tokens · ` +
+            `$${subCost.toFixed(3)} · ${(0, subTaskSupport_1.formatElapsed)(Date.now() - subStartedAt)}]`;
+        const out = { ...r, ...(childVerifications.length ? { childVerifications } : {}) };
+        if (out.error !== undefined)
+            out.error = `${out.error}\n\n${stats}${isoNote}`;
+        else
+            out.output = `${out.output ?? ''}\n\n${stats}${isoNote}`;
+        return out;
+    };
+    // Claimed right before `try` (whose finally releases it). runSubTask has no `await`
+    // before this point, so two parallel calls cannot both pass the check.
+    if (resumed && !(0, agentRegistry_1.claimAgentForResume)(resumed.id)) {
+        clearInterval(stallWatchdog);
+        clearInterval(parentAbortPoll);
+        if (isoState)
+            (0, worktree_1.removeWorktree)(isoState, { force: true });
+        return {
+            error: `Sub-agent "${resumed.id}" is already being resumed by another task call that is still running. ` +
+                'Wait for that result, then resume it again with your follow-up — two parallel resumes of one agent ' +
+                'would overwrite each other\'s work.',
+        };
+    }
+    const childMeta = (m) => (m
+        ? { ...m, parentId: m.parentId ?? options._taskToolUseId, agentName: m.agentName ?? agent?.name ?? 'general-purpose' }
+        : undefined);
+    try {
+        // The point of no return: past here a real agent loop exists and the budget slot is spent.
+        if (started)
+            started.value = true;
+        // SubagentStart: observer (cannot veto — the PreToolUse hook on `task` already can).
+        // additionalContext is appended to the brief the child receives.
+        {
+            const subAgentName = agent?.name ?? (typeof input.subagent_type === 'string' && input.subagent_type ? input.subagent_type : 'general-purpose');
+            const startItems = (0, hooks_1.loadHooks)(options.workDir).SubagentStart;
+            if (startItems?.length) {
+                const o = await (0, hooks_1.runLifecycleHooks)(startItems, 'SubagentStart', options.workDir, { session_id: options.sessionId ?? '', agent_type: subAgentName, description: String(input.description ?? '') }, subAgentName, (0, hooks_1.hookRunOptsFor)(options)).catch(() => ({ block: false }));
+                if (o.context) {
+                    const last = subMessages[subMessages.length - 1];
+                    if (last && Array.isArray(last.content)) {
+                        subMessages[subMessages.length - 1] = { ...last, content: [...last.content, { type: 'text', text: `\n\n<hook-context>\n${o.context}\n</hook-context>` }] };
+                    }
+                }
+            }
+        }
+        const childRun = runChild(subMessages, {
+            ...options,
+            _depth: depth + 1,
+            _agentScope: `sub_${++_subTaskCounter}`, // isolated todo store per sub-agent
+            // ── Assigned UNCONDITIONALLY, never by conditional spread ────────────────
+            //
+            // These two were previously spread in only when set:
+            //
+            //   ...(agent && memoryScope ? { _agentMemory: … } : {}),
+            //
+            // which does NOT clear the key — it leaves whatever `...options` already had.
+            // So a child WITHOUT its own `memory:` inherited its PARENT's binding and would
+            // have appended to another agent's private notes; likewise an agent with no
+            // `tools:` line inherited the parent's allowlist, making the prompt's capability
+            // claim disagree with its real one.
+            //
+            // This is now LIVE, not latent: nesting is enabled by default, so a grandchild really
+            // can be spawned by an agent that has a memory binding. The explicit `undefined` is
+            // what stops it inheriting that binding and appending to its grandparent's private
+            // notes — a silent cross-agent write rather than a visible error. Note the allowlist
+            // takes the opposite direction on purpose (inherited, because it RESTRICTS); identity
+            // must not be inherited, capability must.
+            _agentMemory: agent && memoryScope ? { agentName: agent.name, scope: memoryScope } : undefined,
+            // Assigned unconditionally for the same reason as _agentMemory above: a
+            // conditional spread would leave the PARENT's type name in place, so an
+            // untyped (general-purpose) child would be recorded in the audit trail
+            // under its parent's agent type — a wrong attribution, which is worse in a
+            // compliance record than an absent one.
+            _agentTypeName: agent?.name,
+            // The same set `gatedPermission` enforces above, so prompt and permission agree
+            // by construction instead of by two people remembering to update both.
+            _allowedTools: allowed ?? undefined,
+            // Propagated so a grandchild inherits it too — see _testFilesOnly. Assigned
+            // unconditionally (not by conditional spread) for the same reason as _agentMemory
+            // above: a conditional spread leaves the parent's value in place instead of clearing
+            // it, and here that direction is at least safe, whereas forgetting to propagate is not.
+            _testFilesOnly: testFilesOnly,
+            editorContext: null, // fresh isolated context for sub-agent
+            model: (0, modelCatalogue_1.resolveSubAgentModel)(agent?.model, options.model),
+            workDir: childWorkDir,
+            env: childEnv,
+            effort: agent?.effort ?? options.effort,
+            // A bounded run that REPORTS when it hits the limit (see childStop below), instead
+            // of inheriting the main agent's 500-step budget plus auto-continue to 2000.
+            maxIterations: agent?.maxTurns ?? subTaskSupport_1.DEFAULT_SUBAGENT_MAX_TURNS,
+            autoContinue: false,
+            // ── Session-level channels a child must NEVER consume ────────────────────
+            // Inherited through `...options`, a child drained the user's queued follow-ups
+            // and inbound peer messages into ITS history (the main agent never saw them),
+            // and its onProgress saved the child's transcript AS the session (CLI/desktop).
+            takePendingInput: undefined,
+            onInjectedInput: undefined,
+            drainPeerMessages: undefined,
+            onPeerMessage: undefined,
+            onProgress: undefined,
+            backgroundAgents: undefined,
+            _projectNexrallMd: projectMd,
+            _disallowedTools: disallowed.size ? disallowed : undefined,
+            _mcpServerAllowlist: mcpAllow,
+            _agentHooks: agent?.hooks,
+            _onStopReason: (reason, notice) => { childStop = reason; childNotice = notice; },
+            _onVerifications: (records) => { childVerifications = records; },
+            onUsage: (u, partial, cost, _sub) => {
+                if (!partial) {
+                    subTokens += (u.input_tokens ?? 0) + (u.output_tokens ?? 0)
+                        + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+                    subCost += cost ?? 0;
+                }
+                options.onUsage(u, partial, cost, true);
+            },
+            // Plan mode is inherited, never relaxed. If the main agent could spawn a
+            // sub-agent that writes, the lock would be one `task` call from useless.
+            // `permissionMode: plan` in a definition can only ADD the lock.
+            planMode: options.planMode || agent?.permissionMode === 'plan',
+            // Same reasoning as planMode directly above: a sub-agent that could reach
+            // outside its parent's worktree would defeat the isolation in one `task`
+            // call. Already inherited via `...options` above — restated explicitly so
+            // it reads the same way as planMode and is never accidentally dropped by
+            // a future refactor of this spread.
+            worktree: isoState ?? options.worktree,
+            // A sub-agent using message_peer_session/list_peer_sessions should
+            // present as the SAME peer identity as its parent — there is one
+            // registered peer per SESSION, not per sub-agent, so a sub-agent is
+            // not a separate discoverable entity of its own.
+            selfPeer: options.selfPeer,
+            nexrallMd: subNexrallMd,
+            abortSignal: subAbort,
+            requestPermission: gatedPermission,
+            onText: () => { }, // sub-agent text is returned as the tool result, not streamed live
+            // A sub-agent renders nothing live (text and thinking are not streamed — see below),
+            // so a restart of ITS stream has nothing on screen to roll back: a real no-op
+            // handler is exactly right, and it opts the child into post-render restarts.
+            onStreamRestart: () => { },
+            // Forward tool events with isSubTask=true so the UI can render a badge
+            // instead of prepending "[sub-task]" to the tool name (which caused double-prefix
+            // when the name was already labelled, and mixed display concerns into the data layer).
+            // Every tool event is PROGRESS: it proves the sub-agent is still doing work, which
+            // is what the stall watchdog above measures. Bumping on both use and result means a
+            // single very slow tool (a long test run) resets the clock when it starts AND when
+            // it finishes, so it cannot be mistaken for a hang.
+            // `parentId` = the `task` call that spawned THIS child. Set only if not already set,
+            // so a grandchild's events keep pointing at their own (nearest) task row.
+            onToolUse: (n, i, _s, m) => { bumpProgress(); subToolCalls++; options.onToolUse(n, i, true, childMeta(m)); },
+            onToolResult: (n, r, _s, m) => { bumpProgress(); options.onToolResult(n, r, true, childMeta(m)); },
+            // A long command streaming output is working, not hung.
+            onToolStreamChunk: (n, c, _s, m) => { bumpProgress(); options.onToolStreamChunk?.(n, c, true, childMeta(m)); },
+            // Thinking is progress (a model reasoning for minutes is working, not stalled), but
+            // it is NOT forwarded to the UI: parallel siblings' deltas interleaved into one live
+            // thinking block, and Claude Code does not show sub-agent reasoning either. The
+            // sub-agent's tool rows (grouped under its task row) are its visible progress.
+            onThinking: () => { bumpProgress(); },
+            onThinkingDelta: () => { bumpProgress(); },
+            onThinkingProgress: () => { bumpProgress(); },
+        });
+        const raced = await (0, subTaskSupport_1.raceHardStop)(childRun, subAbort);
+        if (raced === subTaskSupport_1.HARD_STOPPED) {
+            // The child was told to stop (stall watchdog, parent Stop, background stop) but a
+            // tool it is running ignored cancellation — an MCP call, an editor-side tool. The
+            // parent must not hang on it forever; the orphaned call is left to finish alone.
+            return finalize({
+                error: `Sub-task did not stop within ${Math.round((0, subTaskSupport_1.hardStopGraceMs)() / 1000)}s of being stopped: a tool it was ` +
+                    'running ignored cancellation. Its partial work could not be collected. Do not re-run it as-is — ' +
+                    'narrow the task, or avoid the tool that hung.',
+            });
+        }
+        const result = raced;
+        // ── Stall timeout: SALVAGE, don't discard ────────────────────────────────
+        //
+        // The sub-agent hit its wall-clock cap (rather than finishing, or the parent
+        // aborting). This used to return ONLY an error string — throwing away
+        // everything the sub-agent had produced in up to ten minutes of work. The
+        // tokens were billed in full either way, and the parent model, told merely
+        // that "it stalled", would routinely re-run the identical work from scratch.
+        //
+        // The timeout still has to be reported unmistakably (the parent must not
+        // mistake a truncated run for a complete answer), but it is reported ALONGSIDE
+        // whatever was actually accomplished, not instead of it. `preferLast: false`
+        // because a killed sub-agent rarely has a closing summary — its useful output
+        // is spread across the assistant turns it did manage to produce.
+        if (stalled && !options.abortSignal?.aborted) {
+            const mins = Math.round(subtaskTimeoutMs / 60000);
+            const partial = (0, subTaskSupport_1.capSubTaskText)((0, subTaskSupport_1.extractSubTaskText)(result, false));
+            const progress = (0, subTaskSupport_1.summariseSubTaskProgress)(result);
+            // Keep the transcript so the parent can CONTINUE this run instead of redoing it.
+            //
+            // Previously only a cleanly-finished sub-agent was remembered, on the reasoning
+            // that a transcript ending mid-thought is unsafe to build on. The reasoning is
+            // sound; the conclusion was too strong. Refusing to store it meant a stalled
+            // sub-agent's entire body of work — dozens of tool calls, already billed — was
+            // unreachable, so the parent's only option was the very thing we tell it not to
+            // do: run the whole task again. Resuming is now POSSIBLE but never implied to be
+            // safe: the text below states plainly that the work is unverified, and resumption
+            // re-authorises against current permissions exactly as it does for a clean run.
+            const partialId = (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result, agentScope, options.sessionId);
+            const sections = [
+                `Sub-task STOPPED after ${mins} minutes with NO PROGRESS (it was not making tool calls or ` +
+                    'producing output) — treat everything below as PARTIAL, unverified work, not a finished answer.',
+                progress,
+                partial ? `Partial output before it was stopped:\n\n${partial}` : '',
+                `Do NOT re-run the same sub-task from scratch. Either build on what is above, or continue THIS ` +
+                    `run with resume_agent_id="${partialId}" (it still has everything it read), or split the ` +
+                    'remaining work into smaller, more focused sub-tasks.',
+            ].filter(Boolean);
+            // Returned as `error` (not `output`) on purpose: the loop's ledger counts an
+            // errored call as a non-effect, which is right — nothing here is verified —
+            // and the STALL_LIMIT runaway guard must still see repeated timeouts as
+            // failures so a permanently stuck sub-task can't loop forever.
+            return finalize({ error: sections.join('\n\n') });
+        }
+        // ── Stopped abnormally (turn limit, repeated failures, truncation, no balance) ──
+        // runAgentLoop RETURNS normally for these, so this used to fall through to the
+        // success path: the parent was handed a fragment as if it were the finished report,
+        // while the explanation went to the user's chat as if the main agent had stopped.
+        // Assigned inside callbacks, so TS narrows them to `null` here without the casts.
+        const stopReasonOfChild = childStop;
+        const noticeOfChild = childNotice;
+        if (stopReasonOfChild && subTaskSupport_1.ABNORMAL_SUBAGENT_STOPS.has(stopReasonOfChild) && !subAbort.aborted) {
+            const partial = (0, subTaskSupport_1.capSubTaskText)((0, subTaskSupport_1.extractSubTaskText)(result, false));
+            const progress = (0, subTaskSupport_1.summariseSubTaskProgress)(result);
+            const partialId = resumed
+                ? ((0, agentRegistry_1.updateAgent)(resumed.id, result, agentScope, options.sessionId), resumed.id)
+                : (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result, agentScope, options.sessionId);
+            const why = stopReasonOfChild === 'budget'
+                ? `it reached its turn limit (${agent?.maxTurns ?? subTaskSupport_1.DEFAULT_SUBAGENT_MAX_TURNS} model round-trips)`
+                : `it stopped early (${stopReasonOfChild})`;
+            const sections = [
+                `Sub-task did NOT finish: ${why}. Treat everything below as PARTIAL, unverified work.`,
+                noticeOfChild ? noticeOfChild.trim() : '',
+                progress,
+                partial ? `Partial output:\n\n${partial}` : '',
+                `To continue it with everything it already read, call task with resume_agent_id="${partialId}".`,
+            ].filter(Boolean);
+            return finalize({ error: sections.join('\n\n') });
+        }
+        // Normal completion: the final assistant message is the sub-agent's answer.
+        const text = (0, subTaskSupport_1.capSubTaskText)((0, subTaskSupport_1.extractSubTaskText)(result, true));
+        // Store the transcript so a follow-up can continue this agent rather than
+        // re-running it from scratch, and tell the parent the id.
+        //
+        // (The stalled and stopped-early paths above register their transcripts too, marked
+        // as partial work in the text they return; only a thrown failure is not resumable.)
+        const agentId = resumed
+            ? ((0, agentRegistry_1.updateAgent)(resumed.id, result, agentScope, options.sessionId), resumed.id)
+            : (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result, agentScope, options.sessionId);
+        const body = text || '(sub-task completed with no text output)';
+        return finalize({
+            output: `${body}\n\n[resumable: this sub-agent is "${agentId}". To ask IT a follow-up — keeping ` +
+                'everything it already read and concluded — call task again with resume_agent_id="' + agentId +
+                '" instead of writing a new prompt from scratch.]',
+        });
+    }
+    catch (err) {
+        // Same salvage rule as the timeout path above, for the other way a sub-agent
+        // dies: runAgentLoop throws AgentTurnError when its stream fails, and that
+        // error CARRIES the history completed up to the failure precisely so callers
+        // don't lose it (see types.ts). Discarding it here — as this catch used to —
+        // reproduced the exact waste that class was written to prevent, one level down.
+        const salvaged = (0, types_1.salvageHistory)(err);
+        if (salvaged) {
+            const partial = (0, subTaskSupport_1.capSubTaskText)((0, subTaskSupport_1.extractSubTaskText)(salvaged, false));
+            const progress = (0, subTaskSupport_1.summariseSubTaskProgress)(salvaged);
+            const sections = [
+                `Sub-task FAILED before completing: ${err.message}`,
+                progress,
+                partial ? `Partial output before the failure:\n\n${partial}` : '',
+                'Treat the above as PARTIAL, unverified work. Build on it rather than re-running the whole sub-task.',
+            ].filter(Boolean);
+            return finalize({ error: sections.join('\n\n') });
+        }
+        return finalize({ error: `Sub-task failed: ${err.message}` });
+    }
+    finally {
+        clearInterval(stallWatchdog);
+        clearInterval(parentAbortPoll);
+        // Every return above already ran finalize(); this only catches an unexpected path.
+        if (isoState && !(0, worktree_1.worktreeHasWork)(isoState))
+            (0, worktree_1.removeWorktree)(isoState, { force: true });
+        if (resumed)
+            (0, agentRegistry_1.releaseAgentForResume)(resumed.id);
+    }
+}
+//# sourceMappingURL=subTask.js.map