plugin-scanner 2.0.1__tar.gz → 2.0.2__tar.gz

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1
-Summary: Security, operational-security, and publishability scanner for Codex, Claude, Gemini, and OpenCode plugin ecosystems.
+Version: 2.0.2
+Summary: Local Guard runtime plus security and publishability scanning for Codex, Claude, Cursor, Gemini, and OpenCode.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Issues, https://github.com/hashgraph-online/ai-plugin-scanner/issues
@@ -47,10 +47,47 @@ Description-Content-Type: text/markdown
 [![GitHub Stars](https://img.shields.io/github/stars/hashgraph-online/ai-plugin-scanner?style=social)](https://github.com/hashgraph-online/ai-plugin-scanner/stargazers)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg)](https://github.com/astral-sh/ruff)
 
-| ![Hashgraph Online Logo](https://hol.org/brand/Logo_Whole_Dark.png) | **The default CI gate for AI agent plugin ecosystems**. Lint locally, verify in CI, and ship publish-ready bundles for manifests, skills, MCP, and marketplace metadata across Codex, Claude, Gemini, and OpenCode.<br><br>Use this after scaffolding and before publishing, review, or distribution.<br><br>[PyPI Package (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)<br>[Legacy Namespace (`codex-plugin-scanner`)](https://pypi.org/project/codex-plugin-scanner/)<br>[HOL Plugin Registry](https://hol.org/registry/plugins)<br>[HOL GitHub Organization](https://github.com/hashgraph-online)<br>[Report an Issue](https://github.com/hashgraph-online/ai-plugin-scanner/issues) |
+| ![Hashgraph Online Logo](https://hol.org/brand/Logo_Whole_Dark.png) | **HOL Guard for local harness protection, plus the scanner CI gate for plugin ecosystems**. Protect Codex, Claude Code, Cursor, Gemini, and OpenCode before local tools run, then lint locally, verify in CI, and ship publish-ready bundles for manifests, skills, MCP, and marketplace metadata.<br><br>Use Guard when you want a local safety loop. Use the scanner when you want publishing and CI confidence.<br><br>[PyPI Package (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)<br>[Legacy Namespace (`codex-plugin-scanner`)](https://pypi.org/project/codex-plugin-scanner/)<br>[HOL Plugin Registry](https://hol.org/registry/plugins)<br>[HOL GitHub Organization](https://github.com/hashgraph-online)<br>[Report an Issue](https://github.com/hashgraph-online/ai-plugin-scanner/issues) |
 | :--- | :--- |
 
-## Start In 30 Seconds
+## Guard Start In 60 Seconds
+
+```bash
+# See what Guard can protect on this machine
+pipx run plugin-guard guard start
+
+# Install Guard in front of Codex
+pipx run plugin-guard guard install codex
+
+# Review the current tool state before launch
+pipx run plugin-guard guard run codex
+
+# Inspect local receipts later
+pipx run plugin-guard guard receipts
+```
+
+Guard is local-first:
+
+1. detect your harnesses
+2. install a Guard launcher
+3. run the harness through Guard
+4. approve or block changes
+5. inspect receipts locally
+6. connect sync only if you want shared history later
+
+Guard commands that matter most:
+
+- `plugin-scanner guard start` for the first-run path
+- `plugin-scanner guard status` for the current protection state
+- `plugin-scanner guard install <harness>` to create a local Guard launcher
+- `plugin-scanner guard run <harness> --dry-run` to record the current state before launch
+- `plugin-scanner guard run <harness>` to review and approve changed tools before launch
+- `plugin-scanner guard diff <harness>` when Guard says something changed
+- `plugin-scanner guard receipts` for local history
+
+See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local flow.
+
+## Scanner Start In 30 Seconds
 
 ```bash
 # Local preflight
@@ -70,7 +107,27 @@ pipx run plugin-scanner verify .
 
 If your repository uses a Codex marketplace root like `.agents/plugins/marketplace.json`, keep `plugin_dir: "."`. The scanner will discover local `./plugins/...` entries automatically, scan each local plugin manifest, and skip remote marketplace entries instead of treating the repo root as a single plugin.
 
-## Use After `$plugin-creator`
+## Two Product Modes
+
+### HOL Guard
+
+Use Guard when the problem is local runtime safety inside a harness:
+
+- a new MCP server showed up in local config
+- an existing tool changed after you trusted it
+- you want receipts for what was approved or blocked
+- you want to review changes before Codex, Claude Code, Cursor, Gemini, or OpenCode launches
+
+### Scanner CI Gate
+
+Use the scanner when the problem is authoring, CI, and publish readiness:
+
+- lint manifests and metadata
+- verify runtime and install surfaces
+- block PRs with policy gates
+- emit artifacts before submission or publishing
+
+## Use Scanner After `$plugin-creator`
 
 `plugin-scanner` is designed as the quality gate between plugin creation and distribution:
 

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/README.md

@@ -12,10 +12,47 @@
 [![GitHub Stars](https://img.shields.io/github/stars/hashgraph-online/ai-plugin-scanner?style=social)](https://github.com/hashgraph-online/ai-plugin-scanner/stargazers)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg)](https://github.com/astral-sh/ruff)
 
-| ![Hashgraph Online Logo](https://hol.org/brand/Logo_Whole_Dark.png) | **The default CI gate for AI agent plugin ecosystems**. Lint locally, verify in CI, and ship publish-ready bundles for manifests, skills, MCP, and marketplace metadata across Codex, Claude, Gemini, and OpenCode.<br><br>Use this after scaffolding and before publishing, review, or distribution.<br><br>[PyPI Package (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)<br>[Legacy Namespace (`codex-plugin-scanner`)](https://pypi.org/project/codex-plugin-scanner/)<br>[HOL Plugin Registry](https://hol.org/registry/plugins)<br>[HOL GitHub Organization](https://github.com/hashgraph-online)<br>[Report an Issue](https://github.com/hashgraph-online/ai-plugin-scanner/issues) |
+| ![Hashgraph Online Logo](https://hol.org/brand/Logo_Whole_Dark.png) | **HOL Guard for local harness protection, plus the scanner CI gate for plugin ecosystems**. Protect Codex, Claude Code, Cursor, Gemini, and OpenCode before local tools run, then lint locally, verify in CI, and ship publish-ready bundles for manifests, skills, MCP, and marketplace metadata.<br><br>Use Guard when you want a local safety loop. Use the scanner when you want publishing and CI confidence.<br><br>[PyPI Package (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)<br>[Legacy Namespace (`codex-plugin-scanner`)](https://pypi.org/project/codex-plugin-scanner/)<br>[HOL Plugin Registry](https://hol.org/registry/plugins)<br>[HOL GitHub Organization](https://github.com/hashgraph-online)<br>[Report an Issue](https://github.com/hashgraph-online/ai-plugin-scanner/issues) |
 | :--- | :--- |
 
-## Start In 30 Seconds
+## Guard Start In 60 Seconds
+
+```bash
+# See what Guard can protect on this machine
+pipx run plugin-guard guard start
+
+# Install Guard in front of Codex
+pipx run plugin-guard guard install codex
+
+# Review the current tool state before launch
+pipx run plugin-guard guard run codex
+
+# Inspect local receipts later
+pipx run plugin-guard guard receipts
+```
+
+Guard is local-first:
+
+1. detect your harnesses
+2. install a Guard launcher
+3. run the harness through Guard
+4. approve or block changes
+5. inspect receipts locally
+6. connect sync only if you want shared history later
+
+Guard commands that matter most:
+
+- `plugin-scanner guard start` for the first-run path
+- `plugin-scanner guard status` for the current protection state
+- `plugin-scanner guard install <harness>` to create a local Guard launcher
+- `plugin-scanner guard run <harness> --dry-run` to record the current state before launch
+- `plugin-scanner guard run <harness>` to review and approve changed tools before launch
+- `plugin-scanner guard diff <harness>` when Guard says something changed
+- `plugin-scanner guard receipts` for local history
+
+See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local flow.
+
+## Scanner Start In 30 Seconds
 
 ```bash
 # Local preflight
@@ -35,7 +72,27 @@ pipx run plugin-scanner verify .
 
 If your repository uses a Codex marketplace root like `.agents/plugins/marketplace.json`, keep `plugin_dir: "."`. The scanner will discover local `./plugins/...` entries automatically, scan each local plugin manifest, and skip remote marketplace entries instead of treating the repo root as a single plugin.
 
-## Use After `$plugin-creator`
+## Two Product Modes
+
+### HOL Guard
+
+Use Guard when the problem is local runtime safety inside a harness:
+
+- a new MCP server showed up in local config
+- an existing tool changed after you trusted it
+- you want receipts for what was approved or blocked
+- you want to review changes before Codex, Claude Code, Cursor, Gemini, or OpenCode launches
+
+### Scanner CI Gate
+
+Use the scanner when the problem is authoring, CI, and publish readiness:
+
+- lint manifests and metadata
+- verify runtime and install surfaces
+- block PRs with policy gates
+- emit artifacts before submission or publishing
+
+## Use Scanner After `$plugin-creator`
 
 `plugin-scanner` is designed as the quality gate between plugin creation and distribution:
 

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/docs/guard/architecture.md

@@ -1,10 +1,11 @@
 # Guard Architecture
 
-Guard lives inside `codex_plugin_scanner` and uses the existing scan engine as its trust and evidence core.
+Guard lives inside `codex_plugin_scanner` and is the local product surface for harness protection. The existing scan engine remains the trust and evidence core, but the user workflow starts with local harness installs and launch interception rather than CI.
 
 The runtime is split into:
 
 - `guard/adapters`: harness discovery for Codex, Claude Code, Cursor, Gemini, and OpenCode
+- `guard/shims`: local launcher shims that route harness launches through Guard
 - `guard/consumer`: orchestration for detection, policy evaluation, and consumer-mode scan output
 - `guard/policy`: local action resolution for allow, review, warn, and block decisions
 - `guard/receipts`: receipt creation for first use and changed-artifact events
@@ -21,4 +22,12 @@ Guard evaluates local artifacts in this order:
 5. Record a receipt and optional diff
 6. Launch the harness only if the effective action is not `block`
 
-Wrapper mode is the default implementation strategy in this phase. Config mutation is limited to the Claude Code hook helper, where Guard can add and remove its own hook entry in workspace-local settings.
+The local product loop is:
+
+1. `guard start` detects supported harnesses and suggests the next step
+2. `guard install <harness>` creates a local launcher shim
+3. `guard run <harness>` evaluates changes before the harness launches
+4. `guard receipts` and `guard status` let users inspect local decisions
+5. `guard login` and `guard sync` stay optional
+
+Wrapper mode is still the core execution strategy in this phase. Config mutation is limited to the Claude Code hook helper, where Guard can add and remove its own hook entry in workspace-local settings.

plugin_scanner-2.0.2/docs/guard/get-started.md

@@ -0,0 +1,82 @@
+# Guard Get Started
+
+Guard is the local product inside `plugin-scanner`.
+If you want the shortest entrypoint, install and run the dedicated `plugin-guard` console script.
+
+Use it when you want to protect a harness before local MCP servers, skills, hooks, or plugin surfaces run.
+
+## The local loop
+
+1. Detect your harnesses:
+
+   ```bash
+   plugin-guard guard start
+   ```
+
+2. Install Guard in front of the harness you use most:
+
+   ```bash
+   plugin-guard guard install codex
+   ```
+
+3. Run one dry pass so Guard records the current state:
+
+   ```bash
+   plugin-guard guard run codex --dry-run
+   ```
+
+4. Launch through Guard after that. Guard will prompt you if a tool is new or changed:
+
+   ```bash
+   plugin-guard guard run codex
+   ```
+
+5. Review changes when Guard blocks or asks for another look:
+
+   ```bash
+   plugin-scanner guard diff codex
+   plugin-scanner guard allow codex --scope artifact --artifact-id codex:project:workspace_skill
+   plugin-scanner guard deny codex --scope artifact --artifact-id codex:project:workspace_skill
+   ```
+
+6. Inspect receipts:
+
+   ```bash
+   plugin-guard guard receipts
+   plugin-guard guard status
+   ```
+
+7. Connect sync only if you want shared history later:
+
+   ```bash
+   plugin-scanner guard login --sync-url <url> --token <token>
+   plugin-scanner guard sync
+   ```
+
+## What `install` does
+
+`guard install <harness>` creates a local launcher shim under Guard’s home directory:
+
+- macOS/Linux: `~/.config/.ai-plugin-scanner-guard/bin/guard-<harness>`
+- Windows: `~/.config/.ai-plugin-scanner-guard/bin/guard-<harness>.cmd`
+
+Claude Code also gets Guard hook entries in `.claude/settings.local.json` when you install from a workspace.
+
+## First-party canaries
+
+Use these local repos to prove Guard against real first-party surfaces:
+
+- `hashnet-mcp-js` for a real MCP server harness target
+- `registry-broker-skills` for a real skills registry fixture during scan and trust checks
+
+Suggested local validation:
+
+```bash
+plugin-scanner guard detect codex --json
+plugin-scanner guard install codex
+plugin-scanner guard status
+plugin-scanner guard run codex --dry-run
+plugin-scanner guard receipts
+```
+
+For a real Codex canary, point `~/.codex/config.toml` or `<workspace>/.codex/config.toml` at a local `hashnet-mcp` command, then repeat the Guard loop above.

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/docs/guard/testing-matrix.md

@@ -3,20 +3,30 @@
 Automated coverage in this phase includes:
 
 - Guard CLI behavior tests for detect, scan, run, diff, receipts, install, uninstall, login, and sync
+- Guard product-flow tests for `guard start`, `guard status`, and launcher shim creation
 - SQLite persistence through real command execution in temporary homes and workspaces
 - consumer-mode JSON contract generation against scanner fixtures
 - local HTTP sync against a live in-process server instead of mocked transport
 
 Manual verification should include:
 
+- `guard start`
+- `guard status`
 - `guard detect codex --json`
 - `guard detect cursor --json`
 - `guard detect gemini --json`
 - `guard detect opencode --json`
+- `guard install codex`
 - `guard run codex --dry-run --default-action allow --json`
+- `guard receipts`
 - `codex mcp list`
 - `cursor-agent mcp list`
 - `gemini --help`
 - `opencode --help`
 
+First-party canaries for local manual validation:
+
+- a local `hashnet-mcp-js` checkout wired into Codex, Cursor, or Claude Code config
+- a local `registry-broker-skills` checkout for scanner fixtures and trust review
+
 Claude Code smoke tests remain conditional on the local `claude` binary being available.

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.1"
-description = "Security, operational-security, and publishability scanner for Codex, Claude, Gemini, and OpenCode plugin ecosystems."
+version = "2.0.2"
+description = "Local Guard runtime plus security and publishability scanning for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.10"
@@ -50,6 +50,7 @@ publish = [
 
 [project.scripts]
 plugin-scanner = "codex_plugin_scanner.cli:main"
+plugin-guard = "codex_plugin_scanner.cli:main"
 codex-plugin-scanner = "codex_plugin_scanner.cli:main"
 plugin-ecosystem-scanner = "codex_plugin_scanner.cli:main"
 
@@ -66,6 +67,15 @@ extend-exclude = ["tests/test-trust-scoring.py", "tests/test-trust-specs.py"]
 [tool.hatch.build.targets.wheel]
 packages = ["src/codex_plugin_scanner"]
 
+[tool.hatch.build]
+exclude = [
+    ".guard-e2e/**",
+    ".guard-e2e-prod/**",
+    ".guard-e2e-prod2/**",
+    ".guard-prod-venv/**",
+    ".guard-prod-venv-fresh/**",
+]
+
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "RUF"]
 

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/src/codex_plugin_scanner/cli.py

@@ -137,7 +137,11 @@ def _add_common_policy_args(parser: argparse.ArgumentParser) -> None:
 
 
 def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="codex-plugin-scanner", description="Scan and lint Codex plugin directories")
+    program_name = Path(sys.argv[0]).name or "plugin-scanner"
+    parser = argparse.ArgumentParser(
+        prog=program_name,
+        description="Run HOL Guard locally or scan plugin ecosystems for CI and publish readiness.",
+    )
     parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     parser.add_argument("--list-ecosystems", action="store_true", help="List supported plugin ecosystems and exit")
     subparsers = parser.add_subparsers(dest="command")

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/src/codex_plugin_scanner/guard/adapters/base.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ..models import GuardArtifact, HarnessDetection
+from ..shims import install_guard_shim, remove_guard_shim
 
 
 @dataclass(frozen=True, slots=True)
@@ -77,19 +78,21 @@ class HarnessAdapter:
         raise NotImplementedError
 
     def install(self, context: HarnessContext) -> dict[str, object]:
+        shim_manifest = install_guard_shim(self.harness, context)
         return {
             "harness": self.harness,
             "active": True,
-            "config_path": None,
-            "notes": ["No harness config was changed. Guard will evaluate this harness in wrapper mode."],
+            "config_path": shim_manifest["shim_path"],
+            **shim_manifest,
         }
 
     def uninstall(self, context: HarnessContext) -> dict[str, object]:
+        shim_manifest = remove_guard_shim(self.harness, context)
         return {
             "harness": self.harness,
             "active": False,
-            "config_path": None,
-            "notes": ["No harness config was changed. Guard wrapper mode is now disabled."],
+            "config_path": shim_manifest["shim_path"],
+            **shim_manifest,
         }
 
     def launch_command(self, context: HarnessContext, passthrough_args: list[str]) -> list[str]:

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/src/codex_plugin_scanner/guard/adapters/claude_code.py

@@ -8,6 +8,7 @@ import sys
 from pathlib import Path
 
 from ..models import GuardArtifact, HarnessDetection
+from ..shims import install_guard_shim, remove_guard_shim
 from .base import HarnessAdapter, HarnessContext, _command_available, _json_payload
 
 
@@ -119,14 +120,30 @@ class ClaudeCodeHarnessAdapter(HarnessAdapter):
 
     @staticmethod
     def _hook_command(context: HarnessContext) -> str:
-        command = [sys.executable, "-m", "codex_plugin_scanner.cli", "guard", "hook"]
+        command = [
+            sys.executable,
+            "-m",
+            "codex_plugin_scanner.cli",
+            "guard",
+            "hook",
+            "--guard-home",
+            str(context.guard_home),
+        ]
+        if context.home_dir.resolve() != Path.home().resolve():
+            command.extend(["--home", str(context.home_dir)])
         if context.workspace_dir is not None:
             command.extend(["--workspace", str(context.workspace_dir)])
         return subprocess.list2cmdline(command)
 
     def install(self, context: HarnessContext) -> dict[str, object]:
+        shim_manifest = install_guard_shim(self.harness, context)
         if context.workspace_dir is None:
-            return super().install(context)
+            return {
+                "harness": self.harness,
+                "active": True,
+                "config_path": shim_manifest["shim_path"],
+                **shim_manifest,
+            }
         settings_path = context.workspace_dir / ".claude" / "settings.local.json"
         payload = _json_payload(settings_path)
         hook_command = self._hook_command(context)
@@ -144,12 +161,22 @@ class ClaudeCodeHarnessAdapter(HarnessAdapter):
             "harness": self.harness,
             "active": True,
             "config_path": str(settings_path),
-            "notes": ["Guard hook entries added to .claude/settings.local.json"],
+            **shim_manifest,
+            "notes": [
+                "Guard hook entries added to .claude/settings.local.json",
+                *[str(note) for note in shim_manifest.get("notes", [])],
+            ],
         }
 
     def uninstall(self, context: HarnessContext) -> dict[str, object]:
+        shim_manifest = remove_guard_shim(self.harness, context)
         if context.workspace_dir is None:
-            return super().uninstall(context)
+            return {
+                "harness": self.harness,
+                "active": False,
+                "config_path": shim_manifest["shim_path"],
+                **shim_manifest,
+            }
         settings_path = context.workspace_dir / ".claude" / "settings.local.json"
         payload = _json_payload(settings_path)
         hook_command = self._hook_command(context)
@@ -164,5 +191,9 @@ class ClaudeCodeHarnessAdapter(HarnessAdapter):
             "harness": self.harness,
             "active": False,
             "config_path": str(settings_path),
-            "notes": ["Guard hook entries removed from .claude/settings.local.json"],
+            **shim_manifest,
+            "notes": [
+                "Guard hook entries removed from .claude/settings.local.json",
+                *[str(note) for note in shim_manifest.get("notes", [])],
+            ],
         }

{plugin_scanner-2.0.1 → plugin_scanner-2.0.2}/src/codex_plugin_scanner/guard/cli/commands.py

@@ -16,6 +16,8 @@ from ..policy.engine import SAFE_CHANGED_HASH_ACTION, VALID_GUARD_ACTIONS
 from ..receipts import build_receipt
 from ..runtime import guard_run, sync_receipts
 from ..store import GuardStore
+from .product import build_guard_start_payload, build_guard_status_payload
+from .prompt import build_prompt_artifacts, resolve_interactive_decisions
 from .render import emit_guard_payload
 
 
@@ -26,6 +28,7 @@ def _now() -> str:
 def add_guard_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     """Register the Guard command family."""
 
+    program_name = Path(sys.argv[0]).name or "plugin-scanner"
     guard_parser = subparsers.add_parser(
         "guard",
         help="Run local harness protection workflows",
@@ -35,19 +38,27 @@ def add_guard_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentPar
         ),
         epilog=(
             "Examples:\n"
-            "  codex-plugin-scanner guard detect\n"
-            "  codex-plugin-scanner guard doctor cursor\n"
-            "  codex-plugin-scanner guard run codex --dry-run\n"
-            "  codex-plugin-scanner guard install claude-code --workspace ."
+            f"  {program_name} guard detect\n"
+            f"  {program_name} guard doctor cursor\n"
+            f"  {program_name} guard run codex --dry-run\n"
+            f"  {program_name} guard install claude-code --workspace ."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     guard_subparsers = guard_parser.add_subparsers(
         dest="guard_command",
-        metavar="{detect,install,uninstall,run,scan,diff,receipts,explain,allow,deny,doctor,login,sync}",
+        metavar="{start,status,detect,install,uninstall,run,scan,diff,receipts,explain,allow,deny,doctor,login,sync}",
     )
     guard_subparsers.required = True
 
+    start_parser = guard_subparsers.add_parser("start", help="Show the first Guard steps for a local harness")
+    _add_guard_common_args(start_parser)
+    start_parser.add_argument("--json", action="store_true")
+
+    status_parser = guard_subparsers.add_parser("status", help="Show current Guard protection status")
+    _add_guard_common_args(status_parser)
+    status_parser.add_argument("--json", action="store_true")
+
     detect_parser = guard_subparsers.add_parser("detect", help="Discover supported harnesses and local artifacts")
     detect_parser.add_argument("harness", nargs="?")
     _add_guard_common_args(detect_parser)
@@ -95,10 +106,11 @@ def add_guard_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentPar
         policy_parser.add_argument("--artifact-id")
         policy_parser.add_argument(
             "--scope",
-            choices=("global", "harness", "workspace", "artifact"),
+            choices=("global", "harness", "workspace", "artifact", "publisher"),
             default="harness",
         )
         policy_parser.add_argument("--reason")
+        policy_parser.add_argument("--publisher")
         _add_guard_common_args(policy_parser)
         policy_parser.add_argument("--json", action="store_true")
         policy_parser.set_defaults(policy_action=action)
@@ -112,10 +124,12 @@ def add_guard_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentPar
     login_parser.add_argument("--sync-url", required=True)
     login_parser.add_argument("--token", required=True)
     login_parser.add_argument("--home")
+    login_parser.add_argument("--guard-home")
     login_parser.add_argument("--json", action="store_true")
 
     sync_parser = guard_subparsers.add_parser("sync", help="Sync receipts to the configured Guard endpoint")
     sync_parser.add_argument("--home")
+    sync_parser.add_argument("--guard-home")
     sync_parser.add_argument("--json", action="store_true")
 
     hook_parser = guard_subparsers.add_parser("hook", help=argparse.SUPPRESS)
@@ -133,6 +147,7 @@ def add_guard_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentPar
 
 def _add_guard_common_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--home")
+    parser.add_argument("--guard-home")
     parser.add_argument("--workspace")
 
 
@@ -144,16 +159,27 @@ def run_guard_command(args: argparse.Namespace) -> int:
         _emit("scan", payload, args.json or args.consumer_mode)
         return 0
 
-    guard_home = resolve_guard_home(getattr(args, "home", None))
+    home_override = getattr(args, "home", None)
+    guard_home = resolve_guard_home(getattr(args, "guard_home", None) or home_override)
     workspace = Path(args.workspace).resolve() if getattr(args, "workspace", None) else None
     context = HarnessContext(
-        home_dir=Path(getattr(args, "home", None)).resolve() if getattr(args, "home", None) else Path.home(),
+        home_dir=Path(home_override).resolve() if home_override else Path.home().resolve(),
         workspace_dir=workspace,
         guard_home=guard_home,
     )
     config = load_guard_config(guard_home, workspace=workspace)
     store = GuardStore(guard_home)
 
+    if args.guard_command == "start":
+        payload = build_guard_start_payload(context, store, config)
+        _emit("start", payload, getattr(args, "json", False))
+        return 0
+
+    if args.guard_command == "status":
+        payload = build_guard_status_payload(context, store, config)
+        _emit("status", payload, getattr(args, "json", False))
+        return 0
+
     if args.guard_command == "detect":
         detections = [detect_harness(args.harness, context)] if args.harness else detect_all(context)
         payload = {
@@ -182,6 +208,27 @@ def run_guard_command(args: argparse.Namespace) -> int:
         return 0
 
     if args.guard_command == "run":
+        interactive_resolver = None
+        if (
+            not getattr(args, "json", False)
+            and not bool(args.dry_run)
+            and config.mode == "prompt"
+            and sys.stdin.isatty()
+        ):
+
+            def interactive_resolver(detection, payload):
+                return resolve_interactive_decisions(
+                    store=store,
+                    evaluation=payload,
+                    prompt_artifacts=build_prompt_artifacts(
+                        harness=detection.harness,
+                        artifacts=list(detection.artifacts),
+                        evaluation_artifacts=[item for item in payload.get("artifacts", []) if isinstance(item, dict)],
+                    ),
+                    workspace=str(workspace) if workspace else None,
+                    now=_now(),
+                )
+
         payload = guard_run(
             args.harness,
             context=context,
@@ -190,7 +237,18 @@ def run_guard_command(args: argparse.Namespace) -> int:
             dry_run=bool(args.dry_run),
             passthrough_args=list(args.passthrough_args),
             default_action=args.default_action,
+            interactive_resolver=interactive_resolver,
         )
+        if (
+            payload.get("blocked")
+            and config.mode == "prompt"
+            and not getattr(args, "json", False)
+            and not sys.stdin.isatty()
+        ):
+            payload["review_hint"] = (
+                f"Guard blocked {args.harness} because this shell is non-interactive. "
+                f"Run `plugin-guard guard diff {args.harness}` and allow or deny the changed artifacts first."
+            )
         _emit("run", payload, getattr(args, "json", False))
         if payload.get("blocked"):
             return 1
@@ -216,7 +274,7 @@ def run_guard_command(args: argparse.Namespace) -> int:
         return 0
 
     if args.guard_command in {"allow", "deny"}:
-        _validate_policy_scope(args.scope, args.artifact_id, workspace)
+        _validate_policy_scope(args.scope, args.artifact_id, workspace, getattr(args, "publisher", None))
         payload = record_policy(
             store=store,
             harness=args.harness,
@@ -224,6 +282,7 @@ def run_guard_command(args: argparse.Namespace) -> int:
             scope=args.scope,
             artifact_id=args.artifact_id,
             workspace=str(workspace) if workspace else None,
+            publisher=getattr(args, "publisher", None),
             reason=args.reason,
         )
         _emit(args.guard_command, {"decision": payload}, getattr(args, "json", False))
@@ -349,10 +408,18 @@ def _string_list(value: object | None) -> list[str]:
     return [str(item) for item in value if isinstance(item, str) and item.strip()]
 
 
-def _validate_policy_scope(scope: str, artifact_id: str | None, workspace: Path | None) -> None:
+def _validate_policy_scope(
+    scope: str,
+    artifact_id: str | None,
+    workspace: Path | None,
+    publisher: str | None,
+) -> None:
     if scope == "artifact" and not artifact_id:
         print("--artifact-id is required when --scope artifact", file=sys.stderr)
         raise SystemExit(2)
     if scope == "workspace" and workspace is None:
         print("--workspace is required when --scope workspace", file=sys.stderr)
         raise SystemExit(2)
+    if scope == "publisher" and not publisher:
+        print("--publisher is required when --scope publisher", file=sys.stderr)
+        raise SystemExit(2)