plugin-scanner 2.0.99__tar.gz → 2.0.100__tar.gz

{plugin_scanner-2.0.99 → plugin_scanner-2.0.100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.99
+Version: 2.0.100
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner

{plugin_scanner-2.0.99 → plugin_scanner-2.0.100}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.99"
+version = "2.0.100"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.99 → plugin_scanner-2.0.100}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.99"
+version = "2.0.100"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

plugin_scanner-2.0.100/src/codex_plugin_scanner/guard/runtime/decisions.py

@@ -0,0 +1,211 @@
+"""Typed runtime decisions for Guard pause and approval UX."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+from codex_plugin_scanner.guard.models import GuardAction
+from codex_plugin_scanner.guard.runtime.signals import (
+    RiskConfidenceLabel,
+    RiskSignalV2,
+)
+
+GuardDecisionAction = Literal["allow", "warn", "ask", "block"]
+
+_ACTION_MESSAGES: dict[GuardAction, tuple[GuardDecisionAction, str, str, str]] = {
+    "allow": (
+        "allow",
+        "Allowed by policy",
+        "Policy allows this action.",
+        "HOL Guard allowed this action because policy already trusts it.",
+    ),
+    "warn": (
+        "warn",
+        "Risk signals found",
+        "HOL Guard noticed risk signals, but policy allows the harness to continue.",
+        "Review the warning if this action was unexpected.",
+    ),
+    "review": (
+        "ask",
+        "Approval required",
+        "HOL Guard needs your approval before this action can run.",
+        "Choose an approval scope, then retry in the harness.",
+    ),
+    "sandbox-required": (
+        "ask",
+        "Sandbox review required",
+        "HOL Guard wants this action reviewed and run in a sandboxed path.",
+        "Run it in a sandbox or choose a scoped approval before retrying.",
+    ),
+    "require-reapproval": (
+        "ask",
+        "Fresh approval required",
+        "HOL Guard needs a fresh approval because this action changed.",
+        "Choose the smallest approval scope that matches your intent, then retry.",
+    ),
+    "block": (
+        "block",
+        "Blocked by policy",
+        "HOL Guard blocked this action.",
+        "Review the details before changing policy or retrying.",
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class GuardDecisionV2:
+    """Product-facing Guard decision with harness and dashboard copy."""
+
+    action: GuardDecisionAction
+    reason: str
+    user_title: str
+    user_body: str
+    harness_message: str
+    dashboard_primary_detail: str
+    approval_scopes: tuple[str, ...]
+    retry_instruction: str | None
+    signals: tuple[RiskSignalV2, ...]
+    confidence: RiskConfidenceLabel
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "action": self.action,
+            "reason": self.reason,
+            "user_title": self.user_title,
+            "user_body": self.user_body,
+            "harness_message": self.harness_message,
+            "dashboard_primary_detail": self.dashboard_primary_detail,
+            "approval_scopes": list(self.approval_scopes),
+            "retry_instruction": self.retry_instruction,
+            "signals": [signal.to_dict() for signal in self.signals],
+            "confidence": self.confidence,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, object]) -> GuardDecisionV2:
+        return cls(
+            action=_parse_action(payload.get("action")),
+            reason=_required_string(payload, "reason"),
+            user_title=_required_string(payload, "user_title"),
+            user_body=_required_string(payload, "user_body"),
+            harness_message=_required_string(payload, "harness_message"),
+            dashboard_primary_detail=_required_string(payload, "dashboard_primary_detail"),
+            approval_scopes=_parse_string_tuple(payload.get("approval_scopes"), "approval_scopes"),
+            retry_instruction=_optional_string(payload, "retry_instruction"),
+            signals=_parse_signals(payload.get("signals")),
+            confidence=_parse_confidence(payload.get("confidence")),
+        )
+
+
+def decision_from_legacy_policy_action(
+    policy_action: GuardAction,
+    *,
+    reason: str,
+    signals: Sequence[RiskSignalV2] = (),
+) -> GuardDecisionV2:
+    action, user_title, harness_message, retry_instruction = _ACTION_MESSAGES[policy_action]
+    signal_tuple = tuple(signals)
+    confidence = _highest_confidence(signal_tuple)
+    dashboard_detail = _dashboard_detail_from_signals(signal_tuple, harness_message)
+    return GuardDecisionV2(
+        action=action,
+        reason=reason,
+        user_title=user_title,
+        user_body=dashboard_detail,
+        harness_message=harness_message,
+        dashboard_primary_detail=dashboard_detail,
+        approval_scopes=_approval_scopes_for_action(action),
+        retry_instruction=None if action in {"allow", "warn"} else retry_instruction,
+        signals=signal_tuple,
+        confidence=confidence,
+    )
+
+
+def _approval_scopes_for_action(action: GuardDecisionAction) -> tuple[str, ...]:
+    if action != "ask":
+        return ()
+    return ("artifact", "workspace", "publisher", "harness")
+
+
+def _dashboard_detail_from_signals(signals: tuple[RiskSignalV2, ...], fallback: str) -> str:
+    if not signals:
+        return fallback
+    strongest = max(signals, key=lambda item: _confidence_rank(item.confidence))
+    return strongest.plain_reason
+
+
+def _highest_confidence(signals: tuple[RiskSignalV2, ...]) -> RiskConfidenceLabel:
+    if not signals:
+        return "likely"
+    return max((signal.confidence for signal in signals), key=_confidence_rank)
+
+
+def _confidence_rank(confidence: RiskConfidenceLabel) -> int:
+    match confidence:
+        case "strong":
+            return 3
+        case "likely":
+            return 2
+        case "weak":
+            return 1
+
+
+def _parse_action(value: object) -> GuardDecisionAction:
+    match value:
+        case "allow":
+            return "allow"
+        case "warn":
+            return "warn"
+        case "ask":
+            return "ask"
+        case "block":
+            return "block"
+        case _:
+            raise ValueError("action must be a known Guard decision action")
+
+
+def _parse_confidence(value: object) -> RiskConfidenceLabel:
+    match value:
+        case "weak":
+            return "weak"
+        case "likely":
+            return "likely"
+        case "strong":
+            return "strong"
+        case _:
+            raise ValueError("confidence must be a known confidence label")
+
+
+def _parse_signals(value: object) -> tuple[RiskSignalV2, ...]:
+    if not isinstance(value, list):
+        raise ValueError("signals must be a list")
+    signals: list[RiskSignalV2] = []
+    for item in value:
+        if not isinstance(item, Mapping):
+            raise ValueError(f"signal item must be an object, got {type(item).__name__}")
+        signals.append(RiskSignalV2.from_dict(item))
+    return tuple(signals)
+
+
+def _parse_string_tuple(value: object, key: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(item, str) and item.strip() for item in value):
+        raise ValueError(f"{key} must be a list of non-empty strings")
+    return tuple(value)
+
+
+def _required_string(payload: Mapping[str, object], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{key} must be a non-empty string")
+    return value
+
+
+def _optional_string(payload: Mapping[str, object], key: str) -> str | None:
+    value = payload.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{key} must be a string or null")
+    return value

{plugin_scanner-2.0.99 → plugin_scanner-2.0.100}/src/codex_plugin_scanner/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for tool version."""
 
