pi-sessions 0.18.1 → 0.19.0

package/README.md

@@ -68,8 +68,9 @@ Open the frontend implementation task in a session to the right.
 | ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------- |
 | Session Search     | `session_search` pi tool                                               | Search through old sessions                             |
 | Session Ask        | `session_ask` pi tool                                                  | Ask questions about old sessions                        |
-| Session Handoff    | `session_handoff` pi tool, `/handoff` board                            | Start and manage focused child sessions                 |
-| Session Messaging  | `session_reachable`, `session_send_message`, `session_cancel` pi tools | Coordinate between live Pi sessions and own subagents   |
+| Session Handoff    | `session_handoff` pi tool, `/handoff` board                            | Start user-facing child sessions                        |
+| Session Messaging  | `session_reachable`, `session_send_message`, `session_cancel` pi tools | Coordinate between live user-facing Pi sessions          |
+| Subagents          | `subagent_list`, `subagent_send`, `subagent_cancel`, `subagent_launch`, `submit_task_report` | Delegate and manage background work |
 | Session Picker     | `Alt+O`                                                                | Reference old sessions in your prompt                   |
 | Session Index      | `/session-index` slash command                                         | Shows index status and rebuilds the local session index |
 | Session Auto Title | in background, `/title` slash command                                  | Give sessions titles                                    |
@@ -107,34 +108,44 @@ Use `kind: "user"` or `kind: "subagent"` to filter by session type across the wh
 
 ## Session Handoff
 
-The `session_handoff` tool lets the agent create a child session with a self-contained task. Ask for a direction when you want a visible split, ask for a deferred handoff when you only want the prepared session, or let the agent delegate suitable independent work to a background subagent.
+The `session_handoff` tool creates a user-facing child session with a self-contained task. Ask for a direction when you want a visible split, or a deferred handoff when you only want the prepared session. Use `subagent_launch` to delegate suitable independent work to a background subagent.
 
 Directional launches use tmux when the current terminal is inside tmux, or Ghostty on macOS. Deferred launches create the child without starting it and copy its resume command to the clipboard. A background subagent runs in a detached tmux window and reports back when finished; note that subagents are started with `--approve`, meaning pi will always start in the directory as trusted.
 
-When an external host registers, its name replaces all directional launch values, even inside tmux or Ghostty. Deferred and subagent launches remain available. External-host children start automatically without draft review; their resume commands also carry `--approve`.
+When a host claims peers, pi-sessions leaves all user-facing coordination and launches to it. Subagent tools remain available; external-host launch targets are not part of pi-sessions.
 
-Run `/handoff` to open the **Handoffs** board. The Subagents and User sessions tabs show status, age, launch details, and the actions currently available: stop, copy an observation command, or copy a resume command.
+Run `/handoff` to open the **Handoffs** board. The Subagents and User sessions tabs show status, age, launch details, and the actions currently available: stop, copy an observation command, or copy a resume command. With a peer-claiming host, only Subagents are shown.
+
+Both launch tools take `goal`, `title` (at most 64 characters), and `requestResponse`, with optional `cwd`, `provider`, `model`, and `thinkingLevel` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). `session_handoff` additionally requires `launch` (`left`, `right`, `up`, `down` when a split backend is available, or `deferred` when enabled). `subagent_launch` has no `launch` parameter. Provider and model must be supplied together.
 
 ## Session Messaging
 
-Agents can coordinate with live Pi sessions and their own subagents:
+Standalone agents can coordinate with live user-facing Pi sessions:
+
+- `session_reachable({})` lists live user sessions only; there is no scope parameter
+- `session_send_message({ session, message, requestResponse })` sends a message to a live user session
+- `session_cancel({ session })` aborts another live user session's current turn
+
+Subagent coordination is a separate addressable directory:
 
-- `session_reachable` lists the sessions this session can send messages to
-- `session_send_message` sends a message to a live session or own subagent
-- `session_cancel` aborts another live session's current turn
+- `subagent_list({ scope? })` lists the ledger/roster with `branch` (default) or `tree` scope
+- `subagent_send({ session, message, requestResponse })` sends to a live subagent (including siblings) or a dormant owned worker, waking owned workers automatically
+- `subagent_cancel({ session })` stops a subagent, recording owned cancellation intent before teardown
+- `subagent_launch` creates a delegated background worker (parameters above)
+- `submit_task_report({ status, summary, details?, references?, nextSteps? })` reports to the parent; available only in a subagent session
 
