Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

ヘッドレスの--output-format stream-jsonで、依存関係が満たされないためにプラグインが降格された場合、initイベントにplugin_errorsが含まれるようになりました。

原文（英語） ​

Headless --output-format stream-json now includes plugin_errors on the init event when plugins are demoted for unsatisfied dependencies.

概要 ​

Claude Code v2.1.111では、ヘッドレスモードで--output-format stream-jsonを使用した際、プラグインの依存関係が満たされない場合にinitイベントのplugin_errorsフィールドにエラー情報が含まれるようになりました。これにより、CI/CDパイプラインやスクリプトからClaude Codeを呼び出す際に、プラグインの問題を自動的に検出・処理できるようになります。

基本的な使い方 ​

stream-jsonでのヘッドレス実行 ​

bash
# stream-json形式で出力
claude --output-format stream-json --print "タスクを実行してください"

initイベントの構造（plugin_errorsあり） ​

json
{
  "type": "init",
  "session_id": "sess_xxx",
  "model": "claude-opus-4-7",
  "plugins": ["plugin-a", "plugin-b"],
  "plugin_errors": [
    {
      "plugin": "plugin-c",
      "error": "unsatisfied_dependency",
      "reason": "requires plugin-d >= 2.0.0, but 1.5.0 is installed",
      "demoted": true
    }
  ]
}

initイベントの構造（plugin_errorsなし） ​

json
{
  "type": "init",
  "session_id": "sess_xxx",
  "model": "claude-opus-4-7",
  "plugins": ["plugin-a", "plugin-b"],
  "plugin_errors": []
}

実践例 ​

CI/CDパイプラインでのプラグインエラー検出 ​

bash
#!/bin/bash
# CI/CDでClaude Codeを実行してプラグインエラーをチェック

OUTPUT=$(claude --output-format stream-json --print "ビルドを確認してください" 2>&1)

# initイベントを抽出してplugin_errorsを確認
INIT_EVENT=$(echo "$OUTPUT" | head -1 | jq '.')
PLUGIN_ERRORS=$(echo "$INIT_EVENT" | jq '.plugin_errors // []')

if [ "$(echo "$PLUGIN_ERRORS" | jq 'length')" -gt "0" ]; then
  echo "警告: プラグインエラーが検出されました"
  echo "$PLUGIN_ERRORS" | jq '.'
  # エラーレポートを生成
fi

Pythonスクリプトでのプラグインエラーハンドリング ​

python
import subprocess
import json

def run_claude_with_plugin_check(prompt: str) -> dict:
    """Claude Codeを実行してplugin_errorsを確認する"""
    result = subprocess.run(
        ["claude", "--output-format", "stream-json", "--print", prompt],
        capture_output=True,
        text=True
    )
    
    lines = result.stdout.strip().split('\n')
    events = []
    
    for line in lines:
        try:
            event = json.loads(line)
            events.append(event)
        except json.JSONDecodeError:
            continue
    
    # initイベントを取得
    init_event = next((e for e in events if e.get('type') == 'init'), None)
    
    if init_event:
        plugin_errors = init_event.get('plugin_errors', [])
        if plugin_errors:
            print(f"プラグインエラー: {len(plugin_errors)}件")
            for error in plugin_errors:
                print(f"  - {error['plugin']}: {error['reason']}")
    
    return events

# 使用例
events = run_claude_with_plugin_check("コードをレビューしてください")

jqを使ったstream-jsonの解析 ​

bash
# stream-jsonをストリームで処理してinitイベントのみを抽出
claude --output-format stream-json --print "分析してください" | \
  while IFS= read -r line; do
    TYPE=$(echo "$line" | jq -r '.type // ""')
    if [ "$TYPE" = "init" ]; then
      echo "=== initイベント ==="
      echo "$line" | jq '.plugin_errors'
    fi
  done

プラグインエラーに応じた処理分岐 ​

bash
#!/bin/bash
# プラグインエラーの種類に応じて処理を変える

OUTPUT=$(claude --output-format stream-json --print "実行してください" | head -1)
ERROR_COUNT=$(echo "$OUTPUT" | jq '.plugin_errors | length')

if [ "$ERROR_COUNT" -gt "0" ]; then
  ERROR_TYPE=$(echo "$OUTPUT" | jq -r '.plugin_errors[0].error')
  
  case "$ERROR_TYPE" in
    "unsatisfied_dependency")
      echo "依存関係エラー: プラグインを更新してください"
      claude --print "/plugins update"
      ;;
    "conflicting_versions")
      echo "バージョン競合: 手動解決が必要です"
      ;;
    *)
      echo "不明なエラー: $ERROR_TYPE"
      ;;
  esac
fi

注意点 ​

  • plugin_errorsはプラグインが**降格（demoted）**された場合のみ含まれます。プラグインが完全に読み込めない場合とは異なります
  • plugin_errorsフィールドは配列として常に存在しますが、エラーがない場合は空の配列[]になります
  • initイベントはstream-json出力の最初のイベントとして送信されます
  • 依存関係エラーの種類（conflicting、invalid、overly complex）はv2.1.111でより詳細に分類されるようになりました
  • このフィールドはヘッドレスモード（--output-format stream-json）専用です。TUIモードでは関係ありません

関連情報 ​