- 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.
- 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.
- 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).
- 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.
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.
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.
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).
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.