hook-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SKILL: Hook Creator

技能：钩子创建器

LIBRARY-FIRST PROTOCOL (MANDATORY)

库优先协议（强制要求）

Before writing ANY code, you MUST check:

在编写任何代码之前，你必须完成以下检查：

Step 1: Library Catalog

步骤1：库目录

Location:
```
.claude/library/catalog.json
```
If match >70%: REUSE or ADAPT

位置：
```
.claude/library/catalog.json
```
匹配度>70%：复用或适配

Step 2: Patterns Guide

步骤2：模式指南

Location:

.claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md

If pattern exists: FOLLOW documented approach

位置：

.claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md

若存在对应模式：遵循文档中记录的实现方式

Step 3: Existing Projects

步骤3：现有项目

Location:
```
D:\Projects\*
```
If found: EXTRACT and adapt

位置：
```
D:\Projects\*
```
若找到同类实现：提取并适配

Decision Matrix

决策矩阵

Match	Action
Library >90%	REUSE directly
Library 70-90%	ADAPT minimally
Pattern exists	FOLLOW pattern
In project	EXTRACT
No match	BUILD (add to library after)

匹配度	操作
库匹配>90%	直接复用
库匹配70-90%	最小程度适配
存在对应模式	遵循模式
项目中已有	提取复用
无匹配项	构建（完成后添加到库中）

Purpose

用途

Create production-ready Claude Code hooks that integrate with our RBAC security system, follow official schemas, and meet performance requirements (<20ms for pre-hooks).

创建可用于生产环境的Claude Code钩子，这些钩子需集成我们的RBAC安全系统、遵循官方Schema并满足性能要求（前置钩子响应时间<20ms）。

When to Use This Skill

适用场景

Creating new automation hooks (pre/post operations)
Implementing security validation hooks
Building audit/logging hooks
Extending the RBAC permission system
Adding custom session management hooks

创建新的自动化钩子（前置/后置操作）
实现安全验证钩子
构建审计/日志钩子
扩展RBAC权限系统
添加自定义会话管理钩子

8-Stage Hook Creation Methodology

八阶段钩子创建方法论

Stage 1: Hook Type Selection

阶段1：钩子类型选择

Identify which of the 10 hook event types you need:

Category	Hook Type	Purpose
Blocking	UserPromptSubmit	Validate/modify user prompts
Blocking	SessionStart	Initialize session state
Blocking	PreToolUse	Validate tool operations
Blocking	PermissionRequest	Auto-approve/deny permissions
Observational	PostToolUse	Log tool results
Observational	Notification	Forward notifications
Observational	Stop	Cleanup on agent stop
Observational	SubagentStop	Track subagent completion
Observational	PreCompact	Preserve context during compaction
Observational	SessionEnd	Final session cleanup

确定你需要的10种钩子事件类型之一：

分类	钩子类型	用途
阻塞型	UserPromptSubmit	验证/修改用户提示
阻塞型	SessionStart	初始化会话状态
阻塞型	PreToolUse	验证工具操作
阻塞型	PermissionRequest	自动批准/拒绝权限请求
观测型	PostToolUse	记录工具执行结果
观测型	Notification	转发通知信息
观测型	Stop	代理停止时执行清理操作
观测型	SubagentStop	跟踪子代理完成状态
观测型	PreCompact	压缩过程中保留上下文
观测型	SessionEnd	会话结束时执行最终清理

Stage 2: Schema Definition

阶段2：Schema定义

Define input/output schemas based on hook type.

PreToolUse Input:

json

{
  "session_id": "string",
  "tool_name": "Bash|Read|Write|Edit|...",
  "tool_input": { "...tool-specific..." }
}

Blocking Output:

json

{
  "continue": true|false,
  "decision": "approve|block|modify",
  "reason": "string (if blocked)",
  "suppressOutput": false,
  "updatedInput": { "..." }
}

Non-Blocking Output:

json

{
  "suppressOutput": false
}

根据钩子类型定义输入/输出Schema。

PreToolUse输入:

json

{
  "session_id": "string",
  "tool_name": "Bash|Read|Write|Edit|...",
  "tool_input": { "...tool-specific..." }
}

