OpenAI Codexのstop hookとは：エージェントが自律的に作業を終了する仕組み

概要¶

OpenAI Codex などの AI コーディングエージェントには「stop hook」と呼ばれる仕組みがある。エージェントが「タスクを完了した」と自律的に判断して作業を停止するトリガーの設計方法。stop hook の条件設計が甘いと、エージェントが途中で止まったり、逆に不必要な作業を続けたりする原因になる。

詳細¶

stop hook とは¶

エージェントが実行ループを終了するために評価する条件・関数のこと。以下のような判断基準を組み合わせる。

エージェントの実行ループ:

1. ユーザーのゴールを受け取る
2. ツール（コード実行・ファイル編集・検索）を使って作業
3. stop hook を評価
   ├── 条件を満たす → 作業完了として終了
   └── 条件を満たさない → ステップ2に戻る

stop hook の設計パターン¶

パターン1: テスト通過による停止¶

def stop_hook(state: AgentState) -> bool:
    """全テストが通過したら停止"""
    if state.last_tool == "run_tests":
        result = state.last_tool_output
        return result.exit_code == 0 and result.failed == 0
    return False

パターン2: ゴール達成の自己評価¶

def stop_hook(state: AgentState) -> bool:
    """エージェントが完了を宣言したら停止"""
    last_message = state.messages[-1]
    completion_signals = [
        "タスクが完了しました",
        "実装を終えました",
        "DONE",
        "TASK_COMPLETE",
    ]
    return any(sig in last_message.content for sig in completion_signals)

パターン3: ステップ数による安全停止¶

def stop_hook(state: AgentState) -> bool:
    """最大ステップ数を超えたら強制停止（無限ループ防止）"""
    MAX_STEPS = 50
    return state.step_count >= MAX_STEPS

パターン4: 複合条件¶

def stop_hook(state: AgentState) -> bool:
    # エラーが一定回数を超えたら停止
    if state.consecutive_errors >= 3:
        return True

    # ファイルの変更がなければ停止
    if state.step_count > 5 and not state.has_file_changes:
        return True

    # ゴール達成を確認
    if state.goal_achieved:
        return True

    return False

Claude Code での stop hook 設定例¶

Claude Code では settings.json の hooks セクションで Stop フックを定義できる。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Claude stopped. Notify user.' | terminal-notifier -title 'Claude Code'"
          }
        ]
      }
    ]
  }
}

stop hook 設計の注意点¶

問題	原因	対策
早期停止	判定条件が厳しすぎる	複数の成功シグナルを OR 条件で評価
無限ループ	stop 条件が実現不可能	最大ステップ数を必ず設ける
偽陽性停止	部分一致で誤検知	完了メッセージは厳密に定義する

なぜ重要か / いつ使うか¶

AI エージェントを本番ワークフローに組み込む際の設計知識として必須
「エージェントが途中で止まる」「終わらない」バグを調査するときの手がかりに
Claude Code や Codex をカスタマイズして自動化パイプラインを構築するときの参考に
エージェント設計の面接・レビューで stop condition の話が出たときの知識として