GitHub Copilot CLI 후크 참조

          코파일럿 CLI에 대한 후크 이벤트, 구성 형식 및 입력 페이로드를 찾습니다.

이 기사에서

후크는 세션 중에 특정 수명 주기 지점에서 실행되는 외부 명령으로, 사용자 지정 자동화, 보안 제어 및 통합을 사용하도록 설정합니다. 후크 구성 파일은 리포지토리의 .github/hooks/*.json에서 자동으로 로드됩니다.

후크 구성 형식

후크 구성 파일은 버전 1이 있는 JSON 형식을 사용합니다.

명령 후크

명령 후크는 셸 스크립트를 실행하며 모든 후크 유형에서 지원됩니다.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "your-bash-command",
        "powershell": "your-powershell-command",
        "cwd": "optional/working/directory",
        "env": { "VAR": "value" },
        "timeoutSec": 30
      }
    ]
  }
}
분야유형필수Description
bashstring다음 중 하나 bash/powershellUnix에 대한 셸 명령입니다.
cwdstringNo명령에 대한 작업 디렉터리입니다(리포지토리 루트 또는 절대를 기준으로).
envobjectNo설정할 환경 변수(변수 확장 지원).
powershellstring다음 중 하나 bash/powershellWindows용 셸 명령입니다.
timeoutSec숫자No초 단위의 시간 제한입니다. 기본값: 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 | 예 | 제출할 텍스트는 자연어 메시지 또는 슬래시 명령일 수 있습니다. |

후크 이벤트

Event발생하는 경우처리된 출력
agentStop주 에이전트가 턴을 완료합니다.예 - 연속을 차단하고 강제 적용할 수 있습니다.
errorOccurred실행하는 동안 오류가 발생합니다.No
notificationCLI가 시스템 알림(셸 완료, 에이전트 완료 또는 유휴 상태, 권한 프롬프트, 유도 대화 상자)을 내보낸 경우 비동기적으로 발생합니다. Fire-and-forget: 세션을 차단하지 않습니다. 에서 regex를 지원합니다 matcher``notification_type.선택 사항 - additionalContext를 세션에 삽입할 수 있습니다.
permissionRequest권한 서비스가 실행되기 전에 트리거됩니다(규칙 엔진, 세션 승인, 자동 허용/자동 거부 및 사용자 확인). 병합된 후크 출력이 behavior: "allow" 또는 "deny"를 반환할 경우, 해당 결정은 일반 권한 흐름을 단락시킵니다. 에서 regex를 지원합니다 matcher``toolName.예 - 프로그래밍 방식으로 허용하거나 거부할 수 있습니다.
postToolUse각 도구가 성공적으로 완료된 후예 - 성공적인 결과를 바꿀 수 있습니다(SDK 프로그래밍 후크만 해당).
postToolUseFailure도구가 실패로 완료된 후예, additionalContext를 통해 복구 지침을 제공할 수 있으며, 명령 후크에 대한 종료 코드는 2입니다.
preCompact컨텍스트 압축이 시작됩니다(수동 또는 자동).
          `matcher`는 트리거 (`"manual"` 또는 `"auto"`)에 따라 필터링을 지원합니다. | 아니요 - 알림만 해당합니다. |

| preToolUse | 각 도구를 실행하기 전에. | 예 - 허용, 거부 또는 수정할 수 있습니다. | | sessionEnd | 세션이 종료됩니다. | No | | sessionStart | 새 세션 또는 다시 시작된 세션이 시작됩니다. | No | | subagentStart | 하위 에이전트가 생성됩니다(실행되기 전에). 서브에이전트 프롬프트 앞에 additionalContext가 추가되어 반환됩니다. 에이전트 이름으로 필터링하도록 지원합니다 matcher . | 아니요 - 만들기를 차단할 수 없습니다. | | subagentStop | 서브에이전트가 완료됩니다. | 예 - 연속을 차단하고 강제 적용할 수 있습니다. | | userPromptSubmitted | 사용자가 프롬프트를 제출합니다. | No |

후크 이벤트 페이로드 입력

각 후크 이벤트는 후크 처리기에 JSON 페이로드를 제공합니다. 후크 구성에 사용되는 이벤트 이름으로 선택한 두 개의 페이로드 형식이 지원됩니다.

  • camelCase 형식 - camelCase에서 이벤트 이름을 구성합니다(예: sessionStart). 필드는 camelCase를 사용합니다.
          VS Code 호환되는 형식** - PascalCase에서 이벤트 이름을 구성합니다(예: `SessionStart`). 필드는 확장 형식에 일치시키기 위해 snake_case를 사용합니다.

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 호환되는 입력:**

PascalCase 이벤트 이름으로 PreToolUse 구성된 경우, 페이로드는 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` 후크는 stdout에 JSON 개체를 작성하여 도구 실행을 제어할 수 있습니다.
분야가치들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"`을 반환하는 경우, 해당 결정은 정상적인 권한 흐름을 단락시킵니다. 아무 것도 반환하지 않는 것은 정상적인 권한 처리로 넘어갑니다. 이 도구를 사용하여 프로그래밍 방식으로 도구 호출을 승인하거나 거부합니다. 특히 대화형 프롬프트를 사용할 수 없는 파이프 모드(`-p`) 및 CI 환경에서 유용합니다.

구성된 permissionRequest 후크는 (후크 전에 단락하는 사용 권한 종류인 read 및 hook를 제외하고) 각 요청에 대해 실행됩니다. 후크 출력은 나중에 생성된 후크 출력이 이전 출력을 덮어쓰면서 병합됩니다.

          **Matcher:**`toolName`에 대해 테스트하는 선택적 정규식입니다. 
          `^(?:pattern)$`로 고정되며 도구의 전체 이름과 일치해야 합니다. 설정하면 후크는 일치하는 도구 이름에 대해서만 발생합니다.

권한 결정을 제어하기 위해 stdout에 JSON을 출력합니다.

분야가치들Description
behavior
          `"allow"`, `"deny"` | 도구 호출을 승인할지 또는 거부할지 여부입니다. |

| message | string | 거부 시 LLM에 피드백으로 제공되는 이유입니다. | | interrupt | 부울 | true가 "deny"와 결합되면, 에이전트가 완전히 중지됩니다. |

빈 출력을 반환하거나 {} 일반 권한 흐름으로 넘어갈 수 있습니다. 명령 후크의 경우, 종료 코드 2는 거절로 처리되며, stdout JSON(있는 경우)은 {"behavior":"deny"}으로 병합되고 stderr는 무시됩니다.

          `notification` 후크

CLI에서 notification 시스템 알림을 내보낸 경우 후크가 비동기적으로 실행됩니다. 이러한 후크는 일단 실행되면 추가 조작이 필요 없는 방식으로 작동합니다. 세션을 차단하지 않으며, 오류는 기록되고 건너뜁니다.

          **입력:**

{
    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_detached_completed분리된 셸 세션이 완료됨
agent_completed백그라운드 서브에이전트가 완료됨(완료됨 또는 실패됨)
agent_idle백그라운드 에이전트가 턴을 완료하고 유휴 상태로 전환됩니다(대기 중 write_agent).
permission_prompt에이전트가 도구를 실행할 수 있는 권한을 요청합니다.
elicitation_dialog에이전트가 사용자에게 추가 정보를 요청합니다.
          **출력:**

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

          `additionalContext` 반환되면 텍스트가 앞에 추가된 사용자 메시지로 세션에 삽입됩니다. 세션이 유휴 상태인 경우 추가 에이전트 처리를 트리거할 수 있습니다. 작업을 수행하지 않으려면 `{}` 또는 빈 출력을 반환하십시오.

          **Matcher:**`notification_type`에 대한 선택적인 정규식. 패턴은 다음과 같이 `^(?:pattern)$`고정됩니다. 모든 알림 유형을 수신하려면 `matcher`를 생략하십시오.

후크 일치를 위한 도구 이름

도구 이름Description
ask_user사용자에게 명확한 질문을 합니다.
bash셸 명령 실행(Unix).
create새 파일을 만듭니다.
edit파일 내용을 수정합니다.
glob패턴별로 파일을 찾습니다.
grep파일 콘텐츠를 검색합니다.
powershell셸 명령을 실행합니다(Windows).
task서브에이전트 작업을 실행합니다.
view파일 내용을 읽습니다.
web_fetch웹 페이지를 가져옵니다.

동일한 형식의 여러 후크가 구성된 경우 순서대로 실행됩니다. 의 경우 preToolUse후크가 반환 "deny"되면 도구가 차단됩니다. 명령 후크의 경우 postToolUseFailure 코드를 2 사용하여 종료하면 stderr가 도우미에 대한 복구 지침으로 반환됩니다. 후크 오류(0이 아닌 종료 코드 또는 시간 초과)는 로그에 기록되며 건너뜁니다. 이러한 오류는 에이전트 실행을 절대 차단하지 않습니다.

추가 읽기