🔍

🔍 「完了」を信用しない：StopフックがJSONLを読んでLLMの出力を強制する

#automation#claudecode#副業2026-09-07 · 約30分

月10万の大学生だった頃、作業を人に任せることへの信頼感は「丁寧に頼む」「進捗を聞く」「信じる」の3ステップで成立していると思っていました。今は違います。月商120万の今、信頼は仕組みが担保するものだと知っています。LLMも同じです。

なぜこの仕組みが効くのか

LLMに実装を任せ始めると、必ずぶつかる壁があります。

「実装しました。」「テストが通っています。」「完了です。」

この3行の後、実際に動かしてみると壊れている。あるいは、確かに動いてはいるが肝心なエラーハンドリングが抜けている。境界値でゼロ除算する。並行実行で競合する。こういう「完了と言っているが完了していない」状態は、LLMを使う開発の最大のノイズです。

指摘すれば直してくれます。でも、指摘するためには自分が細部まで追いかけなければならない。それでは人間の目を通すコストが高すぎて、自律化の意味がありません。

解決策は「LLMが自分で自分の出力を審査する習慣を、ハードウェアレベルで強制すること」です。

ポイントは「習慣」ではなく「強制」という語です。LLMはプロンプトで「必ずセルフ監査してください」と書けば一定確率で従います。でも一定確率は100%ではありません。セッションが長くなれば指示は薄まり、モデルの調子によって省略されます。プロンプトで習慣づけようとするのは、貼り紙で安全を担保しようとするのと同じです。

Stopフック＋PostToolUseフックの組み合わせは、そこを仕組みで解決します。**LLMがセッションを終了しようとした瞬間に、その出力テキストをシェルスクリプトが読んで、キーワードが無ければ exit 2 でブロックする。**LLMは自分の「完了」宣言を自分のハーネスに拒否される体験をします。

プロンプトを忘れても、モデルが違っても、セッションが10時間続いても、このフックは走ります。環境が監査を要求するので、監査は習慣ではなく物理的な必要条件になります。

もう一つ重要な設計判断があります。作業が無かったターンはフックを黙らせる、という点です。

LLMと会話するだけのターン、調査だけして何も書かなかったターンに「監査してください」と毎回出てきたら、それは監査ではなくノイズです。実際、最初のバージョンでは全ターンに監査要求が出ていました。2026-07-11のパフォーマンス監査で「監査が儀式化して本題を壊している」という評価が下り、「変更があったターンにだけ発火する」設計に変わりました。

この「変更のあったターンだけ」を実現するために、2つのフックが連携します。

PostToolUseフック（audit_flag_set.sh）が「ファイルを書いた・編集した」イベントを受け取ってフラグファイルを立て、Stopフック（self_audit_stop.sh）がそのフラグを拾う。フラグが無ければ黙る。フラグがあれば出力テキストを精査する。この2フック連携によって、静かに動くべき時は静かで、監査が必要な時だけ声を上げる構造が完成します。

加えて、もう一つの落とし穴への対処が組み込まれています。sdk-cli経由の無人自動化セッションへの対応です。

launchdで深夜に走る自動化バッチ、Agent SDK経由のパイプライン実行、こういった無人セッションに監査要求を出しても読む人間はいません。2026-07-12、一晩で sdk-cli 自動化が19件走り、stderr に監査要求が19件積まれるという事態が発生しました。以来、セッション先頭15行を読んで "entrypoint":"sdk-cli" が含まれていれば即スキップする処理が入っています。人間のいるセッションにだけ語りかける、という判断です。

そしてセッション当たり最大2回という上限も設けています。同じセッション内で何度も「監査してください」が出ると、モデルが反応するたびにまた監査が走り、ループが起きるリスクがあります。セッション別のカウンタファイルで2回を超えたら黙る、という安全弁です。

この仕組みが効く理由を一言でまとめると、**「人間がルールを守ることに期待するのではなく、ルールを破れない構造を作る」**という設計思想です。自律化とはLLMを信頼することではなく、LLMが信頼できる状態を強制することです。

全体の流れ

まずフック連携の全体像をアスキー図で把握します。

