権限モードを変えても止まらない書き込み — サブエージェント用 PreToolUse ゲートを150通りで測る

判定できないときに止まる実装へ書き直す

方針を三つ決めました。

1. 判定は exit 0 + stdout の JSON で返す。 Claude Code は exit 0 のときだけ JSON を解釈します。exit 2 を出すと JSON は無視されるため、どちらか一方に統一する必要があります。
2. 想定外の例外は exit 2 で落とす。 exit 1 では素通りします。判定できないなら止める、をコードで表明します。
3. 判定材料が欠けている入力は deny ではなく ask に上げる。 経路不明の書き込みを一律に拒否すると、正当な作業まで止まります。人間に上げるのが妥当な落としどころでした。

書き直したものが以下です。そのまま .claude/hooks/agent_write_gate.py に置ける形にしてあります。

#!/usr/bin/env python3
"""PreToolUse: サブエージェントの書き込みを agent_type ごとの許可ルートに限定する。
 
Claude Code の規約に合わせた設計:
  - 判定は exit 0 + stdout の JSON で返す（exit 2 との併用は不可）
  - 想定外の例外は exit 2 で落とす（exit 1 は non-blocking error 扱いで素通りする）
  - agent_id / agent_type はサブエージェント内でのみ届く任意フィールド
"""
import json
import os
import sys
 
WRITE_TOOLS = {"Write", "Edit", "NotebookEdit"}
 
# agent_type -> 書き込みを許すルート（絶対パス）
ALLOWED_ROOTS = {
    "doc-writer":         ["/repo/content"],
    "test-runner":        ["/repo/tests", "/repo/fixtures"],
    "my-plugin:reviewer": [],          # 読むだけ。書き込みは一切許さない
}
DEFAULT_ROOTS = []                      # 未知の agent_type は書けない
 
 
def decide(payload):
    """(permissionDecision, reason) を返す。None は「意見なし」。"""
    tool = payload.get("tool_name", "")
    if tool not in WRITE_TOOLS:
        return None, None
 
    agent_type = payload.get("agent_type")
    if agent_type is None:
        # メインスレッドの書き込み。通常のパーミッション評価に委ねる
        return None, None
 
    tool_input = payload.get("tool_input") or {}
    path = tool_input.get("file_path")
    if not path:
        # 経路不明の書き込み。素通しにせず人間に上げる
        return "ask", f"{agent_type} の {tool} に file_path がありません"
 
    path = os.path.normpath(path)
    roots = ALLOWED_ROOTS.get(agent_type, DEFAULT_ROOTS)
    for r in roots:
        r = os.path.normpath(r)
        if path == r or path.startswith(r + os.sep):
            return "allow", f"{agent_type} の許可ルート {r} 配下です"
 
    return "deny", (
        f"{agent_type} に許可された書き込み先は {roots or '（なし）'} です。"
        f"{path} は範囲外のため中止しました"
    )
 
 
def main():
    try:
        payload = json.load(sys.stdin)
        decision, reason = decide(payload)
    except Exception as e:
        # フェイルクローズ。exit 1 だと non-blocking error として書き込みが通る
        print(f"agent-write-gate が判定できませんでした: {e!r}", file=sys.stderr)
        sys.exit(2)
 
    if decision is None:
        sys.exit(0)                     # JSON を出さない＝通常評価へ委ねる
 
    json.dump({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": decision,
            "permissionDecisionReason": reason,
        }
    }, sys.stdout)
    sys.exit(0)
 
 
if __name__ == "__main__":
    main()

hookEventName を hookSpecificOutput の中に入れる点は忘れやすい箇所です。トップレベルに置くと出力が解釈されません。permissionDecisionReason はモデルにも渡るため、再試行を誘発しない言い回しにしておくと無駄な往復が減ります。

同じ150通りを流し直した結果です。

素通り54件がゼロになりました。うち24件は ask として人間に上がり、30件はメインスレッド由来として通常のパーミッション評価へ明示的に委ねられます。同じ「通る」でも、意図した委譲と例外の副作用では意味がまるで違います。

壊れた入力も直接流して確かめました。

接頭辞一致が許可ルートを広げていた

もうひとつ、測るまで気づかなかった穴があります。startswith による許可ルートの判定です。

doc-writer に /repo/content を許可したつもりで、実際には何が通るのかを並べました。

/repo/content で始まる文字列は /repo/content-archive/ も /repo/contentious.txt も含みます。ディレクトリを一段増やしただけで、意図していない領域が許可範囲に入る。修正は区切り文字を明示するだけで、path == r or path.startswith(r + os.sep) とします。

.. を含むパスについては、公式ドキュメントに「Claude Code は ~ と相対パスをフックの実行前に展開する」とあるため、実運用では正規化済みの絶対パスが届きます。os.path.normpath は二重の備えという位置づけですが、ローカルでこのフックを単体テストする場面では効きます。

