@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/hooks/useNumberedSelection.ts

@@ -0,0 +1,76 @@
+/**
+ * CLI-2004 — the typed-number input wiring shared by every numbered menu.
+ *
+ * The reducer lives in `flows/selection-flow.ts` (one owner of "what is selected"); this hook is the
+ * Ink adapter around it, so six components get the same behaviour without six copies of the same
+ * `useInput` block. Inactive when the mode is off, so the arrow-key handlers keep the terminal.
+ */
+
+import { useInput } from 'ink';
+import { useCallback, useRef, useState } from 'react';
+
+import {
+  applyNumericSelection,
+  createNumericSelectionState,
+  type INumericSelectionState,
+} from '../flows/selection-flow.js';
+
+export interface IUseNumberedSelectionInputs {
+  /** Screen-reader mode. Off ⇒ the hook reads nothing. */
+  enabled: boolean;
+  itemCount: number;
+  cancellable?: boolean;
+  /** A checklist: a number toggles a row, the menu stays open, and an empty Enter commits. */
+  multi?: boolean;
+  /** Keep a single-row selection open so the user can select another row later. */
+  repeatable?: boolean;
+  onSelect: (index: number) => void;
+  onCancel?: () => void;
+  /** Required with `multi` — what an empty Enter commits. */
+  onConfirm?: () => void;
+}
+
+export interface INumberedSelection {
+  buffer: string;
+  invalid: boolean;
+  clear: () => void;
+}
+
+/** Read a typed selection for a numbered list. */
+export function useNumberedSelection(inputs: IUseNumberedSelectionInputs): INumberedSelection {
+  const [state, setState] = useState<INumericSelectionState>(createNumericSelectionState);
+  const stateRef = useRef(state);
+  const { enabled, itemCount, cancellable, multi, repeatable, onSelect, onCancel, onConfirm } = inputs;
+
+  const clear = useCallback((): void => {
+    const empty = createNumericSelectionState();
+    stateRef.current = empty;
+    setState(empty);
+  }, []);
+
+  const handle = useCallback(
+    (input: string, key: Parameters<typeof applyNumericSelection>[2]): void => {
+      const result = applyNumericSelection(stateRef.current, input, key, {
+        itemCount,
+        ...(cancellable === true ? { cancellable: true } : {}),
+        ...(multi === true ? { multi: true } : {}),
+        ...(repeatable === true ? { repeatable: true } : {}),
+      });
+      stateRef.current = result.state;
+      setState(result.state);
+      if (result.effect.type === 'select') onSelect(result.effect.index);
+      else if (result.effect.type === 'cancel') onCancel?.();
+      else if (result.effect.type === 'confirm') onConfirm?.();
+    },
+    [itemCount, cancellable, multi, repeatable, onSelect, onCancel, onConfirm],
+  );
+
+  useInput(
+    (input, key) => {
+      handle(input, key);
+    },
+    { isActive: enabled },
+  );
+
+  return { buffer: state.buffer, invalid: state.invalid, clear };
+}

package/src/hooks/usePluginCallbacks.ts

@@ -0,0 +1,38 @@
+/**
+ * Hook: uses the host plugin adapter, or an explicit unsupported adapter when none is provided.
+ *
+ * A missing host capability must fail visibly. Returning successful no-ops would make the plugin
+ * screen claim mutations succeeded while changing nothing.
+ */
+
+import { useMemo } from 'react';
+
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+function unsupported(): Promise<never> {
+  return Promise.reject(new Error('Plugin management is unavailable in this host.'));
+}
+
+function createUnsupportedPluginAdapter(): ICommandPluginAdapter {
+  return {
+    listInstalled: unsupported,
+    listAvailablePlugins: unsupported,
+    install: unsupported,
+    uninstall: unsupported,
+    enable: unsupported,
+    disable: unsupported,
+    marketplaceAdd: unsupported,
+    marketplaceRemove: unsupported,
+    marketplaceUpdate: unsupported,
+    marketplaceList: unsupported,
+    reloadPlugins: unsupported,
+  };
+}
+
+export function resolvePluginCallbacks(adapter?: ICommandPluginAdapter): ICommandPluginAdapter {
+  return adapter ?? createUnsupportedPluginAdapter();
+}
+
+export function usePluginCallbacks(adapter?: ICommandPluginAdapter): ICommandPluginAdapter {
+  return useMemo(() => resolvePluginCallbacks(adapter), [adapter]);
+}

