Codex CLIで長時間タスクを動かしていると、最終出力に「停止しました」と書かれることがあります。

しかし、その停止には少なくとも次の違いがあります。

Paused        人間が一時停止した
Blocked       外部入力や外部状態の変更が必要になった
UsageLimited  サービス側の利用制限に達した
BudgetLimited Goalに割り当てたToken Budgetに達した
Complete      完了条件を証拠付きで満たした

これらをすべて「止まった」と扱うと、次の操作を誤ります。

Blockedなのに同じ指示を繰り返す
BudgetLimitedなのに成功または失敗と断定する
Completeを人間による承認やmergeと取り違える
Activeを「いまプロセスが実行中」と誤解する

本記事は/goalの一般的な入門解説ではなく、現行実装の6状態、状態ごとの復旧方法、実案件での完了境界に焦点を当てます。

確認日: 2026年8月8日
対象: Codex CLIのinteractive TUI。OpenAI公式ドキュメントとopenai/codex公開ソースを確認しています。表示名や挙動は更新される可能性があります。

先に結論

/planと/goalの役割は次のように分けます。

/plan = How
        現状を調査し、到達経路を設計する

/goal = Outcome + Done + Boundaries
        成果、完了条件、権限境界を保持して実行する

Goalの状態遷移は、実務上次のように整理できます。

[No Goal] -- /goal <objective> --> [Active]
                                     |
                                     +-- /goal pause --> [Paused]
                                     |                     |
                                     | <--- /goal resume ---+
                                     |
                                     +-- external change --> [Blocked]
                                     |      required           |
                                     | <--- fix + resume -------+
                                     |
                                     +-- usage limit ------> [UsageLimited]
                                     |                         |
                                     | <--- limit clears -------+
                                     |
                                     +-- token budget -----> [BudgetLimited]
                                     |                         |
                                     |      +-- rebudget ------> [Active]
                                     |      \-- successor ----> [new Active Goal]
                                     |
                                     \-- predicate true ---> [Complete]

any existing Goal -- /goal clear --> [No Goal]

重要なのは次の3点です。

Blocked       != Failed
BudgetLimited != Complete
Complete      != Human approval / merge

正式な6状態

現行の公開スキーマには次の6状態があります。

active
paused
blocked
usageLimited
budgetLimited
complete

CLIやUIでは大文字・小文字、空白、説明文が異なる場合があります。本記事では読みやすさのため、Active、Pausedのように表記します。

状態	意味	自動継続	主な次の操作
`Active`	Goalが継続可能	条件付きで可能	継続、pause、完了判定
`Paused`	人間が自動継続を一時停止	しない	`/goal resume`
`Blocked`	外部入力・権限・環境変更なしでは有効に進めない	しない	原因解消後にresume
`UsageLimited`	アカウントまたはサービス側の利用制限	しない	制限解消後に再開
`BudgetLimited`	Goal固有のToken Budgetへ到達	しない	予算再設定または新Goal
`Complete`	完了条件を証拠付きで充足	しない	次の仕事は新Goal

遷移の制御主体も異なる

現行のGoal tool specificationでは、モデル自身が更新できる状態はCompleteとBlockedに限定されています。

Model:
  Active -> Complete
  Active -> Blocked

User / System:
  Active <-> Paused
  Active <-> UsageLimited
  Active -> BudgetLimited
  Goalのclear、置換、予算変更

これは安全上重要です。モデルが自分の判断だけで利用制限を解除したり、Token Budgetを増額したり、pauseを無視したりする設計ではありません。

Goal状態、実行状態、成果状態を分ける

/goalを扱う際に最も多い誤解は、異なる層の状態を混同することです。

1. Goal lifecycle state
   Active / Paused / Blocked / UsageLimited / BudgetLimited / Complete

2. Turn or process state
   running / idle / waiting approval / background process running

3. Repository state
   dirty / clean / tests pass / PR open / mergeable / CI pending

