@bastani/atomic 0.9.2 → 0.9.3-alpha.1

package/dist/core/tools/read.js

@@ -1,26 +1,30 @@
 import { basename, dirname, isAbsolute, relative, resolve as resolvePath, sep } from "node:path";
 import { Text } from "@earendil-works/pi-tui";
 import { constants } from "fs";
-import { access as fsAccess, readFile as fsReadFile } from "fs/promises";
+import { access as fsAccess, readFile as fsReadFile, stat as fsStat } from "fs/promises";
 import { Type } from "typebox";
 import { getReadmePath } from "../../config.js";
 import { keyHint, keyText } from "../../modes/interactive/components/keybinding-hints.js";
+import { parseConflictBlocks, registerConflictBlocks } from "./conflict-registry.js";
 import { getLanguageFromPath, highlightCode } from "../../modes/interactive/theme/theme.js";
 import { formatDimensionNote, resizeImage } from "../../utils/image-resize.js";
 import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
 import { formatPathRelativeToCwdOrAbsolute } from "../../utils/paths.js";
+import { buildDirectoryTree } from "./directory-tree.js";
+import { applyReadLineSelection, extractDocumentMarkdown, isDocumentPath } from "./read-document-extract.js";
+import { isReadableUrlPath } from "./fetch-url.js";
+import { readUrlBranch } from "./read-url.js";
+import { isNotebookPath, readEditableNotebookText } from "./notebook.js";
+import { createHashlineSnapshotStore, formatHashlineContent, recordHashlineSnapshot } from "./hashline.js";
 import { resolveReadPathAsync, resolveToCwd } from "./path-utils.js";
 import { getTextOutput, invalidArgText, replaceTabs, shortenPath, str } from "./render-utils.js";
