Ссылка на крючки GitHub Copilot CLI

Хуки — это внешние команды, которые выполняются в определённых жизненных точках сессии, обеспечивая индивидуальную автоматизацию, управление безопасностью и интеграции. Файлы конфигурации крюков загружаются автоматически из .github/hooks/*.json вашего репозитория.

Формат конфигурации крючка

Конфигурационные файлы крючка используют формат JSON с версией 1.

Командные крючки

Командные хуки запускают shell-скрипты и поддерживаются на всех типах хуков.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "your-bash-command",
        "powershell": "your-powershell-command",
        "cwd": "optional/working/directory",
        "env": { "VAR": "value" },
        "timeoutSec": 30
      }
    ]
  }
}

Поле	Тип	Обязательный	Description
bash	string	Один из bash/powershell	Команда shell для Unix.
cwd	string	Нет	Рабочая папка для команды (относительно корня репозитория или абсолюта).
env	object	Нет	Переменные среды для установки (поддерживает расширение переменных).
powershell	string	Один из bash/powershell	Команда shell для Windows.
timeoutSec	число/номер	Нет	Время ожидания в секундах. По умолчанию: 30.
type	"command"	Да	Этот параметр должен содержать значение "command".

Подсказочные зацепки

Подсказочные крючки автоматически отправляют текст так, будто его написал сам пользователь. Они поддерживаются только на sessionStart новых интерактивных сессиях и запускаются только для новых интерактивных сессий. Они не срабатывают при возобновлении и не срабатывают в неинтерактивном режиме запросов (-p). Текст может быть подсказкой на естественном языке или командой слэша.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

Поле	Тип	Обязательный	Description
type	"prompt"	Да	Этот параметр должен содержать значение "prompt".
prompt	string	Да	Текст для отправки — это может быть сообщение на естественном языке или команда слэша.

События с крючками

Событие	Срабатывает, когда	Обработка выхода
agentStop	Главный агент завершает ход.	Да — может блокировать и заставлять продолжение.
errorOccurred	Ошибка возникает во время выполнения.	Нет
notification	Срабатывает асинхронно, когда CLI отправляет системное уведомление (завершение оболочки, завершение работы агента или простоя, запросы разрешения, диалоги вызова). Удар и забыть: никогда не блокирует сессию. Поддерживает matcher regex на notification_type.	Опционально — можно вводить additionalContext в сессию.
permissionRequest	Срабатывает до запуска сервиса разрешений (движок правил, утверждение сессии, авторазрешение/автозапрет и подсказка пользователя). Если выход объединённого крючка возвращается behavior: "allow" или "deny", это решение приводит к короткому замыканию нормального потока разрешений. Поддерживает matcher regex на toolName.	Да — можно разрешить или отклонить программно.
postToolUse	После успешного завершения каждого инструмента.	Да — можно заменить успешный результат (только программные хуки SDK).
postToolUseFailure	После того, как инструмент завершается с неудачей.	Да — может предоставить навигацию по восстановлению через additionalContext (код 2 выхода для командных хуков).
preCompact	Вот-вот начнётся уплотнение контекста (ручное или автоматическое). Поддерживают matcher фильтрацию по триггерам ("manual" или "auto").	Нет — только уведомление.
preToolUse	Перед тем, как каждый инструмент сработает.	Да — можно разрешать, отрицать или изменять.
sessionEnd	Сессия заканчивается.	Нет
sessionStart	Начинается новая или возобновлённая сессия.	Нет
subagentStart	Появляется субагент (до его запуска). Возвраты additionalContext предшествуют запросу субагента. Поддерживает matcher фильтрацию по имени агента.	Нет — нельзя блокировать создание.
subagentStop	Субагент завершает.	Да — может блокировать и заставлять продолжение.
userPromptSubmitted	Пользователь отправляет запрос.	Нет

Полезные нагрузки для ввода событий hook

Каждое событие с крючком доставляет JSON-полезную нагрузку обработчику крючков. Поддерживаются два формата полезной нагрузки, выбираемых по имени события, используемому в конфигурации крючка:

• camelCase format — Настройте имя события в camelCase (например, sessionStart). Поля используют CamelCase.

---

          VS Code совместимый формат** — Настройте имя события в PascalCase (например, `SessionStart`). Поля используют snake_case для соответствия VS CodeCopilot формату расширения.

sessionStart / SessionStart

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

          **
          VS Code Совместимый вход:**

{
    hook_event_name: "SessionStart";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    source: "startup" | "resume" | "new";
    initial_prompt?: string;
}

sessionEnd / SessionEnd

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

          **
          VS Code Совместимый вход:**

{
    hook_event_name: "SessionEnd";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

userPromptSubmitted / UserPromptSubmit

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

          **
          VS Code Совместимый вход:**

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

preToolUse / PreToolUse

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
}

          **
          VS Code Совместимый вход:**

При настройке с именем PreToolUseсобытия PascalCase полезная нагрузка использует snake_case имена полей, чтобы соответствовать формату VS CodeCopilot расширения:

{
    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)
}

postToolUse / PostToolUse

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

          **
          VS Code Совместимый вход:**

{
    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" | "failure" | "denied" | "error";
        text_result_for_llm: string;
    }
}

postToolUseFailure / PostToolUseFailure

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

          **
          VS Code Совместимый вход:**

{
    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:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

          **
          VS Code Совместимый вход:**

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

subagentStart

          **Входные данные:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

subagentStop / SubagentStop

          **Ввод CamelCase:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

          **
          VS Code Совместимый вход:**

{
    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:**

{
    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 Совместимый вход:**

{
    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:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

          **
          VS Code Совместимый вход:**

{
    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"` | Работает ли инструмент. Пустой выход использует стандартное поведение. |

| permissionDecisionReason | string | Агенту показали разум. Требуется при принятии решения "deny". | | modifiedArgs | object | Замените аргументы инструментов вместо оригиналов. |

          `agentStop`
           / 
          `subagentStop` Контроль принятия решений

Поле	Ценности	Description
decision

          `"block"`, `"allow"` | 
          `"block"` заставляет другого агента поступить, используя `reason` это как подсказку. |

| reason | string | Подсказка для следующего хода, когда decision ."block" |

          `permissionRequest` Контроль принятия решений

          `permissionRequest` Крюк срабатывает до запуска сервиса разрешений — до проверки правил, одобрения сессии, авторазрешения/автозапрета и подсказки пользователя. Если крючки возвращаются `behavior: "allow"` или `"deny"`, это решение приводит к короткому замыканию нормального потока разрешений. Возврат ничего не выходит на обычную обработку разрешений. Используйте его для программного одобрения или отклонения вызовов инструментов — особенно полезно в режимах pipe (`-p`) и 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` Крюк

          `notification` Крюк срабатывает асинхронно, когда CLI издаёт системное уведомление. Эти хуки — это система «убери и забудь»: они никогда не блокируют сессию, а любые ошибки фиксируются и пропускаются.

          **Входные данные:**

{
    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
}

          **Типы уведомлений:**

Тип	Когда он срабатывает
shell_completed	Заканчивается фоновая (асинхронная) команда shell
shell_detached_completed	Завершается отделённая оболочная сессия
agent_completed	Фоновый субагент заканчивает (выполнен или неудачно)
agent_idle	Агент фона заканчивает ход и переходит в состояние простоя (ожидание write_agent)
permission_prompt	Агент запрашивает разрешение на запуск инструмента
elicitation_dialog	Агент запрашивает дополнительную информацию у пользователя

          **Выходные данные:**

{
    additionalContext?: string; // Injected into the session as a user message
}

Если additionalContext он возвращается, текст вводится в сессию в виде предварительного пользовательского сообщения. Это может запустить дальнейшую обработку агентов, если сессия находится в простое. Возврат {} или опустошение выхода, чтобы не предпринимать действия.

          **Матчер:** Опциональный регуляр на `notification_type`. Паттерн закреплён как `^(?:pattern)$`. Опустите `matcher` все типы уведомлений.

Имена инструментов для подбора крючков

Имя инструмента	Description
ask_user	Задайте пользователю уточняющий вопрос.
bash	Выполнять команды оболочки (Unix).
create	Создавайте новые файлы.
edit	Изменять содержимое файла.
glob	Ищите файлы по шаблону.
grep	Поиск по содержимому файла.
powershell	Выполнять команды shell (Windows).
task	Запускайте задачи субагентов.
view	Чтение содержимого файла.
web_fetch	Загружайте веб-страницы.

Если настраивать несколько хуков одного типа, они выполняются по порядку. Для preToolUse, если какой-либо крюк возвращается "deny", инструмент блокируется. Для командных хуков выход с кодом postToolUseFailure приводит к возврату stderr в качестве руководства 2 по восстановлению для помощника. Сбои с крючками (ненулевые коды выхода или тайм-ауты) фиксируются и пропускаются — они никогда не блокируют выполнение агентов.

Дополнительные материалы

• Использование крючков с GitHub Copilot CLI
• Конфигурация крючков
• Справочник команды GitHub Copilot CLI