agentHost: observe dispatched actions through a chat contribution hook (#333238)

* agentHost: report every terminal turn outcome through onTurnEnd

Closes three gaps where a turn ended without telling contributions. A turn that captured a
start checkpoint and then failed to send never scheduled its changeset recompute, because
`captureTurnStartCheckpoint` runs before `sendMessage` but the catch never reported the end.

- Reports a turn end when a send throws. This is the bug: `CheckpointAndChangesetContribution`
  handles `kind === 'error'` and never heard about these turns, so their changeset recompute
  and unread marking did not run.
- Reports a turn end for a client-dispatched cancellation, which the agent-signal path already
  did. This fires exactly once: the reducer clears the active turn first, so a later
  agent-emitted cancellation takes the no-active-turn path, which reports only completions.
- Adds a `rejected` reason for requests refused before their turn started, and fires it from
  both `startTurn` early returns: a rejected admission and a missing provider. This restores
  the per-rejection observability that hoisting the admission gate removed.
- Makes `MarkUnreadContribution` ignore `rejected`. It filtered negatively, so the new reason
  would have marked a session unread for a request that never ran, and a rejection on an
  archived session would resurface it.
- Leaves `QueueDrainContribution` untouched for `rejected`. A rejected queued turn consumes its
  message and the queue stalls, but draining would cascade an archived chat through every
  queued message. The fix is to return the message to the queue, which is recorded as such.
- Adds tests for all three paths, including that a rejected turn end does not resurface a read
  session. Both new `agentSideEffects` tests were confirmed to fail without the fix.

Rewrites `chatContributions/TODO.md` as a backlog. It had grown into a changelog of finished
extractions and a design-decision record, and two of its claims were already wrong: the
side-chat migration it listed as pending was complete, and `githubReferences` was filed under
outgoing-turn contributions although it only implements `onTurnEnd`. Rationale that had no
other home moved into JSDoc beside the code it explains.

(Commit message generated by Copilot)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* agentHost: observe dispatched actions through a chat contribution hook

Moves session input-needed aggregation, turn-usage persistence, and session flag persistence
out of `AgentSideEffects`, which loses 252 lines. All three observed
`AgentHostStateManager.onDidEmitEnvelope` rather than the client dispatch path, so none of
them could use the existing action hook: most of the actions they react to are dispatched by
the host, not by a client.

- Adds `onDidDispatchAction`, which observes an action from any origin once its outcome is
  known, including server-dispatched actions and rejected ones that never reduced. It is a
  separate hook and not a widening of the client hook, because `queueDrain` depends on that
  hook being client-only and would otherwise see each client action twice.
- Adds `SessionInputNeededContribution` (order 200), which mirrors per-chat blockers into the
  owning session's `inputNeeded` list. This is the bulk of the move at roughly 170 lines.
- Gives `PersistedTurnUsageContribution` the write half of turn-usage persistence. It already
  owned the restore half, so one contribution now owns both directions, as chat drafts and
  chat titles already do.
- Adds `SessionFlagsContribution` (order 700) for read state, archived state, and merged
  config values. It preserves an asymmetry that is easy to lose: read and archived changes
  skip a rejected action, config values do not.
- Makes `AgentHostToolCallTracker` injectable. Input-needed reports blocked and unblocked tool
  calls to it, and it was constructed inside `AgentSideEffects`, so a contribution could not
  reach it.

Renames the two action hooks so each says what it observes:

- `onAction` becomes `onDidApplyClientAction`, and `IObservedAction` becomes
  `IAppliedClientAction`. Rejected client actions never reach it, so an action it sees always
  reduced.
- `onEnvelope` becomes `onDidDispatchAction`, and `IObservedEnvelope` becomes
  `IDispatchedAction`. It also delivers rejected actions, so a name claiming they were applied
  would be wrong.

Registers the built-in contributions in the tool-call and turn-hang telemetry test graphs.
Both build `AgentSideEffects` without them, so they stopped exercising blocked-call telemetry
once that reporting moved into a contribution. The graphs now mirror production wiring; no
assertion changed.

Updates the contributions skill, which described four hooks and named two that no longer
exist. It now documents all seven, records that the admission hook fails closed and is
synchronous while every other hook isolates failures, and carries the design rationale that
`TODO.md` used to hold. `TODO.md` keeps only open work and caveats, with each fact in one
place.

(Commit message generated by Copilot)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* agentHost: fix cyclic dependency and rejected-action handling from review

- Moves `toolSourceKindFromContributor` and `canRefineContributor` into
  `node/shared/toolCallContributor.ts`. Injecting the turn tracker into the tool-call tracker
  made the two import each other at runtime, which failed the cyclic dependency check.
- Reports a turn end only when a turn actually ended. `AgentHostTurnTracker.turnCompleted` now
  returns whether it had a tracked turn, and the client cancellation and failed-send paths use
  that. The reducer no-ops a stale or duplicate cancellation, so reporting one unconditionally
  marked a read session unread for a turn that never stopped.
- Reports a turn end when a resumed turn fails to send. That path dispatched `ChatError` and
  completed tracking without telling contributions, so it stayed invisible.
- Skips rejected actions in `sessionInputNeeded` and `persistedTurnUsage`. A rejected action
  never reduced, so mirroring it can clear a blocker that is still outstanding, and persisting
  it can write durable state that was refused.
- Starts the turn through `handleAction` in the client-cancellation test, as `_dispatchActionNow`
  does. The shared `startTurn` helper only dispatches to state, so the turn was never tracked
  and the test did not reflect production wiring.
- Adds a test that a stale cancellation reports no turn end, and corrects a stale
  `_chatContributions.action(...)` reference in the backlog.

(Commit message generated by Copilot)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Dmitriy Vasyura <dmitriv@microsoft.com>

Author: 3 people

.github/skills/agent-host-chat-contributions/SKILL.md

@@ -16,14 +16,16 @@ export const IAgentHostChatContributions = createDecorator<IAgentHostChatContrib
 
 /**
  * Why a turn ended. Contributions must discriminate on `kind`: successful,
- * cancelled, failed, and host-handled local-command turns deliberately run
- * different side effects. `success`, `cancelled`, and `localCommand` carry no
- * payload on purpose; add fields only when a contribution actually needs them.
+ * cancelled, failed, rejected, and host-handled local-command turns deliberately
+ * run different side effects. A rejected request was refused or could not be
+ * routed before its turn started, so contributions that finalize started turns
+ * must ignore it because there is no turn or checkpoint to finalize.
  */
 export type TurnEndReason =
 	| { readonly kind: 'success' }
 	| { readonly kind: 'cancelled' }
 	| { readonly kind: 'error'; readonly error: ErrorInfo; readonly resumable: boolean }
+	| { readonly kind: 'rejected'; readonly error: ErrorInfo }
 	| { readonly kind: 'localCommand' };
 
 /** A terminal turn outcome offered to contributions after a turn ended. */
@@ -123,14 +125,31 @@ export interface IRestoredChat {
 }
 
 /** A client action after it has been reduced into host state. */
-export interface IObservedAction {
+export interface IAppliedClientAction {
 	readonly channel: ProtocolURI;
 	readonly session: ProtocolURI;
 	readonly action: StateAction;
 	readonly clientId: string | undefined;
 	readonly clientContext: IAgentHostClientTelemetryContext;
 }
 
+/**
+ * A dispatched action, from any origin, after its outcome is known.
+ *
+ * Unlike {@link IAppliedClientAction}, this covers server-dispatched actions — which is
+ * most agent-produced state — and rejected actions, which never reduced. A contribution
+ * that only cares about client dispatch should use `onDidApplyClientAction` instead;
+ * observing both would see the same client action twice.
+ */
+export interface IDispatchedAction {
+	readonly channel: ProtocolURI;
+	/** The owning session URI, or the channel itself when it is not a chat channel. */
+	readonly session: ProtocolURI;
+	readonly action: StateAction;
+	/** Set when the action was rejected and never reached state. */
+	readonly rejectionReason?: string;
+}
+
 export interface IQueuedMessageSender {
 	readonly clientId: string | undefined;
 	readonly clientContext: IAgentHostClientTelemetryContext;
@@ -205,21 +224,44 @@ export interface IAgentHostChatContribution extends IDisposable {
 	 */
 	readonly order?: number;
 	/**
-	 * Fires when a turn ends through the agent signal path, or when a host handled
-	 * local command completes. It does NOT fire for a client dispatched
-	 * cancellation, nor for the failures that report `ChatError` directly, such as
-	 * a missing provider, a read-only or archived chat, or a send that throws.
-	 * Unifying those paths is tracked in `chatContributions/TODO.md`.
+	 * Fires on every terminal outcome a started turn can reach — the agent signal
+	 * path, a host-handled local command, a send that throws, and a cancellation
+	 * from either the client or the agent — and when admission refuses a request
+	 * before its turn starts. Discriminate `rejected` from `error`: the former has
+	 * no started turn to finalize and no checkpoint to capture.
+	 *
+	 * It does not fire for an agent-emitted terminal action that arrives when no
+	 * turn is active, because the reducer no-ops for those.
 	 *
 	 * Must not throw; the dispatcher isolates failures.
 	 */
 	onTurnEnd?(turn: ITurnEnd): void;
-	/** Observes actions submitted through the client dispatch path after state reduction. */
-	onAction?(action: IObservedAction): void;
+	/**
+	 * Observes a client-dispatched action after it was applied to host state.
+	 * Rejected client actions never reach this hook, so an action seen here always
+	 * reduced.
+	 */
+	onDidApplyClientAction?(action: IAppliedClientAction): void;
+	/**
+	 * Observes a dispatched action from any origin, after its outcome is known.
+	 * This covers server-dispatched actions — which is most agent-produced state — and
+	 * rejected actions, which never reduced. Check `rejectionReason` before acting on
+	 * one.
+	 *
+	 * Prefer `onDidApplyClientAction` when a behavior genuinely only concerns client
+	 * dispatch: a contribution implementing both sees every client action twice.
+	 *
+	 * Must not throw; the dispatcher isolates failures.
+	 */
+	onDidDispatchAction?(dispatched: IDispatchedAction): void;
 	/**
 	 * Awaited before the turn is sent. Instructions are concatenated in `order`;
 	 * text replacements are threaded in `order`, so each contribution observes
 	 * the prior contribution's text. Failures are isolated and do not block the send.
+	 *
+	 * Runs after admission and after the provider lookup, so a rejected turn and a turn
+	 * that fails with `noAgent` never reach it: only messages that are actually sent are
+	 * enriched.
 	 */
 	onOutgoingTurn?(turn: IOutgoingTurn): ISendContribution | undefined | Promise<ISendContribution | undefined>;
 	/**
@@ -271,7 +313,8 @@ export interface IAgentHostChatContributions extends IDisposable {
 	/** Returns the currently registered host, if AgentSideEffects has been constructed. */
 	getHost(): IAgentHostChatContributionHost | undefined;
 	turnEnd(turn: ITurnEnd): void;
-	action(action: IObservedAction): void;
+	didApplyClientAction(action: IAppliedClientAction): void;
+	didDispatchAction(dispatched: IDispatchedAction): void;
 	outgoingTurn(turn: IOutgoingTurn): Promise<IOutgoingTurnContributionResult>;
 	incomingRequest(request: IIncomingRequest): IncomingRequestDisposition;
 	hydrateTurns(context: IHydrationContext, turns: readonly Turn[]): Promise<readonly Turn[]>;

src/vs/platform/agentHost/common/agentHostChatContributionsService.ts

@@ -8,7 +8,7 @@ import { NKeyMap } from '../../../base/common/map.js';
 import { observableValue, type ISettableObservable } from '../../../base/common/observable.js';
 import { IInstantiationService, type IConstructorSignature } from '../../instantiation/common/instantiation.js';
 import { ILogService } from '../../log/common/log.js';
-import type { IAgentHostChatContribution, IAgentHostChatContributionContext, IAgentHostChatContributionHost, IAgentHostChatContributions, IChatMementoKey, IHydrationContext, IIncomingRequest, IObservedAction, IOutgoingTurn, IOutgoingTurnContributionResult, IncomingRequestDisposition, IRestoredChat, ISessionMementoKey, ITurnEnd } from '../common/agentHostChatContributionsService.js';
+import type { IAgentHostChatContribution, IAgentHostChatContributionContext, IAgentHostChatContributionHost, IAgentHostChatContributions, IChatMementoKey, IHydrationContext, IIncomingRequest, IAppliedClientAction, IDispatchedAction, IOutgoingTurn, IOutgoingTurnContributionResult, IncomingRequestDisposition, IRestoredChat, ISessionMementoKey, ITurnEnd } from '../common/agentHostChatContributionsService.js';
 import { isAhpChatChannel, parseRequiredSessionUriFromChatUri, type Turn, type URI as ProtocolURI } from '../common/state/sessionState.js';
 
 type MementoKeySegment = string | boolean | number;
@@ -146,14 +146,28 @@ export class AgentHostChatContributions extends Disposable implements IAgentHost
 		}
 	}
 
-	action(action: IObservedAction): void {
+	didApplyClientAction(action: IAppliedClientAction): void {
 		for (const registration of this._getOrderedContributions()) {
 			const { contribution } = registration;
-			if (!contribution.onAction) {
+			if (!contribution.onDidApplyClientAction) {
 				continue;
 			}
 			try {
-				contribution.onAction(action);
+				contribution.onDidApplyClientAction(action);
+			} catch (err) {
+				this._logContributionFailure(registration, err);
+			}
+		}
+	}
+
+	didDispatchAction(dispatched: IDispatchedAction): void {
+		for (const registration of this._getOrderedContributions()) {
+			const { contribution } = registration;
+			if (!contribution.onDidDispatchAction) {
+				continue;
+			}
+			try {
+				contribution.onDidDispatchAction(dispatched);
 			} catch (err) {
 				this._logContributionFailure(registration, err);
 			}

src/vs/platform/agentHost/node/agentHostChatContributionsService.ts

@@ -55,6 +55,7 @@ import { AgentHostSessionOpenTelemetry, IAgentHostSessionOpenTelemetry } from '.
 import { AgentHostStorageService, IAgentHostStorageService } from './agentHostStorageService.js';
 import { AgentHostTerminalManager, IAgentHostTerminalManager } from './agentHostTerminalManager.js';
 import { AgentHostTelemetryReporter, IAgentHostTelemetryReporter } from './agentHostTelemetryReporter.js';
+import { AgentHostToolCallTracker, IAgentHostToolCallTracker } from './agentHostToolCallTracker.js';
 import { AgentHostTurnTracker, IAgentHostTurnTracker } from './agentHostTurnTracker.js';
 import { AgentHostProviderService, IAgentHostProviderService } from './agentHostProviderService.js';
 import { AgentEditAttributionService } from './shared/agentEditAttributionService.js';
@@ -100,6 +101,7 @@ export function registerAgentHostCoreServices(services: ServiceCollection, input
 	services.set(IAgentHostChatContributions, new SyncDescriptor(AgentHostChatContributions));
 	services.set(IAgentHostTelemetryReporter, new SyncDescriptor(AgentHostTelemetryReporter));
 	services.set(IAgentHostTurnTracker, new SyncDescriptor(AgentHostTurnTracker));
+	services.set(IAgentHostToolCallTracker, new SyncDescriptor(AgentHostToolCallTracker));
 	services.set(IAgentHostProviderService, new SyncDescriptor(AgentHostProviderService));
 	services.set(IAgentBranchNameGenerator, new SyncDescriptor(AgentBranchNameGenerator));
 	services.set(IAgentHostWorktreeIsolation, new SyncDescriptor(WorktreeIsolation));

src/vs/platform/agentHost/node/agentHostServices.ts

@@ -6,10 +6,13 @@
 import { disposableTimeout } from '../../../base/common/async.js';
 import { Disposable, DisposableMap } from '../../../base/common/lifecycle.js';
 import { StopWatch } from '../../../base/common/stopwatch.js';
+import { createDecorator } from '../../instantiation/common/instantiation.js';
 import type { IAgentHostClientTelemetryContext } from '../common/agentHostTelemetry.js';
 import type { SessionToolAuthenticationRequest, SessionToolClientExecutionRequest, SessionToolConfirmationRequest } from '../common/state/protocol/state.js';
-import { ToolCallContributorKind, type ToolCallContributor, type ToolCallResult } from '../common/state/sessionState.js';
-import type { AgentHostModelTelemetryKind, AgentHostTelemetryReporter, IAgentHostToolInvokedReport } from './agentHostTelemetryReporter.js';
+import { type ToolCallContributor, type ToolCallResult } from '../common/state/sessionState.js';
+import { IAgentHostTelemetryReporter, type AgentHostModelTelemetryKind, type AgentHostTelemetryReporter, type IAgentHostToolInvokedReport } from './agentHostTelemetryReporter.js';
+import { IAgentHostTurnTracker, type AgentHostTurnTracker } from './agentHostTurnTracker.js';
+import { canRefineContributor, toolSourceKindFromContributor } from './shared/toolCallContributor.js';
 
 export type ToolInvokedResult = 'success' | 'error' | 'userCancelled';
 
@@ -34,41 +37,6 @@ export function deriveToolInvokedResult(result: ToolCallResult): ToolInvokedResu
 	return 'error';
 }
 
-/**
- * Maps a tool call's contributor to the telemetry `toolSourceKind`. A tool with
- * no contributor is provided by the agent host itself; an MCP contributor maps
- * to `mcp` and a client contributor to `client`.
- */
-export function toolSourceKindFromContributor(contributor: ToolCallContributor | undefined): string {
-	if (!contributor) {
-		return 'agentHost';
-	}
-	// Widen to `string` so an unrecognized kind from a newer protocol version
-	// falls through to a valid telemetry value rather than `undefined`.
-	const kind: string = contributor.kind;
-	switch (kind) {
-		case ToolCallContributorKind.MCP:
-			return 'mcp';
-		case ToolCallContributorKind.Client:
-			return 'client';
-		default:
-			return kind;
-	}
-}
-
-/**
- * Whether `next` is a safe refinement of the currently recorded contributor.
- * A client contributor may only be refined by the same client, and a client
- * contributor is never replaced by a non-client one, so execution ownership
- * cannot be reassigned by a later, less specific signal.
- */
-export function canRefineContributor(current: ToolCallContributor | undefined, next: ToolCallContributor): boolean {
-	if (current?.kind === ToolCallContributorKind.Client) {
-		return next.kind === ToolCallContributorKind.Client && next.clientId === current.clientId;
-	}
-	return next.kind !== ToolCallContributorKind.Client;
-}
-
 /** Per-tool-call timing state, keyed by `session:toolCallId`. */
 interface IToolCallTiming {
 	readonly lifecycleStopWatch: StopWatch;
@@ -104,17 +72,21 @@ interface IStalledToolCall {
  * tool call) are dropped via {@link clearSession} / {@link clear} so the
  * tracking map cannot leak.
  */
+export const IAgentHostToolCallTracker = createDecorator<AgentHostToolCallTracker>('agentHostToolCallTracker');
+
 export class AgentHostToolCallTracker extends Disposable {
 
+	declare readonly _serviceBrand: undefined;
+
 	private readonly _toolCalls = new Map<string, IToolCallTiming>();
 	private readonly _turnModels = new Map<string, { model: string; modelTelemetryKind: AgentHostModelTelemetryKind }>();
 	private readonly _pendingToolReports = new Map<string, IAgentHostToolInvokedReport[]>();
 	private readonly _toolCallStallTimers = this._register(new DisposableMap<string>());
 	private readonly _stalledToolCalls = new Map<string, IStalledToolCall>();
 
 	constructor(
-		private readonly _reporter: AgentHostTelemetryReporter,
-		private readonly _getClientContext: (session: string, turnId: string) => IAgentHostClientTelemetryContext | undefined = () => undefined,
+		@IAgentHostTelemetryReporter private readonly _reporter: AgentHostTelemetryReporter,
+		@IAgentHostTurnTracker private readonly _turnTracker: AgentHostTurnTracker,
 	) {
 		super();
 	}
@@ -132,7 +104,7 @@ export class AgentHostToolCallTracker extends Disposable {
 			model: resolvedModel?.model ?? model,
 			modelTelemetryKind: resolvedModel?.modelTelemetryKind ?? modelTelemetryKind,
 			modelResolvedFromUsage: resolvedModel !== undefined,
-			clientContext: this._getClientContext(session, turnId),
+			clientContext: this._turnTracker.getClientTelemetryContext(session, turnId),
 		});
 	}
 

src/vs/platform/agentHost/node/agentHostToolCallTracker.ts

@@ -10,7 +10,7 @@ import type { IAgent } from '../common/agent.js';
 import type { IAgentHostClientTelemetryContext } from '../common/agentHostTelemetry.js';
 import { IAgentHostChatContributions } from '../common/agentHostChatContributionsService.js';
 import { ActionType } from '../common/state/sessionActions.js';
-import { createErrorResponsePart, type Message, type URI as ProtocolURI } from '../common/state/sessionState.js';
+import { createErrorResponsePart, type ErrorInfo, type Message, type URI as ProtocolURI } from '../common/state/sessionState.js';
 import { createAgentChatContext } from './agentChatContext.js';
 import { IAgentHostStateManager } from './agentHostStateManager.js';
 import { IAgentHostProviderService } from './agentHostProviderService.js';
@@ -37,7 +37,22 @@ export interface ITurnStartRequest {
 	readonly turnStopWatch: StopWatch;
 }
 
-/** Admits a turn, records its telemetry, and resolves the provider that will send it. */
+/**
+ * Admits a turn, records its telemetry, and resolves the provider that will send it.
+ * Both the direct (`handleAction`) and queued (`QueueDrainContribution`) admission paths
+ * run this, so the preamble has one copy.
+ *
+ * This is a plain function rather than a service because it holds no state: registering it
+ * in DI bought nothing and cost a registration in every hand-built test service graph. Keep
+ * it a function unless it acquires state.
+ *
+ * The gate runs before {@link IAgentHostTurnTracker.turnStarted}, so a refused request has
+ * no turn to complete: it reports neither `userMessageSent` nor `turnCompleted`, and does
+ * not call `_completeTurn` or clear the tool-call tracker. That is deliberate, not an
+ * oversight — a rejection is observable through `onTurnEnd` with `kind === 'rejected'`, so
+ * measure rejection volume from a contribution rather than by reviving the turn-completion
+ * path.
+ */
 export function startTurn(accessor: ServicesAccessor, request: ITurnStartRequest): IStartedTurn | undefined {
 	const chatContributions = accessor.get(IAgentHostChatContributions);
 	const stateManager = accessor.get(IAgentHostStateManager);
@@ -66,6 +81,13 @@ export function startTurn(accessor: ServicesAccessor, request: ITurnStartRequest
 			duration: Math.max(0, request.turnStopWatch.elapsed()),
 			part: createErrorResponsePart(disposition.error),
 		});
+		chatContributions.turnEnd({
+			session: request.session,
+			channel: request.turnChannel,
+			turnId: request.turnId,
+			reason: { kind: 'rejected', error: disposition.error },
+			clientContext: request.clientContext,
+		});
 		return undefined;
 	}
 
@@ -77,11 +99,19 @@ export function startTurn(accessor: ServicesAccessor, request: ITurnStartRequest
 
 	const agent = providerService.getProviderForSession(request.session);
 	if (!agent) {
+		const error: ErrorInfo = { errorType: 'noAgent', message: 'No agent found for session' };
 		stateManager.dispatchServerAction(request.turnChannel, {
 			type: ActionType.ChatError,
 			turnId: request.turnId,
 			duration: Math.max(0, request.turnStopWatch.elapsed()),
-			part: createErrorResponsePart({ errorType: 'noAgent', message: 'No agent found for session' }),
+			part: createErrorResponsePart(error),
+		});
+		chatContributions.turnEnd({
+			session: request.session,
+			channel: request.turnChannel,
+			turnId: request.turnId,
+			reason: { kind: 'rejected', error },
+			clientContext: request.clientContext,
 		});
 		return undefined;
 	}

src/vs/platform/agentHost/node/agentHostTurnStarter.ts

@@ -16,7 +16,7 @@ import { createUnknownAgentHostClientTelemetryContext, type IAgentHostClientTele
 import { AgentHostClientType } from '../common/agentHostClientInfo.js';
 import { IAgentHostClientConnectionService } from './agentHostClientConnectionService.js';
 import { ILogService } from '../../log/common/log.js';
-import { canRefineContributor, toolSourceKindFromContributor } from './agentHostToolCallTracker.js';
+import { canRefineContributor, toolSourceKindFromContributor } from './shared/toolCallContributor.js';
 import { SessionInputRequestKind } from '../common/state/protocol/state.js';
 import type { ITurnTokenTotal, ToolCallContributor } from '../common/state/sessionState.js';
 import { IAgentHostTelemetryReporter, type AgentHostInitiatorClientConnectionState, type AgentHostMessageOriginTelemetryKind, type AgentHostModelTelemetryKind, type AgentHostProviderDiagnosticState, type AgentHostTelemetryReporter, type AgentHostTurnFailureStage, type AgentHostTurnHangReason, type AgentHostTurnResult, type IAgentHostTurnFailure } from './agentHostTelemetryReporter.js';
@@ -374,11 +374,17 @@ export class AgentHostTurnTracker extends Disposable {
 		return this._turnTimings.get(this._key(session, turnId))?.initiatorClientId;
 	}
 
-	turnCompleted(session: string, turnId: string, result: AgentHostTurnResult, failure?: IAgentHostTurnFailure, workspace?: { readonly isMultiRoot: boolean; readonly folderCount: number }): void {
+	/**
+	 * Records a turn's completion. Returns whether a tracked turn actually ended:
+	 * `false` means no turn was in flight for `turnId`, which happens for a stale or
+	 * duplicate terminal action that the reducer also no-ops. Callers that run
+	 * end-of-turn side effects should skip them when this returns `false`.
+	 */
+	turnCompleted(session: string, turnId: string, result: AgentHostTurnResult, failure?: IAgentHostTurnFailure, workspace?: { readonly isMultiRoot: boolean; readonly folderCount: number }): boolean {
 		const key = this._key(session, turnId);
 		const timing = this._turnTimings.get(key);
 		if (!timing) {
-			return;
+			return false;
 		}
 		const usage = this._turnUsages.get(key);
 		this._disposeTurn(key, timing);
@@ -425,6 +431,7 @@ export class AgentHostTurnTracker extends Disposable {
 				timeAfterHangMs: timing.lastHangStopWatch?.elapsed() ?? 0,
 			});
 		}
+		return true;
 	}
 
 	/**