弾かれるフックより、弾かれないフックのほうが高くつく — matcher 到達可能性を静的に測る

空文字は、意味そのものが反転します

表の一行目です。

空文字を部分一致で当てると 21 ツール全部に一致します。完全一致で当てると 1 つも一致しません。同じ「何も書かれていない文字列」が、実装側の照合方式ひとつで「全部」と「ゼロ」の間を行き来します。

空の matcher は「フィルタを掛けない」つもりで書かれます。その意図は、部分一致の実装では通ります。完全一致の実装では、フック全体が沈黙します。しかも設定としては何も壊れていないので、読み込み時の検査には引っかかりません。

* を書いてしまう間違いは、これよりずっと素直でした。グロブの癖で手が動くのだと思いますが、正規表現としては量指定子の対象がなく、nothing to repeat at position 0 で確実に落ちます。落ちてくれるぶん、こちらは親切です。

Notebook も少し意地が悪い挙動でした。部分一致なら NotebookEdit に当たりますが、完全一致では当たりません。書いた側は「当たっている」と思い込みやすい形です。

Edit と書くと、3 つに当たっていました

もう一つ、自分の設定で実際にやっていたのがこれです。

search("Edit")    → Edit, MultiEdit, NotebookEdit
fullmatch("Edit") → Edit

PostToolUse に matcher: "Edit" を置いて Prettier を走らせていました。狙いは Edit だけです。実際には MultiEdit と NotebookEdit にも乗っていました。3 回に 2 回は、意図していない発火です。

ノートブックが Prettier に通されていたわけで、幸い壊れはしませんでしたが、気持ちのいい話ではありません。

個人開発で自分の端末だけを触っているうちは、この種のずれは誰からも指摘されません。設定を書いた人と設定に困る人が同じなので、困っていることにすら気づけないのです。

hookcheck.py — 到達可能性を静的に検査する

目視では追えないので、検査するものを書きました。設定ファイルとツール名の一覧を渡すと、不達（DEAD）と過剰一致（WIDE）を並べて返します。

見ているのは 4 点です。イベント名が既知の集合に含まれるか。matcher が正規表現としてコンパイルできるか。ツール名の集合に対して 1 つでも当たるか。コマンドの先頭語が実際に解決できるか。

#!/usr/bin/env python3
"""hookcheck.py - フック設定の到達可能性を静的に検査する"""
import json, os, re, shlex, sys, time
 
KNOWN_EVENTS = {
    "PreToolUse", "PostToolUse", "UserPromptSubmit",
    "SessionStart", "SessionEnd", "Stop", "Notification",
}
TOOL_EVENTS = {"PreToolUse", "PostToolUse"}
 
 
def load_tool_universe(path):
    with open(path, encoding="utf-8") as fp:
        return [line.strip() for line in fp if line.strip() and not line.startswith("#")]
 
 
def resolve_command(command):
    try:
        argv = shlex.split(command)
    except ValueError as exc:
        return None, f"シェル構文エラー: {exc}"
    if not argv:
        return None, "コマンドが空です"
    head = argv[0]
    if "/" in head:
        return (head, None) if os.access(head, os.X_OK) else (None, f"実行可能でないパス: {head}")
    for directory in os.environ.get("PATH", "").split(os.pathsep):
        candidate = os.path.join(directory, head)
        if os.access(candidate, os.X_OK):
            return candidate, None
    return None, f"PATH 上に見つかりません: {head}"
 
 
def check(config, tools, semantics="search"):
    findings = []
    for event, groups in config.get("hooks", {}).items():
        if event not in KNOWN_EVENTS:
            findings.append(("DEAD", event, None, f"未知のイベント名: {event}"))
            continue
        for index, group in enumerate(groups):
            where = f"{event}[{index}]"
            matcher = group.get("matcher")
 
            if event in TOOL_EVENTS:
                if matcher is None:
                    findings.append(("DEAD", where, None, "matcher が未定義"))
                else:
                    try:
                        rx = re.compile(matcher)
                    except re.error as exc:
                        findings.append(("DEAD", where, matcher, f"正規表現として不正: {exc}"))
                        rx = None
                    if rx is not None:
                        test = rx.fullmatch if semantics == "fullmatch" else rx.search
                        hits = [t for t in tools if test(t)]
                        if not hits:
                            findings.append(("DEAD", where, matcher, "どのツール名にも一致しません"))
                        elif matcher != ".*" and len(hits) > 1 and not matcher.startswith("^"):
                            findings.append(("WIDE", where, matcher,
                                             f"{len(hits)} 個に一致: {', '.join(hits)}"))
            elif matcher not in (None, "", ".*"):
                findings.append(("DEAD", where, matcher,
                                 f"{event} はツール名を持たないため matcher は評価されません"))
 
            for hook in group.get("hooks", []):
                command = hook.get("command", "")
                _, error = resolve_command(command)
                if error:
                    findings.append(("DEAD", where, command, error))
    return findings
 
 
