📒 Stopフックでサブエージェント台帳を自動生成する

月10万の大学生だったころ、副業を掛け持ちして月60万まで伸ばしました。会社都合で解雇されて一度0に戻りましたが、半年かけてClaude Codeの自律環境を構築し、今は月商120万で動いています。その環境の土台になっているのが、Stopフックを使ったセッション後の自動ログ収集です。

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

Claude Codeを使いはじめてしばらく経つと、「どこにコストがかかっているのかわからない」という感覚が出てきます。Exploreエージェント、code-reviewerエージェント、general-purposeエージェント──複数のサブエージェントを組み合わせて作業をこなしているうち、気づけばセッションが何十分も回っている。でもどのエージェントが遅いのか、どのエージェントがよくエラーを出しているのか、数字で見たことはありませんでした。

感覚で「あのエージェントは重い」と言うのは、データではありません。改善しようにも、どこを直せばいいかが不明のまま。これは個人開発でシステムを量産している身としては致命的な状態です。仕事の流れを最適化するには、まず計測から始める必要があります。

Claude Codeにはその計測を自動化できる仕組みが最初から組み込まれています。Stopフックです。

Stopフックは、Claude Codeのセッションが終了するたびに呼ばれるシェルスクリプトです。フックにはtranscript_pathが渡されます。これはそのセッション全体の会話ログ──ツール呼び出し、エージェント起動、レスポンスのタイムスタンプまで含む生のJSONL──へのパスです。つまりセッションが終わるたびに、「このセッションで何が起きたか」を丸ごと読み込むチャンスが自動的に生まれます。

ここに気づいてから、考えが変わりました。記録を手動でつける必要はありません。セッション終了を起点にスクリプトを走らせ、transcript_pathを解析してサブエージェント呼び出しの一覧をJSONLに書き出す。それだけで「どのエージェントが何秒かかったか・成功したか失敗したか」が蓄積されていきます。

あとはこの台帳をjqで集計すれば、感覚論から数字の議論へ移行できます。

もう一つ重要な点があります。このアプローチはClaude Code本体に何も手を加えません。Stopフックは~/.claude/settings.jsonに1行追加するだけで有効になります。元の動作を変えず、セッション終了という既存のイベントに乗っかるだけです。副作用がゼロに近いのは、量産環境を維持するうえで大きなメリットです。

transcript.jsonlに何が入っているか

Stopフックが受け取るJSONのうち重要なフィールドは二つです。

{
  "session_id": "...",
  "transcript_path": "/path/to/transcript.jsonl"
}

transcript_pathが指すファイルには、そのセッションで交わされたすべてのメッセージがJSONL形式（1行1JSON）で並んでいます。各行のmessage.contentの中に、ツール呼び出しを示す"type": "tool_use"のブロックが含まれています。

サブエージェントの起動はこの中で"name": "Agent"として記録されます。注意点として、Claude Codeの内部ではUIに「Task」と表示されているにもかかわらず、transcript上のツール名は"Agent"です（スクリプトのコメントにも「Claude Code の transcript では『Task』ツールは name="Agent" として記録される」と明示されています）。subagent_typeはinput.subagent_typeに入っています。

エージェント呼び出しに対する結果は"type": "tool_result"として別行に現れ、tool_use_idで呼び出し側と結びついています。is_error: trueがあればエラー終了、なければ成功です。

この構造さえ把握しておけば、Pythonで2パス処理するだけでサブエージェントの実行記録が取れます。

全体の流れ

システム全体を図で示すと次のようになります。

 Claude Codeセッション
 ┌─────────────────────────────────────────────────┐
 │ tool_use (name="Agent", subagent_type="Explore") │
 │     ...処理中...                                  │
 │ tool_result (tool_use_id=xxx, is_error=false)    │
 └─────────────────────────────────────────────────┘
              ↓ セッション終了 (Stop イベント)
 ┌─────────────────────────────────────────────────┐
 │ Stop hook: stop_agent_tracker.sh                 │
 │   stdin: {"session_id", "transcript_path", ...}  │
 └─────────────────────────────────────────────────┘
              ↓ transcript_path を読み込む
 ┌─────────────────────────────────────────────────┐
 │ Python: 2パス解析                                 │
 │   Pass1: uses{} / results{} を構築               │
 │   Pass2: tool_use_id で突き合わせ・duration算出   │
 └─────────────────────────────────────────────────┘
              ↓ 追記
 ~/.claude/logs/agent-invocations.jsonl

