# Hooks
URL: /zh-CN/docs/customize/hooks

在会话、工具和子智能体事件上跑脚本。可以允许、拒绝或询问。



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/` |

同一事件上，用户条目与工作区条目会按顺序拼接，不是互相覆盖。

在 **设置 → Hooks** 管理。CLI 用 `spirit hooks list` 和 `spirit hooks validate` 校验。内置 Skill `create-hook` 可以起草。

## 文件字段 [#文件字段]

根对象必须包含 `version` 和 `hooks`。`version` 目前只接受 `1`。

| 参数        | 说明                          |
| --------- | --------------------------- |
| `version` | 必填。必须为 `1`                  |
| `hooks`   | 必填。对象。键是事件名，值是该事件下的 hook 数组 |

### 每条 hook [#每条-hook]

| 参数           | 说明                                                                                  |
| ------------ | ----------------------------------------------------------------------------------- |
| `command`    | 必填。脚本路径。相对路径相对于配置所在目录，不能越出该目录                                                       |
| `timeout`    | 可选。超时（秒）。必须为正数，默认 `30`                                                              |
| `failClosed` | 可选。脚本崩溃、超时或 stdout 不是合法 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"
      }
    ]
  }
}
```