@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/terminal/terminals.js

@@ -13,6 +13,8 @@ import { readAudit } from "../accounts/store.js";
 import { log } from "../core/bus.js";
 import { HarnessError, invalid } from "../core/errors.js";
 import { newId, now } from "../core/fs.js";
+import { formatBashCommandForApproval } from "../core/workspaceBashTool.js";
+import { resolveWorkspaceRoot } from "../core/workspace.js";
 import { prependSearchPath, searchPath } from "../core/path.js";
 import { dispatch } from "../tools/dispatch.js";
 import { materialise } from "../variant/materialise.js";
@@ -20,8 +22,14 @@ import * as componentLibrary from "../variant/components.js";
 import * as variantStore from "../variant/store.js";
 import { compile, copyToRun, record, render, saveForSession } from "../prompt/compile.js";
 import { isActiveStatus } from "../sessions/contracts.js";
-import { findRun, loadRun, saveRun, updateRun } from "../sessions/runStore.js";
-import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { findRun, loadRun, readEvents, recordedSubagents, saveRun, updateRun } from "../sessions/runStore.js";
+import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "../sessions/workspaceBoundary.js";
+import { TODO_WRITE } from "../tools/todo.js";
+import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
+import { harnessTools } from "../tools/harnessTools.js";
+import { HARNESS_PLUGINS } from "../plugins/builtin.js";
+import * as attachments from "../plugins/attachments.js";
+import { FIRST_PARTY_PLUGINS } from "../plugins/firstParty.js";
 import { createProfile, listProfiles, profileDirs, profileSection, removeProfile, resolveProfile } from "../agents/profiles.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
 import { contributionId } from "../plugins/identity.js";
@@ -34,7 +42,7 @@ import { TerminalController } from "./controller.js";
 import { terminalCommandFiles } from "./launch.js";
 import { SessionSocket, socketPath } from "./socket.js";
 import { harnessLogInfo, readHarnessLogChunk } from "./logs.js";
-import { listTerminalTrajectoryRuns, readTerminalTrajectory } from "./trajectory.js";
+import { listTerminalTrajectoryRuns, readTerminalTrajectory, latestTerminalTodo } from "./trajectory.js";
 import { BrowserControl } from "./browserControl.js";
 /** Identity of the exact resource decision that this terminal was prepared with. */
 function resourceIdentity(loading) {
@@ -90,12 +98,61 @@ export class Terminals {
         }
         return this.childProfiles.get(record.id) ?? null;
     }
