pi-sessions 0.11.1 → 0.12.0

package/README.md

@@ -108,7 +108,7 @@ Use `kind: "user"` or `kind: "subagent"` to filter by session type across the wh
 
 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.
 
-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.
+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.
 
 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.
 
@@ -142,6 +142,7 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
       "pickerShortcut": "alt+p",
       "model": "openai-codex/gpt-5.6-terra",
       "thinkingLevel": "low",
+      "roster": ["anthropic/*", "openai-codex/gpt-5.6-terra:high"],
       "deferred": {
         "copyToClipboard": true
       }
@@ -152,6 +153,8 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
 
 `model` and `thinkingLevel` configure the agent that builds handoff prompts. They default to the new session's values when absent.
 
+`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.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.
 
 Subagents require the handoff and messaging features. Limit recursive delegation depth with `sessions.subagents.maxDepth` (default `2`):

package/extensions/session-handoff/bootstrap-failed-renderer.ts

@@ -0,0 +1,28 @@
+import type { EntryRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import type { RenderTheme } from "../shared/rendering/theme.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import { HANDOFF_BOOTSTRAP_FAILED_SCHEMA, type HandoffBootstrapFailed } from "./metadata.ts";
+
+export const renderHandoffBootstrapFailedEntry: EntryRenderer = (entry, _options, theme) => {
+  const failure = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_FAILED_SCHEMA, entry.data);
+  if (!failure) {
+    return undefined;
+  }
+
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(presentHandoffBootstrapFailure(failure, theme), 0, 0));
+  return box;
+};
+
+export function presentHandoffBootstrapFailure(
+  failure: HandoffBootstrapFailed,
+  theme: RenderTheme,
+): string {
+  const header = `${theme.fg("error", theme.bold("handoff failed"))} ${theme.fg("muted", "draft generation did not complete")}`;
+  const retry = theme.fg(
+    "dim",
+    "The handoff is retried every time this session starts, until a message is sent.",
+  );
+  return [header, "", theme.fg("toolOutput", failure.error), "", retry].join("\n");
+}

package/extensions/session-handoff/bootstrap.ts

@@ -11,6 +11,7 @@ import {
   findPendingHandoffBootstrap,
   getHandoffMetadataFromEntries,
   HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE,
+  HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE,
   HANDOFF_METADATA_CUSTOM_TYPE,
   HANDOFF_STALE_SESSION_MESSAGE,
   type HandoffBootstrapConsumedReason,
@@ -54,6 +55,7 @@ export async function consumePendingHandoffBootstrap(
     ctx,
     bootstrap,
     scan.entryId,
+    scan.failure !== undefined,
     consumeBootstrap,
     getModelRuntime,
     destinationThinkingLevel,
@@ -66,6 +68,7 @@ async function startChildGeneratedHandoff(
   ctx: ExtensionContext,
   bootstrap: ChildGeneratedHandoffBootstrap,
   bootstrapEntryId: string,
+  hasEarlierFailure: boolean,
   consumeBootstrap: (reason: HandoffBootstrapConsumedReason) => void,
   getModelRuntime: ModelRuntimeProvider,
   destinationThinkingLevel: ThinkingLevel | undefined,
@@ -80,8 +83,13 @@ async function startChildGeneratedHandoff(
     return;
   }
 
+  // An automatic bootstrap exits on its first failure because only an
+  // unattended worker ever reaches that attempt. Every later start is someone
+  // opening the session deliberately, so it latches open for them instead.
+  const exitOnFailure = bootstrap.bootstrapMode === "automatic" && !hasEarlierFailure;
+
   if (!ctx.hasUI) {
-    if (bootstrap.bootstrapMode === "automatic") {
+    if (exitOnFailure) {
       ctx.shutdown();
     }
     return;
@@ -164,8 +172,15 @@ async function startChildGeneratedHandoff(
       { triggerTurn: true },
     );
   } catch (error) {
-    ctx.ui.notify(formatHandoffError(error), "error");
-    if (bootstrap.bootstrapMode === "automatic") {
+    // An exiting bootstrap takes the notification down with it, so the reason
+    // has to live in the transcript instead.
+    const message = formatHandoffError(error);
+    pi.appendEntry(HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE, {
+      bootstrapEntryId,
+      error: message,
+    });
+    ctx.ui.notify(message, "error");
+    if (exitOnFailure) {
       ctx.shutdown();
     }
   }

package/extensions/session-handoff/extract.ts

@@ -1,4 +1,4 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type {
   Api,
   AssistantMessage,
@@ -26,7 +26,7 @@ import { type Static, Type } from "typebox";
 import { freshenModel } from "../shared/model-runtime.ts";
 import { getDefaultHandoffRunsDir, type HandoffSettings } from "../shared/settings.ts";
 import { parseTypeBoxValue } from "../shared/typebox.ts";
-import { resolveModelOverride } from "./model.ts";
+import { resolveModelPattern } from "./model.ts";
 
 const MAX_HANDOFF_EXTRACTION_ATTEMPTS = 3;
 const HANDOFF_EXTRACTION_RETRY_PROMPT =
@@ -111,7 +111,7 @@ export async function generateHandoffDraftFromSessionManager({
   requestResponse?: boolean | undefined;
 }): Promise<HandoffDraftResult | undefined> {
   const modelOverride = settings.model
-    ? resolveModelOverride(modelRuntime, settings.model, settings.thinkingLevel)
+    ? resolveModelPattern(modelRuntime, settings.model, settings.thinkingLevel)
     : undefined;
   let model = modelOverride?.model;
   if (!model) {
@@ -247,6 +247,13 @@ async function runHandoffExtractionAgent(
       if (capturedArguments) {
         break;
       }
+      // A failed turn carries no refusal to re-prompt: retrying only burns the
+      // remaining attempts and buries the provider's reason behind the generic
+      // "did not return structured context" error.
+      const providerError = findProviderError(session.messages);
+      if (providerError) {
+        throw new Error(`Handoff extraction failed: ${providerError}`);
+      }
     }
   } finally {
     signal?.removeEventListener("abort", abortHandler);
@@ -272,6 +279,14 @@ async function runHandoffExtractionAgent(
   };
 }
 
+function findProviderError(messages: readonly AgentMessage[]): string | undefined {
+  const lastAssistant = messages.findLast((message) => message.role === "assistant");
+  if (lastAssistant?.role !== "assistant" || lastAssistant.stopReason !== "error") {
+    return undefined;
+  }
+  return lastAssistant.errorMessage || "the provider returned an error.";
+}
+
 export function assembleHandoffDraft(
   sessionId: string,
   sessionPath: string | undefined,

package/extensions/session-handoff/install.ts

@@ -10,13 +10,16 @@ import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
 import { type HandoffBoardServices, openHandoffBoard } from "./board.ts";
 import { consumePendingHandoffBootstrap } from "./bootstrap.ts";
+import { renderHandoffBootstrapFailedEntry } from "./bootstrap-failed-renderer.ts";
 import { HANDOFF_KICKOFF_CUSTOM_TYPE, renderHandoffKickoffMessage } from "./kickoff.ts";
 import type { ClipboardStatus } from "./launch/backend.ts";
 import { resolveSplitLaunchBackend } from "./launch/resolution.ts";
 import { createHandoffLaunchTargets } from "./launch-options.ts";
 import type { HandoffLaunchTarget } from "./launch-target.ts";
+import { HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE } from "./metadata.ts";
 import { openSessionReferencePicker } from "./picker.ts";
 import { SESSION_TOKEN_PREFIX } from "./query.ts";
+import { type HandoffRoster, resolveHandoffRoster } from "./roster.ts";
 import {
   executeSessionHandoffTool,
   type HandoffToolParams,
@@ -51,9 +54,11 @@ export function installHandoff(
   });
 
   pi.registerMessageRenderer(HANDOFF_KICKOFF_CUSTOM_TYPE, renderHandoffKickoffMessage);
+  pi.registerEntryRenderer(HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE, renderHandoffBootstrapFailedEntry);
   function registerHandoffTool(
     models: readonly Model<Api>[],
     launchTargets: readonly HandoffLaunchTarget[],
+    roster: HandoffRoster | undefined,
   ): void {
     pi.registerTool({
       name: "session_handoff",
@@ -61,7 +66,7 @@ export function installHandoff(
       description: "Start a new Pi session with a self-contained task.",
       promptSnippet:
         "Delegate bounded work to a background subagent or hand off context to another Pi session",
-      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models),
+      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models, roster),
       parameters: Type.Object({
         goal: Type.String({
           description:
@@ -138,6 +143,7 @@ export function installHandoff(
           ctx,
           modelRuntime,
           launchTargets,
+          roster,
           (sessionId, status) => clipboardStatusBySessionId.set(sessionId, status),
         );
       },
@@ -199,14 +205,20 @@ export function installHandoff(
 
   return {
     async onSessionStart(_event, ctx) {
+      const models = ctx.modelRegistry.getAvailable();
       registerHandoffTool(
-        ctx.modelRegistry.getAvailable(),
+        models,
         createHandoffLaunchTargets({
           pi,
           splitBackend,
           copyDeferredToClipboard: settings.handoff.deferred.copyToClipboard,
           additionalTargets: deps.getLaunchTargets?.() ?? [],
         }),
+        resolveHandoffRoster({
+          models,
+          patterns: settings.handoff.roster,
+          scopedModels: ctx.scopedModels,
+        }),
       );
 
       await consumePendingHandoffBootstrap(

package/extensions/session-handoff/launch-target.ts

@@ -59,6 +59,8 @@ export interface HandoffLaunchTarget {
   description?: string | undefined;
   requestResponseDefault: boolean;
   bootstrapMode: "review" | "automatic";
+  /** Unattended children skip the startup trust prompt; watched ones let the user answer it. */
+  approveProjectTrust: boolean;
   /** Subagent launches stamp their child's identity into the child bootstrap. */
   describeSubagentChild?(input: {
     childSessionId: string;
@@ -79,6 +81,7 @@ export function createBackendLaunchTarget(
     ...(description ? { description } : {}),
     requestResponseDefault: false,
     bootstrapMode: "review",
+    approveProjectTrust: false,
     prepareChild() {},
     launch(input) {
       return backend.launch({

package/extensions/session-handoff/metadata.ts

@@ -12,6 +12,7 @@ import {
 export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
 export const HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap";
 export const HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-consumed";
+export const HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-failed";
 export const HANDOFF_STALE_SESSION_MESSAGE =
   "Session handoff failed: target session already has user input.";
 export const SESSION_STARTING_MESSAGE =
@@ -62,6 +63,14 @@ export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Union([
   }),
 ]);
 
+// A bootstrap whose generation failed stays pending so a resume can retry it,
+// but the failure is recorded so the session stops reading as one that is
+// still starting.
+export const HANDOFF_BOOTSTRAP_FAILED_SCHEMA = Type.Object({
+  bootstrapEntryId: Type.String(),
+  error: Type.String(),
+});
+
 export const HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA = Type.Object({
   bootstrapEntryId: Type.String(),
   reason: Type.Union([
@@ -77,6 +86,7 @@ export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHE
 export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
 export type ChildGeneratedHandoffBootstrap = HandoffBootstrap;
 export type HandoffBootstrapConsumed = Static<typeof HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA>;
+export type HandoffBootstrapFailed = Static<typeof HANDOFF_BOOTSTRAP_FAILED_SCHEMA>;
 export type HandoffBootstrapConsumedReason = HandoffBootstrapConsumed["reason"];
 
 export function createHandoffSessionMetadata(
@@ -125,7 +135,7 @@ export function createChildGeneratedHandoffBootstrap(options: {
 }
 
 export type PendingHandoffBootstrapScan =
-  | { kind: "pending"; entryId: string; bootstrap: HandoffBootstrap }
+  | { kind: "pending"; entryId: string; bootstrap: HandoffBootstrap; failure?: string | undefined }
   | { kind: "invalid"; entryId: string };
 
 /**
@@ -137,6 +147,7 @@ export function findPendingHandoffBootstrap(
   branch: readonly SessionEntry[],
 ): PendingHandoffBootstrapScan | undefined {
   const consumedEntryIds = new Set<string>();
+  const failuresByEntryId = new Map<string, string>();
   for (const entry of branch) {
     if (entry.type === "custom_message" && entry.customType === HANDOFF_KICKOFF_CUSTOM_TYPE) {
       const details = safeParseTypeBoxValue(HANDOFF_KICKOFF_DETAILS_SCHEMA, entry.details);
@@ -150,6 +161,12 @@ export function findPendingHandoffBootstrap(
         consumedEntryIds.add(consumed.bootstrapEntryId);
       }
     }
+    if (entry.type === "custom" && entry.customType === HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE) {
+      const failed = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_FAILED_SCHEMA, entry.data);
+      if (failed) {
+        failuresByEntryId.set(failed.bootstrapEntryId, failed.error);
+      }
+    }
   }
 
   for (let i = branch.length - 1; i >= 0; i -= 1) {
@@ -163,9 +180,11 @@ export function findPendingHandoffBootstrap(
     }
 
     const bootstrap = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_SCHEMA, entry.data);
-    return bootstrap
-      ? { kind: "pending", entryId: entry.id, bootstrap }
-      : { kind: "invalid", entryId: entry.id };
+    if (!bootstrap) {
+      return { kind: "invalid", entryId: entry.id };
+    }
+    const failure = failuresByEntryId.get(entry.id);
+    return { kind: "pending", entryId: entry.id, bootstrap, ...(failure ? { failure } : {}) };
   }
 
   return undefined;
@@ -175,10 +194,13 @@ export function findPendingHandoffBootstrap(
  * A session is *starting* when its active branch still carries an unconsumed,
  * well-formed handoff bootstrap: it has been prepared but has not received its
  * kickoff. An invalid bootstrap does not count — the child consumes it and
- * proceeds as an ordinary session rather than kicking off a handoff.
+ * proceeds as an ordinary session rather than kicking off a handoff. Neither
+ * does one whose generation already failed: it stays retryable on resume, but
+ * nothing is starting right now.
  */
 export function isSessionStarting(branch: readonly SessionEntry[]): boolean {
-  return findPendingHandoffBootstrap(branch)?.kind === "pending";
+  const scan = findPendingHandoffBootstrap(branch);
+  return scan?.kind === "pending" && scan.failure === undefined;
 }
 
 /**

package/extensions/session-handoff/model.ts

@@ -1,34 +1,20 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import {
+  type ExactModelReference,
+  findModelByReference,
+  formatModelSelection,
+  selectModel,
+} from "../shared/model.ts";
 import { formatAvailableModelList, resolveAuthenticatedModel } from "../shared/model-resolution.ts";
-import { isThinkingLevel } from "../shared/thinking-levels.ts";
+import { type HandoffRoster, selectFromRoster } from "./roster.ts";
 
 export function formatModelArgument(
   model: Model<Api> | undefined,
   thinkingLevel: ThinkingLevel | undefined,
 ): string | undefined {
-  if (!model) {
-    return undefined;
-  }
-
-  const base = `${model.provider}/${model.id}`;
-  return thinkingLevel ? `${base}:${thinkingLevel}` : base;
-}
-
-export function parseModelArgument(value: string): {
-  model: string;
-  thinkingLevel?: ThinkingLevel | undefined;
-} {
-  const separator = value.lastIndexOf(":");
-  const suffix = separator >= 0 ? value.slice(separator + 1) : undefined;
-  if (!isThinkingLevel(suffix)) {
-    return { model: value };
-  }
-  return {
-    model: value.slice(0, separator),
-    thinkingLevel: suffix,
-  };
+  return model ? formatModelSelection(selectModel(model, thinkingLevel)) : undefined;
 }
 
 export interface HandoffModelOverride {
@@ -36,7 +22,41 @@ export interface HandoffModelOverride {
   thinkingLevel: ThinkingLevel | undefined;
 }
 
-export function resolveModelOverride(
+/**
+ * Resolves the model a handoff launches its child on. A roster replaces Pi's CLI
+ * matching entirely: fuzzy aliases resolve across every authenticated provider,
+ * which is how delegated work lands on a metered provider that happens to serve
+ * the same model id, so a rostered handoff accepts only an exact roster entry.
+ */
+export function resolveChildModel(
+  modelRuntime: ModelRuntime,
+  roster: HandoffRoster | undefined,
+  requested: ExactModelReference,
+  thinkingLevel: ThinkingLevel | undefined,
+): HandoffModelOverride {
+  if (!roster) {
+    return resolveModelPattern(
+      modelRuntime,
+      formatModelSelection({ ...requested, thinkingLevel: undefined }),
+      thinkingLevel,
+    );
+  }
+
+  const level = selectFromRoster(roster, requested, thinkingLevel);
+  const model = findModelByReference(modelRuntime.getAvailableSnapshot(), requested);
+  if (!model) {
+    throw new Error(
+      `Model "${requested.provider}/${requested.modelId}" is no longer an available authenticated model.`,
+    );
+  }
+  return { model, thinkingLevel: level };
+}
+
+/**
+ * Resolves a user-configured model pattern with Pi's CLI grammar, including fuzzy
+ * aliases. Only for settings the user writes by hand; never for a model's choice.
+ */
+export function resolveModelPattern(
   modelRuntime: ModelRuntime,
   modelPattern: string,
   thinkingLevel?: ThinkingLevel | undefined,

package/extensions/session-handoff/roster.ts

@@ -0,0 +1,162 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ScopedModel } from "@earendil-works/pi-coding-agent";
+import type { ExactModelReference, ModelSelection } from "../shared/model.ts";
+
+export interface HandoffRosterEntry extends ExactModelReference {
+  /** The thinking levels this model may run at, or undefined for the agent's choice. */
+  thinkingLevels: readonly ThinkingLevel[] | undefined;
+}
+
+export type HandoffRoster = readonly HandoffRosterEntry[];
+
+/**
+ * Chooses the roster a handoff selects from, in descending priority: an explicit
+ * `sessions.handoff.roster`, the session's own scoped models (`enabledModels`),
+ * then everything authenticated. The middle tier lets a curated model cycle
+ * govern delegation too; the top tier exists for when the two should disagree.
+ */
+export function resolveHandoffRoster(options: {
+  models: readonly Model<Api>[];
+  patterns: readonly ModelSelection[];
+  scopedModels: readonly ScopedModel[];
+}): HandoffRoster | undefined {
+  const configured = buildHandoffRoster(options.models, options.patterns);
+  if (configured) {
+    return configured;
+  }
+  return options.scopedModels.length > 0 ? options.scopedModels.map(scopedEntry) : undefined;
+}
+
+function scopedEntry(scoped: ScopedModel): HandoffRosterEntry {
+  return {
+    provider: scoped.model.provider,
+    modelId: scoped.model.id,
+    thinkingLevels: scoped.thinkingLevel ? [scoped.thinkingLevel] : undefined,
+  };
+}
+
+/**
+ * Expands configured roster patterns against the authenticated models. A roster
+ * only ever narrows what a handoff may launch, so patterns that match nothing
+ * are dropped rather than raised; the resulting roster is still safe, just
+ * smaller. An unconfigured roster returns undefined, deferring to the next tier.
+ */
+export function buildHandoffRoster(
+  models: readonly Model<Api>[],
+  patterns: readonly ModelSelection[],
+): HandoffRoster | undefined {
+  if (patterns.length === 0) {
+    return undefined;
+  }
+
+  const entries = new Map<string, HandoffRosterEntry>();
+  for (const pattern of patterns) {
+    const provider = globMatcher(pattern.provider);
+    const modelId = globMatcher(pattern.modelId);
+    for (const model of models) {
+      if (!provider.test(model.provider) || !modelId.test(model.id)) {
+        continue;
+      }
+      const key = `${model.provider}/${model.id}`;
+      const existing = entries.get(key);
+      entries.set(key, {
+        provider: model.provider,
+        modelId: model.id,
+        thinkingLevels: mergeThinkingLevels(existing, pattern.thinkingLevel),
+      });
+    }
+  }
+
+  return [...entries.values()];
+}
+
+/**
+ * Narrows a requested model to its roster entry. An entry listing a single
+ * thinking level pins it, so the agent may leave the level out; an entry listing
+ * several makes the choice mandatory.
+ */
+export function selectFromRoster(
+  roster: HandoffRoster,
+  requested: ExactModelReference,
+  thinkingLevel: ThinkingLevel | undefined,
+): ThinkingLevel | undefined {
+  if (roster.length === 0) {
+    throw new Error(
+      "session_handoff cannot override the model: sessions.handoff.roster matches no authenticated model.",
+    );
+  }
+
+  const entry = roster.find(
+    (candidate) =>
+      candidate.provider === requested.provider && candidate.modelId === requested.modelId,
+  );
+  if (!entry) {
+    throw new Error(
+      `Model "${requested.provider}/${requested.modelId}" is not on the handoff roster. Allowed models: ${formatRoster(roster)}.`,
+    );
+  }
+
+  const allowed = entry.thinkingLevels;
+  if (!allowed) {
+    return thinkingLevel;
+  }
+  if (!thinkingLevel) {
+    if (allowed.length > 1) {
+      throw new Error(
+        `The handoff roster requires a thinking level for "${formatEntryReference(entry)}": one of ${allowed.join(", ")}.`,
+      );
+    }
+    return allowed[0];
+  }
+  if (!allowed.includes(thinkingLevel)) {
+    throw new Error(
+      `The handoff roster does not allow thinking level ${thinkingLevel} for "${formatEntryReference(entry)}"; allowed: ${allowed.join(", ")}.`,
+    );
+  }
+  return thinkingLevel;
+}
+
+export function formatRoster(roster: HandoffRoster): string {
+  return roster.map(formatRosterEntry).join(", ");
+}
+
+export function formatRosterEntry(entry: HandoffRosterEntry): string {
+  const reference = formatEntryReference(entry);
+  if (!entry.thinkingLevels) {
+    return reference;
+  }
+  return entry.thinkingLevels.length === 1
+    ? `${reference}:${entry.thinkingLevels[0]}`
+    : `${reference}:{${entry.thinkingLevels.join(",")}}`;
+}
+
+function formatEntryReference(entry: ExactModelReference): string {
+  return `${entry.provider}/${entry.modelId}`;
+}
+
+function mergeThinkingLevels(
+  existing: HandoffRosterEntry | undefined,
+  added: ThinkingLevel | undefined,
+): readonly ThinkingLevel[] | undefined {
+  if (!added) {
+    return undefined;
+  }
+  if (!existing) {
+    return [added];
+  }
+  if (!existing.thinkingLevels) {
+    return undefined;
+  }
+  return existing.thinkingLevels.includes(added)
+    ? existing.thinkingLevels
+    : [...existing.thinkingLevels, added];
+}
+
+function globMatcher(pattern: string): RegExp {
+  const source = pattern
+    .split("*")
+    .map((segment) => segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${source}$`);
+}

