agent-session.ts

/**
 * AgentSession - Core abstraction for agent lifecycle and session management.
 *
 * This class is shared between all run modes (interactive, print, rpc).
 * It encapsulates:
 * - Agent state access
 * - Event subscription with automatic session persistence
 * - Model and thinking level management
 * - Compaction (manual and auto)
 * - Bash execution
 * - Session switching and branching
 *
 * Modes use this class and add their own I/O layer on top.
 */

import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { basename, dirname } from "node:path";
import {
	type Agent,
	type AgentEvent,
	type AgentMessage,
	type AgentState,
	type AgentTool,
	NOOP_TELEMETRY_CONTEXT,
	type PrepareNextTurnContext,
	type TelemetryContext,
	type ThinkingLevel,
	uuidv7,
} from "@diffexai/diffex-agent-core";
import { contentText } from "@diffexai/diffex-ai";
import type {
	AssistantMessage,
	AuthResult,
	ImageContent,
	Model,
	ProviderHeaders,
	TextContent,
	Usage,
} from "@diffexai/diffex-ai/compat";
import {
	clampThinkingLevel,
	cleanupSessionResources,
	getSupportedThinkingLevels,
	isContextOverflow,
	isRecoverableLength,
	isRetryableAssistantError,
	modelsAreEqual,
	type RetryCallbacks,
	resetApiProviders,
	streamSimple,
} from "@diffexai/diffex-ai/compat";
import type {
	HarnessStateStore,
	HarnessVersion,
	HarnessVersionBundle,
	HarnessVersionList,
	HarnessWorkspaceIdentity,
} from "@diffexai/diffex-harness-state";
import { getThemeByName, theme } from "../modes/interactive/theme/theme.ts";
import { type BackgroundProcessPolicy, OwnedShellProcesses } from "../utils/owned-shell-processes.ts";
import { canonicalizePath, resolvePath } from "../utils/paths.ts";
import { sleep } from "../utils/sleep.ts";
import { normalizeToolResultImages } from "../utils/tool-result-images.ts";
import type { AgentSessionLifecycleObserver } from "./agent-session-lifecycle.ts";
import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.ts";
import { type BashResult, executeBashWithOperations } from "./bash-executor.ts";
import {
	CHANGE_COLLABORATION_MODE,
	COLLABORATION_MODE_CUSTOM_TYPE,
	type CollaborationMode,
	type CollaborationModeTransitionResult,
	GET_COLLABORATION_MODE,
	IS_COLLABORATION_MODE_BUSY,
	PLAN_MODE_SYSTEM_PROMPT,
	PLAN_MODE_TOOL_NAMES,
	planHandoffSettlementGuards,
	SUBSCRIBE_PROMPT_ADMISSION,
} from "./collaboration-mode.ts";
import {
	type CompactionResult,
	calculateContextTokens,
	collectEntriesForBranchSummary,
	compact,
	estimateContextTokens,
	estimateTokens,
	generateBranchSummary,
	prepareCompaction,
	shouldCompact,
} from "./compaction/index.ts";
import { createSessionUpdatePlanToolDefinition, formatCurrentPlanSnapshot } from "./current-plan-state.ts";
import { DEFAULT_THINKING_LEVEL } from "./defaults.ts";
import { exportSessionToHtml, type ToolHtmlRenderer } from "./export-html/index.ts";
import { createToolHtmlRenderer } from "./export-html/tool-renderer.ts";
import {
	type ContextUsage,
	type ExtensionCommandContextActions,
	type ExtensionErrorListener,
	type ExtensionMode,
	ExtensionRunner,
	type ExtensionUIContext,
	type InputSource,
	type MessageEndEvent,
	type MessageStartEvent,
	type MessageUpdateEvent,
	type ReplacedSessionContext,
	type SessionBeforeCompactResult,
	type SessionBeforeTreeResult,
	type SessionStartEvent,
	type ShutdownHandler,
	type ToolDefinition,
	type ToolExecutionEndEvent,
	type ToolExecutionStartEvent,
	type ToolExecutionUpdateEvent,
	type ToolInfo,
	type TreePreparation,
	type TurnEndEvent,
	type TurnStartEvent,
	wrapRegisteredTools,
} from "./extensions/index.ts";
import { emitSessionShutdownEvent } from "./extensions/runner.ts";
import { parseFinalizedPlanResponse } from "./finalized-plan.ts";
import type { BashExecutionMessage, CustomMessage } from "./messages.ts";
import { ModelRegistry } from "./model-registry.ts";
import type { ModelRuntime } from "./model-runtime.ts";
import { expandPromptTemplate, type PromptTemplate } from "./prompt-templates.ts";
import type { ResourceExtensionPaths, ResourceLoader } from "./resource-loader.ts";
import type {
	BranchSummaryEntry,
	CompactionAppendTransaction,
	SessionEntry,
	SessionManager,
} from "./session-manager.ts";
import {
	appendCompactionTransaction,
	appendCustomEntryWithRollback,
	appendCustomMessageWithRollback,
	CURRENT_SESSION_VERSION,
	getLatestCompactionEntry,
	type SessionHeader,
} from "./session-manager.ts";
import type { SettingsManager } from "./settings-manager.ts";
import {
	createEvolvedSkillCatalog,
	createSkillReferenceSnapshot,
	formatSkillReferenceSnapshot,
	isSkillListedInPrompt,
	type Skill,
	type SkillReference,
	type SkillReferenceSnapshot,
} from "./skills.ts";
import type { SlashCommandInfo } from "./slash-commands.ts";
import { createSyntheticSourceInfo, type SourceInfo } from "./source-info.ts";
import type { SubagentController } from "./subagents/controller.ts";
import { hasFixedHarnessSubagentSession } from "./subagents/session-runtime.ts";
import type { SubagentBatchResult, SubagentDeliveryBatch, SubagentSummary } from "./subagents/types.ts";
import { type BuildSystemPromptOptions, buildSystemPrompt } from "./system-prompt.ts";
import { type CodingAgentTelemetrySpan, startCodingAgentSpan } from "./telemetry.ts";
import { type BashOperations, createLocalBashOperations } from "./tools/bash.ts";
import { createAllToolDefinitions } from "./tools/index.ts";
import { createRequestUserInputToolDefinition, REQUEST_USER_INPUT_TOOL_NAME } from "./tools/request-user-input.ts";
import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.ts";
import { addUsageToTotals, createUsageTotals } from "./usage-totals.ts";

// ============================================================================
// Skill Block Parsing
// ============================================================================

/** Parsed skill block from a user message */
export interface ParsedSkillBlock {
	name: string;
	location: string;
	content: string;
	userMessage: string | undefined;
}

export interface ParsedSkillInvocation {
	skills: ParsedSkillBlock[];
	userMessage: string | undefined;
}

function unescapeXmlAttribute(value: string): string {
	return value
		.replace(/"/g, '"')
		.replace(/'/g, "'")
		.replace(/>/g, ">")
		.replace(/&lt;/g, "<")
		.replace(/&amp;/g, "&");
}

export function parseSkillInvocation(text: string): ParsedSkillInvocation | null {
	const skills: ParsedSkillBlock[] = [];
	let remaining = text;
	while (remaining.startsWith("<skill ")) {
		const match = remaining.match(/^<skill ([^>\n]+)>\n([\s\S]*?)\n<\/skill>(?:\n\n|$)/);
		if (!match) return null;
		const attributes = new Map<string, string>();
		for (const attribute of match[1].matchAll(/([a-z-]+)="([^"]*)"/g)) {
			attributes.set(attribute[1], unescapeXmlAttribute(attribute[2]));
		}
		const name = attributes.get("name");
		const location = attributes.get("location");
		if (!name || !location) return null;
		skills.push({ name, location, content: match[2], userMessage: undefined });
		remaining = remaining.slice(match[0].length);
	}
	if (skills.length === 0) return null;
	const userMessage = remaining.trim() || undefined;
	return {
		skills: skills.map((skill) => ({ ...skill, userMessage })),
		userMessage,
	};
}

/**
 * Parse one skill block from message text.
 * Returns null for ordinary text and multi-skill invocations.
 */
export function parseSkillBlock(text: string): ParsedSkillBlock | null {
	const invocation = parseSkillInvocation(text);
	return invocation?.skills.length === 1 ? invocation.skills[0] : null;
}

interface SkillExpansion {
	text: string;
	references: SkillReferenceSnapshot[];
	forceLoaded: SkillReferenceSnapshot[];
}

interface ActiveSkillTrace {
	operationSpan: CodingAgentTelemetrySpan<"diffex.coding_agent.operation">;
	skills: readonly SkillReferenceSnapshot[];
}

const SKILL_REFERENCE_PATTERN =
	/<skill-reference id="(skill:[a-f0-9]{64})" version="(sha256:[a-f0-9]{64})" name="[^"]*"( load="force")?\/>/g;

