multi-forge 0.2.0__py3-none-any.whl

forge/guard/semantic/verdict.py

@@ -0,0 +1,183 @@
+"""Supervisor verdict parsing and conversion.
+
+Parses structured JSON responses from the semantic supervisor and
+converts them to PolicyDecision objects.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from forge.core.reactive.structured_output import extract_json_from_response
+from forge.guard.types import PolicyDecision, Severity, Violation
+
+_log = logging.getLogger(__name__)
+
+# Confidence threshold for blocking (require high confidence + citations)
+CONFIDENCE_THRESHOLD = 0.8
+
+
+@dataclass
+class SupervisorVerdict:
+    """Parsed verdict from the semantic supervisor.
+
+    Attributes:
+        verdict: "aligned" (action matches plan) or "divergent" (action deviates)
+        confidence: 0.0-1.0 confidence in the verdict
+        violations: List of violation details for divergent verdicts
+    """
+
+    verdict: Literal["aligned", "divergent"]
+    confidence: float = 1.0
+    violations: list[dict[str, Any]] = field(default_factory=list)
+
+
+def _warn_verdict(evidence: str, suggested_fix: str) -> SupervisorVerdict:
+    """Create a divergent verdict with 0.0 confidence (maps to warn, not deny)."""
+    return SupervisorVerdict(
+        verdict="divergent",
+        confidence=0.0,
+        violations=[
+            {
+                "severity": "low",
+                "evidence": evidence,
+                "suggested_fix": suggested_fix,
+                "citations": [],
+            }
+        ],
+    )
+
+
+def parse_supervisor_verdict(response: str) -> SupervisorVerdict:
+    """Extract JSON verdict from supervisor response.
+
+    Uses ``extract_json_from_response`` for code-fence/raw JSON extraction,
+    then validates the verdict structure. Unparseable responses return a
+    divergent verdict with 0.0 confidence (maps to "warn", not deny or
+    silent allow).
+
+    Args:
+        response: Raw text response from the supervisor
+
+    Returns:
+        Parsed SupervisorVerdict
+    """
+    if not response:
+        _log.warning("Empty supervisor response, failing open with warning")
+        return _warn_verdict(
+            "Supervisor response was empty — check supervisor session health",
+            "Verify supervisor resume_id and proxy connectivity",
+        )
+
+    data = extract_json_from_response(response)
+    if data is None:
+        _log.warning("Could not parse supervisor verdict, failing open with warning")
+        return _warn_verdict(
+            "Supervisor verdict could not be parsed — check supervisor response format",
+            "Verify supervisor session responds with valid JSON verdict",
+        )
+
+    return _parse_verdict_data(data)
+
+
+def _parse_verdict_data(data: dict[str, Any]) -> SupervisorVerdict:
+    """Parse verdict from JSON data."""
+    verdict = data.get("verdict", "aligned")
+    if verdict not in ("aligned", "divergent"):
+        _log.warning("Unknown verdict '%s', treating as aligned", verdict)
+        verdict = "aligned"
+
+    confidence = data.get("confidence", 1.0)
+    if not isinstance(confidence, (int, float)):
+        confidence = 1.0
+    confidence = max(0.0, min(1.0, float(confidence)))
+
+    violations = data.get("violations", [])
+    if not isinstance(violations, list):
+        violations = []
+
+    return SupervisorVerdict(
+        verdict=verdict,  # type: ignore[arg-type]  # mypy doesn't track narrowing from reassignment
+        confidence=confidence,
+        violations=violations,
+    )
+
+
+def verdict_to_decision(verdict: SupervisorVerdict, *, intent: str | None = None) -> PolicyDecision:
+    """Convert a SupervisorVerdict to a PolicyDecision.
+
+    Blocking rules:
+    - Aligned verdicts always allow
+    - Divergent verdicts only block if:
+      - Confidence >= CONFIDENCE_THRESHOLD (0.8)
+      - At least one violation has citations
+    - Low confidence or no citations → warn only
+
+    Args:
+        verdict: Parsed supervisor verdict
+        intent: Policy intent to attach to deny decisions.
+
+    Returns:
+        PolicyDecision (allow, deny, or warn)
+    """
+    policy_id = "semantic.supervisor"
+
+    # Aligned = allow
+    if verdict.verdict == "aligned":
+        return PolicyDecision(
+            decision="allow",
+            policy_id=policy_id,
+        )
+
+    # Divergent: check confidence and citations
+    blocking_violations: list[Violation] = []
+    warnings: list[str] = []
+
+    for v in verdict.violations:
+        citations = v.get("citations", [])
+        severity_str = v.get("severity", "medium")
+        severity: Severity = (
+            severity_str if severity_str in ("critical", "high", "medium", "low") else "medium"
+        )  # type: ignore[assignment]  # membership check narrows str to Literal at runtime
+
+        violation = Violation(
+            rule_id=f"{policy_id}.alignment",
+            message=v.get("evidence", "Divergent from plan"),
+            severity=severity,
+            evidence=v.get("evidence"),
+            suggested_fix=v.get("suggested_fix"),
+            citations=citations if isinstance(citations, list) else [],
+        )
+
+        # Only block on high-confidence violations with citations
+        if verdict.confidence >= CONFIDENCE_THRESHOLD and citations:
+            blocking_violations.append(violation)
+        else:
+            # Low confidence or no citations → warning only
+            warnings.append(f"Possible divergence: {violation.message} (confidence: {verdict.confidence:.0%})")
+
+    if blocking_violations:
+        return PolicyDecision(
+            decision="deny",
+            policy_id=policy_id,
+            violations=blocking_violations,
+            warnings=warnings,
+            intent=intent,
+        )
+
+    # No blocking violations (low confidence or no citations)
+    if warnings:
+        return PolicyDecision(
+            decision="warn",
+            policy_id=policy_id,
+            warnings=warnings,
+        )
+
+    # No violations at all (shouldn't happen for divergent, but handle gracefully)
+    return PolicyDecision(
+        decision="warn",
+        policy_id=policy_id,
+        warnings=[f"Divergent verdict with no specific violations (confidence: {verdict.confidence:.0%})"],
+    )

forge/guard/store.py

@@ -0,0 +1,124 @@
+"""Helpers for reading/writing policy state to the session manifest.
+
+Policy state is persisted to confirmed.policy in the session manifest.
+This enables stateful policies (like TDD) to track state across hook
+invocations, since hooks are short-lived processes.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from forge.core.state import now_iso
+from forge.guard.types import CompositeDecision, PolicyDecision, Violation
+
+_log = logging.getLogger(__name__)
+
+# Maximum number of decisions to keep in the log
+MAX_DECISION_LOG = 100
+
+
+def serialize_decision(decision: PolicyDecision) -> dict[str, Any]:
+    """Serialize a PolicyDecision for persistence.
+
+    Args:
+        decision: The decision to serialize
+
+    Returns:
+        Dict suitable for JSON serialization
+    """
+    return {
+        "decision": decision.decision,
+        "policy_id": decision.policy_id,
+        "violations": [_serialize_violation(v) for v in decision.violations],
+        "warnings": decision.warnings,
+        "cached": decision.cached,
+        "evaluated_at": decision.evaluated_at,
+    }
+
+
+def _serialize_violation(violation: Violation) -> dict[str, Any]:
+    """Serialize a Violation for persistence."""
+    return {
+        "rule_id": violation.rule_id,
+        "message": violation.message,
+        "severity": violation.severity,
+        "evidence": violation.evidence,
+        "suggested_fix": violation.suggested_fix,
+        "citations": violation.citations,
+    }
+
+
+def serialize_composite_decision(
+    composite: CompositeDecision,
+    context_summary: str | None = None,
+) -> dict[str, Any]:
+    """Serialize a CompositeDecision for the decision log.
+
+    Args:
+        composite: The composite decision to serialize
+        context_summary: Optional summary of the action context
+
+    Returns:
+        Dict suitable for JSON serialization
+    """
+    return {
+        "final_decision": composite.final_decision,
+        "context_summary": context_summary,
+        "blocking_violations": [_serialize_violation(v) for v in composite.blocking_violations],
+        "warnings": composite.all_warnings,
+        "evaluated_at": now_iso(),
+        "decisions": [serialize_decision(d) for d in composite.decisions],
+    }
+
+
+def build_policy_state_update(
+    result: CompositeDecision,
+    engine_state: dict[str, dict[str, Any]],
+    existing_state: dict[str, Any] | None,
+    *,
+    forge_version: str | None = None,
+    bundles: list[str] | None = None,
+    rules_active: list[str] | None = None,
+    context_summary: str | None = None,
+) -> dict[str, Any]:
+    """Build the policy state update for the session manifest.
+
+    Appends to the decision log and merges the engine's collected policy states
+    into existing states. Policies that weren't evaluated (applies_to() returned
+    False) retain their prior state — only policies that ran get updated.
+
+    Args:
+        result: The composite decision from evaluation
+        engine_state: Collected state from evaluated stateful policies (keyed by policy_id)
+        existing_state: Current confirmed.policy state (may be None)
+        forge_version: Forge version for provenance
+        bundles: Active bundle names for provenance
+        rules_active: Active rule IDs for provenance
+        context_summary: Summary of the action for logging
+
+    Returns:
+        Dict to write to confirmed.policy
+    """
+    existing = existing_state or {}
+
+    # Append to decision log (with bounded size)
+    decisions_log = list(existing.get("decisions", []))
+    decisions_log.append(serialize_composite_decision(result, context_summary))
+    if len(decisions_log) > MAX_DECISION_LOG:
+        decisions_log = decisions_log[-MAX_DECISION_LOG:]
+
+    # Merge engine state into existing policy_states.
+    # Policies that weren't evaluated (applies_to() returned False) retain
+    # their prior state. Only policies that ran get their state updated.
+    merged_states = dict(existing.get("policy_states", {}))
+    merged_states.update(engine_state)
+
+    return {
+        "forge_version": forge_version or existing.get("forge_version"),
+        "bundles": bundles or existing.get("bundles", []),
+        "rules_active": rules_active or existing.get("rules_active", []),
+        "decisions": decisions_log,
+        "policy_states": merged_states,
+    }