Windows で運用する場合はもう一段あります。ドキュメントによれば file_path はバックスラッシュ区切りで届くため、Git Bash 上で $PWD が /c/project に見えていても、/src/ のようなスラッシュ表記の比較は一致しません。パスの比較はプラットフォームを意識して書く必要があります。

実行コストを測ってから配線する

PreToolUse は Claude がツールを呼ぶたびに走ります。書き込みの多いパイプラインでは、フック自体の実行時間が積み上がります。同一ペイロードで1,000回実行した実測が以下です。

内訳を取ると、python3 -c pass だけで p50 が 16.8 ms でした。判定ロジックそのものは5 ms 程度で、大半はインタプリタの起動コストです。書き込み1,000回で22秒。許容できる範囲だと判断しましたが、ここを削るなら判定を単一バイナリや常駐プロセスへ寄せる余地があります。数値を持たずに「フックは重そうだから避ける」と決めてしまうのが、いちばん惜しい判断でした。

配線は .claude/settings.json に書きます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/agent_write_gate.py\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

timeout は既定で command 型が600秒です。ポリシーゲートとしては長すぎるので、実測 p99 の 23.7 ms に対して十分な余裕を見た10秒へ落としました。

配線で押さえておくべき挙動が二つあります。ひとつは、条件に一致するフックはすべて並列に走り、deny が defer より、defer が ask より、ask が allow より優先されること。どれか一つでも deny を返せば、他が何を返してもツール呼び出しは止まります。ゲートを分割して足していける設計になっています。

もうひとつは、PreToolUse は Claude がツールを呼んだときにだけ走るという点です。プロンプト内で @ を使って参照したファイルはツール呼び出しを経ずに読み込まれるため、Read にマッチするフックも発火しません。読み取りを止めたい場合は、フックではなく Read の deny ルールを使う必要があります。

本番運用で私が踏んだ注意点

配線した直後、ゲートが何も言わないように見える時間帯がありました。原因は単純で、exit 0 で終えたフックの stderr は デバッグログにしか出ず、トランスクリプトにも Claude にも渡らないという仕様です。print(..., file=sys.stderr) でデバッグ出力を仕込んでも、通常の画面には現れません。私はこの挙動に気づくまで、ゲートが発火していないのかログが出ていないだけなのかを切り分けられませんでした。回避策としては、判定内容を自前のファイルへ追記するか、デバッグログを有効化して確認します。

もうひとつ、フックのプロセスは親の環境変数を引き継ぎますが、OTEL_* のエクスポータ変数だけは Claude Code が生成する全サブプロセスから取り除かれます。判定結果をテレメトリへ流そうと考えている場合、この一点で計装が無言のまま届かなくなります。相関を取りたいなら、共通入力に含まれる prompt_id を自前のログへ記録しておくのが確実です。この場合は OpenTelemetry 側のイベントと後から突き合わせられます。

残っている不確かさ

正直に書いておきたい点があります。

ここで測ったのは、私が書いたゲートスクリプトが PreToolUse の入力仕様に対してどう振る舞うか、です。ターン単位のサブエージェント（Task）からの書き込みについては、agent_id / agent_type が届くことがドキュメントに明記されており、このゲートが効くと考えて差し支えありません。

一方、隔離されたワークフローランタイムで同じフックが発火するかどうかは、私が確認した範囲ではドキュメントに明示がありませんでした。ワークフローを自律実行の中核に据えるなら、ここは自分の環境で確かめてから頼るべき箇所です。確かめ方はそれほど難しくありません。agent_write_gate.py の main() の冒頭に、受け取ったペイロードをそのまま追記するだけの数行を差し込み、ワークフローを一度走らせて、ログに agent_id を持つ PreToolUse が現れるかを見ます。現れなければ、そのランタイムに対してこのゲートは存在しないのと同じです。

次にやること

自動運用を組んでいる方に、まず一つだけ確かめてほしいことがあります。

いま設定している PreToolUse フックに、わざと壊れた JSON を流してみてください。終了コードが 2 以外なら、そのフックはポリシーゲートとして機能していません。判定を間違える以前に、判定しないまま通しています。

私自身、境界を引いた気になっていた期間がそれなりに長くありました。設定ファイルに書いた文字列と、実際に走る挙動は別物です。150通り流すのに要したのはスクリプト二本と数分でした。同じ時間で自分の設定を測り直せるなら、やっておく価値はあると思います。

お読みいただきありがとうございました。

参考

• Hooks reference — Claude Code Docs
• Intercept and control agent behavior with hooks — Claude Code Docs
• Configure permissions — Claude Code Docs