Stopフックが起動されると、stdinからJSONを受け取り、その中のtranscript_pathを使ってPythonスクリプトがトランスクリプトを読みます。出力先は固定で~/.claude/logs/agent-invocations.jsonlです。

stop_agent_tracker.sh の中身

スクリプトの実体はほぼPythonです。shell部分は環境変数の受け渡しのみ担当しています。

INPUT=$(cat)           # stdin から Stop イベント JSON を受け取る
export STOP_INPUT="$INPUT"
export OUT_LOG_PATH="$OUT_LOG"    # ~/.claude/logs/agent-invocations.jsonl

Python部分は大きく3ブロックに分かれています。

重複防止ブロック

同一セッションで複数回Stopフックが走った場合（Claude Codeの仕様上ありえます）に同じエントリを二重書きしないよう、既存ログからsession_idとtool_use_idの組み合わせを読み込んでseen_idsセットに入れます。

seen_ids = set()
if os.path.exists(out_path):
    with open(out_path, "r", ...) as f:
        for line in f:
            r = json.loads(line)
            if r.get("session_id") == sid and r.get("tool_use_id"):
                seen_ids.add(r["tool_use_id"])

第1パス: インデックス構築

トランスクリプトを1行ずつ読み、"name": "Agent"かつsubagent_typeを持つtool_useブロックをuses辞書へ、tool_resultブロックをresults辞書へそれぞれ格納します。

uses = {}    # tool_use_id -> (ts, name, input, caller)
results = {} # tool_use_id -> (ts, is_error)

for b in content:
    if b.get("type") == "tool_use" and b.get("name") == "Agent":
        inp = b.get("input") or {}
        if "subagent_type" not in inp:
            continue
        uses[uid] = (ts, b.get("name"), inp, b.get("caller"))
    elif b.get("type") == "tool_result":
        results[rid] = (ts, bool(b.get("is_error")))

subagent_typeを持たないAgent呼び出しはスキップしています。これはメインのClaudeエージェント自身の呼び出しを除外するための判定です。

第2パス: 突き合わせと書き出し

usesを走査し、対応するresultsエントリがあればduration_msを計算して書き出します。

t0 = parse_ts(use_ts)    # tool_use のタイムスタンプ
t1 = parse_ts(res_ts)    # tool_result のタイムスタンプ
if t0 and t1:
    duration_ms = int((t1 - t0).total_seconds() * 1000)

結果がまだ返ってきていないエントリは"status": "pending"で記録します。

descriptionフィールドは300文字でトランケートされます。これはエージェントへの指示文が長い場合でもログファイルのサイズを制御するための措置です。

if len(description) > 300:
    description = description[:300] + "…"

最終的に書き出されるJSONLの1行は次の形です。

{
  "ts": "2026-09-10T08:30:00Z",
  "session_id": "abc123",
  "cwd": "~/dev/my-project",
  "tool_use_id": "toolu_01Xyz...",
  "subagent_type": "Explore",
  "description": "Find all TypeScript files that reference the Auth module…",
  "duration_ms": 18420,
  "status": "ok",
  "caller": null
}

フィールドを整理すると、subagent_typeがエージェントの種類、duration_msが実行時間（ミリ秒）、statusが"ok" / "error" / "pending"の3値です。callerは呼び出し元の情報ですが、多くの場合nullになります。

なぜ2パスなのか

1パスでtool_useを読んだ時点では、対応するtool_resultがまだ現れていない可能性があります。JSONLは時系列順に並んでいますが、長いエージェント実行では間に他のメッセージが挟まることもあります。先に全行を読んでインデックスを作り、後から突き合わせる2パス構造にすることで確実にペアを取得できます。

また、parse_ts関数はISO8601のタイムスタンプをdatetimeオブジェクトに変換する際に、末尾のZを+00:00に置換してfromisoformatに渡します。

def parse_ts(s):
    try:
        return datetime.datetime.fromisoformat(s.replace("Z", "+00:00"))
    except Exception:
        return None

Pythonのfromisoformatは3.11未満ではZサフィックスを直接パースできないため、この変換が必要です。

ログの蓄積方法

