Antigravity 훅 문서

한 줄 요약: Antigravity 공식 문서 "Hooks". Antigravity의 실행 루프 중 정해진 시점에 셸 명령을 돌려 규칙을 강제하거나 린터를 돌리거나 진단 정보를 남기는 훅을 다룬다. App·CLI·IDE별 hooks.json 위치, 이벤트 6개(SessionStart, PreToolUse, PostToolUse, PreInvocation, PostInvocation, Stop), 도구 이름 matcher, 핸들러 필드(command만 지원), stdin·stdout JSON 계약과 이벤트별 결정 값을 담는다.

원본 정보#

• 제목: Hooks
• 발행: Antigravity 공식 문서(antigravity.google). 원문에 발행일·갱신일 표기가 없다(원본 날짜 미상).
• URL: https://antigravity.google/docs/hooks/ (새 창) (받은 주소는 원문 마크다운 https://antigravity.google/docs/hooks.md)
• 수집(fetch)일: 2026-10-21. 경로, 이벤트 이름, 필드 이름은 이 날짜 기준이다.

핵심 주장#

1. 훅은 실행 루프의 정해진 시점에 스크립트를 돌린다. 원본은 훅으로 규칙을 강제하고(enforce rules), 린터를 실행하고, 진단 정보를 남길 수 있다고 말한다. CLI 절은 실행 직전·직후에 에이전트 동작을 가로채므로 사전 점검이나 생성 뒤 포매터(예: 파일을 쓴 뒤 prettier)에 쓸모 있다고 한다. → 훅, Antigravity CLI
2. 정의 위치는 hooks.json이다. Antigravity CLI는 워크스페이스 .agents/hooks.json(프로젝트 루트), 전역 ~/.gemini/config/hooks.json 또는 ~/.gemini/antigravity-cli/settings.json 안, 설치한 플러그인의 hooks.json 세 곳에서 훅을 읽는다. TUI에서 /hooks로 로드된 훅을 볼 수 있다. App과 IDE는 워크스페이스 .agents/hooks.json과 전역 ~/.gemini/config/hooks.json을 쓰고, 설정 메뉴(App은 Settings > Customizations > Hooks, IDE는 에이전트 패널 … > Customizations > Hooks)에서 보고 켜고 끈다. → Antigravity CLI, 플러그인
3. 이벤트는 6개다. SessionStart(세션 시작 때 한 번, 첫 모델 호출 전), PreToolUse(도구 실행 전), PostToolUse(도구 완료 뒤), PreInvocation(모델 호출 전), PostInvocation(모델 호출이 끝난 직후마다), Stop(실행 루프가 끝날 때). matcher는 PreToolUse·PostToolUse에서만 쓰이고 도구 이름에 대한 정규식이다. 나머지 네 이벤트는 matcher를 무시하고 구조도 더 단순하다(이벤트 키 아래에 핸들러 목록을 바로 둔다). → 훅
4. 핸들러는 지금 command 하나뿐이다. 원본 표: type은 선택이고 "Currently only "command" is supported", 기본값도 "command". command(필수, 실행할 셸 명령), timeout(선택, 초 단위, 기본 30). 훅 이름 단위로 enabled: false를 두면 지우지 않고 끌 수 있다(기본 true). → 훅
5. 입출력은 stdin·stdout JSON이고 필드 이름은 camelCase다. 모든 이벤트가 공통 필드(conversationId, workspacePaths, transcriptPath, artifactDirectoryPath, modelName)를 받는다. PreToolUse는 decision(필수: allow, auto_approve, deny, ask, force_ask, deny_unless_prior_grant)으로 도구 호출을 거르고, 인자를 바꾸는 overwrite와 permissionOverrides를 돌려줄 수 있다. Stop은 decision: "continue"로 멈춤을 막고 실행 루프로 되돌린다. SessionStart·PreInvocation·PostInvocation은 injectSteps로 대화에 단계를 넣고, PostInvocation은 terminationBehavior(force_continue, terminate)로 흐름을 정한다. → 훅

원본의 경로·필드 (2026-10-21 기준)#

hooks.json은 훅 이름을 이벤트 설정에 대응시키는 형식이다. 원본 예시의 일부:

{
  "my-linter-hook": {
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

matcher 예(원본): "" 또는 "*"는 모든 도구, "run_command"는 정확히 그 도구, "run_command|view_file"은 둘 중 하나, "browser_.*"는 browser_로 시작하는 도구.

원본은 matcher에 쓸 표준 도구 이름을 범주별로 든다: 파일·디렉터리(view_file, write_to_file, replace_file_content, multi_replace_file_content, list_dir, find_by_name), 검색(grep_search, search_web, read_url_content), 시스템·실행(run_command, manage_task, schedule, list_permissions, ask_permission), 에이전트 협업(invoke_subagent, define_subagent, send_message, manage_subagents), 상호작용·미디어(ask_question, generate_image).

이벤트별 결정 값 (2026-10-21 기준)#

PreToolUse의 decision 값(원본 설명 그대로 옮김):

• allow: 도구 호출을 진행시키되 다음 훅이나 기본 정책에 판단을 넘긴다.
• auto_approve: 기본 정책이라면 확인을 물었을 때 자동으로 승인하되, 사용자가 명시적으로 설정한 규칙은 따른다.
• deny: 즉시 실행을 막는다("Hard blocks execution immediately").
• ask: 승인을 묻지만 "Always Allow" 설정은 존중한다.
• force_ask: 캐시된 권한을 무시하고 항상 묻는다.
• deny_unless_prior_grant: 이전에 승인된 자원이 아니면 막는다.

overwrite는 실행 전에 toolCall.args에 최상위 얕은 병합으로 합쳐지고, 인자가 바뀌면 바뀐 키 이름을 적은 안내가 도구 결과 앞에 붙는다.

injectSteps의 각 항목은 systemMessage(객체), userMessage(문자열), ephemeralMessage(문자열), toolCall(객체) 중 하나를 가진다. Stop의 decision이 "continue"가 아니면 멈춤을 허용하고, "continue"일 때 reason이 시스템 메시지로 대화에 들어간다.

원본에 없는 것#

• 훅 명령이 실패하거나 timeout을 넘기거나 잘못된 JSON을 내놓을 때 도구 호출이 막히는지 진행되는지는 말하지 않는다. 그래서 deny로 막는 훅이 실패했을 때의 동작은 원본 근거가 없다.
• 같은 이벤트에 훅이 여러 개일 때 실행 순서와 결정이 엇갈릴 때의 규칙은 allow가 "다음 훅이나 기본 정책에 넘긴다"는 설명 말고는 없다.
• 워크스페이스와 전역 hooks.json이 둘 다 있을 때 합치는지, 같은 이름이면 어느 쪽이 이기는지 말하지 않는다.
• 셸 명령의 작업 디렉터리, 환경 변수, 종료 코드의 의미는 말하지 않는다.
• Gemini CLI 훅을 옮기는 방법, Claude Code 훅과의 관계는 다루지 않는다.