{
  "markdown": "# HOL Guard Plugin\n\n[![HOL Guard](https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fguard%2Fhashgraph-online%2Fhol-guard-plugin&style=flat-square)](https://hol.org/guard)\n[![skills.sh](https://skills.sh/b/hashgraph-online/hol-guard-plugin)](https://skills.sh/hashgraph-online/hol-guard-plugin)\n\nCodex and DeepSeek Harness plugin for HOL Guard, the local AI security layer from [`hol-guard`](https://github.com/hashgraph-online/hol-guard).\n\nHOL Guard protects local AI harnesses before tools run. It can inspect Codex, Claude Code, Copilot CLI, Cursor, DeepSeek Harness, Gemini, Hermes, OpenClaw, OpenCode, and Antigravity surfaces, then route risky changes through local approvals and receipts.\n\n## Install in DeepSeek Harness\n\nInstall HOL Guard first:\n\n```bash\npipx install hol-guard\nhol-guard status\n```\n\nAdd the plugin to each DSH profile you use:\n\n```bash\ndsh plugin --profile headless add github:hashgraph-online/hol-guard-plugin\ndsh plugin --profile web add github:hashgraph-online/hol-guard-plugin\n```\n\nVerify that the composed profile contains `hol-guard-plugin`:\n\n```bash\ndsh --profile headless --dump-config\n```\n\nYou can also let HOL Guard install its managed local copy into detected DSH profiles:\n\n```bash\nhol-guard install dsh\n```\n\n### DSH enforcement contract\n\nThe plugin uses both DSH policy layers instead of relying on a reorderable listener alone:\n\n1. `tools/pre-execute` performs the bounded asynchronous HOL Guard review.\n2. Guard `ask`, `review`, and `require-reapproval` outcomes use DSH's native one-time approval service when it is mounted.\n3. The resolved decision is latched onto the exact DSH execution.\n4. `ctx.tools.guard()` enforces the latch as a monotonic final denial boundary before dispatch.\n\nA missing Guard command, timeout, malformed response, rejected or unavailable approval, `sandbox-required` outcome, incomplete review, or another plugin short-circuiting the pre-execute waterfall fails closed and prevents the tool from running. An ordinary pre-execute listener cannot force-allow a HOL Guard denial.\n\nSee [DeepSeek Harness security boundary](docs/dsh-security-boundary.md) for the ordering, failure matrix, trust properties, and explicit limitations.\n\n## Install the security skill\n\nInstall the portable `plugin-scanner` skill with the open Skills CLI:\n\n```bash\nnpx skills add hashgraph-online/hol-guard-plugin --skill plugin-scanner\n```\n\nThe Skills CLI supports many coding agents. The skill asks before installing the separate `plugin-scanner` package and never executes code from a repository just to scan it.\n\n## What this plugin adds\n\n- A native DSH bundle with asynchronous Guard review, native one-time approval, and a monotonic pre-dispatch denial guard.\n- A public Codex skill at [`skills/hol-guard/SKILL.md`](skills/hol-guard/SKILL.md).\n- A portable security skill at [`skills/plugin-scanner/SKILL.md`](skills/plugin-scanner/SKILL.md).\n- Guard setup guidance for Codex, Claude Code, Copilot CLI, Cursor, DeepSeek Harness, Gemini, Hermes, OpenClaw, OpenCode, and Antigravity.\n- Scanner guidance for Codex plugins, Claude Code project surfaces, skills, MCP servers, and marketplace packages.\n- Helper script for common `hol-guard` and `plugin-scanner` workflows.\n- Validation for the Codex manifest, DSH bundle, skill assets, script paths, and `.mcp.json`.\n\n## MCP server\n\nThis plugin includes a `.mcp.json` that registers the HOL Guard local MCP server (`guard-mcp.v1`). The server runs directly via the `hol-guard` binary, with no package-manager startup or shell wrapper.\n\n### Prerequisites\n\n- `hol-guard` CLI installed and on PATH (minimum version: 2.0.1024)\n- Python >= 3.10\n\n### Tools\n\n| Tool | Input | Returns |\n| :--- | :--- | :--- |\n| `search` | `{query: string}` | Max 20 sanitized results from local receipts and inventory |\n| `fetch` | `{id: string}` | Single receipt or inventory item, max 32 KiB sanitized text |\n| `get_guard_status` | `{}` | CLI availability, receipt count, inventory count |\n\nAll tools return a `guard-mcp.v1` contract envelope with `contractVersion`, `source: local`, `generatedAt`, and `freshness: real-time`.\n\n### Local vs Cloud\n\n- **Local** (`hol-guard mcp serve --stdio`): reads local Guard data offline. No network access required.\n- **Cloud** (`/api/guard/mcp` on the portal): reads synced workspace data. Requires OAuth Bearer token with `guard:workspace.read` and `guard:receipt.read` scopes.\n\n### Setup\n\n```bash\npipx install hol-guard\nhol-guard status\n```\n\nThe `.mcp.json` is automatically discovered by MCP-compatible clients. No additional configuration is needed.\n\n## Install HOL Guard locally\n\nRecommended:\n\n```bash\npipx install hol-guard\n```\n\nFallback:\n\n```bash\npython3 -m pip install --user hol-guard\n```\n\nVerify:\n\n```bash\nhol-guard status\nhol-guard detect --json\n```\n\n## Use from Codex\n\nInstall this plugin in Codex, then ask:\n\n```text\nUse HOL Guard to protect this workspace before running agent tools.\n```\n\nor:\n\n```text\nUse HOL Guard to scan this plugin before release.\n```\n\n## Local helper\n\n```bash\nbash scripts/hol-guard-plugin status\nbash scripts/hol-guard-plugin harnesses\nbash scripts/hol-guard-plugin protect claude-code\nbash scripts/hol-guard-plugin protect codex\nbash scripts/hol-guard-plugin protect dsh\nbash scripts/hol-guard-plugin scan-system claude .\nbash scripts/hol-guard-plugin scan-system codex .\nbash scripts/hol-guard-plugin scan .\nbash scripts/hol-guard-plugin evidence\n```\n\nThe helper does not read `.env` files. It only calls `hol-guard` and `plugin-scanner` commands already exposed by their respective upstream distributions.\n\n## Supported harness systems\n\n| System | Helper command | Guard command |\n| :--- | :--- | :--- |\n| Codex | `bash scripts/hol-guard-plugin protect codex` | `hol-guard install codex` |\n| Claude Code | `bash scripts/hol-guard-plugin protect claude-code` | `hol-guard install claude-code` |\n| Copilot CLI | `bash scripts/hol-guard-plugin protect copilot` | `hol-guard install copilot` |\n| Cursor | `bash scripts/hol-guard-plugin protect cursor` | `hol-guard install cursor` |\n| DeepSeek Harness | `bash scripts/hol-guard-plugin protect dsh` | `hol-guard install dsh` |\n| Gemini CLI | `bash scripts/hol-guard-plugin protect gemini` | `hol-guard install gemini` |\n| Hermes | `bash scripts/hol-guard-plugin protect hermes` | `hol-guard hermes bootstrap` |\n| OpenClaw | `bash scripts/hol-guard-plugin protect openclaw` | `hol-guard install openclaw` |\n| OpenCode | `bash scripts/hol-guard-plugin protect opencode` | `hol-guard install opencode` |\n| Antigravity | `bash scripts/hol-guard-plugin protect antigravity` | `hol-guard install antigravity` |\n\n## Validation\n\n```bash\nnpm test\n```\n\nThe repository also runs an actual DSH headless session against a local OpenAI-compatible mock inference endpoint. The control session executes a bash tool call, while the protected session proves HOL Guard's native DSH gate blocks the same call:\n\n```bash\nnpm run test:dsh-e2e\n```\n\nNo provider key is required for the end-to-end test.\n\n## Source projects\n\n- Plugin repository: https://github.com/hashgraph-online/hol-guard-plugin\n- Guard and scanner source: https://github.com/hashgraph-online/hol-guard\n- DeepSeek Harness source: https://github.com/deepseek-ai/deepseek-harness\n- HOL Guard product: https://hol.org/guard\n- Plugin security dataset: https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security\n\nSnapshot of catalog scores (~205 scored plugins), modeled Guard runtime fixtures, and public advisories. Scan ≠ safety guarantee. Catalog plugin count is not the Registry Broker agent catalog. HOL publishes it; not independent validation. Do not attribute Hashgraph Online's org-wide GitHub stars to this plugin repository.\n",
  "bytes": 7715,
  "sha": "f52610bd005d67a2a92481d030c8e2d312f0ff830059fca87c538e990221c92b",
  "repo_slug": "hashgraph-online/hol-guard-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hashgraph_online_hol_guard_plugin_5cc43538/readme"
}