OpenCode 2.3 実地検証:サブエージェント、タイムアウトしたコマンド、コンテキスト圧縮がバックグラウンドへ
結論: OpenCode 2.3.0(11 月 13 日)と 2.3.1(日本時間 11 月 18 日 9 時 17 分)で、これまで待たされていた 3 つの処理が既定でバックグラウンドに移った。サブエージェントの呼び出しはすぐ戻り、結果は子が idle になった時点で親に届く。タイムアウトに達したシェルコマンドは殺されずにバックグラウンドへ移り、終わったら報告が来る。自動圧縮のしきい値に近づくと要約は裏で先に書かれていて、しきい値では差し替えるだけになる。[1][2] ほとんどの環境では何も変えなくてよい。確認が必要なのは次のケースだ。
| 状況 | やること |
|---|---|
npm i -g opencode-ai で入れた | このパッケージは 1.x 専用で、1.19.6 で止まっている。2.x は @opencode/cli。npm i -g @opencode/cli か curl -fsSL https://opencode.ai/v2/install | bash で入れる。[3] |
| タイムアウトでコマンドを止めることに頼っている | タイムアウトはもう止めない。上限が必要ならコマンド側に timeout 60 <cmd> と書く。フォアグラウンドの timeout: 0 は既定の 120 秒の意味になった。 |
設定に experimental.background_compaction か shell_timeout_background がある | 前者は削除。compaction.background(既定 true)を使う。後者のフラグもなくなったが、書いたままでも読み込める。 |
| 使われない要約にトークンを払いたくない | opencode.jsonc に "compaction": { "background": false } と書く。 |
プロジェクトに CLAUDE.md しかない | 2.3.1 は再びこれを読む。不要なら OPENCODE_DISABLE_CLAUDE_CODE=1 を設定する。 |
同じ 3 つの仕組みでも、他の harness の既定はかなり違う。
| シェルのタイムアウト | サブエージェント | 自動圧縮 | |
|---|---|---|---|
| OpenCode 2.3.1 | バックグラウンドへ移して通知 | 常にバックグラウンド、idle 時に報告 | 60k トークン手前で要約を先に書く |
| Claude Code 2.1.327 | バックグラウンドへ移す(sleep で始まるものは除く) | 既定でバックグラウンド | 上限に達してから圧縮、放置時の圧縮もある |
| Codex CLI 0.169.1 | セッション ID を返し、モデルがポーリング | 依頼されたら spawn、メインは結果を待つ | モデル既定のしきい値、async_compaction はオフ |
| Gemini CLI 0.68.0 | 出力なしで 300 秒たつと終了 | ツールとして呼び、戻るまで待つ | 50% で圧縮 |
| Qwen Code 0.28.0 | 120 秒で終了 | 既定でバックグラウンド、完了を通知 | 約 85% で圧縮 |
これは「Agent Harness 動向」の第 1 回で、OpenCode を軸に、同じ仕組みを他の harness がどう扱っているかも見ていく。OpenCode が前回このサイトに登場したのは Console への侵入事件のときだった(英語版:After the OpenCode Breach)。
1.x と 2.x は別の npm パッケージになった
テスト機には opencode-ai パッケージで入れた 1.18.31 があった。このパッケージの latest は 1.19.6 で、npm update を何度やっても 2.x にはならない。OpenCode 2 は @opencode/cli として配布されている。v1 用のインストールスクリプトは 2.x の指定を拒否し、https://opencode.ai/v2/install か opencode upgrade --major を使うよう案内する。[3]

