@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/sessions/sessions.js

@@ -1,12 +1,15 @@
 // Starting a session turn: the account, the run record, the compiled prompt, the tools and
 // their gate, then Pi. Everything before Pi answers is synchronous with the caller; the reply
 // itself streams as run events.
+import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { log } from "../core/bus.js";
 import { HarnessError, invalid } from "../core/errors.js";
+import { formatBashCommandForApproval } from "../core/workspaceBashTool.js";
 import { capabilitySet as parseCapabilitySet, freezeRun } from "../capabilities/runSnapshot.js";
 import { now, writeJson } from "../core/fs.js";
+import { resolveWorkspaceRoot, verifyWorkspaceRoot } from "../core/workspace.js";
 import { takeChars } from "../core/text.js";
 import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
 import { sessionLaunch } from "../prompt/compile.js";
@@ -16,17 +19,43 @@ 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 { CHECKPOINT_WRITE, checkpointOf } from "../tools/checkpoint.js";
 import { SESSION_NAME, 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 { 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";
-import { loadRun, runDir, saveRun, updateRun } from "./runStore.js";
-import { planRefusal, planSection } from "./planMode.js";
+import { loadRun, readEvents, runDir, saveRun, updateRun } from "./runStore.js";
+import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "./workspaceBoundary.js";
+import { PLAN_INSTRUCTIONS, PLAN_RESEARCH_SUBAGENT_INSTRUCTIONS, planRefusal, planSection } from "./planMode.js";
 import { CONTINUATION_SECTION_ID, continuationOf, continuationSection } from "./continuation.js";
 import { deliveredSnapshot } from "../prompt/compile.js";
 import { profileSection } from "../agents/profiles.js";
+/** A session command acts on a saved conversation and is never combined with a request of its own. */
+function checkCommand(command, historyFile, input) {
+    if (!historyFile)
+        throw invalid('There is no saved conversation for this command yet.');
+    if (input.plan || input.continueFrom || input.automatic || input.initialBashCommand != null || input.images?.length) {
+        throw invalid('A session command runs on its own, without plan mode, a continuation, Bash or images.');
+    }
+    switch (command?.name) {
+        case 'compact': return;
+        case 'navigate':
+            if (typeof command.entryId !== 'string' || !command.entryId)
+                throw invalid('navigate needs the entry to go to.');
+            return;
+        case 'export':
+            if (typeof command.path !== 'string' || !isAbsolute(command.path) || !command.path.endsWith('.html'))
+                throw invalid('export needs an absolute .html path.');
+            return;
+        default: throw invalid('Unknown session command.');
+    }
+}
 const CONTINUE_TEXT = 'Continue from where you stopped.';
 /** Fills a continuing run's input from the run it continues, refusing anything that would differ. */
 function continueInput(root, input) {
@@ -95,7 +124,7 @@ export class Sessions {
     diagnosticGate(run, caller) {
         return this.gate(run, caller, new Set(), true);
     }
-    gate(run, caller, gated, diagnostic = false) {
+    gate(run, caller, gated, diagnostic = false, automatic = false) {
         const { policy } = this.options;
         return {
             ask: (names) => {
@@ -103,9 +132,19 @@ export class Sessions {
                     gated.add(name);
             },
             check: async (tool, args) => {
-                const call = { run: loadRun(this.env.root, run.runId), caller, tool, args };
-                const scope = (await policy.scope?.(call)) ?? { allowed: true };
-                if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
+                let record;
+                let inspection;
+                try {
+                    record = loadRun(this.env.root, run.runId);
+                    inspection = inspectRunWorkspaceWrite(record, tool, args);
+                }
+                catch (error) {
+                    return error instanceof Error ? error.message : 'The active project workspace could not be verified.';
+                }
+                const call = { run: record, caller, tool, args: inspection.input };
+                const hostScope = (await policy.scope?.(call)) ?? { allowed: true };
+                const scope = combineWorkspaceScope(hostScope, inspection);
+                if (!scope.allowed && (scope.automatic || (automatic && inspection.outside) || !scope.requiresApproval))
                     return scope.reason ?? 'Outside the approved work scope.';
                 try {
                     await policy.authorize?.(call);
@@ -122,11 +161,11 @@ export class Sessions {
                     return scope.reason ? `Refused in a refinement run: ${scope.reason}` : 'Refused in a refinement run: this call needs a person to approve it.';
                 if (call.run.trigger === 'reflection')
                     return scope.reason ? `Refused in a reflection run: ${scope.reason}` : 'Refused in a reflection run: this call needs a person to approve it.';
-                // A call outside the scope is approved one at a time; a gated tool may be remembered, unless only a person may decide it.
+                const boundaryAction = inspection.outside ? `${inspection.reason} ${summarize(call.args, tool)}` : summarize(call.args);
                 const decision = await run.requestApproval({
                     target: tool,
-                    action: summarize(args),
-                    operation: { tool, args: (args && typeof args === 'object' ? args : {}) },
+                    action: boundaryAction,
+                    operation: { tool, args: (call.args && typeof call.args === 'object' ? call.args : {}) },
                     rememberable: scope.allowed && !scope.humanOnly,
                     standing: scope.humanOnly ? (scope.allowGlobalApproval ? 'switch' : 'none') : undefined
                 });
@@ -139,6 +178,69 @@ export class Sessions {
                     return error instanceof Error ? error.message : 'Tool was disabled while waiting.';
                 }
                 return null;
+            },
+            workspaceBoundaryBypass: async (tool, args) => {
+                if (diagnostic || automatic || tool.toLowerCase() !== 'bash')
+                    return false;
+                const record = loadRun(this.env.root, run.runId);
+                if (record.trigger != null && record.trigger !== 'user')
+                    return false;
+                if (!await this.options.fullPermission?.(record))
+                    return false;
+                const call = { run: record, caller, tool, args };
+                const scope = (await policy.scope?.(call)) ?? { allowed: true };
+                if (scope.automatic || (!scope.allowed && !scope.requiresApproval) || (scope.humanOnly && !scope.allowGlobalApproval))
+                    return false;
+                try {
+                    await policy.authorize?.(call);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            requestWorkspaceWriteScope: async (tool, args, reason) => {
+                if (diagnostic || automatic || tool.toLowerCase() !== 'bash')
+                    return false;
+                const record = loadRun(this.env.root, run.runId);
+                if (!isActiveStatus(record.status) || (record.trigger != null && record.trigger !== 'user'))
+                    return false;
+                const operationArgs = (args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+                if (operationArgs.workspaceWriteScope !== 'outside' || typeof operationArgs.command !== 'string' || !operationArgs.command)
+                    return false;
+                const call = { run: record, caller, tool, args: operationArgs };
+                const scope = (await policy.scope?.(call)) ?? { allowed: true };
+                if (scope.automatic || (!scope.allowed && !scope.requiresApproval))
+                    return false;
+                try {
+                    await policy.authorize?.(call);
+                }
+                catch {
+                    return false;
+                }
+                const decision = await run.requestApproval({
+                    target: 'workspace-write',
+                    action: `${reason}\n\nCommand to be run once after approval:\n${formatBashCommandForApproval(operationArgs.command)}`,
+                    operation: { tool, args: operationArgs },
+                    rememberable: false,
+                    standing: 'none'
+                });
+                if (decision !== 'approved')
+                    return false;
+                const currentRecord = loadRun(this.env.root, run.runId);
+                if (!isActiveStatus(currentRecord.status) || (currentRecord.trigger != null && currentRecord.trigger !== 'user'))
+                    return false;
+                const currentCall = { run: currentRecord, caller, tool, args: operationArgs };
+                const currentScope = (await policy.scope?.(currentCall)) ?? { allowed: true };
+                if (currentScope.automatic || (!currentScope.allowed && !currentScope.requiresApproval))
+                    return false;
+                try {
+                    await policy.authorize?.(currentCall);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
             }
         };
     }
@@ -195,6 +297,50 @@ export class Sessions {
         });
         return { release };
     }
+    /**
+     * Starts the next slice when a reply stopped at its work-slice boundary (PROP-0041). Never for
+     * unattended, plan, subagent, command or worktree runs, after a blocked or fruitless slice, or
+     * past the policy's slice cap. The earlier record is never reopened; this is a new run with the
+     * same pins, exactly as an application-asked continuation.
+     */
+    async continueSlice(input) {
+        const { root, runId, source, policy } = input;
+        if (!policy.enabled || !policy.continue || policy.maxSlices <= 0)
+            return;
+        if (source.automatic || source.plan || source.command || source.run.relation || source.run.worktreeId)
+            return;
+        if ((source.depth ?? 0) > 0)
+            return;
+        const record = loadRun(root, runId);
+        if (record.terminalReason !== 'slice_complete')
+            return;
+        const events = readEvents(root, runId);
+        const checkpoint = checkpointOf(events);
+        if (checkpoint?.blocked)
+            return;
+        const progressed = events.some((event) => event.type === 'file.changed')
+            || events.some((event) => {
+                const payload = event.payload;
+                return event.type === 'tool.completed' && payload.name === 'bash' && payload.ok === true;
+            })
+            || (checkpoint?.done.length ?? 0) > 0;
+        if (!progressed)
+            return;
+        if (sliceOf(root, runId) >= policy.maxSlices)
+            return;
+        const next = {
+            ...source,
+            run: { ...source.run, id: randomUUID(), resumedFromRunId: null, parentRunId: null, relation: null },
+            continueFrom: runId,
+            text: CONTINUE_TEXT
+        };
+        next.initialBashCommand = undefined;
+        next.initialBashContext = undefined;
+        next.images = undefined;
+        next.resume = null;
+        next.command = undefined;
+        await this.run(next).catch((error) => log(`the next work slice did not start: ${error instanceof Error ? error.message : String(error)}`));
+    }
     async start(input) {
         const { root } = this.env;
         if ((input.initialBashCommand !== undefined && input.initialBashCommand !== null) || (input.initialBashContext !== undefined && input.initialBashContext !== null)) {
@@ -222,8 +368,23 @@ export class Sessions {
                 throw invalid('An initial Bash command is available only for a new interactive user turn.');
             }
         }
+        let slicePolicy;
+        try {
+            slicePolicy = parseWorkSlice(input.workSlice);
+        }
+        catch (error) {
+            if (error instanceof WorkSliceError)
+                throw invalid(error.message);
+            throw error;
+        }
         const continuation = input.continueFrom ? continueInput(root, input) : null;
+        const previousRun = continuation ? loadRun(root, continuation.runId) : null;
+        const workspaceRoot = previousRun?.workspaceRoot
+            ? verifyWorkspaceRoot(previousRun.workspaceRoot)
+            : resolveWorkspaceRoot(previousRun?.workingDirectory ?? input.cwd);
         const historyFile = selectHistory({ sessionDir: input.sessionDir, resume: input.resume });
+        if (input.command)
+            checkCommand(input.command, historyFile, input);
         const account = this.options.accounts.resolve(input.accountId, input.poolId);
         const context = this.options.accounts.context(account);
         const runId = input.run.id;
@@ -239,7 +400,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, SESSION_NAME, ...DEFAULT_TOOL_NAMES] : []),
+                ...(harnessToolsEnabled ? [...(canAskUser ? [ASK_USER] : []), CHECKLIST_WRITE, CHECKPOINT_WRITE, SESSION_NAME, GET_CAPABILITIES, ...DEFAULT_TOOL_NAMES] : []),
                 ...(broker?.toolNames ?? []),
                 ...(canSpawn ? [SPAWN_SUBAGENT, WAIT_SUBAGENTS] : [])
             ])];
@@ -276,6 +437,7 @@ export class Sessions {
             sessionId: input.run.sessionId,
             nativeSessionId: null,
             workingDirectory: input.cwd,
+            workspaceRoot,
             worktreeId: input.run.worktreeId ?? null,
             goal: input.run.goal ?? takeChars(input.text, 4000),
             attachmentCount: input.run.attachmentCount ?? 0,
@@ -310,11 +472,11 @@ export class Sessions {
             if (!existsSync(input.sessionDir))
                 mkdirSync(input.sessionDir, { recursive: true });
             const launch = input.launch ?? {};
-            const plan = planSection(input.plan === true, historyFile);
+            const plan = planSection(input.plan === true, historyFile, input.run.relation === 'subagent');
             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) : null;
+            const profiles = capabilities.tools.includes(SPAWN_SUBAGENT) ? profileSection(root, input.cwd, variant?.dir ?? null, input.plan === true) : null;
             if (profiles && variant)
                 variant = { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) };
             const own = [plan, resumed, profiles].filter((section) => section !== null);
@@ -331,6 +493,9 @@ 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);
+        const sliceState = createSliceState(slicePolicy, sliceOf(root, runId));
         const run = this.options.runs.start(input.run.sessionId, runId);
         if (run.finished)
             return { runId, nativeSessionId: null };
@@ -353,6 +518,11 @@ export class Sessions {
         });
         try {
             const tools = [
+                ...(harnessToolsEnabled && allow.includes(GET_CAPABILITIES) ? [getCapabilitiesTool(() => ({
+                        capabilities,
+                        active: pi?.getActiveToolNames?.() ?? [],
+                        registered: pi?.getAllTools?.() ?? []
+                    }))] : []),
                 ...BUILTIN_PLUGIN_REGISTRY.tools({
                     env: this.options.env,
                     caller,
@@ -379,12 +549,15 @@ export class Sessions {
                 }
             }
             const readOnly = new Set(tools.filter((tool) => tool.readOnly).map((tool) => tool.name));
+            const checkpointPlanInstructions = input.plan
+                ? () => input.run.relation === 'subagent' ? PLAN_RESEARCH_SUBAGENT_INSTRUCTIONS : PLAN_INSTRUCTIONS
+                : undefined;
             const planModeSafety = new Map();
             for (const tool of tools)
                 if (tool.planModeSafe)
                     planModeSafety.set(tool.name, tool.planModeSafe);
             const gate = (() => {
-                const baseGate = this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name))));
+                const baseGate = this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name))), false, input.automatic === true);
                 return {
                     ...baseGate,
                     check: (name, args) => {
@@ -401,7 +574,9 @@ export class Sessions {
                 ...(input.initialBashContext !== undefined && input.initialBashContext !== null ? { initialBashContext: input.initialBashContext } : {}),
                 gate,
                 restrictTools: input.run.relation === 'subagent',
+                ...(input.plan ? { plan: true } : {}),
                 cwd: input.cwd,
+                workspaceRoot,
                 sessionDir: input.sessionDir,
                 historyFile,
                 model: input.model ?? null,
@@ -414,10 +589,20 @@ export class Sessions {
                 account: context,
                 resources: { ids: [], skillPaths: variant?.skillPaths ?? [], promptPaths: [] },
                 variantExtensions: variant?.extensionPaths ?? [],
-                inline: [...firstPartyFor(root, capabilities.contributions), runLineageJoin(root, runId), this.options.subagents.extension(runId), { name: 'image-pruning', factory: imagePruning() }],
+                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 }) }] : [])
+                ],
                 ...(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) } } : {}),
                 system,
