name: configure-hooks description: 为ADW可观察性配置基于钩子的事件处理。在设置PreToolUse、PostToolUse或其他钩子用于工作流监控时使用。 argument-hint: <hook-type> [configuration] allowed-tools: Read, Write, Glob, Grep

配置钩子

为AI开发者工作流可观察性配置基于钩子的事件处理。

参数

$ARGUMENTS: <hook-type> [configuration]
- hook-type: 钩子类型 (PreToolUse, PostToolUse, Notification, Stop)
- configuration: 可选的JSON配置或描述

钩子类型

文档验证： 钩子事件类型是Claude Code内部类型，可能在不同版本间变化。有关权威的当前事件类型，请通过hook-management技能 → docs-management验证。

钩子	触发时机	使用案例
`PreToolUse`	工具执行前	捕获意图，验证
`PostToolUse`	工具执行后	捕获结果，总结
`Notification`	工作流事件	警报，日志，广播
`Stop`	错误条件	停止执行

指令

步骤1：识别钩子需求

确定需要捕获哪些事件：

常见场景：

可观察性： 捕获所有工具调用以进行监控
成本跟踪： 跟踪每个工作流的令牌使用情况
调试： 记录决策点以供审查
广播： 将事件流式传输到外部系统

步骤2：设计钩子配置

在settings.json格式中创建钩子配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python /path/to/pre_tool_hook.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python /path/to/post_tool_hook.py"
          }
        ]
      }
    ]
  }
}

步骤3：创建钩子脚本模板

根据类型生成钩子脚本：

PreToolUse脚本：

#!/usr/bin/env python3
"""PreToolUse hook for ADW observability."""
import json
import sys
import os

def main():
    # Read hook input from stdin
    input_data = json.load(sys.stdin)

    tool_name = input_data.get("tool_name", "unknown")
    tool_input = input_data.get("tool_input", {})
    adw_id = os.environ.get("ADW_ID", "no-adw")

    # Log event
    event = {
        "type": "PreToolUse",
        "adw_id": adw_id,
        "tool": tool_name,
        "input_preview": str(tool_input)[:100]
    }

    # Write to log or broadcast
    with open(f"agents/{adw_id}/events.jsonl", "a") as f:
        f.write(json.dumps(event) + "
")

    # Return decision (continue or block)
    print(json.dumps({"decision": "continue"}))

if __name__ == "__main__":
    main()

PostToolUse脚本：

#!/usr/bin/env python3
"""PostToolUse hook for ADW observability."""
import json
import sys
import os

def main():
    # Read hook input from stdin
    input_data = json.load(sys.stdin)

    tool_name = input_data.get("tool_name", "unknown")
    tool_result = input_data.get("tool_result", "")
    adw_id = os.environ.get("ADW_ID", "no-adw")

    # Log event
    event = {
        "type": "PostToolUse",
        "adw_id": adw_id,
        "tool": tool_name,
        "result_preview": str(tool_result)[:200]
    }

    # Write to log or broadcast
    with open(f"agents/{adw_id}/events.jsonl", "a") as f:
        f.write(json.dumps(event) + "
")

if __name__ == "__main__":
    main()

步骤4：环境变量设置

定义ADW上下文变量：

export ADW_ID="a1b2c3d4"
export ADW_STEP="build"
export ADW_WORKFLOW="plan_build_review"
export ADW_OUTPUT_DIR="agents/${ADW_ID}"

步骤5：创建输出目录

确保事件输出位置存在：

mkdir -p agents/${ADW_ID}

输出

## 钩子配置报告

**钩子类型：** {hook_type}
**配置：** {config}

### 生成的文件

| 文件 | 用途 |
| --- | --- |
| `hooks/pre_tool_hook.py` | PreToolUse事件捕获 |
| `hooks/post_tool_hook.py` | PostToolUse事件捕获 |

### 设置配置

```json
{settings snippet}

环境变量

变量	值	目的
ADW_ID	{id}	工作流关联
ADW_STEP	{step}	当前步骤上下文
ADW_OUTPUT_DIR	{path}	事件输出位置

验证

运行测试命令以验证钩子触发：

# In Claude Code session with hooks configured
echo "Test hook" > /dev/null
# Check agents/{adw_id}/events.jsonl for captured events

后续步骤

添加钩子脚本到版本控制
用钩子条目配置settings.json
用示例ADW执行进行测试
添加WebSocket广播（参见/broadcast-event）

事件负载

PreToolUse负载

{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.py",
    "content": "..."
  }
}

PostToolUse负载

{
  "tool_name": "Write",
  "tool_input": {...},
  "tool_result": "File written successfully"
}

交叉引用

@hook-event-patterns.md - 事件类型和负载
@websocket-architecture.md - 广播事件
hook-event-architecture 技能 - 事件系统设计
event-broadcaster 代理 - 广播设计