dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/persistence-changes/2026-10-13-liveshare-share-viewer-principal.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-13-liveshare-share-viewer-principal
+
+English | [中文](2026-10-13-liveshare-share-viewer-principal.zh.md)
+
+## Summary
+
+Adds the LiveShare share-viewer principal, including the Relay-asserted display name when available, to the user-rpc message source of prompts a share reader submits.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-13-liveshare-share-viewer-principal
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+The share-viewer variant is written only for a prompt that a LiveShare share reader's Peer submits; owner prompts still omit principal, so their sources and every existing Session log are unchanged. The value carries the share id and the Relay-asserted provider, tenant, and subject ids. It also carries an optional display name when the Relay asserts one, for attribution only; credentials and avatars are never persisted, and authorization still uses the identity triple. Readers that do not know the optional field keep showing the durable subject id. The LiveShare host consumes it in two places: the `agent/pre-step` admission check re-reads the Relay's grant for every entering message whose principal is a share viewer, and rejects the step when that grant no longer holds; the same step records, in memory for that turn only, that the running turn was viewer-started, which confines that turn to the shared tool surface and leaves an owner-started turn on the Session's native tools. That marker is never appended to the Session log and is recomputed from the next admitted step. A build without LiveShare keeps the message an ordinary user message because the kind stays 'user', and a principal kind this package does not drive is left to whoever drives it. A current reader of an older log finds no share-viewer principal and admits those prompts as ordinary input, as before. The field is not part of any model request. SESSION_FORMAT_VERSION does not change.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run packages/experimental/liveshare/tests/relay-target-admission.host.spec.ts packages/experimental/liveshare/tests/relay-pre-step-admission.host.spec.ts packages/experimental/liveshare/tests/share-host-listeners.spec.ts packages/experimental/liveshare packages/experimental/liveshare-protocol: a share reader's prompt persists source.principal in agent/inbox/spliced, recovered reader input is refused at the `agent/pre-step` admission check, an admitted one enters the model, and a principal this package does not drive is left alone; the optional displayName is persisted for attribution, accepted only as a non-empty string, and missing or malformed values fall back to the subject id; 35 tests passed plus the two-package LiveShare and protocol suites.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-13-liveshare-share-viewer-principal.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-13-liveshare-share-viewer-principal
+
+[English](2026-10-13-liveshare-share-viewer-principal.md) | 中文
+
+## 概述
+
+为分享读者提交的提示词，在 user-rpc 消息来源中加入 LiveShare 的 share-viewer principal；Relay 断言了显示名时一并保存。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-13-liveshare-share-viewer-principal
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "cdf988172b589b230f2bce868489def1bb575eb0501076ac757a8f369ac5c64e"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "70d2acdec1ebcfea56d02f7233ebb9ec0f7f494447fb952884c22c3afdc01d6f"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "2e505098f9209e52eebd577f1a6f9d4e773ec4d78987aff28a7c786442b9f54c"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-25-skill-catalog-incomplete"
+    after: "5bb231bc5afdb532a6898a20604e76bf0c1db438bfcdc17d4847dceaddc02451"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+只有 LiveShare 分享读者的 Peer 提交提示词时才写入 share-viewer 变体；所有者的提示词仍不写 principal，因此其来源与所有已有会话日志都不变。该值含分享 ID 和 Relay 断言的 provider、tenant、subject ID；Relay 断言了显示名时还包含可选的 displayName，仅供展示。凭据与头像永不持久化，授权仍只使用身份三元组；不认识该可选字段的读取方继续显示持久化的 subject id。LiveShare Host 在两个地方消费它：`agent/pre-step` 准入校验会为每条带分享查看者 principal 的进入消息重新读取 Relay 授权，授权不再成立时拒绝该步骤；同一步骤还会在当前轮次的内存状态中记录该轮次由查看者发起，使该轮次只运行共享工具面，而所有者自己发起的轮次保留会话原生工具。该标记不写入会话日志，并从下一个准入步骤重新计算。未装 LiveShare 的构建因 kind 仍为 'user' 而照常把它当作普通用户消息；本包不驱动的 principal 种类交由驱动它的插件处理。当前读取方读取旧日志时找不到 share-viewer principal，与以往一样把这些提示词当作普通输入放行。该字段不进入任何模型请求。SESSION_FORMAT_VERSION 不变。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/experimental/liveshare/tests/relay-target-admission.host.spec.ts packages/experimental/liveshare/tests/relay-pre-step-admission.host.spec.ts packages/experimental/liveshare/tests/share-host-listeners.spec.ts packages/experimental/liveshare packages/experimental/liveshare-protocol：分享读者的提示词在 agent/inbox/spliced 中持久化 source.principal，恢复的读者输入在 `agent/pre-step` 准入校验中被拒绝，已准入的输入进入模型，本包不驱动的 principal 种类不受影响；可选 displayName 仅用于展示，只接受非空字符串，缺失或非法值回退 subject id；35 个测试通过，另有 LiveShare 与协议两个包的全量测试。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-19-session-team-mode.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-19-session-team-mode
+
+English | [中文](2026-10-19-session-team-mode.zh.md)
+
+## Summary
+
+Records the root Session’s Agent Teams selection with the required team/mode event.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-19-session-team-mode
+baseline: false
+changes:
+  - root: "event:team/mode"
+    previous: null
+    after: "920d87e22b7409bcc7224f8b1dc7f5101c33574c75627c65baab12b85cc96e75"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing V4 logs remain readable. Without a selection, historical tasks enable Team; without historical tasks it remains disabled. Readers predating team/mode refuse the unknown required discriminator, so they cannot silently restore the wrong mode. Ordinary forks ignore inherited mode selections and start disabled. No existing payload or Session header version changes.
+
+<a id="verification"></a>
+## Verification
+
+197 focused Team, tool, model-menu and client tests passed; the Web mode and task-board scenario passed 8 tests. The authored team-session-mode headless and TypeScript SDK snapshots exercise on/off commands; Python SDK raw-event projection retains both selections.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-19-session-team-mode.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-19-session-team-mode
+
+[English](2026-10-19-session-team-mode.md) | 中文
+
+## 概述
+
+通过必读的 team/mode 事件记录根 Session 的智能体团队选择。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-19-session-team-mode
+baseline: false
+changes:
+  - root: "event:team/mode"
+    previous: null
+    after: "920d87e22b7409bcc7224f8b1dc7f5101c33574c75627c65baab12b85cc96e75"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有 V4 日志仍可读取。没有显式选择时，历史任务使 Team 开启；没有历史任务时保持关闭。旧读取器拒绝未知的必读 team/mode 判别值，避免静默恢复错误模式。普通分叉忽略继承的模式选择，初始保持关闭。不修改已有载荷或 Session 头部版本。
+
+<a id="verification"></a>
+## 验证
+
+197 个 Team、工具、模型菜单和客户端定向测试通过；Web 开关与任务板场景的 8 个测试通过。team-session-mode 的 headless 和 TypeScript SDK 人工编写快照覆盖开关命令；Python SDK 原始事件投影保留两次选择。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-22-action-card-status.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-22-action-card-status
+
+English | [中文](2026-10-22-action-card-status.zh.md)
+
+## Summary
+
+Adds action-card status attribution to logged model context.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-22-action-card-status
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing messages and records are unchanged. Readers without the action-card plugin preserve the new action-cards source kind and its JSON metadata and derive the recorded text as ordinary context. Only the producer uses the through sequence, to acknowledge delivered decisions; it grants no authority and does not change replay interpretation.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run on the action-cards, creation-recommendations, client-ui-action-cards and client-ui-creation-recommendations tests: 120 tests passed with 100% coverage of their sources. The Web creation-recommendations replay logs the status notice of a dismissed card before the next answer.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-22-action-card-status.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-22-action-card-status
+
+[English](2026-10-22-action-card-status.md) | 中文
+
+## 概述
+
+为写入日志的模型上下文新增操作卡片状态的来源标识。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-22-action-card-status
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "b36fd842cd004b532ce96fd5d6f5be28e017eda043131aa3cf5e69edc436108e"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "5ef58f2a1bdc576c1f12fa1f4da1920ece020b13c0f991a578cddcbeb28bc5be"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "efa1a091017ce533e38b0ef3e14d11a5c102ff1793229b18dad719a4268d9adc"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-13-user-rpc-principal"
+    after: "58b122df513aeaf7ddc5783dbb1fd844e2979bb273964e30ae351a8db6510019"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有消息和记录不变。没有操作卡片插件的读取方保留新的 action-cards 来源类型及其 JSON 元数据，并把记录的文本当作普通上下文。只有写入方使用 through 序号确认已送达的决定；它不授予任何权限，也不改变回放的解释。
+
+<a id="verification"></a>
+## 验证
+
+对 action-cards、creation-recommendations、client-ui-action-cards 和 client-ui-creation-recommendations 的测试运行 pnpm exec vitest run：120 个测试通过，源码覆盖率 100%。Web creation-recommendations 回放在下一次回答之前记录了已忽略卡片的状态通知。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-25-skill-catalog-incomplete.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-25-skill-catalog-incomplete
+
+English | [中文](2026-10-25-skill-catalog-incomplete.zh.md)
+
+## Summary
+
+Adds optional incomplete: true metadata to skill-catalog message sources when discovery returns only the currently readable skills.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-25-skill-catalog-incomplete
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-22-action-card-status"
+    after: "9e8043098fb89db6d7c92a92c70146c5c8d24fa88f733c687fa29e5e7a58ab30"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-22-action-card-status"
+    after: "95acdbd066cf445d37092e5fdfe2e8717ef6ca1aed50f70e2e6037a6989a1f2f"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-22-action-card-status"
+    after: "eaa9125aec0fb28478096c46e73e21bf512ab0d84d826bfb41e7308707734cb5"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-22-action-card-status"
+    after: "39adb7fce8475af6402acd925ea79697b3341c22422ac32833d71217d84e987f"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing catalogs omit the flag and remain complete. New readers compare both entries and completeness. Older readers accept the unchanged source discriminator and entry fields, preserve the already-rendered discovery warning in message content, and ignore the optional flag. No event discriminator, required field, or Session format version changes.
+
+<a id="verification"></a>
+## Verification
+
+Focused skill-filesystem and tool-skill tests: 71 passed with 100% coverage for both changed source files. Keyless headless skill-root-isolation and skill-load snapshots: 2 passed; the isolation fixture logs the partial catalog and loads a readable skill despite a failing root.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-25-skill-catalog-incomplete.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-25-skill-catalog-incomplete
+
+[English](2026-10-25-skill-catalog-incomplete.md) | 中文
+
+## 概述
+
+当技能发现仅返回当前可读技能时，为 skill-catalog 消息来源添加可选的 incomplete: true 元数据。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-25-skill-catalog-incomplete
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-22-action-card-status"
+    after: "9e8043098fb89db6d7c92a92c70146c5c8d24fa88f733c687fa29e5e7a58ab30"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-22-action-card-status"
+    after: "95acdbd066cf445d37092e5fdfe2e8717ef6ca1aed50f70e2e6037a6989a1f2f"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-22-action-card-status"
+    after: "eaa9125aec0fb28478096c46e73e21bf512ab0d84d826bfb41e7308707734cb5"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-22-action-card-status"
+    after: "39adb7fce8475af6402acd925ea79697b3341c22422ac32833d71217d84e987f"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有目录不含此标记，仍按完整目录读取。新读取方同时比较条目与完整性。旧读取方接受未变的来源判别值与条目字段，保留消息正文中已渲染的发现警告，并忽略可选标记。不改变事件判别值、必填字段或 Session 格式版本。
+
+<a id="verification"></a>
+## 验证
+
+skill-filesystem 与 tool-skill 定向测试共 71 项通过，两个修改源文件覆盖率均为 100%。无密钥 headless skill-root-isolation 与 skill-load 快照共 2 项通过；隔离夹具记录部分目录，并在一个根失败时成功加载可读技能。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-27-retry-control-input.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-27-retry-control-input
+
+English | [中文](2026-10-27-retry-control-input.zh.md)
+
+## Summary
+
+Add the retry message source for empty Session API continuation prompts; ordinary user/message records retain the input identity and caller metadata.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-27-retry-control-input
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "1682631f010d5ea717d181ed6f4ef46cde08d92a31ab461e7e98edfc98461f85"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "510826cf4e1f9220d75c1efd90b349dd9a77fc5ba15d19e16f87e85a48db5f99"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "3bca25b2baa6b22be9b577621a7603497f40870ed88a8dac4383d37dc2bb6e18"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "50a15408d511e9be3fa93abff37a38ae770f3ab905fc6849fee0d989200d2b97"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+The retry source is producer-owned metadata on the existing empty UserMessage representation. AgentLoop, model-history derivation, and SDK prompt behavior are unchanged. Older readers preserve extensible source metadata and consume these messages through ordinary user-message admission; they may display an empty context row. Updated readers retain historical ordinary messages and hide only empty retry messages in Chat. Existing event discriminators and the current Session version remain unchanged; no new required event is introduced.
+
+<a id="verification"></a>
+## Verification
+
+The Session API suite passed 1112 tests across 51 files; continuation.ts has 100% statements, branches, functions, and lines. Chat and conversation tests passed 1875 tests across 113 files; final focused Chat and input regressions passed 96 and 31 tests. The browser continuation replay passed with an empty retry user message retained in the log, no empty Chat bubble, and normally closed turns. Build passed all 10 gates, typed lint exited 0, and doc-sync passed all 43 gates. Git comparison against the PR base confirms no AgentLoop, Core Agent, Core Session, or SDK changes.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-27-retry-control-input.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-27-retry-control-input
+
+[English](2026-10-27-retry-control-input.md) | 中文
+
+## 概述
+
+为空 Session API 继续提示词增加 retry 消息来源；普通 user/message 记录保留输入身份和调用方元数据。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-27-retry-control-input
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "1682631f010d5ea717d181ed6f4ef46cde08d92a31ab461e7e98edfc98461f85"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "510826cf4e1f9220d75c1efd90b349dd9a77fc5ba15d19e16f87e85a48db5f99"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "3bca25b2baa6b22be9b577621a7603497f40870ed88a8dac4383d37dc2bb6e18"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-27-subagent-settlement-attribution"
+    after: "50a15408d511e9be3fa93abff37a38ae770f3ab905fc6849fee0d989200d2b97"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+retry 来源是现有空 UserMessage 表示中的生产方元数据。AgentLoop、模型历史派生与 SDK 提示词行为保持不变。旧读取方保留可扩展来源元数据，并按普通用户消息准入消费；旧界面可能显示空上下文行。更新后的读取方保留历史普通消息，Chat 仅隐藏空重试消息。现有事件判别标签与当前 Session 版本不变，不新增必读事件。
+
+<a id="verification"></a>
+## 验证
+
+Session API 测试通过：51 个文件、1112 个测试，continuation.ts 的语句、分支、函数和行覆盖率均为 100%。Chat 与 conversation 测试通过：113 个文件、1875 个测试；最终定向 Chat 与输入回归分别通过 96 和 31 个测试。浏览器继续回放通过，断言日志保留空 retry 用户消息、Chat 无空气泡且轮次正常闭合。构建 10 项全部通过，类型感知 lint 退出码为 0，doc-sync 的 43 项全部通过。与 PR 基线的 Git 比较确认 AgentLoop、Core Agent、Core Session 和 SDK 无改动。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-27-subagent-settlement-attribution.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-27-subagent-settlement-attribution
+
+English | [中文](2026-10-27-subagent-settlement-attribution.zh.md)
+
+## Summary
+
+Adds optional stopReason attribution to persisted subagent settlement notices while keeping the Session format version unchanged.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-27-subagent-settlement-attribution
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "ddce54a3873dc57113b0cd38ad9b23b3c259186139e8847e5e5f415d86f52482"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "70ea8e7943c5e2d76905bcc2e694e8c3d5b138aaae3609f3e261b8d369a6e35a"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "d95c624eddecdacf1ee74356196c09d2f3fcd625714be5e852a6b643fa12a7ca"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "dcb07e04496586d2664d72dab0e94312917da56927b2a0dc3ee53d6a33e32450"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+New readers accept historical notices without stopReason and must not infer it from the English summary. Writers always record the exact captured execution stopReason. Older readers preserve additional source metadata and continue using the existing kind, notice form, summary, senderSessionId, and unchanged content; native V4 source admission validates the producer kind rather than rejecting additional attribution fields. The new metadata affects presentation only, not replay, authority, or recovery. No migration or Session version bump is required.
+
+<a id="verification"></a>
+## Verification
+
+Focused Vitest runs passed: continuation-messages.spec.ts (14 tests), external-activation.spec.ts (19 tests), continuation-messages-adapter.spec.ts (1 test), and continuation.spec.ts (166 tests), all under packages/subagent/subagent/tests. Command: node node_modules/vitest/vitest.mjs run followed by the listed owner paths. Coverage includes all five terminal reasons, historical attribution without inference, external cleanup failure retaining the captured execution reason, cold resume, and unchanged DeepSeek Messages wire content. Historical Session generations remain unchanged; affected current-format snapshot expectations include stopReason.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.