[bug] Agent Teams 与直接委派共存：list_agents 同名冲突、wait_agent 语义错位（附可复现证据与补丁）

[zhouyunsheng31]

[bug] 启用 Agent Teams 后直接委派没有被禁用（web preset 逃过 patch）→ list_agents 同名冲突 + wait_agent 语义错位

摘要（TL;DR）

@deepseek-ai/dsh-experimental-agent-team-profile 的文档承诺：

Ordinary subagent delegation and overlapping global child controls are disabled.
The subagent and subagent_fork tools and overlapping global child controls are disabled.

但该层只按 id 禁用了根层的那几行；packages/bundle/web-app/presets/*.patch.yml 在各自的
嵌套 plugins: 列表里又声明了一遍同名 id 的行，那些是独立实例，patch 够不到。结果是
Agent Teams 与直接委派同时生效：

1. 同一个 agent 作用域里出现两个不同的 list_agents；
2. wait_agent（只观察 teammate）和 subagent（直接委派的后台子代理）并存，模型用
   wait_agent 等普通子智能体时永远拿到 noProgress: no-active-peer；
3. 客户端把这条结果渲染成「没有正在运行的子智能体」，把「没有团队成员」说成了
   「没有子智能体」，进一步误导。

环境

• dsh 0.2.0-rc.2（npm latest）；同一问题在 master（0.2.1-alpha.2）上依然存在
• profile：web，dsh.profile.bundles 含 @deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app、
  @deepseek-ai/dsh-experimental-agent-team-profile
• 顺带一提：profile 里若残留 @deepseek-ai/dsh-experimental-agent-team-web-profile，
  启动时会报 cannot resolve profile bundle（该包已不存在，README 要求移除该条目）

复现

1. 启用 Agent Teams（Plugins 页开启该 bundle）
2. 让 Lead 用 subagent 创建普通子智能体（或先 spawn_teammate 再改用 subagent）
3. 调 wait_agent → 无论 timeout 多长，立即返回：

{"timedOut":false,"noProgress":{"reason":"no-active-peer",
 "message":"No other Team member is running or provisioning. wait_agent cannot make progress or wake inactive teammates. ..."}}

4. 调 list_agents → 返回的是 teammate 花名册，看不到任何普通子智能体：

[{"target":"lead","role":"lead","status":"running","model":"..."},
 {"target":"repo-architect","role":"teammate","status":"running","provider":"spawn",...}]

证据

1) 合成后的 profile：根层被禁用、preset 层没有

$ dsh --profile web --dump-config | grep -n -A3 'id: tool-subagent-list-agents'
555:- id: tool-subagent-list-agents          # ← 根层：teams 层生效
556-  name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
557-  disabled: true
1023:          - id: tool-subagent-list-agents  # ← 在 preset-standard 的 plugins 里
1024-            name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
1205:          - id: tool-subagent-list-agents  # ← preset-ptc
1469:          - id: tool-subagent-list-agents  # ← preset-cordis

2) 实际会话日志（~/.dsh/sessions/.../session.v4.jsonl.zstd）

[ 326] CALL subagent  {"description":"梳理仓库分层与依赖", ...}
[ 646]  RES subagent  started subagent 34c15194-c3a1-4475-96cb-2b5278e27750
[ 442] CALL wait_agent {"timeout_ms":20000}
[ 443]  RES wait_agent {"timedOut":false,"noProgress":{"reason":"no-active-peer","message":"No other Team member is running..."}}
...
[1114] CALL wait_agent {"timeout_ms":1000}
[1115]  RES wait_agent Error: timeoutMs must be an integer from 10000 through 3600000

同一会话里 subagent 调用 21 次（都成功返回 started subagent <id>）、wait_agent
调用 59 次（除开头 team 阶段外全部 no-active-peer），而子智能体的完成通知其实是通过
source.kind: 'subagent-settled' 推回来的（该会话共 24 条）。也就是说模型在空转。

3) 上游源码

• 承诺与禁用：packages/experimental/agent-team-profile/cordis.patch.yml:4-14、
  packages/experimental/agent-team-profile/README.md（"are disabled"）
• preset 里的同名副本：
  packages/bundle/web-app/presets/standard.patch.yml:91-110、
  ptc.patch.yml:91-110、cordis.patch.yml:90-109
• 两个同名工具：
  packages/experimental/tool-agent-team/src/index.ts:233（teams 花名册）
  vs packages/subagent/tool-subagent-control/src/list-agents.ts:87（子代理列表）
• wait_agent 只观察 teammate：
  packages/experimental/tool-agent-team/src/index.ts:40（NO_ACTIVE_PEER_MESSAGE）
• 误导文案：packages/client/ui-conversation/src/client/locales.ts:263(zh) / :641(en)

根因

agent-team-profile 层的 patch 以根索引的 id 定位并禁用行（Cordis patch 的
id 寻址不进入 preset 的嵌套 plugins: 列表）。web-app 的三个 preset 各自声明了
同一批 id 的新行，因此：

• 根层 tool-subagent* 被禁用 ✅（符合文档）
• preset 层 tool-subagent* 仍然激活 ❌（违反文档）

于是 tool-agent-team（根层）与 preset 的 tool-subagent-control/list-agents
在同一个 agent 作用域里争用 list_agents 这个名字，实际解析到 teams 版；
与此同时 subagent / subagent_fork 也仍然可用。

建议修复

A（推荐，恢复文档承诺）：preset 行跟随 teams bundle

在三个 preset 的直接委派行上加同一个条件（!!js + ctx.get，与
presets/cordis.patch.yml:145 现有写法一致）：

- id: tool-subagent
  name: '@deepseek-ai/dsh-tool-subagent'
  disabled: !!js "ctx.get('agentTeams') !== undefined"

覆盖 tool-subagent-control / tool-subagent-list-agents / tool-subagent /
tool-subagent-fork，各 3 个 preset、共 12 行。teams bundle 关掉时这些行自动恢复。
补丁：dsh-agent-team-preset-delegation.patch（见文末）。

B（若「两者共存」是有意设计）：消除同名冲突

把 teams 的花名册工具从 list_agents 改名（例如 list_teammates），并同步
POLICY 文本、文档、客户端引用与测试。这样 wait_agent 与 subagent 可以共存，
但需要维护者确认这是期望的产品形态——目前的文档说的是 A。

C（独立、无论 A/B 都建议修）：wait_agent 的 noProgress 文案

detail.wait.noProgress 说的是「没有正在运行的子智能体」，而这条结果来自只观察
team member 的 wait_agent。改成「没有正在运行的团队成员」/「No active teammates」。
补丁：dsh-agent-team-wait-label.patch。

范围说明：detail.wait.title（'子智能体状态'/'Subagent activity'）与
tool.title.waitAgent（'等待子智能体'）同样指向 teams 语义，但属于命名决策，
本补丁故意未改，留给维护者与工具 roadmap 一起定。

影响

• web profile 下「等待智能体」表现为永远失败，模型会在 wait_agent 上反复空转
  （实测 59 次），浪费轮次与 token；
• 模型可能误判「没有子智能体在跑」，从而重复派活或提前结束；
• 团队工作流与直接委派工作流互相干扰，与该 bundle 的设计意图相反。

附：补丁

• dsh-agent-team-preset-delegation.patch — 12 行 / 3 文件（建议 A）
• dsh-agent-team-wait-label.patch — 3 行 / 2 文件（建议 C）

两者都基于 master，可直接 git apply。注意： 提交者未执行仓库测试套件
（需要 monorepo pnpm install），仅做了 YAML 解析与 id/条件的存在性校验；
建议 A 最好补一条 preset 级装配断言（apps/cli/tests/web-agent-presets.e2e.ts
的 harness 看起来正合适）。

---

English (for the issue body)

Summary

@deepseek-ai/dsh-experimental-agent-team-profile documents that ordinary subagent
delegation is disabled while Agent Teams is active. Its patch disables the root
rows by id, but packages/bundle/web-app/presets/{standard,ptc,cordis}.patch.yml
each declare their own rows with the same ids inside their nested plugins:
lists, which the root-addressed patch never reaches.

Result with Agent Teams enabled:

1. two different tools named list_agents exist in one agent scope (Agent Teams'
   roster at tool-agent-team/src/index.ts:233 vs.
   tool-subagent-control/src/list-agents.ts:87);
2. wait_agent (teammates only) is offered next to subagent, whose background
   children it cannot observe, so it always answers
   noProgress: { reason: 'no-active-peer' };
3. the Web UI renders that as "no running subagents" — a claim about subagents,
   when the tool only ever checks team members
   (ui-conversation/src/client/locales.ts:263 / :641).

Repro

Enable Agent Teams, create a plain subagent with subagent, then call wait_agent:
it returns noProgress/no-active-peer immediately regardless of timeout_ms, while
list_agents returns the teammate roster. Observed in one session: 21 successful
subagent calls, 59 wait_agent calls (all no-active-peer outside the initial
team phase), 24 subagent-settled notices delivered.

Evidence commands are in the Chinese section above (dsh --profile web --dump-config).

Suggested fixes

• A (recommended): gate the preset rows on the Teams domain, restoring the
  documented contract — disabled: !!js "ctx.get('agentTeams') !== undefined" on
  tool-subagent-control / tool-subagent-list-agents / tool-subagent /
  tool-subagent-fork in all three presets (12 lines). Patch attached.
• B: if coexistence is intended, rename the Teams roster tool (e.g.
  list_teammates) and update its policy text, docs, client references and tests.
• C: rename the detail.wait.noProgress string to teammates (patch attached).

---

Links / 链接

CONTRIBUTING.md 说明暂不接受外部 PR，因此按仓库指引把问题与补丁发在 Discussions。

• Branch fix/agent-team-preset-delegation（建议 A，12 行 / 3 文件）
  https://github.com/zhouyunsheng31/deepseek-harness/tree/fix/agent-team-preset-delegation
• Branch fix/wait-agent-no-progress-label（建议 C，3 行 / 2 文件）
  https://github.com/zhouyunsheng31/deepseek-harness/tree/fix/wait-agent-no-progress-label
• Diff A: https://github.com/deepseek-ai/deepseek-harness/compare/master...zhouyunsheng31:deepseek-harness:fix/agent-team-preset-delegation?expand=1
• Diff C: https://github.com/deepseek-ai/deepseek-harness/compare/master...zhouyunsheng31:deepseek-harness:fix/wait-agent-no-progress-label?expand=1

两个补丁都基于 master，可直接 git apply。提交者未运行仓库测试套件（需 monorepo 全量
pnpm install），仅做了 YAML 解析与条件存在性校验。

[zhouyunsheng31]

补充：解耦方案（建议 B）已实现并推送

上面的建议 A 是"严格按文档把直接委派关掉"。但那样会砍掉一半能力——同一个名字被两个语义不同的工具占用，更好的做法是把名字解开，两边都留着。按这个思路做了实现：

分支：fix/decouple-agent-teams
https://github.com/zhouyunsheng31/deepseek-harness/tree/fix/decouple-agent-teams
Diff: https://github.com/deepseek-ai/deepseek-harness/compare/master...zhouyunsheng31:deepseek-harness:fix/decouple-agent-teams?expand=1

改了什么（12 文件 / +50 −47）

1. 团队花名册工具改名：list_agents → list_teammates（tool name、POLICY、send_message/interrupt_agent/task 的 target 描述、teammate 的 system-reminder），于是 list_agents 只剩 tool-subagent-control 那一个，语义唯一。
2. 把 wait_agent 的作用域写进工具描述与 noProgress 文案：它只观察 Agent Teams 成员；subagent 这类委派工具创建的不是成员、永远唤不醒它；下一步依赖子代理结果时应给委派工具传 run_in_background: false。
3. 客户端：新增 list_teammates 标题映射；tool.title.waitAgent、detail.wait.title、detail.wait.noProgress 原来都在说"子智能体"，改为"团队成员"（这正是它们的真实语义）。
4. 测试 / README / 生成物跟随改名。

需要维护者注意

• packages/core/tools/tests/gen-tool-catalog.spec.ts 与
  packages/extensions/cordis-client-runner/src/client/slot-catalog.ts 是生成物，
  我是按预期结果手改的，正式合入时应重跑生成器（gen-client-catalog 等）。
• 未运行仓库测试套件（需 monorepo 全量 pnpm install），仅做了引用一致性与 YAML/文本核对。
• 若维护者认为"共享 worker 能力可用"另有更合适的产品形态（例如让一个 list_agents
  同时列出 teammate 与 subagent 并带 kind 字段），这个分支也可以作为对照实现。

三个方案的关系

方案	分支	取舍
A 禁用直接委派	fix/agent-team-preset-delegation	忠实文档，但少一半能力
B 解耦（本分支）	fix/decouple-agent-teams	两边都可用，代价是 teams 花名册工具改名
C 只改文案	fix/wait-agent-no-progress-label	最小改动，只消除误导

个人建议：B + C 的内容已包含在本分支；A 保留作为"严格按文档"的备选。

[argszero]

An out-of-tree plugin already holds the delegation half of this, and it was built on the same root cause you reached.

Same diagnosis, independently. experimental/agent-team-profile/cordis.patch.yml addresses rows by id; vendor/include/src/index.ts buildMap recurses only into same-level group rows and skips an unmatched id, and scripts/verify-cordis-config.ts::validatePresetPlaneSeparation enforces that a row belongs to exactly one plane — so a top-level patch structurally cannot reach a preset row. On web the four ids it re-sets had already been turned off by bundle/web-app/cordis.patch.yml, which is why the miss is silent instead of warned about; the patch does match rows, so nothing looks wrong.

Runtime-plane equivalent of your fix A, with no core change: @argszero/cordis-plugin-team-delegation-guard@0.1.0

• npm: https://www.npmjs.com/package/@argszero/cordis-plugin-team-delegation-guard
• source: https://github.com/argszero/cordis-plugin-team-delegation-guard

# any profile / bundle layer
- insert:
    - id: team-delegation-guard
      name: '@argszero/cordis-plugin-team-delegation-guard'

It keys on spawn_teammate — the marker tool-agent-team registers into agent.ctx (tool-agent-team/src/index.ts:164-176) and nothing else in the tree registers — and then calls agent.ctx.tools.restrict({ deny }) for the legacy names that agent can still see (default subagent, subagent_fork, plus the one-shot providers subagent_codex, subagent_claude_code). The seam asymmetry is what makes it precise: restrict() filters inherited layers only and merges the scope's own registrations after the filter, so preset-plane rows are maskable while Team's own-layer tools are not. It is inert in a composition without Teams, and it goes inert by itself once a composition stops exposing the names — i.e. once your fix A lands. mode: warn previews what a given composition leaks without changing anything.

What it does not fix, measured against your three symptoms:

1. Your (2) — wait_agent stuck on no-active-peer after subagent created the child — is the one it targets. With subagent/subagent_fork withdrawn, the only delegation surface left on that session is the Team one, so the child is a Team member and wait_agent has a peer to observe.
2. Your (1) — the duplicate list_agents — cannot be fixed by denying the name at this seam: Team registers list_agents into each agent's own layer, which restrict() exempts by construction, so denying it would withdraw the Team roster along with the preset row. Your evidence is consistent with that: the resolved call returns the teammate roster, i.e. own-layer shadowing already gives the Team version precedence. What a Team session actually loses is the delegation tools, not the roster name.
3. Your (3) — the noProgress wording — is out of reach for a mount; that string lives in the client locale table rather than in a seam a bundle layer can replace.

One note for the review of fix A, in case it gets simplified: keep the condition per row. The enclosing delegation group also carries the workflow row, which headless Team snapshots appear to retain — that is why the guard works off the live visible-name set rather than a constant list.

[zhouyunsheng31]

Thanks — that account of the mechanism is sharper than my report had it, and it settles the one observation I could not reconcile: why the duplicate list_agents resolved to the Team roster even though the preset row is the nearer ancestor. Own-layer vs. inherited at the tool seam explains it, and it matches what the session log shows (tool-agent-team installs through agent.ctx; core/tools/src/index.ts view() merges the own layer after the restriction filter, exactly as you describe).

I re-verified both structural claims against master before replying:

• vendor/include/src/index.ts:66-73 — buildMap descends only into entry.group === true rows whose config is an array. A preset definition carries config: { plugins: [...] }, so its rows never enter entryMap and a top-level patch structurally cannot address them. An unmatched id produces only a debug warn, and here the id does match the host row — so the miss is silent, not warned. Confirmed.
• scripts/verify-cordis-config.ts:139-166 — validatePresetPlaneSeparation derives the host-side active set from top-level disabled entries only, so the preset rows never trip the one-plane rule. Confirmed.

On the review note for fix A: agreed, and the branch already does it per row. The condition lands on tool-subagent-control, tool-subagent-list-agents, tool-subagent, tool-subagent-fork — not on the enclosing delegation group — which is why workflow-ptc is untouched. Branch fix/agent-team-preset-delegation (fork, 12 lines / 3 files).

Where the guard and the two core branches sit

Symptom	guard (runtime)	fix A (core, per row)	fix B (core, rename)	fix C (locale)
(1) duplicate list_agents	cannot — own-layer is exempt by construction	removes the preset row, so only Team's roster is left	renames Team's roster to list_teammates, so each name has one owner and the subagent list comes back	—
(2) wait_agent no-active-peer after subagent	yes — by withdrawing the delegation surface	yes, same route	no — both surfaces stay; instead the wait_agent description and the noProgress text now state the scope and point at run_in_background: false	—
(3) noProgress wording	cannot — client locale	—	—	yes

Two things I think are worth stating plainly, because they are policy rather than mechanism:

1. The guard and fix A implement one policy (the documented exclusivity); B implements the other (coexistence). A deployment that wants both surfaces cannot use the guard, and the guard going inert once A lands is real, not rhetorical — I checked that against the DEFAULT_DENY/live-view logic and it holds.
2. (1) and (3) are unreachable from any mount, so if the project wants all three symptoms covered, at least those two need in-tree changes. That is the entire reason branch B exists rather than being a stylistic preference.

Cross-reference: #7642 reported the same root cause three weeks ago and covered the roster/reachability half ("dispatched someone and can neither find nor reach them"). This thread adds the wait_agent half and one patch per symptom.

Question for the maintainers: for the shipped Web profile, is the intended long-term policy exclusivity (A, with the guard as the out-of-tree stopgap) or coexistence (B)? That decides which branch is worth landing — both are small, both are on the fork, and neither needs anything beyond the four preset rows / the one tool name.

Branches:

• A: https://github.com/deepseek-ai/deepseek-harness/compare/master...zhouyunsheng31:deepseek-harness:fix/agent-team-preset-delegation?expand=1
• B: https://github.com/deepseek-ai/deepseek-harness/compare/master...zhouyunsheng31:deepseek-harness:fix/decouple-agent-teams?expand=1
• C: https://github.com/deepseek-ai/deepseek-harness/compare/master...zhouyunsheng31:deepseek-harness:fix/wait-agent-no-progress-label?expand=1