@event4u/agent-config 2.9.0 → 2.11.0

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

@@ -0,0 +1,162 @@
+"""``DecisionGateHook`` — refuse to advance when an opt-in gate fires.
+
+Bridges :mod:`work_engine.scoring.decision_engine` into the dispatcher
+hook bus. Reads the gate config from
+:class:`work_engine.hooks.settings.HookSettings.decision_engine` and
+fires on ``AFTER_STEP`` only for the phase each gate owns.
+
+Gate-conflict resolution and the non-TTY timeout protocol live in
+``docs/contracts/decision-engine-gates.md``. The hook only consumes
+them; it never re-implements gate logic.
+
+Three actions, mapped 1:1 from :func:`evaluate_gates`:
+
+- ``stop``        → raise :class:`HookHalt` with a numbered-option
+                    surface. Dispatcher returns ``BLOCKED``.
+- ``warn``        → raise :class:`HookError` so the runner logs the
+                    reason and the step proceeds.
+- ``ask_timeout`` → non-interactive context; apply
+                    ``on_block_fallback`` and re-resolve to ``stop``
+                    or ``warn``. ``block_reason=ask_timeout`` is
+                    surfaced verbatim so the trace records it.
+- ``ask``         → interactive context; for the CLI integration this
+                    collapses to ``stop`` with the prompt surface,
+                    matching how every other ``HookHalt`` is rendered.
+                    The interactive resumption path is owned by the
+                    CLI, not by the hook.
+
+Default-off: when ``settings.decision_engine`` is ``None`` or every
+gate is ``off`` the hook short-circuits without examining state.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...scoring.decision_engine import (
+    DecisionEngineSettings,
+    GateDecision,
+    evaluate_gates,
+)
+from ...scoring.decision_trace import (
+    derive_confidence_band,
+    derive_risk_class,
+    summarise_memory,
+    summarise_verify,
+)
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError, HookHalt
+from ..registry import HookRegistry
+
+_BLOCK_REASON_PREFIX = "decision_gate"
+
+
+class DecisionGateHook:
+    """Evaluate decision-engine gates on every ``AFTER_STEP``.
+
+    Parameters
+    ----------
+    settings:
+        Resolved :class:`DecisionEngineSettings`. The hook stores it as
+        a frozen reference; tests pass a fresh instance per scenario.
+    """
+
+    def __init__(self, settings: DecisionEngineSettings) -> None:
+        self._settings = settings
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register the gate callback on ``AFTER_STEP``."""
+        registry.register(HookEvent.AFTER_STEP, self._evaluate)
+
+    # -- lifecycle callback ------------------------------------------
+
+    def _evaluate(self, ctx: HookContext) -> None:
+        if not self._settings.any_gate_active:
+            return
+        phase = ctx.step_name
+        if not phase:
+            return
+        delivery = ctx.delivery
+        memory = summarise_memory(getattr(delivery, "memory", None))
+        verify = summarise_verify(getattr(delivery, "verify", None))
+        ambiguity = bool(getattr(delivery, "questions", None))
+        decision = evaluate_gates(
+            self._settings,
+            phase=phase,
+            confidence_band=derive_confidence_band(
+                memory_hits=memory["hits"],
+                verify_claims=verify["claims"],
+                verify_first_try_passes=verify["first_try_passes"],
+                ambiguity_flag=ambiguity,
+            ),
+            risk_class=derive_risk_class(
+                getattr(delivery, "changes", None),
+            ),
+            memory_hits=memory["hits"],
+        )
+        if decision is None:
+            return
+        self._apply(decision)
+
+    # -- action dispatch ----------------------------------------------
+
+    def _apply(self, decision: GateDecision) -> None:
+        action = decision.action
+        if action == "warn":
+            raise HookError(self._format_reason(decision))
+        if action == "ask_timeout":
+            fallback = self._settings.on_block_fallback
+            if fallback == "warn":
+                raise HookError(self._format_reason(decision, suffix="ask_timeout"))
+            raise HookHalt(
+                f"{_BLOCK_REASON_PREFIX}:{decision.gate_id}:ask_timeout",
+                surface=self._surface(decision, suffix="ask_timeout"),
+            )
+        raise HookHalt(
+            f"{_BLOCK_REASON_PREFIX}:{decision.gate_id}",
+            surface=self._surface(decision),
+        )
+
+    # -- formatting helpers -------------------------------------------
+
+    @staticmethod
+    def _format_reason(decision: GateDecision, *, suffix: str = "") -> str:
+        tag = f"{_BLOCK_REASON_PREFIX}:{decision.gate_id}"
+        if suffix:
+            tag = f"{tag}:{suffix}"
+        return f"{tag} — {decision.reason}"
+
+    @staticmethod
+    def _surface(
+        decision: GateDecision, *, suffix: str = "",
+    ) -> list[str]:
+        header = f"Decision-engine gate fired: {decision.gate_id} (phase={decision.phase})"
+        if suffix:
+            header = f"{header} [{suffix}]"
+        return [
+            header,
+            f"Reason: {decision.reason}",
+            "1) Address the gate condition and resume.",
+            "2) Lower the gate in `.agent-settings.yml` "
+            "(`decision_engine` block) and resume.",
+            "3) Abort the run.",
+        ]
+
+
+def build_decision_gate_hook(
+    settings: Any,
+) -> DecisionGateHook | None:
+    """Construct the hook from a :class:`DecisionEngineSettings`-like
+    object. Returns ``None`` when the config is absent or every gate is
+    ``off``; the bootstrap layer then skips registration entirely.
+    """
+    if settings is None:
+        return None
+    if not isinstance(settings, DecisionEngineSettings):
+        return None
+    if not settings.any_gate_active:
+        return None
+    return DecisionGateHook(settings)
+
+
+__all__ = ["DecisionGateHook", "build_decision_gate_hook"]

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

