github / github/copilot-cli

FLEET: fleet.start() ignores customAgents — always dispatches built-in agent types

Open
#2,261 1 comment 1 reaction 0 assignees View on GitHub
area:agents
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

## Summary

When a session is created with `customAgents` defined, calling `rpc.fleet.start()` **ignores the registered custom agents entirely**. Sub-agents are dispatched as built-in types (`explore`, `general-purpose`, etc.), never as the custom agents registered in the session config.

## Steps to Reproduce

```javascript
const session = await client.createSession({
onPermissionRequest: async () => ({ approved: true }),
customAgents: [{
name: 'my-researcher',
displayName: 'My Researcher',
description: 'A custom agent that only reads files.',
prompt: 'You are a focused research agent. Only read files.',
tools: ['view', 'grep'],
infer: false,
}],
});

// Confirm registered:
const agentList = await session.rpc.agent.list();
// → { agents: [{ name: 'my-researcher', ... }] } ✓ registered

await session.rpc.fleet.start({ prompt: 'Research X in parallel' });

session.on('subagent.started', (data) => {
console.log(data.agentName);
// → 'explore' ← always built-in, never 'my-researcher'
});
```

## Observed Behaviour

Fleet dispatches `explore` built-ins regardless of `customAgents` config. The custom agent is visible in `rpc.agent.list()` immediately before the fleet call, confirming registration is not the issue.

Spike data (2026-03-17):
```json
{
"agentNamesObserved": ["explore", "explore"],
"subagentCount": 2,
"answer": "PARTIAL — dispatched built-in names, not custom names"
}
```

## Expected Behaviour

One of:
1. `fleet.start()` uses custom agents when registered in the session
2. `fleet.start()` accepts `agentNames: string[]` to specify which agents to dispatch
3. Documentation clarifies fleet only uses built-in types (so callers know not to expect otherwise)

## Impact

- Custom agent tool restrictions (`customAgents[n].tools`) cannot be applied to fleet workers
- Custom system prompts are ignored during fleet
- Fleet workers always get unrestricted built-in agent capabilities regardless of session config

## Environment

- SDK: `@github/copilot-sdk` v0.1.32
- CLI: latest
- Node: v24.13.1

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the session setup with customAgents, then inspect the fleet.start, agent.list, and subagent.started entry points described in the issue. Confirm whether fleet should dispatch registered custom names, accept explicit agentNames, or document built-in-only behavior; done requires an agreed behavior and verification that the observed subagent names and custom restrictions match it.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
api, backend
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.