先に opencode-ai をアンインストールする。両方のパッケージが opencode というコマンド名を使うからだ。npm はインストールスクリプトが実行されなかったと警告するが、実害はない。入ったバイナリは release の opencode-linux-x64.tar.gz から取り出したものとハッシュが一致した。2.x は既定でバックグラウンドサービスを起動し、CLI はそれを通じて動く。opencode run --standalone は実行ごとに専用サーバーを立てて、終わると止める。この違いは後の圧縮テストで効いてくる。
テストはすべて専用の XDG_* ディレクトリで行い、有料アカウントはつながず、OpenCode Zen に並ぶ無料モデルを使った。
図:テスト機で計った 3 つのバックグラウンド化。サブエージェントとシェルの行は上の時間軸に沿う。圧縮の 2 行は同じ入力を 2 つの設定で流した比較。
サブエージェント:呼び出しはすぐ戻り、結果は後から届く
2.3.0 より前は、親セッションはサブエージェントが終わるまで待っていた。今は subagent ツールがすぐにセッション ID を返し、子は裏で作業を続ける。子が idle になるたびに親へ <subagent> メッセージが届き、その後に子がもう一巡すれば再び届く。[1] ツールがモデルに返す文面ははっきりしている。sleep しない、ポーリングしない、子の仕事を重複させない。重ならない作業をするか、何を起動したかをユーザーに伝えてターンを終える。

テストでは子に sleep 15 の後でタイムスタンプを書かせ、親にはツールが戻った直後に別のタイムスタンプを書かせた。parent.txt は 09:04:55、sub.txt は 09:05:10 で、差はちょうど sleep 1 回分になる。親のターンが終わっても opencode run は終了せず、waiting for 1 background job と表示して、報告が届いたところでターンを再開した。スクリプトや CI から opencode run を呼んでも、子が走っている途中の半端な答えを受け取ることはない。
子が自分でもバックグラウンド処理を始めることがある。たとえば長いコマンドがバックグラウンドに移り、子自身は先に idle になる場合だ。2.3.0 からは、このときの報告に「still running」と付くので、親は途中の答えを結論と取り違えずに最終報告を待つ。[1] 2.3.1 では関連するバグも直った。子の回答が「Background work still running」という見出しを引用していると、実行中と誤判定されていた。[2]
利点は、親がただ待たなくなり、互いに関係のない子を同時に複数走らせられることだ。代償は 2 つある。並行で動くぶん、複数のコンテキストが同時にトークンを使う。そしてモデルには「投げたら手を離す」振る舞いが求められる。プロンプトに「サブエージェントが終わってから……」と書いてあっても動くが、待つのはランタイムの仕事で、モデルが sleep して待つものではない。サブエージェントの権限確認は、そのセッションを開いているときに表示されるようになった。1 件を拒否しても、拒否されるのは同じステップの他の要求だけで、セッション全体の保留中の要求までは拒否されない。[2]
シェルのタイムアウト:止めずにバックグラウンドで続ける
2.3.1 でいちばん実用的な変更がこれだ。タイムアウトに達してもまだ動いているシェルコマンドは、すべてのビルドでバックグラウンドに移る。出力はファイルに書かれ続け、コマンドが終わるとセッションが起きて結果を受け取る。2.3.0 では実験フラグ shell_timeout_background の裏にあった機能で、2.3.1 で既定になりフラグは削除された。フラグを書いたままの設定もそのまま読み込める。[1][2]

