SubagentStop 훅 — 서브에이전트 완료 시 처리

SubagentStop 훅은 서브에이전트가 태스크를 완료한 시점에 자동으로 셸 명령을 실행하는 Hooks 이벤트입니다. LLM의 판단에 기대지 않고 확실하게 실행되므로, 서브에이전트 완료를 트리거로 삼는 로그 기록 같은 후처리에 잘 맞습니다.

비동기 실행 async:true까지가 훅의 실행 방식에 관한 이야기였다면, 이 글부터는 특정 상황에서만 쓰는 이벤트를 다룹니다. 필요해졌을 때 참조하는 식으로 읽어도 문제없습니다.

핵심 요약

• SubagentStop 훅은 서브에이전트가 태스크를 완료했을 때 실행됩니다.
• Stop 훅은 메인 에이전트 완료 시, SubagentStop 훅은 서브에이전트 완료 시에 발화합니다.
• 로그 기록 등의 후처리에 활용할 수 있습니다.
• JSON 출력으로 "계속 지시"를 내려 추가 작업을 시킬 수도 있습니다.

SubagentStop 훅은 언제 필요한가

서브에이전트를 쓴 태스크 분산은 Claude Code의 편리한 기능 중 하나입니다. 대규모 코드베이스 조사나 여러 파일의 병렬 편집 같은 복잡한 태스크를 효율적으로 처리할 수 있습니다. 서브에이전트의 구조 자체는 서브 에이전트로 작업 나누기에서 다룹니다.

그렇다면 서브에이전트의 완료 타이밍에 뭔가 처리를 실행하고 싶을 때는 어떻게 해야 할까요. 여기서 등장하는 것이 SubagentStop 훅입니다. Hooks의 기본 구조는 훅(Hooks)으로 동작 강제하기를 참고하세요.

Stop 훅과 SubagentStop 훅은 무엇이 다른가

Claude Code에는 에이전트의 완료를 감지하는 훅이 2종류 있습니다.

양쪽의 최대 차이는 "어느 에이전트의 완료를 감지하느냐"입니다. 메인 에이전트는 사용자와 직접 대화하는 Claude이고, 서브에이전트는 메인 에이전트로부터 특정 태스크를 위임받은 Claude로 독자적인 컨텍스트 윈도우를 갖습니다. Stop 훅의 상세는 Stop 훅에서 해설합니다.

PreToolUse/PostToolUse 훅은 서브에이전트 안에서 도구가 호출된 경우에도 같은 설정으로 발화합니다. 서브에이전트가 파일을 편집하면 PostToolUse 훅으로 설정한 자동 포맷도 그대로 실행됩니다(JSON 입력에는 agent_id나 agent_type이 추가됩니다). 한편 SubagentStop 훅은 도구 호출 전후가 아니라 서브에이전트의 완료 타이밍 자체를 감지하므로, 로그 기록처럼 "완료 시에 딱 한 번 실행하고 싶은 처리"에 알맞습니다. 도구 전후 훅은 PreToolUse·PostToolUse 훅을 참고하세요.

기본 설정 방법

설정은 settings.json에 기술합니다. 설정 파일의 위치와 sh 파일화 요령은 Hooks 설정 방법에서 다룹니다.

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): Subagent completed\" >> ~/Desktop/hooks-test/subagent.log"
          }
        ]
      }
    ]
  }
}

이 설정에서는 서브에이전트가 완료될 때마다 일시와 함께 로그 파일에 기록됩니다.

Mon Dec 29 19:06:41 KST 2025: Subagent completed

matcher로 에이전트 종류를 좁힐 수 있나

SubagentStop 훅에는 SubagentStart 훅과 같은 에이전트 종별에 의한 matcher를 쓸 수 있습니다(general-purpose, Explore, Plan, 커스텀 에이전트명 등). 특정 종류의 서브에이전트가 완료됐을 때만 처리를 실행하고 싶다면 이 matcher로 좁힙니다. 생략하면 모든 서브에이전트의 완료 시에 발화합니다.

다만 PreToolUse나 PostToolUse에서 쓰는 "matcher": "Edit" 같은 도구명 지정과는 형식이 다릅니다. SubagentStop의 matcher가 지정하는 것은 어디까지나 에이전트의 종류입니다. 참고로 Stop 훅에는 매처 개념이 없어 늘 발화합니다. 매처의 일반 규칙은 Hooks 매처를 참고하세요.

커스텀 에이전트명을 matcher에 쓰려면 먼저 에이전트를 정의해야 합니다. 정의 파일 작성법은 커스텀 에이전트 정의 파일에서 다룹니다.

프롬프트 베이스 훅은 무엇인가

지금까지는 type: "command"에 의한 셸 명령 실행을 설명했지만, SubagentStop 훅에는 type: "prompt"라는 다른 방식도 준비되어 있습니다.

프롬프트 베이스 훅은 LLM(Haiku)을 써서 서브에이전트가 태스크를 완료했는지를 지적으로 평가합니다. 문맥을 이해한 유연한 판정이 가능한 대신, 셸 명령보다 처리 시간이 걸립니다. 대부분의 유스케이스에서는 type: "command"로 충분히 대응할 수 있으므로, 먼저 이쪽부터 시작하는 것을 추천합니다.

정리

• SubagentStop 훅은 서브에이전트의 완료 시에 발화합니다.
• Stop 훅과는 발화 타이밍(메인 에이전트 vs 서브에이전트)이 다르므로 목적에 맞게 가려 씁니다.
• matcher로 에이전트 종별(general-purpose, Explore, Plan 등)을 지정해 좁힐 수 있습니다.
• JSON 출력의 continue: false로 Claude 전체의 실행을 정지할 수도 있습니다.
• 필수가 되는 장면은 많지 않지만, 설정해 두면 로그 출력이나 실행 후 테스트 같은 유연한 후처리를 실현할 수 있습니다. 사용자 입력 자체를 다루는 훅은 UserPromptSubmit 훅에서 이어집니다.