dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/extra/persistence-changes/2026-09-13-working-directory.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-13-working-directory
+
+English | [中文](2026-09-13-working-directory.zh.md)
+
+## Summary
+
+Adds durable per-Session working-directory changes.
+
+## 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-09-13-working-directory
+baseline: false
+changes:
+  - root: "event:working-directory/change"
+    previous: null
+    after: "124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing Session headers and events remain valid. The new event is required on read: older builds that do not know working-directory/change refuse logs containing it. The event vocabulary grows without changing the structural Session format.
+
+<a id="verification"></a>
+## Verification
+
+Focused working-directory and system-prompt suites pass 113 tests with per-file 100% coverage. Keyless headless replay verifies changes, recovery, user-context notices, and a stable system prompt.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-09-13-working-directory.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-13-working-directory
+
+[English](2026-09-13-working-directory.md) | 中文
+
+## 概述
+
+增加每个 Session 的持久化工作目录变更。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-13-working-directory
+baseline: false
+changes:
+  - root: "event:working-directory/change"
+    previous: null
+    after: "124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有 Session header 和事件继续有效。新事件在读取时为必需：不认识 working-directory/change 的旧版本拒绝包含它的日志。事件词汇扩展不改变 Session 的结构格式。
+
+<a id="verification"></a>
+## 验证
+
+工作目录和系统提示词定向套件通过 113 个测试，各源码文件覆盖率达到 100%。无密钥 headless 回放验证变更、恢复、用户上下文通知和稳定的系统提示词。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-09-14-image-offload.md

@@ -0,0 +1,96 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-14-image-offload
+
+English | [中文](2026-09-14-image-offload.zh.md)
+
+## Summary
+
+Record selected image occurrences with the image/offload event and derive their offloaded marks through the owning plugin's message projection.
+
+## 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-09-14-image-offload
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-11-initial"
+    after: "646c2f1d243d3a78c5bc9305786fb340f5209c48a97e65f2a186cc5195491f3f"
+    decision: same-version
+  - root: "event:assistant/attempt"
+    previous: "2026-09-11-initial"
+    after: "c80c89da83c46db7a454f034c10f969e03cfb574859c7316e5bff683f5a14b0e"
+    decision: same-version
+  - root: "event:assistant/message"
+    previous: "2026-09-11-initial"
+    after: "1169b301aaabcd992657b93ec93750c43175dda81ada5cac086f14f2eaaeed6d"
+    decision: same-version
+  - root: "event:compaction/summary"
+    previous: "2026-09-11-initial"
+    after: "f6f3f30109e9008fccf7da2a3268a63da8646b59dd7cf7b75bcd9cf08ac08a59"
+    decision: same-version
+  - root: "event:image/offload"
+    previous: null
+    after: "b222069eea2d768065161c1147b1f2c78c1b54328c84b3586ae5c8f91b8ed35e"
+    decision: same-version
+  - root: "event:llm/retry"
+    previous: "2026-09-11-initial"
+    after: "525254db03b1d1e6b74cf55aced52817568331ac1f96c0818728910b6692e336"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-11-initial"
+    after: "e0b5bf44c27bbfc6ab144239e3e4169c4d21146645e0e3121bbb359c3bc8591d"
+    decision: same-version
+  - root: "event:system/message"
+    previous: "2026-09-11-initial"
+    after: "69becfb6b2d3fd5da91518089454cae8ef33f1835637ec44dde35dd077fd4bae"
+    decision: same-version
+  - root: "event:team/message/queued"
+    previous: "2026-09-11-initial"
+    after: "443371ec07a03a82a0e93d93abca3e70b03bca55ba5b01d507030fcb66e8fbb4"
+    decision: same-version
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-12-auto-review-error-metadata"
+    after: "b33142af8176323ffbb20762541be81c1d51b60a60887803836e0b146e5bef0c"
+    decision: same-version
+  - root: "event:tool/result"
+    previous: "2026-09-12-auto-review-error-metadata"
+    after: "29af48b840d0cd9e48b6f50bf3b354f8f6340607c5b99220a48e74f60beac9e2"
+    decision: same-version
+  - root: "event:turn/end"
+    previous: "2026-09-11-initial"
+    after: "bab768260853e13a7cf2e22e65af572a1e76a5b2c01f3cdc2ce09d39b87fb70b"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-09-11-initial"
+    after: "314765bdff29c7862fb6ce820f1773563ba3094a680d163ea21180a2591b8578"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing logs remain readable. The optional offloaded image field leaves unmarked occurrences retained. The new event is required on read: older builds that do not recognize image/offload refuse those logs, and current readers require its message projection. Event envelopes and structural Session format versions are unchanged.
+
+<a id="verification"></a>
+## Verification
+
+Session and image-offload tests cover event validation, immutable message projection, missing interpreters, restore, and retry. The focused 1,144-test run and two TypeScript image snapshots pass. The Python advanced SDK recording was refreshed through the built dsh profile and includes the standalone image/offload event.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-09-14-image-offload.zh.md

