# Claude Code Hooks 使用：拦住密钥与锁文件误改，同时允许编辑配置示例

## 身份和范围

本站原创 fixture 与人工参考；实际运行：Hook 子进程五例退出码及源 SHA。目标代理模型、账号会话、付费 API、第三方 PR、推送和发布均未执行。公开包不含 .env；需要时仅在自己的临时练习目录从文本模板创建。

## 本地命令

```sh
python3 verify.py
```

## 七步原生操作

### 1. 先把保护对象限定为练习文件

解压后先读 fake-files.json：里面的 .env 和 .env.example 都是虚构种子，verify.py 只在临时目录创建它们。把 .claude/settings.json 和 protect.py 放进你自己的独立 Claude Code 练习项目，切勿拿真实密钥目录试错。

### 2. 配置 PreToolUse 的工具匹配

在项目 .claude/settings.json 的 hooks → PreToolUse 中设 matcher 为 Edit|Write，command 指向 python3 "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect.py。脚本从标准输入读取 tool_name 和 tool_input.file_path；相对路径必须先按项目目录归一化。

### 3. 用精确文件名保留配置示例例外

检查脚本：.env、package-lock.json 等精确文件名返回 exit 2，.env.example 不在名单中。不要用 startswith(".env") 把示例文件一起拦住；脚本还拒绝解析后逃出练习根目录的 Edit/Write 路径。

### 4. 让 Claude 分别提出四种编辑请求

进入项目启动 Claude Code，先要求 Edit 修改虚构 .env，再要求 Write 覆盖锁文件，然后修改 .env.example 与 app.txt。观察原生 Hook 阻断反馈和工具实际输入；不要为了通过测试授权其他工具绕过保护。

### 5. 先独立跑允许和拒绝正反例

在解压目录运行 python3 verify.py。它用真正子进程传入五份工具输入，验证退出码 2/2/0/0/0，并保存 result.json；第五项 Bash 返回 0 是刻意展示未覆盖的边界，不是保护成功。

### 6. 回读源文件与原生会话日志

核对 result.json 的 shaBefore/shaAfter 完全相同，因为独立检查器没有实际执行写文件。Claude 会话中另行确认被拒请求未改文件、放行请求确实改了练习文件；两种证据不要混为一次执行。

### 7. 记录覆盖范围后再迁移配置

整理匹配工具、精确文件名、项目根目录、阻断提示及绕过边界。此 Hook 只约束匹配的 Edit/Write；Bash、其他工具或操作系统写入仍需单独约束，不能把它描述成系统级文件权限。

## 验收产物

项目级 PreToolUse 配置与可执行拦截脚本；四种 Edit/Write 请求的允许或阻断日志、受保护文件前后 SHA 对照

## 门槛

- Claude Code 可用账号或 API 调用另计费；本研究不调用模型。
- 需本机 shell、可执行 Hook 脚本及 JSON 解析能力；按实际安装版验证配置。
- 只覆盖匹配的 Edit/Write，不覆盖 Bash 等其他写文件途径，不宣称系统级文件保护。

## 官方来源

- https://code.claude.com/docs/en/hooks-guide
- https://code.claude.com/docs/en/hooks

静态配图冻结于本次输入。修改输入需重新运行并自行重渲染；不把旧截图当新结果。