one-code-extension 0.4.1 → 0.6.0

package/extensions/tool-search/index.ts

@@ -26,194 +26,361 @@
  * and pi's event bus only delivers to listeners already registered.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
 	DEFER_CHANNEL,
 	deferredAddendumText,
 	deferredMissReminderText,
 	DeferredRegistry,
+	deferralEnabled,
 	deferredReminderText,
+	loaderUnavailableReminderText,
 	type DeferRequest,
 	resultText,
 	searchTools,
-	selectedNames,
+	selectedRequests,
+	type ResponsesToolLoadModel,
 	stabilizeDeferredTools,
+	stabilizeResponsesToolLoads,
+	responsesToolLoadCompat,
 	supportsToolReferences,
 	toolNotFoundName,
 	toolSearchLoads,
+	toolsInUse,
+	callableDeferredTools,
+	reconcileActive,
+	WITHHOLD_CHANNEL,
+	DEFERRED_QUERY_CHANNEL,
+	type DeferredQuery,
+	deferredRemovedText,
+	withheldMissReminderText,
+	unavailableToolReminderText,
 } from "../lib/deferred.ts";
-import { looksLikeAnthropicRequest } from "../lib/anthropic-payload.ts";
-import { MCP_TOOLS_CHANNEL, type McpToolsPayload } from "../lib/mcp-share.ts";
-import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { looksLikeAnthropicRequest, MID_CONVERSATION_SYSTEM_BETA, withBetas } from "../lib/anthropic-payload.ts";
+import { liftAddenda, supportsToolAdditions, TOOL_ADDITION_BETAS, withToolAdditions } from "../lib/tool-additions.ts";
+import { inContextEntries } from "../lib/compaction-boundary.ts";
+import { CALLABLE_TOOLS } from "../lib/ledger/fold.ts";
+import { foldOnce, sameEntries } from "../lib/ledger/fold-memo.ts";
+import { recordedToolNames } from "../lib/ledger/wire.ts";
+import { MCP_TOOLS_CHANNEL } from "../lib/mcp-share.ts";
+import { sessionIdentity } from "../lib/anthropic-auth.ts";
+import type { EntryLike } from "../lib/ledger/records.ts";
+import { CONTEXT_ORDER, REMINDER_CHANNEL, RENDER_CHANNEL, type RenderRequest } from "../lib/reminders.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
 import { ccToolRenderers } from "../lib/tui-render.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
-import { applyAnnouncement, planAnnouncement } from "./announce.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
 
