agentic-dev-loop 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

agentic_dev_loop/core/failure.py

@@ -0,0 +1,21 @@
+"""Structural failure vocabulary for agent steps (unit-11).
+
+These classes are value objects: they name *why* an agent step failed
+structurally, never how the run should prose its way around the failure. A
+structural failure halts the step and the run - it never enters the retry
+path, because retrying re-runs the same refusal (FD-11, rule E-1).
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class FailureClass(str, enum.Enum):
+    """The named structural failure classes an agent step can raise."""
+
+    NO_ACTIONS = "no_actions"
+    NO_VERDICT_TOOL = "no_verdict_tool"
+    INVALID_VERDICT_VALUE = "invalid_verdict_value"
+    CONFLICTING_VERDICT = "conflicting_verdict"
+    WIRE_SHAPE = "wire_shape"

agentic_dev_loop/core/verdict.py

@@ -10,10 +10,17 @@ totality for arbitrary input (no crash, no silent routing).
 from __future__ import annotations
 
 import enum
+import json
 from dataclasses import dataclass
+from typing import Iterable
 
+from .failure import FailureClass
 from .results import Result
 
+# The structured verdict channel's tool name. The tool is registered by the
+# engine (engine/agents.py); the entity owns the argument contract.
+RECORD_VERDICT_TOOL = "record_verdict"
+
 # Leading markdown/list/quote decoration tolerated on a verdict line.
 _LEAD_DECOR = "#*_`>- "
 # Decoration tolerated between VERDICT and ':' and after the keyword.
@@ -33,6 +40,15 @@ class VerdictError(enum.Enum):
     AMBIGUOUS = "ambiguous"
 
 
+@dataclass(frozen=True)
+class VerdictChannelError:
+    """A structured verdict channel failure: the class plus the evidence a
+    report must name (the offending value, the configured set, the conflict)."""
+
+    code: FailureClass
+    detail: str
+
+
 @dataclass(frozen=True)
 class Verdict:
     """A parsed decision: `value` is the canonical outcome (e.g. 'pass').
@@ -64,6 +80,77 @@ class Verdict:
         return Result.err(VerdictError.NO_VERDICT)
 
 
+    @staticmethod
+    def from_events(
+        events: Iterable[object], verdicts: dict[str, str]
+    ) -> "Result[Verdict, VerdictChannelError]":
+        """Decode the verdict from record_verdict tool calls (FR-11.2).
+
+        The event stream is the only source: prose is never parsed here. Zero
+        calls is NO_VERDICT_TOOL; a value outside the configured set is
+        INVALID_VERDICT_VALUE; two different decisions are CONFLICTING_VERDICT
+        (fail fast, FD-Q1). Matching is case-insensitive because models vary
+        the casing of a configured keyword."""
+        values: list[str] = []
+        calls = 0
+        for event in events:
+            if getattr(event, "tool_name", None) != RECORD_VERDICT_TOOL:
+                continue
+            calls += 1
+            value = _verdict_argument(event)
+            if value is not None:
+                values.append(value)
+        if calls == 0:
+            return Result.err(VerdictChannelError(
+                FailureClass.NO_VERDICT_TOOL,
+                f"no {RECORD_VERDICT_TOOL} tool call in the event stream"))
+        lookup = {keyword.casefold(): value
+                  for keyword, value in verdicts.items()}
+        decided: dict[str, str] = {}
+        for value in values:
+            canonical = lookup.get(value.casefold())
+            if canonical is None:
+                configured = ", ".join(sorted(verdicts))
+                return Result.err(VerdictChannelError(
+                    FailureClass.INVALID_VERDICT_VALUE,
+                    f"{RECORD_VERDICT_TOOL} value {value!r} is not in the "
+                    f"configured set [{configured}]"))
+            decided[canonical] = value
+        if not decided:
+            return Result.err(VerdictChannelError(
+                FailureClass.INVALID_VERDICT_VALUE,
+                f"{RECORD_VERDICT_TOOL} call carried no readable verdict "
+                "argument"))
+        if len(decided) > 1:
+            return Result.err(VerdictChannelError(
+                FailureClass.CONFLICTING_VERDICT,
+                "conflicting verdicts: "
+                + ", ".join(sorted(repr(v) for v in decided.values()))))
+        return Result.ok(Verdict(value=next(iter(decided))))
+
+
+def _verdict_argument(event: object) -> str | None:
+    """The verdict argument carried by one RecordVerdictAction event.
+
+    Prefers the parsed action (the SDK's normal path); falls back to the raw
+    tool-call arguments JSON when the action was not parsed."""
+    action = getattr(event, "action", None)
+    value = getattr(action, "verdict", None)
+    if isinstance(value, str):
+        return value
+    tool_call = getattr(event, "tool_call", None)
+    arguments = getattr(tool_call, "arguments", None)
+    if not isinstance(arguments, str):
+        return None
+    try:
+        payload = json.loads(arguments)
+    except json.JSONDecodeError:
+        return None
+    if isinstance(payload, dict) and isinstance(payload.get("verdict"), str):
+        return payload["verdict"]
+    return None
+
+
 def parse_verdict(text: str, verdicts: dict[str, str]) -> str:
     """Route for a verdict artifact: the canonical decision value on a single
     clear decision, else ``retry``. Never raises - unclear verdicts retry."""

