@oh-my-pi/pi-coding-agent 17.1.5 → 17.1.7

package/src/session/session-advisors.ts

@@ -254,6 +254,7 @@ export class SessionAdvisors {
 	#advisorConfigs: AdvisorConfig[] | undefined;
 	#advisorStatuses = new Map<string, { name: string; status: AdvisorRuntimeStatus }>();
 	#advisorProviderSessionIds = new Map<string, string>();
+	#advisorCosts = new Map<string, number>();
 	#advisorRecorderClosed: Promise<void> = Promise.resolve();
 	#advisorAutoResumeSuppressed = false;
 	#preserveAdvisorAdvice = false;
@@ -326,8 +327,13 @@ export class SessionAdvisors {
 	}
 
 	/** Re-primes advisor transcript views across a conversation boundary. */
-	resetSessionState(): void {
-		this.#resetAdvisorSessionState();
+	resetSessionState(options: { preserveCost?: boolean } = {}): void {
+		this.#resetAdvisorSessionState(options.preserveCost === true);
+	}
+
+	/** Drop the recorded spend once a conversation boundary has committed. */
+	clearCost(): void {
+		this.#advisorCosts.clear();
 	}
 
 	/**
@@ -451,7 +457,8 @@ export class SessionAdvisors {
 	 * agent steer/follow-up queues, and preserved cards deferred to the next turn —
 	 * so none of them inject into the new conversation.
 	 */
-	#resetAdvisorSessionState(): void {
+	#resetAdvisorSessionState(preserveCost: boolean): void {
+		if (!preserveCost) this.#advisorCosts.clear();
 		// Mute the recorder across the re-prime: AdvisorRuntime.reset() aborts the advisor
 		// loop, and that abort can emit an `aborted` message_end we must not attribute to
 		// either session's transcript. Detach, reset, then re-attach the live agent's feed.
@@ -959,8 +966,7 @@ export class SessionAdvisors {
 			.catch(err => logger.debug("advisor delivery failed", { err: String(err) }));
 	}
 
-	/** Re-prime every advisor's transcript view (compaction/shake/rewind) without the
-	 *  session-level latch reset {@link #resetAdvisorSessionState} performs. */
+	/** Re-prime every advisor's transcript view after an in-conversation history rewrite. */
 	#resetAllAdvisorRuntimes(): void {
 		for (const a of this.#advisors) a.runtime.reset();
 	}
@@ -985,12 +991,18 @@ export class SessionAdvisors {
 		this.#advisorYieldQueueUnsubscribe = undefined;
 	}
 
+	#recordAdvisorCost(advisor: ActiveAdvisor, message: AssistantMessage): void {
+		this.#advisorCosts.set(advisor.slug, (this.#advisorCosts.get(advisor.slug) ?? 0) + message.usage.cost.total);
+	}
+
 	/** Subscribe the advisor agent's finalized messages into the transcript recorder.
 	 *  Idempotent-by-replacement: callers detach the prior feed first. Kept separate
 	 *  so the re-prime path can mute the feed across an abort-driven reset. */
 	#attachAdvisorRecorderFeed(advisor: ActiveAdvisor): void {
 		advisor.agentUnsubscribe = advisor.agent.subscribe(event => {
-			if (event.type === "message_end") advisor.recorder.record(event.message);
+			if (event.type !== "message_end") return;
+			if (event.message.role === "assistant") this.#recordAdvisorCost(advisor, event.message);
+			advisor.recorder.record(event.message);
 		});
 	}
 
@@ -1507,6 +1519,13 @@ export class SessionAdvisors {
 		}));
 		return { configured: this.#advisorEnabled, advisors };
 	}
+
+	/** Return cumulative advisor cost recorded for the current session. */
+	getAdvisorCost(): number {
+		let cost = 0;
+		for (const advisorCost of this.#advisorCosts.values()) cost += advisorCost;
+		return cost;
+	}
 	/**
 	 * Return structured advisor stats for the status command and TUI panel.
 	 */
@@ -1530,12 +1549,13 @@ export class SessionAdvisors {
 					contextWindow: 0,
 					contextTokens: 0,
 					tokens: { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-					cost: 0,
+					cost: this.#advisorCosts.get(slug) ?? 0,
 					messages: { user: 0, assistant: 0, total: 0 },
 				});
 			}
 		}
 		const active = liveAdvisors.length > 0;
