> [!left-bubble] ![[claudine-mini.webp]]
> [[Claude Code]]がまとめたレポートです。
## 概要
[[GitHub Copilot CLI]]のデバッグログを解析し、エージェントのhookライフサイクル（userPromptSubmitted → [[sessionStart (GitHub Copilot)|sessionStart]] → preToolUse/postToolUse → [[agentStop (GitHub Copilot)|agentStop]] → [[sessionEnd (GitHub Copilot)|sessionEnd]]）を[[Mermaid|mermaid]]図として可視化する。また、公式ドキュメントを調査し「セッション」の定義を明確にする。
## 計画
- [x] デバッグログからhookイベントの発火順序を解析
- [x] [[Mermaid|mermaid]]のシーケンス図を作成
- [x] [[Markdown|markdown]]貼り付け用のコードブロック形式で出力
- [x] 「セッション」の定義を公式ドキュメント(CLI/SDK)から調査
- [x] sessionStart/sessionEndの挙動がper-promptである事実と、バグ報告(copilot-cli#991)の存在を確認
- [x] 調査結果を総括にまとめる
## 総括
### 対応内容
- デバッグログ (`process-1774566141399-51111.log`) を解析し、[[GitHub Copilot CLI]]のhookライフサイクルの発火順序を特定
- [[Mermaid|mermaid]]シーケンス図を作成し、[[Markdown|markdown]]貼り付け可能な形式で提供
- 公式ドキュメント（CLI/SDK両方）を調査し「セッション」の定義と`sessionStart`の`source`フィールドを確認
- `sessionStart`/`sessionEnd`のper-prompt発火がバグとして報告されている事実を発見
### 対応による恩恵
- [[GitHub Copilot CLI]]のhookイベントの発火タイミングが視覚的に把握できるようになった
- 「セッション」の定義が曖昧であること、および現在の挙動（per-prompt）がドキュメントの記述と異なる可能性があることが明確になった
### 詳細
#### hookイベント発火順序（1ターンあたり）
| 順序 | イベント | タイミング |
| --- | --------------------- | ------------------- |
| 1 | `userPromptSubmitted` | ユーザーがプロンプトを送信した直後 |
| 2 | `sessionStart` | エージェントセッション開始時 |
| 3 | `preToolUse` | 各ツール実行の直前（ツールごとに発火） |
| 4 | `postToolUse` | 各ツール実行の直後（ツールごとに発火） |
| 5 | `agentStop` | エージェントの応答完了時 |
| 6 | `sessionEnd` | セッション終了時 |
#### mermaid図
```mermaid
sequenceDiagram
participant User as ユーザー
participant CLI as Copilot CLI
participant Hook as Hook
participant Agent as エージェント(LLM)
participant Tool as ツール
Note over CLI: CLI起動・初期化
CLI->>CLI: プラグインからHook読み込み
CLI->>CLI: セッション登録 (session.foreground)
CLI->>CLI: MCP/ツール初期化
rect rgb(230, 245, 255)
Note over User,Tool: ターン (ユーザーの入力ごとに繰り返し)
User->>CLI: プロンプト入力
CLI->>Hook: 👇 userPromptSubmitted
CLI->>Hook: ✨ sessionStart
CLI->>Agent: プロンプト送信
loop エージェントがツールを使う間
Agent->>CLI: ツール呼び出し要求
CLI->>Hook: 🫷 preToolUse
CLI->>Tool: ツール実行
Tool-->>CLI: 実行結果
CLI->>Hook: 🫸 postToolUse
CLI-->>Agent: ツール結果返却
end
Agent-->>CLI: 最終応答
CLI->>Hook: ⛔ agentStop
CLI->>Hook: ✋ sessionEnd
CLI-->>User: 応答表示
end
```
#### セッションの定義について
CLIレベルとhookレベルで2つの「セッション」概念が存在する:
| 概念 | スコープ | ログ上の表現 |
|------|---------|-------------|
| CLIセッション | `copilot`コマンド起動〜終了 | `session.foreground` (ID付き、1回だけ登録) |
| エージェントセッション (hook対象) | 1プロンプト→エージェント応答完了 | `sessionStart`〜`sessionEnd` (ターンごとに繰り返し) |
公式ドキュメント上の `sessionStart` hook inputには `source` フィールド (`"new"` / `"resume"` / `"startup"`) があるが、「セッション」自体の明確な定義は記載されていない。
### 備考・注意事項
- `sessionStart`/`sessionEnd`がインタラクティブモードでプロンプトごとに発火する挙動は、github/copilot-cli#991 でバグとして報告されている（未解決）。ドキュメント上はセッション開始/終了時に1回発火する想定だが、実装はper-promptになっている
- 今後の仕様変更で挙動が変わる可能性がある
### 参考リンク
- [Hooks configuration - GitHub Copilot](https://docs.github.com/en/copilot/reference/hooks-configuration)
- [Using hooks with GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)
- [github/copilot-cli#991 - sessionStart/sessionEnd per-prompt issue](https://github.com/github/copilot-cli/issues/991)
- [Copilot SDK - Session Hooks](https://github.com/github/copilot-sdk/blob/main/nodejs/README.md)
## 作業メモ
- ログファイル: `/tmp/copilot-log/process-1774566141399-51111.log` (約67000トークン)
- hookイベントは `Executing hook:` / `[hook stdout]` で検索可能
- ユーザーフックとプラグインフック(notify.sh)が同一イベントで並行実行されている