@armadra/agent 0.0.0-stage → 0.2.1

package/dist/config/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 磁盘配置文件形状（设计 §3.5、§7.3、§10.2、§10.3、§12.10）。[B0] 契约文件。
+ *
+ * 补全与偏差：§1.2 把这些类型放在 config/schema.ts（B5），但 Runtime（cli/runtime.ts，B0）
+ * 与 SDK 的 `CreateSessionOptions.config` 都要引用 `AmaConfig`，而 B5 与 B6 并行开工，
+ * 所以形状在这里定死；config/schema.ts 只做校验并可再导出这些类型。
+ * hooks.json 的形状是 `HookConfig`（hooks/types.ts）。
+ * （W3-C0）第三波：`cache` 段（§1.12，只认用户级 / profile）；`ModelConfig` / `ModelOverride`
+ * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
+ */
+import type { WarmingMode } from "../ai/cache/types.js";
+import type { Api, AuthHeader, CacheRetention, Model, ModelThinkingLevel, ProviderCompat } from "../ai/types.js";
+import type { PermissionMode } from "../permissions/types.js";
+export declare const CONFIG_FILE_VERSION: 1;
+/**
+ * 自定义模型条目；缺省 maxTokens 8192、reasoning false、input ["text"]，不猜 contextWindow。
+ * `api` 缺省沿用供应商的协议。
+ */
+export type ModelConfig = Partial<Omit<Model, "id" | "provider">> & {
+    id: string;
+};
+/** 只改元数据的覆盖项（含模型级 `api`）。 */
+export type ModelOverride = Partial<Omit<Model, "id" | "provider">> & {
+    id: string;
+};
+export interface ProviderConfig {
+    name?: string;
+    /** 自定义供应商缺省 openai-completions。 */
+    api?: Api;
+    baseUrl?: string;
+    /** 支持 "$ENV_NAME"、"${ENV_NAME}"、"!command"；"$$" 转义。 */
+    apiKey?: string;
+    envKeys?: string[];
+    authHeader?: AuthHeader;
+    headers?: Record<string, string>;
+    compat?: ProviderCompat;
+    requiresApiKey?: boolean;
+    models?: ModelConfig[];
+    modelOverrides?: ModelOverride[];
+}
+export interface PermissionConfig {
+    mode?: PermissionMode;
+    allow?: string[];
+    deny?: string[];
+    /**
+     * 内置 deny 表（`.git/**` 写、`.ssh/**` 读写）：缺省 true 全部启用；false 全部移除；
+     * 数组 = 要移除的规则原文。放宽项，只认用户级 / profile，项目级忽略并 warning。
+     */
+    builtinDeny?: boolean | string[];
+}
+export interface CompactionConfig {
+    enabled?: boolean;
+    reserveTokens?: number;
+    keepRecentTokens?: number;
+}
+export interface RetryConfig {
+    enabled?: boolean;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+/** 工具预设（设计 §5.6）：模型直接看到的工具集合。 */
+export type ToolsPreset = "default" | "minimal" | "codemode" | "coordinator";
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+export declare const TOOLS_PRESETS_STRICT_FIRST: readonly ToolsPreset[];
+export interface ToolsConfig {
+    /** 缺省 `default`；命令行 `--tools-preset`。 */
+    preset?: ToolsPreset;
+    /**
+     * 在预设上微调（设计 §5.6）：`+name` 加、`-name` 去；不带前缀的名字整组替换预设的内置工具。
+     * 只认用户级 / profile（项目级忽略并 warning）。
+     */
+    default?: string[];
+    maxToolResultChars?: number;
+    bashTimeoutMs?: number;
+    disabled?: string[];
+}
+/** codemode 调用方式（设计 §5.5）：off 不注册；on 全部工具 + codemode；only 只有 codemode。 */
+export type CodemodeMode = "off" | "on" | "only";
+export declare const CODEMODE_MODES: readonly CodemodeMode[];
+export interface CodemodeConfig {
+    /** 命令行 `--codemode`；项目级只接受 "off"。 */
+    mode?: CodemodeMode;
+    /** `codemode` 描述里内联工具声明的总预算（估算 token，缺省 3 000），超出只列名字。 */
+    inlineBudget?: number;
+    /** true：运行时 Node 的权限模型不隔离网络（Node 22 / 24）时直接禁用 codemode。 */
+    requireStrict?: boolean;
+}
+export interface HooksSettings {
+    timeoutMs?: number;
+}
+export interface UiConfig {
+    theme?: "dark" | "light";
+    markdown?: boolean;
+    showThinking?: "full" | "collapsed" | "hidden";
+    /** 第一期只有 regular（§12.10）。 */
+    tuiMode?: "regular";
+    quietStartup?: "normal" | "header" | "silent";
+}
+export interface SkillsConfig {
+    dirs?: string[];
+}
+export declare const CACHE_RETENTIONS: readonly CacheRetention[];
+/**
+ * 缓存（第三波 §1.12）。整段只认用户级 / profile，项目级忽略并 warning（同 `permission.allow`）；
+ * 环境变量 `AMA_CACHE_WARMING` / `AMA_CACHE_RETENTION` 覆盖对应项。
+ */
+export interface CacheConfig {
+    /** off | streaming | idle，缺省 streaming。 */
+    warming?: WarmingMode;
+    /** none | short | long，缺省 short。 */
+    retention?: CacheRetention;
+    /** 保温的最低期望节省（美元），缺省 0.05。 */
+    minSavingsUsd?: number;
+    /** 转录 / 消息区的未命中与上下文余量提示，缺省 true（统计面板不受影响）。 */
+    missNotices?: boolean;
+    /** 子会话（task）也保温，缺省 false。 */
+    warmSubagents?: boolean;
+}
+export declare const DEFAULT_CACHE_CONFIG: Readonly<Required<CacheConfig>>;
+/** config.json（用户级 / 项目级 / profile.config 同形状；项目级只接受受限字段，§10.2）。 */
+export interface AmaConfig {
+    version: typeof CONFIG_FILE_VERSION;
+    /** `provider/model-id`。 */
+    defaultModel?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    providers?: Record<string, ProviderConfig>;
+    permission?: PermissionConfig;
+    compaction?: CompactionConfig;
+    retry?: RetryConfig;
+    tools?: ToolsConfig;
+    codemode?: CodemodeConfig;
+    hooks?: HooksSettings;
+    ui?: UiConfig;
+    skills?: SkillsConfig;
+    cache?: CacheConfig;
+}
+/** auth.json（0600）。 */
+export interface AuthFile {
+    version: typeof CONFIG_FILE_VERSION;
+    providers: Record<string, {
+        apiKey: string;
+        env?: Record<string, string>;
+        baseUrl?: string;
+    }>;
+}
+/** profile.json（宿主用，§10.3；与 Armadra 文档 B §2.4 一致）；路径必须是绝对路径，不含密钥。 */
+export interface ProfileFile {
+    version: typeof CONFIG_FILE_VERSION;
+    host?: string;
+    instructions?: string[];
+    skillDirs?: string[];
+    promptDirs?: string[];
+    hooksFile?: string;
+    authFile?: string;
+    /** false：key 只来自 authFile，不读环境变量（§11.2）。 */
+    authEnv?: boolean;
+    sessionDir?: string;
+    config?: string;
+    trustProject?: boolean;
+}
+export interface TrustEntry {
+    path: string;
+    trusted: boolean;
+    /** ISO 8601。 */
+    at: string;
+}
+/** trust.json（只在用户级目录）。 */
+export interface TrustFile {
+    version: typeof CONFIG_FILE_VERSION;
+    entries: TrustEntry[];
+}

package/dist/config/types.js

@@ -0,0 +1,27 @@
+/**
+ * 磁盘配置文件形状（设计 §3.5、§7.3、§10.2、§10.3、§12.10）。[B0] 契约文件。
+ *
+ * 补全与偏差：§1.2 把这些类型放在 config/schema.ts（B5），但 Runtime（cli/runtime.ts，B0）
+ * 与 SDK 的 `CreateSessionOptions.config` 都要引用 `AmaConfig`，而 B5 与 B6 并行开工，
+ * 所以形状在这里定死；config/schema.ts 只做校验并可再导出这些类型。
+ * hooks.json 的形状是 `HookConfig`（hooks/types.ts）。
+ * （W3-C0）第三波：`cache` 段（§1.12，只认用户级 / profile）；`ModelConfig` / `ModelOverride`
+ * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
+ */
+export const CONFIG_FILE_VERSION = 1;
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+export const TOOLS_PRESETS_STRICT_FIRST = [
+    "coordinator",
+    "minimal",
+    "default",
+    "codemode",
+];
+export const CODEMODE_MODES = ["off", "on", "only"];
+export const CACHE_RETENTIONS = ["none", "short", "long"];
+export const DEFAULT_CACHE_CONFIG = Object.freeze({
+    warming: "streaming",
+    retention: "short",
+    minSavingsUsd: 0.05,
+    missNotices: true,
+    warmSubagents: false,
+});

package/dist/config/write.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 写配置文件（第三波 §2.3，`ama models discover --write` 用）。[W3-B12]
+ *
+ * 2 空格缩进 + 换行结尾；目标已存在时先复制为 `<path>.bak`（`backup` 缺省 true）并沿用原文件
+ * 权限；先写同目录临时文件再 rename，中途失败不会留下半个 config.json。
+ */
+import type { AmaConfig } from "./types.js";
+export declare function writeConfigFile(path: string, config: AmaConfig, options?: {
+    backup?: boolean;
+}): void;

package/dist/config/write.js

@@ -0,0 +1,25 @@
+/**
+ * 写配置文件（第三波 §2.3，`ama models discover --write` 用）。[W3-B12]
+ *
+ * 2 空格缩进 + 换行结尾；目标已存在时先复制为 `<path>.bak`（`backup` 缺省 true）并沿用原文件
+ * 权限；先写同目录临时文件再 rename，中途失败不会留下半个 config.json。
+ */
+import { chmodSync, copyFileSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function writeConfigFile(path, config, options = {}) {
+    mkdirSync(dirname(path), { recursive: true });
+    let mode;
+    try {
+        mode = statSync(path).mode & 0o777;
+    }
+    catch {
+        mode = undefined;
+    }
+    if (mode !== undefined && options.backup !== false)
+        copyFileSync(path, `${path}.bak`);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: mode ?? 0o644 });
+    if (mode !== undefined)
+        chmodSync(tmp, mode);
+    renameSync(tmp, path);
+}

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 共享错误类型（设计 §2「错误」）。[B0] 契约文件。
+ *
+ * 补全说明：设计只给出 `class AmaError extends Error { code; exitCode?; detail? }` 与
+ * `StartupError`，未指定文件位置。各层（ai / agent / tools / config / cli）都要抛它，
+ * 而 ai 是最底层、不得 import 上层，所以放在 src 根，由 B0 所有。
+ * `exitCode` 用数字而不是 `ExitCode` 类型，避免底层模块反向依赖 cli/。
+ */
+/** 已知错误码；实现可以使用其它字符串，但下列码的语义固定。 */
+export type KnownErrorCode = "no_api_key" | "busy" | "aborted" | "invalid_arguments" | "schema_violation" | "model_not_found" | "provider_not_found" | "tool_not_found" | "tool_exists" | "config_invalid" | "profile_invalid" | "session_not_found" | "session_corrupt" | "host_load_failed" | "host_version_mismatch" | "hook_failed" | "not_implemented";
+export type ErrorCode = KnownErrorCode | (string & {});
+export interface AmaErrorOptions {
+    exitCode?: number;
+    detail?: unknown;
+    cause?: unknown;
+}
+export declare class AmaError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: number | undefined;
+    readonly detail: unknown;
+    constructor(code: ErrorCode, message: string, options?: AmaErrorOptions);
+}
+/** 启动序列（§11.1）中的错误；`exitCode` 必填，取值见 cli/exit-codes.ts。 */
+export declare class StartupError extends AmaError {
+    readonly exitCode: number;
+    constructor(code: ErrorCode, message: string, exitCode: number, options?: AmaErrorOptions);
+}
+export declare function isAmaError(value: unknown): value is AmaError;

