@nexrall/code-core 1.4.66 → 1.4.68

package/dist/agent/planMode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planMode.d.ts","sourceRoot":"","sources":["../../src/agent/planMode.ts"],"names":[],"mappings":"AAgJA,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAAC;IAC/C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAqFD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA8D1D;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,GAAG,IAAI,CAoCxB;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,QAqBvB,CAAC"}
+{"version":3,"file":"planMode.d.ts","sourceRoot":"","sources":["../../src/agent/planMode.ts"],"names":[],"mappings":"AAiJA,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAAC;IAC/C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAqFD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CA8D1D;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,GAAG,IAAI,CAoCxB;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,QAqBvB,CAAC"}

package/dist/agent/planMode.js

@@ -36,6 +36,7 @@ const READ_ONLY_TOOLS = new Set([
     // list, not the repo, so it stays available — a plan mode that cannot draft
     // a checklist is missing the point of plan mode.
     'todo_write', 'todo_read',
+    'cron_list', 'mcp_list_resources', 'mcp_read_resource',
     // Reading memory is fine; memory_write is NOT here on purpose. Memory is
     // durable state that survives the session, so writing it is a real mutation
     // even though no file in the repo changes.

package/dist/agent/sharedTasks.d.ts

@@ -59,5 +59,12 @@ export declare const _sharedTasksInternal: {
     CLAIM_STALE_MS: number;
     MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS: number;
 };
+/**
+ * Remove a task outright — the veto path for a `TaskCreated` hook. Claude Code creates the
+ * task, and when a hook refuses it the task is DELETED and the reason goes back to the
+ * model as the tool's error; so "no task remains" is the observable contract of a veto,
+ * and this is the only place that needs to make it true.
+ */
+export declare function deleteSharedTask(workDir: string, taskId: string): boolean;
 export {};
 //# sourceMappingURL=sharedTasks.d.ts.map

package/dist/agent/sharedTasks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharedTasks.d.ts","sourceRoot":"","sources":["../../src/agent/sharedTasks.ts"],"names":[],"mappings":"AA6DA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,4HAA4H;IAC5H,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8HAA8H;IAC9H,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0BD,iBAAS,SAAS,IAAI,MAAM,CAE3B;AAED,iBAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzC;AAED,iBAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AA4BD,0HAA0H;AAC1H,iBAAS,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAUnD;AAED,4GAA4G;AAC5G,iBAAS,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAG/D;AAED,0IAA0I;AAC1I,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAW7D;AAED,sJAAsJ;AACtJ,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC/C,UAAU,CAUZ;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,GAAG,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+BxG;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACrF,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAED,eAAO,MAAM,oBAAoB;;;;;;;;CAAqH,CAAC"}
+{"version":3,"file":"sharedTasks.d.ts","sourceRoot":"","sources":["../../src/agent/sharedTasks.ts"],"names":[],"mappings":"AA6DA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,4HAA4H;IAC5H,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8HAA8H;IAC9H,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0BD,iBAAS,SAAS,IAAI,MAAM,CAE3B;AAED,iBAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzC;AAED,iBAAS,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AA4BD,0HAA0H;AAC1H,iBAAS,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAUnD;AAED,4GAA4G;AAC5G,iBAAS,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAG/D;AAED,0IAA0I;AAC1I,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAW7D;AAED,sJAAsJ;AACtJ,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC/C,UAAU,CAUZ;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,GAAG,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+BxG;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACrF,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAED,eAAO,MAAM,oBAAoB;;;;;;;;CAAqH,CAAC;AAEvJ;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzE"}

package/dist/agent/sharedTasks.js

@@ -38,6 +38,7 @@ exports.listSharedTasks = listSharedTasks;
 exports.createSharedTask = createSharedTask;
 exports.claimTask = claimTask;
 exports.updateSharedTaskStatus = updateSharedTaskStatus;
+exports.deleteSharedTask = deleteSharedTask;
 /**
  * Shared task list — lets MULTIPLE independent sessions (two CLI windows, or
  * CLI + VS Code + Desktop, all working the same project) coordinate who is
@@ -281,4 +282,19 @@ async function updateSharedTaskStatus(workDir, taskId, status, opts = {}) {
     }, workDir);
 }
 exports._sharedTasksInternal = { tasksRoot, scopeDir, taskPath, isClaimAbandoned, isUnblocked, CLAIM_STALE_MS, MIN_CLAIM_AGE_FOR_DEATH_CHECK_MS };
+/**
+ * Remove a task outright — the veto path for a `TaskCreated` hook. Claude Code creates the
+ * task, and when a hook refuses it the task is DELETED and the reason goes back to the
+ * model as the tool's error; so "no task remains" is the observable contract of a veto,
+ * and this is the only place that needs to make it true.
+ */
+function deleteSharedTask(workDir, taskId) {
+    try {
+        fs.unlinkSync(taskPath(workDir, taskId));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=sharedTasks.js.map

package/dist/agent/subAgentBudget.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 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.
+ */
+export declare function resolveMaxConcurrentSubtasks(settingsRaw?: Record<string, unknown>): number;
+/** Resolve the session-total sub-agent ceiling: env → settings.json → default. */
+export declare function resolveMaxSubagentsPerSession(settingsRaw?: Record<string, unknown>): number;
+/**
+ * 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
+ * dozen lines.
+ */
+export declare function createLimiter(max: number): <T>(fn: () => Promise<T>) => Promise<T>;
+/** In-flight count per depth — used only to detect queueing, so the notice is accurate. */
+export declare const _inFlightByDepth: Map<number, number>;
+export declare function subTaskLimiter(depth: number, workDir?: string): {
+    run: <T>(fn: () => Promise<T>) => Promise<T>;
+    max: number;
+};
+/** Test-only: forget the memoised limiter so a new limit can take effect. */
+export declare function _resetSubTaskLimiter(): void;
+export declare const PROCESS_BUDGET_KEY = "\0process";
+/**
+ * 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.
+ */
+export declare function resetSessionSubAgentBudget(sessionKey?: string): void;
+/**
+ * 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.
+ */
+export declare function claimSessionSubAgentSlot(workDir?: string, notify?: (msg: string) => void, sessionKey?: string): string | 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.
+ */
+export declare function refundSessionSubAgentSlot(sessionKey?: string): void;
+/** Test-only: observe the session counter without exporting the mutable binding. */
+export declare function _sessionSubAgentCount(sessionKey?: string): number;
+//# sourceMappingURL=subAgentBudget.d.ts.map

package/dist/agent/subAgentBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subAgentBudget.d.ts","sourceRoot":"","sources":["../../src/agent/subAgentBudget.ts"],"names":[],"mappings":"AAyCA;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAW9F;AAoBD,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAa/F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAgBlF;AA8BD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,qBAA4B,CAAC;AAE1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;IAC/D,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb,CAuBA;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C;AAkBD,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAQ9C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAGpE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB7H;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAGnE;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/agent/subAgentBudget.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROCESS_BUDGET_KEY = exports._inFlightByDepth = void 0;
+exports.resolveMaxConcurrentSubtasks = resolveMaxConcurrentSubtasks;
+exports.resolveMaxSubagentsPerSession = resolveMaxSubagentsPerSession;
+exports.createLimiter = createLimiter;
+exports.subTaskLimiter = subTaskLimiter;
+exports._resetSubTaskLimiter = _resetSubTaskLimiter;
+exports.resetSessionSubAgentBudget = resetSessionSubAgentBudget;
+exports.claimSessionSubAgentSlot = claimSessionSubAgentSlot;
+exports.refundSessionSubAgentSlot = refundSessionSubAgentSlot;
+exports._sessionSubAgentCount = _sessionSubAgentCount;
+const rules_1 = require("../permissions/rules");
+// ─── Sub-agent fan-out limiter ────────────────────────────────────────────────
+//
+// Tool calls in one turn run via Promise.all with no ceiling. For ordinary tools
+// that is right — they're cheap and mostly I/O — but a `task` call spawns a WHOLE
+// nested agent loop: its own model stream, its own tool executions, its own
+// sub-process spawns. A model that emits ten `task` blocks in one turn therefore
+// starts ten concurrent agents, each billing tokens and competing for the same
+// CPU, file handles and API rate limit. The practical symptoms are the ones users
+// report as "it got slow and then stalled": every sub-agent's stream slows, some
+// trip their own stall watchdog, and one shared rate limit is spread across ten
+// callers.
+//
+// Anthropic hit the same wall and capped Claude Code's concurrent subagents at 20
+// (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 = 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 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), HARD_MAX_CONCURRENT_SUBTASKS));
+    const fromEnv = Number(process.env.NEXRALL_MAX_CONCURRENT_SUBTASKS);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return clamp(fromEnv);
+    const fromSettings = Number(settingsRaw.maxConcurrentSubtasks);
+    if (Number.isFinite(fromSettings) && fromSettings > 0)
+        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
+ * dozen lines.
+ */
+function createLimiter(max) {
+    let active = 0;
+    const queue = [];
+    const release = () => {
+        active--;
+        queue.shift()?.();
+    };
+    return async (fn) => {
+        if (active >= max)
+            await new Promise((resolve) => queue.push(resolve));
+        active++;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    };
+}
+// Process-wide, deliberately: the limit exists to protect shared resources (CPU,
+// the API rate limit, file handles), and those are shared across every concurrent
+// turn in this process, not just the tool calls of one message.
+//
+// Built LAZILY on first use rather than at module load, because the limit can now come
+// from settings.json and the workspace is not known when this module is imported.
+// 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.
+// 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;
+/** In-flight count per depth — used only to detect queueing, so the notice is accurate. */
+exports._inFlightByDepth = new Map();
+function subTaskLimiter(depth, workDir) {
+    if (!_subTaskLimitMax) {
+        _subTaskLimitMax = resolveMaxConcurrentSubtasks(workDir ? (0, rules_1.loadSettings)(workDir).raw : {});
+    }
+    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: 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` (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.
+        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() {
+    _subTaskLimiters.clear();
+    _subTaskLimitMaxByDepth.clear();
+    exports._inFlightByDepth.clear();
+    _subTaskLimitMax = 0;
+    _subAgentBudgets.clear();
+}
+const _subAgentBudgets = new Map();
+exports.PROCESS_BUDGET_KEY = '\0process';
+function budgetFor(sessionKey) {
+    const key = sessionKey || exports.PROCESS_BUDGET_KEY;
+    let b = _subAgentBudgets.get(key);
+    if (!b) {
+        b = { used: 0, max: 0, notified: false };
+        _subAgentBudgets.set(key, b);
+    }
+    return b;
+}
+/**
+ * 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(sessionKey) {
+    // No key: the legacy "new conversation" call — reset the process-wide budget only.
+    _subAgentBudgets.delete(sessionKey || exports.PROCESS_BUDGET_KEY);
+}
+/**
+ * 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, sessionKey) {
+    const b = budgetFor(sessionKey);
+    if (!b.max) {
+        b.max = resolveMaxSubagentsPerSession(workDir ? (0, rules_1.loadSettings)(workDir).raw : {});
+    }
+    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.');
+        }
+        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.');
+    }
+    b.used++;
+    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(sessionKey) {
+    const b = budgetFor(sessionKey);
+    if (b.used > 0)
+        b.used--;
+}
+/** Test-only: observe the session counter without exporting the mutable binding. */
+function _sessionSubAgentCount(sessionKey) {
+    return budgetFor(sessionKey).used;
+}
+//# sourceMappingURL=subAgentBudget.js.map

package/dist/agent/subTask.d.ts

@@ -0,0 +1,15 @@
+import type { Message, ToolResult, AgentLoopOptions } from '../types';
+import { type AgentType } from './agentTypes';
+/**
+ * A conversation to FORK into the sub-agent (the `/subtask` command) instead of running it
+ * with a fresh, isolated context. The parent's transcript is copied in as the child's
+ * opening history, so it starts out knowing everything the main agent knows.
+ */
+export interface ForkContext {
+    /** The conversation so far, as the caller's live array — copied, never aliased. */
+    messages: Message[];
+}
+export declare function runSubTask(input: Record<string, unknown>, options: AgentLoopOptions, agentTypes: AgentType[], started: {
+    value: boolean;
+} | undefined, runChild: (messages: Message[], options: AgentLoopOptions) => Promise<Message[]>, fork?: ForkContext): Promise<ToolResult>;
+//# sourceMappingURL=subTask.d.ts.map

package/dist/agent/subTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subTask.d.ts","sourceRoot":"","sources":["../../src/agent/subTask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAiB,MAAM,UAAU,CAAC;AAGrF,OAAO,EAA6C,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAezF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,SAAS,EAAE,EAQvB,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,EAEvC,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,EAIhF,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC,CAmvBrB"}