@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/dist/sdk/sessions/sessions.js

@@ -18,15 +18,17 @@ import { FIRST_PARTY_PLUGINS, firstPartyExtensions } from "../plugins/firstParty
 import { imagePruning } from "../world/images.js";
 import { materialise } from "../variant/materialise.js";
 import { ASK_USER } from "../tools/askUser.js";
-import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { defaultSkillPaths } from "../tools/defaultSkills.js";
+import { TODO_WRITE } from "../tools/todo.js";
 import { CHECKPOINT_WRITE, checkpointOf } from "../tools/checkpoint.js";
-import { SESSION_NAME, sessionNameTool } from "../tools/sessionName.js";
+import { SESSION_NAME, deriveSessionName, sessionNameTool } from "../tools/sessionName.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
 import { GET_CAPABILITIES, getCapabilitiesTool } from "../tools/getCapabilities.js";
 import { isActiveStatus } from "./contracts.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, subagentDepth, subagentHistory, subagentNesting } from "./subagents.js";
 import { selectHistory } from "./history.js";
 import { runLineageJoin } from "./lineageJoin.js";
+import { latestSessionName } from "./sessionState.js";
 import { compactionCheckpoint, COMPACTION_CHECKPOINT_EXTENSION } from "./compactionCheckpoint.js";
 import { createSliceState, parseWorkSlice, sliceOf, workSliceGuard, WorkSliceError, WORK_SLICE_EXTENSION } from "./workSlice.js";
 import { piSessionFactory, runTurn, summarize } from "./runner.js";
@@ -400,7 +402,7 @@ export class Sessions {
         const canAskUser = pinnedAskUser || (interactivePlan && harnessToolsEnabled);
         const requestedTools = [...new Set([
                 ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT && name !== WAIT_SUBAGENTS && (name !== ASK_USER || canAskUser)),
-                ...(harnessToolsEnabled ? [...(canAskUser ? [ASK_USER] : []), CHECKLIST_WRITE, CHECKPOINT_WRITE, SESSION_NAME, GET_CAPABILITIES, ...DEFAULT_TOOL_NAMES] : []),
+                ...(harnessToolsEnabled ? [...(canAskUser ? [ASK_USER] : []), TODO_WRITE, CHECKPOINT_WRITE, SESSION_NAME, GET_CAPABILITIES, ...DEFAULT_TOOL_NAMES] : []),
                 ...(broker?.toolNames ?? []),
                 ...(canSpawn ? [SPAWN_SUBAGENT, WAIT_SUBAGENTS] : [])
             ])];
