Gemini CLI 후크

후크는 Gemini CLI가 에이전트 루프의 특정 지점에서 실행하는 스크립트 또는 프로그램으로, CLI의 소스 코드를 수정하지 않고도 동작을 가로채고 사용자 지정할 수 있습니다.

후크란 무엇인가요?

후크는 에이전트 루프의 일부로 동기적으로 실행됩니다. 후크 이벤트가 발생하면 Gemini CLI는 일치하는 모든 후크가 완료될 때까지 기다렸다가 계속 진행합니다.

후크를 사용하여 다음을 수행할 수 있습니다:

컨텍스트 추가: 모델이 요청을 처리하기 전에 관련 정보(예: git 기록)를 주입합니다.
작업 검증: 도구 인수를 검토하고 위험할 수 있는 작업을 차단합니다.
정책 시행: 보안 스캐너 및 규정 준수 검사를 구현합니다.
상호 작용 기록: 감사를 위해 도구 사용량 및 모델 응답을 추적합니다.
동작 최적화: 사용 가능한 도구를 동적으로 필터링하거나 모델 매개변수를 조정합니다.

시작하기

후크 작성 가이드: 포괄적인 예제와 함께 첫 번째 후크를 만드는 튜토리얼입니다.
모범 사례: 보안, 성능 및 디버깅에 대한 지침입니다.
후크 참조: I/O 스키마 및 종료 코드에 대한 확정적인 기술 사양입니다.

핵심 개념

후크 이벤트

후크는 Gemini CLI 수명 주기의 특정 이벤트에 의해 트리거됩니다.

이벤트	발생 시기	영향	일반적인 사용 사례
`SessionStart`	세션이 시작될 때 (시작, 재개, 지우기)	컨텍스트 주입	리소스 초기화, 컨텍스트 로드
`SessionEnd`	세션이 종료될 때 (종료, 지우기)	권고	정리, 상태 저장
`BeforeAgent`	사용자가 프롬프트를 제출한 후, 계획 전에	턴 / 컨텍스트 차단	컨텍스트 추가, 프롬프트 검증, 턴 차단
`AfterAgent`	에이전트 루프가 끝날 때	재시도 / 중단	출력 검토, 재시도 강제 또는 실행 중단
`BeforeModel`	LLM에 요청을 보내기 전	턴 차단 / 모의(Mock)	프롬프트 수정, 모델 교체, 모의 응답
`AfterModel`	LLM 응답을 받은 후	턴 차단 / 수정(Redact)	응답 필터링/수정, 상호 작용 기록
`BeforeToolSelection`	LLM이 도구를 선택하기 전	도구 필터링	사용 가능한 도구 필터링, 선택 최적화
`BeforeTool`	도구가 실행되기 전	도구 차단 / 재작성	인수 검증, 위험한 작업 차단
`AfterTool`	도구가 실행된 후	결과 차단 / 컨텍스트	결과 처리, 테스트 실행, 결과 숨기기
`PreCompress`	컨텍스트 압축 전	권고	상태 저장, 사용자에게 알림
`Notification`	시스템 알림이 발생할 때	권고	데스크톱 알림으로 전달, 로깅

전역 메커니즘

이러한 핵심 원칙을 이해하는 것은 견고한 후크를 구축하는 데 필수적입니다.

엄격한 JSON 요구 사항 ("황금률")

후크는 stdin(입력) 및 stdout(출력)을 통해 통신합니다.

침묵은 필수입니다: 스크립트는 최종 JSON 객체 외에 stdout에 어떠한 일반 텍스트도 출력해서는 안 됩니다. JSON 앞에 echo나 print 호출이 하나만 있어도 파싱이 중단됩니다.
오염 = 실패: stdout에 JSON이 아닌 텍스트가 포함되면 파싱이 실패합니다. CLI는 "Allow(허용)"를 기본값으로 설정하고 전체 출력을 systemMessage로 처리합니다.
Stderr를 통한 디버그: 모든 로깅 및 디버깅에는 stderr를 사용하세요(예: echo "debug" >&2). Gemini CLI는 stderr를 캡처하지만 JSON으로 파싱을 시도하지는 않습니다.

