docs(agent): clarify parameter preconditions

[tao943]

What this PR does

Clarifies the Agent tool's advertised parameter contracts without changing runtime behavior:

• documents that read_only requires a named teammate in an active team;
• documents the mutual exclusion between read_only and plan_mode_required;
• states that an unnamed caller-owned working_dir rejects explicit background execution, while configured background execution is rejected at the top level and downgraded to the foreground when nested;
• aligns the user-facing worktree guide with the existing runtime and developer documentation;
• adds schema-description regression assertions for these contracts.

Why it's needed

The runtime already rejects these invalid combinations, but the tool schema described effects or defaults without stating the corresponding preconditions and failure modes. Because the schema guides model tool calls, the mismatch can cause avoidable invalid Agent invocations.

Reviewer Test Plan

How to verify

1. Enable Agent Teams and inspect the generated Agent tool schema.
2. Confirm read_only says it requires a named teammate in an active team and cannot be combined with plan_mode_required.
3. Confirm plan_mode_required documents the reciprocal incompatibility.
4. Confirm run_in_background states that an unnamed caller-owned working_dir rejects explicit background execution, rejects configured background execution at the top level, and downgrades configured background execution to the foreground when nested.
5. Run the focused schema tests and core typecheck.

Evidence (Before & After)

N/A — tool-schema and documentation-only change.

Tested on

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

Environment (optional)

Windows 11, Node.js 24.15.0, npm 11.12.1.

Verification:

• npm run test --workspace=packages/core -- --run src/tools/agent/agent.test.ts -t "declares the background default and foreground opt-out|rejects read_only without a named teammate|rejects read_only when no team is active|rejects combining read_only with plan_mode_required" — 4 passed.
• Additional rejection/downgrade and model-guidance coverage — 4 focused tests passed.
• npm run typecheck --workspace=packages/core — passed.
• npm run build -- --cli-only — passed.
• Targeted ESLint, Prettier, and git diff --check — passed.
• Full agent.test.ts: 264 passed, 1 existing Windows-only path assertion failed because the test expects /test/project/... while Windows returns D:\\test\\project\\...; the schema tests changed here passed.

Risk & Scope

• Main risk or tradeoff: wording may need adjustment to match maintainer terminology.
• Not validated / out of scope: no runtime validation or execution behavior changes; the unrelated Windows path assertion remains out of scope.
• Breaking changes / migration notes: none.

Linked Issues

Fixes #9514

中文说明

此 PR 的改动

在不改变运行时行为的前提下，明确 Agent 工具公开参数的契约：

• 说明 read_only 只能用于 active team 中的具名 teammate；
• 说明 read_only 与 plan_mode_required 互斥；
• 说明匿名、caller-owned working_dir 会拒绝显式后台执行；配置出的后台执行在顶层被拒绝，在嵌套调用中降级为前台；
• 让用户侧 worktree 文档与现有运行时和开发者文档保持一致；
• 为这些契约补充 schema 描述回归断言。

为什么需要

运行时已经会拒绝这些非法组合，但工具 schema 只描述了效果或默认值，没有写清前置条件和失败方式。由于 schema 会指导模型调用工具，这种不一致可能导致本可避免的无效 Agent 调用。

Reviewer Test Plan

验证方式

1. 启用 Agent Teams 并查看生成的 Agent 工具 schema。
2. 确认 read_only 写明需要 active team 中的具名 teammate，且不能与 plan_mode_required 组合。
3. 确认 plan_mode_required 也写明对应的互斥关系。
4. 确认 run_in_background 写明匿名 caller-owned working_dir 会拒绝显式后台执行、在顶层拒绝配置出的后台执行，并在嵌套调用中将配置出的后台执行降级为前台。
5. 运行聚焦的 schema 测试和 core typecheck。

修改前后证据

N/A——仅修改工具 schema 描述和文档。

测试平台

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

环境

Windows 11、Node.js 24.15.0、npm 11.12.1。

验证结果：

• 四条聚焦 schema/运行时契约测试通过；
• 新增的拒绝/降级与模型提示语义覆盖：4 条聚焦测试通过；
• core typecheck 通过；
• npm run build -- --cli-only 通过；
• 目标 ESLint、Prettier 和 git diff --check 通过；
• 完整 agent.test.ts 为 264 通过、1 失败；唯一失败是既有 Windows 路径断言，测试期望 /test/project/...，Windows 实际返回 D:\\test\\project\\...，本 PR 修改的 schema 测试均通过。

风险与范围

• 主要风险或权衡：维护者可能希望调整措辞以匹配项目术语。
• 未验证 / 范围外：不修改运行时校验或执行行为；无关的 Windows 路径断言不在本 PR 范围内。
• 破坏性变更 / 迁移说明：无。

关联 Issue

Fixes #9514

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: observed, not theoretical — the linked issue #9514 documents two planning exercises in which models reading the Agent tool schema could not determine rules the runtime enforces (read_only on unnamed subagents, working_dir + run_in_background), and cites the exact validation lines that reject those calls. The issue is open and triaged (type/documentation, priority/P3).

Direction: aligned. The schema text is what models plan tool calls from; stating preconditions and failure modes the same way neighbouring descriptions already do is squarely in scope.

Size: core paths are touched but the change is tiny — 9 production-logic lines (description string literals only), 15 test lines, 2 docs lines. No escalation triggers.

Approach: matches the issue's asks one-for-one and carries nothing extra — the two main instances plus the mutual-exclusion note, with schema-description regression assertions in the existing test style, and a one-line alignment of the user-facing worktree guide. Nothing I'd cut.

Risk: no elevated risk signals (no high-risk paths touched).

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：已观测而非理论——关联 issue #9514 记录了两次规划练习，模型仅凭 Agent 工具 schema 无法确定运行时实际强制的规则（无名 subagent 上的 read_only、working_dir + run_in_background），并引用了拒绝这些调用的确切校验代码行。该 issue 处于开启状态且已被分类（type/documentation、priority/P3）。

方向：对齐。schema 文本是模型规划工具调用的依据；像相邻描述已有的写法那样写明前置条件和失败方式，完全在项目范围内。

规模：触及核心路径但改动很小——9 行生产逻辑（仅描述字符串字面量）、15 行测试、2 行文档。无升级触发条件。

