@codingame/monaco-vscode-chat-service-override 34.1.3 → 35.0.1

package/vscode/src/vs/platform/agentHost/common/agentService.d.ts

@@ -3,15 +3,15 @@ import { IReference } from "@codingame/monaco-vscode-api/vscode/vs/base/common/l
 import type { IObservable } from "@codingame/monaco-vscode-api/vscode/vs/base/common/observable";
 import { URI } from "@codingame/monaco-vscode-api/vscode/vs/base/common/uri";
 import { IConfigurationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/configuration/common/configuration.service";
-import type { ISyncedCustomization } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/agentPluginManager";
+import type { IAgentServerToolHost } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/agentServerTools";
 import type { IActiveSubscriptionInfo, IAgentSubscription } from "./state/agentSubscription.js";
 import type { IRemoteWatchHandle } from "./agentHostFileSystemProvider.js";
 import type { CompletionsParams, CompletionsResult, CreateTerminalParams, ResolveSessionConfigResult, SessionConfigCompletionsResult } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/commands";
 import type { InvokeChangesetOperationParams, InvokeChangesetOperationResult } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/channels-changeset/commands";
-import { ProtectedResourceMetadata, type ChangesetSummary, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/state";
-import type { ActionEnvelope, INotification, IRootConfigChangedAction, SessionAction, TerminalAction } from "./state/sessionActions.js";
+import { ProtectedResourceMetadata, type Changeset, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition, ChangesSummary } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/state";
+import type { ActionEnvelope, AuthRequiredParams, INotification, IRootConfigChangedAction, SessionAction, ChatAction, TerminalAction, ClientAnnotationsAction } from "./state/sessionActions.js";
 import type { ResourceCopyParams, ResourceCopyResult, ResourceDeleteParams, ResourceDeleteResult, ResourceListResult, ResourceMkdirParams, ResourceMkdirResult, ResourceMoveParams, ResourceMoveResult, ResourceReadResult, ResourceResolveParams, ResourceResolveResult, ResourceWriteParams, ResourceWriteResult, CreateResourceWatchParams, CreateResourceWatchResult } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionProtocol";
-import { ComponentToState, SessionInputResponseKind, SessionStatus, StateComponents, type ClientPluginCustomization, type Customization, type PendingMessage, type RootState, type SessionInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionState";
+import { ComponentToState, ChatInputResponseKind, SessionStatus, StateComponents, type AgentCapabilities, type ClientPluginCustomization, type Customization, type PendingMessage, type RootState, type ChatInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionState";
 export declare enum AgentHostIpcChannels {
     /** Channel for the agent host service on the main-process side */
     AgentHost = "agentHost",
@@ -35,31 +35,163 @@ export declare const AgentHostAhpJsonlLoggingSettingId = "chat.agentHost.ahpJson
 /** Configuration key that controls whether Agent Host uses its terminal tool override for Copilot SDK sessions. */
 export declare const AgentHostCustomTerminalToolEnabledSettingId = "chat.agentHost.customTerminalTool.enabled";
 /**
- * Configuration key that holds the absolute path to a locally-installed
- * `@anthropic-ai/claude-agent-sdk` package. When non-empty, the Claude agent
- * provider is registered inside the agent host and the SDK module is loaded
- * via dynamic `import()` from this path. When empty (the default), the
- * Claude provider is not registered. The SDK is intentionally not bundled
- * with VS Code; users opting into the Claude agent install the SDK
- * themselves and point this setting at it. The agent host process must be
- * restarted for changes to take effect.
+ * Configuration key that controls whether Copilot SDK sessions running a Claude
+ * Opus 4.8 model apply the Opus 4.8-tuned system-prompt section overrides.
+ * Forwarded into the agent host's root config (`opus48Prompt`) by
+ * `AgentHostCopilotPromptContribution`.
  */
-export declare const AgentHostClaudeAgentSdkPathSettingId = "chat.agentHost.claudeAgent.path";
+export declare const AgentHostOpus48PromptEnabledSettingId = "chat.agentHost.opus48Prompt.enabled";
 /**
- * Environment variable that holds the absolute path to a locally-installed
- * `@anthropic-ai/claude-agent-sdk` package. When set to a non-empty value,
- * the agent host process registers the Claude agent provider and loads the
- * SDK module from this path. Set by the agent host starters from
- * {@link AgentHostClaudeAgentSdkPathSettingId}, and may also be set directly
- * by developers as an override.
+ * Configuration key controlling whether the Claude provider is registered in
+ * the agent host process. When `false`, the agent host skips registering the
+ * Claude provider regardless of SDK availability. Defaults to `true`.
+ *
+ * Independent of {@link ClaudePreferAgentHostAgentsSettingId} /
+ * {@link ClaudePreferAgentHostEditorSettingId}, which control whether the
+ * workbench surfaces the agent host's Claude provider (vs. the GitHub Copilot
+ * Chat extension's). This setting is strictly about whether the agent host
+ * advertises Claude at all. The agent host process must be restarted for
+ * changes to take effect.
+ */
+export declare const AgentHostClaudeAgentEnabledSettingId = "chat.agentHost.claudeAgent.enabled";
+/**
+ * Configuration key controlling whether the Codex provider is registered in
+ * the agent host process. When `false` (the default), the agent host skips
+ * registering the Codex provider regardless of SDK availability. The agent
+ * host process must be restarted for changes to take effect.
+ */
+export declare const AgentHostCodexAgentEnabledSettingId = "chat.agentHost.codexAgent.enabled";
+/**
+ * Configuration key controlling whether the agent host *wires up* the BYOK
+ * ("bring your own key") language-model bridge: the renderer LM handler, the
+ * reverse-RPC channel, and the per-connection link to the node-side OpenAI
+ * proxy + bridge registry. When `false` (the default), the proxy and registry
+ * are still constructed but stay inert — the renderer's BYOK server channel and
+ * the per-connection bridge are not wired, so the registry stays empty and
+ * extension-provided BYOK models are never reachable from agent-host sessions.
+ * The agent host process must be restarted for changes to take effect.
+ */
+export declare const AgentHostByokModelsEnabledSettingId = "chat.agentHost.byokModels.enabled";
+/**
+ * Optional override that points at an **SDK root directory** containing a
+ * `node_modules/@anthropic-ai/claude-agent-sdk` subtree. When set, the agent
+ * host loads the Claude SDK from that path instead of the bare import (which
+ * resolves via this repo's `node_modules` in dev) or the on-demand download
+ * from `product.agentSdks.claude` (built products). Mainly exists for the
+ * remote server's `--claude-sdk-root` CLI flag and for one-off developer
+ * overrides pointing at an out-of-tree SDK build.
+ */
+export declare const AgentHostClaudeSdkRootEnvVar = "VSCODE_AGENT_HOST_CLAUDE_SDK_ROOT";
+/**
+ * Environment variable form of {@link AgentHostClaudeAgentEnabledSettingId}.
+ * Set by the agent host starters from the setting. Accepts `'true'` /
+ * `'false'`; absent means "default" (`true` for Claude, `false` for Codex).
+ */
+export declare const AgentHostClaudeAgentEnabledEnvVar = "VSCODE_AGENT_HOST_CLAUDE_AGENT_ENABLED";
+/**
+ * Environment variable form of {@link AgentHostCodexAgentEnabledSettingId}.
+ * Set by the agent host starters from the setting. Accepts `'true'` /
+ * `'false'`; absent means "default" (`false`).
+ */
+export declare const AgentHostCodexAgentEnabledEnvVar = "VSCODE_AGENT_HOST_CODEX_AGENT_ENABLED";
+/**
+ * Environment variable form of {@link AgentHostByokModelsEnabledSettingId}.
+ * Set by the agent host starters from the setting. Accepts `'true'` /
+ * `'false'`; absent means "default" (`false`).
+ */
+export declare const AgentHostByokModelsEnabledEnvVar = "VSCODE_AGENT_HOST_BYOK_MODELS_ENABLED";
+/**
+ * Resolves the effective enable state for a Claude/Codex provider from the
+ * env-var value forwarded by the starter. Recognized values (case- and
+ * whitespace-insensitive):
+ *
+ *  - `'true'`  / `'1'` → enabled
+ *  - `'false'` / `'0'` → disabled
+ *  - `undefined`, empty string, or any other value → falls through to
+ *    {@link defaultEnabled}
+ */
+export declare function isAgentEnabled(envValue: string | undefined, defaultEnabled: boolean): boolean;
+/**
+ * Configuration key that controls the sandbox mode for the Copilot SDK's built-in
+ * shell tool (the path taken when {@link AgentHostCustomTerminalToolEnabledSettingId}
+ * is `false`). Values mirror {@link AgentSandboxEnabledValue}:
+ *
+ *  - `'off'` (the default): no sandbox policy is forwarded for the SDK shell
+ *    path \u2014 commands run unsandboxed.
+ *  - `'on'`: the Agent Host runs the SDK\u2019s shell tool inside a sandbox
+ *    using the user's `chat.agent.sandbox.fileSystem.*` filesystem policy.
+ *    Outbound network is enforced via the user's allow/deny host lists.
+ *  - `'allowNetwork'`: same as `'on'` but with unrestricted outbound network.
+ *
+ * Has no effect when {@link AgentHostCustomTerminalToolEnabledSettingId} is
+ * `true` \u2014 the host\u2019s own terminal sandbox engine then handles shell
+ * commands and reads `chat.agent.sandbox.enabled` directly.
+ */
+export declare const AgentHostSdkSandboxEnabledSettingId = "chat.agentHost.sdkSandbox.enabled";
+/**
+ * Selects which Claude integration fulfills Claude sessions opened from the
+ * **Agents Window**:
+ *  - `true` — Claude is provided by the agent host process.
+ *  - `false` (default) — Claude is provided by the GitHub Copilot Chat extension.
+ *
+ * The agent host always registers Claude when its SDK is reachable; this
+ * setting only controls whether the per-window bridge in
+ * `AgentHostContribution` actually surfaces the AH provider in the Agents
+ * Window. The extension's `chatSessions` contribution mirrors the rule
+ * declaratively (its `when` clause hides the EH provider when this is `true`),
+ * so flipping the setting takes effect live without a window reload.
+ *
+ * Paired with {@link ClaudePreferAgentHostEditorSettingId} which governs the
+ * regular workbench (sidebar). EXP-backed (`experiment: { mode: 'startup' }`).
  */
-export declare const AgentHostClaudeSdkPathEnvVar = "VSCODE_AGENT_HOST_CLAUDE_SDK_PATH";
+export declare const ClaudePreferAgentHostAgentsSettingId = "chat.agents.claude.preferAgentHost";
 /**
- * Absolute path to a locally-installed `codex` binary. When non-empty, the
- * Codex agent provider is registered inside the agent host. Empty (the
- * default) disables the provider entirely.
+ * Sibling of {@link ClaudePreferAgentHostAgentsSettingId} that selects the
+ * Claude implementation for the **regular workbench** (sidebar chat in a
+ * non-Agents-Window window). Same shape, same semantics — just a different
+ * surface scope.
  */
-export declare const AgentHostCodexAgentBinaryPathSettingId = "chat.agentHost.codexAgent.path";
+export declare const ClaudePreferAgentHostEditorSettingId = "chat.editor.claude.preferAgentHost";
+/**
+ * The per-window setting that selects which Claude implementation surfaces:
+ * the Agents Window reads {@link ClaudePreferAgentHostAgentsSettingId}, every
+ * other window reads {@link ClaudePreferAgentHostEditorSettingId}. Callers that
+ * observe the gate (to react to live flips) watch the id returned here; callers
+ * that evaluate it use {@link shouldSurfaceLocalAgentHostProvider}.
+ */
+export declare function claudePreferAgentHostSettingId(isSessionsWindow: boolean): string;
+/**
+ * Whether this window should surface the agent host's implementation of
+ * `provider`, given the per-window AH/EH preference settings. Today only the
+ * `claude` provider has dual implementations (the GitHub Copilot Chat
+ * extension's extension-host provider vs. the agent host's in-process
+ * provider) and a corresponding preference; every other provider is AH-only
+ * and unconditionally surfaced.
+ *
+ * Mirrors the EH-side gate declared in the extension's `chatSessions`
+ * contribution `when` clause:
+ *   - Agents Window  → {@link ClaudePreferAgentHostAgentsSettingId}
+ *   - Editor Window  → {@link ClaudePreferAgentHostEditorSettingId}
+ *
+ * When the relevant setting is `false`, the extension-host Claude is the one
+ * that surfaces in this window, so every agent-host surface (the chat session
+ * contribution and the sessions-window picker) suppresses its own Claude to
+ * avoid two identical entries.
+ *
+ * TODO: Remove this gate (and the `claude` special-case below) once the
+ * extension-host Claude implementation is retired. With only the agent host
+ * providing Claude there is no dual implementation to disambiguate, so this
+ * should unconditionally return `true` and callers can drop the gate entirely.
+ */
+export declare function shouldSurfaceLocalAgentHostProvider(provider: AgentProvider, configurationService: IConfigurationService, isSessionsWindow: boolean): boolean;
+/**
+ * Absolute path to the **SDK root directory** containing a
+ * `node_modules/@openai/codex` subtree. When non-empty, the agent host treats
+ * it as a dev override and skips the on-demand download from
+ * `product.agentSdks.codex`. Empty (the default) falls through to product
+ * config; if neither is present, the provider is not registered.
+ */
+export declare const AgentHostCodexAgentSdkRootSettingId = "chat.agentHost.codexAgent.sdkRoot";
 /**
  * Optional override for `$CODEX_HOME`. When set, the codex app-server child
  * process inherits this value, controlling where rollouts and config live.
@@ -71,11 +203,10 @@ export declare const AgentHostCodexAgentCodexHomeSettingId = "chat.agentHost.cod
  */
 export declare const AgentHostCodexAgentBinaryArgsSettingId = "chat.agentHost.codexAgent.binaryArgs";
 /**
- * Environment variable the agent host process reads to locate the codex
- * binary. Forwarded by the starters from
- * {@link AgentHostCodexAgentBinaryPathSettingId}.
+ * Environment variable form of {@link AgentHostCodexAgentSdkRootSettingId}.
+ * Forwarded by the starters from the setting.
  */
-export declare const AgentHostCodexAgentBinaryPathEnvVar = "VSCODE_AGENT_HOST_CODEX_APP_SERVER_PATH";
+export declare const AgentHostCodexAgentSdkRootEnvVar = "VSCODE_AGENT_HOST_CODEX_SDK_ROOT";
 /** Forwarded `$CODEX_HOME`. */
 export declare const AgentHostCodexAgentCodexHomeEnvVar = "CODEX_HOME";
 /** Forwarded extra args for `codex app-server` (JSON-encoded string[]). */
@@ -84,12 +215,23 @@ export declare const AgentHostCodexAgentBinaryArgsEnvVar = "VSCODE_AGENT_HOST_CO
 export declare const AgentHostOTelEnabledSettingId = "chat.agentHost.otel.enabled";
 /** Exporter type for the SDK's OTel pipeline. One of: `otlp-http`, `otlp-grpc`, `console`, `file`. */
 export declare const AgentHostOTelExporterTypeSettingId = "chat.agentHost.otel.exporterType";
+/**
+ * OTLP wire protocol (`http/json`, `http/protobuf`, `grpc`). Policy-only delivery slot (no user UI):
+ * carries the enterprise-managed `telemetry.protocol` so it can be threaded into the agent host's
+ * `OTEL_EXPORTER_OTLP_PROTOCOL` env, which the runtime needs to distinguish protobuf from json
+ * (the `exporterType` setting only models transport, not the HTTP wire encoding).
+ */
+export declare const AgentHostOTelOtlpProtocolSettingId = "chat.agentHost.otel.otlpProtocol";
 /** OTLP endpoint URL when `exporterType` is `otlp-http` or `otlp-grpc`. */
 export declare const AgentHostOTelOtlpEndpointSettingId = "chat.agentHost.otel.otlpEndpoint";
 /** Whether to include prompt/response content in span attributes (privacy-sensitive). */
 export declare const AgentHostOTelCaptureContentSettingId = "chat.agentHost.otel.captureContent";
 /** Output path when `exporterType` is `file`. */
 export declare const AgentHostOTelOutfileSettingId = "chat.agentHost.otel.outfile";
+/** Policy-only delivery slot for the enterprise-managed OTel `service.name` (no user UI). */
+export declare const AgentHostOTelServiceNameSettingId = "chat.agentHost.otel.serviceName";
+/** Policy-only delivery slot for enterprise-managed OTel resource attributes (no user UI). */
+export declare const AgentHostOTelResourceAttributesSettingId = "chat.agentHost.otel.resourceAttributes";
 /** When true, ALL spans are persisted to a local SQLite store regardless of `exporterType`. */
 export declare const AgentHostOTelDbSpanExporterEnabledSettingId = "chat.agentHost.otel.dbSpanExporter.enabled";
 /**
@@ -114,10 +256,14 @@ export declare const AgentHostOTelEnvVars: Readonly<{
     readonly OtlpEndpoint: "OTEL_EXPORTER_OTLP_ENDPOINT";
     readonly OtlpEndpointAlt: "COPILOT_OTEL_ENDPOINT";
     readonly OtlpProtocol: "OTEL_EXPORTER_OTLP_PROTOCOL";
+    readonly OtlpTracesProtocol: "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL";
+    readonly OtlpMetricsProtocol: "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL";
     readonly OtlpHeaders: "OTEL_EXPORTER_OTLP_HEADERS";
     readonly CaptureContent: "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT";
     readonly FilePath: "COPILOT_OTEL_FILE_EXPORTER_PATH";
     readonly SourceName: "COPILOT_OTEL_SOURCE_NAME";
+    readonly ServiceName: "OTEL_SERVICE_NAME";
+    readonly ResourceAttributes: "OTEL_RESOURCE_ATTRIBUTES";
     readonly DbSpanExporterEnabled: "COPILOT_OTEL_DB_SPAN_EXPORTER_ENABLED";
 }>;
 /**
@@ -127,11 +273,39 @@ export declare const AgentHostOTelEnvVars: Readonly<{
 export interface IAgentHostOTelSettings {
     readonly enabled?: boolean;
     readonly exporterType?: string;
+    readonly otlpProtocol?: string;
     readonly otlpEndpoint?: string;
     readonly captureContent?: boolean;
     readonly outfile?: string;
+    readonly serviceName?: string;
+    readonly resourceAttributes?: Record<string, string>;
     readonly dbSpanExporterEnabled?: boolean;
 }
+/**
+ * IPC channel (renderer -> main) the desktop agent-host path uses to hand the
+ * enterprise-resolved `chat.agentHost.otel.*` policy to `ElectronAgentHostStarter`.
+ *
+ * The main-process configuration service does NOT include the renderer-only
+ * `AccountPolicyService` (managed settings: server / native-MDM / file channels), so a
+ * starter running in the main process sees `policyValue === undefined` for these keys.
+ * The renderer — whose policy layer does include managed settings — forwards the resolved
+ * values here just before requesting the agent-host connection, so the host is spawned with
+ * the managed OTel env. See {@link readAgentHostOTelPolicySettings}.
+ */
+export declare const AgentHostOTelPolicyIpcChannel = "vscode:agentHostOTelPolicy";
+/**
+ * Resolve the enterprise-policy values for the `chat.agentHost.otel.*` settings from a
+ * configuration service whose policy layer includes managed settings (i.e. the renderer's).
+ * Each field is `undefined` when no policy is set. Intended as the `policySettings` argument
+ * of {@link buildAgentHostOTelEnv}.
+ */
+export declare function readAgentHostOTelPolicySettings(configurationService: IConfigurationService): IAgentHostOTelSettings;
+/**
+ * Validate/normalize an {@link IAgentHostOTelSettings} received over IPC, keeping only
+ * well-typed fields. Defends the main process against a malformed payload before the values
+ * are turned into agent-host process env vars.
+ */
+export declare function sanitizeAgentHostOTelPolicySettings(raw: unknown): IAgentHostOTelSettings;
 /**
  * Build the env-var overlay for the agent host process from user settings and
  * inherited env. Settings are translated to env vars, but if the same env var is
@@ -140,7 +314,27 @@ export interface IAgentHostOTelSettings {
  * Only sets a key when the underlying setting was explicitly configured — empty
  * string / undefined settings are dropped so they don't shadow inherited env.
  */
-export declare function buildAgentHostOTelEnv(settings: IAgentHostOTelSettings, inheritedEnv: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export declare function buildAgentHostOTelEnv(settings: IAgentHostOTelSettings, inheritedEnv: Readonly<Record<string, string | undefined>>, policySettings?: IAgentHostOTelSettings): Record<string, string>;
+/**
+ * Settings -> env-var fan-out for the Claude/Codex SDK overrides that the
+ * agent host process consumes. Shared by both starters
+ * (`nodeAgentHostStarter.ts`, `electronAgentHostStarter.ts`) so they don't
+ * drift the next time someone adds a setting.
+ *
+ * The shape mirrors {@link buildAgentHostOTelEnv}: only set a key when the
+ * underlying setting has a non-empty value AND the inherited env doesn't
+ * already define it (developer override wins). Returns a partial env map
+ * the caller spreads into the spawned child's environment.
+ */
+export interface IAgentSdkStarterSettings {
+    readonly codexSdkRoot?: string;
+    readonly codexHome?: string;
+    readonly codexBinaryArgs?: readonly string[];
+    readonly claudeAgentEnabled?: boolean;
+    readonly codexAgentEnabled?: boolean;
+    readonly byokModelsEnabled?: boolean;
+}
+export declare function buildAgentSdkEnv(settings: IAgentSdkStarterSettings, inheritedEnv: Readonly<Record<string, string | undefined>>): Record<string, string>;
 /** Result of starting the agent host WebSocket server on-demand. */
 export interface IAgentHostSocketInfo {
     readonly socketPath: string;
@@ -182,32 +376,34 @@ export interface IAgentSessionMetadata {
     readonly status?: SessionStatus;
     /** Human-readable description of what the session is currently doing. */
     readonly activity?: string;
-    readonly model?: ModelSelection;
-    /**
-     * Selected custom agent for this session. Absent (`undefined`) means no
-     * custom agent is selected — the session uses the provider's default
-     * behavior.
-     */
-    readonly agent?: AgentSelection;
     readonly workingDirectory?: URI;
     readonly customizationDirectory?: URI;
     readonly isRead?: boolean;
     readonly isArchived?: boolean;
+    /**
+     * Aggregate counts (additions / deletions / files) describing the
+     * `changeKind: 'session'` changeset for this session — the chip
+     * aggregate previously embedded in the catalogue entry. Mirrors
+     * `SessionSummary.changes`.
+     */
+    readonly changes?: ChangesSummary;
     /**
      * Catalogue of changesets the agent can produce for this session — the
-     * {@link ChangesetSummary | catalogue} that travels on
+     * {@link Changeset | catalogue} that travels on
      * `SessionSummary.changesets`. Lightweight summary entries (id / label /
      * URI template / aggregate counts) without per-file detail; clients
      * subscribe to a specific expanded changeset URI when they need the full
      * file list.
      */
-    readonly changesets?: readonly ChangesetSummary[];
+    readonly changesets?: readonly Changeset[];
     /**
      * Side-channel metadata mirroring {@link SessionState._meta}, propagated
-     * to clients via per-session state subscriptions.
-     * Producers SHOULD use namespaced keys; consumers MUST ignore unknown
-     * keys. Use the typed accessors in `sessionState.ts` (e.g.
-     * `readSessionGitState`) for well-known slots.
+     * to clients via per-session state subscriptions and the root-channel
+     * session summary (the host treats the session-state and session-summary
+     * `_meta` as the same bag). Producers SHOULD use namespaced keys; consumers
+     * MUST ignore unknown keys. Use the typed accessors in `sessionState.ts`
+     * (e.g. `readSessionGitState`, `readSessionGitHubState`) for well-known
+     * slots.
      */
     readonly _meta?: SessionMeta;
 }
@@ -223,7 +419,7 @@ export interface IAgentCreateSessionResult {
     /**
      * `true` when the agent only allocated an in-memory placeholder for this
      * session (no SDK session, no worktree, no on-disk state). Materialization
-     * happens lazily on the first {@link IAgent.sendMessage}, at which point
+     * happens lazily on the first {@link IAgentChats.sendMessage}, at which point
      * the agent fires {@link IAgent.onDidMaterializeSession}. The
      * {@link IAgentService} uses this flag to defer the `sessionAdded` protocol
      * notification so observers don't see the session in their list until it
@@ -242,11 +438,27 @@ export interface IAgentMaterializeSessionEvent {
     readonly project: IAgentSessionProjectInfo | undefined;
 }
 export type AgentProvider = string;
+/** Well-known agent provider id for the Claude agent-host backend. */
+export declare const CLAUDE_AGENT_PROVIDER_ID: "claude";
+/**
+ * Static capability facts an agent backend advertises about itself. Each flag
+ * is opt-in (absent means unsupported) so single-chat agents (e.g. Codex) can omit
+ * the bag entirely. Discovered over IPC alongside the rest of
+ * {@link IAgentDescriptor} and surfaced to the sessions UI so features are
+ * capability-gated instead of switched on the provider id.
+ *
+ * This is the IPC contract alias of the protocol-visible {@link AgentCapabilities}
+ * type (defined in the root-state protocol); both share a single canonical shape
+ * so a new flag added in one place is automatically reflected in the other.
+ */
+export type IAgentCapabilities = AgentCapabilities;
 /** Metadata describing an agent backend, discovered over IPC. */
 export interface IAgentDescriptor {
     readonly provider: AgentProvider;
     readonly displayName: string;
     readonly description: string;
+    /** Static capability flags the agent advertises (see {@link IAgentCapabilities}). */
+    readonly capabilities?: IAgentCapabilities;
 }
 /**
  * Parameters for the `authenticate` command.
@@ -316,7 +528,7 @@ export interface IAgentCreateSessionConfig {
     /**
      * Eagerly claim the active client role for the new session. When provided,
      * the server initializes the session with this client as the active
-     * client, equivalent to dispatching a `session/activeClientChanged`
+     * client, equivalent to dispatching a `session/activeClientSet`
      * action immediately after creation. The `clientId` MUST match the
      * connection's own `clientId`.
      */
@@ -334,6 +546,182 @@ export interface IAgentCreateSessionConfig {
          */
         readonly turnIdMapping?: ReadonlyMap<string, string>;
     };
+    /**
+     * MCP-style opt-in progress token from the client's `createSession`. When
+     * set, the service reports any long-running session bring-up work — chiefly
+     * the lazy first-use SDK download — as `progress` notifications carrying
+     * this token, so the client can correlate them to this call.
+     */
+    readonly progressToken?: string;
+}
+/** Options for creating an additional chat within a session. */
+export interface IAgentCreateChatOptions {
+    /** Optional display title for the new chat. */
+    readonly title?: string;
+    /** Optional model override; defaults to the session's model. */
+    readonly model?: ModelSelection;
+    /**
+     * Fork an existing chat into this new chat. The new chat starts
+     * pre-populated with the source chat's turns up to and including
+     * {@link IAgentCreateChatForkSource.turnId}, and its backing chat
+     * is forked from the source so it can continue independently.
+     */
+    readonly fork?: IAgentCreateChatForkSource;
+}
+/** Identifies a source chat and turn to fork a new chat from. */
+export interface IAgentCreateChatForkSource {
+    /** URI of the existing chat to fork from. */
+    readonly source: URI;
+    /** Turn ID in the source chat; content up to and including this turn is copied. */
+    readonly turnId: string;
+    /**
+     * Maps old source turn IDs to fresh turn IDs for the forked chat. Populated
+     * by the agent service so the agent can remap per-turn data (e.g. SDK event
+     * ID mappings) in the forked chat's database.
+     */
+    readonly turnIdMapping?: ReadonlyMap<string, string>;
+}
+/** Result of {@link IAgentChats.createChat}: the opaque blob to persist for restore. */
+export interface IAgentCreateChatResult {
+    /**
+     * Opaque, agent-owned token the orchestrator persists verbatim in the chat
+     * catalog and hands back to {@link IAgent.materializeChat} on
+     * restore. The orchestrator never parses it. `undefined` means nothing to
+     * persist (e.g. the agent keeps no resumable backing).
+     */
+    readonly providerData?: string;
+    /**
+     * The SDK-level session URI that backs this peer chat, when the agent mints
+     * one in the same session store its own {@link IAgent.listSessions} enumerates
+     * (e.g. Claude). First-class and non-opaque — unlike {@link providerData} the
+     * orchestrator reads it to correlate and suppress the backing session so it
+     * never surfaces as a top-level session. `undefined` when the agent keeps no
+     * separately-enumerable backing session.
+     */
+    readonly backingSession?: URI;
+}
+/** Payload of {@link IAgent.onDidChangeChatData}. */
+export interface IAgentChatDataChange {
+    /** The peer chat whose backing chat's blob changed. */
+    readonly chat: URI;
+    /** The new opaque blob to persist (replaces any previously stored value). */
+    readonly providerData: string;
+}
+/** A legacy peer chat enumerated by {@link IAgent.listLegacyChats} for one-time migration. */
+export interface IAgentLegacyChat {
+    /** The peer chat's channel URI (see {@link buildChatUri}). */
+    readonly uri: URI;
+    /** The opaque, agent-owned backing blob, encoded as {@link materializeChat} expects. */
+    readonly providerData?: string;
+}
+/**
+ * Identifies the parent that spawned a chat. The orchestrator records
+ * it as the spawned chat's {@link ChatOriginKind.Tool} origin so clients can
+ * render the parent/child relationship (e.g. a sub-agent "team" member spawned
+ * by a tool call in the parent chat).
+ */
+export interface IAgentSpawnedChatParent {
+    /** The parent chat (chat) URI whose tool call performed the spawn. */
+    readonly chat: URI;
+    /** The id of the tool call in the parent that spawned this chat. */
+    readonly toolCallId: string;
+}
+/**
+ * Payload of {@link IAgent.onDidSpawnChat}: a new chat the
+ * agent spawned itself (e.g. a sub-agent delegated by a tool call), as opposed
+ * to a user-driven chat created via
+ * {@link IAgentChats.createChat}.
+ */
+export interface IAgentSpawnChatEvent {
+    /** The session URI the spawned chat belongs to. */
+    readonly session: URI;
+    /** The spawned chat's channel URI (the new chat). */
+    readonly chat: URI;
+    /**
+     * The parent that spawned it, when the spawn was delegated by a tool call.
+     * Recorded as the chat's tool origin in the catalog. Absent for a
+     * top-level, agent-initiated chat with no spawning tool call.
+     */
+    readonly parent?: IAgentSpawnedChatParent;
+    /** Optional display title for the spawned chat. */
+    readonly title?: string;
+}
+/**
+ * Builds the tab title for a subagent peer chat. Prefers the concise
+ * per-task description (so two subagents of the same type still get
+ * distinct, meaningful names), truncating it so an over-long value never
+ * blows out the tab strip or the Subagents dropdown; falls back to the
+ * agent type's display name, then a generic label. Shared by the live
+ * spawn path and the restore path so both name subagent tabs identically.
+ */
+export declare function subagentChatTitle(taskDescription: string | undefined, agentDisplayName: string | undefined): string;
+/**
+ * Maps agent `subagent_*` signals to the unified chat catalog's
+ * spawn/end events. Shared by the agents' spawn bridges and the orchestrator so
+ * subagent membership has one derivation.
+ */
+export declare namespace SubagentChatSignal {
+    /**
+     * Derives the {@link IAgentSpawnChatEvent} for a `subagent_started` signal,
+     * addressing the subagent by the stable {@link buildSubagentChatUri} and
+     * recording the spawning tool call as its parent edge. Returns `undefined`
+     * for any other signal (or an unmappable chat URI).
+     */
+    function toSpawnEvent(signal: AgentSignal): IAgentSpawnChatEvent | undefined;
+}
+/**
+ * The chat-addressed operation surface an agent exposes for the chats
+ * within a session.
+ *
+ * Every operation method addresses a chat by a concrete chat channel URI:
+ * the default chat channel for a session's DEFAULT chat, or an additional
+ * chat's own channel URI. The orchestrator ({@link IAgentService}) owns the
+ * feature-level `(session, chat)` to chat-channel mapping and only ever calls
+ * these operations with a concrete chat URI. This replaces the legacy
+ * `(session, chat?)` parameter pairs and the per-agent default-chat handling on
+ * {@link IAgent}.
+ *
+ * Optional on {@link IAgent}: agents implement this incrementally (waves
+ * C2/C3/C4). Until an agent exposes it, {@link IAgentService} falls back to the
+ * agent's legacy `(session, chat?)` methods via a thin adapter.
+ */
+export interface IAgentChats {
+    /**
+     * Create a fresh additional chat within the session the `chat` URI belongs
+     * to, sharing the session's working directory, model, agent, and
+     * customizations. `chat` is the client-chosen channel URI the new chat is
+     * addressed by; its parent session is derived from it.
+     * Returns the opaque {@link IAgentCreateChatResult} blob to persist for
+     * restore (or `void` when the agent keeps no resumable backing).
+     */
+    createChat(chat: URI, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
+    /**
+     * Fork a new chat from an existing one. The new `chat`
+     * inherits `source`'s backing up to and including
+     * {@link IAgentCreateChatForkSource.turnId} and then continues
+     * independently. The new chat's parent session is derived from its URI.
+     */
+    fork(chat: URI, source: IAgentCreateChatForkSource, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
+    /**
+     * Dispose an additional chat created via
+     * {@link createChat}/{@link fork}, freeing its backing. A session's
+     * default chat cannot be disposed in isolation; it lives and dies
+     * with the session.
+     */
+    disposeChat(chat: URI): Promise<void>;
+    /** Send a user message into `chat`. */
+    sendMessage(chat: URI, prompt: string, attachments?: readonly MessageAttachment[], turnId?: string, senderClientId?: string): Promise<void>;
+    /** Abort the in-flight turn for `chat`. */
+    abort(chat: URI): Promise<void>;
+    /** Change the model for `chat`. */
+    changeModel(chat: URI, model: ModelSelection): Promise<void>;
+    /**
+     * Change (or clear) the selected custom agent for `chat`. Passing
+     * `undefined` clears the selection (provider default behavior).
+     */
+    changeAgent(chat: URI, agent: AgentSelection | undefined): Promise<void>;
+    /** Reconstruct the turns for `chat` (used on restore). */
+    getMessages(chat: URI): Promise<readonly Turn[]>;
 }
 export interface IAgentResolveSessionConfigParams {
     readonly provider?: AgentProvider;
@@ -350,6 +738,8 @@ export interface IAgentModelInfo {
     readonly id: string;
     readonly name: string;
     readonly maxContextWindow?: number;
+    readonly maxOutputTokens?: number;
+    readonly maxPromptTokens?: number;
     readonly supportsVision: boolean;
     readonly configSchema?: ConfigSchema;
     readonly policyState?: PolicyState;
@@ -371,15 +761,15 @@ export type AgentSignal = IAgentActionSignal | IAgentToolPendingConfirmationSign
  * dispatches the action through the state manager after routing via
  * {@link IAgentActionSignal.parentToolCallId} (if set).
  *
- * Agents are responsible for populating `session` and any `turnId` /
+ * Agents are responsible for populating the target channel and any `turnId` /
  * `partId` fields on the action.
  */
 export interface IAgentActionSignal {
     readonly kind: "action";
-    /** Top-level session URI. For inner subagent events this is the parent session — see {@link parentToolCallId}. */
-    readonly session: URI;
+    /** Target session or chat channel URI. For inner subagent events this is the parent session — see {@link parentToolCallId}. */
+    readonly resource: URI;
     /** Protocol action to dispatch. */
-    readonly action: SessionAction;
+    readonly action: SessionAction | ChatAction;
     /** If set, route the action to the subagent session belonging to this tool call. */
     readonly parentToolCallId?: string;
 }
@@ -388,7 +778,7 @@ export interface IAgentActionSignal {
  * whether it should run (or, mid-execution, re-confirm). The host applies
  * auto-approval logic over {@link permissionKind} / {@link permissionPath}
  * (see `SessionPermissionManager.getAutoApproval`) and then dispatches the
- * appropriate `SessionToolCallReady` action — with confirmation options
+ * appropriate `ChatToolCallReady` action — with confirmation options
  * baked in when the user must approve, or with `confirmed: NotNeeded` when
  * the host auto-approved.
  *
@@ -399,19 +789,26 @@ export interface IAgentActionSignal {
  */
 export interface IAgentToolPendingConfirmationSignal {
     readonly kind: "pending_confirmation";
-    readonly session: URI;
-    /** Protocol-shaped pending-confirmation state, dispatched verbatim into `SessionToolCallReady`. */
+    /** Target chat channel URI containing the tool call. */
+    readonly chat: URI;
+    /** Protocol-shaped pending-confirmation state, dispatched verbatim into `ChatToolCallReady`. */
     readonly state: ToolCallPendingConfirmationState;
     /** Host-only auto-approval kind (not part of the dispatched action). */
     readonly permissionKind?: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "hook" | "memory" | "extension-management" | "extension-permission-access";
     /** Host-only auto-approval path target (not part of the dispatched action). */
     readonly permissionPath?: string;
+    /**
+     * Host-only flag (not part of the dispatched action): the model requested
+     * this shell command run OUTSIDE the sandbox (and the host opted in via
+     * `sandbox.allowBypass`).
+     */
+    readonly requestSandboxBypass?: boolean;
     /**
      * If set, the tool call belongs to the subagent rooted at this
      * parent tool call. Used by the host to route the resulting
-     * `SessionToolCallReady` to the subagent session — otherwise the
+     * `ChatToolCallReady` to the subagent session — otherwise the
      * action would land on the parent session, where there is no
-     * matching `SessionToolCallStart`.
+     * matching `ChatToolCallStart`.
      */
     readonly parentToolCallId?: string;
 }
@@ -424,11 +821,36 @@ export interface IAgentToolPendingConfirmationSignal {
  */
 export interface IAgentSubagentStartedSignal {
     readonly kind: "subagent_started";
-    readonly session: URI;
+    readonly chat: URI;
     readonly toolCallId: string;
     readonly agentName: string;
     readonly agentDisplayName: string;
     readonly agentDescription?: string;
+    /**
+     * The spawning Task tool's short (typically 3-5 word) `description`
+     * input, e.g. "Review package.json structure". Distinct from
+     * {@link agentDescription} (the agent *type*'s long role blurb) and
+     * {@link agentDisplayName} (the agent type's name). Preferred as the
+     * peer chat's tab title because it is concise and per-task, so two
+     * subagents of the same type still get distinct, meaningful names.
+     * Absent when the harness does not surface a task description.
+     */
+    readonly taskDescription?: string;
+    /**
+     * If set, the spawning tool call ({@link toolCallId}) itself lives
+     * inside another subagent's chat — this is the tool call **one level up**
+     * from the spawning tool (its parent), i.e. the tool that spawned the
+     * immediate parent chat. The host uses it to route the
+     * subagent-discovery side effect (the `ChatToolCallContentChanged`
+     * block that lets clients find the child chat) to that immediate parent
+     * chat rather than the top-level {@link chat}. Because subagent chats
+     * are flat (all keyed off the root session + the spawning tool id),
+     * this single one-hop reference resolves the correct parent chat at
+     * ANY nesting depth — no per-level chain is needed. Absent for a
+     * top-level subagent, whose spawning tool call lives directly in
+     * {@link chat}.
+     */
+    readonly parentToolCallId?: string;
 }
 /**
  * A subagent has finished — either successfully or with an error. The host
@@ -439,13 +861,13 @@ export interface IAgentSubagentStartedSignal {
  */
 export interface IAgentSubagentCompletedSignal {
     readonly kind: "subagent_completed";
-    readonly session: URI;
+    readonly chat: URI;
     readonly toolCallId: string;
 }
 /** A steering message was consumed (sent to the model). */
 export interface IAgentSteeringConsumedSignal {
     readonly kind: "steering_consumed";
-    readonly session: URI;
+    readonly chat: URI;
     readonly id: string;
 }
 export declare namespace AgentSession {
@@ -465,6 +887,58 @@ export declare namespace AgentSession {
      */
     function provider(session: URI | string): AgentProvider | undefined;
 }
+/**
+ * A notification originating from an MCP server, routed back to the AHP
+ * client through the `mcp://` side channel. `channel` is the channel
+ * URI advertised on the owning
+ * {@link McpServerCustomization.channel | McpServerCustomization}; the
+ * client uses it to fan the notification out to the appropriate App.
+ * `method` and `params` follow the underlying MCP notification spec
+ * (e.g. `notifications/tools/list_changed`).
+ */
+export interface IMcpNotification {
+    readonly channel: string;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+/**
+ * A subagent child session discovered in a parent session's event log,
+ * returned by {@link IAgent.getSubagentSessions} so a parent restore can
+ * register the child's state up-front.
+ */
+export interface IRestoredSubagentSession {
+    /** Child subagent session URI (subscribable by clients). */
+    readonly resource: URI;
+    /** Parent tool call id that spawned the subagent. */
+    readonly toolCallId: string;
+    /** Display title for the subagent session. */
+    readonly title: string;
+    /** Reconstructed turns for the subagent's transcript. */
+    readonly turns: readonly Turn[];
+}
+/**
+ * A per-session handle for one active client's contributions (tools and
+ * plugin customizations) to an agent session, obtained via
+ * {@link IAgent.getOrCreateActiveClient}.
+ *
+ * `tools` and `customizations` are mutable accessor properties: assigning a
+ * new array replaces this client's contribution wholesale and triggers the
+ * agent's internal reaction (refreshing the merged tool set exposed to the
+ * model, or kicking off an asynchronous customization sync). The arrays are
+ * `readonly` so callers cannot mutate them in place and silently bypass the
+ * setter. The agent merges the contributions of all active clients on a
+ * session, deduplicating as needed.
+ */
+export interface IActiveClient {
+    /** Client identifier (matches `clientId` from `initialize`). */
+    readonly clientId: string;
+    /** Human-readable client name (e.g. `"VS Code"`), if provided. */
+    readonly displayName: string | undefined;
+    /** This client's tools. Assigning replaces the set (full replacement). */
+    tools: readonly ToolDefinition[];
+    /** This client's plugin customizations. Assigning replaces the set and starts an internal sync. */
+    customizations: readonly ClientPluginCustomization[];
+}
 /**
  * Implemented by each agent backend (e.g. Copilot SDK).
  * The {@link IAgentService} dispatches to the appropriate agent based on
@@ -484,23 +958,74 @@ export interface IAgent {
      * summary.
      */
     readonly onDidMaterializeSession?: Event<IAgentMaterializeSessionEvent>;
+    /**
+     * Provides the agent host's server-tool host so the provider can advertise
+     * and execute the agent host's server tools (feedback "comments" today, more
+     * in the future) against a session's state. Optional: providers that do not
+     * support server-side tools simply omit it. Called once during registration
+     * with the {@link IAgentService}.
+     */
+    setServerToolHost?(host: IAgentServerToolHost): void;
+    /**
+     * Chat-addressed surface for the chats within a session (send/abort/
+     * change model/agent, create/fork/dispose chats, read history).
+     */
+    readonly chats: IAgentChats;
     /** Create a new session. Returns server-owned session metadata. */
     createSession(config?: IAgentCreateSessionConfig): Promise<IAgentCreateSessionResult>;
     /** Resolve the dynamic configuration schema for creating a session. */
     resolveSessionConfig(params: IAgentResolveSessionConfigParams): Promise<ResolveSessionConfigResult>;
     /** Return dynamic completions for a session configuration property. */
     sessionConfigCompletions(params: IAgentSessionConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
-    /** Send a user message into an existing session. */
-    sendMessage(session: URI, prompt: string, attachments?: readonly MessageAttachment[], turnId?: string): Promise<void>;
+    /**
+     * Re-attach an agent's in-memory backing for a peer chat on session
+     * restore, decoding the opaque `providerData` produced earlier by
+     * {@link IAgentChats.createChat} (or the latest
+     * {@link onDidChangeChatData}). After this resolves the agent MUST
+     * be able to serve {@link getSessionMessages}/
+     * {@link IAgentChats.sendMessage} for `chat`.
+     * Best-effort: implementations SHOULD NOT throw on a corrupt/unknown blob —
+     * log and no-op so the orchestrator restores the chat with history but no
+     * live backing. `providerData` is `undefined` only for legacy entries with
+     * no stored blob, in which case the agent MAY consult its own legacy
+     * persistence once to recover the backing.
+     */
+    materializeChat?(chat: URI, providerData: string | undefined): Promise<void>;
+    /**
+     * Migration-only enumeration of a session's peer chats persisted in the
+     * agent's OWN legacy format (predating the orchestrator-owned catalog). The
+     * orchestrator calls this once, when its own catalog is absent, to drain the
+     * legacy chats into {@link PEER_CHATS_METADATA_KEY}; subsequent restores read
+     * the orchestrator catalog and never consult this again. Each entry's
+     * `providerData` uses the same encoding {@link IAgentChats.createChat}
+     * produces and {@link materializeChat} decodes. Agents with no legacy
+     * format (e.g. Codex) omit this method.
+     */
+    listLegacyChats?(session: URI): Promise<readonly IAgentLegacyChat[]>;
+    /**
+     * Fires when a peer chat's opaque `providerData` changes after creation
+     * (e.g. per-chat model switch, fork remap). The orchestrator re-persists the
+     * blob. Agents whose blob is immutable never fire this.
+     */
+    readonly onDidChangeChatData?: Event<IAgentChatDataChange>;
+    /**
+     * Fires when the agent spawns a new chat within a session (e.g. a
+     * sub-agent delegated by a tool call). The orchestrator records it in the
+     * chat catalog, preserving the {@link IAgentSpawnChatEvent.parent}
+     * spawn edge as the chat's {@link ChatOriginKind.Tool} origin.
+     */
+    readonly onDidSpawnChat?: Event<IAgentSpawnChatEvent>;
     /**
      * Called when the session's pending (steering) message changes.
      * The agent harness decides how to react — e.g. inject steering
-     * mid-turn via `mode: 'immediate'`.
+     * mid-turn via `mode: 'immediate'`. When `chat` is provided (an additional
+     * peer chat's URI), the steering targets that chat's chat rather
+     * than the session's default chat.
      *
      * Queued messages are consumed on the server side and are not
      * forwarded to the agent; `queuedMessages` will always be empty.
      */
-    setPendingMessages?(session: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[]): void;
+    setPendingMessages?(session: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[], chat?: URI): void;
     /**
      * Retrieve the reconstructed turns for a session, used when restoring
      * sessions from persistent storage. Each agent owns the conversion from
@@ -509,23 +1034,22 @@ export interface IAgent {
      * child session's turns).
      */
     getSessionMessages(session: URI): Promise<readonly Turn[]>;
-    /** Dispose a session, freeing resources. */
-    disposeSession(session: URI): Promise<void>;
-    /** Abort the current turn, stopping any in-flight processing. */
-    abortSession(session: URI): Promise<void>;
-    /** Change the model for an existing session. */
-    changeModel(session: URI, model: ModelSelection): Promise<void>;
     /**
-     * Change (or clear) the selected custom agent for an existing session.
-     * Passing `undefined` clears the selection and resets the session to no
-     * selected custom agent (provider default behavior). Optional so non-
-     * Copilot agents can opt out.
+     * Returns the subagent child sessions discoverable in a session's event
+     * log so a parent restore can eagerly register them in a single pass.
+     * Without this, every child is restored separately by re-fetching and
+     * re-reconstructing the full parent event log (one pass per subagent).
+     * Agents that serve this from the same reconstruction they already
+     * produced for the parent turns avoid that redundant work entirely.
+     * Optional; agents without subagents omit it.
      */
-    changeAgent?(session: URI, agent: AgentSelection | undefined): Promise<void>;
+    getSubagentSessions?(session: URI): Promise<readonly IRestoredSubagentSession[]>;
+    /** Dispose a session, freeing resources. */
+    disposeSession(session: URI): Promise<void>;
     /** Respond to a pending permission request from the SDK. */
     respondToPermissionRequest(requestId: string, approved: boolean): void;
     /** Respond to a pending user input request from the SDK's ask_user tool. */
-    respondToUserInputRequest(requestId: string, response: SessionInputResponseKind, answers?: Record<string, SessionInputAnswer>): void;
+    respondToUserInputRequest(requestId: string, response: ChatInputResponseKind, answers?: Record<string, ChatInputAnswer>): void;
     /** Return the descriptor for this agent. */
     getDescriptor(): IAgentDescriptor;
     /** Available models from this provider. */
@@ -542,6 +1066,14 @@ export interface IAgent {
      * can republish {@link AgentInfo} and session customization state.
      */
     readonly onDidCustomizationsChange?: Event<void>;
+    /**
+     * Fires when this agent needs the client to (re-)authenticate a
+     * protected resource — for example after a runtime transport-mode flip
+     * makes a previously-unneeded credential required. The host stamps the
+     * root channel and forwards it verbatim as an `auth/required`
+     * notification; clients respond via {@link authenticate}.
+     */
+    readonly onDidRequireAuth?: Event<Omit<AuthRequiredParams, "channel">>;
     /**
      * Returns the host-owned customizations this agent currently exposes.
      *
@@ -561,11 +1093,21 @@ export interface IAgent {
      */
     authenticate(resource: string, token: string): Promise<boolean>;
     /**
-     * Truncate a session's history. If `turnId` is provided, keeps turns up to
+     * Optional hook for provider-owned session resources that are not advertised
+     * as root agent protected resources, such as MCP server OAuth challenges.
+     */
+    handleAuthenticationToken?(params: AuthenticateParams): Promise<boolean>;
+    /**
+     * Truncate a chat's history. If `turnId` is provided, keeps turns up to
      * and including that turn. If omitted, all turns are removed.
+     *
+     * `chat` identifies which chat to truncate: the session's default chat
+     * (addressed by the session's default chat URI) or a peer (non-default)
+     * chat, which has its own backing.
+     *
      * Optional — not all providers support truncation.
      */
-    truncateSession?(session: URI, turnId?: string): Promise<void>;
+    truncateSession?(session: URI, turnId: string | undefined, chat: URI): Promise<void>;
     /**
      * Notifies the provider that a session's archived state has changed.
      * Providers may use this to clean up or restore per-session resources
@@ -574,35 +1116,41 @@ export interface IAgent {
      */
     onArchivedChanged?(session: URI, isArchived: boolean): Promise<void>;
     /**
-     * Receives client-provided customization refs for a session and syncs them
-     * (e.g. copies plugin files to local storage). The agent publishes
-     * customization state actions as the sync progresses.
+     * Get (or lazily create) the per-session handle for an active client,
+     * identified by `clientId`. Mutating the returned {@link IActiveClient}'s
+     * `tools` / `customizations` updates only that client's contribution; the
+     * agent merges the contributions of all active clients when exposing them
+     * to the model. A session MAY have several active clients at once.
      *
-     * The agent MAY defer a client restart until all active sessions are idle.
+     * @param session The session URI this client contributes to.
+     * @param client The client's `clientId` and optional human-readable name.
      */
-    setClientCustomizations(session: URI, clientId: string, customizations: ClientPluginCustomization[]): Promise<ISyncedCustomization[]>;
+    getOrCreateActiveClient(session: URI, client: {
+        readonly clientId: string;
+        readonly displayName?: string;
+    }): IActiveClient;
     /**
-     * Receives client-provided tool definitions to make available in a
-     * specific session. The agent registers these as custom tools so the
-     * LLM can call them; execution is routed back to the owning client.
+     * Remove an active client from a session, clearing its tool and
+     * customization contributions. No-op when no active client matches
+     * `clientId`.
      *
-     * Always called on `activeClientChanged`, even with an empty array,
-     * to clear a previous client's tools.
-     *
-     * @param session The session URI this tool set applies to.
-     * @param clientId The client that owns these tools.
-     * @param tools The tool definitions (full replacement).
+     * @param session The session the client is leaving.
+     * @param clientId The client to remove.
      */
-    setClientTools(session: URI, clientId: string, tools: ToolDefinition[]): void;
+    removeActiveClient(session: URI, clientId: string): void;
     /**
      * Called when a client completes a client-provided tool call.
      * Resolves the tool handler's deferred promise so the SDK can continue.
      *
      * @param session The session the tool call belongs to.
+     * @param chat The chat channel the tool call was issued on, when known.
+     * Agents that track peer chats separately from the default chat (e.g.
+     * copilot) use this to route the completion to the right chat;
+     * agents without peer chats ignore it and resolve by `session`.
      * @param toolCallId The id of the tool call being completed.
      * @param result The result of the tool call.
      */
-    onClientToolCallComplete(session: URI, toolCallId: string, result: ToolCallResult): void;
+    onClientToolCallComplete(session: URI, chat: URI, toolCallId: string, result: ToolCallResult): void;
     /**
      * Notifies the agent that a customization has been toggled on or off.
      * The agent MAY restart its client before the next message is sent.
@@ -612,6 +1160,32 @@ export interface IAgent {
     setCustomizationEnabled(id: string, enabled: boolean): void;
     /** Gracefully shut down all sessions. */
     shutdown(): Promise<void>;
+    /**
+     * Routes a request received on an `mcp://` side channel to the agent's
+     * MCP server implementation. The channel carries raw MCP JSON-RPC
+     * methods (e.g. `tools/list`, `tools/call`, `resources/read`) tagged
+     * with the routing envelope; the protocol server decodes the envelope
+     * and forwards `(session, serverName, method, params)` here.
+     *
+     * The agent MUST reject unknown methods with an error whose message
+     * begins with `Method not found` so the protocol server can map it to
+     * a JSON-RPC `-32601`.
+     *
+     * Optional — agents that don't surface any MCP servers (or don't
+     * advertise `mcpApp` capabilities) can omit this.
+     */
+    handleMcpRequest?(session: URI, serverName: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
+    /**
+     * Fires when an MCP server owned by this agent emits a notification
+     * that should be forwarded to AHP clients over the `mcp://` side
+     * channel. Today this is exclusively
+     * `notifications/tools/list_changed` and
+     * `notifications/resources/list_changed`. The protocol server
+     * fans the notification out to every connected client.
+     *
+     * Optional — agents that don't expose MCP servers can omit this.
+     */
+    readonly onMcpNotification?: Event<IMcpNotification>;
     /** Dispose this provider and all its resources. */
     dispose(): void;
 }
@@ -633,6 +1207,12 @@ export interface IAgentConnection {
      */
     getSubscription<T extends StateComponents>(kind: T, resource: URI, owner: string): IReference<IAgentSubscription<ComponentToState[T]>>;
     getSubscriptionUnmanaged<T extends StateComponents>(kind: T, resource: URI): IAgentSubscription<ComponentToState[T]> | undefined;
+    /**
+     * Returns the in-flight `createSession` Promise for `resource`, or `undefined` if no create is pending. Callers
+     * that need to gate work on a racing eager `createSession` (e.g. before deciding whether to fall through to a
+     * duplicate create) should await this first.
+     */
+    getInflightSessionCreate(resource: URI): Promise<unknown> | undefined;
     /**
      * Read-only descriptors of every active resource subscription on this
      * connection, for inspection/debug surfaces. Excludes the always-live
@@ -647,9 +1227,28 @@ export interface IAgentConnection {
      * than {@link URI} objects so authority-less scheme URIs like
      * `ahp-root://` survive the wire format without normalization.
      */
-    dispatch(channel: string, action: SessionAction | TerminalAction | IRootConfigChangedAction): void;
+    dispatch(channel: string, action: SessionAction | ChatAction | TerminalAction | ClientAnnotationsAction | IRootConfigChangedAction): void;
     readonly onDidNotification: Event<INotification>;
     readonly onDidAction: Event<ActionEnvelope>;
+    /**
+     * Fires when the host forwards an MCP server notification (e.g.
+     * `notifications/tools/list_changed`) over the `mcp://` side channel.
+     * The `channel` field on the notification routes the payload to the
+     * matching {@link McpServerCustomization}.
+     */
+    readonly onMcpNotification: Event<IMcpNotification>;
+    /**
+     * Send a request on an `mcp://` AHP side channel. `channel` is the
+     * `mcp://` URI advertised by the matching {@link McpServerCustomization}
+     * (only available while the server is `ready`). `method` is the raw MCP
+     * JSON-RPC method (e.g. `tools/call`, `resources/read`,
+     * `sampling/createMessage`); `params` are the JSON-RPC params (the
+     * connection adds the routing envelope's `channel` field automatically).
+     *
+     * Rejects with an `Error` whose message begins with `Method not found`
+     * when the channel is unknown or the host doesn't recognise the method.
+     */
+    handleMcpRequest(channel: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
     authenticate(params: AuthenticateParams): Promise<AuthenticateResult>;
     listSessions(): Promise<IAgentSessionMetadata[]>;
     createSession(config?: IAgentCreateSessionConfig): Promise<URI>;
@@ -663,6 +1262,14 @@ export interface IAgentConnection {
      */
     getCompletionTriggerCharacters(): Promise<readonly string[]>;
     disposeSession(session: URI): Promise<void>;
+    /**
+     * Create an additional peer chat inside an existing session. `chat` is a
+     * client-chosen chat URI (see {@link buildChatUri}). The host adds the
+     * chat to the session's catalog and publishes `session/chatAdded`.
+     */
+    createChat(session: URI, chat: URI, options?: IAgentCreateChatOptions): Promise<void>;
+    /** Dispose an additional chat created via {@link createChat}. */
+    disposeChat(chat: URI): Promise<void>;
     createTerminal(params: CreateTerminalParams): Promise<void>;
     disposeTerminal(terminal: URI): Promise<void>;
     invokeChangesetOperation(params: InvokeChangesetOperationParams): Promise<InvokeChangesetOperationResult>;