@sayknow-cli/coding-agent 0.3.6 → 0.3.7

package/src/prompts/agents/architect.md

@@ -25,7 +25,7 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the verdict markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the verdict markdown through the `SKC_RALPLAN_ARTIFACT` env override and `--artifact-env SKC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Never approve code or plans you have not grounded in inspected files.
 - Never give generic advice detached from this codebase.
 - Never approve CRITICAL or HIGH severity issues.
@@ -63,6 +63,9 @@ A narrow compatibility fallback can be acceptable only when it is scoped to a kn
 ## Summary
 2-3 sentences with result and main recommendation.
 
+## Claims
+Evidence-backed claims being reviewed or introduced.
+
 ## Analysis
 Evidence-backed findings.
 
@@ -81,12 +84,12 @@ Prioritized concrete actions.
 ## Code Review Recommendation
 `APPROVE` / `COMMENT` / `REQUEST CHANGES`
 
-## Trade-offs
+## Tradeoffs
 Table or bullets comparing viable options when relevant.
 
-Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown through the `SKC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --json
+  skc ralplan --write --stage architect --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (Architectural Status + Code Review Recommendation). Never paste the full review body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/critic.md

@@ -17,7 +17,7 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 
 <constraints>
 - Read-only: do not write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the evaluation markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the evaluation markdown through the `SKC_RALPLAN_ARTIFACT` env override and `--artifact-env SKC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - A lone file path is valid input; read and evaluate it.
 - Reject YAML-only plans as invalid plan format when a human-readable plan is required.
 - Do not invent problems; report no issues found when the plan passes.
@@ -42,11 +42,19 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 </success_criteria>
 
 <output_contract>
+## Verdict
 **[OKAY / ITERATE / REJECT]**
 
-**Justification**: concise evidence-backed explanation.
+## Claim Checks
+Concise evidence-backed explanation of verified claims.
 
-**Summary**:
+## Missing Evidence
+Definitely missing or unverified evidence, or `None`.
+
+## Approval Boundary
+What execution may proceed with, and what remains outside approval.
+
+## Summary
 - Clarity
 - Verifiability
 - Completeness
@@ -55,11 +63,12 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - Alternatives Depth
 - Risk/Verification Rigor
 
-If not OKAY, list concrete required fixes.
+## Required Changes
+If not OKAY, list concrete required fixes; otherwise write `None`.
 
-Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown through the `SKC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --json
+  skc ralplan --write --stage critic --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (OKAY / ITERATE / REJECT). Never paste the full evaluation body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/planner.md

@@ -17,7 +17,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the plan markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the plan markdown through the `SKC_RALPLAN_ARTIFACT` env override and `--artifact-env SKC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Persist durable plans only through `skc ralplan --write`. Never write plan files to `/tmp`, the repository, or any other path, and never rely on a file the caller must read back. The CLI is your only persistence channel.
 - Inspect the repository before asking about code facts.
 - Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences that repository inspection cannot resolve.
@@ -45,16 +45,21 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 <output_contract>
 Build the full plan as a single markdown document containing:
 - Summary
+- Intent Diff
+- Decision Drivers
+- Options
 - In scope / out of scope
 - File-level changes
 - Sequencing and dependencies
 - Acceptance criteria
 - Verification
+- Escalation/Risk Gate
+- Verification Plan
 - Risks and mitigations
 
-Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan inline (never a file path, never `/tmp`):
+Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan through the `SKC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --json
+  skc ralplan --write --stage planner --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus a compact plan summary (<=10 lines). Never paste the full plan body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/system/system-prompt.md

@@ -60,8 +60,13 @@ Use for read-only plan critique. It approves only when execution can proceed wit
 
 <routing>
 - Clear, low-risk implementation request → implement directly with focused verification.
