agent-devkit 0.1.0 → 0.1.6

package/runtime/cli/aikit/control_router.py

@@ -0,0 +1,298 @@
+"""Natural-language control routing for tools, integrations, skills and LLMs."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.decision_store import forget_decision, list_decisions, reset_decisions, set_decision
+from cli.aikit.llm import BACKENDS
+from cli.aikit.providers import load_providers
+from cli.aikit.toolchain import load_toolchain
+
+
+CATEGORY_ALIASES: dict[str, tuple[str, ...]] = {
+    "tools": ("tool", "tools", "ferramenta", "ferramentas", "cli", "clis", "toolchain"),
+    "integrations": ("integration", "integrations", "integracao", "integracoes", "integração", "integrações", "provider", "providers"),
+    "skills": ("skill", "skills", "habilidade", "habilidades"),
+    "llms": ("llm", "llms", "modelo", "modelos", "backend", "backends"),
+}
+LIST_MARKERS = ("mostre", "mostrar", "liste", "listar", "ver", "exiba", "exibir")
+ENABLE_MARKERS = ("reative", "ative", "habilite", "enable")
+DISABLE_MARKERS = ("desative", "desabilite", "disable", "bloqueie", "bloquear")
+FORGET_MARKERS = ("esqueca", "esqueça", "remova", "remover", "limpe", "limpar", "delete", "apague", "apagar")
+DECISION_MARKERS = ("decisao", "decisão", "decisoes", "decisões", "decision", "decisions", "bloqueio")
+TOKEN_PATTERN = re.compile(r"[a-z0-9._:-]+")
+SKILL_ROW_PATTERN = re.compile(r"^\|\s*`([^`]+)`\s*\|")
+
+
+def dispatch_natural_control_prompt(root: Path, normalized_prompt: str) -> dict[str, Any] | None:
+    action = detect_action(normalized_prompt)
+    category = detect_category(normalized_prompt)
+    if action == "list":
+        return list_payload(root, category=category)
+    if action == "reset" and category:
+        result = reset_decisions(category)
+        return control_payload(
+            status="ok",
+            response=f"Decisoes de {category} foram resetadas.",
+            result={"action": "reset", "category": category, "decision": result},
+        )
+    if action not in {"enable", "disable", "forget"}:
+        return None
+
+    index = build_control_index(root)
+    matches = resolve_target(index, normalized_prompt, category=category)
+    if not matches:
+        return needs_input_unknown(root, normalized_prompt, category=category)
+    if len(matches) > 1:
+        return needs_input_ambiguous(matches, normalized_prompt, category=category)
+
+    target = matches[0]
+    if action == "forget":
+        decision = forget_decision(str(target["category"]), str(target["id"]))
+        return control_payload(
+            status="ok",
+            response=f"Decisao local sobre {target['id']} removida.",
+            result={"action": "forget", "category": target["category"], "id": target["id"], "removed": decision.get("removed"), "decision": decision},
+        )
+
+    state = "enabled" if action == "enable" else "disabled_by_user"
+    decision = set_decision(str(target["category"]), str(target["id"]), state, reason=f"natural prompt: {action}")
+    return control_payload(
+        status="ok",
+        response=f"{target['id']} foi {'ativado' if state == 'enabled' else 'desativado'} para {target['category']}.",
+        result={"action": action, "category": target["category"], "id": target["id"], "state": state, "decision": decision.get("item")},
+    )
+
+
+def plan_natural_control_prompt(root: Path, normalized_prompt: str) -> dict[str, Any] | None:
+    action = detect_action(normalized_prompt)
+    category = detect_category(normalized_prompt)
+    if action == "list":
+        payload = list_payload(root, category=category)
+        payload["dry_run"] = True
+        return payload
+    if action == "reset" and category:
+        return control_payload(
+            status="planned",
+            response=f"Dry-run: decisoes de {category} seriam resetadas.",
+            result={"action": "reset", "category": category},
+        ) | {"dry_run": True, "ok": True}
+    if action not in {"enable", "disable", "forget"}:
+        return None
+    index = build_control_index(root)
+    matches = resolve_target(index, normalized_prompt, category=category)
+    if not matches:
+        payload = needs_input_unknown(root, normalized_prompt, category=category)
+        payload["dry_run"] = True
+        return payload
+    if len(matches) > 1:
+        payload = needs_input_ambiguous(matches, normalized_prompt, category=category)
+        payload["dry_run"] = True
+        return payload
+    target = matches[0]
+    state = "enabled" if action == "enable" else "disabled_by_user"
+    return control_payload(
+        status="planned",
+        response=f"Dry-run: {target['id']} seria {'ativado' if action == 'enable' else 'desativado' if action == 'disable' else 'removido das decisoes'} para {target['category']}.",
+        result={"action": action, "category": target["category"], "id": target["id"], "state": state if action != "forget" else None},
+    ) | {"dry_run": True, "ok": True}
+
+
+def build_control_index(root: Path) -> dict[str, list[dict[str, Any]]]:
+    return {
+        "tools": tool_items(root),
+        "integrations": integration_items(root),
+        "skills": skill_items(root),
+        "llms": llm_items(),
+    }
+
+
+def tool_items(root: Path) -> list[dict[str, Any]]:
+    return [
+        item("tools", tool_id, label=str(spec.get("label") or tool_id), source="toolchain", aliases=aliases_for(tool_id, spec.get("label")))
+        for tool_id, spec in load_toolchain(root).items()
+    ]
+
+
+def integration_items(root: Path) -> list[dict[str, Any]]:
+    items = []
+    for provider in load_providers(root):
+        provider_id = str(provider.get("id") or "")
+        if provider_id:
+            items.append(item("integrations", provider_id, label=str(provider.get("name") or provider_id), source="providers", aliases=aliases_for(provider_id, provider.get("name"))))
+    return items
+
+
+def skill_items(root: Path) -> list[dict[str, Any]]:
+    catalog = root / "vendor" / "skills" / "CATALOG.md"
+    if not catalog.exists():
+        return []
+    items = []
+    for line in catalog.read_text(encoding="utf-8").splitlines():
+        match = SKILL_ROW_PATTERN.match(line)
+        if not match:
+            continue
+        skill_id = match.group(1).strip()
+        if skill_id and skill_id.lower() != "skill":
+            items.append(item("skills", skill_id, label=skill_id, source="vendor-skills", aliases=aliases_for(skill_id)))
+    return items
+
+
+def llm_items() -> list[dict[str, Any]]:
+    return [
+        item("llms", backend_id, label=backend.display_name, source="llm-backends", aliases=aliases_for(backend_id, backend.display_name))
+        for backend_id, backend in BACKENDS.items()
+    ]
+
+
+def item(category: str, item_id: str, *, label: str, source: str, aliases: set[str]) -> dict[str, Any]:
+    return {"category": category, "id": item_id, "label": label, "source": source, "aliases": sorted(aliases)}
+
+
+def aliases_for(item_id: str, label: Any = None) -> set[str]:
+    values = {normalize(item_id)}
+    if label:
+        values.add(normalize(str(label)))
+    values.add(normalize(item_id.replace("-", " ")))
+    values.add(normalize(item_id.replace("_", " ")))
+    for token in re.split(r"[-_\s]+", item_id):
+        normalized = normalize(token)
+        if normalized and normalized not in {"cli", "mcp", "api", "tool", "skill", "plugin"}:
+            values.add(normalized)
+    if item_id.endswith("-cli"):
+        values.add(normalize(item_id.removesuffix("-cli")))
+    if item_id.endswith("-mcp"):
+        values.add(normalize(item_id.removesuffix("-mcp")))
+    return {value for value in values if value}
+
+
+def detect_action(prompt: str) -> str | None:
+    if contains_any(prompt, LIST_MARKERS):
+        return "list"
+    if contains_any(prompt, FORGET_MARKERS) and contains_any(prompt, DECISION_MARKERS) and detect_category(prompt):
+        return "reset"
+    if contains_any(prompt, FORGET_MARKERS) and contains_any(prompt, DECISION_MARKERS):
+        return "forget"
+    if contains_any(prompt, FORGET_MARKERS) and detect_category(prompt):
+        return "reset"
+    if contains_any(prompt, DISABLE_MARKERS):
+        return "disable"
+    if contains_any(prompt, ENABLE_MARKERS):
+        return "enable"
+    return None
+
+
+def detect_category(prompt: str) -> str | None:
+    for category, aliases in CATEGORY_ALIASES.items():
+        if contains_any(prompt, aliases):
+            return category
+    return None
+
+
+def list_payload(root: Path, *, category: str | None) -> dict[str, Any]:
+    index = build_control_index(root)
+    if category:
+        result = {
+            "kind": "control-index",
+            "status": "ok",
+            "category": category,
+            "items": public_items(index.get(category, [])),
+            "decisions": list_decisions(category),
+        }
+        return control_payload(status="ok", response=f"Estes sao os itens catalogados para {category}.", result=result)
+    result = {
+        "kind": "control-index",
+        "status": "ok",
+        "categories": {key: public_items(value) for key, value in index.items()},
+        "decisions": list_decisions(),
+    }
+    return control_payload(status="ok", response="Estes sao os recursos controlaveis catalogados.", result=result)
+
+
+def resolve_target(index: dict[str, list[dict[str, Any]]], prompt: str, *, category: str | None) -> list[dict[str, Any]]:
+    candidates = index.get(category, []) if category else [item for items in index.values() for item in items]
+    prompt_tokens = set(TOKEN_PATTERN.findall(prompt))
+    matches = []
+    for candidate in candidates:
+        aliases = set(candidate.get("aliases") or [])
+        if any(alias_matches_prompt(alias, prompt, prompt_tokens) for alias in aliases):
+            matches.append(candidate)
+            continue
+        candidate_tokens = set(TOKEN_PATTERN.findall(normalize(str(candidate.get("id") or ""))))
+        if candidate_tokens and candidate_tokens <= prompt_tokens:
+            matches.append(candidate)
+    return sorted(unique_matches(matches), key=lambda item: (str(item["category"]), str(item["id"])))
+
+
+def unique_matches(matches: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen: set[tuple[str, str]] = set()
+    unique = []
+    for match in matches:
+        key = (str(match.get("category")), str(match.get("id")))
+        if key not in seen:
+            seen.add(key)
+            unique.append(match)
+    return unique
+
+
+def alias_matches_prompt(alias: str, prompt: str, prompt_tokens: set[str]) -> bool:
+    if not alias:
+        return False
+    alias_tokens = set(TOKEN_PATTERN.findall(alias))
+    if len(alias_tokens) == 1:
+        return alias in prompt_tokens
+    return alias in prompt
+
+
+def needs_input_unknown(root: Path, prompt: str, *, category: str | None) -> dict[str, Any]:
+    index = build_control_index(root)
+    categories = [category] if category else sorted(index)
+    return {
+        "kind": "agent",
+        "status": "needs-input",
+        "ok": False,
+        "mode": "control-center-route",
+        "requires_llm": False,
+        "unknown_control_target": True,
+        "category": category,
+        "prompt": prompt,
+        "available_categories": categories,
+        "response": "Nao encontrei esse recurso nos catalogos locais controlaveis.",
+        "result": {"categories": {key: public_items(index.get(key, [])) for key in categories}},
+        "exit_code": 2,
+    }
+
+
+def needs_input_ambiguous(matches: list[dict[str, Any]], prompt: str, *, category: str | None) -> dict[str, Any]:
+    return {
+        "kind": "agent",
+        "status": "needs-input",
+        "ok": False,
+        "mode": "control-center-route",
+        "requires_llm": False,
+        "ambiguous_control_target": True,
+        "category": category,
+        "prompt": prompt,
+        "matches": public_items(matches),
+        "response": "Encontrei mais de um recurso compativel. Informe a categoria ou id exato.",
+        "exit_code": 2,
+    }
+
+
+def control_payload(*, status: str, response: str, result: dict[str, Any]) -> dict[str, Any]:
+    return {"kind": "agent", "status": status, "ok": status == "ok", "mode": "control-center-route", "requires_llm": False, "response": response, "result": result}
+
+
+def public_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [{"category": item.get("category"), "id": item.get("id"), "label": item.get("label"), "source": item.get("source")} for item in items]
+
+
+def contains_any(prompt: str, markers: tuple[str, ...]) -> bool:
+    return any(normalize(marker) in prompt for marker in markers)
+
+
+def normalize(value: str) -> str:
+    return " ".join(value.lower().split())

package/runtime/cli/aikit/decision_store.py

@@ -0,0 +1,175 @@
+"""Persistent local decisions for tools, integrations, skills and LLMs."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import app_path, ensure_app_home
+
+
+DECISION_VERSION = 1
+VALID_CATEGORIES = {"tools", "integrations", "skills", "llms"}
+VALID_STATES = {"enabled", "disabled_by_user", "denied_by_user", "needs_setup", "unavailable", "available", "requires_permission"}
+ITEM_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
+
+
+def decisions_path() -> Path:
+    ensure_app_home()
+    path = app_path("config", "decisions.json")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def empty_decisions() -> dict[str, Any]:
+    return {"version": DECISION_VERSION, "items": {}}
+
+
+def load_decisions() -> dict[str, Any]:
+    path = decisions_path()
+    if not path.exists():
+        return empty_decisions()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return empty_decisions()
+    if not isinstance(data, dict):
+        return empty_decisions()
+    data.setdefault("version", DECISION_VERSION)
+    if not isinstance(data.get("items"), dict):
+        data["items"] = {}
+    return data
+
+
+def save_decisions(data: dict[str, Any]) -> Path:
+    path = decisions_path()
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def list_decisions(category: str | None = None) -> dict[str, Any]:
+    data = load_decisions()
+    items = [public_decision(item) for item in data.get("items", {}).values() if not category or item.get("category") == category]
+    items.sort(key=lambda item: (item["category"], item["id"]))
+    return {
+        "kind": "decisions",
+        "status": "ok",
+        "category": category,
+        "path": str(decisions_path()),
+        "items": items,
+    }
+
+
+def set_decision(
+    category: str,
+    item_id: str,
+    state: str,
+    *,
+    reason: str | None = None,
+    scope: str = "persistent",
+) -> dict[str, Any]:
+    validate_category(category)
+    validate_item_id(item_id)
+    if state not in VALID_STATES:
+        raise ValueError(f"invalid decision state: {state}")
+    data = load_decisions()
+    key = decision_key(category, item_id)
+    item = {
+        "key": key,
+        "category": category,
+        "id": item_id,
+        "state": state,
+        "scope": scope,
+        "reason": reason,
+        "updated_at": now_iso(),
+    }
+    existing = data["items"].get(key)
+    if isinstance(existing, dict) and existing.get("created_at"):
+        item["created_at"] = existing["created_at"]
+    else:
+        item["created_at"] = item["updated_at"]
+    data["items"][key] = item
+    path = save_decisions(data)
+    return {
+        "kind": "decision",
+        "status": "updated",
+        "path": str(path),
+        "item": public_decision(item),
+        "category": category,
+        "id": item_id,
+        "state": state,
+    }
+
+
+def get_decision(category: str, item_id: str) -> dict[str, Any] | None:
+    validate_category(category)
+    validate_item_id(item_id)
+    item = load_decisions().get("items", {}).get(decision_key(category, item_id))
+    return public_decision(item) if isinstance(item, dict) else None
+
+
+def reset_decisions(category: str | None = None) -> dict[str, Any]:
+    data = load_decisions()
+    if category:
+        validate_category(category)
+        data["items"] = {key: value for key, value in data.get("items", {}).items() if value.get("category") != category}
+    else:
+        data["items"] = {}
+    path = save_decisions(data)
+    return {"kind": "decisions-reset", "status": "reset", "category": category, "path": str(path)}
+
+
+def forget_decision(category: str, item_id: str) -> dict[str, Any]:
+    validate_category(category)
+    validate_item_id(item_id)
+    data = load_decisions()
+    key = decision_key(category, item_id)
+    removed = data.get("items", {}).pop(key, None)
+    path = save_decisions(data)
+    return {
+        "kind": "decision-forget",
+        "status": "forgotten" if isinstance(removed, dict) else "not-found",
+        "path": str(path),
+        "category": category,
+        "id": item_id,
+        "removed": public_decision(removed) if isinstance(removed, dict) else None,
+    }
+
+
+def is_disabled(category: str, item_id: str) -> bool:
+    decision = get_decision(category, item_id)
+    return bool(decision and decision.get("state") in {"disabled_by_user", "denied_by_user"})
+
+
+def public_decision(item: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "category": item.get("category"),
+        "id": item.get("id"),
+        "state": item.get("state"),
+        "scope": item.get("scope"),
+        "reason": item.get("reason"),
+        "created_at": item.get("created_at"),
+        "updated_at": item.get("updated_at"),
+    }
+
+
+def decision_key(category: str, item_id: str) -> str:
+    return f"{category}:{item_id}"
+
+
+def validate_category(category: str) -> None:
+    if category not in VALID_CATEGORIES:
+        available = ", ".join(sorted(VALID_CATEGORIES))
+        raise ValueError(f"invalid decision category: {category}. available: {available}")
+
+
+def validate_item_id(item_id: str) -> None:
+    if not item_id or not ITEM_ID_PATTERN.fullmatch(item_id):
+        raise ValueError("item id must use letters, numbers, dots, dashes, underscores or colons")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()

