0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

claude agentsが自動PRを作るようになったので中身を検証した

0
Posted at

はじめに

Claude Code の claude agents（background agents）が v2.1.198 で「作業が終わっても確認を待たずに、コミット・push・ドラフトPR作成まで自動で終わらせる」ように変わりました。あわせて、エージェントが入力待ちになったとき・完了したときに Notification フックが発火する仕組みも追加されています。

本記事では公式チェンジログの内容を検証しつつ、追加された Notification フックを実際に手元で動かして挙動を確認した結果をまとめます。

この記事で学べること

  • v2.1.198 で claude agents に何が追加されたか（自動PR作成・Notificationフック）
  • Notificationフックで agent_needs_input / agent_completed を受け取る最小実装
  • 自動PR作成に乗り換える前に把握しておきたい注意点

前提環境

  • Claude Code v2.1.198 以降
  • Node.js / Python3 が使えるシェル環境（フックスクリプトの動作確認用）

TL;DR

  • claude agents から起動した background agent は、worktree でのコード作業が終わると 止まって確認を求めるのではなく、自分でコミット・push・ドラフトPR作成まで完了させる ようになった1
  • 新設の通知イベント agent_needs_input / agent_completed は Notification フック経由で拾える1。ただし本記事執筆時点（2026年7月2日）の公式 Hooks リファレンスには、この2つはまだ matcher の一覧に載っていない
  • v2.1.198 は1リリースで 32項目 の変更を含む（公式チェンジログは新機能・不具合修正・改善を区分せず1つの箇条書きにまとめている）。CHANGELOG.md 上で v2.1.190（6月24日）から v2.1.198（7月1日）までの8日間に掲載されているバージョンは190/191/193/195/196/197/198の7つで、192と194は掲載されていない1

背景・課題

background agents はこれまで、worktree 内での作業が終わると人間の確認待ちで止まる挙動でした。複数の background agent を並列で走らせていると、「終わったのに気づかず放置」が発生しやすく、結果としてマージまでの往復が長くなる問題がありました。

v2.1.198 のリリースノートには次のように書かれています。

Background agents launched from claude agents now commit, push, and open a draft PR when they finish code work in a worktree, instead of stopping to ask
— Claude Code Changelog（v2.1.198）

つまり「終わったら止まって聞く」から「終わったら自分でドラフトPRまで作る」に変わったということです。あわせて、エージェントの状態変化を検知するための通知も強化されています。

Added background agent notifications in claude agents — sessions that need input or finish now fire the Notification hook (agent_needs_input / agent_completed)
— Claude Code Changelog（v2.1.198）

Notificationフックを実際に動かして確認する

公式 Hooks リファレンス2によれば、Notification フックが受け取る共通フィールドは次の形式です（session_id / transcript_path / cwd / permission_mode / hook_event_name）。ただし前述の通り、agent_needs_input / agent_completed はチェンジログにのみ記載があり、本記事執筆時点でのHooksリファレンスの matcher 一覧（permission_prompt / idle_prompt / auth_success / elicitation_dialog / elicitation_complete / elicitation_response）にはまだ反映されていません。ドキュメントの反映漏れなのか、まだ内部的な扱いなのかは公式には明言されていないため、実際に受け取れる値の形は自分の手元で確認するのが確実 です。

そこで、共通フィールドの形式に沿った最小限のフックスクリプトを書いて、実際に標準入力からJSONを流し込んで挙動を確かめました。

#!/usr/bin/env bash
# Notification hook のペイロードを受け取り、通知種別ごとにログへ振り分ける最小実装
payload=$(cat)
event=$(echo "$payload" | python3 -c "import json,sys; print(json.load(sys.stdin).get('hook_event_name','unknown'))")
notif=$(echo "$payload" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('message', d.get('notification_type','')))")
echo "[notify-hook] event=${event} detail=${notif}"

agent_needs_input と agent_completed に相当する通知が来たと想定して、それぞれ模擬ペイロードを流し込んでみます。

chmod +x notify-hook.sh

echo '{"session_id":"test-abc123","hook_event_name":"Notification","message":"agent_needs_input: background agent waiting for approval","cwd":"/tmp"}' | ./notify-hook.sh

echo '{"session_id":"test-abc123","hook_event_name":"Notification","message":"agent_completed: background agent finished and opened a draft PR","cwd":"/tmp"}' | ./notify-hook.sh

実際に試したところ、出力は以下のようになりました。

[notify-hook] event=Notification detail=agent_needs_input: background agent waiting for approval
[notify-hook] event=Notification detail=agent_completed: background agent finished and opened a draft PR

hook_event_name は常に Notification で共通化されており、agent_needs_input / agent_completed の区別は本文（メッセージ）側に含まれる形になる、という組み方が最も自然です。Slack通知などに繋ぎ込む場合は、message フィールドの中身をパースして種別を判定する実装にしておくと、正式にドキュメント化された後の仕様変更にも追従しやすくなります。

自動PR作成に乗り換える前に知っておきたい注意点

チェンジログを読み込むと、自動PR化とセットでいくつかの関連修正が入っていることが分かります。

  • Explore agent のモデル継承: 組み込みの Explore agent が haiku 固定ではなく、メインセッションのモデルを継承（上限はopus）するよう変更されています1。調査系サブエージェントの精度がメインセッションのモデル選択に引っ張られるようになったため、コスト最適化のためにメインを軽量モデルに落としている場合は影響範囲を確認したほうが良いでしょう
  • APIエラー時の失敗報告: agent teams で、API エラーで死んだチームメイトが「failed」とリードに報告するようになりました1。自動PR化前は気づかれにくかった「途中で死んだエージェント」が可視化されやすくなっています
  • worktreeのロック解除は別バージョンの話: 「エージェント終了後にworktreeが自動クリーンアップされる」という趣旨の変更は、v2.1.198ではなく1つ前のv2.1.186で入ったものです（エージェント終了後にworktreeのロックが解除され、git worktree remove/prune で手動クリーンアップできるようになった）3。自動PR化と直接セットの機能ではない点に注意してください

著者視点の発見ポイント

実際に手を動かして気づいたのは、Notification フックの hook_event_name がイベント種別ごとに分かれていない設計だという点です。てっきり agent_needs_input や agent_completed が独立した hook_event_name として届くのだろうと予想していましたが、公式ドキュメントの共通フィールド定義を素直に読む限り、種別は本文側で判定する作りになっている可能性が高いという結論に至りました。この手のマイナーな挙動は変更ログだけでは分からず、実際に自分でペイロードを組んで流してみないと確信を持てません。自動化を組み込む前に、まず手元で最小のフックを書いて動かしてみることをおすすめします。

まとめ

  • claude agents の background agents は、worktree での作業完了時に自動でコミット・push・ドラフトPR作成まで行うようになった
  • Notification フックに agent_needs_input / agent_completed が追加されたが、本記事執筆時点では公式 Hooks リファレンスの matcher 一覧には未反映
  • 実際にフックスクリプトを動かして確認したところ、通知種別は hook_event_name ではなく本文（message）側で判定する必要があった
  • 自動PR化とあわせて Explore agent のモデル継承・agent teams の失敗報告改善も同時に入っている（worktreeの自動クリーンアップは別バージョン(v2.1.186)の変更なので混同注意）

参考リンク

  1. Claude Code Changelog（GitHub） v2.1.198（2026年7月時点） ↩ ↩2 ↩3 ↩4 ↩5

  2. Claude Code Hooks リファレンス（2026年7月時点） ↩

  3. Claude Code Changelog（GitHub） v2.1.186（2026年7月時点） ↩

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?