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

package/src/task/types.ts

@@ -7,6 +7,35 @@ import type { NestedRepoPatch } from "./worktree";
 
 /** Source of an agent definition */
 export type AgentSource = "bundled" | "user" | "project";
+/**
+ * Enforcement policy for a structured subagent output schema.
+ *
+ * `permissive` preserves legacy retry-budget overrides; `strict` turns every
+ * invalid final payload, including an exhausted retry override, into a failed
+ * `schema_violation` result.
+ */
+export type StructuredSubagentSchemaMode = "permissive" | "strict";
+
+/** Origin of the schema selected for a structured subagent invocation. */
+export type StructuredSubagentSchemaSource = "caller" | "agent" | "session" | "none";
+
+/** Final validation state of a structured subagent invocation. */
+export type StructuredSubagentValidationStatus = "valid" | "invalid" | "unavailable";
+
+/**
+ * Parsed structured completion and its schema-validation metadata.
+ *
+ * `data` is present whenever a payload could be assembled or parsed, even when
+ * strict validation rejects it. `error` explains unavailable or invalid
+ * validation without requiring consumers to parse presentation text.
+ */
+export interface StructuredSubagentOutput {
+	source: StructuredSubagentSchemaSource;
+	mode: StructuredSubagentSchemaMode;
+	status: StructuredSubagentValidationStatus;
+	data?: unknown;
+	error?: string;
+}
 
 const parseNumber = (value: string | undefined, defaultValue: number): number => {
 	if (value) {
@@ -81,12 +110,16 @@ export const taskItemSchema = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
+	"outputSchema?": "unknown",
+	"schemaMode?": '"permissive" | "strict"',
 	"+": "delete",
 });
 const taskItemSchemaIsolated = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
+	"outputSchema?": "unknown",
+	"schemaMode?": '"permissive" | "strict"',
 	"isolated?": "boolean",
 	"+": "delete",
 });
@@ -99,6 +132,10 @@ export interface TaskItem {
 	agent?: string;
 	/** The work; required by the schema. */
 	task?: string;
+	/** Caller-provided output schema; its presence overrides the selected agent's schema. */
+	outputSchema?: unknown;
+	/** Validation behavior for a caller-provided or inherited output schema. */
+	schemaMode?: "permissive" | "strict";
 	/** Run this spawn in an isolated worktree (batch form; flat form carries it top-level). */
 	isolated?: boolean;
 }
@@ -107,6 +144,8 @@ export const taskSchema = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
+	"outputSchema?": "unknown",
+	"schemaMode?": '"permissive" | "strict"',
 	"isolated?": "boolean",
 	"+": "delete",
 });
