@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/sessions/workSlice.js

@@ -0,0 +1,297 @@
+// A reply's work slice (PROP-0041): a bounded amount of work, then a handoff checkpoint, then a
+// continuation. The guard here refuses the call that would run past the budget, once with a
+// request for the checkpoint, and ends the reply if the model keeps calling tools. It also names
+// repeated work before it becomes a loop. All decisions are deterministic; no model is consulted.
+import { createHash } from 'node:crypto';
+import { findRun } from "./runStore.js";
+export const WORK_SLICE_EXTENSION = 'work-slice';
+/** The foundation defaults: enough for one meaningful step of work, short enough to report. */
+export const DEFAULT_SLICE_POLICY = {
+    enabled: true,
+    // Roughly 40 minutes of ordinary work (about 15 s a call), so a checkpoint is a chapter of a
+    // task, not an interruption every few edits. A task still gets eight of them before the cap.
+    maxToolCalls: 160,
+    maxMinutes: 40,
+    // A generous cost ceiling, counted on new input, cache writes and output only: heavy reading at
+    // a large context can add tens of thousands of tokens a request, so a small cap stopped useful
+    // work (see the "Confirm plan model support" thread). 320k is a safety net, not the bound.
+    maxNewTokens: 320_000,
+    maxSlices: 8,
+    continue: true
+};
+const LIMITS = {
+    maxToolCalls: { min: 1, max: 2_000 },
+    maxMinutes: { min: 1, max: 480 },
+    maxNewTokens: { min: 1_000, max: 5_000_000 },
+    maxSlices: { min: 1, max: 100 }
+};
+export 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 function parseWorkSlice(input) {
+    if (input === undefined || input === null) {
+        const launch = process.env.XINGULAR_WORK_SLICE?.trim().toLowerCase();
+        return { ...DEFAULT_SLICE_POLICY, ...(launch === 'off' || launch === '0' || launch === 'false' ? { enabled: false } : {}) };
+    }
+    if (typeof input !== 'object' || Array.isArray(input))
+        throw new WorkSliceError('workSlice must be an object.');
+    const record = input;
+    const policy = { ...DEFAULT_SLICE_POLICY };
+    for (const key of Object.keys(record)) {
+        if (key === 'enabled') {
+            if (typeof record.enabled !== 'boolean')
+                throw new WorkSliceError('workSlice.enabled must be true or false.');
+            policy.enabled = record.enabled;
+            continue;
+        }
+        if (key === 'continue') {
+            if (typeof record.continue !== 'boolean')
+                throw new WorkSliceError('workSlice.continue must be true or false.');
+            policy.continue = record.continue;
+            continue;
+        }
+        const limits = LIMITS[key];
+        if (!limits)
+            throw new WorkSliceError(`workSlice has no field ${key}.`);
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isInteger(value))
+            throw new WorkSliceError(`workSlice.${key} must be a whole number.`);
+        // 0 switches one limit off, as the settings page says.
+        if (value === 0) {
+            policy[key] = 0;
+            continue;
+        }
+        if (value < limits.min || value > limits.max)
+            throw new WorkSliceError(`workSlice.${key} must be between ${limits.min} and ${limits.max}, or 0 for no limit.`);
+        policy[key] = value;
+    }
+    return policy;
+}
+export function createSliceState(_policy, slice = 1, now = Date.now()) {
+    return { slice, steps: 0, tokens: 0, startedAt: now, lastTool: null, compactions: 0, checkpointWritten: false, endedBy: null, endedByLimit: null, refusedAt: null };
+}
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+export function resetSliceState(state, now = Date.now()) {
+    state.steps = 0;
+    state.tokens = 0;
+    state.startedAt = now;
+    state.lastTool = null;
+    state.compactions = 0;
+    state.checkpointWritten = false;
+    state.endedBy = null;
+    state.endedByLimit = null;
+    state.refusedAt = null;
+}
+/** The first limit this reply has passed, named as a person would say it. */
+export function sliceLimitReached(policy, state, now = Date.now()) {
+    if (policy.maxToolCalls > 0 && state.steps >= policy.maxToolCalls)
+        return `${policy.maxToolCalls} tool calls`;
+    if (policy.maxMinutes > 0 && now - state.startedAt >= policy.maxMinutes * 60_000)
+        return `${policy.maxMinutes} minutes`;
+    if (policy.maxNewTokens > 0 && state.tokens >= policy.maxNewTokens)
+        return `${Math.round(policy.maxNewTokens / 1000)}k new tokens`;
+    return null;
+}
+/** Tools a reply may still call while it writes its handoff. A plan update waits for the next slice. */
+const HANDOFF_TOOLS = new Set(['checkpoint_write', 'session_name']);
+/** Tools whose repetition is how waiting works, not a loop. */
+const POLLING_TOOLS = new Set(['wait_subagents', 'subagents.list', 'subagents.status']);
+/** Commands that read as a check, for "no progress" and "still failing" rules. */
+export function looksLikeCheck(command) {
+    return /\b(test|tests|typecheck|tsc|vitest|jest|cargo|check:|prove|lint|ci|build)\b/u.test(command);
+}
+/**
+ * A stable rendering of a value: object keys sorted, so argument order never changes the result.
+ * Depth is bounded so a cyclic or absurdly nested input cannot recurse forever.
+ */
+function canonical(value, depth = 0) {
+    if (depth > 8)
+        return '…';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item, depth + 1)).join(',')}]`;
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined);
+    entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, depth + 1)}`).join(',')}}`;
+}
+/**
+ * A call's identity: its name and every argument, hashed so the key stays small even when an
+ * argument is a whole file. A changed argument is a different call; only an identical one repeats.
+ * Reading a fixed handful of fields made every `checklist_write` look identical, so a reply that
+ * reported its progress was told it was repeating work.
+ */
+const signature = (name, input) => `${name}\u0000${createHash('sha256').update(canonical(input ?? null)).digest('hex')}`;
+const clip = (value, limit) => (value.length <= limit ? value : `${value.slice(0, limit - 1)}…`);
+function handoffRequest(limit, state) {
+    return clip(`This reply reached its work-slice limit (${limit}; step ${state.steps}). Call checkpoint_write now with what is done, the single next step, anything blocking, the files you touched and the checks that matter. Then tell the user in a few lines where you stopped. Do not call other tools.`, 600);
+}
+function stalledNote(reason) {
+    return clip(`You are repeating work: ${reason}. Do not repeat it. Choose a different approach, read what the earlier attempt returned, or call checkpoint_write with the blocker so the next slice can decide.`, 600);
+}
+/**
+ * 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 function workSliceGuard(options) {
+    const { policy, state } = options;
+    const calls = new Map();
+    const edits = new Map();
+    const failures = new Map();
+    let stepsSinceProgress = 0;
+    let nudged = false;
+    /** Repetition is judged inside one reply; the next reply starts from a clean count. */
+    const resetRepetition = () => {
+        calls.clear();
+        edits.clear();
+        failures.clear();
+        stepsSinceProgress = 0;
+        nudged = false;
+    };
+    const end = (kind, limit) => {
+        state.endedBy = kind;
+        state.endedByLimit = limit;
+        options.onEnd?.(kind, limit);
+        const reason = kind === 'stuck'
+            ? stalledNote(limit)
+            : kind === 'compaction-thrash'
+                ? handoffRequest('three context compactions in one reply', state)
+                : handoffRequest(limit, state);
+        return { block: true, terminate: true, reason };
+    };
+    const repeated = (name, input) => {
+        if (POLLING_TOOLS.has(name))
+            return null;
+        const key = signature(name, input);
+        const count = (calls.get(key) ?? 0) + 1;
+        calls.set(key, count);
+        if (count < 3)
+            return null;
+        return name === 'bash' ? `the same Bash command ${count} times (steps ending at ${state.steps})` : `the same ${name} call ${count} times (steps ending at ${state.steps})`;
+    };
+    const failing = (name, input) => {
+        if (name !== 'bash')
+            return null;
+        const command = input && typeof input === 'object' ? String(input.command ?? '') : '';
+        if (!command || !looksLikeCheck(command))
+            return null;
+        const count = failures.get(command) ?? 0;
+        return count >= 2 ? `the check ${command} failed ${count} times` : null;
+    };
+    return (pi) => {
+        pi.on('agent_start', () => {
+            resetSliceState(state);
+            resetRepetition();
+        });
+        pi.on('message_end', (event) => {
+            const usage = event.message.usage;
+            if (event.message.role !== 'assistant' || !usage)
+                return;
+            // New tokens only: the cached prefix was sent before and is not new context or new cost.
+            state.tokens += (usage.input ?? 0) + (usage.cacheWrite ?? 0) + (usage.output ?? 0);
+        });
+        pi.on('tool_result', (event) => {
+            if (event.toolName === 'checkpoint_write' && !event.isError) {
+                state.checkpointWritten = true;
+                stepsSinceProgress = 0;
+                nudged = false;
+            }
+            if (event.toolName !== 'bash')
+                return;
+            const command = event.input && typeof event.input === 'object' ? String(event.input.command ?? '') : '';
+            if (!command || !looksLikeCheck(command))
+                return;
+            if (event.isError) {
+                failures.set(command, (failures.get(command) ?? 0) + 1);
+                return;
+            }
+            // A passing check is progress: the repetition rules start over.
+            failures.delete(command);
+            edits.clear();
+            calls.clear();
+            stepsSinceProgress = 0;
+            nudged = false;
+        });
+        pi.on('tool_call', (event) => {
+            const name = event.toolName;
+            state.steps += 1;
+            state.lastTool = name;
+            const handoff = HANDOFF_TOOLS.has(name);
+            // A handoff is always callable; after the slice ended it is the only thing that is.
+            if (state.endedBy) {
+                return handoff ? undefined : { block: true, terminate: true, reason: 'This reply is over. Its checkpoint is recorded; nothing else runs.' };
+            }
+            if (state.compactions >= 3) {
+                if (handoff) {
+                    state.endedBy = 'compaction-thrash';
+                    state.endedByLimit = 'three compactions';
+                    return undefined;
+                }
+                return end('compaction-thrash', 'three compactions');
+            }
+            const limit = sliceLimitReached(policy, state);
+            if (limit) {
+                // The slice ends here; the model gets one wrap-up request to write the handoff. A handoff
+                // call is never refused, including when it is the very first call past the budget.
+                state.endedBy = 'budget';
+                state.endedByLimit = limit;
+                state.refusedAt ??= state.steps;
+                stepsSinceProgress = 0;
+                return handoff ? undefined : { block: true, reason: handoffRequest(limit, state) };
+            }
+            if (handoff)
+                return undefined;
+            const edit = name === 'edit' || name === 'write';
+            const path = edit && event.input && typeof event.input === 'object' ? String(event.input.path ?? '') : '';
+            if (edit && path) {
+                const count = (edits.get(path) ?? 0) + 1;
+                edits.set(path, count);
+                stepsSinceProgress = 0;
+                if (count >= 4) {
+                    const reason = `${path} was edited ${count} times with no passing check between`;
+                    if (nudged)
+                        return end('stuck', reason);
+                    nudged = true;
+                    return { block: true, reason: stalledNote(reason) };
+                }
+            }
+            else {
+                stepsSinceProgress += 1;
+            }
+            const repeat = repeated(name, event.input);
+            const failure = failing(name, event.input);
+            const noProgress = stepsSinceProgress >= 25 ? `${stepsSinceProgress} steps with no file change and no passing check` : null;
+            const reason = repeat ?? failure ?? noProgress;
+            if (!reason)
+                return undefined;
+            if (nudged)
+                return end('stuck', reason);
+            nudged = true;
+            stepsSinceProgress = 0;
+            return { block: true, reason: stalledNote(reason) };
+        });
+    };
+}
+/**
+ * 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 function sliceOf(root, runId, limit = 100) {
+    let current = runId;
+    let count = 0;
+    const seen = new Set();
+    while (current && count < limit && !seen.has(current)) {
+        seen.add(current);
+        count += 1;
+        current = findRun(root, current)?.resumedFromRunId ?? null;
+    }
+    return Math.max(1, count);
+}
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export function derivedReason(end) {
+    return end ?? 'requested';
+}

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

@@ -0,0 +1,15 @@
+import type { RunRecord } from "./contracts.js";
+import type { ScopeDecision } from "./policy.js";
+export declare const WORKSPACE_FILE_WRITE_TOOLS: Set<string>;
+export interface WorkspaceWriteInspection {
+    input: unknown;
+    path: string | null;
+    outside: boolean;
+    reason: string | null;
+}
+/** Canonicalize native file-write arguments and identify an explicit workspace escape. */
+export declare function inspectWorkspaceWrite(workspaceRoot: string, cwd: string, tool: string, input: unknown): WorkspaceWriteInspection;
+/** Adds the mandatory per-operation boundary without allowing it to waive host hard denials. */
+export declare function combineWorkspaceScope(scope: ScopeDecision, inspection: WorkspaceWriteInspection): ScopeDecision;
+/** Resolve a root for pre-boundary run records, then inspect the write using the pinned directory. */
+export declare function inspectRunWorkspaceWrite(run: RunRecord, tool: string, input: unknown): WorkspaceWriteInspection;

package/dist/sdk/sessions/workspaceBoundary.js

@@ -0,0 +1,46 @@
+import { isWithinWorkspace, resolveWorkspaceRoot, resolveWritePath, verifyWorkspaceRoot } from "../core/workspace.js";
+export const WORKSPACE_FILE_WRITE_TOOLS = new Set(['edit', 'write']);
+/** Canonicalize native file-write arguments and identify an explicit workspace escape. */
+export function inspectWorkspaceWrite(workspaceRoot, cwd, tool, input) {
+    if (!WORKSPACE_FILE_WRITE_TOOLS.has(tool.toLowerCase()) || !input || typeof input !== 'object' || Array.isArray(input)) {
+        return { input, path: null, outside: false, reason: null };
+    }
+    const args = input;
+    if (typeof args.path !== 'string')
+        return { input, path: null, outside: false, reason: null };
+    const root = verifyWorkspaceRoot(workspaceRoot);
+    const path = resolveWritePath(args.path, cwd);
+    const outside = !isWithinWorkspace(root, path);
+    return {
+        input: { ...args, path },
+        path,
+        outside,
+        reason: outside ? `Write target ${path} is outside the active project workspace ${root}.` : null
+    };
+}
+/** Adds the mandatory per-operation boundary without allowing it to waive host hard denials. */
+export function combineWorkspaceScope(scope, inspection) {
+    if (!inspection.outside)
+        return scope;
+    if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
+        return scope;
+    return {
+        ...scope,
+        allowed: false,
+        requiresApproval: true,
+        humanOnly: true,
+        allowGlobalApproval: scope.humanOnly ? scope.allowGlobalApproval : true,
+        reason: inspection.reason
+    };
+}
+/** Resolve a root for pre-boundary run records, then inspect the write using the pinned directory. */
+export function inspectRunWorkspaceWrite(run, tool, input) {
+    const cwd = run.workingDirectory;
+    const root = run.workspaceRoot ?? (cwd ? resolveWorkspaceRoot(cwd) : null);
+    if (!root || !cwd) {
+        if (WORKSPACE_FILE_WRITE_TOOLS.has(tool.toLowerCase()))
+            throw new Error('The active project workspace could not be resolved; file writes are blocked.');
+        return { input, path: null, outside: false, reason: null };
+    }
+    return inspectWorkspaceWrite(root, cwd, tool, input);
+}

package/dist/sdk/terminal/browserControl.js

@@ -1,4 +1,5 @@
 import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { describePlugin } from "../plugins/surfaces.js";
 import * as path from 'node:path';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { invalid } from "../core/errors.js";
@@ -46,7 +47,7 @@ export class BrowserControl {
         ])
             add({ id: `foundation:${id}`, section: 'foundation', name: name, description: description, owner: 'Foundation', origin: 'Built-in', status: 'Read-only' });
         for (const plugin of plugins) {
-            add({ id: `plugin:${plugin.id}`, section: 'plugins', name: plugin.title, description: plugin.description,
+            add({ id: `plugin:${plugin.id}`, section: 'plugins', name: plugin.title, description: describePlugin(plugin),
                 owner: plugin.title, origin: plugin.source, status: plugin.required ? 'Required' : plugin.trust === 'untrusted' ? 'Needs trust' : 'Saved configuration',
                 pluginId: plugin.id, path: plugin.path ?? undefined, required: plugin.required });
             for (const entry of plugin.contributions) {

package/dist/sdk/terminal/controller.d.ts

@@ -1,9 +1,10 @@
 import { type RunEvent, type RunRecord } from "../sessions/contracts.js";
 import type { ActiveRun, ApprovalDecision, QuestionAnswer } from "../sessions/registry.js";
-import { type TerminalSubagentActivity, type TerminalSubagentProfile } from "./subagentMonitor.js";
+import { type TerminalSubagentActivity, type TerminalSubagentProfile, type TerminalSubagentRun } from "./subagentMonitor.js";
 export interface PolicyReply {
     allowed: boolean;
     reason?: string | null;
+    workspaceRoot?: string;
     requiresApproval?: boolean;
     rememberable?: boolean;
     standing?: 'full' | 'switch' | 'none';
@@ -19,6 +20,12 @@ export interface ControllerHooks {
     }): ActiveRun;
     /** Whether a native tool call may run. */
     policy(run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply>;
+    /** The workspace root pinned on the run record. */
+    workspaceRoot(run: ActiveRun): string;
+    /** One-shot approval before an explicitly broad Bash command runs. */
+    workspaceEscape(run: ActiveRun, tool: string, args: unknown, reason: string): Promise<boolean>;
+    /** Whether Full Permission may bypass the filesystem boundary for this Bash command. */
+    workspaceBoundaryBypass(run: ActiveRun, tool: string, args: unknown): Promise<boolean>;
     /** Saves a user-selected tool grant in the shared local approval store. */
     allowToolGlobally(target: string): void;
     /** The native conversation identity changed. */
@@ -37,6 +44,7 @@ export declare class TerminalController {
     private run;
     private readonly pending;
     private readonly subagents;
+    private subagentParentRunId;
     private ready;
     private disposed;
     private dirty;
@@ -67,8 +75,8 @@ export declare class TerminalController {
     /** Project registry-owned questions, including grouped requests, into the terminal inbox. */
     observe(event: RunEvent, descendant?: boolean): void;
     /** A child event that belongs to the active terminal parent run. */
-    observeSubagent(parentRunId: string, run: RunRecord, event: RunEvent, profile?: TerminalSubagentProfile | null): void;
-    /** Read-only child activity for the active run. */
+    observeSubagent(parentRunId: string, run: RunRecord, event: RunEvent, profile?: TerminalSubagentProfile | null, runtime?: Pick<TerminalSubagentRun, 'accountLabel' | 'model' | 'effort'>): void;
+    /** Read-only child activity for the latest parent run, retained until another run begins. */
     subagentSnapshot(): TerminalSubagentActivity[];
     /** The socket grants this interface only to the process that owns terminal input. */
     control(call: string, data: Record<string, any>): Promise<unknown>;

package/dist/sdk/terminal/controller.js

@@ -14,6 +14,7 @@ export class TerminalController {
     run = null;
     pending = new Map();
     subagents = new SubagentMonitor();
+    subagentParentRunId = null;
     ready = false;
     disposed = false;
     dirty = false;
@@ -52,6 +53,7 @@ export class TerminalController {
             throw new Error('The native prompt did not match the reserved delivery. Inspect the terminal before continuing.');
         const run = this.hooks.begin({ reservedRunId: delivery?.runId ?? null, nativeTurnId, text });
         this.run = run;
+        this.subagentParentRunId = run.runId;
         this.subagents.begin(run.runId);
         run.onInterrupt(() => void this.commands.push({ type: 'interrupt' }));
         if (text)
@@ -60,10 +62,8 @@ export class TerminalController {
         this.delivery = null;
         return run;
     }
-    finish(outcome, message) {
-        const runId = this.run?.runId;
-        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined);
-        this.subagents.clear(runId);
+    finish(outcome, message, reason) {
+        this.run?.finish(outcome, message ? { code: 'terminal_attention', message } : undefined, reason);
         this.run = null;
         this.seen.clear();
         this.pending.clear();
@@ -133,10 +133,11 @@ export class TerminalController {
             const payload = event.payload;
             this.pending.set(String(payload.questionId), { ...payload, type: 'question', requestId: payload.questionId, runId: event.runId });
         }
-        else if (descendant && event.type === 'approval.requested') {
+        else if (event.type === 'approval.requested') {
             const payload = event.payload;
-            if (!payload.automatic)
+            if (!payload.automatic && (descendant || payload.target === 'workspace-write')) {
                 this.pending.set(String(payload.approvalId), { ...payload, type: 'approval', requestId: payload.approvalId, runId: event.runId });
+            }
         }
         else if (event.type === 'approval.resolved') {
             this.pending.delete(String(event.payload.approvalId));
@@ -146,7 +147,7 @@ export class TerminalController {
         }
     }
     /** A child event that belongs to the active terminal parent run. */
-    observeSubagent(parentRunId, run, event, profile = null) {
+    observeSubagent(parentRunId, run, event, profile = null, runtime = {}) {
         if (this.disposed || this.activeRun?.runId !== parentRunId || run.relation !== 'subagent')
             return;
         this.subagents.observe(parentRunId, {
@@ -158,13 +159,13 @@ export class TerminalController {
             status: runStatusSchema.parse(run.status),
             startedAt: run.startedAt,
             endedAt: run.endedAt,
-            profile
+            profile,
+            ...runtime
         }, event);
     }
-    /** Read-only child activity for the active run. */
+    /** Read-only child activity for the latest parent run, retained until another run begins. */
     subagentSnapshot() {
-        const run = this.activeRun;
-        return run ? this.subagents.snapshot(run.runId) : [];
+        return this.subagentParentRunId ? this.subagents.snapshot(this.subagentParentRunId) : [];
     }
     /** The socket grants this interface only to the process that owns terminal input. */
     async control(call, data) {
@@ -185,6 +186,20 @@ export class TerminalController {
                 throw new HarnessError('invalid_request', 'An active run and tool name are required.');
             return this.hooks.policy(run, data.tool, data.args ?? {});
         }
+        if (call === 'terminal.workspaceBoundaryBypass') {
+            const run = this.activeRun;
+            if (!run || data.tool !== 'bash')
+                throw new HarnessError('invalid_request', 'An active run and Bash command are required.');
+            const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+            return { bypass: await this.hooks.workspaceBoundaryBypass(run, 'bash', args) };
+        }
+        if (call === 'terminal.workspaceEscape') {
+            const run = this.activeRun;
+            if (!run || data.tool !== 'bash' || typeof data.reason !== 'string' || !data.reason)
+                throw new HarnessError('invalid_request', 'An active run, Bash command, and outside-scope request are required.');
+            const args = data.args && typeof data.args === 'object' && !Array.isArray(data.args) ? data.args : {};
+            return { approved: await this.hooks.workspaceEscape(run, 'bash', args, data.reason) };
+        }
         if (call === 'terminal.approval')
             return this.requestNativeApproval(data);
         if (call === 'terminal.answers' && this.hooks.answerQuestions) {
@@ -294,6 +309,10 @@ export class TerminalController {
             }
             this.ready = true;
             if (typeof data.nativeSessionId === 'string' && data.nativeSessionId) {
+                if (this.nativeId !== data.nativeSessionId) {
+                    this.subagents.clear();
+                    this.subagentParentRunId = null;
+                }
                 this.nativeId = data.nativeSessionId;
                 this.hooks.native(data.nativeSessionId);
             }
@@ -301,7 +320,7 @@ export class TerminalController {
         }
         if (event === 'begin') {
             const run = this.begin(String(data.turnId ?? randomUUID()), String(data.text ?? ''));
-            return { runId: run.runId };
+            return { runId: run.runId, workspaceRoot: this.hooks.workspaceRoot(run) };
         }
         if (event === 'shutdown') {
             this.ready = false;
@@ -309,7 +328,11 @@ export class TerminalController {
             return {};
         }
         if (event === 'settled') {
-            this.finish(data.aborted ? 'interrupted' : data.error ? 'failed' : 'completed', data.error ? String(data.error) : undefined);
+            // A reply that stopped at its work-slice boundary is interrupted, not completed: the record
+            // says `slice_complete` (or `stalled`) so a host can continue it (PROP-0041).
+            const reason = typeof data.reason === 'string' ? data.reason : undefined;
+            const outcome = data.error ? 'failed' : data.aborted || reason ? 'interrupted' : 'completed';
+            this.finish(outcome, data.error ? String(data.error) : undefined, reason);
             return {};
         }
         const run = this.run;
@@ -356,6 +379,8 @@ export class TerminalController {
             run.emit('usage.updated', data);
         else if (event === 'checklist')
             run.emit('checklist.updated', { items: data.items });
+        else if (event === 'checkpoint')
+            run.emit('checkpoint', data);
         else if (event === 'file')
             run.emit('file.changed', data);
         else if (event === 'message')
@@ -379,5 +404,7 @@ export class TerminalController {
         this.delivery?.reject(new Error('The terminal stopped before prompt acknowledgement.'));
         this.delivery = null;
         this.finish('interrupted');
+        this.subagents.clear();
+        this.subagentParentRunId = null;
     }
 }

package/dist/sdk/terminal/opentui/theme.d.ts

@@ -0,0 +1,43 @@
+export interface OpenTuiTheme {
+    background: string;
+    panel: string;
+    /** The translucent layer that dims the console behind a centered page dialog. */
+    scrim: string;
+    border: string;
+    borderFocus: string;
+    text: string;
+    muted: string;
+    dim: string;
+    /** The shared selected-row field and its two text tones. */
+    selectionBg: string;
+    selectionText: string;
+    selectionMuted: string;
+    questionSelectedBg: string;
+    questionActionBg: string;
+    questionActionText: string;
+    primary: string;
+    accent: string;
+    success: string;
+    warning: string;
+    error: string;
+    /** The composer's Bash mode marker and rules; the command body keeps the normal text color. */
+    bashMode: string;
+    /** The composer's rules while plan mode is on. */
+    planMode: string;
+    /** Image and pasted-text labels in the composer and in sent messages. */
+    attachment: string;
+    purple: string;
+    cyan: string;
+}
+export declare const opentuiTheme: OpenTuiTheme;
+/** The colour of an agent profile's name (PROP-0029); an unknown name falls back to the accent. */
+export declare function profileColor(theme: OpenTuiTheme, name: string): string;
+export declare function blendHexColor(from: string, to: string, amount: number): string;
+export declare function composerRuleColor(theme: OpenTuiTheme, mode: {
+    bash: boolean;
+    plan: boolean;
+    overlay: boolean;
+}): string;
+export declare function noticeColor(theme: OpenTuiTheme, type: string): string;
+export declare function toolColor(theme: OpenTuiTheme, status: 'running' | 'ok' | 'error' | 'pending'): string;
+export declare function thinkingLevelColor(theme: OpenTuiTheme, level: string): string;