package/dist/errors.js

@@ -0,0 +1,30 @@
+/**
+ * 共享错误类型（设计 §2「错误」）。[B0] 契约文件。
+ *
+ * 补全说明：设计只给出 `class AmaError extends Error { code; exitCode?; detail? }` 与
+ * `StartupError`，未指定文件位置。各层（ai / agent / tools / config / cli）都要抛它，
+ * 而 ai 是最底层、不得 import 上层，所以放在 src 根，由 B0 所有。
+ * `exitCode` 用数字而不是 `ExitCode` 类型，避免底层模块反向依赖 cli/。
+ */
+export class AmaError extends Error {
+    code;
+    exitCode;
+    detail;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "AmaError";
+        this.code = code;
+        this.exitCode = options.exitCode;
+        this.detail = options.detail;
+    }
+}
+/** 启动序列（§11.1）中的错误；`exitCode` 必填，取值见 cli/exit-codes.ts。 */
+export class StartupError extends AmaError {
+    constructor(code, message, exitCode, options = {}) {
+        super(code, message, { ...options, exitCode });
+        this.name = "StartupError";
+    }
+}
+export function isAmaError(value) {
+    return value instanceof AmaError;
+}

package/dist/hooks/config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 命令式 Hook 的发现与合并（设计 §6.1「配置位置与合并」「信任边界」）。[B5]
+ *
+ * - 三层：`<configDir>/hooks.json`（user）→ profile `hooksFile`（profile，视同用户级）→
+ *   `<cwd>/.ama/hooks.json`（project，需信任）；事件数组按此顺序**拼接**，不覆盖。
+ * - 未信任时项目级跳过（`skippedProject` 交给 doctor / 状态栏提示）。
+ * - 语法 / 字段错误抛 StartupError（退出码 3）；非法 matcher 同样按字段错误处理。
+ */
+import type { HookConfig, HookEvent, HookSource } from "./types.js";
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 60000;
+/** 展平后的一条 Hook 命令。 */
+export interface LoadedHook {
+    event: HookEvent;
+    matcher?: string;
+    command: string;
+    timeoutMs: number;
+    source: HookSource;
+    /** 来源文件（SDK 为 "sdk"）。 */
+    file: string;
+    /** 全局配置顺序（additionalContext 拼接顺序）。 */
+    order: number;
+}
+export interface HookLayer {
+    source: HookSource;
+    file: string;
+    config: HookConfig;
+}
+export declare function clampTimeout(value: number | undefined, fallback: number): number;
+/** 把若干层按顺序展平；`defaultTimeoutMs` 来自 config.hooks.timeoutMs。 */
+export declare function flattenHookLayers(layers: readonly HookLayer[], defaultTimeoutMs?: number): LoadedHook[];
+export interface LoadHookConfigsInput {
+    configDir: string;
+    cwd: string;
+    /** profile.hooksFile（必须存在）。 */
+    profileHooksFile?: string | undefined;
+    trusted: boolean;
+    /** config.hooks.timeoutMs。 */
+    defaultTimeoutMs?: number | undefined;
+}
+export interface LoadHookConfigsResult {
+    hooks: LoadedHook[];
+    layers: HookLayer[];
+    /** 项目级存在但因未信任被跳过的文件。 */
+    skippedProject?: string;
+    warnings: string[];
+}
+export declare function loadHookConfigs(input: LoadHookConfigsInput): LoadHookConfigsResult;
+/** SDK 传入的 HookConfig（视同用户级，不经过信任）。 */
+export declare function hooksFromConfig(config: HookConfig, defaultTimeoutMs?: number): LoadedHook[];

