review-agent-setup

review-agent-governance — セットアップ

AI エージェントのレビュー操作（PR レビュー、コメント、マージ、CI 編集）を、明示的な人間の承認の背後でゲートします。承認・拒否を問わず、すべての試行は Ed25519 署名付きのレシートを生成します。

このプラグインを使うべき場面

Claude Code エージェントが次のことを行うプロジェクトにインストールしてください。

• プルリクエストのレビュー、コメント、マージ（gh pr review、gh pr merge）
• Issue のトリアージ（gh issue comment、gh issue close）
• リリースの公開（gh release create）
• CI 設定の変更（.github/workflows/、.gitlab-ci.yml）
• 保護されたブランチへのプッシュ（main、master、release、production）
• 外部通知サーフェスへの投稿（Slack Webhook、Discord）。ただし、投稿するコマンドに対するルールを追加した場合に限ります（デフォルトポリシーではこれらをゲートしません）

エージェントがローカルのファイル編集とテストの実行だけを行っている場合、このプラグインは過剰です。一般的なツール呼び出しのポリシー適用には protect-mcp を使用し、こちらはスキップしてください。

初回セットアップ

1. プラグインをインストールする

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

2. デフォルトポリシーをプロジェクトにコピーする

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

このファイルを編集して、プロジェクト固有のルールに合わせることができます。レビューポリシーの作成に関するガイダンスについては、../agents/review-policy-author.md を参照してください。

3. レシートディレクトリと署名鍵を作成する

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 [email protected] init --dir "$d" && mv "$d/keys/gateway.json" ./review-governance.key
fi

protect-mcp 0.7.4 の sign は鍵を作成しないため、最後のコマンドで鍵を作成します。また、既存の鍵を置き換えることはありません。鍵がない場合、レシートは署名されません。鍵をローテーションするには、まず ./review-governance.key と ./review-receipts/receipts.jsonl をアーカイブしてから、コマンドを再度実行してください。監査者には ./review-governance.key の publicKey の値を渡してください。このファイルは秘密鍵も保持しているため、コミットしないでください。

セッションごとのワークフロー

Cedar ポリシーはレビューサーフェスの操作を無条件で拒否します。特定の操作を承認するには、その操作の前に承認ウィンドウを開き、操作の後に閉じます。

フラグファイル（最も簡単）

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

# Let Claude Code run the review / comment / merge

# Immediately after
rm ./.review-approved

スラッシュコマンド（Claude Code 内から）

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

これにより、指定した理由がノートとして埋め込まれた ./.review-approved が作成され、理由が ./review-receipts/approvals/ 配下の署名なし承認ログに記録されます。ウィンドウを閉じるには、引き続き rm が必要です。

すべてをドライランする（完全なポリシー評価を強制）

すべてのツール呼び出しを、承認バイパスなしで Cedar に通したい場合：

export REVIEW_APPROVAL_FLAG=./.never-approve

forbid ルールに一致するツール呼び出しは拒否されます。承認済みウィンドウは効果がありません。CI やロックダウンされた監査実行に役立ちます。

レシートの検証

すべてのレシートを一覧表示します：

ls -la ./review-receipts/

公開鍵を使用して、すべてのレシートをオフラインで検証します：

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

終了コード 0 は、すべてのレシートが検証されたことを意味します。終了コード 1 は、改ざんされた、鍵が間違っている、または行が不正な形式であるために、レシートの検証が失敗したことを意味します。終了コード 2 は、レシートファイルを読み取れなかったことを意味します。

拒否された呼び出しは決して実行されないため、レシートがありません。ポリシーが何をブロックしたかを確認するには、Claude Code 内で次を実行します：

/list-pending

現在のセッションで PreToolUse フックがブロックしたツール呼び出しを、ツール名とコマンドまたはパスとともに一覧表示します。

例：PR レビューの承認

# 1. Human reviews the agent's proposed comment
$ /list-pending
  Blocked in this session:
  - Bash "gh pr review 42 --approve --body 'LGTM'"
  - Bash "gh pr comment 42 --body 'Looking good'"

# 2. Human decides the first one is appropriate, approves it
$ /approve-review "Approving LGTM on PR 42 after visual inspection"
  ./.review-approved created

# 3. Agent retries the action; this time it succeeds
$ agent: gh pr review 42 --approve --body "LGTM"
  [receipt appended to ./review-receipts/receipts.jsonl, decision=allow]

# 4. Human closes the window
$ rm ./.review-approved

許可された呼び出しには署名付きレシートがあり、公開鍵を持つ誰でもオフラインで検証できます。拒否された試行にはレシートがなく、承認ログは署名されていないため、監査者に証跡を示す際にはこの両方を念頭に置いてください。

protect-mcp との組み合わせ

両方のプラグインがインストールされている場合、各プラグインの hooks/hooks.json がそれぞれ独自の PreToolUse フックを登録し、Claude Code はすべてのツール呼び出しで両方を実行します：

{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/evaluate.sh" }

各 evaluate.sh は、標準入力のフックペイロードから tool_name と tool_input を読み取り（Claude Code は TOOL_NAME 変数を設定しません）、それぞれ独自のポリシーを評価します：protect-mcp は ./protect.cedar、こちらは ./review-governance.cedar です。

ツール呼び出しを続行するには、両方のフックが通過する必要があります。いずれかのポリシーで Cedar が deny すると、その呼び出しはブロックされます。

標準

• Ed25519 — RFC 8032（デジタル署名）
• JCS — RFC 8785（決定的な JSON 正規化）
• Cedar — AWS のオープンな認可ポリシー言語
• IETF ドラフト — draft-farley-acta-signed-receipts