Claude Code / Codex / Cursor Agent Hooks 설정 방법? PreToolUse 비교, 최소 스크립트와 fail-open 실측

Instructions, AGENTS.md, skills는 모델이 무시할 수 있는 제안이고, hooks는 harness가 고정된 시점에 실행하는 결정론적 스크립트다. 이 글에서는 Claude Code, Codex, Cursor의 PreToolUse(또는 동등한 이벤트) 설정 경로, 이벤트 이름, exit 2 / deny, fail-open과 fail-closed를 비교하고, Claude Code에서 실측한 최소 인터셉트 스크립트를 제공한다.

8 分钟阅读
Claude Code / Codex / Cursor Agent Hooks 설정 방법? PreToolUse 비교, 최소 스크립트와 fail-open 실측

결론부터 말하면:

  • AGENTS.md / skills / 시스템 설명은 제안이다: 모델이 읽기도 하지만 잊거나 우회할 수 있다.
  • Hooks는 harness가 실행하는 스크립트다: 도구 호출 전후 등 고정된 시점에 실행되며, 모델이 규칙을 「기억」하는지 여부와 무관하다.
  • 세 클라이언트 모두 도구 호출을 차단할 수 있다: Claude Code / Codex는 PreToolUse를 사용하고, Cursor는 preToolUse(또는 더 좁은 범위의 beforeShellExecution)를 사용한다. 차단 방법은 주로 exit code 2, 또는 JSON의 deny 반환이다.
  • 기본값은 대부분 fail-open이다: 스크립트가 충돌하거나, 타임아웃이 발생하거나, 0/2 이외의 코드로 종료되면 도구 호출은 대개 계속 진행된다. 보안 정책에서는 명시적으로 fail-closed로 변경해야 한다(Claude Code: onFailure: "block"; Cursor: failClosed: true). Codex 공식 문서에 따르면 hook 실패 시 hook failure를 보고하며, 기본적으로 실패를 하드 차단으로 처리하지 않는다.
  • Claude Code에서 실측했다: rm -rf /tmp/hooks-deny-me에 매칭되는 Bash는 PreToolUse로 차단(exit 2)되었고, echo hooks-allow-ok는 정상 통과했다. Cursor는 로컬 비GUI 환경에서 동등한 실측이 불가능하므로, Cursor 설정은 공식 문서를 기반으로 정리했으며 실측이라고 주장하지 않는다.

SwiftLee / Antoine van der Lee의 2026-11-02 글 및 @peterfriese의 X 리트윗에 따르면: hooks는 AGENTS.md에 규칙을 작성하는 것보다 훨씬 신뢰할 수 있다. 이하는 각 회사의 공식 문서를 기준으로 하며, 서드파티 글과 불일치하는 부분은 공식 문서를 우선하고 출처를 명시한다.

관련 배경: 플러그인이 몰래 SessionStart hooks를 달 수 있으며(Postman 플러그인 확인 및 제거 참고), AGENTS.md도 디렉터리 컨텍스트에 의해 흔들릴 수 있다(Downloads 디렉터리 하이재킹 참고). Hooks는 「Downloads 디렉터리에서 agent를 열지 말 것」을 대체하지 못하지만, markdown으로는 강제할 수 없는 하드 규칙을 실행할 수 있다. MCP와 권한 경계는 Codex Playwright MCP 보안 가이드를, skills와 hooks의 역할 분담은 AI Agent에서 Skills 사용법을 참고하라.

1분 비교표

항목Claude CodeCodexCursor
사용자 수준 설정~/.claude/settings.json~/.codex/hooks.json 또는 config.toml~/.cursor/hooks.json
프로젝트 수준 설정.claude/settings.json.codex/hooks.json 또는 config.toml.cursor/hooks.json(워크스페이스 신뢰 필요)
도구 호출 전PreToolUsePreToolUsepreToolUse; 셸 명령에는 beforeShellExecution도 사용 가능
도구 호출 후PostToolUsePostToolUsepostToolUse / afterFileEdit 등
Shell 도구 이름(matcher)BashBashShell(beforeShellExecution은 명령 텍스트로 매칭)
차단exit 2, 또는 JSON permissionDecision: "deny"exit 2, 또는 JSON permissionDecision: "deny" / 구버전 decision: "block"exit 2, 또는 JSON permission: "deny"
Hook 실패 기본값대부분의 이벤트에서 계속 진행(fail-open); onFailure: "block" 설정 가능hook failure 보고, 실패를 하드 차단으로 처리하지 않음(공식 Hooks 페이지 기준)기본 fail-open; failClosed: true 설정 가능
신뢰 / 검토워크스페이스 신뢰 여부가 프로젝트 hooks에 영향비관리형 hooks는 /hooks로 검토 후 trust 필요; --dangerously-bypass-hook-trust 일회성 사용 가능프로젝트 hooks는 신뢰된 워크스페이스에서만 로드됨