package/runtime/cli/aikit/diagnostics.py

@@ -7,7 +7,7 @@ import os
 from pathlib import Path
 from typing import Any
 
-from cli.aikit.app_home import APP_DIRS, app_home
+from cli.aikit.app_home import APP_DIRS, app_home, app_home_status
 from cli.aikit.llm import config_path as llm_config_path
 from cli.aikit.llm import doctor_backends
 from cli.aikit.lock import lock_path, lock_status, read_lock
@@ -44,6 +44,7 @@ def runtime_diagnostics(
         "status": status,
         "root": str(root),
         "app_home": str(app_home()),
+        "app_home_status": app_home_status(),
         "app_dirs": {
             name: {
                 "path": str(app_home() / name),

package/runtime/cli/aikit/execution_reviewer.py

@@ -0,0 +1,174 @@
+"""Runtime execution for the execution-reviewer agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.llm import BACKENDS, candidate_backend_ids, doctor_backend, invoke_agent_prompt, load_config
+from cli.aikit.review_gate import mark_reviewed
+
+
+PREFERRED_REVIEW_BACKENDS = ("claude-code", "codex-cli")
+REVIEW_OK_MARKER = "REVIEW OK"
+REVIEW_BLOCKED_MARKER = "REVIEW BLOCKED"
+
+
+def enforce_execution_review(
+    *,
+    prompt: str,
+    result: dict[str, Any],
+    review_gate: dict[str, Any],
+    execution_plan: dict[str, Any] | None = None,
+    producer_backend: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    """Run a second concrete review when required and apply the gate outcome."""
+    if not review_gate.get("required"):
+        review_result = {
+            "kind": "execution-review",
+            "agent_id": "execution-reviewer",
+            "capability_id": "review-final-output",
+            "status": "not-required",
+            "ok": True,
+        }
+        return result, review_gate, review_result
+
+    response = str(result.get("response") or result.get("message") or "")
+    review_backend = select_review_backend(producer_backend=producer_backend, preferred=review_gate.get("preferred_reviewers") or [])
+    if not review_backend:
+        review_result = needs_review("No configured independent reviewer backend is available.", producer_backend=producer_backend)
+        return block_for_review(result, review_gate, review_result)
+
+    review_prompt = build_review_prompt(prompt=prompt, response=response, review_gate=review_gate, execution_plan=execution_plan)
+    invoked = invoke_agent_prompt(
+        review_prompt,
+        review_backend,
+        public_name="Execution Reviewer",
+        allow_fallback=False,
+    )
+    decision = parse_review_decision(str(invoked.get("response") or ""))
+    review_result = {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "capability": "execution-reviewer.review-final-output",
+        "status": review_status(invoked=invoked, decision=decision),
+        "ok": bool(invoked.get("ok")) and decision == "approved",
+        "llm_backend": invoked.get("llm_backend"),
+        "producer_backend": producer_backend,
+        "decision": decision,
+        "response": invoked.get("response"),
+        "message": invoked.get("message"),
+        "attempts": invoked.get("llm_backend_attempts"),
+    }
+    if not invoked.get("ok"):
+        return block_for_review(result, review_gate, review_result)
+    if decision == "blocked":
+        review_result["message"] = "Execution reviewer blocked the proposed final output."
+        return block_for_review(result, review_gate, review_result)
+    if decision != "approved":
+        review_result["message"] = "Execution reviewer did not return REVIEW OK."
+        return block_for_review(result, review_gate, review_result)
+    reviewed_gate = mark_reviewed(review_gate, reviewer=str(invoked.get("llm_backend") or review_backend), notes=str(invoked.get("response") or "Reviewed."))
+    return result, reviewed_gate, review_result
+
+
+def select_review_backend(*, producer_backend: str | None, preferred: list[str]) -> str | None:
+    config = load_config()
+    candidates = candidate_backend_ids(config=config, allow_fallback=True)
+    preferred_order = [item for item in list(preferred or []) + list(PREFERRED_REVIEW_BACKENDS) if item in BACKENDS]
+    ordered = [item for item in preferred_order if item in candidates]
+    ordered.extend(item for item in candidates if item not in ordered and item != "ollama")
+    for backend_id in ordered:
+        if backend_id == producer_backend:
+            continue
+        backend = doctor_backend(BACKENDS[backend_id], config)
+        if backend.get("status") == "ok":
+            return backend_id
+    return None
+
+
+def build_review_prompt(
+    *,
+    prompt: str,
+    response: str,
+    review_gate: dict[str, Any],
+    execution_plan: dict[str, Any] | None,
+) -> str:
+    plan_summary = {}
+    if isinstance(execution_plan, dict):
+        plan_summary = {
+            "status": execution_plan.get("status"),
+            "coordinator": (execution_plan.get("coordinator_agent") or {}).get("id") if isinstance(execution_plan.get("coordinator_agent"), dict) else None,
+            "specialist_tasks": [
+                {
+                    "agent_id": task.get("agent_id"),
+                    "capability_id": task.get("capability_id"),
+                    "status": task.get("status"),
+                }
+                for task in execution_plan.get("specialist_tasks") or []
+                if isinstance(task, dict)
+            ],
+        }
+    return "\n".join(
+        [
+            "Revise a entrega final do Agent DevKit antes da conclusao.",
+            "Verifique aderencia ao pedido, riscos, lacunas, evidencias, uso indevido de credenciais e necessidade de bloquear.",
+            "Responda com uma decisao objetiva: REVIEW OK ou REVIEW BLOCKED, seguida de justificativa curta.",
+            "",
+            f"Motivo do review gate: {review_gate.get('reason')}",
+            f"Prompt original: {prompt}",
+            f"Resumo do plano: {plan_summary}",
+            "",
+            "Resposta final proposta:",
+            response,
+        ]
+    )
+
+
+def parse_review_decision(response: str) -> str:
+    upper = response.upper()
+    if REVIEW_BLOCKED_MARKER in upper:
+        return "blocked"
+    if REVIEW_OK_MARKER in upper:
+        return "approved"
+    return "unstructured"
+
+
+def review_status(*, invoked: dict[str, Any], decision: str) -> str:
+    if not invoked.get("ok"):
+        return str(invoked.get("status", "failed"))
+    if decision == "blocked":
+        return "blocked"
+    if decision != "approved":
+        return "needs-review"
+    return "ok"
+
+
+def needs_review(message: str, *, producer_backend: str | None) -> dict[str, Any]:
+    return {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "capability": "execution-reviewer.review-final-output",
+        "status": "needs-review",
+        "ok": False,
+        "producer_backend": producer_backend,
+        "message": message,
+    }
+
+
+def block_for_review(
+    result: dict[str, Any],
+    review_gate: dict[str, Any],
+    review_result: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    blocked = dict(result)
+    blocked["status"] = "needs-review"
+    blocked["ok"] = False
+    blocked["exit_code"] = 2
+    blocked["message"] = review_result.get("message") or "Execution requires review before completion."
+    gate = dict(review_gate)
+    gate["status"] = "needs-review"
+    gate["reviewer"] = None
+    gate["notes"] = review_result.get("message")
+    return blocked, gate, review_result