Task.ts

import * as path from "path"
import os from "os"
import crypto from "crypto"
import { v7 as uuidv7 } from "uuid"
import EventEmitter from "events"

import { AskIgnoredError } from "./AskIgnoredError.js"
import { startApiRequestTimer, openedApiReqInfo, endedApiReqInfo, type StreamPhaseMarks } from "./api-req-timing.js"

import { Anthropic } from "@anthropic-ai/sdk"
import OpenAI from "openai"
import debounce from "lodash.debounce"
import delay from "delay"
import pWaitFor from "p-wait-for"
import { serializeError } from "serialize-error"
import { Package } from "../shared/package.js"
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import { formatToolInvocation } from "../tools/helpers/toolResultFormatting.js"

import {
	type TaskLike,
	type TaskMetadata,
	type Envelope,
	MAILBOX_WAKE_TURN_TEXT,
	type TaskEvents,
	type ProviderSettings,
	type TokenUsage,
	type ToolUsage,
	type ToolName,
	type ContextCondense,
	type ContextTruncation,
	type ShoferMessage,
	type ShoferSay,
	type ShoferAsk,
	type PluginMarkerPayload,
	type ToolProgressStatus,
	type HistoryItem,
	type CreateTaskOptions,
	type TaskState,
	type ModelInfo,
	type ShoferApiReqCancelReason,
	type ShoferApiReqInfo,
	type ApiReqError,
	type ToolSpan,
	type ApiRequestFinishedPayload,
	type AskResolvedInfo,
	type TraceContext,
	type TaskInteractionPayload,
	type TaskHandle,
	type CostLimit,
	type McpToolCallResponse,
	ShoferEventName,
	// eslint-disable-next-line @typescript-eslint/no-unused-vars
	TelemetryEventName,
	TaskStatus,
	TodoItem,
	getApiProtocol,
	getModelId,
	isRetiredProvider,
	isIdleAsk,
	isInteractiveAsk,
	isResumableAsk,
	QueuedMessage,
	DEFAULT_CONSECUTIVE_MISTAKE_LIMIT,
	ConsecutiveMistakeError,
	MAX_MCP_TOOLS_THRESHOLD,
	countEnabledMcpTools,
} from "@shofer/types"
import { TelemetryService } from "@shofer/telemetry"

// api
import { ApiHandler, ApiHandlerCreateMessageMetadata } from "../api/api-handler-types.js"
import { buildApiHandler } from "../api/index.js"
import { ApiStream, GroundingSource } from "../api/transform/stream.js"
import { maybeRemoveImageBlocks } from "../api/transform/image-cleaning.js"

// shared
import { findLastIndex } from "@shofer/types"
import { combineApiRequests } from "@shofer/types"
import { combineCommandSequences } from "@shofer/types"
import { t } from "../i18n/index.js"
import { getApiMetrics, hasTokenUsageChanged, hasToolUsageChanged } from "@shofer/types"
import { ShoferAskResponse } from "@shofer/types"
import { defaultModeSlug, getModeBySlug, resolveModeConfig } from "@shofer/types"
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import { DiffStrategy, type ToolUse, type McpToolUse, type ToolParamName, toolParamNames } from "@shofer/types"
import { getModelMaxOutputTokens } from "@shofer/types"
import type { BackgroundTaskStatus } from "@shofer/types"

// services
import { McpHub } from "../services/mcp/McpHub.js"
import { getMcpHubFactory } from "../services/mcp/mcp-hub-factory.js"

// integrations
import type { DiffView } from "@shofer/types"
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import { findToolName } from "./findToolName.js"
import { ShoferTerminalProcess } from "@shofer/types"
import { TerminalRegistry } from "../terminal/TerminalRegistry.js"
import { OutputInterceptor } from "../terminal/OutputInterceptor.js"

// utils
import { calculateApiCostAnthropic, calculateApiCostOpenAI } from "@shofer/types"
import { getWorkspacePath } from "../path/path.js"
import { sanitizeToolUseId } from "../utils/tool-id.js"
import { humanMessageBlock } from "../utils/user-message.js"
import { getTaskDirectoryPath } from "../utils/storage.js"
import { BlobStore, DEFAULT_BLOB_CAP_BYTES } from "../blob-store/BlobStore.js"
import {
	MAX_EXPONENTIAL_BACKOFF_SECONDS,
	DEFAULT_USAGE_COLLECTION_TIMEOUT_MS,
	FORCED_CONTEXT_REDUCTION_PERCENT,
	MAX_CONTEXT_WINDOW_RETRIES,
	MCP_READY_DEADLINE_MS,
	TASK_TOKEN_USAGE_EMIT_INTERVAL_MS,
	TASK_SAVE_DEBOUNCE_INTERVAL_MS,
	TASK_PARTIAL_APPEND_THROTTLE_MS,
} from "../constants.js"

// prompts
import { formatResponse } from "../prompts/responses.js"
import { SYSTEM_PROMPT } from "../prompts/system.js"
import { buildNativeToolsArrayWithRestrictions } from "./build-tools.js"
import { emitTaskCompleted } from "./emit-task-completed.js"
import { MAX_SUBTASK_RESULT_LENGTH } from "../tools/NewTaskTool.js"

// plugin lifecycle hooks (design §6.9)
import { pluginRegistry } from "../plugins/plugin-registry.js"

// core modules
import { ToolRepetitionDetector } from "../tools/ToolRepetitionDetector.js"
import { restoreTodoListForTask } from "../tools/UpdateTodoListTool.js"
import { FileContextTracker } from "../context-tracking/FileContextTracker.js"
import { ShoferIgnoreController } from "../ignore/ShoferIgnoreController.js"
import { ShoferProtectedController } from "../protect/ShoferProtectedController.js"
import { type AssistantMessageContent, presentAssistantMessage } from "../assistant-message/index.js"
import { NativeToolCallParser } from "../assistant-message/NativeToolCallParser.js"
import { manageContext, willManageContext } from "../context-management/index.js"
import { aggregateTaskCostsRecursive } from "../webview/aggregateTaskCosts.js"
import { type TaskProviderLike } from "../task-provider/index.js"
import { MultiSearchReplaceDiffStrategy } from "../diff/strategies/multi-search-replace.js"
import { type ApiMessage } from "../task-persistence/apiMessages.js"
import type { TaskPersistencePort } from "../task-persistence/PersistencePort.js"
import { resolveTaskPersistence } from "../task-persistence/backend.js"
import { taskMetadata } from "../task-persistence/taskMetadata.js"
import { getHost } from "@shofer/types"
import { getEnvironmentDetails } from "../environment/getEnvironmentDetails.js"
import { checkContextWindowExceededError } from "../context/context-management/context-error-handling.js"
import { isNonRetryableApiError } from "../api/providers/utils/retryable-error.js"
import { ApiRetryBudgetExceededError, resolveMaxConsecutiveApiFailures } from "./api-retry-budget.js"
import { processUserContentMentions } from "../mentions/processUserContentMentions.js"
import { getMessagesSinceLastSummary, summarizeConversation, getEffectiveApiHistory } from "../condense/index.js"
import { MessageQueueService } from "../message-queue/MessageQueueService.js"
import { Mailbox } from "../mailbox/Mailbox.js"
import { AutoApprovalHandler } from "../auto-approval/AutoApprovalHandler.js"
import { checkAutoApproval, type CheckAutoApprovalResult } from "../auto-approval/index.js"
import { MessageManager } from "../message-manager/index.js"
import { validateAndFixToolResultIds } from "./validateToolResultIds.js"
import { mergeConsecutiveApiMessages } from "./mergeConsecutiveApiMessages.js"
import { taskLog } from "../logging/subsystems.js"
import { runWithLogTaskContext } from "../logging/logContext.js"
import { time } from "../utils/perf.js"
import {
	recordLlmDuration,
	incLlmCalls,
	incLlmErrors,
	incLlmCost,
	incLlmTokens,
	classifyLlmError,
} from "../metrics/registry.js"

// Tunable retry / timeout / context-recovery knobs are centralised in
// `../constants.js`. See MAX_EXPONENTIAL_BACKOFF_SECONDS,
// DEFAULT_USAGE_COLLECTION_TIMEOUT_MS, FORCED_CONTEXT_REDUCTION_PERCENT,
// MAX_CONTEXT_WINDOW_RETRIES, MCP_READY_DEADLINE_MS, and the TASK_* throttle
// intervals there.

export interface TaskOptions extends CreateTaskOptions {
	provider: TaskProviderLike<Task>
	apiConfiguration: ProviderSettings
	consecutiveMistakeLimit?: number
	task?: string
	images?: string[]
	historyItem?: HistoryItem
	experiments?: Record<string, boolean>
	startTask?: boolean
	rootTask?: Task
	parentTask?: Task
	taskNumber?: number
	onCreated?: (task: Task) => void
	initialTodos?: TodoItem[]
	workspacePath?: string
	/**
	 * Working directory for this task. When set (e.g., for embedded worktree
	 * tasks), this overrides the default workspacePath as the task's CWD for
	 * tool invocations, file path resolution, and git operations.
	 *
	 * If not set, cwd defaults to workspacePath.
	 */
	cwd?: string
	/** Initial execution state for the task's history item (e.g., for child tasks) */
	initialState?: TaskState
}

/**
 * Handle for an in-flight async MCP tool call, stored in {@link Task.mcpAsyncCalls}.
 * Mirrors {@link TaskHandle} for background children.
 */
export interface McpAsyncCallHandle {
	callId: string
	serverName: string
	toolName: string
	status: "running" | "completed" | "error" | "cancelled"
	promise: Promise<McpToolCallResponse | undefined>
	abortController: AbortController
	result?: McpToolCallResponse
	error?: string
	createdAt: number
}

export class Task extends EventEmitter<TaskEvents> implements TaskLike {
	readonly taskId: string
	readonly rootTaskId?: string
	readonly parentTaskId?: string
	childTaskId?: string
	pendingNewTaskToolCallId?: string

	// NEW: Track background children
	backgroundChildren: Map<string, TaskHandle> = new Map()

	/**
	 * Least-privilege peer scope restriction. Peer tools only allow
	 * communication with task IDs present in this set. The baseline
	 * always includes the parent (if any) and children this task spawns
	 * (dynamically added). When undefined, no peer communication is
	 * allowed at all — every peer-tool access is denied.
	 *
	 * Set explicitly by {@link NewTaskTool} at spawn time (baseline: parent
	 * only) and extended as the task spawns children.
	 */
	knownPeers?: Set<string>

	/**
	 * Set while this child is parked on a question it FORWARDED to its parent.
	 *
	 * A child's `ask_followup_question` is dual-channel: the question is raised
	 * as an ordinary `followup` ask in the child's own chat AND delivered to the
	 * parent's mailbox as a `request` envelope. This field is the correlation
	 * between the two — `envelopeId` names the request in the parent's box,
	 * `question` is the text — and it exists because three things need it and
	 * none of them can derive it:
	 *
	 * - the parent's `reply` must unpark THIS ask ({@link answerForwardedQuestion});
	 * - `check_task_status` reports that the child is waiting on an answer;
	 * - `TaskManager` suppresses the desktop `needs_input` notification, because
	 *   the question has a live agent audience and is not (only) the human's to
	 *   answer.
	 *
	 * The blocking itself is `task.ask("followup", …)`, exactly as for a
	 * user-facing question, so either channel resolves it through
	 * `handleWebviewAskResponse` and the first answer wins.
	 */
	private _forwardedQuestion?: { envelopeId: string; question: string }

	/**
	 * In-flight async MCP tool calls (mirrors `backgroundChildren` for MCP calls).
	 * Each entry tracks a fire-and-forget `McpHub.callTool()` promise plus an
	 * AbortController. Cleaned up inline in {@link abortTask}.
	 */
	mcpAsyncCalls: Map<string, McpAsyncCallHandle> = new Map()

	/**
	 * Per-root-task USD budget cap. Stored only on root tasks; subtasks
	 * resolve the limit by walking up the parentTask chain via
	 * `resolveCostLimit()`. Unset or maxUsd <= 0 disables enforcement.
	 */
	costLimit?: CostLimit

	/**
	 * Cached aggregated cost for the current API request, keyed by the
	 * `shoferMessages` index of the request. Avoids re-scanning history
	 * on every chunk of a single streaming response.
	 */
	private _costLimitCheckCache?: { spent: number; requestIndex: number }

	/**
	 * Snapshot of the aggregated cost across the root task's history
	 * captured at the start of the current API request, BEFORE this
	 * request's own usage is added. Used by the in-stream check
	 * (`checkInFlightCostLimit`) to compute live spend as
	 * `_priorAggregateUsd + thisRequestCostUsd` on every `usage` chunk
	 * without re-scanning history each time. Reset per request boundary.
	 */
	private _priorAggregateUsd?: number

	/**
	 * Per-request guard so the in-stream cost check fires its
	 * abort/pause/kill action AT MOST ONCE for the current API call.
	 * Without this, multiple `usage` chunks crossing the cap would each
	 * try to enforce — re-aborting an already-aborting task or stacking
	 * pause prompts. Reset per request boundary alongside the snapshot.
	 */
	private _costLimitEnforcementFiredForRequest = false

	/**
	 * Set to `true` when the user has chosen to continue past the cost
	 * cap for the remainder of this task. Reset only by abort/dispose.
	 * Implements the "Continue without limit" branch of the pause dialog.
	 */
	private _costLimitBypassed = false

	// Helper to check if child is alive
	isBackgroundChildAlive(childId: string): boolean {
		if (
			this.providerRef.deref() &&
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			typeof (this.providerRef.deref() as any).getManagedTaskInstance === "function"
		) {
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			return (this.providerRef.deref() as any).getManagedTaskInstance(childId) !== undefined
		}
		return false
	}

	// Cleanup dead children on parent resume/load
	async cleanupBackgroundChildren(): Promise<void> {
		for (const [childId, handle] of this.backgroundChildren) {
			if (!this.isBackgroundChildAlive(childId)) {
				try {
					// Use TaskManager.getTaskState() (in-memory, set synchronously
					// by lifecycle events) rather than the persisted HistoryItem
					// snapshot which can lag behind due to the async persistState
					// fire-and-forget write.
					const provider = this.providerRef.deref()
					if (provider) {
						// eslint-disable-next-line @typescript-eslint/no-explicit-any
						const taskState = (provider as any).taskManager?.getTaskState(childId)
						handle.status = taskState?.lifecycle === "completed" ? "completed" : "error"
					}
				} catch (_) {
					handle.status = "error"
				}
			}
		}
	}

	/**
	 * Rebuild the in-memory {@link backgroundChildren} map from persisted history
	 * after a process restart.
	 *
	 * `backgroundChildren` is a runtime-only `Map` populated by `NewTaskTool` when
	 * spawning background subtasks. It is never serialized. After a VS Code /
	 * code-server restart, a resumed parent task starts with an empty map, so
	 * `check_task_status` and `cancel_tasks` — both of which gate on
	 * `task.backgroundChildren.get(task_id)` — reject the parent's own children
	 * with "Task not found in background children or peers" even though
	 * `list_background_tasks` (which has a persisted-history fallback) still
	 * shows them. This method closes that gap by repopulating the map from the
	 * persisted `HistoryItem` rows that carry `isBackground && parentTaskId ===
	 * this.taskId`.
	 *
	 * Status resolution mirrors {@link cleanupBackgroundChildren}: the live
	 * `TaskManager.getTaskState()` wins (set synchronously by lifecycle events);
	 * otherwise the persisted `HistoryItem.taskState.lifecycle` is used. Children
	 * whose persisted lifecycle was transient (`running`, `waiting`,
	 * `waiting_input`) are mapped to `idle`-equivalent handle statuses so the
	 * tools treat them as resumable rather than terminal.
	 *
	 * Idempotent: existing live handles are preserved (a live handle always
	 * reflects more-current state than the persisted snapshot).
	 */
	async rehydrateBackgroundChildren(): Promise<void> {
		const provider = this.providerRef.deref()
		if (!provider) return

		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		const taskHistoryStore = (provider as any).taskHistoryStore as { getAll?: () => any[] } | undefined
		if (!taskHistoryStore || typeof taskHistoryStore.getAll !== "function") return

		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		let historyItems: any[]
		try {
			historyItems = taskHistoryStore.getAll() ?? []
		} catch {
			return
		}

		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		const taskManager = (provider as any).taskManager as { getTaskState?: (id: string) => any } | undefined

		for (const item of historyItems) {
			// Only persisted background children of THIS task belong in the map.
			if (!item || !item.isBackground) continue
			if (item.parentTaskId !== this.taskId) continue

			const childId: string = item.id
			// Preserve any live handle already present — it is more current.
			if (this.backgroundChildren.has(childId)) continue

			// Resolve the most authoritative status available post-restart.
			let status: BackgroundTaskStatus
			const liveState = taskManager?.getTaskState?.(childId)
			const lifecycle = liveState?.lifecycle ?? item.taskState?.lifecycle

			switch (lifecycle) {
				case "completed":
					status = "completed"
					break
				case "error":
					status = "error"
					break
				// Transient lifetimes do not survive a restart (sanitizeRestoredState
				// downgrades them to `idle`). Map them to the resumable handle status
				// so the parent can wait on / re-inspect them rather than treating
				// them as gone.
				case "running":
				case "waiting":
				case "waiting_input":
				case "idle":
				case "paused":
					status = "running"
					break
				default:
					status = "running"
			}

			this.backgroundChildren.set(childId, {
				taskId: childId,
				status,
				createdAt: item.createdAt ?? item.ts ?? Date.now(),
				parentTaskId: this.taskId,
			})
		}
	}

	readonly instanceId: string
	readonly metadata: TaskMetadata

	todoList?: TodoItem[]

	/**
	 * Per-task snapshot of the pending todo list approval. Used by
	 * UpdateTodoListTool to detect user edits made in the webview
	 * between the tool's ask and the approval response.
	 *
	 * Replaces the former module-level `approvedTodoList` global
	 * that leaked between concurrent Task instances.
	 */
	pendingTodoApproval?: TodoItem[]

	readonly rootTask: Task | undefined = undefined
	readonly parentTask: Task | undefined = undefined
	readonly taskNumber: number
	readonly workspacePath: string

	/** Outside-workspace dirs the user trusted for THIS task (+ subtasks) via the
	 *  inline "Trust path" button. In-memory only; the persistent equivalent is
	 *  allowedReadPaths/allowedWritePaths. */
	readonly trustedReadPaths: string[]
	readonly trustedWritePaths: string[]

	/**
	 * Maximum characters the parent will accept as the completion result.
	 * Set by {@link NewTaskTool} via {@link CreateTaskOptions.softResultLength} when a parent
	 * spawns a child task. The child's {@link attempt_completion} tool enforces this.
	 * If undefined, no result length constraint applies (top-level tasks).
	 */
	softResultLength?: number

	/**
	 * Soft guidance (in seconds) for how long the parent expects to wait.
	 * Set by {@link NewTaskTool} via {@link CreateTaskOptions.softTimeoutSec}.
	 * Not a hard deadline — informational only. If undefined, no time guidance applies.
	 */
	softTimeoutSec?: number

	/**
	 * When true, this task's display title was assigned by its spawning parent
	 * (via {@link NewTaskTool}'s `title` parameter / {@link CreateTaskOptions.initialTitle})
	 * and is locked: the {@link SetTaskTitleTool} refuses to overwrite it. Seeded
	 * at construction from `initialTitle` for fresh tasks, or rehydrated from
	 * {@link HistoryItem.nameLocked} on restore so the lock survives restarts.
	 */
	nameLocked = false

	/**
	 * The locked title value, persisted as `HistoryItem.name` on every metadata
	 * write while {@link nameLocked} is true. Undefined when the title is not
	 * parent-locked (the task's `name` is then owned by `set_task_title` / the
	 * auto-generated default).
	 */
	private lockedTitle?: string

	/**
	 * Per-task JSON Schema override for the `attempt_completion` tool's
	 * `result` parameter. When set, the generic `result: string` schema is
	 * replaced with a structured object schema so providers with constrained
	 * decoding enforce an output contract at decode time.
	 *
	 * contract. When undefined, the default `result: string` schema applies.
	 */
	completionSchema?: Record<string, unknown>

	/**
	 * Optional persona/role injected into this task's system prompt. Layered on
	 * top of the mode's
	 * roleDefinition for this task only; see {@link CreateTaskOptions.agentRole}.
	 */
	agentRole?: string

	/**
	 * The W3C trace context of the work this task was created on behalf of, when
	 * its creator supplied one ({@link CreateTaskOptions.trace}).
	 *
	 * Core stores it and hands it to `beforeTaskStart` observers; it never parses
	 * it and never acts on it. Keeping it on the task rather than passing it
	 * straight through is what lets a plugin registered AFTER creation still
	 * learn where the run came from.
	 */
	readonly trace?: TraceContext

	/**
	 * Per-task tool-group allow-list (a caller passes the declared
	 * `tools:` here). Intersected with the mode's groups when building the
	 * tool array; see {@link CreateTaskOptions.agentToolGroups}. A restriction
	 * only — never grants tools beyond the mode.
	 */
	agentToolGroups?: string[]

	/**
	 * Per-task overrides for system-prompt components; see
	 * {@link CreateTaskOptions.agentContext}.
	 * Each key is a boolean toggle for a specific component. Absent keys
	 * inherit the global default.
	 *
	 * Supported keys: `include_agents_md`, `include_subfolder_rules`,
	 * `include_mode_rules`, `include_user_rules`, `include_skills`,
	 * `require_todos`, `include_system_info`, `include_mcp`.
	 */
	agentContext?: Record<string, boolean>

	/**
	 * The mode associated with this task. Persisted across sessions
	 * to maintain user context when reopening tasks from history.
	 *
	 * ## Lifecycle
	 *
	 * ### For new tasks:
	 * 1. Initially `undefined` during construction
	 * 2. Asynchronously initialized from provider state via `initializeTaskMode()`
	 * 3. Falls back to `defaultModeSlug` if provider state is unavailable
	 *
	 * ### For history items:
	 * 1. Immediately set from `historyItem.mode` during construction
	 * 2. Falls back to `defaultModeSlug` if mode is not stored in history
	 *
	 * ## Important
	 * This property should NOT be accessed directly until `taskModeReady` promise resolves.
	 * Use `getTaskMode()` for async access or `taskMode` getter for sync access after initialization.
	 *
	 * @private
	 * @see {@link getTaskMode} - For safe async access
	 * @see {@link taskMode} - For sync access after initialization
	 * @see {@link waitForModeInitialization} - To ensure initialization is complete
	 */
	private _taskMode: string | undefined

	/**
	 * Promise that resolves when the task mode has been initialized.
	 * This ensures async mode initialization completes before the task is used.
	 *
	 * ## Purpose
	 * - Prevents race conditions when accessing task mode
	 * - Ensures provider state is properly loaded before mode-dependent operations
	 * - Provides a synchronization point for async initialization
	 *
	 * ## Resolution timing
	 * - For history items: Resolves immediately (sync initialization)
	 * - For new tasks: Resolves after provider state is fetched (async initialization)
	 *
	 * @private
	 * @see {@link waitForModeInitialization} - Public method to await this promise
	 */
	private taskModeReady: Promise<void>

	/**
	 * The API configuration name (provider profile) associated with this task.
	 * Persisted across sessions to maintain the provider profile when reopening tasks from history.
	 *
	 * ## Lifecycle
	 *
	 * ### For new tasks:
	 * 1. Initially `undefined` during construction
	 * 2. Asynchronously initialized from provider state via `initializeTaskApiConfigName()`
	 * 3. Falls back to "default" if provider state is unavailable
	 *
	 * ### For history items:
	 * 1. Immediately set from `historyItem.apiConfigName` during construction
	 * 2. Falls back to undefined if not stored in history (for backward compatibility)
	 *
	 * ## Important
	 * If you need a non-`undefined` provider profile (e.g., for profile-dependent operations),
	 * wait for `taskApiConfigReady` first (or use `getTaskApiConfigName()`).
	 * The sync `taskApiConfigName` getter may return `undefined` for backward compatibility.
	 *
	 * @private
	 * @see {@link getTaskApiConfigName} - For safe async access
	 * @see {@link taskApiConfigName} - For sync access after initialization
	 */
	private _taskApiConfigName: string | undefined

	/**
	 * Promise that resolves when the task API config name has been initialized.
	 * This ensures async API config name initialization completes before the task is used.
	 *
	 * ## Purpose
	 * - Prevents race conditions when accessing task API config name
	 * - Ensures provider state is properly loaded before profile-dependent operations
	 * - Provides a synchronization point for async initialization
	 *
	 * ## Resolution timing
	 * - For history items: Resolves immediately (sync initialization)
	 * - For new tasks: Resolves after provider state is fetched (async initialization)
	 *
	 * @private
	 */
	private taskApiConfigReady: Promise<void>

	providerRef: WeakRef<TaskProviderLike<Task>>
	private readonly globalStoragePath: string
	abort: boolean = false

	/**
	 * Tracks the currently running initiateTaskLoop Promise.
	 * Used by cancelAndProcessQueuedMessages to wait for the old task loop
	 * to fully exit before starting a new one, preventing race conditions
	 * that cause duplicate messages and orphaned tool_use blocks.
	 */
	private _taskLoopPromise: Promise<void> | undefined = undefined
	currentRequestAbortController?: AbortController

	/**
	 * Task-lifetime AbortController. Aborted whenever the task is cancelled
	 * (Stop button -> abortTask) or its current run is interrupted to drain
	 * queued messages (Send Now -> cancelAndProcessQueuedMessages). Long-running
	 * in-task operations (MCP tool calls, HTTP fetches initiated by tools, etc.)
	 * subscribe to `abortSignal` so they can bail immediately instead of waiting
	 * for their own per-operation timeout.
	 *
	 * For Send Now we replace the controller before restarting the loop so the
	 * fresh run does not see an already-aborted signal.
	 */
	private _taskAbortController: AbortController = new AbortController()
	public get abortSignal(): AbortSignal {
		return this._taskAbortController.signal
	}
	skipPrevResponseIdOnce: boolean = false

	// TaskStatus
	idleAsk?: ShoferMessage
	resumableAsk?: ShoferMessage
	interactiveAsk?: ShoferMessage

	didFinishAbortingStream = false
	abandoned = false
	abortReason?: ShoferApiReqCancelReason
	isInitialized = false
	isPaused: boolean = false

	/**
	 * Soft-cancel marker for the "Send Now" flow.
	 *
	 * When the user clicks Send Now while the task is mid-stream, we want to
	 * interrupt the current API request and immediately restart the loop with
	 * the queued message — WITHOUT tearing down the task. The default abort
	 * path (recursivelyMakeShoferRequests catch block) calls `abortTask()` on
	 * `this.abort === true`, which calls `dispose()`, which wipes the message
	 * queue, removes the queue listener, and releases terminals. That would
	 * silently delete the very message we are trying to send and leave the
	 * webview with an orphan UI entry that cannot be dismissed.
	 *
	 * When this flag is set, callers that would otherwise fully abort the
	 * task on `this.abort === true` should instead unwind cleanly so
	 * `cancelAndProcessQueuedMessages()` can restart the loop.
	 */
	private _softCancelForQueuedMessage = false

	// API
	apiConfiguration: ProviderSettings
	api: ApiHandler
	private static lastGlobalApiRequestTime?: number
	private autoApprovalHandler: AutoApprovalHandler

	/**
	 * Reset the global API request timestamp. This should only be used for testing.
	 * @internal
	 */
	static resetGlobalApiRequestTime(): void {
		Task.lastGlobalApiRequestTime = undefined
	}

	toolRepetitionDetector: ToolRepetitionDetector
	shoferIgnoreController?: ShoferIgnoreController
	shoferProtectedController?: ShoferProtectedController

	// ===== Task Visualization — Timeline =====

	/**
	 * Monotonic origin for all per-task timing.  Set once at construction
	 * via `performance.now()` so every span offset is relative to the
	 * same starting point regardless of when the task's history was
	 * written.
	 */
	timelineOriginMs!: number

	/**
	 * Tool spans accumulated during the current API request.  Drained
	 * into `api_req_finished.toolSpans[]` at stream end and reset for
	 * each new request.
	 */
	_pendingToolSpans: ToolSpan[] = []

	/**
	 * Offset from `timelineOriginMs` when the current API request was
	 * initiated (just before the streaming call).
	 */
	_pendingRequestStartOffset = 0

	/**
	 * TTFB for the current API request in ms, or `null` when not yet
	 * available.
	 */
	_pendingTtfbMs: number | null = null

	/**
	 * Offset (ms from request start) at which output generation began — the
	 * first non-reasoning chunk (text or tool call). The window between
	 * `_pendingTtfbMs` and this is the model's reasoning/"thinking" phase.
	 * `null` until the first non-reasoning chunk arrives.
	 */
	_pendingGenStartMs: number | null = null

	/**
	 * Reasoning intervals CLOSED so far in the current request — every
	 * reasoning run the stream terminated with a non-reasoning chunk, as
	 * `[start, end]` offsets from the request's open.
	 *
	 * `_pendingGenStartMs` above records only the FIRST such boundary, which is
	 * all the `api_req_finished` span publishes; a model that interleaves
	 * thinking with output has more, and this is where they are kept.
	 */
	_pendingReasoningIntervals: Array<[number, number]> = []

	/**
	 * Offset at which the currently-open reasoning run began, or `null` when
	 * the stream is not reasoning. A run still open at stream end is closed
	 * there by `streamPhaseFields`.
	 */
	_pendingReasoningOpenedAtMs: number | null = null

	/**
	 * True while an API request is in flight and its `api_req_finished` span has
	 * not yet been emitted. Guards `emitApiReqFinished` against double-emit and
	 * lets `abortTask` flush the final request (e.g. the attempt_completion turn,
	 * which disposes the task before the normal post-tools emit point).
	 */
	_pendingApiReqNeedsEmit = false

	/**
	 * 0-based monotonic index assigned to each API request span within
	 * this task.
	 */
	_currentRequestIndex = 0
	fileContextTracker: FileContextTracker
	terminalProcess?: ShoferTerminalProcess

	/**
	 * Backgrounded command processes — an execute_command the agent moved on from
	 * (agent timeout, or the user chose "Proceed While Running") while it is still
	 * running. The foreground `terminalProcess` reference is cleared once the tool
	 * returns, so without this map a backgrounded command could no longer be
	 * terminated by the Stop button or the per-command Kill button. Keyed by
	 * executionId; entries are removed when the command actually completes.
	 */
	backgroundTerminalProcesses = new Map<string, ShoferTerminalProcess>()

	// Editing
	diffViewProvider: DiffView
	diffStrategy?: DiffStrategy
	didEditFile: boolean = false

	// LLM Messages & Chat Messages
	apiConversationHistory: ApiMessage[] = []
	shoferMessages: ShoferMessage[] = []

	/**
	 * Promise that resolves when `shoferMessages` has been populated.
	 *
	 * For history-resume tasks, resolves after `resumeTaskFromHistory()` loads
	 * messages from disk. For new tasks, resolves after `startTask()` posts the
	 * first user message. For non-started tasks (`startTask: false`), resolves
	 * immediately.
	 *
	 * Used by `createTaskWithHistoryItem` to defer `postInitState` until
	 * messages are available, preventing the home-screen flash when switching
	 * focus to a history task before its messages have loaded.
	 */
	messagesReady: Promise<void>

	private _messagesReadyResolve!: () => void

	/**
	 * True once `shoferMessages` and `apiConversationHistory` have been loaded
	 * from disk and sanitized. Set by either `preloadShoferMessages()` (called
	 * explicitly by `createTaskWithHistoryItem` BEFORE the task is published as
	 * `getCurrentTask()`) or by `resumeTaskFromHistory()` on its own.
	 *
	 * Used by `resumeTaskFromHistory()` to skip the load+sanitize prefix when
	 * the messages were already preloaded, avoiding redundant disk I/O and
	 * guaranteeing the same array is observed by both code paths.
	 */
	private historyPreloaded: boolean = false

	/** Read-only accessor for diagnostics (see ShoferProvider home-screen-flash log). */
	public get isHistoryPreloaded(): boolean {
		return this.historyPreloaded
	}

	// Ask
	private askResponse?: ShoferAskResponse
	private askResponseText?: string
	private askResponseImages?: string[]
	public lastMessageTs?: number
	/**
	 * UUID v7 identifying the currently-outstanding ask. Set when a
	 * complete (non-partial) ask enters the pWaitFor loop; cleared when
	 * the ask is resolved, superseded, or the task is disposed. A
	 * new ask() call that generates its own askId implicitly supersedes
	 * the previous one (no separate invalidation needed).
	 *
	 * Replaces the former `lastMessageTs` timestamp for ask identity so
	 * that unrelated code paths (say(), supersedePendingAsk()) can no
	 * longer invalidate an in-flight ask by bumping a global mutable field.
	 */
	private _currentAskId?: string
	private autoApprovalTimeoutRef?: NodeJS.Timeout
	// True while ask() is actively waiting for a response from the user/webview.
	// Used by handleWebviewAskResponse() to detect stray messageResponse arrivals
	// (e.g. user typing during a tool execution window when no ask is pending) and
	// route them to the message queue instead of silently overwriting unread
	// askResponse* slots that the next ask() call would clear.
	private isAwaitingAskResponse: boolean = false

	// Experiments
	experimentsConfig?: Record<string, boolean>

	// Tool Use
	consecutiveMistakeCount: number = 0
	consecutiveMistakeLimit: number
	consecutiveMistakeCountForApplyDiff: Map<string, number> = new Map()
	consecutiveMistakeCountForEditFile: Map<string, number> = new Map()
	consecutiveNoToolUseCount: number = 0
	consecutiveNoAssistantMessagesCount: number = 0
	toolUsage: ToolUsage = {}

	// Skill tracking — maps skill name to SKILL.md absolute path
	loadedSkills: Map<string, string> = new Map()

	// H15: Per-turn system prompt cache.
	// The assembled prompt (base + subtask-constraints) is stable across
	// round-trips within a turn; peer notifications are appended fresh.
	// Cleared at turn start (initiateTaskLoop) and on context-management
	// (condenseContext / handleContextWindowExceededError).
	_cachedSystemPromptBase: string | null = null
	_cachedSystemPromptKey: string = ""

	// H16: Per-request tool-array cache.
	// buildNativeToolsArrayWithRestrictions is called up to 3× per
	// attemptApiRequest (context management, actual call, + Gemini
	// variant).  Compute once and reuse within the request scope.
	_cachedToolsResult: {
		tools: import("openai").default.Chat.ChatCompletionTool[]
		allowedFunctionNames?: string[]
	} | null = null
	_cachedToolsKey: string = ""

	// H15: Snapshot of the MCP server-set ID captured when the system prompt
	// is built on a cache miss.  Folded into the cache key so a server that
	// finishes connecting mid-turn invalidates the stale prompt.
	_mcpServerSetId: string = ""

	// Message Queue Service
	public readonly messageQueueService: MessageQueueService
	private messageQueueStateChangedHandler: (() => void) | undefined

	/**
	 * This task's mailbox — the single destination for messages from peers, the
	 * bus, the A2A mesh and Temporal owners. Owned exactly like
	 * {@link messageQueueService}, and deliberately separate from it: a human
	 * message is a TURN, an envelope is MAIL.
	 */
	public readonly mailbox: Mailbox

	/**
	 * Settles when the mailbox has been hydrated from disk.
	 *
	 * The constructor is synchronous, so the load is kicked off there and awaited
	 * by anything that must see persisted mail (the environment-details digest,
	 * a provider delivering into a task it just rehydrated). A delivery does not
	 * need to await it: `deliver` re-reads nothing and the load only ADDS what
	 * was already durable.
	 */
	public readonly mailboxReady: Promise<void>

	// Streaming
	isWaitingForFirstChunk = false
	isStreaming = false
	/**
	 * CONSECUTIVE failed model API requests — the counter behind the retry bound
	 * (`api-retry-budget.ts`). Incremented wherever the loop is about to retry
	 * automatically, and reset to 0 the moment a request completes successfully,
	 * so a blip mid-task costs nothing and only a condition that is not clearing
	 * up can reach the ceiling.
	 */
	private consecutiveApiFailures = 0
	currentStreamingContentIndex = 0
	/**
	 * Assistant turns this task has run — incremented once per API request. Surfaced to
	 * plugins as `PluginContext.turn` so a hook that fires per *tool call* (a turn can
	 * issue several) can act once per turn without guessing where turn boundaries are.
	 */
	turnCount = 0
	assistantMessageContent: AssistantMessageContent[] = []
	presentAssistantMessageLocked = false
	presentAssistantMessageHasPendingUpdates = false
	userMessageContent: (Anthropic.TextBlockParam | Anthropic.ImageBlockParam | Anthropic.ToolResultBlockParam)[] = []
	userMessageContentReady = false

	/**
	 * Flag indicating whether the assistant message for the current streaming session
	 * has been saved to API conversation history.
	 *
	 * This is critical for parallel tool calling: tools should NOT execute until
	 * the assistant message is saved. Otherwise, if a tool like `new_task` triggers
	 * `flushPendingToolResultsToHistory()`, the user message with tool_results would
	 * appear BEFORE the assistant message with tool_uses, causing API errors.
	 *
	 * Reset to `false` at the start of each API request.
	 * Set to `true` after the assistant message is saved in `recursivelyMakeShoferRequests`.
	 */
	assistantMessageSavedToHistory = false

	/** True when TaskStarted has been emitted for the current run. Reset on each initiateTaskLoop. */
	taskStartedEmitted = false
	/**
	 * Push a tool_result block to userMessageContent, preventing duplicates.
	 * Duplicate tool_use_ids cause API errors.
	 *
	 * @param toolResult - The tool_result block to add
	 * @returns true if added, false if duplicate was skipped
	 */
	public pushToolResultToUserContent(toolResult: Anthropic.ToolResultBlockParam): boolean {
		const existingResult = this.userMessageContent.find(
			(block): block is Anthropic.ToolResultBlockParam =>
				block.type === "tool_result" && block.tool_use_id === toolResult.tool_use_id,
		)
		if (existingResult) {
			taskLog.warn(
				`[Task#pushToolResultToUserContent] Skipping duplicate tool_result for tool_use_id: ${toolResult.tool_use_id}`,
			)
			return false
		}
		this.userMessageContent.push(toolResult)
		return true
	}
	didRejectTool = false
	didAlreadyUseTool = false
	didToolFailInCurrentTurn = false
	didExecuteAttemptCompletion = false
	/**
	 * True once this instance reached its OWN terminal state and emitted
	 * `TaskCompleted` — set by `emitTaskCompleted`, so it covers every
	 * completion shape (`attempt_completion` and the conversational turn of a
	 * `toolCallingEnabled === false` task alike).
	 *
	 * It exists because a completed instance is still torn down later — a
	 * follow-up message rehydrates the task, and rehydration aborts the old
	 * instance. That abort is CLEANUP, not an abort, and `abortTask` must not
	 * announce it as one: a controller watching the event stream treats any
	 * `TaskAborted` as the turn's terminal event.
	 */
	completedTerminalState = false
	didCompleteReadingStream = false
	private _started = false
	// No streaming parser is required.
	assistantMessageParser?: undefined
	private providerProfileChangeListener?: (config: { name: string; provider?: string }) => void

	// Native tool call streaming state (track which index each tool is at)
	private streamingToolCallIndices: Map<string, number> = new Map()

	/**
	 * This task's native tool-call stream assembler.
	 *
	 * Owned per task, never shared: the wire `index` a provider stamps on each
	 * argument fragment restarts at 0 for every stream, so a process-global
	 * assembler splices two concurrently streaming tasks' tool-call arguments
	 * into one another (see `NativeToolCallParser`'s class docstring). A
	 * headless worker runs many tasks in one process, so "concurrently
	 * streaming" is the normal case there, not an edge one.
	 */
	private readonly nativeToolCallParser = new NativeToolCallParser()

	// Cached model info for current streaming session (set at start of each API request)
	// This prevents excessive getModel() calls during tool execution
	cachedStreamingModel?: { id: string; info: ModelInfo }

	// Token Usage Cache
	private tokenUsageSnapshot?: TokenUsage
	private tokenUsageSnapshotAt?: number

	// Tool Usage Cache
	private toolUsageSnapshot?: ToolUsage

	// Token Usage Throttling - Debounced emit function (see ../constants.js)
	private readonly TOKEN_USAGE_EMIT_INTERVAL_MS = TASK_TOKEN_USAGE_EMIT_INTERVAL_MS
	private debouncedEmitTokenUsage: ReturnType<typeof debounce>

	// Save Debouncing — reduces write amplification during streaming.
	// During an agent turn, saveShoferMessages can fire hundreds of times
	// (once per streamed chunk). A short trailing-only debounce collapses
	// a burst of streaming updates into a single write, dramatically
	// reducing the fsync+rename rate. Flush at turn boundaries (ask/say
	// completion, abort) guarantees persistence at every observable
	// checkpoint.
	private static readonly SAVE_DEBOUNCE_INTERVAL_MS = TASK_SAVE_DEBOUNCE_INTERVAL_MS
	private _debouncedSaveShoferMessages: ReturnType<typeof debounce>

	// H29 — Throttle per-chunk partial-message appends. A streamed message is
	// re-appended to the JSONL log on every chunk via `updateShoferMessage`
	// purely for crash durability; each line is superseded almost immediately
	// (dedupe keeps the latest), so appending every one is wasted write +
	// compaction churn. Partial updates are appended at most once per interval;
	// finalized messages always append so the canonical value is durable.
	private static readonly PARTIAL_APPEND_THROTTLE_MS = TASK_PARTIAL_APPEND_THROTTLE_MS
	private _lastPartialAppendTs = 0

	// Serializes every `updateShoferMessage` publication for this task, FIFO in
	// call order. Each publication reaches its consumers only after at least one
	// await (the webview post, the task-store append), and those awaits take
	// variable time — a Postgres-backed store under load holds one for tens of
	// milliseconds. Un-serialized, two in-flight publications can therefore
	// EMIT in the opposite of call order, and the caller cannot await around it
	// because most call sites are fire-and-forget. Both consequences were
	// observed on the ShoferApi transport: cumulative partial snapshots of one
	// streamed message arriving out of order (a controller's delta view re-emits
	// the whole text, doubling it), and — the worst case — a finalized
	// `completion_result` whose emission was still parked behind its store
	// append when `TaskCompleted` went out, so every controller that correctly
	// stops reading at `taskCompleted` lost the tail of the reply.
	//
	// Lazily initialized (see `enqueueMessagePublication`) rather than a field
	// initializer, so instances built without the constructor — test doubles via
	// `Object.create(Task.prototype)` — still publish instead of throwing.
	private _messagePublishChain: Promise<void> | undefined

	// enqueueMessagePublication appends one publication to the per-task FIFO and
	// returns ITS completion. The chain swallows the link's failure so one failed
	// publication cannot wedge every later one.
	private enqueueMessagePublication(publish: () => void | Promise<void>): Promise<void> {
		const link = (this._messagePublishChain ?? Promise.resolve()).then(publish)
		this._messagePublishChain = link.catch(() => undefined)
		return link
	}

	// H2.bis — Incremental token-usage caching.
	// tokenMetadata() re-walks the entire message array on every save to
	// recompute token usage.  Most saves happen during streaming where only
	// api_req_started / condense_context messages carry token data.  Track
	// the count of those messages and reuse the cached TokenUsage when
	// unchanged — avoids an O(n) walk per save.
	// H11: _tokenBearingMessageCount is now maintained incrementally
	// (updated at the few mutation sites) so the validity check in
	// _refreshTaskMetadata is O(1) — no more O(n) walk per save.
	private _cachedTokenUsage: import("@shofer/types").TokenUsage | undefined
	private _tokenBearingMessageCount = 0

	// Initial execution state for the task's history item (set at creation time to avoid race conditions)
	private readonly initialState?: TaskState

	// When true, this task is a child of another task. Persisted onto the task's
	// HistoryItem.isBackground from the first save, which is what a scan of the
	// history store filters on to find a parent's children.
	private readonly isBackground: boolean

	// MessageManager for high-level message operations (lazy initialized)
	private _messageManager?: MessageManager

	// §4.3: lazy per-task BlobStore for inline-content externalisation.
	// Constructed on first access; persists under `<taskDir>/blobs/`.
	private _blobStore?: BlobStore

	constructor({
		provider,
		apiConfiguration,
		consecutiveMistakeLimit = DEFAULT_CONSECUTIVE_MISTAKE_LIMIT,
		taskId,
		task,
		images,
		historyItem,
		experiments: experimentsConfig,
		startTask = true,
		rootTask,
		parentTask,
		taskNumber = -1,
		onCreated,
		initialTodos,
		workspacePath,
		cwd,
		initialState,
		initialMode,
		initialApiConfigName,
		isBackground,
		softResultLength,
		softTimeoutSec,
		completionSchema,
		initialKnownPeers,
		initialTitle,
		agentRole,
		agentToolGroups,
		agentContext,
		trace,
	}: TaskOptions) {
		super()

		if (startTask && !task && !images && !historyItem) {
			throw new Error("Either historyItem or task/images must be provided")
		}

		this.taskId = historyItem ? historyItem.id : (taskId ?? uuidv7())
		this.rootTaskId = historyItem ? historyItem.rootTaskId : (rootTask?.rootTaskId ?? rootTask?.taskId)
		this.parentTaskId = historyItem ? historyItem.parentTaskId : parentTask?.taskId

		// Rehydrate knownPeers so peer communication grants survive extension
		// restarts: persisted peerIds plus this task's own children (parent↔child
		// is always allowed). Including children also covers tasks persisted before
		// peerIds existed, keeping parent→child messaging working after a reload.
		if (historyItem) {
			const rehydratedPeers = new Set<string>([
				...(historyItem.peerIds ?? []),
				...(historyItem.childIds ?? []),
				...(historyItem.backgroundChildIds ?? []),
			])
			if (rehydratedPeers.size > 0) {
				this.knownPeers = rehydratedPeers
			}
		} else if (initialKnownPeers && initialKnownPeers.length > 0) {
			// Fresh task (no persisted history yet): seed knownPeers from the
			// spawn-time grant so the first persisted HistoryItem.peerIds carries
			// it (see the peerIds write in
			// _refreshTaskMetadata). This removes the post-creation persistence
			// race the spawner would otherwise hit ("Task not found").
			this.knownPeers = new Set<string>(initialKnownPeers)
		}
		this.childTaskId = undefined

		// Timeline: monotonic origin for all per-task span offsets.
		this.timelineOriginMs = performance.now()

		this.metadata = {
			task: historyItem ? historyItem.task : task,
			images: historyItem ? [] : images,
		}

		// Normal use-case is usually retry similar history task with new workspace.
		this.workspacePath = parentTask
			? parentTask.workspacePath
			: (workspacePath ?? getWorkspacePath(path.join(os.homedir(), "Desktop")))

		// Per-task working directory. For embedded worktree tasks this is the
		// worktree subdirectory (e.g. .worktrees/repo-hl911/); for
		// regular tasks it defaults to workspacePath.
		this._cwd = cwd ?? historyItem?.cwd ?? this.workspacePath

		this.instanceId = crypto.randomUUID().slice(0, 8)
		this.taskNumber = -1

		this.shoferIgnoreController = new ShoferIgnoreController(this.cwd)
		this.shoferProtectedController = new ShoferProtectedController(this.cwd)
		this.fileContextTracker = new FileContextTracker(
			provider as unknown as ConstructorParameters<typeof FileContextTracker>[0],
			this.taskId,
			this.cwd,
		)

		this.shoferIgnoreController.initialize().catch((error) => {
			taskLog.error("Failed to initialize ShoferIgnoreController:", error)
		})

		this.apiConfiguration = apiConfiguration
		this.api = buildApiHandler(this.apiConfiguration, {
			taskId: this.taskId,
			parentTaskId: this.parentTaskId,
			rootTaskId: this.rootTaskId,
		})
		this.autoApprovalHandler = new AutoApprovalHandler()

		this.consecutiveMistakeLimit = consecutiveMistakeLimit ?? DEFAULT_CONSECUTIVE_MISTAKE_LIMIT
		this.experimentsConfig = experimentsConfig
		this.providerRef = new WeakRef(provider)
		this.globalStoragePath = (provider.context as { globalStorageUri: { fsPath: string } }).globalStorageUri.fsPath
		this.diffViewProvider = getHost().createDiffView(this.cwd, this)

		this.parentTask = parentTask
		this.rootTask = rootTask
		// Inherit task-scoped outside-workspace trust from the parent as a snapshot
		// at creation time (subtasks trust what the parent trusted so far).
		this.trustedReadPaths = [...(parentTask?.trustedReadPaths ?? [])]
		this.trustedWritePaths = [...(parentTask?.trustedWritePaths ?? [])]
		this.taskNumber = taskNumber
		this.agentRole = agentRole
		this.trace = trace
		this.agentToolGroups = agentToolGroups
		this.agentContext = agentContext
		this.softResultLength = softResultLength
		this.softTimeoutSec = softTimeoutSec
		this.completionSchema = completionSchema
		// Restore the cost limit from history ONLY for root tasks. Subtasks
		// resolve their effective limit via resolveCostLimit() and never carry
		// their own — keeping a single source of truth on the root.
		if (!parentTask) {
			this.costLimit = historyItem?.costLimit
		}
		this.initialState = initialState
		// Prefer explicit constructor flag; otherwise inherit from history item on rehydration.
		this.isBackground = isBackground ?? historyItem?.isBackground ?? false

		// Parent-locked title: a fresh task seeds its name + lock from `initialTitle`
		// (set by NewTaskTool's `title` param); a rehydrated task re-applies the lock
		// from its persisted history so `set_task_title` stays blocked across restarts.
		// `_refreshTaskMetadata` re-persists `name`/`nameLocked` on every write while
		// locked. Trimmed/clamped to 60 chars to match set_task_title's bound.
		if (historyItem) {
			if (historyItem.nameLocked) {
				this.nameLocked = true
				this.lockedTitle = historyItem.name
			}
		} else if (initialTitle) {
			const cleanTitle = initialTitle.trim().substring(0, 60)
			if (cleanTitle) {
				this.nameLocked = true
				this.lockedTitle = cleanTitle
			}
		}

		// Store the task's mode and API config name when it's created.
		// For history items, use the stored values; for new tasks, we'll set them
		// after getting state.
		if (historyItem) {
			this._taskMode = historyItem.mode || defaultModeSlug
			this._taskApiConfigName = historyItem.apiConfigName
			this.taskModeReady = Promise.resolve()

			// Restore loaded skills from history item (survives rehydration)
			if (historyItem.loadedSkills) {
				for (const skillName of historyItem.loadedSkills) {
					this.loadedSkills.set(skillName, "")
				}
			}
			this.taskApiConfigReady = Promise.resolve()
			TelemetryService.instance.captureTaskRestarted(this.taskId)
		} else if (initialMode || initialApiConfigName) {
			// Allow callers to seed task mode / API config without mutating provider globals.
			this._taskMode = initialMode
			this._taskApiConfigName = initialApiConfigName
			this.taskModeReady = initialMode ? Promise.resolve() : this.initializeTaskMode(provider)
			this.taskApiConfigReady = initialApiConfigName
				? Promise.resolve()
				: this.initializeTaskApiConfigName(provider)
			TelemetryService.instance.captureTaskCreated(this.taskId)
		} else {
			// For new tasks, don't set the mode/apiConfigName yet - wait for async initialization.
			this._taskMode = undefined
			this._taskApiConfigName = undefined
			this.taskModeReady = this.initializeTaskMode(provider)
			this.taskApiConfigReady = this.initializeTaskApiConfigName(provider)
			TelemetryService.instance.captureTaskCreated(this.taskId)
		}

		this.assistantMessageParser = undefined

		this.messageQueueService = new MessageQueueService()

		// Hydrate the mailbox from its own file (never from the history row —
		// `taskState` has a single writer and the fire-and-forget history writes
		// race). Failure inside `load()` fails closed to an empty box, so this
		// promise never rejects and a task always starts.
		this.mailbox = new Mailbox(this.taskId, this.globalStoragePath)
		this.mailboxReady = this.mailbox.load()

		this.messageQueueStateChangedHandler = () => {
			this.emit(ShoferEventName.TaskUserMessage, this.taskId)
			this.emit(ShoferEventName.QueuedMessagesUpdated, this.taskId, this.messageQueueService.messages)
			// Push the updated message queue to the webview via incremental
			// taskStateUpdate (not a full postInitState). Gate on the same
			// focused/current-task check as addToShoferMessages.
			const p = this.providerRef.deref()
			if (
				p &&
				(p.taskManager?.getFocusedTaskId() === this.taskId || p.getCurrentTask()?.taskId === this.taskId)
			) {
				p.postTaskStateUpdate({ messageQueue: this.messageQueueService.messages })
			}
		}

		this.messageQueueService.on("stateChanged", this.messageQueueStateChangedHandler)

		// Listen for provider profile changes to update parser state
		this.setupProviderProfileChangeListener(provider)

		// Set up diff strategy
		this.diffStrategy = new MultiSearchReplaceDiffStrategy()

		this.toolRepetitionDetector = new ToolRepetitionDetector(this.consecutiveMistakeLimit)

		// Initialize todo list if provided
		if (initialTodos && initialTodos.length > 0) {
			this.todoList = initialTodos
		}

		// Initialize debounced token usage emit function
		// Uses debounce with maxWait to achieve throttle-like behavior:
		// - leading: true  - Emit immediately on first call
		// - trailing: true - Emit final state when updates stop
		// - maxWait        - Ensures at most one emit per interval during rapid updates (throttle behavior)
		this.debouncedEmitTokenUsage = debounce(
			(tokenUsage: TokenUsage, toolUsage: ToolUsage) => {
				const tokenChanged = hasTokenUsageChanged(tokenUsage, this.tokenUsageSnapshot)
				const toolChanged = hasToolUsageChanged(toolUsage, this.toolUsageSnapshot)

				if (tokenChanged || toolChanged) {
					this.emit(ShoferEventName.TaskTokenUsageUpdated, this.taskId, tokenUsage, toolUsage)
					this.tokenUsageSnapshot = tokenUsage
					this.tokenUsageSnapshotAt = this.shoferMessages.at(-1)?.ts
					// Deep copy tool usage for snapshot
					this.toolUsageSnapshot = JSON.parse(JSON.stringify(toolUsage))
				}
			},
			this.TOKEN_USAGE_EMIT_INTERVAL_MS,
			{ leading: true, trailing: true, maxWait: this.TOKEN_USAGE_EMIT_INTERVAL_MS },
		)

		// Initialize debounced metadata refresh.
		//
		// Per §4.1 of `docs/mem-utilization-profiling.md`, individual messages
		// are now persisted via `appendTaskMessage` at the call sites
		// (`addToShoferMessages`, `updateShoferMessage`), so the debounced
		// callback only needs to refresh the lightweight metadata (taskMetadata
		// + updateTaskHistory + token-usage emit) — it does NOT rewrite the
		// full JSONL log. Full rewrites happen only at turn boundaries via
		// `_flushSaveShoferMessages` → `saveShoferMessages`.
		//
		// NOTE: this is fire-and-forget — await is a no-op on the leading
		// edge because lodash.debounce returns the previous invocation's
		// result, not the pending one.  Callers that genuinely need
		// fsync-completion must use _flushSaveShoferMessages().
		this._debouncedSaveShoferMessages = debounce(
			() => {
				void this._refreshTaskMetadata()
			},
			Task.SAVE_DEBOUNCE_INTERVAL_MS,
			{ leading: false, trailing: true, maxWait: Task.SAVE_DEBOUNCE_INTERVAL_MS * 4 },
		)

		onCreated?.(this)

		// Set up messages-ready promise.
		// - `startTask: false`: resolve immediately (no message loading).
		// - `startTask` with `task`/`images`: resolved inside `startTask()` after
		//    the first user message is posted.
		// - `startTask` with `historyItem`: resolved inside
		//    `resumeTaskFromHistory()` after messages are loaded from disk.
		let resolveMessagesReady: () => void
		this.messagesReady = new Promise<void>((resolve) => {
			resolveMessagesReady = resolve
		})
		this._messagesReadyResolve = resolveMessagesReady!

		if (startTask) {
			this._started = true
			if (task || images) {
				this.startTask(task, images)
			} else if (historyItem) {
				this.resumeTaskFromHistory()
			} else {
				this._messagesReadyResolve()
				throw new Error("Either historyItem or task/images must be provided")
			}
		} else {
			this._messagesReadyResolve()
		}
	}

	/**
	 * Trust an outside-workspace directory for this task (and its subtasks) via the
	 * inline "Trust path" approval button. In-memory only; not persisted. A write-group
	 * tool trusts read+write (callers pass `"write"`); a read tool trusts read.
	 */
	public trustOutsideWorkspacePath(dir: string, access: "read" | "write"): void {
		const list = access === "write" ? this.trustedWritePaths : this.trustedReadPaths
		if (!list.includes(dir)) list.push(dir)
	}

	/**
	 * Merge this task's task-scoped trusted paths into a settings state object so
	 * {@link checkAutoApproval} treats them like the persistent allowlists. Returns
	 * the state untouched when there is nothing trusted for this task.
	 */
	private withTaskTrust<T extends { allowedReadPaths?: string[]; allowedWritePaths?: string[] } | undefined>(
		state: T,
	): T {
		if (!state || (this.trustedReadPaths.length === 0 && this.trustedWritePaths.length === 0)) return state
		return {
			...state,
			allowedReadPaths: [...(state.allowedReadPaths ?? []), ...this.trustedReadPaths],
			allowedWritePaths: [...(state.allowedWritePaths ?? []), ...this.trustedWritePaths],
		} as T
	}

	/**
	 * Initialize the task mode from the provider state.
	 * This method handles async initialization with proper error handling.
	 *
	 * ## Flow
	 * 1. Attempts to fetch the current mode from provider state
	 * 2. Sets `_taskMode` to the fetched mode or `defaultModeSlug` if unavailable
	 * 3. Handles errors gracefully by falling back to default mode
	 * 4. Logs any initialization errors for debugging
	 *
	 * ## Error handling
	 * - Network failures when fetching provider state
	 * - Provider not yet initialized
	 * - Invalid state structure
	 *
	 * All errors result in fallback to `defaultModeSlug` to ensure task can proceed.
	 *
	 * @private
	 * @param provider - The ShoferProvider instance to fetch state from
	 * @returns Promise that resolves when initialization is complete
	 */
	private async initializeTaskMode(provider: TaskProviderLike<Task>): Promise<void> {
		try {
			const state = await provider.getState()
			// The global `mode` is the tier-3 cold-start default for a new task that
			// was not seeded with an explicit `initialMode`.
			this._taskMode = state?.mode || defaultModeSlug
		} catch (error) {
			// If there's an error getting state, use the default mode
			this._taskMode = defaultModeSlug
			// Use the provider's log method for better error visibility
			const errorMessage = `Failed to initialize task mode: ${error instanceof Error ? error.message : String(error)}`
			provider.log(errorMessage)
		}
	}

	/**
	 * Initialize the task API config name from the provider state.
	 * This method handles async initialization with proper error handling.
	 *
	 * ## Flow
	 * 1. Attempts to fetch the current API config name from provider state
	 * 2. Sets `_taskApiConfigName` to the fetched name or "default" if unavailable
	 * 3. Handles errors gracefully by falling back to "default"
	 * 4. Logs any initialization errors for debugging
	 *
	 * ## Error handling
	 * - Network failures when fetching provider state
	 * - Provider not yet initialized
	 * - Invalid state structure
	 *
	 * All errors result in fallback to "default" to ensure task can proceed.
	 *
	 * @private
	 * @param provider - The ShoferProvider instance to fetch state from
	 * @returns Promise that resolves when initialization is complete
	 */
	private async initializeTaskApiConfigName(provider: TaskProviderLike<Task>): Promise<void> {
		try {
			const state = await provider.getState()

			// Avoid clobbering a newer value that may have been set while awaiting provider state
			// (e.g., user switches provider profile immediately after task creation).
			if (this._taskApiConfigName === undefined) {
				this._taskApiConfigName = state?.currentApiConfigName ?? "default"
			}
		} catch (error) {
			// If there's an error getting state, use the default profile (unless a newer value was set).
			if (this._taskApiConfigName === undefined) {
				this._taskApiConfigName = "default"
			}
			// Use the provider's log method for better error visibility
			const errorMessage = `Failed to initialize task API config name: ${error instanceof Error ? error.message : String(error)}`
			provider.log(errorMessage)
		}
	}

	/**
	 * Sets up a listener for provider profile changes.
	 *
	 * @private
	 * @param provider - The ShoferProvider instance to listen to
	 */
	private setupProviderProfileChangeListener(provider: TaskProviderLike<Task>): void {
		// Only set up listener if provider has the on method (may not exist in test mocks)
		if (typeof provider.on !== "function") {
			return
		}

		// Remove any previously registered listener to prevent duplicates
		// (can happen if setup is called multiple times on the same Task instance).
		if (this.providerProfileChangeListener) {
			provider.off(ShoferEventName.ProviderProfileChanged, this.providerProfileChangeListener)
		}

		this.providerProfileChangeListener = async (event?: { name?: string; provider?: string }) => {
			try {
				// Respect sticky provider profiles: only update if this task's
				// sticky profile matches the profile that changed. Tasks with a
				// different taskApiConfigName must keep their own provider.
				if (
					event?.name !== undefined &&
					this._taskApiConfigName !== undefined &&
					this._taskApiConfigName !== event.name
				) {
					return
				}

				const newState = await provider.getState()
				if (newState?.apiConfiguration) {
					this.updateApiConfiguration(newState.apiConfiguration)
				}
			} catch (error) {
				taskLog.error(
					`[Task#${this.taskId}.${this.instanceId}] Failed to update API configuration on profile change:`,
					error,
				)
			}
		}

		provider.on(ShoferEventName.ProviderProfileChanged, this.providerProfileChangeListener)
	}

	/**
	 * Wait for the task mode to be initialized before proceeding.
	 * This method ensures that any operations depending on the task mode
	 * will have access to the correct mode value.
	 *
	 * ## When to use
	 * - Before accessing mode-specific configurations
	 * - When switching between tasks with different modes
	 * - Before operations that depend on mode-based permissions
	 *
	 * ## Example usage
	 * ```typescript
	 * // Wait for mode initialization before mode-dependent operations
	 * await task.waitForModeInitialization();
	 * const mode = task.taskMode; // Now safe to access synchronously
	 *
	 * // Or use with getTaskMode() for a one-liner
	 * const mode = await task.getTaskMode(); // Internally waits for initialization
	 * ```
	 *
	 * @returns Promise that resolves when the task mode is initialized
	 * @public
	 */
	public async waitForModeInitialization(): Promise<void> {
		return this.taskModeReady
	}

	/**
	 * Get the task mode asynchronously, ensuring it's properly initialized.
	 * This is the recommended way to access the task mode as it guarantees
	 * the mode is available before returning.
	 *
	 * ## Async behavior
	 * - Internally waits for `taskModeReady` promise to resolve
	 * - Returns the initialized mode or `defaultModeSlug` as fallback
	 * - Safe to call multiple times - subsequent calls return immediately if already initialized
	 *
	 * ## Example usage
	 * ```typescript
	 * // Safe async access
	 * const mode = await task.getTaskMode();
	 * console.log(`Task is running in ${mode} mode`);
	 *
	 * // Use in conditional logic
	 * if (await task.getTaskMode() === 'architect') {
	 *   // Perform architect-specific operations
	 * }
	 * ```
	 *
	 * @returns Promise resolving to the task mode string
	 * @public
	 */
	public async getTaskMode(): Promise<string> {
		await this.taskModeReady
		return this._taskMode || defaultModeSlug
	}

	/**
	 * Get the task mode synchronously. This should only be used when you're certain
	 * that the mode has already been initialized (e.g., after waitForModeInitialization).
	 *
	 * ## When to use
	 * - In synchronous contexts where async/await is not available
	 * - After explicitly waiting for initialization via `waitForModeInitialization()`
	 * - In event handlers or callbacks where mode is guaranteed to be initialized
	 *
	 * ## Example usage
	 * ```typescript
	 * // After ensuring initialization
	 * await task.waitForModeInitialization();
	 * const mode = task.taskMode; // Safe synchronous access
	 *
	 * // In an event handler after task is started
	 * task.on('taskStarted', () => {
	 *   console.log(`Task started in ${task.taskMode} mode`); // Safe here
	 * });
	 * ```
	 *
	 * @throws {Error} If the mode hasn't been initialized yet
	 * @returns The task mode string
	 * @public
	 */
	public get taskMode(): string {
		if (this._taskMode === undefined) {
			throw new Error("Task mode accessed before initialization. Use getTaskMode() or wait for taskModeReady.")
		}

		return this._taskMode
	}

	/**
	 * Wait for the task API config name to be initialized before proceeding.
	 * This method ensures that any operations depending on the task's provider profile
	 * will have access to the correct value.
	 *
	 * ## When to use
	 * - Before accessing provider profile-specific configurations
	 * - When switching between tasks with different provider profiles
	 * - Before operations that depend on the provider profile
	 *
	 * @returns Promise that resolves when the task API config name is initialized
	 * @public
	 */
	public async waitForApiConfigInitialization(): Promise<void> {
		return this.taskApiConfigReady
	}

	/**
	 * Get the task API config name asynchronously, ensuring it's properly initialized.
	 * This is the recommended way to access the task's provider profile as it guarantees
	 * the value is available before returning.
	 *
	 * ## Async behavior
	 * - Internally waits for `taskApiConfigReady` promise to resolve
	 * - Returns the initialized API config name or undefined as fallback
	 * - Safe to call multiple times - subsequent calls return immediately if already initialized
	 *
	 * @returns Promise resolving to the task API config name string or undefined
	 * @public
	 */
	public async getTaskApiConfigName(): Promise<string | undefined> {
		await this.taskApiConfigReady
		return this._taskApiConfigName
	}

	/**
	 * Get the task API config name synchronously. This should only be used when you're certain
	 * that the value has already been initialized (e.g., after waitForApiConfigInitialization).
	 *
	 * ## When to use
	 * - In synchronous contexts where async/await is not available
	 * - After explicitly waiting for initialization via `waitForApiConfigInitialization()`
	 * - In event handlers or callbacks where API config name is guaranteed to be initialized
	 *
	 * Note: Unlike taskMode, this getter does not throw if uninitialized since the API config
	 * name can legitimately be undefined (backward compatibility with tasks created before
	 * this feature was added).
	 *
	 * @returns The task API config name string or undefined
	 * @public
	 */
	public get taskApiConfigName(): string | undefined {
		return this._taskApiConfigName
	}

	/**
	 * Update the task's API config name. This is called when the user switches
	 * provider profiles while a task is active, allowing the task to remember
	 * its new provider profile.
	 *
	 * @param apiConfigName - The new API config name to set
	 * @internal
	 */
	public setTaskApiConfigName(apiConfigName: string | undefined): void {
		this._taskApiConfigName = apiConfigName
	}

	static create(options: TaskOptions): [Task, Promise<void>] {
		const instance = new Task({ ...options, startTask: false })
		const { images, task, historyItem } = options
		let promise

		if (images || task) {
			promise = instance.startTask(task, images)
		} else if (historyItem) {
			promise = instance.resumeTaskFromHistory()
		} else {
			throw new Error("Either historyItem or task/images must be provided")
		}

		return [instance, promise]
	}

	/** No-op: diagnostic logging disabled. */
	private diagLog(_message: string) {}

	// API Messages

	/**
	 * The task store (§5), resolved once per task.
	 *
	 * WHICH backend this is comes from host wiring, not from here — see
	 * `task-persistence/backend.ts`. The default is the local SQLite + files
	 * pair; a host serving a pool of interchangeable processes supplies a shared
	 * one. Resolution is cached per host, so this costs a map lookup after the
	 * first task.
	 */
	private _persistencePromise?: Promise<TaskPersistencePort>
	private getPersistence(): Promise<TaskPersistencePort> {
		if (!this._persistencePromise) {
			this._persistencePromise = resolveTaskPersistence(this.globalStoragePath)
		}
		return this._persistencePromise
	}

	/**
	 * Run one turn under a lease on this task, when the backend has leases.
	 *
	 * Sticky routing makes a second driver for the same task RARE; it does not
	 * make it impossible (a caller holding a stale endpoint list, a previous
	 * owner still finishing, a deliberate failover retry). The lease is what
	 * makes the residual case safe: exactly one holder at a time, and every write
	 * the backend makes carries the fence it was granted at, so a stale holder's
	 * writes are rejected instead of interleaving into the transcript.
	 *
	 * A backend with no lease support runs the turn unchanged — that is the local
	 * default, where a single writer is guaranteed by the filesystem.
	 */
	private async _withTaskLease<T>(run: () => Promise<T>): Promise<T> {
		const persistence = await this.getPersistence()
		if (!persistence.lease) {
			return run()
		}

		const lease = await persistence.lease.claim(this.taskId, (reason) => this._onTaskLeaseLost(reason))
		try {
			return await run()
		} finally {
			await lease.release().catch((error: unknown) => {
				// The claim expires on its own; a failed release costs the next
				// driver one expiry window, never correctness.
				taskLog.warn(`Failed to release the task lease for ${this.taskId}:`, error)
			})
		}
	}

	/**
	 * Losing the lease mid-turn ends the turn, loudly.
	 *
	 * Another process now owns this task, so everything this one is still doing
	 * is work whose output the store will refuse. The abort is the point: a
	 * fence-rejected write is the BACKSTOP for this condition, not the way it is
	 * meant to be discovered, and continuing to stream into a transcript nobody
	 * will accept burns provider quota for output that cannot land.
	 *
	 * Nothing is said into the transcript on the way out — that write is exactly
	 * what the fence rejects — so the log is the record.
	 */
	private _onTaskLeaseLost(reason: Error): void {
		taskLog.error(`Task ${this.taskId}.${this.instanceId} lost its store lease; aborting the turn:`, reason)
		void this.abortTask().catch((error: unknown) => {
			taskLog.error(`Failed to abort ${this.taskId} after losing its store lease:`, error)
		})
	}

	private async getSavedApiConversationHistory(): Promise<ApiMessage[]> {
		return (await this.getPersistence()).readApiMessages(this.taskId)
	}

	/**
	 * XXX TODO REMOVE — temporary diagnostic for the duplicate-user-message bug.
	 * Remove this helper, `_diagnoseDuplicateUserAppend`, and the call site
	 * at the top of `addToApiConversationHistory` once the underlying writer-side
	 * race is identified and fixed.
	 *
	 * Fingerprint of a user message's content for duplicate-append detection.
	 * Strips the `Current Time` line out of any text block so that two iterations
	 * that re-issue the same `currentUserContent` with regenerated env_details
	 * still fingerprint identically. Returns `undefined` for non-user messages
	 * (we only diagnose duplicate user appends — assistants legitimately repeat
	 * structurally similar tool_use blocks across turns).
	 */
	private _userMessageFingerprint(message: Anthropic.MessageParam): string | undefined {
		if (message.role !== "user") return undefined
		const stripTime = (s: string): string => s.replace(/^# Current Time\n.*$/m, "# Current Time\n<elided>")
		const content = message.content
		if (typeof content === "string") return `S:${stripTime(content)}`
		if (!Array.isArray(content)) return undefined
		const parts: string[] = []
		for (const block of content) {
			if (block.type === "text") {
				parts.push(`T:${stripTime(block.text)}`)
			} else if (block.type === "tool_result") {
				const c = block.content
				const body = typeof c === "string" ? c : JSON.stringify(c)
				parts.push(`R:${block.tool_use_id}:${block.is_error ? "E" : "K"}:${body}`)
			} else {
				parts.push(`X:${block.type}:${JSON.stringify(block)}`)
			}
		}
		return parts.join("\n--\n")
	}

	/**
	 * XXX TODO REMOVE — temporary diagnostic for the duplicate-user-message bug.
	 * Remove together with `_userMessageFingerprint` and the call site at the
	 * top of `addToApiConversationHistory` once the writer-side race is fixed.
	 *
	 * Detect (and loudly log) two adjacent byte-identical user-message appends
	 * to `apiConversationHistory`. The pre-existing defensive dedup passes
	 * (`_cleanupOrphanedToolUses`, llm-provider `reorderToolMessages`) mask
	 * the symptom on the wire, but the underlying writer-side race is still
	 * unfixed: this log captures the call stack and surrounding state the next
	 * time it fires so we can identify the offending caller path. Cheap (one
	 * string compare + an `Error()` for the stack) and gated on a real duplicate.
	 */
	private _diagnoseDuplicateUserAppend(message: Anthropic.MessageParam): void {
		const fp = this._userMessageFingerprint(message)
		if (!fp) return
		const tail = this.apiConversationHistory[this.apiConversationHistory.length - 1]
		if (!tail) return
		const tailFp = this._userMessageFingerprint(tail)
		if (!tailFp || tailFp !== fp) return
		const stack = new Error("DUPLICATE_USER_APPEND").stack ?? "<no stack>"
		taskLog.warn(
			`[Task#${this.taskId}.${this.instanceId}] DUPLICATE_USER_APPEND detected: ` +
				`previous tail user message has matching fingerprint (env_details Current Time elided). ` +
				`apiConversationHistory.length=${this.apiConversationHistory.length}, ` +
				// eslint-disable-next-line @typescript-eslint/no-explicit-any
				`tailTs=${(tail as any).ts}, fingerprintBytes=${fp.length}\n` +
				`fingerprintHead=${fp.slice(0, 400)}\n` +
				`stack:\n${stack}`,
		)
	}

	private async addToApiConversationHistory(message: Anthropic.MessageParam, reasoning?: string) {
		// XXX TODO REMOVE — temporary diagnostic for the duplicate-user-message bug.
		// Diagnostic: detect duplicate-user-message-append (two byte-identical
		// user messages mod env_details `Current Time`). The defensive
		// `_cleanupOrphanedToolUses` + provider-side `reorderToolMessages`
		// dedup masks the symptom; this log captures the offending call path
		// the next time the underlying race fires so we can fix the source.
		// Remove this call together with `_diagnoseDuplicateUserAppend` and
		// `_userMessageFingerprint` once the root cause is fixed.
		this._diagnoseDuplicateUserAppend(message)
		// §4.3: externalise any oversized inline text BEFORE the message is
		// snapshotted into `apiConversationHistory` and persisted to disk.
		// Mutates `message.content` in place; refs are resolved back to
		// content only when the message is selected for an outgoing LLM
		// request (see `prepareMessagesForApi`).
		await this.externalizeMessageContent(message)
		// Capture the encrypted_content / thought signatures from the provider (e.g., OpenAI Responses API, Google GenAI) if present.
		// We only persist data reported by the current response body.
		const handler = this.api as ApiHandler & {
			getResponseId?: () => string | undefined
			getEncryptedContent?: () => { encrypted_content: string; id?: string } | undefined
			getThoughtSignature?: () => string | undefined
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			getSummary?: () => any[] | undefined
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			getReasoningDetails?: () => any[] | undefined
		}

		if (message.role === "assistant") {
			const responseId = handler.getResponseId?.()
			const reasoningData = handler.getEncryptedContent?.()
			const thoughtSignature = handler.getThoughtSignature?.()
			const reasoningSummary = handler.getSummary?.()
			const reasoningDetails = handler.getReasoningDetails?.()

			// Only Anthropic's API expects/validates the special `thinking` content block signature.
			// Other providers (notably Gemini 3) use different signature semantics (e.g. `thoughtSignature`)
			// and require round-tripping the signature in their own format.
			const modelId = getModelId(this.apiConfiguration)
			const apiProvider = this.apiConfiguration.apiProvider
			const apiProtocol = getApiProtocol(
				apiProvider && !isRetiredProvider(apiProvider) ? apiProvider : undefined,
				modelId,
			)
			const isAnthropicProtocol = apiProtocol === "anthropic"

			// Start from the original assistant message
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			const messageWithTs: any = {
				...message,
				...(responseId ? { id: responseId } : {}),
				ts: Date.now(),
			}

			// Store reasoning_details array if present (for models like Gemini 3)
			if (reasoningDetails) {
				messageWithTs.reasoning_details = reasoningDetails
			}

			// Store reasoning: Anthropic thinking (with signature), plain text (most providers), or encrypted (OpenAI Native)
			// Skip if reasoning_details already contains the reasoning (to avoid duplication)
			if (isAnthropicProtocol && reasoning && thoughtSignature && !reasoningDetails) {
				// Anthropic provider with extended thinking: Store as proper `thinking` block
				// This format passes through anthropic-filter.ts and is properly round-tripped
				// for interleaved thinking with tool use (required by Anthropic API)
				const thinkingBlock = {
					type: "thinking",
					thinking: reasoning,
					signature: thoughtSignature,
				}

				if (typeof messageWithTs.content === "string") {
					messageWithTs.content = [
						thinkingBlock,
						{ type: "text", text: messageWithTs.content } satisfies Anthropic.Messages.TextBlockParam,
					]
				} else if (Array.isArray(messageWithTs.content)) {
					messageWithTs.content = [thinkingBlock, ...messageWithTs.content]
				} else if (!messageWithTs.content) {
					messageWithTs.content = [thinkingBlock]
				}
			} else if (reasoning && !reasoningDetails) {
				// Other providers (non-Anthropic): Store as generic reasoning block
				const reasoningBlock = {
					type: "reasoning",
					text: reasoning,
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					summary: reasoningSummary ?? ([] as any[]),
				}

				if (typeof messageWithTs.content === "string") {
					messageWithTs.content = [
						reasoningBlock,
						{ type: "text", text: messageWithTs.content } satisfies Anthropic.Messages.TextBlockParam,
					]
				} else if (Array.isArray(messageWithTs.content)) {
					messageWithTs.content = [reasoningBlock, ...messageWithTs.content]
				} else if (!messageWithTs.content) {
					messageWithTs.content = [reasoningBlock]
				}
			} else if (reasoningData?.encrypted_content) {
				// OpenAI Native encrypted reasoning
				const reasoningBlock = {
					type: "reasoning",
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					summary: [] as any[],
					encrypted_content: reasoningData.encrypted_content,
					...(reasoningData.id ? { id: reasoningData.id } : {}),
				}

				if (typeof messageWithTs.content === "string") {
					messageWithTs.content = [
						reasoningBlock,
						{ type: "text", text: messageWithTs.content } satisfies Anthropic.Messages.TextBlockParam,
					]
				} else if (Array.isArray(messageWithTs.content)) {
					messageWithTs.content = [reasoningBlock, ...messageWithTs.content]
				} else if (!messageWithTs.content) {
					messageWithTs.content = [reasoningBlock]
				}
			}

			// For non-Anthropic providers (e.g., Gemini 3), persist the thought signature as its own
			// content block so converters can attach it back to the correct provider-specific fields.
			// Note: For Anthropic extended thinking, the signature is already included in the thinking block above.
			if (thoughtSignature && !isAnthropicProtocol) {
				const thoughtSignatureBlock = {
					type: "thoughtSignature",
					thoughtSignature,
				}

				if (typeof messageWithTs.content === "string") {
					messageWithTs.content = [
						{ type: "text", text: messageWithTs.content } satisfies Anthropic.Messages.TextBlockParam,
						thoughtSignatureBlock,
					]
				} else if (Array.isArray(messageWithTs.content)) {
					messageWithTs.content = [...messageWithTs.content, thoughtSignatureBlock]
				} else if (!messageWithTs.content) {
					messageWithTs.content = [thoughtSignatureBlock]
				}
			}

			this.apiConversationHistory.push(messageWithTs)
		} else {
			// For user messages, validate tool_result IDs ONLY when the immediately previous *effective* message
			// is an assistant message.
			//
			// If the previous effective message is also a user message (e.g., summary + a new user message),
			// validating against any earlier assistant message can incorrectly inject placeholder tool_results.
			const effectiveHistoryForValidation = getEffectiveApiHistory(this.apiConversationHistory)
			const lastEffective = effectiveHistoryForValidation[effectiveHistoryForValidation.length - 1]
			const historyForValidation = lastEffective?.role === "assistant" ? effectiveHistoryForValidation : []

			// If the previous effective message is NOT an assistant, convert tool_result blocks to text blocks.
			// This prevents orphaned tool_results from being filtered out by getEffectiveApiHistory.
			// This can happen when condensing occurs after the assistant sends tool_uses but before
			// the user responds - the tool_use blocks get condensed away, leaving orphaned tool_results.
			let messageToAdd = message
			if (lastEffective?.role !== "assistant" && Array.isArray(message.content)) {
				messageToAdd = {
					...message,
					content: message.content.map((block) =>
						block.type === "tool_result"
							? {
									type: "text" as const,
									text: `Tool result:\n${typeof block.content === "string" ? block.content : JSON.stringify(block.content)}`,
								}
							: block,
					),
				}
			}

			const validatedMessage = validateAndFixToolResultIds(messageToAdd, historyForValidation)
			const messageWithTs = { ...validatedMessage, ts: Date.now() }
			this.apiConversationHistory.push(messageWithTs)
		}

		// §4.1: O(1) append to JSONL log. Full rewrites happen only via
		// `overwriteApiConversationHistory` / `retrySaveApiConversationHistory`.
		try {
			const last = this.apiConversationHistory[this.apiConversationHistory.length - 1]
			if (last) {
				await (await this.getPersistence()).appendApiMessage(this.taskId, last)
			}
		} catch (error) {
			taskLog.error("Failed to append API message:", error)
		}
	}

	// NOTE: We intentionally do NOT mutate stored messages to merge consecutive user turns.
	// For API requests, consecutive same-role messages are merged via mergeConsecutiveApiMessages()
	// so rewind/edit behavior can still reference original message boundaries.

	async overwriteApiConversationHistory(newHistory: ApiMessage[]) {
		this.apiConversationHistory = newHistory
		await this.saveApiConversationHistory()
	}

	/**
	 * Flush any pending tool results to the API conversation history.
	 *
	 * This is critical when the task is about to be
	 * delegated (e.g., via new_task). Before delegation, if other tools were
	 * called in the same turn before new_task, their tool_result blocks are
	 * accumulated in `userMessageContent` but haven't been saved to the API
	 * history yet. If we don't flush them before the parent is disposed,
	 * the API conversation will be incomplete and cause 400 errors when
	 * the parent resumes (missing tool_result for tool_use blocks).
	 *
	 * NOTE: The assistant message is typically already in history by the time
	 * tools execute (added in recursivelyMakeShoferRequests after streaming completes).
	 * So we usually only need to flush the pending user message with tool_results.
	 */
	public async flushPendingToolResultsToHistory(): Promise<boolean> {
		// Only flush if there's actually pending content to save
		if (this.userMessageContent.length === 0) {
			return true
		}

		// CRITICAL: Wait for the assistant message to be saved to API history first.
		// Without this, tool_result blocks would appear BEFORE tool_use blocks in the
		// conversation history, causing API errors like:
		// "unexpected `tool_use_id` found in `tool_result` blocks"
		//
		// This can happen when parallel tools are called (e.g., update_todo_list + new_task).
		// Tools execute during streaming via presentAssistantMessage, BEFORE the assistant
		// message is saved. When new_task triggers delegation, it calls this method to
		// flush pending results - but the assistant message hasn't been saved yet.
		//
		// The assistantMessageSavedToHistory flag is:
		// - Reset to false at the start of each API request
		// - Set to true after the assistant message is saved in recursivelyMakeShoferRequests
		if (!this.assistantMessageSavedToHistory) {
			await pWaitFor(() => this.assistantMessageSavedToHistory || this.abort, {
				interval: 50,
				timeout: 30_000, // 30 second timeout as safety net
			}).catch(() => {
				// If timeout or abort, log and proceed anyway to avoid hanging
				taskLog.warn(
					`[Task#${this.taskId}] flushPendingToolResultsToHistory: timed out waiting for assistant message to be saved`,
				)
			})
		}

		// If task was aborted while waiting, don't flush
		if (this.abort) {
			return false
		}

		// Save the user message with tool_result blocks
		const userMessage: Anthropic.MessageParam = {
			role: "user",
			content: this.userMessageContent,
		}

		// Validate and fix tool_result IDs when the previous *effective* message is an assistant message.
		const effectiveHistoryForValidation = getEffectiveApiHistory(this.apiConversationHistory)
		const lastEffective = effectiveHistoryForValidation[effectiveHistoryForValidation.length - 1]
		const historyForValidation = lastEffective?.role === "assistant" ? effectiveHistoryForValidation : []
		const validatedMessage = validateAndFixToolResultIds(userMessage, historyForValidation)
		const userMessageWithTs = { ...validatedMessage, ts: Date.now() }
		// §4.3: externalise oversized inline text before snapshotting to
		// history / disk. Mirrors the hook in `addToApiConversationHistory`
		// which `flushPending…` bypasses by pushing directly.
		await this.externalizeMessageContent(userMessageWithTs)
		this.apiConversationHistory.push(userMessageWithTs as ApiMessage)
		// §4.1: O(1) append rather than full rewrite. On failure, leave
		// `userMessageContent` populated so the caller can retry via
		// `retrySaveApiConversationHistory()` (which does a full rewrite).
		let saved = true
		try {
			await (await this.getPersistence()).appendApiMessage(this.taskId, userMessageWithTs as ApiMessage)
		} catch (error) {
			saved = false
			taskLog.error("Failed to append pending tool-result message:", error)
		}

		if (saved) {
			// Clear the pending content since it's now saved
			this.userMessageContent = []
		} else {
			taskLog.warn(
				`[Task#${this.taskId}] flushPendingToolResultsToHistory: save failed, retaining pending tool results in memory`,
			)
		}

		return saved
	}

	private async saveApiConversationHistory(): Promise<boolean> {
		try {
			// §5: SQLite write — cheap and incremental, so no pre-serialized JSONL
			// snapshot is needed.
			await (await this.getPersistence()).saveApiMessages(this.taskId, this.apiConversationHistory)
			return true
		} catch (error) {
			taskLog.error("Failed to save API conversation history:", error)
			return false
		}
	}

	/**
	 * Public wrapper to retry saving the API conversation history.
	 * Uses exponential backoff: up to 3 attempts with delays of 100 ms, 500 ms, 1500 ms.
	 * Used by delegation flow when flushPendingToolResultsToHistory reports failure.
	 */
	public async retrySaveApiConversationHistory(): Promise<boolean> {
		const delays = [100, 500, 1500]

		for (let attempt = 0; attempt < delays.length; attempt++) {
			await new Promise<void>((resolve) => setTimeout(resolve, delays[attempt]))
			taskLog.warn(
				`[Task#${this.taskId}] retrySaveApiConversationHistory: retry attempt ${attempt + 1}/${delays.length}`,
			)

			const success = await this.saveApiConversationHistory()

			if (success) {
				return true
			}
		}

		return false
	}

	// Shofer Messages

	public async getSavedShoferMessages(): Promise<ShoferMessage[]> {
		return (await this.getPersistence()).readTaskMessages(this.taskId)
	}

	// T1.B: tail-read helpers for cold task-switch optimisation.
	// Read only the last N messages from disk instead of the full history.
	private async getSavedShoferMessagesTail(maxMessages: number): Promise<[ShoferMessage[], boolean]> {
		return (await this.getPersistence()).readTaskMessagesTail(this.taskId, maxMessages)
	}

	private async getSavedApiConversationHistoryTail(maxMessages: number): Promise<[ApiMessage[], boolean]> {
		return (await this.getPersistence()).readApiMessagesTail(this.taskId, maxMessages)
	}

	/**
	 * `true` when `preloadShoferMessages` was called with `maxMessages` and
	 * there are older messages on disk that were not loaded. The webview
	 * renders a "Load older messages…" sentinel when this flag is set.
	 *
	 * Not persisted — resets to `false` on the next full load or when the
	 * user loads all remaining pages.
	 */
	public hasMoreShoferMessages: boolean = false

	/**
	 * Lazily-constructed BlobStore for this task. The blob directory lives
	 * under `<taskDir>/blobs/` and is removed alongside the task on delete.
	 */
	public async getBlobStore(): Promise<BlobStore> {
		if (!this._blobStore) {
			const taskDir = await getTaskDirectoryPath(this.globalStoragePath, this.taskId)
			this._blobStore = new BlobStore(taskDir)
		}
		return this._blobStore
	}

	/**
	 * Resolve the inline-content cap (bytes) for this task. Reads the
	 * `shoferBlobCapBytes` setting through ContextProxy; falls back to
	 * `DEFAULT_BLOB_CAP_BYTES` when unset or unavailable. A value of `0`
	 * disables externalisation entirely.
	 */
	public getBlobCapBytes(): number {
		const provider = this.providerRef.deref()
		const v = (
			provider as { contextProxy?: { getValue?(key: string): unknown } } | undefined
		)?.contextProxy?.getValue?.("shoferBlobCapBytes")
		return typeof v === "number" && v >= 0 ? v : DEFAULT_BLOB_CAP_BYTES
	}

	/**
	 * Maximum byte size of an MCP tool response text forwarded to the LLM.
	 * Reads the `shoferMcpMaxResponseBytes` setting through ContextProxy;
	 * falls back to 1 MiB when unset. A value of `0` disables truncation.
	 * Mirrors the constant `DEFAULT_MCP_MAX_RESPONSE_BYTES` in
	 * `core/tools/mcp/use-mcp-shared.ts` (kept in sync by tests). Inlined
	 * here to avoid a value-level circular import with `use-mcp-shared`,
	 * which already takes `Task` as a type-only import. See §4.7 of
	 * `docs/mem-utilization-profiling.md`.
	 */
	public getMcpMaxResponseBytes(): number {
		const provider = this.providerRef.deref()
		const v = (
			provider as { contextProxy?: { getValue?(key: string): unknown } } | undefined
		)?.contextProxy?.getValue?.("shoferMcpMaxResponseBytes")
		return typeof v === "number" && v >= 0 ? v : 1024 * 1024
	}

	/**
	 * Externalise any inline text in `message.content` whose UTF-8 byte
	 * length exceeds the per-task cap. Mutates the message in place so
	 * persistence and IPC see the ref-token form. Tool-result content can
	 * be a string or an array of content blocks; both shapes are handled.
	 * Errors are logged but do not propagate — losing externalisation must
	 * not break message persistence.
	 */
	public async externalizeMessageContent(message: Anthropic.MessageParam): Promise<void> {
		const cap = this.getBlobCapBytes()
		if (cap <= 0) return
		let store: BlobStore
		try {
			store = await this.getBlobStore()
		} catch (error) {
			taskLog.error("Failed to obtain BlobStore for externalisation:", error)
			return
		}
		const content = message.content as unknown
		if (typeof content === "string") {
			try {
				message.content = (await store.externalizeIfOverCap(content, cap)) as typeof message.content
			} catch (error) {
				taskLog.error("Failed to externalise message content:", error)
			}
			return
		}
		if (!Array.isArray(content)) return
		for (const block of content as Array<Record<string, unknown>>) {
			try {
				if (block?.type === "text" && typeof block.text === "string") {
					block.text = await store.externalizeIfOverCap(block.text, cap)
				} else if (block?.type === "tool_result") {
					const inner = block.content
					if (typeof inner === "string") {
						block.content = await store.externalizeIfOverCap(inner, cap)
					} else if (Array.isArray(inner)) {
						for (const part of inner as Array<Record<string, unknown>>) {
							if (part?.type === "text" && typeof part.text === "string") {
								part.text = await store.externalizeIfOverCap(part.text, cap)
							}
						}
					}
				}
			} catch (error) {
				taskLog.error("Failed to externalise content block:", error)
			}
		}
	}

	/**
	 * Resolve every `<shofer-blob .../>` reference in a list of API
	 * messages back to its full content. Operates on a deep-cloned array
	 * so the persisted `apiConversationHistory` retains its externalised
	 * form. Returns the cloned, resolved messages.
	 *
	 * Used at LLM request-build time: after sliding-window truncation has
	 * decided which messages survive, expand only those. Messages dropped
	 * by truncation pay neither the disk read nor the context-tokens cost.
	 *
	 * H14: BlobStore.resolveRefs maintains a cross-call sha256 → content
	 * cache so repeated resolutions of the same blob are O(1) in-memory
	 * lookups rather than repeated disk reads.
	 */
	public async prepareMessagesForApi(messages: Anthropic.MessageParam[]): Promise<Anthropic.MessageParam[]> {
		let store: BlobStore
		try {
			store = await this.getBlobStore()
		} catch {
			return messages
		}
		const out: Anthropic.MessageParam[] = []
		for (const message of messages) {
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			const clone: Anthropic.MessageParam = { ...message, content: message.content as any }
			const content = clone.content as unknown
			if (typeof content === "string") {
				clone.content = (await store.resolveRefs(content)) as typeof clone.content
			} else if (Array.isArray(content)) {
				// eslint-disable-next-line @typescript-eslint/no-explicit-any
				const resolvedBlocks: any[] = []
				for (const block of content as Array<Record<string, unknown>>) {
					const b: Record<string, unknown> = { ...block }
					if (b.type === "text" && typeof b.text === "string") {
						b.text = await store.resolveRefs(b.text)
					} else if (b.type === "tool_result") {
						const inner = b.content
						if (typeof inner === "string") {
							b.content = await store.resolveRefs(inner)
						} else if (Array.isArray(inner)) {
							// eslint-disable-next-line @typescript-eslint/no-explicit-any
							const innerOut: any[] = []
							for (const part of inner as Array<Record<string, unknown>>) {
								const p: Record<string, unknown> = { ...part }
								if (p.type === "text" && typeof p.text === "string") {
									p.text = await store.resolveRefs(p.text)
								}
								innerOut.push(p)
							}
							b.content = innerOut
						}
					}
					resolvedBlocks.push(b)
				}
				clone.content = resolvedBlocks as typeof clone.content
			}
			out.push(clone)
		}
		return out
	}

	private async addToShoferMessages(message: ShoferMessage) {
		// NOTE: §4.3's `ShoferMessage.text` externalisation was removed here.
		// Indiscriminately replacing `message.text` with a blob ref token
		// corrupted structured payloads — most ask/say variants (`tool`,
		// `command`, `use_mcp_server`, `api_req_started`, `completion_result`,
		// …) carry stringified JSON that ChatRow parses; the only variants
		// safely renderable through MarkdownBlock's lazy resolver are
		// `say === "text"` (assistant prose) and `say === "reasoning"`
		// (thinking). The latter additionally streams chunk-by-chunk via
		// `updateShoferMessage`, which never re-runs this externalisation
		// path, producing an inconsistent mix of inline-text and blob-ref
		// chunks. Net memory/IPC win on the webview channel was marginal
		// versus the bug surface, so the externalisation now lives only on
		// the LLM-bound `apiConversationHistory` path (see `addToApiConversationHistory`
		// and `flushPendingToolResultsToHistory`).
		this.shoferMessages.push(message)
		// Everything published or persisted from here on is a SNAPSHOT of the
		// message as it is NOW, never the live object — see `updateShoferMessage`
		// for why (both paths are deferred by at least one await, and callers
		// mutate these objects in place afterwards).
		const snapshot: ShoferMessage = { ...message }
		// §4.1: O(1) JSONL append — must happen BEFORE the debounced metadata
		// refresh so a crash between the in-memory push and the next compaction
		// does not lose the message.
		try {
			await (await this.getPersistence()).appendTaskMessage(this.taskId, snapshot)
		} catch (error) {
			taskLog.error("Failed to append Shofer message:", error)
		}
		const provider = this.providerRef.deref()
		// §4.2: Ship an incremental `shoferMessageAppended` delta instead of the
		// whole `shoferMessages` array. The webview applies the append to its
		// local copy. We still issue a skinny state push (omits both
		// `shoferMessages` and `taskHistory`) so unrelated state fields
		// (`currentTaskTodos`, `messageQueue`, `currentTaskItem`, …) that may
		// have been mutated by the call site stay in sync. taskHistory is
		// updated via `taskHistoryItemUpdated`.
		// H9: Only push to the webview when this task is the one the user sees.
		// Uses a dual check: TaskManager's focusedTaskId (set by focusTask()) OR
		// the current task on the shoferStack (set by addShoferToStack).  The
		// latter is needed because addShoferToStack does NOT call
		// taskManager.focusTask(), so focusedTaskId is null for the common
		// "new task, user is watching" case. Background tasks (other managed
		// tasks, or tasks popped from the stack) accumulate messages in-memory
		// (still persisted to disk); the webview picks them up via the full
		// postInitState on focusTask() swap.
		if (
			provider &&
			(provider.taskManager?.getFocusedTaskId() === this.taskId ||
				provider.getCurrentTask()?.taskId === this.taskId)
		) {
			await provider.postMessageToWebview({ type: "shoferMessageAppended", shoferMessage: snapshot })
		}
		// H11: maintain the token-bearing count incrementally so
		// _refreshTaskMetadata can skip the O(n) _countTokenBearingMessages walk.
		if (this._isTokenBearingMessage(message)) {
			this._tokenBearingMessageCount++
		}
		// The created-event rides the same per-task FIFO as every updated-event
		// (`_messagePublishChain`): a queued publication of an EARLIER message
		// must not land after this creation on the ShoferApi transport, where
		// consumers reconstruct streams from event order. Awaited — this method's
		// callers already await it — so the event is on the wire when it returns.
		await this.enqueueMessagePublication(() => {
			this.emit(ShoferEventName.Message, { action: "created", message: snapshot })
		})
		await this._debouncedSaveShoferMessages()
	}

	public async overwriteShoferMessages(newMessages: ShoferMessage[]) {
		this.shoferMessages = newMessages
		// H2.bis: Invalidate the token-usage cache since the entire
		// message array has been replaced (preload / restore path).
		// H11: recount from scratch (acceptable — overwrite is O(n) compaction).
		this._cachedTokenUsage = undefined
		this._tokenBearingMessageCount = this._countTokenBearingMessages()
		this._debouncedSaveShoferMessages.cancel() // prevent trailing fire of stale state
		restoreTodoListForTask(this)
		await this.saveShoferMessages()
	}

	private updateShoferMessage(message: ShoferMessage): Promise<void> {
		// What this update PUBLISHES and PERSISTS is a snapshot of the message as
		// it is right now — never the live object. Callers mutate these objects in
		// place (the partial→final transition in `ask()` is the canonical case),
		// and every consumer below is reached after at least one await: the store
		// may queue the write, and a subscriber on the ShoferApi transport
		// serializes the event at write time. Handing out the reference therefore
		// publishes whatever state the object has reached by then, not the state
		// this call was made about — which is how a finalized-but-undecided ask
		// reached controllers once per queued append and minted a pending approval
		// for each.
		const snapshot: ShoferMessage = { ...message }
		// H11: a partial→final api_req_started transition flips text from empty
		// to non-empty — this is a new token-bearing message. Check the prior
		// state by locating the existing message with the same ts. Done here at
		// call time (not in the queued publication) because it inspects
		// `shoferMessages` as they are NOW, against the live object's identity.
		if (this._isTokenBearingMessage(message)) {
			const existing = this.shoferMessages.find((m) => m.ts === message.ts && m !== message)
			if (!existing || !this._isTokenBearingMessage(existing)) {
				this._tokenBearingMessageCount++
			}
		}
		// H29: a `partial` message is mid-stream — it is re-appended on every
		// chunk and immediately superseded, so throttle those appends to at most
		// one per PARTIAL_APPEND_THROTTLE_MS. The in-memory value is already
		// canonical and the live webview gets every chunk via `messageUpdated`;
		// the throttled-out lines would only ever be read after a crash
		// mid-stream (an incomplete, non-resumable response). A finalized message
		// (`partial` false/undefined) always appends so the turn's canonical
		// value is durable even before the next compaction.
		//
		// The decision and the stamp are taken HERE, at enqueue time, so the
		// throttle measures the spacing of our intent to write rather than the
		// store's latency. Taken inside the queued publication it would compare
		// against the last COMPLETED append, so a store whose write takes longer
		// than the window — a shared backend that serializes writes per task,
		// under load — admits every subsequent chunk, and each admitted write
		// makes the next one land later still. That positive feedback disables
		// the throttle exactly when it is needed, and is what stalled a streamed
		// tool call for seconds at a time.
		const isPartial = snapshot.partial === true
		const now = Date.now()
		const shouldAppend = !isPartial || now - this._lastPartialAppendTs >= Task.PARTIAL_APPEND_THROTTLE_MS
		if (shouldAppend && isPartial) {
			this._lastPartialAppendTs = now
		}
		// FIFO per task: the publication (webview post, store append, event emit)
		// runs behind every publication enqueued before it, so consumers see
		// updates in call order — see `_messagePublishChain` for why that cannot
		// be left to the awaits at call sites. The returned promise is THIS
		// publication's completion, so a finalize path that awaits it has its
		// event on the wire before proceeding to the turn's lifecycle events.
		return this.enqueueMessagePublication(() => this.publishShoferMessageUpdate(snapshot, shouldAppend))
	}

	// publishShoferMessageUpdate is the body of one queued `updateShoferMessage`
	// publication. Only ever called through `_messagePublishChain`.
	// `shouldAppend` was decided at enqueue time (the H29 throttle in
	// `updateShoferMessage`); this body must not re-derive it from the clock.
	private async publishShoferMessageUpdate(snapshot: ShoferMessage, shouldAppend: boolean) {
		const provider = this.providerRef.deref()
		// Only push messageUpdated to the webview when this task is the one the
		// user sees — either focused via TaskManager or at the top of the
		// shoferStack.  Background tasks do not have their messages in the
		// webview's shoferMessages array (state pushes always carry the stack-
		// current task's messages), so a targeted update would land on a
		// timestamp the webview doesn't have.
		if (
			provider &&
			(provider.taskManager?.getFocusedTaskId() === this.taskId ||
				provider.getCurrentTask()?.taskId === this.taskId)
		) {
			// Never throws out of the publication: most call sites are
			// fire-and-forget, and a webview hiccup must neither surface as an
			// unhandled rejection nor stop the event emit below.
			try {
				await provider.postMessageToWebview({ type: "messageUpdated", shoferMessage: snapshot })
			} catch (error) {
				taskLog.error("Failed to post updated Shofer message to the webview:", error)
			}
		}
		// §4.1: persist the in-place mutation by appending a new JSONL line
		// with the same `ts`. `readTaskMessages` collapses duplicates so the
		// last appended copy wins while position is preserved. The next
		// compaction (turn-boundary flush) rewrites to canonical form.
		//
		// The throttled-out tail needs no trailing flush: a message's FINAL state is
		// persisted by the finalize path (`saveShoferMessages` plus the
		// unconditional `partial: false` append above), so the only lines dropped
		// are intermediate partials, read back solely after a crash mid-stream (an
		// incomplete, non-resumable response).
		if (shouldAppend) {
			try {
				await (await this.getPersistence()).appendTaskMessage(this.taskId, snapshot)
			} catch (error) {
				taskLog.error("Failed to append updated Shofer message:", error)
			}
		}
		this.emit(ShoferEventName.Message, { action: "updated", message: snapshot })
	}

	/**
	 * Embed the final submitted values of an answered followup form back onto the
	 * pending followup question message and mark it answered. Form answers arrive
	 * via an out-of-band `objectResponse` (no chat echo), so without this the
	 * persisted form would re-render editable with default values after a reload.
	 * Writing `answeredValues` lets the webview replay the form read-only with what
	 * the user entered.
	 */
	public async markFollowupFormAnswered(
		answeredValues: Record<string, string | number | boolean | string[]>,
	): Promise<void> {
		const idx = findLastIndex(this.shoferMessages, (m) => m.type === "ask" && m.ask === "followup" && !m.isAnswered)
		if (idx === -1) {
			return
		}
		const msg = this.shoferMessages[idx]!
		try {
			const payload = JSON.parse(msg.text || "{}")
			payload.answeredValues = answeredValues
			msg.text = JSON.stringify(payload)
		} catch {
			// Leave the message text untouched if it is not parseable JSON.
		}
		msg.isAnswered = true
		await this.updateShoferMessage(msg)
	}

	private async saveShoferMessages(): Promise<boolean> {
		return time("saveShoferMessages", () => this._saveShoferMessagesImpl())
	}

	private async _saveShoferMessagesImpl(): Promise<boolean> {
		try {
			// §5: individual messages are already persisted incrementally via
			// appendTaskMessage (SQLite, dedupe-by-ts), so no JSONL-style compaction
			// rewrite is needed here — just refresh the derived task metadata.
			return await this._refreshTaskMetadata()
		} catch (error) {
			taskLog.error("Failed to save Shofer messages:", error)
			return false
		}
	}

	/**
	 * Metadata-only refresh used by the debounced path.
	 *
	 * Walks `shoferMessages` for token-usage and history-item derivation,
	 * then calls `updateTaskHistory`. Does NOT write the JSONL log — that
	 * is the responsibility of `appendTaskMessage` (incremental) and
	 * `_saveShoferMessagesImpl` (compaction).
	 */
	private async _refreshTaskMetadata(): Promise<boolean> {
		try {
			if (this._taskApiConfigName === undefined) {
				await this.taskApiConfigReady
			}

			// H2.bis + H11: _tokenBearingMessageCount is maintained
			// incrementally (O(1) to read). Pass the cached TokenUsage via
			// tokenUsageOverride so taskMetadata reuses it.
			const tokenBearingCount = this._tokenBearingMessageCount
			const useCachedTokenUsage =
				this._cachedTokenUsage !== undefined && tokenBearingCount === this._tokenBearingMessageCount

			const { historyItem, tokenUsage } = await taskMetadata({
				taskId: this.taskId,
				rootTaskId: this.rootTaskId,
				parentTaskId: this.parentTaskId,
				taskNumber: this.taskNumber,
				messages: this.shoferMessages,
				globalStoragePath: this.globalStoragePath,
				workspace: this.workspacePath,
				cwd: this._cwd !== this.workspacePath ? this._cwd : undefined,
				mode: this._taskMode || defaultModeSlug,
				apiConfigName: this._taskApiConfigName,
				isBackground: this.isBackground,
				costLimit: this.costLimit,
				loadedSkills: this.loadedSkills.size > 0 ? Array.from(this.loadedSkills.keys()) : undefined,
				// When a long task is cold-loaded, `shoferMessages` is only the tail
				// window — `messages[0]` is not the originating prompt. Tell
				// taskMetadata to omit `task`/`createdAt` so the upsert merge preserves
				// the canonical first prompt instead of clobbering it with the
				// window-start `api_req_started` wire blob.
				windowedMessages: this.hasMoreShoferMessages,
				...(useCachedTokenUsage ? { tokenUsageOverride: this._cachedTokenUsage } : {}),
			})

			if (!useCachedTokenUsage) {
				this._cachedTokenUsage = tokenUsage
				this._tokenBearingMessageCount = tokenBearingCount
			}

			// Emit token/tool usage updates using debounced function
			// The debounce with maxWait ensures:
			// - Immediate first emit (leading: true)
			// - At most one emit per interval during rapid updates (maxWait)
			// - Final state is emitted when updates stop (trailing: true)
			this.debouncedEmitTokenUsage(tokenUsage, this.toolUsage)

			// Persist this task's peer-messaging grants on EVERY metadata write,
			// derived from the live `knownPeers` authority. This is what makes a
			// freshly-spawned task's HistoryItem.peerIds exist from its first save
			// (no racy post-creation write by the spawner) and keeps the grant —
			// including the parent edge — surviving restarts (rehydrated in the
			// constructor). Omitted when knownPeers is unset (root/omnipotent or
			// non-peer tasks), leaving any existing persisted peerIds untouched.
			const peerExtension =
				this.knownPeers && this.knownPeers.size > 0 ? { peerIds: Array.from(this.knownPeers) } : {}

			// Parent-locked title: re-assert `name` + `nameLocked` on every write so
			// the spawn-time title is present from the first save and the lock survives
			// restarts. `taskMetadata` never writes `name`, so this is the sole writer
			// of a locked title; when unlocked, omitted entirely, leaving the name owned
			// by `set_task_title` / the upsert-preserved default.
			const titleExtension =
				this.nameLocked && this.lockedTitle ? { name: this.lockedTitle, nameLocked: true } : {}

			await this.providerRef.deref()?.updateTaskHistory({
				...historyItem,
				...peerExtension,
				...titleExtension,
			})

			return true
		} catch (error) {
			taskLog.error("Failed to refresh task metadata:", error)
			return false
		}
	}

	/**
	 * Returns true when a message carries token-usage data.
	 * Used by H11's incremental count maintenance and as a fallback oracle
	 * for recount-on-overwrite.
	 */
	private _isTokenBearingMessage(m: ShoferMessage): boolean {
		return (
			(m.type === "say" && m.say === "api_req_started" && !!m.text) ||
			(m.type === "say" && m.say === "condense_context")
		)
	}

	/**
	 * Count messages that carry token-usage data. O(n) — only called at
	 * overwrite/restore boundaries. Hot-path refreshes use the incrementally
	 * maintained `_tokenBearingMessageCount` field (H11).
	 */
	private _countTokenBearingMessages(): number {
		let count = 0
		for (const m of this.shoferMessages) {
			if (this._isTokenBearingMessage(m)) {
				count++
			}
		}
		return count
	}

	/**
	 * Cancel any pending debounced save and persist immediately.
	 *
	 * Called at turn boundaries (ask/say completion, abort, dispose) to
	 * guarantee that persisted state matches in-memory state at every
	 * observable checkpoint, regardless of the debounce window.
	 *
	 * Idempotent: safe to call even when no debounced save is pending.
	 */
	private async _flushSaveShoferMessages(): Promise<void> {
		this._debouncedSaveShoferMessages.cancel()
		await this.saveShoferMessages()
	}

	private findMessageByTimestamp(ts: number): ShoferMessage | undefined {
		for (let i = this.shoferMessages.length - 1; i >= 0; i--) {
			if (this.shoferMessages[i]!.ts === ts) {
				return this.shoferMessages[i]
			}
		}

		return undefined
	}

	/**
	 * Tell `afterAsk` observers how an ask ended (design §6.9).
	 *
	 * Every terminal path of {@link ask} routes through here — the three
	 * auto-answer fast paths, the plugin auto-answer, the two `AskIgnoredError`
	 * unwinds, and the ordinary answered path — so a plugin sees each ask exactly
	 * once and can tell a DECISION from a mere closure. Flattening the last two
	 * into a refusal would record a "no" nobody said.
	 *
	 * Fire-and-forget, and guarded by `hasLifecycleHook` so a host with no such
	 * plugin does not allocate: the answer must never wait on an observer.
	 */
	private notifyAskResolved(
		askId: string,
		askType: ShoferAsk,
		outcome: AskResolvedInfo["outcome"],
		decision?: { response: string; decidedBy: NonNullable<AskResolvedInfo["decidedBy"]> },
	): void {
		if (!pluginRegistry.hasLifecycleHook("afterAsk")) return
		void pluginRegistry
			.notifyAfterAsk(
				{
					taskId: this.taskId,
					askId,
					askType,
					outcome,
					response: decision?.response,
					decidedBy: decision?.decidedBy,
					autoApproved: decision ? decision.decidedBy !== "user" : undefined,
				},
				{
					parentTaskId: this.parentTaskId,
					rootTaskId: this.rootTaskId,
					cwd: this.cwd,
					mode: this._taskMode,
					turn: this.turnCount,
				},
			)
			.catch(() => {})
	}

	// Note that `partial` has three valid states true (partial message),
	// false (completion of partial message), undefined (individual complete
	// message).
	async ask(
		type: ShoferAsk,
		text?: string,
		partial?: boolean,
		progressStatus?: ToolProgressStatus,
		isProtected?: boolean,
	): Promise<{ response: ShoferAskResponse; text?: string; images?: string[] }> {
		// If this Shofer instance was aborted by the provider, then the only
		// thing keeping us alive is a promise still running in the background,
		// in which case we don't want to send its result to the webview as it
		// is attached to a new instance of Shofer now. So we can safely ignore
		// the result of any active promises, and this class will be
		// deallocated. (Although we set Shofer = undefined in provider, that
		// simply removes the reference to this instance, but the instance is
		// still alive until this promise resolves or rejects.)
		if (this.abort) {
			throw new Error(`[Shofer#ask] task ${this.taskId}.${this.instanceId} aborted`)
		}

		let askTs: number
		/** UUID v7 that uniquely identifies this ask invocation. */
		const askId = uuidv7()

		// Lifecycle `beforeAsk` (design §6.9): a permitted plugin may modify the ask
		// text or auto-answer it before it is surfaced. Only for complete (non-partial)
		// asks — partial streaming chunks are not user decisions. Fast-path: with no
		// participating plugin this is fully skipped and the ask proceeds byte-for-byte
		// as before, never touching the existing approval/auto-approval flow.
		if (partial !== true && pluginRegistry.hasLifecycleHook("beforeAsk")) {
			const hookResult = await pluginRegistry.applyBeforeAsk(type, text, {
				taskId: this.taskId,
				parentTaskId: this.parentTaskId,
				rootTaskId: this.rootTaskId,
				cwd: this.cwd,
				mode: this._taskMode,
				turn: this.turnCount,
				// The host's own id for this ask, so an observer can join its record
				// of the approval to whatever surface ends up deciding it — and to the
				// matching `afterAsk`.
				askId,
			})
			if (hookResult) {
				if (typeof hookResult.text === "string") {
					// Modify the ask surfaced to the user / passed to auto-approval.
					text = hookResult.text
				}
				if (hookResult.decision === "approve" || hookResult.decision === "deny") {
					// Auto-answer: record the ask (marked auto-approved, mirroring the
					// existing auto-approval fast-path) and short-circuit the user prompt.
					const decidedTs = Date.now()
					this.lastMessageTs = decidedTs
					this._currentAskId = askId
					await this.addToShoferMessages({
						ts: decidedTs,
						type: "ask",
						ask: type,
						text,
						isProtected,
						askId,
						autoApproved: true,
						isAnswered: hookResult.decision === "approve" && type === "tool" ? true : undefined,
					})
					this._currentAskId = undefined
					this.emit(ShoferEventName.TaskAskResponded)
					const pluginResponse: ShoferAskResponse =
						hookResult.decision === "approve" ? "yesButtonClicked" : "noButtonClicked"
					this.notifyAskResolved(askId, type, "answered", {
						response: pluginResponse,
						decidedBy: "plugin",
					})
					return {
						response: pluginResponse,
						text: hookResult.text,
						images: undefined,
					}
				}
			}
		}

		// The auto-approval decision for THIS ask invocation, taken at most once.
		//
		// Every branch that publishes a complete ask has to know the decision
		// BEFORE it publishes — `autoApproved` must already be on the message that
		// reaches the webview and the ShoferApi transport, or an observer records a
		// pending approval for an ask nobody will ever be asked about (and the
		// webview flickers Accept/Reject until a later `messageUpdated` retracts
		// them). Asking twice is not merely wasteful: the second read of provider
		// state can disagree with the answer already on the wire, so the memo is
		// part of the contract, not an optimization.
		let autoApproval: CheckAutoApprovalResult | undefined
		const decideAutoApproval = async (): Promise<CheckAutoApprovalResult> => {
			if (autoApproval) {
				return autoApproval
			}
			const stateProvider = this.providerRef.deref()
			const state = stateProvider ? await stateProvider.getState() : undefined
			const decision = await checkAutoApproval({
				state: this.withTaskTrust(state),
				ask: type,
				text,
				isProtected,
			})
			// Suppress auto-approval for a background child's routed followup
			// question — it must wait for the parent agent or the user to answer,
			// not be auto-answered with the first suggestion.
			if (type === "followup" && this.isRoutedFollowupPending()) {
				decision.decision = "ask"
			}
			autoApproval = decision
			return decision
		}

		/**
		 * Close this ask with the answer auto-approval supplied, exactly as each of
		 * the three complete-message branches needs to: clear the outstanding ask,
		 * tell observers it was resolved by policy rather than by a person, and
		 * return the synthesized response to the caller.
		 */
		const resolveAutoApproved = (decision: "approve" | "deny") => {
			this._currentAskId = undefined
			this.emit(ShoferEventName.TaskAskResponded)
			const synthesized: ShoferAskResponse = decision === "approve" ? "yesButtonClicked" : "noButtonClicked"
			this.notifyAskResolved(askId, type, "answered", { response: synthesized, decidedBy: "auto-approval" })
			return { response: synthesized, text: undefined, images: undefined }
		}

		if (partial !== undefined) {
			const lastMessage = this.shoferMessages.at(-1)

			const isUpdatingPreviousPartial =
				lastMessage && lastMessage.partial && lastMessage.type === "ask" && lastMessage.ask === type

			if (partial) {
				if (isUpdatingPreviousPartial) {
					// Existing partial message, so update it.
					lastMessage.text = text
					lastMessage.partial = partial
					lastMessage.progressStatus = progressStatus
					lastMessage.isProtected = isProtected
					// TODO: Be more efficient about saving and posting only new
					// data or one whole message at a time so ignore partial for
					// saves, and only post parts of partial message instead of
					// whole array in new listener.
					this.updateShoferMessage(lastMessage)
					// console.log("Task#ask: current ask promise was ignored (#1)")
					throw new AskIgnoredError("updating existing partial")
				} else {
					// This is a new partial message, so add it with partial
					// state.
					askTs = Date.now()
					this.lastMessageTs = askTs
					await this.addToShoferMessages({ ts: askTs, type: "ask", ask: type, text, partial, isProtected })
					// console.log("Task#ask: current ask promise was ignored (#2)")
					throw new AskIgnoredError("new partial")
				}
			} else {
				if (isUpdatingPreviousPartial) {
					// This is the complete version of a previously partial
					// message, so replace the partial with the complete version.
					this.askResponse = undefined
					this.askResponseText = undefined
					this.askResponseImages = undefined

					// Bug for the history books:
					// In the webview we use the ts as the chatrow key for the
					// virtuoso list. Since we would update this ts right at the
					// end of streaming, it would cause the view to flicker. The
					// key prop has to be stable otherwise react has trouble
					// reconciling items between renders, causing unmounting and
					// remounting of components (flickering).
					// The lesson here is if you see flickering when rendering
					// lists, it's likely because the key prop is not stable.
					// So in this case we must make sure that the message ts is
					// never altered after first setting it.
					askTs = lastMessage.ts
					this.lastMessageTs = askTs
					this._currentAskId = askId

					// Decide auto-approval BEFORE this ask is persisted or published.
					// This is the branch EVERY streamed native tool call takes, so a
					// decision taken afterwards means the finalized ask reaches the
					// webview and the ShoferApi transport undecided — and a
					// controller that records asks durably (user-console's
					// `user_approvals`) opens an approval row for a decision the
					// posture had already made. Same ordering as the two
					// complete-message branches below; keep all three in sync.
					const streamedDecision = (await decideAutoApproval()).decision
					const isStreamedAutoApproved = streamedDecision === "approve" || streamedDecision === "deny"

					lastMessage.text = text
					lastMessage.partial = false
					lastMessage.progressStatus = progressStatus
					lastMessage.isProtected = isProtected
					// Carry the askId onto the finalized message so it reaches the
					// wire (the streaming partial→final path otherwise never sets it,
					// unlike the single-complete-message branch below). A controller
					// echoes it back on respondToAsk so handleWebviewAskResponse can
					// enforce it matches the current ask instead of resolving whatever
					// ask is outstanding — closing wrong-ask / double-submit races.
					lastMessage.askId = askId
					if (isStreamedAutoApproved) {
						lastMessage.autoApproved = true
						if (streamedDecision === "approve" && type === "tool") {
							lastMessage.isAnswered = true
						}
					}
					this._debouncedSaveShoferMessages.cancel()
					await this.saveShoferMessages()
					// Awaited so the finalized ask is on the wire before ask()
					// proceeds to resolve it (an auto-approval below) — a
					// controller must never learn an ask's outcome before the ask.
					await this.updateShoferMessage(lastMessage)

					if (streamedDecision === "approve" || streamedDecision === "deny") {
						return resolveAutoApproved(streamedDecision)
					}
				} else {
					// This is a new and complete message, so add it like normal.
					this.askResponse = undefined
					this.askResponseText = undefined
					this.askResponseImages = undefined
					askTs = Date.now()
					this.lastMessageTs = askTs
					this._currentAskId = askId

					// Check auto-approval BEFORE sending to the webview so the
					// `autoApproved` flag is already set on the initial message.
					// This prevents the Accept/Reject buttons from flickering
					// momentarily before the follow-up `messageUpdated` arrives.
					const quickDecision = (await decideAutoApproval()).decision
					const isAutoApproved = quickDecision === "approve" || quickDecision === "deny"
					const isAutoApprovedTool = quickDecision === "approve" && type === "tool"

					await this.addToShoferMessages({
						ts: askTs,
						type: "ask",
						ask: type,
						text,
						isProtected,
						askId,
						autoApproved: isAutoApproved || undefined,
						isAnswered: isAutoApprovedTool || undefined,
					})

					if (isAutoApproved) {
						return resolveAutoApproved(quickDecision)
					}
				}
			}
		} else {
			// This is a new non-partial message, so add it like normal.
			this.askResponse = undefined
			this.askResponseText = undefined
			this.askResponseImages = undefined
			askTs = Date.now()
			this.lastMessageTs = askTs
			this._currentAskId = askId

			// Check auto-approval BEFORE sending to the webview so the
			// `autoApproved` flag is already set on the initial message.
			// This prevents the Accept/Reject buttons from flickering
			// momentarily before the follow-up `messageUpdated` arrives.
			const quickDecision = (await decideAutoApproval()).decision
			const isAutoApproved = quickDecision === "approve" || quickDecision === "deny"
			const isAutoApprovedTool = quickDecision === "approve" && type === "tool"

			await this.addToShoferMessages({
				ts: askTs,
				type: "ask",
				ask: type,
				text,
				isProtected,
				askId,
				autoApproved: isAutoApproved || undefined,
				isAnswered: isAutoApprovedTool || undefined,
			})

			if (isAutoApproved) {
				return resolveAutoApproved(quickDecision)
			}
		}

		const timeouts: NodeJS.Timeout[] = []

		// The decision the three branches above already took and published on the
		// ask message, reused rather than re-asked. All three return as soon as it
		// is "approve"/"deny", and the fourth path (`partial: true`) throws, so by
		// construction only "ask" and "timeout" reach here — there is no fallback
		// stamping of `autoApproved` after publication, and no ask can be published
		// undecided and decided afterwards.
		const provider = this.providerRef.deref()
		const approval = await decideAutoApproval()

		// Set when the DELAYED auto-approval timer, rather than a person, supplies
		// the answer this invocation is about to return. Without it the timer's
		// answer arrives through the same `handleWebviewAskResponse` a human uses
		// and would be reported to observers as a human decision.
		let decidedByTimer = false

		if (approval.decision === "timeout") {
			// Store the auto-approval timeout so it can be cancelled if user interacts
			this.autoApprovalTimeoutRef = setTimeout(() => {
				const { askResponse, text, images } = approval.fn()
				decidedByTimer = true
				this.handleWebviewAskResponse(askResponse, text, images)
				this.autoApprovalTimeoutRef = undefined
			}, approval.timeout)
			timeouts.push(this.autoApprovalTimeoutRef)
		}

		// The state is mutable if the message is complete and the task will
		// block (via the `pWaitFor`).
		const isBlocking = !(this.askResponse !== undefined || this._currentAskId !== askId)
		const isMessageQueued = !this.messageQueueService.isEmpty()
		// Keep queued user messages intact for asks that require explicit
		// user input — the queued message should not be silently drained as
		// the answer. These ask types are either terminal flow-control
		// (command_output) or user-facing questions (followup). resume_task
		// and resume_completed_task are NOT excluded: when the user sends a
		// message while a resume ask is pending, the message should answer
		// that ask directly (this is the expected behaviour in CLI headless
		// and stdin-stream modes).
		const shouldDrainQueuedMessageForAsk = type !== "command_output" && type !== "followup"
		// State is mutable when the task will actually wait for user input.
		// Both "ask" and "timeout" decisions block waiting for input (timeout may auto-approve after delay).
		const isWaitingForInput = approval.decision === "ask" || approval.decision === "timeout"
		const isStatusMutable = !partial && isBlocking && !isMessageQueued && isWaitingForInput

		if (isStatusMutable) {
			// Emit state changes immediately. The notification guard in
			// TaskManager.onInteractive checks focusedTaskId at emit time,
			// avoiding the TOCTOU race that occurred when the delay was
			// computed synchronously but the emit fired asynchronously
			// after focus could have changed (the task may have been
			// backgrounded during the 2s window, causing the notification
			// to fire for what is now a focused task).
			//
			// The old 2s focused-task delay was meant to prevent TaskSelector
			// icon flicker from quick auto-approvals, but the auto-approval
			// fast-path in Task.ask() returns before reaching this block, so
			// the delay only applied to asks the user would definitely see.

			if (isInteractiveAsk(type)) {
				timeouts.push(
					setTimeout(() => {
						const message = this.findMessageByTimestamp(askTs)

						if (message) {
							this.interactiveAsk = message
							this.emit(ShoferEventName.TaskInteractive, this.taskId)
							provider?.postMessageToWebview({ type: "interactionRequired" })
						}
					}, 0),
				)
			} else if (isResumableAsk(type)) {
				timeouts.push(
					setTimeout(() => {
						const message = this.findMessageByTimestamp(askTs)

						if (message) {
							this.resumableAsk = message
							this.emit(ShoferEventName.TaskResumable, this.taskId)
						}
					}, 0),
				)
			} else if (isIdleAsk(type)) {
				timeouts.push(
					setTimeout(() => {
						const message = this.findMessageByTimestamp(askTs)

						if (message) {
							this.idleAsk = message

							// Error asks are terminal — emit TaskError instead of
							// TaskIdle to avoid a transient idle state before the
							// error state is set.
							const errorAskTypes: ShoferAsk[] = [
								"api_req_failed",
								"mistake_limit_reached",
								"auto_approval_max_req_reached",
							]
							if (errorAskTypes.includes(type)) {
								this.emit(ShoferEventName.TaskError, this.taskId, type)
							} else if (type !== "resume_completed_task") {
								// Re-visiting a completed task should not change
								// the managed task state.
								this.emit(ShoferEventName.TaskIdle, this.taskId)
							}
						}
					}, 0),
				)
			}
		} else if (isMessageQueued && shouldDrainQueuedMessageForAsk) {
			const message = this.messageQueueService.dequeueMessage()

			if (message) {
				this.diagLog(
					`[DIAG ask] draining queued message for ask type=${type}: text=${message.text?.substring(0, 100)}`,
				)
				// Check if this is a tool approval ask that needs to be handled.
				if (type === "tool" || type === "command" || type === "use_mcp_server") {
					// For tool approvals, we need to approve first, then send
					// the message if there's text/images.
					this.handleWebviewAskResponse("yesButtonClicked", message.text, message.images)
				} else {
					// For other ask types (like followup or command_output), fulfill the ask
					// directly.
					this.handleWebviewAskResponse("messageResponse", message.text, message.images)
				}
			}
		}

		// Wait for askResponse to be set. Mark that we are awaiting a response so that
		// handleWebviewAskResponse() knows the askResponse* slots are being consumed by
		// this invocation. The flag is cleared in finally to handle abort/throw paths.
		this.isAwaitingAskResponse = true
		try {
			await pWaitFor(
				() => {
					// Bail out as soon as the task is aborted (e.g. user clicked
					// "Send Now" via cancelAndProcessQueuedMessages, or any other
					// caller flipped this.abort). Without this check the loop
					// would keep waiting indefinitely for a webview response that
					// will never arrive, causing the Send-Now flow to hang on
					// `await this._taskLoopPromise`.
					if (this.abort) {
						return true
					}

					if (this.askResponse !== undefined || this._currentAskId !== askId) {
						return true
					}

					// If a queued message arrives while we're blocked on an ask (e.g. a follow-up
					// suggestion click that was incorrectly queued due to UI state), consume it
					// immediately so the task doesn't hang.
					if (shouldDrainQueuedMessageForAsk && !this.messageQueueService.isEmpty()) {
						const message = this.messageQueueService.dequeueMessage()
						if (message) {
							this.diagLog(
								`[DIAG ask/pWaitFor] draining queued message during wait for ask type=${type}: text=${message.text?.substring(0, 100)}`,
							)
							// If this is a tool approval ask, we need to approve first (yesButtonClicked)
							// and include any queued text/images.
							if (type === "tool" || type === "command" || type === "use_mcp_server") {
								this.handleWebviewAskResponse("yesButtonClicked", message.text, message.images)
							} else {
								this.handleWebviewAskResponse("messageResponse", message.text, message.images)
							}
						}
					}

					return false
				},
				{ interval: 100 },
			)
		} finally {
			this.isAwaitingAskResponse = false
		}

		// If pWaitFor returned because the task was aborted (rather than
		// because the user actually responded), unwind the caller so any
		// `_taskLoopPromise` awaiter (e.g. cancelAndProcessQueuedMessages)
		// can proceed. We treat this the same as a superseded ask: a
		// recoverable, expected control-flow exception.
		if (this.abort && this.askResponse === undefined && this._currentAskId === askId) {
			// Unwound, NOT decided: nothing was approved and nothing was refused.
			this.notifyAskResolved(askId, type, "aborted")
			throw new AskIgnoredError("aborted while awaiting ask response")
		}

		if (this._currentAskId !== askId) {
			// Another ask() call (or supersedePendingAsk()) cleared
			// _currentAskId or set a new one while we were waiting in
			// pWaitFor. The ask this promise represents is no longer
			// the active one — surface a clean control-flow exception so
			// the caller can unwind without corrupting state.
			this.notifyAskResolved(askId, type, "superseded")
			throw new AskIgnoredError("superseded")
		}

		const result = { response: this.askResponse!, text: this.askResponseText, images: this.askResponseImages }
		this.askResponse = undefined
		this.askResponseText = undefined
		this.askResponseImages = undefined
		this._currentAskId = undefined

		// Cancel the timeouts if they are still running.
		timeouts.forEach((timeout) => clearTimeout(timeout))

		// Switch back to an active state.
		if (this.idleAsk || this.resumableAsk || this.interactiveAsk) {
			this.idleAsk = undefined
			this.resumableAsk = undefined
			this.interactiveAsk = undefined
			this.emit(ShoferEventName.TaskActive, this.taskId)
		}

		this.emit(ShoferEventName.TaskAskResponded)
		this.notifyAskResolved(askId, type, "answered", {
			response: result.response,
			decidedBy: decidedByTimer ? "auto-approval" : "user",
		})
		return result
	}

	/**
	 * `trace` is the W3C trace context of the request that delivered this
	 * response, when the caller stated one. It is carried straight to the
	 * `onUserMessage` observers and nowhere else — core stores the two header
	 * values and never parses them.
	 */
	/**
	 * Whether this task is right now parked on the ask identified by `askId`.
	 *
	 * The addressing question a controller's answer has to settle: an ask is
	 * published with the id of the task that RAISED it, but a conversation is
	 * addressed by its ROOT task, so `respondToAsk` needs to find which live task
	 * of the tree the answer belongs to. Both halves are load-bearing —
	 * `_currentAskId` alone would match an ask already resolved, and
	 * `isAwaitingAskResponse` alone would match whatever the task is parked on now,
	 * which after a supersede is a different question than the one answered.
	 */
	public isAwaitingAsk(askId: string): boolean {
		return this.isAwaitingAskResponse && this._currentAskId === askId
	}

	handleWebviewAskResponse(
		askResponse: ShoferAskResponse,
		text?: string,
		images?: string[],
		askId?: string,
		trace?: TraceContext,
	) {
		this.diagLog(
			`[DIAG handleWebviewAskResponse] taskId=${this.taskId}.${this.instanceId}, askResponse=${askResponse}, text=${text?.substring(0, 100)}, askId=${askId}, currentAskId=${this._currentAskId}, abort=${this.abort}, abandoned=${this.abandoned}, isAwaitingAskResponse=${this.isAwaitingAskResponse}`,
		)

		// Defensive: if no ask() is currently waiting, the askResponse* slots are not
		// being consumed and would be cleared by the next ask() call, silently dropping
		// the user's input. This happens when the webview's UI state is briefly stale
		// (e.g. user types during the window between api_req_started finishing and the
		// next ask appearing, or while a tool runs between asks) and falls into the
		// bare `messageResponse` branch in ChatView.handleSendMessage.
		//
		// For messageResponse carrying text/images, route into the message queue so the
		// next ask() (or cancelAndProcessQueuedMessages) drains it. Other response kinds
		// (yes/no/objectResponse) are meaningless without a pending ask and are dropped.
		//
		// IMPORTANT (FIFO): A common cause of arriving here is `processQueuedMessages()`
		// having JUST dequeued this message and then submitting it via `submitUserMessage()`
		// — which lands here. If the surrounding state shifted in between (no ask awaiting
		// at the moment of submission), naively re-enqueuing at the BACK would place this
		// message after any messages that were queued in the same window, reversing the
		// user-visible send order. Use `prependMessage` to put it back at the FRONT.
		if (!this.isAwaitingAskResponse && !this.abort && !this.abandoned) {
			if (askResponse === "messageResponse" && (text || (images && images.length > 0))) {
				this.messageQueueService.prependMessage(text ?? "", images)
			}
			return
		}

		// Validate that the webview-supplied askId (if any) matches the
		// currently-outstanding ask. A mismatch means the user responded
		// to a stale ask (task-switch, superseded, or rapid ask churn).
		// Route the response back into the queue so it is not lost.
		if (askId !== undefined && this._currentAskId !== undefined && askId !== this._currentAskId) {
			if (askResponse === "messageResponse" && (text || (images && images.length > 0))) {
				this.messageQueueService.prependMessage(text ?? "", images)
			}
			return
		}

		// Clear any pending auto-approval timeout when user responds
		this.cancelAutoApprovalTimeout()

		this.askResponse = askResponse
		this.askResponseText = text
		this.askResponseImages = images

		if (askResponse === "messageResponse") {
			// Tell plugins the user just spoke (design §6.9). Not awaited: a plugin must
			// never sit between the user pressing send and the agent hearing it.
			void pluginRegistry
				.notifyUserMessage(
					{ taskId: this.taskId, text, imageCount: images?.length, trace },
					{
						parentTaskId: this.parentTaskId,
						rootTaskId: this.rootTaskId,
						cwd: this.cwd,
						mode: this._taskMode,
						turn: this.turnCount,
					},
				)
				.catch(() => {})
		}

		// Mark the last follow-up question as answered
		if (askResponse === "messageResponse" || askResponse === "yesButtonClicked") {
			// Find the last unanswered follow-up message using findLastIndex
			const lastFollowUpIndex = findLastIndex(
				this.shoferMessages,
				(msg) => msg.type === "ask" && msg.ask === "followup" && !msg.isAnswered,
			)

			if (lastFollowUpIndex !== -1) {
				// Mark this follow-up as answered
				this.shoferMessages[lastFollowUpIndex]!.isAnswered = true
				// Save the updated messages
				this.saveShoferMessages().catch((error) => {
					taskLog.error("Failed to save answered follow-up state:", error)
				})
			}
		}

		// Mark the last tool-approval ask as answered when user approves (or auto-approval)
		if (askResponse === "yesButtonClicked") {
			const lastToolAskIndex = findLastIndex(
				this.shoferMessages,
				(msg) => msg.type === "ask" && msg.ask === "tool" && !msg.isAnswered,
			)
			if (lastToolAskIndex !== -1) {
				this.shoferMessages[lastToolAskIndex]!.isAnswered = true
				void this.updateShoferMessage(this.shoferMessages[lastToolAskIndex]!)
				this.saveShoferMessages().catch((error) => {
					taskLog.error("Failed to save answered tool-ask state:", error)
				})
			}
		}
	}

	/**
	 * Cancel any pending auto-approval timeout.
	 * Called when user interacts (types, clicks buttons, etc.) to prevent the timeout from firing.
	 */
	public cancelAutoApprovalTimeout(): void {
		if (this.autoApprovalTimeoutRef) {
			clearTimeout(this.autoApprovalTimeoutRef)
			this.autoApprovalTimeoutRef = undefined
		}
	}

	public approveAsk({ text, images }: { text?: string; images?: string[] } = {}) {
		this.handleWebviewAskResponse("yesButtonClicked", text, images)
	}

	public denyAsk({ text, images }: { text?: string; images?: string[] } = {}) {
		this.handleWebviewAskResponse("noButtonClicked", text, images)
	}

	public supersedePendingAsk(): void {
		// Clear only the currently-outstanding ask — do NOT mutate a
		// global timestamp that would also invalidate unrelated asks
		// waiting in other concurrent invocations.
		this._currentAskId = undefined
	}

	/**
	 * Updates the API configuration and rebuilds the API handler.
	 * There is no tool-protocol switching or tool parser swapping.
	 *
	 * @param newApiConfiguration - The new API configuration to use
	 */
	public updateApiConfiguration(newApiConfiguration: ProviderSettings): void {
		// Update the configuration and rebuild the API handler
		this.apiConfiguration = newApiConfiguration
		this.api = buildApiHandler(this.apiConfiguration, {
			taskId: this.taskId,
			parentTaskId: this.parentTaskId,
			rootTaskId: this.rootTaskId,
		})
	}

	/**
	 * True when this task runs CONVERSATIONAL turns — no tools, and a complete
	 * text-only assistant reply IS the turn (see `toolCallingEnabled` in
	 * `ProviderSettings`). The task's OWN configuration is authoritative: a task
	 * may run on a per-task profile that differs from the host-global settings.
	 */
	public get toolCallingDisabled(): boolean {
		return this.apiConfiguration?.toolCallingEnabled === false
	}

	/**
	 * The provider settings the tool builder should see.
	 *
	 * The tool-build call sites read the HOST-GLOBAL settings, but whether a task
	 * has a tool plane at all is a property of the TASK. Fold this task's flag
	 * over the global one so a conversational task never receives tools just
	 * because the host default has them on.
	 */
	private toolBuildSettings(apiConfiguration: ProviderSettings | undefined): ProviderSettings | undefined {
		return this.toolCallingDisabled ? { ...(apiConfiguration ?? {}), toolCallingEnabled: false } : apiConfiguration
	}

	public async submitUserMessage(
		text: string,
		images?: string[],
		mode?: string,
		providerProfile?: string,
		trace?: TraceContext,
	): Promise<void> {
		try {
			text = (text ?? "").trim()
			images = images ?? []

			if (text.length === 0 && images.length === 0) {
				return
			}

			const provider = this.providerRef.deref()

			if (provider) {
				if (mode) {
					// Scope the mode switch to THIS task (not the focused task), so a
					// background task switching its own mode never retargets another.
					await provider.handleModeSwitch(mode, this)
				}

				if (providerProfile) {
					await provider.setProviderProfile(providerProfile)

					// Update this task's API configuration to match the new profile
					// This ensures the parser state is synchronized with the selected model
					const newState = await provider.getState()
					if (newState?.apiConfiguration) {
						this.updateApiConfiguration(newState.apiConfiguration)
					}
				}

				this.emit(ShoferEventName.TaskUserMessage, this.taskId)

				// Handle the message directly instead of routing through the webview.
				// This avoids a race condition where the webview's message state hasn't
				// hydrated yet, causing it to interpret the message as a new task request.
				this.handleWebviewAskResponse("messageResponse", text, images, undefined, trace)
			} else {
				taskLog.error("[Task#submitUserMessage] Provider reference lost")
			}
		} catch (error) {
			taskLog.error("[Task#submitUserMessage] Failed to submit user message:", error)
		}
	}

	/**
	 * Set when the user kills the current command via the inline "Abort" / Kill
	 * Command button (handleTerminalOperation("abort")). Read (and cleared) by the
	 * execute_command status emitter so the completion is reported as `"terminated"`
	 * rather than a plain `"exited"`. Not set by the user-timeout path, which emits
	 * its own `"timeout"` status.
	 */
	public userTerminatedCommand = false

	async handleTerminalOperation(terminalOperation: "continue" | "abort") {
		if (terminalOperation === "continue") {
			this.terminalProcess?.continue()
		} else if (terminalOperation === "abort") {
			this.userTerminatedCommand = true
			this.terminalProcess?.abort()
			// Also terminate any backgrounded command so the per-command Kill
			// button works after the agent has moved on from it.
			this.abortBackgroundTerminalProcesses()
		}
	}

	/**
	 * Register a command process that has been backgrounded while still running so
	 * it can be terminated later. Removed via {@link unregisterBackgroundProcess}
	 * when the command completes.
	 */
	registerBackgroundProcess(executionId: string, process: ShoferTerminalProcess) {
		this.backgroundTerminalProcesses.set(executionId, process)
	}

	unregisterBackgroundProcess(executionId: string) {
		this.backgroundTerminalProcesses.delete(executionId)
	}

	/** Abort every backgrounded command process. Each abort() escalates to a
	 * force-kill, and the command's own completion handler removes it from the map
	 * (and emits the terminated status), so we don't clear the map here. */
	private abortBackgroundTerminalProcesses() {
		for (const process of this.backgroundTerminalProcesses.values()) {
			try {
				process.abort()
			} catch (error) {
				taskLog.error(`Error aborting background terminal process for task ${this.taskId}:`, error)
			}
		}
	}

	private async getFilesReadByRooSafely(context: string): Promise<string[] | undefined> {
		try {
			return await this.fileContextTracker.getFilesReadByRoo()
		} catch (error) {
			taskLog.error(`[Task#${context}] Failed to get files read by Shofer:`, error)
			return undefined
		}
	}

	/**
	 * This task's place in the task tree, as request metadata — spread into every
	 * `ApiHandlerCreateMessageMetadata` this task builds so the agent loop, the
	 * condenser and context management all state the same thing.
	 *
	 * BOTH KEYS ARE ABSENT ON A ROOT TASK. A root has no parent and is below no
	 * root, so an empty value is omitted rather than sent: a provider forwarding
	 * this must be able to tell "no tree" from "a tree naming itself", and the
	 * task's own `HistoryItem` carries neither key on a root either.
	 */
	private taskTreeMetadata(): Pick<ApiHandlerCreateMessageMetadata, "parentTaskId" | "rootTaskId"> {
		return {
			...(this.parentTaskId ? { parentTaskId: this.parentTaskId } : {}),
			...(this.rootTaskId ? { rootTaskId: this.rootTaskId } : {}),
		}
	}

	public async condenseContext(): Promise<void> {
		// CRITICAL: Flush any pending tool results before condensing
		// to ensure tool_use/tool_result pairs are complete in history
		await this.flushPendingToolResultsToHistory()

		const systemPrompt = await this.getSystemPrompt()

		// Get condensing configuration
		const state = await this.providerRef.deref()?.getState()
		const customCondensingPrompt = state?.customSupportPrompts?.CONDENSE
		const { apiConfiguration } = state ?? {}
		// Use the task's own mode for tool building in condensing
		// so a background task sees its own mode's tools, not the
		// focused task's.
		const mode = this._taskMode || defaultModeSlug

		const { contextTokens: prevContextTokens } = this.getTokenUsage()

		// Build tools for condensing metadata (same tools used for normal API calls)
		const provider = this.providerRef.deref()
		let allTools: import("openai").default.Chat.ChatCompletionTool[] = []
		if (provider) {
			const modelInfo = this.api.getModel().info
			const toolsResult = await buildNativeToolsArrayWithRestrictions({
				provider: provider as Parameters<typeof buildNativeToolsArrayWithRestrictions>[0]["provider"],
				cwd: this.cwd,
				mode,
				customModes: state?.customModes,
				experiments: state?.experiments,
				apiConfiguration: this.toolBuildSettings(apiConfiguration),
				disabledTools: state?.disabledTools,
				modelInfo,
				includeAllToolsWithRestrictions: false,
				completionSchema: this.completionSchema,
				titleLocked: this.nameLocked,
				agentToolGroups: this.agentToolGroups,
			})
			allTools = toolsResult.tools
		}

		// Build metadata with tools and taskId for the condensing API call
		const metadata: ApiHandlerCreateMessageMetadata = {
			mode,
			taskId: this.taskId,
			...this.taskTreeMetadata(),
			...(allTools.length > 0
				? {
						tools: allTools,
						tool_choice: "auto",
						parallelToolCalls: true,
					}
				: {}),
		}
		// Generate environment details to include in the condensed summary
		const environmentDetails = await getEnvironmentDetails(this, true)

		const filesReadByRoo = await this.getFilesReadByRooSafely("condenseContext")

		const {
			messages,
			summary,
			cost,
			newContextTokens = 0,
			error,
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			errorDetails,
			condenseId,
		} = await summarizeConversation({
			messages: this.apiConversationHistory,
			apiHandler: this.api,
			systemPrompt,
			taskId: this.taskId,
			isAutomaticTrigger: false,
			customCondensingPrompt,
			metadata,
			environmentDetails,
			filesReadByRoo,
			cwd: this.cwd,
			shoferIgnoreController: this.shoferIgnoreController,
		})
		if (error) {
			await this.say(
				"condense_context_error",
				error,
				undefined /* images */,
				false /* partial */,
				undefined /* progressStatus */,
				{ isNonInteractive: true } /* options */,
			)
			return
		}
		await this.overwriteApiConversationHistory(messages)

		// Clear loaded skills BEFORE the persisting `say` below. The overwrite
		// above drops the previously-loaded skill instructions from the
		// conversation, so they must no longer count as "loaded". Clearing here
		// (rather than after the say) ensures the metadata save the say triggers
		// persists the cleared set — otherwise a crash between that save and a
		// later clear would leave history claiming a skill is loaded whose
		// instructions are gone, and the no-op guard would block reloading it.
		this.loadedSkills.clear()
		// H15: Condensation invalidates the system prompt cache (context changed).
		this._cachedSystemPromptBase = null
		this._cachedSystemPromptKey = ""

		const contextCondense: ContextCondense = {
			summary,
			cost,
			newContextTokens,
			prevContextTokens,
			condenseId: condenseId!,
		}
		await this.say(
			"condense_context",
			undefined /* text */,
			undefined /* images */,
			false /* partial */,
			undefined /* progressStatus */,
			{ isNonInteractive: true } /* options */,
			contextCondense,
		)

		// Process any queued messages after condensing completes
		this.processQueuedMessages()
	}

	async say(
		type: ShoferSay,
		text?: string,
		images?: string[],
		partial?: boolean,
		progressStatus?: ToolProgressStatus,
		options: {
			isNonInteractive?: boolean
			/**
			 * Stable identity of the streamed assistant content block. When
			 * provided, the partial → finalization handoff below locates the
			 * owning message by this id (position-independent) instead of
			 * matching `shoferMessages.at(-1)`. This is the root-cause fix for
			 * duplicate "Shofer said" bubbles: a tool_result (or any other
			 * message) appended between the streaming partial and its
			 * finalization no longer defeats the merge.
			 */
			streamBlockId?: string
			/**
			 * Payload for a `say: "plugin_marker"` row — a timeline entry a plugin
			 * appended via `ctx.task.marker(...)`. The host persists and orders it
			 * but never interprets `kind`/`data`; the owning plugin's UI component
			 * renders it.
			 */
			marker?: PluginMarkerPayload
			/**
			 * Write this message even though the task has ABORTED.
			 *
			 * The abort guard below exists to stop a terminated task appending
			 * new AGENT output — content produced after the task stopped, which
			 * nobody asked for and no consumer expects. A message that merely
			 * RECORDS work which already finished is the opposite case, and
			 * refusing it loses the record rather than preventing anything.
			 *
			 * Reserved for exactly that: today the `api_req_finished` span, whose
			 * request completed BEFORE the abort. `attempt_completion` declares
			 * the terminal state by setting `task.abort = true` as its last act
			 * (the Self-Declared Terminal State Rule), so without this the
			 * closing span of every turn threw here and the terminal request of
			 * every conversation was recorded as "started, never finished" —
			 * along with every built-in tool it ran, which that span alone
			 * accounts for.
			 *
			 * Do not reach for this to keep a tool talking after a cancel.
			 */
			allowWhenAborted?: boolean
		} = {},
		contextCondense?: ContextCondense,
		contextTruncation?: ContextTruncation,
	): Promise<undefined> {
		if (this.abort && !options.allowWhenAborted) {
			throw new Error(`[Shofer#say] task ${this.taskId}.${this.instanceId} aborted`)
		}

		if (partial !== undefined) {
			// Identity-based path: when the caller supplies a stable block id,
			// find the owning message by id anywhere in the history rather than
			// assuming it is the last entry. This keeps streaming text
			// finalization correct even when other messages were interleaved.
			const streamBlockId = options.streamBlockId
			if (streamBlockId) {
				const existingIdx = findLastIndex(this.shoferMessages, (m) => m.streamBlockId === streamBlockId)

				if (existingIdx !== -1) {
					// The message for this block already exists: update it in
					// place. We never create a second message for the same id,
					// so re-delivery and out-of-order finalization are both
					// idempotent.
					const existing = this.shoferMessages[existingIdx]!
					existing.text = text
					existing.images = images
					existing.partial = partial
					existing.progressStatus = progressStatus

					if (partial) {
						this.updateShoferMessage(existing)
					} else {
						if (!options.isNonInteractive) {
							this.lastMessageTs = existing.ts
						}
						this._debouncedSaveShoferMessages.cancel()
						await this.saveShoferMessages()
						// Awaited so the finalized message is ON THE WIRE before
						// say() resolves: the caller's next step can be the turn's
						// end (attempt_completion → TaskCompleted), and a
						// controller that stops reading at `taskCompleted` must
						// have seen the final text by then.
						await this.updateShoferMessage(existing)
					}
				} else {
					// First chunk for this block: create the message tagged with
					// its identity so later updates/finalization can find it.
					const sayTs = Date.now()

					if (!options.isNonInteractive) {
						this.lastMessageTs = sayTs
					}

					await this.addToShoferMessages({
						ts: sayTs,
						type: "say",
						say: type,
						text,
						images,
						partial: partial || undefined,
						streamBlockId,
					})
				}

				return
			}

			const lastMessage = this.shoferMessages.at(-1)

			const isUpdatingPreviousPartial =
				lastMessage && lastMessage.partial && lastMessage.type === "say" && lastMessage.say === type

			if (partial) {
				if (isUpdatingPreviousPartial) {
					// Existing partial message, so update it.
					lastMessage.text = text
					lastMessage.images = images
					lastMessage.partial = partial
					lastMessage.progressStatus = progressStatus
					this.updateShoferMessage(lastMessage)
				} else {
					// This is a new partial message, so add it with partial state.
					const sayTs = Date.now()

					if (!options.isNonInteractive) {
						this.lastMessageTs = sayTs
					}

					await this.addToShoferMessages({
						ts: sayTs,
						type: "say",
						say: type,
						text,
						images,
						partial,
						contextCondense,
						contextTruncation,
					})
				}
			} else {
				// This is the complete version of a previously partial
				// message, so replace the partial with the complete version.
				if (isUpdatingPreviousPartial) {
					if (!options.isNonInteractive) {
						this.lastMessageTs = lastMessage.ts
					}

					lastMessage.text = text
					lastMessage.images = images
					lastMessage.partial = false
					lastMessage.progressStatus = progressStatus

					// Instead of streaming partialMessage events, we do a save
					// and post like normal to persist to disk.
					this._debouncedSaveShoferMessages.cancel()
					await this.saveShoferMessages()

					// More performant than an entire `postInitState`. Awaited so
					// the finalized message is on the wire before say() resolves
					// (see the streamBlockId finalize branch above).
					await this.updateShoferMessage(lastMessage)
				} else {
					// This is a new and complete message, so add it like normal.
					// Fall through: genuinely new message.
					const sayTs = Date.now()

					if (!options.isNonInteractive) {
						this.lastMessageTs = sayTs
					}

					await this.addToShoferMessages({
						ts: sayTs,
						type: "say",
						say: type,
						text,
						images,
					})
				}
			}
		} else {
			// This is a new non-partial message, so add it like normal.
			const sayTs = Date.now()

			// A "non-interactive" message is a message is one that the user
			// does not need to respond to. We don't want these message types
			// to trigger an update to `lastMessageTs` since they can be created
			// asynchronously and could interrupt a pending ask.
			if (!options.isNonInteractive) {
				this.lastMessageTs = sayTs
			}

			await this.addToShoferMessages({
				ts: sayTs,
				type: "say",
				say: type,
				text,
				images,
				marker: options.marker,
				contextCondense,
				contextTruncation,
			})
		}
	}

	/**
	 * Finalize any tool_preparing partial row in the webview.
	 * Called whenever a tool call reaches a terminal state (started, completed,
	 * or finalized after streaming) so the preparing spinner disappears.
	 */
	private async dismissToolPreparingRow(): Promise<void> {
		const lastPreparingIndex = findLastIndex(
			this.shoferMessages,
			(m) => m.type === "say" && m.say === "tool_preparing" && m.partial === true,
		)
		if (lastPreparingIndex !== -1 && this.shoferMessages[lastPreparingIndex]!.partial) {
			this.shoferMessages[lastPreparingIndex]!.partial = false
			await this.updateShoferMessage(this.shoferMessages[lastPreparingIndex]!)
		}
	}

	/**
	 * Withdraw the streamed `ask` row a tool call leaves behind when the call is
	 * ABANDONED before it ever reaches `execute()`.
	 *
	 * A native tool renders its invocation while the arguments are still
	 * streaming — `BaseTool.handlePartial` calls `ask(type, text, true)`, which
	 * publishes an ask message with `partial: true` and NO decision on it.
	 * `checkAutoApproval` is consulted only when an ask COMPLETES, and the
	 * complete ask is raised by the tool's own `execute()`. So a call that never
	 * gets there — arguments that did not parse, a mode/tool validation refusal,
	 * a previously rejected tool — leaves that row published forever:
	 * unfinalized, undecided, and unanswerable. The posture cannot suppress it,
	 * because the posture is never asked.
	 *
	 * That remnant is not cosmetic. The abandoning paths hand the model a
	 * re-emit instruction, so ONE tool call produces one such row PER RETRY, all
	 * carrying the same (usually empty) arguments; a controller that records
	 * asks durably opens an approval per row, for a call that was never
	 * attempted. Measured on a live L2 conversation whose tool arguments kept
	 * arriving empty: 39 orphaned partial ask rows against 37 parse failures.
	 *
	 * Withdrawing is NOT deciding — nothing was approved and nothing was refused
	 * — which is why the row is marked `abandoned` rather than answered or
	 * auto-approved.
	 */
	public async withdrawStreamedToolAsk(): Promise<void> {
		const index = findLastIndex(this.shoferMessages, (m) => m.type === "ask" && m.partial === true)
		if (index === -1) {
			return
		}
		const message = this.shoferMessages[index]!
		message.partial = false
		message.abandoned = true
		await this.updateShoferMessage(message)
	}

	async sayAndCreateMissingParamError(toolName: ToolName, paramName: string, relPath?: string) {
		await this.say(
			"error",
			`Shofer tried to use ${toolName}${
				relPath ? ` for '${relPath.toPosix()}'` : ""
			} without value for required parameter '${paramName}'. Retrying...`,
		)
		return formatResponse.toolError(formatResponse.missingToolParameterError(paramName))
	}

	// Lifecycle
	// Start / Resume / Abort / Dispose

	/**
	 * Get enabled MCP tools count for this task.
	 * Returns the count along with the number of servers contributing.
	 *
	 * @returns Object with enabledToolCount and enabledServerCount
	 */
	private async getEnabledMcpToolsCount(): Promise<{ enabledToolCount: number; enabledServerCount: number }> {
		try {
			const provider = this.providerRef.deref()
			if (!provider) {
				return { enabledToolCount: 0, enabledServerCount: 0 }
			}

			const { mcpEnabled } = (await provider.getState()) ?? {}
			if (!(mcpEnabled ?? true)) {
				return { enabledToolCount: 0, enabledServerCount: 0 }
			}

			// Defensive deadline: the MCP hub factory awaits hub.waitUntilReady(),
			// which in turn awaits every server's connectToServer(). The MCP SDK does not
			// always honour a connect-time deadline (e.g. a TCP-accepting but
			// non-responsive HTTP/SSE endpoint), so a misbehaving server could otherwise
			// hang task startup indefinitely. The MCP-tool-count warning is informational
			// only, so we cap the wait and skip the warning if the hub isn't ready in time.
			// Deadline value lives in ../constants.js.
			const mcpHubFactory = getMcpHubFactory()
			const mcpHub = await Promise.race([
				mcpHubFactory ? mcpHubFactory(provider) : Promise.resolve(undefined),
				new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), MCP_READY_DEADLINE_MS)),
			])
			if (!mcpHub) {
				taskLog.warn(
					`[Task#getEnabledMcpToolsCount] MCP hub not ready within ${MCP_READY_DEADLINE_MS}ms; skipping tool-count warning`,
				)
				return { enabledToolCount: 0, enabledServerCount: 0 }
			}

			const servers = mcpHub.getServers()
			return countEnabledMcpTools(servers)
		} catch (error) {
			taskLog.error("[Task#getEnabledMcpToolsCount] Error counting MCP tools:", error)
			return { enabledToolCount: 0, enabledServerCount: 0 }
		}
	}

	/**
	 * Manually start a **new** task when it was created with `startTask: false`.
	 *
	 * This fires `startTask` as a background async operation for the
	 * `task/images` code-path only.  It does **not** handle the
	 * `historyItem` resume path (use the constructor with `startTask: true`
	 * for that).  The primary use-case is in the delegation flow where the
	 * parent's metadata must be persisted to globalState **before** the
	 * child task begins writing its own history (avoiding a read-modify-write
	 * race on globalState).
	 */
	public start(): void {
		if (this._started) {
			return
		}
		this._started = true

		const { task, images } = this.metadata

		if (task || images) {
			this.startTask(task ?? undefined, images ?? undefined)
		}
	}

	private async startTask(task?: string, images?: string[]): Promise<void> {
		// Lifecycle `beforeTaskStart` observer (design §6.9). Owner decision: kept off
		// the latency-critical path — fired non-blocking (not awaited) and timeout-guarded
		// inside the registry, so a plugin can never delay or block task start. No-op when
		// no permitted plugin declares it.
		void pluginRegistry
			.notifyBeforeTaskStart({
				taskId: this.taskId,
				parentTaskId: this.parentTaskId,
				rootTaskId: this.rootTaskId,
				cwd: this.cwd,
				mode: this._taskMode,
				prompt: task,
				// The one point at which the causal chain across the process boundary
				// is still recoverable: the request that asked for this task has
				// already returned by the time the loop is running.
				trace: this.trace,
			})
			.catch(() => {})

		try {
			// `conversationHistory` (for API) and `shoferMessages` (for webview)
			// need to be in sync.
			// If the extension process were killed, then on restart the
			// `shoferMessages` might not be empty, so we need to set it to [] when
			// we create a new Shofer client (otherwise webview would show stale
			// messages from previous session).
			this.shoferMessages = []
			this.apiConversationHistory = []

			// The todo list is already set in the constructor if initialTodos were provided
			// No need to add any messages - the todoList property is already set

			await this.say("text", task, images)
			this._messagesReadyResolve()

			// Check for too many MCP tools and warn the user
			const { enabledToolCount, enabledServerCount } = await this.getEnabledMcpToolsCount()
			if (enabledToolCount > MAX_MCP_TOOLS_THRESHOLD) {
				await this.say(
					"too_many_tools_warning",
					JSON.stringify({
						toolCount: enabledToolCount,
						serverCount: enabledServerCount,
						threshold: MAX_MCP_TOOLS_THRESHOLD,
					}),
					undefined,
					undefined,
					undefined,
					{ isNonInteractive: true },
				)
			}
			this.isInitialized = true

			const imageBlocks: Anthropic.ImageBlockParam[] = formatResponse.imageBlocks(images)

			// Task starting. `String(task)` rather than `task ?? ""`: an
			// image-only start has always put the literal "undefined" inside the
			// wrapper, and that text is part of the prompt the model reads.
			await this._runTaskLoop([humanMessageBlock(String(task)), ...imageBlocks]).catch((error) => {
				// Swallow loop rejection when the task was intentionally abandoned/aborted
				// during delegation or user cancellation to prevent unhandled rejections.
				if (this.abandoned === true || this.abortReason === "user_cancelled") {
					return
				}
				throw error
			})
		} catch (error) {
			// In tests and some UX flows, tasks can be aborted while `startTask` is still
			// initializing. Treat abort/abandon as expected and avoid unhandled rejections.
			if (this.abandoned === true || this.abort === true || this.abortReason === "user_cancelled") {
				return
			}
			throw error
		}
	}

	/**
	 * Load and sanitize this task's persisted `shoferMessages` and
	 * `apiConversationHistory` from disk into memory, idempotently.
	 *
	 * MUST be called by `createTaskWithHistoryItem` BEFORE the task is pushed
	 * onto `shoferStack` (i.e. before it becomes `getCurrentTask()`), so that
	 * any concurrent `postInitState()` triggered during the rehydration
	 * window (e.g. a background task's `addToShoferMessages`, or an unrelated
	 * webview round-trip) reads a non-empty `shoferMessages` and the home
	 * screen never wins a render.
	 *
	 * Idempotent: safe to call multiple times; only the first call performs
	 * I/O. `resumeTaskFromHistory()` checks the same `historyPreloaded` flag
	 * and skips its own load prefix when this has already run.
	 */
	public async preloadShoferMessages(maxMessages?: number): Promise<void> {
		return time("preloadShoferMessages", () => this._preloadShoferMessagesImpl(maxMessages))
	}

	private async _preloadShoferMessagesImpl(maxMessages?: number): Promise<void> {
		if (this.historyPreloaded) {
			return
		}

		// H1 + T1.B: Issue both disk reads concurrently. They touch independent
		// files. When `maxMessages` is set, use the tail reader for shoferMessages
		// (UI) only — apiConversationHistory is re-read fully by
		// resumeTaskFromHistory before any LLM request, so tail-reading it here
		// is wasted overhead.
		const tailMode = typeof maxMessages === "number" && maxMessages > 0
		const [rawShofer, apiConversationHistory] = await Promise.all([
			tailMode
				? this.getSavedShoferMessagesTail(maxMessages)
				: this.getSavedShoferMessages().then((m) => [m, false] as const),
			this.getSavedApiConversationHistory(),
		])

		const [modifiedShoferMessages, hasMoreUi] = rawShofer
		this.hasMoreShoferMessages = hasMoreUi

		// Remove any resume messages that may have been added before.
		const lastRelevantMessageIndex = findLastIndex(
			modifiedShoferMessages,
			(m) => !(m.ask === "resume_task" || m.ask === "resume_completed_task"),
		)

		if (lastRelevantMessageIndex !== -1) {
			modifiedShoferMessages.splice(lastRelevantMessageIndex + 1)
		}

		// Remove any trailing reasoning-only UI messages that were not part of the persisted API conversation
		while (modifiedShoferMessages.length > 0) {
			const last = modifiedShoferMessages[modifiedShoferMessages.length - 1]!
			if (last.type === "say" && last.say === "reasoning") {
				modifiedShoferMessages.pop()
			} else {
				break
			}
		}

		// Since we don't use `api_req_finished` anymore, we need to check if the
		// last `api_req_started` has a cost value, if it doesn't and no
		// cancellation reason to present, then we remove it since it indicates
		// an api request without any partial content streamed.
		const lastApiReqStartedIndex = findLastIndex(
			modifiedShoferMessages,
			(m) => m.type === "say" && m.say === "api_req_started",
		)

		if (lastApiReqStartedIndex !== -1) {
			const lastApiReqStarted = modifiedShoferMessages[lastApiReqStartedIndex]!
			const { cost, cancelReason }: ShoferApiReqInfo = JSON.parse(lastApiReqStarted.text || "{}")

			if (cost === undefined && cancelReason === undefined) {
				modifiedShoferMessages.splice(lastApiReqStartedIndex, 1)
			}
		}

		// H3: Publish in-memory state immediately from the sanitized array.
		// The previous code did overwriteShoferMessages → getSavedShoferMessages,
		// re-reading the same file we just wrote so that the in-memory copy
		// would match the parsed-back form (timestamps, undefined elision,
		// etc.). Since sanitization here is pure JS that only removes
		// elements, the in-memory array is already byte-equivalent to what
		// the round-trip would yield, so we can skip the read.
		this.shoferMessages = modifiedShoferMessages
		this.apiConversationHistory = apiConversationHistory
		this.historyPreloaded = true
		this._messagesReadyResolve()

		// T1.B: When tail-loading, skip the background compaction write.
		// The in-memory array is a window, not the full history — rewriting
		// from it would lose older messages. The JSONL log is already compact
		// (last turn boundary flush compacted it), so this skip is safe and
		// avoids unnecessary I/O on the cold-switch path.
		if (!tailMode) {
			void this.overwriteShoferMessages(modifiedShoferMessages).catch((err) => {
				taskLog.warn(`preloadShoferMessages: background sanitized save failed: ${err}`)
			})
		}
	}

	/**
	 * Public entry point for callers that constructed a Task with
	 * `startTask: false`, preloaded its messages via `preloadShoferMessages()`,
	 * pushed it onto the stack, and now want to drive the resume turn
	 * (present the resume_task ask, run the loop on user response).
	 *
	 * Mirrors the historyItem branch of the constructor's start-on-construct
	 * logic. Idempotent: subsequent calls are no-ops.
	 */
	public startFromHistory(): void {
		if (this._started) {
			return
		}
		this._started = true
		void this.resumeTaskFromHistory()
	}

	private async resumeTaskFromHistory() {
		try {
			if (!this.historyPreloaded) {
				await this.preloadShoferMessages()
			}

			// Rebuild the in-memory backgroundChildren map from persisted history.
			// After a process restart the map is empty (it is never serialized),
			// which would cause check_task_status / cancel_tasks to reject the
			// parent's own children with
			// "Task not found". Idempotent and safe when the map is already populated.
			await this.rehydrateBackgroundChildren()

			const lastShoferMessage = this.shoferMessages
				.slice()
				.reverse()
				.find((m) => !(m.ask === "resume_task" || m.ask === "resume_completed_task")) // Could be multiple resume tasks.

			let askType: ShoferAsk
			if (this.initialState?.lifecycle === "completed" || lastShoferMessage?.ask === "completion_result") {
				askType = "resume_completed_task"
			} else {
				askType = "resume_task"
			}

			this.isInitialized = true

			// A QUEUED MESSAGE IS THE RESUMPTION — do not ask whether to resume.
			//
			// `Task.ask()` would drain the queue to answer this ask, and that is
			// still the right behaviour for a message that arrives while the ask is
			// outstanding. But it drains only AFTER `addToShoferMessages` has
			// published the ask, so the ask is already on the message stream and
			// already dispatched: a headless node's ask dispatcher prints it, spends
			// the `--retry` budget and declines it, before the drain runs. Answering
			// it a moment later makes that harmless but not free — the published ask
			// costs a persist, a `postStateToWebview`, a `getState()` for the
			// auto-approval decision and a `pWaitFor` round trip, on the
			// latency-critical first hop of every follow-up turn in a live
			// conversation.
			//
			// So when the message is ALREADY there at rehydration time, take it as
			// the answer directly and raise nothing. This is what a caller
			// rehydrating a task expressly to deliver a message wants, and it is
			// exactly what the drain would have synthesised.
			const queuedResumption = this.messageQueueService.isEmpty()
				? undefined
				: this.messageQueueService.dequeueMessage()

			let response: ShoferAskResponse
			let text: string | undefined
			let images: string[] | undefined

			if (queuedResumption) {
				this.diagLog(
					`[DIAG resumeTaskFromHistory] queued message answers the resume; skipping ask(${askType}), taskId=${this.taskId}.${this.instanceId}`,
				)
				response = "messageResponse"
				text = queuedResumption.text
				images = queuedResumption.images
				// The queued message IS this turn's user message, and taking it as the
				// resumption bypasses `handleWebviewAskResponse` — the one place that
				// tells `onUserMessage` observers the user spoke. Announce it here, or
				// a plugin sees a user message on the warm path and NOTHING on the
				// cold one, which is every follow-up turn of a rehydrated
				// conversation. `this.trace` is the context the caller delivering it
				// stated (see `TaskOptions.trace`).
				void pluginRegistry
					.notifyUserMessage(
						{ taskId: this.taskId, text, imageCount: images?.length, trace: this.trace },
						{
							parentTaskId: this.parentTaskId,
							rootTaskId: this.rootTaskId,
							cwd: this.cwd,
							mode: this._taskMode,
							turn: this.turnCount,
						},
					)
					.catch(() => {})
			} else {
				this.diagLog(
					`[DIAG resumeTaskFromHistory] about to ask(${askType}), taskId=${this.taskId}.${this.instanceId}, queueSize=${this.messageQueueService.messages.length}`,
				)
				;({ response, text, images } = await this.ask(askType)) // Calls `postInitState`.
				this.diagLog(
					`[DIAG resumeTaskFromHistory] ask returned: response=${response}, text=${text?.substring(0, 100)}, hasImages=${!!(images && images.length > 0)}`,
				)
			}

			let responseText: string | undefined
			let responseImages: string[] | undefined

			// Handle user feedback for both messageResponse and yesButtonClicked with text.
			// When user types a message and clicks "Resume", the response is yesButtonClicked
			// but the text should still be captured as user feedback.
			if (
				response === "messageResponse" ||
				(response === "yesButtonClicked" && (text || (images && images.length > 0)))
			) {
				await this.say("user_feedback", text, images)
				responseText = text
				responseImages = images
			}

			// Make sure that the api conversation history can be resumed by the API,
			// even if it goes out of sync with shofer messages.
			const existingApiConversationHistory: ApiMessage[] = await this.getSavedApiConversationHistory()

			// Tool blocks are always preserved; native tool calling only.

			// if the last message is an assistant message, we need to check if there's tool use since every tool use has to have a tool response
			// if there's no tool use and only a text block, then we can just add a user message
			// (note this isn't relevant anymore since we use custom tool prompts instead of tool use blocks, but this is here for legacy purposes in case users resume old tasks)

			// if the last message is a user message, we can need to get the assistant message before it to see if it made tool calls, and if so, fill in the remaining tool responses with 'interrupted'

			let modifiedOldUserContent: Anthropic.Messages.ContentBlockParam[] // either the last message if its user message, or the user message before the last (assistant) message
			let modifiedApiConversationHistory: ApiMessage[] // need to remove the last user message to replace with new modified user message
			if (existingApiConversationHistory.length > 0) {
				const lastMessage = existingApiConversationHistory[existingApiConversationHistory.length - 1]!

				if (lastMessage.isSummary) {
					// IMPORTANT: If the last message is a condensation summary, we must preserve it
					// intact. The summary message carries critical metadata (isSummary, condenseId)
					// that getEffectiveApiHistory() uses to filter out condensed messages.
					// Removing or merging it would destroy this metadata, causing all condensed
					// messages to become "orphaned" and restored to active status — effectively
					// undoing the condensation and sending the full history to the API.
					// See: https://github.com/shofer-dev/shofer/issues/11487
					modifiedApiConversationHistory = [...existingApiConversationHistory]
					modifiedOldUserContent = []
				} else if (lastMessage.role === "assistant") {
					const content = Array.isArray(lastMessage.content)
						? lastMessage.content
						: [{ type: "text", text: lastMessage.content }]
					const hasToolUse = content.some((block) => block.type === "tool_use")

					if (hasToolUse) {
						const toolUseBlocks = content.filter(
							(block) => block.type === "tool_use",
						) as Anthropic.Messages.ToolUseBlock[]
						const toolResponses: Anthropic.ToolResultBlockParam[] = toolUseBlocks.map((block) => ({
							type: "tool_result",
							tool_use_id: block.id,
							content: "Task was interrupted before this tool call could be completed.",
						}))
						modifiedApiConversationHistory = [...existingApiConversationHistory] // no changes
						modifiedOldUserContent = [...toolResponses]
					} else {
						modifiedApiConversationHistory = [...existingApiConversationHistory]
						modifiedOldUserContent = []
					}
				} else if (lastMessage.role === "user") {
					const previousAssistantMessage: ApiMessage | undefined =
						existingApiConversationHistory[existingApiConversationHistory.length - 2]

					const existingUserContent: Anthropic.Messages.ContentBlockParam[] = Array.isArray(
						lastMessage.content,
					)
						? lastMessage.content
						: [{ type: "text", text: lastMessage.content }]
					if (previousAssistantMessage && previousAssistantMessage.role === "assistant") {
						const assistantContent = Array.isArray(previousAssistantMessage.content)
							? previousAssistantMessage.content
							: [{ type: "text", text: previousAssistantMessage.content }]

						const toolUseBlocks = assistantContent.filter(
							(block) => block.type === "tool_use",
						) as Anthropic.Messages.ToolUseBlock[]

						if (toolUseBlocks.length > 0) {
							const existingToolResults = existingUserContent.filter(
								(block) => block.type === "tool_result",
							) as Anthropic.ToolResultBlockParam[]

							const missingToolResponses: Anthropic.ToolResultBlockParam[] = toolUseBlocks
								.filter(
									(toolUse) =>
										!existingToolResults.some((result) => result.tool_use_id === toolUse.id),
								)
								.map((toolUse) => ({
									type: "tool_result",
									tool_use_id: toolUse.id,
									content: "Task was interrupted before this tool call could be completed.",
								}))

							modifiedApiConversationHistory = existingApiConversationHistory.slice(0, -1) // removes the last user message
							modifiedOldUserContent = [...existingUserContent, ...missingToolResponses]
						} else {
							modifiedApiConversationHistory = existingApiConversationHistory.slice(0, -1)
							modifiedOldUserContent = [...existingUserContent]
						}
					} else {
						modifiedApiConversationHistory = existingApiConversationHistory.slice(0, -1)
						modifiedOldUserContent = [...existingUserContent]
					}
				} else {
					throw new Error("Unexpected: Last message is not a user or assistant message")
				}
			} else {
				throw new Error("Unexpected: No existing API conversation history")
			}

			if (responseText) {
				// When the user provides a new message after stopping, send the
				// interrupted tool_results and the user's new text as SEPARATE
				// role=user messages. This ensures the model sees the user's
				// redirect as a distinct instruction rather than a footnote
				// buried in the same message as tool_result blocks.

				// 1. Close out the interrupted tool calls in the API history
				if (modifiedOldUserContent.length > 0) {
					modifiedApiConversationHistory.push({
						role: "user",
						content: modifiedOldUserContent,
					})
					// The API requires alternating user/assistant messages,
					// so insert a brief assistant acknowledgment.
					modifiedApiConversationHistory.push({
						role: "assistant",
						content: [
							{
								type: "text",
								text: "[The user interrupted the previous action. Awaiting new instructions.]",
							},
						],
					})
				}

				// 2. The user's actual text will be sent as its own role=user
				//    message by initiateTaskLoop → recursivelyMakeShoferRequests.
				const userContent: Anthropic.Messages.ContentBlockParam[] = [humanMessageBlock(responseText)]

				if (responseImages && responseImages.length > 0) {
					userContent.push(...formatResponse.imageBlocks(responseImages))
				}

				this.diagLog(
					`[DIAG resumeTaskFromHistory] split messages: toolResults=${modifiedOldUserContent.length} blocks in history, userContent=${userContent.length} blocks for initiateTaskLoop`,
				)

				await this.overwriteApiConversationHistory(modifiedApiConversationHistory)
				await this._runTaskLoop(userContent)
			} else {
				// No user redirect — just resume with tool_results + environment
				const newUserContent: Anthropic.Messages.ContentBlockParam[] = [...modifiedOldUserContent]

				if (responseImages && responseImages.length > 0) {
					newUserContent.push(...formatResponse.imageBlocks(responseImages))
				}

				// Ensure we have at least some content to send to the API.
				if (newUserContent.length === 0) {
					newUserContent.push({
						type: "text",
						text: "[TASK RESUMPTION] Resuming task...",
					})
				}

				this.diagLog(
					`[DIAG resumeTaskFromHistory] newUserContent blocks=${newUserContent.length}, types=${newUserContent.map((b) => b.type).join(",")}, texts=${newUserContent
						.filter((b) => b.type === "text")
						// eslint-disable-next-line @typescript-eslint/no-explicit-any
						.map((b) => (b as any).text?.substring(0, 80))
						.join(" | ")}`,
				)

				await this.overwriteApiConversationHistory(modifiedApiConversationHistory)
				await this._runTaskLoop(newUserContent)
			}
		} catch (error) {
			// Ensure `messagesReady` is always resolved to unblock
			// `createTaskWithHistoryItem` so it doesn't hang forever.
			this._messagesReadyResolve()

			// Resume and cancellation can race when users issue repeated cancels.
			// Treat intentional abort/abandon flows as expected and avoid process-level crashes.
			if (this.abandoned === true || this.abort === true || this.abortReason === "user_cancelled") {
				return
			}
			throw error
		}
	}

	/**
	 * Cancels the current HTTP request if one is in progress.
	 * This immediately aborts the underlying stream rather than waiting for the next chunk.
	 */
	public cancelCurrentRequest(): void {
		if (this.currentRequestAbortController) {
			taskLog.info(`[Task#${this.taskId}.${this.instanceId}] Aborting current HTTP request`)
			this.currentRequestAbortController.abort()
			this.currentRequestAbortController = undefined
		}
	}

	/**
	 * Force emit a final token usage update, ignoring throttle.
	 * Called before task completion or abort to ensure final stats are captured.
	 * Triggers the debounce with current values and immediately flushes to ensure emit.
	 */
	public emitFinalTokenUsageUpdate(): void {
		const tokenUsage = this.getTokenUsage()
		this.debouncedEmitTokenUsage(tokenUsage, this.toolUsage)
		this.debouncedEmitTokenUsage.flush()
	}

	/**
	 * Abort all background children tracked by this task.
	 *
	 * Each live child found via TaskManager is aborted (fire-and-forget in
	 * parallel) and the in-memory handle map is cleared.  Already-terminated
	 * children whose handle was already `completed` or `error` are no-ops.
	 *
	 * This is the single choke-point for child cleanup — called from both
	 * `abortTask()` (user stop / forced abort) and `AttemptCompletionTool`
	 * (normal parent completion).
	 */
	public async abortBackgroundChildren(clearHandles = true): Promise<void> {
		if (this.backgroundChildren.size === 0) return

		const provider = this.providerRef.deref()
		if (!provider) return

		await Promise.all(
			Array.from(this.backgroundChildren.keys()).map(async (childId) => {
				try {
					const child = provider.taskManager.getManagedTaskInstance(childId)
					if (child) {
						await child.abortTask(false)
					}
				} catch (err) {
					taskLog.error(`[Task#abortBackgroundChildren] Failed to abort child ${childId}:`, err)
				}
			}),
		)

		if (clearHandles) {
			this.backgroundChildren.clear()
		}
	}

	/**
	 * True when this task was spawned as a child of another task.
	 *
	 * It is redundant with `parentTaskId` for any task this code can construct —
	 * `new_task` is the only thing that sets a parent, and every child it makes is
	 * concurrent. It survives because it is the flag the PERSISTED row carries
	 * (`HistoryItem.isBackground`), which is what `rehydrateBackgroundChildren`,
	 * `check_task_status` and `cancel_tasks` filter a history scan on when there
	 * is no live instance to ask.
	 */
	public get isBackgroundTask(): boolean {
		return this.isBackground
	}

	/** The question this child forwarded to its parent, while it is still parked on it. */
	public get forwardedQuestion(): { envelopeId: string; question: string } | undefined {
		return this._forwardedQuestion
	}

	/** Record the question this child just forwarded to its parent. */
	public setForwardedQuestion(info: { envelopeId: string; question: string }): void {
		this._forwardedQuestion = info
	}

	/** Forget the forwarded question — answered by either channel, expired, or aborted. */
	public clearForwardedQuestion(): void {
		this._forwardedQuestion = undefined
	}

	/**
	 * Answer the question this child forwarded, if `envelopeId` is the request it
	 * is actually parked on.
	 *
	 * This is how a parent's `reply` reaches a child that is parked on an ASK
	 * rather than on its mailbox: the answer goes through the same
	 * `handleWebviewAskResponse` path the webview uses, which no-ops when the ask
	 * has already been answered — so a human who answered in the child's chat
	 * first simply wins.
	 *
	 * @returns true when this child was parked on that request.
	 */
	public answerForwardedQuestion(envelopeId: string, answer: string): boolean {
		if (this._forwardedQuestion?.envelopeId !== envelopeId) {
			return false
		}
		this.handleWebviewAskResponse("messageResponse", answer)
		return true
	}

	/**
	 * True when this task has a question outstanding that it FORWARDED to its
	 * parent — awaiting an answer from either the parent agent or a human in this
	 * task's own chat.
	 *
	 * Used by `task.ask()` to suppress the `followup` auto-approval timeout for
	 * such a question: it must NOT be auto-answered with the first suggestion,
	 * because it is directed at the parent (or a human), not at an auto-approval
	 * policy.
	 */
	private isRoutedFollowupPending(): boolean {
		return !!this.parentTaskId && this._forwardedQuestion !== undefined
	}

	public async abortTask(isAbandoned = false) {
		// Aborting task

		// Flush the in-flight API request span before teardown. The terminal
		// attempt_completion turn disposes the task before the normal post-tools
		// emit point, so without this its request (and the attempt_completion
		// tool span) would be missing from the Trace/Stats. Idempotent via the
		// needs-emit guard, so this is a no-op if the request already emitted.
		if (this._pendingApiReqNeedsEmit) {
			const completed = this.didExecuteAttemptCompletion
			// Best effort: this is a BACKSTOP for a request the normal emit
			// points missed, and tear-down must finish either way. A store that
			// refuses the write must not leave the task half-aborted.
			await this.emitApiReqFinished(
				completed ? "completed" : "cancelled",
				completed ? undefined : "user_cancelled",
			).catch((error) => {
				taskLog.error("Failed to flush the in-flight api_req_finished span on abort:", error)
			})
		}

		// If this task was parked on a question it forwarded to its parent, forget
		// it now. The blocking itself is `task.ask("followup", …)`, whose
		// `pWaitFor` already checks `this.abort` and unwinds via
		// `AskIgnoredError` — so no promise rejection is needed here.
		this.clearForwardedQuestion()

		// Abort all background children before aborting self (Decision: abort propagation).
		await this.abortBackgroundChildren()

		// Abort in-flight async MCP tool calls (inline, mirrors backgroundChildren cleanup above).
		if (this.mcpAsyncCalls.size > 0) {
			for (const handle of this.mcpAsyncCalls.values()) {
				if (handle.status === "running") {
					handle.abortController.abort()
					handle.status = "cancelled"
					TelemetryService.instance.captureMcpAsyncCallCancelled(this.taskId, {
						callId: handle.callId,
						serverName: handle.serverName,
						toolName: handle.toolName,
						durationMs: Date.now() - handle.createdAt,
					})
				}
			}
			this.mcpAsyncCalls.clear()
		}

		// Will stop any autonomously running promises.
		if (isAbandoned) {
			this.abandoned = true
		}

		this.abort = true

		// Signal any subscribers (e.g. in-flight MCP tool calls) that the task
		// has been aborted so they can short-circuit instead of waiting for
		// their own timeouts.
		if (!this._taskAbortController.signal.aborted) {
			this._taskAbortController.abort()
		}

		// Abort any running terminal process (e.g., from execute_command)
		// so the Global Stop button kills the process instead of leaving
		// it orphaned after the task loop exits. Covers both the foreground
		// command and any commands the agent backgrounded while still running.
		this.terminalProcess?.abort()
		this.abortBackgroundTerminalProcesses()
		this.backgroundTerminalProcesses.clear()

		// Reset consecutive error counters on abort (manual intervention)
		this.consecutiveNoToolUseCount = 0
		this.consecutiveNoAssistantMessagesCount = 0

		// Force final token usage update before abort event
		this.emitFinalTokenUsageUpdate()

		// Derive abort reason: completed (post-attempt_completion cleanup),
		// error (streaming failure), user (somebody asked for this), or abandoned
		// (force-abandoned).
		//
		// `user_cancelled` is checked BEFORE `abandoned` on purpose. The cancel
		// path also sets `abandoned` — as an internal stop signal, so residual
		// loops exit — but the two say opposite things on the wire: `user` means
		// a person ended this deliberately, `abandoned` means the host discarded
		// the instance out from under whoever was waiting. A controller acts on
		// that difference (one is a normal end, the other is a lost turn to
		// report), so the deliberate act must win the classification.
		const abortReasonValue: "user" | "completed" | "error" | "abandoned" =
			this.completedTerminalState || this.didExecuteAttemptCompletion
				? "completed"
				: this.abortReason === "streaming_failed"
					? "error"
					: this.abortReason === "user_cancelled"
						? "user"
						: this.abandoned
							? "abandoned"
							: "user"

		// A task that already completed is TORN DOWN here, not aborted, so no
		// `TaskAborted` is announced for it. The event is a terminal signal to
		// every consumer that receives it — a controller ends the turn on it, the
		// CLI ends the run, evals score it as a failure — and "the completed
		// instance was later discarded" is not that. It is precisely what a
		// follow-up message does: `sendMessage` on a finished task rehydrates it,
		// and rehydration aborts the old instance, so announcing this abort made
		// every multi-turn conversation look like it ended mid-turn.
		//
		// Nothing downstream loses information: `TaskManager.onAborted` already
		// no-ops on `reason: "completed"`, and the plugin `afterTaskComplete`
		// notification below still fires with the completed reason.
		if (abortReasonValue !== "completed") {
			this.emit(ShoferEventName.TaskAborted, { reason: abortReasonValue })
		}

		// Lifecycle `afterTaskComplete` observer (design §6.9). This is the single task
		// teardown site — it fires both for a normal completion (post-attempt_completion
		// cleanup, `abortReasonValue === "completed"`) and for a genuine abort. Fired
		// non-blocking + timeout-guarded so an observer can never delay teardown. No-op
		// when no permitted plugin declares it.
		void pluginRegistry
			.notifyAfterTaskComplete({
				taskId: this.taskId,
				parentTaskId: this.parentTaskId,
				rootTaskId: this.rootTaskId,
				cwd: this.cwd,
				mode: this._taskMode,
				turn: this.turnCount,
				reason: abortReasonValue === "completed" ? "completed" : "aborted",
			})
			.catch(() => {})

		try {
			this.dispose() // Call the centralized dispose method
		} catch (error) {
			taskLog.error(`Error during task ${this.taskId}.${this.instanceId} disposal:`, error)
			// Don't rethrow - we want abort to always succeed
		}
		// Save the countdown message in the automatic retry or other content.
		try {
			// Save the countdown message in the automatic retry or other content.
			await this._flushSaveShoferMessages()
		} catch (error) {
			taskLog.error(`Error saving messages during abort for task ${this.taskId}.${this.instanceId}:`, error)
		}
	}

	/**
	 * Walk up the parent chain to the true root and return its costLimit.
	 * Subtasks never carry their own; only roots do.
	 */
	private resolveCostLimit(): { root: Task; limit: CostLimit | undefined } {
		// eslint-disable-next-line @typescript-eslint/no-this-alias -- walking up the parentTask chain requires a mutable cursor
		let cursor: Task = this
		while (cursor.parentTask) {
			cursor = cursor.parentTask
		}
		return { root: cursor, limit: cursor.costLimit }
	}

	/**
	 * Public hook so the webview can invalidate the per-request cost cache
	 * after the user updates the limit live (e.g. via TaskHeader's editor).
	 * Without this the running stream would still apply the stale cached spent
	 * value until the next request boundary.
	 */
	public invalidateCostLimitCache(): void {
		this._costLimitCheckCache = undefined
		this._costLimitBypassed = false
		this._costLimitEnforcementFiredForRequest = false
	}

	/**
	 * Check whether the root task's aggregated cost has exceeded the budget
	 * limit. Awaited from the streaming loop after `updateApiReqMsg` writes
	 * the new per-request `cost`. If the limit is reached we either:
	 *   - pause: ask the user (yes=increase / no=abort / msg=continue)
	 *   - abort: clean abort, persists state
	 *   - kill : abandoned abort (headless / evals)
	 *
	 * Awaiting matters: the caller in the stream consumer must observe the
	 * abort flag *before* yielding the next chunk, otherwise we keep burning
	 * tokens past the cap.
	 */
	private async checkCostLimit(requestIndex: number): Promise<void> {
		if (this._costLimitBypassed) return
		if (this._costLimitCheckCache?.requestIndex === requestIndex) return

		const { root, limit } = this.resolveCostLimit()
		if (!limit || limit.maxUsd <= 0) return

		const provider = this.providerRef.deref()
		if (!provider) return

		let spent = 0
		try {
			const aggregated = await aggregateTaskCostsRecursive(root.taskId, (id) =>
				provider.getTaskWithId(id).then((r) => r.historyItem),
			)
			spent = aggregated.totalCost
		} catch (err) {
			// History scan failed — don't block the user's task on telemetry math.
			provider.log?.(
				`[Task#${this.taskId}] checkCostLimit: aggregate failed for root ${root.taskId}: ${err instanceof Error ? err.message : String(err)}`,
			)
			return
		}

		this._costLimitCheckCache = { spent, requestIndex }
		if (spent < limit.maxUsd) return

		await this.enforceCostLimit(root, limit, spent)
	}

	/**
	 * Snapshot the prior-history aggregate cost for the root and stash it
	 * on `_priorAggregateUsd` so the per-chunk in-stream check can compare
	 * `prior + currentRequestCost` against the cap without re-scanning
	 * history on every chunk.
	 *
	 * Called once at the request boundary (before the first chunk of a new
	 * API call). On error or no-limit, leaves the snapshot undefined so
	 * `checkInFlightCostLimit` becomes a no-op for this request.
	 */
	private async snapshotPriorAggregateForCostLimit(): Promise<void> {
		this._priorAggregateUsd = undefined
		this._costLimitEnforcementFiredForRequest = false
		const provider = this.providerRef.deref()
		if (this._costLimitBypassed) {
			return
		}
		const { root, limit } = this.resolveCostLimit()
		if (!limit || limit.maxUsd <= 0) {
			return
		}
		if (!provider) return
		try {
			const aggregated = await aggregateTaskCostsRecursive(root.taskId, (id) =>
				provider.getTaskWithId(id).then((r) => r.historyItem),
			)
			this._priorAggregateUsd = aggregated.totalCost
		} catch (err) {
			provider.log?.(
				`[Task#${this.taskId}] snapshotPriorAggregateForCostLimit: failed for root ${root.taskId}: ${err instanceof Error ? err.message : String(err)}`,
			)
		}
	}

	/**
	 * In-stream cost-cap gate. Called from the main streaming loop on every
	 * `usage` chunk so we abort/pause AS SOON AS the cumulative spend
	 * (prior history aggregate + this request's running cost) crosses the
	 * cap, rather than waiting for the request to finish. This is critical
	 * for tight limits (e.g. 0.05 USD), where a single completion can
	 * easily blow past the cap before the post-stream check would fire.
	 *
	 * No-ops when bypass is set, no limit is configured, or the prior
	 * aggregate snapshot wasn't captured (see
	 * `snapshotPriorAggregateForCostLimit`). The actual enforcement (abort
	 * /kill /pause-ask) is delegated to `enforceCostLimit` so this path
	 * shares behaviour with the post-stream `checkCostLimit`.
	 */
	private async checkInFlightCostLimit(currentRequestCostUsd: number | undefined): Promise<void> {
		if (this._costLimitBypassed) return
		if (this._costLimitEnforcementFiredForRequest) return
		if (this._priorAggregateUsd === undefined) {
			return
		}
		if (currentRequestCostUsd === undefined || !Number.isFinite(currentRequestCostUsd)) {
			return
		}
		const { root, limit } = this.resolveCostLimit()
		if (!limit || limit.maxUsd <= 0) return
		const spent = this._priorAggregateUsd + currentRequestCostUsd
		if (spent < limit.maxUsd) return
		// Latch so subsequent chunks in the same request don't re-fire.
		this._costLimitEnforcementFiredForRequest = true
		await this.enforceCostLimit(root, limit, spent)
	}

	/**
	 * Local-pricing estimate of the CURRENT request's running cost from the
	 * accumulated token counters. Used as the in-flight gate's fallback when
	 * the backend does not stamp a `totalCost` on its usage chunk.
	 *
	 * This is what makes the tight cost cap enforce "regardless of backend":
	 * providers that self-report cost (anthropic, openai-native, gemini,
	 * openrouter, and llm-router/shofer-router via vscode-lm) feed the gate
	 * `chunk.totalCost` directly; providers that DON'T stamp per-request cost
	 * (openai.ts, bedrock.ts, deepseek.ts, and any OpenAI-compatible endpoint)
	 * would otherwise leave the in-stream gate a no-op — the cap could then
	 * only fire at the post-stream boundary, letting a single expensive
	 * completion blow past a tight limit before enforcement kicked in.
	 *
	 * Mirrors the protocol-aware math `updateApiReqMsg` already uses for the
	 * persisted `cost` field, so the in-stream gate and the post-stream
	 * aggregate agree on what an un-stamped request costs. Returns 0 when the
	 * model carries no pricing (nothing we can enforce on — by design we only
	 * cap real, priced spend).
	 */
	private estimateRequestCostUsd(
		modelInfo: ModelInfo,
		inputTokens: number,
		outputTokens: number,
		cacheWriteTokens: number,
		cacheReadTokens: number,
	): number {
		const modelId = getModelId(this.apiConfiguration)
		const apiProvider = this.apiConfiguration.apiProvider
		const apiProtocol = getApiProtocol(
			apiProvider && !isRetiredProvider(apiProvider) ? apiProvider : undefined,
			modelId,
		)
		const costResult =
			apiProtocol === "anthropic"
				? calculateApiCostAnthropic(modelInfo, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens)
				: calculateApiCostOpenAI(modelInfo, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens)
		return costResult.totalCost
	}

	/**
	 * Shared enforcement step: emit telemetry + branch on
	 * `limit.action`. Used by both the post-stream `checkCostLimit` and
	 * the in-stream `checkInFlightCostLimit` so behaviour stays
	 * identical regardless of which gate fires first.
	 */
	private async enforceCostLimit(root: Task, limit: CostLimit, spent: number): Promise<void> {
		TelemetryService.instance.captureBudgetExceeded(this.taskId, {
			rootTaskId: root.taskId,
			limitUsd: limit.maxUsd,
			spentUsd: spent,
			action: limit.action,
			modelId: getModelId(this.apiConfiguration),
		})

		if (limit.action === "abort" || limit.action === "kill") {
			// Cancel the in-flight HTTP request first so the stream consumer
			// stops yielding chunks immediately, then mark this task aborted
			// so its loop exits at the next iteration boundary. Also abort the
			// root if it's a different instance, so the whole tree winds down
			// (subtasks die via the recursive backgroundChildren walk in
			// abortTask).
			try {
				this.cancelCurrentRequest()
			} catch {
				/* best effort */
			}
			const isAbandoned = limit.action === "kill"
			await this.abortTask(isAbandoned)
			if (root !== this) {
				await root.abortTask(isAbandoned)
			}
			return
		}
		// pause
		await this.askUserForBudgetDecision(root, limit, spent)
	}

	/**
	 * Pause-mode handler. Reuses the existing `ask` machinery with three
	 * outcomes wired through ChatView's primary/secondary buttons and the
	 * text input:
	 *   yesButtonClicked    → "Continue without limit". Bypasses further
	 *                          enforcement for the remainder of this task
	 *                          (no further checks fire).
	 *   noButtonClicked     → "Abort task". Cleanly aborts the root and
	 *                          all subtasks via the existing recursive
	 *                          abort path.
	 *   messageResponse     → user typed a new dollar amount. Parsed as a
	 *                          positive float and used as the new
	 *                          maxUsd on the root (action preserved).
	 *                          Non-numeric/invalid input is treated as
	 *                          "continue without limit" so we never silently
	 *                          ignore the user's intent.
	 *
	 * The askText is JSON so the webview's BudgetLimitDialog can render
	 * a structured message; ChatView falls back to the buttons when the
	 * dialog isn't present.
	 */
	private async askUserForBudgetDecision(root: Task, limit: CostLimit, spent: number): Promise<void> {
		const askText = JSON.stringify({ spentUsd: spent, limitUsd: limit.maxUsd, action: limit.action })
		const { response, text } = await this.ask("budget_limit", askText)

		if (response === "noButtonClicked") {
			await root.abortTask(false)
			return
		}
		if (response === "messageResponse") {
			// Parse the user-supplied new limit. Accept a bare number
			// ("0.10") or a leading-$ form ("$0.10"); reject anything else.
			const raw = (text ?? "").trim().replace(/^\$/, "")
			const parsed = Number(raw)
			if (raw.length > 0 && Number.isFinite(parsed) && parsed > 0) {
				const next: CostLimit = { maxUsd: parsed, action: limit.action }
				root.costLimit = next
				root.invalidateCostLimitCache()
				const provider = this.providerRef.deref()
				if (provider) {
					try {
						const { historyItem } = await provider.getTaskWithId(root.taskId)
						if (historyItem) {
							await provider.updateTaskHistory({ ...historyItem, costLimit: next })
						}
					} catch (err) {
						provider.log?.(
							`[askUserForBudgetDecision] persist failed: ${err instanceof Error ? err.message : String(err)}`,
						)
					}
				}
				return
			}
			// Fall through to bypass on unparsable input.
		}
		// yesButtonClicked or unparsable messageResponse → "continue
		// without limit" for this task.
		root._costLimitBypassed = true
		root._costLimitCheckCache = undefined
	}

	public dispose(): void {
		taskLog.info(`[Task#dispose] disposing task ${this.taskId}.${this.instanceId}`)

		// Drain any pending debounced save before tearing down listeners, so
		// the trailing fire cannot execute against a half-disposed instance.
		// Best-effort: dispose is sync, so we cancel the pending fire and
		// kick off a final save without awaiting — abortTask already
		// guarantees synchronous persistence on the abort path.
		try {
			this._debouncedSaveShoferMessages.cancel()
			void this.saveShoferMessages()
		} catch (error) {
			taskLog.error("Error draining debounced save during dispose:", error)
		}

		// Cancel any in-progress HTTP request
		try {
			this.cancelCurrentRequest()
		} catch (error) {
			taskLog.error("Error cancelling current request:", error)
		}

		// Remove provider profile change listener
		try {
			if (this.providerProfileChangeListener) {
				const provider = this.providerRef.deref()
				if (provider) {
					provider.off(ShoferEventName.ProviderProfileChanged, this.providerProfileChangeListener)
				}
				this.providerProfileChangeListener = undefined
			}
		} catch (error) {
			taskLog.error("Error removing provider profile change listener:", error)
		}

		// Dispose message queue and remove event listeners.
		try {
			if (this.messageQueueStateChangedHandler) {
				this.messageQueueService.removeListener("stateChanged", this.messageQueueStateChangedHandler)
				this.messageQueueStateChangedHandler = undefined
			}

			this.messageQueueService.dispose()
		} catch (error) {
			taskLog.error("Error disposing message queue:", error)
		}

		// Drop the mailbox's listeners and in-memory contents. Its FILE survives:
		// mail delivered to a task outlives any one instance of it.
		try {
			this.mailbox.dispose()
		} catch (error) {
			taskLog.error("Error disposing mailbox:", error)
		}

		// Remove all event listeners to prevent memory leaks.
		try {
			this.removeAllListeners()
		} catch (error) {
			taskLog.error("Error removing event listeners:", error)
		}

		// Release any terminals associated with this task.
		try {
			// Release any terminals associated with this task.
			TerminalRegistry.releaseTerminalsForTask(this.taskId)
		} catch (error) {
			taskLog.error("Error releasing terminals:", error)
		}

		// Cleanup command output artifacts
		getTaskDirectoryPath(this.globalStoragePath, this.taskId)
			.then((taskDir) => {
				const outputDir = path.join(taskDir, "command-output")
				return OutputInterceptor.cleanup(outputDir)
			})
			.catch((error) => {
				taskLog.error("Error cleaning up command output artifacts:", error)
			})

		try {
			if (this.shoferIgnoreController) {
				this.shoferIgnoreController.dispose()
				this.shoferIgnoreController = undefined
			}
		} catch (error) {
			taskLog.error("Error disposing ShoferIgnoreController:", error)
			// This is the critical one for the leak fix.
		}

		try {
			this.fileContextTracker.dispose()
		} catch (error) {
			taskLog.error("Error disposing file context tracker:", error)
		}

		try {
			// If we're not streaming then `abortStream` won't be called.
			if (this.isStreaming && this.diffViewProvider.isEditing) {
				this.diffViewProvider
					.revertChanges()
					.catch((e) => taskLog.error("Error reverting diff changes:", { error: String(e) }))
			}
		} catch (error) {
			taskLog.error("Error reverting diff changes:", error)
		}

		// H13(b): release the long-lived append file handle for this task's
		// JSONL log. Best-effort — the fd will be reclaimed by the kernel on
		// process exit anyway.
		void this.getPersistence()
			.then((p) => p.disposeAppendHandleForTask(this.taskId))
			.catch(() => {
				// EACCES in test envs, missing task dir, etc. — harmless.
			})
	}

	// Task Loop

	private async initiateTaskLoop(userContent: Anthropic.Messages.ContentBlockParam[]): Promise<void> {
		this.diagLog(
			`[DIAG initiateTaskLoop] taskId=${this.taskId}.${this.instanceId}, userContent blocks=${userContent.length}, texts=${userContent
				.filter((b) => b.type === "text")
				// eslint-disable-next-line @typescript-eslint/no-explicit-any
				.map((b) => (b as any).text?.substring(0, 80))
				.join(" | ")}`,
		)
		// H15: Invalidate per-turn system prompt and tool-array caches.
		this._cachedSystemPromptBase = null
		this._cachedSystemPromptKey = ""
		this._cachedToolsResult = null
		this._cachedToolsKey = ""

		let nextUserContent = userContent
		let includeFileDetails = true
		this.taskStartedEmitted = false

		while (!this.abort) {
			this.diagLog(
				`[DIAG initiateTaskLoop] Loop iteration START taskId=${this.taskId}.${this.instanceId}, nextUserContent blocks=${nextUserContent.length}`,
			)
			// Defensive: scan the full API history for orphaned tool_use blocks
			// before every request. The primary caller (cancelAndProcessQueuedMessages)
			// already calls this, but history may have been corrupted through other
			// code paths (resumeTaskFromHistory, stored-history load, condensation).
			this._cleanupOrphanedToolUses()
			const didEndLoop = await this.recursivelyMakeShoferRequests(nextUserContent, includeFileDetails)
			taskLog.debug(`initiateTaskLoop: recursivelyMakeShoferRequests returned didEndLoop=${didEndLoop}`)
			includeFileDetails = false // We only need file details the first time.
			this.diagLog(
				`[DIAG initiateTaskLoop] Loop iteration END taskId=${this.taskId}.${this.instanceId}, didEndLoop=${didEndLoop}`,
			)

			// The way this agentic loop works is that shofer will be given a
			// task that he then calls tools to complete. Unless there's an
			// attempt_completion call, we keep responding back to him with his
			// tool's responses until he either attempt_completion or does not
			// use anymore tools. If he does not use anymore tools, we ask him
			// to consider if he's completed the task and then call
			// attempt_completion, otherwise proceed with completing the task.
			// There is a MAX_REQUESTS_PER_TASK limit to prevent infinite
			// requests, but Shofer is prompted to finish the task as efficiently
			// as he can.

			if (didEndLoop) {
				// For now a task never 'completes'. This will only happen if
				// the user hits max requests and denies resetting the count.
				break
			} else if (this.toolCallingDisabled) {
				// A conversational task has no tools to be nudged towards, and
				// the inner loop already ended the turn (completed, or continued
				// with a queued message). Re-prompting here would ask for a tool
				// that was never sent.
				break
			} else {
				nextUserContent = [{ type: "text", text: formatResponse.noToolsUsed() }]
			}
		}
	}

	/**
	 * Wraps initiateTaskLoop to track the running promise.
	 * This allows cancelAndProcessQueuedMessages to await the old loop's
	 * completion before starting a new one.
	 *
	 * This is also the turn boundary the store lease is held across — claimed
	 * before the loop drives anything, released when it stops — so an idle task
	 * holds nothing and a remapped one can be taken over at once.
	 */
	private _runTaskLoop(userContent: Anthropic.Messages.ContentBlockParam[]): Promise<void> {
		// Establish the ambient log context so every line emitted during this
		// task's agent loop (including deep API/MCP/git utility logs reached via
		// awaits and timers) is attributed to this task for the "Logs" tab.
		const promise = this._withTaskLease(() =>
			runWithLogTaskContext({ taskId: this.taskId, rootTaskId: this.rootTaskId }, () =>
				this.initiateTaskLoop(userContent),
			),
		).finally(() => {
			if (this._taskLoopPromise === promise) {
				this._taskLoopPromise = undefined
			}
		})
		this._taskLoopPromise = promise
		return promise
	}

	public async recursivelyMakeShoferRequests(
		userContent: Anthropic.Messages.ContentBlockParam[],
		includeFileDetails: boolean = false,
	): Promise<boolean> {
		interface StackItem {
			userContent: Anthropic.Messages.ContentBlockParam[]
			includeFileDetails: boolean
			retryAttempt?: number
			userMessageWasRemoved?: boolean // Track if user message was removed due to empty response
		}

		const stack: StackItem[] = [{ userContent, includeFileDetails, retryAttempt: 0 }]

		while (stack.length > 0) {
			const currentItem = stack.pop()!
			const currentUserContent = currentItem.userContent
			const currentIncludeFileDetails = currentItem.includeFileDetails

			if (this.abort) {
				throw new Error(`[Shofer#recursivelyMakeRooRequests] task ${this.taskId}.${this.instanceId} aborted`)
			}

			// When the "Disable mistake limit checks" experimental flag is enabled,
			// skip all mistake-limit gating — the counter is still incremented for
			// telemetry but the dialog never fires and the loop never blocks.
			const loopState = await this.providerRef.deref()?.getState()
			const loopExperiments = loopState?.experiments
			const mistakeLimitChecksDisabled = loopExperiments?.disableMistakeLimitChecks === true

			if (
				!mistakeLimitChecksDisabled &&
				this.consecutiveMistakeLimit > 0 &&
				this.consecutiveMistakeCount >= this.consecutiveMistakeLimit
			) {
				// Track consecutive mistake errors in telemetry via event and PostHog exception tracking.
				// The reason is "no_tools_used" because this limit is reached via initiateTaskLoop
				// which increments consecutiveMistakeCount when the model doesn't use any tools.
				TelemetryService.instance.captureConsecutiveMistakeError(this.taskId)
				TelemetryService.instance.captureException(
					new ConsecutiveMistakeError(
						`Task reached consecutive mistake limit (${this.consecutiveMistakeLimit})`,
						this.taskId,
						this.consecutiveMistakeCount,
						this.consecutiveMistakeLimit,
						"no_tools_used",
						this.apiConfiguration.apiProvider,
						getModelId(this.apiConfiguration),
					),
				)

				const { response, text, images } = await this.ask(
					"mistake_limit_reached",
					t("common:errors.mistake_limit_guidance"),
				)

				if (response === "messageResponse") {
					currentUserContent.push(
						...[
							{ type: "text" as const, text: formatResponse.tooManyMistakes(text) },
							...formatResponse.imageBlocks(images),
						],
					)

					await this.say("user_feedback", text, images)
				}

				this.consecutiveMistakeCount = 0
			}

			// Getting verbose details is an expensive operation, it uses ripgrep to
			// top-down build file structure of project which for large projects can
			// take a few seconds. For the best UX we show a placeholder api_req_started
			// message with a loading spinner as this happens.

			// Determine API protocol based on provider and model
			const modelId = getModelId(this.apiConfiguration)
			const apiProvider = this.apiConfiguration.apiProvider
			const apiProtocol = getApiProtocol(
				apiProvider && !isRetiredProvider(apiProvider) ? apiProvider : undefined,
				modelId,
			)

			// Respect user-configured provider rate limiting BEFORE we emit api_req_started.
			// This prevents the UI from showing an "API Request..." spinner while we are
			// intentionally waiting due to the rate limit slider.
			//
			// NOTE: We also set Task.lastGlobalApiRequestTime here to reserve this slot
			// before we build environment details (which can take time).
			// This ensures subsequent requests (including subtasks) still honour the
			// provider rate-limit window.
			await this.maybeWaitForProviderRateLimit(currentItem.retryAttempt ?? 0)
			Task.lastGlobalApiRequestTime = performance.now()

			// ----- Task Visualization: timeline instrumentation -----
			// Reset per-request timeline state before each API request.
			this._pendingToolSpans = []
			this._pendingTtfbMs = null
			this._pendingGenStartMs = null
			this._pendingReasoningIntervals = []
			this._pendingReasoningOpenedAtMs = null
			this._pendingApiReqNeedsEmit = true
			this._pendingRequestStartOffset = performance.now() - this.timelineOriginMs

			// Lifecycle `onApiRequestStart` (design §6.9): the real wall-clock start of
			// one LLM request, which the finish payload cannot supply (it carries
			// offsets). Fire-and-forget and guarded, so nothing sits in front of the
			// request. Fired here — after the rate-limit wait, before the request is
			// built — so the bracket measures the model, not our own queueing.
			if (pluginRegistry.hasLifecycleHook("onApiRequestStart")) {
				void pluginRegistry
					.notifyApiRequestStart(
						{
							taskId: this.taskId,
							requestIndex: this._currentRequestIndex,
							model: modelId ?? "",
							apiProtocol: apiProtocol as "anthropic" | "openai",
							retryAttempt: currentItem.retryAttempt ?? 0,
						},
						{
							parentTaskId: this.parentTaskId,
							rootTaskId: this.rootTaskId,
							cwd: this.cwd,
							mode: this._taskMode,
							turn: this.turnCount,
						},
					)
					.catch(() => {})
			}

			// Monotonic open-time for this request. The elapsed span it yields is
			// stamped onto every stream-end rewrite of the `api_req_started`
			// payload below, which is the only account of the request's timing a
			// consumer gets when no `api_req_finished` span is written.
			const apiReqTimer = startApiRequestTimer()

			await this.say(
				"api_req_started",
				JSON.stringify(
					openedApiReqInfo({
						apiProtocol,
						model: modelId,
						retryAttempt: currentItem.retryAttempt ?? 0,
					}),
				),
			)

			const provider = this.providerRef.deref()
			const state = provider ? await provider.getState() : undefined

			const showShoferIgnoredFiles = state?.showShoferIgnoredFiles ?? false
			const includeDiagnosticMessages = state?.includeDiagnosticMessages ?? true
			const maxDiagnosticMessages = state?.maxDiagnosticMessages ?? 50
			// Use the task's own mode, not the provider-global mode which
			// reflects the currently focused task. Without this, a mode
			// switch in Task A via switch_mode would affect the user-content
			// processing for a background Task B.
			const currentMode = this._taskMode || defaultModeSlug

			const {
				content: parsedUserContent,
				mode: slashCommandMode,
				loadedSkills: mentionLoadedSkills,
			} = await processUserContentMentions({
				userContent: currentUserContent,
				cwd: this.cwd,
				fileContextTracker: this.fileContextTracker,
				shoferIgnoreController: this.shoferIgnoreController,
				showShoferIgnoredFiles,
				includeDiagnosticMessages,
				maxDiagnosticMessages,
				skillsManager: provider?.getSkillsManager() as Parameters<
					typeof processUserContentMentions
				>[0]["skillsManager"],
				currentMode,
			})

			// Track skills resolved via slash-style mentions (e.g. `/skill-name`)
			// so the SkillsButton popover reflects them as loaded — mirroring the
			// behavior of the `skills` tool.
			if (mentionLoadedSkills) {
				for (const [name, path] of Object.entries(mentionLoadedSkills)) {
					this.loadedSkills.set(name, path)
				}
				taskLog.info(
					`[Task] mention-loaded skills set on task. loadedSkills now:`,
					Array.from(this.loadedSkills.entries()),
				)
			}

			// Switch mode if specified in a slash command's frontmatter
			if (slashCommandMode) {
				const provider = this.providerRef.deref()
				if (provider) {
					const state = await provider.getState()
					const targetMode = getModeBySlug(slashCommandMode, state?.customModes)
					if (targetMode) {
						// Scope the mode switch to this task so it doesn't leak
						// to the currently focused task.
						await provider.handleModeSwitch(slashCommandMode, this)
					}
				}
			}

			// Environment details describe a workspace the agent can only act on
			// through tools — the file listing, the terminals, the todo reminder.
			// A conversational turn has none of those, so the whole block is
			// latency and context tokens spent on something unusable. Skipped
			// explicitly rather than degraded to an empty string by accident.
			const environmentDetails = this.toolCallingDisabled
				? ""
				: await getEnvironmentDetails(this, currentIncludeFileDetails)

			// Remove any existing environment_details blocks before adding fresh ones.
			// This prevents duplicate environment details when resuming tasks,
			// where the old user message content may already contain environment details from the previous session.
			// We check for both opening and closing tags to ensure we're matching complete environment detail blocks,
			// not just mentions of the tag in regular content.
			const contentWithoutEnvDetails = parsedUserContent.filter((block) => {
				if (block.type === "text" && typeof block.text === "string") {
					// Check if this text block is a complete environment_details block
					// by verifying it starts with the opening tag and ends with the closing tag
					const isEnvironmentDetailsBlock =
						block.text.trim().startsWith("<environment_details>") &&
						block.text.trim().endsWith("</environment_details>")
					return !isEnvironmentDetailsBlock
				}
				return true
			})

			// Add environment details as its own text block, separate from tool
			// results. A conversational turn generates none, and an empty text
			// block is rejected outright by some providers.
			const finalUserContent = environmentDetails
				? [...contentWithoutEnvDetails, { type: "text" as const, text: environmentDetails }]
				: [...contentWithoutEnvDetails]
			// Only add user message to conversation history if:
			// 1. This is the first attempt (retryAttempt === 0), AND
			// 2. The original userContent was not empty (empty signals delegation resume where
			//    the user message with tool_result and env details is already in history), OR
			// 3. The message was removed in a previous iteration (userMessageWasRemoved === true)
			// This prevents consecutive user messages while allowing re-add when needed
			const isEmptyUserContent = currentUserContent.length === 0
			const shouldAddUserMessage =
				((currentItem.retryAttempt ?? 0) === 0 && !isEmptyUserContent) || currentItem.userMessageWasRemoved
			this.diagLog(
				`[DIAG recursivelyMakeShoferRequests] shouldAddUserMessage=${shouldAddUserMessage}, retryAttempt=${currentItem.retryAttempt}, isEmptyUserContent=${isEmptyUserContent}, userMessageWasRemoved=${currentItem.userMessageWasRemoved}, totalApiHistory=${this.apiConversationHistory.length}, finalUserContentBlocks=${finalUserContent.length}`,
			)
			if (shouldAddUserMessage) {
				this.diagLog(
					`[DIAG recursivelyMakeShoferRequests] ADDING user message to API history, texts=${finalUserContent
						// eslint-disable-next-line @typescript-eslint/no-explicit-any
						.filter((b: any) => b.type === "text")
						// eslint-disable-next-line @typescript-eslint/no-explicit-any
						.map((b: any) => b.text?.substring(0, 80))
						.join(" | ")}`,
				)
				await this.addToApiConversationHistory({ role: "user", content: finalUserContent })
				TelemetryService.instance.captureConversationMessage(this.taskId, "user")
			}

			// Since we sent off a placeholder api_req_started message to update the
			// webview while waiting to actually start the API request (to load
			// potential details for example), we need to update the text of that
			// message.
			const lastApiReqIndex = findLastIndex(this.shoferMessages, (m) => m.say === "api_req_started")

			// Still the OPENING payload — the request has not been sent yet — so it
			// carries no `durationMs`. See `api-req-timing.ts`.
			this.shoferMessages[lastApiReqIndex]!.text = JSON.stringify(
				openedApiReqInfo({
					apiProtocol,
					model: modelId,
					retryAttempt: currentItem.retryAttempt ?? 0,
				}),
			)

			// Must flush synchronously — the API call that follows reads
			// on-disk state and depends on this save being visible.
			await this._flushSaveShoferMessages()
			// Skinny push removed — per-message deltas
			// (`shoferMessageAppended` / `messageUpdated`) keep the webview's
			// shoferMessages array in sync; `taskHistoryItemUpdated` covers history.
			try {
				let cacheWriteTokens = 0
				let cacheReadTokens = 0
				let inputTokens = 0
				let outputTokens = 0
				let totalCost: number | undefined
				/** Response metadata from the LLM provider (shofer-router), populated
				 *  by the response_metadata marker emitted at stream end.  Merged
				 *  into api_req_started via updateApiReqMsg for gentle UI exposure. */
				let responseMetadata:
					| {
							actualModel?: string
							ttfbMs?: number
							ttlbMs?: number
							attempts?: number
							responseError?: string
					  }
					| undefined

				// We can't use `api_req_finished` anymore since it's a unique case
				// where it could come after a streaming message (i.e. in the middle
				// of being updated or executed).
				// Fortunately `api_req_finished` was always parsed out for the GUI
				// anyways, so it remains solely for legacy purposes to keep track
				// of prices in tasks from history (it's worth removing a few months
				// from now).
				const updateApiReqMsg = (
					cancelReason?: ShoferApiReqCancelReason,
					streamingFailedMessage?: string,
					metaOverrides?: typeof responseMetadata,
				) => {
					if (lastApiReqIndex < 0 || !this.shoferMessages[lastApiReqIndex]) {
						return
					}

					const existingData = JSON.parse(this.shoferMessages[lastApiReqIndex].text || "{}")

					// Calculate total tokens and cost using provider-aware function
					const modelId = getModelId(this.apiConfiguration)
					const apiProvider = this.apiConfiguration.apiProvider
					const apiProtocol = getApiProtocol(
						apiProvider && !isRetiredProvider(apiProvider) ? apiProvider : undefined,
						modelId,
					)

					const costResult =
						apiProtocol === "anthropic"
							? calculateApiCostAnthropic(
									streamModelInfo,
									inputTokens,
									outputTokens,
									cacheWriteTokens,
									cacheReadTokens,
								)
							: calculateApiCostOpenAI(
									streamModelInfo,
									inputTokens,
									outputTokens,
									cacheWriteTokens,
									cacheReadTokens,
								)

					// Every call site of this closure is a stream END — the usage
					// drain, the provider's end-of-stream metadata marker, or an
					// aborted/failed stream — so the payload is stamped with the
					// request's duration. Re-measured on each rewrite, so a
					// progressive update leaves the final value at open→stream-end.
					//
					// The phase marks come from `_markStreamProgress`, which the
					// streaming loop below already maintains for the
					// `api_req_finished` span: one measurement, two accounts of it,
					// so a consumer reading either can never see them disagree.
					// The reasoning INTERVALS ride here and only here — see
					// `ShoferApiReqInfo.reasoningIntervalsMs`.
					this.shoferMessages[lastApiReqIndex].text = JSON.stringify(
						endedApiReqInfo(
							{
								...existingData,
								tokensIn: costResult.totalInputTokens,
								tokensOut: costResult.totalOutputTokens,
								cacheWrites: cacheWriteTokens,
								cacheReads: cacheReadTokens,
								cost: totalCost ?? costResult.totalCost,
								cancelReason,
								streamingFailedMessage,
								...(metaOverrides ?? {}),
							} satisfies ShoferApiReqInfo,
							apiReqTimer,
							this._streamPhaseMarks,
						),
					)
				}

				const abortStream = async (cancelReason: ShoferApiReqCancelReason, streamingFailedMessage?: string) => {
					if (this.diffViewProvider.isEditing) {
						await this.diffViewProvider.revertChanges() // closes diff view
					}

					// Finalize ANY still-partial messages so no chat row is left with a
					// perpetual spinner after an interrupt (§6 tool-state reconciliation).
					// Typically only the trailing message is partial, but iterate
					// defensively. DO NOT change ts — it is the virtuoso list key.
					for (const m of this.shoferMessages) {
						if (m.partial) {
							m.partial = false
						}
					}

					// Update `api_req_started` to have cancelled and cost, so that
					// we can display the cost of the partial stream and the cancellation reason
					updateApiReqMsg(cancelReason, streamingFailedMessage)

					// Emit immutable timeline span for the cancelled request.
					const abortStatus: ApiRequestFinishedPayload["status"] =
						cancelReason === "user_cancelled"
							? "cancelled"
							: cancelReason === "streaming_failed"
								? "error"
								: "cancelled"
					const abortCancelReason: ApiRequestFinishedPayload["cancelReason"] | undefined =
						cancelReason === "user_cancelled"
							? "user_cancelled"
							: cancelReason === "streaming_failed"
								? "streaming_failed"
								: undefined
					await this.emitApiReqFinished(abortStatus, abortCancelReason)
					// In-place mutation of api_req_started invalidates the H2.bis
					// token-usage cache (count unchanged; cancellation cost did change).
					this._cachedTokenUsage = undefined
					// Must flush synchronously — abortTask depends on the saved
					// messages being visible on disk.
					await this._flushSaveShoferMessages()

					// Signals to provider that it can retrieve the saved messages
					// from disk, as abortTask can not be awaited on in nature.
					this.didFinishAbortingStream = true
				}

				// Reset streaming state for each new API request
				this.currentStreamingContentIndex = 0
				this.turnCount++
				this.assistantMessageContent = []
				this.didCompleteReadingStream = false
				this.userMessageContent = []
				this.userMessageContentReady = false
				this.didRejectTool = false
				this.didAlreadyUseTool = false
				this.didExecuteAttemptCompletion = false
				this.assistantMessageSavedToHistory = false
				// Reset tool failure flag for each new assistant turn - this ensures that tool failures
				// only prevent attempt_completion within the same assistant message, not across turns
				// (e.g., if a tool fails, then user sends a message saying "just complete anyway")
				this.didToolFailInCurrentTurn = false
				this.presentAssistantMessageLocked = false
				this.presentAssistantMessageHasPendingUpdates = false
				// No legacy text-stream tool parser.
				this.streamingToolCallIndices.clear()
				// Clear any leftover streaming tool call state from previous interrupted streams
				this.nativeToolCallParser.clearAllStreamingToolCalls()
				this.nativeToolCallParser.clearRawChunkState()

				await this.diffViewProvider.reset()

				// Cache model info once per API request to avoid repeated calls during streaming
				// This is especially important for tools and background usage collection
				this.cachedStreamingModel = this.api.getModel()
				const streamModelInfo = this.cachedStreamingModel.info
				// eslint-disable-next-line @typescript-eslint/no-unused-vars
				const cachedModelId = this.cachedStreamingModel.id

				// Snapshot the running spend across the root's history BEFORE
				// this request starts. The streaming `usage`-chunk handler
				// below adds this request's in-flight cost on top and triggers
				// abort/pause as soon as the sum crosses the cap, so a single
				// expensive completion can't silently blow past a tight limit
				// (e.g. $0.05) before the post-stream check fires.
				await this.snapshotPriorAggregateForCostLimit()
				if (this.abort) {
					break
				}

				// Yields only if the first chunk is successful, otherwise will
				// allow the user to retry the request (most likely due to rate
				// limit error, which gets thrown on the first chunk).
				if (!this.taskStartedEmitted) {
					this.taskStartedEmitted = true
					this.emit(ShoferEventName.TaskStarted)
				}
				const stream = this.attemptApiRequest(currentItem.retryAttempt ?? 0, { skipProviderRateLimit: true })
				let assistantMessage = ""
				let reasoningMessage = ""
				const pendingGroundingSources: GroundingSource[] = []
				this.isStreaming = true

				try {
					const iterator = stream[Symbol.asyncIterator]()

					// Helper to race iterator.next() with abort signal
					const nextChunkWithAbort = async () => {
						const nextPromise = iterator.next()

						// If we have an abort controller, race it with the next chunk
						if (this.currentRequestAbortController) {
							const abortPromise = new Promise<never>((_, reject) => {
								const signal = this.currentRequestAbortController!.signal
								if (signal.aborted) {
									reject(new Error("Request cancelled by user"))
								} else {
									signal.addEventListener("abort", () => {
										reject(new Error("Request cancelled by user"))
									})
								}
							})
							return await Promise.race([nextPromise, abortPromise])
						}

						// No abort controller, just return the next chunk normally
						return await nextPromise
					}

					let item = await nextChunkWithAbort()
					while (!item.done) {
						const chunk = item.value
						item = await nextChunkWithAbort()
						if (!chunk) {
							// Sometimes chunk is undefined, no idea that can cause
							// it, but this workaround seems to fix it.
							continue
						}

						// Debug log every chunk received in the stream consumer
						//this.diagLog(
						//	`[Task#${this.taskId}] [STREAM_CONSUMER] Received chunk type=${chunk?.type}, preview=${JSON.stringify(chunk)?.slice(0, 200)}`,
						//)

						switch (chunk.type) {
							case "reasoning": {
								// Reasoning chunk: marks TTFB but not generation start.
								this._markStreamProgress(true)
								reasoningMessage += chunk.text
								// Only apply formatting if the message contains sentence-ending punctuation followed by **
								let formattedReasoning = reasoningMessage
								if (reasoningMessage.includes("**")) {
									// Add line breaks before **Title** patterns that appear after sentence endings
									// This targets section headers like "...end of sentence.**Title Here**"
									// Handles periods, exclamation marks, and question marks
									formattedReasoning = reasoningMessage.replace(
										/([.!?])\*\*([^*\n]+)\*\*/g,
										"$1\n\n**$2**",
									)
								}
								await this.say("reasoning", formattedReasoning, undefined, true)
								break
							}
							case "usage":
								inputTokens += chunk.inputTokens
								outputTokens += chunk.outputTokens
								cacheWriteTokens += chunk.cacheWriteTokens ?? 0
								cacheReadTokens += chunk.cacheReadTokens ?? 0
								totalCost = chunk.totalCost
								// In-stream cost-cap gate. Awaited so any
								// abort/kill takes effect (sets `this.abort`
								// + cancels the in-flight HTTP request)
								// before the consumer pulls the next chunk;
								// the post-switch `if (this.abort) break`
								// then exits the streaming loop immediately
								// instead of burning more tokens past the
								// cap. The pause-mode branch awaits the
								// user's decision here too — fine because
								// no further tokens stream until we resume.
								//
								// Fall back to a local-pricing estimate when the
								// backend doesn't stamp `totalCost` (openai.ts,
								// bedrock.ts, deepseek.ts, raw OpenAI-compatible
								// endpoints). Without this the gate would no-op
								// for those backends and the cap could only fire
								// at the post-stream boundary — too late for a
								// single expensive completion on a tight limit.
								await this.checkInFlightCostLimit(
									totalCost ??
										this.estimateRequestCostUsd(
											streamModelInfo,
											inputTokens,
											outputTokens,
											cacheWriteTokens,
											cacheReadTokens,
										),
								)
								break
							case "grounding":
								// Handle grounding sources separately from regular content
								// to prevent state persistence issues - store them separately
								if (chunk.sources && chunk.sources.length > 0) {
									pendingGroundingSources.push(...chunk.sources)
								}
								break
							case "tool_preparing": {
								// Inline progress row from llm-provider while tool
								// call arguments stream in. Replaces the old
								// thinking-bubble noise ("Preparing…" + dots).
								// partial=true makes repeated markers for the same
								// tool_name kv-update the same row in-place.
								await this.say(
									"tool_preparing",
									JSON.stringify({
										toolName: chunk.toolName,
										byteCount: chunk.byteCount,
									}),
									undefined,
									true, // partial
								)
								break
							}
							case "response_metadata": {
								// Per-request diagnostics from shofer-router (actual model
								// served, latency, failover count, error message on failure).
								// Stored locally and merged into api_req_started by
								// updateApiReqMsg so the UI can show a gentle info icon.
								responseMetadata = {
									actualModel: chunk.actualModel,
									ttfbMs: chunk.ttfbMs,
									ttlbMs: chunk.ttlbMs,
									attempts: chunk.attempts,
									responseError: chunk.error,
								}
								// Merge now so the webview sees it immediately.
								updateApiReqMsg(undefined, undefined, responseMetadata)
								break
							}
							case "tool_call_partial": {
								// Tool-call chunk: generation has started (no preceding text).
								this._markStreamProgress(false)
								// Process raw tool call chunk through NativeToolCallParser
								// which handles tracking, buffering, and emits events
								const events = this.nativeToolCallParser.processRawChunk({
									index: chunk.index,
									id: chunk.id,
									name: chunk.name,
									arguments: chunk.arguments,
								})

								for (const event of events) {
									if (event.type === "tool_call_start") {
										// Guard against duplicate tool_call_start events for the same tool ID.
										// This can occur due to stream retry, reconnection, or API quirks.
										// Without this check, duplicate tool_use blocks with the same ID would
										// be added to assistantMessageContent, causing API 400 errors:
										// "tool_use ids must be unique"
										if (this.streamingToolCallIndices.has(event.id)) {
											taskLog.warn(
												`[Task#${this.taskId}] Ignoring duplicate tool_call_start for ID: ${event.id} (tool: ${event.name})`,
											)
											continue
										}

										// Initialize streaming in NativeToolCallParser
										this.nativeToolCallParser.startStreamingToolCall(
											event.id,
											event.name as ToolName,
										)

										// Before adding a new tool, finalize any preceding text block
										// This prevents the text block from blocking tool presentation
										const lastBlock =
											this.assistantMessageContent[this.assistantMessageContent.length - 1]
										if (lastBlock?.type === "text" && lastBlock.partial) {
											lastBlock.partial = false
										}

										// Track the index where this tool will be stored
										const toolUseIndex = this.assistantMessageContent.length
										this.streamingToolCallIndices.set(event.id, toolUseIndex)

										// Create initial partial tool use
										const partialToolUse: ToolUse = {
											type: "tool_use",
											name: event.name as ToolName,
											params: {},
											partial: true,
										}

										// Store the ID for native protocol
										// eslint-disable-next-line @typescript-eslint/no-explicit-any
										;(partialToolUse as any).id = event.id

										// Add to content and present
										this.assistantMessageContent.push(partialToolUse)
										this.userMessageContentReady = false

										// Dismiss any tool_preparing row now that the tool call has started.
										await this.dismissToolPreparingRow()

										presentAssistantMessage(this)
									} else if (event.type === "tool_call_delta") {
										// Process chunk using streaming JSON parser
										const partialToolUse = this.nativeToolCallParser.processStreamingChunk(
											event.id,
											event.delta,
										)

										if (partialToolUse) {
											// Get the index for this tool call
											const toolUseIndex = this.streamingToolCallIndices.get(event.id)
											if (toolUseIndex !== undefined) {
												// Store the ID for native protocol
												// eslint-disable-next-line @typescript-eslint/no-explicit-any
												;(partialToolUse as any).id = event.id

												// Update the existing tool use with new partial data
												this.assistantMessageContent[toolUseIndex] = partialToolUse

												// Present updated tool use
												presentAssistantMessage(this)
											}
										}
									} else if (event.type === "tool_call_end") {
										// Finalize the streaming tool call
										const finalToolUse = this.nativeToolCallParser.finalizeStreamingToolCall(
											event.id,
										)

										this.captureToolCallTelemetry(undefined, finalToolUse)

										// Get the index for this tool call
										const toolUseIndex = this.streamingToolCallIndices.get(event.id)

										if (finalToolUse) {
											// Store the tool call ID
											// eslint-disable-next-line @typescript-eslint/no-explicit-any
											;(finalToolUse as any).id = event.id

											// Get the index and replace partial with final
											if (toolUseIndex !== undefined) {
												this.assistantMessageContent[toolUseIndex] = finalToolUse
											}

											// Clean up tracking
											this.streamingToolCallIndices.delete(event.id)

											// Mark that we have new content to process
											this.userMessageContentReady = false

											// Present the finalized tool call
											presentAssistantMessage(this)
										} else if (toolUseIndex !== undefined) {
											// finalizeStreamingToolCall returned null (malformed JSON or missing args)
											// Clear the stale partial nativeArgs so presentAssistantMessage's guard
											// (isKnownTool && !block.nativeArgs) fires and surfaces the error instead
											// of silently dispatching the tool with incomplete arguments.
											const existingToolUse = this.assistantMessageContent[toolUseIndex]
											if (existingToolUse && existingToolUse.type === "tool_use") {
												existingToolUse.partial = false
												existingToolUse.nativeArgs = undefined
												// Ensure it has the ID for native protocol
												// eslint-disable-next-line @typescript-eslint/no-explicit-any
												;(existingToolUse as any).id = event.id
											}

											// Clean up tracking
											this.streamingToolCallIndices.delete(event.id)

											// Mark that we have new content to process
											this.userMessageContentReady = false

											// Present the tool call — nativeArgs was cleared above so
											// presentAssistantMessage's §C guard will surface the error.
											presentAssistantMessage(this)
										}
									}
								}
								break
							}

							case "tool_call": {
								// Tool-call chunk: generation has started (no preceding text).
								this._markStreamProgress(false)
								// Legacy: Handle complete tool calls (for backward compatibility)
								// Convert native tool call to ToolUse format
								const toolUse = NativeToolCallParser.parseToolCall({
									id: chunk.id,
									name: chunk.name as ToolName,
									arguments: chunk.arguments,
								})

								this.captureToolCallTelemetry(chunk.name, toolUse)

								if (!toolUse) {
									const parseError = NativeToolCallParser.consumeLastParseError()
									const errorMessage =
										`Tool call failed for "${chunk.name}": the parser could not produce a valid ` +
										`tool invocation.` +
										(parseError
											? ` Reason: ${parseError}`
											: ` This may be due to an unknown tool name, malformed JSON arguments, or missing required parameters.`)

									taskLog.error(`Failed to parse tool call for task ${this.taskId}:`, chunk)

									this.consecutiveMistakeCount++
									try {
										this.recordToolError(chunk.name as ToolName, errorMessage)
									} catch {
										// Best-effort only
									}

									await this.say("error", errorMessage)

									// Push a matching tool_result so the provider doesn't see a
									// dangling tool_use without a corresponding response.
									this.pushToolResultToUserContent({
										type: "tool_result",
										tool_use_id: sanitizeToolUseId(chunk.id),
										content: formatResponse.toolError(errorMessage),
										is_error: true,
									})

									break
								}

								// Store the tool call ID on the ToolUse object for later reference
								// This is needed to create tool_result blocks that reference the correct tool_use_id
								toolUse.id = chunk.id

								// Add the tool use to assistant message content
								this.assistantMessageContent.push(toolUse)

								// Mark that we have new content to process
								this.userMessageContentReady = false

								// Dismiss any tool_preparing row for this tool call.
								await this.dismissToolPreparingRow()

								// Present the tool call to user - presentAssistantMessage will execute
								// tools sequentially and accumulate all results in userMessageContent
								presentAssistantMessage(this)
								break
							}
							case "text": {
								// Text chunk: marks both TTFB and generation start.
								this._markStreamProgress(false)
								assistantMessage += chunk.text

								// Native tool calling: text chunks are plain text.
								// Create or update a text content block directly
								const lastBlock = this.assistantMessageContent[this.assistantMessageContent.length - 1]
								if (lastBlock?.type === "text" && lastBlock.partial) {
									lastBlock.content = assistantMessage
								} else {
									this.assistantMessageContent.push({
										type: "text",
										content: assistantMessage,
										partial: true,
										// Stable identity for the streaming → finalization
										// handoff in say(); prevents duplicate "Shofer said".
										id: uuidv7(),
									})
									this.userMessageContentReady = false
								}
								presentAssistantMessage(this)
								break
							}
						}

						if (this.abort) {
							taskLog.info(`aborting stream, this.abandoned = ${this.abandoned}`)

							if (!this.abandoned) {
								// Only need to gracefully abort if this instance
								// isn't abandoned (sometimes OpenRouter stream
								// hangs, in which case this would affect future
								// instances of Shofer).
								await abortStream("user_cancelled")
							}

							break // Aborts the stream.
						}

						if (this.didRejectTool) {
							// `userContent` has a tool rejection, so interrupt the
							// assistant's response to present the user's feedback.
							assistantMessage += "\n\n[Response interrupted by user feedback]"
							// Instead of setting this preemptively, we allow the
							// present iterator to finish and set
							// userMessageContentReady when its ready.
							// this.userMessageContentReady = true
							break
						}

						if (this.didAlreadyUseTool) {
							assistantMessage +=
								"\n\n[Response interrupted by a tool use result. Only one tool may be used at a time and should be placed at the end of the message.]"
							break
						}
					}

					// Create a copy of current token values to avoid race conditions
					const currentTokens = {
						input: inputTokens,
						output: outputTokens,
						cacheWrite: cacheWriteTokens,
						cacheRead: cacheReadTokens,
						total: totalCost,
					}

					const drainStreamInBackgroundToFindAllUsage = async (apiReqIndex: number) => {
						const timeoutMs = DEFAULT_USAGE_COLLECTION_TIMEOUT_MS
						const startTime = performance.now()
						const modelId = getModelId(this.apiConfiguration)

						// Local variables to accumulate usage data without affecting the main flow
						let bgInputTokens = currentTokens.input
						let bgOutputTokens = currentTokens.output
						let bgCacheWriteTokens = currentTokens.cacheWrite
						let bgCacheReadTokens = currentTokens.cacheRead
						let bgTotalCost = currentTokens.total

						// Helper function to capture telemetry and update messages
						const captureUsageData = async (
							tokens: {
								input: number
								output: number
								cacheWrite: number
								cacheRead: number
								total?: number
							},
							messageIndex: number = apiReqIndex,
						) => {
							if (
								tokens.input > 0 ||
								tokens.output > 0 ||
								tokens.cacheWrite > 0 ||
								tokens.cacheRead > 0 ||
								(tokens.total !== undefined && tokens.total > 0)
							) {
								// Update the shared variables atomically
								inputTokens = tokens.input
								outputTokens = tokens.output
								cacheWriteTokens = tokens.cacheWrite
								cacheReadTokens = tokens.cacheRead
								totalCost = tokens.total

								// Update the API request message with the latest usage data
								updateApiReqMsg()
								// In-place mutation invalidates the H2.bis
								// token-usage cache (count unchanged; values
								// inside the message did change).
								this._cachedTokenUsage = undefined
								await this._debouncedSaveShoferMessages()

								// Update the specific message in the webview
								const apiReqMessage = this.shoferMessages[messageIndex]
								if (apiReqMessage) {
									await this.updateShoferMessage(apiReqMessage)
								}

								// Capture telemetry with provider-aware cost calculation
								const modelId = getModelId(this.apiConfiguration)
								const apiProvider = this.apiConfiguration.apiProvider
								const apiProtocol = getApiProtocol(
									apiProvider && !isRetiredProvider(apiProvider) ? apiProvider : undefined,
									modelId,
								)

								// Use the appropriate cost function based on the API protocol
								const costResult =
									apiProtocol === "anthropic"
										? calculateApiCostAnthropic(
												streamModelInfo,
												tokens.input,
												tokens.output,
												tokens.cacheWrite,
												tokens.cacheRead,
											)
										: calculateApiCostOpenAI(
												streamModelInfo,
												tokens.input,
												tokens.output,
												tokens.cacheWrite,
												tokens.cacheRead,
											)

								TelemetryService.instance.captureLlmCompletion(this.taskId, {
									inputTokens: costResult.totalInputTokens,
									outputTokens: costResult.totalOutputTokens,
									cacheWriteTokens: tokens.cacheWrite,
									cacheReadTokens: tokens.cacheRead,
									cost: tokens.total ?? costResult.totalCost,
								})

								// Mirror the same per-request cost/token totals into Prometheus
								// counters (operational, always-on). captureUsageData fires at
								// most once per request, so these counters are not double-counted.
								const _metricsProvider = apiProvider ?? "unknown"
								const _metricsModelId = modelId ?? "unknown"
								incLlmCost(_metricsProvider, _metricsModelId, tokens.total ?? costResult.totalCost)
								incLlmTokens(_metricsProvider, _metricsModelId, {
									input: costResult.totalInputTokens,
									output: costResult.totalOutputTokens,
									cacheRead: tokens.cacheRead,
									cacheWrite: tokens.cacheWrite,
								})

								// Per-root-task cost cap. Awaited so any abort/pause takes effect
								// before the consumer pulls the next chunk; otherwise we'd keep
								// burning tokens past the cap for the rest of this stream.
								await this.checkCostLimit(messageIndex)
							}
						}

						try {
							// Continue processing the original stream from where the main loop left off
							let usageFound = false
							let chunkCount = 0

							// Use the same iterator that the main loop was using
							while (!item.done) {
								// Check for timeout
								if (performance.now() - startTime > timeoutMs) {
									taskLog.warn(
										`[Background Usage Collection] Timed out after ${timeoutMs}ms for model: ${modelId}, processed ${chunkCount} chunks`,
									)
									// Clean up the iterator before breaking
									if (iterator.return) {
										await iterator.return(undefined)
									}
									break
								}

								const chunk = item.value
								item = await iterator.next()
								chunkCount++

								if (chunk && chunk.type === "usage") {
									usageFound = true
									bgInputTokens += chunk.inputTokens
									bgOutputTokens += chunk.outputTokens
									bgCacheWriteTokens += chunk.cacheWriteTokens ?? 0
									bgCacheReadTokens += chunk.cacheReadTokens ?? 0
									bgTotalCost = chunk.totalCost
								}
							}

							if (
								usageFound ||
								bgInputTokens > 0 ||
								bgOutputTokens > 0 ||
								bgCacheWriteTokens > 0 ||
								bgCacheReadTokens > 0
							) {
								// We have usage data either from a usage chunk or accumulated tokens
								await captureUsageData(
									{
										input: bgInputTokens,
										output: bgOutputTokens,
										cacheWrite: bgCacheWriteTokens,
										cacheRead: bgCacheReadTokens,
										total: bgTotalCost,
									},
									lastApiReqIndex,
								)
							} else {
								taskLog.warn(
									`[Background Usage Collection] Suspicious: request ${apiReqIndex} is complete, but no usage info was found. Model: ${modelId}`,
								)
							}
						} catch (error) {
							taskLog.error("Error draining stream for usage data:", error)
							// Still try to capture whatever usage data we have collected so far
							if (
								bgInputTokens > 0 ||
								bgOutputTokens > 0 ||
								bgCacheWriteTokens > 0 ||
								bgCacheReadTokens > 0
							) {
								await captureUsageData(
									{
										input: bgInputTokens,
										output: bgOutputTokens,
										cacheWrite: bgCacheWriteTokens,
										cacheRead: bgCacheReadTokens,
										total: bgTotalCost,
									},
									lastApiReqIndex,
								)
							}
						}
					}

					// Start the background task and handle any errors
					drainStreamInBackgroundToFindAllUsage(lastApiReqIndex).catch((error) => {
						taskLog.error("Background usage collection failed:", error)
					})
				} catch (error) {
					// Abandoned happens when extension is no longer waiting for the
					// Shofer instance to finish aborting (error is thrown here when
					// any function in the for loop throws due to this.abort).
					if (!this.abandoned) {
						// Persist structured error info for export diagnostics.
						if (!this.abort) {
							this.snapshotApiReqError(this.buildApiReqError(error))
						}

						// Determine cancellation reason
						const cancelReason: ShoferApiReqCancelReason = this.abort
							? "user_cancelled"
							: "streaming_failed"

						const rawErrorMessage =
							error instanceof Error ? error.message : JSON.stringify(serializeError(error), null, 2)
						const streamingFailedMessage = this.abort
							? undefined
							: `${t("common:interruption.streamTerminatedByProvider")}: ${rawErrorMessage}`

						// Clean up partial state
						await abortStream(cancelReason, streamingFailedMessage)

						if (this.abort) {
							// Soft-cancel path: the user clicked "Send Now" and we want to
							// interrupt this request without disposing the task (which would
							// wipe the message queue we are about to drain). Just unwind the
							// loop; cancelAndProcessQueuedMessages will restart it.
							if (this._softCancelForQueuedMessage) {
								this.diagLog(
									`[Task#${this.taskId}.${this.instanceId}] Soft-cancel during stream; skipping abortTask to allow queued message restart`,
								)
								break
							}
							// User cancelled - abort the entire task
							this.abortReason = cancelReason
							await this.abortTask()
						} else {
							// Permanent authentication/authorization failures
							// (HTTP 401/403) will never succeed on retry. Abort the
							// task instead of looping the auto-resubmit forever (which
							// presents to the user as a hang). This also catches the
							// non-retryable error re-thrown from the first-chunk
							// handler in attemptApiRequest().
							if (isNonRetryableApiError(error)) {
								taskLog.error(
									`[Task#${this.taskId}.${this.instanceId}] Non-retryable API error (authentication/authorization); aborting task: ${streamingFailedMessage}`,
								)
								this.abortReason = "streaming_failed"
								await this.abortTask()
								break
							}

							// THE BOUND (see `api-retry-budget.ts`) — the safety net
							// for the failures the classifier above cannot recognise.
							// Either the first-chunk handler already exhausted the
							// budget and threw (in which case the count is done), or
							// this mid-stream failure is the one to count.
							const budgetExceeded =
								error instanceof ApiRetryBudgetExceededError ? error : await this.noteApiFailure(error)

							if (budgetExceeded) {
								taskLog.error(`[Task#${this.taskId}.${this.instanceId}] ${budgetExceeded.message}`)
								// Say it as well as log it: a headless controller sees
								// the task abort and must be able to read WHY.
								await this.say("error", budgetExceeded.message)
								this.abortReason = "streaming_failed"
								await this.abortTask()
								break
							}

							// Stream failed - log the error and retry with the same content
							// The existing rate limiting will prevent rapid retries
							taskLog.error(
								`[Task#${this.taskId}.${this.instanceId}] Stream failed, will retry: ${streamingFailedMessage}`,
							)

							// Apply exponential backoff similar to first-chunk errors when auto-resubmit is enabled
							const stateForBackoff = await this.providerRef.deref()?.getState()
							if (stateForBackoff?.autoApprovalEnabled) {
								await this.backoffAndAnnounce(currentItem.retryAttempt ?? 0, error)

								// Check if task was aborted during the backoff
								if (this.abort) {
									taskLog.info(
										`[Task#${this.taskId}.${this.instanceId}] Task aborted during mid-stream retry backoff`,
									)
									// Abort the entire task
									this.abortReason = "user_cancelled"
									await this.abortTask()
									break
								}
							}

							// Push the same content back onto the stack to retry, incrementing the retry attempt counter
							stack.push({
								userContent: currentUserContent,
								includeFileDetails: false,
								retryAttempt: (currentItem.retryAttempt ?? 0) + 1,
							})

							// Continue to retry the request
							continue
						}
					}
				} finally {
					this.isStreaming = false
					// Clean up the abort controller when streaming completes
					this.currentRequestAbortController = undefined
				}

				// Need to call here in case the stream was aborted.
				if (this.abort || this.abandoned) {
					throw new Error(
						`[Shofer#recursivelyMakeRooRequests] task ${this.taskId}.${this.instanceId} aborted`,
					)
				}

				this.didCompleteReadingStream = true

				// NOTE: api_req_finished is emitted later, after the tools for this
				// request have actually executed (see below, post-pWaitFor). Emitting
				// here would drain an empty `_pendingToolSpans` — tool execution runs
				// in presentAssistantMessage *after* the stream finishes reading.

				// Set any blocks to be complete to allow `presentAssistantMessage`
				// to finish and set `userMessageContentReady` to true.
				// (Could be a text block that had no subsequent tool uses, or a
				// text block at the very end, or an invalid tool use, etc. Whatever
				// the case, `presentAssistantMessage` relies on these blocks either
				// to be completed or the user to reject a block in order to proceed
				// and eventually set userMessageContentReady to true.)

				// Finalize any remaining streaming tool calls that weren't explicitly ended
				// This is critical for MCP tools which need tool_call_end events to be properly
				// converted from ToolUse to McpToolUse via finalizeStreamingToolCall()
				const finalizeEvents = this.nativeToolCallParser.finalizeRawChunks()
				for (const event of finalizeEvents) {
					if (event.type === "tool_call_end") {
						// Finalize the streaming tool call
						const finalToolUse = this.nativeToolCallParser.finalizeStreamingToolCall(event.id)

						this.captureToolCallTelemetry(undefined, finalToolUse)

						// Get the index for this tool call
						const toolUseIndex = this.streamingToolCallIndices.get(event.id)

						if (finalToolUse) {
							// Store the tool call ID
							// eslint-disable-next-line @typescript-eslint/no-explicit-any
							;(finalToolUse as any).id = event.id

							// Get the index and replace partial with final
							if (toolUseIndex !== undefined) {
								this.assistantMessageContent[toolUseIndex] = finalToolUse
							}

							// Clean up tracking
							this.streamingToolCallIndices.delete(event.id)

							// Mark that we have new content to process
							this.userMessageContentReady = false

							// Present the finalized tool call
							presentAssistantMessage(this)
						} else if (toolUseIndex !== undefined) {
							// finalizeStreamingToolCall returned null (malformed JSON or missing args)
							// Clear the stale partial nativeArgs so presentAssistantMessage's guard
							// (isKnownTool && !block.nativeArgs) fires and surfaces the error instead
							// of silently dispatching the tool with incomplete arguments.
							const existingToolUse = this.assistantMessageContent[toolUseIndex]
							if (existingToolUse && existingToolUse.type === "tool_use") {
								existingToolUse.partial = false
								existingToolUse.nativeArgs = undefined
								// Ensure it has the ID for native protocol
								// eslint-disable-next-line @typescript-eslint/no-explicit-any
								;(existingToolUse as any).id = event.id
							}

							// Clean up tracking
							this.streamingToolCallIndices.delete(event.id)

							// Mark that we have new content to process
							this.userMessageContentReady = false

							// Present the tool call — nativeArgs was cleared above so
							// presentAssistantMessage's §C guard will surface the error.
							await this.dismissToolPreparingRow()
							presentAssistantMessage(this)
						}
					}
				}
				// Dismiss any remaining tool_preparing rows after all tools finalized.
				await this.dismissToolPreparingRow()

				// IMPORTANT: Capture partialBlocks AFTER finalizeRawChunks() to avoid double-presentation.
				// Tools finalized above are already presented, so we only want blocks still partial after finalization.
				const partialBlocks = this.assistantMessageContent.filter((block) => block.partial)
				partialBlocks.forEach((block) => (block.partial = false))

				// Can't just do this b/c a tool could be in the middle of executing.
				// this.assistantMessageContent.forEach((e) => (e.partial = false))

				// No legacy streaming parser to finalize.

				// Note: updateApiReqMsg() is now called from within drainStreamInBackgroundToFindAllUsage
				// to ensure usage data is captured even when the stream is interrupted. The background task
				// uses local variables to accumulate usage data before atomically updating the shared state.

				// Complete the reasoning message if it exists
				// We can't use say() here because the reasoning message may not be the last message
				// (other messages like text blocks or tool uses may have been added after it during streaming)
				if (reasoningMessage) {
					const lastReasoningIndex = findLastIndex(
						this.shoferMessages,
						(m) => m.type === "say" && m.say === "reasoning",
					)

					if (lastReasoningIndex !== -1 && this.shoferMessages[lastReasoningIndex]!.partial) {
						this.shoferMessages[lastReasoningIndex]!.partial = false
						await this.updateShoferMessage(this.shoferMessages[lastReasoningIndex]!)
					}
				}

				await this._debouncedSaveShoferMessages()
				// Skinny push removed — per-message deltas keep shoferMessages
				// in sync; taskHistoryItemUpdated covers history.

				// No legacy text-stream tool parser state to reset.

				// CRITICAL: Save assistant message to API history BEFORE executing tools.
				// This ensures that when new_task triggers delegation and calls flushPendingToolResultsToHistory(),
				// the assistant message is already in history. Otherwise, tool_result blocks would appear
				// BEFORE their corresponding tool_use blocks, causing API errors.

				// Check if we have any content to process (text or tool uses)
				const hasTextContent = assistantMessage.length > 0

				const hasToolUses = this.assistantMessageContent.some(
					(block) => block.type === "tool_use" || block.type === "mcp_tool_use",
				)

				if (hasTextContent || hasToolUses) {
					// Reset counter when we get a successful response with content
					this.consecutiveNoAssistantMessagesCount = 0
					// Display grounding sources to the user if they exist
					if (pendingGroundingSources.length > 0) {
						const citationLinks = pendingGroundingSources.map((source, i) => `[${i + 1}](${source.url})`)
						const sourcesText = `${t("common:gemini.sources")} ${citationLinks.join(", ")}`

						await this.say("text", sourcesText, undefined, false, undefined, {
							isNonInteractive: true,
						})
					}

					// Build the assistant message content array
					const assistantContent: Array<Anthropic.TextBlockParam | Anthropic.ToolUseBlockParam> = []

					// Add text content if present
					if (assistantMessage) {
						assistantContent.push({
							type: "text" as const,
							text: assistantMessage,
						})
					}

					// Add tool_use blocks with their IDs for native protocol
					// This handles both regular ToolUse and McpToolUse types
					// IMPORTANT: Track seen IDs to prevent duplicates in the API request.
					// Duplicate tool_use IDs cause Anthropic API 400 errors:
					// "tool_use ids must be unique"
					const seenToolUseIds = new Set<string>()
					const toolUseBlocks = this.assistantMessageContent.filter(
						(block) => block.type === "tool_use" || block.type === "mcp_tool_use",
					)
					for (const block of toolUseBlocks) {
						if (block.type === "mcp_tool_use") {
							// McpToolUse already has the original tool name (e.g., "mcp_serverName_toolName")
							// The arguments are the raw tool arguments (matching the simplified schema)
							const mcpBlock = block as import("@shofer/types").McpToolUse
							if (mcpBlock.id) {
								const sanitizedId = sanitizeToolUseId(mcpBlock.id)
								// Pre-flight deduplication: Skip if we've already added this ID
								if (seenToolUseIds.has(sanitizedId)) {
									taskLog.warn(
										`[Task#${this.taskId}] Pre-flight deduplication: Skipping duplicate MCP tool_use ID: ${sanitizedId} (tool: ${mcpBlock.name})`,
									)
									continue
								}
								seenToolUseIds.add(sanitizedId)
								assistantContent.push({
									type: "tool_use" as const,
									id: sanitizedId,
									name: mcpBlock.name, // Original dynamic name
									input: mcpBlock.arguments, // Direct tool arguments
								})
							}
						} else {
							// Regular ToolUse
							const toolUse = block as import("@shofer/types").ToolUse
							const toolCallId = toolUse.id
							if (toolCallId) {
								const sanitizedId = sanitizeToolUseId(toolCallId)
								// Pre-flight deduplication: Skip if we've already added this ID
								if (seenToolUseIds.has(sanitizedId)) {
									taskLog.warn(
										`[Task#${this.taskId}] Pre-flight deduplication: Skipping duplicate tool_use ID: ${sanitizedId} (tool: ${toolUse.name})`,
									)
									continue
								}
								seenToolUseIds.add(sanitizedId)
								// nativeArgs is already in the correct API format for all tools
								const input = toolUse.nativeArgs || toolUse.params

								// Use originalName (alias) if present for API history consistency.
								// When tool aliases are used (e.g., "edit_file" -> "search_and_replace" -> "edit" (current canonical name)),
								// we want the alias name in the conversation history to match what the model
								// was told the tool was named, preventing confusion in multi-turn conversations.
								const toolNameForHistory = toolUse.originalName ?? toolUse.name

								assistantContent.push({
									type: "tool_use" as const,
									id: sanitizedId,
									name: toolNameForHistory,
									input,
								})
							}
						}
					}

					// `new_task` needs no isolation. It used to have to be the last tool in
					// a turn — and, when repeated, every call had to be a background one —
					// because a SYNCHRONOUS child disposed the parent, orphaning any tool
					// that came after it. Every child is concurrent now: the parent keeps
					// running, nothing is disposed, and fan-out in one turn is the normal
					// way to spawn several children (docs/parallelism.md).

					// Save assistant message BEFORE executing tools
					// This is critical for new_task: when it triggers delegation, flushPendingToolResultsToHistory()
					// will save the user message with tool_results. The assistant message must already be in history
					// so that tool_result blocks appear AFTER their corresponding tool_use blocks.
					await this.addToApiConversationHistory(
						{ role: "assistant", content: assistantContent },
						reasoningMessage || undefined,
					)
					this.assistantMessageSavedToHistory = true

					TelemetryService.instance.captureConversationMessage(this.taskId, "assistant")
				}

				// Present any partial blocks that were just completed.
				// Tool calls are typically presented during streaming via tool_call_partial events,
				// but we still present here if any partial blocks remain (e.g., malformed streams).
				// NOTE: This MUST happen AFTER saving the assistant message to API history.
				// When new_task is in the batch, it triggers delegation which calls flushPendingToolResultsToHistory().
				// If the assistant message isn't saved yet, tool_results would appear before tool_use blocks.
				if (partialBlocks.length > 0) {
					// If there is content to update then it will complete and
					// update `this.userMessageContentReady` to true, which we
					// `pWaitFor` before making the next request.
					presentAssistantMessage(this)
				}

				if (hasTextContent || hasToolUses) {
					// NOTE: This comment is here for future reference - this was a
					// workaround for `userMessageContent` not getting set to true.
					// It was due to it not recursively calling for partial blocks
					// when `didRejectTool`, so it would get stuck waiting for a
					// partial block to complete before it could continue.
					// In case the content blocks finished it may be the api stream
					// finished after the last parsed content block was executed, so
					// we are able to detect out of bounds and set
					// `userMessageContentReady` to true (note you should not call
					// `presentAssistantMessage` since if the last block i
					//  completed it will be presented again).
					// const completeBlocks = this.assistantMessageContent.filter((block) => !block.partial) // If there are any partial blocks after the stream ended we can consider them invalid.
					// if (this.currentStreamingContentIndex >= completeBlocks.length) {
					// 	this.userMessageContentReady = true
					// }

					await pWaitFor(() => this.userMessageContentReady)

					// Tools for this request have now executed, so `_pendingToolSpans`
					// is fully populated. Emit the immutable api_req_finished span here
					// (not at stream-read end) so its toolSpans[] actually reflect the
					// tools that ran during this request.
					await this.emitApiReqFinished("completed")

					this.diagLog(
						`[DIAG recursivelyMakeShoferRequests] After tools executed: taskId=${this.taskId}.${this.instanceId}, abort=${this.abort}, userMessageContent length=${this.userMessageContent.length}`,
					)

					// If the model did not tool use, then we need to tell it to
					// either use a tool or attempt_completion.
					const didToolUse = this.assistantMessageContent.some(
						(block) => block.type === "tool_use" || block.type === "mcp_tool_use",
					)

					this.diagLog(
						`[DIAG recursivelyMakeShoferRequests] Tool usage check: didToolUse=${didToolUse}, consecutiveNoToolUseCount=${this.consecutiveNoToolUseCount}`,
					)

					if (!didToolUse && this.toolCallingDisabled) {
						// CONVERSATIONAL TURN. This task has no tool plane, so a
						// complete text-only reply is not a mistake — it is the
						// deliverable, and it has already been streamed to the
						// caller. Nudging it with `noToolsUsed()` would demand a
						// tool that was never sent and would burn the mistake
						// budget on correct behaviour.
						//
						// Terminal-State Queue-Drain Rule: check the queue BEFORE
						// declaring terminal state. A message queued while the
						// agent was speaking continues the conversation — it is
						// the next user turn, not a new task.
						const queued = this.messageQueueService.isEmpty()
							? undefined
							: this.messageQueueService.dequeueMessage()

						if (queued) {
							taskLog.info(
								`[Task#${this.taskId}] Conversational turn: draining queued message instead of completing`,
							)
							await this.say("user_feedback", queued.text ?? "", queued.images)
							this.userMessageContent.push({
								type: "text",
								text: `<user_message>\n${queued.text ?? ""}\n</user_message>`,
							})
							this.userMessageContent.push(...formatResponse.imageBlocks(queued.images))
						} else {
							// Self-Declared Terminal State Rule: no `ask`, no
							// approval. The text was already said, so nothing is
							// re-rendered as a completion_result — emitting the
							// event and aborting the loop is the whole terminal
							// step. The task stays resumable (`resumeTask` /
							// `sendMessage`), exactly as an attempt_completion-
							// completed task does.
							// `well` — the agent answered as asked. There is no
							// self-assessment to read here (that is a parameter of
							// the `attempt_completion` tool this task does not have).
							emitTaskCompleted(this, "well")
							this.abort = true
							return true
						}
					} else if (!didToolUse) {
						// Increment consecutive no-tool-use counter
						this.consecutiveNoToolUseCount++

						// Only show error and count toward mistake limit after 2 consecutive failures
						if (this.consecutiveNoToolUseCount >= 2) {
							await this.say("error", "MODEL_NO_TOOLS_USED")
							// Only count toward mistake limit after second consecutive failure
							this.consecutiveMistakeCount++
						}

						// Use the task's locked protocol for consistent behavior
						this.userMessageContent.push({
							type: "text",
							text: formatResponse.noToolsUsed(),
						})
					} else {
						// Reset counter when tools are used successfully
						this.consecutiveNoToolUseCount = 0
					}

					// Push to stack if there's content OR if we're paused waiting for a subtask.
					// When paused, we push an empty item so the loop continues to the pause check.
					if (this.userMessageContent.length > 0 || this.isPaused) {
						this.diagLog(
							`[DIAG recursivelyMakeShoferRequests] Pushing to stack and continuing loop: userMessageContent length=${this.userMessageContent.length}, isPaused=${this.isPaused}`,
						)
						stack.push({
							userContent: [...this.userMessageContent], // Create a copy to avoid mutation issues
							includeFileDetails: false, // Subsequent iterations don't need file details
						})

						// Add periodic yielding to prevent blocking
						await new Promise((resolve) => setImmediate(resolve))
					}

					this.diagLog(
						`[DIAG recursivelyMakeShoferRequests] Continuing stack loop: stack length=${stack.length}`,
					)
					continue
				} else {
					// If there's no assistant_responses, that means we got no text
					// or tool_use content blocks from API which we should assume is
					// an error.

					// This request DID reach a stream end — it simply returned
					// nothing — so it gets its span like any other. Without it the
					// retry that follows opens a new request and re-arms the
					// needs-emit flag, and the empty one is the single shape of
					// failure that leaves no record at all: the throwing path is
					// covered by `abortStream` and the normal path by the emit
					// above.
					await this.emitApiReqFinished("error")

					// Increment consecutive no-assistant-messages counter
					this.consecutiveNoAssistantMessagesCount++

					// Only show error and count toward mistake limit after 2 consecutive failures
					// This provides a "grace retry" - first failure retries silently
					if (this.consecutiveNoAssistantMessagesCount >= 2) {
						await this.say("error", "MODEL_NO_ASSISTANT_MESSAGES")
					}

					// IMPORTANT: We already added the user message to
					// apiConversationHistory at line 1876. Since the assistant failed to respond,
					// we need to remove that message before retrying to avoid having two consecutive
					// user messages (which would cause tool_result validation errors).
					const state = await this.providerRef.deref()?.getState()
					if (this.apiConversationHistory.length > 0) {
						const lastMessage = this.apiConversationHistory[this.apiConversationHistory.length - 1]!
						if (lastMessage.role === "user") {
							// Remove the last user message that we added earlier
							this.apiConversationHistory.pop()
						}
					}

					// Check if we should auto-retry or prompt the user
					// Reuse the state variable from above
					if (state?.autoApprovalEnabled) {
						// Auto-retry with backoff - don't persist failure message when retrying
						await this.backoffAndAnnounce(
							currentItem.retryAttempt ?? 0,
							new Error(
								"Unexpected API Response: The language model did not provide any assistant messages. This may indicate an issue with the API or the model's output.",
							),
						)

						// Check if task was aborted during the backoff
						if (this.abort) {
							taskLog.info(
								`[Task#${this.taskId}.${this.instanceId}] Task aborted during empty-assistant retry backoff`,
							)
							break
						}

						// Push the same content back onto the stack to retry, incrementing the retry attempt counter
						// Mark that user message was removed so it gets re-added on retry
						stack.push({
							userContent: currentUserContent,
							includeFileDetails: false,
							retryAttempt: (currentItem.retryAttempt ?? 0) + 1,
							userMessageWasRemoved: true,
						})

						// Continue to retry the request
						continue
					} else {
						// Prompt the user for retry decision
						const { response } = await this.ask(
							"api_req_failed",
							"The model returned no assistant messages. This may indicate an issue with the API or the model's output.",
						)

						if (response === "yesButtonClicked") {
							await this.say("api_req_retried")

							// Push the same content back to retry
							stack.push({
								userContent: currentUserContent,
								includeFileDetails: false,
								retryAttempt: (currentItem.retryAttempt ?? 0) + 1,
							})

							// Continue to retry the request
							continue
						} else {
							// User declined to retry
							// Re-add the user message we removed.
							await this.addToApiConversationHistory({
								role: "user",
								content: currentUserContent,
							})

							await this.say(
								"error",
								"Unexpected API Response: The language model did not provide any assistant messages. This may indicate an issue with the API or the model's output.",
							)

							await this.addToApiConversationHistory({
								role: "assistant",
								content: [{ type: "text", text: "Failure: I did not provide a response." }],
							})
						}
					}
				}

				// If we reach here without continuing, return false (will always be false for now)
				return false
				// eslint-disable-next-line @typescript-eslint/no-unused-vars
			} catch (error) {
				// This should never happen since the only thing that can throw an
				// error is the attemptApiRequest, which is wrapped in a try catch
				// that sends an ask where if noButtonClicked, will clear current
				// task and destroy this instance. However to avoid unhandled
				// promise rejection, we will end this loop which will end execution
				// of this instance (see `startTask`).
				return true // Needs to be true so parent loop knows to end task.
			}
		}

		// If we exit the while loop normally (stack is empty), return false
		return false
	}

	/**
	 * Emit tool-call instrumentation for a single parsed native tool call (audit:
	 * tool-call-recovery, Phases 2–3). Fires on every parse — canonical, aliased,
	 * or unknown — so per-model dialect distribution and alias hit-rates become
	 * measurable, and drains any silent recovery-layer firings the parser recorded
	 * for this call. `emittedName` is the pre-resolution name the model produced.
	 * Best-effort: telemetry must never break the parse/dispatch path.
	 */
	private captureToolCallTelemetry(emittedName: string | undefined, toolUse: ToolUse | McpToolUse | null): void {
		try {
			const modelId = this.api.getModel().id
			if (toolUse) {
				const tu = toolUse as { name: string; originalName?: string; params?: Record<string, unknown> }
				const resolvedName = tu.name
				const emitted = emittedName ?? tu.originalName ?? resolvedName
				TelemetryService.instance.captureToolCallResolved(this.taskId, {
					modelId,
					emittedName: emitted,
					resolvedName,
					wasAliased: emitted !== resolvedName,
					wasUnknown: false,
					argKeys: tu.params ? Object.keys(tu.params) : [],
				})
			} else {
				TelemetryService.instance.captureToolCallResolved(this.taskId, {
					modelId,
					emittedName: emittedName ?? "(unknown)",
					wasAliased: false,
					wasUnknown: true,
				})
			}
			// Drain recovery-layer firings recorded during this (synchronous) parse.
			for (const recovery of NativeToolCallParser.consumeRecoveries()) {
				TelemetryService.instance.captureToolRecovery(this.taskId, { modelId, ...recovery })
			}
		} catch {
			// Instrumentation is best-effort; never let it break tool dispatch.
		}
	}

	/**
	 * Build the system prompt.
	 *
	 * It carries NO per-turn state, deliberately: the system prompt is the
	 * provider's prompt-cache prefix, and anything that changes per turn
	 * invalidates it on every request. Inbound mail is rendered into
	 * `environment_details` instead (`getEnvironmentDetails`), which already
	 * changes per turn because it carries the clock. This method is also called
	 * for the condense/truncation summarizers, which is the second reason
	 * nothing consumable may be drained here — a summarizer prompt would eat it
	 * before the agent ever saw it.
	 */
	private async getSystemPrompt(): Promise<string> {
		const state = await this.providerRef.deref()?.getState()
		const {
			mode,
			customModes,
			customModePrompts,
			customInstructions,
			experiments,
			language,
			apiConfiguration,
			enableSubfolderRules,
			useAgentRules,
			mcpEnabled,
			includeMarkdownFormattingSection,
			includeToolUseSection,
			includeCapabilitiesSection,
			includeModesSection,
			includeRulesSection,
			includeObjectiveSection,
		} = state ?? {}

		const provider = this.providerRef.deref()
		if (!provider) {
			throw new Error("Provider not available")
		}

		const modelInfo = this.api.getModel().info
		const taskMode = this._taskMode || (mode ?? defaultModeSlug)

		// A task may carry a per-task `agentRole`.
		// Layer it on top of the user's custom instructions so it actually shapes
		// the agent's behavior. Scoped
		// to this task only; the mode's roleDefinition is untouched.
		const effectiveCustomInstructions = this.agentRole?.trim()
			? `# Agent Role\n\n${this.agentRole.trim()}${customInstructions ? `\n\n${customInstructions}` : ""}`
			: customInstructions

		// A task may override system-prompt components via its
		// `context { ... }`; each absent key inherits the global default.
		const ctx = this.agentContext
		const effectiveUseAgentRules = ctx?.include_agents_md ?? useAgentRules ?? true
		const effectiveEnableSubfolderRules = ctx?.include_subfolder_rules ?? enableSubfolderRules ?? true

		// Workspace-relative paths this task has touched (read/mentioned/edited).
		// Subfolder AGENTS.md and `paths:`-scoped rules load on demand from this
		// set, so it participates in the prompt cache key: touching a file in a
		// new directory rebuilds the prompt and pulls that directory's rules in.
		let touchedPaths: string[] = []
		try {
			touchedPaths = await this.fileContextTracker.getTouchedFilePaths()
		} catch {
			// Rule gating degrades to "nothing extra loaded"; never block the prompt.
		}
		const effectiveIncludeModeRules = ctx?.include_mode_rules ?? true
		const effectiveIncludeUserRules = ctx?.include_user_rules ?? true
		const effectiveIncludeSkills = ctx?.include_skills ?? true
		const effectiveRequireTodos =
			ctx?.require_todos ?? getHost().config.get<boolean>(Package.name, "newTaskRequireTodos", false)
		const effectiveIncludeSystemInfo = ctx?.include_system_info ?? true
		const effectiveIncludeMcp = ctx?.include_mcp ?? true
		// A conversational task gets the minimal (tool-free) prompt variant.
		const effectiveToolCallingEnabled = !this.toolCallingDisabled

		// Section gates: per-task `agentContext` first, then the GLOBAL setting a
		// deployment publishes (its config bundle materializes the global
		// `.shofer/` scope), then "included". The global layer is what makes these
		// safe to use at scale: the prompt stays byte-identical from turn to turn,
		// which is the condition for the provider's prompt-prefix cache to hit.
		const effectiveIncludeMarkdownFormatting =
			ctx?.include_markdown_formatting ?? includeMarkdownFormattingSection ?? true
		const effectiveIncludeToolUse = ctx?.include_tool_use ?? includeToolUseSection ?? true
		const effectiveIncludeCapabilities = ctx?.include_capabilities ?? includeCapabilitiesSection ?? true
		const effectiveIncludeModes = ctx?.include_modes ?? includeModesSection ?? true
		const effectiveIncludeRules = ctx?.include_rules ?? includeRulesSection ?? true
		const effectiveIncludeObjective = ctx?.include_objective ?? includeObjectiveSection ?? true

		// H15: Build a cache key covering every stable input to the system
		// prompt.  Peer notifications + subtask constraints are appended
		// below; they don't participate in the cache key because they are
		// always fresh per request.
		//
		// Tradeoff: the MCP server-set ID is folded into the key so a server
		// that finishes connecting mid-turn invalidates the cache.  Previously
		// every request re-read MCP state; now we accept a bounded staleness
		// window of one turn.  The cache is cleared at turn start and on
		// context-management events.
		const cacheKey = [
			taskMode,
			this.cwd,
			effectiveCustomInstructions ?? "",
			JSON.stringify(experiments ?? {}),
			language ?? "",
			effectiveUseAgentRules,
			effectiveEnableSubfolderRules,
			effectiveIncludeModeRules,
			effectiveIncludeUserRules,
			effectiveIncludeSkills,
			effectiveRequireTodos,
			effectiveIncludeSystemInfo,
			effectiveIncludeMcp,
			// Section gates: republishing a bundle with one flipped must rebuild
			// the prompt rather than serve the cached one.
			effectiveIncludeMarkdownFormatting,
			effectiveIncludeToolUse,
			effectiveIncludeCapabilities,
			effectiveIncludeModes,
			effectiveIncludeRules,
			effectiveIncludeObjective,
			// Two different prompts; a task with tools off must never reuse a
			// cached tools-on prompt (or vice versa).
			effectiveToolCallingEnabled,
			// The mode's full-schema tier decides whether the tool-use and
			// capabilities sections explain describe_tools, so republishing a mode
			// that starts (or stops) stubbing must rebuild the prompt.
			JSON.stringify(resolveModeConfig(taskMode, customModes).tools_full_schema ?? null),
			JSON.stringify(this.agentToolGroups ?? null),
			JSON.stringify(this.agentContext ?? null),
			apiConfiguration?.todoListEnabled ?? true,
			modelInfo?.isStealthModel ?? false,
			this.api.getModel().id,
			mcpEnabled ?? true,
			// Fold the MCP server-set ID so a connecting server mid-turn busts the cache.
			this._mcpServerSetId ?? "",
			// shoferIgnore instructions are derived from files; include as cache bust.
			this.shoferIgnoreController?.getInstructions() ?? "",
			// Touched paths gate on-demand rule loading; a newly-touched file must
			// bust the cache so its directory's rules can enter the prompt.
			touchedPaths.join(","),
		].join("|")

		let systemPrompt: string
		if (this._cachedSystemPromptBase !== null && this._cachedSystemPromptKey === cacheKey) {
			systemPrompt = this._cachedSystemPromptBase
		} else {
			// H17: MCP-connect gate only fires on cache miss — sidesteps the
			// per-request pWaitFor overhead when the cache is hot.
			let mcpHub: McpHub | undefined
			// When no host factory is registered (headless / non-VS-Code), MCP is
			// simply unavailable and we skip the connect gate. When a factory IS
			// registered but fails to yield a hub, that's a real error we surface.
			const mcpHubFactory = getMcpHubFactory()
			if ((mcpEnabled ?? true) && mcpHubFactory) {
				mcpHub = await mcpHubFactory(provider)
				if (!mcpHub) {
					throw new Error("Failed to get MCP hub from server manager")
				}
				await pWaitFor(() => !mcpHub!.isConnecting, { timeout: 10_000 }).catch(() => {
					taskLog.error("MCP servers failed to connect in time")
				})
				// Capture the server-set ID for cache-key participation (see H15).
				this._mcpServerSetId = mcpHub
					.getServers()
					.map((s) => s.name)
					.sort()
					.join(",")
			}

			const shoferIgnoreInstructions = this.shoferIgnoreController?.getInstructions()

			systemPrompt = await SYSTEM_PROMPT(
				provider.context as Parameters<typeof SYSTEM_PROMPT>[0],
				this.cwd,
				false,
				mcpHub,
				this.diffStrategy,
				taskMode,
				customModePrompts,
				customModes,
				effectiveCustomInstructions,
				experiments,
				language,
				shoferIgnoreInstructions,
				{
					todoListEnabled: apiConfiguration?.todoListEnabled ?? true,
					useAgentRules: effectiveUseAgentRules,
					// Gate the CAPABILITIES prose to the agent's actual tool groups so a
					// tool-restricted agent isn't told it can read/write/execute.
					agentToolGroups: this.agentToolGroups,
					enableSubfolderRules: effectiveEnableSubfolderRules,
					touchedPaths,
					newTaskRequireTodos: effectiveRequireTodos,
					isStealthModel: modelInfo?.isStealthModel,
					// Per-agent context overrides.
					includeModeRules: effectiveIncludeModeRules,
					includeUserRules: effectiveIncludeUserRules,
					includeSkills: effectiveIncludeSkills,
					includeSystemInfo: effectiveIncludeSystemInfo,
					includeMcp: effectiveIncludeMcp,
					// Section gates (deployment-wide `include*Section` settings, or a
					// per-task override).
					includeMarkdownFormatting: effectiveIncludeMarkdownFormatting,
					includeToolUse: effectiveIncludeToolUse,
					includeCapabilities: effectiveIncludeCapabilities,
					includeModes: effectiveIncludeModes,
					includeRules: effectiveIncludeRules,
					includeObjective: effectiveIncludeObjective,
					// No tool plane ⇒ the minimal conversational prompt.
					toolCallingEnabled: effectiveToolCallingEnabled,
				},
				undefined, // todoList
				this.api.getModel().id,
				provider.getSkillsManager() as Parameters<typeof SYSTEM_PROMPT>[15],
			)

			this._cachedSystemPromptBase = systemPrompt
			this._cachedSystemPromptKey = cacheKey
		}

		// The rest of the method appends subtask constraints and peer
		// notifications — these are always fresh per request.

		// Inject subtask constraints for any child task (sync or background).
		// Provides role awareness so the subtask knows it is working on behalf of
		// a parent and what tools / behaviors are available to it.
		if (this.parentTaskId) {
			const constraints: string[] = []
			constraints.push("SUBTASK CONSTRAINTS")
			constraints.push("")

			// Role awareness — always injected.
			if (this.isBackground) {
				constraints.push(
					"- You are a sub-task spawned by a parent task, which is running concurrently with you. Your result is delivered to the parent when you call attempt_completion. If you need a decision only the parent can make, ask_followup_question reaches it. Otherwise work independently — the user is not watching you.",
				)
				constraints.push(
					"- The parent may cancel you at any time via the cancel_tasks tool. Checkpoint partial results in your attempt_completion so the parent can recover useful work even if you are stopped early.",
				)
				constraints.push(
					"- If you genuinely need clarification, you may call ask_followup_question — your question will be routed to the parent task (NOT the user). Keep the question concise and self-contained, and only ask when you cannot make a reasonable judgment on your own.",
				)
			} else {
				constraints.push(
					"- You are a synchronous sub-task spawned by a parent task. The parent is blocked waiting for your result. Complete your work and return a concise attempt_completion result.",
				)
				constraints.push(
					"- Do not ask the user follow-up questions — the parent cannot answer them. If you need clarification, make your best judgment and proceed.",
				)
			}

			// Peer messaging awareness — when knownPeers has more than just the parent,
			// tell the subtask about its available peer communication tools.
			const nonParentPeers = this.knownPeers ? [...this.knownPeers].filter((id) => id !== this.parentTaskId) : []
			if (nonParentPeers.length > 0) {
				constraints.push("")
				constraints.push(
					"- Mailbox: use `send_message` to write to a peer, `reply` to answer a request in your mailbox, and `wait` to read it. `list_background_tasks` finds peers.",
				)
				constraints.push(
					`  Known peer task IDs: ${nonParentPeers.join(", ")}. Use list_background_tasks(scope="peers") to discover more.`,
				)
			} else if (this.knownPeers && this.parentTaskId && this.knownPeers.has(this.parentTaskId)) {
				// Even with parent-only peers, let the child know it CAN message the parent.
				constraints.push("")
				constraints.push(
					`- Mailbox: use send_message to write to your parent (task ID: ${this.parentTaskId}) if needed, reply to answer a request in your mailbox, and wait to read it. Use list_background_tasks(scope="peers") to discover sibling tasks.`,
				)
			}

			// Soft constraints — injected when specified by the parent.
			if (this.softResultLength) {
				if (constraints.length > 2) {
					constraints.push("")
				}
				constraints.push(
					`- Result length suggestion: ${this.softResultLength} characters (soft guidance — aim to keep your attempt_completion result within this budget by summarizing concisely; the parent may accept longer results).`,
				)
				constraints.push(
					`  Hard safety cap: ${MAX_SUBTASK_RESULT_LENGTH} characters (results exceeding this will be truncated).`,
				)
			}
			if (this.softTimeoutSec) {
				constraints.push(
					`- Estimated timeout: ${this.softTimeoutSec} seconds (soft guidance — the parent may wait longer and you may take longer). Pace your work accordingly.`,
				)
			}
			systemPrompt = systemPrompt + "\n\n====\n\n" + constraints.join("\n")
		}

		return systemPrompt
	}

	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	private getCurrentProfileId(state: any): string {
		return (
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			state?.listApiConfigMeta?.find((profile: any) => profile.name === state?.currentApiConfigName)?.id ??
			"default"
		)
	}

	// H16: Build a stable string key for the tool-array cache.
	private _buildToolsCacheKey(
		mode: string | undefined,
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		state: any,
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		apiConfiguration: any,
		supportsAllowedFunctionNames: boolean,
	): string {
		return [
			mode ?? "",
			JSON.stringify(state?.customModes ?? []),
			JSON.stringify(state?.experiments ?? {}),
			JSON.stringify(state?.disabledTools ?? []),
			JSON.stringify(apiConfiguration ?? {}),
			supportsAllowedFunctionNames,
			this.api.getModel().id,
			JSON.stringify(this.completionSchema ?? null),
			JSON.stringify(this.agentToolGroups ?? null),
			// Plugins load asynchronously (fire-and-forget); fold the registry revision in
			// so the cached tool catalog rebuilds once a plugin's tools register — otherwise
			// a task that built tools before the plugin loaded would never see e.g.
			// `ask_live_memory`, even though the system prompt (rebuilt per request) shows it.
			pluginRegistry.revision,
		].join("|")
	}

	// H16: Lazy-compute the tool array, reusing across context-management
	// and main-request call sites within the same attemptApiRequest.
	private async _getOrBuildTools(
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		provider: any,
		mode: string | undefined,
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		state: any,
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		apiConfiguration: any,
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		modelInfo: any,
	): Promise<import("openai").default.Chat.ChatCompletionTool[]> {
		// For _getOrBuildTools we always pass includeAllToolsWithRestrictions=false
		// (context management call sites don't need the Gemini split).
		const cacheKey = this._buildToolsCacheKey(mode, state, apiConfiguration, false)
		if (this._cachedToolsResult && this._cachedToolsKey === cacheKey) {
			return this._cachedToolsResult.tools
		}
		if (!provider) {
			return []
		}
		const toolsResult = await buildNativeToolsArrayWithRestrictions({
			provider,
			cwd: this.cwd,
			mode,
			customModes: state?.customModes,
			experiments: state?.experiments,
			apiConfiguration: this.toolBuildSettings(apiConfiguration),
			disabledTools: state?.disabledTools,
			modelInfo,
			includeAllToolsWithRestrictions: false,
			completionSchema: this.completionSchema,
			titleLocked: this.nameLocked,
			agentToolGroups: this.agentToolGroups,
		})
		this._cachedToolsResult = {
			tools: toolsResult.tools,
			allowedFunctionNames: toolsResult.allowedFunctionNames,
		}
		this._cachedToolsKey = cacheKey
		return toolsResult.tools
	}

	private async handleContextWindowExceededError(): Promise<void> {
		const state = await this.providerRef.deref()?.getState()
		const { profileThresholds = {}, apiConfiguration } = state ?? {}
		// Use the task's own mode for context-management tool building
		// so a background task sees its own mode's tools.
		const mode = this._taskMode || defaultModeSlug

		const { contextTokens } = this.getTokenUsage()
		const modelInfo = this.api.getModel().info

		const maxTokens = getModelMaxOutputTokens({
			modelId: this.api.getModel().id,
			model: modelInfo,
			settings: this.apiConfiguration,
		})

		const contextWindow = modelInfo.contextWindow

		// Get the current profile ID using the helper method
		const currentProfileId = this.getCurrentProfileId(state)

		// Log the context window error for debugging
		taskLog.warn(
			`[Task#${this.taskId}] Context window exceeded for model ${this.api.getModel().id}. ` +
				`Current tokens: ${contextTokens}, Context window: ${contextWindow}. ` +
				`Forcing truncation to ${FORCED_CONTEXT_REDUCTION_PERCENT}% of current context.`,
		)
		// Send condenseTaskContextStarted to show in-progress indicator
		await this.providerRef.deref()?.postMessageToWebview({ type: "condenseTaskContextStarted", text: this.taskId })

		// Build tools for condensing metadata (same tools used for normal API calls)
		const provider = this.providerRef.deref()
		let allTools: import("openai").default.Chat.ChatCompletionTool[] = []
		if (provider) {
			const toolsResult = await buildNativeToolsArrayWithRestrictions({
				provider: provider as Parameters<typeof buildNativeToolsArrayWithRestrictions>[0]["provider"],
				cwd: this.cwd,
				mode,
				customModes: state?.customModes,
				experiments: state?.experiments,
				apiConfiguration: this.toolBuildSettings(apiConfiguration),
				disabledTools: state?.disabledTools,
				modelInfo,
				includeAllToolsWithRestrictions: false,
				completionSchema: this.completionSchema,
				titleLocked: this.nameLocked,
				agentToolGroups: this.agentToolGroups,
			})
			allTools = toolsResult.tools
		}

		// Build metadata with tools and taskId for the condensing API call
		const metadata: ApiHandlerCreateMessageMetadata = {
			mode,
			taskId: this.taskId,
			...this.taskTreeMetadata(),
			...(allTools.length > 0
				? {
						tools: allTools,
						tool_choice: "auto",
						parallelToolCalls: true,
					}
				: {}),
		}

		try {
			// Generate environment details to include in the condensed summary
			const environmentDetails = await getEnvironmentDetails(this, true)

			// Force aggressive truncation by keeping only 75% of the conversation history
			const truncateResult = await manageContext({
				messages: this.apiConversationHistory,
				totalTokens: contextTokens || 0,
				maxTokens,
				contextWindow,
				apiHandler: this.api,
				autoCondenseContext: true,
				autoCondenseContextPercent: FORCED_CONTEXT_REDUCTION_PERCENT,
				systemPrompt: await this.getSystemPrompt(),
				taskId: this.taskId,
				profileThresholds,
				currentProfileId,
				metadata,
				environmentDetails,
			})

			if (truncateResult.messages !== this.apiConversationHistory) {
				await this.overwriteApiConversationHistory(truncateResult.messages)
			}

			// Clear loaded skills BEFORE the persisting `say` calls below — the
			// truncation/overwrite above drops previously-loaded skill
			// instructions from the conversation, so the metadata save those
			// `say`s trigger must persist the cleared set (see condenseContext for
			// the crash-window rationale).
			this.loadedSkills.clear()
			// H15: Context-window-exceeded (truncation/condensation) invalidates the cache.
			this._cachedSystemPromptBase = null
			this._cachedSystemPromptKey = ""

			if (truncateResult.summary) {
				const { summary, cost, prevContextTokens, newContextTokens = 0 } = truncateResult
				const contextCondense: ContextCondense = { summary, cost, newContextTokens, prevContextTokens }
				await this.say(
					"condense_context",
					undefined /* text */,
					undefined /* images */,
					false /* partial */,
					undefined /* progressStatus */,
					{ isNonInteractive: true } /* options */,
					contextCondense,
				)
			} else if (truncateResult.truncationId) {
				// Sliding window truncation occurred (fallback when condensing fails or is disabled)
				const contextTruncation: ContextTruncation = {
					truncationId: truncateResult.truncationId,
					messagesRemoved: truncateResult.messagesRemoved ?? 0,
					prevContextTokens: truncateResult.prevContextTokens,
					newContextTokens: truncateResult.newContextTokensAfterTruncation ?? 0,
				}
				await this.say(
					"sliding_window_truncation",
					undefined /* text */,
					undefined /* images */,
					false /* partial */,
					undefined /* progressStatus */,
					{ isNonInteractive: true } /* options */,
					undefined /* contextCondense */,
					contextTruncation,
				)
			}
		} finally {
			// Notify webview that context management is complete (removes in-progress spinner)
			// IMPORTANT: Must always be sent to dismiss the spinner, even on error
			await this.providerRef
				.deref()
				?.postMessageToWebview({ type: "condenseTaskContextResponse", text: this.taskId })
		}
	}

	/**
	 * Enforce the user-configured provider rate limit.
	 *
	 * NOTE: This is intentionally treated as expected behavior and is surfaced via
	 * the `api_req_rate_limit_wait` say type (not an error).
	 */
	private async maybeWaitForProviderRateLimit(retryAttempt: number): Promise<void> {
		const state = await this.providerRef.deref()?.getState()
		const rateLimitSeconds =
			state?.apiConfiguration?.rateLimitSeconds ?? this.apiConfiguration?.rateLimitSeconds ?? 0

		if (rateLimitSeconds <= 0 || !Task.lastGlobalApiRequestTime) {
			return
		}

		const now = performance.now()
		const timeSinceLastRequest = now - Task.lastGlobalApiRequestTime
		const rateLimitDelay = Math.ceil(
			Math.min(rateLimitSeconds, Math.max(0, rateLimitSeconds * 1000 - timeSinceLastRequest) / 1000),
		)

		// Only show the countdown UX on the first attempt. Retry flows have their own delay messaging.
		if (rateLimitDelay > 0 && retryAttempt === 0) {
			for (let i = rateLimitDelay; i > 0; i--) {
				// Send structured JSON data for i18n-safe transport
				const delayMessage = JSON.stringify({ seconds: i })
				await this.say("api_req_rate_limit_wait", delayMessage, undefined, true)
				await delay(1000)
			}
			// Finalize the partial message so the UI doesn't keep rendering an in-progress spinner.
			await this.say("api_req_rate_limit_wait", undefined, undefined, false)
		}
	}

	public async *attemptApiRequest(
		retryAttempt: number = 0,
		options: { skipProviderRateLimit?: boolean } = {},
	): ApiStream {
		const state = await this.providerRef.deref()?.getState()

		const {
			apiConfiguration,
			autoApprovalEnabled,
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			requestDelaySeconds,
			mode,
			autoCondenseContext = true,
			autoCondenseContextPercent = 90,
			profileThresholds = {},
		} = state ?? {}

		// Get condensing configuration for automatic triggers.
		const customCondensingPrompt = state?.customSupportPrompts?.CONDENSE

		if (!options.skipProviderRateLimit) {
			await this.maybeWaitForProviderRateLimit(retryAttempt)
		}

		// Update last request time right before making the request so that subsequent
		// requests — even from new subtasks — will honour the provider's rate-limit.
		//
		// NOTE: When recursivelyMakeShoferRequests handles rate limiting, it sets the
		// timestamp earlier to include the environment details build. We still set it
		// here for direct callers (tests) and for the case where we didn't rate-limit
		// in the caller.
		Task.lastGlobalApiRequestTime = performance.now()

		// Real agent request: drain + inject any pending async peer notifications here
		// (and only here) so condensation/truncation summary prompts can't consume them.
		const systemPrompt = await this.getSystemPrompt()
		const { contextTokens } = this.getTokenUsage()

		if (contextTokens) {
			const modelInfo = this.api.getModel().info

			const maxTokens = getModelMaxOutputTokens({
				modelId: this.api.getModel().id,
				model: modelInfo,
				settings: this.apiConfiguration,
			})

			const contextWindow = modelInfo.contextWindow

			// Get the current profile ID using the helper method
			const currentProfileId = this.getCurrentProfileId(state)
			// Check if context management will likely run (threshold check)
			// This allows us to show an in-progress indicator to the user
			// We use the centralized willManageContext helper to avoid duplicating threshold logic
			const lastMessage = this.apiConversationHistory[this.apiConversationHistory.length - 1]
			const lastMessageContent = lastMessage?.content
			let lastMessageTokens = 0
			if (lastMessageContent) {
				lastMessageTokens = Array.isArray(lastMessageContent)
					? await this.api.countTokens(lastMessageContent)
					: await this.api.countTokens([{ type: "text", text: lastMessageContent as string }])
			}

			const contextManagementWillRun = willManageContext({
				totalTokens: contextTokens,
				contextWindow,
				maxTokens,
				autoCondenseContext,
				autoCondenseContextPercent,
				profileThresholds,
				currentProfileId,
				lastMessageTokens,
			})

			// Send condenseTaskContextStarted BEFORE manageContext to show in-progress indicator
			// This notification must be sent here (not earlier) because the early check uses stale token count
			// (before user message is added to history), which could incorrectly skip showing the indicator
			if (contextManagementWillRun && autoCondenseContext) {
				await this.providerRef
					.deref()
					?.postMessageToWebview({ type: "condenseTaskContextStarted", text: this.taskId })
			}

			// H16: Reuse the main tool-array build result for context management.
			// The main call below uses the same (mode, cwd, experiments, ...)
			// params; the only difference is includeAllToolsWithRestrictions
			// (false here, variable there).  Passing all tools as a superset
			// to the condensing API call is harmless — it just gets extra
			// tool definitions it won't invoke.
			const _provider = this.providerRef.deref()
			const contextMgmtTools: import("openai").default.Chat.ChatCompletionTool[] = _provider
				? await this._getOrBuildTools(_provider, mode, state, apiConfiguration, modelInfo)
				: []

			// Build metadata with tools and taskId for the condensing API call
			const contextMgmtMetadata: ApiHandlerCreateMessageMetadata = {
				mode,
				taskId: this.taskId,
				...this.taskTreeMetadata(),
				...(contextMgmtTools.length > 0
					? {
							tools: contextMgmtTools,
							tool_choice: "auto",
							parallelToolCalls: true,
						}
					: {}),
			}

			// Only generate environment details when context management will actually run.
			// getEnvironmentDetails(this, true) triggers a recursive workspace listing which
			// adds overhead - avoid this for the common case where context is below threshold.
			const contextMgmtEnvironmentDetails = contextManagementWillRun
				? await getEnvironmentDetails(this, true)
				: undefined

			// Get files read by Shofer for code folding - only when context management will run
			const contextMgmtFilesReadByRoo =
				contextManagementWillRun && autoCondenseContext
					? await this.getFilesReadByRooSafely("attemptApiRequest")
					: undefined

			try {
				const truncateResult = await manageContext({
					messages: this.apiConversationHistory,
					totalTokens: contextTokens,
					maxTokens,
					contextWindow,
					apiHandler: this.api,
					autoCondenseContext,
					autoCondenseContextPercent,
					systemPrompt,
					taskId: this.taskId,
					customCondensingPrompt,
					profileThresholds,
					currentProfileId,
					metadata: contextMgmtMetadata,
					environmentDetails: contextMgmtEnvironmentDetails,
					filesReadByRoo: contextMgmtFilesReadByRoo,
					cwd: this.cwd,
					shoferIgnoreController: this.shoferIgnoreController,
				})
				if (truncateResult.messages !== this.apiConversationHistory) {
					await this.overwriteApiConversationHistory(truncateResult.messages)
				}

				// Clear loaded skills BEFORE the persisting `say` calls below — the
				// overwrite above drops previously-loaded skill instructions from the
				// conversation, so the metadata save those `say`s trigger must persist
				// the cleared set (see condenseContext for the crash-window rationale).
				this.loadedSkills.clear()
				// H15: In-request context management invalidates the cache.
				this._cachedSystemPromptBase = null
				this._cachedSystemPromptKey = ""

				if (truncateResult.error) {
					if (truncateResult.truncationId) {
						// Condensation failed but sliding window truncation succeeded as fallback.
						// Log the condensation error to the output channel instead of alarming the user
						// in chat — the fallback handled it and the conversation continues normally.
						this.diagLog(
							`[Task#${this.taskId}] Context condensation failed (${truncateResult.error}). ` +
								`Fallback sliding window truncation succeeded ` +
								`(removed ${truncateResult.messagesRemoved ?? 0} messages). ` +
								(truncateResult.errorDetails ? `Details: ${truncateResult.errorDetails}` : ""),
						)
					} else {
						// No fallback available — surface the error to the user
						await this.say("condense_context_error", truncateResult.error)
					}
				}
				if (truncateResult.summary) {
					const { summary, cost, prevContextTokens, newContextTokens = 0, condenseId } = truncateResult
					const contextCondense: ContextCondense = {
						summary,
						cost,
						newContextTokens,
						prevContextTokens,
						condenseId,
					}
					await this.say(
						"condense_context",
						undefined /* text */,
						undefined /* images */,
						false /* partial */,
						undefined /* progressStatus */,
						{ isNonInteractive: true } /* options */,
						contextCondense,
					)
				} else if (truncateResult.truncationId) {
					// Sliding window truncation occurred (fallback when condensing fails or is disabled)
					const contextTruncation: ContextTruncation = {
						truncationId: truncateResult.truncationId,
						messagesRemoved: truncateResult.messagesRemoved ?? 0,
						prevContextTokens: truncateResult.prevContextTokens,
						newContextTokens: truncateResult.newContextTokensAfterTruncation ?? 0,
					}
					await this.say(
						"sliding_window_truncation",
						undefined /* text */,
						undefined /* images */,
						false /* partial */,
						undefined /* progressStatus */,
						{ isNonInteractive: true } /* options */,
						undefined /* contextCondense */,
						contextTruncation,
					)
				}
			} finally {
				// Notify webview that context management is complete (sets isCondensing = false)
				// This removes the in-progress spinner and allows the completed result to show
				// IMPORTANT: Must always be sent to dismiss the spinner, even on error
				if (contextManagementWillRun && autoCondenseContext) {
					await this.providerRef
						.deref()
						?.postMessageToWebview({ type: "condenseTaskContextResponse", text: this.taskId })
				}
			}
		}

		// Get the effective API history by filtering out condensed messages
		// This allows non-destructive condensing where messages are tagged but not deleted,
		// enabling accurate rewind operations while still sending condensed history to the API.
		const effectiveHistory = getEffectiveApiHistory(this.apiConversationHistory)
		const messagesSinceLastSummary = getMessagesSinceLastSummary(effectiveHistory)
		// For API only: merge consecutive user messages (excludes summary messages per
		// mergeConsecutiveApiMessages implementation) without mutating stored history.
		const mergedForApi = mergeConsecutiveApiMessages(messagesSinceLastSummary, { roles: ["user"] })
		const messagesWithoutImages = maybeRemoveImageBlocks(mergedForApi, this.api)
		const cleanConversationHistory = this.buildCleanConversationHistory(messagesWithoutImages as ApiMessage[])

		// Check auto-approval limits
		const approvalResult = await this.autoApprovalHandler.checkAutoApprovalLimits(
			state,
			this.combineMessages(this.shoferMessages.slice(1)),
			async (type, data) => this.ask(type, data),
		)

		if (!approvalResult.shouldProceed) {
			// User did not approve, task should be aborted
			throw new Error("Auto-approval limit reached and user did not approve continuation")
		}

		// H16: Reuse the cached tool-array result from above.
		// For non-Gemini providers the context-management and main calls produce
		// identical results; for Gemini the context-management call passes all
		// tools (harmless superset).  The cached result already includes
		// allowedFunctionNames when includeAllToolsWithRestrictions was requested.
		const supportsAllowedFunctionNames = apiConfiguration?.apiProvider === "gemini"

		let allTools: OpenAI.Chat.ChatCompletionTool[]
		let allowedFunctionNames: string[] | undefined

		if (
			this._cachedToolsResult &&
			this._cachedToolsKey ===
				this._buildToolsCacheKey(mode, state, apiConfiguration, supportsAllowedFunctionNames)
		) {
			allTools = this._cachedToolsResult.tools
			allowedFunctionNames = this._cachedToolsResult.allowedFunctionNames
		} else {
			const provider = this.providerRef.deref()
			if (!provider) {
				throw new Error("Provider reference lost during tool building")
			}
			const toolsResult = await buildNativeToolsArrayWithRestrictions({
				provider: provider as Parameters<typeof buildNativeToolsArrayWithRestrictions>[0]["provider"],
				cwd: this.cwd,
				mode,
				customModes: state?.customModes,
				experiments: state?.experiments,
				apiConfiguration: this.toolBuildSettings(apiConfiguration),
				disabledTools: state?.disabledTools,
				modelInfo: this.api.getModel().info,
				includeAllToolsWithRestrictions: supportsAllowedFunctionNames,
				completionSchema: this.completionSchema,
				titleLocked: this.nameLocked,
				agentToolGroups: this.agentToolGroups,
			})
			this._cachedToolsResult = {
				tools: toolsResult.tools,
				allowedFunctionNames: toolsResult.allowedFunctionNames,
			}
			this._cachedToolsKey = this._buildToolsCacheKey(mode, state, apiConfiguration, supportsAllowedFunctionNames)
			allTools = toolsResult.tools
			allowedFunctionNames = toolsResult.allowedFunctionNames
		}

		const shouldIncludeTools = allTools.length > 0

		const metadata: ApiHandlerCreateMessageMetadata = {
			mode: mode,
			taskId: this.taskId,
			...this.taskTreeMetadata(),
			suppressPreviousResponseId: this.skipPrevResponseIdOnce,
			// Include tools whenever they are present.
			...(shouldIncludeTools
				? {
						tools: allTools,
						tool_choice: "auto",
						parallelToolCalls: true,
						// When mode restricts tools, provide allowedFunctionNames so providers
						// like Gemini can see all tools in history but only call allowed ones
						...(allowedFunctionNames ? { allowedFunctionNames } : {}),
					}
				: {}),
		}

		// Create an AbortController to allow cancelling the request mid-stream
		this.currentRequestAbortController = new AbortController()
		const abortSignal = this.currentRequestAbortController.signal
		// Reset the flag after using it
		this.skipPrevResponseIdOnce = false

		// Capture wire-level request metadata for export diagnostics.
		// Persisted alongside the api_req_started entry so the JSON export
		// can show what was actually sent to the provider.
		const wireRequest = JSON.stringify({
			model: this.api.getModel().id,
			apiProtocol: getApiProtocol(
				apiConfiguration?.apiProvider && !isRetiredProvider(apiConfiguration.apiProvider)
					? apiConfiguration.apiProvider
					: undefined,
				this.api.getModel().id,
			),
			systemPromptLength: systemPrompt.length,
			messageCount: cleanConversationHistory.length,
			toolCount: allTools.length,
			messages: cleanConversationHistory,
			tools: allTools.length > 0 ? allTools : undefined,
			// Include a truncated form of the system prompt for context.
			systemPromptHead: systemPrompt.slice(0, 500),
		})

		// LLM API instrumentation — record timing for Prometheus histograms/counters.
		// `apiProvider` is the canonical source for the provider label; never
		// fall back to `modelId` (it pollutes the label cardinality with
		// model identifiers and is semantically wrong — see prometheus.md §7.6).
		const _llmProvider = apiConfiguration?.apiProvider ?? "unknown"
		const _llmModelId = this.api.getModel().id
		const _llmT0 = performance.now()

		// The provider accepts reasoning items alongside standard messages; cast to the expected parameter type.
		// §4.3: expand `<shofer-blob .../>` references back to full content
		// for messages selected for this outgoing request. Messages dropped
		// by sliding-window truncation above never reach this step and so
		// pay neither the disk read nor the context-tokens cost.
		const resolvedConversationHistory = await this.prepareMessagesForApi(
			cleanConversationHistory as unknown as Anthropic.Messages.MessageParam[],
		)
		const stream = this.api.createMessage(systemPrompt, resolvedConversationHistory, metadata)

		const iterator = stream[Symbol.asyncIterator]()

		// Persist the wire request into the api_req_started entry so the
		// JSON export can surface it.
		this.snapshotWireRequest(wireRequest)

		// Set up abort handling - when the signal is aborted, clean up the controller reference
		abortSignal.addEventListener("abort", () => {
			taskLog.info(`[Task#${this.taskId}.${this.instanceId}] AbortSignal triggered for current request`)
			this.currentRequestAbortController = undefined
		})

		try {
			// Awaiting first chunk to see if it will throw an error.
			this.isWaitingForFirstChunk = true

			// Race between the first chunk and the abort signal
			const firstChunkPromise = iterator.next()
			const abortPromise = new Promise<never>((_, reject) => {
				if (abortSignal.aborted) {
					reject(new Error("Request cancelled by user"))
				} else {
					abortSignal.addEventListener("abort", () => {
						reject(new Error("Request cancelled by user"))
					})
				}
			})

			const firstChunk = await Promise.race([firstChunkPromise, abortPromise])
			//this.diagLog(
			//	`[Task#${this.taskId}] [STREAM_PASSTHROUGH] Yielding FIRST chunk type=${firstChunk.value?.type}, preview=${JSON.stringify(firstChunk.value)?.slice(0, 200)}`,
			//)
			yield firstChunk.value
			this.isWaitingForFirstChunk = false
		} catch (error) {
			this.isWaitingForFirstChunk = false
			this.currentRequestAbortController = undefined

			// Record LLM API error for Prometheus.
			recordLlmDuration(_llmProvider, _llmModelId, performance.now() - _llmT0)
			incLlmCalls(_llmProvider, _llmModelId, "error")
			incLlmErrors(_llmProvider, _llmModelId, classifyLlmError(error))
			// Persist structured error info into api_req_started for export diagnostics.
			this.snapshotApiReqError(this.buildApiReqError(error))

			const isContextWindowExceededError = checkContextWindowExceededError(error)

			// If it's a context window error and we haven't exceeded max retries for this error type
			if (isContextWindowExceededError && retryAttempt < MAX_CONTEXT_WINDOW_RETRIES) {
				taskLog.warn(
					`[Task#${this.taskId}] Context window exceeded for model ${this.api.getModel().id}. ` +
						`Retry attempt ${retryAttempt + 1}/${MAX_CONTEXT_WINDOW_RETRIES}. ` +
						`Attempting automatic truncation...`,
				)
				await this.handleContextWindowExceededError()
				// Retry the request after handling the context window error
				yield* this.attemptApiRequest(retryAttempt + 1)
				return
			}

			// note that this api_req_failed ask is unique in that we only present this option if the api hasn't streamed any content yet (ie it fails on the first chunk due), as it would allow them to hit a retry button. However if the api failed mid-stream, it could be in any arbitrary state where some tools may have executed, so that error is handled differently and requires cancelling the task entirely.
			if (autoApprovalEnabled) {
				// Permanent authentication/authorization failures (HTTP 401/403)
				// will never succeed on retry. Re-throw the original error (which
				// carries the HTTP status) so the streaming consumer's
				// non-retryable guard aborts the task, instead of spinning the
				// backoff loop forever — which presents to the user as a hang.
				if (isNonRetryableApiError(error)) {
					throw error
				}

				// THE BOUND (see `api-retry-budget.ts`): the classifier above only
				// knows the failures we have seen. A connection error carries no
				// evidence either way, so the loop is stopped on COUNT — enough
				// consecutive failures with no successful request in between and
				// the task fails loudly, quoting the provider's own error, rather
				// than retrying behind an exponential backoff indefinitely.
				const budgetExceeded = await this.noteApiFailure(error)
				if (budgetExceeded) {
					taskLog.error(`[Task#${this.taskId}.${this.instanceId}] ${budgetExceeded.message}`)
					throw budgetExceeded
				}

				// Apply shared exponential backoff and countdown UX
				await this.backoffAndAnnounce(retryAttempt, error)

				// CRITICAL: Check if task was aborted during the backoff countdown
				// This prevents infinite loops when users cancel during auto-retry
				// Without this check, the recursive call below would continue even after abort
				if (this.abort) {
					throw new Error(
						`[Task#attemptApiRequest] task ${this.taskId}.${this.instanceId} aborted during retry`,
					)
				}

				// Delegate generator output from the recursive call with
				// incremented retry count.
				yield* this.attemptApiRequest(retryAttempt + 1)

				return
			} else {
				const { response } = await this.ask(
					"api_req_failed",
					error instanceof Error ? error.message : JSON.stringify(serializeError(error), null, 2),
				)

				if (response !== "yesButtonClicked") {
					// This will never happen since if noButtonClicked, we will
					// clear current task, aborting this instance.
					throw new Error("API request failed")
				}

				await this.say("api_req_retried")

				// Delegate generator output from the recursive call.
				yield* this.attemptApiRequest()
				return
			}
		}

		// No error, so we can continue to yield all remaining chunks.
		// (Needs to be placed outside of try/catch since it we want caller to
		// handle errors not with api_req_failed as that is reserved for first
		// chunk failures only.)
		// This delegates to another generator or iterable object. In this case,
		// it's saying "yield all remaining values from this iterator". This
		// effectively passes along all subsequent chunks from the original
		// stream.
		// Manual loop with debug logging to trace chunk flow
		for await (const chunk of { [Symbol.asyncIterator]: () => iterator }) {
			// this.diagLog(
			// 	`[Task#${this.taskId}] [STREAM_PASSTHROUGH] Yielding chunk type=${chunk?.type}, preview=${JSON.stringify(chunk)?.slice(0, 200)}`,
			// )
			yield chunk
		}

		// The stream drained without error — this is the ONE place where a
		// request is observably successful end to end (a first chunk proves
		// nothing; a stream can still die mid-flight), so it is where the
		// consecutive-failure streak behind the retry bound is cleared.
		this.resetApiFailureStreak()

		// Record successful LLM API call.
		recordLlmDuration(_llmProvider, _llmModelId, performance.now() - _llmT0)
		incLlmCalls(_llmProvider, _llmModelId, "success")
	}

	/**
	 * Persist the wire-level request metadata into the last `api_req_started`
	 * ShoferMessage so the JSON task-export can surface what was sent.
	 */
	private snapshotWireRequest(wireRequest: string): void {
		const idx = findLastIndex(this.shoferMessages, (m) => m.say === "api_req_started")
		if (idx < 0 || !this.shoferMessages[idx]) return
		try {
			const existing = JSON.parse(this.shoferMessages[idx].text || "{}")
			this.shoferMessages[idx].text = JSON.stringify({
				...existing,
				wireRequest,
			})
		} catch {
			/* best effort */
		}
	}

	/**
	 * Build a structured {@link ApiReqError} payload from a thrown error for
	 * persistence alongside the {@link ShoferApiReqInfo}.
	 */
	private buildApiReqError(error: unknown): ApiReqError {
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		const e = error as any
		return {
			message: e instanceof Error ? e.message : JSON.stringify(error),
			type: e?.type || e?.name || undefined,
			statusCode: typeof e?.status === "number" ? e.status : undefined,
			stack: e instanceof Error ? e.stack : undefined,
		}
	}

	/**
	 * Merge a structured error payload into the last `api_req_started` message.
	 */
	private snapshotApiReqError(reqError: ApiReqError): void {
		const idx = findLastIndex(this.shoferMessages, (m) => m.say === "api_req_started")
		if (idx < 0 || !this.shoferMessages[idx]) return
		try {
			const existing = JSON.parse(this.shoferMessages[idx].text || "{}")
			this.shoferMessages[idx].text = JSON.stringify({
				...existing,
				error: reqError,
			})
		} catch {
			/* best effort */
		}
	}

	/**
	 * Count one failed API request against the retry BOUND and report whether the
	 * budget is now exhausted.
	 *
	 * Called from every site that is about to retry AUTOMATICALLY — the
	 * first-chunk handler in {@link attemptApiRequest} and the mid-stream handler
	 * in `recursivelyMakeShoferRequests`. The interactive path is deliberately
	 * not counted: it asks the user instead of looping, so it cannot hang.
	 *
	 * @returns the error to fail with when the budget is exhausted, otherwise
	 * `undefined` (keep retrying).
	 */
	private async noteApiFailure(error: unknown): Promise<ApiRetryBudgetExceededError | undefined> {
		this.consecutiveApiFailures++

		const state = await this.providerRef.deref()?.getState()
		const limit = resolveMaxConsecutiveApiFailures(state?.maxConsecutiveApiFailures)

		if (this.consecutiveApiFailures < limit) {
			return undefined
		}

		return new ApiRetryBudgetExceededError(this.consecutiveApiFailures, limit, error)
	}

	/** A request completed: the failure streak, if any, is over. */
	private resetApiFailureStreak(): void {
		this.consecutiveApiFailures = 0
	}

	// Shared exponential backoff for retries (first-chunk and mid-stream)
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	private async backoffAndAnnounce(retryAttempt: number, error: any): Promise<void> {
		try {
			const state = await this.providerRef.deref()?.getState()
			const baseDelay = state?.requestDelaySeconds || 5

			let exponentialDelay = Math.min(
				Math.ceil(baseDelay * Math.pow(2, retryAttempt)),
				MAX_EXPONENTIAL_BACKOFF_SECONDS,
			)

			// Respect provider rate limit window
			let rateLimitDelay = 0
			const rateLimit = (state?.apiConfiguration ?? this.apiConfiguration)?.rateLimitSeconds || 0
			if (Task.lastGlobalApiRequestTime && rateLimit > 0) {
				const elapsed = performance.now() - Task.lastGlobalApiRequestTime
				rateLimitDelay = Math.ceil(Math.min(rateLimit, Math.max(0, rateLimit * 1000 - elapsed) / 1000))
			}

			// Prefer RetryInfo on 429 if present
			if (error?.status === 429) {
				const retryInfo = error?.errorDetails?.find(
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					(d: any) => d["@type"] === "type.googleapis.com/google.rpc.RetryInfo",
				)
				const match = retryInfo?.retryDelay?.match?.(/^(\d+)s$/)
				if (match) {
					exponentialDelay = Number(match[1]) + 1
				}
			}

			const finalDelay = Math.max(exponentialDelay, rateLimitDelay)
			if (finalDelay <= 0) {
				return
			}

			// Build header text; fall back to error message if none provided
			let headerText
			if (error.status) {
				// Include both status code (for ChatRow parsing) and detailed message (for error details)
				// Format: "<status>\n<message>" allows ChatRow to extract status via parseInt(text.substring(0,3))
				// while preserving the full error message in errorDetails for debugging
				const errorMessage = error?.message || "Unknown error"
				headerText = `${error.status}\n${errorMessage}`
			} else if (error?.message) {
				headerText = error.message
			} else {
				headerText = "Unknown error"
			}

			headerText = headerText ? `${headerText}\n` : ""

			// Show countdown timer with exponential backoff
			for (let i = finalDelay; i > 0; i--) {
				// Check abort flag during countdown to allow early exit
				if (this.abort) {
					throw new Error(`[Task#${this.taskId}] Aborted during retry countdown`)
				}

				await this.say("api_req_retry_delayed", `${headerText}<retry_timer>${i}</retry_timer>`, undefined, true)
				await delay(1000)
			}

			await this.say("api_req_retry_delayed", headerText, undefined, false)
		} catch (err) {
			const message = err instanceof Error ? err.message : String(err)

			if (this.abort && message.includes("Aborted during retry countdown")) {
				return
			}

			taskLog.error("Exponential backoff failed:", err)
		}
	}

	private buildCleanConversationHistory(messages: ApiMessage[]): Array<
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		Anthropic.Messages.MessageParam | { type: "reasoning"; encrypted_content: string; id?: string; summary?: any[] }
	> {
		type ReasoningItemForRequest = {
			type: "reasoning"
			encrypted_content: string
			id?: string
			// eslint-disable-next-line @typescript-eslint/no-explicit-any
			summary?: any[]
		}

		const cleanConversationHistory: (Anthropic.Messages.MessageParam | ReasoningItemForRequest)[] = []

		for (const msg of messages) {
			// Standalone reasoning: send encrypted, skip plain text
			if (msg.type === "reasoning") {
				if (msg.encrypted_content) {
					cleanConversationHistory.push({
						type: "reasoning",
						summary: msg.summary,
						encrypted_content: msg.encrypted_content!,
						...(msg.id ? { id: msg.id } : {}),
					})
				}
				continue
			}

			// Preferred path: assistant message with embedded reasoning as first content block
			if (msg.role === "assistant") {
				const rawContent = msg.content

				const contentArray: Anthropic.Messages.ContentBlockParam[] = Array.isArray(rawContent)
					? (rawContent as Anthropic.Messages.ContentBlockParam[])
					: rawContent !== undefined
						? ([
								{ type: "text", text: rawContent } satisfies Anthropic.Messages.TextBlockParam,
							] as Anthropic.Messages.ContentBlockParam[])
						: []

				const [first, ...rest] = contentArray

				// Check if this message has reasoning_details (OpenRouter format for Gemini 3, etc.)
				const msgWithDetails = msg
				if (msgWithDetails.reasoning_details && Array.isArray(msgWithDetails.reasoning_details)) {
					// Build the assistant message with reasoning_details
					let assistantContent: Anthropic.Messages.MessageParam["content"]

					if (contentArray.length === 0) {
						assistantContent = ""
					} else if (contentArray.length === 1 && contentArray[0]!.type === "text") {
						assistantContent = (contentArray[0] as Anthropic.Messages.TextBlockParam).text
					} else {
						assistantContent = contentArray
					}

					// Create message with reasoning_details property
					cleanConversationHistory.push({
						role: "assistant",
						content: assistantContent,
						reasoning_details: msgWithDetails.reasoning_details,
						// eslint-disable-next-line @typescript-eslint/no-explicit-any
					} as any)

					continue
				}

				// Embedded reasoning: encrypted (send) or plain text (skip)
				const hasEncryptedReasoning =
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					first && (first as any).type === "reasoning" && typeof (first as any).encrypted_content === "string"
				const hasPlainTextReasoning =
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					first && (first as any).type === "reasoning" && typeof (first as any).text === "string"

				if (hasEncryptedReasoning) {
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					const reasoningBlock = first as any

					// Send as separate reasoning item (OpenAI Native)
					cleanConversationHistory.push({
						type: "reasoning",
						summary: reasoningBlock.summary ?? [],
						encrypted_content: reasoningBlock.encrypted_content,
						...(reasoningBlock.id ? { id: reasoningBlock.id } : {}),
					})

					// Send assistant message without reasoning
					let assistantContent: Anthropic.Messages.MessageParam["content"]

					if (rest.length === 0) {
						assistantContent = ""
					} else if (rest.length === 1 && rest[0]!.type === "text") {
						assistantContent = (rest[0] as Anthropic.Messages.TextBlockParam).text
					} else {
						assistantContent = rest
					}

					cleanConversationHistory.push({
						role: "assistant",
						content: assistantContent,
					} satisfies Anthropic.Messages.MessageParam)

					continue
				} else if (hasPlainTextReasoning) {
					// Check if the model's preserveReasoning flag is set
					// If true, include the reasoning block in API requests
					// If false/undefined, strip it out (stored for history only, not sent back to API)
					const shouldPreserveForApi = this.api.getModel().info.preserveReasoning === true
					let assistantContent: Anthropic.Messages.MessageParam["content"]

					if (shouldPreserveForApi) {
						// Include reasoning block in the content sent to API
						assistantContent = contentArray
					} else {
						// Strip reasoning out - stored for history only, not sent back to API
						if (rest.length === 0) {
							assistantContent = ""
						} else if (rest.length === 1 && rest[0]!.type === "text") {
							assistantContent = (rest[0] as Anthropic.Messages.TextBlockParam).text
						} else {
							assistantContent = rest
						}
					}

					cleanConversationHistory.push({
						role: "assistant",
						content: assistantContent,
					} satisfies Anthropic.Messages.MessageParam)

					continue
				}
			}

			// Default path for regular messages (no embedded reasoning)
			if (msg.role) {
				cleanConversationHistory.push({
					role: msg.role,
					content: msg.content as Anthropic.Messages.ContentBlockParam[] | string,
				})
			}
		}

		return cleanConversationHistory
	}
	// Metrics

	public combineMessages(messages: ShoferMessage[]) {
		return combineApiRequests(combineCommandSequences(messages))
	}

	public getTokenUsage(): TokenUsage {
		return getApiMetrics(this.combineMessages(this.shoferMessages.slice(1)))
	}

	public recordToolUsage(toolName: ToolName) {
		if (!this.toolUsage[toolName]) {
			this.toolUsage[toolName] = { attempts: 0, failures: 0 }
		}

		this.toolUsage[toolName].attempts++
	}

	public recordToolError(toolName: ToolName, error?: string) {
		if (!this.toolUsage[toolName]) {
			this.toolUsage[toolName] = { attempts: 0, failures: 0 }
		}

		this.toolUsage[toolName].failures++

		if (error) {
			this.emit(ShoferEventName.TaskToolFailed, this.taskId, toolName, error)
		}
	}

	// Getters

	public get taskStatus(): TaskStatus {
		if (this.interactiveAsk) {
			return TaskStatus.Interactive
		}

		if (this.resumableAsk) {
			return TaskStatus.Resumable
		}

		if (this.idleAsk) {
			return TaskStatus.Idle
		}

		return TaskStatus.Running
	}

	public get taskAsk(): ShoferMessage | undefined {
		return this.idleAsk || this.resumableAsk || this.interactiveAsk
	}

	public get queuedMessages(): QueuedMessage[] {
		return this.messageQueueService.messages
	}

	public get tokenUsage(): TokenUsage | undefined {
		if (this.tokenUsageSnapshot && this.tokenUsageSnapshotAt) {
			return this.tokenUsageSnapshot
		}

		this.tokenUsageSnapshot = this.getTokenUsage()
		this.tokenUsageSnapshotAt = this.shoferMessages.at(-1)?.ts

		return this.tokenUsageSnapshot
	}

	/**
	 * Working directory for this task. When this task is scoped to an
	 * embedded worktree (e.g. `.worktrees/repo-hl911/`), `_cwd` is the
	 * worktree subdirectory. Otherwise it defaults to `workspacePath`.
	 *
	 * Tools resolve paths relative to this directory, git operations use it
	 * as their working tree, and terminal processes are spawned here.
	 */
	private _cwd: string

	public get cwd() {
		return this._cwd
	}

	/**
	 * Re-point this task's working directory — the seam a plugin that manages
	 * worktrees needs (`ctx.task.setCwd`). Child tasks read `this.cwd` at spawn
	 * time, so anything spawned after the change runs in the new worktree.
	 *
	 * The FileContextTracker's cwd is kept in sync so that any file-change
	 * tracking performed by this task resolves against the new worktree.
	 */
	public reassignCwd(newCwd: string): void {
		this._cwd = newCwd
		this.fileContextTracker.reassignCwd(newCwd)
	}

	/**
	 * Provides convenient access to high-level message operations.
	 * Uses lazy initialization - the MessageManager is only created when first accessed.
	 * Subsequent accesses return the same cached instance.
	 *
	 * ## Important: Single Coordination Point
	 *
	 * **All MessageManager operations must go through this getter** rather than
	 * instantiating `new MessageManager(task)` directly. This ensures:
	 * - A single shared instance for consistent behavior
	 * - Centralized coordination of all rewind/message operations
	 * - Ability to add internal state or instrumentation in the future
	 *
	 * @example
	 * ```typescript
	 * // Correct: Use the getter
	 * await task.messageManager.rewindToTimestamp(ts)
	 *
	 * // Incorrect: Do NOT create new instances directly
	 * // const manager = new MessageManager(task) // Don't do this!
	 * ```
	 */
	get messageManager(): MessageManager {
		if (!this._messageManager) {
			this._messageManager = new MessageManager(this)
		}
		return this._messageManager
	}

	/**
	 * Deliver an envelope into this task's mailbox, and wake the agent if the
	 * sender asked for it and the loop has stopped.
	 *
	 * The three cases, in the order they are decided:
	 *
	 * 1. **`wake` is false** — the envelope is in the box and that is the whole
	 *    job. The agent finds it in its `environment_details` digest on its next
	 *    turn, whenever that is.
	 * 2. **The loop is RUNNING** (`!abort && !abandoned`) — nothing more to do
	 *    either. A running agent reads the digest next request, and one parked in
	 *    `wait` is returned by the `delivered` event `Mailbox` just emitted.
	 *    Interrupting a live turn is exactly the mid-turn preemption this design
	 *    removed.
	 * 3. **The loop is STOPPED and `wake` is set** — resume it by enqueueing ONE
	 *    synthesized plain-text user turn and kicking the tested Send-Now path
	 *    (`cancelAndProcessQueuedMessages`). Nothing here reimplements any part of
	 *    that path: it is what awaits the running-state persist before restarting.
	 *
	 * The wake turn is COALESCED. Two deliveries arriving back-to-back into a
	 * stopped task must not queue two identical turns — the second would be
	 * consumed as an entire wasted turn saying the same thing. The already-queued
	 * turn covers whatever arrived after it, because it does not name a message:
	 * the agent reads the whole box.
	 *
	 * Resolves once the envelope is DURABLE (the mailbox persists before
	 * returning), so a caller that acks on return is acking a fact. The wake
	 * itself is deliberately not awaited — restarting an agent loop is not
	 * something a delivery should block on.
	 *
	 * @throws {MailboxError} when the envelope is invalid, misaddressed, or the box is full.
	 */
	public async deliver(envelope: Envelope): Promise<Envelope> {
		const delivered = await this.mailbox.deliver(envelope)

		/**
		 * Record the delivery once, on every path. `woke` answers "did this
		 * envelope restart a stopped loop", which is why it is stamped where the
		 * wake actually happens rather than copied off `envelope.wake`: a
		 * coalesced second delivery carries `wake: true` and wakes nothing.
		 */
		const record = (woke: boolean) => {
			try {
				TelemetryService.instance.captureMailboxDelivered(this.taskId, {
					kind: envelope.kind,
					plane: envelope.plane,
					woke,
				})
			} catch {
				// non-fatal
			}
		}

		if (!envelope.wake) {
			record(false)
			return delivered
		}

		// Check the loop's liveness BEFORE touching the queue. `attempt_completion`
		// checks `messageQueueService.isEmpty()` before finalizing (the
		// Terminal-State Queue-Drain Rule), so a turn enqueued into a loop that is
		// still winding down would be consumed as ordinary feedback rather than
		// waking anything.
		if (!this.abort && !this.abandoned) {
			record(false)
			return delivered
		}

		const alreadyQueued = this.messageQueueService.messages.some((m) => m.text === MAILBOX_WAKE_TURN_TEXT)
		if (!alreadyQueued) {
			this.messageQueueService.addMessage(MAILBOX_WAKE_TURN_TEXT)
			void this.cancelAndProcessQueuedMessages().catch((error) =>
				taskLog.error(`[Task#${this.taskId}] mailbox wake failed:`, error),
			)
		}
		record(!alreadyQueued)

		return delivered
	}

	/**
	 * Process any queued messages by dequeuing and submitting them.
	 * This ensures that queued user messages are sent when appropriate,
	 * preventing them from getting stuck in the queue.
	 *
	 * @param context - Context string for logging (e.g., the calling tool name)
	 */
	public processQueuedMessages(): void {
		try {
			if (!this.messageQueueService.isEmpty()) {
				const queued = this.messageQueueService.dequeueMessage()
				if (queued) {
					setTimeout(() => {
						this.submitUserMessage(queued.text, queued.images).catch((err) =>
							taskLog.error(`[Task] Failed to submit queued message:`, err),
						)
					}, 0)
				}
			}
		} catch (e) {
			taskLog.error(`[Task] Queue processing error:`, e)
		}
	}

	/**
	 * Cancel the current API request and immediately send the first queued message to the LLM.
	 * This allows the user to interrupt a long-running operation and prioritize a queued message.
	 *
	 * The cancellation follows these steps:
	 * 1. Cancel the current HTTP request
	 * 2. Set abort flag to stop the task loop
	 * 3. Wait for the old task loop to fully exit
	 * 4. Clean up orphaned tool_use blocks in the API conversation history
	 * 5. Reset task state
	 * 6. Restart the task loop with the queued message
	 */
	public async cancelAndProcessQueuedMessages(): Promise<void> {
		this.diagLog(`[Task#${this.taskId}.${this.instanceId}] cancelAndProcessQueuedMessages called`)

		// Capture the next queued message BEFORE any abort plumbing runs.
		// abortTask()/dispose() (which can fire on stream cancellation paths
		// we don't fully control) wipes messageQueueService._messages — losing
		// the very message we are about to send. The soft-cancel flag below
		// is the primary defense, but capturing here makes the flow robust
		// even if a future code path slips through.
		const queued = this.messageQueueService.dequeueMessage()
		if (!queued) {
			this.diagLog(
				`[Task#${this.taskId}.${this.instanceId}] cancelAndProcessQueuedMessages: queue is empty, nothing to do`,
			)
			return
		}

		// Mark soft-cancel so the streaming catch block in
		// recursivelyMakeShoferRequests does NOT call abortTask() (which would
		// dispose this task and prevent us from restarting the loop).
		this._softCancelForQueuedMessage = true

		// Step 1: Cancel the current HTTP request if one is in progress
		if (this.currentRequestAbortController) {
			this.diagLog(`[Task] Cancelling current HTTP request`)
			this.currentRequestAbortController.abort()
			this.currentRequestAbortController = undefined
		}

		// Step 2: Set abort flag to stop the task loop
		// This will cause the initiateTaskLoop while-loop to exit on its next iteration
		this.abort = true
		// Also fire the task-lifetime abort signal so any in-flight MCP tool
		// calls (or other operations subscribed to abortSignal) bail immediately
		// instead of waiting for their per-operation timeout.
		if (!this._taskAbortController.signal.aborted) {
			this._taskAbortController.abort()
		}
		this.diagLog(`[Task] Set abort=true to stop task loop`)

		// Step 3: Wait for the old task loop to fully exit before starting a new one.
		// Without this, the old loop may still be running error-handling or retry logic
		// when the new loop starts, causing duplicate messages and corrupted API history.
		if (this._taskLoopPromise) {
			this.diagLog(`[Task] Waiting for old task loop to exit...`)
			try {
				await this._taskLoopPromise
			} catch (_) {
				// The old loop may throw due to abort — that's expected.
			}
			this.diagLog(`[Task] Old task loop has exited`)
		}

		// Step 4: Clean up orphaned tool_use blocks from the API conversation history.
		// If the HTTP request was aborted mid-stream while the assistant was emitting
		// tool_use blocks, those blocks are now in apiConversationHistory without
		// matching tool_result blocks. We must add placeholder tool_results before
		// starting a new task loop, otherwise the API will reject the request with
		// "insufficient tool messages following tool_calls message".
		this._cleanupOrphanedToolUses()

		// Step 5: Reset ask states so the task can handle the queued message
		this.idleAsk = undefined
		this.resumableAsk = undefined
		this.interactiveAsk = undefined
		this.emit(ShoferEventName.TaskActive, this.taskId)

		// Ensure the running state is durably on disk BEFORE restarting the
		// task loop. Emitting TaskActive above synchronously routes through
		// TaskManager.setState(running) → enqueuePersist; we await that exact
		// persist via the single writer rather than writing taskState directly
		// (which would violate the Single-Writer Persistence Rule and race the
		// fire-and-forget completed+rating write from attempt_completion).
		{
			const provider = this.providerRef.deref()
			if (provider?.taskManager) {
				try {
					await provider.taskManager.waitForPendingPersist(this.taskId)
				} catch {
					// Best-effort — the TaskManager chain will retry asynchronously.
				}
			}
		}

		// Step 6: Restart the task loop with the captured queued message.
		// We dequeued at the top of this method (before triggering abort) to
		// guarantee we still hold the message even if any disposal path ran.
		this.diagLog(`[Task] Restarting task loop with queued message: ${queued.text?.substring(0, 100)}`)
		// Clear soft-cancel marker — the new run is a normal task loop again.
		this._softCancelForQueuedMessage = false
		// Reset abort to allow the task loop to run
		this.abort = false
		// Replace the task-lifetime abort controller so the fresh run does
		// not see the already-aborted signal from the cancellation above.
		this._taskAbortController = new AbortController()
		// Add the queued message to the chat UI so the user can see it.
		// Without this, the message would be sent to the LLM but never
		// appear in the chat — the user's "Send Now" action would seem to
		// silently lose their message from the UI perspective.
		await this.say("user_feedback", queued.text, queued.images)

		// Start a new task loop with the queued message.
		// Wrap in <user_message> so that processUserContentMentions /
		// parseMentions can resolve slash-style skill mentions and track
		// them in Task.loadedSkills for the SkillsButton popover.
		// Append the queued images as image blocks — otherwise a pasted/dropped
		// image on a "Send Now" (queued/interrupt) message is shown in the chat
		// UI (via the say() above) but silently dropped from the LLM payload, so
		// a vision model never sees it. Mirrors startTask() and the ask-response
		// path, which both append formatResponse.imageBlocks(...).
		this._runTaskLoop([humanMessageBlock(queued.text), ...formatResponse.imageBlocks(queued.images)]).catch(
			(err) => {
				taskLog.error(`[Task] Failed to restart task loop:`, err)
			},
		)
	}

	/**
	 * Clean up orphaned tool_use and tool_result blocks in the API
	 * conversation history.
	 *
	 * **Forward pass** (tool_use → tool_result): scans for assistant messages
	 * whose tool_use blocks lack matching tool_result blocks and injects
	 * placeholder results. Prevents:
	 *
	 * 1. Aborts mid-tool-execution: the assistant was saved to history before
	 *    tools ran; on restart a new text-only assistant turn pushes the orphaned
	 *    tool_uses deeper in history where a last-message-only check misses them.
	 * 2. Context condensation: tool_use/tool_result pairs may be restructured.
	 * 3. History replay bugs: duplicate tool_call_ids can appear across turns.
	 *
	 * **Backward pass** (tool_result → tool_use): scans user messages for
	 * tool_result blocks whose matching assistant tool_use is missing (e.g. the
	 * tool was interrupted, a plain-text assistant filler separated the pair, or
	 * the matching assistant scrolled out of the message window in very long
	 * conversations). Drops orphaned tool_results to keep the conversation
	 * valid for strict providers (DeepSeek, etc.) that reject:
	 *
	 *   "Messages with role 'tool' must be a response to a preceding message
	 *    with 'tool_calls'" (HTTP 400)
	 *
	 * Operating on the Anthropic-format apiConversationHistory makes this
	 * provider-agnostic — it protects both the direct API path (Anthropic,
	 * OpenAI, Gemini) and the vscode-lm path (any VS Code LM provider).
	 */
	private _cleanupOrphanedToolUses(): void {
		if (this.apiConversationHistory.length === 0) {
			return
		}

		type HistoryMessage = {
			role: "user" | "assistant"
			content: Anthropic.Messages.ContentBlockParam[]
		}

		const history = this.apiConversationHistory as HistoryMessage[]
		const cleaned: typeof history = []
		let orphansFixed = 0

		// ── Forward pass: tool_use → tool_result ─────────────────────
		for (let i = 0; i < history.length; i++) {
			const msg = history[i]!
			cleaned.push(msg)

			// Process assistant messages that carry tool_use blocks.
			if (msg.role !== "assistant" || !Array.isArray(msg.content)) {
				continue
			}

			const toolUseIds = new Set(
				(msg.content as Anthropic.Messages.ContentBlockParam[])
					.filter((b): b is Anthropic.ToolUseBlock => b.type === "tool_use")
					.map((b) => b.id),
			)
			if (toolUseIds.size === 0) {
				continue
			}

			// Consume subsequent tool_result blocks until we hit a non-tool
			// user message, the next assistant, or end of history.
			const covered = new Set<string>()
			let j = i + 1
			while (j < history.length) {
				const next = history[j]!
				if (next.role === "assistant") {
					break // Next assistant turn — stop consuming.
				}
				if (!Array.isArray(next.content)) {
					break
				}
				const toolResults = next.content.filter(
					(b): b is Anthropic.ToolResultBlockParam => b.type === "tool_result",
				)
				if (toolResults.length === 0) {
					// User message with no tool_results (plain text) — stop.
					break
				}
				for (const tr of toolResults) {
					covered.add(tr.tool_use_id)
				}
				j++
			}

			// Collect any tool_use IDs that lack a matching tool_result.
			const missing: string[] = []
			for (const id of toolUseIds) {
				if (!covered.has(id)) {
					missing.push(id)
				}
			}

			if (missing.length > 0) {
				orphansFixed += missing.length
				this.diagLog(
					`[Task] Orphaned tool_use(s) at history index ${i}: ${missing.join(", ")}. Injecting placeholder tool_results.`,
				)
				const placeholders: Anthropic.ToolResultBlockParam[] = missing.map((id) => ({
					type: "tool_result" as const,
					tool_use_id: id,
					content: "Tool execution was interrupted before completion.",
				}))
				cleaned.push({
					role: "user",
					content: placeholders,
				})
			}
		}

		// ── Backward pass: tool_result → tool_use ────────────────────
		// Walk every user message in cleaned[] and verify that each
		// tool_result block has a preceding assistant turn with a matching
		// tool_use.  Without this, an interrupted tool call whose matching
		// assistant has scrolled out of the message window leaves behind a
		// `role:"tool"` message with no anchor — a guaranteed HTTP 400 from
		// strict providers.
		//
		// We only scan backwards from the current user message, because
		// a tool_result inside a user turn can only answer tool_uses that
		// appeared BEFORE that user turn (the API forbids forward references).
		let resultOrphansDropped = 0
		for (let i = 0; i < cleaned.length; i++) {
			const msg = cleaned[i]!
			if (msg.role !== "user" || !Array.isArray(msg.content)) {
				continue
			}

			const content = msg.content as Anthropic.Messages.ContentBlockParam[]
			const toolResultBlocks = content.filter(
				(b): b is Anthropic.ToolResultBlockParam => b.type === "tool_result",
			)
			if (toolResultBlocks.length === 0) {
				continue
			}

			// Collect every tool_use ID declared by preceding assistant turns.
			const declaredToolUses = new Set<string>()
			for (let j = i - 1; j >= 0; j--) {
				const prev = cleaned[j]!
				if (prev.role !== "assistant" || !Array.isArray(prev.content)) {
					continue
				}
				for (const block of prev.content as Anthropic.Messages.ContentBlockParam[]) {
					if (block.type === "tool_use") {
						declaredToolUses.add(block.id)
					}
				}
			}

			// Drop tool_results whose tool_use_id was never declared.
			const pruned = content.filter((b) => {
				if (b.type !== "tool_result") {
					return true // keep non-tool_result blocks (text, images, etc.)
				}
				const tr = b as Anthropic.ToolResultBlockParam
				if (declaredToolUses.has(tr.tool_use_id)) {
					return true
				}
				resultOrphansDropped++
				this.diagLog(
					`[Task] Dropping orphaned tool_result with id="${tr.tool_use_id}" ` +
						`at history index ${i} — no matching assistant tool_use found.`,
				)
				return false
			})

			if (pruned.length < content.length) {
				// Some blocks were dropped.  Replace the message if it still
				// has content, or remove it entirely.
				if (pruned.length > 0) {
					cleaned[i] = { ...msg, content: pruned }
				} else {
					// Mark for removal (set to null, filter after loop).
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					;(cleaned as any)[i] = null
				}
			}
		}

		// Remove nulled-out messages from the backward pass.
		const filteredCleaned = cleaned.filter((m) => m !== null) as typeof cleaned
		if (filteredCleaned.length < cleaned.length) {
			resultOrphansDropped += cleaned.length - filteredCleaned.length
		}

		// ── Dedup pass: duplicate tool_result for the same tool_use_id ──
		// Two adjacent user messages can each carry a tool_result for the
		// SAME tool_use_id (observed in production: a write-side race in the
		// flush / addToApiConversationHistory paths persisted two byte-identical
		// user messages — same tool_result + identical environment_details —
		// for one assistant tool_use turn). The OpenAI / DeepSeek contract is
		// "exactly one tool message per tool_call"; a second response with the
		// same id triggers HTTP 400 "Messages with role 'tool' must be a
		// response to a preceding message with 'tool_calls'" upstream.
		//
		// validateAndFixToolResultIds already dedupes WITHIN a single user
		// message (GitHub #10465). This pass extends that guarantee ACROSS
		// the user-message run between two assistant turns: within each such
		// run, every tool_use_id may answer at most once. First occurrence
		// wins; later duplicates are dropped. A user message that becomes
		// empty after dropping is removed entirely.
		let duplicatesDropped = 0
		const seenInRun = new Set<string>()
		for (let i = 0; i < filteredCleaned.length; i++) {
			const msg = filteredCleaned[i]!
			if (msg.role === "assistant") {
				seenInRun.clear()
				continue
			}
			if (msg.role !== "user" || !Array.isArray(msg.content)) {
				continue
			}
			const content = msg.content as Anthropic.Messages.ContentBlockParam[]
			const pruned = content.filter((b) => {
				if (b.type !== "tool_result") {
					return true
				}
				const tr = b as Anthropic.ToolResultBlockParam
				if (seenInRun.has(tr.tool_use_id)) {
					duplicatesDropped++
					this.diagLog(
						`[Task] Dropping duplicate tool_result with id="${tr.tool_use_id}" ` +
							`at history index ${i} — already answered earlier in the same user-message run.`,
					)
					return false
				}
				seenInRun.add(tr.tool_use_id)
				return true
			})
			if (pruned.length < content.length) {
				if (pruned.length > 0) {
					filteredCleaned[i] = { ...msg, content: pruned }
				} else {
					// eslint-disable-next-line @typescript-eslint/no-explicit-any
					;(filteredCleaned as any)[i] = null
				}
			}
		}
		const dedupedCleaned = filteredCleaned.filter((m) => m !== null) as typeof filteredCleaned

		if (orphansFixed > 0 || resultOrphansDropped > 0 || duplicatesDropped > 0) {
			this.apiConversationHistory = dedupedCleaned as ApiMessage[]
			const parts: string[] = []
			if (orphansFixed > 0) {
				parts.push(`injected ${orphansFixed} placeholder tool_result(s)`)
			}
			if (resultOrphansDropped > 0) {
				parts.push(`dropped ${resultOrphansDropped} orphaned tool_result(s)`)
			}
			if (duplicatesDropped > 0) {
				parts.push(`dropped ${duplicatesDropped} duplicate tool_result(s)`)
			}
			this.diagLog(`[Task] Conversation history cleanup: ${parts.join(", ")}.`)
		}
	}

	/**
	 * Record stream-timing milestones for the Trace/Stats phase breakdown.
	 *
	 * Three things are recorded from one call, and they answer different
	 * questions:
	 *
	 *   - the first chunk of any kind sets TTFB;
	 *   - the first non-reasoning chunk sets the generation start — the single
	 *     boundary the `api_req_finished` span publishes as `genStartOffsetMs`;
	 *   - EVERY reasoning↔output transition opens or closes a reasoning
	 *     interval, which is what a model that interleaves thinking with output
	 *     needs and what the single boundary above cannot express. A run left
	 *     open when the stream ends is closed at the request's end by
	 *     `streamPhaseFields`, so nothing has to be finalized here.
	 */
	private _markStreamProgress(isReasoning: boolean): void {
		const offset = performance.now() - this.timelineOriginMs - this._pendingRequestStartOffset
		if (this._pendingTtfbMs === null) {
			this._pendingTtfbMs = offset
		}
		if (!isReasoning && this._pendingGenStartMs === null) {
			this._pendingGenStartMs = offset
		}
		if (isReasoning) {
			if (this._pendingReasoningOpenedAtMs === null) {
				this._pendingReasoningOpenedAtMs = offset
			}
		} else if (this._pendingReasoningOpenedAtMs !== null) {
			this._pendingReasoningIntervals.push([this._pendingReasoningOpenedAtMs, offset])
			this._pendingReasoningOpenedAtMs = null
		}
	}

	/**
	 * The live stream marks for the current request, in the shape
	 * `endedApiReqInfo` takes. One accessor rather than four literals at each
	 * rewrite site, so a new mark cannot reach one payload and miss another.
	 */
	private get _streamPhaseMarks(): StreamPhaseMarks {
		return {
			ttfbMs: this._pendingTtfbMs,
			genStartOffsetMs: this._pendingGenStartMs,
			reasoningIntervalsMs: this._pendingReasoningIntervals,
			reasoningOpenedAtMs: this._pendingReasoningOpenedAtMs,
		}
	}

	/**
	 * Emit an immutable `api_req_finished` ShoferSay message.
	 *
	 * Called at stream end (success, cancellation, or error) to record the
	 * completed API request span with its tool sub-spans. The caller has
	 * already drained `this._pendingToolSpans` and computed
	 * `this._pendingTtfbMs` before invoking this.
	 *
	 * EXACTLY ONE span per request, and the guard below is the whole of that
	 * rule: three call sites race for it — the normal post-tools emit, the
	 * `abortStream` path and `abortTask`'s flush — and whichever arrives first
	 * writes, the rest no-op. The claim is taken BEFORE the write so a
	 * re-entrant call during the await cannot slip through, and RELEASED again
	 * if the write fails, so a failure leaves a later path able to try rather
	 * than silently consuming the request's only chance.
	 */
	private async emitApiReqFinished(
		status: ApiRequestFinishedPayload["status"],
		cancelReason?: ApiRequestFinishedPayload["cancelReason"],
	): Promise<void> {
		// Exactly one span per request: whichever path fires first (normal
		// post-tools emit, abortStream, or abortTask) wins; the rest are no-ops.
		if (!this._pendingApiReqNeedsEmit) {
			return
		}
		this._pendingApiReqNeedsEmit = false

		const modelId = getModelId(this.apiConfiguration)
		const apiProvider = this.apiConfiguration.apiProvider
		const apiProtocol = getApiProtocol(
			apiProvider && !isRetiredProvider(apiProvider) ? apiProvider : undefined,
			modelId,
		)

		// Collect token/cost data from the existing api_req_started message.
		const lastApiReqIndex = findLastIndex(this.shoferMessages, (m) => m.say === "api_req_started")

		let tokensIn = 0
		let tokensOut = 0
		let cacheWrites = 0
		let cacheReads = 0
		let cost = 0
		let existingData: Partial<ShoferApiReqInfo> = {}

		if (lastApiReqIndex >= 0 && this.shoferMessages[lastApiReqIndex]) {
			try {
				existingData = JSON.parse(this.shoferMessages[lastApiReqIndex].text || "{}")
				tokensIn = existingData.tokensIn ?? 0
				tokensOut = existingData.tokensOut ?? 0
				cacheWrites = existingData.cacheWrites ?? 0
				cacheReads = existingData.cacheReads ?? 0
				cost = existingData.cost ?? 0
			} catch {
				// Parse errors are non-fatal — emit with zeros.
			}
		}

		const payload: ApiRequestFinishedPayload = {
			requestIndex: this._currentRequestIndex,
			taskId: this.taskId,
			parentTaskId: this.parentTaskId ?? null,
			startedAtOffsetMs: this._pendingRequestStartOffset,
			finishedAtOffsetMs: performance.now() - this.timelineOriginMs,
			ttfbMs: this._pendingTtfbMs,
			genStartOffsetMs: this._pendingGenStartMs,
			model: modelId ?? "",
			apiProtocol: apiProtocol as "anthropic" | "openai",
			retryAttempt: existingData.retryAttempt ?? 0,
			tokensIn,
			tokensOut,
			cacheWrites,
			cacheReads,
			cost,
			status,
			cancelReason,
			// Structured error captured via snapshotApiReqError() on the
			// api_req_started message; surfaced in the Trace tooltip on error rows.
			error: existingData.error,
			actualModel: existingData.actualModel,
			attempts: existingData.attempts,
			responseError: existingData.responseError,
			toolSpans: this._pendingToolSpans,
		}

		// `allowWhenAborted` is what makes this span exist AT ALL for the last
		// request of a turn. `attempt_completion` sets `task.abort = true` as its
		// final act, and the normal emit point is downstream of it (after the
		// tools of this request have run, which is the only moment
		// `_pendingToolSpans` is complete) — so an ordinary `say` throws and the
		// terminal request of every conversation loses its end, its duration and
		// its whole built-in tool account. `abortTask`'s dedicated flush was
		// written for exactly this case and was defeated the same way.
		try {
			await this.say("api_req_finished", JSON.stringify(payload), undefined, undefined, undefined, {
				allowWhenAborted: true,
			})
		} catch (error) {
			this._pendingApiReqNeedsEmit = true
			throw error
		}

		// Lifecycle `onApiRequestFinish` (design §6.9): the host's own per-request
		// record, handed to observers rather than reassembled by each of them from
		// events. Fired after the say so the transcript is written first — an
		// observer must never be able to reorder the record it observes.
		if (pluginRegistry.hasLifecycleHook("onApiRequestFinish")) {
			void pluginRegistry
				.notifyApiRequestFinish(payload, {
					parentTaskId: this.parentTaskId,
					rootTaskId: this.rootTaskId,
					cwd: this.cwd,
					mode: this._taskMode,
					turn: this.turnCount,
				})
				.catch(() => {})
		}

		this._currentRequestIndex++
	}

	/**
	 * Emit a `task_interaction` ShoferSay message recording an inter-task
	 * communication event (spawn, message, await, answer, cancel).
	 *
	 * Called from the inter-task tool dispatch in `presentAssistantMessage`
	 * after the tool executes. `rootOffsetMs` is filled in here from the root
	 * task's timeline origin — all tasks in the extension host share the same
	 * `performance.now()` clock, so origins are directly comparable and the
	 * Sequence view can place every task's events on one shared axis.
	 *
	 * `startOffsetMs` (this task's own timeline offset, from the tool span) marks
	 * when the tool *started*. Pass it so a blocking tool (e.g. ask_followup_question,
	 * which only returns after the answer arrives) is ordered by when it was issued,
	 * not when it unblocked — otherwise the answer sorts before the question.
	 */
	async emitTaskInteraction(
		payload: Omit<TaskInteractionPayload, "rootOffsetMs">,
		startOffsetMs?: number,
	): Promise<void> {
		// Best-effort instrumentation: a Sequence-view event must never break the
		// tool that emitted it. Callers in the inter-task tools (new_task /
		// send_message) invoke this inside their own try/catch, where a
		// throw here would otherwise be misreported as a tool failure.
		try {
			const rootOriginMs = (this.rootTask ?? this).timelineOriginMs
			const atPerfMs = startOffsetMs != null ? startOffsetMs + this.timelineOriginMs : performance.now()
			const fullPayload: TaskInteractionPayload = {
				...payload,
				rootOffsetMs: atPerfMs - rootOriginMs,
			}
			await this.say("task_interaction", JSON.stringify(fullPayload))
		} catch {
			// Swallow — viz recording is non-critical.
		}
	}
}