阻塞型输出:

json

{
  "continue": true|false,
  "decision": "approve|block|modify",
  "reason": "string (if blocked)",
  "suppressOutput": false,
  "updatedInput": { "..." }
}

非阻塞型输出:

json

{
  "suppressOutput": false
}

Stage 3: Template Selection

阶段3：模板选择

Use our pre-built templates:

```
pre-hook-template.js
```
- For blocking hooks (PreToolUse, UserPromptSubmit)
```
post-hook-template.js
```
- For observational hooks (PostToolUse, SessionEnd)
```
session-hook-template.js
```
- For session lifecycle hooks

Generate from templates:

bash

node hook-template-generator.js --type pre --name my-validator --event PreToolUse

使用我们预构建的模板：

```
pre-hook-template.js
```
- 用于阻塞型钩子（PreToolUse、UserPromptSubmit）
```
post-hook-template.js
```
- 用于观测型钩子（PostToolUse、SessionEnd）
```
session-hook-template.js
```
- 用于会话生命周期钩子

通过模板生成钩子：

bash

node hook-template-generator.js --type pre --name my-validator --event PreToolUse

Stage 4: Core Logic Implementation

阶段4：核心逻辑实现

Implement the hook's core logic:

javascript

#!/usr/bin/env node
const fs = require('fs');

// Read input from stdin
const input = JSON.parse(fs.readFileSync(0, 'utf-8'));

// Your validation/processing logic
function processHook(input) {
  // Implement your logic here
  return { continue: true, decision: "approve" };
}

// Execute and output result
try {
  const result = processHook(input);
  console.log(JSON.stringify(result));
} catch (error) {
  console.error(`[HOOK ERROR] ${error.message}`);
  console.log(JSON.stringify({ continue: true }));  // Fail open
  process.exit(1);
}

实现钩子的核心逻辑：

javascript

#!/usr/bin/env node
const fs = require('fs');

// Read input from stdin
const input = JSON.parse(fs.readFileSync(0, 'utf-8'));

// Your validation/processing logic
function processHook(input) {
  // Implement your logic here
  return { continue: true, decision: "approve" };
}

// Execute and output result
try {
  const result = processHook(input);
  console.log(JSON.stringify(result));
} catch (error) {
  console.error(`[HOOK ERROR] ${error.message}`);
  console.log(JSON.stringify({ continue: true }));  // Fail open
  process.exit(1);
}

Stage 5: RBAC Integration

阶段5：RBAC集成

For security hooks, integrate with our identity system:

javascript

const { validateAgentIdentity, loadAgentIdentityByName } = require('../utils/identity');

// Verify agent identity
const identity = loadAgentIdentityByName(input.agent_name);
const validation = validateAgentIdentity(identity);

if (!validation.valid) {
  return {
    continue: false,
    decision: "block",
    reason: `Invalid agent identity: ${validation.errors.join(', ')}`
  };
}

对于安全类钩子，需与我们的身份系统集成：

javascript

const { validateAgentIdentity, loadAgentIdentityByName } = require('../utils/identity');

// Verify agent identity
const identity = loadAgentIdentityByName(input.agent_name);
const validation = validateAgentIdentity(identity);

if (!validation.valid) {
  return {
    continue: false,
    decision: "block",
    reason: `Invalid agent identity: ${validation.errors.join(', ')}`
  };
}

Stage 6: Performance Optimization

阶段6：性能优化

Meet performance targets:

Hook Type	Target	Max
Pre-hooks	<20ms	100ms
Post-hooks	<100ms	1000ms

Optimization Patterns:

Cache identity lookups
Avoid synchronous I/O in hot paths
Use matchers to filter events
Batch logging operations

满足性能目标：

钩子类型	目标值	最大值
前置钩子	<20ms	100ms
后置钩子	<100ms	1000ms

优化模式:

缓存身份查询结果
避免在热点路径中使用同步I/O
使用匹配器过滤事件
批量执行日志操作

Stage 7: Testing

阶段7：测试

Create test scenarios:

javascript