forge/guard/team/__init__.py

@@ -0,0 +1,6 @@
+"""Team hook handlers for Claude Code Agent Teams.
+
+Quality gates at TeammateIdle and TaskCompleted boundaries using
+the shared reactive library (SyncAdapter, run_claude_session,
+extract_json_from_response).
+"""

forge/guard/team/config.py

@@ -0,0 +1,24 @@
+"""Configuration for team quality gate hooks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TeamSupervisorConfig:
+    """Configuration for team quality gate hooks.
+
+    Lives on ``PolicyIntent.team_supervisor``. When ``None``, team hooks
+    are no-ops (allow everything, fail-open).
+    """
+
+    enabled: bool = False
+    tagger_model: str = "gemini/gemini-2.0-flash"
+    resume_id: str | None = None
+    proxy: str | None = None
+    direct: bool = False
+    base_url: str | None = None
+    timeout_seconds: int = 45
+    throttle_seconds: int = 60
+    max_blocks_per_task: int = 3

forge/guard/team/handlers.py

@@ -0,0 +1,209 @@
+"""Team hook handler logic for TeammateIdle and TaskCompleted.
+
+Handlers return ``(exit_code, stderr_message)``:
+- ``(0, "")`` = allow (teammate goes idle / task marked completed)
+- ``(2, "feedback")`` = block (teammate continues / task stays open)
+
+All errors fail-open (return 0). Uses file-backed cache at
+``~/.forge/team-hooks/<session_id>.json`` for throttle + escape hatch.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from forge.core.reactive.proxy import lookup_proxy_base_url
+from forge.core.reactive.session_runner import run_claude_session
+from forge.core.reactive.structured_output import extract_json_from_response
+from forge.core.state import now_iso
+from forge.guard.team.config import TeamSupervisorConfig
+from forge.guard.team.prompts import (
+    IDLE_TAGGER_PROMPT,
+    TASK_TAGGER_PROMPT,
+    TEAM_SUPERVISOR_PROMPT,
+)
+
+_log = logging.getLogger(__name__)
+
+
+def handle_teammate_idle(
+    data: dict[str, Any],
+    config: TeamSupervisorConfig,
+    cache: dict[str, Any],
+) -> tuple[int, str]:
+    """Handle TeammateIdle event.
+
+    Args:
+        data: Raw hook event payload from Claude Code.
+        config: Team supervisor configuration.
+        cache: File-backed dict (loaded/saved by caller).
+
+    Returns:
+        ``(exit_code, stderr_feedback)``.
+    """
+    teammate = data.get("teammate_name") or "unknown"
+    team = data.get("team_name") or "unknown"
+    cache_key = f"{teammate}:idle"
+
+    cached = cache.get(cache_key)
+    if cached and _is_fresh(cached, config.throttle_seconds):
+        return cached.get("exit_code", 0), cached.get("feedback", "")
+
+    tag = _classify_event(config.tagger_model, IDLE_TAGGER_PROMPT, teammate, team)
+    if tag != "needs-review":
+        cache[cache_key] = {"checked_at": now_iso(), "exit_code": 0, "feedback": ""}
+        return 0, ""
+
+    if not config.resume_id:
+        return 0, ""
+
+    exit_code, feedback = _run_supervisor(config, teammate, team, "idle", "")
+    cache[cache_key] = {
+        "checked_at": now_iso(),
+        "exit_code": exit_code,
+        "feedback": feedback,
+    }
+    return exit_code, feedback
+
+
+def handle_task_completed(
+    data: dict[str, Any],
+    config: TeamSupervisorConfig,
+    cache: dict[str, Any],
+) -> tuple[int, str]:
+    """Handle TaskCompleted event.
+
+    Args:
+        data: Raw hook event payload from Claude Code.
+        config: Team supervisor configuration.
+        cache: File-backed dict (loaded/saved by caller).
+
+    Returns:
+        ``(exit_code, stderr_feedback)``.
+    """
+    teammate = data.get("teammate_name") or "unknown"
+    team = data.get("team_name") or "unknown"
+    task_id = data.get("task_id") or "unknown"
+    task_subject = data.get("task_subject")
+    cache_key = f"{teammate}:{task_id}"
+
+    cached = cache.get(cache_key, {})
+
+    # Escape hatch: auto-allow after max_blocks_per_task
+    if cached.get("block_count", 0) >= config.max_blocks_per_task:
+        _log.info(
+            "Escape hatch: auto-allowing %s after %d blocks",
+            cache_key,
+            config.max_blocks_per_task,
+        )
+        return 0, ""
+
+    if _is_fresh(cached, config.throttle_seconds):
+        return cached.get("exit_code", 0), cached.get("feedback", "")
+
+    tag = _classify_event(config.tagger_model, TASK_TAGGER_PROMPT, teammate, team, task_subject)
+    if tag != "needs-review":
+        cache[cache_key] = {"checked_at": now_iso(), "exit_code": 0, "feedback": ""}
+        return 0, ""
+
+    if not config.resume_id:
+        return 0, ""
+
+    task_context = f"Task: {task_subject or 'unknown'} (id: {task_id})"
+    exit_code, feedback = _run_supervisor(config, teammate, team, "task-completed", task_context)
+
+    block_count = cached.get("block_count", 0) + (1 if exit_code == 2 else 0)
+    cache[cache_key] = {
+        "checked_at": now_iso(),
+        "exit_code": exit_code,
+        "feedback": feedback,
+        "block_count": block_count,
+    }
+    return exit_code, feedback
+
+
+def _is_fresh(entry: dict[str, Any], throttle_seconds: int) -> bool:
+    """Return True if the cache entry is within the throttle window."""
+    checked_at = entry.get("checked_at")
+    if not checked_at:
+        return False
+    try:
+        checked_time = datetime.fromisoformat(checked_at.replace("Z", "+00:00"))
+        age = (datetime.now(timezone.utc) - checked_time).total_seconds()
+        return age < throttle_seconds
+    except (ValueError, TypeError):
+        return False
+
+
+def _classify_event(
+    model: str,
+    prompt_template: str,
+    teammate: str,
+    team: str,
+    task_subject: str | None = None,
+) -> str:
+    """Classify event via cheap LLM call. Returns single tag string."""
+    try:
+        from forge.core.llm import SyncAdapter, get_client
+
+        prompt = prompt_template.format(
+            teammate_name=teammate,
+            team_name=team,
+            task_subject=task_subject or "",
+        )
+        adapter = SyncAdapter(get_client(model))
+        response = adapter.ask(prompt)
+        words = response.strip().lower().split()
+        return words[0] if words else "routine"
+    except Exception as e:
+        _log.warning("Team tagger failed: %s", e)
+        return "routine"
+
+
+def _run_supervisor(
+    config: TeamSupervisorConfig,
+    teammate: str,
+    team: str,
+    event_type: str,
+    task_context: str,
+) -> tuple[int, str]:
+    """Run cross-team supervisor. Returns ``(exit_code, feedback)``.
+
+    Fail-open on: subprocess failure, parse failure, missing "verdict",
+    non-dict extraction, verdict != "divergent", or FORGE_DEPTH limit.
+    """
+    from forge.core.reactive.env import should_spawn_subprocesses
+
+    if not should_spawn_subprocesses():
+        _log.debug("Skipping team supervisor at FORGE_DEPTH limit")
+        return 0, ""
+
+    try:
+        base_url = None if config.direct else (config.base_url or lookup_proxy_base_url(config.proxy))
+    except Exception as e:
+        _log.warning("Team supervisor proxy '%s' not found: %s", config.proxy, e)
+        return 0, ""
+    prompt = TEAM_SUPERVISOR_PROMPT.format(
+        teammate_name=teammate,
+        team_name=team,
+        event_type=event_type,
+        task_context=task_context,
+    )
+    result = run_claude_session(
+        prompt,
+        resume_id=config.resume_id,
+        base_url=base_url,
+        timeout_seconds=config.timeout_seconds,
+    )
+    if not result.success:
+        _log.warning("Team supervisor failed: %s", result.error)
+        return 0, ""
+
+    verdict = extract_json_from_response(result.stdout)
+    if not isinstance(verdict, dict) or verdict.get("verdict") != "divergent":
+        return 0, ""
+
+    feedback = verdict.get("feedback", "Supervisor flagged work as divergent")
+    return 2, feedback

