生命周期 Hooks
自 v0.7.2 起，Zagens 可在 Agent 生命周期节点运行用户定义的 shell 命令 — 用于审计、策略注入、环境变量或与企业脚本集成。
在哪里配置
| 入口 | 作用 |
|---|---|
| 设置 → Hooks | 编辑全局 ~/.zagens/config.toml 中的 [hooks]；保存后重启 sidecar |
| 项目目录 | {workspace}/.zagens/hooks.toml、.zagens/hooks.json、.cursor/hooks.json |
合并顺序： 全局 config → 项目 TOML → 项目 JSON → Cursor hooks；项目条目追加在全局之后。
常见事件
| 事件 | 阻塞？ | 触发时机 |
|---|---|---|
session_start / session_end |
否 | 会话开始 / 结束 |
message_submit |
是 | 用户消息送入模型前 |
tool_call_before / tool_call_after |
前阻塞 / 后否 | 工具执行前 / 后 |
shell_env |
否 | 每次 exec_shell 前；stdout 合并为环境变量 |
pre_compact / post_compact |
否 | 上下文压缩前 / 后 |
subagent_start / subagent_end |
前阻塞 / 后否 | 子代理 spawn 前 / 结束 |
支持 Cursor 风格别名（如 beforeShell → tool_call_before + exec_shell 过滤）。
阻塞 vs 后台
- 阻塞事件 可返回
deny或修改 stdin JSON，从而取消或改写工具/消息。 - 标记
background=true的钩子在阻塞事件上会被忽略（保证 deny 有效）。 - 每条 hook 可设超时；超时优先于全局
default_timeout_secs。
输入输出
同步 hook 从 stdin 接收 JSON 上下文（会话 id、工具名、工作区等），从 stdout 返回 JSON 动作（allow / deny / modify 等）。详见产品仓库 docs/desktop/HOOKS.md。
示例用途
tool_call_before：拒绝访问生产路径的exec_shellshell_env：注入CI=true、代理变量message_submit：脱敏或阻断含密钥的 promptsubagent_start：记录 CRAFT 子代理到企业 SIEM
建议
- 脚本保持幂等、快速失败；长任务用
tool_call_after+ 后台。 - 先在测试工作区验证，再挂生产仓库。
- 与 工具审批、Windows 沙箱 叠加使用，而非替代。