{"meta":{"title":"Ссылка на крючки GitHub Copilot CLI","intro":"Найдите события крюка, форматы конфигураций и входные полезные нагрузки для Второй пилот CLI.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ru/copilot","title":"GitHub Copilot"},{"href":"/ru/copilot/reference","title":"Справочные материалы"},{"href":"/ru/copilot/reference/copilot-cli-reference","title":"Ссылка Второй пилот CLI"},{"href":"/ru/copilot/reference/copilot-cli-reference/cli-hooks-reference","title":"Ссылка на CLI-крючки"}],"documentType":"article"},"body":"# Ссылка на крючки GitHub Copilot CLI\n\nНайдите события крюка, форматы конфигураций и входные полезные нагрузки для Второй пилот CLI.\n\nХуки — это внешние команды, которые выполняются в определённых жизненных точках сессии, обеспечивая индивидуальную автоматизацию, управление безопасностью и интеграции. Файлы конфигурации крюков загружаются автоматически из `.github/hooks/*.json` вашего репозитория.\n\n## Формат конфигурации крючка\n\nКонфигурационные файлы крючка используют формат JSON с версией `1`.\n\n### Командные крючки\n\nКомандные хуки запускают shell-скрипты и поддерживаются на всех типах хуков.\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"preToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"your-bash-command\",\n        \"powershell\": \"your-powershell-command\",\n        \"cwd\": \"optional/working/directory\",\n        \"env\": { \"VAR\": \"value\" },\n        \"timeoutSec\": 30\n      }\n    ]\n  }\n}\n```\n\n| Поле         | Тип         | Обязательный                | Description                                                              |\n| ------------ | ----------- | --------------------------- | ------------------------------------------------------------------------ |\n| `bash`       | string      | Один из `bash`/`powershell` | Команда shell для Unix.                                                  |\n| `cwd`        | string      | Нет                         | Рабочая папка для команды (относительно корня репозитория или абсолюта). |\n| `env`        | object      | Нет                         | Переменные среды для установки (поддерживает расширение переменных).     |\n| `powershell` | string      | Один из `bash`/`powershell` | Команда shell для Windows.                                               |\n| `timeoutSec` | число/номер | Нет                         | Время ожидания в секундах. По умолчанию: `30`.                           |\n| `type`       | `\"command\"` | Да                          | Этот параметр должен содержать значение `\"command\"`.                     |\n\n### Подсказочные зацепки\n\nПодсказочные крючки автоматически отправляют текст так, будто его написал сам пользователь. Они поддерживаются только на `sessionStart` новых **интерактивных сессиях** и запускаются только для новых интерактивных сессий. Они не срабатывают при возобновлении и не срабатывают в неинтерактивном режиме запросов (`-p`). Текст может быть подсказкой на естественном языке или командой слэша.\n\n```json\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [\n      {\n        \"type\": \"prompt\",\n        \"prompt\": \"Your prompt text or /slash-command\"\n      }\n    ]\n  }\n}\n```\n\n| Поле     | Тип        | Обязательный | Description                                                                            |\n| -------- | ---------- | ------------ | -------------------------------------------------------------------------------------- |\n| `type`   | `\"prompt\"` | Да           | Этот параметр должен содержать значение `\"prompt\"`.                                    |\n| `prompt` | string     | Да           | Текст для отправки — это может быть сообщение на естественном языке или команда слэша. |\n\n## События с крючками\n\n| Событие               | Срабатывает, когда                                                                                                                                                                                                                                                                                                                      | Обработка выхода                                                                                                    |\n| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\n| `agentStop`           | Главный агент завершает ход.                                                                                                                                                                                                                                                                                                            | Да — может блокировать и заставлять продолжение.                                                                    |\n| `errorOccurred`       | Ошибка возникает во время выполнения.                                                                                                                                                                                                                                                                                                   | Нет                                                                                                                 |\n| `notification`        | Срабатывает асинхронно, когда CLI отправляет системное уведомление (завершение оболочки, завершение работы агента или простоя, запросы разрешения, диалоги вызова). Удар и забыть: никогда не блокирует сессию. Поддерживает `matcher` regex на `notification_type`.                                                                    | Опционально — можно вводить `additionalContext` в сессию.                                                           |\n| `permissionRequest`   | Срабатывает до запуска сервиса разрешений (движок правил, утверждение сессии, авторазрешение/автозапрет и подсказка пользователя). Если выход объединённого крючка возвращается `behavior: \"allow\"` или `\"deny\"`, это решение приводит к короткому замыканию нормального потока разрешений. Поддерживает `matcher` regex на `toolName`. | Да — можно разрешить или отклонить программно.                                                                      |\n| `postToolUse`         | После успешного завершения каждого инструмента.                                                                                                                                                                                                                                                                                         | Да — можно заменить успешный результат (только программные хуки SDK).                                               |\n| `postToolUseFailure`  | После того, как инструмент завершается с неудачей.                                                                                                                                                                                                                                                                                      | Да — может предоставить навигацию по восстановлению через `additionalContext` (код `2` выхода для командных хуков). |\n| `preCompact`          | Вот-вот начнётся уплотнение контекста (ручное или автоматическое). Поддерживают `matcher` фильтрацию по триггерам (`\"manual\"` или `\"auto\"`).                                                                                                                                                                                            | Нет — только уведомление.                                                                                           |\n| `preToolUse`          | Перед тем, как каждый инструмент сработает.                                                                                                                                                                                                                                                                                             | Да — можно разрешать, отрицать или изменять.                                                                        |\n| `sessionEnd`          | Сессия заканчивается.                                                                                                                                                                                                                                                                                                                   | Нет                                                                                                                 |\n| `sessionStart`        | Начинается новая или возобновлённая сессия.                                                                                                                                                                                                                                                                                             | Нет                                                                                                                 |\n| `subagentStart`       | Появляется субагент (до его запуска). Возвраты `additionalContext` предшествуют запросу субагента. Поддерживает `matcher` фильтрацию по имени агента.                                                                                                                                                                                   | Нет — нельзя блокировать создание.                                                                                  |\n| `subagentStop`        | Субагент завершает.                                                                                                                                                                                                                                                                                                                     | Да — может блокировать и заставлять продолжение.                                                                    |\n| `userPromptSubmitted` | Пользователь отправляет запрос.                                                                                                                                                                                                                                                                                                         | Нет                                                                                                                 |\n\n## Полезные нагрузки для ввода событий hook\n\nКаждое событие с крючком доставляет JSON-полезную нагрузку обработчику крючков. Поддерживаются два формата полезной нагрузки, выбираемых по имени события, используемому в конфигурации крючка:\n\n* **camelCase format** — Настройте имя события в camelCase (например, `sessionStart`). Поля используют CamelCase.\n\n***\n\n```\n          VS Code совместимый формат** — Настройте имя события в PascalCase (например, `SessionStart`). Поля используют snake_case для соответствия VS CodeCopilot формату расширения.\n```\n\n### `sessionStart` / `SessionStart`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;      // Unix timestamp in milliseconds\n    cwd: string;\n    source: \"startup\" | \"resume\" | \"new\";\n    initialPrompt?: string;\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"SessionStart\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    source: \"startup\" | \"resume\" | \"new\";\n    initial_prompt?: string;\n}\n```\n\n### `sessionEnd` / `SessionEnd`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"SessionEnd\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n### `userPromptSubmitted` / `UserPromptSubmit`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    prompt: string;\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"UserPromptSubmit\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    prompt: string;\n}\n```\n\n### `preToolUse` / `PreToolUse`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    toolName: string;\n    toolArgs: unknown;\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\nПри настройке с именем `PreToolUse`события PascalCase полезная нагрузка использует snake\\_case имена полей, чтобы соответствовать формату VS CodeCopilot расширения:\n\n```typescript\n{\n    hook_event_name: \"PreToolUse\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    tool_name: string;\n    tool_input: unknown;    // Tool arguments (parsed from JSON string when possible)\n}\n```\n\n### `postToolUse` / `PostToolUse`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    toolName: string;\n    toolArgs: unknown;\n    toolResult: {\n        resultType: \"success\";\n        textResultForLlm: string;\n    }\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"PostToolUse\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    tool_name: string;\n    tool_input: unknown;\n    tool_result: {\n        result_type: \"success\" | \"failure\" | \"denied\" | \"error\";\n        text_result_for_llm: string;\n    }\n}\n```\n\n### `postToolUseFailure` / `PostToolUseFailure`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    toolName: string;\n    toolArgs: unknown;\n    error: string;\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"PostToolUseFailure\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    tool_name: string;\n    tool_input: unknown;\n    error: string;\n}\n```\n\n### `agentStop` / `Stop`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    stopReason: \"end_turn\";\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"Stop\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    transcript_path: string;\n    stop_reason: \"end_turn\";\n}\n```\n\n### `subagentStart`\n\n```\n          **Входные данные:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    agentName: string;\n    agentDisplayName?: string;\n    agentDescription?: string;\n}\n```\n\n### `subagentStop` / `SubagentStop`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    agentName: string;\n    agentDisplayName?: string;\n    stopReason: \"end_turn\";\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"SubagentStop\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    transcript_path: string;\n    agent_name: string;\n    agent_display_name?: string;\n    stop_reason: \"end_turn\";\n}\n```\n\n### `errorOccurred` / `ErrorOccurred`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    error: {\n        message: string;\n        name: string;\n        stack?: string;\n    };\n    errorContext: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n    recoverable: boolean;\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"ErrorOccurred\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    error: {\n        message: string;\n        name: string;\n        stack?: string;\n    };\n    error_context: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n    recoverable: boolean;\n}\n```\n\n### `preCompact` / `PreCompact`\n\n```\n          **Ввод CamelCase:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    transcriptPath: string;\n    trigger: \"manual\" | \"auto\";\n    customInstructions: string;\n}\n```\n\n```\n          **\n          VS Code Совместимый вход:**\n```\n\n```typescript\n{\n    hook_event_name: \"PreCompact\";\n    session_id: string;\n    timestamp: string;      // ISO 8601 timestamp\n    cwd: string;\n    transcript_path: string;\n    trigger: \"manual\" | \"auto\";\n    custom_instructions: string;\n}\n```\n\n##\n\n```\n          `preToolUse` Контроль принятия решений\n```\n\nКрюк `preToolUse` может управлять выполнением инструмента, записывая JSON-объект в stdout.\n\n| Поле                 | Ценности | Description |\n| -------------------- | -------- | ----------- |\n| `permissionDecision` |          |             |\n\n```\n          `\"allow\"`, , `\"deny\"``\"ask\"` | Работает ли инструмент. Пустой выход использует стандартное поведение. |\n```\n\n\\| `permissionDecisionReason` | string | Агенту показали разум. Требуется при принятии решения `\"deny\"`. |\n\\| `modifiedArgs` | object | Замените аргументы инструментов вместо оригиналов. |\n\n##\n\n```\n          `agentStop`\n           / \n          `subagentStop` Контроль принятия решений\n```\n\n| Поле       | Ценности | Description |\n| ---------- | -------- | ----------- |\n| `decision` |          |             |\n\n```\n          `\"block\"`, `\"allow\"` | \n          `\"block\"` заставляет другого агента поступить, используя `reason` это как подсказку. |\n```\n\n\\| `reason` | string | Подсказка для следующего хода, когда `decision` .`\"block\"` |\n\n##\n\n```\n          `permissionRequest` Контроль принятия решений\n\n          `permissionRequest` Крюк срабатывает до запуска сервиса разрешений — до проверки правил, одобрения сессии, авторазрешения/автозапрета и подсказки пользователя. Если крючки возвращаются `behavior: \"allow\"` или `\"deny\"`, это решение приводит к короткому замыканию нормального потока разрешений. Возврат ничего не выходит на обычную обработку разрешений. Используйте его для программного одобрения или отклонения вызовов инструментов — особенно полезно в режимах pipe (`-p`) и CI, где нет интерактивного запроса.\n```\n\nВсе настроенные `permissionRequest` крючки работают для каждого запроса (кроме `read` типов `hook` с разрешениями, которые срабатывают перед хуками). Выходы крючка объединяются с более поздними выходами хука, переопределяя более ранние.\n\n```\n          **Матчер:** Необязательный регулярный выражение, тестируемое против `toolName`. Закрепленное как `^(?:pattern)$`; должно совпадать с полным именем инструмента. При установке крюк срабатывает только при совпадающих названиях инструментов.\n```\n\nВыводите JSON в stdout, чтобы контролировать решение о разрешении:\n\n| Поле       | Ценности | Description |\n| ---------- | -------- | ----------- |\n| `behavior` |          |             |\n\n```\n          `\"allow\"`, `\"deny\"` | Одобрить или отклонить этот инструмент. |\n```\n\n\\| `message` | string | Причина возвращалась к LLM при отказе. |\n\\| `interrupt` | boolean | В `true` сочетании с `\"deny\"`, агент полностью останавливается. |\n\nВернуть пустой выход или `{}` провалиться в нормальный поток разрешений. Для командных хуков выходной код `2` рассматривается как отказ; stdout JSON (если он есть) объединяется с `{\"behavior\":\"deny\"}`, а stderr игнорируется.\n\n##\n\n```\n          `notification` Крюк\n\n          `notification` Крюк срабатывает асинхронно, когда CLI издаёт системное уведомление. Эти хуки — это система «убери и забудь»: они никогда не блокируют сессию, а любые ошибки фиксируются и пропускаются.\n\n          **Входные данные:**\n```\n\n```typescript\n{\n    sessionId: string;\n    timestamp: number;\n    cwd: string;\n    hook_event_name: \"Notification\";\n    message: string;           // Human-readable notification text\n    title?: string;            // Short title (e.g., \"Permission needed\", \"Shell completed\")\n    notification_type: string; // One of the types listed below\n}\n```\n\n```\n          **Типы уведомлений:**\n```\n\n| Тип                        | Когда он срабатывает                                                                |\n| -------------------------- | ----------------------------------------------------------------------------------- |\n| `shell_completed`          | Заканчивается фоновая (асинхронная) команда shell                                   |\n| `shell_detached_completed` | Завершается отделённая оболочная сессия                                             |\n| `agent_completed`          | Фоновый субагент заканчивает (выполнен или неудачно)                                |\n| `agent_idle`               | Агент фона заканчивает ход и переходит в состояние простоя (ожидание `write_agent`) |\n| `permission_prompt`        | Агент запрашивает разрешение на запуск инструмента                                  |\n| `elicitation_dialog`       | Агент запрашивает дополнительную информацию у пользователя                          |\n\n```\n          **Выходные данные:**\n```\n\n```typescript\n{\n    additionalContext?: string; // Injected into the session as a user message\n}\n```\n\nЕсли `additionalContext` он возвращается, текст вводится в сессию в виде предварительного пользовательского сообщения. Это может запустить дальнейшую обработку агентов, если сессия находится в простое. Возврат `{}` или опустошение выхода, чтобы не предпринимать действия.\n\n```\n          **Матчер:** Опциональный регуляр на `notification_type`. Паттерн закреплён как `^(?:pattern)$`. Опустите `matcher` все типы уведомлений.\n```\n\n## Имена инструментов для подбора крючков\n\n| Имя инструмента | Description                             |\n| --------------- | --------------------------------------- |\n| `ask_user`      | Задайте пользователю уточняющий вопрос. |\n| `bash`          | Выполнять команды оболочки (Unix).      |\n| `create`        | Создавайте новые файлы.                 |\n| `edit`          | Изменять содержимое файла.              |\n| `glob`          | Ищите файлы по шаблону.                 |\n| `grep`          | Поиск по содержимому файла.             |\n| `powershell`    | Выполнять команды shell (Windows).      |\n| `task`          | Запускайте задачи субагентов.           |\n| `view`          | Чтение содержимого файла.               |\n| `web_fetch`     | Загружайте веб-страницы.                |\n\nЕсли настраивать несколько хуков одного типа, они выполняются по порядку. Для `preToolUse`, если какой-либо крюк возвращается `\"deny\"`, инструмент блокируется. Для командных хуков выход с кодом `postToolUseFailure` приводит к возврату stderr в качестве руководства `2` по восстановлению для помощника. Сбои с крючками (ненулевые коды выхода или тайм-ауты) фиксируются и пропускаются — они никогда не блокируют выполнение агентов.\n\n## Дополнительные материалы\n\n* [Использование крючков с GitHub Copilot CLI](/ru/copilot/how-tos/copilot-cli/use-hooks)\n* [Конфигурация крючков](/ru/copilot/reference/hooks-configuration)\n* [Справочник команды GitHub Copilot CLI](/ru/copilot/reference/copilot-cli-reference/cli-command-reference)"}