@deepseek-ai/dsh-hook-protocol 0.2.1-alpha.1 → 0.2.1-alpha.3

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,8 +30,8 @@
   en: 08b3960150e9c5e2
   zh: 6bb2f236d697de01
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/processing-pipeline:
-  en: b25d80f19b551f1a
-  zh: 9c6602f008d89bce
+  en: f71878539d98392e
+  zh: 826a0dd95475fff3
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/hook-session-events:
   en: f01ab4ab98f052b3
   zh: 1da25fa50378bd19
@@ -39,11 +39,11 @@
   en: 7f9239eaea5a945c
   zh: 9ba6a2ea955d4934
 /deepseek-ai-dsh-hook-protocol/understand-the-implementation/source-map:
-  en: aa4983adf89ea45c
-  zh: cc83b0ede5ff156c
+  en: 0d8956a6d8608ee0
+  zh: 9f554284c4c0a36e
 /deepseek-ai-dsh-hook-protocol/further-exploration:
-  en: 65a937c4c5f221d5
-  zh: 3b9d6485493dfb8d
+  en: 8b585ce73c2be2cc
+  zh: c0270fd001e1352b
 /deepseek-ai-dsh-hook-protocol/model-experience:
   en: 53d2f59435a4a88f
   zh: 79c8fc2849b20718

package/README.md

@@ -60,6 +60,8 @@ This section explains the design decisions behind the library and points at the
 
 ### Processing pipeline
 
+`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
@@ -82,7 +84,7 @@ 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 |

package/README.zh.md

@@ -60,6 +60,8 @@ kind: "package-library"
 
 ### 处理流水线
 
+`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/*` 会话事件
@@ -82,7 +84,7 @@ 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` 类型 |

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.1-alpha.1",
+  "version": "0.2.1-alpha.3",
   "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",
@@ -27,13 +27,13 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
-    "@deepseek-ai/dsh-shell": "0.2.1-alpha.1"
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   }
 }