スクリプトは"a"モード（追記）でファイルを開きます。毎セッション新しいレコードが末尾に追加されていく形です。ファイルが存在しない場合は自動作成されます（LOG_DIRのmkdir -pで担保）。

セッションをまたいだデータが蓄積されるため、数日から数週間使い続けると「いつもExploreエージェントが20秒以上かかっている」「code-reviewerエージェントがたまにエラーを出している」といった傾向が浮かび上がってきます。

コストログスクリプトの解剖

stop_agent_tracker.shと並んで動いているのがstop_cost_log.shです。こちらはセッションで消費されたトークン数と推定コストを~/.claude/logs/cost-log.jsonlに記録します。エージェントの遅さと並んで「いつ・どのセッションでいくらかかったか」を把握しておくのは、量産環境の維持に欠かせません。

PRICINGテーブルとプレフィックスマッチ

料金テーブルの実装は次のようになっています。

PRICING = {
    "claude-opus-4-7":   {"input": 15.0, "output": 75.0, "cache_read": 1.5,  "cache_create_5m": 18.75, "cache_create_1h": 30.0},
    "claude-sonnet-4-6": {"input": 3.0,  "output": 15.0, "cache_read": 0.3,  "cache_create_5m": 3.75,  "cache_create_1h": 6.0},
    "claude-haiku-4-5":  {"input": 1.0,  "output": 5.0,  "cache_read": 0.1,  "cache_create_5m": 1.25,  "cache_create_1h": 2.0},
}
DEFAULT_RATE = PRICING["claude-sonnet-4-6"]

def rate_for(model: str):
    for k, v in PRICING.items():
        if model.startswith(k):
            return v
    return DEFAULT_RATE

辞書のキーを「完全一致」ではなく「前方一致（startswith）」にしているのがポイントです。Claude Codeがトランスクリプトに書き出すモデル名には、claude-sonnet-4-6-20250620のようにリリース日サフィックスがつく場合があります。完全一致にしてしまうと、マイナーバージョンが更新されるたびにPRICINGを書き直す羽目になります。プレフィックスで引っかければ、サフィックスの変動を吸収できます。未知のモデルはSonnet相当でフォールバックするDEFAULT_RATEがあるため、テーブルにないモデルが登場しても集計が止まりません。

キャッシュトークンの5分枠と1時間枠

Anthropic APIのキャッシュには5分有効のエフェメラルキャッシュと1時間有効のキャッシュの2種類があり、料金が異なります（単価比は約1:1.6）。スクリプトはこれを別々に集計しています。

cc_5m = (usage.get("cache_creation", {}) or {}).get("ephemeral_5m_input_tokens", 0) or 0
cc_1h = (usage.get("cache_creation", {}) or {}).get("ephemeral_1h_input_tokens", 0) or 0
if cc_5m + cc_1h == 0 and cc_total > 0:
    cc_5m = cc_total

最後の3行が整合性チェックです。Claude Codeの古いバージョンや特定の条件では、cache_creationの入れ子オブジェクトが存在せず、フラットなcache_creation_input_tokensのみが返ってくることがあります。その場合にcc_5m + cc_1h == 0かつcc_total > 0という状態になるため、全量を5分枠として扱います。5分枠のほうが安いので、これはコスト過小評価の方向にバイアスがかかります。過大に出るよりは把握しやすいという判断です。

コスト計算式

cost_usd += (
    inp / 1_000_000 * r["input"]
    + out / 1_000_000 * r["output"]
    + cr / 1_000_000 * r["cache_read"]
    + cc_5m / 1_000_000 * r["cache_create_5m"]
    + cc_1h / 1_000_000 * r["cache_create_1h"]
)

単位は「$/MTok（百万トークンあたりドル）」なので、トークン数を1_000_000で割ってから掛けます。_区切りの数値リテラルを使っているのは可読性のためで、Python 3.6以降なら動きます。セッションのすべてのメッセージを走査してcost_usdを積算し、最後にround(cost_usd, 4)で小数点4桁に丸めて記録します。

jqで台帳を集計する

ログが溜まったらjqで問いを立てられます。以下はすべて~/.claude/logs/agent-invocations.jsonlを対象にした実際のクエリです。

エージェント種別ごとの平均・最大実行時間を出す

