pi-sessions 0.18.1 → 0.20.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, but takes an optional `agent` naming an [agent profile](#agent-profiles). 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
 
-- `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 coordination is a separate addressable directory:
 
-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.
+- `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
 
-## Host extension API (v1)
+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.
 
-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.
+## Host extension API
+
+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.
+
+## Durable lineage entry
 
-type HostLaunchResult =
-  | { success: true; clipboardStatus?: "copied" | "failed" }
-  | { success: false; error: string };
+Any extension may append this custom entry to a child session:
 
-interface HostSession {
-  sessionId: string;
-  cwd: string;
-  title: string;
+```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.
 
@@ -232,6 +236,27 @@ Subagents require the handoff and messaging features. Limit recursive delegation
 
 `contextLimit` sets a max context limit before compaction is triggered. It works identically to setting a global value in pi itself, but only applies to subagents.
 
+### Agent profiles
+
+An agent profile lets `subagent_launch` start a subagent with extra instructions, a pinned model, and a thinking level, by name. Profiles are Markdown files in `~/.pi/agent/agents/`, in Claude Code's subagent format, so the same file works in both:
+
+```markdown
+---
+name: oracle
+description: Read-only second opinion on a plan, diff, or hard bug. Use for reviews and high-impact judgment calls.
+model: anthropic/claude-fable-5-1:high
+---
+
+You are the Oracle: a read-only reviewer. Do not modify files. ...
+```
+
+- `name` must match the file name, and `description` tells the calling agent when to use the profile; both are required. The `subagent_launch` prompt guidelines list every valid profile with its description.
+- `model` is a pi model pattern (`provider/id` or a bare id, optionally with `:<thinking>`), and `thinkingLevel` sets the level separately. Explicit `provider`/`model` and `thinkingLevel` on the launch win, and the resolved model must still be on the handoff roster.
+- `tools` is a comma-separated allowlist passed to `--tools`; `submit_task_report` is always kept. Without it, the subagent has every tool.
+- The body is added to the subagent's system prompt, in the subagent section after its standard instructions; `AGENTS.md`, extensions, and the report flow are unchanged. The instructions are stored in the child session when it launches, so later edits to the file don't change a running subagent.
+
+Naming a missing or malformed profile fails the launch with the reason. Profiles apply only to subagents, not to `session_handoff`. Move the directory with `sessions.subagents.agentsDir` (an absolute path or one starting with `~/`).
+
 ## Session Index
 
 The index is a shared cache of your transcripts, used by search, messaging, and the other session features. Pi checks transcripts at startup and syncs files that changed, including sessions run without pi-sessions loaded. Missing, older-schema, or unreadable indexes rebuild automatically in the background; unreadable databases are moved aside rather than overwritten. A malformed transcript is skipped and reported.

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/agent-profiles.ts

@@ -0,0 +1,110 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { formatError } from "../shared/errors.ts";
+import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
+import { parseTypeBoxValue } from "../shared/typebox.ts";
+
+// Claude Code's subagent file format, so one file can serve several harnesses.
+// Keys other harnesses define, such as Claude Code's `color`, are ignored.
+const AGENT_PROFILE_FRONTMATTER_SCHEMA = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  description: Type.String({ minLength: 1 }),
+  model: Type.Optional(Type.String({ minLength: 1 })),
+  thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
+  tools: Type.Optional(Type.String({ minLength: 1 })),
+});
+
+export interface AgentProfile {
+  name: string;
+  description: string;
+  /** A Pi model pattern; a `:<thinking>` suffix travels with the model it names. */
+  model: string | undefined;
+  thinkingLevel: ThinkingLevel | undefined;
+  /** An allowlist for the child's `--tools`, or undefined to inherit every tool. */
+  tools: readonly string[] | undefined;
+  instructions: string;
+}
+
+export interface AgentProfileCatalog {
+  profiles: readonly AgentProfile[];
+  /** Validation errors by file name, so a launch naming a broken profile reports why. */
+  invalid: ReadonlyMap<string, string>;
+}
+
+export const EMPTY_AGENT_PROFILE_CATALOG: AgentProfileCatalog = {
+  profiles: [],
+  invalid: new Map(),
+};
+
+export function loadAgentProfiles(dir: string): AgentProfileCatalog {
+  let fileNames: string[];
+  try {
+    fileNames = readdirSync(dir)
+      .filter((fileName) => fileName.endsWith(".md"))
+      .sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return EMPTY_AGENT_PROFILE_CATALOG;
+    }
+    throw error;
+  }
+
+  const profiles: AgentProfile[] = [];
+  const invalid = new Map<string, string>();
+  for (const fileName of fileNames) {
+    const path = join(dir, fileName);
+    try {
+      profiles.push(parseAgentProfile(path, readFileSync(path, "utf8")));
+    } catch (error) {
+      invalid.set(basename(fileName, ".md"), `${path}: ${formatError(error)}`);
+    }
+  }
+  return { profiles, invalid };
+}
+
+export function parseAgentProfile(path: string, content: string): AgentProfile {
+  const { frontmatter, body } = parseFrontmatter(content);
+  const fields = parseTypeBoxValue(AGENT_PROFILE_FRONTMATTER_SCHEMA, frontmatter, "frontmatter");
+  const fileName = basename(path, ".md");
+  if (fields.name !== fileName) {
+    throw new Error(`name "${fields.name}" must match the file name "${fileName}".`);
+  }
+  const instructions = body.trim();
+  if (!instructions) {
+    throw new Error("the body must hold the profile's instructions.");
+  }
+  const tools = fields.tools
+    ?.split(",")
+    .map((tool) => tool.trim())
+    .filter(Boolean);
+  if (tools?.length === 0) {
+    throw new Error("tools must name at least one tool.");
+  }
+
+  return {
+    name: fields.name,
+    description: fields.description.replace(/\s+/g, " ").trim(),
+    model: fields.model?.trim(),
+    thinkingLevel: fields.thinkingLevel,
+    tools,
+    instructions,
+  };
+}
+
+export function requireAgentProfile(catalog: AgentProfileCatalog, name: string): AgentProfile {
+  const profile = catalog.profiles.find((candidate) => candidate.name === name);
+  if (profile) {
+    return profile;
+  }
+  const error = catalog.invalid.get(name);
+  if (error) {
+    throw new Error(`Agent profile "${name}" is invalid: ${error}`);
+  }
+  const available = catalog.profiles.map((candidate) => candidate.name).join(", ");
+  throw new Error(
+    `Unknown agent profile "${name}". Available agent profiles: ${available || "none"}.`,
+  );
+}

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();