@nexrall/code-core 1.4.66 → 1.4.67

package/dist/agent/subTaskSupport.d.ts

@@ -0,0 +1,156 @@
+import type { Message, ToolResult } from '../types';
+/**
+ * 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.
+ */
+export declare function resolveMaxSubagentDepth(settingsRaw?: Record<string, unknown>): number;
+/**
+ * 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.
+ */
+export declare function noSpawnReason(kind: 'depth' | 'denied', limit?: number): string;
+/**
+ * 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.
+ */
+export declare function intersectAllowlists(own: Set<string> | null, parent: Set<string> | undefined): Set<string> | null;
+export declare function canSpawnSubAgents(depth: number, allowedTools?: Set<string>, limit?: number): boolean;
+/**
+ * How long a sub-agent may make NO progress before it is stopped.
+ *
+ * Precedence matches every other tunable in this file
+ * (env → settings.json → default) — it used to be env-ONLY, which meant a project that
+ * legitimately needed longer sub-tasks had no way to say so in the file where every
+ * other such preference lives, and the limit was invisible to anyone reading settings.
+ *
+ * Exported for tests: the behaviour that matters (a long-but-productive sub-agent is
+ * NOT killed) takes minutes of wall clock to exercise through the real loop.
+ */
+export declare function resolveSubtaskTimeoutMs(settingsRaw: Record<string, unknown>): number;
+/**
+ * Thrown by a sub-agent's permission gate when the AGENT DEFINITION forbids a
+ * tool — as opposed to the user declining it.
+ *
+ * The distinction matters to the model, which is why this is an exception rather
+ * than a `false`: both used to collapse into "Permission denied by user", so an
+ * agent blocked by its own allowlist (very often a mistyped tool name) was told
+ * the human had refused. The rational response to that is to ask again, which
+ * can never succeed. Carrying a reason lets the tool_result say what is actually
+ * true and what to do instead.
+ */
+export declare class ToolNotAllowedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reduce a sub-agent's message history to the text its parent should receive.
+ *
+ * Pure + exported so the salvage rules can be tested without running a real
+ * sub-agent (which needs a live model stream and, for the timeout path, ten
+ * minutes of wall clock).
+ *
+ * `preferLast` — the normal completion path — returns the final assistant
+ * message, which is the sub-agent's actual answer.
+ *
+ * `preferLast: false` is the SALVAGE path, used when the sub-agent was cut off.
+ * A stopped sub-agent usually has no closing summary at all (it was killed
+ * mid-tool-round), so the last assistant message is frequently empty or a
+ * fragment. Concatenating what it did produce is far more useful to the parent
+ * model than nothing: it can build on the work instead of redoing it.
+ */
+export declare function extractSubTaskText(messages: Message[], preferLast?: boolean): string;
+/** Apply the parent-context cap to a sub-task's text, keeping head + tail. */
+export declare function capSubTaskText(text: string, max?: number): string;
+/**
+ * Summarise what a cut-short sub-agent actually accomplished, so the parent model
+ * can continue from it rather than starting over.
+ *
+ * This is the whole point of the salvage path. Previously a timed-out sub-agent
+ * returned ONLY an error string: ten minutes of work, dozens of tool calls and
+ * any files it wrote were invisible to the parent, which typically responded by
+ * re-running the same work from scratch — while the tokens for the discarded run
+ * had already been billed in full.
+ */
+export declare function summariseSubTaskProgress(messages: Message[]): string;
+/**
+ * The last N tool results from a transcript, newest last, each truncated.
+ *
+ * Pure + exported so the salvage rules are testable without a real sub-agent.
+ *
+ * Truncation keeps the HEAD of each result: tool output is overwhelmingly
+ * front-loaded (a file starts with its imports, a failing command starts with its
+ * error), and a head slice is the half that identifies what was found.
+ */
+export declare function lastToolResults(messages: Message[], count: number, maxChars: number): string;
+export declare const HARD_STOPPED: unique symbol;
+export declare function hardStopGraceMs(): number;
+export declare function raceHardStop<T>(run: Promise<T>, abort: {
+    aborted: boolean;
+}): Promise<T | typeof HARD_STOPPED>;
+/** Returned instead of waiting forever for a tool that ignored Stop. */
+export declare const STOP_TIMEOUT_RESULT: ToolResult;
+export declare function stopAwaiting<T>(run: Promise<T>, abort?: {
+    aborted: boolean;
+}): Promise<T | typeof STOP_TIMEOUT_RESULT>;
+/** Default turn limit for a sub-agent whose definition sets no `maxTurns`. */
+export declare const DEFAULT_SUBAGENT_MAX_TURNS = 200;
+/** Stop reasons that mean the sub-agent did NOT deliver a finished report. */
+export declare const ABNORMAL_SUBAGENT_STOPS: Set<string>;
+/**
+ * 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.
+ */
+export declare const SUBAGENT_PREAMBLE: string;
+export declare function formatTokenCount(n: number): string;
+export declare function formatElapsed(ms: number): string;
+//# sourceMappingURL=subTaskSupport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subTaskSupport.d.ts","sourceRoot":"","sources":["../../src/agent/subTaskSupport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAmCpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAOzF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAe9E;AAED;;;;;;;;;;;;;;;GAeG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EACvB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,GAC9B,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAIpB;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,KAAK,GAAE,MAA+B,GACrC,OAAO,CAMT;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAOpF;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,UAAO,GAAG,MAAM,CAYjF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAc,GAAG,MAAM,CAKtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAgCpE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6B5F;AAqBD,eAAO,MAAM,YAAY,eAAyB,CAAC;AACnD,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AACD,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO,YAAY,CAAC,CAW9G;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAE,UAGjC,CAAC;AAEF,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO,mBAAmB,CAAC,CAUtH;AAED,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,aAMlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAIlB,CAAC;AAEb,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGhD"}

