Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

フック設定エラーを改善しました。SessionStart・Setup・SubagentStart イベントに対して prompt 型または agent 型のフックを設定した場合、「代わりにコマンド型フックを使用してください」という明確なエラーメッセージが表示されるようになりました。

原文（英語） ​

Improved hook configuration error: configuring a prompt- or agent-type hook for SessionStart/Setup/SubagentStart now shows a clear "use a command-type hook instead" error.

概要 ​

Claude Code のフック機能では、ライフサイクルイベントの種類によって使用できるフックの型が異なります。SessionStart・Setup・SubagentStart イベントは、シェルコマンドを実行する command 型と MCP ツールを呼び出す mcp_tool 型のフックのみをサポートしており、prompt 型や agent 型は使用できません。これまでは誤ったフック型を設定した場合のエラーメッセージが不明瞭でした。今回の改善により「コマンド型フックを代わりに使用してください」という分かりやすいエラーメッセージが表示され、設定ミスをすぐに修正できるようになりました。

基本的な使い方 ​

フックは .claude/settings.json で設定します。SessionStart・Setup・SubagentStart イベントには command 型または mcp_tool 型のフックを使用してください。

json
// .claude/settings.json（正しい設定例）
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/on-session-start.sh"
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/on-subagent-start.sh"
          }
        ]
      }
    ]
  }
}
json
// NG：SessionStart に prompt 型や agent 型を設定するとエラーになる
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",  // ← エラー：SessionStart には使用不可
            "prompt": "セッション開始時に何かしてください"
          }
        ]
      }
    ]
  }
}
// → エラー: "use a command-type hook instead"

実践例 ​

SessionStart フックでプロジェクト情報を注入する ​

セッション開始時に Git のブランチ情報や最近のコミット履歴を Claude に渡す例です。

bash
# .claude/hooks/on-session-start.sh
#!/bin/bash
echo "=== プロジェクト状態 ==="
echo "ブランチ: $(git branch --show-current)"
echo "最新コミット:"
git log --oneline -5
echo "未コミットの変更:"
git status --short
json
// .claude/settings.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/on-session-start.sh"
          }
        ]
      }
    ]
  }
}

Setup フックで環境変数を設定する ​

プロジェクト固有の環境変数をセッション全体に適用する例です。

bash
# .claude/hooks/setup.sh
#!/bin/bash
# CLAUDE_ENV_FILE を使って環境変数を永続化する
cat <<EOF > "$CLAUDE_ENV_FILE"
PROJECT_ENV=development
DATABASE_URL=postgresql://localhost:5432/mydb
API_BASE_URL=http://localhost:3000
EOF
echo "環境変数を設定しました"
json
// .claude/settings.json
{
  "hooks": {
    "Setup": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup.sh"
          }
        ]
      }
    ]
  }
}

SubagentStart フックでサブエージェントを初期化する ​

サブエージェント（Task ツールで生成されるエージェント）が起動したとき、エージェントの種類に応じて初期化処理を行う例です。

bash
# .claude/hooks/on-subagent-start.sh
#!/bin/bash
# 標準入力から JSON を読み取りエージェント種別を確認
INPUT=$(cat)
AGENT_TYPE=$(echo "$INPUT" | jq -r '.agent_type // "unknown"')

echo "=== サブエージェント起動: $AGENT_TYPE ==="
case "$AGENT_TYPE" in
  "Bash")
    echo "作業ディレクトリ: $(pwd)"
    echo "利用可能なツール: git, npm, python3"
    ;;
  "Explore")
    echo "コードベース概要:"
    find . -name "*.ts" | head -10
    ;;
  *)
    echo "汎用エージェントとして起動しました"
    ;;
esac
json
// .claude/settings.json
{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/on-subagent-start.sh"
          }
        ]
      }
    ]
  }
}

セマンティックな判断が必要な場合の代替手段 ​

SessionStart に prompt 型フックを使いたい場面（例：開始メッセージを AI に解析させたい）では、command 型フック内でサブプロセスとして実行する方法が使えます。

bash
# .claude/hooks/smart-session-start.sh
#!/bin/bash
# command 型フック内で別の処理を呼び出す
INPUT=$(cat)

# 必要に応じて Anthropic API を直接呼び出す
# または jq などで入力を解析してロジックを実装する
SESSION_SOURCE=$(echo "$INPUT" | jq -r '.source // "unknown"')

if [ "$SESSION_SOURCE" = "resume" ]; then
  echo "=== セッション再開 ==="
  echo "前回の作業を引き継ぎます"
  cat .claude/last-session-notes.md 2>/dev/null || true
else
  echo "=== 新規セッション開始 ==="
  echo "プロジェクト: $(basename $(pwd))"
fi

注意点 ​

  • 対応フック型：SessionStart・Setup・SubagentStart では command 型と mcp_tool 型のみ使用可能です。prompt 型・agent 型・http 型は使用できません。
  • エラーメッセージ：誤った型を設定すると "use a command-type hook instead" というエラーが表示されます。設定ファイルの type フィールドを確認してください。
  • 他のイベントとの違い：PreToolUse・PostToolUse などの他のイベントでは prompt 型・agent 型も使用できます。制限は SessionStart・Setup・SubagentStart のみです。
  • stdout の扱い：SessionStart・SubagentStart フックの標準出力はそのまま Claude のコンテキストとして注入されます。有用な情報のみを出力するよう設計してください。
  • CLAUDE_ENV_FILE：Setup フックでは $CLAUDE_ENV_FILE 環境変数が利用可能で、セッション全体に永続化する環境変数を書き込めます。
  • 終了コード：フックが終了コード 2 で終了するとブロッキングエラーとなり、セッションの開始を妨げることがあります。通常は終了コード 0 を使用してください。

関連情報 ​