@dommaker/harness 1.7.0 → 1.8.1

package/src/hooks/__tests__/pipeline.test.ts

@@ -4,16 +4,26 @@
  * block/warn 行为是 studio safeCallHook 语义在管线侧的无损承载面：
  * - 'block'：hook 失败 → passed=false、blockedBy 记名、停止执行后续 hook
  * - 'warn'：hook 失败 → 记录警告、继续执行后续 hook、passed 不受影响
- * - 'ignore'/未声明：静默跳过（历史行为保留）
+ *
+ * #159 起 `enabled` / `errorStrategy` 的唯一声明点是 HookConfig：
+ * HookDefinition 不再携带这两个字段，有效值在注册环节由配置表填充。
  */
 
 import { HookPipeline } from '../pipeline';
 import { HookRegistry } from '../registry';
-import type { HookDefinition } from '../types';
+import type { HookConfig, HookDefinition } from '../types';
+
+function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
+  return { name, enabled: true, errorStrategy: 'warn', ...overrides };
+}
 
-function makeRegistry(hooks: HookDefinition[]): { registry: HookRegistry; pipeline: HookPipeline } {
+function makeRegistry(
+  entries: Array<{ hook: HookDefinition; config?: Partial<HookConfig> }>
+): { registry: HookRegistry; pipeline: HookPipeline } {
   const registry = new HookRegistry();
-  registry.registerAll(hooks);
+  for (const { hook, config } of entries) {
+    registry.register(hook, makeConfig(hook.name, config));
+  }
   return { registry, pipeline: new HookPipeline(registry) };
 }
 
@@ -21,8 +31,8 @@ describe('HookPipeline errorStrategy 语义', () => {
   it('block：失败阻断管线（passed=false、blockedBy 记名、停止后续 hook）', async () => {
     const second = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'first', phase: 'before', errorStrategy: 'block', execute: async () => ({ passed: false, error: 'boom' }) },
-      { name: 'second', phase: 'before', execute: second },
+      { hook: { name: 'first', phase: 'before', execute: async () => ({ passed: false, error: 'boom' }) }, config: { errorStrategy: 'block' } },
+      { hook: { name: 'second', phase: 'before', execute: second } },
     ]);
 
     const result = await pipeline.run('before', {});
@@ -35,8 +45,8 @@ describe('HookPipeline errorStrategy 语义', () => {
   it('warn：失败记录警告并继续（passed 不受影响、后续 hook 照常执行）', async () => {
     const second = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'first', phase: 'before', errorStrategy: 'warn', execute: async () => ({ passed: false, error: 'soft' }) },
-      { name: 'second', phase: 'before', execute: second },
+      { hook: { name: 'first', phase: 'before', execute: async () => ({ passed: false, error: 'soft' }) }, config: { errorStrategy: 'warn' } },
+      { hook: { name: 'second', phase: 'before', execute: second } },
     ]);
 
     const result = await pipeline.run('before', {});
@@ -50,8 +60,8 @@ describe('HookPipeline errorStrategy 语义', () => {
   it('block 失败停在当前 phase，不改变其它 phase 的 hook', async () => {
     const afterHook = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'blocker', phase: 'before', errorStrategy: 'block', execute: async () => ({ passed: false }) },
-      { name: 'afterHook', phase: 'after', execute: afterHook },
+      { hook: { name: 'blocker', phase: 'before', execute: async () => ({ passed: false }) }, config: { errorStrategy: 'block' } },
+      { hook: { name: 'afterHook', phase: 'after', execute: afterHook } },
     ]);
 
     const before = await pipeline.run('before', {});
@@ -62,18 +72,124 @@ describe('HookPipeline errorStrategy 语义', () => {
     expect(afterHook).toHaveBeenCalled();
   });
 
-  it('未声明 errorStrategy：静默跳过（历史行为保留）', async () => {
-    const second = jest.fn().mockResolvedValue({ passed: true });
+  it('配置 enabled:false 的 hook 不进入管线执行（配置表是唯一声明点）', async () => {
+    const disabledHook = jest.fn().mockResolvedValue({ passed: true });
+    const enabledHook = jest.fn().mockResolvedValue({ passed: true });
     const { pipeline } = makeRegistry([
-      { name: 'first', phase: 'before', execute: async () => ({ passed: false }) },
-      { name: 'second', phase: 'before', execute: second },
+      { hook: { name: 'disabled', phase: 'before', execute: disabledHook }, config: { enabled: false } },
+      { hook: { name: 'enabled', phase: 'before', execute: enabledHook } },
     ]);
 
     const result = await pipeline.run('before', {});
 
     expect(result.passed).toBe(true);
-    expect(result.blockedBy).toEqual([]);
-    expect(result.warnings).toEqual([]);
-    expect(second).toHaveBeenCalled();
+    expect(disabledHook).not.toHaveBeenCalled();
+    expect(enabledHook).toHaveBeenCalled();
+    expect(result.records.map(r => r.hookName)).toEqual(['enabled']);
+  });
+});
+
+describe('HookPipeline.runOne 按名执行单个 hook（#167）', () => {
+  it('按名执行并返回观测记录，不连带其它 hook', async () => {
+    const other = jest.fn().mockResolvedValue({ passed: true });
+    const target = jest.fn().mockResolvedValue({ passed: true });
+    const { pipeline } = makeRegistry([
+      { hook: { name: 'target', phase: 'before', execute: target } },
+      { hook: { name: 'other', phase: 'before', execute: other } },
+    ]);
+
+    const record = await pipeline.runOne('target', {});
+
+    expect(record.hookName).toBe('target');
+    expect(record.phase).toBe('before');
+    expect(record.passed).toBe(true);
+    expect(record.skipped).toBeUndefined();
+    expect(typeof record.durationMs).toBe('number');
+    expect(target).toHaveBeenCalledTimes(1);
+    expect(other).not.toHaveBeenCalled();
+  });
+
+  it('enabled:false → 实现体零调用，返回 skipped:true / passed:true 记录', async () => {
+    const disabled = jest.fn().mockResolvedValue({ passed: true });
+    const { pipeline } = makeRegistry([
+      { hook: { name: 'disabled', phase: 'before', execute: disabled }, config: { enabled: false } },
+    ]);
+
+    const record = await pipeline.runOne('disabled', {});
+
+    expect(disabled).not.toHaveBeenCalled();
+    expect(record.skipped).toBe(true);
+    expect(record.passed).toBe(true);
+    expect(record.hookName).toBe('disabled');
+  });
+
+  it('block + 实现体抛错 → 抛错，message 含 hook 名与原文', async () => {
+    const { pipeline } = makeRegistry([
+      {
+        hook: { name: 'guard', phase: 'before', execute: async () => { throw new Error('iron-law violated'); } },
+        config: { errorStrategy: 'block' },
+      },
+    ]);
+
+    await expect(pipeline.runOne('guard', {})).rejects.toThrow('iron-law violated');
+    await expect(pipeline.runOne('guard', {})).rejects.toThrow('[harness] hook "guard" blocked:');
+  });
+
+  it('block + 实现体返回 passed:false → 抛错，message 含 result.error 原文', async () => {
+    const { pipeline } = makeRegistry([
+      { hook: { name: 'guard', phase: 'before', execute: async () => ({ passed: false, error: 'boom' }) }, config: { errorStrategy: 'block' } },
+    ]);
+
+    await expect(pipeline.runOne('guard', {})).rejects.toThrow('[harness] hook "guard" blocked: boom');
+  });
+
+  it('warn + 失败 → resolve，返回 passed:false 带 error 的记录', async () => {
+    const { pipeline } = makeRegistry([
+      {
+        hook: { name: 'soft', phase: 'before', execute: async () => { throw new Error('soft-fail'); } },
+        config: { errorStrategy: 'warn' },
+      },
+    ]);
+
+    const record = await pipeline.runOne('soft', {});
+
+    expect(record.passed).toBe(false);
+    expect(record.error).toBe('soft-fail');
+    expect(record.skipped).toBeUndefined();
+  });
+
+  it('未知 hook 名 → 抛错（与注册表闭环口径一致，不静默跳过）', async () => {
+    const { pipeline } = makeRegistry([
+      { hook: { name: 'known', phase: 'before', execute: async () => ({ passed: true }) } },
+    ]);
+
+    await expect(pipeline.runOne('no_such_hook', {})).rejects.toThrow('no_such_hook');
+    await expect(pipeline.runOne('no_such_hook', {})).rejects.toThrow('未注册');
+  });
+
+  it('sampleRate < 1 时采样语义与 run 路径一致（未抽中 → 零调用 + sampled 记录）', async () => {
+    const execute = jest.fn().mockResolvedValue({ passed: true });
+    const { pipeline } = makeRegistry([
+      { hook: { name: 'sampled', phase: 'before', sampleRate: 0.5, execute } },
+    ]);
+
+    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0.9);
+    try {
+      const record = await pipeline.runOne('sampled', {});
+      expect(execute).not.toHaveBeenCalled();
+      expect(record.sampled).toBe(true);
+      expect(record.passed).toBe(true);
+    } finally {
+      randomSpy.mockRestore();
+    }
+
+    const hitSpy = jest.spyOn(Math, 'random').mockReturnValue(0.1);
+    try {
+      const record = await pipeline.runOne('sampled', {});
+      expect(execute).toHaveBeenCalledTimes(1);
+      expect(record.sampled).toBeUndefined();
+    } finally {
+      hitSpy.mockRestore();
+    }
   });
 });

package/src/hooks/__tests__/registry.test.ts

@@ -2,6 +2,10 @@
  * Hook 注册表闭环双向校验测试（H5，复制 checker 闭环模式）
  *
  * 两个失败方向 + 重复声明/注册都必须抛错；闭环通过时不抛错。
+ *
+ * #159 起注册即配对：`register(hook, config)` 以 HookConfig 填充有效
+ * `enabled` / `errorStrategy`——配置表是这两个语义的唯一声明点，
+ * HookDefinition 类型上不再存在同名字段（矛盾在构造上不可能出现）。
  */
 
 import { assertHookRegistryClosed, HookRegistry } from '../registry';
@@ -15,8 +19,8 @@ function makeHook(name: string): HookDefinition {
   };
 }
 
-function makeConfig(name: string): HookConfig {
-  return { name, enabled: true, errorStrategy: 'block' };
+function makeConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
+  return { name, enabled: true, errorStrategy: 'block', ...overrides };
 }
 
 describe('assertHookRegistryClosed', () => {
@@ -60,8 +64,52 @@ describe('assertHookRegistryClosed', () => {
 
   it('与 HookRegistry.listAll 组合可用（consumer 注册点用法）', () => {
     const registry = new HookRegistry();
-    registry.registerAll([makeHook('beforeAgentExecute')]);
+    registry.registerAll([makeHook('beforeAgentExecute')], [makeConfig('beforeAgentExecute')]);
     expect(() => assertHookRegistryClosed([makeConfig('beforeAgentExecute')], registry.listAll()))
       .not.toThrow();
   });
 });
+
+describe('HookRegistry 注册即配对（#159 配置表唯一化）', () => {
+  it('register 以 HookConfig 填充有效 enabled / errorStrategy', () => {
+    const registry = new HookRegistry();
+    registry.register(makeHook('a'), makeConfig('a', { enabled: false, errorStrategy: 'block' }));
+
+    const effective = registry.get('a');
+    expect(effective?.enabled).toBe(false);
+    expect(effective?.errorStrategy).toBe('block');
+    // 配置 enabled:false → 不进 enabled 列表
+    expect(registry.getEnabled('before')).toEqual([]);
+  });
+
+  it('register 定义与配置名称不一致 → 抛错', () => {
+    const registry = new HookRegistry();
+    expect(() => registry.register(makeHook('a'), makeConfig('b'))).toThrow(/名称不一致/);
+  });
+
+  it('registerAll 有实现缺配置声明 → 抛错', () => {
+    const registry = new HookRegistry();
+    expect(() =>
+      registry.registerAll([makeHook('a'), makeHook('orphan')], [makeConfig('a')])
+    ).toThrow(/hook "orphan" 没有对应的 HookConfig 声明/);
+  });
+
+  it('HookDefinition 类型上不再存在 enabled / errorStrategy（编译期钉）', () => {
+    const withStrategy: HookDefinition = {
+      name: 'x',
+      phase: 'before',
+      // @ts-expect-error HookDefinition 不再存在 errorStrategy 字段（#159）
+      errorStrategy: 'block',
+      execute: async () => ({ passed: true }),
+    };
+    const withEnabled: HookDefinition = {
+      name: 'y',
+      phase: 'before',
+      // @ts-expect-error HookDefinition 不再存在 enabled 字段（#159）
+      enabled: false,
+      execute: async () => ({ passed: true }),
+    };
+    expect(withStrategy.name).toBe('x');
+    expect(withEnabled.name).toBe('y');
+  });
+});

package/src/hooks/bootstrap.ts

@@ -11,17 +11,18 @@
  * // harness.checker, harness.config, harness.hooks, harness.sessions
  * ```
  *
- * checker 的 trace 记录器在此接线（harness#88：core 不上行依赖 monitoring）。
+ * checker 的 trace 记录器在此接线（harness#88：core 不上行依赖 monitoring），
+ * 且锚在本函数收到的 projectPath 上（#139：落点跟根走，不落调用方 cwd）。
  */
 
 import { ConstraintChecker } from '../core/constraints/checker';
 import { SessionManager } from '../context/session-manager';
 import { ProjectConfigLoader } from '../core/project-config-loader';
-import { getTraceCollector } from '../monitoring/traces';
+import { TraceCollector } from '../monitoring/traces';
 import { HookRegistry } from './registry';
 import { HookPipeline } from './pipeline';
 import type { MergedConstraintsConfig } from '../types/project-config';
-import type { HookDefinition } from './types';
+import type { HookConfig, HookDefinition } from './types';
 
 /**
  * 异步加载项目配置（S9：异步 I/O）
@@ -30,8 +31,8 @@ async function loadConfigAsync(projectPath: string): Promise<{
   config: ReturnType<ProjectConfigLoader['getConfig']>;
   mergedConstraints: MergedConstraintsConfig;
 }> {
-  // config.yml 解析经 loadRawProjectConfig 进程级 memoize（工单 16），
-  // 此处不再重复读取文件
+  // config.yml 的读取只有 loadRawProjectConfig 这一条路（ADR-0023 决策 2 撤销进程级
+  // 缓存后，每次调用读当下内容），此处不重复读文件
   const loader = new ProjectConfigLoader(projectPath);
   loader.load();
 
@@ -59,15 +60,36 @@ export interface HarnessBootstrap {
   mergedConstraints: MergedConstraintsConfig;
 }
 
+/**
+ * 注册初始 hook（定义必须配对配置声明表——#159 起 HookConfig 是
+ * enabled / errorStrategy 的唯一声明点，缺表即抛错）
+ */
+function registerInitialHooks(
+  hooks: HookRegistry,
+  hookDefinitions: HookDefinition[] | undefined,
+  hookConfigs: HookConfig[] | undefined
+): void {
+  if (!hookDefinitions || hookDefinitions.length === 0) return;
+  if (!hookConfigs) {
+    throw new Error(
+      '[harness] bootstrap 失败：注册 hook 定义必须同时提供 HookConfig 声明表' +
+      '（enabled / errorStrategy 的唯一声明点）。'
+    );
+  }
+  hooks.registerAll(hookDefinitions, hookConfigs);
+}
+
 /**
  * 初始化 harness 运行环境（异步，不阻塞事件循环）
  *
  * @param projectPath 项目根路径
  * @param hookDefinitions 可选，初始化时注册的 hook
+ * @param hookConfigs 可选，与 hookDefinitions 配对的配置声明表（注册定义时必填）
  */
 export async function bootstrapHarness(
   projectPath?: string,
-  hookDefinitions?: HookDefinition[]
+  hookDefinitions?: HookDefinition[],
+  hookConfigs?: HookConfig[]
 ): Promise<HarnessBootstrap> {
   const resolvedPath = projectPath || process.cwd();
 
@@ -75,16 +97,15 @@ export async function bootstrapHarness(
   const { mergedConstraints } = await loadConfigAsync(resolvedPath);
 
   // 2. 初始化核心组件
-  const checker = new ConstraintChecker(getTraceCollector());
+  // trace 记录器锚根构造（#139）：本函数本就收 projectPath，落点必须跟着根走
+  const checker = new ConstraintChecker(new TraceCollector({ projectPath: resolvedPath }));
 
   const sessions = new SessionManager(resolvedPath);
   const hooks = new HookRegistry();
   const pipeline = new HookPipeline(hooks);
 
   // 3. 注册初始 hook
-  if (hookDefinitions) {
-    hooks.registerAll(hookDefinitions);
-  }
+  registerInitialHooks(hooks, hookDefinitions, hookConfigs);
 
   return {
     checker,
@@ -103,7 +124,8 @@ export async function bootstrapHarness(
  */
 export function bootstrapHarnessSync(
   projectPath?: string,
-  hookDefinitions?: HookDefinition[]
+  hookDefinitions?: HookDefinition[],
+  hookConfigs?: HookConfig[]
 ): HarnessBootstrap {
   const resolvedPath = projectPath || process.cwd();
 
@@ -111,15 +133,13 @@ export function bootstrapHarnessSync(
   loader.load();
   const mergedConstraints = loader.mergeConstraints();
 
-  const checker = new ConstraintChecker(getTraceCollector());
+  const checker = new ConstraintChecker(new TraceCollector({ projectPath: resolvedPath }));
 
   const sessions = new SessionManager(resolvedPath);
   const hooks = new HookRegistry();
   const pipeline = new HookPipeline(hooks);
 
-  if (hookDefinitions) {
-    hooks.registerAll(hookDefinitions);
-  }
+  registerInitialHooks(hooks, hookDefinitions, hookConfigs);
 
   return {
     checker,

package/src/hooks/config.ts

@@ -2,7 +2,7 @@
  * Hook 配置归一（G7）
  *
  * studio 侧 per-hook 运行时配置（`blocking: boolean`）与 harness 侧
- * `HookDefinition.errorStrategy` 双轨归一：以 errorStrategy 为唯一真相，
+ * `HookConfig.errorStrategy` 双轨归一：以 errorStrategy 为唯一真相，
  * `blocking` → errorStrategy 为无损映射。
  *
  * 映射语义（确认于 H5）：
@@ -12,6 +12,10 @@
  *   （管线结果 warnings 记名，passed 不受影响）——对应 studio safeCallHook
  *   console.warn 继续
  *
+ * #159 起 `HookConfig` 是 `enabled` / `errorStrategy` 的唯一声明点：
+ * HookDefinition 不再携带这两个字段，注册环节以配置表填充有效值，
+ * 有效策略集合收敛为 'block' | 'warn'（原 'ignore' 退出有效面）。
+ *
  * studio 侧随动（studio #150 A4）：hooks/config.ts 删 DEFAULTS/safeCallHook，
  * blocking→errorStrategy 无损映射进 toHookDef；HARNESS_HOOK_DISABLE 保留 studio。
  */
@@ -24,6 +28,6 @@ import type { HookErrorStrategy } from './types';
  * @param blocking studio 侧「失败是否阻断」语义
  * @returns 'block'（阻断）| 'warn'（警告继续）
  */
-export function toErrorStrategy(blocking: boolean): Extract<HookErrorStrategy, 'block' | 'warn'> {
+export function toErrorStrategy(blocking: boolean): HookErrorStrategy {
   return blocking ? 'block' : 'warn';
 }

package/src/hooks/index.ts

@@ -5,7 +5,16 @@
  * 无业务逻辑，consumer 自行定义 hook 名称和语义。
  */
 
-export * from './types';
+export type {
+  HookPhase,
+  HookErrorStrategy,
+  HookConfig,
+  HookDefinition,
+  EffectiveHook,
+  HookResult,
+  HookExecutionRecord,
+  PipelineResult,
+} from './types';
 export { HookRegistry, assertHookRegistryClosed } from './registry';
 export { HookPipeline } from './pipeline';
 export { toErrorStrategy } from './config';

package/src/hooks/pipeline.ts

@@ -6,7 +6,7 @@
  */
 
 import type {
-  HookDefinition,
+  EffectiveHook,
   HookPhase,
   HookExecutionRecord,
   PipelineResult,
@@ -47,16 +47,61 @@ export class HookPipeline<C = unknown> {
           blockedBy.push(hook.name);
           break; // blocking hook 失败，停止执行后续 hook
         }
-        if (hook.errorStrategy === 'warn') {
-          warnings.push(hook.name);
-        }
-        // 'ignore' 策略静默跳过
+        // 'warn'：记录警告继续（有效集合仅 block/warn，策略由 HookConfig 必填声明）
+        warnings.push(hook.name);
       }
     }
 
     return { passed, records, blockedBy, warnings };
   }
 
+  /**
+   * 按名执行单个 hook（#167）
+   *
+   * 与 run() 共用 executeOne 的采样与错误隔离路径（判定与错误策略的实现体
+   * 只有一份）；enabled / errorStrategy 的值来源仍是注册环节填充的
+   * EffectiveHook（唯一声明点 HookConfig，#159）。
+   *
+   * - enabled:false → 实现体零调用，返回 skipped:true / passed:true 记录
+   *   （镜像 sampled 先例：未执行 = 记录上一面旗，不是异常）
+   * - errorStrategy 'block' 且失败 → 抛 Error（message 含 hook 名与原文）；
+   *   'warn' 且失败 → resolve，返回 passed:false 带 error 的记录
+   * - 未知名 → 抛错（与 assertHookRegistryClosed 闭环口径一致，拒绝静默缺失）
+   *
+   * @param name hook 名称（须已注册）
+   * @param context 传递给 hook 的上下文
+   * @returns 管线观测记录
+   */
+  async runOne(name: string, context: C): Promise<HookExecutionRecord> {
+    const hook = this.registry.get(name);
+    if (!hook) {
+      throw new Error(
+        `[harness] hook 执行失败：hook "${name}" 未注册。请注册同名 HookDefinition 与 HookConfig 声明。`
+      );
+    }
+
+    if (!hook.enabled) {
+      const now = Date.now();
+      return {
+        hookName: hook.name,
+        phase: hook.phase,
+        startedAt: now,
+        completedAt: now,
+        durationMs: 0,
+        passed: true,
+        skipped: true,
+      };
+    }
+
+    const record = await this.executeOne(hook, context);
+    if (!record.passed && hook.errorStrategy === 'block') {
+      throw new Error(
+        `[harness] hook "${hook.name}" blocked: ${record.error ?? '未知错误'}`
+      );
+    }
+    return record;
+  }
+
   /**
    * 执行 before + after 全套管线
    *
@@ -111,7 +156,7 @@ export class HookPipeline<C = unknown> {
    * 执行单个 hook（带采样和错误隔离）
    */
   private async executeOne(
-    hook: HookDefinition<C, unknown>,
+    hook: EffectiveHook<C, unknown>,
     context: C
   ): Promise<HookExecutionRecord> {
     const startedAt = Date.now();

package/src/hooks/registry.ts

@@ -4,7 +4,7 @@
  * 纯簿记，无执行逻辑。线程不安全（Node.js 单线程）。
  */
 
-import type { HookConfig, HookDefinition, HookPhase } from './types';
+import type { EffectiveHook, HookConfig, HookDefinition, HookPhase } from './types';
 
 /**
  * 注册表闭环双向校验（H5，复制 checker 闭环模式）
@@ -66,21 +66,40 @@ export function assertHookRegistryClosed<C = unknown, R = unknown>(
 }
 
 export class HookRegistry<C = unknown, R = unknown> {
-  private hooks: Map<string, HookDefinition<C, R>> = new Map();
+  private hooks: Map<string, EffectiveHook<C, R>> = new Map();
 
   /**
    * 注册 hook（同名覆盖）
+   *
+   * 有效 `enabled` / `errorStrategy` 由 HookConfig 填充——配置表是这两个
+   * 语义的唯一声明点（#159），定义与配置名称不一致即抛错。
    */
-  register(hook: HookDefinition<C, R>): void {
-    this.hooks.set(hook.name, { ...hook });
+  register(hook: HookDefinition<C, R>, config: HookConfig): void {
+    if (hook.name !== config.name) {
+      throw new Error(
+        `[harness] hook 注册失败：定义 "${hook.name}" 与配置 "${config.name}" 名称不一致。`
+      );
+    }
+    this.hooks.set(hook.name, {
+      ...hook,
+      enabled: config.enabled,
+      errorStrategy: config.errorStrategy,
+    });
   }
 
   /**
-   * 批量注册
+   * 批量注册（按 name 配对配置；有实现缺配置声明即抛错）
    */
-  registerAll(hooks: HookDefinition<C, R>[]): void {
+  registerAll(hooks: HookDefinition<C, R>[], configs: readonly HookConfig[]): void {
+    const configByName = new Map(configs.map(c => [c.name, c]));
     for (const hook of hooks) {
-      this.register(hook);
+      const config = configByName.get(hook.name);
+      if (!config) {
+        throw new Error(
+          `[harness] hook 注册失败：hook "${hook.name}" 没有对应的 HookConfig 声明。`
+        );
+      }
+      this.register(hook, config);
     }
   }
 
@@ -92,18 +111,18 @@ export class HookRegistry<C = unknown, R = unknown> {
   }
 
   /**
-   * 获取单个 hook
+   * 获取单个 hook（含有效 enabled / errorStrategy）
    */
-  get(name: string): HookDefinition<C, R> | undefined {
+  get(name: string): EffectiveHook<C, R> | undefined {
     return this.hooks.get(name);
   }
 
   /**
    * 获取指定时机、已启用的 hook，按优先级排序
    */
-  getEnabled(phase: HookPhase): HookDefinition<C, R>[] {
+  getEnabled(phase: HookPhase): EffectiveHook<C, R>[] {
     return Array.from(this.hooks.values())
-      .filter(h => h.phase === phase && h.enabled !== false)
+      .filter(h => h.phase === phase && h.enabled)
       .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
   }
 
@@ -117,7 +136,7 @@ export class HookRegistry<C = unknown, R = unknown> {
   /**
    * 列出所有 hook（含禁用）
    */
-  listAll(): HookDefinition<C, R>[] {
+  listAll(): EffectiveHook<C, R>[] {
     return Array.from(this.hooks.values());
   }