cursor-opencode-provider 0.7.0 → 0.7.1

package/README.md

@@ -48,7 +48,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **Model discovery** — fetches available models from Cursor's API and caches them locally
 - **Image input** — advertises vision only for supported models and forwards OpenCode image attachments to Cursor
 - **Streaming** — bidirectional Connect-RPC Runs with stale-session rotation, health checks, semantic/read-idle deadlines, bounded replay-safe recovery, and activity-aware held tool continuations
-- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts using only the advertised canonical catalog. Exact advertised subagent names win; standard Cursor roles select compatible OpenCode agents, and native Task maps to OpenCode 1.x `task` or OpenCode 2.0 `subagent`. OCP translates any alternate host vocabulary before it reaches this package. The bridge also covers Cursor's typed read/bash/edit/write/grep/find/ls request/result range, mirrors finalized display-only todo/plan state, and strips OpenCode's `read` XML envelope before returning content to Cursor.
+- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts using only the advertised canonical catalog. Exact advertised subagent names win; standard Cursor roles select compatible OpenCode agents, and native Task maps to OpenCode 1.x `task` or OpenCode 2.0 `subagent`. OCP translates any alternate host vocabulary before it reaches this package. The bridge also covers Cursor's typed read/bash/edit/write/grep/find/ls request/result range, mirrors finalized display-only todo/plan state, and strips OpenCode 1.x and OpenCode 2 read envelopes before returning content to Cursor.
 - **Thinking / reasoning** — surfaces extended-thinking deltas where the model supports it
 
 ## Requirements
@@ -379,7 +379,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **Conversation bindings survive provider restarts** — after each successful `TurnEnded`, the OpenCode-session binding, latest checkpoint, checkpoint-reachable KV blob graph, frozen request-context base, last real tool catalog, host agent, stable system-prompt hash, and pending post-compaction rebase marker are atomically replaced in that session's private `<host-cache>/cursor-conversations/*.pb.gz` snapshot. The protobuf stores checkpoints, blob ids/data, and request context as bytes without JSON/base64 expansion, then gzip compresses the complete record. A checkpoint alone is insufficient: Cursor requests its referenced hashes through `get_blob` when the next Run starts. Reachability follows Cursor CLI's export traversal (turns, messages, steps, images, summaries, todos, prompts, and nested subagents), pruning superseded blobs; decode failure or a missing referenced hash conservatively retains the complete blob set. The stable OpenCode session id selects the file; Cursor conversation ids may rotate during compaction, agent switches, or prompt changes and remain inside the snapshot. Independent files prevent concurrent OpenCode processes from losing unrelated sessions by replacing a shared aggregate cache. Startup restores records updated within 24 hours and safely flushes older ones without deleting a concurrently published fresh replacement. Experimental legacy JSON snapshots are discarded rather than migrated. Debug logs report hydration as `restored`, `missing`, `invalid`, or `expired`, plus the compressed and protobuf snapshot sizes. The restored catalog is a fallback only for lifecycle turns such as compaction; an ordinary restricted/no-tool turn never resurrects it. Process-global bindings and prompt/catalog state still use a 256-session LRU bound; memory eviction drops the live checkpoint, blobs, and frozen context, which can be rehydrated from the restart cache on later use.
 - **Oversized checkpoint graphs rebase instead of flooding the Run stream** — before reusing a checkpoint, the provider measures its reachable KV graph. State above 100 MiB, or an incomplete graph with a missing/undecodable reference, rotates to a fresh Cursor conversation seeded from OpenCode's authoritative history. KV, request-context, MCP-state, interaction, and heartbeat writes are ordered per Run and await HTTP/2 drain, so a large blob reply cannot create an unbounded queue later misreported as heartbeat backpressure. Debug logs distinguish checkpoint-envelope bytes, reachable blob bytes, seed size, and encoded Run-request estimate; raw blob bytes are never presented as tokens.
 - **Interrupted Runs resume from checkpoints** — a remote EOF, Connect end-stream, or trailer error is never emitted as a successful `stop`. When the failed Run produced an eligible checkpoint, the provider opens a new RPC for the same conversation and sends that state with `ResumeAction`, so completed text and tool work are not replayed. Before any stateful output, an interruption without a checkpoint can still rebase from OpenCode history. Stateful interruptions without a checkpoint are surfaced because replay would be ambiguous; retry exhaustion remains explicit. A transport closure after `turn_ended` is treated as successful completion.
-- **Large reads are capped at 50 KB by OpenCode, and the cap is reported** — OpenCode's `read` tool stops at `MAX_BYTES = 50 * 1024`, cutting on a whole-line boundary, and appends `(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)`. The provider strips that envelope before returning content to Cursor so the model cannot echo wrappers into a later write, but it re-states the cap: a capped native read appends a `[Partial read: …]` marker after the content, a capped MCP read gets a separate notice content item, and a Pi read carries structured `PiReadExecSuccess.truncation`. The structured `truncated` flag alone is not enough — verified against live `gpt-5.4-mini` and `grok-4.5` sessions, both of which asserted "highly confident" that partial content was the whole file until the textual marker was added. Deliberately paged reads (explicit `offset`/`limit`) are not marked. Whole-file writes and overwriting `Add File` patches that echo the marker are rejected before OpenCode executes them; targeted edits remain possible, including edits to source that quotes the warning text. Cursor's private legacy-edit read is handled separately as described above, so an edit can operate on a workspace file larger than 50 KB without turning the capped preview into a replacement. The cap is hardcoded in OpenCode's read tool — it is not the configurable `tool_output.max_bytes`, which governs `Truncate.Service` and not read's line accumulation — so ordinary model reads still require paging with `offset`.
+- **Large reads are capped by OpenCode, and the cap is reported** — OpenCode 1.x `read` stops at `MAX_BYTES = 50 * 1024` and appends `(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)`. OpenCode 2 prints `Read file <path>, lines <start>-<end>` with `N: ` prefixes and, when the page ends before EOF, `[Output truncated. Continue reading with offset: N]` (50 KB or 2,000 lines); it also shortens each individual line after 2,000 characters. The provider strips either envelope before returning content to Cursor so the model cannot echo wrappers into a later write, but it re-states every partial result: a native read appends a `[Partial read: …]` marker after the content, an MCP read gets a separate notice content item, and a Pi read carries structured `PiReadExecSuccess.truncation`. Relative grep, glob, and directory entries are resolved against the workspace root. Shell stdout absolutizes only relative path tokens, not prose. Checkpointed turns, which do not resend the system prompt, get that same root on the user message. The structured `truncated` flag alone is not enough — verified against live `gpt-5.4-mini` and `grok-4.5` sessions, both of which asserted "highly confident" that partial content was the whole file until the textual marker was added. Deliberately paged reads (explicit `offset`/`limit`) are not marked unless the host also hits the byte cap or character-truncates a line. Whole-file writes and overwriting `Add File` patches that echo the marker are rejected before OpenCode executes them; targeted edits remain possible, including edits to source that quotes the warning text. Cursor's private legacy-edit read is handled separately as described above, so an edit can operate on a workspace file larger than 50 KB without turning the capped preview into a replacement. The cap is hardcoded in OpenCode's read tool — it is not the configurable `tool_output.max_bytes`, which governs `Truncate.Service` and not read's line accumulation — so ordinary model reads still require paging with `offset`.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License