Claude Code セッション
│
├─ ツール実行（Write / Edit）
│    │
│    └─ PostToolUseフック ─► audit_flag_set.sh
│                               └─ touch /tmp/claude-audit-pending-{sid}
│
│  （LLMが「完了」と言おうとする）
│
└─ Stop イベント
     │
     └─ Stopフック ─► self_audit_stop.sh
                         │
                         ├─ フラグ確認: /tmp/claude-audit-pending-{sid}
                         │    なし → exit 0（黙って通す）
                         │    あり ↓
                         │
                         ├─ entrypoint確認（sdk-cli？）
                         │    sdk-cli → rm flag; exit 0（無人スキップ）
                         │    human ↓
                         │
                         ├─ 回数確認: /tmp/claude-audit-prompted-{sid}
                         │    ≥ 2 → rm flag; exit 0（上限到達）
                         │    < 2 ↓
                         │
                         ├─ transcript JSONL を Python でパース
                         │    └─ 最後の assistant テキストを抽出
                         │
                         ├─ 監査キーワード検索
                         │    あり → exit 0（合格・無音）
                         │    なし ↓
                         │
                         └─ exit 2（ブロック）
                              └─ stderr に促しメッセージ → LLMへ

PostToolUseフック: audit_flag_set.sh（全6行）

#!/bin/bash
# PostToolUse(Write|Edit): このターンでファイル変更があった印をセッション別に立てる。
# Stopフック(self_audit_stop.sh)が拾って、セルフ監査の出し忘れを促す。
sid=$(/usr/bin/python3 -c 'import sys,json;print(json.load(sys.stdin).get("session_id",""))' 2>/dev/null)
[ -n "$sid" ] && touch "/tmp/claude-audit-pending-${sid}" 2>/dev/null
exit 0

このフックはシンプルです。Claude Code が Write または Edit ツールを実行するたびに呼ばれ、stdin から JSON を受け取って session_id を抜き出し、/tmp/claude-audit-pending-{sid} というゼロバイトファイルを作るだけです。touch の失敗は無視（2>/dev/null）し、常に exit 0 で通します。

ポイントは「フラグを立てるだけ」という責務の明確さです。判断はすべて Stopフック側に委ねます。

Stopフック: self_audit_stop.sh の実装詳解

Stopフックは67行あります。各ブロックを順に読んでいきます。

① セッションID・トランスクリプトパスの取得

input=$(cat)
get() { /usr/bin/python3 -c "import sys,json;print(json.load(sys.stdin).get('$1',''))" 2>/dev/null; }
sid=$(printf '%s' "$input" | get session_id)
tpath=$(printf '%s' "$input" | get transcript_path)

input=$(cat) で stdin をバッファリングし、get 関数で JSON フィールドを取り出します。/usr/bin/python3 をフルパス指定しているのは、シェルフックが実行される環境では PATH が最小構成になっていることがあるためです。

② フラグ確認（変更のないターンをスキップ）

flag="/tmp/claude-audit-pending-${sid}"
[ -n "$sid" ] && [ -f "$flag" ] || exit 0

$flag ファイルが存在しなければ即 exit 0。これで「ファイルを触らなかったターン」はすべてスルーされます。

③ sdk-cli 検出（無人自動化スキップ）

if [ -n "$tpath" ] && [ -f "$tpath" ] && head -15 "$tpath" 2>/dev/null | grep -q '"entrypoint":"sdk-cli"'; then
  rm -f "$flag"
  exit 0
fi

トランスクリプト JSONL の先頭15行を読み、"entrypoint":"sdk-cli" が含まれていれば無音スキップします。JSONL のメタデータブロックは先頭数行に固まっているため、ファイル全体を読まずに head -15 で判定できます。フラグは消してから抜けます（残すと次のセッションに持ち越さないよう）。

④ セッション当たり2回上限

prompted="/tmp/claude-audit-prompted-${sid}"
count=$(cat "$prompted" 2>/dev/null || echo 0)
if [ "$count" -ge 2 ]; then rm -f "$flag"; exit 0; fi

/tmp/claude-audit-prompted-{sid} に数値を書き込み、2以上なら黙ります。このカウンタは $((count + 1)) でインクリメントし、ブロック時に書き直します（後述）。

⑤ JSONL を Python で直接パース：最後の assistant テキスト抽出

last=$(/usr/bin/python3 - "$tpath" <<'PY'
import sys, json
msgs = []
try:
    for line in open(sys.argv[1], encoding="utf-8"):
        line = line.strip()
        if not line:
            continue
        try:
            o = json.loads(line)
        except Exception:
            continue
        if o.get("type") == "assistant" or o.get("role") == "assistant":
            m = o.get("message", o)
            c = m.get("content")
            if isinstance(c, list):
                for b in c:
                    if isinstance(b, dict) and b.get("type") == "text":
                        msgs.append(b.get("text", ""))
            elif isinstance(c, str):
                msgs.append(c)
except Exception:
    pass
print(msgs[-1] if msgs else "")
PY
)