-/** Coalesces the burst of per-tool defers one server emits into one listing update. */
-const ANNOUNCE_DEBOUNCE_MS = 100;
+/** The told mode for "this epoch's message 1 lists deferred tools this run cannot load", said once per epoch. */
+const UNAVAILABLE_MODE = "deferred-unavailable";
+
+/** A session manager as far as the reconciler reads it (a test double may lack `getBranch`). */
+type SessionLike = { getBranch?: () => unknown[] };
+const branchOf = (session: SessionLike | undefined) => (session?.getBranch?.() ?? []) as EntryLike[];
 
 export default function toolSearchExtension(pi: ExtensionAPI) {
 	// Owned here (see lib/deferred.ts): the only instance, fed over DEFER_CHANNEL.
 	const deferredRegistry = new DeferredRegistry();
+	// Names WITHHOLD_CHANNEL removed from the registry, kept only so a direct
+	// call to one still gets an explanation (tool_execution_end below) instead
+	// of a bare "not found": the registry itself can't answer that, since
+	// removal is what makes the name stop being deferred (searchable/loadable).
+	// A re-defer (a model change bringing it back) clears the name from here.
+	const withheldNames = new Set<string>();
 	let sessionStarted = false;
-	// The deferred-tools listing is a first-prepend reminder on message 1, part of
-	// the cached prefix of every later request. Before the first request nothing
-	// is cached, so the listing is (re)written freely; after it the listing is
-	// FROZEN and later arrivals ride a one-shot addendum where the model reads
-	// next (./announce.ts — a rewrite re-cached 16.7k tokens of history on
-	// request 2 of every run whose MCP tools registered inside the debounce,
-	// measured 2026-09-04). While the initial MCP connect is still settling the
-	// addendum waits for settle, so one burst of per-tool defers is one notice.
-	let requestSent = false;
-	let mcpSettled = false;
-	let announcePending = false;
-	let announceTimer: NodeJS.Timeout | undefined;
 	// After session_shutdown every pi.* call throws (the runner is invalidated,
-	// findings §8); a debounced announce landing in a timer callback then would
-	// be an uncaught exception and take pi down (LIFECYCLE-REVIEW L1).
+	// findings §8): an event that lands then must do nothing (LIFECYCLE-REVIEW L1).
 	const alive = sessionAlive(pi);
-	/** Names the model has been told about: the frozen listing plus every addendum. */
-	const announced = new Set<string>();
+	/** The session's manager, for folding what the current epoch has told and loaded outside a hook that carries one. */
+	let session: SessionLike | undefined;
+	/** The session's model, for a decision made outside a hook that carries one. */
+	let currentModel: { provider?: string; api?: string; id?: string; compat?: unknown } | undefined;
+	/**
+	 * The branch's fold with the live identity, so a model or auth switch
+	 * counts. Shared with the ledger (lib/ledger/fold-memo.ts): the fold this
+	 * turn_start takes serves the request's `context` hook, and a server's
+	 * connect defers its tools in a burst with nothing appended between.
+	 */
+	const foldOf = (owner: SessionLike | undefined, branch: EntryLike[], model: typeof currentModel) => foldOnce(owner, branch, sessionIdentity(pi, model));
 
-	const searchableTools = () =>
-		pi
-			.getAllTools()
+	/** Whether tool_search is registered; a `--tools` list without it turns deferral off (lib/deferred.ts). */
+	const deferring = () => deferralEnabled(pi.getAllTools());
+	const searchableTools = (all = pi.getAllTools()) => {
+		if (!deferralEnabled(all)) return [];
+		return all
 			.filter((tool) => deferredRegistry.has(tool.name))
 			.map((tool) => ({
 				name: tool.name,
 				description: tool.description ?? "",
 				keywords: deferredRegistry.keywordsFor(tool.name),
 			}));
+	};
 
-	const announce = () => {
+	/**
+	 * The deferred-tools listing as live state: what an epoch's message 1 says.
+	 * Inside an epoch message 1 is the record, so a change here is announced by
+	 * the render step below, never by rewriting it.
+	 */
+	const publishListing = () => {
 		if (!alive()) return;
 		const available = searchableTools();
-		const plan = planAnnouncement({ requestSent, announced, available: available.map((t) => t.name) });
-		if (plan.kind === "rewrite") {
-			pi.events.emit(REMINDER_CHANNEL, {
-				scope: "every-turn",
-				key: "deferred-tools",
-				text: deferredReminderText(available),
-				placement: "first-prepend",
-				order: CONTEXT_ORDER.deferredTools,
-			});
-		} else if (plan.kind === "addendum") {
-			// Unkeyed on purpose: a keyed next-turn reminder replaces its
-			// predecessor, and an addendum replaced before delivery would lose names.
-			pi.events.emit(REMINDER_CHANNEL, { text: deferredAddendumText(plan.added) });
+		if (available.length === 0) {
+			pi.events.emit(REMINDER_CHANNEL, { key: "deferred-tools", remove: true });
+			return;
 		}
-		applyAnnouncement(announced, plan);
-	};
-
-	const clearAnnounce = () => {
-		if (announceTimer) clearTimeout(announceTimer);
-		announceTimer = undefined;
-	};
-	const scheduleAnnounce = () => {
-		clearAnnounce();
-		if (!alive()) return;
-		announceTimer = setTimeout(() => {
-			announceTimer = undefined;
-			// Decided at fire time, not schedule time: a request may have gone out
-			// during the debounce (the -p race).
-			if (requestSent && !mcpSettled) {
-				announcePending = true;
-				return;
-			}
-			announce();
-		}, ANNOUNCE_DEBOUNCE_MS);
-		announceTimer.unref?.();
+		pi.events.emit(REMINDER_CHANNEL, {
+			key: "deferred-tools",
+			text: deferredReminderText(available),
+			placement: "first-prepend",
+			order: CONTEXT_ORDER.deferredTools,
+			facts: [{ kind: "tools", names: available.map((tool) => tool.name) }],
+		});
 	};
 
+	/** Deferred tools this process has seen loadable: one of them missing later is known to be gone. */
+	const seenHere = new Set<string>();
+	/** True once the MCP extension published its settled tool set: an MCP tool missing then is gone. */
+	let mcpSettled = false;
 	pi.events.on(MCP_TOOLS_CHANNEL, (data) => {
-		if (!(data as McpToolsPayload | undefined)?.settled) return;
-		mcpSettled = true;
-		if (announcePending) {
-			announcePending = false;
-			announce();
+		if ((data as { settled?: boolean } | undefined)?.settled) mcpSettled = true;
+	});
+
+	// Inside an epoch, a deferred tool that registered since the epoch's listing
+	// is announced on the request's tail: computed when the request goes out,
+	// from what is loadable then and what the epoch has told, so a tool withheld
+	// in the meantime is never announced (the H1 class). Where the model takes
+	// Claude Code's tool_addition, the addendum becomes one (the context and
+	// payload hooks below) and the tool is callable at once.
+	pi.events.on(RENDER_CHANNEL, (data) => {
+		const request = data as RenderRequest;
+		if (request.epoch) return;
+		const told = request.told.get("tools") ?? new Set<string>();
+		if (!deferring()) {
+			// The epoch's message 1 lists deferred tools this run cannot load.
+			if (told.size > 0 && !request.modes.has(UNAVAILABLE_MODE)) {
+				request.blocks.push({ text: loaderUnavailableReminderText(), facts: [{ kind: "mode", key: UNAVAILABLE_MODE, on: true }] });
+			}
+			return;
+		}
+		// A tool told and missing now is announced gone once its absence is known
+		// (the fold then holds it untold, so a return is announced as new): this
+		// process saw it leave, or it is an MCP tool and the MCP connects have
+		// settled (a resume sends its first request before a slow server
+		// registers, and a fork never had the parent's own tools). A tool
+		// withdrawn for the model is not gone: a call to it says so.
+		const loadable = new Set(searchableTools().map((tool) => tool.name));
+		for (const name of loadable) seenHere.add(name);
+		const absent = (name: string) => seenHere.has(name) || (name.startsWith("mcp__") && mcpSettled);
+		const removed = [...told].filter((name) => !loadable.has(name) && !withheldNames.has(name) && absent(name));
+		if (removed.length > 0) request.blocks.push({ text: deferredRemovedText(removed), facts: [{ kind: "tools", names: removed, removed: true }] });
+		const added = [...loadable].filter((name) => !told.has(name));
+		if (added.length === 0) return;
+		if (!supportsToolAdditions(request.model)) {
+			request.blocks.push({ text: deferredAddendumText(added), facts: [{ kind: "tools", names: added }] });
+			return;
 		}
+		// Here an addendum is a tool_addition, callable at once: only a tool the
+		// reconciler activated before pi fixed this turn's tools (turn_start) is
+		// announced; one that arrived since waits for the next request.
+		const active = new Set(pi.getActiveTools());
+		const callable = added.filter((name) => active.has(name));
+		if (callable.length > 0) request.blocks.push({ text: deferredAddendumText(callable), facts: [{ kind: "tools", names: callable, callable: true }] });
 	});
 
-	pi.on("context", () => {
-		requestSent = true;
+	/** The addenda the last `context` pass lifted off tool results, by call id (lib/tool-additions.ts). */
+	let addendaByCall = new Map<string, string[]>();
+	pi.on("context", (event, ctx) => {
+		addendaByCall = new Map();
+		if (!supportsToolAdditions(ctx?.model) || !Array.isArray(event?.messages)) return undefined;
+		const lifted = liftAddenda(event.messages);
+		addendaByCall = lifted.byCall;
+		return lifted.messages === event.messages ? undefined : { messages: lifted.messages };
 	});
 
-	// Every tool_search load of this session (call id → names), seeded from the
-	// transcript at session_start and extended by each load: the wire hook needs
-	// it to reference a loaded tool from the result that loaded it.
+	// Every tool_search load still in context (call id → names), derived from the
+	// branch by each reconcile, plus the loads this turn made that are not on the
+	// branch yet: the wire hook needs it to reference a loaded tool from the
+	// result that loaded it.
 	let loads = new Map<string, string[]>();
-	// The loads a resumed session's transcript already holds (empty after
-	// /clear). The transcript tells the model those tools are callable, and
-	// Claude Code keeps a ToolSearch-loaded tool callable across a resume (its
-	// tool_reference blocks stay in the history), so deferring them again would
-	// send the model into a "Tool <name> not found" round trip. pi restores them
-	// as active from the transcript before session_start; deferAll and the
-	// late-defer handler leave those alone. A load made during this session
-	// activates the tool directly and never needs this set.
-	let loadedBefore = new Set<string>();
-
-	// On models that take client-side tool references (first-party Claude >= 4.5,
-	// not Haiku) the `tools` array is held byte-identical to request 1's: every
-	// deferred tool rides every Anthropic request as a `defer_loading: true`
-	// definition, and a tool that tool_search loaded — which pi 0.86 promotes into
-	// the eager list, re-caching everything from the tools block down — is
-	// demoted back to deferred and loaded through `tool_reference` blocks in the
-	// tool_search result that activated it (lib/deferred.ts stabilizeDeferredTools
-	// has the rules; docs/decisions/caching.md the measurements).
-	pi.on("before_provider_request", (event, ctx) => {
-		if (!supportsToolReferences(ctx.model as { provider?: string; id?: string } | undefined)) return undefined;
-		if (!looksLikeAnthropicRequest(event.payload)) return undefined;
-		return stabilizeDeferredTools(event.payload as Record<string, unknown>, pi.getAllTools(), (name) => deferredRegistry.has(name), loads);
-	});
+	/** Loads `tool_search` made since the last turn started: their results reach the branch when the batch ends. */
+	const freshLoads = new Map<string, string[]>();
 
+	/** What the branch's in-context history loaded and uses, for the branch it was read from. */
+	let used: { entries: readonly EntryLike[]; loads: ReadonlyMap<string, string[]>; inUse: ReadonlySet<string> } | undefined;
+	/**
+	 * The branch's in-context loads and tools in use, read again only when the
+	 * branch changed (lib/ledger/fold-memo.ts `sameEntries`): the reconciler runs
+	 * at every turn, model switch, defer and withhold, and a server's connect
+	 * defers its tools in a burst with nothing appended between. Both are pure
+	 * functions of the entries; the registry, the model and this turn's loads
+	 * are applied on top at each run.
+	 */
+	const branchUse = (branch: EntryLike[]) => {
+		if (used && sameEntries(used.entries, branch)) return used;
+		const inContext = inContextEntries(branch) as SessionEntry[];
+		const loads = toolSearchLoads(inContext);
+		used = { entries: [...branch], loads, inUse: toolsInUse(inContext, loads) };
+		return used;
+	};
 
-	/** Deactivate every deferred-registry tool the transcript has not loaded, and announce the loadable set. */
-	const deferAll = () => {
+	/**
+	 * The one place deferred tools are activated and deactivated (lib/deferred.ts
+	 * callableDeferredTools): a deferred tool is active exactly when the branch
+	 * gives a reason. Its history uses it (a load or a call in context), the
+	 * epoch announced it callable, the recorded head the next request starts
+	 * from declares it eagerly, or the next request announces it callable.
+	 * Claude Code keeps a loaded tool callable across a resume (its
+	 * tool_reference blocks stay in the history); a compaction returns to
+	 * deferred what its kept turns no longer use, and keeps what the last
+	 * request declared eagerly (removing it from `tools` would be the miss). A
+	 * withheld tool is never active. Run before pi fixes a turn's tools
+	 * (turn_start) and whenever the inputs change.
+	 */
+	const reconcile = (owner: SessionLike | undefined, model: typeof currentModel) => {
+		if (!alive()) return;
+		const all = pi.getAllTools();
+		const registered = new Set(all.map((tool) => tool.name));
+		if (!deferralEnabled(all)) {
+			// Nothing is deferred without the loader, but a withheld tool is still
+			// never active: a /tree switch restores a loadout from before it left.
+			const active = pi.getActiveTools();
+			const next = reconcileActive(active, new Set(), new Set(), withheldNames, registered);
+			if (next !== active) pi.setActiveTools([...next]);
+			return;
+		}
+		const branch = branchOf(owner);
+		const use = branchUse(branch);
+		loads = new Map([...use.loads, ...freshLoads]);
 		const deferred = new Set(deferredRegistry.names);
-		if (deferred.size === 0) return;
+		// With nothing deferred no deferred tool is callable: the active set
+		// loses only withheld tools, and the branch's fold has nothing to decide.
+		let callable = new Set<string>();
+		if (deferred.size > 0) {
+			const fold = foldOf(owner, branch, model);
+			const inUse = new Set(use.inUse);
+			for (const names of freshLoads.values()) for (const name of names) inUse.add(name);
+			const last = fold.lastRequest;
+			const told = fold.told.get("tools") ?? new Set<string>();
+			const announcing = supportsToolAdditions(model) && !fold.opensEpoch ? new Set(searchableTools(all).map((tool) => tool.name).filter((name) => !told.has(name))) : new Set<string>();
+			callable = callableDeferredTools(deferred, {
+				inUse,
+				toldCallable: fold.told.get(CALLABLE_TOOLS) ?? new Set(),
+				declaredEager: last ? recordedToolNames(last, { eager: true }) : new Set(),
+				announcing,
+			});
+		}
 		const active = pi.getActiveTools();
-		const next = active.filter((name) => !deferred.has(name) || loadedBefore.has(name));
-		if (next.length !== active.length) pi.setActiveTools(next);
-		announce();
+		const next = reconcileActive(active, deferred, callable, withheldNames, registered);
+		if (next !== active) pi.setActiveTools([...next]);
 	};
+	const reconcileNow = () => reconcile(session, currentModel);
+
+	// On models that take client-side tool references (first-party Claude >= 4.5,
+	// not Haiku) every deferred tool rides every Anthropic request as a
+	// `defer_loading: true` definition, and a tool that tool_search loaded — which
+	// pi promotes into the eager list — is demoted back to deferred and loaded
+	// through `tool_reference` blocks in the tool_search result that activated it
+	// (lib/deferred.ts stabilizeDeferredTools has the rules;
+	// working-docs/decisions/caching.md the measurements). On OpenAI Responses
+	// models with native tool loading (GPT-5.4 and newer on openai and
+	// openai-codex) a loaded tool leaves `tools` for pi-ai's own load item at the
+	// tool_search result instead (stabilizeResponsesToolLoads). Inside an epoch
+	// the request carries only its tail here: the ledger's payload hook, later,
+	// puts the recorded list in front and keeps the recorded tools.
+	pi.on("before_provider_request", (event, ctx) => {
+		const allTools = pi.getAllTools();
+		const enabled = deferralEnabled(allTools);
+		const toolLoadCompat = responsesToolLoadCompat(ctx.model as ResponsesToolLoadModel | undefined);
+		if (toolLoadCompat) {
+			if (!enabled) return undefined;
+			return stabilizeResponsesToolLoads(event.payload as Record<string, unknown>, (name) => deferredRegistry.has(name), loads, toolLoadCompat);
+		}
+		const original = event.payload as Record<string, unknown>;
+		const additions = supportsToolAdditions(ctx.model) && looksLikeAnthropicRequest(original);
+		// The context step lifted this request's addenda off their tool results;
+		// whatever happens below, they go out (lib/tool-additions.ts).
+		const announceAsText = () => {
+			const text = additions ? withToolAdditions(original, addendaByCall, false) : undefined;
+			return text ? withBetas(text.payload, [MID_CONVERSATION_SYSTEM_BETA]) : undefined;
+		};
+		if (!enabled || !supportsToolReferences(ctx.model as { provider?: string; id?: string } | undefined) || !looksLikeAnthropicRequest(original)) return announceAsText();
+		const isDeferred = (name: string) => deferredRegistry.has(name);
+		// A tool that arrived mid-session goes out as Claude Code's tool_addition
+		// where the model takes one, declared deferred.
+		const lifted = additions ? withToolAdditions(original, addendaByCall) : undefined;
+		const stable = stabilizeDeferredTools(lifted?.payload ?? original, allTools, isDeferred, loads, new Set(lifted?.names ?? []));
+		// Renamed (OAuth) tools cannot be referenced: the active tools stay as pi
+		// rendered them and the addition goes as text.
+		if (!stable) return announceAsText();
+		return lifted ? withBetas(stable, TOOL_ADDITION_BETAS) : stable;
+	});
+
+	pi.events.on(DEFERRED_QUERY_CHANNEL, (data) => {
+		const query = data as DeferredQuery;
+		for (const name of deferredRegistry.names) query.tools.push({ name, keywords: deferredRegistry.keywordsFor(name) });
+	});
 
 	pi.events.on(DEFER_CHANNEL, (data) => {
 		const request = data as DeferRequest;
 		deferredRegistry.add(request);
+		// A withheld tool brought back is deferred again.
+		if (request?.name) withheldNames.delete(request.name);
 		// A defer arriving after the session_start pass (MCP servers connect
 		// asynchronously and register their tools then) would otherwise leave the
-		// tool eager AND unlisted in the reminder. Deactivate it (unless the
-		// transcript loaded it) and refresh the keyed reminder.
-		if (sessionStarted && request?.name) {
-			const active = pi.getActiveTools();
-			if (active.includes(request.name) && !loadedBefore.has(request.name)) {
-				pi.setActiveTools(active.filter((name) => name !== request.name));
-			}
-			// The tool is searchable (keyword search reads the registry) from now;
-			// only the standing listing waits.
-			scheduleAnnounce();
+		// tool eager AND unlisted.
+		if (sessionStarted && request?.name && deferring() && alive()) {
+			reconcileNow();
+			publishListing();
 		}
 	});
 
+	pi.events.on(WITHHOLD_CHANNEL, (data) => {
+		const name = (data as { name?: string } | undefined)?.name;
+		if (!name || !deferredRegistry.remove(name)) return;
+		withheldNames.add(name);
+		if (!alive()) return;
+		reconcileNow();
+		publishListing();
+	});
+
+	// A /tree switch keeps the process: pi restored the selected branch's
+	// loadout, and the selected branch decides which deferred tools are callable
+	// and referenced there.
+	pi.on("session_tree", (_event, ctx) => {
+		freshLoads.clear();
+		reconcile(ctx?.sessionManager, ctx?.model ?? currentModel);
+	});
+
 	pi.on("session_start", (_event, ctx) => {
 		sessionStarted = true;
-		// A pending debounce belongs to the previous session's listing (RPC's
-		// new_session emits session_start twice, findings §3); deferAll below
-		// announces the fresh one.
-		clearAnnounce();
-		loads = toolSearchLoads(ctx?.sessionManager?.getBranch?.() ?? []);
-		loadedBefore = new Set([...loads.values()].flat());
-		// A new session (/clear, or a resume in a new process) has no cached prefix
-		// yet: its first request gets a freshly written listing.
-		requestSent = false;
-		announced.clear();
-		deferAll();
+		currentModel = ctx?.model;
+		session = ctx?.sessionManager;
+		freshLoads.clear();
+		reconcileNow();
+		publishListing();
+	});
+	pi.on("model_select", (event) => {
+		currentModel = event.model;
+		reconcileNow();
+	});
+	// Every turn's tools are fixed right after this (pi's prepareRequest): the
+	// tools the request announces callable must be active by then.
+	pi.on("turn_start", (_event, ctx) => {
+		freshLoads.clear();
+		if (ctx?.model) currentModel = ctx.model;
+		reconcileNow();
 	});
 
-	pi.on("session_shutdown", clearAnnounce);
+	// A compaction opens an epoch, which lists every deferred tool again. The
+	// loads that named a loaded tool went with the summary: the tool goes back to
+	// deferred, so the new epoch declares it the way it declares the rest (Claude
+	// Code declares a deferred tool only while a reference to it is in the
+	// history), unless the reconciler keeps it.
+	pi.on("session_compact", (_event, ctx) => {
+		reconcile(ctx?.sessionManager, ctx?.model ?? currentModel);
+		publishListing();
+	});
 
 	// The every-turn deferred-tools list tells the model to load via tool_search,
 	// but if it calls a deferred tool directly anyway, pi's core dispatcher fails
@@ -228,15 +395,34 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		// Map a Claude Code spelling (a direct `NotebookEdit` call) to our name so
 		// the miss is recognised and the steer names the loadable tool (M1).
 		const name = raw ? normalizeToolName(raw) : undefined;
-		if (!name || !deferredRegistry.has(name)) return;
-		pi.events.emit(REMINDER_CHANNEL, {
-			scope: "next-turn",
-			key: `deferred-miss-${name}`,
-			text: deferredMissReminderText(name),
-		});
+		if (!name) return;
+		// Without tool_search there is nothing to steer a deferred-tool miss to.
+		if (deferredRegistry.has(name) && deferring()) {
+			pi.events.emit(REMINDER_CHANNEL, {
+				key: `deferred-miss-${name}`,
+				text: deferredMissReminderText(name),
+			});
+		} else if (withheldNames.has(name)) {
+			// A withheld tool is gone from the registry too (WITHHOLD_CHANNEL), so
+			// the ordinary steer above would send the model to tool_search for a
+			// name that will not be found there either.
+			pi.events.emit(REMINDER_CHANNEL, {
+				key: `deferred-miss-${name}`,
+				text: withheldMissReminderText(name),
+			});
+		} else if (session && recordedToolNames(foldOf(session, branchOf(session), currentModel).lastRequest ?? { head: {}, list: [] }).has(name)) {
+			// The epoch's recorded tools stay declared after the tool left the
+			// session (a setting turned it off): the call cannot be salvaged, and
+			// the model must not keep trying it.
+			pi.events.emit(REMINDER_CHANNEL, {
+				key: `deferred-miss-${name}`,
+				text: unavailableToolReminderText(name),
+			});
+		}
 	});
 
 	pi.registerTool({
+		// A literal, like every registration: agent-view-tool-labels.test.ts reads them from source.
 		name: "tool_search",
 		label: "Tool Search",
 		...ccToolRenderers("Tool Search"),
@@ -257,14 +443,34 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 			// silently dropped before — the model was told the rest "Loaded" and only
 			// discovered the miss later as an opaque InputValidationError. Always
 			// surface the unmatched names.
-			const requested = selectedNames(params.query);
-			const notFound = requested
-				? requested.filter((n) => !matches.some((m) => m.name.toLowerCase() === n))
+			const requested = selectedRequests(params.query);
+			// A requested tool that is already callable (an eager tool, or one loaded
+			// earlier) is a harmless no-op, as in Claude Code: the model proceeds
+			// instead of retrying a name it was told does not exist.
+			const active = pi.getActiveTools();
+			const alreadyActive = (name: string) => active.find((tool) => tool.toLowerCase() === name);
+			const unmatched = requested
+				? requested.filter((request) => !matches.some((m) => m.name.toLowerCase() === request.name))
 				: [];
+			const eager = [...new Set(unmatched.flatMap((request) => alreadyActive(request.name) ?? []))];
+			const notFound = unmatched.filter((request) => !alreadyActive(request.name));
+			// A withheld name can still sit in the frozen listing (withdrawn by a model
+			// change after the first request), so it gets "do not retry", not a
+			// spelling hint. Both notes quote the model's own spelling.
+			const withdrawn = [...new Set(notFound.filter((n) => withheldNames.has(n.name)).map((n) => n.asWritten))];
+			const missing = [...new Set(notFound.filter((n) => !withheldNames.has(n.name)).map((n) => n.asWritten))];
 			const notFoundNote =
-				notFound.length > 0
-					? ` Not found (not deferred tool names — check spelling, or search by keyword instead of \`select:\`): ${notFound.join(", ")}.`
-					: "";
+				(missing.length > 0
+					? ` Not found (not deferred tool names — check spelling, or search by keyword instead of \`select:\`): ${missing.join(", ")}.`
+					: "") +
+				(withdrawn.length > 0 ? ` Withdrawn for the current model (do not retry): ${withdrawn.join(", ")}.` : "");
+
+			if (matches.length === 0 && eager.length > 0) {
+				return {
+					content: [{ type: "text", text: `Already loaded: ${eager.join(", ")}.${notFoundNote}` }],
+					details: { matches: eager, added: [] as string[], notFound, refused: [] as string[] },
+				};
+			}
 
 			if (matches.length === 0) {
 				const names = available.map((t) => t.name).join(", ") || "(none)";
@@ -272,30 +478,42 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 					content: [
 						{ type: "text", text: `No tools matched "${params.query}".${notFoundNote} Tools that can be loaded: ${names}` },
 					],
-					details: { matches: [] as string[], added: [] as string[], notFound },
+					details: { matches: [] as string[], added: [] as string[], notFound, refused: [] as string[] },
 					isError: true,
 				};
 			}
 
-			const active = pi.getActiveTools();
-			const added = matches.map((m) => m.name).filter((name) => !active.includes(name));
+			const matchNames = matches.map((m) => m.name);
+			const toActivate = matchNames.filter((name) => !active.includes(name));
+			if (toActivate.length > 0) pi.setActiveTools([...new Set([...active, ...toActivate])]);
+			// pi can decline to activate a tool: since 1.0.4 a `--tools` list that
+			// names no `mcp__*` entry keeps the MCP tools registered but not
+			// activatable. Report what pi actually activated, never a plausible load.
+			const now = new Set(pi.getActiveTools());
+			const added = toActivate.filter((name) => now.has(name));
+			const refused = toActivate.filter((name) => !now.has(name));
 			if (added.length > 0) {
-				pi.setActiveTools([...new Set([...active, ...added])]);
+				freshLoads.set(toolCallId, added);
 				loads.set(toolCallId, added);
 			}
 
-			const loaded = matches.map((m) => m.name);
+			const loaded = [...new Set([...matchNames, ...eager])].filter((name) => now.has(name));
+			const already = loaded.filter((name) => !added.includes(name));
+			const refusedNote =
+				refused.length > 0 ? ` Could not load ${refused.join(", ")}: this session's tool list (pi's --tools) leaves them out, so they cannot be called.` : "";
 			return {
 				content: [
 					{
 						type: "text",
 						text:
-							(added.length > 0
-								? `Loaded ${added.join(", ")}. These tools are now callable.`
-								: `Already loaded: ${loaded.join(", ")}.`) + notFoundNote,
+							([
+								added.length > 0 ? `Loaded ${added.join(", ")}. These tools are now callable.` : "",
+								already.length > 0 ? `Already loaded: ${already.join(", ")}.` : "",
+							].filter(Boolean).join(" ") + refusedNote + notFoundNote).trim(),
 					},
 				],
-				details: { matches: loaded, added, notFound },
+				details: { matches: loaded, added, notFound, refused },
+				isError: loaded.length === 0,
 			};
 		},
 	});
@@ -303,6 +521,10 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 	registerLocalCommand(pi, "tools-deferred", {
 		description: "Show which tools are deferred (loadable via tool_search)",
 		handler: async (args, ctx) => {
+			if (!deferring()) {
+				ctx.ui.notify("tool_search is not registered (a --tools list leaves it out), so no tool is deferred.", "info");
+				return;
+			}
 			const available = searchableTools();
 			const activeSet = new Set(pi.getActiveTools());
 			const lines = available.map((t) => `${activeSet.has(t.name) ? "loaded " : "deferred"} ${t.name}`);