{"meta":{"title":"Работа с крючками","intro":"Hooks позволяют вставлять пользовательскую логику на каждый этап сессии Copilot — от самого начала, через каждое пользовательское задание и вызов инструмента, до момента её завершения. Это руководство объясняет практические сценарии использования, чтобы вы могли отправлять права, проводить аудит, уведомлять и многое другое без изменения поведения основного агента.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ru/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos","title":"Инструкции"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Второй пилот SDK"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Возможности"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/hooks","title":"Хуки"}],"documentType":"article"},"body":"# Работа с крючками\n\nHooks позволяют вставлять пользовательскую логику на каждый этап сессии Copilot — от самого начала, через каждое пользовательское задание и вызов инструмента, до момента её завершения. Это руководство объясняет практические сценарии использования, чтобы вы могли отправлять права, проводить аудит, уведомлять и многое другое без изменения поведения основного агента.\n\n\n\n\n\n## Обзор\n\nКрюк — это обратный вызов, который вы регистрируете один раз при создании сессии. SDK вызывает его в определённой точке жизненного цикла разговора, передаёт контекстный ввод и, по желанию, принимает выводы, изменяющие поведение сессии.\n\n![Диаграмма: блок-схема, показывающая описанный процесс.](/assets/images/help/copilot/copilot-sdk/features-hooks-diagram-0.png)\n\n| Хук | Когда он срабатывает | Что можно сделать |\n| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |\n| [Крючки жизненного цикла сессии](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start) | Сессия начинается (новая или возобновлённая) | Инжекция контекста, настройки загрузки |\n| [Хук, присланный пользовательским запросом](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted) | Пользователь отправляет сообщение | Переписывайте подсказки, добавляйте контекст, фильтруйте вводные данные |\n| [Запрос пользователя, преобразованный перехватчик](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed) | Среда выполнения создает запрос модели | Проверка или замена содержимого для модели |\n| [Крючок для использования до использования инструмента](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/pre-tool-use) | До запуска инструмента | Разрешить / отклонить / изменить вызов |\n| [Крючок после использования инструмента](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/post-tool-use) | После возвращения инструмента (только успех) | Трансформировать результаты, редактировать секреты, аудитировать |\n| [Крючок после использования инструмента](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/post-tool-use#failure-variant) | После того как инструмент возвращает отказ | Инжекция повторных инструкций, сбои журнала |\n| [Крючки жизненного цикла сессии](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end) | Сессия завершена | Очистить, зафиксировать метрики |\n| [Крюк для обработки ошибок](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/error-handling) | Возникает ошибка | Пользовательский логинг, логика повторных попыток, оповещения |\n\nВсе крючки **необязательны** — регистрируйте только те, которые вам нужны. Возврат `null` (или языковой эквивалент) с любого хука говорит SDK продолжать поведение по умолчанию.\n\n## Регистрационные крючки\n\nПередайте объект `hooks` при создании (или возобновлении) сессии. Каждый приведённый пример следует этой схеме.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input, invocation) => {\n /* ... */\n },\n onPreToolUse: async (input, invocation) => {\n /* ... */\n },\n onPostToolUse: async (input, invocation) => {\n /* ... */\n },\n // ... add only the hooks you need\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nclient = CopilotClient()\nawait client.start()\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_start\": on_session_start,\n \"on_pre_tool_use\": on_pre_tool_use,\n \"on_post_tool_use\": on_post_tool_use,\n # ... add only the hooks you need\n },\n)\n```\n\n
\n\n
Go
\n\n```golang\nclient := copilot.NewClient(nil)\n\nsession, err := client.CreateSession(ctx, &copilot.SessionConfig{\n Hooks: &copilot.SessionHooks{\n OnSessionStart: onSessionStart,\n OnPreToolUse: onPreToolUse,\n OnPostToolUse: onPostToolUse,\n // ... add only the hooks you need\n },\n OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {\n return &rpc.PermissionDecisionApproveOnce{}, nil\n },\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar client = new CopilotClient();\n\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n Hooks = new SessionHooks\n {\n OnSessionStart = onSessionStart,\n OnPreToolUse = onPreToolUse,\n OnPostToolUse = onPostToolUse,\n // ... add only the hooks you need\n },\n OnPermissionRequest = (req, inv) =>\n Task.FromResult(PermissionDecision.ApproveOnce()),\n});\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\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 .setOnSessionStart((input, inv) -> CompletableFuture.completedFuture(null))\n .setOnPreToolUse((input, inv) -> CompletableFuture.completedFuture(null))\n .setOnPostToolUse((input, inv) -> CompletableFuture.completedFuture(null));\n // ... add only the hooks you need\n\n var session = client.createSession(\n new SessionConfig()\n .setHooks(hooks)\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n ).get();\n}\n```\n\n
\n\n
\n\n> \\[!TIP]\n> Каждый обработчик хука получает `invocation` параметр, содержащий `sessionId`, что полезно для корреляции логов и поддержания состояния за сессию.\n\n## Сценарий использования: контроль разрешений\n\nИспользуйте `onPreToolUse` для создания слоя разрешений, который определяет, какие инструменты агент может запускать, какие аргументы разрешены и следует ли запросить пользователя перед выполнением.\n\n### Список разрешений на безопасный набор инструментов\n\n
\n
TypeScript
\n\n```typescript\nconst READ_ONLY_TOOLS = [\"read_file\", \"glob\", \"grep\", \"view\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if (!READ_ONLY_TOOLS.includes(input.toolName)) {\n return {\n permissionDecision: \"deny\",\n permissionDecisionReason: `Only read-only tools are allowed. \"${input.toolName}\" was blocked.`,\n };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import PermissionDecisionApproveOnce\n\nREAD_ONLY_TOOLS = [\"read_file\", \"glob\", \"grep\", \"view\"]\n\nasync def on_pre_tool_use(input_data, invocation):\n if input_data[\"toolName\"] not in READ_ONLY_TOOLS:\n return {\n \"permissionDecision\": \"deny\",\n \"permissionDecisionReason\":\n f'Only read-only tools are allowed. \"{input_data[\"toolName\"]}\" was blocked.',\n }\n return {\"permissionDecision\": \"allow\"}\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\"on_pre_tool_use\": on_pre_tool_use},\n)\n```\n\n
\n\n
Go
\n\n```golang\nreadOnlyTools := map[string]bool{\"read_file\": true, \"glob\": true, \"grep\": true, \"view\": true}\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{\n Hooks: &copilot.SessionHooks{\n OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {\n if !readOnlyTools[input.ToolName] {\n return &copilot.PreToolUseHookOutput{\n PermissionDecision: \"deny\",\n PermissionDecisionReason: fmt.Sprintf(\"Only read-only tools are allowed. %q was blocked.\", input.ToolName),\n }, nil\n }\n return &copilot.PreToolUseHookOutput{PermissionDecision: \"allow\"}, nil\n },\n },\n})\n```\n\n
\n\n
.NET
\n\n```csharp\nvar readOnlyTools = new HashSet { \"read_file\", \"glob\", \"grep\", \"view\" };\n\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n Hooks = new SessionHooks\n {\n OnPreToolUse = (input, invocation) =>\n {\n if (!readOnlyTools.Contains(input.ToolName))\n {\n return Task.FromResult(new PreToolUseHookOutput\n {\n PermissionDecision = \"deny\",\n PermissionDecisionReason = $\"Only read-only tools are allowed. \\\"{input.ToolName}\\\" was blocked.\",\n });\n }\n return Task.FromResult(\n new PreToolUseHookOutput { PermissionDecision = \"allow\" });\n },\n },\n});\n```\n\n
\n\n
Java
\n\n\n\n```java\nimport java.util.Set;\nimport java.util.concurrent.CompletableFuture;\n\nimport com.github.copilot.rpc.PermissionHandler;\nimport com.github.copilot.rpc.SessionConfig;\nimport com.github.copilot.rpc.SessionHooks;\nimport com.github.copilot.rpc.PreToolUseHookOutput;\nvar readOnlyTools = Set.of(\"read_file\", \"glob\", \"grep\", \"view\");\n\nvar hooks = new SessionHooks()\n .setOnPreToolUse((input, invocation) -> {\n if (!readOnlyTools.contains(input.getToolName())) {\n return CompletableFuture.completedFuture(\n PreToolUseHookOutput.deny(\n \"Only read-only tools are allowed. \\\"\" + input.getToolName() + \"\\\" was blocked.\")\n );\n }\n return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());\n });\n\nvar session = client.createSession(\n new SessionConfig()\n .setHooks(hooks)\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n).get();\n```\n\n
\n\n
\n\n### Ограничить доступ к файлам определёнными каталогами\n\n```typescript\nconst ALLOWED_DIRS = [\"/home/user/projects\", \"/tmp\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if ([\"read_file\", \"write_file\", \"edit\"].includes(input.toolName)) {\n const filePath = (input.toolArgs as { path: string }).path;\n const allowed = ALLOWED_DIRS.some((dir) => filePath.startsWith(dir));\n\n if (!allowed) {\n return {\n permissionDecision: \"deny\",\n permissionDecisionReason: `Access to \"${filePath}\" is outside the allowed directories.`,\n };\n }\n }\n return { permissionDecision: \"allow\" };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Спросите пользователя перед деструктивными операциями\n\n```typescript\nconst DESTRUCTIVE_TOOLS = [\"delete_file\", \"shell\", \"bash\"];\n\nconst session = await client.createSession({\n hooks: {\n onPreToolUse: async (input) => {\n if (DESTRUCTIVE_TOOLS.includes(input.toolName)) {\n return { permissionDecision: \"ask\" };\n }\n return { permissionDecision: \"allow\" };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\nВозврат `\"ask\"` делегирует решение пользователю во время выполнения — это полезно для разрушительных действий, когда вы хотите, чтобы человек был в цикле.\n\n## Сценарий использования: аудит и соответствие требованиям\n\nОбъедините `onPreToolUse`, `onPostToolUse`, и жизненный цикл сессии зацепляется, чтобы создать полный аудит, который фиксирует каждое действие агента.\n\n### Журнал структурированного аудита\n\n
\n
TypeScript
\n\n```typescript\ninterface AuditEntry {\n timestamp: Date;\n sessionId: string;\n event: string;\n toolName?: string;\n toolArgs?: unknown;\n toolResult?: unknown;\n prompt?: string;\n}\n\nconst auditLog: AuditEntry[] = [];\n\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"session_start\",\n });\n return null;\n },\n onUserPromptSubmitted: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"user_prompt\",\n prompt: input.prompt,\n });\n return null;\n },\n onPreToolUse: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"tool_call\",\n toolName: input.toolName,\n toolArgs: input.toolArgs,\n });\n return { permissionDecision: \"allow\" };\n },\n onPostToolUse: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"tool_result\",\n toolName: input.toolName,\n toolResult: input.toolResult,\n });\n return null;\n },\n onSessionEnd: async (input, invocation) => {\n auditLog.push({\n timestamp: input.timestamp,\n sessionId: invocation.sessionId,\n event: \"session_end\",\n });\n\n // Persist the log — swap this with your own storage backend\n await fs.promises.writeFile(\n `audit-${invocation.sessionId}.json`,\n JSON.stringify(auditLog, null, 2),\n );\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n\n\n```python\nimport json, aiofiles\nfrom copilot import PermissionDecisionApproveOnce\n\naudit_log = []\n\nasync def on_session_start(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"session_start\",\n })\n return None\n\nasync def on_user_prompt_submitted(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"user_prompt\",\n \"prompt\": input_data[\"prompt\"],\n })\n return None\n\nasync def on_pre_tool_use(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"tool_call\",\n \"tool_name\": input_data[\"toolName\"],\n \"tool_args\": input_data[\"toolArgs\"],\n })\n return {\"permissionDecision\": \"allow\"}\n\nasync def on_post_tool_use(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"tool_result\",\n \"tool_name\": input_data[\"toolName\"],\n \"tool_result\": input_data[\"toolResult\"],\n })\n return None\n\nasync def on_session_end(input_data, invocation):\n audit_log.append({\n \"timestamp\": input_data[\"timestamp\"].isoformat(),\n \"session_id\": invocation[\"session_id\"],\n \"event\": \"session_end\",\n })\n async with aiofiles.open(f\"audit-{invocation['session_id']}.json\", \"w\") as f:\n await f.write(json.dumps(audit_log, indent=2))\n return None\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_start\": on_session_start,\n \"on_user_prompt_submitted\": on_user_prompt_submitted,\n \"on_pre_tool_use\": on_pre_tool_use,\n \"on_post_tool_use\": on_post_tool_use,\n \"on_session_end\": on_session_end,\n },\n)\n```\n\n
\n\n
\n\n### Скрыть секреты из результатов инструментов\n\n```typescript\nconst SECRET_PATTERNS = [\n /(?:api[_-]?key|token|secret|password)\\s*[:=]\\s*[\"']?[\\w\\-\\.]+[\"']?/gi,\n];\n\nconst session = await client.createSession({\n hooks: {\n onPostToolUse: async (input) => {\n if (typeof input.toolResult !== \"string\") return null;\n\n let redacted = input.toolResult;\n for (const pattern of SECRET_PATTERNS) {\n redacted = redacted.replace(pattern, \"[REDACTED]\");\n }\n\n return redacted !== input.toolResult\n ? { modifiedResult: redacted }\n : null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Сценарий использования: уведомления и звуки\n\nКрючки срабатывают в процессе вашего приложения, так что вы можете вызвать любые побочные эффекты — уведомления на рабочем столе, звуки, сообщения в Slack или звонки через вебхуки.\n\n### Уведомления на рабочем столе о событиях сессии\n\n
\n
TypeScript
\n\n```typescript\nimport notifier from \"node-notifier\"; // npm install node-notifier\n\nconst session = await client.createSession({\n hooks: {\n onSessionEnd: async (input, invocation) => {\n notifier.notify({\n title: \"Copilot Session Complete\",\n message: `Session ${invocation.sessionId.slice(0, 8)} finished (${input.reason}).`,\n });\n return null;\n },\n onErrorOccurred: async (input) => {\n notifier.notify({\n title: \"Copilot Error\",\n message: input.error.slice(0, 200),\n });\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nimport subprocess\nfrom copilot import PermissionDecisionApproveOnce\n\nasync def on_session_end(input_data, invocation):\n sid = invocation[\"session_id\"][:8]\n reason = input_data[\"reason\"]\n subprocess.Popen([\n \"notify-send\", \"Copilot Session Complete\",\n f\"Session {sid} finished ({reason}).\",\n ])\n return None\n\nasync def on_error_occurred(input_data, invocation):\n subprocess.Popen([\n \"notify-send\", \"Copilot Error\",\n input_data[\"error\"][:200],\n ])\n return None\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_end\": on_session_end,\n \"on_error_occurred\": on_error_occurred,\n },\n)\n```\n\n
\n\n
\n\n### Воспроизведите звук, когда инструмент заканчивается\n\n```typescript\nimport { exec } from \"node:child_process\";\n\nconst session = await client.createSession({\n hooks: {\n onPostToolUse: async (input) => {\n // macOS: play a system sound after every tool call\n exec(\"afplay /System/Library/Sounds/Pop.aiff\");\n return null;\n },\n onErrorOccurred: async () => {\n exec(\"afplay /System/Library/Sounds/Basso.aiff\");\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Опубликовать об ошибках в Slack\n\n```typescript\nconst SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL!;\n\nconst session = await client.createSession({\n hooks: {\n onErrorOccurred: async (input, invocation) => {\n if (!input.recoverable) {\n await fetch(SLACK_WEBHOOK_URL, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n text: `🚨 Unrecoverable error in session \\`${invocation.sessionId.slice(0, 8)}\\`:\\n\\`\\`\\`${input.error}\\`\\`\\``,\n }),\n });\n }\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Пример использования: быстрое обогащение\n\nИспользуйте `onSessionStart` и `onUserPromptSubmitted` автоматически вводите контекст, чтобы пользователям не приходилось повторяться.\n\n### Ввести метаданные проекта при начале сессии\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input) => {\n const pkg = JSON.parse(\n await fs.promises.readFile(\"package.json\", \"utf-8\"),\n );\n return {\n additionalContext: [\n `Project: ${pkg.name} v${pkg.version}`,\n `Node: ${process.version}`,\n `Working directory: ${input.workingDirectory}`,\n ].join(\"\\n\"),\n };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Расширяйте команды стенографии в подсказках\n\n```typescript\nconst SHORTCUTS: Record = {\n \"/fix\": \"Find and fix all errors in the current file\",\n \"/test\": \"Write comprehensive unit tests for this code\",\n \"/explain\": \"Explain this code in detail\",\n \"/refactor\": \"Refactor this code to improve readability\",\n};\n\nconst session = await client.createSession({\n hooks: {\n onUserPromptSubmitted: async (input) => {\n for (const [shortcut, expansion] of Object.entries(SHORTCUTS)) {\n if (input.prompt.startsWith(shortcut)) {\n const rest = input.prompt.slice(shortcut.length).trim();\n return { modifiedPrompt: rest ? `${expansion}: ${rest}` : expansion };\n }\n }\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Сценарий использования: обработка ошибок и восстановление\n\nКрючок `onErrorOccurred` даёт вам шанс реагировать на неудачи — будь то повторная попытка, уведомление человека или достойное отключение.\n\n### Повторяйте ошибки переходных моделей\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onErrorOccurred: async (input) => {\n if (input.errorContext === \"model_call\" && input.recoverable) {\n return {\n errorHandling: \"retry\",\n retryCount: 3,\n userNotification: \"Temporary model issue — retrying…\",\n };\n }\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n### Дружественные сообщения об ошибках\n\n```typescript\nconst FRIENDLY_MESSAGES: Record = {\n model_call: \"The AI model is temporarily unavailable. Please try again.\",\n tool_execution: \"A tool encountered an error. Check inputs and try again.\",\n system: \"A system error occurred. Please try again later.\",\n};\n\nconst session = await client.createSession({\n hooks: {\n onErrorOccurred: async (input) => {\n return {\n userNotification: FRIENDLY_MESSAGES[input.errorContext] ?? input.error,\n };\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Сценарий использования: метрики сессии\n\nОтслеживайте, сколько длятся сессии, сколько инструментов запускается и почему сессии заканчиваются — это полезно для дашбордов и мониторинга затрат.\n\n
\n
TypeScript
\n\n```typescript\nconst metrics = new Map<\n string,\n { start: Date; toolCalls: number; prompts: number }\n>();\n\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input, invocation) => {\n metrics.set(invocation.sessionId, {\n start: input.timestamp,\n toolCalls: 0,\n prompts: 0,\n });\n return null;\n },\n onUserPromptSubmitted: async (_input, invocation) => {\n metrics.get(invocation.sessionId)!.prompts++;\n return null;\n },\n onPreToolUse: async (_input, invocation) => {\n metrics.get(invocation.sessionId)!.toolCalls++;\n return { permissionDecision: \"allow\" };\n },\n onSessionEnd: async (input, invocation) => {\n const m = metrics.get(invocation.sessionId)!;\n const durationSec =\n (input.timestamp.getTime() - m.start.getTime()) / 1000;\n\n console.log(\n `Session ${invocation.sessionId.slice(0, 8)}: ` +\n `${durationSec.toFixed(1)}s, ${m.prompts} prompts, ` +\n `${m.toolCalls} tool calls, ended: ${input.reason}`,\n );\n\n metrics.delete(invocation.sessionId);\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import PermissionDecisionApproveOnce\n\nsession_metrics = {}\n\nasync def on_session_start(input_data, invocation):\n session_metrics[invocation[\"session_id\"]] = {\n \"start\": input_data[\"timestamp\"],\n \"tool_calls\": 0,\n \"prompts\": 0,\n }\n return None\n\nasync def on_user_prompt_submitted(input_data, invocation):\n session_metrics[invocation[\"session_id\"]][\"prompts\"] += 1\n return None\n\nasync def on_pre_tool_use(input_data, invocation):\n session_metrics[invocation[\"session_id\"]][\"tool_calls\"] += 1\n return {\"permissionDecision\": \"allow\"}\n\nasync def on_session_end(input_data, invocation):\n m = session_metrics.pop(invocation[\"session_id\"])\n duration = (input_data[\"timestamp\"] - m[\"start\"]).total_seconds()\n sid = invocation[\"session_id\"][:8]\n print(\n f\"Session {sid}: {duration:.1f}s, {m['prompts']} prompts, \"\n f\"{m['tool_calls']} tool calls, ended: {input_data['reason']}\"\n )\n return None\n\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n hooks={\n \"on_session_start\": on_session_start,\n \"on_user_prompt_submitted\": on_user_prompt_submitted,\n \"on_pre_tool_use\": on_pre_tool_use,\n \"on_session_end\": on_session_end,\n },\n)\n```\n\n
\n\n
\n\n## Комбинирование крюков\n\nХуки составляются естественно. Один `hooks` объект может обрабатывать права **доступа,** аудит **и** уведомления — каждый крючок выполняет свою функцию.\n\n```typescript\nconst session = await client.createSession({\n hooks: {\n onSessionStart: async (input) => {\n console.log(`[audit] session started in ${input.workingDirectory}`);\n return { additionalContext: \"Project uses TypeScript and Vitest.\" };\n },\n onPreToolUse: async (input) => {\n console.log(`[audit] tool requested: ${input.toolName}`);\n if (input.toolName === \"shell\") {\n return { permissionDecision: \"ask\" };\n }\n return { permissionDecision: \"allow\" };\n },\n onPostToolUse: async (input) => {\n console.log(`[audit] tool completed: ${input.toolName}`);\n return null;\n },\n onErrorOccurred: async (input) => {\n console.error(`[alert] ${input.errorContext}: ${input.error}`);\n return null;\n },\n onSessionEnd: async (input, invocation) => {\n console.log(\n `[audit] session ${invocation.sessionId.slice(0, 8)} ended: ${input.reason}`,\n );\n return null;\n },\n },\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Лучшие практики\n\n1. **Держите крючки быстрыми.** Каждый крючок идёт по очереди — медленные хуки задерживают разговор. По возможности переложите тяжёлую работу (запись в базу данных, HTTP-вызовы) в фоновую очередь.\n\n2. **Возвращайся `null` , когда тебе нечего менять.** Это указывает SDK продолжать по умолчанию и избегает ненужного распределения объектов.\n\n3. **Будьте чёткие в решениях о разрешении.** Возврат `{ permissionDecision: \"allow\" }` яснее, чем возврат `null`, хотя оба позволяют использовать инструмент.\n\n4. **Не принимайте критические ошибки.** Можно подавить ошибки восстанавливаемых инструментов, но всегда логируйте или оповещайте о невосстановимых ошибках.\n\n5. **Используйте `additionalContext` вместо того, `modifiedPrompt` чтобы иметь возможность.** Добавление контекста сохраняет изначальный замысел пользователя, при этом направляя модель.\n\n6. **Состояние области действия по идентификатору сессии.** Если вы отслеживаете данные за сессию, включайте `invocation.sessionId` их и очищайте в `onSessionEnd`.\n\n## Reference\n\nПолные определения типов, таблицы полей ввода/вывода и дополнительные примеры для каждого хука смотрите ссылку на API:\n\n* [Сессионные хуки](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/hooks-overview)\n* [Крючок для использования до использования инструмента](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/pre-tool-use)\n* [Крючок после использования инструмента](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/post-tool-use)\n* [Хук, присланный пользовательским запросом](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)\n* [Запрос пользователя, преобразованный перехватчик](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed)\n* [Крючки жизненного цикла сессии](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/session-lifecycle)\n* [Крюк для обработки ошибок](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/error-handling)\n\n## См. также\n\n* [Создайте своё первое приложение на базе Copilot](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started)\n* [Пользовательские агенты и оркестровка субагентов](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/custom-agents)\n* [События потоковых сессий](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/streaming-events)\n* [Руководство по отладке](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}