@gajae-code/coding-agent 0.18.6 → 0.18.7

package/src/sdk/broker/task-artifact-owner-validation.ts

@@ -0,0 +1,259 @@
+import type { NativeExactUnlinkResult } from "@gajae-code/natives";
+import {
+	assertSessionRoot,
+	parseTaskArtifactOwnerDeletionEvidence,
+	parseTaskArtifactOwnerRetirementContinuation,
+	parseTaskArtifactOwnerRetirementOutcome,
+	type TaskArtifactOwnerDeletionEvidence,
+	type TaskArtifactOwnerRetirementContinuation,
+	type TaskArtifactOwnerRetirementOutcome,
+	type TaskArtifactOwnerStorageContext,
+} from "../../session/task-artifact-owner-codec";
+
+export type BrokerCleanupPhase = "artifacts" | "transcript" | "metadata" | "lifecycle";
+
+/** Exact owner-disposition wire shape. Evidence and continuation are supplied separately by cleanup replay. */
+export type BrokerTaskArtifactOwnerRetirementDisposition =
+	| { readonly kind: "completed"; readonly nativeOutcome?: NativeExactUnlinkResult }
+	| {
+			readonly kind: "payload_retired";
+			readonly namespace: "retained";
+			readonly nativeOutcome: NativeExactUnlinkResult;
+	  }
+	| { readonly kind: "cleanup_pending"; readonly nativeOutcome?: NativeExactUnlinkResult }
+	| { readonly kind: "uncertain"; readonly reason: string; readonly nativeOutcome?: NativeExactUnlinkResult };
+
+/** Owner-only projection of durable cleanup state accepted by the pure validator. */
+export interface BrokerTaskArtifactOwnerCleanupFields {
+	readonly taskArtifactOwnerDeletionEvidence?: unknown;
+	readonly taskArtifactOwnerRetirementContinuation?: unknown;
+	readonly taskArtifactOwnerRetirementOutcome?: unknown;
+	readonly taskArtifactOwnerPayloadRetired?: unknown;
+	readonly taskArtifactOwnerNamespaceRetained?: unknown;
+	readonly taskArtifactOwnerRetired?: unknown;
+	readonly taskArtifactOwnerTranscriptDeleted?: unknown;
+	readonly taskArtifactOwnerCleanupError?: unknown;
+}
+
+/** Fully decoded owner-only cleanup state for an authorized session and phase. */
+export interface BrokerTaskArtifactOwnerCleanupValidation {
+	readonly deletionEvidence?: TaskArtifactOwnerDeletionEvidence;
+	readonly retirementContinuation?: TaskArtifactOwnerRetirementContinuation;
+	readonly retirementOutcome?: TaskArtifactOwnerRetirementOutcome;
+	readonly payloadRetired?: true;
+	readonly namespaceRetained?: true;
+	readonly retired?: true;
+	readonly transcriptDeleted?: true;
+	readonly cleanupDiagnostic?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+	return Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+function invalidDisposition(): never {
+	throw new Error("task_artifact_owner_retirement_disposition_invalid");
+}
+
+/**
+ * Decode the owner-only wire disposition using its exact trusted evidence and continuation.
+ * A decoded `completed` value is historical DTO data, not proof of physical retirement or writer closure.
+ */
+export function parseBrokerTaskArtifactOwnerRetirementDisposition(
+	value: unknown,
+	context: TaskArtifactOwnerStorageContext,
+	evidence: TaskArtifactOwnerDeletionEvidence,
+	continuation: TaskArtifactOwnerRetirementContinuation | undefined,
+): TaskArtifactOwnerRetirementOutcome {
+	assertSessionRoot(context);
+	if (!isRecord(value)) return invalidDisposition();
+	const kind = value.kind;
+	let expectedKeys: readonly string[];
+	switch (kind) {
+		case "completed":
+		case "cleanup_pending":
+			expectedKeys = Object.hasOwn(value, "nativeOutcome") ? ["kind", "nativeOutcome"] : ["kind"];
+			break;
+		case "payload_retired":
+			expectedKeys = ["kind", "namespace", "nativeOutcome"];
+			break;
+		case "uncertain":
+			expectedKeys = Object.hasOwn(value, "nativeOutcome")
+				? ["kind", "reason", "nativeOutcome"]
+				: ["kind", "reason"];
+			break;
+		default:
+			return invalidDisposition();
+	}
+	if (!hasExactKeys(value, expectedKeys)) return invalidDisposition();
+	const reconstructed = {
+		...value,
+		evidence,
+		...(continuation !== undefined ? { continuation } : {}),
+	};
+	return parseTaskArtifactOwnerRetirementOutcome(context, evidence, reconstructed);
+}
+
+function serializeNativeOutcome(outcome: NativeExactUnlinkResult): NativeExactUnlinkResult {
+	return Object.freeze({
+		ok: outcome.ok,
+		...(outcome.code !== undefined ? { code: outcome.code } : {}),
+		...(outcome.detachedPath !== undefined ? { detachedPath: outcome.detachedPath } : {}),
+		...(outcome.retainedSuccessorPath !== undefined ? { retainedSuccessorPath: outcome.retainedSuccessorPath } : {}),
+		...(outcome.retainedPlaceholderPath !== undefined
+			? { retainedPlaceholderPath: outcome.retainedPlaceholderPath }
+			: {}),
+		...(outcome.retainedUnknownPath !== undefined ? { retainedUnknownPath: outcome.retainedUnknownPath } : {}),
+		...(outcome.payloadDurable !== undefined ? { payloadDurable: outcome.payloadDurable } : {}),
+		...(outcome.windowsErrorCode !== undefined ? { windowsErrorCode: outcome.windowsErrorCode } : {}),
+	}) as NativeExactUnlinkResult;
+}
+
+/** Project an already validated internal outcome to the exact broker wire disposition. */
+export function serializeBrokerTaskArtifactOwnerRetirementDisposition(
+	outcome: TaskArtifactOwnerRetirementOutcome,
+): BrokerTaskArtifactOwnerRetirementDisposition {
+	switch (outcome.kind) {
+		case "completed":
+			return Object.freeze({
+				kind: outcome.kind,
+				...(outcome.nativeOutcome ? { nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome) } : {}),
+			});
+		case "payload_retired":
+			return Object.freeze({
+				kind: outcome.kind,
+				namespace: outcome.namespace,
+				nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome),
+			});
+		case "cleanup_pending":
+			return Object.freeze({
+				kind: outcome.kind,
+				...(outcome.nativeOutcome ? { nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome) } : {}),
+			});
+		case "uncertain":
+			return Object.freeze({
+				kind: outcome.kind,
+				reason: outcome.reason,
+				...(outcome.nativeOutcome ? { nativeOutcome: serializeNativeOutcome(outcome.nativeOutcome) } : {}),
+			});
+		default: {
+			const exhaustive: never = outcome;
+			throw new Error(`task_artifact_owner_retirement_outcome_unknown:${String(exhaustive)}`);
+		}
+	}
+}
+
+const OWNER_CLEANUP_KEYS = new Set([
+	"taskArtifactOwnerDeletionEvidence",
+	"taskArtifactOwnerRetirementContinuation",
+	"taskArtifactOwnerRetirementOutcome",
+	"taskArtifactOwnerPayloadRetired",
+	"taskArtifactOwnerNamespaceRetained",
+	"taskArtifactOwnerRetired",
+	"taskArtifactOwnerTranscriptDeleted",
+	"taskArtifactOwnerCleanupError",
+]);
+
+/**
+ * Strictly decode the owner-field projection of cleanup state against trusted session, scope context, phase,
+ * and artifact-removal state. Empty/legacy owner fields decode to an empty result. A decoded completion
+ * remains historical data: any later effect must separately verify current physical absence, fresh scrub
+ * proof, native success and current owner-parent/side-path authority before it mutates storage or transcripts.
+ */
+export function decodeBrokerTaskArtifactOwnerCleanupFields(
+	value: unknown,
+	context: TaskArtifactOwnerStorageContext,
+	expectedSessionId: string,
+	phase: BrokerCleanupPhase,
+	artifactsRemoved: boolean | undefined,
+): BrokerTaskArtifactOwnerCleanupValidation {
+	assertSessionRoot(context);
+	if (!isRecord(value) || Object.keys(value).some(key => !OWNER_CLEANUP_KEYS.has(key)))
+		throw new Error("task_artifact_owner_cleanup_fields_invalid");
+	if (expectedSessionId.length === 0 || (artifactsRemoved !== undefined && typeof artifactsRemoved !== "boolean"))
+		throw new Error("task_artifact_owner_cleanup_fields_invalid");
+
+	const has = (key: string) => Object.hasOwn(value, key);
+	const trueFlag = (key: string): true | undefined => {
+		if (!has(key)) return undefined;
+		if (value[key] !== true) throw new Error("task_artifact_owner_cleanup_flags_invalid");
+		return true;
+	};
+	let deletionEvidence: TaskArtifactOwnerDeletionEvidence | undefined;
+	if (has("taskArtifactOwnerDeletionEvidence")) {
+		deletionEvidence = parseTaskArtifactOwnerDeletionEvidence(value.taskArtifactOwnerDeletionEvidence);
+		if (deletionEvidence.sessionId !== expectedSessionId)
+			throw new Error("task_artifact_owner_cleanup_session_mismatch");
+	}
+	let retirementContinuation: TaskArtifactOwnerRetirementContinuation | undefined;
+	if (has("taskArtifactOwnerRetirementContinuation")) {
+		if (!deletionEvidence) throw new Error("task_artifact_owner_cleanup_evidence_missing");
+		retirementContinuation = parseTaskArtifactOwnerRetirementContinuation(
+			context,
+			deletionEvidence,
+			value.taskArtifactOwnerRetirementContinuation,
+		);
+	}
+	let retirementOutcome: TaskArtifactOwnerRetirementOutcome | undefined;
+	if (has("taskArtifactOwnerRetirementOutcome")) {
+		if (!deletionEvidence) throw new Error("task_artifact_owner_cleanup_evidence_missing");
+		retirementOutcome = parseBrokerTaskArtifactOwnerRetirementDisposition(
+			value.taskArtifactOwnerRetirementOutcome,
+			context,
+			deletionEvidence,
+			retirementContinuation,
+		);
+	}
+
+	const payloadRetired = trueFlag("taskArtifactOwnerPayloadRetired");
+	const namespaceRetained = trueFlag("taskArtifactOwnerNamespaceRetained");
+	const retired = trueFlag("taskArtifactOwnerRetired");
+	const transcriptDeleted = trueFlag("taskArtifactOwnerTranscriptDeleted");
+	let cleanupDiagnostic: string | undefined;
+	if (has("taskArtifactOwnerCleanupError")) {
+		const diagnostic = value.taskArtifactOwnerCleanupError;
+		if (typeof diagnostic !== "string" || diagnostic.length === 0 || diagnostic.length > 4096)
+			throw new Error("task_artifact_owner_cleanup_diagnostic_invalid");
+		cleanupDiagnostic = diagnostic;
+	}
+
+	if (
+		(retired !== undefined && (payloadRetired !== undefined || namespaceRetained !== undefined)) ||
+		(retired !== undefined && retirementOutcome?.kind !== "completed") ||
+		(payloadRetired !== undefined) !== (namespaceRetained !== undefined) ||
+		((retired !== undefined ||
+			payloadRetired !== undefined ||
+			namespaceRetained !== undefined ||
+			transcriptDeleted !== undefined) &&
+			(!deletionEvidence || !retirementOutcome)) ||
+		(transcriptDeleted !== undefined &&
+			(phase !== "artifacts" || artifactsRemoved !== true || retirementOutcome === undefined))
+	)
+		throw new Error("task_artifact_owner_cleanup_state_invalid");
+
+	if (retirementOutcome) {
+		if (
+			(retired !== undefined && retirementOutcome.kind !== "completed") ||
+			(retirementOutcome.kind === "completed" && retired === undefined) ||
+			(payloadRetired !== undefined &&
+				(retirementOutcome.kind !== "payload_retired" || retirementContinuation === undefined)) ||
+			(retirementOutcome.kind === "payload_retired" && payloadRetired === undefined)
+		)
+			throw new Error("task_artifact_owner_cleanup_disposition_mismatch");
+	}
+
+	return Object.freeze({
+		deletionEvidence,
+		retirementContinuation,
+		retirementOutcome,
+		payloadRetired,
+		namespaceRetained,
+		retired,
+		transcriptDeleted,
+		cleanupDiagnostic,
+	});
+}

