agentHost: subagents (#308592)

* agentHost: subagents

* agentHost: remove _meta.parentToolCallId dependency, subscribe to child sessions instead

Inner tool calls from subagent sessions are no longer stored in the parent
turn with _meta.parentToolCallId. Instead:

- Server: _buildTurnsFromMessages skips inner events (parentToolCallId),
  _restoreSubagentSession builds child session turns from raw messages
- Client: _enrichHistoryWithSubagentCalls subscribes to child sessions
  during history restore, injects serialized inner tool calls with
  subAgentInvocationId set

Also fixes hygiene: replace 'in' operator with hasKey in
agentSideEffects.test.ts, exclude .jsonl from copyright filter.

* fix: set terminalCommandUri from terminal content blocks in stateToProgressAdapter

completedToolCallToSerialized and toolCallStateToInvocation were not
detecting terminal tools via ToolResultContentType.Terminal content
blocks or setting terminalCommandUri/terminalToolSessionId, causing
6 test failures in CI.

* comments

Co-authored-by: Copilot <copilot@github.com>

* revert diff

---------

Co-authored-by: Copilot <copilot@github.com>

Author: roblourens

build/filters.ts

@@ -162,6 +162,7 @@ export const copyrightFilter = Object.freeze<string[]>([
 	'**',
 	'!**/*.desktop',
 	'!**/*.json',
+	'!**/*.jsonl',
 	'!**/*.html',
 	'!**/*.template',
 	'!**/*.md',

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

@@ -169,8 +169,8 @@ export interface IAgentToolStartEvent extends IAgentProgressEventBase {
 	readonly invocationMessage: string;
 	/** A representative input string for display in the UI (e.g., the shell command). */
 	readonly toolInput?: string;
-	/** Hint for the renderer about how to display this tool (e.g., 'terminal' for shell commands). */
-	readonly toolKind?: 'terminal';
+	/** Hint for the renderer about how to display this tool (e.g., 'terminal' for shell commands, 'subagent' for subagent-spawning tools). */
+	readonly toolKind?: 'terminal' | 'subagent';
 	/** Language identifier for syntax highlighting (e.g., 'shellscript', 'powershell'). Used with toolKind 'terminal'. */
 	readonly language?: string;
 	/** Serialized JSON of the tool arguments, if available. */
@@ -252,6 +252,15 @@ export interface IAgentUserInputRequestEvent extends IAgentProgressEventBase {
 	readonly request: ISessionInputRequest;
 }
 
+/** A subagent has been spawned by a tool call. */
+export interface IAgentSubagentStartedEvent extends IAgentProgressEventBase {
+	readonly type: 'subagent_started';
+	readonly toolCallId: string;
+	readonly agentName: string;
+	readonly agentDisplayName: string;
+	readonly agentDescription?: string;
+}
+
 export type IAgentProgressEvent =
 	| IAgentDeltaEvent
 	| IAgentMessageEvent
@@ -264,7 +273,8 @@ export type IAgentProgressEvent =
 	| IAgentUsageEvent
 	| IAgentReasoningEvent
 	| IAgentSteeringConsumedEvent
-	| IAgentUserInputRequestEvent;
+	| IAgentUserInputRequestEvent
+	| IAgentSubagentStartedEvent;
 
 // ---- Session URI helpers ----------------------------------------------------
 
@@ -328,7 +338,7 @@ export interface IAgent {
 	setPendingMessages?(session: URI, steeringMessage: IPendingMessage | undefined, queuedMessages: readonly IPendingMessage[]): void;
 
 	/** Retrieve all session events/messages for reconstruction. */
-	getSessionMessages(session: URI): Promise<(IAgentMessageEvent | IAgentToolStartEvent | IAgentToolCompleteEvent)[]>;
+	getSessionMessages(session: URI): Promise<(IAgentMessageEvent | IAgentToolStartEvent | IAgentToolCompleteEvent | IAgentSubagentStartedEvent)[]>;
 
 	/** Dispose a session, freeing resources. */
 	disposeSession(session: URI): Promise<void>;

src/vs/platform/agentHost/common/state/sessionReducers.ts

@@ -8,3 +8,22 @@
 
 // Re-export reducers from the protocol layer
 export { rootReducer, sessionReducer, softAssertNever, isClientDispatchable } from './protocol/reducers.js';
+
+import type { ICompletedToolCall, IToolCallState } from './sessionState.js';
+
+/**
+ * Extracts the VS Code-specific `toolKind` hint from a tool call's `_meta`
+ * bag. This is not part of the protocol and is injected by the agent adapter
+ * (e.g. `copilotEventMapper`).
+ */
+export function getToolKind(tc: IToolCallState | ICompletedToolCall): 'terminal' | 'subagent' | undefined {
+	return tc._meta?.toolKind as 'terminal' | 'subagent' | undefined;
+}
+
+/**
+ * Extracts the VS Code-specific `language` hint from a tool call's `_meta`
+ * bag. Used for syntax-highlighting terminal tool output.
+ */
+export function getToolLanguage(tc: IToolCallState | ICompletedToolCall): string | undefined {
+	return tc._meta?.language as string | undefined;
+}

src/vs/platform/agentHost/common/state/sessionState.ts

@@ -23,6 +23,8 @@ import {
 	type IToolCallCompletedState,
 	type IToolCallResult,
 	type IToolCallState,
+	type IToolResultContent,
+	type IToolResultSubagentContent,
 	type IToolResultTextContent,
 	type IUserMessage,
 	ITerminalState,
@@ -62,6 +64,7 @@ export {
 	type IToolResultEmbeddedResourceContent as IToolResultBinaryContent,
 	type IToolResultContent,
 	type IToolResultFileEditContent,
+	type IToolResultSubagentContent,
 	type IToolResultTextContent,
 	type ITurn,
 	type IUsageInfo,
@@ -166,6 +169,61 @@ export function getToolFileEdits(result: IToolCallResult): IToolResultFileEditCo
 	return edits;
 }
 
+/**
+ * Extracts the first subagent content entry from a tool call's `content` array.
+ * Works with both completed tool call results and running tool call states.
+ * Returns `undefined` if there are no subagent content parts.
+ */
+export function getToolSubagentContent(result: { content?: readonly IToolResultContent[] }): IToolResultSubagentContent | undefined {
+	if (!result.content || result.content.length === 0) {
+		return undefined;
+	}
+	for (const c of result.content) {
+		if (hasKey(c, { type: true }) && c.type === ToolResultContentType.Subagent) {
+			return c as IToolResultSubagentContent;
+		}
+	}
+	return undefined;
+}
+
+// ---- Subagent URI helpers ---------------------------------------------------
+
+/**
+ * Builds a subagent session URI from a parent session URI and tool call ID.
+ * Convention: `{parentSessionUri}/subagent/{toolCallId}`
+ */
+export function buildSubagentSessionUri(parentSession: string, toolCallId: string): string {
+	// Normalize: strip trailing slash from parent to avoid double-slash in URI
+	const parent = parentSession.endsWith('/') ? parentSession.slice(0, -1) : parentSession;
+	return `${parent}/subagent/${toolCallId}`;
+}
+
+/**
+ * Parses a subagent session URI into its parent session URI and tool call ID.
+ * Returns `undefined` if the URI does not follow the subagent convention.
+ */
+export function parseSubagentSessionUri(uri: string): { parentSession: string; toolCallId: string } | undefined {
+	const idx = uri.lastIndexOf('/subagent/');
+	if (idx < 0) {
+		return undefined;
+	}
+	const toolCallId = uri.substring(idx + '/subagent/'.length);
+	if (!toolCallId) {
+		return undefined;
+	}
+	return {
+		parentSession: uri.substring(0, idx),
+		toolCallId,
+	};
+}
+
+/**
+ * Returns whether a session URI represents a subagent session.
+ */
+export function isSubagentSession(uri: string): boolean {
+	return uri.includes('/subagent/');
+}
+
 // ---- Factory helpers --------------------------------------------------------
 
 export function createRootState(): IRootState {

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

@@ -92,14 +92,30 @@ export class AgentEventMapper {
 				// We emit both toolCallStart (streaming → created) and toolCallReady
 				// (params complete → running with auto-confirm) as a pair.
 				const e = event as IAgentToolStartEvent;
+				const meta: Record<string, unknown> = { toolKind: e.toolKind, language: e.language };
+
+				// For subagent tools, extract agent metadata from tool arguments
+				// so the renderer can display the name/description immediately.
+				if (e.toolKind === 'subagent' && e.toolArguments) {
+					try {
+						const args = JSON.parse(e.toolArguments) as Record<string, unknown>;
+						if (typeof args.description === 'string') {
+							meta.subagentDescription = args.description;
+						}
+						if (typeof args.agentName === 'string') {
+							meta.subagentAgentName = args.agentName;
+						}
+					} catch { /* ignore parse errors */ }
+				}
+
 				const startAction: IToolCallStartAction = {
 					type: ActionType.SessionToolCallStart,
 					session,
 					turnId,
 					toolCallId: e.toolCallId,
 					toolName: e.toolName,
 					displayName: e.displayName,
-					_meta: { toolKind: e.toolKind, language: e.language },
+					_meta: meta,
 				};
 				const readyAction: IToolCallReadyAction = {
 					type: ActionType.SessionToolCallReady,

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

@@ -67,6 +67,20 @@ export class AgentHostStateManager extends Disposable {
 		return this._serverSeq;
 	}
 
+	/**
+	 * Returns all session URIs whose keys start with the given prefix.
+	 * Used to discover subagent sessions for a given parent.
+	 */
+	getSessionUrisWithPrefix(prefix: string): string[] {
+		const result: string[] = [];
+		for (const key of this._sessionStates.keys()) {
+			if (key.startsWith(prefix)) {
+				result.push(key);
+			}
+		}
+		return result;
+	}
+
 	// ---- Snapshots ----------------------------------------------------------
 
 	/**