pi-agent-flow 1.1.0 → 1.2.2

package/{batch.ts → src/batch.ts}

@@ -9,6 +9,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Type } from "@sinclair/typebox";
+import { Text, TruncatedText } from "@mariozechner/pi-tui";
 
 // ---------------------------------------------------------------------------
 // Schema
@@ -83,6 +84,14 @@ interface FileOpInput {
 	l?: number;
 }
 
+interface ContextMapEntry {
+	kind: string;
+	name: string;
+	startLine: number;
+	endLine: number;
+	parent?: string;
+}
+
 interface OpResult {
 	op: "read" | "write" | "edit" | "delete";
 	path: string;
@@ -91,6 +100,11 @@ interface OpResult {
 	bytes?: number;
 	blocksChanged?: number;
 	totalLines?: number;
+	contextMap?: boolean;
+	language?: string;
+	symbols?: ContextMapEntry[];
+	symbolsTruncated?: boolean;
+	warning?: string;
 	truncated?: boolean;
 	nextOffset?: number;
 	error?: string;
@@ -101,6 +115,22 @@ interface ReadTruncationResult {
 	content: string;
 	truncated: boolean;
 	nextOffset?: number;
+	linesRead: number;
+}
+
+interface ReadOptions {
+	/**
+	 * When false, readWithOffsetLimit ignores regular batch MAX_LINES and total
+	 * MAX_BYTES caps. batch_read applies its own safe full-file and targeted-read
+	 * guards before calling this helper.
+	 */
+	truncate?: boolean;
+	toolName?: "batch" | "batch_read";
+}
+
+interface ExecuteOptions {
+	readOptions?: ReadOptions;
+	includeLimitWarnings?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -109,6 +139,9 @@ interface ReadTruncationResult {
 
 const MAX_LINES = 2000;
 const MAX_BYTES = 50 * 1024; // 50KB
+const SAFE_FULL_READ_LIMIT = 300;
+const TARGETED_READ_LINE_LIMIT = 1000;
+const MAX_CONTEXT_MAP_ENTRIES = 100;
 
 function normalizeToLF(text: string): string {
 	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -132,14 +165,366 @@ function stripBom(content: string): { bom: string; text: string } {
 		: { bom: "", text: content };
 }
 
+type ContextLanguage =
+	| "typescript"
+	| "javascript"
+	| "python"
+	| "terraform"
+	| "hcl"
+	| "yaml"
+	| "dockerfile"
+	| "plain";
+
+interface FileContextMap {
+	language: ContextLanguage;
+	symbols: ContextMapEntry[];
+	symbolsTruncated?: boolean;
+}
+
+function isBatchRead(options: ExecuteOptions): boolean {
+	return options.readOptions?.toolName === "batch_read";
+}
+
+function isFullFileRead(op: FileOpInput, totalLines: number): boolean {
+	const start = op.s ?? 1;
+	if (start !== 1) return false;
+	return op.l === undefined || op.l >= totalLines;
+}
+
+function buildBatchReadSafetyWarning(): string {
+	return `[batch_read safety] Raw content truncated at ${TARGETED_READ_LINE_LIMIT} lines to preserve context. Adjust your 's' and 'l' parameters to read further.`;
+}
+
+function detectContextLanguage(filePath: string): ContextLanguage {
+	const base = path.basename(filePath);
+	const lowerBase = base.toLowerCase();
+	const ext = path.extname(lowerBase);
+
+	if (
+		lowerBase === "dockerfile" ||
+		lowerBase.startsWith("dockerfile.") ||
+		lowerBase === ".dockerfile" ||
+		lowerBase.endsWith(".dockerfile")
+	) {
+		return "dockerfile";
+	}
+
+	if ([".ts", ".tsx", ".mts", ".cts"].includes(ext)) return "typescript";
+	if ([".js", ".jsx", ".mjs", ".cjs"].includes(ext)) return "javascript";
+	if ([".py", ".pyw"].includes(ext)) return "python";
+	if ([".tf", ".tfvars"].includes(ext)) return "terraform";
+	if (ext === ".hcl") return "hcl";
+	if ([".yml", ".yaml"].includes(ext)) return "yaml";
+	return "plain";
+}
+
+function buildFileContextMap(filePath: string, lines: string[]): FileContextMap {
+	const language = detectContextLanguage(filePath);
+	let symbols: ContextMapEntry[] = [];
+
+	try {
+		switch (language) {
+			case "typescript":
+			case "javascript":
+				symbols = extractTsJsSymbols(lines);
+				break;
+			case "python":
+				symbols = extractPythonSymbols(lines);
+				break;
+			case "terraform":
+			case "hcl":
+				symbols = extractTerraformSymbols(lines);
+				break;
+			case "yaml":
+				symbols = extractYamlSymbols(lines);
+				break;
+			case "dockerfile":
+				symbols = extractDockerfileSymbols(lines);
+				break;
+			default:
+				symbols = [];
+		}
+	} catch {
+		symbols = [];
+	}
+
+	const sorted = symbols
+		.filter((entry) => entry.startLine > 0 && entry.endLine >= entry.startLine)
+		.sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
+
+	return {
+		language,
+		symbols: sorted.slice(0, MAX_CONTEXT_MAP_ENTRIES),
+		symbolsTruncated: sorted.length > MAX_CONTEXT_MAP_ENTRIES || undefined,
+	};
+}
+
+function countLeadingWhitespace(line: string): number {
+	return line.match(/^\s*/)?.[0].length ?? 0;
+}
+
+function findBraceBlockEnd(lines: string[], startIndex: number): number {
+	let depth = 0;
+	let sawOpenBrace = false;
+
+	for (let i = startIndex; i < lines.length; i++) {
+		for (const char of lines[i]) {
+			if (char === "{") {
+				depth++;
+				sawOpenBrace = true;
+			} else if (char === "}") {
+				depth--;
+			}
+		}
+		if (sawOpenBrace && depth <= 0) return i + 1;
+	}
+
+	return sawOpenBrace ? lines.length : startIndex + 1;
+}
+
+function findStatementEnd(lines: string[], startIndex: number): number {
+	for (let i = startIndex; i < lines.length; i++) {
+		if (lines[i].includes(";")) return i + 1;
+	}
+	return startIndex + 1;
+}
+
+function findIndentedBlockEnd(lines: string[], startIndex: number, indent: number): number {
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		const trimmed = lines[i].trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		if (countLeadingWhitespace(lines[i]) <= indent) return i;
+	}
+	return lines.length;
+}
+
+function findYamlBlockEnd(lines: string[], startIndex: number, indent: number): number {
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		const trimmed = lines[i].trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		if (trimmed === "---" || countLeadingWhitespace(lines[i]) <= indent) return i;
+	}
+	return lines.length;
+}
+
+function extractTsJsSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+	const classes: ContextMapEntry[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		let match = line.match(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/);
+		if (match) {
+			entries.push({ kind: "function", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			const entry = { kind: "class", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) };
+			entries.push(entry);
+			classes.push(entry);
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			entries.push({ kind: "interface", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			entries.push({ kind: "type", name: match[1], startLine: i + 1, endLine: line.includes("{") ? findBraceBlockEnd(lines, i) : findStatementEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?enum\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			entries.push({ kind: "enum", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:function\b|(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>)/);
+		if (match) {
+			entries.push({ kind: "function", name: match[1], startLine: i + 1, endLine: line.includes("{") ? findBraceBlockEnd(lines, i) : findStatementEnd(lines, i) });
+		}
+	}
+
+	const methodNameBlacklist = new Set(["if", "for", "while", "switch", "catch", "function"]);
+	for (const classEntry of classes) {
+		for (let i = classEntry.startLine; i < classEntry.endLine - 1 && i < lines.length; i++) {
+			const match = lines[i].match(/^\s*(?:(?:public|private|protected|static|async|override|readonly)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]+>)?\s*\([^)]*\)\s*(?::\s*[^={]+)?\s*\{/);
+			if (!match || methodNameBlacklist.has(match[1])) continue;
+			entries.push({
+				kind: "method",
+				name: `${classEntry.name}.${match[1]}`,
+				parent: classEntry.name,
+				startLine: i + 1,
+				endLine: findBraceBlockEnd(lines, i),
+			});
+		}
+	}
+
+	return entries;
+}
+
+function extractPythonSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+	const classes: Array<ContextMapEntry & { indent: number }> = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(/^(\s*)class\s+([A-Za-z_]\w*)\b/);
+		if (!match) continue;
+		const indent = match[1].length;
+		const entry = { kind: "class", name: match[2], startLine: i + 1, endLine: findIndentedBlockEnd(lines, i, indent), indent };
+		classes.push(entry);
+		entries.push(entry);
+	}
+
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(/^(\s*)(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/);
+		if (!match) continue;
+		const indent = match[1].length;
+		const parent = classes.find((cls) => i + 1 > cls.startLine && i + 1 < cls.endLine && indent > cls.indent);
+		entries.push({
+			kind: parent ? "method" : "function",
+			name: parent ? `${parent.name}.${match[2]}` : match[2],
+			parent: parent?.name,
+			startLine: i + 1,
+			endLine: findIndentedBlockEnd(lines, i, indent),
+		});
+	}
+
+	return entries;
+}
+
+function extractTerraformSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		let match = line.match(/^\s*(resource|data)\s+"([^"]+)"\s+"([^"]+)"\s*\{/);
+		if (match) {
+			entries.push({ kind: match[1], name: `${match[2]}.${match[3]}`, startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(module|variable|output|provider)\s+"([^"]+)"\s*\{/);
+		if (match) {
+			entries.push({ kind: match[1], name: match[2], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(locals|terraform)\s*\{/);
+		if (match) {
+			entries.push({ kind: match[1], name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^([A-Za-z_][\w-]*)\s*=/);
+		if (match) {
+			entries.push({ kind: "assignment", name: match[1], startLine: i + 1, endLine: i + 1 });
+		}
+	}
+
+	return entries;
+}
+
+function extractYamlSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+
+	let docStart = 0;
+	for (let i = 0; i <= lines.length; i++) {
+		if (i < lines.length && lines[i].trim() !== "---") continue;
+		const docEnd = i === lines.length ? lines.length : i;
+		const docLines = lines.slice(docStart, docEnd);
+		const kindLine = docLines.findIndex((line) => /^kind:\s*\S+/.test(line));
+		const nameLine = docLines.findIndex((line) => /^\s{2}name:\s*\S+/.test(line));
+		if (kindLine >= 0 && nameLine >= 0) {
+			const kind = docLines[kindLine].replace(/^kind:\s*/, "").trim();
+			const name = docLines[nameLine].replace(/^\s{2}name:\s*/, "").trim();
+			entries.push({ kind, name, startLine: docStart + 1, endLine: Math.max(docStart + 1, docEnd) });
+		}
+		docStart = i + 1;
+	}
+
+	for (let i = 0; i < lines.length; i++) {
+		const topLevel = lines[i].match(/^([A-Za-z_][\w.-]*):\s*/);
+		if (topLevel) {
+			const key = topLevel[1];
+			entries.push({ kind: "section", name: key, startLine: i + 1, endLine: findYamlBlockEnd(lines, i, 0) });
+
+			if (["jobs", "services", "volumes", "networks"].includes(key)) {
+				for (let j = i + 1; j < lines.length; j++) {
+					const trimmed = lines[j].trim();
+					if (!trimmed || trimmed.startsWith("#")) continue;
+					const indent = countLeadingWhitespace(lines[j]);
+					if (indent <= 0) break;
+					const child = lines[j].match(/^\s{2}([A-Za-z0-9_.-]+):\s*/);
+					if (!child) continue;
+					const childKind = key === "jobs" ? "job" : key.slice(0, -1);
+					entries.push({ kind: childKind, name: child[1], startLine: j + 1, endLine: findYamlBlockEnd(lines, j, 2) });
+				}
+			}
+		}
+
+		const step = lines[i].match(/^\s*-\s+(?:name:\s*(.+)|uses:\s*(.+)|run:\s*(.+))/);
+		if (step) {
+			const name = (step[1] ?? step[2] ?? step[3] ?? "step").trim();
+			entries.push({ kind: "step", name: name.slice(0, 120), startLine: i + 1, endLine: i + 1 });
+		}
+	}
+
+	return entries;
+}
+
+function findDockerInstructionEnd(lines: string[], startIndex: number): number {
+	let endIndex = startIndex;
+	while (endIndex + 1 < lines.length && lines[endIndex].trimEnd().endsWith("\\")) {
+		endIndex++;
+	}
+	return endIndex + 1;
+}
+
+function extractDockerfileSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+	const fromLines: number[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		if (/^\s*FROM\s+/i.test(lines[i])) fromLines.push(i);
+	}
+
+	for (let idx = 0; idx < fromLines.length; idx++) {
+		const i = fromLines[idx];
+		const nextFrom = fromLines[idx + 1] ?? lines.length;
+		const match = lines[i].match(/^\s*FROM\s+(\S+)(?:\s+AS\s+(\S+))?/i);
+		const image = match?.[1] ?? "unknown";
+		const alias = match?.[2];
+		entries.push({ kind: "stage", name: alias ? `${alias} FROM ${image}` : image, startLine: i + 1, endLine: nextFrom });
+	}
+
+	const important = /^(RUN|COPY|ADD|ENTRYPOINT|CMD|EXPOSE|ENV|ARG|WORKDIR)\b\s*(.*)/i;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].trim().match(important);
+		if (!match) continue;
+		entries.push({ kind: match[1].toUpperCase(), name: (match[2] || match[1]).slice(0, 120), startLine: i + 1, endLine: findDockerInstructionEnd(lines, i) });
+	}
+
+	return entries;
+}
+
 function readWithOffsetLimit(
 	content: string,
 	offset?: number,
 	limit?: number,
 	filePath?: string,
+	options: ReadOptions = {},
 ): ReadTruncationResult {
 	const allLines = content.split("\n");
 	const totalFileLines = allLines.length;
+	const shouldTruncate = options.truncate !== false;
+	const toolName = options.toolName ?? "batch";
 
 	// Validate offset
 	if (offset !== undefined && offset > totalFileLines) {
@@ -161,25 +546,30 @@ function readWithOffsetLimit(
 	let truncated = false;
 	let nextOffset: number | undefined;
 
-	// Apply max-lines cap
-	if (selectedLines.length > MAX_LINES) {
+	// Apply max-lines cap for regular batch reads. batch_read clamps oversized
+	// targeted reads before this helper and context-maps large full-file reads.
+	if (shouldTruncate && selectedLines.length > MAX_LINES) {
 		selectedLines = selectedLines.slice(0, MAX_LINES);
 		truncated = true;
 	}
 
+	// A single selected line that exceeds the byte cap is not safely splittable by
+	// line-oriented offsets, so keep the existing hard error in both modes.
+	for (let i = 0; i < selectedLines.length; i++) {
+		if (Buffer.byteLength(selectedLines[i], "utf-8") > MAX_BYTES) {
+			const lineDisplay = startLine + i + 1;
+			throw new Error(
+				`Line ${lineDisplay} exceeds limit. Try: ${toolName} with o:"read", s:${lineDisplay}, l:10, or use bash: head -c ... ${filePath ?? "<file>"}`,
+			);
+		}
+	}
+
 	// Join and check byte size
 	let result = selectedLines.join("\n");
 
-	// If first line alone exceeds byte limit, give a specific hint
-	if (selectedLines.length >= 1 && Buffer.byteLength(selectedLines[0], "utf-8") > MAX_BYTES) {
-		const startLineDisplay = startLine + 1;
-		throw new Error(
-			`Line ${startLineDisplay} exceeds limit. Try: batch with o:"read", s:${startLineDisplay}, l:10, or use bash: head -c ... ${filePath ?? "<file>"}`,
-		);
-	}
-
-	// Truncate by bytes if needed
-	if (Buffer.byteLength(result, "utf-8") > MAX_BYTES) {
+	// Truncate by total bytes for regular batch reads only. batch_read relies on
+	// its line-oriented safety guards and still rejects an individual huge line.
+	if (shouldTruncate && Buffer.byteLength(result, "utf-8") > MAX_BYTES) {
 		let byteAccum = 0;
 		let keepLines = 0;
 		for (let i = 0; i < selectedLines.length; i++) {
@@ -208,7 +598,7 @@ function readWithOffsetLimit(
 		result += `\n\n[${remaining} more lines in file. Use s=${nextOffset} to continue.]`;
 	}
 
-	return { content: result, truncated, nextOffset };
+	return { content: result, truncated, nextOffset, linesRead: selectedLines.length };
 }
 
 function levenshtein(a: string, b: string): number {
@@ -277,8 +667,6 @@ function getErrorHint(error: string): string {
 		return "Merge overlapping edits into one.";
 	if (error.includes("No changes"))
 		return "File already has this content. No edit needed.";
-	if (error.includes("Path traversal"))
-		return "Use a path within the working directory.";
 	if (error.includes("is not readable") || error.includes("not readable"))
 		return "Check file permissions.";
 	if (error.includes("ENOENT") || error.includes("no such file"))
@@ -557,101 +945,7 @@ export function isWithinDirectory(child: string, parent: string): boolean {
 
 async function validatePath(inputPath: string, cwd: string): Promise<string> {
 	const expandedPath = expandTilde(inputPath);
-	const resolved = path.resolve(cwd, expandedPath);
-	const normalizedResolved = path.normalize(resolved);
-	const normalizedCwd = path.normalize(cwd);
-	if (
-		normalizedResolved !== normalizedCwd &&
-		!isWithinDirectory(normalizedResolved, normalizedCwd)
-	) {
-		throw new Error(
-			`Path traversal detected: ${inputPath} resolves outside working directory.`,
-		);
-	}
-
-	// Resolve cwd and file symlinks to prevent traversal via symlink targets.
-	// cwd must also be resolved (e.g. macOS /var -> /private/var).
-	const realCwd = await fs.realpath(cwd);
-
-	let realPath: string;
-	try {
-		realPath = await fs.realpath(resolved);
-	} catch {
-		const normalizedRealCwd = path.normalize(realCwd);
-
-		// Check if the final component is a broken symlink pointing outside cwd.
-		try {
-			const lstat = await fs.lstat(resolved);
-			if (lstat.isSymbolicLink()) {
-				const linkTarget = await fs.readlink(resolved);
-				const realLinkDir = await fs.realpath(path.dirname(resolved));
-				const resolvedTarget = path.resolve(realLinkDir, linkTarget);
-				const normalizedTarget = path.normalize(resolvedTarget);
-				if (
-					normalizedTarget !== normalizedRealCwd &&
-					!isWithinDirectory(normalizedTarget, normalizedRealCwd)
-				) {
-					throw new Error(
-						`Path traversal detected: ${inputPath} symlink points outside working directory.`,
-					);
-				}
-				return resolved;
-			}
-		} catch (lstatErr: any) {
-			if (lstatErr.code !== "ENOENT") throw lstatErr;
-			// Not a symlink, proceed to ancestor fallback
-		}
-
-		// File doesn't exist yet (e.g. write creates new file).
-		// Walk up to the nearest existing ancestor and validate it is within realCwd.
-		let ancestor = path.dirname(resolved);
-		let ancestorReal: string | null = null;
-		while (ancestor && ancestor !== path.dirname(ancestor)) {
-			try {
-				ancestorReal = await fs.realpath(ancestor);
-				break;
-			} catch {
-				ancestor = path.dirname(ancestor);
-			}
-		}
-		if (!ancestorReal) {
-			throw new Error(`Path not found: ${inputPath}`);
-		}
-		const normalizedAncestor = path.normalize(ancestorReal);
-		if (
-			normalizedAncestor !== normalizedRealCwd &&
-			!isWithinDirectory(normalizedAncestor, normalizedRealCwd)
-		) {
-			throw new Error(
-				`Path traversal detected: ${inputPath} ancestor directory is outside working directory.`,
-			);
-		}
-		return resolved;
-	}
-
-	// Validate resolved real path is within realCwd
-	const normalizedReal = path.normalize(realPath);
-	const normalizedRealCwd = path.normalize(realCwd);
-	if (
-		normalizedReal !== normalizedRealCwd &&
-		!isWithinDirectory(normalizedReal, normalizedRealCwd)
-	) {
-		throw new Error(
-			`Path traversal detected: ${inputPath} symlink points outside working directory.`,
-		);
-	}
-
-	// If the requested path is a symlink, return the original path so that
-	// operations like delete can act on the symlink itself.
-	try {
-		const lstat = await fs.lstat(resolved);
-		if (lstat.isSymbolicLink()) {
-			return resolved;
-		}
-	} catch {
-		// ignore
-	}
-	return realPath;
+	return path.resolve(cwd, expandedPath);
 }
 
 // ---------------------------------------------------------------------------
@@ -758,6 +1052,7 @@ async function executeOperations(
 	operations: FileOpInput[],
 	cwd: string,
 	signal?: AbortSignal,
+	options: ExecuteOptions = {},
 ): Promise<{ summary: string; contentText: string; results: OpResult[] }> {
 	const results: OpResult[] = [];
 	let failed = false;
@@ -765,6 +1060,7 @@ async function executeOperations(
 	const counts = { read: 0, write: 0, edit: 0, delete: 0, error: 0, skipped: 0 };
 	const errors: { path: string; op: string; message: string; hint?: string }[] = [];
 	const truncatedFiles: { path: string; shown: number; total: number; nextOffset?: number }[] = [];
+	const includeLimitWarnings = options.includeLimitWarnings ?? true;
 
 	for (const op of operations) {
 		if (signal?.aborted) {
@@ -801,15 +1097,42 @@ async function executeOperations(
 					const allLines = text.split("\n");
 					const totalFileLines = allLines.length;
 
-					const { content: readContent, truncated, nextOffset } =
-						readWithOffsetLimit(text, op.s, op.l, op.p);
+					if (isBatchRead(options) && isFullFileRead(op, totalFileLines) && totalFileLines > SAFE_FULL_READ_LIMIT) {
+						const context = buildFileContextMap(op.p, allLines);
+						results.push({
+							op: "read",
+							path: op.p,
+							status: "ok",
+							totalLines: totalFileLines,
+							contextMap: true,
+							language: context.language !== "plain" ? context.language : undefined,
+							symbols: context.symbols.length > 0 ? context.symbols : undefined,
+							symbolsTruncated: context.symbolsTruncated,
+						});
+						counts.read++;
+						break;
+					}
 
-					if (truncated || (op.l !== undefined && (op.s ?? 1) - 1 + op.l < totalFileLines)) {
-						const shownLines = truncated
-							? (op.l !== undefined
-									? Math.min(op.l, MAX_LINES)
-									: MAX_LINES)
-							: op.l!;
+					let effectiveLimit = op.l;
+					let safetyTruncated = false;
+					let safetyWarning: string | undefined;
+					if (isBatchRead(options) && !isFullFileRead(op, totalFileLines)) {
+						if (effectiveLimit === undefined || effectiveLimit > TARGETED_READ_LINE_LIMIT) {
+							effectiveLimit = TARGETED_READ_LINE_LIMIT;
+							safetyTruncated = true;
+							safetyWarning = buildBatchReadSafetyWarning();
+						}
+					}
+
+					const { content: readContent, truncated, nextOffset, linesRead } =
+						readWithOffsetLimit(text, op.s, effectiveLimit, op.p, options.readOptions);
+					const finalContent = safetyWarning
+						? `${readContent}\n\n${safetyWarning}`
+						: readContent;
+					const finalTruncated = truncated || safetyTruncated;
+
+					if (finalTruncated || (includeLimitWarnings && effectiveLimit !== undefined && (op.s ?? 1) - 1 + effectiveLimit < totalFileLines)) {
+						const shownLines = finalTruncated ? linesRead : effectiveLimit!;
 						truncatedFiles.push({
 							path: op.p,
 							shown: shownLines,
@@ -822,9 +1145,10 @@ async function executeOperations(
 						op: "read",
 						path: op.p,
 						status: "ok",
-						content: readContent,
+						content: finalContent,
 						totalLines: totalFileLines,
-						truncated: truncated || undefined,
+						warning: safetyWarning,
+						truncated: finalTruncated || undefined,
 						nextOffset,
 					});
 					counts.read++;
@@ -995,11 +1319,108 @@ function buildSummary(
 	return parts.join("\n");
 }
 
+function shortenPath(p: string): string {
+	const home = os.homedir();
+	return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
+type BatchTheme = {
+	fg: (color: string, text: string) => string;
+	bold: (s: string) => string;
+	bg: (color: string, text: string) => string;
+};
+
+function extractBatchOps(args: Record<string, unknown>): Array<{ o: string; p: string; e?: unknown[] }> {
+	let rawOps: unknown[];
+	if (Array.isArray(args.o)) rawOps = args.o;
+	else if (Array.isArray(args.op)) rawOps = args.op;
+	else if (Array.isArray(args.operations)) rawOps = args.operations;
+	else if (Array.isArray(args)) rawOps = args;
+	else rawOps = [];
+
+	return rawOps
+		.filter((op): op is Record<string, unknown> => !!op && typeof op === "object")
+		.map((op) => {
+			const opName = String(op.o ?? op.op ?? "?");
+			const opPath = String(op.p ?? op.path ?? "?");
+			const edits = Array.isArray(op.e) ? op.e : Array.isArray(op.edits) ? op.edits : undefined;
+			return { o: opName, p: opPath, e: edits };
+		});
+}
+
+function formatBatchCall(args: Record<string, unknown>): string {
+	const ops = extractBatchOps(args);
+	if (ops.length === 0) return "batch (empty)";
+
+	const parts: string[] = [];
+	for (const op of ops) {
+		const shortPath = shortenPath(op.p);
+		if (op.o === "edit" && op.e && op.e.length > 1) {
+			parts.push(`edit ${shortPath} (${op.e.length} blocks)`);
+		} else {
+			parts.push(`${op.o} ${shortPath}`);
+		}
+	}
+
+	if (parts.length <= 3) {
+		return parts.join(", ");
+	}
+	return `${parts.slice(0, 2).join(", ")} +${parts.length - 2} more`;
+}
+
+function renderBatchCall(args: Record<string, unknown>, theme: BatchTheme): Text {
+	const summary = formatBatchCall(args);
+	return new Text(theme.fg("muted", "batch ") + theme.fg("accent", summary), 0, 0);
+}
+
+function renderBatchResult(
+	result: { content?: Array<{ type: string; text?: string }> },
+	expanded: boolean,
+	_theme: BatchTheme,
+	_args?: Record<string, unknown>,
+): Text | TruncatedText {
+	const fullText = result.content?.find((c) => c.type === "text")?.text ?? "";
+	if (!expanded) {
+		const summary = fullText.split("\n")[0] ?? "";
+		return new TruncatedText(summary, 0, 0);
+	}
+	return new Text(fullText, 0, 0);
+}
+
+function buildContextMapText(result: OpResult): string {
+	const title = result.language || result.symbols ? "context map" : "file summary";
+	const lines: string[] = [`\n--- ${result.path} ${title} ---`];
+	lines.push(`Total lines: ${result.totalLines ?? 0}`);
+	if (result.language) lines.push(`Language: ${result.language}`);
+	lines.push("");
+	lines.push(`Full-file content omitted because file exceeds SAFE_FULL_READ_LIMIT=${SAFE_FULL_READ_LIMIT} lines.`);
+	lines.push("Use targeted reads with s/l, for example:");
+	lines.push(`{ "o": "read", "p": "${result.path}", "s": <startLine>, "l": <lineCount> }`);
+
+	if (result.symbols && result.symbols.length > 0) {
+		lines.push("");
+		lines.push("Context map:");
+		for (const entry of result.symbols) {
+			lines.push(`- ${entry.kind} ${entry.name} ${entry.startLine}-${entry.endLine}`);
+		}
+		if (result.symbolsTruncated) {
+			lines.push(`... [Context map truncated. Over ${MAX_CONTEXT_MAP_ENTRIES} entries detected. Use targeted reads to explore further.]`);
+		}
+	} else if (result.language) {
+		lines.push("");
+		lines.push("No context map entries detected for this structured file.");
+	}
+
+	return lines.join("\n");
+}
+
 function buildContentText(summary: string, results: OpResult[]): string {
 	const sections: string[] = [summary];
 
 	for (const r of results) {
-		if (r.op === "read" && r.status === "ok" && r.content) {
+		if (r.op === "read" && r.status === "ok" && r.contextMap) {
+			sections.push(buildContextMapText(r));
+		} else if (r.op === "read" && r.status === "ok" && r.content) {
 			const lineInfo = r.totalLines !== undefined ? ` (${r.totalLines} lines)` : "";
 			sections.push(`\n--- ${r.path}${lineInfo} ---\n${r.content}`);
 		} else if (r.op === "edit" && r.status === "ok") {
@@ -1021,6 +1442,147 @@ function buildContentText(summary: string, results: OpResult[]): string {
 // Tool definition factory
 // ---------------------------------------------------------------------------
 
+export const BatchReadParams = Type.Object({
+	o: Type.Array(
+		Type.Object({
+			o: Type.Literal("read"),
+			p: Type.String({ description: "Path to the file (relative or absolute)" }),
+			s: Type.Optional(
+				Type.Number({
+					minimum: 1,
+					description:
+						"1-indexed line number to start reading from (offset). Used with o: 'read'.",
+				}),
+			),
+			l: Type.Optional(
+				Type.Number({
+					minimum: 1,
+					description:
+						"Maximum number of lines to read (limit). Used with o: 'read'.",
+				}),
+			),
+		}),
+		{
+			description:
+				"Ordered list of read operations. Executed sequentially. On failure, remaining operations are skipped.",
+		},
+	),
+});
+
+function prepareBatchReadArguments(input: unknown): { o: FileOpInput[] } | unknown {
+	const prepared = prepareArguments(input);
+	const ops = Array.isArray(prepared) ? prepared : (prepared as { o: unknown[] }).o;
+	if (!Array.isArray(ops)) return { o: [] };
+
+	for (const op of ops) {
+		if (!op || typeof op !== "object") continue;
+		const obj = op as Record<string, unknown>;
+		const opType = String(obj.o ?? obj.op ?? "").toLowerCase();
+		if (opType && opType !== "read") {
+			throw new Error(`batch_read only supports read operations. Received: ${opType}`);
+		}
+	}
+	return prepared;
+}
+
+function renderBatchReadCall(args: Record<string, unknown>, theme: BatchTheme): Text {
+	const summary = formatBatchCall(args);
+	return new Text(theme.fg("muted", "batch_read ") + theme.fg("accent", summary), 0, 0);
+}
+
+export function createBatchReadTool() {
+	return {
+		name: "batch_read",
+		label: "batch_read",
+		description: [
+			"Batch read-only file operations — run multiple read ops in a single call.",
+			"Each operation is independent and executes sequentially in array order; on failure, remaining operations are skipped.",
+			`Full-file reads up to ${SAFE_FULL_READ_LIMIT} lines return raw content; larger full-file reads return a context map for code/infra files or total lines for plain text.`,
+			`Targeted reads with l over ${TARGETED_READ_LINE_LIMIT} are clamped with a continuation warning; a single line over the byte limit still errors.`,
+			"Use `o: \"read\"` with `s` (offset) and `l` (limit) for targeted reading. Prefer this over bash sed/head/tail.",
+			"Best for reading multiple files or sections in one call.",
+		].join("\n"),
+		promptSnippet: "Batch read-only file operations — run multiple read ops in one call",
+		promptGuidelines: [
+			"Use batch_read to perform multiple file reads in a single call rather than separate tool calls.",
+			"Prefer batch_read when reading 2+ files or multiple sections of the same file.",
+			`Small full-file reads (<=${SAFE_FULL_READ_LIMIT} lines) return raw content; larger full-file reads return navigable context maps or line counts.`,
+			`Use targeted reads with s/l around context-map entries; targeted reads are capped at ${TARGETED_READ_LINE_LIMIT} lines.`,
+			"Do not retry the same full-file read when a context map is returned.",
+		],
+		parameters: BatchReadParams,
+		prepareArguments: prepareBatchReadArguments,
+
+		async execute(
+			_toolCallId: string,
+			input: unknown,
+			signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: { cwd: string },
+		) {
+			let prepared: unknown;
+			try {
+				prepared = prepareBatchReadArguments(input);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: `Error: ${message}` }],
+					isError: true,
+				};
+			}
+
+			const ops = Array.isArray(prepared)
+				? (prepared as FileOpInput[])
+				: (prepared as { o: FileOpInput[] }).o;
+
+			if (!Array.isArray(ops) || ops.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "Error: o array is required and must not be empty." },
+					],
+					isError: true,
+				};
+			}
+
+			// Defensive validation: reject any non-read operations
+			for (const op of ops) {
+				if (op.o !== "read") {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Error: batch_read only supports read operations. Received ${op.o} for ${op.p}.`,
+							},
+						],
+						isError: true,
+					};
+				}
+			}
+
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Operation aborted." }],
+					isError: true,
+				};
+			}
+
+			const { contentText, results } = await executeOperations(ops, ctx.cwd, signal, {
+				readOptions: { truncate: false, toolName: "batch_read" },
+				includeLimitWarnings: false,
+			});
+
+			return {
+				content: [{ type: "text", text: contentText }],
+				details: { results },
+			};
+		},
+
+		renderCall: (args: Record<string, unknown>, theme: BatchTheme) => renderBatchReadCall(args, theme),
+		renderResult: (result: any, { expanded }: { expanded: boolean }, theme: BatchTheme, args?: Record<string, unknown>) =>
+			renderBatchResult(result, expanded, theme, args),
+	};
+}
+
 export function createBatchTool() {
 	return {
 		name: "batch",
@@ -1079,5 +1641,9 @@ export function createBatchTool() {
 				details: { results },
 			};
 		},
+
+		renderCall: (args: Record<string, unknown>, theme: BatchTheme) => renderBatchCall(args, theme),
+		renderResult: (result: any, { expanded }: { expanded: boolean }, theme: BatchTheme, args?: Record<string, unknown>) =>
+			renderBatchResult(result, expanded, theme, args),
 	};
 }