package/dist/agent/subTaskSupport.js

@@ -0,0 +1,409 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBAGENT_PREAMBLE = exports.ABNORMAL_SUBAGENT_STOPS = exports.DEFAULT_SUBAGENT_MAX_TURNS = exports.STOP_TIMEOUT_RESULT = exports.HARD_STOPPED = exports.ToolNotAllowedError = void 0;
+exports.resolveMaxSubagentDepth = resolveMaxSubagentDepth;
+exports.noSpawnReason = noSpawnReason;
+exports.intersectAllowlists = intersectAllowlists;
+exports.canSpawnSubAgents = canSpawnSubAgents;
+exports.resolveSubtaskTimeoutMs = resolveSubtaskTimeoutMs;
+exports.extractSubTaskText = extractSubTaskText;
+exports.capSubTaskText = capSubTaskText;
+exports.summariseSubTaskProgress = summariseSubTaskProgress;
+exports.lastToolResults = lastToolResults;
+exports.hardStopGraceMs = hardStopGraceMs;
+exports.raceHardStop = raceHardStop;
+exports.stopAwaiting = stopAwaiting;
+exports.formatTokenCount = formatTokenCount;
+exports.formatElapsed = formatElapsed;
+const safeSlice_1 = require("../util/safeSlice");
+// ─── Sub-task runner ──────────────────────────────────────────────────────────
+// 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.
+//
+// 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;
+}
+// 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
+// own — it shared only the PARENT's overall iteration budget, so a genuinely
+// stuck sub-agent could silently occupy the whole run with no distinct signal
+// pointing at it specifically. Give every sub-task an explicit wall-clock cap:
+// if it hasn't finished by then, fail it clearly instead of hanging the parent
+// turn indefinitely. Overridable via env for slow CI machines / huge sub-tasks.
+const DEFAULT_SUBTASK_TIMEOUT_MS = 10 * 60 * 1000; // 10 min of NO PROGRESS (see the watchdog)
+/**
+ * How long a sub-agent may make NO progress before it is stopped.
+ *
+ * Precedence matches every other tunable in this file
+ * (env → settings.json → default) — it used to be env-ONLY, which meant a project that
+ * legitimately needed longer sub-tasks had no way to say so in the file where every
+ * other such preference lives, and the limit was invisible to anyone reading settings.
+ *
+ * Exported for tests: the behaviour that matters (a long-but-productive sub-agent is
+ * NOT killed) takes minutes of wall clock to exercise through the real loop.
+ */
+function resolveSubtaskTimeoutMs(settingsRaw) {
+    const fromEnv = Number(process.env.NEXRALL_SUBTASK_TIMEOUT_MS);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return Math.floor(fromEnv);
+    const raw = settingsRaw.subtaskTimeoutMs;
+    const fromSettings = Number(raw);
+    if (Number.isFinite(fromSettings) && fromSettings > 0)
+        return Math.floor(fromSettings);
+    return DEFAULT_SUBTASK_TIMEOUT_MS;
+}
+/** Cap on the text a sub-task hands back, so one verbose sub-agent can't blow up
+ *  the PARENT's context in a single tool_result. */
+const SUBTASK_MAX = 48000; // chars (~12k tokens)
+/**
+ * Thrown by a sub-agent's permission gate when the AGENT DEFINITION forbids a
+ * tool — as opposed to the user declining it.
+ *
+ * The distinction matters to the model, which is why this is an exception rather
+ * than a `false`: both used to collapse into "Permission denied by user", so an
+ * agent blocked by its own allowlist (very often a mistyped tool name) was told
+ * the human had refused. The rational response to that is to ask again, which
+ * can never succeed. Carrying a reason lets the tool_result say what is actually
+ * true and what to do instead.
+ */
+class ToolNotAllowedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolNotAllowedError';
+    }
+}
+exports.ToolNotAllowedError = ToolNotAllowedError;
+// 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.
+ *
+ * Pure + exported so the salvage rules can be tested without running a real
+ * sub-agent (which needs a live model stream and, for the timeout path, ten
+ * minutes of wall clock).
+ *
+ * `preferLast` — the normal completion path — returns the final assistant
+ * message, which is the sub-agent's actual answer.
+ *
+ * `preferLast: false` is the SALVAGE path, used when the sub-agent was cut off.
+ * A stopped sub-agent usually has no closing summary at all (it was killed
+ * mid-tool-round), so the last assistant message is frequently empty or a
+ * fragment. Concatenating what it did produce is far more useful to the parent
+ * model than nothing: it can build on the work instead of redoing it.
+ */
+function extractSubTaskText(messages, preferLast = true) {
+    const assistants = messages.filter((m) => m.role === 'assistant');
+    const textOf = (m) => (m?.content ?? [])
+        .filter((b) => b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('')
+        .trim();
+    if (preferLast)
+        return textOf(assistants[assistants.length - 1]);
+    return assistants.map(textOf).filter(Boolean).join('\n\n').trim();
+}
+/** Apply the parent-context cap to a sub-task's text, keeping head + tail. */
+function capSubTaskText(text, max = SUBTASK_MAX) {
+    if (text.length <= max)
+        return text;
+    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}`;
+}
+/**
+ * Summarise what a cut-short sub-agent actually accomplished, so the parent model
+ * can continue from it rather than starting over.
+ *
+ * This is the whole point of the salvage path. Previously a timed-out sub-agent
+ * returned ONLY an error string: ten minutes of work, dozens of tool calls and
+ * any files it wrote were invisible to the parent, which typically responded by
+ * re-running the same work from scratch — while the tokens for the discarded run
+ * had already been billed in full.
+ */
+function summariseSubTaskProgress(messages) {
+    const toolNames = [];
+    for (const m of messages) {
+        if (m.role !== 'assistant' || !Array.isArray(m.content))
+            continue;
+        for (const b of m.content) {
+            if (b?.type === 'tool_use' && typeof b.name === 'string')
+                toolNames.push(b.name);
+        }
+    }
+    if (toolNames.length === 0)
+        return '';
+    // The FINDINGS, not just the activity log.
+    //
+    // An inventory of tool names ("read_file ×9, bash ×14") tells the parent that work
+    // happened but nothing about what was learned, so it re-derives everything. A stalled
+    // research agent's value is almost entirely in what its last few tool calls RETURNED
+    // — the file it had just read, the command output it was about to interpret — because
+    // its own prose summary is exactly the thing it never got to write.
+    const recentFindings = lastToolResults(messages, SALVAGE_RESULT_COUNT, SALVAGE_RESULT_CHARS);
+    // Collapse to "name ×N" so a 40-call run reads as a short inventory rather
+    // than forty repeated lines of the same tool name.
+    const counts = new Map();
+    for (const n of toolNames)
+        counts.set(n, (counts.get(n) ?? 0) + 1);
+    const inventory = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([name, n]) => (n > 1 ? `${name} ×${n}` : name))
+        .join(', ');
+    const header = `Tool calls completed before it was stopped (${toolNames.length} total): ${inventory}.`;
+    return recentFindings
+        ? `${header}\n\nWhat its most recent tool calls actually returned (use this instead of repeating them):\n${recentFindings}`
+        : header;
+}
+/** How many trailing tool results to salvage, and how much of each. */
+const SALVAGE_RESULT_COUNT = 4;
+const SALVAGE_RESULT_CHARS = 2000;
+/**
+ * The last N tool results from a transcript, newest last, each truncated.
+ *
+ * Pure + exported so the salvage rules are testable without a real sub-agent.
+ *
+ * Truncation keeps the HEAD of each result: tool output is overwhelmingly
+ * front-loaded (a file starts with its imports, a failing command starts with its
+ * error), and a head slice is the half that identifies what was found.
+ */
+function lastToolResults(messages, count, maxChars) {
+    // Map tool_use id → tool name, so a salvaged result can say WHICH tool produced it.
+    const nameById = new Map();
+    for (const m of messages) {
+        if (m.role !== 'assistant' || !Array.isArray(m.content))
+            continue;
+        for (const b of m.content) {
+            if (b?.type === 'tool_use' && b.id && typeof b.name === 'string')
+                nameById.set(b.id, b.name);
+        }
+    }
+    const out = [];
+    // Walk backwards and stop early: only the most recent results are worth the tokens,
+    // and a long research run may hold hundreds.
+    for (let i = messages.length - 1; i >= 0 && out.length < count; i--) {
+        const m = messages[i];
+        if (m.role !== 'user' || !Array.isArray(m.content))
+            continue;
+        for (const b of [...m.content].reverse()) {
+            if (out.length >= count)
+                break;
+            if (b?.type !== 'tool_result')
+                continue;
+            const text = toolResultText(b);
+            if (!text)
+                continue;
+            const name = nameById.get(String(b.tool_use_id ?? '')) ?? 'tool';
+            const body = text.length > maxChars
+                ? `${(0, safeSlice_1.sliceSafeEnd)(text, maxChars)}\n… [truncated]`
+                : text;
+            out.push(`• ${name}:\n${body}`);
+        }
+    }
+    return out.reverse().join('\n\n');
+}
+/** Extract readable text from a tool_result block, whose content may be string or blocks. */
+function toolResultText(block) {
+    const c = block.content;
+    if (typeof c === 'string')
+        return c.trim();
+    if (Array.isArray(c)) {
+        return c
+            .filter((x) => x?.type === 'text' && typeof x.text === 'string')
+            .map((x) => x.text)
+            .join('\n')
+            .trim();
+    }
+    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.
+exports.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(exports.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. */
+exports.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(exports.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`. */
+exports.DEFAULT_SUBAGENT_MAX_TURNS = 200;
+/** Stop reasons that mean the sub-agent did NOT deliver a finished report. */
+exports.ABNORMAL_SUBAGENT_STOPS = new Set([
+    'budget', 'stalled', 'stalled-repeat', 'output-limit', 'empty-response',
+    'no-balance', 'no-team-budget', 'team-unavailable', 'reported-elsewhere',
+    // A hook stopping the batch means the sub-agent stopped short of its report, so the
+    // parent must not read the result as a finished one.
+    'hook-blocked',
+]);
+/**
+ * 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.
+ */
+exports.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`;
+}
+//# sourceMappingURL=subTaskSupport.js.map

package/dist/agent/toolDescriptions.d.ts

@@ -0,0 +1,3 @@
+export declare function renderPeerMessages(msgs: import('./peerTransport').PeerMessage[]): string;
+export declare function humanDescription(name: string, input: Record<string, unknown>): string;
+//# sourceMappingURL=toolDescriptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toolDescriptions.d.ts","sourceRoot":"","sources":["../../src/agent/toolDescriptions.ts"],"names":[],"mappings":"AASA,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,WAAW,EAAE,GAAG,MAAM,CAMxF;AAID,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA0HrF"}