@@ -114,6 +153,8 @@ const taskSchemaNoIsolation = type({
 	"name?": "string",
 	agent: "string = 'task'",
 	task: "string",
+	"outputSchema?": "unknown",
+	"schemaMode?": '"permissive" | "strict"',
 	"+": "delete",
 });
 const taskSchemaBatch = type({
@@ -156,6 +197,8 @@ function createTaskSchema(options: {
 				"name?": "string",
 				agent,
 				task: "string",
+				"outputSchema?": "unknown",
+				"schemaMode?": '"permissive" | "strict"',
 				"isolated?": "boolean",
 				"+": "delete",
 			});
@@ -169,6 +212,8 @@ function createTaskSchema(options: {
 			"name?": "string",
 			agent,
 			task: "string",
+			"outputSchema?": "unknown",
+			"schemaMode?": '"permissive" | "strict"',
 			"+": "delete",
 		});
 		return type.raw({
@@ -182,6 +227,8 @@ function createTaskSchema(options: {
 			"name?": "string",
 			agent,
 			task: "string",
+			"outputSchema?": "unknown",
+			"schemaMode?": '"permissive" | "strict"',
 			"isolated?": "boolean",
 			"+": "delete",
 		});
@@ -190,6 +237,8 @@ function createTaskSchema(options: {
 		"name?": "string",
 		agent,
 		task: "string",
+		"outputSchema?": "unknown",
+		"schemaMode?": '"permissive" | "strict"',
 		"+": "delete",
 	});
 }
@@ -231,6 +280,10 @@ export interface TaskParams {
 	agent?: string;
 	/** The work (flat form). */
 	task?: string;
+	/** Caller-provided output schema; its presence overrides the selected agent's schema. */
+	outputSchema?: unknown;
+	/** Validation behavior for a caller-provided or inherited output schema. */
+	schemaMode?: "permissive" | "strict";
 	/** Batch form (`task.batch`): one subagent per item. */
 	tasks?: TaskItem[];
 	/** Batch form: shared background prepended to every assignment; required by the batch schema. */
@@ -413,6 +466,11 @@ export interface SingleResult {
 	output: string;
 	stderr: string;
 	truncated: boolean;
+	/**
+	 * Parsed structured completion and validation metadata, when this invocation
+	 * selected an output schema or strict schema mode.
+	 */
+	structuredOutput?: StructuredSubagentOutput;
 	durationMs: number;
 	/** Cumulative input + output + cacheWrite tokens across all turns. Excludes cacheRead (re-reads cached context every turn, making cumulative sum misleading). */
 	tokens: number;

package/src/tools/__tests__/eval-description.test.ts

@@ -6,7 +6,7 @@ describe("eval tool description", () => {
 		const description = getEvalToolDescription({ py: true, js: false, spawns: "fact-finder,oracle" });
 
 		expect(description).toContain('agent(prompt, agent?="fact-finder"');
-		expect(description).toContain("Allowed: `fact-finder`, `oracle`.");
+		expect(description).toContain("Allowed agents: `fact-finder`, `oracle`.");
 	});
 
 	it("omits agent() when spawning is disabled", () => {

package/src/tools/fetch.ts

@@ -7,7 +7,6 @@ import type { FetchImpl, ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import { htmlToMarkdown } from "@oh-my-pi/pi-natives";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { $which, ptree, truncate } from "@oh-my-pi/pi-utils";
-import { LRUCache } from "lru-cache/raw";
 import type { Settings } from "../config/settings";
 import { readEditableNotebookText } from "../edit/notebook";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -19,6 +18,7 @@ import { renderStatusLine, urlHyperlink } from "../tui";
 import { CachedOutputBlock, markFramedBlockComponent } from "../tui/output-block";
 import { webpExclusionForModel } from "../utils/image-loading";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { CONVERTIBLE_EXTENSIONS } from "../utils/markit";
 import { ensureTool } from "../utils/tools-manager";
 import { type ArchiveFormat, listArchiveRoot, sniffArchiveFormat } from "../utils/zip";
 import { extractWithParallel, findParallelApiKey, getParallelExtractContent } from "../web/parallel";
@@ -39,21 +39,17 @@ import { clampTimeout } from "./tool-timeouts";
 // =============================================================================
 
 const FETCH_DEFAULT_MAX_LINES = 300;
-// Convertible document types handled by markit.
+// MIME types markit can convert — one per registered converter (pdf, docx,
+// pptx, xlsx, epub). Legacy `application/msword`, `application/vnd.ms-*`, and
+// `application/rtf` are intentionally absent: markit has no converter for them.
 const CONVERTIBLE_MIMES = new Set([
 	"application/pdf",
-	"application/msword",
-	"application/vnd.ms-powerpoint",
-	"application/vnd.ms-excel",
 	"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
 	"application/vnd.openxmlformats-officedocument.presentationml.presentation",
 	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-	"application/rtf",
 	"application/epub+zip",
 ]);
 
-const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".rtf", ".epub"]);
-
 const NOTEBOOK_MIMES = new Set(["application/x-ipynb+json"]);
 const NOTEBOOK_EXTENSIONS = new Set([".ipynb"]);
 
@@ -1553,24 +1549,15 @@ export interface ReadUrlToolDetails {
 	meta?: OutputMeta;
 }
 
-interface ReadUrlCacheEntry {
+interface ReadUrlEntry {
 	artifactId?: string;
 	artifactPath?: string;
-	contentPath?: string;
 	details: ReadUrlToolDetails;
 	image?: FetchImagePayload;
 	output: string;
 	content: string;
 }
 
-const READ_URL_CACHE_MAX_ENTRIES = 100;
-const readUrlCache = new LRUCache<string, ReadUrlCacheEntry>({ max: READ_URL_CACHE_MAX_ENTRIES });
-
-function getReadUrlCacheKey(session: ToolSession, requestedUrl: string, raw: boolean): string {
-	const scope = session.getSessionFile() ?? session.cwd;
-	return `${scope}::${raw ? "raw" : "rendered"}::${normalizeUrl(requestedUrl)}`;
-}
-
 async function findArtifactPath(session: ToolSession, artifactId: string): Promise<string | null> {
 	const artifactsDir = session.getArtifactsDir?.();
 	if (!artifactsDir) return null;
@@ -1584,25 +1571,6 @@ async function findArtifactPath(session: ToolSession, artifactId: string): Promi
 	}
 }
 
-async function readArtifactOutput(session: ToolSession, artifactId: string): Promise<string | null> {
-	const artifactPath = await findArtifactPath(session, artifactId);
-	return artifactPath ? await Bun.file(artifactPath).text() : null;
-}
-
-async function materializeReadUrlCacheEntry(
-	session: ToolSession,
-	entry: ReadUrlCacheEntry,
-): Promise<ReadUrlCacheEntry | null> {
-	if (entry.artifactId) {
-		const artifactOutput = await readArtifactOutput(session, entry.artifactId);
-		if (artifactOutput !== null) {
-			return { ...entry, output: artifactOutput };
-		}
-	}
-
-	return entry.output.length > 0 ? entry : null;
-}
-
 async function persistReadUrlArtifact(
 	session: ToolSession,
 	output: string,
@@ -1613,7 +1581,7 @@ async function persistReadUrlArtifact(
 	return artifact;
 }
 
-async function ensureReadUrlCacheArtifact(session: ToolSession, entry: ReadUrlCacheEntry): Promise<ReadUrlCacheEntry> {
+async function ensureReadUrlArtifact(session: ToolSession, entry: ReadUrlEntry): Promise<ReadUrlEntry> {
 	if (entry.artifactId && entry.artifactPath) return entry;
 	if (entry.artifactId) {
 		const artifactPath = await findArtifactPath(session, entry.artifactId);
@@ -1632,19 +1600,7 @@ function readUrlContentExtension(finalUrl: string): string {
 	}
 }
 
-async function ensureReadUrlContentFile(
-	session: ToolSession,
-	entry: ReadUrlCacheEntry,
-	raw: boolean,
-): Promise<ReadUrlCacheEntry> {
-	if (entry.contentPath) {
-		try {
-			await Bun.file(entry.contentPath).stat();
-			return entry;
-		} catch {
-			// Recreate below when the cached scratch file was removed.
-		}
-	}
+async function materializeReadUrlContent(session: ToolSession, entry: ReadUrlEntry, raw: boolean): Promise<string> {
 	const root = session.getArtifactsDir?.();
 	if (!root) {
 		throw new ToolError("Cannot search URL output because this session cannot materialize read artifacts.");
@@ -1654,20 +1610,16 @@ async function ensureReadUrlContentFile(
 	const hash = Bun.hash(`${raw ? "raw" : "rendered"}:${entry.details.finalUrl}`).toString(36);
 	const contentPath = path.join(dir, `${hash}${readUrlContentExtension(entry.details.finalUrl)}`);
 	await Bun.write(contentPath, entry.content);
-	return { ...entry, contentPath };
-}
-
-function cacheReadUrlEntry(session: ToolSession, requestedUrl: string, raw: boolean, entry: ReadUrlCacheEntry): void {
-	readUrlCache.set(getReadUrlCacheKey(session, requestedUrl, raw), entry);
-	readUrlCache.set(getReadUrlCacheKey(session, entry.details.finalUrl, raw), entry);
+	return contentPath;
 }
 
-async function buildReadUrlCacheEntry(
+/** Fetch and render a URL for a read or search operation. */
+export async function fetchReadUrl(
 	session: ToolSession,
 	params: { path: string; raw?: boolean },
 	signal?: AbortSignal,
 	options?: { ensureArtifact?: boolean },
-): Promise<ReadUrlCacheEntry> {
+): Promise<ReadUrlEntry> {
 	const { path: url, raw = false } = params;
 
 	const effectiveTimeout = clampTimeout("fetch", 30);
@@ -1708,30 +1660,6 @@ async function buildReadUrlCacheEntry(
 	};
 }
 
-export async function loadReadUrlCacheEntry(
-	session: ToolSession,
-	params: { path: string; raw?: boolean },
-	signal?: AbortSignal,
-	options?: { ensureArtifact?: boolean; preferCached?: boolean },
-): Promise<ReadUrlCacheEntry> {
-	const raw = params.raw ?? false;
-	const cached = readUrlCache.get(getReadUrlCacheKey(session, params.path, raw));
-	if (options?.preferCached && cached) {
-		const prepared = options.ensureArtifact ? await ensureReadUrlCacheArtifact(session, cached) : cached;
-		const materialized = await materializeReadUrlCacheEntry(session, prepared);
-		if (materialized) {
-			cacheReadUrlEntry(session, params.path, raw, materialized);
-			return materialized;
-		}
-	}
-
-	const fresh = await buildReadUrlCacheEntry(session, params, signal, {
-		ensureArtifact: options?.ensureArtifact,
-	});
-	cacheReadUrlEntry(session, params.path, raw, fresh);
-	return fresh;
-}
-
 /** Materialize rendered URL body text to a local file for tools that require filesystem paths. */
 export async function materializeReadUrlToFile(
 	session: ToolSession,
@@ -1741,13 +1669,9 @@ export async function materializeReadUrlToFile(
 	if (!session.settings.get("fetch.enabled")) {
 		throw new ToolError("URL reads are disabled by settings.");
 	}
-	const cacheEntry = await loadReadUrlCacheEntry(session, params, signal, { preferCached: true });
-	const materialized = await ensureReadUrlContentFile(session, cacheEntry, params.raw ?? false);
-	cacheReadUrlEntry(session, params.path, params.raw ?? false, materialized);
-	if (!materialized.contentPath) {
-		throw new ToolError("Cannot search URL output because this session cannot materialize read artifacts.");
-	}
-	return { path: materialized.contentPath, details: materialized.details };
+	const entry = await fetchReadUrl(session, params, signal);
+	const contentPath = await materializeReadUrlContent(session, entry, params.raw ?? false);
+	return { path: contentPath, details: entry.details };
 }
 
 function buildUrlReadOutput(result: FetchRenderResult, content: string): string {
@@ -1768,36 +1692,35 @@ export async function executeReadUrl(
 	params: { path: string; raw?: boolean },
 	signal?: AbortSignal,
 ): Promise<AgentToolResult<ReadUrlToolDetails>> {
-	let cacheEntry = await loadReadUrlCacheEntry(session, params, signal, { preferCached: true });
-	const truncation = truncateHead(cacheEntry.output, {
+	let entry = await fetchReadUrl(session, params, signal);
+	const truncation = truncateHead(entry.output, {
 		maxBytes: DEFAULT_MAX_BYTES,
 		maxLines: FETCH_DEFAULT_MAX_LINES,
 	});
 	const needsArtifact = truncation.truncated;
-	if (needsArtifact && !cacheEntry.artifactId) {
-		cacheEntry = await ensureReadUrlCacheArtifact(session, cacheEntry);
-		cacheReadUrlEntry(session, params.path, params.raw ?? false, cacheEntry);
+	if (needsArtifact && !entry.artifactId) {
+		entry = await ensureReadUrlArtifact(session, entry);
 	}
-	const output = needsArtifact ? truncation.content : cacheEntry.output;
+	const output = needsArtifact ? truncation.content : entry.output;
 	const details: ReadUrlToolDetails = {
-		...cacheEntry.details,
-		truncated: Boolean(cacheEntry.details.truncated || needsArtifact),
+		...entry.details,
+		truncated: Boolean(entry.details.truncated || needsArtifact),
 	};
 
 	const contentBlocks: Array<TextContent | ImageContent> = [{ type: "text", text: output }];
-	if (cacheEntry.image) {
-		contentBlocks.push({ type: "image", data: cacheEntry.image.data, mimeType: cacheEntry.image.mimeType });
+	if (entry.image) {
+		contentBlocks.push({ type: "image", data: entry.image.data, mimeType: entry.image.mimeType });
 	}
 
 	const resultBuilder = toolResult(details).content(contentBlocks).sourceUrl(details.finalUrl);
 	if (needsArtifact) {
-		resultBuilder.truncation(truncation, { direction: "head", artifactId: cacheEntry.artifactId });
-	} else if (cacheEntry.details.truncated) {
-		const outputLines = cacheEntry.output.split("\n").length;
-		const outputBytes = Buffer.byteLength(cacheEntry.output, "utf-8");
+		resultBuilder.truncation(truncation, { direction: "head", artifactId: entry.artifactId });
+	} else if (entry.details.truncated) {
+		const outputLines = entry.output.split("\n").length;
+		const outputBytes = Buffer.byteLength(entry.output, "utf-8");
 		const totalBytes = Math.max(outputBytes + 1, MAX_OUTPUT_CHARS + 1);
 		const totalLines = outputLines + 1;
-		resultBuilder.truncationFromText(cacheEntry.output, {
+		resultBuilder.truncationFromText(entry.output, {
 			direction: "tail",
 			totalLines,
 			totalBytes,

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/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";
@@ -183,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. */
@@ -403,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;
@@ -466,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") &&
@@ -522,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") ?? "");
 		}
@@ -569,10 +597,11 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	);
 	let tools = baseResults.filter((r): r is Tool => r !== null);
 
-	// Always create the xd:// registry when enabled so SDK assembly can mount
-	// discoverable custom/MCP tools later. Explicitly requested built-ins keep
-	// their top-level presentation; default tool sets mount discoverable built-ins.
-	const xdevEnabled = 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[] = [];
@@ -595,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,

package/src/tools/read.ts

@@ -62,7 +62,7 @@ import {
 	MAX_IMAGE_INPUT_BYTES,
 	webpExclusionForModel,
 } from "../utils/image-loading";
-import { convertFileWithMarkit } from "../utils/markit";
+import { CONVERTIBLE_EXTENSIONS, convertFileWithMarkit } from "../utils/markit";
 import { type ArchiveReader, formatArchiveEntryLines, openArchive, parseArchivePathCandidates } from "../utils/zip";
 import { buildDirectoryTree, type DirectoryTree } from "../workspace-tree";
 import {
@@ -78,7 +78,7 @@ import {
 } from "./conflict-detect";
 import {
 	executeReadUrl,
-	loadReadUrlCacheEntry,
+	fetchReadUrl,
 	parseReadUrlTarget,
 	type ReadUrlToolDetails,
 	renderReadUrlCall,
@@ -151,9 +151,6 @@ function getSummaryParseCache(session: object): LRUCache<string, SummaryResult |
 	return cache;
 }
 
-// Document types converted to markdown via markit.
-const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".rtf", ".epub"]);
-
 const MAX_SUMMARY_BYTES = 2 * 1024 * 1024;
 const MAX_SUMMARY_LINES = 20_000;
 const MAX_ARTIFACT_RAW_INLINE_BYTES = DEFAULT_MAX_BYTES;
@@ -2167,15 +2164,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			const urlRaw = parsedUrlTarget.raw;
 			const urlRanges = parsedUrlTarget.ranges;
 			if (urlRanges !== undefined && urlRanges.length > 1) {
-				const cached = await loadReadUrlCacheEntry(
-					this.session,
-					{ path: parsedUrlTarget.path, raw: urlRaw },
-					signal,
-					{ ensureArtifact: true, preferCached: true },
-				);
-				return this.#buildInMemoryMultiRangeResult(cached.output, urlRanges, {
-					details: { ...cached.details },
-					sourceUrl: cached.details.finalUrl,
+				const entry = await fetchReadUrl(this.session, { path: parsedUrlTarget.path, raw: urlRaw }, signal, {
+					ensureArtifact: true,
+				});
+				return this.#buildInMemoryMultiRangeResult(entry.output, urlRanges, {
+					details: { ...entry.details },
+					sourceUrl: entry.details.finalUrl,
 					entityLabel: "URL output",
 					raw: urlRaw,
 					immutable: true,
@@ -2184,18 +2178,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			const urlOffset = parsedUrlTarget.offset;
 			const urlLimit = parsedUrlTarget.limit;
 			if (urlOffset !== undefined || urlLimit !== undefined) {
-				const cached = await loadReadUrlCacheEntry(
-					this.session,
-					{ path: parsedUrlTarget.path, raw: urlRaw },
-					signal,
-					{
-						ensureArtifact: true,
-						preferCached: true,
-					},
-				);
-				return this.#buildInMemoryTextResult(cached.output, urlOffset, urlLimit, {
-					details: { ...cached.details },
-					sourceUrl: cached.details.finalUrl,
+				const entry = await fetchReadUrl(this.session, { path: parsedUrlTarget.path, raw: urlRaw }, signal, {
+					ensureArtifact: true,
+				});
+				return this.#buildInMemoryTextResult(entry.output, urlOffset, urlLimit, {
+					details: { ...entry.details },
+					sourceUrl: entry.details.finalUrl,
 					entityLabel: "URL output",
 					raw: urlRaw,
 					immutable: true,