+import { formatHashlineSelectedLines, isReadResourceSelector, selectExactReadRanges, selectReadRanges, splitReadLineSelector } from "./read-selectors.js";
+import { parseArchiveSelector, readArchiveSelector, readInternalSelector, readSqliteSelector, resolveArchiveSelector, resolveInternalSelector, sqliteSelectorForPath } from "./resource-selectors.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
 const readSchema = Type.Object({
-    path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
-    offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
-    limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
-});
-// Matches mehmoodosman/claude-code DEFAULT_MAX_RESULT_SIZE_CHARS.
-// Reads are blocked (not persisted) because the source is already a file on disk;
-// re-persisting it would be circular.
+    path: Type.String({ description: "File, directory, archive member, SQLite selector, internal resource, image, document, or URL to read. Append selectors such as :raw, :conflicts, :N, :A-B, :A+C, or :A-B,C-D to scope output." }),
+}, { additionalProperties: false });
 const READ_TOOL_MAX_RESULT_CHARS = 50_000;
 const COMPACT_RESOURCE_FILE_NAMES = new Set(["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
 const defaultReadOperations = {
@@ -28,44 +32,27 @@ const defaultReadOperations = {
     access: (path) => fsAccess(path, constants.R_OK),
     detectImageMimeType: detectSupportedImageMimeTypeFromFile,
 };
-function formatReadLineRange(args, theme) {
-    if (args?.offset === undefined && args?.limit === undefined)
-        return "";
-    const startLine = args.offset ?? 1;
-    const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
-    return theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+function formatReadLineRange(_args, _theme) {
+    return "";
 }
 function formatReadCall(args, theme) {
-    const rawPath = str(args?.file_path ?? args?.path);
+    const rawPath = str(args?.path);
     const path = rawPath !== null ? shortenPath(rawPath) : null;
     const invalidArg = invalidArgText(theme);
     const pathDisplay = path === null ? invalidArg : path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
     return `${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}${formatReadLineRange(args, theme)}`;
 }
-function trimTrailingEmptyLines(lines) {
-    let end = lines.length;
-    while (end > 0 && lines[end - 1] === "") {
-        end--;
-    }
-    return lines.slice(0, end);
-}
-function getNonVisionImageNote(model) {
-    if (!model || model.input.includes("image")) {
-        return undefined;
-    }
-    return "[Current model does not support images. The image will be omitted from this request.]";
-}
-function toPosixPath(filePath) {
-    return filePath.split(sep).join("/");
-}
-function formatCount(count) {
-    return count.toLocaleString("en-US");
-}
+function trimTrailingEmptyLines(lines) { let end = lines.length; while (end > 0 && lines[end - 1] === "")
+    end--; return lines.slice(0, end); }
+function getNonVisionImageNote(model) { return !model || model.input.includes("image") ? undefined : "[Current model does not support images. The image will be omitted from this request.]"; }
+function toPosixPath(filePath) { return filePath.split(sep).join("/"); }
+function formatCount(count) { return count.toLocaleString("en-US"); }
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function buildOversizedReadMessage(details) {
     const pathForExample = JSON.stringify(details.path);
+    const rangePathForExample = JSON.stringify(`${details.path}:${details.startLine}+200`);
     const shellPathForExample = shellQuote(details.path);
     const requestedLimitLine = details.requestedLimit !== undefined ? [`Requested line limit: ${formatCount(details.requestedLimit)}`] : [];
     if (details.byteGuidance) {
@@ -77,21 +64,24 @@ function buildOversizedReadMessage(details) {
             "The selected content starts with a single oversized line, so line pagination is not useful. Read byte slices instead. Examples:",
             `- Inspect the start of line ${details.startLine}: sed -n '${details.startLine}p' ${shellPathForExample} | head -c ${DEFAULT_MAX_BYTES}`,
             `- Inspect a later byte window: sed -n '${details.startLine}p' ${shellPathForExample} | tail -c +${DEFAULT_MAX_BYTES + 1} | head -c ${DEFAULT_MAX_BYTES}`,
-            `- Search for relevant text first: grep({ "pattern": "functionName", "path": ${pathForExample}, "limit": 20 })`,
+            `- Search for relevant text first: search({ "pattern": "functionName", "paths": ${pathForExample} })`,
         ].join("\n");
     }
     const targetedSnippetOffset = Math.max(details.startLine, 120);
+    const snippetPathForExample = JSON.stringify(`${details.path}:${targetedSnippetOffset}+80`);
     return [
         `File read blocked: requested selected range is too large (${formatCount(details.chars)} chars; threshold: ${formatCount(details.maxChars)} chars).`,
         `Path: ${details.path}`,
         ...requestedLimitLine,
         "",
         "Read only the needed context incrementally. Examples:",
-        `- Search for relevant symbols first: grep({ "pattern": "functionName", "path": ${pathForExample}, "limit": 20 })`,
-        `- Read a smaller line range: read({ "path": ${pathForExample}, "offset": ${details.startLine}, "limit": 200 })`,
-        `- Read a targeted snippet around a match: read({ "path": ${pathForExample}, "offset": ${targetedSnippetOffset}, "limit": 80 })`,
+        `- Search for relevant symbols first: search({ "pattern": "functionName", "paths": ${pathForExample} })`,
+        `- Read a smaller line range: read({ "path": ${rangePathForExample} })`,
+        `- Read a targeted snippet around a match: read({ "path": ${snippetPathForExample} })`,
     ].join("\n");
 }
+function readSourceMeta(source) { return { meta: { source, sourcePath: source } }; }
+function oversizedReadResult(details) { return { content: [{ type: "text", text: buildOversizedReadMessage(details) }], details: { oversizedRead: details, meta: { source: details.path, sourcePath: details.path, limits: { maxChars: details.maxChars }, } } }; }
 function getPiDocsClassification(absolutePath) {
     const packageRoot = dirname(getReadmePath());
     const relativePath = relative(resolvePath(packageRoot), resolvePath(absolutePath));
@@ -108,7 +98,7 @@ function getPiDocsClassification(absolutePath) {
     return undefined;
 }
 function getCompactReadClassification(args, cwd) {
-    const rawPath = str(args?.file_path ?? args?.path);
+    const rawPath = str(args?.path);
     if (!rawPath)
         return undefined;
     const absolutePath = resolveToCwd(rawPath, cwd);
@@ -144,7 +134,7 @@ function formatReadResult(args, result, options, theme, showImages, _cwd, isErro
     if (!options.expanded && !isError && !oversizedReadBlocked) {
         return "";
     }
-    const rawPath = str(args?.file_path ?? args?.path);
+    const rawPath = str(args?.path);
     const output = oversizedRead ? buildOversizedReadMessage(oversizedRead) : getTextOutput(result, showImages);
     const lang = rawPath && !oversizedReadBlocked ? getLanguageFromPath(rawPath) : undefined;
     const renderedLines = lang ? highlightCode(replaceTabs(output), lang) : output.split("\n");
@@ -170,18 +160,40 @@ function formatReadResult(args, result, options, theme, showImages, _cwd, isErro
     }
     return text;
 }
+function archiveSelectorMemberExists(pathValue, cwd) { const archive = parseArchiveSelector(pathValue); if (!archive || !archive.memberPath)
+    return false; try {
+    readArchiveSelector(resolveArchiveSelector(archive, cwd));
+    return true;
+}
+catch {
+    return false;
+} }
+function appendReadSelectors(pathValue, selector) {
+    const range = selector.ranges?.map((item) => item.end === undefined ? `${item.start}` : `${item.start}-${item.end}`).join(",") ?? (selector.offset ? `${selector.offset}` : "");
+    return `${pathValue}${range ? `:${range}` : ""}${selector.conflicts ? ":conflicts" : ""}${selector.raw ? ":raw" : ""}`;
+}
 export function createReadToolDefinition(cwd, options) {
     const autoResizeImages = options?.autoResizeImages ?? true;
     const ops = options?.operations ?? defaultReadOperations;
+    const hashlineStore = options?.hashlineStore ?? createHashlineSnapshotStore();
     return {
         name: "read",
         label: "read",
-        description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
-        promptSnippet: "Read file contents",
-        promptGuidelines: ["Use read to examine files instead of cat or sed."],
+        description: "Read files, directories, archives, SQLite databases, internal resources, images, documents, and URLs through one path string.",
+        promptSnippet: "Read a path selector.",
+        promptGuidelines: ["Use read to inspect file and resource contents; use path selectors for line ranges, raw output, and conflict views."],
         parameters: readSchema,
         maxResultSizeChars: Infinity,
-        async execute(_toolCallId, { path, offset, limit }, signal, _onUpdate, ctx) {
+        async execute(_toolCallId, { path }, signal, _onUpdate, ctx) {
+            const resourceCtx = ctx;
+            const splitSelector = splitReadLineSelector(path), markerless = path.replace(/:raw(?=(:|$))/g, "").replace(/:conflicts(?=(:|$))/g, ""), sqliteOriginal = sqliteSelectorForPath(markerless, cwd), sqliteDirect = sqliteSelectorForPath(path, cwd);
+            const selector = archiveSelectorMemberExists(path, cwd) ? { path } : sqliteDirect && (sqliteDirect.table === "raw" || sqliteDirect.table === "conflicts") ? { path } : sqliteOriginal?.rowId && splitSelector.path !== markerless ? { path: markerless, raw: splitSelector.raw, conflicts: splitSelector.conflicts } : sqliteOriginal && splitSelector.path === markerless && markerless !== path ? { path: markerless, raw: splitSelector.raw, conflicts: splitSelector.conflicts } : splitSelector.path === path && sqliteDirect ? { path } : splitSelector;
+            const effectivePath = selector.path;
+            const effectiveOffset = selector.offset;
+            const effectiveLimit = selector.limit;
+            const effectiveRanges = selector.ranges;
+            const rawOutput = selector.raw;
+            const conflictsOnly = selector.conflicts;
             return new Promise((resolve, reject) => {
                 if (signal?.aborted) {
                     reject(new Error("Operation aborted"));
@@ -195,22 +207,125 @@ export function createReadToolDefinition(cwd, options) {
                 signal?.addEventListener("abort", onAbort, { once: true });
                 (async () => {
                     try {
-                        const absolutePath = await resolveReadPathAsync(path, cwd);
+                        const archive = parseArchiveSelector(effectivePath);
+                        const sqlite = sqliteSelectorForPath(effectivePath, cwd);
+                        if (isReadableUrlPath(effectivePath)) {
+                            resolve(await readUrlBranch({ effectivePath, rawOutput: rawOutput === true, effectiveRanges, effectiveOffset, effectiveLimit, cwd, ctx, signal, maxChars: READ_TOOL_MAX_RESULT_CHARS, maxBytes: DEFAULT_MAX_BYTES, oversized: oversizedReadResult, sourceMeta: readSourceMeta }));
+                            return;
+                        }
+                        if (sqlite) {
+                            const textContent = readSqliteSelector(sqlite), selection = applyReadLineSelection(textContent.split("\n"), effectiveRanges, effectiveOffset, effectiveLimit, rawOutput), selectedText = selection.lines.join("\n");
+                            if ((effectiveRanges || effectiveOffset) && selection.lines.length === 0) {
+                                const requested = effectiveRanges?.[0]?.start ?? effectiveOffset ?? 1;
+                                resolve({ content: [{ type: "text", text: `Requested line ${requested} is beyond end of resource (${textContent.split("\n").length} lines total).` }], details: undefined });
+                                return;
+                            }
+                            if (selectedText.length > READ_TOOL_MAX_RESULT_CHARS || Buffer.byteLength(selectedText, "utf8") > DEFAULT_MAX_BYTES) {
+                                resolve(oversizedReadResult({ blocked: true, path: effectivePath, chars: selectedText.length, maxChars: READ_TOOL_MAX_RESULT_CHARS, startLine: selection.firstLine, totalFileLines: textContent.split("\n").length, firstLineBytes: Buffer.byteLength(selection.lines[0] ?? "", "utf8"), byteGuidance: false }));
+                                return;
+                            }
+                            resolve({ content: [{ type: "text", text: selectedText }], details: readSourceMeta(effectivePath) });
+                            return;
+                        }
+                        if (archive) {
+                            const resolvedArchive = resolveArchiveSelector(archive, cwd);
+                            const textContent = readArchiveSelector(resolvedArchive);
+                            let allLines = textContent.split("\n");
+                            if (conflictsOnly) {
+                                let inConflict = false;
+                                const conflictLines = allLines.filter((line) => { if (line.startsWith("<<<<<<<"))
+                                    inConflict = true; const keep = inConflict; if (line.startsWith(">>>>>>>"))
+                                    inConflict = false; return keep; });
+                                if (conflictLines.length === 0) {
+                                    resolve({ content: [{ type: "text", text: "No conflict markers found" }], details: undefined });
+                                    return;
+                                }
+                                allLines = conflictLines;
+                            }
+                            const rangeSelection = (rawOutput ? selectExactReadRanges : selectReadRanges)(allLines, effectiveRanges);
+                            const startLine = rangeSelection ? rangeSelection.firstLine - 1 : effectiveOffset ? Math.max(0, effectiveOffset - 1) : 0;
+                            if (startLine >= allLines.length || (effectiveRanges && rangeSelection?.selectedLines.length === 0)) {
+                                resolve({ content: [{ type: "text", text: `Requested line ${startLine + 1} is beyond end of resource (${allLines.length} lines total).` }], details: undefined });
+                                return;
+                            }
+                            const endLine = effectiveLimit !== undefined ? Math.min(startLine + effectiveLimit, allLines.length) : allLines.length;
+                            const selectedLines = rangeSelection?.selectedLines ?? allLines.slice(startLine, endLine);
+                            const selectedText = selectedLines.join("\n");
+                            if (selectedText.length > READ_TOOL_MAX_RESULT_CHARS || Buffer.byteLength(selectedText, "utf8") > DEFAULT_MAX_BYTES) {
+                                resolve(oversizedReadResult({ blocked: true, path: `${resolvedArchive.archivePath}:${resolvedArchive.memberPath}`, chars: selectedText.length, maxChars: READ_TOOL_MAX_RESULT_CHARS, startLine: startLine + 1, totalFileLines: allLines.length, firstLineBytes: Buffer.byteLength(selectedLines[0] ?? "", "utf8"), byteGuidance: false }));
+                                return;
+                            }
+                            resolve({ content: [{ type: "text", text: selectedText }], details: readSourceMeta(`${resolvedArchive.archivePath}:${resolvedArchive.memberPath}`) });
+                            return;
+                        }
+                        if (/^(?:skill|agent|artifact|history|issue|local|memory|pr|conflict|omp|rule|mcp|vault):\/\//.test(effectivePath)) {
+                            const sourcePath = effectivePath.startsWith("local://") ? resolveInternalSelector(effectivePath, cwd) : undefined;
+                            if (sourcePath) {
+                                resolve(await createReadToolDefinition(cwd, options).execute(_toolCallId, { path: appendReadSelectors(sourcePath, selector) }, signal, _onUpdate, ctx));
+                                return;
+                            }
+                            const allLines = (await readInternalSelector(effectivePath, cwd, resourceCtx)).split("\n");
+                            const rangeSelection = (rawOutput ? selectExactReadRanges : selectReadRanges)(allLines, effectiveRanges);
+                            const startLine = rangeSelection ? rangeSelection.firstLine - 1 : effectiveOffset ? Math.max(0, effectiveOffset - 1) : 0;
+                            if (startLine >= allLines.length || (effectiveRanges && rangeSelection?.selectedLines.length === 0)) {
+                                resolve({ content: [{ type: "text", text: `Requested line ${startLine + 1} is beyond end of resource (${allLines.length} lines total).` }], details: undefined });
+                                return;
+                            }
+                            const endLine = effectiveLimit !== undefined ? Math.min(startLine + effectiveLimit, allLines.length) : allLines.length;
+                            const selectedLines = rangeSelection?.selectedLines ?? allLines.slice(startLine, endLine);
+                            const selectedText = selectedLines.join("\n");
+                            if (selectedText.length > READ_TOOL_MAX_RESULT_CHARS || Buffer.byteLength(selectedText, "utf8") > DEFAULT_MAX_BYTES) {
+                                resolve(oversizedReadResult({ blocked: true, path: effectivePath, chars: selectedText.length, maxChars: READ_TOOL_MAX_RESULT_CHARS, startLine: startLine + 1, totalFileLines: allLines.length, firstLineBytes: Buffer.byteLength(selectedLines[0] ?? "", "utf8"), byteGuidance: false }));
+                                return;
+                            }
+                            resolve({ content: [{ type: "text", text: selectedText }], details: readSourceMeta(effectivePath) });
+                            return;
+                        }
+                        if (isReadResourceSelector(effectivePath))
+                            throw new Error(`Read resource selectors are not supported by this filesystem backend: ${path}`);
+                        const absolutePath = await resolveReadPathAsync(effectivePath, cwd);
                         if (aborted)
                             return;
-                        // Check if file exists and is readable.
+                        let content;
+                        let details;
                         await ops.access(absolutePath);
                         if (aborted)
                             return;
+                        if (isDocumentPath(absolutePath) && !rawOutput && !isNotebookPath(absolutePath)) {
+                            const buffer = await ops.readFile(absolutePath);
+                            const textContent = await extractDocumentMarkdown(buffer, absolutePath);
+                            const selection = applyReadLineSelection(textContent.split("\n"), effectiveRanges, effectiveOffset, effectiveLimit, rawOutput);
+                            if (selection.lines.length === 0) {
+                                resolve({ content: [{ type: "text", text: `Requested line ${selection.firstLine} is beyond end of document (${textContent.split("\n").length} lines total).` }], details: undefined });
+                                return;
+                            }
+                            const selectedText = selection.lines.join("\n");
+                            if (selectedText.length > READ_TOOL_MAX_RESULT_CHARS || Buffer.byteLength(selectedText, "utf8") > DEFAULT_MAX_BYTES) {
+                                resolve(oversizedReadResult({ blocked: true, path: absolutePath, chars: selectedText.length, maxChars: READ_TOOL_MAX_RESULT_CHARS, startLine: selection.firstLine, totalFileLines: textContent.split("\n").length, firstLineBytes: Buffer.byteLength(selection.lines[0] ?? "", "utf8"), byteGuidance: false }));
+                                return;
+                            }
+                            content = [{ type: "text", text: selectedText }];
+                            resolve({ content, details: readSourceMeta(absolutePath) });
+                            return;
+                        }
+                        if (!options?.operations && (await fsStat(absolutePath)).isDirectory()) {
+                            const tree = await buildDirectoryTree(absolutePath, { maxDepth: 2, perDirLimit: 12, rootLimit: null });
+                            const allLines = tree.rendered.split("\n"), rangeSelection = (rawOutput ? selectExactReadRanges : selectReadRanges)(allLines, effectiveRanges), startLine = rangeSelection ? rangeSelection.firstLine - 1 : effectiveOffset ? Math.max(0, effectiveOffset - 1) : 0;
+                            if (startLine >= allLines.length || (effectiveRanges && rangeSelection?.selectedLines.length === 0)) {
+                                resolve({ content: [{ type: "text", text: `Requested line ${startLine + 1} is beyond end of directory (${allLines.length} lines total).` }], details: undefined });
+                                return;
+                            }
+                            const endLine = effectiveLimit !== undefined ? Math.min(startLine + effectiveLimit, allLines.length) : allLines.length, selectedLines = rangeSelection?.selectedLines ?? allLines.slice(startLine, endLine);
+                            content = [{ type: "text", text: selectedLines.join("\n") }];
+                            const meta = { ...readSourceMeta(absolutePath).meta, ...(tree.truncated ? { limits: { perDirLimit: 12, totalLines: tree.totalLines } } : {}) };
+                            resolve({ content, details: { isDirectory: true, resolvedPath: absolutePath, meta } });
+                            return;
+                        }
                         const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
-                        let content;
-                        let details;
                         const nonVisionImageNote = getNonVisionImageNote(ctx?.model);
                         if (mimeType) {
-                            // Read image as binary.
                             const buffer = await ops.readFile(absolutePath);
                             if (autoResizeImages) {
-                                // Resize image if needed before sending it back to the model.
                                 const resized = await resizeImage(buffer, mimeType);
                                 if (!resized) {
                                     let textNote = `Read image file [${mimeType}]\n[Image omitted: could not be resized below the inline image size limit.]`;
@@ -242,24 +357,52 @@ export function createReadToolDefinition(cwd, options) {
                             }
                         }
                         else {
-                            // Read text content.
                             const buffer = await ops.readFile(absolutePath);
-                            const textContent = buffer.toString("utf-8");
-                            const allLines = textContent.split("\n");
+                            const textContent = (isNotebookPath(absolutePath) && !rawOutput) ? readEditableNotebookText(absolutePath, effectivePath) : buffer.toString("utf-8");
+                            let allLines = textContent.split("\n");
+                            let conflictLineNumbers;
+                            if (conflictsOnly) {
+                                registerConflictBlocks(cwd, parseConflictBlocks(absolutePath, textContent));
+                                const conflictLines = [];
+                                conflictLineNumbers = [];
+                                let inConflict = false;
+                                allLines.forEach((line, index) => {
+                                    if (line.startsWith("<<<<<<<"))
+                                        inConflict = true;
+                                    if (inConflict) {
+                                        conflictLines.push(line);
+                                        conflictLineNumbers.push(index + 1);
+                                    }
+                                    if (line.startsWith(">>>>>>>"))
+                                        inConflict = false;
+                                });
+                                if (conflictLines.length > 0)
+                                    allLines = conflictLines;
+                                else {
+                                    signal?.removeEventListener("abort", onAbort);
+                                    resolve({ content: [{ type: "text", text: "No conflict markers found" }], details: undefined });
+                                    return;
+                                }
+                            }
                             const totalFileLines = allLines.length;
-                            // Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.
-                            const startLine = offset ? Math.max(0, offset - 1) : 0;
+                            const rangeSelection = (rawOutput ? selectExactReadRanges : selectReadRanges)(allLines, effectiveRanges);
+                            const startLine = rangeSelection ? rangeSelection.firstLine - 1 : effectiveOffset ? Math.max(0, effectiveOffset - 1) : 0;
                             const startLineDisplay = startLine + 1;
-                            // Check if offset is out of bounds.
-                            if (startLine >= allLines.length) {
-                                throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+                            if (startLine >= allLines.length || (effectiveRanges && rangeSelection?.selectedLines.length === 0)) {
+                                const requested = effectiveRanges?.[0]?.start ?? startLineDisplay;
+                                resolve({ content: [{ type: "text", text: `Requested line ${requested} is beyond end of file (${allLines.length} lines total). Use ${effectivePath}:${Math.max(1, allLines.length)} to read the final line.` }], details: undefined });
+                                return;
                             }
                             let selectedContent;
                             let selectedLines;
                             let userLimitedLines;
-                            // If limit is specified by the user, honor it first. Otherwise truncateHead decides.
-                            if (limit !== undefined) {
-                                const endLine = Math.min(startLine + limit, allLines.length);
+                            if (rangeSelection) {
+                                selectedLines = rangeSelection.selectedLines;
+                                selectedContent = rangeSelection.selectedContent;
+                                userLimitedLines = rangeSelection.userLimitedLines;
+                            }
+                            else if (effectiveLimit !== undefined) {
+                                const endLine = Math.min(startLine + effectiveLimit, allLines.length);
                                 selectedLines = allLines.slice(startLine, endLine);
                                 selectedContent = selectedLines.join("\n");
                                 userLimitedLines = endLine - startLine;
@@ -273,60 +416,47 @@ export function createReadToolDefinition(cwd, options) {
                                 const firstLineBytes = Buffer.byteLength(firstSelectedLine, "utf-8");
                                 const selectedLineCount = trimTrailingEmptyLines(selectedLines).length;
                                 const byteGuidance = selectedLineCount <= 1 || firstLineBytes > DEFAULT_MAX_BYTES;
-                                const oversizedRead = {
-                                    blocked: true,
-                                    path: absolutePath,
-                                    chars: selectedContent.length,
-                                    maxChars: READ_TOOL_MAX_RESULT_CHARS,
-                                    startLine: startLineDisplay,
-                                    ...(limit !== undefined ? { requestedLimit: limit } : {}),
-                                    totalFileLines,
-                                    firstLineBytes,
-                                    byteGuidance,
-                                };
-                                details = { oversizedRead };
+                                const oversizedRead = { blocked: true, path: absolutePath, chars: selectedContent.length, maxChars: READ_TOOL_MAX_RESULT_CHARS, startLine: startLineDisplay, ...(effectiveLimit !== undefined ? { requestedLimit: effectiveLimit } : {}), totalFileLines, firstLineBytes, byteGuidance };
+                                details = { oversizedRead, meta: readSourceMeta(absolutePath).meta };
                                 content = [{ type: "text", text: buildOversizedReadMessage(oversizedRead) }];
                             }
                             else {
-                                // Apply truncation, respecting both line and byte limits.
                                 const truncation = truncateHead(selectedContent);
-                                let outputText;
+                                let outputText = truncation.content;
                                 if (truncation.firstLineExceedsLimit) {
-                                    // First line alone exceeds the byte limit. Point the model at a bash fallback.
                                     const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
-                                    outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
-                                    details = { truncation };
+                                    outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${effectivePath} | head -c ${DEFAULT_MAX_BYTES}]`;
+                                    details = { truncation, meta: { source: absolutePath, sourcePath: absolutePath, truncation } };
                                 }
                                 else if (truncation.truncated) {
-                                    // Truncation occurred. Build an actionable continuation notice.
                                     const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
                                     const nextOffset = endLineDisplay + 1;
-                                    outputText = truncation.content;
-                                    if (truncation.truncatedBy === "lines") {
-                                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
-                                    }
-                                    else {
-                                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
-                                    }
-                                    details = { truncation };
+                                    outputText += truncation.truncatedBy === "lines" ? `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Continue with path selector :${nextOffset}.]` : `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Continue with path selector :${nextOffset}.]`;
+                                    details = { truncation, meta: { source: absolutePath, sourcePath: absolutePath, truncation } };
                                 }
-                                else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
-                                    // User-specified limit stopped early, but the file still has more content.
+                                else if (!rawOutput && userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
                                     const remaining = allLines.length - (startLine + userLimitedLines);
                                     const nextOffset = startLine + userLimitedLines + 1;
-                                    outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+                                    outputText = `${truncation.content}\n\n[${remaining} more lines in file. Continue with path selector :${nextOffset}.]`;
                                 }
+                                if (truncation.firstLineExceedsLimit)
+                                    content = [{ type: "text", text: outputText }];
                                 else {
-                                    // No truncation and no remaining user-limited content.
-                                    outputText = truncation.content;
+                                    const snapshot = recordHashlineSnapshot(absolutePath, cwd, textContent, hashlineStore);
+                                    const visibleContent = truncation.truncated ? truncation.content : selectedContent;
+                                    const header = `[${snapshot.displayPath}#${snapshot.tag}]`;
+                                    const selectedConflictLineNumbers = conflictLineNumbers && rangeSelection?.lineNumbers ? rangeSelection.lineNumbers.map((line) => conflictLineNumbers[line - 1]).filter((line) => typeof line === "number") : conflictLineNumbers ? conflictLineNumbers.slice(startLine, startLine + selectedLines.length) : undefined;
+                                    let hashlineOutput = rawOutput ? visibleContent : selectedConflictLineNumbers && visibleContent === selectedContent ? formatHashlineSelectedLines(header, selectedLines, selectedConflictLineNumbers) : rangeSelection && visibleContent === selectedContent ? formatHashlineSelectedLines(header, selectedLines, rangeSelection.lineNumbers) : formatHashlineContent(snapshot, visibleContent, startLineDisplay);
+                                    if (outputText.startsWith(truncation.content) && outputText.length > truncation.content.length)
+                                        hashlineOutput += outputText.slice(truncation.content.length);
+                                    content = [{ type: "text", text: hashlineOutput }];
                                 }
-                                content = [{ type: "text", text: outputText }];
                             }
                         }
                         if (aborted)
                             return;
                         signal?.removeEventListener("abort", onAbort);
-                        resolve({ content, details });
+                        resolve({ content, details: details ?? readSourceMeta(absolutePath) });
                     }
                     catch (error) {
                         signal?.removeEventListener("abort", onAbort);