package/dist/language-model.d.ts

@@ -87,6 +87,15 @@ type ExtractedToolResult = {
  * are ignored — they are conversation history, not replies for a held-open Run.
  */
 export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOptions["prompt"]): ExtractedToolResult[];
+/**
+ * Checkpointed Runs do not resend the system prompt. Keep the workspace root
+ * on the live user message, and require absolute `path` arguments when that is
+ * the host's file-tool dialect.
+ */
+export declare function groundCheckpointTurnText(userText: string, checkpoint: boolean, workspaceRoot: string, tools: readonly {
+    name?: string;
+    inputSchema?: unknown;
+}[]): string;
 /**
  * Cursor's native UI interactions cannot be surfaced through the AI SDK.
  * Redirect only to OpenCode tools that are genuinely advertised this turn;

package/dist/language-model.js

@@ -9,7 +9,7 @@ import { debugWalkTurnEnded, decodeMessage, encodeMessage } from "./protocol/mes
 import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, buildUnsupportedExecDeny, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, preferCorrelatedTaskDescription, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, buildCompleteEditReadMessages, rejectPartialReadMutation, binaryWritePayload, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, hostToolDialectFromTools, opencodePathArg, } from "./protocol/tools.js";
 import { buildGitDiffExecMessages } from "./protocol/git-diff.js";
 import { cursorExecVariantByRequestField, describeCursorExecVariant } from "./protocol/exec-variants.js";
-import { appendWorkspaceRootGrounding } from "./protocol/workspace-grounding.js";
+import { appendCheckpointUserGrounding, appendWorkspaceRootGrounding } from "./protocol/workspace-grounding.js";
 import { progressOnlyContinuationPrompt, shouldContinueProgressOnlyTurn, } from "./protocol/progress-continuation.js";
 import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, snapshotMirroredTodos, snapshotMirroredTodosFromReadOutput, } from "./protocol/tool-call-bridge.js";
 import { handleKvServerMessage } from "./protocol/kv.js";
@@ -844,12 +844,15 @@ async function startSession(modelId, token, callOptions, options, startOptions)
             `previousId=${bound.previousId ?? "-"} → conversationId=${conversationId}`);
     }
     const lastUser = [...prompt].reverse().find((message) => message.role === "user");
-    const userText = recovery?.kind === "rebase"
+    let userText = recovery?.kind === "rebase"
         ? "Continue the interrupted turn from the conversation history above. Do not repeat completed work."
         : (extractUserText(lastUser) || ".");
     // After an approved SwitchMode, inject the Cursor CLI-shaped mode reminder
     // (same <system_reminder> contract the CLI uses after flipping unifiedMode).
     const startedWithCheckpoint = !!conversationState;
+    if (startedWithCheckpoint) {
+        userText = groundCheckpointTurnText(userText, true, workspaceRoot, cursorTools);
+    }
     const activeMode = getActiveCursorMode(sessionKey);
     const nativePlanPromptOwnsMode = hostAgent === "plan"
         && (activeMode === "plan" || activeMode === "spec");
@@ -2934,6 +2937,18 @@ function extractSystemPrompt(prompt) {
     }
     return parts.length > 0 ? parts.join("\n\n") : undefined;
 }
+/**
+ * Checkpointed Runs do not resend the system prompt. Keep the workspace root
+ * on the live user message, and require absolute `path` arguments when that is
+ * the host's file-tool dialect.
+ */
+export function groundCheckpointTurnText(userText, checkpoint, workspaceRoot, tools) {
+    if (!checkpoint)
+        return userText;
+    return appendCheckpointUserGrounding(userText, workspaceRoot, {
+        requireAbsolutePathArg: hostToolDialectFromTools(tools).filePathKey === "path",
+    });
+}
 /**
  * Cursor's native UI interactions cannot be surfaced through the AI SDK.
  * Redirect only to OpenCode tools that are genuinely advertised this turn;
@@ -3015,6 +3030,9 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
         // leaving the turn with no file-editing guidance at all.
         instructions.push("- Use OpenCode `apply_patch` for file-content changes; do not use shell, Python, or heredocs to change file content while it is available. Cursor-native write and edit requests are accepted and converted to `apply_patch` automatically.");
     }
+    if (hostToolDialectFromTools(tools).filePathKey === "path") {
+        instructions.push("- OpenCode file tools take `path` as an absolute path under the workspace root above. Do not pass a project-relative path, and do not invent a different absolute prefix.");
+    }
     if (names.has("edit") || names.has("write") || names.has("apply_patch")) {
         instructions.push("- Never use a read result as complete file content when it says the output is capped, partial, or requires another offset. Read the remaining ranges first, or make a targeted edit/patch from complete context; do not pass a partial read back as a whole-file replacement.");
     }

package/dist/protocol/tools.d.ts

@@ -290,14 +290,13 @@ export declare function buildUnsupportedExecDeny(input: {
 /**
  * Strip opencode's `read` envelope, leaving raw file content.
  *
- * opencode's read tool (opencode `tool/read.ts`) wraps content in an XML-ish
- * envelope its own models are trained on, but Cursor's are not:
+ * OpenCode 1.x (`tool/read.ts`) wraps content in an XML-ish envelope its own
+ * models are trained on, but Cursor's are not:
  *   <path>{abs}</path>\n<type>file</type>\n<content>\n{N}: {line}\n…\n\n{footer}\n</content>
- * Forwarding that envelope verbatim made Cursor's model treat the wrapper as
- * literal file content and write `<path>`/`<content>` tags + `N:` line prefixes
- * back into files (silent corruption — the write still reports success; seen
- * across 8+ sessions, e.g. language-model.ts rewritten starting with
- * `<path>…</path>\n<type>file</type>\n<content>\n1: import fs…`).
+ * OpenCode 2 replaced that with `Read file <path>, lines <start>-<end>` plus
+ * the same `N: ` prefixes and `[Output truncated. Continue reading with offset: N]`.
+ * Forwarding either envelope verbatim made Cursor's model treat the wrapper as
+ * literal file content and write tags or line prefixes back into files.
  *
  * Returns the raw file body (line numbers + footer + `<system-reminder>` dropped).
  *

package/dist/protocol/tools.js

@@ -860,6 +860,18 @@ export function remapEditToolsForCatalog(parsed, advertisedToolNames, workspaceR
     // the requested path for the typed Cursor result.
     parsed.resultMetadata = { ...parsed.resultMetadata, path: filePath };
 }
+function readRequestResultMetadata(raw, mappedArgs) {
+    const requestedPath = str(raw.path)
+        ?? str(raw.filePath)
+        ?? str(raw.file_path)
+        ?? opencodePathArg(mappedArgs)
+        ?? "";
+    return {
+        path: requestedPath,
+        ...(typeof mappedArgs.offset === "number" ? { offset: mappedArgs.offset } : {}),
+        ...(typeof mappedArgs.limit === "number" ? { limit: mappedArgs.limit } : {}),
+    };
+}
 /**
  * A partial-read notice is for Cursor's model, never for a file. Refuse only
  * whole-file mutation forms that echo it. A targeted edit or Update File patch
@@ -888,12 +900,15 @@ export function rejectPartialReadMutation(parsed) {
         return;
     const filePath = opencodePathArg(parsed.args) ?? "the target file";
     const nextOffset = /Continue with offset=(\d+)/.exec(content)?.[1];
+    const longLine = content.includes("Use a byte-preserving read method");
     parsed.localError =
         `NO FILE CHANGE WAS MADE. Refusing a whole-file mutation of ${JSON.stringify(filePath)} ` +
             "because it contains the provider's partial-read notice. Do not retry the same mutation. " +
             (nextOffset
                 ? `Read the file from offset=${nextOffset}, then use a targeted edit or Update File patch.`
-                : "Read the remaining file ranges, then use a targeted edit or Update File patch.");
+                : longLine
+                    ? "Inspect the full line with a byte-preserving read method, then use a targeted edit or Update File patch."
+                    : "Read the remaining file ranges, then use a targeted edit or Update File patch.");
 }
 export function parseExecServerMessage(msg, dialect = OPENCODE_1_TOOL_DIALECT) {
     const id = msg.id;
@@ -986,13 +1001,17 @@ export function parseExecServerMessage(msg, dialect = OPENCODE_1_TOOL_DIALECT) {
         // tool name (Cursor's model may have shortened "opencode-read" → "read") and
         // decode the argument map back into JSON for opencode to execute.
         const m = msg.mcp_args ?? {};
-        const mapped = mapCursorArgsToOpencode(mcpRealToolName(m), decodeMcpArgs(m.args), "mcp_args", dialect);
+        const rawArgs = decodeMcpArgs(m.args);
+        const mapped = mapCursorArgsToOpencode(mcpRealToolName(m), rawArgs, "mcp_args", dialect);
         return {
             id,
             execId,
             toolName: mapped.toolName,
             args: mapped.args,
             resultField,
+            ...(mapped.toolName === "read"
+                ? { resultMetadata: readRequestResultMetadata(rawArgs, mapped.args) }
+                : {}),
         };
     }
     if (execVariant === "pi_edit_args") {
@@ -1028,12 +1047,8 @@ export function parseExecServerMessage(msg, dialect = OPENCODE_1_TOOL_DIALECT) {
     const rawArgs = msg[execVariant] ?? {};
     const resultMetadata = execVariant === "shell_stream_args" || execVariant === "shell_args"
         ? shellStreamResultMetadata(rawArgs)
-        : execVariant === "read_args"
-            ? {
-                path: str(rawArgs.path) ?? str(rawArgs.file_path) ?? "",
-                ...(typeof mapped.args.offset === "number" ? { offset: mapped.args.offset } : {}),
-                ...(typeof mapped.args.limit === "number" ? { limit: mapped.args.limit } : {}),
-            }
+        : execVariant === "read_args" || execVariant === "pi_read_args"
+            ? readRequestResultMetadata(rawArgs, mapped.args)
             : undefined;
     if (resultMetadata
         && resultMetadata.timeout_behavior !== 2
@@ -1415,9 +1430,11 @@ export function isUriReadTarget(requested) {
  */
 export function resolveReadTargetPath(requested, workspaceRoot) {
     const expanded = untildify(requested);
-    if (workspaceRoot && !path.isAbsolute(expanded)) {
-        return path.resolve(workspaceRoot, expanded);
+    if (isAbsoluteToolPath(expanded)) {
+        return isForeignAbsoluteToolPath(expanded) ? expanded : path.resolve(expanded);
     }
+    if (workspaceRoot)
+        return joinToolPath(workspaceRoot, expanded);
     return path.resolve(expanded);
 }
 /**
@@ -1482,6 +1499,7 @@ export function buildExecClientMessages(input) {
     const resultField = input.resultField || "mcp_result";
     const frames = [];
     if (resultField === "shell_stream") {
+        const stdout = groundShellPathText(input.output, shellPathRoot(input.resultMetadata, input.workspaceRoot));
         // Real clients always emit Start → Stdout/Stderr* → Exit (capture/tests).
         frames.push(encodeShellStream(input.execId, undefined, { start: {} }));
         if (input.error) {
@@ -1489,8 +1507,8 @@ export function buildExecClientMessages(input) {
             frames.push(encodeShellStream(input.execId, input.executionTimeMs, { exit: { code: 1, aborted: false } }));
         }
         else {
-            if (input.output) {
-                frames.push(encodeShellStream(input.execId, undefined, { stdout: { data: input.output } }));
+            if (stdout) {
+                frames.push(encodeShellStream(input.execId, undefined, { stdout: { data: stdout } }));
             }
             if (input.shellOutcome?.kind === "backgrounded") {
                 frames.push(encodeShellStream(input.execId, input.executionTimeMs, {
@@ -1700,17 +1718,396 @@ export function buildUnsupportedExecDeny(input) {
     frames.push(buildExecStreamClose(execId));
     return frames;
 }
+/** OpenCode 2 `read` prints this when a text page does not reach EOF. */
+const OPENCODE2_READ_TRUNCATION = /^\[Output truncated\. Continue reading with offset:\s*(\d+)\]\s*$/;
+/** OpenCode 2 stops a read at 2,000 lines as well as 50 KB. */
+const OPENCODE2_READ_MAX_LINES = 2_000;
+const OPENCODE2_READ_MAX_LINE_CHARS = 2_000;
+const OPENCODE2_READ_LINE_TRUNCATION = `... (line truncated to ${OPENCODE2_READ_MAX_LINE_CHARS} chars)`;
+/**
+ * `read-filesystem.ts` shortens each selected line to 2,000 UTF-16 code units.
+ * One code unit encodes to at most three UTF-8 bytes. Add the 34-byte
+ * `... (line truncated to 2000 chars)` suffix and one line separator when
+ * proving a page was close enough for the next line not to fit.
+ */
+const OPENCODE2_MAX_RENDERED_LINE_BYTES = (OPENCODE2_READ_MAX_LINE_CHARS * 3) + Buffer.byteLength(OPENCODE2_READ_LINE_TRUNCATION, "utf8") + 1;
+function normalizeToolText(output) {
+    return output.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/**
+ * OpenCode 2 `ReadTool.toModelContent` for a file. The whole string must match;
+ * a file that merely quotes the header stays a numbered body line.
+ *
+ *   Read file <path>, lines <start>-<end>
+ *   <n>: <line>
+ *   [Output truncated. Continue reading with offset: <next>]
+ */
+function parseOpenCode2FileRead(output, resultMetadata) {
+    const normalized = normalizeToolText(output).replace(/\n+$/, "");
+    if (!normalized.startsWith("Read file "))
+        return undefined;
+    const lines = normalized.split("\n");
+    const headerLine = (lines[0] ?? "").trim();
+    const empty = /^Read file (.*), 0 lines$/.exec(headerLine);
+    if (empty) {
+        if (lines.length !== 1)
+            return undefined;
+        return {
+            path: empty[1] ?? "",
+            content: "",
+            totalLines: 0,
+            hostTruncated: false,
+            outputCapped: false,
+            truncatedLines: [],
+        };
+    }
+    const header = /^Read file (.*), lines (\d+)-(\d+)$/.exec(headerLine);
+    if (!header)
+        return undefined;
+    const start = Number(header[2]);
+    const end = Number(header[3]);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start) {
+        return undefined;
+    }
+    let bodyEnd = lines.length;
+    let nextOffset;
+    const banner = OPENCODE2_READ_TRUNCATION.exec(lines[lines.length - 1] ?? "");
+    if (banner) {
+        nextOffset = Number(banner[1]);
+        if (!Number.isSafeInteger(nextOffset) || nextOffset < 1)
+            return undefined;
+        bodyEnd -= 1;
+    }
+    const expected = end - start + 1;
+    if (bodyEnd - 1 !== expected)
+        return undefined;
+    const raw = [];
+    const truncatedLines = [];
+    for (let index = 0; index < expected; index++) {
+        const match = /^(\d+):[ \t](.*)$/.exec(lines[index + 1] ?? "");
+        if (!match || Number(match[1]) !== start + index)
+            return undefined;
+        const value = match[2] ?? "";
+        if (value.length === OPENCODE2_READ_MAX_LINE_CHARS + OPENCODE2_READ_LINE_TRUNCATION.length
+            && value.endsWith(OPENCODE2_READ_LINE_TRUNCATION)) {
+            truncatedLines.push(start + index);
+        }
+        raw.push(value);
+    }
+    const content = raw.join("\n");
+    const hostTruncated = nextOffset !== undefined;
+    const requestedLimit = num(resultMetadata?.limit);
+    const effectiveLineLimit = requestedLimit !== undefined && requestedLimit > 0
+        ? Math.min(requestedLimit, OPENCODE2_READ_MAX_LINES)
+        : OPENCODE2_READ_MAX_LINES;
+    // OpenCode 2 ends a text page only for the requested/default line limit or
+    // the 50 KiB byte limit. Fewer lines than the effective line limit, together
+    // with a page close enough that one maximum-size rendered line may not fit,
+    // identifies the byte cap without the old ASCII-only 4 KiB guess.
+    const outputCapped = hostTruncated
+        && expected < effectiveLineLimit
+        && Buffer.byteLength(content, "utf8") > OPENCODE_READ_MAX_BYTES - OPENCODE2_MAX_RENDERED_LINE_BYTES;
+    if (hostTruncated) {
+        return {
+            path: header[1] ?? "",
+            content,
+            startLine: start,
+            endLine: end,
+            nextOffset,
+            hostTruncated: true,
+            outputCapped,
+            truncatedLines,
+        };
+    }
+    // A page that reached EOF is complete. Record the span so a non-1 offset is
+    // not later mistaken for a silent cap, without flagging it truncated.
+    return {
+        path: header[1] ?? "",
+        content,
+        ...(start === 1
+            ? { totalLines: end }
+            : { startLine: start, endLine: end, totalLines: end }),
+        hostTruncated: false,
+        outputCapped: false,
+        truncatedLines,
+    };
+}
+/**
+ * OpenCode 2 directory reads list bare entry names. Join them onto the
+ * directory, then onto the workspace root, so the model can copy a real path
+ * instead of inventing an absolute prefix.
+ */
+function parseOpenCode2DirectoryListing(output, workspaceRoot) {
+    const normalized = normalizeToolText(output).replace(/\n+$/, "");
+    if (!normalized.startsWith("Read directory "))
+        return undefined;
+    const lines = normalized.split("\n");
+    const header = /^Read directory (.*), (?:0 entries|entries (\d+)-(\d+))$/.exec((lines[0] ?? "").trim());
+    if (!header) {
+        trace("parseOpenCode2DirectoryListing: OpenCode 2 directory header did not match — leaving output unchanged");
+        return undefined;
+    }
+    const requested = header[1] ?? "";
+    if (!isAbsoluteToolPath(requested) && !workspaceRoot)
+        return undefined;
+    let bodyEnd = lines.length;
+    let banner;
+    if (bodyEnd > 1 && OPENCODE2_READ_TRUNCATION.test(lines[bodyEnd - 1] ?? "")) {
+        banner = lines[bodyEnd - 1];
+        bodyEnd -= 1;
+    }
+    const rawEntries = lines.slice(1, bodyEnd);
+    if (header[2] === undefined) {
+        if (rawEntries.length !== 0)
+            return undefined;
+    }
+    else {
+        const start = Number(header[2]);
+        const end = Number(header[3]);
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || end - start + 1 !== rawEntries.length) {
+            return undefined;
+        }
+    }
+    const directory = resolveToolPath(requested, workspaceRoot);
+    const directories = [];
+    const files = [];
+    const entries = rawEntries.map((entry) => {
+        const resolved = resolveListedEntry(directory, entry);
+        if (entry.endsWith("/") || entry.endsWith("\\"))
+            directories.push(resolved);
+        else
+            files.push(resolved);
+        return resolved;
+    });
+    const headerLine = header[2] === undefined
+        ? `Read directory ${directory}, 0 entries`
+        : `Read directory ${directory}, entries ${header[2]}-${header[3]}`;
+    return {
+        directory,
+        entries,
+        directories,
+        files,
+        text: [headerLine, ...entries, ...(banner ? [banner] : [])].join("\n"),
+    };
+}
+/**
+ * Absolute on this host, plus Windows drive and UNC paths. A posix agent must
+ * not prefix `C:/…` or `\\server\…` just because `path.isAbsolute` rejects them.
+ */
+function isAbsoluteToolPath(filePath) {
+    return path.isAbsolute(filePath)
+        || /^[A-Za-z]:[\\/]/.test(filePath)
+        || filePath.startsWith("\\\\");
+}
+/** Windows drive or UNC path that `path.isAbsolute` rejects on this host. */
+function isForeignAbsoluteToolPath(filePath) {
+    return isAbsoluteToolPath(filePath) && !path.isAbsolute(filePath);
+}
+/** Separator already used by a drive or UNC path. Host paths keep `path.sep`. */
+function toolPathSeparator(filePath) {
+    if (path.isAbsolute(filePath))
+        return path.sep;
+    if (filePath.startsWith("\\\\") || (filePath.includes("\\") && !filePath.includes("/")))
+        return "\\";
+    return "/";
+}
+/**
+ * Join `relative` onto `root`. Node's `path.resolve` treats `C:/…` and
+ * `\\server\…` as relative on posix and prefixes the process cwd. Keep those
+ * roots intact, including `..`, and still use `path.resolve` for host paths.
+ */
+function joinToolPath(root, relative) {
+    if (!isForeignAbsoluteToolPath(root))
+        return path.resolve(root, relative);
+    const sep = toolPathSeparator(root);
+    const base = splitForeignAbsolute(root, sep);
+    const parts = [...base.segments];
+    for (const part of relative.split(/[\\/]+/)) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..") {
+            if (parts.length > base.frozen)
+                parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    return parts.length === 0 ? base.prefix : `${base.prefix}${parts.join(sep)}`;
+}
+function splitForeignAbsolute(filePath, sep) {
+    if (filePath.startsWith("\\\\")) {
+        const segments = filePath.slice(2).split(/[\\/]+/).filter(Boolean);
+        return { prefix: "\\\\", segments, frozen: Math.min(2, segments.length) };
+    }
+    const rest = filePath.slice(2).replace(/^[\\/]+/, "");
+    return {
+        prefix: `${filePath.slice(0, 2)}${sep}`,
+        segments: rest ? rest.split(/[\\/]+/).filter(Boolean) : [],
+        frozen: 0,
+    };
+}
+function isRelativePathToken(token) {
+    if (!token || isAbsoluteToolPath(token))
+        return false;
+    // A slash alone does not make arbitrary shell output a path. In particular,
+    // compact JSON, quoted strings, package ids, and shell syntax must remain
+    // byte-for-byte model-visible rather than being prefixed with the workspace.
+    if (/[\0"'`{}\[\]<>|;]/.test(token) || token.startsWith("@"))
+        return false;
+    if (token.startsWith("./")
+        || token.startsWith("../")
+        || token.startsWith(".\\")
+        || token.startsWith("..\\"))
+        return true;
+    return token.includes("/") || (path.sep === "\\" && token.includes("\\"));
+}
+function resolveListedEntry(directory, entry) {
+    if (!entry || isAbsoluteToolPath(entry))
+        return entry;
+    if (entry === "~" || entry.startsWith("~/") || entry.startsWith("~\\"))
+        return entry;
+    const directoryEntry = entry.endsWith("/") || entry.endsWith("\\");
+    const resolved = joinToolPath(directory, entry);
+    if (!directoryEntry || resolved.endsWith("/") || resolved.endsWith("\\"))
+        return resolved;
+    return `${resolved}${toolPathSeparator(resolved)}`;
+}
+function resolveToolPath(filePath, workspaceRoot) {
+    if (!filePath || isAbsoluteToolPath(filePath))
+        return filePath;
+    if (filePath === "~" || filePath.startsWith("~/") || filePath.startsWith("~\\"))
+        return filePath;
+    if (!workspaceRoot)
+        return filePath;
+    return joinToolPath(workspaceRoot, filePath);
+}
+/**
+ * Rewrite OpenCode 2 grep/glob lines that are still project-relative. Absolute
+ * paths, indented match previews, and prose stay untouched. Grep file headers
+ * drop the trailing colon only in the structured file list, not in this text.
+ */
+function groundSearchOutput(output, workspaceRoot) {
+    if (!workspaceRoot)
+        return output;
+    const normalized = normalizeToolText(output);
+    const first = normalized.split("\n", 1)[0] ?? "";
+    const searchShaped = /^Found \d+ matches/.test(first)
+        || first === "No matches found"
+        || first === "No files found";
+    if (!searchShaped && !isBarePathList(normalized))
+        return output;
+    return normalized.split("\n").map((line) => rewriteSearchPathLine(line, workspaceRoot)).join("\n");
+}
+function isBarePathList(output) {
+    const lines = output.split("\n").map((line) => line.trim()).filter(Boolean);
+    if (lines.length === 0 || lines.length > 2000)
+        return false;
+    return lines.every((line) => {
+        if (line.startsWith("("))
+            return true;
+        if (/\s/.test(line) || line.includes("://"))
+            return false;
+        return true;
+    });
+}
+function rewriteSearchPathLine(line, workspaceRoot) {
+    if (!line || line.startsWith(" ") || line.startsWith("\t") || line.startsWith("("))
+        return line;
+    if (line.startsWith("Found ") || line === "No matches found" || line === "No files found")
+        return line;
+    const header = /^(.*):$/.exec(line);
+    if (header && !header[1]?.includes("://")) {
+        return `${resolveToolPath(header[1] ?? "", workspaceRoot)}:`;
+    }
+    if (line.includes("://"))
+        return line;
+    return resolveToolPath(line, workspaceRoot);
+}
+/**
+ * Shell stdout is mixed prose. Rewrite only tokens that are clearly relative
+ * paths, including `file:line` and `file:line:col`. Leave sentences, URLs, and
+ * status words alone.
+ */
+function groundShellPathText(output, root) {
+    if (!root || !output)
+        return output;
+    return normalizeToolText(output).split("\n").map((line) => rewriteShellPathLine(line, root)).join("\n");
+}
+function shellPathRoot(resultMetadata, workspaceRoot) {
+    const workingDirectory = str(resultMetadata?.working_directory)?.trim();
+    if (!workingDirectory)
+        return workspaceRoot;
+    if (isAbsoluteToolPath(workingDirectory))
+        return workingDirectory;
+    return workspaceRoot ? joinToolPath(workspaceRoot, workingDirectory) : undefined;
+}
+function rewriteShellPathLine(line, root) {
+    if (!line || line.startsWith(" ") || line.startsWith("\t"))
+        return line;
+    const trimmed = line.trimEnd();
+    if (trimmed.includes("://") || trimmed === "~" || trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+        return line;
+    }
+    const located = /^(.+?):(\d+)(?::(\d+))?$/.exec(trimmed);
+    if (located && located[1] && isRelativePathToken(located[1])) {
+        const suffix = located[3] !== undefined ? `:${located[2]}:${located[3]}` : `:${located[2]}`;
+        return `${resolveToolPath(located[1], root)}${suffix}`;
+    }
+    if (/\s/.test(trimmed))
+        return line;
+    const header = /^(.*):$/.exec(trimmed);
+    if (header && header[1] && isRelativePathToken(header[1])) {
+        return `${resolveToolPath(header[1], root)}:`;
+    }
+    if (isRelativePathToken(trimmed))
+        return resolveToolPath(trimmed, root);
+    return line;
+}
+function extractGroundedPaths(output, workspaceRoot) {
+    const normalized = normalizeToolText(output);
+    const directory = parseOpenCode2DirectoryListing(normalized, workspaceRoot);
+    if (directory)
+        return directory.entries.slice(0, 2000);
+    const first = normalized.split("\n", 1)[0]?.trim() ?? "";
+    if (/^Found \d+ matches/.test(first) || first === "No matches found" || first === "No files found") {
+        const paths = [];
+        for (const raw of normalized.split("\n").slice(1)) {
+            const line = raw.trim();
+            if (!line || line.startsWith("(") || line.startsWith("Line ") || raw.startsWith(" ") || raw.startsWith("\t")) {
+                continue;
+            }
+            const header = /^(.*):$/.exec(line);
+            const candidate = header && !header[1]?.includes("://") ? (header[1] ?? "") : line;
+            if (!candidate || candidate.includes("://"))
+                continue;
+            paths.push(resolveToolPath(candidate, workspaceRoot));
+        }
+        return paths.slice(0, 2000);
+    }
+    if (isBarePathList(output)) {
+        return output
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith("("))
+            .map((line) => resolveToolPath(line.endsWith(":") && !line.includes("://") ? line.slice(0, -1) : line, workspaceRoot))
+            .slice(0, 2000);
+    }
+    return extractPathLines(output).map((line) => {
+        const trimmed = line.trim();
+        const candidate = trimmed.endsWith(":") && !trimmed.includes("://") ? trimmed.slice(0, -1) : trimmed;
+        return resolveToolPath(candidate, workspaceRoot);
+    });
+}
 /**
  * Strip opencode's `read` envelope, leaving raw file content.
  *
- * opencode's read tool (opencode `tool/read.ts`) wraps content in an XML-ish
- * envelope its own models are trained on, but Cursor's are not:
+ * OpenCode 1.x (`tool/read.ts`) wraps content in an XML-ish envelope its own
+ * models are trained on, but Cursor's are not:
  *   <path>{abs}</path>\n<type>file</type>\n<content>\n{N}: {line}\n…\n\n{footer}\n</content>
- * Forwarding that envelope verbatim made Cursor's model treat the wrapper as
- * literal file content and write `<path>`/`<content>` tags + `N:` line prefixes
- * back into files (silent corruption — the write still reports success; seen
- * across 8+ sessions, e.g. language-model.ts rewritten starting with
- * `<path>…</path>\n<type>file</type>\n<content>\n1: import fs…`).
+ * OpenCode 2 replaced that with `Read file <path>, lines <start>-<end>` plus
+ * the same `N: ` prefixes and `[Output truncated. Continue reading with offset: N]`.
+ * Forwarding either envelope verbatim made Cursor's model treat the wrapper as
+ * literal file content and write tags or line prefixes back into files.
  *
  * Returns the raw file body (line numbers + footer + `<system-reminder>` dropped).
  *
@@ -1723,6 +2120,12 @@ export function buildUnsupportedExecDeny(input) {
 export function unwrapReadOutput(output) {
     if (typeof output !== "string" || output.length === 0)
         return output;
+    const opencode2 = parseOpenCode2FileRead(output);
+    if (opencode2)
+        return opencode2.content;
+    if (normalizeToolText(output).startsWith("Read file ")) {
+        trace("unwrapReadOutput: OpenCode 2 read header did not match the page parser — leaving output unchanged");
+    }
     // Require the full opencode read-envelope skeleton *before* `<content>`
     // (read.ts opens with <path>…</path>, <type>file</type>, <content>) so a
     // stray "<content>" later in tool chatter can't trigger unwrapping just
@@ -1773,34 +2176,53 @@ export function unwrapReadOutput(output) {
 export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata, shellOutcome, workspaceRoot) {
     // Prefer the session workspace; never advertise the host process cwd (daemon
     // often starts in $HOME) as the path Cursor shows the model for glob/ls.
-    const resultRoot = typeof workspaceRoot === "string" && workspaceRoot.trim()
-        ? path.resolve(workspaceRoot)
+    const trimmedRoot = typeof workspaceRoot === "string" ? workspaceRoot.trim() : "";
+    // A posix process must not turn `C:/…` or `\\server\…` into `<cwd>/C:/…`.
+    const resultRoot = trimmedRoot
+        ? (isForeignAbsoluteToolPath(trimmedRoot) ? trimmedRoot : path.resolve(trimmedRoot))
         : undefined;
     switch (resultField) {
         case "read_result": {
-            const readPath = str(resultMetadata?.path) ?? extractPathTag(output) ?? "";
+            const parsedFile = parseOpenCode2FileRead(output, resultMetadata);
+            const listing = error ? undefined : parseOpenCode2DirectoryListing(output, resultRoot);
+            const rawPath = str(resultMetadata?.path)
+                ?? parsedFile?.path
+                ?? listing?.directory
+                ?? extractPathTag(output)
+                ?? "";
+            const readPath = resolveToolPath(rawPath, resultRoot);
             if (error)
                 return { error: { path: readPath, error } };
-            // Strip opencode's <path>/<content> envelope so Cursor's model receives
-            // raw file content and can't echo the wrapper into subsequent writes.
+            // The host may have resolved an alternate spelling after the request
+            // (for example a Unicode-space filename). Use the result's own path for
+            // local stat/newline recovery while preserving the requested path in the
+            // Cursor result, matching the existing OpenCode 1 behavior.
+            const outputPath = parsedFile?.path ?? extractPathTag(output);
+            const statPath = resolveToolPath(outputPath ?? readPath, resultRoot);
+            // Strip OpenCode's read envelope so Cursor's model receives raw file
+            // content and can't echo the wrapper into subsequent writes.
             // Cursor's native read_args lands here; `mcp_args` reads land in
             // mcp_result. Live captures show gpt-5.4-mini and grok-4.5 both use the
             // native channel, so this is the path that matters in practice.
-            const statPath = extractPathTag(output) ?? readPath;
-            const outputMetadata = parseOpenCodeReadMetadata(output);
-            const content = restoreCompleteReadTerminator(unwrapReadOutput(output), statPath, outputMetadata, resultMetadata, resultRoot);
+            const outputMetadata = parseOpenCodeReadMetadata(output, resultMetadata);
+            const content = listing
+                ? listing.text
+                : restoreCompleteReadTerminator(unwrapReadOutput(output), statPath, outputMetadata, resultMetadata, resultRoot);
             const totalLines = outputMetadata.totalLines ?? readFileLineCount(statPath) ?? countLines(content);
             const rangeApplied = readRangeApplied(resultMetadata, totalLines);
             // `truncated` alone is not enough: it is set here, and models still assert
             // the partial content is the whole file. Cursor's own executor puts the
             // limit marker in the output text for the same reason, so append one.
-            const notice = readTruncationNotice(output, resultMetadata);
+            const notices = [
+                readTruncationNotice(output, resultMetadata),
+                readLongLineTruncationNotice(output),
+            ].filter((notice) => !!notice);
             return {
                 success: {
-                    path: readPath,
-                    content: notice ? `${content}\n\n${notice}` : content,
+                    path: listing?.directory || readPath,
+                    content: notices.length > 0 ? `${content}\n\n${notices.join("\n\n")}` : content,
                     total_lines: totalLines,
-                    file_size: readFileSize(statPath),
+                    file_size: listing ? 0 : readFileSize(statPath),
                     truncated: readOutputTruncated(resultMetadata, outputMetadata, totalLines),
                     range_applied: rangeApplied,
                 },
@@ -1811,7 +2233,7 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                 return { error: { error } };
             // Prefer files_with_matches: OpenCode glob/grep often returns path lists.
             // Content-mode GrepSuccess also works but needs GrepFileMatch nesting.
-            const files = extractPathLines(output);
+            const files = extractGroundedPaths(output, resultRoot);
             const cwd = resultRoot ?? "";
             return {
                 success: {
@@ -1855,19 +2277,20 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             // Pi results carry truncation structurally (PiReadExecSuccess field 2),
             // which is how Cursor's own executors report a capped payload.
             const content = unwrapReadOutput(output);
-            const truncation = readTruncationMessage(output, content);
+            const truncation = readTruncationMessage(output, content, resultMetadata);
             return { success: { output: content, ...(truncation ? { truncation } : {}) } };
         }
         case "shell_result": {
             const command = str(resultMetadata?.command) ?? "";
             const workingDirectory = str(resultMetadata?.working_directory) ?? "";
+            const stdout = groundShellPathText(output, shellPathRoot(resultMetadata, resultRoot));
             if (error) {
                 return {
                     failure: {
                         command,
                         working_directory: workingDirectory,
                         exit_code: 1,
-                        stdout: output || "",
+                        stdout: stdout || "",
                         stderr: error,
                         aborted: false,
                     },
@@ -1888,7 +2311,7 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                         command: shellOutcome.command || command,
                         working_directory: shellOutcome.workingDirectory || workingDirectory,
                         exit_code: 0,
-                        stdout: output,
+                        stdout: stdout,
                         shell_id: shellOutcome.shellId,
                         pid: shellOutcome.pid,
                         ms_to_wait: shellOutcome.msToWait,
@@ -1906,18 +2329,29 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                     command,
                     working_directory: workingDirectory,
                     exit_code: exitCode,
-                    stdout: output,
+                    stdout: stdout,
                 },
             };
         }
         case "pi_bash_result":
+            if (error)
+                return { error: { error } };
+            return { success: { output: groundShellPathText(output, shellPathRoot(resultMetadata, resultRoot)) } };
         case "pi_edit_result":
+            if (error)
+                return { error: { error } };
+            return { success: { output } };
         case "pi_grep_result":
         case "pi_find_result":
-        case "pi_ls_result":
             if (error)
                 return { error: { error } };
-            return { success: { output } };
+            return { success: { output: groundSearchOutput(output, resultRoot) } };
+        case "pi_ls_result": {
+            if (error)
+                return { error: { error } };
+            const listing = parseOpenCode2DirectoryListing(output, resultRoot);
+            return { success: { output: listing?.text ?? groundSearchOutput(output, resultRoot) } };
+        }
         case "delete_result":
             if (error)
                 return { error: { path: "", error } };
@@ -1963,17 +2397,25 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
         case "ls_result": {
             if (error)
                 return { error: { path: "", error } };
-            const rootPath = resultRoot ?? "";
-            const entries = extractPathLines(output);
+            const listing = parseOpenCode2DirectoryListing(output, resultRoot);
+            const rootPath = listing?.directory || resultRoot || "";
+            const entries = listing ? listing.entries : extractGroundedPaths(output, resultRoot);
+            const directories = listing?.directories ?? [];
+            const files = listing?.files ?? entries;
             return {
                 success: {
                     directory_tree_root: {
                         abs_path: rootPath,
-                        children_dirs: [],
-                        children_files: entries.map((name) => ({
-                            name: name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name,
+                        children_dirs: directories.map((entry) => ({
+                            abs_path: stripTrailingPathSeparator(entry),
+                            children_dirs: [],
+                            children_files: [],
+                            num_files: 0,
                         })),
-                        num_files: entries.length,
+                        children_files: files.map((entry) => ({
+                            name: listedEntryName(entry),
+                        })),
+                        num_files: files.length,
                     },
                 },
             };
@@ -1985,17 +2427,34 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             // a read call returns through mcp_result. Scope the unwrap to toolName
             // "read" so a non-read MCP tool whose output merely contains a
             // "<content>"-like block is never rewritten.
+            if (toolName === "grep" || toolName === "glob") {
+                return {
+                    success: {
+                        content: [{ text: { text: groundSearchOutput(output, resultRoot) } }],
+                        is_error: false,
+                    },
+                };
+            }
             if (toolName !== "read") {
                 return { success: { content: [{ text: { text: output } }], is_error: false } };
             }
+            const listing = parseOpenCode2DirectoryListing(output, resultRoot);
+            if (listing) {
+                return {
+                    success: { content: [{ text: { text: listing.text } }], is_error: false },
+                };
+            }
             // Carry the truncation notice as its own content item: the file content
             // item stays byte-exact, so it can still never be echoed into a write.
-            const notice = readTruncationNotice(output);
+            const notices = [
+                readTruncationNotice(output, resultMetadata),
+                readLongLineTruncationNotice(output),
+            ].filter((notice) => !!notice);
             return {
                 success: {
                     content: [
                         { text: { text: unwrapReadOutput(output) } },
-                        ...(notice ? [{ text: { text: notice } }] : []),
+                        ...notices.map((notice) => ({ text: { text: notice } })),
                     ],
                     is_error: false,
                 },
@@ -2072,7 +2531,19 @@ function readEnvelopeFooter(output) {
     return output.slice(start + 2, close);
 }
 /** Recover full-file metadata before unwrapReadOutput removes OpenCode's footer. */
-function parseOpenCodeReadMetadata(output) {
+function parseOpenCodeReadMetadata(output, resultMetadata) {
+    const opencode2 = parseOpenCode2FileRead(output, resultMetadata);
+    if (opencode2) {
+        return {
+            ...(opencode2.startLine !== undefined ? { startLine: opencode2.startLine } : {}),
+            ...(opencode2.endLine !== undefined ? { endLine: opencode2.endLine } : {}),
+            ...(opencode2.totalLines !== undefined ? { totalLines: opencode2.totalLines } : {}),
+            ...(opencode2.nextOffset !== undefined ? { nextOffset: opencode2.nextOffset } : {}),
+            outputCapped: opencode2.outputCapped,
+            hostTruncated: opencode2.hostTruncated,
+            ...(opencode2.truncatedLines.length > 0 ? { truncatedLines: opencode2.truncatedLines } : {}),
+        };
+    }
     const footer = readEnvelopeFooter(output);
     const showing = /Showing lines (\d+)-(\d+)(?: of (\d+))?\./.exec(footer);
     if (showing) {
@@ -2104,9 +2575,9 @@ function restoreCompleteReadTerminator(content, readPath, metadata, resultMetada
         || num(resultMetadata?.limit) !== undefined
         || content.endsWith("\n"))
         return content;
-    const absolute = path.isAbsolute(readPath)
+    const absolute = isAbsoluteToolPath(readPath)
         ? readPath
-        : path.resolve(workspaceRoot ?? process.cwd(), readPath);
+        : joinToolPath(workspaceRoot ?? process.cwd(), readPath);
     let fd;
     try {
         fd = fs.openSync(absolute, "r");
@@ -2153,8 +2624,8 @@ function restoreCompleteReadTerminator(content, readPath, metadata, resultMetada
  * that, keeping the signal out of the file content itself so it still cannot be
  * echoed into a write.
  */
-function readTruncationSummary(output) {
-    const meta = parseOpenCodeReadMetadata(output);
+function readTruncationSummary(output, resultMetadata) {
+    const meta = parseOpenCodeReadMetadata(output, resultMetadata);
     if (meta.startLine === undefined || meta.endLine === undefined)
         return undefined;
     // A complete read reports "(End of file …)" and never reaches this shape.
@@ -2163,7 +2634,7 @@ function readTruncationSummary(output) {
     return {
         startLine: meta.startLine,
         endLine: meta.endLine,
-        nextOffset: meta.endLine + 1,
+        nextOffset: meta.nextOffset ?? meta.endLine + 1,
         capped: meta.outputCapped === true,
         ...(meta.totalLines !== undefined ? { totalLines: meta.totalLines } : {}),
     };
@@ -2176,7 +2647,7 @@ function readTruncationSummary(output) {
  * would cry wolf on every deliberate paged read.
  */
 function readTruncationNotice(output, resultMetadata) {
-    const summary = readTruncationSummary(output);
+    const summary = readTruncationSummary(output, resultMetadata);
     if (!summary)
         return undefined;
     const rangeRequested = num(resultMetadata?.offset) !== undefined || num(resultMetadata?.limit) !== undefined;
@@ -2191,18 +2662,35 @@ function readTruncationNotice(output, resultMetadata) {
         `acting on the whole file; writing the content above back would delete everything ` +
         `after line ${summary.endLine}.]`);
 }
+function readLongLineTruncationNotice(output) {
+    const lines = parseOpenCodeReadMetadata(output).truncatedLines;
+    if (!lines || lines.length === 0)
+        return undefined;
+    const displayed = lines.slice(0, 8).join(", ");
+    const remainder = lines.length > 8 ? ` and ${lines.length - 8} more` : "";
+    return (`[Partial read: OpenCode shortened ${lines.length === 1 ? "line" : "lines"} ` +
+        `${displayed}${remainder} to ${OPENCODE2_READ_MAX_LINE_CHARS} characters. ` +
+        "It is NOT the complete file. Use a byte-preserving read method to inspect the full " +
+        "line content before acting on the whole file; writing the content above back would lose data.]");
+}
 /** agent.v1.PiTruncation for a capped OpenCode read. */
-function readTruncationMessage(output, content) {
-    const summary = readTruncationSummary(output);
-    if (!summary)
+function readTruncationMessage(output, content, resultMetadata) {
+    const summary = readTruncationSummary(output, resultMetadata);
+    const longLines = parseOpenCodeReadMetadata(output, resultMetadata).truncatedLines;
+    if (!summary && (!longLines || longLines.length === 0))
+        return undefined;
+    const rangeRequested = num(resultMetadata?.offset) !== undefined || num(resultMetadata?.limit) !== undefined;
+    if (summary && rangeRequested && !summary.capped && (!longLines || longLines.length === 0))
         return undefined;
     return {
         truncated: true,
-        truncated_by: summary.capped ? "bytes" : "lines",
-        ...(summary.totalLines !== undefined ? { total_lines: summary.totalLines } : {}),
-        output_lines: Math.max(0, summary.endLine - summary.startLine + 1),
+        truncated_by: summary?.capped ? "bytes" : longLines?.length ? "characters" : "lines",
+        ...(summary?.totalLines !== undefined ? { total_lines: summary.totalLines } : {}),
+        output_lines: summary
+            ? Math.max(0, summary.endLine - summary.startLine + 1)
+            : countLines(content),
         output_bytes: Buffer.byteLength(content, "utf8"),
-        ...(summary.capped ? { max_bytes: OPENCODE_READ_MAX_BYTES } : {}),
+        ...(summary?.capped ? { max_bytes: OPENCODE_READ_MAX_BYTES } : {}),
     };
 }
 /** `tool/read.ts` MAX_BYTES — mirrored only to report the cap, never to apply it. */
@@ -2218,8 +2706,15 @@ function readRangeApplied(resultMetadata, totalLines) {
     return startLine < 0 || startLine <= totalLines;
 }
 function readOutputTruncated(resultMetadata, outputMetadata, totalLines) {
+    if (outputMetadata.truncatedLines && outputMetadata.truncatedLines.length > 0)
+        return true;
     if (outputMetadata.outputCapped)
         return true;
+    if (outputMetadata.hostTruncated) {
+        const rangeRequested = num(resultMetadata?.offset) !== undefined || num(resultMetadata?.limit) !== undefined;
+        if (!rangeRequested)
+            return true;
+    }
     const returnedEnd = outputMetadata.endLine;
     if (returnedEnd === undefined || totalLines === 0)
         return false;
@@ -2233,6 +2728,14 @@ function readOutputTruncated(resultMetadata, outputMetadata, totalLines) {
         : Math.min(totalLines, Math.max(1, startLine) + limit - 1);
     return returnedEnd < expectedEnd;
 }
+function listedEntryName(entry) {
+    const trimmed = stripTrailingPathSeparator(entry);
+    const slash = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+    return slash >= 0 ? trimmed.slice(slash + 1) : trimmed;
+}
+function stripTrailingPathSeparator(entry) {
+    return entry.endsWith("/") || entry.endsWith("\\") ? entry.slice(0, -1) : entry;
+}
 function readFileSize(filePath) {
     if (!filePath)
         return 0;

package/dist/protocol/workspace-grounding.d.ts

@@ -1 +1,17 @@
-export declare function appendWorkspaceRootGrounding(reason: string, workspaceRoot: string | undefined): string;
+export type WorkspaceGroundingOptions = {
+    /** OpenCode 2 file tools take `path` and do not say it must be absolute. */
+    requireAbsolutePathArg?: boolean;
+};
+/**
+ * Attach the exact workspace root to a model-visible string.
+ *
+ * Idempotent: a second call does not stack another root line. The absolute-path
+ * sentence is added only when requested, and only once.
+ */
+export declare function appendWorkspaceRootGrounding(reason: string, workspaceRoot: string | undefined, options?: WorkspaceGroundingOptions): string;
+/**
+ * Checkpointed Runs omit the system prompt, which is where the root normally
+ * lives. Put the same reminder on the live user message so a later turn cannot
+ * invent an absolute prefix before any tool result arrives.
+ */
+export declare function appendCheckpointUserGrounding(userText: string, workspaceRoot: string | undefined, options?: WorkspaceGroundingOptions): string;

package/dist/protocol/workspace-grounding.js

@@ -1,8 +1,37 @@
-export function appendWorkspaceRootGrounding(reason, workspaceRoot) {
+const ABSOLUTE_PATH_ARG = "OpenCode file tools take `path` as an absolute path under this root. Do not pass a project-relative path, and do not invent a different absolute prefix.";
+/**
+ * Attach the exact workspace root to a model-visible string.
+ *
+ * Idempotent: a second call does not stack another root line. The absolute-path
+ * sentence is added only when requested, and only once.
+ */
+export function appendWorkspaceRootGrounding(reason, workspaceRoot, options) {
     if (!workspaceRoot || !workspaceRoot.trim())
         return reason;
-    if (reason.includes("Workspace root:"))
-        return reason;
-    return (`${reason}\nWorkspace root: ${JSON.stringify(workspaceRoot)}. ` +
-        "Resolve workspace paths against exactly this root; never invent an absolute prefix, and verify uncertain paths with an available tool before using them.");
+    const pathSentence = options?.requireAbsolutePathArg ? ` ${ABSOLUTE_PATH_ARG}` : "";
+    if (reason.includes("Workspace root:")) {
+        if (!pathSentence || reason.includes("take `path` as an absolute path"))
+            return reason;
+        return `${reason}${pathSentence}`;
+    }
+    const note = `Workspace root: ${JSON.stringify(workspaceRoot)}. ` +
+        "Resolve workspace paths against exactly this root; never invent an absolute prefix, and verify uncertain paths with an available tool before using them." +
+        pathSentence;
+    if (!reason)
+        return note;
+    return `${reason}\n${note}`;
+}
+/**
+ * Checkpointed Runs omit the system prompt, which is where the root normally
+ * lives. Put the same reminder on the live user message so a later turn cannot
+ * invent an absolute prefix before any tool result arrives.
+ */
+export function appendCheckpointUserGrounding(userText, workspaceRoot, options) {
+    const note = appendWorkspaceRootGrounding("", workspaceRoot, options);
+    if (!note)
+        return userText;
+    if (userText.includes("Workspace root:")) {
+        return appendWorkspaceRootGrounding(userText, workspaceRoot, options);
+    }
+    return userText ? `${userText}\n\n${note}` : note;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",