agentic_dev_loop/engine/actions.py

@@ -215,7 +215,8 @@ def commit(state: dict, params: dict) -> dict:
     if not state.get("commit_allowed", False):
         print(f"[{subject}] Skipping auto-commit - worktree was dirty at run "
               f"start; commit the constructed work manually.", flush=True)
-        return {}
+        return {"verified_state": {
+            "commit": "skipped: worktree dirty at run start"}}
     if "message" not in params:
         raise ValueError("commit action requires params.message "
                          "(a template rendered with {subject})")
@@ -235,10 +236,10 @@ def commit(state: dict, params: dict) -> dict:
         # permission problem) - its error is the diagnostic that matters.
         print(f"WARNING: [{subject}] auto-commit failed - git add: "
               f"{added.stderr.strip()}", file=sys.stderr, flush=True)
-        return {}
+        return {"verified_state": {"commit": "failed: add"}}
     if not _git(["status", "--porcelain"], cwd=cwd).stdout.strip():
         print(f"[{subject}] Nothing to commit.", flush=True)
-        return {}
+        return {"verified_state": {"commit": "nothing to commit"}}
     message = params["message"].format(subject=subject)
     result = _git(["-c", f"core.hooksPath={hooks}", "commit", "-m", message],
                   cwd=cwd)
@@ -247,7 +248,7 @@ def commit(state: dict, params: dict) -> dict:
         # not a pipeline failure.
         print(f"WARNING: [{subject}] auto-commit failed - commit manually.\n"
               f"{result.stderr.strip()}", file=sys.stderr, flush=True)
-        return {}
+        return {"verified_state": {"commit": "failed: commit"}}
     short = _git(["rev-parse", "--short", "HEAD"], cwd=cwd).stdout.strip()
     print(f"[{subject}] Committed constructed work as {short}.", flush=True)
-    return {}
+    return {"verified_state": {"commit": f"committed {short}"}}

agentic_dev_loop/engine/agents.py

@@ -10,13 +10,17 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from openhands.sdk import LLM
-from openhands.sdk.tool import ToolExecutor
+from openhands.sdk.tool import (Action, Observation, ToolAnnotations,
+                                ToolDefinition, ToolExecutor, register_tool)
+from pydantic import Field
 from openhands.tools.file_editor import FileEditorTool  # noqa: F401 - registers "file_editor"
 from openhands.tools.task_tracker import TaskTrackerTool  # noqa: F401 - registers "task_tracker"
 from openhands.tools.terminal import TerminalTool  # noqa: F401 - registers "terminal"
 
 from .forbidden import ForbiddenRule, match_forbidden_command
 from .brief_prompt import render_brief_prompt
+from agentic_dev_loop.core.verdict import RECORD_VERDICT_TOOL
+
 from .isolation import (SandboxError, SandboxExecutionRequest, command_argv,
                         resolve_sandbox_env)
 
