@event4u/agent-config 1.12.0 → 1.14.0

package/.agent-src/templates/scripts/work_engine/dispatcher.py

@@ -0,0 +1,331 @@
+"""Linear step dispatcher for ``/implement-ticket``.
+
+The dispatcher holds no business logic. It walks the fixed eight-step
+order declared in ``agents/contexts/implement-ticket-flow.md``, hands
+each step a live ``DeliveryState``, and honours the three terminal
+outcomes:
+
+- ``SUCCESS`` — record and advance.
+- ``BLOCKED`` — record, copy questions onto the state, halt.
+- ``PARTIAL`` — record, copy questions onto the state, halt.
+
+Resumption semantics (Option A, flow contract §agent-directives):
+steps whose name is already marked ``success`` in
+``state.outcomes`` are **skipped**. This lets a caller re-invoke the
+dispatcher after executing an agent-directive (the ``implement``,
+``test``, ``verify`` steps cannot run from pure Python), update the
+relevant slice of ``DeliveryState``, record ``success`` on the
+resumed step, and continue without replaying earlier work.
+
+Step handlers are injected by the caller rather than discovered at
+import time. Phase 1 shipped the dispatcher with mock handlers;
+Phase 2 wires the real ones under ``steps/``. Keeping injection
+explicit means the dispatcher is trivially testable and never
+depends on handler import order.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import import_module
+from typing import Any
+
+from .delivery_state import DeliveryState, Outcome, Step, StepResult
+from .hooks import HookContext, HookEvent, HookHalt, HookRunner
+from .state import KNOWN_DIRECTIVE_SETS
+
+_NOOP_RUNNER: HookRunner = HookRunner()
+"""Shared empty-registry runner reused when ``dispatch`` is called
+without an explicit ``hooks`` argument. ``HookRunner.emit`` short-circuits
+when no callbacks are registered, so the hot path stays branch-light
+while the call sites stay uniform."""
+
+STEP_ORDER: tuple[str, ...] = (
+    "refine",
+    "memory",
+    "analyze",
+    "plan",
+    "implement",
+    "test",
+    "verify",
+    "report",
+)
+"""Canonical execution order. Eight steps, fixed, no branching.
+
+Changing this order is a roadmap-level decision — not a PR rider — per
+the surface-growth guardrails in
+``agents/roadmaps/road-to-implement-ticket.md``.
+"""
+
+DEFAULT_DIRECTIVE_SET: str = "backend"
+"""Directive set chosen when ``state`` does not carry one explicitly.
+
+Backwards compatibility for v0 ``DeliveryState`` callers: the legacy
+shape has no ``directive_set`` field, so ``select_directive_set``
+falls back to ``"backend"`` and the engine behaves exactly as it did
+before R1 Phase 4.
+"""
+
+# Schema enum names use hyphens (``ui-trivial``) but Python packages
+# cannot. The loader is the single place that bridges between the two
+# forms; everywhere else uses the wire form.
+_PACKAGE_NAME_OVERRIDES: Mapping[str, str] = {"ui-trivial": "ui_trivial"}
+
+
+def dispatch(
+    state: DeliveryState,
+    steps: Mapping[str, Step],
+    hooks: HookRunner | None = None,
+) -> tuple[Outcome, str | None]:
+    """Run the eight steps linearly against ``state``.
+
+    Returns a ``(final_outcome, halting_step)`` tuple. ``halting_step``
+    is ``None`` when every step succeeded; otherwise it carries the
+    name of the step whose result halted the flow.
+
+    Parameters
+    ----------
+    state:
+        Live ``DeliveryState``. Mutated in place: each step's outcome
+        is recorded in ``state.outcomes`` under the step name, and
+        any surfaced questions land on ``state.questions``.
+    steps:
+        Mapping from step name to handler. Every entry in
+        :data:`STEP_ORDER` must be present; missing entries raise
+        ``KeyError`` at dispatch time rather than silently skipping,
+        so incomplete wiring surfaces as a hard failure.
+    hooks:
+        Optional :class:`HookRunner` carrying a registry of dispatcher-
+        layer hooks (``before_step``, ``after_step``, ``on_halt``,
+        ``on_error``). Default ``None`` preserves every existing call
+        site verbatim — internally ``dispatch`` falls back to a shared
+        empty-registry runner so hook bookkeeping stays uniform without
+        a per-emit ``if hooks is None`` branch.
+
+    Raises
+    ------
+    KeyError
+        If ``steps`` does not cover every entry in
+        :data:`STEP_ORDER`.
+    """
+    _assert_all_steps_present(steps)
+
+    # Clear stale questions from a previous halt before we resume so
+    # the caller never mistakes old options for fresh ones.
+    state.questions = []
+
+    runner = hooks if hooks is not None else _NOOP_RUNNER
+
+    for name in STEP_ORDER:
+        if state.outcomes.get(name) == Outcome.SUCCESS.value:
+            # Already completed on an earlier invocation — skip per the
+            # resume contract. The caller is responsible for keeping
+            # ``state.outcomes`` and the matching slice in sync.
+            continue
+
+        before_halt = runner.emit(
+            HookEvent.BEFORE_STEP,
+            HookContext(step_name=name, delivery=state),
+        )
+        if before_halt is not None:
+            return _hook_halt_blocked(state, runner, name, before_halt, result=None)
+
+        handler = steps[name]
+        try:
+            result = handler(state)
+        except Exception as exc:
+            # Let dispatcher-layer observers see the failure before the
+            # exception unwinds the engine. ``on_error`` is observe-only;
+            # the original exception is always re-raised.
+            runner.emit(
+                HookEvent.ON_ERROR,
+                HookContext(step_name=name, delivery=state, exception=exc),
+            )
+            raise
+        _validate_step_result(name, result)
+
+        state.outcomes[name] = result.outcome.value
+
+        after_halt = runner.emit(
+            HookEvent.AFTER_STEP,
+            HookContext(step_name=name, delivery=state, result=result),
+        )
+        if after_halt is not None:
+            return _hook_halt_blocked(state, runner, name, after_halt, result=result)
+
+        if result.outcome is Outcome.BLOCKED:
+            state.questions = list(result.questions)
+            _emit_on_halt(runner, name, state, result)
+            return Outcome.BLOCKED, name
+
+        if result.outcome is Outcome.PARTIAL:
+            state.questions = list(result.questions)
+            _emit_on_halt(runner, name, state, result)
+            return Outcome.PARTIAL, name
+
+    return Outcome.SUCCESS, None
+
+
+def _hook_halt_blocked(
+    state: DeliveryState,
+    runner: HookRunner,
+    name: str,
+    halt: HookHalt,
+    result: StepResult | None,
+) -> tuple[Outcome, str | None]:
+    """Translate a hook-driven :class:`HookHalt` into a clean engine halt.
+
+    Hook-driven halts are treated as first-class engine halts per the
+    P2 contract: the dispatcher returns ``(BLOCKED, step_name)`` with
+    ``state.questions`` rendered verbatim from the halt's ``surface``.
+    The step's outcome marker is set to ``"blocked"`` only when the
+    halt fires before the handler ran (so resume re-enters the gate);
+    when it fires after the handler, the marker the handler produced
+    is preserved so resume reflects what actually happened.
+    """
+    if result is None:
+        state.outcomes[name] = Outcome.BLOCKED.value
+    state.questions = list(halt.surface)
+    _emit_on_halt(runner, name, state, result)
+    return Outcome.BLOCKED, name
+
+
+def _emit_on_halt(
+    runner: HookRunner,
+    name: str,
+    state: DeliveryState,
+    result: StepResult | None,
+) -> None:
+    """Fire ``on_halt`` as an observe-only event.
+
+    A :class:`HookHalt` raised from inside ``on_halt`` would create a
+    halt-of-a-halt loop; the runner returns it but the dispatcher
+    deliberately ignores it — the halt surface is already populated.
+    """
+    runner.emit(
+        HookEvent.ON_HALT,
+        HookContext(step_name=name, delivery=state, result=result),
+    )
+
+
+def _assert_all_steps_present(steps: Mapping[str, Step]) -> None:
+    """Reject an incomplete step mapping up front.
+
+    We deliberately fail loudly here: a missing step would otherwise
+    raise deep inside the dispatch loop after partial state mutation,
+    which makes debugging the wiring harder than it needs to be.
+    """
+    missing = [name for name in STEP_ORDER if name not in steps]
+    if missing:
+        raise KeyError(
+            "Step mapping is missing handlers for: " + ", ".join(missing),
+        )
+
+
+def _validate_step_result(name: str, result: StepResult) -> None:
+    """Enforce the blocked/partial invariant: questions must be set.
+
+    A step that blocks without surfacing a question is a bug — there
+    is nothing for the user to answer. We raise ``ValueError`` instead
+    of silently recording the outcome so the defect is visible at the
+    earliest possible point.
+    """
+    if result.outcome in (Outcome.BLOCKED, Outcome.PARTIAL) and not result.questions:
+        raise ValueError(
+            f"Step {name!r} returned {result.outcome.value} with no questions; "
+            "blocked and partial outcomes must surface at least one numbered option.",
+        )
+
+
+def select_directive_set(state: Any) -> str:
+    """Return the directive set name to dispatch ``state`` against.
+
+    Looks for ``state.directive_set`` (the v1 :class:`work_engine.state.WorkState`
+    field) and falls back to :data:`DEFAULT_DIRECTIVE_SET` when the
+    attribute is missing — the legacy v0 :class:`DeliveryState` has no
+    such field, and existing callers must keep working unchanged
+    until R1 Phase 4 Step 1 lands the runtime switch.
+
+    The returned name is validated against :data:`KNOWN_DIRECTIVE_SETS`;
+    an unknown value raises ``ValueError`` rather than silently
+    falling back, so a typo in a hand-written state file fails loudly
+    instead of producing surprising behavior.
+    """
+    name = getattr(state, "directive_set", DEFAULT_DIRECTIVE_SET)
+    if not isinstance(name, str) or not name:
+        raise ValueError(
+            f"directive_set must be a non-empty string; got {name!r}",
+        )
+    if name not in KNOWN_DIRECTIVE_SETS:
+        raise ValueError(
+            f"unknown directive_set {name!r}; "
+            f"known sets: {sorted(KNOWN_DIRECTIVE_SETS)}",
+        )
+    return name
+
+
+def load_directive_set(name: str) -> Mapping[str, Step]:
+    """Import the ``directives.<name>`` package and return its step mapping.
+
+    The selected set's ``__init__`` exposes a ``get_steps()`` factory
+    (see :class:`work_engine.directives.backend`) that returns the
+    ``{step_name: handler}`` mapping the dispatcher walks. Unimplemented
+    sets (``ui``, ``ui-trivial``, ``mixed``) raise
+    ``NotImplementedError`` from their ``get_steps()`` so the failure
+    point is the loader, not a half-walked dispatch loop.
+
+    The schema enum carries hyphenated wire names (``ui-trivial``) but
+    Python packages must use underscores; :data:`_PACKAGE_NAME_OVERRIDES`
+    is the single translation point.
+    """
+    module = _import_directive_set(name)
+    get_steps = getattr(module, "get_steps", None)
+    if not callable(get_steps):
+        raise AttributeError(
+            f"work_engine.directives.{module.__name__.rsplit('.', 1)[-1]} "
+            "does not expose a callable get_steps()",
+        )
+    steps = get_steps()
+    if not isinstance(steps, Mapping):
+        raise TypeError(
+            f"work_engine.directives.{module.__name__.rsplit('.', 1)[-1]}"
+            f".get_steps() must return a Mapping; "
+            f"got {type(steps).__name__}",
+        )
+    return steps
+
+
+def assert_kind_supported(kind: str, set_name: str) -> None:
+    """Raise ``NotImplementedError`` if ``set_name`` cannot handle ``kind``.
+
+    Reads the per-set ``SUPPORTED_KINDS`` tuple (see
+    :data:`work_engine.directives.backend.SUPPORTED_KINDS`) and checks
+    membership. Distinct from :func:`select_directive_set`, which only
+    validates the directive-set *name*: this gate validates the
+    name/kind *pair*, so a future schema widening that adds new
+    ``input.kind`` values (R2 ``prompt``) halts loudly at the boundary
+    instead of crashing inside the first deterministic step.
+
+    Sets that have no ``SUPPORTED_KINDS`` attribute are treated as
+    "supports nothing" — the unimplemented stubs (``ui``,
+    ``ui-trivial``, ``mixed``) already raise from ``get_steps()``, so
+    this branch only matters during the brief window between adding a
+    new directive set and wiring its capability tuple.
+    """
+    module = _import_directive_set(set_name)
+    supported = getattr(module, "SUPPORTED_KINDS", ())
+    if kind not in supported:
+        raise NotImplementedError(
+            f"directive_set {set_name!r} does not handle "
+            f"input.kind={kind!r}; supported kinds: {sorted(set(supported))}",
+        )
+
+
+def _import_directive_set(name: str):
+    """Validate ``name`` and import the matching package module."""
+    if name not in KNOWN_DIRECTIVE_SETS:
+        raise ValueError(
+            f"unknown directive_set {name!r}; "
+            f"known sets: {sorted(KNOWN_DIRECTIVE_SETS)}",
+        )
+    package_name = _PACKAGE_NAME_OVERRIDES.get(name, name)
+    return import_module(f"work_engine.directives.{package_name}")

package/.agent-src/templates/scripts/work_engine/hooks/__init__.py

@@ -0,0 +1,54 @@
+"""``work_engine.hooks`` — cross-cutting lifecycle hooks for the engine.
+
+Phase 1 of ``agents/roadmaps/road-to-work-engine-hooks.md`` ships the
+primitives only. The dispatcher and CLI are not yet instrumented;
+golden tests must remain byte-identical until Phase 2 / Phase 3 land.
+
+Public surface:
+
+- :class:`HookEvent` — ten lifecycle events, two layers.
+- :class:`HookContext` — per-event payload.
+- :class:`HookError` / :class:`HookHalt` — three-tier error contract.
+- :class:`HookRegistry` — insertion-ordered event \u2192 callbacks map.
+- :class:`HookRunner` — single emit point, owns the error contract.
+
+The principle is documented in
+``agents/roadmaps/road-to-work-engine-hooks.md`` § Underlying
+principle: agent hooks are emulated by moving lifecycle ownership
+from the agent into the work engine. The engine owns boundaries.
+"""
+from __future__ import annotations
+
+from .builtin import (
+    ChatHistoryAppendHook,
+    ChatHistoryHaltAppendHook,
+    ChatHistoryHeartbeatHook,
+    ChatHistoryTurnCheckHook,
+    DirectiveSetGuardHook,
+    HaltSurfaceAuditHook,
+    StateShapeValidationHook,
+    TraceHook,
+)
+from .context import HookContext
+from .events import HookEvent
+from .exceptions import HookError, HookHalt
+from .registry import HookCallback, HookRegistry
+from .runner import HookRunner
+
+__all__ = [
+    "ChatHistoryAppendHook",
+    "ChatHistoryHaltAppendHook",
+    "ChatHistoryHeartbeatHook",
+    "ChatHistoryTurnCheckHook",
+    "DirectiveSetGuardHook",
+    "HaltSurfaceAuditHook",
+    "HookCallback",
+    "HookContext",
+    "HookError",
+    "HookEvent",
+    "HookHalt",
+    "HookRegistry",
+    "HookRunner",
+    "StateShapeValidationHook",
+    "TraceHook",
+]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py

@@ -0,0 +1,32 @@
+"""Concrete observability hooks shipped with the engine.
+
+Phase 4 hooks: low-risk, default-off, observe-only. They are registered
+by ``cli._build_hook_registry`` only when explicitly enabled in
+``.agent-settings.yml`` (Phase 6 wires the settings → registry path).
+
+Each hook is a small class exposing a ``register(registry)`` method so
+the registry stays the single source of truth for event → callback
+wiring. None of these hooks mutate engine state; failures surface as
+:class:`HookError` (non-fatal, the runner warns and continues).
+"""
+from __future__ import annotations
+
+from .chat_history_append import ChatHistoryAppendHook
+from .chat_history_halt_append import ChatHistoryHaltAppendHook
+from .chat_history_heartbeat import ChatHistoryHeartbeatHook
+from .chat_history_turn_check import ChatHistoryTurnCheckHook
+from .directive_set_guard import DirectiveSetGuardHook
+from .halt_surface_audit import HaltSurfaceAuditHook
+from .state_shape_validation import StateShapeValidationHook
+from .trace import TraceHook
+
+__all__ = [
+    "ChatHistoryAppendHook",
+    "ChatHistoryHaltAppendHook",
+    "ChatHistoryHeartbeatHook",
+    "ChatHistoryTurnCheckHook",
+    "DirectiveSetGuardHook",
+    "HaltSurfaceAuditHook",
+    "StateShapeValidationHook",
+    "TraceHook",
+]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/_chat_history_base.py

@@ -0,0 +1,103 @@
+"""Shared plumbing for chat-history hooks.
+
+Subprocess-driven so the work-engine package stays decoupled from
+``scripts/chat_history.py``'s internals. The ``runner`` injection
+point is the test seam — production passes ``subprocess.run``,
+tests pass a fake.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Sequence
+
+from ..context import HookContext
+from ..exceptions import HookError
+
+ProcessRunner = Callable[[Sequence[str]], "subprocess.CompletedProcess[str]"]
+"""Callable that runs a subprocess. Production default: ``_default_runner``."""
+
+EXIT_OK = 0
+EXIT_MISSING = 10
+EXIT_FOREIGN = 11
+EXIT_RETURNING = 12
+
+
+def _default_runner(cmd: Sequence[str]) -> "subprocess.CompletedProcess[str]":
+    return subprocess.run(list(cmd), capture_output=True, text=True, check=False)
+
+
+def _derive_first_user_msg(ctx: HookContext) -> str | None:
+    """Pull a stable first-user-msg out of the available context.
+
+    CLI-layer events carry ``ctx.work`` (the v1 envelope); dispatcher-layer
+    events (``before_step`` / ``after_step`` / ``on_halt``) carry only
+    ``ctx.delivery`` (the legacy :class:`DeliveryState`). Both shapes feed
+    the same ``id: title`` / ``raw`` derivation so chat-history entries
+    stay stable across the lifecycle. Returns ``None`` when the shape is
+    unknown — callers raise ``HookError`` so the runner converts it to
+    a warning.
+    """
+    work = ctx.work
+    if work is not None and getattr(work, "input", None) is not None:
+        inp = work.input
+        data = getattr(inp, "data", None) or {}
+        kind = getattr(inp, "kind", None)
+        if kind == "prompt":
+            raw = data.get("raw")
+            if raw:
+                return str(raw)
+        elif kind == "ticket":
+            joined = _ticket_msg(data)
+            if joined:
+                return joined
+
+    delivery = ctx.delivery
+    if delivery is not None:
+        ticket = getattr(delivery, "ticket", None) or {}
+        joined = _ticket_msg(ticket)
+        if joined:
+            return joined
+    return None
+
+
+def _ticket_msg(ticket: dict) -> str:
+    ticket_id = ticket.get("id") or ""
+    title = ticket.get("title") or ""
+    return f"{ticket_id}: {title}".strip(": ").strip()
+
+
+class _ChatHistoryHookBase:
+    """Shared plumbing — script path, runner, and first-msg derivation."""
+
+    def __init__(
+        self,
+        script_path: Path,
+        *,
+        runner: ProcessRunner | None = None,
+        first_user_msg: str | None = None,
+    ) -> None:
+        self.script_path = Path(script_path)
+        self._runner = runner or _default_runner
+        self._fixed_msg = first_user_msg
+
+    def _resolve_msg(self, ctx: HookContext) -> str:
+        msg = self._fixed_msg or _derive_first_user_msg(ctx)
+        if not msg:
+            raise HookError("chat-history hook: cannot derive first-user-msg")
+        return msg
+
+    def _invoke(self, *args: str) -> "subprocess.CompletedProcess[str]":
+        cmd = [sys.executable, str(self.script_path), *args]
+        return self._runner(cmd)
+
+
+__all__ = [
+    "EXIT_FOREIGN",
+    "EXIT_MISSING",
+    "EXIT_OK",
+    "EXIT_RETURNING",
+    "ProcessRunner",
+    "_ChatHistoryHookBase",
+]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_append.py

