one-code-extension 0.4.0 → 0.5.0

package/extensions/tool-call-corruption/index.ts

@@ -0,0 +1,237 @@
+/** Reject damaged OpenRouter streams before tool execution, without changing the request prefix. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { notifyOrPrint } from "../lib/headless-output.ts";
+import { TURN_FAILED_CHANNEL, type TurnFailedEvent } from "../lib/interrupt.ts";
+import { sessionOutlivesTurn } from "../lib/notifications.ts";
+import { isOpenRouter, openRouterProviderName, toolCallCorruptionNotice, type UpstreamFailure } from "../lib/openrouter-generation.ts";
+import { sessionAlive } from "../lib/session-lifecycle.ts";
+import {
+	CONTENT_MARKUP_LIMIT,
+	RUNAWAY_PADDING_LIMIT,
+	scanToolCallMarkup,
+	TOOL_CALL_MARKUP_LIMIT,
+	type ToolCallDamage,
+	type TrailingPadding,
+	toolCallCorruptionReason,
+	trailingPadding,
+} from "../lib/tool-call-corruption.ts";
+import { withKeepAlive } from "../lsp/keep-alive.ts";
+
+// Silence allowed inside a stream. Every raw chunk restarts the clock, but
+// OpenRouter's keepalive comments never reach us, so a model thinking
+// server-side before its first token looks silent: that wait is long. After
+// the first content it is Claude Code's 90 s watchdog, and 60 s while a tool
+// call's arguments stream (arguments never pause for thinking).
+const FIRST_CONTENT_IDLE_MS = 300_000;
+const STREAM_IDLE_MS = 90_000;
+const TOOL_CALL_IDLE_MS = 60_000;
+
+export default function toolCallCorruptionExtension(pi: ExtensionAPI) {
+	toolCallCorruptionGuard(pi, { announce: true });
+}
+
+/**
+ * The guard itself. `announce: false` is the in-process child's shape
+ * (`child.ts`): it blocks and stops the same way, but a child has no terminal
+ * of its own (stderr is the parent's TUI) and is disposed without
+ * `session_shutdown`, so it prints nothing and starts no provider lookup that
+ * could outlive it. Its parent sees the child's turn end terminated.
+ */
+export function toolCallCorruptionGuard(pi: ExtensionAPI, { announce }: { announce: boolean }) {
+	const alive = sessionAlive(pi);
+	const rawCalls = new Map<number, { raw: string; markup: number; contentMarkup: number; next: number }>();
+	const flagged = new Map<string, ToolCallDamage>();
+	// Any provider: a call streaming blank padding without end never reaches
+	// toolcall_end, and nothing else stops it (gpt-6.1-sol, battery round 7:
+	// 26 MB of tabs and newlines over 25 minutes in a one-shot run).
+	const padding = new Map<number, TrailingPadding>();
+	const pending = new Map<AbortController, Promise<void>>();
+	let responseId: string | undefined;
+	// OpenRouter names the serving provider on every chunk; a cancelled
+	// generation is never recorded, so the lookup cannot name it after a stop.
+	let streamProvider: string | undefined;
+	let stopped = false;
+	// A suspect call goes back to the model once per run; the next one is corrupt.
+	let suspectReturned = false;
+	let contentStarted = false;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let idleMs = 0;
+
+	const clearIdle = () => {
+		clearTimeout(idleTimer);
+		idleTimer = undefined;
+	};
+	const resetMessage = () => {
+		rawCalls.clear();
+		flagged.clear();
+		padding.clear();
+		responseId = undefined;
+		streamProvider = undefined;
+		contentStarted = false;
+		clearIdle();
+	};
+	const resetRun = () => {
+		resetMessage();
+		stopped = false;
+		suspectReturned = false;
+	};
+	const cancelLookups = () => {
+		for (const controller of pending.keys()) controller.abort();
+		pending.clear();
+	};
+
+	/** Abort the turn once and tell the user which upstream provider failed. */
+	const stopTurn = (ctx: ExtensionContext, failure: UpstreamFailure) => {
+		if (stopped || !alive()) return;
+		stopped = true;
+		clearIdle();
+		const what = typeof failure === "object" ? `stalled ${failure.stalledSeconds} s` : failure;
+		pi.events.emit(TURN_FAILED_CHANNEL, { reason: `OpenRouter upstream failure: ${what}` } satisfies TurnFailedEvent);
+		ctx.abort();
+		if (!announce) return;
+		const model = ctx.model!;
+		const registry = ctx.modelRegistry;
+		const output = { hasUI: ctx.hasUI, ui: ctx.ui };
+		const controller = new AbortController();
+		const named = streamProvider;
+		const notice = withKeepAlive(async () => {
+			const provider = named ?? await openRouterProviderName(responseId, async () => {
+				const auth = await registry.getApiKeyAndHeaders(model);
+				return auth.ok ? auth.apiKey : undefined;
+			}, controller.signal);
+			if (alive() && !controller.signal.aborted) notifyOrPrint(output, toolCallCorruptionNotice(model.id, provider, failure), "error");
+		}).finally(() => pending.delete(controller));
+		pending.set(controller, notice);
+	};
+	/** (Re)start the silence clock; a call still streaming arguments keeps the short window. */
+	const armIdle = (ctx: ExtensionContext) => {
+		if (stopped) return clearIdle();
+		const ms = rawCalls.size > 0 ? TOOL_CALL_IDLE_MS : contentStarted ? STREAM_IDLE_MS : FIRST_CONTENT_IDLE_MS;
+		if (idleTimer && ms === idleMs) {
+			idleTimer.refresh();
+			return;
+		}
+		clearIdle();
+		idleMs = ms;
+		idleTimer = setTimeout(() => {
+			idleTimer = undefined;
+			try {
+				stopTurn(ctx, { stalledSeconds: ms / 1000 });
+			} catch {
+				// A child session disposed mid-stream (no session_shutdown): its ctx throws, and there is nothing left to stop.
+			}
+		}, ms);
+		idleTimer.unref?.();
+	};
+
+	pi.on("session_start", () => {
+		cancelLookups();
+		resetRun();
+	});
+	pi.on("session_shutdown", () => {
+		cancelLookups();
+		resetRun();
+	});
+	pi.on("agent_start", resetRun);
+	pi.on("message_start", (event, ctx) => {
+		if (event.message.role !== "assistant") return;
+		resetMessage();
+		if (alive() && isOpenRouter(ctx.model)) armIdle(ctx);
+	});
+
+	pi.on("provider_stream_event", (event, ctx) => {
+		if (!alive() || !isOpenRouter(ctx.model)) return;
+		const provider = (event.data as { provider?: unknown } | null)?.provider;
+		if (typeof provider === "string" && provider.trim()) streamProvider = provider.trim();
+		// Any chunk is a sign of life, content or not (reasoning details, usage, an empty delta).
+		if (idleTimer) armIdle(ctx);
+	});
+
+	pi.on("message_update", (event, ctx) => {
+		const update = event.assistantMessageEvent;
+		if (!alive() || stopped || update.type !== "toolcall_delta") return;
+		const state = trailingPadding(padding.get(update.contentIndex), update.delta);
+		padding.set(update.contentIndex, state);
+		if (!state.structural || state.run < RUNAWAY_PADDING_LIMIT) return;
+		stopped = true;
+		clearIdle();
+		const reason = `The model streamed over ${RUNAWAY_PADDING_LIMIT.toLocaleString("en-US")} characters of blank space into a tool call's arguments without finishing it, so the turn was stopped.`;
+		pi.events.emit(TURN_FAILED_CHANNEL, { reason } satisfies TurnFailedEvent);
+		ctx.abort();
+		if (announce) notifyOrPrint({ hasUI: ctx.hasUI, ui: ctx.ui }, `${reason} Send the request again, or switch models if it repeats.`, "error");
+	});
+
+	pi.on("message_update", (event, ctx) => {
+		if (!alive() || !isOpenRouter(ctx.model)) return;
+		const update = event.assistantMessageEvent;
+		if (!("partial" in update)) return;
+		responseId = update.partial.responseId || responseId;
+		contentStarted = true;
+		switch (update.type) {
+			case "toolcall_start":
+				rawCalls.set(update.contentIndex, { raw: "", markup: 0, contentMarkup: 0, next: 0 });
+				break;
+			case "toolcall_delta": {
+				const call = rawCalls.get(update.contentIndex) ?? { raw: "", markup: 0, contentMarkup: 0, next: 0 };
+				call.raw += update.delta;
+				const scan = scanToolCallMarkup(call.raw, call.next);
+				call.markup += scan.count;
+				call.contentMarkup += scan.contentCount;
+				call.next = scan.next;
+				rawCalls.set(update.contentIndex, call);
+				// A leaked call can stream markup without end and never reach toolcall_end.
+				if (call.markup >= TOOL_CALL_MARKUP_LIMIT || call.contentMarkup >= CONTENT_MARKUP_LIMIT) return stopTurn(ctx, "corrupt-stream");
+				break;
+			}
+			case "toolcall_end": {
+				const raw = rawCalls.get(update.contentIndex)?.raw;
+				rawCalls.delete(update.contentIndex);
+				if (raw === undefined) break;
+				const damage = toolCallCorruptionReason(update.toolCall.name, raw);
+				if (damage) flagged.set(update.toolCall.id, damage);
+				break;
+			}
+		}
+		armIdle(ctx);
+	});
+	pi.on("message_end", (event, ctx) => {
+		if (event.message.role === "assistant") clearIdle();
+		if (alive() && isOpenRouter(ctx.model) && event.message.role === "assistant") {
+			responseId = event.message.responseId || responseId;
+			// A reply cut off at the token limit ends mid-call: the damage to its
+			// last block is the limit's, not the provider's. A call completed
+			// before it was judged whole and stays blocked.
+			const last = event.message.stopReason === "length" ? event.message.content.at(-1) : undefined;
+			if (last?.type === "toolCall") flagged.delete(last.id);
+		}
+	});
+	pi.on("tool_call", (event, ctx) => {
+		if (!alive() || !isOpenRouter(ctx.model)) return;
+		const damage = flagged.get(event.toolCallId);
+		if (!damage) return;
+		if (damage.kind === "suspect" && !suspectReturned) {
+			suspectReturned = true;
+			flagged.delete(event.toolCallId);
+			return { block: true, reason: `${damage.reason} It was not run. Send the complete command again; if it really ends there, drop the trailing blank or the empty option.` };
+		}
+		const repeat = damage.kind === "suspect" ? " An earlier command in this run came through cut the same way." : "";
+		flagged.set(event.toolCallId, { kind: "corrupt", reason: damage.reason });
+		return {
+			block: true,
+			reason: `OpenRouter tool-call corruption: ${damage.reason}${repeat} Do not retry this call; switch models or exclude the upstream provider.`,
+			terminate: true,
+		};
+	});
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (!alive() || stopped || !isOpenRouter(ctx.model) || flagged.get(event.toolCallId)?.kind !== "corrupt") return;
+		// Aborting inside tool_call would replace our reason with "Operation aborted".
+		// This also catches schema-validation failures, which bypass tool_call entirely.
+		stopTurn(ctx, "blocked-call");
+	});
+	pi.on("agent_end", async (_event, ctx) => {
+		clearIdle();
+		// Print/JSON dispose the session immediately after agent_end. The turn is
+		// already aborted; flush its bounded diagnostic before one-shot teardown.
+		if (!sessionOutlivesTurn(ctx.mode)) await Promise.all(pending.values());
+	});
+}

