agentic-dev-loop 0.12.1__tar.gz → 0.12.2__tar.gz

{agentic_dev_loop-0.12.1/src/agentic_dev_loop.egg-info → agentic_dev_loop-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 0.12.1
+Version: 0.12.2
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -32,6 +32,7 @@ Requires-Dist: openhands-tools~=1.17.0
 Requires-Dist: agent-client-protocol<1.0.0
 Requires-Dist: langgraph>=1.2
 Requires-Dist: langgraph-checkpoint-sqlite>=3.0
+Requires-Dist: msgpack>=1.0
 Requires-Dist: filelock>=4.2.1
 Requires-Dist: pyasn1>=0.6.5
 Requires-Dist: pypdf>=6.21.4
@@ -165,6 +166,27 @@ reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
 uv pip install --refresh "agentic-dev-loop==1.0.0a17"
 ```
 
+### Inspecting a run
+
+`agentic-dev-loop run-status <pipeline>` renders the latest run for a pipeline
+as a mermaid flowchart with the current step highlighted, plus a bullet
+summary, reading the run-state checkpoint database directly:
+
+```bash
+agentic-dev-loop run-status agentic-dev-loop/pipeline.yaml
+```
+
+To drive that from OpenCode, install the bundled `/run-status` command once into
+your global OpenCode commands directory:
+
+```bash
+agentic-dev-loop run-status --install
+```
+
+This copies the command wrapper to
+`${XDG_CONFIG_HOME:-~/.config}/opencode/commands/run-status.md`; from then on
+`/run-status` in any OpenCode workspace shells out to the subcommand above.
+
 On the first run the engine pulls the **digest-pinned** dev image
 (`ghcr.io/lukedawilson/agentic-dev-loop/dev`) and verifies its digest - the
 supply-chain check refuses to continue on a mismatch. If you're running
@@ -219,8 +241,9 @@ flowchart LR
    Its edits are untracked; only declared `produces:` files are hygiene-tracked.
 2. **test** - a mechanical command step runs the suite inside the sandbox.
    Exit 0 moves on; anything else rewinds to `dev` with the failing output.
-3. **review / qa** - verdict agents write artifacts whose `VERDICT:` lines route
-   the graph. `fail` rewinds to `dev` and consumes an attempt.
+3. **review / qa** - verdict agents finish by calling the `record_verdict`
+   tool; the validated tool call routes the graph. `fail` rewinds to `dev`
+   and consumes an attempt.
 4. **commit** - the single commit point fires only when all gates passed and
    the worktree was clean at start.
 5. **success** - committed; or **failure** when attempts are exhausted.
@@ -303,7 +326,7 @@ steps:
 | Key | Notes |
 | --- | --- |
 | `agent:` / `command:` / `action:` / `brief_inputs:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). `brief_inputs:` is a native brief step - see its row below. |
-| `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs structured-verdict routing. The verdict comes from a validated `record_verdict` tool call, never from prose; stale artifacts are deleted at each attempt start. |
 | `brief_inputs:` | The discriminator for a native brief step: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. There is no `agent:`, `produces:`, or `max_iterations:` - the prompt is engine-embedded, the capture file is `attempt-brief.md`, and the iteration cap is 12, all engine-owned. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as the step's task message, and regenerates the step only when those inputs change. `sections` is the ordered list of digest headings the brief must emit (default `[Repo rules digest, Unit scope digest, Environment facts, Open risks]`; non-empty and unique). `name` stays free-form, so multiple brief steps are allowed. |
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
@@ -626,13 +649,15 @@ and the `commit` step never commits it). `init` writes them; the layout is:
 
 Each `sdk_agents/<name>.agent.md` is a markdown prompt plus YAML frontmatter:
 `name` matches a step's `agent:` value; `tools` lists the tool names the step
-may use (`terminal` always; a repo can add more via extensions, e.g.
-`figma`).
+may use (`terminal` always; verdict steps also need `record_verdict`; a repo
+can add more via extensions, e.g. `figma`). A step configured with `verdicts:`
+whose agent file does not grant `record_verdict` fails at load, never at
+routing time.
 
 ```markdown
 ---
 name: review                 # matches a step's `agent:` value
-tools: [terminal]
+tools: [terminal, record_verdict]
 ---
 # Review Agent
 ## WORKFLOW                   # numbered steps
@@ -646,8 +671,8 @@ Three roles, three contracts:
 | Role | Verdict contract | Typical sandbox |
 | --- | --- | --- |
 | dev | none - the final response is captured as the `produces:` summary | rw mount, offline |
-| review | `VERDICT: APPROVED` / `VERDICT: NEEDS CHANGES` on the first content line | ro mount, offline |
-| qa | `VERDICT: PASS` / `VERDICT: FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
+| review | `record_verdict` with `APPROVED` / `NEEDS CHANGES`; the prose keeps the findings for humans | ro mount, offline |
+| qa | `record_verdict` with `PASS` / `FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
 
 The conventions that make a good agent file - each one below exists because
 an agent burned budget learning it mid-run:

{agentic_dev_loop-0.12.1 → agentic_dev_loop-0.12.2}/README.md

