dsh-hooks 0.2.2 → 0.4.0

package/lib/config.js

@@ -3,7 +3,14 @@ import Schema from '@deepseek-ai/schemastery';
 export const HOOK_EVENTS = [
     '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',
@@ -24,11 +31,39 @@ 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 | approval/asked | agent/created | agent/disposed | agent/error | agent/status'),
+        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'),
         when: Schema.union([...TURN_END_REASONS]).description('可选过滤：对 turn/end 匹配结束原因（completed/error/aborted/blocked/max-tokens/interrupted）；其他事件忽略该字段'),
-        run: Schema.string().required().description('触发时通过系统 shell 执行的命令'),
+        match: Schema.dict(Schema.regExp()).description('可选通用过滤：字段 → 正则，全部匹配才触发。字段为上下文键（tool/sessionName/sessionId/error/source/cwd/content/reason/…），上下文中不存在的字段视为不匹配'),
+        run: Schema.string().description('触发时通过系统 shell 执行的命令（与 notify 二选一）'),
+        notify: Schema.union([
+            Schema.object({
+                channel: Schema.union(['webhook', 'desktop'])
+                    .required()
+                    .description('通知渠道：webhook 发 HTTP JSON；desktop 发系统桌面通知'),
+                url: Schema.string().description('webhook 渠道的目标 URL（缺省时用环境变量 DSH_HOOKS_WEBHOOK_URL）'),
+                slack: Schema.boolean().default(false).description('webhook 渠道：改为发送 Slack 风格 { text } 单行摘要'),
+            }),
+            Schema.const(null),
+        ])
+            .default(null)
+            .description('内置通知（与 run 二选一）：配置驱动发送，无需外部脚本'),
+        input: Schema.union(['env', 'stdin'])
+            .default('env')
+            .description('上下文传递方式：env 只传 DSH_HOOK_* 环境变量（默认）；stdin 额外把完整上下文 JSON 写入命令标准输入'),
         timeoutMs: Schema.number().default(10000).description('单次执行超时（毫秒）'),
-    }).description('一个事件 → 命令的 hook 声明'))
+        retries: Schema.natural().default(0).description('非零退出码的重试次数（默认 0 不重试；spawn 失败与超时不重试）'),
+        retryDelayMs: Schema.natural().default(500).description('重试基础间隔（毫秒），每次翻倍'),
+    }).description('一个事件 → 命令/通知的 hook 声明'))
         .default([])
         .description('事件触发时执行的外部命令列表；按声明顺序触发'),
+    history: Schema.union([
+        Schema.object({
+            enabled: Schema.boolean().default(true).description('是否把执行历史持久化到磁盘（默认 true）'),
+            path: Schema.string().description('JSONL 文件路径（默认 ~/.dsh/dsh-hooks/history.jsonl，权限 0600）'),
+            max: Schema.natural().default(500).description('内存环形缓冲条数（默认 500）'),
+        }),
+        Schema.const(null),
+    ])
+        .default(null)
+        .description('hook 执行历史：内存环形缓冲 + 可选 JSONL 持久化日志（供 UI/调试使用，严格 best-effort）'),
 }).description('dsh-hooks 配置：声明式生命周期 hooks');

package/lib/context.d.ts

