feat: add AgentHooks support for dogfooding

[IndenScale]

This PR adds AgentHooks support to kimi-cli for dogfooding purposes.

Changes

• Add hooks discovery, parser, executor, and manager modules
• Add built-in hooks for:
  • block-dangerous-commands: Security hook blocking dangerous shell commands
  • enforce-tests: Quality gate (checks test existence)
  • auto-format-python: Auto-format Python files after write
  • session-logger / session-logger-end: Session auditing hooks
• Hook events: pre-session, post-session, pre-agent-turn, post-agent-turn, pre-agent-turn-stop, pre-tool-call, post-tool-call, etc.
• New: Add /hooks slash command to display loaded hooks and their statistics
• Refactor: Remove legacy trigger name aliases (backward compatibility code)
  • Remove TRIGGER_ALIASES mapping
  • Remove normalize_trigger() function
  • Use canonical trigger names only

Notes

• enforce-tests hook checks for test directory existence (doesn't run tests)
• All hooks follow the AgentHooks protocol with exit codes: 0=allow, 2=block
• Hooks can be configured at user level (~/.config/kimi/hooks/) or project level (.agents/hooks/)

---

[IndenScale]

🔧 Devin Review 修复已完成

已根据 Devin Review 的反馈修复了 4 个问题：

修复摘要

级别	文件	问题	修复方式
🔴		对非 JSON 序列化输入崩溃	添加 参数
🔴		缓存的 ToolResult 包含过时的	只缓存 ，返回时构造新的 ToolResult
🟡		在 时错误匹配	当设置了 pattern 但值为 None 时返回 False
🔴		hook 可能导致无限 LLM 调用	添加限制（最多 3 次阻止）

详细说明

1. 非 JSON 序列化输入处理 - 与 executor 第 91 行的做法保持一致
2. tool_call_id 修复 - Devin 建议的方法：缓存决策理由而非完整 ToolResult
3. Matcher 逻辑修正 - 确保配置了 tool pattern 但没有提供 tool_name 时正确返回不匹配
4. before_stop 限制 - 防止 misconfigured hook 浪费过多 API 调用

所有修复均已验证通过。

---

🔧 Devin Review Fix completed

4 issues have been fixed based on feedback from Devin Review:

Fix summary

Level	File	Problem	Fix
🔴		Crash on non-JSON serialized input	Add parameters
🔴		Cached ToolResult containing stale	Cache only, construct new ToolResult on return
🟡		False match when	Returns False when pattern is set but the value is None
🔴		Hook may cause unlimited LLM calls	Add limit (max 3 blocks)

Detailed description

1. Non-JSON serialized input handling - consistent with executor line 91
2. tool_call_id fix - Devin's suggested approach: cache decision reasons instead of full ToolResult
3. Matcher logic correction - Ensure that a mismatch is correctly returned when tool pattern is configured but tool_name is not provided.
4. before_stop limit - prevent misconfigured hooks from wasting too many API calls

All fixes have been verified.

[IndenScale]

🔧 Devin Review 第二轮修复已完成

已根据第二轮反馈修复了 3 个新问题：

修复摘要

级别	文件	问题	修复方式
🔴	executor.py	路径空格导致 hook 静默失效	使用 create_subprocess_exec 替代 create_subprocess_shell
🟡	kimisoul.py	_total_steps 从未递增	在 _step() 成功后调用 increment_step_count()
🟡	toolset.py	ToolHookCache 永久缓存	完全移除缓存机制（非 AgentHooks 规范要求）

详细说明

1. create_subprocess_exec - 避免路径包含空格时 shell 错误解析导致安全 hook 被绕过
2. increment_step_count() - 确保 session_end hooks 收到准确的 total_steps 数据
3. 移除 ToolHookCache - 缓存不是 AgentHooks 规范的一部分，且可能导致误报无法恢复

请重新扫描确认所有问题已修复。

---

🔧 Devin Review Round 2 Fix Completed

Fixed 3 new issues from the second round of review:

Level	File	Issue	Fix
🔴	executor.py	Paths with spaces cause silent hook failure	Use create_subprocess_exec instead of create_subprocess_shell
🟡	kimisoul.py	_total_steps never incremented	Call increment_step_count() after _step() succeeds
🟡	toolset.py	ToolHookCache permanent caching	Remove caching entirely (not in AgentHooks spec)

Please rescan to verify all issues are resolved.

[IndenScale]

🔄 更新：钩子触发器命名标准化

本次推送对钩子事件命名进行了系统性重构，采用统一的 pre/post-event 模式：

命名变更对照表

旧命名 (Legacy)	新命名 (Canonical)	说明
session_start	pre-session	会话开始前
session_end	post-session	会话结束后
before_agent	pre-agent-turn	Agent 轮次开始前
after_agent	post-agent-turn	Agent 轮次结束后
before_tool	pre-tool-call	工具调用前
after_tool	post-tool-call	工具调用后
after_tool_failure	post-tool-call-failure	工具调用失败后
subagent_start	pre-subagent	子 Agent 启动前
subagent_stop	post-subagent	子 Agent 结束后
pre_compact	pre-context-compact	上下文压缩前
before_stop	pre-agent-turn-stop	Agent 停止前（Quality Gate）
-	post-agent-turn-stop	Agent 停止后（新增）
-	post-context-compact	上下文压缩后（新增）

主要改动

1. 标准化命名：所有事件采用 {timing}-{entity}[-qualifier] 统一格式
2. 向后兼容：旧命名作为别名保留，现有钩子无需修改
3. 新增事件：post-agent-turn-stop, post-context-compact
4. 异步执行优化：新增 fire_and_forget() 用于后台执行异步钩子
5. 代码简化：重构 HookManager，移除 asyncio task 跟踪

影响范围

• agenthooks/hooks-ref/src/agenthooks_ref/models.py - 更新 HookEventType 枚举
• src/kimi_cli/hooks/ - 核心钩子模块更新
• src/kimi_cli/soul/ - KimiSoul 钩子调用点更新
• 所有内置钩子定义和文档

所有旧命名仍然可用，无需修改现有钩子配置。

[IndenScale]

📦 agenthooks 参考实现已同步更新

独立仓库（https://github.com/IndenScale/agenthooks）也已推送同步更新：

• 更新 HookEventType 枚举，添加新的 canonical 事件名和 legacy 别名
• 更新 SPECIFICATION.md 文档，统一使用新的命名规范
• 更新所有示例钩子（auto-format-hook, notify-hook, security-hook）
• 保持向后兼容：旧命名作为别名保留

提交：81902cb - refactor: standardize hook triggers with pre/post-event pattern

[IndenScale]

🔧 Devin Review 第三轮修复已完成

已根据最新反馈修复了 4 个问题：

修复摘要

级别	文件	问题	修复方式
🟡		Message.content (Pydantic 模型) 非 JSON 可序列化	使用 显式转换 ContentPart
🔴		hooks 不触发	根据 error 动态选择事件类型
🔴		hooks 覆盖用户工具拒绝	仅对 执行 hooks
🟡		超时后产生僵尸进程	后添加

详细说明

1. Message.content 序列化 - Pydantic ContentPart 模型现在使用 正确序列化为 JSON，hook 脚本可正常解析
2. post-tool-call-failure 事件 - 工具失败时现在正确触发 钩子，符合 AgentHooks 规范
3. 用户拒绝保护 - 停止原因不再被 hooks 覆盖，尊重用户明确决策
4. 僵尸进程修复 - 遵循 Python asyncio 最佳实践，确保子进程资源完全回收

Commit:

所有相关测试通过 (71 passed)。

---

🔧 Devin Review The third round of repairs has been completed

4 issues have been fixed based on latest feedback:

Fix summary

Level	File	Problem	Fix
🟡		Message.content (Pydantic model) non-JSON serializable	Use explicit conversion ContentPart
🔴		Hooks are not triggered	Dynamically select event type based on error
🔴		hooks override user tool denial	Execute hooks only for
🟡		Spawn zombie process after timeout	Add later

Detailed description

1. Message.content serialization - Pydantic ContentPart model is now correctly serialized to JSON, and the hook script can be parsed normally
2. post-tool-call-failure event - the hook is now correctly triggered when the tool fails, compliant with the AgentHooks specification
3. User Rejection Protection - The reason for stopping is no longer covered by hooks, respecting the user’s clear decision-making
4. Zombie process fix - Follow Python asyncio best practices to ensure that child process resources are fully recycled

Commit:

All relevant tests passed (71 passed).

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 32 additional findings in Devin Review.

[devin-ai-integration]

🔴 Matcher pattern matching on str(dict) breaks anchored regex patterns like \.py$

The Matcher.matches() method converts the entire arguments dict to a string via str() before applying re.search(). This means str({"file_path": "/tmp/test.py", "content": "..."}) produces "{'file_path': '/tmp/test.py', 'content': '...'}"—a string ending with }, not .py. Anchored patterns such as \.py$ will therefore never match.

