dsh-plugin-guide 0.3.27 → 0.3.29

package/references/official-docs/docs/persistence-changes/2026-09-13-working-directory.i18n.yaml

@@ -0,0 +1,28 @@
+# Bilingual-pair consistency record for 2026-09-13-working-directory.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 docs/persistence-changes/2026-09-13-working-directory.md
+/:
+  en: 3d5a424ae7d7e46b
+  zh: c22a8e4a62d8cc1a
+/2026-09-13-working-directory:
+  en: 2ae6bda09b2fb22b
+  zh: 45204fff7e931e07
+/2026-09-13-working-directory/summary:
+  en: ac7c5d84de3040fa
+  zh: 85af1f5ea31e8956
+/2026-09-13-working-directory/table-of-contents:
+  en: 6cf314a069ceb451
+  zh: 9adff678e9ecab3b
+/2026-09-13-working-directory/declaration:
+  en: 6907136f28e48c90
+  zh: 02f8298485f3d8e7
+/2026-09-13-working-directory/compatibility:
+  en: 3dae5b1bf48b0435
+  zh: aea832a92da37dc4
+/2026-09-13-working-directory/verification:
+  en: ff3444e53a105e07
+  zh: 7a77d20c75e59a59
+/2026-09-13-working-directory/dev-note:
+  en: b75c8458928b72b9
+  zh: 003ba4e17b4b5269

package/references/official-docs/docs/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/references/official-docs/docs/persistence-changes/2026-09-13-working-directory.schema.json

@@ -0,0 +1,76 @@
+{
+  "formatVersion": 1,
+  "roots": [
+    {
+      "key": "event:working-directory/change",
+      "kind": "event",
+      "event": "working-directory/change",
+      "surface": false,
+      "digest": "124aa62078ca3311353b39cc3bf6c75da281338be6bbf672f8b361d828cddca3",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "cwd",
+                "type": 2,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "literal",
+            "value": "working-directory/change"
+          }
+        ]
+      }
+    }
+  ],
+  "types": []
+}

package/references/official-docs/docs/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/references/official-docs/docs/persistence-changes/2026-09-16-session-format-v4.i18n.yaml

@@ -18,11 +18,11 @@
   en: 6907136f28e48c90
   zh: 02f8298485f3d8e7
 /2026-09-16-session-format-v4/compatibility:
-  en: 62d76f6b66d04dc4
-  zh: 736b1b7cc2f6084f
+  en: 0fc8ce7241c4ecbe
+  zh: d3f2c2812ecaca38
 /2026-09-16-session-format-v4/verification:
-  en: f917c71292c98b17
-  zh: 974c65afde0adb22
+  en: 94b3c1b1d07bc87d
+  zh: af7ec37007c62ecb
 /2026-09-16-session-format-v4/dev-note:
   en: b75c8458928b72b9
   zh: 003ba4e17b4b5269

package/references/official-docs/docs/persistence-changes/2026-09-16-session-format-v4.md

