docs(subagent): clarify shared preset delegation tradeoffs

2026-10-26 15:02:10 +08:00
1 parent c527f18146
commit db38164d4c
@@ -6,8 +6,8 @@
  en: 982ac05aa02da2f0
  zh: 225f89c994efb1c4
 /agent-note-awaited-per-agent-initialization/problem:
-  en: 03e6b75365b29406
-  zh: cc880a33cf2303d0
+  en: 6e9393e78ff71286
+  zh: b931a7e606cad37e
 /agent-note-awaited-per-agent-initialization/decision:
  en: 48cdb570d3feb222
  zh: 904a1169540e3111
@@ -15,5 +15,5 @@
  en: 466a9ebbb13f68c6
  zh: ab88fb34786d2c2b
 /agent-note-awaited-per-agent-initialization/consequences:
-  en: d8cfe8d88ccacfc8
-  zh: 8d2aa21408e6e40e
+  en: 3fc2b36a94ace3ba
+  zh: 65bb386b89ff89ce
@@ -6,7 +6,7 @@ English | [中文](2026-09-09-awaited-agent-creation.zh.md)

 ## Problem

-Shared presets install tools and prompt sections separately for each Agent. That installation can await plugin activation, and external SessionStart hooks can produce context asynchronously. A creator must know that these contributions have finished before the Agent's first model request.
+Agent-specific plugins can install tools asynchronously, and external SessionStart hooks can produce context asynchronously. A creator must know that these contributions have finished before the Agent's first model request.

 ## Decision

