Subagent tool description says "returns its result" but the call returns immediately (non-blocking) — and spawn_teammate never says it does not block

[warm-flame-core]

Subagent tool description contradicts runtime: it says "returns its result" but returns immediately with started subagent <id>

Summary

The model-facing tool description for subagent (and subagent_fork) tells the model it will receive the subagent's result:

"The subagent returns its result, not its intermediate steps."
"You receive its result, not its intermediate steps."

But the runtime does not wait. render() returns started subagent ${value.subagentId}, and per packages/subagent/subagent/README.zh.md the tool "立即返回子会话 ID，后台 activation 结算后父级收到完成通知". The result arrives later, as a separate completion notification.

A model that trusts the description believes the delegation is synchronous. It then continues immediately, treating the just-launched child as if it had already reported — or it "helpfully" fills the wait with other work. There is no instruction anywhere in the model-visible text telling it that (a) the call returns at once, (b) a completion notification will arrive later and will re-enter the conversation, or (c) what it must do in between.

The agent-team plugin has the mirror-image gap: teamPolicy() does say "The Lead must wait for required teammates before giving the final answer" and explains wait_agent semantics in detail, but spawn_teammate's own description says nothing about the fact that spawning is also non-blocking — it only says "Create one named, durable teammate." A model reading only that tool description has no signal that it must wait_agent (or at least list_agents) before assuming the work is done.

Why this matters in practice

In real sessions this produces two recurring failure modes, both observed repeatedly:

1. Lead continues after spawning. The Lead spawns a subagent or teammate, then immediately performs work that depends on the child's output — using stale conclusions, or producing deliverables that the child's result will invalidate.

2. Concurrent unsynchronized writes. The Lead spawns a teammate, does not wait, and starts editing files itself. The teammate later edits the same file. Nothing in the model-facing text explains the shared-filesystem + no-lock model strongly enough at the point of the spawn_teammate call; the guidance lives only in the injected teamPolicy block, far from the tool call itself.

The second mode is the expensive one: the teammate discovers the Lead's edit mid-task, its work is invalidated, and it returns to redo it — a full round-trip that a one-line "this call does not block; call wait_agent before depending on the result" would have prevented.

Where the gap is

Surface	What the model is told	Missing
subagent / subagent_fork tool description	"returns its result", "You receive its result"	No mention that the call is fire-and-forget; no mention of the completion notification or of what to do between
subagent tool result (render)	started subagent <childId>	Nothing explains this is not the result, or that a notification follows
spawn_teammate tool description	"Create one named, durable teammate."	No "does not block", no pointer to wait_agent / list_agents
Injected teamPolicy()	Detailed wait_agent semantics, "The Lead must wait…"	Does not cover spawn_teammate being non-blocking; not co-located with the call
subagent (no team plugin)	—	No injected policy block at all; the only guidance is the misleading tool description

The asymmetry is the core issue: the team plugin injects a policy block that describes waiting, while the plain subagent path injects nothing — yet both are non-blocking. A model that has never been told the subagent path is asynchronous has no way to infer it, and the description actively suggests the opposite.

Suggested fix (small, model-facing text only)

No runtime change needed — the behaviour is fine; the description is what misleads.

1. providerWording() in packages/subagent/tool-subagent/src/index.ts — replace "returns its result" with something like:

   "This call returns immediately with started subagent <childId>; it does not block. The child runs in the background and its result arrives later as a completion notification that re-enters this conversation. Do not treat the child's work as done in the meantime, and do not start work that depends on its result."

2. spawn_teammate description in packages/experimental/tool-agent-team/src/index.ts — add one clause:

   "Spawning does not block and does not wait for the teammate's turn. Use wait_agent (with list_agents first) before depending on its output, and do not write to files the teammate may also write."

3. Consider an injected policy block for the plain subagent path, mirroring teamPolicy(), or at minimum a sentence in the tool result render() such as started subagent <id> (running in background; result arrives as a notification).

Environment

• DSH checkout: F:\Code\deepseek-harness, HEAD 22ddee3792
• Observed on both the plain subagent path and the agent-team plugin path, across multiple long writing sessions where delegation was used heavily.

Happy to open a PR with the wording changes if that is useful — though I understand from CONTRIBUTING that external PRs are not being accepted right now.

[warm-flame-core]

Currently, a significant portion of my work involves extensive file modifications. After the main agent has completed its planning, it will attempt to utilize either the intelligent agent team or the sub-agent function. However, due to the interdependencies among multiple files, file modifications heavily emphasize both asynchronous and synchronous processes. Often, the lead fails to recognize the need to wait for teammates' changes before proceeding, resulting in premature modifications that disrupt teammates' judgment and lead to repeated rework. A temporary solution involves clearly defining the synchronous and asynchronous methods in file specifications, but I believe this falls under the scope of system prompt design