claude agentsのdraft PR自動化、通知はagent view限定だった

Posted at 2026-07-09

はじめに

このリポジトリの記事執筆パイプラインは、Claude Cloudのスケジュール実行で claude を無人稼働させている。今回そのセッション自身から claude agents --json を叩いてみたところ、面白いことに気づいた。このパイプライン自身も「1つのセッション」として claude agents の管理対象に見えている。

Claude Codeは v2.1.198（2026-07-01）で、バックグラウンドAgent（claude agents / claude --bg）が worktree 内で作業を終えると、確認なしで commit・push・draft PR作成まで自動でやる ようになった¹。実際にこの環境で動かして検証する。

この記事でわかること

claude agents のバックグラウンドAgentが何を自動化するようになったか（公式ソース付き）
claude agents --json を実際に叩いた実測ログ
完了通知（Notification hook）を設定したのに鳴らない、というハマりどころ

前提環境

Claude Code: v2.1.205（2026-07-08リリース）²
実行環境: Claude Cloud スケジュール実行（本記事執筆パイプライン自身）

TL;DR

v2.1.198で、worktree isolationされたバックグラウンドAgentは 作業完了時に自動でcommit→push→draft PR を開くようになった。mainへの直接pushやforce-push・mergeは一切しない安全設計
claude agents --json で今動いているセッション一覧をJSON取得できる。このパイプライン自身も "kind": "interactive" の1行として見えた
落とし穴: 完了通知（agent_needs_input / agent_completed）を拾うNotification hookは、claude agents（agent view）を開いている間しか発火しない³。バックグラウンドで放置していると通知は来ない

背景・課題

claude agents は複数のClaude Codeセッションを1画面で管理する機能で、v2.1.139（2026-05-11）でリサーチプレビューとして登場した⁴。それまでバックグラウンドAgentは「作業が終わったら人間に確認してからcommit/PRを作る」挙動だったが、v2.1.198の変更点は次の1行に集約される。

As of v2.1.198, a background session that isolated its code changes in a worktree also commits, pushes its own branch, and opens a draft pull request without stopping to ask.
— Manage multiple agents with agent view（Claude Code公式ドキュメント）

「確認を待たずに」が今回の変更の核心である。ただし安全側の制約も明記されている:

main / master へは 絶対にpushしない
force-pushや自動mergeは 一切しない
PRを作らないよう指示していた場合、またはリポジトリにremoteが無い場合はPR作成をスキップする

実際に動かしてみた

このパイプラインが動いている実環境で、まず現在のバージョンを確認した。

$ claude --version
2.1.205 (Claude Code)

v2.1.198（draft PR自動化の導入）より新しく、この機能は有効な状態のはずである。次に claude agents --json でセッション一覧を取得した。

$ claude agents --json
[
  {
    "pid": 577,
    "cwd": "/home/user/zenn-blog-automation",
    "kind": "interactive",
    "startedAt": 1783593103964,
    "sessionId": "93bedbd6-4091-59f9-aa95-84fbbb165af9",
    "name": "zenn-blog-automation-ef"
  }
]

このスケジュール実行セッション自身が "kind": "interactive" として1件だけ表示された。claude agents --json は「今生きているセッション＋処理中/ブロック中のバックグラウンドセッション」を返す仕様で、--all を付けると完了済みのバックグラウンドセッションも含まれる⁵。

もう1つ、バックグラウンドAgentを支える supervisor（常駐プロセス）の状態も確認した。

$ claude daemon status
not running

bg sessions:
  sock dir:     /tmp/cc-daemon-0/addcfb49
  control.sock: unreachable (connect ENOENT ...)
  bg workers:   0 in roster.json (control unreachable)
  roster.json:  absent

supervisorは「一度もバックグラウンドセッションを起動していない・または claude agents を開いていない」環境では起動していない。supervisorは claude --bg かバックグラウンド化（/bg）のどちらかを初めて実行したタイミングで自動起動する⁵。つまりこのパイプラインは claude -p（ヘッドレス実行）でセッションを直接起動しており、claude agents のバックグラウンドAgent機構そのものは経由していないことがログからも裏付けられた。

draft PR自動化を使う手順

claude agents からバックグラウンドAgentを使う最短ルートは以下の3通り。

# 1. agent view を開いて対話的にディスパッチ
claude agents

# 2. 対話セッションの途中でバックグラウンド化
/bg このリポジトリのlintエラーを直して