jq -s '
  group_by(.subagent_type) |
  map({
    type: .[0].subagent_type,
    count: length,
    avg_ms: (map(select(.duration_ms != null) | .duration_ms) | add / length | round),
    max_ms: (map(select(.duration_ms != null) | .duration_ms) | max)
  }) | sort_by(-.avg_ms)
' ~/.claude/logs/agent-invocations.jsonl

group_byで種別ごとに束ね、avg_msとmax_msを計算して降順に並べます。実際にこれを走らせると、私の環境ではExploreエージェントが平均22秒前後、code-reviewerが平均37秒、general-purposeが平均18秒という分布でした。code-reviewerが遅い理由は複数ファイルを読み込んでいるからで、これが数字で確認できてから「複数ファイル横断の確認にcode-reviewerを使うのは重い」という感覚論に根拠がつきました。

エラー率が高いエージェントを特定する

jq -s '
  group_by(.subagent_type) |
  map({
    type: .[0].subagent_type,
    total: length,
    errors: map(select(.status == "error")) | length,
    error_rate: ((map(select(.status == "error")) | length) / length * 100 | round)
  }) | sort_by(-.error_rate)
' ~/.claude/logs/agent-invocations.jsonl

特定のプロジェクト（cwd）でのコストを合算する

jq -s '
  map(select(.cwd | contains("my-project"))) |
  { total_cost: (map(.cost_usd) | add) }
' ~/.claude/logs/cost-log.jsonl

コストログのほうにもcwdフィールドが入っているため、プロジェクトのパス名でフィルタして合計コストを出せます。どのプロジェクトにどれだけ使ったかが一目で見えるようになると、採算の感覚が変わります。

---

私が詰まった話

実装が完成するまでに4つの具体的な詰まりを経験しました。いずれも「なぜ動かないのかすぐわからない」タイプのバグで、症状だけ見ると原因が見えにくいものです。

詰まり①：stdnが空になってPythonが何も処理しない

最初に書いたバージョンでは、シェルとPythonを次のように繋いでいました。

cat | python3 - <<'PY'
data = json.load(sys.stdin)  # ← ここで空が返ってくる
PY

「ヒアドキュメントのPythonスクリプト自体をstdinで渡しているので、sys.stdinで入力を読める」という勘違いです。実際には<<'PY'がシェルにとってのstdinを占有しているため、スクリプト実行時点でのsys.stdinはすでにEOFになっています。catでStopフックのJSONを受け取っていても、それがPythonに届く経路がありません。

直し方はシンプルで、「一度シェル変数に入れてから環境変数として渡す」です。

INPUT=$(cat)
export STOP_INPUT="$INPUT"

python3 - <<'PY'
data = json.loads(os.environ.get("STOP_INPUT", ""))
PY

INPUT=$(cat)でStopフックのJSONを読み込み、exportで環境変数にします。ヒアドキュメントのPython内ではos.environから読む。この迂回路を取ることで、stdinの競合を回避できます。実際のスクリプトがこの形になっているのはこの経緯があるからです。

詰まり②：fromisoformatがZで落ちる

トランスクリプトのタイムスタンプは"2026-09-10T08:30:00Z"の形式で入っています。最初は素直にdatetime.fromisoformat(ts)と書きました。

# Python 3.10以前ではこれが ValueError になる
datetime.datetime.fromisoformat("2026-09-10T08:30:00Z")

macOSのシステムPythonが3.10だったため、この1行がValueErrorを投げてスクリプトが止まりました。try/exceptを書いていなかったので、Stopフック全体がエラー終了し、ログが何も残らない状態が数日続きました。なぜログが生成されないのかが全くわからず、最終的にCC_AGENT_TRACKER_DEBUG=1でデバッグログを有効にして初めて原因がわかりました。

修正はparse_ts関数の中に収まっています。

def parse_ts(s):
    if not s:
        return None
    try:
        return datetime.datetime.fromisoformat(s.replace("Z", "+00:00"))
    except Exception:
        return None

Zを+00:00に置換してから渡すと、Python 3.7以降で動きます。さらにtry/exceptで囲んでいるため、想定外の形式が来てもスクリプトが止まらずにNoneを返します。duration_msの計算は「t0とt1が両方Noneでない場合のみ行う」という条件になっているので、Noneが返ってきたエントリはduration_ms: nullで記録されます。計算を諦めて記録は残す、という方針です。

