用途:Task 插件的 Hook 系统用于处理会话级事件,目前只有两个官方 Hook,分别在会话启动或恢复时、会话结束时触发。任务启动、迭代、完成、失败等内部生命周期事件不使用 Hook,改由 Agent 内部逻辑处理。
主要能力:SessionStart 在会话启动或恢复时触发,用于初始化环境变量、加载配置、设置资源。SessionEnd 在会话结束时触发,可用环境变量 SESSION_ID,用于清理临时文件、归档日志、生成报告。日志写入 .claude/logs/task-hooks-{session_id}.jsonl。
使用方式:通过 plugin.json 配置 Hook,命令类型示例为 echo 'export ...' >> "$CLAUDE_ENV_FILE",可设 async: true。Hook 输入包括环境变量(如 SESSION_ID)与 stdin JSON;输出方面 stdout 为日志,stderr 为错误,退出码 0 表示成功、2 表示阻塞、其他为非阻塞。最佳实践为执行时间小于 1 秒、使用 async: true、健壮错误处理、保持幂等,默认超时 600 秒。
迁移说明(v0.0.184):移除 6 个不受官方支持的 Hook:TaskStart、IterationStart、IterationEnd、TaskComplete、TaskFailed、CheckpointSave。替代方案:TaskStart 由 Loop skill 输出 [MindFlow] 任务启动;迭代起止由 Loop skill 迭代日志;TaskComplete 由 Finalizer 生成报告;TaskFailed 由 Adjuster 记录失败;IterationEnd 指标由 Observability skill 处理;CheckpointSave 由 Checkpoint skill 日志处理。
故障排查:未触发时检查 Hook 名是否在官方列表、plugin.json 是否配置、脚本是否可执行、路径是否正确;失败时检查语法、环境变量、stderr、超时与权限。
限制:官方仅支持上述两个 Hook;内部任务事件不走 Hook;其余能力与配置细节在资料中暂未提供。