@nexrall/code-core 1.4.63 → 1.4.65

package/dist/agent/loop.js

@@ -57,26 +57,37 @@ exports.capSubTaskText = capSubTaskText;
 exports.summariseSubTaskProgress = summariseSubTaskProgress;
 exports.lastToolResults = lastToolResults;
 exports.contextWindowFor = contextWindowFor;
+exports.compactionLimits = compactionLimits;
 exports.compactionThresholds = compactionThresholds;
+exports.pruneReclaimFloor = pruneReclaimFloor;
 exports.estimateBodyBytes = estimateBodyBytes;
 exports.allowsTestOnlyWrite = allowsTestOnlyWrite;
 exports.findSafeCutIndex = findSafeCutIndex;
+exports.persistRuntimeContext = persistRuntimeContext;
 exports.transcriptOf = transcriptOf;
 exports.createLedger = createLedger;
 exports.ledgerRecord = ledgerRecord;
 exports.ledgerSummary = ledgerSummary;
 exports.pruneOldToolResults = pruneOldToolResults;
+exports.makeCachedSummarizer = makeCachedSummarizer;
 exports.estimateTokensRough = estimateTokensRough;
 exports.compactMessagesForResume = compactMessagesForResume;
 exports.dispatchSubAgent = dispatchSubAgent;
+exports.dispatchBackgroundSubAgent = dispatchBackgroundSubAgent;
 exports.runAgentLoop = runAgentLoop;
 exports.trimToResumableBoundary = trimToResumableBoundary;
+const readDedupe_1 = require("./readDedupe");
+const toolPrefetch_1 = require("./toolPrefetch");
+const worktree_1 = require("./worktree");
+const backgroundAgents_1 = require("./backgroundAgents");
 const types_1 = require("../types");
 const client_1 = require("../api/client");
 const executor_1 = require("../tools/executor");
 const agentTypes_1 = require("./agentTypes");
 const skills_1 = require("./skills");
 const rules_1 = require("../permissions/rules");
+const modePolicy_1 = require("../permissions/modePolicy");
+const destructive_1 = require("../permissions/destructive");
 // bashNeedsRepoLock lives in permissions/bashClassify.ts, not here: the permission
 // gate needs the same "does this command mutate shared state?" answer, and importing
 // it from loop.ts would make permissions depend on the agent loop (a cycle).