方案：与 issue 的诉求一一对应，没有多余内容——两个主要实例加上互斥说明，附既有测试风格的 schema 描述回归断言，以及用户侧 worktree 指南的一行对齐。没有需要砍掉的部分。

风险：无升级风险信号（未触及高风险路径）。

进入代码审查 🔍

— Qwen Code · qwen3.8-max

_{Reviewed at 3dc3dde1c40de388a4ddf2d9997dec851dd74a9e · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

Read against the runtime at the reviewed commit, every new sentence is accurate:

• read_only — "Only valid with a named teammate in an active team" matches validateToolParams, which rejects read_only without a name and without an active team; "Cannot be combined with plan_mode_required" (and the mirror sentence added to plan_mode_required) matches the existing mutual-exclusion rejection.
• run_in_background — "explicit run_in_background: true is rejected" is exactly right: validation rejects only an explicit true on unnamed caller-owned working_dir launches, while an omitted value resolves to foreground via the default computation. The old "default to foreground" phrasing read as an overridable default, which it is not.
• The worktree guide's "reject explicit or configured background execution" is correct on both routes — the explicit request is rejected in validation, and a subagent config with background: true is rejected by the spawn-time guard.
• The new test assertions quote strings that appear verbatim in the new descriptions and sit inside the two existing schema tests; the local type extension for read_only is consistent with the teams-enabled schema shape.

No runtime behavior changes — the diff touches only description string literals, test assertions, and docs prose.

One non-blocking observation: the issue's "Anything else" section listed two smaller instances; this PR covers the mutual-exclusion one but not the note that run_in_background states no default for named teammates. The existing "always concurrent — omit run_in_background" clause arguably covers it already, but worth a glance when closing #9514.

Testing

CI on this commit: this is a fork PR, and both pull_request workflow runs (Qwen Code CI, Security Checks) completed as action_required — they have not executed yet and need maintainer approval, so no build/lint/unit checks exist for this commit yet.

Check	Conclusion
Qwen Code CI	⏸️ awaiting workflow approval (fork PR)
Security Checks	⏸️ awaiting workflow approval (fork PR)
precheck-pr / precheck	✅ success
label	✅ success

• Not verified: unit tests on this commit — the fork's CI has not run. The Windows test results quoted in the PR description are the author's claim, not independently re-run here (triage never executes PR code). If the Windows job later lands red on the path-format assertion the author mentions, that looks pre-existing: the test file mocks POSIX paths throughout and this PR only adds toContain assertions on description strings — but judge it from the actual log when it exists.
• Real-scenario (tmux): N/A — docs/schema-description change with nothing user-visible to drive.

中文说明

代码审查

对照被审 commit 的运行时代码逐条核对，新增的每一句描述都是准确的：

• read_only——"Only valid with a named teammate in an active team" 与 validateToolParams 一致（缺少 name 或没有活跃 team 都会被拒绝）；"Cannot be combined with plan_mode_required"（以及加在 plan_mode_required 上的镜像句）与既有的互斥拒绝一致。
• run_in_background——"explicit run_in_background: true is rejected" 完全准确：校验只拒绝匿名 caller-owned working_dir 启动上显式的 true，省略该参数时默认值计算会落到前台。旧措辞 "default to foreground" 读起来像可覆盖的默认值，实际并非如此。
• worktree 指南中的 "reject explicit or configured background execution" 两条路径都成立：显式请求在校验阶段被拒绝，subagent 配置 background: true 由启动时的守卫拒绝。
• 新增测试断言引用的字符串与新描述逐字一致，且位于两个既有 schema 测试内；read_only 的本地类型扩展与启用 teams 时的 schema 形状一致。

无运行时行为变化——diff 只触及描述字符串字面量、测试断言和文档文本。

一个非阻塞观察：issue 的"其他"小节列了两个较小实例；本 PR 覆盖了互斥那一条，但没有处理 "run_in_background 未写明具名 teammate 默认值" 那条。现有 "always concurrent — omit run_in_background" 子句可以说已经覆盖，但关闭 #9514 时值得看一眼。

测试

本 commit 的 CI：这是 fork PR，两个 pull_request 工作流运行（Qwen Code CI、Security Checks）以 action_required 结束——尚未执行，需要维护者批准，因此该 commit 目前没有任何构建/lint/单测检查（表格见上方英文部分）。

• 未验证：该 commit 上的单元测试——fork 的 CI 尚未运行。PR 描述中引用的 Windows 测试结果是作者自述，不是独立复跑的证据（triage 从不执行 PR 代码）。如果之后 Windows 任务因作者提到的路径格式断言变红，那看起来是既有问题：测试文件通篇 mock POSIX 路径，而本 PR 只新增了对描述字符串的 toContain 断言——届时以实际日志为准。
• 真实场景（tmux）：N/A——纯文档/schema 描述改动，没有可驱动的用户可见行为。

— Qwen Code · qwen3.8-max

_{Reviewed at 3dc3dde1c40de388a4ddf2d9997dec851dd74a9e · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 4/5 — verified word-by-word against the runtime, minimal, and exactly what the issue asked for; the only gap is that the fork's CI hasn't run yet.

Stepping back: this is the kind of PR that is easy to vouch for. The problem is real and observed — models reading the schema could not learn rules the runtime enforces — and the fix does precisely what #9514 requested, copying the sibling wording instead of inventing new phrasing. My independent sketch of the fix (update the three descriptions, pin them with schema assertions in the existing test style, align the user guide) is exactly what landed; I found no simpler path and nothing unnecessary in the diff. The additions to read_only and plan_mode_required mirror each other, and the run_in_background rewrite keeps the "explicit" qualifier that makes it true — validation rejects an explicit true, not an omitted one.

The one reservation is procedural, not substantive: the fork's CI is still awaiting workflow approval, so "tests pass on this commit" is the author's claim rather than a green run — static review can vouch for the wording, not for the suite. The two pull_request workflow runs completed as action_required without spawning any checks, so approval is deferred until CI lands green on 3dc3dde1c40de388a4ddf2d9997dec851dd74a9e.

中文说明

这个 PR 很容易让人认可。问题真实且已观测——模型仅凭 schema 无法得知运行时实际强制的规则——修复恰好做了 #9514 要求的事，沿用相邻参数的既有措辞而不是自造新说法。我独立的修复设想（更新三处描述、用既有测试风格的 schema 断言固定下来、对齐用户指南）与落地的完全一致；没找到更简路径，diff 中也没有多余内容。read_only 与 plan_mode_required 的新增措辞互相镜像，run_in_background 的改写保留了让它成立的 "explicit" 限定——校验拒绝的是显式的 true，而非省略该参数的情况。

唯一的保留是流程性的，而非实质性的：fork 的 CI 仍在等待工作流批准，因此"该 commit 测试通过"目前是作者自述而非绿色运行结果——静态审查可以为措辞背书，无法为测试套件背书。两个 pull_request 工作流运行以 action_required 结束、未产生任何检查，因此批准延迟到 CI 在该 commit 上全绿后由 finalize 流程执行（上方标记行即为该指令）。

— Qwen Code · qwen3.8-max

_{Reviewed at 3dc3dde1c40de388a4ddf2d9997dec851dd74a9e · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Partially reviewed — gaps disclosed. Suggestions are inline.

Not explored to full depth (tool budget reached): "agent 3b": none — no check was cut short.; "agent 6b": executing the updated agent.test.ts — the worktree's node_modules is partially broken ( npm ci fails with ENOTEMPTY under packages/mobile-mcp/node_modul…; "agent 1a": run packages/core agent.test.ts to execute the new assertions (worktree has no node_modules ; install+build exceeds the review budget). Substring/mocking v….

Not reviewed: reverse audit — stopped before round 4 by the review time budget.

Test Plan (not a blocker): 2 passed — this review observed 20711, 1638, 22570, 1616, 494, 3860, 556 passed; 261 passed — this review observed 20711, 1638, 22570, 1616, 494, 3860, 556 passed.

中文说明

仅完成部分审查，审查缺口已披露。 建议见行内评论。

未探索到全部深度（达到工具调用预算）："agent 3b"：none — no check was cut short.；"agent 6b"：executing the updated agent.test.ts — the worktree's node_modules is partially broken ( npm ci fails with ENOTEMPTY under packages/mobile-mcp/node_modul…；"agent 1a"：run packages/core agent.test.ts to execute the new assertions (worktree has no node_modules ; install+build exceeds the review budget). Substring/mocking v…。

未审查：反向审计——评审时间预算不足，未能开始第 4 轮。

Test Plan（非阻断）：2 passed — this review observed 20711, 1638, 22570, 1616, 494, 3860, 556 passed; 261 passed — this review observed 20711, 1638, 22570, 1616, 494, 3860, 556 passed。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[qwen-code-ci-bot]

[Suggestion] This diff pins description text promising three read_only preconditions, but the runtime validation branches that enforce them — requires a name, requires an active team, mutual exclusion with plan_mode_required (agent.ts:1199-1216) — have zero tests, while the analogous plan_mode_required branches are tested. A probe deletion confirmed the gap: removing the mutual-exclusion guard (or all three branches) ships green at 262/262, so the enforcement the new schema text promises could be deleted with CI staying green — and the description assertion this diff adds would stay green too, since it only reads text. Mirror the existing plan_mode_required tests, e.g.:

it('rejects read_only without a named teammate', () => {
  expect(
    agentTool.validateToolParams({ ...validParams, read_only: true }),
  ).toMatch(/named teammate/i);
});

it('rejects read_only when no team is active', () => {
  vi.mocked(config.getTeamManager).mockReturnValue(null);
  expect(
    agentTool.validateToolParams({
      ...validParams,
      name: 'reader',
      read_only: true,
    }),
  ).toMatch(/active team/i);
});

it('rejects combining read_only with plan_mode_required', () => {
  vi.mocked(config.getTeamManager).mockReturnValue({
    spawnTeammate: vi.fn(),
  } as never);
  expect(
    agentTool.validateToolParams({
      ...validParams,
      name: 'reader',
      read_only: true,
      plan_mode_required: true,
    }),
  ).toMatch(/cannot be used together/i);
});

Probe evidence: deleting only the mutual-exclusion guard → 262/262 pass; deleting all three read_only branches → 262/262 pass; a probe test asserting the rejection fails with the guard removed and passes with it restored.

中文说明

此 diff 固定了承诺 read_only 三项前置条件的描述文本，但执行这些前置条件的运行时校验分支（需要 name、需要 active team、与 plan_mode_required 互斥，agent.ts:1199-1216）没有任何测试，而类似的 plan_mode_required 分支却有测试。探针删除证实了该缺口：删除互斥守卫（或全部三个分支）后 262/262 仍全部通过，即新 schema 文本所承诺的校验可以在 CI 全绿的情况下被删除——本 diff 新增的描述断言也会保持绿色，因为它只读取文本。建议仿照现有 plan_mode_required 测试补充上述测试。

探针证据：仅删除互斥守卫 → 262/262 通过；删除全部三个 read_only 分支 → 262/262 通过；断言该拒绝的探针测试在守卫删除时失败、恢复后通过。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[tao943]

Fixed in 4c2cc6f. Added direct validateToolParams regression coverage for all three advertised read_only preconditions: named teammate, active team, and mutual exclusion with plan_mode_required. I also mutation-tested the coverage by temporarily removing the three guards; all three new tests failed, then passed again after restoring the runtime validation.

[qwen-code-ci-bot]

[Suggestion] The sentence this PR rewrites documents only the explicit-true rejection, but the worktree.md sentence written in this same PR says "reject explicit or configured background execution" — and the configured route is real: a subagent definition with background: true frontmatter, launched unnamed with working_dir while omitting run_in_background, passes validateToolParams (agent.ts:1143 only checks explicit true), then at execute time the omitted flag resolves to subagentConfig.background === true and the spawn guard (agent.ts:2655-2667) rejects the launch — the existing test 'rejects working_dir when the resolved subagent config runs in the background' proves that route. So the schema promises a foreground run where the runtime hard-rejects the launch: the same description-vs-rejection mismatch class issue #9514 is about, in the very sentence this PR rewrote. Consider mirroring the worktree.md wording:

Suggested change

'Defaults to true for top-level regular subagents. Set to false to run a regular agent in the foreground and return its result inline. Set to true for an interactive fork to receive its completion notification; headless forks always run in the background. Nested agents run in the foreground unless run_in_background is explicitly true, which is rejected because they cannot receive background completion notifications. Unnamed caller-owned working_dir launches run in the foreground; explicit run_in_background: true is rejected because the caller owns the worktree lifecycle. Named teammates are always concurrent and report through team messaging: omit run_in_background when spawning one — an explicit false is rejected; for an inline blocking result, omit "name" and run a regular agent with run_in_background: false. A teammate pinned to a caller-owned worktree must be shut down before that worktree is removed.',

'Defaults to true for top-level regular subagents. Set to false to run a regular agent in the foreground and return its result inline. Set to true for an interactive fork to receive its completion notification; headless forks always run in the background. Nested agents run in the foreground unless run_in_background is explicitly true, which is rejected because they cannot receive background completion notifications. Unnamed caller-owned working_dir launches run in the foreground; explicit run_in_background: true and configured background defaults (a subagent definition with background: true) are rejected because the caller owns the worktree lifecycle. Named teammates are always concurrent and report through team messaging: omit run_in_background when spawning one — an explicit false is rejected; for an inline blocking result, omit "name" and run a regular agent with run_in_background: false. A teammate pinned to a caller-owned worktree must be shut down before that worktree is removed.',

中文说明

本 PR 重写的这句话只写明了显式 run_in_background: true 会被拒绝，但同一 PR 中 worktree.md 的句子写的是"拒绝显式或配置出的后台执行"——配置路径确实存在：带有 background: true frontmatter 的 subagent 定义，在未指定 name 时携带 working_dir 启动且省略 run_in_background，能通过 validateToolParams（agent.ts:1143 只检查显式 true），但在执行期省略的标志会解析为 subagentConfig.background === true，spawn 守卫（agent.ts:2655-2667）会拒绝该启动——现有测试 'rejects working_dir when the resolved subagent config runs in the background' 证明了该路径。即 schema 承诺前台运行，而运行时却硬拒绝该启动：正是 issue #9514 所指的"描述与拒绝不一致"的同类问题，且恰好出现在本 PR 重写的这句里。建议对齐 worktree.md 的措辞（见上方 suggestion）。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[tao943]

Fixed in 4c2cc6f. The schema now documents both rejection routes: explicit run_in_background: true and configured background defaults from a subagent definition with background: true. The schema assertion was updated to lock in the configured-default wording.

[qwen-code-ci-bot]

Reviewed. Suggestions are inline.

Not explored to full depth (tool budget reached): "agent 1a": executing the new assertions via vitest in packages/core — the worktree (and parent checkout) has no node_modules , and a full npm ci + monorepo build exce…; "agent 3b": running packages/core agent.test.ts to confirm the new tests pass — the review worktree has no installed dependencies ( vitest unresolvable), so verificati….

Test Plan (not a blocker): 4 passed — this review observed 20636, 1638, 22570, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20636, 1638, 22570, 1616, 494, 3860, 556 passed.

Deferred under the convergence posture (round 2, not a blocker) — recorded, not requested in this round:

• packages/core/src/tools/agent/agent.ts:296 — [probe] read_only description omits the team-leader precondition enforced in execute()

中文说明

已审查。 建议见行内评论。

未探索到全部深度（达到工具调用预算）："agent 1a"：executing the new assertions via vitest in packages/core — the worktree (and parent checkout) has no node_modules , and a full npm ci + monorepo build exce…；"agent 3b"：running packages/core agent.test.ts to confirm the new tests pass — the review worktree has no installed dependencies ( vitest unresolvable), so verificati…。

Test Plan（非阻断）：4 passed — this review observed 20636, 1638, 22570, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20636, 1638, 22570, 1616, 494, 3860, 556 passed。

收敛姿态下延后（第 2 轮，非阻断）——已记录，本轮不要求修改：共 1 条（原文未翻译，列表见上方英文部分）。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[qwen-code-ci-bot]

[Suggestion] The new sentence documents two rejection routes for unnamed caller-owned working_dir launches, but the configured-background route is only rejected at the top level. The spawn guard is conditioned on shouldRunInBackground = backgroundRequested && isTopLevelSession() (agent.ts:2654-2655), so a nested launch with a background: true subagent definition never reaches it — the launch is silently downgraded to a foreground run with only a debug log. A nested sub-agent spawning an unnamed working_dir agent whose definition sets background: true, omitting run_in_background, gets a silent foreground launch where the documented rejection is expected. The behavior itself is safe and deliberate (the guard's comment documents the downgrade to avoid over-rejecting a nested call), so this is a wording fix only: qualify the sentence, e.g. "explicit run_in_background: true is rejected, and a configured background default (a subagent definition with background: true) is rejected at the top level (downgraded to a foreground run for nested launches), because the caller owns the worktree lifecycle". The worktree.md sentence carries the same claim and gets a parallel comment. Confirmed by running the two existing tests that pin each arm at this commit — the top-level rejection test and the nested-downgrade test, both green.

中文说明

新句子为匿名 caller-owned working_dir 启动记录了两条拒绝路径，但配置出的后台路径只在顶层会话被拒绝。spawn 守卫以 shouldRunInBackground = backgroundRequested && isTopLevelSession()（agent.ts:2654-2655）为条件，因此带有 background: true subagent 定义的嵌套启动永远到不了该守卫——启动会静默降级为前台运行，仅输出一条 debug 日志。当嵌套 sub-agent 启动一个定义中设置了 background: true 且省略 run_in_background 的匿名 working_dir agent 时，调用方期待文档承诺的拒绝，实际得到的却是静默的前台启动。行为本身安全且是有意为之（守卫注释说明了为避免过度拒绝嵌套调用而降级），因此这只是措辞修正：给句子加限定，例如"显式 run_in_background: true 会被拒绝；配置出的后台默认（background: true 的 subagent 定义）在顶层被拒绝，嵌套启动则降级为前台运行，因为 caller 拥有 worktree 生命周期"。worktree.md 中的句子有相同表述，会收到一条并行评论。已在本提交上运行钉住两种分支的两个既有测试确认——顶层拒绝测试与嵌套降级测试均为绿色。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[tao943]

Thanks for catching the top-level versus nested distinction. Addressed in c6be15f: the schema now states that explicit run_in_background: true is rejected, while a configured background default is rejected at the top level and downgraded to the foreground for nested launches. The focused rejection and nested-downgrade tests pass.

[qwen-code-ci-bot]

[Suggestion] Same wording defect as the parallel comment on agent.ts: this rewritten sentence states that unnamed caller-owned working_dir launches "reject explicit or configured background execution", but the configured-background route is only rejected at the top level — the spawn guard is conditioned on shouldRunInBackground, which requires a top-level session (agent.ts:2654-2655), and a nested launch with a background: true subagent definition silently downgrades to a foreground run instead of being rejected (verified by running the existing nested-downgrade test at this commit). Qualify the sentence the same way, e.g. "run in the foreground; explicit or configured background execution is rejected at the top level and downgrades to a foreground run when nested, because their lifecycle is managed externally."

中文说明

与 agent.ts 上的并行评论相同的措辞缺陷：本句重写后声称匿名 caller-owned working_dir 启动"拒绝显式或配置出的后台执行"，但配置出的后台路径只在顶层被拒绝——spawn 守卫以 shouldRunInBackground 为条件，要求顶层会话（agent.ts:2654-2655）；带有 background: true subagent 定义的嵌套启动会静默降级为前台运行，而非被拒绝（已在本提交上运行既有的嵌套降级测试确认）。请同样为句子加限定，例如"以前台运行；显式或配置出的后台执行在顶层被拒绝，嵌套时降级为前台运行，因为其生命周期由外部管理"。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[tao943]

Addressed in c6be15f. The worktree guide now matches the runtime semantics: explicit background execution is rejected; configured background execution is rejected at the top level and downgraded to a foreground run when nested.

[qwen-code-ci-bot]

[Suggestion] The new regression guard pins the subject of the new claim but stops before its verb: if the description's "are rejected" were rewritten to "are supported", this test would still pass, and the #9514 guard would stay green while the model-facing description becomes false. Verified by mutation at this commit — with the description mutated to "are supported" the test stays green, and adding the suggested assertion turns it red. The sibling assertion in the same test ('an explicit false is rejected') already pins its verb the same way.

Suggested change

	expect(properties.properties.run_in_background.description).toContain(
	'explicit run_in_background: true and configured background defaults',
	);
	expect(properties.properties.run_in_background.description).toContain(
	'explicit run_in_background: true and configured background defaults',
	);
	expect(properties.properties.run_in_background.description).toContain(
	'are rejected because the caller owns the worktree lifecycle',
	);

中文说明

新的回归守卫钉住了新声明的主语，却停在动词之前：若把描述中的 "are rejected" 改写成 "are supported"，该测试仍会通过，#9514 的回归守卫保持绿色，而面向模型的描述已变为错误。已在本提交上做变异验证——将描述变异为 "are supported" 后该测试仍为绿色；加上建议的断言后变红。同一测试中的姊妹断言（'an explicit false is rejected'）已经以同样方式钉住了动词。

— qwen3.8-max via Qwen Code /review (v0.21.14)

[tao943]

Addressed in c6be15f. The regression assertions now pin both verbs explicitly: explicit run_in_background: true is rejected, and configured background defaults are rejected at the top level and downgraded for nested launches. The focused schema test is green.

[qwen-code-ci-bot]

Reviewed — no blockers. Suggestions are inline.

Test Plan (not a blocker): 4 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed.

Deferred under the convergence posture (round 3, not a blocker) — recorded, not requested in this round:

• packages/core/src/tools/agent/agent.test.ts:697 — [probe] missing absence-pin for read_only in the team-disabled schema half

中文说明

已审查——无阻断问题。 建议见行内评论。

Test Plan（非阻断）：4 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed。

收敛姿态下延后（第 3 轮，非阻断）——已记录，本轮不要求修改：共 1 条（原文未翻译，列表见上方英文部分）。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[qwen-code-ci-bot]

[Suggestion] This clarified wording updates two of the surfaces that state this rule, but a third copy is left stale: docs/developers/tools/task.md:19 still reads "Caller-owned working_dir launches run in the foreground and reject explicit or configured background execution." The blanket reject for configured background execution is false for nested launches — in agent.ts execute() (~2643–2672), a subagent definition with background: true resolves backgroundRequested = true, the spawn guard only blocks when isTopLevelSession() is true, and a nested launch logs "Background request downgraded to a foreground run" and proceeds in the foreground. A developer consulting task.md expects the nested working_dir + background: true combination to be rejected; the runtime accepts and downgrades it, so after this PR two doc surfaces disagree on exactly the reject-vs-downgrade distinction the PR exists to clarify. Update the run_in_background bullet in task.md to match, e.g. "Unnamed caller-owned working_dir launches run in the foreground: an explicit run_in_background: true is rejected, and a configured background default is rejected at the top level but downgraded to a foreground run when nested."

Witness: the repo's own pinned tests run at the reviewed commit — 'allows working_dir for a background:true subagent that downgrades to foreground when nested' → 1 passed; 'rejects working_dir when the resolved subagent config runs in the background' → 1 passed.

中文说明

这句澄清后的措辞更新了表述该规则的其中两处，但第三份副本仍然过时：docs/developers/tools/task.md:19 仍写着 "Caller-owned working_dir launches run in the foreground and reject explicit or configured background execution."。其中对配置出的后台执行一律 拒绝 的说法在嵌套启动中不成立——在 agent.ts 的 execute()（约 2643–2672 行）中，带有 background: true 的 subagent 定义会解析出 backgroundRequested = true，spawn 守卫只在 isTopLevelSession() 为真时拦截，嵌套启动会记录 "Background request downgraded to a foreground run" 并以前台方式继续执行。阅读 task.md 的开发者会以为嵌套的 working_dir + background: true 组合会被拒绝，而运行时实际接受并降级为前台，因此本 PR 合入后，两份文档恰好在本 PR 要澄清的"拒绝还是降级"这一点上互相矛盾。请将 task.md 中 run_in_background 条目更新为一致的措辞，例如："Unnamed caller-owned working_dir launches run in the foreground: an explicit run_in_background: true is rejected, and a configured background default is rejected at the top level but downgraded to a foreground run when nested."

证据：在受审提交上运行仓库自带的固定测试——'allows working_dir for a background:true subagent that downgrades to foreground when nested' → 1 passed；'rejects working_dir when the resolved subagent config runs in the background' → 1 passed。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[tao943]

Fixed in fa42510. The task.md run_in_background entry now scopes the rule to unnamed caller-owned working_dir launches and distinguishes explicit rejection from configured top-level rejection and nested foreground downgrade.

[qwen-code-ci-bot]

[Suggestion] The same rule is also stated in this file's usage-guidance bullet at agent.ts:866 ("Unnamed caller-owned working_dir launches default to foreground and cannot run in the background"), and this update does not reach that copy. The bullet is not currently wrong — such a launch never actually runs in the background on any route — but the regression assertions this PR adds pin only the schema wording above. The next edit to this rule will be forced to touch the pinned copy while the unpinned bullet in the same file stays behind, leaving two model-facing texts stating the same rule at different depths indefinitely. Aligning the bullet with this wording in this PR makes all three surfaces move together.

中文说明

同一规则还出现在本文件的使用指引条目 agent.ts:866 中（"Unnamed caller-owned working_dir launches default to foreground and cannot run in the background"），本次更新没有覆盖到那份副本。该条目目前并不算错——无论走哪条路径，这类启动最终都不会真正在后台运行——但本 PR 新增的回归断言只固定了上方 schema 措辞。下次修改这条规则时，被固定措辞的副本会被迫同步更新，而同文件中这条未被固定措辞的条目会被落下，两份面向模型的文本将无限期地以不同深度表述同一规则。在本 PR 中将该条目对齐为此处措辞，可让三处表述同步变更。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[tao943]

Fixed in fa42510. The model-facing usage guidance now carries the same explicit/configured distinction as the schema, and the initialization test pins both the explicit rejection and configured top-level rejection/nested downgrade clauses.

[qwen-code-ci-bot]

[Suggestion] A fourth surface still states the old blanket rule: docs/users/features/sub-agents.md:138 says a working_dir launch "cannot be combined with subagent_type: \"fork\" or background execution." The background half of that sentence is false for the nested + configured case — background: true is a real subagent-definition key, and a nested launch with working_dir is accepted and downgraded to a foreground run (agent.ts ~2668–2672; the pinned test 'allows working_dir for a background:true subagent that downgrades to foreground when nested' passes at this commit). The fork half stays correct (fork + working_dir is always rejected) and should be kept. Rewrite the background half to match this sentence, e.g. "an explicit background request is rejected, and a configured background: true default is rejected at the top level and downgraded to a foreground run when nested."

中文说明

还有第四处表述仍写着旧的一刀切规则：docs/users/features/sub-agents.md:138 称 working_dir 启动 "cannot be combined with subagent_type: \"fork\" or background execution."。这句话中关于 background 的半句在嵌套 + 配置路径下不成立——background: true 是真实存在的 subagent 定义字段，嵌套启动携带 working_dir 时会被接受并降级为前台运行（agent.ts 约 2668–2672 行；固定测试 'allows working_dir for a background:true subagent that downgrades to foreground when nested' 在本提交上通过）。关于 fork 的半句仍然正确（fork + working_dir 始终被拒绝），应保留。请将关于 background 的半句改写为与本句一致，例如 "an explicit background request is rejected, and a configured background: true default is rejected at the top level and downgraded to a foreground run when nested."

— qwen3.8-max via Qwen Code /review (v0.21.15)

[tao943]

Fixed in fa42510. The sub-agents guide preserves the unconditional fork incompatibility and now documents explicit background rejection plus configured top-level rejection/nested foreground downgrade.

[qwen-code-ci-bot]

[Suggestion] This sentence introduces "configured background execution" without defining it — it is the only occurrence of "background" in this file, and no page under docs/users/ documents the background: true subagent-definition key it refers to. The schema-description counterpart updated in this same PR carries an explicit gloss ("A configured default comes from a subagent definition with background: true."), which shows the term is not self-explanatory; this sentence omits it. A user whose subagent definition has background: true — and who hits either the top-level rejection or an unexplained foreground run — cannot tell from this page which outcome applies to their setup, because "configured background execution" reads as a near-synonym of the "explicit background execution" earlier in the same sentence. Add the gloss inline, e.g. "...while configured background execution (a subagent definition with background: true) is rejected at the top level and downgraded to a foreground run when nested...".

中文说明

这句话引入了 "configured background execution" 一词却没有定义——它是本文件中唯一出现的 "background"，而 docs/users/ 下没有任何页面说明它所指的 background: true subagent 定义字段。同一 PR 中更新的 schema 描述带有明确的解释（"A configured default comes from a subagent definition with background: true."），说明该术语并非不言自明；本句却省略了。一位在 subagent 定义中写了 background: true 的用户——无论是遇到顶层拒绝还是不明原因的前台运行——都无法从本页判断自己的配置对应哪种结果，因为 "configured background execution" 读起来与同句前面的 "explicit background execution" 近乎同义。请在句中内联补充解释，例如 "...while configured background execution (a subagent definition with background: true) is rejected at the top level and downgraded to a foreground run when nested..."。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[tao943]

Fixed in fa42510. The worktree guide now defines configured background execution inline as background: true in a subagent definition.

[qwen-code-ci-bot]

Not explored to full depth (tool budget reached): "agent 6b": executing packages/core/src/tools/agent/agent.test.ts — the review worktree has no node_modules (verified), so test execution was replaced by static verific….

Test Plan (not a blocker): 4 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed.

Deferred under the convergence posture (round 4, not a blocker) — recorded, not requested in this round:

• packages/core/src/tools/agent/agent.test.ts:545 — [probe] schema-description assertions leave the leading foreground clause unpinned

中文说明

未探索到全部深度（达到工具调用预算）："agent 6b"：executing packages/core/src/tools/agent/agent.test.ts — the review worktree has no node_modules (verified), so test execution was replaced by static verific…。

Test Plan（非阻断）：4 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20714, 1638, 22567, 1616, 494, 3860, 556 passed。

收敛姿态下延后（第 4 轮，非阻断）——已记录，本轮不要求修改：共 1 条（原文未翻译，列表见上方英文部分）。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[qwen-code-ci-bot]

[Critical] The bullet this diff adds scopes the foreground rule to unnamed caller-owned working_dir launches, but the unchanged working_dir bullet two lines below (line 21) still states categorically "The caller owns the worktree lifecycle, so this mode runs in the foreground" — a guarantee wider than the code's. Named teammates pinned to a working_dir are always concurrent: team routing returns via executeTeammate before any background classification (agent.ts ~2278), the teammate worktree pin passes the worktree as the teammate's cwd and returns immediately (agent.ts ~4267), and an explicit run_in_background: false for a named teammate is rejected both in validateToolParams (~1172) and at runtime (~2293) — while the tool's own guidance recommends pinning a writer teammate to a leader-owned worktree (agent.ts ~832). The diff re-scoped the equivalent sentence in sub-agents.md, worktree.md, the schema description and the usage notes to "Unnamed" while missing this one, so the page now contradicts itself: pre-diff it was uniformly blanket, post-diff line 19's scoping falsifies line 21. An integrator scripting a team workflow reads the working_dir bullet, expects an inline blocking result when pinning a named teammate to a leader-owned worktree, and instead receives a concurrent spawn confirmation, then an error when trying to force the documented foreground semantics.

Witness (probe at fa42510):

ROW_A (name=writer + working_dir): "Teammate \"writer\" is now running concurrently. … Worktree: /test/project/.qwen/tmp/writer …"
ROW_B (same + run_in_background: false): "Parameter \"run_in_background\" cannot be false for a named teammate: teammates always run concurrently …"

Update the working_dir bullet (line 21) in the same change — e.g.:

- `working_dir` (string, optional): Pin an explicitly named, non-fork agent to an existing registered git worktree inside the current repository. Unnamed launches run in the foreground because the caller owns the worktree lifecycle (see `run_in_background`); a named teammate pinned to one runs concurrently and must be shut down before the worktree is removed. If both `working_dir` and `isolation` are provided, `working_dir` takes precedence.

(No one-click suggestion block: this comment is anchored on line 19, the run_in_background bullet, because line 21 is outside the diff hunks — the fix targets line 21.)

中文说明

本 diff 新增的条目将前台规则限定为匿名 caller-owned working_dir 启动，但下方两行的 working_dir 条目（第 21 行，未被修改）仍然绝对地写着 "The caller owns the worktree lifecycle, so this mode runs in the foreground"——承诺范围超出代码实际行为。固定到 working_dir 的具名 teammate 始终并发运行：team 路由在任何后台分类之前就通过 executeTeammate 返回（agent.ts ~2278），teammate worktree 固定把 worktree 作为 teammate 的 cwd 并立即返回（agent.ts ~4267），而对具名 teammate 显式传 run_in_background: false 会在 validateToolParams（~1172）和运行时（~2293）两层被拒绝——与此同时工具自身的指引却推荐把 writer teammate 固定到 leader 拥有的 worktree（agent.ts ~832）。本 diff 已把 sub-agents.md、worktree.md、schema 描述和使用说明中的等价句子都改为 "Unnamed" 限定，唯独漏了这一处，导致该页面自相矛盾：改动前整页是笼统一致的表述，改动后第 19 行的限定使第 21 行失真。集成者按 working_dir 条目编写团队工作流脚本，把具名 teammate 固定到 leader 的 worktree 并期望内联阻塞结果，实际收到的是并发启动确认，再试图强制前台语义时得到错误。

见证（在 fa42510 上的探针执行结果）见英文部分 ROW_A / ROW_B。请在同一修改中更新 working_dir 条目（第 21 行），示例见英文部分。（注：因第 21 行不在 diff hunk 内，本评论锚定在第 19 行即 run_in_background 条目上，修改目标是第 21 行，故不提供一键 suggestion 块。）

— qwen3.8-max via Qwen Code /review (v0.21.15)

[tao943]

Fixed in f854a19. The working_dir bullet now distinguishes unnamed launches, which run in the foreground, from named teammates, which run concurrently and must be shut down before the caller-owned worktree is removed.

[qwen-code-ci-bot]

[Suggestion] This assertion is satisfied by the pre-existing nested-agent sentence, not by the working_dir sentence it was added to pin — the substring occurs twice in tool.description (the usage notes at agent.ts:866 carry both the nested-agent sentence and the new working_dir sentence). Mutate only the working_dir sentence this PR added — flip "is rejected" to "is downgraded to the foreground" in that sentence, inverting exactly the rejected-vs-downgraded distinction the PR clarifies in the model-facing prompt — and the whole agent.test.ts stays green (probe: 265 passed with the mutant in place), so the regression ships with the #9514 guard green. The schema-property test is unaffected (the phrase is unique there); only the usage-notes half is unpinned. Anchoring the assertion to the working_dir sentence fixes it — verified: the longer assertion fails the mutant and passes the real code.

Suggested change

	expect(tool.description).toContain(
	'an explicit `run_in_background: true` request is rejected',
	);
	expect(tool.description).toContain(
	'Unnamed caller-owned `working_dir` launches run in the foreground: an explicit `run_in_background: true` request is rejected',
	);

中文说明

该断言命中的是既有的 nested-agent 句子，而非它要保护的 working_dir 句子——这个子串在 tool.description 中出现两次（agent.ts:866 的使用说明同时包含 nested-agent 句子和新增的 working_dir 句子）。只变异本 PR 新增的 working_dir 句子——把该句中的 "is rejected" 翻转为 "is downgraded to the foreground"，恰好颠倒本 PR 在模型可见提示中澄清的"拒绝/降级"区分——整个 agent.test.ts 仍然全绿（探针：变异体下 265 通过），该回归会在 #9514 守卫保持绿色的情况下溜走。schema 属性测试不受影响（该短语在那里唯一）；只有使用说明这一半未被固定。将断言锚定到 working_dir 句子即可修复——已验证：加长后的断言能使变异体失败、在真实代码上通过。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[tao943]

Fixed in f854a19. The assertion is now anchored to the complete working_dir clause (Unnamed caller-owned working_dir launches...), so it no longer passes by matching the earlier nested-agent sentence. Mutation verification confirmed that changing only the working_dir rejection to a downgrade makes the focused test fail; the restored code passes all four focused tests.

[qwen-code-ci-bot]

No blocking issues. LGTM! ✅

Test Plan (not a blocker): 4 passed — this review observed 20714, 1638, 22570, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20714, 1638, 22570, 1616, 494, 3860, 556 passed.

Deferred under the convergence posture (round 5, not a blocker) — recorded, not requested in this round:

• packages/core/src/tools/agent/agent.test.ts:714 — [probe] schema test missing read_only absence-pin for the teams-disabled half

中文说明

无阻断问题。LGTM！✅

Test Plan（非阻断）：4 passed — this review observed 20714, 1638, 22570, 1616, 494, 3860, 556 passed; 264 passed — this review observed 20714, 1638, 22570, 1616, 494, 3860, 556 passed。

收敛姿态下延后（第 5 轮，非阻断）——已记录，本轮不要求修改：共 1 条（原文未翻译，列表见上方英文部分）。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[qwen-code-ci-bot]

No blocking issues. LGTM! ✅

Not explored to full depth (tool budget reached): "agent 6c": execute the new agent.test.ts assertions (no node_modules/dist in the shared review worktree; npm ci + root build prerequisite exceeded the review budget) — s….

Test Plan (not a blocker): 4 passed — this review observed 20747, 1661, 22839, 1638, 495, 4026, 595 passed; 264 passed — this review observed 20747, 1661, 22839, 1638, 495, 4026, 595 passed.

Deferred under the convergence posture (round 6, not a blocker) — recorded, not requested in this round:

• packages/core/src/tools/agent/agent.test.ts:717 — [probe] read_only schema removal has no absence-pin for the teams-disabled refresh path

中文说明

无阻断问题。LGTM！✅

未探索到全部深度（达到工具调用预算）："agent 6c"：execute the new agent.test.ts assertions (no node_modules/dist in the shared review worktree; npm ci + root build prerequisite exceeded the review budget) — s…。

Test Plan（非阻断）：4 passed — this review observed 20747, 1661, 22839, 1638, 495, 4026, 595 passed; 264 passed — this review observed 20747, 1661, 22839, 1638, 495, 4026, 595 passed。

收敛姿态下延后（第 6 轮，非阻断）——已记录，本轮不要求修改：共 1 条（原文未翻译，列表见上方英文部分）。

— qwen3.8-max via Qwen Code /review (v0.21.15)

[wenshao]

Maintainer local verification — merge-ready (52/52 assertions)

Post-merge note: this round was running when the PR was squash-merged as 3a9d2d37f834 — so this reads as independent confirmation of what landed, not a pre-merge gate. Current main (95b2cf4cb1) carries all five contract sentences (re-checked against the origin/main blob after the merge).

Verified head a1a0593f2b43 · base arm 04886c4354f0 (resolved from baseRefOid) · trial-merge arm 8fda2ddf8617 (PR head + main@2855149d47, conflict-free). Full report with methodology and raw-log pointers is in the run artifacts; the load-bearing results:

Central claim proven both directions

The PR claims the schema documents preconditions/failure modes without changing runtime behavior. Both halves were proven against the real artifacts:

• Wire A/B (real CLI, loopback OpenAI server, full request bodies captured): head's Agent tool schema carries all five new contract sentences; base lacks every one of them; with the four edited descriptions masked, the rest of the schema JSON is byte-identical between arms. 30/30 scripted assertions (compare.mjs).
• Runtime unchanged (real binary, 5 rejection scenarios incl. a full team_create → mutex-rejection multi-turn flow): every rejection string is byte-identical base↔head, and each matches what the new schema text promises.

Schema delta as captured off the wire — base said working_dir launches "default to foreground" (reads as overridable); head says explicit run_in_background: true is rejected and a configured default is rejected at the top level / downgraded to the foreground when nested. read_only gains "Only valid with a named teammate in an active team. Cannot be combined with plan_mode_required."

Mutation / vacuity matrix — the new tests are load-bearing

arm (full agent.test.ts)	result
head (control)	265/265 green
agent.ts reverted to base + head tests	exactly the 3 schema-description tests red, 262 green — and the 3 new validateToolParams tests stay green ⇒ they pin pre-existing runtime
mutual-exclusion guard deleted	exactly rejects combining read_only with plan_mode_required red (positive control; closes the zero-coverage gap the first CI review round flagged)
usage-note verb flipped (is rejected → is downgraded)	exactly the pinned usage-notes test red (the "satisfied by the nested-agent sentence" finding from round 1 stays fixed)

Suite gates: head 265/265, base 262/262 (Δ = +3 = exactly the new tests; the Windows-only path failure in the PR description does not reproduce on macOS), core tsc --noEmit clean. Trial merge into main@2855149d (which had already touched agent.ts/agent.test.ts in disjoint regions, and a diverging lockfile — merged tree got its own npm ci): 265/265 green, wire schema still carries all five sentences, rejections identical, docs pages updated — 14/14 merge-arm assertions.

Not covered

• The configured-background (background: true definition) top-level rejection / nested downgrade was verified at suite level (the two pre-existing pinned tests, green on both arms) plus code reading of agent.ts:2643–2672 — not driven end-to-end through the wire harness (needs a background subagent definition + full execute).
• No real model call — the loopback server is a wire-shape oracle; issue Agent tool parameters document effects but not preconditions or failure modes #9514's planning exercises were not re-run.
• Windows-only path assertion not reproduced (macOS arm64 round); ESLint/Prettier and the CVE audit left to CI (lockfile byte-identical base↔head, so the audit result cannot differ).

中文摘要

结论：merge-ready —— 52/52 条脚本化断言全部通过。（本验证进行期间 PR 已由 wenshao squash 合并为 3a9d2d37，本报告作为对已合入内容的独立确认。）

• A/B 双向证明：用真实 CLI 二进制 + 本地回环 OpenAI 服务器捕获完整请求体。head 的 Agent 工具 schema 携带全部五条新契约句（read_only 需具名 teammate 且与 plan_mode_required 互斥；working_dir 显式后台被拒绝、配置默认后台顶层拒绝/嵌套降级为前台），base 全部缺失；屏蔽这 4 处描述后两臂 schema 逐字节相同。5 个拒绝场景（含 team_create 建队后的互斥拒绝多轮流程）报错文本 base↔head 逐字节一致 —— 运行时行为未变，与 PR 声明一致。
• 变异矩阵：还原描述后恰好 3 个 schema 测试变红（文本断言 load-bearing）、3 个新运行时测试仍绿（钉的是既有行为）；删除互斥 guard 恰好对应测试变红（阳性对照，封住 CI 首轮指出的零覆盖缺口）；翻转 usage-notes 动词恰好对应测试变红。
• 套件门禁：head 265/265、base 262/262（差值 +3 恰为新增测试；Windows 路径失败在 macOS 不复现）；core typecheck 干净；对 main@2855149d 的 trial merge 无冲突且全绿（14/14）。
• 未覆盖：background: true 配置默认的顶层拒绝/嵌套降级仅在套件层 + 代码阅读验证，未走 wire 端到端；未调用真实模型；Windows 断言未复现；CVE audit 交由 CI（lockfile 两臂逐字节相同，结果不可能不同）。

[qwen-code-ci-bot]

Released in v0.22.2.