@@ -452,7 +454,9 @@ export class Sessions {
             variantScope: variant?.scope ?? null,
             variantVersion: variant?.fingerprint ?? null,
             ...(input.run.profile ? { profile: input.run.profile } : {}),
-            ...(input.run.title ? { title: input.run.title } : {})
+            ...(input.run.title ? { title: input.run.title } : {}),
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.effort ? { effort: input.effort } : {})
         });
         // What the session is, kept with the run so later consolidation knows which memory it had.
         try {
@@ -466,6 +470,28 @@ export class Sessions {
             updateRun(root, runId, (record) => Object.assign(record, { status: 'failed', endedAt: now(), terminalReason: message }));
             log(`session ${runId} did not start: ${message}`, code);
         };
+        // Plugins are resolved once per run: for the profiles the prompt lists, then for what Pi loads.
+        const { plugins } = this.options;
+        let pluginLoading = null;
+        const loadPlugins = plugins
+            ? () => (pluginLoading ??= plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }, contributions: capabilities.contributions }))
+            : null;
+        // A person's main session sees its current name and whether this run's todo is empty. A
+        // command, child, side question or unattended run has no such state to show.
+        const stateEligible = !input.command
+            && !input.run.relation
+            && (input.depth ?? 0) === 0
+            && !input.automatic
+            && (input.run.trigger == null || input.run.trigger === 'user');
+        const existingName = stateEligible ? latestSessionName(historyFile) : null;
+        const sessionState = stateEligible
+            ? {
+                name: existingName,
+                todo: [],
+                ...(continuation?.todo.length ? { previousTodo: continuation.todo } : {}),
+                firstTurn: !historyFile
+            }
+            : undefined;
         let system;
         let update;
         try {
@@ -476,12 +502,22 @@ export class Sessions {
             const delivered = historyFile ? deliveredSnapshot(historyFile) : null;
             const resumed = continuationSection(continuation, delivered?.some((entry) => entry.id === CONTINUATION_SECTION_ID) ?? false);
             // The profiles replace the variant's own subagent list, which they include.
-            const profiles = capabilities.tools.includes(SPAWN_SUBAGENT) ? profileSection(root, input.cwd, variant?.dir ?? null, input.plan === true) : null;
+            const researchContext = input.plan === true ? {
+                frozenTools: capabilities.tools,
+                contributions: capabilities.contributions,
+                descriptors: BUILTIN_PLUGIN_REGISTRY.descriptors()
+            } : undefined;
+            if (capabilities.tools.includes(SPAWN_SUBAGENT) && loadPlugins && !input.automatic)
+                input.packageProfiles = (await loadPlugins()).profilePaths;
+            const profiles = capabilities.tools.includes(SPAWN_SUBAGENT)
+                ? profileSection(root, input.cwd, variant?.dir ?? null, input.plan === true, researchContext, input.packageProfiles ?? [])
+                : null;
             if (profiles && variant)
                 variant = { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) };
             const own = [plan, resumed, profiles].filter((section) => section !== null);
             const effectiveLaunch = {
                 ...launch,
+                ...(sessionState ? { sessionState } : {}),
                 sections: own.length ? [...(launch.sections ?? []).filter((section) => !own.some((entry) => entry.id === section.id)), ...own] : launch.sections,
                 tools: capabilities.tools,
                 connectionTools: (launch.connectionTools ?? []).filter((name) => capabilities.tools.includes(name)),
@@ -493,8 +529,10 @@ export class Sessions {
             fail(error);
             throw error;
         }
-        // A reply is bounded only when its checkpoint tool is part of the frozen capability set.
-        const sliceEnabled = slicePolicy.enabled && capabilities.tools.includes(CHECKPOINT_WRITE);
+        // Plan-research children are bounded too, but their read-only capability set omits checkpoint_write.
+        const checkpointAvailable = capabilities.tools.includes(CHECKPOINT_WRITE);
+        const planResearchChild = input.plan === true && input.run.relation === 'subagent';
+        const sliceEnabled = slicePolicy.enabled && (checkpointAvailable || planResearchChild);
         const sliceState = createSliceState(slicePolicy, sliceOf(root, runId));
         const run = this.options.runs.start(input.run.sessionId, runId);
         if (run.finished)
@@ -505,7 +543,6 @@ export class Sessions {
         // What every session has, after the tools the caller switched on and in a fixed order.
         const allow = capabilities.tools;
         const session = { run, caller, allow, depth, cwd: input.cwd, capabilities };
-        const { plugins } = this.options;
         let pi;
         const naming = sessionNameTool(() => {
             const current = pi;
@@ -587,17 +624,17 @@ export class Sessions {
                 preamble: input.preamble ?? null,
                 automatic: input.automatic,
                 account: context,
-                resources: { ids: [], skillPaths: variant?.skillPaths ?? [], promptPaths: [] },
+                resources: { ids: [], skillPaths: [...(variant?.skillPaths ?? []), ...defaultSkillPaths(variant?.dir)], promptPaths: [] },
                 variantExtensions: variant?.extensionPaths ?? [],
                 inline: [
                     ...firstPartyFor(root, capabilities.contributions),
                     runLineageJoin(root, runId),
                     this.options.subagents.extension(runId),
                     { name: 'image-pruning', factory: imagePruning() },
-                    { name: COMPACTION_CHECKPOINT_EXTENSION, factory: compactionCheckpoint({ initialChecklist: continuation?.checklist, planInstructions: checkpointPlanInstructions }) },
-                    ...(sliceEnabled ? [{ name: WORK_SLICE_EXTENSION, factory: workSliceGuard({ policy: slicePolicy, state: sliceState }) }] : [])
+                    { name: COMPACTION_CHECKPOINT_EXTENSION, factory: compactionCheckpoint({ initialTodo: continuation?.todo, planInstructions: checkpointPlanInstructions }) },
+                    ...(sliceEnabled ? [{ name: WORK_SLICE_EXTENSION, factory: workSliceGuard({ policy: slicePolicy, state: sliceState, checkpointAvailable }) }] : [])
                 ],
-                ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }, contributions: capabilities.contributions }), loaded: (extensions) => plugins.loaded(extensions) } } : {}),
+                ...(plugins && loadPlugins ? { plugins: { loading: loadPlugins, loaded: (extensions) => plugins.loaded(extensions) } } : {}),
                 system,
                 ...(sliceEnabled ? { slice: { state: sliceState, maxToolCalls: slicePolicy.maxToolCalls } } : {}),
                 // A command sends no request of its own, so the context update waits for the next turn.
@@ -624,11 +661,32 @@ export class Sessions {
                 run.finish('failed', { code: 'native_resume_unavailable', message: 'The saved conversation could not be restored.' });
                 throw new HarnessError('native_resume_unavailable', 'The saved conversation could not be restored.');
             }
+            // The fallback is a name, not a task step: a refused or failed name never fails the run.
+            if (stateEligible && input.autoName !== false && !existingName && !pi.sessionName
+                && pi.setSessionName && capabilities.tools.includes(SESSION_NAME)) {
+                const name = deriveSessionName(input.text);
+                if (name) {
+                    try {
+                        if (await gate.check(SESSION_NAME, { name }) === null)
+                            pi.setSessionName(name);
+                    }
+                    catch {
+                        // Session naming is metadata; leave the session unnamed.
+                    }
+                }
+            }
             const opened = pi;
