@event4u/agent-config 1.12.0 → 1.14.0

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

@@ -0,0 +1,49 @@
+"""``ChatHistoryTurnCheckHook`` — guards engine-driven turns.
+
+Fires on ``before_dispatch``; classifies the chat-history file via
+``scripts/chat_history.py turn-check``:
+
+- exit 0 (``ok``)        → continue
+- exit 10 (``missing``)  → continue (auto-init handled by chat_history.py)
+- exit 11 (``foreign``)  → raise :class:`HookHalt` so CLI exits 2
+- exit 12 (``returning``)→ raise :class:`HookHalt` so CLI exits 2
+- any other exit         → raise :class:`HookError` (warn, continue)
+"""
+from __future__ import annotations
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError, HookHalt
+from ..registry import HookRegistry
+from ._chat_history_base import (
+    EXIT_FOREIGN,
+    EXIT_MISSING,
+    EXIT_OK,
+    EXIT_RETURNING,
+    _ChatHistoryHookBase,
+)
+
+
+class ChatHistoryTurnCheckHook(_ChatHistoryHookBase):
+    """Run ``turn-check`` at the start of dispatch; halt on drift."""
+
+    def register(self, registry: HookRegistry) -> None:
+        registry.register(HookEvent.BEFORE_DISPATCH, self._on_before_dispatch)
+
+    def _on_before_dispatch(self, ctx: HookContext) -> None:
+        msg = self._resolve_msg(ctx)
+        result = self._invoke("turn-check", "--first-user-msg", msg)
+        code = result.returncode
+        if code in (EXIT_OK, EXIT_MISSING):
+            return
+        if code in (EXIT_FOREIGN, EXIT_RETURNING):
+            text = (result.stderr or result.stdout or "").strip()
+            reason = "foreign" if code == EXIT_FOREIGN else "returning"
+            surface = [line for line in text.splitlines() if line] or [
+                f"chat-history turn-check: {reason}",
+            ]
+            raise HookHalt(f"chat_history_turn_check_{reason}", surface=surface)
+        raise HookError(f"chat-history turn-check failed (exit {code})")
+
+
+__all__ = ["ChatHistoryTurnCheckHook"]

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

@@ -0,0 +1,53 @@
+"""``DirectiveSetGuardHook`` — catch CLI / state directive-set drift.
+
+Fires on :data:`HookEvent.BEFORE_DISPATCH`. Compares the resolved
+``set_name`` (the directive bundle the CLI just loaded) against the
+``directive_set`` field on the persisted ``WorkState``. Mismatch →
+:class:`HookError` (non-fatal: the runner warns), so a flow that
+silently re-dispatches under a different set surfaces the drift before
+any step runs.
+
+The guard is read-only. It does not rewrite ``state.directive_set``;
+fixing the drift is the user's call (typically a ``/mode`` switch or a
+fresh state file).
+"""
+from __future__ import annotations
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+
+
+class DirectiveSetGuardHook:
+    """Asserts ``set_name`` matches ``state.directive_set`` on dispatch."""
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register on :data:`HookEvent.BEFORE_DISPATCH`."""
+        registry.register(HookEvent.BEFORE_DISPATCH, self._guard)
+
+    def _guard(self, ctx: HookContext) -> None:
+        set_name = ctx.set_name
+        work = ctx.work
+        if set_name is None or work is None:
+            # ``before_dispatch`` always carries both refs per the
+            # context surface; missing means a hook-bug, not drift.
+            raise HookError(
+                "directive-set guard: missing set_name or work on "
+                f"before_dispatch (set_name={set_name!r}, work={work!r})",
+            )
+
+        persisted = getattr(work, "directive_set", None)
+        if persisted is None:
+            # Legacy v0 envelopes have no ``directive_set`` field;
+            # the guard is a no-op for those — nothing to compare.
+            return
+
+        if persisted != set_name:
+            raise HookError(
+                "directive-set drift: CLI resolved "
+                f"{set_name!r} but state carries {persisted!r}",
+            )
+
+
+__all__ = ["DirectiveSetGuardHook"]

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

@@ -0,0 +1,50 @@
+"""``HaltSurfaceAuditHook`` — defense-in-depth around halt surfaces.
+
+The dispatcher already calls ``_validate_step_result`` to reject a
+``BLOCKED`` / ``PARTIAL`` outcome with no questions. This hook fires on
+``on_halt`` and re-asserts the same invariant from the hook side, so a
+hand-crafted handler that bypasses the validator (e.g. a future direct
+``state.questions`` mutation) still surfaces a clear failure.
+
+Pure observability: emits :class:`HookError` (non-fatal) when the
+surface is empty. The runner converts it to a ``warnings.warn`` so the
+violation is visible in test logs and CI.
+"""
+from __future__ import annotations
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+
+
+class HaltSurfaceAuditHook:
+    """Asserts that every halt carries a non-empty user-facing surface."""
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register on :data:`HookEvent.ON_HALT` only."""
+        registry.register(HookEvent.ON_HALT, self._audit)
+
+    def _audit(self, ctx: HookContext) -> None:
+        result = ctx.result
+        if result is None:
+            # Hook-driven halts go through ``_hook_halt_blocked`` and
+            # may not carry a ``StepResult`` — the surface lives on
+            # ``state.questions`` instead. Audit that fallback too.
+            questions = getattr(ctx.delivery, "questions", None)
+            if not questions:
+                raise HookError(
+                    f"halt at step {ctx.step_name!r} surfaced no questions "
+                    "(hook-driven halt with empty state.questions)",
+                )
+            return
+
+        questions = getattr(result, "questions", None)
+        if not questions:
+            raise HookError(
+                f"halt at step {ctx.step_name!r} surfaced no questions "
+                "(StepResult.questions empty); the user has nothing to act on",
+            )
+
+
+__all__ = ["HaltSurfaceAuditHook"]

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