ここがこのフックの核心です。Claude Code のトランスクリプトは JSONL（1行1オブジェクト）で保存されています。Python で1行ずつ読み、type == "assistant" または role == "assistant" の行を探し、content を取り出します。

content が配列の場合（ツール呼び出しと混在するリッチ形式）は type == "text" のブロックだけを集めます。文字列の場合はそのまま追加します。最後に msgs[-1]、すなわち直近のassistantテキストメッセージだけを返します。

try / except でエラーを握りつぶしているのは意図的なフェイルオープン設計です。トランスクリプトが壊れていても、読み込みに失敗しても、ブロックしない。誤爆よりも見逃しを許容する設計です。

⑥ 監査キーワード検索とブロック

rm -f "$flag"
[ -z "$last" ] && exit 0

if printf '%s' "$last" | grep -qE '監査|潰した|既に堅牢|あえて見送り|セルフ監査|三層|予測できる不具合'; then
  exit 0
fi

echo $((count + 1)) > "$prompted"
echo "⚠️ セルフ監査未実施。実装/配線したなら敵対的監査(並行/失敗時/冪等/境界/秘密値/実検証)を済ませ、報告は**3行以内**で(要点のみ・表や長文禁止=2026-07-11フィードバック)。軽微なら『監査不要:理由』の一言で良い。" >&2
exit 2

フラグは先にここで消します（ループ防止）。$last が空なら読み取り失敗なのでフェイルオープンで通過。

exit 2 がなぜブロックになるのかという点を補足します。Claude Code のフックは終了コードで動作を制御します。exit 0 は正常通過、exit 2 は「モデルにフィードバックを返して継続を促す」という意味を持ちます。stderrに書いたメッセージはそのままモデルへのフィードバックとして渡され、モデルは「なぜ止められたか」を読んで監査を書き直します。

このメッセージに 2026-07-11フィードバック という日付注記が入っているのも実際のコードそのままです。最初は長い表形式の監査を要求していましたが、「表や長文禁止・3行以内」というフィードバックが入り、メッセージ文言が更新されました。フックのコメントはその経緯の記録です。

実装の詳細

なぜシェルスクリプトか

self_audit_stop.sh はBashで書いてあります。Claude Codeのフックは package.json のある環境であればNodeでも書けますが、私はあえてシェルにしています。理由は「フックが起動する環境は最小構成のシェルだから」です。

hooks.json を見ると、ECC（Everything Claude Code）のフックはほぼすべてNodeのワンライナーで書かれています。Nodeでも問題はありませんが、Nodeが走るためには node へのPATHが通っている必要があります。私の環境ではnvmでNodeを管理しているため、インタラクティブシェル（.zshrcが読まれる状態）ではPATHが通りますが、launchd経由の最小シェルでは通らない。ECC側は自前でNode実行パスをエントリーポイントに埋め込むことで解決していますが、それをカスタムフックに毎回書くのは過剰です。

シェルスクリプトなら #!/bin/bash で確実に /bin/bash が使われます。Python呼び出しだけはPATHに依存しないよう /usr/bin/python3 をフルパス指定しており、それだけ覚えておけばあとはシェル組み込みで済む。依存がゼロで確実に動くことが、監査フックに求める最大の性質です。フックが動かなければ監査が素通りになるので、フック自体は限りなくシンプルにします。

フェイルオープン設計の哲学

コードの複数箇所に || exit 0、2>/dev/null、try / except: pass が散っています。これは意図的なフェイルオープン設計です。

[ -z "$last" ] && exit 0            # 読めなければフェイルオープン

except Exception:
    pass
print(msgs[-1] if msgs else "")

トランスクリプトが読めない状況は実際に起きます。セッションが突然切れてJSONLが不完全なまま残っているとき、ファイルシステムの権限が変わっているとき、Pythonのパース中にUnicodeエラーが出るとき。こういった異常系で exit 2 を返すと、何もしていないのにモデルがブロックされます。

誤ブロックのコストは、見逃しのコストより高い。見逃した監査は次のターンで（フラグが立てば）また拾えます。でも誤ブロックはモデルが「なぜ止められたか」を解釈しようとして余計なターンを消費し、場合によってはフックへの信頼が失われます。「またフックが誤作動した」と判断されたら、そのフックは実質無効です。

エラーは黙って通す。監査のかけ忘れより、フックへの不信任のほうが長期ダメージが大きい。この判断がフェイルオープン設計の根拠です。

キーワード7パターンの選定基準

if printf '%s' "$last" | grep -qE '監査|潰した|既に堅牢|あえて見送り|セルフ監査|三層|予測できる不具合'; then
  exit 0