# 3. シェルから直接バックグラウンド起動
claude --bg "READMEのtypoを一括で直して"

バックグラウンドAgentはファイル編集の前に自動で .claude/worktrees/ 配下へ隔離される（すでにworktree内にいる場合や、リポジトリでない場合を除く）⁴。worktree隔離が働いた状態でタスクが完了すると、v2.1.198以降は次を 確認なしで 実行する。

変更をそのブランチにcommit
自分のブランチをpush
draft PRを作成

claude agents の画面では、PRが開くと行の右端に #1234 のラベルが付き、色でステータスが分かる（黄=チェック待ち/レビュー待ち、緑=チェック通過、紫=マージ済み、グレー=draft/クローズ）⁴。

worktree隔離をオフにしたいリポジトリは .claude/settings.json に以下を設定する。

{
  "worktree": {
    "bgIsolation": "none"
  }
}

この設定を入れると、バックグラウンドAgentは作業ディレクトリを直接編集するようになり、commitやブランチ切り替えの前に 改めて確認を求める 挙動に戻る⁴。

ハマりポイント: Notification hookは agent view を開いていないと鳴らない

バックグラウンドAgentの完了を検知するために、~/.claude/settings.json にNotification hookを仕込んだ場合を考える。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Agentが完了/入力待ちになりました'"
          }
        ]
      }
    ]
  }
}

公式リファレンスのマッチャー一覧を見ると、agent_needs_input と agent_completed には次の注記が付いている³。

agent_needs_input: A background session starts waiting on your input. Fires only while agent view is open
agent_completed: A background session finishes or fails. Fires only while agent view is open
— Automate actions with hooks「Get notified when Claude needs input」節

つまり claude --bg でタスクを投げっぱなしにして端末を閉じてしまうと、この2つのイベントは発火しない。バックグラウンドAgentの完了を見逃さない構成にしたいなら、「claude agents を開いたままにしておく」か、「定期的に claude agents --json をポーリングして state フィールド（working / blocked / done / failed / stopped）を自前でチェックする」かのどちらかが必要になる。通知フックを設定しただけで安心してagent viewを閉じると、完了通知は来ない というのが実測で確認できた落とし穴である。

著者視点の発見ポイント

このリポジトリのようにClaude Cloudのスケジュール実行（claude -p ヘッドレス起動）でパイプラインを回している場合、今回の draft PR 自動化そのものの恩恵は直接は受けられない。claude agents --json で確認した通り、このセッションは "kind": "interactive" として動いており、supervisorも起動していないため、claude agents のバックグラウンドAgent経路（worktree隔離→自動commit→自動push→自動draft PR）を通っていないからだ。

ただし応用の余地はある。長時間かかる調査・検証タスク（例えば大量記事のファクトチェックのやり直しや、依存ライブラリの一括アップデート検証）を claude --bg でリポジトリのworktreeに投げ、claude agents --json を別プロセスからポーリングして state: "done" を検知した瞬間だけ本パイプラインに合流させる、という設計は現実的に組める。人間の確認を待たずにdraft PRまで自動で上がる今回の変更は、まさに「無人運用のパイプラインに、もう1段別系統のバックグラウンドAgentを差し込む」ユースケースに向いている。

まとめ

Claude Code v2.1.198で、worktree隔離されたバックグラウンドAgentは作業完了時に自動でcommit・push・draft PRを作るようになった（mainへのpush・force-push・自動mergeは一切しない）
claude agents --json で今動いているセッションをJSON取得できる。このパイプライン自身もその1行として見えた
Notification hookの agent_needs_input / agent_completed は agent viewを開いている間しか発火しない。ポーリング前提の設計にしないと完了を見逃す

参考リンク

Manage multiple agents with agent view — draft PR自動化・worktree隔離の仕様
Automate actions with hooks — Notification hookのマッチャー一覧
Claude Code changelog — v2.1.198・v2.1.205のリリースノート

Manage multiple agents with agent view「How file edits are isolated」節（2026-07時点） ↩
Claude Code changelog v2.1.205（2026-07-08） ↩
Automate actions with hooks「Get notified when Claude needs input」節のマッチャー表 ↩ ↩²
Manage multiple agents with agent view ↩ ↩² ↩³ ↩⁴
Manage multiple agents with agent view「Manage sessions from the shell」節 ↩ ↩²

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up