@deepseek-ai/dsh-hook-protocol 0.2.0-rc.2 → 0.2.1-alpha.2

package/README.i18n.yaml

@@ -1,13 +1,13 @@
 # Bilingual-pair consistency record for README.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 packages/hooks/hook-protocol/README.md
+#   pnpm run verify-translation-pairing --write packages/experimental/hook-protocol/README.md
 /:
   en: 7cfe3761eedff848
   zh: 80b0bed5743d0924
 /deepseek-ai-dsh-hook-protocol:
-  en: bcf8ec6c43311fb7
-  zh: 4ef45c5aaced087d
+  en: 3092627c127b688d
+  zh: bbdb083e0a5dbc25
 /deepseek-ai-dsh-hook-protocol/summary:
   en: e8ab847d0db16043
   zh: 5c1e72f4b4a54fe1
@@ -30,20 +30,20 @@
   en: 08b3960150e9c5e2
   zh: 6bb2f236d697de01
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/processing-pipeline:
-  en: 5672f4151de0b50a
-  zh: d8fdc68d806e0d7b
+  en: f71878539d98392e
+  zh: 826a0dd95475fff3
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/hook-session-events:
-  en: ad77f468168fcbff
-  zh: 897bc6880fe76e1b
+  en: f01ab4ab98f052b3
+  zh: 1da25fa50378bd19
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/design-philosophy:
-  en: ccf3eacdd2219631
-  zh: 0732935a47a17c9d
+  en: 7f9239eaea5a945c
+  zh: 9ba6a2ea955d4934
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/source-map:
-  en: d613d9bd98d499fb
-  zh: afe2939d7df250ea
+  en: 0d8956a6d8608ee0
+  zh: 9f554284c4c0a36e
 /deepseek-ai-dsh-hook-protocol/further-exploration:
-  en: d93c5107a12af16c
-  zh: 89da3abc953a4c6b
+  en: 8b585ce73c2be2cc
+  zh: c0270fd001e1352b
 /deepseek-ai-dsh-hook-protocol/model-experience:
   en: 53d2f59435a4a88f
   zh: 79c8fc2849b20718

package/README.md

@@ -60,20 +60,22 @@ This section explains the design decisions behind the library and points at the
 
 ### Processing pipeline
 
-The library is a chain of single-purpose steps, one function each: validate the matcher pattern, run the command through the `dsh-shell` executor, decode the outcome, merge every matched hook's outcome into one most-restrictive result, and record the durable `hook/*` event pair. The matcher's `mode` parameter is the single axis the dialects differ on — `claude-code` interprets a pattern as literal alternatives or a regex, `codex` always as an unanchored regex. Every step degrades to a contained outcome instead of throwing, so a hook can never crash the calling turn: an invalid regex is a non-match, an executor rejection becomes a `HookOutput` with no exit code, exit 2 blocks with stderr as the reason, and every other failure stays non-blocking. Merging applies `deny > ask > allow` precedence, keeps the first `continue: false` stop sticky, and accumulates context in hook order. Detached runs are tracked so `fiber.dispose()` reaches quiescence, and the invariant companion rejects `hook/*` records outside an open turn. The steps live in [`src/matcher.ts`](src/matcher.ts), [`src/runner.ts`](src/runner.ts), [`src/codec.ts`](src/codec.ts), [`src/merge.ts`](src/merge.ts), [`src/events.ts`](src/events.ts), [`src/detached.ts`](src/detached.ts), and [`src/invariant.ts`](src/invariant.ts).
+`selectHookGroups` selects nonempty matching groups in config order. Each bridge resolves the current working directory only when this selection contains commands to run. `appendHookInvoked` omits absent or undefined matchers from the recorded event.
+
+The library is a chain of single-purpose steps, one function each: validate the matcher pattern, run the command through the `dsh-shell` executor, decode the outcome, merge every matched hook's outcome into one most-restrictive result, and record the durable `hook/*` event pair. The matcher's `mode` parameter is the single axis the dialects differ on — `claude-code` interprets a pattern as literal alternatives or a regex, `codex` always as an unanchored regex. Every step degrades to a contained outcome instead of throwing, so a hook can never crash the calling turn: an invalid regex is a non-match, an executor rejection becomes a `HookOutput` with no exit code, exit 2 blocks with stderr as the reason, and every other failure stays non-blocking. Merging applies `deny > ask > allow` precedence, keeps the first `continue: false` stop sticky, and accumulates context in hook order. Detached runs are tracked so `fiber.dispose()` reaches quiescence. The steps live in [`src/matcher.ts`](src/matcher.ts), [`src/runner.ts`](src/runner.ts), [`src/codec.ts`](src/codec.ts), [`src/merge.ts`](src/merge.ts), [`src/events.ts`](src/events.ts), and [`src/detached.ts`](src/detached.ts).
 
 ### `hook/*` session events
 
 The `hook/invoked` and `hook/result` events are declaration-merged into `SessionEventMap` as log-only records: like `compaction/*`, they are not surface events and carry no `surfaceOp`. A `hook/result` pairs with its `hook/invoked` by `handlerId`, and `appendHookResult` owns the decision rule. Payloads and per-event JSDoc live in the generated [persistence log event catalog](../../../docs/persistence-catalog.md).
 
