@oh-my-pi/pi-coding-agent 17.0.1 → 17.0.3

package/src/tools/gh.ts

@@ -10,7 +10,7 @@ import type {
 	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
 
-import { getWorktreeDir, hashPath, isEnoent, prompt, untilAborted } from "@oh-my-pi/pi-utils";
+import { getWorktreeDir, hashPath, isEnoent, logger, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import type { Settings } from "../config/settings";
 import githubDescription from "../prompts/tools/github.md" with { type: "text" };
@@ -239,6 +239,8 @@ const RUN_WATCH_TAIL_DEFAULT = 15;
 const RUN_WATCH_TAIL_MAX = 200;
 const REVIEW_COMMENTS_PAGE_SIZE = 100;
 const RUN_JOBS_PAGE_SIZE = 100;
+const PR_DIFF_FILES_PAGE_SIZE = 100;
+const PR_DIFF_FILES_MAX = 3000;
 const PR_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)(?:\/.*)?$/;
 const ISSUE_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)(?:\/.*)?$/;
 const RUN_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/(\d+)(?:\/.*)?$/;
@@ -2931,6 +2933,160 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 	return file;
 }
 
+/**
+ * A single entry from `GET /repos/{owner}/{repo}/pulls/{n}/files`. `patch` is
+ * absent for binary files and for individual file diffs GitHub deems too large
+ * to render.
+ */
+interface GhPrFileApi {
+	filename?: string;
+	previous_filename?: string;
+	status?: string;
+	additions?: number;
+	deletions?: number;
+	patch?: string;
+}
+
+interface GhPrApi {
+	changed_files?: number;
+}
+
+/**
+ * GitHub rejects the aggregate PR diff endpoint with HTTP 406 once the diff
+ * exceeds 20,000 lines. Detect that specific failure so the caller can fall
+ * back to the per-file endpoint instead of aborting the whole review.
+ */
+function isPrDiffTooLargeError(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : String(err);
+	return (
+		/\bHTTP 406\b/.test(message) ||
+		/exceeded the maximum number of lines/i.test(message) ||
+		/\btoo_large\b/.test(message)
+	);
+}
+
+function formatSyntheticDiffPath(prefix: "a/" | "b/", path: string): string {
+	const prefixedPath = `${prefix}${path}`;
+	if (!/[\u0000-\u001F\s"\\]/.test(prefixedPath)) return prefixedPath;
+
+	let escaped = "";
+	for (const char of prefixedPath) {
+		switch (char) {
+			case "\\":
+				escaped += "\\\\";
+				break;
+			case '"':
+				escaped += '\\"';
+				break;
+			case "\n":
+				escaped += "\\n";
+				break;
+			case "\r":
+				escaped += "\\r";
+				break;
+			case "\t":
+				escaped += "\\t";
+				break;
+			default: {
+				const code = char.charCodeAt(0);
+				escaped += code < 32 ? `\\${code.toString(8).padStart(3, "0")}` : char;
+			}
+		}
+	}
+	return `"${escaped}"`;
+}
+
+/**
+ * Reconstruct a `diff --git` section from a single files-API entry. The API's
+ * `patch` field carries only the hunk body, so the `diff --git`/`---`/`+++`
+ * headers are synthesized to match `gh pr diff` output — this keeps
+ * {@link parsePrUnifiedDiff} and the review parser producing identical section
+ * boundaries and byte offsets. Files whose `patch` is omitted (binary or
+ * too-large) stay visible with an explicit marker rather than being dropped.
+ */
+function buildSyntheticDiffSection(file: GhPrFileApi): string | undefined {
+	const newPath = file.filename;
+	if (!newPath) return undefined;
+	const status = file.status ?? "modified";
+	const oldPath = file.previous_filename ?? newPath;
+	const oldDiffPath = formatSyntheticDiffPath("a/", oldPath);
+	const newDiffPath = formatSyntheticDiffPath("b/", newPath);
+	const lines: string[] = [`diff --git ${oldDiffPath} ${newDiffPath}`];
+	if (status === "added") {
+		lines.push("new file mode 100644");
+	} else if (status === "removed") {
+		lines.push("deleted file mode 100644");
+	} else if (status === "renamed" || file.previous_filename) {
+		lines.push(`rename from ${oldPath}`, `rename to ${newPath}`);
+	}
+	if (typeof file.patch === "string" && file.patch.length > 0) {
+		lines.push(status === "added" ? "--- /dev/null" : `--- ${oldDiffPath}`);
+		lines.push(status === "removed" ? "+++ /dev/null" : `+++ ${newDiffPath}`);
+		lines.push(file.patch);
+	} else {
+		lines.push(
+			`* patch unavailable (binary or too large); additions ${file.additions ?? 0}, deletions ${file.deletions ?? 0}`,
+		);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Fallback PR diff retrieval via the paginated per-file endpoint, used when the
+ * aggregate `gh pr diff` is rejected for exceeding GitHub's 20,000-line limit.
+ * The per-file patches are not subject to that aggregate cap, so even very
+ * large PRs can be reassembled into a synthetic unified diff.
+ */
+async function fetchPrDiffViaFilesApi(
+	cwd: string,
+	repo: string,
+	number: number,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	const pull = await git.github.json<GhPrApi>(
+		cwd,
+		["api", "--method", "GET", `/repos/${repo}/pulls/${number}`],
+		signal,
+		{ repoProvided: true },
+	);
+	if ((pull.changed_files ?? 0) > PR_DIFF_FILES_MAX) {
+		throw new ToolError(
+			`Pull request changes ${pull.changed_files} files, exceeding GitHub's ${PR_DIFF_FILES_MAX}-file limit for the per-file diff API.`,
+		);
+	}
+
+	const sections: string[] = [];
+	let page = 1;
+	while (true) {
+		const response = await git.github.json<GhPrFileApi[]>(
+			cwd,
+			[
+				"api",
+				"--method",
+				"GET",
+				`/repos/${repo}/pulls/${number}/files`,
+				"-F",
+				`per_page=${PR_DIFF_FILES_PAGE_SIZE}`,
+				"-F",
+				`page=${page}`,
+			],
+			signal,
+			{ repoProvided: true },
+		);
+		for (const file of response) {
+			const section = buildSyntheticDiffSection(file);
+			if (section) sections.push(section);
+		}
+		if (response.length < PR_DIFF_FILES_PAGE_SIZE) {
+			break;
+		}
+		page += 1;
+	}
+	// Trailing newline mirrors `gh pr diff` so downstream parsers splitting on
+	// `^diff --git ` see identical boundaries.
+	return sections.length > 0 ? `${sections.join("\n")}\n` : "";
+}
+
 async function fetchPrDiffFresh(
 	cwd: string,
 	repo: string,
@@ -2939,7 +3095,18 @@ async function fetchPrDiffFresh(
 ): Promise<{ rendered: string; sourceUrl: string | undefined; payload: PrDiffPayload }> {
 	const args = ["pr", "diff", String(number), "--color", "never"];
 	appendRepoFlag(args, repo, String(number));
-	const text = await git.github.text(cwd, args, signal, { repoProvided: true, trimOutput: false });
+	let text: string;
+	try {
+		text = await git.github.text(cwd, args, signal, { repoProvided: true, trimOutput: false });
+	} catch (err) {
+		if (!isPrDiffTooLargeError(err)) throw err;
+		logger.debug("gh pr diff exceeded GitHub's aggregate line limit; falling back to per-file API", {
+			repo,
+			number,
+			err: String(err),
+		});
+		text = await fetchPrDiffViaFilesApi(cwd, repo, number, signal);
+	}
 	const payload = parsePrUnifiedDiff(text);
 	// `rendered` already carries the verbatim diff; blank the payload copy so
 	// the cache row stores a potentially huge diff once instead of twice.

package/src/tools/hub/messaging.ts

@@ -17,6 +17,7 @@ import type { RenderResultOptions } from "../../extensibility/custom-tools/types
 import { IrcBus, type IrcDeliveryReceipt, type IrcMessage } from "../../irc/bus";
 import type { Theme } from "../../modes/theme/theme";
 import { type AgentRegistry, MAIN_AGENT_ID } from "../../registry/agent-registry";
+import { registerPersistedSubagents } from "../../registry/persisted-agents";
 import { canSpawnAtDepth } from "../../task/types";
 import { Ellipsis, renderStatusLine, renderTreeList, truncateToWidth } from "../../tui";
 import {
@@ -81,10 +82,22 @@ export function messageResult(senderId: string, waited: IrcMessage): AgentToolRe
 	};
 }
 
-export function executeList(registry: AgentRegistry, senderId: string): AgentToolResult<CoordinationDetails> {
+/**
+ * List every addressable peer, restoring parked refs from disk when a resumed
+ * session has no in-memory roster.
+ */
+export async function executeList(
+	registry: AgentRegistry,
+	senderId: string,
+): Promise<AgentToolResult<CoordinationDetails>> {
+	let refs = registry.list();
+	if (!refs.some(ref => ref.id !== senderId && ref.status !== "aborted" && ref.kind !== "advisor")) {
+		await registerPersistedSubagents(registry, registry.get(senderId)?.sessionFile);
+		refs = registry.list();
+	}
+
 	const bus = IrcBus.global();
-	const peers = registry
-		.list()
+	const peers = refs
 		.filter(ref => ref.id !== senderId && ref.status !== "aborted" && ref.kind !== "advisor")
 		.map(ref => ({
 			id: ref.id,

package/src/tools/image-gen.ts

@@ -45,7 +45,7 @@ const IMAGE_SYSTEM_INSTRUCTION =
 	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
 
 export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
-export type ImageProviderPreference = Exclude<ImageProvider, "openai-codex"> | "auto";
+export type ImageProviderPreference = ImageProvider | "auto";
 
 interface ImageApiKey {
 	provider: ImageProvider;
@@ -57,8 +57,17 @@ interface ImageApiKey {
 const COMMON_IMAGE_ASPECT_RATIOS = ["1:1", "3:4", "4:3", "9:16", "16:9"] as const;
 const XAI_IMAGE_ASPECT_RATIOS = [...COMMON_IMAGE_ASPECT_RATIOS, "3:2", "2:3"] as const;
 const COMMON_IMAGE_ASPECT_RATIO_SET = new Set<string>(COMMON_IMAGE_ASPECT_RATIOS);
-const IMAGE_PROVIDER_PREFERENCES = new Set<string>(["auto", "antigravity", "gemini", "openai", "openrouter", "xai"]);
-const AUTO_IMAGE_PROVIDER_ORDER = ["openai", "antigravity", "xai", "openrouter", "gemini"] as const;
+const IMAGE_PROVIDER_CHOICES = [
+	"auto",
+	"antigravity",
+	"gemini",
+	"openai",
+	"openai-codex",
+	"openrouter",
+	"xai",
+] as const;
+const IMAGE_PROVIDER_PREFERENCES = new Set<string>(IMAGE_PROVIDER_CHOICES);
+const AUTO_IMAGE_PROVIDER_ORDER = ["openai", "openai-codex", "antigravity", "xai", "openrouter", "gemini"] as const;
 
 const responseModalitySchema = type('"IMAGE" | "TEXT"');
 
@@ -71,6 +80,10 @@ const inputImageSchema = type({
 	"mime_type?": type("string").describe("mime type"),
 });
 
+const imageProviderSchema = type
+	.enumerated(...IMAGE_PROVIDER_CHOICES)
+	.describe("image provider for this request; overrides the providers.image setting (default: use the setting)");
+
 export const imageGenSchema = type({
 	subject: type("string").describe("main subject"),
 	"action?": type("string").describe("what subject is doing"),
@@ -83,6 +96,7 @@ export const imageGenSchema = type({
 	"aspect_ratio?": aspectRatioSchema,
 	"image_size?": imageSizeSchema,
 	"input?": inputImageSchema.array().describe("input images"),
+	"provider?": imageProviderSchema,
 });
 export type ImageGenParams = typeof imageGenSchema.infer;
 export type GeminiResponseModality = typeof responseModalitySchema.infer;
@@ -548,6 +562,49 @@ async function findOpenAIHostedImageCredentials(
 	};
 }
 
+// Codex (ChatGPT subscription) chat models that carry OpenAI's hosted
+// `image_generation` tool. Priority: newest general model first, then Codex
+// variants; any available openai-codex hosted-image model is the last resort.
+const CODEX_IMAGE_MODEL_PRIORITY = ["gpt-5.5", "gpt-5.4", "gpt-5.1", "gpt-5", "gpt-5-codex"] as const;
+
+function resolveDefaultCodexImageModel(modelRegistry: ModelRegistry): Model | undefined {
+	for (const id of CODEX_IMAGE_MODEL_PRIORITY) {
+		const model = modelRegistry.find("openai-codex", id);
+		if (model && isOpenAIHostedImageModel(model)) return model;
+	}
+	return modelRegistry.getAll().find(model => model.provider === "openai-codex" && isOpenAIHostedImageModel(model));
+}
+
+/**
+ * Codex subscription (ChatGPT OAuth) image credentials — engages OpenAI's hosted
+ * `image_generation` tool through a CONNECTED Codex account, independent of the
+ * active chat model. This is what lets image generation run on a ChatGPT
+ * subscription (no metered OPENAI_API_KEY) even when the active model is, e.g.,
+ * Claude. The active-model-is-codex case is already served by
+ * {@link findOpenAIHostedImageCredentials}, so it is skipped here to avoid a
+ * duplicate resolution.
+ */
+async function findCodexSubscriptionImageCredentials(
+	modelRegistry: ModelRegistry | undefined,
+	activeModel: Model | undefined,
+	sessionId?: string,
+): Promise<ImageApiKey | null> {
+	if (!modelRegistry) return null;
+	if (isOpenAIHostedImageModel(activeModel) && getOpenAIHostedImageProvider(activeModel) === "openai-codex") {
+		return null;
+	}
+	// A Codex subscription credential is an OAuth JWT with an account claim. API
+	// keys stored under this provider cannot use the ChatGPT backend and must not
+	// prevent fallback providers from being selected.
+	const token = await modelRegistry.getApiKeyForProvider("openai-codex", sessionId);
+	if (!token || !getCodexAccountId(token)) return null;
+	const model = resolveDefaultCodexImageModel(modelRegistry);
+	if (!model) return null;
+	const apiKey = await modelRegistry.getApiKey(model, sessionId);
+	if (!isAuthenticated(apiKey) || !getCodexAccountId(apiKey)) return null;
+	return { provider: "openai-codex", apiKey, model };
+}
+
 function activeImageProvider(model: Model | undefined): Exclude<ImageProviderPreference, "auto"> | null {
 	switch (model?.provider) {
 		case "openai":
@@ -567,7 +624,10 @@ function activeImageProvider(model: Model | undefined): Exclude<ImageProviderPre
 	}
 }
 
-function imageProviderOrder(activeModel: Model | undefined): Array<Exclude<ImageProviderPreference, "auto">> {
+function imageProviderOrder(
+	activeModel: Model | undefined,
+	preference: ImageProviderPreference = preferredImageProvider,
+): Array<Exclude<ImageProviderPreference, "auto">> {
 	const providers: Array<Exclude<ImageProviderPreference, "auto">> = [];
 	const added = new Set<Exclude<ImageProviderPreference, "auto">>();
 	const add = (provider: Exclude<ImageProviderPreference, "auto"> | null): void => {
@@ -576,7 +636,7 @@ function imageProviderOrder(activeModel: Model | undefined): Array<Exclude<Image
 		providers.push(provider);
 	};
 
-	if (preferredImageProvider !== "auto") add(preferredImageProvider);
+	if (preference !== "auto") add(preference);
 	add(activeImageProvider(activeModel));
 	for (const provider of AUTO_IMAGE_PROVIDER_ORDER) add(provider);
 	return providers;
@@ -591,6 +651,8 @@ async function findImageApiKey(
 	switch (provider) {
 		case "openai":
 			return findOpenAIHostedImageCredentials(modelRegistry, activeModel, sessionId);
+		case "openai-codex":
+			return findCodexSubscriptionImageCredentials(modelRegistry, activeModel, sessionId);
 		case "antigravity":
 			return modelRegistry ? findAntigravityCredentials(modelRegistry, sessionId) : null;
 		case "xai":
@@ -1047,7 +1109,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 	async execute(_toolCallId, params, _onUpdate, ctx, signal) {
 		return untilAborted(signal, async () => {
 			const sessionId = ctx.sessionManager.getSessionId();
-			const providerOrder = imageProviderOrder(ctx.model);
+			const providerOrder = imageProviderOrder(ctx.model, params.provider ?? preferredImageProvider);
 			const cwd = ctx.sessionManager.getCwd();
 			const requestSignal = ptree.combineSignals(signal, IMAGE_TIMEOUT);
 			const fetchImpl = ctx.fetch ?? fetch;
@@ -1604,7 +1666,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 
 			if (!foundCredentials) {
 				throw new Error(
-					"No image API credentials found. Use a GPT Responses/Codex model with OpenAI credentials, login with google-antigravity or xAI Grok OAuth, or set XAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
+					"No image API credentials found. Connect a Codex (ChatGPT) subscription, use a GPT Responses/Codex model with OpenAI credentials, log in with google-antigravity or xAI Grok OAuth, or set OPENAI_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY.",
 				);
 			}
 

package/src/tools/index.ts

@@ -28,7 +28,7 @@ import type { UsageStatistics } from "../session/session-entries";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
 import { TaskTool } from "../task";
 import type { AgentOutputManager } from "../task/output-manager";
-import { canSpawnAtDepth } from "../task/types";
+import { canSpawnAtDepth, type StructuredSubagentSchemaMode } from "../task/types";
 import type { EventBus } from "../utils/event-bus";
 import { WebSearchTool } from "../web/search";
 import type { WorkspaceTree } from "../workspace-tree";
@@ -45,7 +45,7 @@ import { resolveEvalBackends } from "./eval-backends";
 import { GithubTool } from "./gh";
 import { GlobTool } from "./glob";
 import { GrepTool } from "./grep";
-import { HubTool } from "./hub";
+import { HubTool, isIrcEnabled } from "./hub";
 import { InspectImageTool } from "./inspect-image";
 import { LearnTool } from "./learn";
 import { ManageSkillTool } from "./manage-skill";
@@ -74,6 +74,7 @@ export * from "./bash";
 export * from "./browser";
 export * from "./checkpoint";
 export * from "./debug";
+export * from "./essential-tools";
 export * from "./eval";
 export * from "./eval-backends";
 export * from "./gh";
@@ -182,17 +183,31 @@ export interface ToolSession {
 	customToolPaths?: ToolPathWithSource[];
 	/** Whether LSP integrations are enabled */
 	enableLsp?: boolean;
+	/** Whether this invocation may expose IRC. `false` removes it even for subagents. */
+	enableIrc?: boolean;
+	/**
+	 * Whether MCP capabilities may be forwarded to child sessions. `false`
+	 * prohibits inherited-manager and process-global MCP fallback.
+	 */
+	enableMCP?: boolean;
 	/** Whether an edit-capable tool is available in this session (controls hashline output) */
 	hasEditTool?: boolean;
 	/** Event bus for tool/extension communication */
 	eventBus?: EventBus;
-	/** Output schema for structured completion (subagents) */
+	/** Output schema for structured completion (subagents). */
 	outputSchema?: unknown;
+	/** Enforcement policy for {@link outputSchema}; defaults to legacy permissive behavior. */
+	outputSchemaMode?: StructuredSubagentSchemaMode;
 	/** Whether to include the yield tool by default */
 	requireYieldTool?: boolean;
 	/** Session starts with a prewalk hand-off armed. Keeps `todo` in yield-gated
 	 *  (subagent) registries: the prewalk plan nudge + todo gate need it. */
 	prewalkArmed?: boolean;
+	/**
+	 * Constrain the active set to the caller's explicit built-in names (plus a
+	 * required yield tool). Suppresses automatic tool-set expansion.
+	 */
+	restrictToolNames?: boolean;
 	/** Task recursion depth (0 = top-level, 1 = first child, etc.) */
 	taskDepth?: number;
 	/** Get shared eval executor session ID. Subagents inherit this to share JS/Python/Ruby/Julia state. */
@@ -402,13 +417,18 @@ export type ToolName = BuiltinToolName;
  * Create tools from BUILTIN_TOOLS registry.
  */
 export async function createTools(session: ToolSession, toolNames?: string[]): Promise<Tool[]> {
+	const restrictToolNames = session.restrictToolNames === true;
 	const includeYield = session.requireYieldTool === true;
 	const enableLsp = session.enableLsp ?? true;
-	let requestedTools = toolNames && toolNames.length > 0 ? normalizeToolNames(toolNames) : undefined;
+	const requestedTools = restrictToolNames
+		? normalizeToolNames(toolNames ?? [])
+		: toolNames && toolNames.length > 0
+			? normalizeToolNames(toolNames)
+			: undefined;
 	const goalEnabled = session.settings.get("goal.enabled");
-	const goalModeActive = goalEnabled && session.getGoalModeState?.()?.enabled === true;
+	const goalModeActive = !restrictToolNames && goalEnabled && session.getGoalModeState?.()?.enabled === true;
 	if (goalModeActive && requestedTools && !requestedTools.includes("goal")) {
-		requestedTools = [...requestedTools, "goal"];
+		requestedTools.push("goal");
 	}
 	const backends = resolveEvalBackends(session);
 	const allowPython = backends.python;
@@ -465,8 +485,12 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	// unreachable, in which case eval dispatches exclusively to the others.
 	const allowEval = effectivePythonAllowed || allowJs || effectiveRubyAllowed || effectiveJuliaAllowed;
 
-	// Auto-include AST counterparts when their text-based sibling is present
-	if (requestedTools) {
+	// Auto-include AST counterparts when their text-based sibling is present.
+	// Restricted callers own the active list and must not have it widened.
+	if (requestedTools && !restrictToolNames) {
+		if (goalModeActive && !requestedTools.includes("goal")) {
+			requestedTools.push("goal");
+		}
 		if (
 			requestedTools.includes("grep") &&
 			!requestedTools.includes("ast_grep") &&
@@ -521,6 +545,11 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "ask") return session.settings.get("ask.enabled");
 		if (name === "browser") return session.settings.get("browser.enabled");
 		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");
+		if (name === "hub") {
+			return (
+				!restrictToolNames && session.enableIrc !== false && isIrcEnabled(session.settings, session.taskDepth ?? 0)
+			);
+		}
 		if (name === "retain" || name === "recall" || name === "reflect") {
 			return ["hindsight", "mnemopi"].includes(session.settings.get("memory.backend") ?? "");
 		}
@@ -568,15 +597,17 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	);
 	let tools = baseResults.filter((r): r is Tool => r !== null);
 
-	// xd:// mounting: unmount discoverable built-ins from the tools array and
-	// expose them as virtual device URLs driven through read/write. Active for
-	// default tool sets when `tools.xdev` is enabled.
-	const xdevEnabled = requestedTools === undefined && session.settings.get("tools.xdev");
+	// Ordinary sessions use xd:// for discoverable built-ins, custom tools, and
+	// MCP tools. Structured children must expose only their host-provided names,
+	// so never allocate a registry that later SDK assembly could populate.
+	// Explicitly requested built-ins retain their top-level presentation.
+	const xdevEnabled = !restrictToolNames && session.settings.get("tools.xdev");
+	const mountBuiltinTools = requestedTools === undefined;
 	if (xdevEnabled) {
 		const mounted: Tool[] = [];
 		const kept: Tool[] = [];
 		for (const tool of tools) {
-			const mountable = isMountableUnderXdev(tool) && tool.name in BUILTIN_TOOLS;
+			const mountable = mountBuiltinTools && isMountableUnderXdev(tool) && tool.name in BUILTIN_TOOLS;
 			(mountable ? mounted : kept).push(tool);
 		}
 		session.xdevRegistry = new XdevRegistry(mounted);
@@ -593,13 +624,17 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	// (e.g. ast_edit) also resolve through a `write` to xd://resolve/reject. Retain
 	// both whenever any device is mounted or a deferrable tool can stage one.
 	const xdevMounted = (session.xdevRegistry?.size ?? 0) > 0;
-	if ((tools.some(tool => tool.deferrable === true) || xdevMounted) && !tools.some(tool => tool.name === "write")) {
+	if (
+		!restrictToolNames &&
+		(tools.some(tool => tool.deferrable === true) || xdevMounted) &&
+		!tools.some(tool => tool.name === "write")
+	) {
 		const writeTool = await logger.time("createTools:write", BUILTIN_TOOLS.write, session);
 		if (writeTool) {
 			tools.push(wrapToolWithMetaNotice(writeTool));
 		}
 	}
-	if (xdevMounted && !tools.some(tool => tool.name === "read")) {
+	if (!restrictToolNames && xdevMounted && !tools.some(tool => tool.name === "read")) {
 		const readTool = await logger.time("createTools:read", BUILTIN_TOOLS.read, session);
 		if (readTool) {
 			tools.push(wrapToolWithMetaNotice(readTool));

package/src/tools/path-utils.ts

@@ -35,6 +35,7 @@ const INTERNAL_SCHEMES_WITH_SELECTORS: Record<string, true> = {
 	agent: true,
 	artifact: true,
 	issue: true,
+	history: true,
 	local: true,
 	memory: true,
 	omp: true,