@@ -32,7 +36,39 @@ if TYPE_CHECKING:
 BRIEF_AGENT_NAME = "4f1c9e2b-7a3d-4e5f-8b6c-0d1a2f3c4d5e"
 
 
-def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
+def check_required_tools(tools: list[str], required: tuple[str, ...],
+                         *, agent_name: str) -> None:
+    """Fail loudly when a step's contract needs a tool the agent file does not
+    grant (BR-1: the frontmatter list is the exact allowlist)."""
+    missing = [name for name in required if name not in tools]
+    if missing:
+        raise ValueError(
+            f"agent {agent_name!r} does not grant required tools "
+            f"{missing}; add them to its frontmatter 'tools:' allowlist")
+
+
+def validate_agent_contracts(cfg, agents_dir: Path | str) -> None:
+    """Load-time contract check (unit-11, B-2): a step configured with
+    ``verdicts:`` requires ``record_verdict`` in its agent's tool allowlist.
+
+    A missing agent file is left to ``load_agent`` (which fails fast naming
+    it); this check only inspects files that exist so graph construction stays
+    a pure config pass for fake-agent test harnesses."""
+    from openhands.sdk.subagent.schema import AgentDefinition
+
+    for step in cfg.steps:
+        if step.agent is None or step.verdicts is None:
+            continue
+        path = Path(agents_dir) / f"{step.agent}.agent.md"
+        if not path.is_file():
+            continue
+        agent_def = AgentDefinition.load(path)
+        check_required_tools(agent_def.tools, (RECORD_VERDICT_TOOL,),
+                             agent_name=step.agent)
+
+
+def load_agent(agents_dir: Path | str, name: str, llm: LLM,
+               required_tools: tuple[str, ...] = ()) -> "Agent":
     """Load `<agents_dir>/<name>.agent.md` and build the Agent via the SDK
     factory (frontmatter tool names resolved against the registry, unknown →
     ValueError; the markdown body is delivered as the system prompt suffix).
@@ -63,6 +99,7 @@ def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
         raise ValueError(
             f"Agent file {path} name {agent_def.name!r} does not match "
             f"filename {stem!r}")
+    check_required_tools(agent_def.tools, required_tools, agent_name=name)
     return agent_definition_to_factory(agent_def)(llm)
 
 
@@ -206,3 +243,58 @@ def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None]
                 allowlist=allowlist))
 
     register_tool("terminal", factory)
+
+
+class RecordVerdictAction(Action):
+    """The structured verdict channel's input (unit-11, FR-11.2)."""
+
+    verdict: str = Field(
+        description=(
+            "The verdict keyword for this step, exactly as configured in the "
+            "pipeline's `verdicts:` map (for example APPROVED or NEEDS "
+            "CHANGES)."))
+
+
+class RecordVerdictObservation(Observation):
+    """A visible acknowledgement: the wire invariant (D-3) requires the tool
+    result to reach the model, so this is never empty."""
+
+
+class RecordVerdictExecutor(ToolExecutor):
+    def __call__(self, action: RecordVerdictAction,
+                 conversation=None) -> RecordVerdictObservation:
+        return RecordVerdictObservation.from_text(
+            f"recorded verdict: {action.verdict}")
+
+
+class RecordVerdictTool(
+        ToolDefinition[RecordVerdictAction, RecordVerdictObservation]):
+    """Registers `record_verdict`; validation against the step's configured
+    verdict set happens in `Verdict.from_events`, never in the tool schema."""
+
+    @classmethod
+    def create(cls, conv_state=None, **params):
+        if params:
+            raise ValueError("RecordVerdictTool does not accept parameters")
+        return [
+            cls(
+                action_type=RecordVerdictAction,
+                observation_type=RecordVerdictObservation,
+                description=(
+                    "Record this step's verdict. Call exactly once when your "
+                    "work is complete, passing the configured verdict keyword. "
+                    "Never state the verdict only in prose: the pipeline reads "
+                    "this tool call, not your final message."),
+                executor=RecordVerdictExecutor(),
+                annotations=ToolAnnotations(
+                    title=RECORD_VERDICT_TOOL,
+                    readOnlyHint=True,
+                    destructiveHint=False,
+                    idempotentHint=True,
+                    openWorldHint=False,
+                ),
+            )
+        ]
+
+
+register_tool(RECORD_VERDICT_TOOL, RecordVerdictTool)

