{"meta":{"title":"セッション フック","intro":"フックを使用すると、会話ライフサイクルの重要なポイントでCopilotセッションの動作をインターセプトしてカスタマイズできます。 フックを使用して以下を行います。","product":"GitHub Copilot","breadcrumbs":[{"href":"/ja/copilot","title":"GitHub Copilot"},{"href":"/ja/copilot/how-tos","title":"方法"},{"href":"/ja/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/ja/copilot/how-tos/copilot-sdk/hooks","title":"フックを使用する"},{"href":"/ja/copilot/how-tos/copilot-sdk/hooks/hooks-overview","title":"フックの概要"}],"documentType":"article"},"body":"# セッション フック\n\nフックを使用すると、会話ライフサイクルの重要なポイントでCopilotセッションの動作をインターセプトしてカスタマイズできます。 フックを使用して以下を行います。\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n* **ツールの実行を制御** する - ツール呼び出しの承認、拒否、または変更\n* **変換結果** - 処理前にツールの出力を変更する\n* **コンテキストの追加** - セッション開始時に追加情報を挿入する\n* **エラーの処理** - カスタム エラー処理を実装する\n* **監査とログ** - コンプライアンスのすべての対話を追跡する\n\n## 使用可能なフック\n\n| フック                                                                                      | Trigger              | ユースケース(事例)                |\n| ---------------------------------------------------------------------------------------- | -------------------- | ------------------------- |\n| [ツール使用前のフック](/ja/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)                         | ツールの実行前              | アクセス許可の制御、引数の検証           |\n| [ツール使用後フック](/ja/copilot/how-tos/copilot-sdk/hooks/post-tool-use)                         | ツールの実行後 (成功のみ)       | 結果変換、ログ記録                 |\n| [ツール使用後フック](/ja/copilot/how-tos/copilot-sdk/hooks/post-tool-use#failure-variant)         | 結果が失敗したツールの実行後       | 再試行のガイダンスを挿入し、エラーをログに記録する |\n| [ユーザー プロンプト送信後フック](/ja/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)          | ユーザーがメッセージを送信する場合    | プロンプトの変更、フィルター処理          |\n| [ユーザープロンプト変換用フック](/ja/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed)         | ランタイムでのプロンプト変換後      | モデル向けのコンテンツを検査または置換する     |\n| [セッションライフサイクルフック](/ja/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start) | セッションの開始             | コンテキストの追加、セッションの構成        |\n| [セッションライフサイクルフック](/ja/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end)   | セッションの終了             | クリーンアップ、分析                |\n| [エラー処理フック](/ja/copilot/how-tos/copilot-sdk/hooks/error-handling)                         | エラーが発生する             | カスタム エラー処理                |\n| [セッションライフサイクルフック](/ja/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#agent-stop)    | 最上位のエージェントは自然に停止します。 | 完了を検証するか、別のターンを要求する       |\n\n## 簡単スタート\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\n\nconst session = await client.createSession({\n  hooks: {\n    onPreToolUse: async (input) => {\n      console.log(`Tool called: ${input.toolName}`);\n      // Allow all tools\n      return { permissionDecision: \"allow\" };\n    },\n    onPostToolUse: async (input) => {\n      console.log(`Tool result: ${JSON.stringify(input.toolResult)}`);\n      return null; // No modifications\n    },\n    onSessionStart: async (input) => {\n      return { additionalContext: \"User prefers concise answers.\" };\n    },\n  },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient\nfrom copilot.session import PermissionHandler\n\nasync def main():\n    client = CopilotClient()\n    await client.start()\n\n    async def on_pre_tool_use(input_data, invocation):\n        print(f\"Tool called: {input_data['toolName']}\")\n        return {\"permissionDecision\": \"allow\"}\n\n    async def on_post_tool_use(input_data, invocation):\n        print(f\"Tool result: {input_data['toolResult']}\")\n        return None\n\n    async def on_session_start(input_data, invocation):\n        return {\"additionalContext\": \"User prefers concise answers.\"}\n\n    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={\n            \"on_pre_tool_use\": on_pre_tool_use,\n            \"on_post_tool_use\": on_post_tool_use,\n            \"on_session_start\": on_session_start,\n        })\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    copilot \"github.com/github/copilot-sdk/go\"\n)\n\nfunc main() {\n    client := copilot.NewClient(nil)\n\n    session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{\n        Hooks: &copilot.SessionHooks{\n            OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {\n                fmt.Printf(\"Tool called: %s\\n\", input.ToolName)\n                return &copilot.PreToolUseHookOutput{\n                    PermissionDecision: \"allow\",\n                }, nil\n            },\n            OnPostToolUse: func(input copilot.PostToolUseHookInput, inv copilot.HookInvocation) (*copilot.PostToolUseHookOutput, error) {\n                fmt.Printf(\"Tool result: %v\\n\", input.ToolResult)\n                return nil, nil\n            },\n            OnSessionStart: func(input copilot.SessionStartHookInput, inv copilot.HookInvocation) (*copilot.SessionStartHookOutput, error) {\n                return &copilot.SessionStartHookOutput{\n                    AdditionalContext: \"User prefers concise answers.\",\n                }, nil\n            },\n        },\n    })\n    _ = session\n}\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nusing GitHub.Copilot;\n\nvar client = new CopilotClient();\n\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n    Hooks = new SessionHooks\n    {\n        OnPreToolUse = (input, invocation) =>\n        {\n            Console.WriteLine($\"Tool called: {input.ToolName}\");\n            return Task.FromResult<PreToolUseHookOutput?>(\n                new PreToolUseHookOutput { PermissionDecision = \"allow\" }\n            );\n        },\n        OnPostToolUse = (input, invocation) =>\n        {\n            Console.WriteLine($\"Tool result: {input.ToolResult}\");\n            return Task.FromResult<PostToolUseHookOutput?>(null);\n        },\n        OnSessionStart = (input, invocation) =>\n        {\n            return Task.FromResult<SessionStartHookOutput?>(\n                new SessionStartHookOutput { AdditionalContext = \"User prefers concise answers.\" }\n            );\n        },\n    },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.*;\nimport com.github.copilot.rpc.*;\nimport java.util.concurrent.CompletableFuture;\n\ntry (var client = new CopilotClient()) {\n    client.start().get();\n\n    var hooks = new SessionHooks()\n        .setOnPreToolUse((input, invocation) -> {\n            System.out.println(\"Tool called: \" + input.getToolName());\n            return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());\n        })\n        .setOnPostToolUse((input, invocation) -> {\n            System.out.println(\"Tool result: \" + input.getToolResult());\n            return CompletableFuture.completedFuture(null);\n        })\n        .setOnSessionStart((input, invocation) -> {\n            return CompletableFuture.completedFuture(\n                new SessionStartHookOutput(\"User prefers concise answers.\", null)\n            );\n        });\n\n    var session = client.createSession(\n        new SessionConfig()\n            .setHooks(hooks)\n            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n}\n```\n\n</div>\n\n</div>\n\n## フック呼び出しコンテキスト\n\nすべてのフックは、現在のセッションに関するコンテキストを持つ `invocation` パラメーターを受け取ります。\n\n| フィールド       | タイプ | Description  |\n| ----------- | --- | ------------ |\n| `sessionId` | 文字列 | 現在のセッションの ID |\n\nこれにより、フックで状態を維持したり、セッション固有のロジックを実行したりできます。\n\n## 一般的なパターン\n\n### すべてのツール呼び出しのログ記録\n\n```typescript\nconst session = await client.createSession({\n  hooks: {\n    onPreToolUse: async (input) => {\n      console.log(`[${new Date().toISOString()}] Tool: ${input.toolName}, Args: ${JSON.stringify(input.toolArgs)}`);\n      return { permissionDecision: \"allow\" };\n    },\n    onPostToolUse: async (input) => {\n      console.log(`[${new Date().toISOString()}] Result: ${JSON.stringify(input.toolResult)}`);\n      return null;\n    },\n  },\n});\n```\n\n### 危険なツールのブロック\n\n```typescript\nconst BLOCKED_TOOLS = [\"shell\", \"bash\", \"exec\"];\n\nconst session = await client.createSession({\n  hooks: {\n    onPreToolUse: async (input) => {\n      if (BLOCKED_TOOLS.includes(input.toolName)) {\n        return {\n          permissionDecision: \"deny\",\n          permissionDecisionReason: \"Shell access is not permitted\",\n        };\n      }\n      return { permissionDecision: \"allow\" };\n    },\n  },\n});\n```\n\n### ユーザー コンテキストの追加\n\n```typescript\nconst session = await client.createSession({\n  hooks: {\n    onSessionStart: async () => {\n      const userPrefs = await loadUserPreferences();\n      return {\n        additionalContext: `User preferences: ${JSON.stringify(userPrefs)}`,\n      };\n    },\n  },\n});\n```\n\n## フックガイド\n\n* **[ツール使用前のフック](/ja/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)** - コントロール ツールの実行アクセス許可\n* **[ツール使用後フック](/ja/copilot/how-tos/copilot-sdk/hooks/post-tool-use)** - 変換ツールの結果\n* **[ユーザー プロンプト送信後フック](/ja/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)** - ユーザー プロンプトを変更する\n* **[ユーザープロンプト変換用フック](/ja/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed)** - モデルに表示されるプロンプトを置き換える\n* **[セッションライフサイクルフック](/ja/copilot/how-tos/copilot-sdk/hooks/session-lifecycle)** - セッションの開始と終了\n* **[セッションライフサイクルフック](/ja/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#agent-stop)** - エージェントが停止する前に完了を検証する\n* **[エラー処理フック](/ja/copilot/how-tos/copilot-sdk/hooks/error-handling)** - カスタム エラー処理\n\n## こちらも参照ください\n\n* [初めてのCopilot搭載アプリを構築する](/ja/copilot/how-tos/copilot-sdk/getting-started)\n* [初めてのCopilot搭載アプリを構築する](/ja/copilot/how-tos/copilot-sdk/getting-started#step-4-add-a-custom-tool)\n* [デバッグ ガイド](/ja/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}