-Incoming messages start the recipient agent when idle and steer it when already running. Messaging a dormant owned subagent or a dormant session listed by a wake-capable host resumes it automatically. Hosted sessions appear in `session_reachable` with a `host` field and a broker-derived `live`, `starting`, or `dormant` state. Other inactive sessions cannot receive messages, but you can still use `session_search` and `session_ask` with them.
+Pass bare session UUIDs, not `@session:` tokens. A subagent cannot message or cancel its parent; it reports through `submit_task_report`. Incoming messages start an idle recipient and steer a running one. Other dormant sessions cannot receive messages, but remain searchable with `session_search` and `session_ask`. Cancellation results describe delivery and, when available, the resulting worker state; they do not expose transport/managed subsystem tags.
 
-## Host extension API (v1)
+## Host extension API
 
-A host controls where user-facing handoff children run. Built-in hosts launch tmux splits, Ghostty splits, or deferred resume commands. External extensions register over `pi.events`; neither extension imports the other.
+A host claims ownership of peer coordination, rather than supplying launch, listing, or wake callbacks. External extensions register over `pi.events`; neither extension imports the other.
 
 Install a listener during extension initialization, **not** in your `session_start` handler:
 
 ```ts
-pi.events.on("pi-sessions:hosts:v1", (request) => {
+pi.events.on("pi-sessions:hosts", (request) => {
   const { register } = request as HostRegistrationRequest;
-  register({ name: "swb", launch, listSessions, wake });
+  register({ name: "swb", peers: true });
 });
 ```
 
