@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/tools/memory-render.ts

@@ -4,7 +4,10 @@
  *
  * These keep the transcript terse — one status line plus, for `retain`, one
  * `Remember: …` line per stored item — instead of the generic JSON arg tree,
- * which exploded multi-line memory blobs into an unreadable wall.
+ * which exploded multi-line memory blobs into an unreadable wall. The tool
+ * container is a transparent passthrough, so these renderers stay frameless:
+ * a status line with a couple of dim bullets reads far cleaner than boxing a
+ * one-line memory note.
  */
 import type { Component } from "@prometheus-ai/tui";
 import { Text } from "@prometheus-ai/tui";
@@ -46,10 +49,11 @@ function queryHeader(
 	icon: ToolUIStatus,
 	theme: Theme,
 	meta?: string[],
+	iconOverride?: string,
 ): string {
 	const trimmed = replaceTabs((query ?? "").trim());
 	const description = trimmed ? truncateToWidth(trimmed, 80, Ellipsis.Unicode) : undefined;
-	return renderStatusLine({ icon, title, description, meta }, theme);
+	return renderStatusLine({ icon, iconOverride, title, description, meta }, theme);
 }
 
 function retainComponent(contents: string[], header: string, getExpanded: () => boolean, theme: Theme): Component {
@@ -93,7 +97,11 @@ export const retainToolRenderer = {
 		// trailing period so it reads cleanly as a status meta segment.
 		const summary = resultText(result).replace(/\.$/, "");
 		const header = renderStatusLine(
-			{ icon: "success", title: "Retain", meta: summary ? [summary] : undefined },
+			{
+				iconOverride: theme.styledSymbol("tool.memory", "accent"),
+				title: "Retain",
+				meta: summary ? [summary] : undefined,
+			},
 			theme,
 		);
 		return retainComponent(contents, header, () => options.expanded, theme);
@@ -118,9 +126,11 @@ export const recallToolRenderer = {
 		const text = resultText(result);
 		const match = text.match(/^Found (\d+) relevant/);
 		const found = match ? Number(match[1]) : 0;
-		const icon: ToolUIStatus = found > 0 ? "success" : "warning";
 		const meta = [found > 0 ? `${found} found` : "no matches"];
-		const header = queryHeader("Recall", args?.query, icon, theme, meta);
+		const header =
+			found > 0
+				? queryHeader("Recall", args?.query, "success", theme, meta, theme.styledSymbol("tool.memory", "accent"))
+				: queryHeader("Recall", args?.query, "warning", theme, meta);
 		if (found === 0) {
 			return new Text(header, 0, 0);
 		}
@@ -160,7 +170,14 @@ export const reflectToolRenderer = {
 		if (result.isError) {
 			return new Text(formatErrorMessage(resultText(result) || "Reflect failed", theme), 0, 0);
 		}
-		const header = queryHeader("Reflect", args?.query, "success", theme);
+		const header = queryHeader(
+			"Reflect",
+			args?.query,
+			"success",
+			theme,
+			undefined,
+			theme.styledSymbol("tool.memory", "accent"),
+		);
 		const answer = resultText(result);
 		const answerLines = answer.split("\n").filter(line => line.trim().length > 0);
 		return createCachedComponent(

package/src/tools/memory-retain.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@prometheus-ai/agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import retainDescription from "../prompts/tools/retain.md" with { type: "text" };
 import type { ToolSession } from ".";
 
@@ -30,16 +30,16 @@ export class MemoryRetainTool implements AgentTool<typeof memoryRetainSchema> {
 
 	static createIf(session: ToolSession): MemoryRetainTool | null {
 		const backend = session.settings.get("memory.backend");
-		if (backend !== "hindsight" && backend !== "prometheus-memory") return null;
+		if (backend !== "hindsight" && backend !== "mnemopi") return null;
 		return new MemoryRetainTool(session);
 	}
 
 	async execute(_id: string, params: MemoryRetainParams): Promise<AgentToolResult> {
 		const backend = this.session.settings.get("memory.backend");
-		if (backend === "prometheus-memory") {
+		if (backend === "mnemopi") {
 			const state = this.session.getMnemopiSessionState?.();
 			if (!state) {
-				throw new Error("Prometheus Memory backend is not initialised for this session.");
+				throw new Error("Mnemopi backend is not initialised for this session.");
 			}
 
 			for (const item of params.items) {

package/src/tools/path-utils.ts

@@ -398,6 +398,11 @@ export function formatPathRelativeToCwd(
 export function stripOuterDoubleQuotes(input: string): string {
 	return input.startsWith('"') && input.endsWith('"') && input.length > 1 ? input.slice(1, -1) : input;
 }
+function normalizePathSeparators(input: string): string {
+	if (isInternalUrlPath(input)) return input;
+	if (!input.includes("\\")) return input;
+	return input.replace(/\\/g, "/");
+}
 
 export function normalizePathLikeInput(input: string): string {
 	return stripOuterDoubleQuotes(input.trim());
@@ -572,24 +577,30 @@ export interface ResolvedMultiSearchPath {
 	targets?: ResolvedSearchTarget[];
 }
 
-export interface ResolvedMultiFindPattern {
+export interface ResolvedFindTarget {
 	basePath: string;
 	globPattern: string;
-	scopePath: string;
+	hasGlob: boolean;
 }
 
-/**
- * Split a user path into a base path + glob pattern for tools that delegate to
- * APIs accepting separate `path` and `glob` arguments.
- */
+export interface ResolvedMultiFindPattern {
+	targets: ResolvedFindTarget[];
+	scopePath: string;
+}
 export function parseSearchPath(filePath: string): ParsedSearchPath {
-	const normalizedPath = filePath.replace(/\\/g, "/");
-	if (!hasGlobPathChars(normalizedPath)) {
-		return { basePath: filePath };
+	const normalizedPath = normalizePathSeparators(filePath);
+	const segments = normalizedPath.split("/");
+	let firstGlobIndex = -1;
+	for (let i = 0; i < segments.length; i++) {
+		if (hasGlobPathChars(segments[i])) {
+			firstGlobIndex = i;
+			break;
+		}
 	}
 
-	const segments = normalizedPath.split("/");
-	const firstGlobIndex = segments.findIndex(segment => hasGlobPathChars(segment));
+	if (firstGlobIndex === -1) {
+		return { basePath: normalizedPath };
+	}
 
 	if (firstGlobIndex <= 0) {
 		return { basePath: ".", glob: normalizedPath };
@@ -601,6 +612,23 @@ export function parseSearchPath(filePath: string): ParsedSearchPath {
 	};
 }
 
+/**
+ * Async sibling of {@link parseSearchPath} that prefers literal interpretation
+ * when a path containing glob metacharacters resolves to an existing entry on
+ * disk. Disambiguates Next.js/SvelteKit routes like `apps/[id]/page.tsx` —
+ * without this, `[id]` is parsed as a glob character class and silently
+ * matches nothing.
+ */
+export async function parseSearchPathPreferringLiteral(filePath: string, cwd: string): Promise<ParsedSearchPath> {
+	if (!hasGlobPathChars(filePath) || isInternalUrlPath(filePath)) return parseSearchPath(filePath);
+	try {
+		await fs.promises.stat(resolveToCwd(filePath, cwd));
+		return { basePath: normalizePathSeparators(filePath) };
+	} catch {
+		return parseSearchPath(filePath);
+	}
+}
+
 // Parse a find pattern into a base directory path and a glob pattern.
 // Examples:
 //   src/app/**/\*.tsx -> { basePath: "src/app", globPattern: "**/*.tsx", hasGlob: true }
@@ -610,7 +638,8 @@ export function parseSearchPath(filePath: string): ParsedSearchPath {
 //   /abs/path/**/\*.ts -> { basePath: "/abs/path", globPattern: "**/*.ts", hasGlob: true }
 //   src/app -> { basePath: "src/app", globPattern: "**/*", hasGlob: false }
 export function parseFindPattern(pattern: string): ParsedFindPattern {
-	const segments = pattern.split("/");
+	const normalizedPattern = normalizePathSeparators(pattern);
+	const segments = normalizedPattern.split("/");
 	let firstGlobIndex = -1;
 	for (let i = 0; i < segments.length; i++) {
 		if (hasGlobPathChars(segments[i])) {
@@ -620,14 +649,14 @@ export function parseFindPattern(pattern: string): ParsedFindPattern {
 	}
 
 	if (firstGlobIndex === -1) {
-		return { basePath: pattern, globPattern: "**/*", hasGlob: false };
+		return { basePath: normalizedPattern, globPattern: "**/*", hasGlob: false };
 	}
 
 	if (firstGlobIndex === 0) {
-		const needsRecursive = !pattern.startsWith("**/");
+		const needsRecursive = !normalizedPattern.startsWith("**/");
 		return {
 			basePath: ".",
-			globPattern: needsRecursive ? `**/${pattern}` : pattern,
+			globPattern: needsRecursive ? `**/${normalizedPattern}` : normalizedPattern,
 			hasGlob: true,
 		};
 	}
@@ -700,6 +729,7 @@ async function resolveSearchPathItems(
 	pathItems: string[],
 	cwd: string,
 	suffixGlob?: string,
+	fanOutFileItems = false,
 ): Promise<ResolvedMultiSearchPath | undefined> {
 	if (pathItems.length < 1) {
 		return undefined;
@@ -707,7 +737,7 @@ async function resolveSearchPathItems(
 
 	const parsedItems = await Promise.all(
 		pathItems.map(async item => {
-			const parsedPath = parseSearchPath(item);
+			const parsedPath = await parseSearchPathPreferringLiteral(item, cwd);
 			const absoluteBasePath = resolveToCwd(parsedPath.basePath, cwd);
 			const stat = await fs.promises.stat(absoluteBasePath);
 			return { raw: item, parsedPath, absoluteBasePath, stat };
@@ -731,14 +761,27 @@ async function resolveSearchPathItems(
 		}
 		return relativeBasePath === "." ? path.basename(item.absoluteBasePath) : relativeBasePath;
 	});
-	const rootPath = path.parse(commonBasePath).root;
-	const isDegenerateRoot = commonBasePath === rootPath && parsedItems.length > 1;
-	const targets = isDegenerateRoot
-		? parsedItems.map(item => ({
-				basePath: item.absoluteBasePath,
-				glob: item.parsedPath.glob ? combineSearchGlobs(item.parsedPath.glob, suffixGlob) : suffixGlob,
-			}))
-		: undefined;
+	// A single walk rooted at the common ancestor is only safe when that
+	// ancestor is itself one of the requested scopes (e.g. `.` + `src/foo.ts`):
+	// the walk then covers exactly what the caller asked for. When the common
+	// ancestor is an unrequested parent (`.` + `~/.gitconfig` → `$HOME`, or
+	// disjoint trees → `/`), a collapsed walk traverses every unrelated sibling
+	// under it — fan out into per-item targets so each scan stays bounded to a
+	// requested path.
+	const commonIsRequestedScope = parsedItems.some(item => item.absoluteBasePath === commonBasePath);
+	// Walkers prune `.git` unconditionally and honor gitignore, so a plain-file
+	// item folded into a directory walk's glob union (`.` + `.git/config`) can
+	// silently never match. Callers that dedupe overlapping results opt in via
+	// `fanOutFileItems` to get explicit file targets, which bypass the walker.
+	const demotesFileItem =
+		fanOutFileItems && !allExactFiles && parsedItems.some(item => !item.parsedPath.glob && item.stat.isFile());
+	const targets =
+		parsedItems.length > 1 && (!commonIsRequestedScope || demotesFileItem)
+			? parsedItems.map(item => ({
+					basePath: item.absoluteBasePath,
+					glob: item.parsedPath.glob ? combineSearchGlobs(item.parsedPath.glob, suffixGlob) : suffixGlob,
+				}))
+			: undefined;
 
 	return {
 		basePath: commonBasePath,
@@ -753,8 +796,9 @@ export async function resolveExplicitSearchPaths(
 	pathItems: string[],
 	cwd: string,
 	suffixGlob?: string,
+	fanOutFileItems = false,
 ): Promise<ResolvedMultiSearchPath | undefined> {
-	return resolveSearchPathItems([...new Set(pathItems)], cwd, suffixGlob);
+	return resolveSearchPathItems([...new Set(pathItems)], cwd, suffixGlob, fanOutFileItems);
 }
 
 async function resolveFindPatternItems(
@@ -765,30 +809,22 @@ async function resolveFindPatternItems(
 		return undefined;
 	}
 
-	const parsedItems = await Promise.all(
-		patternItems.map(async item => {
-			const parsedPattern = parseFindPattern(item);
-			const absoluteBasePath = resolveToCwd(parsedPattern.basePath, cwd);
-			const stat = await fs.promises.stat(absoluteBasePath);
-			return { raw: item, parsedPattern, absoluteBasePath, stat };
-		}),
-	);
-
-	const commonBasePath = findCommonBasePath(parsedItems.map(item => item.absoluteBasePath));
-	const combinedPatterns = parsedItems.map(item => {
-		const relativeBasePath = normalizePosixPath(path.relative(commonBasePath, item.absoluteBasePath)) || ".";
-		if (item.parsedPattern.hasGlob) {
-			return joinRelativeGlob(relativeBasePath, item.parsedPattern.globPattern);
-		}
-		if (item.stat.isDirectory()) {
-			return joinRelativeGlob(relativeBasePath, "**/*");
-		}
-		return relativeBasePath === "." ? path.basename(item.absoluteBasePath) : relativeBasePath;
+	// Each path becomes its own walk root. Collapsing to a shared common ancestor
+	// (and filtering with a brace-union glob) would force the walker to traverse
+	// and stat every unrelated sibling under that ancestor — two paths under
+	// $HOME would scan all of $HOME. The find tool fans these targets out in
+	// parallel instead, so every scan stays bounded to exactly one requested path.
+	const targets = patternItems.map(item => {
+		const parsedPattern = parseFindPattern(item);
+		return {
+			basePath: resolveToCwd(parsedPattern.basePath, cwd),
+			globPattern: parsedPattern.globPattern,
+			hasGlob: parsedPattern.hasGlob,
+		};
 	});
 
 	return {
-		basePath: commonBasePath,
-		globPattern: buildBraceUnion(combinedPatterns) ?? "**/*",
+		targets,
 		scopePath: toScopeDisplay(patternItems, cwd),
 	};
 }
@@ -907,6 +943,10 @@ export interface ToolScopeOptions {
 	trackImmutableSources?: boolean;
 	/** Honor `exactFilePaths` from {@link resolveExplicitSearchPaths} (search-only). */
 	surfaceExactFilePaths?: boolean;
+	/** Fan plain-file entries out into per-target scans instead of folding them
+	 * into a directory walk's glob union (search-only: the caller must dedupe
+	 * matches from overlapping targets). */
+	fanOutFileTargets?: boolean;
 	/** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
 	multipathStatHint?: string;
 	/** Calling session's settings — forwarded to the internal-URL router so caller-aware handlers (issue://, pr://) honor it. */
@@ -946,6 +986,15 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 	if (rawPaths.some(rawPath => rawPath.length === 0)) {
 		throw new ToolError("`paths` must contain non-empty paths or globs");
 	}
+	// External (http/https/ftp/file) URLs are not searchable; route the caller
+	// to `read` instead of letting the path-resolver surface a confusing
+	// "Path not found" for a slash-stripped URL.
+	const externalUrl = rawPaths.find(rawPath => /^(?:https?|ftp|file|ws|wss):\/\//i.test(rawPath));
+	if (externalUrl) {
+		throw new ToolError(
+			`Cannot ${internalUrlAction} external URL: ${externalUrl}. Use \`read\` to fetch web content, then search the returned text.`,
+		);
+	}
 	const internalRouter = InternalUrlRouter.instance();
 	const resolvedPathInputs: string[] = [];
 	const immutableSourcePaths = new Set<string>();
@@ -989,12 +1038,17 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 	let multiTargets: ResolvedSearchTarget[] | undefined;
 	let exactFilePaths: string[] | undefined;
 	if (effectivePaths.length === 1) {
-		const parsedPath = parseSearchPath(effectivePaths[0] ?? ".");
+		const parsedPath = await parseSearchPathPreferringLiteral(effectivePaths[0] ?? ".", cwd);
 		searchPath = resolveToCwd(parsedPath.basePath, cwd);
 		globFilter = parsedPath.glob;
 		scopePath = formatPathRelativeToCwd(searchPath, cwd);
 	} else {
-		const multiSearchPath = await resolveExplicitSearchPaths(effectivePaths, cwd);
+		const multiSearchPath = await resolveExplicitSearchPaths(
+			effectivePaths,
+			cwd,
+			undefined,
+			opts.fanOutFileTargets === true,
+		);
 		if (!multiSearchPath) {
 			throw new ToolError("`paths` must contain at least one path or glob");
 		}

package/src/tools/plan-mode-guard.ts

@@ -1,16 +1,103 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveLocalUrlToPath, resolveVaultUrlToPath } from "../internal-urls";
+import { HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "@prometheus-ai/hashline";
+import { resolveLocalRoot, resolveLocalUrlToPath, resolveVaultUrlToPath } from "../internal-urls";
 import type { ToolSession } from ".";
 import { normalizeLocalScheme, resolveToCwd } from "./path-utils";
 import { ToolError } from "./tool-errors";
 
 const VAULT_SCHEME_PREFIX = "vault:";
 const LOCAL_SCHEME_PREFIX = "local:";
-const PLAN_ALIAS_FILE = "PLAN.md";
-const LOCAL_PLAN_ALIAS = "local://PLAN.md";
+const HL_TRAILING_TAG_RE = new RegExp(`${HL_FILE_HASH_SEP}[0-9A-Fa-f]{${HL_FILE_HASH_LENGTH}}$`);
 
-function resolveRawPath(session: ToolSession, targetPath: string): string {
-	const normalized = normalizeLocalScheme(targetPath);
+/** Resolve the absolute path of the session's `local://` artifact sandbox.
+ *  Returns `null` when the session has no artifact wiring (e.g. tests). */
+function localSandboxRoot(session: ToolSession): string | null {
+	try {
+		return path.resolve(
+			resolveLocalRoot({
+				getArtifactsDir: session.getArtifactsDir,
+				getSessionId: session.getSessionId,
+			}),
+		);
+	} catch {
+		return null;
+	}
+}
+
+/** True when `absolutePath` resolves inside `root` (== root or under it). */
+function isWithinRoot(absolutePath: string, root: string): boolean {
+	if (absolutePath === root) return true;
+	const sep = `${root}${path.sep}`;
+	return absolutePath.startsWith(sep);
+}
+
+/** Strip the hashline `[path#TAG]` wrapper from a write/edit target so the inner
+ *  filesystem path drives both authorization and resolution. Only unwraps inputs
+ *  that match the strict hashline header shape (`[path]` or `[path#XXXX]` with a
+ *  4-hex tag); anything else returns the original string so the downstream
+ *  resolver surfaces the real error. Exported for callers (e.g. `write`) that
+ *  make scheme/bridge-routing decisions before {@link resolvePlanPath} runs. */
+export function unwrapHashlineHeaderPath(targetPath: string): string {
+	const trimmed = targetPath.trimEnd();
+	if (
+		trimmed.length < HL_FILE_PREFIX.length + HL_FILE_SUFFIX.length ||
+		trimmed[0] !== HL_FILE_PREFIX ||
+		trimmed[trimmed.length - 1] !== HL_FILE_SUFFIX
+	) {
+		return targetPath;
+	}
+	const inner = trimmed.slice(HL_FILE_PREFIX.length, trimmed.length - HL_FILE_SUFFIX.length);
+	const tagMatch = HL_TRAILING_TAG_RE.exec(inner);
+	const pathPart = tagMatch ? inner.slice(0, tagMatch.index) : inner;
+	// A valid header is exactly `PATH` or `PATH#XXXX`; reject any other shape
+	// (selectors, non-hex tags, embedded `#`) so we never silently rewrite a
+	// path the model did not author.
+	if (pathPart.length === 0 || pathPart.includes(HL_FILE_HASH_SEP)) return targetPath;
+	return pathPart;
+}
+
+/** True when `targetPath` resolves into the session-local artifact sandbox.
+ *  Routes through {@link resolvePlanPath} so the guard and the eventual write
+ *  always agree on the absolute target (including bracketed hashline headers,
+ *  `local://` URLs, and bare absolute paths). Files inside the sandbox are not
+ *  part of the working tree, so plan mode treats them as freely writable
+ *  scratch/plan space. */
+function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean {
+	const root = localSandboxRoot(session);
+	if (!root) return false;
+	let resolved: string;
+	try {
+		resolved = resolvePlanPath(session, targetPath);
+	} catch {
+		return false;
+	}
+	if (!path.isAbsolute(resolved)) return false;
+	const absolute = path.resolve(resolved);
+	if (isWithinRoot(absolute, root)) return true;
+	// Compare realpath-normalized forms so that `/tmp/…` vs `/private/tmp/…`
+	// (macOS) and other symlink-collapsed roots both resolve to the same
+	// sandbox identity.
+	try {
+		const realRoot = fs.realpathSync.native(root);
+		if (isWithinRoot(absolute, realRoot)) return true;
+		const realParent = fs.realpathSync.native(path.dirname(absolute));
+		return isWithinRoot(path.join(realParent, path.basename(absolute)), realRoot);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Resolve a write/edit target to its absolute filesystem path, honoring the
+ * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ * Bracketed hashline headers (`[path#TAG]`) are unwrapped first so the inner
+ * filesystem path drives resolution — keeping the plan-mode guard and the
+ * eventual write in lockstep.
+ */
+export function resolvePlanPath(session: ToolSession, targetPath: string): string {
+	const unwrapped = unwrapHashlineHeaderPath(targetPath);
+	const normalized = normalizeLocalScheme(unwrapped);
 	if (normalized.startsWith(LOCAL_SCHEME_PREFIX)) {
 		return resolveLocalUrlToPath(normalized, {
 			getArtifactsDir: session.getArtifactsDir,
@@ -25,37 +112,12 @@ function resolveRawPath(session: ToolSession, targetPath: string): string {
 	return resolveToCwd(normalized, session.cwd);
 }
 
-function isPlanAliasTarget(session: ToolSession, targetPath: string, resolved: string): boolean {
-	const normalized = normalizeLocalScheme(targetPath);
-	if (normalized === LOCAL_PLAN_ALIAS) return true;
-	return resolved === resolveToCwd(PLAN_ALIAS_FILE, session.cwd);
-}
-
 /**
- * Resolve a write/edit target to its absolute filesystem path.
- *
- * In plan mode, transparently redirects `PLAN.md` aliases and targets whose
- * basename matches the plan file's basename to the canonical plan file
- * location at `state.planFilePath`. This lets `write` and `edit` accept the
- * habitual plan filename after approval even when the active artifact has a
- * titled path such as `local://APPROVED.md`.
- *
- * Outside plan mode (or when the basename does not match) this is a no-op.
+ * Plan mode keeps the working tree read-only while letting the agent draft its
+ * plan. Writes and edits to the `local://` artifact sandbox are allowed (that is
+ * where the plan and any scratch notes live); anything that would touch the
+ * working tree — or rename/delete a file — is rejected.
  */
-export function resolvePlanPath(session: ToolSession, targetPath: string): string {
-	const resolved = resolveRawPath(session, targetPath);
-
-	const state = session.getPlanModeState?.();
-	if (!state?.enabled) return resolved;
-
-	const planResolved = resolveRawPath(session, state.planFilePath);
-	if (resolved === planResolved) return resolved;
-	if (isPlanAliasTarget(session, targetPath, resolved)) return planResolved;
-	if (path.basename(resolved) !== path.basename(planResolved)) return resolved;
-
-	return planResolved;
-}
-
 export function enforcePlanModeWrite(
 	session: ToolSession,
 	targetPath: string,
@@ -64,9 +126,6 @@ export function enforcePlanModeWrite(
 	const state = session.getPlanModeState?.();
 	if (!state?.enabled) return;
 
-	const resolvedTarget = resolvePlanPath(session, targetPath);
-	const resolvedPlan = resolvePlanPath(session, state.planFilePath);
-
 	if (options?.move) {
 		throw new ToolError("Plan mode: renaming files is not allowed.");
 	}
@@ -75,7 +134,9 @@ export function enforcePlanModeWrite(
 		throw new ToolError("Plan mode: deleting files is not allowed.");
 	}
 
-	if (resolvedTarget !== resolvedPlan) {
-		throw new ToolError(`Plan mode: only the plan file may be modified (${state.planFilePath}).`);
-	}
+	if (targetsLocalSandbox(session, targetPath)) return;
+
+	throw new ToolError(
+		"Plan mode: the working tree is read-only. Write your plan to a local://<slug>-plan.md file instead.",
+	);
 }