공식 문서: Claude Code Hooks · Codex Hooks · Cursor Hooks

왜 AGENTS.md만 쓰면 안 되는가

SwiftLee 글의 경험에 따르면: xcodebuild 출력 필터링을 전역 설명에 작성했음에도 agent가 원시 로그를 컨텍스트에 그대로 집어넣는 경우가 잦았다. 설명 텍스트는 prompt에 들어가고, 모델이 준수 여부를 결정한다. 반면 hook은 harness 레이어에서 실행되므로, 모델이 「hook 실행 여부」를 거부할 수 없다.

적합한 역할 분담:

  1. 설명과 선호도 → AGENTS.md / skills (의도, 스타일, 프로세스 설명)
  2. 매번 반드시 성립해야 하는 규칙 → hooks (위험 명령 차단, 빌드 명령 재작성, 감사, 세션 종료 후 기록)
  3. hooks를 유일한 방어선으로 삼지 말 것 → 일부 경로는 hooks를 우회한다(예: Codex 문서에 명시된 바와 같이, write_stdin으로 이미 PreToolUse를 통과한 명령을 폴링할 때는 PreToolUse가 다시 실행되지 않는다).

최소 스크립트: 위험한 Bash 하나 차단하기(fail-open)

아래 스크립트는 세 클라이언트 모두에 적용 가능하다. stdin JSON을 읽어 명령을 추출하고, 매칭되면 차단하며, 그렇지 않으면 통과시킨다. 파싱에 실패하면 exit 0(fail-open). ~/.agents/hooks/block-rm-demo.sh 같은 경로에 실행 가능한 파일로 저장한다.

bash
#!/bin/bash
# fail-open: jq가 없거나 JSON 오류 → exit 0, 작업을 막지 않음
input=$(cat || true)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)

if [[ -z "$command" ]]; then
  exit 0
fi

if [[ "$command" == *"rm -rf /tmp/hooks-deny-me"* ]]; then
  # Cursor: cursor_version 필드가 있을 때는 JSON deny 사용(공식 Cursor Hooks 문서 + SwiftLee 글 작성 방식 기준)
  if printf '%s' "$input" | jq -e 'has("cursor_version")' >/dev/null 2>&1; then
    jq -n '{permission:"deny", agent_message:"Blocked by PreToolUse-style hook: refusing rm -rf /tmp/hooks-deny-me"}'
    exit 0
  fi
  # Claude Code / Codex: stderr + exit 2
  echo "Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me" >&2
  exit 2
fi

exit 0

chmod +x 후 설정에 등록한다.

Claude Code 등록

~/.claude/settings.json 또는 프로젝트 .claude/settings.json에 작성:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm-demo.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

사용자 수준에서는 절대 경로를 사용할 수 있다. 보안 정책 hook에는 "onFailure": "block" 추가를 권장한다(비교적 최신 버전 필요, 공식 Hooks reference 참고). 스크립트 경로가 잘못되었을 때 정책 전체가 무효화되는 것을 방지한다.

Codex 등록

구조는 Claude Code와 비슷하며, ~/.codex/hooks.json 또는 프로젝트 .codex/hooks.json에 작성:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/bash /absolute/path/to/block-rm-demo.sh",
            "timeout": 5,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

주의: Codex는 비관리형 hooks를 CLI에서 /hooks로 검토 후 trust해야 한다. 프로젝트 수준 hooks는 프로젝트 .codex/가 신뢰되어야 한다. 일회성 자동화에는 공식 문서의 --dangerously-bypass-hook-trust를 사용할 수 있다. [features] hooks = false로 전역 비활성화도 가능하다.

Cursor 등록

Cursor의 hooks.json은 더 단순하며 version이 필요하다:

json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "~/.agents/hooks/block-rm-demo.sh",
        "matcher": "Shell",
        "timeout": 5
      }
    ]
  }
}

프로젝트 수준 경로는 저장소 루트 기준 상대 경로를 사용한다(예: .cursor/hooks/block-rm-demo.sh). 보안이 중요한 hook에는 "failClosed": true를 추가한다. beforeShellExecution으로 변경하면 matcher가 명령 텍스트를 직접 매칭한다(예: rm\\s+-rf).

실측: Claude Code PreToolUse(본 사이트 Key)