-__version__ = "2.0.99"
+__version__ = "2.0.100"

plugin_scanner-2.0.100/tests/test_guard_runtime_decisions.py

@@ -0,0 +1,129 @@
+"""Behavior tests for typed Guard runtime decisions."""
+
+from __future__ import annotations
+
+import pytest
+
+from codex_plugin_scanner.guard.runtime.decisions import (
+    GuardDecisionV2,
+    decision_from_legacy_policy_action,
+)
+from codex_plugin_scanner.guard.runtime.signals import RiskSignalV2
+
+
+def _signal() -> RiskSignalV2:
+    return RiskSignalV2(
+        signal_id="secret:env-read",
+        category="secret",
+        severity="high",
+        confidence="strong",
+        detector="guard-risk-v2",
+        title="Can read local environment secrets",
+        plain_reason="can read local environment secrets",
+        technical_detail=None,
+        evidence_ref="artifact",
+        redaction_level="summary",
+        false_positive_hint="Review whether this is read-only source search.",
+        advisory_id=None,
+    )
+
+
+def _weak_signal() -> RiskSignalV2:
+    return RiskSignalV2(
+        signal_id="network:traffic",
+        category="network",
+        severity="medium",
+        confidence="weak",
+        detector="guard-risk-v2",
+        title="Can send network traffic",
+        plain_reason="can send or receive network traffic",
+        technical_detail=None,
+        evidence_ref="artifact",
+        redaction_level="summary",
+        false_positive_hint=None,
+        advisory_id=None,
+    )
+
+
+def test_guard_decision_v2_round_trips_to_dict_payload() -> None:
+    decision = GuardDecisionV2(
+        action="ask",
+        reason="require-reapproval",
+        user_title="Review this changed action",
+        user_body="HOL Guard needs a fresh decision before this can run.",
+        harness_message="HOL Guard paused this changed action.",
+        dashboard_primary_detail="Changed shell command reads local secrets.",
+        approval_scopes=("artifact", "workspace"),
+        retry_instruction="Choose an approval scope, then retry in the harness.",
+        signals=(_signal(),),
+        confidence="strong",
+    )
+
+    payload = decision.to_dict()
+
+    assert payload == {
+        "action": "ask",
+        "reason": "require-reapproval",
+        "user_title": "Review this changed action",
+        "user_body": "HOL Guard needs a fresh decision before this can run.",
+        "harness_message": "HOL Guard paused this changed action.",
+        "dashboard_primary_detail": "Changed shell command reads local secrets.",
+        "approval_scopes": ["artifact", "workspace"],
+        "retry_instruction": "Choose an approval scope, then retry in the harness.",
+        "signals": [_signal().to_dict()],
+        "confidence": "strong",
+    }
+    assert GuardDecisionV2.from_dict(payload) == decision
+
+
+def test_guard_decision_v2_rejects_non_object_signal_entries() -> None:
+    payload = GuardDecisionV2(
+        action="ask",
+        reason="require-reapproval",
+        user_title="Review this changed action",
+        user_body="HOL Guard needs a fresh decision before this can run.",
+        harness_message="HOL Guard paused this changed action.",
+        dashboard_primary_detail="Changed shell command reads local secrets.",
+        approval_scopes=("artifact", "workspace"),
+        retry_instruction="Choose an approval scope, then retry in the harness.",
+        signals=(_signal(),),
+        confidence="strong",
+    ).to_dict()
+    payload["signals"] = [_signal().to_dict(), "not-a-signal"]
+
+    with pytest.raises(ValueError, match="signal item must be an object"):
+        GuardDecisionV2.from_dict(payload)
+
+
+def test_decision_from_legacy_policy_action_maps_all_actions() -> None:
+    cases = {
+        "allow": ("allow", "Policy allows this action."),
+        "warn": ("warn", "HOL Guard noticed risk signals, but policy allows the harness to continue."),
+        "review": ("ask", "HOL Guard needs your approval before this action can run."),
+        "sandbox-required": ("ask", "HOL Guard wants this action reviewed and run in a sandboxed path."),
+        "require-reapproval": ("ask", "HOL Guard needs a fresh approval because this action changed."),
+        "block": ("block", "HOL Guard blocked this action."),
+    }
+
+    for legacy_action, expected in cases.items():
+        decision = decision_from_legacy_policy_action(
+            legacy_action,
+            reason="test-reason",
+            signals=(_signal(),),
+        )
+
+        assert (decision.action, decision.harness_message) == expected
+        assert decision.reason == "test-reason"
+        assert decision.confidence == "strong"
+        assert decision.signals == (_signal(),)
+
+
+def test_decision_from_legacy_policy_action_uses_highest_confidence_signal() -> None:
+    decision = decision_from_legacy_policy_action(
+        "review",
+        reason="mixed-signals",
+        signals=(_weak_signal(), _signal()),
+    )
+
+    assert decision.confidence == "strong"
+    assert decision.dashboard_primary_detail == "can read local environment secrets"