Apply PR #12755: feat(session): add handoff functionality and agent updates

Author: opencode-agent[bot]

packages/opencode/src/agent/agent.ts

@@ -184,6 +184,18 @@ export namespace Agent {
         ),
         prompt: PROMPT_TITLE,
       },
+      handoff: {
+        name: "handoff",
+        mode: "primary",
+        options: {},
+        native: true,
+        hidden: true,
+        temperature: 0.5,
+        permission: PermissionNext.fromConfig({
+          "*": "allow",
+        }),
+        prompt: "none",
+      },
       summary: {
         name: "summary",
         mode: "primary",

packages/opencode/src/cli/cmd/tui/component/dialog-command.tsx

@@ -83,6 +83,7 @@ function init() {
     },
     slashes() {
       return visibleOptions().flatMap((option) => {
+        if (option.disabled) return []
         const slash = option.slash
         if (!slash) return []
         return {

packages/opencode/src/cli/cmd/tui/component/prompt/history.tsx

@@ -9,7 +9,7 @@ import type { AgentPart, FilePart, TextPart } from "@opencode-ai/sdk/v2"
 
 export type PromptInfo = {
   input: string
-  mode?: "normal" | "shell"
+  mode?: "normal" | "shell" | "handoff"
   parts: (
     | Omit<FilePart, "id" | "messageID" | "sessionID">
     | Omit<AgentPart, "id" | "messageID" | "sessionID">

packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx

@@ -120,7 +120,7 @@ export function Prompt(props: PromptProps) {
 
   const [store, setStore] = createStore<{
     prompt: PromptInfo
-    mode: "normal" | "shell"
+    mode: "normal" | "shell" | "handoff"
     extmarkToPartIndex: Map<number, number>
     interrupt: number
     placeholder: number
@@ -349,6 +349,20 @@ export function Prompt(props: PromptProps) {
           ))
         },
       },
+      {
+        title: "Handoff",
+        value: "prompt.handoff",
+        disabled: props.sessionID === undefined,
+        category: "Prompt",
+        slash: {
+          name: "handoff",
+        },
+        onSelect: () => {
+          input.clear()
+          setStore("mode", "handoff")
+          setStore("prompt", { input: "", parts: [] })
+        },
+      },
     ]
   })
 
@@ -526,17 +540,45 @@ export function Prompt(props: PromptProps) {
   async function submit() {
     if (props.disabled) return
     if (autocomplete?.visible) return
+    const selectedModel = local.model.current()
+    if (!selectedModel) {
+      promptModelWarning()
+      return
+    }
+
+    if (store.mode === "handoff") {
+      const result = await sdk.client.session.handoff({
+        sessionID: props.sessionID!,
+        goal: store.prompt.input,
+        model: {
+          providerID: selectedModel.providerID,
+          modelID: selectedModel.modelID,
+        },
+      })
+      if (result.data) {
+        route.navigate({
+          type: "home",
+          initialPrompt: {
+            input: result.data.text,
+            parts:
+              result.data.files.map((file) => ({
+                type: "file",
+                url: file,
+                filename: file,
+                mime: "text/plain",
+              })) ?? [],
+          },
+        })
+      }
+      return
+    }
+
     if (!store.prompt.input) return
     const trimmed = store.prompt.input.trim()
     if (trimmed === "exit" || trimmed === "quit" || trimmed === ":q") {
       exit()
       return
     }
-    const selectedModel = local.model.current()
-    if (!selectedModel) {
-      promptModelWarning()
-      return
-    }
     const sessionID = props.sessionID
       ? props.sessionID
       : await (async () => {
@@ -737,6 +779,7 @@ export function Prompt(props: PromptProps) {
   const highlight = createMemo(() => {
     if (keybind.leader) return theme.border
     if (store.mode === "shell") return theme.primary
+    if (store.mode === "handoff") return theme.warning
     return local.agent.color(local.agent.current().name)
   })
 
@@ -748,6 +791,7 @@ export function Prompt(props: PromptProps) {
   })
 
   const placeholderText = createMemo(() => {
+    if (store.mode === "handoff") return "Goal for the new session"
     if (props.sessionID) return undefined
     if (store.mode === "shell") {
       const example = SHELL_PLACEHOLDERS[store.placeholder % SHELL_PLACEHOLDERS.length]
@@ -875,7 +919,7 @@ export function Prompt(props: PromptProps) {
                   e.preventDefault()
                   return
                 }
-                if (store.mode === "shell") {
+                if (store.mode === "shell" || store.mode === "handoff") {
                   if ((e.name === "backspace" && input.visualCursor.offset === 0) || e.name === "escape") {
                     setStore("mode", "normal")
                     e.preventDefault()
@@ -996,7 +1040,11 @@ export function Prompt(props: PromptProps) {
             />
             <box flexDirection="row" flexShrink={0} paddingTop={1} gap={1}>
               <text fg={highlight()}>
-                {store.mode === "shell" ? "Shell" : Locale.titlecase(local.agent.current().name)}{" "}
+                <Switch>
+                  <Match when={store.mode === "normal"}>{Locale.titlecase(local.agent.current().name)}</Match>
+                  <Match when={store.mode === "shell"}>Shell</Match>
+                  <Match when={store.mode === "handoff"}>Handoff</Match>
+                </Switch>
               </text>
               <Show when={store.mode === "normal"}>
                 <box flexDirection="row" gap={1}>
@@ -1143,6 +1191,11 @@ export function Prompt(props: PromptProps) {
                     esc <span style={{ fg: theme.textMuted }}>exit shell mode</span>
                   </text>
                 </Match>
+                <Match when={store.mode === "handoff"}>
+                  <text fg={theme.text}>
+                    esc <span style={{ fg: theme.textMuted }}>exit handoff mode</span>
+                  </text>
+                </Match>
               </Switch>
             </box>
           </Show>

packages/opencode/src/cli/cmd/tui/context/route.tsx

@@ -1,4 +1,4 @@
-import { createStore } from "solid-js/store"
+import { createStore, reconcile } from "solid-js/store"
 import { createSimpleContext } from "./helper"
 import type { PromptInfo } from "../component/prompt/history"
 
@@ -32,7 +32,7 @@ export const { use: useRoute, provider: RouteProvider } = createSimpleContext({
       },
       navigate(route: Route) {
         console.log("navigate", route)
-        setStore(route)
+        setStore(reconcile(route))
       },
     }
   },

packages/opencode/src/server/routes/session.ts

@@ -7,6 +7,7 @@ import { MessageV2 } from "../../session/message-v2"
 import { SessionPrompt } from "../../session/prompt"
 import { SessionCompaction } from "../../session/compaction"
 import { SessionRevert } from "../../session/revert"
+import { SessionHandoff } from "../../session/handoff"
 import { SessionStatus } from "@/session/status"
 import { SessionSummary } from "@/session/summary"
 import { Todo } from "../../session/todo"
@@ -932,5 +933,41 @@ export const SessionRoutes = lazy(() =>
         })
         return c.json(true)
       },
+    )
+    .post(
+      "/:sessionID/handoff",
+      describeRoute({
+        summary: "Handoff session",
+        description: "Extract context and relevant files for another agent to continue the conversation.",
+        operationId: "session.handoff",
+        responses: {
+          200: {
+            description: "Handoff data extracted",
+            content: {
+              "application/json": {
+                schema: resolver(z.object({ text: z.string(), files: z.string().array() })),
+              },
+            },
+          },
+          ...errors(400, 404),
+        },
+      }),
+      validator(
+        "param",
+        z.object({
+          sessionID: z.string().meta({ description: "Session ID" }),
+        }),
+      ),
+      validator("json", SessionHandoff.handoff.schema.omit({ sessionID: true })),
+      async (c) => {
+        const params = c.req.valid("param")
+        const body = c.req.valid("json")
+        const result = await SessionHandoff.handoff({
+          sessionID: params.sessionID,
+          model: body.model,
+          goal: body.goal,
+        })
+        return c.json(result)
+      },
     ),
 )

packages/opencode/src/session/handoff.ts

@@ -0,0 +1,105 @@
+import { fn } from "@/util/fn"
+import z from "zod"
+import { MessageV2 } from "./message-v2"
+import { LLM } from "./llm"
+import { Agent } from "@/agent/agent"
+import { Provider } from "@/provider/provider"
+import { iife } from "@/util/iife"
+import { Identifier } from "@/id/id"
+import PROMPT_HANDOFF from "./prompt/handoff.txt"
+import { type Tool } from "ai"
+import { SessionStatus } from "./status"
+import { defer } from "@/util/defer"
+
+export namespace SessionHandoff {
+  const HandoffTool: Tool = {
+    description:
+      "A tool to extract relevant information from the thread and select relevant files for another agent to continue the conversation. Use this tool to identify the most important context and files needed.",
+    inputSchema: z.object({
+      text: z.string().describe(PROMPT_HANDOFF),
+      files: z
+        .string()
+        .array()
+        .describe(
+          [
+            "An array of file or directory paths (workspace-relative) that are relevant to accomplishing the goal.",
+            "",
+            'IMPORTANT: Return as a JSON array of strings, e.g., ["packages/core/src/session/message-v2.ts", "packages/core/src/session/prompt/handoff.txt"]',
+            "",
+            "Rules:",
+            "- Maximum 10 files. Only include the most critical files needed for the task.",
+            "- You can include directories if multiple files from that directory are needed",
+            "- Prioritize by importance and relevance. PUT THE MOST IMPORTANT FILES FIRST.",
+            '- Return workspace-relative paths (e.g., "packages/core/src/session/message-v2.ts")',
+            "- Do not use absolute paths or invent files",
+          ].join("\n"),
+        ),
+    }),
+    async execute(_args, _ctx) {
+      return {}
+    },
+  }
+
+  export const handoff = fn(
+    z.object({
+      sessionID: z.string(),
+      model: z.object({ providerID: z.string(), modelID: z.string() }),
+      goal: z.string().optional(),
+    }),
+    async (input) => {
+      SessionStatus.set(input.sessionID, { type: "busy" })
+      using _ = defer(() => SessionStatus.set(input.sessionID, { type: "idle" }))
+      const messages = await MessageV2.filterCompacted(MessageV2.stream(input.sessionID))
+      const agent = await Agent.get("handoff")
+      const model = await iife(async () => {
+        if (agent.model) return Provider.getModel(agent.model.providerID, agent.model.modelID)
+        const small = await Provider.getSmallModel(input.model.providerID)
+        if (small) return small
+        return Provider.getModel(input.model.providerID, input.model.modelID)
+      })
+      const user = {
+        info: {
+          model: {
+            providerID: model.providerID,
+            modelID: model.id,
+          },
+          agent: agent.name,
+          sessionID: input.sessionID,
+          id: Identifier.ascending("user"),
+          role: "user",
+          time: {
+            created: Date.now(),
+          },
+        } satisfies MessageV2.User,
+        parts: [
+          {
+            type: "text",
+            text: PROMPT_HANDOFF + "\n\nMy request:\n" + (input.goal ?? "general summarization"),
+            id: Identifier.ascending("part"),
+            sessionID: input.sessionID,
+            messageID: Identifier.ascending("message"),
+          },
+        ] satisfies MessageV2.TextPart[],
+      } satisfies MessageV2.WithParts
+      const abort = new AbortController()
+      const stream = await LLM.stream({
+        agent,
+        messages: MessageV2.toModelMessages([...messages, user], model),
+        sessionID: input.sessionID,
+        abort: abort.signal,
+        model,
+        system: [],
+        small: true,
+        user: user.info,
+        output: "tool",
+        tools: {
+          handoff: HandoffTool,
+        },
+      })
+
+      const [result] = await stream.toolCalls
+      if (!result) throw new Error("Handoff tool did not return a result")
+      return result.input
+    },
+  )
+}

packages/opencode/src/session/llm.ts

@@ -38,6 +38,7 @@ export namespace LLM {
     small?: boolean
     tools: Record<string, Tool>
     retries?: number
+    output?: "tool"
     toolChoice?: "auto" | "required" | "none"
   }
 
@@ -209,6 +210,7 @@ export namespace LLM {
       toolChoice: input.toolChoice,
       maxOutputTokens,
       abortSignal: input.abort,
+      toolChoice: input.output === "tool" ? "required" : undefined,
       headers: {
         ...(input.model.providerID.startsWith("opencode")
           ? {

packages/opencode/src/session/prompt/handoff.txt

@@ -0,0 +1,17 @@
+Extract relevant context from the conversation above for continuing this work. Write from my perspective (first person: "I did...", "I told you...").
+
+Consider what would be useful to know based on my request below. Questions that might be relevant:
+
+- What did I just do or implement?
+- What instructions did I already give you which are still relevant (e.g. follow patterns in the codebase)?
+- What files did I already tell you that's important or that I am working on (and should continue working on)?
+- Did I provide a plan or spec that should be included?
+- What did I already tell you that's important (certain libraries, patterns, constraints, preferences)?
+- What important technical details did I discover (APIs, methods, patterns)?
+- What caveats, limitations, or open questions did I find?
+
+Extract what matters for the specific request below. Don't answer questions that aren't relevant. Pick an appropriate length based on the complexity of the request.
+
+Focus on capabilities and behavior, not file-by-file changes. Avoid excessive implementation details (variable names, storage keys, constants) unless critical.
+
+Format: Plain text with bullets. No markdown headers, no bold/italic, no code fences. Use workspace-relative paths for files.