Hook Actions
Agent Hook이 실제로 어떤 동작을 수행할지 결정하는 두 가지 액션 유형(Agent Prompt와 Shell Command)을 살펴봅니다.
Hook을 만들 때는 먼저 어떤 이벤트에서 실행할지를 고르고, 그다음 어떤 행동을 취할지를 정의합니다. Kiro의 Agent Hooks는 이 "행동" 부분을 두 가지 액션 타입으로 나누어 제공합니다. 하나는 자연어 지시를 통해 에이전트에게 작업을 맡기는 Agent Prompt(일명 Ask Kiro) 액션이고, 다른 하나는 로컬에서 결정적으로 실행되는 Shell Command 액션입니다.
Agent Prompt 액션
Agent Prompt 액션은 Hook이 발동될 때마다 에이전트에 전달할 프롬프트를 미리 작성해 두는 방식입니다. 작성한 프롬프트는 사용자가 채팅 창에서 직접 입력한 메시지와 동일하게 처리되며, 에이전트는 평소처럼 컨텍스트를 읽고 도구를 사용해 응답합니다. 따라서 "변경된 파일을 검토하고 누락된 테스트가 있으면 작성해 줘"처럼 상황 의존적인 지시를 자연어로 표현할 때 유용합니다.
PromptSubmit인 경우 이 액션은 이름이 Add to prompt로 바뀝니다. Hook에 정의한 프롬프트가 사용자의 원래 프롬프트 뒤에 덧붙여진(append) 뒤, 합쳐진 메시지가 한 번에 에이전트로 전달되기 때문입니다. 즉, 사용자의 입력을 대체하지 않고 보강하는 형태로 동작합니다.
Shell Command 액션
Shell Command 액션은 Hook이 발동될 때 지정된 셸 명령을 실행합니다. 명령의 종료 코드(exit code)에 따라 결과가 다르게 처리됩니다.
- 종료 코드 0 (성공): 명령의
stdout출력이 에이전트의 컨텍스트에 추가됩니다. 즉, 빌드 로그·테스트 결과·환경 정보 등을 자동으로 에이전트에게 전달할 수 있습니다. - 0이 아닌 종료 코드 (실패):
stderr출력이 에이전트에게 전달되며, Hook이 오류로 끝났다는 사실도 함께 알려집니다. 트리거 종류에 따라 추가 동작이 달라집니다.PreToolUseHook이라면 해당 도구 호출 자체가 차단(block)됩니다.PromptSubmitHook이라면 사용자의 프롬프트 제출이 차단됩니다.
또한 명령 실행 시간 제한(timeout)을 설정할 수 있습니다. 기본값은 60초이며, 0으로 지정하면 타임아웃이 비활성화됩니다.
0을 반환하도록 스크립트를 설계하세요. 그렇지 않으면 PreToolUse·PromptSubmit 트리거에서 의도치 않게 작업이 막힐 수 있습니다.
어떤 액션 타입을 선택할까
두 액션은 서로 대체재가 아니라 용도가 다릅니다. 다음 기준으로 선택하면 됩니다.
- 맥락에 따라 판단이 필요한가? — 변경된 코드 내용을 보고 리뷰하거나 테스트를 추가해야 한다면 Agent Prompt가 적합합니다.
- 고정된 명령을 실행하면 되는가? — 린터·포매터·빌드 스크립트처럼 결정적인 동작이라면 Shell Command가 더 잘 맞습니다.
- 속도와 비용은? — Agent Prompt는 새로운 에이전트 루프를 띄우므로 크레딧을 소비합니다. 반면 Shell Command는 LLM 호출 없이 로컬에서 실행되어 일반적으로 더 빠르고 비용이 들지 않습니다.
- 두 액션을 조합할 수도 있습니다. — 예를 들어 Shell Command로 정적 분석을 돌려 결과를 컨텍스트에 주입한 뒤, 별도의 Hook에서 Agent Prompt로 그 결과를 해석·수정하도록 구성할 수 있습니다.
요약하자면, 유연성과 자연어 추론이 중요하면 Agent Prompt를, 속도·비용·예측 가능성이 중요하면 Shell Command를 선택하세요. 트리거 종류와 액션 타입을 어떻게 짝짓는지에 따라 Hook의 표현력이 크게 달라집니다.