4. Organizational decision
   reviewed / approved / merge authorized / release authorized

例えば、次の組み合わせは矛盾しません。

Goal state:        Active
Turn state:        idle
Repository state:  clean

現在のターンは終わっていても、Goalは条件が整えば次の継続を開始できるためです。

次も矛盾しません。

Goal state:        Complete
PR state:          OPEN
Human approval:    not granted
Merge:             not performed

Goalの完了条件を「人間が最終判断できるReady状態」と定義していれば、PRをmergeしないままCompleteになります。

1. Active――「いま実行中」ではなく「継続可能」

Activeは、Goalが自動継続の対象になり得る状態です。必ずしもシェルコマンドやモデル推論が動作中という意味ではありません。

次の条件がそろうと、Goalの次のターンへ進めます。

現在のターンが完了している
スレッドがidleである
ユーザー入力がキューにない
承認待ちや別処理が残っていない
利用制限やToken Budget上限に達していない
GoalがPaused、Blocked、Completeではない

状態確認は次で行います。

/goal
/status
/ps

それぞれの対象は異なります。

コマンド	主に確認するもの
`/goal`	Goalのobjective、状態、予算・利用状況
`/status`	chat、workspace、model、権限など
`/ps`	Codexが起動したバックグラウンドterminal

2. Paused――人間が意図的に止めた状態

Goalの自動継続を止めるには次を使います。

/goal pause

再開は次です。

/goal resume

PausedではGoalのobjectiveと進捗は残ります。/goal clearとは異なります。

安全に作業を中断する場合は、Goalとバックグラウンドプロセスを分けて確認します。

/goal pause
/stop
/goal
/ps

/goal pause: Goalの自動継続を止める
/stop: Codexが開始したバックグラウンドterminalを止める
/goal clear: Goalそのものを削除する

/goal pauseだけでは、起動済みの開発サーバーやwatch processが残る場合があります。/stopだけではGoalがActiveのまま残る場合があります。

3. Blocked――現在の外部状態では進めない

Blockedは失敗確定ではありません。

Blocked
=
Goalは未達成
AND 許可範囲内に有効な次の行動がない
AND ユーザー入力または外部状態の変更が必要

現行のGoal tool specificationでは、モデルがBlockedへ遷移する条件は厳しく制限されています。

同じblocking conditionが少なくとも3回連続する
外部入力または外部状態の変更なしでは意味のある進行ができない
「難しい」「遅い」「不確実」「未完了」というだけではBlockedにしない
一度BlockedになったGoalをresumeした後は、新しいblocked auditとして数え直す

典型的なblockerは次です。

必須の認証情報がない
GitHub、クラウド、DBなどへの権限がない
外部サービスが停止している
人間による方針決定が必要
要件同士が矛盾している
禁止操作を行わなければ進めない
許可された変更範囲では解決できない

望ましいBlocked報告

Blocked時には、単に「できません」と報告させるのではなく、再開契約を残します。

Outcome: Blocked

Completed:
- ローカルで実行可能な静的検証
- 設定読み込み経路の確認
- worktree clean確認

Not completed:
- 外部API疎通
- 実データ取得
- end-to-end検証

Blocking condition:
- CHAT_SERVICE_API_TOKENが未設定
- 認証なしでは外部APIを安全に検証できない

Evidence:
- 設定検査コマンドと終了コード
- 変数名のみ。値は出力しない

Resume condition:
- 利用者が環境変数を設定する
- 値を表示せず、存在と疎通だけを再確認する

Next command:
- /goal resume

Blockedからの再開

外部状態を変更した後、同じchatで再開します。

不足していた環境変数を設定しました。
secretの値は出力せず、存在と接続可否だけを確認してください。
既存のGoal specification、scope、完了条件を維持して続行してください。

/goal resume

