dsh-plugin-dev-kb 1.4.0 → 1.5.2

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-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/kb/extra/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/kb/extra/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/kb/extra/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>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-09-30-job-session-lifecycle.md

@@ -0,0 +1,52 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-30-job-session-lifecycle
+
+English | [中文](2026-09-30-job-session-lifecycle.zh.md)
+
+## Summary
+
+Records owned job registration and settlement with one unique JobId, original timestamps, creating tool calls, and producer completion reports.
+
+## 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-30-job-session-lifecycle
+baseline: false
+changes:
+  - root: "event:job/registered"
+    previous: null
+    after: "f5520c1d261ca86ea03735799c311a0a9ede8babb588cf0a65422576d2ee0ad1"
+    decision: same-version
+  - root: "event:job/settled"
+    previous: null
+    after: "edd37b1e4974af648633014435572089b1e8fb71910468a0767a7e28fdd22abf"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Adds required job event kinds without changing the Session envelope. New JobIds use a kind-prefixed UUID for both live controls and durable pairing; historical sessions receive no fabricated job history. Older builds reject unknown required events. producerReported describes completion-promise fulfillment, not verified resource release.
+
+<a id="verification"></a>
+## Verification
+
+Registry and snapshot-normalizer tests cover causal order and unique JobIds. CLI and SDK snapshots verify registration, settlement, and notices during execution; the [job lifecycle contract](../subsystems/jobs.md#session-lifecycle-records) allows incomplete terminal history during application teardown.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-09-30-job-session-lifecycle.zh.md

@@ -0,0 +1,52 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-30-job-session-lifecycle
+
+[English](2026-09-30-job-session-lifecycle.md) | 中文
+
+## 概述
+
+以唯一 JobId 将有所有者 job 的注册与结算记录为 Session 事件，包含原始时间戳、创建工具调用和生产方完成报告。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-30-job-session-lifecycle
+baseline: false
+changes:
+  - root: "event:job/registered"
+    previous: null
+    after: "f5520c1d261ca86ea03735799c311a0a9ede8babb588cf0a65422576d2ee0ad1"
+    decision: same-version
+  - root: "event:job/settled"
+    previous: null
+    after: "edd37b1e4974af648633014435572089b1e8fb71910468a0767a7e28fdd22abf"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+增加必需的 job 事件类型，不改变 Session 封装。新 JobId 用带 kind 前缀的 UUID 同时进行运行期控制与持久化配对；不为历史会话补造 job 事件。旧构建拒绝未知的必需事件。producerReported 表示完成 promise 兑现，不确认资源已释放。
+
+<a id="verification"></a>
+## 验证
+
+注册表和快照归一化测试覆盖因果顺序与唯一 JobId。CLI 和 SDK 快照验证运行中的注册、结算和通知；[job 生命周期约定](../subsystems/jobs.zh.md#session-lifecycle-records)允许应用销毁时留下不完整的终态历史。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-05-ptc-operation-metadata.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-05-ptc-operation-metadata
+
+English | [中文](2026-10-05-ptc-operation-metadata.zh.md)
+
+## Summary
+
+Adds optional pure presentation metadata to persisted nested PTC tool results so history retains operation-time directories and file targets.
+
+## 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-05-ptc-operation-metadata
+baseline: false
+changes:
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-16-session-format-v4"
+    after: "d66e11dddf5dfa3c71547e2cbd7b0608824cd8d6243fc16f532017ff28e8fba5"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing tool/ptc-dispatch records without meta remain valid. The optional JsonValue field does not change canonical program values, model-visible content, tool identities or message ordering. Historical calls without a recorded relative target keep safe unavailable navigation. The writer and accepted baseline stay at V4.
+
+<a id="verification"></a>
+## Verification
+
+963 focused tests passed with per-file 100% coverage of the six affected runtime/UI sources; actual nested shell and relative filesystem regressions, frozen metadata controls, TypeScript SDK 45 tests, Python SDK 29 tests and three owning keyless refresh/replays passed.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-05-ptc-operation-metadata.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-05-ptc-operation-metadata
+
+[English](2026-10-05-ptc-operation-metadata.md) | 中文
+
+## 概述
+
+为持久化的嵌套 PTC 工具结果增加可选的纯展示元数据，使历史保留操作时的目录和文件目标。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-05-ptc-operation-metadata
+baseline: false
+changes:
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-16-session-format-v4"
+    after: "d66e11dddf5dfa3c71547e2cbd7b0608824cd8d6243fc16f532017ff28e8fba5"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+没有 meta 的已有 tool/ptc-dispatch 记录仍然有效。可选 JsonValue 字段不改变程序读取的规范值、模型可见内容、工具标识或消息顺序。没有记录相对文件目标的历史调用仍安全地禁用导航。写入版本和已接受基线保持 V4。
+
+<a id="verification"></a>
+## 验证
+
+963 个定向测试通过，六个受影响 runtime/UI 源文件逐文件覆盖率 100%；实际嵌套 shell 与相对文件操作回归、冻结元数据控制、TypeScript SDK 45 个测试、Python SDK 29 个测试及三个 owning keyless refresh/replay 通过。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-05-working-directory-attribution.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-05-working-directory-attribution
+
+English | [中文](2026-10-05-working-directory-attribution.zh.md)
+
+## Summary
+
+Adds producer-owned working-directory notice attribution.
+
+## 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-05-working-directory-attribution
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-21-user-question-reply"
+    after: "9a36727716d0e73f681f3b725e7f28f89417c68174c8af0ff2b1ef52b08326a0"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-09-21-user-question-reply"
+    after: "ba5b10ea77d68f4a29439a9bd2a14f6a560acf55731749d57237757cc72fbc06"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-21-user-question-reply"
+    after: "19fab83e64cf84ee8a6caf62c592e85c9b195bfd19e84a2667c6693a395681fd"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-09-21-user-question-reply"
+    after: "2ace3b8059b82b6d9837fed518ca97a99eb37c4482df7aad0e71c85489428ade"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing records remain valid. The additive working-directory source kind is attribution only; the declared source policy preserves unknown attribution without interpreting it. The Session format remains unchanged.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run packages/session/working-directory/tests packages/shell/tool-bash/tests/tools.spec.ts packages/shell/tool-pwsh/tests/tools.spec.ts packages/subagent/subagent/tests/schedule-tools.spec.ts: 5 files and 207 tests passed.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-05-working-directory-attribution.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-05-working-directory-attribution
+
+[English](2026-10-05-working-directory-attribution.md) | 中文
+
+## 概述
+
+新增由工作目录组件拥有的通知来源标记。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-05-working-directory-attribution
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-21-user-question-reply"
+    after: "9a36727716d0e73f681f3b725e7f28f89417c68174c8af0ff2b1ef52b08326a0"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-09-21-user-question-reply"
+    after: "ba5b10ea77d68f4a29439a9bd2a14f6a560acf55731749d57237757cc72fbc06"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-21-user-question-reply"
+    after: "19fab83e64cf84ee8a6caf62c592e85c9b195bfd19e84a2667c6693a395681fd"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-09-21-user-question-reply"
+    after: "2ace3b8059b82b6d9837fed518ca97a99eb37c4482df7aad0e71c85489428ade"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有记录仍然有效。新增的 working-directory 来源种类只提供来源标记；已声明的来源策略保留未知标记而不解释其含义。Session 格式保持不变。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/session/working-directory/tests packages/shell/tool-bash/tests/tools.spec.ts packages/shell/tool-pwsh/tests/tools.spec.ts packages/subagent/subagent/tests/schedule-tools.spec.ts：5 个文件、207 个测试通过。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-10-07-title-reasoning-effort.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-10-07-title-reasoning-effort
+
+English | [中文](2026-10-07-title-reasoning-effort.zh.md)
+
+## Summary
+
+Records the concrete reasoning effort selected for auxiliary session-title requests.
+
+## 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-07-title-reasoning-effort
+baseline: false
+changes:
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-05-working-directory-attribution"
+    after: "b33545b3244861bcbf73b407d24b53402710f5acacab7ae939537e5504a68dc6"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+The new reasoningEffort field is optional. Existing V4 records remain valid and retain their original absence of a recorded effort. Prepared title requests write the resolved effort when the route exposes selectable reasoning; no Session format bump is required.
+
+<a id="verification"></a>
+## Verification
+
+Focused LLM, adapter, title-provider, and replay tests passed: 50 files and 1960 tests. The session-title-after-turn SDK snapshot passed with a recorded low effort selected from a route whose default is high.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-10-07-title-reasoning-effort.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-07-title-reasoning-effort
+
+[English](2026-10-07-title-reasoning-effort.md) | 中文
+
+## 概述
+
+记录辅助会话标题请求选择的具体推理强度。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-07-title-reasoning-effort
+baseline: false
+changes:
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-05-working-directory-attribution"
+    after: "b33545b3244861bcbf73b407d24b53402710f5acacab7ae939537e5504a68dc6"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+新增 reasoningEffort 字段为可选。现有 V4 记录仍有效，继续保留其未记录强度的事实。路由提供可选推理强度时，已准备的标题请求写入解析后的强度；无需提升 Session 格式版本。
+
+<a id="verification"></a>
+## 验证
+
+LLM、适配器、标题提供方与回放的定向测试通过：50 个文件、1960 个测试。session-title-after-turn SDK 快照通过，记录从默认 high 的路由中选出的 low 强度。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。