@nexrall/code-core 1.4.32 → 1.4.34

package/dist/agent/loop.js

@@ -40,8 +40,15 @@ exports.stopReasonNotice = stopReasonNotice;
 exports.resolveMaxIterations = resolveMaxIterations;
 exports.lockPathsFor = lockPathsFor;
 exports.resolveMaxConcurrentSubtasks = resolveMaxConcurrentSubtasks;
+exports.resolveMaxSubagentsPerSession = resolveMaxSubagentsPerSession;
 exports.createLimiter = createLimiter;
 exports._resetSubTaskLimiter = _resetSubTaskLimiter;
+exports.resetSessionSubAgentBudget = resetSessionSubAgentBudget;
+exports._sessionSubAgentCount = _sessionSubAgentCount;
+exports.resolveMaxSubagentDepth = resolveMaxSubagentDepth;
+exports.noSpawnReason = noSpawnReason;
+exports.intersectAllowlists = intersectAllowlists;
+exports.canSpawnSubAgents = canSpawnSubAgents;
 exports.resolveSubtaskTimeoutMs = resolveSubtaskTimeoutMs;
 exports.extractSubTaskText = extractSubTaskText;
 exports.capSubTaskText = capSubTaskText;
@@ -80,6 +87,7 @@ const testIntegrity_1 = require("./testIntegrity");
 const flaky_1 = require("./flaky");
 const claimEvidence_1 = require("./claimEvidence");
 const memory_1 = require("./memory");
