Hooks

Hooks 在智能体生命周期的固定节点运行你的命令 —— 审计日志、编辑即 lint、策略闸门、通知。一个 hook 就是一条 shell 命令:stdin 收事件 JSON,某些事件还能经输出阻断动作或注入上下文。

事件

事件	触发时机	可阻断?
SessionStart	会话开始(REPL、exec、serve、ACP)	—
UserPromptSubmit	你提交提示、模型看到之前	✅ 阻断,或加上下文
PreToolUse	工具调用执行前	✅ 阻断该调用
PostToolUse	工具调用返回后	—(可加上下文)
Stop	回合完成	—
SessionEnd	会话结束	—

Hooks 在所有路径触发 —— 交互 REPL、无头 exec、serve 会话与任务、ACP 连接、stream-json SDK 宿主。

配置

在 <原生配置根目录>/config.json(或标准 settings 层)里；原生根按 HIPMMCODE_CONFIG_DIR → 否则 CLAUDE_CONFIG_DIR（v0.16.0+）→ 否则 HIPMMCODE_HOME → 否则 ~/.hipmmcode 解析:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "/usr/local/bin/audit-bash.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "FileEdit|FileWrite",
        "hooks": [{ "type": "command", "command": "npx prettier --write \"$FILE\" 2>/dev/null || true" }]
      }
    ],
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "echo session-started >> ~/audit.log" }] }
    ]
  }
}

• matcher —— 工具名上的正则(工具类事件);省略则匹配全部。
• 每个 hook 的 stdin 收到事件 JSON:会话 id、cwd、事件名、工具名 + 输入(工具事件)、提示内容(UserPromptSubmit)、工具结果(PostToolUse)。
• 环境:注入原生 HIPMMCODE_SESSION_ID、HIPMMCODE_TURN、HIPMMCODE_PROJECT_DIR，以及在适用时注入 HIPMMCODE_PLUGIN_ROOT / HIPMMCODE_PLUGIN_DATA。外部 hook/plugin 协议需要时也会同时导出对应 CLAUDE_* 字段，保证旧集成兼容。

用 hook 控制智能体

退出码与 stdout 决定后续:

Hook 结果	效果
exit 0,stdout 空	正常继续
exit 0,stdout JSON { "decision": "block", "reason": "…" }	阻断该提示/工具调用;reason 展示给模型
exit 0,stdout JSON { "additionalContext": "…" }	向回合注入上下文
exit 2	阻断(简写)—— stderr 作为 reason

查看

/hooks            # REPL 里列出已配置 hooks

无头流式运行可用 --include-hook-events 把 hook 活动作为事件输出。

Killswitch

托管环境:disableAllHooks 全关;allowManagedHooksOnly 只允许策略定义的 hooks。--safe-mode 单次运行也会禁用 hooks(排障)。

WARNING

Hooks 以你的凭证执行任意 shell 命令,而触发它们的事件受模型影响。像对待其他特权自动化一样对待 hook 脚本:审查内容、用绝对路径、别放在全局可写目录。