-            updateRun(root, runId, (record) => void (record.nativeSessionId = opened.sessionId));
+            const openedModel = pi.model?.id && pi.model.provider ? `${pi.model.provider}/${pi.model.id}` : null;
+            updateRun(root, runId, (record) => {
+                record.nativeSessionId = opened.sessionId;
+                if (openedModel)
+                    record.model = openedModel;
+                if (opened.thinkingLevel)
+                    record.effort = opened.thinkingLevel;
+            });
             this.options.subagents.register(input, account.id, capabilities, Boolean(pi.sessionManager));
-            if (pi.model?.id && pi.model.provider)
-                this.options.subagents.resolvedModel(runId, `${pi.model.provider}/${pi.model.id}`, pi.thinkingLevel);
+            if (openedModel)
+                this.options.subagents.resolvedModel(runId, openedModel, pi.thinkingLevel);
             params.settle = () => this.options.subagents.verify(runId, opened.sessionManager ? subagentHistory(opened.sessionManager.getBranch()) : undefined);
             void runTurn(run, pi, params).then(() => (sliceEnabled && !input.command ? this.continueSlice({ root, runId, source: input, policy: slicePolicy }) : undefined));
             return { runId, nativeSessionId: pi.sessionId };

package/dist/sdk/sessions/subagentService.d.ts

