@gajae-code/coding-agent 0.15.5 → 0.15.6

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

@@ -5,16 +5,30 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { promisify } from "node:util";
 import { ThinkingLevel } from "@gajae-code/agent-core";
-import type { Api, Model } from "@gajae-code/ai/core";
+import type { Api, ImageContent, Model } from "@gajae-code/ai/core";
 import { logger } from "@gajae-code/utils";
 import { AsyncJobManager } from "../../async";
+import {
+	getProxyRoutableProviders,
+	inspectProxyProviderId,
+	requiresQualifiedModelProfileRoleResolution,
+	resolveProxyMode,
+	rewriteSelectorForProxy,
+	tryResolveProxyProviderId,
+} from "../../config/model-profile-activation";
 import { isModelProfileProviderAvailable, projectModelProfileCatalog } from "../../config/model-profile-contract";
-import { type ModelProfileDefinition, resolveProfileBindings } from "../../config/model-profiles";
+import {
+	deriveModelProfileMappedProviders,
+	type ModelProfileDefinition,
+	resolveProfileBindings,
+} from "../../config/model-profiles";
+import { isAuthenticated, kNoAuth } from "../../config/model-registry";
 import { resolveModelChainWithAuth, splitSelectorThinkingSuffix } from "../../config/model-resolver";
 import { type ModelSelectorValue, normalizeModelSelectorValue } from "../../config/model-selector-value";
 import { type Settings, validateSettingPatch } from "../../config/settings";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "../../extensibility/extensions";
 import { normalizeGoal } from "../../goals/state";
