@oh-my-pi/pi-coding-agent 14.6.2 → 14.6.3

package/src/tools/gh-renderer.ts

@@ -47,6 +47,9 @@ const OP_TITLES: Record<string, string> = {
 	pr_push: "GitHub PR Push",
 	search_issues: "GitHub Search Issues",
 	search_prs: "GitHub Search PRs",
+	search_code: "GitHub Search Code",
+	search_commits: "GitHub Search Commits",
+	search_repos: "GitHub Search Repos",
 	run_watch: "GitHub Run Watch",
 };
 
@@ -99,11 +102,17 @@ function buildOpMeta(args: GithubToolRenderArgs): string[] {
 			break;
 		}
 		case "search_issues":
-		case "search_prs": {
+		case "search_prs":
+		case "search_code":
+		case "search_commits": {
 			if (args.query) meta.push(truncateVisualWidth(args.query, TRUNCATE_LENGTHS.CONTENT));
 			if (args.repo) meta.push(args.repo);
 			break;
 		}
+		case "search_repos": {
+			if (args.query) meta.push(truncateVisualWidth(args.query, TRUNCATE_LENGTHS.CONTENT));
+			break;
+		}
 		case "repo_view": {
 			if (args.repo) meta.push(args.repo);
 			if (args.branch) meta.push(args.branch);

package/src/tools/gh.ts

@@ -113,6 +113,24 @@ const GH_SEARCH_FIELDS = [
 	"updatedAt",
 	"url",
 ];
+const GH_SEARCH_CODE_FIELDS = ["path", "repository", "sha", "textMatches", "url"];
+const GH_SEARCH_COMMITS_FIELDS = ["author", "commit", "committer", "id", "repository", "sha", "url"];
+const GH_SEARCH_REPOS_FIELDS = [
+	"createdAt",
+	"description",
+	"forksCount",
+	"fullName",
+	"isArchived",
+	"isFork",
+	"isPrivate",
+	"language",
+	"openIssuesCount",
+	"owner",
+	"stargazersCount",
+	"updatedAt",
+	"url",
+	"visibility",
+];
 const SEARCH_LIMIT_DEFAULT = 10;
 const SEARCH_LIMIT_MAX = 50;
 const FILE_PREVIEW_LIMIT = 50;
@@ -139,6 +157,9 @@ const githubSchema = Type.Object({
 			"pr_push",
 			"search_issues",
 			"search_prs",
+			"search_code",
+			"search_commits",
+			"search_repos",
 			"run_watch",
 		],
 		{ description: "github operation" },
@@ -186,11 +207,16 @@ const githubSchema = Type.Object({
 	forceWithLease: Type.Optional(Type.Boolean({ description: "force-with-lease push (pr_push)" })),
 	query: Type.Optional(
 		Type.String({
-			description: "search query (search_issues, search_prs)",
+			description: "search query (search_issues, search_prs, search_code, search_commits, search_repos)",
 			examples: ["is:open label:bug"],
 		}),
 	),
-	limit: Type.Optional(Type.Number({ description: "max results (search_issues, search_prs)", default: 10 })),
+	limit: Type.Optional(
+		Type.Number({
+			description: "max results (search_issues, search_prs, search_code, search_commits, search_repos)",
+			default: 10,
+		}),
+	),
 	run: Type.Optional(Type.String({ description: "actions run id or url (run_watch)", examples: ["123456"] })),
 	tail: Type.Optional(Type.Number({ description: "log lines per failed job (run_watch)", default: 15 })),
 });
@@ -414,6 +440,58 @@ interface GhSearchResult {
 	url?: string;
 }
 
+interface GhSearchCodeTextMatch {
+	fragment?: string;
+	property?: string;
+}
+
+interface GhSearchCodeResult {
+	path?: string;
+	repository?: GhSearchRepository | null;
+	sha?: string;
+	textMatches?: GhSearchCodeTextMatch[];
+	url?: string;
+}
+
+interface GhSearchCommitGitActor {
+	name?: string;
+	email?: string;
+	date?: string;
+}
+
+interface GhSearchCommitDetail {
+	author?: GhSearchCommitGitActor | null;
+	committer?: GhSearchCommitGitActor | null;
+	message?: string;
+}
+
+interface GhSearchCommitResult {
+	author?: GhUser | null;
+	commit?: GhSearchCommitDetail | null;
+	committer?: GhUser | null;
+	id?: string;
+	repository?: GhSearchRepository | null;
+	sha?: string;
+	url?: string;
+}
+
+interface GhSearchRepoResult {
+	createdAt?: string;
+	description?: string | null;
+	forksCount?: number;
+	fullName?: string;
+	isArchived?: boolean;
+	isFork?: boolean;
+	isPrivate?: boolean;
+	language?: string | null;
+	openIssuesCount?: number;
+	owner?: GhUser | null;
+	stargazersCount?: number;
+	updatedAt?: string;
+	url?: string;
+	visibility?: string | null;
+}
+
 interface GhRunReference {
 	repo?: string;
 	runId?: number;
@@ -551,14 +629,25 @@ function appendRepoFlag(args: string[], repo: string | undefined, identifier?: s
 	args.push("--repo", repo);
 }
 
+const SEARCH_FIELDS_BY_COMMAND: Record<"issues" | "prs" | "code" | "commits" | "repos", readonly string[]> = {
+	issues: GH_SEARCH_FIELDS,
+	prs: GH_SEARCH_FIELDS,
+	code: GH_SEARCH_CODE_FIELDS,
+	commits: GH_SEARCH_COMMITS_FIELDS,
+	repos: GH_SEARCH_REPOS_FIELDS,
+};
+
 function buildGhSearchArgs(
-	command: "issues" | "prs",
+	command: "issues" | "prs" | "code" | "commits" | "repos",
 	query: string,
 	limit: number,
 	repo: string | undefined,
 ): string[] {
-	const args = ["search", command, "--limit", String(limit), "--json", GH_SEARCH_FIELDS.join(",")];
-	appendRepoFlag(args, repo);
+	const fields = SEARCH_FIELDS_BY_COMMAND[command];
+	const args = ["search", command, "--limit", String(limit), "--json", fields.join(",")];
+	if (command !== "repos") {
+		appendRepoFlag(args, repo);
+	}
 	args.push("--", query);
 	return args;
 }
@@ -1826,6 +1915,94 @@ function formatSearchResults(
 	return lines.join("\n").trim();
 }
 
+function formatSearchCodeResults(query: string, repo: string | undefined, items: GhSearchCodeResult[]): string {
+	const lines: string[] = [`# GitHub code search`, "", `Query: ${query}`];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push("No code matches found.");
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		lines.push(`- ${item.path ?? "(unknown path)"}`);
+		pushLine(lines, "  Repo", item.repository?.nameWithOwner);
+		pushLine(lines, "  Commit", formatShortSha(item.sha));
+		pushLine(lines, "  URL", item.url);
+		const fragment = item.textMatches?.find(match => match.fragment)?.fragment;
+		if (fragment) {
+			pushLine(lines, "  Match", normalizeText(fragment).split("\n", 1)[0]);
+		}
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatSearchCommitMessage(message: string | undefined): string | undefined {
+	if (!message) return undefined;
+	const firstLine = normalizeText(message).split("\n", 1)[0];
+	return firstLine || undefined;
+}
+
+function formatSearchCommitsResults(query: string, repo: string | undefined, items: GhSearchCommitResult[]): string {
+	const lines: string[] = [`# GitHub commits search`, "", `Query: ${query}`];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push("No commits found.");
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		const sha = formatShortSha(item.sha) ?? "(unknown sha)";
+		const subject = formatSearchCommitMessage(item.commit?.message) ?? "(no commit message)";
+		lines.push(`- ${sha} ${subject}`);
+		pushLine(lines, "  Repo", item.repository?.nameWithOwner);
+		pushLine(lines, "  Author", formatAuthor(item.author) ?? item.commit?.author?.name);
+		pushLine(lines, "  Date", item.commit?.author?.date ?? item.commit?.committer?.date);
+		pushLine(lines, "  URL", item.url);
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatSearchReposResults(query: string, items: GhSearchRepoResult[]): string {
+	const lines: string[] = [`# GitHub repositories search`, "", `Query: ${query}`];
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push("No repositories found.");
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		lines.push(`- ${item.fullName ?? "(unknown repository)"}`);
+		const description = normalizeText(item.description).split("\n", 1)[0];
+		if (description) {
+			pushLine(lines, "  Description", description);
+		}
+		pushLine(lines, "  Language", item.language ?? undefined);
+		pushLine(lines, "  Stars", item.stargazersCount);
+		pushLine(lines, "  Forks", item.forksCount);
+		pushLine(lines, "  Open issues", item.openIssuesCount);
+		pushLine(lines, "  Visibility", item.visibility ?? undefined);
+		pushLine(lines, "  Archived", item.isArchived);
+		pushLine(lines, "  Fork", item.isFork);
+		pushLine(lines, "  Updated", item.updatedAt);
+		pushLine(lines, "  URL", item.url);
+	}
+
+	return lines.join("\n").trim();
+}
+
 async function saveArtifactText(session: ToolSession, toolType: string, text: string): Promise<string | undefined> {
 	const { path: artifactPath, id: artifactId } = (await session.allocateOutputArtifact?.(toolType)) ?? {};
 	if (!artifactPath || !artifactId) {
@@ -1898,6 +2075,12 @@ export class GithubTool implements AgentTool<typeof githubSchema, GhToolDetails>
 					return executeSearchIssues(this.session, params, signal);
 				case "search_prs":
 					return executeSearchPrs(this.session, params, signal);
+				case "search_code":
+					return executeSearchCode(this.session, params, signal);
+				case "search_commits":
+					return executeSearchCommits(this.session, params, signal);
+				case "search_repos":
+					return executeSearchRepos(this.session, params, signal);
 				case "run_watch":
 					return executeRunWatch(this.session, this.name, params, signal, onUpdate);
 			}
@@ -2291,6 +2474,51 @@ async function executeSearchPrs(
 	return buildTextResult(formatSearchResults("pull requests", query, repo, items));
 }
 
+async function executeSearchCode(
+	session: ToolSession,
+	params: GithubInput,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<GhToolDetails>> {
+	const query = requireNonEmpty(params.query, "query");
+	const repo = normalizeOptionalString(params.repo);
+	const limit = resolveSearchLimit(params.limit);
+	const args = buildGhSearchArgs("code", query, limit, repo);
+
+	const items = await git.github.json<GhSearchCodeResult[]>(session.cwd, args, signal, {
+		repoProvided: Boolean(repo),
+	});
+	return buildTextResult(formatSearchCodeResults(query, repo, items));
+}
+
+async function executeSearchCommits(
+	session: ToolSession,
+	params: GithubInput,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<GhToolDetails>> {
+	const query = requireNonEmpty(params.query, "query");
+	const repo = normalizeOptionalString(params.repo);
+	const limit = resolveSearchLimit(params.limit);
+	const args = buildGhSearchArgs("commits", query, limit, repo);
+
+	const items = await git.github.json<GhSearchCommitResult[]>(session.cwd, args, signal, {
+		repoProvided: Boolean(repo),
+	});
+	return buildTextResult(formatSearchCommitsResults(query, repo, items));
+}
+
+async function executeSearchRepos(
+	session: ToolSession,
+	params: GithubInput,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<GhToolDetails>> {
+	const query = requireNonEmpty(params.query, "query");
+	const limit = resolveSearchLimit(params.limit);
+	const args = buildGhSearchArgs("repos", query, limit, undefined);
+
+	const items = await git.github.json<GhSearchRepoResult[]>(session.cwd, args, signal);
+	return buildTextResult(formatSearchReposResults(query, items));
+}
+
 async function executeRunWatch(
 	session: ToolSession,
 	toolName: string,

package/src/tools/hindsight-recall.ts

@@ -0,0 +1,70 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { getHindsightSessionState } from "../hindsight/backend";
+import { formatCurrentTime, formatMemories } from "../hindsight/content";
+import recallDescription from "../prompts/tools/recall.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const hindsightRecallSchema = Type.Object({
+	query: Type.String({
+		description: "Natural language search query. Be specific about what you need to know.",
+	}),
+});
+
+export type HindsightRecallParams = Static<typeof hindsightRecallSchema>;
+
+export class HindsightRecallTool implements AgentTool<typeof hindsightRecallSchema> {
+	readonly name = "recall";
+	readonly label = "Recall";
+	readonly description = recallDescription;
+	readonly parameters = hindsightRecallSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): HindsightRecallTool | null {
+		if (session.settings.get("memory.backend") !== "hindsight") return null;
+		return new HindsightRecallTool(session);
+	}
+
+	async execute(_id: string, params: HindsightRecallParams, signal?: AbortSignal): Promise<AgentToolResult> {
+		return untilAborted(signal, async () => {
+			const sessionId = this.session.getSessionId?.();
+			const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+
+			try {
+				const response = await state.client.recall(state.bankId, params.query, {
+					budget: state.config.recallBudget,
+					maxTokens: state.config.recallMaxTokens,
+					types: state.config.recallTypes.length > 0 ? state.config.recallTypes : undefined,
+					tags: state.recallTags,
+					tagsMatch: state.recallTagsMatch,
+				});
+				const results = response.results ?? [];
+				if (results.length === 0) {
+					return {
+						content: [{ type: "text", text: "No relevant memories found." }],
+						details: {},
+					};
+				}
+				const formatted = formatMemories(results);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Found ${results.length} relevant memories (as of ${formatCurrentTime()} UTC):\n\n${formatted}`,
+						},
+					],
+					details: {},
+				};
+			} catch (err) {
+				logger.warn("recall failed", { bankId: state.bankId, error: String(err) });
+				throw err instanceof Error ? err : new Error(String(err));
+			}
+		});
+	}
+}

package/src/tools/hindsight-reflect.ts

@@ -0,0 +1,57 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { getHindsightSessionState } from "../hindsight/backend";
+import { ensureBankMission } from "../hindsight/bank";
+import reflectDescription from "../prompts/tools/reflect.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const hindsightReflectSchema = Type.Object({
+	query: Type.String({ description: "The question to answer using long-term memory." }),
+	context: Type.Optional(Type.String({ description: "Optional additional context to guide the reflection." })),
+});
+
+export type HindsightReflectParams = Static<typeof hindsightReflectSchema>;
+
+export class HindsightReflectTool implements AgentTool<typeof hindsightReflectSchema> {
+	readonly name = "reflect";
+	readonly label = "Reflect";
+	readonly description = reflectDescription;
+	readonly parameters = hindsightReflectSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): HindsightReflectTool | null {
+		if (session.settings.get("memory.backend") !== "hindsight") return null;
+		return new HindsightReflectTool(session);
+	}
+
+	async execute(_id: string, params: HindsightReflectParams, signal?: AbortSignal): Promise<AgentToolResult> {
+		return untilAborted(signal, async () => {
+			const sessionId = this.session.getSessionId?.();
+			const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+
+			try {
+				await ensureBankMission(state.client, state.bankId, state.config, state.missionsSet);
+				const response = await state.client.reflect(state.bankId, params.query, {
+					context: params.context,
+					budget: state.config.recallBudget,
+					tags: state.recallTags,
+					tagsMatch: state.recallTagsMatch,
+				});
+				const text = response.text?.trim() || "No relevant information found to reflect on.";
+				return {
+					content: [{ type: "text", text }],
+					details: {},
+				};
+			} catch (err) {
+				logger.warn("reflect failed", { bankId: state.bankId, error: String(err) });
+				throw err instanceof Error ? err : new Error(String(err));
+			}
+		});
+	}
+}

package/src/tools/hindsight-retain.ts

@@ -0,0 +1,63 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { type Static, Type } from "@sinclair/typebox";
+import { getHindsightSessionState } from "../hindsight/backend";
+import { enqueueRetain } from "../hindsight/retain-queue";
+import retainDescription from "../prompts/tools/retain.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const hindsightRetainSchema = Type.Object({
+	items: Type.Array(
+		Type.Object({
+			content: Type.String({
+				description: "The information to remember. Be specific and self-contained — include who, what, when, why.",
+			}),
+			context: Type.Optional(
+				Type.String({ description: "Optional context describing where this information came from." }),
+			),
+		}),
+		{
+			minItems: 1,
+			description:
+				"One or more memories to retain. Batch related facts in a single call rather than calling retain repeatedly — they are deduplicated and consolidated together.",
+		},
+	),
+});
+
+export type HindsightRetainParams = Static<typeof hindsightRetainSchema>;
+export class HindsightRetainTool implements AgentTool<typeof hindsightRetainSchema> {
+	readonly name = "retain";
+	readonly label = "Retain";
+	readonly description = retainDescription;
+	readonly parameters = hindsightRetainSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): HindsightRetainTool | null {
+		if (session.settings.get("memory.backend") !== "hindsight") return null;
+		return new HindsightRetainTool(session);
+	}
+
+	async execute(_id: string, params: HindsightRetainParams): Promise<AgentToolResult> {
+		const sessionId = this.session.getSessionId?.();
+		const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+		if (!state || !sessionId) {
+			throw new Error("Hindsight backend is not initialised for this session.");
+		}
+
+		// Push every item onto the global queue and return immediately. The
+		// queue flushes either when it reaches its batch threshold or when its
+		// debounce timer fires. If the eventual batch fails, the queue
+		// surfaces a UI-only warning notice — the LLM is not informed.
+		for (const item of params.items) {
+			enqueueRetain(sessionId, item.content, item.context);
+		}
+
+		const count = params.items.length;
+		const noun = count === 1 ? "memory" : "memories";
+		return {
+			content: [{ type: "text", text: `${count} ${noun} queued.` }],
+			details: { count },
+		};
+	}
+}

package/src/tools/index.ts

@@ -30,6 +30,9 @@ import { EvalTool } from "./eval";
 import { ExitPlanModeTool } from "./exit-plan-mode";
 import { FindTool } from "./find";
 import { GithubTool } from "./gh";
+import { HindsightRecallTool } from "./hindsight-recall";
+import { HindsightReflectTool } from "./hindsight-reflect";
+import { HindsightRetainTool } from "./hindsight-retain";
 import { InspectImageTool } from "./inspect-image";
 import { IrcTool } from "./irc";
 import { JobTool } from "./job";
@@ -69,6 +72,9 @@ export * from "./eval";
 export * from "./exit-plan-mode";
 export * from "./find";
 export * from "./gh";
+export * from "./hindsight-recall";
+export * from "./hindsight-reflect";
+export * from "./hindsight-retain";
 export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
@@ -231,6 +237,9 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	web_search: s => new WebSearchTool(s),
 	search_tool_bm25: SearchToolBm25Tool.createIf,
 	write: s => new WriteTool(s),
+	retain: HindsightRetainTool.createIf,
+	recall: HindsightRecallTool.createIf,
+	reflect: HindsightReflectTool.createIf,
 };
 
 export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
@@ -342,6 +351,11 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		) {
 			requestedTools.push("recipe");
 		}
+		if (session.settings.get("memory.backend") === "hindsight") {
+			for (const name of ["recall", "retain", "reflect"]) {
+				if (!requestedTools.includes(name)) requestedTools.push(name);
+			}
+		}
 	}
 	const allTools: Record<string, ToolFactory> = { ...BUILTIN_TOOLS, ...HIDDEN_TOOLS };
 	const isToolAllowed = (name: string) => {
@@ -365,6 +379,9 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");
 		if (name === "irc") return session.settings.get("irc.enabled");
 		if (name === "recipe") return session.settings.get("recipe.enabled");
+		if (name === "retain" || name === "recall" || name === "reflect") {
+			return session.settings.get("memory.backend") === "hindsight";
+		}
 		if (name === "task") {
 			const maxDepth = session.settings.get("task.maxRecursionDepth") ?? 2;
 			const currentDepth = session.taskDepth ?? 0;

package/src/tools/path-utils.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
+import { isEnoent } from "@oh-my-pi/pi-utils";
 
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 const NARROW_NO_BREAK_SPACE = "\u202F";
@@ -442,6 +443,60 @@ export async function resolveExplicitFindPatterns(
 	return resolveFindPatternItems([...new Set(patternItems)], cwd);
 }
 
+/**
+ * Result of partitioning a list of user-supplied paths/globs into entries whose
+ * base directory currently exists on disk versus those that do not.
+ *
+ * Used by multi-path tools (search, find, ast_grep, ast_edit) to tolerate one
+ * or more missing entries in a multi-path call: the surviving entries should
+ * still be searched, with the missing entries surfaced as a non-fatal warning.
+ */
+export interface PartitionedPaths {
+	/** Raw input strings whose resolved base path exists. */
+	valid: string[];
+	/** Raw input strings whose resolved base path is missing (ENOENT). */
+	missing: string[];
+}
+
+/**
+ * Stat each input's base path concurrently; return entries split by existence.
+ *
+ * `splitter` is expected to be {@link parseFindPattern} or
+ * {@link parseSearchPath}: both return a `basePath` field that this helper
+ * resolves against `cwd` and stats. ENOENT is the only swallowed error — every
+ * other stat failure (permission, IO, etc.) propagates so callers do not silently
+ * skip paths that exist but are unreadable.
+ *
+ * Order of `valid` and `missing` follows the input order, so callers can rely
+ * on `valid[0]` matching the first surviving user-supplied entry.
+ */
+export async function partitionExistingPaths(
+	items: string[],
+	cwd: string,
+	splitter: (item: string) => { basePath: string },
+): Promise<PartitionedPaths> {
+	const settled = await Promise.all(
+		items.map(async item => {
+			const { basePath } = splitter(item);
+			const absoluteBasePath = resolveToCwd(basePath, cwd);
+			try {
+				await fs.promises.stat(absoluteBasePath);
+				return { item, exists: true } as const;
+			} catch (err) {
+				if (isEnoent(err)) return { item, exists: false } as const;
+				throw err;
+			}
+		}),
+	);
+	const valid: string[] = [];
+	const missing: string[] = [];
+	for (const entry of settled) {
+		if (entry.exists) valid.push(entry.item);
+		else missing.push(entry.item);
+	}
+	return { valid, missing };
+}
+
 export function resolveReadPath(filePath: string, cwd: string): string {
 	const resolved = resolveToCwd(filePath, cwd);
 	const shellEscapedVariant = tryShellEscapedPath(resolved);

package/src/tools/read.ts

@@ -472,7 +472,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		this.description = prompt.render(readDescription, {
 			DEFAULT_LIMIT: String(this.#defaultLimit),
 			DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
-			IS_HASHLINE_MODE: displayMode.hashLines,
+			IS_HL_MODE: displayMode.hashLines,
 			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
 		});
 	}