詰まり③：Stopフックが同一セッションで複数回呼ばれて重複書きが起きる

Stopフックを有効にして数日後、ログに同じtool_use_idのエントリが重複しているのを発見しました。たとえば3時間動かしたセッションのあと、agent-invocations.jsonlを確認すると同一IDのレコードが2行入っている。

Claude Codeは条件によってSessionの終了イベントを複数回発行することがあります（サブプロセスの終了とメインセッションの終了が重なるケース等）。つまり同一セッションに対してStopフックが2回走り、2回目も同じトランスクリプトを読んで同じレコードを書き出す、という状態でした。

対処として「このセッションで既に書いたtool_use_idをセット化して、次回スキップする」という重複防止ロジックを冒頭に追加しました。

seen_ids = set()
if os.path.exists(out_path):
    with open(out_path, "r", encoding="utf-8", errors="replace") as f:
        for line in f:
            try:
                r = json.loads(line)
                if r.get("session_id") == sid and r.get("tool_use_id"):
                    seen_ids.add(r["tool_use_id"])
            except Exception:
                continue

書き出し時は次のように判定します。

for uid, (use_ts, _, inp, caller) in uses.items():
    if uid in seen_ids:
        continue  # 既に記録済みならスキップ

session_idとtool_use_idの組み合わせで同一性を判定しているのは、セッションをまたいで同じtool_use_idが衝突する確率がゼロでないためです（UUIDなので極めて低いですが、念のため）。既存ログ全体を読むのではなく、同一session_idの範囲だけを読む点がパフォーマンス上の配慮です。

詰まり④：name="Task"でフィルタしたら何も取れない

最初にトランスクリプトの構造を調べたとき、Claude Codeのインターフェース上に「Task」と表示されていたため、スクリプトでも次のように書きました。

if btype == "tool_use" and b.get("name") == "Task":

これで実行してもログに何も記録されません。デバッグのためにフィルタをはずして全tool_useを出力したところ、実際のトランスクリプトには"name": "Agent"として記録されていることがわかりました。

UIの表示名とトランスクリプト上のツール名が一致していない。これはClaude Codeのインターナルな命名の非対称性で、ドキュメントには明記されていません。実際のスクリプトにコメントで「Claude Code の transcript では『Task』ツールは name="Agent" として記録される」と明示しているのはこの経験からです。同じ落とし穴にはまらないよう、最初に目にする場所に書き残しています。

正しいフィルタは次の2条件の組み合わせです。

if btype == "tool_use" and b.get("name") == "Agent":
    inp = b.get("input") or {}
    if "subagent_type" not in inp:
        continue

name == "Agent"かつinputにsubagent_typeが存在する行だけを対象にします。subagent_typeのないAgent呼び出しはメインのClaudeセッション自体のエントリである場合があり、それを除外するために2段フィルタになっています。

詰まり⑤：set -eで無言死し、ログが全く残らない

初期バージョンのシェルヘッダはset -euo pipefailでした。-eはコマンドが非ゼロで終了したらシェル全体を即終了する設定です。

問題が起きたのは「トランスクリプトが存在しないセッション」で実行されたときです。Claude Codeの軽量セッション（短い質問をして終了するだけ）ではトランスクリプトが生成されないことがあります。このときos.path.exists(tp)がFalseを返してPythonがsys.exit(0)で終了しますが、その前段の[ -z "$INPUT" ] && exit 0でシェルが正常終了するパスもあります。-eが有効だと&&の評価結果によっては意図せずスクリプトが止まるケースが出てきました。

また、Pythonスクリプト内でsys.exit(0)を呼ぶと正常終了（終了コード0）なので問題ないのですが、環境によってpython3コマンド自体が見つからない（PATHが通っていない）場合に終了コード127が返り、-eによってシェルが止まって後段の処理が全部スキップされることもありました。

修正は-eを外して-uo pipefailにすることです。

set -uo pipefail

-uは未定義変数へのアクセスを即エラーにします。pipefailはパイプの途中でエラーが出た場合にパイプ全体を失敗とします。-eは外しています。フックスクリプトは「自分がコケてもClaude Codeの動作に影響を与えない」のが原則なので、積極的にexit 0で抜けるほうが安全です。エラーはDEBUG_LOG（~/.claude/logs/stop_agent_tracker.log）に書き出す設計になっているため、-eで無言死するよりもデバッグログで原因が見える状態を優先しています。

