Claude Code Hooks実践ガイド — 全24イベント解説・セキュリティゲート・defer承認ワークフロー・MCP連携の本番パターン集

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command // empty' | grep -qE '\\brm\\b' && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"rm command is blocked by security policy\"}}' || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [{ "hooks": [{ "type": "command", "command": "echo \"$(date '+%H:%M:%S') PreToolUse $(jq -r '.tool_name' 2>/dev/null)\" >> /tmp/hooks.log" }] }],
    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "echo \"$(date '+%H:%M:%S') PostToolUse $(jq -r '.tool_name' 2>/dev/null)\" >> /tmp/hooks.log" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "echo \"$(date '+%H:%M:%S') Stop\" >> /tmp/hooks.log" }] }],
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "echo \"$(date '+%H:%M:%S') SessionStart\" >> /tmp/hooks.log" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "echo \"$(date '+%H:%M:%S') SessionEnd\" >> /tmp/hooks.log" }] }]
  }
}

#!/bin/sh
# hooks/block-dangerous.sh
# stdin から JSON を読み取り、危険なコマンドをブロック

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "Bash" ]; then
  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

  # rm -rf, git push --force, DROP TABLE をブロック
  if echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f|git\s+push\s+.*--force|DROP\s+TABLE'; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Destructive command blocked. Use a safer alternative."}}'
    exit 0
  fi
fi

#!/bin/sh
# hooks/protect-files.sh
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

# Edit / Write ツールで .env や credentials を保護
if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "Write" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

  if echo "$FILE_PATH" | grep -qE '\.(env|pem|key)$|credentials|secrets'; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Sensitive file is protected. Request manual edit instead."}}'
    exit 0
  fi
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "sh hooks/block-dangerous.sh" }]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "sh hooks/protect-files.sh" }]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "以下のコマンドが本番環境に影響を与える可能性があるか判定してください。環境変数の変更、外部APIへのリクエスト、データベースへの書き込みを含む場合はブロックしてください。コマンド: $ARGUMENTS",
            "statusMessage": "セキュリティ審査中..."
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# hooks/defer-deploy.sh
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "Bash" ]; then
  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

  if echo "$COMMAND" | grep -qE 'vercel deploy --prod|npm run deploy'; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"defer","permissionDecisionReason":"Production deploy requires approval"}}'
    exit 0
  fi
fi

// approve-and-resume.mjs
import { execSync } from "child_process";

const sessionId = process.argv[2];
const decision = process.argv[3]; // "allow" or "deny"

if (!sessionId || !decision) {
  console.error("Usage: node approve-and-resume.mjs <session-id> <allow|deny>");
  process.exit(1);
}

// セッションを再開（再開時に同じ PreToolUse が発火する）
// 承認済みフラグをファイルで管理する簡易実装
if (decision === "allow") {
  // 承認フラグを書き込み、Hook 側で参照させる
  const fs = await import("fs");
  fs.writeFileSync(`/tmp/approved-${sessionId}`, "approved");
}

const result = execSync(
  `claude -p --resume "${sessionId}" --no-input`,
  { encoding: "utf-8", timeout: 300000 }
);
console.log(result);

#!/bin/sh
# hooks/defer-deploy.sh（承認フラグ対応版）
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

if [ "$TOOL_NAME" = "Bash" ]; then
  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

  if echo "$COMMAND" | grep -qE 'vercel deploy --prod|npm run deploy'; then
    # 承認フラグがあれば allow
    if [ -f "/tmp/approved-${SESSION_ID}" ]; then
      rm "/tmp/approved-${SESSION_ID}"
      echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
    else
      echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"defer","permissionDecisionReason":"Production deploy requires Slack approval"}}'
    fi
    exit 0
  fi
fi

mcp__supabase__query
mcp__github__create_pull_request
mcp__memory__create_entities

#!/bin/sh
# hooks/mcp-guard.sh
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

# Supabase MCP の破壊的 SQL をブロック
if echo "$TOOL_NAME" | grep -q '^mcp__supabase__'; then
  QUERY=$(echo "$INPUT" | jq -r '.tool_input.query // .tool_input.sql // empty' | tr '[:lower:]' '[:upper:]')

  if echo "$QUERY" | grep -qE 'INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE'; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Write operations on Supabase require manual execution. Use SELECT only."}}'
    exit 0
  fi
fi

# GitHub MCP の main ブランチへの PR を ask に回す
if [ "$TOOL_NAME" = "mcp__github__create_pull_request" ]; then
  BASE=$(echo "$INPUT" | jq -r '.tool_input.base // empty')
  if [ "$BASE" = "main" ] || [ "$BASE" = "master" ]; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"PR to main branch requires manual approval"}}'
    exit 0
  fi
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__supabase__.*|mcp__github__.*",
        "hooks": [{ "type": "command", "command": "sh hooks/mcp-guard.sh" }]
      }
    ]
  }
}

{
  "matcher": "mcp__.*",
  "hooks": [
    {
      "type": "http",
      "url": "https://audit.example.com/hooks/mcp-calls",
      "headers": { "Authorization": "Bearer $AUDIT_TOKEN" },
      "allowedEnvVars": ["AUDIT_TOKEN"],
      "timeout": 5
    }
  ]
}

{
  "hooks": {
    "SubagentStart": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/T.../B.../xxx",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "TeammateIdle": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date)] Teammate idle\" >> /tmp/agent-team.log"
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# hooks/debug-wrapper.sh
# Usage: sh hooks/debug-wrapper.sh <actual-hook-script>

INPUT=$(cat)
TIMESTAMP=$(date '+%Y%m%d_%H%M%S')
HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"')

# 入力をダンプ
echo "$INPUT" | jq . > "/tmp/hook_${HOOK_EVENT}_${TIMESTAMP}_input.json"

# 実際の Hook を実行
OUTPUT=$(echo "$INPUT" | sh "$1" 2>/tmp/hook_${HOOK_EVENT}_${TIMESTAMP}_stderr.log)
EXIT_CODE=$?

# 出力をダンプ
echo "$OUTPUT" > "/tmp/hook_${HOOK_EVENT}_${TIMESTAMP}_output.json"

# 結果を返す
echo "$OUTPUT"
exit $EXIT_CODE