package/dist/hooks/config.js

@@ -0,0 +1,102 @@
+/**
+ * 命令式 Hook 的发现与合并（设计 §6.1「配置位置与合并」「信任边界」）。[B5]
+ *
+ * - 三层：`<configDir>/hooks.json`（user）→ profile `hooksFile`（profile，视同用户级）→
+ *   `<cwd>/.ama/hooks.json`（project，需信任）；事件数组按此顺序**拼接**，不覆盖。
+ * - 未信任时项目级跳过（`skippedProject` 交给 doctor / 状态栏提示）。
+ * - 语法 / 字段错误抛 StartupError（退出码 3）；非法 matcher 同样按字段错误处理。
+ */
+import { existsSync } from "node:fs";
+import { StartupError } from "../errors.js";
+import { loadConfigFile } from "../config/load.js";
+import { HOOKS_FILE, projectFile, userFile } from "../config/paths.js";
+import { HOOK_TIMEOUT_MAX_MS } from "../config/schema.js";
+import { checkMatcher } from "./matcher.js";
+import { HOOK_EVENTS } from "./types.js";
+export const DEFAULT_HOOK_TIMEOUT_MS = 60_000;
+export function clampTimeout(value, fallback) {
+    const v = value ?? fallback;
+    return Math.min(Math.max(1, Math.floor(v)), HOOK_TIMEOUT_MAX_MS);
+}
+/** 把若干层按顺序展平；`defaultTimeoutMs` 来自 config.hooks.timeoutMs。 */
+export function flattenHookLayers(layers, defaultTimeoutMs = DEFAULT_HOOK_TIMEOUT_MS) {
+    const hooks = [];
+    let order = 0;
+    for (const layer of layers) {
+        for (const event of HOOK_EVENTS) {
+            for (const group of layer.config.hooks[event] ?? []) {
+                for (const command of group.hooks) {
+                    const hook = {
+                        event,
+                        command: command.command,
+                        timeoutMs: clampTimeout(command.timeoutMs, defaultTimeoutMs),
+                        source: layer.source,
+                        file: layer.file,
+                        order: order++,
+                    };
+                    if (group.matcher !== undefined)
+                        hook.matcher = group.matcher;
+                    hooks.push(hook);
+                }
+            }
+        }
+    }
+    return hooks;
+}
+function validateMatchers(file, config) {
+    const problems = [];
+    for (const event of HOOK_EVENTS) {
+        (config.hooks[event] ?? []).forEach((group, index) => {
+            const error = checkMatcher(group.matcher);
+            if (error !== undefined)
+                problems.push(`hooks.${event}[${index}].matcher: ${error}`);
+        });
+    }
+    if (problems.length > 0) {
+        throw new StartupError("config_invalid", `配置文件无效：\n  ${problems.map((p) => `${file}: ${p}`).join("\n  ")}`, 3);
+    }
+}
+function readLayer(source, file, required) {
+    const loaded = loadConfigFile("hooks", file, { required });
+    if (loaded === undefined)
+        return undefined;
+    validateMatchers(file, loaded.value);
+    return { source, file, config: loaded.value };
+}
+export function loadHookConfigs(input) {
+    const layers = [];
+    const warnings = [];
+    const user = readLayer("user", userFile(input, HOOKS_FILE), false);
+    if (user !== undefined)
+        layers.push(user);
+    if (input.profileHooksFile !== undefined) {
+        const profile = readLayer("profile", input.profileHooksFile, true);
+        if (profile !== undefined)
+            layers.push(profile);
+    }
+    const projectPath = projectFile(input.cwd, HOOKS_FILE);
+    let skippedProject;
+    if (input.trusted) {
+        const project = readLayer("project", projectPath, false);
+        if (project !== undefined)
+            layers.push(project);
+    }
+    else if (existsSync(projectPath)) {
+        // 未信任时不解析内容（不让不可信文件的语法错误阻断启动），只看存在性。
+        skippedProject = projectPath;
+        warnings.push(`${projectPath}: 项目未信任，跳过项目级 Hook（用 --trust 或在交互模式确认信任）`);
+    }
+    const result = {
+        hooks: flattenHookLayers(layers, input.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS),
+        layers,
+        warnings,
+    };
+    if (skippedProject !== undefined)
+        result.skippedProject = skippedProject;
+    return result;
+}
+/** SDK 传入的 HookConfig（视同用户级，不经过信任）。 */
+export function hooksFromConfig(config, defaultTimeoutMs = DEFAULT_HOOK_TIMEOUT_MS) {
+    validateMatchers("sdk", config);
+    return flattenHookLayers([{ source: "sdk", file: "sdk", config }], defaultTimeoutMs);
+}

