pi-sessions 0.4.1 → 0.5.0

package/README.md

@@ -55,7 +55,7 @@ What session did I implement the db layer?
 | ------------------ | ------------------------------------- | ------------------------------------------------------- |
 | Session Search     | `session_search` pi tool              | Search through old sessions                             |
 | Session Ask        | `session_ask` pi tool                 | Ask questions about old sessions                        |
-| Session Handoff    | `/handoff`, session picker shortcut   | Start a focused new session; alternative to compaction  |
+| Session Handoff    | `/handoff`, `session_handoff` pi tool | Start a focused new session; alternative to compaction  |
 | 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                                    |
@@ -82,6 +82,10 @@ Flow:
 
 If you do nothing, the preview autostarts after a short countdown.
 
+When running in Ghostty on macOS, pi-sessions also exposes a `session_handoff` tool. This lets the agent start a background handoff after you choose a split direction. The current session keeps running, while the child session opens in the requested split, gathers context, and shows the same review countdown before starting.
+
+If background handoffs ever target the wrong pane, run `/handoff --identify` from the intended source pane to refresh the in-memory Ghostty terminal binding.
+
 ## Session picker
 
 Directly reference prior sessions by looking them up by contents.

package/extensions/session-handoff/extract.ts

@@ -93,10 +93,30 @@ export async function generateHandoffDraft(
     throw new Error("No model is available for handoff.");
   }
 
+  return generateHandoffDraftFromSessionManager(
+    ctx,
+    ctx.sessionManager,
+    goal,
+    thinkingLevel,
+    signal,
+  );
+}
+
+export async function generateHandoffDraftFromSessionManager(
+  ctx: ExtensionContext,
+  sourceSessionManager: ExtensionContext["sessionManager"],
+  goal: string,
+  thinkingLevel: ThinkingLevel | undefined,
+  signal?: AbortSignal,
+): Promise<HandoffDraftResult | undefined> {
+  if (!ctx.model) {
+    throw new Error("No model is available for handoff.");
+  }
+
   const model = ctx.model;
   const sessionContext = buildSessionContext(
-    ctx.sessionManager.getEntries(),
-    ctx.sessionManager.getLeafId(),
+    sourceSessionManager.getEntries(),
+    sourceSessionManager.getLeafId(),
   );
   if (sessionContext.messages.length === 0) {
     throw new Error("No conversation is available to hand off.");
@@ -115,8 +135,8 @@ export async function generateHandoffDraft(
     return undefined;
   }
 
-  const sessionId = ctx.sessionManager.getSessionId();
-  const sessionPath = ctx.sessionManager.getSessionFile();
+  const sessionId = sourceSessionManager.getSessionId();
+  const sessionPath = sourceSessionManager.getSessionFile();
 
   return {
     draft: assembleHandoffDraft(sessionId, sessionPath, handoffContext, goal),

package/extensions/session-handoff/metadata.ts

@@ -16,7 +16,7 @@ export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Object({
   initial_prompt: Type.String(),
 });
 
-export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
+export const IMMEDIATE_HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
   sessionId: Type.String(),
   goal: Type.String(),
   nextTask: Type.String(),
@@ -24,7 +24,24 @@ export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
   initialPrompt: Type.String(),
 });
 
+export const CHILD_GENERATED_HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
+  mode: Type.Literal("generate"),
+  sessionId: Type.String(),
+  goal: Type.String(),
+  title: Type.String(),
+  parentSessionFile: Type.String(),
+});
+
+export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Union([
+  IMMEDIATE_HANDOFF_BOOTSTRAP_SCHEMA,
+  CHILD_GENERATED_HANDOFF_BOOTSTRAP_SCHEMA,
+]);
+
 export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHEMA>;
