@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/terminal/subagentMonitor.js

@@ -1,3 +1,4 @@
+import { usagePayloadSchema } from "../sessions/contracts.js";
 export const ACTIVE_SUBAGENT_STATUSES = new Set(['queued', 'running', 'waiting_for_approval', 'waiting_for_input']);
 export function terminalSubagentDuration(activity, now = Date.now()) {
     const start = Date.parse(activity.startedAt);
@@ -41,7 +42,7 @@ function stringOf(value) {
 function latestTool(tools) {
     return [...tools.values()].sort((left, right) => right.sequence - left.sequence)[0]?.text;
 }
-/** Volatile, read-only activity projection for the active terminal parent run. */
+/** Volatile, read-only activity projection for the latest terminal parent run. */
 export class SubagentMonitor {
     parentRunId = null;
     activities = new Map();
@@ -64,12 +65,22 @@ export class SubagentMonitor {
             activity: statusActivity(run.status),
             checklist: null,
             profile: run.profile ?? null,
+            accountLabel: run.accountLabel ?? null,
+            model: run.model ?? null,
+            effort: run.effort ?? null,
+            usage: null,
             tools: new Map(),
             lastTool: null
         };
         row.parentRunId = run.parentRunId;
         if (run.profile !== undefined)
             row.profile = run.profile;
+        if (run.accountLabel !== undefined)
+            row.accountLabel = run.accountLabel;
+        if (run.model !== undefined && !row.usage?.model)
+            row.model = run.model;
+        if (run.effort !== undefined)
+            row.effort = run.effort;
         row.title = run.title;
         row.goal = run.goal;
         row.status = run.status;
@@ -94,6 +105,26 @@ export class SubagentMonitor {
             row.lastTool = null;
             row.activity = 'Responding';
         }
+        else if (event.type === 'usage.updated') {
+            const parsed = usagePayloadSchema.safeParse(payload);
+            if (parsed.success) {
+                const usage = parsed.data;
+                row.usage = {
+                    ...(usage.provider === undefined ? {} : { provider: usage.provider }),
+                    ...(usage.model === undefined ? {} : { model: usage.model }),
+                    ...(usage.inputTokens === undefined ? {} : { inputTokens: usage.inputTokens }),
+                    ...(usage.outputTokens === undefined ? {} : { outputTokens: usage.outputTokens }),
+                    ...(usage.cacheReadTokens === undefined ? {} : { cacheReadTokens: usage.cacheReadTokens }),
+                    ...(usage.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: usage.cacheWriteTokens }),
+                    ...(usage.reasoningTokens === undefined ? {} : { reasoningTokens: usage.reasoningTokens }),
+                    ...(usage.costUsd === undefined ? {} : { costUsd: usage.costUsd }),
+                    ...(usage.costSource === undefined ? {} : { costSource: usage.costSource }),
+                    ...(usage.requests === undefined ? {} : { requests: usage.requests }),
+                    ...(usage.contextTokens === undefined ? {} : { contextTokens: usage.contextTokens }),
+                    ...(usage.contextWindow === undefined ? {} : { contextWindow: usage.contextWindow })
+                };
+            }
+        }
         else if (event.type === 'checklist.updated') {
             const items = Array.isArray(payload.items) ? payload.items : [];
             row.checklist = items.length ? { done: items.filter(item => item?.status === 'completed').length, total: items.length } : null;

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

@@ -22,6 +22,8 @@ import type { World } from "../world/world.js";
 import type { Worktrees } from "../worktrees/service.js";
 import type { AnnotationCapture } from "../annotations/capture.js";
 import type { NoteDeliveries } from "../annotations/delivery.js";
+import type { Usage } from "../usage/service.js";
+import type { UsageLimits } from "../usage/limits/service.js";
 /** The files a terminal session needs on disk, outside this process. */
 export interface TerminalAssets {
     /** The Node binary that runs the commands. */
@@ -103,6 +105,10 @@ export interface TerminalsOptions {
     noteCapture?: AnnotationCapture;
     /** Page notes on their way to a session (PROP-0018). */
     pageNotes?: NoteDeliveries;
+    /** Usage analytics over the derived ledger (`/usage:analysis`). */
+    usage?: Usage;
+    /** Provider plan windows, balances and rate limits (`/usage:limit`). */
+    usageLimits?: UsageLimits;
 }
 /** What `/plugins` in a terminal can do. Each takes the session's folder, account and project. */
 export interface PluginControl {
@@ -147,10 +153,17 @@ export declare class Terminals {
     constructor(options: TerminalsOptions);
     /** The commands a terminal session finds on PATH. Rewritten only when they change. */
     private ensureCommands;
-    /** 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).
+     */
     private tools;
+    private readonly ownNames;
+    private ownTools;
     /** The world tools a new session will have, named in its instructions. */
     private worldToolNames;
+    /** The harness's own History, Wiki and skill tools a new session will have. */
+    private ownToolNames;
     /** Whether a world tool's plugin is switched on for a session's folder, account and project. */
     private worldOn;
     private appsCall;
@@ -169,7 +182,9 @@ export declare class Terminals {
     private agentsCall;
     /** `/worktree`: the managed worktrees of the repository this session works in. */
     private worktreesCall;
-    /** `/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. */
+    private usageCall;
+    /** `/annotate:notes` and `/annotate:`: Web annotations and their visible capture browser. */
     private annotationsCall;
     /** The account a session asked to switch to. Taken once, after its Pi process has ended and before `dispose`. */
     takeRelaunch(sessionId: string): TerminalRelaunch | null;
@@ -179,6 +194,8 @@ export declare class Terminals {
     /** The run a native turn reports into: the one reserved by `send`, or a new one for what the person typed. */
     private begin;
     private decide;
+    private workspaceEscape;
+    private workspaceBoundaryBypass;
     private subagentsCall;
     private componentsCall;
     private trajectoryCall;

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";
@@ -21,7 +23,13 @@ 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 { combineWorkspaceScope, inspectRunWorkspaceWrite } from "../sessions/workspaceBoundary.js";
 import { CHECKLIST_WRITE } from "../tools/checklist.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";
@@ -108,7 +116,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 ?? null,
+                        effort: settings?.effort ?? null
+                    });
                     break;
                 }
                 parentId = parent.parentRunId;
@@ -153,23 +166,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 +219,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 +251,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 +510,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 +675,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,7 +684,9 @@ 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. */
@@ -612,57 +712,151 @@ export class Terminals {
         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 === CHECKLIST_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 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: [] };
+            freezeRun(this.options.env.root, run.runId, caller, capabilities);
+            if (!service || live.input.subagents === null)
+                return { runId: run.runId, connectors: capabilities.connectors };
             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 +864,12 @@ 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 };
+            return { runId: run.runId, connectors: capabilities.connectors };
         }
         if (call === 'terminal.subagents.verify') {
             await service.verify(run.runId, params.history);
@@ -834,16 +1029,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 ?? []), CHECKLIST_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,
@@ -853,6 +1052,12 @@ export class Terminals {
                     nativeSessionId: input.nativeSessionId ?? null,
                     begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
                     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 }),
@@ -980,11 +1185,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 +1202,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/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 };
 }

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