---

ここまで実装の詳細と失敗の記録を書いてきました。次のパートではこれらのログをどう運用に組み込むか、具体的に数字が変わった例と、jqレシピの実践集を扱います。

つまずきポイント（追加・網羅版）

前パートで5つの詰まりを書きましたが、実運用に入ると追加でぶつかるポイントがあります。よくある順に並べます。

• ⑥ python3が見つからずフックが無言終了する
  Claude CodeはGUIから起動するとログインシェルを読み込まず、/usr/bin:/bin程度の最小限のPATHしか持ちません。~/.pyenv/shims/python3や~/.nvm/versions/.../bin/python3はこのPATHに含まれません。症状は「フックが登録されているのにログが一切生えない」。set -uo pipefailで-eを外していれば127で死んでも後続スクリプトは動き続けますが、出力ファイルは空のままです。対策は2つあります。スクリプト冒頭にexport PATH="/usr/local/bin:/usr/bin:$HOME/.pyenv/shims:$PATH"を書くか、/usr/bin/env python3ではなくフルパスで/usr/bin/python3を固定する。macOS Ventura以降ではXCode Command Line Toolsが/usr/bin/python3を提供しているため、システムPythonが存在するなら後者が最も安全です。

• ⑦ contentフィールドがlistでなくstringになっているメッセージがある
  transcript.jsonlのほとんどのメッセージはcontentがリストですが、ごく一部のシステムメッセージではcontentが文字列になっています。for b in contentでイテレートしようとすると文字列を1文字ずつ処理してしまいます。実際のスクリプトにはif not isinstance(content, list): continueというガードが入っていますが（94〜96行目）、自前でスクリプトを改変するときにこの行を削ると壊れます。contentがlistかどうかは毎行確認するのが鉄則です。

• ⑧ jq -sで数万行のJSONLをメモリに展開するとOOMになる
  jq -sはファイル全体をメモリに読み込んでから処理します。agent-invocations.jsonlが数万行を超えてくると、Macのメモリを数百MB消費するクエリになります。月に数百セッション動かすと3〜4ヶ月で到達します。解決策は--streamオプションか、定期的なアーカイブです。私は月次でログを~/logs/archive/agent-YYYY-MM.jsonlに退避させ、agent-invocations.jsonlには直近30日分だけ残す運用にしています。

  # 月次ローテーション（launchdで自動実行）
  MONTH=$(date -v-1m +%Y-%m)
  jq -c 'select(.ts | startswith("'"$MONTH"'"))' \
      ~/.claude/logs/agent-invocations.jsonl \
      >> ~/.claude/logs/archive/agent-${MONTH}.jsonl
  

• ⑨ status: "pending"のエントリが大量に蓄積される
  サブエージェントの実行中にClaude Codeが強制終了（⌘Q、OSシャットダウン、OOM kill）された場合、tool_resultが書き込まれないままトランスクリプトが終わります。この状態でStopフックが走ると、対応するresultsが存在しないためstatus: "pending"で記録されます。これ自体は正しい動作ですが、pendingエントリが月に数十件たまると平均実行時間の集計が歪みます（duration_ms: nullなエントリをselect(.duration_ms != null)でフィルタする必要があります）。月次の集計クエリには必ずselect(.status == "ok")を追加しておくのが安全です。

• ⑩ 重複防止ブロックが巨大ログで遅くなる
  セッション冒頭の重複チェックでは、既存ログを全行読んでsession_idが一致するレコードを探します（58〜69行目）。ログが10万行を超えると、1セッションあたりのフック実行に数秒かかるようになります。実用上の対策は2つです。まずJSONLをセッション日付でパーティションする。次にseen_idsの読み込みを「最新N行だけ」に制限する（同一セッションのエントリが連続しているとは限らないので完全な回避策ではありませんが、現実的な妥協点です）。

• ⑪ cwdに実パスが記録されてスクリプトを公開できなくなる
  stop_agent_tracker.shが出力するJSONLには"cwd": "/Users/実名/dev/my-project"が入ります。このログを.gitignoreに追加し忘れてリポジトリにコミットすると、ホームディレクトリの絶対パスが外部に漏れます。~/.claude/logs/はリポジトリ外に置いているので問題ありませんが、ログを分析用スクリプトに渡すとき、ログファイルごとgistや共有フォルダに出してしまうケースがあります。jq 'del(.cwd)'で加工してから共有するか、cwdフィールドをディレクトリ名だけ（basename）に丸める前処理を入れると安全です。