@@ -0,0 +1,96 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-14-image-offload
+
+[English](2026-09-14-image-offload.md) | 中文
+
+## 概述
+
+用 image/offload 事件记录选中的图片出现位置，通过所属插件的消息投影派生 offloaded 标记。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-14-image-offload
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-11-initial"
+    after: "646c2f1d243d3a78c5bc9305786fb340f5209c48a97e65f2a186cc5195491f3f"
+    decision: same-version
+  - root: "event:assistant/attempt"
+    previous: "2026-09-11-initial"
+    after: "c80c89da83c46db7a454f034c10f969e03cfb574859c7316e5bff683f5a14b0e"
+    decision: same-version
+  - root: "event:assistant/message"
+    previous: "2026-09-11-initial"
+    after: "1169b301aaabcd992657b93ec93750c43175dda81ada5cac086f14f2eaaeed6d"
+    decision: same-version
+  - root: "event:compaction/summary"
+    previous: "2026-09-11-initial"
+    after: "f6f3f30109e9008fccf7da2a3268a63da8646b59dd7cf7b75bcd9cf08ac08a59"
+    decision: same-version
+  - root: "event:image/offload"
+    previous: null
+    after: "b222069eea2d768065161c1147b1f2c78c1b54328c84b3586ae5c8f91b8ed35e"
+    decision: same-version
+  - root: "event:llm/retry"
+    previous: "2026-09-11-initial"
+    after: "525254db03b1d1e6b74cf55aced52817568331ac1f96c0818728910b6692e336"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-11-initial"
+    after: "e0b5bf44c27bbfc6ab144239e3e4169c4d21146645e0e3121bbb359c3bc8591d"
+    decision: same-version
+  - root: "event:system/message"
+    previous: "2026-09-11-initial"
+    after: "69becfb6b2d3fd5da91518089454cae8ef33f1835637ec44dde35dd077fd4bae"
+    decision: same-version
+  - root: "event:team/message/queued"
+    previous: "2026-09-11-initial"
+    after: "443371ec07a03a82a0e93d93abca3e70b03bca55ba5b01d507030fcb66e8fbb4"
+    decision: same-version
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-12-auto-review-error-metadata"
+    after: "b33142af8176323ffbb20762541be81c1d51b60a60887803836e0b146e5bef0c"
+    decision: same-version
+  - root: "event:tool/result"
+    previous: "2026-09-12-auto-review-error-metadata"
+    after: "29af48b840d0cd9e48b6f50bf3b354f8f6340607c5b99220a48e74f60beac9e2"
+    decision: same-version
+  - root: "event:turn/end"
+    previous: "2026-09-11-initial"
+    after: "bab768260853e13a7cf2e22e65af572a1e76a5b2c01f3cdc2ce09d39b87fb70b"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-09-11-initial"
+    after: "314765bdff29c7862fb6ce820f1773563ba3094a680d163ea21180a2591b8578"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+现有日志仍可读取。可选的图片字段 offloaded 使未标记的出现位置保持保留状态。新事件在读取时必须被识别：不认识 image/offload 的旧版本拒绝读取这些日志，当前读取器需要对应的消息投影。事件信封和结构性的 Session 格式版本不变。
+
+<a id="verification"></a>
+## 验证
+
+Session 和图片省略测试覆盖事件校验、不可变消息投影、缺少处理器、恢复和重试。所选的 1,144 项测试和两项 TypeScript 图片快照通过。Python advanced SDK 录制已通过构建后的 dsh profile 刷新，包含独立的 image/offload 事件。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-09-14-workspace-changes-event.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-14-workspace-changes-event
+
+English | [中文](2026-09-14-workspace-changes-event.zh.md)
+
+## Summary
+
+Adds the log-only workspace/changes event that records the files a top-level turn changed.
+
+## 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-09-14-workspace-changes-event
+baseline: false
+changes:
+  - root: "event:workspace/changes"
+    previous: null
+    after: "e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+A new root in the same Session format version. Existing logs contain no such event and stay valid; readers that predate it refuse a log carrying it, as every required-on-read event does. The event is appended only by the Web bundle's workspace-changes plugin and is never model-visible; the Web changed-files card is its only consumer and reads the latest event per turn.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run packages/deliverables/workspace-changes packages/client/ui-deliverables: 165 tests passed; snapshots/web/changed-files-turn replays the recorded event through the Web profile.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-09-14-workspace-changes-event.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-14-workspace-changes-event
+
+[English](2026-09-14-workspace-changes-event.md) | 中文
+
+## 概述
+
+新增仅写日志的 workspace/changes 事件，记录顶层轮次改动的文件。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-14-workspace-changes-event
+baseline: false
+changes:
+  - root: "event:workspace/changes"
+    previous: null
+    after: "e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+同一 Session 格式版本内的新根类型。已有日志没有该事件，保持有效；早于它的读取方遇到它会拒绝该日志，与所有读取时必需的事件一致。该事件只由 Web bundle 的 workspace-changes 插件追加，模型永远看不到；Web 的改动文件卡片是唯一消费者，读取每轮最新的一条。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/deliverables/workspace-changes packages/client/ui-deliverables：165 个测试通过；snapshots/web/changed-files-turn 通过 Web profile 回放了记录的事件。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-09-16-session-format-v4.md