+- Do not invoke `deep-interview`, `ralplan`, `ultragoal`, `team`, or role agents for simple clear implementation requests; direct tools and the default launch path are enough.
+- The runtime records a `workflow-intent-diff` CustomEntry for direct-path traceability; it does not participate in LLM context and is not a reason to slow down direct execution.
+- When a task is clear, bounded, and low-risk, the default action is to make the smallest correct change and verify it, not to interview, plan, open a durable ledger, or delegate.
+- Small verification needs do not make a task a planning workflow. Escalate only for real ambiguity, non-trivial architecture/sequence risk, durable multi-goal tracking, or useful coordinated workers.
+- Root-cause phase schema is active only for contradiction, regression, or high-risk transition work; otherwise keep ordinary verification and do not add root-cause ceremony.
 - Vague requirements → use `deep-interview` before planning or execution.
-- Clear requirements but non-trivial architecture/sequence risk → use `ralplan` and stop at pending approval.
+- Clear requirements but non-trivial architecture/sequence risk → use `ralplan --deliberate` and stop at pending approval.
 - Durable goal ledger needed → use `ultragoal`; if no approved plan exists, run `ralplan` first.
 - Approved work benefits from coordinated persistent workers → use `team`.
 - Large enough implementation work → delegate bounded slices to `executor` through the task/sub-agent tool when it improves quality or throughput.
@@ -131,6 +136,18 @@ Use tools whenever they materially improve correctness, completeness, or groundi
 </inventory>
 {{/if}}
 
