hol-guard

HOL Guard

O HOL Guard protege harnesses de IA locais antes da execução de ferramentas. Use esta skill quando o usuário quiser comportamento de antivírus para IA, revisão de aprovação local, proteção para Codex, proteção para Claude Code, verificações de segurança MCP, verificação de skills/pacotes ou portões de lançamento do hol-guard e plugin-scanner.

Regras Rígidas

• Nunca leia arquivos .env.
• Nunca ignore aprovações do Guard.
• Não marque um workspace como protegido até que um comando do Guard comprove o status.
• Prefira comandos reversíveis do Guard em vez de edições diretas na configuração do harness.
• Não altere a configuração do harness no nível do usuário, a menos que o comando hol-guard seja o proprietário dessa mutação.
• Trate falhas do scanner como reais até que sejam inspecionadas.
• Preserve alterações existentes do usuário e inspecione git status --short antes de editar em um repositório.

Verificação de Instalação

Verifique ambos os CLIs independentemente:

command -v hol-guard
command -v plugin-scanner

Se o hol-guard estiver ausente e o usuário solicitar configuração em tempo de execução, prefira:

pipx install hol-guard

Se o plugin-scanner estiver ausente e o usuário solicitar varredura, instale a distribuição separada do scanner:

pipx install plugin-scanner

Não presuma que a distribuição hol-guard fornece o comando plugin-scanner. Se o pipx não estiver disponível, explique que a instalação isolada do CLI é recomendada em vez de alterar silenciosamente o ambiente Python do usuário.

Após a instalação em tempo de execução:

hol-guard status
hol-guard detect --json

Proteger um Harness Local

Use este fluxo para Codex, Claude Code, Copilot CLI, Cursor, Gemini, Hermes, OpenClaw, OpenCode ou Antigravity.

hol-guard bootstrap
hol-guard install <harness>
hol-guard run <harness> --dry-run
hol-guard run <harness>
hol-guard status

Nomes de harnesses:

• codex
• claude-code
• copilot
• cursor
• gemini
• hermes
• openclaw
• opencode
• antigravity

Apelidos de harnesses:

• claude mapeia para claude-code
• gemini-cli mapeia para gemini
• open-code mapeia para opencode
• open-claw mapeia para openclaw
• copilot-cli mapeia para copilot

Use o bootstrap específico do harness quando disponível:

hol-guard hermes bootstrap

Claude Code

Use quando o workspace tiver .claude/settings.local.json, .claude/agents, hooks do Claude, .mcp.json ou superfícies de aprovação de ferramentas gerenciadas pelo Claude.

hol-guard install claude-code
hol-guard run claude-code --dry-run
hol-guard run claude-code
hol-guard doctor claude-code --json

Claude Code é um alvo de primeira classe do Guard. Prefira hooks do Claude de propriedade do Guard em vez de edições manuais diretas na configuração do Claude.

Codex

Use quando o workspace tiver configuração do Codex, .codex/hooks.json, servidores MCP do Codex ou fluxos de ferramentas do Codex App/CLI.

hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex
hol-guard doctor codex --json

O Codex suporta hooks Bash PreToolUse de propriedade do Guard e elicitação MCP no mesmo chat quando disponível.

Outros Harnesses

Use o mesmo fluxo do Guard para:

• Copilot CLI: hol-guard install copilot
• Cursor: hol-guard install cursor
• Gemini CLI: hol-guard install gemini
• Hermes: hol-guard hermes bootstrap
• OpenClaw: hol-guard install openclaw
• OpenCode: hol-guard install opencode
• Antigravity: hol-guard install antigravity

Trabalho de Aprovação

Se o Guard bloquear ou enfileirar trabalho:

hol-guard approvals
hol-guard approvals open
hol-guard receipts
hol-guard diff <harness>

Para resolução apenas no terminal:

hol-guard approvals approve <request-id>
hol-guard approvals deny <request-id>

Aprove somente após ler o motivo do risco e entender o escopo solicitado.

Trabalho de Evidência

Use comandos de evidência quando o usuário precisar de prova, trilha de auditoria ou artefatos de transferência:

hol-guard receipts
hol-guard inventory
hol-guard abom --format json
hol-guard events
hol-guard explain <artifact-id>

Para sincronização em nuvem, mantenha opcional e direcionada pelo usuário:

hol-guard connect
hol-guard connect status
hol-guard connect repair
hol-guard sync

Escanear um Plugin ou Pacote de Skill

Use o modo scanner para plugins do Codex, superfícies de projeto do Claude Code, marketplaces .agents, skills, configurações de servidor MCP e portões de lançamento.

plugin-scanner lint .
plugin-scanner verify .

Se estiver escaneando um pacote específico:

plugin-scanner lint <path>
plugin-scanner verify <path>

Se o alvo for uma raiz de marketplace do Codex com .agents/plugins/marketplace.json, escaneie a raiz do repositório para que as entradas de plugin locais possam ser descobertas.

Orientação de alvo do scanner:

• Plugin do Codex: escaneie a raiz do repositório ou pasta do plugin contendo .codex-plugin/plugin.json.
• Marketplace do Codex: escaneie a raiz do repositório contendo .agents/plugins/marketplace.json.
• Projeto do Claude Code: escaneie a raiz do workspace contendo .claude/, .mcp.json, hooks ou pastas de agentes.
• Pacote de servidor MCP: escaneie a raiz do pacote contendo configuração do servidor e metadados do pacote.
• Pacote de skill: escaneie a pasta contendo SKILL.md.
• Workspace de agente misto: escaneie a raiz do repositório para que superfícies de plugin local, skill, MCP e configuração de harness sejam descobertas juntas.

Comandos Comuns de Depuração

hol-guard doctor
hol-guard doctor <harness> --json
hol-guard detect --json
hol-guard settings show
hol-guard explain install-connect
plugin-scanner verify . --json

Padrão de Resposta

Ao usar o Guard, relate:

• Qual comando foi executado.
• O que o Guard encontrou.
• O que permanece bloqueado ou arriscado.
• Que prova existe.
• O próximo comando exato se o usuário precisar agir.

Não afirme proteção, aprovação ou prontidão de lançamento sem a saída do comando que prove isso.