Root Cause and Impact

The Matcher is used in src/kimi_cli/hooks/manager.py:176 to pre-filter which hooks fire for a given event. The auto-format-python hook at .agents/hooks/auto-format-python/HOOK.md:7 specifies pattern: "\\.py$", intending to match only Python files. But because Matcher.matches() at src/kimi_cli/hooks/parser.py:199 does:

if arguments is None or not self.arg_pattern.search(str(arguments)):
    return False

the $ anchor requires the entire dict string to end with .py, which it never will (it ends with }). This silently disables any hook whose matcher uses anchored patterns ($, ^). Specifically, auto-format-python will never fire for Python files. Non-anchored patterns (e.g., rm -rf /|mkfs) are unaffected because re.search finds them anywhere in the string.

Impact: Hooks relying on anchored regex patterns in matcher.pattern are silently broken and will never be executed.

Prompt for agents

Fix the Matcher.matches() method in src/kimi_cli/hooks/parser.py lines 192-202 so that the arg_pattern is tested against individual string values of the arguments dict (not the str() of the entire dict). For example, when arguments is a dict, iterate over the values and apply re.search to each string value. If any value matches, return True for the pattern check. This ensures anchored patterns like '\.py$' work correctly when matching against individual values like file paths. If arguments is not a dict, fall back to str(arguments) as currently done.

---

Was this helpful? React with 👍 or 👎 to provide feedback.