package/dist/hooks/dispatcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HookDispatcher：实现 HookDispatcherApi（设计 §6.1、§6.3）。[B5]
+ *
+ * AgentSession（B2）在各钩子点调用 `run(event, payload, signal?, context?)`；公共字段（sessionId、
+ * cwd、model、permissionMode、depth、host…）由构造时给的 `context()` 每次现取，再由第 4 参数
+ * 按次覆盖（子 Agent 的 depth / sessionId / sessionFile）。每条 Hook 执行后回调
+ * `onExecuted`（bootstrap 把它接到宿主事件 `hook_executed`）。matcher 只在 Pre/PostToolUse 生效。
+ */
+import type { LoadedHook } from "./config.js";
+import { type RunHookOptions } from "./runner.js";
+import type { HookCommonContext, HookContextOverrides, HookDispatcherApi, HookEvent, HookEventPayload, HookInput, HookNotification, HookOutcome, HookRunResult, HookSource } from "./types.js";
+export type { HookCommonContext } from "./types.js";
+export type HookExecutor = (hooks: readonly LoadedHook[], input: HookInput, options: RunHookOptions) => Promise<HookRunResult[]>;
+export interface HookDispatcherOptions {
+    hooks: readonly LoadedHook[];
+    context: () => HookCommonContext;
+    /** 每条 Hook 结束后（含超时）回调；异常被吞掉。 */
+    onExecuted?: (result: HookRunResult) => void;
+    /** 合并后的 warning（Hook 失败、超时、冲突的 updatedInput）。 */
+    onWarning?: (message: string) => void;
+    /** 测试注入；缺省为子进程 runner。 */
+    executor?: HookExecutor;
+    /** 额外环境变量。 */
+    env?: Readonly<Record<string, string | undefined>>;
+}
+export declare class HookDispatcher implements HookDispatcherApi {
+    private readonly byEvent;
+    private readonly options;
+    constructor(options: HookDispatcherOptions);
+    private matching;
+    has(event: HookEvent, toolName?: string): boolean;
+    run(event: HookEvent, payload: HookEventPayload, signal?: AbortSignal, context?: HookContextOverrides): Promise<HookOutcome>;
+    /** Notification 投递：纯通知，不等待结果、不抛错。 */
+    notify(notification: HookNotification): void;
+    list(): readonly {
+        event: HookEvent;
+        matcher?: string;
+        command: string;
+        source: HookSource;
+    }[];
+}