+export type ImmediateHandoffBootstrap = Static<typeof IMMEDIATE_HANDOFF_BOOTSTRAP_SCHEMA>;
+export type ChildGeneratedHandoffBootstrap = Static<
+  typeof CHILD_GENERATED_HANDOFF_BOOTSTRAP_SCHEMA
+>;
 export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
 
 export function createHandoffSessionMetadata(
@@ -48,7 +65,7 @@ export function createHandoffSessionMetadata(
 export function createHandoffBootstrap(
   sessionId: string,
   metadata: HandoffSessionMetadata,
-): HandoffBootstrap {
+): ImmediateHandoffBootstrap {
   return {
     sessionId,
     goal: metadata.goal,
@@ -58,6 +75,27 @@ export function createHandoffBootstrap(
   };
 }
 
+export function createChildGeneratedHandoffBootstrap(options: {
+  sessionId: string;
+  goal: string;
+  title: string;
+  parentSessionFile: string;
+}): ChildGeneratedHandoffBootstrap {
+  return {
+    mode: "generate",
+    sessionId: options.sessionId,
+    goal: options.goal.trim(),
+    title: options.title.trim(),
+    parentSessionFile: options.parentSessionFile,
+  };
+}
+
+export function isChildGeneratedHandoffBootstrap(
+  bootstrap: HandoffBootstrap,
+): bootstrap is ChildGeneratedHandoffBootstrap {
+  return "mode" in bootstrap && bootstrap.mode === "generate";
+}
+
 export function encodeHandoffBootstrap(bootstrap: HandoffBootstrap): string {
   return Buffer.from(JSON.stringify(bootstrap), "utf8").toString("base64");
 }

package/extensions/session-handoff/review.ts

@@ -17,6 +17,11 @@ const PREVIEW_BODY_LINE_LIMIT = 16;
 
 type ReviewAction = "accept" | "edit" | "cancel";
 
+export type HandoffReviewResult =
+  | { action: "send"; prompt: string }
+  | { action: "prefill"; prompt: string }
+  | { action: "cancel" };
+
 interface TimerHandle {
   stop(): void;
 }
@@ -234,21 +239,33 @@ export async function reviewHandoffDraft(
   ctx: ExtensionCommandContext,
   draft: string,
 ): Promise<string | undefined> {
-  const action = await runPreviewGate(ctx.ui, draft);
-  if (action === "cancel") {
+  const result = await reviewHandoffDraftForSend(ctx.ui, draft);
+  if (result.action !== "send") {
     return undefined;
   }
 
+  return result.prompt;
+}
+
+export async function reviewHandoffDraftForSend(
+  ui: ExtensionUIContext,
+  draft: string,
+): Promise<HandoffReviewResult> {
+  const action = await runPreviewGate(ui, draft);
+  if (action === "cancel") {
+    return { action: "prefill", prompt: draft };
+  }
+
   if (action === "accept") {
-    return draft;
+    return { action: "send", prompt: draft };
   }
 
-  const editedDraft = await ctx.ui.editor("Edit handoff prompt", draft);
+  const editedDraft = await ui.editor("Edit handoff prompt", draft);
   if (!editedDraft?.trim()) {
-    return undefined;
+    return { action: "prefill", prompt: draft };
   }
 
-  return editedDraft;
+  return { action: "send", prompt: editedDraft };
 }
 
 async function runPreviewGate(ui: ExtensionUIContext, draft: string): Promise<ReviewAction> {

package/extensions/session-handoff/spawn.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import {
   CURRENT_SESSION_VERSION,
   type ExtensionAPI,
-  type ExtensionCommandContext,
+  type ExtensionContext,
   type SessionHeader,
   type SessionInfoEntry,
 } from "@earendil-works/pi-coding-agent";
@@ -22,9 +22,13 @@ export interface CreatedHandoffSession {
   sessionFile: string;
 }
 
+export function isGhosttyHandoffAvailable(): boolean {
+  return process.platform === "darwin" && process.env.TERM_PROGRAM === "ghostty";
+}
+
 export async function validateSplitHandoffPrerequisites(
   _pi: ExtensionAPI,
-  ctx: ExtensionCommandContext,
+  ctx: ExtensionContext,
 ): Promise<string | undefined> {
   if (!ctx.sessionManager.getSessionFile()) {
     return "Split handoff requires a persisted current session.";
@@ -77,6 +81,27 @@ export function createHandoffSession(options: {
   return { sessionId, sessionFile };
 }
 
+export async function getFocusedGhosttyTerminalId(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<string | undefined> {
+  const appleScript = [
+    'tell application "Ghostty"',
+    "    get id of focused terminal of selected tab of front window",
+    "end tell",
+  ].join("\n");
+  const result = await pi.exec(OSASCRIPT_PATH, ["-e", appleScript], {
+    cwd,
+    timeout: GHOSTTY_SPLIT_TIMEOUT_MS,
+  });
+
+  if (result.code !== 0) {
+    return undefined;
+  }
+
+  return result.stdout.trim() || undefined;
+}
+
 export async function launchSplitHandoffSession(
   pi: ExtensionAPI,
   options: {
@@ -86,24 +111,32 @@ export async function launchSplitHandoffSession(
     sessionId: string;
     bootstrapValue: string;
     title: string;
+    terminalId?: string | undefined;
+    restoreFocus?: boolean | undefined;
+    model?: string | undefined;
   },
 ): Promise<{ success: true } | { success: false; error: string }> {
-  const piCommand = buildPiLaunchCommand(
-    options.sessionDir,
-    options.sessionId,
-    options.bootstrapValue,
-    options.title,
-  );
+  const piCommand = buildPiLaunchCommand({
+    sessionDir: options.sessionDir,
+    sessionId: options.sessionId,
+    bootstrapValue: options.bootstrapValue,
+    title: options.title,
+    model: options.model,
+  });
   const escapedCwd = escapeAppleScriptString(options.cwd);
   const escapedCommand = escapeAppleScriptString(piCommand);
+  const targetTerminalLine = options.terminalId
+    ? `    set targetTerminal to item 1 of (every terminal whose id is "${escapeAppleScriptString(options.terminalId)}")`
+    : "    set targetTerminal to focused terminal of selected tab of front window";
+  const focusLine = options.restoreFocus === false ? [] : ["    focus targetTerminal"];
   const appleScript = [
     'tell application "Ghostty"',
-    "    set targetTerminal to focused terminal of selected tab of front window",
+    targetTerminalLine,
     "    set cfg to new surface configuration",
     `    set initial working directory of cfg to "${escapedCwd}"`,
     `    set command of cfg to "${escapedCommand}"`,
     `    set newTerminal to split targetTerminal direction ${options.direction} with configuration cfg`,
-    "    focus targetTerminal",
+    ...focusLine,
     "end tell",
   ].join("\n");
   const result = await pi.exec(OSASCRIPT_PATH, ["-e", appleScript], {
@@ -129,6 +162,7 @@ export function buildPiResumeCommand(
   sessionId: string,
   bootstrapValue: string,
   title: string,
+  model?: string | undefined,
 ): string {
   const args = [
     `${HANDOFF_BOOTSTRAP_ENV}=${shellQuote(bootstrapValue)}`,
@@ -141,16 +175,27 @@ export function buildPiResumeCommand(
     shellQuote(title),
   ];
 
+  if (model) {
+    args.push("--model", shellQuote(model));
+  }
+
   return args.join(" ");
 }
 
-export function buildPiLaunchCommand(
-  sessionDir: string,
-  sessionId: string,
-  bootstrapValue: string,
-  title: string,
-): string {
-  const payload = `${buildPiResumeCommand(sessionDir, sessionId, bootstrapValue, title)}; exec /bin/zsh -il`;
+export function buildPiLaunchCommand(options: {
+  sessionDir: string;
+  sessionId: string;
+  bootstrapValue: string;
+  title: string;
+  model?: string | undefined;
+}): string {
+  const payload = `${buildPiResumeCommand(
+    options.sessionDir,
+    options.sessionId,
+    options.bootstrapValue,
+    options.title,
+    options.model,
+  )}; exec /bin/zsh -il`;
   return `/bin/zsh -ilc ${shellQuote(payload)}`;
 }
 

package/extensions/session-handoff.ts

@@ -1,8 +1,24 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { buildSessionContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import { buildSessionContext, SessionManager } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey } from "@earendil-works/pi-tui";
-import { generateHandoffDraft, type HandoffDraftResult } from "./session-handoff/extract.js";
+import { Type } from "typebox";
 import {
+  generateHandoffDraft,
+  generateHandoffDraftFromSessionManager,
+  type HandoffDraftResult,
+} from "./session-handoff/extract.js";
+import {
+  type ChildGeneratedHandoffBootstrap,
+  createChildGeneratedHandoffBootstrap,
   createHandoffBootstrap,
   createHandoffSessionMetadata,
   encodeHandoffBootstrap,
@@ -11,15 +27,22 @@ import {
   HANDOFF_METADATA_CUSTOM_TYPE,
   HANDOFF_STALE_SESSION_MESSAGE,
   hasUserMessages,
+  isChildGeneratedHandoffBootstrap,
   parseHandoffBootstrap,
 } from "./session-handoff/metadata.js";
 import { openSessionReferencePicker } from "./session-handoff/picker.js";
 import { SESSION_TOKEN_PREFIX } from "./session-handoff/query.js";
-import { renderStrongModal, reviewHandoffDraft } from "./session-handoff/review.js";
+import {
+  renderStrongModal,
+  reviewHandoffDraft,
+  reviewHandoffDraftForSend,
+} from "./session-handoff/review.js";
 import {
   buildPiResumeCommand,
   createHandoffSession,
+  getFocusedGhosttyTerminalId,
   type HandoffSplitDirection,
+  isGhosttyHandoffAvailable,
   launchSplitHandoffSession,
   validateSplitHandoffPrerequisites,
 } from "./session-handoff/spawn.js";
@@ -27,14 +50,72 @@ import { isTuiMode } from "./shared/pi-mode.js";
 import { loadSettings } from "./shared/settings.js";
 
 const HANDOFF_USAGE = "Usage: /handoff [--left|--right|--up|--down] <goal for new thread>";
+const TOOL_HANDOFF_PROVISIONAL_TITLE = "Session handoff";
+const NO_IDENTIFIED_TERMINAL_MESSAGE =
+  "No Ghostty source terminal identified. Run /handoff --identify from the intended source pane.";
+
+interface HandoffToolParams {
+  goal: string;
+  splitDirection: HandoffSplitDirection;
+  cwd?: string | undefined;
+}
+
+interface HandoffToolDetails {
+  error: boolean;
+  sessionId?: string | undefined;
+  title?: string | undefined;
+  splitDirection?: HandoffSplitDirection | undefined;
+  cwd?: string | undefined;
+}
 
 interface HandoffPromptContext {
-  ui: ExtensionCommandContext["ui"];
+  ui: ExtensionUIContext;
   sendUserMessage(content: string): Promise<void>;
 }
 
 export default function sessionHandoffExtension(pi: ExtensionAPI): void {
   const settings = loadSettings();
+  let identifiedGhosttyTerminalId: string | undefined;
+
+  if (isGhosttyHandoffAvailable()) {
+    pi.registerTool({
+      name: "session_handoff",
+      label: "Session Handoff",
+      description:
+        "Start a new background Pi session with directed instructions based on current work. The current session continues after launch.",
+      promptSnippet:
+        "Start a background pi session in a terminal split based on the current session",
+      promptGuidelines: [
+        "Use session_handoff only when it is clear the work should be forked to a new context.",
+        "Prefer using session_handoff by direction of the user, not as an unsolicited default.",
+        "The goal should capture enough detail to encompass the ask and include any directions the next sessions should consider.",
+        "Only capable of a background handoff; to replace the current session, tell the user to run /handoff instead.",
+      ],
+      executionMode: "sequential",
+      parameters: Type.Object({
+        goal: Type.String({
+          description:
+            "Goal for the new session, including enough detail to capture the user's ask and any directions the next prompt should consider.",
+        }),
+        splitDirection: Type.Union(
+          [Type.Literal("left"), Type.Literal("right"), Type.Literal("up"), Type.Literal("down")],
+          {
+            description:
+              "Direction to split the Ghostty terminal. Must be explicitly provided by the user.",
+          },
+        ),
+        cwd: Type.Optional(
+          Type.String({
+            description:
+              "Optional target working directory. Relative paths resolve from the current session cwd.",
+          }),
+        ),
+      }),
+      async execute(_toolCallId, params: HandoffToolParams, _signal, _onUpdate, ctx) {
+        return executeSessionHandoffTool(pi, params, ctx, identifiedGhosttyTerminalId);
+      },
+    });
+  }
 
   pi.registerCommand("handoff", {
     description: "Transfer context to a new focused session",
@@ -44,17 +125,29 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      if (!ctx.model) {
-        ctx.ui.notify("No model selected", "error");
-        return;
-      }
-
       const parsedArgs = parseHandoffCommandArgs(args);
       if (parsedArgs.kind === "error") {
         ctx.ui.notify(parsedArgs.message, "error");
         return;
       }
 
+      if (parsedArgs.kind === "identify") {
+        const terminalId = await getFocusedGhosttyTerminalId(pi, ctx.cwd);
+        if (!terminalId) {
+          ctx.ui.notify("Unable to identify the focused Ghostty terminal.", "error");
+          return;
+        }
+
+        identifiedGhosttyTerminalId = terminalId;
+        ctx.ui.notify(`Identified Ghostty terminal ${terminalId}.`, "info");
+        return;
+      }
+
+      if (!ctx.model) {
+        ctx.ui.notify("No model selected", "error");
+        return;
+      }
+
       const sessionContext = buildSessionContext(
         ctx.sessionManager.getEntries(),
         ctx.sessionManager.getLeafId(),
@@ -118,14 +211,25 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         const bootstrapValue = encodeHandoffBootstrap(
           createHandoffBootstrap(createdSession.sessionId, handoffMetadata),
         );
-        const launchResult = await launchSplitHandoffSession(pi, {
+        let launchResult = await launchSplitHandoffSession(pi, {
           cwd: ctx.cwd,
           sessionDir: ctx.sessionManager.getSessionDir(),
           direction: parsedArgs.splitDirection,
           sessionId: createdSession.sessionId,
           bootstrapValue,
           title: handoffMetadata.title,
+          terminalId: identifiedGhosttyTerminalId,
         });
+        if (!launchResult.success && identifiedGhosttyTerminalId) {
+          launchResult = await launchSplitHandoffSession(pi, {
+            cwd: ctx.cwd,
+            sessionDir: ctx.sessionManager.getSessionDir(),
+            direction: parsedArgs.splitDirection,
+            sessionId: createdSession.sessionId,
+            bootstrapValue,
+            title: handoffMetadata.title,
+          });
+        }
 
         if (!launchResult.success) {
           ctx.ui.notify(
@@ -193,6 +297,11 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
     }
 
     try {
+      if (isChildGeneratedHandoffBootstrap(bootstrap)) {
+        await startChildGeneratedHandoff(pi, ctx, bootstrap, pi.getThinkingLevel());
+        return;
+      }
+
       const entries = ctx.sessionManager.getEntries();
       if (hasUserMessages(entries)) {
         if (ctx.hasUI) {
@@ -223,7 +332,12 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("before_agent_start", async (event) => {
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (isGhosttyHandoffAvailable() && ctx) {
+      identifiedGhosttyTerminalId =
+        (await getFocusedGhosttyTerminalId(pi, ctx.cwd)) ?? identifiedGhosttyTerminalId;
+    }
+
     return {
       systemPrompt:
         event.systemPrompt +
@@ -232,8 +346,243 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
   });
 }
 
+async function executeSessionHandoffTool(
+  pi: ExtensionAPI,
+  params: HandoffToolParams,
+  ctx: ExtensionContext,
+  terminalId: string | undefined,
+) {
+  const goal = params.goal.trim();
+  if (!goal) {
+    return createHandoffToolError("session_handoff requires a goal.");
+  }
+
+  if (!ctx.model) {
+    return createHandoffToolError("No model selected.");
+  }
+
+  const preflightError = await validateSplitHandoffPrerequisites(pi, ctx);
+  if (preflightError) {
+    return createHandoffToolError(preflightError);
+  }
+
+  if (!terminalId) {
+    return createHandoffToolError(NO_IDENTIFIED_TERMINAL_MESSAGE);
+  }
+
+  const targetCwd = resolveHandoffCwd(ctx.cwd, params.cwd);
+  if (targetCwd.error) {
+    return createHandoffToolError(targetCwd.message);
+  }
+
+  const parentSessionFile = ctx.sessionManager.getSessionFile();
+  if (!parentSessionFile) {
+    return createHandoffToolError("Handoff requires a persisted current session.");
+  }
+
+  const sessionContext = buildSessionContext(
+    ctx.sessionManager.getEntries(),
+    ctx.sessionManager.getLeafId(),
+  );
+  if (sessionContext.messages.length === 0) {
+    return createHandoffToolError("No conversation to hand off.");
+  }
+
+  const createdSession = createHandoffSession({
+    cwd: targetCwd.path,
+    sessionDir: ctx.sessionManager.getSessionDir(),
+    parentSessionFile,
+    title: TOOL_HANDOFF_PROVISIONAL_TITLE,
+  });
+  const bootstrapValue = encodeHandoffBootstrap(
+    createChildGeneratedHandoffBootstrap({
+      sessionId: createdSession.sessionId,
+      goal,
+      title: TOOL_HANDOFF_PROVISIONAL_TITLE,
+      parentSessionFile,
+    }),
+  );
+  const model = formatModelArgument(ctx.model, pi.getThinkingLevel());
+  const launchResult = await launchSplitHandoffSession(pi, {
+    cwd: targetCwd.path,
+    sessionDir: ctx.sessionManager.getSessionDir(),
+    direction: params.splitDirection,
+    sessionId: createdSession.sessionId,
+    bootstrapValue,
+    title: TOOL_HANDOFF_PROVISIONAL_TITLE,
+    terminalId,
+    restoreFocus: true,
+    model,
+  });
+
+  if (!launchResult.success) {
+    return createHandoffToolError(
+      `${launchResult.error} Created handoff session ${createdSession.sessionId}; start it manually with: ${buildPiResumeCommand(
+        ctx.sessionManager.getSessionDir(),
+        createdSession.sessionId,
+        bootstrapValue,
+        TOOL_HANDOFF_PROVISIONAL_TITLE,
+        model,
+      )}`,
+      {
+        sessionId: createdSession.sessionId,
+        title: TOOL_HANDOFF_PROVISIONAL_TITLE,
+        splitDirection: params.splitDirection,
+        cwd: targetCwd.path,
+      },
+    );
+  }
+
+  const details: HandoffToolDetails = {
+    error: false,
+    sessionId: createdSession.sessionId,
+    title: TOOL_HANDOFF_PROVISIONAL_TITLE,
+    splitDirection: params.splitDirection,
+    cwd: targetCwd.path,
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `Started handoff session ${createdSession.sessionId} (${params.splitDirection}) in ${targetCwd.path}.`,
+      },
+    ],
+    details,
+  };
+}
+
+async function startChildGeneratedHandoff(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  bootstrap: ChildGeneratedHandoffBootstrap,
+  thinkingLevel: ThinkingLevel | undefined,
+): Promise<void> {
+  const entries = ctx.sessionManager.getEntries();
+  if (hasUserMessages(entries)) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(HANDOFF_STALE_SESSION_MESSAGE, "error");
+    }
+    return;
+  }
+
+  if (!ctx.hasUI) {
+    return;
+  }
+
+  try {
+    const sourceSessionManager = SessionManager.open(bootstrap.parentSessionFile);
+    const generatedDraft = await runWithLoader(
+      ctx,
+      "Generating handoff draft...",
+      async (signal: AbortSignal) =>
+        generateHandoffDraftFromSessionManager(
+          ctx,
+          sourceSessionManager,
+          bootstrap.goal,
+          thinkingLevel,
+          signal,
+        ),
+    );
+    if (!generatedDraft) {
+      ctx.ui.notify("Cancelled", "info");
+      return;
+    }
+
+    const review = await reviewHandoffDraftForSend(ctx.ui, generatedDraft.draft);
+    if (review.action === "prefill") {
+      ctx.ui.setEditorText(review.prompt);
+      ctx.ui.notify("Handoff prompt ready in editor.", "info");
+      return;
+    }
+
+    if (review.action === "cancel") {
+      ctx.ui.notify("Cancelled", "info");
+      return;
+    }
+
+    const metadata = createHandoffSessionMetadata(
+      bootstrap.goal,
+      generatedDraft.context.nextTask,
+      review.prompt,
+      generatedDraft.context.title,
+    );
+    if (!getHandoffMetadataFromEntries(ctx.sessionManager.getEntries())) {
+      pi.appendEntry(HANDOFF_METADATA_CUSTOM_TYPE, metadata);
+    }
+    pi.setSessionName(metadata.title);
+    pi.sendUserMessage(review.prompt);
+  } catch (error) {
+    ctx.ui.notify(formatHandoffError(error), "error");
+  }
+}
+
+function createHandoffToolError(message: string, details: Partial<HandoffToolDetails> = {}) {
+  const resultDetails: HandoffToolDetails = {
+    error: true,
+    ...details,
+  };
+
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: resultDetails,
+  };
+}
+
+function resolveHandoffCwd(
+  currentCwd: string,
+  requestedCwd: string | undefined,
+): { path: string; error?: undefined } | { error: true; message: string } {
+  const rawPath = requestedCwd?.trim();
+  const resolvedPath = rawPath ? resolveRequestedPath(currentCwd, rawPath) : currentCwd;
+
+  if (!existsSync(resolvedPath)) {
+    return {
+      error: true,
+      message: `Handoff cwd does not exist: ${resolvedPath}`,
+    };
+  }
+
+  if (!statSync(resolvedPath).isDirectory()) {
+    return {
+      error: true,
+      message: `Handoff cwd is not a directory: ${resolvedPath}`,
+    };
+  }
+
+  return { path: resolvedPath };
+}
+
+function resolveRequestedPath(currentCwd: string, requestedPath: string): string {
+  if (requestedPath === "~") {
+    return homedir();
+  }
+
+  if (requestedPath.startsWith("~/")) {
+    return resolve(homedir(), requestedPath.slice(2));
+  }
+
+  if (isAbsolute(requestedPath)) {
+    return requestedPath;
+  }
+
+  return resolve(currentCwd, requestedPath);
+}
+
+function formatModelArgument(
+  model: ExtensionContext["model"],
+  thinkingLevel: ThinkingLevel | undefined,
+): string | undefined {
+  if (!model) {
+    return undefined;
+  }
+
+  const base = `${model.provider}/${model.id}`;
+  return thinkingLevel ? `${base}:${thinkingLevel}` : base;
+}
+
 async function runWithLoader<T>(
-  ctx: ExtensionCommandContext,
+  ctx: { ui: ExtensionUIContext },
   label: string,
   task: (signal: AbortSignal) => Promise<T>,
 ): Promise<T | undefined> {
@@ -313,16 +662,23 @@ function formatHandoffError(error: unknown): string {
   return "Handoff generation failed.";
 }
 
-function parseHandoffCommandArgs(
-  args: string,
-):
-  | { kind: "ok"; goal: string; splitDirection?: HandoffSplitDirection | undefined }
+function parseHandoffCommandArgs(args: string):
+  | { kind: "identify" }
+  | {
+      kind: "ok";
+      goal: string;
+      splitDirection?: HandoffSplitDirection | undefined;
+    }
   | { kind: "error"; message: string } {
   const tokens = args
     .trim()
     .split(/\s+/)
     .filter((token) => token.length > 0);
 
+  if (tokens.includes("--identify")) {
+    return { kind: "identify" };
+  }
+
   if (tokens.length === 0) {
     return { kind: "error", message: HANDOFF_USAGE };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, auto-titling, and indexing tools",
   "license": "MIT",