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という結果を返し、プロセスごと終了します。同期的に実行するサブエージェントでは発生しません。

この記事が扱うのは、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.2.5まで切り分け、0.1.76は問題なく、0.1.77以降のすべてのバージョンで再現することを確認していました。

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

なぜ非同期(バックグラウンド)のときだけ失敗するのかは、同じ時期に報告された別のissueが具体的に説明しています。Claude Code本体側のissue(#16768)では、バックグラウンドのBashタスクが完了したときに同じエラーで丸ごとCLIが終了する現象が報告されました。報告者がminifyされたソースを確認したコメントによると、バックグラウンドタスクが完了するとmode: "task-notification"というコマンドがストリーミングのキューに積まれます。ところがストリーミング入力モードのハンドラーはmodeが"prompt"か"orphaned-permission"のどちらかであることしか想定していませんでした。それ以外のmodeを受け取ると、only prompt commands are supported in streaming modeを投げてプロセスを止める作りだったのです。

非同期サブエージェントも、完了時に同じtask-notification経路で親セッションへ結果を伝えます。この通知がハンドラーの想定外のコマンドとして扱われ、成功の結果メッセージが届いた直後にエラーで終了していました。同一の不具合が、Agent SDKとClaude Code CLIの両方で起きていたことになります。バックグラウンドサブエージェントが完了・失敗をどう親セッションへ伝えるかという仕組み自体は、CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSとはで扱っているストール検知の通知経路とも重なります。

TypeScript SDK固有の現象で、Python側の報告は見当たらない

issue #130のタイトルと再現コードはTypeScript版の@anthropic-ai/claude-agent-sdkを対象にしています。GitHub検索で同じエラー文字列とPython版パッケージ名(claude_agent_sdk)を組み合わせて調べても、対応する報告は見つかりませんでした。Python版でも同様の構成であれば同じ経路で発生しうるはずですが、内部実装の違いまでは公式に説明されておらず、報告が見つからない理由は分かりません。

error_during_executionの他の原因と区別する

error_during_executionという結果subtypeは、この不具合専用のものではありません。公式ドキュメントは、レート制限のようなAPIエラーでサブエージェントが早期終了した場合も、その結果が正常な形では返されないと説明しています。つまり同じerror_during_executionを見ても、原因はいくつか考えられます。

• errors配列にonly prompt commands are supported in streaming modeという文字列が入っている → 本記事で扱っている、非同期サブエージェントの完了通知がSDK内部のstream-json経路で弾かれるバグが原因
• errors配列に別のエラー文字列が入っている → サブエージェント内のAPI呼び出しなど、別の原因で早期終了している

原因を切り分ける最初の一歩は、errors配列の文言をそのまま確認することです。似た形の結果メッセージでも、エラー文字列が違えば対処法も変わります。

「バックグラウンドが既定」になった今こそ影響範囲を確認する価値がある

このバグが報告された2026年1月には、Agent tool呼び出しでrun_in_backgroundを省略したときにサブエージェントが同期実行されるか非同期実行されるかは、段階的なロールアウトの途中でした。公式ドキュメントによると、Claude Code v2.1.198以降はサブエージェントが既定でバックグラウンド実行になり、run_in_backgroundを省略したAgent tool呼び出しは非同期のバックグラウンドサブエージェントとして起動します。結果を先に必要とするときだけClaudeがrun_in_background: falseを選ぶ形です。

つまり現在の既定動作は、issue #130が再現条件として明示的に指定していた「非同期サブエージェント」の側に寄っています。Agent SDKアプリケーションを組んでいるなら、意識して同期呼び出しを選ばない限りサブエージェントの大半がバックグラウンド経路を通るということです。これは同種の不具合が万一再発したときの影響範囲が、2026年1月の報告当時より広がっていることを意味します。バージョンを更新済みかどうかを確認しておく価値は、既定動作が変わった分だけ上がっていると言えます。

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

issue #130と#16768の両方に、コメント欄でのバージョン言及が残っています。時系列に並べると次のとおりです。

claude-agent-sdk-typescriptのパッケージバージョンとClaude Code本体のバージョンは、Changelogが「Updated to parity with Claude Code v2.1.X」という形で1対1に対応づけています。issue内のコメントが「2.1.7」のようにClaude Code側の番号で語られている場合も、npm側のバージョンはその横に並ぶ0.2.7が該当します。

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

このエラーに当たった場合、まず確認すべきは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相当)へ上げると解決したと報告されています。ただし前述のとおりissue #130には2026年1月25日付けで「2.1.16でもまだ再現する」というコメントも残っており、更新後も同じエラーに当たったら公式の追跡状況を確認してください。

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

依存関係のロックファイルが古いバージョンを固定したまま更新されていないケースは見落としやすいポイントです。npm lsの表示だけでなくロックファイル(package-lock.json等)も合わせて確認してから上げ直してください。バージョンをすぐに上げられない事情がある場合は、プロンプトで同期実行を指示するなど、サブエージェントを同期で動かせば再現コード上は発生しません。TypeScript SDK全体の基本的な組み方はClaudeのTypeScript SDKで実装するStreaming・Tool・MCPヘルパーで扱っています。

よくあるつまずき

• 結果メッセージが2件届く前提でコードを書いていないと、1件目の成功結果だけ見て後続処理を進めてしまい、2件目のエラーに気づかない
• only prompt commands are supported in streaming modeというエラー文だけを見て、プロンプトの書き方が悪いと誤解する。実際はサブエージェントが非同期(バックグラウンド)実行されたとき、その完了通知がSDK内部のstream-json経路で弾かれることに起因する
• Claude Code CLIを直接--input-format stream-jsonで使っている場合も、バックグラウンドタスクが完了すると同じonly prompt commands are supported in streaming modeで落ちることがある(issue #16768)。SDK側のバージョンだけでなくClaude Code CLI本体のバージョンも合わせて確認する
• 同じエラー文字列は、--model haiku指定時の実行中(mid-execution)の追加入力が原因で出ることもある(issue #17406)。こちらはバックグラウンドタスクとは無関係の別現象で、原因を一括りにしない

まとめ

only prompt commands are supported in streaming modeは、Agent SDK内部のストリーミング経路が原因のバグです。バックグラウンドタスクの完了通知(task-notification)を、prompt・orphaned-permission以外の想定外コマンドとして拒否していました。非同期サブエージェントはこの経路で完了を通知するため影響を受けました。@anthropic-ai/claude-agent-sdk 0.2.7(Claude Code v2.1.7相当)以降では解決済みと報告されていますが、issue内には2.1.16でも再現したというコメントも残っており、依存関係が古いバージョンに固定されたままのプロジェクトも含め今も再現する可能性があります。バージョンを確認し、固定されている場合はまず更新してから原因調査に進むのが近道です。