Procházet zdrojové kódy

docs(auto-review): name delegation records explicitly

Tianyi Cui před 1 měsícem
rodič
revize
2d9e3a175f

+ 2 - 2
.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md
-2026-07-25-subagent-policy-inheritance.md: ae718d66383e9ee69c5156bda0ab75a2a389f2f3
-2026-07-25-subagent-policy-inheritance.zh.md: 7a8d8c1b74a07491cbdbc3b18d242d52555f93a4
+2026-07-25-subagent-policy-inheritance.md: 8ca63bd511a275acbfda5ddee8cb50af51c348a1
+2026-07-25-subagent-policy-inheritance.zh.md: 630c69274e8e9cba07a6152395149757be3d6560

+ 1 - 1
.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md

@@ -14,7 +14,7 @@ The delegation boundary calls the shared child-agent helpers (`captureDelegatedP
 
 An inherited Auto or Full access identity becomes a `permission/preset` event, while captured sandbox and pinned approval values become source-tagged `sandbox/mode` and `approval/policy` events during the child factory's unpublished setup. The session constructor has already fixed `Session.firstLiveSeq` after the constructor seed, while `Session.inheritedEventCount` keeps the exact fork-prefix length, so the inherited facts follow fork history without changing its lineage cut. Lifecycle-local telemetry starts at `firstLiveSeq`, so it excludes the constructor seed and includes these unpublished-setup events. Existing last-event-wins folds therefore make the delegation snapshot beat stale fork history and let a later child switch beat the snapshot. A grandchild folds its parent's logged state, so the rule composes without another inheritance mechanism.
 
-Auto review does not turn that inherited preset event into an authorization receipt. Each child call is classified again: ordinary project-local work is low risk and allowed, medium-risk work requires explicit authorization naming its action, exact target and scope in the child's creation prompt or an authenticated human/direct-parent message, with no unresolved conflict, while high-risk work is always denied. `parentSession`, the creation prompt, and existing `agent-message.senderSessionId` are sufficient to recover that context across one-shot, continuable, and cold-resume paths; no parent call id, parsed task metadata, delegation provenance, review receipt, or Session-format migration is introduced.
+Auto review does not turn that inherited preset event into an authorization receipt. Each child call is classified again: ordinary project-local work is low risk and allowed, medium-risk work requires explicit authorization naming its action, exact target and scope in the child's creation prompt or an authenticated human/direct-parent message, with no unresolved conflict, while high-risk work is always denied. `parentSession`, the creation prompt, and existing `agent-message.senderSessionId` are sufficient to recover that context across one-shot, continuable, and cold-resume paths; no parent call id, parsed task metadata, delegation records, review receipt, or Session-format migration is introduced.
 
 Ordinary session appends validate the inherited events before publication, and persistence captures the complete unpublished log when the session is announced. Any materialized child log therefore stores the inherited events with its first batch; there is no second policy store, schema field, or query index. The `source: 'delegation'` marker lets approval narration distinguish inheritance from a child-side user switch.
 

+ 1 - 1
.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.zh.md

@@ -14,7 +14,7 @@ Auto 或 Full access 预设身份以及沙箱与审批覆盖项都是按会话
 
 继承的 Auto 或 Full access 身份会成为一条 `permission/preset` 事件,捕获的沙箱值与钉定的审批值则会在子 agent 工厂的未发布设置阶段成为带来源标记的 `sandbox/mode` 与 `approval/policy` 事件。会话构造函数已把 `Session.firstLiveSeq` 固定在 constructor seed 之后,而 `Session.inheritedEventCount` 保留精确的 fork 前缀长度,因此继承事实会排在 fork 历史之后,却不改变其谱系 cut。生命周期本地遥测从 `firstLiveSeq` 开始,因此排除 constructor seed,并包含这些未发布设置事件。因此,既有的末事件胜出折叠会让委派快照压过陈旧的 fork 历史,并让子 agent 后续的切换压过该快照。孙代 agent 会折叠其父级已记录的状态,因此无需另一套继承机制即可组合此规则。
 
-Auto review 不会把这条继承的 preset 事件变成授权回执。每次 child 调用仍会重新分类:普通项目内工作为低风险并直接允许;中风险工作必须在 child 创建 prompt 或已核验的 human/直接父级消息中得到点名动作、准确目标和范围的明确授权,且不存在未解决冲突;高风险工作始终拒绝。`parentSession`、创建 prompt 与既有 `agent-message.senderSessionId` 足以在 one-shot、continuable 与 cold resume 路径中恢复这份上下文;不会新增父 call id、解析后的任务 metadata、delegation provenance、review receipt 或 Session format migration。
+Auto review 不会把这条继承的 preset 事件变成授权回执。每次 child 调用仍会重新分类:普通项目内工作为低风险并直接允许;中风险工作必须在 child 创建 prompt 或已核验的 human/直接父级消息中得到点名动作、准确目标和范围的明确授权,且不存在未解决冲突;高风险工作始终拒绝。`parentSession`、创建 prompt 与既有 `agent-message.senderSessionId` 足以在 one-shot、continuable 与 cold resume 路径中恢复这份上下文;不会新增父 call id、解析后的任务 metadata、委派记录、review receipt 或 Session format migration。
 
 普通的会话追加会在发布前校验继承事件,持久化层则在会话公布时捕获完整的未发布日志。因此,任何已物化的子 agent 日志都会在首批数据中存下继承事件;不存在第二套策略存储、schema 字段或查询索引。`source: 'delegation'` 标记让审批叙述能够区分继承与子 agent 侧的用户切换。
 

+ 2 - 2
.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-28-auto-review.md
-2026-08-28-auto-review.md: 1468cbe5c59789921f3d147830e474aa54bef584
-2026-08-28-auto-review.zh.md: ee9763e371a47c9a5c5ab828b66eecccfa57954d
+2026-08-28-auto-review.md: 06925b9cd69395a980a13fb7307b82ea42bfdf30
+2026-08-28-auto-review.zh.md: f2052766ed89d04ed984cc21bb1cd914ec5c5348

+ 1 - 1
.agents/notes/implemented/feature/2026-08-28-auto-review.md

@@ -60,7 +60,7 @@ The permission owner publishes one complete process catalog through generated `p
 
 Auto appears with a superscript `EXP` badge. Both visible current-session pickers require the experimental confirmation; explicit `/permission auto` is already consent. The composer uses the generic Menu's existing portal placement to stay within the viewport while keeping its 218–360px bounds. The slash popup keeps `min(220px, 100%)` with `max-width: 100%`, including when a narrow composer collapses its trigger.
 
-The [delegation-time policy capture](2026-07-25-subagent-policy-inheritance.md) records Auto or Full access before the first await and appends that existing preset event after fork seeding and sandbox/approval overrides. One-shot and continuable creation share the rule; cold resume reads only the child log. Later parent switches do not alter that child, while a later child switch can win. Read Only and Workspace Write retain sandbox inheritance plus `approval: never` and may therefore remain `custom`. Auto children classify each call independently using the existing lineage and messages, without parent call metadata, delegation provenance, receipts, Header/descriptor additions, or a Session-format change. Out-of-process children retain their own permission systems after the parent delegation is allowed.
+The [delegation-time policy capture](2026-07-25-subagent-policy-inheritance.md) records Auto or Full access before the first await and appends that existing preset event after fork seeding and sandbox/approval overrides. One-shot and continuable creation share the rule; cold resume reads only the child log. Later parent switches do not alter that child, while a later child switch can win. Read Only and Workspace Write retain sandbox inheritance plus `approval: never` and may therefore remain `custom`. Auto children classify each call independently using the existing lineage and messages, without parent call metadata, delegation records, receipts, Header/descriptor additions, or a Session-format change. Out-of-process children retain their own permission systems after the parent delegation is allowed.
 
 ## Alternatives considered
 

+ 1 - 1
.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md

@@ -60,7 +60,7 @@ Permission owner 通过生成的 `permissionPresets` Remote 方法发布一份
 
 Auto 带右上标 `EXP`。两个可见当前会话选择器都要求实验确认;显式 `/permission auto` 已构成同意。Composer 使用通用 Menu 既有 portal 定位保持在视口内,同时保留 218–360px 边界。Slash popup 保留 `min(220px, 100%)` 与 `max-width: 100%`,窄 composer 将 trigger 折叠时也一样。
 
-[委派时权限捕获](2026-07-25-subagent-policy-inheritance.zh.md)在首次 await 前记录 Auto 或 Full access,并在 fork seed 与 sandbox/approval override 之后追加该既有 preset event。单次与可继续创建共用此规则;cold resume 只读取 child 日志。后续 parent 切换不改变该 child,后续 child 自己的切换仍可胜出。Read Only 与 Workspace Write 保留 sandbox 继承加 `approval: never`,因此可能保持 `custom`。Auto child 使用既有 lineage 与消息独立分类每次调用,不增加父 call metadata、delegation provenance、receipt、Header/descriptor 字段或 Session format。进程外 child 在父委派获准后保留自己的权限系统。
+[委派时权限捕获](2026-07-25-subagent-policy-inheritance.zh.md)在首次 await 前记录 Auto 或 Full access,并在 fork seed 与 sandbox/approval override 之后追加该既有 preset event。单次与可继续创建共用此规则;cold resume 只读取 child 日志。后续 parent 切换不改变该 child,后续 child 自己的切换仍可胜出。Read Only 与 Workspace Write 保留 sandbox 继承加 `approval: never`,因此可能保持 `custom`。Auto child 使用既有 lineage 与消息独立分类每次调用,不增加父 call metadata、委派记录、receipt、Header/descriptor 字段或 Session format。进程外 child 在父委派获准后保留自己的权限系统。
 
 ## 考虑过的替代方案
 

+ 2 - 2
docs/subsystems/subagent.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
-subagent.md: ed47512cc62653a8e6abf690b87798077650fcb2
-subagent.zh.md: 8b9b7bed96e5252805027d8c0f4e4f0e80966914
+subagent.md: ae04dfd06cfda39a5bc8d7a079c9c3097c11193f
+subagent.zh.md: 730039af6a75e070b8b7f08021353a289927449e

+ 1 - 1
docs/subsystems/subagent.md

@@ -458,7 +458,7 @@ Provider `start()` fulfills with a published run. The service mints a unique `ru
 
 The spawn and fork backends create an ordinary one-shot agent through `parent.ctx`, pass cancellation into core creation, and dispose through `AgentHandle`; a continuable child is instead created by the continuation manager through its own activation-owner scope. Provider removal blocks new starts without revoking accepted runs. Each child gets a new flat scope rather than inheriting parent registrations. Permission, depth, and fork seeding reuse existing Session vocabulary:
 
-- **Delegated permission** is captured before the first await. Auto and Full access parents append their captured `permission/preset` identity to the fresh child after fork seeding and sandbox/approval overrides. One-shot and continuable children share this path; cold resume reads only the child log. Read Only and Workspace Write retain the inherited sandbox override plus `approval: never`, so unmatched bundles remain `custom`. Each Auto child call is reviewed independently using existing `parentSession`, creation prompt, and authenticated human/direct-parent messages. The [Auto review decision](../../.agents/notes/implemented/feature/2026-08-28-auto-review.md) defines low/medium/high semantics; no delegation provenance, receipt, Header field, descriptor field, or Session format is added.
+- **Delegated permission** is captured before the first await. Auto and Full access parents append their captured `permission/preset` identity to the fresh child after fork seeding and sandbox/approval overrides. One-shot and continuable children share this path; cold resume reads only the child log. Read Only and Workspace Write retain the inherited sandbox override plus `approval: never`, so unmatched bundles remain `custom`. Each Auto child call is reviewed independently using existing `parentSession`, creation prompt, and authenticated human/direct-parent messages. The [Auto review decision](../../.agents/notes/implemented/feature/2026-08-28-auto-review.md) defines low/medium/high semantics; no delegation records, receipt, Header field, descriptor field, or Session format is added.
 
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/runtime-diagnostics/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).

+ 1 - 1
docs/subsystems/subagent.zh.md

@@ -462,7 +462,7 @@ interface SubagentProvider {
 
 spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent,将取消信号传入核心创建流程,并通过 `AgentHandle` 进行 dispose;而可继续子 agent 则由继续执行管理器通过其自己的 activation-owner 作用域创建。移除提供方会阻止新的 start,但不会撤销已接受的 run。每个子 agent 获得一个新的扁平作用域,而非继承父级注册。权限、深度与 fork 种子注入复用既有的 Session 词汇:
 
-- **委派权限**在首次 await 前捕获。Auto 与 Full access 父级在 fresh child 完成 fork seed 和 sandbox/approval override 后,追加捕获的 `permission/preset` 身份。单次与可继续 child 共用此路径;cold resume 只读取 child 日志。Read Only 与 Workspace Write 保留继承的 sandbox override 加 `approval: never`,不匹配预设的组合仍为 `custom`。每个 Auto child 调用都使用既有 `parentSession`、创建 prompt 和经过核验的 human/直接父级消息独立审查。[Auto review 决策](../../.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md)定义 low/medium/high 语义;不增加 delegation provenance、receipt、Header 字段、descriptor 字段或 Session format。
+- **委派权限**在首次 await 前捕获。Auto 与 Full access 父级在 fresh child 完成 fork seed 和 sandbox/approval override 后,追加捕获的 `permission/preset` 身份。单次与可继续 child 共用此路径;cold resume 只读取 child 日志。Read Only 与 Workspace Write 保留继承的 sandbox override 加 `approval: never`,不匹配预设的组合仍为 `custom`。每个 Auto child 调用都使用既有 `parentSession`、创建 prompt 和经过核验的 human/直接父级消息独立审查。[Auto review 决策](../../.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md)定义 low/medium/high 语义;不增加 委派记录、receipt、Header 字段、descriptor 字段或 Session format。
 
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示;缺失表示顶层深度为零,存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1,冷恢复无法降低深度,而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.zh.md#creation-and-ownership)(一个 `SessionEvent[]` 前缀,经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递,与 `ctx.agents.resume()` 使用的原语相同)。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续,[invariants](../../packages/runtime-diagnostics/invariants) 回放可以接受它(进行中的、未平衡的轮次被排除在外)。

+ 2 - 2
packages/subagent/subagent/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: 568e9afdcc6d448a8f942b536bf0573f6d4db50d
-README.zh.md: 186239da3c35403f98f478fc73cf7fef0a38b711
+README.md: 30ecc5f1257068c6ce287db901733c34daf9272d
+README.zh.md: 5c3ea2c209b1e6d032a00dedbe66e57430086972

+ 1 - 1
packages/subagent/subagent/README.md

@@ -90,7 +90,7 @@ This section explains how the service is built and where the observable behavior
 
 ### One-shot flow
 
-A request is validated against the provider's advertised capabilities, a durable descriptor is snapshotted, and the provider builds the child. Both in-process providers advertise `agentOptions`: child creation merges requested fields over the provider, model, and reasoning effort in the parent's latest logged request, falls back to creation options before the first request, and retains the configured token limit. They also snapshot delegated permission state before the first await: an Auto or Full access parent gives the child the same `permission/preset` identity, while the existing sandbox override and approval-policy pin continue to apply. Recording both identities prevents an older same-bundle fork value from winning. Auto then reviews every supported child call independently: ordinary project-local work is low risk and allowed, medium-risk work requires explicit action, exact-target and scope authorization from the existing creation prompt or an authenticated human/direct-parent message, without conflicting human limits, while high-risk work is always denied. The reviewer derives that context from `parentSession` and existing messages; delegation adds no parent call metadata, provenance, review receipt, or Session format. A route change without an explicit effort clears the inherited route-owned effort so the selected model resolves its default. DSH SDK also advertises `agentOptions` but runs a separate child runtime, so it does not inherit Auto; ACP, Codex, and Claude Code likewise retain their own permission systems after the parent delegation call passes review. On success the run is published and ownership transfers to the caller; on failure the provider rolls back every unpublished resource. The result carries the child's final output, an optional structured value, a stop reason, and an optional safe diagnostic.
+A request is validated against the provider's advertised capabilities, a durable descriptor is snapshotted, and the provider builds the child. Both in-process providers advertise `agentOptions`: child creation merges requested fields over the provider, model, and reasoning effort in the parent's latest logged request, falls back to creation options before the first request, and retains the configured token limit. They also snapshot delegated permission state before the first await: an Auto or Full access parent gives the child the same `permission/preset` identity, while the existing sandbox override and approval-policy pin continue to apply. Recording both identities prevents an older same-bundle fork value from winning. Auto then reviews every supported child call independently: ordinary project-local work is low risk and allowed, medium-risk work requires explicit action, exact-target and scope authorization from the existing creation prompt or an authenticated human/direct-parent message, without conflicting human limits, while high-risk work is always denied. The reviewer derives that context from `parentSession` and existing messages; delegation adds no parent call metadata, delegation records, review receipt, or Session format. A route change without an explicit effort clears the inherited route-owned effort so the selected model resolves its default. DSH SDK also advertises `agentOptions` but runs a separate child runtime, so it does not inherit Auto; ACP, Codex, and Claude Code likewise retain their own permission systems after the parent delegation call passes review. On success the run is published and ownership transfers to the caller; on failure the provider rolls back every unpublished resource. The result carries the child's final output, an optional structured value, a stop reason, and an optional safe diagnostic.
 
 ### Continuable flow
 

+ 1 - 1
packages/subagent/subagent/README.zh.md

@@ -90,7 +90,7 @@ kind: "package-reference"
 
 ### 一次性流程
 
-请求先对照提供方声明的能力进行校验,随后对持久化描述符做快照,再由提供方构建子 agent。两个进程内提供方都声明 `agentOptions`:创建子级时把请求字段叠加到父级最新已记录请求的提供方、模型与推理强度之上;父级还没有请求时回退到创建选项,并保留配置的 token 上限。它们还会在第一次 await 前快照委派权限状态:Auto 或 Full access 父级让子级获得相同的 `permission/preset` 身份,而既有沙箱覆盖与审批策略固定仍然生效;同时记录这两个身份可防止 fork 中更早的同旋钮组合身份胜出。Auto 随后会独立审查 child 的每个受支持调用:普通项目内工作为低风险并直接允许;中风险工作必须在既有创建 prompt 或已核验的 human/直接父级消息中获得动作、准确目标和范围的明确授权,且不与 human 限制冲突;高风险工作始终拒绝。reviewer 从 `parentSession` 与既有消息派生这份上下文;委派不会新增父 call metadata、provenance、review receipt 或 Session format。更改路由而不显式指定推理强度时,会清除继承的路由自有强度,使所选模型解析自己的默认值。DSH SDK 也声明 `agentOptions`,但会运行独立子运行时,因此不继承 Auto;ACP、Codex 与 Claude Code 同样在父级委派调用通过审查后保留各自的权限系统。成功时运行被发布、所有权转移给调用方;失败时提供方回滚每个尚未发布的资源。结果携带子 agent 的最终输出、可选的结构化值、停止原因与可选的安全诊断。
+请求先对照提供方声明的能力进行校验,随后对持久化描述符做快照,再由提供方构建子 agent。两个进程内提供方都声明 `agentOptions`:创建子级时把请求字段叠加到父级最新已记录请求的提供方、模型与推理强度之上;父级还没有请求时回退到创建选项,并保留配置的 token 上限。它们还会在第一次 await 前快照委派权限状态:Auto 或 Full access 父级让子级获得相同的 `permission/preset` 身份,而既有沙箱覆盖与审批策略固定仍然生效;同时记录这两个身份可防止 fork 中更早的同旋钮组合身份胜出。Auto 随后会独立审查 child 的每个受支持调用:普通项目内工作为低风险并直接允许;中风险工作必须在既有创建 prompt 或已核验的 human/直接父级消息中获得动作、准确目标和范围的明确授权,且不与 human 限制冲突;高风险工作始终拒绝。reviewer 从 `parentSession` 与既有消息派生这份上下文;委派不会新增父 call metadata、委派记录、review receipt 或 Session format。更改路由而不显式指定推理强度时,会清除继承的路由自有强度,使所选模型解析自己的默认值。DSH SDK 也声明 `agentOptions`,但会运行独立子运行时,因此不继承 Auto;ACP、Codex 与 Claude Code 同样在父级委派调用通过审查后保留各自的权限系统。成功时运行被发布、所有权转移给调用方;失败时提供方回滚每个尚未发布的资源。结果携带子 agent 的最终输出、可选的结构化值、停止原因与可选的安全诊断。
 
 ### 可继续流程