dsh-hooks 0.10.0 → 0.11.0

package/README.md

@@ -54,6 +54,18 @@ Add a config block to your profile's `cordis.patch.yml`:
           channel: 'webhook'         # POST JSON to any HTTP endpoint
           url: 'https://hooks.slack.com/services/…'
           slack: true                # optional: { text } one-line summary (Slack style)
+      - on: 'step/end'
+        run: 'node examples/log-step.mjs'
+        debounceMs: 500              # optional: debounce high-frequency events
+        maxConcurrent: 2             # optional: cap concurrent processes
+      - on: 'tool/result'
+        match:
+          toolDurationMs: '>10000'   # numeric comparison ({ gt: 10000 } object form too)
+        run: 'node examples/notify-slow-tool.mjs'
+      - on: 'turn/end'
+        enabled: false               # optional: disable without deleting
+        cwd: 'session'               # optional: run in the session working directory
+        run: 'node examples/log-turn.mjs'
 ```
 
 Every hook field:
@@ -62,24 +74,28 @@ Every hook field:
 | --- | --- | --- |
 | `on` | triggering event (see the event table) | required |
 | `when` | filter `turn/end` by end reason | all reasons |
-| `match` | field → regex, all must match; fields are context keys (`tool` / `sessionName` / `sessionId` / `error` / `source` / `cwd` / `content` / `reason`, …), a field absent from the context never matches | no filter |
+| `match` | field → regex or numeric comparison, all must match; fields are context keys (`tool` / `sessionName` / `sessionId` / `error` / `source` / `cwd` / `content` / `reason` / `turn` / `durationMs` / `toolDurationMs`, …), a field absent from the context never matches. Regexes test the string form; comparisons (`{ gt: 10000 }` or `'>10000'`, ops `gt` / `gte` / `lt` / `lte` / `eq`, combinable) apply only to numeric fields and never match non-numeric ones | no filter |
 | `run` | command spawned through the platform shell (exactly one of `run` / `notify`) | one of the two required |
 | `notify` | built-in notification (exactly one of `run` / `notify`): `channel: webhook` (HTTP JSON; omit `url` to use `DSH_HOOKS_WEBHOOK_URL`, `slack: true` for a one-line summary) or `channel: desktop` (platform balloon/toast) | one of the two required |
 | `input` | `env` passes only the `DSH_HOOK_*` variables; `stdin` additionally writes the full context JSON to the command's stdin | `env` |
 | `timeoutMs` | per-run timeout (ms); the process tree is terminated on expiry | 10000 |
 | `retries` | retry count for non-zero exit codes (spawn failures and timeouts never retry) | 0 |
 | `retryDelayMs` | base delay between retries (ms), doubles per attempt | 500 |
+| `enabled` | `false` disables the hook without deleting it: the declaration stays, dispatch skips it silently (never counts as a failure) | `true` |
+| `cwd` | working directory for the spawned command: `session` runs in the session's cwd, an absolute path runs there (`run` only) | plugin process directory |
+| `maxConcurrent` | max concurrently running processes for this hook; triggers beyond the cap are dropped (recorded as `skipped`) | unlimited |
+| `debounceMs` | debounce window (ms): triggers of high-frequency events (`step/end`, `tool/*`, …) inside the window collapse into one trailing execution carrying the latest context | 0 (off) |
 
 ## Events (v1)
 
 | Event | When it fires | Useful context |
 | --- | --- | --- |
-| `turn/start` | A turn begins | session id, turn |
+| `turn/start` | A turn begins (with `turn/start` hooks, dispatch waits for the turn's first direct user message and attaches its text as `DSH_HOOK_CONTENT`; turns without one dispatch content-less at `turn/end`, see below) | session id, turn, initiating message text |
 | `turn/end` | A turn ends (`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`) | reason, turn, duration, content, turn token usage, running subagents |
 | `tree/settled` | A watched session's whole subagent tree settles (no live child still running) after a turn ended with work handed off | total subagents, handoff→settle duration |
 | `step/end` | One step of a turn ends (one model call plus its tool executions) | turn, step |
 | `tool/call` | The model requests one tool invocation | tool name, call id, raw arguments JSON |
-| `tool/result` | A tool call completes | tool name (resolved), result text, failure identity |
+| `tool/result` | A tool call completes | tool name (resolved), result text, failure identity, wall-clock duration (absent when the pairing call was never seen) |
 | `user/message` | A user-role message appears on the surface | source kind (`user` / `plugin` / …), message text |
 | `approval/asked` | A tool call requests user approval | tool name, call id, approval id, reason |
 | `approval/decided` | A pending approval gets its outcome (paired with `approval/asked` by id) | outcome, tool name (resolved), call id, approval id |
@@ -112,11 +128,12 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_CALL_ID` | tool call id (approval / tool events) |
 | `DSH_HOOK_TOOL_ARGS` | raw tool arguments JSON (tool/call) |
 | `DSH_HOOK_TOOL_ERROR` | tool failure identity `name: code` (tool/result errors) |
+| `DSH_HOOK_TOOL_DURATION_MS` | wall-clock tool execution ms (tool/result; absent when the pairing tool/call was never seen) |
 | `DSH_HOOK_SOURCE` | message / title source kind (`user`, `plugin`, `fallback`, `provider`, …) |
 | `DSH_HOOK_DURATION_MS` | turn duration ms (turn/end) |
 | `DSH_HOOK_STATUS` | agent status (`agent/status`) |
 | `DSH_HOOK_ERROR` | error text (`agent/error`, and the failure message on `turn/end` error) |
-| `DSH_HOOK_CONTENT` | event content snapshot: turn assistant text, tool result text, user message text |
+| `DSH_HOOK_CONTENT` | event content snapshot: turn assistant text, tool result text, user message text, turn-initiating message text (turn/start) |
 | `DSH_HOOK_USAGE_INPUT_TOKENS` | aggregated input tokens of the turn (turn/end, summed across steps) |
 | `DSH_HOOK_USAGE_OUTPUT_TOKENS` | aggregated output tokens of the turn |
 | `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | aggregated cache-read tokens, when reported |
@@ -167,6 +184,62 @@ For the simpler "notify only once the whole tree settles" pattern, the synthetic
 
 Settled-but-idle continuable children do not count as running, so they don't keep suppressing the notification. The settle watch is event-driven and best-effort: it survives until the plugin restarts, and a failed re-check drops the watch silently (no late notification).
 
+### Numeric match comparisons
+
+Numeric context fields (`turn`, `step`, `durationMs`, `toolDurationMs`, `usage*`, `runningSubagents`, …) support real comparisons instead of regex hacks:
+
+```yaml
+- on: 'tool/result'
+  match: { toolDurationMs: '>10000' }   # string syntax: > >= < <= =
+  run: 'node examples/notify-slow-tool.mjs'
+
+- on: 'tool/result'
+  match:
+    toolDurationMs: { gt: 10000, lt: 60000 }   # object syntax: gt/gte/lt/lte/eq, combinable
+  run: 'node examples/notify-slow-tool.mjs'
+```
+
+Rules:
+
+- Comparison semantics apply only to **numeric** fields; on a string field a comparison **never matches** (no string coercion).
+- A string value counts as a comparison only when it starts with `>` / `>=` / `<` / `<=` / `=` followed by a number (e.g. `'>10000'`); anything else stays a plain regex.
+- A missing field still never matches. An empty object `{}` matches vacuously.
+
+### Execution options: enabled / cwd / maxConcurrent / debounceMs
+
+Every hook can tune its execution independently:
+
+- **`enabled: false`** disables the hook but keeps the declaration. Skipping is silent — no history record, never part of a failure streak (`hook/failed` never fires for a disabled hook). dry-run marks it `enabled: false（已停用）`.
+- **`cwd: 'session'`** spawns `run` in the session's working directory (the project the agent works on), so hook scripts can read/write project files directly; an absolute path works too. Defaults to the plugin process directory.
+- **`maxConcurrent`** caps concurrent processes for the hook. Triggers beyond the cap are dropped and recorded as `skipped` (no failure alert); one logical run (its internal retries included) always occupies one slot.
+- **`debounceMs`** debounces high-frequency events (`step/end`, `tool/*`, …): triggers inside the window collapse into one **trailing** execution carrying the latest context. Collapsed triggers are fully silent — they never flood the log or history. New triggers after the window run normally.
+
+The recommended combination against `step/end` / `tool/*` spawn storms:
+
+```yaml
+- on: 'step/end'
+  run: 'node examples/log-step.mjs'
+  debounceMs: 500       # consecutive step ends within half a second run once
+  maxConcurrent: 2      # safety net: at most 2 processes even when slow
+```
+
+### turn/start carries the initiating message
+
+The session log records `turn/start` *before* the turn's `user/message`, so the prompt text is not readable at turn-start time. When `turn/start` hooks exist, the plugin defers their dispatch until the turn's first direct user message is classified, attaching its text as `DSH_HOOK_CONTENT` (capped at 2000 chars):
+
+```yaml
+- on: 'turn/start'
+  match: { content: 'deploy|release' }   # only turns asking about deploys
+  notify: { channel: 'desktop' }
+```
+
+Timing notes:
+
+- The deferral only kicks in when `turn/start` hooks exist; otherwise dispatch stays as before (immediate, no content).
+- Only direct user messages (`source.kind === 'user'`) complete the dispatch; synthetic injections (agent/plugin sources) do not.
+- A turn without a direct user message (e.g. a goal continuation round) dispatches `turn/start` **without content** at `turn/end`; a new turn flushes an unclaimed previous `turn/start` first.
+- For direct-user turns the delay is typically milliseconds (`user/message` immediately follows `turn/start`), still ahead of any step/tool events.
+
 ## Generic webhook example
 
 Besides Feishu, `examples/notify-webhook.mjs` posts the full hook context as one JSON document to any HTTP endpoint — Slack incoming webhooks, Discord, Lark/DingTalk custom bots, ntfy, Bark, n8n:
@@ -200,7 +273,7 @@ Every hook trigger is recorded into an in-memory ring buffer (default 500 entrie
     hooks: […]
 ```
 
-Each record: timestamp, kind (run/notify), event, command, session, outcome (spawned / exit-0 / exit-nonzero / timeout / sent / send-failed, …), exit code, duration, stderr tail. Disk failures are swallowed silently — history never blocks a hook.
+Each record: timestamp, kind (run/notify), event, command, session, outcome (spawned / exit-0 / exit-nonzero / timeout / skipped / sent / send-failed, …), exit code, duration, stderr tail. Disk failures are swallowed silently — history never blocks a hook.
 
 ## dry-run: verify config
 

package/README.zh.md

@@ -54,6 +54,18 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
           channel: 'webhook'         # POST JSON 到任意 HTTP 端点
           url: 'https://hooks.slack.com/services/…'
           slack: true                # 可选：改为 { text } 单行摘要（Slack 风格）
+      - on: 'step/end'
+        run: 'node examples/log-step.mjs'
+        debounceMs: 500              # 可选：高频事件去抖，窗口内合并为一次
+        maxConcurrent: 2             # 可选：并发上限，超出的触发被丢弃
+      - on: 'tool/result'
+        match:
+          toolDurationMs: '>10000'   # 数值比较（也支持 { gt: 10000 } 对象语法）
+        run: 'node examples/notify-slow-tool.mjs'
+      - on: 'turn/end'
+        enabled: false               # 可选：停用但不删除（跳过派发）
+        cwd: 'session'               # 可选：在会话工作目录执行
+        run: 'node examples/log-turn.mjs'
 ```
 
 每个 hook 的完整字段：
@@ -62,24 +74,28 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | --- | --- | --- |
 | `on` | 触发事件（见上方事件表） | 必填 |
 | `when` | 对 `turn/end` 按结束原因过滤 | 全部原因 |
-| `match` | 字段 → 正则，全部匹配才触发；字段为上下文键（`tool`/`sessionName`/`sessionId`/`error`/`source`/`cwd`/`content`/`reason`…），上下文中不存在的字段视为不匹配 | 不过滤 |
+| `match` | 字段 → 正则或数值比较，全部匹配才触发；字段为上下文键（`tool`/`sessionName`/`sessionId`/`error`/`source`/`cwd`/`content`/`reason`/`turn`/`durationMs`/`toolDurationMs`…），上下文中不存在的字段视为不匹配。正则匹配字段的字符串表示；数值比较（`{ gt: 10000 }` 或 `'>10000'`，支持 `gt`/`gte`/`lt`/`lte`/`eq` 组合）只对数字字段生效，非数字字段上的比较永不匹配 | 不过滤 |
 | `run` | 通过系统 shell 执行的命令（与 `notify` 二选一） | 二选一必填 |
 | `notify` | 内置通知（与 `run` 二选一）：`channel: webhook`（HTTP JSON，`url` 可省略用 `DSH_HOOKS_WEBHOOK_URL`，`slack: true` 换单行摘要）或 `channel: desktop`（系统气泡/toast） | 二选一必填 |
 | `input` | `env` 只传 `DSH_HOOK_*` 环境变量；`stdin` 额外把完整上下文 JSON 写入命令标准输入 | `env` |
 | `timeoutMs` | 单次执行超时（毫秒），超时终止进程树 | 10000 |
 | `retries` | 非零退出码的重试次数（spawn 失败与超时不重试） | 0 |
 | `retryDelayMs` | 重试基础间隔（毫秒），每次翻倍 | 500 |
+| `enabled` | `false` 停用该 hook：配置保留、静默跳过派发（不计入失败） | `true` |
+| `cwd` | 命令执行目录：`session` 在会话工作目录执行；绝对路径在指定目录执行（只作用于 `run`） | 插件进程目录 |
+| `maxConcurrent` | 该 hook 允许的最大并发进程数；超出的触发被丢弃（执行历史记 `skipped`） | 不限 |
+| `debounceMs` | 去抖窗口（毫秒）：高频事件（`step/end`、`tool/*`…）窗口内的多次触发合并为一次 trailing 执行，携带最新上下文 | 0（不去抖） |
 
 ## 事件（v1）
 
 | 事件 | 触发时机 | 有用上下文 |
 | --- | --- | --- |
-| `turn/start` | 回合开始 | 会话 id、回合号 |
+| `turn/start` | 回合开始（若有 `turn/start` hook，派发延迟到本回合的首条用户消息分类后，把触发文本注入 `DSH_HOOK_CONTENT`；无用户消息的回合在 `turn/end` 时无内容派发，见下方说明） | 会话 id、回合号、触发消息文本 |
 | `turn/end` | 回合结束（`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`） | reason、回合号、耗时、内容、本回合 token 用量、运行中子代理数 |
 | `tree/settled` | 回合结束后把工作交给子代理的会话，其整个子代理树全部落定（无存活子代理仍在运行） | 子代理总数、交接到落定的耗时 |
 | `step/end` | 回合内一步结束（一次模型调用 + 其工具执行） | 回合号、步号 |
 | `tool/call` | 模型请求一次工具调用 | 工具名、调用 id、原始参数 JSON |
-| `tool/result` | 工具调用完成 | 工具名（自动反查）、结果文本、失败标识 |
+| `tool/result` | 工具调用完成 | 工具名（自动反查）、结果文本、失败标识、工具耗时（配对失败时无耗时） |
 | `user/message` | 会话表面出现用户角色消息 | 来源 kind（`user` / `plugin` / …）、消息文本 |
 | `approval/asked` | 工具调用请求用户审批 | 工具名、调用 id、审批 id、原因 |
 | `approval/decided` | 待审批项得出结果（与 `approval/asked` 按 id 配对） | 结果 outcome、工具名（自动反查）、调用 id、审批 id |
@@ -112,11 +128,12 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_CALL_ID` | 工具调用 id（审批 / 工具事件） |
 | `DSH_HOOK_TOOL_ARGS` | 工具原始参数 JSON（tool/call） |
 | `DSH_HOOK_TOOL_ERROR` | 工具失败标识 `名称: 代码`（tool/result 出错时） |
+| `DSH_HOOK_TOOL_DURATION_MS` | 工具执行耗时毫秒（tool/result；配对 tool/call 丢失时无此变量） |
 | `DSH_HOOK_SOURCE` | 消息 / 标题来源 kind（`user`、`plugin`、`fallback`、`provider`…） |
 | `DSH_HOOK_DURATION_MS` | 回合耗时毫秒（turn/end） |
 | `DSH_HOOK_STATUS` | Agent 状态（agent/status） |
 | `DSH_HOOK_ERROR` | 错误文本（agent/error，以及 turn/end 出错时的失败详情） |
-| `DSH_HOOK_CONTENT` | 事件内容快照：回合最后助手文本、工具结果文本、用户消息文本 |
+| `DSH_HOOK_CONTENT` | 事件内容快照：回合最后助手文本、工具结果文本、用户消息文本、回合触发消息文本（turn/start） |
 | `DSH_HOOK_USAGE_INPUT_TOKENS` | 本回合输入 token 总量（turn/end，逐 step 聚合） |
 | `DSH_HOOK_USAGE_OUTPUT_TOKENS` | 本回合输出 token 总量 |
 | `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 本回合缓存读 token（有上报时） |
@@ -168,6 +185,62 @@ config:
 
 已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。落定监视是事件驱动且 best-effort 的：插件重启后监视集合丢失；重查失败会静默放弃该监视（不会补发迟到的通知）。
 
+### match 数值比较
+
+对数字字段（`turn`、`step`、`durationMs`、`toolDurationMs`、`usage*`、`runningSubagents`…）可以直接写数值比较，不用绕正则：
+
+```yaml
+- on: 'tool/result'
+  match: { toolDurationMs: '>10000' }   # 字符串语法：> >= < <= =
+  run: 'node examples/notify-slow-tool.mjs'
+
+- on: 'tool/result'
+  match:
+    toolDurationMs: { gt: 10000, lt: 60000 }   # 对象语法：gt/gte/lt/lte/eq 可组合
+  run: 'node examples/notify-slow-tool.mjs'
+```
+
+规则：
+
+- 比较语义只对**数字字段**生效；字段是字符串时比较**永不匹配**（不会把字符串转数字强比）。
+- 字符串语法以 `>`/`>=`/`<`/`<=`/`=` 开头且后跟数字才算比较（如 `'>10000'`）；其余字符串仍是普通正则。
+- 字段缺失照旧视为不匹配。空对象 `{}` 恒真（无任何条件）。
+
+### 执行选项：enabled / cwd / maxConcurrent / debounceMs
+
+每个 hook 都可以独立微调执行方式：
+
+- **`enabled: false`**：停用该 hook 但保留配置。跳过是静默的——不记执行历史、不计入失败链（`hook/failed` 不会因停用的 hook 触发）。dry-run 会标出 `enabled: false（已停用）`。
+- **`cwd: 'session'`**：在会话工作目录（agent 正在工作的项目目录）执行 `run`，方便 hook 脚本直接读写当前项目文件；`cwd` 也接受绝对路径。缺省在插件进程目录执行。
+- **`maxConcurrent`**：并发进程上限。超过上限的触发被丢弃并记入执行历史（`skipped`，不触发失败告警）；一次逻辑执行（含其内部重试）始终占用一个名额。
+- **`debounceMs`**：去抖窗口。高频事件（`step/end`、`tool/*`…）窗口内的多次触发合并为一次 **trailing** 执行，携带最新一次的上下文；被合并掉的触发完全静默，不会刷日志/历史。窗口结束后的新触发正常执行。
+
+防 `step/end`/`tool/*` spawn 风暴的推荐组合：
+
+```yaml
+- on: 'step/end'
+  run: 'node examples/log-step.mjs'
+  debounceMs: 500       # 半秒内的连续步结束只跑一次
+  maxConcurrent: 2      # 兜底：命令变慢时并发不超过 2
+```
+
+### turn/start 的触发内容
+
+会话日志先记录 `turn/start`、后记录该回合的 `user/message`，所以回合开始那一刻还读不到触发文本。插件因此把 `turn/start` 的派发**延迟到本回合首条直接用户消息分类后**，把消息文本注入 `DSH_HOOK_CONTENT`（截断 2000 字符）：
+
+```yaml
+- on: 'turn/start'
+  match: { content: '部署|发版' }   # 只关心包含关键词的回合
+  notify: { channel: 'desktop' }
+```
+
+时序说明：
+
+- 有 `turn/start` hook 时才启用延迟；没有的话派发保持原样（立即执行，无内容）。
+- 注入文本只认 `source.kind === 'user'` 的直接用户消息；系统注入（agent/plugin 来源）不会完成派发。
+- 回合内没有直接用户消息（如目标续跑回合）时，`turn/start` 在 `turn/end` 时**不带内容**派发；新回合开始会先冲掉上一个未认领的 `turn/start`。
+- 直接用户回合中，延迟通常只有几毫秒（`user/message` 紧随 `turn/start`），先于任何步骤/工具事件。
+
 ## 执行历史
 
 每次 hook 触发都会记入内存环形缓冲（默认 500 条），并 best-effort 追加到 `~/.dsh/dsh-hooks/history.jsonl`（权限 0600）——供未来 UI 与调试使用。环形缓冲在启动时从 JSONL 回填，且 Web 面板每次读取时增量同步磁盘上新增的记录（包括其他 dsh 进程的追加，如任务看板 Host），因此重启后历史不会消失。记录不含 secret（环境变量从不入记录）：
@@ -183,7 +256,7 @@ config:
     hooks: […]
 ```
 
-每条记录：时间戳、kind（run/notify）、事件、命令、会话、结果（spawned / exit-0 / exit-nonzero / timeout / sent / send-failed…）、退出码、耗时、stderr 尾部。写盘失败静默吞掉，绝不阻塞 hook。
+每条记录：时间戳、kind（run/notify）、事件、命令、会话、结果（spawned / exit-0 / exit-nonzero / timeout / skipped / sent / send-failed…）、退出码、耗时、stderr 尾部。写盘失败静默吞掉，绝不阻塞 hook。
 
 ## dry-run：验证配置
 

package/lib/client.js

@@ -252,6 +252,10 @@ window.__ModuleLoader__.load({
 			if (hook.timeoutMs !== void 0 && hook.timeoutMs !== 1e4) lines.push(`  timeoutMs: ${hook.timeoutMs}`);
 			if (hook.retries !== void 0 && hook.retries !== 0) lines.push(`  retries: ${hook.retries}`);
 			if (hook.retryDelayMs !== void 0 && hook.retryDelayMs !== 500) lines.push(`  retryDelayMs: ${hook.retryDelayMs}`);
+			if (hook.enabled === false) lines.push("  enabled: false");
+			if (hook.cwd !== void 0 && hook.cwd !== "") lines.push(`  cwd: ${q(hook.cwd)}`);
+			if (hook.maxConcurrent !== void 0) lines.push(`  maxConcurrent: ${hook.maxConcurrent}`);
+			if (hook.debounceMs !== void 0) lines.push(`  debounceMs: ${hook.debounceMs}`);
 			return lines.join("\n");
 		}
 		async function copyText(text) {
@@ -285,7 +289,11 @@ window.__ModuleLoader__.load({
 				notify: draft.notify ?? null,
 				timeoutMs: draft.timeoutMs,
 				retries: draft.retries,
-				retryDelayMs: draft.retryDelayMs
+				retryDelayMs: draft.retryDelayMs,
+				enabled: draft.enabled === false ? false : void 0,
+				cwd: draft.cwd === "" ? void 0 : draft.cwd,
+				maxConcurrent: draft.maxConcurrent,
+				debounceMs: draft.debounceMs
 			};
 		}
 		const NEW_HOOK = {
@@ -483,7 +491,11 @@ window.__ModuleLoader__.load({
 					},
 					timeoutMs: hook.timeoutMs,
 					retries: hook.retries,
-					retryDelayMs: hook.retryDelayMs
+					retryDelayMs: hook.retryDelayMs,
+					enabled: hook.enabled,
+					cwd: hook.cwd,
+					maxConcurrent: hook.maxConcurrent,
+					debounceMs: hook.debounceMs
 				})));
 				setSaveMessage(null);
 				setEditing(true);
@@ -1122,7 +1134,7 @@ window.__ModuleLoader__.load({
 												className: "dh-input",
 												value: pattern,
 												onChange: (e) => patchMatchValue(index, field, e.target.value),
-												placeholder: "正则（^(rm|git|ssh)）"
+												placeholder: "正则或数值比较（^(rm|git|ssh) / >10000）"
 											}),
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 												type: "button",
@@ -1187,6 +1199,67 @@ window.__ModuleLoader__.load({
 												children: "删除"
 											})
 										]
+									}),
+									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: "dh-test-row",
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+												className: "dh-field",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "dh-field-label",
+													children: "enabled"
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("select", {
+													className: "dh-input",
+													value: hook.enabled === false ? "false" : "true",
+													onChange: (e) => patchDraft(index, { enabled: e.target.value === "true" }),
+													children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+														value: "true",
+														children: "启用"
+													}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+														value: "false",
+														children: "停用"
+													})]
+												})]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+												className: "dh-field",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "dh-field-label",
+													children: "cwd"
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+													className: "dh-input",
+													value: hook.cwd ?? "",
+													onChange: (e) => patchDraft(index, { cwd: e.target.value }),
+													placeholder: "session 或绝对路径"
+												})]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+												className: "dh-field",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "dh-field-label",
+													children: "maxConcurrent"
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+													className: "dh-input",
+													type: "number",
+													value: hook.maxConcurrent ?? "",
+													onChange: (e) => patchDraft(index, { maxConcurrent: parseNum(e.target.value) }),
+													placeholder: "不限"
+												})]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+												className: "dh-field",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "dh-field-label",
+													children: "debounceMs"
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+													className: "dh-input",
+													type: "number",
+													value: hook.debounceMs ?? "",
+													onChange: (e) => patchDraft(index, { debounceMs: parseNum(e.target.value) }),
+													placeholder: "0"
+												})]
+											})
+										]
 									})
 								]
 							}, index)),
@@ -1244,7 +1317,7 @@ window.__ModuleLoader__.load({
 								}),
 								hook.match !== void 0 && Object.keys(hook.match).length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 									className: "dh-hook-match",
-									children: Object.entries(hook.match).map(([field, pattern]) => `${field} =~ /${pattern}/`).join("，")
+									children: Object.entries(hook.match).map(([field, pattern]) => /^([<>]=?|=)\s*-?\d/.test(pattern) ? `${field} ${pattern}` : `${field} =~ /${pattern}/`).join("，")
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 									className: "dh-hook-meta",
@@ -1256,10 +1329,14 @@ window.__ModuleLoader__.load({
 									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 										className: "dh-feishu-hint",
 										children: [
+											hook.enabled === false ? "已停用 · " : "",
 											"timeout ",
 											hook.timeoutMs ?? 1e4,
 											"ms · retries ",
-											hook.retries ?? 0
+											hook.retries ?? 0,
+											hook.cwd !== void 0 && hook.cwd !== "" ? ` · cwd: ${hook.cwd}` : "",
+											hook.maxConcurrent !== void 0 ? ` · 并发≤${hook.maxConcurrent}` : "",
+											hook.debounceMs !== void 0 && hook.debounceMs > 0 ? ` · 去抖 ${hook.debounceMs}ms` : ""
 										]
 									})]
 								})

package/lib/config.d.ts

@@ -17,7 +17,20 @@ export interface NotifySpec {
     /** webhook: post a Slack-style `{ text }` one-line summary instead of the full context document. */
     slack?: boolean;
 }
