Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

StopおよびSubagentStopフックの入力に background_tasks フィールドと session_crons フィールドが追加されました

原文（英語） ​

Stop and SubagentStop hook input now includes background_tasks and session_crons fields

概要 ​

Claude Code v2.1.145から、Stop フックおよび SubagentStop フックに渡される入力データに、background_tasks と session_crons の2つの新しいフィールドが追加されました。これにより、セッションやサブエージェントが終了する際に、実行中のバックグラウンドタスクやスケジュールされたcronジョブの状態を把握し、適切なクリーンアップや後処理を行えるようになります。

基本的な使い方 ​

Stopフックのスクリプトで新しいフィールドを参照できます。

json
// Stopフックに渡される入力データの例
{
  "session_id": "session-abc123",
  "stop_hook_active": true,
  "background_tasks": [
    {
      "task_id": "task-001",
      "description": "データベースのマイグレーション",
      "status": "running"
    }
  ],
  "session_crons": [
    {
      "cron_id": "cron-001",
      "schedule": "*/5 * * * *",
      "command": "npm run health-check"
    }
  ]
}
bash
# .claude/hooks/stop.sh
#!/bin/bash
INPUT=$(cat)

# background_tasksの数を確認
BG_TASK_COUNT=$(echo "$INPUT" | jq '.background_tasks | length')
CRON_COUNT=$(echo "$INPUT" | jq '.session_crons | length')

echo "セッション終了: バックグラウンドタスク ${BG_TASK_COUNT}件, Cron ${CRON_COUNT}件"

実践例 ​

バックグラウンドタスクが残っている場合に警告を表示 ​

bash
#!/bin/bash
# .claude/hooks/stop.sh - タスク残存時に警告

INPUT=$(cat)

BG_TASKS=$(echo "$INPUT" | jq '.background_tasks')
TASK_COUNT=$(echo "$BG_TASKS" | jq 'length')

if [ "$TASK_COUNT" -gt 0 ]; then
  echo "警告: $TASK_COUNT 件のバックグラウンドタスクが実行中です"
  echo "$BG_TASKS" | jq -r '.[] | "  - \(.description // .task_id): \(.status)"'
  
  # 終了をブロックする場合はexit 2を返す
  # exit 2
fi

session_cronsのクリーンアップ処理 ​

bash
#!/bin/bash
# .claude/hooks/stop.sh - セッション終了時にcronをクリーンアップ

INPUT=$(cat)

SESSION_CRONS=$(echo "$INPUT" | jq '.session_crons')
CRON_COUNT=$(echo "$SESSION_CRONS" | jq 'length')

if [ "$CRON_COUNT" -gt 0 ]; then
  echo "セッション終了: $CRON_COUNT 件のcronジョブが登録されています"
  echo "$SESSION_CRONS" | jq -r '.[] | "  - \(.cron_id): \(.schedule) -> \(.command)"'
  
  # 外部システムへのcronジョブ停止通知
  CRON_IDS=$(echo "$SESSION_CRONS" | jq -r '.[].cron_id')
  for cron_id in $CRON_IDS; do
    echo "Cron停止: $cron_id"
    # curl -X DELETE "https://api.example.com/crons/${cron_id}"
  done
fi

SubagentStopフックでの後処理 ​

bash
#!/bin/bash
# .claude/hooks/subagent-stop.sh - サブエージェント終了時の処理

INPUT=$(cat)

SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
BG_TASKS=$(echo "$INPUT" | jq '.background_tasks // []')
SESSION_CRONS=$(echo "$INPUT" | jq '.session_crons // []')

# サブエージェントの完了情報をログに記録
LOG_FILE="/tmp/claude-subagent-${SESSION_ID}.log"
cat >> "$LOG_FILE" <<EOF
$(date '+%Y-%m-%d %H:%M:%S') - SubagentStop
Session: $SESSION_ID
Background Tasks: $(echo "$BG_TASKS" | jq 'length')
Session Crons: $(echo "$SESSION_CRONS" | jq 'length')
---
$(echo "$BG_TASKS" | jq -r '.[] | "  Task: \(.task_id) [\(.status)]"')
$(echo "$SESSION_CRONS" | jq -r '.[] | "  Cron: \(.cron_id) [\(.schedule)]"')
EOF

echo "ログ記録完了: $LOG_FILE"

未完了タスクをSlackに通知 ​

bash
#!/bin/bash
# .claude/hooks/stop.sh - 未完了タスクをSlack通知

INPUT=$(cat)
SLACK_WEBHOOK="${SLACK_WEBHOOK_URL}"

BG_TASKS=$(echo "$INPUT" | jq '[.background_tasks[] | select(.status == "running")]')
TASK_COUNT=$(echo "$BG_TASKS" | jq 'length')

if [ "$TASK_COUNT" -gt 0 ] && [ -n "$SLACK_WEBHOOK" ]; then
  TASK_LIST=$(echo "$BG_TASKS" | jq -r '.[] | "• \(.description // .task_id)"' | head -5)
  
  curl -s -X POST "$SLACK_WEBHOOK" \
    -H 'Content-type: application/json' \
    --data "{
      \"text\": \"Claude Codeセッション終了: ${TASK_COUNT}件のタスクが未完了です\n${TASK_LIST}\"
    }"
fi

注意点 ​

  • background_tasks と session_crons はどちらも配列形式で提供されます。セッションに該当するものがない場合は空の配列 [] が返されます
  • 既存のStopフックスクリプトは引き続き動作します（新しいフィールドは追加されるだけで、既存のフィールドは変更されません）
  • background_tasks の具体的なフィールド構造はタスクの種類によって異なる場合があります。jq の // 演算子などでデフォルト値を設定することを推奨します
  • SubagentStop フックはサブエージェントが終了するたびに呼び出されます（メインの Stop フックとは別です）
  • フックスクリプトでエラーが発生した場合でも、セッションの終了処理は継続されます

関連情報 ​