• ⑫ デバッグログを有効にする方法を知らないまま数日溶かす
  stop_agent_tracker.shにはCC_AGENT_TRACKER_DEBUG=1という環境変数スイッチが実装されています（31行目）。1を設定すると~/.claude/logs/stop_agent_tracker.logに詳細ログが書き出されます。stop_cost_log.shはCC_COST_DEBUG=1で同様に~/.claude/logs/stop_cost_log.logへ書き出します。フックが動いているかどうか確認するファーストステップはtail -f ~/.claude/logs/stop_agent_tracker.logです。これを知らずに「ログが生えない原因がわからない」状態で数日溶かした経験が私にはあります。新しい環境でフックを設定したら、まずデバッグモードで1セッション動かして動作確認するのが必須手順です。

---

ベストプラクティス

実装・運用を経て固まったルールを書き出します。

1. フックスクリプトは必ずexit 0で終わる

Stopフックが非ゼロで終了すると、Claude Codeが次のセッション起動時に警告を出すことがあります。スクリプト内で何か問題が起きたとしても、ログに書いてexit 0で抜ける設計が鉄則です。set -eを外すのも同じ理由です。フックの失敗がClaude Code本体の動作に波及しない状態を維持します。

2. stdinは最初の1行でINPUT=$(cat)に受けて環境変数に詰め替える

ヒアドキュメントのPythonへstdinを渡す方法はありません。必ずINPUT=$(cat) → export STOP_INPUT → os.environの経路を使います。これはP2で詳述した詰まり①の直接の教訓です。この形を崩さない限り、どんなにPythonコードを改変しても入力が届きます。

3. Pythonコードは1つの大きなtry/exceptで包み、例外を握りつぶさずデバッグログに書く

try:
    # メイン処理
    ...
except Exception as e:
    log(f"unexpected_error: {e}")
sys.exit(0)

例外が出てもsys.exit(0)で正常終了します。ログには残る。Claude Codeには影響しない。この3点を同時に達成するのが上記の構造です。

4. タイムスタンプはparse_ts関数に閉じ込めてNoneを返す設計にする

fromisoformatのZ問題（詰まり②）が象徴するように、タイムスタンプ処理は環境依存のエッジケースが多いです。変換は必ず専用関数に分離し、失敗時はNoneを返します。duration_msの計算は「t0とt1がどちらもNotNoneのときだけ行う」という条件にしておけば、NoneのせいでTypeErrorが出ることもありません。

5. 重複防止は最初から入れる。後から入れると既存ログの汚染が取れない

詰まり③（Stopフックの多重呼び出し）は、数日後に「なぜ同じエントリが2行あるのか」という形で気づきます。この時点で既存ログには重複が埋まっており、sort -uで取り除こうとしてもJSONLはキーが順序不定なのでそのままでは使えません。重複防止ロジックは実装当初から入れるのが原則です。コストは「既存ログを読む1パス」だけです。

6. jqクエリには必ずselect(.duration_ms != null)とselect(.status == "ok")を入れる

pendingエントリ（duration_ms: null）を含めた平均を出すと数字がゼロ側に引き寄せられます。集計クエリのデフォルトに上記2条件を追加しておくと、有効なデータだけを対象にした正確な数字が出ます。

jq -s '
  map(select(.duration_ms != null and .status == "ok")) |
  group_by(.subagent_type) |
  map({type: .[0].subagent_type, avg_ms: (map(.duration_ms) | add / length | round)})
' ~/.claude/logs/agent-invocations.jsonl

7. ログファイルは毎月アーカイブして現行ファイルを軽量に保つ

agent-invocations.jsonlが大きくなると重複チェックパスが遅くなり（詰まり⑩）、jq -sでメモリを食います（詰まり⑧）。月次でアーカイブするlaunchdジョブを最初から設定しておくと、これらの問題が発生しません。実際には「ログが重くなった」と気づいた時点でアーカイブする人が多いですが、最初から入れておくほうが運用が楽です。

8. PRICINGテーブルは完全一致でなくプレフィックスマッチで引く

