# HOOK.yaml - Hook 配置示例模板
#
# 此文件为模板示例，展示了 HOOK.yaml 的完整配置格式。
# 创建新 hook 时，复制此目录结构并修改：
#   .jcli/hooks/<your_hook_name>/HOOK.yaml
#
# 注意：文件名支持 HOOK.yaml 或 HOOK.yml，两者共存时优先取 HOOK.yaml。
#
# Hook 目录结构：
# .jcli/hooks/<hook_name>/
# ├── HOOK.yaml      # hook 定义（也支持 HOOK.yml）
# └── script.sh      # 可选脚本（bash hook 可直接用文件名调用）
#
# Hook 支持三级来源：
# 1. 项目级：.jcli/hooks/<hook_name>/HOOK.yaml
# 2. 用户级：~/.jdata/agent/hooks/<hook_name>/HOOK.yaml
# 3. 会话级：通过 RegisterHook 工具动态注册

# ============================================
# 字段说明
# ============================================

# events: [必填] 绑定的事件列表，一个 hook 可绑定多个事件
# 可用事件：
#   - pre_send_message             # 用户发送消息前（可修改 user_input）
#   - post_send_message            # 用户发送消息后（仅通知）
#   - pre_llm_request              # LLM API 请求前（可修改 messages、system_prompt）
#   - post_llm_response            # LLM 回复完成后（可修改 assistant_output）
#   - pre_tool_execution           # 工具执行前（可修改 tool_arguments，action=skip）
#   - post_tool_execution          # 工具执行成功后（可修改 tool_result）
#   - post_tool_execution_failure  # 工具执行失败后（可修改 tool_error）
#   - stop                         # LLM 即将结束回复
#   - pre_micro_compact            # 轮次级压缩前
#   - post_micro_compact           # 轮次级压缩后
#   - pre_auto_compact             # 全量压缩前
#   - post_auto_compact            # 全量压缩后
#   - session_start                # 会话启动时
#   - session_end                  # 会话退出时

# type: [可选] hook 类型，默认 bash
#   - bash: 通过 sh -c 执行 Shell 命令
#   - llm:  通过 prompt 模板调用 LLM

# command: [type=bash 时必填] Shell 命令
#   - hook 目录在 PATH 中，脚本可直接用文件名调用

# prompt: [type=llm 时必填] LLM prompt 模板
#   - 支持模板变量：{{event}}, {{user_input}}, {{assistant_output}},
#     {{tool_name}}, {{tool_arguments}}, {{tool_result}}, {{model}}, {{cwd}}

# model: [type=llm 时可选] 覆盖当前使用的模型名

# timeout: [可选] 超时秒数，bash 默认 10，llm 默认 30

# retry: [可选] 重试次数，默认 0（bash）/ 1（llm）

# on_error: [可选] 失败策略，默认 skip
#   - skip:  记录日志继续执行后续 hook
#   - stop: 中止整条 hook 链

# filter: [可选] 条件过滤，仅当匹配时执行
#   - tool_name: 工具名精确匹配
#   - tool_matcher: 工具名模式匹配（管道分隔，如 "Bash|Write|Edit"）
#   - model_prefix: 模型名前缀匹配

# ============================================
# 示例配置（取消注释即可使用）
# ============================================

# --- 示例 1：Bash hook - 基础配置 ---
# events: [pre_send_message]
# type: bash
# command: script.sh
# timeout: 5
# on_error: skip

# --- 示例 2：LLM hook - AI 回复纠查官 ---
# events: [post_llm_response]
# type: llm
# prompt: |
#   检查以下 AI 回复是否包含敏感信息（密码、密钥、token）：
#   {{assistant_output}}
#   如果包含敏感信息，返回 {"action":"stop","retry_feedback":"请移除敏感信息"}。
#   如果没有问题，返回空 JSON {}。
# timeout: 30
# retry: 1
# on_error: skip

# --- 示例 3：多事件绑定 ---
# events: [pre_send_message, post_send_message]
# type: bash
# command: log.sh
# timeout: 5

# --- 示例 4：带过滤器的工具审查 ---
# events: [pre_tool_execution]
# type: llm
# prompt: |
#   审查工具调用是否安全：工具={{tool_name}}, 参数={{tool_arguments}}
#   如果不安全，返回 {"action":"skip"}。
#   如果安全，返回 {}。
# filter:
#   tool_matcher: "Bash|Shell"
# timeout: 15
# retry: 1

# --- 示例 5：消息审查 + 指定模型 ---
# events: [pre_send_message]
# type: llm
# prompt: |
#   审查用户消息是否合规：{{user_input}}
#   如有违规返回 {"action":"stop","retry_feedback":"消息不合规：原因"}。
# model: gpt-4o-mini
# timeout: 15
# retry: 1

# ============================================
# HookResult JSON 字段参考（脚本 stdout 返回）
# ============================================
#
# 返回的 JSON 只包含要修改的字段，空 {} 表示无修改：
#
# | 字段               | 生效事件                                | 说明 |
# |--------------------|-----------------------------------------|------|
# | user_input         | pre_send_message                        | 替换用户消息 |
# | assistant_output   | post_llm_response                       | 替换 AI 回复 |
# | messages           | pre_llm_request, post_*_compact         | 替换消息列表 |
# | system_prompt      | pre_llm_request                         | 替换系统提示词 |
# | tool_arguments     | pre_tool_execution                      | 替换工具参数 |
# | tool_result        | post_tool_execution                     | 替换工具结果 |
# | tool_error         | post_tool_execution_failure             | 替换错误信息 |
# | inject_messages    | pre_llm_request                         | 追加消息到末尾 |
# | retry_feedback     | pre*/stop/post_llm_response             | 带反馈重试 |
# | additional_context | pre_llm_request, stop, pre_auto_compact | 追加到 system_prompt |
# | system_message     | 所有事件                                | 展示给用户的提示 |
# | action             | 大部分事件                              | "stop" 中止 / "skip" 跳过 |
#
# 完整文档请运行：jcli ai help hook
