Fix: session_handoff tool not triggering (bristena-op#9)

* feat: add chat.message hook to reliably trigger session_handoff tool

* fix: add Zod schema for session_handoff tool args

Author: mariusom

index.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { buildHandoffPrompt, type HandoffArgs } from "./prompt.ts";
+import { isHandoffTrigger, extractGoalFromHandoff } from "./index.ts";
 
 const baseArgs: HandoffArgs = {
   previousSessionId: "ses_123",
@@ -95,3 +96,68 @@ describe("buildHandoffPrompt - next steps", () => {
     expect(build({ next_steps: [] })).not.toContain("**Next:**");
   });
 });
+
+describe("isHandoffTrigger", () => {
+  it("returns true for 'handoff'", () => {
+    expect(isHandoffTrigger("handoff")).toBe(true);
+    expect(isHandoffTrigger("Handoff")).toBe(true);
+    expect(isHandoffTrigger("HANDOFF")).toBe(true);
+    expect(isHandoffTrigger("  handoff  ")).toBe(true);
+  });
+
+  it("returns true for '/handoff'", () => {
+    expect(isHandoffTrigger("/handoff")).toBe(true);
+    expect(isHandoffTrigger("/Handoff")).toBe(true);
+    expect(isHandoffTrigger("  /handoff  ")).toBe(true);
+  });
+
+  it("returns true for 'session handoff'", () => {
+    expect(isHandoffTrigger("session handoff")).toBe(true);
+    expect(isHandoffTrigger("Session Handoff")).toBe(true);
+  });
+
+  it("returns true for 'handoff <goal>'", () => {
+    expect(isHandoffTrigger("handoff implement login")).toBe(true);
+    expect(isHandoffTrigger("handoff fix the bug")).toBe(true);
+  });
+
+  it("returns true for '/handoff <goal>'", () => {
+    expect(isHandoffTrigger("/handoff implement login")).toBe(true);
+    expect(isHandoffTrigger("/handoff fix tests")).toBe(true);
+  });
+
+  it("returns false for non-handoff messages", () => {
+    expect(isHandoffTrigger("implement handoff feature")).toBe(false);
+    expect(isHandoffTrigger("hello world")).toBe(false);
+    expect(isHandoffTrigger("hand off the work")).toBe(false);
+  });
+});
+
+describe("extractGoalFromHandoff", () => {
+  it("extracts goal from 'handoff <goal>'", () => {
+    expect(extractGoalFromHandoff("handoff implement login")).toBe("implement login");
+    expect(extractGoalFromHandoff("handoff fix the failing tests")).toBe("fix the failing tests");
+    expect(extractGoalFromHandoff("Handoff Create PR")).toBe("Create PR");
+  });
+
+  it("extracts goal from '/handoff <goal>'", () => {
+    expect(extractGoalFromHandoff("/handoff implement login")).toBe("implement login");
+    expect(extractGoalFromHandoff("/handoff fix tests")).toBe("fix tests");
+  });
+
+  it("returns null for standalone handoff", () => {
+    expect(extractGoalFromHandoff("handoff")).toBe(null);
+    expect(extractGoalFromHandoff("/handoff")).toBe(null);
+    expect(extractGoalFromHandoff("  handoff  ")).toBe(null);
+  });
+
+  it("returns null for 'handoff ' with only whitespace after", () => {
+    expect(extractGoalFromHandoff("handoff   ")).toBe(null);
+    expect(extractGoalFromHandoff("/handoff   ")).toBe(null);
+  });
+
+  it("returns null for non-handoff messages", () => {
+    expect(extractGoalFromHandoff("hello world")).toBe(null);
+    expect(extractGoalFromHandoff("session handoff")).toBe(null);
+  });
+});

index.ts

@@ -1,5 +1,6 @@
 import type { Plugin, PluginInput } from "@opencode-ai/plugin";
 import type { Message, Part } from "@opencode-ai/sdk";
+import { z } from "zod";
 import { buildHandoffPrompt } from "./prompt.ts";
 import { createAutoUpdateHook } from "./auto-update.ts";
 
@@ -210,6 +211,15 @@ async function executeHandoff(
   return `✓ Session "${newTitle}" created (${context.agent || "default"} · ${modelDisplay}). Select it from the picker.`;
 }
 