stop_cost_log.shのrate_for関数の実装がそのままベストプラクティスです。model.startswith(k)でキーを引くことで、claude-sonnet-4-6-20250620のようにリリース日サフィックスが付いたモデル名の変動を吸収できます。未知モデルはSonnet相当でフォールバックするため、テーブルにないモデルが出ても集計が止まりません。

9. フックを設定したら必ずデバッグモードで1セッション通して確認する

# ~/.claude/settings.json に追加（既存のhooksブロックに追記）
CC_AGENT_TRACKER_DEBUG=1 claude  # ← デバッグモードで起動
tail -f ~/.claude/logs/stop_agent_tracker.log  # 別ターミナルで監視

「設定した」と「動いている」は別です。実際にセッションを走らせてログが生えるまでを確認してから、デバッグモードを外してください。

10. subagent_typeでフィルタせずinput.subagent_typeの存在で判定する

詰まり④（name="Task"問題）と対になるベストプラクティスです。name == "Agent"だけではサブエージェント呼び出し以外のエントリも引っかかる可能性があります。"subagent_type" in inpの2段フィルタを必ず入れてください。これが実際のスクリプトの設計です。

11. cwdフィールドを使ってプロジェクト別に集計する

cost-log.jsonlにもagent-invocations.jsonlにもcwdが入っています。プロジェクトごとの所要時間とコストを出すには、次のjqで十分です。

# プロジェクト別コスト
jq -rsc '
  group_by(.cwd) |
  map({cwd: .[0].cwd, cost_usd: (map(.cost_usd) | add | . * 10000 | round / 10000)}) |
  sort_by(-.cost_usd)[] |
  "\(.cost_usd) USD  \(.cwd)"
' ~/.claude/logs/cost-log.jsonl

どのプロジェクトにどれだけClaude Codeを使っているかが見えると、採算の感覚が変わります。

12. Stopフックは複数登録でき、独立して動く

~/.claude/settings.jsonのhooks.Stopは配列で複数エントリを書けます。stop_agent_tracker.shとstop_cost_log.shが別々に登録されているのはこのためです。一方が失敗してももう一方は動きます。役割ごとにスクリプトを分けておくと、修正・差し替えが独立してできます。

13. 数字を週1で見る習慣をつける

ログが蓄積されても見なければ意味がありません。私は毎週月曜の朝にエイリアスccstatsを実行しています。

alias ccstats='
  echo "=== エージェント平均時間（直近7日） ===";
  jq -sc "map(select(.status==\"ok\" and .duration_ms != null)) |
    group_by(.subagent_type) |
    map({type:.[0].subagent_type, avg_ms:(map(.duration_ms)|add/length|round)}) |
    sort_by(-.avg_ms)[]" \
    ~/.claude/logs/agent-invocations.jsonl;
  echo "=== 週間コスト ===";
  jq -sc "map(.cost_usd) | add | . * 100 | round / 100" \
    ~/.claude/logs/cost-log.jsonl
'

この数字を見てから「今週はcode-reviewerの呼び出しを減らそう」「このプロジェクトはExploreを減らしてGrepに変えよう」という判断ができます。感覚論から数字ベースの判断へ移行するのが、この仕組みの本来の目的です。

---

まとめ

Claude CodeのStopフックは、セッション終了という既存のイベントに乗っかるだけでログ収集を自動化できます。transcript_pathを受け取ってPythonで2パス処理し、agent-invocations.jsonlに追記する。この設計の核心は「Claude Code本体に何も変えない」という点です。フックが失敗してもexit 0で抜けるため、本体の動作に波及しません。副作用がゼロに近い仕組みだから、量産環境に組み込んでも安心して置き続けられます。

実際に数字を見てわかったのは、感覚で「重い」と思っていたエージェントと、データで「重い」エージェントは必ずしも一致しない、ということです。私の環境では体感上はgeneral-purposeが重い印象でしたが、計測したら平均18秒でExplore（22秒）よりも速かった。code-reviewerの37秒という数字を見てから、「複数ファイル横断確認はcode-reviewerより先にGrepで絞り込む」という習慣が生まれ、週間コストが体感で15〜20%落ちました。

この変化は、計測なしには生まれませんでした。

セッション終了のたびに静かに動いているフックスクリプトが、月商120万を支える自律環境の精度を少しずつ上げ続けています。

---

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。

📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

---

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

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

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