@@ -14,14 +14,28 @@ export interface HookContext {
     /** Absolute working directory of the session, when known. */
     cwd?: string;
     turn?: number;
+    /** Step number of the turn (step and tool events). */
+    step?: number;
     reason?: string;
     tool?: string;
     callId?: string;
+    /** Raw tool-call arguments JSON as the model produced it (tool/call). */
+    toolArgs?: string;
+    /** Tool failure identity (`name`/`code`) when a tool result errored. */
+    toolError?: string;
+    /** Producer source kind: user message source, title source, etc. */
+    source?: string;
     durationMs?: number;
     status?: string;
     error?: string;
-    /** Turn content snapshot, e.g. the turn's final assistant text. */
+    /** Event content snapshot: turn assistant text, tool result text, … */
     content?: string;
+    /** Aggregated token usage of the turn (turn/end), when reported. */
+    usageInputTokens?: number;
+    usageOutputTokens?: number;
+    usageCacheReadTokens?: number;
+    usageCacheWriteTokens?: number;
+    usageReasoningTokens?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;

package/lib/context.js

@@ -13,12 +13,20 @@ export function toEnv(ctx) {
         env.DSH_HOOK_CWD = ctx.cwd;
     if (ctx.turn !== undefined)
         env.DSH_HOOK_TURN = String(ctx.turn);
+    if (ctx.step !== undefined)
+        env.DSH_HOOK_STEP = String(ctx.step);
     if (ctx.reason !== undefined)
         env.DSH_HOOK_REASON = ctx.reason;
     if (ctx.tool !== undefined)
         env.DSH_HOOK_TOOL = ctx.tool;
     if (ctx.callId !== undefined)
         env.DSH_HOOK_CALL_ID = ctx.callId;
+    if (ctx.toolArgs !== undefined)
+        env.DSH_HOOK_TOOL_ARGS = ctx.toolArgs;
+    if (ctx.toolError !== undefined)
+        env.DSH_HOOK_TOOL_ERROR = ctx.toolError;
+    if (ctx.source !== undefined)
+        env.DSH_HOOK_SOURCE = ctx.source;
     if (ctx.durationMs !== undefined)
         env.DSH_HOOK_DURATION_MS = String(ctx.durationMs);
     if (ctx.status !== undefined)
@@ -27,6 +35,16 @@ export function toEnv(ctx) {
         env.DSH_HOOK_ERROR = ctx.error;
     if (ctx.content !== undefined)
         env.DSH_HOOK_CONTENT = ctx.content;
+    if (ctx.usageInputTokens !== undefined)
+        env.DSH_HOOK_USAGE_INPUT_TOKENS = String(ctx.usageInputTokens);
+    if (ctx.usageOutputTokens !== undefined)
+        env.DSH_HOOK_USAGE_OUTPUT_TOKENS = String(ctx.usageOutputTokens);
+    if (ctx.usageCacheReadTokens !== undefined)
+        env.DSH_HOOK_USAGE_CACHE_READ_TOKENS = String(ctx.usageCacheReadTokens);
+    if (ctx.usageCacheWriteTokens !== undefined)
+        env.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS = String(ctx.usageCacheWriteTokens);
+    if (ctx.usageReasoningTokens !== undefined)
+        env.DSH_HOOK_USAGE_REASONING_TOKENS = String(ctx.usageReasoningTokens);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

package/lib/dry-run.d.ts

@@ -0,0 +1,48 @@
+import { type HookSpec, type TurnEndReasonKind } from './config.js';
+import type { HookContext } from './context.js';
+/** Profile patch file for a profile name. */
+export declare function patchFilePath(profile: string): string;
+/**
+ * Load and normalize the dsh-hooks config block from a profile's
+ * cordis.patch.yml. Runs the block through the Config schema so match
+ * regexes compile and invalid entries fail loudly.
+ */
+export declare function loadHooks(profile: string, paths?: {
+    patchFile?: string;
+}): {
+    hooks: HookSpec[];
+    source: string;
+};
+/** A synthetic context for the simulated event, overridable per field. */
+export declare function mockContext(event: string, overrides?: Partial<HookContext>): HookContext;
+export interface DryRunLine {
+    /** 1-based hook index in the config. */
+    index: number;
+    matched: boolean;
+    /** Short reason the hook was skipped (empty when matched). */
+    why: string;
+    /** One-line hook description. */
+    summary: string;
+}
+/** One-line hook description for report rows. */
+export declare function describeHook(hook: HookSpec): string;
+/** Evaluate every hook against the simulated event/context. */
+export declare function evaluateHooks(hooks: readonly HookSpec[], event: string, ctx: HookContext, reasonKind?: TurnEndReasonKind): DryRunLine[];
+export interface DryRunOptions {
+    profile?: string;
+    event: string;
+    reason?: TurnEndReasonKind;
+    tool?: string;
+    sessionName?: string;
+    /** Actually run the matching hooks (real side effects!). */
+    execute?: boolean;
+    print?: (line: string) => void;
+    paths?: {
+        patchFile?: string;
+    };
+}
+/** Full dry-run report; optionally executes the matching hooks. */
+export declare function runDryRun(options: DryRunOptions): Promise<{
+    matched: number;
+    total: number;
+}>;

package/lib/dry-run.js

@@ -0,0 +1,136 @@
+/**
+ * dry-run: simulate a hook event against a profile's dsh-hooks config and
+ * report which hooks would fire (and why the others would not). `--execute`
+ * actually runs the matching hooks, for end-to-end verification.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { Config } from './config.js';
+import { matchFilters } from './events.js';
+import { createHookRunner } from './runner.js';
+import { fireNotify } from './notify.js';
+/** Profile patch file for a profile name. */
+export function patchFilePath(profile) {
+    return join(homedir(), '.dsh', 'profiles', profile, 'cordis.patch.yml');
+}
+/**
+ * Load and normalize the dsh-hooks config block from a profile's
+ * cordis.patch.yml. Runs the block through the Config schema so match
+ * regexes compile and invalid entries fail loudly.
+ */
+export function loadHooks(profile, paths = {}) {
+    const file = paths.patchFile ?? patchFilePath(profile);
+    if (!existsSync(file))
+        throw new Error(`未找到 ${file}（profile 不存在或没有 cordis.patch.yml）`);
+    let entries;
+    try {
+        entries = YAML.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new Error(`cordis.patch.yml 解析失败：${file}`);
+    }
+    if (!Array.isArray(entries))
+        throw new Error('cordis.patch.yml 顶层必须是 YAML 数组');
+    let block;
+    for (const entry of entries) {
+        if (entry !== null && typeof entry === 'object' && entry.id === 'dsh-hooks') {
+            block = entry;
+            break;
+        }
+    }
+    if (block === undefined)
+        throw new Error('cordis.patch.yml 中没有 id: dsh-hooks 的配置块');
+    const rawHooks = block.config?.hooks;
+    const config = Config({ hooks: (Array.isArray(rawHooks) ? rawHooks : []) });
+    return { hooks: config.hooks ?? [], source: file };
+}
+/** A synthetic context for the simulated event, overridable per field. */
+export function mockContext(event, overrides = {}) {
+    return {
+        event,
+        sessionId: 'dry-run',
+        sessionName: 'dry-run 会话',
+        cwd: process.cwd(),
+        turn: 1,
+        step: 1,
+        tool: 'pwsh',
+        callId: 'dry-run-call',
+        content: 'dry-run 模拟内容',
+        timestamp: new Date().toISOString(),
+        ...overrides,
+    };
+}
+/** 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])))},`
+        : '';
+    if (hook.run)
+        return `[${hook.on}${when}]${match} run: ${hook.run}`;
+    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)`;
+}
+/** 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.on !== event) {
+            return { index: index + 1, matched: false, why: `事件不匹配（${hook.on} ≠ ${event}）`, summary };
+        }
+        if (event === 'turn/end' && hook.when !== undefined && hook.when !== reasonKind) {
+            return { index: index + 1, matched: false, why: `when 不匹配（期望 ${hook.when}，实际 ${reasonKind ?? '无'}）`, summary };
+        }
+        if (!matchFilters(hook.match, ctx)) {
+            return { index: index + 1, matched: false, why: 'match 过滤未通过', summary };
+        }
+        return { index: index + 1, matched: true, why: '', summary };
+    });
+}
+/** Full dry-run report; optionally executes the matching hooks. */
+export async function runDryRun(options) {
+    const profile = options.profile ?? 'web';
+    const print = options.print ?? console.log;
+    const { hooks, source } = loadHooks(profile, options.paths);
+    const reasonKind = options.reason;
+    const ctx = mockContext(options.event, {
+        reason: reasonKind,
+        tool: options.tool,
+        sessionName: options.sessionName,
+    });
+    print('dsh-hooks dry-run');
+    print(`配置来源：${source}（${hooks.length} 个 hook）`);
+    print(`模拟事件：${options.event}${reasonKind ? `（reason=${reasonKind}）` : ''}`);
+    const lines = evaluateHooks(hooks, options.event, ctx, reasonKind);
+    for (const line of lines) {
+        print(line.matched ? `✅ [${line.index}] ${line.summary}` : `⏭ [${line.index}] ${line.summary} —— ${line.why}`);
+    }
+    const matched = lines.filter((line) => line.matched);
+    if (options.execute) {
+        if (matched.length === 0) {
+            print('没有匹配的 hook 可执行');
+        }
+        const runner = createHookRunner((line) => print(`  ${line}`));
+        for (const line of matched) {
+            const hook = hooks[line.index - 1];
+            if (hook.run) {
+                print(`▶ 执行 [${line.index}] ${describeHook(hook)}`);
+                const outcome = runner.run(hook, ctx);
+                if (!outcome.ok)
+                    print(`  ✗ ${outcome.reason}${outcome.detail ? `: ${outcome.detail}` : ''}`);
+            }
+            else if (hook.notify) {
+                print(`▶ 发送 [${line.index}] notify:${hook.notify.channel}`);
+                await fireNotify(hook.notify, ctx);
+            }
+        }
+        print('（run 命令 fire-and-forget：执行结果见 dsh 日志）');
+    }
+    else if (matched.length > 0) {
+        print(`共 ${matched.length} 个 hook 会触发。加 --execute 实际执行（真实副作用！）`);
+    }
+    return { matched: matched.length, total: hooks.length };
+}

package/lib/events.d.ts

@@ -9,9 +9,23 @@ export interface ApprovalAskedData {
     callId?: string;
     reason?: string;
 }
+/** `session/title` payload (merge-extensible, declared by dsh-session-title). */
+export interface SessionTitleEventData {
+    title: string;
+    messageSeqs: number[];
+    source: {
+        kind: 'fallback';
+    } | {
+        kind: 'provider';
+        provider?: unknown;
+    } | {
+        kind: 'user';
+    };
+}
 declare module '@deepseek-ai/dsh-session/types' {
     interface SessionEventMap {
         'approval/asked': ApprovalAskedData;
+        'session/title': SessionTitleEventData;
     }
 }
 /** Agent lifecycle payloads (structural; emitted by dsh-agent's AgentService). */
@@ -45,12 +59,52 @@ export declare function sessionTitle(session: Session): string | undefined;
  * their own display truncation.
  */
 export declare function turnContent(session: Session, turn: number): string | undefined;
+/** Aggregated turn usage for hook contexts (only fields actually reported). */
+export interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/**
+ * Sum the `usage` of every `assistant/message` of a turn. Steps without
+ * reported accounting are skipped; returns undefined when no step reported
+ * any usage (adapters may omit it entirely).
+ */
+export declare function turnUsage(session: Session, turn: number): UsageTotals | undefined;
 export declare function rememberTurnStart(session: Session): void;
 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).
+ */
+export declare function matchFilters(match: Record<string, RegExp> | 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;
+export declare function toolCallContext(session: Session, turn: number, step: number, callId: unknown, name: unknown, args: unknown): HookContext;
+export declare function toolResultContext(session: Session, turn: number, step: number, callId: unknown, message: {
+    content?: readonly {
+        type?: unknown;
+        text?: unknown;
+    }[];
+}, error: {
+    name?: unknown;
+    code?: unknown;
+} | undefined): HookContext;
+export declare function userMessageContext(session: Session, content: readonly {
+    type?: unknown;
+    text?: unknown;
+}[], source: unknown): HookContext;
+export declare function titleContext(session: Session, title: unknown, source: unknown): HookContext;
+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 agentCreatedContext(agent: AgentLike): HookContext;
 export declare function agentDisposedContext(agent: AgentLike): HookContext;

package/lib/events.js

@@ -1,8 +1,13 @@
 /** 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`. */
+const callTools = new Map();
 function sessionKey(session) {
     return String(session.id);
 }
+function callKey(session, callId) {
+    return `${sessionKey(session)}\u0000${String(callId)}`;
+}
 /** Best-effort access to a session's event log (test fakes may omit it). */
 function sessionEvents(session) {
     return Array.isArray(session.events) ? session.events : [];
@@ -76,6 +81,36 @@ export function turnContent(session, turn) {
     }
     return out === undefined ? undefined : out.slice(0, 4000);
 }
+/**
+ * Sum the `usage` of every `assistant/message` of a turn. Steps without
+ * reported accounting are skipped; returns undefined when no step reported
+ * any usage (adapters may omit it entirely).
+ */
+export function turnUsage(session, turn) {
+    let totals;
+    for (const event of sessionEvents(session)) {
+        if (event.type !== 'assistant/message')
+            continue;
+        if (event.data.turn !== turn)
+            continue;
+        const usage = event.data.usage;
+        if (typeof usage?.inputTokens !== 'number')
+            continue;
+        totals ??= { inputTokens: 0, outputTokens: 0 };
+        totals.inputTokens += usage.inputTokens;
+        totals.outputTokens += usage.outputTokens;
+        if (typeof usage.cacheReadTokens === 'number') {
+            totals.cacheReadTokens = (totals.cacheReadTokens ?? 0) + usage.cacheReadTokens;
+        }
+        if (typeof usage.cacheWriteTokens === 'number') {
+            totals.cacheWriteTokens = (totals.cacheWriteTokens ?? 0) + usage.cacheWriteTokens;
+        }
+        if (typeof usage.reasoningTokens === 'number') {
+            totals.reasoningTokens = (totals.reasoningTokens ?? 0) + usage.reasoningTokens;
+        }
+    }
+    return totals;
+}
 export function rememberTurnStart(session) {
     turnStarts.set(sessionKey(session), Date.now());
 }
@@ -99,6 +134,36 @@ export function hookMatches(spec, event, reasonKind) {
         return true;
     return spec.when === reasonKind;
 }
+/**
+ * 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).
+ */
+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;
+    }
+    return true;
+}
+function baseContext(session, event) {
+    return {
+        event,
+        sessionId: sessionKey(session),
+        sessionName: sessionTitle(session),
+        cwd: session.header.cwd,
+        timestamp: new Date().toISOString(),
+    };
+}
 export function turnEndContext(session, turn, reason) {
     const kind = typeof reason === 'string' ? reason : reason.kind;
     let error;
@@ -107,39 +172,108 @@ export function turnEndContext(session, turn, reason) {
         if (typeof failure?.message === 'string')
             error = failure.message;
     }
+    const usage = turnUsage(session, turn);
     return {
-        event: 'turn/end',
-        sessionId: sessionKey(session),
-        sessionName: sessionTitle(session),
-        cwd: session.header.cwd,
+        ...baseContext(session, 'turn/end'),
         turn,
         reason: kind,
         durationMs: takeDuration(session),
         error,
         content: turnContent(session, turn),
-        timestamp: new Date().toISOString(),
+        usageInputTokens: usage?.inputTokens,
+        usageOutputTokens: usage?.outputTokens,
+        usageCacheReadTokens: usage?.cacheReadTokens,
+        usageCacheWriteTokens: usage?.cacheWriteTokens,
+        usageReasoningTokens: usage?.reasoningTokens,
     };
 }
 export function turnStartContext(session, turn) {
+    return { ...baseContext(session, 'turn/start'), turn };
+}
+export function stepEndContext(session, turn, step) {
+    return { ...baseContext(session, 'step/end'), 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));
+    return {
+        ...baseContext(session, 'tool/call'),
+        turn,
+        step,
+        tool: typeof name === 'string' ? name : String(name),
+        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)
+        callTools.delete(key);
+    let toolError;
+    if (error !== undefined) {
+        const name = typeof error.name === 'string' ? error.name : undefined;
+        const code = typeof error.code === 'string' ? error.code : undefined;
+        if (name !== undefined || code !== undefined)
+            toolError = [name, code].filter(Boolean).join(': ');
+    }
+    const content = textOfBlocks(message.content);
+    return {
+        ...baseContext(session, 'tool/result'),
+        turn,
+        step,
+        tool,
+        callId: String(callId),
+        toolError,
+        content: content === undefined ? undefined : content.slice(0, 4000),
+    };
+}
+export function userMessageContext(session, content, source) {
+    const kind = typeof source === 'object' && source !== null && 'kind' in source
+        ? String(source.kind)
+        : undefined;
+    const text = textOfBlocks(content);
+    return {
+        ...baseContext(session, 'user/message'),
+        source: kind,
+        content: text === undefined ? undefined : text.slice(0, 4000),
+    };
+}
+export function titleContext(session, title, source) {
+    const kind = typeof source === 'object' && source !== null && 'kind' in source
+        ? String(source.kind)
+        : undefined;
+    const cleaned = title === undefined ? undefined : oneLineTitle(title);
     return {
-        event: 'turn/start',
+        ...baseContext(session, 'session/title'),
+        sessionName: cleaned === undefined || cleaned === '' ? undefined : cleaned.slice(0, 60),
+        source: kind,
+    };
+}
+export function sessionCreatedContext(session) {
+    return {
+        event: 'session/created',
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
-        turn,
         timestamp: new Date().toISOString(),
     };
 }