package/src/hooks/usePluginScreenData.ts

@@ -0,0 +1,85 @@
+/**
+ * Hook: fetch data for PluginTUI screens.
+ * Extracted from PluginTUI.tsx for single-responsibility.
+ */
+
+import { useState, useEffect } from 'react';
+
+import type { IMenuSelectItem } from '../MenuSelect.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+export function usePluginScreenData(
+  screen: string,
+  marketplace: string | undefined,
+  callbacks: ICommandPluginAdapter,
+  refreshCounter: number,
+  stackLength: number,
+): { items: IMenuSelectItem[]; loading: boolean; error: string | undefined } {
+  const [items, setItems] = useState<IMenuSelectItem[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | undefined>();
+
+  useEffect(() => {
+    setItems([]);
+    setError(undefined);
+
+    if (screen === 'marketplace-list') {
+      setLoading(true);
+      callbacks
+        .marketplaceList()
+        .then((sources) => {
+          const baseItems: IMenuSelectItem[] = [{ label: 'Add Marketplace', value: '__add__' }];
+          const sourceItems: IMenuSelectItem[] = sources.map((s) => ({
+            label: s.name,
+            value: s.name,
+            hint: s.type,
+          }));
+          setItems([...baseItems, ...sourceItems]);
+          setLoading(false);
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        });
+    } else if (screen === 'marketplace-browse') {
+      const mp = marketplace ?? '';
+      setLoading(true);
+      callbacks
+        .listAvailablePlugins(mp)
+        .then((plugins) => {
+          setItems(
+            plugins.map((p) => ({
+              label: p.name,
+              value: p.name,
+              hint: p.installed ? 'installed' : p.description,
+            })),
+          );
+          setLoading(false);
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        });
+    } else if (screen === 'installed-list') {
+      setLoading(true);
+      callbacks
+        .listInstalled()
+        .then((plugins) => {
+          setItems(
+            plugins.map((p) => ({
+              label: p.name,
+              value: p.name,
+              hint: p.description,
+            })),
+          );
+          setLoading(false);
+        })
+        .catch((err) => {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        });
+    }
+  }, [stackLength, screen, marketplace, callbacks, refreshCounter]);
+
+  return { items, loading, error };
+}

package/src/hooks/useRealCursorPosition.ts

@@ -0,0 +1,125 @@
+/**
+ * CLI-062 — position the REAL terminal cursor at the CJK composition point.
+ *
+ * Mechanism (contract: .design/investigations/2026-07-25-cli-062-ime-cursor-design.md, POC-PASS):
+ * the input box's absolute frame-space origin comes from walking the yoga `parentNode` chain from
+ * a `<Box ref>` (the `5195e326b` approach, minus its debug logging); the cell is handed to ink's
+ * `useCursor().setCursorPosition`, which converts it into a relative `cursorUp` from the frame
+ * bottom INSIDE the same atomic synchronized frame write (invariant I3: never out-of-band — all
+ * cursor movement rides ink's ≤30fps frame writes; this hook itself writes NOTHING to any stream,
+ * the PoC row-accounting lesson).
+ *
+ * Measurement happens post-commit (layout is valid there) and is stored in state so the NEXT
+ * commit's insertion effect propagates a fresh position with its frame; `useBoxMetrics` provides
+ * the layout-change subscription so sibling-driven moves re-measure too. A stale origin self-heals
+ * within one frame (ink recomputes layout before onRender and notifies layout listeners).
+ */
+
+import { useBoxMetrics, useCursor, useWindowSize } from 'ink';
+import { useEffect, useState } from 'react';
+
+import { computeCursorCell, shouldPositionRealCursor } from '../flows/real-cursor-flow.js';
+
+import type { DOMElement } from 'ink';
+import type { RefObject } from 'react';
+
+export interface IUseRealCursorPositionOptions {
+  /** Ref attached to the `<Box>` wrapping the input's text. */
+  boxRef: RefObject<DOMElement | null>;
+  /** Capability + focus gate: supportsImeCursorPositioning() && focus && showCursor. */
+  enabled: boolean;
+  /** Live input value (from the input's state ref — fresh at render time). */
+  value: string;
+  /** Live cursor character index. */
+  cursor: number;
+  /** Wrap width in columns (matches the input's own wrap math). */
+  availableWidth?: number;
+}
+
+export interface IUseRealCursorPositionResult {
+  /** True while the hardware cursor is being positioned — the drawn cursor must be suppressed. */
+  realCursorActive: boolean;
+}
+
+interface IMeasuredOrigin {
+  x: number;
+  y: number;
+  frameHeight: number;
+}
+
+/** Walk the yoga `parentNode` chain to the absolute frame-space origin, plus the root frame height. */
+function measureAbsoluteOrigin(element: DOMElement): IMeasuredOrigin | undefined {
+  if (element.yogaNode === undefined) return undefined;
+  let x = 0;
+  let y = 0;
+  let current: DOMElement | undefined = element;
+  let root: DOMElement = element;
+  while (current !== undefined) {
+    const layout = current.yogaNode?.getComputedLayout();
+    x += layout?.left ?? 0;
+    y += layout?.top ?? 0;
+    root = current;
+    current = current.parentNode;
+  }
+  const frameHeight = root.yogaNode?.getComputedLayout().height ?? 0;
+  return { x, y, frameHeight };
+}
+
+function sameOrigin(a: IMeasuredOrigin | undefined, b: IMeasuredOrigin | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.x === b.x && a.y === b.y && a.frameHeight === b.frameHeight;
+}
+
+export function useRealCursorPosition(
+  options: IUseRealCursorPositionOptions,
+): IUseRealCursorPositionResult {
+  const { setCursorPosition } = useCursor();
+  // Layout-change subscription: useBoxMetrics re-renders this component whenever the tracked
+  // box's metrics change on a root layout commit, and exposes hasMeasured for invariant I1.
+  const metrics = useBoxMetrics(options.boxRef);
+  const { rows: viewportRows } = useWindowSize();
+  const [origin, setOrigin] = useState<IMeasuredOrigin | undefined>(undefined);
+
+  // I1: never a guessed row — measure the absolute origin ONLY from a committed yoga layout
+  // (post-commit effect; ink ran calculateLayout before onRender, passive effects run after).
+  // No dependency array on purpose: any render may follow a layout change, and the setState
+  // bails out when the origin is unchanged, so this settles instead of looping.
+  useEffect(() => {
+    const element = options.boxRef.current;
+    const next = element === null ? undefined : measureAbsoluteOrigin(element);
+    setOrigin((previous) => (sameOrigin(previous, next) ? previous : next));
+  });
+
+  const cell =
+    origin !== undefined && options.enabled
+      ? computeCursorCell({
+          absX: origin.x,
+          absY: origin.y,
+          value: options.value,
+          cursor: options.cursor,
+          ...(options.availableWidth !== undefined
+            ? { availableWidth: options.availableWidth }
+            : {}),
+        })
+      : undefined;
+
+  const realCursorActive =
+    cell !== undefined &&
+    origin !== undefined &&
+    shouldPositionRealCursor({
+      hasMeasured: metrics.hasMeasured, // I1 — `origin` is already narrowed non-undefined above
+      y: cell.y,
+      frameHeight: origin.frameHeight, // I2 checked inside the guard
+      viewportRows,
+      capability: options.enabled, // I5 folded in via supportsImeCursorPositioning()
+    });
+
+  // Render-phase call is safe: useCursor only records the position in a ref; propagation happens
+  // in its insertion effect, inside ink's synchronized frame write (I3). I4: when the guard fails
+  // (blur, fullscreen frame, not measured yet) we pass `undefined` — ink hides the hardware cursor
+  // and the caller falls back to today's drawn-cursor rendering; on unmount, useCursor's cleanup
+  // propagates `undefined` by itself.
+  setCursorPosition(realCursorActive && cell !== undefined ? { x: cell.x, y: cell.y } : undefined);
+
+  return { realCursorActive };
+}

package/src/hooks/useRenderMarkdown.ts

@@ -0,0 +1,38 @@
+import { renderMarkdown } from '../render-markdown.js';
+import { useScreenReader } from '../screen-reader-context.js';
+import { useSyntaxHighlighting, useTheme } from '../theme/index.js';
+
+import type { IRenderMarkdownOptions } from '../render-markdown.js';
+
+/** What a call site still decides. The three appearance inputs are no longer among them. */
+export type TRenderMarkdownExtras = Omit<
+  IRenderMarkdownOptions,
+  'theme' | 'syntaxHighlighting' | 'screenReader'
+>;
+
+/**
+ * SCREEN-2002 — markdown rendered with this surface's resolved appearance.
+ *
+ * The three inputs every render site needs — the theme, the syntax-highlighting setting and
+ * screen-reader mode — are bound here instead of at each call. That is a deliberate removal of an
+ * obligation rather than a convenience.
+ *
+ * The obligation was forgotten once and guarded four times. `/theme syntax off` shipped persisting
+ * a setting no call site passed, so the command reported success and changed nothing; each guard
+ * written afterwards measured a PROXY for "every call site passes it" — the prop appears in the
+ * file, the file matched the regex, the identifier occurs N times — and each held for exactly one
+ * review round. A binding removes the thing being proxied: there is no per-call-site argument left
+ * to forget, and the floor collapses to a single-consumer ratchet (nothing outside this module
+ * imports `renderMarkdown`), which is a property rather than a proxy for one.
+ *
+ * Screen-reader mode is bound too, uniformly. `StreamingIndicator` previously omitted it, which was
+ * correct but only incidentally: it returns its collapsed line before reaching any markdown, so the
+ * flag never applied. Binding it removes that coincidence as something a reader has to reconstruct.
+ */
+export function useRenderMarkdown(): (md: string, extras?: TRenderMarkdownExtras) => string {
+  const theme = useTheme();
+  const syntaxHighlighting = useSyntaxHighlighting();
+  const screenReader = useScreenReader();
+  return (md, extras = {}) =>
+    renderMarkdown(md, { ...extras, theme, syntaxHighlighting, screenReader });
+}

package/src/hooks/useScreenReaderTurnSignals.ts

@@ -0,0 +1,113 @@
+/**
+ * CLI-2004 — the non-visual half of a turn: the bell and the OSC 133 boundary marks.
+ *
+ * Both are byte-stream events, not rendering, so they live in a hook rather than a component: the
+ * App says WHEN a turn starts, ends, or wants an answer, and this decides what reaches the terminal.
+ * When the mode is off both writers are inert, so the App has exactly one code path.
+ *
+ * One turn emits `A` (prompt start) → `B` (prompt end) → `C` (turn start) → `D` (turn end): the
+ * prompt is marked while the user is being asked for input, and the execution pair brackets the
+ * agent's work. That is the boundary a reader jumps between.
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+
+import { createAttentionBell } from '../attention-bell.js';
+import { useScreenReaderPacing } from '../screen-reader-pacing-context.js';
+import { supportsTurnMarks } from '../terminal-capabilities.js';
+import { useTerminalCapabilityOverrides } from '../terminal-capabilities-context.js';
+import { createTurnMarkWriter } from '../terminal-marks.js';
+
+import type { IAttentionBell } from '../attention-bell.js';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+export interface IUseScreenReaderTurnSignalsInputs {
+  enabled: boolean;
+  /** The agent is working (a turn is in flight). */
+  isThinking: boolean;
+  /** Tools currently reported as active by the session. */
+  activeTools: readonly IToolState[];
+  /** A permission ask or user-action dialog is mounted and waiting for an answer. */
+  awaitingAnswer: boolean;
+}
+
+/**
+ * Stable key for one tool run within a turn.
+ *
+ * `executionId` where the session supplies one; otherwise the position, which `onToolEnd` preserves
+ * (it replaces the entry at its index rather than removing it).
+ */
+function toolKey(tool: IToolState, index: number): string {
+  return tool.executionId ?? `${tool.toolName}#${index}`;
+}
+
+/** The keys of the tools currently RUNNING — not merely present in the array. */
+function runningKeys(activeTools: readonly IToolState[]): Set<string> {
+  const running = new Set<string>();
+  activeTools.forEach((tool, index) => {
+    if (tool.isRunning) running.add(toolKey(tool, index));
+  });
+  return running;
+}
+
+/** Wire the bell and the turn marks to the App's turn lifecycle. */
+export function useScreenReaderTurnSignals(inputs: IUseScreenReaderTurnSignalsInputs): void {
+  const { enabled, isThinking, activeTools, awaitingAnswer } = inputs;
+  const bell = useMemo<IAttentionBell>(() => createAttentionBell({ enabled }), [enabled]);
+  // SCREEN-2670: the marks are POSITIONAL — the terminal records the line they arrive on — so they
+  // travel through the owned write path, ordered with the commit they belong to. Outside a provider
+  // the port writes to the process's own stdout, which is exactly today's path.
+  const pacing = useScreenReaderPacing();
+  const terminalCapabilities = useTerminalCapabilityOverrides();
+  const marks = useMemo(
+    () =>
+      createTurnMarkWriter({
+        enabled,
+        supported: () => supportsTurnMarks({ override: terminalCapabilities.turnMarks }),
+        write: (text) => pacing.write(text),
+      }),
+    [enabled, pacing, terminalCapabilities.turnMarks],
+  );
+  const wasThinking = useRef(false);
+  const runningTools = useRef<ReadonlySet<string>>(new Set());
+
+  // Turn boundaries: B/C when work starts, D/A when it ends and the prompt comes back.
+  useEffect(() => {
+    if (isThinking && !wasThinking.current) {
+      marks.emit('promptEnd');
+      marks.emit('turnStart');
+    } else if (!isThinking && wasThinking.current) {
+      marks.emit('turnEnd');
+      marks.emit('promptStart');
+      bell.replyCompleted();
+    }
+    wasThinking.current = isThinking;
+  }, [isThinking, bell, marks]);
+
+  // The very first prompt of the session is marked once, before anything has been asked.
+  useEffect(() => {
+    marks.emit('promptStart');
+  }, [marks]);
+
+  // A prompt or dialog that wants an answer rings once on mount.
+  useEffect(() => {
+    if (awaitingAnswer) bell.promptMounted();
+  }, [awaitingAnswer, bell]);
+
+  // Long-running tools: record each start, ring on the completions that outlived the threshold.
+  //
+  // Completion is the `isRunning` true→false transition, NOT the entry leaving the array. The
+  // session's `onToolEnd` replaces the finished entry in place (same index, same name, so the same
+  // key) and only `onThinking(false)` empties the array — so a membership test would report every
+  // tool as completing at turn end, judging its duration against the whole turn.
+  useEffect(() => {
+    const running = runningKeys(activeTools);
+    for (const key of running) {
+      if (!runningTools.current.has(key)) bell.toolStarted(key);
+    }
+    for (const key of runningTools.current) {
+      if (!running.has(key)) bell.toolCompleted(key);
+    }
+    runningTools.current = running;
+  }, [activeTools, bell]);
+}