+import type { SdkRunCapability } from "../../session/sdk-run-capability";
 import {
 	boundTerminalRetentionState,
 	findOwnedRegistrationsForTurn,
@@ -26,7 +40,6 @@ import { parseThinkingLevel } from "../../thinking";
 import { ensureBroker } from "../broker/ensure";
 import { SessionIndex } from "../broker/session-index";
 import {
-	collectAuthenticatedProfileProviders,
 	parseSyntheticModelId,
 	resolveSyntheticModelSelection,
 	SYNTHETIC_PROVIDER_ID,
@@ -34,8 +47,9 @@ import {
 	syntheticNamespaceCollision,
 } from "../model-profile-model";
 import { projectQ10Models } from "../models.js";
-import { PromptDeadlineManager } from "../prompt-deadline-manager";
+import { PromptDeadlineManager, type PromptTerminalTransitionEvidence } from "../prompt-deadline-manager";
 import { formatPromptFailureForLocalLog, sanitizePromptFailure } from "../prompt-failure";
+import { validateRequiredPromptText } from "../protocol/adapter-validation";
 import { OPERATIONS } from "../protocol/operation-registry";
 import {
 	createKindAwareReconciliation,
@@ -43,11 +57,13 @@ import {
 	type KindAwareReconciliation,
 	resolveReconciliationSessionFile,
 } from "../reconciliation-extensions";
+import { sanitizeTurnResultContent, type TurnResultContent } from "../turn-result";
 import { type ControlSurface, controlRequestFromFrame, dispatchControl } from "./control";
 import { BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD } from "./control/runtime-gate";
 import { SessionSdkHost, type SessionSdkHostOptions } from "./host";
 import { clearAutoroutingInactive, isAutoroutingInactive, markAutoroutingInactive } from "./internal-autorouting-state";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "./query";
+import { createSdkRunCapability } from "./sdk-run-capability";
 import {
 	createSdkCapabilities,
 	createSdkSurfacePolicyForContext,
@@ -420,6 +436,7 @@ export interface InvocationCorrelation {
 
 export type InvocationKind = "prompt" | "skill" | "steer";
 type InvocationStatus = "accepted" | "in_flight" | "terminal_ok" | "failed" | "uncertain";
+const EMPTY_PROMPT_FAILURE = { code: "prompt_failed", message: "Prompt submission failed." } as const;
 interface InvocationRecord extends InvocationCorrelation {
 	kind: InvocationKind;
 	revision: number;
@@ -440,7 +457,14 @@ export interface InvocationReconciliation {
 	noteTransition(
 		kind: InvocationKind,
 		correlation: InvocationCorrelation | undefined,
-		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+		frame:
+			| {
+					type: "agent_start" | "agent_end";
+					content?: TurnResultContent;
+					hasActivity?: boolean;
+					outcome?: { kind: "stopped"; reason: "cancelled"; provenance: "client_cancel" };
+			  }
+			| { type: "agent_failed"; error: unknown; content?: TurnResultContent; hasActivity?: boolean },
 	): Promise<void>;
 	lookup(kind: InvocationKind, selector: { commandId?: string; turnId?: string; clientRef?: string }): unknown;
 	lookupResult(kind: InvocationKind, selector: { commandId?: string; turnId?: string; clientRef?: string }): unknown;
@@ -464,7 +488,13 @@ export interface InvocationReconciliation {
 		correlation: InvocationCorrelation,
 		outcome?: { kind: string; code: string; message: string; provenance?: string },
 		arg4?: (() => boolean) | { code: string; message: string },
+		// Terminal evidence accepted by finalizeOutcome (exact-head review P1/P2):
+		// when an explicit outcome is absent, a content-bearing, activity-bearing,
+		// or explicitly stopped finalization is still a successful terminal; only a
+		// genuinely empty, no-activity completion fails closed with the sanitized
+		// empty-prompt failure. Mirrors the noteTransition evidence predicate.
 		arg5?: unknown,
+		arg6?: { content?: TurnResultContent; hasActivity?: boolean; outcomeKind?: string },
 	): Promise<void>;
 	markUncertain(
 		kind: InvocationKind,
@@ -699,7 +729,14 @@ export function createInvocationReconciliation(
 						// so a real lifecycle event is never swallowed.
 					}
 					const current = records.get(recordKey);
-					if (frame.type === "agent_end" && current === pending.finalizedRecord) {
+					if (
+						frame.type === "agent_end" &&
+						current === pending.finalizedRecord &&
+						(kind !== "prompt" ||
+							frame.outcome?.kind === "stopped" ||
+							frame.hasActivity === true ||
+							frame.content?.text.trim())
+					) {
 						// A real lifecycle end that arrived during deadline finalization is
 						// stronger evidence than the synthetic deadline outcome. Upgrade the
 						// durable terminal instead of treating the event as a duplicate.
@@ -734,7 +771,14 @@ export function createInvocationReconciliation(
 				}
 			}
 			if (record.terminalAt !== undefined) {
-				if (frame.type === "agent_end" && record.error?.code === "prompt_deadline_exceeded") {
+				if (
+					frame.type === "agent_end" &&
+					record.error?.code === "prompt_deadline_exceeded" &&
+					(kind !== "prompt" ||
+						frame.outcome?.kind === "stopped" ||
+						frame.hasActivity === true ||
+						frame.content?.text.trim())
+				) {
 					const upgraded = { ...record, revision: ++mutationRevision, status: "terminal_ok" as const };
 					// The synthetic deadline error is superseded evidence; terminal_ok must not
 					// surface a deadline failure for a prompt that actually completed.
@@ -795,7 +839,17 @@ export function createInvocationReconciliation(
 				if (next.error === undefined || (next.error.code === "agent_failed" && failure.code !== "agent_failed"))
 					next.error = failure;
 			} else {
-				next.status = next.error === undefined ? "terminal_ok" : "failed";
+				if (
+					kind === "prompt" &&
+					next.error === undefined &&
+					frame.type === "agent_end" &&
+					frame.outcome?.kind !== "stopped" &&
+					!frame.content?.text.trim() &&
+					!frame.hasActivity
+				) {
+					next.status = "failed";
+					next.error = EMPTY_PROMPT_FAILURE;
+				} else next.status = next.error === undefined ? "terminal_ok" : "failed";
 				next.terminalAt = Date.now();
 			}
 			records.set(recordKey, next);
@@ -868,6 +922,7 @@ export function createInvocationReconciliation(
 			outcome,
 			arg4?: (() => boolean) | { code: string; message: string },
 			arg5?: unknown,
+			arg6?: { content?: TurnResultContent; hasActivity?: boolean; outcomeKind?: string },
 		) {
 			// Normalize every supported positional form (exact-head review P1):
 			//   (…, isCurrent) | (…, recordError) | (…, undefined, recordError) |
@@ -880,6 +935,14 @@ export function createInvocationReconciliation(
 						? (arg5 as { code: string; message: string })
 						: undefined;
 			const recordError = recordErrorCandidate;
+			// Terminal evidence may also arrive positionally through arg5 (legacy
+			// callers) when it does not carry a recordError shape; normalize it so
+			// the empty predicate below sees every evidence channel consistently.
+			const legacyEvidenceCandidate =
+				typeof arg5 === "object" && arg5 !== null && !("code" in arg5)
+					? (arg5 as { content?: TurnResultContent; hasActivity?: boolean; outcomeKind?: string })
+					: undefined;
+			const evidence = arg6 ?? legacyEvidenceCandidate;
 			const recordKey = key(kind, correlation);
 			const record = records.get(recordKey);
 			if (!record || record.terminalAt !== undefined || record.kind !== kind) return;
@@ -896,6 +959,19 @@ export function createInvocationReconciliation(
 					recordError !== undefined
 						? { code: recordError.code, message: recordError.message }
 						: { code: finalOutcome.code, message: finalOutcome.message };
+			} else if (kind === "prompt" && finalOutcome === undefined) {
+				// Evidence-based empty predicate (exact-head review P1/P2): the same
+				// semantics as the noteTransition agent_end classifier. A
+				// content-bearing, activity-bearing, or explicitly stopped
+				// finalization without an explicit outcome is a successful terminal;
+				// only a genuinely empty, no-activity completion fails closed.
+				const terminalText = evidence?.content?.text.trim() ?? "";
+				if (terminalText === "" && !evidence?.hasActivity && evidence?.outcomeKind !== "stopped") {
+					finalizedRecord.status = "failed";
+					finalizedRecord.error = EMPTY_PROMPT_FAILURE;
+				} else {
+					finalizedRecord.status = "terminal_ok";
+				}
 			} else {
 				finalizedRecord.status = "terminal_ok";
 			}
@@ -1057,21 +1133,50 @@ function createQuerySurface(
 		return undefined;
 	};
 	const getProfileCredentialSessionId = () => ctx.credentialSessionId ?? id;
+	const profileSettings = (options.settings ?? ctx.settings) as Pick<Settings, "get"> | undefined;
+	const getProfileAvailableModels = (): Model<Api>[] => {
+		const getAvailableForProfileActivation = ctx.modelRegistry.getAvailableForProfileActivation;
+		return typeof getAvailableForProfileActivation === "function"
+			? getAvailableForProfileActivation.call(ctx.modelRegistry)
+			: ctx.modelRegistry.getAvailable();
+	};
 	const resolveProfileAvailability = async (
 		profile: ModelProfileDefinition,
 		authenticatedProviders: ReadonlySet<string>,
 	): Promise<{ available: boolean; defaultModel?: Model<Api> }> => {
+		if (profile.source !== "user" && inspectProxyProviderId(profileSettings).status === "invalid")
+			return { available: false };
+		const proxyProvider = profile.source === "user" ? undefined : tryResolveProxyProviderId(profileSettings);
+		const proxyAuthenticated = proxyProvider !== undefined && authenticatedProviders.has(proxyProvider);
+		const profileAuthenticated = new Set(authenticatedProviders);
+		if (proxyAuthenticated) {
+			for (const provider of getProxyRoutableProviders(profile)) profileAuthenticated.add(provider);
+		}
 		const rewriteSelectorProvider = (selector: string): string => {
 			const slash = selector.indexOf("/");
 			if (slash < 0) return selector;
 			const provider = selector.slice(0, slash);
-			if (authenticatedProviders.has(provider)) return selector;
+			if (profileAuthenticated.has(provider)) return selector;
 			const group = (profile.alternativeProviderGroups ?? []).find(candidates => candidates.includes(provider));
 			if (!group) return selector;
-			const replacement = group.find(candidate => authenticatedProviders.has(candidate));
+			const replacement = group.find(candidate => profileAuthenticated.has(candidate));
 			return replacement ? replacement + selector.slice(slash) : selector;
 		};
 		try {
+			const proxyMode = profile.source === "user" ? "fallback" : resolveProxyMode(profileSettings);
+			if (profile.source !== "user") {
+				const configuredProviders = ctx.modelRegistry.getConfiguredProviderIds?.() ?? [];
+				if (proxyProvider !== undefined && !configuredProviders.includes(proxyProvider))
+					return { available: false };
+			}
+			if (profile.source !== "user" && proxyMode === "always") {
+				if (
+					proxyProvider === undefined ||
+					!proxyAuthenticated ||
+					!(ctx.modelRegistry.getConfiguredProviderIds?.() ?? []).includes(proxyProvider)
+				)
+					return { available: false };
+			}
 			const bindings = resolveProfileBindings(profile);
 			const assignments: Array<{ value: ModelSelectorValue; isDefault: boolean }> = [];
 			if (bindings.defaultSelector !== undefined) {
@@ -1079,23 +1184,44 @@ function createQuerySurface(
 			}
 			for (const value of Object.values(bindings.modelRoles)) assignments.push({ value, isDefault: false });
 			for (const value of Object.values(bindings.agentModelOverrides)) assignments.push({ value, isDefault: false });
+			const availableModels = getProfileAvailableModels();
+			const resolutionRegistry = {
+				...ctx.modelRegistry,
+				getAvailable: () => availableModels,
+				getApiKey: (model: Model<Api>, sessionId?: string) =>
+					ctx.modelRegistry.getApiKeyForProvider(model.provider, sessionId, model.baseUrl),
+				resolveCanonicalModel: ctx.modelRegistry.resolveCanonicalModel?.bind(ctx.modelRegistry),
+				getCanonicalVariants: ctx.modelRegistry.getCanonicalVariants?.bind(ctx.modelRegistry),
+				getCanonicalId: ctx.modelRegistry.getCanonicalId?.bind(ctx.modelRegistry),
+				resolveModelByLookupAlias: ctx.modelRegistry.resolveModelByLookupAlias?.bind(ctx.modelRegistry),
+				lookupAliasExists: ctx.modelRegistry.lookupAliasExists?.bind(ctx.modelRegistry),
+				clearCanonicalVariant: ctx.modelRegistry.clearCanonicalVariant?.bind(ctx.modelRegistry),
+			};
 			let defaultModel: Model<Api> | undefined;
 			for (const assignment of assignments) {
-				const selectors = normalizeModelSelectorValue(assignment.value).map(rewriteSelectorProvider);
+				let selectors = normalizeModelSelectorValue(assignment.value).map(rewriteSelectorProvider);
+				if (proxyProvider !== undefined && proxyAuthenticated && profile.source !== "user") {
+					selectors = selectors.map(selector =>
+						rewriteSelectorForProxy(
+							selector,
+							proxyProvider,
+							proxyMode,
+							availableModels,
+							new Set(authenticatedProviders),
+							getProxyRoutableProviders(profile),
+						),
+					);
+				}
 				const hasBareSelector = selectors.some(selector => {
 					const suffix = splitSelectorThinkingSuffix(selector);
 					const identity = suffix.thinkingLevel ? suffix.selector : selector;
 					return !identity.includes("/");
 				});
-				if (!assignment.isDefault && !hasBareSelector) continue;
+				if (!assignment.isDefault && !requiresQualifiedModelProfileRoleResolution(profile) && !hasBareSelector)
+					continue;
 				const resolution = await resolveModelChainWithAuth(
 					selectors,
-					{
-						...ctx.modelRegistry,
-						getAvailable: () => ctx.modelRegistry.getAvailable(),
-						getApiKey: (model: Model<Api>, sessionId?: string) =>
-							ctx.modelRegistry.getApiKeyForProvider(model.provider, sessionId, model.baseUrl),
-					},
+					resolutionRegistry,
 					options.settings,
 					getProfileCredentialSessionId(),
 					{
@@ -1113,6 +1239,45 @@ function createQuerySurface(
 			return { available: false };
 		}
 	};
+	const collectProfileAuthentication = async (
+		profiles: ReadonlyMap<string, ModelProfileDefinition>,
+	): Promise<Set<string>> => {
+		const providers = new Set<string>();
+		for (const profile of profiles.values()) {
+			for (const provider of profile.requiredProviders) providers.add(provider);
+			for (const group of profile.alternativeProviderGroups ?? []) {
+				for (const provider of group) providers.add(provider);
+			}
+			for (const provider of deriveModelProfileMappedProviders(profile)) providers.add(provider);
+		}
+		const authenticated = new Set<string>();
+		await Promise.all(
+			[...providers].map(async provider => {
+				try {
+					const apiKey = await ctx.modelRegistry.getApiKeyForProvider(provider, getProfileCredentialSessionId());
+					if (apiKey === kNoAuth || isAuthenticated(apiKey)) authenticated.add(provider);
+				} catch {
+					// A provider whose credential state cannot be read is not currently configurable.
+				}
+			}),
+		);
+		const proxyProviders = new Set<string>();
+		for (const profile of profiles.values()) {
+			if (profile.source === "user") continue;
+			const proxyProvider = tryResolveProxyProviderId(profileSettings);
+			if (proxyProvider !== undefined) proxyProviders.add(proxyProvider);
+		}
+		for (const proxyProvider of proxyProviders) {
+			try {
+				const apiKey = await ctx.modelRegistry.getApiKeyForProvider(proxyProvider, getProfileCredentialSessionId());
+				if (apiKey === kNoAuth || isAuthenticated(apiKey)) authenticated.add(proxyProvider);
+			} catch {
+				// Passive availability must degrade to unavailable when proxy credential
+				// refresh/storage fails; explicit activation retains its diagnostics.
+			}
+		}
+		return authenticated;
+	};
 	const getDiff = async () => {
 		try {
 			const { stdout } = await execFileAsync("git", ["diff", "--no-ext-diff"], {
@@ -1245,9 +1410,7 @@ function createQuerySurface(
 			if (collision) return degraded();
 			let authenticatedProviders: ReadonlySet<string>;
 			try {
-				authenticatedProviders = await collectAuthenticatedProfileProviders(profiles, provider =>
-					ctx.modelRegistry.getApiKeyForProvider(provider, getProfileCredentialSessionId()),
-				);
+				authenticatedProviders = await collectProfileAuthentication(profiles);
 			} catch {
 				// Availability join failed: degrade only the synthetic facade,
 				// retain concrete rows and the active marker readback.
@@ -1265,7 +1428,12 @@ function createQuerySurface(
 			);
 			const availableProfileIds = new Set<string>();
 			for (const [name, profile] of profiles) {
-				if (!isModelProfileProviderAvailable(profile, authenticatedProviders)) continue;
+				if (profile.source !== "user" && inspectProxyProviderId(profileSettings).status === "invalid") continue;
+				const profileAuthenticated = new Set(authenticatedProviders);
+				const proxyProvider = profile.source === "user" ? undefined : tryResolveProxyProviderId(profileSettings);
+				if (proxyProvider !== undefined && profileAuthenticated.has(proxyProvider))
+					for (const provider of getProxyRoutableProviders(profile)) profileAuthenticated.add(provider);
+				if (!isModelProfileProviderAvailable(profile, profileAuthenticated)) continue;
 				if (!fullyResolvedProfiles.has(name)) continue;
 				// A profile with a default mapping is selectable only when its
 				// default chain actually resolves to an authenticated model:
@@ -1336,18 +1504,19 @@ function createQuerySurface(
 			(options.steerStatusLookup ?? (value => reconciliation.lookup("steer", value)))(selector),
 		getModelProfiles: async () => {
 			const profiles = ctx.modelRegistry.getModelProfiles();
-			const authenticatedProviders = await collectAuthenticatedProfileProviders(profiles, provider =>
-				ctx.modelRegistry.getApiKeyForProvider(provider, getProfileCredentialSessionId()),
-			);
+			const authenticatedProviders = await collectProfileAuthentication(profiles);
 			return (await Promise.all(
-				projectModelProfileCatalog(profiles, ctx.modelRegistry.getError()).map(async item => ({
-					...item,
-					available:
-						isModelProfileProviderAvailable(profiles.get(item.id)!, authenticatedProviders) &&
-						(
-							await resolveProfileAvailability(profiles.get(item.id)!, authenticatedProviders)
-						).available,
-				})),
+				projectModelProfileCatalog(profiles, ctx.modelRegistry.getError()).map(async item => {
+					const profile = profiles.get(item.id)!;
+					const profileAuthenticated = new Set(authenticatedProviders);
+					const proxyProvider = profile.source === "user" ? undefined : tryResolveProxyProviderId(profileSettings);
+					if (proxyProvider !== undefined && profileAuthenticated.has(proxyProvider))
+						for (const provider of getProxyRoutableProviders(profile)) profileAuthenticated.add(provider);
+					const available =
+						isModelProfileProviderAvailable(profile, profileAuthenticated) &&
+						(await resolveProfileAvailability(profile, authenticatedProviders)).available;
+					return { ...item, available };
+				}),
 			)) as unknown[];
 		},
 		installedQueries: policy.installedQueries,
@@ -1600,6 +1769,55 @@ function providerFailureFromAgentEnd(event: unknown): { code: string; message: s
 	}
 }
 
+interface PromptTerminalEvidence {
+	content?: TurnResultContent;
+	hasActivity: boolean;
+}
+
+function promptTerminalEvidenceFromAgentEnd(event: unknown): PromptTerminalEvidence {
+	try {
+		if (!event || typeof event !== "object") return { hasActivity: false };
+		const messages = (event as { messages?: unknown }).messages;
+		if (!Array.isArray(messages)) return { hasActivity: false };
+		const assistant = [...messages]
+			.reverse()
+			.find(
+				message => message && typeof message === "object" && (message as { role?: unknown }).role === "assistant",
+			);
+		if (!assistant || typeof assistant !== "object") return { hasActivity: false };
+		const content = (assistant as { content?: unknown }).content;
+		if (typeof content === "string") {
+			const bounded = sanitizeTurnResultContent(content);
+			return { content: bounded, hasActivity: content.trim().length > 0 };
+		}
+		if (Array.isArray(content)) {
+			const hasActivity = content.some(block => {
+				if (block === null || typeof block !== "object") return false;
+				const type = (block as { type?: unknown }).type;
+				if (type === "text") {
+					const text = (block as { text?: unknown }).text;
+					return typeof text === "string" && text.trim().length > 0;
+				}
+				return typeof type === "string" && type.length > 0;
+			});
+			const text = content
+				.filter(
+					(block): block is { type: "text"; text: string } =>
+						block !== null &&
+						typeof block === "object" &&
+						(block as { type?: unknown }).type === "text" &&
+						typeof (block as { text?: unknown }).text === "string",
+				)
+				.map(block => block.text)
+				.join("");
+			return { content: sanitizeTurnResultContent(text), hasActivity };
+		}
+		return { content: sanitizeTurnResultContent(""), hasActivity: false };
+	} catch {
+		return { hasActivity: false };
+	}
+}
+
 function createControlSurface(
 	ctx: ExtensionContext,
 	api: ExtensionAPI,
@@ -1611,6 +1829,7 @@ function createControlSurface(
 		startsOwnTurn: boolean,
 		sdkRunToken: string,
 	) => void,
+	armPromptDeadline: (correlation: InvocationCorrelation) => void,
 	steerReconciliation: KindAwareReconciliation,
 	onPromotedTurn?: (
 		kind: InvocationKind,
@@ -1638,6 +1857,36 @@ function createControlSurface(
 	canResolveGate: () => boolean = () => true,
 	trackGateResolution: <T>(resolution: Promise<T>) => Promise<T> = async resolution => await resolution,
 ): ControlSurface {
+	const normalizePromptImages = (value: unknown): ImageContent[] => {
+		if (!Array.isArray(value)) return [];
+		const normalized: ImageContent[] = [];
+		for (const candidate of value) {
+			if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+			const image = candidate as Record<string, unknown>;
+			if (typeof image.data !== "string" || image.data.trim().length === 0) continue;
+			if (image.mimeType !== undefined && typeof image.mimeType !== "string") continue;
+			normalized.push({
+				type: "image",
+				data: image.data,
+				mimeType: typeof image.mimeType === "string" && image.mimeType.length > 0 ? image.mimeType : "image/png",
+			});
+		}
+		return normalized;
+	};
+	type InternalSendOptions = NonNullable<Parameters<ExtensionAPI["sendUserMessage"]>[1]> & {
+		sdkRunCapability?: SdkRunCapability;
+	};
+	type InternalSdkApi = Omit<ExtensionAPI, "sendUserMessage"> & {
+		sendUserMessage: (
+			content: Parameters<ExtensionAPI["sendUserMessage"]>[0],
+			options?: InternalSendOptions,
+		) => Promise<void>;
+	};
+	const internalApi = api as InternalSdkApi;
+	const sendSdkUserMessage = (
+		content: Parameters<ExtensionAPI["sendUserMessage"]>[0],
+		options?: Record<string, unknown>,
+	): Promise<void> => internalApi.sendUserMessage(content, options);
 	const surfacePolicy =
 		policy ?? createSdkSurfacePolicyForContext(ctx, hasSdkWorkflowGateCapability(ctx.workflowGate));
 	const typed = (operation: string, input: Record<string, unknown> = {}) =>
@@ -1722,7 +1971,7 @@ function createControlSurface(
 		kind: InvocationKind,
 		clientRef: string | undefined,
 		run: (options: {
-			sdkRunToken: string;
+			sdkRunCapability: SdkRunCapability;
 			onPreflightAccepted: () => void;
 			onPreflightAcceptCommit: () => Promise<void>;
 			/** Internal disposition before a queued submission is actually consumed. */
@@ -1743,6 +1992,7 @@ function createControlSurface(
 		reconciliation.admit(kind, retainedClientRef);
 		const correlation = newCorrelation();
 		const sdkRunToken = `${correlation.commandId}:${correlation.turnId}`;
+		const sdkRunCapability = createSdkRunCapability(sdkRunToken);
 		const preflight = Promise.withResolvers<void>();
 		let accepted = false;
 		let settled = false;
@@ -1766,6 +2016,7 @@ function createControlSurface(
 				await reconciliation.noteAccepted(kind, correlation, retainedClientRef);
 				accepted = true;
 				settled = true;
+				if (kind === "prompt" && startsOwnTurn) armPromptDeadline(correlation);
 				// The accepted submission does NOT own the active turn until its run
 				// actually STARTS: the connection is carried on the pending entry and
 				// associated at agent_start instead (review thread P1).
@@ -1801,7 +2052,7 @@ function createControlSurface(
 			const submission = Promise.resolve(
 				run({
 					onPreflightAccepted: () => void accept().catch(() => undefined),
-					sdkRunToken,
+					sdkRunCapability,
 					onPreflightAcceptCommit: accept,
 					onDispatchDisposition: promotion => {
 						promotionStartsOwnRun = promotion.startsOwnRun;
@@ -2881,52 +3132,77 @@ function createControlSurface(
 		}
 	};
 	return {
-		prompt: async (text, images, clientRef) =>
-			submit("prompt", clientRef, ({ queuedAtDispatch, sdkRunToken, ...options }) =>
-				api.sendUserMessage(
-					typeof images === "undefined" ? text : ([{ type: "text", text }, ...(images as never[])] as never),
+		prompt: async (text, images, clientRef) => {
+			const invalid = validateRequiredPromptText("turn.prompt", { text, images });
+			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
+			return await submit("prompt", clientRef, ({ queuedAtDispatch, sdkRunCapability, ...options }) =>
+				sendSdkUserMessage(
+					typeof images === "undefined"
+						? text
+						: ([{ type: "text", text }, ...normalizePromptImages(images)] as [
+								{ type: "text"; text: string },
+								...ImageContent[],
+							]),
 					{
 						...options,
-						sdkRunToken,
+						sdkRunCapability,
+						// ACP terminal settlement is owned by the correlated agent_end
+						// publication. Post-prompt recovery may include independent
+						// subagent work and must not hold that client-facing boundary.
 						...(queuedAtDispatch ? { queuedAtDispatch: true } : {}),
 					},
 				),
-			),
+			);
+		},
 		steer: async (text, clientRef) => {
+			const invalid = validateRequiredPromptText("turn.steer", { text });
+			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
 			const retainedClientRef = normalizeClientRef(clientRef);
 			if (retainedClientRef === undefined) {
 				const correlation = newCorrelation();
-				await api.sendUserMessage(text, { deliverAs: "steer" });
+				await sendSdkUserMessage(text, { deliverAs: "steer" });
 				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 api.sendUserMessage(text, { deliverAs: "steer" });
+				await sendSdkUserMessage(text, { deliverAs: "steer" });
 				return { accepted: true, ...(await durable.settleSteer(retainedClientRef, "accepted")) };
 			} catch (error) {
 				return { accepted: false, ...(await durable.settleSteer(retainedClientRef, "rejected", error)) };
 			}
 		},
-		followUp: async text =>
-			submit(
+		followUp: async text => {
+			const invalid = validateRequiredPromptText("turn.follow_up", { text });
+			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
+			return await submit(
 				"prompt",
 				undefined,
-				options => api.sendUserMessage(text, { ...options, deliverAs: "followUp" }),
+				({ sdkRunCapability, ...options }) =>
+					sendSdkUserMessage(text, {
+						...options,
+						sdkRunCapability,
+						deliverAs: "followUp",
+					}),
 				undefined,
 				false,
 				// Follow-ups never start inline; ownership correlates at promotion.
 				true,
-			),
+			);
+		},
 		abort: async () => {
 			await Promise.resolve(ctx.abort()).catch(() => undefined);
 			return { aborted: true };
 		},
 		abortTerminal: terminalAbort,
 		abortAndPrompt: async text => {
+			const invalid = validateRequiredPromptText("turn.abort_and_prompt", { text });
+			if (invalid) throw Object.assign(new Error(invalid.message), { code: invalid.code });
 			await ctx.abort();
-			return await submit("prompt", undefined, options => api.sendUserMessage(text, options));
+			return await submit("prompt", undefined, ({ sdkRunCapability, ...options }) =>
+				sendSdkUserMessage(text, { ...options, sdkRunCapability }),
+			);
 		},
 		answerAsk: unavailable("ask.answer"),
 		answerGate: async (id, response, expectedSessionId, idempotencyKey) =>
@@ -2953,9 +3229,10 @@ function createControlSurface(
 			return await submit(
 				"skill",
 				clientRef,
-				options =>
+				({ sdkRunCapability, ...options }) =>
 					ctx.invokeSkill!(name, args, {
 						...options,
+						sdkRunCapability,
 						onSkillPrepared: meta => {
 							prepared = meta;
 						},
@@ -3374,6 +3651,9 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		failureCause?: unknown,
 		maintenanceOutcome?: string,
 		lifecycleOwner?: LifecycleOwner,
+		terminalContent?: TurnResultContent,
+		terminalHasActivity = false,
+		terminalOutcome?: { kind: "stopped"; reason: "cancelled"; provenance: "client_cancel" },
 	): Promise<void> => {
 		const current = lifecycleOwner?.state ?? active;
 		if (!current) return;
@@ -3461,6 +3741,11 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				if (current.activeInvocation?.kind === "prompt") {
 					current.deadlineManager.onAccepted(current.activeInvocation.correlation);
 				}
+			} else {
+				// An empty drain is an agent-initiated successor run. Clear the
+				// predecessor's SDK owner and active invocation so abort ownership and
+				// tool-progress renewal cannot leak into the successor.
+				adoptLifecycleBatch(undefined);
 			}
 			transitions = drained.map(({ kind, correlation }) => ({ kind, correlation }));
 		} else {
@@ -3626,7 +3911,17 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					const reasonKey = `${invocation.correlation.commandId}:${invocation.correlation.turnId}`;
 					const unrecorded = type === "agent_end" ? current.unrecordedFailureReasons?.get(reasonKey) : undefined;
 					if (type === "agent_end" && invocation.kind === "prompt")
-						current.deadlineManager.noteTerminalTransition(invocation.correlation, unrecorded);
+						current.deadlineManager.noteTerminalTransition(
+							invocation.correlation,
+							unrecorded,
+							terminalContent !== undefined || terminalHasActivity || terminalOutcome !== undefined
+								? ({
+										content: terminalContent,
+										hasActivity: terminalHasActivity,
+										outcome: terminalOutcome,
+									} satisfies PromptTerminalTransitionEvidence)
+								: undefined,
+						);
 					if (type === "agent_end") {
 						// Compound recovery (exact-head review P1): if this run's
 						// agent_failed write failed, re-record the sanitized reason
@@ -3650,7 +3945,16 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 									error:
 										failureCause ?? Object.assign(new Error("agent run failed"), { code: "agent_failed" }),
 								}
-							: { type };
+							: {
+									type,
+									...(type === "agent_end" && terminalContent !== undefined
+										? { content: terminalContent }
+										: {}),
+									...(type === "agent_end" && terminalHasActivity ? { hasActivity: true } : {}),
+									...(type === "agent_end" && terminalOutcome !== undefined
+										? { outcome: terminalOutcome }
+										: {}),
+								};
 					await current.reconciliation.noteTransition(invocation.kind, invocation.correlation, frame as never);
 					if ((type as string) === "agent_end") {
 						if (invocation.kind === "prompt") current.deadlineManager.clear(invocation.correlation);
@@ -3814,6 +4118,11 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 			owner?.failureDiagnosticKeys.has(lifecycleCorrelationKey(correlation)),
 		);
 		const failureAlreadyPublished = failure === undefined || (hasExistingFailure && genericFailureKeys.length === 0);
+		const terminalEvidence = promptTerminalEvidenceFromAgentEnd(event);
+		const terminalOutcome =
+			event.stopReason === "cancelled"
+				? ({ kind: "stopped", reason: "cancelled", provenance: "client_cancel" } as const)
+				: undefined;
 		return trackLifecycle(async () => {
 			if (failure && !failureAlreadyPublished) {
 				for (const key of genericFailureKeys) owner?.failureDiagnosticKeys.delete(key);
@@ -3825,6 +4134,9 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				undefined,
 				event.stopReason === "maintenance" ? event.maintenanceOutcome : undefined,
 				lifecycleOwner,
+				terminalEvidence.content,
+				terminalEvidence.hasActivity,
+				terminalOutcome,
 			);
 		}, owner).finally(() => {
 			if (typeof event.sdkRunToken === "string" && lifecycleRunOwners.get(event.sdkRunToken)?.state === owner)
@@ -4159,8 +4471,8 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 				// promotion/agent_start instead, so a prompt waiting behind a
 				// legitimately long turn never false-fires. The agent_start
 				// re-entry in emitLifecycle is a no-op for an existing lease.
-				if (startsOwnTurn && kind === "prompt") deadlineManager.onAccepted(correlation);
 			},
+			correlation => deadlineManager.onAccepted(correlation),
 			steerReconciliation,
 			(kind, correlation, connectionId, sdkRunToken, promotion) => {
 				const bindPromotedToken = (batch?: LifecycleBatch): void => {