-Invocation and result records must sit inside an open turn: `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that relation by construction, while `SessionStart` runs before turn 1 and gets no `hook/*` record — its injected context is delivered instead. The invariant companion registers on `ctx.invariants` and rejects `hook/*` events appended outside an open turn, a result without a matching invoked, an unknown dialect, or a non-finite duration.
+Invocation and result records must sit inside an open turn: `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that relation by construction, while `SessionStart` runs before turn 1 and gets no `hook/*` record — its injected context is delivered instead.
 
 ### Design philosophy
 
 - **One axis of difference collapsed into `mode`.** The dialects differ only in how a matcher pattern is interpreted, so the matcher takes the mode as a parameter instead of duplicating the engine.
 - **The executor owns process control.** Commands run through the `dsh-shell` executor rather than a bespoke spawn: the executor already provides the scrubbed-but-overridable environment, process-group cancellation, and timeout the protocol needs.
 - **Never throw into the loop.** Every failure mode — malformed JSON, an invalid regex, an executor rejection — degrades to a contained outcome or a non-match, so a hook can never crash the calling turn.
-- **Log-only, turn-enclosed events.** The `hook/*` records are durable evidence of what ran and what it decided; they are not surface events, and the invariant companion rejects them outside an open turn.
+- **Log-only, turn-enclosed events.** The `hook/*` records are durable evidence of what ran and what it decided; they are not surface events.
 
 The [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md) records the shared-versus-per-dialect split and the alternatives considered.
 
@@ -82,14 +84,13 @@ The [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Public exports of every primitive and event helper |
-| [`src/matcher.ts`](src/matcher.ts) | Match-all sentinels, literal-vs-regex mode, validation and runtime matching |
+| [`src/matcher.ts`](src/matcher.ts) | Matcher validation, dialect matching, and nonempty command-group selection |
 | [`src/runner.ts`](src/runner.ts) | `runHook` execution through `ctx.shell` and `DEFAULT_HOOK_TIMEOUT_MS` |
 | [`src/codec.ts`](src/codec.ts) | Exit-code and structured-stdout decoding into `HookOutput` |
 | [`src/merge.ts`](src/merge.ts) | Most-restrictive merge and the `MergedHookOutcome` type |
 | [`src/events.ts`](src/events.ts) | `hook/*` event declaration, append helpers, stderr summary |
 | [`src/detached.ts`](src/detached.ts) | Detached-run quiescence tracking |
 | [`src/types.ts`](src/types.ts) | `HookOutput`, `MatcherGroup`, `CommandHook`, and the `hook/*` payload types |
-| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: pairing, turn enclosure, dialect, and duration checks |
 
 </details>
 
@@ -103,7 +104,7 @@ Read these pages when the package-level contract is not enough. They move from t
 - [Hooks group map](../README.md) — the sibling group page and its package table.
 - [Hook protocol library Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md) — why the protocol core is shared and what each bridge owns.
 - [Hook bridges Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-bridges.md) — how the two bridges use these primitives.
-- [Interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md) — the typed-Decision surface the bridges map onto.
+- [Interception extension-points reference](../../../docs/tool-execution-pipeline.md) — the typed-Decision surface the bridges map onto.
 - [Generated persistence log event catalog](../../../docs/persistence-catalog.md) — the `hook/*` event payloads and per-event JSDoc.
 
 -----

package/README.zh.md

@@ -60,20 +60,22 @@ kind: "package-library"
 
 ### 处理流水线
 
-本库是一串单一用途的步骤，每个步骤一个函数：校验 matcher pattern、通过 `dsh-shell` 执行器运行命令、解码结果、把每个匹配 hook 的结果合并为最严格的一个结果，并记录持久的 `hook/*` 事件对。matcher 的 `mode` 参数是两个方言唯一的差异轴——`claude-code` 把 pattern 解释为字面量备选或正则，`codex` 始终解释为未锚定正则。每个步骤都会降级为受控结果而不是抛异常，因此钩子永远不会使调用轮次崩溃：无效正则是运行时的不匹配，执行器拒绝会变成没有退出码的 `HookOutput`，退出码 2 以 stderr 作为原因阻塞，其他失败均不阻塞。合并应用 `deny > ask > allow` 优先级，保持首个 `continue: false` 停止的粘性，并按 hook 顺序累积上下文。脱离运行会被跟踪，因此 `fiber.dispose()` 能达到完全停稳；不变式伴生插件会拒绝位于尚未结束的轮次之外的 `hook/*` 记录。这些步骤位于 [`src/matcher.ts`](src/matcher.ts)、[`src/runner.ts`](src/runner.ts)、[`src/codec.ts`](src/codec.ts)、[`src/merge.ts`](src/merge.ts)、[`src/events.ts`](src/events.ts)、[`src/detached.ts`](src/detached.ts) 与 [`src/invariant.ts`](src/invariant.ts)。
+`selectHookGroups` 按配置顺序选出包含命令的匹配组。仅当所选组中有待运行的命令时，各桥接才解析当前工作目录。`appendHookInvoked` 不会将缺失或值为 undefined 的 matcher 写入事件。
+
+本库是一串单一用途的步骤，每个步骤一个函数：校验 matcher pattern、通过 `dsh-shell` 执行器运行命令、解码结果、把每个匹配 hook 的结果合并为最严格的一个结果，并记录持久的 `hook/*` 事件对。matcher 的 `mode` 参数是两个方言唯一的差异轴——`claude-code` 把 pattern 解释为字面量备选或正则，`codex` 始终解释为未锚定正则。每个步骤都会降级为受控结果而不是抛异常，因此钩子永远不会使调用轮次崩溃：无效正则是运行时的不匹配，执行器拒绝会变成没有退出码的 `HookOutput`，退出码 2 以 stderr 作为原因阻塞，其他失败均不阻塞。合并应用 `deny > ask > allow` 优先级，保持首个 `continue: false` 停止的粘性，并按 hook 顺序累积上下文。脱离运行会被跟踪，因此 `fiber.dispose()` 能达到完全停稳。这些步骤位于 [`src/matcher.ts`](src/matcher.ts)、[`src/runner.ts`](src/runner.ts)、[`src/codec.ts`](src/codec.ts)、[`src/merge.ts`](src/merge.ts)、[`src/events.ts`](src/events.ts) 与 [`src/detached.ts`](src/detached.ts)。
 
 ### `hook/*` 会话事件
 
 `hook/invoked` 与 `hook/result` 事件通过 declaration merging 合并进 `SessionEventMap`，作为仅日志记录：与 `compaction/*` 相同，它们不是 surface 事件，也不携带 `surfaceOp`。`hook/result` 按 `handlerId` 与其 `hook/invoked` 配对，决策规则由 `appendHookResult` 负责。载荷与逐事件 JSDoc 位于生成的[持久化日志事件目录](../../../docs/persistence-catalog.zh.md)中。
 
-调用与结果记录必须位于尚未结束的轮次内：`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足该关系，而 `SessionStart` 在轮次 1 之前运行、没有 `hook/*` 记录——改为投递其注入的上下文。不变式伴生插件注册到 `ctx.invariants`，拒绝在尚未结束的轮次之外追加的 `hook/*` 事件、没有匹配 invoked 的结果、未知方言或非有限时长。
+调用与结果记录必须位于尚未结束的轮次内：`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足该关系，而 `SessionStart` 在轮次 1 之前运行、没有 `hook/*` 记录——改为投递其注入的上下文。
 
 ### 设计理念
 
 - **把唯一差异轴收拢进 `mode`。** 两个方言只在 matcher pattern 的解读方式上不同，因此 matcher 把 mode 作为参数，而不是复制引擎。
 - **执行器拥有进程控制。** 命令通过 `dsh-shell` 执行器运行，而非自建 spawn：执行器已经提供了协议所需的已清理但可覆盖的环境、进程组取消与超时。
 - **绝不向循环抛异常。** 每种失败模式——格式错误的 JSON、无效正则、执行器拒绝——都会降级为受控的结果或不匹配，因此钩子永远不能使调用轮次崩溃。
-- **仅日志、轮次内的事件。** `hook/*` 记录是「运行了什么、决定了什么」的持久证据；它们不是 surface 事件，不变式伴生插件会拒绝尚未结束的轮次之外的记录。
+- **仅日志、轮次内的事件。** `hook/*` 记录是「运行了什么、决定了什么」的持久证据；它们不是 surface 事件。
 
 [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md) 记录了共享与逐方言的划分以及备选方案。
 
@@ -82,14 +84,13 @@ kind: "package-library"
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 每个原语与事件辅助函数的公开导出 |
-| [`src/matcher.ts`](src/matcher.ts) | 匹配全部哨兵、字面量或正则模式、校验与运行时匹配 |
+| [`src/matcher.ts`](src/matcher.ts) | matcher 校验、方言匹配，以及包含命令的匹配组选择 |
 | [`src/runner.ts`](src/runner.ts) | 通过 `ctx.shell` 的 `runHook` 执行与 `DEFAULT_HOOK_TIMEOUT_MS` |
 | [`src/codec.ts`](src/codec.ts) | 退出码与结构化 stdout 解码为 `HookOutput` |
 | [`src/merge.ts`](src/merge.ts) | 最严格合并与 `MergedHookOutcome` 类型 |
 | [`src/events.ts`](src/events.ts) | `hook/*` 事件声明、追加辅助函数、stderr 摘要 |
 | [`src/detached.ts`](src/detached.ts) | 脱离运行的完全停稳跟踪 |
 | [`src/types.ts`](src/types.ts) | `HookOutput`、`MatcherGroup`、`CommandHook` 与 `hook/*` 载荷类型 |
-| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：配对、轮次包裹、方言与时长检查 |
 
 </details>
 
@@ -103,7 +104,7 @@ kind: "package-library"
 - [hooks 组地图](../README.zh.md)——同级组页面及其包表。
 - [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md)——协议核心为何共享、各桥接负责什么。
 - [钩子桥接 Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-bridges.md)——两个桥接如何使用这些原语。
-- [拦截扩展点 Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md)——桥接所映射的类型化 Decision 接口面。
+- [拦截扩展点 参考](../../../docs/tool-execution-pipeline.zh.md)——桥接所映射的类型化 Decision 接口面。
 - [生成的持久化日志事件目录](../../../docs/persistence-catalog.zh.md)——`hook/*` 事件载荷与逐事件 JSDoc。
 
 -----

package/lib/index.js

@@ -1,6 +1,6 @@
 //#region lib/types/matcher.js
 /**
-* Matcher shared by both hook dialects. Claude treats alphanumeric/underscore/
+* Matching and command-group selection shared by both hook dialects. Claude treats alphanumeric/underscore/
 * pipe patterns as literal alternatives and other patterns as regex; Codex
 * treats every non-empty pattern as an unanchored regex. Missing, empty, and
 * `*` match all. Runtime matching contains invalid regexes as non-matches;
@@ -50,6 +50,16 @@ function matchesMatcher(matcher, query, mode) {
 	if (mode === "claude-code" && CLAUDE_LITERAL.test(pattern)) return pattern.split("|").includes(query);
 	return compileRegex(pattern)?.test(query) ?? false;
 }
+/**
+* Select configured groups that have command hooks and match the event subject.
+* @param groups - groups for one hook point; absent points select no groups.
+* @param query - the event's matcher subject.
+* @param mode - dialect controlling literal or regex matching.
+* @returns Selected groups in config order, retaining their original references.
+*/
+function selectHookGroups(groups, query, mode) {
+	return (groups ?? []).filter((group) => group.hooks.length > 0 && matchesMatcher(group.matcher, query, mode));
+}
 //#endregion
 //#region lib/types/codec.js
 /**
@@ -311,7 +321,7 @@ function summarizeStderr(stderr, maxChars) {
 /**
 * Append a `hook/invoked` event naming the handler and hook point to `session`.
 * @param session - the session whose open turn records the event.
-* @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
+* @param invocation - the invocation identity; absent or `undefined` matchers are omitted from the payload.
 */
 function appendHookInvoked(session, invocation) {
 	session.append("hook/invoked", {
@@ -374,4 +384,4 @@ function createDetachedRuns() {
 	};
 }
 //#endregion
-export { DEFAULT_HOOK_TIMEOUT_MS, DEFAULT_STDERR_SUMMARY_MAX_CHARS, appendHookInvoked, appendHookResult, createDetachedRuns, matcherDiagnostic, matchesMatcher, mergeHookOutputs, parseHookOutput, runHook, summarizeStderr };
+export { DEFAULT_HOOK_TIMEOUT_MS, DEFAULT_STDERR_SUMMARY_MAX_CHARS, appendHookInvoked, appendHookResult, createDetachedRuns, matcherDiagnostic, matchesMatcher, mergeHookOutputs, parseHookOutput, runHook, selectHookGroups, summarizeStderr };

package/lib/types/events.d.ts

@@ -17,8 +17,8 @@ export interface HookInvocation {
     dialect: HookDialect;
     /** A stable id correlating the invoked event with its result. */
     handlerId: string;
-    /** The matcher-group pattern that selected it (absent for match-all). */
-    matcher?: string;
+    /** The matcher-group pattern; absent or `undefined` is omitted from the event. */
+    matcher?: string | undefined;
 }
 /** The decided outcome half of the pair. */
 export interface HookResultRecord {
@@ -60,7 +60,7 @@ export declare function summarizeStderr(stderr: string, maxChars: number): strin
 /**
  * Append a `hook/invoked` event naming the handler and hook point to `session`.
  * @param session - the session whose open turn records the event.
- * @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
+ * @param invocation - the invocation identity; absent or `undefined` matchers are omitted from the payload.
  */
 export declare function appendHookInvoked(session: Session, invocation: HookInvocation): void;
 /**

package/lib/types/index.d.ts

@@ -6,7 +6,7 @@
  * @module @deepseek-ai/dsh-hook-protocol
  */
 export type { CommandHook, HookDialect, HookOutput, MatcherGroup, MatcherMode, } from './types.ts';
-export { matcherDiagnostic, matchesMatcher } from './matcher.ts';
+export { matcherDiagnostic, matchesMatcher, selectHookGroups } from './matcher.ts';
 export { parseHookOutput } from './codec.ts';
 export { DEFAULT_HOOK_TIMEOUT_MS, runHook } from './runner.ts';
 export type { RunHookOptions, RunHookResult } from './runner.ts';

package/lib/types/matcher.d.ts

@@ -1,12 +1,12 @@
 /**
- * Matcher shared by both hook dialects. Claude treats alphanumeric/underscore/
+ * Matching and command-group selection shared by both hook dialects. Claude treats alphanumeric/underscore/
  * pipe patterns as literal alternatives and other patterns as regex; Codex
  * treats every non-empty pattern as an unanchored regex. Missing, empty, and
  * `*` match all. Runtime matching contains invalid regexes as non-matches;
  * config parsers use {@link matcherDiagnostic} to reject them with a diagnostic.
  * @module @deepseek-ai/dsh-hook-protocol/matcher
  */
-import type { MatcherMode } from './types.ts';
+import type { MatcherGroup, MatcherMode } from './types.ts';
 /**
  * Validate one matcher before a bridge accepts its config group.
  * @param matcher - configured pattern; match-all sentinels are valid.
@@ -26,4 +26,12 @@ export declare function matcherDiagnostic(matcher: string | undefined, mode: Mat
  *   regex.
  */
 export declare function matchesMatcher(matcher: string | undefined, query: string, mode: MatcherMode): boolean;
+/**
+ * Select configured groups that have command hooks and match the event subject.
+ * @param groups - groups for one hook point; absent points select no groups.
+ * @param query - the event's matcher subject.
+ * @param mode - dialect controlling literal or regex matching.
+ * @returns Selected groups in config order, retaining their original references.
+ */
+export declare function selectHookGroups(groups: readonly MatcherGroup[] | undefined, query: string, mode: MatcherMode): MatcherGroup[];
 //# sourceMappingURL=matcher.d.ts.map

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@deepseek-ai/dsh-hook-protocol",
   "description": "Shared Claude Code / Codex hook wire protocol: matcher engine, stdin/exit-code/stdout codec, multi-hook merge, and hook/* session events",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/hooks/hook-protocol"
+    "directory": "packages/experimental/hook-protocol"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -18,29 +18,22 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
-    "lib/invariant.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-shell": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   }
 }

package/lib/invariant.js

@@ -1,97 +0,0 @@
-//#region lib/types/invariant.js
-/** Package-owned hook invocation/result stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
-const PACKAGE_NAME = "@deepseek-ai/dsh-hook-protocol";
-/** Cordis companion plugin name. */
-const name = "hook-protocol-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/** Correlation key shared by an invoked/result pair. */
-function hookKey(data) {
-	return `${data.turn}\0${data.point}\0${data.handlerId}`;
-}
-/** Validate one hook event against committed pending invocations. */
-function validateHookEvent(trace, event, fail) {
-	if (event.type !== "hook/invoked" && event.type !== "hook/result") return void 0;
-	if (trace.openTurn === null) fail(`${event.type} appended outside any open turn`);
-	if (event.data.turn !== trace.openTurn) fail(`${event.type} names turn ${event.data.turn} but open turn is ${trace.openTurn}`);
-	if (event.type === "hook/invoked") {
-		if (event.data.point.length === 0 || event.data.handlerId.length === 0) fail("hook/invoked point and handlerId must be non-empty");
-		const dialect = event.data.dialect;
-		if (dialect !== "claude-code" && dialect !== "codex") fail(`hook/invoked carries unknown dialect ${JSON.stringify(dialect)}`);
-		return {
-			key: hookKey(event.data),
-			delta: 1
-		};
-	}
-	const key = hookKey(event.data);
-	if ((trace.pending.get(key) ?? 0) === 0) fail(`hook/result has no matching hook/invoked for ${JSON.stringify(event.data.handlerId)}`);
-	if (!Number.isFinite(event.data.durationMs) || event.data.durationMs < 0) fail("hook/result durationMs must be a non-negative finite number");
-	return {
-		key,
-		delta: -1
-	};
-}
-/** Apply one committed hook-pair transition. */
-function applyHookTransition(pending, transition) {
-	const next = (pending.get(transition.key) ?? 0) + transition.delta;
-	if (next === 0) pending.delete(transition.key);
-	else pending.set(transition.key, next);
-}
-/** Install hook invoked/result pairing checks. */
-const install = Object.assign((ctx, fail) => {
-	const traces = /* @__PURE__ */ new WeakMap();
-	const staged = /* @__PURE__ */ new WeakMap();
-	const seed = (session) => {
-		const trace = {
-			openTurn: null,
-			pending: /* @__PURE__ */ new Map()
-		};
-		traces.set(session, trace);
-		for (const event of session.snapshotEvents()) {
-			if (event.type === "turn/start") trace.openTurn = event.data.turn;
-			else if (event.type === "turn/end") trace.openTurn = null;
-			const transition = validateHookEvent(trace, event, fail);
-			if (transition !== void 0) applyHookTransition(trace.pending, transition);
-		}
-		return trace;
-	};
-	const traceFor = (session) => traces.get(session) ?? seed(session);
-	for (const session of ctx.sessions.list()) seed(session);
-	ctx.on("session/created", (session) => {
-		seed(session);
-	}, { global: true });
-	ctx.on("session/event", (session, event) => {
-		const trace = traceFor(session);
-		if (event.type === "turn/start") {
-			trace.openTurn = event.data.turn;
-			return;
-		}
-		if (event.type === "turn/end") {
-			trace.openTurn = null;
-			return;
-		}
-		if (event.type !== "hook/invoked" && event.type !== "hook/result") return;
-		const candidate = staged.get(event);
-		/* v8 ignore next -- internal/dispatch stages every hook invocation/result event */
-		if (candidate === void 0 || candidate.session !== session) return fail("hook event published without pre-commit validation");
-		staged.delete(event);
-		applyHookTransition(trace.pending, candidate.transition);
-	}, { global: true });
-	ctx.on("internal/dispatch", (_mode, eventName, args) => {
-		if (eventName !== "session/event") return;
-		const [session, event] = args;
-		const transition = validateHookEvent(traceFor(session), event, fail);
-		if (transition !== void 0) staged.set(event, {
-			session,
-			transition
-		});
-	}, { global: true });
-}, { inject: ["sessions"] });
-/**
-* Register the hook-protocol invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,13 +0,0 @@
-/** Package-owned hook invocation/result stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "hook-protocol-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register the hook-protocol invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map