@@ -98,6 +109,16 @@ const crossProcessLock_1 = require("./crossProcessLock");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+function withAgentHooks(base, agent) {
+    if (!agent)
+        return base;
+    return {
+        ...base,
+        PreToolUse: [...(base.PreToolUse ?? []), ...(agent.PreToolUse ?? [])],
+        PostToolUse: [...(base.PostToolUse ?? []), ...(agent.PostToolUse ?? [])],
+        SubagentStop: [...(base.SubagentStop ?? []), ...(agent.Stop ?? [])],
+    };
+}
 function loadHooks(workDir) {
     let fromSettings = {};
     try {
@@ -128,7 +149,60 @@ function loadHooks(workDir) {
 //   • stdout JSON object    → { "decision": "block"|"allow", "reason": "...",
 //                              "additionalContext": "text to feed the model" }
 //   • any other exit code   → non-blocking (stderr logged, tool proceeds)
-function runToolHooks(entries, phase, toolName, input, workDir, result) {
+/**
+ * Run one hook command WITHOUT blocking the event loop. spawnSync froze everything in
+ * the process for up to the hook's timeout — parallel sub-agents' streams, the UI, the
+ * stall watchdogs — which a 60 s PostToolUse test hook turned into a visible hang.
+ */
+function spawnHook(command, opts) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const done = (status) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ status, stdout, stderr });
+        };
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(command, { shell: true, cwd: opts.cwd, env: opts.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            resolve({ status: null, stdout: '', stderr: '' });
+            return;
+        }
+        const timer = setTimeout(() => { try {
+            child.kill('SIGTERM');
+        }
+        catch { /* gone */ } done(null); }, opts.timeout);
+        const cap = 16 * 1024 * 1024;
+        child.stdout?.on('data', (d) => { if (stdout.length < cap)
+            stdout += d.toString('utf-8'); });
+        child.stderr?.on('data', (d) => { if (stderr.length < cap)
+            stderr += d.toString('utf-8'); });
+        child.on('error', () => done(null));
+        child.on('close', (code) => done(code));
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(opts.input ?? '');
+    });
+}
+/**
+ * Does a hook's matcher select this tool? Empty / "*" = every tool. "A|B" = either.
+ * Each alternative may be a Claude Code tool name ("Bash", "Edit") or a Nexrall one, and
+ * a Nexrall-name alternative keeps the old substring behaviour ("file" matches read_file).
+ */
+function hookMatches(matcher, toolName) {
+    if (!matcher || matcher === '*')
+        return true;
+    return matcher.split('|').map((m) => m.trim()).filter(Boolean).some((alt) => {
+        const norm = (0, agentTypes_1.normaliseToolName)(alt);
+        return norm === toolName || (norm === alt && toolName.includes(alt));
+    });
+}
+async function runToolHooks(entries, phase, toolName, input, workDir, result) {
     const outcome = { block: false };
     if (!entries?.length)
         return outcome;
@@ -139,7 +213,7 @@ function runToolHooks(entries, phase, toolName, input, workDir, result) {
         ...(result ? { result: { output: result.output, error: result.error } } : {}),
     });
     for (const entry of entries) {
-        if (entry.matcher && entry.matcher !== '*' && !toolName.includes(entry.matcher))
+        if (!hookMatches(entry.matcher, toolName))
             continue;
         for (const hook of entry.hooks ?? []) {
             if (hook.type !== 'command' || !hook.command)
@@ -150,26 +224,17 @@ function runToolHooks(entries, phase, toolName, input, workDir, result) {
             const hookTimeout = typeof hook.timeout_ms === 'number' && hook.timeout_ms > 0
                 ? Math.min(hook.timeout_ms, 600000)
                 : 60000;
-            let r;
-            try {
-                r = (0, child_process_1.spawnSync)(hook.command, {
-                    shell: true,
-                    cwd: workDir,
-                    timeout: hookTimeout,
-                    encoding: 'utf-8',
-                    maxBuffer: 16 * 1024 * 1024,
-                    input: payload,
-                    env: {
-                        ...process.env,
-                        NEXRALL_TOOL_NAME: toolName,
-                        NEXRALL_TOOL_INPUT: JSON.stringify(input),
-                        NEXRALL_HOOK_PHASE: phase,
-                    },
-                });
-            }
-            catch {
-                continue; // hook itself failed to spawn — non-fatal
-            }
+            const r = await spawnHook(hook.command, {
+                cwd: workDir,
+                timeout: hookTimeout,
+                input: payload,
+                env: {
+                    ...process.env,
+                    NEXRALL_TOOL_NAME: toolName,
+                    NEXRALL_TOOL_INPUT: JSON.stringify(input),
+                    NEXRALL_HOOK_PHASE: phase,
+                },
+            });
             // Optional JSON directive on stdout
             const out = (r.stdout ?? '').toString().trim();
             if (out.startsWith('{')) {
@@ -195,15 +260,12 @@ function runToolHooks(entries, phase, toolName, input, workDir, result) {
     }
     return outcome;
 }
-function runSimpleHooks(defs, workDir) {
+async function runSimpleHooks(defs, workDir, extraEnv) {
     if (!defs?.length)
         return;
     for (const hook of defs) {
         if (hook.type === 'command' && hook.command) {
-            try {
-                (0, child_process_1.spawnSync)(hook.command, { shell: true, cwd: workDir, timeout: 10000 });
-            }
-            catch { /* non-fatal */ }
+            await spawnHook(hook.command, { cwd: workDir, timeout: 10000, env: extraEnv ? { ...process.env, ...extraEnv } : undefined });
         }
     }
 }
@@ -575,29 +637,45 @@ function lockPathsFor(name, input, workDir) {
 // callers.
 //
 // Anthropic hit the same wall and capped Claude Code's concurrent subagents at 20
-// (v2.1.217, July 2026); community guidance settles far lower, around 3-5, because
-// past that the synthesis overhead cancels the parallelism. We default to 4:
-// enough for genuine fan-out (the case sub-agents exist for), low enough that a
-// runaway `task` burst degrades into a queue instead of a thundering herd.
+// (v2.1.217, July 2026, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS); community guidance for
+// everyday work settles around 3-5 because past that the synthesis overhead cancels
+// the parallelism.
+//
+// Default 10, raised from 4 (2026-09-29), with a hard ceiling of 32 (see below). Measured
+// on a 12-core dev box against the Nexrall repo, the per-agent latency of a
+// search_files + glob pair was 116 ms at N=4, 176 ms at N=10, 300 ms at N=20 and 415 ms
+// at N=30. Local CPU is NOT what limits fan-out; the model API is (rounds are seconds
+// long, tools are milliseconds). What did limit it was the SERVER: /api/code was IP
+// rate-limited at 100 req/15 min, which even 4 agents exhausted. That is now per-user
+// (backend shared/utils/codeRateLimit.js), so the old "4" no longer protects anything
+// that 10 does not.
+//
+// Why not default 20/30 like the headline number: the default applies to EVERY user, on
+// every model, including ones with a low per-key TPM, and each concurrent agent is its
+// own bill. Wide fan-out is opt-in (maxConcurrentSubtasks / NEXRALL_MAX_CONCURRENT_SUBTASKS
+// up to 32), narrow fan-out is the safe default.
 //
 // This is a QUEUE, not a rejection: every sub-task still runs, just at most N at a
 // time. Failing the excess would be worse than serialising it.
-const DEFAULT_MAX_CONCURRENT_SUBTASKS = 4;
+const DEFAULT_MAX_CONCURRENT_SUBTASKS = 10;
+/** Hard ceiling on maxConcurrentSubtasks, whatever settings.json (repo-controlled) says. */
+const HARD_MAX_CONCURRENT_SUBTASKS = 32;
 /**
  * Resolve the fan-out limit: env → settings.json → default.
  *
  * Was env-ONLY, the same gap as the sub-task timeout: a project on a small machine that
  * wanted 2, or a big one that wanted 6, had to set a shell variable, and nobody reading
- * settings.json could see what the limit even was. Capped at 16 because this bounds real
- * shared resources (CPU, the API rate limit, file handles) and a typo like 400 should
- * degrade to "a lot" rather than fork-bomb the machine.
+ * settings.json could see what the limit even was. Capped at HARD_MAX_CONCURRENT_SUBTASKS
+ * (32 — above Claude Code's default 20, so a user who wants that width can have it)
+ * because this bounds real shared resources (CPU, the API rate limit, file handles) and a
+ * typo like 400 should degrade to "a lot" rather than fork-bomb the machine.
  */
 function resolveMaxConcurrentSubtasks(settingsRaw = {}) {
     // `Math.max(1, …)` matters: a fractional value like 0.5 passes the `> 0` guard, then floors
     // to 0, and createLimiter(0) queues every task with nothing left to ever release them — a
     // silent permanent hang with no timeout and no error. Harmless when only depth 0 used the
     // limiter; now that every level does, it would wedge the whole tree.
-    const clamp = (n) => Math.max(1, Math.min(Math.floor(n), 16));
+    const clamp = (n) => Math.max(1, Math.min(Math.floor(n), HARD_MAX_CONCURRENT_SUBTASKS));
     const fromEnv = Number(process.env.NEXRALL_MAX_CONCURRENT_SUBTASKS);
     if (Number.isFinite(fromEnv) && fromEnv > 0)
         return clamp(fromEnv);
@@ -703,11 +781,11 @@ function subTaskLimiter(depth, workDir) {
     if (!run) {
         // TAPERED per level, not `max` at every level.
         //
-        // Giving each depth the full `max` multiplies total concurrency by the depth limit: 4
-        // becomes 12 by default and 16×5 = 80 at the configured maxima. The value is justified by
+        // Giving each depth the full `max` multiplies total concurrency by the depth limit: 10
+        // becomes 30 by default and 32×5 = 160 at the configured maxima. The value is justified by
         // shared resources — CPU, file handles, ONE API rate limit — none of which care which
         // level a loop is running at, so honouring `4` per level silently abandons the limit the
-        // user set. Halving per level bounds the total at ~2× `max` (4+2+1 = 7) while keeping the
+        // user set. Halving per level bounds the total at ~2× `max` (10+5+3 = 18 by default) while keeping the
         // per-depth structure that makes the wait-for graph acyclic.
         //
         // Never below 1: a level with 0 slots is a permanent hang, not a restriction.
@@ -724,22 +802,19 @@ function _resetSubTaskLimiter() {
     _subTaskLimitMaxByDepth.clear();
     _inFlightByDepth.clear();
     _subTaskLimitMax = 0;
-    _subAgentsThisSession = 0;
-    _sessionCapMax = 0;
-    _sessionCapNotified = false;
+    _subAgentBudgets.clear();
+}
+const _subAgentBudgets = new Map();
+const PROCESS_BUDGET_KEY = '\0process';
+function budgetFor(sessionKey) {
+    const key = sessionKey || PROCESS_BUDGET_KEY;
+    let b = _subAgentBudgets.get(key);
+    if (!b) {
+        b = { used: 0, max: 0, notified: false };
+        _subAgentBudgets.set(key, b);
+    }
+    return b;
 }
-// Counts sub-agents STARTED, never decremented — that is what makes it a budget rather
-// than a concurrency gate.
-//
-// NOT process-wide, unlike the limiter, and the distinction is load-bearing. A concurrency
-// gate is safe to share across a process because it self-drains; a monotonic counter is
-// not. In the CLI one process is one session, but VS Code calls runAgentLoop from a
-// long-lived extension host, so process-scoped state would accumulate across every
-// conversation in the window until delegation died permanently — and the remedy string
-// ("start a new session") would be a lie, since only reloading the window would help.
-let _subAgentsThisSession = 0;
-let _sessionCapMax = 0;
-let _sessionCapNotified = false;
 /**
  * Start a fresh sub-agent budget. Call when a NEW conversation begins.
  *
@@ -747,10 +822,9 @@ let _sessionCapNotified = false;
  * host). A client that never calls it gets process-lifetime semantics, which is correct
  * for a one-shot CLI invocation.
  */
-function resetSessionSubAgentBudget() {
-    _subAgentsThisSession = 0;
-    _sessionCapMax = 0;
-    _sessionCapNotified = false;
+function resetSessionSubAgentBudget(sessionKey) {
+    // No key: the legacy "new conversation" call — reset the process-wide budget only.
+    _subAgentBudgets.delete(sessionKey || PROCESS_BUDGET_KEY);
 }
 /**
  * Claim one slot against the session total. Returns an error string when exhausted.
@@ -760,13 +834,15 @@ function resetSessionSubAgentBudget() {
  * the user never learns delegation was capped, which is the one thing a runaway guard has
  * to make visible.
  */
-function claimSessionSubAgentSlot(workDir, notify) {
-    if (!_sessionCapMax) {
-        _sessionCapMax = resolveMaxSubagentsPerSession(workDir ? (0, rules_1.loadSettings)(workDir).raw : {});
+function claimSessionSubAgentSlot(workDir, notify, sessionKey) {
+    const b = budgetFor(sessionKey);
+    if (!b.max) {
+        b.max = resolveMaxSubagentsPerSession(workDir ? (0, rules_1.loadSettings)(workDir).raw : {});
     }
-    if (_subAgentsThisSession >= _sessionCapMax) {
-        if (!_sessionCapNotified) {
-            _sessionCapNotified = true;
+    const _sessionCapMax = b.max;
+    if (b.used >= b.max) {
+        if (!b.notified) {
+            b.notified = true;
             notify?.(`\u26a0\ufe0f Sub-agent budget reached (${_sessionCapMax} this session) \u2014 further delegation is ` +
                 'blocked and the agent will continue without it. Raise "maxSubagentsPerSession" in ' +
                 '.nexrall/settings.json if this was legitimate work.');
@@ -775,7 +851,7 @@ function claimSessionSubAgentSlot(workDir, notify) {
             'runaway-delegation guard, not a per-task limit: do the remaining work directly, and say ' +
             'in your final message that you hit the delegation cap.');
     }
-    _subAgentsThisSession++;
+    b.used++;
     return null;
 }
 /**
@@ -794,13 +870,14 @@ function claimSessionSubAgentSlot(workDir, notify) {
  *
  * Floored at 0 so a double refund can never manufacture budget.
  */
-function refundSessionSubAgentSlot() {
-    if (_subAgentsThisSession > 0)
-        _subAgentsThisSession--;
+function refundSessionSubAgentSlot(sessionKey) {
+    const b = budgetFor(sessionKey);
+    if (b.used > 0)
+        b.used--;
 }
 /** Test-only: observe the session counter without exporting the mutable binding. */
-function _sessionSubAgentCount() {
-    return _subAgentsThisSession;
+function _sessionSubAgentCount(sessionKey) {
+    return budgetFor(sessionKey).used;
 }
 // ─── Peer message rendering ───────────────────────────────────────────────────
 //
@@ -830,7 +907,7 @@ function humanDescription(name, input) {
         case 'bash':
             return `Run: ${input.command ?? '(unknown)'}`;
         case 'search_files': {
-            const searchType = input.type === 'filename' ? 'filename' : 'content';
+            const searchType = input.type === 'filename' ? 'filename' : input.type === 'content' || input.context_lines ? 'content' : 'files';
             const inPath = input.path ? ` in ${input.path}` : '';
             return `Search ${searchType}: "${input.pattern ?? ''}"${inPath}`;
         }
@@ -1235,6 +1312,72 @@ function toolResultText(block) {
     }
     return '';
 }
+// ── Hard stop ─────────────────────────────────────────────────────────────────
+// The stall watchdog and the parent's Stop only SET a flag; runAgentLoop notices it at
+// the next boundary. A tool that never returns (an MCP server that ignores the abort,
+// a stuck editor-side call) meant that boundary never came and the parent hung forever.
+// After the flag is set, the child gets this long to wind down before we stop waiting.
+const HARD_STOPPED = Symbol('hard-stopped');
+function hardStopGraceMs() {
+    const v = Number(process.env.NEXRALL_SUBAGENT_HARD_STOP_MS);
+    return Number.isFinite(v) && v > 0 ? v : 30000;
+}
+function raceHardStop(run, abort) {
+    return new Promise((resolve, reject) => {
+        let grace = null;
+        const poll = setInterval(() => {
+            if (abort.aborted && !grace) {
+                grace = setTimeout(() => { clearInterval(poll); resolve(HARD_STOPPED); }, hardStopGraceMs());
+            }
+        }, 250);
+        const settle = () => { clearInterval(poll); if (grace)
+            clearTimeout(grace); };
+        run.then((v) => { settle(); resolve(v); }, (e) => { settle(); reject(e); });
+    });
+}
+/** Returned instead of waiting forever for a tool that ignored Stop. */
+const STOP_TIMEOUT_RESULT = {
+    error: 'Interrupted: this tool did not respond to Stop, so the agent stopped waiting for it.',
+    interrupted: true,
+};
+const STOP_GRACE_MS = 5000;
+function stopAwaiting(run, abort) {
+    if (!abort)
+        return run;
+    return new Promise((resolve, reject) => {
+        let grace = null;
+        const poll = setInterval(() => {
+            if (abort.aborted && !grace)
+                grace = setTimeout(() => { clearInterval(poll); resolve(STOP_TIMEOUT_RESULT); }, STOP_GRACE_MS);
+        }, 200);
+        const settle = () => { clearInterval(poll); if (grace)
+            clearTimeout(grace); };
+        run.then((v) => { settle(); resolve(v); }, (e) => { settle(); reject(e); });
+    });
+}
+/** Default turn limit for a sub-agent whose definition sets no `maxTurns`. */
+const DEFAULT_SUBAGENT_MAX_TURNS = 200;
+/** Stop reasons that mean the sub-agent did NOT deliver a finished report. */
+const ABNORMAL_SUBAGENT_STOPS = new Set([
+    'budget', 'stalled', 'stalled-repeat', 'output-limit', 'empty-response',
+    'no-balance', 'no-team-budget', 'team-unavailable', 'reported-elsewhere',
+]);
+/**
+ * Prepended to EVERY sub-agent's instructions (named or not) — Claude Code's
+ * "you are a sub-agent; your final message is the report" contract.
+ */
+const SUBAGENT_PREAMBLE = [
+    '# You are a sub-agent',
+    'The main agent started you for ONE delegated task. You cannot see its conversation with the user — only the task you were given — and you cannot ask the user anything: if something is ambiguous, make the most reasonable assumption and state it.',
+    'Your FINAL message is the only thing returned to the main agent, and the user does not see it directly. Make it a concise, self-contained report: what you found or changed (with file paths and line numbers), what you verified and how, and anything left undone or uncertain. Do not pad it, and do not paste whole files — cite locations instead.',
+].join('\n');
+function formatTokenCount(n) {
+    return n >= 1000000 ? `${(n / 1000000).toFixed(1)}M` : n >= 1000 ? `${(n / 1000).toFixed(1)}K` : String(n);
+}
+function formatElapsed(ms) {
+    const s = Math.round(ms / 1000);
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
 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.
@@ -1294,7 +1437,7 @@ started) {
     //
     // 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)) {
+    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.',
@@ -1341,7 +1484,9 @@ started) {
                 'do not create it and do not retry. Do the work yourself, or use a different sub-agent.',
         };
     }
-    let agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
+    // 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
@@ -1380,12 +1525,39 @@ started) {
     // `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.
-    const inheritedMd = agent?.lightPrompt ? '' : (options.nexrallMd ?? '');
-    const subNexrallMd = agent
-        ? `# Sub-agent role: ${agent.name}\n${agent.prompt}` +
-            (agentMemoryNotes ? `\n\n---\n\n${agentMemoryNotes}` : '') +
-            (inheritedMd ? `\n\n---\n\n${inheritedMd}` : '')
-        : options.nexrallMd;
+    //
+    // 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
+    // ("reviewer … 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,
+        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
@@ -1414,6 +1586,20 @@ started) {
     // it, so the allowlist stays the single source of truth for what this agent can do.
     if (allowed && memoryScope)
         allowed.add(exports.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
@@ -1461,12 +1647,42 @@ started) {
         // allowlist above, a restriction can only ever be narrowed by nesting, never shed.
         // Without the inherited half, `test-writer` 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 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 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 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 && !allowsTestOnlyWrite(req.tool, req.input)) {
             throw new 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.');
         }
-        return options.requestPermission(req);
+        // 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 === exports.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 ──────────
     //
@@ -1507,6 +1723,10 @@ started) {
     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;
@@ -1520,11 +1740,83 @@ started) {
         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) · ${formatTokenCount(subTokens)} tokens · ` +
+            `$${subCost.toFixed(3)} · ${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;
-        const result = await runAgentLoop(subMessages, {
+        const childRun = runAgentLoop(subMessages, {
             ...options,
             _depth: depth + 1,
             _agentScope: `sub_${++_subTaskCounter}`, // isolated todo store per sub-agent
@@ -1562,16 +1854,48 @@ started) {
             // 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: agent?.model ?? options.model,
+            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 ?? 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.
-            planMode: options.planMode,
+            // `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: options.worktree,
+            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
@@ -1581,22 +1905,10 @@ started) {
             abortSignal: subAbort,
             requestPermission: gatedPermission,
             onText: () => { }, // sub-agent text is returned as the tool result, not streamed live
-            // Forwarded DELIBERATELY, and it must be a real handler rather than a no-op.
-            //
-            // A sub-agent streams no text (onText above is a no-op) but it DOES stream thinking
-            // through the parent's UI (see onThinking/onThinkingDelta below), and thinking sets
-            // `emittedToCaller`. So a sub-agent stream that dies after reasoning genuinely has
-            // rendered output to discard — a no-op here would let the restart proceed and then
-            // re-stream that reasoning on top of the copy still on screen, the exact duplication
-            // the opt-in exists to prevent.
-            //
-            // Forwarding is safe because the parent's own output is already closed by this
-            // point: dispatching the `task` tool goes through options.onToolUse, which finalizes
-            // the parent's bubble (VS Code) / flushes the renderer (CLI) before the sub-agent
-            // starts. The only live, discardable element at restart time is the sub-agent's own
-            // thinking block. Completed tool rows are left alone — those are real side effects
-            // that actually happened.
-            onStreamRestart: (reason, chars) => options.onStreamRestart?.(reason, chars),
+            // 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).
@@ -1604,17 +1916,32 @@ started) {
             // 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.
-            onToolUse: (n, i) => { bumpProgress(); options.onToolUse(n, i, true); },
-            onToolResult: (n, r) => { bumpProgress(); options.onToolResult(n, r, true); },
-            onToolStreamChunk: (n, c) => options.onToolStreamChunk?.(n, c, true),
-            // Forward thinking so the UI shows the indicator while sub-agent reasons
-            // Thinking is progress too — a model reasoning for minutes on a hard problem is
-            // working, not stalled. Without this, deep reasoning on an expensive tier would
-            // trip the watchdog precisely when the sub-agent was most valuable.
-            onThinking: (text) => { bumpProgress(); options.onThinking?.(text); },
-            onThinkingDelta: (text) => { bumpProgress(); options.onThinkingDelta?.(text); },
-            onThinkingProgress: (tok) => { bumpProgress(); options.onThinkingProgress?.(tok); },
+            // `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 raceHardStop(childRun, subAbort);
+        if (raced === 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(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
@@ -1642,7 +1969,7 @@ started) {
             // 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);
+            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.',
@@ -1656,27 +1983,49 @@ started) {
             // 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 { error: sections.join('\n\n') };
+            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 && ABNORMAL_SUBAGENT_STOPS.has(stopReasonOfChild) && !subAbort.aborted) {
+            const partial = capSubTaskText(extractSubTaskText(result, false));
+            const progress = 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 ?? 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 = capSubTaskText(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.
         //
-        // Only on NORMAL completion. A timed-out or failed run is deliberately not
-        // resumable: its transcript ends mid-thought, often mid-tool-call, and
-        // resuming from that state invites the model to build on work whose status
-        // it cannot determine. Those paths already salvage their partial output as
-        // TEXT, which is the safe way to carry that information forward.
+        // (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), resumed.id)
-            : (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result, agentScope);
+            ? ((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 {
+        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
@@ -1694,13 +2043,18 @@ started) {
                 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 { error: sections.join('\n\n') };
+            return finalize({ error: sections.join('\n\n') });
         }
-        return { error: `Sub-task failed: ${err.message}` };
+        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);
     }
 }
 // ─── Auto-compact ─────────────────────────────────────────────────────────────
@@ -1738,7 +2092,7 @@ const MODEL_CONTEXT_TOKENS = {
     ultra: 1000000,
     fast: 200000,
     // Anthropic, by real model id.
-    'claude-sonnet-5': 1000000,
+    'claude-sonnet-5-5': 1000000,
     'claude-opus-5-5': 1000000,
     'claude-fable-5-1': 1000000,
     'claude-haiku-4-5-20251001': 200000,
@@ -1806,13 +2160,13 @@ function contextWindowFor(model) {
 //     session that is real money accruing per turn long before the 1M wall.
 //     Anthropic's own server-side compaction defaults its trigger to 150K
 //     input tokens (docs: compact_20260112 default trigger 150000). We mirror
-//     that intent: start shedding already-consumed tool_result bulk at ~35% of
-//     a 1M window (~350K tokens) so the per-turn cache-read bill stops growing,
+//     that intent: start shedding already-consumed tool_result bulk at ~120K
+//     tokens (see compactionLimits) so the per-turn cache-read bill stops growing,
 //     WITHOUT paying for a summariser model call and WITHOUT dropping any turn
 //     (pruneOldToolResults keeps every tool_use/tool_result pair intact).
 //
-//   • SUMMARISE threshold (expensive: a real model call, lossy: drops whole
-//     turns): stays LATE, because summarise-of-summarise is the main cause of an
+//   • SUMMARISE threshold (a model call, lossy: drops whole turns): Claude Code's
+//     ~167K line (see compactionLimits). Later than prune, because summarise-of-summarise is the main cause of an
 //     agent "forgetting" earlier work. Only when cheap pruning can't keep the
 //     prompt under this line do we fall through to summarisation.
 //
@@ -1821,17 +2175,67 @@ function envFraction(name, fallback) {
     const v = Number(process.env[name]);
     return Number.isFinite(v) && v > 0 && v < 1 ? v : fallback;
 }
-// Prune early (~35% of window), summarise late (~80% of window).
-const AUTO_PRUNE_THRESHOLD = envFraction('NEXRALL_PRUNE_THRESHOLD', 0.35);
-const AUTO_COMPACT_THRESHOLD = envFraction('NEXRALL_COMPACT_THRESHOLD', 0.8); // summarise when prompt > 80% of the window
+// Where auto-compaction fires, in TOKENS — Claude Code's rule, not a fraction of a 1M window.
+//
+// Claude Code summarises at `window − min(maxOutput, 20K) − 13K buffer`, on a 200K window
+// (~167K tokens). We used to wait for 80% of a 1M window (~800K): every request of a long
+// run re-read that whole prefix from cache, so a session cost ~5× more per request than
+// the same work in Claude Code long before anything was shed. The window used for this is
+// capped (default 200K, like Claude Code) — the model's real 1M window still bounds what
+// the backend will accept; this only decides when WE tidy up.
+//
+//   NEXRALL_COMPACT_WINDOW / settings.json "autoCompactWindow": the cap (tokens). Set it
+//     to e.g. 1000000 to use the whole window before compacting.
+//   NEXRALL_PRUNE_THRESHOLD / NEXRALL_COMPACT_THRESHOLD: fractions of that capped window.
+const DEFAULT_COMPACT_WINDOW = 200000;
+const COMPACT_OUTPUT_RESERVE = 20000; // Claude Code: min(model max output, 20K)
+const COMPACT_BUFFER_TOKENS = 13000; // Claude Code's autocompact buffer
+const DEFAULT_PRUNE_FRACTION = 0.6; // cheap lossless prune ~120K, before the ~167K summarise
+function compactWindowCap(settingsRaw) {
+    const fromEnv = Number(process.env.NEXRALL_COMPACT_WINDOW);
+    if (Number.isFinite(fromEnv) && fromEnv >= 50000)
+        return fromEnv;
+    const fromSettings = Number(settingsRaw?.autoCompactWindow);
+    if (Number.isFinite(fromSettings) && fromSettings >= 50000)
+        return fromSettings;
+    return DEFAULT_COMPACT_WINDOW;
+}
+/** Token counts at which auto-prune and auto-compact (summarise) fire for a model window. */
+function compactionLimits(contextWindow, settingsRaw) {
+    const eff = Math.min(contextWindow, compactWindowCap(settingsRaw));
+    const compactFrac = envFraction('NEXRALL_COMPACT_THRESHOLD', 0);
+    const pruneFrac = envFraction('NEXRALL_PRUNE_THRESHOLD', 0);
+    const compact = compactFrac
+        ? eff * compactFrac
+        : Math.max(eff * 0.5, eff - Math.min(COMPACT_OUTPUT_RESERVE, eff * 0.1) - COMPACT_BUFFER_TOKENS);
+    const prune = Math.min(pruneFrac ? eff * pruneFrac : eff * DEFAULT_PRUNE_FRACTION, compact * 0.9);
+    return { prune: Math.floor(prune), compact: Math.floor(compact) };
+}
 /** Auto-prune / auto-compact thresholds as fractions of the context window — for UI display (e.g. `/context`). */
-function compactionThresholds() {
-    return { prune: AUTO_PRUNE_THRESHOLD, compact: AUTO_COMPACT_THRESHOLD };
+function compactionThresholds(contextWindow = 1000000, settingsRaw) {
+    const { prune, compact } = compactionLimits(contextWindow, settingsRaw);
+    return { prune: prune / contextWindow, compact: compact / contextWindow };
 }
 // Only bother pruning if it reclaims a meaningful amount — a tiny prune busts
 // the message-level prompt cache (the pruned prefix changes) for little gain,
 // so we require at least this many bytes reclaimed before accepting a prune.
-const PRUNE_MIN_RECLAIM_BYTES = 256 * 1024; // 256 KB
+// Sized for the ~120K-token prune line: at 256 KB a prune could rarely reclaim enough to
+// qualify, so sessions skipped straight to the lossy summariser.
+const PRUNE_MIN_RECLAIM_BYTES = 96 * 1024; // 96 KB
+// Cache-aware prune floor. The 96 KB floor exists ONLY to avoid busting a WARM prompt
+// cache for a small gain. Once the session has been idle past the provider cache TTL
+// (Anthropic/OpenAI: 5 min), the whole prefix is re-written on the next request anyway,
+// so a prune at that moment costs nothing extra — accept a much smaller reclaim then.
+// Keyed by sessionId (same scheme as _subAgentBudgets) because runAgentLoop runs once
+// per user turn and the idle gap that matters is BETWEEN turns.
+const PRUNE_MIN_RECLAIM_BYTES_COLD = 16 * 1024; // 16 KB
+const CACHE_COLD_AFTER_MS = 5 * 60000;
+const _lastApiCallEndedAt = new Map();
+function pruneReclaimFloor(lastCallEndedAt, now = Date.now()) {
+    return lastCallEndedAt !== undefined && now - lastCallEndedAt >= CACHE_COLD_AFTER_MS
+        ? PRUNE_MIN_RECLAIM_BYTES_COLD
+        : PRUNE_MIN_RECLAIM_BYTES;
+}
 const COMPACT_KEEP_MIN = 6; // always keep at least the last N messages verbatim
 /**
  * Bytes a compaction must reclaim to count as productive.
@@ -1991,10 +2395,27 @@ const MAX_TRANSCRIPT_CHARS = 600000;
  * middle — a middle-out elision that preserves both "what we set out to do" and
  * "where we are now", which is what the continuation summary needs most.
  */
+/**
+ * Appends the backend-announced runtime-context block to the user message it was
+ * attached to. No-op if that message is not a user turn or already ends with the
+ * identical block. Exported for tests.
+ */
+function persistRuntimeContext(messages, idx, text) {
+    const m = messages[idx];
+    if (!m || m.role !== 'user' || !Array.isArray(m.content))
+        return false;
+    const lastBlock = m.content[m.content.length - 1];
+    if (lastBlock && lastBlock.type === 'text' && lastBlock.text === text)
+        return false;
+    messages[idx] = { ...m, content: [...m.content, { type: 'text', text }] };
+    return true;
+}
 function transcriptOf(messages) {
     const parts = [];
     for (const m of messages) {
         for (const b of m.content) {
+            if ((0, types_1.isRuntimeContextBlock)(b))
+                continue; // editor scaffolding, not conversation
             if (b.type === 'text' && b.text) {
                 parts.push(`${m.role.toUpperCase()}: ${(0, safeSlice_1.sliceSafeEnd)(b.text, 2000)}`);
             }
@@ -2253,7 +2674,7 @@ function originalTaskText(messages) {
     if (!first || !Array.isArray(first.content))
         return '';
     return first.content
-        .filter((b) => b.type === 'text' && b.text)
+        .filter((b) => b.type === 'text' && b.text && !(0, types_1.isRuntimeContextBlock)(b))
         .map((b) => b.text)
         .join('\n')
         .trim();
@@ -2278,7 +2699,32 @@ class CompactionUnavailableError extends Error {
         this.name = 'CompactionUnavailableError';
     }
 }
-async function autoCompactMessages(messages, options, ledger) {
+function makeCachedSummarizer(messages, requestOptions, abortSignal) {
+    return async (instruction) => {
+        const last = messages[messages.length - 1];
+        if (!last || last.role !== 'user')
+            return '';
+        const lastContent = typeof last.content === 'string'
+            ? [{ type: 'text', text: last.content }]
+            : [...last.content];
+        const probe = [
+            ...messages.slice(0, -1),
+            { ...last, content: [...lastContent, { type: 'text', text: instruction }] },
+        ];
+        const reply = await (0, client_1.streamChat)(probe, { ...requestOptions(), abortSignal, allowRestartAfterRender: true }, () => { });
+        return reply.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('')
+            .trim();
+    };
+}
+const CACHED_SUMMARY_INSTRUCTION = `[Context compaction — this is an automated request from the agent runtime, not the user.]\n` +
+    `Do NOT call any tools and do NOT continue the task. Reply with text only: a concise bullet-point ` +
+    `summary of this whole session so far that you will need to continue the work — the user's goal, ` +
+    `key decisions, files changed (and how), commands run and their outcome, unresolved problems, and ` +
+    `user preferences. Max 400 words.`;
+async function autoCompactMessages(messages, options, ledger, summarizeCached) {
     const cut = findSafeCutIndex(messages, messages.length - COMPACT_KEEP_MIN);
     if (cut < 2)
         return false; // nothing meaningful to fold
@@ -2296,44 +2742,64 @@ async function autoCompactMessages(messages, options, ledger) {
         `key decisions, files changed (and how), commands run, unresolved problems, and user preferences. Max 400 words.\n\n` +
         transcriptOf(toSummarize);
     let summary = '';
-    try {
-        const reply = await (0, client_1.streamChat)([{ role: 'user', content: [{ type: 'text', text: summaryPrompt }] }], {
-            // Run on the SAME model as the actual conversation. A previous version
-            // forced 'turbo' (Claude Sonnet 5) here on the theory that a mechanical
-            // "bullet-point this transcript" task doesn't need the user's tier — but
-            // that silently billed Anthropic (and made a real network call to a
-            // provider the user may not have configured/paid for) even when the
-            // whole session was running on OpenAI/DeepSeek/Qwen. Whatever the user
-            // is already paying for is used for compaction too, so there is never a
-            // surprise charge on a different provider. Falls back to the same
-            // default as the main loop (see `runAgentLoop`) only when no model was
-            // set at all.
-            model: options.model ?? 'turbo',
-            mode: 'ask', // summariser must not call tools; ask-mode discourages action
-            env: options.env,
-            clientType: options.clientType,
-            abortSignal: options.abortSignal,
-            // The summariser renders NOTHING (onEvent below is a no-op) and its result is
-            // read only from the returned message, so a restart has nothing to roll back —
-            // always safe. Worth enabling: a blip here used to abandon compaction entirely,
-            // which then let the very next turn hit the context wall it was meant to prevent.
-            allowRestartAfterRender: true,
-        }, () => { });
-        summary = reply.content
-            .filter((b) => b.type === 'text')
-            .map((b) => b.text ?? '')
-            .join('')
-            .trim();
-    }
-    catch {
-        // Summarisation FAILED — the model call itself threw (network blip, 529,
-        // provider quota). Distinguished from "ran fine but didn't help" by the
-        // caller, because the two must not feed the same circuit breaker: three
-        // transient network errors would otherwise permanently disable compaction
-        // for the rest of the run, leaving the context to grow until the turn dies
-        // with no recovery left. Leave history as is; the turn may still fit.
-        throw new CompactionUnavailableError();
+    // Cache-friendly path first; any failure or empty reply falls back to the standalone
+    // transcript summariser below, which always works but pays for the history uncached.
+    if (summarizeCached) {
+        try {
+            summary = await summarizeCached(CACHED_SUMMARY_INSTRUCTION);
+        }
+        catch (err) {
+            if (options.abortSignal?.aborted || err.name === 'AbortError')
+                throw err;
+            summary = '';
+        }
     }
+    if (!summary)
+        try {
+            const reply = await (0, client_1.streamChat)([{ role: 'user', content: [{ type: 'text', text: summaryPrompt }] }], {
+                // Run on the SAME model as the actual conversation. A previous version
+                // forced 'turbo' (Claude Sonnet 5) here on the theory that a mechanical
+                // "bullet-point this transcript" task doesn't need the user's tier — but
+                // that silently billed Anthropic (and made a real network call to a
+                // provider the user may not have configured/paid for) even when the
+                // whole session was running on OpenAI/DeepSeek/Qwen. Whatever the user
+                // is already paying for is used for compaction too, so there is never a
+                // surprise charge on a different provider. Falls back to the same
+                // default as the main loop (see `runAgentLoop`) only when no model was
+                // set at all.
+                //
+                // Cheapest model of the SAME vendor (Claude Code runs this kind of work on
+                // Haiku). Safe to downgrade HERE because this fallback sends a fresh
+                // transcript — it shares no cached prefix with the conversation, unlike
+                // summarizeCached above, which must stay on the conversation's own model.
+                // Never crosses providers; falls back to the session model if the
+                // catalogue is not loaded.
+                model: (0, modelCatalogue_1.cheapestSameVendorModel)(options.model ?? 'turbo') ?? options.model ?? 'turbo',
+                mode: 'ask', // summariser must not call tools; ask-mode discourages action
+                env: options.env,
+                clientType: options.clientType,
+                abortSignal: options.abortSignal,
+                // The summariser renders NOTHING (onEvent below is a no-op) and its result is
+                // read only from the returned message, so a restart has nothing to roll back —
+                // always safe. Worth enabling: a blip here used to abandon compaction entirely,
+                // which then let the very next turn hit the context wall it was meant to prevent.
+                allowRestartAfterRender: true,
+            }, () => { });
+            summary = reply.content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text ?? '')
+                .join('')
+                .trim();
+        }
+        catch {
+            // Summarisation FAILED — the model call itself threw (network blip, 529,
+            // provider quota). Distinguished from "ran fine but didn't help" by the
+            // caller, because the two must not feed the same circuit breaker: three
+            // transient network errors would otherwise permanently disable compaction
+            // for the rest of the run, leaving the context to grow until the turn dies
+            // with no recovery left. Leave history as is; the turn may still fit.
+            throw new CompactionUnavailableError();
+        }
     if (!summary)
         return false;
     // Replace the summarized head with a single user summary message. The cut is
@@ -2375,7 +2841,9 @@ async function maybeCompactMemory(scope, options) {
                 // Same reasoning as autoCompactMessages' summariser: run on the same
                 // model as the actual conversation rather than forcing a fixed tier
                 // (which silently billed Anthropic regardless of the user's provider).
-                model: options.model ?? 'turbo',
+                // Cheapest SAME-vendor model: a fresh prompt with no shared cache prefix,
+                // and merging a few memory bullets does not need the session's top tier.
+                model: (0, modelCatalogue_1.cheapestSameVendorModel)(options.model ?? 'turbo') ?? options.model ?? 'turbo',
                 mode: 'ask',
                 env: options.env,
                 clientType: options.clientType,
@@ -2446,8 +2914,9 @@ async function compactMessagesForResume(messages, opts) {
     // only at the late one. On resume this matters most: a stored session is resent
     // whole on the first turn, so shedding old tool_result bulk up front is exactly
     // what stops that first message being billed at full size.
-    const overPruneThreshold = () => tokenGuess > contextWindow * AUTO_PRUNE_THRESHOLD || bodyBytes > MAX_BODY_BYTES;
-    const overCompactThreshold = () => tokenGuess > contextWindow * AUTO_COMPACT_THRESHOLD || bodyBytes > MAX_BODY_BYTES;
+    const limits = compactionLimits(contextWindow, settings.raw);
+    const overPruneThreshold = () => tokenGuess > limits.prune || bodyBytes > MAX_BODY_BYTES;
+    const overCompactThreshold = () => tokenGuess > limits.compact || bodyBytes > MAX_BODY_BYTES;
     if (!overPruneThreshold())
         return false;
     let compacted = false;
@@ -2525,7 +2994,7 @@ async function compactMessagesForResume(messages, opts) {
  */
 async function dispatchSubAgent(input, options, agentTypes) {
     const depth = options._depth ?? 0;
-    const overBudget = claimSessionSubAgentSlot(options.workDir, options.onNotice ?? options.onText);
+    const overBudget = claimSessionSubAgentSlot(options.workDir, options.onNotice ?? options.onText, options.sessionId);
     if (overBudget)
         return { error: overBudget };
     const childDepth = depth + 1;
@@ -2543,7 +3012,7 @@ async function dispatchSubAgent(input, options, agentTypes) {
     }
     finally {
         if (!started.value)
-            refundSessionSubAgentSlot();
+            refundSessionSubAgentSlot(options.sessionId);
         const n = (_inFlightByDepth.get(childDepth) ?? 1) - 1;
         if (n > 0)
             _inFlightByDepth.set(childDepth, n);
@@ -2551,11 +3020,81 @@ async function dispatchSubAgent(input, options, agentTypes) {
             _inFlightByDepth.delete(childDepth);
     }
 }
+/**
+ * `task` with run_in_background — start the sub-agent detached and return at once.
+ *
+ * The child runs with its OWN abort signal (the user's Stop on the main turn does not
+ * kill it; the hub's stop() does), renders nothing into the chat (its tool calls are
+ * only counted for the "N agents" badge), and cannot prompt the user: a call that the
+ * project's rules or the session mode do not already allow is refused with an
+ * explanation, which the child then reports (Claude Code auto-denies the same way).
+ * Its final report reaches the main agent as a <task-notification>.
+ */
+function dispatchBackgroundSubAgent(input, options, agentTypes, hub) {
+    const overBudget = claimSessionSubAgentSlot(options.workDir, options.onNotice ?? options.onText, options.sessionId);
+    if (overBudget)
+        return { error: overBudget };
+    const agentType = (typeof input.subagent_type === 'string' && input.subagent_type) || 'general-purpose';
+    const description = (typeof input.description === 'string' && input.description.trim())
+        || String(input.prompt ?? '').trim().slice(0, 60) || agentType;
+    const mode = (0, modePolicy_1.parseMode)(options.mode);
+    const backgroundPermission = async (req) => {
+        const rule = (0, rules_1.evaluatePermission)((0, rules_1.loadSettings)(options.workDir).permissions, req.tool, req.input, options.workDir);
+        if (rule === 'deny')
+            throw new ToolNotAllowedError(`\`${req.tool}\` is denied by a permission rule in this project.`);
+        if (rule === 'allow')
+            return true;
+        const destructive = !!(0, destructive_1.isDestructiveBash)(req.tool, req.input);
+        if ((0, modePolicy_1.decide)({ tool: req.tool, input: req.input, mode, destructive }) === 'allow')
+            return true;
+        throw new ToolNotAllowedError(`Background agents cannot ask the user for permission, and \`${req.tool}\` is not pre-approved in the ` +
+            `current mode (${mode}). Do not retry it: finish what you can without it and say in your report that ` +
+            'this step needs the main agent (or the user) to run it.');
+    };
+    const started = hub.start({ description, agentType }, async ({ abort, onToolUse }) => {
+        const didStart = { value: false };
+        try {
+            return await runSubTask(input, {
+                ...options,
+                abortSignal: abort,
+                backgroundAgents: undefined,
+                requestPermission: backgroundPermission,
+                onText: () => { },
+                onNotice: () => { },
+                onToolUse: (name) => onToolUse(name),
+                onToolResult: () => { },
+                onToolStreamChunk: undefined,
+                onThinking: undefined,
+                onThinkingDelta: undefined,
+                onThinkingProgress: undefined,
+                onStreamRestart: undefined,
+                onRetry: undefined,
+                onRetryResolved: undefined,
+            }, agentTypes, didStart);
+        }
+        finally {
+            if (!didStart.value)
+                refundSessionSubAgentSlot(options.sessionId);
+        }
+    });
+    if ('error' in started) {
+        refundSessionSubAgentSlot(options.sessionId);
+        return { error: started.error };
+    }
+    return {
+        output: `Started background agent ${started.id} ("${description}", ${agentType}). It runs independently: its ` +
+            'report will arrive automatically as a <task-notification> in a later turn. Do not poll for it, do not ' +
+            'wait for it, and do not duplicate its work — continue with something else, or end your turn if nothing ' +
+            'else needs doing now.',
+    };
+}
 // ─── Agent Loop ───────────────────────────────────────────────────────────────
 async function runAgentLoop(initialMessages, options) {
     const messages = [...initialMessages];
     const model = options.model ?? 'turbo';
-    const hooks = loadHooks(options.workDir);
+    // An agent definition's own hooks apply only to its own run (appended after the
+    // project's, which run first) — runSubTask sets _agentHooks per child, never inherits it.
+    const hooks = withAgentHooks(loadHooks(options.workDir), options._agentHooks);
     const depth = options._depth ?? 0;
     const agentScope = options._agentScope ?? 'root';
     // ── Audit trail (opt-in) ────────────────────────────────────────────────────
@@ -2627,6 +3166,62 @@ async function runAgentLoop(initialMessages, options) {
         options.worktree ? (0, worktreeEnforcement_1.worktreeInstructions)(options.worktree) : null,
         options.nexrallMd ?? null,
     ].filter((s) => s !== null).join('\n\n---\n\n') || undefined; // '' (nothing at all was present) must behave exactly like the old `: options.nexrallMd` fallback (undefined), not an empty-but-truthy string.
+    // The request options every main-loop call sends. Shared with the compaction
+    // summariser so its request has the SAME system prompt and tools as the conversation
+    // — that is what lets the summary call read the whole history from cache (0.10×)
+    // instead of re-sending it as a fresh, uncached transcript.
+    const chatRequestOptions = () => ({
+        model,
+        mode: options.mode,
+        effort: options.effort,
+        env: options.env,
+        editorContext: options.editorContext,
+        nexrallMd: planAndWorktreeAwareNexrallMd,
+        clientType: options.clientType,
+        abortSignal: options.abortSignal,
+        // MCP tools, plus the per-agent memory tool when (and only when) this run
+        // is a sub-agent that declared a `memory:` scope. Declaring it through
+        // extraTools rather than the backend's static catalogue keeps it invisible
+        // to every other run: a tool the model cannot see is one it cannot try,
+        // which is better than advertising it everywhere and refusing it at the gate.
+        extraTools: [
+            ...(options.mcpManager?.getAnthropicTools() ?? [])
+                .filter((t) => !options._mcpServerAllowlist || options._mcpServerAllowlist.has(String(t.name).split('__')[0])),
+            ...(options._agentMemory ? [exports.AGENT_MEMORY_TOOL_SCHEMA] : []),
+        ],
+        // Derived from the run's ACTUAL allowlist rather than asserted separately,
+        // so the prompt's memory instructions cannot drift from what is permitted.
+        // That drift is the bug being fixed: sub-agents were told they MUST call
+        // memory_write, which no sub-agent allowlist contains.
+        // Sub-agents NEVER write the shared store (the main agent decides what to persist) —
+        // an unnamed/general-purpose child has no allowlist, which used to read as "may write".
+        canWriteSharedMemory: depth > 0
+            ? false
+            : options._allowedTools
+                ? options._allowedTools.has('memory_write')
+                : true, // no allowlist = main agent = may write
+        hasOwnAgentStore: !!options._agentMemory,
+        // Same derivation, same reason, for the network. The base prompt's
+        // "Web search" section tells the run to reach the network, but
+        // READ_ONLY_TOOLS (explorer, security-auditor, ...) contains neither
+        // `fetch_url` nor `web_search`. MEASURED on the 195-trial 2026-08-10
+        // deepseek-v4-pro benchmark: 29 of 51 `fetch_url` failures and 3 of 14
+        // `web_search` failures were the permission gate refusing a sub-agent
+        // that its own system prompt had just invited to browse — every one a
+        // wasted round-trip on a paid turn.
+        canBrowseWeb: options._allowedTools
+            ? options._allowedTools.has('fetch_url') || options._allowedTools.has('web_search')
+            : true, // no allowlist = main agent = may browse
+        // Only the tools this run may use are sent as schemas — explorer no longer pays for
+        // (and gets refused on) write, office and image tools. Sorted so the tools cache
+        // prefix is identical for every run of the same agent type.
+        toolAllowlist: options._allowedTools ? [...options._allowedTools].sort() : undefined,
+        // Withholds the `task` schema and its instructions when this run cannot
+        // delegate — see canSpawnSubAgents.
+        canSpawnSubAgents: maySpawn,
+        agents: agentsCatalogue || undefined,
+        skills: skillsCatalogue || undefined,
+    });
     // Optional OS-level bash sandbox (opt-in via settings.json "sandbox").
     const sandboxCfg = (0, sandbox_1.parseSandboxConfig)(settings.raw.sandbox) ?? undefined;
     // Soft iteration budget + optional auto-continue past it (see resolvers above).
@@ -2637,6 +3232,11 @@ async function runAgentLoop(initialMessages, options) {
     // Live catalogue first (see contextWindowFor's doc comment above for why),
     // same fallback chain this call site always used otherwise.
     const contextWindow = (0, modelCatalogue_1.liveContextWindowFor)(model, MODEL_CONTEXT_TOKENS[model] ?? 200000);
+    const compactLimits = compactionLimits(contextWindow, settings.raw);
+    // Per-run: a sub-agent's own runAgentLoop gets its own, so it never sees its parent's reads.
+    const readDedupe = new readDedupe_1.ReadDedupe(options.workDir);
+    // Only the main agent owns background agents (runSubTask never passes the hub down).
+    const drainBackgroundNotifications = () => depth === 0 ? (options.backgroundAgents?.takeNotifications() ?? []) : [];
     // Live prompt-size estimate, updated from usage events after every stream.
     let lastPromptTokens = 0;
     let compacting = false; // re-entrancy guard — compaction itself calls streamChat
@@ -2758,22 +3358,22 @@ async function runAgentLoop(initialMessages, options) {
             // every single turn on a long task. Runs at a turn boundary only.
             //
             // THREE nested triggers, cheapest/earliest first:
-            //   1. PRUNE pressure — prompt crossed AUTO_PRUNE_THRESHOLD (~35% of window)
+            //   1. PRUNE pressure — prompt crossed compactLimits.prune (~120K tokens)
             //      OR the body crossed MAX_BODY_BYTES. Handled by the CHEAP, structure-
             //      preserving prune (no model call, keeps every turn). This is the big
             //      cost win: it fires ~2× earlier than summarisation used to, shedding
             //      already-consumed tool_result bulk (read_file/bash/grep output the
             //      model has long since acted on) so the per-turn cache-read bill stops
             //      compounding well before the old 80% wall.
-            //   2. SUMMARISE pressure — prompt crossed AUTO_COMPACT_THRESHOLD (~80%) or
+            //   2. SUMMARISE pressure — prompt crossed compactLimits.compact (~167K, Claude Code's line) or
             //      the body is STILL over MAX_BODY_BYTES after pruning. Only then do we
             //      pay for a summariser call + drop whole turns (kept late on purpose:
             //      summarise-of-summarise is what makes an agent "forget" earlier work).
             // The byte trigger also fires even on turn 0 of a resumed large session,
             // where lastPromptTokens is 0.
             let bodyBytes = estimateBodyBytes(messages);
-            const prunePressure = lastPromptTokens > contextWindow * AUTO_PRUNE_THRESHOLD;
-            const tokenPressure = lastPromptTokens > contextWindow * AUTO_COMPACT_THRESHOLD;
+            const prunePressure = lastPromptTokens > compactLimits.prune;
+            const tokenPressure = lastPromptTokens > compactLimits.compact;
             let bytePressure = bodyBytes > MAX_BODY_BYTES;
             // Cheap prune first — on token OR byte pressure. Require a meaningful reclaim
             // (PRUNE_MIN_RECLAIM_BYTES): a tiny prune would bust the message-level prompt
@@ -2784,16 +3384,18 @@ async function runAgentLoop(initialMessages, options) {
                 // The gate lives INSIDE pruneOldToolResults now (atomic: it measures the
                 // total first and mutates nothing if it's below the floor), so a declined
                 // prune never invalidates the prompt cache.
-                const reclaimed = pruneOldToolResults(messages, PRUNE_MIN_RECLAIM_BYTES);
+                // Main agent only: a sub-agent's own cache is warm while it works, but it would read
+                // the PARENT's last-call time, which goes stale exactly while the parent waits on it.
+                const floor = depth === 0
+                    ? pruneReclaimFloor(_lastApiCallEndedAt.get(options.sessionId || PROCESS_BUDGET_KEY))
+                    : PRUNE_MIN_RECLAIM_BYTES;
+                const reclaimed = pruneOldToolResults(messages, floor);
                 if (reclaimed > 0) {
                     bodyBytes = estimateBodyBytes(messages);
                     bytePressure = bodyBytes > MAX_BODY_BYTES;
-                    // System notice, NOT model output — route through onNotice (falls back to
-                    // onText only if the caller hasn't been updated yet) so the UI can render
-                    // it as a small dim/system line instead of splicing it into the middle of
-                    // the assistant's own streamed reply, where it reads like the model itself
-                    // said "Trimmed ~0.3MB of already-processed tool output…".
-                    (options.onNotice ?? options.onText)(`\u267b\ufe0f Trimmed ~${(reclaimed / (1024 * 1024)).toFixed(1)}MB of already-processed tool output to keep this chat cheap to continue.`);
+                    // Silent by design: routine housekeeping the user can't act on. It used to
+                    // print "♻️ Trimmed ~0.1MB of already-processed tool output…" into the chat,
+                    // which read as noise (and, before onNotice, as the model's own words).
                 }
             }
             // Re-arm the breaker once the conversation has grown materially past the
@@ -2816,7 +3418,7 @@ async function runAgentLoop(initialMessages, options) {
                     let did = false;
                     let unavailable = false;
                     try {
-                        did = await autoCompactMessages(messages, options, ledger);
+                        did = await autoCompactMessages(messages, options, ledger, makeCachedSummarizer(messages, chatRequestOptions, options.abortSignal));
                     }
                     catch (err) {
                         if (!(err instanceof CompactionUnavailableError))
@@ -2830,9 +3432,9 @@ async function runAgentLoop(initialMessages, options) {
                         const reason = bytePressure
                             ? `body ~${(bodyBytes / (1024 * 1024)).toFixed(1)}MB`
                             : 'context window';
-                        // Same reasoning as above: this is a system notice about housekeeping,
-                        // not part of the model's answer — keep it out of the text bubble.
-                        (options.onNotice ?? options.onText)(`\u267b\ufe0f Auto-compacted earlier conversation to stay within the ${reason}.`);
+                        // Silent, same as the prune above — routine housekeeping. Only the
+                        // actionable "auto-compaction paused" warning below is surfaced.
+                        void reason;
                         // Refresh local pressure so the rest of THIS iteration sees the new size.
                         bodyBytes = bytesAfter;
                         bytePressure = bodyBytes > MAX_BODY_BYTES;
@@ -2874,6 +3476,16 @@ async function runAgentLoop(initialMessages, options) {
             if (!autoContinue && iteration === budget - 5 && budget > 5) {
                 options.onText(`\n⚠️ Approaching the ${budget}-step limit (step ${iteration + 1}). Please wrap up and summarise what has been done.\n`);
             }
+            // Runtime-context block the backend appended to this request's final user message
+            // (see SSERuntimeContextEvent). Applied only AFTER streamChat succeeds: mutating
+            // `messages` mid-stream would change the request hash a same-turnId retry sends,
+            // and the backend would then run (and bill) it as a brand-new turn.
+            let pendingRuntimeContext = null;
+            const sentUserIdx = messages.length - 1;
+            // Pure-read tools announced mid-stream (tool_use_ready) start here, before the
+            // message is complete. Results are only reused after every gate below passes.
+            const prefetcher = new toolPrefetch_1.ToolPrefetcher((toolName, toolInput) => (0, executor_1.executeTool)(toolName, toolInput, options.abortSignal, sandboxCfg, options.workDir, agentScope, undefined, options.selfPeer));
+            const prefetchOn = (0, toolPrefetch_1.toolPrefetchEnabled)();
             // Build SSE event handler
             const onEvent = (event) => {
                 switch (event.type) {
@@ -2943,11 +3555,20 @@ async function runAgentLoop(initialMessages, options) {
                         // an assumption: tools are dispatched from `assistantMessage.content` AFTER
                         // streamChat() returns, and a restarted attempt threw instead of returning.
                         // So no tool ran, no file changed, no checkpoint or hook fired.
+                        // The replacement attempt generates new tool_use ids; drop early reads.
+                        prefetcher.clear();
                         options.onStreamRestart?.(event.reason, event.discardedChars);
                         break;
                     case 'balance_status':
                         options.onBalanceStatus?.(event.balance, event.zero);
                         break;
+                    case 'runtime_context':
+                        pendingRuntimeContext = event.text;
+                        break;
+                    case 'tool_use_ready':
+                        if (prefetchOn && !options.abortSignal?.aborted)
+                            prefetcher.start(event.id, event.name, event.input);
+                        break;
                     case 'done':
                         break;
                     case 'error':
@@ -2965,47 +3586,7 @@ async function runAgentLoop(initialMessages, options) {
             const _apiCallStartedAt = Date.now();
             try {
                 assistantMessage = await (0, client_1.streamChat)(messages, {
-                    model,
-                    mode: options.mode,
-                    effort: options.effort,
-                    env: options.env,
-                    editorContext: options.editorContext,
-                    nexrallMd: planAndWorktreeAwareNexrallMd,
-                    clientType: options.clientType,
-                    abortSignal: options.abortSignal,
-                    // MCP tools, plus the per-agent memory tool when (and only when) this run
-                    // is a sub-agent that declared a `memory:` scope. Declaring it through
-                    // extraTools rather than the backend's static catalogue keeps it invisible
-                    // to every other run: a tool the model cannot see is one it cannot try,
-                    // which is better than advertising it everywhere and refusing it at the gate.
-                    extraTools: [
-                        ...(options.mcpManager?.getAnthropicTools() ?? []),
-                        ...(options._agentMemory ? [exports.AGENT_MEMORY_TOOL_SCHEMA] : []),
-                    ],
-                    // Derived from the run's ACTUAL allowlist rather than asserted separately,
-                    // so the prompt's memory instructions cannot drift from what is permitted.
-                    // That drift is the bug being fixed: sub-agents were told they MUST call
-                    // memory_write, which no sub-agent allowlist contains.
-                    canWriteSharedMemory: options._allowedTools
-                        ? options._allowedTools.has('memory_write')
-                        : true, // no allowlist = main agent = may write
-                    hasOwnAgentStore: !!options._agentMemory,
-                    // Same derivation, same reason, for the network. The base prompt's
-                    // "Web search" section tells the run to reach the network, but
-                    // READ_ONLY_TOOLS (explorer, security-auditor, ...) contains neither
-                    // `fetch_url` nor `web_search`. MEASURED on the 195-trial 2026-08-10
-                    // deepseek-v4-pro benchmark: 29 of 51 `fetch_url` failures and 3 of 14
-                    // `web_search` failures were the permission gate refusing a sub-agent
-                    // that its own system prompt had just invited to browse — every one a
-                    // wasted round-trip on a paid turn.
-                    canBrowseWeb: options._allowedTools
-                        ? options._allowedTools.has('fetch_url')
-                        : true, // no allowlist = main agent = may browse
-                    // Withholds the `task` schema and its instructions when this run cannot
-                    // delegate — see canSpawnSubAgents.
-                    canSpawnSubAgents: maySpawn,
-                    agents: agentsCatalogue || undefined,
-                    skills: skillsCatalogue || undefined,
+                    ...chatRequestOptions(),
                     // Only allow a post-render restart when the caller actually implements the
                     // rollback. Without a handler the partial output can't be un-rendered, so we
                     // keep the old conservative behaviour (fail the turn) rather than duplicate
@@ -3015,6 +3596,12 @@ async function runAgentLoop(initialMessages, options) {
                 // Measured on the SUCCESS path only — a throw below reports its own duration
                 // in the catch block, so this can't double-report the same call.
                 options.onApiCallDuration?.(Date.now() - _apiCallStartedAt);
+                if (depth === 0)
+                    _lastApiCallEndedAt.set(options.sessionId || PROCESS_BUDGET_KEY, Date.now());
+                // Persist the context block where the backend put it, so later rounds carry it
+                // in the cached history and the backend stops re-sending it uncached.
+                if (pendingRuntimeContext)
+                    persistRuntimeContext(messages, sentUserIdx, pendingRuntimeContext);
             }
             catch (err) {
                 options.onApiCallDuration?.(Date.now() - _apiCallStartedAt);
@@ -3070,7 +3657,7 @@ async function runAgentLoop(initialMessages, options) {
                     stopReason = 'team-unavailable';
                     break;
                 }
-                runSimpleHooks(hooks.OnError, options.workDir);
+                await runSimpleHooks(hooks.OnError, options.workDir);
                 // Carry the work already done in this turn out with the error. The loop
                 // owns a COPY of the caller's history, so a plain throw would strand every
                 // completed tool round inside this function and the caller would fall back
@@ -3094,7 +3681,8 @@ async function runAgentLoop(initialMessages, options) {
             if (assistantMessage.content.length === 0) {
                 const queued = options.takePendingInput?.() ?? [];
                 const peerMsgs = options.drainPeerMessages?.() ?? [];
-                if (queued.length || peerMsgs.length) {
+                const bgDone = drainBackgroundNotifications();
+                if (queued.length || peerMsgs.length || bgDone.length) {
                     const parts = [];
                     if (queued.length) {
                         parts.push(queued.join('\n\n'));
@@ -3104,6 +3692,8 @@ async function runAgentLoop(initialMessages, options) {
                         parts.push(renderPeerMessages(peerMsgs));
                         options.onPeerMessage?.(peerMsgs);
                     }
+                    if (bgDone.length)
+                        parts.push((0, backgroundAgents_1.formatBackgroundNotifications)(bgDone));
                     messages.push({ role: 'user', content: [{ type: 'text', text: parts.join('\n\n') }] });
                     continue;
                 }
@@ -3147,7 +3737,8 @@ async function runAgentLoop(initialMessages, options) {
                     iteration--;
                     continue;
                 }
-                runSimpleHooks(hooks.PostMessageComplete, options.workDir);
+                if (depth === 0)
+                    await runSimpleHooks(hooks.PostMessageComplete, options.workDir);
                 stopReason = assistantMessage.stopReason === 'max_tokens' ? 'output-limit' : 'empty-response';
                 break;
             }
@@ -3200,7 +3791,8 @@ async function runAgentLoop(initialMessages, options) {
             if (toolUseBlocks.length === 0) {
                 const queued = options.takePendingInput?.() ?? [];
                 const peerMsgs = options.drainPeerMessages?.() ?? [];
-                if (queued.length || peerMsgs.length) {
+                const bgDone = drainBackgroundNotifications();
+                if (queued.length || peerMsgs.length || bgDone.length) {
                     const parts = [];
                     if (queued.length) {
                         parts.push(queued.join('\n\n'));
@@ -3210,6 +3802,8 @@ async function runAgentLoop(initialMessages, options) {
                         parts.push(renderPeerMessages(peerMsgs));
                         options.onPeerMessage?.(peerMsgs);
                     }
+                    if (bgDone.length)
+                        parts.push((0, backgroundAgents_1.formatBackgroundNotifications)(bgDone));
                     messages.push({ role: 'user', content: [{ type: 'text', text: parts.join('\n\n') }] });
                     continue;
                 }
@@ -3307,15 +3901,21 @@ async function runAgentLoop(initialMessages, options) {
                         continue;
                     }
                 }
-                runSimpleHooks(hooks.PostMessageComplete, options.workDir);
+                if (depth === 0)
+                    await runSimpleHooks(hooks.PostMessageComplete, options.workDir);
                 stopReason = 'clean';
                 break;
             }
             // 5. Execute all tool uses in parallel
+            // Early reads are only valid if nothing in this message can change the files
+            // they read (a write ordered before them would otherwise be missed).
+            const prefetchSafe = prefetchOn && (0, toolPrefetch_1.isPrefetchSafeMessage)(toolUseBlocks.map((b) => b.name));
             const toolResults = await Promise.all(toolUseBlocks.map(async (block) => {
                 const { id, name, input } = block;
-                // Notify caller about pending tool use
-                options.onToolUse(name, input);
+                // Notify caller about pending tool use. `meta.id` lets the UI pair the result
+                // with THIS row even when parallel sub-agents interleave their events.
+                const toolMeta = { id };
+                options.onToolUse(name, input, undefined, toolMeta);
                 let result;
                 // Checked BEFORE requesting permission: no point asking the user to
                 // approve a diff/preview built from possibly-garbage truncated input
@@ -3338,7 +3938,7 @@ async function runAgentLoop(initialMessages, options) {
                                     : '') +
                             `so the full response fits comfortably under the per-turn output budget.`,
                     };
-                    options.onToolResult(name, result);
+                    options.onToolResult(name, result, undefined, toolMeta);
                     return { block: { ...block, id }, result };
                 }
                 // ── Plan mode: a session-wide read-only lock ────────────────────────
@@ -3352,7 +3952,7 @@ async function runAgentLoop(initialMessages, options) {
                     const refusal = (0, planMode_1.checkPlanMode)(name, input);
                     if (refusal) {
                         result = { error: refusal.message };
-                        options.onToolResult(name, result);
+                        options.onToolResult(name, result, undefined, toolMeta);
                         return { block: { ...block, id }, result };
                     }
                 }
@@ -3366,7 +3966,7 @@ async function runAgentLoop(initialMessages, options) {
                     const refusal = (0, worktreeEnforcement_1.checkWorktreeIsolation)(name, input, options.worktree, options.workDir);
                     if (refusal) {
                         result = { error: refusal.message };
-                        options.onToolResult(name, result);
+                        options.onToolResult(name, result, undefined, toolMeta);
                         return { block: { ...block, id }, result };
                     }
                 }
@@ -3397,10 +3997,36 @@ async function runAgentLoop(initialMessages, options) {
                     // depth 0) needs its own limiter. Extracted into dispatchSubAgent so
                     // `@nexrall/agent`'s delegate()/spawn() drive the SAME path instead of
                     // reimplementing depth/budget/concurrency enforcement a second time.
-                    result = await dispatchSubAgent(input, auditOptions, agentTypes);
+                    // Background only for the MAIN agent, and only when the host can deliver the
+                    // result later; otherwise it quietly runs in the foreground.
+                    const wantsBackground = input.run_in_background === true
+                        || (input.run_in_background !== false && !!(0, agentTypes_1.findAgentType)(agentTypes, String(input.subagent_type ?? ''))?.background);
+                    const taskOptions = { ...auditOptions, _taskToolUseId: id };
+                    // PreToolUse/PostToolUse cover spawns too (Claude Code's matcher "Task"/"Agent"
+                    // works the same way): a hook can veto a delegation or audit what came back.
+                    const preTask = await runToolHooks(hooks.PreToolUse, 'PreToolUse', name, input, options.workDir);
+                    if (preTask.block) {
+                        result = { error: `Blocked by PreToolUse hook: ${preTask.reason}` };
+                    }
+                    else {
+                        result = wantsBackground && depth === 0 && options.backgroundAgents && !input.resume_agent_id
+                            ? dispatchBackgroundSubAgent(input, taskOptions, agentTypes, options.backgroundAgents)
+                            : await dispatchSubAgent(input, taskOptions, agentTypes);
+                        const postTask = await runToolHooks(hooks.PostToolUse, 'PostToolUse', name, input, options.workDir, result);
+                        const injectedTask = [preTask.context, postTask.context].filter(Boolean).join('\n');
+                        if (injectedTask) {
+                            if (result.error !== undefined)
+                                result.error = `${result.error}\n\n[hook] ${injectedTask}`;
+                            else
+                                result.output = `${result.output ?? ''}\n\n[hook] ${injectedTask}`;
+                        }
+                        if (postTask.block) {
+                            result.error = `${result.error ? result.error + '\n' : ''}PostToolUse hook flagged: ${postTask.reason}`;
+                        }
+                    }
                 }
                 else {
-                    const pre = runToolHooks(hooks.PreToolUse, 'PreToolUse', name, input, options.workDir);
+                    const pre = await runToolHooks(hooks.PreToolUse, 'PreToolUse', name, input, options.workDir);
                     if (pre.block) {
                         result = { error: `Blocked by PreToolUse hook: ${pre.reason}` };
                     }
@@ -3412,27 +4038,32 @@ async function runAgentLoop(initialMessages, options) {
                             // could not tell whose notes to write to (and must not be able to).
                             if (name === exports.AGENT_MEMORY_TOOL) {
                                 result = await executeAgentMemoryWrite(input, options._agentMemory, options.workDir);
-                                options.onToolResult(name, result);
+                                options.onToolResult(name, result, undefined, toolMeta);
                                 return { block: { ...block, id }, result };
                             }
                             // 1. Try platform-specific tools (e.g. VS Code semantic tools)
+                            // Both of these run code we do not control (the editor, a third-party MCP
+                            // server) and may ignore Stop; stopAwaiting returns an "interrupted" result
+                            // a few seconds after Stop instead of leaving the turn hanging on them.
                             const external = options.executeExternalTool
-                                ? await options.executeExternalTool(name, input)
+                                ? await stopAwaiting(options.executeExternalTool(name, input), options.abortSignal)
                                 : null;
                             if (external !== null && external !== undefined) {
                                 result = external;
                                 // 2. Try MCP tools (serverName__toolName)
                             }
                             else if (options.mcpManager?.isMcpTool(name)) {
-                                const mcpOutput = await options.mcpManager.callTool(name, input, options.abortSignal);
-                                result = { output: mcpOutput ?? '' };
+                                const mcpOutput = await stopAwaiting(options.mcpManager.callTool(name, input, options.abortSignal), options.abortSignal);
+                                result = mcpOutput === STOP_TIMEOUT_RESULT
+                                    ? STOP_TIMEOUT_RESULT
+                                    : { output: (0, executor_1.capExternalOutput)(mcpOutput ?? '', `mcp-${name}`) };
                                 // 3. Fall through to built-in executor
                             }
                             else {
                                 // Snapshot pre-mutation state so the user can /rewind this turn.
                                 options.checkpointManager?.recordBeforeMutation(name, input);
                                 const onStream = options.onToolStreamChunk
-                                    ? (chunk) => options.onToolStreamChunk(name, chunk)
+                                    ? (chunk) => options.onToolStreamChunk(name, chunk, undefined, toolMeta)
                                     : undefined;
                                 const run = () => (0, executor_1.executeTool)(name, input, options.abortSignal, sandboxCfg, options.workDir, agentScope, onStream, options.selfPeer);
                                 // Serialise anything that would otherwise race. Two sources of races:
@@ -3463,9 +4094,31 @@ async function runAgentLoop(initialMessages, options) {
                                 // Nesting cross-process OUTSIDE in-process means a process holding
                                 // the OS lock for a group of sub-agents takes it exactly ONCE for the
                                 // whole group, not once per sub-agent.
-                                result = locks.length
-                                    ? await (0, crossProcessLock_1.withCrossProcessLocks)(locks, () => withFileLocks(locks, run), options.workDir)
-                                    : await run();
+                                // Unchanged re-read of a range whose earlier result is still in the
+                                // history → one-line stub instead of the same content again (readDedupe.ts).
+                                const dedupeStub = name === 'read_file' ? readDedupe.check(input, messages) : null;
+                                const prefetched = !dedupeStub && prefetchSafe ? prefetcher.take(id, name, input) : null;
+                                if (dedupeStub) {
+                                    result = { output: dedupeStub };
+                                }
+                                else if (prefetched) {
+                                    result = await prefetched;
+                                    if (name === 'read_file' && result.error === undefined && result.output?.startsWith('[File:')) {
+                                        readDedupe.record(input, id);
+                                    }
+                                }
+                                else {
+                                    result = locks.length
+                                        ? await (0, crossProcessLock_1.withCrossProcessLocks)(locks, () => withFileLocks(locks, run), options.workDir)
+                                        : await run();
+                                    if (name === 'read_file' && result.error === undefined && result.output?.startsWith('[File:')) {
+                                        readDedupe.record(input, id);
+                                    }
+                                }
+                                // A write tool touched these paths — drop their recorded reads even if
+                                // mtime happens to be unchanged (same-millisecond edit).
+                                if (name !== 'bash' && locks.length)
+                                    readDedupe.invalidate(locks);
                             }
                         }
                         catch (err) {
@@ -3480,7 +4133,7 @@ async function runAgentLoop(initialMessages, options) {
                             void maybeCompactMemory(scope, options);
                         }
                         // PostToolUse can inject context for the model or flag a problem.
-                        const post = runToolHooks(hooks.PostToolUse, 'PostToolUse', name, input, options.workDir, result);
+                        const post = await runToolHooks(hooks.PostToolUse, 'PostToolUse', name, input, options.workDir, result);
                         const injected = [pre.context, post.context].filter(Boolean).join('\n');
                         if (injected) {
                             if (result.error !== undefined)
@@ -3503,7 +4156,7 @@ async function runAgentLoop(initialMessages, options) {
                     result.output = (0, testIntegrity_1.stripTestIntegrityMarker)(result.output);
                 }
                 // Notify caller about result
-                options.onToolResult(name, result);
+                options.onToolResult(name, result, undefined, toolMeta);
                 return { block: { ...block, id }, result, rawOutput };
             }));
             // Track whether files were mutated / verified this run, for the one-shot
@@ -3524,6 +4177,20 @@ async function runAgentLoop(initialMessages, options) {
                 if (auditCtx) {
                     (0, audit_1.recordAudit)(auditCtx, block.name, block.input, ok, result.output, result.error, result.exitCode);
                 }
+                // Build/test commands a sub-agent ran count for THIS run too — otherwise the main
+                // agent, reporting "tests pass" from a sub-agent's verified run, was told no test
+                // had been run and re-ran the whole suite. Counted even when the task errored
+                // (a stopped sub-agent may still have run the suite).
+                if (block.name === 'task' && result.childVerifications?.length) {
+                    for (const v of result.childVerifications) {
+                        ledger.verifications.push({ cmd: `(sub-agent) ${v.cmd}`.slice(0, 120), ok: v.ok, epoch: ledger.epoch });
+                    }
+                    const lastChild = result.childVerifications[result.childVerifications.length - 1];
+                    if (lastChild.ok) {
+                        ranVerificationCmd = true;
+                        filesMutatedSinceVerify = false;
+                    }
+                }
                 if (!ok)
                     continue; // failed calls don't count either way
                 if (exports.WRITE_TOOL_NAMES.has(block.name))
@@ -3575,6 +4242,12 @@ async function runAgentLoop(initialMessages, options) {
                 options.onPeerMessage?.(inboundPeerMessages);
                 toolResultContent.push({ type: 'text', text: renderPeerMessages(inboundPeerMessages) });
             }
+            // Background agents that finished while this round ran — same boundary, same
+            // reason: a notification must never interrupt an in-flight tool call.
+            const bgFinished = drainBackgroundNotifications();
+            if (bgFinished.length) {
+                toolResultContent.push({ type: 'text', text: (0, backgroundAgents_1.formatBackgroundNotifications)(bgFinished) });
+            }
             const toolResultMessage = {
                 role: 'user',
                 content: toolResultContent,
@@ -3653,8 +4326,13 @@ async function runAgentLoop(initialMessages, options) {
         // message in this file — these are statements from the harness, not from the model,
         // and splicing them into the assistant's own bubble reads as if it said them.
         const notice = stopReasonNotice(stopReason, { budget, repeatError: stalledRepeatError });
-        if (notice)
+        // A sub-agent's stop belongs in its parent's tool result, not in the user's chat as
+        // if the MAIN agent had stopped (runSubTask turns it into an error for the parent).
+        if (options._onStopReason)
+            options._onStopReason(stopReason, notice || null);
+        else if (notice)
             (options.onNotice ?? options.onText)(notice);
+        options._onVerifications?.(ledger.verifications.map((v) => ({ cmd: v.cmd, ok: v.ok })));
     }
     catch (err) {
         // Every other failure path (a tool executor blowing up, a hook throwing, an
@@ -3669,7 +4347,12 @@ async function runAgentLoop(initialMessages, options) {
         throw new types_1.AgentTurnError(err?.message || 'The turn ended unexpectedly', trimToResumableBoundary(messages), completedRounds, err);
     }
     finally {
-        runSimpleHooks(hooks.OnStop, options.workDir);
+        // OnStop is the MAIN agent's turn ending. Firing it at the end of every sub-agent
+        // ran the user's "turn finished" hook (notifications, formatters) mid-turn.
+        if (depth === 0)
+            await runSimpleHooks(hooks.OnStop, options.workDir);
+        else
+            await runSimpleHooks(hooks.SubagentStop, options.workDir, { NEXRALL_AGENT_NAME: options._agentTypeName ?? 'general-purpose' });
     }
     return messages;
 }