@event4u/agent-config 8.4.0 → 8.4.1

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.ts

@@ -0,0 +1,161 @@
+/**
+ * `MemoryVisibilityHook` — emit the visibility line on save.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/memory_visibility.py`
+ * (ADR-200 py2ts — work_engine.hooks.builtin subpackage). Implements the
+ * producer side of `docs/contracts/memory-visibility-v1.md`: derive
+ * `asks/hits/ids` from `state.memory` and thread the rendered line into
+ * `state.report`.
+ *
+ * Fires on `before_save`. Default-off; opt-in via `.agent-settings.yml`. The
+ * hook is purely observational: failures surface as {@link HookError}
+ * (non-fatal per the three-tier contract).
+ */
+import { summarise_memory, summarise_verify } from '../../scoring/decision_trace.js';
+import {
+    DEFAULT_ASKED_TYPES,
+    compute_affected,
+    format_changed_decisions_block,
+    format_line,
+    should_emit,
+    summarise_visibility,
+} from '../../scoring/memory_visibility.js';
+import type { HookContext } from '../context.js';
+import { HookEvent } from '../events.js';
+import { HookError } from '../exceptions.js';
+import type { HookRegistry } from '../registry.js';
+
+/** Arbitrary value, mirroring the Python `Any` fields. */
+type Any = unknown;
+
+/**
+ * Thread the `🧠 Memory: <hits>/<asks> · ids=[…]` line into the report.
+ *
+ * `memory_cadence` is the `memory.cadence` cadence key. `visibility_off`
+ * mirrors `memory.visibility: off`. `asked_types` overrides the list of
+ * memory types treated as `asks` in the visibility line.
+ */
+export class MemoryVisibilityHook {
+    private readonly _memory_cadence: string;
+    private readonly _visibility_off: boolean;
+    private readonly _asked_types: readonly string[];
+
+    constructor(
+        options: {
+            memory_cadence?: string;
+            visibility_off?: boolean;
+            asked_types?: Iterable<string> | null;
+        } = {},
+    ) {
+        this._memory_cadence = options.memory_cadence ?? 'always';
+        this._visibility_off = options.visibility_off ?? false;
+        this._asked_types =
+            options.asked_types !== undefined && options.asked_types !== null
+                ? [...options.asked_types]
+                : DEFAULT_ASKED_TYPES;
+    }
+
+    /** Register the visibility-line emitter on `before_save`. */
+    register(registry: HookRegistry): void {
+        registry.register(HookEvent.BEFORE_SAVE, (ctx) => this._on_before_save(ctx));
+    }
+
+    private _on_before_save(ctx: HookContext): void {
+        const work = ctx.work;
+        if (work === null || work === undefined) {
+            return;
+        }
+        const memory = _getattr(work, 'memory', null);
+        const summary = summarise_visibility(memory, { asked_types: this._asked_types });
+        if (
+            !should_emit(summary, {
+                memory_cadence: this._memory_cadence,
+                visibility_off: this._visibility_off,
+            })
+        ) {
+            return;
+        }
+        const affected = this._derive_affected(work, memory);
+        const line = format_line(summary, { affected });
+        if (!line) {
+            return;
+        }
+        const block = format_changed_decisions_block(
+            (summary['ids'] as string[]) || [],
+            affected,
+        );
+        const existing = (_getattr(work, 'report', '') as string) || '';
+        const rendered = block === null ? line : `${line}\n\n${block}`;
+        if (existing.includes(line) && (block === null || existing.includes(block))) {
+            return;
+        }
+        const sep = existing ? '\n\n' : '';
+        try {
+            (work as Record<string, Any>)['report'] = `${existing}${sep}${rendered}`;
+        } catch (_exc) {
+            throw new HookError('memory-visibility: state.report not writable');
+        }
+    }
+
+    /**
+     * Compute the closed-list `affected` keys for this work step. Returns
+     * `null` when memory was not consulted (hits == 0).
+     */
+    private _derive_affected(work: Any, memory: Any): string[] | null {
+        const memory_summary = summarise_memory(memory);
+        const verify_summary = summarise_verify(_getattr(work, 'verify', null));
+        const ambiguity = _pyTruthy(_getattr(work, 'questions', null));
+        return compute_affected({
+            memory_hits: memory_summary['hits'] as number,
+            verify_claims: verify_summary['claims'] as number,
+            verify_first_try_passes: verify_summary['first_try_passes'] as number,
+            ambiguity_flag: ambiguity,
+            changes: _getattr(work, 'changes', null),
+            applied_rules: _getattr(work, 'applied_rules', null) as string[] | null,
+            test_plan: _getattr(work, 'test_plan', null) as string[] | null,
+        });
+    }
+}
+
+/**
+ * Convenience helper: render the line directly from a memory list. Used by
+ * external callers that have a `memory` list but no {@link HookContext}.
+ * Returns `null` when `asks == 0`.
+ */
+export function derive_visibility(memory: Any): string | null {
+    return format_line(summarise_visibility(memory));
+}
+
+/** Python `getattr(obj, name, default)`. */
+function _getattr(obj: Any, name: string, dflt: Any): Any {
+    if (obj !== null && typeof obj === 'object' && name in (obj as object)) {
+        return (obj as Record<string, Any>)[name];
+    }
+    return dflt;
+}
+
+/** Python `bool(x)` truthiness for the `questions` shapes seen here. */
+function _pyTruthy(value: Any): boolean {
+    if (value === null || value === undefined || value === false) {
+        return false;
+    }
+    if (value === true) {
+        return true;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    if (typeof value === 'string') {
+        return value.length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (value instanceof Map || value instanceof Set) {
+        return value.size > 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as Record<string, unknown>).length > 0;
+    }
+    return true;
+}

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/state_shape_validation.ts

@@ -0,0 +1,45 @@
+/**
+ * `StateShapeValidationHook` — round-trip the v1 envelope on load and save.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/state_shape_validation.py`
+ * (ADR-200 py2ts — work_engine.hooks.builtin subpackage). Fires on
+ * `AFTER_LOAD` and `BEFORE_SAVE`. For each event, serialises the live
+ * `WorkState` through `state.to_dict` and re-validates via `state.from_dict`.
+ * A `SchemaError` from either side is reported as a {@link HookError} so the
+ * runner warns and continues — observability, not a gate.
+ */
+import { SchemaError, type WorkState, from_dict, to_dict } from '../../state.js';
+import type { HookContext } from '../context.js';
+import { HookEvent } from '../events.js';
+import { HookError } from '../exceptions.js';
+import type { HookRegistry } from '../registry.js';
+
+/** Round-trips the loaded `WorkState` against the v1 schema. */
+export class StateShapeValidationHook {
+    /** Register on AFTER_LOAD and BEFORE_SAVE. */
+    register(registry: HookRegistry): void {
+        registry.register(HookEvent.AFTER_LOAD, (ctx) => this._validate(ctx));
+        registry.register(HookEvent.BEFORE_SAVE, (ctx) => this._validate(ctx));
+    }
+
+    private _validate(ctx: HookContext): void {
+        const work = ctx.work;
+        if (work === null || work === undefined) {
+            // Should not happen on AFTER_LOAD/BEFORE_SAVE; treat as a
+            // hook-side bug rather than swallow silently.
+            throw new HookError(
+                'state-shape validation: HookContext.work is None at ' +
+                    `event for state_file=${ctx.state_file === null ? 'None' : ctx.state_file}`,
+            );
+        }
+
+        try {
+            from_dict(to_dict(work as WorkState));
+        } catch (exc) {
+            if (exc instanceof SchemaError) {
+                throw new HookError(`state-shape validation failed: ${exc.message}`);
+            }
+            throw exc;
+        }
+    }
+}

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/trace.ts

@@ -0,0 +1,134 @@
+/**
+ * `TraceHook` — emit one stderr line per hook event.
+ *
+ * TypeScript twin of `work_engine/hooks/builtin/trace.py` (ADR-200 py2ts —
+ * work_engine.hooks.builtin subpackage). Registers on every `HookEvent`;
+ * output goes to a configurable stream (default `process.stderr`) so tests can
+ * capture it.
+ *
+ * Pure observability — never mutates context, never halts. A misbehaving sink
+ * raises {@link HookError}, which the runner swallows with a warning.
+ */
+import type { HookEvent } from '../events.js';
+import { HOOK_EVENTS } from '../events.js';
+import type { HookContext } from '../context.js';
+import { HookError } from '../exceptions.js';
+import type { HookCallback, HookRegistry } from '../registry.js';
+
+/** Arbitrary value, mirroring the Python `Any` fields. */
+type Any = unknown;
+
+/**
+ * Minimal write+flush sink, mirroring Python's `IO[str]`. `process.stderr`
+ * satisfies it; tests pass a string-collector.
+ */
+export interface TextStream {
+    write(s: string): unknown;
+    flush?(): void;
+}
+
+/** Stderr-trace hook for every lifecycle event. */
+export class TraceHook {
+    private readonly _stream: TextStream;
+    private readonly _prefix: string;
+
+    constructor(stream: TextStream | null = null, prefix = '[hook]') {
+        this._stream = stream !== null ? stream : process.stderr;
+        this._prefix = prefix;
+    }
+
+    /** Register the trace callback for every `HookEvent`. */
+    register(registry: HookRegistry): void {
+        for (const event of HOOK_EVENTS) {
+            registry.register(event, this._make_callback(event));
+        }
+    }
+
+    private _make_callback(event: HookEvent): HookCallback {
+        const _cb = (ctx: HookContext): void => {
+            try {
+                const line = this._format(event, ctx);
+                this._stream.write(line + '\n');
+                if (typeof this._stream.flush === 'function') {
+                    this._stream.flush();
+                }
+            } catch (exc) {
+                if (exc instanceof HookError) {
+                    throw exc;
+                }
+                // Mirror Python `except (OSError, ValueError)`: wrap stream
+                // failures as a non-fatal HookError; re-raise anything else.
+                throw new HookError(`trace stream unavailable: ${_errStr(exc)}`);
+            }
+        };
+        return _cb;
+    }
+
+    /**
+     * Build a one-line trace record.
+     *
+     * Format: `[hook] event=<name> step=<step> set=<set> outcome=<o>`.
+     * Missing fields are skipped so the line stays short on events that only
+     * carry a subset of the context.
+     */
+    private _format(event: HookEvent, ctx: HookContext): string {
+        const parts: string[] = [this._prefix, `event=${event}`];
+        if (ctx.step_name) {
+            parts.push(`step=${ctx.step_name}`);
+        }
+        if (ctx.set_name) {
+            parts.push(`set=${ctx.set_name}`);
+        }
+        if (ctx.result !== null && ctx.result !== undefined) {
+            const outcome = _getattr(ctx.result, 'outcome', null);
+            if (outcome !== null && outcome !== undefined) {
+                parts.push(`outcome=${_valueOf(outcome)}`);
+            }
+        }
+        if (ctx.final !== null && ctx.final !== undefined) {
+            parts.push(`final=${_valueOf(ctx.final)}`);
+        }
+        if (ctx.halting) {
+            parts.push(`halting=${ctx.halting}`);
+        }
+        if (ctx.exception !== null && ctx.exception !== undefined) {
+            parts.push(`exception=${_typeName(ctx.exception)}`);
+        }
+        return parts.join(' ');
+    }
+}
+
+/** Python `getattr(obj, name, default)`. */
+function _getattr(obj: Any, name: string, dflt: Any): Any {
+    if (obj !== null && typeof obj === 'object' && name in (obj as object)) {
+        return (obj as Record<string, Any>)[name];
+    }
+    return dflt;
+}
+
+/** Python `getattr(x, "value", x)` — enum value if present, else the value. */
+function _valueOf(x: Any): string {
+    if (x !== null && typeof x === 'object' && 'value' in (x as object)) {
+        return String((x as Record<string, Any>)['value']);
+    }
+    return String(x);
+}
+
+/** Python `type(exc).__name__`. */
+function _typeName(exc: Any): string {
+    if (exc instanceof Error) {
+        return exc.constructor.name;
+    }
+    if (exc !== null && exc !== undefined && typeof exc === 'object') {
+        return (exc as { constructor?: { name?: string } }).constructor?.name ?? 'object';
+    }
+    return typeof exc;
+}
+
+/** `str(exc)` for the wrapped-sink-failure message. */
+function _errStr(exc: unknown): string {
+    if (exc instanceof Error) {
+        return exc.message;
+    }
+    return String(exc);
+}

package/src/agent-src/templates/scripts/work_engine/hooks/context.ts

@@ -0,0 +1,94 @@
+/**
+ * `HookContext` — payload carried into every hook callback.
+ *
+ * TypeScript twin of `work_engine/hooks/context.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). One class for both layers. Most fields are
+ * `null` for any given event; the per-event subset is documented below and
+ * locked by the roadmap's hook event surface table. Hooks must tolerate
+ * missing fields gracefully.
+ *
+ * Per-event subset (mirrors the roadmap):
+ *
+ * Dispatcher layer (`delivery` is set; `work` is `null`):
+ *     - `before_step`   → `step_name`, `delivery`
+ *     - `after_step`    → `step_name`, `delivery`, `result`
+ *     - `on_halt`       → `step_name`, `delivery`, `result`
+ *     - `on_error`      → `step_name`, `delivery`, `exception`
+ *
+ * CLI layer (`work` is set; `delivery` may be set after load):
+ *     - `before_load`       → `state_file`, `args`
+ *     - `after_load`        → `state_file`, `work`, `fmt`
+ *     - `before_dispatch`   → `work`, `delivery`, `set_name`
+ *     - `after_dispatch`    → `work`, `delivery`, `final`, `halting`
+ *     - `before_save`       → `work`, `delivery`, `fmt`
+ *     - `after_save`        → `work`, `state_file`, `fmt`
+ */
+
+/** Arbitrary value, mirroring the Python `Any` fields. */
+export type Any = unknown;
+
+/** Per-event payload passed to every hook callback (matches the dataclass). */
+export interface HookContextInit {
+    // Dispatcher-layer refs.
+    step_name?: string | null;
+    delivery?: Any; // DeliveryState
+    result?: Any; // StepResult
+    exception?: Any; // BaseException
+
+    // CLI-layer refs.
+    work?: Any; // WorkState
+    state_file?: string | null;
+    fmt?: string | null;
+    set_name?: string | null;
+    final?: Any; // Outcome
+    halting?: string | null;
+    args?: Any; // argparse.Namespace
+
+    // Escape hatch for hook-specific state.
+    extra?: Record<string, Any>;
+}
+
+/**
+ * Per-event payload passed to every hook callback.
+ *
+ * Fields are intentionally optional — the runner does not validate which
+ * ones are populated for a given event. The contract is enforced by the
+ * call sites, not by the class.
+ *
+ * `extra` exists as an escape hatch for hook-specific state that does not
+ * warrant a dedicated field.
+ */
+export class HookContext {
+    // Dispatcher-layer refs.
+    step_name: string | null;
+    delivery: Any;
+    result: Any;
+    exception: Any;
+
+    // CLI-layer refs.
+    work: Any;
+    state_file: string | null;
+    fmt: string | null;
+    set_name: string | null;
+    final: Any;
+    halting: string | null;
+    args: Any;
+
+    // Escape hatch for hook-specific state.
+    extra: Record<string, Any>;
+
+    constructor(init: HookContextInit = {}) {
+        this.step_name = init.step_name ?? null;
+        this.delivery = init.delivery ?? null;
+        this.result = init.result ?? null;
+        this.exception = init.exception ?? null;
+        this.work = init.work ?? null;
+        this.state_file = init.state_file ?? null;
+        this.fmt = init.fmt ?? null;
+        this.set_name = init.set_name ?? null;
+        this.final = init.final ?? null;
+        this.halting = init.halting ?? null;
+        this.args = init.args ?? null;
+        this.extra = init.extra ?? {};
+    }
+}

package/src/agent-src/templates/scripts/work_engine/hooks/events.ts

@@ -0,0 +1,58 @@
+/**
+ * Hook event surface for `work_engine`.
+ *
+ * TypeScript twin of `work_engine/hooks/events.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). Mirrors the Python `str`-Enum 1:1: each
+ * value is the event name verbatim, so round-trips stay trivial for
+ * telemetry and JSON tracing.
+ *
+ * Ten events split across two layers per
+ * `agents/roadmaps/road-to-work-engine-hooks.md` (locked).
+ *
+ * Dispatcher-layer events fire from inside `dispatcher.dispatch()` and
+ * operate on `DeliveryState` (legacy, internal). CLI-layer events fire
+ * from `cli.main()` and operate on `WorkState` (v1 envelope) plus
+ * auxiliary refs (`state_file`, `fmt`, `args`).
+ */
+
+/**
+ * Lifecycle events emitted by the work engine.
+ *
+ * Modelled as a const object + value-union so it behaves like the Python
+ * `str`-Enum: members compare equal to their string value, and the value
+ * IS the event name. `HookEvent.BEFORE_STEP === 'before_step'`.
+ */
+export const HookEvent = {
+    // Dispatcher layer (DeliveryState).
+    BEFORE_STEP: 'before_step',
+    AFTER_STEP: 'after_step',
+    ON_HALT: 'on_halt',
+    ON_ERROR: 'on_error',
+
+    // CLI layer (WorkState).
+    BEFORE_LOAD: 'before_load',
+    AFTER_LOAD: 'after_load',
+    BEFORE_DISPATCH: 'before_dispatch',
+    AFTER_DISPATCH: 'after_dispatch',
+    BEFORE_SAVE: 'before_save',
+    AFTER_SAVE: 'after_save',
+} as const;
+
+export type HookEvent = (typeof HookEvent)[keyof typeof HookEvent];
+
+/**
+ * Iteration order over every event, mirroring Python `for event in HookEvent`
+ * (declaration order). Used by {@link TraceHook} to register on all events.
+ */
+export const HOOK_EVENTS: readonly HookEvent[] = [
+    HookEvent.BEFORE_STEP,
+    HookEvent.AFTER_STEP,
+    HookEvent.ON_HALT,
+    HookEvent.ON_ERROR,
+    HookEvent.BEFORE_LOAD,
+    HookEvent.AFTER_LOAD,
+    HookEvent.BEFORE_DISPATCH,
+    HookEvent.AFTER_DISPATCH,
+    HookEvent.BEFORE_SAVE,
+    HookEvent.AFTER_SAVE,
+];

package/src/agent-src/templates/scripts/work_engine/hooks/exceptions.ts

@@ -0,0 +1,85 @@
+/**
+ * Hook control-flow signals.
+ *
+ * TypeScript twin of `work_engine/hooks/exceptions.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). Class names stay 1:1 with the Python module.
+ *
+ * Three-tier error contract (locked by roadmap P1):
+ *
+ * - `HookError` — non-fatal. Hook implementation failed; the runner
+ *   catches it, warns, and continues with the next callback for the same
+ *   event. Work proceeds.
+ * - `HookHalt` — fatal-controlled. Hook demands a clean stop (canonical
+ *   example: chat-history `turn-check` foreign session). The runner
+ *   catches it and **returns** it to the caller, who decides how to
+ *   surface it (engine halt, CLI exit code 2 + readable surface). Not
+ *   re-raised through the dispatch loop.
+ * - any other `Error` — fatal-uncontrolled. Treated as a bug in the
+ *   hook. The runner lets it propagate verbatim; dispatch unwinds.
+ *
+ * Both signals share a private `_HookSignal` base so the runner can
+ * distinguish hook-originated control flow from genuine bugs.
+ */
+
+/**
+ * Internal marker for hook-originated control flow.
+ *
+ * Not part of the public API. The runner uses `instanceof` checks
+ * against the concrete subclasses below; the base exists only so a
+ * single `instanceof _HookSignal` would cover both signals if a future
+ * refactor needs it.
+ */
+export class _HookSignal extends Error {
+    constructor(message?: string) {
+        super(message);
+        Object.setPrototypeOf(this, _HookSignal.prototype);
+        this.name = '_HookSignal';
+    }
+}
+
+/**
+ * Non-fatal hook failure.
+ *
+ * Raised when a hook callback fails in a way the *engine* should ignore.
+ * The runner catches it, emits a warning with the message, and moves
+ * on to the next callback registered for the event.
+ *
+ * Use this for transient or non-critical hook failures (telemetry
+ * sinks, optional reporters). Do **not** use it to signal "stop the
+ * engine" — that is what {@link HookHalt} is for.
+ */
+export class HookError extends _HookSignal {
+    constructor(message?: string) {
+        super(message);
+        Object.setPrototypeOf(this, HookError.prototype);
+        this.name = 'HookError';
+    }
+}
+
+/**
+ * Fatal-controlled stop requested by a hook.
+ *
+ * Hooks raise this when execution must not continue. The runner catches
+ * it and returns it to the caller; the caller turns it into the
+ * appropriate halt surface (dispatcher `Outcome.BLOCKED`, CLI exit 2).
+ *
+ * `surface` is a list of pre-formatted numbered options per the
+ * `user-interaction` rule (one entry per line). Callers must not
+ * reformat — surface is rendered verbatim.
+ *
+ * `reason` is a short machine-readable code (e.g. `"foreign"`,
+ * `"missing"`, `"validation_failed"`) for logging and tests; it is not
+ * shown to the user.
+ */
+export class HookHalt extends _HookSignal {
+    readonly reason: string;
+    readonly surface: string[];
+
+    constructor(reason: string, surface: string[] | null = null) {
+        super(reason);
+        Object.setPrototypeOf(this, HookHalt.prototype);
+        this.name = 'HookHalt';
+        this.reason = reason;
+        this.surface = surface ? [...surface] : [];
+    }
+}

package/src/agent-src/templates/scripts/work_engine/hooks/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `work_engine.hooks` — cross-cutting lifecycle hooks for the engine.
+ *
+ * TypeScript twin of `work_engine/hooks/__init__.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). Public surface:
+ *
+ * - `HookEvent` — ten lifecycle events, two layers.
+ * - `HookContext` — per-event payload.
+ * - `HookError` / `HookHalt` — three-tier error contract.
+ * - `HookRegistry` — insertion-ordered event → callbacks map.
+ * - `HookRunner` — single emit point, owns the error contract.
+ */
+export {
+    ChatHistoryAppendHook,
+    ChatHistoryHaltAppendHook,
+    DecisionTraceHook,
+    DirectiveSetGuardHook,
+    HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
+    StateShapeValidationHook,
+    TraceHook,
+} from './builtin/index.js';
+export { HookContext } from './context.js';
+export { HookEvent } from './events.js';
+export { HookError, HookHalt } from './exceptions.js';
+export { type HookCallback, HookRegistry } from './registry.js';
+export { HookRunner } from './runner.js';

package/src/agent-src/templates/scripts/work_engine/hooks/registry.ts

@@ -0,0 +1,66 @@
+/**
+ * `HookRegistry` — insertion-ordered map from event to callbacks.
+ *
+ * TypeScript twin of `work_engine/hooks/registry.py` (ADR-200 py2ts —
+ * work_engine.hooks subpackage). Phase 1 ships insertion-ordered
+ * registration only.
+ *
+ * The registry is a plain container. It does not invoke callbacks, does
+ * not catch exceptions, and does not know about the error contract; that
+ * responsibility lives in {@link HookRunner}.
+ */
+import type { HookContext } from './context.js';
+import type { HookEvent } from './events.js';
+
+/**
+ * A hook callback. Returns `void` on success, throws `HookError` or
+ * `HookHalt` to signal control flow per `exceptions.ts`.
+ */
+export type HookCallback = (ctx: HookContext) => void;
+
+/**
+ * Insertion-ordered registry of hook callbacks per event.
+ *
+ * Single instance per CLI invocation. Built once and shared with
+ * `dispatch()` so dispatcher events and CLI events are routed through the
+ * same callback set.
+ */
+export class HookRegistry {
+    // Map preserves insertion order, mirroring Python's dict ordering.
+    private _hooks: Map<HookEvent, HookCallback[]> = new Map();
+
+    /**
+     * Register `callback` for `event`.
+     *
+     * Multiple callbacks for the same event are allowed; they fire in
+     * registration order.
+     */
+    register(event: HookEvent, callback: HookCallback): void {
+        let list = this._hooks.get(event);
+        if (list === undefined) {
+            list = [];
+            this._hooks.set(event, list);
+        }
+        list.push(callback);
+    }
+
+    /**
+     * Return callbacks registered for `event` in insertion order.
+     *
+     * Returns an empty array when no callbacks are registered — the runner
+     * uses this to short-circuit a no-op fast path.
+     */
+    for_event(event: HookEvent): HookCallback[] {
+        const list = this._hooks.get(event);
+        return list === undefined ? [] : [...list];
+    }
+
+    /**
+     * Iterate over events that have at least one callback.
+     *
+     * Diagnostics-only; not used on the hot path.
+     */
+    events(): IterableIterator<HookEvent> {
+        return this._hooks.keys();
+    }
+}