// test-my-hook.js
const testCases = [
  {
    name: "Should approve valid operation",
    input: { tool_name: "Read", tool_input: { file_path: "/src/app.js" } },
    expectedOutput: { continue: true, decision: "approve" }
  },
  {
    name: "Should block dangerous command",
    input: { tool_name: "Bash", tool_input: { command: "rm -rf /" } },
    expectedOutput: { continue: false, decision: "block" }
  }
];

创建测试场景：

javascript

// test-my-hook.js
const testCases = [
  {
    name: "Should approve valid operation",
    input: { tool_name: "Read", tool_input: { file_path: "/src/app.js" } },
    expectedOutput: { continue: true, decision: "approve" }
  },
  {
    name: "Should block dangerous command",
    input: { tool_name: "Bash", tool_input: { command: "rm -rf /" } },
    expectedOutput: { continue: false, decision: "block" }
  }
];

Stage 8: Registration

阶段8：注册

json

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "node /path/to/your/hook.js",
        "timeout": 5000,
        "matcher": { "tool_name_regex": "^(Bash|Write|Edit)$" }
      }
    ]
  }
}

在settings.json中注册钩子：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "node /path/to/your/hook.js",
        "timeout": 5000,
        "matcher": { "tool_name_regex": "^(Bash|Write|Edit)$" }
      }
    ]
  }
}

Hook Templates

钩子模板

Pre-Hook Template (Blocking)

前置钩子模板（阻塞型）

Location:

resources/templates/pre-hook-template.js

Features:

Input validation
Error handling with fail-open
Performance timing
RBAC integration point

位置：

resources/templates/pre-hook-template.js

特性：

输入验证
故障开放的错误处理
性能计时
RBAC集成点

Post-Hook Template (Observational)

后置钩子模板（观测型）

Location:

resources/templates/post-hook-template.js

Features:

Async-safe logging
Metric collection
Non-blocking execution
Error isolation

位置：

resources/templates/post-hook-template.js

特性：

异步安全日志
指标收集
非阻塞执行
错误隔离

Output Artifacts

输出产物

```
{hook-name}.js
```
- Main hook script
```
{hook-name}.test.js
```
- Test file
Settings entry for
```
.claude/settings.json
```

```
{hook-name}.js
```
- 主钩子脚本
```
{hook-name}.test.js
```
- 测试文件
在
```
.claude/settings.json
```
中的配置项

Integration Points

集成点

RBAC System:
```
hooks/12fa/utils/identity.js
```
Permission Checker:
```
hooks/12fa/permission-checker.js
```
Budget Tracker:
```
hooks/12fa/budget-tracker.js
```

Reference Docs:

hooks/12fa/docs/CLAUDE-CODE-HOOKS-REFERENCE.md

RBAC系统:
```
hooks/12fa/utils/identity.js
```
权限检查器:
```
hooks/12fa/permission-checker.js
```
预算跟踪器:
```
hooks/12fa/budget-tracker.js
```

参考文档:

hooks/12fa/docs/CLAUDE-CODE-HOOKS-REFERENCE.md

Agents Used

使用的代理

Agent	Role
hook-creator	Generate hook code from templates
coder	Implement custom logic
reviewer	Validate hook implementation
tester	Create and run test scenarios

代理	角色
hook-creator	从模板生成钩子代码
coder	实现自定义逻辑
reviewer	验证钩子实现
tester	创建并运行测试场景

Example Invocations

调用示例

Create a command validator hook:

User: "Create a hook that blocks any Bash command containing 'sudo'"

hook-creator:
  1. Hook Type: PreToolUse (blocking)
  2. Schema: PreToolUse input, blocking output
  3. Template: pre-hook-template.js
  4. Logic: Check tool_input.command for 'sudo'
  5. RBAC: Not required (simple validation)
  6. Performance: Target <10ms (regex only)
  7. Tests: Valid command, sudo command, edge cases
  8. Register in settings.json with Bash matcher

Create an audit logging hook:

User: "Create a hook that logs all file writes to an audit trail"