@@ -23,8 +23,11 @@ from __future__ import annotations
 
 from typing import Any, Iterable
 
+from ...scoring.decision_trace import summarise_memory, summarise_verify
 from ...scoring.memory_visibility import (
     DEFAULT_ASKED_TYPES,
+    compute_affected,
+    format_changed_decisions_block,
     format_line,
     should_emit,
     summarise_visibility,
@@ -82,20 +85,46 @@ class MemoryVisibilityHook:
             visibility_off=self._visibility_off,
         ):
             return
-        line = format_line(summary)
+        affected = self._derive_affected(work, memory)
+        line = format_line(summary, affected=affected)
         if not line:
             return
+        block = format_changed_decisions_block(
+            summary.get("ids") or [], affected,
+        )
         existing = getattr(work, "report", "") or ""
-        if line in existing:
+        rendered = line if block is None else f"{line}\n\n{block}"
+        if line in existing and (block is None or block in existing):
             return
         sep = "\n\n" if existing else ""
         try:
-            work.report = f"{existing}{sep}{line}"
+            work.report = f"{existing}{sep}{rendered}"
         except AttributeError as exc:
             raise HookError(
                 "memory-visibility: state.report not writable",
             ) from exc
 
+    def _derive_affected(self, work: Any, memory: Any) -> list[str] | None:
+        """Compute the closed-list ``affected`` keys for this work step.
+
+        Reuses the decision-trace summarisers so the counterfactual
+        matches the trace hook's view of the same WorkState. Returns
+        ``None`` when memory was not consulted (hits == 0); callers
+        then omit the ``· affected: …`` segment per the contract.
+        """
+        memory_summary = summarise_memory(memory)
+        verify_summary = summarise_verify(getattr(work, "verify", None))
+        ambiguity = bool(getattr(work, "questions", None))
+        return compute_affected(
+            memory_hits=memory_summary["hits"],
+            verify_claims=verify_summary["claims"],
+            verify_first_try_passes=verify_summary["first_try_passes"],
+            ambiguity_flag=ambiguity,
+            changes=getattr(work, "changes", None),
+            applied_rules=getattr(work, "applied_rules", None),
+            test_plan=getattr(work, "test_plan", None),
+        )
+
 
 def derive_visibility(memory: Any) -> str | None:
     """Convenience helper: render the line directly from a memory list.

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

@@ -28,6 +28,11 @@ from pathlib import Path
 from typing import Any
 
 from work_engine._lib.agent_settings import load_agent_settings
+from work_engine.scoring.decision_engine import (
+    DecisionEngineConfigError,
+    DecisionEngineSettings,
+    parse as _parse_decision_engine,
+)
 
 DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
 DEFAULT_CHAT_HISTORY_SCRIPT = "scripts/chat_history.py"
@@ -41,6 +46,11 @@ class HookSettings:
     empty regardless of the per-hook fields; this is the default when no
     settings file exists or no ``hooks`` block is declared, and it is
     what keeps golden-replay tests byte-stable.
+
+    ``decision_engine`` carries the parsed gate config so
+    :class:`DecisionGateHook` can read it without re-parsing
+    ``.agent-settings.yml``. When the block is absent or malformed the
+    field stays at the default (every gate ``off``).
     """
 
     enabled: bool = False