-                update
+                ...(sliceEnabled ? { slice: { state: sliceState, maxToolCalls: slicePolicy.maxToolCalls } } : {}),
+                // A command sends no request of its own, so the context update waits for the next turn.
+                update: input.command ? null : update,
+                ...(input.command ? { command: input.command } : {})
             };
             pi = await this.factory({
                 params,
@@ -445,7 +630,7 @@ export class Sessions {
             if (pi.model?.id && pi.model.provider)
                 this.options.subagents.resolvedModel(runId, `${pi.model.provider}/${pi.model.id}`, pi.thinkingLevel);
             params.settle = () => this.options.subagents.verify(runId, opened.sessionManager ? subagentHistory(opened.sessionManager.getBranch()) : undefined);
-            void runTurn(run, pi, params);
+            void runTurn(run, pi, params).then(() => (sliceEnabled && !input.command ? this.continueSlice({ root, runId, source: input, policy: slicePolicy }) : undefined));
             return { runId, nativeSessionId: pi.sessionId };
         }
         catch (error) {

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

@@ -15,6 +15,10 @@ export type SpawnedSubagent = Started & {
     agent?: string;
     unavailableTools?: string[];
 };
+export interface SubagentRuntimeSettings {
+    model: string | null;
+    effort: Effort | null;
+}
 export interface SubagentServiceOptions {
     /** The plugin descriptors, so a profile's plugin list can drop the tools those plugins own. */
     descriptors?: () => readonly PluginDescriptor[];
@@ -30,11 +34,16 @@ export declare class Subagents {
     private readonly launch;
     private readonly options;
     private readonly parents;
+    private readonly runtimeSettingsByRun;
     constructor(env: HarnessEnv, runs: RunRegistry, launch: (input: SessionRunInput) => Promise<Started>, options?: SubagentServiceOptions);
     /** Internal adapter contract: context comes from a live run, never from model arguments. */
     register(input: SessionRunInput, accountId: string, capabilities: CapabilitySet, deferUntilPrompt?: boolean): void;
+    runtimeSettings(runId: string): SubagentRuntimeSettings | null;
+    private rememberRuntimeSettings;
     resolvedModel(runId: string, model: string, effort?: Effort): void;
     private parent;
+    /** 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>;
     private selected;
     results(selection: SubagentSelection): SubagentResult[];

package/dist/sdk/sessions/subagentService.js

@@ -6,6 +6,7 @@ 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 { resolveProfile } from "../agents/profiles.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";
@@ -27,6 +28,7 @@ export class Subagents {
     launch;
     options;
     parents = new Map();
+    runtimeSettingsByRun = new Map();
     constructor(env, runs, launch, options = {}) {
         this.env = env;
         this.runs = runs;
@@ -66,12 +68,26 @@ export class Subagents {
             started();
         this.parents.set(input.run.id, { ready, started, input: structuredClone({ ...input, text: '', images: undefined, requiresImageInput: false, preamble: null, resume: null }), accountId, capabilities: ceiling, stopped: new AbortController(), recovered: new Set(), launching: new Map() });
     }
+    runtimeSettings(runId) {
+        return this.runtimeSettingsByRun.get(runId) ?? null;
+    }
+    rememberRuntimeSettings(runId, settings) {
+        this.runtimeSettingsByRun.set(runId, settings);
+        if (this.runtimeSettingsByRun.size > 500) {
+            const oldest = this.runtimeSettingsByRun.keys().next().value;
+            if (oldest !== undefined)
+                this.runtimeSettingsByRun.delete(oldest);
+        }
+    }
     resolvedModel(runId, model, effort) {
         const parent = this.parents.get(runId);
         if (parent) {
             parent.input.model = model;
             parent.input.effort = effort ?? parent.input.effort;
         }
+        const settings = this.runtimeSettingsByRun.get(runId);
+        if (settings)
+            this.rememberRuntimeSettings(runId, { model, effort: effort ?? settings.effort });
     }
     parent(runId) {
         const parent = this.parents.get(runId);
@@ -79,6 +95,34 @@ 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) {
+        const parent = this.parents.get(parentRunId);
+        if (!parent || !this.runs.active(parentRunId))
+            return 'The parent run is not accepting subagents.';
+        if (!parent.input.plan)
+            return '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.';
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            return 'Plan-mode delegation requires a named, eligible read-only research profile.';
+        const request = args;
+        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.';
+        }
+        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;
+    }
     async spawn(request) {
         const parent = this.parent(request.parentRunId);
         const { input, accountId, capabilities } = parent;
@@ -97,6 +141,11 @@ export class Subagents {
         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 (input.plan) {
+            const refusal = this.planSpawnRefusal(request.parentRunId, request);
+            if (refusal)
+                throw invalid(refusal);
+        }
         await until(parent.ready, parent.stopped.signal);
         let variant = input.variant ?? null;
         let launch = input.launch;
@@ -122,20 +171,30 @@ 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 tools = narrowed.capabilities.tools;
+        const childCapabilities = input.plan
+            ? { ...narrowed.capabilities, tools: narrowed.capabilities.tools.filter(name => PLAN_RESEARCH_TOOLS.has(name)), connectors: [] }
+            : 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, id: runId, sessionId, parentRunId: request.parentRunId, relation: SUBAGENT_RELATION, goal: takeChars(brief, 4000), title, attachmentCount: 0, resumedFromRunId: null, handoffId: null, profile: profile?.name ?? null },
+            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 },
             accountId, poolId: null, sessionDir: join(input.sessionDir, 'subagents', runId), resume: null,
             text: brief, images: undefined, requiresImageInput: false, preamble: null,
             caller: { ...input.caller, runId: undefined, sessionId },
             tools: { allow: tools, gated: (input.tools.gated ?? []).filter((name) => tools.includes(name)) },
-            capabilities: narrowed.capabilities, depth: (input.depth ?? 0) + 1,
-            variant, launch, model, effort
+            capabilities: childCapabilities, depth: (input.depth ?? 0) + 1,
+            variant, launch, model, effort,
+            ...(input.plan ? { connections: false, subagents: null } : {})
         };
         const started = this.launch(child).catch((error) => {
             if (!findRun(this.env.root, runId)) {

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

@@ -0,0 +1,103 @@
+import type { Checkpoint } from "./contracts.js";
+export declare const WORK_SLICE_EXTENSION = "work-slice";
+export interface WorkSliceInput {
+    /** False turns the guard off for this run: no budget, no stall notes, no continuation. */
+    enabled?: boolean;
+    /** Tool calls in one reply; 0 disables this limit. */
+    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. */
+    maxNewTokens?: number;
+    /** Slices one task may use before it is handed back to the person; 0 disables the cap. */
+    maxSlices?: number;
+    /** Start the next slice from the checkpoint without asking. */
+    continue?: boolean;
+}
+export interface SlicePolicy {
+    enabled: boolean;
+    maxToolCalls: number;
+    maxMinutes: number;
+    maxNewTokens: number;
+    maxSlices: number;
+    continue: boolean;
+}
+/** The foundation defaults: enough for one meaningful step of work, short enough to report. */
+export declare const DEFAULT_SLICE_POLICY: SlicePolicy;
+export declare class WorkSliceError extends Error {
+}
+/**
+ * The policy a run asked for, or the defaults. `XINGULAR_WORK_SLICE=off` at launch turns the guard
+ * off for every run in this process; nothing is persisted, so restarting without it restores the
+ * defaults.
+ */
+export declare function parseWorkSlice(input: unknown): SlicePolicy;
+export type SliceEnd = 'budget' | 'stuck' | 'compaction-thrash';
+/** What a live reply tracks for its slice; the runner reads it after the reply. */
+export interface SliceState {
+    slice: number;
+    steps: number;
+    tokens: number;
+    startedAt: number;
+    lastTool: string | null;
+    compactions: number;
+    checkpointWritten: boolean;
+    /** Set when the guard ended the reply instead of the model finishing it. */
+    endedBy: SliceEnd | null;
+    /** The limit that ended it, for the record. */
+    endedByLimit: string | null;
+    /** Steps past which every non-exempt tool call is refused, once one was refused. */
+    refusedAt: number | null;
+}
+export declare function createSliceState(_policy: SlicePolicy, slice?: number, now?: number): SliceState;
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+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. */
+export declare function looksLikeCheck(command: string): boolean;
+interface ToolCall {
+    toolName: string;
+    input?: unknown;
+}
+interface ToolResult {
+    toolName: string;
+    isError?: boolean;
+    input?: unknown;
+}
+/** The part of Pi's extension API this guard uses. Structural, so the module needs no Pi import. */
+interface GuardApi {
+    on(event: 'agent_start', handler: () => unknown): void;
+    on(event: 'tool_call', handler: (event: ToolCall) => unknown): void;
+    on(event: 'tool_result', handler: (event: ToolResult) => unknown): void;
+    on(event: 'message_end', handler: (event: {
+        message: {
+            role: string;
+            usage?: {
+                input?: number;
+                output?: number;
+                cacheRead?: number;
+                cacheWrite?: number;
+            };
+        };
+    }) => unknown): void;
+}
+export interface WorkSliceGuardOptions {
+    policy: SlicePolicy;
+    state: SliceState;
+    /** Called once the guard has decided the reply must stop; 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.
+ */
+export declare function workSliceGuard(options: WorkSliceGuardOptions): (pi: GuardApi) => void;
+/**
+ * Which slice of its session a run is, from 1. Counts the recorded continuation chain, so it
+ * survives a restart and needs no extra field on the run record.
+ */
+export declare function sliceOf(root: string, runId: string, limit?: number): number;
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export declare function derivedReason(end: SliceEnd | null): Checkpoint['reason'];
+export {};