customizations-in-the-agent-host

name	customizations-in-the-agent-host
description	Architecture and hard-won debugging lessons for customization enablement (plugins, MCP servers, agents, skills, instructions) in the agent host. Use when changing how customizations are discovered, published, enabled/disabled, or handed to a provider SDK; when a customization shows the wrong enabled state in the UI; or when a disabled MCP server or plugin is still reaching the model.

Customizations in the Agent Host

Customizations are the plugins, MCP servers, agents, skills and instructions that an agent-host session exposes to a model. This skill covers enablement: how a customization's on/off state is decided, stored, published and enforced.

Read this before changing anything in:

• src/vs/platform/agentHost/node/agentHostCustomizationEnablementService.ts
• src/vs/platform/agentHost/node/shared/customizationEnablementGate.ts
• src/vs/platform/agentHost/common/customizationEnablement.ts
• the per-provider customization paths under node/copilot/, node/claude/, node/codex/

The mental model

Enablement is a list of scoped decisions, not a boolean

A plugin or MCP server carries enablement?: CustomizationEnablement[] — an ordered list of decisions, most specific first:

Kind	Owner	Meaning
Session	agent host	this session only
Workspace	agent host	this working directory (carries uri)
Global	client, unless the host discovered it	everywhere

isCustomizationEnabled() picks the first entry; absent entries inherit from the next scope out, and an absent list means enabled. Never re-add a parallel enabled boolean to plugins or MCP servers — a second source of truth is what this design exists to remove. (DirectoryCustomization legitimately keeps a plain enabled; consumers derive its state through isCustomizationEnabled() all the same.)

Who owns Global

The host owns Global for anything it discovered, even when that thing lives inside a plugin the client forwarded. The client owns Global only for what it actually bundled. The discriminator is childEnablement — not clientId. A plugin whose childEnablement record has a key for a child MCP server means "the client bundled this child and owns its global decision"; anything else the host discovered by parsing the plugin directory.

The overlay model

This is the single most important invariant, and getting it wrong caused a self-defeating write that silently erased user decisions:

The client's value is the base. Host decisions layer on top. "Store only what differs" compares against that base — never against a hardcoded true.

Concretely, in agentHostCustomizationEnablementService.ts:

• _clientGlobalEnablement is the in-memory base, per session. _setClientGlobal writes here and must never touch _persistent.
• _persistent holds only host-owned decisions that differ from the base.
• Inheritance runs host → base → DEFAULT_CUSTOMIZATION_ENABLED (_globalEnablement, _workspaceInheritedEnablement).
• _setPersistentDecision deletes a decision that matches its inherited value, so the UI can restore inheritance without a third "Inherit" action.

Keeping these separate is what stops this loop: replaceEnablement → synchronous republish → client's stale [{global,true}] → _setClientGlobal → "store only what differs" deletes the entry just written.

Identity must not depend on tree position

An MCP server's storage key is derived from owningPluginUri, never from where it happened to appear in the published tree. The same server discovered top-level (mcpServers#azure) and nested under a plugin (<pluginURI>#mcp=azure) must produce one key, or a decision written in one session is invisible to the next. targetForMcpServer() and withOwningPluginUri() in the gate are the only supported way to build that target.

Pending means fail closed — but pending must be transient

resolve() returns {kind:'pending'} when the session isn't initialized yet (reason: 'session') or the working directory isn't known (reason: 'workingDirectory'). resolveCustomizationEnablement() records those in pendingCustomizationIds, and isCustomizationSdkEligible() makes SDK-boundary consumers fail closed.

Two rules follow:

1. Never "fix" a pending customization by defaulting it to enabled.
2. Never cache the pending verdict. Pending is a temporary state; recompute it, and republish when the enablement service settles. A cached pendingEnablement: true silently drops a plugin forever.

A pending child MCP server also marks its containing plugin pending, because a plugin directory can cause the SDK to discover the child on its own.

The rule that prevents most bugs

Every publication, emit and SDK-handoff path must go through resolution.

Three separate production bugs on this feature came from paths that skipped it (four sites in copilotAgent, one in mcpCustomizationController, plus the post-startup reconcile). When you add a new place that publishes a customization or hands one to a provider, route it through resolveCustomizationEnablement() — do not read a stored snapshot.

The corollary: state computed once must be rebuilt when its inputs change. Merged per-client enablement maps that are only appended to will leak stale decisions onto a newly parsed plugin with the same URI.

Enforcement is per-provider, and they differ

Provider	Launch	Mid-session
Copilot	disabledMcpServers on SessionConfig at open/resume	rpc.mcp.enable / rpc.mcp.disable
Claude	session options at materialize	live reconcile
Codex	MCP servers supplied only at thread/start / resume	not possible — documented limitation

Two traps here:

• The post-startup reconcile runs ~800 ms after launch. Anything gated only there can still start, and request authentication, during the launch window. Gate at launch too.
• The SDK's not_configured status must not be translated as enabled: true. That bug made a correct "skip this disabled server" decision look like "enable it".

Client-provided MCP servers (ones the client bundled rather than the host discovering) must route their global Disable to the client, not the host — the host correctly refuses to store a client-owned global, so routing it to the host is a silent no-op. isClientBundled is the discriminator; see getBuiltinMcpServerEnablementActions in mcpListWidget.ts.

Debugging playbook

Rank your signals. They disagree, and the model lies:

1. Primary — the published customization object and the host's stored decision.
2. Definitive for tool exposure — tool_search override … clientMatched=[…] in Agent Host.log.
3. Secondary — the customizations UI.
4. Corroborating only — what the model says. A model answered "yes, I have azure tools" while the server was stopped. Never conclude from this alone.

Reproduction recipe that exercises the real failure surface: start a session, send a message to boot everything, disable the thing, then ask a new session whether it has those tools. Cross-session persistence is where identity and overlay bugs surface.

Use the agent-host-logs skill for exported bundles, and the launch skill to drive a real instance.

Known false alarms:

• The azure plugin contributes 24 azure-* skills in addition to its MCP server. Disabling the server correctly leaves the skills enabled.
• sleepy is a deliberately broken test server that cannot initialize — useless as a positive control.

Gotchas that cost real time

• CustomizationType and CustomizationEnablementKind are const enums. A type-only import compiles and lints cleanly, then crashes at runtime. Import them as values.
• The unit-test runner uses pre-compiled output and does not fail on type errors. Always run npm run typecheck-client separately.
• Integration-test servers start with --quiet. Wiring that you hoist out of if (!options.quiet) in agentHostServerMain.ts silently changes their behaviour — hoisting setWorktreeIsolation made quiet servers resolve isolation: 'folder' and broke seven unrelated tests.
• Protocol files under common/state/protocol/ carry a "DO NOT EDIT — auto-generated" banner. Changes there need a matching backport to the agent-host-protocol repo.
• Electron runner setup aborts (EEXIST/EPERM/ENOENT/ReactiveObjC) are environmental. Recover with rm -rf .build/electron && npm run electron.

Validation

npm run typecheck-client
./scripts/test.sh --grep "customizationEnablement"
./scripts/test-integration.sh --runGlob "**/agentHost/**/{sessionConfig,toolApproval,codexCustomizations}.integrationTest.js"
./scripts/test-integration.sh --run src/vs/platform/agentHost/test/node/claudeAgent.integrationTest.ts

Tests that construct an agent session directly need IAgentHostCustomizationEnablementService in their service collection; use createNoopCustomizationEnablementService() from src/vs/platform/agentHost/test/node/testCustomizationEnablementService.ts.