one-code-extension 0.5.0 → 0.6.0

package/extensions/tool-search/index.ts

@@ -26,7 +26,7 @@
  * 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,
@@ -47,22 +47,37 @@ import {
 	supportsToolReferences,
 	toolNotFoundName,
 	toolSearchLoads,
+	toolsInUse,
+	callableDeferredTools,
+	reconcileActive,
 	WITHHOLD_CHANNEL,
+	DEFERRED_QUERY_CHANNEL,
+	type DeferredQuery,
+	deferredRemovedText,
 	withheldMissReminderText,
+	unavailableToolReminderText,
 } from "../lib/deferred.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 { 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, 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. */
-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.
@@ -74,31 +89,24 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 	// 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 model as last seen, for an announcement made outside any hook. */
-	let latestModel: { provider?: string; api?: string; compat?: unknown } | undefined;
+	/** 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));
 
 	/** 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();
+	const searchableTools = (all = pi.getAllTools()) => {
 		if (!deferralEnabled(all)) return [];
 		return all
 			.filter((tool) => deferredRegistry.has(tool.name))
@@ -109,74 +117,80 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 			}));
 	};
 
-	const publishBaseline = (names: ReadonlySet<string>) => {
-		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "tool-search", value: [...names] });
-	};
-	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) });
-		// 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 (available.length === 0) {
+			pi.events.emit(REMINDER_CHANNEL, { key: "deferred-tools", remove: true });
+			return;
 		}
-		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) });
-			// 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);
-	};
-
-	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 }] });
 	});
 
 	/** 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);
@@ -184,33 +198,97 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		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>();
+	/** 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;
+	};
+
+	/**
+	 * 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);
+		// 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 = 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) 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; 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).
+	// 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) => {
-		latestModel = ctx.model;
 		const allTools = pi.getAllTools();
 		const enabled = deferralEnabled(allTools);
 		const toolLoadCompat = responsesToolLoadCompat(ctx.model as ResponsesToolLoadModel | undefined);
@@ -238,33 +316,22 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		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 || !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);
-		announce();
-	};
+	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 && deferring()) {
-			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();
 		}
 	});
 
@@ -273,49 +340,47 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		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();
+		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();
-		latestModel = ctx?.model;
-		const branch = ctx?.sessionManager?.getBranch?.() ?? [];
-		loads = toolSearchLoads(branch);
-		loadedBefore = new Set([...loads.values()].flat());
-		// 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);
+		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
@@ -334,7 +399,6 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		// 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),
 			});
@@ -343,10 +407,17 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 			// 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),
 			});
+		} 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),
+			});
 		}
 	});
 
@@ -421,7 +492,10 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 			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);
+			if (added.length > 0) {
+				freshLoads.set(toolCallId, added);
+				loads.set(toolCallId, added);
+			}
 
 			const loaded = [...new Set([...matchNames, ...eager])].filter((name) => now.has(name));
 			const already = loaded.filter((name) => !added.includes(name));

package/extensions/workflow/agent-session.ts

@@ -41,6 +41,7 @@ import { withoutUnusable } from "../lib/model-unusable.ts";
 import { cleanupWorktree, createWorktree, isGitRepo, type Worktree } from "../subagents/worktree.ts";
 import type { AgentCallOptions, AgentCallResult, AgentEffort, AgentRunUpdate, KeptWorktree } from "./types.ts";
 import { WorkflowScriptError } from "./types.ts";
+import { type DeferRequest, deferLikeParentExtension, injectedByParent } from "../lib/deferred.ts";
 
 const MAX_SCHEMA_RETRIES = 2;
 const OUTPUT_CAP = 50_000;
@@ -78,6 +79,8 @@ export interface AgentRunnerOptions {
 	 * as custom tools over the parent's connections, as the subagent runner does.
 	 */
 	getMcpTools?: () => ToolDefinition[] | Promise<ToolDefinition[]>;
+	/** The tools the parent defers (lib/deferred.ts DEFERRED_QUERY_CHANNEL): the agent defers them too, so its MCP tools are listed, not declared. */
+	getParentDeferred?: () => DeferRequest[];
 	/** Where an answer past OUTPUT_CAP is saved (`<dir>/tool-results/`): the run's directory. */
 	resultsDir?: string;
 }
@@ -299,7 +302,7 @@ export class AgentRunner {
 				extraExtensionPaths: CHILD_EXTENSION_PATHS,
 				// claude-context (a child extension) injects the CLAUDE.md instructions itself.
 				noContextFiles: true,
-				...(handback ? { extraFactories: [subagentHandbackExtension(handback)] } : {}),
+				extraFactories: [deferLikeParentExtension(this.options.getParentDeferred?.() ?? [], injectedByParent([])), ...(handback ? [subagentHandbackExtension(handback)] : [])],
 				getPermissionBridge: this.options.getPermissionBridge,
 				getHookBridge: this.options.getHookBridge,
 			},

