훅
세션, 도구, 하위 에이전트 이벤트에서 스크립트를 실행합니다. 허용, 거부 또는 질문할 수 있습니다.
훅은 Spirit이 고정된 지점에서 실행하는 스크립트입니다. 도구를 허용하거나, 거부하거나, 승인 프롬프트(ask)를 강제할 수 있습니다.
이벤트
sessionStartsessionEndsubmitPromptpreToolUsepostToolUsesubagentStartsubagentEnd
preToolUse가 ask를 반환하면 자동 승인 또는 우회 상태에서도 여전히 프롬프트가 표시됩니다.
위치
| 범위 | 구성 | 스크립트 |
|---|---|---|
| 사용자 | {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에서는 하위 에이전트 유형과 일치합니다 |
예시
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "hooks/guard.sh",
"timeout": 10,
"failClosed": true,
"matcher": "^shell$"
}
],
"sessionEnd": [
{
"command": "hooks/log.sh"
}
]
}
}