package/dist/hooks/dispatcher.js

@@ -0,0 +1,104 @@
+/**
+ * HookDispatcher：实现 HookDispatcherApi（设计 §6.1、§6.3）。[B5]
+ *
+ * AgentSession（B2）在各钩子点调用 `run(event, payload, signal?, context?)`；公共字段（sessionId、
+ * cwd、model、permissionMode、depth、host…）由构造时给的 `context()` 每次现取，再由第 4 参数
+ * 按次覆盖（子 Agent 的 depth / sessionId / sessionFile）。每条 Hook 执行后回调
+ * `onExecuted`（bootstrap 把它接到宿主事件 `hook_executed`）。matcher 只在 Pre/PostToolUse 生效。
+ */
+import { compileMatcher } from "./matcher.js";
+import { emptyOutcome, mergeResults } from "./protocol.js";
+import { runHooks } from "./runner.js";
+/** 用 `overrides` 里值不为 undefined 的键覆盖 `base`。 */
+function withOverrides(base, overrides) {
+    if (overrides === undefined)
+        return base;
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return merged;
+}
+const TOOL_EVENTS = new Set(["PreToolUse", "PostToolUse"]);
+export class HookDispatcher {
+    byEvent = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+        const sorted = [...options.hooks].sort((a, b) => a.order - b.order);
+        for (const hook of sorted) {
+            const list = this.byEvent.get(hook.event) ?? [];
+            list.push({
+                hook,
+                matcher: compileMatcher(hook.matcher),
+                nameMatcher: compileMatcher(hook.matcher, true),
+            });
+            this.byEvent.set(hook.event, list);
+        }
+    }
+    matching(event, toolName, toolInput) {
+        const list = this.byEvent.get(event) ?? [];
+        if (!TOOL_EVENTS.has(event))
+            return list.map((c) => c.hook);
+        if (toolName === undefined)
+            return list.map((c) => c.hook);
+        return list.filter((c) => c.matcher(toolName, toolInput)).map((c) => c.hook);
+    }
+    has(event, toolName) {
+        const list = this.byEvent.get(event) ?? [];
+        if (list.length === 0)
+            return false;
+        if (!TOOL_EVENTS.has(event) || toolName === undefined)
+            return true;
+        // 不知道输入时只按工具名判断（括号参数视为可能匹配）。
+        return list.some((c) => c.nameMatcher(toolName, undefined));
+    }
+    async run(event, payload, signal, context) {
+        const hooks = this.matching(event, payload.toolName, payload.toolInput);
+        if (hooks.length === 0)
+            return emptyOutcome();
+        const common = withOverrides(this.options.context(), context);
+        const input = { ...common, ...payload, hookEventName: event };
+        const executor = this.options.executor ?? runHooks;
+        const runOptions = { cwd: common.cwd, signal };
+        if (this.options.env !== undefined)
+            runOptions.env = this.options.env;
+        const results = await executor(hooks, input, runOptions);
+        for (const result of results) {
+            try {
+                this.options.onExecuted?.(result);
+            }
+            catch {
+                // 观察者异常不影响 Hook 结论
+            }
+        }
+        const outcome = mergeResults(results);
+        for (const warning of outcome.warnings)
+            this.options.onWarning?.(warning);
+        return outcome;
+    }
+    /** Notification 投递：纯通知，不等待结果、不抛错。 */
+    notify(notification) {
+        if (!this.has("Notification"))
+            return;
+        void this.run("Notification", { notification }).catch(() => undefined);
+    }
+    list() {
+        const all = [];
+        for (const list of this.byEvent.values())
+            all.push(...list.map((c) => c.hook));
+        return all
+            .sort((a, b) => a.order - b.order)
+            .map((hook) => {
+            const item = {
+                event: hook.event,
+                command: hook.command,
+                source: hook.source,
+            };
+            if (hook.matcher !== undefined)
+                item.matcher = hook.matcher;
+            return item;
+        });
+    }
+}