package/extensions/tool-search/announce.ts

@@ -31,6 +31,22 @@ export function planAnnouncement(input: {
 	return added.length === 0 ? { kind: "none" } : { kind: "addendum", added };
 }
 
+/** JSON-safe persisted baseline for the names already described to the model. */
+export function deferredToolsBaseline(value: unknown): string[] | undefined {
+	if (!Array.isArray(value) || !value.every((name) => typeof name === "string")) return undefined;
+	return [...new Set(value)];
+}
+
+/** Compatibility fallback for a v1 stack written before structured baselines. */
+export function deferredToolsFromReminder(text: string | undefined): string[] | undefined {
+	if (!text) return undefined;
+	const marker = "\n";
+	const lines = text.split(marker);
+	return lines.length > 1 && lines[0].startsWith("The following deferred tools are available via tool_search")
+		? lines.slice(1).filter(Boolean)
+		: undefined;
+}
+
 /** Bring the announced set in line with what the plan told the model. */
 export function applyAnnouncement(announced: Set<string>, plan: AnnouncementPlan): void {
 	if (plan.kind === "rewrite") {

package/extensions/tool-search/index.ts

@@ -33,23 +33,32 @@ import {
 	deferredAddendumText,
 	deferredMissReminderText,
 	DeferredRegistry,
+	deferralEnabled,
 	deferredReminderText,
+	loaderUnavailableReminderText,
 	type DeferRequest,
 	resultText,
 	searchTools,
-	selectedNames,
+	selectedRequests,
+	type ResponsesToolLoadModel,
 	stabilizeDeferredTools,
+	stabilizeResponsesToolLoads,
+	responsesToolLoadCompat,
 	supportsToolReferences,
 	toolNotFoundName,
 	toolSearchLoads,
+	WITHHOLD_CHANNEL,
+	withheldMissReminderText,
 } from "../lib/deferred.ts";
-import { looksLikeAnthropicRequest } from "../lib/anthropic-payload.ts";
+import { looksLikeAnthropicRequest, MID_CONVERSATION_SYSTEM_BETA, withBetas } from "../lib/anthropic-payload.ts";
+import { addendumNamesOnBranch, liftAddenda, supportsToolAdditions, TOOL_ADDITION_BETAS, withToolAdditions } from "../lib/tool-additions.ts";
 import { MCP_TOOLS_CHANNEL, type McpToolsPayload } from "../lib/mcp-share.ts";
 import { CONTEXT_ORDER, REMINDER_CHANNEL } 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 { applyAnnouncement, deferredToolsBaseline, deferredToolsFromReminder, planAnnouncement } from "./announce.ts";
+import { CONTEXT_BASELINE_CHANNEL, restoredContext } from "../lib/context-stack.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
 
 /** Coalesces the burst of per-tool defers one server emits into one listing update. */
@@ -58,6 +67,12 @@ const ANNOUNCE_DEBOUNCE_MS = 100;
 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
@@ -77,21 +92,36 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 	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 model as last seen, for an announcement made outside any hook. */
+	let latestModel: { provider?: string; api?: string; compat?: unknown } | undefined;
 
-	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 = () => {
+		const 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 publishBaseline = (names: ReadonlySet<string>) => {
+		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "tool-search", value: [...names] });
+	};
 	const announce = () => {
 		if (!alive()) return;
 		const available = searchableTools();
 		const plan = planAnnouncement({ requestSent, announced, available: available.map((t) => t.name) });
+		// Store the post-announcement state before the next context pass can place it.
+		if (plan.kind !== "none") {
+			const next = new Set(announced);
+			applyAnnouncement(next, plan);
+			publishBaseline(next);
+		}
 		if (plan.kind === "rewrite") {
 			pi.events.emit(REMINDER_CHANNEL, {
 				scope: "every-turn",
@@ -104,6 +134,12 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 			// 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) });
+			// Where the request carries it as Claude Code's tool_addition, the model
+			// calls the tool directly, so pi's dispatcher must already accept it.
+			if (supportsToolAdditions(latestModel)) {
+				for (const name of plan.added) loadedBefore.add(name);
+				pi.setActiveTools([...new Set([...pi.getActiveTools(), ...plan.added])]);
+			}
 		}
 		applyAnnouncement(announced, plan);
 	};
@@ -137,8 +173,15 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("context", () => {
+	/** 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) => {
 		requestSent = true;
+		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
@@ -162,18 +205,44 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 	// 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).
+	// 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).
 	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);
+		latestModel = ctx.model;
+		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;
 	});
 
 
 	/** Deactivate every deferred-registry tool the transcript has not loaded, and announce the loadable set. */
 	const deferAll = () => {
 		const deferred = new Set(deferredRegistry.names);
-		if (deferred.size === 0) return;
+		if (deferred.size === 0 || !deferring()) return;
 		const active = pi.getActiveTools();
 		const next = active.filter((name) => !deferred.has(name) || loadedBefore.has(name));
 		if (next.length !== active.length) pi.setActiveTools(next);
@@ -183,11 +252,12 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 	pi.events.on(DEFER_CHANNEL, (data) => {
 		const request = data as DeferRequest;
 		deferredRegistry.add(request);
+		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) {
+		if (sessionStarted && request?.name && deferring()) {
 			const active = pi.getActiveTools();
 			if (active.includes(request.name) && !loadedBefore.has(request.name)) {
 				pi.setActiveTools(active.filter((name) => name !== request.name));
@@ -198,19 +268,51 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		}
 	});
 
+	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;
+		const active = pi.getActiveTools();
+		if (active.includes(name)) pi.setActiveTools(active.filter((n) => n !== name));
+		// Before the first request the listing is still free to change: rewrite it
+		// now, synchronously, so a request going out right after session_start
+		// never names the withheld tool. After it the frozen listing stands.
+		if (sessionStarted && !requestSent) announce();
+	});
+
 	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?.() ?? []);
+		latestModel = ctx?.model;
+		const branch = ctx?.sessionManager?.getBranch?.() ?? [];
+		loads = toolSearchLoads(branch);
 		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;
+		// Tools added mid-session by tool_addition stay callable after a resume.
+		if (supportsToolAdditions(latestModel)) for (const name of addendumNamesOnBranch(branch)) loadedBefore.add(name);
+		const restored = restoredContext(pi.events);
+		// A restored stack is already message 1. Seed its announced names so a live
+		// capability change becomes one addendum, not a rewrite or duplicate notice.
+		requestSent = restored !== undefined;
 		announced.clear();
+		const baseline = deferredToolsBaseline(restored?.baselines["tool-search"]);
+		const legacy = deferredToolsFromReminder(restored?.stack.find((entry) => (entry as { key?: string }).key === "deferred-tools")?.text);
+		for (const name of baseline ?? legacy ?? []) announced.add(name);
+		// Native tool_addition entries can outlive an older baseline snapshot; they
+		// already told the model about these names, so merge them before planning.
+		for (const name of addendumNamesOnBranch(branch)) announced.add(name);
 		deferAll();
+		// A restored message 1 keeps its listing (its bytes are locked), so when
+		// this run's tool list leaves tool_search out, say once that it is gone.
+		if (restored && announced.size > 0 && !deferring()) {
+			pi.events.emit(REMINDER_CHANNEL, { scope: "next-turn", key: "deferred-unavailable", text: loaderUnavailableReminderText() });
+		}
+		// Even an absent listing is meaningful on resume: preserve that baseline so
+		// the first later deferred tool is a tail notice, not a message-1 rewrite.
+		if (!restored) publishBaseline(announced);
 	});
 
 	pi.on("session_shutdown", clearAnnounce);
@@ -228,15 +330,28 @@ 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, {
+				scope: "next-turn",
+				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, {
+				scope: "next-turn",
+				key: `deferred-miss-${name}`,
+				text: withheldMissReminderText(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 +372,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 +407,39 @@ 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));
-			if (added.length > 0) {
-				pi.setActiveTools([...new Set([...active, ...added])]);
-				loads.set(toolCallId, added);
-			}
+			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) 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 +447,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}`);