@@ -0,0 +1,52 @@
+"""``StateShapeValidationHook`` — round-trip the v1 envelope on load and save.
+
+Fires on :data:`HookEvent.AFTER_LOAD` and :data:`HookEvent.BEFORE_SAVE`.
+For each event, serialises the live :class:`work_engine.state.WorkState`
+through ``state.to_dict`` and re-validates via ``state.from_dict``. A
+:class:`work_engine.state.SchemaError` from either side is reported as
+a :class:`HookError` so the runner warns and continues — observability,
+not a gate.
+
+The hook only sees the post-migration v1 shape. ``_load_or_build`` owns
+v0 → v1 migration; this hook is the safety net catching any drift the
+migration or a hand-edited state file might have produced.
+"""
+from __future__ import annotations
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+
+
+class StateShapeValidationHook:
+    """Round-trips the loaded ``WorkState`` against the v1 schema."""
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register on AFTER_LOAD and BEFORE_SAVE."""
+        registry.register(HookEvent.AFTER_LOAD, self._validate)
+        registry.register(HookEvent.BEFORE_SAVE, self._validate)
+
+    def _validate(self, ctx: HookContext) -> None:
+        work = ctx.work
+        if work is None:
+            # Should not happen on AFTER_LOAD/BEFORE_SAVE; treat as
+            # a hook-side bug rather than swallow silently.
+            raise HookError(
+                "state-shape validation: HookContext.work is None at "
+                f"event for state_file={ctx.state_file}",
+            )
+
+        # Local imports keep the hook module import-light and avoid a
+        # cycle with ``work_engine.state`` at package import time.
+        from ...state import SchemaError, from_dict, to_dict  # noqa: PLC0415
+
+        try:
+            from_dict(to_dict(work))
+        except SchemaError as exc:
+            raise HookError(
+                f"state-shape validation failed: {exc}",
+            ) from exc
+
+
+__all__ = ["StateShapeValidationHook"]

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

@@ -0,0 +1,84 @@
+"""``TraceHook`` — emit one stderr line per hook event.
+
+Useful for debugging dispatch flow and Phase 5 chat-history wiring.
+Registers on every :class:`HookEvent`; output goes to a configurable
+stream (default ``sys.stderr``) so tests can capture it.
+
+Pure observability — never mutates context, never halts. A misbehaving
+sink (e.g. closed stream) raises :class:`HookError`, which the runner
+swallows with a warning per the three-tier contract.
+"""
+from __future__ import annotations
+
+import sys
+from typing import IO
+
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+
+
+class TraceHook:
+    """Stderr-trace hook for every lifecycle event.
+
+    Parameters
+    ----------
+    stream:
+        Output stream. Defaults to ``sys.stderr``. Tests pass an
+        ``io.StringIO`` to capture the trace without touching stderr.
+    prefix:
+        Line prefix. Defaults to ``"[hook]"`` for visual separation
+        from regular CLI output.
+    """
+
+    def __init__(
+        self,
+        stream: IO[str] | None = None,
+        prefix: str = "[hook]",
+    ) -> None:
+        self._stream = stream if stream is not None else sys.stderr
+        self._prefix = prefix
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register the trace callback for every :class:`HookEvent`."""
+        for event in HookEvent:
+            registry.register(event, self._make_callback(event))
+
+    def _make_callback(self, event: HookEvent):
+        def _cb(ctx: HookContext) -> None:
+            try:
+                line = self._format(event, ctx)
+                self._stream.write(line + "\n")
+                self._stream.flush()
+            except (OSError, ValueError) as exc:
+                raise HookError(f"trace stream unavailable: {exc}") from exc
+
+        return _cb
+
+    def _format(self, event: HookEvent, ctx: HookContext) -> str:
+        """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.
+        """
+        parts: list[str] = [self._prefix, f"event={event.value}"]
+        if ctx.step_name:
+            parts.append(f"step={ctx.step_name}")
+        if ctx.set_name:
+            parts.append(f"set={ctx.set_name}")
+        if ctx.result is not None:
+            outcome = getattr(ctx.result, "outcome", None)
+            if outcome is not None:
+                parts.append(f"outcome={getattr(outcome, 'value', outcome)}")
+        if ctx.final is not None:
+            parts.append(f"final={getattr(ctx.final, 'value', ctx.final)}")
+        if ctx.halting:
+            parts.append(f"halting={ctx.halting}")
+        if ctx.exception is not None:
+            parts.append(f"exception={type(ctx.exception).__name__}")
+        return " ".join(parts)
+
+
+__all__ = ["TraceHook"]

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

