@robota-sdk/agent-ui-terminal 3.0.0-beta.82 → 3.0.0-beta.84

package/src/render.tsx

@@ -23,13 +23,20 @@ import type { ITerminalCapabilityOverrides } from './terminal-capabilities-conte
 import { createFocusReportingWriter } from './terminal-focus-reporting.js';
 import { TerminalHandoffController } from './terminal-handoff-controller.js';
 import { TuiInteractionChannel } from './TuiInteractionChannel.js';
+import { WireTuiChannel } from './wire-tui-channel.js';
 
+import type {
+  IAttachedSessionConnection,
+  TAttachedSessionEnd,
+} from './attached-session-connection.js';
+import type { IAttentionSource } from './attention/attention-tracker.js';
 import type { IKeybindingsSource } from './keybindings/node-keybindings-source.js';
 import type { TScreenReaderChannel } from './screen-reader-announcement.js';
 import type { IThemeRegistry } from './theme/theme-registry.js';
 import type { ITuiAppChannelPort } from './tui-app-channel-port.js';
 import type { ITuiCliAdapter } from './tui-cli-adapter.js';
 import type { ITuiInteractionChannelOptions } from './TuiInteractionChannel.js';
+import type { ITuiClientCommands } from './wire-tui-client-commands.js';
 import type {
   IAIProvider,
   IToolWithEventService,
@@ -52,6 +59,7 @@ import type {
   IPerTurnRecallConfig,
   TWorkspaceProjectAccess,
   EditCheckpointStore,
+  TInteractiveSessionOptions,
   IOrgPolicy,
   IProviderErrorGuidance,
   IProjectSettingsPath,
@@ -104,8 +112,19 @@ export interface IRenderOptions {
    * is what disabled the one check that would have caught the missing declaration.
    */
   orgPolicy?: IOrgPolicy | undefined;
-  /** Explicit authority- and permission-backed edit checkpoint capability. */
-  editCheckpointStore?: EditCheckpointStore;
+  /**
+   * Builds the authority- and permission-backed edit checkpoint store for one session; absent, no
+   * session keeps checkpoints. A factory, not a store: a session switch builds the next channel
+   * while the old session may still be finishing a turn, and a store holds one turn in progress.
+   */
+  createEditCheckpointStore?: () => EditCheckpointStore;
+  /** The host's way to build each external-event grant's verifier; absent, no grant opens. */
+  externalEventVerifierFactory?: TInteractiveSessionOptions['externalEventVerifierFactory'];
+  /**
+   * #3189: the run's grant history, handed to every session this TUI builds so a switch replays no
+   * spent token and resets no rate. DECLARED for the reason `orgPolicy` above is.
+   */
+  externalEventGrantHistory?: TInteractiveSessionOptions['externalEventGrantHistory'];
   providerOverride?: string | undefined;
   /**
    * #1844: forwarded to the session so `/provider switch` can construct the provider it switches TO.
@@ -165,6 +184,8 @@ export interface IRenderOptions {
    */
   additionalTools?: IToolWithEventService[];
   defaultTools?: readonly IToolWithEventService[];
+  /** The sandbox the shell tools run under, so the session can let a confined command skip the prompt. */
+  sandboxClient?: ICreateSessionOptions['sandboxClient'];
   commandModules?: readonly ICommandModule[];
   commandHostAdapters?: ICommandHostAdapters;
   shellExec?: TShellExecFn;
@@ -285,8 +306,11 @@ export function toChannelOptions(
       ? { userSettingsSources: options.userSettingsSources }
       : {}),
     ...(options.orgPolicy !== undefined ? { orgPolicy: options.orgPolicy } : {}),
-    ...(options.editCheckpointStore !== undefined
-      ? { editCheckpointStore: options.editCheckpointStore }
+    ...(options.externalEventVerifierFactory !== undefined
+      ? { externalEventVerifierFactory: options.externalEventVerifierFactory }
+      : {}),
+    ...(options.externalEventGrantHistory !== undefined
+      ? { externalEventGrantHistory: options.externalEventGrantHistory }
       : {}),
     ...(options.providerDefinitions ? { providerDefinitions: options.providerDefinitions } : {}),
     // CLI-076: the display model id doubles as the session's model override so `--model` actually reaches
@@ -327,6 +351,7 @@ export function toChannelOptions(
       : {}),
     ...(options.additionalTools !== undefined ? { additionalTools: options.additionalTools } : {}),
     ...(options.defaultTools !== undefined ? { defaultTools: options.defaultTools } : {}),
+    ...(options.sandboxClient !== undefined ? { sandboxClient: options.sandboxClient } : {}),
     commandModules: options.commandModules,
     commandHostAdapters: options.commandHostAdapters,
     shellExec: options.shellExec,
@@ -380,21 +405,195 @@ export async function renderApp(options: IRenderOptions): Promise<void> {
   // is the product assembly's boundary (agent-cli installs the guards via onChannelReady).
   try {
     await options.keybindingsSource?.start();
-    await renderStartedApp(options);
+    await renderStartedApp(options, (services) => ({
+      createChannel: createInProcessChannelFactory(options, services),
+    }));
+  } finally {
+    options.keybindingsSource?.dispose();
+  }
+}
+
+/**
+ * What the full TUI needs to attach to a session a host runs (a daemon) instead of building one.
+ * Only presentation options: everything else belongs to the host's session.
+ */
+export interface IRenderAttachedAppOptions extends Pick<
+  IRenderOptions,
+  | 'cwd'
+  | 'productDisplayName'
+  | 'version'
+  | 'cliAdapter'
+  | 'screenReader'
+  | 'screenReaderChannel'
+  | 'screenReaderHint'
+  | 'screenReaderPacing'
+  | 'terminalCapabilities'
+  | 'keybindingsSource'
+  | 'themeRegistry'
+  | 'reducedMotion'
+  | 'reducedMotionOverride'
+  | 'focusReporting'
+  | 'promptHistorySource'
+  | 'promptHistoryProject'
+> {
+  /** The session protocol connection; closing it belongs to the caller. */
+  readonly connection: IAttachedSessionConnection;
+  /** Shown as the session's label until the session reports its own name. */
+  readonly sessionLabel: string;
+  /** This terminal's driver id, from the attach handshake. */
+  readonly driverId: string;
+  /** Commands this terminal runs itself (`/shell`, `/theme`, ...); the host never sees them. */
+  readonly clientCommands?: ITuiClientCommands;
+  /**
+   * How this terminal is on the session: `'drive'` (the default) sends prompts and answers questions;
+   * `'observe'` only watches, and the host refuses anything else from it.
+   */
+  readonly mode?: 'drive' | 'observe';
+  /** Print the screen-reader line; false when this process already printed it. Default true. */
+  readonly announce?: boolean;
+}
+
+/**
+ * Render the full TUI on a session the terminal is attached to over the session protocol. Leaving
+ * only detaches: the session keeps running. Resolves `'user'` when the user leaves (`/exit`,
+ * Ctrl-C) and `'closed'` when the connection closed.
+ */
+export async function renderAttachedApp(
+  options: IRenderAttachedAppOptions,
+): Promise<TAttachedSessionEnd> {
+  let end: TAttachedSessionEnd = 'user';
+  let endApp: () => void = () => undefined;
+  const ended = new Promise<void>((resolve) => {
+    endApp = resolve;
+  });
+  try {
+    await options.keybindingsSource?.start();
+    await renderStartedApp(options, (services) => {
+      let channel: WireTuiChannel | undefined;
+      return {
+        // One channel for the App's life: a session switch is the host's, and the channel follows it.
+        createChannel: () =>
+          (channel ??= new WireTuiChannel({
+            connection: options.connection,
+            driverId: options.driverId,
+            sessionName: options.sessionLabel,
+            role: options.mode ?? 'drive',
+            terminalHandoff: services.terminalHandoff,
+            attention: services.attention,
+            ...(options.clientCommands !== undefined
+              ? { clientCommands: options.clientCommands, cwd: options.cwd }
+              : { clientCommands: undefined }),
+            onEnd: (reason) => {
+              end = reason;
+              endApp();
+            },
+          })),
+        requestSessionSwitch: async (sessionId) => channel?.requestSessionSwitch(sessionId),
+        ended,
+      };
+    });
   } finally {
     options.keybindingsSource?.dispose();
   }
+  return end;
+}
+
+/** Presentation options the App shell reads, whichever kind of channel it renders. */
+type TAppShellOptions = Pick<
+  IRenderOptions,
+  | 'cwd'
+  | 'productDisplayName'
+  | 'modelCommandToolPrefix'
+  | 'providerOverride'
+  | 'providerType'
+  | 'modelId'
+  | 'permissionMode'
+  | 'version'
+  | 'sessionStore'
+  | 'resumeSessionId'
+  | 'showSessionPickerOnStart'
+  | 'initialInput'
+  | 'initialInputOrigin'
+  | 'startupUpdateNotice'
+  | 'transportRegistry'
+  | 'commandHostAdapters'
+  | 'cliAdapter'
+  | 'promptHistorySource'
+  | 'promptHistoryProject'
+  | 'themeRegistry'
+  | 'reducedMotion'
+  | 'reducedMotionOverride'
+  | 'screenReader'
+  | 'screenReaderPacing'
+  | 'terminalCapabilities'
+  | 'screenReaderChannel'
+  | 'screenReaderHint'
+  | 'keybindingsSource'
+  | 'focusReporting'
+> & {
+  /** Print the screen-reader line. Default true; false when this process already printed it. */
+  readonly announce?: boolean;
+};
+
+/** Terminal-wide services a channel is built with; they outlive every channel. */
+export interface IChannelServices {
+  readonly terminalHandoff: TerminalHandoffController;
+  readonly attention: IAttentionSource;
+}
+
+/** Where the App's channels come from, and how a session switch and an app end are decided. */
+interface IAppChannelComposition {
+  readonly createChannel: (resumeSessionId?: string) => ITuiAppChannelPort;
+  /** Present when the host switches sessions and the channel follows it. */
+  readonly requestSessionSwitch?: (sessionId: string) => Promise<void>;
+  /** Settles when the app ends without the user closing it (the connection closed). */
+  readonly ended?: Promise<void>;
+}
+
+/**
+ * The in-process factory: every channel builds its own session, and its own checkpoint store, from
+ * the render options. A resumed session's store restores its active branch from the persisted pointer.
+ */
+export function createInProcessChannelFactory(
+  options: IRenderOptions,
+  services: IChannelServices,
+): (resumeSessionId?: string) => ITuiAppChannelPort {
+  // Issue #3081: the move is announced by the FIRST session only — a later switch to another
+  // session (a `/fork` attach) did not move anywhere.
+  let pendingWorkspaceMovedFrom = options.workspaceMovedFrom;
+  return (resumeSessionId) => {
+    const workspaceMovedFrom = pendingWorkspaceMovedFrom;
+    pendingWorkspaceMovedFrom = undefined;
+    const channel = new TuiInteractionChannel({
+      ...toChannelOptions(options, resumeSessionId),
+      ...(options.createEditCheckpointStore !== undefined
+        ? { editCheckpointStore: options.createEditCheckpointStore() }
+        : {}),
+      ...(workspaceMovedFrom !== undefined ? { workspaceMovedFrom } : {}),
+      terminalHandoff: services.terminalHandoff,
+      attention: services.attention,
+    });
+    // Expose each live channel (incl. session-switch re-creations) to the embedding product,
+    // e.g. for process-level error routing (ERR-001 G1).
+    options.onChannelReady?.(channel);
+    return channel;
+  };
 }
 
-async function renderStartedApp(options: IRenderOptions): Promise<void> {
+async function renderStartedApp(
+  options: TAppShellOptions,
+  compose: (services: IChannelServices) => IAppChannelComposition,
+): Promise<void> {
   // CLI-2004: one resolved boolean drives Ink's own screen-reader support AND the React context
   // every component reads. Both are set here so they can never disagree.
   const screenReader = options.screenReader === true;
-  writeScreenReaderAnnouncement({
-    enabled: screenReader,
-    channel: options.screenReaderChannel,
-    hint: options.screenReaderHint,
-  });
+  if (options.announce !== false) {
+    writeScreenReaderAnnouncement({
+      enabled: screenReader,
+      channel: options.screenReaderChannel,
+      hint: options.screenReaderHint,
+    });
+  }
   const pacing = resolvePacing({ enabled: screenReader, overrides: options.screenReaderPacing });
   // SCREEN-2670: the pre-write park. Constructed only when the mode is on AND the interval is
   // non-zero, so with the mode off `stdout` is not passed at all and Ink defaults to
@@ -436,24 +635,11 @@ async function renderStartedApp(options: IRenderOptions): Promise<void> {
 
   // Concrete framework creation has one composition boundary. React receives only the bounded port;
   // App owns which narrowed channel is active, while each channel owns its own lifecycle.
+  const composition = compose({ terminalHandoff: handoffController, attention });
   let activeChannel: ITuiAppChannelPort | undefined;
-  // Issue #3081: the move is announced by the FIRST session only — a later switch to another
-  // session (a `/fork` attach) did not move anywhere.
-  let pendingWorkspaceMovedFrom = options.workspaceMovedFrom;
   const createChannel = (resumeSessionId?: string): ITuiAppChannelPort => {
-    const workspaceMovedFrom = pendingWorkspaceMovedFrom;
-    pendingWorkspaceMovedFrom = undefined;
-    const channel = new TuiInteractionChannel({
-      ...toChannelOptions(options, resumeSessionId),
-      ...(workspaceMovedFrom !== undefined ? { workspaceMovedFrom } : {}),
-      terminalHandoff: handoffController,
-      attention,
-    });
-    // Expose each live channel (incl. session-switch re-creations) to the embedding product,
-    // e.g. for process-level error routing (ERR-001 G1).
-    options.onChannelReady?.(channel);
-    activeChannel = channel;
-    return channel;
+    activeChannel = composition.createChannel(resumeSessionId);
+    return activeChannel;
   };
 
   // The startup quiet period sits between the confirmation line and the first frame, so a reader
@@ -486,6 +672,9 @@ async function renderStartedApp(options: IRenderOptions): Promise<void> {
             <App
               cwd={options.cwd}
               createChannel={createChannel}
+              {...(composition.requestSessionSwitch !== undefined
+                ? { requestSessionSwitch: composition.requestSessionSwitch }
+                : {})}
               providerOverride={options.providerOverride}
               providerType={options.providerType}
               modelId={options.modelId}
@@ -526,6 +715,8 @@ async function renderStartedApp(options: IRenderOptions): Promise<void> {
   );
   // The controller needs the Ink instance to clear the frame before a handoff.
   handoffController.setInkInstance(instance);
+  // Unmounting resolves `waitUntilExit`, so an app the host ended leaves the way a user exit does.
+  void composition.ended?.then(() => instance.unmount());
   try {
     await waitForRenderAndStop(
       () => instance.waitUntilExit(),

package/src/short-session-id.ts

@@ -0,0 +1,9 @@
+/** Every stored session id starts with this, so it tells no two sessions apart. */
+const SESSION_ID_PREFIX = 'session_';
+const SHORT_SESSION_ID_LENGTH = 8;
+
+/** A session id short enough for a picker row or a status bar: the start of the part that differs. */
+export function shortSessionId(id: string): string {
+  const distinct = id.startsWith(SESSION_ID_PREFIX) ? id.slice(SESSION_ID_PREFIX.length) : id;
+  return distinct === '' ? id : distinct.slice(0, SHORT_SESSION_ID_LENGTH);
+}

package/src/slash-command-input.ts

@@ -0,0 +1,11 @@
+/** A typed `/name args` line, split the way every TUI channel dispatches it. */
+export interface ISlashCommandInput {
+  /** Lower-cased, without the slash. */
+  readonly name: string;
+  readonly args: string;
+}
+
+export function parseSlashCommandInput(input: string): ISlashCommandInput {
+  const parts = input.slice(1).split(/\s+/);
+  return { name: parts[0]?.toLowerCase() ?? '', args: parts.slice(1).join(' ') };
+}

package/src/tui-app-channel-port.ts

@@ -14,7 +14,11 @@ import type {
   IExecutionDetailPage,
   IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
-import type { IInteractiveSessionEvents, IToolState } from '@robota-sdk/agent-interface-session';
+import type {
+  IInteractiveSessionEvents,
+  ISessionListingEntry,
+  IToolState,
+} from '@robota-sdk/agent-interface-session';
 
 export interface ITuiCommandQueryPort {
   getCommands(filter?: string): ICommand[];
@@ -33,6 +37,8 @@ export interface ITuiRuntimeStatusSnapshot {
   sessionId: string;
   activePresetId?: string;
   effort?: TModelEffortSelection;
+  /** The model the session reports, when its host says; absent ⇒ the one this terminal was started with. */
+  modelId?: string;
 }
 
 export interface ITuiChannelSnapshot {
@@ -52,6 +58,28 @@ export interface ITuiChannelSnapshot {
   permissionRequest: IPendingPermissionRequest | null;
   pendingUserAction: IActionRequest | null;
   contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  /**
+   * The sessions the session picker offers, when the host keeps them (a terminal attached to a
+   * daemon). Absent ⇒ the picker lists this terminal's own session store. A host that keeps sessions
+   * live says which rows run now and how many clients are on each; the picker shows both.
+   */
+  hostSessions?: readonly ISessionListingEntry[];
+  /**
+   * Changes when the transcript starts over for another session while the App keeps this channel.
+   * The terminal prints the transcript once and counts what it printed, so a new transcript is
+   * printed from its start. Absent ⇒ the transcript never starts over under this channel.
+   */
+  transcriptGeneration?: number;
+  /**
+   * True while this terminal only observes the session: it sends nothing that changes it, and the
+   * App offers no key that would. Absent ⇒ the terminal drives the session.
+   */
+  readOnly?: boolean;
+  /**
+   * True when this terminal is attached to a session a host runs: leaving only detaches it, and
+   * Ctrl-] leaves too. Absent ⇒ the terminal runs its own session, where Ctrl-] means nothing.
+   */
+  attached?: boolean;
 }
 
 /**

package/src/tui-channel-options.ts

@@ -20,6 +20,7 @@ import type {
   ICreateSessionOptions,
   ILivePromptTracePort,
   EditCheckpointStore,
+  TInteractiveSessionOptions,
   IMemoryStore,
   IPromptHistoryOptions,
   IPerTurnRecallConfig,
@@ -79,8 +80,15 @@ export interface ITuiInteractionChannelOptions {
   contributionSources?: ICreateSessionOptions['contributionSources'];
   skillRoots?: ICreateSessionOptions['skillRoots'];
   userSettingsSources?: readonly INodeHostSettingsSource[];
-  /** Explicit authority- and permission-backed edit checkpoint capability. */
+  /**
+   * Explicit authority- and permission-backed edit checkpoint capability for this channel's one
+   * session. Never shared with another channel's session: a store holds one turn in progress.
+   */
   editCheckpointStore?: EditCheckpointStore;
+  /** The host's way to build each external-event grant's verifier; absent, no grant opens. */
+  externalEventVerifierFactory?: TInteractiveSessionOptions['externalEventVerifierFactory'];
+  /** The run's grant history, shared by every session this TUI binds (#3189). */
+  externalEventGrantHistory?: TInteractiveSessionOptions['externalEventGrantHistory'];
   /**
    * CLI-076: the resolved model id (the same value the status line displays). Forwarded to the session so an
    * explicit `--model` override reaches the provider chat call instead of being silently replaced by the
@@ -106,7 +114,6 @@ export interface ITuiInteractionChannelOptions {
   /** Issue #3081: this channel's session is the target of a `/cd` from this directory. */
   workspaceMovedFrom?: string;
   sessionName?: string;
-  onAutoNamed?: (name: string) => void;
   backgroundTaskRunners?: IBackgroundTaskRunner[];
   /** MCP-004: forwarded to `ICreateSessionOptions.toolCallHandoff`. */
   toolCallHandoff?: IToolCallHandoffPolicy;
@@ -122,6 +129,8 @@ export interface ITuiInteractionChannelOptions {
    */
   additionalTools?: IToolWithEventService[];
   defaultTools?: readonly IToolWithEventService[];
+  /** The sandbox the shell tools run under, so the session can let a confined command skip the prompt. */
+  sandboxClient?: ICreateSessionOptions['sandboxClient'];
   commandModules?: readonly ICommandModule[];
   commandHostAdapters?: ICommandHostAdapters;
   shellExec?: TShellExecFn;

package/src/tui-interaction-queues.ts

@@ -1,6 +1,9 @@
 import type { IPendingPermissionRequest } from './types.js';
 import type { IActionRequest, TActionResponse, TToolArgs } from '@robota-sdk/agent-core';
-import type { TPermissionResultValue } from '@robota-sdk/agent-interface-session';
+import type {
+  TPermissionRequester,
+  TPermissionResultValue,
+} from '@robota-sdk/agent-interface-session';
 
 interface IUserActionQueueEntry {
   presentedRequest: IActionRequest;
@@ -13,6 +16,8 @@ interface IPermissionQueueEntry {
   toolArgs: TToolArgs;
   canPersistProjectPermission?: boolean;
   requestedByPeer?: string;
+  /** Issue #3288 §1: a background agent's own request, forwarded to the person. */
+  requester?: TPermissionRequester;
   resolve: (result: TPermissionResultValue) => void;
   id?: string;
 }
@@ -96,6 +101,7 @@ export class TuiPermissionQueue {
     id?: string,
     canPersistProjectPermission?: boolean,
     requestedByPeer?: string,
+    requester?: TPermissionRequester,
   ): Promise<TPermissionResultValue> {
     return new Promise<TPermissionResultValue>((resolve) => {
       this.entries.push({
@@ -105,6 +111,7 @@ export class TuiPermissionQueue {
         ...(id !== undefined ? { id } : {}),
         ...(canPersistProjectPermission !== undefined ? { canPersistProjectPermission } : {}),
         ...(requestedByPeer !== undefined ? { requestedByPeer } : {}),
+        ...(requester !== undefined ? { requester } : {}),
       });
       this.processNext();
     });
@@ -149,6 +156,7 @@ export class TuiPermissionQueue {
         ? { canPersistProjectPermission: next.canPersistProjectPermission }
         : {}),
       ...(next.requestedByPeer !== undefined ? { requestedByPeer: next.requestedByPeer } : {}),
+      ...(next.requester !== undefined ? { requester: next.requester } : {}),
       resolve: (result) => {
         if (this.entries[0] !== next) return;
         this.entries.shift();

package/src/tui-session-event-projector.ts

@@ -13,19 +13,21 @@ import type {
   IExecutionResult,
   IInteractiveSessionEvents,
   TInteractiveEventName,
+  TPermissionRequester,
   TPermissionResultValue,
 } from '@robota-sdk/agent-interface-session';
 
 export interface ITuiSessionEventProjectorOptions {
   session: InteractiveSession;
   manager: TuiStateManager;
-  onUserMessage: (content: string) => void;
   requestPermission: (
     toolName: string,
     toolArgs: TToolArgs,
     id: string,
     canPersistProjectPermission?: boolean,
     requestedByPeer?: string,
+    /** Issue #3288 §1: a background agent's own request, forwarded to the person. */
+    requester?: TPermissionRequester,
   ) => Promise<TPermissionResultValue>;
   askUser: (request: IActionRequest, id: string) => Promise<TActionResponse>;
   dismissPrompt: (id: string) => void;
@@ -45,7 +47,6 @@ export class TuiSessionEventProjector {
     const { session, manager, attention } = this.options;
 
     const onUserMessage = (content: string): void => {
-      this.options.onUserMessage(content);
       manager.addUserEcho(attributedUserEcho(content, session));
     };
     const syncHistory = (): void => manager.syncHistory(session.getFullHistory());
@@ -88,6 +89,7 @@ export class TuiSessionEventProjector {
       toolArgs,
       canPersistProjectPermission,
       requesterDriverId,
+      requester,
     }) => {
       attention?.onNeedsInput();
       // A peer turn's ask names the peer, printed only as a plain identifier.
@@ -95,7 +97,14 @@ export class TuiSessionEventProjector {
         ? printablePeerDriver(requesterDriverId)
         : undefined;
       void this.options
-        .requestPermission(toolName, toolArgs, id, canPersistProjectPermission, requestedByPeer)
+        .requestPermission(
+          toolName,
+          toolArgs,
+          id,
+          canPersistProjectPermission,
+          requestedByPeer,
+          requester,
+        )
         .then((result) => session.resolvePermission(id, result))
         .catch(() => session.resolvePermission(id, false));
     };

package/src/tui-session-events.ts

@@ -35,6 +35,12 @@ export const TUI_SESSION_EVENT_CLASSIFICATION = {
   ui_intent: 'react-side-effect',
   session_renamed: 'react-side-effect',
   history_cleared: 'channel',
+  // #3189: a host's session slot emits it on a switch; the TUI switches by remounting its own
+  // channel onto the next session, so it never follows a slot.
+  session_switched: 'non-surface',
+  // A host forwards it to attached clients as `session_status`; this channel owns its session and
+  // reads the status from it on each render.
+  status_changed: 'non-surface',
 } as const satisfies Record<TInteractiveEventName, TTuiSessionEventClassification>;
 
 export interface ITuiSessionEventNotice {

package/src/tui-session-options.ts

@@ -55,6 +55,12 @@ export function buildTuiSessionOptions(
     ...(opts.editCheckpointStore !== undefined
       ? { editCheckpointStore: opts.editCheckpointStore }
       : {}),
+    ...(opts.externalEventVerifierFactory !== undefined
+      ? { externalEventVerifierFactory: opts.externalEventVerifierFactory }
+      : {}),
+    ...(opts.externalEventGrantHistory !== undefined
+      ? { externalEventGrantHistory: opts.externalEventGrantHistory }
+      : {}),
     // CLI-076: forward the resolved model so `--model` takes effect rather than falling through to the
     // session's config/default model.
     ...(opts.model !== undefined ? { model: opts.model } : {}),
@@ -80,6 +86,8 @@ export function buildTuiSessionOptions(
       ? { workspaceMovedFrom: opts.workspaceMovedFrom }
       : {}),
     sessionName: opts.sessionName,
+    // The session names itself after its first real turn, unless it already has a name.
+    autoName: true,
     backgroundTaskRunners: opts.backgroundTaskRunners,
     ...(opts.toolCallHandoff !== undefined ? { toolCallHandoff: opts.toolCallHandoff } : {}),
     subagentRunnerFactory: opts.subagentRunnerFactory,
@@ -90,6 +98,7 @@ export function buildTuiSessionOptions(
     ...(opts.pluginDirectories !== undefined ? { pluginDirectories: opts.pluginDirectories } : {}),
     ...(opts.additionalTools !== undefined ? { additionalTools: opts.additionalTools } : {}),
     ...(opts.defaultTools !== undefined ? { defaultTools: opts.defaultTools } : {}),
+    ...(opts.sandboxClient !== undefined ? { sandboxClient: opts.sandboxClient } : {}),
     commandModules: opts.commandModules,
     commandHostAdapters: opts.commandHostAdapters,
     shellExec: opts.shellExec,

package/src/tui-state-manager.ts

@@ -130,8 +130,14 @@ export class TuiStateManager {
   };
 
   onToolEnd = (state: IToolState): void => {
-    // findLastIndex: when same tool runs concurrently, match the most recently started instance
-    const idx = this.activeTools.findLastIndex((t) => t.toolName === state.toolName && t.isRunning);
+    // #3288: attribute by executionId first — two same-named parallel calls can finish out of
+    // start order, and `findLastIndex` by name alone would close the wrong (most recently
+    // started, not most recently finished) running entry. Fall back to the name+running-order
+    // heuristic only when the event carries no executionId (legacy fixtures / old hosts).
+    const idx =
+      state.executionId !== undefined
+        ? this.activeTools.findIndex((t) => t.executionId === state.executionId && t.isRunning)
+        : this.activeTools.findLastIndex((t) => t.toolName === state.toolName && t.isRunning);
     if (idx !== -1) {
       const updated = [...this.activeTools];
       updated[idx] = state;
@@ -163,7 +169,7 @@ export class TuiStateManager {
     this.notify();
   };
 
-  onComplete = (result: IExecutionResult): void => {
+  onComplete = (result: Pick<IExecutionResult, 'contextState'>): void => {
     this.clearStallTimer();
     this.debouncedStreamNotify.flush();
     this.streamBuf = '';
@@ -215,6 +221,21 @@ export class TuiStateManager {
    */
   syncHistory(entries: IHistoryEntry[]): void {
     if (entries.length === 0) return;
+    this.history = this.withLocalNotices(entries);
+    this.notify();
+  }
+
+  /**
+   * A host's history as a terminal attached to it last read it, then the echoes of prompts the host
+   * has not recorded yet. Unlike `syncHistory`, an empty history is an answer: the host's session
+   * has no entries.
+   */
+  syncHostHistory(entries: readonly IHistoryEntry[], echoes: readonly IHistoryEntry[]): void {
+    this.history = [...this.withLocalNotices(entries), ...echoes];
+    this.notify();
+  }
+
+  private withLocalNotices(entries: readonly IHistoryEntry[]): IHistoryEntry[] {
     // `<Static>` counts what it already printed, so a local notice dropped here would shift every
     // later index by one and the next committed entry (the assistant's answer) would never print.
     const merged: IHistoryEntry[] = [];
@@ -225,8 +246,7 @@ export class TuiStateManager {
       merged.push(notice.entry);
     }
     while (next < entries.length) merged.push(entries[next++]!);
-    this.history = merged;
-    this.notify();
+    return merged;
   }
 
   /** Add a notice this terminal owns; it survives the next session-history sync in place. */

package/src/types.ts

@@ -1,7 +1,7 @@
 /** UI-layer permission types for the Ink TUI */
 
 import type { TToolArgs } from '@robota-sdk/agent-core';
-import type { TPermissionResultValue } from '@robota-sdk/agent-interface-session';
+import type { TPermissionRequester, TPermissionResultValue } from '@robota-sdk/agent-interface-session';
 
 /**
  * Permission result: true (allow once), false (deny), 'allow-session' (remember for session),
@@ -15,5 +15,7 @@ export interface IPendingPermissionRequest {
   canPersistProjectPermission?: boolean;
   /** The peer session whose message this call serves, when a peer turn asked. */
   requestedByPeer?: string;
+  /** Issue #3288 §1: a background agent's own request, forwarded to the person. */
+  requester?: TPermissionRequester;
   resolve: (result: TPermissionResult) => void;
 }