forge/guard/team/prompts.py

@@ -0,0 +1,41 @@
+"""Prompt templates for team hook handlers."""
+
+IDLE_TAGGER_PROMPT = """\
+A teammate went idle. Classify why (respond with just the tag):
+
+- needs-review: work may need verification before proceeding
+- routine: normal idle (thinking, waiting for dependency)
+- trivial: brief pause, no action needed
+
+Teammate: {teammate_name}, Team: {team_name}
+Tag:"""
+
+TASK_TAGGER_PROMPT = """\
+A teammate completed a task. Classify the result (respond with just the tag):
+
+- needs-review: completed work should be verified for quality/alignment
+- routine: standard task completion, no concerns
+- trivial: minor task, no review needed
+
+Teammate: {teammate_name}, Team: {team_name}
+Task: {task_subject}
+Tag:"""
+
+TEAM_SUPERVISOR_PROMPT = """\
+You are a team supervisor reviewing teammate work against the approved plan.
+
+Teammate: {teammate_name} ({team_name})
+Event: {event_type}
+{task_context}
+
+Evaluate whether this work aligns with the approved plan.
+Focus on: correct approach, right files modified, tests included.
+
+Respond with JSON in a code fence:
+```json
+{{
+  "verdict": "aligned" | "divergent",
+  "confidence": 0.0-1.0,
+  "feedback": "Brief feedback message for the teammate"
+}}
+```"""