whchoi98.github.io
홈Home / Workshop / Kiro CLI Workshop

Hook

Hook

Table of contents

  1. Hook 정의
  2. 1. Hook Event Structure
    1. 1.1. 기본 이벤트 구조 예시
    2. 1.2. Tool 관련 Hook의 추가 필드
  3. 2. Hook Output 규칙
  4. 3. 도구 매칭 규칙
    1. matcher 예시
  5. 4. Hook 종류
    1. 4.1. AgentSpawn
      1. Event Example
      2. Exit Code 동작
    2. 4.2. UserPromptSubmit
      1. Event Example
      2. Exit Code 동작
    3. 4.3. PreToolUse
      1. Event Example
      2. Exit Code 동작
    4. 4.4. PostToolUse
      1. Event Example
      2. Exit Code 동작
    5. 4.5. Stop
      1. Event Example
      2. Exit Code 동작
  6. 5. MCP 예
    1. Example
  7. 6. Timeout
  8. 7. Caching

Hooks는 에이전트(agent) 생명주기(lifecycle) 및 도구(tool) 실행 과정의 특정 시점에 사용자 정의 명령(custom commands)을 실행할 수 있도록 하는 기능입니다.

이를 통해 다음과 같은 고급 동작을 구현할 수 있습니다:

Hooks는 Kiro의 에이전트 기능을 조직·프로젝트 요구사항에 맞게 확장하는 핵심 메커니즘입니다.

Hook 정의

Hooks는 에이전트 설정(agent configuration) 파일 내에서 정의됩니다.

1. Hook Event Structure

모든 Hook은 STDIN을 통해 JSON 형식의 이벤트(payload)를 전달받습니다.

1.1. 기본 이벤트 구조 예시

{
  "hook_event_name": "agentSpawn",
  "cwd": "/current/working/directory"
}

1.2. Tool 관련 Hook의 추가 필드

필드명의미
tool_name실행되는 도구의 이름
tool_input도구 실행에 전달된 입력 값
tool_responsePostToolUse 시점에서의 도구 실행 결과

2. Hook Output 규칙

Exit Code의미동작
0Hook 성공STDOUT은 사용자에게 표시되지 않고 컨텍스트에 반영됨
2(PreToolUse 전용) 도구 실행 차단STDERR 내용이 LLM에게 반환됨
기타 코드Hook 실패사용자에게 STDERR 경고 표시, 도구는 계속 실행됨 (PreToolUse 제외)

3. 도구 매칭 규칙

matcher 필드를 통해 특정 도구에만 Hook이 적용되도록 지정할 수 있습니다.

matcher 예시

matcher 값적용 범위
"write"built-in write 도구에만 적용
"@git"git MCP 서버의 모든 도구
"@git/status"git MCP 서버의 특정 도구
"*"전 도구 (built-in + MCP)
"@builtin"모든 built-in 도구
(생략)모든 도구

도구 참조 형식은 Agent Configuration Reference와 동일합니다.

4. Hook 종류

4.1. AgentSpawn

에이전트가 초기화될 때 실행됩니다.

도구 관련 정보는 포함되지 않습니다.

Event Example

{
  "hook_event_name": "agentSpawn",
  "cwd": "/current/working/directory"
}

Exit Code 동작

4.2. UserPromptSubmit

사용자가 프롬프트를 제출할 때마다 실행됩니다.

출력은 대화 컨텍스트에 추가되어 LLM이 참고할 수 있습니다.

Event Example

{
  "hook_event_name": "userPromptSubmit",
  "cwd": "/current/working/directory",
  "prompt": "user's input prompt"
}

Exit Code 동작

4.3. PreToolUse

도구 실행 직전에 실행되며, 유효성 검사 및 보안 확인에 적합합니다.

유일하게 도구 실행을 차단할 수 있는 Hook입니다.

Event Example

{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "read",
  "tool_input": {
    "operations": [
      {
        "mode": "Line",
        "path": "/current/working/directory/docs/hooks.md"
      }
    ]
  }
}

Exit Code 동작

Exit Code동작
0도구 실행 허용
2도구 실행 차단, STDERR이 LLM에 반환됨
기타경고 표시 후 도구는 계속 실행됨

4.4. PostToolUse

도구 실행 완료 후 실행되며, 실행 결과(tool_response)에 접근할 수 있습니다.

Event Example

{
  "hook_event_name": "postToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "read",
  "tool_input": {
    "operations": [
      {
        "mode": "Line",
        "path": "/current/working/directory/docs/hooks.md"
      }
    ]
  },
  "tool_response": {
    "success": true,
    "result": ["# Hooks\n\nHooks allow you to execute..."]
  }
}

Exit Code 동작

4.5. Stop

Assistant가 응답을 완료할 때마다 실행되는 Hook입니다.

포매팅, 테스트, 빌드, 정리 작업 등 후처리에 적합합니다.

Event Example

{
  "hook_event_name": "stop",
  "cwd": "/current/working/directory"
}

Exit Code 동작

Stop Hook에는 matcher가 필요하지 않습니다. 특정 도구와 연결되지 않는 이벤트이기 때문입니다.

5. MCP 예

MCP 도구가 호출될 때는 tool_name에 서버 네임스페이스가 포함됩니다.

Example

{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "@postgres/query",
  "tool_input": {
    "sql": "SELECT * FROM orders LIMIT 10;"
  }
}

6. Timeout

7. Caching