@@ -54,6 +64,7 @@ class HookSettings:
     cost_profile: str = "standard"
     chat_history_enabled: bool = False
     chat_history_script: str = DEFAULT_CHAT_HISTORY_SCRIPT
+    decision_engine: DecisionEngineSettings = DecisionEngineSettings()
 
 
 _DEFAULT = HookSettings()
@@ -89,8 +100,18 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
     if not isinstance(hooks, dict):
         return _DEFAULT
     enabled = _coerce_bool(hooks.get("enabled"), False)
+
+    decision_engine_raw = data.get("decision_engine")
+    try:
+        decision_engine_settings = _parse_decision_engine(decision_engine_raw)
+    except DecisionEngineConfigError:
+        decision_engine_settings = DecisionEngineSettings()
+
     if not enabled:
-        return HookSettings(enabled=False)
+        return HookSettings(
+            enabled=False,
+            decision_engine=decision_engine_settings,
+        )
 
     chat_section = hooks.get("chat_history")
     if isinstance(chat_section, dict):
@@ -108,11 +129,7 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
         and _coerce_bool(global_chat.get("enabled"), False)
     )
 
-    decision_engine = data.get("decision_engine")
-    decision_trace_on = (
-        isinstance(decision_engine, dict)
-        and _coerce_bool(decision_engine.get("surface_traces"), False)
-    )
+    decision_trace_on = decision_engine_settings.surface_traces
 
     memory_section = data.get("memory")
     visibility_off = False
@@ -154,6 +171,7 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
         cost_profile=cost_profile,
         chat_history_enabled=chat_block_enabled and global_chat_on,
         chat_history_script=chat_script,
+        decision_engine=decision_engine_settings,
     )
 
 

package/.agent-src/templates/scripts/work_engine/scoring/decision_engine.py