@@ -121,6 +121,27 @@ reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
 uv pip install --refresh "agentic-dev-loop==1.0.0a17"
 ```
 
+### Inspecting a run
+
+`agentic-dev-loop run-status <pipeline>` renders the latest run for a pipeline
+as a mermaid flowchart with the current step highlighted, plus a bullet
+summary, reading the run-state checkpoint database directly:
+
+```bash
+agentic-dev-loop run-status agentic-dev-loop/pipeline.yaml
+```
+
+To drive that from OpenCode, install the bundled `/run-status` command once into
+your global OpenCode commands directory:
+
+```bash
+agentic-dev-loop run-status --install
+```
+
+This copies the command wrapper to
+`${XDG_CONFIG_HOME:-~/.config}/opencode/commands/run-status.md`; from then on
+`/run-status` in any OpenCode workspace shells out to the subcommand above.
+
 On the first run the engine pulls the **digest-pinned** dev image
 (`ghcr.io/lukedawilson/agentic-dev-loop/dev`) and verifies its digest - the
 supply-chain check refuses to continue on a mismatch. If you're running
@@ -175,8 +196,9 @@ flowchart LR
    Its edits are untracked; only declared `produces:` files are hygiene-tracked.
 2. **test** - a mechanical command step runs the suite inside the sandbox.
    Exit 0 moves on; anything else rewinds to `dev` with the failing output.
-3. **review / qa** - verdict agents write artifacts whose `VERDICT:` lines route
-   the graph. `fail` rewinds to `dev` and consumes an attempt.
+3. **review / qa** - verdict agents finish by calling the `record_verdict`
+   tool; the validated tool call routes the graph. `fail` rewinds to `dev`
+   and consumes an attempt.
 4. **commit** - the single commit point fires only when all gates passed and
    the worktree was clean at start.
 5. **success** - committed; or **failure** when attempts are exhausted.
@@ -259,7 +281,7 @@ steps:
 | Key | Notes |
 | --- | --- |
 | `agent:` / `command:` / `action:` / `brief_inputs:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). `brief_inputs:` is a native brief step - see its row below. |
-| `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs structured-verdict routing. The verdict comes from a validated `record_verdict` tool call, never from prose; stale artifacts are deleted at each attempt start. |
 | `brief_inputs:` | The discriminator for a native brief step: `{ include: [<paths/globs>], env_facts: [<strings>], sections: [<headings>] }`. There is no `agent:`, `produces:`, or `max_iterations:` - the prompt is engine-embedded, the capture file is `attempt-brief.md`, and the iteration cap is 12, all engine-owned. The engine resolves the include list against the workspace, passes the resolved docs + include contents + env facts as the step's task message, and regenerates the step only when those inputs change. `sections` is the ordered list of digest headings the brief must emit (default `[Repo rules digest, Unit scope digest, Environment facts, Open risks]`; non-empty and unique). `name` stays free-form, so multiple brief steps are allowed. |
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
@@ -582,13 +604,15 @@ and the `commit` step never commits it). `init` writes them; the layout is:
 
 Each `sdk_agents/<name>.agent.md` is a markdown prompt plus YAML frontmatter:
 `name` matches a step's `agent:` value; `tools` lists the tool names the step
-may use (`terminal` always; a repo can add more via extensions, e.g.
-`figma`).
+may use (`terminal` always; verdict steps also need `record_verdict`; a repo
+can add more via extensions, e.g. `figma`). A step configured with `verdicts:`
+whose agent file does not grant `record_verdict` fails at load, never at
+routing time.
 
 ```markdown
 ---
 name: review                 # matches a step's `agent:` value
-tools: [terminal]
+tools: [terminal, record_verdict]
 ---
 # Review Agent
 ## WORKFLOW                   # numbered steps
@@ -602,8 +626,8 @@ Three roles, three contracts:
 | Role | Verdict contract | Typical sandbox |
 | --- | --- | --- |
 | dev | none - the final response is captured as the `produces:` summary | rw mount, offline |
-| review | `VERDICT: APPROVED` / `VERDICT: NEEDS CHANGES` on the first content line | ro mount, offline |
-| qa | `VERDICT: PASS` / `VERDICT: FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
+| review | `record_verdict` with `APPROVED` / `NEEDS CHANGES`; the prose keeps the findings for humans | ro mount, offline |
+| qa | `record_verdict` with `PASS` / `FAIL`; map `unverifiable: UNVERIFIABLE` if you want a third way | shaped by the repo: rw + network + `class: browser` when it boots servers and drives a browser (the consumer repo); ro + offline when it probes the CLI only (this repo) |
 
 The conventions that make a good agent file - each one below exists because
 an agent burned budget learning it mid-run:

{agentic_dev_loop-0.12.1 → agentic_dev_loop-0.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "0.12.1"
+version = "0.12.2"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -43,6 +43,9 @@ dependencies = [
     "agent-client-protocol<1.0.0",
     "langgraph>=1.2",
     "langgraph-checkpoint-sqlite>=3.0",
+    # msgpack is a transitive dep (langgraph-checkpoint-sqlite), but the
+    # run-status subcommand decodes checkpoints directly, so pin it explicitly.
+    "msgpack>=1.0",
     # filelock is a transitive dep (openhands-sdk, litellm, virtualenv).
     # 3.32.7 carries CVE-2026-112907/-112913/-112940 (fixed in 4.2.1); pin a
     # floor so the restore step's pip-audit stays green.

agentic_dev_loop-0.12.2/src/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-0.12.1 → agentic_dev_loop-0.12.2}/src/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-0.12.1 → agentic_dev_loop-0.12.2}/src/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-0.12.1 → agentic_dev_loop-0.12.2}/src/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-0.12.1 → agentic_dev_loop-0.12.2}/src/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-0.12.2/src/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-0.12.1 → agentic_dev_loop-0.12.2}/src/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-0.12.1 → agentic_dev_loop-0.12.2}/src/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)