テストのコマンドは date +%T; sleep 20; date +%T; echo SLEEP-DONE > done.txt、タイムアウトは 5 秒。5 秒の時点でツールは「Command moved to the background」を返し、シェル ID、PID、出力先のパスと、同じコマンドをもう 1 つ起動するなという注意を添えた。20 秒後にセッションは <shell id=... state="completed"> を受け取り、中には 09:04:07 と 09:04:27 の 2 つの時刻が入っていた。done.txt も書かれていた。
タイムアウトまわりでは、ほかに 2 つ変わった。
- フォアグラウンドの
timeout: 0は以前「終わるまで待つ」だったが、今は既定の 120 秒を意味し、時間が来ればバックグラウンドに移る。 - プロセスデーモンが後始末をするようになった。終わったコマンドが
opencode-ptyの下にゾンビプロセスを残すことはない。成功したコマンドがcmd &で起動したプロセスは残り、失敗したコマンドの残りは止められる。[2]
この既定は正しいと思う。ビルドやテストがタイムアウトで殺されると、モデルはたいてい引数を変えてもう一度走らせ、数分を余計に使う。バックグラウンドに移せば、コマンドは 1 回で走りきり、結果もきちんと届く。
ただし副作用は覚えておきたい。タイムアウトはもう「停止」を意味しない。データベースのマイグレーション、外部へのリクエスト、共有ディレクトリへの書き込みは、以前ならタイムアウトで止まったが、今は最後まで走る。タイムアウトを安全装置として使っていたなら、コマンドに明示的な timeout を入れるか、権限ルールで止める。
バックグラウンド圧縮:要約は必要になる前にできている
圧縮そのものは変わっていない。モデルのコンテキスト上限に近づくと、OpenCode は会話全体を要約し、直近の約 15k トークンはそのまま残して、古い部分と差し替える。[4] 変わったのは、要約をいつ書くかだ。
以前はしきい値に達してから書いていたので、その数秒間は次のプロンプトが待たされた。2.3.1 は既定で、しきい値の 60k トークン手前から裏で要約を書き始める。書き終えた要約はメモリに置いたまま、セッションは普段どおり進む。しきい値に達すると要約に差し替え、要約より後の内容はそのまま残す。[2][4]
図:バックグラウンド圧縮の開始位置とフォールバック条件。しきい値はウィンドウから buffer を引いた値で、buffer の既定はウィンドウの 15%、最低 16k。OpenCode ドキュメントの Compaction ページによる。[4]
ドキュメントには境界条件がはっきり書かれている。[4]
- 要約の後で会話がしきい値の約 40% を超えて伸びた場合や、会話の先頭が変わった場合は、保持していた要約を捨てて通常の圧縮に戻る。
- ウィンドウが小さいモデルでは、開始点は「前回の圧縮後の最初の応答」としきい値の中間より早くならない。
- 要約はメモリにだけあり、再起動で消える。プロバイダー側の native 圧縮ではこの経路を使わない。
- モデルを切り替えた直後や、prompt cache の有効期限を超えて間が空いた後は、次の応答から数え直す。
- 要約のリクエストは prompt cache を再利用するが、使われなかった要約にも課金される。しきい値に届く前にセッションが終われば、そのトークンは無駄になる。
数ターンで圧縮まで届かせるため、テストではプロジェクト設定で mimo-v2.6-flash-free のコンテキストウィンドウを 48000 にした。buffer は最低値の 16k になり、しきい値は約 32k になる。1 ターン目でリリースノートを 1 つ添付し、2 ターン目でさらに 3 ファイルを添付して約 23k まで増やした。40 秒置いて 3 ターン目に約 11k トークンの JSON を添付し、しきい値を越えた。同じ 3 ターンを、"compaction": { "background": false } を加えた別のディレクトリでもう一度流した。どちらもバックグラウンドサービス上で動かした。--standalone だと終了のたびにメモリ上の要約が消えるからだ。

時系列はセッションのデータベースから取り出した。既定の設定では、3 つ目のプロンプトから 0.02 秒後に compaction レコード(reason=auto、status=completed)が現れ、さらに 0.03 秒後にアシスタントが回答を始めた。要約はとっくにできていたということだ。バックグラウンド圧縮を切ると、compaction レコードからアシスタントの開始まで 5.3 秒かかった。この 5.3 秒がその場で要約を書いた時間になる。
コンテキストが長いほど要約には時間がかかり、待たずに済む時間も増える。代わりに要約のリクエストが 1 回余分にかかる。セッションがたいてい短い人や、トークンを細かく管理したい人は、切ってしまってもよい。
CLAUDE.md が再び読まれるようになった
2.3.1 は Claude Code のファイル規約との互換性を戻した。AGENTS.md がなく CLAUDE.md があるディレクトリでは CLAUDE.md を読む。グローバルの ~/.config/opencode/AGENTS.md がなければ ~/.claude/CLAUDE.md にフォールバックする。エージェントが入れ子のディレクトリのファイルを読んだときに見つかる指示にも、同じ規則が当てはまる。OPENCODE_DISABLE_CLAUDE_CODE か OPENCODE_DISABLE_CLAUDE_CODE_PROMPT を設定すると、どの CLAUDE.md も読まなくなる。[2][5]