-export function approvalContext(session, data) {
+export function sessionDisposedContext(session) {
     return {
-        event: 'approval/asked',
+        event: 'session/disposed',
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function approvalContext(session, data) {
+    return {
+        ...baseContext(session, 'approval/asked'),
         tool: data.toolName,
         callId: data.callId,
         reason: data.reason,
-        timestamp: new Date().toISOString(),
     };
 }
 export function agentCreatedContext(agent) {
@@ -181,8 +315,24 @@ export function classifySessionEvent(session, event) {
             return turnStartContext(session, event.data.turn);
         case 'turn/end':
             return turnEndContext(session, event.data.turn, event.data.reason);
+        case 'step/end':
+            return stepEndContext(session, event.data.turn, event.data.step);
+        case 'tool/call':
+            return toolCallContext(session, event.data.turn, event.data.step, event.data.callId, event.data.name, event.data.arguments);
+        case 'tool/result': {
+            // The call id rides the tool-result block (and the tool source), not
+            // the event envelope — resolve it structurally with fallbacks.
+            const block = event.data.message.content[0];
+            const source = event.data.message.source;
+            const callId = block?.toolCallId ?? source?.callId;
+            return toolResultContext(session, event.data.turn, event.data.step, callId, event.data.message.content[0], event.data.error);
+        }
+        case 'user/message':
+            return userMessageContext(session, event.data.content, event.data.source);
         case 'approval/asked':
             return approvalContext(session, event.data);
+        case 'session/title':
+            return titleContext(session, event.data.title, event.data.source);
         default:
             return undefined;
     }

package/lib/history.d.ts

@@ -0,0 +1,34 @@
+/** One recorded hook execution. No secrets: env vars never enter records. */
+export interface HookRunRecord {
+    /** Epoch milliseconds when the record was written. */
+    ts: number;
+    /** `run` (spawned command) or `notify` (built-in channel). */
+    kind: 'run' | 'notify';
+    event: string;
+    /** Rendered command (`run`) or `notify:<channel>` (`notify`). */
+    command: string;
+    sessionId?: string;
+    sessionName?: string;
+    outcome: 'spawned' | 'spawn-failed' | 'timeout' | 'exit-0' | 'exit-nonzero' | 'sent' | 'send-failed';
+    exitCode?: number;
+    durationMs?: number;
+    /** stderr tail or error message. */
+    error?: string;
+}
+export declare const DEFAULT_HISTORY_PATH: string;
+export declare const DEFAULT_HISTORY_MAX = 500;
+export interface HistorySinkOptions {
+    /** Whether to persist records to disk. Defaults to true. */
+    enabled?: boolean;
+    /** JSONL file path. Defaults to ~/.dsh/dsh-hooks/history.jsonl. */
+    path?: string;
+    /** In-memory ring buffer size. Defaults to 500. */
+    max?: number;
+}
+export interface HistorySink {
+    record(record: Omit<HookRunRecord, 'ts'>): void;
+    /** Most recent records, oldest first. */
+    recent(): readonly HookRunRecord[];
+    dispose(): void;
+}
+export declare function createHistorySink(options?: HistorySinkOptions): HistorySink;