dsh-hooks 0.7.0 → 0.9.0

package/README.md

@@ -75,12 +75,14 @@ Every hook field:
 | Event | When it fires | Useful context |
 | --- | --- | --- |
 | `turn/start` | A turn begins | session id, turn |
-| `turn/end` | A turn ends (`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`) | reason, turn, duration, content, turn token usage |
+| `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 |
 | `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, reason |
+| `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 |
 | `session/title` | The session title updates (explicit rename / LLM title / fallback) | new title, source kind |
 | `session/created` | A session is published | session id, cwd |
 | `session/disposed` | A session leaves the registry | session id, cwd |
@@ -119,9 +121,37 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `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_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 |
+| `DSH_HOOK_DELEGATION_DEPTH` | delegation depth from the session header (`0` = top-level session) |
+| `DSH_HOOK_SESSION_CREATED_AT` | session creation time, epoch ms |
+| `DSH_HOOK_AGENT_PRESET` | agent preset id composing the session's agent, when known |
+| `DSH_HOOK_APPROVAL_ID` | approval audit id (`approval/asked` + `approval/decided`) |
+| `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_TIMESTAMP` | ISO timestamp |
 
 - `{{var}}` placeholders inside `run` are substituted from the same context, e.g. `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`.
+- `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`:
+
+```yaml
+- on: 'turn/end'
+  match: { runningSubagents: '^0$' }  # anchor the regex: bare '0' also matches '10'
+  run: 'node examples/notify-webhook.mjs'
+```
+
+For the simpler "notify only once the whole tree settles" pattern, the synthetic `tree/settled` event does the watching for you — the plugin tracks sessions whose turn ended with running subagents and fires `tree/settled` on that session when the tree reaches zero:
+
+```yaml
+- on: 'tree/settled'
+  notify: { channel: 'webhook', url: 'https://hooks.slack.com/services/…' }
+```
+
+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).
 
 ## Generic webhook example
 

package/README.zh.md

@@ -75,12 +75,14 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | 事件 | 触发时机 | 有用上下文 |
 | --- | --- | --- |
 | `turn/start` | 回合开始 | 会话 id、回合号 |
-| `turn/end` | 回合结束（`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`） | reason、回合号、耗时、内容、本回合 token 用量 |
+| `turn/end` | 回合结束（`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`） | reason、回合号、耗时、内容、本回合 token 用量、运行中子代理数 |
+| `tree/settled` | 回合结束后把工作交给子代理的会话，其整个子代理树全部落定（无存活子代理仍在运行） | 子代理总数、交接到落定的耗时 |
 | `step/end` | 回合内一步结束（一次模型调用 + 其工具执行） | 回合号、步号 |
 | `tool/call` | 模型请求一次工具调用 | 工具名、调用 id、原始参数 JSON |
 | `tool/result` | 工具调用完成 | 工具名（自动反查）、结果文本、失败标识 |
 | `user/message` | 会话表面出现用户角色消息 | 来源 kind（`user` / `plugin` / …）、消息文本 |
-| `approval/asked` | 工具调用请求用户审批 | 工具名、调用 id、原因 |
+| `approval/asked` | 工具调用请求用户审批 | 工具名、调用 id、审批 id、原因 |
+| `approval/decided` | 待审批项得出结果（与 `approval/asked` 按 id 配对） | 结果 outcome、工具名（自动反查）、调用 id、审批 id |
 | `session/title` | 会话标题更新（显式改名 / LLM 生成 / 回退） | 新标题、来源 kind |
 | `session/created` | 会话发布 | 会话 id、cwd |
 | `session/disposed` | 会话离开注册表 | 会话 id、cwd |