fi

7パターンを見ると、大きく3種類に分かれます。

**「監査」「セルフ監査」**は最も直接的なマーカーです。私がCLAUDE.mdで「敵対的セルフ監査を済ませ」と指示しているので、モデルが従えば必ずこの語を含む文を書きます。

**「潰した」「既に堅牢」「あえて見送り」**は3区分報告の語彙です。「潰した（対処済み）/ 既に堅牢（対処不要）/ あえて見送り（意図的に後回し）」という3区分で報告するよう指示しているので、このどれかが含まれれば監査は実施されている。

**「三層」「予測できる不具合」**は補助的なマーカーです。深い監査をするとき自然に出てくる語ですが、これは将来的に削除する候補でもあります。語が具体すぎると、モデルが「この語を含めれば通る」とショートカットを学習するリスクがあります。

マーカーキーワードは定期的に見直すのが正解です。モデルが「監査しました」だけで通そうとする傾向が強くなれば、より具体的な語へ差し替えます。

フックの登録：settings.jsonへの書き方

audit_flag_set.sh と self_audit_stop.sh は、Claude Codeのユーザーレベル設定（~/.claude/settings.json に相当）のフックセクションで登録します。実際の設定形式は次の通りです。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/audit_flag_set.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/self_audit_stop.sh"
          }
        ]
      }
    ]
  }
}

matcher に Write|Edit と書くのがポイントです。* にするとBashツールの実行にも反応してフラグが立ち、「コマンドを走らせただけで監査が要求される」という誤発火が起きます。ファイルを書いたターンにだけ監査を求めたいので、ファイル書き込み系ツールだけにマッチさせます。

MultiEditも含めたい場合は Write|Edit|MultiEdit にします。私の環境では MultiEdit の使用頻度が低いのでデフォルトでは外しています。

私が詰まった話

詰まり①：全ターンで監査要求が出てセッションがうるさくなった

一番最初のバージョンにはPostToolUseフックがありませんでした。Stopフックだけで「毎回監査を要求する」という実装でした。

# 最初期の誤った設計（フラグなし）
last=$(python3 でJSONLを読む)
if printf '%s' "$last" | grep -qE '監査|...'; then
  exit 0
fi
exit 2

症状：会話しただけのターン、調査しただけのターン、既存コードを読んだだけのターンにも全部「セルフ監査を実施してください」が出ました。1時間のセッションで監査要求が20回以上積まれ、本題の議論のあいだに「監査してください」が割り込んでくる状態になりました。

原因：「何かを変更したターン」と「会話だけのターン」を区別する仕組みがなかったことです。

直し方：PostToolUseフックで /tmp/claude-audit-pending-{sid} を立て、Stopフックでそのフラグの有無を最初に確認する設計に変更しました。フラグがなければ即 exit 0。これでファイル書き込みが発生したターンだけに絞られます。

CLAUDE.mdに「2026-07-11のパフォーマンス監査で「監査が儀式化して本題を壊している」という評価が下り」と記録されているのは、この改修を決断したきっかけです。監査が毎回出ると、モデルも私も「またか」という慣れが生じて、形式的な一行を書くだけのルーティンになります。少ない回数で確実に効かせるほうが、監査の重みが保たれます。

詰まり②：深夜に自動化バッチが走るたびstderrがspamされた

launchdで深夜2時に走る画像生成自動化バッチがあります（Obsidianの hot.md に記録されているai-portraitsの自動化です）。このバッチはAgent SDK経由でClaude Codeセッションを立ち上げ、処理を実行して終了するという無人フローでした。

Stopフックを追加した翌朝、ログを見たら異変がありました。stderrに「⚠️ セルフ監査未実施。」が19件並んでいました。

症状：無人の自動化セッションに毎回監査要求が出て、stderr に積まれるが誰も読まない。9時間後に私が発見するまで何の意味もない警告が出続けていました。

原因：フックが「誰が実行しているか」を区別していなかったことです。人間がインタラクティブに使うセッションと、Agent SDK経由の無人バッチセッションを同じロジックで処理していました。

直し方：トランスクリプトJSONLの先頭15行を読み、"entrypoint":"sdk-cli" が含まれているかを確認する処理を追加しました。

if [ -n "$tpath" ] && [ -f "$tpath" ] && head -15 "$tpath" 2>/dev/null | grep -q '"entrypoint":"sdk-cli"'; then
  rm -f "$flag"
  exit 0
fi