hook-creator:
  1. Hook Type: PostToolUse (observational)
  2. Schema: PostToolUse input, non-blocking output
  3. Template: post-hook-template.js
  4. Logic: Append to audit JSONL file
  5. RBAC: Load agent identity for WHO tag
  6. Performance: Target <50ms (file append)
  7. Tests: Successful write, failed write, large file
  8. Register with Write/Edit matcher

创建命令验证钩子:

用户: "创建一个阻止所有包含'sudo'的Bash命令的钩子"

hook-creator:
  1. 钩子类型: PreToolUse（阻塞型）
  2. Schema: PreToolUse输入，阻塞型输出
  3. 模板: pre-hook-template.js
  4. 逻辑: 检查tool_input.command中是否包含'sudo'
  5. RBAC: 不需要（简单验证）
  6. 性能: 目标<10ms（仅使用正则表达式）
  7. 测试: 合法命令、含sudo的命令、边缘情况
  8. 在settings.json中注册并配置Bash匹配器

创建审计日志钩子:

用户: "创建一个将所有文件写入操作记录到审计日志的钩子"

hook-creator:
  1. 钩子类型: PostToolUse（观测型）
  2. Schema: PostToolUse输入，非阻塞型输出
  3. 模板: post-hook-template.js
  4. 逻辑: 追加到审计JSONL文件
  5. RBAC: 加载代理身份以添加WHO标签
  6. 性能: 目标<50ms（文件追加操作）
  7. 测试: 成功写入、写入失败、大文件场景
  8. 注册并配置Write/Edit匹配器

Security Considerations

安全注意事项

Never log sensitive data - Filter passwords, API keys, tokens
Validate all input - Treat hook input as untrusted
Fail open for non-security hooks - Don't block on errors
Fail closed for security hooks - Block on validation errors
Use absolute paths - Avoid path traversal vulnerabilities

切勿记录敏感数据 - 过滤密码、API密钥、令牌等信息
验证所有输入 - 将钩子输入视为不可信内容
非安全钩子故障开放 - 不要因错误阻塞操作
安全钩子故障关闭 - 验证失败时阻塞操作
使用绝对路径 - 避免路径遍历漏洞

Shell Script Best Practices (Codex Recommendations)

Shell脚本最佳实践（Codex建议）

When creating bash/shell hooks, follow these best practices:

创建Bash/Shell钩子时，请遵循以下最佳实践：

1. Enable Strict Mode

1. 启用严格模式

Always start shell hooks with strict mode:

bash

#!/bin/bash
set -euo pipefail

Shell钩子始终以严格模式开头：

bash

#!/bin/bash
set -euo pipefail

-e: Exit on error

-e: 出错时退出

-u: Treat unset variables as errors

-u: 将未设置的变量视为错误

-o pipefail: Pipe fails if any command fails

-o pipefail: 管道中任一命令失败则整个管道失败

undefined

undefined

2. Proper Variable Quoting

2. 正确引用变量

Always quote variable expansions to prevent word splitting:

bash

undefined

始终引用变量扩展以防止单词拆分：

bash

undefined

GOOD

正确写法

FILE_PATH="${HOME}/.claude/state.json" if [[ -f "$FILE_PATH" ]]; then cat "$FILE_PATH" fi

BAD - unquoted variables can break with spaces

错误写法 - 未引用的变量在路径含空格时会失效

FILE_PATH=${HOME}/.claude/state.json if [ -f $FILE_PATH ]; then # Breaks if path has spaces cat $FILE_PATH fi

undefined

FILE_PATH=${HOME}/.claude/state.json if [ -f $FILE_PATH ]; then # 路径含空格时失效 cat $FILE_PATH fi

undefined

3. Defensive jq Usage

3. 防御性使用jq

Handle jq failures gracefully:

bash

undefined

优雅处理jq执行失败：

bash

undefined

GOOD - handle missing keys and errors

正确写法 - 处理缺失的键和错误

VALUE=$(echo "$JSON" | jq -r '.key // "default"' 2>/dev/null || echo "default")

BAD - crashes if key missing or json invalid

错误写法 - 键缺失或JSON无效时崩溃

VALUE=$(echo "$JSON" | jq -r '.key')

undefined

VALUE=$(echo "$JSON" | jq -r '.key')

