docs: refresh subagent lifecycle guidance

[wenshao]

What this PR does

Refreshes the subagent user and developer documentation to match the current agent lifecycle. It documents headless fork support, completion notifications, background-agent discovery and continuation, session roster restoration, and caller-owned worktree behavior.

Why it's needed

The existing guidance still described forks as interactive-only and unable to return results to the parent conversation. It also characterized subagents as stateless, single-use executions, despite the shipped list_agents and send_message continuation flow. These discrepancies could lead users and tool authors to launch duplicate agents or misunderstand supported execution modes.

Reviewer Test Plan

How to verify

Compare the documented behavior against the current Agent tool schema and background-task lifecycle: forks should be available in headless sessions and report results through completion notifications; background agents should be discoverable and continuable across running, paused, completed, and restored states; caller-owned worktrees should remain foreground-only and unavailable to forks.

Evidence (Before & After)

N/A — documentation-only change.

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	N/A
🐧 Linux	N/A

Environment (optional)

Documentation validation with Prettier and git diff --check.

Risk & Scope

• Main risk or tradeoff: Documentation could drift from implementation details; the updated statements were checked against the Agent tool schema, background-task registry, and message continuation paths.
• Not validated / out of scope: No runtime behavior was changed or exercised end-to-end.
• Breaking changes / migration notes: None.

Linked Issues

None.

中文说明

本 PR 做了什么

更新 subagent 的用户与开发者文档，使其与当前 agent 生命周期保持一致。文档现在覆盖 headless fork 支持、完成通知、后台 agent 的发现与继续、会话 roster 恢复，以及调用方拥有的 worktree 行为。

为什么需要

现有文档仍将 fork 描述为仅支持交互模式且无法将结果反馈给父对话；同时也将 subagent 描述为无状态、单次执行，尽管已经上线了基于 list_agents 和 send_message 的继续工作流程。这些差异可能导致用户和工具作者重复启动 agent，或误解当前支持的执行模式。

Reviewer Test Plan

How to verify

将文档描述与当前 Agent tool schema 和后台任务生命周期进行对照：fork 应支持 headless 会话并通过完成通知返回结果；后台 agent 应能在 running、paused、completed 和 restored 状态下被发现和继续；调用方拥有的 worktree 应仅支持前台运行，且不能用于 fork。

Evidence (Before & After)

N/A — 仅文档改动。

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	N/A
🐧 Linux	N/A

Environment (optional)

使用 Prettier 和 git diff --check 验证文档。

Risk & Scope

• 主要风险或取舍：文档可能与实现细节再次发生漂移；本次更新已对照 Agent tool schema、后台任务 registry 和消息继续路径进行检查。
• 未验证 / 不在范围内：未改变或进行端到端测试任何运行时行为。
• 破坏性变更 / 迁移说明：无。

Linked Issues

无。

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: This is a documentation-drift fix — the existing docs describe forks as interactive-only and subagents as stateless/single-use, which no longer matches the shipped implementation (headless fork support, list_agents/send_message continuation, completion notifications). The discrepancy is observable by comparing the docs to the current Agent tool schema and background-task lifecycle.

Direction: Aligned — keeping docs accurate is core mission. The updates cover headless forks, continuation, caller-owned worktrees, and completion delivery, all of which are shipped features.

Size: Not applicable — docs-only change (2 files, 42+/13-).

Approach: Scope feels right. Every edit maps to a specific documentation gap, no unrelated changes or drive-by refactors. The two files are the natural homes for this content.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：这是一个文档漂移修复——现有文档将 fork 描述为仅支持交互模式、将 subagent 描述为无状态/单次执行，与已上线的实现（headless fork 支持、list_agents/send_message 继续流程、完成通知）不再一致。通过对比文档与当前 Agent tool schema 和后台任务生命周期即可观察到这一差异。

方向：对齐——保持文档准确是核心使命。更新覆盖了 headless fork、继续流程、调用方拥有的 worktree 和完成通知投递，均为已上线功能。

规模：不适用——仅文档改动（2 个文件，42+/13-）。

方案：范围合理。每处编辑都对应一个具体的文档缺口，没有无关改动或顺手重构。两个文件是这些内容的自然归属。

进入代码审查 🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 4f408825e5fc7d1b599d59a38adfca0ae9a6a0a3 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code Review

Independent proposal: For a subagent lifecycle docs refresh, I would update docs/developers/tools/task.md (add working_dir param, update isolation/run_in_background descriptions, add continuation section, fix "stateless/single-use" claims) and docs/users/features/sub-agents.md (remove interactive-only fork restriction, remove "No result feedback" limitation, add continuation and working_dir sections).

Comparison with the diff: The PR does exactly this. I verified every factual claim against the source code:

• Headless forks — confirmed in fork-subagent.ts and agent.ts: headless forks always use the background registry. ✅
• Fork result feedback — confirmed: results arrive via <task-notification> completion notifications through BackgroundTaskRegistry. Removing the "No result feedback" limitation is accurate. ✅
• list_agents / send_message continuation — both tools exist in packages/core/src/tools/. send_message handles running, paused, and completed agents (resident runtime continuation or transcript revival). ✅
• Session roster restoration — confirmed in background-agent-resume.ts: compatible agents are restored on session resume, with resumeBlockedReason for incompatible ones. ✅
• working_dir parameter — confirmed in the Agent tool schema: pins to an existing caller-owned worktree, foreground-only, rejects background execution. ✅
• working_dir vs isolation precedence — confirmed: createInvocation drops isolation when working_dir is set. ✅
• run_in_background defaults — confirmed: true for top-level regular agents; working_dir excludes from implicit background. ✅
• isolation restriction — confirmed: requires explicit subagent_type that is not "fork". The docs' "explicitly named, non-fork agent" wording is consistent with the codebase's "named subagent" terminology. ✅