@@ -0,0 +1,120 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-16-session-format-v4
+
+English | [中文](2026-09-16-session-format-v4.zh.md)
+
+## Summary
+
+Advances the declared SessionHeader.version from 3 to 4 for the finalized V4 writer, records first-class tool-role results and producer-owned sources, and adds the forked variant to turn/end.reason. Adds developer-role Session changes with name-only tool additions bound to historical request headers, tool removals, and deferred-loading schema markers.
+
+## 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-09-16-session-format-v4
+baseline: false
+changes:
+  - root: "SessionHeader"
+    previous: "2026-09-11-initial"
+    after: "1a3440e3577382704d42a6263aa463504eb74c566734a55e9503a63efcd02445"
+    decision: version-bump
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-14-image-offload"
+    after: "1506a9b8224986c83015ae99d2cb5ede705538c58c063d6a48ef6d761a31ba6c"
+    decision: version-bump
+  - root: "event:assistant/attempt"
+    previous: "2026-09-14-image-offload"
+    after: "15d5dfdd822aa35e115afd74a8982825a493880457774e6850bc1520b50875e4"
+    decision: version-bump
+  - root: "event:assistant/message"
+    previous: "2026-09-14-image-offload"
+    after: "1033093edd0db80ff410e00830b523405e00bb0c7684948e531ff65095799625"
+    decision: version-bump
+  - root: "event:compaction/summary"
+    previous: "2026-09-14-image-offload"
+    after: "e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602"
+    decision: version-bump
+  - root: "event:developer/message"
+    previous: null
+    after: "eef4ef54dc7a133d47448a4ee822e45a351314923ef5f66db34c8b24e4b32d80"
+    decision: version-bump
+  - root: "event:request/header"
+    previous: "2026-09-11-initial"
+    after: "4208123b50df5006b181481ab45fcf1cde807b88d3fd4d340090bc2e202fac41"
+    decision: version-bump
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-14-image-offload"
+    after: "fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d"
+    decision: version-bump
+  - root: "event:system/message"
+    previous: "2026-09-14-image-offload"
+    after: "69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1"
+    decision: version-bump
+  - root: "event:team/message/queued"
+    previous: "2026-09-14-image-offload"
+    after: "21fb6a90d5068f6a0003b7ab316ed2f56342477146a65c00db0f13c4d8df667d"
+    decision: version-bump
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-14-image-offload"
+    after: "100f6dca1468538239522cde3533e5bd721d0f1a7b50bea8b0eb533ea6c96163"
+    decision: version-bump
+  - root: "event:tool/result"
+    previous: "2026-09-14-image-offload"
+    after: "7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397"
+    decision: version-bump
+  - root: "event:turn/end"
+    previous: "2026-09-14-image-offload"
+    after: "0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce"
+    decision: version-bump
+  - root: "event:user/message"
+    previous: "2026-09-14-image-offload"
+    after: "3f72db3d87a0c5c43e68be467b4cca728eaf5adc1d5d2b6975ff42bfbd961761"
+    decision: version-bump
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+The tool-role declaration changes ten event roots because inbox entries, message events, compaction summaries, title requests, team messages, and PTC dispatches embed the shared `Message` or `ContentBlock` declarations. Removing `tool-result` from that union and specializing message roles changes those reachable schemas without adding ten independent event protocols. The `turn/end` change separately records the forked reason; `SessionHeader` records the version increase.
+
+The [native V4 validation decision](../../.agents/notes/implemented/architecture/2026-09-17-native-v4-read-validation.md) owns the reader admission required by these current fields.
+
+The V3-to-V4 migration lifts released user-role tool results into tool-role messages with a required toolCallId and optional isError. Tool-result wrappers leave the content-block union. The migration preserves every admitted source event and inherited cut, and appends missing parent subagent/catalog records from retained direct-child logs in the same persistence root. Historical body restoration requires an explicit child-evidence set, including an empty set when no children are available to backfill. Missing, multiple, or unknown-version child descriptors skip that child’s backfill; conflicting identities, timestamps, or modes refuse migration without publication. Existing catalog facts remain. Historical read opens prepare the result in memory. Write opens revalidate child membership and revisions before publishing the current successor beside unchanged predecessor files. Delivery-generation checks keep historical acknowledgements from becoming active V4 watermarks. V3 readers refuse the newer generation. The finalized transition adds forked to turn/end.reason; exact-cut forks append child-owned error results and closers after the inherited marker. V4 admits checked not-started fork results with deterministic branch-specific IDs and wording; released V0–V3 validators and recorded predecessor generations remain unchanged.
+
+The `request/header` schema also records the retired `system` key as forbidden. This declaration captures the existing native-reader refusal without changing stored data or prompt reconstruction; later permitting a value requires compatibility review for a same-version change, or an explicit version bump, instead of being classified as an ordinary optional-field addition.
+
+Producer-owned sources replace released plugin wrappers through the [V3-to-V4 migration](../../packages/session/session-format-v3-to-v4/README.md#v3-to-v4-specification). The frozen rename table and collision rules preserve source fields and event coordinates; unknown producer attribution retains every own JSON property. Native read and write opens validate source fields before exposing the Session. Existing V4 files do not rerun the incoming migration edge.
+
+The core-owned user source property records the attribution-preservation policy; tmux-context qualifies its location attribution while retaining producer-local duplicate suppression. Auto Review and the compaction summarizer use request-only user inputs, removing their active source registrations without removing historical migration support. These inputs cannot be written as durable Session messages. Catalog formatVersion 2 stores the policy metadata; it does not change the Session version or rewrite frozen schema records. System, model, and tool sources retain their strict semantic rules.
+
+Developer events retain their original role and require an open step. Each addition stores toolName; developer/message.headerSeq identifies an earlier known request/header containing exactly one complete matching ToolSchema. All additions in one event share that historical header revision, while removal-only and other developer messages omit headerSeq. Native and Session admission reject absent, forward, non-header, unknown-header, ambiguous, incomplete-definition and retired inline-definition forms without interpreting unknown ignorable records or dropping unrelated JSON metadata. Same-name replacement, restart, fork, surface replacement and compaction retain historical schema identity without consulting the latest header or registry. Generic sourceEventSeqs remains independent. Developer sources use the same recorded attribution-preservation policy as user sources. The optional deferLoading marker is independent of addition history. No shipped profile emits developer records; provider serialization, automatic emission and UI support remain deferred.
+
+The PTC producer writes `source.kind: 'ptc-mode'`. The V3-to-V4 edge retains `tools-code-mode` and `tools-ptc` as historical plugin lookup keys and maps both to that current kind. The source policy reserves `ptc-mode` against attribution-only qualification.
+
+<a id="verification"></a>
+## Verification
+
+The focused Session, agent-loop, Session Controller, V4, chat-view, and compaction suites passed 1,523 tests across 63 files after integration of exact-cut forks. V4 fork tests retain original IDs and text across encoding, decoding, and restoration, reject malformed results, and validate nested inherited cuts. The tool-role migration tests and SDK snapshot refresh also passed in the originating change; the built Python runtime sdk-snapshot scenario passed, and focused pi-ai and auto-review coverage passed 351 tests with 100% coverage of the three affected modules.
+
+The generated request-header reservation regression and existing retired-syntax and Session surface tests passed 65 tests across three files. The generated field retains optional `never`; the current classifier marks permitting an optional string as requiring compatibility review, while the native reader still refuses the retired key.
+
+The producer-source and request-input checks pass 447 tests across 12 files, including provider equality, request-only type rejection, user-attribution retention, source migration, and native source admission. Comparing the generated inventories with the tool-role parent reports four changed roots and 447 unchanged type fingerprints.
+
+The focused Session, V4 and request-input suite passes 884 tests across 38 files, with 100% statements, branches, functions and lines for the complete V3-to-V4 package and Session surface. Coverage includes historical same-name schema binding, compound additions/removals, malformed references and definitions, unknown-header refusal, opaque unknown records, metadata preservation, forks, replacements, compaction references, and native plain/zstd read/write admission without rewriting the generation.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-09-16-session-format-v4.zh.md

@@ -0,0 +1,120 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-16-session-format-v4
+
+[English](2026-09-16-session-format-v4.md) | 中文
+
+## 概述
+
+将 已定稿 V4 写入方声明的 SessionHeader.version 从 3 推进到 4，记录一等 tool 角色结果与生产者拥有的 source，并向 turn/end.reason 添加 forked 变体。 添加 developer 角色的 Session 变更，工具添加仅记录名称并绑定历史请求头，另含工具移除和延迟加载模式标记。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-16-session-format-v4
+baseline: false
+changes:
+  - root: "SessionHeader"
+    previous: "2026-09-11-initial"
+    after: "1a3440e3577382704d42a6263aa463504eb74c566734a55e9503a63efcd02445"
+    decision: version-bump
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-14-image-offload"
+    after: "1506a9b8224986c83015ae99d2cb5ede705538c58c063d6a48ef6d761a31ba6c"
+    decision: version-bump
+  - root: "event:assistant/attempt"
+    previous: "2026-09-14-image-offload"
+    after: "15d5dfdd822aa35e115afd74a8982825a493880457774e6850bc1520b50875e4"
+    decision: version-bump
+  - root: "event:assistant/message"
+    previous: "2026-09-14-image-offload"
+    after: "1033093edd0db80ff410e00830b523405e00bb0c7684948e531ff65095799625"
+    decision: version-bump
+  - root: "event:compaction/summary"
+    previous: "2026-09-14-image-offload"
+    after: "e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602"
+    decision: version-bump
+  - root: "event:developer/message"
+    previous: null
+    after: "eef4ef54dc7a133d47448a4ee822e45a351314923ef5f66db34c8b24e4b32d80"
+    decision: version-bump
+  - root: "event:request/header"
+    previous: "2026-09-11-initial"
+    after: "4208123b50df5006b181481ab45fcf1cde807b88d3fd4d340090bc2e202fac41"
+    decision: version-bump
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-14-image-offload"
+    after: "fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d"
+    decision: version-bump
+  - root: "event:system/message"
+    previous: "2026-09-14-image-offload"
+    after: "69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1"
+    decision: version-bump
+  - root: "event:team/message/queued"
+    previous: "2026-09-14-image-offload"
+    after: "21fb6a90d5068f6a0003b7ab316ed2f56342477146a65c00db0f13c4d8df667d"
+    decision: version-bump
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-14-image-offload"
+    after: "100f6dca1468538239522cde3533e5bd721d0f1a7b50bea8b0eb533ea6c96163"
+    decision: version-bump
+  - root: "event:tool/result"
+    previous: "2026-09-14-image-offload"
+    after: "7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397"
+    decision: version-bump
+  - root: "event:turn/end"
+    previous: "2026-09-14-image-offload"
+    after: "0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce"
+    decision: version-bump
+  - root: "event:user/message"
+    previous: "2026-09-14-image-offload"
+    after: "3f72db3d87a0c5c43e68be467b4cca728eaf5adc1d5d2b6975ff42bfbd961761"
+    decision: version-bump
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+工具角色声明会改变十个事件根，因为 inbox 条目、消息事件、compaction 摘要、标题请求、团队消息和 PTC dispatch 嵌入了共享的 `Message` 或 `ContentBlock` 声明。从联合中移除 `tool-result` 并按角色细化消息，会改变这些可达 schema，并非新增十套独立事件协议。`turn/end` 的变更单独记录 forked reason；`SessionHeader` 记录版本递增。
+
+[原生 V4 校验决策](../../.agents/notes/implemented/architecture/2026-09-17-native-v4-read-validation.zh.md) 负责说明这些当前字段所需的读取接纳规则。
+
+V3-to-V4 迁移将已发布的 user 角色工具结果提升为 tool 角色消息，包含必需的 toolCallId 和可选的 isError。工具结果包装不再属于内容块联合。迁移保留每个已接纳源事件和继承切分点，并根据同一持久化根目录中保留的直属子 Session 日志追加缺失的父级 subagent/catalog 记录。历史正文恢复要求显式提供子日志证据集合；没有可供补全的子日志时也须传入空集合。子日志的 descriptor 缺失、多条或版本未知时，跳过该子项的补全；身份、时间戳或模式冲突会拒绝迁移且不发布后继。已有 catalog 事实保持不变。历史读取打开在内存中准备结果。写入打开在重新校验子项成员与修订后，将当前后继发布到未修改的前代文件旁。Delivery generation 校验防止历史确认成为有效的 V4 水位。V3 读取方拒绝更新的 generation。已定稿迁移向 turn/end.reason 添加 forked。精确切点的 fork 在继承标记之后追加子会话自有的错误结果和结束事件。V4 接纳经过校验、使用确定性分支 ID 和文案的未启动 fork 结果；已发布的 V0–V3 校验器和已记录的前驱代际保持不变。
+
+`request/header` schema 还将退役的 `system` 键记录为禁止字段。这项声明记录已有的原生读取拒绝规则，不改变存储数据或提示词重建；以后允许该字段携带值时，同版本变更必须经过兼容性评审，或显式提升格式版本，而不能归类为普通可选字段添加。
+
+生产者拥有的 source 通过 [V3→V4 迁移](../../packages/session/session-format-v3-to-v4/README.zh.md#v3-to-v4-specification)替代已发布的 plugin wrapper。冻结的重命名表和冲突规则保留 source 字段与事件坐标；未知生产者归属保留每个自有 JSON 属性。原生读取和写入打开在公开 Session 之前校验 source 字段。已有 V4 文件不会重新运行迁入边。
+
+核心拥有的 user source 属性记录归属保留策略；tmux-context 将位置归属标记为符合条件，同时保留生产者内部的去重。Auto Review 和压缩摘要器使用仅供请求使用的 user 输入，移除其活动 source 注册，同时保留历史迁移支持。这些输入不能写为持久化 Session 消息。目录 formatVersion 2 保存策略元数据，不改变 Session 版本，也不重写冻结的 schema 记录。System、model 和 tool source 保持严格的语义规则。
+
+Developer 事件保留原始角色，并要求处于打开的 step。每个添加块存储 toolName；developer/message.headerSeq 指向更早且已知的 request/header，其中必须恰好包含一个完整同名 ToolSchema。同一事件的所有添加共用该历史请求头版本，仅移除或其他 developer 消息省略 headerSeq。原生与 Session 接纳拒绝缺失、前向、非请求头、未知请求头、歧义、不完整定义及已退役内嵌定义形式，不解释未知且可忽略的记录，也不丢弃无关 JSON 元数据。同名替换、重启、fork、surface 替换和压缩保留历史模式身份，不查询最新请求头或注册表。通用 sourceEventSeqs 保持独立。Developer source 使用与 user source 相同的已记录归属保留策略。可选的 deferLoading 标记独立于添加历史。已提供的 profile 不发出 developer 记录；提供方序列化、自动发出及 UI 支持仍未启用。
+
+PTC 生产者写入 `source.kind: 'ptc-mode'`。V3→V4 迁入边保留 `tools-code-mode` 和 `tools-ptc` 作为历史 plugin 查找键，并将二者映射到该当前 kind。source 策略保留 `ptc-mode`，不允许将其声明为仅用于归属。
+
+<a id="verification"></a>
+## 验证
+
+精确切点 fork 集成后，聚焦的 Session、agent-loop、Session Controller、V4、chat-view 和 compaction 测试共 63 个文件、1,523 个测试通过。V4 fork 测试确认编码、解码和恢复保留原始 ID 与文本，拒绝格式错误的结果，并验证嵌套继承切点。工具角色迁移测试和 SDK 快照刷新也在原始变更中通过；构建后的 Python runtime sdk-snapshot 场景通过，定向 pi-ai 与 auto-review 覆盖率检查通过 351 个测试，三个受影响模块覆盖率均为 100%。
+
+生成的请求头保留字段回归测试以及已有的退役语法和 Session surface 测试曾通过三个文件中的 65 项测试。生成字段保留可选的 `never`；当前分类器将允许可选字符串标记为需要兼容性评审，而原生读取方仍拒绝该退役键。
+
+Producer-source 与 request-input 检查共通过 12 个文件中的 447 项测试，覆盖 provider 等价性、仅供请求使用的输入的类型拒绝、user 归属保留、source 迁移及原生 source 准入。与 tool-role 父层的生成目录相比，有四个 root 发生变化，447 个类型指纹保持不变。
+
+聚焦的 Session、V4 和 request-input 测试共 38 个文件、884 项通过，完整 V3-to-V4 包与 Session surface 的语句、分支、函数及行覆盖率均为 100%。覆盖历史同名模式绑定、复合添加/移除、畸形引用与定义、未知请求头拒绝、未知记录不透明性、元数据保留、fork、替换、压缩引用，以及不重写 generation 的原生 plain/zstd 读写接纳。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。