package/extensions/workflow/index.ts

@@ -76,6 +76,7 @@ import { isKeyRelease, keyId } from "../lib/key-input.ts";
 import { projectConfigDirName } from "../lib/config-mode.ts";
 import { panelUi } from "../lib/panel-focus.ts";
 import { dockRowsReporter, trackDockRows } from "../lib/dock-rows.ts";
+import { queryDeferred } from "../lib/deferred.ts";
 
 /**
  * Claude Code's own arming reminder, verbatim in intent: the keyword is a
@@ -268,6 +269,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
 					getPermissionBridge,
 					getHookBridge,
 					getMcpTools,
+					getParentDeferred: () => queryDeferred(pi.events),
 					// Workflow agents run in their own sessions; their spend reaches the footer only through the bus.
 					onUsage: (cost) => recordUsage(pi, "subagent", { cost: { total: cost } }),
 					unusableModels: () => unusableModels,
@@ -342,15 +344,21 @@ export default function workflowExtension(pi: ExtensionAPI) {
 	// comes back if a later session turns it on) and the keyword arms nothing.
 	let workflowsEnabled = true;
 	let workflowWithheld = false;
+	/** Take the tool out of the active set while workflows are off; true when it was active. */
+	const withholdIfOff = (): boolean => {
+		const active = pi.getActiveTools();
+		if (workflowsEnabled || !active.includes("workflow")) return false;
+		pi.setActiveTools(active.filter((name) => name !== "workflow"));
+		return true;
+	};
 	const applyWorkflowSettings = (cwd: string) => {
 		const settings = readWorkflowSettings(cwd, os.homedir());
 		workflowsEnabled = settings.enabled;
 		setWorkflowDescription(workflowDescription(settings.sizeGuideline, settings.sizeConfigured));
-		const active = pi.getActiveTools();
-		if (!settings.enabled && active.includes("workflow")) {
-			pi.setActiveTools(active.filter((name) => name !== "workflow"));
+		if (withholdIfOff()) {
 			workflowWithheld = true;
 		} else if (settings.enabled && workflowWithheld) {
+			const active = pi.getActiveTools();
 			if (!active.includes("workflow")) pi.setActiveTools([...active, "workflow"]);
 			workflowWithheld = false;
 		}
@@ -427,7 +435,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
 	pi.on("input", (event) => {
 		if (!workflowsEnabled || ultracodeMode || !/\bultracode\b/i.test(event.text)) return undefined;
 		if (event.streamingBehavior) queuedKeyword.hold(event.text, true);
-		else pi.events.emit(REMINDER_CHANNEL, { text: ULTRACODE_REMINDER, scope: "next-turn" });
+		else pi.events.emit(REMINDER_CHANNEL, { text: ULTRACODE_REMINDER });
 		return undefined;
 	});
 	pi.on("message_start", (event) => {
@@ -513,6 +521,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
 		applyWorkflowSettings(ctx.cwd);
 		registerInputHook(ctx);
 	});
+	// pi restores the selected branch's tool loadout at a /tree switch: turned off, the tool stays out.
+	pi.on("session_tree", () => {
+		withholdIfOff();
+	});
 
 	// The permission-mode badge is a below-editor widget too, re-set on every
 	// mode change; setWidget order is last-write order, so re-set the strip

package/extensions/workflow/run-manager.ts

@@ -29,6 +29,7 @@ import { runWorkflowScript } from "./vm-runtime.ts";
 import type { AgentRecord, RunProgressEvent, RunStatus, WorkflowMeta } from "./types.ts";
 import { WorkflowScriptError } from "./types.ts";
 import type { ViewerRunSnapshot } from "./viewer.ts";
+import type { DeferRequest } from "../lib/deferred.ts";
 
 const WALL_CLOCK_CAP_MS = 30 * 60 * 1000;
 const RECENT_EVENTS_CAP = 200;
@@ -58,6 +59,8 @@ export interface StartRunOptions {
 	onChildWrite?: (path: string, agent: string | undefined) => void;
 	/** The parent's live MCP tools, shared into every workflow agent (see AgentRunnerOptions). */
 	getMcpTools?: () => ToolDefinition[] | Promise<ToolDefinition[]>;
+	/** The tools the parent defers: each agent defers them too. */
+	getParentDeferred?: () => DeferRequest[];
 }
 
 export class RunHandle extends EventEmitter {
@@ -263,6 +266,7 @@ export class WorkflowRunManager {
 				onModelUnusable: options.onModelUnusable,
 				onChildWrite: options.onChildWrite,
 				getMcpTools: options.getMcpTools,
+				getParentDeferred: options.getParentDeferred,
 				resultsDir: handle.runDir,
 			});