agentic_dev_loop/engine/cli.py

@@ -226,6 +226,9 @@ def main(argv: list[str] | None = None, *, keep_alive: bool = True) -> int:
         return _run_copilot_login(argv[1:])
     if argv and argv[0] == "copilot-models":
         return _run_copilot_models(argv[1:])
+    if argv and argv[0] == "run-status":
+        from .run_status import _run_status
+        return _run_status(argv[1:])
     if argv and argv[0] == "init":
         from .onboarding.init import run_init
         return run_init(argv[1:])

agentic_dev_loop/engine/completion.py

@@ -0,0 +1,48 @@
+"""Completion classification from the conversation event stream (unit-11).
+
+Completion is a structural fact: an agent step completes only when it took at
+least one verifiable action. The OpenHands SDK marks a content-bearing turn
+with zero tool calls as FINISHED, which is how tool-less narration used to
+read as a clean pass (planning-docs/059). This module reclassifies that shape
+as ``FailureClass.NO_ACTIONS``; truncation semantics stay with ``stages.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from openhands.sdk.event.llm_convertible.action import ActionEvent
+
+from agentic_dev_loop.core.failure import FailureClass
+
+
+def count_actions(events: Iterable[object]) -> int:
+    """The number of tool calls in the event stream.
+
+    Each tool call emits exactly one ``ActionEvent`` (a ``FinishAction``
+    included: the SDK's done signal is itself a tool call)."""
+    return sum(1 for event in events if isinstance(event, ActionEvent))
+
+
+def classify_completion(events: Iterable[object], *,
+                        finished: bool) -> FailureClass | None:
+    """Classify a completed conversation, or return None when it took actions.
+
+    A FINISHED conversation with zero ActionEvents is NO_ACTIONS. A truncated
+    conversation keeps the existing truncation path: ``finished`` is False and
+    classification is left to the caller."""
+    events = list(events)
+    if count_actions(events) > 0:
+        return None
+    if not finished:
+        return None
+    return FailureClass.NO_ACTIONS
+
+
+def completion_evidence(events: Iterable[object]) -> str:
+    """The classifier evidence recorded in a structural failure report."""
+    events = list(events)
+    actions = [e for e in events if isinstance(e, ActionEvent)]
+    tools = ", ".join(sorted({getattr(e, "tool_name", "?") for e in actions}))
+    return (f"event_count={len(events)} action_events={len(actions)} "
+            f"tool_calls=[{tools}]")

agentic_dev_loop/engine/dryrun.py

@@ -13,6 +13,8 @@ from __future__ import annotations
 from pathlib import Path
 
 from agentic_dev_loop.core.config import PipelineConfig, StepConfig, load_config
+from agentic_dev_loop.core.verdict import RECORD_VERDICT_TOOL
+from .agents import check_required_tools
 from .hostboundary import check_orchestrator_install, check_tooling_integrity
 from .loaders import resolve_docs
 from .isolation import (isolation_state_dir, resolve_effective_profile,
@@ -30,12 +32,18 @@ def _validate_agents(cfg: PipelineConfig, agents_dir: Path) -> None:
     The brief prompt is engine-embedded (046), so a native ``brief_inputs:``
     step (kind 'brief') has `agent is None` and is exempt from the agents_dir
     lookup - it never reads a vendored file."""
+    from openhands.sdk.subagent.schema import AgentDefinition
+
     for step in cfg.steps:
         if step.agent is None:
             continue
         path = agents_dir / f"{step.agent}.agent.md"
         if not path.is_file():
             raise FileNotFoundError(f"Agent file not found: {path}")
+        if step.verdicts is not None:
+            agent_def = AgentDefinition.load(path)
+            check_required_tools(agent_def.tools, (RECORD_VERDICT_TOOL,),
+                                 agent_name=step.agent)
 
 
 def _validate_actions(cfg: PipelineConfig, registry: Registry) -> None:

agentic_dev_loop/engine/graph.py

@@ -19,6 +19,7 @@ from langgraph.graph import END, START, StateGraph
 
 from agentic_dev_loop import viz
 from .actions import git_worktree_clean, kill_listeners_on_port
+from .agents import validate_agent_contracts
 from .allowlist import resolve_engine_allowlist
 from agentic_dev_loop.core.config import load_config
 from .hostboundary import (check_orchestrator_install,
@@ -68,6 +69,9 @@ class LoopState(TypedDict):
     state_dir: str                     # resolved pipeline state dir (for the commit action)
     tooling_paths: list[str]          # workspace-relative paths the commit never sweeps
     step_verdicts: dict[str, str | None]  # per-step pass/fail/None(unclear)
+    failure_class: str | None          # structural failure class (unit-11)
+    mechanical_notes: Annotated[list[str], operator.add]  # command/action output
+    verified_state: Annotated[dict[str, str], _merge_artifacts]  # engine-verified facts
     retry_target: str | None           # where the bump node loops back to
     thread_id: str
     brief_hashes: Annotated[dict[str, str], _merge_artifacts]  # step name -> input hash (033)
@@ -78,6 +82,7 @@ def build_graph(runtime: Runtime, checkpointer=None):
     """Compile the pipeline's state graph: one node per step (agent, command,
     or action), plus the bump retry node and the success terminal. Unknown
     action names fail here, at build time, not mid-run."""
+    validate_agent_contracts(runtime.cfg, runtime.agents_dir)
     known_actions = (set(runtime.registry.actions)
                      | set(runtime.registry.sandbox_actions))
     for step in runtime.cfg.steps:
@@ -235,6 +240,9 @@ def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
             "state_dir": str(state_dir),
             "tooling_paths": tooling_paths,
             "step_verdicts": {},
+            "failure_class": None,
+            "mechanical_notes": [],
+            "verified_state": {},
             "retry_target": None,
             "thread_id": thread_id,
             "brief_hashes": {},
@@ -362,6 +370,9 @@ def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
                 f"{final.get('failed_step', 'unknown')!r}; see "
                 f"{state_dir}/last-error.md",
                 flush=True)
+            if final.get("failure_class"):
+                print(f"[{final['subject']}] structural failure class: "
+                      f"{final['failure_class']}", flush=True)
         else:
             print(f"[{final['subject']}] FAILED after {final['attempt']} "
                   f"attempt(s).", flush=True)

agentic_dev_loop/engine/llm.py

@@ -6,7 +6,11 @@ import os
 from openhands.sdk import LLM
 
 from agentic_dev_loop.core.config import LlmConfig
-from agentic_dev_loop.engine.provider_wire import adapter_for
+from agentic_dev_loop.engine.provider_wire import (adapter_for,
+                                                   merge_choices,
+                                                   validate_response_shape,
+                                                   validate_string_tool_results,
+                                                   validate_tool_call_pairing)
 from agentic_dev_loop.engine.secrets import (
     SecretResolutionError, resolve_secret_spec)
 
@@ -62,6 +66,8 @@ if not getattr(_ORIGINAL_FORMAT_MESSAGES, "_agentic_dev_loop_reasoning_repair",
                 d.pop("reasoning_content", None)
             if any(getattr(m, "reasoning_content", None) for m in messages):
                 raise _reasoning_stripped_error(self)
+            validate_string_tool_results(
+                messages, out, forced=bool(self.force_string_serializer))
             return out
 
         last = None
@@ -79,12 +85,62 @@ if not getattr(_ORIGINAL_FORMAT_MESSAGES, "_agentic_dev_loop_reasoning_repair",
                     d["reasoning_content"] = last
             elif rc:
                 d["reasoning_content"] = rc
+        validate_string_tool_results(
+            messages, out, forced=bool(self.force_string_serializer))
         return out
 
     _config_gated_reasoning_serializer._agentic_dev_loop_reasoning_repair = True
     LLM.format_messages_for_llm = _config_gated_reasoning_serializer
 
 
+_ORIGINAL_COMPLETION = LLM.completion
+_ORIGINAL_RESPONSES = LLM.responses
+
+
+def _wire_checked_completion(self, messages, *args, **kwargs):
+    """D-2 before the request, D-1 on the surfaced response (chat path)."""
+    validate_tool_call_pairing(messages)
+    response = _ORIGINAL_COMPLETION(self, messages, *args, **kwargs)
+    validate_response_shape(response)
+    return response
+
+
+def _wire_checked_responses(self, messages, *args, **kwargs):
+    """D-2 before the request; D-1 where the Responses shape exposes it."""
+    validate_tool_call_pairing(messages)
+    response = _ORIGINAL_RESPONSES(self, messages, *args, **kwargs)
+    validate_response_shape(response)
+    return response
+
+
+if not getattr(LLM.completion, "_agentic_dev_loop_wire_checked", False):
+    _wire_checked_completion._agentic_dev_loop_wire_checked = True
+    LLM.completion = _wire_checked_completion
+
+if not getattr(LLM.responses, "_agentic_dev_loop_wire_checked", False):
+    _wire_checked_responses._agentic_dev_loop_wire_checked = True
+    LLM.responses = _wire_checked_responses
+
+
+# The Copilot gateway splits Anthropic-model turns across multiple choices
+# (narration-only choice + one choice per tool call); the SDK reads only
+# choices[0] inside LLM.completion, so the merge must happen BEFORE that read,
+# at the _transport_call boundary where the litellm ModelResponse is built.
+_ORIGINAL_TRANSPORT_CALL = LLM._transport_call
+
+
+def _merge_checked_transport_call(self, **kwargs):
+    ret = _ORIGINAL_TRANSPORT_CALL(self, **kwargs)
+    if getattr(self, "_agentic_dev_loop_merge_choices", False):
+        merge_choices(ret)
+    return ret
+
+
+if not getattr(LLM._transport_call, "_agentic_dev_loop_merge_checked", False):
+    _merge_checked_transport_call._agentic_dev_loop_merge_checked = True
+    LLM._transport_call = _merge_checked_transport_call
+
+
 def resolve_api_key(cfg: LlmConfig, environ=None) -> str:
     """Resolve the configured host-side key: the existing env mechanism, or
     the file-backed secret spec. Missing values fail fast naming the fix."""
@@ -120,4 +176,6 @@ def build_llm(cfg: LlmConfig, reasoning_effort: str | None = None) -> LLM:
         force_string_serializer=adapter.force_string_serializer if adapter else None,
     )
     llm._agentic_dev_loop_reasoning_effort = effort
+    llm._agentic_dev_loop_merge_choices = (
+        adapter.merge_choices if adapter else False)
     return llm

agentic_dev_loop/engine/onboarding/templates/qa.agent.md

@@ -1,6 +1,6 @@
 ---
 name: qa
-tools: [terminal]
+tools: [terminal, record_verdict]
 ---
 # QA Agent
 
@@ -52,10 +52,11 @@ QA section marks "QA executes first-hand".
 4. Probe only the uncovered surface per the rules below, then stop.
 5. State your report in your **final response** - the pipeline captures it
    as your qa report. Give every acceptance check a status of `PASS`,
-   `FAIL`, `UNVERIFIABLE`, or `ENV`, then the verdict. If any check is
-   `UNVERIFIABLE`, add an `## UNVERIFIABLE` section listing each skipped
-   check and the blocking reason. If the verification environment itself is
-   broken, emit `VERDICT: ENV` and add an `## ENV` section (see ENV below).
+   `FAIL`, `UNVERIFIABLE`, or `ENV`, then call `record_verdict` with your verdict
+   (PASS, FAIL, UNVERIFIABLE, or ENV). If any check is `UNVERIFIABLE`, add
+   an `## UNVERIFIABLE` section listing each skipped check and the blocking
+   reason. If the verification environment itself is
+   broken, call `record_verdict(verdict="ENV")` and add an `## ENV` section (see ENV below).
 
 ## ENV
 
@@ -76,7 +77,7 @@ than the product code, the verdict is `ENV`.
 each environmental blocker with its evidence (command, output, expected).
 
 **Anti-livelock rule.** If the same environmental blocker persists across
-2 attempts, emit `VERDICT: ENV` instead of further workarounds. Do not burn
+2 attempts, call `record_verdict(verdict="ENV")` instead of further workarounds. Do not burn
 turns building synthetic fixtures or debugging the harness.
 
 ## PROBE-PLAN RULES
@@ -167,15 +168,21 @@ turns building synthetic fixtures or debugging the harness.
 
 ## OUTPUT
 
-Start your final response with a `VERDICT:` line on its own line, then the
-check table and findings. Each check row carries either a probe result or a
-citation (`covered by <test>` or `gate record`). The verdict rules are:
-
-- `VERDICT: PASS` when every reachable acceptance check passes. Checks that
-  could not be verified are recorded as `UNVERIFIABLE` in the report, not
-  treated as failures.
-- `VERDICT: UNVERIFIABLE` when the acceptance checks cannot be touched at
-  all, or none of them can be verified in this sandbox.
-- `VERDICT: ENV` when the verification environment itself is broken mid-run
-  and PASS/FAIL/UNVERIFIABLE cannot be determined (see ENV above).
-- `VERDICT: FAIL` on any genuine defect, as always.
+Call `record_verdict` exactly once when your report is ready, then write the
+check table and findings in your final response for humans. Each check row
+carries either a probe result or a citation (`covered by <test>` or `gate
+record`). The verdict values are:
+
+- `PASS` when every reachable acceptance check passes. Checks that could
+  not be verified are recorded as `UNVERIFIABLE` in the report, not treated
+  as failures.
+- `UNVERIFIABLE` when the acceptance checks cannot be touched at all, none
+  of them can be verified in this sandbox, or the plan's headline feature
+  cannot be verified here. Name the headline feature and its blocking reason
+  in the `## UNVERIFIABLE` section.
+- `ENV` when the verification environment itself is broken mid-run and
+  PASS/FAIL/UNVERIFIABLE cannot be determined (see ENV above).
+- `FAIL` on any genuine defect, as always.
+
+The tool call is the routing channel; the prose no longer carries a
+`VERDICT:` line.

agentic_dev_loop/engine/onboarding/templates/review.agent.md

@@ -1,6 +1,6 @@
 ---
 name: review
-tools: [terminal]
+tools: [terminal, record_verdict]
 ---
 # Review Agent
 
@@ -17,16 +17,12 @@ repo's README.
      artifact hygiene, single gated commit point, fail-fast config)?
    - Do the tests pin the new behavior without touching the network
      (FakeAgents in tests/conftest.py is the only permitted stub)?
-4. State your findings in your **final response** - the pipeline captures it
-   as your review. Include the verdict line:
-
-VERDICT: APPROVED
-
-or
-
-VERDICT: NEEDS CHANGES
-
-List specific issues with file paths and suggestions.
+4. Call the `record_verdict` tool exactly once with `APPROVED` or
+   `NEEDS CHANGES` when your review is complete. The tool call is the routing
+   channel; prose is not.
+5. State your findings in your **final response** - the pipeline captures it
+   as your review for humans. List specific issues with file paths and
+   suggestions. Do not put a `VERDICT:` line in the prose.
 
 ## RULES
 
@@ -48,6 +44,7 @@ List specific issues with file paths and suggestions.
 
 ## OUTPUT
 
-Start your final response with `VERDICT: APPROVED` or `VERDICT: NEEDS
-CHANGES` on its own line - no markdown decoration (no `**`, no `##` heading);
-the pipeline parses that response mechanically.
+Call `record_verdict` with `verdict="APPROVED"` or `verdict="NEEDS CHANGES"`
+as soon as your review is complete. The pipeline reads that tool call and
+nothing else. Your final response carries the findings for humans; there is
+no `VERDICT:` line contract.