Skip to main content

Hooks

ℹ️Note

本文以 Careti 为基准，遵循 Careti v3.38.1 合并版本。如有 Hook 范围、认证/路由、日志/遥测差异，会以 <Note> 标注。

ℹ️Note

Careti 账号/组织 Hooks 可能包含账号信息，参见 caret-docs/features/f04-caret-account.md。日志/遥测使用 caret-src/utils/。

Hooks 可以在关键时刻注入逻辑：在执行前校验操作、在执行后记录结果，并为后续决策补充上下文。

⚠️Warning

Hooks 目前仅支持 macOS 与 Linux，Windows 暂不支持。

开始使用​

Hooks in action

启用 Hooks

在 Careti 设置中勾选 "Enable Hooks"。

路径：

  1. 打开 Careti
  2. 右上角 Settings
  3. 左侧 Feature
  4. 启用 Enable Hooks

选择 Hook 位置

个人/组织级 Hooks:

  • ~/Documents/.agents/hooks/

项目级 Hooks:

  • .agents/hooks/
  • 仅作用于当前工作区

创建第一个 Hook

Hook 文件必须使用准确文件名(无扩展名)：

vim .agents/hooks/TaskStart
#!/usr/bin/env bash
input=$(cat)
echo "$input" | jq .
echo "$input" | jq -r '.timestamp | type'
chmod +x .agents/hooks/TaskStart

测试 Hook

启动任务并确认 Hook 执行。

💡Tip

建议先从仅记录日志的 Hook 开始。

可实现的能力​

智能代码审查

保存前运行 lint 或校验，阻止问题操作。

安全策略

阻止违反安全策略的操作并记录审计。

开发分析

统计操作耗时与模式，生成报表。

集成中心

将 Hook 作为与外部系统的粘合层。

Hook 类型​

ℹ️Note

以下 Hook 名称是文件名，必须严格一致。

共通字段：clineVersion, hookName, timestamp, taskId, workspaceRoots, userId。

工具执行​

PreToolUse​

输入字段:

{
  "clineVersion": "string",
  "hookName": "PreToolUse",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "preToolUse": {
    "toolName": "string",
    "parameters": {}
  }
}

PostToolUse​

输入字段:

{
  "clineVersion": "string",
  "hookName": "PostToolUse",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "postToolUse": {
    "toolName": "string",
    "parameters": {},
    "result": "string",
    "success": boolean,
    "executionTimeMs": number
  }
}

用户交互​

UserPromptSubmit​

输入字段:

{
  "clineVersion": "string",
  "hookName": "UserPromptSubmit",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "userPromptSubmit": {
    "prompt": "string",
    "attachments": ["string"]
  }
}

任务生命周期​

TaskStart​

输入字段:

{
  "clineVersion": "string",
  "hookName": "TaskStart",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskStart": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string",
      "initialTask": "string"
    }
  }
}

TaskResume​

输入字段:

{
  "clineVersion": "string",
  "hookName": "TaskResume",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskResume": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string"
    },
    "previousState": {
      "lastMessageTs": "string",
      "messageCount": "string",
      "conversationHistoryDeleted": "string"
    }
  }
}

TaskCancel​

输入字段:

{
  "clineVersion": "string",
  "hookName": "TaskCancel",
  "timestamp": "string",
  "taskId": "string",
  "workspaceRoots": ["string"],
  "userId": "string",
  "taskCancel": {
    "taskMetadata": {
      "taskId": "string",
      "ulid": "string",
      "completionStatus": "string"
    }
  }
}

系统事件​

JSON 通信​

Hooks 通过 stdin 接收 JSON 并通过 stdout 返回 JSON。

{
  "cancel": false,
  "contextModification": "WORKSPACE_RULES: Use TypeScript",
  "errorMessage": "Error details if blocking"
}

stdout 可输出日志，但最后一行必须是 JSON。

#!/usr/bin/env bash
echo "Processing hook..."
echo "Tool: $tool_name"
echo '{"cancel": false}'

cancel 控制是否阻止执行；contextModification 会影响后续决策。

上下文时机​

  1. AI 已做出当前决定
  2. Hook 可阻止或允许
  3. 注入上下文
  4. 下一次请求生效

故障排查​

Hook 未运行​

  • 确认已启用 Enable Hooks
  • 文件可执行(chmod +x)
  • 检查语法错误
  • 查看 VS Code 输出面板

Hook 超时​

  • 减少脚本复杂度
  • 避免网络调用

上下文未生效​

上下文只影响下一次请求。需要立即阻止时，请在 PreToolUse 中返回 cancel: true。

JSON 字符串中的引号​

#!/usr/bin/env bash
output='{"foo":"bar"}'
jq -n --arg ctx "$output" '{cancel: false, contextModification: $ctx}'
⚠️Warning

Hooks 具有与 VS Code 相同权限，可访问工作区文件与环境变量，请谨慎启用。

相关功能​