Claude Codeでmainへのpushを2段で止める

Claude Codeでmainへのpushを2段で止める

Claude Code に main ブランチへ直接 push させたくないとき、最初に思いつくのは PreToolUse の hook でコマンドの文字列を見て止める方法です。

ところが文字列の判定は、書き方の揺れで漏れますし、関係のないブランチ名を誤って止めることもあります。

Git の pre-push フックなら、Git が解釈した後の宛先を受け取れるので、書き方の揺れに左右されません。

宛先の判定は pre-push に任せ、hook は pre-push を外す操作を止める役に回すと、2 段の守りが互いの弱点を補えます。

Zenn に、同じ考え方で守りを作り直した記録が公開されていたので、手元で両方の判定に実際のコマンドを流して確かめました。

参考: ブランチ保護のない private リポで、Claude Code の main への push を止める守りを「割り切って」作り直した話

ブランチ保護のない private リポで、Claude Code の main への push を止める守りを「割り切って」作り直した話

前提(最小限)

Claude Code の PreToolUse hook は、Bash などの道具を実行する直前に呼ばれるスクリプトです。

標準入力には JSON が渡され、Bash なら tool_input.command に実行しようとしているコマンドの文字列が入ります。

止めるときは exit 2 で終えるか、exit 0 で permissionDecision を含む JSON を出力します。

hook そのものの考え方は、次の記事にまとめました。

フックとは?AIエージェントの操作をコードで止める仕組み

手元の検証は、Windows 11 の Git for Windows 2.48.1 と Python 3.12.10 で行っています。

hook のスクリプトに JSON を標準入力で渡して判定を確かめたもので、Claude Code(手元は 2.1.234)に組み込んで動かしてはいません。

Claude Code が hook の返事をどう扱うかは、公式ドキュメントの記述をもとに書いています。

参考: Hooks reference – Claude Code Docs

Hooks reference - Claude Code Docs

文字列で止める hook は漏れと誤検知が両方出る

まず、よく見かける形の hook を書いてみました。

コマンドに git push と main が両方含まれていれば、exit 2 で止めるだけのものです。

import json
import re
import sys

data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")

# 文字列に「git push」と「main」が両方あれば止める
if re.search(r"git push", cmd) and "main" in cmd:
    print("main への push は禁止です", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

この hook に 14 通りのコマンドを流したうち、主なものの結果は次のとおりです。

コマンド文字列の hook望む結果
git push origin main止めた止めたい
git push(main にいて上流も main)通した止めたい
git push origin HEAD(main にいる)通した止めたい
git -C . push origin main通した止めたい
git 'push' origin main通した止めたい
git push origin feature:main止めた止めたい
git push origin maintenance止めた通したい
git push -u origin feature/login通した通したい

止めたい形のうち 4 つが通り、通したい maintenance への push は止まりました。

git push や git push origin HEAD は、文字列に宛先が書かれていません。

今どのブランチにいるかを知らない hook には、判定のしようがないのです。

git -C . push と git 'push' は、Git にとっては同じ push ですが、文字列の上では git push と並んでいません。

Claude Code の権限ルールにも同じ限界があり、公式ドキュメントは Bash(git push *) の deny ルールが git -C . push origin main や git 'push' origin main を止めないと明記しています。

そのうえで、こうしたルールはプログラムの周りのセキュリティ境界ではない、と説明しています。

参考: Configure permissions – Claude Code Docs

Configure permissions - Claude Code Docs

pre-push は Git が解釈した後の宛先を受け取る

pre-push は、git push が送る直前に Git が呼ぶフックです。

標準入力には、送るものごとに「ローカルの ref・そのオブジェクト名・リモートの ref・そのオブジェクト名」が 1 行で渡されます。

フックが 0 以外で終わると、git push は何も送らずに中止します。

リモートの ref が refs/heads/main なら止めるだけの pre-push を書きました。

#!/bin/sh
# 標準入力: <local-ref> <local-sha> <remote-ref> <remote-sha>
while read local_ref local_sha remote_ref remote_sha; do
  echo "pre-push: $local_ref -> $remote_ref" >&2
  case "$remote_ref" in
    refs/heads/main|refs/heads/master)
      echo "pre-push: $remote_ref への push は止めました" >&2
      exit 1
      ;;
  esac
done
exit 0

一時フォルダに bare のリモートと作業用のリポジトリを作り、.git/hooks/pre-push に置いて push を試しました。

コマンドいるブランチpre-push に届いた宛先結果
git push origin featurefeaturerefs/heads/feature通った
git push origin feature:mainfeaturerefs/heads/main止めた
git push origin HEAD:mainfeaturerefs/heads/main止めた
git -C . push origin feature:mainfeaturerefs/heads/main止めた
git push(上流は origin/main)mainrefs/heads/main止めた
git push origin HEADmainrefs/heads/main止めた
git push origin mainmainrefs/heads/main止めた

文字列の hook が見落とした git push と git push origin HEAD も、Git が上流と HEAD を展開した後の refs/heads/main として届いています。

ローカル側は HEAD と書いたまま渡される一方で、リモート側の宛先はいつも完全な ref の形で届きました。

宛先を見るなら、文字列を読むより Git に解釈させた後で見るほうが確実です。

参考: Git – githooks Documentation

pre-push にも外し方がある

ただし、pre-push にも弱点があります。

git push の --no-verify は pre-push を飛ばすオプションで、Git のドキュメントにもフックを完全に迂回すると書かれています。

