dsh-hooks 0.10.0 → 0.12.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 |
@@ -91,6 +107,7 @@ Every hook field:
 | `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 |
+| `usage/daily` | The first event after the local calendar day rolls over (synthetic, no timers): reports the token usage of the day that just ended | covered day, turns that day, contributing sessions, day's token totals |
 
 The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `error`, …). Hooks for other events run unconditionally.
 
@@ -112,16 +129,17 @@ 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_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 |
-| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | aggregated cache-write tokens, when reported |
-| `DSH_HOOK_USAGE_REASONING_TOKENS` | aggregated reasoning tokens, when reported |
+| `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` | input token total (turn/end: this turn, summed across steps; usage/daily: the whole day) |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | output token total (same scoping) |
+| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | cache-read tokens when reported (same scoping) |
+| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | cache-write tokens when reported (same scoping) |
+| `DSH_HOOK_USAGE_REASONING_TOKENS` | reasoning tokens when reported (same scoping) |
 | `DSH_HOOK_RUNNING_SUBAGENTS` | live subagents still running under this session (turn/end; `0` = none — lets a hook tell "work handed off to background subagents" apart from "the turn finished for real") |
 | `DSH_HOOK_PARENT_SESSION_ID` | parent session id (subagent lineage; absent for top-level sessions) |
 | `DSH_HOOK_SUBAGENT` | `1` when the session is a subagent child, `0` otherwise |
@@ -134,6 +152,9 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `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_USAGE_DAY` | local calendar day the token totals cover, `YYYY-MM-DD` (`usage/daily`) |
+| `DSH_HOOK_USAGE_TURNS` | turns with reported accounting that day (`usage/daily`) |
+| `DSH_HOOK_USAGE_SESSIONS` | distinct sessions that contributed usage that day (`usage/daily`) |
 | `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'`.
@@ -167,6 +188,82 @@ 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).
 
+### usage/daily: the cross-day token report
+
+`turn/end` answers "what did this turn cost". For a per-day view, use the synthetic `usage/daily` event: the plugin accumulates every reported `turn/end` usage in memory per **local calendar day** (subagent sessions included — same account), and when the day rolls over it emits one report for the day that just ended, on the next event that arrives. Detection is purely event-driven: no timers, no scheduled tasks.
+
+```yaml
+- on: 'usage/daily'
+  match: { usageInputTokens: '>0' }     # optional: skip days without usage
+  run: 'node examples/log-usage.mjs'    # or notify: { channel: 'webhook', url: '…' }
+```
+
+`DSH_HOOK_USAGE_DAY` is the day the report covers (`YYYY-MM-DD`); `DSH_HOOK_USAGE_TURNS` / `DSH_HOOK_USAGE_SESSIONS` are that day's counted turns and contributing sessions; the token details reuse the `turn/end` variable names (`usageInputTokens` / `usageOutputTokens` / `usageCacheReadTokens` / `usageCacheWriteTokens` / `usageReasoningTokens`) with day scope instead of turn scope.
+
+Three boundaries by design, not bugs:
+
+- **In-memory**: a plugin-process restart drops the day in progress (the new process starts a fresh day at zero); reports already emitted are unaffected.
+- **Event-driven, not timed**: a day is reported when the next event arrives, so after a quiet midnight the report waits for the next event; a day with no reported turn usage is never reported (an empty report is noise).
+- **Zero cost when unused**: with no `usage/daily` hook declared, no accumulation and no day check happen at all.
+
+`dsh-hooks dry-run usage/daily` simulates a report for "yesterday" with non-zero tokens, so match filters and the command can be verified first.
+
+### 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 +297,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 |
@@ -91,6 +107,7 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `agent/error` | Agent 循环报错 | 错误文本 |
 | `agent/status` | Agent 状态切换 | 状态 |
 | `hook/failed` | 同一 hook 连续失败达到 `failedAlertThreshold`（默认 3；合成事件，从结果流发射） | 失败 hook 摘要、连续失败次数 |
+| `usage/daily` | 本地日历日翻篇后的下一个事件（合成事件，无定时器）：报告刚结束那一天的 token 用量 | 覆盖日期、当日回合数、贡献会话数、当日 token 明细 |
 
 `turn/end` 的 `when` 匹配结束原因（`completed`、`error`…）；其他事件的 hook 无条件执行。
 
