@gajae-code/coding-agent 0.9.0 → 0.9.2

package/src/notifications/telegram-reference.ts

@@ -143,6 +143,23 @@ export function buildActionMessage(action: {
 	return { text: body, inline_keyboard };
 }
 
+/** Render an `action_needed` body as raw markdown (rich-message source; the HTML fallback stays on buildActionMessage). */
+export function buildActionMarkdown(action: {
+	kind: "ask" | "idle";
+	question?: string;
+	options?: string[];
+	summary?: string;
+}): string {
+	if (action.kind === "idle") {
+		return action.summary ? `🟢 Agent idle\n${action.summary}` : "🟢 Agent idle";
+	}
+	const heading = `❓ **${action.question ?? "Question"}**`;
+	const options = action.options ?? [];
+	if (options.length === 0) return `${heading}\n\n(reply with text)`;
+	const list = options.map((label, i) => `${i + 1}. ${label.replace(/^\s*\d+[.)]\s+/, "")}`).join("\n");
+	return `${heading}\n\n${list}`;
+}
+
 /** Send Telegram HTML text chunks sequentially so long messages preserve order. */
 export async function sendTelegramHtmlChunks(
 	send: TelegramSend,

package/src/notifications/threaded-render.ts

@@ -38,6 +38,13 @@ export interface ThreadedSend {
 	 * message. Set for streamed turn frames so live + finalized share one message.
 	 */
 	editable?: boolean;
+	/** Rich message class metadata. Only finalized final-answer sends are ever
+	 * rich-promoted; the daemon gate (`shouldPromoteRich`) requires exactly this. */
+	richClass?: "final";
+	/** Rich final-answer markdown (raw). Delivery marker derived ONLY from a frame's `finalAnswer` bit; never inferred from `phase`. */
+	richMarkdown?: string;
+	/** Live-turn raw markdown for opt-in draft streaming (set ONLY on non-finalized turn frames; never triggers rich-final promotion, which requires `lane === "finalized"`). */
+	richDraftMarkdown?: string;
 }
 
 interface ThreadedFrame {
@@ -58,6 +65,7 @@ interface ThreadedFrame {
 	cwd?: unknown;
 	// turn_stream
 	phase?: unknown;
+	finalAnswer?: boolean;
 	text?: unknown;
 	messageRef?: unknown;
 	// image_attachment / file_attachment
@@ -69,12 +77,19 @@ interface ThreadedFrame {
 	// config_update
 	verbosity?: unknown;
 	redact?: unknown;
+	// control_command_result
+	status?: unknown;
+	message?: unknown;
 }
 
 function str(v: unknown): string | undefined {
 	return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 
+function isDotOnlyText(value: string): boolean {
+	return /^[.\s]+$/.test(value);
+}
+
 /** Format the one-time identity header as pinned bullets. */
 export function formatIdentityHeader(frame: {
 	repo?: unknown;
@@ -139,6 +154,7 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 		case "turn_stream": {
 			const raw = str(frame.text);
 			if (!raw) return undefined;
+			if (frame.phase === "finalized" && isDotOnlyText(raw)) return undefined;
 			const text = markdownToTelegramHtml(raw);
 			const finalized = frame.phase === "finalized";
 			// A per-turn ref ties the streamed live edits and the finalized text to
@@ -156,6 +172,16 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 				text,
 				coalesceKey,
 				editable: coalesceKey !== undefined,
+				// Rich-final markers are set ONLY on a non-editable finalized final
+				// (no messageRef / coalesceKey). A streamed (editable) final owns a live
+				// message edited in place, so it is never rich-promoted and carries no
+				// rich marker to leak into split continuations.
+				richClass: frame.finalAnswer === true && coalesceKey === undefined ? "final" : undefined,
+				richMarkdown: frame.finalAnswer === true && coalesceKey === undefined ? raw : undefined,
+				// Live-only draft marker: carries the RAW markdown on non-finalized turn
+				// frames so the opt-in draft gate has the source. It never arms rich-final
+				// promotion (shouldPromoteRich requires lane === "finalized").
+				richDraftMarkdown: finalized ? undefined : raw,
 			};
 		}
 		case "image_attachment": {
@@ -188,9 +214,24 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 			const redact = typeof frame.redact === "boolean" ? `redact ${frame.redact ? "on" : "off"}` : undefined;
 			const parts = [verbosity ? `verbosity ${verbosity}` : undefined, redact].filter(Boolean);
 			return parts.length
-				? { method: "sendMessage", lane: "idle", text: finalizeTelegramHtml(`⚙ ${escapeHtml(parts.join(", "))}`) }
+				? {
+						method: "sendMessage",
+						lane: "idle",
+						text: finalizeTelegramHtml(`⚙ ${escapeHtml(parts.join(", "))}`),
+					}
 				: undefined;
 		}
+		case "control_command_result": {
+			const message = str(frame.message);
+			if (!message) return undefined;
+			const status = str(frame.status);
+			const prefix = status === "ok" ? "✅" : status === "unavailable" ? "⚠️" : "❌";
+			return {
+				method: "sendMessage",
+				lane: "idle",
+				text: finalizeTelegramHtml(`${prefix} ${escapeHtml(truncate(message, 1200))}`),
+			};
+		}
 		default:
 			return undefined;
 	}

package/src/notifications/topic-registry.ts

@@ -120,15 +120,16 @@ export class TopicRegistry {
 		return record ? !record.identitySent : true;
 	}
 
-	/**
-	 * Record the topic's applied title. Returns `true` when it changed (so the
-	 * caller should `editForumTopic`), `false` when already current or unknown.
-	 */
-	applyName(sessionId: string, name: string): boolean {
+	/** Whether a known session topic's applied title differs from `name`. */
+	needsRename(sessionId: string, name: string): boolean {
 		const record = this.topics.get(sessionId);
-		if (!record || record.name === name) return false;
-		record.name = name;
-		return true;
+		return record !== undefined && record.name !== name;
+	}
+
+	/** Commit a successfully-applied Telegram topic title. */
+	markNameApplied(sessionId: string, name: string): void {
+		const record = this.topics.get(sessionId);
+		if (record) record.name = name;
 	}
 
 	/** Remove a session topic record after Telegram deletes the topic. */

package/src/prompts/tools/search-tool-bm25.md

@@ -21,3 +21,8 @@ Returns JSON with:
 - `activated_tools` — tools activated by this search call
 - `match_count` — number of ranked matches returned by the search
 - `total_tools`
+
+Match details include:
+- `server_name` — MCP server name when the activated result is an MCP tool
+- `mcp_tool_name` — original MCP tool name when applicable
+- `schema_keys` — searchable input property names

package/src/prompts/tools/skill-discovery.md

@@ -0,0 +1,13 @@
+Discover project and user runtime skills without loading full skill content.
+
+<instruction>
+- Searches only custom runtime skill locations: project `.gjc/skills` and user `~/.gjc/skills`.
+- Built-in, bundled, and internal workflow skills are intentionally excluded.
+- Returns thin metadata only: name, description, source scope, path, and use conditions when present.
+- To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.
+</instruction>
+
+Input:
+- `query` (optional): words to match against skill name, description, source, or use conditions.
+- `source` (optional): `all`, `project`, or `user`.
+- `limit` (optional): maximum results, 1-50.

package/src/runtime-credential-selector.ts

@@ -0,0 +1,35 @@
+import type { AuthCredentialSelector, AuthCredentialSelectorKind } from "@gajae-code/ai";
+
+export interface CliCredentialSelector {
+	provider?: string;
+	selector: AuthCredentialSelector;
+	raw: string;
+}
+
+const SELECTOR_KINDS = new Set<AuthCredentialSelectorKind>(["id", "email", "account", "project"]);
+
+function parseSelectorBody(body: string): AuthCredentialSelector | undefined {
+	const separator = body.indexOf(":");
+	if (separator === -1) {
+		if (body.includes("@")) return { kind: "email", value: body };
+		return undefined;
+	}
+	const rawKind = body.slice(0, separator);
+	const value = body.slice(separator + 1).trim();
+	if (!SELECTOR_KINDS.has(rawKind as AuthCredentialSelectorKind) || value.length === 0) return undefined;
+	return { kind: rawKind as AuthCredentialSelectorKind, value };
+}
+
+export function parseCliCredentialSelector(raw: string): CliCredentialSelector {
+	const trimmed = raw.trim();
+	const slash = trimmed.indexOf("/");
+	const provider = slash === -1 ? undefined : trimmed.slice(0, slash).trim();
+	const body = slash === -1 ? trimmed : trimmed.slice(slash + 1).trim();
+	const selector = parseSelectorBody(body);
+	if (!selector || provider === "") {
+		throw new Error(
+			`Invalid --credential selector "${raw}". Use email:name@example.com, id:123, account:<id>, project:<id>, or provider/email:name@example.com.`,
+		);
+	}
+	return { ...(provider ? { provider } : {}), selector, raw };
+}

package/src/sdk.ts

@@ -9,6 +9,7 @@ import {
 	type ThinkingLevel,
 } from "@gajae-code/agent-core";
 import {
+	type AuthCredentialSelector,
 	type CredentialDisabledEvent,
 	type Message,
 	type Model,
@@ -39,7 +40,7 @@ import {
 import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElapsedMs } from "./async";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
-import { ModelRegistry } from "./config/model-registry";
+import { kNoAuth, ModelRegistry } from "./config/model-registry";
 import {
 	formatModelString,
 	parseModelPattern,
@@ -121,7 +122,12 @@ import {
 } from "./system-prompt";
 import { AgentOutputManager } from "./task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "./thinking";
-import { collectDiscoverableTools, type DiscoverableTool } from "./tool-discovery/tool-index";
+import {
+	collectDiscoverableTools,
+	type DiscoverableTool,
+	isMCPBridgeTool,
+	isMCPToolName,
+} from "./tool-discovery/tool-index";
 import {
 	applyConfiguredSearchTimeout,
 	BashTool,
@@ -267,6 +273,8 @@ export interface CreateAgentSessionOptions {
 	/** Optional provider-facing session identifier for prompt caches and sticky auth selection.
 	 * Keeps persisted session files isolated while reusing provider-side caches. */
 	providerSessionId?: string;
+	/** Runtime credential selector for multi-account auth pools. */
+	credentialSelector?: { provider?: string; selector: AuthCredentialSelector; raw: string };
 
 	/** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
 	customTools?: (CustomTool | ToolDefinition)[];
@@ -898,10 +906,22 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			startupCredentialDisabledEvents.push(event);
 		}
 	});
+	let runtimeCredentialSelectorInstalled = false;
+	const installRuntimeCredentialSelector = (provider: string): void => {
+		if (!options.credentialSelector || runtimeCredentialSelectorInstalled) return;
+		authStorage.setRuntimeCredentialSelector(provider, options.credentialSelector.selector);
+		runtimeCredentialSelectorInstalled = true;
+	};
+	const earlyCredentialSelectorProvider = options.credentialSelector?.provider ?? options.model?.provider;
+	if (earlyCredentialSelectorProvider) {
+		installRuntimeCredentialSelector(earlyCredentialSelectorProvider);
+	}
 	const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
 	modelRegistry.applyConfiguredModelBindings(settings);
 	logger.time("initializeWithSettings", initializeWithSettings, settings);
-	if (!options.modelRegistry) {
+	const canRefreshModelsBeforeCredentialSelector =
+		!options.credentialSelector || runtimeCredentialSelectorInstalled || options.modelRegistry !== undefined;
+	if (!options.modelRegistry && canRefreshModelsBeforeCredentialSelector) {
 		modelRegistry.refreshInBackground();
 	}
 	// Kick off workspace tree discovery early. The native workspace scan returns
@@ -967,7 +987,29 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			return cached;
 		}
 
-		const hasKey = !!(await modelRegistry.getApiKey(candidate, providerSessionId));
+		const credentialSelector =
+			options.credentialSelector && !runtimeCredentialSelectorInstalled
+				? options.credentialSelector.provider === undefined ||
+					options.credentialSelector.provider === candidate.provider
+					? options.credentialSelector.selector
+					: undefined
+				: undefined;
+		if (options.credentialSelector?.provider && options.credentialSelector.provider !== candidate.provider) {
+			modelApiKeyAvailability.set(availabilityKey, false);
+			return false;
+		}
+		const key = await modelRegistry.getApiKey(candidate, providerSessionId, { credentialSelector }).catch(error => {
+			if (credentialSelector) {
+				logger.debug("Credential selector did not match model availability candidate", {
+					provider: candidate.provider,
+					model: candidate.id,
+					error: error instanceof Error ? error.message : String(error),
+				});
+				return undefined;
+			}
+			throw error;
+		});
+		const hasKey = Boolean(key) && (!credentialSelector || key !== kNoAuth);
 		modelApiKeyAvailability.set(availabilityKey, hasKey);
 		return hasKey;
 	};
@@ -1042,6 +1084,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const taskDepth = options.taskDepth ?? 0;
 
 	let thinkingLevel = options.thinkingLevel;
+	const hasExplicitDefaultThinkingLevel = settings.has("defaultThinkingLevel");
+	let thinkingLevelFromSchemaDefault = false;
 
 	// If session has data and includes a thinking entry, restore it
 	if (thinkingLevel === undefined && hasExistingSession && hasThinkingEntry) {
@@ -1052,13 +1096,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		thinkingLevel = defaultRoleSpec.thinkingLevel;
 	}
 
-	// Prefer the selected model's configured defaultLevel, otherwise fall back
-	// to the global settings default.
+	// An explicit user/project default should win over the model's bundled
+	// defaultLevel. The schema default is only a final fallback so model metadata
+	// can keep driving first-run behavior until the user chooses "Set as default".
+	if (thinkingLevel === undefined && hasExplicitDefaultThinkingLevel) {
+		thinkingLevel = settings.get("defaultThinkingLevel");
+	}
+
 	if (thinkingLevel === undefined && model?.thinking?.defaultLevel !== undefined) {
 		thinkingLevel = model.thinking.defaultLevel;
 	}
+
 	if (thinkingLevel === undefined) {
 		thinkingLevel = settings.get("defaultThinkingLevel");
+		thinkingLevelFromSchemaDefault = true;
 	}
 	if (model) {
 		const resolvedModel = model;
@@ -1603,6 +1654,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (resolved) {
 				model = resolved;
 				modelFallbackMessage = undefined;
+				if (thinkingLevelFromSchemaDefault && resolved.thinking?.defaultLevel !== undefined) {
+					thinkingLevel = resolved.thinking.defaultLevel;
+					thinkingLevelFromSchemaDefault = false;
+				}
+				thinkingLevel = resolveThinkingLevelForModel(resolved, thinkingLevel);
 			} else {
 				modelFallbackMessage = `Model "${options.modelPattern}" not found`;
 			}
@@ -1634,6 +1690,18 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		}
 
+		if (options.credentialSelector && !runtimeCredentialSelectorInstalled) {
+			const credentialProvider = options.credentialSelector.provider ?? model?.provider;
+			if (!credentialProvider) {
+				throw new Error(
+					`--credential ${options.credentialSelector.raw} requires a resolved model or an explicit provider prefix`,
+				);
+			}
+			installRuntimeCredentialSelector(credentialProvider);
+			if (!options.modelRegistry && !canRefreshModelsBeforeCredentialSelector) {
+				modelRegistry.refreshInBackground();
+			}
+		}
 		const customCommandsResult: CustomCommandsLoadResult = { commands: [], errors: [] };
 
 		let extensionRunner: ExtensionRunner | undefined;
@@ -1789,7 +1857,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							{ source: "builtin" },
 						)
 					: [];
-			const discoverableToolsForDesc: DiscoverableTool[] = [...discoverableBuiltinTools];
+			const discoverableMCPTools: DiscoverableTool[] = mcpDiscoveryEnabled
+				? collectDiscoverableTools(
+						Array.from(tools.values()).filter(
+							tool => isMCPToolName(tool.name) && !activeToolNames.has(tool.name),
+						),
+						{ source: "mcp" },
+					)
+				: [];
+			const discoverableToolsForDesc: DiscoverableTool[] = [...discoverableBuiltinTools, ...discoverableMCPTools];
 			const promptTools = buildSystemPromptToolMetadata(tools, {
 				search_tool_bm25: { description: renderSearchToolBm25Description(discoverableToolsForDesc) },
 			});
@@ -1838,8 +1914,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				intentField,
 				mcpDiscoveryMode: false,
 				mcpDiscoveryServerSummaries: [],
-				toolDiscoveryActive: effectiveDiscoveryMode === "all",
-				discoverableTools: discoverableBuiltinTools
+				toolDiscoveryActive: effectiveDiscoveryMode === "all" || mcpDiscoveryEnabled,
+				discoverableTools: [...discoverableBuiltinTools, ...discoverableMCPTools]
 					.map(tool => ({ name: tool.name, summary: tool.summary }))
 					.sort((a, b) => a.name.localeCompare(b.name)),
 				eagerTasks,
@@ -1870,11 +1946,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			: toolNamesFromRegistry;
 		const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
 		const requestedToolNameSet = new Set(normalizedRequested);
-		// Effective discovery mode only covers built-in tools; MCP tool discovery
-		// is quarantined from the GJC public surface.
+		// Generic tool discovery hides non-essential built-ins behind search_tool_bm25.
+		// Legacy MCP discovery remains separately controlled by mcp.discoveryMode so
+		// loaded MCP catalogs can be searched without enabling every hidden built-in.
 		const toolsDiscoveryModeSetting = settings.get("tools.discoveryMode");
 		const effectiveDiscoveryMode: "off" | "all" = toolsDiscoveryModeSetting === "all" ? "all" : "off";
-		const mcpDiscoveryEnabled = false;
+		const mcpDiscoveryEnabled = settings.get("mcp.discoveryMode") === true;
 		const defaultInactiveToolNames = new Set(
 			registeredTools.filter(tool => tool.definition.defaultInactive).map(tool => tool.definition.name),
 		);
@@ -1887,6 +1964,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const discoveryDefaultServerToolNames: string[] = [];
 		let initialSelectedMCPToolNames: string[] = [];
 		let defaultSelectedMCPToolNames: string[] = [];
+		if (mcpDiscoveryEnabled) {
+			const defaultServerNames = new Set(settings.get("mcp.discoveryDefaultServers") ?? []);
+			for (const tool of toolRegistry.values()) {
+				if (!isMCPBridgeTool(tool)) continue;
+				discoverableMCPToolNames.add(tool.name);
+				if (initialRequestedActiveToolNames.includes(tool.name)) {
+					explicitlyRequestedMCPToolNames.push(tool.name);
+				}
+				const serverName = (tool as AgentTool & { mcpServerName?: string }).mcpServerName;
+				if (serverName && defaultServerNames.has(serverName)) {
+					discoveryDefaultServerToolNames.push(tool.name);
+				}
+			}
+		}
 		let initialToolNames = [...initialRequestedActiveToolNames];
 		if (mcpDiscoveryEnabled) {
 			const restoredSelectedMCPToolNames = existingSession.selectedMCPToolNames.filter(name =>
@@ -2247,7 +2338,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			initialSelectedMCPToolNames,
 			defaultSelectedMCPToolNames,
 			persistInitialMCPToolSelection: !hasExistingSession,
-			defaultSelectedMCPServerNames: [],
+			defaultSelectedMCPServerNames: settings.get("mcp.discoveryDefaultServers") ?? [],
 			ttsrManager,
 			obfuscator,
 			agentId: resolvedAgentId,

package/src/session/agent-session.ts

@@ -473,6 +473,8 @@ export interface PromptOptions {
 	images?: ImageContent[];
 	/** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). */
 	streamingBehavior?: "steer" | "followUp";
+	/** When set to "sequential", this follow-up is delivered one prompt at a time even if followUpMode is "all". */
+	followUpQueuePolicy?: "respect-mode" | "sequential";
 	/** Optional tool choice override for the next LLM call. */
 	toolChoice?: ToolChoice;
 	/** Send as developer/system message instead of user. Providers that support it use the developer role; others fall back to user. */
@@ -1786,7 +1788,7 @@ export class AgentSession {
 					high = mid - 1;
 				}
 			}
-			return { message: bestMessage, tokens: Math.min(bestTokens, maxTokens) };
+			return { message: bestMessage, tokens: bestTokens };
 		};
 
 		for (let i = providerMessages.length - 1; i >= 0; i--) {
@@ -1806,9 +1808,11 @@ export class AgentSession {
 				recordSkip("token-limit");
 				if (selected.length === 0) {
 					const truncated = truncateMessageToTokenBudget(sanitized);
-					selected.unshift(truncated.message);
-					approximateTokens = truncated.tokens;
-					skippedReasons["newest-message-truncated"] = (skippedReasons["newest-message-truncated"] ?? 0) + 1;
+					if (truncated.tokens <= maxTokens) {
+						selected.unshift(truncated.message);
+						approximateTokens = truncated.tokens;
+						skippedReasons["newest-message-truncated"] = (skippedReasons["newest-message-truncated"] ?? 0) + 1;
+					}
 				}
 				break;
 			}
@@ -5302,7 +5306,9 @@ export class AgentSession {
 				throw new AgentBusyError();
 			}
 			if (options.streamingBehavior === "followUp") {
-				await this.#queueFollowUp(expandedText, options?.images);
+				await this.#queueFollowUp(expandedText, options?.images, {
+					forceOneAtATime: options.followUpQueuePolicy === "sequential",
+				});
 			} else {
 				await this.#queueSteer(expandedText, options?.images);
 			}
@@ -5420,7 +5426,7 @@ export class AgentSession {
 
 	async promptCustomMessage<T = unknown>(
 		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">,
-		options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice">,
+		options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy">,
 	): Promise<void> {
 		const textContent =
 			typeof message.content === "string"
@@ -5434,7 +5440,10 @@ export class AgentSession {
 			if (!options?.streamingBehavior) {
 				throw new AgentBusyError();
 			}
-			await this.sendCustomMessage(message, { deliverAs: options.streamingBehavior });
+			await this.sendCustomMessage(message, {
+				deliverAs: options.streamingBehavior,
+				followUpQueuePolicy: options.followUpQueuePolicy,
+			});
 			return;
 		}
 
@@ -5781,13 +5790,19 @@ export class AgentSession {
 	/**
 	 * Queue a follow-up message to process after the agent would otherwise stop.
 	 */
-	async followUp(text: string, images?: ImageContent[]): Promise<void> {
+	async followUp(
+		text: string,
+		images?: ImageContent[],
+		options?: Pick<PromptOptions, "followUpQueuePolicy">,
+	): Promise<void> {
 		if (text.startsWith("/")) {
 			this.#throwIfExtensionCommand(text);
 		}
 
 		const expandedText = expandPromptTemplate(text, [...this.#promptTemplates]);
-		await this.#queueFollowUp(expandedText, images);
+		await this.#queueFollowUp(expandedText, images, {
+			forceOneAtATime: options?.followUpQueuePolicy === "sequential",
+		});
 	}
 
 	/**
@@ -5824,19 +5839,22 @@ export class AgentSession {
 	/**
 	 * Internal: Queue a follow-up message (already expanded, no extension command check).
 	 */
-	async #queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
+	async #queueFollowUp(text: string, images?: ImageContent[], options?: { forceOneAtATime?: boolean }): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
 		this.#followUpMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
 		}
-		this.agent.followUp({
-			role: "user",
-			content,
-			attribution: "user",
-			timestamp: Date.now(),
-		});
+		this.agent.followUp(
+			{
+				role: "user",
+				content,
+				attribution: "user",
+				timestamp: Date.now(),
+			},
+			options?.forceOneAtATime ? { forceOneAtATime: true } : undefined,
+		);
 		// When fully idle AND the session is in a resumable assistant-ended state,
 		// schedule an immediate continue so the queued follow-up is delivered
 		// without waiting for the next user turn. We gate on isStreaming (model
@@ -5984,7 +6002,11 @@ export class AgentSession {
 	 */
 	async sendCustomMessage<T = unknown>(
 		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">,
-		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+		options?: {
+			triggerTurn?: boolean;
+			deliverAs?: "steer" | "followUp" | "nextTurn";
+			followUpQueuePolicy?: "respect-mode" | "sequential";
+		},
 	): Promise<void> {
 		const appMessage: CustomMessage<T> = {
 			role: "custom",
@@ -6002,7 +6024,10 @@ export class AgentSession {
 			}
 
 			if (options?.deliverAs === "followUp") {
-				this.agent.followUp(appMessage);
+				this.agent.followUp(
+					appMessage,
+					options.followUpQueuePolicy === "sequential" ? { forceOneAtATime: true } : undefined,
+				);
 			} else {
 				this.agent.steer(appMessage);
 			}
@@ -6928,7 +6953,7 @@ export class AgentSession {
 
 	/**
 	 * Set thinking level.
-	 * Saves the effective metadata-clamped level to session and settings only if it changes.
+	 * Saves the effective metadata-clamped level to the session, and to settings when requested.
 	 */
 	setThinkingLevel(level: ThinkingLevel | undefined, persist: boolean = false): void {
 		const effectiveLevel = resolveThinkingLevelForModel(this.model, level);
@@ -6937,11 +6962,12 @@ export class AgentSession {
 		this.#thinkingLevel = effectiveLevel;
 		this.agent.setThinkingLevel(toReasoningEffort(effectiveLevel));
 
+		if (persist && effectiveLevel !== undefined) {
+			this.settings.set("defaultThinkingLevel", effectiveLevel);
+		}
+
 		if (isChanging) {
 			this.sessionManager.appendThinkingLevelChange(effectiveLevel);
-			if (persist && effectiveLevel !== undefined && effectiveLevel !== ThinkingLevel.Off) {
-				this.settings.set("defaultThinkingLevel", effectiveLevel);
-			}
 			this.#emit({ type: "thinking_level_changed", thinkingLevel: effectiveLevel });
 		}
 	}