Hooks
在会话、工具和子智能体事件上跑脚本。可以允许、拒绝或询问。
Hooks 是 Spirit 在固定节点跑的脚本。它们可以允许工具、拒绝工具，或强制弹出审批（ask）。
事件
sessionStartsessionEndsubmitPromptpreToolUsepostToolUsesubagentStartsubagentEnd
preToolUse 返回 ask 时，即使开了自动审批或绕过也会问你。
放在哪里
| 范围 | 配置 | 脚本 |
|---|---|---|
| 用户 | {spiritDataDir}/hooks.json | {spiritDataDir}/hooks/ |
| 工作区 | {workspace}/.spirit/hooks.json | {workspace}/.spirit/hooks/ |
同一事件上，用户条目与工作区条目会按顺序拼接，不是互相覆盖。
在 设置 → Hooks 管理。CLI 用 spirit hooks list 和 spirit hooks validate 校验。内置 Skill create-hook 可以起草。
文件字段
根对象必须包含 version 和 hooks。version 目前只接受 1。
| 参数 | 说明 |
|---|---|
version | 必填。必须为 1 |
hooks | 必填。对象。键是事件名，值是该事件下的 hook 数组 |
每条 hook
| 参数 | 说明 |
|---|---|
command | 必填。脚本路径。相对路径相对于配置所在目录，不能越出该目录 |
timeout | 可选。超时（秒）。必须为正数，默认 30 |
failClosed | 可选。脚本崩溃、超时或 stdout 不是合法 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"
}
]
}
}