# 훅
URL: /ko/docs/customize/hooks

세션, 도구, 하위 에이전트 이벤트에서 스크립트를 실행합니다. 허용, 거부 또는 질문할 수 있습니다.



훅은 Spirit이 고정된 지점에서 실행하는 스크립트입니다. 도구를 허용하거나, 거부하거나, 승인 프롬프트(`ask`)를 강제할 수 있습니다.

## 이벤트 [#이벤트]

* `sessionStart`
* `sessionEnd`
* `submitPrompt`
* `preToolUse`
* `postToolUse`
* `subagentStart`
* `subagentEnd`

`preToolUse`가 `ask`를 반환하면 [자동 승인 또는 우회](../agent/approvals.mdx) 상태에서도 여전히 프롬프트가 표시됩니다.

## 위치 [#위치]

| 범위   | 구성                               | 스크립트                         |
| ---- | -------------------------------- | ---------------------------- |
| 사용자  | `{spiritDataDir}/hooks.json`     | `{spiritDataDir}/hooks/`     |
| 작업공간 | `{workspace}/.spirit/hooks.json` | `{workspace}/.spirit/hooks/` |

같은 이벤트에서 사용자 항목과 작업공간 항목은 해당 순서로 연결됩니다. 서로 덮어쓰지 않습니다.

**설정 → 훅**에서 관리하세요. CLI에서 `spirit hooks list` 및 `spirit hooks validate`로 검증하세요. 내장 Skill `create-hook`이 훅 초안을 작성합니다.

## 파일 필드 [#파일-필드]

루트 객체에는 `version`과 `hooks`가 포함되어야 합니다. `version`은 현재 `1`만 허용합니다.

| 필드        | 설명                                     |
| --------- | -------------------------------------- |
| `version` | 필수. `1`이어야 합니다                         |
| `hooks`   | 필수. 객체. 키는 이벤트 이름이고 값은 해당 이벤트의 훅 배열입니다 |

### 각 훅 [#각-훅]

| 필드           | 설명                                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `command`    | 필수. 스크립트 경로. 상대 경로는 구성 디렉터리를 기준으로 해석되며 그 안에 있어야 합니다                                                                 |
| `timeout`    | 선택. 시간 제한(초). 양수여야 합니다. 기본값은 `30`입니다                                                                                |
| `failClosed` | 선택. 스크립트가 충돌하거나 시간 초과되거나 표준 출력에 잘못된 JSON을 쓰는 경우 차단할지 여부. 기본값은 차단하지 않음                                               |
| `matcher`    | 선택. 비어 있지 않은 정규식. `preToolUse` / `postToolUse`에서는 도구 이름과 일치하고, `subagentStart` / `subagentEnd`에서는 하위 에이전트 유형과 일치합니다 |

## 예시 [#예시]

```json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "hooks/guard.sh",
        "timeout": 10,
        "failClosed": true,
        "matcher": "^shell$"
      }
    ],
    "sessionEnd": [
      {
        "command": "hooks/log.sh"
      }
    ]
  }
}
```