only prompt commands are supported in streaming modeエラーの原因

only prompt commands are supported in streaming modeとは何のエラーか

only prompt commands are supported in streaming modeは、Claude Agent SDKのストリーミング入力モードで特定の内部イベントを受け付けられなかったときに出るエラー文字列です。TypeScript SDKで非同期(バックグラウンド)のサブエージェントを動かすと、その完了通知がSDK内部のstream-json経路で弾かれて発生しました。セッションはerror_during_executionという結果を返し、プロセスは終了コード1で終わります。同期的に実行するサブエージェントでは発生しません。

この記事が扱うのは、2026年1月にclaude-agent-sdk-typescriptリポジトリのissue(#130)で報告された非同期サブエージェント固有のバグです。ストリーミング入力とシングルメッセージ入力の一般的な使い分けはAgent SDKストリーミング入力とシングルメッセージ入力の使い分けにまとめています。

再現コードで見る「同期は通り、非同期だけ失敗する」現象

issue #130の報告者が添えた再現コードは、同じdog-namerサブエージェントを同期・非同期の2パターンで呼び出し、結果メッセージの件数を数えるだけの短いスクリプトでした。

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function testSubagent(mode: "synchronous" | "asynchronous") {
  const response = query({
    prompt: `as a test, spawn one ${mode} subagent. it should be tasked with thinking of a name for a very good dog. then you should tell me the name`,
    options: {
      allowedTools: ["Task"],
      agents: {
        "dog-namer": {
          description: "Use this agent to think of creative names for dogs",
          prompt: "Think of a name for a dog.",
          tools: [],
        },
      },
    },
  });
 
  let resultCount = 0;
  for await (const message of response) {
    if (message.type === "result") {
      resultCount++;
    }
  }
  console.log(`Received ${resultCount} result message(s)`);
}

modeにsynchronousを渡すと結果メッセージは1件で終わります。asynchronousを渡すと、成功の結果メッセージに続けてもう1件error_during_executionが届き、errors配列にonly prompt commands are supported in streaming modeが入ります。報告者はSDKの0.1.76・0.1.77・0.2.0・0.2.5を試し、0.1.76は問題なく、0.1.77・0.2.0・0.2.5で再現したと書いています。

2件目の結果メッセージは、中身の数字がすべて空です。issue #130の2026年1月25日付けコメントに貼られた実物は、次のような形でした(長いusageの内訳は省略)。

{"type":"result","subtype":"error_during_execution","duration_ms":0,
 "duration_api_ms":0,"is_error":true,"num_turns":0,"total_cost_usd":0,
 "errors":["only prompt commands are supported in streaming mode"]}

所要時間・ターン数・費用がすべて0で、モデルを呼ばずに終わった結果に見えます。1件目の成功結果が正常に値を持っている点とも対照的です。ただしゼロ値だけでは決め手にならず、判別はerrorsの文言で行います。

原因はバックグラウンドタスクの完了通知がstreaming modeのキューで弾かれること

なぜ非同期(バックグラウンド)のときだけ失敗するのかは、同じ時期に報告された別のissueが具体的に説明しています。Claude Code本体側のissue(#16768、2026年1月8日起票)では、バックグラウンドのBashタスクが完了したときに同じエラーでCLIが終了する現象が報告されました。2026年1月9日付けのコメントで、報告者がminifyされたソースを調べた結果が共有されています。

#130も#16768と同じ2.1.7で修正されているため、非同期サブエージェントの完了通知も同じtask-notification経路で弾かれていたと読めます。同じ不具合が、Agent SDKとClaude Code CLIの両方に現れていたことになります。完了・失敗を親セッションへ伝える仕組みは、CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSとはで扱っているストール検知の通知経路とも重なります。

#130はTypeScript SDKの報告で、Python版で同じ症状が出たという記述はない

issue #130のタイトルと再現コードはTypeScript版の@anthropic-ai/claude-agent-sdkを対象にしています。#130と#16768のどちらにも、Python版(claude_agent_sdk)で同じ症状が出たという記述はありません。TypeScript SDK固有の不具合はほかにもあり、thinkingブロックの前に空のテキストが混入する(no content)不具合も報告されています。

同じ文字列でも原因が別のもの、見た目が似た別のエラー

このエラー文字列を含む報告には、バックグラウンドタスクと無関係なものがあります。issue #17406は、--model haikuで起動したClaude Codeに実行中の追加入力を送ると、終了コード1とこの文字列で落ちるという報告です。報告者は約50回の試行で、haikuでは毎回、opusでは1回だけ発生したと書いています。このissueは修正の報告がないまま、2026年3月に長期間動きがないことを理由にクローズされました。コメントには、--input-formatをtextにしても同じエラーが出るという声も残っています。

一方、サブエージェントがAPIエラーで早期終了するケースは、まったく別の経路です。公式ドキュメントは、レート制限のようなAPIエラーでサブエージェントが終わったとき、その結果が親へどう戻るかを実行形態ごとに説明しています。

切り分けの決め手はerrors配列の文言です。今回の文字列が入っていれば本記事の不具合で、数字が0なのは補助的な手がかりにとどまります。起動失敗の結果も0を返すためです。サブエージェントの失敗なら、親へ戻るメッセージ側にAPIエラーの名前が出ます。

サブエージェントの既定がバックグラウンドになった経緯

公式ドキュメントによると、Claude Code v2.1.198より前は、バックグラウンド実行を既定にする切り替えが段階的に進んでいる途中で、run_in_backgroundを省略した呼び出しが同期実行になることもありました。v2.1.198以降はサブエージェントが既定でバックグラウンド実行になります。run_in_backgroundを省略したAgent tool呼び出しは、非同期のバックグラウンドサブエージェントとして起動します。結果を先に必要とするときだけClaudeがrun_in_background: falseを選ぶ形です。

エージェント定義側のbackgroundフィールドをtrueにすると、Claudeの指定にかかわらず常にバックグラウンドで動かせます。同期か非同期かを意識して選ぶ場合の分かれ目は、この2つの指定です。

いつのバージョンで直ったか

issue #130と#16768のコメントを日付順に並べると、次のとおりです。

@anthropic-ai/claude-agent-sdkのCHANGELOGは、0.2系で「Updated to parity with Claude Code v2.1.X」という形で、npm側の0.2.Xと本体の2.1.Xを1対1で対応づけています。issue内のコメントが「2.1.7」のようにClaude Code側の番号で語られていても、npm側は0.2.7が該当します。0.2.6では、この対応を機械的に調べられるclaudeCodeVersionフィールドがpackage.jsonに追加されました。

手元で当たった場合の対処

このエラーに当たった場合、まず確認するのはpackage.jsonに固定されている@anthropic-ai/claude-agent-sdkのバージョンです。

npm ls @anthropic-ai/claude-agent-sdk

0.1.77から0.2.6までのレンジに固定されている場合は、0.2.7以降(Claude Code v2.1.7相当)へ上げると解決したと報告されています。更新先のバージョンと、それが対応するClaude Codeのバージョンはnpm viewで読めます。v2.1.289のClaude Codeを入れた環境でこの2項目を引くと、次のように出ました。

npm view @anthropic-ai/claude-agent-sdk version claudeCodeVersion

version = '0.3.289'
claudeCodeVersion = '2.1.289'

0.3系でも、SDKのバージョン末尾とClaude Codeのバージョンは揃っています。更新後も同じエラーに当たる場合は、前掲の時系列にある1月25日の報告と同じ状況の可能性があります。

npm install @anthropic-ai/claude-agent-sdk@latest

依存関係のロックファイルが古いバージョンを固定したまま更新されていないケースは見落としやすいポイントです。npm lsの表示だけでなくロックファイル(package-lock.json等)も合わせて確認してから上げ直すと確実です。

バージョンをすぐに上げられない事情がある場合の回避策は2つあります。1つは、プロンプトで同期実行を指示することです。再現コードでは、同期を指示したときは発生していません。もう1つは、成功結果を受け取ったあとに届くerror_during_executionを、文言で見分けて無視する書き方です。

let succeeded = false;
for await (const message of response) {
  if (message.type !== "result") continue;
  if (message.subtype === "success") {
    succeeded = true;
  } else if (
    succeeded &&
    message.subtype === "error_during_execution" &&
    message.errors?.some((e) => e.includes("only prompt commands are supported"))
  ) {
    continue; // 成功のあとに続く、完了通知起因の誤報
  }
}

この書き方は、再現コードで観察された「成功の1件に続いてエラーが1件届く」並びだけを前提にしています。成功結果が先に来ていないエラーまで握りつぶさないよう、succeededを条件に入れています。TypeScript SDK全体の基本的な組み方はClaudeのTypeScript SDKで実装するStreaming・Tool・MCPヘルパーで扱っています。

Claude Code CLIを直接stream-jsonで使っている場合

SDKを介さず、CLIを--input-format stream-jsonで直接起動している場合も、バックグラウンドタスクの完了で同じエラーに当たったのがissue #16768です。--input-formatは--print(-p)と組み合わせたときだけ有効で、v2.1.289のclaude --helpは次のように説明しています。

claude --help | grep -A3 -- "--input-format"

  --input-format <format>               Input format (only works with --print):
                                        "text" (default), or "stream-json"
                                        (realtime streaming input) (choices:
                                        "text", "stream-json")

SDK側のバージョンだけでなく、Claude Code CLI本体のバージョンも合わせて確認します。#16768のコメントでは、2.1.2で再現し、2.1.7で修正されたと報告されています。

よくあるつまずき

• 結果メッセージが2件届く前提でコードを書いていないと、1件目の成功結果だけ見て後続処理を進めてしまい、2件目のエラーに気づかない
• only prompt commands are supported in streaming modeというエラー文だけを見て、プロンプトの書き方が悪いと誤解する。実際は、非同期(バックグラウンド)実行の完了通知がstream-json経路で弾かれることに起因すると読める
• issue #17406のhaikuの事例まで同じ原因と見なす。こちらはバックグラウンドタスクとは無関係で、修正の報告もないまま終わっている

まとめ

SDKは0.2.7以降、CLIは2.1.7以降へ上げるのが基本の対処です。上げても成功のあとに同じ文字列が届く場合は、前掲の回避コードで成功後の誤報だけを除外しておけば、後続処理は止まりません。