@@ -93,7 +93,7 @@ The [native V4 validation decision](../../.agents/notes/implemented/architecture
 
 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 a version bump instead of being classified as an ordinary optional-field addition.
+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.
 
@@ -108,7 +108,7 @@ The PTC producer writes `source.kind: 'ptc-mode'`. The V3-to-V4 edge retains `to
 
 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 pass 65 tests across three files. The generated field retains optional `never`; permitting an optional string produces a version-bump diagnostic while the native reader still refuses the retired key.
+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.
 

package/references/official-docs/docs/persistence-changes/2026-09-16-session-format-v4.zh.md

@@ -93,7 +93,7 @@ changes:
 
 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` 键记录为禁止字段。这项声明记录已有的原生读取拒绝规则，不改变存储数据或提示词重建；以后允许该字段携带值时，必须提升格式版本，而不能归类为普通可选字段添加。
+`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 文件不会重新运行迁入边。
 
@@ -108,7 +108,7 @@ PTC 生产者写入 `source.kind: 'ptc-mode'`。V3→V4 迁入边保留 `tools-c
 
 精确切点 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`；允许可选字符串会产生必须提升版本的诊断，而原生读取方仍拒绝该退役键。
+生成的请求头保留字段回归测试以及已有的退役语法和 Session surface 测试曾通过三个文件中的 65 项测试。生成字段保留可选的 `never`；当前分类器将允许可选字符串标记为需要兼容性评审，而原生读取方仍拒绝该退役键。
 
 Producer-source 与 request-input 检查共通过 12 个文件中的 447 项测试，覆盖 provider 等价性、仅供请求使用的输入的类型拒绝、user 归属保留、source 迁移及原生 source 准入。与 tool-role 父层的生成目录相比，有四个 root 发生变化，447 个类型指纹保持不变。
 

package/references/official-docs/docs/persistence-changes/2026-09-19-external-subagent-catalog.i18n.yaml

@@ -0,0 +1,28 @@
+# Bilingual-pair consistency record for 2026-09-19-external-subagent-catalog.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 docs/persistence-changes/2026-09-19-external-subagent-catalog.md
+/:
+  en: 3d5a424ae7d7e46b
+  zh: c22a8e4a62d8cc1a
+/2026-09-19-external-subagent-catalog:
+  en: 81860767c8b7e373
+  zh: 4fcb6866cd8d8696
+/2026-09-19-external-subagent-catalog/summary:
+  en: 02848a04a27423e5
+  zh: 8fa393f6130f3212
+/2026-09-19-external-subagent-catalog/table-of-contents:
+  en: 6cf314a069ceb451
+  zh: 9adff678e9ecab3b
+/2026-09-19-external-subagent-catalog/declaration:
+  en: 6907136f28e48c90
+  zh: 02f8298485f3d8e7
+/2026-09-19-external-subagent-catalog/compatibility:
+  en: ae460855a021bf2b
+  zh: 3789da36fc4202fd
+/2026-09-19-external-subagent-catalog/verification:
+  en: f629646a19627773
+  zh: 7538959cb86407a1
+/2026-09-19-external-subagent-catalog/dev-note:
+  en: b75c8458928b72b9
+  zh: 003ba4e17b4b5269

package/references/official-docs/docs/persistence-changes/2026-09-19-external-subagent-catalog.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-19-external-subagent-catalog
+
+English | [中文](2026-09-19-external-subagent-catalog.zh.md)
+
+## Summary
+
+Add external mode to parent catalog entries for children without a local Session.
+
+## 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-19-external-subagent-catalog
+baseline: false
+changes:
+  - root: "event:subagent/catalog"
+    previous: "2026-09-20-unknown-child-catalog"
+    after: "53750b9abf61efb7992b0aadc3e247ec927449c63266df28230fd1139f5590ac"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing version-0 and version-1 one-shot and continuable facts remain valid; version 1 also retains unknown mode. New external executions write payload version 2 with mode external, without a separate marker. Creation writes one membership fact; execution and cleanup do not update it. Duplicate child ids remain invalid. This does not change released generations or the Session format version.
+
+<a id="verification"></a>
+## Verification
+
+Focused catalog, external activation, native V4 restoration, client navigation, and control-tool tests passed. They cover external membership, historical local modes, invalid marker rejection, non-navigable external leaves, and duplicate-child rejection.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/references/official-docs/docs/persistence-changes/2026-09-19-external-subagent-catalog.schema.json

@@ -0,0 +1,290 @@
+{
+  "formatVersion": 2,
+  "roots": [
+    {
+      "key": "event:subagent/catalog",
+      "kind": "event",
+      "event": "subagent/catalog",
+      "surface": false,
+      "digest": "53750b9abf61efb7992b0aadc3e247ec927449c63266df28230fd1139f5590ac",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 17,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 18,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "union",
+            "types": [
+              2,
+              7,
+              9,
+              12,
+              14,
+              15
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 11,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "external"
+          },
+          {
+            "kind": "literal",
+            "value": 2
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 16,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog"
+          }
+        ]
+      }
+    }
+  ],
+  "types": []
+}

package/references/official-docs/docs/persistence-changes/2026-09-19-external-subagent-catalog.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-19-external-subagent-catalog
+
+[English](2026-09-19-external-subagent-catalog.md) | 中文
+
+## 概述
+
+为父级目录中没有本地 Session 的子级添加 external 模式。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-19-external-subagent-catalog
+baseline: false
+changes:
+  - root: "event:subagent/catalog"
+    previous: "2026-09-20-unknown-child-catalog"
+    after: "53750b9abf61efb7992b0aadc3e247ec927449c63266df28230fd1139f5590ac"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有 version-0 和 version-1 的 one-shot 与 continuable 事实仍然有效；version 1 还保留 unknown 模式。新外部执行写入 payload version 2 和 external 模式，不使用单独的标记。创建时写入一次成员事实，执行和清理不更新它。重复的子 id 仍然无效。这不改变已发布的代际或 Session 格式版本。
+
+<a id="verification"></a>
+## 验证
+
+定向 catalog、外部 activation、原生 V4 恢复、客户端导航和控制工具测试通过，覆盖外部成员关系、历史本地模式、非法标记拒绝、不可导航的外部叶节点，以及重复子级拒绝。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。