手元でも、main にいて git push --no-verify origin main を実行すると、pre-push は呼ばれずにリモートの main が進みました。

git -c core.hooksPath=<空のフォルダ> push origin main のように、その場でフックの置き場所を変えたときも素通りでした。

2 段目の pre-push は、1 段目がこの 2 つの書き方を止めて初めて守りとして効きます。

参考: Git – git-push Documentation

hook はいつもの形と外す操作に絞る

そこで、1 段目の hook の役目を次の 3 つに割り切りました。

  • pre-push を外す書き方(--no-verify・core.hooksPath)は拒否する
  • いつもの形 git push [-u] origin <ブランチ> だけを読み、宛先が main なら拒否する
  • それ以外の push は、拒否ではなく確認(ask)に回す

確認にしておけば、判定が外れても作業が一度止まるだけで、人が宛先を見て決められます。

ROUTINE = re.compile(r"git push (-u )?origin ([A-Za-z0-9._/-]+)")
PROTECTED = {"main", "master"}
BYPASS = re.compile(r"--no-verify|core\.hooksPath")
# 略(decide() は permissionDecision の JSON を出力して exit 0)

try:
    cmd = json.load(sys.stdin)["tool_input"]["command"].strip()
    if not re.search(r"\bpush\b", cmd):
        sys.exit(0)  # push と無関係なら何も言わない
    if BYPASS.search(cmd):
        decide("deny", "pre-push を外す push は使えません")
    m = ROUTINE.fullmatch(cmd)
    if m and m.group(2) in PROTECTED:
        decide("deny", "main への push は禁止です。作業ブランチに push してください")
    if m and m.group(2) != "HEAD":
        sys.exit(0)  # いつもの形は通常の権限確認に任せる
    decide("ask", "いつもと違う形の push です。宛先を確かめてください")
# 略(例外の扱いは次の見出しで)

decide() が出力するのは、hookSpecificOutput の中に permissionDecision と permissionDecisionReason を入れた JSON です。

同じ 14 通りを流した結果を並べます。

コマンド作り直した hook
git push origin maindeny
git pushask
git push origin HEADask
git push origin feature:mainask
git -C . push origin mainask
cd repo && git push origin mainask
git 'push' origin mainask
sh -c 'git push origin main'ask
git push origin maintenance何も返さない
git push -u origin feature/login何も返さない
git push --no-verify origin feature/logindeny
git -c core.hooksPath=/dev/null push origin maindeny
git status何も返さない
bash scripts/release.sh何も返さない

maintenance への push といつもの作業ブランチへの push は、hook が何も返さないので、Claude Code のふだんの権限確認に任されます。

公式ドキュメントによると、ask の理由はユーザーへの確認画面に表示され、deny の理由は Claude に伝わります。

複数の hook が別々の答えを返したときは、deny が ask より優先されるとも書かれています。

判定が落ちたときの倒れ方は 2 段で逆

hook のスクリプト自体が壊れたときの動きも、2 段で違います。

Claude Code の PreToolUse hook は、0 と 2 以外の終了コードや起動の失敗を止めないエラーとして扱い、道具はそのまま実行されます。

Python の例外で落ちると終了コードは 1 なので、判定の書き損じ 1 つで守りが素通りになるわけです。

そこで上の hook は、例外を受け取ったら exit 2 で終えるようにしました。

壊れた JSON を標準入力に渡すと、手元でもエラーの理由を出して exit 2 で終わりました。

終了コードごとの動きと、失敗したら止める新しい設定は、別の記事で試しています。

Claude Codeのhookはexit 1では止まらない

pre-push のほうは、0 以外で終われば push が中止されるので、もともと止める側に倒れます。

存在しないコマンドを呼ぶだけの壊れた pre-push に差し替えると、作業ブランチへの push も failed to push some refs で止まりました。

登録のしかたと残る穴

1 段目の hook は、プロジェクトの .claude/settings.json に matcher を Bash として登録します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python \"${CLAUDE_PROJECT_DIR}/.claude/hooks/guard_push.py\""
          }
        ]
      }
    ]
  }
}

この設定の形は公式ドキュメントの例に合わせたもので、手元の Claude Code では読み込みまでは試していません。

2 段目の pre-push は .git/hooks に置くファイルで、リポジトリの中身としては管理されません。

手元でも、pre-push を入れたリポジトリを git clone した先の .git/hooks には、pre-push がありませんでした。

clone し直したときや別の作業フォルダでは、入れ直しが要ります。

この 2 段でも、塞げない経路は残ります。

たとえば bash scripts/release.sh の中に git push --no-verify が書かれていれば、hook は push の語を見ないので通し、pre-push も飛ばされます。

matcher を Bash にした hook は、Edit や Write の道具で .git/hooks を書き換える呼び出しにも反応しません。

手元の守りは取り違えや誘導を止める網と考え、壁が要るなら GitHub のブランチ保護ルールのように、サーバー側で止める仕組みを使ってください。

参考: About protected branches – GitHub Docs

About protected branches - GitHub Docs

最後に

文字列を読む hook で push の書き方を全部追いかけると、漏れか誤検知のどちらかが残ります。

宛先の判定は Git が解釈した後の pre-push に任せ、hook は pre-push を外す書き方の拒否と、見慣れない形の確認だけを受け持つ形にしました。

2 つの守りが互いの弱点を塞いでいるかは、実際のコマンドを流して表にすると確かめられます。

以上です。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA