@andrewhampton/opencode-handoff 0.1.0 → 0.2.0

package/README.md

@@ -6,32 +6,34 @@ An [OpenCode](https://opencode.ai) plugin that implements the `/handoff` command
 
 When you run `/handoff <instruction>`, the plugin:
 
-1. Asks the AI to summarize the current thread context
-2. Creates a new session
-3. Sends the handoff prompt (with your instruction) to the new session
-4. Shows a toast notification when complete
+1. Asks the AI to analyze the conversation and identify relevant files
+2. Creates a new session with a handoff prompt
+3. Links the new session to the original (for lookback via `read_session`)
+4. Automatically injects referenced files into the new session's context
+5. Starts the AI responding immediately
 
 The new session uses the same model as the original session.
 
+## Features
+
+- **Auto-registered command** - No manual command configuration needed
+- **Session linkage** - New sessions can use `read_session` to fetch details from the source session
+- **File context injection** - `@file` references in the handoff are automatically loaded
+- **Smart file selection** - AI is guided to include 8-15 relevant files (up to 20 for complex work)
+
 ## Installation
 
-Add the plugin and command to your `opencode.json` (or `opencode.jsonc`). The plugin is available on npm as `opencode-handoff`, and OpenCode will install it automatically when you restart:
+Add the plugin to your `opencode.json` (or `opencode.jsonc`):
 
 ```json
 {
-  "plugin": ["opencode-handoff"],
-  "command": {
-    "handoff": {
-      "description": "Create a handoff prompt in a new session",
-      "template": "Create a handoff prompt based on the instruction:\n\n$ARGUMENTS\n\nRequirements:\n- Review the current thread before responding.\n- Produce a prompt for a new thread that includes relevant context from this thread.\n- Conclude with a verbatim copy of the instruction above."
-    }
-  }
+  "plugin": ["@andrewhampton/opencode-handoff"]
 }
 ```
 
-Then restart OpenCode.
+Then restart OpenCode. The `/handoff` command is automatically registered.
 
-> **Note:** Both the plugin and command are required. The command tells the AI how to generate the handoff summary, and the plugin listens for the command's completion to create the new session.
+> **Note:** You can override the default command template by adding your own `handoff` command to the config.
 
 ## Usage
 
@@ -46,7 +48,21 @@ For example:
 /handoff Continue implementing the user authentication feature
 ```
 
-The AI will review the current thread, create a summary with relevant context, and start a new session with that context plus your instruction.
+The AI will:
+1. Review the current thread
+2. Identify relevant files to include
+3. Create a focused summary with context
+4. Start a new session with everything the next AI needs
+
+## Tools
+
+The plugin provides a `read_session` tool that allows the AI in the new session to fetch additional context from the source session:
+
+```
+read_session(sessionID: string, limit?: number)
+```
+
+This is automatically available when the handoff prompt includes session linkage.
 
 ## Limitations
 

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { HandoffPlugin } from "./plugin/handoff";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,391 @@
+// plugin/tools.ts
+import { tool } from "@opencode-ai/plugin";
+function formatTranscript(messages, limit) {
+  const lines = [];
+  for (const msg of messages) {
+    if (msg.info.role === "user") {
+      lines.push("## User");
+      for (const part of msg.parts) {
+        if (part.type === "text" && !part.ignored) {
+          lines.push(part.text ?? "");
+        }
+        if (part.type === "file") {
+          lines.push(`[Attached: ${part.filename || "file"}]`);
+        }
+      }
+      lines.push("");
+    }
+    if (msg.info.role === "assistant") {
+      lines.push("## Assistant");
+      for (const part of msg.parts) {
+        if (part.type === "text") {
+          lines.push(part.text ?? "");
+        }
+        if (part.type === "tool" && part.state?.status === "completed") {
+          lines.push(`[Tool: ${part.tool}] ${part.state.title}`);
+        }
+      }
+      lines.push("");
+    }
+  }
+  const output = lines.join(`
+`).trim();
+  if (messages.length >= (limit ?? 100)) {
+    return output + `
+
+(Showing ${messages.length} most recent messages. Use a higher 'limit' to see more.)`;
+  }
+  return output + `
+
+(End of session - ${messages.length} messages)`;
+}
+var ReadSession = (client) => {
+  return tool({
+    description: "Read the conversation transcript from a previous session. Use this when you need specific information from the source session that wasn't included in the handoff summary.",
+    args: {
+      sessionID: tool.schema.string().describe("The full session ID (e.g., ses_01jxyz...)"),
+      limit: tool.schema.number().optional().describe("Maximum number of messages to read (defaults to 100, max 500)")
+    },
+    async execute(args) {
+      const limit = Math.min(args.limit ?? 100, 500);
+      try {
+        const response = await client.session.messages({
+          path: { id: args.sessionID },
+          query: { limit }
+        });
+        const data = response.data ?? response;
+        if (!data || Array.isArray(data) && data.length === 0) {
+          return "Session has no messages or does not exist.";
+        }
+        return formatTranscript(data, limit);
+      } catch (error) {
+        return `Could not read session ${args.sessionID}: ${error instanceof Error ? error.message : "Unknown error"}`;
+      }
+    }
+  });
+};
+
+// plugin/files.ts
+import * as path2 from "node:path";
+import * as fs2 from "node:fs/promises";
+
+// plugin/vendor.ts
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+var DEFAULT_READ_LIMIT = 2000;
+var MAX_LINE_LENGTH = 2000;
+var BINARY_EXTENSIONS = new Set([
+  ".zip",
+  ".tar",
+  ".gz",
+  ".exe",
+  ".dll",
+  ".so",
+  ".class",
+  ".jar",
+  ".war",
+  ".7z",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  ".odt",
+  ".ods",
+  ".odp",
+  ".bin",
+  ".dat",
+  ".obj",
+  ".o",
+  ".a",
+  ".lib",
+  ".wasm",
+  ".pyc",
+  ".pyo"
+]);
+async function isBinaryFile(filepath) {
+  const ext = path.extname(filepath).toLowerCase();
+  if (BINARY_EXTENSIONS.has(ext)) {
+    return true;
+  }
+  try {
+    const buffer = await fs.readFile(filepath);
+    if (!buffer)
+      return false;
+    const fileSize = buffer.length;
+    if (fileSize === 0)
+      return false;
+    const bufferSize = Math.min(4096, fileSize);
+    const bytes = buffer.subarray(0, bufferSize);
+    let nonPrintableCount = 0;
+    for (let i = 0;i < bytes.length; i++) {
+      const byte = bytes[i];
+      if (byte === undefined)
+        continue;
+      if (byte === 0)
+        return true;
+      if (byte < 9 || byte > 13 && byte < 32) {
+        nonPrintableCount++;
+      }
+    }
+    return nonPrintableCount / bytes.length > 0.3;
+  } catch {
+    return false;
+  }
+}
+function formatFileContent(_filepath, content) {
+  const lines = content.split(`
+`);
+  const limit = DEFAULT_READ_LIMIT;
+  const offset = 0;
+  const raw = lines.slice(offset, offset + limit).map((line) => {
+    return line.length > MAX_LINE_LENGTH ? line.substring(0, MAX_LINE_LENGTH) + "..." : line;
+  });
+  const formatted = raw.map((line, index) => {
+    return `${(index + offset + 1).toString().padStart(5, "0")}| ${line}`;
+  });
+  let output = `<file>
+`;
+  output += formatted.join(`
+`);
+  const totalLines = lines.length;
+  const lastReadLine = offset + formatted.length;
+  const hasMoreLines = totalLines > lastReadLine;
+  if (hasMoreLines) {
+    output += `
+
+(File has more lines. Use 'offset' parameter to read beyond line ${lastReadLine})`;
+  } else {
+    output += `
+
+(End of file - total ${totalLines} lines)`;
+  }
+  output += `
+</file>`;
+  return output;
+}
+
+// plugin/files.ts
+var FILE_REGEX = /(?<![\w`])@(\.?[^\s`,.]*(?:\.[^\s`,.]+)*)/g;
+function parseFileReferences(text) {
+  const fileRefs = new Set;
+  for (const match of text.matchAll(FILE_REGEX)) {
+    if (match[1]) {
+      fileRefs.add(match[1]);
+    }
+  }
+  return fileRefs;
+}
+async function buildSyntheticFileParts(directory, refs) {
+  const parts = [];
+  for (const ref of refs) {
+    const filepath = path2.resolve(directory, ref);
+    try {
+      const stats = await fs2.stat(filepath);
+      if (!stats.isFile())
+        continue;
+      if (await isBinaryFile(filepath))
+        continue;
+      const content = await fs2.readFile(filepath, "utf-8");
+      parts.push({
+        type: "text",
+        synthetic: true,
+        text: `Called the Read tool with the following input: ${JSON.stringify({ filePath: filepath })}`
+      });
+      parts.push({
+        type: "text",
+        synthetic: true,
+        text: formatFileContent(filepath, content)
+      });
+    } catch {}
+  }
+  return parts;
+}
+
+// plugin/handoff.ts
+var HANDOFF_COMMAND = `GOAL: You are creating a handoff message to continue work in a new session.
+
+<context>
+When an AI assistant starts a fresh session, it spends significant time exploring the codebase—grepping, reading files, searching—before it can begin actual work. This "file archaeology" is wasteful when the previous session already discovered what matters.
+
+A good handoff frontloads everything the next session needs so it can start implementing immediately.
+</context>
+
+<instructions>
+Analyze this conversation and extract what matters for continuing the work.
+
+1. Identify all relevant files that should be loaded into the next session's context
+
+   Include files that will be edited, dependencies being touched, relevant tests, configs, and key reference docs. Be generous—the cost of an extra file is low; missing a critical one means another archaeology dig. Target 8-15 files, up to 20 for complex work.
+
+2. Draft the context and goal description
+
+   Describe what we're working on and provide whatever context helps continue the work. Structure it based on what fits the conversation—could be tasks, findings, a simple paragraph, or detailed steps.
+
+   Preserve: decisions, constraints, user preferences, technical patterns.
+
+   Exclude: conversation back-and-forth, dead ends, meta-commentary.
+
+The user controls what context matters. If they mentioned something to preserve, include it—trust their judgment about their workflow.
+</instructions>
+
+<user_input>
+This is what the next session should focus on. Use it to shape your handoff's direction—don't investigate or search, just incorporate the intent into your context and goals.
+
+If empty, capture a natural continuation of the current conversation's direction.
+
+USER: $ARGUMENTS
+</user_input>
+
+---
+
+Produce a prompt for a new thread that includes relevant context from this thread. Use @filepath format for file references. Conclude with a verbatim copy of the user's instruction above.`;
+var getResponseData = (response) => {
+  if (typeof response === "object" && response !== null && "data" in response) {
+    return response.data;
+  }
+  return response;
+};
+var HandoffPlugin = async ({ client, directory }) => {
+  const log = async (level, message, extra) => {
+    try {
+      await client.app.log({
+        body: {
+          service: "handoff",
+          level,
+          message,
+          extra
+        }
+      });
+    } catch {}
+  };
+  const promptForInstruction = async () => {
+    await client.tui.showToast({
+      body: {
+        message: "Provide a handoff instruction after /handoff",
+        variant: "warning"
+      }
+    });
+    await client.tui.appendPrompt({ body: { text: "/handoff " } });
+  };
+  const extractMessageText = (entry) => {
+    if (!entry) {
+      return "";
+    }
+    return entry.parts.filter((part) => part.type === "text").map((part) => part.text ?? "").join("").trim();
+  };
+  const buildHandoff = async (sessionID, assistantMessageID, instruction) => {
+    await log("info", "buildHandoff called", { sessionID, assistantMessageID });
+    let messages;
+    try {
+      const response = await client.session.messages({
+        path: { id: sessionID }
+      });
+      messages = getResponseData(response);
+      await log("info", `Fetched ${messages.length} messages`);
+    } catch (err) {
+      await log("error", `Failed to fetch messages: ${err}`);
+      throw err;
+    }
+    const assistantMessage = messages.find((message) => message.info.id === assistantMessageID);
+    await log("info", `Looking for message id=${assistantMessageID}`);
+    await log("info", `Assistant message found: ${!!assistantMessage}`);
+    const handoffText = extractMessageText(assistantMessage);
+    if (!handoffText) {
+      await log("error", "No handoff text found");
+      throw new Error("No handoff content returned from the command");
+    }
+    await log("info", `Handoff text length: ${handoffText.length}`);
+    const providerID = assistantMessage?.info.providerID;
+    const modelID = assistantMessage?.info.modelID;
+    await log("info", `Using model: ${providerID}/${modelID}`);
+    const fileRefs = parseFileReferences(handoffText);
+    await log("info", `Found ${fileRefs.size} file references`, { files: Array.from(fileRefs) });
+    let fileParts = [];
+    if (fileRefs.size > 0) {
+      fileParts = await buildSyntheticFileParts(directory, fileRefs);
+      await log("info", `Built ${fileParts.length} synthetic file parts`);
+    }
+    let createdSessionId;
+    try {
+      const created = await client.session.create({ body: {} });
+      const createdSession = getResponseData(created);
+      createdSessionId = createdSession.id;
+      await log("info", `Created session: ${createdSessionId}`);
+    } catch (err) {
+      await log("error", `Failed to create session: ${err}`);
+      throw err;
+    }
+    await client.tui.showToast({
+      body: {
+        message: `Handoff session created`,
+        variant: "success",
+        duration: 5000
+      }
+    });
+    const sessionReference = `Continuing work from session ${sessionID}. When you lack specific information you can use read_session to get it.`;
+    const fullHandoffText = `${sessionReference}
+
+${handoffText}`;
+    const promptBody = {
+      parts: [{ type: "text", text: fullHandoffText }, ...fileParts]
+    };
+    if (providerID && modelID) {
+      promptBody.model = { providerID, modelID };
+    }
+    client.session.prompt({
+      path: { id: createdSessionId },
+      body: promptBody
+    }).then(() => {
+      log("info", "AI response completed in handoff session");
+    }).catch((err) => {
+      log("error", `AI response failed: ${err}`);
+    });
+    await log("info", "Handoff session created, AI responding in background");
+  };
+  return {
+    config: async (config) => {
+      config.command = config.command || {};
+      config.command["handoff"] = {
+        description: "Create a focused handoff prompt for a new session",
+        template: HANDOFF_COMMAND
+      };
+    },
+    tool: {
+      read_session: ReadSession(client)
+    },
+    event: async ({ event }) => {
+      try {
+        if (event.type === "command.executed") {
+          await log("info", `Event received: ${event.type}`, { name: event.properties.name });
+          if (event.properties.name !== "handoff") {
+            return;
+          }
+          const props = event.properties;
+          await log("info", "Handoff command matched", props);
+          const instruction = props.arguments?.trim() ?? "";
+          if (!instruction) {
+            await promptForInstruction();
+            return;
+          }
+          await log("info", "About to call buildHandoff");
+          await buildHandoff(props.sessionID, props.messageID, instruction);
+          await log("info", "buildHandoff completed");
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        await log("error", `Event handler error: ${message}`);
+        await client.tui.showToast({
+          body: {
+            message: `Handoff failed: ${message}`,
+            variant: "error"
+          }
+        });
+      }
+    }
+  };
+};
+export {
+  HandoffPlugin
+};

package/dist/plugin/files.d.ts

@@ -0,0 +1,39 @@
+/**
+ * File reference parsing and building for handoff sessions.
+ *
+ * Handles extraction of @file references from handoff prompts and
+ * building synthetic text parts that match OpenCode's Read tool output format.
+ */
+/**
+ * File reference regex matching OpenCode's internal pattern.
+ * Matches @file references like @src/plugin.ts
+ */
+export declare const FILE_REGEX: RegExp;
+/**
+ * Synthetic text part matching OpenCode's TextPartInput structure.
+ */
+export type SyntheticTextPart = {
+    type: "text";
+    synthetic: true;
+    text: string;
+};
+/**
+ * Parse @file references from text.
+ *
+ * @param text - Text to search for @file references
+ * @returns Set of file paths referenced in the text
+ */
+export declare function parseFileReferences(text: string): Set<string>;
+/**
+ * Build synthetic text parts matching OpenCode's Read tool output.
+ *
+ * Creates two synthetic text parts for each file:
+ * 1. Header describing the Read tool call
+ * 2. Formatted file content with line numbers
+ *
+ * @param directory - Project directory to resolve relative paths against
+ * @param refs - Set of file path references to check
+ * @returns Array of synthetic text parts (non-existent and binary files are skipped)
+ */
+export declare function buildSyntheticFileParts(directory: string, refs: Set<string>): Promise<SyntheticTextPart[]>;
+//# sourceMappingURL=files.d.ts.map

package/dist/plugin/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../plugin/files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;GAGG;AACH,eAAO,MAAM,UAAU,QAA+C,CAAA;AAEtE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,IAAI,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAU7D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAoC9B"}

package/dist/plugin/handoff.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const HandoffPlugin: Plugin;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/plugin/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../plugin/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AA6DjD,eAAO,MAAM,aAAa,EAAE,MA8L3B,CAAA"}

package/dist/plugin/tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool definitions for opencode-handoff plugin.
+ *
+ * Factory functions that create tool definitions with injected dependencies:
+ * - ReadSession: Read conversation transcript from a session
+ */
+import type { PluginInput } from "@opencode-ai/plugin";
+export type OpencodeClient = PluginInput["client"];
+/**
+ * Create the read_session tool.
+ *
+ * Takes the OpenCode client as a dependency for session.messages() calls.
+ */
+export declare const ReadSession: (client: OpencodeClient) => {
+    description: string;
+    args: {
+        sessionID: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        sessionID: string;
+        limit?: number | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
+//# sourceMappingURL=tools.d.ts.map

package/dist/plugin/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../plugin/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAGtD,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAA;AAoDlD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,cAAc;;;;;;;;;;CA2BjD,CAAA"}

package/dist/plugin/vendor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Code extracted from OpenCode for compatibility.
+ *
+ * Source: https://github.com/sst/opencode
+ * File: packages/opencode/src/tool/read.ts
+ *
+ * These functions and constants are copied to ensure our synthetic file parts
+ * match OpenCode's Read tool output exactly.
+ */
+/**
+ * Constants from OpenCode's ReadTool
+ */
+export declare const DEFAULT_READ_LIMIT = 2000;
+export declare const MAX_LINE_LENGTH = 2000;
+/**
+ * Check if a file is binary (copied from OpenCode's ReadTool)
+ */
+export declare function isBinaryFile(filepath: string): Promise<boolean>;
+/**
+ * Format file content matching OpenCode's Read tool output format.
+ *
+ * @param _filepath - Absolute path to the file (unused in output, kept for signature compatibility)
+ * @param content - File content as string
+ * @returns Formatted output with line numbers in <file> tags
+ */
+export declare function formatFileContent(_filepath: string, content: string): string;
+//# sourceMappingURL=vendor.d.ts.map

package/dist/plugin/vendor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendor.d.ts","sourceRoot":"","sources":["../../plugin/vendor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;GAEG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AACtC,eAAO,MAAM,eAAe,OAAO,CAAA;AAWnC;;GAEG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiCrE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA4B5E"}

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "@andrewhampton/opencode-handoff",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Handoff command plugin for OpenCode - transfer context to a new session",
   "type": "module",
-  "main": "index.ts",
+  "main": "dist/index.js",
   "exports": {
-    ".": "./index.ts"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
   },
-  "types": "./index.ts",
+  "types": "./dist/index.d.ts",
   "files": [
-    "index.ts",
-    "plugin/"
+    "dist"
   ],
   "sideEffects": false,
+  "scripts": {
+    "build": "bun build index.ts --outfile dist/index.js --target node --packages external && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
   "keywords": [
     "opencode",
     "plugin",
@@ -33,6 +42,11 @@
   "peerDependencies": {
     "@opencode-ai/plugin": ">=1.0.0"
   },
+  "devDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0",
+    "@types/node": "^25.0.9",
+    "typescript": "^5.9.3"
+  },
   "publishConfig": {
     "access": "public"
   }

package/index.ts

@@ -1 +0,0 @@
-export { HandoffPlugin } from "./plugin/handoff.ts"

package/plugin/handoff.ts

@@ -1,182 +0,0 @@
-import type { Plugin } from "@opencode-ai/plugin"
-
-const getResponseData = <T>(response: { data?: T } | T): T => {
-  if (typeof response === "object" && response !== null && "data" in response) {
-    return response.data as T
-  }
-
-  return response as T
-}
-
-type MessageEntry = {
-  info: {
-    id: string
-    role: "user" | "assistant"
-    parentID?: string
-    providerID?: string
-    modelID?: string
-  }
-  parts: Array<{ type: string; text?: string }>
-}
-
-export const HandoffPlugin: Plugin = async ({ client }) => {
-  const log = async (level: "info" | "error", message: string, extra?: object) => {
-    try {
-      await client.app.log({
-        body: {
-          service: "handoff",
-          level,
-          message,
-          extra,
-        },
-      })
-    } catch {
-      // Ignore log failures
-    }
-  }
-
-  const promptForInstruction = async () => {
-    await client.tui.showToast({
-      body: {
-        message: "Provide a handoff instruction after /handoff",
-        variant: "warning",
-      },
-    })
-    await client.tui.appendPrompt({ body: { text: "/handoff " } })
-  }
-
-  const extractMessageText = (entry?: MessageEntry) => {
-    if (!entry) {
-      return ""
-    }
-
-    return entry.parts
-      .filter((part) => part.type === "text")
-      .map((part) => part.text ?? "")
-      .join("")
-      .trim()
-  }
-
-  const buildHandoff = async (sessionID: string, assistantMessageID: string, instruction: string) => {
-    await log("info", "buildHandoff called", { sessionID, assistantMessageID })
-
-    let messages: Array<MessageEntry>
-    try {
-      const response = await client.session.messages({
-        path: { id: sessionID },
-      })
-      messages = getResponseData<Array<MessageEntry>>(response)
-      await log("info", `Fetched ${messages.length} messages`)
-    } catch (err) {
-      await log("error", `Failed to fetch messages: ${err}`)
-      throw err
-    }
-
-    // The messageID from command.executed is the assistant message itself
-    const assistantMessage = messages.find(
-      (message) => message.info.id === assistantMessageID
-    )
-
-    await log("info", `Looking for message id=${assistantMessageID}`)
-    await log("info", `Assistant message found: ${!!assistantMessage}`)
-
-    const handoffText = extractMessageText(assistantMessage)
-
-    if (!handoffText) {
-      await log("error", "No handoff text found")
-      throw new Error("No handoff content returned from the command")
-    }
-
-    await log("info", `Handoff text length: ${handoffText.length}`)
-
-    // Get the model from the assistant message
-    const providerID = assistantMessage?.info.providerID
-    const modelID = assistantMessage?.info.modelID
-    await log("info", `Using model: ${providerID}/${modelID}`)
-
-    let createdSessionId: string
-    try {
-      const created = await client.session.create({ body: {} })
-      const createdSession = getResponseData<{ id: string }>(created)
-      createdSessionId = createdSession.id
-      await log("info", `Created session: ${createdSessionId}`)
-    } catch (err) {
-      await log("error", `Failed to create session: ${err}`)
-      throw err
-    }
-
-    // Show toast immediately so user knows handoff is ready
-    await client.tui.showToast({
-      body: {
-        message: `Handoff session created`,
-        variant: "success",
-        duration: 5000,
-      },
-    })
-
-    // Send the prompt and trigger AI response (don't await - let it run in background)
-    const promptBody: {
-      parts: Array<{ type: "text"; text: string }>
-      model?: { providerID: string; modelID: string }
-    } = {
-      parts: [{ type: "text", text: handoffText }],
-    }
-
-    if (providerID && modelID) {
-      promptBody.model = { providerID, modelID }
-    }
-
-    client.session.prompt({
-      path: { id: createdSessionId },
-      body: promptBody,
-    }).then(() => {
-      log("info", "AI response completed in handoff session")
-    }).catch((err) => {
-      log("error", `AI response failed: ${err}`)
-    })
-
-    await log("info", "Handoff session created, AI responding in background")
-  }
-
-  return {
-    event: async ({ event }) => {
-      try {
-        if (event.type === "command.executed") {
-          await log("info", `Event received: ${event.type}`, { name: (event.properties as { name?: string }).name })
-          
-          if ((event.properties as { name?: string }).name !== "handoff") {
-            return
-          }
-
-          const props = event.properties as {
-            name: string
-            sessionID: string
-            messageID: string
-            arguments?: string
-          }
-
-          await log("info", "Handoff command matched", props)
-
-          const instruction = props.arguments?.trim() ?? ""
-          if (!instruction) {
-            await promptForInstruction()
-            return
-          }
-
-          await log("info", "About to call buildHandoff")
-          await buildHandoff(props.sessionID, props.messageID, instruction)
-          await log("info", "buildHandoff completed")
-        }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err)
-        await log("error", `Event handler error: ${message}`)
-        await client.tui.showToast({
-          body: {
-            message: `Handoff failed: ${message}`,
-            variant: "error",
-          },
-        })
-      }
-    },
-  }
-}