가이드

모든 AI 코딩 에이전트의 hook: Claude Code, Cursor, Gemini CLI, GitHub Copilot, Kiro, Factory Droid (2026)

각 AI 코딩 에이전트에서 hook은 어디에 두며, hook은 명령을 어떻게 차단합니까?

Claude Code는 .claude/settings.json의 hooks 블록을, Gemini CLI는 .gemini/settings.json의 hooks 블록을 읽습니다. Cursor는 .cursor/hooks.json, Factory Droid는 .factory/hooks.json, GitHub Copilot은 .github/hooks/*.json, Kiro는 .kiro/hooks/의 모든 JSON 파일을 읽습니다. 모두 이벤트를 stdin의 JSON으로 스크립트에 전달합니다. 도구 호출을 차단하려면 Claude Code, Cursor, Gemini CLI, Factory Droid, Kiro CLI에서는 코드 2로 종료하거나, deny 결정을 JSON으로 출력합니다(Copilot은 permissionDecision, Cursor는 permission 사용).

이 페이지는 영어 가이드를 번역한 것입니다. 명령어, 설정 키, 코드는 원문 그대로이며 내용이 다를 경우 영어판을 기준으로 합니다. 영어 원문 보기 → · 다른 언어: 简体中文 · 日本語 · Español · Português (Brasil)

설정 변경 소식을 가장 먼저 받아 보세요

이 도구들의 설정, 플래그, 권한 규칙이 바뀌면 주 1회 이메일(영어)로 알려 드립니다. 모든 내용은 공식 문서로 확인합니다.

빠른 답변: hook 파일 위치

  • Claude Code: .claude/settings.json(프로젝트) 또는 ~/.claude/settings.json(사용자)의 hooks 키. /hooks로 설정된 내용을 확인합니다.
  • Cursor: .cursor/hooks.json(프로젝트) 또는 ~/.cursor/hooks.json(사용자), "version": 1 포함. Enterprise 및 팀 hook이 둘 다보다 상위에 있습니다.
  • Gemini CLI: .gemini/settings.json(프로젝트), ~/.gemini/settings.json(사용자) 또는 /etc/gemini-cli/settings.json(시스템)의 hooks 키.
  • GitHub Copilot: cloud agent와 Copilot CLI용 .github/hooks/*.json, 그리고 CLI용 ~/.copilot/hooks/. "version": 1.
  • Kiro: .kiro/hooks/(워크스페이스) 또는 ~/.kiro/hooks/(전역, CLI V3)의 모든 .json 파일, "version": "v1" 포함.
  • Factory Droid: .factory/hooks.json(프로젝트) 또는 ~/.factory/hooks.json(사용자). /hooks가 hook 관리자를 엽니다.

hook이 도구 호출을 차단하는 방법

  • Claude Code: 코드 2로 종료하는 PreToolUse hook은 작업을 차단하고 stderr를 이유로 돌려보냅니다.
  • Cursor: 코드 2로 종료하거나 {"permission": "deny"}를 출력합니다. 그 밖의 0이 아닌 코드는 hook에 failClosed: true가 없으면 fail open됩니다.
  • Gemini CLI: 코드 0으로 종료하고 {"decision": "deny", "reason": "..."}를 출력하거나(권장 방식), stderr에 이유를 남기고 코드 2로 종료합니다. 다른 코드는 경고만 합니다.
  • GitHub Copilot: preToolUse hook이 {"permissionDecision": "deny", "permissionDecisionReason": "..."}를 출력합니다. 아무것도 하지 않으면 호출이 허용됩니다.
  • Kiro: CLI에서는 코드 2로 종료하면 PreToolUse가 차단됩니다. IDE에서는 0이 아닌 모든 종료 코드가 Pre Tool Use hook을 차단합니다.
  • Factory Droid: PreToolUse에서 코드 2로 종료하면 도구 호출이 차단됩니다. 그 밖의 0이 아닌 코드는 기록되고 Droid는 계속 진행합니다.

같은 개념, 다른 이벤트 이름

  • 도구 실행 전: PreToolUse(Claude Code, Kiro, Factory Droid), preToolUse와 beforeShellExecution(Cursor), BeforeTool(Gemini CLI), preToolUse(Copilot).
  • 도구 실행 후: PostToolUse(Claude Code, Kiro, Factory Droid), postToolUse와 afterFileEdit(Cursor), AfterTool(Gemini CLI), postToolUse(Copilot).
  • 세션 시작: SessionStart(Claude Code, Kiro, Factory Droid, Gemini CLI), sessionStart(Cursor, Copilot).
  • 에이전트 완료: Stop(Kiro, Factory Droid), stop(Cursor), agentStop(Copilot).
  • prompt 제출: UserPromptSubmit(Kiro, Factory Droid), beforeSubmitPrompt(Cursor), userPromptSubmitted(Copilot).

같은 hook, 네 가지 문법

Claude Code: .claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Cursor: .cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/block-risky.sh",
        "matcher": "rm -rf|curl|wget"
      }
    ]
  }
}

Gemini CLI: .gemini/settings.json

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

Kiro: .kiro/hooks/guard-shell.json

{
  "version": "v1",
  "hooks": [
    {
      "name": "Guard shell commands",
      "trigger": "PreToolUse",
      "matcher": "shell",
      "action": {
        "type": "command",
        "command": "./scripts/guard.sh"
      }
    }
  ]
}

주의할 점

  • Gemini CLI의 stdout에는 최종 JSON만 있어야 합니다. 잘못된 JSON은 allow로 처리됩니다.
  • Gemini CLI는 이름이나 명령이 바뀐 프로젝트 hook을 실행하기 전에 경고합니다(예: git pull 이후).
  • Copilot은 toolArgs를 JSON 문자열로 전달하므로 두 번 파싱해야 합니다. cloud agent는 "ask" 결정을 "deny"로 처리하며 기본 브랜치의 hook만 로드합니다.
  • Cursor 프로젝트 hook은 프로젝트 루트에서, 사용자 hook은 ~/.cursor/에서 실행되므로 상대 스크립트 경로가 다릅니다.
  • Kiro의 agent prompt 작업은 새 에이전트 루프를 시작하고 크레딧을 사용합니다. 셸 명령 작업은 그렇지 않습니다.
  • Factory Droid matcher는 대소문자를 구분하는 정규식입니다. 명령 텍스트로 Execute 호출을 필터링하려면 commandRegex를 사용하십시오.

에이전트별 전체 hook 가이드

출처

이 가이드에서 확인한 공식 문서(영어)입니다. 영어판 확인일: 2026-10-18

Claude Code: Automate actions with hooksCursor: HooksGemini CLI: HooksGemini CLI: Hooks referenceGitHub Docs: Hooks referenceGitHub Docs: Use hooks with Copilot CLIKiro Docs: HooksFactory: Hooks

다른 한국어 가이드