@@ -0,0 +1,351 @@
+"""Decision-engine gates — schema, validation, and per-phase evaluation.
+
+Reads the optional ``decision_engine:`` block from ``.agent-settings.yml``.
+Absent block = current behaviour (observe-only, no gates fire).
+
+Schema (all keys optional; the parser rejects unknown keys hard):
+
+- ``surface_traces`` (bool, default ``false``) — opt-in for
+  ``DecisionTraceHook``. Predates the gates; lives here so the
+  ``decision_engine:`` block has one source-of-truth schema.
+- ``min_confidence`` (``low``/``medium``/``high``/``off``, default
+  ``off``) — confidence-band floor; Phase=Plan refuses to advance
+  when the band is below.
+- ``block_on_risk`` (``low``/``medium``/``high``/``off``, default
+  ``off``) — risk-class ceiling; Phase=Implement refuses to advance
+  when risk exceeds.
+- ``require_memory_hits`` (bool, default ``false``) — Phase=Refine
+  demands ``memory_hits >= 1``.
+- ``on_block`` (``stop``/``ask``/``warn``, default ``stop``) —
+  what happens when a gate fires.
+- ``ask_timeout_seconds`` (int, default ``30``) — timeout when
+  ``on_block=ask`` runs in a non-interactive context (no TTY, or
+  ``CI=true``).
+- ``on_block_fallback`` (``stop``/``warn``, default ``stop``) —
+  resolution after ``ask_timeout`` elapses.
+
+Gate-conflict resolution (first match wins, only one gate fires per
+phase):
+
+1. ``block_on_risk``         (highest impact)
+2. ``require_memory_hits``
+3. ``min_confidence``        (lowest impact)
+
+See ``docs/contracts/decision-engine-gates.md`` for the full
+priority matrix.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Callable
+
+ALLOWED_KEYS: frozenset[str] = frozenset({
+    "surface_traces",
+    "min_confidence",
+    "block_on_risk",
+    "require_memory_hits",
+    "on_block",
+    "ask_timeout_seconds",
+    "on_block_fallback",
+})
+
+_LEVEL_VALUES: frozenset[str] = frozenset({"low", "medium", "high", "off"})
+_LEVEL_RANK: dict[str, int] = {"low": 1, "medium": 2, "high": 3}
+_ON_BLOCK_VALUES: frozenset[str] = frozenset({"stop", "ask", "warn"})
+_FALLBACK_VALUES: frozenset[str] = frozenset({"stop", "warn"})
+
+GATE_PRIORITY: tuple[str, ...] = (
+    "block_on_risk",
+    "require_memory_hits",
+    "min_confidence",
+)
+"""Conflict-resolution order. Highest-impact gate first; the first
+firing gate emits its reason and downstream gates are skipped."""
+
+_PHASE_FOR_GATE: dict[str, str] = {
+    "block_on_risk": "implement",
+    "require_memory_hits": "refine",
+    "min_confidence": "plan",
+}
+
+
+class DecisionEngineConfigError(ValueError):
+    """Raised when the ``decision_engine:`` block is malformed."""
+
+
+@dataclass(frozen=True)
+class DecisionEngineSettings:
+    """Resolved ``decision_engine:`` block. Frozen to keep gate
+    evaluations replay-stable."""
+
+    surface_traces: bool = False
+    min_confidence: str = "off"
+    block_on_risk: str = "off"
+    require_memory_hits: bool = False
+    on_block: str = "stop"
+    ask_timeout_seconds: int = 30
+    on_block_fallback: str = "stop"
+
+    @property
+    def any_gate_active(self) -> bool:
+        """True when at least one gate is enabled."""
+        return (
+            self.min_confidence != "off"
+            or self.block_on_risk != "off"
+            or self.require_memory_hits
+        )
+
+
+@dataclass(frozen=True)
+class GateDecision:
+    """Outcome of one gate evaluation. ``action`` is the resolved
+    response after applying ``on_block`` plus the non-TTY fallback."""
+
+    gate_id: str
+    phase: str
+    reason: str
+    action: str  # "stop" | "warn" | "ask" | "ask_timeout"
+
+
+def parse(data: Any) -> DecisionEngineSettings:
+    """Parse a ``decision_engine`` block into validated settings.
+
+    Returns defaults when ``data`` is ``None`` (block absent) or an
+    empty mapping. Raises :class:`DecisionEngineConfigError` on
+    unknown keys or invalid values.
+    """
+    if data is None:
+        return DecisionEngineSettings()
+    if not isinstance(data, dict):
+        raise DecisionEngineConfigError(
+            "decision_engine: must be a mapping, got "
+            f"{type(data).__name__}"
+        )
+    unknown = set(data.keys()) - ALLOWED_KEYS
+    if unknown:
+        raise DecisionEngineConfigError(
+            "decision_engine: unknown key(s): "
+            + ", ".join(sorted(unknown))
+            + ". Allowed: " + ", ".join(sorted(ALLOWED_KEYS))
+        )
+    return DecisionEngineSettings(
+        surface_traces=_coerce_bool(data.get("surface_traces"), False),
+        min_confidence=_coerce_level(
+            data.get("min_confidence", "off"), "min_confidence",
+        ),
+        block_on_risk=_coerce_level(
+            data.get("block_on_risk", "off"), "block_on_risk",
+        ),
+        require_memory_hits=_coerce_bool(
+            data.get("require_memory_hits"), False,
+        ),
+        on_block=_coerce_choice(
+            data.get("on_block", "stop"), "on_block", _ON_BLOCK_VALUES,
+        ),
+        ask_timeout_seconds=_coerce_int(
+            data.get("ask_timeout_seconds", 30), "ask_timeout_seconds",
+        ),
+        on_block_fallback=_coerce_choice(
+            data.get("on_block_fallback", "stop"),
+            "on_block_fallback", _FALLBACK_VALUES,
+        ),
+    )
+
+
+
+def _coerce_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, str):
+        s = value.strip().lower()
+        if s in ("true", "yes", "on", "1"):
+            return True
+        if s in ("false", "no", "off", "0"):
+            return False
+    raise DecisionEngineConfigError(
+        f"decision_engine.{value!r}: expected bool"
+    )
+
+
+def _coerce_level(value: Any, key: str) -> str:
+    if value is None:
+        return "off"
+    # YAML 1.1 parses unquoted ``off`` as boolean False; accept it as
+    # the off sentinel so writers don't have to quote. Boolean True
+    # stays rejected — there is no defensible level it maps to.
+    if isinstance(value, bool):
+        if value is False:
+            return "off"
+        raise DecisionEngineConfigError(
+            f"decision_engine.{key}: boolean True is not a valid level "
+            "(quote a string: low/medium/high/off)"
+        )
+    if not isinstance(value, str):
+        raise DecisionEngineConfigError(
+            f"decision_engine.{key}: expected string, got "
+            f"{type(value).__name__}"
+        )
+    s = value.strip().lower()
+    if s not in _LEVEL_VALUES:
+        raise DecisionEngineConfigError(
+            f"decision_engine.{key}: invalid value {value!r}. "
+            "Allowed: " + ", ".join(sorted(_LEVEL_VALUES))
+        )
+    return s
+
+
+def _coerce_choice(value: Any, key: str, allowed: frozenset[str]) -> str:
+    if not isinstance(value, str):
+        raise DecisionEngineConfigError(
+            f"decision_engine.{key}: expected string, got "
+            f"{type(value).__name__}"
+        )
+    s = value.strip().lower()
+    if s not in allowed:
+        raise DecisionEngineConfigError(
+            f"decision_engine.{key}: invalid value {value!r}. "
+            "Allowed: " + ", ".join(sorted(allowed))
+        )
+    return s
+
+
+def _coerce_int(value: Any, key: str) -> int:
+    if isinstance(value, bool):
+        raise DecisionEngineConfigError(
+            f"decision_engine.{key}: expected int, got bool"
+        )
+    if isinstance(value, int):
+        if value < 0:
+            raise DecisionEngineConfigError(
+                f"decision_engine.{key}: must be >= 0"
+            )
+        return value
+    raise DecisionEngineConfigError(
+        f"decision_engine.{key}: expected int, got "
+        f"{type(value).__name__}"
+    )
+
+
+def evaluate_gates(
+    settings: DecisionEngineSettings,
+    *,
+    phase: str,
+    confidence_band: str | None,
+    risk_class: str | None,
+    memory_hits: int,
+    is_interactive: Callable[[], bool] | None = None,
+) -> GateDecision | None:
+    """Evaluate gates for ``phase``. Returns the first firing gate, or
+    ``None`` when no gate fires.
+
+    Conflict resolution follows :data:`GATE_PRIORITY` — only the first
+    matching gate's phase is considered. Each gate maps to exactly one
+    phase via :data:`_PHASE_FOR_GATE`.
+    """
+    if not settings.any_gate_active:
+        return None
+    for gate_id in GATE_PRIORITY:
+        if _PHASE_FOR_GATE.get(gate_id) != phase:
+            continue
+        decision = _evaluate_single(
+            gate_id, settings,
+            confidence_band=confidence_band,
+            risk_class=risk_class,
+            memory_hits=memory_hits,
+        )
+        if decision is not None:
+            action = _resolve_action(settings, is_interactive)
+            return GateDecision(
+                gate_id=decision.gate_id,
+                phase=decision.phase,
+                reason=decision.reason,
+                action=action,
+            )
+    return None
+
+
+def _evaluate_single(
+    gate_id: str,
+    settings: DecisionEngineSettings,
+    *,
+    confidence_band: str | None,
+    risk_class: str | None,
+    memory_hits: int,
+) -> GateDecision | None:
+    if gate_id == "min_confidence" and settings.min_confidence != "off":
+        floor = _LEVEL_RANK[settings.min_confidence]
+        actual = _LEVEL_RANK.get((confidence_band or "").lower(), 0)
+        if actual < floor:
+            return GateDecision(
+                gate_id=gate_id, phase="plan", action="stop",
+                reason=(
+                    f"confidence_band={confidence_band!r} below floor "
+                    f"min_confidence={settings.min_confidence!r}"
+                ),
+            )
+    elif gate_id == "block_on_risk" and settings.block_on_risk != "off":
+        ceiling = _LEVEL_RANK[settings.block_on_risk]
+        actual = _LEVEL_RANK.get((risk_class or "").lower(), 0)
+        if actual >= ceiling:
+            return GateDecision(
+                gate_id=gate_id, phase="implement", action="stop",
+                reason=(
+                    f"risk_class={risk_class!r} at/above ceiling "
+                    f"block_on_risk={settings.block_on_risk!r}"
+                ),
+            )
+    elif gate_id == "require_memory_hits" and settings.require_memory_hits:
+        if memory_hits < 1:
+            return GateDecision(
+                gate_id=gate_id, phase="refine", action="stop",
+                reason=(
+                    f"memory_hits={memory_hits} but "
+                    "require_memory_hits=true (need >= 1)"
+                ),
+            )
+    return None
+
+
+def _resolve_action(
+    settings: DecisionEngineSettings,
+    is_interactive: Callable[[], bool] | None,
+) -> str:
+    """Map ``on_block`` to an action, applying the non-TTY fallback.
+
+    Non-interactive context = either ``is_interactive()`` returns
+    False, or the ``CI`` env var is truthy. ``on_block=ask`` collapses
+    to ``ask_timeout`` (consumer applies ``on_block_fallback``).
+    """
+    if settings.on_block in ("stop", "warn"):
+        return settings.on_block
+    interactive = (
+        is_interactive() if is_interactive is not None
+        else _default_is_interactive()
+    )
+    if interactive:
+        return "ask"
+    return "ask_timeout"
+
+
+def _default_is_interactive() -> bool:
+    if os.environ.get("CI", "").strip().lower() in ("1", "true", "yes"):
+        return False
+    try:
+        import sys
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+__all__ = [
+    "ALLOWED_KEYS",
+    "GATE_PRIORITY",
+    "DecisionEngineConfigError",
+    "DecisionEngineSettings",
+    "GateDecision",
+    "evaluate_gates",
+    "parse",
+]