@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/tools/descriptors.ts

@@ -244,6 +244,7 @@ function defaultAvailabilityContext(session: ToolSession): ToolAvailabilityConte
 
 function availableFor(name: string, session: ToolSession, context = defaultAvailabilityContext(session)): boolean {
 	if (name === "goal") return context.goalEnabled === true;
+	if (name === "move_session") return typeof session.rescopeSessionCwd === "function";
 	if (context.goalStateToolNames?.includes(name)) return context.goalEnabled === true;
 	if (name === "lsp") return (context.enableLsp ?? true) && Boolean(session.settings.get("lsp.enabled"));
 	if (name === "eval") return context.allowEval ?? true;
@@ -296,6 +297,9 @@ function cached(key: string, load: () => Promise<any>): Promise<any> {
 	}
 	return promise;
 }
+export function evictCachedTool(key: string): void {
+	moduleCache.delete(key);
+}
 
 const loaders: Record<string, Loader> = {
 	read: session => cached("read", () => import("./read")).then(module => new module.ReadTool(session)),
@@ -324,6 +328,17 @@ const loaders: Record<string, Loader> = {
 		cached("checkpoint", () => import("./checkpoint")).then(module => module.RewindTool.createIf(session)),
 	task: session => cached("task", () => import("../task")).then(module => module.TaskTool.create(session)),
 	subagent: session => cached("subagent", () => import("./subagent")).then(module => new module.SubagentTool(session)),
+	python: session =>
+		cached("python", () => import("./python")).then(module =>
+			module.createSessionPythonTool({
+				cwd: session.cwd,
+				getCwd: () => session.cwd,
+				getSessionId: () => session.getSessionId?.() ?? null,
+				registerSessionCleanup: (cleanup: () => Promise<void> | void) => {
+					session.registerSessionCleanup?.(cleanup);
+				},
+			}),
+		),
 	job: session => cached("job", () => import("./job")).then(module => module.JobTool.createIf(session)),
 	monitor: session =>
 		cached("monitor", () => import("./monitor")).then(module => module.MonitorTool.createIf(session)),
@@ -350,6 +365,8 @@ const loaders: Record<string, Loader> = {
 	skill: session => cached("skill", () => import("./skill")).then(module => module.SkillTool.createIf(session)),
 	goal: session =>
 		cached("goal", () => import("../goals/tools/goal-tool")).then(module => new module.GoalTool(session)),
+	move_session: session =>
+		cached("move_session", () => import("./move-session")).then(module => new module.MoveSessionTool(session)),
 	yield: session => cached("yield", () => import("./yield")).then(module => new module.YieldTool(session)),
 	report_finding: _session => cached("review", () => import("./review")).then(module => module.reportFindingTool),
 	resolve: session => cached("resolve", () => import("./resolve")).then(module => new module.ResolveTool(session)),
@@ -404,6 +421,12 @@ const names: Array<[name: string, label: string, summary: string | undefined, lo
 		["debug", "Debug", "Debug a running process with DAP (debugger adapter protocol)", "discoverable"],
 		["bisect", "Bisect", "Find the commit that introduced a regression", "discoverable"],
 		["eval", "Eval", "Execute Python or JavaScript code in an in-process eval backend", "discoverable"],
+		[
+			"python",
+			"Python",
+			"Execute Python in a persistent per-session REPL kernel (every call is appended to the session transcript)",
+			"discoverable",
+		],
 		["calc", "Calc", "Evaluate a mathematical expression", "discoverable"],
 		["ssh", "SSH", "Execute a command on a remote host over SSH", "discoverable"],
 		["github", "GitHub", "Interact with GitHub issues, pull requests, and repositories", "discoverable"],
@@ -429,6 +452,7 @@ const names: Array<[name: string, label: string, summary: string | undefined, lo
 		["write", "Write", "Write content to a file", "discoverable"],
 		["skill", "Skill", "Chain into another available skill", "essential"],
 		["goal", "Goal", undefined, "essential"],
+		["move_session", "Move Session", undefined, "essential"],
 	];
 
 const descriptorRawArgumentValidations: Readonly<Record<string, ToolDescriptorMetadata["rawArgumentValidation"]>> = {

package/src/tools/image-gen.ts

@@ -19,6 +19,7 @@ import {
 	ptree,
 	readSseJson,
 	Snowflake,
+	sanitizeHeaderComponent,
 	untilAborted,
 } from "@gajae-code/utils";
 import * as z from "zod/v4";
@@ -1259,7 +1260,10 @@ function buildOpenAIImageHeaders(model: Model, apiKey: string, sessionId: string
 		headers.set(OPENAI_HEADERS.ACCOUNT_ID, accountId);
 		headers.set(OPENAI_HEADERS.BETA, OPENAI_HEADER_VALUES.BETA_RESPONSES);
 		headers.set(OPENAI_HEADERS.ORIGINATOR, OPENAI_HEADER_VALUES.ORIGINATOR_CODEX);
-		headers.set("User-Agent", `pi/${packageJson.version} (${os.platform()} ${os.release()}; ${os.arch()})`);
+		headers.set(
+			"User-Agent",
+			`pi/${packageJson.version} (${sanitizeHeaderComponent(os.platform())} ${sanitizeHeaderComponent(os.release())}; ${sanitizeHeaderComponent(os.arch())})`,
+		);
 		if (sessionId) {
 			headers.set(OPENAI_HEADERS.CONVERSATION_ID, sessionId);
 			headers.set(OPENAI_HEADERS.SESSION_ID, sessionId);

package/src/tools/index.ts

@@ -32,6 +32,7 @@ import {
 	BUILTIN_TOOLS,
 	HIDDEN_TOOL_DESCRIPTORS,
 	LazyAgentTool,
+	PLATFORM_EXCLUDED_TOOL_DESCRIPTORS,
 	resolveEffectiveDiscoveryMode,
 	type ToolAvailabilityContext,
 } from "./descriptors";
@@ -50,6 +51,18 @@ export type { WriteToolDetails, WriteToolInput } from "./write";
 /** Tool type (AgentTool from pi-ai) */
 export type Tool = AgentTool<any, any, any>;
 
+/** Built-in automation surfaces that an SDK host may back with its own transport. */
+export type AutomationToolName = "browser" | "computer";
+
+/**
+ * Host-owned implementations for the built-in automation surfaces.
+ *
+ * Each implementation must use the matching built-in name. The normal
+ * AgentTool execute signature carries cancellation through its AbortSignal,
+ * while the implementation owns the model-facing schema and description.
+ */
+export type AutomationTools = Partial<Record<AutomationToolName, Tool>>;
+
 export type ContextFileEntry = {
 	path: string;
 	content: string;
@@ -179,6 +192,16 @@ export interface ToolSession {
 	/** Pre-loaded workspace tree (forwarded to subagents to skip re-scanning) */
 	workspaceTree?: WorkspaceTree;
 	/** Pre-loaded skills */
+	/**
+	 * Explicit user home for runtime skill discovery. Tests construct sessions
+	 * against an isolated home because the trusted-home resolver deliberately
+	 * ignores `$HOME` on Linux (it reads the NSS account database instead), so a
+	 * `process.env.HOME` override cannot steer user-scope discovery there.
+	 *
+	 * Production sessions leave this unset and the trusted OS home governs.
+	 * Runtime discovery only; never threaded into capability loading.
+	 */
+	home?: string;
 	skills?: Skill[];
 	/** Currently executing skill prompt, when this tool session is inside one. */
 	getActiveSkillState?: () => Pick<SkillActiveEntry, "skill" | "session_id"> | undefined;
@@ -309,6 +332,18 @@ export interface ToolSession {
 	goalToolAllowedOps?: readonly ("create" | "get" | "complete" | "resume" | "drop" | "pause")[];
 	/** Goal runtime for the active agent session. */
 	getGoalRuntime?: () => GoalRuntime | undefined;
+	/**
+	 * Agent-invokable session rescope (issue #4629): move the whole session to
+	 * an existing directory, running the same sequence as the `/move` handler
+	 * (flush → moveTo → setProjectDir → plugin/capability cache reset). Absent
+	 * in contexts where relocation must not happen: subagent sessions
+	 * (taskDepth > 0) and read-only/restricted bash profiles. Bound to one
+	 * successful move per session, rejects re-entrant calls, and only narrows:
+	 * the canonical (realpath) target must be a strict descendant of the
+	 * canonical current cwd. Throws when the target does not exist, is not a
+	 * directory, or escapes the current scope.
+	 */
+	rescopeSessionCwd?: (path: string) => Promise<{ from: string; to: string }>;
 	/** Bridge to the connected client (e.g. ACP editor host). Tools should route fs/terminal/permission requests through this when available. */
 	getClientBridge?: () => ClientBridge | undefined;
 	/** Get compact conversation context for subagents (excludes tool results, system prompts) */
@@ -533,7 +568,11 @@ export function resolveEvalBackends(session: ToolSession): EvalBackendsAllowance
 /**
  * Create tools from the descriptor registry.
  */
-export async function createTools(session: ToolSession, toolNames?: string[]): Promise<Tool[]> {
+export async function createTools(
+	session: ToolSession,
+	toolNames?: string[],
+	automationTools: AutomationTools = {},
+): Promise<Tool[]> {
 	const includeYield = session.requireYieldTool === true;
 	const enableLsp = session.enableLsp ?? true;
 	let requestedTools =
@@ -614,8 +653,14 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		allowEval,
 		discoveryActive,
 	};
-	const allToolDescriptors: Record<string, (typeof BUILTIN_TOOL_DESCRIPTORS)[string]> = {
+	const builtinToolDescriptors: Record<string, (typeof BUILTIN_TOOL_DESCRIPTORS)[string]> = {
 		...BUILTIN_TOOL_DESCRIPTORS,
+		...(automationTools.computer && !BUILTIN_TOOL_DESCRIPTORS.computer
+			? { computer: PLATFORM_EXCLUDED_TOOL_DESCRIPTORS.computer }
+			: {}),
+	};
+	const allToolDescriptors: Record<string, (typeof BUILTIN_TOOL_DESCRIPTORS)[string]> = {
+		...builtinToolDescriptors,
 		...HIDDEN_TOOL_DESCRIPTORS,
 	};
 	const allToolDescriptorEntries = Object.entries(allToolDescriptors) as Array<
@@ -640,13 +685,21 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	const filteredRequestedTools = requestedTools
 		?.map(name => allToolsByRequestName.get(name))
 		.filter((entry): entry is [string, (typeof BUILTIN_TOOL_DESCRIPTORS)[string]] => entry !== undefined)
-		.filter(([, descriptor]) => descriptor.isAvailable(session, availabilityContext));
+		.filter(
+			([name, descriptor]) =>
+				automationTools[name as AutomationToolName] !== undefined ||
+				descriptor.isAvailable(session, availabilityContext),
+		);
 	const baseEntries =
 		filteredRequestedTools !== undefined
 			? filteredRequestedTools.filter(([name]) => name !== "resolve")
 			: [
-					...Object.entries(BUILTIN_TOOL_DESCRIPTORS)
-						.filter(([, descriptor]) => descriptor.isAvailable(session, availabilityContext))
+					...Object.entries(builtinToolDescriptors)
+						.filter(
+							([name, descriptor]) =>
+								automationTools[name as AutomationToolName] !== undefined ||
+								descriptor.isAvailable(session, availabilityContext),
+						)
 						.map(([name, descriptor]) => [name, descriptor] as const),
 					...(includeYield ? ([["yield", HIDDEN_TOOL_DESCRIPTORS.yield]] as const) : []),
 				];
@@ -657,6 +710,10 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		),
 	);
 	const materialize = async ([name, descriptor]: readonly [string, (typeof BUILTIN_TOOL_DESCRIPTORS)[string]]) => {
+		const externalAutomationTool = automationTools[name as AutomationToolName];
+		if (externalAutomationTool) {
+			return wrapToolWithMetaNotice(new LazyAgentTool(descriptor, externalAutomationTool, undefined, session));
+		}
 		const defer =
 			effectiveDiscoveryMode !== "off" &&
 			descriptor.metadata.loadMode === "discoverable" &&

package/src/tools/move-session.ts

@@ -0,0 +1,107 @@
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import type { Component } from "@gajae-code/tui";
+import { Text } from "@gajae-code/tui";
+import { prompt, sanitizeText } from "@gajae-code/utils";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import moveSessionDescription from "../prompts/tools/move-session.md" with { type: "text" };
+import type { ToolSession } from "./index";
+import { Ellipsis, replaceTabs, shortenPath, truncateToWidth } from "./render-utils";
+import { ToolError } from "./tool-errors";
+
+const moveSessionSchema = z.object({
+	path: z.string().describe("target directory: absolute, or relative to the current session cwd"),
+});
+
+export type MoveSessionToolInput = z.infer<typeof moveSessionSchema>;
+
+export interface MoveSessionToolDetails {
+	from: string;
+	to: string;
+}
+
+export class MoveSessionTool implements AgentTool<typeof moveSessionSchema, MoveSessionToolDetails> {
+	readonly name = "move_session";
+	readonly label = "Move Session";
+	readonly loadMode = "essential" as const;
+	readonly description = prompt.render(moveSessionDescription);
+	readonly parameters = moveSessionSchema;
+	readonly strict = true;
+	readonly intent = "omit" as const;
+	// The move chdirs the process and resets global caches; it must not
+	// interleave with other tool executions across flush→moveTo→chdir.
+	readonly concurrency = "exclusive" as const;
+	// The move commits session-file relocation; aborting mid-sequence would
+	// leave a half-moved session with no rollback path.
+	readonly nonAbortable = true;
+	readonly #session: ToolSession;
+
+	constructor(session: ToolSession) {
+		this.#session = session;
+	}
+
+	async execute(_toolCallId: string, params: MoveSessionToolInput): Promise<AgentToolResult<MoveSessionToolDetails>> {
+		const rescope = this.#session.rescopeSessionCwd;
+		if (!rescope) {
+			throw new ToolError(
+				"This session cannot rescope its working directory; only top-level unrestrained sessions can move.",
+			);
+		}
+		if (typeof params.path !== "string" || params.path.trim() === "") {
+			throw new ToolError("path is required and must be a directory path.");
+		}
+		let moved: { from: string; to: string };
+		try {
+			moved = await rescope(params.path);
+		} catch (error) {
+			throw new ToolError(error instanceof Error ? error.message : String(error));
+		}
+		return {
+			content: [{ type: "text", text: `Session moved to ${moved.to} (from ${moved.from}).` }],
+			details: { from: moved.from, to: moved.to },
+		};
+	}
+}
+
+interface MoveSessionRenderArgs {
+	from: string;
+	to: string;
+}
+
+const MOVE_SESSION_PREVIEW_WIDTH = 120;
+
+export const moveSessionToolRenderer = {
+	renderCall: (args: unknown): Component => {
+		const target =
+			typeof args === "object" && args !== null && typeof (args as { path?: unknown }).path === "string"
+				? (args as { path: string }).path
+				: "";
+		const text = truncateToWidth(
+			replaceTabs(sanitizeText(`move_session ${target}`)),
+			MOVE_SESSION_PREVIEW_WIDTH,
+			Ellipsis.Omit,
+		);
+		return new Text(text, 1, 1);
+	},
+	renderResult: (
+		result: { details?: unknown; isError?: boolean },
+		_options: RenderResultOptions & { renderContext?: Record<string, unknown> },
+		theme: Theme,
+	): Component => {
+		const details = (result.details ?? {}) as Partial<MoveSessionRenderArgs>;
+		const from = typeof details.from === "string" ? details.from : "";
+		const to = typeof details.to === "string" ? details.to : "";
+		const body = result.isError
+			? "move_session failed"
+			: `Session moved: ${shortenPath(sanitizeText(from))} → ${shortenPath(sanitizeText(to))}`;
+		return new Text(
+			theme.fg(
+				result.isError ? "error" : "accent",
+				truncateToWidth(replaceTabs(sanitizeText(body)), MOVE_SESSION_PREVIEW_WIDTH, Ellipsis.Omit),
+			),
+			1,
+			1,
+		);
+	},
+};

package/src/tools/python.ts

@@ -0,0 +1,205 @@
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import { type Static, z } from "@gajae-code/ai/core";
+import { logger } from "@gajae-code/utils";
+import { disposeKernelSessionsByOwner, executePython } from "../eval/py/executor";
+import type { ToolDefinition } from "../extensibility/extensions/types";
+import { applyToolProxy } from "../extensibility/tool-proxy";
+import {
+	openPythonKernelTranscript,
+	type PythonKernelTranscript,
+	type PythonTranscriptRecord,
+} from "../gjc-runtime/python-transcript";
+import { sessionIpykernelsArtifactsDir } from "../gjc-runtime/session-layout";
+import pythonToolDescription from "../prompts/tools/python.md" with { type: "text" };
+
+export const PYTHON_TOOL_NAME = "python";
+
+export function pythonKernelOwnerId(sessionId: string): string {
+	return `python:${sessionId}`;
+}
+
+export interface SessionPythonToolInput {
+	/** Working directory for kernel execution (session cwd). */
+	cwd: string;
+	/** Resolve the GJC session id used for the kernel owner and transcript paths. */
+	getSessionId: () => string | null;
+	/** Register cleanup with the current logical session lifecycle. */
+	registerSessionCleanup: (cleanup: () => Promise<void> | void) => void;
+}
+
+const paramsSchema = z.object({
+	action: z
+		.enum(["execute", "clear"])
+		.default("execute")
+		.describe(
+			'"execute" runs `code` in the persistent per-session REPL and is the default. "clear" disposes this session\'s kernel; the next execute starts a fresh kernel.',
+		),
+	code: z
+		.string()
+		.optional()
+		.describe('Python source to execute when action is "execute" (required then, ignored for "clear").'),
+});
+
+const NO_SESSION_ERROR = "Python requires a GJC session id. Start or resume a session before using this tool.";
+
+interface TranscriptExecutionResult {
+	output: string;
+	exitCode: number | null;
+	cancelled: boolean;
+	truncated: boolean;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isCancellationError(error: unknown, signal: AbortSignal | undefined): boolean {
+	return (
+		signal?.aborted === true ||
+		(error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) ||
+		(error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError"))
+	);
+}
+
+function appendFailureTrailer(output: string, appendFailure: string | undefined): string {
+	if (appendFailure === undefined) return output;
+	const trailer = `[transcript append failed: ${appendFailure}]`;
+	return output.length > 0 ? `${output}\n${trailer}` : trailer;
+}
+
+export function createSessionPythonTool(input: SessionPythonToolInput): AgentTool {
+	let armedForSession: string | null = null;
+	const seenOwnerIds = new Set<string>();
+	let currentTranscript: PythonKernelTranscript | null = null;
+
+	const armCleanupForSession = (sessionId: string): void => {
+		if (armedForSession === sessionId) return;
+		input.registerSessionCleanup(async () => {
+			await Promise.all([...seenOwnerIds].map(ownerId => disposeKernelSessionsByOwner(ownerId)));
+			seenOwnerIds.clear();
+			currentTranscript = null;
+			armedForSession = null;
+		});
+		armedForSession = sessionId;
+	};
+
+	const appendTranscript = async (
+		sessionId: string,
+		code: string,
+		result: TranscriptExecutionResult,
+	): Promise<string | undefined> => {
+		if (currentTranscript === null) {
+			currentTranscript = openPythonKernelTranscript({
+				cwd: input.cwd,
+				sessionId,
+				kernelInstanceId: crypto.randomUUID(),
+			});
+		}
+		const record: PythonTranscriptRecord = {
+			timestamp: new Date().toISOString(),
+			code,
+			output: result.output,
+			exitCode: result.exitCode,
+			cancelled: result.cancelled,
+			truncated: result.truncated,
+		};
+		try {
+			await currentTranscript.append(record);
+			return undefined;
+		} catch (error) {
+			const message = errorMessage(error);
+			logger.warn("Python transcript append failed", { sessionId, error: message });
+			return message;
+		}
+	};
+
+	const definition: ToolDefinition<typeof paramsSchema> = {
+		name: PYTHON_TOOL_NAME,
+		label: "Python",
+		description: pythonToolDescription,
+		parameters: paramsSchema,
+		defaultInactive: true,
+		concurrency: "exclusive",
+		async execute(
+			_toolCallId: string,
+			params: Static<typeof paramsSchema>,
+			signal?: AbortSignal,
+		): Promise<AgentToolResult> {
+			const sessionId = input.getSessionId();
+			if (sessionId === null) {
+				return {
+					content: [{ type: "text", text: NO_SESSION_ERROR }],
+					isError: true,
+				};
+			}
+			armCleanupForSession(sessionId);
+			const ownerId = pythonKernelOwnerId(sessionId);
+			if (params.action === "clear") {
+				await disposeKernelSessionsByOwner(ownerId);
+				currentTranscript = null;
+				return {
+					content: [{ type: "text", text: "Python kernel cleared; the next execute starts a fresh kernel." }],
+				};
+			}
+			const code = params.code;
+			if (code === undefined) {
+				return {
+					content: [{ type: "text", text: 'Missing required "code" parameter for action "execute".' }],
+					isError: true,
+				};
+			}
+
+			seenOwnerIds.add(ownerId);
+			try {
+				const result = await executePython(code, {
+					cwd: input.cwd,
+					kernelMode: "session",
+					sessionId: ownerId,
+					kernelOwnerId: ownerId,
+					artifactsDir: sessionIpykernelsArtifactsDir(input.cwd, sessionId),
+					signal,
+					onKernelStart: kernelInstanceId => {
+						if (currentTranscript?.kernelInstanceId !== kernelInstanceId) {
+							currentTranscript = openPythonKernelTranscript({
+								cwd: input.cwd,
+								sessionId,
+								kernelInstanceId,
+							});
+						}
+					},
+				});
+				const appendFailure = await appendTranscript(sessionId, code, {
+					output: result.output,
+					exitCode: result.exitCode ?? null,
+					cancelled: result.cancelled,
+					truncated: result.truncated,
+				});
+				const output = result.output.length > 0 ? result.output : "(no output)";
+				return { content: [{ type: "text", text: appendFailureTrailer(output, appendFailure) }] };
+			} catch (error) {
+				const output = errorMessage(error);
+				const appendFailure = await appendTranscript(sessionId, code, {
+					output,
+					exitCode: null,
+					cancelled: isCancellationError(error, signal),
+					truncated: false,
+				});
+				return {
+					content: [{ type: "text", text: appendFailureTrailer(output, appendFailure) }],
+					isError: true,
+				};
+			}
+		},
+	};
+	const agentTool = {
+		async execute(
+			toolCallId: string,
+			params: Static<typeof paramsSchema>,
+			signal?: AbortSignal,
+		): Promise<AgentToolResult> {
+			return definition.execute(toolCallId, params, signal, undefined, undefined as never);
+		},
+	} as AgentTool;
+	applyToolProxy(definition, agentTool);
+	return agentTool;
+}

package/src/tools/read.ts

@@ -1429,18 +1429,28 @@ interface ResolvedSqliteReadPath {
  * Directories return a formatted listing with modification times.
  */
 /**
- * A client-authority denial is a decision, not a transport failure: falling back to
- * disk would bypass the permission the client just refused. Availability failures
- * still fall back so an unreachable bridge cannot break local reads.
+ * Only an explicit bridge transport-unavailable marker authorizes falling back to
+ * the agent host's disk. Raw OS errno values, including EACCES/EPERM, are
+ * ambiguous at this boundary: treating them as transport failures can bypass a
+ * remote client's access decision by reading the path locally.
  */
-function isClientAuthorityDenial(error: unknown): boolean {
-	const code =
+function isExplicitTransportUnavailable(error: unknown): boolean {
+	const directCode =
 		typeof error === "object" && error !== null && "code" in error ? (error as { code?: unknown }).code : undefined;
-	// ACP clients surface refusals as an application error; -32001 is the reserved
-	// client-authority denial code and -32603 covers hosts without a dedicated code.
-	if (code === "permission_denied" || code === "forbidden" || code === -32001 || code === -32603) return true;
-	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
-	return /permission denied|not permitted|access denied|forbidden/i.test(message);
+	const namedCode = error instanceof Error ? error.name : undefined;
+	const nestedCode =
+		typeof error === "object" &&
+		error !== null &&
+		"data" in error &&
+		typeof (error as { data?: unknown }).data === "object"
+			? ((error as { data?: { code?: unknown } }).data?.code ?? undefined)
+			: undefined;
+	const code = directCode ?? nestedCode ?? namedCode;
+	return code === "transport_unavailable" || code === "bridge_unavailable";
+}
+
+function isClientAuthorityDenial(error: unknown): boolean {
+	return !isExplicitTransportUnavailable(error);
 }
 
 export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
@@ -2395,6 +2405,53 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		if (!bridge?.capabilities.readTextFile || !bridge.readTextFile) return undefined;
 		return bridge.readTextFile({ path: absolutePath, ...options });
 	}
+	async #readMissingPathThroughBridge(
+		absolutePath: string,
+		parsed: ParsedSelector,
+		_localReadPath: string,
+		truncation: TruncationDirection | undefined,
+		signal: AbortSignal | undefined,
+	): Promise<AgentToolResult<ReadToolDetails> | undefined> {
+		const bridgePromise = this.#routeReadThroughBridge(absolutePath);
+		if (bridgePromise === undefined) return undefined;
+		throwIfAborted(signal);
+		try {
+			const bridgeText = await bridgePromise;
+			if (parsed.kind === "conflicts") return undefined;
+			const bareEligible = parsed.kind === "none";
+			const route = isMultiRange(parsed)
+				? "local-multi-range"
+				: bareEligible
+					? "local-bare-stream"
+					: isRawSelector(parsed)
+						? "local-raw"
+						: "local-range";
+			const direction = resolveEffectiveDirection(truncation, route, this.session.settings);
+			if (isMultiRange(parsed) && parsed.kind === "lines") {
+				return this.#buildInMemoryMultiRangeResult(bridgeText, parsed.ranges, {
+					details: { resolvedPath: absolutePath },
+					sourcePath: absolutePath,
+					entityLabel: "file",
+					raw: isRawSelector(parsed),
+					truncationDirection: direction,
+					cacheLinesFor: absolutePath,
+				});
+			}
+			const { offset, limit } = selToOffsetLimit(parsed);
+			return this.#buildInMemoryTextResult(bridgeText, offset, limit, {
+				details: { resolvedPath: absolutePath },
+				sourcePath: absolutePath,
+				entityLabel: "file",
+				raw: isRawSelector(parsed),
+				cacheLinesFor: absolutePath,
+				truncationDirection: direction,
+			});
+		} catch (error) {
+			if (isClientAuthorityDenial(error)) throw error;
+			logger.warn("ACP fs readTextFile failed for a path missing on disk", { path: absolutePath, error });
+			return undefined;
+		}
+	}
 
 	async #trySummarize(absolutePath: string, fileSize: number, signal?: AbortSignal): Promise<SummaryResult | null> {
 		if (fileSize > MAX_SUMMARY_BYTES) return null;
@@ -2402,10 +2459,17 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		try {
 			throwIfAborted(signal);
 			const bridgePromise = this.#routeReadThroughBridge(absolutePath);
-			const code =
-				bridgePromise !== undefined
-					? await bridgePromise.catch(() => Bun.file(absolutePath).text())
-					: await Bun.file(absolutePath).text();
+			let code: string;
+			if (bridgePromise !== undefined) {
+				try {
+					code = await bridgePromise;
+				} catch (error) {
+					if (isClientAuthorityDenial(error)) throw error;
+					code = await Bun.file(absolutePath).text();
+				}
+			} else {
+				code = await Bun.file(absolutePath).text();
+			}
 			throwIfAborted(signal);
 			if (countTextLines(code) > MAX_SUMMARY_LINES) return null;
 
@@ -2416,7 +2480,8 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				minBodyLines: this.session.settings.get("read.summarize.minBodyLines"),
 				minCommentLines: this.session.settings.get("read.summarize.minCommentLines"),
 			});
-		} catch {
+		} catch (error) {
+			if (isClientAuthorityDenial(error)) throw error;
 			return null;
 		}
 	}
@@ -2663,6 +2728,14 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			isDirectory = stat.isDirectory();
 		} catch (error) {
 			if (isNotFoundError(error)) {
+				const bridged = await this.#readMissingPathThroughBridge(
+					absolutePath,
+					parsed,
+					localReadPath,
+					params.truncation,
+					signal,
+				);
+				if (bridged) return bridged;
 				// Attempt unique suffix resolution before falling back to fuzzy suggestions
 				if (!isRemoteMountPath(absolutePath)) {
 					const suffixMatch = await findUniqueSuffixMatch(localReadPath, this.session.cwd, signal);

package/src/tools/renderers.ts

@@ -23,6 +23,7 @@ import { evalToolRenderer } from "./eval";
 import { findToolRenderer } from "./find";
 import { githubToolRenderer } from "./gh-renderer";
 import { jobToolRenderer } from "./job";
+import { moveSessionToolRenderer } from "./move-session";
 import { readToolRenderer } from "./read";
 import { recipeToolRenderer } from "./recipe/render";
 import { resolveToolRenderer } from "./resolve";
@@ -72,6 +73,7 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	todo_write: todoWriteToolRenderer as ToolRenderer,
 	github: githubToolRenderer as ToolRenderer,
 	goal: goalToolRenderer as ToolRenderer,
+	move_session: moveSessionToolRenderer as ToolRenderer,
 	web_search: webSearchToolRenderer as ToolRenderer,
 	write: writeToolRenderer as ToolRenderer,
 };