@@ -0,0 +1,66 @@
+"""``HookContext`` — payload carried into every hook callback.
+
+One dataclass for both layers. Most fields are ``None`` 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 — accessing a field that is ``None`` for the current event
+is a hook bug, not an engine bug.
+
+Per-event subset (mirrors the roadmap):
+
+Dispatcher layer (``delivery`` is set; ``work`` is ``None``):
+    - ``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``
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class HookContext:
+    """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 in ``dispatcher.py`` and ``cli.py``,
+    not by the dataclass.
+
+    ``extra`` exists as an escape hatch for hook-specific state that
+    does not warrant a dedicated field. Use sparingly; if a piece of
+    state is read by more than one hook, promote it to a real field.
+    """
+
+    # Dispatcher-layer refs.
+    step_name: str | None = None
+    delivery: Any = None  # DeliveryState — typed Any to avoid an import cycle.
+    result: Any = None  # StepResult
+    exception: BaseException | None = None
+
+    # CLI-layer refs.
+    work: Any = None  # WorkState — typed Any to avoid an import cycle.
+    state_file: Path | None = None
+    fmt: str | None = None
+    set_name: str | None = None
+    final: Any = None  # Outcome
+    halting: str | None = None
+    args: Any = None  # argparse.Namespace
+
+    # Escape hatch for hook-specific state.
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = ["HookContext"]

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

@@ -0,0 +1,44 @@
+"""Hook event surface for ``work_engine``.
+
+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``). The split is
+deliberate — see the ``Hook event surface (locked)`` section of the
+roadmap for the per-event context payloads.
+
+Adding events is a roadmap-level decision: hook consumers depend on
+the surface staying stable, and an enum makes accidental string typos
+fail at import time.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class HookEvent(str, Enum):
+    """Lifecycle events emitted by the work engine.
+
+    Subclassing ``str`` keeps round-trips trivial for telemetry and
+    JSON tracing — the value is the event name verbatim.
+    """
+
+    # 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"
+
+
+__all__ = ["HookEvent"]

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