指示ファイルごとに別の合言葉を入れ、ツールを使わずに指示だけから答えさせた。4 つの回答はどれも規則どおりだった。ただ、回答だけでは証拠として弱い。モデルが自分でファイルを読みにいくこともあるからだ。そこでスクリーンショットの最後のコマンドで、各セッションに実際に注入された指示ファイルをセッション DB から一覧にした。結果は回答と一対一で対応し、環境変数を設定したセッションには指示ファイルが 1 つも入っていなかった。
Claude Code から移ってくるチームにとっては、OpenCode のためだけに AGENTS.md を複製しなくてよくなる。ただし両方があるときに読まれるのは AGENTS.md だけで、2 つは統合されない。
そのほかの変更
- TUI の既定表示が静かになった。 2.3.0 から、ツール呼び出しと思考の連続が 1 行のアクティビティ行にまとまる。各ステップを見たいときは設定で Verbosity を
mediumかhighにするか、TUI の設定でsession.verbosityを指定する。すでに設定していた値はそのまま使われる。[1] - schedules は automations に改名された。 実験的な API は
/api/experimental/automationとclient.experimental.automation.*になり、schedule 系は削除された。[2] - ChatGPT でサインインすると GPT 6.2 Sol と GPT 6.2 Astra と、それぞれの fast 版が使える。[2]
readは小さなファイルでも既定の行数とバイト数でページ分割する。limit: 0はエラーになる。[2]
他の harness は同じ 3 つをどう扱っているか
図:5 つの harness の 3 つの仕組みでの既定動作。緑は既定でバックグラウンドかつ完了を通知、黄は一部だけバックグラウンドかポーリング、灰は待つ、コマンドを終了させる、またはその場で圧縮する。
Claude Code 2.1.327 は OpenCode にいちばん近い。フォアグラウンドの Bash コマンドは既定 2 分でタイムアウトし、そこでバックグラウンドに移る。例外は sleep で始まるコマンドだ。移ったコマンドは、対話セッションなら時間制限がない。-p のような無人セッションでは移った時点から 30 分(テキストのプロンプトを渡す -p では 10 分)が上限になる。[6] メインの会話から起動したサブエージェントは既定でバックグラウンドで動く。結果を待たせたいときは CLAUDE_CODE_FORK_SUBAGENT を 0 にする。[7] いちばん違うのは圧縮だ。ウィンドウを指定しなければ、Claude Code はコンテキスト上限に達してから圧縮する(ネイティブで 1M ウィンドウのモデルでは約 967K)。そのうえで「放置時の圧縮」がある。20 万トークンを超えた会話を 1 時間ほど放っておくと、prompt cache が切れる前に圧縮し、次のメッセージでは要約だけを送る。[8][9] どちらも待ち時間を隠そうとしているが、OpenCode はしきい値の直前を、Claude Code はユーザーが離れている時間を選んだ。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 でこうしたバックグラウンド動作はまとめて止まり、タイムアウトしたコマンドも再び停止されるようになる。[10]
Codex CLI 0.169.1 は別の道をとる。既定で有効な unified exec では、短い待ち時間を過ぎても終わらないコマンドは、セッション ID とそこまでの出力を先に返し、プロセスは動き続ける。モデルはその後 write_stdin で出力を取りにいき、空のポーリングは最長 5 分待つ(background_terminal_max_timeout)。[11] 通知ではなくポーリングの方式だ。サブエージェントは、ユーザーが頼んだときか、プロジェクトや skill の指示が求めたときに spawn される。ドキュメントによれば、複数のエージェントが動いていると Codex はすべての結果がそろうまで待ってからまとめて答える。[12] 自動圧縮は model_auto_compact_token_limit で決まり、未設定ならモデルの既定値になる。[11] テスト機の codex features list では async_compaction と wake_on_agent_messages がどちらも under development でオフになっていて、changelog には「Add a root-only option for background compaction」のような項目がある。[13] Codex もバックグラウンド圧縮とエージェントからの起床を作っている最中で、まだ既定ではオンになっていない。
Gemini CLI 0.68.0 はいちばん保守的だ。コマンドをバックグラウンドで走らせるには、モデルがシェルツールを呼ぶときに is_background: true を付ける必要がある。フォアグラウンドのコマンドは 300 秒出力がないと終了させられる(tools.shell.inactivityTimeout)。[14] サブエージェントは同じ名前のツールとしてメインのエージェントに見え、呼び出しはサブエージェントが報告を返すまで戻らない。[15] 圧縮はコンテキストの 50% で始まり(model.compressionThreshold)、他よりずっと早く、その場で実行される。[16]
Qwen Code 0.28.0 は Gemini CLI からのフォークで、今は半分が Gemini 風、半分が Claude Code 風になっている。シェルは Gemini と同じで、バックグラウンドには明示的な is_background: true が必要、フォアグラウンドのコマンドは既定 120 秒で終了する。この値は tools.shell.defaultTimeoutMs で変えられる。[17][18] サブエージェントは Claude Code と同じで、トップレベルのサブエージェントは既定でバックグラウンドで動き、結果を通知としてメインのセッションに送る。agents.defaultBackground: false でフォアグラウンドに戻せる。[19] 自動圧縮はウィンドウの約 85% を目安にし、小さなウィンドウでは要約の余地を残すためにもっと早く始まる。[18]

