review-agent-governance — Configuração

Bloqueie ações de revisão do agente AI (revisões de PR, comentários, merges, edições de CI) por trás de aprovação humana explícita. Cada tentativa, aprovada ou negada, produz um recibo assinado com Ed25519.

Quando usar este plugin

Instale-o em projetos onde um agente Claude Code:

• Revisa, comenta ou faz merge de pull requests (gh pr review, gh pr merge)
• Triagem de issues (gh issue comment, gh issue close)
• Publica releases (gh release create)
• Modifica a configuração de CI (.github/workflows/, .gitlab-ci.yml)
• Faz push para branches protegidos (main, master, release, production)
• Posta em superfícies de notificação externas (webhooks do Slack, Discord), assim que você adicionar uma regra para o comando que posta (a política padrão não os bloqueia)

Se o agente estiver apenas fazendo edições de arquivos locais e executando testes, este plugin é exagero. Use protect-mcp para aplicação geral de políticas de chamada de ferramentas e pule este.

Configuração única

1. Instale o plugin

claude plugin install wshobson/agents/review-agent-governance

2. Copie a política padrão para o seu projeto

cp .claude/plugins/review-agent-governance/policies/review-agent-governance.cedar \
   ./review-governance.cedar

Você pode editar este arquivo para corresponder às regras específicas do seu projeto. Veja ../agents/review-policy-author.md para orientação sobre como criar políticas de revisão.

3. Crie um diretório de recibos e uma chave de assinatura

mkdir -p ./review-receipts
echo "/review-receipts/" >> .gitignore
echo "/review-governance.key" >> .gitignore
echo "/.review-approved" >> .gitignore
if [ ! -e ./review-governance.key ]; then
  d=$(mktemp -d) && npx protect-mcp@0.7.4 init --dir "$d" && mv "$d/keys/gateway.json" ./review-governance.key
fi

protect-mcp 0.7.4 sign não cria a chave, então o último comando a cria, e ela nunca substitui uma chave existente. Sem uma chave, os recibos não são assinados. Para rotacionar a chave, arquive ./review-governance.key e ./review-receipts/receipts.jsonl primeiro, depois execute o comando novamente. Dê aos auditores o valor publicKey de ./review-governance.key. Não comite o arquivo, pois ele também contém a chave privada.

Fluxo de trabalho por sessão

A política Cedar nega ações de superfície de revisão incondicionalmente. Para aprovar uma ação específica, abra uma janela de aprovação antes dela e feche-a depois.

Arquivo de flag (o mais simples)

# Before the action you want to approve
touch ./.review-approved

# Let Claude Code run the review / comment / merge

# Immediately after
rm ./.review-approved

Comando de barra (de dentro do Claude Code)

/approve-review "Reviewing PR #123 authored by contributor X"

Isso cria ./.review-approved com o motivo fornecido incorporado como uma nota, e registra o motivo em um log de aprovação não assinado em ./review-receipts/approvals/. Um rm de acompanhamento ainda é necessário para fechar a janela.

Dry-run de tudo (força a avaliação completa da política)

Se você quiser que todas as chamadas de ferramenta passem pelo Cedar sem bypass de aprovação:

export REVIEW_APPROVAL_FLAG=./.never-approve

Qualquer chamada de ferramenta que corresponda a uma regra de proibição será negada; janelas aprovadas não têm efeito. Útil para CI ou para uma execução de auditoria bloqueada.

Verificando os recibos

Liste todos os recibos:

ls -la ./review-receipts/

Verifique cada recibo offline com a chave pública:

PUB=$(node -p 'JSON.parse(require("fs").readFileSync("./review-governance.key")).publicKey')
npx @veritasacta/verify@0.9.2 --replay-chain ./review-receipts/receipts.jsonl --key "$PUB"

Saída 0 significa que todos os recibos foram verificados. Saída 1 significa que um recibo falhou na verificação, porque foi adulterado, a chave está errada ou uma linha está malformada. Saída 2 significa que o arquivo de recibos não pôde ser lido.

Uma chamada negada nunca é executada, então não tem recibo. Para ver o que a política bloqueou, execute isto dentro do Claude Code:

/list-pending

Ele lista as chamadas de ferramenta que o hook PreToolUse bloqueou na sessão atual, com o nome da ferramenta e o comando ou caminho.

Exemplo: aprovando uma revisão de PR

# 1. Humano revisa o comentário proposto pelo agente
$ /list-pending
  Bloqueado nesta sessão:
  - Bash "gh pr review 42 --approve --body 'LGTM'"
  - Bash "gh pr comment 42 --body 'Looking good'"

# 2. Humano decide que o primeiro é apropriado, aprova-o
$ /approve-review "Aprovando LGTM no PR 42 após inspeção visual"
  ./.review-approved criado

# 3. Agente tenta a ação novamente; desta vez ela tem sucesso
$ agent: gh pr review 42 --approve --body "LGTM"

…