+const handoffArgsSchema = {
+  summary: z.string().describe("1-3 sentence summary of current state (required)"),
+  goal: z.string().optional().describe("Goal for the next session if user specified one"),
+  next_steps: z.array(z.string()).optional().describe("Array of remaining tasks"),
+  blocked: z.string().optional().describe("Current blocker if any"),
+  key_decisions: z.array(z.string()).optional().describe("Important decisions made"),
+  files_modified: z.array(z.string()).optional().describe("Key files that were changed"),
+};
+
 function createHandoffTool(pluginCtx: PluginContext) {
   return {
     description: `Generate a compact continuation prompt and start a new session with it.
@@ -222,16 +232,8 @@ When called, this tool:
 
 IMPORTANT: You MUST provide a concise summary. Do not dump the entire conversation - distill it to essential context only.
 
-Arguments (pass as JSON object):
-- summary (required): 1-3 sentence summary of current state
-- goal (optional): If the user said "handoff <something>" or "session_handoff <something>", extract what comes after as the goal for the next session
-- next_steps (optional): Array of remaining tasks
-- blocked (optional): Current blocker if any
-- key_decisions (optional): Array of important decisions made
-- files_modified (optional): Array of key files changed
-
 The new session will have access to \`read_session\` tool if more context is needed later.`,
-    args: {},
+    args: handoffArgsSchema,
     async execute(args: Record<string, unknown>, ctx: { sessionID: string }) {
       return executeHandoff(pluginCtx, args as unknown as HandoffToolArgs, ctx.sessionID);
     },
@@ -290,6 +292,30 @@ This tool fetches the last 20 messages which uses significant tokens. The handof
   };
 }
 
+export function isHandoffTrigger(text: string): boolean {
+  const trimmed = text.trim().toLowerCase();
+  return (
+    trimmed === "handoff" ||
+    trimmed === "/handoff" ||
+    trimmed === "session handoff" ||
+    trimmed.startsWith("handoff ") ||
+    trimmed.startsWith("/handoff ")
+  );
+}
+
+export function extractGoalFromHandoff(text: string): string | null {
+  const trimmed = text.trim();
+  const lower = trimmed.toLowerCase();
+
+  if (lower.startsWith("/handoff ")) {
+    return trimmed.slice(9).trim() || null;
+  }
+  if (lower.startsWith("handoff ")) {
+    return trimmed.slice(8).trim() || null;
+  }
+  return null;
+}
+
 const HandoffPlugin: Plugin = async (ctx) => {
   const autoUpdateHook = createAutoUpdateHook({
     directory: ctx.directory,
@@ -309,6 +335,46 @@ const HandoffPlugin: Plugin = async (ctx) => {
         client: ctx.client,
       }),
     },
+    "chat.message": async (
+      _input: {
+        sessionID: string;
+        agent?: string;
+        model?: { providerID: string; modelID: string };
+        messageID?: string;
+        variant?: string;
+      },
+      output: { message: unknown; parts: Part[] },
+    ) => {
+      const textParts = output.parts.filter(
+        (p): p is Part & { type: "text"; text: string } =>
+          p.type === "text" && typeof (p as { text?: string }).text === "string",
+      );
+
+      for (const part of textParts) {
+        if (isHandoffTrigger(part.text)) {
+          const goal = extractGoalFromHandoff(part.text);
+
+          part.text = [
+            '<system-instruction priority="critical">',
+            "The user has triggered a session handoff. You MUST invoke the `session_handoff` tool immediately.",
+            "",
+            "DO NOT interpret this as a regular task request.",
+            "DO NOT continue working on any previous tasks.",
+            "DO NOT ask clarifying questions.",
+            "",
+            "IMMEDIATELY call the session_handoff tool with:",
+            "- summary: A brief summary of what was accomplished in this session",
+            goal ? `- goal: "${goal}"` : "- goal: (not specified)",
+            "- next_steps: Any remaining tasks from the todo list",
+            "- key_decisions: Important decisions made during the session",
+            "- files_modified: Key files that were changed",
+            "</system-instruction>",
+          ].join("\n");
+
+          break;
+        }
+      }
+    },
   };
 };