並べてみると方向ははっきりしている。サブエージェントを既定でバックグラウンドにするのは、OpenCode、Claude Code、Qwen Code で共通になった。タイムアウトしたコマンドをバックグラウンドに移すのは OpenCode と Claude Code で、Gemini CLI と Qwen Code はまだ終了させる。要約を先に書くのを既定にしているのは OpenCode だけで、Codex はフラグを用意しつつオフのままだ。残る違いは、バックグラウンドの結果がどう戻ってくるかにある。OpenCode、Claude Code、Qwen Code は通知でセッションを起こし、Codex はモデルにポーリングさせる。通知はトークンを節約し、モデルが sleep を繰り返す空回りもなくすが、ターンが終わった後のセッションをランタイムが起こせなければならない。2.3.1 で直った「バックグラウンドのシェルが元のターン終了後に起こしたターンを ACP クライアントが取りこぼす」問題は、まさにこの種類のものだ。[2]
バックグラウンド化で難しくなること
3 つの変更はどれも待ち時間を視界から消す。その一方で、新しい問題も持ち込む。
まずコストが読みにくくなる。並行して動くサブエージェントも、先に書く要約も、直接頼んだわけではないトークン消費だ。従量課金なら 1、2 週間は opencode stats を見ておきたい。自分の数字で計算できるコストモデルは When Claude Haiku 5.5 Actually Saves Money as a Subagent or Compaction Engine(英語) にある。組織でこうした既定値をどう管理するかは Control the Harness, Control the Cost(英語) を参照してほしい。
次に副作用を抑えにくくなる。タイムアウトはもうコマンドを止めず、バックグラウンドのコマンドやサブエージェントは「このターンは終わった」と思った後もファイルを書き換えたりリクエストを送ったりできる。監査では会話の記録だけでなく、バックグラウンドのタスク一覧と出力ファイルも見る必要がある。
最後にデバッグが難しくなる。1 つの回答が、サブエージェントの報告、バックグラウンドのシェルの完了通知、先に書かれた要約という、届いた時刻の違う 3 つの結果に依存することがある。問題が起きたら、まず順序を確かめる。セッション DB の session_message テーブルには各メッセージの種類と時刻が残っていて、本文の時系列もそこから取っている。harness の基本的なループ構造については エージェント・ハーネス・パターン も参考になる。
試したこと、試していないこと
実際に動かしたもの(OpenCode 2.3.1、Linux x64、無料モデル、隔離した XDG_* ディレクトリ):
opencode-ai1.18.31 から@opencode/cli2.3.1 への切り替え。ハッシュは GitHub release と一致。- バックグラウンドのサブエージェント。呼び出しはすぐ戻り、親が先にタイムスタンプを書き、子の報告は 15 秒後に届いた。
- シェルのタイムアウト。タイムアウト 5 秒で 20 秒のコマンドがバックグラウンドに移り、完了時に報告が来た。
- バックグラウンド圧縮。モデルのウィンドウを 48k にして、
compaction.backgroundのオンとオフで待ち時間は 0.03 秒と 5.3 秒。 CLAUDE.mdへのフォールバック。プロジェクト単位、グローバル、AGENTS.mdの優先、環境変数による無効化の 4 通り。- 他の 4 つの harness。Claude Code 2.1.327、Codex CLI 0.169.1、Gemini CLI 0.68.0、Qwen Code 0.28.0 を作業用ディレクトリに入れ、
--help、features list、パッケージ内の既定値を確認した。
試していないもの(ドキュメントとリリースノートに基づく記述):
- TUI の
session.verbosityと折りたたみ表示。テストはopencode runだけで行った。 - フォアグラウンドの
timeout: 0が 120 秒になること。 - 自分でもバックグラウンド処理を持つ子からの「still running」報告と、サブエージェントの権限確認。
- automations の API。
- 他の 4 つの harness での実際のセッション。どれもサインインしていない。
- 無料モデルには利用上限があり、1 回は回答の後に「Free usage limit reached」と表示された。自分のモデルとウィンドウサイズでは要約にかかる時間も変わる。
参考資料
- OpenCode v2.3.0 リリースノート:https://github.com/sst/opencode/releases/tag/v2.3.0(PR #63382、#63675、#63024、#63207) ↩
- OpenCode v2.3.1 リリースノート:https://github.com/sst/opencode/releases/tag/v2.3.1(PR #63699、#64290、#64266、#64026、#64474、#64533、#64343、#64160、#64262) ↩
- OpenCode インストールスクリプト:https://opencode.ai/install(v1)、https://opencode.ai/v2/install(v2)。npm パッケージ @opencode/cli ↩
- OpenCode ドキュメント、Compaction:https://opencode.ai/v2/docs/compaction ↩
- OpenCode ドキュメント、Rules:https://opencode.ai/v2/docs/rules ↩
- Claude Code ドキュメント、Tools reference(タイムアウトとバックグラウンドの時間制限):https://code.claude.com/docs/en/tools-reference ↩
- Claude Code ドキュメント、Subagents:https://code.claude.com/docs/en/sub-agents ↩
- Claude Code ドキュメント、Model configuration(auto-compact ウィンドウ):https://code.claude.com/docs/en/model-config ↩
- Claude Code ドキュメント、Settings reference(
idleCompaction):https://code.claude.com/docs/en/settings-reference ↩ - Claude Code ドキュメント、Environment variables:https://code.claude.com/docs/en/env-vars ↩
- Codex ドキュメント、Configuration reference:https://developers.openai.com/codex/config-reference ↩
- Codex ドキュメント、Subagents:https://developers.openai.com/codex/subagents ↩
- Codex changelog:https://developers.openai.com/codex/changelog ↩
- Gemini CLI ドキュメント、Shell tool:https://geminicli.com/docs/tools/shell/ ↩
- Gemini CLI ドキュメント、Subagents:https://geminicli.com/docs/core/subagents/ ↩
- Gemini CLI ドキュメント、Configuration:https://geminicli.com/docs/reference/configuration/ ↩
- Qwen Code ドキュメント、Shell tool:https://github.com/QwenLM/qwen-code/blob/v0.28.0/docs/developers/tools/shell.md ↩
- Qwen Code ドキュメント、Settings:https://github.com/QwenLM/qwen-code/blob/v0.28.0/docs/users/configuration/settings.md ↩
- Qwen Code ドキュメント、Sub-agents:https://github.com/QwenLM/qwen-code/blob/v0.28.0/docs/users/features/sub-agents.md ↩