@@ -1,11 +1,13 @@
 import type { TerminalPage } from "./page.js";
 import type { TerminalCommandHost } from "./commands.js";
 import { type AnnotateStart } from "./pages/annotatePage.js";
-export type CommandPageId = 'doctor' | 'accounts' | 'permissions' | 'plugins' | 'hub' | 'components' | 'settings' | 'trajectory' | 'log' | 'harness' | 'skills' | 'connections' | 'tools' | 'worktree' | 'notes' | 'annotate' | 'subagents' | 'agents';
+export type CommandPageId = 'doctor' | 'accounts' | 'permissions' | 'plugins' | 'hub' | 'components' | 'settings' | 'trajectory' | 'log' | 'harness' | 'skills' | 'connections' | 'tools' | 'worktree' | 'notes' | 'annotate' | 'subagents' | 'agents' | 'usage';
 /** Construct one independent full-screen page for a slash command. */
 export declare function createCommandPage(host: TerminalCommandHost, id: CommandPageId, options?: {
     runId?: string;
     url?: string;
     annotate?: AnnotateStart;
+    usageTab?: 'analysis' | 'limit';
+    usagePeriod?: 'today' | '7d' | '30d' | 'all';
     close?(): void;
 }): TerminalPage;

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

@@ -10,12 +10,15 @@ import { NotesPage } from "./pages/notesPage.js";
 import { AnnotatePage } from "./pages/annotatePage.js";
 import { SubagentsPage } from "./pages/subagentsPage.js";
 import { AgentsPage } from "./pages/agentsPage.js";
+import { UsagePage } from "./pages/usagePage.js";
 import { createSettingsModel } from "./settingsModel.js";
 /** Construct one independent full-screen page for a slash command. */
 export function createCommandPage(host, id, options = {}) {
     const theme = () => host.ui.theme;
     const notify = (message, type) => host.ui.notify(message, type === 'error' || type === 'warning' ? type : 'info');
     switch (id) {
+        case 'usage':
+            return new UsagePage({ theme, call: host.control, changed: host.changed, initialTab: options.usageTab === 'limit' ? 'limits' : 'analysis', ...(options.usagePeriod ? { initialPeriod: options.usagePeriod } : {}) });
         case 'doctor':
             return new DoctorPage({ theme, call: host.control, confirm: host.ui.confirm.bind(host.ui), select: host.ui.select.bind(host.ui), changed: host.changed,
                 selection: () => {