+const safeSlice_1 = require("../util/safeSlice");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -477,7 +485,11 @@ const DEFAULT_MAX_CONCURRENT_SUBTASKS = 4;
  * degrade to "a lot" rather than fork-bomb the machine.
  */
 function resolveMaxConcurrentSubtasks(settingsRaw = {}) {
-    const clamp = (n) => Math.min(Math.floor(n), 16);
+    // `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 fromEnv = Number(process.env.NEXRALL_MAX_CONCURRENT_SUBTASKS);
     if (Number.isFinite(fromEnv) && fromEnv > 0)
         return clamp(fromEnv);
@@ -486,6 +498,40 @@ function resolveMaxConcurrentSubtasks(settingsRaw = {}) {
         return clamp(fromSettings);
     return DEFAULT_MAX_CONCURRENT_SUBTASKS;
 }
+// ── Session TOTAL, distinct from the per-moment concurrency gate ─────────────
+//
+// maxConcurrentSubtasks bounds how many run AT ONCE; it does not bound how many run
+// IN TOTAL. With a queue rather than a rejection, "4 at a time" and "unbounded" are the
+// same thing given enough turns — the limiter just meters the spend, it never stops it.
+// A model in a retry loop could spawn sub-agents indefinitely and the only signal would
+// be the bill.
+//
+// This gap did not matter much while sub-agents were leaves: only the main agent could
+// spawn, so the count grew linearly with its own turns. With nesting it grows like a
+// tree, which is exactly why Anthropic added a per-session subagent ceiling alongside
+// their concurrency cap rather than relying on concurrency alone.
+//
+// 100 is chosen to be invisible in real work (a heavy orchestration session uses a few
+// dozen) and decisive in a runaway. Unlike the concurrency gate this REJECTS rather than
+// queues: a queue that never drains is a hang, and the point here is to stop.
+const DEFAULT_MAX_SUBAGENTS_PER_SESSION = 100;
+/** Resolve the session-total sub-agent ceiling: env → settings.json → default. */
+function resolveMaxSubagentsPerSession(settingsRaw = {}) {
+    // Clamped, unlike the first draft of this function. The argument for leaving it unbounded
+    // was that it only moves a counter — but `.nexrall/settings.json` is REPO-CONTROLLED and
+    // merged last, so a cloned repo could set 999999 and neutralise the one ceiling that makes
+    // a default depth > 1 defensible, turning `depth 5 x 16 wide` into an unbounded spend on a
+    // machine whose owner only opened a project. Depth and concurrency were already clamped for
+    // exactly this reason; this was the gap between them.
+    const floor = (n) => Math.max(1, Math.min(Math.floor(n), 10000));
+    const fromEnv = Number(process.env.NEXRALL_MAX_SUBAGENTS_PER_SESSION);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return floor(fromEnv);
+    const fromSettings = Number(settingsRaw.maxSubagentsPerSession);
+    if (Number.isFinite(fromSettings) && fromSettings > 0)
+        return floor(fromSettings);
+    return DEFAULT_MAX_SUBAGENTS_PER_SESSION;
+}
 /**
  * Minimal concurrency gate. Hand-rolled rather than pulling in `p-limit` because
  * the CLI ships as a single esbuild bundle with no node_modules, and this is a
@@ -519,21 +565,134 @@ function createLimiter(max) {
 // Once created it is reused for the process lifetime — rebuilding it per turn would
 // reset `active` and let the ceiling be exceeded, which is worse than not honouring a
 // mid-session settings change.
-let _subTaskLimitInstance = null;
+// ONE LIMITER PER DEPTH, which is what makes nesting safe to gate at all.
+//
+// The old design gated only `depth === 0` and left nested spawns ungated — deliberately,
+// because a single shared limiter deadlocks the moment a slot-holder re-enters it: a
+// parent holding one of N slots waits for a child that can only start when a slot frees,
+// and if all N are held by such parents the run wedges forever. While sub-agents were
+// leaves that could not happen, so "gate the top, leave the rest" cost nothing.
+//
+// With nesting it costs everything: nested fan-out becomes completely unbounded, which is
+// worse than the deadlock it was avoiding.
+//
+// Keying the limiter by depth fixes both at once. A depth-D run only ever waits on the
+// depth-(D+1) limiter, never its own, so the wait-for graph is strictly ordered by depth —
+// a DAG, and a DAG cannot deadlock. Every level is independently bounded, so worst-case
+// concurrency is bounded per level rather than unbounded below level 1.
+const _subTaskLimiters = new Map();
+/** The tapered ceiling actually applied at each depth, so the queue notice can report it. */
+const _subTaskLimitMaxByDepth = new Map();
 let _subTaskLimitMax = 0;
-/** Sub-tasks dispatched but not yet finished — used only to detect queueing. */
-let _inFlightSubTasks = 0;
-function subTaskLimiter(workDir) {
-    if (!_subTaskLimitInstance) {
+/** In-flight count per depth — used only to detect queueing, so the notice is accurate. */
+const _inFlightByDepth = new Map();
+function subTaskLimiter(depth, workDir) {
+    if (!_subTaskLimitMax) {
         _subTaskLimitMax = resolveMaxConcurrentSubtasks(workDir ? (0, rules_1.loadSettings)(workDir).raw : {});
-        _subTaskLimitInstance = createLimiter(_subTaskLimitMax);
     }
-    return { run: _subTaskLimitInstance, max: _subTaskLimitMax };
+    let run = _subTaskLimiters.get(depth);
+    let max = _subTaskLimitMaxByDepth.get(depth) ?? 0;
+    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
+        // 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
+        // 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.
+        max = Math.max(1, Math.ceil(_subTaskLimitMax / 2 ** Math.max(0, depth - 1)));
+        run = createLimiter(max);
+        _subTaskLimiters.set(depth, run);
+        _subTaskLimitMaxByDepth.set(depth, max);
+    }
+    return { run, max };
 }
 /** Test-only: forget the memoised limiter so a new limit can take effect. */
 function _resetSubTaskLimiter() {
-    _subTaskLimitInstance = null;
+    _subTaskLimiters.clear();
+    _subTaskLimitMaxByDepth.clear();
+    _inFlightByDepth.clear();
     _subTaskLimitMax = 0;
+    _subAgentsThisSession = 0;
+    _sessionCapMax = 0;
+    _sessionCapNotified = false;
+}
+// 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.
+ *
+ * Exported for clients that reuse one process across conversations (the VS Code extension
+ * 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;
+}
+/**
+ * Claim one slot against the session total. Returns an error string when exhausted.
+ *
+ * `notify` surfaces exhaustion to the HUMAN exactly once. Without it only the model is
+ * told, and a model instructed to "do the remaining work directly" complies silently — so
+ * 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 : {});
+    }
+    if (_subAgentsThisSession >= _sessionCapMax) {
+        if (!_sessionCapNotified) {
+            _sessionCapNotified = 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.');
+        }
+        return (`Sub-agent budget for this session is exhausted (${_sessionCapMax} started). This is a ` +
+            '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++;
+    return null;
+}
+/**
+ * Give back a slot claimed for a spawn that never started an agent.
+ *
+ * The claim happens at the dispatch site, BEFORE the concurrency limiter, so that a spawn
+ * which is already over budget is refused immediately instead of queueing behind running
+ * siblings. That ordering is what makes the guard useful in a runaway — but it also means
+ * the claim precedes runSubTask's own validation, which rejects on several paths without
+ * ever starting a loop (empty prompt, a `deny` rule, an unusable resume id).
+ *
+ * Without a refund those rejections spend budget: a model retrying against a deny rule would
+ * silently burn the whole allowance on spawns that never ran, then lose delegation for the
+ * session with a notice blaming a runaway that never happened. The counter's contract is
+ * "sub-agents STARTED", and this is what keeps that true while preserving fast refusal.
+ *
+ * Floored at 0 so a double refund can never manufacture budget.
+ */
+function refundSessionSubAgentSlot() {
+    if (_subAgentsThisSession > 0)
+        _subAgentsThisSession--;
+}
+/** Test-only: observe the session counter without exporting the mutable binding. */
+function _sessionSubAgentCount() {
+    return _subAgentsThisSession;
 }
 // ─── Human-readable tool descriptions ────────────────────────────────────────
 function humanDescription(name, input) {
@@ -620,15 +779,131 @@ function humanDescription(name, input) {
     }
 }
 // ─── Sub-task runner ──────────────────────────────────────────────────────────
-// Deepest nesting level allowed to spawn a sub-agent. The main agent runs at
-// depth 0 and the sub-agents it spawns at depth 1.
+// Nesting depth. The main agent runs at depth 0, the sub-agents it spawns at depth 1.
+//
+// A run at `depth` may spawn when `depth < limit`, so a limit of N means N generations
+// below the main agent. This used to be a hard-coded 1 with the historical note "This is
+// 1, not 2" — that note was about making the CONSTANT agree with a system prompt that
+// promised "sub-agents cannot spawn further sub-agents". Both sides of that agreement have
+// now moved: nesting is a supported, configured capability, and the prompt is generated
+// from the same predicate that enforces it (canSpawnSubAgents), so the two cannot drift
+// again regardless of the value.
 //
-// This is 1, not 2. With 2 the guard below (`depth >= MAX_TASK_DEPTH`) let a
-// depth-1 sub-agent spawn depth-2 grandchildren — contradicting both the constant's
-// own comment and the system prompt's promise that "sub-agents cannot spawn further
-// sub-agents", and quietly making the worst-case fan-out quadratic. The value and
-// the documented behaviour now agree.
-const MAX_TASK_DEPTH = 1;
+// What made the old value load-bearing was that fan-out had no TOTAL bound — only a
+// per-moment concurrency gate. Depth × fan-out is multiplicative, so raising depth without
+// a session ceiling converts a bounded queue into an unbounded tree. That ceiling
+// (resolveMaxSubagentsPerSession) is what makes a depth > 1 safe to default to.
+const DEFAULT_MAX_TASK_DEPTH = 3;
+/**
+ * Hard ceiling on `maxSubagentDepth`, independent of what anyone configures.
+ *
+ * 5 matches the deepest tier Anthropic shipped for Claude Code. It exists because depth
+ * is MULTIPLICATIVE with fan-out: at 4-wide, depth 5 is 4^5 = 1024 possible loops. The
+ * per-depth limiter and the session ceiling below are what actually bound that, but a
+ * typo'd `maxSubagentDepth: 50` should degrade to "deep" rather than to a fork bomb —
+ * same reasoning as the clamp on maxConcurrentSubtasks.
+ */
+const HARD_MAX_TASK_DEPTH = 5;
+/**
+ * Deepest nesting level allowed to spawn: env → settings.json → default 3.
+ *
+ * Was a hard-coded 1, i.e. "sub-agents are leaves". That was the right default while the
+ * three capability decisions disagreed with each other (see canSpawnSubAgents), but it is
+ * no longer where the ecosystem is: Claude Code lifted the no-nesting rule and, after a
+ * brief period with it disabled entirely, settled on a configurable default of 3.
+ *
+ * 3, not 5, deliberately. Depth is a budget you SPEND, not headroom you fill: every level
+ * is a context window that receives only a dispatch prompt on the way down and returns
+ * only a summary on the way up, so the deeper frames pay full freight to carry less
+ * information. 3 covers orchestrator → worker → helper, which is where the observed value
+ * is; beyond that latency and token cost tend to exceed the benefit.
+ *
+ * Depth 1 remains available (`maxSubagentDepth: 1`) for anyone who wants leaves-only.
+ */
+function resolveMaxSubagentDepth(settingsRaw = {}) {
+    const clamp = (n) => Math.max(1, Math.min(Math.floor(n), HARD_MAX_TASK_DEPTH));
+    const fromEnv = Number(process.env.NEXRALL_MAX_SUBAGENT_DEPTH);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return clamp(fromEnv);
+    const fromSettings = Number(settingsRaw.maxSubagentDepth);
+    if (Number.isFinite(fromSettings) && fromSettings > 0)
+        return clamp(fromSettings);
+    return DEFAULT_MAX_TASK_DEPTH;
+}
+/**
+ * The ONE explanation for "this run may not spawn a sub-agent", shared by every place
+ * that can refuse it, so the same impossibility never gets two different stories.
+ *
+ * Parameterised on the REASON because the reasons are no longer interchangeable. It used
+ * to be a flat constant reading "Sub-agents cannot spawn further sub-agents — this is a
+ * structural limit"; with nesting configurable that sentence is now false for most runs,
+ * and telling a depth-1 agent its limit is structural when the user could raise it by one
+ * line of settings is the same class of misdirection as the "needs a different agent" text
+ * this replaced. A refusal has to be accurate about whether it can be lifted, or the model
+ * either gives up when it shouldn't or hunts for an escape that doesn't exist.
+ */
+function noSpawnReason(kind, limit) {
+    if (kind === 'denied') {
+        return ('This sub-agent\'s definition does not grant `task`, so it may not delegate. That is a ' +
+            'deliberate restriction on this agent type — do not ask for approval and do not look for ' +
+            'a way around it. Do the work with the tools you have, or report back what is missing.');
+    }
+    return (`Maximum sub-agent nesting depth (${limit ?? DEFAULT_MAX_TASK_DEPTH}) reached, so this run ` +
+        'is a leaf and cannot delegate further. Depth is a budget, not a bug: finish this work ' +
+        'yourself, or report back so a shallower frame can decide. (The ceiling is ' +
+        '"maxSubagentDepth" in .nexrall/settings.json, but raising it mid-task will not help you — ' +
+        'it applies from the next session.)');
+}
+/**
+ * Whether a run at `depth` may spawn sub-agents.
+ *
+ * The single source of truth for THREE things that must agree: the `<available_subagents>`
+ * catalogue in the system prompt, whether the backend is asked to send the `task` tool
+ * schema at all, and which prompt block teaches delegation. They used to be decided
+ * independently, and the result was a sub-agent that got the tool plus instructions to use
+ * it but no catalogue — then a permission-gate refusal telling it not to ask for approval.
+ *
+ * `depth < limit` because the children this run would create land at `depth + 1`; the
+ * guard inside runSubTask mirrors it as `depth >= limit`.
+ *
+ * `limit` is injected rather than read from module state so this stays pure and testable.
+ * Callers pass the resolved per-workspace value; it defaults to the built-in for the
+ * handful of call sites that have no settings in hand.
+ */
+/**
+ * A child sub-agent's effective tool allowlist: its own, narrowed by its parent's.
+ *
+ * Exported and pure because it is a SECURITY boundary and was previously verified only by
+ * grepping the source for the intersection expression — which matched happily while the
+ * code threw a TypeError on one of its own four cases. A boundary needs behavioural tests.
+ *
+ * `null` means "no allowlist" (unrestricted), and it is returned only when BOTH sides say
+ * so. The four cases:
+ *   own + parent → intersection (a child can narrow, never widen)
+ *   own only     → own (the main agent, which has no allowlist, spawning a specialist)
+ *   parent only  → a COPY of parent (an unnamed/general-purpose child inherits the
+ *                  restriction instead of resetting to full access — this is the
+ *                  escalation path, since `general-purpose` declares no tools at all)
+ *   neither      → null
+ *
+ * The parent-only case must COPY: the caller adds AGENT_MEMORY_TOOL to the returned set,
+ * which would otherwise mutate the parent's live allowlist.
+ */
+function intersectAllowlists(own, parent) {
+    if (own && parent)
+        return new Set([...own].filter((t) => parent.has(t)));
+    if (own)
+        return own;
+    return parent ? new Set(parent) : null;
+}
+function canSpawnSubAgents(depth, allowedTools, limit = DEFAULT_MAX_TASK_DEPTH) {
+    if (depth >= limit)
+        return false;
+    // An allowlist that omits `task` is the other reason a run cannot delegate. No
+    // allowlist at all (the main agent, or a general-purpose sub-task) means no
+    // restriction from this clause — the depth check above still applies.
+    return allowedTools ? allowedTools.has('task') : true;
+}
 let _subTaskCounter = 0; // unique per-process id → per-sub-agent todo scope
 // A sub-agent that stalls (hung tool, model provider stuck, infinite tool-call
 // loop bypassing the iteration budget somehow) used to have NO ceiling of its
@@ -680,34 +955,11 @@ class ToolNotAllowedError extends Error {
     }
 }
 exports.ToolNotAllowedError = ToolNotAllowedError;
-/**
- * Slice `s` to at most `max` UTF-16 units without splitting a surrogate pair.
- *
- * A bare `slice()` can cut between the high and low half of a non-BMP character
- * (emoji, many CJK extension glyphs), producing a lone surrogate — invalid UTF-16
- * that the Anthropic API rejects outright with "no low surrogate in string". That
- * exact failure has already been shipped and fixed once in this codebase; every
- * new cap on model-facing text has to be surrogate-aware from the start.
- */
-function sliceSafeEnd(s, max) {
-    if (s.length <= max)
-        return s;
-    let end = max;
-    const code = s.charCodeAt(end - 1);
-    if (code >= 0xd800 && code <= 0xdbff)
-        end--; // trailing high surrogate — drop it
-    return s.slice(0, end);
-}
-/** Mirror of sliceSafeEnd for a tail slice: never START on a low surrogate. */
-function sliceSafeStart(s, from) {
-    if (from <= 0)
-        return s;
-    let start = from;
-    const code = s.charCodeAt(start);
-    if (code >= 0xdc00 && code <= 0xdfff)
-        start++; // leading low surrogate — drop it
-    return s.slice(start);
-}
+// sliceSafeEnd/sliceSafeStart moved to ../util/safeSlice so every module that
+// truncates model-facing/wire-facing text (loop.ts and tools/executor.ts) shares
+// ONE surrogate-safe implementation instead of drifting copies. See that file's
+// header for why raw `.slice()` on these strings caused a 400
+// "no low surrogate in string" from the Anthropic API.
 /**
  * Reduce a sub-agent's message history to the text its parent should receive.
  *
@@ -739,8 +991,8 @@ function extractSubTaskText(messages, preferLast = true) {
 function capSubTaskText(text, max = SUBTASK_MAX) {
     if (text.length <= max)
         return text;
-    const head = sliceSafeEnd(text, Math.floor(max * 0.6));
-    const tail = sliceSafeStart(text, text.length - Math.floor(max * 0.4));
+    const head = (0, safeSlice_1.sliceSafeEnd)(text, Math.floor(max * 0.6));
+    const tail = (0, safeSlice_1.sliceSafeStart)(text, text.length - Math.floor(max * 0.4));
     return `${head}\n\n[… sub-task output truncated (${text.length} chars) — kept the beginning and end …]\n\n${tail}`;
 }
 /**
@@ -827,7 +1079,7 @@ function lastToolResults(messages, count, maxChars) {
                 continue;
             const name = nameById.get(String(b.tool_use_id ?? '')) ?? 'tool';
             const body = text.length > maxChars
-                ? `${sliceSafeEnd(text, maxChars)}\n… [truncated]`
+                ? `${(0, safeSlice_1.sliceSafeEnd)(text, maxChars)}\n… [truncated]`
                 : text;
             out.push(`• ${name}:\n${body}`);
         }
@@ -848,14 +1100,29 @@ function toolResultText(block) {
     }
     return '';
 }
-async function runSubTask(input, options, agentTypes) {
+async function runSubTask(input, options, agentTypes, 
+// Set to true at the moment an agent loop actually STARTS, so the caller can refund the
+// session slot it claimed for a spawn that turned out never to run.
+//
+// An out-param rather than a discriminated return type on purpose: every one of this
+// function's ~8 early returns is a non-start, and several are far from the top. Enumerating
+// them in the caller would be a list to forget to update; flipping one flag at the single
+// point of no return cannot go stale, and a path added later is a non-start by default.
+started) {
     const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
     if (!prompt)
         return { error: 'task tool requires a non-empty prompt' };
+    // The scope of the frame DOING the spawning — i.e. the owner of any resumable id this call
+    // produces, and the identity checked when resuming one. 'root' is the main agent.
+    const agentScope = options._agentScope ?? 'root';
     const depth = options._depth ?? 0;
-    if (depth >= MAX_TASK_DEPTH) {
-        return { error: 'Sub-agents cannot spawn further sub-agents. Do this work directly, or report back so the main agent can delegate it.' };
+    const depthLimit = resolveMaxSubagentDepth(options.workDir ? (0, rules_1.loadSettings)(options.workDir).raw : {});
+    if (depth >= depthLimit) {
+        return { error: noSpawnReason('depth', depthLimit) };
     }
+    // NOTE: the session budget is claimed at the DISPATCH SITE, not here — runSubTask runs
+    // inside the concurrency limiter, so claiming here would make a doomed spawn wait behind
+    // running siblings before being told no. See the `name === 'task'` branch in runAgentLoop.
     // Resolve an optional custom agent type (subagent_type).
     //
     // `agentTypes` is a snapshot taken once at the top of runAgentLoop, before the
@@ -882,6 +1149,22 @@ async function runSubTask(input, options, agentTypes) {
     // used to launder a denied agent under an allowed name.
     const resumeId = typeof input.resume_agent_id === 'string' ? input.resume_agent_id.trim() : '';
     const resumed = resumeId ? (0, agentRegistry_1.getAgent)(resumeId) : undefined;
+    // OWNERSHIP, in addition to the deny-rule re-authorisation below.
+    //
+    // Re-deriving the agent NAME from storage stops an id laundering a denied agent, but it
+    // says nothing about WHO may use the id. The registry is one flat process-global Map, so a
+    // nested sub-agent could name an id it was never given and read another agent's entire
+    // unredacted transcript, or overwrite it. Harmless while sub-agents were leaves (only the
+    // main agent ever held an id); live once they can spawn.
+    //
+    // Reported as "expired" rather than "not yours": a distinct message would confirm the id
+    // exists, turning the error into an oracle for enumerating other frames' agents.
+    if (resumed && !(0, agentRegistry_1.canResume)(resumed, agentScope)) {
+        return {
+            error: `No resumable sub-agent with id "${resumeId}" is available to this run. Start a fresh ` +
+                'sub-task with a self-contained prompt instead.',
+        };
+    }
     if (resumeId && !resumed) {
         return {
             error: `No resumable sub-agent with id "${resumeId}". Ids live only for the current session and the ` +
@@ -902,15 +1185,26 @@ async function runSubTask(input, options, agentTypes) {
     //
     // Phrased as a policy refusal, not "unknown type": the model must not respond
     // by trying to create the agent file it thinks is missing.
-    if (requestedType) {
-        const decision = (0, rules_1.evaluatePermission)((0, rules_1.loadSettings)(options.workDir).permissions, 'task', { subagent_type: requestedType }, options.workDir);
-        if (decision === 'deny') {
-            return {
-                error: `The sub-agent "${requestedType}" is disabled by a permission rule in this project ` +
-                    `(permissions.deny in settings.json). This is a deliberate policy choice, not a missing file — ` +
-                    'do not create it and do not retry. Do the work yourself, or use a different sub-agent.',
-            };
-        }
+    // Evaluated UNCONDITIONALLY, with 'general-purpose' standing in for an unnamed dispatch.
+    //
+    // This used to be `if (requestedType)`, which meant an unnamed spawn skipped the rule
+    // entirely: `deny: ["task(general-purpose)"]` matched the named form and returned null for
+    // the unnamed one. Omitting the field was therefore a bypass for the single most
+    // privileged variant — an unnamed sub-task has no allowlist of its own, so before the
+    // parent-intersection it received FULL access, exactly what such a rule is written to stop.
+    //
+    // The substitution is also the honest model rather than a patch: an unnamed sub-task IS
+    // general-purpose behaviourally (that is what naming it accomplished in the first place),
+    // so a rule about that agent should govern both spellings. A bare `deny: ["task"]` already
+    // caught both and is unaffected.
+    const denyKey = requestedType || 'general-purpose';
+    const decision = (0, rules_1.evaluatePermission)((0, rules_1.loadSettings)(options.workDir).permissions, 'task', { subagent_type: denyKey }, options.workDir);
+    if (decision === 'deny') {
+        return {
+            error: `The sub-agent "${denyKey}" is disabled by a permission rule in this project ` +
+                `(permissions.deny in settings.json). This is a deliberate policy choice, not a missing file — ` +
+                'do not create it and do not retry. Do the work yourself, or use a different sub-agent.',
+        };
     }
     let agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
     let knownTypes = agentTypes;
@@ -959,7 +1253,24 @@ async function runSubTask(input, options, agentTypes) {
     // "Permission denied by user", which was actively misleading: the user denied
     // nothing, and a model told that will re-ask for approval instead of noticing
     // that the agent's own allowlist (often a typo'd tool name) is what stopped it.
-    const allowed = agent?.tools ? new Set(agent.tools) : null;
+    // ── The child's allowlist is INTERSECTED with the parent's ──────────────────
+    //
+    // A child's own definition can only ever NARROW what its parent had, never widen it.
+    // Without this, nesting is a privilege-escalation ladder: `reviewer` is read-only and
+    // has no write_file, but `general-purpose` declares no `tools:` at all (= full access),
+    // so a read-only agent could delegate to an unrestricted one and edit the repo through
+    // it. The user's "this agent cannot write" would silently mean "cannot write directly".
+    //
+    // This was unreachable while sub-agents were leaves — nobody but the (unrestricted) main
+    // agent could spawn. Turning nesting on is what makes it live, so the intersection ships
+    // in the same change rather than as a follow-up.
+    //
+    // `null` still means "no allowlist", but only when BOTH sides say so: an unrestricted
+    // parent spawning general-purpose stays unrestricted (today's behaviour at depth 1),
+    // while a restricted parent yields a restricted child no matter what the child declares.
+    // Sticky for the same reason the allowlist intersects: inherited OR own, never shed.
+    const testFilesOnly = !!agent?.testFilesOnly || !!options._testFilesOnly;
+    const allowed = intersectAllowlists(agent?.tools ? new Set(agent.tools) : null, options._allowedTools);
     // The ONE capability `memory:` grants. Added to the allowlist rather than bypassing
     // it, so the allowlist stays the single source of truth for what this agent can do.
     if (allowed && memoryScope)
@@ -973,16 +1284,48 @@ async function runSubTask(input, options, agentTypes) {
                 '`memory:` scope (project, user or local). Report anything worth remembering in your final ' +
                 'message instead — the main agent decides what to persist.');
         }
+        // `task` is answered by the same predicate that decides whether the tool was sent in
+        // the first place, so the gate cannot disagree with the prompt.
+        //
+        // This was briefly an UNCONDITIONAL refusal, which was correct only while the depth
+        // ceiling was hard-coded to 1 (every gated run was a leaf by definition). With nesting
+        // configurable that shortcut becomes a real bug: a depth-1 agent under
+        // `maxSubagentDepth: 3` would be handed the tool by the backend and then refused here.
+        // Fail-closed, so it would have looked like a mysterious dead end rather than a crash.
+        //
+        // Two distinct reasons, two distinct messages — a depth ceiling is raisable, an agent
+        // definition withholding `task` is not, and a refusal that lies about which one applies
+        // makes the model either give up early or hunt for an escape hatch.
+        if (req.tool === 'task' && !canSpawnSubAgents(depth + 1, allowed ?? undefined, depthLimit)) {
+            // `depth + 1`, not `depth`: this closure gates the CHILD's tool calls, and the child
+            // runs one level below the `depth` in scope here (which belongs to its parent). Using
+            // `depth` would evaluate the parent's right to spawn — permitting one level too many.
+            throw new ToolNotAllowedError(allowed && !allowed.has('task')
+                ? noSpawnReason('denied')
+                : noSpawnReason('depth', depthLimit));
+        }
         if (allowed && !allowed.has(req.tool)) {
-            throw new ToolNotAllowedError(`The "${agent.name}" sub-agent is not allowed to use \`${req.tool}\` — it is not in that agent's ` +
+            throw new ToolNotAllowedError(
+            // `agent?.name`, NOT `agent!.name`. The non-null assertion held only while `allowed`
+            // was derived solely from `agent?.tools` (non-null allowlist ⇒ named agent). The
+            // parent-intersection broke that invariant: a RESTRICTED parent dispatching `task`
+            // with no subagent_type yields a non-null inherited allowlist with `agent`
+            // undefined, and this line then threw a TypeError instead of ToolNotAllowedError —
+            // which the dispatch site does not recognise, so it laundered the refusal into the
+            // generic "Permission denied by user" this very message exists to avoid.
+            `The "${agent?.name ?? 'general-purpose'}" sub-agent is not allowed to use \`${req.tool}\` — it is not in that agent's ` +
                 'tool allowlist. This is a restriction of the agent definition, NOT a user decision: do not ask ' +
                 'for approval, use one of the tools you do have, or report back that the task needs a different agent.');
         }
-        // Path-scoped write restriction (agent.testFilesOnly) — see
-        // allowsTestOnlyWrite for the reasoning and its known limit.
-        if (agent?.testFilesOnly && !allowsTestOnlyWrite(req.tool, req.input)) {
-            throw new ToolNotAllowedError(`The "${agent.name}" 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.');
+        // Path-scoped write restriction — see allowsTestOnlyWrite for the reasoning and its
+        // known limit. Applies when THIS agent declares it OR any ancestor did: like the tool
+        // allowlist above, a restriction can only ever be narrowed by nesting, never shed.
+        // Without the inherited half, `test-writer` could delegate to an unrestricted agent and
+        // have production source written on its behalf.
+        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);
     };
@@ -1039,6 +1382,9 @@ async function runSubTask(input, options, agentTypes) {
             subAbort.aborted = true;
     }, 250);
     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, {
             ...options,
             _depth: depth + 1,
@@ -1055,15 +1401,21 @@ async function runSubTask(input, options, agentTypes) {
             // `tools:` line inherited the parent's allowlist, making the prompt's capability
             // claim disagree with its real one.
             //
-            // MAX_TASK_DEPTH === 1 means no nested spawn can reach this today, so it is
-            // latent rather than live — but the limiter comment below explicitly contemplates
-            // raising that depth, and this is exactly the kind of leak that would come back
-            // as a security bug rather than a visible error. Explicit undefined makes the
-            // child's identity independent of the parent's by construction.
+            // This is now LIVE, not latent: nesting is enabled by default, so a grandchild really
+            // can be spawned by an agent that has a memory binding. The explicit `undefined` is
+            // what stops it inheriting that binding and appending to its grandparent's private
+            // notes — a silent cross-agent write rather than a visible error. Note the allowlist
+            // takes the opposite direction on purpose (inherited, because it RESTRICTS); identity
+            // must not be inherited, capability must.
             _agentMemory: agent && memoryScope ? { agentName: agent.name, scope: memoryScope } : undefined,
             // The same set `gatedPermission` enforces above, so prompt and permission agree
             // by construction instead of by two people remembering to update both.
             _allowedTools: allowed ?? undefined,
+            // Propagated so a grandchild inherits it too — see _testFilesOnly. Assigned
+            // unconditionally (not by conditional spread) for the same reason as _agentMemory
+            // above: a conditional spread leaves the parent's value in place instead of clearing
+            // it, and here that direction is at least safe, whereas forgetting to propagate is not.
+            _testFilesOnly: testFilesOnly,
             editorContext: null, // fresh isolated context for sub-agent
             model: agent?.model ?? options.model,
             // Plan mode is inherited, never relaxed. If the main agent could spawn a
@@ -1134,7 +1486,7 @@ async function runSubTask(input, options, agentTypes) {
             // 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);
+            const partialId = (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result, agentScope);
             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.',
@@ -1161,8 +1513,8 @@ async function runSubTask(input, options, agentTypes) {
         // it cannot determine. Those paths already salvage their partial output as
         // TEXT, which is the safe way to carry that information forward.
         const agentId = resumed
-            ? ((0, agentRegistry_1.updateAgent)(resumed.id, result), resumed.id)
-            : (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result);
+            ? ((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);
         const body = text || '(sub-task completed with no text output)';
         return {
             output: `${body}\n\n[resumable: this sub-agent is "${agentId}". To ask IT a follow-up — keeping ` +
@@ -1420,13 +1772,13 @@ function transcriptOf(messages) {
     for (const m of messages) {
         for (const b of m.content) {
             if (b.type === 'text' && b.text) {
-                parts.push(`${m.role.toUpperCase()}: ${b.text.slice(0, 2000)}`);
+                parts.push(`${m.role.toUpperCase()}: ${(0, safeSlice_1.sliceSafeEnd)(b.text, 2000)}`);
             }
             else if (b.type === 'tool_use') {
-                parts.push(`${m.role.toUpperCase()} [tool: ${b.name}]: ${JSON.stringify(b.input ?? {}).slice(0, 400)}`);
+                parts.push(`${m.role.toUpperCase()} [tool: ${b.name}]: ${(0, safeSlice_1.sliceSafeEnd)(JSON.stringify(b.input ?? {}), 400)}`);
             }
             else if (b.type === 'tool_result') {
-                parts.push(`TOOL RESULT: ${String(b.content ?? '').slice(0, 600)}`);
+                parts.push(`TOOL RESULT: ${(0, safeSlice_1.sliceSafeEnd)(String(b.content ?? ''), 600)}`);
             }
         }
     }
@@ -1437,8 +1789,8 @@ function transcriptOf(messages) {
     // continuation). Slice on line boundaries so we don't cut a line in half.
     const headBudget = Math.floor(MAX_TRANSCRIPT_CHARS * 0.4);
     const tailBudget = MAX_TRANSCRIPT_CHARS - headBudget;
-    const head = full.slice(0, headBudget);
-    const tail = full.slice(full.length - tailBudget);
+    const head = (0, safeSlice_1.sliceSafeEnd)(full, headBudget);
+    const tail = (0, safeSlice_1.sliceSafeStart)(full, full.length - tailBudget);
     const dropped = full.length - head.length - tail.length;
     return `${head}\n\n[… ${dropped} chars of mid-session transcript elided to fit the summariser's context window …]\n\n${tail}`;
 }
@@ -1892,8 +2244,8 @@ async function runAgentLoop(initialMessages, options) {
     // switch a sub-agent off, and an agent that may not run must not be
     // advertised (see below).
     const settings = (0, rules_1.loadSettings)(options.workDir);
-    // Discover custom sub-agent types. Only the top-level agent is told the
-    // catalogue (sub-agents can't spawn further), but every level resolves types.
+    // Discover custom sub-agent types. Every level resolves types; only a level that may
+    // actually delegate is TOLD the catalogue (see maySpawn below).
     //
     // Denied agents are filtered OUT of the catalogue rather than left in it to be
     // refused on dispatch. Listing an agent you have forbidden trains the model to
@@ -1901,7 +2253,15 @@ async function runAgentLoop(initialMessages, options) {
     // error path would name it again. Enforcement still happens at dispatch
     // (runSubTask) — this is the cosmetic half; that is the load-bearing half.
     const agentTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir).filter((t) => (0, rules_1.evaluatePermission)(settings.permissions, 'task', { subagent_type: t.name }, options.workDir) !== 'deny');
-    const agentsCatalogue = depth === 0 ? (0, agentTypes_1.summariseAgents)(agentTypes) : '';
+    // Can THIS run delegate at all? Previously only the catalogue was gated (`depth === 0`)
+    // while the tool schema and its instructions went to every run — see canSpawnSubAgents.
+    //
+    // The depth limit is resolved from the SAME settings object the rest of the run uses, so
+    // a project that sets maxSubagentDepth gets a prompt matching its own configuration
+    // rather than the built-in default.
+    const depthLimit = resolveMaxSubagentDepth(settings.raw);
+    const maySpawn = canSpawnSubAgents(depth, options._allowedTools, depthLimit);
+    const agentsCatalogue = maySpawn ? (0, agentTypes_1.summariseAgents)(agentTypes) : '';
     // Skills catalogue — unlike agentsCatalogue, available at every depth: a skill is
     // just a reusable prompt template (via use_skill), not another spawn point, so
     // sub-agents benefit from the same playbooks without the recursion concerns that
@@ -2224,6 +2584,9 @@ async function runAgentLoop(initialMessages, options) {
                         ? options._allowedTools.has('memory_write')
                         : true, // no allowlist = main agent = may write
                     hasOwnAgentStore: !!options._agentMemory,
+                    // Withholds the `task` schema and its instructions when this run cannot
+                    // delegate — see canSpawnSubAgents.
+                    canSpawnSubAgents: maySpawn,
                     agents: agentsCatalogue || undefined,
                     skills: skillsCatalogue || undefined,
                     // Only allow a post-render restart when the caller actually implements the
@@ -2515,37 +2878,57 @@ async function runAgentLoop(initialMessages, options) {
                     // sub-task queued behind three long-running siblings could then be
                     // "stopped for stalling" having never executed a single step.
                     //
-                    // Only TOP-LEVEL fan-out is gated (`depth === 0`) — a deliberate
-                    // deadlock guard, kept even though MAX_TASK_DEPTH currently makes a
-                    // nested spawn impossible anyway. A nested spawn would request a slot
-                    // while its parent still holds one; if every slot were held by a parent
-                    // waiting on a child that can never be scheduled, the run would wedge
-                    // permanently. Keeping the limiter acyclic (a holder never re-enters it)
-                    // means raising MAX_TASK_DEPTH later can't silently reintroduce that.
-                    if (depth === 0) {
-                        const { run: limitRun, max: limitMax } = subTaskLimiter(options.workDir);
+                    // EVERY level is gated, each against its own depth's limiter.
+                    //
+                    // This used to be `depth === 0` only, because one shared limiter deadlocks if a
+                    // slot-holder re-enters it — and with sub-agents as leaves, skipping the nested
+                    // case was free. Now that nesting is real, skipping it would leave fan-out below
+                    // level 1 completely unbounded. Per-depth limiters give bounded concurrency at
+                    // every level while keeping the wait-for graph a DAG (a depth-D holder only ever
+                    // waits on depth-D+1), so there is no cycle to deadlock on. See _subTaskLimiters.
+                    // Session budget FIRST, outside the limiter. runSubTask runs inside limitRun, so
+                    // claiming in there meant a spawn that was already over budget queued behind up to
+                    // `max` running siblings before hearing no — in a runaway, i.e. the exact case this
+                    // guard exists for, refusals trickled out at sibling-completion rate.
+                    const overBudget = claimSessionSubAgentSlot(options.workDir, options.onNotice ?? options.onText);
+                    if (overBudget) {
+                        result = { error: overBudget };
+                    }
+                    else {
+                        const childDepth = depth + 1;
+                        const { run: limitRun, max: limitMax } = subTaskLimiter(childDepth, options.workDir);
                         // Tell the user when a sub-task is WAITING rather than working.
                         //
                         // With a burst of 8 and a ceiling of 4, the last four sat silently in the
                         // queue. From the outside they looked started, so a long wait read as a
                         // hang — and the fix for a hang (Ctrl+C and retry) is exactly wrong here,
-                        // since the work was about to run. `_inFlightSubTasks` is only ever
-                        // touched from this single dispatch point, so the count is exact.
-                        if (_inFlightSubTasks >= limitMax) {
-                            (options.onNotice ?? options.onText)(`\u23f3 Queued: ${limitMax} sub-agents are already running, so this one starts when a ` +
-                                `slot frees up (raise "maxConcurrentSubtasks" in .nexrall/settings.json to widen it).`);
+                        // since the work was about to run. Counted per depth, so a level-2 queue is
+                        // not reported using a level-1 count.
+                        const inFlight = _inFlightByDepth.get(childDepth) ?? 0;
+                        if (inFlight >= limitMax) {
+                            (options.onNotice ?? options.onText)(`\u23f3 Queued: ${limitMax} sub-agent(s) already running at this level, so this one ` +
+                                `starts when a slot frees up (raise "maxConcurrentSubtasks" in .nexrall/settings.json ` +
+                                'to widen it).');
                         }
-                        _inFlightSubTasks++;
+                        _inFlightByDepth.set(childDepth, inFlight + 1);
+                        // runSubTask flips this at its point of no return, so a spawn rejected by its own
+                        // validation (empty prompt, a deny rule, an unusable resume id) gives the slot
+                        // back. Without it, a model retrying against a deny rule would burn the entire
+                        // allowance on spawns that never ran and then lose delegation for the session.
+                        const started = { value: false };
                         try {
-                            result = await limitRun(() => runSubTask(input, options, agentTypes));
+                            result = await limitRun(() => runSubTask(input, options, agentTypes, started));
                         }
                         finally {
-                            _inFlightSubTasks--;
+                            if (!started.value)
+                                refundSessionSubAgentSlot();
+                            const n = (_inFlightByDepth.get(childDepth) ?? 1) - 1;
+                            if (n > 0)
+                                _inFlightByDepth.set(childDepth, n);
+                            else
+                                _inFlightByDepth.delete(childDepth); // don't retain a key per depth forever
                         }
                     }
-                    else {
-                        result = await runSubTask(input, options, agentTypes);
-                    }
                 }
                 else {
                     const pre = runToolHooks(hooks.PreToolUse, 'PreToolUse', name, input, options.workDir);