undefined

4. Ensure Directories Exist

4. 确保目录存在

Create directories before writing:

bash

STATE_DIR="${HOME}/.claude/my-hook"
mkdir -p "$STATE_DIR" 2>/dev/null

写入前创建目录：

bash

STATE_DIR="${HOME}/.claude/my-hook"
mkdir -p "$STATE_DIR" 2>/dev/null

5. Use Environment Variables for Paths

5. 使用环境变量配置路径

Never hardcode project paths:

bash

undefined

切勿硬编码项目路径：

bash

undefined

GOOD - configurable via environment

正确写法 - 可通过环境变量配置

PROJECT_PATH="${MY_PROJECT_PATH:-/default/path}"

BAD - hardcoded, breaks on other systems

错误写法 - 硬编码路径在其他系统上会失效

PROJECT_PATH="/c/Users/john/projects/myapp"

undefined

PROJECT_PATH="/c/Users/john/projects/myapp"

undefined

ANTI-PATTERNS TO AVOID

需避免的反模式

These patterns caused real bugs in production hooks. NEVER use them:

这些模式曾导致生产环境钩子出现真实故障，切勿使用：

ANTI-PATTERN 1: Using grep -P (Perl Regex)

反模式1：使用grep -P（Perl正则）

Problem:

grep -P

requires Perl regex support, not available on all systems.

bash

undefined

问题:

grep -P

需要Perl正则支持，并非所有系统都具备。

bash

undefined

BAD - grep -P not portable

错误写法 - grep -P不具备可移植性

FOUND=$(echo "$TEXT" | grep -oP '(?<=<tag>).*?(?=</tag>)')

GOOD - use bash regex matching

正确写法 - 使用Bash正则匹配

if [[ "$TEXT" =~ <tag>([^<]+)</tag> ]]; then FOUND="${BASH_REMATCH[1]}" fi

undefined

if [[ "$TEXT" =~ <tag>([^<]+)</tag> ]]; then FOUND="${BASH_REMATCH[1]}" fi

undefined

ANTI-PATTERN 2: Using sed -i Directly

反模式2：直接使用sed -i

Problem:

sed -i

behaves differently on macOS (requires

''

), Linux, and Windows Git Bash.

bash

undefined

问题:

sed -i

在macOS（需要

''

）、Linux和Windows Git Bash上的行为不同。

bash

undefined

BAD - not portable

错误写法 - 不具备可移植性

sed -i 's/old/new/' "$FILE"

ALSO BAD - OS detection is fragile

同样错误 - 操作系统检测不可靠

if [[ "$(uname -s)" == "Darwin" ]]; then sed -i '' 's/old/new/' "$FILE" else sed -i 's/old/new/' "$FILE" fi

GOOD - portable temp file approach

正确写法 - 可移植的临时文件方案

sed_inplace() { local pattern="$1" local file="$2" local temp_file="${file}.tmp.$$" sed "$pattern" "$file" > "$temp_file" && mv "$temp_file" "$file" } sed_inplace 's/old/new/' "$FILE"

undefined

sed_inplace() { local pattern="$1" local file="$2" local temp_file="${file}.tmp.$$" sed "$pattern" "$file" > "$temp_file" && mv "$temp_file" "$file" } sed_inplace 's/old/new/' "$FILE"

undefined

ANTI-PATTERN 3: Hardcoded Paths

反模式3：硬编码路径

Problem: Hardcoded paths break on other systems or when projects move.

bash

undefined

问题: 硬编码路径在其他系统或项目迁移时会失效。

bash

undefined

BAD - hardcoded

错误写法 - 硬编码路径

cd D:/Projects/connascence python analyze.py

GOOD - environment variable with fallback

正确写法 - 带 fallback 的环境变量

CONNASCENCE_PATH="${CONNASCENCE_PROJECT_PATH:-D:/Projects/connascence}" if [[ -d "$CONNASCENCE_PATH" ]]; then cd "$CONNASCENCE_PATH" python analyze.py else echo "ERROR: Connascence project not found at $CONNASCENCE_PATH" >&2 exit 1 fi

undefined

undefined