@@ -0,0 +1,44 @@
+"""``ChatHistoryAppendHook`` — phase-boundary persistence.
+
+Fires on ``after_step``. Appends a ``--type phase`` entry whenever a
+step closed with ``Outcome.SUCCESS``. Failures bubble up as
+:class:`HookError` so the runner converts them to warnings — append
+errors must not break the main flow.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+from ._chat_history_base import EXIT_OK, _ChatHistoryHookBase
+
+
+class ChatHistoryAppendHook(_ChatHistoryHookBase):
+    """Append a phase-boundary entry after every successful step."""
+
+    def register(self, registry: HookRegistry) -> None:
+        registry.register(HookEvent.AFTER_STEP, self._on_after_step)
+
+    def _on_after_step(self, ctx: HookContext) -> None:
+        from ...delivery_state import Outcome  # local: avoid import cycle.
+
+        result = ctx.result
+        if result is None or getattr(result, "outcome", None) != Outcome.SUCCESS:
+            return
+        msg = self._resolve_msg(ctx)
+        payload: dict[str, Any] = {"step": ctx.step_name or "<unknown>"}
+        proc = self._invoke(
+            "append", "--first-user-msg", msg,
+            "--type", "phase", "--json", json.dumps(payload),
+        )
+        if proc.returncode != EXIT_OK:
+            raise HookError(
+                f"chat-history append failed (exit {proc.returncode})"
+            )
+
+
+__all__ = ["ChatHistoryAppendHook"]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_halt_append.py

@@ -0,0 +1,42 @@
+"""``ChatHistoryHaltAppendHook`` — capture halt surfaces in the log.
+
+Fires on ``on_halt``. Records a ``--type decision`` entry with the
+step name and any pending questions so a fresh chat can resume from
+the persisted log alone.
+"""
+from __future__ import annotations
+
+import json
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+from ._chat_history_base import EXIT_OK, _ChatHistoryHookBase
+
+
+class ChatHistoryHaltAppendHook(_ChatHistoryHookBase):
+    """Append a decision entry whenever a step halts."""
+
+    def register(self, registry: HookRegistry) -> None:
+        registry.register(HookEvent.ON_HALT, self._on_halt)
+
+    def _on_halt(self, ctx: HookContext) -> None:
+        msg = self._resolve_msg(ctx)
+        questions: list[str] = []
+        if ctx.result is not None:
+            questions = list(getattr(ctx.result, "questions", []) or [])
+        if not questions and ctx.delivery is not None:
+            questions = list(getattr(ctx.delivery, "questions", []) or [])
+        payload = {"step": ctx.step_name or "<unknown>", "questions": questions}
+        proc = self._invoke(
+            "append", "--first-user-msg", msg,
+            "--type", "decision", "--json", json.dumps(payload),
+        )
+        if proc.returncode != EXIT_OK:
+            raise HookError(
+                f"chat-history halt-append failed (exit {proc.returncode})"
+            )
+
+
+__all__ = ["ChatHistoryHaltAppendHook"]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_heartbeat.py

@@ -0,0 +1,50 @@
+"""``ChatHistoryHeartbeatHook`` — visibility marker before save.
+
+Fires on ``before_save``. Runs ``chat_history.py heartbeat`` and,
+if the script emits a marker line, threads it onto ``state.report``
+so the agent's reply naturally carries the heartbeat without manual
+copy/paste.
+
+Why ``before_save`` and not ``after_dispatch``: the marker must land
+in the report that gets persisted. ``cli._sync_back`` runs between
+``after_dispatch`` and ``before_save`` and reassigns
+``work.report = delivery.report`` — a marker written on
+``after_dispatch`` would be overwritten before ``_save``. Firing on
+``before_save`` runs after the sync, so the marker survives.
+"""
+from __future__ import annotations
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+from ._chat_history_base import EXIT_OK, _ChatHistoryHookBase
+
+
+class ChatHistoryHeartbeatHook(_ChatHistoryHookBase):
+    """Run heartbeat before save; thread marker into ``state.report``."""
+
+    def register(self, registry: HookRegistry) -> None:
+        registry.register(HookEvent.BEFORE_SAVE, self._on_before_save)
+
+    def _on_before_save(self, ctx: HookContext) -> None:
+        msg = self._resolve_msg(ctx)
+        proc = self._invoke("heartbeat", "--first-user-msg", msg)
+        if proc.returncode != EXIT_OK:
+            raise HookError(
+                f"chat-history heartbeat failed (exit {proc.returncode})"
+            )
+        marker = (proc.stdout or "").strip()
+        if not marker or ctx.work is None:
+            return
+        existing = getattr(ctx.work, "report", "") or ""
+        if marker in existing:
+            return
+        sep = "\n\n" if existing else ""
+        try:
+            ctx.work.report = f"{existing}{sep}{marker}"
+        except AttributeError:
+            raise HookError("chat-history heartbeat: state.report not writable")
+
+
+__all__ = ["ChatHistoryHeartbeatHook"]