+    /** Account, model and effort for a monitor row, from the run record. */
+    monitorRuntime(live, record) {
+        let accountLabel = record.accountId === live.account.id ? live.account.label : null;
+        if (accountLabel === null && record.accountId) {
+            try {
+                accountLabel = this.options.accounts.find(record.accountId).label;
+            }
+            catch { }
+        }
+        return { accountLabel, model: record.model ?? null, effort: record.effort ?? null };
+    }
+    /**
+     * Shows the reopened conversation's latest parent run again: the last owner on its native branch
+     * that ran in this folder, with every descendant flat, as each ended.
+     */
+    hydrateMonitor(live, owners) {
+        const { root } = this.options.env;
+        const native = live.controller.nativeSessionId;
+        if (!native)
+            return;
+        for (const id of [...owners].reverse()) {
+            const record = findRun(root, id);
+            if (!record || record.relation || record.nativeSessionId !== native || record.workingDirectory !== live.input.cwd)
+                continue;
+            const children = [];
+            const seen = new Set([record.id]);
+            const visit = (parentId) => {
+                for (const childId of recordedSubagents(root, parentId)) {
+                    if (seen.has(childId))
+                        continue;
+                    seen.add(childId);
+                    const child = findRun(root, childId);
+                    if (child?.relation !== 'subagent')
+                        continue;
+                    children.push(child);
+                    visit(child.id);
+                }
+            };
+            visit(record.id);
+            const entry = (run, profile = null) => ({ record: run, events: readEvents(root, run.id), profile, runtime: this.monitorRuntime(live, run) });
+            live.controller.restoreMonitor(entry(record), children.map(child => entry(child, this.subagentProfile(child))));
+            return;
+        }
+    }
     constructor(options) {
         this.options = options;
         this.assets = options.assets ?? defaultAssets();
         options.runs.listen(event => {
-            this.sessions.get(event.sessionId)?.controller.observe(event);
+            const session = this.sessions.get(event.sessionId);
+            session?.controller.observe(event);
             const record = findRun(options.env.root, event.runId);
+            if (record && !record.relation && session) {
+                session.controller.observeMain(record, event, this.monitorRuntime(session, record));
+                return;
+            }
             if (record?.relation !== 'subagent')
                 return;
             let parentId = record.parentRunId;
@@ -108,7 +165,12 @@ export class Terminals {
                 const owner = this.sessions.get(parent.sessionId);
                 if (owner?.controller.activeRun?.runId === parent.id) {
                     owner.controller.observe(event, true);
-                    owner.controller.observeSubagent(parent.id, record, event, this.subagentProfile(record));
+                    const settings = options.subagents?.runtimeSettings(record.id);
+                    owner.controller.observeSubagent(parent.id, record, event, this.subagentProfile(record), {
+                        accountLabel: owner.account.label,
+                        model: settings?.model ?? record.model ?? null,
+                        effort: settings?.effort ?? record.effort ?? null
+                    });
                     break;
                 }
                 parentId = parent.parentRunId;
@@ -153,23 +215,48 @@ export class Terminals {
         }
         return bin;
     }
-    /** The broker's tools, then the world tools whose plugins are on for this session. */
+    /**
+     * The harness's own History, Wiki and skill tools, then the broker's, then the world tools whose
+     * plugins are on for this session: the same tools a structured session has (INV-PAR-1).
+     */
     async tools(session, listing) {
         const brokered = this.options.apps.brokerTools(session);
         const live = this.sessions.get(session.sessionId);
-        const { world } = this.options;
-        if (!world || !live)
+        if (!live)
             return brokered;
+        const own = await this.ownTools(live, listing);
+        const { world } = this.options;
+        if (!world)
+            return [...own, ...brokered];
         const context = { run: live.controller.activeRun, caller: live.caller, attended: true, subagent: false, sessionKey: session.sessionId, cwd: live.input.cwd };
         if (!listing)
-            return [...brokered, ...world.tools(context, (_plugin, tool) => this.worldNames.get(session.sessionId)?.has(tool) ?? false)];
+            return [...own, ...brokered, ...world.tools(context, (_plugin, tool) => this.worldNames.get(session.sessionId)?.has(tool) ?? false)];
         const on = await this.worldOn(live);
         const tools = world.tools(context, (plugin, tool) => on(plugin, tool));
         this.worldNames.set(session.sessionId, new Set(tools.map((tool) => tool.name)));
         for (const tool of tools)
             if (tool.readOnly)
                 this.worldReadOnly.add(tool.name);
-        return [...brokered, ...tools];
+        return [...own, ...brokered, ...tools];
+    }
+    ownNames = new Map();
+    async ownTools(live, listing) {
+        const sessionId = live.caller.sessionId;
+        const all = harnessTools(this.options.env, live.caller, { variantDir: this.variantDirs.get(sessionId) ?? null })
+            .filter((tool) => DEFAULT_TOOL_NAMES.includes(tool.name));
+        if (!listing)
+            return all.filter((tool) => this.ownNames.get(sessionId)?.has(tool.name) ?? false);
+        const on = await this.worldOn(live);
+        const owner = (tool) => HARNESS_PLUGINS.find((plugin) => plugin.tools?.some((entry) => entry.name === tool))?.id ?? null;
+        const tools = all.filter((tool) => {
+            const plugin = owner(tool.name);
+            return !plugin || on(plugin, tool.name);
+        });
+        this.ownNames.set(sessionId, new Set(tools.map((tool) => tool.name)));
+        for (const tool of tools)
+            if (tool.readOnly)
+                this.worldReadOnly.add(tool.name);
+        return tools;
     }
     /** The world tools a new session will have, named in its instructions. */
     async worldToolNames(input, account) {
@@ -181,6 +268,16 @@ export class Terminals {
         const on = plugins ? new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id))) : null;
         return world.plugins.flatMap((plugin) => (plugin.tools ?? []).map((tool) => tool.name).filter((name) => !on || on.has(contributionId(plugin.id, 'tool', name))));
     }
+    /** The harness's own History, Wiki and skill tools a new session will have. */
+    async ownToolNames(input, account) {
+        const list = this.options.pluginControl?.list;
+        const plugins = list ? await list({ cwd: input.cwd, accountId: account.id, projectId: input.projectId ?? null }) : null;
+        const on = plugins ? new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id))) : null;
+        return DEFAULT_TOOL_NAMES.filter((name) => {
+            const plugin = HARNESS_PLUGINS.find((entry) => entry.tools?.some((tool) => tool.name === name));
+            return !on || !plugin || on.has(contributionId(plugin.id, 'tool', name));
+        });
+    }
     /** Whether a world tool's plugin is switched on for a session's folder, account and project. */
     async worldOn(live) {
         const list = this.options.pluginControl?.list;
@@ -203,6 +300,17 @@ export class Terminals {
                 const { Type } = await import('typebox');
                 return { tools: (await this.tools(session, true)).map((tool) => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) };
             }
+            case 'firstParty.list': {
+                // The harness's own extensions switched on for this session, with their settings.
+                const live = this.sessions.get(session.sessionId);
+                const list = this.options.pluginControl?.list;
+                if (!live || !list)
+                    return { plugins: [] };
+                const plugins = await list({ cwd: live.input.cwd, accountId: live.account.id, projectId: live.input.projectId ?? null });
+                const on = new Set(plugins.flatMap((plugin) => plugin.contributions.filter((item) => item.state === 'on').map((item) => item.id)));
+                const settings = attachments.load(this.options.env.root).settings;
+                return { plugins: FIRST_PARTY_PLUGINS.filter((plugin) => plugin.code?.some((code) => on.has(`${plugin.id}/code/${code.name}`))).map((plugin) => ({ id: plugin.id, settings: settings[plugin.id] ?? {} })) };
+            }
             case 'tools.call': {
                 const tool = (await this.tools(session, false)).find((candidate) => candidate.name === params.name);
                 if (!tool)
@@ -451,7 +559,45 @@ export class Terminals {
                 throw new HarnessError('unknown_method', `Unknown call ${call}.`);
         }
     }
-    /** `/plugin:notes` and `/plugin:annotate`: the page notes a person keeps, and the visible browser they capture them in. */
+    /** `/usage:analysis` and `/usage:limit`: usage for this session's own account, project or session. */
+    async usageCall(live, call, params) {
+        const usage = this.options.usage;
+        const limits = this.options.usageLimits;
+        if (!usage || !limits)
+            throw invalid('Usage is unavailable in this host.');
+        if (call === 'terminal.usage.summary') {
+            const scope = params.scope === 'session' || params.scope === 'project' || params.scope === 'all' ? params.scope : 'account';
+            if (scope === 'project' && !live.input.projectId)
+                throw invalid('This session has no project to report usage for.');
+            const period = params.period === 'today' || params.period === '30d' || params.period === 'all' ? params.period : '7d';
+            return usage.summary({
+                scope,
+                sessionId: live.input.sessionId,
+                accountId: live.account.id,
+                projectId: live.input.projectId ?? null,
+                period,
+                timezoneOffsetMinutes: typeof params.timezoneOffsetMinutes === 'number' ? params.timezoneOffsetMinutes : 0
+            });
+        }
+        if (call === 'terminal.usage.limits') {
+            return params.refresh === true ? limits.refresh(live.account.id, { force: true }) : limits.read(live.account.id);
+        }
+        if (call === 'terminal.usage.headers') {
+            if (typeof params.provider !== 'string' || !params.provider)
+                throw invalid('A provider is required.');
+            if (typeof params.status !== 'number' || !Number.isFinite(params.status))
+                throw invalid('A response status is required.');
+            const headers = params.headers && typeof params.headers === 'object' && !Array.isArray(params.headers)
+                ? Object.fromEntries(Object.entries(params.headers).filter((entry) => typeof entry[1] === 'string'))
+                : {};
+            if (!Object.keys(headers).length)
+                return {};
+            limits.recordHeaders(live.account.id, params.provider, { status: params.status, headers });
+            return {};
+        }
+        throw invalid('Unknown usage operation.');
+    }
+    /** `/annotate:notes` and `/annotate:`: Web annotations and their visible capture browser. */
     async annotationsCall(live, call, params) {
         const root = this.options.env.root;
         const sessionId = live.input.sessionId;
@@ -578,6 +724,7 @@ export class Terminals {
             sessionId: input.sessionId,
             nativeSessionId: live.controller.nativeSessionId,
             workingDirectory: input.cwd,
+            workspaceRoot: resolveWorkspaceRoot(input.cwd),
             worktreeId: input.run?.worktreeId ?? null,
             goal: text,
             attachmentCount: 0,
@@ -586,11 +733,13 @@ export class Terminals {
             status: 'queued',
             exitCode: null,
             handoffId: null,
-            accountId: live.account.id
+            accountId: live.account.id,
+            variantScope: live.variant?.scope ?? null,
+            variantVersion: live.variant?.fingerprint ?? null
         };
     }
     /** The run a native turn reports into: the one reserved by `send`, or a new one for what the person typed. */
-    begin(live, reservedRunId, text) {
+    begin(live, reservedRunId, text, launch = {}) {
         const { root } = this.options.env;
         const { sessionId } = live.input;
         if (this.options.runs.activeForSession(sessionId))
@@ -606,63 +755,174 @@ export class Terminals {
             saveRun(root, this.runRecord(live, runId, text || null));
             copyToRun(root, live.input.sessionFolder, runId);
         }
+        if (launch.model || launch.effort) {
+            updateRun(root, runId, (record) => {
+                if (launch.model)
+                    record.model = launch.model;
+                if (launch.effort)
+                    record.effort = launch.effort;
+            });
+        }
         return this.options.runs.start(sessionId, runId);
     }
     async decide(live, run, tool, args) {
         const record = loadRun(this.options.env.root, run.runId);
         if (!isActiveStatus(record.status))
             throw invalid(`The run is no longer active (its status is ${record.status}).`);
-        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args };
+        const name = tool.toLowerCase();
+        const workspaceRoot = record.workspaceRoot ?? resolveWorkspaceRoot(record.workingDirectory ?? live.input.cwd);
+        if (live.input.readOnly && ['bash', 'edit', 'write'].includes(name))
+            return { allowed: false, reason: 'This session is read-only.', workspaceRoot };
+        let inspection;
+        try {
+            inspection = inspectRunWorkspaceWrite(record, tool, args);
+        }
+        catch (error) {
+            return { allowed: false, reason: error instanceof Error ? error.message : 'The active project workspace could not be verified.', workspaceRoot };
+        }
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args: inspection.input };
         const { policy } = this.options;
         if (policy.scope) {
-            const scope = await policy.scope(call);
+            const scope = combineWorkspaceScope(await policy.scope(call), inspection);
             if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
-                return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' };
+                return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.', workspaceRoot };
             try {
                 await policy.authorize?.(call);
             }
             catch (error) {
-                return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.' };
+                return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.', workspaceRoot };
             }
             const requiresApproval = !!scope.requiresApproval || (scope.allowed && !!scope.humanOnly);
             return {
                 allowed: scope.allowed,
                 requiresApproval,
                 reason: scope.reason ?? null,
+                workspaceRoot,
                 rememberable: scope.allowed && !scope.humanOnly,
                 ...(scope.humanOnly ? { standing: scope.allowGlobalApproval ? 'switch' : 'none' } : {})
             };
         }
-        // With no application policy: reads run, a read-only session refuses the rest, and anything else asks.
-        const name = tool.toLowerCase();
-        if (name === SESSION_NAME || name === CHECKLIST_WRITE || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name))
-            return { allowed: true };
-        if (live.input.readOnly)
-            return { allowed: false, reason: 'This session is read-only.' };
-        return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.' };
+        if (inspection.outside)
+            return { allowed: false, requiresApproval: true, rememberable: false, standing: 'switch', reason: inspection.reason, workspaceRoot };
+        if (name === SESSION_NAME || name === TODO_WRITE || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name) || ['bash', 'edit', 'write'].includes(name)) {
+            return { allowed: true, workspaceRoot };
+        }
+        return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.', workspaceRoot };
+    }
+    async workspaceEscape(live, run, tool, args, reason) {
+        if (tool !== 'bash' || live.input.readOnly)
+            return false;
+        const record = loadRun(this.options.env.root, run.runId);
+        if (!isActiveStatus(record.status) || (record.trigger != null && record.trigger !== 'user'))
+            return false;
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args };
+        const scope = (await this.options.policy.scope?.(call)) ?? { allowed: true };
+        if (scope.automatic || (!scope.allowed && !scope.requiresApproval))
+            return false;
+        try {
+            await this.options.policy.authorize?.(call);
+        }
+        catch {
+            return false;
+        }
+        const operationArgs = (args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+        const command = typeof operationArgs.command === 'string' ? operationArgs.command : '';
+        if (operationArgs.workspaceWriteScope !== 'outside' || !command)
+            return false;
+        const workspaceRoot = record.workspaceRoot ?? resolveWorkspaceRoot(record.workingDirectory ?? live.input.cwd);
+        const decision = await run.requestApproval({
+            target: 'workspace-write',
+            action: `${reason} Workspace: ${workspaceRoot}. This exact command will run once with broader filesystem access.\n\nCommand:\n${formatBashCommandForApproval(command)}`,
+            operation: { tool, args: operationArgs },
+            rememberable: false,
+            standing: 'none'
+        });
+        if (decision !== 'approved')
+            return false;
+        const currentRecord = loadRun(this.options.env.root, run.runId);
+        if (!isActiveStatus(currentRecord.status) || (currentRecord.trigger != null && currentRecord.trigger !== 'user'))
+            return false;
+        const currentCall = { run: currentRecord, caller: { ...live.caller, runId: run.runId }, tool, args: operationArgs };
+        const currentScope = (await this.options.policy.scope?.(currentCall)) ?? { allowed: true };
+        if (currentScope.automatic || (!currentScope.allowed && !currentScope.requiresApproval))
+            return false;
+        try {
+            await this.options.policy.authorize?.(currentCall);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async workspaceBoundaryBypass(live, run, tool, args) {
+        if (tool !== 'bash' || live.input.readOnly || !this.options.approvals.isAuto('pi'))
+            return false;
+        const record = loadRun(this.options.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 (typeof operationArgs.command !== 'string' || !operationArgs.command)
+            return false;
+        const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args: operationArgs };
+        try {
+            const scope = (await this.options.policy.scope?.(call)) ?? { allowed: true };
+            if (scope.automatic || (!scope.allowed && !scope.requiresApproval) || (scope.humanOnly && !scope.allowGlobalApproval))
+                return false;
+            await this.options.policy.authorize?.(call);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     async subagentsCall(live, call, params) {
         if (call === 'terminal.subagents.monitor')
             return { children: live.controller.subagentSnapshot() };
         const service = this.options.subagents;
-        if (!service || live.input.subagents === null) {
+        if ((!service || live.input.subagents === null) && call !== 'terminal.subagents.register') {
             if (call === 'terminal.subagents.tools')
                 return { tools: [] };
             throw invalid('Subagents are disabled for this terminal.');
         }
-        if (call === 'terminal.subagents.tools')
-            return { tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) };
+        if (call === 'terminal.subagents.tools') {
+            const variantDir = this.variantDirs.get(live.input.sessionId) ?? null;
+            return {
+                tools: subagentTools(service, '').map(tool => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })),
+                profiles: {
+                    normal: profileSection(this.options.env.root, live.input.cwd, variantDir).body,
+                    plan: profileSection(this.options.env.root, live.input.cwd, variantDir, true).body
+                }
+            };
+        }
         const run = live.controller.activeRun;
         if (!run)
             throw new HarnessError('run_not_active', 'This terminal has no active parent run.');
+        if (call === 'terminal.subagents.planSafe') {
+            const reason = service.planSpawnRefusal(run.runId, params.input);
+            return { allowed: reason === null, ...(reason ? { reason } : {}) };
+        }
         if (call === 'terminal.subagents.register') {
             if (!Array.isArray(params.tools) || params.tools.some((name) => typeof name !== 'string'))
                 throw invalid('Native tool names are required.');
+            if (params.plan !== undefined && typeof params.plan !== 'boolean')
+                throw invalid('plan must be a boolean.');
             const readOnly = live.input.readOnly === true;
-            const readTools = new Set([...READ_ONLY_TOOLS, SESSION_NAME, CHECKLIST_WRITE, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load']);
-            const tools = params.tools.filter((name) => !readOnly || readTools.has(name));
-            const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(live.caller, tools, live.input.cwd) : { version: 1, tools, connectors: [], contributions: [] };
-            freezeRun(this.options.env.root, run.runId, live.caller, capabilities);
+            const readTools = new Set([...READ_ONLY_TOOLS, SESSION_NAME, TODO_WRITE, SPAWN_SUBAGENT, WAIT_SUBAGENTS, 'ask_user', 'mcp_list_tools', 'mcp_call_tool', 'history_search', 'history_read', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load']);
+            const tools = [...new Set(params.tools)].filter(name => (!readOnly || readTools.has(name)) && (params.plan === true || (name !== 'ask_user' && name !== 'ask_user_question')));
+            const caller = { ...live.caller, runId: run.runId };
+            const capabilities = this.options.resolveCapabilities ? await this.options.resolveCapabilities(caller, tools, live.input.cwd) : { version: 1, tools, connectors: [], contributions: [] };
+            const variantDir = this.variantDirs.get(live.input.sessionId) ?? null;
+            const subagentProfiles = {
+                normal: profileSection(this.options.env.root, live.input.cwd, variantDir).body,
+                plan: profileSection(this.options.env.root, live.input.cwd, variantDir, true, {
+                    frozenTools: capabilities.tools,
+                    contributions: capabilities.contributions,
+                    descriptors: HARNESS_PLUGINS
+                }).body
+            };
+            freezeRun(this.options.env.root, run.runId, caller, capabilities);
+            if (!service || live.input.subagents === null)
+                return { runId: run.runId, connectors: capabilities.connectors, subagentProfiles };
             service.register({
                 run: { id: run.runId, sessionId: live.input.sessionId, mode: live.input.run?.mode ?? 'code', projectId: live.input.projectId, worktreeId: live.input.run?.worktreeId },
                 cwd: live.input.cwd, sessionDir: this.historyDir(live.input), text: '', caller: live.caller,
@@ -670,11 +930,15 @@ export class Terminals {
                 effort: typeof params.effort === 'string' ? params.effort : null,
                 launch: live.input.launch, tools: { allow: capabilities.tools, gated: capabilities.tools.filter(name => !readTools.has(name)) },
                 connections: live.input.connections === false ? false : { readOnly }, subagents: live.input.subagents,
-                variant: this.variantDirs.has(live.input.sessionId) ? { dir: this.variantDirs.get(live.input.sessionId), scope: live.input.variant && 'scope' in live.input.variant ? live.input.variant.scope ?? null : null } : null,
+                plan: params.plan === true,
+                variant: live.variant ? { dir: live.variant.dir, scope: live.variant.scope } : null,
                 capabilities
             }, live.account.id, capabilities);
-            service.restore(run.runId, params.history ?? { owners: [], receipts: [] });
-            return { runId: run.runId };
+            const history = params.history ?? { owners: [], receipts: [] };
+            service.restore(run.runId, history);
+            // Children an earlier reply left stopped, reported before the model answers.
+            const notice = await service.delivery(run.runId, history, false);
+            return { runId: run.runId, connectors: capabilities.connectors, subagentProfiles, notice };
         }
         if (call === 'terminal.subagents.verify') {
             await service.verify(run.runId, params.history);
@@ -834,16 +1098,20 @@ export class Terminals {
             if (variant)
                 this.variantDirs.set(sessionId, variant.dir);
             const worldTools = await this.worldToolNames(input, preparedAccount);
-            const launchTools = [...new Set([...(input.launch?.tools ?? []), CHECKLIST_WRITE, SESSION_NAME, ...worldTools])];
+            const ownTools = await this.ownToolNames(input, preparedAccount);
+            const launchTools = [...new Set([...(input.launch?.tools ?? []), TODO_WRITE, SESSION_NAME, ...ownTools, ...(broker ? apps.toolNames : []), ...worldTools])];
             // The profiles replace the variant's own subagent list, which they include.
             const profiles = this.options.subagents && input.subagents !== null ? profileSection(root, input.cwd, variant?.dir ?? null) : null;
             const launchSections = profiles ? [...(input.launch?.sections ?? []).filter((section) => section.id !== profiles.id), profiles] : input.launch?.sections;
-            const pack = compile(env, caller, { ...input.launch, sections: launchSections, tools: launchTools }, variant && profiles ? { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) } : variant);
+            // A terminal is a person's own session: the same standard sections a host's session has.
+            const standard = input.launch?.standard === null ? null : input.launch?.standard ?? { cwd: input.cwd };
+            const pack = compile(env, caller, { ...input.launch, standard, sections: launchSections, tools: launchTools }, variant && profiles ? { ...variant, sections: variant.sections.filter((section) => section.id !== profiles.id) } : variant);
             record(root, pack);
             mkdirSync(this.historyDir(input), { recursive: true });
             saveForSession(input.sessionFolder, pack);
             const live = {
                 input,
+                variant,
                 account: preparedAccount,
                 broker,
                 caller,
@@ -851,8 +1119,15 @@ export class Terminals {
                 controller: new TerminalController({
                     sessionId,
                     nativeSessionId: input.nativeSessionId ?? null,
-                    begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
+                    begin: ({ reservedRunId, text, model, effort }) => this.begin(live, reservedRunId, text, { model, effort }),
+                    hydrate: (owners) => this.hydrateMonitor(live, owners),
                     policy: (run, tool, args) => this.decide(live, run, tool, args),
+                    workspaceRoot: run => {
+                        const record = loadRun(this.options.env.root, run.runId);
+                        return record.workspaceRoot ?? resolveWorkspaceRoot(record.workingDirectory ?? live.input.cwd);
+                    },
+                    workspaceEscape: (run, tool, args, reason) => this.workspaceEscape(live, run, tool, args, reason),
+                    workspaceBoundaryBypass: (run, tool, args) => this.workspaceBoundaryBypass(live, run, tool, args),
                     allowToolGlobally: target => { this.options.approvals.allowTool('pi', target); },
                     native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
                     telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event }),
@@ -963,6 +1238,8 @@ export class Terminals {
                             return this.componentsCall(live, call, params);
                         if (call.startsWith('terminal.trajectory.'))
                             return this.trajectoryCall(live, call, params);
+                        if (call === 'terminal.todo')
+                            return latestTerminalTodo(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId);
                         if (call === 'terminal.permissions.get') {
                             const policy = this.options.approvals.read();
                             return { full: this.options.approvals.isAuto('pi'), globalTools: policy.globalTools.pi ?? [] };
@@ -980,11 +1257,15 @@ export class Terminals {
                                 : this.options.approvals.revokeTool('pi', params.tool);
                             return { globalTools: policy.globalTools.pi ?? [] };
                         }
+                        if (call.startsWith('terminal.usage.'))
+                            return this.usageCall(live, call, params);
                         if (call !== 'terminal.resources')
                             return live.controller.control(call, params);
                         const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, preparedAccount), install: false, caller: { projectId: input.projectId ?? null } }) ?? null;
-                        if (resourceIdentity(current) !== resourceIdentity(loading))
+                        const currentVariant = variant ? materialise(root, { dir: variant.dir, scope: variant.scope }, { trust: this.options.trust ?? null }) : null;
+                        if (resourceIdentity(current) !== resourceIdentity(loading) || (variant && (currentVariant?.fingerprint !== variant.fingerprint || JSON.stringify(currentVariant.extensionPaths) !== JSON.stringify(variant.extensionPaths)))) {
                             throw new HarnessError('terminal_resources_changed', 'Trusted resources changed since this terminal was prepared. Review /plugins and reopen the terminal to load the new selection.');
+                        }
                         return {};
                     } }
             });
@@ -993,16 +1274,17 @@ export class Terminals {
             const args = [...command.argsPrefix, '--append-system-prompt', render(env, pack)];
             if (input.model)
                 args.push('--model', input.model);
-            if (loading) {
+            {
                 // Pi's own discovery is off: the terminal loads what the harness found and nothing else.
                 args.push('--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes');
-                for (const path of [...loading.extensionPaths, ...loading.builtins, ...(variant?.extensionPaths ?? [])])
+                // The pi command's own extensions are not loaded: a host's session cannot have them (PROP-0039).
+                for (const path of [...(loading?.extensionPaths ?? []), ...(variant?.extensionPaths ?? [])])
                     args.push('--extension', path);
-                for (const path of [...(variant?.skillPaths ?? []), ...loading.skillPaths])
+                for (const path of [...(variant?.skillPaths ?? []), ...(loading?.skillPaths ?? [])])
                     args.push('--skill', path);
-                for (const path of loading.promptPaths)
+                for (const path of loading?.promptPaths ?? [])
                     args.push('--prompt-template', path);
-                for (const path of loading.themePaths)
+                for (const path of loading?.themePaths ?? [])
                     args.push('--theme', path);
             }
             // Last, so its gate sees a tool call as every other extension left it.

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

@@ -1,4 +1,4 @@
-import type { RunEvent, RunRecord } from "../sessions/contracts.js";
+import type { RunEvent, RunRecord, TodoItem } from "../sessions/contracts.js";
 export type TerminalTrajectoryRun = Pick<RunRecord, 'id' | 'mode' | 'goal' | 'startedAt' | 'endedAt' | 'status'>;
 export interface TerminalTrajectorySnapshot {
     run: TerminalTrajectoryRun;
@@ -6,5 +6,10 @@ export interface TerminalTrajectorySnapshot {
 }
 /** The native conversation file is the terminal's boundary for this read-only view. */
 export declare function listTerminalTrajectoryRuns(root: string, sessionId: string, nativeSessionId: string | null): TerminalTrajectoryRun[];
+/** The todo of the latest reply in this native conversation, for a host's /todo view. */
+export declare function latestTerminalTodo(root: string, sessionId: string, nativeSessionId: string | null): {
+    runId: string;
+    todo: TodoItem[];
+};
 /** Read a run only when it belongs to both this terminal and its current native conversation. */
 export declare function readTerminalTrajectory(root: string, sessionId: string, nativeSessionId: string | null, runId: string, afterSequence?: number): TerminalTrajectorySnapshot;

package/dist/sdk/terminal/trajectory.js

@@ -1,5 +1,6 @@
 import { notFound } from "../core/errors.js";
 import { findRun, listRuns, readEvents } from "../sessions/runStore.js";
+import { todoOf } from "../tools/todo.js";
 function summary(run) {
     return {
         id: run.id,
@@ -18,6 +19,13 @@ export function listTerminalTrajectoryRuns(root, sessionId, nativeSessionId) {
         .filter(run => run.nativeSessionId === nativeSessionId || run.trigger === 'side-question' && run.sessionId === sessionId)
         .map(summary);
 }
+/** The todo of the latest reply in this native conversation, for a host's /todo view. */
+export function latestTerminalTodo(root, sessionId, nativeSessionId) {
+    if (!nativeSessionId)
+        return { runId: '', todo: [] };
+    const run = listRuns(root, { sessionId }).find(candidate => candidate.nativeSessionId === nativeSessionId && candidate.trigger !== 'side-question');
+    return run ? { runId: run.id, todo: todoOf(readEvents(root, run.id)) } : { runId: '', todo: [] };
+}
 /** Read a run only when it belongs to both this terminal and its current native conversation. */
 export function readTerminalTrajectory(root, sessionId, nativeSessionId, runId, afterSequence) {
     if (!nativeSessionId || !Number.isSafeInteger(afterSequence ?? 0) || (afterSequence ?? 0) < 0)

package/dist/sdk/terminal/tui/annotateCommand.d.ts

@@ -1,3 +1,3 @@
 import type { AnnotateStart } from "./pages/annotatePage.js";
-/** `/plugin:annotate` accepts a page address, DevTools target, or page-bridge target. */
+/** `/annotate:annotate` accepts a page address, DevTools target, or page-bridge target. */
 export declare function parseAnnotate(argument: string): AnnotateStart | string;

package/dist/sdk/terminal/tui/annotateCommand.js

@@ -1,4 +1,4 @@
-/** `/plugin:annotate` accepts a page address, DevTools target, or page-bridge target. */
+/** `/annotate:annotate` accepts a page address, DevTools target, or page-bridge target. */
 export function parseAnnotate(argument) {
     const words = argument.trim().split(/\s+/).filter(Boolean);
     if (!words.length)
@@ -6,7 +6,7 @@ export function parseAnnotate(argument) {
     if (words[0] === '--app') {
         const endpoint = words[1];
         if (!endpoint)
-            return 'Give the app\'s DevTools address: /plugin:annotate --app http://127.0.0.1:9229';
+            return 'Give the app\'s DevTools address: /annotate:annotate --app http://127.0.0.1:9229';
         const address = /^\d+$/.test(endpoint) ? `http://127.0.0.1:${endpoint}` : endpoint;
         const name = words.slice(2).join(' ');
         return { kind: 'cdp', endpoint: address, ...(name ? { name } : {}) };
@@ -16,7 +16,7 @@ export function parseAnnotate(argument) {
         return { kind: 'bridge', ...(name ? { name } : {}) };
     }
     if (words.length > 1 || words[0].startsWith('--'))
-        return 'Use /plugin:annotate [url], /plugin:annotate --app <DevTools address>, or /plugin:annotate --bridge.';
+        return 'Use /annotate:annotate [url], /annotate:annotate --app <DevTools address>, or /annotate:annotate --bridge.';
     const url = /^[a-z][a-z0-9+.-]*:\/\//i.test(words[0]) ? words[0] : /^(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/.test(words[0]) ? `http://${words[0]}` : `https://${words[0]}`;
     return { kind: 'web', url };
 }