plugin-scanner 3.2.0__py3-none-any.whl → 3.3.1__py3-none-any.whl

codex_plugin_scanner/guard/adapters/bounded_cli_hook_failure.py

@@ -4,10 +4,10 @@ from __future__ import annotations
 
 from ..daemon.hook_availability_policy import (
     EMERGENCY_SAFE_REASON,
-    hook_action_is_emergency_safe,
     hook_event_is_permission_request,
     hook_event_pauses_when_unavailable,
 )
+from ..daemon.hook_launcher_recovery import hook_action_is_launcher_recovery_safe
 
 _DECISION_HOOK_HARNESSES = frozenset({"grok", "hermes", "openclaw"})
 
@@ -134,7 +134,7 @@ def failure_payload(
         pauses
         and not _is_permission_event(event_name)
         and isinstance(payload, dict)
-        and hook_action_is_emergency_safe(payload)
+        and hook_action_is_launcher_recovery_safe(payload)
     ):
         return _emergency_safe_payload(harness, event_name), 0
     if not pauses:

codex_plugin_scanner/guard/adapters/codex_daemon_hook_bridge.py

@@ -14,6 +14,7 @@ if __package__:
     from ..codex_hook_bridge_runtime import bridge_config_from_argv as _parse_bridge_config
     from ..config import MAX_APPROVAL_WAIT_TIMEOUT_SECONDS
     from ..daemon.hook_availability_policy import hook_event_is_permission_request
