Claude Code の Request timed out、Bash tool の待機終了、terminal の切断、session の再開は、すべて「長時間タスクが止まった」ように見えます。しかし、それぞれ別の lifecycle であり、残っている state も異なります。
復旧の最初の問いは「もう一度実行するか」ではなく、「どの時計が切れ、どの副作用がすでに存在するか」です。request、command、conversation、file rollback、durable project state を分けて初めて、retry、resume、rewind、respawn のどれが安全か判断できます。
Request timeout と Bash timeout は別の時計
現在の公式エラーリファレンスでは API_TIMEOUT_MS の default は 600000ms、つまり model request ごとに10分です。別の環境変数リファレンスでは、Bash tool の BASH_DEFAULT_TIMEOUT_MS は120000ms、BASH_MAX_TIMEOUT_MS は600000msが default です。
Request timeout は Claude Code が deadline までに model response を受け取れなかったことを示します。Bash timeout は tool invocation の待機上限であり、model request やすべての child process の状態を示すものではありません。さらに、全体の時間、費用、risk に対する job deadline は利用者が別に決めます。
公式文書は Request timed out の原因として高負荷や非常に大きな response を挙げています。作業を小さな unit に分ける方が、単純に timeout を延ばすより復旧点が明確になります。遅い network や proxy が既知の bottleneck の場合だけ API_TIMEOUT_MS の変更を検討してください。時間を延ばしても checkpoint や idempotency は得られません。
Claude Code は server error、overload、request timeout、一時的な429、connection drop を default で最大10回、指数 backoff 付きで自動 retry します。最終エラーが表示された時点では、その retry は使い切られています。外側に無制限 loop を追加すると、費用や side effect の重複を増やす危険があります。
閉じるものを決めてから実行方法を選ぶ
| 必要な状態 | 候補 | 重要な制約 |
|---|---|---|
| 完了条件まで Claude に turn を続けてほしい | /goal | 現在の session が基準。evaluator は会話に出た証拠だけを見る |
| test、build、dev server を動かしながら会話したい | Background Bash、Ctrl+B、/tasks | Claude Code 終了時に command は cleanup される |
| terminal を閉じても local agent session を維持したい | Agent view の background session | PC、network、usage、permission には依存する |
| 後日同じ conversation に戻りたい | --continue、--resume | transcript の復元であり、旧 process の復元ではない |
| 開いている session で定期確認したい | /loop、cron tools | session-scoped で有効期限がある |
| PC を閉じた後も継続したい | Remote session、Routines、CI | cloud environment に local の未 commit 状態は自動で移らない |
Interactive mode の公式説明では、background Bash command は Claude Code 終了時に自動 cleanup されます。Ctrl+B は「長い process の間も Claude と対話する」ための機能であり、shutdown 後の永続化ではありません。
/goal には成果ではなく検証可能な条件を書く
大規模 refactoring に「最後までやって」と指示しても、どの test が通れば最後なのか、どの file を変更してはいけないのかが分かりません。長時間実行では、目標と同時に verifier と停止条件を渡します。
text/goal auth module の async API 移行を完了する。 npm test -- auth と npm run typecheck が exit 0、 legacyAuthClient の call site が 0 件であることを示す。 database schema は変更しない。15 turns または2時間で未完なら停止して blocker を報告する。
/goal のドキュメントによると、各 turn の終了後に別の小さな model が条件を判定し、未達なら次の turn が始まります。判定側は command を実行せず、file も直接読みません。したがって Claude 自身が test や search を実行し、その結果を transcript に出す必要があります。
Active goal は同じ session を --continue または --resume すると復元されます。ただし timer、turn count、token の基準は再開時に reset されます。これは作業を別の時間帯に再開できるという意味で、停止中も agent が動いたという意味ではありません。
Dev server と test は Background Bash で非同期化する
現在の conversation を保ったまま dev server、test suite、build、Docker などを動かすなら Background Bash が適しています。Bash tool の実行中に Ctrl+B を押すか、Claude に background で実行するよう依頼します。tmux では prefix と重なるため Ctrl+B を2回押します。
Command には task ID が付き、output は file に保存されます。/tasks（/bashes でも可）から確認、attach、stop ができます。test を待ちながら原因を調べる、server を動かしながら UI を直す、といった同一 session 内の並行作業に向いています。
一方、output が 5GB を超えると current contract では task が終了します。大量ログは level を下げる、rotation する、専用 process manager に渡すといった対策が必要です。Claude Code 自体を終了する予定なら、Bash の detach option を重ねるより、所有者が明確な service や background session に移します。
Terminal から離れるなら background session を使う
Agent view のドキュメントでは、background session は terminal の child ではなく user ごとの supervisor が管理する Claude Code process です。
bashclaude agents claude attach <id> claude logs <id> claude stop <id> claude respawn <id>
作業中、入力待ち、または terminal が attach している session は process を維持します。完了後に unattached のまま約1時間経つと、resource 解放のため process が停止することがありますが、transcript と state は disk に残り、次回 attach で復旧します。
これで terminal window への依存は減ります。しかし実行場所は local PC です。sleep、shutdown、network 切断、usage limit、認証失敗、permission prompt は依然として停止原因です。PC を閉じても続ける必要があるなら local background session は要件を満たしません。
Checkpoint はlocal undoでありtransactionではない
Claude Code は user prompt ごとに checkpoint を作成します。Esc を2回押すか /rewind を実行すると、code、conversation、その両方を戻すか、選択した範囲の context を要約できます。Checkpointing の公式説明では、これらは再開した session でも利用できます。
ただし rewind が追跡するのは Claude の file editing tool による変更です。Bash command、手動や外部 tool の変更、別の concurrent session の変更は元に戻せません。Database rollback でも Git の代替でもありません。Migration、code generation、external API を含む workflow では、git diff、generated file、database、外部 state を別々に確認します。
長時間タスクの checkpoint は二層にすると扱いやすくなります。Claude Code の prompt checkpoint は conversation と直接編集に使い、project 側の ledger は完了 unit、verification、不可逆な side effect を記録します。後者は verification が成功した後だけ更新します。
/loop、Desktop、Routines を同じ scheduler と考えない
/loop と scheduled taskは、現在の session で deployment や CI を定期確認する用途に合います。
text/loop 10m integration job を確認し、失敗していたら最後の failing step と 次に試す最小の action を報告する
Scheduled prompt は Claude が turn の途中にいないときに実行されます。Recurring task は7日で expire し、miss した interval をすべて後追い実行することはありません。Resume で unexpired schedule は戻せますが、background Bash と monitor task は復元されません。
より長い lifecycle が必要なら実行面を変えます。
- Desktop scheduled tasks は local file に access できますが PC の電源が必要です。
- Claude Code Desktopの Remote session は Anthropic cloud で動き、app を閉じたり PC を shutdown した後も続きます。
- Routinesは schedule、API、対応 event ごとに新しい cloud session を作り、実行結果を review できます。
- CI は repository event、cron、log、approval gate を一つの workflow に置きたい場合に適します。
Cloud に移せば local の uncommitted file、service、secret、MCP が自動で付いてくるわけではありません。必要な branch、environment、入力 artifact を明示し、run が終了したことと task が成功したことを分けて確認します。
Context の外に復旧用 state を残す
Session 管理では、CLI conversation は継続的に保存され、claude --continue、claude --resume、/resume で戻れます。ただし transcript は唯一の state store にしない方が安全です。
長時間 task 用の file には、少なくとも次を残します。
md目的と禁止事項 - 何を変えるか、何を変えないか 完了済み - milestone、対象 file、verification command、結果 現在の blocker - exact error、再現方法、否定済みの仮説 次の action - 1つの具体的な手順と停止条件
Anthropic の長時間 scientific computing の事例でも、progress file、test oracle、明確な rule、Git checkpoint が使われています。これは HPC 向けの実例であり必須構成ではありませんが、進捗を model context だけに置かない考え方は一般化できます。
Parallel session を使うなら worktree と file ownership を分離します。複数 worker が必要な場合は Claude Code Agent Teamsも参考になりますが、各 lane の完了条件は別に必要です。
Permission の interruption を消す前に権限を狭める
Permission modeは中断頻度と監督を調整します。acceptEdits は edit を進めやすくし、dontAsk は pre-approved tool だけを実行します。Auto mode は追加 classifier で action を確認しながら prompt を減らしますが、research preview であり version、plan、model、provider、admin setting の条件があります。
bypassPermissions は permission layer を外すため、Anthropic は isolated container または VM 向けとしています。Unattended task では file system、network、credential、branch、budget を狭くし、deployment、purchase、secret 送信、destructive action の前で停止させる方が重要です。
Usage limit で止まった場合は、goal、diff、最後の verification、次の action を先に保存し、Claude Code の利用上限診断へ切り替えます。
Retry の前に副作用を照合する
Response が失敗しても、turn 内で試みた action がrollbackされたとは限りません。再実行前に、目的の file がすでに存在するか、test や build の artefact が残っているか、process が期待する owner の下で動いているか、external API が request を受け取ったかを確認します。
Unit は可能なら冪等にします。すでに望ましい state ならskipし、外部 system が operation key を受け付けるなら安定した key で重複を防ぎます。不可能な場合は、verify、compensate、retry のどれを選ぶか判断できる evidence を残します。
API error で turn が終わると StopFailure hook が発火しますが、Hooks リファレンスでは output と exit code は無視されます。Logging や通知には使えても、failed turn を自動再開する仕組みではありません。自作 recovery loop にも retry budget と照合 rule が必要です。
再開時は「続けて」だけを送らず、task file、git status、process の存在、最後の log、最小 verification を順に確認します。現在どの runtime が所有しているか、state がどこにあるか、何が完了を証明するか。この三点が追跡できれば、terminal や session が途中で止まっても、長時間 task は推測ではなく手順で復旧できます。
