opencode-amp-like-handoff 0.2.0

package/README.md

@@ -0,0 +1,191 @@
+# opencode-amp-like-handoff
+
+Amp-like new-session handoff plugin for [OpenCode](https://opencode.ai).
+
+## What it does
+
+When an AI coding session accumulates enough context that starting fresh would be more efficient, `/handoff` distills the relevant context into a new session — avoiding the costly "file archaeology" phase where the AI re-discovers files, decisions, and patterns from scratch.
+
+- Registers a `/handoff <goal>` command that triggers a structured context-transfer workflow
+- The model analyzes the current conversation, extracts context relevant to the stated goal, and identifies the most important files (targeting 8–15, up to 20 for complex work)
+- Creates a new session with the handoff prompt as an **editable draft** — the user reviews it, edits if needed, and sends when ready
+- Files are referenced as `@file` markers in the draft (e.g., `@src/plugin.ts`); their contents are **auto-injected** when the user sends the message
+- File contents match **OpenCode's Read tool format** (5-digit zero-padded line numbers, `<file>` tags), so the AI treats them identically to files it read itself
+- Binary files are detected by extension and byte analysis, and silently skipped
+- Records the source session ID so the new session knows where it came from
+- Provides `read_session` to pull conversation transcript from the source session on demand
+- Logs all operations via `app.log` for observability
+
+## Usage
+
+```
+/handoff <your next goal>
+```
+
+**Example:**
+
+```
+/handoff Refactor the auth module to use JWT instead of sessions
+```
+
+When invoked, the model:
+
+1. Reads the current conversation to infer task status
+2. Extracts decisions, constraints, user preferences, technical patterns, blockers, and exact next steps relevant to the stated goal
+3. Identifies 8–15 relevant files (source files, dependencies, tests, configs)
+4. Calls `handoff_session` with a focused continuation prompt and file list
+5. A new session opens with the handoff as an **editable draft** — review it, make changes, and press Enter to send
+6. When the message is sent, the `chat.message` hook automatically parses `@file` references, reads file contents from disk, and injects them as synthetic parts matching the Read tool format
+
+In the new session, `read_session` is available to pull message history from the source session on demand if more detail is needed.
+
+## Tools
+
+### `handoff_session`
+
+Creates a new session with the handoff prompt as an editable draft. File contents are auto-loaded when the user sends the message.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | `string` | yes | The generated handoff prompt with context and goals. Must be non-empty. |
+| `files` | `string[]` | no | File paths to load into the new session context (8–15 recommended). Leading `@` is stripped automatically. Duplicates and blank entries are ignored. |
+
+**Success response:**
+
+```ts
+{
+  ok: true,
+  sourceSessionId: string,  // ID of the session that initiated the handoff
+  files: string[],           // deduplicated list of file paths
+  message: string            // confirmation message
+}
+```
+
+**Error response:**
+
+```ts
+{ ok: false, error: string }
+```
+
+Errors are returned (not thrown) for: empty prompt, or failure to create the draft session.
+
+---
+
+### `read_session`
+
+Reads conversation transcript from a previous session. Returns a formatted markdown transcript with `## User` and `## Assistant` sections.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `sessionId` | `string` | yes | The full session ID (e.g., `sess_01jxyz...`). Must be non-empty. |
+| `limit` | `number` | no | Maximum number of messages to read. Clamped to 1–500. Defaults to `100`. |
+
+**Success response:**
+
+```ts
+{
+  ok: true,
+  sessionId: string,
+  count: number,
+  transcript: string  // formatted markdown transcript
+}
+```
+
+**Error response:**
+
+```ts
+{ ok: false, error: string }
+```
+
+## How it works
+
+### Editable draft workflow
+
+Unlike a direct `session.create()` + `session.prompt()` approach that auto-injects context without user review, this plugin uses an editable draft workflow:
+
+1. `handoff_session` calls `tui.executeCommand({ command: "session_new" })` to create a new session and navigate to it
+2. After a short delay (200ms for the TUI to mount), it calls `tui.appendPrompt()` to populate the prompt input with the handoff text
+3. The user sees the full handoff prompt as editable text — they can modify, remove, or add context before sending
+
+### Automatic file injection
+
+When the user sends the handoff message, the `chat.message` hook:
+
+1. Detects messages containing "Continuing work from session" (the marker placed by the handoff tool)
+2. Parses `@file` references using the `FILE_REGEX` pattern
+3. Reads each file from disk, skipping binary files and unreadable paths
+4. Formats content with 5-digit zero-padded line numbers and `<file>` tags, matching OpenCode's Read tool output
+5. Injects synthetic text parts into the session via `session.prompt({ noReply: true })` — the AI sees them as if it called the Read tool itself
+
+Each session is tracked in a `processedSessions` set to prevent duplicate injection. The set is cleaned up via the `event` hook when sessions are deleted.
+
+### File format
+
+Files are formatted to match OpenCode's Read tool output:
+
+```
+Called the Read tool with the following input: {"filePath": "/abs/path/to/file.ts"}
+
+<file>
+00001| import { foo } from "./bar"
+00002| 
+00003| export function hello() {
+00004|   return "world"
+00005| }
+00006| 
+
+(End of file - total 6 lines)
+</file>
+```
+
+- Lines are zero-padded to 5 digits with a `| ` separator
+- Lines longer than 2000 characters are truncated
+- Files longer than 2000 lines show only the first 2000
+
+## Project structure
+
+```
+src/
+  plugin.ts   — Main plugin: hooks, handoff template, session lifecycle
+  tools.ts    — HandoffSession and ReadSession tool definitions
+  files.ts    — Binary detection, Read tool format, @file reference parsing
+```
+
+## Install locally
+
+Place this plugin in a plugins directory supported by OpenCode:
+
+- `.opencode/plugins/opencode-amp-like-handoff/` — project-level (checked into the repo)
+- `~/.config/opencode/plugins/opencode-amp-like-handoff/` — user-level (applies to all projects)
+
+Example directory tree:
+
+```text
+.opencode/
+  plugins/
+    opencode-amp-like-handoff/
+      package.json
+      tsconfig.json
+      src/
+        plugin.ts
+        tools.ts
+        files.ts
+```
+
+OpenCode picks up the plugin automatically on startup. If the plugin directory contains a `package.json`, OpenCode runs `bun install` to resolve dependencies before loading.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Type-check without emitting output
+bun run typecheck
+```
+
+TypeScript configuration: strict mode, `bundler` module resolution, `ESNext` target. The plugin runs directly as TypeScript via Bun — no build step required.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "opencode-amp-like-handoff",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Amp-like new-session handoff plugin for OpenCode",
+  "main": "src/plugin.ts",
+  "exports": {
+    ".": "./src/plugin.ts"
+  },
+  "files": ["src"],
+  "author": "cuongnt3",
+  "license": "MIT",
+  "keywords": ["opencode", "plugin", "handoff", "session"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cuongntr/opencode-amp-like-handoff.git"
+  },
+  "homepage": "https://github.com/cuongntr/opencode-amp-like-handoff#readme",
+  "bugs": {
+    "url": "https://github.com/cuongntr/opencode-amp-like-handoff/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/files.ts

@@ -0,0 +1,224 @@
+/**
+ * File reference parsing, binary detection, and synthetic part building.
+ *
+ * Handles @file references from handoff prompts and builds synthetic text
+ * parts that match OpenCode's Read tool output format (line numbers, <file>
+ * tags) so the AI treats them identically to files it read itself.
+ */
+
+import * as path from "node:path"
+import * as fs from "node:fs/promises"
+
+// ---------------------------------------------------------------------------
+// Constants (matching OpenCode's ReadTool)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_READ_LIMIT = 2000
+const MAX_LINE_LENGTH = 2000
+
+const BINARY_EXTENSIONS = new Set([
+  // Archives
+  ".7z",
+  ".gz",
+  ".jar",
+  ".tar",
+  ".war",
+  ".zip",
+  // Compiled / object
+  ".a",
+  ".bin",
+  ".class",
+  ".dat",
+  ".dll",
+  ".exe",
+  ".lib",
+  ".o",
+  ".obj",
+  ".pyc",
+  ".pyo",
+  ".so",
+  ".wasm",
+  // Documents
+  ".doc",
+  ".docx",
+  ".ods",
+  ".odt",
+  ".odp",
+  ".pdf",
+  ".ppt",
+  ".pptx",
+  ".xls",
+  ".xlsx",
+  // Images
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".png",
+  ".tiff",
+  ".webp",
+  // Audio / Video
+  ".mp3",
+  ".mp4",
+  ".ogg",
+  ".wav",
+  ".webm",
+  // Fonts
+  ".eot",
+  ".otf",
+  ".ttf",
+  ".woff",
+  ".woff2",
+])
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SyntheticTextPart = {
+  type: "text"
+  text: string
+  synthetic: true
+}
+
+// ---------------------------------------------------------------------------
+// @file reference regex
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches @file references like `@src/plugin.ts` or `@./config.json`.
+ * Must not be preceded by a word char or backtick to avoid false positives
+ * inside inline code or email addresses.
+ */
+export const FILE_REGEX = /(?<![\w`])@(\.?[^\s`,.]*(?:\.[^\s`,.]+)*)/g
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract unique @file references from text.
+ */
+export function parseFileReferences(text: string): Set<string> {
+  const refs = new Set<string>()
+  for (const match of text.matchAll(FILE_REGEX)) {
+    if (match[1]) refs.add(match[1])
+  }
+  return refs
+}
+
+/**
+ * Check whether a file is binary by extension or by sampling content bytes.
+ */
+export async function isBinaryFile(filepath: string): Promise<boolean> {
+  const ext = path.extname(filepath).toLowerCase()
+  if (BINARY_EXTENSIONS.has(ext)) return true
+
+  try {
+    const buffer = await fs.readFile(filepath)
+    if (!buffer || buffer.length === 0) return false
+
+    const sample = buffer.subarray(0, Math.min(4096, buffer.length))
+    let nonPrintable = 0
+
+    for (let i = 0; i < sample.length; i++) {
+      const byte = sample[i]
+      if (byte === undefined) continue
+      // Null byte → binary
+      if (byte === 0) return true
+      // Control chars outside whitespace range
+      if (byte < 9 || (byte > 13 && byte < 32)) nonPrintable++
+    }
+
+    return nonPrintable / sample.length > 0.3
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Format file content matching OpenCode's Read tool output.
+ *
+ * - 5-digit zero-padded line numbers with `| ` separator
+ * - Lines truncated at MAX_LINE_LENGTH
+ * - Content limited to DEFAULT_READ_LIMIT lines
+ * - Wrapped in `<file>` / `</file>` tags
+ */
+export function formatFileContent(
+  _filepath: string,
+  content: string,
+): string {
+  const lines = content.split("\n")
+  const limit = DEFAULT_READ_LIMIT
+
+  const visible = lines.slice(0, limit).map((line) =>
+    line.length > MAX_LINE_LENGTH
+      ? line.substring(0, MAX_LINE_LENGTH) + "..."
+      : line,
+  )
+
+  const numbered = visible.map(
+    (line, i) => `${(i + 1).toString().padStart(5, "0")}| ${line}`,
+  )
+
+  let output = "<file>\n"
+  output += numbered.join("\n")
+
+  if (lines.length > visible.length) {
+    output += `\n\n(File has more lines. Use 'offset' parameter to read beyond line ${visible.length})`
+  } else {
+    output += `\n\n(End of file - total ${lines.length} lines)`
+  }
+  output += "\n</file>"
+
+  return output
+}
+
+/**
+ * Build synthetic text parts for a set of @file references.
+ *
+ * Creates two synthetic parts per file, matching what OpenCode's Read tool
+ * produces:
+ *   1. Header: "Called the Read tool with the following input: ..."
+ *   2. Body:   Formatted file content with line numbers inside <file> tags
+ *
+ * Binary files and unreadable files are silently skipped.
+ */
+export async function buildSyntheticFileParts(
+  directory: string,
+  refs: Set<string>,
+): Promise<SyntheticTextPart[]> {
+  const parts: SyntheticTextPart[] = []
+
+  for (const ref of refs) {
+    const filepath = path.resolve(directory, ref)
+
+    try {
+      const stats = await fs.stat(filepath)
+      if (!stats.isFile()) continue
+      if (await isBinaryFile(filepath)) continue
+
+      const content = await fs.readFile(filepath, "utf-8")
+
+      // Header part — matches OpenCode's prompt.ts synthetic format
+      parts.push({
+        type: "text",
+        synthetic: true,
+        text: `Called the Read tool with the following input: ${JSON.stringify({ filePath: filepath })}`,
+      })
+
+      // Content part with line numbers and <file> tags
+      parts.push({
+        type: "text",
+        synthetic: true,
+        text: formatFileContent(filepath, content),
+      })
+    } catch {
+      // Skip files that cannot be read — one bad path should not
+      // block the rest of the handoff.
+    }
+  }
+
+  return parts
+}

package/src/plugin.ts

@@ -0,0 +1,178 @@
+/**
+ * Amp-like session handoff plugin for OpenCode.
+ *
+ * Provides `/handoff <goal>` to create a focused continuation session.
+ * The handoff prompt appears as an editable draft — the user reviews it,
+ * edits if needed, and sends. File contents are auto-injected when the
+ * message arrives, matching OpenCode's Read tool format so the AI treats
+ * them as if it read the files itself.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { HandoffSession, ReadSession } from "./tools"
+import { parseFileReferences, buildSyntheticFileParts } from "./files"
+
+// ---------------------------------------------------------------------------
+// Handoff template
+// ---------------------------------------------------------------------------
+
+const HANDOFF_TEMPLATE = `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
+
+   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,
+   blockers, and exact next steps.
+   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>
+
+---
+
+After generating the handoff message, IMMEDIATELY call handoff_session with
+your prompt and files:
+\`handoff_session(prompt="...", files=["src/foo.ts", "src/bar.ts", ...])\``
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+export const AmpLikeHandoffPlugin: Plugin = async (ctx) => {
+  // Track sessions that have already had file parts injected to avoid
+  // duplicate processing when chat.message fires multiple times.
+  const processedSessions = new Set<string>()
+
+  return {
+    // -----------------------------------------------------------------
+    // Register /handoff command
+    // -----------------------------------------------------------------
+    config: async (config) => {
+      config.command ||= {}
+      config.command.handoff = {
+        description: "Create a focused handoff prompt for a new session",
+        template: HANDOFF_TEMPLATE,
+      }
+    },
+
+    // -----------------------------------------------------------------
+    // Expose tools
+    // -----------------------------------------------------------------
+    tool: {
+      handoff_session: HandoffSession(ctx.client),
+      read_session: ReadSession(ctx.client),
+    },
+
+    // -----------------------------------------------------------------
+    // Auto-inject file contents when a handoff message arrives
+    // -----------------------------------------------------------------
+    "chat.message": async (_input, output) => {
+      const sessionID = output.message.sessionID
+
+      // Skip if we already injected files into this session
+      if (processedSessions.has(sessionID)) return
+
+      // Extract non-synthetic text from the message parts
+      const text = output.parts
+        .filter(
+          (p): p is typeof p & { type: "text"; text: string } =>
+            p.type === "text" && !p.synthetic && typeof p.text === "string",
+        )
+        .map((p) => p.text)
+        .join("\n")
+
+      // Only process messages that look like handoff continuations
+      if (!text.includes("Continuing work from session")) return
+
+      // Mark as processed immediately to prevent re-entry
+      processedSessions.add(sessionID)
+
+      // Parse @file references from the message text
+      const fileRefs = parseFileReferences(text)
+      if (fileRefs.size === 0) return
+
+      const fileParts = await buildSyntheticFileParts(ctx.directory, fileRefs)
+      if (fileParts.length === 0) return
+
+      // Inject synthetic file parts into the session without triggering a
+      // reply. Pass model and agent from the current message to prevent
+      // mode or model switching.
+      try {
+        await ctx.client.session.prompt({
+          path: { id: sessionID },
+          body: {
+            noReply: true,
+            model: output.message.model,
+            agent: output.message.agent,
+            parts: fileParts,
+          },
+        })
+
+        await ctx.client.app.log({
+          body: {
+            service: "handoff",
+            level: "info",
+            message: "Injected synthetic file parts",
+            extra: { sessionID, fileCount: fileRefs.size },
+          },
+        })
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err)
+        await ctx.client.app.log({
+          body: {
+            service: "handoff",
+            level: "error",
+            message: "Failed to inject file parts",
+            extra: { sessionID, error },
+          },
+        })
+      }
+    },
+
+    // -----------------------------------------------------------------
+    // Cleanup: remove tracking when sessions are deleted
+    // -----------------------------------------------------------------
+    event: async ({ event }) => {
+      if (event.type === "session.deleted") {
+        processedSessions.delete(event.properties.info.id)
+      }
+    },
+  }
+}
+
+export default AmpLikeHandoffPlugin

package/src/tools.ts

@@ -0,0 +1,245 @@
+/**
+ * Tool definitions for the handoff plugin.
+ *
+ * - HandoffSession: Creates new session with the handoff prompt as an
+ *   editable draft. File contents are injected later via chat.message hook.
+ * - ReadSession: Reads conversation transcript from a previous session with
+ *   formatted markdown output.
+ */
+
+import type { PluginInput } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+
+export type OpencodeClient = PluginInput["client"]
+
+// ---------------------------------------------------------------------------
+// HandoffSession
+// ---------------------------------------------------------------------------
+
+export const HandoffSession = (client: OpencodeClient) => {
+  return tool({
+    description:
+      "Create a new session with the handoff prompt as an editable draft. " +
+      "The user can review, edit, and send when ready. " +
+      "File contents are auto-loaded when the message is sent.",
+    args: {
+      prompt: tool.schema
+        .string()
+        .describe("The generated handoff prompt with context and goals"),
+      files: tool.schema
+        .array(tool.schema.string())
+        .optional()
+        .describe(
+          "File paths to load into the new session context (8-15 recommended)",
+        ),
+    },
+    async execute(
+      args: { prompt: string; files?: string[] },
+      context: { sessionID: string },
+    ) {
+      const prompt = args.prompt?.trim()
+      if (!prompt) {
+        return JSON.stringify({ ok: false, error: "Handoff prompt must not be empty." })
+      }
+
+      const sourceSessionId = context.sessionID
+      const sessionReference = `Continuing work from session ${sourceSessionId}. Use read_session if you need details not included here.`
+
+      // Format files as @file references — the chat.message hook will parse
+      // these and inject synthetic file parts when the user sends the message.
+      const uniqueFiles = [
+        ...new Set(
+          (args.files ?? [])
+            .map((f) => f.trim().replace(/^@/, ""))
+            .filter(Boolean),
+        ),
+      ]
+      const fileRefs = uniqueFiles.length
+        ? uniqueFiles.map((f) => `@${f}`).join(" ")
+        : ""
+
+      const fullPrompt = fileRefs
+        ? `${sessionReference}\n\n${fileRefs}\n\n${prompt}`
+        : `${sessionReference}\n\n${prompt}`
+
+      // Create a new session via TUI command — this also navigates to it
+      // automatically, so the user lands in the new session ready to review.
+      try {
+        await client.tui.executeCommand({
+          body: { command: "session_new" },
+        })
+        // session_new fires asynchronously. The TUI needs a moment to
+        // navigate and mount the new prompt input before we can append text.
+        await new Promise((r) => setTimeout(r, 200))
+        await client.tui.appendPrompt({ body: { text: fullPrompt } })
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err)
+        await client.app.log({
+          body: {
+            service: "handoff",
+            level: "error",
+            message: "Failed to create handoff draft",
+            extra: { error, sourceSessionId },
+          },
+        })
+        return JSON.stringify({ ok: false, error: `Failed to create handoff draft: ${error}` })
+      }
+
+      // Non-fatal toast notification
+      try {
+        await client.tui.showToast({
+          body: {
+            title: "Handoff Ready",
+            message: "Review the draft, edit if needed, then send",
+            variant: "success",
+            duration: 4000,
+          },
+        })
+      } catch {
+        // TUI toast may not be available in headless/test contexts
+      }
+
+      await client.app.log({
+        body: {
+          service: "handoff",
+          level: "info",
+          message: "Handoff draft created",
+          extra: { fileCount: uniqueFiles.length, sourceSessionId },
+        },
+      })
+
+      return JSON.stringify({
+        ok: true,
+        sourceSessionId,
+        files: uniqueFiles,
+        message:
+          "Handoff prompt created as editable draft in new session. " +
+          "File contents will be loaded automatically when the user sends.",
+      })
+    },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Transcript formatting
+// ---------------------------------------------------------------------------
+
+function formatTranscript(
+  messages: Array<{
+    info: Record<string, unknown>
+    parts: Array<Record<string, unknown>>
+  }>,
+  limit: number,
+): string {
+  const lines: string[] = []
+
+  for (const msg of messages) {
+    const role = msg.info.role as string
+
+    if (role === "user") {
+      lines.push("## User")
+      for (const part of msg.parts) {
+        if (part.type === "text" && !part.ignored) {
+          lines.push(part.text as string)
+        }
+        if (part.type === "file") {
+          lines.push(
+            `[Attached: ${(part.filename as string) || "file"}]`,
+          )
+        }
+      }
+      lines.push("")
+    }
+
+    if (role === "assistant") {
+      lines.push("## Assistant")
+      for (const part of msg.parts) {
+        if (part.type === "text") {
+          lines.push(part.text as string)
+        }
+        if (part.type === "tool") {
+          const state = part.state as Record<string, unknown> | undefined
+          if (state?.status === "completed") {
+            lines.push(
+              `[Tool: ${part.tool as string}] ${(state.title as string) ?? ""}`,
+            )
+          }
+        }
+      }
+      lines.push("")
+    }
+  }
+
+  const output = lines.join("\n").trim()
+  const suffix =
+    messages.length >= limit
+      ? `\n\n(Showing ${messages.length} most recent messages. Use a higher 'limit' to see more.)`
+      : `\n\n(End of session — ${messages.length} messages)`
+
+  return output + suffix
+}
+
+// ---------------------------------------------------------------------------
+// ReadSession
+// ---------------------------------------------------------------------------
+
+export const ReadSession = (client: OpencodeClient) => {
+  return tool({
+    description:
+      "Read conversation transcript from a previous session. " +
+      "Returns a formatted markdown transcript. " +
+      "Use when you need specific information not included in the handoff summary.",
+    args: {
+      sessionId: tool.schema
+        .string()
+        .describe("The full session ID (e.g., sess_01jxyz...)"),
+      limit: tool.schema
+        .number()
+        .optional()
+        .describe("Max messages to read (default 100, max 500)"),
+    },
+    async execute(args: { sessionId: string; limit?: number }) {
+      if (!args.sessionId?.trim()) {
+        return JSON.stringify({ ok: false, error: "sessionId must not be empty." })
+      }
+
+      const limit = Math.max(1, Math.min(args.limit ?? 100, 500))
+
+      try {
+        const response = (await client.session.messages({
+          path: { id: args.sessionId },
+          query: { limit },
+        })) as
+          | { data?: unknown[] }
+          | unknown[]
+
+        const messages = (
+          Array.isArray(response) ? response : (response.data ?? [])
+        ) as Array<{
+          info: Record<string, unknown>
+          parts: Array<Record<string, unknown>>
+        }>
+
+        if (messages.length === 0) {
+          return JSON.stringify({
+            ok: false,
+            error: "Session has no messages or does not exist.",
+          })
+        }
+
+        return JSON.stringify({
+          ok: true,
+          sessionId: args.sessionId,
+          count: messages.length,
+          transcript: formatTranscript(messages, limit),
+        })
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err)
+        return JSON.stringify({
+          ok: false,
+          error: `Failed to read session ${args.sessionId}: ${error}`,
+        })
+      }
+    },
+  })
+}