@@ -14,6 +14,7 @@ type Started = {
 export type SpawnedSubagent = Started & {
     agent?: string;
     unavailableTools?: string[];
+    continued?: string;
 };
 export interface SubagentRuntimeSettings {
     model: string | null;
@@ -42,9 +43,23 @@ export declare class Subagents {
     private rememberRuntimeSettings;
     resolvedModel(runId: string, model: string, effort?: Effort): void;
     private parent;
+    private planSpawnCheck;
     /** The plan-mode per-call gate and spawn implementation share this eligibility check. */
     planSpawnRefusal(parentRunId: string, args: unknown): string | null;
     spawn(request: SubagentInput): Promise<SpawnedSubagent>;
+    /** Records ownership, starts the child, and writes a failed record when it never opened. */
+    private launchChild;
+    /** The children this parent may read or continue: its own, and those recovered from its history. */
+    private owned;
+    /** The newest run in a continued child's chain, among the runs this parent owns. */
+    private latestLink;
+    /** The first run of a chain: its folder holds the child's history for every later link. */
+    private firstLink;
+    /**
+     * Continues a stopped child as a new child run with `continueFrom`: the same history, profile,
+     * account, variant version and capability set, which must still lie within the parent's.
+     */
+    private continueChild;
     private selected;
     results(selection: SubagentSelection): SubagentResult[];
     wait(selection: SubagentSelection, signal?: AbortSignal): Promise<SubagentResult[]>;

package/dist/sdk/sessions/subagentService.js

@@ -6,10 +6,11 @@ import { now } from "../core/fs.js";
 import { takeChars } from "../core/text.js";
 import { isActiveStatus } from "./contracts.js";
 import { narrowForProfile } from "../agents/narrow.js";
-import { PLAN_RESEARCH_EVIDENCE_TOOLS, PLAN_RESEARCH_TOOLS, planResearchProfile } from "../agents/planResearch.js";
+import { planResearchEligibility } from "../agents/planResearch.js";
 import { resolveProfile } from "../agents/profiles.js";
+import { continuationOf } from "./continuation.js";
 import { findRun, loadRun, readEvents, recordedSubagents, recordSubagent, saveRun } from "./runStore.js";
-import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, briefTitle, subagentHistory, subagentTitle } from "./subagents.js";
+import { SPAWN_SUBAGENT, SUBAGENT_RELATION, SUBAGENT_OWNER, SUBAGENT_RECEIPT, SUBAGENT_RESULTS, briefTitle, continueHint, subagentHistory, subagentTitle } from "./subagents.js";
 function until(promise, signal) {
     if (signal.aborted) {
         void promise.catch(() => { });
@@ -95,39 +96,53 @@ export class Subagents {
             throw new HarnessError('run_not_active', 'The parent run is not accepting subagents.');
         return parent;
     }
-    /** The plan-mode per-call gate and spawn implementation share this eligibility check. */
-    planSpawnRefusal(parentRunId, args) {
+    planSpawnCheck(parentRunId, args) {
         const parent = this.parents.get(parentRunId);
         if (!parent || !this.runs.active(parentRunId))
-            return 'The parent run is not accepting subagents.';
+            return { refusal: 'The parent run is not accepting subagents.' };
         if (!parent.input.plan)
-            return 'Read-only research delegation is available only during plan mode.';
+            return { refusal: 'Read-only research delegation is available only during plan mode.' };
         if (!parent.capabilities.tools.includes(SPAWN_SUBAGENT))
-            return 'Subagents are not enabled for this run.';
+            return { refusal: 'Subagents are not enabled for this run.' };
         if (!args || typeof args !== 'object' || Array.isArray(args))
-            return 'Plan-mode delegation requires a named, eligible read-only research profile.';
-        const request = args;
+            return { refusal: 'Plan-mode delegation requires a named, eligible read-only research profile.' };
+        let request = args;
+        if (request.continue !== undefined) {
+            // A continued child keeps its own profile; judge that profile.
+            const id = typeof request.continue === 'string' ? request.continue.trim() : '';
+            const record = id && this.owned(parentRunId, parent).has(id) ? findRun(this.env.root, id) : null;
+            if (!record?.profile)
+                return { refusal: 'Plan mode can continue only a stopped research subagent of this conversation that has a named profile.' };
+            if (request.agent !== undefined || request.tools !== undefined)
+                return { refusal: 'A continued subagent keeps its profile and tools; omit agent and tools.' };
+            request = { agent: record.profile };
+        }
         if (typeof request.agent !== 'string' || !request.agent.trim())
-            return 'Plan-mode delegation requires a named, eligible read-only research profile.';
-        const profile = resolveProfile(this.env.root, parent.input.cwd, request.agent.trim(), parent.input.variant && 'dir' in parent.input.variant ? parent.input.variant.dir : null);
-        if (!profile)
-            return `There is no agent profile named ${request.agent.trim()}.`;
-        if (!planResearchProfile(profile))
-            return 'This profile is not eligible for plan-mode research; use an explicit read-only research profile.';
-        if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some(name => typeof name !== 'string' || !PLAN_RESEARCH_TOOLS.has(name) || !profile.tools.includes(name) || !parent.capabilities.tools.includes(name)))) {
-            return 'Plan-mode subagent tools must be plan-safe and included in the selected profile and parent capabilities.';
+            return { refusal: 'Plan-mode delegation requires a named, eligible read-only research profile.' };
+        if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some(name => typeof name !== 'string'))) {
+            return { refusal: 'The optional tools field must be an array of tool names. Omit it to inherit the selected profile’s safe research intersection.' };
         }
-        const requested = Array.isArray(request.tools) ? request.tools : null;
-        const available = profile.tools.filter(name => parent.capabilities.tools.includes(name) && (!requested || requested.includes(name)));
-        if (!available.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name)))
-            return 'The selected profile has no available read-only research tools in this run.';
-        return null;
+        const profile = resolveProfile(this.env.root, parent.input.cwd, request.agent.trim(), parent.input.variant && 'dir' in parent.input.variant ? parent.input.variant.dir : null, parent.input.packageProfiles);
+        if (!profile)
+            return { refusal: `There is no agent profile named ${request.agent.trim()}.` };
+        const eligibility = planResearchEligibility(profile, {
+            frozenTools: parent.capabilities.tools,
+            contributions: parent.capabilities.contributions,
+            descriptors: this.options.descriptors?.() ?? []
+        }, request.tools);
+        return { refusal: eligibility.refusal, profile, eligibility };
+    }
+    /** The plan-mode per-call gate and spawn implementation share this eligibility check. */
+    planSpawnRefusal(parentRunId, args) {
+        return this.planSpawnCheck(parentRunId, args).refusal;
     }
     async spawn(request) {
         const parent = this.parent(request.parentRunId);
         const { input, accountId, capabilities } = parent;
         if (!capabilities.tools.includes(SPAWN_SUBAGENT))
             throw invalid('Subagents are not enabled for this run.');
+        if (request.continue !== undefined)
+            return this.continueChild(parent, request);
         const brief = typeof request.brief === 'string' ? request.brief.trim() : '';
         if (!brief)
             throw invalid('Give the subagent a brief.');
@@ -138,27 +153,33 @@ export class Subagents {
             throw invalid('wait must be a boolean.');
         if (request.tools !== undefined && (!Array.isArray(request.tools) || request.tools.some((name) => typeof name !== 'string')))
             throw invalid('Tools must be an array of tool names.');
-        const outside = request.tools?.filter((name) => !capabilities.tools.includes(name)) ?? [];
-        if (outside.length)
-            throw invalid(`A subagent cannot have tools you do not have: ${outside.join(', ')}.`);
+        let profile = null;
+        let planEligibility = null;
         if (input.plan) {
-            const refusal = this.planSpawnRefusal(request.parentRunId, request);
-            if (refusal)
-                throw invalid(refusal);
+            const check = this.planSpawnCheck(request.parentRunId, request);
+            if (check.refusal || !check.profile || !check.eligibility)
+                throw invalid(check.refusal ?? 'The selected profile has no eligible research tools in this run.');
+            profile = check.profile;
+            planEligibility = check.eligibility;
+        }
+        else {
+            const outside = request.tools?.filter((name) => !capabilities.tools.includes(name)) ?? [];
+            if (outside.length)
+                throw invalid(`A subagent cannot have tools you do not have: ${outside.join(', ')}.`);
+            if (request.agent !== undefined) {
+                if (typeof request.agent !== 'string' || !request.agent.trim())
+                    throw invalid('agent must be the name of an agent profile.');
+                profile = resolveProfile(this.env.root, input.cwd, request.agent.trim(), input.variant && 'dir' in input.variant ? input.variant.dir : null, input.packageProfiles);
+                if (!profile)
+                    throw invalid(`There is no agent profile named ${request.agent.trim()}.`);
+            }
         }
         await until(parent.ready, parent.stopped.signal);
         let variant = input.variant ?? null;
         let launch = input.launch;
         let model = input.model;
         let effort = input.effort;
-        let profile = null;
-        if (request.agent !== undefined) {
-            if (typeof request.agent !== 'string' || !request.agent.trim())
-                throw invalid('agent must be the name of an agent profile.');
-            const dir = variant && 'dir' in variant ? variant.dir : null;
-            profile = resolveProfile(this.env.root, input.cwd, request.agent.trim(), dir);
-            if (!profile)
-                throw invalid(`There is no agent profile named ${request.agent.trim()}.`);
+        if (profile) {
             // A variant's own subagent works from its definition alone; a profile keeps the parent's
             // variant unless it names another one, or none.
             if (profile.source === 'variant' || profile.variant === 'none')
@@ -171,20 +192,13 @@ export class Subagents {
                 effort = profile.effort;
             launch = { ...(input.launch ?? {}), sections: [...(input.launch?.sections ?? []).filter((section) => section.id !== 'subagent'), { id: 'subagent', title: `Your role: ${profile.name}`, body: profile.instructions || profile.description, budget: 16_000, order: 22 }] };
         }
-        if (input.plan) {
-            const refusal = this.planSpawnRefusal(request.parentRunId, request);
-            if (refusal)
-                throw invalid(refusal);
-        }
-        const narrowed = narrowForProfile(capabilities, profile, request.tools, this.options.descriptors?.() ?? []);
-        const childCapabilities = input.plan
-            ? { ...narrowed.capabilities, tools: narrowed.capabilities.tools.filter(name => PLAN_RESEARCH_TOOLS.has(name)), connectors: [] }
-            : narrowed.capabilities;
+        const narrowed = input.plan
+            ? { capabilities: planEligibility.capabilities, unavailable: planEligibility.unavailableTools }
+            : narrowForProfile(capabilities, profile, request.tools, this.options.descriptors?.() ?? []);
+        const childCapabilities = narrowed.capabilities;
         const tools = childCapabilities.tools;
         const runId = randomUUID();
         const sessionId = randomUUID();
-        this.rememberRuntimeSettings(runId, { model: model ?? null, effort: effort ?? null });
-        recordSubagent(this.env.root, request.parentRunId, runId);
         const child = {
             ...input,
             run: { ...input.run, ...(input.plan ? { worktreeId: null } : {}), id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), title, attachmentCount: 0, resumedFromRunId: null, handoffId: null, profile: profile?.name ?? null },
@@ -196,10 +210,18 @@ export class Subagents {
             variant, launch, model, effort,
             ...(input.plan ? { connections: false, subagents: null } : {})
         };
+        const result = await this.launchChild(parent, request, child);
+        return { ...result, ...(profile ? { agent: profile.name } : {}), ...(narrowed.unavailable.length ? { unavailableTools: narrowed.unavailable } : {}) };
+    }
+    /** Records ownership, starts the child, and writes a failed record when it never opened. */
+    async launchChild(parent, request, child) {
+        const runId = child.run.id;
+        this.rememberRuntimeSettings(runId, { model: child.model ?? null, effort: child.effort ?? null });
+        recordSubagent(this.env.root, request.parentRunId, runId);
         const started = this.launch(child).catch((error) => {
             if (!findRun(this.env.root, runId)) {
                 const source = loadRun(this.env.root, request.parentRunId);
-                saveRun(this.env.root, { ...source, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: null, handoffId: null, exitCode: null, goal: takeChars(brief, 4000), title, attachmentCount: 0, status: 'failed', startedAt: now(), endedAt: now(), terminalReason: error instanceof HarnessError ? error.message : 'Subagent startup failed before its session opened.', profile: profile?.name ?? null });
+                saveRun(this.env.root, { ...source, id: runId, sessionId: child.run.sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, nativeSessionId: null, resumedFromRunId: child.run.resumedFromRunId ?? null, handoffId: null, exitCode: null, goal: child.run.goal ?? null, title: child.run.title ?? null, attachmentCount: 0, status: 'failed', startedAt: now(), endedAt: now(), terminalReason: error instanceof HarnessError ? error.message : 'Subagent startup failed before its session opened.', profile: child.run.profile ?? null, model: child.model ?? null, effort: child.effort ?? null });
             }
             return { runId, nativeSessionId: null };
         });
@@ -208,10 +230,113 @@ export class Subagents {
         const result = await until(started, parent.stopped.signal);
         if (request.wait)
             await this.wait({ parentRunId: request.parentRunId, runIds: [runId] });
-        return { ...result, ...(profile ? { agent: profile.name } : {}), ...(narrowed.unavailable.length ? { unavailableTools: narrowed.unavailable } : {}) };
+        return result;
+    }
+    /** The children this parent may read or continue: its own, and those recovered from its history. */
+    owned(parentRunId, parent) {
+        return new Set([...recordedSubagents(this.env.root, parentRunId), ...(parent?.recovered ?? [])]);
+    }
+    /** The newest run in a continued child's chain, among the runs this parent owns. */
+    latestLink(start, owned) {
+        const records = [...owned].flatMap((id) => findRun(this.env.root, id) ?? []);
+        let latest = start;
+        const seen = new Set([start.id]);
+        for (;;) {
+            const next = records.filter((record) => record.resumedFromRunId === latest.id && !seen.has(record.id)).sort((left, right) => left.startedAt.localeCompare(right.startedAt)).at(-1);
+            if (!next)
+                return latest;
+            seen.add(next.id);
+            latest = next;
+        }
+    }
+    /** The first run of a chain: its folder holds the child's history for every later link. */
+    firstLink(record) {
+        let first = record;
+        const seen = new Set([record.id]);
+        while (first.resumedFromRunId && !seen.has(first.resumedFromRunId)) {
+            const previous = findRun(this.env.root, first.resumedFromRunId);
+            if (!previous || previous.relation !== SUBAGENT_RELATION)
+                break;
+            seen.add(previous.id);
+            first = previous;
+        }
+        return first;
+    }
+    /**
+     * Continues a stopped child as a new child run with `continueFrom`: the same history, profile,
+     * account, variant version and capability set, which must still lie within the parent's.
+     */
+    async continueChild(parent, request) {
+        const { root } = this.env;
+        const { input, accountId, capabilities } = parent;
+        const requested = typeof request.continue === 'string' ? request.continue.trim() : '';
+        if (!requested)
+            throw invalid('continue must be the run ID of a subagent that stopped.');
+        if (request.agent !== undefined || request.tools !== undefined)
+            throw invalid('A continued subagent keeps its profile and tools; omit agent and tools.');
+        if (request.brief !== undefined && typeof request.brief !== 'string')
+            throw invalid('brief must be text.');
+        if (request.wait !== undefined && typeof request.wait !== 'boolean')
+            throw invalid('wait must be a boolean.');
+        await until(parent.ready, parent.stopped.signal);
+        const owned = this.owned(request.parentRunId, parent);
+        const named = owned.has(requested) ? findRun(root, requested) : null;
+        if (!named || named.relation !== SUBAGENT_RELATION)
+            throw invalid('Continue only a subagent that this conversation started.');
+        const latest = this.latestLink(named, owned);
+        if (isActiveStatus(latest.status))
+            throw invalid(`Subagent ${latest.id} is still running; wait for it with wait_subagents.`);
+        if (latest.status === 'completed')
+            throw invalid(`Subagent ${latest.id} already finished and its result was delivered. Start a new subagent for more work.`);
+        const sessionDir = join(input.sessionDir, 'subagents', this.firstLink(latest).id);
+        const continuation = continuationOf(root, latest.id, sessionDir);
+        if (!continuation.resumable || !continuation.resume)
+            throw invalid(`Subagent ${latest.id} cannot be continued: ${continuation.reason === 'no_history' ? 'it stopped before its conversation started' : 'its saved conversation is missing'}. Start a new subagent instead.`);
+        if (continuation.accountId !== accountId)
+            throw invalid(`Subagent ${latest.id} ran on another account; start a new subagent instead.`);
+        const pinned = continuation.capabilities;
+        if (!pinned)
+            throw invalid(`Subagent ${latest.id} has no recorded capabilities; start a new subagent instead.`);
+        const missing = [
+            ...pinned.tools.filter((name) => !capabilities.tools.includes(name)),
+            ...pinned.connectors.filter((id) => !capabilities.connectors.includes(id)),
+            ...pinned.contributions.filter((id) => !capabilities.contributions.includes(id))
+        ];
+        if (missing.length)
+            throw invalid(`Subagent ${latest.id} needs capabilities you do not have in this run: ${missing.join(', ')}. Start a new subagent instead.`);
+        let profile = null;
+        if (latest.profile)
+            profile = resolveProfile(root, input.cwd, latest.profile, input.variant && 'dir' in input.variant ? input.variant.dir : null, input.packageProfiles);
+        if (input.plan) {
+            // A plan run continues only a research child whose pinned tools still qualify.
+            const check = latest.profile ? this.planSpawnCheck(request.parentRunId, { agent: latest.profile }) : { refusal: 'Plan mode can continue only a stopped research subagent that has a named profile.' };
+            if (check.refusal || !check.eligibility)
+                throw invalid(check.refusal ?? 'This subagent is not eligible for plan-mode research.');
+            const outside = pinned.tools.filter((name) => !check.eligibility.capabilities.tools.includes(name));
+            if (outside.length)
+                throw invalid(`Subagent ${latest.id} has tools plan mode does not allow: ${outside.join(', ')}.`);
+        }
+        const launch = profile
+            ? { ...(input.launch ?? {}), sections: [...(input.launch?.sections ?? []).filter((section) => section.id !== 'subagent'), { id: 'subagent', title: `Your role: ${profile.name}`, body: profile.instructions || profile.description, budget: 16_000, order: 22 }] }
+            : input.launch;
+        const runId = randomUUID();
+        const child = {
+            ...input,
+            run: { ...input.run, ...(input.plan ? { worktreeId: null } : {}), id: runId, sessionId: latest.sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: latest.goal, title: latest.title ?? briefTitle(latest.goal), attachmentCount: 0, resumedFromRunId: latest.id, handoffId: null, profile: latest.profile ?? null },
+            accountId, poolId: null, sessionDir, resume: null, continueFrom: latest.id,
+            text: typeof request.brief === 'string' ? request.brief.trim() : '', images: undefined, requiresImageInput: false, preamble: null,
+            caller: { ...input.caller, runId: undefined, sessionId: latest.sessionId },
+            tools: { allow: pinned.tools, gated: (input.tools.gated ?? []).filter((name) => pinned.tools.includes(name)) },
+            capabilities: pinned, depth: (input.depth ?? 0) + 1,
+            variant: null, launch,
+            model: latest.model ?? input.model, effort: latest.effort ?? input.effort,
+            ...(input.plan ? { connections: false, subagents: null } : {})
+        };
+        const result = await this.launchChild(parent, request, child);
+        return { ...result, continued: latest.id, ...(latest.profile ? { agent: latest.profile } : {}) };
     }
     selected(selection, parent) {
-        const owned = new Set([...recordedSubagents(this.env.root, selection.parentRunId), ...(parent?.recovered ?? [])]);
+        const owned = this.owned(selection.parentRunId, parent);
         if (selection.runIds !== undefined && (!Array.isArray(selection.runIds) || selection.runIds.some((id) => typeof id !== 'string')))
             throw invalid('runIds must be an array of child run IDs.');
         const ids = [...new Set(selection.runIds ?? [...owned])];
@@ -251,7 +376,9 @@ export class Subagents {
             if (owner === parentRunId)
                 continue;
             const old = findRun(this.env.root, owner);
-            if (!old || old.sessionId !== current.sessionId || old.accountId !== current.accountId || old.agentId !== current.agentId || old.projectId !== current.projectId || old.workingDirectory !== current.workingDirectory || !old.nativeSessionId || old.nativeSessionId !== current.nativeSessionId)
+            // The owner marker on this native branch is the lineage; a host may give each launch of the
+            // same conversation a new session id (INV-RUN-4).
+            if (!old || old.accountId !== current.accountId || old.agentId !== current.agentId || old.projectId !== current.projectId || old.workingDirectory !== current.workingDirectory || !old.nativeSessionId || old.nativeSessionId !== current.nativeSessionId)
                 continue;
             for (const id of recordedSubagents(this.env.root, owner)) {
                 let child = findRun(this.env.root, id);
@@ -277,12 +404,19 @@ export class Subagents {
             }
         }
         const delivered = new Set(history.receipts.flatMap((receipt) => receipt.delivered ?? []));
-        const pending = this.results({ parentRunId }).filter((result) => !isActiveStatus(result.status) && !delivered.has(result.runId));
+        const all = this.results({ parentRunId });
+        const records = new Map(all.map((result) => [result.runId, findRun(this.env.root, result.runId)]));
+        // A stopped child that was continued is reported through its continuation instead.
+        const superseded = new Set([...records.values()].flatMap((record) => record?.resumedFromRunId ? [record.resumedFromRunId] : []));
+        const pending = all.filter((result) => !isActiveStatus(result.status) && !delivered.has(result.runId) && !superseded.has(result.runId));
         const chunks = [];
         const ids = [];
         let size = 0;
         for (const result of pending) {
-            const text = `Subagent run ${result.runId} · ${result.status}\n${result.text || result.terminalReason || 'No written reply.'}`;
+            const record = records.get(result.runId);
+            const label = [record?.profile, record?.title].filter(Boolean).join(' · ');
+            const stopped = (result.status === 'interrupted' || result.status === 'failed') && continuationOf(this.env.root, result.runId).resumable;
+            const text = `Subagent run ${result.runId} · ${result.status}${label ? ` (${label})` : ''}\n${result.text || result.terminalReason || 'No written reply.'}${stopped ? `\nIt stopped before finishing. ${continueHint(result.runId)}` : ''}`;
             if (size + text.length > 32_000 && ids.length)
                 break;
             chunks.push(text);
@@ -301,12 +435,18 @@ export class Subagents {
     }
     extension(runId) {
         return { name: 'native-subagents', factory: (pi) => {
-                pi.on('before_agent_start', (_event, ctx) => {
+                pi.on('before_agent_start', async (_event, ctx) => {
                     if (!this.parents.has(runId))
                         return;
-                    this.restore(runId, subagentHistory(ctx.sessionManager.getBranch()));
+                    const history = subagentHistory(ctx.sessionManager.getBranch());
+                    this.restore(runId, history);
                     pi.appendEntry(SUBAGENT_OWNER, { runId });
                     this.parent(runId).started();
+                    // Children an earlier reply left stopped are reported before the model answers, so it can
+                    // continue them instead of starting over.
+                    const notice = await this.delivery(runId, history, false);
+                    if (notice)
+                        return { message: { customType: SUBAGENT_RESULTS, content: notice.text, display: false, details: { [SUBAGENT_RECEIPT]: notice.receipt } } };
                 });
                 const deliver = async (event, ctx, settle) => {
                     if (!this.parents.has(runId) || (settle && event.outcome !== 'completed') || ctx.signal?.aborted)

package/dist/sdk/sessions/subagents.d.ts

@@ -11,14 +11,23 @@ export interface SubagentOptions {
 export declare function subagentDepth(options: SubagentOptions | undefined): number;
 export interface SubagentInput {
     parentRunId: string;
-    brief: string;
+    /** The task for a new child; with `continue`, an optional extra instruction. */
+    brief?: string;
     /** The short name the roster shows for the child (PROP-0030); the spawn tool requires it. */
     title?: string;
     tools?: string[];
     wait?: boolean;
     /** An agent profile by name (PROP-0029), or one of the parent variant's subagents (c5). */
     agent?: string;
+    /**
+     * A stopped child to continue instead of starting a fresh one: its run id. The new child reopens
+     * that child's own history and keeps its profile, tools, account and variant; `brief` is then an
+     * optional extra instruction.
+     */
+    continue?: string;
 }
+/** The words that tell a parent a stopped child can be continued rather than started again. */
+export declare function continueHint(runId: string): string;
 /** A subagent title is one short imperative, at most this many words (PROP-0030). */
 export declare const MAX_SUBAGENT_TITLE_WORDS = 6;
 /** The title a subagent title input means after cleaning, or undefined when it is not one. */

package/dist/sdk/sessions/subagents.js

@@ -10,6 +10,10 @@ export function subagentDepth(options) {
     const value = Math.trunc(options?.maxDepth ?? DEFAULT_SUBAGENT_DEPTH);
     return Math.min(MAX_SUBAGENT_DEPTH, Math.max(1, Number.isFinite(value) ? value : DEFAULT_SUBAGENT_DEPTH));
 }
+/** The words that tell a parent a stopped child can be continued rather than started again. */
+export function continueHint(runId) {
+    return `Its conversation is saved: continue it with spawn_subagent { "continue": "${runId}" } if the work is still needed, instead of starting it again from scratch.`;
+}
 /** A subagent title is one short imperative, at most this many words (PROP-0030). */
 export const MAX_SUBAGENT_TITLE_WORDS = 6;
 const BRIEF_TITLE_LENGTH = 60;

package/dist/sdk/sessions/workSlice.d.ts

@@ -7,7 +7,7 @@ export interface WorkSliceInput {
     maxToolCalls?: number;
     /** Minutes in one reply; 0 disables this limit. */
     maxMinutes?: number;
-    /** New tokens in one reply (input + cache read + output); 0 disables this limit. */
+    /** New tokens in one reply (new input + cache writes + output); 0 disables this limit, and no limit is the default. */
     maxNewTokens?: number;
     /** Slices one task may use before it is handed back to the person; 0 disables the cap. */
     maxSlices?: number;
@@ -54,7 +54,7 @@ export declare function createSliceState(_policy: SlicePolicy, slice?: number, n
 export declare function resetSliceState(state: SliceState, now?: number): void;
 /** The first limit this reply has passed, named as a person would say it. */
 export declare function sliceLimitReached(policy: SlicePolicy, state: SliceState, now?: number): string | null;
-/** Commands that read as a check, for "no progress" and "still failing" rules. */
+/** Commands that read as a check for the repeated-failure rule. */
 export declare function looksLikeCheck(command: string): boolean;
 interface ToolCall {
     toolName: string;
@@ -85,12 +85,15 @@ interface GuardApi {
 export interface WorkSliceGuardOptions {
     policy: SlicePolicy;
     state: SliceState;
-    /** Called once the guard has decided the reply must stop; the runner ends it. */
+    /** Whether checkpoint_write is active; a function supports the terminal's live plan-mode switch. */
+    checkpointAvailable?: boolean | (() => boolean);
+    /** Called when a triggering call terminates the reply; the runner ends it. */
     onEnd?: (end: SliceEnd, limit: string) => void;
 }
 /**
- * Bounds one reply and names repeated work. The first refusal asks for a checkpoint; a tool call
- * after that refusal ends the reply. A repeated call or failing command is named once, then ends it.
+ * Bounds one reply and names repeated work. Refusals request a checkpoint when available; without
+ * one, they ask for a partial report and prohibit further tools. A repeated call or failing command
+ * is named once, then ends the reply.
  */
 export declare function workSliceGuard(options: WorkSliceGuardOptions): (pi: GuardApi) => void;
 /**