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.

Bắt đầu với SessionConfig trong các định nghĩa kiểu SDK đã được ghim (types.d.ts), sau đó so sánh availableTools/excludedTools với excludedBuiltinAgents và đọc tài liệu custom-agents được liên kết. Hoàn thành có nghĩa là cung cấp availableBuiltinAgents với ngữ nghĩa allow-list, bao gồm cả danh sách rỗng để vô hiệu hóa tất cả các agent tích hợp sẵn, đồng thời xác thực hành vi mà không yêu cầu các host phải liệt kê tên.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.