@@ -147,37 +158,30 @@ interface HostRegistrationRequest {
 
 interface Host {
   name: string;
-  launch(input: HostLaunchInput): Promise<HostLaunchResult>;
-  listSessions?(): Promise<HostSession[]>;
-  wake?(sessionId: string): Promise<void>;
+  peers: true;
 }
+```
 
-interface HostLaunchInput {
-  sessionId: string;
-  sessionFile: string;
-  cwd: string;
-  title: string;
-  model: string;
-  resumeCommand: string;
-}
+- **Registration:** pi-sessions emits `pi-sessions:hosts` at every `session_start`, including reloads and switches. Register synchronously before returning or awaiting anything. Registration freezes when `emit` returns; late calls throw. Names must match `[a-z][a-z0-9-]*`, be unique, and cannot be `left`, `right`, `up`, `down`, `deferred`, `subagent`, `tmux`, or `ghostty`. TypeBox validates exactly `{ name, peers: true }`; additional properties are rejected.
+- **Ownership:** any registered claim suppresses pi-sessions' `session_reachable`, `session_send_message`, `session_cancel`, and `session_handoff`. Peer tools are never registered at extension load, so a host may register its own tools at load without conflicts. Discovery runs before late registration. Pi currently has no tool-unregistration API: definitions retained from a prior standalone session are deactivated with `setActiveTools` and execution-guarded; reload rebuilds registrations. A new standalone session reactivates pi-sessions' tools.
+- **Subagents:** `subagent_list`, `subagent_send`, `subagent_cancel`, `subagent_launch`, and `submit_task_report` remain pi-sessions-owned under a host. Availability still follows feature settings, tmux installation, delegation depth, and whether the caller is a subagent. The host supplies no waker; owned-worker recovery retains its two 30-second broker-registration waits.
 
-type HostLaunchResult =
-  | { success: true; clipboardStatus?: "copied" | "failed" }
-  | { success: false; error: string };
+## Durable lineage entry
 
-interface HostSession {
-  sessionId: string;
-  cwd: string;
-  title: string;
+Any extension may append this custom entry to a child session:
+
+```ts
+{
+  type: "custom",
+  customType: "pi-sessions.lineage",
+  data: {
+    parentSessionId: "parent-session-uuid",
+    parentSessionFile: "/absolute/path/to/parent.jsonl", // optional
+  },
 }
 ```
 
-- **Registration:** pi-sessions emits `pi-sessions:hosts:v1` at each `session_start`, including reloads and session switches. Call `register` synchronously, before returning or awaiting anything. Registration freezes when `emit` returns; late calls throw. Names must match `[a-z][a-z0-9-]*`, be unique, and cannot be `left`, `right`, `up`, `down`, `deferred`, `subagent`, `tmux`, or `ghostty`. Registration and callback results are validated with TypeBox. Multiple external hosts are offered in registration order; any external host suppresses all split targets. Without one, precedence remains tmux, then Ghostty, then deferred. Subagent availability still depends on tmux installation and delegation depth.
-- **Launch:** the child file, lineage, title, and automatic bootstrap are durable before `launch` runs. External-host children always use Pi's default session directory for `cwd`, even when the parent uses a custom directory. Start interactive Pi in that cwd with `--session-id`, `--approve`, and `--model` using the supplied `model` (including its thinking suffix, such as `provider/model:high`), or execute `resumeCommand`. Preserve the same Pi agent directory and load pi-sessions in the child. Do not inject a second initial prompt. Return `{ success: true }` after starting the process; return `{ success: false, error }` or throw on failure. The tool surfaces the surviving child's resume command on failure. `clipboardStatus` is used by the deferred host; external hosts normally omit it.
-- **Discovery:** `listSessions()` returns all open user-facing sessions this host can wake, whether running or dormant. Exclude closed sessions and subagents. It is called on demand by `session_reachable` and dormant-message routing, not polled in the background. Return unique session IDs; competing host ownership is an error. Hosts without both `listSessions` and `wake` do not contribute dormant reachability. `wake` without `listSessions` is invalid.
-- **Wake:** `wake(sessionId)` starts or resumes an owned session and resolves with no value; throw on failure. It must be idempotent across callers because different Pi processes can wake the same target concurrently. Within one sender, concurrent wakes are coalesced. After it resolves, pi-sessions waits **30 seconds** for broker registration before delivering. It retries wake/delivery once if the target disconnects before acceptance, but does not restart a host session on registration timeout. The broker alone supplies liveness; do not wait for broker readiness inside `wake`. Host callbacks have no imposed timeout: bound your own I/O. Built-in split launch commands use a 15-second timeout; subagent stale-window recovery retains two 30-second registration waits.
-
-Subagents are not hosts. They retain parent-owned tmux windows, automatic approval, their own ledger, and their own wake/recovery policy. `/handoff` remains a receipt board; it accepts external-host launch receipts but does not provide a separate launch picker or wake action.
+Using Pi's extension API, call `pi.appendEntry("pi-sessions.lineage", { parentSessionId, parentSessionFile? })` in the child (Pi supplies the entry id, timestamp, and tree link). The index uses the first TypeBox-valid lineage entry only when the session header has no `parentSession`; the header takes precedence. The parent id works even without an accessible parent file. This durable relation survives leaving a host; the SQLite index is only its rebuildable cache.
 
 ## Session picker
 
@@ -213,7 +217,7 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
 
 `roster` limits which models a handoff may launch a child session on. Defaults to pi's own `enabledModels` scoping, then to all configured models. May optionally include a thinking level; listing a model more than once adds to the levels it allows.
 
-`deferred.enable` (default `true`) offers the `deferred` launch. Turn it off, along with `sessions.subagents.enable`, to leave only host and split launches.
+`deferred.enable` (default `true`) offers the `deferred` peer launch. Turn it off to leave only split launches. Hosts own their own launch policy.
 
 `deferred.copyToClipboard` (default `true`) controls whether deferred handoffs copy the resume command to the clipboard. When off, the resume command is only shown in the tool call.
 

package/extensions/hosts/contract.ts

@@ -1,51 +1,15 @@
 import { type Static, Type } from "typebox";
 
-export const HOSTS_CHANNEL = "pi-sessions:hosts:v1";
-
-export const HOST_LAUNCH_INPUT_SCHEMA = Type.Object({
-  sessionId: Type.String({ minLength: 1 }),
-  sessionFile: Type.String({ minLength: 1 }),
-  cwd: Type.String({ minLength: 1 }),
-  title: Type.String(),
-  model: Type.String({ minLength: 1 }),
-  resumeCommand: Type.String({ minLength: 1 }),
-});
-
-export const HOST_LAUNCH_RESULT_SCHEMA = Type.Union([
-  Type.Object({
-    success: Type.Literal(true),
-    clipboardStatus: Type.Optional(Type.Union([Type.Literal("copied"), Type.Literal("failed")])),
-  }),
-  Type.Object({ success: Type.Literal(false), error: Type.String() }),
-]);
-
-export const HOST_SESSION_SCHEMA = Type.Object({
-  sessionId: Type.String({ minLength: 1 }),
-  cwd: Type.String({ minLength: 1 }),
-  title: Type.String(),
-});
-
-export const HOST_SCHEMA = Type.Object({
-  name: Type.String({ pattern: "^[a-z][a-z0-9-]*$" }),
-  launch: Type.Function([HOST_LAUNCH_INPUT_SCHEMA], Type.Unknown()),
-  listSessions: Type.Optional(Type.Function([], Type.Unknown())),
-  wake: Type.Optional(Type.Function([Type.String()], Type.Unknown())),
-});
-
-export type HostLaunchInput = Static<typeof HOST_LAUNCH_INPUT_SCHEMA>;
-export type HostLaunchResult = Static<typeof HOST_LAUNCH_RESULT_SCHEMA>;
-export type HostSession = Static<typeof HOST_SESSION_SCHEMA>;
-export interface Host {
-  name: string;
-  launch(input: HostLaunchInput): Promise<HostLaunchResult>;
-  listSessions?(): Promise<HostSession[]>;
-  wake?(sessionId: string): Promise<void>;
-}
-
-export interface HostedSession extends HostSession {
-  host: string;
-}
-
+export const HOSTS_CHANNEL = "pi-sessions:hosts";
+export const HOST_SCHEMA = Type.Object(
+  {
+    name: Type.String({ pattern: "^[a-z][a-z0-9-]*$" }),
+    peers: Type.Literal(true),
+  },
+  { additionalProperties: false },
+);
+
+export type Host = Static<typeof HOST_SCHEMA>;
 export interface HostRegistrationRequest {
   register(host: Host): void;
 }

package/extensions/hosts/registry.ts

@@ -1,15 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import { parseTypeBoxValue } from "../shared/typebox.ts";
-import {
-  HOST_LAUNCH_RESULT_SCHEMA,
-  HOST_SCHEMA,
-  HOST_SESSION_SCHEMA,
-  HOSTS_CHANNEL,
-  type Host,
-  type HostedSession,
-  type HostLaunchInput,
-} from "./contract.ts";
+import { HOST_SCHEMA, HOSTS_CHANNEL, type Host } from "./contract.ts";
 
 const RESERVED_NAMES = new Set([
   "left",
@@ -39,46 +30,7 @@ export class HostRegistry {
             if (RESERVED_NAMES.has(host.name) || hosts.some((entry) => entry.name === host.name)) {
               throw new Error(`Host name is reserved or already registered: ${host.name}`);
             }
-            if (host.wake && !host.listSessions) {
-              throw new Error(`Host ${host.name}: wake requires listSessions.`);
-            }
-            const name = host.name;
-            const launch = host.launch.bind(host);
-            const listSessions = host.listSessions?.bind(host);
-            const wake = host.wake?.bind(host);
-            hosts.push(
-              Object.freeze({
-                name,
-                async launch(input: HostLaunchInput) {
-                  return parseTypeBoxValue(
-                    HOST_LAUNCH_RESULT_SCHEMA,
-                    await launch(input),
-                    `Host ${name} launch result`,
-                  );
-                },
-                ...(listSessions
-                  ? {
-                      listSessions: async () =>
-                        parseTypeBoxValue(
-                          Type.Array(HOST_SESSION_SCHEMA),
-                          await listSessions(),
-                          `Host ${name} sessions`,
-                        ),
-                    }
-                  : {}),
-                ...(wake
-                  ? {
-                      async wake(target: string) {
-                        parseTypeBoxValue(
-                          Type.Void(),
-                          await wake(target),
-                          `Host ${name} wake result`,
-                        );
-                      },
-                    }
-                  : {}),
-              }),
-            );
+            hosts.push(Object.freeze({ ...host }));
           } catch (error) {
             registrationError = error;
             throw error;
@@ -97,33 +49,7 @@ export class HostRegistry {
     return this.hosts;
   }
 
-  async listSessions(): Promise<HostedSession[]> {
-    const sessions = await Promise.all(
-      this.hosts.map(async (host) => {
-        if (!host.wake || !host.listSessions) return [];
-        return (await host.listSessions()).map((session) => ({ ...session, host: host.name }));
-      }),
-    );
-    const result = sessions.flat();
-    const ids = new Set<string>();
-    for (const session of result) {
-      if (ids.has(session.sessionId))
-        throw new Error(`Multiple hosts claim session ${session.sessionId}.`);
-      ids.add(session.sessionId);
-    }
-    return result;
-  }
-
-  async owns(target: string): Promise<boolean> {
-    return (await this.listSessions()).some((session) => session.sessionId === target);
-  }
-
-  async wake(target: string): Promise<void> {
-    const hosts = this.hosts;
-    const session = (await this.listSessions()).find((session) => session.sessionId === target);
-    if (this.hosts !== hosts) throw new Error("The host registry changed while waking a session.");
-    const host = hosts.find((host) => host.name === session?.host);
-    if (!host?.wake) throw new Error(`No host can wake session ${target}.`);
-    await host.wake(target);
+  claimsPeers(): boolean {
+    return this.hosts.length > 0;
   }
 }

package/extensions/pi-sessions.ts

@@ -9,18 +9,15 @@ import { installAutoTitle } from "./session-auto-title/install.ts";
 import { installHandoff } from "./session-handoff/install.ts";
 import { installHooks } from "./session-hooks/install.ts";
 import { installIndex } from "./session-index/install.ts";
+import { createPeerDirectory, createSubagentDirectory } from "./session-messaging/directory.ts";
 import { installMessaging } from "./session-messaging/install.ts";
-import { MessageRouter, type SessionWaker } from "./session-messaging/message-router.ts";
-import { createSessionReachableTool } from "./session-messaging/pi/reachable-tool.ts";
-import {
-  createSessionCancelTool,
-  createSessionSendMessageTool,
-} from "./session-messaging/pi/tools.ts";
+import { MessageRouter } from "./session-messaging/message-router.ts";
+import { installDirectoryTools } from "./session-messaging/pi/install.ts";
 import { installSearch } from "./session-search/install.ts";
 import type { SessionLifecycle } from "./shared/composition.ts";
 import { createSessionModelRuntime, type ModelRuntimeProvider } from "./shared/model-runtime.ts";
 import { loadSettings, readCompactionSettings } from "./shared/settings.ts";
-import { installSubagents } from "./subagents/install.ts";
+import { installSubagents, type SubagentsHandle } from "./subagents/install.ts";
 
 /**
  * The single advertised entrypoint. It loads settings once, constructs each feature in
@@ -57,65 +54,42 @@ export default function piSessions(pi: ExtensionAPI): void {
   if (messaging) {
     lifecycles.push(messaging);
   }
-  const wakers: SessionWaker[] = [hosts];
-  const messageRouter = messaging
-    ? new MessageRouter(messaging, wakers, () => sessionEpoch)
+  const messageRouter: MessageRouter | undefined = messaging
+    ? new MessageRouter(
+        messaging,
+        () => subagents?.waker,
+        () => sessionEpoch,
+      )
     : undefined;
-  const subagents =
+  const subagents: SubagentsHandle | undefined =
     settings.features.subagents && messaging && messageRouter
       ? installSubagents(pi, {
           settings,
           messaging,
           readCompactionSettings,
           sendMessage: (request) => messageRouter.sendMessage(request),
-          hasHostedSessions: () => hosts.getHosts().some((host) => Boolean(host.wake)),
         })
       : undefined;
   if (subagents) {
-    wakers.unshift(subagents.waker);
     lifecycles.push(subagents);
   }
-  const registerMessagingTools = (): void => {
-    if (!messaging || !messageRouter) return;
-    const isSubagent = subagents?.getParentSessionId() !== undefined;
-    const hostedSessions = hosts.getHosts().some((host) => Boolean(host.wake));
-    pi.registerTool(
-      createSessionSendMessageTool(messageRouter, {
-        role: isSubagent
-          ? { kind: "subagent" }
-          : subagents
-            ? { kind: "wakeCapable" }
-            : { kind: "plain" },
-        hostedSessions,
-        getCachedRelationTo: messaging.getCachedRelationTo,
-        ...(subagents ? { getParentSessionId: () => subagents.getParentSessionId() } : {}),
-      }),
-    );
-    pi.registerTool(
-      createSessionCancelTool(subagents ?? messaging, {
-        role: isSubagent ? { kind: "subagent" } : { kind: "plain" },
-        ...(subagents ? { getParentSessionId: () => subagents.getParentSessionId() } : {}),
-      }),
-    );
-    pi.registerTool(
-      createSessionReachableTool({
-        indexPath: index.path,
-        hostedSessions,
-        listSessions: () => messaging.listSessions(),
-        listHostedSessions: () => hosts.listSessions(),
-        getRelationTo: messaging.getCachedRelationTo,
-        ...(subagents
-          ? {
-              listSubagents: async (scope) => (await subagents.roster.resolve(scope)).entries,
-              getParentSessionId: () => subagents.getParentSessionId(),
-            }
+  const directoryTools = messaging
+    ? installDirectoryTools(pi, {
+        peers: createPeerDirectory(messaging, {
+          indexPath: index.path,
+          listSessions: () => messaging.listSessions(),
+          getRelationTo: messaging.getCachedRelationTo,
+          getParentSessionId: () => subagents?.getParentSessionId(),
+        }),
+        ...(subagents && messageRouter
+          ? { subagents: createSubagentDirectory(subagents, messageRouter, messaging, index.path) }
           : {}),
-      }),
-    );
-  };
-  registerMessagingTools();
+        claimsPeers: () => hosts.claimsPeers(),
+      })
+    : undefined;
   if (settings.features.handoff) {
     const board = {
+      showUserSessions: () => !hosts.claimsPeers(),
       roster: subagents?.roster,
       cancelSubagent: subagents
         ? (sessionId: string) => subagents.cancelSession(sessionId)
@@ -128,7 +102,7 @@ export default function piSessions(pi: ExtensionAPI): void {
         settings,
         index,
         getModelRuntime,
-        getHosts: () => hosts.getHosts(),
+        claimsPeers: () => hosts.claimsPeers(),
         ...(subagents ? { getLaunchTargets: () => subagents.getLaunchTargets() } : {}),
         board,
       }),
@@ -167,7 +141,7 @@ export default function piSessions(pi: ExtensionAPI): void {
     for (const lifecycle of lifecycles) {
       await lifecycle.onSessionStart?.(event, ctx);
     }
-    registerMessagingTools();
+    directoryTools?.refresh();
     for (const lifecycle of lifecycles) {
       lifecycle.onSessionReady?.(ctx);
     }

package/extensions/session-handoff/board-loading.ts

@@ -5,6 +5,7 @@ import { HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE } from "./metadata.ts";
 import { parseHandoffLaunchReceiptEntry } from "./receipt.ts";
 
 export interface HandoffBoardServices {
+  showUserSessions: () => boolean;
   roster?: SubagentRoster | undefined;
   cancelSubagent?: ((sessionId: string) => Promise<unknown>) | undefined;
   listLiveSessions?: (() => Promise<string[]>) | undefined;
@@ -15,7 +16,8 @@ export async function loadHandoffBoardSnapshot(
   entries: readonly SessionEntry[],
   services: HandoffBoardServices,
 ): Promise<HandoffBoardSnapshot> {
-  const userSessions = collectUserSessions(entries);
+  const showUserSessions = services.showUserSessions();
+  const userSessions = showUserSessions ? collectUserSessions(entries) : [];
   const [branchRoster, liveSessionIds, hydratedUserSessions] = await Promise.all([
     services.roster?.resolve("branch") ?? Promise.resolve({ entries: [], total: 0 }),
     services.listLiveSessions?.() ?? Promise.resolve([]),
@@ -29,6 +31,7 @@ export async function loadHandoffBoardSnapshot(
     ),
   ]);
   return {
+    showUserSessions,
     subagents: branchRoster.entries,
     userSessions: hydratedUserSessions,
     liveSessionIds: new Set(liveSessionIds),

package/extensions/session-handoff/board-view-model.ts

@@ -20,6 +20,7 @@ export interface UserSessionEntry {
 }
 
 export interface HandoffBoardSnapshot {
+  showUserSessions: boolean;
   subagents: readonly SubagentRosterEntry[];
   userSessions: readonly UserSessionEntry[];
   liveSessionIds: ReadonlySet<string>;

package/extensions/session-handoff/board.ts

@@ -278,6 +278,8 @@ export class HandoffBoard implements Focusable {
   }
 
   private renderTabs(row: number, width: number): string {
+    if (!this.snapshot.showUserSessions)
+      return this.theme.fg("accent", this.theme.bold("Subagents"));
     this.controlHits.set(
       row,
       [
@@ -493,7 +495,7 @@ export class HandoffBoard implements Focusable {
 
     const action = view.action;
     const items: LegendItem[] = [
-      { key: "<>", description: "tab" },
+      ...(!this.snapshot.showUserSessions ? [] : [{ key: "<>", description: "tab" }]),
       { key: "↑↓", description: "select" },
     ];
     if (action?.canStop) {
@@ -557,6 +559,7 @@ export class HandoffBoard implements Focusable {
   }
 
   private setTab(tab: HandoffBoardTab): void {
+    if (tab === "user-sessions" && !this.snapshot.showUserSessions) return;
     this.tab = tab;
     this.clearTransientState();
     this.clampSelection();