@oh-my-pi/pi-coding-agent 17.1.6 → 17.1.8

package/src/session/model-controls.ts

@@ -52,7 +52,7 @@ export interface ModelControlsHost {
 	promptGeneration(): number;
 	resolveActiveEditMode(): EditMode;
 	syncAfterModelChange(previousEditMode: EditMode): Promise<void>;
-	setModelWithProviderSessionReset(model: Model): void;
+	setModelWithProviderSessionReset(model: Model): Promise<void>;
 	clearActiveRetryFallback(): void;
 	clearInheritedProviderPromptCacheKey(): void;
 	magicKeywordEnabled(keyword: "orchestrate" | "ultrathink" | "workflow"): boolean;
@@ -220,7 +220,7 @@ export class ModelControls {
 
 		this.#host.modelRegistry.clearSuppressedSelector(formatModelStringWithRouting(targetModel));
 		this.#host.clearActiveRetryFallback();
-		this.#host.setModelWithProviderSessionReset(targetModel);
+		await this.#host.setModelWithProviderSessionReset(targetModel);
 		this.#host.sessionManager.appendModelChange(`${targetModel.provider}/${targetModel.id}`, role);
 		if (options?.persist) {
 			this.#host.settings.setModelRole(
@@ -265,7 +265,7 @@ export class ModelControls {
 
 		this.#host.modelRegistry.clearSuppressedSelector(formatModelStringWithRouting(targetModel));
 		this.#host.clearActiveRetryFallback();
-		this.#host.setModelWithProviderSessionReset(targetModel);
+		await this.#host.setModelWithProviderSessionReset(targetModel);
 		this.#host.sessionManager.appendModelChange(
 			`${targetModel.provider}/${targetModel.id}`,
 			options?.ephemeral ? EPHEMERAL_MODEL_CHANGE_ROLE : "temporary",
@@ -425,7 +425,7 @@ export class ModelControls {
 		// Apply model
 		this.#host.modelRegistry.clearSuppressedSelector(formatModelStringWithRouting(next.model));
 		this.#host.clearActiveRetryFallback();
-		this.#host.setModelWithProviderSessionReset(next.model);
+		await this.#host.setModelWithProviderSessionReset(next.model);
 		this.#host.sessionManager.appendModelChange(`${next.model.provider}/${next.model.id}`);
 		this.#host.settings.getStorage()?.recordModelUsage(`${next.model.provider}/${next.model.id}`);
 
@@ -456,7 +456,7 @@ export class ModelControls {
 
 		this.#host.modelRegistry.clearSuppressedSelector(formatModelStringWithRouting(nextModel));
 		this.#host.clearActiveRetryFallback();
-		this.#host.setModelWithProviderSessionReset(nextModel);
+		await this.#host.setModelWithProviderSessionReset(nextModel);
 		this.#host.sessionManager.appendModelChange(`${nextModel.provider}/${nextModel.id}`);
 		this.#host.settings.getStorage()?.recordModelUsage(`${nextModel.provider}/${nextModel.id}`);
 		// Re-apply the current thinking level (or auto) for the newly selected model
@@ -581,9 +581,9 @@ export class ModelControls {
 
 	/**
 	 * Classify the current user turn and set the effective thinking level for it.
-	 * Bounded by a timeout + abort; on any failure (no smol model, timeout, parse
-	 * error) it falls back to the provisional concrete level and continues. Never
-	 * throws into the turn, and never clears `#autoThinking` (auto stays active).
+	 * Bounded by a timeout + abort; on failure it preserves the last classified
+	 * level, or uses the provisional concrete level before the first resolution.
+	 * Never throws into the turn, and never clears `#autoThinking`.
 	 */
 	async applyAutoThinkingLevel(promptText: string, generation: number): Promise<void> {
 		const model = this.#model;
@@ -625,7 +625,7 @@ export class ModelControls {
 
 		const effort = clampThinkingLevelToCeiling(
 			model,
-			resolved ?? resolveProvisionalAutoLevel(model),
+			resolved ?? this.#autoResolvedLevel ?? resolveProvisionalAutoLevel(model),
 			this.#thinkingLevelCeiling,
 		);
 		if (effort === undefined) return;

package/src/session/session-advisors.ts

@@ -48,7 +48,6 @@ import {
 	type AdvisorSeverity,
 	AdvisorTranscriptRecorder,
 	advisorTranscriptFilename,
-	annotateForStaleness,
 	buildAdvisorQuarantineSourceText,
 	formatAdvisorBatchContent,
 	getOrCreateAdvisorProviderSessionId,
@@ -890,10 +889,6 @@ export class SessionAdvisors {
 			logger.debug("advisor advice suppressed by emission guard", { severity, advisor: advisor.name });
 			return;
 		}
-		// When newer primary turns already arrived while the advisor model was
-		// processing this batch, the advice was generated without seeing them.
-		// Append a lightweight staleness caveat so the primary can weigh recency.
-		const deliveredNote = annotateForStaleness(note, advisor.runtime.hasFreshBacklog);
 		// The implicit single ("default") advisor stamps no source name, so its
 		// agent-facing `<advisory>` bytes stay identical to the pre-multi-advisor path.
 		const source = advisor.slug ? advisor.name : undefined;
@@ -911,10 +906,10 @@ export class SessionAdvisors {
 			interruptImmuneTurnActive: interrupting && this.#isAdvisorInterruptImmuneTurnActive(),
 		});
 		if (channel === "aside") {
-			this.#host.yieldQueue.enqueue("advisor", { note: deliveredNote, severity, advisor: source });
+			this.#host.yieldQueue.enqueue("advisor", { note, severity, advisor: source });
 			return;
 		}
-		const notes: AdvisorNote[] = [{ note: deliveredNote, severity, advisor: source }];
+		const notes: AdvisorNote[] = [{ note, severity, advisor: source }];
 		const content = formatAdvisorBatchContent(notes);
 		const details = { notes } satisfies AdvisorMessageDetails;
 		if (channel === "preserve") {

package/src/session/session-history-format.ts

@@ -218,7 +218,10 @@ function toolCallLine(
 	return base;
 }
 
-/** One line for a user-initiated `!`/`$` execution. */
+/** One line for a user-initiated `!`/`$` execution. Always attributed to the
+ *  user: these roles never carry agent-run commands (the model's bash goes
+ *  through `toolCall`), so the `user-` prefix makes provenance explicit for the
+ *  advisor and history readers regardless of render mode. */
 function executionLine(
 	kind: "bash" | "python",
 	source: string,
@@ -231,7 +234,7 @@ function executionLine(
 			: "ok";
 	const lines = lineCount(msg.output);
 	const sourcePreview = formatExecutionSourcePreview(source);
-	return `→ ${kind}! ${sourcePreview} ⇒ ${status} · ${lines} ${lines === 1 ? "line" : "lines"}`;
+	return `→ user-${kind}! ${sourcePreview} ⇒ ${status} · ${lines} ${lines === 1 ? "line" : "lines"}`;
 }
 
 /**
@@ -311,6 +314,18 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 	// every call repeats `**agent**:`). Cleared whenever a
 	// non-role-labeled line is emitted so the next turn re-labels.
 	let lastWatchedLabel: string | undefined;
+	// Emit a watched-mode role label, collapsing consecutive same-role turns
+	// under one label (matching the user/assistant paths). Used for the
+	// user-attributed `!`/`$` execution lines so the advisor never reads them
+	// as agent actions.
+	const pushWatchedRole = (label: string, body: string): void => {
+		if (lastWatchedLabel === label) {
+			lines.push(body, "");
+		} else {
+			lines.push(label, body, "");
+			lastWatchedLabel = label;
+		}
+	};
 
 	for (const msg of typed) {
 		switch (msg.role) {
@@ -372,15 +387,25 @@ export function formatSessionHistoryMarkdown(messages: unknown[], opts?: History
 			case "bashExecution": {
 				const bashMsg = msg as BashExecutionMessage;
 				if (bashMsg.excludeFromContext) break;
-				lines.push(executionLine("bash", bashMsg.command, bashMsg), "");
-				lastWatchedLabel = undefined;
+				const bashLine = executionLine("bash", bashMsg.command, bashMsg);
+				if (opts?.watchedRoles) {
+					pushWatchedRole("**user**:", bashLine);
+				} else {
+					lines.push(bashLine, "");
+					lastWatchedLabel = undefined;
+				}
 				break;
 			}
 			case "pythonExecution": {
 				const pythonMsg = msg as PythonExecutionMessage;
 				if (pythonMsg.excludeFromContext) break;
-				lines.push(executionLine("python", pythonMsg.code, pythonMsg), "");
-				lastWatchedLabel = undefined;
+				const pythonLine = executionLine("python", pythonMsg.code, pythonMsg);
+				if (opts?.watchedRoles) {
+					pushWatchedRole("**user**:", pythonLine);
+				} else {
+					lines.push(pythonLine, "");
+					lastWatchedLabel = undefined;
+				}
 				break;
 			}
 			case "custom":

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

@@ -21,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,
@@ -56,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 {
@@ -63,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[];
@@ -161,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;
@@ -190,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 ?? [];
@@ -242,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()
@@ -250,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[] {
@@ -268,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. */
@@ -403,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. */
@@ -543,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");
@@ -557,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");
@@ -590,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;
@@ -612,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;
 		}
@@ -637,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
@@ -649,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;
@@ -678,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,
@@ -727,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"),
 		);
 	}
@@ -736,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.
@@ -849,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;
@@ -964,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({