froid-loop 0.11.1__py3-none-any.whl

froid_loop/plugins/__init__.py

@@ -0,0 +1,64 @@
+"""froid-loop plugin system.
+
+A first-class, general extension layer for the orchestrator: a plugin extends
+the froid_loop without modifying core, ranging from a data-only settings
+contribution to an in-process Python module. Distribution is folder-drop today
+(builtins under ``froid_loop/data/plugins/``, project-local under
+``.froid-loop/plugins/``) with a locked seam for entry-point packaging later.
+
+Phase 0 ships the foundation — manifest model, loader, trust gate, registry —
+wired into nothing yet. The hook bus, dynamic settings, and the engine migration
+build on this in later phases.
+"""
+
+from __future__ import annotations
+
+from .bus import HookBus
+from .context import VETO_ACTIONS, HookContext, Veto
+from .loader import (
+    ENTRY_POINT_GROUP,
+    USER_PLUGINS_REL,
+    discover,
+    get_plugin,
+    load_plugins,
+)
+from .model import (
+    API_VERSION,
+    SETTING_TYPES,
+    SUPPORTED_API,
+    HookSpec,
+    LoadedPlugin,
+    Plugin,
+    PluginError,
+    PluginManifest,
+    PythonSpec,
+    SettingSpec,
+)
+from .registry import PluginRegistry
+from .trust import PluginUntrusted, is_enabled, require_enabled
+
+__all__ = [
+    "API_VERSION",
+    "SUPPORTED_API",
+    "SETTING_TYPES",
+    "ENTRY_POINT_GROUP",
+    "USER_PLUGINS_REL",
+    "HookSpec",
+    "SettingSpec",
+    "PythonSpec",
+    "PluginManifest",
+    "Plugin",
+    "LoadedPlugin",
+    "PluginError",
+    "PluginUntrusted",
+    "PluginRegistry",
+    "HookBus",
+    "HookContext",
+    "Veto",
+    "VETO_ACTIONS",
+    "discover",
+    "load_plugins",
+    "get_plugin",
+    "is_enabled",
+    "require_enabled",
+]

froid_loop/plugins/bus.py