package/src/sdk/bus/chat-daemon-control.ts

@@ -141,8 +141,8 @@ export type ChatDaemonAction = "stop" | "reload";
  * crashes, recovery, and attachment retirement cannot replay ambiguous work.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 82,
-	slack: 89,
+	discord: 83,
+	slack: 90,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -318,6 +318,9 @@ export class ChatDaemonRuntime {
 		this.#router = new SessionRouter({
 			agentDir: input.agentDir,
 			observer: true,
+			// A lean final answer carries no messageRef, so the raw native copy of a
+			// positioned frame has no identity to collapse onto and would post twice.
+			positionedNotificationEffects: true,
 			correlateFrame,
 			deps: {
 				...deps.routerDeps,

package/src/sdk/bus/index.ts

@@ -105,6 +105,7 @@ import {
 	canDeliverSdkEvent,
 	createSdkSurfaceFactory,
 	masterAttestationForEffectiveHost,
+	POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY,
 	reattestMasterSessionIdentity,
 	SESSION_HOST_OBSERVER_CAPABILITY,
 	type SessionSdkHost,
@@ -204,7 +205,6 @@ import {
 	ASK_SELECTED_ACK_CAPABILITY,
 	type EnsureDaemonResult,
 	ensureTelegramDaemonRunningDetailed,
-	POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY,
 } from "./telegram-daemon";
 
 export type {
@@ -3722,8 +3722,8 @@ function sdkControlSurface(
 				return unavailable("model.cycle", "no session model-cycle seam is installed")();
 			return { changed: (await ctx.cycleModel()) !== undefined };
 		},
-		setThinking: level => {
-			api.setThinkingLevel(level as ThinkingLevel);
+		setThinking: async level => {
+			await api.setThinkingLevelForControl(level as ThinkingLevel, false);
 			return { changed: true };
 		},
 		cycleThinking: () => {

package/src/sdk/bus/telegram-daemon.ts

@@ -71,6 +71,7 @@ export {
 	TELEGRAM_TRANSPORT_GENERATION,
 } from "./telegram-daemon-contract";
 
+import { POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY } from "../host/host";
 import {
 	type AgentDirSessionLifecycleService,
 	createSessionLifecycleService,
@@ -303,8 +304,9 @@ export const ASK_CONTROLS_CAPABILITY = "ask_controls_v1";
 export const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 /** Receive-only compatibility capability for pre-v2 hosts. */
 export const LEGACY_TOOL_ACTIVITY_CAPABILITY = "tool_activity_v1";
-/** Opts notification adapters into positioned-only delivery for matching live effects. */
-export const POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY = "positioned_notification_effects_v1";
+/** Public `sdk/bus/telegram-daemon` path for the canonical `sdk/host` capability token. */
+export { POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY };
+
 type ToolActivityCapability = "v1" | "v2";
 
 function negotiateToolActivityCapability(

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;

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

@@ -4372,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/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/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,
@@ -291,6 +295,13 @@ export interface SessionRouterOptions {
 	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;
@@ -619,6 +630,7 @@ export class SessionRouter {
 	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;
@@ -662,6 +674,7 @@ export class SessionRouter {
 		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);
@@ -1530,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

@@ -161,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";
@@ -2653,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);
@@ -3685,6 +3698,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					: {}),
 			});
 			owned.setAuthStorage(authStorage);
+			installMcpInputHandler(owned);
 			mcpManager = owned;
 			ownsMcpManager = true;
 			registerOwnedMcpManagerCleanup(owned);