head -15 で先頭だけ読むのは、JSOLのメタデータが先頭に固まっているためです。ファイル全体を読む必要はなく、15行で十分判定できます。このフラグはClaude Codeがセッション開始時に書き込むもので、sdk-cliエントリーポイントはその値が "sdk-cli" になります。

コードのコメントに 2026-07-12: 一晩でsdk-cli自動化19件がstopspamを埋めた と残しているのは、この事件の記録です。フックを書いた翌日に即座に発生したので、設計漏れとして記憶させています。

詰まり③：監査ループが起きてセッションが止まらなくなった

フラグとsdk-cli検出を入れた後、新しい問題が出ました。監査を書いたターンの次のターンでもう一度監査が要求されるループです。

症状の詳細：

モデルが実装を書く → PostToolUseでフラグが立つ
モデルが「完了」と言う → Stopフックが走る → フラグあり・監査なし → exit 2 でブロック
モデルが監査を書く → このターンでもPostToolUseが走るわけではないが、Stopがまた走る
しかし rm -f "$flag" のタイミングが後ろ過ぎて、前のフラグが残っていた

これは実際にはフラグの消し忘れではなく、初期実装でフラグを消す位置が間違っていたことが原因でした。最初は「キーワードが見つかったらフラグを消す / 見つからなかったらフラグを消さず exit 2」という流れで書いていました。

# 誤った設計（フラグ消しのタイミングが遅い）
if grep -qE '監査|...'; then
  rm -f "$flag"   # 合格時だけ消す
  exit 0
fi
exit 2            # 不合格時はフラグが残る

症状：不合格でブロック→モデルが監査を書く→次のStopでまたフラグあり→またブロック。同じセッション内で「監査してください」が連続して出ます。

直し方：フラグはexit 2の分岐に入る前に必ず消す設計に変えました。

rm -f "$flag"                       # 単発: このターンのflagは必ず消す(ループ防止)
[ -z "$last" ] && exit 0

if printf '%s' "$last" | grep -qE '監査|...'; then
  exit 0
fi

echo $((count + 1)) > "$prompted"
exit 2

フラグはチェックの結果に関係なく、Stopフックが走った時点で消します。次のStopで同じセッションIDのフラグが残るのは「そのターンでまたファイルを書いた場合だけ」に限定されます。

加えて、同一セッション内で2回まで、という上限も設けました。

count=$(cat "$prompted" 2>/dev/null || echo 0)
if [ "$count" -ge 2 ]; then rm -f "$flag"; exit 0; fi

カウンタファイルに1か2を書き、2以上になったら黙る。これでループの安全弁が完成しました。

詰まり④：JSOLのcontentが配列の場合、テキストが全部空になった

Pythonのパース部分も一筋縄ではいきませんでした。初期実装はこうでした。

# 誤った実装（contentが文字列前提）
c = m.get("content")
if isinstance(c, str):
    msgs.append(c)

Claude Codeのトランスクリプトは、テキストだけのレスポンスでは content が文字列です。しかしツール呼び出しと混在するターン（つまり「コードを読んでから実装する」という典型的なターン）では content は配列になります。

{
  "role": "assistant",
  "content": [
    {"type": "text", "text": "ここで実装しました。"},
    {"type": "tool_use", "id": "...", "name": "Write", "input": {...}}
  ]
}

このフォーマットで isinstance(c, str) は偽になり、テキストが取れません。msgs が空のまま print(msgs[-1] if msgs else "") に到達し、空文字列が返ります。空文字列はフェイルオープンで exit 0 になるので、監査要求が出なくなります。つまり「監査が必要なターンが常に素通りになる」というサイレントバグです。

症状として気づいたのは「実装のターンに全く監査要求が出ない」でした。調査ターンは正しく素通りするのに、実装ターンでも出ないのはおかしい。フックをデバッグして $last の中身を見ると空文字列になっており、Pythonのロジックをトレースして配列形式のハンドリング漏れに気づきました。

修正後は配列と文字列の両方を処理します。

c = m.get("content")
if isinstance(c, list):
    for b in c:
        if isinstance(b, dict) and b.get("type") == "text":
            msgs.append(b.get("text", ""))
elif isinstance(c, str):
    msgs.append(c)

配列の場合は type == "text" のブロックだけを集め、ツール呼び出しのブロックは無視します。このロジックに変えてから、実装ターンで確実に監査要求が出るようになりました。

詰まり⑤：監査メッセージが長すぎてモデルが従わなかった

最初の exit 2 の際のメッセージはこうでした。

セルフ監査を実施してください。以下の観点を表形式で報告してください。
| 観点 | 状態 | 詳細 |
|------|------|------|
| 並行 | | |
| 失敗時 | | |
| 冪等 | | |
（中略）