再開後に同じblockerが再発した場合、現行実装では新しいblocked auditとして扱われます。以前の3回をそのまま引き継いで即座にBlockedへ戻すわけではありません。

4. UsageLimited――サービス側の利用制限

UsageLimitedは、Goalに設定したToken Budgetではなく、アカウントまたはサービス側の利用制限です。

UsageLimited != BudgetLimited

例:

利用量上限
モデル利用枠
一時的なrate limit
契約・workspace側の制約

制限が解消した後、クライアントの表示に従って再開します。利用制限は外部要因なので、resume前にGoal、worktree、branch、基準SHAを再確認します。

復旧時には次を確認します。

1. 制限が解消したか
2. Goalが残っているか
3. workspaceとbranchが正しいか
4. 外部状態が途中で変わっていないか
5. 再実行すべき検証範囲はどこか

利用制限の前後でmain branchやPR headが変わる可能性があるため、単にresumeするだけでなく、基準SHAを再確認します。

5. BudgetLimited――資源切れであり成果判定ではない

現行のbudget-limit templateでは、Token Budgetへ到達すると新しい実質的作業を開始せず、進捗、残作業、blocker、次の操作をまとめるよう定義されています。

BudgetLimited != Complete
BudgetLimited != Failed

これは成果の意味ではなく、現在のGoal runに割り当てた計算資源の状態です。

BudgetLimited時に残すべきcheckpoint

Outcome: BudgetLimited

Objective:
- 変更しない

Completed:
- 何が完了したか
- どのcommitまでpush済みか
- どのテストが成功したか

Current exact state:
- branch
- local HEAD
- tracking HEAD
- remote HEAD
- PR head
- worktree status

Remaining:
- 未実装項目
- 未実行検証
- unresolved review

Known failures:
- コマンド
- 終了コード
- 最小限のerror summary

Safe resume point:
- 次に読むファイル
- 次に実行する検証
- 再開前に確認する外部状態

CLIの通常操作だけでToken Budgetを再設定できない環境では、次のいずれかを選びます。

予算変更を扱えるクライアントまたはApp Serverで再設定する
進捗checkpointを参照する新しいGoalを作る
Goalを分割し、残作業を別のobjectiveにする

新しいGoalへ切り替える場合も、完了したふりをしてCompleteにするべきではありません。

6. Complete――完了述語が真になった状態

Completeは、モデルが「十分できたと思う」と宣言する状態ではありません。

Complete
iff
すべての必須受け入れ条件が証拠付きで真
AND 必須作業が残っていない
AND 禁止操作を行っていない

例えば、PRを人間の判断直前まで進めるGoalは次のように定義できます。

Complete iff:
- Issueの受け入れ条件を実装した
- lint / typecheck / test / buildが成功した
- required checksが成功した
- 対象review threadがすべて解消された
- local / tracking / remote / PR headが一致する
- worktreeがcleanである
- PRがOPENかつレビュー可能である
- merge、auto-merge、force-pushを行っていない

ここでは「mergeしていない」ことも完了条件の一部です。

Agent completion != Human approval

実例1――PRをmergeせず、人間の判断直前まで進める

公開リポジトリのcrypto-communications-assurance PR #24では、Codexによる長時間作業の終点を「merge」ではなく、次のReady-stateに設定しました。

- 最終exact headを固定
- lint / typecheck / buildを成功
- schema checks 458件を成功
- tests 512件を成功
- docs / workflow checksを成功
- GitHub required checksを成功
- review threadをすべて解消
- local / tracking / remote / PR headを一致
- worktreeをcleanにする
- PRはOPENかつReadyのまま
- merge、auto-merge、force-pushをしない

公開PR上の最終headは次です。

a399d209e5f14a2a5e5ba295cf2442494355c584

2026年8月8日の再確認時点でも、PRはOPEN、draftではなく、mergeableでした。最終判断は人間に残されています。

このGoalの境界は次です。

