Claude Code ガイド

Appearance

長時間セッションでStop/SubagentStopフックが失敗する問題と、フック評価APIエラーの誤表示を修正 ​

原文（日本語に翻訳） ​

長時間セッションでプロンプトタイプのStop/SubagentStopフックが失敗する問題と、フック評価APIエラーで「JSONバリデーションに失敗しました」の代わりに実際のエラーメッセージが表示されない問題を修正しました。

原文（英語） ​

Fixed prompt-type Stop/SubagentStop hooks failing on long sessions, and hook evaluator API errors showing 'JSON validation failed' instead of the real message

概要 ​

Claude Codeのフック機能において2つの問題が修正されました。1つ目は、長時間のセッションで Stop および SubagentStop フック（プロンプトタイプ）が正常に実行されない問題です。2つ目は、フック評価中にAPIエラーが発生した際に実際のエラーメッセージではなく「JSON validation failed」という誤ったメッセージが表示される問題です。

基本的な使い方 ​

修正1: Stop/SubagentStopフックの長時間セッション対応 ​

修正前の動作:

json
// settings.json のフック設定例
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "作業完了後にサマリーをsummary.mdに保存してください"
          }
        ]
      }
    ]
  }
}
# 短時間のセッション（例: 30分）: フックが正常に実行される ✓
# 長時間のセッション（例: 3時間）: フックが失敗する ✗
# → 終了処理のフックが動作せず、後処理が行われない

修正後の動作:

# セッション長さに関わらずフックが正常に実行される
# 短時間セッション: 正常動作 ✓
# 長時間セッション: 正常動作 ✓

修正2: フック評価APIエラーの正確なメッセージ表示 ​

修正前の動作:

# フック実行中にAPIエラーが発生した場合
エラー: "JSON validation failed"
# → 実際のエラー原因が分からず、デバッグが困難だった

修正後の動作:

# 同じ状況でのエラーメッセージ
エラー: "Request timeout: The API request timed out after 30 seconds"
# または
エラー: "Invalid API key: The provided API key is not valid"
# → 実際のエラーメッセージが表示され、問題を特定しやすい

実践例 ​

### 長時間の開発セッション後の自動後処理 ​

一日の作業終了時に自動でサマリーを生成するフック：

json
// settings.json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "今日の作業内容をsummary.mdにまとめてください。変更したファイル、実装した機能、残タスクを含めてください。"
          }
        ]
      }
    ]
  }
}
# 一日の長時間作業後にClaude Codeを終了
/exit または Ctrl+C

# 修正後: セッションが長くてもStopフックが正常に実行され、
# summary.mdが自動生成される

### SubagentStopフックによる完了通知 ​

サブエージェントの完了時に通知を送るフック：

json
// settings.json
{
  "hooks": {
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'サブエージェントのタスクが完了しました'"
          }
        ]
      }
    ]
  }
}
# 長時間動作するサブエージェントの処理完了後
# 修正後: SubagentStopフックが正常に実行され、通知が送られる

### APIエラーのデバッグ ​

フックが失敗した際の問題特定が容易に：

# フック設定に問題がある場合のデバッグ

# 修正前のエラーメッセージ
エラー: "JSON validation failed"
# → 何が問題か特定できない

# 修正後のエラーメッセージ例
エラー: "The 'prompt' field cannot be empty"
エラー: "API rate limit exceeded"
エラー: "Model 'claude-invalid' not found"
# → 具体的な問題が分かり、素早く修正できる

注意点 ​

  • Stop フックはユーザーがセッションを終了した際に実行されます。SubagentStop フックはサブエージェントが完了した際に実行されます。
  • 長時間セッションでのフック失敗は、セッションデータが一定サイズを超えた場合にプロンプトタイプのフックで発生していました。コマンドタイプのフックは影響を受けていませんでした。
  • フック評価のエラーメッセージ改善により、フック設定のデバッグが大幅に容易になります。
  • フックはClaude Codeのセキュリティモデル内で実行されるため、許可された操作のみが実行可能です。

関連情報 ​