환경: Claude Code CLI 2.1.319, 프로젝트 내 .claude/settings.json에 위의 fail-open 스크립트 등록, aicodewith 호환 인터페이스로 비대화형 -p 실행.

  1. 통과 경로: 모델에 echo hooks-allow-ok 실행 요청 → hooks-allow-ok 출력, 약 8초.
  2. 차단 경로: 모델에 rm -rf /tmp/hooks-deny-me 실행 요청 → PreToolUse hook error 반환, 명령 미실행, 약 9초. 오류 내용 발췌:
text
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
  1. 단위 수준 fail-open: stdin에 잘못된 JSON 입력 → 스크립트 exit 0(후속 작업 미차단).

Cursor는 로컬 비GUI 환경에서 동등한 실측이 불가능했으며, 위 표의 Cursor 열은 Cursor 공식 Hooks 문서를 기반으로 한다. Codex 설정 구조는 공식 문서와 대조 완료했으며, 이번 통합 실측은 중복 소비를 피하기 위해 Claude Code 단일 경로를 선택했다.

Codex를 사용하는 경우, 동일한 스크립트를 PreToolUse + matcher Bash로 등록하고, /hooks trust 후 매칭 명령 하나와 비매칭 명령 하나를 실행해 자체 검증할 수 있다.

fail-open이냐 fail-closed냐

시나리오권장설정 방법
편의성(빌드 로그 필터링, 자동 format)fail-open기본값으로 충분; 스크립트 내 파싱 실패 시도 exit 0
보안 / 컴플라이언스(삭제 금지, 외부 전송 금지, 키 파일 수정 금지)fail-closedClaude Code: onFailure: "block"; Cursor: failClosed: true; 「스크립트 삭제 후 도구가 차단되는지」 직접 테스트
Codex 관리형 정책기업 requirements.toml / managed hooks공식 Managed hooks 참고; 로컬 사용자 hook 실패는 기본적으로 하드 차단 아님

SwiftLee 글에 따르면: 편의성 hook은 fail-open이어야 하며, 망가진 hook 때문에 작업이 불가능해지면 안 된다. 위험 동작을 막는 hook만 fail-closed로 설정해야 한다.

설정 시 주의사항(세 클라이언트 공통)

  1. 먼저 읽고 활성화하라: 저장소나 플러그인이 가져온 hooks는 로컬 스크립트이며, 권한은 사용자 본인과 동등하다. Postman 같은 플러그인이 자동으로 SessionStart hooks를 설치한 사례가 있었으니, 설치 전에 무엇이 등록되는지 확인하라.
  2. timeout은 짧게: agent는 hook을 기다린다. 사용자 수준 편의성 hook의 일반적인 값은 5초다.
  3. Stop / stop 후속 실행에는 루프 제한을 두라: Cursor는 stop / subagentStop에 loop_limit이 있다(기본값 5). 「종료 후 한 마디 더」가 무한 반복되지 않게 하라.
  4. matcher 이름을 혼동하지 말라: Claude Code / Codex의 Shell 도구 이름은 Bash이고, Cursor의 범용 도구 매칭은 Shell이다.
  5. Hooks ≠ skills: skills는 이름이나 설명으로 호출하는 능력 패키지이고, hooks는 이벤트로 트리거되며 누가 지목하지 않아도 실행된다.

aicodewith Key로 Claude Code / Codex 실행하기(선택)

Hooks 테스트는 특정 모델 공급자에 의존하지 않는다. aicodewith를 통해 모델을 호출하는 경우:

  • Claude Code: 사이트 문서에 따라 호환 Base URL과 Key를 설정한다.
  • Codex: 전역 ~/.codex/config.toml에서 experimental_bearer_token 사용, name = "aicodewith", base_url = "https://api.aicodewith.ai/chatgpt/v1"(경로는 /chatgpt/v1이며 /v1이 아님).

API Key 만들기 →

자주 묻는 질문

Hooks와 AGENTS.md의 차이는 무엇인가?

AGENTS.md는 컨텍스트에 들어가며 모델이 무시할 수 있다. Hooks는 Claude Code / Codex / Cursor가 생명주기 이벤트에서 직접 실행한다. 의도는 markdown에 쓰고, 하드 제약은 hook으로 작성하라.

Exit code 2와 JSON deny 중 무엇을 선택해야 하나?

둘 다 차단 가능하다. Claude Code / Codex에서는 stderr + exit 2가 일반적이고, 구조화된 이유 제공이나 입력 재작성이 필요할 때는 JSON을 사용한다(예: permissionDecision / updatedInput). Cursor는 permission hooks에서 stdout JSON의 permission 필드를 더 선호하며, exit 2도 deny와 동등하게 동작한다.

왜 프로젝트 hooks가 실행되지 않는가?

