Bug Report: SessionEnd/Stop Hooks 无法正常工作 - 环境变量未设置且触发不稳定
概述
iFlow CLI v0.5.13 的 hook 系统存在两个关键问题：
- 环境变量
IFLOW_HOOK_EVENT_NAME从未被设置 — Hook 被调用但无法判断是哪个事件触发的 - SessionEnd/Stop hook 触发不稳定 — 有时触发，有时不触发
环境信息
- iFlow CLI 版本: 0.5.13
- 操作系统: Windows 10 (win32 10.0.19045)
- Python 版本: 3.13.2
问题 1: IFLOW_HOOK_EVENT_NAME 环境变量未设置
描述
根据文档 (docs_cn/examples/hooks.md)，hook 应该通过 IFLOW_HOOK_EVENT_NAME 环境变量接收事件名称。但是，当 hook 被调用时，这个变量从未被设置。
证据
调试日志显示 hook 接收到的环境变量：
[2026-02-22 11:05:31] Hook triggered: event=, all_iflow_envs={'IFLOW_AONE': 'false', 'IFLOW_CWD': 'E:\\Bak\\Users\\LG\\Documents\\Cli\\TTS', 'IFLOW_PROJECT_DIR': 'E:\\Bak\\Users\\LG\\Documents\\Cli\\TTS', 'IFLOW_SESSION_ID': 'session-dde90bd0-175f-4923-b840-9ebd126cbef4', 'IFLOW_TRANSCRIPT_PATH': '...'}
注意 event= 是空的，而且 all_iflow_envs 中没有 IFLOW_HOOK_EVENT_NAME。
预期行为
IFLOW_HOOK_EVENT_NAME 环境变量应该被设置为以下值之一：
PreToolUsePostToolUseSessionEndStop
实际行为
IFLOW_HOOK_EVENT_NAME 从未被设置，导致 hook 无法知道是哪个事件触发了调用。
临时解决方案
我们实现了启发式方法来检测事件类型：
- 检查是否有 stdin 数据（PreToolUse/PostToolUse 有 stdin 数据）
- 检查 stdin 数据内容（PostToolUse 包含
error或result字段） - 无 stdin 数据则为 SessionEnd/Stop
问题 2: SessionEnd/Stop Hook 触发不稳定
描述
SessionEnd 和 Stop hook 在会话结束时不稳定触发。有时正常工作，有时完全不触发。
复现步骤
- 在
.iflow/settings.json中配置SessionEnd或Stophook - 启动 iFlow CLI 会话
- 使用以下方式之一结束会话：
/exit命令- 连续两次 Ctrl+C
- 检查 hook 是否被触发
证据
成功触发 SessionEnd：
[2026-02-22 11:07:49] Hook triggered: env_event=, all_iflow_envs={'IFLOW_CLI': '1'}
[2026-02-22 11:07:49] Detected event type: SessionEnd
[2026-02-22 11:07:49] SessionEnd/Stop handler called (detected)
未触发 SessionEnd（会话结束但没有 hook 调用）：
[2026-02-22 11:20:34] Hook triggered: ... session-dde90bd0 ...
[2026-02-22 11:21:42] Hook triggered: ... session-d06a1667 ... # 新会话开始了
注意两个会话之间没有 SessionEnd 事件。会话 dde90bd0 结束了，但没有触发 SessionEnd/Stop hook。
预期行为
SessionEnd hook 应在以下情况触发：
- 用户执行
/exit命令 - 用户执行
/bye或/quit命令
Stop hook 应在以下情况触发：
- 用户连续按两次 Ctrl+C
- 主会话因任何原因结束
实际行为
SessionEnd/Stop hook 触发不稳定：
- 有时触发（11:07:49, 11:18:19）
- 有时不触发（11:20:34 和 11:21:42 之间）
Hook 配置
文件: .iflow/settings.json
{
"hooks": {
"SessionEnd": [
{
"command": "python",
"args": [".iflow/hooks/tts_project_hook.py"]
}
],
"Stop": [
{
"command": "python",
"args": [".iflow/hooks/tts_project_hook.py"]
}
],
"PreToolUse": [
{
"command": "python",
"args": [".iflow/hooks/tts_project_hook.py"]
}
],
"PostToolUse": [
{
"command": "python",
"args": [".iflow/hooks/tts_project_hook.py"]
}
]
}
}
调试日志
[2026-02-22 11:05:31] Hook triggered: event=, all_iflow_envs={'IFLOW_AONE': 'false', ...}
[2026-02-22 11:07:39] stdin data detected, length=43777
[2026-02-22 11:07:39] Detected event type: PreToolUse
[2026-02-22 11:07:49] Hook triggered: env_event=, all_iflow_envs={'IFLOW_CLI': '1'}
[2026-02-22 11:07:49] Detected event type: SessionEnd ✅ 成功触发
[2026-02-22 11:07:49] SessionEnd/Stop handler called (detected)
[2026-02-22 11:18:19] Hook triggered: env_event=, all_iflow_envs={'IFLOW_CLI': '1'}
[2026-02-22 11:18:19] Detected event type: SessionEnd ✅ 成功触发
[2026-02-22 11:20:34] Hook triggered: ... session-dde90bd0 ...
[2026-02-22 11:20:34] Detected event type: PreToolUse
[2026-02-22 11:21:42] Hook triggered: ... session-d06a1667 ... ❌ 新会话开始，但上一会话没有 SessionEnd
[2026-02-22 11:21:42] Detected event type: PreToolUse
影响
这些 bug 导致无法可靠地实现：
- 会话清理任务
- 会话结束通知
- 文档更新提醒
- 会话间状态持久化
建议修复方案
- 问题 1：确保在调用 hook 脚本前设置
IFLOW_HOOK_EVENT_NAME环境变量 - 问题 2：确保无论会话如何结束，SessionEnd/Stop hook 都能被触发
相关文档
docs_cn/examples/hooks.md— 文档说明了 hook 系统和IFLOW_HOOK_EVENT_NAME变量docs_cn/changelog.md— SessionEnd 和 Stop hook 在 v0.2.30 (2025-09-24) 版本添加