8行の表テンプレートを含む、200字近いメッセージでした。

症状：モデルが表を埋めようとして15〜20行の監査報告を毎回書くようになりました。報告自体は丁寧でしたが、「3ファイル書き換えた軽微な修正」でも20行の表が出てきます。本題の実装の議論が監査の表に埋もれてしまい、セッションの読み返しが困難になりました。

2026-07-11のフィードバックは「表や長文禁止・3行以内」でした。

直し方：メッセージを1行の指示に圧縮しました。

echo "⚠️ セルフ監査未実施。実装/配線したなら敵対的監査(並行/失敗時/冪等/境界/秘密値/実検証)を済ませ、報告は**3行以内**で(要点のみ・表や長文禁止=2026-07-11フィードバック)。軽微なら『監査不要:理由』の一言で良い。" >&2

「軽微なら『監査不要:理由』の一言で良い」という逃げ道を作ったのが効いています。これを入れることで、本当に軽微な変更では「監査不要:定数変更のみ」という1行で完結するようになりました。重要な変更では「潰した：並行書き込みは atomic rename で対処済み」という1〜2行が出ます。

観点を列挙しながら「3行以内」という制約を組み合わせることで、「監査を形式的に通過させるための長い表」ではなく「本当に問題があれば1行で指摘する」という行動に変わりました。監査の量ではなく質を上げる変更です。

つまずきポイント

前半で書いた5つの詰まりは実装ロジックの話でした。ここでは設定・環境・運用面で引っかかりやすい点を網羅します。私が実際に踏んだもの、コミュニティで見かけたものを箇条書きにします。

設定・環境まわり

