From 6eadbf053775433c0f17f40d1375720c70fd6b77 Mon Sep 17 00:00:00 2001
From: yiliang114 <1204183885@qq.com>
Date: Tue, 18 Aug 2026 20:57:45 +0000
Subject: [PATCH] docs(tools): clarify list_agents excludes Agent Team
 teammates

The empty list_agents result ("No background agents are available in
this session") is true for the ordinary background-subagent roster but
reads as team status while named Agent Team teammates are active, which
can trigger duplicate launches or a false "no workers running"
conclusion.

Make the control-plane boundary explicit:
- tool description states that named teammates are NOT listed, deliver
  their final reports automatically, and that list_agents/task_list
  polling must not be used to wait for them;
- empty result names the roster it reports on and the teammate
  exclusion.

The registries stay separate; this is a tool-contract wording fix only.

Fixes #9431
---
 packages/core/src/tools/list-agents.test.ts | 17 ++++++++++++++++-
 packages/core/src/tools/list-agents.ts      | 18 +++++++++++++-----
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/packages/core/src/tools/list-agents.test.ts b/packages/core/src/tools/list-agents.test.ts
index 7ca39d0e21c..ed42c4bf5f2 100644
--- a/packages/core/src/tools/list-agents.test.ts
+++ b/packages/core/src/tools/list-agents.test.ts
@@ -28,7 +28,22 @@ describe('ListAgentsTool', () => {
 
     expect(tool.name).toBe('list_agents');
     expect(result.llmContent).toBe(
-      'No background agents are available in this session.',
+      'No ordinary background subagents are available in this session. ' +
+        'Named Agent Team teammates are not listed here; their results are ' +
+        'delivered automatically through team messaging, so do not use ' +
+        'list_agents to wait for a teammate.',
+    );
+  });
+
+  it('states the Agent Team boundary in the tool description', () => {
+    expect(tool.description).toContain(
+      'Named Agent Team teammates are NOT listed here',
+    );
+    expect(tool.description).toContain(
+      'deliver their final reports automatically',
+    );
+    expect(tool.description).toContain(
+      'do not use list_agents (or poll task_list) to wait for a teammate',
     );
   });
 
diff --git a/packages/core/src/tools/list-agents.ts b/packages/core/src/tools/list-agents.ts
index 0613a2a456d..0154abbfddb 100644
--- a/packages/core/src/tools/list-agents.ts
+++ b/packages/core/src/tools/list-agents.ts
@@ -28,7 +28,7 @@ class ListAgentsInvocation extends BaseToolInvocation<
   }
 
   getDescription(): string {
-    return 'List background agents';
+    return 'List ordinary background subagents';
   }
 
   async execute(): Promise<ToolResult> {
@@ -52,7 +52,11 @@ class ListAgentsInvocation extends BaseToolInvocation<
       }));
 
     if (agents.length === 0) {
-      const message = 'No background agents are available in this session.';
+      const message =
+        'No ordinary background subagents are available in this session. ' +
+        'Named Agent Team teammates are not listed here; their results are ' +
+        'delivered automatically through team messaging, so do not use ' +
+        'list_agents to wait for a teammate.';
       return { llmContent: message, returnDisplay: message };
     }
 
@@ -75,9 +79,13 @@ export class ListAgentsTool extends BaseDeclarativeTool<
     super(
       ListAgentsTool.Name,
       ToolDisplayNames.LIST_AGENTS,
-      'List addressable background agents in the current session, including ' +
-        'agents restored from a prior session run. Use the returned task_id ' +
-        'with send_message to continue a running, paused, or completed agent.',
+      'List addressable ordinary background subagents in the current ' +
+        'session, including agents restored from a prior session run. Named ' +
+        'Agent Team teammates are NOT listed here: they have their own team ' +
+        'lifecycle and deliver their final reports automatically, so do not ' +
+        'use list_agents (or poll task_list) to wait for a teammate. Use the ' +
+        'returned task_id with send_message to continue a running, paused, ' +
+        'or completed agent.',
       Kind.Read,
       {
         type: 'object',