No correctness issues, no AGENTS.md violations.

Testing

Docs-only change — no runtime behavior to exercise in tmux. Verification:

$ npx prettier --check docs/developers/tools/task.md docs/users/features/sub-agents.md
Checking formatting...
All matched files use Prettier code style!

$ git diff --check HEAD~1
(no whitespace errors)

Content accuracy verified against source code as detailed above.

中文说明

代码审查

独立方案： 对于 subagent 生命周期文档刷新，我会更新 docs/developers/tools/task.md（添加 working_dir 参数、更新 isolation/run_in_background 描述、添加继续流程章节、修正"无状态/单次使用"描述）和 docs/users/features/sub-agents.md（移除 fork 仅限交互模式的限制、移除"无结果反馈"限制、添加继续流程和 working_dir 章节）。

与 diff 对比： PR 完全按照这个思路执行。我逐一对照源码验证了每个事实性声明：

• Headless fork — 在 fork-subagent.ts 和 agent.ts 中确认：headless fork 始终使用后台 registry。✅
• Fork 结果反馈 — 确认：结果通过 BackgroundTaskRegistry 的 <task-notification> 完成通知到达。移除"无结果反馈"限制是准确的。✅
• list_agents / send_message 继续流程 — 两个工具均存在于 packages/core/src/tools/。send_message 处理 running、paused 和 completed 状态的 agent。✅
• 会话 roster 恢复 — 在 background-agent-resume.ts 中确认：兼容的 agent 在会话恢复时被还原。✅
• working_dir 参数 — 在 Agent tool schema 中确认：固定到已有的调用方拥有的 worktree，仅前台运行。✅
• working_dir 与 isolation 优先级 — 确认：设置 working_dir 时 createInvocation 会丢弃 isolation。✅
• run_in_background 默认值 — 确认：顶层常规 agent 默认为 true；working_dir 排除在隐式后台之外。✅
• isolation 限制 — 确认：需要显式的 subagent_type 且不能是 "fork"。✅

无正确性问题，无 AGENTS.md 违规。

测试

仅文档改动——无需在 tmux 中运行运行时行为。验证结果：Prettier 格式检查通过，git diff --check 无空白错误，内容准确性已对照源码逐一验证。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 4f408825e5fc7d1b599d59a38adfca0ae9a6a0a3 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5

Every factual claim in this PR checks out against the source code — headless fork support, completion notifications, background agent continuation via list_agents/send_message, session roster restoration, caller-owned worktree behavior, and working_dir/isolation precedence. The "No result feedback" limitation removal is accurate: fork results are delivered through <task-notification> completion notifications.

The changes are focused (2 docs files, no code), the scope matches the stated goal, and formatting passes Prettier and git diff --check. No issues found.

LGTM, approving. ✅

中文说明

置信度：5/5

本 PR 中的每个事实性声明都已对照源码验证——headless fork 支持、完成通知、通过 list_agents/send_message 的后台 agent 继续流程、会话 roster 恢复、调用方拥有的 worktree 行为、以及 working_dir/isolation 优先级。移除"无结果反馈"限制是准确的：fork 结果通过 <task-notification> 完成通知投递。

改动聚焦（2 个文档文件，无代码改动），范围与目标一致，格式通过 Prettier 和 git diff --check 检查。未发现问题。

LGTM，批准。✅

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 4f408825e5fc7d1b599d59a38adfca0ae9a6a0a3 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-ci-bot]

Reviewed. Suggestions are inline.

— qwen3.7-max via Qwen Code /review

[qwen-code-ci-bot]

[Suggestion] Interactive forks without run_in_background: true default to the foreground path and return only a placeholder — the fork's actual result is never delivered to the parent conversation. The docs here cover "background runs" (completion notification) and "foreground regular subagents" (inline), but omit the interactive fork case.

The same gap exists in two other places this PR touches:

• The fork prose above (line 17) says forks "normally run detached in the background" without explaining when they don't. The tool schema at agent.ts:794 has the missing guidance: "Set to true for an interactive fork to receive its completion notification."
• docs/developers/tools/task.md line 17 describes run_in_background for "top-level regular agents" and "headless forks" but omits interactive forks.

Failure scenario: A user launches agent({subagent_type: "fork", prompt: "..."}) in an interactive session without run_in_background: true. The code routes this to the foreground fork path (agent.ts:2463–2471), returns FORK_PLACEHOLDER_RESULT, and the fork's actual result is never delivered.

Suggested change

	4. **Results**: Background runs send a completion notification containing the result to the main conversation; foreground regular subagents return results inline
	4. **Results**: Background runs send a completion notification containing the result to the main conversation; foreground regular subagents return results inline. Interactive forks require `run_in_background: true` to receive a completion notification; without it, the fork returns only a placeholder.

— qwen3.7-max via Qwen Code /review

[tanzhenxin]

LGTM!