{"meta":{"title":"ツール使用前のフック","intro":"onPreToolUse フックは、ツールを実行する前に呼び出されます。 これは次の目的で使用されます。","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/pre-tool-use","title":"ツール使用前"}],"documentType":"article"},"body":"# ツール使用前のフック\n\nonPreToolUse フックは、ツールを実行する前に呼び出されます。 これは次の目的で使用されます。\n\n\n\n\n\n* ツールの実行を承認または拒否する\n* ツールの引数を変更する\n* ツールのコンテキストを追加する\n* 会話からのツール出力を抑制する\n\n## フック署名\n\n
\n
TypeScript
\n\n```typescript\ntype PreToolUseHandler = (\n input: PreToolUseHookInput,\n invocation: HookInvocation\n) => Promise;\n```\n\n
\n\n
Python
\n\n```python\nPreToolUseHandler = Callable[\n [PreToolUseHookInput, dict[str, str]],\n Awaitable[PreToolUseHookOutput | None]\n]\n```\n\n
\n\n
Go
\n\n```golang\ntype PreToolUseHandler func(\n input PreToolUseHookInput,\n invocation HookInvocation,\n) (*PreToolUseHookOutput, error)\n```\n\n
\n\n
.NET
\n\n```csharp\npublic delegate Task PreToolUseHandler(\n PreToolUseHookInput input,\n HookInvocation invocation);\n```\n\n
\n\n
Java
\n\n```java\n@FunctionalInterface\npublic interface PreToolUseHandler {\n CompletableFuture handle(\n PreToolUseHookInput input,\n HookInvocation invocation);\n}\n```\n\n
\n\n
\n\n## 入力\n\n| フィールド | タイプ | Description |\n| ----------- | ------ | --------------------------- |\n| `timestamp` | 数値 | フックがトリガーされたときの Unix タイムスタンプ |\n| `cwd` | 文字列 | 現在の作業ディレクトリ |\n| `toolName` | 文字列 | 呼び出されるツールの名前 |\n| `toolArgs` | オブジェクト | ツールに渡される引数 |\n\n## アウトプット\n\n`null`または`undefined`を返して、変更なしでツールを実行できるようにします。 それ以外の場合は、次のいずれかのフィールドを持つオブジェクトを返します。\n\n| フィールド | タイプ | Description |\n| -------------------------- | ------- | ----------------------- |\n| `permissionDecision` | | |\n| `\"allow\"` | | |\n| \\| | | |\n| `\"deny\"` | | |\n| \\| | | |\n| `\"ask\"` | | |\n| ツール呼び出しを許可するかどうか | | |\n| `permissionDecisionReason` | 文字列 | ユーザーに表示される説明 (deny/ask) |\n| `modifiedArgs` | オブジェクト | ツールに渡す引数を変更しました |\n| `additionalContext` | 文字列 | 会話に挿入された追加のコンテキスト |\n| `suppressOutput` | boolean | true、ツールの出力は会話に表示されません |\n\n### アクセス許可の決定\n\n| 決定 | Behavior |\n| --------- | ------------------------------- |\n| `\"allow\"` | ツールが正常に実行される |\n| `\"deny\"` | ツールがブロックされ、その理由がユーザーに表示される |\n| `\"ask\"` | ユーザーに承認を求めるメッセージが表示される (対話型モード) |\n\n### 信頼できるカスタム ツールのアクセス許可プロンプトをスキップする\n\nプロンプトを表示せずに安全に実行できるカスタム ツールを定義する場合は、ツール定義に `skipPermission: true` を設定します。 これは、入力がアプリケーションによって既に制限されている、信頼できるアプリ所有のツールに使用します。呼び出しごとのポリシー チェックまたは引数の検証が必要な場合は、 `onPreToolUse` を使用します。\n\n```typescript\nconst getWeather = defineTool(\"get_weather\", {\n description: \"Get weather for a location.\",\n parameters: {\n type: \"object\",\n properties: { location: { type: \"string\" } },\n required: [\"location\"],\n },\n skipPermission: true,\n handler: async ({ location }) => ({ forecast: `Sunny in ${location}` }),\n});\n```\n\n## 例\n\n### すべてのツールを許可する (ログ記録のみ)\n\n
\n
TypeScript
\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input, invocation) => {\n console.log(`[${invocation.sessionId}] Calling ${input.toolName}`);\n console.log(` Args: ${JSON.stringify(input.toolArgs)}`);\n return { permissionDecision: \"allow\" };\n },\n },\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot.session import PermissionHandler\n\nasync def on_pre_tool_use(input_data, invocation):\n print(f\"[{invocation['session_id']}] Calling {input_data['toolName']}\")\n print(f\" Args: {input_data['toolArgs']}\")\n return {\"permissionDecision\": \"allow\"}\n\nsession = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={\"on_pre_tool_use\": on_pre_tool_use})\n```\n\n
\n\n
Go
\n\n```golang\nsession, _ := 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(\"[%s] Calling %s\\n\", inv.SessionID, input.ToolName)\n fmt.Printf(\" Args: %v\\n\", input.ToolArgs)\n return &copilot.PreToolUseHookOutput{\n PermissionDecision: \"allow\",\n }, nil\n },\n },\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n Hooks = new SessionHooks\n {\n OnPreToolUse = (input, invocation) =>\n {\n Console.WriteLine($\"[{invocation.SessionId}] Calling {input.ToolName}\");\n Console.WriteLine($\" Args: {input.ToolArgs}\");\n return Task.FromResult(\n new PreToolUseHookOutput { PermissionDecision = \"allow\" }\n );\n },\n },\n});\n```\n\n
\n\n
Java
\n\n\n\n```java\nimport com.github.copilot.*;\nimport com.github.copilot.rpc.*;\nimport java.util.concurrent.CompletableFuture;\n\nvar hooks = new SessionHooks()\n .setOnPreToolUse((input, invocation) -> {\n System.out.println(\"[\" + invocation.getSessionId() + \"] Calling \" + input.getToolName());\n System.out.println(\" Args: \" + input.getToolArgs());\n return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());\n });\n\nvar session = client.createSession(\n new SessionConfig()\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n .setHooks(hooks)\n).get();\n```\n\n
\n\n
\n\n### 特定のツールをブロックする\n\n```typescript\nconst BLOCKED_TOOLS = [\"shell\", \"bash\", \"write_file\", \"delete_file\"];\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: `Tool '${input.toolName}' is not permitted in this environment`,\n };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n});\n```\n\n### ツールの引数を変更する\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n // Add a default timeout to all shell commands\n if (input.toolName === \"shell\" && input.toolArgs) {\n const args = input.toolArgs as { command: string; timeout?: number };\n return {\n permissionDecision: \"allow\",\n modifiedArgs: {\n ...args,\n timeout: args.timeout ?? 30000, // Default 30s timeout\n },\n };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n});\n```\n\n### 特定のディレクトリへのファイル アクセスを制限する\n\n```typescript\nconst ALLOWED_DIRECTORIES = [\"/home/user/projects\", \"/tmp\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if (input.toolName === \"read_file\" || input.toolName === \"write_file\") {\n const args = input.toolArgs as { path: string };\n const isAllowed = ALLOWED_DIRECTORIES.some(dir => \n args.path.startsWith(dir)\n );\n \n if (!isAllowed) {\n return {\n permissionDecision: \"deny\",\n permissionDecisionReason: `Access to '${args.path}' is not permitted. Allowed directories: ${ALLOWED_DIRECTORIES.join(\", \")}`,\n };\n }\n }\n return { permissionDecision: \"allow\" };\n },\n },\n});\n```\n\n### 冗長なツール出力を抑制する\n\n```typescript\nconst VERBOSE_TOOLS = [\"list_directory\", \"search_files\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n return {\n permissionDecision: \"allow\",\n suppressOutput: VERBOSE_TOOLS.includes(input.toolName),\n };\n },\n },\n});\n```\n\n### ツールに基づいてコンテキストを追加する\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if (input.toolName === \"query_database\") {\n return {\n permissionDecision: \"allow\",\n additionalContext: \"Remember: This database uses PostgreSQL syntax. Always use parameterized queries.\",\n };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n});\n```\n\n## ベスト プラクティス\n\n1. **常に決定を返す** - `null` を返すことはツールを許可しますが、 `{ permissionDecision: \"allow\" }` で明示的に行う方が明確です。\n\n2. **拒否に役立つ理由を提供する** - 拒否する場合は、ユーザーが理解する理由を説明します。\n\n ```typescript\n return {\n permissionDecision: \"deny\",\n permissionDecisionReason: \"Shell commands require approval. Please describe what you want to accomplish.\",\n };\n ```\n\n3. **引数の変更には注意してください** 。 変更された引数で、ツールに必要なスキーマが維持されていることを確認してください。\n\n4. **パフォーマンスを考慮する** - ツール前フックは、各ツール呼び出しの前に同期的に実行されます。 高速状態を維持してください。\n\n5. \\*\\*\n `suppressOutput`慎重に使用\\*\\*する - 出力を抑制することは、モデルに結果が表示されないことを意味し、会話の品質に影響を与える可能性があります。\n\n## こちらも参照ください\n\n* [フックを使用する](/ja/copilot/how-tos/copilot-sdk/hooks)\n* [ツール使用後フック](/ja/copilot/how-tos/copilot-sdk/hooks/post-tool-use)\n* [デバッグ ガイド](/ja/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}