Claude Code hooks の実装ガイド——PreToolUse で mv・sed の上書きを防ぐ設定例と全スクリプト
Claude Code を使っていると「CLAUDE.md に書いたのに守ってくれない」という経験を一度はするはずです。
その根本的な解決策として hooks があります。この記事では、実際に使えるスクリプトと settings.json の設定例をそのまま掲載します。設計の考え方については元記事（Claude Code の hooks はなぜ CLAUDE.md や指示文では代替できないのか）を参照してください。
hooks とは——1行で説明すると
Claude Code がツールを実行する直前・直後に、シェルスクリプトを自動実行できる仕組み。LLM を介さないので確定的に動く。
設定ファイルの場所
.claude/
├── settings.json ← hooks をここに書く（リポジトリ共有）
└── hooks/
├── check-mv-overwrite.sh
├── check-cp-overwrite.sh
└── check-sed-awk-inplace.sh
.claude/settings.json をコミットすると、このリポジトリを触るすべてのエージェント・メンバーに自動適用されます。
settings.json の基本構成
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/check-mv-overwrite.sh"
},
{
"type": "command",
"command": "bash .claude/hooks/check-sed-awk-inplace.sh"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/check-process-completion.sh"
}
]
}
]
}
}
matcher はツール名（Bash / Write / Edit）または *（全ツール）を指定します。
exit code と permissionDecision の早見表
| 返り値 | 動作 |
|---|---|
exit 0 |
通過（ツールをそのまま実行） |
exit 2 + stderr 出力 |
Claude へのフィードバック付きでブロック |
permissionDecision: "ask" |
ユーザーへの確認プロンプトを表示 |
permissionDecision: "deny" |
ツール呼び出しをキャンセルして Claude に理由を送る |
hooks スクリプトは 標準入力から JSON を受け取り、permissionDecision を含む JSON を標準出力に返すか、exit code で返します。
スクリプト①: mv の上書きを防ぐ（check-mv-overwrite.sh）
#!/usr/bin/env bash
# PreToolUse: mv コマンドで移動先ファイルが存在する場合に確認プロンプトを出す
set -euo pipefail
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
# mv コマンドでなければ素通し
if [[ ! "$CMD" =~ ^[[:space:]]*mv([[:space:]]|$) ]]; then
exit 0
fi
# コマンドをトークン分割して最後の引数を DEST とみなす
read -ra TOKENS <<< "$CMD"
DEST="${TOKENS[-1]}"
# オプションフラグは除外
while [[ "$DEST" == -* ]]; do
DEST="${TOKENS[-2]}"
TOKENS=("${TOKENS[@]:0:${#TOKENS[@]}-1}")
done
# 移動先が既に存在する場合のみ確認
if [[ -e "$DEST" ]]; then
cat <<JSON
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"permissionDecisionReason": "上書き警告: $DEST が既に存在します。上書きしますか？"
}
}
JSON
fi
exit 0
スクリプト②: sed の in-place 編集にバックアップを強制（check-sed-awk-inplace.sh）
#!/usr/bin/env bash
# PreToolUse: バックアップなしの sed -i を検知して確認プロンプトを出す
set -euo pipefail
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
emit_ask() {
cat <<JSON
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "ask",
"permissionDecisionReason": "$1"
}
}
JSON
exit 0
}
# sed が含まれていなければ素通し
if [[ ! "$CMD" =~ sed ]]; then
exit 0
fi
# -i.<拡張子> 形式（-i.bak 等）はバックアップあり → 素通し
if [[ "$CMD" =~ -i\.[a-zA-Z0-9_-]+ ]]; then
exit 0
fi
# -i '' (macOS) または -i (GNU) はバックアップなし → 確認
if [[ "$CMD" =~ sed.*-i[[:space:]]+\'\' ]] || [[ "$CMD" =~ sed.*-i[[:space:]] ]]; then
emit_ask "sed -i はバックアップなしの in-place 編集です。-i.bak を推奨します。実行しますか？"
fi
exit 0
スクリプト③: 未完了プロセスがあればセッション終了をブロック（check-process-completion.sh）
#!/usr/bin/env bash
# Stop hook: 進捗ファイルに未完了チェックリストが残っていたら終了をブロック
PROGRESS_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/progress"
if [[ ! -d "$PROGRESS_DIR" ]]; then
exit 0
fi
for file in "$PROGRESS_DIR"/*.md; do
[[ -e "$file" ]] || continue
UNCHECKED=$(grep -n "^- \[ \]" "$file" 2>/dev/null || true)
if [[ -n "$UNCHECKED" ]]; then
echo "⚠️ 未完了のプロセスステップがあります: $file" >&2
echo "$UNCHECKED" >&2
exit 2
fi
done
exit 0
スクリプトに実行権限を付ける
chmod +x .claude/hooks/*.sh
マルチエージェント構成での使い方
.claude/settings.json をコミットするだけで、秘書エージェント・エンジニアエージェント・マーケターエージェントなどすべてのサブエージェントに同一のガードレールが適用されます。個々のエージェント定義に同じルールを書く必要はありません。
エージェントA ──┐
エージェントB ──┼──→ PreToolUse hook ──→ check-mv-overwrite.sh ──→ ブロック or 通過
エージェントC ──┘
CLAUDE.md に書いたルールはエージェントが「読んで判断する」（確率的）のに対し、hooks は「ランタイムが直接実行する」（確定的）という点が本質的な違いです。
元記事
Claude Code の hooks はなぜ CLAUDE.md や指示文では代替できないのか——マルチエージェント環境での安全設計3原則
設計の考え方（なぜ CLAUDE.md では代替できないのか）・ブロック vs 警告の判断基準・タイムアウト設計については元記事で詳しく解説しています。