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

{agentic_dev_loop-0.12.0/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.0
+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
@@ -60,6 +61,10 @@ checkpointed, and nothing gets committed until every gate passes.
   parsed from files, retries are bounded, nothing is best-effort.
 - **Sandboxed by default.** The agent's shell and every command step run inside
   an always-on Docker sandbox. There is no opt-out.
+- **Any OpenAI-compatible model, or your Copilot subscription.** Point
+  `llm.base_url` at any OpenAI-compatible endpoint with an API key, or log in
+  with `agentic-dev-loop copilot-login` and run on Copilot models. See
+  [LLM providers](#llm-providers).
 
 ---
 
@@ -94,6 +99,40 @@ Docker engine does:
 Native Windows (outside WSL2) is not supported: every Windows-specific code
 path and test was removed, and CI runs on Ubuntu only.
 
+## LLM providers
+
+Two ways to run the same pipeline. The engine speaks OpenAI-compatible wire
+format throughout, so every step, profile, and gate works identically on
+either provider style:
+
+| Provider | Setup |
+| --- | --- |
+| **Any OpenAI-compatible endpoint** | API key via `api_key_env` + `base_url` in the `llm:` block: DeepSeek, OpenAI, or any OpenAI-compatible API. Full reference: [pipeline.yaml reference](#pipelineyaml-reference). |
+| **GitHub Copilot subscription** | `agentic-dev-loop copilot-login` once, then point the `llm:` block at `https://api.githubcopilot.com` with the file-backed token. Probe-validated pins: `openai/gpt-5.6-luna` (pro) and `openai/gpt-4.1` (lite). Full config and known limitations: [Copilot subscription endpoint](#copilot-subscription-endpoint). |
+
+```yaml
+# OpenAI-compatible endpoint (any provider)
+llm:
+  model: openai/deepseek-v4-pro
+  base_url: https://api.deepseek.com
+  api_key_env: OPENAI_API_KEY
+```
+
+```yaml
+# GitHub Copilot subscription
+llm:
+  model: openai/gpt-5.6-luna        # pro; probe-validated pin
+  base_url: https://api.githubcopilot.com
+  api_key_secret:
+    from: file
+    key: ~/.agentic-dev-loop/auth/copilot.json
+    json_key: access_token
+  headers:
+    Copilot-Integration-Id: vscode-chat
+    Editor-Version: vscode/1.94.0
+    Openai-Intent: conversation-panel
+```
+
 ## Installation
 
 **Prerequisites**
@@ -102,7 +141,7 @@ path and test was removed, and CI runs on Ubuntu only.
 | --- | --- |
 | Python | ≥ 3.12 |
 | Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, run under WSL2: the repo must live on the WSL filesystem, not /mnt/c. |
-| LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set - a missing key fails fast, naming it. |
+| LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set - a missing key fails fast, naming it. Alternatively, `agentic-dev-loop copilot-login` authenticates a Copilot subscription (see [LLM providers](#llm-providers)). |
 
 ```bash
 pip install "agentic-dev-loop==1.0.0a17"
@@ -127,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
@@ -181,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.
@@ -265,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). |
@@ -588,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
@@ -608,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.0 → agentic_dev_loop-0.12.2}/README.md

@@ -16,6 +16,10 @@ checkpointed, and nothing gets committed until every gate passes.
   parsed from files, retries are bounded, nothing is best-effort.
 - **Sandboxed by default.** The agent's shell and every command step run inside
   an always-on Docker sandbox. There is no opt-out.
+- **Any OpenAI-compatible model, or your Copilot subscription.** Point
+  `llm.base_url` at any OpenAI-compatible endpoint with an API key, or log in
+  with `agentic-dev-loop copilot-login` and run on Copilot models. See
+  [LLM providers](#llm-providers).
 
 ---
 
@@ -50,6 +54,40 @@ Docker engine does:
 Native Windows (outside WSL2) is not supported: every Windows-specific code
 path and test was removed, and CI runs on Ubuntu only.
 
+## LLM providers
+
+Two ways to run the same pipeline. The engine speaks OpenAI-compatible wire
+format throughout, so every step, profile, and gate works identically on
+either provider style:
+
+| Provider | Setup |
+| --- | --- |
+| **Any OpenAI-compatible endpoint** | API key via `api_key_env` + `base_url` in the `llm:` block: DeepSeek, OpenAI, or any OpenAI-compatible API. Full reference: [pipeline.yaml reference](#pipelineyaml-reference). |
+| **GitHub Copilot subscription** | `agentic-dev-loop copilot-login` once, then point the `llm:` block at `https://api.githubcopilot.com` with the file-backed token. Probe-validated pins: `openai/gpt-5.6-luna` (pro) and `openai/gpt-4.1` (lite). Full config and known limitations: [Copilot subscription endpoint](#copilot-subscription-endpoint). |
+
+```yaml
+# OpenAI-compatible endpoint (any provider)
+llm:
+  model: openai/deepseek-v4-pro
+  base_url: https://api.deepseek.com
+  api_key_env: OPENAI_API_KEY
+```
+
+```yaml
+# GitHub Copilot subscription
+llm:
+  model: openai/gpt-5.6-luna        # pro; probe-validated pin
+  base_url: https://api.githubcopilot.com
+  api_key_secret:
+    from: file
+    key: ~/.agentic-dev-loop/auth/copilot.json
+    json_key: access_token
+  headers:
+    Copilot-Integration-Id: vscode-chat
+    Editor-Version: vscode/1.94.0
+    Openai-Intent: conversation-panel
+```
+
 ## Installation
 
 **Prerequisites**
@@ -58,7 +96,7 @@ path and test was removed, and CI runs on Ubuntu only.
 | --- | --- |
 | Python | ≥ 3.12 |
 | Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works - Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, run under WSL2: the repo must live on the WSL filesystem, not /mnt/c. |
-| LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set - a missing key fails fast, naming it. |
+| LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set - a missing key fails fast, naming it. Alternatively, `agentic-dev-loop copilot-login` authenticates a Copilot subscription (see [LLM providers](#llm-providers)). |
 
 ```bash
 pip install "agentic-dev-loop==1.0.0a17"
@@ -83,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
@@ -137,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.
@@ -221,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). |
@@ -544,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
@@ -564,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.0 → 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.0"
+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.0 → 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.0 → 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.0 → 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.0 → 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:])