package/dist/hooks/matcher.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Hook matcher（设计 §6.1「matcher」）。[B5]
+ *
+ * 语法：缺省 / 空串 / `*` 匹配全部；`bash` 精确；`write|edit` 多选；`canvas_*` glob；
+ * `bash(git push*)` 先匹配工具名，再对参数文本做 glob；`/regex/flags` 对工具名做正则。
+ * 括号内的文本：bash → `input.command`；文件类工具 → `input.path`（或 `file_path`）；
+ * 其它工具 → 输入 JSON 文本。`|` 只在括号外分隔候选。只在 Pre/PostToolUse 生效。
+ */
+export type ToolMatcher = (toolName: string, input: unknown) => boolean;
+/** glob → 正则：`*` 任意字符串（含 `/`），`?` 单个字符，其余字面量。 */
+export declare function globToRegExp(glob: string): RegExp;
+/** 括号外的 `|` 切分。 */
+export declare function splitAlternatives(matcher: string): string[];
+/** 括号内 glob 匹配的参数文本。 */
+export declare function argumentText(toolName: string, input: unknown): string;
+/**
+ * 编译 matcher；语法错误（非法正则）抛 Error。
+ * `nameOnly`：忽略括号参数，只看工具名（输入未知时判断「可能匹配」）。
+ */
+export declare function compileMatcher(matcher: string | undefined, nameOnly?: boolean): ToolMatcher;
+/** 校验 matcher 语法；返回错误信息或 undefined。 */
+export declare function checkMatcher(matcher: string | undefined): string | undefined;