ANTI-PATTERN 4: Missing Directory Creation

反模式4：未创建目录

Problem: Writing to directories that don't exist causes silent failures.

bash

undefined

问题: 写入不存在的目录会导致静默失败。

bash

undefined

BAD - assumes directory exists

错误写法 - 假设目录已存在

echo "$DATA" > ~/.claude/my-hook/state.json

GOOD - ensure directory exists first

正确写法 - 先确保目录存在

STATE_DIR="${HOME}/.claude/my-hook" mkdir -p "$STATE_DIR" 2>/dev/null echo "$DATA" > "$STATE_DIR/state.json"

undefined

STATE_DIR="${HOME}/.claude/my-hook" mkdir -p "$STATE_DIR" 2>/dev/null echo "$DATA" > "$STATE_DIR/state.json"

undefined

ANTI-PATTERN 5: Blocking cat Reads

反模式5：阻塞式cat读取

Problem: Using

cat

without timeout can block indefinitely if stdin never closes.

bash

undefined

问题: 无超时使用

cat

会在标准输入未关闭时无限阻塞。

bash

undefined

BAD - can block forever

错误写法 - 可能永久阻塞

INPUT=$(cat)

GOOD - use timeout or check for input

正确写法 - 使用超时或检查输入

INPUT=$(timeout 5 cat 2>/dev/null || echo "{}")

OR check if stdin has data

或者检查标准输入是否有数据

if [[ -t 0 ]]; then # No stdin data, use default INPUT="{}" else INPUT=$(cat) fi

undefined

if [[ -t 0 ]]; then # 无标准输入数据，使用默认值 INPUT="{}" else INPUT=$(cat) fi

undefined

ANTI-PATTERN 6: Silent Failures

反模式6：静默失败

Problem: Errors are silently swallowed, making debugging impossible.

bash

undefined

问题: 错误被静默吞噬，导致调试困难。

bash

undefined

BAD - silent failure

错误写法 - 静默失败

jq '.key' "$FILE" 2>/dev/null

GOOD - log errors to stderr, handle gracefully

正确写法 - 将错误记录到标准错误输出，优雅处理

if ! VALUE=$(jq -r '.key' "$FILE" 2>&1); then echo "[HOOK ERROR] Failed to parse $FILE: $VALUE" >&2 VALUE="default" fi

undefined

if ! VALUE=$(jq -r '.key' "$FILE" 2>&1); then echo "[HOOK ERROR] Failed to parse $FILE: $VALUE" >&2 VALUE="default" fi

undefined

Hook Validation Checklist

钩子验证清单

Before deploying a hook, verify:

Uses
```
set -euo pipefail
```
(or equivalent error handling)
All variables are properly quoted
No
```
grep -P
```
usage (use bash regex or grep -E)
No direct
```
sed -i
```
(use temp file approach)
No hardcoded paths (use environment variables)
Directories created before use
jq errors handled gracefully
Timeout on stdin reads if applicable
Errors logged to stderr
Tested on target platform (Windows Git Bash/macOS/Linux)

部署钩子前，请验证：

使用了
```
set -euo pipefail
```
（或等效的错误处理）
所有变量都正确引用
未使用
```
grep -P
```
（使用Bash正则或grep -E）
未直接使用
```
sed -i
```
（使用临时文件方案）
无硬编码路径（使用环境变量）
写入前创建了目录
优雅处理jq错误
必要时对标准输入读取设置超时
错误记录到标准错误输出
在目标平台（Windows Git Bash/macOS/Linux）上测试通过

Performance Monitoring

性能监控

Add performance logging to all hooks:

javascript

const start = process.hrtime.bigint();
// ... hook logic ...
const durationMs = Number(process.hrtime.bigint() - start) / 1_000_000;
console.error(`[PERF] ${hookName} completed in ${durationMs.toFixed(2)}ms`);

为所有钩子添加性能日志：

javascript

const start = process.hrtime.bigint();
// ... hook logic ...
const durationMs = Number(process.hrtime.bigint() - start) / 1_000_000;
console.error(`[PERF] ${hookName} completed in ${durationMs.toFixed(2)}ms`);