@gajae-code/coding-agent 0.18.0 → 0.18.1

package/src/sdk/client/client.ts

@@ -14,6 +14,8 @@ export type SdkErrorCode =
 export class SdkClientError extends Error {
 	readonly code: SdkErrorCode;
 	readonly details: unknown;
+	/** True only when the SDK client itself reported a transport failure, never for a server error frame. */
+	readonly transport: boolean;
 	/**
 	 * Reconnect-cycle diagnostics, separate from `details` because `details` is an
 	 * established contract: callers read the terminating transport error straight off
@@ -22,19 +24,35 @@ export class SdkClientError extends Error {
 	 * break every such reader, so the new attribution rides alongside it instead.
 	 */
 	readonly reconnect?: SdkReconnectExhaustedDetails;
-	constructor(code: SdkErrorCode, message: string, details?: unknown, reconnect?: SdkReconnectExhaustedDetails) {
+	constructor(
+		code: SdkErrorCode,
+		message: string,
+		details?: unknown,
+		reconnect?: SdkReconnectExhaustedDetails,
+		options: { transport?: boolean } = {},
+	) {
 		super(message);
 		this.name = "SdkClientError";
 		this.code = code;
 		this.details = details;
+		this.transport = options.transport === true;
 		if (reconnect) this.reconnect = reconnect;
 	}
 }
 
+function transportError(
+	code: SdkErrorCode,
+	message: string,
+	details?: unknown,
+	reconnect?: SdkReconnectExhaustedDetails,
+): SdkClientError {
+	return new SdkClientError(code, message, details, reconnect, { transport: true });
+}
+
 /** A prepared transport operation failed before any wire handoff. */
 export class SdkPreparedDispatchError extends SdkClientError {
 	constructor(error: SdkClientError) {
-		super(error.code, error.message, error.details, error.reconnect);
+		super(error.code, error.message, error.details, error.reconnect, { transport: error.transport });
 		this.name = "SdkPreparedDispatchError";
 	}
 }
@@ -350,18 +368,18 @@ export class SdkClient {
 	}
 
 	send(frame: SdkFrame): void {
-		if (this.#closed) throw new SdkClientError("connection_closed", "SDK client closed");
+		if (this.#closed) throw transportError("connection_closed", "SDK client closed");
 		this.#throwIfDeadlineElapsed();
 		const current = this.#currentSocketRecord ?? this.#opening?.candidate;
 		const authoritative =
 			this.#isActive(current ?? null) ||
 			(!!current && current.phase === "hello" && this.#isCandidate(current.cycle, current));
 		if (!current || !authoritative || current.socket.readyState !== WebSocket.OPEN)
-			throw new SdkClientError("connection_closed", "SDK WebSocket is not connected");
+			throw transportError("connection_closed", "SDK WebSocket is not connected");
 		try {
 			current.socket.send(JSON.stringify(frame));
 		} catch (error) {
-			throw new SdkClientError("unavailable", "SDK WebSocket send failed", error);
+			throw transportError("unavailable", "SDK WebSocket send failed", error);
 		}
 	}
 
@@ -383,19 +401,19 @@ export class SdkClient {
 			if (cycle.backoffTimer) clearTimeout(cycle.backoffTimer);
 			if (cycle.candidate) {
 				transports.add(cycle.candidate);
-				this.#retire(cycle.candidate, new SdkClientError("connection_closed", "SDK client closed"), false);
+				this.#retire(cycle.candidate, transportError("connection_closed", "SDK client closed"), false);
 			}
-			cycle.rejectBackoff?.(new SdkClientError("connection_closed", "SDK client closed"));
+			cycle.rejectBackoff?.(transportError("connection_closed", "SDK client closed"));
 			cycle.rejectBackoff = undefined;
 			if (this.#opening === cycle) this.#opening = null;
 		}
 		const current = this.#currentSocketRecord;
 		if (current) {
 			transports.add(current);
-			this.#retire(current, new SdkClientError("connection_closed", "SDK client closed"), false, true);
+			this.#retire(current, transportError("connection_closed", "SDK client closed"), false, true);
 		}
 		for (const [id, pending] of this.#pending)
-			this.#settlePending(id, pending, new SdkClientError("connection_closed", "SDK client closed"), true);
+			this.#settlePending(id, pending, transportError("connection_closed", "SDK client closed"), true);
 		try {
 			await Promise.all([...transports].map(incarnation => this.#closeTransport(incarnation)));
 		} finally {
@@ -469,7 +487,7 @@ export class SdkClient {
 
 	async #request(frame: Frame, options: SdkRequestOptions, onResponse?: () => void): Promise<unknown> {
 		if (this.#closed) {
-			const error = new SdkClientError("connection_closed", "SDK client closed");
+			const error = transportError("connection_closed", "SDK client closed");
 			throw options.connectedOnly ? new SdkPreparedDispatchError(error) : error;
 		}
 		try {
@@ -526,7 +544,7 @@ export class SdkClient {
 					this.#settlePending(
 						id,
 						pending,
-						new SdkClientError("timeout", `SDK request timed out after ${timeoutMs}ms`, {
+						transportError("timeout", `SDK request timed out after ${timeoutMs}ms`, {
 							requestId: id,
 							requestSent: pending.sent,
 						} satisfies SdkRequestTimeoutDetails),
@@ -537,7 +555,7 @@ export class SdkClient {
 		};
 		this.#pending.set(id, pending);
 		if (!this.#isActive(incarnation) || incarnation.socket.readyState !== WebSocket.OPEN) {
-			const error = new SdkClientError("unavailable", "SDK WebSocket is not connected");
+			const error = transportError("unavailable", "SDK WebSocket is not connected");
 			this.#settlePending(id, pending, options.connectedOnly ? new SdkPreparedDispatchError(error) : error);
 			return await deferred.promise;
 		}
@@ -591,9 +609,9 @@ export class SdkClient {
 					pending,
 					options.connectedOnly
 						? new SdkPreparedDispatchError(
-								new SdkClientError("connection_closed", "SDK client closed during dispatch"),
+								transportError("connection_closed", "SDK client closed during dispatch"),
 							)
-						: new SdkClientError("connection_closed", "SDK client closed during dispatch"),
+						: transportError("connection_closed", "SDK client closed during dispatch"),
 				);
 			return await deferred.promise;
 		}
@@ -603,7 +621,7 @@ export class SdkClient {
 			return await deferred.promise;
 		}
 		if (incarnation.socket.readyState !== WebSocket.OPEN) {
-			const error = new SdkClientError("unavailable", "SDK WebSocket is not connected");
+			const error = transportError("unavailable", "SDK WebSocket is not connected");
 			this.#settlePending(id, pending, options.connectedOnly ? new SdkPreparedDispatchError(error) : error);
 			return await deferred.promise;
 		}
@@ -638,7 +656,7 @@ export class SdkClient {
 				const sendError =
 					error instanceof SdkClientError
 						? error
-						: new SdkClientError("unavailable", "SDK WebSocket send failed", error);
+						: transportError("unavailable", "SDK WebSocket send failed", error);
 				this.#settlePending(
 					id,
 					pending,
@@ -665,7 +683,7 @@ export class SdkClient {
 	}
 
 	#deadlineError(reconnect?: SdkReconnectExhaustedDetails): SdkClientError {
-		return new SdkClientError("timeout", "SDK client deadline elapsed.", undefined, reconnect);
+		return transportError("timeout", "SDK client deadline elapsed.", undefined, reconnect);
 	}
 
 	#remainingTimeout(limit = this.#timeoutMs): number {
@@ -682,7 +700,7 @@ export class SdkClient {
 		const current = this.#currentSocketRecord;
 		if (current && this.#isActive(current) && current.socket.readyState === WebSocket.OPEN) return current;
 		if (current)
-			this.#retire(current, new SdkClientError("connection_closed", "SDK WebSocket connection closed"), true, true);
+			this.#retire(current, transportError("connection_closed", "SDK WebSocket connection closed"), true, true);
 
 		let cycle = this.#opening;
 		if (!cycle) {
@@ -696,7 +714,7 @@ export class SdkClient {
 	#requireConnectedIncarnation(): Incarnation {
 		const current = this.#currentSocketRecord;
 		if (!current || !this.#isActive(current) || current.socket.readyState !== WebSocket.OPEN)
-			throw new SdkClientError("connection_closed", "SDK WebSocket disconnected before prepared dispatch.");
+			throw transportError("connection_closed", "SDK WebSocket disconnected before prepared dispatch.");
 		return current;
 	}
 
@@ -711,7 +729,7 @@ export class SdkClient {
 			reason,
 		});
 		const cancelled = (): SdkClientError =>
-			new SdkClientError("connection_closed", "SDK client closed", lastError, diagnostics("cancelled"));
+			transportError("connection_closed", "SDK client closed", lastError, diagnostics("cancelled"));
 		/**
 		 * A deadline and retry budget measure different failure axes. One-shot clients
 		 * need the deadline to fast-fail their operation, while long-lived ACP sessions
@@ -730,10 +748,10 @@ export class SdkClient {
 			try {
 				const incarnation = await this.#open(cycle);
 				if (!this.#isActive(incarnation) && (!this.#isOpening(cycle) || cycle.candidate !== incarnation))
-					throw new SdkClientError("connection_closed", "SDK WebSocket is not connected");
+					throw transportError("connection_closed", "SDK WebSocket is not connected");
 				await this.#waitForHello(incarnation);
 				if (this.#isActive(incarnation)) return incarnation;
-				throw new SdkClientError("connection_closed", "SDK WebSocket is not connected");
+				throw transportError("connection_closed", "SDK WebSocket is not connected");
 			} catch (error) {
 				lastError = error;
 				if (!this.#isOpening(cycle)) throw cancelled();
@@ -743,7 +761,7 @@ export class SdkClient {
 						candidate,
 						error instanceof SdkClientError
 							? error
-							: new SdkClientError("unavailable", "SDK WebSocket connection failed", error),
+							: transportError("unavailable", "SDK WebSocket connection failed", error),
 						true,
 					);
 				if (attempt < this.#reconnectAttempts) {
@@ -780,7 +798,7 @@ export class SdkClient {
 		}
 		cycle.phase = "complete";
 		if (this.#opening === cycle) this.#opening = null;
-		const error = new SdkClientError(
+		const error = transportError(
 			"reconnect_exhausted",
 			"SDK WebSocket reconnect attempts exhausted",
 			lastError,
@@ -891,7 +909,7 @@ export class SdkClient {
 		if (incarnation.failure) return Promise.reject(incarnation.failure);
 		if (this.#isActive(incarnation)) return Promise.resolve();
 		if (!this.#isCandidate(incarnation.cycle, incarnation) || incarnation.phase !== "hello")
-			return Promise.reject(new SdkClientError("connection_closed", "SDK WebSocket is not connected"));
+			return Promise.reject(transportError("connection_closed", "SDK WebSocket is not connected"));
 		const deferred = Promise.withResolvers<void>();
 		incarnation.resolveHello = deferred.resolve;
 		incarnation.rejectHello = deferred.reject;
@@ -903,7 +921,7 @@ export class SdkClient {
 		const error =
 			this.#deadline !== undefined && Date.now() >= this.#deadline
 				? this.#deadlineError()
-				: new SdkClientError("timeout", `SDK WebSocket connection timed out after ${timeoutMs}ms`);
+				: transportError("timeout", `SDK WebSocket connection timed out after ${timeoutMs}ms`);
 		incarnation.rejectOpen?.(error);
 		this.#retire(incarnation, error, true);
 	}
@@ -911,20 +929,20 @@ export class SdkClient {
 	#onSocketFailure(incarnation: Incarnation, event?: Event): void {
 		if (!this.#isCandidate(incarnation.cycle, incarnation) && !this.#isActive(incarnation)) return;
 		const detail = event as (Event & { error?: unknown; message?: unknown }) | undefined;
+		let failureMessage = "SDK WebSocket connection closed";
+		if (detail?.error instanceof Error) failureMessage = detail.error.message;
+		else if (typeof detail?.message === "string") failureMessage = detail.message;
 		const error =
-			detail?.error instanceof Error
+			detail?.error instanceof SdkClientError && detail.error.transport
 				? detail.error
-				: new SdkClientError(
-						"connection_closed",
-						typeof detail?.message === "string" ? detail.message : "SDK WebSocket connection closed",
-					);
+				: transportError("connection_closed", failureMessage);
 		if (incarnation.phase === "opening") incarnation.rejectOpen?.(error);
 		if (incarnation.phase === "hello") incarnation.rejectHello?.(error);
 		this.#retire(
 			incarnation,
 			error instanceof SdkClientError
 				? error
-				: new SdkClientError("unavailable", "SDK WebSocket connection failed", error),
+				: transportError("unavailable", "SDK WebSocket connection failed", error),
 			true,
 			true,
 		);
@@ -1115,7 +1133,7 @@ export class SdkClient {
 		const onClose = (): void => resolve();
 		socket.addEventListener("close", onClose, { once: true });
 		const timer = setTimeout(
-			() => reject(new SdkClientError("timeout", `SDK WebSocket close timed out after ${timeoutMs}ms`)),
+			() => reject(transportError("timeout", `SDK WebSocket close timed out after ${timeoutMs}ms`)),
 			timeoutMs,
 		);
 		timer.unref?.();
@@ -1124,9 +1142,9 @@ export class SdkClient {
 			if (Number(socket.readyState) === WebSocket.CLOSED) resolve();
 			await promise;
 		} catch (error) {
-			if (error instanceof SdkClientError) throw error;
+			if (error instanceof SdkClientError && error.transport) throw error;
 			if (Number(socket.readyState) !== WebSocket.CLOSED)
-				throw new SdkClientError("connection_closed", "SDK WebSocket close failed", error);
+				throw transportError("connection_closed", "SDK WebSocket close failed", error);
 		} finally {
 			clearTimeout(timer);
 			socket.removeEventListener("close", onClose);

package/src/sdk/protocol/operation-inventory.generated.json

@@ -5506,6 +5506,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:getAutoCompactionThresholdTokens",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal compaction-threshold accessor feeding the /context breakdown; exposed through context.get, not an independent SDK operation",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:getContextUsage",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/session/agent-session.ts

@@ -58,23 +58,28 @@ import {
 	CompactionCancelledError,
 	type CompactionPreparation,
 	type CompactionResult,
+	type CompactionSettings,
 	calculateContextTokens,
 	calculatePromptTokens,
 	collectEntriesForBranchSummary,
 	compact,
 	type EmergencyCompactionSample,
+	effectiveReserveTokens,
 	emergencyCompactionReason,
 	estimateMessageTokensHeuristic,
 	estimateTextTokensHeuristic,
 	generateBranchSummary,
 	generateHandoff,
 	IMAGE_TOKEN_ESTIMATE,
+	isDefaultAutoThresholdCeilingApplied,
 	prepareCompaction,
 	type RemoteCompactionFallbackHealthEvent,
 	type RemoteCompactionFallbackHealthHooks,
+	resolveThresholdTokens,
 	type SummaryOptions,
 	shouldCompact,
 } from "@gajae-code/agent-core/compaction";
+
 import {
 	commitToolOutputPrune,
 	createPrunedNotice,
@@ -19954,10 +19959,15 @@ export class AgentSession {
 				const compactionSettings = this.settings.getGroup("compaction");
 				const pathEntries = this.#withoutEphemeralCustomMessageEntries(this.sessionManager.getBranch());
 
-				const preparation = prepareCompaction(pathEntries, compactionSettings, {
-					contextWindow: this.model.contextWindow,
-					tokenCorrectionRatio: this.#computeCompactionTokenCorrectionRatio(),
-				});
+				const preparation = prepareCompaction(
+					pathEntries,
+					this.#compactionSettingsForContextPromotion(compactionSettings),
+					{
+						contextWindow: this.model.contextWindow,
+						tokenCorrectionRatio: this.#computeCompactionTokenCorrectionRatio(),
+					},
+				);
+
 				if (!preparation) {
 					// Check why we can't compact
 					const lastEntry = pathEntries[pathEntries.length - 1];
@@ -20974,12 +20984,12 @@ export class AgentSession {
 		}
 	}
 
-	#recordAdaptiveCompactionCall<T extends { adaptive?: { enabled: boolean; turnWindow: number } }>(
+	#recordAdaptiveCompactionCall(
 		contextTokens: number,
-		settings: T,
+		settings: CompactionSettings,
 		assistantMessage: AssistantMessage,
-	): T {
-		if (!settings.adaptive?.enabled) return settings;
+	): CompactionSettings {
+		if (!settings.adaptive?.enabled) return this.#compactionSettingsWithAdaptiveState(settings);
 		this.#adaptiveCompactionTracker.setWindowMs(settings.adaptive.turnWindow * 60_000);
 		const messageKey = this.#adaptiveCompactionMessageKey(assistantMessage);
 		if (this.#adaptiveCompactionRecordedMessageKey === messageKey) {
@@ -20994,11 +21004,31 @@ export class AgentSession {
 		return `${message.provider}\u0000${message.model}\u0000${message.timestamp}\u0000${message.usage?.totalTokens ?? ""}`;
 	}
 
-	#compactionSettingsWithAdaptiveState<T extends { adaptive?: { enabled: boolean } }>(settings: T): T {
-		if (!settings.adaptive?.enabled) return settings;
+	#compactionSettingsWithAdaptiveState(settings: CompactionSettings): CompactionSettings {
+		const adaptiveSettings = settings.adaptive?.enabled
+			? { ...settings, adaptiveState: this.#adaptiveCompactionTracker.decisionState() }
+			: settings;
+		return this.#compactionSettingsForContextPromotion(adaptiveSettings);
+	}
+
+	#compactionSettingsForContextPromotion(settings: CompactionSettings): CompactionSettings {
+		const contextWindow = this.model?.contextWindow ?? 0;
+		const isContextPromoted = this.#temporaryProviderSessionScopes.some(
+			scope => scope.token.reason === "context-promotion",
+		);
+		if (
+			!isContextPromoted ||
+			!isDefaultAutoThresholdCeilingApplied(contextWindow, settings)
+		) {
+			return settings;
+		}
+
+		// Context promotion is opt-in and exists to use the larger model's headroom.
+		// Keep the reserve-based default on the promoted model instead of immediately
+		// compacting at the same 300K ceiling that triggered promotion.
 		return {
 			...settings,
-			adaptiveState: this.#adaptiveCompactionTracker.decisionState(),
+			thresholdTokens: contextWindow - effectiveReserveTokens(contextWindow, settings),
 		};
 	}
 
@@ -22304,10 +22334,15 @@ export class AgentSession {
 			// correction only when it SHRINKS the keep window (ratio >= 1), never when
 			// it would grow it, so recovery cannot re-overflow the provider window.
 			const overflowRatio = this.#computeCompactionTokenCorrectionRatio();
-			const preparation = prepareCompaction(pathEntries, compactionSettings, {
-				contextWindow: this.model?.contextWindow,
-				tokenCorrectionRatio: overflowRatio !== undefined ? Math.max(1, overflowRatio) : undefined,
-			});
+			const preparation = prepareCompaction(
+				pathEntries,
+				this.#compactionSettingsForContextPromotion(compactionSettings),
+				{
+					contextWindow: this.model?.contextWindow,
+					tokenCorrectionRatio: overflowRatio !== undefined ? Math.max(1, overflowRatio) : undefined,
+				},
+			);
+
 			if (autoCompactionSignal.aborted) return await emitAborted();
 
 			if (!preparation) {
@@ -27184,6 +27219,21 @@ export class AgentSession {
 		};
 	}
 
+	/** Current auto-compaction threshold, including active model-promotion policy. */
+	getAutoCompactionThresholdTokens(contextTokens?: number): number {
+		const model = this.model;
+		if (!model) return 0;
+		const contextWindow = model.contextWindow ?? 0;
+		if (contextWindow <= 0) return 0;
+		const settings = this.settings.getGroup("compaction") as CompactionSettings;
+		return resolveThresholdTokens(
+			contextWindow,
+			this.#compactionSettingsWithAdaptiveState(settings),
+			0,
+			contextTokens,
+		);
+	}
+
 	/**
 	 * Get current context usage statistics.
 	 * Uses the last assistant message's usage data when available,

package/src/task/index.ts

@@ -32,11 +32,11 @@ import { resolveProfileBindings } from "../config/model-profiles";
 import { resolveAgentModelPatterns } from "../config/model-resolver";
 import type { Theme } from "../modes/theme/theme";
 import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.md" with { type: "text" };
-import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
 import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type: "text" };
 import type { ForkContextSeed } from "../session/agent-session";
 import { splitSelectorThinkingSuffix } from "../thinking";
 import { formatBytes, formatDuration } from "../tools/render-utils";
+import { renderTaskDescription } from "../tools/session-descriptions";
 import { escapeXmlAttribute } from "../utils/xml-escape";
 import {
 	type AgentDefinition,
@@ -317,57 +317,26 @@ export {
 	taskSchema,
 } from "./types";
 
-/**
- * Render the tool description from a cached agent list and current settings.
- */
 function hasAvailableIrcTool(session: ToolSession): boolean {
 	return session.settings.get("irc.enabled") === true && session.getToolByName?.("irc") !== undefined;
 }
 
-function renderDescription(
-	agents: AgentDefinition[],
-	maxConcurrency: number,
-	isolationEnabled: boolean,
-	asyncEnabled: boolean,
-	disabledAgents: string[],
-	simpleMode: TaskSimpleMode,
-	ircEnabled: boolean,
-	parentSpawns: string,
-	autoroutingActive: boolean,
-): string {
-	const spawningDisabled = parentSpawns === "";
-	let filteredAgents = filterVisibleAgents(agents);
-	filteredAgents =
-		disabledAgents.length > 0 ? filteredAgents.filter(a => !disabledAgents.includes(a.name)) : filteredAgents;
-	if (spawningDisabled) {
-		filteredAgents = [];
-	} else if (parentSpawns !== "*") {
-		const allowed = new Set(
-			parentSpawns
-				.split(",")
-				.map(s => s.trim())
-				.filter(Boolean),
-		);
-		filteredAgents = filteredAgents.filter(a => allowed.has(a.name));
-	}
-	const { contextEnabled, customSchemaEnabled } = getTaskSimpleModeCapabilities(simpleMode);
-	const description = prompt.render(taskDescriptionTemplate, {
-		agents: filteredAgents,
-		spawningDisabled,
-		MAX_CONCURRENCY: maxConcurrency,
-		isolationEnabled,
-		asyncEnabled,
-		contextEnabled,
-		customSchemaEnabled,
-		ircEnabled,
-		defaultMode: simpleMode === "default",
-		schemaFreeMode: simpleMode === "schema-free",
-		independentMode: simpleMode === "independent",
-		autoroutingActive,
-	});
-	return description;
+function callableAgents(agents: readonly AgentDefinition[], session: ToolSession): AgentDefinition[] {
+	const disabledAgents = new Set(session.settings.get("task.disabledAgents"));
+	const parentSpawns = session.getSessionSpawns() ?? "*";
+	const allowedSpawns =
+		parentSpawns === "*"
+			? undefined
+			: new Set(
+					parentSpawns
+						.split(",")
+						.map(agent => agent.trim())
+						.filter(Boolean),
+				);
+	return filterVisibleAgents(agents).filter(
+		agent => !disabledAgents.has(agent.name) && (allowedSpawns === undefined || allowedSpawns.has(agent.name)),
+	);
 }
-
 function createTaskModeError(text: string): AgentToolResult<TaskToolDetails> {
 	return {
 		content: [{ type: "text", text }],
@@ -614,22 +583,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		return renderTaskCall(args as TaskParams, options, theme);
 	}
 
-	/** Dynamic description that reflects current disabled-agent settings */
 	get description(): string {
-		const disabledAgents = this.session.settings.get("task.disabledAgents") as string[];
-		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
-		const isolationMode = this.session.settings.get("task.isolation.mode");
-		return renderDescription(
-			this.#discoveredAgents,
-			maxConcurrency,
-			isolationMode !== "none",
-			true,
-			disabledAgents,
-			this.#getTaskSimpleMode(),
-			hasAvailableIrcTool(this.session),
-			this.session.getSessionSpawns() ?? "*",
-			this.session.settings.getEffectiveAutorouting().active,
-		);
+		return renderTaskDescription(this.session);
 	}
 	readonly #sessionRepositoryBinding: RepositoryBinding;
 	#testRunSubprocess: typeof runSubprocess | undefined;
@@ -945,8 +900,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const agent = getAgent(this.#discoveredAgents, params.agent);
 		if (!agent) {
 			const available =
-				filterVisibleAgents(this.#discoveredAgents)
-					.map(a => a.name)
+				callableAgents(this.#discoveredAgents, this.session)
+					.map(agent => agent.name)
 					.join(", ") || "none";
 			return {
 				content: [{ type: "text", text: `Unknown agent "${params.agent}". Available: ${available}` }],
@@ -1714,8 +1669,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		const agent = getAgent(agents, agentName);
 		if (!agent) {
 			const available =
-				filterVisibleAgents(agents)
-					.map(a => a.name)
+				callableAgents(agents, this.session)
+					.map(agent => agent.name)
 					.join(", ") || "none";
 			return {
 				content: [

package/src/tools/descriptors.ts

@@ -11,6 +11,12 @@ import {
 	validateDeferredAskArguments,
 	validateDeferredTodoArguments,
 } from "./descriptor-validation";
+import {
+	evalToolDescriptionForSession,
+	renderTaskDescription,
+	searchToolDescriptionForSession,
+	taskParametersForSession,
+} from "./session-descriptions";
 import { TOOL_CATALOG, type ToolCatalogEntry } from "./tool-catalog.generated";
 import { ToolError } from "./tool-errors";
 
@@ -33,6 +39,11 @@ export interface ToolDescriptorMetadata {
 	readonly intent?: AgentTool<any, any, any>["intent"];
 	readonly parametersForSession?: (session?: ToolSession) => TSchema;
 	readonly parameters?: TSchema;
+	/**
+	 * Renders the description the loaded tool will report for this session. Tools whose prompt text
+	 * depends on session settings need it, or the advertised text changes on first load (#5992).
+	 */
+	readonly descriptionForSession?: (session: ToolSession) => string;
 	readonly description?: string;
 	readonly label?: string;
 	readonly customWireName?: string;
@@ -121,8 +132,10 @@ export class LazyAgentTool implements AgentTool<any, any, any> {
 		return this.#tool?.name ?? this.descriptor.metadata.name;
 	}
 	get description(): string {
+		const session = this.#session;
 		return (
 			this.#tool?.description ??
+			(session ? this.descriptor.metadata.descriptionForSession?.(session) : undefined) ??
 			this.descriptor.metadata.description ??
 			this.descriptor.presentation.summary ??
 			this.descriptor.metadata.summary ??
@@ -393,6 +406,7 @@ function descriptor(spec: DescriptorSpec): ToolDescriptor {
 		inline: catalog?.inline ?? spec.inline,
 		rawArgumentValidation: spec.rawArgumentValidation,
 		parametersForSession: spec.parametersForSession,
+		descriptionForSession: spec.descriptionForSession,
 		intent: catalog?.intent ?? spec.intent,
 		description: catalog?.description ?? spec.description,
 		parameters: spec.parameters ?? (catalog?.parameters as TSchema | undefined),
@@ -465,6 +479,15 @@ const names: Array<[name: string, label: string, summary: string | undefined, lo
 		["move_session", "Move Session", undefined, "essential"],
 	];
 
+const sessionDescriptions: Readonly<Record<string, ToolDescriptorMetadata["descriptionForSession"]>> = {
+	eval: evalToolDescriptionForSession,
+	search: searchToolDescriptionForSession,
+	task: renderTaskDescription,
+};
+
+const sessionParameters: Readonly<Record<string, ToolDescriptorMetadata["parametersForSession"]>> = {
+	task: taskParametersForSession,
+};
 const descriptorRawArgumentValidations: Readonly<Record<string, ToolDescriptorMetadata["rawArgumentValidation"]>> = {
 	ask: validateDeferredAskArguments,
 	todo_write: validateDeferredTodoArguments,
@@ -487,7 +510,10 @@ const builtins = names
 					: undefined,
 			parameters: name === "ask" ? deferredAskParameters : undefined,
 			parametersForSession:
-				name === "ask" ? session => selectAskParameters(session?.getDeepInterviewAskStage?.()) : undefined,
+				name === "ask"
+					? session => selectAskParameters(session?.getDeepInterviewAskStage?.())
+					: sessionParameters[name],
+			descriptionForSession: sessionDescriptions[name],
 			rawArgumentValidation: descriptorRawArgumentValidations[name],
 			intent: deferredIntentPolicies[name],
 			loader: loaders[name],