package/extensions/session-handoff/spawn.ts

@@ -21,6 +21,7 @@ export function prepareHandoffLaunch(options: {
   parentSessionFile: string;
   title: string;
   model: string | undefined;
+  approveProjectTrust: boolean;
   buildBootstrap: (sessionId: string) => HandoffBootstrap;
   prepareChild?: ((manager: SessionManager, sessionId: string) => void) | undefined;
 }): PreparedHandoff {
@@ -52,6 +53,7 @@ export function prepareHandoffLaunch(options: {
     sessionId: manager.getSessionId(),
     sessionDir: manager.usesDefaultSessionDir() ? undefined : manager.getSessionDir(),
     model: options.model,
+    approveProjectTrust: options.approveProjectTrust,
   });
 
   return { sessionId: manager.getSessionId(), sessionFile, resumeCommand };
@@ -79,6 +81,11 @@ function flushPreparedSession(manager: SessionManager): void {
  * The canonical recovery artifact consumed by launch backends, failure
  * messages, clipboard delivery, and renderers. Self-locating: when the target
  * cwd differs from the parent's, the command starts with `cd <target> &&`.
+ *
+ * Unattended children carry `--approve`, which resolves project trust for that
+ * process without prompting: nobody is watching a detached worker's window, so
+ * a blocked trust selector there stalls the launch indefinitely. The override
+ * is process-scoped and never written to the trust store.
  */
 export function buildPiResumeCommand(options: {
   targetCwd: string;
@@ -86,12 +93,16 @@ export function buildPiResumeCommand(options: {
   sessionId: string;
   sessionDir?: string | undefined;
   model?: string | undefined;
+  approveProjectTrust: boolean;
 }): string {
   const args = ["pi"];
   if (options.sessionDir) {
     args.push("--session-dir", shellQuote(options.sessionDir));
   }
   args.push("--session-id", shellQuote(options.sessionId));
+  if (options.approveProjectTrust) {
+    args.push("--approve");
+  }
   if (options.model) {
     args.push("--model", shellQuote(options.model));
   }

package/extensions/session-handoff/tool-renderer.ts

@@ -40,14 +40,19 @@ export class HandoffToolComponent implements Component {
       return container.render(width);
     }
 
-    const commandLabel =
-      this.model.result.launch === "deferred"
-        ? formatDeferredCommandLabel(this.clipboardStatus)
-        : "recovery command";
-    container.addChild(new Spacer(1));
-    container.addChild(
-      createLaunchCommandComponent(this.model.result.resumeCommand, commandLabel, this.theme),
-    );
+    // Only a deferred handoff needs its command in the transcript, because the
+    // user is the one who has to run it. A launched child is already running;
+    // the board is where its command belongs.
+    if (this.model.result.launch === "deferred") {
+      container.addChild(new Spacer(1));
+      container.addChild(
+        createLaunchCommandComponent(
+          this.model.result.resumeCommand,
+          formatDeferredCommandLabel(this.clipboardStatus),
+          this.theme,
+        ),
+      );
+    }
     if (this.model.result.degradedFrom) {
       container.addChild(new Spacer(1));
       container.addChild(

package/extensions/session-handoff/tool-schema.ts

@@ -1,7 +1,7 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { formatAvailableModelList } from "../shared/model-resolution.ts";
 import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "./launch-target.ts";
+import { formatRosterEntry, type HandoffRoster } from "./roster.ts";
 
 export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
   const descriptions = targets.flatMap((target) =>
@@ -31,6 +31,9 @@ const MODEL_INHERITANCE_GUIDELINES = [
   "To run the handoff on a different model, set both provider and model together (both are required).",
 ];
 
+const RESTRICTED_THINKING_GUIDELINE =
+  'A ":level" suffix on a listed model limits it to those thinking levels; set thinkingLevel to one of them, or leave it unset when only one is listed.';
+
 const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
   "For subagents, choose the model that best fits the delegated task; for directional or deferred handoffs, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
 
@@ -40,15 +43,19 @@ const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
 export function buildHandoffPromptGuidelines(
   targets: readonly HandoffLaunchTarget[],
   models: readonly Model<Api>[],
+  roster: HandoffRoster | undefined,
 ): string[] {
   const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
+  const selectable =
+    roster?.map(formatRosterEntry) ?? models.map((model) => `${model.provider}/${model.id}`);
   return [
     ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
     LAUNCH_TARGET_GUIDELINE,
     ...MODEL_INHERITANCE_GUIDELINES,
     hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
-    ...(models.length > 0
-      ? [`Available models, given as provider/model-id: ${formatAvailableModelList(models)}.`]
+    ...(selectable.length > 0
+      ? [`Available models, given as provider/model-id: ${selectable.join(", ")}.`]
       : []),
+    ...(roster?.some((entry) => entry.thinkingLevels) ? [RESTRICTED_THINKING_GUIDELINE] : []),
   ];
 }

package/extensions/session-handoff/tool.ts

@@ -12,8 +12,9 @@ import {
   type HandoffLaunchValue,
 } from "./launch-target.ts";
 import { createChildGeneratedHandoffBootstrap } from "./metadata.ts";
-import { formatModelArgument, resolveModelOverride } from "./model.ts";
+import { formatModelArgument, resolveChildModel } from "./model.ts";
 import { buildLaunchReceipt } from "./receipt.ts";
+import type { HandoffRoster } from "./roster.ts";
 import { formatHandoffLaunchFailure, prepareHandoffLaunch } from "./spawn.ts";
 import type { HandoffToolDetails } from "./tool-contract.ts";
 
@@ -39,6 +40,7 @@ export async function executeSessionHandoffTool(
   ctx: ExtensionContext,
   modelRuntime: ModelRuntime,
   launchTargets: readonly HandoffLaunchTarget[],
+  roster: HandoffRoster | undefined,
   recordClipboardStatus: (sessionId: string, status: ClipboardStatus) => void,
 ) {
   const goal = params.goal.trim();
@@ -90,7 +92,7 @@ export async function executeSessionHandoffTool(
   }
   const override =
     provider && modelId
-      ? resolveModelOverride(modelRuntime, `${provider}/${modelId}`, params.thinkingLevel)
+      ? resolveChildModel(modelRuntime, roster, { provider, modelId }, params.thinkingLevel)
       : undefined;
   const childModel = override?.model ?? ctx.model;
   const thinkingLevel = override?.thinkingLevel ?? params.thinkingLevel ?? pi.getThinkingLevel();
@@ -105,6 +107,7 @@ export async function executeSessionHandoffTool(
     parentSessionFile,
     title,
     model,
+    approveProjectTrust: target.approveProjectTrust,
     buildBootstrap: (sessionId) =>
       createChildGeneratedHandoffBootstrap({
         sessionId,

package/extensions/shared/model.ts

@@ -1,10 +1,51 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { isThinkingLevel } from "./thinking-levels.ts";
 
 export interface ExactModelReference {
   provider: string;
   modelId: string;
 }
 
+/**
+ * The structured representation of "which model, at which thinking level". Pi's
+ * CLI grammar spells this `provider/model-id[:level]`; that string is an edge
+ * format, parsed on the way in and rebuilt on the way out.
+ */
+export interface ModelSelection extends ExactModelReference {
+  thinkingLevel: ThinkingLevel | undefined;
+}
+
+export function parseModelSelection(value: string): ModelSelection {
+  const separator = value.lastIndexOf(":");
+  const suffix = separator >= 0 ? value.slice(separator + 1) : undefined;
+  const thinkingLevel = isThinkingLevel(suffix) ? suffix : undefined;
+  const reference = thinkingLevel ? value.slice(0, separator) : value;
+
+  const boundary = reference.indexOf("/");
+  if (boundary <= 0 || boundary === reference.length - 1) {
+    throw new Error(`Expected a "provider/model-id" reference; got "${value}".`);
+  }
+
+  return {
+    provider: reference.slice(0, boundary),
+    modelId: reference.slice(boundary + 1),
+    thinkingLevel,
+  };
+}
+
+export function formatModelSelection(selection: ModelSelection): string {
+  const reference = `${selection.provider}/${selection.modelId}`;
+  return selection.thinkingLevel ? `${reference}:${selection.thinkingLevel}` : reference;
+}
+
+export function selectModel(
+  model: Model<Api>,
+  thinkingLevel: ThinkingLevel | undefined,
+): ModelSelection {
+  return { provider: model.provider, modelId: model.id, thinkingLevel };
+}
+
 export function findModelByReference(
   availableModels: readonly Model<Api>[],
   reference: ExactModelReference,

package/extensions/shared/settings.ts

@@ -4,6 +4,7 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { KeyId } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
+import { type ModelSelection, parseModelSelection } from "./model.ts";
 import { isThinkingLevel } from "./thinking-levels.ts";
 import { parseTypeBoxValue } from "./typebox.ts";
 
@@ -30,6 +31,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       persistRuns: Type.Optional(Type.Boolean()),
       model: Type.Optional(Type.String()),
       thinkingLevel: Type.Optional(Type.String()),
+      roster: Type.Optional(Type.Array(Type.String())),
       deferred: Type.Optional(
         Type.Object({
           copyToClipboard: Type.Optional(Type.Boolean()),
@@ -97,6 +99,8 @@ export interface AskSettings extends AgentModelSettings {
 export interface HandoffSettings extends AgentModelSettings {
   pickerShortcut: KeyId;
   persistRuns: boolean;
+  /** Patterns naming the models a handoff may launch a child on. Empty means unrestricted. */
+  roster: readonly ModelSelection[];
   deferred: {
     copyToClipboard: boolean;
   };
@@ -182,6 +186,19 @@ function normalizePickerShortcut(value: string | undefined): KeyId {
   return (trimmed ? trimmed : "alt+o") as KeyId;
 }
 
+function normalizeRoster(value: readonly string[] | undefined): readonly ModelSelection[] {
+  return (value ?? [])
+    .map((pattern) => pattern.trim())
+    .filter(Boolean)
+    .map((pattern) => {
+      try {
+        return parseModelSelection(pattern);
+      } catch (error) {
+        throw new Error(`Invalid sessions.handoff.roster entry: ${(error as Error).message}`);
+      }
+    });
+}
+
 function parseThinkingLevel(value: string | undefined): ThinkingLevel | undefined {
   const trimmed = value?.trim();
   return isThinkingLevel(trimmed) ? trimmed : undefined;
@@ -238,6 +255,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       ...resolveAgentModelSettings(fileSettings.handoff),
       pickerShortcut: normalizePickerShortcut(fileSettings.handoff?.pickerShortcut),
       persistRuns: fileSettings.handoff?.persistRuns ?? false,
+      roster: normalizeRoster(fileSettings.handoff?.roster),
       deferred: {
         copyToClipboard: fileSettings.handoff?.deferred?.copyToClipboard ?? true,
       },

package/extensions/subagents/launch-target.ts

@@ -21,6 +21,7 @@ export function createSubagentLaunchTarget(
       "'subagent' delegates one task to a detached tmux worker and requests a report by default.",
     requestResponseDefault: true,
     bootstrapMode: "automatic",
+    approveProjectTrust: true,
     describeSubagentChild(input) {
       return {
         childSessionId: input.childSessionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,20 +38,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-agent-core": "^0.82.1",
-    "@earendil-works/pi-ai": "^0.82.1",
-    "@earendil-works/pi-coding-agent": "^0.82.1",
-    "@earendil-works/pi-tui": "^0.82.1",
+    "@earendil-works/pi-agent-core": "^0.83.0",
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
     "@types/node": "^25.6.2",
     "strip-ansi": "^7.2.0",
     "typebox": "^1.1.38",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.0",
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.82.1",
-    "@earendil-works/pi-ai": ">=0.82.1",
-    "@earendil-works/pi-coding-agent": ">=0.82.1",
-    "@earendil-works/pi-tui": ">=0.82.1"
+    "@earendil-works/pi-agent-core": ">=0.83.0",
+    "@earendil-works/pi-ai": ">=0.83.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@earendil-works/pi-tui": ">=0.83.0"
   }
 }