Hook Types

Agent Hooks가 지원하는 트리거 유형별 동작과 활용 시나리오를 정리한 문서입니다.

Kiro의 Agent Hooks는 다양한 시점에서 자동화를 걸 수 있도록 여러 트리거 유형을 제공합니다. 각 유형은 서로 다른 자동화 상황을 염두에 두고 설계되어 있어, 워크플로의 어느 지점에서 작업을 끼워 넣고 싶은지에 따라 적절한 트리거를 선택하면 됩니다.

Prompt Submit

사용자가 프롬프트를 제출하는 순간에 발화되는 트리거입니다. shell 명령으로 동작을 정의할 경우, 입력된 프롬프트 내용은 USER_PROMPT 환경 변수로 전달되어 그대로 활용할 수 있습니다.

에이전트가 자신의 턴을 마치고 응답을 완료한 직후에 실행됩니다. 마무리 단계에서 후속 검증이나 정리 작업을 자동화하기에 적합합니다.

에이전트가 도구(tool)를 호출하기 직전에 실행됩니다. 도구 호출을 가로채서 차단하거나, 호출 전에 별도의 가이드를 덧붙이는 용도로 유용합니다.

Tool Name 필드에서는 다음과 같은 내장 카테고리를 지정할 수 있습니다.

도구 출처를 기준으로 좁혀서 매칭하려면 다음 prefix를 사용할 수 있습니다.

@로 시작하는 prefix는 정규식으로 매칭됩니다. 예를 들어 @mcp.*sql.*처럼 작성하면 이름에 sql이 포함된 특정 MCP 도구만 골라 잡을 수 있습니다. 사용 가능한 도구 이름이 기억나지 않는다면 Kiro에게 직접 물어보세요.

에이전트가 도구를 호출한 직후에 실행됩니다. Tool Name 필드의 사용 방식은 Pre Tool Use와 동일하며, 호출 결과를 후처리하거나 감사 로그를 남길 때 유용합니다.

지정한 패턴에 해당하는 새 파일이 워크스페이스에 생성될 때 발화됩니다. 새 파일이 만들어지는 시점에 한 번에 처리해 두면 좋은 작업을 자동화할 수 있습니다.

지정한 패턴에 해당하는 파일이 저장될 때 실행됩니다. 가장 일상적으로 활용되는 트리거 중 하나로, 저장 시점마다 코드 품질을 다듬는 데 적합합니다.

지정한 패턴의 파일이 삭제되는 순간에 발화됩니다. 파일이 사라지면서 발생할 수 있는 부수 효과를 일관되게 처리할 수 있습니다.

Spec mode에서 task가 시작되어 상태가 in_progress로 바뀌는 시점에 실행됩니다. 작업을 본격적으로 진행하기 전에 환경을 준비하는 단계로 활용하기 좋습니다.

Spec mode의 task가 완료되어 상태가 completed로 전환되는 시점에 실행됩니다. 한 단위 작업이 끝날 때마다 검증과 마감 작업을 자동화할 수 있습니다.

예약된 시점이 아닌, 사용자가 원할 때만 직접 실행하는 수동 트리거입니다. 일상적으로 자동화할 필요는 없지만 필요할 때 한 번에 돌리고 싶은 작업에 적합합니다.

어떤 트리거를 고르더라도 hook은 에이전트가 수행하는 동작을 자동으로 확장합니다. 차단(blocking) 용도로 쓰는 hook은 의도치 않게 정상 워크플로까지 막을 수 있으므로, 패턴과 도구 이름 매칭 범위를 좁게 설정하고 충분히 검증한 뒤 적용하세요.