🪝 Hooks

一言で

🧠 instructions が「お願い」で agent の判断に頼るのに対し、hooks は 実行ロジックそのものを止める。policy enforcement が必要なら hooks 一択。

6 つのフック種別

🔑 PreToolUse だけが agent の動きを止められる。他の 5 つは「観察 / 記録 / 通知」用と覚えておけばよい。

設定方法

.github/hooks/ 配下に 任意名の .json ファイル を 1 個以上置く。CLI / VS Code はローカルから、Cloud Agent は デフォルトブランチの .github/hooks/ から読み込む。

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/guard.sh",
        "powershell": "./scripts/guard.ps1",
        "cwd": ".",
        "timeoutSec": 30,
        "env": { "LOG_LEVEL": "INFO" }
      }
    ]
  }
}

• 📦 bash / powershell どちらも書いておけば OS 横断で動く
• ⏱️ デフォルト timeout は 30 秒。重い検証を入れるなら timeoutSec を上げる
• 🔁 同じイベントに 複数フックを配列で 並べると上から順に実行される
• 📥 スクリプトは stdin から JSON を受け取り、必要なら stdout に JSON を返す

★ 特定コマンドのブロック (PreToolUse)

agent が何を実行しようとしているかを toolName と toolArgs で受け取り、{"permissionDecision": "deny", "permissionDecisionReason": "..."} を返すだけで実行を止められる。

#!/bin/bash
# .github/hooks/scripts/guard.sh
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')
TOOL_ARGS=$(echo "$INPUT" | jq -r '.toolArgs')

# bash 以外はそのまま許可
if [ "$TOOL_NAME" != "bash" ]; then
  exit 0
fi

COMMAND=$(echo "$TOOL_ARGS" | jq -r '.command')

# 🚨 危険コマンドの黒リスト
if echo "$COMMAND" | grep -qE 'rm -rf /|sudo |mkfs|dd if=|:\(\)\{'; then
  jq -nc \
    --arg reason "禁止コマンド: $COMMAND" \
    '{permissionDecision: "deny", permissionDecisionReason: $reason}'
  exit 0
fi

# 🔒 production 環境への変更を禁止
if echo "$COMMAND" | grep -qE 'kubectl .*--context[= ]prod|terraform apply.*prod'; then
  jq -nc '{permissionDecision: "deny", permissionDecisionReason: "production への変更は人間レビュー必須"}'
  exit 0
fi

# それ以外は許可 (出力なし or "allow")
exit 0

どこから読み込まれる?

📝 実装時は どの環境で動かすか に注意: hooks.json は timeout(VS Code) vs timeoutSec(CLI/Cloud)、script は tool_name / tool_input / hookSpecificOutput(VS Code) vs toolName / toolArgs / permissionDecision(CLI/Cloud)。