@hasna-internal/kai-hook-protocol 0.1.1-rc.2 → 0.1.1-rc.3

package/README.md

@@ -1,44 +1,3 @@
 # @hasna-internal/kai-hook-protocol
 
-English | [中文](README.zh.md)
-
-The **shared core** of the Claude Code / Codex hook wire protocol. NOT a cordis plugin — it registers nothing and injects nothing. It is a **library** of dialect-neutral primitives the two bridge plugins (`@hasna-internal/kai-hooks-claude-code`, `@hasna-internal/kai-hooks-codex`) import so neither re-implements the identical halves of the protocol.
-
-Codex deliberately reimplements a *subset* of the Claude Code hook protocol — the same `hooks.json` matcher-group shape, the same exit-code/stdout output contract, the same command-hook execution model. The genuinely-shared parts live here; each bridge owns only what differs.
-
-## What's shared (here) vs. per-dialect (the bridges)
-
-| Concern | Here (`dsh-hook-protocol`) | The bridge (`dsh-hooks-claude-code` / `-codex`) |
-|---|---|---|
-| Matcher validation + test | `matcherDiagnostic(pattern, mode)` for parse-time diagnostics; `matchesMatcher(pattern, query, mode)` for contained runtime matching | picks its `mode` (`claude` = literal-or-regex, `codex` = always regex) and rejects a config group carrying a diagnostic |
-| Run a hook | `runHook(bash, hook, opts, now)` — stdin payload + env via `ctx.shell`, decode | builds the per-event stdin **payload** + the dialect's **env** |
-| Decode output | `parseHookOutput(exit, stdout, stderr)` → neutral `HookOutput` | maps the neutral `HookOutput` onto an extension-point-specific typed Decision |
-| Merge N hooks | `mergeHookOutputs(outputs)` → most-restrictive `MergedHookOutcome` | — |
-| Durable record | `appendHookInvoked` / `appendHookResult` (`hook/*` session events; the result's `decision`/`stderrSummary` derive from the `HookOutput` here) | calls them around each invocation |
-| Detached-run quiescence | `createDetachedRuns()` — track fire-and-forget run chains; `drain()` aborts, then awaits them | passes `signal` to each detached `runHook`, registers `drain` as its effect disposer |
-
-## Primitives
-
-- **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`** — match-all on absent/`''`/`'*'`; `claude` mode treats a pure `[A-Za-z0-9_|]+` pattern as a literal (pipe = exact-match alternation) and anything else as a regex; `codex` mode is always an unanchored regex. Bridge parsers discard matcher fields for events without matcher subjects, then use `matcherDiagnostic` to reject an invalid consumed regex with a stable diagnostic before registering any hooks. The runtime predicate still contains an invalid pattern as a non-match, so a direct library caller cannot throw into the agent loop.
-- **`runHook(bash, hook, options, now)`** — require and forward the caller-owned `options.signal`, serialize `options.payload` to the hook's stdin (with a trailing newline iff `options.trailingNewline`), merge `options.env` after the executor's credential scrub (the `dsh-shell` trusted-plugin API), honor the hook's `timeoutSec` (else `options.defaultTimeoutMs` — the bridge owns the default, its config defaulting to the lib's `DEFAULT_HOOK_TIMEOUT_MS` 10-minute reference), and decode the result (threading `options.expectedEventName` to the codec). Cancellation therefore reaches the executor's process-group kill and join boundary. Never throws: an executor rejection (infra fault) becomes a `HookOutput` with `exitCode: undefined` (a non-blocking error). `now` is injected for testable durations.
-- **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** decodes exit status and structured stdout. Exit 2 blocks with stderr; other failures are non-blocking. A matching hook-specific permission decision overrides the legacy top-level decision; mismatched or missing event discriminators suppress only event-specific fields. Top-level fields remain event-agnostic, and successful non-JSON output is left to the bridge.
-- **`mergeHookOutputs(outputs)`** — fold the results of every hook that matched one point: permission precedence **deny > ask > allow**, halt sticky on the first `continue:false`, block reasons joined with `\n\n`, `additionalContext`/`systemMessages` accumulated in order.
-- **`createDetachedRuns()`** — quiescence tracking for the emit-shaped points, which run detached (no extension point awaits them). The bridge tracks each run chain — the hook run PLUS its continuation — and registers `drain()` as its effect disposer: drain fires the tracker's abort `signal` (so a still-running hook process is killed via `runHook`, not awaited out to its timeout), then resolves once every tracked chain has settled. `fiber.dispose()` resolving therefore means no detached hook work is left to fire into a disposed context ([defensive patterns](../../../docs/defensive-patterns.md): dispose must reach quiescence).
-
-## `hook/*` session events
-
-Declaration-merged into `SessionEventMap` (log-only, like `compaction/*` — NOT a `SurfaceEventType`, no `surfaceOp`): `hook/invoked` (a hook command ran) and `hook/result` (its outcome, paired by `handlerId`, with `appendHookResult` owning the decision rule). Payloads and per-event JSDoc are in the generated [persistence log event catalog](../../../docs/persistence-catalog.md); `stderrSummary` is truncated to the record's `stderrSummaryMaxChars` (the bridge's config, reference default `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500; omitted when empty).
-
-Hook invocation/result records must sit inside an open turn. `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that owner-defined relation by construction. `SessionStart` runs before turn 1 and gets no `hook/*` record; its allowed context remains pending in the inbox until a waking delivery opens a turn — see the hooks Agent Note.
-
-## Model Experience
-
-Indirectly, through `dsh-hooks-claude-code` and `dsh-hooks-codex`, which can turn parsed hook output into prompt context, blocked outcomes, or continuation feedback.
-
-#### KV Cache effect
-
-No direct invalidation; the named consumer owns any request-prefix changes.
-
-## Known Limitations and Deferred Work
-
-- **`HookOutput.updatedInput` is parsed but not honored** — input rewrite is a deferred consistency-design problem ([the pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md)); a bridge logs + warns when a hook sets it. See `src/types.ts` for the full contracts.
+This package has been retired by its owner. This release is an empty placeholder with no dependencies or supported functionality. Do not use it.

package/index.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = {};

package/package.json

@@ -1,46 +1,16 @@
 {
   "name": "@hasna-internal/kai-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.1.1-rc.2",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/hooks/hook-protocol"
-  },
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "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"
-  },
+  "version": "0.1.1-rc.3",
+  "description": "Retired package. Empty placeholder with no dependencies.",
+  "main": "index.js",
   "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts"
+    "index.js",
+    "README.md"
   ],
   "license": "MIT",
-  "peerDependencies": {
-    "@hasna-internal/kai-session": "^0.1.1-rc.2",
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
-    "@hasna-internal/kai-shell": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
-  },
-  "devDependencies": {
-    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
-    "@hasna-internal/kai-shell": "^0.1.1-rc.2",
-    "@hasna-internal/kai-session": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+  "deprecated": "Retired by the package owner. Empty placeholder; do not use.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 DeepSeek
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.i18n.yaml

@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/hooks/hook-protocol/README.md
-README.md: cebf93a04caef67a82549663018c10aac4cd535d
-README.zh.md: bc02e90aee14491ee62c1954a459cb70832a408c

package/README.zh.md

@@ -1,44 +0,0 @@
-# @hasna-internal/kai-hook-protocol
-
-[English](README.md) | 中文
-
-Claude Code／Codex hook 协议格式（wire format）的**共享核心**。它不是 Cordis 插件：不注册也不注入任何内容。它是一个**库**，提供两个桥接插件（`@hasna-internal/kai-hooks-claude-code`、`@hasna-internal/kai-hooks-codex`）导入的方言无关原语，使两者都无需重复实现协议中相同的部分。
-
-Codex 有意重新实现了 Claude Code hook 协议的一个*子集*，包括相同的 `hooks.json` matcher group 结构、相同的退出码／stdout 输出约定以及相同的 command hook 执行模式。真正共享的部分位于此处；每个桥接只负责不同的部分。
-
-## 共享内容（此处）与各方言内容（桥接）
-
-| 关注点 | 此处（`dsh-hook-protocol`） | 桥接（`dsh-hooks-claude-code` / `-codex`） |
-|---|---|---|
-| Matcher 校验与匹配判断 | `matcherDiagnostic(pattern, mode)` 用于解析时诊断；`matchesMatcher(pattern, query, mode)` 用于隔离的运行时匹配 | 选择自身的 `mode`（`claude` = 字面量或正则，`codex` = 始终使用正则），并拒绝带有诊断的配置组 |
-| 运行 hook | `runHook(bash, hook, opts, now)`：通过 `ctx.shell` 提供 stdin payload + env，再解码 | 构造每个事件的 stdin **payload** + 该方言的 **env** |
-| 解码输出 | `parseHookOutput(exit, stdout, stderr)` → 中性 `HookOutput` | 将中性 `HookOutput` 映射到扩展点特定的类型化 Decision |
-| 合并 N 个 hook | `mergeHookOutputs(outputs)` → 最严格的 `MergedHookOutcome` | （无） |
-| 持久记录 | `appendHookInvoked` / `appendHookResult`（`hook/*` 会话事件；结果的 `decision`／`stderrSummary` 从此处的 `HookOutput` 派生） | 在每次调用前后调用它们 |
-| 脱离运行的完全停稳 | `createDetachedRuns()`：跟踪触发后不等待的运行链；`drain()` 先 abort，再等待它们 | 将 `signal` 传给每个脱离的 `runHook`，并将 `drain` 注册为 effect disposer |
-
-## 原语
-
-- **`matcherDiagnostic(matcher, mode)` / `matchesMatcher(matcher, query, mode)`**：缺失、`''` 或 `'*'` 时匹配全部；`claude` mode 将纯 `[A-Za-z0-9_|]+` pattern 视为字面量（管道符 = 精确匹配交替），其他 pattern 视为正则；`codex` mode 始终使用未锚定正则。桥接解析器会丢弃没有 matcher 匹配对象的事件所带的 matcher 字段，再用 `matcherDiagnostic` 拒绝事件实际使用的无效正则，并在注册任何钩子之前给出稳定诊断。运行时谓词仍会将无效 pattern 隔离为不匹配，因此直接调用本库不会向 agent loop（智能体循环）抛异常。
-- **`runHook(bash, hook, options, now)`**：要求并转发调用方拥有的 `options.signal`，将 `options.payload` 序列化到 hook stdin（当且仅当 `options.trailingNewline` 时添加尾随换行符），在执行器凭证清理后合并 `options.env`（`dsh-shell` 受信任插件接口），遵循 hook 的 `timeoutSec`（否则使用 `options.defaultTimeoutMs`；默认值属于桥接，其配置默认为 lib 的 `DEFAULT_HOOK_TIMEOUT_MS` 10 分钟参考值），再解码结果（将 `options.expectedEventName` 传递给 codec）。因此取消会到达执行器的进程组终止与 join 边界。它绝不抛出异常：执行器拒绝（基础设施故障）会变为 `HookOutput`，其 `exitCode: undefined`（非阻塞错误）。`now` 会被注入，以便测试持续时间。
-- **`parseHookOutput(exitCode, stdout, stderr, expectedEventName?)`** 解码退出状态与结构化 stdout。退出码为 2 时，会以 stderr 内容阻止执行；其他失败不阻塞。匹配的 hook 特定权限决策会覆盖遗留顶层决策；事件判别字段不匹配或缺失只会抑制事件特定字段。顶层字段仍与事件无关，成功但非 JSON 的输出会留给桥接处理。
-- **`mergeHookOutputs(outputs)`**：折叠在一个点上匹配的每个 hook 结果：权限优先级为 **deny > ask > allow**，从首个 `continue:false` 起，halt 状态保持不变，阻塞原因用 `\n\n` 连接，`additionalContext`／`systemMessages` 按顺序累积。
-- **`createDetachedRuns()`**：跟踪以 emit 形式脱离运行的点是否完全停稳（没有扩展点等待它们）。桥接会跟踪每条运行链，包括 hook 运行及其 continuation，并将 `drain()` 注册为 effect disposer。drain 会触发 tracker 的 abort `signal`（因此仍在运行的 hook 进程会通过 `runHook` 终止，而不是等待到超时），随后在所有已跟踪链结算后 resolve。因此 `fiber.dispose()` resolve 时，不会遗留任何可能作用于已 dispose（资源释放）的上下文的脱离 hook 工作（见 [防御模式](../../../docs/defensive-patterns.zh.md)：dispose 必须达到完全停稳）。
-
-## `hook/*` 会话事件
-
-通过 declaration merging 合并到 `SessionEventMap`（仅日志，与 `compaction/*` 相同；不是 `SurfaceEventType`，没有 `surfaceOp`）：`hook/invoked`（hook 命令已运行）与 `hook/result`（其结果，按 `handlerId` 配对，决策规则由 `appendHookResult` 负责）。Payload 与每事件 JSDoc 位于生成的 [持久化日志事件目录](../../../docs/persistence-catalog.zh.md)；`stderrSummary` 会截断到记录的 `stderrSummaryMaxChars`（桥接配置，参考默认值 `DEFAULT_STDERR_SUMMARY_MAX_CHARS` = 500；为空时省略）。
-
-Hook 调用／结果记录必须位于一个尚未结束的轮次内。`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足这条由所有者定义的关系。`SessionStart` 在轮次 1 之前运行，因此没有 `hook/*` 记录；其获准的上下文会在 inbox 中保持待处理，直到唤醒交付打开一个轮次，详见 hooks Agent Note。
-
-## 模型体验
-
-通过 `dsh-hooks-claude-code` 与 `dsh-hooks-codex` 间接影响；它们可以将解析后 hook 输出转为提示词上下文、已阻塞结果或 continuation 反馈。
-
-#### KV Cache 影响
-
-不会直接失效；请求前缀变更由上述消费方负责。
-
-## 已知限制与暂缓事项
-
-- **`HookOutput.updatedInput` 会被解析但不会应用**：输入改写是已暂缓的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md)）；当 hook 设置它时，桥接会记录 + 警告。完整约定见 `src/types.ts`。

package/lib/index.js

@@ -1,377 +0,0 @@
-//#region lib/types/matcher.js
-/**
-* Matcher 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 @hasna-internal/kai-hook-protocol/matcher
-*/
-/** True for an absent / empty / `'*'` pattern — the match-all sentinels. */
-function isMatchAll(matcher) {
-	return matcher === void 0 || matcher === "" || matcher === "*";
-}
-/** A Claude-literal pattern is purely word chars + `|` (the regex-vs-literal discriminator). */
-const CLAUDE_LITERAL = /^[A-Za-z0-9_|]+$/;
-/** Compile an unanchored matcher regex; invalid patterns return `undefined`. */
-function compileRegex(pattern) {
-	try {
-		return new RegExp(pattern);
-	} catch (_syntaxError) {
-		return;
-	}
-}
-/**
-* Validate one matcher before a bridge accepts its config group.
-* @param matcher - configured pattern; match-all sentinels are valid.
-* @param mode - dialect deciding whether a word-and-pipe pattern is literal.
-* @returns `undefined` for a valid matcher, otherwise a stable diagnostic.
-*/
-function matcherDiagnostic(matcher, mode) {
-	if (isMatchAll(matcher)) return void 0;
-	const pattern = matcher;
-	if (mode === "claude-code" && CLAUDE_LITERAL.test(pattern)) return void 0;
-	return compileRegex(pattern) === void 0 ? `invalid ${mode} regex matcher ${JSON.stringify(pattern)}` : void 0;
-}
-/**
-* Whether `matcher` selects `query` under the given dialect. Claude literal
-* patterns exact-match pipe-separated alternatives; all other patterns are
-* unanchored regexes. Invalid regexes return `false` rather than throwing;
-* bridge config parsers surface them through {@link matcherDiagnostic} before use.
-* @param matcher - the configured pattern; absent/empty/`'*'` are the match-all sentinels.
-* @param query - the candidate value (a tool name, a session source, …).
-* @param mode - the dialect deciding literal-vs-regex interpretation of the pattern.
-* @returns `true` when the pattern selects the query; `false` on a non-match or an invalid
-*   regex.
-*/
-function matchesMatcher(matcher, query, mode) {
-	if (isMatchAll(matcher)) return true;
-	const pattern = matcher;
-	if (mode === "claude-code" && CLAUDE_LITERAL.test(pattern)) return pattern.split("|").includes(query);
-	return compileRegex(pattern)?.test(query) ?? false;
-}
-//#endregion
-//#region lib/types/codec.js
-/**
-* Decode hook process outcomes for both dialects. Exit 0 may carry structured
-* JSON or plain stdout; exit 2 blocks with stderr as the reason; every other
-* exit is a non-blocking error. Bridges decide which recognized fields apply.
-* @module @hasna-internal/kai-hook-protocol/codec
-*/
-/** The exit code a hook uses to signal a blocking error (stderr → model). */
-const BLOCKING_EXIT_CODE = 2;
-/** Read a string field from a parsed object, or `undefined` if absent/wrong type. */
-function str(obj, key) {
-	const v = obj[key];
-	return typeof v === "string" ? v : void 0;
-}
-/** Read a boolean field, or `undefined` if absent/wrong type. */
-function bool(obj, key) {
-	const v = obj[key];
-	return typeof v === "boolean" ? v : void 0;
-}
-/** A plain (non-null, non-array) object, or `undefined`. */
-function obj(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
-}
-/**
-* The legacy TOP-LEVEL `decision` is only `approve`/`block` in both reference
-* schemas — `allow`/`deny`/`ask` are reserved for `hookSpecificOutput.
-* permissionDecision`. So an out-of-band `{"decision":"deny"}` is invalid and
-* ignored here (it must not become a real blocking decision).
-*/
-function topLevelDecisionOf(value) {
-	return value === "approve" || value === "block" ? value : void 0;
-}
-/** A `hookSpecificOutput.permissionDecision` is `allow`/`deny`/`ask` only. */
-function permissionDecisionOf(value) {
-	return value === "allow" || value === "deny" || value === "ask" ? value : void 0;
-}
-/**
-* Decode process output into a dialect-neutral hook outcome. This function is
-* total: malformed JSON remains plain stdout. When `expectedEventName` is set,
-* a missing or different `hookSpecificOutput.hookEventName` discards only its
-* event-scoped fields; top-level fields and the claimed discriminator remain.
-* Omitting the guard applies the block as-is.
-* @param exitCode - process exit, or `undefined` when spawn failed.
-* @param stdout - output parsed as structured JSON only on exit 0.
-* @param stderr - the captured stderr stream; becomes the blocking `reason` on exit 2.
-* @param expectedEventName - firing event used to guard hook-specific fields; omit to disable the guard.
-* @returns the dialect-neutral decoded outcome.
-*/
-function parseHookOutput(exitCode, stdout, stderr, expectedEventName) {
-	const trimmedErr = stderr.trim();
-	const trimmedOut = stdout.trim();
-	const output = {
-		exitCode,
-		stderr: trimmedErr,
-		stdout: trimmedOut
-	};
-	if (exitCode === BLOCKING_EXIT_CODE) {
-		output.decision = "block";
-		if (trimmedErr.length > 0) output.reason = trimmedErr;
-	}
-	if (exitCode === 0) {
-		if (trimmedOut.startsWith("{")) {
-			let parsed;
-			try {
-				parsed = obj(JSON.parse(trimmedOut));
-			} catch {
-				parsed = void 0;
-			}
-			if (parsed) applyStructured(output, parsed, expectedEventName);
-		}
-	}
-	return output;
-}
-/**
-* Fold a parsed structured-stdout object into `output` (mutates in place).
-* `expectedEventName` (the firing event) gates the per-event `hookSpecificOutput`
-* block: a block whose `hookEventName` names a different event — OR omits it — has
-* its event-scoped fields discarded (any present `hookEventName` is still recorded).
-*/
-function applyStructured(output, parsed, expectedEventName) {
-	const cont = bool(parsed, "continue");
-	if (cont !== void 0) output.continue = cont;
-	const stopReason = str(parsed, "stopReason");
-	if (stopReason !== void 0) output.stopReason = stopReason;
-	const sysMsg = str(parsed, "systemMessage");
-	if (sysMsg !== void 0) output.systemMessage = sysMsg;
-	const topDecision = topLevelDecisionOf(str(parsed, "decision"));
-	if (topDecision !== void 0) output.decision = topDecision;
-	const topReason = str(parsed, "reason");
-	if (topReason !== void 0) output.reason = topReason;
-	const hso = obj(parsed.hookSpecificOutput);
-	if (hso) {
-		const eventName = str(hso, "hookEventName");
-		if (eventName !== void 0) output.hookEventName = eventName;
-		if (expectedEventName !== void 0 && eventName !== expectedEventName) return;
-		const permission = permissionDecisionOf(str(hso, "permissionDecision"));
-		if (permission !== void 0) output.decision = permission;
-		const permissionReason = str(hso, "permissionDecisionReason");
-		if (permissionReason !== void 0) output.reason = permissionReason;
-		const addCtx = str(hso, "additionalContext");
-		if (addCtx !== void 0) output.additionalContext = addCtx;
-		const updated = obj(hso.updatedInput);
-		if (updated !== void 0) output.updatedInput = updated;
-	}
-}
-//#endregion
-//#region lib/types/runner.js
-/**
-* Execute command hooks through `ctx.shell`, using its credential scrub,
-* process-group cancellation, and timeout machinery. The bridge supplies the
-* trusted stdin payload and dialect environment, then this module decodes the
-* captured outcome.
-* @module @hasna-internal/kai-hook-protocol/runner
-*/
-/**
-* The reference default per-hook timeout, in ms (10 minutes) — the value both
-* Claude Code and Codex apply to a hook whose config sets no `timeout`. It
-* lives here, once, as the protocol's default; the bridges' `defaultTimeoutMs`
-* config defaults to it, and a per-hook {@link CommandHook.timeoutSec} is the
-* override API.
-*/
-const DEFAULT_HOOK_TIMEOUT_MS = 6e5;
-/**
-* Run `hook` with serialized stdin and decode its outcome. A hook-specific
-* timeout in seconds overrides the default; trusted environment entries merge
-* after the executor scrub. Infrastructure rejection becomes an outcome with
-* no exit code, so this function never throws or crashes the calling turn.
-* @param bash - The executor service the command runs through.
-* @param hook - the configured command; its `timeoutSec` (wire unit: seconds) overrides the default timeout.
-* @param options - the invocation's payload, env, cwd, signal, stdin framing, and default timeout.
-* @param now - millisecond clock used for the reported duration.
-* @returns the decoded output plus the run's wall-clock duration.
-*/
-async function runHook(bash, hook, options, now) {
-	const started = now();
-	const timeoutMs = hook.timeoutSec !== void 0 ? hook.timeoutSec * 1e3 : options.defaultTimeoutMs;
-	const stdin = JSON.stringify(options.payload) + (options.trailingNewline ? "\n" : "");
-	const request = {
-		command: hook.command,
-		timeoutMs,
-		stdin,
-		signal: options.signal,
-		...options.cwd !== void 0 ? { workdir: options.cwd } : {},
-		...options.env !== void 0 ? { env: options.env } : {}
-	};
-	try {
-		const result = await bash.run(bash.resolve(request));
-		return {
-			output: parseHookOutput(result.exitCode ?? void 0, result.stdout.text, result.stderr.text, options.expectedEventName),
-			durationMs: now() - started
-		};
-	} catch (error) {
-		return {
-			output: parseHookOutput(void 0, "", error instanceof Error ? error.message : String(error)),
-			durationMs: now() - started
-		};
-	}
-}
-//#endregion
-//#region lib/types/merge.js
-/**
-* Merge matched hooks into one most-restrictive outcome. Permission precedence
-* is `deny > ask > allow`; the first `continue:false` stop is sticky; reasons
-* for the winning rank are joined; and context and system messages accumulate
-* in hook order.
-* @module @hasna-internal/kai-hook-protocol/merge
-*/
-/** Rank a single hook's decision for the deny>ask>allow precedence (higher = stricter). */
-function rank(decision) {
-	switch (decision) {
-		case "deny":
-		case "block": return 3;
-		case "ask": return 2;
-		case "approve":
-		case "allow": return 1;
-		default: return 0;
-	}
-}
-/** Collapse a ranked decision back to the merged enum. */
-function decisionForRank(maxRank) {
-	switch (maxRank) {
-		case 3: return "deny";
-		case 2: return "ask";
-		case 1: return "allow";
-		default: return "none";
-	}
-}
-/**
-* Fold `outputs` (the results of every hook that matched a point, in hook order)
-* into one {@link MergedHookOutcome} by the precedence rules above. An empty list
-* yields a neutral outcome (`decision: 'none'`, no stop, empty context) — the
-* caller treats that as "no hook had anything to say".
-* @param outputs - every matched hook's decoded output, in hook order.
-* @returns the single folded outcome the bridge maps onto its extension point.
-*/
-function mergeHookOutputs(outputs) {
-	let maxRank = 0;
-	const reasonsByRank = /* @__PURE__ */ new Map();
-	let stop = false;
-	let stopReason;
-	const additionalContext = [];
-	const systemMessages = [];
-	for (const out of outputs) {
-		const r = rank(out.decision);
-		if (r > maxRank) maxRank = r;
-		if ((r === 3 || r === 2) && out.reason !== void 0 && out.reason.length > 0) {
-			const list = reasonsByRank.get(r) ?? [];
-			list.push(out.reason);
-			reasonsByRank.set(r, list);
-		}
-		if (out.continue === false && !stop) {
-			stop = true;
-			if (out.stopReason !== void 0) stopReason = out.stopReason;
-		}
-		if (out.additionalContext !== void 0 && out.additionalContext.length > 0) additionalContext.push(out.additionalContext);
-		if (out.systemMessage !== void 0 && out.systemMessage.length > 0) systemMessages.push(out.systemMessage);
-	}
-	const reasons = reasonsByRank.get(maxRank) ?? [];
-	return {
-		decision: decisionForRank(maxRank),
-		...reasons.length > 0 ? { reason: reasons.join("\n\n") } : {},
-		stop,
-		...stopReason !== void 0 ? { stopReason } : {},
-		additionalContext,
-		systemMessages
-	};
-}
-//#endregion
-//#region lib/types/events.js
-/**
-* Append helpers for durable, log-only hook events. They carry no surface
-* intent and must remain turn-enclosed and invoked/result paired. Mid-turn hook
-* points satisfy that boundary; SessionStart records injected context instead
-* and does not append `hook/*` outside a turn.
-* @module @hasna-internal/kai-hook-protocol/events
-*/
-/**
-* The reference default for {@link HookResultRecord.stderrSummaryMaxChars}
-* (both bridges' config default). It lives here, once, next to the truncation
-* rule it bounds, so the bridges cannot drift apart on the shared event's
-* default cap.
-*/
-const DEFAULT_STDERR_SUMMARY_MAX_CHARS = 500;
-/**
-* Truncate a hook's stderr for {@link HookResultRecord.stderrSummary}: trimmed,
-* `undefined` when empty, cut at `maxChars` with an ellipsis when over. The
-* bound is a parameter — like `runHook`'s `defaultTimeoutMs`, each bridge owns
-* the config default and passes it in.
-* @param stderr - the hook's raw captured stderr.
-* @param maxChars - the character cap for the summary (the bridge's config value).
-* @returns the trimmed, capped summary, or `undefined` when stderr is blank.
-*/
-function summarizeStderr(stderr, maxChars) {
-	const t = stderr.trim();
-	if (t.length === 0) return void 0;
-	return t.length > maxChars ? t.slice(0, maxChars) + "…" : t;
-}
-/**
-* 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.
-*/
-function appendHookInvoked(session, invocation) {
-	session.append("hook/invoked", {
-		turn: invocation.turn,
-		point: invocation.point,
-		dialect: invocation.dialect,
-		handlerId: invocation.handlerId,
-		...invocation.matcher !== void 0 ? { matcher: invocation.matcher } : {}
-	});
-}
-/**
-* Append the durable result paired with `hook/invoked`. The recorded decision
-* is the parsed decision, then `stop` for `continue:false`, else `pass`; stderr
-* is trimmed and capped, and an absent process exit stays omitted.
-* @param session - the session whose open turn records the event.
-* @param record - the outcome to record: the decoded output plus the summary cap and duration.
-*/
-function appendHookResult(session, record) {
-	const { output } = record;
-	const stderrSummary = summarizeStderr(output.stderr, record.stderrSummaryMaxChars);
-	session.append("hook/result", {
-		turn: record.turn,
-		point: record.point,
-		handlerId: record.handlerId,
-		decision: output.decision ?? (output.continue === false ? "stop" : "pass"),
-		...output.exitCode !== void 0 ? { exitCode: output.exitCode } : {},
-		...stderrSummary !== void 0 ? { stderrSummary } : {},
-		durationMs: record.durationMs
-	});
-}
-//#endregion
-//#region lib/types/detached.js
-/**
-* Quiescence tracking for emit-shaped hook runs that no extension point awaits. Bridges
-* track the run plus its continuation, pass the tracker signal into execution,
-* and drain on disposal so no process or late callback outlives the fiber.
-* @module @hasna-internal/kai-hook-protocol/detached
-*/
-/**
-* Create a {@link DetachedRuns} tracker (one per bridge `apply()`); settled
-* runs are pruned so a long-lived session does not accumulate them.
-* @returns the tracker.
-*/
-function createDetachedRuns() {
-	const inflight = /* @__PURE__ */ new Set();
-	const controller = new AbortController();
-	return {
-		signal: controller.signal,
-		track(run) {
-			inflight.add(run);
-			const settled = () => {
-				inflight.delete(run);
-			};
-			run.then(settled, settled);
-		},
-		async drain() {
-			controller.abort(/* @__PURE__ */ new Error("hook bridge disposed"));
-			while (inflight.size > 0) await Promise.allSettled([...inflight]);
-		}
-	};
-}
-//#endregion
-export { DEFAULT_HOOK_TIMEOUT_MS, DEFAULT_STDERR_SUMMARY_MAX_CHARS, appendHookInvoked, appendHookResult, createDetachedRuns, matcherDiagnostic, matchesMatcher, mergeHookOutputs, parseHookOutput, runHook, summarizeStderr };

package/lib/invariant.js

@@ -1,97 +0,0 @@
-//#region lib/types/invariant.js
-/** Package-owned hook invocation/result stream invariants. @module @hasna-internal/kai-hook-protocol/invariant */
-const PACKAGE_NAME = "@hasna-internal/kai-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.events) {
-			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/codec.d.ts

@@ -1,21 +0,0 @@
-/**
- * Decode hook process outcomes for both dialects. Exit 0 may carry structured
- * JSON or plain stdout; exit 2 blocks with stderr as the reason; every other
- * exit is a non-blocking error. Bridges decide which recognized fields apply.
- * @module @hasna-internal/kai-hook-protocol/codec
- */
-import type { HookOutput } from './types.ts';
-/**
- * Decode process output into a dialect-neutral hook outcome. This function is
- * total: malformed JSON remains plain stdout. When `expectedEventName` is set,
- * a missing or different `hookSpecificOutput.hookEventName` discards only its
- * event-scoped fields; top-level fields and the claimed discriminator remain.
- * Omitting the guard applies the block as-is.
- * @param exitCode - process exit, or `undefined` when spawn failed.
- * @param stdout - output parsed as structured JSON only on exit 0.
- * @param stderr - the captured stderr stream; becomes the blocking `reason` on exit 2.
- * @param expectedEventName - firing event used to guard hook-specific fields; omit to disable the guard.
- * @returns the dialect-neutral decoded outcome.
- */
-export declare function parseHookOutput(exitCode: number | undefined, stdout: string, stderr: string, expectedEventName?: string): HookOutput;
-//# sourceMappingURL=codec.d.ts.map

package/lib/types/detached.d.ts

@@ -1,42 +0,0 @@
-/**
- * Quiescence tracking for emit-shaped hook runs that no extension point awaits. Bridges
- * track the run plus its continuation, pass the tracker signal into execution,
- * and drain on disposal so no process or late callback outlives the fiber.
- * @module @hasna-internal/kai-hook-protocol/detached
- */
-/** In-flight registry for one bridge's detached hook runs; see the module doc for the wiring contract. */
-export interface DetachedRuns {
-    /**
-     * The abort signal every tracked run must hand to {@link runHook} (via its
-     * `signal` option). {@link drain} fires it so a still-running hook process is
-     * killed rather than awaited out to its timeout (default 10 minutes).
-     */
-    readonly signal: AbortSignal;
-    /**
-     * Register one detached run until it settles. Pass the FULL chain — the hook
-     * run and its continuation/error handler — so {@link drain} waits for the
-     * side effects (an inject, a warn), not just the process exit. A rejected
-     * chain is absorbed here (settlement bookkeeping only), but rejection
-     * handling is still the caller's job: an untracked `.catch` is what turns a
-     * failure into a logged warning instead of silence.
-     * @param run - the detached run chain to hold until settled.
-     */
-    track(run: Promise<unknown>): void;
-    /**
-     * Abort {@link signal}, then resolve once every tracked chain has settled —
-     * including chains tracked while the drain is in progress. The bridge
-     * registers this as its effect disposer; cordis awaits it, so
-     * `fiber.dispose()` resolving means the bridge's detached work is quiescent.
-     * A run tracked AFTER drain resolves is not awaited by anyone — by then the
-     * bridge's listeners are disposed, so nothing can start one.
-     * @returns resolves when all tracked runs have settled.
-     */
-    drain(): Promise<void>;
-}
-/**
- * Create a {@link DetachedRuns} tracker (one per bridge `apply()`); settled
- * runs are pruned so a long-lived session does not accumulate them.
- * @returns the tracker.
- */
-export declare function createDetachedRuns(): DetachedRuns;
-//# sourceMappingURL=detached.d.ts.map

package/lib/types/events.d.ts

@@ -1,74 +0,0 @@
-/**
- * Append helpers for durable, log-only hook events. They carry no surface
- * intent and must remain turn-enclosed and invoked/result paired. Mid-turn hook
- * points satisfy that boundary; SessionStart records injected context instead
- * and does not append `hook/*` outside a turn.
- * @module @hasna-internal/kai-hook-protocol/events
- */
-import type { Session } from '@hasna-internal/kai-session';
-import type { HookDialect, HookOutput } from './types.ts';
-/** What identifies a hook invocation across its invoked/result pair. */
-export interface HookInvocation {
-    /** The open turn the invocation lives inside. */
-    turn: number;
-    /** The hook point (`PreToolUse`, `Stop`, …). */
-    point: string;
-    /** The bridge dialect that ran it. */
-    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 decided outcome half of the pair. */
-export interface HookResultRecord {
-    turn: number;
-    point: string;
-    handlerId: string;
-    /**
-     * The decoded outcome the run produced. {@link appendHookResult} derives the
-     * durable `decision`/`exitCode`/`stderrSummary` fields from it, so the shared
-     * event's semantics live here, in the lib that declares it, not per-bridge.
-     */
-    output: HookOutput;
-    /**
-     * Character cap for the derived `stderrSummary`. The bound is the bridge's
-     * to own (its `stderrSummaryMaxChars` config) and is passed in explicitly —
-     * {@link DEFAULT_STDERR_SUMMARY_MAX_CHARS} is the reference default.
-     */
-    stderrSummaryMaxChars: number;
-    /** Wall-clock duration of the run (from `runHook`) — durable audit timing. */
-    durationMs: number;
-}
-/**
- * The reference default for {@link HookResultRecord.stderrSummaryMaxChars}
- * (both bridges' config default). It lives here, once, next to the truncation
- * rule it bounds, so the bridges cannot drift apart on the shared event's
- * default cap.
- */
-export declare const DEFAULT_STDERR_SUMMARY_MAX_CHARS = 500;
-/**
- * Truncate a hook's stderr for {@link HookResultRecord.stderrSummary}: trimmed,
- * `undefined` when empty, cut at `maxChars` with an ellipsis when over. The
- * bound is a parameter — like `runHook`'s `defaultTimeoutMs`, each bridge owns
- * the config default and passes it in.
- * @param stderr - the hook's raw captured stderr.
- * @param maxChars - the character cap for the summary (the bridge's config value).
- * @returns the trimmed, capped summary, or `undefined` when stderr is blank.
- */
-export declare function summarizeStderr(stderr: string, maxChars: number): string | undefined;
-/**
- * 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.
- */
-export declare function appendHookInvoked(session: Session, invocation: HookInvocation): void;
-/**
- * Append the durable result paired with `hook/invoked`. The recorded decision
- * is the parsed decision, then `stop` for `continue:false`, else `pass`; stderr
- * is trimmed and capped, and an absent process exit stays omitted.
- * @param session - the session whose open turn records the event.
- * @param record - the outcome to record: the decoded output plus the summary cap and duration.
- */
-export declare function appendHookResult(session: Session, record: HookResultRecord): void;
-//# sourceMappingURL=events.d.ts.map

package/lib/types/index.d.ts

@@ -1,19 +0,0 @@
-/**
- * Shared, non-plugin hook protocol library: matching, command execution and
- * decoding, restrictive outcome merging, durable event helpers, and detached
- * run quiescence. Claude Code and Codex bridges own their distinct payloads,
- * environment rules, matcher mode, and typed extension-point mappings.
- * @module @hasna-internal/kai-hook-protocol
- */
-export type { CommandHook, HookDialect, HookOutput, MatcherGroup, MatcherMode, } from './types.ts';
-export { matcherDiagnostic, matchesMatcher } from './matcher.ts';
-export { parseHookOutput } from './codec.ts';
-export { DEFAULT_HOOK_TIMEOUT_MS, runHook } from './runner.ts';
-export type { RunHookOptions, RunHookResult } from './runner.ts';
-export { mergeHookOutputs } from './merge.ts';
-export type { MergedDecision, MergedHookOutcome } from './merge.ts';
-export { appendHookInvoked, appendHookResult, DEFAULT_STDERR_SUMMARY_MAX_CHARS, summarizeStderr } from './events.ts';
-export type { HookInvocation, HookResultRecord } from './events.ts';
-export { createDetachedRuns } from './detached.ts';
-export type { DetachedRuns } from './detached.ts';
-//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -1,13 +0,0 @@
-/** Package-owned hook invocation/result stream invariants. @module @hasna-internal/kai-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

package/lib/types/matcher.d.ts

@@ -1,29 +0,0 @@
-/**
- * Matcher 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 @hasna-internal/kai-hook-protocol/matcher
- */
-import type { MatcherMode } from './types.ts';
-/**
- * Validate one matcher before a bridge accepts its config group.
- * @param matcher - configured pattern; match-all sentinels are valid.
- * @param mode - dialect deciding whether a word-and-pipe pattern is literal.
- * @returns `undefined` for a valid matcher, otherwise a stable diagnostic.
- */
-export declare function matcherDiagnostic(matcher: string | undefined, mode: MatcherMode): string | undefined;
-/**
- * Whether `matcher` selects `query` under the given dialect. Claude literal
- * patterns exact-match pipe-separated alternatives; all other patterns are
- * unanchored regexes. Invalid regexes return `false` rather than throwing;
- * bridge config parsers surface them through {@link matcherDiagnostic} before use.
- * @param matcher - the configured pattern; absent/empty/`'*'` are the match-all sentinels.
- * @param query - the candidate value (a tool name, a session source, …).
- * @param mode - the dialect deciding literal-vs-regex interpretation of the pattern.
- * @returns `true` when the pattern selects the query; `false` on a non-match or an invalid
- *   regex.
- */
-export declare function matchesMatcher(matcher: string | undefined, query: string, mode: MatcherMode): boolean;
-//# sourceMappingURL=matcher.d.ts.map

package/lib/types/merge.d.ts

@@ -1,39 +0,0 @@
-/**
- * Merge matched hooks into one most-restrictive outcome. Permission precedence
- * is `deny > ask > allow`; the first `continue:false` stop is sticky; reasons
- * for the winning rank are joined; and context and system messages accumulate
- * in hook order.
- * @module @hasna-internal/kai-hook-protocol/merge
- */
-import type { HookOutput } from './types.ts';
-/** The single decision a hook point resolves to after merging all matched hooks. */
-export type MergedDecision = 'allow' | 'ask' | 'deny' | 'none';
-/** The folded outcome of every hook that matched one point. */
-export interface MergedHookOutcome {
-    /**
-     * The most-restrictive permission decision across all hooks (`deny` > `ask` >
-     * `allow`), or `none` when no hook expressed one. `block`/`deny` both fold to
-     * `deny`; `approve`/`allow` both fold to `allow`.
-     */
-    decision: MergedDecision;
-    /** Joined (`\n\n`) reasons from every blocking/denying hook, or `undefined`. */
-    reason?: string;
-    /** `true` when any hook asked to halt (`continue:false`). */
-    stop: boolean;
-    /** The first halting hook's `stopReason`, when one halted. */
-    stopReason?: string;
-    /** Every hook's `additionalContext`, in hook order (no joining — the bridge decides). */
-    additionalContext: string[];
-    /** Every hook's `systemMessage`, in hook order. */
-    systemMessages: string[];
-}
-/**
- * Fold `outputs` (the results of every hook that matched a point, in hook order)
- * into one {@link MergedHookOutcome} by the precedence rules above. An empty list
- * yields a neutral outcome (`decision: 'none'`, no stop, empty context) — the
- * caller treats that as "no hook had anything to say".
- * @param outputs - every matched hook's decoded output, in hook order.
- * @returns the single folded outcome the bridge maps onto its extension point.
- */
-export declare function mergeHookOutputs(outputs: HookOutput[]): MergedHookOutcome;
-//# sourceMappingURL=merge.d.ts.map

package/lib/types/runner.d.ts

@@ -1,62 +0,0 @@
-/**
- * Execute command hooks through `ctx.shell`, using its credential scrub,
- * process-group cancellation, and timeout machinery. The bridge supplies the
- * trusted stdin payload and dialect environment, then this module decodes the
- * captured outcome.
- * @module @hasna-internal/kai-hook-protocol/runner
- */
-import type { ShellExecutor } from '@hasna-internal/kai-shell';
-import type { CommandHook, HookOutput } from './types.ts';
-/**
- * The reference default per-hook timeout, in ms (10 minutes) — the value both
- * Claude Code and Codex apply to a hook whose config sets no `timeout`. It
- * lives here, once, as the protocol's default; the bridges' `defaultTimeoutMs`
- * config defaults to it, and a per-hook {@link CommandHook.timeoutSec} is the
- * override API.
- */
-export declare const DEFAULT_HOOK_TIMEOUT_MS = 600000;
-/** Everything a single hook invocation needs beyond its command line. */
-export interface RunHookOptions {
-    /** The JSON payload object written to the hook's stdin (the bridge builds it). */
-    payload: unknown;
-    /** Extra env vars for the hook process (`CLAUDE_PROJECT_DIR`, …); the bridge builds these. */
-    env?: Record<string, string>;
-    /** Working directory for the hook (defaults to the executor's own default when omitted). */
-    cwd?: string;
-    /** Explicit owning-operation signal; firing it cancels the hook run. */
-    readonly signal: AbortSignal;
-    /** Whether to append a trailing newline to the stdin payload (CC yes, Codex no). */
-    trailingNewline: boolean;
-    /**
-     * Timeout applied when the hook's config sets no `timeout` of its own. The
-     * bridge owns the default (its `defaultTimeoutMs` config, reference default
-     * {@link DEFAULT_HOOK_TIMEOUT_MS}) and passes it in explicitly.
-     */
-    defaultTimeoutMs: number;
-    /**
-     * The event this hook is firing for (e.g. `'PreToolUse'`). When set, a
-     * structured `hookSpecificOutput` block whose `hookEventName` names a DIFFERENT
-     * event is treated as malformed and its event-scoped fields are discarded (see
-     * {@link parseHookOutput}). Omit it to apply any block as-is.
-     */
-    expectedEventName?: string;
-}
-/** The {@link HookOutput} plus the wall-clock duration of the run (for `hook/result`). */
-export interface RunHookResult {
-    output: HookOutput;
-    /** Wall-clock duration of the run, from `now` — durable on the `hook/result` event. */
-    durationMs: number;
-}
-/**
- * Run `hook` with serialized stdin and decode its outcome. A hook-specific
- * timeout in seconds overrides the default; trusted environment entries merge
- * after the executor scrub. Infrastructure rejection becomes an outcome with
- * no exit code, so this function never throws or crashes the calling turn.
- * @param bash - The executor service the command runs through.
- * @param hook - the configured command; its `timeoutSec` (wire unit: seconds) overrides the default timeout.
- * @param options - the invocation's payload, env, cwd, signal, stdin framing, and default timeout.
- * @param now - millisecond clock used for the reported duration.
- * @returns the decoded output plus the run's wall-clock duration.
- */
-export declare function runHook(bash: ShellExecutor, hook: CommandHook, options: RunHookOptions, now: () => number): Promise<RunHookResult>;
-//# sourceMappingURL=runner.d.ts.map

package/lib/types/types.d.ts

@@ -1,132 +0,0 @@
-/**
- * Dialect-neutral vocabulary and log-only events shared by the Claude Code and
- * Codex hook bridges. Payload construction, matching differences, environment,
- * and extension-point-specific decision mapping remain owned by each bridge.
- * @module @hasna-internal/kai-hook-protocol/types
- */
-declare module '@hasna-internal/kai-session/types' {
-    interface SessionEventMap {
-        /**
-         * A hook command was invoked at a hook point — a log-only record (like
-         * `compaction/*`; NOT a {@link SurfaceEventType}, carries no `surfaceOp`).
-         * `dialect` is the bridge that ran it (`claude`/`codex`), `point`
-         * the hook point (`PreToolUse`, `Stop`, …), `matcher` the matcher-group
-         * pattern that selected it (absent for match-all), `handlerId` a stable id
-         * for the command (so an invoked/result pair correlates). `turn` is the open
-         * turn the invocation lives inside.
-         */
-        'hook/invoked': {
-            turn: number;
-            point: string;
-            dialect: HookDialect;
-            matcher?: string;
-            handlerId: string;
-        };
-        /**
-         * Log-only outcome paired to `hook/invoked` by `handlerId`. Decision is the
-         * parsed permission result, `stop` for `continue:false`, or `pass`; exit code
-         * may be absent, stderr is bounded, and duration is wall-clock runtime.
-         */
-        'hook/result': {
-            turn: number;
-            point: string;
-            handlerId: string;
-            decision: string;
-            exitCode?: number;
-            stderrSummary?: string;
-            durationMs: number;
-        };
-    }
-}
-/**
- * The bridge that ran a hook — the CC bridge stamps `'claude-code'`, the Codex
- * bridge `'codex'`. A native plugin at the interception points is not a bridge
- * and writes no `hook/*` invocation/result records (see the interception extension-points Agent Note).
- */
-export type HookDialect = 'claude-code' | 'codex';
-/**
- * One configured command hook (the `{ type: 'command', command, timeout? }`
- * shape shared by both dialects). Non-command hook types (CC's `prompt`/`agent`/
- * `http`) are parsed-and-skipped by a bridge, so only this shape reaches the
- * runner.
- */
-export interface CommandHook {
-    /** The shell command line to run. */
-    command: string;
-    /** Per-hook timeout in SECONDS (the wire unit); the runner converts to ms. */
-    timeoutSec?: number;
-}
-/**
- * One matcher group: a `matcher` pattern (absent / `''` / `'*'` = match-all)
- * plus the command hooks that run when it matches. Both dialects share this
- * shape (CC's `hooks.json` and Codex's `hooks.json`).
- */
-export interface MatcherGroup {
-    matcher?: string;
-    hooks: CommandHook[];
-}
-/**
- * How a matcher pattern is interpreted. Claude Code uses {@link literal} when the
- * pattern is purely `[A-Za-z0-9_|]+` (pipe = exact-match alternation) and
- * {@link regex} otherwise; Codex is always {@link regex}. The bridge picks the
- * mode for its dialect.
- */
-export type MatcherMode = 'claude-code' | 'codex';
-/**
- * The dialect-neutral OUTCOME a hook produced, parsed from its exit code +
- * stdout JSON + stderr by {@link parseHookOutput}. A bridge maps this onto a
- * extension-point-specific typed Decision (PreToolDecision, PreStepDecision, …). Every field
- * is OPTIONAL because a hook may exercise any subset; the bridge decides which
- * fields are meaningful for its hook point and which it ignores (faithful-but-
- * degraded — e.g. Codex ignores `allow`/`ask`).
- */
-export interface HookOutput {
-    /** The raw process exit code (`undefined` if the hook could not be run). */
-    exitCode: number | undefined;
-    /** Trimmed stderr — the block-reason source on a blocking (exit 2) hook. */
-    stderr: string;
-    /**
-     * Trimmed stdout, verbatim. On a clean exit a hook may emit PLAIN (non-JSON)
-     * stdout that the protocol renders as output (CC) or treats as
-     * `additionalContext` (Codex SessionStart/UserPromptSubmit) — so the bridge
-     * needs the raw text, not just the parsed structured fields. Empty string when
-     * the hook produced no stdout.
-     */
-    stdout: string;
-    /**
-     * `false` ⇒ the hook asked to halt (CC/Codex `continue:false`); pairs with
-     * {@link stopReason}. `true`/absent ⇒ proceed.
-     */
-    continue?: boolean;
-    /** Human-readable reason shown when {@link continue} is `false`. */
-    stopReason?: string;
-    /**
-     * The neutral blocking decision a hook expressed, folded from the two channels
-     * the reference protocols keep DISTINCT: the legacy top-level `decision`
-     * (`approve`/`block` only) and `hookSpecificOutput.permissionDecision`
-     * (`allow`/`deny`/`ask`). We normalize them to one enum — `'block'`/`'deny'`
-     * forbid, `'approve'`/`'allow'` permit, `'ask'` requests confirmation — but
-     * `'allow'`/`'deny'`/`'ask'` arise ONLY from a `permissionDecision`, never from
-     * a top-level `decision` (an out-of-band `{"decision":"deny"}` is invalid and
-     * ignored, matching the schemas). Absent ⇒ no explicit decision (exit code governs).
-     */
-    decision?: 'approve' | 'allow' | 'block' | 'deny' | 'ask';
-    /** The reason/explanation accompanying {@link decision}. */
-    reason?: string;
-    /**
-     * Event discriminator claimed by `hookSpecificOutput`. On mismatch,
-     * {@link parseHookOutput} preserves this value but discards event-scoped fields.
-     */
-    hookEventName?: string;
-    /** Extra context to inject for the next model request (CC `additionalContext`). */
-    additionalContext?: string;
-    /** A warning surfaced to the user (CC `systemMessage`). */
-    systemMessage?: string;
-    /**
-     * A tool-input rewrite a hook requested (CC `updatedInput`). PARSED but NOT
-     * honored — input rewrite is deferred (see the interception extension-points Agent Note); a
-     * bridge logs + warns when this is present.
-     */
-    updatedInput?: Record<string, unknown>;
-}
-//# sourceMappingURL=types.d.ts.map