종료 코드

Gemini CLI는 종료 코드를 사용하여 후크 실행의 상위 수준 결과를 결정합니다:

종료 코드	레이블	행동 영향
0	성공	`stdout`이 JSON으로 파싱됩니다. 의도적인 차단(예: `{"decision": "deny"}`)을 포함한 모든 로직에 대해 선호되는 코드입니다.
2	시스템 차단	중대한 차단. 대상 작업(도구, 턴 또는 중지)이 중단됩니다. `stderr`가 거부 사유로 사용됩니다. 심각도가 높으며 보안 중지 또는 스크립트 실패에 사용됩니다.
기타	경고	치명적이지 않은 실패입니다. 경고가 표시되지만 상호 작용은 원래 매개변수를 사용하여 진행됩니다.

매처 (Matchers)

matcher 필드를 사용하여 후크를 실행할 특정 도구 또는 트리거를 필터링할 수 있습니다.

도구 이벤트 (BeforeTool, AfterTool): 매처는 정규 표현식입니다. (예: "write_.*").
수명 주기 이벤트: 매처는 정확한 문자열입니다. (예: "startup").
와일드카드: "*" 또는 "" (빈 문자열)은 모든 발생과 일치합니다.

구성

후크는 settings.json에서 구성됩니다. Gemini CLI는 다음 우선순위 순서(높은 순에서 낮은 순)로 여러 계층의 구성을 병합합니다:

프로젝트 설정: 현재 디렉터리의 .gemini/settings.json.
사용자 설정: ~/.gemini/settings.json.
시스템 설정: /etc/gemini-cli/settings.json.
확장: 설치된 확장에 의해 정의된 후크.

구성 스키마

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

후크 구성 필드

필드	유형	필수 여부	설명
`type`	string	Yes	실행 엔진입니다. 현재 `"command"`만 지원됩니다.
`command`	string	Yes*	실행할 셸 명령입니다. (`type`이 `"command"`일 때 필수).
`name`	string	No	로그 및 CLI 명령에서 후크를 식별하기 위한 친절한 이름입니다.
`timeout`	number	No	실행 제한 시간(밀리초)입니다 (기본값: 60000).
`description`	string	No	후크의 목적에 대한 간략한 설명입니다.

환경 변수

후크는 정화된 환경에서 실행됩니다.

GEMINI_PROJECT_DIR: 프로젝트 루트의 절대 경로입니다.
GEMINI_SESSION_ID: 현재 세션의 고유 ID입니다.
GEMINI_CWD: 현재 작업 디렉터리입니다.
CLAUDE_PROJECT_DIR: (별칭) 호환성을 위해 제공됩니다.

보안 및 위험

경고: 후크는 사용자 권한으로 임의의 코드를 실행합니다. 후크를 구성하면 스크립트가 사용자 머신에서 셸 명령을 실행하도록 허용하는 것입니다.

프로젝트 수준 후크는 신뢰할 수 없는 프로젝트를 열 때 특히 위험합니다. Gemini CLI는 프로젝트 후크를 **지문(fingerprint)**으로 식별합니다. 후크의 이름이나 명령이 변경되면(예: git pull을 통해) 새롭고 신뢰할 수 없는 후크로 취급되며 실행 전에 경고가 표시됩니다.

자세한 위협 모델은 보안 고려 사항을 참조하세요.

후크 관리

JSON을 수동으로 편집하지 않고 CLI 명령을 사용하여 후크를 관리하세요:

후크 보기: /hooks panel
모두 활성화/비활성화: /hooks enable-all 또는 /hooks disable-all
개별 토글: /hooks enable <name> 또는 /hooks disable <name>

원격 서브 에이전트 (실험적)IDE 통합