settings.json 内のパスに ~ を使った：シェルの ~ 展開は、フックが呼ばれる最小環境では起きないことがある。settings.json のコマンドパスは展開済みの絶対パスで書く。/Users/自分のユーザー名/.claude/hooks/audit_flag_set.sh のように直接指定する（この記事では読みやすさのため ~ 表記を使っているが、実際のファイルは絶対パス）。
chmod +x を忘れた：フックを登録した、ファイルもある、でも何も起きない——の大半はこれ。ls -la ~/.claude/hooks/ で -rwxr-xr-x になっているか確認。なければ chmod +x ~/.claude/hooks/*.sh で付与する。Git管理している場合は git add --chmod=+x するか .gitattributes に *.sh eol=lf text eol=lf と実行ビット設定を入れておく。
settings.json のフォーマットを間違えた：hooks.PostToolUse は配列の中にオブジェクト、その中にまた hooks 配列が入る二重構造。JSON構造のミスはClaude Codeがサイレントに無視するだけでエラーが出ない。フック登録後は必ず jq . ~/.claude/settings.json で整形して目視確認する。jq がなければ python3 -m json.tool ~/.claude/settings.json でも可。
matcher に Write|Edit|Bash と書いた：Bashツールの実行（grepやコマンド実行）でもフラグが立ち、「コードを調べただけのターン」に監査要求が出る。Write|Edit（または Write|Edit|MultiEdit）に限定する。MultiEditを追加するかどうかはMultiEditの使用頻度次第。
/usr/bin/python3 が存在しない：macOS でもXcode Command Line Toolsを入れていない場合、/usr/bin/python3 自体が「インストールしますか？」を聞いてくる状態になっている。フックの中でこれが走ると対話プロンプトが出て止まる。xcode-select --install を事前に済ませるか、Homebrewの python3 を使う場合はフルパス（/opt/homebrew/bin/python3 など）に書き直す。

JSONL パース・実行タイミングまわり

セッション開始直後の最初のターンでフックが素通りした：tpath が渡されていても、トランスクリプトファイルの書き込みがフックより後になるケースがある。[ -f "$tpath" ] が偽になり last が空、フェイルオープンで通過する。初回ターンは「まだ書いた直後」という状態なので実害は少ない。
JSONL の末尾が不完全な行で終わっていた：LLMの応答が長い場合、トランスクリプトへの書き込みとStopフックの実行がレースコンディションを起こす。末尾の行が途中で切れた JSON になり json.loads が例外を投げる。try / except: continue で行単位にスキップしているため実害はなく、1つ前の完全な assistant メッセージを使って判定する。
content が None のターン：ツール呼び出しだけを含むassistantメッセージ（テキストブロックを持たない）では m.get("content") が None を返す。isinstance(None, list) も isinstance(None, str) も偽なので msgs に何も追加されない。これは意図通りの動作で、テキストを持たないターンは素通りする。
セッションIDが空文字になる：stdin JSON に session_id が含まれないケースが稀にある。[ -n "$sid" ] && [ -f "$flag" ] || exit 0 の条件で $sid が空なら即スキップになるため実害はないが、フックが「静かに何もしない」状態になる。症状として気づいたら input を一時ファイルに書き出して jq . で確認する。

運用・長期まわり

/tmp のフラグが古いセッションIDで蓄積した：/tmp/claude-audit-pending-* と /tmp/claude-audit-prompted-* は、Claude Codeを終了しても自動では消えない。OSを再起動すれば消えるが、数週間起動しっぱなしの環境では大量のゴミが積まれる。月1回程度 rm -f /tmp/claude-audit-* で掃除するか、フックの起動時に古いファイルを削除する行を加える。
監査キーワードがモデルに学習されて形骸化した：「監査」という語を含む1行で通過できることをモデルが覚えると、「監査：問題なし」のような空砲が出るようになる。このシグナルが見えたらキーワードを更新する。「潰した」「既に堅牢」「あえて見送り」のように実際の判断を語る言葉は形骸化しにくい。語彙の棚卸しは2〜3ヶ月おきが目安。
複数のStopフックが干渉した：別のStopフックが先に exit 2 を返すと、Claude Codeがフックチェーンをそこで止める可能性がある（実装依存）。フックは登録順に実行されるため、監査フックは配列の末尾に置く。あるいは複数のロジックを1本のStopフックに統合する。
stderrのデバッグ出力を消し忘れた：フックをデバッグするとき echo "DEBUG: sid=$sid" >&2 を追加するが、消し忘れると本番のstderrにデバッグ行が混入する。デバッグ専用のフラグ変数（DEBUG_HOOK=1）を環境変数にして制御するか、デバッグ後は必ず削除する。

ベストプラクティス

1. Pythonは /usr/bin/python3 フルパス固定

フックが動く最小シェル環境はPATHが通っていない。python3 とだけ書くと「見つからない」でサイレントスキップになる。/usr/bin/python3 のフルパス指定のみ安全。このフックでコメントに「フルパス」と書いてある理由はここ。

2. フラグは判定前に消す（ループ防止の要）

rm -f "$flag"   # 単発: このターンのflagは必ず消す(ループ防止)
[ -z "$last" ] && exit 0

「合格時だけ消す」設計にすると、不合格でブロック→モデルが監査を書く→次のStopでフラグが残ったまま→またブロック、のループが起きる。フラグはStopフック起動時点で必ず消す。次回フラグが立つのは「そのターンでまたファイルを書いた場合だけ」に限定される。

3. フェイルオープン原則を徹底する

フックが異常終了したときは exit 0（通す）を選ぶ。フックへの不信任が積み重なるほうが長期ダメージが大きい。監査の見逃しは次のターンで拾える。フックの誤ブロックは「またフックが誤作動した」という評価に直結し、以降フックが実質無効化される。安全系フック（秘密値のコミット防止など）は逆にフェイルクローズが正しい。役割によって設計方針を分ける。

4. セッション別フラグで複数ウィンドウの干渉を防ぐ

flag="/tmp/claude-audit-pending-${sid}"

session_id をファイル名に埋め込むことで、複数のClaude Codeウィンドウを同時開きしていても混線しない。カウンタファイル claude-audit-prompted-${sid} も同様。session_idが入っていなければ $sid が空になり [ -n "$sid" ] の条件で即スキップする安全弁にもなる。

5. head -15 で先頭だけ読む

head -15 "$tpath" 2>/dev/null | grep -q '"entrypoint":"sdk-cli"'

Claude CodeのJSONLは、セッションのメタデータブロック（エントリーポイント情報を含む）を先頭数行に書き込む。ファイル全体を cat せず head -15 で十分判定できる。長大なセッション（数百KB）でもフックの起動コストがほぼゼロになる。

6. matcher は Write|Edit に限定する

* にするとBashコマンド実行・Read・Grep でもPostToolUseフックが走り、「調査だけしたターン」にフラグが立つ。ファイルを書いたターンだけを拾いたいなら Write|Edit。MultiEditも含める場合は Write|Edit|MultiEdit。

7. セッション当たり上限（2回）で連発を防ぐ

count=$(cat "$prompted" 2>/dev/null || echo 0)
if [ "$count" -ge 2 ]; then rm -f "$flag"; exit 0; fi

同一セッション内で監査要求が3回以上出ると、モデルが「監査は定期ルーティン」と認識して形式的な応答をするようになる。2回を超えたら黙る。「少ない回数で確実に効かせる」ほうが監査の重みが保たれる。

8. 無人セッションを検出してスキップする

launchd・Agent SDK・cron経由の無人実行セッションに監査要求を出しても読む人間がいない。トランスクリプト先頭15行に "entrypoint":"sdk-cli" があればフラグを消して exit 0。これを入れないと夜間バッチのstderrが監査要求で埋まる（実際に1晩で19件積まれた事件が起きた）。

9. ブロックメッセージは短く、逃げ道を作る

echo "⚠️ セルフ監査未実施。...軽微なら『監査不要:理由』の一言で良い。" >&2

200字の表テンプレートを送ると20行の監査が毎回返ってくる。「軽微なら1行でよい」という逃げ道を作ることで、重要な変更では「潰した：atomic renameで対処済み」の1行が出て、軽微な変更では「監査不要：定数変更のみ」の1行が出る。監査の量ではなく質の問題。

10. キーワードは「判断を語る言葉」にする

監査|潰した|既に堅牢|あえて見送り|セルフ監査|三層|予測できる不具合 の7パターンのうち、最も形骸化しにくいのは「潰した」「既に堅牢」「あえて見送り」の3つ。これらは3区分報告の語彙であり、実際の判断を経ないと自然に出ない言葉。「監査」だけを残してほかを削ると「監査済み」1行で通過できるショートカットが増える。

11. コメントに事件日時を残す

# 2026-07-12: 一晩でsdk-cli自動化19件がstopspamを埋めた

このコードがここにある理由を、将来のモデルと自分に伝える。フックは後から読んでも意図が不透明になりやすい（「なぜここでhead -15？」「なぜ2回上限？」）。事件の日時と症状を1行残すだけで、半年後の改修コストが大きく下がる。

12. jq で settings.json を検証する

jq . ~/.claude/settings.json

フックを登録した後は jq で整形して目視確認する。特に hooks.PostToolUse[].hooks[] の二重配列構造は間違えやすく、JSON構造のミスはClaude Codeがサイレントに無視するため気づきにくい。動かないと思ったらまずここ。

13. デバッグは一時ファイルへの書き出しで

# デバッグ時のみ追加。終わったら必ず削除
printf '%s' "$input" > /tmp/hook-debug-input.json
echo "DEBUG: sid=$sid tpath=$tpath" >&2

stderrへのデバッグ出力はモデルにフィードバックされるため、消し忘れると本番で余計なノイズになる。デバッグ完了後は必ず削除する。/tmp/hook-debug-input.json に stdin を書き出して jq . で見ると、フックに渡ってくるJSONの全容が分かる。

14. フック自体も監査対象にする

「フックが動いているはず」を検証せず運用しない。週1回程度、意図的にファイルを書いて監査要求が出ることを確認する。または /tmp/claude-audit-prompted-* のタイムスタンプを見て「最後に監査が要求されたのはいつか」を確認する。フックが静かに壊れていると、監査なしで「完了」が通り続ける。

まとめ

「完了です」という言葉は、LLMが出力する語の中で最も危険なものの一つです。文字として存在するが、実態を保証しない。「動きました」「テストが通っています」「実装が完了しました」——この3行を読んで安心した翌朝、本番で壊れているという経験は、LLMを使う開発者なら一度は通る道です。

Stopフック＋PostToolUseフックの組み合わせは、そこに1本の物理的な柵を立てます。

audit_flag_set.sh の6行がファイル変更のたびにフラグを立て、self_audit_stop.sh の67行がそのフラグを拾い、トランスクリプトJSONLをPythonで直接パースし、直近のassistantテキストから7つのキーワードを探し、なければ exit 2 でブロックする。プロンプトで「必ず監査してください」と頼むのではなく、ハーネスが監査を物理的な通過条件にする。

この仕組みを入れてから、「完了と言ったのに壊れていた」の頻度が体感で7〜8割落ちました。残りの2〜3割は、キーワードの形骸化（「監査：問題なし」の空砲）か、フックが静かにスキップした異常系です。どちらもキーワードの定期更新とフックログの確認で対応できます。

月商120万の自律環境で最も大切なのは「LLMが正しく動いていると信じること」ではなく、「LLMが正しく動いているか確認できる構造を持つこと」です。信頼は仕組みが担保する——月10万の大学生だった頃から変わった、最も根本的な考え方です。

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。 📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事に💰
OSS: github.com/bokuwalily 🐙
最新情報・お問い合わせは X @bokuwalily へ🌍
AI導入・自動化の相談と実装テンプレ7本の配布は公式LINE から💬

皆さんの ❤️ やシェアが励みになります！