/** Session-specific events that extend the core AgentEvent */
export type AgentSessionEvent =
	| Exclude<AgentEvent, { type: "agent_end" }>
	| {
			type: "agent_end";
			messages: AgentMessage[];
			willRetry: boolean;
	  }
	| { type: "agent_settled"; planHandoff?: { readonly plan: string } }
	| {
			type: "queue_update";
			steering: readonly string[];
			followUp: readonly string[];
	  }
	| { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
	| { type: "entry_appended"; entry: SessionEntry }
	| { type: "session_info_changed"; name: string | undefined }
	| { type: "thinking_level_changed"; level: ThinkingLevel }
	| {
			type: "compaction_end";
			reason: "manual" | "threshold" | "overflow";
			result: CompactionResult | undefined;
			aborted: boolean;
			willRetry: boolean;
			errorMessage?: string;
	  }
	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
	| {
			type: "summarization_retry_scheduled";
			attempt: number;
			maxAttempts: number;
			delayMs: number;
			errorMessage: string;
	  }
	| { type: "summarization_retry_attempt_start"; source: "branchSummary" }
	| {
			type: "summarization_retry_attempt_start";
			source: "compaction";
			reason: "manual" | "threshold" | "overflow";
	  }
	| { type: "summarization_retry_finished" }
	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
	| { type: "subagent_wait_start"; names: readonly string[] }
	| { type: "subagent_wait_end"; names: readonly string[]; cancelled: boolean }
	| {
			type: "subagent_notice";
			name: string;
			status: "idle" | "failed" | "interrupted";
			attempt: "initial" | "retry";
			retryAvailable: boolean;
			text: string;
	  }
	| { type: "bash_execution_update"; id?: string; delta: string };

/** Listener function for agent session events */
export type AgentSessionEventListener = (event: AgentSessionEvent) => void;

// ============================================================================
// Types
// ============================================================================

function withoutDeletedHeaders(headers: ProviderHeaders | undefined): Record<string, string> | undefined {
	return headers
		? Object.fromEntries(Object.entries(headers).filter((entry): entry is [string, string] => entry[1] !== null))
		: undefined;
}

export interface AgentSessionConfig {
	/** Lifetime of background groups launched by successful local shell commands. */
	backgroundProcessPolicy?: BackgroundProcessPolicy;
	agent: Agent;
	sessionManager: SessionManager;
	settingsManager: SettingsManager;
	cwd: string;
	/** Models to cycle through with Ctrl+P (from --models flag) */
	scopedModels?: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>;
	/** Resource loader for extensions, skills, prompts, themes, context files, and system prompt */
	resourceLoader: ResourceLoader;
	/** SDK custom tools registered outside extensions */
	customTools?: ToolDefinition[];
	/** Canonical model/auth runtime used by coding-agent internals. */
	modelRuntime: ModelRuntime;
	/** Initial active built-in tool names. Default: [read, bash, edit, write, update_plan] */
	initialActiveToolNames?: string[];
	/** Optional allowlist of tool names. When provided, only these tool names are exposed. */
	allowedToolNames?: string[];
	/** Optional denylist of tool names. When provided, these tool names are not exposed. */
	excludedToolNames?: string[];
	/**
	 * Override base tools (useful for custom runtimes).
	 *
	 * These are synthesized into minimal ToolDefinitions internally so AgentSession can keep
	 * a definition-first registry even when callers provide plain AgentTool instances.
	 */
	baseToolsOverride?: Record<string, AgentTool>;
	/** Mutable ref used by Agent to access the current ExtensionRunner */
	extensionRunnerRef?: { current?: ExtensionRunner };
	/** Session start event metadata emitted when extensions bind to this runtime. */
	sessionStartEvent?: SessionStartEvent;
	/** Lifecycle-owned child-agent controller. */
	subagentController?: SubagentController;
	/** Global immutable harness revision store. */
	harnessStateStore?: HarnessStateStore;
	/** Harness revision activated for this session. */
	harnessVersionBundle?: HarnessVersionBundle;
	/** Stable identity used to scope evolved harness skills. */
	workspaceIdentity?: HarnessWorkspaceIdentity;
	/** Keep the supplied harness revision fixed instead of refreshing it after compaction. */
	pinHarnessVersion?: boolean;
	/** Parent context for passive runtime telemetry. */
	telemetryContext?: TelemetryContext;
	/** Process-owned observer for durable lifecycle boundaries. */
	lifecycleObserver?: AgentSessionLifecycleObserver;
}

export interface ExtensionBindings {
	uiContext?: ExtensionUIContext;
	mode?: ExtensionMode;
	commandContextActions?: ExtensionCommandContextActions;
	abortHandler?: () => void;
	shutdownHandler?: ShutdownHandler;
	onError?: ExtensionErrorListener;
}

/** Options for AgentSession.prompt() */
export interface PromptOptions {
	/** Whether to expand file-based prompt templates (default: true) */
	expandPromptTemplates?: boolean;
	/** Image attachments */
	images?: ImageContent[];
	/** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */
	streamingBehavior?: "steer" | "followUp";
	/** Source of input for extension input event handlers. Defaults to "interactive". */
	source?: InputSource;
	/** Internal hook used by RPC mode to observe prompt preflight acceptance or rejection. */
	preflightResult?: (success: boolean) => void;
	/** Cancel prompt preflight or abort the active run after it starts. */
	signal?: AbortSignal;
}

/** Result from cycleModel() */
export interface ModelCycleResult {
	model: Model<any>;
	thinkingLevel: ThinkingLevel;
	/** Whether cycling through scoped models (--models flag) or all available */
	isScoped: boolean;
}

/** Session statistics for /session command */
export interface SessionStats {
	sessionFile: string | undefined;
	sessionId: string;
	userMessages: number;
	assistantMessages: number;
	toolCalls: number;
	toolResults: number;
	totalMessages: number;
	tokens: {
		input: number;
		output: number;
		cacheRead: number;
		cacheWrite: number;
		total: number;
	};
	cost: number;
	contextUsage?: ContextUsage;
}

interface ToolDefinitionEntry {
	definition: ToolDefinition;
	sourceInfo: SourceInfo;
}

interface SubagentEscalationEntry {
	readonly name: string;
	readonly message: string;
}

interface PendingSubagentEscalationEnvelope {
	readonly message: CustomMessage<{ names: string[] }>;
	readonly escalations: SubagentEscalationEntry[];
	messageCharacters: number;
}

interface SubagentCoordination {
	readonly batch: SubagentDeliveryBatch;
	readonly names: readonly string[];
	readonly terminalNotices: Set<string>;
	currentWaitAbortController?: AbortController;
	exitReason?: "escalation" | "cancellation";
	waitStarted: boolean;
	completionChecked?: boolean;
}

interface PromptReservation {
	readonly signaled: boolean;
	readonly collaborationMode: CollaborationMode;
	readonly collaborationState?: CollaborationModeState;
	agentStarted: boolean;
}

interface CollaborationModeState {
	readonly mode: CollaborationMode;
	readonly baseSystemPrompt: string;
	readonly baseSystemPromptOptions: BuildSystemPromptOptions;
	readonly effectiveSystemPrompt: string;
	readonly effectiveToolDefinitions: Map<string, ToolDefinitionEntry>;
	readonly tools: AgentTool[];
}

function estimateMessagesTokens(messages: AgentMessage[]): number {
	let tokens = 0;
	for (const message of messages) {
		tokens += estimateTokens(message);
	}
	return tokens;
}

// ============================================================================
// Constants
// ============================================================================

/** Standard thinking levels */
const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high"];
const MAX_PENDING_SUBAGENT_ESCALATION_CHARACTERS = 8_000;
const INCOMPATIBLE_SUBAGENT_PARENT_HOOKS = [
	"resources_discover",
	"input",
	"context",
	"before_agent_start",
	"before_provider_request",
	"before_provider_headers",
	"session_before_compact",
	"tool_call",
	"tool_result",
	"message_end",
] as const;

// ============================================================================
// AgentSession Class
// ============================================================================

export class AgentSession {
	readonly agent: Agent;
	readonly sessionManager: SessionManager;
	readonly settingsManager: SettingsManager;

	private _scopedModels: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>;

	// Event subscription state
	private _unsubscribeAgent?: () => void;
	private _eventListeners: AgentSessionEventListener[] = [];
	private _isAgentRunActive = false;
	private readonly _promptReservations = new Set<PromptReservation>();
	private _idleWaitPromise: Promise<void> | undefined;
	private _resolveIdleWait: (() => void) | undefined;

	/** Tracks pending steering messages for UI display. Removed when delivered. */
	private _steeringMessages: string[] = [];
	/** Tracks pending follow-up messages for UI display. Removed when delivered. */
	private _followUpMessages: string[] = [];
	/** Messages queued to be included with the next user prompt as context ("asides"). */
	private _pendingNextTurnMessages: CustomMessage[] = [];
	private readonly _skillReferenceSnapshots = new Map<string, SkillReferenceSnapshot>();
	private readonly _skillEnablementOverrides = new Map<string, boolean>();
	private _activeSkillTrace: ActiveSkillTrace | undefined;

	// Compaction state
	private _compactionAbortController: AbortController | undefined = undefined;
	private _autoCompactionAbortController: AbortController | undefined = undefined;
	private _overflowRecoveryAttempted = false;

	// Branch summarization state
	private _branchSummaryAbortController: AbortController | undefined = undefined;

	// Retry state
	private _retryAbortController: AbortController | undefined = undefined;
	private _retryAttempt = 0;

	// Bash execution state
	private readonly _bashAbortControllers = new Set<AbortController>();
	private _pendingBashMessages: BashExecutionMessage[] = [];
	private readonly _ownedOperations = new Set<Promise<unknown>>();
	private readonly _shellProcesses: OwnedShellProcesses;
	private readonly _bashOperations = new Set<Promise<BashResult>>();

	// Extension system
	private _extensionRunner!: ExtensionRunner;
	private _turnIndex = 0;

	private _resourceLoader: ResourceLoader;
	private _customTools: ToolDefinition[];
	private _baseToolDefinitions: Map<string, ToolDefinition> = new Map();
	private _baseToolRegistry: Map<string, AgentTool> = new Map();
	private _requestUserInputDefinition: ToolDefinition | undefined;
	private _requestUserInputTool: AgentTool | undefined;
	private _cwd: string;
	private _extensionRunnerRef?: { current?: ExtensionRunner };
	private _initialActiveToolNames?: string[];
	private _allowedToolNames?: Set<string>;
	private _excludedToolNames?: Set<string>;
	private _baseToolsOverride?: Record<string, AgentTool>;
	private _sessionStartEvent: SessionStartEvent;
	private _extensionUIContext?: ExtensionUIContext;
	private _extensionMode: ExtensionMode = "print";
	private _extensionCommandContextActions?: ExtensionCommandContextActions;
	private _extensionAbortHandler?: () => void;
	private _extensionShutdownHandler?: ShutdownHandler;
	private _extensionErrorListener?: ExtensionErrorListener;
	private _extensionErrorUnsubscriber?: () => void;
	private _modelRuntime: ModelRuntime;

	// Tool registry for extension getTools/setTools
	private _toolRegistry: Map<string, AgentTool> = new Map();
	private _toolDefinitions: Map<string, ToolDefinitionEntry> = new Map();
	private _effectiveToolDefinitions: Map<string, ToolDefinitionEntry> = new Map();

	// Base system prompt (without extension appends) - used to apply fresh appends each turn
	private _baseSystemPrompt = "";
	private _baseSystemPromptOptions!: BuildSystemPromptOptions;
	private _systemPromptOverride?: string;
	private _requestedToolNames: string[] = [];
	private _collaborationMode: CollaborationMode = "default";
	private _activeRunCollaborationMode: CollaborationMode | undefined;
	private _activeRunCollaborationState: CollaborationModeState | undefined;
	private _latestFinalizedPlan: string | undefined;
	private _collaborationModeTransitionInProgress = false;
	private _manualCompactionOperations = 0;
	private readonly _subagentController: SubagentController | undefined;
	private readonly _harnessStateStore: HarnessStateStore | undefined;
	private readonly _workspaceIdentity: HarnessWorkspaceIdentity | undefined;
	private readonly _pinHarnessVersion: boolean;
	private _harnessVersionBundle: HarnessVersionBundle | undefined;
	private readonly _telemetryContext: TelemetryContext;
	private readonly _lifecycleObserver: AgentSessionLifecycleObserver | undefined;
	private _harnessSwitchInProgress = false;
	private _promptAdmissionInProgress = false;
	private readonly _promptAdmissionListeners = new Set<() => void>();
	private _planHandoffGeneration = 0;
	private _subagentCoordination: SubagentCoordination | undefined;
	private _pendingSubagentEscalationEnvelope: PendingSubagentEscalationEnvelope | undefined;
	private readonly _pendingIdleSubagentEscalations = new Map<string, number>();
	private _agentRunAborted = false;
	private _disposePromise: Promise<void> | undefined;

	constructor(config: AgentSessionConfig) {
		this._shellProcesses = new OwnedShellProcesses(config.backgroundProcessPolicy);
		this.agent = config.agent;
		this.sessionManager = config.sessionManager;
		this.settingsManager = config.settingsManager;
		this._scopedModels = config.scopedModels ?? [];
		this._resourceLoader = config.resourceLoader;
		this._customTools = config.customTools ?? [];
		this._cwd = config.cwd;
		this._modelRuntime = config.modelRuntime;
		this._extensionRunnerRef = config.extensionRunnerRef;
		this._initialActiveToolNames = config.initialActiveToolNames;
		this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
		this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
		this._baseToolsOverride = config.baseToolsOverride;
		this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
		this._subagentController = config.subagentController;
		this._harnessStateStore = config.harnessStateStore;
		this._workspaceIdentity = config.workspaceIdentity;
		this._pinHarnessVersion = config.pinHarnessVersion ?? false;
		this._harnessVersionBundle = config.harnessVersionBundle;
		this._resourceLoader.setEvolvedSkills(
			config.harnessVersionBundle === undefined || config.workspaceIdentity === undefined
				? { skills: [], diagnostics: [] }
				: createEvolvedSkillCatalog(config.harnessVersionBundle, config.workspaceIdentity),
		);
		this._telemetryContext = config.telemetryContext ?? NOOP_TELEMETRY_CONTEXT;
		this._lifecycleObserver = config.lifecycleObserver;

		// Always subscribe to agent events for internal handling
		// (session persistence, extensions, auto-compaction, retry logic)
		this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
		this._installAgentToolHooks();
		this._installAgentNextTurnRefresh();

		this._buildRuntime({
			activeToolNames: this._initialActiveToolNames,
			includeAllExtensionTools: true,
		});
		this._subagentController?.bindParent(
			this,
			() => INCOMPATIBLE_SUBAGENT_PARENT_HOOKS.filter((hook) => this._extensionRunner.hasHandlers(hook)),
			(name, message) => this._acceptSubagentEscalation(name, message),
		);
	}

	get modelRuntime(): ModelRuntime {
		return this._modelRuntime;
	}

	get telemetryContext(): TelemetryContext {
		return this._telemetryContext;
	}

	get harnessStateStore(): HarnessStateStore | undefined {
		return this._harnessStateStore;
	}

	get harnessVersionBundle(): HarnessVersionBundle | undefined {
		return this._harnessVersionBundle;
	}

	private async _getRequiredRequestAuth(
		model: Model<any>,
		signal?: AbortSignal,
	): Promise<{
		model: Model<any>;
		apiKey?: string;
		headers?: Record<string, string>;
		env?: Record<string, string>;
	}> {
		let result: AuthResult | undefined;
		try {
			result = await this._modelRuntime.getAuth(model, { signal });
		} catch (error) {
			const cause = error instanceof Error ? error.cause : undefined;
			if (cause instanceof Error && cause.message === "authHeader requires a resolved API key") {
				throw new Error(formatNoApiKeyFoundMessage(model.provider));
			}
			throw error;
		}
		if (result && (result.auth.apiKey || result.auth.headers)) {
			const requestModel = result.auth.baseUrl ? { ...model, baseUrl: result.auth.baseUrl } : model;
			return {
				model: requestModel,
				apiKey: result.auth.apiKey,
				headers: withoutDeletedHeaders(result.auth.headers),
				env: result.env,
			};
		}

		const isOAuth = this._modelRuntime.isUsingOAuth(model.provider);
		if (isOAuth) {
			throw new Error(
				`Authentication failed for "${model.provider}". ` +
					`Credentials may have expired or network is unavailable. ` +
					`Run '/login ${model.provider}' to re-authenticate.`,
			);
		}
		throw new Error(formatNoApiKeyFoundMessage(model.provider));
	}

	private async _getSummarizationRequestAuth(
		model: Model<any>,
		signal?: AbortSignal,
	): Promise<{
		model: Model<any>;
		apiKey?: string;
		headers?: Record<string, string>;
		env?: Record<string, string>;
	}> {
		if (this.agent.streamFunction === streamSimple) {
			return this._getRequiredRequestAuth(model, signal);
		}

		try {
			const result = await this._modelRuntime.getAuth(model, { signal });
			signal?.throwIfAborted();
			if (!result) return { model };
			const requestModel = result.auth.baseUrl ? { ...model, baseUrl: result.auth.baseUrl } : model;
			return {
				model: requestModel,
				apiKey: result.auth.apiKey,
				headers: withoutDeletedHeaders(result.auth.headers),
				env: result.env,
			};
		} catch {
			if (signal?.aborted) throw signal.reason;
			return { model };
		}
	}

	/**
	 * Install tool hooks once on the Agent instance.
	 *
	 * The callbacks read `this._extensionRunner` at execution time, so extension reload swaps in the
	 * new runner without reinstalling hooks. Extension-specific tool wrappers are still used to adapt
	 * registered tool execution to the extension context. Tool call and tool result interception now
	 * happens here instead of in wrappers.
	 */
	private _installAgentToolHooks(): void {
		this.agent.beforeToolCall = async ({ toolCall, args, context }) => {
			if (toolCall.name === REQUEST_USER_INPUT_TOOL_NAME && this._activeRunCollaborationMode !== "plan") {
				return {
					block: true,
					reason: `Tool "${REQUEST_USER_INPUT_TOOL_NAME}" is unavailable outside Plan mode.`,
				};
			}
			if (this._activeRunCollaborationMode === "plan") {
				const capturedTool = this._activeRunCollaborationState?.tools.find((tool) => tool.name === toolCall.name);
				const activeTool = context.tools?.find((tool) => tool.name === toolCall.name);
				if (!(PLAN_MODE_TOOL_NAMES as readonly string[]).includes(toolCall.name) || activeTool !== capturedTool) {
					return {
						block: true,
						reason: `Tool "${toolCall.name}" is unavailable in Plan mode.`,
					};
				}
			}
			const runner = this._extensionRunner;
			if (!runner.hasHandlers("tool_call")) {
				return undefined;
			}

			try {
				return await runner.emitToolCall({
					type: "tool_call",
					toolName: toolCall.name,
					toolCallId: toolCall.id,
					input: args as Record<string, unknown>,
				});
			} catch (err) {
				if (err instanceof Error) {
					throw err;
				}
				throw new Error(`Extension failed, blocking execution: ${String(err)}`);
			}
		};

		this.agent.afterToolCall = async ({ toolCall, args, result, isError }) => {
			const runner = this._extensionRunner;
			const hookResult = runner.hasHandlers("tool_result")
				? await runner.emitToolResult({
						type: "tool_result",
						toolName: toolCall.name,
						toolCallId: toolCall.id,
						input: args as Record<string, unknown>,
						content: result.content,
						details: result.details,
						isError,
						usage: result.usage,
					})
				: undefined;

			const content = hookResult?.content ?? result.content ?? [];
			// Runs after the extension hook so images injected or replaced by extensions are normalized too.
			const normalizedContent = await normalizeToolResultImages(content, {
				autoResizeImages: this.settingsManager.getImageAutoResize(),
			});
			this._recordSkillRead(toolCall.name, args, result.details, hookResult?.isError ?? isError);

			if (!hookResult && normalizedContent === content) {
				return undefined;
			}

			return {
				content: normalizedContent,
				details: hookResult?.details,
				isError: hookResult?.isError ?? isError,
				usage: hookResult?.usage,
			};
		};
	}

	private _installAgentNextTurnRefresh(): void {
		const previousPrepareNextTurnWithContext =
			this.agent.prepareNextTurnWithContext ??
			(this.agent.prepareNextTurn
				? async (_turn: PrepareNextTurnContext, signal?: AbortSignal) => await this.agent.prepareNextTurn?.(signal)
				: undefined);
		this.agent.prepareNextTurnWithContext = async (turn, signal) => {
			const previousSnapshot = await previousPrepareNextTurnWithContext?.(turn, signal);
			const previousContext = previousSnapshot?.context ?? turn.context;
			let messages = previousContext.messages;
			// Tool output is part of the next request even though the model's usage
			// only describes the request before that output. Check every complete batch.
			if (turn.toolResults.length > 0 && !signal?.aborted && this.model) {
				const settings = this.settingsManager.getCompactionSettings();
				if (shouldCompact(estimateContextTokens(messages).tokens, this.model.contextWindow, settings)) {
					const beforeCompaction = this.agent.state.messages;
					await this._runAutoCompaction("threshold", true, signal);
					if (this.agent.state.messages !== beforeCompaction) {
						messages = this.agent.state.messages;
					}
				}
			}

			signal?.throwIfAborted();
			return {
				...previousSnapshot,
				context: {
					...previousContext,
					messages,
					systemPrompt:
						this._activeRunCollaborationState?.effectiveSystemPrompt ??
						this._deriveEffectivePrompt(
							this._systemPromptOverride ?? this._baseSystemPrompt,
							this._activeRunCollaborationMode ?? this._collaborationMode,
						),
					tools: (this._activeRunCollaborationState?.tools ?? this.agent.state.tools).slice(),
				},
				model: this.agent.state.model,
				thinkingLevel: this.agent.state.thinkingLevel,
			};
		};
	}

	// =========================================================================
	// Event Subscription
	// =========================================================================

	/** Emit an event to all listeners */
	private _emit(event: AgentSessionEvent): void {
		for (const l of this._eventListeners) {
			l(event);
		}
	}

	private _emitQueueUpdate(): void {
		this._emit({
			type: "queue_update",
			steering: [...this._steeringMessages],
			followUp: [...this._followUpMessages],
		});
	}

	private _getIdleWaitPromise(): Promise<void> {
		if (!this._idleWaitPromise) {
			this._idleWaitPromise = new Promise((resolve) => {
				this._resolveIdleWait = resolve;
			});
		}
		return this._idleWaitPromise;
	}

	private _resolveIdleWaitIfIdle(): void {
		if (this._isAgentRunActive || !this._resolveIdleWait) {
			return;
		}
		const resolve = this._resolveIdleWait;
		this._idleWaitPromise = undefined;
		this._resolveIdleWait = undefined;
		resolve();
	}

	private async _emitAgentSettled(planHandoff?: { readonly plan: string }): Promise<void> {
		const generation = this._planHandoffGeneration;
		const event = { type: "agent_settled", ...(planHandoff ? { planHandoff } : {}) } as const;
		planHandoffSettlementGuards.set(event, () => !this._disposePromise && generation === this._planHandoffGeneration);
		this._isAgentRunActive = false;
		try {
			await this._extensionRunner.emit({ type: "agent_settled" });
			this._emit(event);
		} finally {
			this._resolveIdleWaitIfIdle();
		}
	}

	// Track last assistant message for auto-compaction check
	private _lastAssistantMessage: AssistantMessage | undefined = undefined;

	/** Internal handler for agent events - shared by subscribe and reconnect */
	private _handleAgentEvent = async (event: AgentEvent): Promise<void> => {
		if (event.type === "agent_start") {
			for (const reservation of this._promptReservations) {
				if (!reservation.signaled) continue;
				reservation.agentStarted = true;
				break;
			}
		}
		if (event.type === "message_start" && this._pendingSubagentEscalationEnvelope?.message === event.message) {
			// The exact queued object is now entering parent context. Seal it so later reports form a new envelope.
			this._pendingSubagentEscalationEnvelope = undefined;
			const coordination = this._subagentCoordination;
			if (coordination?.exitReason === "escalation") coordination.exitReason = undefined;
		}
		// When a user message starts, check if it's from either queue and remove it BEFORE emitting
		// This ensures the UI sees the updated queue state
		if (event.type === "message_start" && event.message.role === "user") {
			this._latestFinalizedPlan = undefined;
			this._subagentController?.beginCoordinationCycle();
			this._overflowRecoveryAttempted = false;
			const messageText = contentText(event.message.content, "");
			if (messageText) {
				// Check steering queue first
				const steeringIndex = this._steeringMessages.indexOf(messageText);
				if (steeringIndex !== -1) {
					this._steeringMessages.splice(steeringIndex, 1);
					this._emitQueueUpdate();
				} else {
					// Check follow-up queue
					const followUpIndex = this._followUpMessages.indexOf(messageText);
					if (followUpIndex !== -1) {
						this._followUpMessages.splice(followUpIndex, 1);
						this._emitQueueUpdate();
					}
				}
			}
		}

		// Emit to extensions first
		await this._emitExtensionEvent(event);
		if (
			event.type === "message_end" &&
			event.message.role === "assistant" &&
			event.message.stopReason !== "pending" &&
			event.message.stopReason !== "toolUse"
		) {
			this._latestFinalizedPlan = undefined;
			if (this._activeRunCollaborationMode === "plan") {
				const finalizedPlan = parseFinalizedPlanResponse(event.message);
				if (finalizedPlan) {
					this._replaceMessageInPlace(event.message, finalizedPlan.message);
					this._latestFinalizedPlan = finalizedPlan.plan;
				}
			}
		}

		// Notify all listeners
		this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);

		// Handle session persistence
		if (event.type === "message_end") {
			// Check if this is a custom message from extensions
			if (event.message.role === "custom") {
				// Persist as CustomMessageEntry
				this.sessionManager.appendCustomMessageEntry(
					event.message.customType,
					event.message.content,
					event.message.display,
					event.message.details,
				);
			} else if (
				event.message.role === "user" ||
				event.message.role === "assistant" ||
				event.message.role === "toolResult"
			) {
				// Regular LLM message - persist as SessionMessageEntry
				this.sessionManager.appendMessage(event.message);
			}
			// Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere

			// Track assistant message for auto-compaction (checked on agent_end)
			if (event.message.role === "assistant") {
				this._lastAssistantMessage = event.message;

				const assistantMsg = event.message as AssistantMessage;
				if (assistantMsg.stopReason !== "error" && assistantMsg.stopReason !== "length") {
					this._overflowRecoveryAttempted = false;
				}

				// Reset retry counter immediately on successful assistant response
				// This prevents accumulation across multiple LLM calls within a turn
				if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
					this._emit({
						type: "auto_retry_end",
						success: true,
						attempt: this._retryAttempt,
					});
					this._retryAttempt = 0;
				}
			}
		}
	};

	private _willRetryAfterAgentEnd(event: Extract<AgentEvent, { type: "agent_end" }>): boolean {
		const settings = this.settingsManager.getRetrySettings();
		if (!settings.enabled || this._retryAttempt >= settings.maxRetries) {
			return false;
		}

		for (let i = event.messages.length - 1; i >= 0; i--) {
			const message = event.messages[i];
			if (message.role === "assistant") {
				return this._isRetryableError(message as AssistantMessage);
			}
		}
		return false;
	}

	/** Find the last assistant message in agent state (including aborted ones) */
	private _findLastAssistantMessage(): AssistantMessage | undefined {
		const messages = this.agent.state.messages;
		for (let i = messages.length - 1; i >= 0; i--) {
			const msg = messages[i];
			if (msg.role === "assistant") {
				return msg as AssistantMessage;
			}
		}
		return undefined;
	}

	private _replaceMessageInPlace(target: AgentMessage, replacement: AgentMessage): void {
		// Agent-core stores the finalized message object in its state before emitting message_end.
		// SessionManager persistence happens later in _handleAgentEvent() with event.message.
		// Mutating this object in place keeps agent state, later turn/agent events, listeners,
		// and the eventual SessionManager.appendMessage(event.message) persistence in sync.
		if (target === replacement) {
			return;
		}

		const targetRecord = target as unknown as Record<string, unknown>;
		for (const key of Object.keys(targetRecord)) {
			delete targetRecord[key];
		}
		Object.assign(targetRecord, replacement);
	}

	/** Emit extension events based on agent events */
	private async _emitExtensionEvent(event: AgentEvent): Promise<void> {
		if (event.type === "agent_start") {
			this._turnIndex = 0;
			await this._extensionRunner.emit({ type: "agent_start" });
		} else if (event.type === "agent_end") {
			await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
		} else if (event.type === "turn_start") {
			const extensionEvent: TurnStartEvent = {
				type: "turn_start",
				turnIndex: this._turnIndex,
				timestamp: Date.now(),
			};
			await this._extensionRunner.emit(extensionEvent);
		} else if (event.type === "turn_end") {
			const extensionEvent: TurnEndEvent = {
				type: "turn_end",
				turnIndex: this._turnIndex,
				message: event.message,
				toolResults: event.toolResults,
			};
			await this._extensionRunner.emit(extensionEvent);
			this._turnIndex++;
		} else if (event.type === "message_start") {
			const extensionEvent: MessageStartEvent = {
				type: "message_start",
				message: event.message,
			};
			await this._extensionRunner.emit(extensionEvent);
		} else if (event.type === "message_update") {
			const extensionEvent: MessageUpdateEvent = {
				type: "message_update",
				message: event.message,
				assistantMessageEvent: event.assistantMessageEvent,
			};
			await this._extensionRunner.emit(extensionEvent);
		} else if (event.type === "message_end") {
			const extensionEvent: MessageEndEvent = {
				type: "message_end",
				message: event.message,
			};
			const replacement = await this._extensionRunner.emitMessageEnd(extensionEvent);
			if (replacement) {
				// Untyped extension handlers can return messages with null/missing content;
				// normalize so it never enters agent state or session history.
				const normalized =
					(replacement.role === "user" ||
						replacement.role === "assistant" ||
						replacement.role === "toolResult" ||
						replacement.role === "custom") &&
					replacement.content == null
						? ({ ...replacement, content: [] } as AgentMessage)
						: replacement;
				this._replaceMessageInPlace(event.message, normalized);
			}
		} else if (event.type === "tool_execution_start") {
			const extensionEvent: ToolExecutionStartEvent = {
				type: "tool_execution_start",
				toolCallId: event.toolCallId,
				toolName: event.toolName,
				args: event.args,
			};
			await this._extensionRunner.emit(extensionEvent);
		} else if (event.type === "tool_execution_update") {
			const extensionEvent: ToolExecutionUpdateEvent = {
				type: "tool_execution_update",
				toolCallId: event.toolCallId,
				toolName: event.toolName,
				args: event.args,
				partialResult: event.partialResult,
			};
			await this._extensionRunner.emit(extensionEvent);
		} else if (event.type === "tool_execution_end") {
			const extensionEvent: ToolExecutionEndEvent = {
				type: "tool_execution_end",
				toolCallId: event.toolCallId,
				toolName: event.toolName,
				result: event.result,
				isError: event.isError,
			};
			await this._extensionRunner.emit(extensionEvent);
		}
	}

	/**
	 * Subscribe to agent events.
	 * Session persistence is handled internally (saves messages on message_end).
	 * Multiple listeners can be added. Returns unsubscribe function for this listener.
	 */
	subscribe(listener: AgentSessionEventListener): () => void {
		this._eventListeners.push(listener);

		// Return unsubscribe function for this specific listener
		return () => {
			const index = this._eventListeners.indexOf(listener);
			if (index !== -1) {
				this._eventListeners.splice(index, 1);
			}
		};
	}

	/** Disconnect from agent events during disposal. */
	private _disconnectFromAgent(): void {
		if (this._unsubscribeAgent) {
			this._unsubscribeAgent();
			this._unsubscribeAgent = undefined;
		}
	}

	/**
	 * Remove all listeners and disconnect from agent.
	 * Call this when completely done with the session.
	 */
	dispose(): Promise<void> {
		if (this._disposePromise) return this._disposePromise;

		let resolveDispose!: () => void;
		let rejectDispose!: (reason: unknown) => void;
		const disposePromise = new Promise<void>((resolve, reject) => {
			resolveDispose = resolve;
			rejectDispose = reject;
		});
		this._disposePromise = disposePromise;
		this._exitSubagentCoordination("cancellation");
		let childCleanup: Promise<void> | undefined;
		try {
			childCleanup = this._subagentController?.shutdown();
		} catch (error) {
			childCleanup = Promise.reject(error);
		}
		void this._finishDispose(childCleanup).then(resolveDispose, rejectDispose);
		return disposePromise;
	}

	private _runOwnedOperation<T>(run: () => Promise<T>): Promise<T> {
		if (this._disposePromise) {
			return Promise.reject(new Error("Agent session is disposed"));
		}

		let resolveOperation!: (value: T | PromiseLike<T>) => void;
		let rejectOperation!: (reason: unknown) => void;
		const operation = new Promise<T>((resolve, reject) => {
			resolveOperation = resolve;
			rejectOperation = reject;
		});
		this._ownedOperations.add(operation);
		try {
			void run().then(resolveOperation, rejectOperation);
		} catch (error) {
			rejectOperation(error);
		}
		void operation.then(
			() => this._ownedOperations.delete(operation),
			() => this._ownedOperations.delete(operation),
		);
		return operation;
	}

	private async _waitForOwnedOperations(): Promise<void> {
		while (this._ownedOperations.size > 0) {
			await Promise.allSettled([...this._ownedOperations]);
		}
	}

	private async _finishDispose(childCleanup: Promise<void> | undefined): Promise<void> {
		const failures: unknown[] = [];
		this._pendingIdleSubagentEscalations.clear();
		try {
			this.clearQueue();
		} catch (error) {
			failures.push(error);
		}
		for (const abort of [
			() => this.abortRetry(),
			() => this.abortCompaction(),
			() => this.abortBranchSummary(),
			() => this.abortBash(),
		]) {
			try {
				abort();
			} catch (error) {
				failures.push(error);
			}
		}

		let rootIdle: Promise<void> | undefined;
		try {
			this.agent.abort();
			rootIdle = this.waitForIdle();
		} catch (error) {
			failures.push(error);
		}
		const ownedOperationsIdle = this._waitForOwnedOperations();

		const cleanupResults = await Promise.allSettled(
			[childCleanup, rootIdle, ownedOperationsIdle, this.terminateOwnedShellProcesses()].filter(
				(promise): promise is Promise<void> => promise !== undefined,
			),
		);
		for (const result of cleanupResults) {
			if (result.status !== "rejected") continue;
			if (result.reason instanceof AggregateError) {
				failures.push(...result.reason.errors);
			} else {
				failures.push(result.reason);
			}
		}

		try {
			this._extensionRunner.invalidate(
				"This extension ctx is stale after session replacement or reload. Do not use a captured diffex or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().",
			);
		} catch (error) {
			failures.push(error);
		}
		try {
			this._disconnectFromAgent();
		} catch (error) {
			failures.push(error);
		}
		this._eventListeners = [];
		this._promptAdmissionListeners.clear();
		try {
			cleanupSessionResources(this.sessionId);
		} catch (error) {
			failures.push(error);
		}

		if (failures.length > 0) {
			throw new AggregateError(failures, "Failed to dispose agent session");
		}
	}

	// =========================================================================
	// Read-only State Access
	// =========================================================================

	/** Full agent state */
	get state(): AgentState {
		return this.agent.state;
	}

	/** Current model (may be undefined if not yet selected) */
	get model(): Model<any> | undefined {
		return this.agent.state.model;
	}

	/** Current thinking level */
	get thinkingLevel(): ThinkingLevel {
		return this.agent.state.thinkingLevel;
	}

	/** Whether the session is currently processing an agent run or post-run continuation. */
	get isStreaming(): boolean {
		return this._isAgentRunActive;
	}

	/** Whether the session has no active agent run, retry, auto-compaction, or queued continuation. */
	get isIdle(): boolean {
		return !this._isAgentRunActive;
	}

	/** Current effective system prompt (includes any per-turn extension modifications) */
	get systemPrompt(): string {
		return this.agent.state.systemPrompt;
	}

	[GET_COLLABORATION_MODE](): CollaborationMode {
		return this._collaborationMode;
	}

	/** Globally selected harness revision activated for this session. */
	get activeHarnessVersion(): HarnessVersion | undefined {
		return this._harnessVersionBundle?.manifest.version;
	}

	/** Current retry attempt (0 if not retrying) */
	get retryAttempt(): number {
		return this._retryAttempt;
	}

	/**
	 * Get the names of currently active tools.
	 * Returns the names of tools currently set on the agent.
	 */
	getActiveToolNames(): string[] {
		return this.agent.state.tools.map((t) => t.name);
	}

	/**
	 * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
	 */
	getAllTools(): ToolInfo[] {
		return Array.from(this._toolDefinitions.values()).map(({ definition, sourceInfo }) => ({
			name: definition.name,
			description: definition.description,
			parameters: definition.parameters,
			promptGuidelines: definition.promptGuidelines,
			sourceInfo,
		}));
	}

	getToolDefinition(name: string): ToolDefinition | undefined {
		return (this._activeRunCollaborationState?.effectiveToolDefinitions ?? this._effectiveToolDefinitions).get(name)
			?.definition;
	}

	[SUBSCRIBE_PROMPT_ADMISSION](listener: () => void): () => void {
		this._promptAdmissionListeners.add(listener);
		return () => {
			this._promptAdmissionListeners.delete(listener);
		};
	}

	private _invalidatePlanHandoff(): void {
		this._planHandoffGeneration++;
		for (const listener of this._promptAdmissionListeners) listener();
	}

	[IS_COLLABORATION_MODE_BUSY](): boolean {
		return (
			this._collaborationModeTransitionInProgress ||
			this._promptAdmissionInProgress ||
			this._harnessSwitchInProgress ||
			this.isStreaming ||
			this.isRetrying ||
			this._manualCompactionOperations > 0 ||
			this.isCompacting ||
			this.isBashRunning
		);
	}

	[CHANGE_COLLABORATION_MODE](mode: CollaborationMode, persist: boolean): CollaborationModeTransitionResult {
		if (mode === this._collaborationMode) return { status: "unchanged", mode };
		if (this[IS_COLLABORATION_MODE_BUSY]()) {
			return { status: "busy", mode: this._collaborationMode };
		}

		this._collaborationModeTransitionInProgress = true;
		try {
			const nextState = this._deriveCollaborationModeState(mode);
			const entryId = persist
				? appendCustomEntryWithRollback(this.sessionManager, COLLABORATION_MODE_CUSTOM_TYPE, { mode })
				: undefined;
			this._collaborationMode = mode;
			this._planHandoffGeneration++;
			this._installCollaborationModeState(nextState);
			if (entryId) {
				const entry = this.sessionManager.getEntry(entryId);
				if (entry) this._emit({ type: "entry_appended", entry });
			}
			return { status: "changed", mode };
		} finally {
			this._collaborationModeTransitionInProgress = false;
		}
	}

	/** Current in-memory child-agent roster, sorted by name. */
	getSubagents(): readonly SubagentSummary[] {
		return this._subagentController?.getSummaries() ?? Object.freeze([]);
	}

	/** List valid harness revisions and diagnostics for unavailable revision paths. */
	async listHarnessVersions(): Promise<HarnessVersionList> {
		if (!this._harnessStateStore) {
			return { versions: Object.freeze([]), diagnostics: Object.freeze([]), currentVersion: null };
		}
		return this._harnessStateStore.listVersions();
	}

	/**
	 * Atomically select and activate a complete harness revision for future requests.
	 * Conversation history and unrelated resources remain unchanged.
	 */
	async switchHarnessVersion(version: HarnessVersion): Promise<void> {
		if (!this._harnessStateStore) {
			if (version === this.activeHarnessVersion) return;
			throw new Error("Harness version switching is unavailable for this session.");
		}
		if (this._harnessSwitchInProgress) {
			throw new Error("Cannot switch harness versions while another switch is in progress.");
		}

		this._harnessSwitchInProgress = true;
		try {
			const listing = await this._harnessStateStore.listVersions();
			const target = listing.versions.find((bundle) => bundle.manifest.version === version);
			// Background activation can move the shared pointer without changing this session's pinned bundle.
			if (target && version === this.activeHarnessVersion && version === listing.currentVersion) return;

			if (this._promptAdmissionInProgress) {
				throw new Error("Cannot switch harness versions while a prompt is being admitted.");
			}
			if (this.isStreaming) {
				throw new Error("Cannot switch harness versions while a response is streaming.");
			}
			if (this._manualCompactionOperations > 0 || this.isCompacting) {
				throw new Error("Cannot switch harness versions while compaction is in progress.");
			}
			if (this.isBashRunning) {
				throw new Error("Cannot switch harness versions while a bash command is running.");
			}
			if (!target) {
				const diagnostic = listing.diagnostics.find((entry) => entry.version === version);
				throw new Error(
					diagnostic
						? `Harness version ${version} is unavailable: ${diagnostic.message}`
						: `Harness version ${version} was not found.`,
				);
			}

			if (version === this.activeHarnessVersion) {
				await this._harnessStateStore.selectVersion(version);
			} else {
				await this._activateHarnessBundle(target, () => this._harnessStateStore!.selectVersion(version));
			}
		} finally {
			this._harnessSwitchInProgress = false;
		}
	}

	private async _activateHarnessBundle(
		bundle: HarnessVersionBundle,
		selectBundle?: () => Promise<HarnessVersionBundle>,
	): Promise<void> {
		await this._subagentController?.reset();
		const activatedBundle = selectBundle ? await selectBundle() : bundle;
		this._resourceLoader.setEvolvedSkills(
			this._workspaceIdentity === undefined
				? { skills: [], diagnostics: [] }
				: createEvolvedSkillCatalog(activatedBundle, this._workspaceIdentity),
		);
		this._harnessVersionBundle = activatedBundle;
		this._systemPromptOverride = undefined;
		this._installCollaborationModeState(this._deriveCollaborationModeState(this._collaborationMode));
		await this._notifyHarnessActivated(activatedBundle.manifest.version);
	}

	private async _reconcileSelectedHarness(): Promise<void> {
		if (!this._harnessStateStore || this._pinHarnessVersion || hasFixedHarnessSubagentSession(this.sessionManager)) {
			return;
		}

		const selected = await this._harnessStateStore.loadCurrent();
		if (selected.manifest.version === this.activeHarnessVersion) return;

		await this._activateHarnessBundle(selected);
	}

	private async _refreshHarnessAfterCompaction(): Promise<string | undefined> {
		try {
			const systemPromptOverride = this._systemPromptOverride;
			await this._reconcileSelectedHarness();
			// A before_agent_start override still owns this logical run's effective prompt.
			if (systemPromptOverride !== undefined) {
				this._systemPromptOverride = systemPromptOverride;
				this._installCollaborationModeState(this._deriveCollaborationModeState(this._collaborationMode));
			}
			if (this._activeRunCollaborationState) {
				this._activeRunCollaborationState = this._capturePlanAdmissionState();
			}
			return undefined;
		} catch (error) {
			return error instanceof Error ? error.message : String(error);
		}
	}

	/**
	 * Set active tools by name.
	 * Only tools in the registry can be enabled. Unknown tool names are ignored.
	 * Also rebuilds the system prompt to reflect the new tool set.
	 * Changes take effect on the next agent turn.
	 */
	setActiveToolsByName(toolNames: string[]): void {
		this._requestedToolNames = [...new Set(toolNames.filter((name) => this._toolRegistry.has(name)))];
		if (this._activeRunCollaborationMode === "plan") return;
		this._installCollaborationModeState(
			this._deriveCollaborationModeState(this._activeRunCollaborationMode ?? this._collaborationMode),
		);
	}

	/** Whether compaction or branch summarization is currently running */
	get isCompacting(): boolean {
		return (
			this._autoCompactionAbortController !== undefined ||
			this._compactionAbortController !== undefined ||
			this._branchSummaryAbortController !== undefined
		);
	}

	/** All messages including custom types like BashExecutionMessage */
	get messages(): AgentMessage[] {
		return this.agent.state.messages;
	}

	/** Current steering mode */
	get steeringMode(): "all" | "one-at-a-time" {
		return this.agent.steeringMode;
	}

	/** Current follow-up mode */
	get followUpMode(): "all" | "one-at-a-time" {
		return this.agent.followUpMode;
	}

	/** Current session file path, or undefined if sessions are disabled */
	get sessionFile(): string | undefined {
		return this.sessionManager.getSessionFile();
	}

	/** Current session ID */
	get sessionId(): string {
		return this.sessionManager.getSessionId();
	}

	/** Current session display name, if set */
	get sessionName(): string | undefined {
		return this.sessionManager.getSessionName();
	}

	/** Scoped models for cycling (from --models flag) */
	get scopedModels(): ReadonlyArray<{ model: Model<any>; thinkingLevel?: ThinkingLevel }> {
		return this._scopedModels;
	}

	/** Update scoped models for cycling */
	setScopedModels(scopedModels: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>): void {
		this._scopedModels = scopedModels;
	}

	/** File-based prompt templates */
	get promptTemplates(): ReadonlyArray<PromptTemplate> {
		return this._resourceLoader.getPrompts().prompts;
	}

	private _skillReferenceKey(skillId: string, version: string): string {
		return `${skillId}\0${version}`;
	}

	private _isSkillEnabled(skill: Pick<Skill, "disableModelInvocation" | "skillId">): boolean {
		return this._skillEnablementOverrides.get(skill.skillId) ?? !skill.disableModelInvocation;
	}

	private _snapshotSkill(skill: Skill): SkillReferenceSnapshot {
		const snapshot = createSkillReferenceSnapshot(skill);
		snapshot.enabled = this._isSkillEnabled(skill);
		this._skillReferenceSnapshots.set(this._skillReferenceKey(snapshot.skillId, snapshot.version), snapshot);
		return snapshot;
	}

	private _snapshotSkillCatalog(): SkillReferenceSnapshot[] {
		return this._resourceLoader.getSkills().skills.map((skill) => this._snapshotSkill(skill));
	}

	private _skillObservationAttributes(skill: SkillReferenceSnapshot) {
		return {
			"diffex.skill.id": skill.skillId,
			"diffex.skill.version": skill.version,
			"diffex.skill.content_digest": skill.contentDigest,
			"diffex.skill.source_kind": skill.sourceKind,
			"diffex.skill.source": skill.sourceInfo.source,
			"diffex.skill.scope": skill.scope,
			...(skill.harnessRevision === undefined ? {} : { "diffex.skill.harness_revision": skill.harnessRevision }),
			...(this._workspaceIdentity === undefined
				? {}
				: {
						"diffex.workspace.repository_id": this._workspaceIdentity.repositoryId,
						...(this._workspaceIdentity.directoryId === undefined
							? {}
							: { "diffex.workspace.directory_id": this._workspaceIdentity.directoryId }),
					}),
			...(this.activeHarnessVersion === undefined ? {} : { "diffex.harness.version": this.activeHarnessVersion }),
		};
	}

	private _recordSkillAdmission(
		operationSpan: CodingAgentTelemetrySpan<"diffex.coding_agent.operation">,
		available: readonly SkillReferenceSnapshot[],
		references: readonly SkillReferenceSnapshot[],
		forceLoaded: readonly SkillReferenceSnapshot[],
		systemPrompt: string,
	): readonly SkillReferenceSnapshot[] {
		for (const skill of available) {
			operationSpan.addEvent("diffex.skill.available", this._skillObservationAttributes(skill));
			if (isSkillListedInPrompt(systemPrompt, skill)) {
				operationSpan.addEvent("diffex.skill.listed", this._skillObservationAttributes(skill));
			}
		}
		this._recordSkillReferences(operationSpan, references);
		for (const skill of references) {
			operationSpan.addEvent("diffex.skill.explicitly_referenced", this._skillObservationAttributes(skill));
		}
		for (const skill of forceLoaded) {
			operationSpan.addEvent("diffex.skill.force_loaded", this._skillObservationAttributes(skill));
		}

		const snapshots = new Map<string, SkillReferenceSnapshot>();
		for (const skill of [...available, ...references]) {
			snapshots.set(this._skillReferenceKey(skill.skillId, skill.version), skill);
		}
		return [...snapshots.values()];
	}

	private _recordSkillRead(toolName: string, args: unknown, details: unknown, isError: boolean): void {
		const activeTrace = this._activeSkillTrace;
		if (
			isError ||
			toolName !== "read" ||
			!activeTrace ||
			typeof args !== "object" ||
			args === null ||
			typeof details !== "object" ||
			details === null
		) {
			return;
		}
		const path = "path" in args && typeof args.path === "string" ? args.path : undefined;
		const contentDigest =
			"contentDigest" in details && typeof details.contentDigest === "string" ? details.contentDigest : undefined;
		if (!path || !contentDigest) return;
		const resolvedPath = canonicalizePath(resolvePath(path, this._cwd));
		for (const skill of activeTrace.skills) {
			if (skill.contentDigest !== contentDigest) continue;
			if (canonicalizePath(resolvePath(skill.location, this._cwd)) !== resolvedPath) continue;
			activeTrace.operationSpan.addEvent("diffex.skill.read", this._skillObservationAttributes(skill));
		}
	}

	/** Enable or disable progressive disclosure of a skill for future model prompts. */
	setSkillEnabled(skillId: string, enabled: boolean): boolean {
		const skill = this._resourceLoader.getSkills().skills.find((candidate) => candidate.skillId === skillId);
		if (skill === undefined) return false;
		this._skillEnablementOverrides.set(skillId, enabled);
		if (this._activeRunCollaborationMode === "plan") return true;
		this._installCollaborationModeState(
			this._deriveCollaborationModeState(this._activeRunCollaborationMode ?? this._collaborationMode),
		);
		return true;
	}

	/** Snapshot every currently available skill for explicit selection. */
	createSkillReferences(): SkillReference[] {
		const references: SkillReference[] = [];
		for (const skill of this._resourceLoader.getSkills().skills) {
			try {
				const snapshot = this._snapshotSkill(skill);
				references.push({
					skillId: snapshot.skillId,
					version: snapshot.version,
					contentDigest: snapshot.contentDigest,
					name: snapshot.name,
					description: snapshot.description,
					sourceKind: snapshot.sourceKind,
					scope: snapshot.scope,
					...(snapshot.harnessRevision === undefined ? {} : { harnessRevision: snapshot.harnessRevision }),
					reference: snapshot.reference,
					group: snapshot.group,
					enabled: snapshot.enabled,
				});
			} catch (error) {
				this._extensionRunner.emitError({
					extensionPath: skill.filePath,
					event: "skill_reference",
					error: error instanceof Error ? error.message : String(error),
				});
			}
		}
		return references;
	}

	private _normalizePromptSnippet(text: string | undefined): string | undefined {
		if (!text) return undefined;
		const oneLine = text
			.replace(/[\r\n]+/g, " ")
			.replace(/\s+/g, " ")
			.trim();
		return oneLine.length > 0 ? oneLine : undefined;
	}

	private _normalizePromptGuidelines(guidelines: string[] | undefined): string[] {
		if (!guidelines || guidelines.length === 0) {
			return [];
		}

		const unique = new Set<string>();
		for (const guideline of guidelines) {
			const normalized = guideline.trim();
			if (normalized.length > 0) {
				unique.add(normalized);
			}
		}
		return Array.from(unique);
	}

	private _createSystemPrompt(
		toolNames: string[],
		definitions: ReadonlyMap<string, ToolDefinitionEntry>,
	): { prompt: string; options: BuildSystemPromptOptions } {
		const validToolNames = toolNames.filter((name) => definitions.has(name));
		const toolSnippets: Record<string, string> = {};
		const promptGuidelines: Record<string, string[]> = {};
		for (const name of validToolNames) {
			const definition = definitions.get(name)?.definition;
			const snippet = this._normalizePromptSnippet(definition?.promptSnippet);
			if (snippet) {
				toolSnippets[name] = snippet;
			}

			const toolGuidelines = this._normalizePromptGuidelines(definition?.promptGuidelines);
			if (toolGuidelines.length > 0) {
				promptGuidelines[name] = toolGuidelines;
			}
		}
		const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
		const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
		const appendSystemPrompt =
			loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined;
		const loadedSkills = this._resourceLoader.getSkills().skills.filter((skill) => this._isSkillEnabled(skill));
		const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;

		const options: BuildSystemPromptOptions = {
			cwd: this._cwd,
			skills: loadedSkills,
			contextFiles: loadedContextFiles,
			customPrompt: loaderSystemPrompt,
			appendSystemPrompt,
			selectedTools: validToolNames,
			toolSnippets,
			promptGuidelines,
			evolutionMemory: this._harnessVersionBundle
				? {
						version: this._harnessVersionBundle.manifest.version,
						memory: this._harnessVersionBundle.state.memory,
					}
				: undefined,
		};
		return { prompt: buildSystemPrompt(options), options };
	}

	private _deriveEffectivePrompt(systemPrompt: string, mode: CollaborationMode): string {
		return mode === "plan" ? `${systemPrompt}\n\n${PLAN_MODE_SYSTEM_PROMPT}` : systemPrompt;
	}

	private _deriveCollaborationModeState(mode: CollaborationMode): CollaborationModeState {
		let definitions: Map<string, ToolDefinitionEntry>;
		let tools: AgentTool[];
		if (mode === "plan") {
			definitions = new Map();
			tools = [];
			for (const name of PLAN_MODE_TOOL_NAMES) {
				const tool =
					name === REQUEST_USER_INPUT_TOOL_NAME ? this._requestUserInputTool : this._baseToolRegistry.get(name);
				const definition =
					name === REQUEST_USER_INPUT_TOOL_NAME
						? this._requestUserInputDefinition
						: this._baseToolDefinitions.get(name);
				if (!tool || !definition) continue;
				tools.push(tool);
				definitions.set(name, {
					definition,
					sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
				});
			}
		} else {
			definitions = this._toolDefinitions;
			tools = this._requestedToolNames.flatMap((name) => {
				const tool = this._toolRegistry.get(name);
				return tool ? [tool] : [];
			});
		}

		const { prompt, options } = this._createSystemPrompt(
			tools.map((tool) => tool.name),
			definitions,
		);
		return {
			mode,
			baseSystemPrompt: prompt,
			baseSystemPromptOptions: options,
			effectiveSystemPrompt: this._deriveEffectivePrompt(this._systemPromptOverride ?? prompt, mode),
			effectiveToolDefinitions: definitions,
			tools,
		};
	}

	private _installCollaborationModeState(state: CollaborationModeState): void {
		this._baseSystemPrompt = state.baseSystemPrompt;
		this._baseSystemPromptOptions = state.baseSystemPromptOptions;
		this._effectiveToolDefinitions = state.effectiveToolDefinitions;
		this.agent.state.tools = state.tools;
		this.agent.state.systemPrompt = state.effectiveSystemPrompt;
	}

	private _capturePlanAdmissionState(): CollaborationModeState | undefined {
		if (this._collaborationMode !== "plan") return undefined;
		return {
			mode: "plan",
			baseSystemPrompt: this._baseSystemPrompt,
			baseSystemPromptOptions: this._baseSystemPromptOptions,
			effectiveSystemPrompt: this.agent.state.systemPrompt,
			effectiveToolDefinitions: new Map(this._effectiveToolDefinitions),
			tools: this.agent.state.tools.slice(),
		};
	}

	// =========================================================================
	// Prompting
	// =========================================================================

	private _traceOperation<Result>(
		kind: "prompt" | "compaction" | "navigation" | "abort" | "queue" | "bash" | "export",
		callback: (
			telemetryContext: CodingAgentTelemetrySpan<"diffex.coding_agent.operation">,
		) => Result | Promise<Result>,
	): Promise<Result> {
		const operationId = uuidv7();
		const taskLineageId = kind === "prompt" ? operationId : undefined;
		const firstEntryOrdinal = this.sessionManager.getEntryCount();
		const operation = startCodingAgentSpan(
			this.agent.telemetryContext,
			"diffex.coding_agent.operation",
			{
				"diffex.operation.id": operationId,
				...(taskLineageId === undefined ? {} : { "diffex.task.lineage.id": taskLineageId }),
				"diffex.session.id": this.sessionId,
				"diffex.operation.kind": kind,
			},
			async (span) => {
				const previousAgentContext = this.agent.telemetryContext;
				const bindsAgentContext = kind === "prompt" && !this.isStreaming;
				if (bindsAgentContext) this.agent.telemetryContext = span;
				try {
					const result = await callback(span);
					const aborted = bindsAgentContext && this._agentRunAborted;
					span.setAttributes({ "diffex.operation.outcome": aborted ? "aborted" : "completed" });
					if (aborted) span.setStatus({ status: "error" });
					return result;
				} catch (error) {
					const aborted =
						error instanceof Error &&
						(error.name === "AbortError" || error.message.toLowerCase().includes("cancelled"));
					span.setAttributes({ "diffex.operation.outcome": aborted ? "aborted" : "failed" });
					span.setStatus({ status: "error" });
					throw error;
				} finally {
					if (bindsAgentContext && this.agent.telemetryContext === span) {
						this.agent.telemetryContext = previousAgentContext;
					}
				}
			},
		);
		return operation.finally(() => this._notifyOperationSettled({ operationId, taskLineageId, firstEntryOrdinal }));
	}

	private async _notifyOperationSettled(options: {
		operationId: string;
		taskLineageId?: string;
		firstEntryOrdinal: number;
	}): Promise<void> {
		try {
			await this._lifecycleObserver?.operationSettled({
				...options,
				sessionManager: this.sessionManager,
			});
		} catch {
			// Lifecycle observers are passive and never change operation behavior.
		}
	}

	private async _notifyHarnessActivated(version: HarnessVersion): Promise<void> {
		try {
			await this._lifecycleObserver?.harnessActivated(version);
		} catch {
			// Lifecycle observers are passive and never change activation behavior.
		}
	}

	private async _runAgentPrompt(
		messages: AgentMessage | AgentMessage[],
		collaborationMode: CollaborationMode = this._collaborationMode,
		collaborationState: CollaborationModeState | undefined = this._capturePlanAdmissionState(),
	): Promise<void> {
		this._agentRunAborted = false;
		this._latestFinalizedPlan = undefined;
		this._activeRunCollaborationMode = collaborationMode;
		this._activeRunCollaborationState = collaborationState;
		if (collaborationState) this._installCollaborationModeState(collaborationState);
		this._isAgentRunActive = true;
		try {
			// Extension custom messages can start a logical run without prompt().
			this._invalidatePlanHandoff();
			let firstRun = true;
			while (true) {
				if (firstRun) await this.agent.prompt(messages);
				else await this.agent.continue();
				firstRun = false;
				const next = await this._handlePostAgentRun();
				if (next === "failed") break;
				if (next === "continue") {
					if (this._agentRunAborted) {
						const coordination = this._subagentCoordination;
						if (coordination) {
							this._exitSubagentCoordination("cancellation");
							await this._waitForSubagentCoordination(coordination);
						}
						break;
					}
					continue;
				}
				if (this._agentRunAborted) break;

				// No await is permitted between the inactive mark and final queue recheck.
				this._isAgentRunActive = false;
				if (!this.agent.hasQueuedMessages()) break;
				this._isAgentRunActive = true;
			}
		} finally {
			const planHandoff =
				this._activeRunCollaborationMode === "plan" && this._latestFinalizedPlan !== undefined
					? { plan: this._latestFinalizedPlan }
					: undefined;
			this._latestFinalizedPlan = undefined;
			this._systemPromptOverride = undefined;
			this._activeRunCollaborationMode = undefined;
			this._activeRunCollaborationState = undefined;
			this._installCollaborationModeState(this._deriveCollaborationModeState(this._collaborationMode));
			this._flushPendingBashMessages();
			await this._emitAgentSettled(planHandoff);
		}
	}

	private _createSubagentNotice(result: SubagentBatchResult): Extract<AgentSessionEvent, { type: "subagent_notice" }> {
		const text =
			result.status === "idle"
				? `${result.name} has finished execution.`
				: result.status === "interrupted"
					? `${result.name} was interrupted.`
					: result.retryAvailable
						? `${result.name} failed and a retry is being planned.`
						: `${result.name} failed after one retry.`;
		return {
			type: "subagent_notice",
			name: result.name,
			status: result.status,
			attempt: result.attempt,
			retryAvailable: result.retryAvailable,
			text,
		};
	}

	private _createSubagentResultMessage(results: readonly SubagentBatchResult[]): CustomMessage {
		const agents = results.map((result) => ({
			name: result.name,
			status: result.status,
			attempt: result.attempt,
			retry_available: result.retryAvailable,
			...(result.status === "idle" && result.result !== undefined ? { result: result.result } : {}),
			...(result.status !== "idle" && result.result !== undefined ? { partial_output: result.result } : {}),
			...(result.error === undefined ? {} : { error: result.error }),
		}));
		const retryTargets = results.filter((result) => result.retryAvailable).map((result) => result.name);
		return {
			role: "custom",
			customType: "subagent_results",
			content: JSON.stringify({
				type: "subagent_batch_results",
				agents,
				...(retryTargets.length === 0
					? {}
					: {
							retry_instruction:
								"Analyze each failed child's error and partial output. If a correction can help, call agent_action with action set to message, a corrective message, and wake set to true. Only one coordinated retry is available for each listed child in this parent prompt cycle. You may decline a retry and answer normally.",
							retry_targets: retryTargets,
						}),
			}),
			display: false,
			details: { names: results.map((result) => result.name) },
			timestamp: Date.now(),
		};
	}

	private _getOrCreateSubagentCoordination(): SubagentCoordination | undefined {
		if (this._subagentCoordination) return this._subagentCoordination;
		const batch = this._subagentController?.freezeUnconsumedBatch();
		if (!batch) return undefined;
		const coordination: SubagentCoordination = {
			batch,
			names: Object.freeze(batch.attempts.map((attempt) => attempt.name)),
			terminalNotices: new Set(),
			waitStarted: false,
		};
		this._subagentCoordination = coordination;
		return coordination;
	}

	private _exitSubagentCoordination(reason: "escalation" | "cancellation"): void {
		const coordination = this._subagentCoordination;
		if (!coordination) return;
		if (reason === "cancellation" || coordination.exitReason === undefined) {
			coordination.exitReason = reason;
		}
		coordination.currentWaitAbortController?.abort(new Error(`Subagent coordination ${reason}`));
	}

	private _clearSubagentCoordination(coordination: SubagentCoordination, cancelled: boolean): void {
		if (this._subagentCoordination !== coordination) return;
		this._subagentCoordination = undefined;
		coordination.currentWaitAbortController = undefined;
		if (coordination.waitStarted) {
			this._emit({ type: "subagent_wait_end", names: coordination.names, cancelled });
		}
	}

	private async _waitForSubagentCoordination(
		coordination: SubagentCoordination,
	): Promise<
		| { reason: "terminal"; results: readonly SubagentBatchResult[] }
		| { reason: "escalation" }
		| { reason: "cancellation" }
	> {
		const controller = this._subagentController;
		if (!controller) return { reason: "terminal", results: Object.freeze([]) };

		const emitNotice = (result: SubagentBatchResult): void => {
			if (coordination.terminalNotices.has(result.name)) return;
			coordination.terminalNotices.add(result.name);
			this._emit(this._createSubagentNotice(result));
		};
		const waitAbortController = new AbortController();
		coordination.currentWaitAbortController = waitAbortController;
		if (this._agentRunAborted || coordination.exitReason === "cancellation") {
			coordination.exitReason = "cancellation";
			waitAbortController.abort(new Error("Subagent coordination cancellation"));
		} else if (coordination.exitReason === "escalation") {
			waitAbortController.abort(new Error("Subagent coordination escalation"));
		}
		if (!coordination.waitStarted) {
			coordination.waitStarted = true;
			this._emit({ type: "subagent_wait_start", names: coordination.names });
		}

		try {
			try {
				await controller.waitForBatch(coordination.batch, {
					signal: waitAbortController.signal,
					onTerminal: emitNotice,
				});
			} catch (error) {
				if (!waitAbortController.signal.aborted) throw error;
				const exitReason =
					coordination.exitReason === "cancellation" || this._agentRunAborted
						? "cancellation"
						: coordination.exitReason;
				if (!exitReason) throw error;
				if (exitReason === "escalation") {
					coordination.exitReason = undefined;
					return { reason: "escalation" };
				}
				if (!this._disposePromise) {
					await controller.interruptBatch(coordination.batch);
					await controller.waitForBatch(coordination.batch, { onTerminal: emitNotice });
					controller.consumeBatch(coordination.batch);
				}
				this._clearSubagentCoordination(coordination, true);
				return { reason: "cancellation" };
			}
			const results = controller.consumeBatch(coordination.batch);
			this._clearSubagentCoordination(coordination, false);
			return { reason: "terminal", results };
		} finally {
			if (coordination.currentWaitAbortController === waitAbortController) {
				coordination.currentWaitAbortController = undefined;
			}
		}
	}

	private async _handlePostAgentRun(): Promise<"continue" | "settled" | "failed"> {
		const msg = this._lastAssistantMessage;
		this._lastAssistantMessage = undefined;
		if (!msg) {
			return "settled";
		}

		if (this._isRetryableError(msg) && (await this._prepareRetry(msg))) {
			return "continue";
		}

		if (msg.stopReason === "error" && this._retryAttempt > 0) {
			this._emit({
				type: "auto_retry_end",
				success: false,
				attempt: this._retryAttempt,
				finalError: msg.errorMessage,
			});
			this._retryAttempt = 0;
		}

		if (await this._checkCompaction(msg)) {
			return "continue";
		}

		if (msg.stopReason === "error") {
			// Recovery may have removed the failed response before giving up.
			if (!this.agent.state.messages.includes(msg)) this.agent.state.messages.push(msg);
			while (true) {
				const coordination = this._getOrCreateSubagentCoordination();
				if (!coordination) break;
				this._exitSubagentCoordination("cancellation");
				await this._waitForSubagentCoordination(coordination);
			}
			// Queued reports and input must not bypass an exhausted recovery budget.
			// Leave them available for an explicit prompt or queue recovery by the caller.
			return "failed";
		}

		// Reports already queued by this run must enter context before a new batch is frozen
		// or an escalation-suspended coordination resumes waiting.
		if (this.agent.hasQueuedMessages()) return "continue";

		while (true) {
			const coordination = this._getOrCreateSubagentCoordination();
			if (!coordination) break;
			if (coordination.exitReason === "cancellation" || this._agentRunAborted) {
				this._exitSubagentCoordination("cancellation");
			} else if (!coordination.completionChecked) {
				coordination.completionChecked = true;
				const active = this.getSubagents().filter(
					(child) =>
						coordination.names.includes(child.name) && (child.status === "running" || child.status === "queued"),
				);
				if (active.length > 0) {
					await this.sendCustomMessage(
						{
							customType: "subagent_completion_check",
							content: JSON.stringify({
								type: "subagent_completion_check",
								agents: active,
								instruction:
									"Review active children before finishing: cancel obsolete work with agent_action interrupt. If needed work remains, end your response to wait automatically. Renew only justified work.",
							}),
							display: false,
						},
						{ deliverAs: "steer" },
					);
					return "continue";
				}
			}
			const delivery = await this._waitForSubagentCoordination(coordination);
			if (delivery.reason === "cancellation") return "settled";
			if (delivery.reason === "escalation") {
				if (coordination.exitReason === "cancellation" || this._agentRunAborted) {
					this._exitSubagentCoordination("cancellation");
					await this._waitForSubagentCoordination(coordination);
					return "settled";
				}
				return "continue";
			}
			if (delivery.results.length > 0) {
				const message = this._createSubagentResultMessage(delivery.results);
				await this.sendCustomMessage(message, { deliverAs: "steer" });
				return "continue";
			}
			// Explicit agents consumption can empty this batch while the same continuation
			// starts another coordinated child. Freeze that pending run before settling.
		}

		// The agent loop drains both queues before emitting agent_end. Any messages
		// here were queued by agent_end extension handlers and need a continuation.
		return this.agent.hasQueuedMessages() ? "continue" : "settled";
	}

	/**
	 * Send a prompt to the agent.
	 * - Handles extension commands (registered via diffex.registerCommand) immediately, even during streaming
	 * - Expands file-based prompt templates by default
	 * - During streaming, queues via steer() or followUp() based on streamingBehavior option
	 * - Validates model and API key before sending (when not streaming)
	 * @throws Error if streaming and no streamingBehavior specified
	 * @throws Error if no model selected or no API key available (when not streaming)
	 */
	prompt(text: string, options?: PromptOptions): Promise<void> {
		const signal = options?.signal;
		const preflightResult = options?.preflightResult;
		const rejectPreflight = (error: unknown): Promise<never> => {
			try {
				preflightResult?.(false);
			} catch {
				// Synchronous rejection gates remain authoritative unless the callback cancels the prompt.
			}
			return Promise.reject(signal?.aborted ? signal.reason : error);
		};
		if (signal?.aborted) {
			return rejectPreflight(signal.reason);
		}
		if ([...this._promptReservations].some((reservation) => reservation.signaled)) {
			return rejectPreflight(new Error("Cannot submit a prompt while another prompt owns prompt preflight."));
		}
		if (signal && this._promptReservations.size > 0) {
			return rejectPreflight(new Error("Cannot submit a prompt while another prompt owns prompt preflight."));
		}
		if (signal && this._isAgentRunActive) {
			return rejectPreflight(new Error("Cannot submit a signaled prompt while an agent run is active."));
		}
		const reservesAdmission = !this.isStreaming;
		if (reservesAdmission && this._promptAdmissionInProgress) {
			return rejectPreflight(new Error("Cannot submit a prompt while another prompt is being admitted."));
		}
		if (reservesAdmission) this._promptAdmissionInProgress = true;

		const reservation: PromptReservation = {
			signaled: signal !== undefined,
			collaborationMode: this._collaborationMode,
			collaborationState: this._capturePlanAdmissionState(),
			agentStarted: false,
		};
		this._promptReservations.add(reservation);
		const releaseUnsignaledPreflight = (): void => {
			if (!reservation.signaled) this._promptReservations.delete(reservation);
		};
		const onAbort = signal
			? (): void => {
					if (reservation.agentStarted) {
						void this.abort().catch(() => {});
					} else {
						this.abortCompaction();
					}
				}
			: undefined;
		if (onAbort && signal) signal.addEventListener("abort", onAbort, { once: true });

		const cleanup = (): void => {
			if (onAbort && signal) signal.removeEventListener("abort", onAbort);
			this._promptReservations.delete(reservation);
			if (reservesAdmission) this._promptAdmissionInProgress = false;
		};
		try {
			if (reservesAdmission) {
				this._invalidatePlanHandoff();
			}
			return this._traceOperation("prompt", (operationSpan) =>
				this._prompt(
					text,
					options,
					releaseUnsignaledPreflight,
					operationSpan,
					reservation.collaborationMode,
					reservation.collaborationState,
				),
			).finally(cleanup);
		} catch (error) {
			cleanup();
			return Promise.reject(error);
		}
	}

	private async _prompt(
		text: string,
		options: PromptOptions | undefined,
		releaseUnsignaledPreflight: () => void,
		operationSpan: CodingAgentTelemetrySpan<"diffex.coding_agent.operation">,
		collaborationMode: CollaborationMode,
		collaborationState: CollaborationModeState | undefined,
	): Promise<void> {
		await this._promptAfterReservation(
			text,
			options,
			releaseUnsignaledPreflight,
			operationSpan,
			collaborationMode,
			collaborationState,
		);
	}

	private async _promptAfterReservation(
		text: string,
		options: PromptOptions | undefined,
		releaseUnsignaledPreflight: () => void,
		operationSpan: CodingAgentTelemetrySpan<"diffex.coding_agent.operation">,
		collaborationMode: CollaborationMode,
		collaborationState: CollaborationModeState | undefined,
	): Promise<void> {
		if (this._harnessSwitchInProgress) {
			throw new Error("Cannot submit a prompt while a harness version switch is in progress.");
		}
		const expandPromptTemplates = options?.expandPromptTemplates ?? true;
		const preflightResult = options?.preflightResult;
		const signal = options?.signal;
		let messages: AgentMessage[] | undefined;
		let activeSkillTrace: ActiveSkillTrace | undefined;
		let consumedNextTurnMessages: CustomMessage[] | undefined;
		let preflightAccepted = false;
		let pendingCompaction: CompactionAppendTransaction | undefined;
		const commitPendingCompaction = async (): Promise<void> => {
			if (!pendingCompaction) return;
			pendingCompaction.commit();
			pendingCompaction = undefined;
			// Do not refresh a harness for compaction that cancellable preflight can still roll back.
			const refreshError = await this._refreshHarnessAfterCompaction();
			if (refreshError) {
				this._extensionRunner.emitError({
					extensionPath: "<runtime>",
					event: "harness_refresh",
					error: refreshError,
				});
			}
			if (collaborationState) collaborationState = this._capturePlanAdmissionState();
		};
		const rollbackPendingCompaction = (): void => {
			if (!pendingCompaction) return;
			pendingCompaction.rollback();
			pendingCompaction = undefined;
			this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
		};

		try {
			// Handle extension commands first (execute immediately, even during streaming)
			// Extension commands manage their own LLM interaction via diffex.sendMessage()
			if (expandPromptTemplates && text.startsWith("/")) {
				const handled = await this._tryExecuteExtensionCommand(text);
				signal?.throwIfAborted();
				if (handled) {
					// Extension command executed, no prompt to send
					preflightAccepted = true;
					preflightResult?.(true);
					signal?.throwIfAborted();
					return;
				}
			}

			if (this._compactionAbortController !== undefined) {
				throw new Error(
					"Cannot submit a prompt while compaction is in progress. Wait for compaction to finish and retry.",
				);
			}

			signal?.throwIfAborted();

			// Emit input event for extension interception (before skill/template expansion)
			let currentText = text;
			let currentImages = options?.images;
			if (this._extensionRunner.hasHandlers("input")) {
				const inputResult = await this._extensionRunner.emitInput(
					currentText,
					currentImages,
					options?.source ?? "interactive",
					this.isStreaming ? options?.streamingBehavior : undefined,
				);
				signal?.throwIfAborted();
				if (inputResult.action === "handled") {
					preflightAccepted = true;
					preflightResult?.(true);
					signal?.throwIfAborted();
					return;
				}
				if (inputResult.action === "transform") {
					currentText = inputResult.text;
					currentImages = inputResult.images ?? currentImages;
				}
			}

			// Expand prompt templates and explicit skill references.
			const availableSkills = this._snapshotSkillCatalog();
			let expandedText = currentText;
			let referencedSkills: SkillReferenceSnapshot[] = [];
			let forceLoadedSkills: SkillReferenceSnapshot[] = [];
			if (expandPromptTemplates) {
				expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
				const explicitReferences = this._expandSkillReferences(expandedText);
				expandedText = explicitReferences.text;
				referencedSkills = explicitReferences.references;
				forceLoadedSkills = explicitReferences.forceLoaded;
			}

			// If streaming, queue via steer() or followUp() based on option
			if (this.isStreaming) {
				if (!options?.streamingBehavior) {
					throw new Error(
						"Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.",
					);
				}
				this._recordSkillAdmission(
					operationSpan,
					availableSkills,
					referencedSkills,
					forceLoadedSkills,
					this.agent.state.systemPrompt,
				);
				if (options.streamingBehavior === "followUp") {
					await this._queueFollowUp(expandedText, currentImages, referencedSkills, forceLoadedSkills, false);
				} else {
					await this._queueSteer(expandedText, currentImages, referencedSkills, forceLoadedSkills, false);
				}
				preflightAccepted = true;
				preflightResult?.(true);
				return;
			}

			// Validate model
			if (!this.model) {
				throw new Error(formatNoModelSelectedMessage());
			}

			const hasConfiguredAuth =
				this._modelRuntime.hasConfiguredAuth(this.model.provider) ||
				(await this._modelRuntime.checkAuth(this.model.provider, { signal })) !== undefined;
			signal?.throwIfAborted();
			if (!hasConfiguredAuth) {
				const isOAuth = this._modelRuntime.isUsingOAuth(this.model.provider);
				if (isOAuth) {
					throw new Error(
						`Authentication failed for "${this.model.provider}". ` +
							`Credentials may have expired or network is unavailable. ` +
							`Run '/login ${this.model.provider}' to re-authenticate.`,
					);
				}
				throw new Error(formatNoApiKeyFoundMessage(this.model.provider));
			}

			// Check if we need to compact before sending (catches aborted responses).
			// The user's new prompt is sent below, so do not call agent.continue() here.
			const lastAssistant = this._findLastAssistantMessage();
			if (lastAssistant) {
				await this._checkCompaction(lastAssistant, false, signal, (transaction) => {
					pendingCompaction = transaction;
				});
				signal?.throwIfAborted();
			}

			// Build messages array (custom message if any, then user message)
			messages = [];

			// Add user message
			const userContent: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
			if (currentImages) {
				userContent.push(...currentImages);
			}
			messages.push({
				role: "user",
				content: userContent,
				timestamp: Date.now(),
			});

			// Inject any pending "nextTurn" messages as context alongside the user message
			consumedNextTurnMessages = this._pendingNextTurnMessages;
			for (const msg of consumedNextTurnMessages) {
				messages.push(msg);
			}
			this._pendingNextTurnMessages = [];

			// Emit before_agent_start extension event
			const result = await this._extensionRunner.emitBeforeAgentStart(
				expandedText,
				currentImages,
				collaborationState?.baseSystemPrompt ?? this._baseSystemPrompt,
				collaborationState?.baseSystemPromptOptions ?? this._baseSystemPromptOptions,
			);
			signal?.throwIfAborted();
			// Flush pending bash history only after cancellable preflight has completed.
			this._flushPendingBashMessages();
			// Add all custom messages from extensions
			if (result?.messages) {
				for (const msg of result.messages) {
					messages.push({
						role: "custom",
						customType: msg.customType,
						// Untyped extensions can pass null/missing content; normalize at ingestion.
						content: msg.content ?? [],
						display: msg.display,
						details: msg.details,
						timestamp: Date.now(),
					});
				}
			}
			// Apply collaboration instructions only after all extension prompt hooks.
			if (result?.systemPrompt !== undefined) {
				this._systemPromptOverride = result.systemPrompt;
			} else {
				// Ensure we're using the base prompt (in case previous turn had modifications)
				this._systemPromptOverride = undefined;
			}
			let effectiveSystemPrompt: string;
			if (collaborationState) {
				collaborationState = {
					...collaborationState,
					effectiveSystemPrompt: this._deriveEffectivePrompt(
						this._systemPromptOverride ?? collaborationState.baseSystemPrompt,
						collaborationMode,
					),
				};
				effectiveSystemPrompt = collaborationState.effectiveSystemPrompt;
			} else {
				effectiveSystemPrompt = this._deriveEffectivePrompt(
					this._systemPromptOverride ?? this._baseSystemPrompt,
					collaborationMode,
				);
				this.agent.state.systemPrompt = effectiveSystemPrompt;
			}
			activeSkillTrace = {
				operationSpan,
				skills: this._recordSkillAdmission(
					operationSpan,
					availableSkills,
					referencedSkills,
					forceLoadedSkills,
					effectiveSystemPrompt,
				),
			};
		} catch (error) {
			let failure = error;
			if (!preflightAccepted) {
				try {
					preflightResult?.(false);
				} catch (callbackError) {
					failure = callbackError;
				}
			}
			if (signal?.aborted) {
				rollbackPendingCompaction();
			} else {
				await commitPendingCompaction();
			}
			if (signal?.aborted && consumedNextTurnMessages) {
				this._pendingNextTurnMessages = [...consumedNextTurnMessages, ...this._pendingNextTurnMessages];
			}
			throw signal?.aborted ? signal.reason : failure;
		}

		if (!messages) {
			return;
		}

		preflightAccepted = true;
		try {
			preflightResult?.(true);
		} catch (error) {
			if (signal?.aborted) {
				rollbackPendingCompaction();
				this._pendingNextTurnMessages = [...(consumedNextTurnMessages ?? []), ...this._pendingNextTurnMessages];
				throw signal.reason;
			}
			await commitPendingCompaction();
			throw error;
		}
		if (signal?.aborted) {
			rollbackPendingCompaction();
			this._pendingNextTurnMessages = [...(consumedNextTurnMessages ?? []), ...this._pendingNextTurnMessages];
			consumedNextTurnMessages = undefined;
			throw signal.reason;
		}
		await commitPendingCompaction();
		if (signal?.aborted) {
			this._pendingNextTurnMessages = [...(consumedNextTurnMessages ?? []), ...this._pendingNextTurnMessages];
			throw signal.reason;
		}
		consumedNextTurnMessages = undefined;
		releaseUnsignaledPreflight();
		this._releaseIdleSubagentEscalationsForSelectedBranch();
		this._activeSkillTrace = activeSkillTrace;
		try {
			await this._runAgentPrompt(messages, collaborationMode, collaborationState);
		} finally {
			if (this._activeSkillTrace === activeSkillTrace) this._activeSkillTrace = undefined;
		}
	}

	/**
	 * Try to execute an extension command. Returns true if command was found and executed.
	 */
	private async _tryExecuteExtensionCommand(text: string): Promise<boolean> {
		// Parse command name and args
		const spaceIndex = text.indexOf(" ");
		const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
		const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);

		const command = this._extensionRunner.getCommand(commandName);
		if (!command) return false;

		// Get command context from extension runner (includes session control methods)
		const ctx = this._extensionRunner.createCommandContext();

		try {
			await command.handler(args, ctx);
			return true;
		} catch (err) {
			// Emit error via extension runner
			this._extensionRunner.emitError({
				extensionPath: `command:${commandName}`,
				event: "command",
				error: err instanceof Error ? err.message : String(err),
			});
			return true;
		}
	}

	private _recordSkillReferences(
		operationSpan: CodingAgentTelemetrySpan<"diffex.coding_agent.operation">,
		references: readonly SkillReferenceSnapshot[],
	): void {
		if (references.length === 0) return;
		operationSpan.setAttributes({
			"diffex.skill.references": references.map((reference) => `${reference.skillId}@${reference.version}`),
		});
	}

	private _expandSkillReferences(text: string): SkillExpansion {
		const references: SkillReferenceSnapshot[] = [];
		const forceLoaded: SkillReferenceSnapshot[] = [];
		const seen = new Set<string>();
		const remaining = text.replace(
			SKILL_REFERENCE_PATTERN,
			(_match, skillId: string, version: string, forceLoadMarker: string | undefined) => {
				const key = this._skillReferenceKey(skillId, version);
				const snapshot = this._skillReferenceSnapshots.get(key);
				if (!snapshot) {
					throw new Error(`Skill reference ${skillId}@${version} is not available in this session.`);
				}
				if (
					snapshot.sourceKind === "evolved" &&
					snapshot.harnessRevision !== this._harnessVersionBundle?.manifest.version
				) {
					throw new Error(
						`Evolved skill reference ${skillId}@${version} is not part of the active harness revision.`,
					);
				}
				if (!seen.has(key)) {
					seen.add(key);
					references.push(snapshot);
					if (forceLoadMarker !== undefined) forceLoaded.push(snapshot);
				}
				return "";
			},
		);
		if (references.length === 0) return { text, references, forceLoaded };
		const userText = remaining.trim();
		const skillBlocks = references.map(formatSkillReferenceSnapshot).join("\n\n");
		return {
			text: userText ? `${skillBlocks}\n\n${userText}` : skillBlocks,
			references,
			forceLoaded,
		};
	}

	/**
	 * Queue a steering message while the agent is running.
	 * Delivered after the current assistant turn finishes executing its tool calls,
	 * before the next LLM call.
	 * Expands prompt templates and explicit skill references. Errors on extension commands.
	 * @param images Optional image attachments to include with the message
	 * @throws Error if text is an extension command
	 */
	async steer(text: string, images?: ImageContent[]): Promise<void> {
		// Check for extension commands (cannot be queued)
		if (text.startsWith("/")) {
			this._throwIfExtensionCommand(text);
		}

		// Expand prompt templates and explicit skill references.
		const explicitReferences = this._expandSkillReferences(expandPromptTemplate(text, [...this.promptTemplates]));
		await this._queueSteer(
			explicitReferences.text,
			images,
			explicitReferences.references,
			explicitReferences.forceLoaded,
		);
	}

	/**
	 * Queue a follow-up message to be processed after the agent finishes.
	 * Delivered only when agent has no more tool calls or steering messages.
	 * Expands prompt templates and explicit skill references. Errors on extension commands.
	 * @param images Optional image attachments to include with the message
	 * @throws Error if text is an extension command
	 */
	async followUp(text: string, images?: ImageContent[]): Promise<void> {
		// Check for extension commands (cannot be queued)
		if (text.startsWith("/")) {
			this._throwIfExtensionCommand(text);
		}

		// Expand prompt templates and explicit skill references.
		const explicitReferences = this._expandSkillReferences(expandPromptTemplate(text, [...this.promptTemplates]));
		await this._queueFollowUp(
			explicitReferences.text,
			images,
			explicitReferences.references,
			explicitReferences.forceLoaded,
		);
	}

	/**
	 * Internal: Queue a steering message (already expanded, no extension command check).
	 */
	private async _queueSteer(
		text: string,
		images?: ImageContent[],
		references: readonly SkillReferenceSnapshot[] = [],
		forceLoaded: readonly SkillReferenceSnapshot[] = [],
		recordAdmission = true,
	): Promise<void> {
		await this._traceOperation("queue", (operationSpan) => {
			if (recordAdmission) {
				this._recordSkillAdmission(
					operationSpan,
					this._snapshotSkillCatalog(),
					references,
					forceLoaded,
					this.agent.state.systemPrompt,
				);
			}
			return this._enqueueSteer(text, images);
		});
	}

	private async _enqueueSteer(text: string, images?: ImageContent[]): Promise<void> {
		this._steeringMessages.push(text);
		this._emitQueueUpdate();
		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
		if (images) {
			content.push(...images);
		}
		this.agent.steer({
			role: "user",
			content,
			timestamp: Date.now(),
		});
	}

	/**
	 * Internal: Queue a follow-up message (already expanded, no extension command check).
	 */
	private async _queueFollowUp(
		text: string,
		images?: ImageContent[],
		references: readonly SkillReferenceSnapshot[] = [],
		forceLoaded: readonly SkillReferenceSnapshot[] = [],
		recordAdmission = true,
	): Promise<void> {
		await this._traceOperation("queue", (operationSpan) => {
			if (recordAdmission) {
				this._recordSkillAdmission(
					operationSpan,
					this._snapshotSkillCatalog(),
					references,
					forceLoaded,
					this.agent.state.systemPrompt,
				);
			}
			return this._enqueueFollowUp(text, images);
		});
	}

	private async _enqueueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
		this._followUpMessages.push(text);
		this._emitQueueUpdate();
		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
		if (images) {
			content.push(...images);
		}
		this.agent.followUp({
			role: "user",
			content,
			timestamp: Date.now(),
		});
	}

	/**
	 * Throw an error if the text is an extension command.
	 */
	private _throwIfExtensionCommand(text: string): void {
		const spaceIndex = text.indexOf(" ");
		const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
		const command = this._extensionRunner.getCommand(commandName);

		if (command) {
			throw new Error(
				`Extension command "/${commandName}" cannot be queued. Use prompt() or execute the command when not streaming.`,
			);
		}
	}

	/**
	 * Send a custom message to the session. Creates a CustomMessageEntry.
	 *
	 * Handles three cases:
	 * - Streaming: queues message, processed when loop pulls from queue
	 * - Not streaming + triggerTurn: appends to state/session, starts new turn
	 * - Not streaming + no trigger: appends to state/session, no turn
	 *
	 * @param message Custom message with customType, content, display, details
	 * @param options.triggerTurn If true and not streaming, triggers a new LLM turn
	 * @param options.deliverAs Delivery mode: "steer", "followUp", or "nextTurn"
	 */
	async sendCustomMessage<T = unknown>(
		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
	): Promise<void> {
		const appMessage = {
			role: "custom" as const,
			customType: message.customType,
			// Untyped extensions can pass null/missing content; normalize at ingestion.
			content: message.content ?? [],
			display: message.display,
			details: message.details,
			timestamp: Date.now(),
		} satisfies CustomMessage<T>;
		if (options?.deliverAs === "nextTurn") {
			this._pendingNextTurnMessages.push(appMessage);
		} else if (this.isStreaming) {
			if (options?.deliverAs === "followUp") {
				this.agent.followUp(appMessage);
			} else {
				this.agent.steer(appMessage);
			}
		} else if (options?.triggerTurn) {
			await this._runAgentPrompt(appMessage);
		} else {
			this.agent.state.messages.push(appMessage);
			this.sessionManager.appendCustomMessageEntry(
				message.customType,
				message.content,
				message.display,
				message.details,
			);
			this._emit({ type: "message_start", message: appMessage });
			this._emit({ type: "message_end", message: appMessage });
		}
	}

	private async _acceptSubagentEscalation(name: string, message: string): Promise<void> {
		if (this._disposePromise) throw new Error("Agent session is disposed");
		const pendingCharacters =
			(this._pendingSubagentEscalationEnvelope?.messageCharacters ?? 0) +
			[...this._pendingIdleSubagentEscalations.values()].reduce((sum, length) => sum + length, 0);
		if (pendingCharacters + message.length > MAX_PENDING_SUBAGENT_ESCALATION_CHARACTERS) {
			throw new Error("Subagent escalation pending capacity exceeded");
		}

		if (this.isStreaming) {
			const pending = this._pendingSubagentEscalationEnvelope;
			if (pending) {
				pending.escalations.push({ name, message });
				pending.messageCharacters += message.length;
				pending.message.content = JSON.stringify({
					type: "subagent_escalations",
					escalations: pending.escalations,
				});
				pending.message.details = { names: pending.escalations.map((entry) => entry.name) };
				return;
			}

			const escalations: SubagentEscalationEntry[] = [{ name, message }];
			const appMessage: CustomMessage<{ names: string[] }> = {
				role: "custom",
				customType: "subagent_escalations",
				content: JSON.stringify({ type: "subagent_escalations", escalations }),
				display: false,
				details: { names: [name] },
				timestamp: Date.now(),
			};
			this._pendingSubagentEscalationEnvelope = {
				message: appMessage,
				escalations,
				messageCharacters: message.length,
			};
			try {
				this.agent.steer(appMessage);
			} catch (error) {
				if (this._pendingSubagentEscalationEnvelope?.message === appMessage) {
					this._pendingSubagentEscalationEnvelope = undefined;
				}
				throw error;
			}
			this._exitSubagentCoordination("escalation");
			return;
		}

		const appMessage: CustomMessage<{ names: string[] }> = {
			role: "custom",
			customType: "subagent_escalations",
			content: JSON.stringify({
				type: "subagent_escalations",
				escalations: [{ name, message }],
			}),
			display: false,
			details: { names: [name] },
			timestamp: Date.now(),
		};
		const entryId = appendCustomMessageWithRollback(
			this.sessionManager,
			appMessage.customType,
			appMessage.content,
			appMessage.display,
			appMessage.details,
		);
		this.agent.state.messages.push(appMessage);
		this._pendingIdleSubagentEscalations.set(entryId, message.length);
		this._emitEscalationObservation({ type: "message_start", message: appMessage });
		this._emitEscalationObservation({ type: "message_end", message: appMessage });
	}

	private _emitEscalationObservation(event: AgentSessionEvent): void {
		for (const listener of [...this._eventListeners]) {
			try {
				listener(event);
			} catch {
				// Idle escalation admission is already committed; passive listener failures are isolated.
			}
		}
	}

	private _filterPendingIdleSubagentEscalationsToSelectedBranch(): void {
		const selectedIds = new Set(this.sessionManager.getBranch().map((entry) => entry.id));
		for (const entryId of this._pendingIdleSubagentEscalations.keys()) {
			if (!selectedIds.has(entryId)) this._pendingIdleSubagentEscalations.delete(entryId);
		}
	}

	private _releaseIdleSubagentEscalationsForSelectedBranch(): void {
		this._filterPendingIdleSubagentEscalationsToSelectedBranch();
		this._pendingIdleSubagentEscalations.clear();
	}

	/**
	 * Send a user message to the agent. Always triggers a turn.
	 * When the agent is streaming, use deliverAs to specify how to queue the message.
	 *
	 * @param content User message content (string or content array)
	 * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
	 */
	async sendUserMessage(
		content: string | (TextContent | ImageContent)[],
		options?: { deliverAs?: "steer" | "followUp" },
	): Promise<void> {
		// Normalize content to text string + optional images
		let text: string;
		let images: ImageContent[] | undefined;

		if (typeof content === "string") {
			text = content;
		} else {
			const textParts: string[] = [];
			images = [];
			for (const part of content) {
				if (part.type === "text") {
					textParts.push(part.text);
				} else {
					images.push(part);
				}
			}
			text = textParts.join("\n");
			if (images.length === 0) images = undefined;
		}

		// Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
		await this.prompt(text, {
			expandPromptTemplates: false,
			streamingBehavior: options?.deliverAs,
			images,
			source: "extension",
		});
	}

	/**
	 * Clear all queued messages and return them.
	 * Useful for restoring to editor when user aborts.
	 * @returns Object with steering and followUp arrays
	 */
	clearQueue(): { steering: string[]; followUp: string[] } {
		const steering = [...this._steeringMessages];
		const followUp = [...this._followUpMessages];
		this._steeringMessages = [];
		this._followUpMessages = [];
		this._pendingSubagentEscalationEnvelope = undefined;
		this.agent.clearAllQueues();
		this._emitQueueUpdate();
		return { steering, followUp };
	}

	/** Number of pending messages (includes both steering and follow-up) */
	get pendingMessageCount(): number {
		return this._steeringMessages.length + this._followUpMessages.length;
	}

	/** Get pending steering messages (read-only) */
	getSteeringMessages(): readonly string[] {
		return this._steeringMessages;
	}

	/** Get pending follow-up messages (read-only) */
	getFollowUpMessages(): readonly string[] {
		return this._followUpMessages;
	}

	get resourceLoader(): ResourceLoader {
		return this._resourceLoader;
	}

	/**
	 * Abort current operation and wait for agent to become idle.
	 */
	async abort(): Promise<void> {
		if (this._isAgentRunActive) this._agentRunAborted = true;
		this._exitSubagentCoordination("cancellation");
		return this._traceOperation("abort", () => this._abort());
	}

	private async _abort(): Promise<void> {
		this.abortRetry();
		this.abortCompaction();
		this.abortBranchSummary();
		this.abortBash();
		if (this._isAgentRunActive) this._agentRunAborted = true;
		this._exitSubagentCoordination("cancellation");
		this.agent.abort();
		await Promise.all([this.waitForIdle(), this.terminateOwnedShellProcesses(), ...this._bashOperations]);
	}

	/** Stop and verify all shell processes owned by this session, including background jobs. */
	async terminateOwnedShellProcesses(): Promise<void> {
		await this._shellProcesses.terminateAll();
	}

	get backgroundProcessPolicy(): BackgroundProcessPolicy {
		return this._shellProcesses.policy;
	}

	get ownedShellProcessCount(): number {
		return this._shellProcesses.count;
	}

	async waitForIdle(): Promise<void> {
		if (this.isIdle) {
			return;
		}
		await this._getIdleWaitPromise();
	}

	// =========================================================================
	// Model Management
	// =========================================================================

	private async _emitModelSelect(
		nextModel: Model<any>,
		previousModel: Model<any> | undefined,
		source: "set" | "cycle" | "restore",
	): Promise<void> {
		if (modelsAreEqual(previousModel, nextModel)) return;
		await this._extensionRunner.emit({
			type: "model_select",
			model: nextModel,
			previousModel,
			source,
		});
	}

	/**
	 * Set model directly.
	 * Validates that auth is configured, saves to session and settings.
	 * @throws Error if no auth is configured for the model
	 */
	async setModel(model: Model<any>): Promise<void> {
		if (!(await this._modelRuntime.checkAuth(model.provider))) {
			throw new Error(`No API key for ${model.provider}/${model.id}`);
		}

		const previousModel = this.model;
		const thinkingLevel = this._getThinkingLevelForModelSwitch();
		this.agent.state.model = model;
		this.sessionManager.appendModelChange(model.provider, model.id);
		this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);

		// Re-clamp thinking level for new model's capabilities
		this.setThinkingLevel(thinkingLevel);

		await this._emitModelSelect(model, previousModel, "set");
	}

	/**
	 * Cycle to next/previous model.
	 * Uses scoped models (from --models flag) if available, otherwise all available models.
	 * @param direction - "forward" (default) or "backward"
	 * @returns The new model info, or undefined if only one model available
	 */
	async cycleModel(direction: "forward" | "backward" = "forward"): Promise<ModelCycleResult | undefined> {
		if (this._scopedModels.length > 0) {
			return this._cycleScopedModel(direction);
		}
		return this._cycleAvailableModel(direction);
	}

	private async _cycleScopedModel(direction: "forward" | "backward"): Promise<ModelCycleResult | undefined> {
		const availableIds = new Set(
			this._modelRuntime.getAvailableSnapshot().map((model) => `${model.provider}\0${model.id}`),
		);
		const scopedModels = this._scopedModels.filter((scoped) =>
			availableIds.has(`${scoped.model.provider}\0${scoped.model.id}`),
		);
		if (scopedModels.length <= 1) return undefined;

		const currentModel = this.model;
		let currentIndex = scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));

		if (currentIndex === -1) currentIndex = 0;
		const len = scopedModels.length;
		const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
		const next = scopedModels[nextIndex];
		const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);

		// Apply model
		this.agent.state.model = next.model;
		this.sessionManager.appendModelChange(next.model.provider, next.model.id);
		this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);

		// Apply thinking level.
		// - Explicit scoped model thinking level overrides current session level
		// - Undefined scoped model thinking level inherits the current session preference
		// setThinkingLevel clamps to model capabilities.
		this.setThinkingLevel(thinkingLevel);

		await this._emitModelSelect(next.model, currentModel, "cycle");

		return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
	}

	private async _cycleAvailableModel(direction: "forward" | "backward"): Promise<ModelCycleResult | undefined> {
		const availableModels = this._modelRuntime.getAvailableSnapshot();
		if (availableModels.length <= 1) return undefined;

		const currentModel = this.model;
		let currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel));

		if (currentIndex === -1) currentIndex = 0;
		const len = availableModels.length;
		const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
		const nextModel = availableModels[nextIndex];

		const thinkingLevel = this._getThinkingLevelForModelSwitch();
		this.agent.state.model = nextModel;
		this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
		this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);

		// Re-clamp thinking level for new model's capabilities
		this.setThinkingLevel(thinkingLevel);

		await this._emitModelSelect(nextModel, currentModel, "cycle");

		return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
	}

	// =========================================================================
	// Thinking Level Management
	// =========================================================================

	/**
	 * Set thinking level.
	 * Clamps to model capabilities based on available thinking levels.
	 * Saves to session and settings only if the level actually changes.
	 */
	setThinkingLevel(level: ThinkingLevel): void {
		const availableLevels = this.getAvailableThinkingLevels();
		const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);

		// Only persist if actually changing
		const previousLevel = this.agent.state.thinkingLevel;
		const isChanging = effectiveLevel !== previousLevel;

		this.agent.state.thinkingLevel = effectiveLevel;

		if (isChanging) {
			this.sessionManager.appendThinkingLevelChange(effectiveLevel);
			if (this.supportsThinking() || effectiveLevel !== "off") {
				this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
			}
			this._emit({ type: "thinking_level_changed", level: effectiveLevel });
			void this._extensionRunner.emit({
				type: "thinking_level_select",
				level: effectiveLevel,
				previousLevel,
			});
		}
	}

	/**
	 * Cycle to next thinking level.
	 * @returns New level, or undefined if model doesn't support thinking
	 */
	cycleThinkingLevel(): ThinkingLevel | undefined {
		if (!this.supportsThinking()) return undefined;

		const levels = this.getAvailableThinkingLevels();
		const currentIndex = levels.indexOf(this.thinkingLevel);
		const nextIndex = (currentIndex + 1) % levels.length;
		const nextLevel = levels[nextIndex];

		this.setThinkingLevel(nextLevel);
		return nextLevel;
	}

	/**
	 * Get available thinking levels for current model.
	 * The provider will clamp to what the specific model supports internally.
	 */
	getAvailableThinkingLevels(): ThinkingLevel[] {
		if (!this.model) return THINKING_LEVELS;
		return getSupportedThinkingLevels(this.model) as ThinkingLevel[];
	}

	/**
	 * Check if current model supports thinking/reasoning.
	 */
	supportsThinking(): boolean {
		return !!this.model?.reasoning;
	}

	private _getThinkingLevelForModelSwitch(explicitLevel?: ThinkingLevel): ThinkingLevel {
		if (explicitLevel !== undefined) {
			return explicitLevel;
		}
		if (!this.supportsThinking()) {
			return this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
		}
		return this.thinkingLevel;
	}

	private _clampThinkingLevel(level: ThinkingLevel, _availableLevels: ThinkingLevel[]): ThinkingLevel {
		return this.model ? (clampThinkingLevel(this.model, level) as ThinkingLevel) : "off";
	}

	// =========================================================================
	// Queue Mode Management
	// =========================================================================

	private syncQueueModesFromSettings(): void {
		this.agent.steeringMode = this.settingsManager.getSteeringMode();
		this.agent.followUpMode = this.settingsManager.getFollowUpMode();
	}

	/**
	 * Set steering message mode.
	 * Saves to settings.
	 */
	setSteeringMode(mode: "all" | "one-at-a-time"): void {
		this.agent.steeringMode = mode;
		this.settingsManager.setSteeringMode(mode);
	}

	/**
	 * Set follow-up message mode.
	 * Saves to settings.
	 */
	setFollowUpMode(mode: "all" | "one-at-a-time"): void {
		this.agent.followUpMode = mode;
		this.settingsManager.setFollowUpMode(mode);
	}

	// =========================================================================
	// Compaction
	// =========================================================================

	/**
	 * Manually compact the session context.
	 * Aborts current agent operation first.
	 * @param customInstructions Optional instructions for the compaction summary
	 */
	compact(customInstructions?: string): Promise<CompactionResult> {
		this._manualCompactionOperations++;
		return this._runOwnedOperation(() =>
			this._traceOperation("compaction", (telemetryContext) => this._compact(customInstructions, telemetryContext)),
		).finally(() => {
			this._manualCompactionOperations--;
		});
	}

	private async _compact(customInstructions?: string, telemetryContext?: TelemetryContext): Promise<CompactionResult> {
		await this.abort();
		if (this._disposePromise) {
			throw new Error("Compaction cancelled");
		}
		this._compactionAbortController = new AbortController();
		this._emit({ type: "compaction_start", reason: "manual" });

		try {
			if (!this.model) {
				throw new Error(formatNoModelSelectedMessage());
			}

			const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(this.model);

			const pathEntries = this.sessionManager.getBranch();
			const settings = this.settingsManager.getCompactionSettings();

			const preparation = prepareCompaction(pathEntries, settings);
			if (!preparation) {
				// Check why we can't compact
				const lastEntry = pathEntries[pathEntries.length - 1];
				if (lastEntry?.type === "compaction") {
					throw new Error("Already compacted");
				}
				throw new Error("Nothing to compact (session too small)");
			}

			let extensionCompaction: CompactionResult | undefined;
			let fromExtension = false;

			if (this._extensionRunner.hasHandlers("session_before_compact")) {
				const result = (await this._extensionRunner.emit({
					type: "session_before_compact",
					preparation,
					branchEntries: pathEntries,
					customInstructions,
					reason: "manual",
					willRetry: false,
					signal: this._compactionAbortController.signal,
				})) as SessionBeforeCompactResult | undefined;

				if (result?.cancel) {
					throw new Error("Compaction cancelled");
				}

				if (result?.compaction) {
					extensionCompaction = result.compaction;
					fromExtension = true;
				}
			}

			let summary: string;
			let firstKeptEntryId: string;
			let tokensBefore: number;
			let usage: Usage | undefined;
			let details: unknown;

			if (extensionCompaction) {
				// Extension provided compaction content
				summary = extensionCompaction.summary;
				firstKeptEntryId = extensionCompaction.firstKeptEntryId;
				tokensBefore = extensionCompaction.tokensBefore;
				usage = extensionCompaction.usage;
				details = extensionCompaction.details;
			} else {
				// Generate compaction result
				const result = await compact(
					preparation,
					requestModel,
					apiKey,
					headers,
					customInstructions,
					this._compactionAbortController.signal,
					this.thinkingLevel,
					this.agent.streamFunction,
					env,
					this.settingsManager.getRetrySettings(),
					this._summarizationRetryCallbacks({ source: "compaction", reason: "manual" }, telemetryContext),
					telemetryContext,
				);
				summary = result.summary;
				firstKeptEntryId = result.firstKeptEntryId;
				tokensBefore = result.tokensBefore;
				usage = result.usage;
				details = result.details;
			}

			if (this._compactionAbortController.signal.aborted) {
				throw new Error("Compaction cancelled");
			}

			const compactionResult = await this._recordSuccessfulCompaction({
				reason: "manual",
				summary,
				firstKeptEntryId,
				tokensBefore,
				details,
				fromExtension,
				usage,
				willRetry: false,
			});
			const refreshError = await this._refreshHarnessAfterCompaction();
			// compaction_end listeners may submit queued prompts, so expose idle state before notifying them.
			this._compactionAbortController = undefined;
			this._emit({
				type: "compaction_end",
				reason: "manual",
				result: compactionResult,
				aborted: false,
				willRetry: false,
				errorMessage: refreshError,
			});
			return compactionResult;
		} catch (error) {
			const message = error instanceof Error ? error.message : String(error);
			const aborted = message === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError");
			this._compactionAbortController = undefined;
			this._emit({
				type: "compaction_end",
				reason: "manual",
				result: undefined,
				aborted,
				willRetry: false,
				errorMessage: aborted ? undefined : `Compaction failed: ${message}`,
			});
			throw error;
		} finally {
			this._compactionAbortController = undefined;
		}
	}

	/**
	 * Cancel in-progress compaction (manual or auto).
	 */
	abortCompaction(): void {
		this._compactionAbortController?.abort();
		this._autoCompactionAbortController?.abort();
	}

	/**
	 * Cancel in-progress branch summarization.
	 */
	abortBranchSummary(): void {
		this._branchSummaryAbortController?.abort();
	}

	private async _recordSuccessfulCompaction(options: {
		reason: "manual" | "threshold" | "overflow";
		summary: string;
		firstKeptEntryId: string;
		tokensBefore: number;
		details: unknown;
		fromExtension: boolean;
		usage: Usage | undefined;
		willRetry: boolean;
		signal?: AbortSignal;
		deferCommit?: (transaction: CompactionAppendTransaction) => void;
	}): Promise<CompactionResult> {
		const summary = `${options.summary}\n\n${formatCurrentPlanSnapshot(this.sessionManager)}`;
		const transaction = appendCompactionTransaction(
			this.sessionManager,
			summary,
			options.firstKeptEntryId,
			options.tokensBefore,
			options.details,
			options.fromExtension,
			options.usage,
		);
		const sessionContext = this.sessionManager.buildSessionContext();
		this.agent.state.messages = sessionContext.messages;
		const estimatedTokensAfter = estimateMessagesTokens(sessionContext.messages);

		if (this._extensionRunner) {
			try {
				await this._extensionRunner.emit({
					type: "session_compact",
					compactionEntry: transaction.entry,
					fromExtension: options.fromExtension,
					reason: options.reason,
					willRetry: options.willRetry,
				});
			} catch (error) {
				if (options.signal?.aborted) {
					transaction.rollback();
					this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
					throw options.signal.reason;
				}
				transaction.commit();
				throw error;
			}
		}
		if (options.signal?.aborted) {
			transaction.rollback();
			this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
			throw options.signal.reason;
		}
		if (options.deferCommit) options.deferCommit(transaction);
		else transaction.commit();

		const compactionResult: CompactionResult = {
			summary,
			firstKeptEntryId: options.firstKeptEntryId,
			tokensBefore: options.tokensBefore,
			estimatedTokensAfter,
			usage: options.usage,
			details: options.details,
		};
		return compactionResult;
	}

	/**
	 * Check if compaction is needed and run it.
	 * Called after agent_end and before prompt submission.
	 *
	 * Two cases:
	 * 1. Recoverable failure: LLM returned context overflow or stopped below its desired output limit;
	 *    remove the assistant message, compact, and auto-retry once
	 * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
	 *
	 * @param assistantMessage The assistant message to check
	 * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
	 */
	private async _checkCompaction(
		assistantMessage: AssistantMessage,
		skipAbortedCheck = true,
		signal?: AbortSignal,
		deferCommit?: (transaction: CompactionAppendTransaction) => void,
	): Promise<boolean> {
		const settings = this.settingsManager.getCompactionSettings();
		if (!settings.enabled) return false;

		// Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
		if (skipAbortedCheck && assistantMessage.stopReason === "aborted") return false;

		const contextWindow = this.model?.contextWindow ?? 0;

		// Skip overflow check if the message came from a different model.
		// This handles the case where user switched from a smaller-context model (e.g. opus)
		// to a larger-context model (e.g. codex) - the overflow error from the old model
		// shouldn't trigger compaction for the new model.
		const sameModel =
			this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;

		// Skip compaction checks if this assistant message is older than the latest
		// compaction boundary. This prevents a stale pre-compaction usage/error
		// from retriggering compaction on the first prompt after compaction.
		const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());
		const assistantIsFromBeforeCompaction =
			compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();
		if (assistantIsFromBeforeCompaction) {
			return false;
		}

		// Case 1: Recoverable failure. Explicit/silent context overflow still uses context metadata.
		// A length stop is recoverable when output ended below the model's original desired limit,
		// independent of the configured context size or any context-clamped provider request limit.
		// A successful response over the configured window should compact but must not retry: the
		// assistant answer already completed and agent.continue() cannot continue from an assistant.
		const recoverableLength = sameModel && isRecoverableLength(assistantMessage, this.model?.maxTokens ?? 0);
		if (sameModel && (isContextOverflow(assistantMessage, contextWindow) || recoverableLength)) {
			const willRetry = assistantMessage.stopReason !== "stop";

			if (!willRetry) {
				return await this._runAutoCompaction("overflow", false, signal, deferCommit);
			}

			if (this._overflowRecoveryAttempted) {
				this._emit({
					type: "compaction_end",
					reason: "overflow",
					result: undefined,
					aborted: false,
					willRetry: false,
					errorMessage:
						"Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.",
				});
				return false;
			}

			this._overflowRecoveryAttempted = true;
			// Remove the failed or truncated message from agent state. It remains in session history,
			// but must not be included in the compact-and-retry context.
			const messages = this.agent.state.messages;
			if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
				this.agent.state.messages = messages.slice(0, -1);
			}
			return await this._runAutoCompaction("overflow", willRetry, signal, deferCommit);
		}

		// Case 2: Threshold - context is getting large
		// For error messages or all-zero usage messages, estimate from the last valid response.
		// This ensures sessions that hit persistent API errors (e.g. 529) or malformed zero-usage
		// responses can still compact and do not reset context accounting.
		let contextTokens: number;
		const directContextTokens = assistantMessage.usage ? calculateContextTokens(assistantMessage.usage) : 0;
		if (assistantMessage.stopReason === "error" || directContextTokens === 0) {
			const messages = this.agent.state.messages;
			const estimate = estimateContextTokens(messages);
			if (estimate.lastUsageIndex === null) return false; // No usage data at all
			// Verify the usage source is post-compaction. Kept pre-compaction messages
			// have stale usage reflecting the old (larger) context and would falsely
			// trigger compaction right after one just finished.
			const usageMsg = messages[estimate.lastUsageIndex];
			if (
				compactionEntry &&
				usageMsg.role === "assistant" &&
				(usageMsg as AssistantMessage).timestamp <= new Date(compactionEntry.timestamp).getTime()
			) {
				return false;
			}
			contextTokens = estimate.tokens;
		} else {
			contextTokens = directContextTokens;
		}
		if (shouldCompact(contextTokens, contextWindow, settings)) {
			const queuedContinuation = await this._runAutoCompaction("threshold", false, signal, deferCommit);
			// Threshold compaction does not recover a provider failure.
			return assistantMessage.stopReason !== "error" && queuedContinuation;
		}
		return false;
	}

	/**
	 * Internal: Run auto-compaction with events.
	 */
	private _runAutoCompaction(
		reason: "overflow" | "threshold",
		willRetry: boolean,
		signal?: AbortSignal,
		deferCommit?: (transaction: CompactionAppendTransaction) => void,
	): Promise<boolean> {
		if (this._disposePromise) return Promise.resolve(false);
		return this._runOwnedOperation(() =>
			this._traceOperation("compaction", (telemetryContext) =>
				this._runAutoCompactionOperation(reason, willRetry, telemetryContext, signal, deferCommit),
			),
		);
	}

	private async _runAutoCompactionOperation(
		reason: "overflow" | "threshold",
		willRetry: boolean,
		telemetryContext: TelemetryContext = this._telemetryContext,
		signal?: AbortSignal,
		deferCommit?: (transaction: CompactionAppendTransaction) => void,
	): Promise<boolean> {
		const settings = this.settingsManager.getCompactionSettings();
		let started = false;

		try {
			if (!this.model) {
				return false;
			}

			const {
				model: requestModel,
				apiKey,
				headers,
				env,
			} = await this._getSummarizationRequestAuth(this.model, signal);
			signal?.throwIfAborted();
			if (this._disposePromise) return false;

			const pathEntries = this.sessionManager.getBranch();

			const preparation = prepareCompaction(pathEntries, settings);
			if (!preparation) {
				return false;
			}

			this._autoCompactionAbortController = new AbortController();
			const compactionSignal = signal
				? AbortSignal.any([signal, this._autoCompactionAbortController.signal])
				: this._autoCompactionAbortController.signal;
			this._emit({ type: "compaction_start", reason });
			started = true;

			let extensionCompaction: CompactionResult | undefined;
			let fromExtension = false;

			if (this._extensionRunner.hasHandlers("session_before_compact")) {
				const extensionResult = (await this._extensionRunner.emit({
					type: "session_before_compact",
					preparation,
					branchEntries: pathEntries,
					customInstructions: undefined,
					reason,
					willRetry,
					signal: compactionSignal,
				})) as SessionBeforeCompactResult | undefined;

				if (extensionResult?.cancel) {
					this._emit({
						type: "compaction_end",
						reason,
						result: undefined,
						aborted: true,
						willRetry: false,
					});
					return false;
				}

				if (extensionResult?.compaction) {
					extensionCompaction = extensionResult.compaction;
					fromExtension = true;
				}
			}

			let summary: string;
			let firstKeptEntryId: string;
			let tokensBefore: number;
			let usage: Usage | undefined;
			let details: unknown;

			if (extensionCompaction) {
				// Extension provided compaction content
				summary = extensionCompaction.summary;
				firstKeptEntryId = extensionCompaction.firstKeptEntryId;
				tokensBefore = extensionCompaction.tokensBefore;
				usage = extensionCompaction.usage;
				details = extensionCompaction.details;
			} else {
				// Generate compaction result
				const compactResult = await compact(
					preparation,
					requestModel,
					apiKey,
					headers,
					undefined,
					compactionSignal,
					this.thinkingLevel,
					this.agent.streamFunction,
					env,
					this.settingsManager.getRetrySettings(),
					this._summarizationRetryCallbacks({ source: "compaction", reason }, telemetryContext),
					telemetryContext,
				);
				summary = compactResult.summary;
				firstKeptEntryId = compactResult.firstKeptEntryId;
				tokensBefore = compactResult.tokensBefore;
				usage = compactResult.usage;
				details = compactResult.details;
			}

			if (compactionSignal.aborted) {
				this._emit({
					type: "compaction_end",
					reason,
					result: undefined,
					aborted: true,
					willRetry: false,
				});
				return false;
			}

			const result = await this._recordSuccessfulCompaction({
				reason,
				summary,
				firstKeptEntryId,
				tokensBefore,
				details,
				fromExtension,
				usage,
				willRetry,
				signal,
				deferCommit,
			});
			const refreshError = deferCommit ? undefined : await this._refreshHarnessAfterCompaction();
			this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry, errorMessage: refreshError });

			if (willRetry) {
				const messages = this.agent.state.messages;
				const lastMsg = messages[messages.length - 1];
				// The overflow response was persisted on message_end before _checkCompaction() removed it
				// from agent state. Rebuilding state from the new compaction can restore that kept entry,
				// leaving an assistant as the final message. agent.continue() rejects that state, so remove
				// the retriable error or truncated-length response again before continuing the interrupted turn.
				if (lastMsg?.role === "assistant" && (lastMsg.stopReason === "error" || lastMsg.stopReason === "length")) {
					this.agent.state.messages = messages.slice(0, -1);
				}
				return true;
			}

			// Auto-compaction can complete while follow-up/steering/custom messages are waiting.
			// Continue once so queued messages are delivered.
			return this.agent.hasQueuedMessages();
		} catch (error) {
			const errorMessage = error instanceof Error ? error.message : "compaction failed";
			const aborted = signal?.aborted || this._autoCompactionAbortController?.signal.aborted || false;
			if (started) {
				this._emit({
					type: "compaction_end",
					reason,
					result: undefined,
					aborted,
					willRetry: false,
					...(aborted
						? {}
						: {
								errorMessage:
									reason === "overflow"
										? `Context overflow recovery failed: ${errorMessage}`
										: `Auto-compaction failed: ${errorMessage}`,
							}),
				});
			}
			return false;
		} finally {
			this._autoCompactionAbortController = undefined;
		}
	}

	/**
	 * Toggle auto-compaction setting.
	 */
	setAutoCompactionEnabled(enabled: boolean): void {
		this.settingsManager.setCompactionEnabled(enabled);
	}

	/** Whether auto-compaction is enabled */
	get autoCompactionEnabled(): boolean {
		return this.settingsManager.getCompactionEnabled();
	}

	async bindExtensions(bindings: ExtensionBindings): Promise<void> {
		if (bindings.uiContext !== undefined) {
			this._extensionUIContext = bindings.uiContext;
		}
		if (bindings.mode !== undefined) {
			this._extensionMode = bindings.mode;
		}
		if (bindings.commandContextActions !== undefined) {
			this._extensionCommandContextActions = bindings.commandContextActions;
		}
		if (bindings.abortHandler !== undefined) {
			this._extensionAbortHandler = bindings.abortHandler;
		}
		if (bindings.shutdownHandler !== undefined) {
			this._extensionShutdownHandler = bindings.shutdownHandler;
		}
		if (bindings.onError !== undefined) {
			this._extensionErrorListener = bindings.onError;
		}

		this._applyExtensionBindings(this._extensionRunner);
		await this._extensionRunner.emit(this._sessionStartEvent);
		await this.extendResourcesFromExtensions(this._sessionStartEvent.reason === "reload" ? "reload" : "startup");
	}

	private async extendResourcesFromExtensions(reason: "startup" | "reload"): Promise<void> {
		if (!this._extensionRunner.hasHandlers("resources_discover")) {
			return;
		}

		const { skillPaths, promptPaths, themePaths } = await this._extensionRunner.emitResourcesDiscover(
			this._cwd,
			reason,
		);

		if (skillPaths.length === 0 && promptPaths.length === 0 && themePaths.length === 0) {
			return;
		}

		const extensionPaths: ResourceExtensionPaths = {
			skillPaths: this.buildExtensionResourcePaths(skillPaths),
			promptPaths: this.buildExtensionResourcePaths(promptPaths),
			themePaths: this.buildExtensionResourcePaths(themePaths),
		};

		this._resourceLoader.extendResources(extensionPaths);
		if (this._activeRunCollaborationMode === "plan") return;
		this._installCollaborationModeState(
			this._deriveCollaborationModeState(this._activeRunCollaborationMode ?? this._collaborationMode),
		);
	}

	private buildExtensionResourcePaths(entries: Array<{ path: string; extensionPath: string }>): Array<{
		path: string;
		metadata: { source: string; scope: "temporary"; origin: "top-level"; baseDir?: string };
	}> {
		return entries.map((entry) => {
			const source = this.getExtensionSourceLabel(entry.extensionPath);
			const baseDir = entry.extensionPath.startsWith("<") ? undefined : dirname(entry.extensionPath);
			return {
				path: entry.path,
				metadata: {
					source,
					scope: "temporary",
					origin: "top-level",
					baseDir,
				},
			};
		});
	}

	private getExtensionSourceLabel(extensionPath: string): string {
		if (extensionPath.startsWith("<")) {
			return `extension:${extensionPath.replace(/[<>]/g, "")}`;
		}
		const base = basename(extensionPath);
		const name = base.replace(/\.(ts|js)$/, "");
		return `extension:${name}`;
	}

	private _applyExtensionBindings(runner: ExtensionRunner): void {
		runner.setUIContext(this._extensionUIContext, this._extensionMode);
		runner.bindCommandContext(this._extensionCommandContextActions);

		this._extensionErrorUnsubscriber?.();
		this._extensionErrorUnsubscriber = this._extensionErrorListener
			? runner.onError(this._extensionErrorListener)
			: undefined;
	}

	private _refreshCurrentModelFromRegistry(): void {
		const currentModel = this.model;
		if (!currentModel) {
			return;
		}

		const refreshedModel = this._modelRuntime.getModel(currentModel.provider, currentModel.id);
		if (!refreshedModel || refreshedModel === currentModel) {
			return;
		}

		this.agent.state.model = refreshedModel;
	}

	private _bindExtensionCore(runner: ExtensionRunner): void {
		const getCommands = (): SlashCommandInfo[] => {
			const extensionCommands: SlashCommandInfo[] = runner.getRegisteredCommands().map((command) => ({
				name: command.invocationName,
				description: command.description,
				source: "extension",
				sourceInfo: command.sourceInfo,
			}));

			const templates: SlashCommandInfo[] = this.promptTemplates.map((template) => ({
				name: template.name,
				description: template.description,
				source: "prompt",
				sourceInfo: template.sourceInfo,
			}));

			return [...extensionCommands, ...templates];
		};

		runner.bindCore(
			{
				sendMessage: (message, options) => {
					this.sendCustomMessage(message, options).catch((err) => {
						runner.emitError({
							extensionPath: "<runtime>",
							event: "send_message",
							error: err instanceof Error ? err.message : String(err),
						});
					});
				},
				sendUserMessage: (content, options) => {
					this.sendUserMessage(content, options).catch((err) => {
						runner.emitError({
							extensionPath: "<runtime>",
							event: "send_user_message",
							error: err instanceof Error ? err.message : String(err),
						});
					});
				},
				appendEntry: (customType, data) => {
					const entryId = this.sessionManager.appendCustomEntry(customType, data);
					const entry = this.sessionManager.getEntry(entryId);
					if (entry) {
						this._emit({ type: "entry_appended", entry });
					}
				},
				setSessionName: (name) => {
					this.setSessionName(name);
				},
				getSessionName: () => {
					return this.sessionManager.getSessionName();
				},
				setLabel: (entryId, label) => {
					this.sessionManager.appendLabelChange(entryId, label);
				},
				getActiveTools: () => this.getActiveToolNames(),
				getAllTools: () => this.getAllTools(),
				setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
				refreshTools: () => this._refreshToolRegistry(),
				getCommands,
				setModel: async (model) => {
					if (!this._modelRuntime.hasConfiguredAuth(model.provider)) return false;
					await this.setModel(model);
					return true;
				},
				getThinkingLevel: () => this.thinkingLevel,
				setThinkingLevel: (level) => this.setThinkingLevel(level),
			},
			{
				getModel: () => this.model,
				getScopedModels: () => this._scopedModels,
				isIdle: () => this.isIdle,
				isProjectTrusted: () => this.settingsManager.isProjectTrusted(),
				getSignal: () => this.agent.signal,
				abort: () => {
					if (this._extensionAbortHandler) {
						this._extensionAbortHandler();
						return;
					}
					void this.abort();
				},
				hasPendingMessages: () => this.pendingMessageCount > 0,
				shutdown: () => {
					this._extensionShutdownHandler?.();
				},
				getContextUsage: () => this.getContextUsage(),
				compact: (options) => {
					void (async () => {
						try {
							const result = await this.compact(options?.customInstructions);
							options?.onComplete?.(result);
						} catch (error) {
							const err = error instanceof Error ? error : new Error(String(error));
							options?.onError?.(err);
						}
					})();
				},
				getSystemPrompt: () => this.systemPrompt,
				getSystemPromptOptions: () => this._baseSystemPromptOptions,
			},
			{
				registerProvider: (name, config) => {
					this._modelRuntime.registerProvider(name, config);
					this._refreshCurrentModelFromRegistry();
				},
				registerNativeProvider: (provider) => {
					this._modelRuntime.registerNativeProvider(provider);
					this._refreshCurrentModelFromRegistry();
				},
				unregisterProvider: (name) => {
					this._modelRuntime.unregisterProvider(name);
					this._refreshCurrentModelFromRegistry();
				},
			},
		);
	}

	private _refreshToolRegistry(options?: { activeToolNames?: string[]; includeAllExtensionTools?: boolean }): void {
		const previousRegistryNames = new Set(this._toolRegistry.keys());
		const previousRequestedToolNames = this._requestedToolNames;
		const allowedToolNames = this._allowedToolNames;
		const excludedToolNames = this._excludedToolNames;
		const isAllowedTool = (name: string): boolean =>
			(!allowedToolNames || allowedToolNames.has(name)) && !excludedToolNames?.has(name);

		const registeredTools = this._extensionRunner.getAllRegisteredTools();
		const allCustomTools = [
			...registeredTools,
			...this._customTools.map((definition) => ({
				definition,
				sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
			})),
		].filter((tool) => tool.definition.name !== REQUEST_USER_INPUT_TOOL_NAME && isAllowedTool(tool.definition.name));
		const definitionRegistry = new Map<string, ToolDefinitionEntry>(
			Array.from(this._baseToolDefinitions.entries())
				.filter(([name]) => isAllowedTool(name))
				.map(([name, definition]) => [
					name,
					{
						definition,
						sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
					},
				]),
		);
		for (const tool of allCustomTools) {
			definitionRegistry.set(tool.definition.name, {
				definition: tool.definition,
				sourceInfo: tool.sourceInfo,
			});
		}
		this._toolDefinitions = definitionRegistry;
		const runner = this._extensionRunner;
		const wrappedExtensionTools = wrapRegisteredTools(allCustomTools, runner);
		const wrappedBuiltInTools = wrapRegisteredTools(
			Array.from(this._baseToolDefinitions.values())
				.filter((definition) => isAllowedTool(definition.name))
				.map((definition) => ({
					definition,
					sourceInfo: createSyntheticSourceInfo(`<builtin:${definition.name}>`, { source: "builtin" }),
				})),
			runner,
		);
		this._baseToolRegistry = new Map(wrappedBuiltInTools.map((tool) => [tool.name, tool]));
		this._requestUserInputDefinition = isAllowedTool(REQUEST_USER_INPUT_TOOL_NAME)
			? (createRequestUserInputToolDefinition() as ToolDefinition)
			: undefined;
		this._requestUserInputTool = this._requestUserInputDefinition
			? wrapRegisteredTools(
					[
						{
							definition: this._requestUserInputDefinition,
							sourceInfo: createSyntheticSourceInfo(`<builtin:${REQUEST_USER_INPUT_TOOL_NAME}>`, {
								source: "builtin",
							}),
						},
					],
					runner,
				)[0]
			: undefined;

		const toolRegistry = new Map(wrappedBuiltInTools.map((tool) => [tool.name, tool]));
		for (const tool of wrappedExtensionTools as AgentTool[]) {
			toolRegistry.set(tool.name, tool);
		}
		this._toolRegistry = toolRegistry;

		const nextActiveToolNames = (
			options?.activeToolNames ? [...options.activeToolNames] : [...previousRequestedToolNames]
		).filter((name) => isAllowedTool(name));

		if (allowedToolNames) {
			for (const toolName of this._toolRegistry.keys()) {
				if (allowedToolNames.has(toolName)) {
					nextActiveToolNames.push(toolName);
				}
			}
		} else if (options?.includeAllExtensionTools) {
			for (const tool of wrappedExtensionTools) {
				nextActiveToolNames.push(tool.name);
			}
		} else if (!options?.activeToolNames) {
			for (const toolName of this._toolRegistry.keys()) {
				if (!previousRegistryNames.has(toolName)) {
					nextActiveToolNames.push(toolName);
				}
			}
		}

		this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
	}

	private _buildRuntime(options: {
		activeToolNames?: string[];
		flagValues?: Map<string, boolean | string>;
		includeAllExtensionTools?: boolean;
	}): void {
		const autoResizeImages = this.settingsManager.getImageAutoResize();
		const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
		const shellPath = this.settingsManager.getShellPath();
		const baseToolsOverrideEntries = this._baseToolsOverride
			? Object.entries(this._baseToolsOverride).filter(([name]) => name !== REQUEST_USER_INPUT_TOOL_NAME)
			: undefined;
		const baseToolDefinitions = baseToolsOverrideEntries
			? Object.fromEntries(
					baseToolsOverrideEntries.map(([name, tool]) => [name, createToolDefinitionFromAgentTool(tool)]),
				)
			: {
					...createAllToolDefinitions(this._cwd, {
						read: { autoResizeImages },
						bash: { commandPrefix: shellCommandPrefix, shellPath, owner: this._shellProcesses },
					}),
					update_plan: createSessionUpdatePlanToolDefinition(this.sessionManager),
				};

		this._baseToolDefinitions = new Map(
			Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool as ToolDefinition]),
		);

		const extensionsResult = this._resourceLoader.getExtensions();
		if (options.flagValues) {
			for (const [name, value] of options.flagValues) {
				extensionsResult.runtime.flagValues.set(name, value);
			}
		}

		this._extensionRunner = new ExtensionRunner(
			extensionsResult.extensions,
			extensionsResult.runtime,
			this._cwd,
			this.sessionManager,
			new ModelRegistry(this._modelRuntime),
			this._telemetryContext,
		);
		if (this._extensionRunnerRef) {
			this._extensionRunnerRef.current = this._extensionRunner;
		}
		this._bindExtensionCore(this._extensionRunner);
		this._applyExtensionBindings(this._extensionRunner);

		const defaultActiveToolNames = baseToolsOverrideEntries
			? baseToolsOverrideEntries.map(([name]) => name)
			: ["read", "bash", "edit", "write", "update_plan"];
		const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
		this._refreshToolRegistry({
			activeToolNames: baseActiveToolNames,
			includeAllExtensionTools: options.includeAllExtensionTools,
		});
	}

	async reload(options?: { beforeSessionStart?: () => void | Promise<void> }): Promise<void> {
		if (
			this._promptAdmissionInProgress ||
			this._harnessSwitchInProgress ||
			this.isStreaming ||
			this.agent.hasQueuedMessages() ||
			this.isRetrying ||
			this._manualCompactionOperations > 0 ||
			this.isCompacting ||
			this.isBashRunning
		) {
			throw new Error("Cannot reload while the session is busy.");
		}
		await this._subagentController?.reset();
		const oldRunner = this._extensionRunner;
		const previousFlagValues = oldRunner.getFlagValues();
		await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
		oldRunner.invalidate();
		await this.settingsManager.reload();
		this.syncQueueModesFromSettings();
		resetApiProviders();
		await this._resourceLoader.reload();
		this._buildRuntime({
			activeToolNames: this._requestedToolNames,
			flagValues: previousFlagValues,
			includeAllExtensionTools: true,
		});

		const hasBindings =
			this._extensionUIContext ||
			this._extensionCommandContextActions ||
			this._extensionShutdownHandler ||
			this._extensionErrorListener;
		if (hasBindings) {
			await options?.beforeSessionStart?.();
			await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
			await this.extendResourcesFromExtensions("reload");
		}
	}

	// =========================================================================
	// Auto-Retry
	// =========================================================================

	/**
	 * Check if an error is retryable (overloaded, rate limit, server errors).
	 * Context overflow errors are NOT retryable (handled by compaction instead).
	 */
	private _isRetryableError(message: AssistantMessage): boolean {
		// Context overflow is handled by compaction, not retry.
		if (isContextOverflow(message, this.model?.contextWindow ?? 0)) return false;
		return isRetryableAssistantError(message);
	}

	/**
	 * Retry policy + callbacks shared by compaction and branch-summary summarization calls.
	 * Uses the same `settings.retry` budget/backoff as agent-turn retries so a single transient
	 * stream drop no longer fails the whole operation. `source` carries the context
	 * the TUI needs to render the retry and recreate the underlying indicator.
	 */
	private _summarizationRetryCallbacks(
		source: { source: "branchSummary" } | { source: "compaction"; reason: "manual" | "threshold" | "overflow" },
		telemetryContext: TelemetryContext = this.agent.telemetryContext,
	): RetryCallbacks {
		return {
			onRetryScheduled: (attempt, maxAttempts, delayMs, errorMessage) => {
				void startCodingAgentSpan(
					telemetryContext,
					"diffex.coding_agent.retry",
					{
						"diffex.session.id": this.sessionId,
						"diffex.retry.kind": source.source === "branchSummary" ? "branch_summary" : "compaction",
						"diffex.retry.attempt": attempt,
						"diffex.retry.max_attempts": maxAttempts,
						"diffex.retry.delay_ms": delayMs,
					},
					(span) => {
						span.setAttributes({ "diffex.retry.outcome": "scheduled" });
					},
				);
				this._emit({
					type: "summarization_retry_scheduled",
					attempt,
					maxAttempts,
					delayMs,
					errorMessage,
				});
			},
			onRetryAttemptStart: () => {
				this._emit({
					type: "summarization_retry_attempt_start",
					...source,
				});
			},
			onRetryFinished: () => {
				this._emit({ type: "summarization_retry_finished" });
			},
		};
	}

	/**
	 * Prepare a retryable error for continuation with exponential backoff.
	 * @returns true if the caller should continue the agent, false otherwise
	 */
	private async _prepareRetry(message: AssistantMessage): Promise<boolean> {
		const settings = this.settingsManager.getRetrySettings();
		if (!settings.enabled) {
			return false;
		}

		this._retryAttempt++;

		if (this._retryAttempt > settings.maxRetries) {
			// Preserve the completed attempt count so post-run handling can emit the final failure.
			this._retryAttempt--;
			return false;
		}

		const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);

		this._emit({
			type: "auto_retry_start",
			attempt: this._retryAttempt,
			maxAttempts: settings.maxRetries,
			delayMs,
			errorMessage: message.errorMessage || "Unknown error",
		});

		// Remove error message from agent state (keep in session for history)
		const messages = this.agent.state.messages;
		if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
			this.agent.state.messages = messages.slice(0, -1);
		}

		// Wait with exponential backoff (abortable)
		this._retryAbortController = new AbortController();
		try {
			const resumed = await startCodingAgentSpan(
				this.agent.telemetryContext,
				"diffex.coding_agent.retry",
				{
					"diffex.session.id": this.sessionId,
					"diffex.retry.kind": "provider",
					"diffex.retry.attempt": this._retryAttempt,
					"diffex.retry.max_attempts": settings.maxRetries,
					"diffex.retry.delay_ms": delayMs,
				},
				async (span) => {
					try {
						await sleep(delayMs, this._retryAbortController?.signal);
						span.setAttributes({ "diffex.retry.outcome": "resumed" });
						return true;
					} catch {
						span.setAttributes({ "diffex.retry.outcome": "cancelled" });
						span.setStatus({ status: "error" });
						return false;
					}
				},
			);
			if (!resumed) {
				// Aborted during sleep - emit end event so UI can clean up
				const attempt = this._retryAttempt;
				this._retryAttempt = 0;
				this._emit({
					type: "auto_retry_end",
					success: false,
					attempt,
					finalError: "Retry cancelled",
				});
				return false;
			}
		} finally {
			this._retryAbortController = undefined;
		}

		return true;
	}

	/**
	 * Cancel in-progress retry.
	 */
	abortRetry(): void {
		this._retryAbortController?.abort();
	}

	/** Whether auto-retry is currently in progress */
	get isRetrying(): boolean {
		return this._retryAbortController !== undefined;
	}

	/** Whether auto-retry is enabled */
	get autoRetryEnabled(): boolean {
		return this.settingsManager.getRetryEnabled();
	}

	/**
	 * Toggle auto-retry setting.
	 */
	setAutoRetryEnabled(enabled: boolean): void {
		this.settingsManager.setRetryEnabled(enabled);
	}

	// =========================================================================
	// Bash Execution
	// =========================================================================

	/**
	 * Execute a bash command.
	 * Adds result to agent context and session.
	 * @param command The bash command to execute
	 * @param onChunk Optional streaming callback for output
	 * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
	 * @param options.id Optional identifier included in bash execution update events
	 * @param options.operations Custom BashOperations for remote execution
	 */
	executeBash(
		command: string,
		onChunk?: (chunk: string) => void,
		options?: { excludeFromContext?: boolean; id?: string; operations?: BashOperations },
	): Promise<BashResult> {
		const operation = this._runOwnedOperation(() =>
			this._traceOperation("bash", () =>
				startCodingAgentSpan(
					this.agent.telemetryContext,
					"diffex.coding_agent.terminal",
					{ "diffex.session.id": this.sessionId },
					async (span) => {
						const result = await this._executeBash(command, onChunk, options);
						const outcome = result.cancelled ? "cancelled" : result.exitCode === 0 ? "completed" : "failed";
						span.setAttributes({
							"diffex.terminal.exit_code": result.exitCode,
							"diffex.terminal.outcome": outcome,
						});
						if (outcome !== "completed") span.setStatus({ status: "error" });
						return result;
					},
				),
			),
		);
		this._bashOperations.add(operation);
		void operation.then(
			() => this._bashOperations.delete(operation),
			() => this._bashOperations.delete(operation),
		);
		return operation;
	}

	private async _executeBash(
		command: string,
		onChunk?: (chunk: string) => void,
		options?: { excludeFromContext?: boolean; id?: string; operations?: BashOperations },
	): Promise<BashResult> {
		const abortController = new AbortController();
		this._bashAbortControllers.add(abortController);

		// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
		const prefix = this.settingsManager.getShellCommandPrefix();
		const shellPath = this.settingsManager.getShellPath();
		const resolvedCommand = prefix ? `${prefix}\n${command}` : command;

		try {
			const result = await executeBashWithOperations(
				resolvedCommand,
				this.sessionManager.getCwd(),
				options?.operations ?? createLocalBashOperations({ shellPath, owner: this._shellProcesses }),
				{
					onChunk: (delta) => {
						onChunk?.(delta);
						this._emit({ type: "bash_execution_update", id: options?.id, delta });
					},
					signal: abortController.signal,
				},
			);

			this.recordBashResult(command, result, options);
			return result;
		} finally {
			this._bashAbortControllers.delete(abortController);
		}
	}

	/**
	 * Record a bash execution result in session history.
	 * Used by executeBash and by extensions that handle bash execution themselves.
	 */
	recordBashResult(command: string, result: BashResult, options?: { excludeFromContext?: boolean }): void {
		const bashMessage: BashExecutionMessage = {
			role: "bashExecution",
			command,
			output: result.output,
			exitCode: result.exitCode,
			cancelled: result.cancelled,
			truncated: result.truncated,
			fullOutputPath: result.fullOutputPath,
			timestamp: Date.now(),
			excludeFromContext: options?.excludeFromContext,
		};

		// If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering
		if (this.isStreaming) {
			// Queue for later - will be flushed on agent_end
			this._pendingBashMessages.push(bashMessage);
		} else {
			// Add to agent state immediately
			this.agent.state.messages.push(bashMessage);

			// Save to session
			this.sessionManager.appendMessage(bashMessage);
		}
	}

	/**
	 * Cancel running bash command.
	 */
	abortBash(): void {
		for (const abortController of [...this._bashAbortControllers]) {
			abortController.abort();
		}
	}

	/** Whether a bash command is currently running */
	get isBashRunning(): boolean {
		return this._bashAbortControllers.size > 0;
	}

	/** Whether there are pending bash messages waiting to be flushed */
	get hasPendingBashMessages(): boolean {
		return this._pendingBashMessages.length > 0;
	}

	/**
	 * Flush pending bash messages to agent state and session.
	 * Called after agent turn completes to maintain proper message ordering.
	 */
	private _flushPendingBashMessages(): void {
		if (this._pendingBashMessages.length === 0) return;

		for (const bashMessage of this._pendingBashMessages) {
			// Add to agent state
			this.agent.state.messages.push(bashMessage);

			// Save to session
			this.sessionManager.appendMessage(bashMessage);
		}

		this._pendingBashMessages = [];
	}

	// =========================================================================
	// Session Management
	// =========================================================================

	/**
	 * Set a display name for the current session.
	 */
	setSessionName(name: string): void {
		this.sessionManager.appendSessionInfo(name);
		const event = { type: "session_info_changed", name: this.sessionManager.getSessionName() } as const;
		this._emit(event);
		void this._extensionRunner.emit(event);
	}

	// =========================================================================
	// Tree Navigation
	// =========================================================================

	/**
	 * Navigate to a different node in the session tree.
	 * Unlike fork() which creates a new session file, this stays in the same file.
	 *
	 * @param targetId The entry ID to navigate to
	 * @param options.summarize Whether user wants to summarize abandoned branch
	 * @param options.customInstructions Custom instructions for summarizer
	 * @param options.replaceInstructions If true, customInstructions replaces the default prompt
	 * @param options.label Label to attach to the branch summary entry
	 * @returns Result with editorText (if user message) and cancelled status
	 */
	navigateTree(
		targetId: string,
		options: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string } = {},
	): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }> {
		return this._runOwnedOperation(() =>
			this._traceOperation("navigation", (telemetryContext) =>
				this._navigateTree(targetId, options, telemetryContext),
			),
		);
	}

	private async _navigateTree(
		targetId: string,
		options: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
		telemetryContext: TelemetryContext,
	): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }> {
		if (this.isStreaming) {
			throw new Error("Wait for the current response to finish before navigating the session tree.");
		}

		const oldLeafId = this.sessionManager.getLeafId();

		// No-op if already at target
		if (targetId === oldLeafId) {
			return { cancelled: false };
		}

		// Model required for summarization
		if (options.summarize && !this.model) {
			throw new Error("No model available for summarization");
		}

		const targetEntry = this.sessionManager.getEntry(targetId);
		if (!targetEntry) {
			throw new Error(`Entry ${targetId} not found`);
		}

		// Collect entries to summarize (from old leaf to common ancestor)
		const { entries: entriesToSummarize, commonAncestorId } = collectEntriesForBranchSummary(
			this.sessionManager,
			oldLeafId,
			targetId,
		);

		// Prepare event data - mutable so extensions can override
		let customInstructions = options.customInstructions;
		let replaceInstructions = options.replaceInstructions;
		let label = options.label;

		const preparation: TreePreparation = {
			targetId,
			oldLeafId,
			commonAncestorId,
			entriesToSummarize,
			userWantsSummary: options.summarize ?? false,
			customInstructions,
			replaceInstructions,
			label,
		};

		// Set up abort controller for summarization
		this._branchSummaryAbortController = new AbortController();

		try {
			let extensionSummary: { summary: string; details?: unknown; usage?: Usage } | undefined;
			let fromExtension = false;

			// Emit session_before_tree event
			if (this._extensionRunner.hasHandlers("session_before_tree")) {
				const result = (await this._extensionRunner.emit({
					type: "session_before_tree",
					preparation,
					signal: this._branchSummaryAbortController.signal,
				})) as SessionBeforeTreeResult | undefined;

				if (result?.cancel) {
					return { cancelled: true };
				}

				if (result?.summary && options.summarize) {
					extensionSummary = result.summary;
					fromExtension = true;
				}

				// Allow extensions to override instructions and label
				if (result?.customInstructions !== undefined) {
					customInstructions = result.customInstructions;
				}
				if (result?.replaceInstructions !== undefined) {
					replaceInstructions = result.replaceInstructions;
				}
				if (result?.label !== undefined) {
					label = result.label;
				}
			}

			// Run default summarizer if needed
			let summaryText: string | undefined;
			let summaryDetails: unknown;
			let summaryUsage: Usage | undefined;
			if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
				const model = this.model!;
				const { model: requestModel, apiKey, headers, env } = await this._getSummarizationRequestAuth(model);
				const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
				const result = await generateBranchSummary(entriesToSummarize, {
					model: requestModel,
					apiKey,
					headers,
					env,
					signal: this._branchSummaryAbortController.signal,
					customInstructions,
					replaceInstructions,
					reserveTokens: branchSummarySettings.reserveTokens,
					streamFn: this.agent.streamFunction,
					retry: this.settingsManager.getRetrySettings(),
					callbacks: this._summarizationRetryCallbacks({ source: "branchSummary" }, telemetryContext),
					telemetryContext,
				});
				if (result.aborted) {
					return { cancelled: true, aborted: true };
				}
				if (result.error) {
					throw new Error(result.error);
				}
				summaryText = result.summary;
				summaryUsage = result.usage;
				summaryDetails = {
					readFiles: result.readFiles || [],
					modifiedFiles: result.modifiedFiles || [],
				};
			} else if (extensionSummary) {
				summaryText = extensionSummary.summary;
				summaryDetails = extensionSummary.details;
				summaryUsage = extensionSummary.usage;
			}

			// Determine the new leaf position based on target type
			let newLeafId: string | null;
			let editorText: string | undefined;

			if (targetEntry.type === "message" && targetEntry.message.role === "user") {
				// User message: leaf = parent (null if root), text goes to editor
				newLeafId = targetEntry.parentId;
				editorText = contentText(targetEntry.message.content, "");
			} else if (targetEntry.type === "custom_message") {
				// Custom message: leaf = parent (null if root), text goes to editor
				newLeafId = targetEntry.parentId;
				editorText = contentText(targetEntry.content, "");
			} else {
				// Non-user message: leaf = selected node
				newLeafId = targetId;
			}

			// Switch leaf (with or without summary)
			// Summary is attached at the navigation target position (newLeafId), not the old branch
			let summaryEntry: BranchSummaryEntry | undefined;
			const mutateLeaf = (): void => {
				if (summaryText) {
					const summary = `${summaryText}\n\nThe plan below is authoritative for the selected conversation branch. Plan references in the exploration summary above are historical.\n${formatCurrentPlanSnapshot(this.sessionManager, newLeafId)}`;
					const summaryId = this.sessionManager.branchWithSummary(
						newLeafId,
						summary,
						summaryDetails,
						fromExtension,
						summaryUsage,
					);
					summaryEntry = this.sessionManager.getEntry(summaryId) as BranchSummaryEntry;
					if (label) this.sessionManager.appendLabelChange(summaryId, label);
				} else if (newLeafId === null) {
					this.sessionManager.resetLeaf();
				} else {
					this.sessionManager.branch(newLeafId);
				}

				if (label && !summaryText) this.sessionManager.appendLabelChange(targetId, label);
			};

			try {
				if (this._subagentController) await this._subagentController.reconcileBranch(mutateLeaf);
				else mutateLeaf();
			} catch (error) {
				if (oldLeafId === null) this.sessionManager.resetLeaf();
				else this.sessionManager.branch(oldLeafId);
				throw error;
			}

			// Update agent state
			this._planHandoffGeneration++;
			const sessionContext = this.sessionManager.buildSessionContext();
			this.agent.state.messages = sessionContext.messages;
			this._filterPendingIdleSubagentEscalationsToSelectedBranch();

			// Emit session_tree event
			await this._extensionRunner.emit({
				type: "session_tree",
				newLeafId: this.sessionManager.getLeafId(),
				oldLeafId,
				summaryEntry,
				fromExtension: summaryText ? fromExtension : undefined,
			});

			// Emit to custom tools

			return { editorText, cancelled: false, summaryEntry };
		} finally {
			this._branchSummaryAbortController = undefined;
		}
	}

	/**
	 * Get all user messages from session for fork selector.
	 */
	getUserMessagesForForking(): Array<{ entryId: string; text: string }> {
		const entries = this.sessionManager.getEntries();
		const result: Array<{ entryId: string; text: string }> = [];

		for (const entry of entries) {
			if (entry.type !== "message") continue;
			if (entry.message.role !== "user") continue;

			const text = contentText(entry.message.content, "");
			if (text) {
				result.push({ entryId: entry.id, text });
			}
		}

		return result;
	}

	/**
	 * Get session statistics. Aggregates over ALL session entries (including
	 * history that was compacted away), so token/cost totals reflect what was
	 * actually billed across the session.
	 */
	getSessionStats(): SessionStats {
		let userMessages = 0;
		let assistantMessages = 0;
		let toolResults = 0;
		let totalMessages = 0;
		let toolCalls = 0;
		const usageTotals = createUsageTotals();

		for (const entry of this.sessionManager.getEntries()) {
			if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
				addUsageToTotals(usageTotals, entry.usage);
			}
			if (entry.type !== "message") continue;
			totalMessages++;
			const message = entry.message;
			if (message.role === "user") {
				userMessages++;
			} else if (message.role === "toolResult") {
				toolResults++;
				if (message.usage) {
					addUsageToTotals(usageTotals, message.usage);
				}
			} else if (message.role === "assistant") {
				assistantMessages++;
				const assistantMsg = message as AssistantMessage;
				if (Array.isArray(assistantMsg.content)) {
					toolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
				}
				addUsageToTotals(usageTotals, assistantMsg.usage);
			}
		}

		return {
			sessionFile: this.sessionFile,
			sessionId: this.sessionId,
			userMessages,
			assistantMessages,
			toolCalls,
			toolResults,
			totalMessages,
			tokens: {
				input: usageTotals.input,
				output: usageTotals.output,
				cacheRead: usageTotals.cacheRead,
				cacheWrite: usageTotals.cacheWrite,
				total: usageTotals.input + usageTotals.output + usageTotals.cacheRead + usageTotals.cacheWrite,
			},
			cost: usageTotals.cost,
			contextUsage: this.getContextUsage(),
		};
	}

	getContextUsage(): ContextUsage | undefined {
		const model = this.model;
		if (!model) return undefined;

		const contextWindow = model.contextWindow ?? 0;
		if (contextWindow <= 0) return undefined;

		// After compaction, the last assistant usage reflects pre-compaction context size.
		// We can only trust usage from an assistant that responded after the latest compaction.
		// If no such assistant exists, context token count is unknown until the next LLM response.
		const branchEntries = this.sessionManager.getBranch();
		const latestCompaction = getLatestCompactionEntry(branchEntries);

		if (latestCompaction) {
			// Check if there's a valid assistant usage after the compaction boundary
			const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
			let hasPostCompactionUsage = false;
			for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
				const entry = branchEntries[i];
				if (entry.type === "message" && entry.message.role === "assistant") {
					const assistant = entry.message;
					if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
						const contextTokens = calculateContextTokens(assistant.usage);
						if (contextTokens > 0) {
							hasPostCompactionUsage = true;
							break;
						}
					}
				}
			}

			if (!hasPostCompactionUsage) {
				return { tokens: null, contextWindow, percent: null };
			}
		}

		const estimate = estimateContextTokens(this.messages);
		const percent = (estimate.tokens / contextWindow) * 100;

		return {
			tokens: estimate.tokens,
			contextWindow,
			percent,
		};
	}

	/**
	 * Export session to HTML.
	 * @param outputPath Optional output path (defaults to session directory)
	 * @returns Path to exported file
	 */
	async exportToHtml(outputPath?: string): Promise<string> {
		return this._traceOperation("export", () => this._exportToHtml(outputPath));
	}

	private async _exportToHtml(outputPath?: string): Promise<string> {
		const configuredThemeName = this.settingsManager.getTheme();
		const themeName = configuredThemeName && getThemeByName(configuredThemeName) ? configuredThemeName : undefined;

		// Create tool renderer if we have an extension runner (for custom tool HTML rendering)
		const toolRenderer: ToolHtmlRenderer = createToolHtmlRenderer({
			getToolDefinition: (name) => this.getToolDefinition(name),
			theme,
			cwd: this.sessionManager.getCwd(),
		});

		const filePath = await exportSessionToHtml(this.sessionManager, this.state, {
			outputPath,
			themeName,
			toolRenderer,
		});
		this._recordArtifact("html", filePath);
		return filePath;
	}

	private _recordArtifact(kind: "html" | "jsonl", filePath: string): void {
		void startCodingAgentSpan(
			this.agent.telemetryContext,
			"diffex.coding_agent.artifact",
			{
				"diffex.session.id": this.sessionId,
				"diffex.artifact.kind": kind,
			},
			(span) => {
				span.setAttributes({
					"diffex.artifact.path": filePath,
					"diffex.artifact.outcome": "written",
				});
			},
		);
	}

	/**
	 * Export the current session branch to a JSONL file.
	 * Writes the session header followed by all entries on the current branch path.
	 * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
	 * @returns The resolved output file path.
	 */
	exportToJsonl(outputPath?: string): string {
		const filePath = resolvePath(
			outputPath ?? `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`,
			process.cwd(),
		);
		const dir = dirname(filePath);
		if (!existsSync(dir)) {
			mkdirSync(dir, { recursive: true });
		}

		const header: SessionHeader = {
			type: "session",
			version: CURRENT_SESSION_VERSION,
			id: this.sessionManager.getSessionId(),
			timestamp: new Date().toISOString(),
			cwd: this.sessionManager.getCwd(),
		};

		const branchEntries = this.sessionManager.getBranch();
		const lines = [JSON.stringify(header)];

		// Re-chain parentIds to form a linear sequence
		let prevId: string | null = null;
		for (const entry of branchEntries) {
			const linear = { ...entry, parentId: prevId };
			lines.push(JSON.stringify(linear));
			prevId = entry.id;
		}

		writeFileSync(filePath, `${lines.join("\n")}\n`);
		this._recordArtifact("jsonl", filePath);
		return filePath;
	}

	// =========================================================================
	// Utilities
	// =========================================================================

	/**
	 * Get text content of last assistant message.
	 * Useful for /copy command.
	 * @returns Text content, or undefined if no assistant message exists
	 */
	getLastAssistantText(): string | undefined {
		const lastAssistant = this.messages
			.slice()
			.reverse()
			.find((m) => {
				if (m.role !== "assistant") return false;
				const msg = m as AssistantMessage;
				// Skip aborted messages with no content
				if (msg.stopReason === "aborted" && msg.content.length === 0) return false;
				return true;
			});

		if (!lastAssistant) return undefined;

		let text = "";
		for (const content of (lastAssistant as AssistantMessage).content) {
			if (content.type === "text") {
				text += content.text;
			}
		}

		return text.trim() || undefined;
	}

	// =========================================================================
	// Extension System
	// =========================================================================

	createReplacedSessionContext(): ReplacedSessionContext {
		const context = Object.defineProperties(
			{},
			Object.getOwnPropertyDescriptors(this._extensionRunner.createCommandContext()),
		) as ReplacedSessionContext;
		context.sendMessage = (message, options) => this.sendCustomMessage(message, options);
		context.sendUserMessage = (content, options) => this.sendUserMessage(content, options);
		return context;
	}

	/**
	 * Check if extensions have handlers for a specific event type.
	 */
	hasExtensionHandlers(eventType: string): boolean {
		return this._extensionRunner.hasHandlers(eventType);
	}

	/**
	 * Get the extension runner (for setting UI context and error handlers).
	 */
	get extensionRunner(): ExtensionRunner {
		return this._extensionRunner;
	}
}