pi-sessions 0.18.1 → 0.20.0

package/extensions/session-handoff/install.ts

@@ -2,13 +2,17 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import type { Host } from "../hosts/contract.ts";
 import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
 import type { ModelRuntimeProvider } from "../shared/model-runtime.ts";
 import { isTuiMode } from "../shared/pi-mode.ts";
 import type { SessionSettings } from "../shared/settings.ts";
 import { THINKING_LEVELS } from "../shared/thinking-levels.ts";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import {
+  type AgentProfileCatalog,
+  EMPTY_AGENT_PROFILE_CATALOG,
+  loadAgentProfiles,
+} from "./agent-profiles.ts";
 import { type HandoffBoardServices, openHandoffBoard } from "./board.ts";
 import { consumePendingHandoffBootstrap } from "./bootstrap.ts";
 import { renderHandoffBootstrapFailedEntry } from "./bootstrap-failed-renderer.ts";
@@ -21,11 +25,7 @@ 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,
-  MAX_HANDOFF_TITLE_LENGTH,
-} from "./tool.ts";
+import { executeSessionHandoffTool, MAX_HANDOFF_TITLE_LENGTH } from "./tool.ts";
 import { HANDOFF_TOOL_DETAILS_SCHEMA } from "./tool-contract.ts";
 import { HandoffToolComponent } from "./tool-renderer.ts";
 import {
@@ -51,7 +51,7 @@ export function installHandoff(
     index: IndexHandle;
     getModelRuntime: ModelRuntimeProvider;
     getLaunchTargets?: (() => readonly HandoffLaunchTarget[]) | undefined;
-    getHosts?: () => readonly Host[];
+    claimsPeers: () => boolean;
     board: HandoffBoardServices;
   },
 ): SessionLifecycle {
@@ -69,18 +69,26 @@ export function installHandoff(
     models: readonly Model<Api>[],
     launchTargets: readonly HandoffLaunchTarget[],
     roster: HandoffRoster | undefined,
+    agentProfiles: AgentProfileCatalog,
+    name: "session_handoff" | "subagent_launch",
   ): void {
     const offersSubagent = offersSubagentLaunch(launchTargets);
+    const offersAgents = name === "subagent_launch" && agentProfiles.profiles.length > 0;
     pi.registerTool({
-      name: "session_handoff",
+      name,
       label: "Session Handoff",
       description: "Start a new Pi session with a self-contained task.",
       // Nested calls write no toolResult entry, so the board would never see the launch receipt.
       exposure: "model-only",
       promptSnippet: offersSubagent
-        ? "Delegate bounded work to a background subagent or hand off context to another Pi session"
+        ? "Delegate bounded work to a background subagent"
         : "Hand off context to another Pi session",
-      promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models, roster),
+      promptGuidelines: buildHandoffPromptGuidelines(
+        launchTargets,
+        models,
+        roster,
+        offersAgents ? agentProfiles.profiles : [],
+      ),
       parameters: Type.Object({
         goal: Type.String({
           description:
@@ -91,17 +99,16 @@ export function installHandoff(
           description:
             "Short display title for the child session, 64 characters or less. Summarize the mission; do not repeat the full goal.",
         }),
-        launch: buildHandoffLaunchSchema(launchTargets),
+        ...(name === "session_handoff" ? { launch: buildHandoffLaunchSchema(launchTargets) } : {}),
         cwd: Type.Optional(
           Type.String({
             description: "Optional target working directory (defaults to current).",
           }),
         ),
-        requestResponse: Type.Optional(
-          Type.Boolean({
-            description: `Whether the child session should report completion/results of its task back to this session. ${offersSubagent ? "Defaults to true for subagent launches and false otherwise." : "Defaults to false."}`,
-          }),
-        ),
+        requestResponse: Type.Boolean({
+          description:
+            "Whether the child session should report completion/results of its task back to this session.",
+        }),
         provider: Type.Optional(
           Type.String({
             description: "Model provider for the child session.",
@@ -122,12 +129,22 @@ export function installHandoff(
             },
           ),
         ),
+        ...(offersAgents
+          ? {
+              agent: Type.Optional(
+                Type.String({
+                  description:
+                    "Agent profile to run the subagent as. The profile adds instructions to the subagent's system prompt and may set its model and thinking level; explicit provider/model and thinkingLevel take precedence.",
+                }),
+              ),
+            }
+          : {}),
       }),
       renderCall(args, theme, context) {
         const state = context.state as HandoffToolRendererState;
         const component = state.callComponent ?? new HandoffToolComponent(theme);
         state.callComponent = component;
-        component.update(buildHandoffToolView(args), context.expanded);
+        component.update(buildHandoffToolView(args, undefined, name), context.expanded);
         return component;
       },
       renderResult(result, options, theme, context) {
@@ -143,21 +160,31 @@ export function installHandoff(
         }
 
         state.callComponent.update(
-          buildHandoffToolView(context.args, details),
+          buildHandoffToolView(context.args, details, name),
           options.expanded,
           clipboardStatusBySessionId.get(details.sessionId),
         );
         return new Text("", 0, 0);
       },
-      async execute(_toolCallId, params: HandoffToolParams, _signal, _onUpdate, ctx) {
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        if (name === "session_handoff" && deps.claimsPeers())
+          throw new Error("Peer tools belong to the current host.");
+        const launch = name === "subagent_launch" ? "subagent" : params.launch;
+        if (typeof launch !== "string") throw new Error("session_handoff requires launch.");
+        if (name === "subagent_launch" && !deps.getLaunchTargets?.().length)
+          throw new Error("Subagent launch is unavailable.");
+        const { agent, ...rest } = params;
+        if (agent !== undefined && typeof agent !== "string")
+          throw new Error("agent must name an agent profile.");
         const modelRuntime = await deps.getModelRuntime(ctx.modelRegistry);
         return executeSessionHandoffTool(
           pi,
-          params,
+          { ...rest, launch, ...(agent === undefined ? {} : { agent }) },
           ctx,
           modelRuntime,
           launchTargets,
           roster,
+          agentProfiles,
           (sessionId, status) => clipboardStatusBySessionId.set(sessionId, status),
         );
       },
@@ -205,7 +232,7 @@ export function installHandoff(
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    if (!deps.getHosts?.().length && splitBackend?.identifyTerminalId && ctx) {
+    if (!deps.claimsPeers() && splitBackend?.identifyTerminalId && ctx) {
       identifiedGhosttyTerminalId =
         (await splitBackend.identifyTerminalId(ctx.cwd)) ?? identifiedGhosttyTerminalId;
     }
@@ -216,21 +243,38 @@ export function installHandoff(
   return {
     async onSessionStart(_event, ctx) {
       const models = ctx.modelRegistry.getAvailable();
-      registerHandoffTool(
+      const roster = resolveHandoffRoster({
         models,
-        createHandoffLaunchTargets({
-          pi,
-          splitBackend,
-          deferred: settings.handoff.deferred,
-          additionalTargets: deps.getLaunchTargets?.() ?? [],
-          hosts: deps.getHosts?.() ?? [],
-        }),
-        resolveHandoffRoster({
+        patterns: settings.handoff.roster,
+        scopedModels: ctx.scopedModels,
+      });
+      const subagentTargets = deps.getLaunchTargets?.() ?? [];
+      const agentProfiles = subagentTargets.length
+        ? loadAgentProfiles(settings.subagents.agentsDir)
+        : EMPTY_AGENT_PROFILE_CATALOG;
+      if (!deps.claimsPeers?.()) {
+        registerHandoffTool(
           models,
-          patterns: settings.handoff.roster,
-          scopedModels: ctx.scopedModels,
-        }),
-      );
+          createHandoffLaunchTargets({
+            pi,
+            splitBackend,
+            deferred: settings.handoff.deferred,
+            additionalTargets: [],
+          }),
+          roster,
+          EMPTY_AGENT_PROFILE_CATALOG,
+          "session_handoff",
+        );
+        pi.setActiveTools([...new Set([...pi.getActiveTools(), "session_handoff"])]);
+      } else {
+        pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "session_handoff"));
+      }
+      if (subagentTargets.length) {
+        registerHandoffTool(models, subagentTargets, roster, agentProfiles, "subagent_launch");
+        pi.setActiveTools([...new Set([...pi.getActiveTools(), "subagent_launch"])]);
+      } else {
+        pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "subagent_launch"));
+      }
 
       await consumePendingHandoffBootstrap(
         pi,

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

@@ -1,9 +1,21 @@
-import type { Host, HostLaunchInput } from "../../hosts/contract.ts";
-
 export type HandoffSplitDirection = "left" | "right" | "up" | "down";
 
-export type LaunchInput = HostLaunchInput;
+export interface LaunchInput {
+  sessionId: string;
+  sessionFile: string;
+  cwd: string;
+  title: string;
+  model: string;
+  resumeCommand: string;
+}
 
 export type ClipboardStatus = "copied" | "failed";
 
-export type LaunchBackend = Host;
+export interface LaunchBackend {
+  name: string;
+  launch(
+    input: LaunchInput,
+  ): Promise<
+    { success: true; clipboardStatus?: ClipboardStatus } | { success: false; error: string }
+  >;
+}

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

@@ -1,5 +1,4 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { Host } from "../hosts/contract.ts";
 import type { HandoffSettings } from "../shared/settings.ts";
 import { createDeferredLaunchBackend } from "./launch/deferred.ts";
 import type { SplitLaunchBackend } from "./launch/resolution.ts";
@@ -21,10 +20,8 @@ export function createHandoffLaunchTargets(options: {
   splitBackend: SplitLaunchBackend | undefined;
   deferred: HandoffSettings["deferred"];
   additionalTargets: readonly HandoffLaunchTarget[];
-  hosts?: readonly Host[];
 }): HandoffLaunchTarget[] {
-  const hosts = options.hosts ?? [];
-  const splitBackend = hosts.length ? undefined : options.splitBackend;
+  const splitBackend = options.splitBackend;
   const splitTargets = splitBackend
     ? LAUNCH_DIRECTIONS.map((direction, index) =>
         createBackendLaunchTarget(
@@ -45,19 +42,7 @@ export function createHandoffLaunchTargets(options: {
         ),
       ]
     : [];
-  return [
-    ...hosts.map((host) =>
-      createBackendLaunchTarget(
-        host.name,
-        host,
-        `'${host.name}' opens a session in ${host.name}.`,
-        true,
-      ),
-    ),
-    ...splitTargets,
-    ...deferredTargets,
-    ...options.additionalTargets,
-  ];
+  return [...splitTargets, ...deferredTargets, ...options.additionalTargets];
 }
 
 export function resolveHandoffLaunchTarget(

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

@@ -1,9 +1,8 @@
 import type { SessionManager } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
-import type { Host } from "../hosts/contract.ts";
 import { formatError } from "../shared/errors.ts";
-import type { ClipboardStatus } from "./launch/backend.ts";
-import type { HandoffSubagent } from "./metadata.ts";
+import type { ClipboardStatus, LaunchBackend } from "./launch/backend.ts";
+import type { HandoffSubagent, HandoffSubagentAgent } from "./metadata.ts";
 import type { PreparedHandoff } from "./spawn.ts";
 
 export const DEFERRED_LAUNCH = "deferred" as const;
@@ -58,16 +57,18 @@ export type HandoffLaunchTargetOutcome =
 export interface HandoffLaunchTarget {
   value: HandoffLaunchValue;
   description?: string | undefined;
-  requestResponseDefault: boolean;
   bootstrapMode: "review" | "automatic";
   /** Unattended children skip the startup trust prompt; watched ones let the user answer it. */
   approveProjectTrust: boolean;
   useDefaultSessionDir?: boolean;
+  /** Tools the child keeps when an agent profile narrows its tool allowlist. */
+  requiredTools?: readonly string[];
   /** Subagent launches stamp their child's identity into the child bootstrap. */
   describeSubagentChild?(input: {
     childSessionId: string;
     ownerSessionId: string;
     requestResponse: boolean;
+    agent: HandoffSubagentAgent | undefined;
   }): HandoffSubagent;
   prepareChild(input: HandoffLaunchTargetPreparation): void;
   launch(input: HandoffLaunchTargetInput): Promise<HandoffLaunchTargetOutcome>;
@@ -75,17 +76,14 @@ export interface HandoffLaunchTarget {
 
 export function createBackendLaunchTarget(
   value: string,
-  host: Host,
+  host: LaunchBackend,
   description?: string | undefined,
-  external = false,
 ): HandoffLaunchTarget {
   return {
     value,
     ...(description ? { description } : {}),
-    requestResponseDefault: false,
-    bootstrapMode: external ? "automatic" : "review",
-    approveProjectTrust: external,
-    useDefaultSessionDir: external,
+    bootstrapMode: "review",
+    approveProjectTrust: false,
     prepareChild() {},
     async launch(input) {
       try {

package/extensions/session-handoff/metadata.ts

@@ -20,6 +20,14 @@ export const HANDOFF_STALE_SESSION_MESSAGE =
 export const SESSION_STARTING_MESSAGE =
   "Target session is still starting. wait for session_reachable to report it as live, then resend.";
 
+// An agent profile's instructions travel with the child, which adds them to
+// its subagent prompt section, so they survive wakes and restarts without
+// depending on the profile file.
+export const HANDOFF_SUBAGENT_AGENT_SCHEMA = Type.Object({
+  name: Type.String(),
+  instructions: Type.String(),
+});
+
 // A subagent's self-knowledge, stamped into its child-local bootstrap so the
 // child never opens the parent transcript to learn who it is.
 export const HANDOFF_SUBAGENT_SCHEMA = Type.Object({
@@ -27,6 +35,7 @@ export const HANDOFF_SUBAGENT_SCHEMA = Type.Object({
   ownerSessionId: Type.String(),
   depth: Type.Integer({ minimum: 1 }),
   requestResponse: Type.Boolean(),
+  agent: Type.Optional(HANDOFF_SUBAGENT_AGENT_SCHEMA),
 });
 
 const HANDOFF_METADATA_BASE = {
@@ -84,6 +93,7 @@ export const HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA = Type.Object({
 });
 
 export type HandoffSubagent = Static<typeof HANDOFF_SUBAGENT_SCHEMA>;
+export type HandoffSubagentAgent = Static<typeof HANDOFF_SUBAGENT_AGENT_SCHEMA>;
 export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHEMA>;
 export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
 export type ChildGeneratedHandoffBootstrap = HandoffBootstrap;

package/extensions/session-handoff/model.ts

@@ -52,6 +52,28 @@ export function resolveChildModel(
   return { model, thinkingLevel: level };
 }
 
+/**
+ * Resolves an agent profile's model. The pattern is user-written, so it gets Pi's
+ * CLI grammar, but the model it lands on must still clear the roster.
+ */
+export function resolveProfileModel(
+  modelRuntime: ModelRuntime,
+  roster: HandoffRoster | undefined,
+  modelPattern: string,
+  thinkingLevel: ThinkingLevel | undefined,
+): HandoffModelOverride {
+  const resolved = resolveModelPattern(modelRuntime, modelPattern, thinkingLevel);
+  if (!roster) {
+    return resolved;
+  }
+  return resolveChildModel(
+    modelRuntime,
+    roster,
+    { provider: resolved.model.provider, modelId: resolved.model.id },
+    resolved.thinkingLevel,
+  );
+}
+
 /**
  * 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.

package/extensions/session-handoff/receipt.ts

@@ -35,7 +35,7 @@ export function parseHandoffLaunchReceiptEntry(
   if (
     entry.type === "message" &&
     entry.message.role === "toolResult" &&
-    entry.message.toolName === "session_handoff"
+    (entry.message.toolName === "session_handoff" || entry.message.toolName === "subagent_launch")
   ) {
     return safeParseTypeBoxValue(HANDOFF_LAUNCH_RECEIPT_SCHEMA, entry.message.details);
   }

package/extensions/session-handoff/spawn.ts

@@ -21,6 +21,7 @@ export function prepareHandoffLaunch(options: {
   parentSessionFile: string;
   title: string;
   model: string | undefined;
+  tools: readonly string[] | undefined;
   approveProjectTrust: boolean;
   useDefaultSessionDir?: boolean;
   buildBootstrap: (sessionId: string) => HandoffBootstrap;
@@ -54,6 +55,7 @@ export function prepareHandoffLaunch(options: {
     sessionId: manager.getSessionId(),
     sessionDir: manager.usesDefaultSessionDir() ? undefined : manager.getSessionDir(),
     model: options.model,
+    tools: options.tools,
     approveProjectTrust: options.approveProjectTrust,
   });
 
@@ -94,6 +96,7 @@ export function buildPiResumeCommand(options: {
   sessionId: string;
   sessionDir?: string | undefined;
   model?: string | undefined;
+  tools?: readonly string[] | undefined;
   approveProjectTrust: boolean;
 }): string {
   const args = ["pi"];
@@ -107,6 +110,9 @@ export function buildPiResumeCommand(options: {
   if (options.model) {
     args.push("--model", shellQuote(options.model));
   }
+  if (options.tools) {
+    args.push("--tools", shellQuote(options.tools.join(",")));
+  }
 
   const command = args.join(" ");
   return options.targetCwd === options.parentCwd

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

@@ -18,7 +18,7 @@ export function buildHandoffToolPresentation(
 
   return {
     header: [
-      theme.fg("accent", "session_handoff"),
+      theme.fg("accent", model.toolName ?? "session_handoff"),
       theme.fg("dim", `[${model.launch ?? PENDING}]`),
       theme.bold(model.title ?? PENDING),
     ].join(" "),

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

@@ -1,5 +1,6 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import type { AgentProfile } from "./agent-profiles.ts";
 import {
   DEFERRED_LAUNCH,
   type HandoffLaunchTarget,
@@ -21,7 +22,7 @@ export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]
 }
 
 const SUBAGENT_GUIDELINES = [
-  'Use session_handoff with launch: "subagent" for a concrete, bounded task that can proceed independently while useful work continues in the current session.',
+  "Use subagent_launch for a concrete, bounded task that can proceed independently while useful work continues in the current session.",
   "Do not launch a subagent for work that is trivial, duplicates work already underway, requires frequent coordination, or is tightly coupled to the current session's immediate next step.",
   "Tell every subagent explicitly whether it may modify files or should only investigate and report.",
   "Give concurrent subagents disjoint responsibilities and non-overlapping write scopes.",
@@ -42,10 +43,14 @@ const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
 const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
   "Only override the model when the task clearly warrants it.";
 
+const AGENT_PROFILE_GUIDELINE =
+  "Set agent to run a subagent as one of the agent profiles below when its description fits the task; the profile supplies the model, so leave provider, model, and thinkingLevel unset unless the user asks otherwise.";
+
 export function buildHandoffPromptGuidelines(
   targets: readonly HandoffLaunchTarget[],
   models: readonly Model<Api>[],
   roster: HandoffRoster | undefined,
+  agentProfiles: readonly AgentProfile[],
 ): string[] {
   const hasSubagent = offersSubagentLaunch(targets);
   const userFacingKinds = describeUserFacingLaunchKinds(targets);
@@ -62,6 +67,14 @@ export function buildHandoffPromptGuidelines(
       ? [`Available models, given as provider/model-id: ${selectable.join(", ")}.`]
       : []),
     ...(roster?.some((entry) => entry.thinkingLevels) ? [RESTRICTED_THINKING_GUIDELINE] : []),
+    ...(agentProfiles.length > 0
+      ? [
+          AGENT_PROFILE_GUIDELINE,
+          ...agentProfiles.map(
+            (profile) => `Agent profile "${profile.name}": ${profile.description}`,
+          ),
+        ]
+      : []),
   ];
 }
 
@@ -73,14 +86,6 @@ function describeUserFacingLaunchKinds(targets: readonly HandoffLaunchTarget[]):
   const isDirection = (value: string) => LAUNCH_DIRECTIONS.some((direction) => direction === value);
   const kinds = [
     targets.some((target) => isDirection(target.value)) ? "directional" : undefined,
-    targets.some(
-      (target) =>
-        target.value !== SUBAGENT_LAUNCH &&
-        target.value !== DEFERRED_LAUNCH &&
-        !isDirection(target.value),
-    )
-      ? "host"
-      : undefined,
     targets.some((target) => target.value === DEFERRED_LAUNCH) ? "deferred" : undefined,
   ];
   return kinds.filter((kind) => kind !== undefined).join(" or ");

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

@@ -4,6 +4,7 @@ import { isThinkingLevel } from "../shared/thinking-levels.ts";
 import type { HandoffToolDetails } from "./tool-contract.ts";
 
 export interface HandoffToolViewModel {
+  toolName: string;
   launch?: string | undefined;
   title?: string | undefined;
   goal?: string | undefined;
@@ -15,14 +16,17 @@ export interface HandoffToolViewModel {
 
 export function buildHandoffToolView(
   args: unknown,
-  result?: HandoffToolDetails | undefined,
+  result: HandoffToolDetails | undefined,
+  toolName: string,
 ): HandoffToolViewModel {
   const record = isRecord(args) ? args : {};
   const provider = normalizeOptionalText(result?.provider) ?? readString(record.provider);
   const model = normalizeOptionalText(result?.modelName) ?? readString(record.model);
   const thinkingLevel = result?.thinkingLevel ?? readThinkingLevel(record.thinkingLevel);
   return {
-    launch: readString(record.launch) ?? result?.launch,
+    toolName,
+    launch:
+      toolName === "subagent_launch" ? "subagent" : (readString(record.launch) ?? result?.launch),
     title: readString(record.title) ?? result?.title,
     goal: readString(record.goal),
     ...(provider ? { provider } : {}),

package/extensions/session-handoff/tool.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type AgentProfileCatalog, requireAgentProfile } from "./agent-profiles.ts";
 import { resolveHandoffSource } from "./extract.ts";
 import type { ClipboardStatus } from "./launch/backend.ts";
 import { resolveHandoffLaunchTarget } from "./launch-options.ts";
@@ -10,9 +11,10 @@ import {
   DEFERRED_LAUNCH,
   type HandoffLaunchTarget,
   type HandoffLaunchValue,
+  SUBAGENT_LAUNCH,
 } from "./launch-target.ts";
 import { createChildGeneratedHandoffBootstrap } from "./metadata.ts";
-import { formatModelArgument, resolveChildModel } from "./model.ts";
+import { formatModelArgument, resolveChildModel, resolveProfileModel } from "./model.ts";
 import { buildLaunchReceipt } from "./receipt.ts";
 import type { HandoffRoster } from "./roster.ts";
 import { formatHandoffLaunchFailure, prepareHandoffLaunch } from "./spawn.ts";
@@ -28,10 +30,11 @@ export interface HandoffToolParams {
   title: string;
   launch: HandoffLaunchValue;
   cwd?: string | undefined;
-  requestResponse?: boolean | undefined;
+  requestResponse: boolean;
   provider?: string | undefined;
   model?: string | undefined;
   thinkingLevel?: ThinkingLevel | undefined;
+  agent?: string | undefined;
 }
 
 export async function executeSessionHandoffTool(
@@ -41,6 +44,7 @@ export async function executeSessionHandoffTool(
   modelRuntime: ModelRuntime,
   launchTargets: readonly HandoffLaunchTarget[],
   roster: HandoffRoster | undefined,
+  agentProfiles: AgentProfileCatalog,
   recordClipboardStatus: (sessionId: string, status: ClipboardStatus) => void,
 ) {
   const goal = params.goal.trim();
@@ -61,6 +65,11 @@ export async function executeSessionHandoffTool(
   }
 
   const { target, degradedFrom } = resolveHandoffLaunchTarget(params.launch, launchTargets);
+  if (params.agent !== undefined && target.value !== SUBAGENT_LAUNCH) {
+    throw new Error("Agent profiles apply only to subagent launches.");
+  }
+  const profile =
+    params.agent === undefined ? undefined : requireAgentProfile(agentProfiles, params.agent);
 
   const targetCwd = resolveHandoffCwd(ctx.cwd, params.cwd);
   if (targetCwd.error) {
@@ -84,18 +93,21 @@ export async function executeSessionHandoffTool(
 
   resolveHandoffSource(ctx.sessionManager, sourceLeafId);
 
-  const requestResponse = params.requestResponse ?? target.requestResponseDefault;
+  const requestResponse = params.requestResponse;
   const provider = params.provider?.trim();
   const modelId = params.model?.trim();
   if (Boolean(provider) !== Boolean(modelId)) {
     throw new Error("session_handoff requires provider and model together, or neither.");
   }
+  const requestedThinkingLevel = params.thinkingLevel ?? profile?.thinkingLevel;
   const override =
     provider && modelId
-      ? resolveChildModel(modelRuntime, roster, { provider, modelId }, params.thinkingLevel)
-      : undefined;
+      ? resolveChildModel(modelRuntime, roster, { provider, modelId }, requestedThinkingLevel)
+      : profile?.model
+        ? resolveProfileModel(modelRuntime, roster, profile.model, requestedThinkingLevel)
+        : undefined;
   const childModel = override?.model ?? ctx.model;
-  const thinkingLevel = override?.thinkingLevel ?? params.thinkingLevel ?? pi.getThinkingLevel();
+  const thinkingLevel = override?.thinkingLevel ?? requestedThinkingLevel ?? pi.getThinkingLevel();
   const model = formatModelArgument(childModel, thinkingLevel);
   if (!model) {
     throw new Error("No active model is available for the handoff.");
@@ -107,6 +119,7 @@ export async function executeSessionHandoffTool(
     parentSessionFile,
     title,
     model,
+    tools: profile?.tools && [...new Set([...profile.tools, ...(target.requiredTools ?? [])])],
     approveProjectTrust: target.approveProjectTrust,
     useDefaultSessionDir: target.useDefaultSessionDir ?? false,
     buildBootstrap: (sessionId) =>
@@ -123,6 +136,7 @@ export async function executeSessionHandoffTool(
           childSessionId: sessionId,
           ownerSessionId: ctx.sessionManager.getSessionId(),
           requestResponse,
+          agent: profile && { name: profile.name, instructions: profile.instructions },
         }),
       }),
     prepareChild: (manager, childSessionId) =>