lacvet/AX-Copilot

Fork 0

Files

lacvet deffb33cf9 Initial commit to new repository

2026-04-03 18:23:52 +09:00

7.0 KiB

Raw Blame History

훅 레퍼런스

모든 훅 이벤트, 입력 페이로드, 출력 스키마, 각 종료 코드가 Claude 동작에 미치는 영향에 대한 전체 레퍼런스.

훅은 Claude의 에이전틱 루프에서 정의된 지점에서 발생하는 셸 커맨드, HTTP 엔드포인트, LLM 프롬프트, 또는 인프로세스 콜백입니다.

설정

훅은 설정 파일의 최상위 hooks 키로 구성됩니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'bash 커맨드 실행 예정' >&2"
          }
        ]
      }
    ]
  }
}

매처 설정

matcher 필드는 이벤트별로 다른 필드와 매칭됩니다:

이벤트	매칭되는 필드
`PreToolUse` / `PostToolUse` / `PostToolUseFailure` / `PermissionRequest` / `PermissionDenied`	`tool_name`
`Notification`	`notification_type`
`SessionStart`	`source` (`startup`, `resume`, `clear`, `compact`)
`Setup`	`trigger` (`init`, `maintenance`)
`SubagentStart` / `SubagentStop`	`agent_type`
`PreCompact` / `PostCompact`	`trigger` (`manual`, `auto`)
`ConfigChange`	`source`
`FileChanged`	파일 이름 패턴 (예: `".envrc

훅 타입

셸 커맨드:

{
  "type": "command",
  "command": "jq '.tool_name' && my-validator",
  "timeout": 30,
  "shell": "bash",
  "async": false,
  "once": false,
  "if": "Bash(git *)",
  "statusMessage": "검증 중..."
}

필드:

command: 실행할 셸 커맨드 (필수)
timeout: 타임아웃(초), 기본 60초
shell: bash (기본) 또는 powershell
async: true면 백그라운드에서 비블로킹 실행
asyncRewake: true면 백그라운드 실행, 종료코드 2로 종료 시 모델 깨움
once: true면 한 번 실행 후 자동 제거
if: 조건부로 훅 건너뛰기 위한 권한 규칙 구문
statusMessage: 실행 중 스피너에 표시되는 커스텀 메시지

LLM 평가:

{
  "type": "prompt",
  "prompt": "이 bash 커맨드가 안전한지 확인하세요: $ARGUMENTS",
  "model": "claude-haiku-4-5",
  "timeout": 30
}

에이전틱 검증기:

{
  "type": "agent",
  "prompt": "단위 테스트가 실행되고 통과했는지 확인하세요.",
  "model": "claude-haiku-4-5",
  "timeout": 120
}

HTTP 엔드포인트:

{
  "type": "http",
  "url": "https://my-server.example.com/hook",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 10
}

기본 훅 입력

모든 훅이 stdin에서 받는 공통 필드:

필드	타입	설명
`hook_event_name`	`string`	발생한 이벤트 (예: `"PreToolUse"`)
`session_id`	`string`	현재 세션 식별자
`transcript_path`	`string`	세션 JSONL 트랜스크립트 파일의 절대 경로
`cwd`	`string`	훅 발생 시점의 현재 작업 디렉토리
`permission_mode`	`string`	활성 권한 모드
`agent_id`	`string`	서브에이전트에서 발생 시 식별자

동기 훅 출력 (stdout의 JSON)

블로킹 훅의 경우 종료 전에 JSON을 stdout에 씁니다:

{
  "continue": true,
  "suppressOutput": false,
  "decision": "approve",
  "reason": "커맨드가 안전합니다",
  "systemMessage": "훅이 이 작업을 승인했습니다.",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow"
  }
}

훅 이벤트 상세

`PreToolUse`

도구가 실행되기 직전에 발생.

입력 필드: tool_name, tool_input, tool_use_id

종료 코드:

코드	효과
`0`	stdout/stderr 표시 안 됨. 훅 출력 JSON 적용
`2`	stderr를 Claude에게 표시; 도구 호출 차단
기타	stderr를 사용자에게만 표시; 도구 호출 계속

hookSpecificOutput 필드:

permissionDecision: 'allow' | 'deny' | 'ask' — 권한 결정 재정의
updatedInput: 도구가 받을 교체 입력
additionalContext: 이 턴의 Claude 컨텍스트에 주입될 텍스트

`PostToolUse`

도구가 성공적으로 완료된 후 발생.

입력 필드: tool_name, tool_input, tool_response, tool_use_id

종료 코드:

코드	효과
`0`	stdout이 트랜스크립트 모드에 표시 (Ctrl+O)
`2`	stderr를 즉시 Claude에게 시스템 메시지로 표시
기타	stderr를 사용자에게만 표시

`Stop`

Claude가 응답을 종료하기 직전에 발생.

입력 필드: stop_hook_active, last_assistant_message

종료 코드:

코드	효과
`0`	stdout/stderr 표시 안 됨
`2`	stderr를 시스템 메시지로 주입; Claude 대화 계속
기타	stderr를 사용자에게만 표시; Claude 중지

💡 Stop 훅의 종료코드 2를 사용해 Claude 출력을 확인하고 조건이 충족되지 않으면 대화를 계속하게 합니다 — 예를 들어 테스트가 여전히 실패하는 경우.

`SessionStart`

세션 시작 시 발생. 초기 컨텍스트 주입이나 환경 설정에 사용.

입력 필드: source ('startup' | 'resume' | 'clear' | 'compact'), model

hookSpecificOutput 필드:

additionalContext: 세션 시스템 프롬프트에 주입될 컨텍스트
initialUserMessage: 세션의 첫 사용자 메시지로 자동 제출
watchPaths: FileChanged 감시기에 등록할 절대 파일 경로

`UserPromptSubmit`

사용자가 프롬프트를 제출할 때 발생.

입력 필드: prompt

종료 코드:

코드	효과
`0`	stdout이 Claude에게 추가 컨텍스트로 표시
`2`	처리 차단; 원본 프롬프트 지워짐; stderr를 사용자에게 표시
기타	stderr를 사용자에게만 표시

`PermissionRequest`

권한 다이얼로그가 표시될 때 발생. UI 없이 프로그래밍 방식으로 승인/거부 가능.

종료 코드:

코드	효과
`0`	`hookSpecificOutput.decision`이 설정된 경우 훅 결정 적용
기타	stderr를 사용자에게 표시; 일반 다이얼로그로 폴백

`CwdChanged`

작업 디렉토리 변경 후 발생.

입력 필드: old_cwd, new_cwd

CLAUDE_ENV_FILE 환경 변수가 설정됨 — 환경 변수를 export KEY=value 줄로 써서 이후 Bash 도구 호출에 적용합니다.

`FileChanged`

감시 중인 파일이 수정, 추가, 제거될 때 발생.

입력 필드: file_path, event ('change' | 'add' | 'unlink')

비동기 훅

백그라운드에서 실행되는 훅은 일반 동기 출력 대신 비동기 확인을 stdout에 출력합니다:

{
  "async": true,
  "asyncTimeout": 30
}

⚠️ 비동기 훅은 도구 실행을 차단하거나 컨텍스트를 주입할 수 없습니다. 에이전틱 루프를 느리게 하면 안 되는 알림, 로깅, 메트릭 같은 부작용에 사용하세요.

7.0 KiB Raw Blame History

훅 레퍼런스

설정

매처 설정

훅 타입

기본 훅 입력

동기 훅 출력 (stdout의 JSON)

훅 이벤트 상세

PreToolUse

PostToolUse

Stop

SessionStart

UserPromptSubmit

PermissionRequest

CwdChanged

FileChanged

비동기 훅

7.0 KiB

Raw Blame History

`PreToolUse`

`PostToolUse`

`Stop`

`SessionStart`

`UserPromptSubmit`

`PermissionRequest`

`CwdChanged`

`FileChanged`