package/src/hooks/useSideEffects.ts

@@ -0,0 +1,144 @@
+/**
+ * CMD-004 Phase 2 Stage C — the TUI as a pure renderer.
+ *
+ * The session layer (the host) executes every command host action via `ICommandHostAdapters`
+ * BEFORE the command result returns (language change, settings reset, exit/restart, rename,
+ * statusline patch, remote control — see `interactive-session-host-actions.ts`). This hook only:
+ *
+ * 1. renders the four UI screens from the requester-routed `ui_intent` session event
+ *    (`show-plugin-manager` / `show-settings` / `show-session-picker` / `show-agent-switcher`) —
+ *    the surface that issued the command renders the intent; intents stamped with another
+ *    surface's driver id (or unattributed) are ignored;
+ * 2. reflects the broadcast `session_renamed` event into the rendered title (the host performed
+ *    the rename — the TUI never mutates the session);
+ * 3. refreshes the statusline display after a slash-command result arrives by RE-READING the
+ *    persisted settings (refresh-on-result — the host applied any patch via the settings adapter).
+ */
+
+import { OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-session';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+
+import type { IUseSideEffectsOptions, IUseSideEffectsResult } from './side-effects-types.js';
+import type { ITuiSessionUiEventPort } from '../tui-app-channel-port.js';
+import type { ISessionRenamedEvent, IUiIntentEvent } from '@robota-sdk/agent-interface-session';
+
+interface IUiEventHandlers {
+  setSessionName: (name: string) => void;
+  refreshStatusLineSettings: () => void;
+  /** SCREEN-2002: re-read the persisted appearance after a slash command may have patched it. */
+  refreshAppearanceSettings: () => void;
+  openAgentSwitcher?: (() => void) | undefined;
+}
+
+interface IScreenSetters {
+  setShowPluginTUI: (show: boolean) => void;
+  setShowTransportTUI: (show: boolean) => void;
+  setShowSessionPicker: (show: boolean) => void;
+  setShowThemePicker: (show: boolean) => void;
+}
+
+/** Subscribe to `ui_intent` (requester-routed) + `session_renamed` (broadcast); returns cleanup. */
+function subscribeToSessionUiEvents(
+  uiEventPort: ITuiSessionUiEventPort,
+  screens: IScreenSetters,
+  handlersRef: { current: IUiEventHandlers },
+): () => void {
+  const onUiIntent = (event: IUiIntentEvent): void => {
+    // Requester-routed: this surface is the local operator (OWNER_DRIVER_ID). Intents issued by
+    // other surfaces — or unattributed ones — are theirs to render, not ours.
+    if (event.requesterDriverId !== OWNER_DRIVER_ID) return;
+    switch (event.intent.type) {
+      case 'show-plugin-manager':
+        screens.setShowPluginTUI(true);
+        return;
+      case 'show-settings':
+        screens.setShowTransportTUI(true);
+        return;
+      case 'show-session-picker':
+        screens.setShowSessionPicker(true);
+        return;
+      case 'show-agent-switcher':
+        handlersRef.current.openAgentSwitcher?.();
+        return;
+      case 'show-theme-picker':
+        screens.setShowThemePicker(true);
+        return;
+    }
+  };
+  const onSessionRenamed = (event: ISessionRenamedEvent): void => {
+    handlersRef.current.setSessionName(event.name);
+  };
+  uiEventPort.on('ui_intent', onUiIntent);
+  uiEventPort.on('session_renamed', onSessionRenamed);
+  return () => {
+    uiEventPort.off('ui_intent', onUiIntent);
+    uiEventPort.off('session_renamed', onSessionRenamed);
+  };
+}
+
+/**
+ * Latest-callback refs so the session subscription binds exactly once per session: App recreates
+ * some callbacks every render, and re-subscribing on each identity change would churn listeners.
+ */
+function useLatestHandlers(handlers: IUiEventHandlers): { current: IUiEventHandlers } {
+  const ref = useRef(handlers);
+  ref.current = handlers;
+  return ref;
+}
+
+export function useSideEffects({
+  uiEventPort,
+  baseHandleSubmit,
+  setSessionName,
+  refreshStatusLineSettings,
+  refreshAppearanceSettings,
+  showSessionPickerOnStart,
+  openAgentSwitcher,
+}: IUseSideEffectsOptions): IUseSideEffectsResult {
+  const [showPluginTUI, setShowPluginTUI] = useState(false);
+  const [showSessionPicker, setShowSessionPicker] = useState(showSessionPickerOnStart ?? false);
+  const [showTransportTUI, setShowTransportTUI] = useState(false);
+  const [showThemePicker, setShowThemePicker] = useState(false);
+
+  const handlersRef = useLatestHandlers({
+    setSessionName,
+    refreshStatusLineSettings,
+    refreshAppearanceSettings,
+    openAgentSwitcher,
+  });
+
+  useLayoutEffect(
+    () =>
+      subscribeToSessionUiEvents(
+        uiEventPort,
+        { setShowPluginTUI, setShowTransportTUI, setShowSessionPicker, setShowThemePicker },
+        handlersRef,
+      ),
+    [uiEventPort],
+  );
+
+  const handleSubmit = useCallback(
+    async (input: string): Promise<void> => {
+      await baseHandleSubmit(input);
+      // Refresh-on-result: a slash command's result has arrived; the host may have patched the
+      // persisted statusline settings — re-read them for the status bar.
+      if (input.trimStart().startsWith('/')) {
+        handlersRef.current.refreshStatusLineSettings();
+        handlersRef.current.refreshAppearanceSettings();
+      }
+    },
+    [baseHandleSubmit],
+  );
+
+  return {
+    handleSubmit,
+    showPluginTUI,
+    showSessionPicker,
+    showTransportTUI,
+    showThemePicker,
+    setShowPluginTUI,
+    setShowSessionPicker,
+    setShowTransportTUI,
+    setShowThemePicker,
+  };
+}

package/src/hooks/useStatusLineSettings.ts

@@ -0,0 +1,50 @@
+import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
+import { useCallback, useState } from 'react';
+
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+import type { IStatusLineCommandSettings } from '@robota-sdk/agent-interface-command';
+
+function readStatusLineSettings(
+  settings: Record<string, TUniversalValue>,
+): IStatusLineCommandSettings {
+  const defaults = { ...DEFAULT_STATUS_LINE_COMMAND_SETTINGS };
+  const raw = settings.statusline;
+  if (!isRecord(raw)) {
+    return defaults;
+  }
+  return {
+    enabled: typeof raw.enabled === 'boolean' ? raw.enabled : defaults.enabled,
+    gitBranch: typeof raw.gitBranch === 'boolean' ? raw.gitBranch : defaults.gitBranch,
+  };
+}
+
+function isRecord(value: TUniversalValue): value is Record<string, TUniversalValue> {
+  return (
+    value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
+  );
+}
+
+function readFromAdapter(cliAdapter: ITuiCliAdapter): IStatusLineCommandSettings {
+  return readStatusLineSettings(cliAdapter.readSettings(cliAdapter.getUserSettingsPath()));
+}
+
+/**
+ * Statusline settings as persisted on disk, plus a from-disk `refresh()`.
+ *
+ * CMD-004 Phase 2 Stage C: the HOST applies `statusline-settings-patch` via the settings adapter
+ * (the TUI no longer writes settings), so the renderer refreshes by RE-READING the persisted
+ * document when a command result arrives (refresh-on-result).
+ */
+export function useStatusLineSettings(): [IStatusLineCommandSettings, () => void] {
+  const cliAdapter = useTuiCliAdapter();
+  const [settings, setSettings] = useState<IStatusLineCommandSettings>(() =>
+    readFromAdapter(cliAdapter),
+  );
+  const refresh = useCallback((): void => {
+    setSettings(readFromAdapter(cliAdapter));
+  }, [cliAdapter]);
+  return [settings, refresh];
+}