Ask: A supported way to disable built-in sub-agents

1. The ask

Provide a supported allow-list for built-in sub-agents on SessionConfig — availableBuiltinAgents — where, when the host application supplies the list, only the built-in sub-agents named in it stay enabled and every other built-in is disabled. This lets a host run a session that exposes only the agents it has explicitly allowed; an empty list therefore disables all built-ins.

Today the SDK offers only a name-by-name deny-list (SessionConfig.excludedBuiltinAgents) — there is no allow-list, so there is no way to keep the built-in set closed without enumerating names.

2. Why we need it

An SDK built-in sub-agent auto-exposed in the host. A built-in sub-agent — auto-exposed by the SDK and never validated by the host — was invoked and defaulted to a model not provisioned in the host's environment; it returned repeated 400 "Unknown model" errors and failed the user's turn.

The host's mitigation is to disable the built-in sub-agents entirely and expose only the custom agents it has validated. That is why the host needs a reliable, supported way to turn built-in sub-agents off.

3. What the SDK offers today

Verified against the pinned SDK type definitions and the public custom-agents docs (citations in the Appendix).

excludedBuiltinAgents — a deny-list keyed on exact name. It works, but the host must enumerate and hardcode every built-in name; there is no allow-list and no "disable all" switch.

customAgents — registers the host's own agents only. Neither the type definitions nor the docs state that customAgents disables built-ins, and an empty customAgents does not turn built-ins off (confirmed empirically).

4. What we're asking the SDK to support

A supported allow-list on SessionConfig — availableBuiltinAgents: when the host provides the list, only the built-in sub-agents in it are enabled and all others are disabled; an empty list disables every built-in — with no names to enumerate.

This mirrors the shape the SDK already offers for tools (availableTools with builtin:* / builtin: patterns), so an agent-level equivalent is consistent.

Why an allow-list rather than the existing deny-list: the built-in roster is not guaranteed stable. A deny-list is open by default — every new built-in the SDK adds is exposed until the host discovers it and patches its exclude list. An allow-list is closed by default — new built-ins stay off unless the host opts them in — which removes that ongoing burden and keeps another unvetted built-in from reaching users.

Appendix — sources

SDK type definitions (@github/copilot-sdk-next v1.0.6, types.d.ts):

SessionConfig.excludedBuiltinAgents?: string[] — deny-list by exact name.

SessionConfig.availableTools / excludedTools — allow-list + deny-list for tools, with builtin:* / builtin: patterns.

SessionConfig.customAgents?: CustomAgentConfig[] — "Custom agent configurations for the session"; no built-in-disable semantics.

SDK public documentation — Custom agents (docs.github.com/en/copilot/how-tos/copilot-sdk/features/custom-agents): defines only how to author custom agents (name/description/tools/prompt/infer/skills). It defines no built-in-agent control and no "empty array disables built-ins" semantics.

Originating scenario — Reported as a live-site issue: with only the name-based deny-list available, the host had to disable the built-in set by enumerating the full roster, which was flagged as unmaintainable — hence this request to the SDK for a supported control.

Start with SessionConfig in the pinned SDK type definitions (types.d.ts), then compare availableTools/excludedTools with excludedBuiltinAgents and read the linked custom-agents documentation. Done means exposing availableBuiltinAgents with allow-list semantics, including an empty list that disables all built-ins, and validating the behavior without requiring hosts to enumerate names.

Scritto dal modello di indicizzazione a partire dal testo della issue.