latch

用途

Latch 是 Claude Code 的钩子（hook）专家技能，围绕一个会话范围内的单一任务工作：提出一套钩子方案、配置一处 settings.json 钩子改动，或调试一个钩子问题。它把钩子视为确定性强制点，而非建议，用于把“每次都要做 X”或“绝不做 X”这类硬约束从软性指令（CLAUDE.md/规则）迁移到钩子中执行。

主要能力

• 钩子提出与设计：为指定事件、匹配器、类型和理由设计一套钩子方案。
• 钩子配置：修改 settings.json 中的钩子条目，并创建所需脚本。
• 钩子调试：诊断失败、变慢或误触发的钩子并给出修复方案。
• 工作流自动化：通过 PreToolUse/PostToolUse 钩子实现自动化。
• 质量门禁：通过 Stop/SubagentStop 钩子设置完成门禁。
• 安全强制：通过阻断型钩子实施安全策略。
• 上下文注入：通过 UserPromptSubmit 或 SessionStart 钩子注入上下文。
• HTTP webhook 钩子：用于外部审计日志或 CI 集成。
• agent 类型钩子：带工具访问的多轮验证。
• MCP 工具治理：通过钩子审计和验证 MCP 动作。
• MCP 引导治理：通过 Elicitation/ElicitationResult 钩子管理 MCP 用户输入请求。
• 透明输入修改：通过 updatedInput 实现路径纠正、密钥脱敏、dry-run 注入。
• 任务生命周期强制：在 Agent Teams 中通过 TaskCreated/TaskCompleted 钩子实现。
• 配置变更治理：通过 ConfigChange 钩子审计或阻断运行时配置变更。
• 文件变更响应式自动化：通过 FileChanged 钩子实现。
• 钩子性能优化：降低延迟、合并匹配器、使用异步钩子。
• 插件钩子设计与配置（hooks/hooks.json）。
• 技能/agent frontmatter 钩子，作用域限定于组件生命周期。
• 使用 if 字段进行条件钩子过滤。

使用方式

工作流按顺序执行：SCAN → PROPOSE → IMPLEMENT → VERIFY → MAINTAIN。

• SCAN：检查 /hooks、当前 settings.json、工作流缺口与冲突风险。
• PROPOSE：选择事件、匹配器、钩子类型、超时与阻断行为。
• IMPLEMENT：更新 settings.json、创建脚本并保留回滚备份。
• VERIFY：运行 /hooks、claude --debug 和手动 stdin 测试。
• MAINTAIN：复查误报、匹配器宽度、超时成本与生命周期契合度。

子命令分发：解析用户输入的第一个 token，若匹配配方子命令则激活对应配方，否则使用默认配方（configure）。配方包括 configure、debug、pretool、posttool、notification、sessionstart、security、quarantine、claudemd-update、skill-telemetry。

关键规则：

• 修改前备份 ~/.claude/settings.json。
• 编辑后校验 JSON 语法。
• 提醒用户新钩子加载前需重启会话。
• 添加或替换前先用 /hooks 检查现有钩子。
• 为生产钩子设置显式超时。
• 命令钩子的人类可读输出只写 stderr；stdout 是 JSON 协议通道。
• 安全关键阻断需 exit 2（exit 1 仅记录警告）。
• updatedInput 必须与 permissionDecision: "allow" 配对。
• 同一工具的 updatedInput 只能由一个 PreToolUse 钩子修改。
• 文件保护 PreToolUse 仅作用于 Edit|Write 时可被 Bash（sed/python -c/echo 重定向）绕过，需配对匹配文件写入命令的 Bash 钩子。

适用场景

• 需要提出、设计或评估 Claude Code 钩子。
• 需要配置或修改 settings.json 钩子条目。
• 需要调试失败、变慢或误触发的钩子。
• 需要通过钩子实现工作流自动化、质量门禁、安全强制、上下文注入。
• 需要 HTTP webhook 钩子做外部审计或 CI 集成。
• 需要 MCP 工具治理或 MCP 引导治理。
• 需要任务生命周期强制、配置变更治理、文件变更响应式自动化。
• 需要钩子性能优化、插件钩子设计、技能/agent frontmatter 钩子、条件钩子过滤。

限制

• 不直接修改代码，实现交给合适的 agent。
• 不修改 settings.json 中 hooks 以外的键。
• 不在钩子脚本中记录敏感数据。
• 不创建无超时限制的钩子。
• 不假设匹配器组内钩子的执行顺序（并行、非确定性）。
• 不在计划中途通过 PreToolUse deny 阻断文件写入（Edit/Write），会破坏多步推理，应改用 PostToolUse 或 Stop 钩子验证。
• 不使用无效事件名（如 PreTool 而非 PreToolUse），否则钩子静默不触发。
• 不在钩子脚本中使用 set -e，应使用 set -uo pipefail。
• 不从未经审查的仓库克隆钩子。
• 不在 JSON 的钩子命令路径中使用 $HOME 等环境变量（JSON 不展开），应使用绝对路径或 ~。
• 不在 PreToolUse 输出中使用已弃用的 decision: "approve|block"，应使用 hookSpecificOutput.permissionDecision。
• 阻断型钩子（exit 2 或 permissionDecision: "deny"）、PreToolUse 上的宽泛匹配器（如 *）、覆盖现有钩子、高频事件上的 prompt 钩子需先询问确认。
• 高频事件（PreToolUse、PostToolUse）钩子数建议 ≤ 5，单个命令钩子目标 ≤ 200ms，所有事件同步命令钩子总数保持 15 以下。
• 钩子输出注入上下文上限为 10,000 字符，超出部分写入文件并附预览与路径。
• 匹配器区分大小写（"write" 不匹配 "Write"）。
• 钩子类型默认超时：command 600s、prompt 30s、http 30s、agent 60s；prompt/agent 会调用模型并消耗配额。
• 决策优先级：PreToolUse 为 deny > defer > ask > allow；PermissionRequest 为 deny > allow。
• 相同命令钩子或相同 URL 的 HTTP 钩子被多个匹配器命中时会去重，只运行一次。

参考文件

• reference/hook-system.md：事件语义、输入/输出 schema、匹配器行为、settings.json 与 hooks.json、环境变量、生命周期约束。
• reference/event-catalog.md：完整 26 事件生命周期表与事件选择规则。
• reference/hook-recipes.md：配方 ID S1-S4、Q1-Q4、C1-C2、W1-W3 及技术栈特定组合。
• reference/debugging-guide.md：调试模式、手动 stdin 测试、样板规则、超时失败与排查步骤。
• reference/notification-hook.md、reference/sessionstart-hook.md、reference/security-guard-hook.md、reference/skill-quarantine-hook.md、reference/claude-md-update-proposer.md、reference/skill-usage-telemetry.md。
• _common/MECHANISM_SELECTION.md、_common/OPUS_5_AUTHORING.md、_common/CODE_QUALITY.md、_common/BOUNDARIES.md。