def main():
    if len(sys.argv) < 3:
        print("usage: hookcheck.py <hooks.json> <tools.txt> [--fullmatch]", file=sys.stderr)
        return 2
    semantics = "fullmatch" if "--fullmatch" in sys.argv else "search"
    with open(sys.argv[1], encoding="utf-8") as fp:
        config = json.load(fp)
    tools = load_tool_universe(sys.argv[2])
 
    started = time.perf_counter()
    findings = check(config, tools, semantics)
    elapsed_ms = (time.perf_counter() - started) * 1000
 
    dead = sum(1 for f in findings if f[0] == "DEAD")
    for level, where, subject, message in findings:
        mark = "x" if level == "DEAD" else "!"
        subject_text = f" [{subject}]" if subject else ""
        print(f"{mark} {where}{subject_text} {message}")
    print(f"\nDEAD={dead} WIDE={len(findings) - dead} semantics={semantics} {elapsed_ms:.2f}ms")
    return 1 if dead else 0
 
 
if __name__ == "__main__":
    sys.exit(main())

ツール名の一覧は、セッションで実際に使えるものを 1 行 1 個で書き出しておくだけです。手で並べるのが面倒なら、起動直後のツール一覧をコピーしておけば足ります。

過剰一致の判定に not matcher.startswith("^") を入れているのは、先頭を明示的に固定してある matcher は「広く当てにいっている」と読めるためです。意図的に広げたものまで警告すると、警告そのものが読まれなくなります。

手元の設定を通してみます

自分の設定に通すと、こう出ました。

$ python3 hookcheck.py hooks.json tools.txt
! PreToolUse[0] [Bash] 2 個に一致: Bash, BashOutput
x PreToolUse[1] [*] 正規表現として不正: nothing to repeat at position 0
x PreToolUse[2] [edit] どのツール名にも一致しません
x PreToolUse[2] [prettier --write] PATH 上に見つかりません: prettier
! PostToolUse[0] [Edit] 3 個に一致: Edit, MultiEdit, NotebookEdit
! PostToolUse[1] 21 個に一致: Bash, BashOutput, KillShell, Read, Write, ...
x PostToolUse[1] [notify-send done] PATH 上に見つかりません: notify-send
x UserPromptSubmit[0] [Bash] UserPromptSubmit はツール名を持たないため matcher は評価されません
x PreCompact 未知のイベント名: PreCompact

DEAD=6 WIDE=3 semantics=search 0.62ms

--fullmatch を付けて、照合方式を変えた場合も見ます。

$ python3 hookcheck.py hooks.json tools.txt --fullmatch
...
DEAD=7 WIDE=0 semantics=fullmatch 0.51ms

DEAD が 6 から 7 へ増え、WIDE が 3 から 0 へ消えました。設定は 1 文字も変えていません。

私はこの二本立てを常用しています。両方の方式で回して差分だけを見る、という読み方です。差が出た matcher は、照合方式の前提に寄りかかっている matcher でした。ドキュメントに照合方式が明記されていない以上、寄りかからないほうが安全でした。

弾かれるほうは、実は安いのです

ここが自分にとっていちばん意外だった部分です。

不達フック（DEAD）は、コストが 0ms です。当たり前ですが、呼ばれないので何も消費しません。実害は「やったつもりの品質チェックがやられていない」という、設計上の穴だけです。読み込み時に拒否されれば、その場で気づけます。

過剰一致（WIDE）は違いました。呼ばれます。毎回呼ばれます。フックの実体はプロセス起動なので、そこに実時間が乗ります。

同じ環境で、何もしないコマンドを 30 回ずつ起動して測りました。

何もしない Node が 31.61ms です。実際のフックはここに自分の処理が乗ります。

