dsh-hooks 0.9.1 → 0.11.0

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)
@@ -65,6 +67,10 @@ export function toEnv(ctx) {
         env.DSH_HOOK_TOTAL_SUBAGENTS = String(ctx.totalSubagents);
     if (ctx.treeDurationMs !== undefined)
         env.DSH_HOOK_TREE_DURATION_MS = String(ctx.treeDurationMs);
+    if (ctx.hookFailedHook !== undefined)
+        env.DSH_HOOK_FAILED_HOOK = ctx.hookFailedHook;
+    if (ctx.hookFailures !== undefined)
+        env.DSH_HOOK_FAILURES = String(ctx.hookFailures);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

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;
@@ -119,6 +121,13 @@ export declare function approvalDecidedContext(session: Session, data: ApprovalD
  * off. Emitted by index.ts, not classified from a session log event.
  */
 export declare function treeSettledContext(session: Session, totalSubagents: number, treeDurationMs: number): HookContext;
+/**
+ * Synthetic `hook/failed` context: one hook failed consecutively past the
+ * alert threshold. Emitted by index.ts from the runner/history outcome
+ * stream, not classified from a session log event; `origin` supplies the
+ * session identity of the event that triggered the failing hook.
+ */
+export declare function hookFailedContext(origin: HookContext, hookFailedHook: string, hookFailures: number): HookContext;
 export declare function agentCreatedContext(agent: AgentLike): HookContext;
 export declare function agentDisposedContext(agent: AgentLike): HookContext;
 export declare function agentErrorContext(agent: AgentLike, turn: number | undefined, error: unknown): 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),
     };
@@ -329,6 +386,23 @@ export function treeSettledContext(session, totalSubagents, treeDurationMs) {
         treeDurationMs,
     };
 }
+/**
+ * Synthetic `hook/failed` context: one hook failed consecutively past the
+ * alert threshold. Emitted by index.ts from the runner/history outcome
+ * stream, not classified from a session log event; `origin` supplies the
+ * session identity of the event that triggered the failing hook.
+ */
+export function hookFailedContext(origin, hookFailedHook, hookFailures) {
+    return {
+        event: 'hook/failed',
+        sessionId: origin.sessionId,
+        sessionName: origin.sessionName,
+        cwd: origin.cwd,
+        hookFailedHook,
+        hookFailures,
+        timestamp: new Date().toISOString(),
+    };
+}
 export function agentCreatedContext(agent) {
     return {
         event: 'agent/created',

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 \u5171 16 \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

@@ -1,6 +1,6 @@
 import './types.js';
 import { Config } from './config.js';
-import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookMatches, matchFilters, sessionCreatedContext, sessionDisposedContext, treeSettledContext, } from './events.js';
+import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookFailedContext, hookMatches, matchFilters, sessionCreatedContext, sessionDisposedContext, treeSettledContext, } from './events.js';
 import { eventLabel } from './context.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.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 共 16 类事件），支持 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);
@@ -97,22 +97,109 @@ export function apply(ctx, config = {}) {
     if (systemPrompt !== undefined) {
         ctx.effect(() => systemPrompt.section({ name: 'plugin:dsh-hooks', order: 200, text: DSH_HOOKS_GUIDANCE }), 'dsh-hooks: prompt section');
     }
+    // Consecutive failure tracking for the synthetic hook/failed alert: a hook
+    // that keeps failing is dead automation, and fire-and-forget dispatch would
+    // otherwise let it rot silently. Counters are keyed by hook index, reset on
+    // success, and the alert fires once per streak (dedup until a success).
+    const failureThreshold = Math.max(1, config.failedAlertThreshold ?? 3);
+    const failures = new Map();
+    const alerted = new Set();
+    /** One-line identity of a hook for failure alerts. */
+    function hookFailureSummary(hook) {
+        const when = hook.when ? `/${hook.when}` : '';
+        const action = hook.run ? hook.run : hook.notify ? `notify:${hook.notify.channel}` : '(既无 run 也无 notify)';
+        return `${hook.on}${when}: ${action}`.slice(0, 200);
+    }
     const runMatching = (ctxValue, reasonKind) => {
-        for (const hook of hooks) {
+        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))
-                continue;
+                return;
             if (!matchFilters(hook.match, ctxValue))
-                continue;
-            if (hook.notify) {
-                void fireNotify(hook.notify, ctxValue, (record) => history.record(record));
-                continue;
+                return;
+            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;
+                }
+                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;
+            }
+            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;
             }
-            if (hook.run) {
-                runner.run(hook, ctxValue);
-                continue;
+            if (record.outcome === 'exit-0' || record.outcome === 'sent') {
+                failures.delete(index);
+                alerted.delete(index);
             }
-            console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
+        };
+        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
@@ -193,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.
@@ -210,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) => {
@@ -240,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): 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;