Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
👯 fix: Separate Subagents and Handoffs Into Native Tools (#16761)
lia-by-librechat[bot]a4f6763b070c
diff --git a/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx b/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsxindex 2f9abe47b4..c76db6b09e 100644--- a/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx@@ -1,59 +1,46 @@-import { useMemo } from 'react';-import { useFormContext, Controller } from 'react-hook-form';+import { Controller, useFormContext } from 'react-hook-form';import { AgentCapabilities, MAX_SUBAGENTS } from 'librechat-data-provider';import type { AgentForm } from '~/common';import { useAgentPanelContext } from '~/Providers';import AgentSubagents from './AgentSubagents';import AgentHandoffs from './AgentHandoffs';-import { groupHeadingClass } from './ui';-import { useLocalize } from '~/hooks';interface OrchestrationHubProps {currentAgentId: string;+ tool: 'subagents' | 'handoffs';}-/**- * Settings for the native orchestration tool. Handoffs are always available.- */-export default function OrchestrationHub({ currentAgentId }: OrchestrationHubProps) {- const localize = useLocalize();+/** Settings for one native collaboration tool, never the other tool's fields. */+export default function OrchestrationHub({ currentAgentId, tool }: OrchestrationHubProps) {const { control } = useFormContext<AgentForm>();const { agentsConfig } = useAgentPanelContext();- const subagentsEnabled = useMemo(- () => agentsConfig?.capabilities.includes(AgentCapabilities.subagents) ?? false,- [agentsConfig],- );- const maxSubagents = agentsConfig?.maxSubagents ?? MAX_SUBAGENTS;-- return (- <section className="flex flex-col gap-1">- <div className="flex flex-col gap-0.5">- <span className={groupHeadingClass}>{localize('com_ui_agent_orchestration')}</span>- <p className="text-text-secondary text-xs">{localize('com_ui_agent_orchestration_hint')}</p>- </div>- <div className="divide-border-light divide-y">- {subagentsEnabled && (- <Controller- name="subagents"- control={control}- render={({ field }) => (- <AgentSubagents- field={field}- currentAgentId={currentAgentId}- maxSubagents={maxSubagents}- fileSharingEnabled={agentsConfig?.fileSharing?.enabled === true}- />- )}+ if (tool === 'subagents') {+ if (!agentsConfig?.capabilities.includes(AgentCapabilities.subagents)) {+ return null;+ }+ return (+ <Controller+ name="subagents"+ control={control}+ render={({ field }) => (+ <AgentSubagents+ field={field}+ currentAgentId={currentAgentId}+ maxSubagents={agentsConfig.maxSubagents ?? MAX_SUBAGENTS}+ fileSharingEnabled={agentsConfig.fileSharing?.enabled === true}/>)}- <Controller- name="edges"- control={control}- defaultValue={[]}- render={({ field }) => <AgentHandoffs field={field} currentAgentId={currentAgentId} />}- />- </div>- </section>+ />+ );+ }++ return (+ <Controller+ name="edges"+ control={control}+ defaultValue={[]}+ render={({ field }) => <AgentHandoffs field={field} currentAgentId={currentAgentId} />}+ />);}diff --git a/client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsx b/client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsxnew file mode 100644index 0000000000..ddad60ced6--- /dev/null+++ b/client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsx@@ -0,0 +1,69 @@+import { useForm, FormProvider } from 'react-hook-form';+import { fireEvent, render, screen } from '@testing-library/react';+import type { UseFormReturn } from 'react-hook-form';+import type { AgentForm } from '~/common';+import OrchestrationHub from '../OrchestrationHub';++let mockCapabilities = ['subagents'];+let mockGetValues: UseFormReturn<AgentForm>['getValues'];+jest.mock('~/hooks', () => ({ useLocalize: () => (key: string) => key }));+jest.mock('~/Providers', () => ({+ useAgentPanelContext: () => ({+ agentsConfig: {+ capabilities: mockCapabilities,+ maxSubagents: 3,+ fileSharing: { enabled: true },+ },+ }),+ useAgentsMapContext: () => ({}),+}));++function Harness({ tool }: { tool: 'subagents' | 'handoffs' }) {+ const methods = useForm<AgentForm>({+ defaultValues: {+ subagents: { enabled: true, allowSelf: false, agent_ids: [], shareFiles: true },+ edges: [{ from: 'parent', to: 'child' }],+ },+ });+ mockGetValues = methods.getValues;+ return (+ <FormProvider {...methods}>+ <OrchestrationHub tool={tool} currentAgentId="parent" />+ </FormProvider>+ );+}++beforeEach(() => {+ mockCapabilities = ['subagents'];+});++test('the subagent dialog exposes only subagent settings and preserves handoffs', () => {+ render(<Harness tool="subagents" />);+ expect(screen.getByRole('region', { name: 'com_ui_agent_subagents' })).toBeVisible();+ expect(screen.queryByRole('region', { name: 'com_ui_agent_handoffs' })).not.toBeInTheDocument();+ expect(screen.getByText('0 / 3')).toBeInTheDocument();+ expect(screen.getByRole('switch', { name: 'com_ui_agent_subagents_share_files' })).toBeChecked();+ const edges = mockGetValues('edges');+ fireEvent.click(screen.getByRole('switch', { name: 'com_ui_agent_subagents_enable' }));+ expect(mockGetValues('subagents.enabled')).toBe(false);+ expect(mockGetValues('edges')).toEqual(edges);+});++test('the handoff dialog exposes only destination settings and preserves subagents', () => {+ render(<Harness tool="handoffs" />);+ expect(screen.getByRole('region', { name: 'com_ui_agent_handoffs' })).toBeVisible();+ expect(screen.queryByRole('region', { name: 'com_ui_agent_subagents' })).not.toBeInTheDocument();+ const subagents = mockGetValues('subagents');+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_agent_handoff_remove' }));+ expect(mockGetValues('edges')).toEqual([]);+ expect(mockGetValues('subagents')).toEqual(subagents);+});++test('the capability gate suppresses subagents but not handoffs', () => {+ mockCapabilities = [];+ const { unmount } = render(<Harness tool="subagents" />);+ expect(screen.queryByRole('region')).not.toBeInTheDocument();+ unmount();+ render(<Harness tool="handoffs" />);+ expect(screen.getByRole('region', { name: 'com_ui_agent_handoffs' })).toBeVisible();+});diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsxindex 9eac7bc824..4582f07bab 100644--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx@@ -14,7 +14,8 @@ interface Props {export default function ItemDialog({ item, agentId, onClose }: Props) {const [portalElement, setPortalElement] = useState<HTMLDivElement | null>(null);- const isOrchestration = item?.kind === 'builtin' && item.id === 'orchestration';+ const isOrchestration =+ item?.kind === 'builtin' && (item.id === 'subagents' || item.id === 'handoffs');const isAction = item?.kind === 'action';return (<OGDialog open={item !== null} onOpenChange={(next) => !next && onClose()}>diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsxindex e0ee7c2af8..d8f3d63ee0 100644--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx@@ -143,8 +143,8 @@ export default function BuiltinSection({let body: React.ReactNode = null;- if (builtinId === 'orchestration') {- body = <OrchestrationHub currentAgentId={agentId} />;+ if (builtinId === 'subagents' || builtinId === 'handoffs') {+ body = <OrchestrationHub currentAgentId={agentId} tool={builtinId} />;} else if (builtinId === 'execute_code') {body = (<div className="flex flex-col gap-4">@@ -176,7 +176,9 @@ export default function BuiltinSection({}const localizedDescription =- description && builtinId !== 'orchestration' ? localize(description as TranslationKeys) : '';+ description && builtinId !== 'subagents' && builtinId !== 'handoffs'+ ? localize(description as TranslationKeys)+ : '';return (<div className="flex flex-col gap-5">diff --git a/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx b/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsxindex 83b79998eb..b4d89e9043 100644--- a/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx@@ -23,9 +23,9 @@ import {} from './items/selectors';import { useAgentFileEntries, useAgentItems, useUninstallToolCredentials } from './hooks';import MarketplaceSidebar, { MarketplaceFilterBar } from './MarketplaceSidebar';+import { setSubagentsEnabled, removeHandoffs } from './items/orchestration';import { requiresFileManagerRemoval } from './items/capabilities';import AddMcpServerDialog from './ItemDialog/AddMcpServerDialog';-import { removeOrchestration } from './items/orchestration';import { computeToggleAction } from './items/mutations';import { useLocalize, useToolFavorites } from '~/hooks';import MarketplaceCatalog from './MarketplaceCatalog';@@ -131,14 +131,14 @@ export default function ToolsMarketplaceDialog({case 'configure':setDetailItem(item);break;- case 'orchestration-remove': {- const next = removeOrchestration(getValues('subagents'), getValues('edges'));- if (next.subagents) {- setValue('subagents', next.subagents, { shouldDirty: true });- }- setValue('edges', next.edges, { shouldDirty: true });+ case 'subagents':+ setValue('subagents', setSubagentsEnabled(getValues('subagents'), patch.enabled), {+ shouldDirty: true,+ });+ break;+ case 'handoffs-remove':+ setValue('edges', removeHandoffs(getValues('edges')), { shouldDirty: true });break;- }case 'builtin':setValue(patch.field as keyof AgentForm, patch.value as never, { shouldDirty: true });if (patch.field === AgentCapabilities.execute_code && patch.value === false) {diff --git a/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx b/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsxindex 1885ae0548..2d3c2cc44e 100644--- a/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx@@ -21,10 +21,10 @@ import {useUninstallToolCredentials,} from './hooks';import { useSkillsInfiniteQuery, useDeleteAgentAction } from '~/data-provider';+import { setSubagentsEnabled, removeHandoffs } from './items/orchestration';import { requiresFileManagerRemoval } from './items/capabilities';import { useRemoveMCPTool, useVisibleTools } from '~/hooks/MCP';import ToolsMarketplaceDialog from './ToolsMarketplaceDialog';-import { removeOrchestration } from './items/orchestration';import { computeToggleAction } from './items/mutations';import { useLocalize, useHasAccess } from '~/hooks';import { useAgentPanelContext } from '~/Providers';@@ -128,14 +128,14 @@ export default function ToolsSection({ agentId }: Props) {case 'configure':setDialogItem(item);break;- case 'orchestration-remove': {- const next = removeOrchestration(getValues('subagents'), getValues('edges'));- if (next.subagents) {- setValue('subagents', next.subagents, { shouldDirty: true });- }- setValue('edges', next.edges, { shouldDirty: true });+ case 'subagents':+ setValue('subagents', setSubagentsEnabled(getValues('subagents'), patch.enabled), {+ shouldDirty: true,+ });+ break;+ case 'handoffs-remove':+ setValue('edges', removeHandoffs(getValues('edges')), { shouldDirty: true });break;- }case 'builtin':setValue(patch.field as keyof AgentForm, patch.value as never, { shouldDirty: true });if (patch.field === AgentCapabilities.execute_code && patch.value === false) {diff --git a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsxindex 0ddb103916..bc6aa93af1 100644--- a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx+++ b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx@@ -9,6 +9,8 @@ let mockWatchedTools: string[] = [];let mockExecuteCode = false;let mockMcpServersMap = new Map<string, object>();let mockIsDesktop = true;+let mockSubagents = { enabled: false, allowSelf: false, agent_ids: ['reviewer'] };+let mockEdges: Array<{ from: string; to: string; edgeType?: 'handoff' | 'direct' }> = [];jest.mock('react-hook-form', () => ({useFormContext: () => ({@@ -18,6 +20,8 @@ jest.mock('react-hook-form', () => ({}),useWatch: ({ name }: { name: string }) => {const map: Record<string, unknown> = {+ subagents: mockSubagents,+ edges: mockEdges,tools: mockWatchedTools,skills: [],execute_code: mockExecuteCode,@@ -34,7 +38,7 @@ jest.mock('react-hook-form', () => ({jest.mock('~/Providers', () => ({useAgentPanelContext: () => ({- agentsConfig: { capabilities: ['execute_code', 'tools'] },+ agentsConfig: { capabilities: ['execute_code', 'tools', 'subagents'] },regularTools: [{ pluginKey: 'dalle', name: 'DALL-E', description: 'Images' }],mcpServersMap: mockMcpServersMap,actions: [],@@ -102,6 +106,8 @@ jest.mock('../hooks', () => {});const selected = deriveSelectedItems({+ subagents: useWatch({ name: 'subagents' }),+ edges: useWatch({ name: 'edges' }),execute_code: (useWatch({ name: 'execute_code' }) ?? false) as boolean,web_search: (useWatch({ name: 'web_search' }) ?? false) as boolean,file_search: (useWatch({ name: 'file_search' }) ?? false) as boolean,@@ -173,6 +179,8 @@ describe('ToolsMarketplaceDialog', () => {mockToggleFavorite.mockClear();mockFavoriteKeys = new Set<string>();mockIsDesktop = true;+ mockSubagents = { enabled: false, allowSelf: false, agent_ids: ['reviewer'] };+ mockEdges = [];mockFileEntries = { contextFiles: [], knowledgeFiles: [], codeFiles: [] };});@@ -410,3 +418,54 @@ describe('ToolsMarketplaceDialog', () => {expect(screen.getByText('com_ui_tools_view_favorites_empty')).toBeInTheDocument();});});++describe('native collaboration tools', () => {+ beforeEach(() => {+ mockSetValue.mockClear();+ mockGetValues.mockReset();+ mockGetValues.mockReturnValue([]);+ mockSubagents = { enabled: false, allowSelf: false, agent_ids: ['reviewer'] };+ mockEdges = [];+ });++ test.each(['subagents', 'handoffs'] as const)(+ 'the marketplace removes %s independently',+ (id) => {+ mockSubagents = { enabled: true, allowSelf: false, agent_ids: ['reviewer'] };+ mockEdges = [+ { from: 'parent', to: 'reviewer' },+ { from: 'parent', to: 'other', edgeType: 'direct' },+ ];+ mockGetValues.mockImplementation((name: string) =>+ name === 'subagents' ? mockSubagents : mockEdges,+ );+ render(<ToolsMarketplaceDialog open onOpenChange={jest.fn()} agentId="a1" />);+ fireEvent.click(+ screen.getByRole('button', {+ name: new RegExp(id === 'subagents' ? 'com_ui_agent_subagents' : 'com_ui_agent_handoffs'),+ }),+ );+ expect(mockSetValue.mock.calls).toEqual(+ id === 'subagents'+ ? [['subagents', { ...mockSubagents, enabled: false }, { shouldDirty: true }]]+ : [['edges', [mockEdges[1]], { shouldDirty: true }]],+ );+ },+ );++ test('adding subagents enables the retained configuration without touching handoffs', () => {+ mockGetValues.mockImplementation(() => mockSubagents);+ render(<ToolsMarketplaceDialog open onOpenChange={jest.fn()} agentId="a1" />);+ fireEvent.click(screen.getByRole('button', { name: /com_ui_agent_subagents/ }));+ expect(mockSetValue.mock.calls).toEqual([+ ['subagents', { ...mockSubagents, enabled: true }, { shouldDirty: true }],+ ]);+ });++ test('adding handoffs opens only their destination dialog without mutating the form', () => {+ render(<ToolsMarketplaceDialog open onOpenChange={jest.fn()} agentId="a1" />);+ fireEvent.click(screen.getByRole('button', { name: /com_ui_agent_handoffs/ }));+ expect(screen.getByTestId('item-dialog')).toBeInTheDocument();+ expect(mockSetValue).not.toHaveBeenCalled();+ });+});diff --git a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsxindex cf7a6bef04..d4226ad31e 100644--- a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx+++ b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx@@ -304,3 +304,26 @@ describe('ToolsSection', () => {);});});++test.each(['subagents', 'handoffs'] as const)(+ 'removing %s only writes that tool’s fields',+ (id) => {+ mockSelected = [{ kind: 'builtin', id, name: '', description: '', iconKey: id }];+ const subagents = {+ enabled: true,+ allowSelf: false,+ shareFiles: true,+ agent_ids: ['reviewer'],+ };+ const handoff = { from: 'parent', to: 'reviewer' };+ const direct = { from: 'parent', to: ['left', 'right'] };+ mockFormValues = { subagents, edges: [handoff, direct] };+ render(<ToolsSection agentId="a" />);+ fireEvent.click(screen.getByRole('button', { name: `remove-${id}` }));+ expect(mockSetValue.mock.calls).toEqual(+ id === 'subagents'+ ? [['subagents', { ...subagents, enabled: false }, { shouldDirty: true }]]+ : [['edges', [direct], { shouldDirty: true }]],+ );+ },+);diff --git a/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts b/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.tsindex b3d57ff719..a131a52241 100644--- a/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts@@ -23,8 +23,8 @@ const askInputs: BuildCatalogInputs = {};describe('buildCatalog', () => {- test('offers orchestration for always-available handoffs without the subagents capability', () => {- expect(buildCatalog(emptyInputs).map((item) => item.id)).toEqual(['orchestration']);+ test('offers handoffs without the subagents capability', () => {+ expect(buildCatalog(emptyInputs).map((item) => item.id)).toEqual(['handoffs']);});test('emits built-in items only for capabilities the admin enabled', () => {@@ -35,18 +35,19 @@ describe('buildCatalog', () => {},});expect(items.filter((i) => i.kind === 'builtin').map((i) => i.id)).toEqual([- 'orchestration',+ 'handoffs',AgentCapabilities.execute_code,AgentCapabilities.web_search,]);});- test('offers exactly one orchestration item when subagents are enabled', () => {+ test('offers two separate native tools when subagents are enabled', () => {const items = buildCatalog({...emptyInputs,agentsConfig: { capabilities: [AgentCapabilities.subagents] },});- expect(items.map((item) => item.id)).toEqual(['orchestration']);+ expect(items.map((item) => item.id)).toEqual(['subagents', 'handoffs']);+ expect(items.map((item) => item.kind)).toEqual(['builtin', 'builtin']);});test('emits the memory builtin only when showMemory is set', () => {diff --git a/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts b/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.tsindex ff83f2a477..26dfbb1fc3 100644--- a/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts@@ -1,18 +1,26 @@import type { AgentSubagentsConfig, GraphEdge } from 'librechat-data-provider';import type { FormSelection } from '../selectors';import type { AgentItem } from '../types';-import { isHandoffEdge, removeOrchestration } from '../orchestration';+import { isHandoffEdge, setSubagentsEnabled, removeHandoffs } from '../orchestration';import { hasConfigurableSettings } from '../configurable';import { deriveSelectedItems } from '../selectors';import { computeToggleAction } from '../mutations';-const item: AgentItem = {+const subagentItem: AgentItem = {kind: 'builtin',- id: 'orchestration',+ id: 'subagents',name: '',description: '',- iconKey: 'orchestration',+ iconKey: 'subagents',};+const handoffItem: AgentItem = {+ kind: 'builtin',+ id: 'handoffs',+ name: '',+ description: '',+ iconKey: 'handoffs',+};+const catalog = [subagentItem, handoffItem];const form: FormSelection = {execute_code: false,web_search: false,@@ -33,28 +41,40 @@ const handoff: GraphEdge = {};const direct: GraphEdge = { from: 'parent', to: 'other', edgeType: 'direct' };-test('derives the native item from existing subagent and handoff configurations', () => {- expect(deriveSelectedItems(form, [item], [])).toEqual([]);- expect(deriveSelectedItems({ ...form, subagents: { enabled: true } }, [item], [])).toEqual([- item,+test('derives each native tool independently from stored configuration', () => {+ expect(deriveSelectedItems(form, catalog, [])).toEqual([]);+ expect(deriveSelectedItems({ ...form, subagents: { enabled: true } }, catalog, [])).toEqual([+ subagentItem,]);- expect(deriveSelectedItems({ ...form, edges: [handoff] }, [item], [])).toEqual([item]);+ expect(deriveSelectedItems({ ...form, edges: [handoff] }, catalog, [])).toEqual([handoffItem]);+ expect(+ deriveSelectedItems({ ...form, subagents: { enabled: true }, edges: [handoff] }, catalog, []),+ ).toEqual(catalog);expect(deriveSelectedItems({ ...form, edges: [direct], subagents: { enabled: false, agent_ids: ['child'] } },- [item],+ catalog,[],),).toEqual([]);});-test('adding opens settings instead of writing a bogus capability or plugin', () => {- expect(computeToggleAction(item, { selected: false })).toEqual({ type: 'configure' });- expect(computeToggleAction(item, { selected: true })).toEqual({ type: 'orchestration-remove' });- expect(hasConfigurableSettings(item)).toBe(true);+test('toggles subagents and opens destination settings to add handoffs', () => {+ expect(computeToggleAction(subagentItem, { selected: false })).toEqual({+ type: 'subagents',+ enabled: true,+ });+ expect(computeToggleAction(subagentItem, { selected: true })).toEqual({+ type: 'subagents',+ enabled: false,+ });+ expect(computeToggleAction(handoffItem, { selected: false })).toEqual({ type: 'configure' });+ expect(computeToggleAction(handoffItem, { selected: true })).toEqual({ type: 'handoffs-remove' });+ expect(hasConfigurableSettings(subagentItem)).toBe(true);+ expect(hasConfigurableSettings(handoffItem)).toBe(true);});-test('removal explicitly disables subagents and preserves their settings and unrelated edges', () => {+test('subagent toggles preserve their complete settings and restore the retained roster', () => {const subagents: AgentSubagentsConfig = {enabled: true,allowSelf: false,@@ -72,12 +92,15 @@ test('removal explicitly disables subagents and preserves their settings and unr},],};- expect(removeOrchestration(subagents, [handoff, direct])).toEqual({- subagents: { ...subagents, enabled: false },- edges: [direct],- });+ const disabled = setSubagentsEnabled(subagents, false);+ expect(disabled).toEqual({ ...subagents, enabled: false });expect(subagents.enabled).toBe(true);- expect(removeOrchestration(undefined, [handoff])).toEqual({ subagents: undefined, edges: [] });+ expect(setSubagentsEnabled(disabled, true)).toEqual(subagents);+ expect(setSubagentsEnabled(undefined, true)).toEqual({+ enabled: true,+ allowSelf: true,+ agent_ids: [],+ });});test.each<[GraphEdge, boolean]>([@@ -90,8 +113,16 @@ test.each<[GraphEdge, boolean]>([[{ from: 'parent', to: 'child', edgeType: 'direct' }, false],])('matches runtime classification for %j', (edge, expected) => {expect(isHandoffEdge(edge)).toBe(expected);- expect(deriveSelectedItems({ ...form, edges: [edge] }, [item], [])).toEqual(- expected ? [item] : [],+ expect(deriveSelectedItems({ ...form, edges: [edge] }, [handoffItem], [])).toEqual(+ expected ? [handoffItem] : [],);- expect(removeOrchestration(undefined, [edge]).edges).toEqual(expected ? [] : [edge]);+ expect(removeHandoffs([edge])).toEqual(expected ? [] : [edge]);+});++test('handoff removal retains all direct edges and does not mutate stored input', () => {+ const implicitDirect: GraphEdge = { from: 'parent', to: ['left', 'right'] };+ const edges = [handoff, direct, implicitDirect];+ expect(removeHandoffs(edges)).toEqual([direct, implicitDirect]);+ expect(edges).toHaveLength(3);+ expect(removeHandoffs()).toEqual([]);});diff --git a/client/src/components/SidePanel/Agents/Tools/items/catalog.ts b/client/src/components/SidePanel/Agents/Tools/items/catalog.tsindex e7b5c633ac..0b2b62e593 100644--- a/client/src/components/SidePanel/Agents/Tools/items/catalog.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/catalog.ts@@ -122,14 +122,23 @@ export function buildCatalog(inputs: BuildCatalogInputs): AgentItem[] {const items: AgentItem[] = [{kind: 'builtin',- id: 'orchestration',- iconKey: 'orchestration',- name: 'com_ui_agent_orchestration',- description: 'com_ui_agent_orchestration_hint',+ id: 'handoffs',+ iconKey: 'handoffs',+ name: 'com_ui_agent_handoffs',+ description: 'com_ui_agent_handoffs_subtitle',},];const enabled = new Set(inputs.agentsConfig.capabilities);+ if (enabled.has(AgentCapabilities.subagents)) {+ items.unshift({+ kind: 'builtin',+ id: AgentCapabilities.subagents,+ iconKey: 'subagents',+ name: 'com_ui_agent_subagents',+ description: 'com_ui_agent_subagents_subtitle',+ });+ }for (const def of BUILTIN_DEFINITIONS) {if (!enabled.has(def.id)) {continue;diff --git a/client/src/components/SidePanel/Agents/Tools/items/configurable.ts b/client/src/components/SidePanel/Agents/Tools/items/configurable.tsindex b3e4f6a7a6..7e4662bc86 100644--- a/client/src/components/SidePanel/Agents/Tools/items/configurable.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/configurable.ts@@ -16,7 +16,8 @@ export function hasConfigurableSettings(item: AgentItem): boolean {item.id === 'file_search' ||item.id === 'context' ||item.id === 'memory' ||- item.id === 'orchestration' ||+ item.id === 'subagents' ||+ item.id === 'handoffs' ||(item.id === 'web_search' && item.userProvidedAuth === true));case 'tool':diff --git a/client/src/components/SidePanel/Agents/Tools/items/icons.ts b/client/src/components/SidePanel/Agents/Tools/items/icons.tsindex 1e75d7049e..3ddd5461c5 100644--- a/client/src/components/SidePanel/Agents/Tools/items/icons.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/icons.ts@@ -12,6 +12,7 @@ import {Zap,Layers,Network,+ Waypoints,} from 'lucide-react';import type { LucideIcon } from 'lucide-react';import type { AgentItem } from './types';@@ -23,10 +24,14 @@ export interface ItemIcon {}const BUILTIN_ICONS: Record<string, ItemIcon> = {- orchestration: {+ subagents: {Icon: Network,colorClass: 'bg-series-2/15 text-series-2',},+ handoffs: {+ Icon: Waypoints,+ colorClass: 'bg-series-4/15 text-series-4',+ },execute_code: {Icon: Code,colorClass: 'bg-series-7/15 text-series-7',diff --git a/client/src/components/SidePanel/Agents/Tools/items/mutations.ts b/client/src/components/SidePanel/Agents/Tools/items/mutations.tsindex e79206f84d..f7debe7dc4 100644--- a/client/src/components/SidePanel/Agents/Tools/items/mutations.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/mutations.ts@@ -3,7 +3,8 @@ import type { AgentItem } from './types';export type TogglePatch =| { type: 'builtin'; field: AgentCapabilities; value: boolean | string }- | { type: 'orchestration-remove' }+ | { type: 'subagents'; enabled: boolean }+ | { type: 'handoffs-remove' }| { type: 'configure' }| { type: 'tool-add'; id: string }| { type: 'tool-remove'; id: string }@@ -15,8 +16,11 @@ export type TogglePatch =| { type: 'action-remove'; actionId: string };function builtinTogglePatch(id: string, selected: boolean): TogglePatch {- if (id === 'orchestration') {- return selected ? { type: 'orchestration-remove' } : { type: 'configure' };+ if (id === 'subagents') {+ return { type: 'subagents', enabled: !selected };+ }+ if (id === 'handoffs') {+ return selected ? { type: 'handoffs-remove' } : { type: 'configure' };}if (id === 'ask_user_question') {// Native tool presented as a builtin — it has no capability field; thediff --git a/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts b/client/src/components/SidePanel/Agents/Tools/items/orchestration.tsindex 232d176be9..1849ab27b7 100644--- a/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts@@ -9,10 +9,20 @@ export function isHandoffEdge(edge: GraphEdge): boolean {return edge.edgeType !== 'direct' && !defaultDirect;}-/** Disable orchestration without losing subagent settings or non-handoff edges. */-export function removeOrchestration(subagents?: AgentSubagentsConfig, edges?: GraphEdge[]) {+/** Persist the explicit flag while retaining the roster, graphs, and granular settings. */+export function setSubagentsEnabled(+ subagents: AgentSubagentsConfig | undefined,+ enabled: boolean,+): AgentSubagentsConfig {return {- subagents: subagents ? { ...subagents, enabled: false } : undefined,- edges: (edges ?? []).filter((edge) => !isHandoffEdge(edge)),+ ...subagents,+ enabled,+ allowSelf: subagents?.allowSelf ?? true,+ agent_ids: subagents?.agent_ids ?? [],};}++/** Removing handoffs must leave unrelated direct edges intact. */+export function removeHandoffs(edges?: GraphEdge[]): GraphEdge[] {+ return (edges ?? []).filter((edge) => !isHandoffEdge(edge));+}diff --git a/client/src/components/SidePanel/Agents/Tools/items/selectors.ts b/client/src/components/SidePanel/Agents/Tools/items/selectors.tsindex d1186e095f..2735f490c9 100644--- a/client/src/components/SidePanel/Agents/Tools/items/selectors.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/selectors.ts@@ -53,8 +53,10 @@ function isBuiltinSelected(item: AgentItem, form: FormSelection): boolean {return Boolean(form.artifacts);case 'context':return form.context_files.length > 0;- case 'orchestration':- return form.subagents?.enabled === true || form.edges?.some(isHandoffEdge) === true;+ case 'subagents':+ return form.subagents?.enabled === true;+ case 'handoffs':+ return form.edges?.some(isHandoffEdge) === true;case 'ask_user_question':// Native tool presented as a builtin — selection lives in agent.tools.return form.tools.includes('ask_user_question');diff --git a/client/src/components/SidePanel/Agents/Tools/items/types.ts b/client/src/components/SidePanel/Agents/Tools/items/types.tsindex 7478c15064..43e0f1872c 100644--- a/client/src/components/SidePanel/Agents/Tools/items/types.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/types.ts@@ -22,7 +22,8 @@ export type BuiltinId =* in `selectors.ts` / `mutations.ts`.*/| 'ask_user_question'- | 'orchestration';+ | `${AgentCapabilities.subagents}`+ | 'handoffs';export type AgentItemStatus = 'needs_setup';diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex b2e873d112..43ab38d6e6 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -1115,8 +1115,6 @@"com_ui_agent_id_copy": "Copy agent ID","com_ui_agent_name": "Agent name","com_ui_agent_name_is_required": "Agent name is required",- "com_ui_agent_orchestration": "Multi-agent orchestration",- "com_ui_agent_orchestration_hint": "Choose how this agent works with other agents.","com_ui_agent_recursion_limit": "Max Agent Steps","com_ui_agent_recursion_limit_info": "Limits how many steps the agent can take in a run before giving a final response. Default is 25 steps. A step is either an AI API request or a tool usage round. For example, a basic tool interaction takes 3 steps: initial request, tool usage, and follow-up request.","com_ui_agent_subagents": "Subagents",diff --git a/e2e/specs/mock/agent-collaboration-tools.spec.ts b/e2e/specs/mock/agent-collaboration-tools.spec.tsnew file mode 100644index 0000000000..5b81d4bd84--- /dev/null+++ b/e2e/specs/mock/agent-collaboration-tools.spec.ts@@ -0,0 +1,122 @@+import { expect, test } from '@playwright/test';+import type { Locator, Page } from '@playwright/test';+import type { AgentDetail } from './agents.helpers';+import { cleanupAgent, openAgentBuilder, uniqueAgentName } from './agents.helpers';+import { MOCK_ENDPOINTS, fetchJson, getAccessToken, requestJson } from './helpers';++const toolRow = (form: Locator, name: string) =>+ form.getByRole('listitem').filter({ has: form.page().getByText(name, { exact: true }) });++async function saveAgent(page: Page, form: Locator, agentId: string) {+ const [response] = await Promise.all([+ page.waitForResponse(+ (candidate) =>+ candidate.request().method() === 'PATCH' &&+ new URL(candidate.url()).pathname === `/api/agents/${agentId}` &&+ candidate.ok(),+ ),+ form.getByRole('button', { name: 'Save', exact: true }).click(),+ ]);+ expect(response.ok()).toBeTruthy();+}++test('subagents and handoffs have separate native tools, settings, and persistence', async ({+ page,+}) => {+ test.setTimeout(90000);+ await page.goto('/c/new');+ const token = await getAccessToken(page);+ const child = await requestJson<AgentDetail>(page, {+ path: '/api/agents',+ token,+ method: 'POST',+ body: {+ name: uniqueAgentName('E2E Native Reviewer'),+ provider: MOCK_ENDPOINTS[0].label,+ model: MOCK_ENDPOINTS[0].model,+ },+ });+ let parent: AgentDetail | undefined;+ try {+ parent = await requestJson<AgentDetail>(page, {+ path: '/api/agents',+ token,+ method: 'POST',+ body: {+ name: uniqueAgentName('E2E Native Collaboration'),+ provider: MOCK_ENDPOINTS[0].label,+ model: MOCK_ENDPOINTS[0].model,+ subagents: { enabled: true, allowSelf: false, agent_ids: [child.id] },+ edges: [+ { from: '', to: child.id },+ { from: '', to: child.id, edgeType: 'direct' },+ ],+ },+ });+ const form = await openAgentBuilder(page);+ await form.getByRole('combobox', { name: 'Agent', exact: true }).click();+ await page.getByRole('option', { name: parent.name, exact: true }).click();+ await expect(form.getByLabel('Agent name')).toHaveValue(parent.name ?? '');+ const subagents = toolRow(form, 'Subagents');+ const handoffs = toolRow(form, 'Handoffs');+ await expect(subagents).toBeVisible();+ await expect(handoffs).toBeVisible();+ await expect(form.getByText('Multi-agent orchestration', { exact: true })).toHaveCount(0);++ await subagents.getByRole('button', { name: 'Configure', exact: true }).click();+ const dialog = page.getByTestId('item-dialog');+ await expect(dialog.getByRole('region', { name: 'Subagents', exact: true })).toBeVisible();+ await expect(dialog.getByRole('region', { name: 'Handoffs', exact: true })).toHaveCount(0);+ await expect(+ dialog.getByRole('switch', { name: 'Allow self-spawn', exact: true }),+ ).not.toBeChecked();+ await dialog.getByRole('button', { name: 'Close', exact: true }).click();+ await expect(dialog).toBeHidden();++ await handoffs.getByRole('button', { name: 'Configure', exact: true }).click();+ await expect(dialog.getByRole('region', { name: 'Handoffs', exact: true })).toBeVisible();+ await expect(dialog.getByRole('region', { name: 'Subagents', exact: true })).toHaveCount(0);+ await dialog.getByRole('combobox', { name: 'Select agent', exact: true }).click();+ const search = page.locator('input[placeholder="Search agent"]:visible');+ await search.fill(child.name ?? '');+ await expect(search).toBeFocused();+ await expect(page.getByRole('option', { name: child.name, exact: true })).toBeVisible();+ await page.keyboard.press('Escape');+ await dialog.getByRole('button', { name: 'Close', exact: true }).click();+ await expect(dialog).toBeHidden();++ await subagents.getByRole('button', { name: 'Remove from agent', exact: true }).click();+ await expect(subagents).toHaveCount(0);+ await expect(handoffs).toBeVisible();+ await saveAgent(page, form, parent.id);+ let saved = await fetchJson<AgentDetail>(page, `/api/agents/${parent.id}/expanded`, token);+ expect(saved.subagents).toEqual({ enabled: false, allowSelf: false, agent_ids: [child.id] });+ expect(saved.edges).toEqual(parent.edges);++ await form.getByRole('button', { name: 'Add tools', exact: true }).click();+ const library = page.getByRole('dialog', { name: 'Tool Library', exact: true });+ await library+ .getByRole('button', { name: /^Subagents/ })+ .first()+ .click();+ await library.getByRole('button', { name: 'Close', exact: true }).click();+ await expect(subagents).toBeVisible();+ await handoffs.getByRole('button', { name: 'Remove from agent', exact: true }).click();+ await expect(handoffs).toHaveCount(0);+ await expect(subagents).toBeVisible();+ await saveAgent(page, form, parent.id);+ saved = await fetchJson<AgentDetail>(page, `/api/agents/${parent.id}/expanded`, token);+ expect(saved.subagents).toEqual({ enabled: true, allowSelf: false, agent_ids: [child.id] });+ expect(saved.edges).toEqual(parent.edges?.filter((edge) => edge.edgeType === 'direct'));+ await page.reload();+ const reopened = await openAgentBuilder(page, { navigate: false });+ await reopened.getByRole('combobox', { name: 'Agent', exact: true }).click();+ await page.getByRole('option', { name: parent.name, exact: true }).click();+ await expect(reopened.getByLabel('Agent name')).toHaveValue(parent.name ?? '');+ await expect(toolRow(reopened, 'Subagents')).toBeVisible();+ await expect(toolRow(reopened, 'Handoffs')).toHaveCount(0);+ } finally {+ await cleanupAgent(page, parent?.id);+ await cleanupAgent(page, child.id);+ }+});diff --git a/e2e/specs/mock/agent-handoffs.spec.ts b/e2e/specs/mock/agent-handoffs.spec.tsindex a0e1b427f7..a450c25e3b 100644--- a/e2e/specs/mock/agent-handoffs.spec.ts+++ b/e2e/specs/mock/agent-handoffs.spec.ts@@ -68,7 +68,7 @@ async function waitForMCPTool(page: Page, token: string): Promise<void> {async function openOrchestration(page: Page, form: Locator) {const settings = form.getByRole('listitem')- .filter({ hasText: 'Multi-agent orchestration' })+ .filter({ hasText: 'Handoffs' }).getByRole('button', { name: 'Configure', exact: true });if (await settings.count()) {await settings.click();@@ -77,7 +77,7 @@ async function openOrchestration(page: Page, form: Locator) {await page.getByRole('dialog', { name: 'Tool Library', exact: true }).getByRole('listitem')- .filter({ hasText: 'Multi-agent orchestration' })+ .filter({ hasText: 'Handoffs' }).getByRole('button', { name: 'Configure', exact: true }).click();}