+{{#if toolDiscoveryActive}}
+<tool-discovery>
+Only essential tools are loaded up front; other tools are hidden to save context and are available on demand. Call `{{toolRefs.search_tool_bm25}}` with a short natural-language query to find and activate the tool you need, then call it. Prefer discovering a purpose-built tool over forcing the task onto a resident one.
+{{#if discoverableTools.length}}
+Discoverable tools:
+{{#each discoverableTools}}
+- `{{name}}`{{#if summary}} — {{summary}}{{/if}}
+{{/each}}
+{{/if}}
+</tool-discovery>
+{{/if}}
+
 <inputs>
 - Keep tool inputs concise where possible.
 - For `path` or path-like fields, prefer relative paths.
@@ -233,9 +250,10 @@ For image understanding, call `{{toolRefs.read}}` on the image path; the image i
 </before-editing>
 
 <decomposition>
-- Use todo tracking for tasks with three or more distinct steps.
+- Use todo tracking for tasks with three or more distinct steps; skip it for one-step or obvious two-step fixes where the next action is already clear.
 - Mark completed tasks immediately and continue to the next task without yielding.
 - Delegate rather than silently shrinking scope. Prefer `executor` for bounded implementation slices, `planner` for sequencing, `architect` for architecture/code-review lanes, and `critic` for plan critique.
+- Do not delegate for single-line typos, obvious syntax errors, single-file known-location fixes, or direct answers.
 </decomposition>
 
 <verification>

package/src/prompts/tools/bash.md

@@ -33,7 +33,7 @@ This session's bash tool is restricted. It only accepts commands beginning with:
 {{#each restrictedAllowedPrefixes}}
 - `{{this}}`
 {{/each}}
-Use it only for sanctioned SKC workflow CLI persistence or state read/write/contract operations; per-command env overrides and all other shell command shapes are blocked before execution.
+Use it only for sanctioned SKC workflow CLI persistence or state read/write/contract operations; the only per-command env override allowed is `SKC_RALPLAN_ARTIFACT` when paired with `skc ralplan --write ... --artifact-env SKC_RALPLAN_ARTIFACT`, and all other shell command shapes are blocked before execution.
 {{/when}}
 </restricted-bash-mode>
 {{/if}}

package/src/runtime-mcp/config-writer.ts

@@ -237,6 +237,34 @@ export async function listMCPServers(filePath: string): Promise<string[]> {
 	return Object.keys(config.mcpServers ?? {});
 }
 
+/**
+ * Set a server's autoload flag (connect automatically at session startup).
+ *
+ * Autoload defaults to true, so turning it on removes the key to keep the
+ * config file free of redundant fields; turning it off writes `autoload: false`.
+ *
+ * @throws Error if the server doesn't exist
+ */
+export async function setServerAutoload(filePath: string, name: string, autoload: boolean): Promise<void> {
+	const existing = await readMCPConfigFile(filePath);
+	const server = existing.mcpServers?.[name];
+	if (!server) {
+		throw new Error(`Server "${name}" not found in ${filePath}`);
+	}
+
+	const { autoload: _removed, ...rest } = server;
+	const updatedServer = (autoload ? rest : { ...rest, autoload: false }) as MCPServerConfig;
+	const updated: MCPConfigFile = {
+		...existing,
+		mcpServers: {
+			...existing.mcpServers,
+			[name]: updatedServer,
+		},
+	};
+
+	await writeMCPConfigFile(filePath, updated);
+}
+
 /**
  * Read the disabled servers list from a config file.
  */

package/src/runtime-mcp/config.ts

@@ -20,6 +20,8 @@ export interface LoadMCPConfigsOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
+	/** Only include servers eligible for startup connection, i.e. autoload !== false (default: false) */
+	autoloadOnly?: boolean;
 }
 
 /** Result of loading MCP configs */
@@ -40,6 +42,7 @@ function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
 	const transport = server.transport ?? (server.command ? "stdio" : server.url ? "http" : "stdio");
 	const shared = {
 		enabled: server.enabled,
+		autoload: server.autoload,
 		timeout: server.timeout,
 		auth: server.auth,
 		oauth: server.oauth,
@@ -96,6 +99,7 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 	const enableProjectConfig = options?.enableProjectConfig ?? true;
 	const filterExa = options?.filterExa ?? true;
 	const filterBrowser = options?.filterBrowser ?? false;
+	const autoloadOnly = options?.autoloadOnly ?? false;
 
 	// Load MCP servers via capability system
 	const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
@@ -115,6 +119,9 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 		if (config.enabled === false || disabledServers.has(server.name)) {
 			continue;
 		}
+		if (autoloadOnly && config.autoload === false) {
+			continue;
+		}
 		configs[server.name] = config;
 		sources[server.name] = server._source;
 	}

package/src/runtime-mcp/loader.ts

@@ -34,6 +34,8 @@ export interface MCPToolsLoadOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
+	/** Only connect servers with autoload !== false (default: false) */
+	autoloadOnly?: boolean;
 	/** SQLite storage for MCP tool cache (null disables cache) */
 	cacheStorage?: AgentStorage | null;
 	/** Auth storage used to resolve OAuth credentials before initial MCP connect */
@@ -72,6 +74,7 @@ export async function discoverAndLoadMCPTools(cwd: string, options?: MCPToolsLoa
 			enableProjectConfig: options?.enableProjectConfig,
 			filterExa: options?.filterExa,
 			filterBrowser: options?.filterBrowser,
+			autoloadOnly: options?.autoloadOnly,
 		});
 	} catch (error) {
 		// If discovery fails entirely, return empty result

package/src/runtime-mcp/manager.ts

@@ -147,6 +147,8 @@ export interface MCPDiscoverOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
+	/** Only connect servers with autoload !== false (default: false) */
+	autoloadOnly?: boolean;
 	/** Called when starting to connect to servers */
 	onConnecting?: (serverNames: string[]) => void;
 }
@@ -325,6 +327,7 @@ export class MCPManager {
 			enableProjectConfig: options?.enableProjectConfig,
 			filterExa: options?.filterExa,
 			filterBrowser: options?.filterBrowser,
+			autoloadOnly: options?.autoloadOnly,
 		});
 		const result = await this.connectServers(configs, sources, options?.onConnecting);
 		result.exaApiKeys = exaApiKeys;

package/src/runtime-mcp/types.ts

@@ -61,6 +61,12 @@ export interface MCPAuthConfig {
 interface MCPServerConfigBase {
 	/** Whether this server is enabled (default: true) */
 	enabled?: boolean;
+	/**
+	 * Whether to connect this server automatically at session startup (default: true).
+	 * When false the server stays configured-but-disconnected until connected
+	 * explicitly (e.g. `/mcp connect <name>`).
+	 */
+	autoload?: boolean;
 	/** Connection timeout in milliseconds (default: 30000) */
 	timeout?: number;
 	/** Authentication configuration (optional) */

package/src/sdk.ts

@@ -121,6 +121,7 @@ import { AgentOutputManager } from "./task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "./thinking";
 import { collectDiscoverableTools, type DiscoverableTool } from "./tool-discovery/tool-index";
 import {
+	applyConfiguredSearchTimeout,
 	BashTool,
 	BUILTIN_TOOLS,
 	computeEssentialBuiltinNames,
@@ -129,10 +130,10 @@ import {
 	EditTool,
 	EvalTool,
 	FindTool,
+	getConfiguredSearchProviderPreference,
 	getSearchTools,
 	HIDDEN_TOOLS,
 	isConfigurableSearchProviderId,
-	isSearchProviderPreference,
 	type LspStartupServerInfo,
 	loadSshTool,
 	ReadTool,
@@ -142,7 +143,6 @@ import {
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
-	setSearchHardTimeoutMs,
 	type Tool,
 	type ToolSession,
 	WebSearchTool,
@@ -257,7 +257,7 @@ export interface CreateAgentSessionOptions {
 	thinkingLevel?: ThinkingLevel;
 	/** Runtime substitution metadata for the initial model_change session event. */
 	modelSubstitution?: { requestedModel: Model; reason: string };
-	/** Models available for cycling (Ctrl+P in interactive mode) */
+	/** Models available for cycling (Alt+N in interactive mode) */
 	scopedModels?: ScopedModelSelection[];
 
 	/** System prompt blocks. Array replaces default, function receives default blocks and returns final blocks. */
@@ -934,20 +934,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	slashCommandsPromise.catch(() => {});
 
 	// Initialize provider preferences from settings
-	const webSearchProvider = settings.get("providers.webSearch");
-	if (typeof webSearchProvider === "string" && isSearchProviderPreference(webSearchProvider)) {
-		setPreferredSearchProvider(webSearchProvider);
-	}
+	const webSearchProvider = getConfiguredSearchProviderPreference(settings);
+	setPreferredSearchProvider(webSearchProvider);
 	const webSearchFallback = settings.get("web_search.fallback");
 	if (Array.isArray(webSearchFallback)) {
 		setSearchFallbackProviders(
 			webSearchFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
-	const webSearchTimeout = settings.get("web_search.timeout");
-	if (typeof webSearchTimeout === "number" && Number.isFinite(webSearchTimeout) && webSearchTimeout > 0) {
-		setSearchHardTimeoutMs(webSearchTimeout * 1000);
-	}
+	applyConfiguredSearchTimeout(settings);
 
 	const imageProvider = settings.get("providers.image");
 	if (
@@ -1844,6 +1839,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				intentField,
 				mcpDiscoveryMode: false,
 				mcpDiscoveryServerSummaries: [],
+				toolDiscoveryActive: effectiveDiscoveryMode === "all",
+				discoverableTools: discoverableBuiltinTools
+					.map(tool => ({ name: tool.name, summary: tool.summary }))
+					.sort((a, b) => a.name.localeCompare(b.name)),
 				eagerTasks,
 				secretsEnabled,
 				workspaceTree: workspaceTreePromise,

package/src/session/agent-session.ts

@@ -260,6 +260,7 @@ import { type EditMode, resolveEditMode } from "../utils/edit-mode";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { extractFileMentions, generateFileMentionMessages } from "../utils/file-mentions";
 import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-choice";
+import { buildWorkflowIntentDiff, WORKFLOW_INTENT_DIFF_CUSTOM_TYPE } from "../workflow/workflow-intent-diff";
 import type { AuthStorage } from "./auth-storage";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome } from "./client-bridge";
 import {
@@ -902,7 +903,7 @@ function extractPermissionLocations(
  *  custom messages queued during streaming) and is matched by the custom-role
  *  `message_start` dequeue branch; user-message pushes leave it undefined and
  *  rely on the existing text-equality match. */
-type QueuedDisplayEntry = { text: string; tag?: string };
+type QueuedDisplayEntry = { text: string; tag?: string; sequence: number };
 
 /** A custom message contributed at the before-agent-start point. */
 export type BeforeAgentStartInternalMessage = Pick<
@@ -956,6 +957,7 @@ export class AgentSession {
 	/** Tracks pending follow-up messages for UI display. Removed when delivered.
 	 *  See `#steeringMessages` for entry shape. */
 	#followUpMessages: QueuedDisplayEntry[] = [];
+	#queuedDisplaySequence = 0;
 	/** Messages queued to be included with the next user prompt as context ("asides"). */
 	#pendingNextTurnMessages: CustomMessage[] = [];
 	#scheduledHiddenNextTurnGeneration: number | undefined = undefined;
@@ -1625,6 +1627,14 @@ export class AgentSession {
 		this.#planCompactAbortPending = false;
 	}
 
+	#createQueuedDisplayEntry(text: string, tag?: string): QueuedDisplayEntry {
+		const entry: QueuedDisplayEntry = { text, sequence: ++this.#queuedDisplaySequence };
+		if (tag !== undefined) {
+			entry.tag = tag;
+		}
+		return entry;
+	}
+
 	/** Register a compact display string for a custom message that the caller is
 	 *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
 	 *  Returns a stable tag the caller MUST embed in
@@ -1638,7 +1648,7 @@ export class AgentSession {
 		const tag = `skc-cmd-${Date.now()}-${++this.#customDisplayTagCounter}`;
 		const displayText = text.trim();
 		if (!displayText) return tag;
-		const entry: QueuedDisplayEntry = { text: displayText, tag };
+		const entry = this.#createQueuedDisplayEntry(displayText, tag);
 		if (mode === "steer") {
 			this.#steeringMessages.push(entry);
 		} else {
@@ -4809,6 +4819,7 @@ export class AgentSession {
 
 		// Expand file-based prompt templates if requested
 		const expandedText = expandPromptTemplates ? expandPromptTemplate(text, [...this.#promptTemplates]) : text;
+		const workflowIntentDiff = options?.synthetic ? null : buildWorkflowIntentDiff(expandedText);
 
 		// If streaming, queue via steer() or followUp() based on option
 		if (this.isStreaming) {
@@ -4820,9 +4831,16 @@ export class AgentSession {
 			} else {
 				await this.#queueSteer(expandedText, options?.images);
 			}
+			if (workflowIntentDiff) {
+				this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
+			}
 			return;
 		}
 
+		if (workflowIntentDiff) {
+			this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
+		}
+
 		// Skip eager todo prelude when the user has already queued a directive
 		const hasPendingUserDirective = this.#toolChoiceQueue.inspect().includes("user-force");
 		const eagerTodoPrelude =
@@ -5276,7 +5294,7 @@ export class AgentSession {
 	 */
 	async #queueSteer(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#steeringMessages.push({ text: displayText });
+		this.#steeringMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -5307,7 +5325,7 @@ export class AgentSession {
 	 */
 	async #queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#followUpMessages.push({ text: displayText });
+		this.#followUpMessages.push(this.#createQueuedDisplayEntry(displayText));
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -5683,18 +5701,21 @@ export class AgentSession {
 	 * record — no orphan state can outlive the queue entry.
 	 */
 	popLastQueuedMessage(): string | undefined {
-		// Pop from steering first (LIFO)
-		if (this.#steeringMessages.length > 0) {
+		const steeringEntry = this.#steeringMessages.at(-1);
+		const followUpEntry = this.#followUpMessages.at(-1);
+
+		if (steeringEntry && (!followUpEntry || steeringEntry.sequence > followUpEntry.sequence)) {
 			const entry = this.#steeringMessages.pop();
 			this.agent.popLastSteer();
 			return entry?.text;
 		}
-		// Then from follow-up
-		if (this.#followUpMessages.length > 0) {
+
+		if (followUpEntry) {
 			const entry = this.#followUpMessages.pop();
 			this.agent.popLastFollowUp();
 			return entry?.text;
 		}
+
 		return undefined;
 	}