+		const cost = this.getAdvisorCost();
 		if (liveAdvisors.length === 0) {
 			return {
 				configured,
@@ -1543,14 +1563,13 @@ export class SessionAdvisors {
 				contextWindow: 0,
 				contextTokens: 0,
 				tokens: { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-				cost: 0,
+				cost,
 				messages: { user: 0, assistant: 0, total: 0 },
 				advisors: roster,
 			};
 		}
 		const tokens = { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
 		const messages = { user: 0, assistant: 0, total: 0 };
-		let cost = 0;
 		let contextTokens = 0;
 		for (const a of liveAdvisors) {
 			tokens.input += a.tokens.input;
@@ -1562,7 +1581,6 @@ export class SessionAdvisors {
 			messages.user += a.messages.user;
 			messages.assistant += a.messages.assistant;
 			messages.total += a.messages.total;
-			cost += a.cost;
 			contextTokens += a.contextTokens;
 		}
 		// Single-advisor displays read the top-level model/window directly; surface the
@@ -1591,7 +1609,6 @@ export class SessionAdvisors {
 		let cacheRead = 0;
 		let cacheWrite = 0;
 		let totalTokens = 0;
-		let cost = 0;
 		let user = 0;
 		let assistant = 0;
 		for (const message of messages) {
@@ -1605,7 +1622,6 @@ export class SessionAdvisors {
 				cacheRead += assistantMsg.usage.cacheRead;
 				cacheWrite += assistantMsg.usage.cacheWrite;
 				totalTokens += assistantMsg.usage.totalTokens;
-				cost += assistantMsg.usage.cost.total;
 			}
 		}
 		return {
@@ -1619,7 +1635,7 @@ export class SessionAdvisors {
 			contextWindow: model.contextWindow ?? 0,
 			contextTokens,
 			tokens: { input, output, reasoning, cacheRead, cacheWrite, total: totalTokens },
-			cost,
+			cost: this.#advisorCosts.get(advisor.slug) ?? 0,
 			messages: { user, assistant, total: messages.length },
 			sessionId: advisor.agent.sessionId,
 		};
@@ -1649,7 +1665,7 @@ export class SessionAdvisors {
 			const spendParts = [`${s.tokens.input.toLocaleString()} input`, `${s.tokens.output.toLocaleString()} output`];
 			if (s.tokens.cacheRead > 0) spendParts.push(`${s.tokens.cacheRead.toLocaleString()} cache read`);
 			if (s.tokens.cacheWrite > 0) spendParts.push(`${s.tokens.cacheWrite.toLocaleString()} cache write`);
-			const spendLine = `Spend: ${spendParts.join(", ")}, $${s.cost.toFixed(4)}`;
+			const spendLine = `Spend: ${spendParts.join(", ")}, $${stats.cost.toFixed(4)}`;
 			if (!s.model || s.status !== "running") return `Advisor "${s.name}" is ${s.status.replace("_", " ")}.`;
 			return `Advisor is enabled (${s.model.provider}/${s.model.id}). ${contextLine}. ${spendLine}.`;
 		}

package/src/session/session-listing.ts

@@ -2,8 +2,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@oh-my-pi/pi-ai";
 import { getAgentDir as getDefaultAgentDir, logger, parseJsonlLenient, toError } from "@oh-my-pi/pi-utils";
+import { LRUCache } from "lru-cache/raw";
 import { computeDefaultSessionDir } from "./session-paths";
-import { FileSessionStorage, type SessionStorage } from "./session-storage";
+import { FileSessionStorage, type SessionStorage, type SessionStorageStat } from "./session-storage";
 
 /**
  * Coarse lifecycle status of a session, derived from its last persisted message.
@@ -65,6 +66,44 @@ const SESSION_LIST_SUFFIX_BYTES = 32_768;
 const SESSION_LIST_PARALLEL_THRESHOLD = 64;
 const SESSION_LIST_MAX_WORKERS = 16;
 
+/**
+ * Memoizes {@link scanSessionFile} results keyed by stat identity so listing
+ * refreshes (resume picker opens, startup recent-sessions, cross-project
+ * scans) skip the open+read+parse for unchanged files. The `statSync` still
+ * runs on every scan — it IS the invalidation check: a hit requires both
+ * `mtimeMs` and `size` to match. This covers the two mutation paths:
+ * - streaming appends grow `size` (and bump `mtimeMs`);
+ * - `updateSessionTitle` rewrites the fixed-width title slot in place via
+ *   `writeSync`, which leaves `size` unchanged but updates `mtimeMs`.
+ * Negative results (unparseable files) are cached too, as `undefined` info.
+ * Entries are small header objects, so a generous cap is cheap.
+ */
+const SESSION_SCAN_CACHE_MAX = 4096;
+
+interface SessionScanCacheEntry {
+	mtimeMs: number;
+	size: number;
+	info: SessionInfo | undefined;
+}
+
+type SessionScanCache = LRUCache<string, SessionScanCacheEntry>;
+
+/** All {@link FileSessionStorage} instances view the same real filesystem, so they share one cache. */
+const fileSessionScanCache: SessionScanCache = new LRUCache({ max: SESSION_SCAN_CACHE_MAX });
+/** Other storages (in-memory test doubles) each carry their own cache to avoid cross-instance path collisions. */
+const kScanCache = Symbol("session-listing.scanCache");
+
+interface StorageWithScanCache extends SessionStorage {
+	[kScanCache]?: SessionScanCache;
+}
+
+function getSessionScanCache(storage: SessionStorage): SessionScanCache {
+	if (storage instanceof FileSessionStorage) return fileSessionScanCache;
+	const holder = storage as StorageWithScanCache;
+	if (!holder[kScanCache]) holder[kScanCache] = new LRUCache({ max: SESSION_SCAN_CACHE_MAX });
+	return holder[kScanCache];
+}
+
 function sanitizeSessionName(value: string | undefined): string | undefined {
 	if (!value) return undefined;
 	const firstLine = value.split(/\r?\n/)[0] ?? "";
@@ -355,8 +394,22 @@ async function scanSessionFile(
 	storage: SessionStorage,
 	withStatus: boolean,
 ): Promise<SessionInfo | undefined> {
+	let stat: SessionStorageStat;
+	try {
+		stat = storage.statSync(file);
+	} catch {
+		// Missing/unstatable file: no stat identity to cache under.
+		return undefined;
+	}
+	const cache = getSessionScanCache(storage);
+	// `withStatus` changes what a scan reads (tail window) and returns, so the
+	// two variants are cached under distinct keys.
+	const cacheKey = withStatus ? `s\0${file}` : `h\0${file}`;
+	const cached = cache.get(cacheKey);
+	if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+		return cached.info ? { ...cached.info } : undefined;
+	}
 	try {
-		const stat = storage.statSync(file);
 		const [content, suffix] = await storage.readTextSlices(
 			file,
 			SESSION_LIST_PREFIX_BYTES,
@@ -365,7 +418,12 @@ async function scanSessionFile(
 		const { size, mtime } = stat;
 		const entries = parseJsonlLenient<Record<string, unknown>>(content);
 		const header = parseSessionListHeader(content, entries);
-		if (!header) return undefined;
+		if (!header) {
+			// Cache the negative result too: an unparseable file stays unparseable
+			// until its stat identity changes.
+			cache.set(cacheKey, { mtimeMs: stat.mtimeMs, size: stat.size, info: undefined });
+			return undefined;
+		}
 
 		let parsedMessageCount = 0;
 		let firstMessage = "";
@@ -398,7 +456,7 @@ async function scanSessionFile(
 
 		firstMessage ||= extractFirstDisplayMessageFromPrefix(content) ?? "";
 		const messageCount = Math.max(parsedMessageCount, countMessageMarkers(content));
-		return {
+		const info: SessionInfo = {
 			path: file,
 			id: header.id,
 			cwd: header.cwd ?? "",
@@ -412,6 +470,10 @@ async function scanSessionFile(
 			allMessagesText: allMessages.length > 0 ? allMessages.join(" ") : firstMessage,
 			status: withStatus ? deriveSessionStatus(suffix) : undefined,
 		};
+		// The cache keeps its own shallow copy; hits also hand out copies, so
+		// callers can never mutate the shared cached object.
+		cache.set(cacheKey, { mtimeMs: stat.mtimeMs, size: stat.size, info: { ...info } });
+		return info;
 	} catch {
 		return undefined;
 	}

package/src/session/session-tools.ts

@@ -11,6 +11,7 @@ import type { ExtensionRunner } from "../extensibility/extensions";
 import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import { loadSkills, type Skill, type SkillWarning, setActiveSkills } from "../extensibility/skills";
 import { type LocalProtocolOptions, XD_URL_PREFIX } from "../internal-urls";
+import { deduplicateMCPToolsByName } from "../mcp/tool-bridge";
 import { resolveMemoryBackend } from "../memory-backend/resolve";
 import { MEMORY_BACKEND_TOOL_NAMES } from "../memory-backend/tool-names";
 import type { MemoryBackendStartOptions } from "../memory-backend/types";
@@ -20,8 +21,9 @@ import { isMCPToolName, normalizeToolNames } from "../tools/builtin-names";
 import { computerExposureMode } from "../tools/computer/exposure";
 import { wrapToolWithMetaNotice } from "../tools/output-meta";
 import { ToolAbortError, ToolError } from "../tools/tool-errors";
-import { isMountableUnderXdev, type XdevRegistry } from "../tools/xdev";
+import { isMountableUnderXdev, listXdevTools, type XdevState, xdevDocsFor, xdevEntries } from "../tools/xdev";
 import { type EditMode, resolveEditMode } from "../utils/edit-mode";
+import { type InspectImageMode, isInspectImageToolActive } from "../utils/inspect-image-mode";
 import { formatLocalCalendarDate } from "../utils/local-date";
 import {
 	extractPermissionLocations,
@@ -55,6 +57,9 @@ export interface SessionToolsHost {
 	emitNotice(level: "info" | "warning" | "error", message: string, source?: string): void;
 	notifyCommandMetadataChanged(): void;
 	localProtocolOptions(): LocalProtocolOptions;
+	/** Session-scoped `/vision` override; undefined means "follow the persisted setting". */
+	getInspectImageModeOverride(): InspectImageMode | undefined;
+	setInspectImageModeOverride(mode: InspectImageMode | undefined): void;
 }
 
 interface SessionToolsOptions {
@@ -62,14 +67,15 @@ interface SessionToolsOptions {
 	toolRegistry?: Map<string, AgentTool>;
 	createVibeTools?: () => AgentTool[];
 	createComputerTool?: () => Promise<AgentTool | null>;
+	/** Creates the built-in `inspect_image` tool for session-scoped runtime enablement (see {@link SessionTools.setInspectImageMode}). */
+	createInspectImageTool?: () => Promise<AgentTool | null>;
 	builtInToolNames?: Iterable<string>;
 	presentationPinnedToolNames?: ReadonlySet<string>;
 	ensureWriteRegistered?: () => Promise<boolean>;
 	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{ systemPrompt: string[] }>;
 	getLocalCalendarDate?: () => string;
 	getMcpServerInstructions?: () => Map<string, string> | undefined;
-	xdevRegistry?: XdevRegistry;
-	initialMountedXdevToolNames?: string[];
+	xdev?: XdevState;
 	setActiveToolNames?: (names: Iterable<string>) => void;
 	baseSystemPrompt: string[];
 	skills?: Skill[];
@@ -160,11 +166,11 @@ export class SessionTools {
 	#toolRegistry: Map<string, AgentTool>;
 	#createVibeTools: (() => AgentTool[]) | undefined;
 	#createComputerTool: SessionToolsOptions["createComputerTool"];
+	#createInspectImageTool: SessionToolsOptions["createInspectImageTool"];
 	#installedVibeToolNames = new Set<string>();
 	#builtInToolNames: Set<string>;
 	#rpcHostToolNames = new Set<string>();
-	#xdevRegistry: XdevRegistry | undefined;
-	#mountedXdevToolNames: Set<string>;
+	#xdev: XdevState | undefined;
 	#pendingXdevMountDelta: { added: Set<string>; removed: Set<string> } | undefined;
 	#presentationPinnedToolNames: ReadonlySet<string> | undefined;
 	#runtimeSelectedToolNames: ReadonlySet<string> | undefined;
@@ -189,14 +195,18 @@ export class SessionTools {
 		this.#toolRegistry = options.toolRegistry ?? new Map();
 		this.#createVibeTools = options.createVibeTools;
 		this.#createComputerTool = options.createComputerTool;
+		this.#createInspectImageTool = options.createInspectImageTool;
 		this.#builtInToolNames = new Set(options.builtInToolNames ?? []);
 		this.#presentationPinnedToolNames = options.presentationPinnedToolNames;
 		this.#ensureWriteRegistered = options.ensureWriteRegistered;
 		this.#rebuildSystemPrompt = options.rebuildSystemPrompt;
 		this.#getLocalCalendarDate = options.getLocalCalendarDate ?? formatLocalCalendarDate;
 		this.#getMcpServerInstructions = options.getMcpServerInstructions;
-		this.#xdevRegistry = options.xdevRegistry;
-		this.#mountedXdevToolNames = new Set(options.initialMountedXdevToolNames ?? []);
+		this.#xdev = options.xdev;
+		if (this.#xdev && this.#xdev.tools !== this.#toolRegistry) {
+			throw new Error("xd:// state must reference the canonical session tool map");
+		}
+		if (this.#xdev) this.#xdev.decorateExecution = tool => this.#wrapToolForAcpPermission(tool);
 		this.#setActiveToolNames = options.setActiveToolNames;
 		this.#baseSystemPrompt = options.baseSystemPrompt;
 		this.#skills = options.skills ?? [];
@@ -241,7 +251,7 @@ export class SessionTools {
 		this.#acpPermissionDecisions.clear();
 	}
 
-	/** Re-wraps active and mounted tools after the ACP client changes. */
+	/** Drops cached ACP decisions and re-wraps active tools after the client changes. */
 	refreshAcpPermissionGates(): void {
 		this.#acpPermissionDecisions.clear();
 		const activeTools = this.getActiveToolNames()
@@ -249,11 +259,6 @@ export class SessionTools {
 			.filter((tool): tool is AgentTool => tool !== undefined)
 			.map(tool => this.#wrapToolForAcpPermission(tool));
 		this.#host.agent.setTools(activeTools);
-		const mountedTools = [...this.#mountedXdevToolNames]
-			.map(name => this.#toolRegistry.get(name))
-			.filter((tool): tool is AgentTool => tool !== undefined)
-			.map(tool => this.#wrapToolForAcpPermission(tool));
-		this.#xdevRegistry?.reconcile(mountedTools);
 	}
 
 	#getActiveNonMCPToolNames(): string[] {
@@ -267,13 +272,14 @@ export class SessionTools {
 
 	/** Enabled top-level and discoverable tool names. */
 	getEnabledToolNames(): string[] {
-		if (this.#mountedXdevToolNames.size === 0) return this.getActiveToolNames();
-		return [...this.getActiveToolNames(), ...this.#mountedXdevToolNames];
+		const mountedNames = this.#xdev?.mountedNames;
+		if (!mountedNames || mountedNames.size === 0) return this.getActiveToolNames();
+		return [...this.getActiveToolNames(), ...mountedNames];
 	}
 
-	/** Names of dynamic tools mounted under `xd://`. */
+	/** Names currently presented as `xd://` devices. */
 	getMountedXdevToolNames(): string[] {
-		return [...this.#mountedXdevToolNames];
+		return [...(this.#xdev?.mountedNames ?? [])];
 	}
 
 	/** Whether the edit tool is registered. */
@@ -402,6 +408,10 @@ export class SessionTools {
 		} else if (computerExpected) {
 			this.#logComputerState("Computer tool retained after model change", true);
 		}
+
+		// inspect_image auto mode keys off model image capability, so a model
+		// switch can flip the tool either way.
+		await this.reconcileInspectImageAfterModelChange();
 	}
 
 	/** Enabled MCP tools in their current presentation partition. */
@@ -542,10 +552,7 @@ export class SessionTools {
 			this.#presentationPinnedToolNames?.has(name) === true || this.#runtimeSelectedToolNames?.has(name) === true;
 		const mountCandidates = selectedTools.filter(
 			({ name, tool }) =>
-				this.#xdevRegistry !== undefined &&
-				xdevReadAvailable &&
-				!isPresentationPinned(name) &&
-				isMountableUnderXdev(tool),
+				this.#xdev !== undefined && xdevReadAvailable && !isPresentationPinned(name) && isMountableUnderXdev(tool),
 		);
 
 		let builtInWriteAvailable = this.#builtInToolNames.has("write");
@@ -556,19 +563,15 @@ export class SessionTools {
 		const mountNames = builtInWriteAvailable ? new Set(mountCandidates.map(({ name }) => name)) : new Set<string>();
 		const tools: AgentTool[] = [];
 		const validToolNames: string[] = [];
-		const mountedTools: AgentTool[] = [];
 		for (const { name, tool } of selectedTools) {
-			if (mountNames.has(name)) {
-				mountedTools.push(this.#wrapToolForAcpPermission(tool));
-			} else {
-				tools.push(this.#wrapToolForAcpPermission(tool));
-				validToolNames.push(name);
-			}
+			if (mountNames.has(name)) continue;
+			tools.push(this.#wrapToolForAcpPermission(tool));
+			validToolNames.push(name);
 		}
 
 		const pinnedWrite = isPresentationPinned("write");
 		const activeDeferrableTool = tools.some(tool => tool.deferrable === true);
-		const transportNeeded = mountedTools.length > 0 || activeDeferrableTool || this.#host.planModeEnabled();
+		const transportNeeded = mountNames.size > 0 || activeDeferrableTool || this.#host.planModeEnabled();
 		if (transportNeeded && !builtInWriteAvailable) {
 			builtInWriteAvailable = (await this.#ensureWriteRegistered?.()) === true;
 			if (builtInWriteAvailable) this.#builtInToolNames.add("write");
@@ -589,14 +592,9 @@ export class SessionTools {
 			if (writeToolIndex >= 0) tools.splice(writeToolIndex, 1);
 		}
 
-		const previousMounted = this.#mountedXdevToolNames;
-		const previousMountedTools = [...previousMounted].flatMap(name => {
-			const tool = this.#xdevRegistry?.get(name);
-			return tool ? [tool] : [];
-		});
+		const previousMounted = new Set(this.#xdev?.mountedNames ?? []);
 		const previousActiveToolNames = this.getActiveToolNames();
-		this.#mountedXdevToolNames = new Set(mountedTools.map(tool => tool.name));
-		this.#xdevRegistry?.reconcile(mountedTools);
+		this.#setMountedNames(mountNames);
 		this.#setActiveToolNames?.(validToolNames);
 
 		let rebuiltSystemPrompt: string[] | undefined;
@@ -611,15 +609,13 @@ export class SessionTools {
 				}
 			}
 		} catch (error) {
-			this.#mountedXdevToolNames = previousMounted;
-			this.#xdevRegistry?.reconcile(previousMountedTools);
+			this.#setMountedNames(previousMounted);
 			this.#setActiveToolNames?.(previousActiveToolNames);
 			throw error;
 		}
 
 		if (this.#host.isDisposed()) {
-			this.#mountedXdevToolNames = previousMounted;
-			this.#xdevRegistry?.reconcile(previousMountedTools);
+			this.#setMountedNames(previousMounted);
 			this.#setActiveToolNames?.(previousActiveToolNames);
 			return;
 		}
@@ -636,6 +632,13 @@ export class SessionTools {
 		}
 	}
 
+	#setMountedNames(names: Iterable<string>): void {
+		const mountedNames = this.#xdev?.mountedNames;
+		if (!mountedNames) return;
+		mountedNames.clear();
+		for (const name of names) mountedNames.add(name);
+	}
+
 	/**
 	 * Record a mid-session `xd://` mount delta for the model. Non-MCP mount
 	 * churn remains notice-only, leaving the system prompt and provider cache
@@ -648,9 +651,8 @@ export class SessionTools {
 	 * Full docs join the system prompt opportunistically on a rebuild.
 	 */
 	#notifyXdevMountDelta(previousMounted: ReadonlySet<string>): void {
-		const registry = this.#xdevRegistry;
-		if (!registry) return;
-		const current = this.#mountedXdevToolNames;
+		const current = this.#xdev?.mountedNames;
+		if (!current) return;
 		const addedNames = [...current].filter(name => !previousMounted.has(name));
 		const removedNames = [...previousMounted].filter(name => !current.has(name));
 		if (addedNames.length === 0 && removedNames.length === 0) return;
@@ -677,14 +679,17 @@ export class SessionTools {
 		const pending = this.#pendingXdevMountDelta;
 		if (!pending) return undefined;
 		this.#pendingXdevMountDelta = undefined;
-		const summaries = new Map(this.#xdevRegistry?.entries().map(entry => [entry.name, entry.summary]) ?? []);
+		const summaries = new Map(this.#xdev ? xdevEntries(this.#xdev).map(entry => [entry.name, entry.summary]) : []);
 		const added = [...pending.added].map(name => ({ name, summary: summaries.get(name) ?? "" }));
 		const removed = [...pending.removed].map(name => ({ name }));
-		const docs = this.#xdevRegistry?.docsFor(
-			pending.added,
-			this.#host.settings.get("tools.xdevDocs"),
-			this.#host.settings.get("tools.xdevInlineDevices"),
-		);
+		const docs = this.#xdev
+			? xdevDocsFor(
+					this.#xdev,
+					pending.added,
+					this.#host.settings.get("tools.xdevDocs"),
+					this.#host.settings.get("tools.xdevInlineDevices"),
+				)
+			: "";
 		return {
 			role: "custom",
 			customType: XDEV_MOUNT_NOTICE_MESSAGE_TYPE,
@@ -726,7 +731,7 @@ export class SessionTools {
 		// selection change should not demote `write` unless it is already active.
 		await this.#applyToolPresentation(
 			normalized,
-			this.#mountedXdevToolNames,
+			this.#xdev?.mountedNames ?? new Set(),
 			this.getActiveToolNames().includes("write"),
 		);
 	}
@@ -735,7 +740,7 @@ export class SessionTools {
 	 * Restore an enabled tool set with its exact top-level versus `xd://` partition.
 	 *
 	 * Both inputs are required because {@link setActiveToolsByName} only receives the
-	 * enabled name list and classifies mounts from the current `#mountedXdevToolNames`.
+	 * enabled name list and classifies mounts from the current presentation set.
 	 * Rollback/restore callers must pass the snapshotted mounted subset so names that
 	 * were top-level stay pinned (`#runtimeSelectedToolNames`) and names that were under
 	 * `xd://` remain mount-eligible, even when the live mount set has drifted.
@@ -848,6 +853,108 @@ export class SessionTools {
 		return true;
 	}
 
+	/** Current effective inspect_image state for `/vision status`. */
+	inspectImageState(): { mode: InspectImageMode; active: boolean; model: string | undefined } {
+		const model = this.#host.model();
+		return {
+			mode: this.#host.getInspectImageModeOverride() ?? this.#host.settings.get("inspect_image.mode"),
+			active: this.getEnabledToolNames().includes("inspect_image"),
+			model: model ? formatModelString(model) : undefined,
+		};
+	}
+
+	/**
+	 * Brings the active tool set in line with the effective inspect_image state
+	 * (mode setting, `/vision` override, active-model image capability).
+	 * Mirrors {@link setComputerToolEnabled}: enabling builds the tool through
+	 * the config factory on first use and reuses the registry entry afterwards.
+	 * Idempotent — safe to call from every model/settings change path.
+	 *
+	 * @returns false when the tool should be active but this session cannot
+	 *   build it (e.g. restricted child sessions have no factory).
+	 */
+	async reconcileInspectImageTool(): Promise<boolean> {
+		const expected = isInspectImageToolActive({
+			settings: this.#host.settings,
+			getActiveModel: () => this.#host.model(),
+			getInspectImageModeOverride: () => this.#host.getInspectImageModeOverride(),
+		});
+		// Keep the read tool's advertised description in sync BEFORE any prompt
+		// rebuild below, passing the post-change availability so the prompt never
+		// lags a flip in either direction. Per-read lazy sync is the backstop.
+		const syncReadDescription = (available: boolean): void => {
+			const readTool = this.#toolRegistry.get("read") as
+				| { syncInspectImageState?: (available?: boolean) => boolean }
+				| undefined;
+			readTool?.syncInspectImageState?.(available);
+		};
+		const active = this.getEnabledToolNames();
+		const isActive = active.includes("inspect_image");
+		if (expected === isActive) {
+			syncReadDescription(isActive);
+			return true;
+		}
+		if (!expected) {
+			syncReadDescription(false);
+			await this.applyActiveToolsByName(active.filter(name => name !== "inspect_image"));
+			return true;
+		}
+		if (!this.#toolRegistry.has("inspect_image")) {
+			const tool = await this.#createInspectImageTool?.();
+			if (tool?.name !== "inspect_image") {
+				logger.warn("inspect_image tool could not be created", {
+					model: this.#host.model()?.id,
+				});
+				syncReadDescription(false);
+				return false;
+			}
+			const wrapped = this.#wrapRuntimeTool(tool);
+			this.#toolRegistry.set(wrapped.name, wrapped);
+			this.#builtInToolNames.add(wrapped.name);
+		}
+		syncReadDescription(true);
+		await this.applyActiveToolsByName([...active, "inspect_image"]);
+		return true;
+	}
+
+	/**
+	 * Reconciles inspect_image after a model change and surfaces a notice when
+	 * the visible tool set actually flipped. Called from every model-change
+	 * path — including retry-fallback switches that bypass
+	 * {@link syncAfterModelChange}.
+	 */
+	async reconcileInspectImageAfterModelChange(): Promise<void> {
+		const before = this.getEnabledToolNames().includes("inspect_image");
+		const reconciled = await this.reconcileInspectImageTool();
+		const after = this.getEnabledToolNames().includes("inspect_image");
+		if (!reconciled || before === after) return;
+		const model = this.#host.model();
+		const modelName = model ? formatModelString(model) : "the current model";
+		this.#host.emitNotice(
+			"info",
+			after
+				? `inspect_image is now available: ${modelName} has no native image input.`
+				: `inspect_image is now hidden: ${modelName} supports image input natively. Override with /vision on.`,
+			"vision",
+		);
+	}
+
+	/**
+	 * Session-scoped `/vision` override. `auto` clears the override so the
+	 * persisted `inspect_image.mode` setting (itself possibly `auto`) decides;
+	 * `on`/`off` force the tool for this session only. Takes effect before the
+	 * next model call.
+	 *
+	 * @returns false when `on` was requested but the tool cannot be built here.
+	 */
+	async setInspectImageMode(mode: InspectImageMode): Promise<boolean> {
+		this.#host.setInspectImageModeOverride(mode === "auto" ? undefined : mode);
+		const applied = await this.reconcileInspectImageTool();
+		const { active, model } = this.inspectImageState();
+		logger.debug("inspect_image mode changed", { mode, active, model });
+		return applied;
+	}
+
 	/** Rebuilds the stable base prompt for the current tools and model. */
 	async refreshBaseSystemPrompt(): Promise<void> {
 		if (this.#host.isDisposed() || !this.#rebuildSystemPrompt) return;
@@ -963,7 +1070,7 @@ export class SessionTools {
 			`${tool.name}=${tool.label ?? ""}|${tool.description ?? ""}|${tool.customWireName ?? ""}`;
 		const descriptionSegment = tools.map(describeTool).join("\u0002");
 		const mountedMCPProjection = projectMountedMCPXdevGuidance(
-			collectMountedMCPToolRoutes(this.#xdevRegistry?.list() ?? []),
+			collectMountedMCPToolRoutes(this.#xdev ? listXdevTools(this.#xdev) : []),
 		);
 		const mountedMCPRouteSegment =
 			JSON.stringify({
@@ -1040,7 +1147,8 @@ export class SessionTools {
 		});
 
 		const extensionRunner = this.#host.extensionRunner();
-		for (const customTool of mcpTools) {
+		const uniqueMcpTools = deduplicateMCPToolsByName(mcpTools);
+		for (const customTool of uniqueMcpTools) {
 			const wrapped = wrapToolWithMetaNotice(CustomToolAdapter.wrap(customTool, getCustomToolContext) as AgentTool);
 			const finalTool = (
 				extensionRunner ? new ExtensionToolWrapper(wrapped, extensionRunner) : wrapped
@@ -1050,7 +1158,7 @@ export class SessionTools {
 
 		// Every connected MCP tool is selected; centralized repartitioning owns
 		// presentation pins and write-transport activation/removal.
-		const nextActive = [...new Set([...this.#getActiveNonMCPToolNames(), ...mcpTools.map(tool => tool.name)])];
+		const nextActive = [...new Set([...this.#getActiveNonMCPToolNames(), ...uniqueMcpTools.map(tool => tool.name)])];
 		try {
 			await this.applyActiveToolsByName(nextActive);
 			if (this.#host.isDisposed()) restorePreviousMcpTools();