dsh-hooks 0.9.1 → 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 |
@@ -90,6 +106,7 @@ Every hook field:
 | `agent/disposed` | An agent leaves the registry | session id |
 | `agent/error` | The agent loop reports an error | error text |
 | `agent/status` | Agent status transition | status |
+| `hook/failed` | A hook fails consecutively past `failedAlertThreshold` (default 3; synthetic, emitted from the outcome stream) | failing hook summary, consecutive failure count |
 
 The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `error`, …). Hooks for other events run unconditionally.
 
@@ -111,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 |
@@ -131,9 +149,22 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_APPROVAL_OUTCOME` | approval decision outcome (`approval/decided`) |
 | `DSH_HOOK_TOTAL_SUBAGENTS` | total subagents in the settled tree (`tree/settled`) |
 | `DSH_HOOK_TREE_DURATION_MS` | parent turn/end → tree settle duration, ms (`tree/settled`) |
+| `DSH_HOOK_FAILED_HOOK` | identity summary of the hook that failed consecutively (`hook/failed`) |
+| `DSH_HOOK_FAILURES` | consecutive failure count when the alert fired (`hook/failed`) |
 | `DSH_HOOK_TIMESTAMP` | ISO timestamp |
 
 - `{{var}}` placeholders inside `run` are substituted from the same context, e.g. `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`.
+- Failure alerts: fire-and-forget hooks fail silently by design, so the plugin also watches the outcome stream. When one hook fails `failedAlertThreshold` consecutive times (`spawn-failed` / `exit-nonzero` / `timeout` / `send-failed`; one logical run's final outcome counts once, internal retries don't add extra counts), the synthetic `hook/failed` event fires once per streak — a success resets both the counter and the dedup. Alert with a normal hook:
+
+```yaml
+config:
+  failedAlertThreshold: 3   # optional, default 3
+  hooks:
+    - on: 'hook/failed'
+      notify: { channel: 'desktop' }
+    - on: 'turn/end'
+      run: 'node my-hook.mjs'
+```
 - `turn/end` hooks are dispatched after the running-subagent count resolves, i.e. one async hop later than other events — an immediately following event from the same session (e.g. the next `turn/start`) may dispatch first.
 
 A common use for `DSH_HOOK_RUNNING_SUBAGENTS` is suppressing the end-of-turn notification while background subagents are still working and only notifying once a turn settles with nothing left running. Note the parent session emits `turn/end` exactly once (with the count > 0); the "everything settled" signal arrives as `turn/end` on the last child session, whose count is `0`:
@@ -153,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:
@@ -186,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 |
@@ -90,6 +106,7 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `agent/disposed` | Agent 离开注册表 | 会话 id |
 | `agent/error` | Agent 循环报错 | 错误文本 |
 | `agent/status` | Agent 状态切换 | 状态 |
+| `hook/failed` | 同一 hook 连续失败达到 `failedAlertThreshold`（默认 3；合成事件，从结果流发射） | 失败 hook 摘要、连续失败次数 |
 
 `turn/end` 的 `when` 匹配结束原因（`completed`、`error`…）；其他事件的 hook 无条件执行。
 
@@ -111,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（有上报时） |
@@ -131,9 +149,23 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_APPROVAL_OUTCOME` | 审批结果 outcome（`approval/decided`） |
 | `DSH_HOOK_TOTAL_SUBAGENTS` | 已落定树中的子代理总数（`tree/settled`） |
 | `DSH_HOOK_TREE_DURATION_MS` | 父回合结束 → 树落定的耗时（毫秒，`tree/settled`） |
+| `DSH_HOOK_FAILED_HOOK` | 连续失败的 hook 身份摘要（`hook/failed`） |
+| `DSH_HOOK_FAILURES` | 告警触发时的连续失败次数（`hook/failed`） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
+- 失败告警：fire-and-forget 的 hook 失败本来就是静默的，插件因此同时监视结果流——同一 hook 连续失败 `failedAlertThreshold` 次（`spawn-failed` / `exit-nonzero` / `timeout` / `send-failed`；一次逻辑执行的最终结果计一次，内部重试不另计）后发射合成事件 `hook/failed`，每条失败链只发一次；成功会清零计数并解除去抖。用普通 hook 接告警即可：
+
+```yaml
+config:
+  failedAlertThreshold: 3   # 可选，默认 3
+  hooks:
+    - on: 'hook/failed'
+      notify: { channel: 'desktop' }
+    - on: 'turn/end'
+      run: 'node my-hook.mjs'
+```
+
 - `turn/end` 的 hook 在运行中子代理计数解析完成后才派发，比其他事件晚一个异步跳——同会话紧随其后的事件（如下一轮 `turn/start`）可能先执行。
 
 `DSH_HOOK_RUNNING_SUBAGENTS` 的典型用法：后台子代理还在运行时抑制回合结束通知，只在本会话回合真正落定时才通知。注意父会话只会收到一次 `turn/end`（此时计数 > 0）；「全部落定」的信号由最后一个子会话自己的 `turn/end`（计数为 `0`）送达：
@@ -153,6 +185,62 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 
 已落定但闲置（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（环境变量从不入记录）：
@@ -168,7 +256,7 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
     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

@@ -1,5 +1,5 @@
 /** Hookable event kinds. v1 is emit-only: no waterfall/interception events. */
-export declare const HOOK_EVENTS: readonly ['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'];
+export declare const HOOK_EVENTS: readonly ['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'];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
 export declare const TURN_END_REASONS: readonly ['completed', 'error', 'aborted', 'blocked', 'max-tokens', 'interrupted'];
@@ -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 {
@@ -68,6 +107,13 @@ export interface HistoryConfig {
 export interface Config {
     hooks?: HookSpec[];
     history?: HistoryConfig | null;
+    /**
+     * Consecutive failure count (spawn-failed / exit-nonzero / timeout /
+     * send-failed; one logical run counts once, internal retries included)
+     * that emits the synthetic `hook/failed` event. Defaults to 3; values
+     * below 1 are clamped to 1.
+     */
+    failedAlertThreshold?: number;
 }
 export declare const Config: {
     (data?: Config | null): Config;

package/lib/config.js

@@ -17,6 +17,7 @@ export const HOOK_EVENTS = [
     'agent/disposed',
     'agent/error',
     'agent/status',
+    'hook/failed',
 ];
 /** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
 export const TURN_END_REASONS = [
@@ -33,9 +34,18 @@ export const TURN_END_REASONS = [
 // declaration self-contained.
 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'),
+        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({
@@ -55,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('事件触发时执行的外部命令列表；按声明顺序触发'),
@@ -68,4 +84,7 @@ export const Config = Schema.object({
     ])
         .default(null)
         .description('hook 执行历史：内存环形缓冲 + 可选 JSONL 持久化日志（供 UI/调试使用，严格 best-effort）'),
+    failedAlertThreshold: Schema.natural()
+        .default(3)
+        .description('同一 hook 连续失败达到该次数时发射 hook/failed 合成事件（spawn-failed/exit-nonzero/timeout/send-failed 计失败；一次逻辑执行的最终结果计一次，内部重试不另计；成功清零，触发后去抖）'),
 }).description('dsh-hooks 配置：声明式生命周期 hooks');

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;
@@ -60,6 +65,10 @@ export interface HookContext {
     totalSubagents?: number;
     /** Parent turn/end → tree settle duration, ms (tree/settled). */
     treeDurationMs?: number;
+    /** Identity summary of the hook that failed consecutively (hook/failed). */
+    hookFailedHook?: string;
+    /** Consecutive failure count when the alert fired (hook/failed). */
+    hookFailures?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;