matcher: "Edit" で Node 製のフォーマッタを回していた自分の場合、3 回に 2 回が意図しない発火でした。空 matcher が部分一致で解釈される実装なら、全ツール呼び出しに乗ります。ツール呼び出し 50 回のセッションで 1.6 秒、200 回なら 6.3 秒。単純な掛け算ですが、体感としては「今日はなんとなく重いな」に化ける種類の数字です。

照合そのものが重いのではないか、とも疑いました。そちらは測ると無視できる範囲でした。

1,000 本並べても 0.19ms です。コストは全部プロセス起動側に立っていました。

つまり、読み込み時の検査が拾ってくれるのは、コストの安いほうの問題です。高くつくほうは、検査を涼しい顔で素通りしていきます。設定が正しいことと、設定が意図どおりであることは、まったく別の話でした。

CI の 1 ステップに置けるかどうか

検査は速くないと運用に乗りません。グループ数を変えて測りました。

1,000 グループでも検査部 48.28ms、Python の起動を含めて 76.1ms です。人間が現実的に書く規模では、実質ゼロとみなして構いません。

DEAD が 1 件でもあれば終了コード 1 を返すようにしてあるので、そのまま止められます。

python3 tools/hookcheck.py .antigravity/hooks.json tools.txt \
  && python3 tools/hookcheck.py .antigravity/hooks.json tools.txt --fullmatch

自分は両方の方式で二回叩いています。片方だけ通る設定は、環境が変わったときに黙って挙動が変わります。

WIDE のほうは終了コードを分けていません。落とすかどうかは、そのリポジトリで過剰一致をどれだけ許すかによるためです。自分は、警告として毎回目に入る状態で十分でした。

一度だけ通す手順

新しいリポジトリに入るたび、次の順で通しています。5 分もかかりません。

1. セッション開始直後のツール一覧を tools.txt へ 1 行 1 個で書き出す。MCP サーバ由来の名前を落とさないよう、接続が済んでから取ること
2. hookcheck.py を部分一致で実行し、DEAD をゼロにする。ここで出るのは大半が綴りとイベント名
3. 同じ設定を --fullmatch で実行し、DEAD の件数が変わらないことを確認する。変わったら、その matcher を ^ と $ で挟む
4. WIDE の行に並ぶツール名を 1 つずつ読み、意図していないものが混ざっていないか確かめる
5. フックのコマンドを絶対パスか npx / env 経由に直し、もう一度 2 と 3 を回す
6. 両方の実行を CI のステップへ入れて、次に設定を触る人が同じ手順を踏まなくて済むようにする

4 だけは機械に任せられません。何を意図したかを知っているのは書いた本人だけだからです。

公式に書かれていないところ

三点、設定を書き換える前に知っておきたかったことがあります。

照合方式が明記されていないことが多い。部分一致なのか完全一致なのかで、空文字と Edit と Notebook の意味が変わります。分からないなら、両方で検査して差分が出る matcher を避けるのがいちばん確実でした。^ と $ で挟んでおけば、どちらの実装でも同じ結果になります。

コマンド解決は PATH に依存する。prettier は自分の端末では通り、CI では通りませんでした。逆もあります。フックのコマンドは絶対パスにするか、npx や env を明示的に挟むほうが、環境をまたいだときの事故が減ります。検査側も PATH を見ているので、CI で走らせる意味があります。

未知のイベント名は静かに落ちる可能性がある。PreCompact のようなそれらしい名前を書いても、既知の集合になければ何も起きません。既知イベント集合との突き合わせは、正規表現の検査より地味ですが、実際に自分が引っかかったのはこちらでした。

フックの登録タイミングと発火条件の関係については、宣言的なセッション定義へ移したときの経緯をたまに落ちるフックが毎回落ちるようになった話に書いています。あわせて読んでいただけると、どこで何が決まるのかが見通しやすくなるはずです。

設定を疑う順番が変わりました

私自身、以前はフックが動かないときにだけ設定を疑っていました。今は、動いているフックのほうを先に疑います。

読み込み時に拒否してもらえる範囲は広がりました。それでも、拒否されなかったことは「意図どおり」の証明にはなりません。当たる本数を数える、という一手間だけが、そこを埋めてくれました。

まずは自分の hooks.json を、部分一致と完全一致の両方で一度通してみてください。DEAD が 0 でも、WIDE の行に見覚えのないツール名が並んでいたら、そこが毎回 31ms を払っている場所です。

お読みいただきありがとうございました。手元の設定を測り直すきっかけになれば嬉しく思います。