@@ -119,9 +121,37 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `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` |
+| `DSH_HOOK_DELEGATION_DEPTH` | 会话头中的委托深度（`0` = 顶层会话） |
+| `DSH_HOOK_SESSION_CREATED_AT` | 会话创建时间，epoch 毫秒 |
+| `DSH_HOOK_AGENT_PRESET` | 组合该会话 Agent 的预设 id（有值时） |
+| `DSH_HOOK_APPROVAL_ID` | 审批审计 id（`approval/asked` 与 `approval/decided` 共用） |
+| `DSH_HOOK_APPROVAL_OUTCOME` | 审批结果 outcome（`approval/decided`） |
+| `DSH_HOOK_TOTAL_SUBAGENTS` | 已落定树中的子代理总数（`tree/settled`） |
+| `DSH_HOOK_TREE_DURATION_MS` | 父回合结束 → 树落定的耗时（毫秒，`tree/settled`） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
+- `turn/end` 的 hook 在运行中子代理计数解析完成后才派发，比其他事件晚一个异步跳——同会话紧随其后的事件（如下一轮 `turn/start`）可能先执行。
+
+`DSH_HOOK_RUNNING_SUBAGENTS` 的典型用法：后台子代理还在运行时抑制回合结束通知，只在本会话回合真正落定时才通知。注意父会话只会收到一次 `turn/end`（此时计数 > 0）；「全部落定」的信号由最后一个子会话自己的 `turn/end`（计数为 `0`）送达：
+
+```yaml
+- on: 'turn/end'
+  match: { runningSubagents: '^0$' }  # 正则要锚定：裸 '0' 也会匹配 '10'
+  run: 'node examples/notify-webhook.mjs'
+```
+
+如果只想要「整棵树落定才通知一次」的简单模式，合成事件 `tree/settled` 帮你做了监视：插件跟踪回合结束时仍有运行中子代理的会话，树归零时对该会话发射 `tree/settled`：
+
+```yaml
+- on: 'tree/settled'
+  notify: { channel: 'webhook', url: 'https://hooks.slack.com/services/…' }
+```
+
+已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。落定监视是事件驱动且 best-effort 的：插件重启后监视集合丢失；重查失败会静默放弃该监视（不会补发迟到的通知）。
 
 ## 执行历史
 

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', 'step/end', 'tool/call', 'tool/result', 'user/message', 'approval/asked', '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'];
 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'];

package/lib/config.js

@@ -3,11 +3,13 @@ import Schema from '@deepseek-ai/schemastery';
 export const HOOK_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',
@@ -31,7 +33,7 @@ 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 | step/end | tool/call | tool/result | user/message | approval/asked | 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'),
         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/…），上下文中不存在的字段视为不匹配'),
         run: Schema.string().description('触发时通过系统 shell 执行的命令（与 notify 二选一）'),

package/lib/context.d.ts

@@ -36,6 +36,30 @@ export interface HookContext {
     usageCacheReadTokens?: number;
     usageCacheWriteTokens?: number;
     usageReasoningTokens?: number;
+    /**
+     * Number of live subagents still running under this session at `turn/end`
+     * (0 = none). Always present on `turn/end`; the plugin fills the real count
+     * from the agents/subagents services when they are available.
+     */
+    runningSubagents?: number;
+    /** Subagent lineage: the parent session id (session header `parentSession`). */
+    parentSessionId?: string;
+    /** Whether the session was created as a subagent child (header `origin`). */
+    subagent?: boolean;
+    /** Delegation depth from the session header; 0 = top-level session. */
+    delegationDepth?: number;
+    /** Session creation time, epoch ms (session header `createdAt`). */
+    sessionCreatedAt?: number;
+    /** Agent preset id that composed the session's agent (header `agentPreset`). */
+    agentPreset?: string;
+    /** Approval audit id, pairing `approval/asked` with `approval/decided`. */
+    approvalId?: string;
+    /** Approval decision outcome (approval/decided). */
+    approvalOutcome?: string;
+    /** Total subagents in the settled tree (tree/settled). */
+    totalSubagents?: number;
+    /** Parent turn/end → tree settle duration, ms (tree/settled). */
+    treeDurationMs?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;

package/lib/context.js

@@ -45,6 +45,26 @@ export function toEnv(ctx) {
         env.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS = String(ctx.usageCacheWriteTokens);
     if (ctx.usageReasoningTokens !== undefined)
         env.DSH_HOOK_USAGE_REASONING_TOKENS = String(ctx.usageReasoningTokens);
+    if (ctx.runningSubagents !== undefined)
+        env.DSH_HOOK_RUNNING_SUBAGENTS = String(ctx.runningSubagents);
+    if (ctx.parentSessionId !== undefined)
+        env.DSH_HOOK_PARENT_SESSION_ID = ctx.parentSessionId;
+    if (ctx.subagent !== undefined)
+        env.DSH_HOOK_SUBAGENT = ctx.subagent ? '1' : '0';
+    if (ctx.delegationDepth !== undefined)
+        env.DSH_HOOK_DELEGATION_DEPTH = String(ctx.delegationDepth);
+    if (ctx.sessionCreatedAt !== undefined)
+        env.DSH_HOOK_SESSION_CREATED_AT = String(ctx.sessionCreatedAt);
+    if (ctx.agentPreset !== undefined)
+        env.DSH_HOOK_AGENT_PRESET = ctx.agentPreset;
+    if (ctx.approvalId !== undefined)
+        env.DSH_HOOK_APPROVAL_ID = ctx.approvalId;
+    if (ctx.approvalOutcome !== undefined)
+        env.DSH_HOOK_APPROVAL_OUTCOME = ctx.approvalOutcome;
+    if (ctx.totalSubagents !== undefined)
+        env.DSH_HOOK_TOTAL_SUBAGENTS = String(ctx.totalSubagents);
+    if (ctx.treeDurationMs !== undefined)
+        env.DSH_HOOK_TREE_DURATION_MS = String(ctx.treeDurationMs);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

package/lib/events.d.ts

@@ -9,6 +9,11 @@ export interface ApprovalAskedData {
     callId?: string;
     reason?: string;
 }
+/** `approval/decided` payload (merge-extensible, declared by dsh-user-approval). */
+export interface ApprovalDecidedData {
+    id: string;
+    outcome: string;
+}
 /** `session/title` payload (merge-extensible, declared by dsh-session-title). */
 export interface SessionTitleEventData {
     title: string;
@@ -25,6 +30,7 @@ export interface SessionTitleEventData {
 declare module '@deepseek-ai/dsh-session/types' {
     interface SessionEventMap {
         'approval/asked': ApprovalAskedData;
+        'approval/decided': ApprovalDecidedData;
         'session/title': SessionTitleEventData;
     }
 }
@@ -106,6 +112,13 @@ export declare function titleContext(session: Session, title: unknown, source: u
 export declare function sessionCreatedContext(session: Session): HookContext;
 export declare function sessionDisposedContext(session: Session): HookContext;
 export declare function approvalContext(session: Session, data: ApprovalAskedData): HookContext;
+export declare function approvalDecidedContext(session: Session, data: ApprovalDecidedData): HookContext;
+/**
+ * Synthetic `tree/settled` context: the session's whole subagent tree has
+ * settled (no live child still running) after a turn ended with work handed
+ * off. Emitted by index.ts, not classified from a session log event.
+ */
+export declare function treeSettledContext(session: Session, totalSubagents: number, treeDurationMs: 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

@@ -2,12 +2,17 @@
 const turnStarts = new Map();
 /** Tool name for an in-flight call, remembered at `tool/call` and consumed at `tool/result`. */
 const callTools = new Map();
+/** Approval identity remembered at `approval/asked` and consumed at `approval/decided`. */
+const approvalTools = new Map();
 function sessionKey(session) {
     return String(session.id);
 }
 function callKey(session, callId) {
     return `${sessionKey(session)}\u0000${String(callId)}`;
 }
+function approvalKey(session, id) {
+    return `${sessionKey(session)}\u0000${String(id)}`;
+}
 /** Best-effort access to a session's event log (test fakes may omit it). */
 function sessionEvents(session) {
     return Array.isArray(session.events) ? session.events : [];
@@ -155,12 +160,27 @@ export function matchFilters(match, ctx) {
     }
     return true;
 }
+/**
+ * Session-header lineage/metadata shared by every session-backed context:
+ * subagent parentage, delegation depth, creation time, and agent preset.
+ */
+function sessionMeta(session) {
+    const header = session.header;
+    return {
+        parentSessionId: header.parentSession,
+        subagent: header.origin === 'subagent',
+        delegationDepth: header.delegationDepth ?? 0,
+        sessionCreatedAt: header.createdAt,
+        agentPreset: header.agentPreset,
+    };
+}
 function baseContext(session, event) {
     return {
         event,
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
+        ...sessionMeta(session),
         timestamp: new Date().toISOString(),
     };
 }
@@ -185,6 +205,9 @@ export function turnEndContext(session, turn, reason) {
         usageCacheReadTokens: usage?.cacheReadTokens,
         usageCacheWriteTokens: usage?.cacheWriteTokens,
         usageReasoningTokens: usage?.reasoningTokens,
+        // Default until index.ts fills the live count from the agents/subagents
+        // services (0 = no subagent running under this session).
+        runningSubagents: 0,
     };
 }
 export function turnStartContext(session, turn) {
@@ -256,6 +279,7 @@ export function sessionCreatedContext(session) {
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
+        ...sessionMeta(session),
         timestamp: new Date().toISOString(),
     };
 }
@@ -265,17 +289,46 @@ export function sessionDisposedContext(session) {
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
+        ...sessionMeta(session),
         timestamp: new Date().toISOString(),
     };
 }
 export function approvalContext(session, data) {
+    approvalTools.set(approvalKey(session, data.id), { toolName: data.toolName, callId: data.callId });
     return {
         ...baseContext(session, 'approval/asked'),
+        approvalId: data.id,
         tool: data.toolName,
         callId: data.callId,
         reason: data.reason,
     };
 }
+export function approvalDecidedContext(session, data) {
+    const key = approvalKey(session, data.id);
+    const paired = approvalTools.get(key);
+    if (paired !== undefined)
+        approvalTools.delete(key);
+    return {
+        ...baseContext(session, 'approval/decided'),
+        approvalId: data.id,
+        approvalOutcome: data.outcome,
+        tool: paired?.toolName,
+        callId: paired?.callId,
+    };
+}
+/**
+ * Synthetic `tree/settled` context: the session's whole subagent tree has
+ * settled (no live child still running) after a turn ended with work handed
+ * off. Emitted by index.ts, not classified from a session log event.
+ */
+export function treeSettledContext(session, totalSubagents, treeDurationMs) {
+    return {
+        ...baseContext(session, 'tree/settled'),
+        reason: 'settled',
+        totalSubagents,
+        treeDurationMs,
+    };
+}
 export function agentCreatedContext(agent) {
     return {
         event: 'agent/created',
@@ -331,6 +384,8 @@ export function classifySessionEvent(session, event) {
             return userMessageContext(session, event.data.content, event.data.source);
         case 'approval/asked':
             return approvalContext(session, event.data);
+        case 'approval/decided':
+            return approvalDecidedContext(session, event.data);
         case 'session/title':
             return titleContext(session, event.data.title, event.data.source);
         default:

package/lib/index.d.ts

@@ -3,6 +3,54 @@ import './types.js';
 import { Config } from './config.js';
 import { clearTurnTracking } from './events.js';
 export declare const name = "dsh-hooks";
+/** Minimal structural contract of the optional `agents` service. */
+interface AgentsLike {
+    get(id: string): {
+        id: string;
+        status: string;
+    } | undefined;
+    list(): Array<{
+        id: string;
+        status: string;
+    }>;
+    isOwnedBy(id: string, owner: {
+        id: string;
+    }): boolean;
+}
+/** Minimal structural contract of the optional `subagents` service. */
+interface SubagentsLike {
+    listDescendants(rootSessionId: string): Promise<Array<{
+        id?: string;
+    }>>;
+}
+/** Snapshot of one session's subagent tree: live-running plus total descendants. */
+export interface SubagentTreeStats {
+    /** Descendants whose live agent status is `running`. */
+    running: number;
+    /** Total descendants in the durable tree (running, idle, or settled). */
+    total: number;
+}
+/**
+ * Inspect one session's descendant subagent tree.
+ *
+ * Lineage comes from the durable session tree (`subagents.listDescendants`,
+ * driven by the session header `parentSession`): a subagent's runtime owner
+ * in the agents registry is the subagent manager's host-level scope, not the
+ * parent agent, so ownership chains (`agents.isOwnedBy`) cannot find children.
+ * Only agents whose live status is `running` count as running — a settled/idle
+ * continuable child does not. Returns `{ running: 0, total: 0 }` when the
+ * session has no live agent or the services are unavailable.
+ *
+ * The live-registry scan is strictly a fallback for when listing is
+ * unavailable (service absent or listing threw): a successful empty listing
+ * stays empty, so ordinary subagent-free turns don't pay an O(registry) scan.
+ */
+export declare function inspectSubagentTree(agents: AgentsLike, subagents: SubagentsLike | undefined, sessionId: string | undefined): Promise<SubagentTreeStats>;
+/**
+ * Count live agents still running in one session's descendant subagent tree
+ * (the `running` half of {@link inspectSubagentTree}).
+ */
+export declare function countRunningSubagents(agents: AgentsLike, subagents: SubagentsLike | undefined, sessionId: string | undefined): Promise<number>;
 export declare const inject: readonly ['sessions'];
 export { Config };
 export { hookMatches, matchFilters } from './events.js';
@@ -11,8 +59,10 @@ 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\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status \u5171 14 \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 \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 function apply(ctx: Context, config?: Config): void;
 export declare const _internals: {
     clearTurnTracking: typeof clearTurnTracking;
+    countRunningSubagents: typeof countRunningSubagents;
+    inspectSubagentTree: typeof inspectSubagentTree;
 };

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, } from './events.js';
+import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookMatches, matchFilters, sessionCreatedContext, sessionDisposedContext, treeSettledContext, } from './events.js';
 import { eventLabel } from './context.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.js';
@@ -8,6 +8,61 @@ import { createHistorySink } from './history.js';
 import { createFeishuSetupManager } from './feishu-session.js';
 import { registerHookRoutes } from './server.js';
 export const name = 'dsh-hooks';
+/**
+ * Inspect one session's descendant subagent tree.
+ *
+ * Lineage comes from the durable session tree (`subagents.listDescendants`,
+ * driven by the session header `parentSession`): a subagent's runtime owner
+ * in the agents registry is the subagent manager's host-level scope, not the
+ * parent agent, so ownership chains (`agents.isOwnedBy`) cannot find children.
+ * Only agents whose live status is `running` count as running — a settled/idle
+ * continuable child does not. Returns `{ running: 0, total: 0 }` when the
+ * session has no live agent or the services are unavailable.
+ *
+ * The live-registry scan is strictly a fallback for when listing is
+ * unavailable (service absent or listing threw): a successful empty listing
+ * stays empty, so ordinary subagent-free turns don't pay an O(registry) scan.
+ */
+export async function inspectSubagentTree(agents, subagents, sessionId) {
+    if (sessionId === undefined || agents.get(sessionId) === undefined)
+        return { running: 0, total: 0 };
+    let ids = [];
+    let listed = false;
+    if (subagents !== undefined) {
+        try {
+            ids = (await subagents.listDescendants(sessionId))
+                .map((row) => row.id)
+                .filter((id) => typeof id === 'string' && id !== sessionId);
+            listed = true;
+        }
+        catch {
+            // listing unavailable — fall back to the live-registry child scan below
+        }
+    }
+    if (!listed) {
+        const owner = agents.get(sessionId);
+        if (owner === undefined)
+            return { running: 0, total: 0 };
+        ids = agents
+            .list()
+            .filter((candidate) => candidate !== owner && agents.isOwnedBy(candidate.id, owner))
+            .map((candidate) => candidate.id);
+    }
+    let running = 0;
+    for (const id of ids) {
+        const agent = agents.get(id);
+        if (agent !== undefined && agent.status === 'running')
+            running++;
+    }
+    return { running, total: ids.length };
+}
+/**
+ * Count live agents still running in one session's descendant subagent tree
+ * (the `running` half of {@link inspectSubagentTree}).
+ */
+export async function countRunningSubagents(agents, subagents, sessionId) {
+    return (await inspectSubagentTree(agents, subagents, sessionId)).running;
+}
 // Dependency on the session service: `session/event` only exists once a
 // SessionStore is composed, and this plugin consumes the durable firehose.
 export const inject = ['sessions'];
@@ -18,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、step/end、tool/call、tool/result、user/message、approval/asked、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status 共 14 类事件），支持 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 共 16 类事件），支持 when 原因过滤、match 字段正则过滤、stdin JSON 输入、opt-in 重试、内置 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);
@@ -59,6 +114,78 @@ export function apply(ctx, config = {}) {
             console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(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
+    // "the turn finished for real". The services are read lazily at event time —
+    // at plugin apply time the agents/subagents rows may not be composed yet.
+    let warnedAgentsUnavailable = false;
+    const watchedTrees = new Map();
+    /**
+     * Re-check every watched tree on subagent-activity signals (any turn/end or
+     * agent/status). Each entry is claimed (deleted) before its await, so a
+     * concurrent refresh can never emit the same settle twice; entries whose
+     * tree is still running are re-armed. Best-effort: a failed re-check or a
+     * vanished service drops the watch silently instead of leaking it.
+     */
+    const refreshWatchedTrees = async () => {
+        if (watchedTrees.size === 0)
+            return;
+        const agents = ctx.get('agents', false);
+        if (agents === undefined) {
+            watchedTrees.clear();
+            return;
+        }
+        const subagents = ctx.get('subagents', false);
+        for (const [sessionId, entry] of [...watchedTrees]) {
+            watchedTrees.delete(sessionId);
+            try {
+                const { running, total } = await inspectSubagentTree(agents, subagents, sessionId);
+                if (running === 0) {
+                    runMatching(treeSettledContext(entry.session, total, Date.now() - entry.startedAt));
+                }
+                else {
+                    watchedTrees.set(sessionId, entry);
+                }
+            }
+            catch {
+                // Re-check failed: the claim above already dropped the entry.
+            }
+        }
+    };
+    const matchAfterSubagentCount = async (session, ctxValue, reasonKind) => {
+        const agents = ctx.get('agents', false);
+        if (agents === undefined) {
+            // Warn once, not on every turn/end: profiles without the agents service
+            // would otherwise spam the log on each turn boundary.
+            if (!warnedAgentsUnavailable) {
+                warnedAgentsUnavailable = true;
+                ctx.logger?.warn?.('[dsh-hooks] agents service unavailable at turn/end — runningSubagents stays 0');
+            }
+        }
+        else {
+            const subagents = ctx.get('subagents', false);
+            const sessionId = String(session.id);
+            try {
+                const { running } = await inspectSubagentTree(agents, subagents, ctxValue.sessionId);
+                ctxValue.runningSubagents = running;
+                if (running > 0) {
+                    // Work was handed off: watch this tree until it settles. A re-handoff
+                    // on a later turn restarts the settle clock from that turn/end.
+                    watchedTrees.set(sessionId, { session, startedAt: Date.now() });
+                }
+                else {
+                    watchedTrees.delete(sessionId);
+                }
+            }
+            catch (error) {
+                ctx.logger?.warn?.('[dsh-hooks] failed to count running subagents: %s', String(error));
+            }
+        }
+        runMatching(ctxValue, reasonKind);
+        void refreshWatchedTrees().catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] tree settle refresh failed: %s', String(error));
+        });
+    };
     // Durable session firehose: turn boundaries, steps, tool calls, messages,
     // titles, and approval requests.
     ctx.on('session/event', (session, event) => {
@@ -66,14 +193,28 @@ export function apply(ctx, config = {}) {
         if (classified === undefined)
             return;
         const reasonKind = extractReasonKind(event);
-        runMatching(classified, reasonKind);
+        if (classified.event !== 'turn/end') {
+            runMatching(classified, reasonKind);
+            return;
+        }
+        // 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.
+        void matchAfterSubagentCount(session, classified, reasonKind).catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] turn/end dispatch failed: %s', String(error));
+        });
     });
     // Session lifecycle (published by the session store, not the firehose).
     ctx.on('session/created', (session) => {
         runMatching(sessionCreatedContext(session));
     });
     ctx.on('session/disposed', (session) => {
+        watchedTrees.delete(String(session.id));
         runMatching(sessionDisposedContext(session));
+        // A child session leaving the store is also settle-relevant activity.
+        void refreshWatchedTrees().catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] tree settle refresh failed: %s', String(error));
+        });
     });
     // Agent lifecycle events.
     ctx.on('agent/created', (payload) => {
@@ -81,15 +222,25 @@ export function apply(ctx, config = {}) {
     });
     ctx.on('agent/disposed', (payload) => {
         runMatching(agentDisposedContext(payload.agent));
+        // A disposed (interrupted/killed) child agent can never settle on its
+        // own — re-check watched trees so its parent's settle still fires.
+        void refreshWatchedTrees().catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] tree settle refresh failed: %s', String(error));
+        });
     });
     ctx.on('agent/error', (payload) => {
         runMatching(agentErrorContext(payload.agent, payload.turn, payload.error));
     });
     ctx.on('agent/status', (payload) => {
         runMatching(agentStatusContext(payload.agent, payload.status));
+        // A child agent going idle is the settle signal for watched trees.
+        void refreshWatchedTrees().catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] tree settle refresh failed: %s', String(error));
+        });
     });
     ctx.effect(() => () => {
         runner.dispose();
+        watchedTrees.clear();
     });
 }
 /** Extract the `turn/end` reason kind from a session event, when present. */
@@ -101,6 +252,6 @@ function extractReasonKind(event) {
         return undefined;
     return typeof e.data?.reason?.kind === 'string' ? e.data.reason.kind : undefined;
 }
-// Referenced only for tree-shaking clarity of the module contract; clearTurnTracking
-// is exported for tests that need deterministic duration bookkeeping.
-export const _internals = { clearTurnTracking };
+// Referenced only for tree-shaking clarity of the module contract; exported
+// for tests that need deterministic bookkeeping.
+export const _internals = { clearTurnTracking, countRunningSubagents, inspectSubagentTree };

package/lib/server.d.ts

@@ -48,7 +48,7 @@ export interface HookRoutesOptions {
 /** Sanitized per-hook description for the settings panel (regex sources, no RegExp objects). */
 export declare function describeHooks(hooks: readonly HookSpec[]): {
     index: number;
-    on: "agent/created" | "agent/disposed" | "agent/error" | "agent/status" | "approval/asked" | "session/created" | "session/disposed" | "session/title" | "step/end" | "tool/call" | "tool/result" | "turn/end" | "turn/start" | "user/message";
+    on: "agent/created" | "agent/disposed" | "agent/error" | "agent/status" | "approval/asked" | "approval/decided" | "session/created" | "session/disposed" | "session/title" | "step/end" | "tool/call" | "tool/result" | "tree/settled" | "turn/end" | "turn/start" | "user/message";
     when: "aborted" | "blocked" | "completed" | "error" | "interrupted" | "max-tokens" | undefined;
     match: {
         [k: string]: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hooks",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "packageManager": "pnpm@11.21.0",
   "description": "Config-driven lifecycle hooks plugin for DeepSeek Harness: declare event -> command hooks in cordis.patch.yml, no plugin code required. Includes a Hooks section in the Web GUI settings (history timeline + manual tester + notify tests + hook editor + Feishu connect).",
   "author": "PeterBon",
@@ -79,7 +79,7 @@
     "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@tsdown/css": "^0.22.14",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",
     "react": "^18.3.1",