-/** One declared hook: a matching event runs `run` (or sends `notify`). */
+/**
+ * Numeric comparison filter for `match`: every declared op must hold for
+ * the (numeric) context field. Declared in YAML as an object (`{ gt: 10000 }`)
+ * or as an equivalent string (`'>10000'`); both compare against the field's
+ * number value, never its string form.
+ */
+export interface NumericMatch {
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    eq?: number;
+}
+/** One hook: a matching event runs `run` (or sends `notify`). */
 export interface HookSpec {
     /** Event that triggers the hook. */
     on: HookEvent;
@@ -27,12 +40,15 @@ export interface HookSpec {
      */
     when?: TurnEndReasonKind;
     /**
-     * Optional field → regex filters: every declared regex must match the
-     * context's field value for the hook to run. Fields are `HookContext`
-     * keys (`tool`, `sessionName`, `sessionId`, `error`, `source`, `cwd`,
-     * `content`, …); a field absent from the context never matches.
+     * Optional field → filter map: every declared filter must match the
+     * context's field value for the hook to run. Values are regexes (tested
+     * against the String-coerced field) or numeric comparisons (`{ gt: 10000 }`
+     * / `'>10000'`, numbers only). Fields are `HookContext` keys (`tool`,
+     * `sessionName`, `sessionId`, `error`, `source`, `cwd`, `content`, `turn`,
+     * `durationMs`, `runningSubagents`, …); a field absent from the context
+     * never matches.
      */
-    match?: Record<string, RegExp>;
+    match?: Record<string, RegExp | NumericMatch>;
     /**
      * Command to spawn through the platform shell. Exactly one of `run` and
      * `notify` must be declared.
@@ -55,6 +71,29 @@ export interface HookSpec {
     retries?: number;
     /** Base delay between retries in milliseconds; doubles per attempt. Defaults to 500. */
     retryDelayMs?: number;
+    /**
+     * Disable this hook without deleting it: the declaration stays in config,
+     * dispatch skips it silently (never counted as a failure). Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Working directory for the spawned command. `'session'` runs in the
+     * session's cwd (the project the agent works on); any other value must be
+     * an absolute path. Defaults to the plugin process directory.
+     */
+    cwd?: 'session' | string;
+    /**
+     * Maximum number of concurrently running processes for this hook.
+     * Triggers beyond the limit are dropped (recorded as `skipped`). Defaults
+     * to unlimited; `0` also means unlimited.
+     */
+    maxConcurrent?: number;
+    /**
+     * Debounce window in milliseconds for high-frequency events (step/end,
+     * tool/*, …): triggers inside the window collapse into one trailing
+     * execution carrying the latest context. Defaults to 0 (disabled).
+     */
+    debounceMs?: number;
 }
 /** Execution-history settings: in-memory ring buffer + optional JSONL log. */
 export interface HistoryConfig {

package/lib/config.js

@@ -36,7 +36,16 @@ export const Config = Schema.object({
     hooks: Schema.array(Schema.object({
         on: Schema.union([...HOOK_EVENTS]).description('触发事件：turn/start | turn/end | tree/settled | step/end | tool/call | tool/result | user/message | approval/asked | approval/decided | session/title | session/created | session/disposed | agent/created | agent/disposed | agent/error | agent/status | hook/failed'),
         when: Schema.union([...TURN_END_REASONS]).description('可选过滤：对 turn/end 匹配结束原因（completed/error/aborted/blocked/max-tokens/interrupted）；其他事件忽略该字段'),
-        match: Schema.dict(Schema.regExp()).description('可选通用过滤：字段 → 正则，全部匹配才触发。字段为上下文键（tool/sessionName/sessionId/error/source/cwd/content/reason/…），上下文中不存在的字段视为不匹配'),
+        match: Schema.dict(Schema.union([
+            Schema.regExp(),
+            Schema.object({
+                gt: Schema.number(),
+                gte: Schema.number(),
+                lt: Schema.number(),
+                lte: Schema.number(),
+                eq: Schema.number(),
+            }).description('数值比较（可组合，全部满足才匹配；要求上下文字段为数字）'),
+        ])).description('可选通用过滤：字段 → 正则或数值比较，全部匹配才触发。正则匹配字段的字符串表示；数值比较支持对象语法 { gt: 10000 } 或字符串语法 \'>10000\'（gt/gte/lt/lte/eq），只对数字字段生效，非数字字段永不匹配。字段为上下文键（tool/sessionName/sessionId/error/source/cwd/content/reason/turn/durationMs/runningSubagents/…），上下文中不存在的字段视为不匹配'),
         run: Schema.string().description('触发时通过系统 shell 执行的命令（与 notify 二选一）'),
         notify: Schema.union([
             Schema.object({
@@ -56,6 +65,12 @@ export const Config = Schema.object({
         timeoutMs: Schema.number().default(10000).description('单次执行超时（毫秒）'),
         retries: Schema.natural().default(0).description('非零退出码的重试次数（默认 0 不重试；spawn 失败与超时不重试）'),
         retryDelayMs: Schema.natural().default(500).description('重试基础间隔（毫秒），每次翻倍'),
+        enabled: Schema.boolean()
+            .default(true)
+            .description('停用开关：false 保留配置但跳过派发（静默跳过，不计失败；默认 true）'),
+        cwd: Schema.union([Schema.const('session'), Schema.string()]).description('执行工作目录：session 在会话工作目录执行；绝对路径在指定目录执行；缺省用插件进程目录（只作用于 run）'),
+        maxConcurrent: Schema.natural().description('该 hook 允许的最大并发进程数；超过上限的触发被丢弃（历史记 skipped）。缺省不限（0 同样视为不限）'),
+        debounceMs: Schema.natural().description('去抖窗口（毫秒）：高频事件（step/end、tool/* 等）窗口内的多次触发合并为一次 trailing 执行，携带最新上下文。缺省 0 = 不去抖'),
     }).description('一个事件 → 命令/通知的 hook 声明'))
         .default([])
         .description('事件触发时执行的外部命令列表；按声明顺序触发'),

package/lib/context.d.ts

@@ -30,6 +30,11 @@ export interface HookContext {
     error?: string;
     /** Event content snapshot: turn assistant text, tool result text, … */
     content?: string;
+    /**
+     * Wall-clock tool execution time, ms (tool/result only; undefined when the
+     * pairing tool/call was never seen, e.g. after a plugin restart).
+     */
+    toolDurationMs?: number;
     /** Aggregated token usage of the turn (turn/end), when reported. */
     usageInputTokens?: number;
     usageOutputTokens?: number;

package/lib/context.js

@@ -35,6 +35,8 @@ export function toEnv(ctx) {
         env.DSH_HOOK_ERROR = ctx.error;
     if (ctx.content !== undefined)
         env.DSH_HOOK_CONTENT = ctx.content;
+    if (ctx.toolDurationMs !== undefined)
+        env.DSH_HOOK_TOOL_DURATION_MS = String(ctx.toolDurationMs);
     if (ctx.usageInputTokens !== undefined)
         env.DSH_HOOK_USAGE_INPUT_TOKENS = String(ctx.usageInputTokens);
     if (ctx.usageOutputTokens !== undefined)

package/lib/dry-run.js

@@ -62,22 +62,37 @@ export function mockContext(event, overrides = {}) {
         ...overrides,
     };
 }
+/** Render a match value (regex source, comparison op, or object form). */
+function matchText(value) {
+    if (value instanceof RegExp)
+        return value.source;
+    return JSON.stringify(value);
+}
 /** One-line hook description for report rows. */
 export function describeHook(hook) {
     const when = hook.when ? ` when=${hook.when}` : '';
     const match = hook.match && Object.keys(hook.match).length > 0
-        ? ` match=${JSON.stringify(Object.fromEntries(Object.entries(hook.match).map(([key, re]) => [key, re.source])))},`
+        ? ` match=${JSON.stringify(Object.fromEntries(Object.entries(hook.match).map(([key, re]) => [key, matchText(re)])))},`
         : '';
+    const options = [
+        hook.enabled === false ? ' enabled:false' : '',
+        hook.cwd !== undefined ? ` cwd:${hook.cwd}` : '',
+        hook.maxConcurrent !== undefined && hook.maxConcurrent > 0 ? ` maxConcurrent:${hook.maxConcurrent}` : '',
+        hook.debounceMs !== undefined && hook.debounceMs > 0 ? ` debounceMs:${hook.debounceMs}` : '',
+    ].join('');
     if (hook.run)
-        return `[${hook.on}${when}]${match} run: ${hook.run}`;
+        return `[${hook.on}${when}]${match} run: ${hook.run}${options}`;
     if (hook.notify)
-        return `[${hook.on}${when}]${match} notify: ${hook.notify.channel}${hook.notify.url ? ` ${hook.notify.url}` : ''}`;
-    return `[${hook.on}${when}]${match} (既无 run 也无 notify)`;
+        return `[${hook.on}${when}]${match} notify: ${hook.notify.channel}${hook.notify.url ? ` ${hook.notify.url}` : ''}${options}`;
+    return `[${hook.on}${when}]${match} (既无 run 也无 notify)${options}`;
 }
 /** Evaluate every hook against the simulated event/context. */
 export function evaluateHooks(hooks, event, ctx, reasonKind) {
     return hooks.map((hook, index) => {
         const summary = describeHook(hook);
+        if (hook.enabled === false) {
+            return { index: index + 1, matched: false, why: 'enabled: false（已停用）', summary };
+        }
         if (hook.on !== event) {
             return { index: index + 1, matched: false, why: `事件不匹配（${hook.on} ≠ ${event}）`, summary };
         }

package/lib/events.d.ts

@@ -1,6 +1,6 @@
 import type { Session, SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session';
 import type { HookContext } from './context.js';
-import type { HookSpec, TurnEndReasonKind } from './config.js';
+import type { HookSpec, NumericMatch, TurnEndReasonKind } from './config.js';
 import type { AgentLike } from './types.js';
 /** `approval/asked` payload (merge-extensible, declared by dsh-user-approval). */
 export interface ApprovalAskedData {
@@ -84,13 +84,15 @@ export declare function clearTurnTracking(session: Session): void;
 /** Does a declared hook match this event (type + optional `when` filter)? */
 export declare function hookMatches(spec: HookSpec, event: string, reasonKind?: TurnEndReasonKind): boolean;
 /**
- * Apply the optional `match` field → regex filters. Every declared regex
- * must match its context field (String-coerced); a field the context does
- * not carry never matches. An empty/absent `match` passes everything.
- * RegExps come pre-compiled from the config schema; non-RegExp entries are
- * rejected defensively (never match).
+ * Apply the optional `match` field → filter map. Each value is either a
+ * regex (compiled by the config schema; tested against the String-coerced
+ * field) or a numeric comparison — declared as an object (`{ gt: 10000 }`)
+ * or as a string that parses as one (`'>10000'`). Comparison semantics
+ * apply only when the context field is a number; on a non-numeric field a
+ * comparison never matches. Every declared filter must pass. An empty or
+ * absent `match` passes everything; unsupported shapes never match.
  */
-export declare function matchFilters(match: Record<string, RegExp> | undefined, ctx: HookContext): boolean;
+export declare function matchFilters(match: Record<string, RegExp | NumericMatch> | undefined, ctx: HookContext): boolean;
 export declare function turnEndContext(session: Session, turn: number, reason: TurnEndReason | string): HookContext;
 export declare function turnStartContext(session: Session, turn: number): HookContext;
 export declare function stepEndContext(session: Session, turn: number, step: number): HookContext;

package/lib/events.js

@@ -1,6 +1,9 @@
 /** Per-session turn start timestamps for duration reporting. */
 const turnStarts = new Map();
-/** Tool name for an in-flight call, remembered at `tool/call` and consumed at `tool/result`. */
+/**
+ * Tool name + start timestamp for an in-flight call, remembered at
+ * `tool/call` and consumed at `tool/result` (name back-fill + duration).
+ */
 const callTools = new Map();
 /** Approval identity remembered at `approval/asked` and consumed at `approval/decided`. */
 const approvalTools = new Map();
@@ -139,24 +142,76 @@ export function hookMatches(spec, event, reasonKind) {
         return true;
     return spec.when === reasonKind;
 }
+/** Comparison-prefixed string syntax: `'>10000'`, `'>=5'`, `'<2'`, `'<=9'`, `'=42'`. */
+const COMPARE_STRING = /^([<>]=?|=)\s*(-?\d+(?:\.\d+)?)$/;
+const OPERATOR_SYMBOLS = {
+    '>': 'gt',
+    '>=': 'gte',
+    '<': 'lt',
+    '<=': 'lte',
+    '=': 'eq',
+};
+/** Symbol/field form of a comparison matcher: `{ gt: 10000 }`, `' > 10000'`, … */
+function numericOps(value) {
+    if (!(value instanceof RegExp))
+        return value;
+    const parsed = COMPARE_STRING.exec(value.source);
+    if (parsed === null)
+        return undefined;
+    const op = OPERATOR_SYMBOLS[parsed[1]];
+    if (op === undefined)
+        return undefined;
+    return { [op]: Number(parsed[2]) };
+}
+/** Does a numeric context field satisfy every declared comparison op? */
+function compareNumber(n, ops) {
+    if (ops.gt !== undefined && !(n > ops.gt))
+        return false;
+    if (ops.gte !== undefined && !(n >= ops.gte))
+        return false;
+    if (ops.lt !== undefined && !(n < ops.lt))
+        return false;
+    if (ops.lte !== undefined && !(n <= ops.lte))
+        return false;
+    if (ops.eq !== undefined && !(n === ops.eq))
+        return false;
+    return true;
+}
 /**
- * Apply the optional `match` field → regex filters. Every declared regex
- * must match its context field (String-coerced); a field the context does
- * not carry never matches. An empty/absent `match` passes everything.
- * RegExps come pre-compiled from the config schema; non-RegExp entries are
- * rejected defensively (never match).
+ * Apply the optional `match` field → filter map. Each value is either a
+ * regex (compiled by the config schema; tested against the String-coerced
+ * field) or a numeric comparison — declared as an object (`{ gt: 10000 }`)
+ * or as a string that parses as one (`'>10000'`). Comparison semantics
+ * apply only when the context field is a number; on a non-numeric field a
+ * comparison never matches. Every declared filter must pass. An empty or
+ * absent `match` passes everything; unsupported shapes never match.
  */
 export function matchFilters(match, ctx) {
     if (match === undefined)
         return true;
     for (const [field, pattern] of Object.entries(match)) {
-        if (!(pattern instanceof RegExp))
-            return false;
         const value = ctx[field];
         if (value === undefined)
             return false;
-        if (!pattern.test(String(value)))
-            return false;
+        if (pattern instanceof RegExp) {
+            const ops = numericOps(pattern);
+            if (ops !== undefined) {
+                // Comparison syntax: numbers only, never coerced strings.
+                if (typeof value !== 'number' || !compareNumber(value, ops))
+                    return false;
+                continue;
+            }
+            if (!pattern.test(String(value)))
+                return false;
+            continue;
+        }
+        // Object form `{ gt: … }` comes pre-typed from the schema.
+        if (typeof pattern === 'object' && pattern !== null) {
+            if (typeof value !== 'number' || !compareNumber(value, pattern))
+                return false;
+            continue;
+        }
+        return false;
     }
     return true;
 }
@@ -218,20 +273,21 @@ export function stepEndContext(session, turn, step) {
 }
 export function toolCallContext(session, turn, step, callId, name, args) {
     const key = callKey(session, callId);
-    callTools.set(key, typeof name === 'string' ? name : String(name));
+    const tool = typeof name === 'string' ? name : String(name);
+    callTools.set(key, { tool, startedAt: Date.now() });
     return {
         ...baseContext(session, 'tool/call'),
         turn,
         step,
-        tool: typeof name === 'string' ? name : String(name),
+        tool,
         callId: String(callId),
         toolArgs: typeof args === 'string' ? args.slice(0, 4000) : undefined,
     };
 }
 export function toolResultContext(session, turn, step, callId, message, error) {
     const key = callKey(session, callId);
-    const tool = callTools.get(key);
-    if (tool !== undefined)
+    const paired = callTools.get(key);
+    if (paired !== undefined)
         callTools.delete(key);
     let toolError;
     if (error !== undefined) {
@@ -245,8 +301,9 @@ export function toolResultContext(session, turn, step, callId, message, error) {
         ...baseContext(session, 'tool/result'),
         turn,
         step,
-        tool,
+        tool: paired?.tool,
         callId: String(callId),
+        toolDurationMs: paired === undefined ? undefined : Date.now() - paired.startedAt,
         toolError,
         content: content === undefined ? undefined : content.slice(0, 4000),
     };

package/lib/history.d.ts

@@ -9,7 +9,7 @@ export interface HookRunRecord {
     command: string;
     sessionId?: string;
     sessionName?: string;
-    outcome: 'spawned' | 'spawn-failed' | 'timeout' | 'exit-0' | 'exit-nonzero' | 'sent' | 'send-failed';
+    outcome: 'spawned' | 'spawn-failed' | 'timeout' | 'exit-0' | 'exit-nonzero' | 'skipped' | 'sent' | 'send-failed';
     exitCode?: number;
     durationMs?: number;
     /** stderr tail or error message. */

package/lib/index.d.ts

@@ -59,7 +59,7 @@ export { createHistorySink } from './history.js';
  * Model-facing announcement, installed only when the system-prompt service
  * exists (web profile). Tells agents the plugin exists and how to cooperate.
  */
-export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hooks \u63D2\u4EF6\uFF08DeepSeek Harness \u914D\u7F6E\u9A71\u52A8\u751F\u547D\u5468\u671F hooks\uFF09\uFF1A\u53EF\u5728 profile \u7684 cordis.patch.yml \u58F0\u660E\u300C\u4E8B\u4EF6 \u2192 \u547D\u4EE4/\u901A\u77E5\u300D\u7684 hook\uFF08turn/start\u3001turn/end\u3001tree/settled\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001approval/decided\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status\u3001hook/failed \u5171 17 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219\u8FC7\u6EE4\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\u3001\u5185\u7F6E webhook/desktop \u901A\u77E5\u6E20\u9053\uFF1B\u6267\u884C\u5386\u53F2\u8BB0\u5F55\u4E8E ~/.dsh/dsh-hooks/history.jsonl\uFF1B`dsh-hooks dry-run <event>` \u53EF\u6A21\u62DF\u4E8B\u4EF6\u9A8C\u8BC1\u914D\u7F6E\u3002\u7528\u6237\u63D0\u5230\u300Chooks / \u94A9\u5B50 / \u751F\u547D\u5468\u671F / \u901A\u77E5\u914D\u7F6E\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hooks \u63D2\u4EF6\uFF08DeepSeek Harness \u914D\u7F6E\u9A71\u52A8\u751F\u547D\u5468\u671F hooks\uFF09\uFF1A\u53EF\u5728 profile \u7684 cordis.patch.yml \u58F0\u660E\u300C\u4E8B\u4EF6 \u2192 \u547D\u4EE4/\u901A\u77E5\u300D\u7684 hook\uFF08turn/start\u3001turn/end\u3001tree/settled\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001approval/decided\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status\u3001hook/failed \u5171 17 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219/\u6570\u503C\u6BD4\u8F83\u8FC7\u6EE4\uFF08\u5982 '>10000'\uFF09\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\u3001\u6267\u884C\u9009\u9879\uFF08enabled \u505C\u7528 / cwd \u5DE5\u4F5C\u76EE\u5F55 / maxConcurrent + debounceMs \u9632\u9AD8\u9891\u98CE\u66B4\uFF09\u3001\u5185\u7F6E webhook/desktop \u901A\u77E5\u6E20\u9053\uFF1B\u6267\u884C\u5386\u53F2\u8BB0\u5F55\u4E8E ~/.dsh/dsh-hooks/history.jsonl\uFF1B`dsh-hooks dry-run <event>` \u53EF\u6A21\u62DF\u4E8B\u4EF6\u9A8C\u8BC1\u914D\u7F6E\u3002\u7528\u6237\u63D0\u5230\u300Chooks / \u94A9\u5B50 / \u751F\u547D\u5468\u671F / \u901A\u77E5\u914D\u7F6E\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 export declare function apply(ctx: Context, config?: Config): void;
 export declare const _internals: {
     clearTurnTracking: typeof clearTurnTracking;

package/lib/index.js

@@ -73,7 +73,7 @@ export { createHistorySink } from './history.js';
  * Model-facing announcement, installed only when the system-prompt service
  * exists (web profile). Tells agents the plugin exists and how to cooperate.
  */
-export const DSH_HOOKS_GUIDANCE = '本机已安装 dsh-hooks 插件（DeepSeek Harness 配置驱动生命周期 hooks）：可在 profile 的 cordis.patch.yml 声明「事件 → 命令/通知」的 hook（turn/start、turn/end、tree/settled、step/end、tool/call、tool/result、user/message、approval/asked、approval/decided、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status、hook/failed 共 17 类事件），支持 when 原因过滤、match 字段正则过滤、stdin JSON 输入、opt-in 重试、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl；`dsh-hooks dry-run <event>` 可模拟事件验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
+export const DSH_HOOKS_GUIDANCE = '本机已安装 dsh-hooks 插件（DeepSeek Harness 配置驱动生命周期 hooks）：可在 profile 的 cordis.patch.yml 声明「事件 → 命令/通知」的 hook（turn/start、turn/end、tree/settled、step/end、tool/call、tool/result、user/message、approval/asked、approval/decided、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status、hook/failed 共 17 类事件），支持 when 原因过滤、match 字段正则/数值比较过滤（如 \'>10000\'）、stdin JSON 输入、opt-in 重试、执行选项（enabled 停用 / cwd 工作目录 / maxConcurrent + debounceMs 防高频风暴）、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl；`dsh-hooks dry-run <event>` 可模拟事件验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
 export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
     const history = createHistorySink(config.history ?? undefined);
@@ -112,42 +112,94 @@ export function apply(ctx, config = {}) {
     }
     const runMatching = (ctxValue, reasonKind) => {
         hooks.forEach((hook, index) => {
+            // enabled: false keeps the declaration but silences dispatch entirely —
+            // skipped hooks are never failure-streak candidates.
+            if (hook.enabled === false)
+                return;
             if (!hookMatches(hook, ctxValue.event, reasonKind))
                 return;
             if (!matchFilters(hook.match, ctxValue))
                 return;
-            // Attribute every outcome record to this hook identity so the failure
-            // streak below sees the full run/notify lifecycle (retries included).
-            const track = (record) => {
-                history.record(record);
-                const failed = record.outcome === 'spawn-failed' ||
-                    record.outcome === 'exit-nonzero' ||
-                    record.outcome === 'timeout' ||
-                    record.outcome === 'send-failed';
-                if (failed) {
-                    const count = (failures.get(index) ?? 0) + 1;
-                    failures.set(index, count);
-                    if (count >= failureThreshold && !alerted.has(index)) {
-                        alerted.add(index);
-                        runMatching(hookFailedContext(ctxValue, hookFailureSummary(hook), count));
-                    }
+            const debounceMs = hook.debounceMs ?? 0;
+            if (debounceMs > 0) {
+                // Trailing-edge merge: triggers inside the window collapse into one
+                // execution carrying the latest context. Dropped triggers stay silent
+                // so high-frequency events cannot flood the log/history.
+                const pending = debounceTimers.get(index);
+                if (pending !== undefined) {
+                    pending.ctx = ctxValue;
                     return;
                 }
-                if (record.outcome === 'exit-0' || record.outcome === 'sent') {
-                    failures.delete(index);
-                    alerted.delete(index);
-                }
-            };
-            if (hook.notify) {
-                void fireNotify(hook.notify, ctxValue, track);
+                const timer = setTimeout(() => {
+                    const armed = debounceTimers.get(index);
+                    debounceTimers.delete(index);
+                    if (armed !== undefined)
+                        dispatchHook(hook, index, armed.ctx);
+                }, debounceMs);
+                timer.unref?.();
+                debounceTimers.set(index, { timer, ctx: ctxValue });
                 return;
             }
-            if (hook.run) {
-                runner.run(hook, ctxValue, track);
+            dispatchHook(hook, index, ctxValue);
+        });
+    };
+    /**
+     * Dispatch one matched, enabled hook (run or notify). Outcome records are
+     * attributed to the hook index so the failure streak sees the full
+     * run/notify lifecycle (retries included).
+     */
+    const dispatchHook = (hook, index, ctxValue) => {
+        const track = (record) => {
+            history.record(record);
+            const failed = record.outcome === 'spawn-failed' ||
+                record.outcome === 'exit-nonzero' ||
+                record.outcome === 'timeout' ||
+                record.outcome === 'send-failed';
+            if (failed) {
+                const count = (failures.get(index) ?? 0) + 1;
+                failures.set(index, count);
+                if (count >= failureThreshold && !alerted.has(index)) {
+                    alerted.add(index);
+                    runMatching(hookFailedContext(ctxValue, hookFailureSummary(hook), count));
+                }
                 return;
             }
-            console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
-        });
+            if (record.outcome === 'exit-0' || record.outcome === 'sent') {
+                failures.delete(index);
+                alerted.delete(index);
+            }
+        };
+        if (hook.notify) {
+            void fireNotify(hook.notify, ctxValue, track);
+            return;
+        }
+        if (hook.run) {
+            const limiter = hook.maxConcurrent !== undefined && hook.maxConcurrent > 0
+                ? { id: `hook:${index}`, max: hook.maxConcurrent }
+                : undefined;
+            runner.run(hook, ctxValue, track, limiter);
+            return;
+        }
+        console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
+    };
+    // Per-hook debounce state (trailing timers); cleared on dispose.
+    const debounceTimers = new Map();
+    // turn/start content: the session log records `turn/start` BEFORE the
+    // turn's `user/message`, so the initiating prompt text cannot be read at
+    // turn-start time. When turn/start hooks exist, dispatch is deferred until
+    // the turn's first direct user message is classified (its text attached as
+    // `content`), or the turn ends without one (continuation/goal rounds) —
+    // then it fires without content.
+    const hasTurnStartHooks = hooks.some((hook) => hook.on === 'turn/start' && hook.enabled !== false);
+    const pendingTurnStarts = new Map();
+    /** Dispatch a deferred turn/start, optionally attaching the initiating text. */
+    const flushTurnStart = (sessionId, content) => {
+        const pending = pendingTurnStarts.get(sessionId);
+        if (pending === undefined)
+            return;
+        pendingTurnStarts.delete(sessionId);
+        const ctxValue = content === undefined ? pending.ctx : { ...pending.ctx, content: content.slice(0, 2000) };
+        runMatching(ctxValue);
     };
     // turn/end: fill the live running-subagent count before dispatching hooks,
     // so a hook can tell "work handed off to still-running subagents" apart from
@@ -228,10 +280,38 @@ export function apply(ctx, config = {}) {
         if (classified === undefined)
             return;
         const reasonKind = extractReasonKind(event);
+        const sessionId = String(session.id);
+        if (classified.event === 'turn/start') {
+            if (!hasTurnStartHooks) {
+                runMatching(classified, reasonKind);
+                return;
+            }
+            // A new turn claims the session: flush a previous unclaimed turn/start
+            // (empty/rejected turn) without content, then arm the new one.
+            flushTurnStart(sessionId);
+            pendingTurnStarts.set(sessionId, { ctx: classified });
+            return;
+        }
+        if (classified.event === 'user/message') {
+            // The turn's first direct user message completes the deferred turn/start
+            // with the initiating text attached; synthetic messages (agent/plugin
+            // sources) do not complete it.
+            const pending = pendingTurnStarts.get(sessionId);
+            if (pending !== undefined && classified.source === 'user') {
+                pendingTurnStarts.delete(sessionId);
+                const text = classified.content;
+                runMatching(text === undefined ? pending.ctx : { ...pending.ctx, content: text.slice(0, 2000) });
+            }
+            runMatching(classified, reasonKind);
+            return;
+        }
         if (classified.event !== 'turn/end') {
             runMatching(classified, reasonKind);
             return;
         }
+        // The turn produced no direct user message (continuation round): dispatch
+        // the deferred turn/start without content, then the turn/end flow.
+        flushTurnStart(sessionId);
         // Dispatch is deferred past the async count; guard the fire-and-forget
         // promise so a synchronous throw inside dispatch surfaces as a log line
         // instead of an unhandled rejection.
@@ -245,6 +325,8 @@ export function apply(ctx, config = {}) {
     });
     ctx.on('session/disposed', (session) => {
         watchedTrees.delete(String(session.id));
+        // A disposed session never completes its deferred turn/start — drop it.
+        pendingTurnStarts.delete(String(session.id));
         runMatching(sessionDisposedContext(session));
         // A child session leaving the store is also settle-relevant activity.
         void refreshWatchedTrees().catch((error) => {
@@ -275,6 +357,10 @@ export function apply(ctx, config = {}) {
     });
     ctx.effect(() => () => {
         runner.dispose();
+        for (const entry of debounceTimers.values())
+            clearTimeout(entry.timer);
+        debounceTimers.clear();
+        pendingTurnStarts.clear();
         watchedTrees.clear();
     });
 }

package/lib/patch-config.d.ts

@@ -13,6 +13,10 @@ export interface HookWireSpec {
     timeoutMs?: number;
     retries?: number;
     retryDelayMs?: number;
+    enabled?: boolean;
+    cwd?: 'session' | string;
+    maxConcurrent?: number;
+    debounceMs?: number;
 }
 /** Parse a patch list; throws a user-facing error on malformed YAML. */
 export declare function parsePatchText(text: string): unknown[];

package/lib/patch-config.js

@@ -7,6 +7,7 @@
  * so a save applies without a restart.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import YAML from 'yaml';
 import { HOOK_EVENTS, TURN_END_REASONS } from './config.js';
 /** Parse a patch list; throws a user-facing error on malformed YAML. */
@@ -55,12 +56,15 @@ export function validateHookWire(hooks) {
         if (hasNotify && hook.notify.channel !== 'webhook' && hook.notify.channel !== 'desktop') {
             return `${label}：无效通知渠道 ${hook.notify.channel}`;
         }
-        for (const key of ['timeoutMs', 'retries', 'retryDelayMs']) {
+        for (const key of ['timeoutMs', 'retries', 'retryDelayMs', 'maxConcurrent', 'debounceMs']) {
             const value = hook[key];
             if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
                 return `${label}：${key} 必须是非负数字`;
             }
         }
+        if (hook.cwd !== undefined && hook.cwd !== '' && hook.cwd !== 'session' && !isAbsolute(hook.cwd)) {
+            return `${label}：cwd 必须是 session 或绝对路径（收到 ${hook.cwd}）`;
+        }
     }
     return null;
 }

package/lib/runner.d.ts

@@ -9,7 +9,7 @@ export interface RunOutcome {
 }
 /** Track in-flight hook runs so a missing parent never outlives teardown. */
 export interface HookRunner {
-    run(spec: HookSpec, ctx: HookContext, recordOverride?: RunRecord): RunOutcome;
+    run(spec: HookSpec, ctx: HookContext, recordOverride?: RunRecord, limiter?: RunLimiter): RunOutcome;
     /** Live counters for the web-panel diagnostics. */
     stats(): HookRunnerStats;
     dispose(): void;
@@ -21,6 +21,15 @@ export interface HookRunnerStats {
     pendingRetries: number;
 }
 export type RunRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
+/**
+ * Per-hook concurrency gate: runs carrying the same `id` share one cap.
+ * Accepted runs occupy a slot until the logical run reaches a terminal
+ * outcome (retries keep the slot), so a retrying hook still counts.
+ */
+export interface RunLimiter {
+    id: string;
+    max: number;
+}
 export declare const DEFAULT_TIMEOUT_MS = 10000;
 export declare const DEFAULT_RETRY_DELAY_MS = 500;
 /**
@@ -38,5 +47,7 @@ export declare function terminate(child: ChildProcess): void;
  * templating by the user. `input: 'stdin'` additionally writes the full
  * context as one JSON document to stdin, and `retries` re-spawns commands
  * whose exit code is non-zero (with exponential backoff, in the background).
+ * `cwd` moves the spawn into the session/project directory, and an optional
+ * `limiter` caps concurrent runs per identity.
  */
 export declare function createHookRunner(log?: (line: string) => void, record?: RunRecord): HookRunner;

package/lib/runner.js

@@ -26,6 +26,18 @@ export function terminate(child) {
     }
     child.kill();
 }
+/**
+ * Resolve the spawn working directory for a hook: `cwd: 'session'` runs in
+ * the session's cwd (falling back to the plugin process when unknown); any
+ * other configured value is used verbatim (documented as an absolute path).
+ */
+function resolveCwd(spec, ctx) {
+    if (spec.cwd === undefined)
+        return undefined;
+    if (spec.cwd === 'session')
+        return ctx.cwd ?? process.cwd();
+    return spec.cwd;
+}
 /**
  * Fire-and-forget command runner. Emissions are irreversible side effects:
  * failures only warn, never block the agent loop. Context travels through
@@ -34,11 +46,24 @@ export function terminate(child) {
  * templating by the user. `input: 'stdin'` additionally writes the full
  * context as one JSON document to stdin, and `retries` re-spawns commands
  * whose exit code is non-zero (with exponential backoff, in the background).
+ * `cwd` moves the spawn into the session/project directory, and an optional
+ * `limiter` caps concurrent runs per identity.
  */
 export function createHookRunner(log = console.log, record) {
     const children = new Set();
     const pendingRetries = new Set();
-    function spawnOnce(spec, ctx, attempt, recordOverride) {
+    /** Live logical-run counts per limiter id (retries keep their slot). */
+    const inFlightById = new Map();
+    function releaseSlot(limiter) {
+        if (limiter === undefined)
+            return;
+        const count = (inFlightById.get(limiter.id) ?? 0) - 1;
+        if (count <= 0)
+            inFlightById.delete(limiter.id);
+        else
+            inFlightById.set(limiter.id, count);
+    }
+    function spawnOnce(spec, ctx, attempt, recordOverride, done) {
         if (!spec.run)
             return { ok: false, reason: 'skipped', detail: 'no run command' };
         // Per-run override replaces the shared sink for this logical run so
@@ -62,6 +87,7 @@ export function createHookRunner(log = console.log, record) {
         try {
             child = spawn(command, {
                 shell: true,
+                cwd: resolveCwd(spec, ctx),
                 env: { ...process.env, ...env },
                 stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
             });
@@ -70,6 +96,7 @@ export function createHookRunner(log = console.log, record) {
             const detail = error instanceof Error ? error.message : String(error);
             console.warn(`[dsh-hooks] spawn 失败 (${eventLabel(ctx)}): ${detail}`);
             rec?.({ ...base, outcome: 'spawn-failed', error: detail });
+            done?.();
             return { ok: false, reason: 'spawn-failed', detail };
         }
         const startedAt = Date.now();
@@ -112,6 +139,7 @@ export function createHookRunner(log = console.log, record) {
                 if (!timedOut && code !== null) {
                     rec?.({ ...base, outcome: 'exit-0', exitCode: 0, durationMs: Date.now() - startedAt });
                 }
+                done?.();
                 return;
             }
             if (attempt < retries) {
@@ -119,7 +147,7 @@ export function createHookRunner(log = console.log, record) {
                 log(`[dsh-hooks] hook 退出码 ${code}，${delay}ms 后重试（${attempt + 1}/${retries}）：${eventLabel(ctx)}`);
                 const retryTimer = setTimeout(() => {
                     pendingRetries.delete(retryTimer);
-                    spawnOnce(spec, ctx, attempt + 1, recordOverride);
+                    spawnOnce(spec, ctx, attempt + 1, recordOverride, done);
                 }, delay);
                 retryTimer.unref?.();
                 pendingRetries.add(retryTimer);
@@ -129,13 +157,23 @@ export function createHookRunner(log = console.log, record) {
             const detail = tail === '' ? '' : `，stderr：${tail.slice(-400)}`;
             console.warn(`[dsh-hooks] hook 退出码 ${code} (${eventLabel(ctx)})${detail}`);
             rec?.({ ...base, outcome: 'exit-nonzero', exitCode: code, durationMs: Date.now() - startedAt, error: tail.slice(-400) || undefined });
+            done?.();
         });
         return { ok: true, reason: 'ran' };
     }
-    function run(spec, ctx, recordOverride) {
+    function run(spec, ctx, recordOverride, limiter) {
         if (!spec.run)
             return { ok: false, reason: 'skipped', detail: 'no run command' };
-        return spawnOnce(spec, ctx, 0, recordOverride);
+        if (limiter !== undefined) {
+            const inFlight = inFlightById.get(limiter.id) ?? 0;
+            if (inFlight >= limiter.max) {
+                const detail = `maxConcurrent 达到上限（${limiter.max}），本次触发被丢弃`;
+                recordOverride?.({ kind: 'run', event: ctx.event, command: spec.run, sessionId: ctx.sessionId, sessionName: ctx.sessionName, outcome: 'skipped', error: detail });
+                return { ok: false, reason: 'skipped', detail };
+            }
+            inFlightById.set(limiter.id, inFlight + 1);
+        }
+        return spawnOnce(spec, ctx, 0, recordOverride, () => releaseSlot(limiter));
     }
     function dispose() {
         for (const timer of pendingRetries)

package/lib/server.d.ts

@@ -63,6 +63,10 @@ export declare function describeHooks(hooks: readonly HookSpec[]): {
     timeoutMs: number | undefined;
     retries: number | undefined;
     retryDelayMs: number | undefined;
+    enabled: boolean | undefined;
+    cwd: string | undefined;
+    maxConcurrent: number | undefined;
+    debounceMs: number | undefined;
 }[];
 /** Create the /dsh-hooks route handler (exported for tests). */
 export declare function createHookHandler(options: HookRoutesOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/lib/server.js

@@ -55,6 +55,21 @@ async function readJsonBody(req) {
         return null;
     }
 }
+/** Render a match value for the panel: regex source or comparison string. */
+function matchText(value) {
+    if (value instanceof RegExp)
+        return value.source;
+    // Normalize single-op objects to the equivalent string syntax so the
+    // editor round-trip keeps comparison semantics; multi-op stays JSON.
+    const ops = Object.entries(value);
+    if (ops.length === 1) {
+        const [op, n] = ops[0];
+        const symbol = { gt: '>', gte: '>=', lt: '<', lte: '<=', eq: '=' }[op];
+        if (symbol !== undefined && typeof n === 'number')
+            return `${symbol}${n}`;
+    }
+    return JSON.stringify(value);
+}
 /** Sanitized per-hook description for the settings panel (regex sources, no RegExp objects). */
 export function describeHooks(hooks) {
     return hooks.map((hook, i) => ({
@@ -63,7 +78,7 @@ export function describeHooks(hooks) {
         when: hook.when,
         match: hook.match === undefined
             ? undefined
-            : Object.fromEntries(Object.entries(hook.match).map(([field, re]) => [field, re.source])),
+            : Object.fromEntries(Object.entries(hook.match).map(([field, re]) => [field, matchText(re)])),
         run: hook.run,
         notify: hook.notify === undefined || hook.notify === null
             ? undefined
@@ -72,6 +87,10 @@ export function describeHooks(hooks) {
         timeoutMs: hook.timeoutMs,
         retries: hook.retries,
         retryDelayMs: hook.retryDelayMs,
+        enabled: hook.enabled,
+        cwd: hook.cwd,
+        maxConcurrent: hook.maxConcurrent,
+        debounceMs: hook.debounceMs,
     }));
 }
 const FAILED_OUTCOMES = new Set(['exit-nonzero', 'timeout', 'spawn-failed', 'send-failed']);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hooks",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "packageManager": "pnpm@11.21.0",
   "description": "Config-driven lifecycle hooks plugin for DeepSeek Harness: declare event -> command hooks in cordis.patch.yml, no plugin code required. Includes a Hooks section in the Web GUI settings (history timeline + manual tester + notify tests + hook editor + Feishu connect).",
   "author": "PeterBon",