Codex:
  実装、検証、レビュー対応、head整合性確認
  -> 人間が判断できるReady-stateまで

Human:
  exact headを独立に確認
  -> mergeするか判断

「Issue #10を完成させる」より、次のobjectiveの方が安全です。

PR #24の指定headについて、定義済みのReady-state gateをすべて満たす。
merge、auto-merge、release、承認の代行は行わない。

実例2――認証情報不足でBlockedになり、後から再開する

外部チャットサービスの履歴を取得するツールを想定します。

必要な環境変数:

CHAT_SERVICE_API_TOKEN
CHAT_SERVICE_ENDPOINT
ARCHIVE_ROOT
ROOM_ID

認証情報なしで実データ検証はできません。一方で、ローカルの設定検査、parser、保存形式、dry-runなどは実行できます。

望ましい進行:

Phase 0  local static checks          complete
Phase 1  credential existence check  blocked
Phase 2  API overlap                 not run
Phase 3  archive retrieval           not run
Phase 4  resume test                 not run

この場合、Codexは可能なローカル検証を終えた後、Blockedへ遷移し、resume conditionを報告します。

利用者が環境変数を設定した後は、同じGoalを再開します。

不足していた4変数を設定しました。
値を出力せず、存在・権限・疎通だけを確認してください。
開始済みGoalの未完了phaseから再開してください。

/goal resume

悪い対応は次です。

推測したtokenやdummy値で実APIへ接続する
外部検証を省略してCompleteにする
変数の値をログへ出す
同じ認証失敗を無制限に繰り返す

実例3――レビュー対応だけを限定Goalにする

既存PRへ追加レビューが来た場合、Issue全体をもう一度Goalにするとscope creepが起きやすくなります。

/goal PR #456の現在headに対する未解決review threadだけを処理する。
各指摘を検証し、妥当なものは最小変更で修正する。
反映しない指摘には技術的理由を返信する。
対象テストとrequired checksを成功させる。
レビュー範囲外の設計変更、merge、force-pushは行わない。

完了条件を開始時点のreview setへ固定します。

Complete iff:
- 開始時に記録した対象threadをすべて評価した
- 修正した指摘には必要な回帰テストがある
- 対象threadがresolvedまたは理由付き回答済み
- required checksが成功した
- PR headと報告headが一致する
- scope外変更がない

Goalの大きさを「Issue全体」ではなく「レビューセットの解消」に限定することで、完了判定が明確になります。

`/plan`はGoalの前処理として使う

本記事の主題は状態遷移ですが、/planとの関係は押さえておく必要があります。

曖昧な要求
    |
    | /plan
    v
調査済みの経路候補
    |
    | 人間がscope・制約・完了条件を確認
    v
Goal specification
    |
    | /goal
    v
実装 -> 検証 -> 状態遷移

/planで決めるもの:

現在状態
原因と依存関係
変更候補
実装順序
リスク
検証方法

/goalで固定するもの:

成立させる最終状態
完了述語
許可操作と禁止操作
scopeとnon-goals
Blocked条件
人間へ戻す判断

Planは経路仮説。
Goalは成功条件と境界。
Evidenceが完了を決める。

最小のGoal specification

詳細指示は、4,000文字のobjectiveへ詰め込むより、version管理できるファイルへ置く方が安全です。

# Objective

Issue #123の受け入れ条件を満たし、対象PRを人間が最終レビューできる状態にする。

# Scope