@@ -0,0 +1,79 @@
+"""Hook control-flow signals.
+
+Three-tier error contract (locked by roadmap P1):
+
+- ``HookError`` — non-fatal. Hook implementation failed; the runner
+  catches it, warns via ``warnings.warn``, 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 ``Exception`` — 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 without
+catching ``BaseException``.
+"""
+from __future__ import annotations
+
+
+class _HookSignal(Exception):
+    """Internal marker for hook-originated control flow.
+
+    Not part of the public API. The runner uses ``isinstance`` checks
+    against the concrete subclasses below; the base exists only so a
+    single ``except _HookSignal`` would cover both signals if a future
+    refactor needs it.
+    """
+
+
+class HookError(_HookSignal):
+    """Non-fatal hook failure.
+
+    Raised (or ``warn``-equivalent — both forms work) when a hook
+    callback fails in a way the *engine* should ignore. The runner
+    catches it, emits a ``warnings.warn`` with the message, and moves
+    on to the next callback registered for the event.
+
+    Example:
+        ``raise HookError("trace sink unavailable: connection refused")``
+
+    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 :class:`HookHalt` is for.
+    """
+
+
+class HookHalt(_HookSignal):
+    """Fatal-controlled stop requested by a hook.
+
+    Hooks raise this when execution must not continue (e.g. chat-history
+    ``turn-check`` returns ``foreign``: a different session owns the
+    log, work cannot safely proceed). The runner catches it and returns
+    it to the caller; the caller turns it into the appropriate halt
+    surface:
+
+    - Dispatcher layer → ``Outcome.BLOCKED`` with ``state.questions``
+      populated from ``surface``.
+    - CLI layer → exit code 2, ``surface`` printed to stderr, no state
+      saved unless the halt fires after ``_save()``.
+
+    ``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.
+    """
+
+    def __init__(self, reason: str, surface: list[str] | None = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.surface: list[str] = list(surface or [])
+
+
+__all__ = ["HookError", "HookHalt"]

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

@@ -0,0 +1,60 @@
+"""``HookRegistry`` — insertion-ordered map from event to callbacks.
+
+Phase 1 ships insertion-ordered registration only. If a real ordering
+need surfaces later (e.g. trace must fire before mutation hooks), add
+a priority field as a follow-up — do not pre-build it (per Notes
+section of the roadmap).
+
+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 :class:`HookRunner`.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Iterable
+
+from .context import HookContext
+from .events import HookEvent
+
+HookCallback = Callable[[HookContext], None]
+"""A hook callback. Returns ``None`` on success, raises ``HookError``
+or ``HookHalt`` to signal control flow per ``exceptions.py``."""
+
+
+class HookRegistry:
+    """Insertion-ordered registry of hook callbacks per event.
+
+    Single instance per CLI invocation. Built once in ``cli.main()``
+    and shared with ``dispatch()`` so dispatcher events and CLI events
+    are routed through the same callback set.
+    """
+
+    def __init__(self) -> None:
+        self._hooks: dict[HookEvent, list[HookCallback]] = {}
+
+    def register(self, event: HookEvent, callback: HookCallback) -> None:
+        """Register ``callback`` for ``event``.
+
+        Multiple callbacks for the same event are allowed; they fire
+        in registration order.
+        """
+        self._hooks.setdefault(event, []).append(callback)
+
+    def for_event(self, event: HookEvent) -> tuple[HookCallback, ...]:
+        """Return callbacks registered for ``event`` in insertion order.
+
+        Returns an empty tuple when no callbacks are registered — the
+        runner uses this to short-circuit a no-op fast path.
+        """
+        return tuple(self._hooks.get(event, ()))
+
+    def events(self) -> Iterable[HookEvent]:
+        """Iterate over events that have at least one callback.
+
+        Diagnostics-only; not used on the hot path.
+        """
+        return self._hooks.keys()
+
+
+__all__ = ["HookCallback", "HookRegistry"]

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

@@ -0,0 +1,73 @@
+"""``HookRunner`` — single emit point for hook callbacks.
+
+Implements the three-tier error contract documented in
+``exceptions.py``:
+
+- ``HookError`` from a callback → caught, ``warnings.warn`` is emitted,
+  the runner continues with the next callback for the same event.
+  Returns ``None`` once the event is fully drained.
+- ``HookHalt`` from a callback → caught, **returned** to the caller
+  with no further callbacks invoked for this event. The caller
+  decides how to surface the halt (engine halt, CLI exit 2). Never
+  re-raised through the dispatch loop.
+- any other ``Exception`` → propagates unchanged. Treated as a hook
+  bug; dispatch unwinds.
+
+The runner is intentionally tiny. Behavior changes belong here so
+``dispatcher.py`` and ``cli.py`` stay free of hook bookkeeping.
+"""
+from __future__ import annotations
+
+import warnings
+
+from .context import HookContext
+from .events import HookEvent
+from .exceptions import HookError, HookHalt
+from .registry import HookRegistry
+
+
+class HookRunner:
+    """Emit hook events through a :class:`HookRegistry`.
+
+    Construct once per CLI invocation, share between the CLI and the
+    dispatcher. ``emit`` is the only public method on the hot path.
+    """
+
+    def __init__(self, registry: HookRegistry | None = None) -> None:
+        self._registry = registry if registry is not None else HookRegistry()
+
+    @property
+    def registry(self) -> HookRegistry:
+        """Return the underlying registry.
+
+        Exposed so callers can register additional hooks after
+        construction (e.g. in tests). Not used on the hot path.
+        """
+        return self._registry
+
+    def emit(self, event: HookEvent, ctx: HookContext) -> HookHalt | None:
+        """Fire all callbacks registered for ``event``.
+
+        Returns ``None`` when every callback completed (with or without
+        a swallowed :class:`HookError`). Returns the first
+        :class:`HookHalt` raised, after which no further callbacks are
+        invoked for this event. Any other exception propagates.
+        """
+        callbacks = self._registry.for_event(event)
+        if not callbacks:
+            return None
+        for callback in callbacks:
+            try:
+                callback(ctx)
+            except HookHalt as halt:
+                return halt
+            except HookError as err:
+                warnings.warn(
+                    f"hook {event.value} raised HookError: {err}",
+                    stacklevel=2,
+                )
+                continue
+        return None
+
+
+__all__ = ["HookRunner"]