@@ -0,0 +1,259 @@
+"""HookBus: dispatch lifecycle stages to plugin hooks (declarative + python).
+
+The bus is the single fan-out point between the engine's stages and the loaded
+plugins. It enforces the two invariants that keep plugins safe:
+
+  * **No-op fast path.** ``active(stage)`` is an O(1) set membership test
+    precomputed at build time. A run with no plugin bound to a stage never
+    builds a context or calls ``emit`` — zero-plugin runs stay byte-identical.
+  * **Failure isolation.** Every hook — subprocess or in-process Python — is
+    wrapped. A python hook that raises is caught (``except Exception`` only;
+    ``RunStopped``/SIGTERM as ``BaseException`` propagate), journalled, and the
+    offending instance disabled for the rest of the run. A declarative hook that
+    errors (timeout, bad interpreter) fails open by default (the run survives);
+    ``fail_closed`` turns an error into a defer veto.
+
+Dispatch order is registry order (manifest ``priority`` then load order).
+Mutations pipeline — a later plugin sees an earlier plugin's edits. Vetoes are
+collected without short-circuit so order can never hide a severer objection;
+the context resolves the most-conservative one.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any, Callable
+
+from .context import MUTABLE_FIELDS, VETO_ACTIONS, HookContext, Veto
+from .model import LoadedPlugin
+from .registry import PluginRegistry
+
+# (returncode, combined-output) — the declarative-hook transport. Injectable so
+# tests can drive the bus without spawning real subprocesses.
+HookRunner = Callable[..., "tuple[int, str]"]
+
+
+class _HookError(Exception):
+    """A declarative hook could not run to completion (timeout / launch failure),
+    as distinct from a clean non-zero exit. Decides fail-open vs fail-closed."""
+
+
+def _run_subprocess(
+    cmd: str, *, cwd: str | None, env: dict[str, str], timeout: int
+) -> tuple[int, str]:
+    """Default declarative-hook transport: a shell command with the plugin env,
+    capturing output. shell=True is intentional (mirrors the deterministic verify
+    commands + the legacy engine ``*_cmd`` hooks).
+
+    Output decodes with ``errors="replace"`` (#383): a hook's output is arbitrary
+    operator-tool text whose bytes are not ours to constrain, and a strict decode
+    raised ``UnicodeDecodeError`` — a ``ValueError``, named by neither ``except``
+    arm below — which escaped ``_HookError``, the bus's designed
+    transport-failure channel, and crashed the run, losing even a passing hook's
+    exit code. Same fix and reasoning as ``verify.run_verify_commands`` (#378)."""
+    try:
+        proc = subprocess.run(  # nosec B602 - operator-authored plugin command
+            cmd,
+            shell=True,  # portability: operator-authored plugin command — sanctioned shell-out (see plan out-of-scope)
+            cwd=cwd,
+            env=env,
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise _HookError(f"timed out after {timeout}s") from e
+    except OSError as e:
+        raise _HookError(str(e)) from e
+    return proc.returncode, proc.stdout + proc.stderr
+
+
+def _instance_stages(instance: Any) -> set[str]:
+    """The stages an in-process plugin handles: every ``on_<stage>`` method it
+    defines. Lets ``active()`` stay precise — a python plugin only marks the
+    stages it actually implements, so the fast path holds for the rest."""
+    return {
+        name[3:]
+        for name in dir(instance)
+        if name.startswith("on_") and callable(getattr(instance, name, None))
+    }
+
+
+def _hook_env(ctx: HookContext, lp: LoadedPlugin) -> dict[str, str]:
+    """The ``FROID_LOOP_*`` environment a declarative hook reads — the run's
+    identity fields plus the plugin's resolved settings as ``FROID_LOOP_SETTING_*``.
+    Generalizes ``engine._run_engine_hook``'s env block to any plugin/stage."""
+    env = dict(os.environ)
+    fields = {
+        "FROID_LOOP_STAGE": ctx.stage,
+        "FROID_LOOP_RUN_ID": ctx.run_id,
+        "FROID_LOOP_RUN_DIR": ctx.run_dir or "",
+        "FROID_LOOP_REPO_ROOT": ctx.repo_root or "",
+        "FROID_LOOP_WORKTREE": ctx.worktree or ctx.repo_root or "",
+        "FROID_LOOP_STORY_KEY": ctx.story_key or "",
+        "FROID_LOOP_ROLE": ctx.role or "",
+        "FROID_LOOP_PHASE": ctx.phase or "",
+        "FROID_LOOP_BRANCH": ctx.branch or "",
+        "FROID_LOOP_AGENTS": ",".join(ctx.agents),
+        "FROID_LOOP_PLUGIN": lp.name,
+    }
+    env.update({k: v for k, v in fields.items() if v != ""})
+    # the plugin's *resolved* settings (defaults overlaid by [plugins.<name>]),
+    # not bare manifest defaults, so a declarative hook sees the operator's config.
+    for key, value in lp.settings.items():
+        env[f"FROID_LOOP_SETTING_{key.upper()}"] = str(value)
+    return env
+
+
+def _last_json(output: str) -> dict[str, Any] | None:
+    """A declarative hook may emit a JSON object on its last non-empty stdout
+    line to mutate the context. Anything else is treated as plain advisory log
+    text. Parse failures are ignored (the hook still ran)."""
+    for line in reversed(output.splitlines()):
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("{") and line.endswith("}"):
+            try:
+                payload = json.loads(line)
+            except json.JSONDecodeError:
+                return None
+            return payload if isinstance(payload, dict) else None
+        return None
+    return None
+
+
+class HookBus:
+    """Fan stage emits out to every loaded plugin. Build once per run from the
+    registry; share with the engine."""
+
+    def __init__(
+        self,
+        registry: PluginRegistry,
+        journal: Any = None,
+        *,
+        runner: HookRunner | None = None,
+    ):
+        self._registry = registry
+        self._journal = journal
+        self._runner = runner or _run_subprocess
+        # plugins disabled mid-run after an in-process hook raised (failure
+        # isolation): skipped for every subsequent stage.
+        self._disabled: set[str] = set()
+        # precompute the active-stage set for the O(1) fast path.
+        self._active: set[str] = set()
+        self._py_stages: dict[str, set[str]] = {}
+        for lp in registry.plugins():
+            for hook in lp.manifest.hooks:
+                self._active.add(hook.stage)
+            if lp.instance is not None:
+                stages = _instance_stages(lp.instance)
+                if stages:
+                    self._py_stages[lp.name] = stages
+                    self._active.update(stages)
+
+    # ----------------------------------------------------------- fast path
+
+    def active(self, stage: str) -> bool:
+        """True iff some loaded plugin binds ``stage``. The engine guards every
+        emit with this so a zero-plugin run does no work."""
+        return stage in self._active
+
+    def any_active(self) -> bool:
+        return bool(self._active)
+
+    def active_plugins(self) -> list[str]:
+        """Names of plugins that bind at least one stage — for a one-line
+        run-start journal entry when (and only when) plugins are live."""
+        out: list[str] = []
+        for lp in self._registry.plugins():
+            if lp.manifest.hooks or lp.name in self._py_stages:
+                out.append(lp.name)
+        return out
+
+    # -------------------------------------------------------------- dispatch
+
+    def emit(self, stage: str, ctx: HookContext) -> HookContext:
+        """Dispatch ``stage`` to every plugin bound to it, in registry order.
+        Returns the same context (carrying mutations + collected vetoes). A no-op
+        when no plugin binds the stage."""
+        if stage not in self._active:
+            return ctx
+        for lp in self._registry.plugins():
+            if lp.name in self._disabled:
+                continue
+            hook = lp.manifest.hook_for(stage)
+            if hook is not None:
+                self._dispatch_declarative(lp, hook, ctx)
+            if lp.instance is not None and stage in self._py_stages.get(lp.name, ()):
+                self._dispatch_python(lp, stage, ctx)
+        return ctx
+
+    def _dispatch_declarative(self, lp: LoadedPlugin, hook: Any, ctx: HookContext) -> None:
+        cmd = lp.manifest.render(hook.cmd)
+        env = _hook_env(ctx, lp)
+        cwd = ctx.worktree or ctx.repo_root or None
+        try:
+            rc, output = self._runner(cmd, cwd=cwd, env=env, timeout=hook.timeout_sec)
+        except _HookError as e:
+            self._log("plugin-hook-error", plugin=lp.name, stage=hook.stage, error=str(e))
+            if hook.blocking and hook.fail_closed:
+                ctx.add_veto(
+                    Veto("defer", f"plugin {lp.name!r} hook {hook.stage} errored: {e}", lp.name)
+                )
+            return
+        explicit_veto = self._apply_stdout(lp, ctx, output)
+        if not hook.blocking:
+            self._log("plugin-hook", plugin=lp.name, stage=hook.stage, rc=rc)
+            return
+        # blocking hook: a non-zero exit vetoes (defer) unless the hook already
+        # asked for a specific action via its stdout JSON.
+        if rc != 0 and not explicit_veto:
+            tail = output.strip()[-500:]
+            ctx.add_veto(
+                Veto("defer", f"plugin {lp.name!r} hook {hook.stage} exited {rc}: {tail}", lp.name)
+            )
+        self._log("plugin-hook", plugin=lp.name, stage=hook.stage, rc=rc, blocking=True)
+
+    def _apply_stdout(self, lp: LoadedPlugin, ctx: HookContext, output: str) -> bool:
+        """Merge a declarative hook's optional stdout-JSON: ``shared`` updates,
+        whitelisted ``mutate`` fields, and an explicit ``veto``. Returns whether
+        an explicit veto was supplied (so the exit-code path doesn't double-veto)."""
+        payload = _last_json(output)
+        if not payload:
+            return False
+        shared = payload.get("shared")
+        if isinstance(shared, dict):
+            ctx.shared.update(shared)
+        mutate = payload.get("mutate")
+        if isinstance(mutate, dict):
+            for key, value in mutate.items():
+                if key in MUTABLE_FIELDS:
+                    setattr(ctx, key, value)
+        veto = payload.get("veto")
+        if isinstance(veto, dict) and veto.get("action") in VETO_ACTIONS:
+            ctx.add_veto(Veto(veto["action"], str(veto.get("reason", "")), lp.name))
+            return True
+        return False
+
+    def _dispatch_python(self, lp: LoadedPlugin, stage: str, ctx: HookContext) -> None:
+        instance = lp.instance
+        ctx._current_plugin = lp.name
+        try:
+            instance.hook(stage, ctx)  # type: ignore[union-attr]
+        except Exception as e:  # isolate plugin failures; never BaseException
+            self._log("plugin-error", plugin=lp.name, stage=stage, error=f"{type(e).__name__}: {e}")
+            # disable the misbehaving instance for the rest of the run; its
+            # declarative hooks (if any) keep working — they are out-of-process.
+            self._disabled.add(lp.name)
+            if getattr(instance, "fail_closed", False):
+                ctx.add_veto(Veto("defer", f"plugin {lp.name!r} hook {stage} raised: {e}", lp.name))
+        finally:
+            ctx._current_plugin = ""
+
+    def _log(self, kind: str, **fields: Any) -> None:
+        if self._journal is not None:
+            self._journal.append(kind, **fields)

froid_loop/plugins/context.py

@@ -0,0 +1,319 @@
+"""HookContext + Veto: the per-stage object the hook bus hands every plugin.
+
+A ``HookContext`` is the shared run context for one lifecycle stage. It carries:
+
+  * **read-only** facts about where the run is (identity/git fields, the current
+    phase/role/attempt, a *copy* of the session result, etc.) — exposed as
+    properties with no setter so a plugin can observe but never rewrite history;
+  * a **per-stage mutable whitelist** (``proposed_prompt``/``proposed_env`` for a
+    session, ``proposed_commit_message`` for a commit, ``proposed_feedback``,
+    ``proposed_decision``) the engine reads back after dispatch and applies;
+  * a free-form ``shared`` dict that persists across stages (the engine backs it
+    with ``RunState.plugin_shared`` so it survives pause/resume).
+
+Veto is collect-then-resolve-most-conservative: every plugin that objects to a
+stage appends a ``Veto``; the bus never short-circuits, so load order can never
+hide a severer veto. ``resolved_veto()`` returns the single most-conservative one
+(``skip`` < ``defer`` < ``pause``). The engine maps it onto its *existing*
+control flow — there is no new abort path.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Type-only, exactly as `model.py` imports `HookContext`: the concrete
+    # verifier record type belongs in the signature, but importing it for real
+    # would be this package's SECOND core import (after manifest.py ->
+    # platform_util) and would point `plugins/` at the engine's I/O layer. There
+    # is no cycle today — `verify` reaches deferredwork/froidconfig/frontmatter/
+    # model/platform_util/policy/sprintstatus, none of which touch `plugins/` —
+    # so this is layering, not a workaround.
+    from ..verify import CommandResult
+
+# Veto actions, least to most conservative. `skip` drops the current unit and
+# continues the loop; `defer` routes through the engine's defer primitive; `pause`
+# escalates (raises RunPaused). Severity orders a multi-plugin resolve.
+VETO_ACTIONS = ("skip", "defer", "pause")
+_VETO_SEVERITY = {"skip": 1, "defer": 2, "pause": 3}
+
+# The mutable whitelist. A declarative hook's stdout `mutate` block and a python
+# hook may only assign these; everything else on the context is read-only.
+MUTABLE_FIELDS = frozenset(
+    {
+        "proposed_prompt",
+        "proposed_env",
+        "proposed_feedback",
+        "proposed_commit_message",
+        "proposed_decision",
+    }
+)
+
+
+@dataclass(frozen=True)
+class Veto:
+    """One plugin's objection to a stage. ``action`` is in VETO_ACTIONS;
+    ``plugin_id`` records who raised it for the journal + escalation message."""
+
+    action: str
+    reason: str = ""
+    plugin_id: str = "?"
+
+    def __post_init__(self) -> None:
+        if self.action not in VETO_ACTIONS:
+            raise ValueError(f"veto action must be one of {VETO_ACTIONS}: got {self.action!r}")
+
+
+class HookContext:
+    """Mutable run context for a single stage emit. The bus dispatches it to
+    every plugin bound to the stage; the engine applies the whitelisted
+    mutations + resolves the veto afterwards."""
+
+    def __init__(
+        self,
+        stage: str,
+        *,
+        run_id: str = "",
+        story_key: str | None = None,
+        epic: int | None = None,
+        phase: str | None = None,
+        attempt: int | None = None,
+        role: str | None = None,
+        worktree: str | None = None,
+        branch: str | None = None,
+        repo_root: str | None = None,
+        run_dir: str | None = None,
+        agents: tuple[str, ...] = (),
+        result_json: dict[str, Any] | None = None,
+        session_status: str | None = None,
+        verify_reason: str | None = None,
+        command_results: tuple[CommandResult, ...] = (),
+        verification_stage: str | None = None,
+        verification_sequence: int | None = None,
+        decision_action: str | None = None,
+        settings: dict[str, Any] | None = None,
+        shared: dict[str, Any] | None = None,
+        proposed_prompt: str | None = None,
+        proposed_env: dict[str, str] | None = None,
+        proposed_feedback: str | None = None,
+        proposed_commit_message: str | None = None,
+        proposed_decision: str | None = None,
+    ):
+        self._stage = stage
+        self._run_id = run_id
+        self._story_key = story_key
+        self._epic = epic
+        self._phase = phase
+        self._attempt = attempt
+        self._role = role
+        self._worktree = worktree
+        self._branch = branch
+        self._repo_root = repo_root
+        self._run_dir = run_dir
+        # the agent ids of the CLIs that run in this unit's worktree (dev + review),
+        # for a plugin that routes per-agent config (e.g. the engine's MCP routing).
+        self._agents = tuple(agents)
+        # A *deep* copy, and the depth is the whole point. `dict()` is shallow, so
+        # the nested `escalations` list stayed SHARED with the engine's own
+        # `result.result_json` — and both verify legs now emit `post_dev_verify`
+        # ahead of their `critical_escalations` audit (dev via `decide_dev`, fix
+        # at the reordered call in `_fix_phase`). An in-process plugin holding
+        # this context could therefore clear that list and erase a CRITICAL
+        # escalation out from under the audit, letting a verify-green repair
+        # proceed where the run owed a pause. Copying at all exists to make
+        # "plugins observe, cannot alter" true; shallow made it true only of the
+        # top level, which is not where escalations live.
+        self._result_json = copy.deepcopy(result_json) if result_json is not None else None
+        self._session_status = session_status
+        self._verify_reason = verify_reason
+        # Frozen command-result records with immutable strings.  This is an
+        # observe-only surface: plugins cannot replace the verifier outcome or
+        # modify this tuple, and the engine never reads it back for a decision.
+        self._command_results = tuple(command_results)
+        # The journal correlation keys for the pass those records came from —
+        # `verification_stage` is also the dev-vs-repair discriminator, which
+        # neither `stage` (both legs emit `post_dev_verify`) nor `phase` (both
+        # are DEV_VERIFY) nor `attempt` (one counter, shared) can supply.
+        self._verification_stage = verification_stage
+        self._verification_sequence = verification_sequence
+        self._decision_action = decision_action
+        self._settings = dict(settings) if settings is not None else {}
+        # free-form, persisted across stages (engine backs it with plugin_shared)
+        self.shared: dict[str, Any] = shared if shared is not None else {}
+        # mutable whitelist (plain public attributes; engine reads them back)
+        self.proposed_prompt = proposed_prompt
+        self.proposed_env = dict(proposed_env) if proposed_env is not None else None
+        self.proposed_feedback = proposed_feedback
+        self.proposed_commit_message = proposed_commit_message
+        self.proposed_decision = proposed_decision
+        # veto collection + the plugin currently dispatching (set by the bus so
+        # ctx.veto() can attribute the objection without the plugin passing a name)
+        self._vetoes: list[Veto] = []
+        self._current_plugin = ""
+
+    # ---------------------------------------------------------- read-only view
+
+    @property
+    def stage(self) -> str:
+        return self._stage
+
+    @property
+    def run_id(self) -> str:
+        return self._run_id
+
+    @property
+    def story_key(self) -> str | None:
+        return self._story_key
+
+    @property
+    def epic(self) -> int | None:
+        return self._epic
+
+    @property
+    def phase(self) -> str | None:
+        return self._phase
+
+    @property
+    def attempt(self) -> int | None:
+        return self._attempt
+
+    @property
+    def role(self) -> str | None:
+        return self._role
+
+    @property
+    def worktree(self) -> str | None:
+        return self._worktree
+
+    @property
+    def branch(self) -> str | None:
+        return self._branch
+
+    @property
+    def repo_root(self) -> str | None:
+        return self._repo_root
+
+    @property
+    def run_dir(self) -> str | None:
+        return self._run_dir
+
+    @property
+    def agents(self) -> tuple[str, ...]:
+        return self._agents
+
+    @property
+    def result_json(self) -> dict[str, Any] | None:
+        return self._result_json
+
+    @property
+    def session_status(self) -> str | None:
+        return self._session_status
+
+    @property
+    def verify_reason(self) -> str | None:
+        return self._verify_reason
+
+    @property
+    def command_results(self) -> tuple[CommandResult, ...]:
+        """The verifier ``CommandResult`` records from this attempt's verify pass,
+        in the order the commands ran. Read-only observability for
+        ``post_dev_verify``; nothing here feeds an engine decision.
+
+        Empty is ambiguous ON ITS OWN and must not be read as "the commands did
+        not run" — read it together with :attr:`verification_stage`, which is what
+        separates the cases:
+
+        * ``verification_stage is None`` — no verify pass ran at all. FOUR
+          distinct causes reach here and an empty tuple names none of them:
+
+          1. the session did not complete — ``session_status`` says so;
+          2. the dev-artifact gate already failed the attempt — ``verify_reason``;
+          3. on the repair leg, the deferral harvest short-circuited ahead of the
+             commands — also ``verify_reason``;
+          4. the engine variant suppressed the pass for this leg —
+             ``StoriesEngine`` skips it on a plan-halt leg, which has no
+             implementation to build, so nothing on the context marks this one
+             apart from a run that simply configured no commands.
+
+          ``session_status`` and ``verify_reason`` separate 1–3; this tuple
+          separates none of them, and does not try.
+        * ``verification_stage`` set with ``verification_sequence is None`` — the
+          pass DID run and executed nothing, because ``[verify] commands`` is
+          empty. No journal record exists for it either.
+        * ``verification_stage`` set with an int ``verification_sequence`` — those
+          commands ran, and each has a matching journal entry (see that property).
+        """
+        return self._command_results
+
+    @property
+    def verification_stage(self) -> str | None:
+        """Which leg produced :attr:`command_results` — ``"dev"`` for the initial
+        dev verification, ``"fix"`` for a feedback-driven repair one, ``None``
+        when no verify pass ran (see :attr:`command_results`).
+
+        This is the ONLY discriminator between the two. ``stage`` and ``phase``
+        are literally identical across them (``post_dev_verify`` from
+        ``Phase.DEV_VERIFY``), and ``attempt`` is one per-story counter the
+        repair leg CONTINUES rather than restarts — so its value orders the two
+        but never names either, and a human re-arm reuses the numbers outright.
+        """
+        return self._verification_stage
+
+    @property
+    def verification_sequence(self) -> int | None:
+        """This story's 1-based ordinal for the verify pass that produced
+        :attr:`command_results`, or ``None`` when the pass recorded nothing.
+
+        The join key back to the run journal: the ``verify-command-result``
+        entries with this ``story_key`` + ``verification_stage`` +
+        ``verification_sequence`` are exactly these results, one per record,
+        ordered by their ``command_index``. Monotonic per story across a
+        pause/resume — the sequence is durable, unlike ``attempt``, which a human
+        re-arm can reuse.
+        """
+        return self._verification_sequence
+
+    @property
+    def decision_action(self) -> str | None:
+        return self._decision_action
+
+    @property
+    def settings(self) -> dict[str, Any]:
+        return self._settings
+
+    # ------------------------------------------------------------ veto surface
+
+    def veto(self, action: str, reason: str = "") -> None:
+        """Plugin-facing: object to this stage. Attributed to the dispatching
+        plugin. Multiple plugins (and multiple calls) accumulate — the engine
+        resolves the most-conservative one."""
+        self._vetoes.append(
+            Veto(action=action, reason=reason, plugin_id=self._current_plugin or "?")
+        )
+
+    def add_veto(self, veto: Veto) -> None:
+        """Bus-facing: record a veto synthesized from a declarative hook's exit
+        code or stdout (the plugin id is already filled in)."""
+        self._vetoes.append(veto)
+
+    @property
+    def vetoed(self) -> bool:
+        return bool(self._vetoes)
+
+    @property
+    def vetoes(self) -> tuple[Veto, ...]:
+        return tuple(self._vetoes)
+
+    def resolved_veto(self) -> Veto | None:
+        """The single most-conservative veto (pause > defer > skip), or None.
+        Ties resolve to the first raised, so a deterministic plugin order gives a
+        deterministic outcome."""
+        if not self._vetoes:
+            return None
+        return max(self._vetoes, key=lambda v: _VETO_SEVERITY[v.action])
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"<HookContext {self._stage!r} story={self._story_key!r} vetoes={len(self._vetoes)}>"