- src/feature-x/**
- tests/feature-x/**
- 対応する設計文書

# Non-goals

- 無関係なリファクタリング
- 公開APIの変更
- productionへの反映

# Allowed

- 対象worktree内の変更
- lint / typecheck / test / build
- 通常commitと通常push
- 対象PRの作成・更新・review返信

# Forbidden

- merge / auto-merge
- force-push / history rewrite
- mainへの直接push
- repository設定変更
- secretの表示・commit

# Required Evidence

- 受け入れ条件ごとの実装証拠
- lint / typecheck / tests / build
- git diff --check
- local / tracking / remote / PR head一致
- worktree clean
- required checks
- unresolved reviewなし

# Blocked Conditions

- 必須認証情報または権限がない
- 外部サービス障害が継続する
- 要件に解消不能な矛盾がある
- 許可範囲内に有効な解決策がない
- 不可逆操作について人間判断が必要

# Completion Predicate

上記Required Evidenceがすべて成立し、必須作業が残っておらず、Forbiddenを実行していない。

# Final Report

- Goal status
- exact head / PR URL
- 実施内容
- 検証コマンドと結果
- 未完了事項
- blockerまたは人間が次に判断する事項

Codex CLIでは次のように参照します。

/goal docs/goals/issue-123.mdを唯一の実行正本として処理する。
完了述語を客観的証拠で満たすまで継続する。
定義済みのBlocked条件に達した場合だけ停止する。

状態別の復旧runbook

Codexが止まったとき、まず/goalで状態を確認します。

/goal
  |
  +-- Active
  |     -> turn、approval、background process、queued inputを確認
  |
  +-- Paused
  |     -> 再開してよいか確認し /goal resume
  |
  +-- Blocked
  |     -> blocking conditionとresume conditionを確認
  |     -> 外部状態を変更し /goal resume
  |
  +-- UsageLimited
  |     -> 利用制限解消を待つ
  |     -> branch / head / external stateを再確認して再開
  |
  +-- BudgetLimited
  |     -> checkpointを確認
  |     -> 予算再設定、新Goal、作業分割を選ぶ
  |
  +-- Complete
        -> evidenceとexact headを独立確認
        -> 人間が承認・merge・releaseを判断

よくある誤り

`Pursuing`を正式な状態名だと思う

UIの説明としてPursuing goalのような表示があっても、公開スキーマ上の状態名はActiveです。

`Unmet`をGoal状態として扱う

「未達」は人間向けの結果表現です。正式状態としては、原因に応じてBlocked、BudgetLimited、UsageLimitedなどを使います。

難しい作業をすぐBlockedにする

難しさはblockerではありません。外部状態の変更なしでは意味のある進行ができないことが必要です。

テスト成功だけでCompleteにする

既存テストが受け入れ条件を網羅していない場合があります。

Complete
=
Acceptance conditions
AND Required tests
AND Constraint preservation
AND No required work remaining

BudgetLimitedを失敗とみなす

資源上限と成果の意味を分けます。checkpointと残作業が正確なら、別runへ安全に引き継げます。

Completeになったので自動mergeする

技術的完了と組織的承認は別です。特に本番、release、法務・セキュリティ責任を伴う操作は人間へ残します。

実行前チェックリスト

[ ] codex --versionを記録した
[ ] /goalがスラッシュメニューにある
[ ] Outcomeを状態として一文で書いた
[ ] 完了述語が観測可能である
[ ] scopeとnon-goalsを定義した
[ ] AllowedとForbiddenを定義した
[ ] Required Evidenceを具体化した
[ ] Blocked条件とresume条件を定義した
[ ] BudgetLimited時のcheckpoint形式を定義した
[ ] Completeとhuman approvalを分離した
[ ] secretをログや成果物へ出さない
[ ] final reportにexact headを含める

まとめ

/goalを実務で使う場合、最も重要なのは自動継続そのものではありません。

1. 状態を正しく分類する
2. 状態ごとに異なる復旧操作を行う
3. 完了を証拠で判定する
4. 技術的完了と人間の承認を分ける

特に次の区別を維持すると、長時間作業の制御が安定します。

Blocked       != Failed
BudgetLimited != Complete
Complete      != Human approval
Goal state    != Process state

Goalは「最後まで頑張らせる指示」ではありません。成果、境界、停止理由、再開条件を外部から検証できる実行契約です。

参考資料