+    from ..daemon.hook_launcher_recovery import hook_action_is_launcher_recovery_safe
     from ..live_process_identity import (
         CODEX_BROWSER_WAIT_PROCESS_KEY,
         CODEX_BROWSER_WAIT_TIMEOUT_SECONDS_KEY,
@@ -44,6 +45,9 @@ else:  # pragma: no cover - exercised by subprocess integration tests
     from codex_plugin_scanner.guard.daemon.hook_availability_policy import (
         hook_event_is_permission_request,
     )
+    from codex_plugin_scanner.guard.daemon.hook_launcher_recovery import (
+        hook_action_is_launcher_recovery_safe,
+    )
     from codex_plugin_scanner.guard.live_process_identity import (
         CODEX_BROWSER_WAIT_PROCESS_KEY,
         CODEX_BROWSER_WAIT_TIMEOUT_SECONDS_KEY,
@@ -232,7 +236,7 @@ def main(
         )
         if response is None:
             if launch_integrity_failed:
-                response = _fail_closed(event_name, _LAUNCH_INTEGRITY_REASON)
+                response = _launcher_integrity_response(event_name, data)
             else:
                 failure_reason = _OVERLOAD_REASON if daemon_overloaded else _FAIL_CLOSED_REASON
                 response = _unavailable_response(event_name, failure_reason, data)
@@ -248,6 +252,17 @@ def main(
     return 0
 
 
+def _launcher_integrity_response(event_name: str, data: str) -> dict[str, object]:
+    """Keep a bad launcher from approving work, without locking out its repair."""
+
+    payload = _json_object(data)
+    if event_name == "PreToolUse" and payload is not None and hook_action_is_launcher_recovery_safe(payload):
+        return _unavailable_response(event_name, _LAUNCH_INTEGRITY_REASON, data)
+    if event_name in {"PreToolUse", "PermissionRequest"}:
+        return _fail_closed(event_name, _LAUNCH_INTEGRITY_REASON)
+    return _unavailable_response(event_name, _LAUNCH_INTEGRITY_REASON, data)
+
+
 def _bridge_output(
     response: dict[str, object],
     *,

codex_plugin_scanner/guard/adapters/codex_daemon_hook_bridge_flow.py

@@ -17,6 +17,8 @@ from .codex_daemon_hook_auth import _DaemonResponseError
 from .codex_daemon_hook_transport import _daemon_response_once, _DaemonGenerationChangedError
 
 _DAEMON_START_TIMEOUT_SECONDS = 8
+_DAEMON_RPC_TIMEOUT_SECONDS = 4.0
+_FALLBACK_TIMEOUT_SECONDS = 4.0
 _MINIMUM_OPERATION_SECONDS = 0.01
 _OVERLOAD_RESERVE_MS = 100
 
@@ -42,7 +44,7 @@ def bridge_review_response(
             state_path=state_path,
             query=query,
             data=data,
-            timeout_seconds=_remaining_seconds(deadline),
+            timeout_seconds=min(_remaining_seconds(deadline), _DAEMON_RPC_TIMEOUT_SECONDS),
         )
 
     try:
@@ -199,14 +201,18 @@ def _fallback_response(
         fallback_stdout = trusted_launch.run_fallback(
             fallback_command,
             data=data,
-            timeout_seconds=_remaining_seconds(deadline),
+            timeout_seconds=_remaining_seconds(deadline, cap=_FALLBACK_TIMEOUT_SECONDS),
         )
         if fallback_stdout is None:
             return None
         return _json_object(fallback_stdout.strip()) if fallback_stdout.strip() else {}
     if launch_integrity_failed:
         return None
-    return _run_local_fallback(fallback_command, data=data, timeout_seconds=_remaining_seconds(deadline))
+    return _run_local_fallback(
+        fallback_command,
+        data=data,
+        timeout_seconds=_remaining_seconds(deadline, cap=_FALLBACK_TIMEOUT_SECONDS),
+    )
 
 
 def _run_daemon_start(

codex_plugin_scanner/guard/cli/approval_gate_prompt.py

@@ -74,6 +74,12 @@ def prompt_for_approval_gate(
         )
     if summary:
         print(summary, file=sys.stderr)
+    proof_name = "authenticator code" if gate.totp_enabled else "approval password"
+    print(
+        f"HOL Guard is waiting for your {proof_name}. Enter it at the next prompt to continue.",
+        file=sys.stderr,
+        flush=True,
+    )
     password = None if gate.totp_enabled else getpass.getpass("Approval password: ")
     totp_code = getpass.getpass("Authenticator code: ") if gate.totp_enabled else None
     return ApprovalGateInput(

codex_plugin_scanner/guard/cli/extension_builder_commands.py

@@ -3,12 +3,14 @@
 from __future__ import annotations
 
 import argparse
+import json
+import subprocess
 import sys
 from pathlib import Path
 from typing import TextIO
 
 from ..extension_builder.errors import BuilderError
-from ..extension_builder.io import canonical_json
+from ..extension_builder.io import canonical_json, list_value, object_value, read_json
 
 _METADATA_FLAGS = (
     "slug",
@@ -21,6 +23,7 @@ _METADATA_FLAGS = (
     "launcher",
     "package",
 )
+_HANDOFF_TIMEOUT_SECONDS = 1_500
 
 
 def configure_extension_builder_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -54,7 +57,16 @@ def configure_extension_builder_parser(subparsers: argparse._SubParsersAction[ar
     apply.add_argument("--repo", type=Path, required=True, help="HOL Guard source checkout")
     apply.add_argument("--write", action="store_true", help="Explicitly apply the inspected source changes")
     apply.add_argument("--expected-plan", help="Require the plan digest from a previous inspection")
-    for command in (generate, validate, diff, apply):
+    handoff = commands.add_parser(
+        "handoff", help="Check command-extension inputs and generated projections before opening a pull request"
+    )
+    handoff.add_argument("--source", type=Path, required=True, help="Canonical command source JSON")
+    handoff.add_argument("--fixture", type=Path, required=True, help="Portable command fixture JSON")
+    handoff.add_argument(
+        "--repo", type=Path, default=Path("."), help="HOL Guard checkout containing generated projections"
+    )
+    handoff.add_argument("--compiler", type=Path, help="Use an already-built native source compiler")
+    for command in (generate, validate, diff, apply, handoff):
         command.add_argument("--json", action="store_true", help="Emit a deterministic JSON result")
 
 
@@ -96,6 +108,91 @@ def _generate(args: argparse.Namespace) -> dict[str, object]:
     return {**kit.summary(), "generated": True}
 
 
+def _handoff(args: argparse.Namespace) -> dict[str, object]:
+    source = object_value(read_json(args.source), code="source_shape")
+    if source.get("schema") != "guard.command-extension-source.v1":
+        raise BuilderError("source_schema", "Source must use guard.command-extension-source.v1.")
+    extension = object_value(source.get("extension"), code="source_shape")
+    extension_id = extension.get("extension_id")
+    if not isinstance(extension_id, str) or not extension_id.startswith("command."):
+        raise BuilderError("source_identity", "Source must declare a command.* extension ID.")
+    try:
+        repo = args.repo.resolve(strict=True)
+        source_path = args.source.resolve(strict=True)
+        fixture_path = args.fixture.resolve(strict=True)
+    except OSError as exc:
+        raise BuilderError("repository_path", "Repository, source, and fixture paths must exist.") from exc
+    expected_source = repo / "contributions" / "command-sources" / f"{extension_id}.json"
+    expected_fixture = repo / "tests" / "fixtures" / f"command-source-{extension_id.removeprefix('command.')}.v1.json"
+    if source_path != expected_source or fixture_path != expected_fixture:
+        raise BuilderError("canonical_paths", "Source and fixture must use their canonical repository paths.")
+    trust_map = object_value(
+        read_json(repo / "contracts" / "extensions" / "trust-class-map.v1.json"), code="trust_shape"
+    )
+    if trust_map.get("schemaVersion") != "guard.extension-trust-class-map.v1":
+        raise BuilderError("trust_schema", "Trust map must use guard.extension-trust-class-map.v1.")
+    classes = object_value(trust_map.get("classes"), code="trust_shape")
+    external = list_value(classes.get("external"), maximum=4096)
+    if not all(isinstance(item, str) for item in external):
+        raise BuilderError("trust_shape", "Trust map must list extension IDs as strings.")
+    other_classes = {
+        class_name
+        for class_name in ("first-party", "trusted-library")
+        if extension_id in list_value(classes.get(class_name), maximum=4096)
+    }
+    if extension_id not in external:
+        if other_classes:
+            raise BuilderError(
+                "trust_class", "External contributions must remain in the reviewed external trust class."
+            )
+        raise BuilderError("missing_external_trust", "Trust map must list the extension under external.")
+    if other_classes:
+        raise BuilderError("trust_class", "Trust map must assign the extension to only the external trust class.")
+    script = repo / "scripts" / "prepare_extension_contribution.py"
+    if script.is_symlink() or not script.is_file():
+        raise BuilderError("repository_layout", "Repository preparation tooling is unavailable.")
+    command = [
+        sys.executable,
+        str(script),
+        "--check",
+        "--source",
+        str(source_path),
+        "--fixture",
+        str(fixture_path),
+    ]
+    if args.compiler is not None:
+        command.extend(("--compiler", str(args.compiler)))
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=repo,
+            capture_output=True,
+            text=True,
+            timeout=_HANDOFF_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise BuilderError("handoff_validation", "Native handoff validation could not be completed.") from exc
+    if completed.returncode:
+        raise BuilderError("handoff_validation", "Native source or generated-projection validation failed.")
+    try:
+        validation = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise BuilderError("handoff_validation", "Native handoff validation produced an invalid result.") from exc
+    if (
+        not isinstance(validation, dict)
+        or validation.get("ok") is not True
+        or validation.get("checked") is not True
+        or validation.get("targetCommandsExecuted") != 0
+    ):
+        raise BuilderError("handoff_validation", "Native handoff validation did not complete safely.")
+    return {
+        "contributionId": extension_id,
+        "readyForPullRequest": True,
+        "targetCommandsExecuted": 0,
+    }
+
+
 def _operate(args: argparse.Namespace) -> dict[str, object]:
     from ..extension_builder.kit import diff_kits, load_kit
     from ..extension_builder.repository_write import apply_kit
@@ -104,6 +201,8 @@ def _operate(args: argparse.Namespace) -> dict[str, object]:
     command = args.extension_builder_command
     if command == "generate":
         return _generate(args)
+    if command == "handoff":
+        return _handoff(args)
     if command == "validate":
         return {**load_kit(args.kit).summary(), "validated": True}
     if command == "diff":
@@ -129,6 +228,10 @@ def _emit(result: dict[str, object], command: str, output: TextIO) -> None:
         print("Kits differ." if result["changed"] else "Kits are identical.", file=output)
         for name in ("addedOperations", "removedOperations", "changedOperations", "changedReviews"):
             print(f"{name}: {result[name]}", file=output)
+    elif command == "handoff":
+        print(f"Contribution handoff is ready for {result['contributionId']}.", file=output)
+        print("Source, fixture, external trust mapping, and generated projections agree.", file=output)
+        print("No target was executed and active protection was not changed.", file=output)
     else:
         verb = "Generated" if command == "generate" else "Validated"
         print(

codex_plugin_scanner/guard/daemon/hook_availability_policy.py

@@ -187,9 +187,10 @@ def availability_harness_response(
 ) -> dict[str, object]:
     """Render a schema-valid harness result when native review is unavailable."""
 
+    from .hook_launcher_recovery import hook_action_is_launcher_recovery_safe
     from .hook_worker_responses import observe_lifecycle_fail_safe_response
 
-    del payload, workspace, home_dir, guard_home, recording_only
+    del guard_home, recording_only
     canonical_lifecycle = _LIFECYCLE_CANONICAL_BY_COMPACT.get(_compact_hook_event_name(event_name))
     if canonical_lifecycle is not None:
         return observe_lifecycle_fail_safe_response(
@@ -211,6 +212,12 @@ def availability_harness_response(
     if pre_tool_event and reason_code.strip() in _INTEGRITY_FAIL_CLOSED_REASON_CODES:
         from .hook_worker_responses import integrity_fail_closed_pre_tool_response
 
+        if hook_action_is_launcher_recovery_safe(payload, workspace=workspace, home_dir=home_dir):
+            return recording_only_pre_tool_response(
+                harness,
+                reason_code=reason_code,
+                reason=reason,
+            )
         return integrity_fail_closed_pre_tool_response(
             harness,
             reason=reason,

codex_plugin_scanner/guard/daemon/hook_launcher_recovery.py

@@ -0,0 +1,106 @@
+"""Exact repair commands that may start while hook review cannot authenticate."""
+
+from __future__ import annotations
+
+import shlex
+from collections.abc import Mapping
+from pathlib import Path
+
+from .hook_availability_floor import (
+    _BLOCKED_SOURCE_EVENTS,
+    _MUTATING_TOOLS,
+    _UNSAFE_SHELL_MARKERS,
+    _flag_name,
+    _payload_command,
+    _payload_is_mcp,
+    _payload_source_events,
+    _tool_name,
+    hook_action_is_emergency_safe,
+)
+from .hook_request_parsing import runtime_hook_event_name
+
+_LAUNCHER_REPAIR_BINARIES = frozenset({"hol-guard", "plugin-guard"})
+_LAUNCHER_REPAIR_FLAGS = frozenset({"--dry-run", "--force-pypi-reinstall", "--json"})
+_LAUNCHER_REPAIR_HARNESSES = frozenset(
+    {
+        "antigravity",
+        "claude-code",
+        "cline",
+        "codex",
+        "copilot",
+        "cursor",
+        "gemini",
+        "grok",
+        "hermes",
+        "kimi",
+        "omp",
+        "openclaw",
+        "opencode",
+        "paseo",
+        "pi",
+        "zcode",
+    }
+)
+
+
+def hook_action_is_launcher_recovery_safe(
+    payload: Mapping[str, object],
+    *,
+    workspace: Path | None = None,
+    home_dir: Path | None = None,
+) -> bool:
+    """Allow inspection, or the exact bare command that restores a managed launcher.
+
+    A path-qualified executable is never treated as the managed launcher. An
+    unauthenticated payload reference is not evidence of the tool that will run.
+    Every other action stays blocked.
+    """
+
+    if "guard_payload_ref" in payload:
+        return False
+    if hook_action_is_emergency_safe(payload, workspace=workspace, home_dir=home_dir):
+        return True
+    if runtime_hook_event_name(payload) != "PreToolUse":
+        return False
+    tool_name = _tool_name(payload)
+    if tool_name in _MUTATING_TOOLS and tool_name not in {"bash", "shell"}:
+        return False
+    if _payload_source_events(payload) & _BLOCKED_SOURCE_EVENTS:
+        return False
+    if _payload_is_mcp(payload) or tool_name.startswith("plugin-"):
+        return False
+    command = _payload_command(payload)
+    if command is None:
+        return False
+    return _command_is_launcher_repair(command)
+
+
+def _command_is_launcher_repair(command: str) -> bool:
+    stripped = command.strip()
+    if not stripped or len(stripped) > 4096:
+        return False
+    if any(marker in stripped for marker in _UNSAFE_SHELL_MARKERS):
+        return False
+    try:
+        tokens = shlex.split(stripped, posix=True, comments=False)
+    except ValueError:
+        return False
+    if len(tokens) < 2 or tokens[0] not in _LAUNCHER_REPAIR_BINARIES:
+        return False
+    positional: list[str] = []
+    for token in tokens[1:]:
+        if token.startswith("-"):
+            if _flag_name(token) not in _LAUNCHER_REPAIR_FLAGS or "=" in token:
+                return False
+            continue
+        positional.append(token)
+    if positional[:1] == ["install"]:
+        return len(positional) == 2 and positional[1] in _LAUNCHER_REPAIR_HARNESSES
+    if positional[:1] == ["update"]:
+        return len(positional) == 1
+    if positional[:1] == ["daemon"]:
+        return positional[1:] in (["repair"], ["status"])
+    return False
+
+
+__all__ = ["hook_action_is_launcher_recovery_safe"]

codex_plugin_scanner/guard/daemon/static/assets/chunks/app-detail-workspace.js

@@ -1,4 +1,4 @@
-import { r as reactExports, i as harnessDisplayName, aq as fetchSettings, b3 as runHarnessAction, b4 as GuardHarnessActionError, j as jsxRuntimeExports, S as SectionLabel, A as ActionButton, b5 as HiMiniRocketLaunch, w as HiMiniShieldCheck, am as HiMiniArrowPath, y as formatRelativeTime, P as HiMiniExclamationTriangle, s as HiMiniCheckCircle, b6 as HiMiniTrash, b7 as isGuardDemoMode, b8 as fetchGuardApi, b9 as formatHarnessCommand, ah as HiMiniAdjustmentsHorizontal, ba as fetchApprovalPage, bb as fetchPolicy, x as guardActionDisposition, p as protectionHealthFor, l as useProtectionPresentationState, aY as HiMiniArrowLeft, c as HiMiniChevronRight, t as GuardHero, a5 as ProofStrip, bc as HiMiniHome, Q as HiMiniBolt, bd as appSetupTarget, be as guardActionPresentation, R as Badge, bf as DEFAULT_FILTER_STATE, bg as filterEvidence, bh as sortEvidence, bi as computeMetrics, bj as CommandActivityWorkspace, n as EmptyState, bk as EvidenceFilterBar, bl as EvidenceInsightStrip, bm as EvidenceActionList, bn as EvidenceActionDetail, M as useFocusTrap, bo as policyIdentityKey, K as HiMiniCloud, aJ as Tag, a7 as HiMiniXCircle, bp as clearLabelForScope, bq as HiMiniChartBar } from "../guard-dashboard.js";
+import { r as reactExports, i as harnessDisplayName, aq as fetchSettings, b3 as runHarnessAction, b4 as GuardHarnessActionError, j as jsxRuntimeExports, S as SectionLabel, A as ActionButton, b5 as HiMiniRocketLaunch, w as HiMiniShieldCheck, am as HiMiniArrowPath, y as formatRelativeTime, P as HiMiniExclamationTriangle, s as HiMiniCheckCircle, b6 as HiMiniTrash, b7 as isGuardDemoMode, b8 as fetchGuardApi, b9 as formatHarnessCommand, ah as HiMiniAdjustmentsHorizontal, ba as fetchApprovalPage, bb as fetchPolicy, x as guardActionDisposition, p as protectionHealthFor, l as useProtectionPresentationState, aZ as HiMiniArrowLeft, c as HiMiniChevronRight, t as GuardHero, a5 as ProofStrip, bc as HiMiniHome, Q as HiMiniBolt, bd as appSetupTarget, be as guardActionPresentation, R as Badge, bf as DEFAULT_FILTER_STATE, bg as filterEvidence, bh as sortEvidence, bi as computeMetrics, bj as CommandActivityWorkspace, n as EmptyState, bk as EvidenceFilterBar, bl as EvidenceInsightStrip, bm as EvidenceActionList, bn as EvidenceActionDetail, M as useFocusTrap, bo as policyIdentityKey, K as HiMiniCloud, aJ as Tag, a7 as HiMiniXCircle, bp as clearLabelForScope, bq as HiMiniChartBar } from "../guard-dashboard.js";
 import { A as ApprovalProofModal } from "./approval-proof-modal.js";
 import { u as useHarnessDetection, i as isHarnessDetected } from "./harness-detection.js";
 function HarnessSetupPanel(props) {

codex_plugin_scanner/guard/daemon/static/assets/chunks/approval-proof-modal.js

@@ -1,4 +1,4 @@
-import { r as reactExports, M as useFocusTrap, al as isApprovalProofSubmitDisabled, aP as buildApprovalProofCredentials, j as jsxRuntimeExports, S as SectionLabel, an as ApprovalProofFieldInputs, A as ActionButton } from "../guard-dashboard.js";
+import { r as reactExports, M as useFocusTrap, al as isApprovalProofSubmitDisabled, aQ as buildApprovalProofCredentials, j as jsxRuntimeExports, S as SectionLabel, an as ApprovalProofFieldInputs, A as ActionButton } from "../guard-dashboard.js";
 function ApprovalProofModal(props) {
   const {
     title,

codex_plugin_scanner/guard/daemon/static/assets/chunks/audit-workspace.js

@@ -1,4 +1,4 @@
-import { j as jsxRuntimeExports, aJ as Tag, y as formatRelativeTime, r as reactExports, A as ActionButton, ck as HiMiniChevronLeft, c as HiMiniChevronRight, bw as IconActionButton, C as HiMiniXMark, bB as GuardModalLayer, cl as HiMiniFunnel, aG as HiMiniMagnifyingGlass, cm as HiMiniArrowDown, cn as HiMiniArrowUp, S as SectionLabel, am as HiMiniArrowPath, bA as HiMiniBugAnt, n as EmptyState, ah as HiMiniAdjustmentsHorizontal, bC as ConnectFlowCard, P as HiMiniExclamationTriangle, aN as useResolvedApprovalGate, co as runAuditRemediation, R as Badge, ch as isBlockedGuardAction, bs as isSupplyChainAuditEvidence, s as HiMiniCheckCircle, a7 as HiMiniXCircle, i as harnessDisplayName, bU as HiMiniDocumentText, b2 as guardAwareHref, w as HiMiniShieldCheck } from "../guard-dashboard.js";
+import { j as jsxRuntimeExports, aJ as Tag, y as formatRelativeTime, r as reactExports, A as ActionButton, ck as HiMiniChevronLeft, c as HiMiniChevronRight, bw as IconActionButton, C as HiMiniXMark, bB as GuardModalLayer, cl as HiMiniFunnel, aG as HiMiniMagnifyingGlass, cm as HiMiniArrowDown, cn as HiMiniArrowUp, S as SectionLabel, am as HiMiniArrowPath, bA as HiMiniBugAnt, n as EmptyState, ah as HiMiniAdjustmentsHorizontal, bC as ConnectFlowCard, P as HiMiniExclamationTriangle, aO as useResolvedApprovalGate, co as runAuditRemediation, R as Badge, ch as isBlockedGuardAction, bs as isSupplyChainAuditEvidence, s as HiMiniCheckCircle, a7 as HiMiniXCircle, i as harnessDisplayName, bU as HiMiniDocumentText, b2 as guardAwareHref, w as HiMiniShieldCheck } from "../guard-dashboard.js";
 import { A as ApprovalProofModal } from "./approval-proof-modal.js";
 import { p as packageWorkbenchEcosystems, f as filterPackageWorkbenchFindings, c as sortPackageWorkbenchFindings, i as isApprovalGateRequiredError } from "./supply-chain-hub-workspace.js";
 import { r as resolveManagerCoverageManagers, a as resolveManagerCoverageStatus } from "./supply-chain-protection-stats.js";