@@ -28,4 +28,6 @@ This decision owns asynchronous creation timing. The [scope runtime reference](.

 Creation latency includes asynchronous plugin and SessionStart work. Initializer failures become caller-visible creation failures, and cancellation relies on listeners settling cooperatively. Notifications already delivered cannot be undone; rollback pairs them with disposal notifications.

-Scoped installer tests verify rollback, lifecycle tests verify ordered completion and cancellation, and the SDK serial-created scenario verifies that asynchronous prompt context reaches the first request. Hook tests cover awaited context injection and subprocess disposal.
+Lifecycle tests verify initialization rollback, ordered completion and cancellation, and the SDK serial-created scenario verifies that asynchronous prompt context reaches the first request. Hook tests cover awaited context injection and subprocess disposal.
+
+Delegation tools use [shared preset registrations](../bug-fix/2026-10-25-shared-preset-delegation-tools.md); they do not require per-Agent installation. This event still owns asynchronous Agent initialization.
@@ -6,7 +6,7 @@ Status: implemented

 ## 问题

-共享 preset 为每个 Agent（智能体）分别安装工具与提示词段。安装可能要等待插件激活，外部 SessionStart 钩子也可能异步产生上下文。创建方必须知道这些贡献已完成，才能允许 Agent 发起首次模型请求。
+针对单个 Agent（智能体）的插件可能异步安装工具，外部 SessionStart 钩子也可能异步产生上下文。创建方必须知道这些贡献已完成，才能允许 Agent 发起首次模型请求。

 ## 决策

@@ -28,4 +28,6 @@ AgentLoop 在 setup 与创建分发期间保留现有的维护活动。初始化

 创建延迟包括异步插件与 SessionStart 工作。初始化器失败成为调用方可见的创建失败，取消依赖监听器协作结算。已经送达的通知无法撤回；回滚会为其配对销毁通知。

-作用域安装器测试验证回滚，生命周期测试验证有序完成与取消，SDK serial-created 场景验证异步提示词上下文进入首次请求。钩子测试覆盖需等待的上下文注入与子进程 dispose。
+生命周期测试验证初始化回滚、有序完成与取消，SDK serial-created 场景验证异步提示词上下文进入首次请求。钩子测试覆盖需等待的上下文注入与子进程 dispose。
+
+委派工具使用[预设共享注册](../bug-fix/2026-10-25-shared-preset-delegation-tools.zh.md)，无须按 Agent 安装。此事件仍负责异步 Agent 初始化。
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-25-shared-preset-delegation-tools.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-10-25-shared-preset-delegation-tools.md
+/agent-note-shared-preset-delegation-tools:
+  en: 2f33b8a19d8291b8
+  zh: 4f49de632ac53d01
+/agent-note-shared-preset-delegation-tools/problem:
+  en: 3150532ae6efd14c
+  zh: 3c3d662c5bcb323b
+/agent-note-shared-preset-delegation-tools/decision:
+  en: ccaa0792d54fe79d
+  zh: b2993214c35c1db0
+/agent-note-shared-preset-delegation-tools/alternatives-considered:
+  en: 2f53caf2af750178
+  zh: cd4d9b823a9348dc
+/agent-note-shared-preset-delegation-tools/consequences:
+  en: 4aaaaec2038b3f1d
+  zh: b52bdd02118ffb6f
@@ -0,0 +1,31 @@
+# Agent Note: Shared preset delegation tools
+
+Status: implemented
+
+English | [中文](2026-10-25-shared-preset-delegation-tools.zh.md)
+
+## Problem
+
+Agents sharing a preset need the same delegation definitions immediately after a preset switch. Installing identical tools separately for each Agent introduces an asynchronous visibility gap and places those definitions in the Agent's own registration layer, which is exempt from inherited-tool restrictions.
+
+## Decision
+
+Each tool-subagent instance registers its definition in its owning composition. Agents sharing a preset revision inherit that registration. Switching presets changes ancestry; it requires no per-Agent installation or tool-change reconciliation. Provider availability and the owning composition's disposal control registration lifetime.
+
+Tool configuration validates its own fields, allowlist consistency, required services and provider capabilities. Candidate preset documents are not read during registration, for either Host-mounted or preset-mounted tools. The delegation executor validates the model's selection against the allowlist; child startup resolves the selected id against the current registry. A later declaration can therefore satisfy a previously unavailable target without reinstalling the tool. Independent selection and restoration retain the [spawn preset semantics](../feature/2026-09-20-spawn-agent-preset-selection.md).
+
+The schema contains preset ids and default or inheritance guidance without candidate descriptions. This keeps shared definitions independent of other presets' declaration order and avoids retaining document text that can become stale. [Awaited Agent initialization](../architecture/2026-09-09-awaited-agent-creation.md) remains necessary for other asynchronous contributions.
+
+## Alternatives considered
+
+**Reinstall tools for each Agent.** Identical definitions gain extra installation, disposal and reconciliation work, and Agent-local ownership prevents inherited-tool restrictions from applying.
+
+**Validate every target at tool registration.** A target declared later is rejected even though it can be available when used. An early successful lookup also cannot guarantee availability after registry changes.
+
+**Retain candidate descriptions in shared schemas.** Reading descriptions during registration makes the result depend on declaration order. Keeping those descriptions current requires additional update coordination; the tool exposes ids instead.
+
+## Consequences
+
+Unknown or unloadable targets fail the selected delegation without leaving a child Agent or Session. An unused invalid reference remains undetected. Agent restrictions and restored historical filters apply to inherited delegation schemas, execution and guidance; sibling Agents retain their tools.
+
+Focused preset-selection tests cover immediate switch visibility, shared ownership and disposal, restrictions, missing targets and retry after declaration. The Web Loader cases cover shipped composition compatibility, and the headless preset snapshot pins model-visible choices. The historical-filter tests exercise child composition directly; they do not establish cold-resume coverage.
@@ -0,0 +1,31 @@
+# Agent Note: 预设共享委派工具
+
+Status: implemented
+
+[English](2026-10-25-shared-preset-delegation-tools.md) | 中文
+
+## 问题
+
+共享预设的 Agent（智能体）需要在预设切换完成后立即取得相同的委派定义。为每个 Agent 分别安装相同工具会产生异步可见性缺口，并将定义放在 Agent 自身的注册层，而该层不受继承工具限制约束。
+
+## 决策
+
+每个 tool-subagent 实例在所属组装中注册定义。共享同一预设代际的 Agent 继承该注册。切换预设只改变祖先关系，无须按 Agent 安装或协调工具变更。提供方可用性及所属组装的 dispose（资源释放）决定注册的生命周期。
+
+工具配置校验自身字段、白名单一致性、必需服务及提供方能力。Host 挂载和预设内挂载的工具都不在注册时读取候选预设文档。委派执行器按白名单校验模型选择，子级启动时再从当前注册表解析所选 id。因此，后续声明能够使原先不可用的目标变得可用，无须重新安装工具。独立选择与恢复保留 [spawn 预设语义](../feature/2026-09-20-spawn-agent-preset-selection.zh.md)。
+
+schema 包含预设 id 及默认或继承提示，不包含候选描述。这使共享定义不依赖其他预设的声明顺序，也避免保留可能陈旧的文档文本。其他异步贡献仍需要[等待 Agent 初始化](../architecture/2026-09-09-awaited-agent-creation.zh.md)。
+
+## 考虑过的替代方案
+
+**为每个 Agent 重新安装工具。** 相同定义需要额外的安装、释放与协调工作，Agent 本地所有权还会阻止继承工具限制生效。
+
+**在工具注册时校验所有目标。** 后声明的目标即使在使用时可用，也会被拒绝。提前查找成功同样无法保证注册表变更后的可用性。
+
+**在共享 schema 中保留候选描述。** 注册时读取描述会使结果依赖声明顺序。保持描述同步需要额外的更新协调；工具选择公开 id。
+
+## 后果
+
+未知或无法加载的目标会使选中它的委派失败，不残留子 Agent 或 Session。未使用的无效引用仍不会被发现。Agent 限制及恢复的历史过滤器约束继承的委派 schema、执行与指导文本；同级 Agent 保留各自的工具。
+
+针对性预设选择测试覆盖切换完成时的即时可见性、共享所有权与释放、限制、缺失目标及补声明后重试。Web Loader 用例覆盖 shipped 组装兼容性，headless 预设快照固定模型可见选项。历史过滤器测试直接执行子级组装，不证明冷恢复覆盖。
@@ -132,8 +132,8 @@
  en: f5d5f97a153f7c70
  zh: 3d6bc05b9eadfbc2
 /deepseek-ai-dsh-tool-subagent/known-limitations-and-deferred-work:
-  en: 8df10e04fbd2b205
-  zh: b4d906aa42bc8c53
+  en: d2daad284c68bc25
+  zh: 2f10007341188c10
 /deepseek-ai-dsh-tool-subagent/known-limitations-and-deferred-work/dev-note:
  en: e67f633dc6fe7773
  zh: 3bb0c20c93f16f98
@@ -239,6 +239,8 @@ Append-only; newly visible content follows the reusable request prefix and does
 These limits define what this tool does not return or enforce; they are current package constraints.

 - **This tool does not wait for results** — use the completion notice or child messages. Programmatic result waiting belongs to the subagent service.
+- **Preset choices omit descriptions** — `agent_preset` exposes ids and default or inheritance guidance only. The schema does not read candidate preset documents, so registration is independent of their declaration order. Use ids that convey each candidate's purpose.
+- **Preset references are checked on delegation** — Host-mounted and preset-mounted tools both resolve the target when starting a child. A target can be declared or replaced after tool registration, so loading the tool cannot establish its availability for a later call. Misspelled or unavailable ids remain undetected until selected; that call returns an error.
 - **Shipped fork tools omit model selection** — their configuration leaves `modelSelection` disabled to preserve inherited-prefix reuse. Custom fork tools may enable it under the same Session authorization and adapter validation as other delegation tools.
 - **Depth caps are fixed per instance** — another cap requires another distinctly named tool. Child personas and tools belong to the selected Agent Preset. Explicit LLM selection requires `modelSelection` and is restricted to the Session’s authorized routes, or the current parent route without an enabled policy.

@@ -239,6 +239,8 @@ Delegation depth for `subagent`: current 1, maximum 1, remaining levels 0. Do no
 这些限制说明本工具不返回或不强制执行什么；它们是当前包约束。

 - **本工具不等待结果**——使用完成通知或子任务消息。程序化结果等待由 subagent 服务提供。
+- **预设选项不含描述**——`agent_preset` 只公开 id 及默认或继承提示。schema 不读取候选预设文档，因此注册不依赖它们的声明顺序。请使用能够表达各候选用途的 id。
+- **预设引用在委派时检查**——Host 挂载和预设内挂载的工具都在启动子级时解析目标。目标可以在工具注册后声明或替换，因此加载工具无法确定后续调用时目标是否可用。拼错或不可用的 id 在被选中前不会被发现；选中它的调用会返回错误。
 - **随附 fork 工具省略模型选择**：其配置保持 `modelSelection` 关闭，以保留对继承前缀的复用。自定义 fork 工具可以启用它，并接受与其他委派工具相同的 Session 授权和适配器校验。
 - **深度上限按实例固定** — 更换上限需要另一个不同名称的工具。子级角色和工具由所选 Agent Preset 配置。显式 LLM 选择需要 `modelSelection`，并受 Session 授权路由限制，没有启用策略时只允许当前父级路由。

@@ -288,7 +288,8 @@ describe('spawn preset selection', () => {
    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'Reply with Ready.' }], source: { kind: 'user' } }))
    await agent.whenIdle()
    for (const { preset, names } of views) expect(names, `tools after selecting ${preset}`).toContain('switch_delegate')
-    const request = adapter.requests[0]
+    const request = adapter.requests.find(request => request.purpose === undefined)
+    expect(request).toBeDefined()
    expect(request?.tools?.map(tool => tool.name)).toContain('switch_delegate')
    const header = agent.session.snapshotEvents().find(event => event.type === 'request/header')
    expect(header?.data.header.tools).toEqual(request?.tools)
@@ -8,7 +8,7 @@ export const name = 'parent-agent-preset'
 export const inject = ['agentPresets']

 /**
- * Select the root Session's presets before publication checks.
+ * Select the root Session's presets before its first model request.
 * @param ctx - Snapshot composition context with the preset roster.
 * @param config - Ordered preset selections; omission selects the parent preset once.
 */