# Ссылка на крючки GitHub Copilot Найдите события крючков, форматы конфигурации и входные полезные нагрузки для хуков в Второй пилот CLI и Copilot облачный агент. ## Introduction Хуки — это внешние команды, которые выполняются в определённых жизненных точках сессии, обеспечивая индивидуальную автоматизацию, управление безопасностью и интеграции. Крючки поддерживаются двумя Copilot поверхностями: Второй пилот CLI и Copilot облачный агент. Большинство конфигурационных форматов и событий одинаковы, но окружение выполнения и набор событий, которые могут запускаться, различаются. На протяжении всей статьи поведение, отличающееся между двумя поверхностями, отмечается в заметках «только для CLI» и «только для облачных агентов». Всё, что не отмечено, относится к обеим. ## Местоположение крючков Места, где запускаются крючки и где можно хранить конфигурационные файлы крючков, зависят от поверхности: * **Второй пилот CLI** — крючки запускаются на локальной машине разработчика в той же оболоке, что и CLI. Все события с крючками, описанные в этой статье, поддерживаются CLI. Крючки загружаются из следующих источников в порядке (policy, затем user, project и плагины) и объединяются. Когда одно и то же событие появляется в нескольких источниках, выполняются все записи хуков из всех источников. * **Файлы крючков на уровне политики** — JSON-файлы в платформенном каталоге политик, загруженных в алфавитном порядке. Крючки полисов работают по всей машине и загружаются раньше всех остальных крючков. Их нельзя отключить и `disableAllHooks` они доступны независимо от состояния доверия папок. См. [раздел «Крючки по политике](#policy-hooks) » ниже. * **Hook на уровне репозитория —**`.github/hooks/*.json` в корне репозитория. * **Файлы хуков на уровне** пользователя — `*.json` файлы в каталоге hooks на уровне пользователя. По умолчанию это `~/.copilot/hooks/` на macOS и Linux или `%USERPROFILE%\.copilot\hooks\` на Windows. Если `COPILOT_HOME` установлено, то это .`$COPILOT_HOME/hooks/` * **Встроенный `hooks` блок в настройках репозитория** — `hooks` поле на верхнем уровне ( `.github/copilot/settings.json` Git committed) или `.github/copilot/settings.local.json` (обычно gitignore и пользователю) в репозитории. Также читаются кросс-инструменты `.claude/settings.json` и `.claude/settings.local.json` файлы в репозитории. * **Встроенный `hooks` блок в пользовательской конфигурации** — `hooks` поле на верхнем уровне `~/.copilot/settings.json`. * **Крючки, добавленные установленными плагинами** — объявленные каждым плагином в отдельном `hooks.json` (или ниже `hooks/hooks.json`) в каталоге установки плагина. * **Copilot облачный агент** — крючки работают внутри эфемерной песочницы Linux, которая предоставляет облачные агенты для каждой задачи. Песочница неинтерактивна, имеет ограниченную сеть и уничтожается после завершения работы. Подмножество событий срабатывает, и признаются только `bash` (или `command`) записи. Конфигурация крючка загружается из `.github/hooks/*.json` файлов в клонированном репозитории. ### Политические крючки > \[!NOTE] > **Второй пилот CLI Только.** Политические крючки не поддерживаются в разделе Copilot облачный агент. Крючки политики — это хуки для всей машины, загружаемые администраторами. Они загружаются раньше всех остальных хуков и не могут быть отключены .`disableAllHooks` Политические зацепки можно найти из двух источников: * **Файловая система**: JSON-файлы в платформенном каталоге политик, загруженных в алфавитном порядке: * Linux/macOS: `/etc/github-copilot/policy.d/*.json` * Виндовс: `C:\ProgramData\GitHub\Copilot\policy.d\*.json` * **Windows Реестр**: Значения под `HKLM\Software\Policies\GitHub\Copilot` (каждый подключ содержит значение `Policy` REG\_SZ с JSON-политикой). Файлы крючков политики используют тот же формат конфигурации хуков, что и пользовательские и проектные хуки (`{ "version": 1, "hooks": { ... } }`). В системах POSIX файлы политики должны принадлежать root и не подлежать групповому или мировому записыванию. Крючки политики предназначены для использования корпоративными ИТ-администраторами и требуют повышенных прав для установки. Конечные пользователи не могут их изменять. ## Среда выполнения облачных агентов Этот раздел **применяется только кCopilot облачный агент** В нём описываются ограничения, влияющие на то, как вы пишете скрипты hook и настраиваете записи hook для заданий облачных агентов. | Недвижимость | Ценность | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Операционная система | Linux. Учитывается только поле `bash` командных крюков; `powershell` записи игнорируются. Кросс-платформенное `command` поле считается запасным вариантом. | | Рабочий каталог | | | `/workspace` когда репозиторий клонируется, иначе `/root`. Используйте этот путь при установке `cwd` записи hook или при ссылке на файлы из скрипта. | | | Filesystem | Эфемерно. Файлы, написанные с помощью hooks (логи, CSV, транскрипты), выбрасываются после окончания работы. Чтобы сохранить выход крючка, отправьте его через `http` вход с крючком. | | Исходящая сеть | Ограничен файрволом облачных агентов. По умолчанию доступны только имена хостов GitHub и Copilot; чтобы получить доступ к любому другому хосту (например, `https://hooks.example.com`), требуется правило разрешения межсетевого экрана, настроенное администратором. | | Доступные переменные среды | | | `GITHUB_COPILOT_API_TOKEN` и `GITHUB_COPILOT_GIT_TOKEN` происходят в песочнице. | | | `COPILOT_AGENT_PROMPT` удерживает подсказку, с которой была вызвана работа. | | | `HOME` установлена на `/root`, поэтому любой скрипт крюка, разрешающий `~/...` пути, записывает в эфемерную песочницу. | | | `GITHUB_TOKEN` не задан. | | | Интерактивность | Полностью неинтерактивный. Агент работает с заранее предоставленными всеми разрешениями инструментов, поэтому не отображаются диалоги разрешений и уведомления не появляются пользователю. | | Обнаружение конфигурации | В задании облачного агента по умолчанию существует единственная конфигурация крючка, которая `.github/hooks/*.json` существует внутри клонированного репозитория. Песочница не поставляется с пользовательскими hook-файлами, `settings.json`, `config.json`, или установленными плагинами. | ## Формат конфигурации крючка Конфигурационные файлы крючка используют формат JSON с версией `1`. ### Командные крючки Командные хуки запускают shell-скрипты и поддерживаются на всех типах хуков. > \[!NOTE] > **Только облачный агент.** Облачный агент запускает крючки в песочнице Linux. Признаётся только поле `bash` ; `powershell` заявки игнорируются. Кросс-платформенное `command` поле считается запасным вариантом. ```json { "version": 1, "hooks": { "preToolUse": [ { "type": "command", "bash": "your-bash-command", "powershell": "your-powershell-command", "cwd": "optional/working/directory", "env": { "VAR": "value" }, "timeoutSec": 30 } ] } } ``` | Поле | Type | Обязательный | Description | | ------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bash` | string | Одно из значений `bash`, `powershell` или `command`. | Команда shell для Unix. | | `command` | string | Одно из значений `bash`, `powershell` или `command`. | Кроссплатформенный запасной вариант. Скопировано в обе `bash` сферы и `powershell` когда эти поля отсутствуют; явные `bash` или `powershell` записи имеют приоритет на соответствующих платформах. | | `cwd` | string | Нет | Рабочая папка для команды (относительно корня репозитория или абсолюта). | | `env` | object | Нет | Переменные среды для установки (поддерживает расширение переменных). | | `powershell` | string | Одно из значений `bash`, `powershell` или `command`. | Команда shell для Windows. | | `timeout` | Номер | Нет | Псевдоним для `timeoutSec`, за секунды. Используется только при `timeoutSec` отсутствии; `timeoutSec` имеет приоритет, когда присутствуют оба варианта. | | `timeoutSec` | Номер | Нет | Время ожидания в секундах. По умолчанию: `30`. | | `type` | `"command"` | Нет | Тип крюка. По умолчанию `"command"` — когда его опускают. | ### HTTP-крючки HTTP-хуки отправляют входную полезность в виде JSON `POST` на URL. > \[!NOTE] > > * По умолчанию разрешены только `https://` URL. Запросы, не входящие в TLS `http://` , отклоняются, за `http://localhost`исключением , `http://127.*`, и `http://[::1]` когда `COPILOT_HOOK_ALLOW_LOCALHOST=1` установлен. > * **Только облачный агент.** Исходящая сеть из песочницы ограничена межсетевым экраном облачного агента, поэтому `url` должна нацелиться на хост, указанный в списке разрешений. ```json { "version": 1, "hooks": { "postToolUse": [ { "type": "http", "url": "https://hooks.example.com/copilot", "headers": { "X-Source": "copilot-cli" }, "allowedEnvVars": ["GITHUB_TOKEN"], "timeoutSec": 30 } ] } } ``` | Поле | Type | Обязательный | Description | | ---------------- | --------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowedEnvVars` | string\[] | Нет | Имена переменных среды, которые могут быть расширены внутри `headers` значений. Когда установлен, `url` нужно использовать `https://`. | | `headers` | object | Нет | Запросите заголовки для включения. | | `timeout` | Номер | Нет | Псевдоним для `timeoutSec`, за секунды. Используется только при `timeoutSec` отсутствии; `timeoutSec` имеет приоритет, когда присутствуют оба варианта. | | `timeoutSec` | Номер | Нет | Время ожидания в секундах. По умолчанию: `30`. | | `type` | `"http"` | Да | Этот параметр должен содержать значение `"http"`. | | `url` | string | Да | Целевой URL-адрес. Обязательно использовать `http:` или `https:`. Для `preToolUse` и `permissionRequest`, обязательно использовать `https://` , потому что ответ может предоставлять разрешения инструментам. | ### Подсказочные зацепки Подсказочные крючки автоматически отправляют текст так, будто его написал сам пользователь. Они поддерживаются только на `sessionStart`. Текст может быть подсказкой на естественном языке или командой слэша. > \[!NOTE] > **Второй пилот CLI Только.** Подсказки **запускают только для новых интерактивных сессий**. Они не срабатывают при возобновлении и не срабатывают в неинтерактивном режиме запросов (`-p`). > \[!NOTE] > **Облачный агент.** Задания облачных агентов выполняются неинтерактивно (аналогично `-p`), поэтому `prompt` записи с крючками могут не срабатывать. Проверьте поведение в своей среде, прежде чем полагаться на них. ```json { "version": 1, "hooks": { "sessionStart": [ { "type": "prompt", "prompt": "Your prompt text or /slash-command" } ] } } ``` | Поле | Type | Обязательный | Description | | -------- | ---------- | ------------ | -------------------------------------------------------------------------------------- | | `type` | `"prompt"` | Да | Этот параметр должен содержать значение `"prompt"`. | | `prompt` | string | Да | Текст для отправки — это может быть сообщение на естественном языке или команда слэша. | ## События с крючками В таблице ниже перечислены все поддерживаемые события. **Столбец «Облачный агент**» показывает, срабатывает ли событие под облачным агентом, и отмечает различия в поведении. | Событие | Срабатывает, когда | Обработка выхода | Облачный агент | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agentStop` | Главный агент завершает ход. | Да — может блокировать и заставлять продолжение. | Пожары. | | `decision: "block"` заставляет делать ещё один ход, который всё равно учитывается в тайм-ауте работы. | | | | | `errorOccurred` | Ошибка возникает во время выполнения. | Нет | Пожары. | | `notification` | Срабатывает асинхронно, когда CLI отправляет системное уведомление (завершение оболочки, завершение работы агента или простоя, запросы разрешения, диалоги вызова). Удар и забыть: никогда не блокирует сессию. Поддерживает `matcher` regex на `notification_type`. | Опционально — можно вводить `additionalContext` в сессию. | | | **Не стреляет.** Облачный агент не отображает уведомления пользователю (см. строку **интерактивности** в таблице среды выполнения облачных агентов выше). | | | | | `permissionRequest` | Срабатывает до запуска сервиса разрешений (движок правил, утверждение сессии, авторазрешение/автозапрет и подсказка пользователя). Если выход объединённого крючка возвращается `behavior: "allow"` или `"deny"`, это решение приводит к короткому замыканию нормального потока разрешений. Поддерживает `matcher` regex на `toolName`. | Да — можно разрешить или отклонить программно. | Вызовы инструментов предварительно одобрены, поэтому этот крюк либо не срабатывает, либо не действует. Используйте `preToolUse` для принятия решений по разрешению. | | `postToolUse` | После успешного завершения каждого инструмента. | Да — можно изменить результат инструмента или добавить дополнительный контекст для модели. | Пожары. | | `postToolUseFailure` | После того, как инструмент завершается с неудачей. | Да — может предоставить навигацию по восстановлению через `additionalContext` (код `2` выхода для командных хуков). | Пожары. | | `preCompact` | Вот-вот начнётся уплотнение контекста (ручное или автоматическое). Поддерживают `matcher` фильтрацию по триггерам (`"manual"` или `"auto"`). | Нет — только уведомление. | Огонь только с `trigger: "auto"`. Нет пользователя, который бы запросил ручное уплотнение. | | `preToolUse` | Перед тем, как каждый инструмент сработает. | Да — можно разрешать, отрицать или изменять. | Пожары. Решение считается `"ask"` так `"deny"` , что нет доступного пользователя для ответа. | | `sessionEnd` | Сессия заканчивается. | Нет | Пожары — один раз за работу. | | `reason` обычно `"complete"`, `"error"`, или `"timeout"`; `"abort"` и `"user_exit"` не ожидаются, потому что пользователя нет. | | | | | `sessionStart` | Начинается новая или возобновлённая сессия. | Опционально — можно вводить `additionalContext` в сессию. | Уволяется один раз за каждую работу, как новая сессия (не резюме). См. примечание Prompt hooks выше для поведения `prompt` записей в облачном агенте. | | `subagentStart` | Появляется субагент (до его запуска). Поддерживает `matcher` фильтрацию по имени агента. | Опционально — не может блокировать создание, но `additionalContext` предшествует подсказке субагента. | Пожары. | | `subagentStop` | Субагент завершает. | Да — может блокировать и заставлять продолжение. | Пожары. | | `userPromptSubmitted` | Пользователь отправляет запрос. | Нет | Срабатывает максимум один раз — по запросу, который подают на работу. Нет никакого дополнительного ввода пользователя. | ## Полезные нагрузки для ввода событий hook Каждое событие с крючком доставляет JSON-полезную нагрузку обработчику крючков. Поддерживаются два формата полезной нагрузки, выбираемых по имени события, используемому в конфигурации крючка: * **camelCase format** — Настройте имя события в camelCase (например, `sessionStart`). Поля используют CamelCase. * **VS Code совместимый формат** — Настройте имя события в PascalCase (например, `SessionStart`). Поля используют snake\_case для соответствия VS CodeCopilot формату расширения. ### `sessionStart` / `SessionStart` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; // Unix timestamp in milliseconds cwd: string; source: "startup" | "resume" | "new"; initialPrompt?: string; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "SessionStart"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; source: "startup" | "resume" | "new"; initial_prompt?: string; } ``` ### `sessionEnd` / `SessionEnd` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "SessionEnd"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; } ``` ### `userPromptSubmitted` / `UserPromptSubmit` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; prompt: string; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "UserPromptSubmit"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; prompt: string; } ``` ### `preToolUse` / `PreToolUse` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; } ``` \*\* VS Code Совместимый вход:\*\* При настройке с именем `PreToolUse`события PascalCase полезная нагрузка использует snake\_case имена полей, чтобы соответствовать формату VS CodeCopilot расширения: ```typescript { hook_event_name: "PreToolUse"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; // Tool arguments (parsed from JSON string when possible) } ``` > \[!IMPORTANT] > **Поведение при отказе команд против HTTP для `preToolUse`:** Командные `preToolUse` хуки **закрываются —** сбой или ненулевой выход лишает вызов инструмента. HTTP-хуки `preToolUse` — это **fail-open** — сетевая ошибка, тайм-аут или ответ, не входящий в 2xx, попадают в стандартный поток разрешений. Выберите вариант, который соответствует вашим требованиям безопасности. ### `postToolUse` / `PostToolUse` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; toolResult: { resultType: "success"; textResultForLlm: string; } } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "PostToolUse"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; tool_result: { result_type: "success"; text_result_for_llm: string; } } ``` ### `postToolUseFailure` / `PostToolUseFailure` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; toolName: string; toolArgs: unknown; error: string; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "PostToolUseFailure"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; tool_name: string; tool_input: unknown; error: string; } ``` ### `agentStop` / `Stop` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; stopReason: "end_turn"; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "Stop"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; stop_reason: "end_turn"; } ``` ### `subagentStart` > \[!NOTE] > Встроенный `general-purpose` агент не излучает `subagentStart` события `subagentStop` или эмит. **Входные данные:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; agentName: string; agentDisplayName?: string; agentDescription?: string; } ``` ### `subagentStop` / `SubagentStop` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; agentName: string; agentDisplayName?: string; stopReason: "end_turn"; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "SubagentStop"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; agent_name: string; agent_display_name?: string; stop_reason: "end_turn"; } ``` ### `errorOccurred` / `ErrorOccurred` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; error: { message: string; name: string; stack?: string; }; errorContext: "model_call" | "tool_execution" | "system" | "user_input"; recoverable: boolean; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "ErrorOccurred"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; error: { message: string; name: string; stack?: string; }; error_context: "model_call" | "tool_execution" | "system" | "user_input"; recoverable: boolean; } ``` ### `preCompact` / `PreCompact` **Ввод CamelCase:** ```typescript { sessionId: string; timestamp: number; cwd: string; transcriptPath: string; trigger: "manual" | "auto"; customInstructions: string; } ``` \*\* VS Code Совместимый вход:\*\* ```typescript { hook_event_name: "PreCompact"; session_id: string; timestamp: string; // ISO 8601 timestamp cwd: string; transcript_path: string; trigger: "manual" | "auto"; custom_instructions: string; } ``` ## `preToolUse` Контроль принятия решений Крюк `preToolUse` может управлять выполнением инструмента, записывая JSON-объект в stdout. | Поле | Ценности | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `permissionDecision` | | | | `"allow"`, , `"deny"``"ask"` | Работает ли инструмент. Пустой выход использует стандартное поведение. В облачном агенте `"ask"` рассматривается как `"deny"` отсутствие доступного пользователя для ответа. | | | `permissionDecisionReason` | string | Агенту показали разум. Требуется при принятии решения `"deny"`. | | `modifiedArgs` | object | Замените аргументы инструментов вместо оригиналов. | ## `agentStop`/ `subagentStop` Контроль принятия решений | Поле | Ценности | Description | | ------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------- | | `decision` | | | | `"block"`, `"allow"` | | | | `"block"` заставляет другого агента поступить, используя `reason` это как подсказку. | | | | `reason` | string | Подсказка для следующего хода, когда `decision` .`"block"` | ## `postToolUse` Выход Крючок `postToolUse` может изменять результат инструмента или добавить дополнительный контекст для модели, записывая JSON-объект в stdout. ```typescript { modifiedResult?: { resultType: "success"; textResultForLlm: string; }; additionalContext?: string; } ``` | Поле | Type | Description | | ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `modifiedResult` | object | Результат замены инструмента. Должно быть.`resultType: "success"` Если вернуть с `resultType: "failure"`, отказ идёт вниз по течению и `postToolUseFailure` стреляет следующим. | | `additionalContext` | string | Добавлено дополнительное руководство `textResultForLlm` , чтобы модель видела его после вывода инструмента на том же ходе. Когда несколько хуков возвращаются `additionalContext`, результат соединяется двойной новой строкой и ограничивается 10 КБ. | Возврат `{}` или очистка выхода, чтобы сохранить исходный успешный результат. > \[!NOTE] > `modifiedResult` отмечается как программными хуками SDK, так и командными/HTTP-конфигурационными `postToolUse` хуками. ## `permissionRequest` Контроль принятия решений > \[!NOTE] > **Второй пилот CLI Только.** Крючок `permissionRequest` не применяется в Copilot облачный агент— вызовы инструментов там предварительно одобрены (см. строку **интерактивности** в таблице среды исполнения облачных агентов). Используйте `preToolUse` для принятия решений по разрешению в облачном агенте. `permissionRequest` Крюк срабатывает до запуска сервиса разрешений — до проверки правил, одобрения сессии, авторазрешения/автозапрета и подсказки пользователя. Если крючки возвращаются `behavior: "allow"` или `"deny"`, это решение приводит к короткому замыканию нормального потока разрешений. Возврат ничего не выходит на обычную обработку разрешений. Используйте его для программного одобрения или отклонения вызовов инструментов — особенно полезно в режиме CLI pipe (`-p`) и других CLI CI, где нет интерактивного запроса. Это не относится к облачному агенту. Все настроенные `permissionRequest` крючки работают для каждого запроса (кроме `read` типов `hook` с разрешениями, которые срабатывают перед хуками). Выходы крючка объединяются с более поздними выходами хука, переопределяя более ранние. **Матчер:** Необязательный регулярный выражение, тестируемое против `toolName`. Закрепленное как `^(?:pattern)$`; должно совпадать с полным именем инструмента. При установке крюк срабатывает только при совпадающих названиях инструментов. Выводите JSON в stdout, чтобы контролировать решение о разрешении: | Поле | Ценности | Description | | ------------------- | --------------------------------------- | --------------------------------------------------------------- | | `behavior` | | | | `"allow"`, `"deny"` | Одобрить или отклонить этот инструмент. | | | `message` | string | Причина возвращалась к LLM при отказе. | | `interrupt` | boolean | В `true` сочетании с `"deny"`, агент полностью останавливается. | Вернуть пустой выход или `{}` провалиться в нормальный поток разрешений. Для командных хуков выходной код `2` рассматривается как отказ; stdout JSON (если он есть) объединяется с `{"behavior":"deny"}`, а stderr игнорируется. ## `notification` Крюк > \[!NOTE] > **Второй пилот CLI Только.** `notification` Крюк не стреляет под Copilot облачный агент. `notification` Крюк срабатывает асинхронно, когда CLI издаёт системное уведомление. Эти хуки — это система «убери и забудь»: они никогда не блокируют сессию, а любые ошибки фиксируются и пропускаются. **Входные данные:** ```typescript { sessionId: string; timestamp: number; cwd: string; hook_event_name: "Notification"; message: string; // Human-readable notification text title?: string; // Short title (e.g., "Permission needed", "Shell completed") notification_type: string; // One of the types listed below } ``` **Типы уведомлений:** | Type | Когда он срабатывает | | -------------------------- | ----------------------------------------------------------------------------------- | | `shell_completed` | Заканчивается фоновая (асинхронная) команда shell | | `shell_detached_completed` | Завершается отделённая оболочная сессия | | `agent_completed` | Фоновый субагент заканчивает (выполнен или неудачно) | | `agent_idle` | Агент фона заканчивает ход и переходит в состояние простоя (ожидание `write_agent`) | | `permission_prompt` | Агент запрашивает разрешение на запуск инструмента | | `elicitation_dialog` | Агент запрашивает дополнительную информацию у пользователя | **Output:** ```typescript { additionalContext?: string; // Injected into the session as a user message } ``` Если `additionalContext` он возвращается, текст вводится в сессию в виде предварительного пользовательского сообщения. Это может запустить дальнейшую обработку агентов, если сессия находится в простое. Возврат `{}` или опустошение выхода, чтобы не предпринимать действия. **Матчер:** Опциональный регуляр на `notification_type`. Паттерн закреплён как `^(?:pattern)$`. Опустите `matcher` все типы уведомлений. ## Фильтрация матчеров Несколько событий принимают необязательный `matcher` регулярный выражений на каждом записи крюка, который фильтрует и вызывает срабатывание хука. Узор закреплён как `^(?:matcher)$` и должен соответствовать полному значению. Некорректные регексы приводят к пропуску записи с крюком. \| Событие | `matcher` против него встречается | \|-------|------------------------------| \| `notification` | `notification_type` | \| `permissionRequest` | `toolName` | \| `preCompact` | `trigger` (`"manual"` или `"auto"`) | \| `preToolUse` | `toolName` | \| `subagentStart` | `agentName` | ## Имена инструментов для подбора крючков | Имя инструмента | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `ask_user` | Задайте пользователю уточняющий вопрос. В облачном агенте нет пользователя, поэтому `ask_user` не даёт полезного результата. | | `bash` | Выполнять команды оболочки (Unix). | | `create` | Создавайте новые файлы. | | `edit` | Изменять содержимое файла. | | `glob` | Ищите файлы по шаблону. | | `grep` | Поиск по содержимому файла. | | `powershell` | Выполнять команды shell (Windows). Не отображается в облачном агенте (песочница Linux). | | `task` | Запускайте задачи субагентов. | | `view` | Чтение содержимого файла. | | `web_fetch` | Загружайте веб-страницы. | Если настраивать несколько хуков одного типа, они выполняются по порядку. Для `preToolUse`, если какой-либо крюк возвращается `"deny"`, инструмент блокируется. Для большинства событий сбои крючка (ненулевые коды выхода, кроме `2`, или тайм-ауты) фиксируются и пропускаются. **Исключение: `preToolUse` является fail-closed** — авария, ненулевой выход (кроме выхода 2), или тайм-аут отклоняет вызов инструмента, а не позволяет его безмолвно. ## Коды выхода для командных крючков | Код выхода | Значение | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `0` | Успех. | | `stdout` парсируется как выходной JSON для хука, если он присутствует. | | | `2` | По умолчанию это воспринимается как предупреждение. | | `stderr` показывают пользователю, но забег продолжается. Для `permissionRequest`, выход `2` рассматривается как `{"behavior":"deny"}` , и любой `stdout` JSON объединяется. Для , выход `postToolUseFailure` рассматривается как `2` и `additionalContext` добавляется к неудаче, `stdout`показанному агенту. | | | Другие ненулевые значения | Зарегистрировано как сбой с крюком. Запуск продолжается (fail-open). | | **Исключение: `preToolUse` является fail-closed** — ненулевой выход (кроме выхода 2) отклоняет вызов инструмента с `"Denied by preToolUse hook (hook errored)"`. | | | Timeout | Убит после `timeoutSec`. Ошибка зафиксирована, агент продолжает. | | **Исключение: `preToolUse` fail-closed** — тайм-аут отклоняет вызов инструмента. | | Для большинства событий ненулевые выходы и тайм-ауты фиксируются и пропускаются — работа агента продолжается. `preToolUse` Исключение: ошибки, сбои и тайм-ауты блокируют вызов инструмента, а не позволяют его молчаливо. Это предотвращает обход хрупкого крючка, когда вход крюка вызывает неожиданный сбой. Выход 2 обрабатывается по правилам выше и не блокирует выполнение. ## Отключить все крючки Используйте `disableAllHooks` его, когда хотите сохранить конфигурацию крючка на диске, но остановить её работу — например: * Отладка проблемы — и вы хотите убедиться, что причиной является крючок, не удаляя конфигурацию. * Приостановка автоматизации во время чувствительной задачи (обзор кода, ветка выпуска, работа с секретами) без потери настройки. (**Второй пилот CLI только.**) * Отправка файла hooks в системе контроля версий, от которого участники могут отказаться локально, установив эту опцию в своём репозитории `settings.json`. (**Второй пилот CLI только.**) * Временное отключение медленных или шумных хуков во время интерактивной сессии. (**Второй пилот CLI только.**) Установите `disableAllHooks` верхний `true` уровень, чтобы пропускать все крючки в файле без удаления. ```json { "version": 1, "disableAllHooks": false, "hooks": { "preToolUse": [ /* hook entries */ ] } } ``` Поведение зависит от того, где вы устанавливаете флаг: * **Внутри одного `.github/hooks/*.json` файла** пропускаются только объявленные крючки. Удостоен уважения от обоих Второй пилот CLI и Copilot облачный агент. * **На верхнем уровне репозитория `settings.json`** — **Второй пилот CLI только.** Каждый хук из каждого источника (файлы репозитория, пользовательские файлы, плагины и встроенные блоки хуков) пропускается для сессий в этом репозитории. Политические крючки не затронуты и продолжают работать. Облачный агент не загружается `settings.json`. ## Дополнительные материалы * [Использование крючков с интерфейс командной строки GitHub Copilot](/ru/copilot/how-tos/copilot-cli/use-hooks) * [Ссылка на крючки GitHub Copilot](/ru/copilot/reference/hooks-configuration) * [Справочник команды GitHub Copilot CLI](/ru/copilot/reference/copilot-cli-reference/cli-command-reference) * [Концепции облачного агента GitHub Copilot](/ru/copilot/concepts/agents/cloud-agent)