확인 사항: 워크스페이스 / 프로젝트가 신뢰되었는지; Codex에서 /hooks trust를 완료했는지; 경로가 올바른지(Cursor 프로젝트 hooks는 저장소 루트 기준 상대 경로); matcher에 올바른 도구 이름이 작성되었는지; Claude Code에서는 /hooks 메뉴로 출처를 확인할 수 있다.

Hooks가 보안 정책을 완전히 대체할 수 있는가?

아니다. 공식 문서에서도 일부 경로는 hook을 통과하지 않는다고 명시한다. 플러그인과 SessionStart 스크립트 자체도 위험 면이 될 수 있다. Hooks는 결정론적인 방어 레이어 하나이며, 권한 모델, 키 관리, 디렉터리 선택과 함께 사용해야 한다.

Cursor의 ask는 preToolUse에서 신뢰할 수 있나?

Cursor 공식 문서에 따르면: preToolUse의 출력에서 "ask"는 현재 강제 실행되지 않는다. 동작을 차단하려면 "deny" 또는 exit 2를 사용하라. beforeShellExecution 등의 이벤트는 allow / deny / ask를 지원한다.

정리

「모델이 기억해야 하는」 규칙을 「harness가 매번 실행하는」 hooks로 격상시켜라. 먼저 PreToolUse / preToolUse 최소 스크립트 하나부터 시작하라: matcher를 Bash 또는 Shell로 지정하고, 매칭 시 exit 2 / deny, 기본 fail-open, 보안 시나리오에서만 fail-closed. Claude Code, Codex, Cursor는 설정 파일과 이벤트 이름이 다르지만, 이벤트 → matcher → 스크립트 → 결정 이라는 흐름은 동일하다.

API Key 만들기 → · 모델 및 연동 문서 보기 →

출처

相关文章

UI SDK는 무엇이고 어떻게 쓰나? Vercel과 shadcn이 Agent를 위해 만든 동작 라이브러리를 Claude Code / Codex / Cursor에서 설치하고 실측하기 (0.1.0-beta.1)

UI SDK는 무엇이고 어떻게 쓰나? Vercel과 shadcn이 Agent를 위해 만든 동작 라이브러리를 Claude Code / Codex / Cursor에서 설치하고 실측하기 (0.1.0-beta.1)

UI SDK는 Vercel이 2026년 11월 12일에 공개한 Agent용 동작(behaviors) 라이브러리이며, 버전은 0.1.0-beta.1입니다. 동작은 프레임워크에 의존하지 않는 @ui-sdk/core에 있고, React, Vue, Svelte, Solid, Web Components 어댑터가 렌더링합니다. 공식 문서를 따라 무엇인지, 어떻게 설치하는지, Claude Code / Codex / Cursor에 skill을 어떻게 넣는지 정리하고, 테스트 머신에서 실제로 실행한 명령, 소요 시간, 출력을 기록합니다.

AWS Emulator란? 설치 방법과 Claude Code / Codex로 AWS 앱을 로컬에서 테스트하는 법 (1.0.322 실측)

AWS Emulator란? 설치 방법과 Claude Code / Codex로 AWS 앱을 로컬에서 테스트하는 법 (1.0.322 실측)

AWS Emulator는 AWS 공식 로컬 AWS 에뮬레이터로, 2026년 11월 11일(미국 시간)부터 정식 출시(GA)되었습니다. 추가 서비스 요금이 없고 소스가 공개되어 있으며 AWS 계정 없이 200개가 넘는 서비스를 다룹니다. 이 글에서는 Debian 13에서 1.0.322를 직접 테스트해 설치 명령, AWS CLI를 로컬 endpoint로 향하게 해 S3 버킷과 DynamoDB 테이블을 만드는 과정, 실제로 만난 오류, 그리고 Claude Code·Codex·Cursor가 에뮬레이터를 상대로 코드를 짜고 테스트하게 하는 방법을 정리합니다.

T3 Code란? 설치 방법, Claude Code·Codex 연결, 서드파티 API Key 설정과 자주 나는 오류 (0.1.9 실제 테스트)

T3 Code란? 설치 방법, Claude Code·Codex 연결, 서드파티 API Key 설정과 자주 나는 오류 (0.1.9 실제 테스트)

T3 Code는 pingdotgg가 공개한 오픈소스 코딩 에이전트 콘솔입니다. 자체 모델 없이, 컴퓨터에 이미 설치된 Claude Code, Codex, Cursor 등의 CLI를 조작합니다. Linux에서 T3 Code 0.1.9를 테스트해 설치 명령, Claude Code와 Codex를 AICodeWith API Key에 연결해 T3 Code가 조작하도록 하는 설정, t3 thread 명령으로 두 에이전트를 실제로 돌린 결과, 실제로 만난 오류와 해결 방법을 정리했습니다.