@@ -112,16 +129,17 @@ 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_USAGE_INPUT_TOKENS` | 本回合输入 token 总量（turn/end，逐 step 聚合） |
-| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | 本回合输出 token 总量 |
-| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 本回合缓存读 token（有上报时） |
-| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | 本回合缓存写 token（有上报时） |
-| `DSH_HOOK_USAGE_REASONING_TOKENS` | 本回合思考 token（有上报时） |
+| `DSH_HOOK_CONTENT` | 事件内容快照：回合最后助手文本、工具结果文本、用户消息文本、回合触发消息文本（turn/start） |
+| `DSH_HOOK_USAGE_INPUT_TOKENS` | 输入 token 总量（turn/end 为本回合、逐 step 聚合；usage/daily 为当日聚合） |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | 输出 token 总量（同上） |
+| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 缓存读 token（有上报时，同上） |
+| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | 缓存写 token（有上报时，同上） |
+| `DSH_HOOK_USAGE_REASONING_TOKENS` | 思考 token（有上报时，同上） |
 | `DSH_HOOK_RUNNING_SUBAGENTS` | 本会话下仍在运行的存活子代理数（turn/end；`0` = 无——让 hook 能区分「工作已交给后台子代理」与「回合真正结束」） |
 | `DSH_HOOK_PARENT_SESSION_ID` | 父会话 id（子代理谱系；顶层会话无此变量） |
 | `DSH_HOOK_SUBAGENT` | 会话为子代理时为 `1`，否则 `0` |
@@ -134,6 +152,9 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_TREE_DURATION_MS` | 父回合结束 → 树落定的耗时（毫秒，`tree/settled`） |
 | `DSH_HOOK_FAILED_HOOK` | 连续失败的 hook 身份摘要（`hook/failed`） |
 | `DSH_HOOK_FAILURES` | 告警触发时的连续失败次数（`hook/failed`） |
+| `DSH_HOOK_USAGE_DAY` | 报告覆盖的本地日历日 `YYYY-MM-DD`（`usage/daily`） |
+| `DSH_HOOK_USAGE_TURNS` | 当日计入的回合数（`usage/daily`） |
+| `DSH_HOOK_USAGE_SESSIONS` | 当日贡献用量的会话数（`usage/daily`） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
@@ -168,6 +189,82 @@ config:
 
 已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。落定监视是事件驱动且 best-effort 的：插件重启后监视集合丢失；重查失败会静默放弃该监视（不会补发迟到的通知）。
 
+### usage/daily：跨日 token 日报
+
+`turn/end` 只回答「这个回合花了多少」。要按天看成本，用合成事件 `usage/daily`：插件在内存里按**本地日历日**累计每个 `turn/end` 上报的 token（子代理会话的回合一并计入——同一个账号），日期翻篇后对下一个到达的事件发射一次日报，报告刚结束的那一天。检测纯事件驱动、无定时器、无定时任务。
+
+```yaml
+- on: 'usage/daily'
+  match: { usageInputTokens: '>0' }     # 可选：跳过没有用量的日子
+  run: 'node examples/log-usage.mjs'    # 或 notify: { channel: 'webhook', url: '…' }
+```
+
+`DSH_HOOK_USAGE_DAY` 是报告覆盖的日期（`YYYY-MM-DD`）；`DSH_HOOK_USAGE_TURNS` / `DSH_HOOK_USAGE_SESSIONS` 是当日计入的回合数与贡献会话数；token 明细沿用 `turn/end` 的 `DSH_HOOK_USAGE_*` 变量名（`usageInputTokens` / `usageOutputTokens` / `usageCacheReadTokens` / `usageCacheWriteTokens` / `usageReasoningTokens`），语义变为「该日聚合」。
+
+三条边界（按设计，不是 bug）：
+
+- **内存累计**：插件进程重启会丢掉进行中那一天的累计（重启后从新的一天、从零开始）；已发出的日报不受影响。
+- **事件驱动而非定时**：一天的用量要等下一个事件到达才报告，所以跨夜后若一直没动静，日报会推迟到下一次有事件时补发；那一天从未有回合上报用量则不发射（空日报是噪声）。
+- **零开销**：没有声明任何 `usage/daily` hook 时，插件完全不做累计与跨日检测。
+
+`dsh-hooks dry-run usage/daily` 用「昨天」和非零 token 模拟一次日报，可先验证 match 与命令。
+
+### 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 +280,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

@@ -200,18 +200,22 @@ window.__ModuleLoader__.load({
 		const EVENTS = [
 			"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"
+			"agent/status",
+			"hook/failed",
+			"usage/daily"
 		];
 		const TURN_END_REASONS = [
 			"completed",
@@ -252,6 +256,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 +293,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 +495,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 +1138,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 +1203,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 +1321,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 +1333,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', 'hook/failed'];
+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', 'usage/daily'];
 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 {