@gajae-code/coding-agent 0.18.5 → 0.18.7

package/src/sdk/host/control/dispatch.ts

@@ -93,6 +93,7 @@ const IDEMPOTENCY_TTL_MS = 15 * 60 * 1_000;
 const MAX_IDEMPOTENCY_ENTRIES = 256;
 
 const sessionChains = new WeakMap<ControlSurface, Promise<void>>();
+const pendingReplacementBarriers = new WeakMap<ControlSurface, Promise<void>>();
 interface IdempotencyEntry {
 	hash: string;
 	expiresAt: number;
@@ -189,6 +190,19 @@ function invalidInput(message: string): never {
 	throw new TypedControlError("invalid_input", message);
 }
 
+const EXPECTED_SDK_RUN_TOKEN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}:[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+
+function enqueueReplacementBarrier(surface: ControlSurface): () => void {
+	const previous = pendingReplacementBarriers.get(surface) ?? Promise.resolve();
+	const { promise: current, resolve: resolveCurrent } = Promise.withResolvers<void>();
+	const barrier = previous.then(() => current);
+	pendingReplacementBarriers.set(surface, barrier);
+	return () => {
+		resolveCurrent();
+		if (pendingReplacementBarriers.get(surface) === barrier) pendingReplacementBarriers.delete(surface);
+	};
+}
+
 /**
  * C04 `turn.abort` dispatch.
  *
@@ -244,7 +258,11 @@ function invoke(
 		case "turn.prompt":
 			return surface.prompt(text(input), input.images, input.clientRef as string | undefined);
 		case "turn.steer":
-			return surface.steer(text(input), typeof input.clientRef === "string" ? input.clientRef : undefined);
+			return surface.steer(
+				text(input),
+				typeof input.clientRef === "string" ? input.clientRef : undefined,
+				Object.hasOwn(input, "expectedSdkRunToken") ? (input.expectedSdkRunToken as string) : undefined,
+			);
 		case "turn.follow_up":
 			return surface.followUp(text(input));
 		case "turn.abort":
@@ -486,6 +504,15 @@ export function dispatchControl(
 		);
 	if (!isInput(request.input))
 		return Promise.resolve(failure(request.id, "invalid_input", "Control input must be an object."));
+	if (
+		row.sdkId === "turn.steer" &&
+		Object.hasOwn(request.input, "expectedSdkRunToken") &&
+		(typeof request.input.expectedSdkRunToken !== "string" ||
+			!EXPECTED_SDK_RUN_TOKEN_PATTERN.test(request.input.expectedSdkRunToken))
+	)
+		return Promise.resolve(
+			failure(request.id, "invalid_input", "expectedSdkRunToken must be a commandId:turnId pair."),
+		);
 	if (
 		row.sdkId === "turn.abort" &&
 		((brokerAbortFieldPresent && !brokerAbortAuthorized) ||
@@ -538,10 +565,31 @@ export function dispatchControl(
 	const work = () => execute(surface, row, dispatchRequest);
 	if (row.sdkId === "turn.abort_and_prompt") {
 		const cancellable = surface as PreflightCancellableSurface;
-		if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
-		return serialize(surface, work);
+		const releaseBarrier = enqueueReplacementBarrier(surface);
+		try {
+			if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
+			return serialize(surface, async () => {
+				try {
+					return await work();
+				} finally {
+					releaseBarrier();
+				}
+			});
+		} catch (error) {
+			releaseBarrier();
+			throw error;
+		}
 	}
 	if (row.idempotency === "idempotent" && dispatchRequest.idempotencyKey)
 		return idempotent(surface, row, dispatchRequest, work);
-	return row.idempotency === "ordered" && row.sdkId !== "retry.now" ? serialize(surface, work) : work();
+	if (row.sdkId === "turn.steer") {
+		const replacementBarrier = pendingReplacementBarriers.get(surface);
+		return replacementBarrier ? replacementBarrier.then(work) : work();
+	}
+	// Active feedback must reach the worker even while an earlier ordered control
+	// waits for that worker. Correlated steer admission remains deduplicated by
+	// the runtime reconciliation store, independently of this dispatch chain.
+	return row.idempotency === "ordered" && row.sdkId !== "retry.now" && row.sdkId !== "turn.steer"
+		? serialize(surface, work)
+		: work();
 }

package/src/sdk/host/control/operations.ts

@@ -22,7 +22,7 @@ export type ControlInput = Record<string, unknown>;
  */
 export interface ControlSurface {
 	prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-	steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
+	steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
 	followUp(text: string): Promise<ControlValue> | ControlValue;
 	abort(): Promise<ControlValue> | ControlValue;
 	/** Terminal abort: stop the current root turn (and optionally exact owned work). */

package/src/sdk/host/host.ts

@@ -107,6 +107,12 @@ export const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 export const TURN_STREAM_CAPABILITY = "turn_stream";
 /** Capability used by notification adapters that observe a host without owning its work. */
 export const SESSION_HOST_OBSERVER_CAPABILITY = "session_host_observer_v1";
+/**
+ * Opts notification adapters into positioned-only delivery for matching live
+ * effects: the host excludes a negotiating connection from the raw native leg
+ * of every frame its positioned envelope already reached.
+ */
+export const POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY = "positioned_notification_effects_v1";
 export const CAP_GATED_FRAME_KINDS: ReadonlySet<string> = new Set(["tool_activity", "reasoning_summary"]);
 const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 

package/src/sdk/host/session-runtime.test.ts

@@ -3,8 +3,9 @@ import { createHash } from "node:crypto";
 import { chmod, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import { markNonDispatchedToolEvent } from "@gajae-code/agent-core";
+import { markNonDispatchedToolEvent, ThinkingLevel } from "@gajae-code/agent-core";
 import { logger } from "@gajae-code/utils";
+import { createTestSession } from "../../../test/utilities";
 import { AsyncJobManager } from "../../async";
 import type { Settings } from "../../config/settings";
 import type { ExtensionAPI, ExtensionContext, ExtensionTranscriptEntry } from "../../extensibility/extensions";
@@ -103,7 +104,46 @@ test("runtime capabilities preserve explicit primary control surface", () => {
 	expect(createSdkCapabilities(policy, false, "cli")).toMatchObject({ primaryControlSurface: "cli" });
 });
 
-function memoryTransport(): SessionSdkTransport & {
+test("thinking.set uses the control setter and reports the applied session level", async () => {
+	const sessionContext = await createTestSession({ inMemory: true });
+	const { session, tempDir: cwd, cleanup } = sessionContext;
+	const handlers = new Map<string, (event: unknown, ctx: ExtensionContext) => Promise<void> | void>();
+	const api = {
+		on(event: string, handler: (event: unknown, ctx: ExtensionContext) => Promise<void> | void) {
+			handlers.set(event, handler);
+		},
+		sendUserMessage: async () => {},
+		setThinkingLevel: () => {
+			throw new Error("thinking.set must not use the legacy setter");
+		},
+		setThinkingLevelForControl: async (level: ThinkingLevel, persist: boolean) => {
+			expect(persist).toBe(false);
+			await session.setThinkingLevelForControl(level, persist);
+		},
+	} as unknown as ExtensionAPI;
+	const response = Promise.withResolvers<SdkFrame>();
+	const transport = memoryTransport(frame => {
+		if (frame.type === "control_response" && frame.id === "thinking-set") response.resolve(frame);
+	});
+	createSdkSessionRuntimeExtension(api, { agentDir: cwd, createTransport: async () => transport });
+	const ctx = extensionContext(transport.sessionId, cwd);
+	try {
+		await handlers.get("session_start")?.({}, ctx);
+		transport.feed("client", {
+			type: "control_request",
+			id: "thinking-set",
+			operation: "thinking.set",
+			input: { level: ThinkingLevel.Medium },
+		} as SdkFrame);
+		await response.promise;
+		expect(session.thinkingLevel).toBe(ThinkingLevel.Medium);
+	} finally {
+		await handlers.get("session_shutdown")?.({}, ctx);
+		await cleanup();
+	}
+});
+
+function memoryTransport(onSend?: (frame: SdkFrame) => void): SessionSdkTransport & {
 	feed(connectionId: string, frame: SdkFrame): void;
 	readonly sent: SdkFrame[];
 	readonly broadcasts: SdkFrame[];
@@ -126,6 +166,7 @@ function memoryTransport(): SessionSdkTransport & {
 		},
 		sendFrame(_connectionId, frame) {
 			sent.push(frame);
+			onSend?.(frame);
 		},
 		start: async () => {
 			started = true;
@@ -290,7 +331,7 @@ test("session.last_assistant returns the latest projected readable text past non
 	});
 });
 
-test("session.last_assistant returns resource_gone when the projected transcript has no readable assistant text", async () => {
+test("session.last_assistant returns null when the projected transcript has no readable assistant text", async () => {
 	const sessionId = "last-assistant-empty";
 	const ctx = extensionContext(sessionId, "/tmp", {
 		transcript: [
@@ -311,7 +352,7 @@ test("session.last_assistant returns resource_gone when the projected transcript
 		],
 	});
 
-	expect(await queryLastAssistant(ctx, sessionId)).toMatchObject({ ok: false, error: { code: "resource_gone" } });
+	expect(await queryLastAssistant(ctx, sessionId)).toMatchObject({ ok: true, page: { items: [null] } });
 });
 
 test("native prompt reconciliation fails closed for an explicitly empty assistant result", () => {
@@ -4142,6 +4183,7 @@ describe("SessionSdkSessionRuntime", () => {
 interface PreflightHooks {
 	onPreflightAccepted?: () => void;
 	onPreflightAcceptCommit?: () => void | Promise<void>;
+	expectedSdkRunToken?: string;
 }
 
 interface ResponseFrame {
@@ -4482,6 +4524,43 @@ function neverSettlingPromise(): Promise<void> {
 	return Promise.withResolvers<void>().promise;
 }
 
+test("SDK turn.steer preserves its expected run token and propagates a stale-run rejection", async () => {
+	const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-turn-steer-run-token-"));
+	const staleToken = "ended-command:ended-turn";
+	const clientRef = "stale-steer-ref";
+	const calls: Array<{ content: unknown; deliverAs?: string; expectedSdkRunToken?: string }> = [];
+	let harness: InvocationHarness | undefined;
+	try {
+		harness = await invocationHarness("steer-run-token", cwd, {
+			sendUserMessage: async (content, options) => {
+				calls.push({
+					content,
+					deliverAs: options?.deliverAs,
+					expectedSdkRunToken: options?.expectedSdkRunToken,
+				});
+				if (options?.expectedSdkRunToken === staleToken)
+					throw Object.assign(new Error("The expected SDK run is not active."), { code: "turn_not_active" });
+				return "completed";
+			},
+		});
+
+		const rejected = await harness.control("turn.steer", {
+			text: "stale steer",
+			expectedSdkRunToken: staleToken,
+			clientRef,
+		});
+		expect(rejected).toMatchObject({ ok: false, error: { code: "turn_not_active" } });
+		expect(calls).toEqual([{ content: "stale steer", deliverAs: "steer", expectedSdkRunToken: staleToken }]);
+		expect(await harness.query("turn.steer_status", { clientRef })).toMatchObject({
+			ok: true,
+			result: { status: "rejected" },
+		});
+	} finally {
+		if (harness) await harness.stop();
+		await rm(cwd, { recursive: true, force: true });
+	}
+});
+
 describe("post-acceptance invocation terminalization", () => {
 	test.each([
 		{ status: 402, code: "provider_http_402" },

package/src/sdk/host/session-runtime.ts

@@ -2059,7 +2059,7 @@ function createQuerySurface(
 					: entry.content?.flatMap(block => (block.type === "text" ? [block.text] : [])).join("\n");
 			if (text !== undefined && text.trim().length > 0) return text;
 		}
-		return undefined;
+		return null;
 	};
 	const getProfileCredentialSessionId = () => ctx.credentialSessionId ?? id;
 	const profileSettings = (options.settings ?? ctx.settings) as Pick<Settings, "get"> | undefined;
@@ -2914,6 +2914,7 @@ function createControlSurface(
 	};
 	type InternalSendOptions = NonNullable<Parameters<ExtensionAPI["sendUserMessage"]>[1]> & {
 		sdkRunCapability?: SdkRunCapability;
+		expectedSdkRunToken?: string;
 	};
 	type InternalSdkApi = Omit<ExtensionAPI, "sendUserMessage"> & {
 		sendUserMessage: (
@@ -4243,23 +4244,30 @@ function createControlSurface(
 				),
 			);
 		},
-		steer: async (text, clientRef) => {
+		steer: async (text, clientRef, expectedSdkRunToken) => {
 			const invalid = validateRequiredPromptText("turn.steer", { text });
 			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
 			const retainedClientRef = normalizeClientRef(clientRef);
+			const sendSteer = () =>
+				sendSdkUserMessage(text, {
+					deliverAs: "steer",
+					...(expectedSdkRunToken === undefined ? {} : { expectedSdkRunToken }),
+				});
 			if (retainedClientRef === undefined) {
 				const correlation = newCorrelation();
-				await sendSdkUserMessage(text, { deliverAs: "steer" });
+				await sendSteer();
 				return { accepted: true, ...correlation };
 			}
 			const durable = steerReconciliation;
 			const reservation = await durable.reserveSteer(retainedClientRef, text);
 			if (reservation.replay) return { accepted: reservation.result.status === "accepted", ...reservation.result };
 			try {
-				await sendSdkUserMessage(text, { deliverAs: "steer" });
+				await sendSteer();
 				return { accepted: true, ...(await durable.settleSteer(retainedClientRef, "accepted")) };
 			} catch (error) {
-				return { accepted: false, ...(await durable.settleSteer(retainedClientRef, "rejected", error)) };
+				const settled = await durable.settleSteer(retainedClientRef, "rejected", error);
+				if (expectedSdkRunToken !== undefined) throw error;
+				return { accepted: false, ...settled };
 			}
 		},
 		followUp: async text => {
@@ -4364,8 +4372,8 @@ function createControlSurface(
 		},
 		setModelProfile: id => (ctx.setModelProfile ? ctx.setModelProfile(id) : unavailable("model.profile.set")()),
 		cycleModel: () => (ctx.cycleModel ? ctx.cycleModel() : unavailable("model.cycle")()),
-		setThinking: level => {
-			api.setThinkingLevel(level as never);
+		setThinking: async level => {
+			await api.setThinkingLevelForControl(level as ThinkingLevel, false);
 			return { changed: true };
 		},
 		cycleThinking: () =>

package/src/sdk/index.ts

@@ -21,6 +21,7 @@ export type {
 	TrackedSendUserMessageOptions,
 } from "../session/agent-session";
 export * as bus from "./bus";
+export * from "./diagnostics/observe-broker";
 export * as host from "./host";
 export * as lifecycle from "./lifecycle";
 export * as mcp from "./mcp";

package/src/sdk/lifecycle-session.ts

@@ -123,6 +123,7 @@ export async function createLifecycleAgentSession(
 			// inside the broker's readiness window is what kills the child at the
 			// cutoff; the host resumes it once readiness is published.
 			deferMemoryBackendStartup: true,
+			deferOptionalModelRefresh: true,
 			[lifecycleStartupCapabilityOption]: capability,
 			...(mcpStartupTimeoutMs !== undefined ? { [lifecycleMcpStartupTimeoutOption]: mcpStartupTimeoutMs } : {}),
 		} as CreateAgentSessionOptions & {

package/src/sdk/mcp/server.ts

@@ -1,4 +1,4 @@
-import { getAgentDir } from "@gajae-code/utils";
+import { getAgentDir, VERSION } from "@gajae-code/utils";
 import { ensureBroker } from "../broker/ensure";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
 import { SdkClientError } from "../client/client";
@@ -14,6 +14,8 @@ import { type SessionAttachment, SessionRouter, SessionRouterError } from "../ro
 import { SessionListTraversalError, sessionListPageFromResponse, traverseSessionList } from "../session-list";
 
 const PROTOCOL_VERSION = "2024-11-05";
+const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION, "2025-03-26", "2025-06-18"] as const;
+const NEWEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[SUPPORTED_PROTOCOL_VERSIONS.length - 1];
 const SERVER_NAME = "gjc-sdk-mcp";
 const ENDPOINT_CREDENTIAL_OPERATION = "session.get_endpoint";
 
@@ -107,6 +109,16 @@ function isObject(value: unknown): value is Arguments {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function negotiatedProtocolVersion(params: unknown): string {
+	const requestedProtocolVersion = isObject(params) ? params.protocolVersion : undefined;
+	if (
+		typeof requestedProtocolVersion === "string" &&
+		(SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(requestedProtocolVersion)
+	)
+		return requestedProtocolVersion;
+	return NEWEST_PROTOCOL_VERSION;
+}
+
 function asString(args: Arguments, name: string): string | null {
 	return typeof args[name] === "string" && args[name] ? (args[name] as string) : null;
 }
@@ -389,9 +401,9 @@ export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
 				jsonrpc: "2.0",
 				id,
 				result: {
-					protocolVersion: PROTOCOL_VERSION,
+					protocolVersion: negotiatedProtocolVersion(request.params),
 					capabilities: { tools: {} },
-					serverInfo: { name: SERVER_NAME },
+					serverInfo: { name: SERVER_NAME, version: VERSION },
 				},
 			};
 		if (request.method === "tools/list")

package/src/sdk/protocol/operation-registry.ts

@@ -267,7 +267,7 @@ function controlErrors(id: string): string[] {
 		// refuses a session with no selected model before admission. The code is
 		// appended: ACP machine-only mapping reads errorCodes[0].
 		C01: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed", "model_not_selected"],
-		C02: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
+		C02: ["turn_not_active", "client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C09: ["client_ref_conflict", "reconciliation_capacity", "reconciliation_persist_failed"],
 		C06: ["action_claimed"],
 		C07: ["action_claimed", "terminal_uncertain"],

package/src/sdk/router/session-router.ts

@@ -25,7 +25,11 @@ import {
 	readSdkSessionEndpoint,
 	type SdkSessionEndpoint,
 } from "../client/discovery";
-import { SESSION_HOST_OBSERVER_CAPABILITY, TURN_STREAM_CAPABILITY } from "../host/host";
+import {
+	POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY,
+	SESSION_HOST_OBSERVER_CAPABILITY,
+	TURN_STREAM_CAPABILITY,
+} from "../host/host";
 import {
 	type ActivatedPreparedSession,
 	type PreparedSessionActivationClient,
@@ -287,8 +291,17 @@ export interface SessionRouterOptions {
 	agentDir: string;
 	/** Limits attachment to exact ids selected by a Broker-scoped operation. */
 	sessionIds?: readonly string[];
+	/** Dynamically limits attachment to sessions currently owned by the caller. */
+	attachFilter?: (sessionId: string) => boolean;
 	/** Marks default SDK clients as notification-only observers; demanding by default. */
 	observer?: boolean;
+	/**
+	 * Negotiates positioned-only notification effects on default SDK clients, so the
+	 * host stops sending them the raw native copy of frames whose positioned
+	 * envelope already reached them. Only notification-effect publishers opt in;
+	 * ordinary SDK observers keep both public surfaces.
+	 */
+	positionedNotificationEffects?: boolean;
 	deps?: SessionRouterDeps;
 	/** Runtime-specific identity validation; Router supplies a conservative fallback. */
 	correlateFrame?: SessionRouterFrameCorrelator;
@@ -615,7 +628,9 @@ type AdoptedSession = {
 export class SessionRouter {
 	readonly #agentDir: string;
 	readonly #sessionIds: ReadonlySet<string> | undefined;
+	readonly #attachFilter: ((sessionId: string) => boolean) | undefined;
 	readonly #observer: boolean;
+	readonly #positionedNotificationEffects: boolean;
 	readonly #deps: SessionRouterDeps;
 	readonly #correlateFrame: SessionRouterFrameCorrelator;
 	readonly #index: SessionIndex;
@@ -657,7 +672,9 @@ export class SessionRouter {
 	constructor(options: SessionRouterOptions) {
 		this.#agentDir = options.agentDir;
 		this.#sessionIds = options.sessionIds === undefined ? undefined : new Set(options.sessionIds);
+		this.#attachFilter = options.attachFilter;
 		this.#observer = options.observer === true;
+		this.#positionedNotificationEffects = options.positionedNotificationEffects === true;
 		this.#deps = options.deps ?? {};
 		this.#correlateFrame = options.correlateFrame ?? fallbackCorrelation;
 		this.#index = this.#deps.createIndex?.(options.agentDir) ?? new DefaultSessionIndex(options.agentDir);
@@ -797,6 +814,7 @@ export class SessionRouter {
 		if (
 			sessionId !== fallback.sessionId ||
 			(this.#sessionIds !== undefined && !this.#sessionIds.has(sessionId ?? "")) ||
+			(this.#attachFilter !== undefined && !this.#attachFilter(sessionId ?? "")) ||
 			endpointGeneration === undefined ||
 			pid === undefined ||
 			endpointMtimeMs === undefined ||
@@ -1294,7 +1312,8 @@ export class SessionRouter {
 				session.live &&
 				isSessionAuthorityEligible(session) &&
 				!session.terminalUncertain &&
-				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)),
+				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)) &&
+				(this.#attachFilter === undefined || this.#attachFilter(session.sessionId)),
 		);
 		const liveIds = new Set(live.map(session => session.sessionId));
 		const attachedIds = new Set<string>();
@@ -1524,9 +1543,13 @@ export class SessionRouter {
 				endpointMtimeMs,
 			});
 		} else {
+			const capabilities = [
+				...(this.#observer ? [SESSION_HOST_OBSERVER_CAPABILITY, TURN_STREAM_CAPABILITY] : []),
+				...(this.#positionedNotificationEffects ? [POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY] : []),
+			];
 			const defaultClient = new SdkClient(endpoint.url, endpoint.token, {
 				...ACP_SESSION_RECONNECT,
-				...(this.#observer ? { capabilities: [SESSION_HOST_OBSERVER_CAPABILITY, TURN_STREAM_CAPABILITY] } : {}),
+				...(capabilities.length > 0 ? { capabilities } : {}),
 			});
 			transport = defaultClient;
 			connection = defaultClient.connect().then(() => defaultClient);

package/src/sdk/session.ts

@@ -59,7 +59,11 @@ import { loadCapability, reset as resetCapabilities } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
 import type { SourceMeta } from "../capability/types";
 import { AUTOROUTING_INACTIVE_WARNING } from "../config/autorouting-contract";
-import { ModelProfileCredentialError, resolveMissingSessionModelRecovery } from "../config/model-profile-activation";
+import {
+	isSessionCredentialPinBlocking,
+	ModelProfileCredentialError,
+	resolveMissingSessionModelRecovery,
+} from "../config/model-profile-activation";
 import { resolveModelProfileName } from "../config/model-profile-contract";
 import { resolveProfileBindings } from "../config/model-profiles";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
@@ -157,6 +161,7 @@ import {
 	type MCPToolCache,
 	resolveMCPToolCache,
 } from "../runtime-mcp";
+import { createMCPFormInputHandler } from "../runtime-mcp/elicitation";
 import type { MCPLoadResult } from "../runtime-mcp/manager";
 import { MCP_STARTUP_WAIT_GRACE_MS } from "../runtime-mcp/startup-policy";
 import type { MCPServerConfig } from "../runtime-mcp/types";
@@ -577,6 +582,12 @@ export interface CreateAgentSessionOptions {
 	 * @internal CLI-only ordering guard; SDK callers retain immediate startup by default.
 	 */
 	deferMemoryBackendStartup?: boolean;
+	/**
+	 * Skip optional model-catalog discovery during lifecycle startup. ACP hosts must
+	 * publish their endpoint before unrelated provider credential refreshes begin.
+	 * @internal lifecycle-only startup guard.
+	 */
+	deferOptionalModelRefresh?: boolean;
 
 	/** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
 	enableLsp?: boolean;
@@ -695,6 +706,22 @@ export interface CreateAgentSessionResult {
 	gjcRuntimeSnapshot?: GjcRuntimeSnapshotProvider;
 }
 
+/**
+ * Start optional provider/model discovery only when it is safe to add work to
+ * the caller's startup graph. Lifecycle hosts deliberately skip this during
+ * construction: discovery preflights every configured provider and may refresh
+ * an unrelated OAuth credential while several hosts are opening the same DB.
+ */
+export function startOptionalModelRefresh(
+	modelRegistry: Pick<ModelRegistry, "refreshInBackground">,
+	credentialSessionId: string | undefined,
+	deferred: boolean,
+): boolean {
+	if (deferred) return false;
+	modelRegistry.refreshInBackground("online-if-uncached", credentialSessionId);
+	return true;
+}
+
 export interface DeferredMcpConfigStartupResult {
 	loadedToolCount: number;
 	hasErrors: boolean;
@@ -1970,11 +1997,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				options.preferredCredentialSelector.selector,
 			);
 		}
+		// A runtime key or this registry's literal models.yml apiKey outranks an
+		// unavailable pin; without one the provider stays blocked (never retargeted).
+		const isCredentialPinBlocking = (provider: string): boolean =>
+			isSessionCredentialPinBlocking(modelRegistry, provider, credentialSessionId);
 		const modelApiKeyAvailability = new Map<string, boolean>();
 		const getModelAvailabilityKey = (candidate: Model): string =>
 			`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
 		const hasModelApiKey = async (candidate: Model): Promise<boolean> => {
-			if (authStorage.hasSessionCredentialUnavailable(candidate.provider, credentialSessionId)) return false;
+			if (isCredentialPinBlocking(candidate.provider)) return false;
 			const availabilityKey = getModelAvailabilityKey(candidate);
 			const cached = modelApiKeyAvailability.get(availabilityKey);
 			if (cached !== undefined) {
@@ -2000,6 +2031,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const key = await modelRegistry
 				.getApiKey(candidate, credentialSessionId, { credentialSelector })
 				.catch(error => {
+					if (isCredentialPinBlocking(candidate.provider)) return undefined;
 					if (credentialSelector) {
 						logger.debug("Credential selector did not match model availability candidate", {
 							provider: candidate.provider,
@@ -2148,7 +2180,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				settings,
 			);
 			await refreshMissingQualifiedModelProviders(startupModelSelectors, modelRegistry, credentialSessionId);
-			modelRegistry.refreshInBackground("online-if-uncached", credentialSessionId);
+			startOptionalModelRefresh(modelRegistry, credentialSessionId, options.deferOptionalModelRefresh === true);
 		}
 
 		const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
@@ -2241,8 +2273,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					{
 						managedFallback: defaultModelEntries.length > 1,
 						canonicalSessionId: providerSessionId,
-						isCredentialUnavailable: provider =>
-							authStorage.hasSessionCredentialUnavailable(provider, credentialSessionId),
+						isCredentialUnavailable: isCredentialPinBlocking,
 						...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
 					},
 				);
@@ -2297,7 +2328,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			!hasExplicitModel &&
 			!model &&
 			defaultRoleSpec.model &&
-			!authStorage.hasSessionCredentialUnavailable(defaultRoleSpec.model.provider, credentialSessionId) &&
+			!isCredentialPinBlocking(defaultRoleSpec.model.provider) &&
 			(!preferredCredentialProvider || defaultRoleSpec.model.provider === preferredCredentialProvider)
 		) {
 			const settingsDefaultModel = defaultRoleSpec.model;
@@ -2623,7 +2654,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		let ownedMcpManagerTools: readonly CustomTool[] = [];
 		let publishOwnedMcpTools = false;
 		const notificationDebounceTimers = new Map<string, Timer>();
+		const installMcpInputHandler = (manager: MCPManager): void => {
+			manager.setInputRequestHandler(
+				createMCPFormInputHandler({
+					getUi: () => {
+						const context = toolContextStore.getContext();
+						return { ui: context.ui, hasUI: context.hasUI === true };
+					},
+					getAskAnswerSource: () => session.getAskAnswerSource(),
+				}),
+			);
+		};
 		const wireMcpManagerCallbacks = (manager: MCPManager): void => {
+			installMcpInputHandler(manager);
 			manager.setOnPromptsChanged(serverName => {
 				const promptCommands = buildMCPPromptCommands(manager);
 				session.setMCPPromptCommands(promptCommands);
@@ -3655,6 +3698,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					: {}),
 			});
 			owned.setAuthStorage(authStorage);
+			installMcpInputHandler(owned);
 			mcpManager = owned;
 			ownsMcpManager = true;
 			registerOwnedMcpManagerCleanup(owned);
@@ -4236,8 +4280,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				{
 					managedFallback: defaultModelEntries.length > 1,
 					canonicalSessionId: providerSessionId,
-					isCredentialUnavailable: provider =>
-						authStorage.hasSessionCredentialUnavailable(provider, credentialSessionId),
+					isCredentialUnavailable: isCredentialPinBlocking,
 					...(persistedProfileOwnsDefault ? { aliasIntent: "preset-equivalent" as const } : {}),
 				},
 			);