ECC Hooks 体系详解工具生命周期三大 Hook 类型、Auto-Accept 权限边界与 TodoWrite 最佳实践【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文以 common-hooks.md 规则文档为主线讲解 ECCThe agent harness performance optimization system中 Hooks 系统的三个核心知识点PreToolUse / PostToolUse / Stop 三类工具生命周期 Hook 的职责划分、Auto-Accept 权限的安全使用边界以及 TodoWrite 待办工具的最佳实践并结合仓库中的真实 Hook 配置hooks/hooks.json、.cursor/hooks.json与 Hook 事件 Schemaschemas/hooks.schema.json说明这些规则如何在 Claude Code、Codex、Cursor 等多 Harness 环境中落地执行。一、规则文件定位一份跨 Harness 的公共约定common-hooks.md 位于.cursor/rules/目录是随仓库分发给 Cursor 使用的规则文件其 Frontmatter 声明如下--- description: Hooks system: types, auto-accept permissions, TodoWrite best practices alwaysApply: true ---其中alwaysApply: true表示该规则在当前工作区的每次会话中始终生效而不是按文件类型或场景条件触发。文档本身非常精炼聚焦三件事Hook TypesHook 的三种类型及其触发时机Auto-Accept Permissions自动接受工具调用的权限边界TodoWrite Best Practices待办工具的使用规范。值得注意的是仓库根目录下存在一份内容完全一致的同名规则 rules/common/hooks.md面向的是 Claude Code 侧的通用规则集rules/common/目录。也就是说ECC 将同一套 Hooks 约定同时下发给不同 Agent Harness 的规则目录保证「跨 Harness 行为一致」——这与仓库 README 中强调的「for Claude Code, Codex, Opencode, Cursor and beyond」定位相符。而规则文档描述的是「约定」真正被 Harness 加载执行的「Hook 图」则存放在两处配置文件配置文件服务对象说明hooks/hooks.jsonClaude Code完整的 Hook 事件图含 PreToolUse / PostToolUse / Stop 等 7 类事件hooks/codex-hooks.jsonCodex精简的原生 Hook仅保留 SessionStart 引导文件头注明「Claude hook profiles remain separate」.cursor/hooks.jsonCursorCursor 事件体系下的对应 Hook 图事件名为sessionStart、beforeShellExecution等二、三大 Hook 类型职责划分与触发时机规则文档将 Hook 类型归纳为三类。下面逐类说明其语义并对照仓库实际配置展开。2.1 PreToolUse工具执行前的拦截点文档定义PreToolUse在工具执行前触发用途是「validation, parameter modification」校验与参数修改。它是唯一能够阻止工具调用的时机。在 ECC 的 hooks/hooks.json 中PreToolUse 段hooks/hooks.json#L4-L98注册了 8 个匹配器条目覆盖了 Bash、Write、Edit、MCP 等关键工具Hook IDMatcher行为备注pre:bash:dispatcherBash统一的 Bash 预检分发器聚合质量检查、tmux 提醒、git push 审查与 GateGuard 检查见 hooks/hooks.json#L6-L14pre:write:doc-file-warningWrite对非标准命名文档文件发出警告仅警告exit 0hooks/hooks.json#L17-L26pre:edit-write:suggest-compactEdit\|Write在逻辑间隔处建议手动/compact压缩上下文hooks/hooks.json#L28-L37pre:observe:continuous-learning.*捕获工具使用观察数据供持续学习使用异步执行timeout 10spre:governance-captureBash\|Write\|Edit\|MultiEdit捕获治理事件密钥、策略违规、审批请求需ECC_GOVERNANCE_CAPTURE1启用timeout 10spre:config-protectionWrite\|Edit\|MultiEdit阻止修改 linter/formatter 配置文件引导 Agent 修复代码而非放宽配置timeout 5spre:mcp-health-check.*在执行 MCP 工具前检查 MCP 服务器健康状态阻止对不健康服务器的调用hooks/hooks.json#L76-L85pre:edit-write:gateguard-fact-forceEdit\|Write\|MultiEdit「事实强制」门禁对每个文件的首次编辑进行拦截要求先调查importers、数据结构、用户指令后才放行timeout 5s从源码结构看这些条目中的command字段都采用同一种「引导 分发」模式先内联一段 Node.js 解析逻辑优先读取CLAUDE_PLUGIN_ROOT环境变量否则在~/.claude下依次探测ecc、marketplaces/ecc、plugins/cache等安装位置定位到插件根目录后加载scripts/hooks/plugin-hook-bootstrap.js再执行真正的 Hook 脚本。这意味着同一个仓库内的hooks.json是「面向插件/仓库」的中枢定义安装时会被解析改写为指向实际安装路径的命令——hooks/README.md 也明确提醒不要把仓库中的原始hooks.json直接粘贴进~/.claude/settings.json应使用安装器bash ./install.sh --target claude --modules hooks-runtime --enable-hooks2.2 PostToolUse工具执行后的分析点文档定义PostToolUse在工具执行后触发用途是「auto-format, checks」自动格式化与检查。它发生在工具成功完成之后因此可以拿到工具输出但不能阻止本次调用。.cursor/hooks.json 的afterFileEdit事件.cursor/hooks.json#L37-L43就是这一类型在 Cursor 侧的直接体现其挂载的脚本职责为「Auto-format, TypeScript check, console.log warning, and frontend design-quality reminder」——与文档中「auto-format, checks」的描述一一对应。在 Claude 侧hooks/hooks.json#L136-L162 将 PostToolUse 拆成了两个分发器post:dispatcher:sync单进程内同步执行一批 PostToolUse Hooktimeout 30spost:dispatcher:async以async: true在后台执行timeout 45s不阻塞主流程。这种「同步/异步双通道」设计保证了轻量检查如格式化即时生效而重型分析如构建日志分析不拖慢交互。此外还有PostToolUseFailure事件hooks/hooks.json#L163-L186用于在工具调用失败时记录 MCP 调用失败、标记不健康服务器并尝试重连以及通过post:skill:track记录 Skill 工具的硬失败供 skill-health 遥测使用。2.3 Stop响应结束时的最终校验点文档定义Stop在会话响应结束时触发用途是「final verification」最终校验。ECC 在 Stop 事件下挂载了 7 个 Hookhooks/hooks.json#L187-L274构成每次响应结束时的「收尾流水线」Hook ID行为特性stop:plan-canvas-pending在 Agent 停止前投递未送达的 Plan Canvas 浏览器反馈同步timeout 30sstop:format-typecheck对本轮响应中编辑过的所有 JS/TS 文件批量执行格式化Biome/Prettier与tsc类型检查——刻意在 Stop 时一次性运行而不是每次 Edit 后都跑同步timeout 300sstop:check-console-log检查所有被修改文件中残留的console.log同步stop:session-end持久化会话状态Stop 事件携带transcript_path异步stop:evaluate-session评估本次会话可提取的模式持续学习异步stop:cost-tracker跟踪每次会话的 token 与成本指标异步stop:desktop-notify响应结束时发送桌面通知macOS/WSL异步stop:format-typecheck的设计值得单独说明其描述明确写着「runs once at Stop instead of after every Edit」。将格式化/类型检查从 PostToolUse每次编辑后移到 Stop每轮响应是典型的「批处理摊薄开销」策略——编辑过程中频繁触发tsc --noEmit会显著拖慢循环而用户可感知的节奏是以「一次响应」为单位的。2.4 超出三类的完整事件面规则文档归纳的三类是最核心的工具生命周期事件。从 schemas/hooks.schema.json 的propertyNames枚举schemas/hooks.schema.json#L155-L177可以看到当前 Claude Code 配置面实际支持17 种Hook 事件SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, Stop, SubagentStop, PreCompact, InstructionsLoaded, TeammateIdle, TaskCompleted, ConfigChange, WorktreeCreate, WorktreeRemove, SessionEndECC 在此面上实际使用了其中 7 类PreToolUse、PostToolUse、PostToolUseFailure、Stop、SessionStart、PreCompact、SessionEnd。Schema 同时约束了三种 Hook 动作类型command本地命令支持async与timeout字段、http远端 URL 调用支持headers/allowedEnvVars、prompt/agentLLM 提示词类 Hook支持指定model——这为读者理解「Hook 不止能跑脚本」提供了完整的能力边界。Hook 命令本身的 I/O 契约在 hooks/README.md 中有明确定义Hook 是从 stdin 接收 JSON工具输入、向 stdout 输出 JSON 的 shell 命令退出码0表示放行退出码2表示阻止仅 PreToolUse 有效其他非零值记为错误但不阻断写 stderr 的文本会作为警告展示给 Agent。这与规则文档中「PreToolUse 可以 validation/修改参数、PostToolUse 只做 checks」的类型划分在机制层面完全吻合。三、Cursor 侧的 Hook 映射同一套约定的另一种事件命名.cursor/hooks.json 展示了规则文档中三大类型在 Cursor 事件体系下的具体落点。由于 Cursor 的 Hook 事件命名更贴近「动作」而非「工具生命周期阶段」对应关系如下规则文档中的类型Cursor 事件挂载脚本与职责PreToolUsebeforeShellExecutionbefore-shell-execution.jstmux 开发服务器拦截、tmux 提醒、git push 审查另有一条专门的 before-shell-execution-block-no-verify.js 用于阻止绕过 git hook 的 flag保护 pre-commit/commit-msg/pre-push 不被跳过PreToolUsebeforeMCPExecutionMCP 审计日志与不受信任服务器警告.cursor/hooks.json#L44-L50PreToolUsebeforeReadFile/beforeTabFileRead读取敏感文件.env、.key、.pem时警告或拦截PreToolUsebeforeSubmitPrompt在提示词中检测密钥模式sk-、ghp_、AKIAPostToolUseafterShellExecutionPR URL 记录、构建分析.cursor/hooks.json#L30-L36PostToolUseafterFileEdit自动格式化、TS 检查、console.log 警告、前端设计质量提醒PostToolUseafterMCPExecutionMCP 结果日志Stopstop对所有修改文件做 console.log 审计.cursor/hooks.json#L107-L113会话生命周期sessionStart/sessionEnd/preCompact加载上一上下文与检测环境、持久化会话状态并评估模式、压缩前保存状态此外还有subagentStart/subagentStop两个事件用于记录子 Agent 的生成与完成提供可观测性。从源码结构看.cursor/hooks/下的每个脚本如 session-start.js、stop.js与 Claude 侧scripts/hooks/下的同名逻辑在职责上一一对应ECC 通过 scaffolds/cursor/ 与规则目录实现「一套约定、多套适配」。四、Auto-Accept 权限规则文档给出的四条安全边界规则文档「Auto-Accept Permissions」一节给出了四条明确的行为准则原文继承如下并逐条展开Enable for trusted, well-defined plans为可信的、边界清晰的计划开启自动接受 当任务目标明确、步骤已经过规划确认例如已经过 plan 流程产出的实现清单时开启自动接受可以减少确认摩擦、提高吞吐。ECC 的 Stop 批处理设计见 2.3 节正是建立在「流程可信、批量执行」这一前提上的。Disable for exploratory work探索性工作应关闭自动接受 在代码结构未知、改动方向未定的探索阶段每次工具调用都应保留人工确认点。这与仓库中pre:edit-write:gateguard-fact-force门禁的设计意图一致对首次编辑强制「先调查、再动手」本质上就是用 Hook 弥补自动放行带来的失控风险。Never use dangerously-skip-permissions flag永远不要使用dangerously-skip-permissions标志 这是四条中最强的一条属于绝对禁令。全量跳过权限检查会使 Agent 拥有无任何拦截的 shell 与文件写入能力ECC 将其列为明确反模式。值得注意的是仓库的 Hook 体系中存在大量「精确拦截」类 Hook如pre:config-protection阻止篡改 lint 配置、before-shell-execution-block-no-verify.js阻止跳过 git hooks——它们与「全量放行」是两种截然相反的安全哲学ECC 选择细粒度授权 关键路径强校验。ConfigureallowedToolsin~/.claude.jsoninstead改为在~/.claude.json中配置allowedTools 安全的替代方案是按工具白名单授权只将明确可信的具体工具或工具参数模式加入允许列表而不是整体开关。仓库中同样涉及权限面的是 Schema 里的PermissionRequest事件——它允许在权限请求发生时挂载 Hook为「审批前策略」提供了扩展点。这四条准则合起来构成一条决策链先判断计划可信度 → 决定开关 → 用白名单替代跳过 → 由 Hook 在关键路径兜底。五、TodoWrite 最佳实践用待办清单暴露理解偏差规则文档的第三节「TodoWrite Best Practices」给出了 TodoWrite 工具的两层规范。5.1 四个使用目的文档要求使用 TodoWrite 工具做到Track progress on multi-step tasks跟踪多步骤任务的进度Verify understanding of instructions验证对指令的理解Enable real-time steering支持实时纠偏Show granular implementation steps展示细粒度的实现步骤。其中「Verify understanding」是最容易被忽视的一条。它意味着在动手实现之前Agent 应先把任务拆成待办清单呈现出来——这份清单本身就是一次「理解检查」。人只需审阅清单即可发现偏差成本远低于审阅错误代码后的返工。5.2 待办清单能暴露的五类问题文档明确列出了审阅 Todo 清单时可识别的五种信号信号含义Out of order steps步骤顺序错误依赖关系被颠倒例如先写调用方后写被调用方Missing items遗漏项任务分解不完整遗漏了测试、文档、配置等必要环节Extra unnecessary items多余项Agent 理解了超出需求范围的东西产生镀金Wrong granularity粒度不当过粗无法跟踪过细增加维护成本粒度本身反映任务切分质量Misinterpreted requirements需求误解清单条目与原始指令不一致直接暴露语义偏差5.3 与 Hook 体系的配合长任务的连续性TodoWrite 的价值在多步骤任务中才充分体现而多步骤任务的真正风险是上下文压缩导致的进度丢失。ECC 在这条链路上有配套机制PreCompact事件挂载的pre:compactHookhooks/hooks.json#L99-L111在上下文压缩前保存状态stop:session-end在每轮响应结束时持久化会话状态session:start在新会话启动时加载上一上下文。从源码结构看这套「Todo 表达计划 → Stop 持久化 → PreCompact 保状态 → SessionStart 恢复」的闭环使 TodoWrite 清单不只是一次会话内的沟通工具而是跨会话连续性的锚点。六、运行时控制不改 hooks.json 的开关对于实际部署hooks/README.md 提供了通过环境变量控制 Hook 行为的完整手段比编辑hooks.json推荐得多# 总开关。显式的环境变量值会覆盖插件偏好 export ECC_HOOKS_ENABLEDtrue # minimal | standard | strict默认 standard export ECC_HOOK_PROFILEstandard # 按 ID 禁用特定 Hook逗号分隔 export ECC_DISABLED_HOOKSpre:bash:tmux-reminder,post:edit:typecheck # 在 setup 或恢复期间仅关闭 GateGuard export ECC_GATEGUARDoff # 限制 SessionStart 附加上下文长度默认 8000 字符 export ECC_SESSION_START_MAX_CHARS4000 # 完全关闭 SessionStart 附加上下文 export ECC_SESSION_START_CONTEXToff # 保留上下文/作用域/循环警告但抑制 API 费率成本估算 export ECC_CONTEXT_MONITOR_COST_WARNINGSoff三个档位profile的语义为minimal仅保留必要生命周期与安全 Hookstandard为默认的均衡档质量安全检查strict启用额外提醒与更严的护栏。这与规则文档「对可信计划放宽、对探索收紧」的原则在操作层面对应起来探索阶段可切minimal交付前可切strict并配合ECC_GATEGUARD保持门禁开启。七、小结.cursor/rules/common-hooks.md 虽然只有 30 行但它把 ECC Hooks 体系压缩成了三条可执行的工程约定按生命周期分工PreToolUse 管「执行前拦截」唯一可 exit 2 阻止的时机PostToolUse 管「执行后分析」不可阻止Stop 管「响应级最终校验」——仓库的 hooks/hooks.json 与 .cursor/hooks.json 给出了两套 Harness 下的完整落地样例权限收窄而非跳过按计划可信度决定 auto-accept 开关用~/.claude.json的allowedTools白名单替代dangerously-skip-permissions并依靠配置保护类 Hook 兜底用 TodoWrite 前置理解验证在实现前以细粒度清单呈现任务分解借助「顺序、遗漏、多余、粒度、误解」五个信号在编码前拦截偏差。读者可以进一步深入的文件Hook 图定义 hooks/hooks.json 与 hooks/codex-hooks.json、事件与动作类型约束 schemas/hooks.schema.json、Hook 编写契约与全部内置 Hook 说明 hooks/README.md以及 Claude 侧同名规则 rules/common/hooks.md。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ECC Hooks 体系详解：工具生命周期三大 Hook 类型、Auto-Accept 权限边界与 TodoWrite 最佳实践
ECC Hooks 体系详解工具生命周期三大 Hook 类型、Auto-Accept 权限边界与 TodoWrite 最佳实践【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文以 common-hooks.md 规则文档为主线讲解 ECCThe agent harness performance optimization system中 Hooks 系统的三个核心知识点PreToolUse / PostToolUse / Stop 三类工具生命周期 Hook 的职责划分、Auto-Accept 权限的安全使用边界以及 TodoWrite 待办工具的最佳实践并结合仓库中的真实 Hook 配置hooks/hooks.json、.cursor/hooks.json与 Hook 事件 Schemaschemas/hooks.schema.json说明这些规则如何在 Claude Code、Codex、Cursor 等多 Harness 环境中落地执行。一、规则文件定位一份跨 Harness 的公共约定common-hooks.md 位于.cursor/rules/目录是随仓库分发给 Cursor 使用的规则文件其 Frontmatter 声明如下--- description: Hooks system: types, auto-accept permissions, TodoWrite best practices alwaysApply: true ---其中alwaysApply: true表示该规则在当前工作区的每次会话中始终生效而不是按文件类型或场景条件触发。文档本身非常精炼聚焦三件事Hook TypesHook 的三种类型及其触发时机Auto-Accept Permissions自动接受工具调用的权限边界TodoWrite Best Practices待办工具的使用规范。值得注意的是仓库根目录下存在一份内容完全一致的同名规则 rules/common/hooks.md面向的是 Claude Code 侧的通用规则集rules/common/目录。也就是说ECC 将同一套 Hooks 约定同时下发给不同 Agent Harness 的规则目录保证「跨 Harness 行为一致」——这与仓库 README 中强调的「for Claude Code, Codex, Opencode, Cursor and beyond」定位相符。而规则文档描述的是「约定」真正被 Harness 加载执行的「Hook 图」则存放在两处配置文件配置文件服务对象说明hooks/hooks.jsonClaude Code完整的 Hook 事件图含 PreToolUse / PostToolUse / Stop 等 7 类事件hooks/codex-hooks.jsonCodex精简的原生 Hook仅保留 SessionStart 引导文件头注明「Claude hook profiles remain separate」.cursor/hooks.jsonCursorCursor 事件体系下的对应 Hook 图事件名为sessionStart、beforeShellExecution等二、三大 Hook 类型职责划分与触发时机规则文档将 Hook 类型归纳为三类。下面逐类说明其语义并对照仓库实际配置展开。2.1 PreToolUse工具执行前的拦截点文档定义PreToolUse在工具执行前触发用途是「validation, parameter modification」校验与参数修改。它是唯一能够阻止工具调用的时机。在 ECC 的 hooks/hooks.json 中PreToolUse 段hooks/hooks.json#L4-L98注册了 8 个匹配器条目覆盖了 Bash、Write、Edit、MCP 等关键工具Hook IDMatcher行为备注pre:bash:dispatcherBash统一的 Bash 预检分发器聚合质量检查、tmux 提醒、git push 审查与 GateGuard 检查见 hooks/hooks.json#L6-L14pre:write:doc-file-warningWrite对非标准命名文档文件发出警告仅警告exit 0hooks/hooks.json#L17-L26pre:edit-write:suggest-compactEdit\|Write在逻辑间隔处建议手动/compact压缩上下文hooks/hooks.json#L28-L37pre:observe:continuous-learning.*捕获工具使用观察数据供持续学习使用异步执行timeout 10spre:governance-captureBash\|Write\|Edit\|MultiEdit捕获治理事件密钥、策略违规、审批请求需ECC_GOVERNANCE_CAPTURE1启用timeout 10spre:config-protectionWrite\|Edit\|MultiEdit阻止修改 linter/formatter 配置文件引导 Agent 修复代码而非放宽配置timeout 5spre:mcp-health-check.*在执行 MCP 工具前检查 MCP 服务器健康状态阻止对不健康服务器的调用hooks/hooks.json#L76-L85pre:edit-write:gateguard-fact-forceEdit\|Write\|MultiEdit「事实强制」门禁对每个文件的首次编辑进行拦截要求先调查importers、数据结构、用户指令后才放行timeout 5s从源码结构看这些条目中的command字段都采用同一种「引导 分发」模式先内联一段 Node.js 解析逻辑优先读取CLAUDE_PLUGIN_ROOT环境变量否则在~/.claude下依次探测ecc、marketplaces/ecc、plugins/cache等安装位置定位到插件根目录后加载scripts/hooks/plugin-hook-bootstrap.js再执行真正的 Hook 脚本。这意味着同一个仓库内的hooks.json是「面向插件/仓库」的中枢定义安装时会被解析改写为指向实际安装路径的命令——hooks/README.md 也明确提醒不要把仓库中的原始hooks.json直接粘贴进~/.claude/settings.json应使用安装器bash ./install.sh --target claude --modules hooks-runtime --enable-hooks2.2 PostToolUse工具执行后的分析点文档定义PostToolUse在工具执行后触发用途是「auto-format, checks」自动格式化与检查。它发生在工具成功完成之后因此可以拿到工具输出但不能阻止本次调用。.cursor/hooks.json 的afterFileEdit事件.cursor/hooks.json#L37-L43就是这一类型在 Cursor 侧的直接体现其挂载的脚本职责为「Auto-format, TypeScript check, console.log warning, and frontend design-quality reminder」——与文档中「auto-format, checks」的描述一一对应。在 Claude 侧hooks/hooks.json#L136-L162 将 PostToolUse 拆成了两个分发器post:dispatcher:sync单进程内同步执行一批 PostToolUse Hooktimeout 30spost:dispatcher:async以async: true在后台执行timeout 45s不阻塞主流程。这种「同步/异步双通道」设计保证了轻量检查如格式化即时生效而重型分析如构建日志分析不拖慢交互。此外还有PostToolUseFailure事件hooks/hooks.json#L163-L186用于在工具调用失败时记录 MCP 调用失败、标记不健康服务器并尝试重连以及通过post:skill:track记录 Skill 工具的硬失败供 skill-health 遥测使用。2.3 Stop响应结束时的最终校验点文档定义Stop在会话响应结束时触发用途是「final verification」最终校验。ECC 在 Stop 事件下挂载了 7 个 Hookhooks/hooks.json#L187-L274构成每次响应结束时的「收尾流水线」Hook ID行为特性stop:plan-canvas-pending在 Agent 停止前投递未送达的 Plan Canvas 浏览器反馈同步timeout 30sstop:format-typecheck对本轮响应中编辑过的所有 JS/TS 文件批量执行格式化Biome/Prettier与tsc类型检查——刻意在 Stop 时一次性运行而不是每次 Edit 后都跑同步timeout 300sstop:check-console-log检查所有被修改文件中残留的console.log同步stop:session-end持久化会话状态Stop 事件携带transcript_path异步stop:evaluate-session评估本次会话可提取的模式持续学习异步stop:cost-tracker跟踪每次会话的 token 与成本指标异步stop:desktop-notify响应结束时发送桌面通知macOS/WSL异步stop:format-typecheck的设计值得单独说明其描述明确写着「runs once at Stop instead of after every Edit」。将格式化/类型检查从 PostToolUse每次编辑后移到 Stop每轮响应是典型的「批处理摊薄开销」策略——编辑过程中频繁触发tsc --noEmit会显著拖慢循环而用户可感知的节奏是以「一次响应」为单位的。2.4 超出三类的完整事件面规则文档归纳的三类是最核心的工具生命周期事件。从 schemas/hooks.schema.json 的propertyNames枚举schemas/hooks.schema.json#L155-L177可以看到当前 Claude Code 配置面实际支持17 种Hook 事件SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, Stop, SubagentStop, PreCompact, InstructionsLoaded, TeammateIdle, TaskCompleted, ConfigChange, WorktreeCreate, WorktreeRemove, SessionEndECC 在此面上实际使用了其中 7 类PreToolUse、PostToolUse、PostToolUseFailure、Stop、SessionStart、PreCompact、SessionEnd。Schema 同时约束了三种 Hook 动作类型command本地命令支持async与timeout字段、http远端 URL 调用支持headers/allowedEnvVars、prompt/agentLLM 提示词类 Hook支持指定model——这为读者理解「Hook 不止能跑脚本」提供了完整的能力边界。Hook 命令本身的 I/O 契约在 hooks/README.md 中有明确定义Hook 是从 stdin 接收 JSON工具输入、向 stdout 输出 JSON 的 shell 命令退出码0表示放行退出码2表示阻止仅 PreToolUse 有效其他非零值记为错误但不阻断写 stderr 的文本会作为警告展示给 Agent。这与规则文档中「PreToolUse 可以 validation/修改参数、PostToolUse 只做 checks」的类型划分在机制层面完全吻合。三、Cursor 侧的 Hook 映射同一套约定的另一种事件命名.cursor/hooks.json 展示了规则文档中三大类型在 Cursor 事件体系下的具体落点。由于 Cursor 的 Hook 事件命名更贴近「动作」而非「工具生命周期阶段」对应关系如下规则文档中的类型Cursor 事件挂载脚本与职责PreToolUsebeforeShellExecutionbefore-shell-execution.jstmux 开发服务器拦截、tmux 提醒、git push 审查另有一条专门的 before-shell-execution-block-no-verify.js 用于阻止绕过 git hook 的 flag保护 pre-commit/commit-msg/pre-push 不被跳过PreToolUsebeforeMCPExecutionMCP 审计日志与不受信任服务器警告.cursor/hooks.json#L44-L50PreToolUsebeforeReadFile/beforeTabFileRead读取敏感文件.env、.key、.pem时警告或拦截PreToolUsebeforeSubmitPrompt在提示词中检测密钥模式sk-、ghp_、AKIAPostToolUseafterShellExecutionPR URL 记录、构建分析.cursor/hooks.json#L30-L36PostToolUseafterFileEdit自动格式化、TS 检查、console.log 警告、前端设计质量提醒PostToolUseafterMCPExecutionMCP 结果日志Stopstop对所有修改文件做 console.log 审计.cursor/hooks.json#L107-L113会话生命周期sessionStart/sessionEnd/preCompact加载上一上下文与检测环境、持久化会话状态并评估模式、压缩前保存状态此外还有subagentStart/subagentStop两个事件用于记录子 Agent 的生成与完成提供可观测性。从源码结构看.cursor/hooks/下的每个脚本如 session-start.js、stop.js与 Claude 侧scripts/hooks/下的同名逻辑在职责上一一对应ECC 通过 scaffolds/cursor/ 与规则目录实现「一套约定、多套适配」。四、Auto-Accept 权限规则文档给出的四条安全边界规则文档「Auto-Accept Permissions」一节给出了四条明确的行为准则原文继承如下并逐条展开Enable for trusted, well-defined plans为可信的、边界清晰的计划开启自动接受 当任务目标明确、步骤已经过规划确认例如已经过 plan 流程产出的实现清单时开启自动接受可以减少确认摩擦、提高吞吐。ECC 的 Stop 批处理设计见 2.3 节正是建立在「流程可信、批量执行」这一前提上的。Disable for exploratory work探索性工作应关闭自动接受 在代码结构未知、改动方向未定的探索阶段每次工具调用都应保留人工确认点。这与仓库中pre:edit-write:gateguard-fact-force门禁的设计意图一致对首次编辑强制「先调查、再动手」本质上就是用 Hook 弥补自动放行带来的失控风险。Never use dangerously-skip-permissions flag永远不要使用dangerously-skip-permissions标志 这是四条中最强的一条属于绝对禁令。全量跳过权限检查会使 Agent 拥有无任何拦截的 shell 与文件写入能力ECC 将其列为明确反模式。值得注意的是仓库的 Hook 体系中存在大量「精确拦截」类 Hook如pre:config-protection阻止篡改 lint 配置、before-shell-execution-block-no-verify.js阻止跳过 git hooks——它们与「全量放行」是两种截然相反的安全哲学ECC 选择细粒度授权 关键路径强校验。ConfigureallowedToolsin~/.claude.jsoninstead改为在~/.claude.json中配置allowedTools 安全的替代方案是按工具白名单授权只将明确可信的具体工具或工具参数模式加入允许列表而不是整体开关。仓库中同样涉及权限面的是 Schema 里的PermissionRequest事件——它允许在权限请求发生时挂载 Hook为「审批前策略」提供了扩展点。这四条准则合起来构成一条决策链先判断计划可信度 → 决定开关 → 用白名单替代跳过 → 由 Hook 在关键路径兜底。五、TodoWrite 最佳实践用待办清单暴露理解偏差规则文档的第三节「TodoWrite Best Practices」给出了 TodoWrite 工具的两层规范。5.1 四个使用目的文档要求使用 TodoWrite 工具做到Track progress on multi-step tasks跟踪多步骤任务的进度Verify understanding of instructions验证对指令的理解Enable real-time steering支持实时纠偏Show granular implementation steps展示细粒度的实现步骤。其中「Verify understanding」是最容易被忽视的一条。它意味着在动手实现之前Agent 应先把任务拆成待办清单呈现出来——这份清单本身就是一次「理解检查」。人只需审阅清单即可发现偏差成本远低于审阅错误代码后的返工。5.2 待办清单能暴露的五类问题文档明确列出了审阅 Todo 清单时可识别的五种信号信号含义Out of order steps步骤顺序错误依赖关系被颠倒例如先写调用方后写被调用方Missing items遗漏项任务分解不完整遗漏了测试、文档、配置等必要环节Extra unnecessary items多余项Agent 理解了超出需求范围的东西产生镀金Wrong granularity粒度不当过粗无法跟踪过细增加维护成本粒度本身反映任务切分质量Misinterpreted requirements需求误解清单条目与原始指令不一致直接暴露语义偏差5.3 与 Hook 体系的配合长任务的连续性TodoWrite 的价值在多步骤任务中才充分体现而多步骤任务的真正风险是上下文压缩导致的进度丢失。ECC 在这条链路上有配套机制PreCompact事件挂载的pre:compactHookhooks/hooks.json#L99-L111在上下文压缩前保存状态stop:session-end在每轮响应结束时持久化会话状态session:start在新会话启动时加载上一上下文。从源码结构看这套「Todo 表达计划 → Stop 持久化 → PreCompact 保状态 → SessionStart 恢复」的闭环使 TodoWrite 清单不只是一次会话内的沟通工具而是跨会话连续性的锚点。六、运行时控制不改 hooks.json 的开关对于实际部署hooks/README.md 提供了通过环境变量控制 Hook 行为的完整手段比编辑hooks.json推荐得多# 总开关。显式的环境变量值会覆盖插件偏好 export ECC_HOOKS_ENABLEDtrue # minimal | standard | strict默认 standard export ECC_HOOK_PROFILEstandard # 按 ID 禁用特定 Hook逗号分隔 export ECC_DISABLED_HOOKSpre:bash:tmux-reminder,post:edit:typecheck # 在 setup 或恢复期间仅关闭 GateGuard export ECC_GATEGUARDoff # 限制 SessionStart 附加上下文长度默认 8000 字符 export ECC_SESSION_START_MAX_CHARS4000 # 完全关闭 SessionStart 附加上下文 export ECC_SESSION_START_CONTEXToff # 保留上下文/作用域/循环警告但抑制 API 费率成本估算 export ECC_CONTEXT_MONITOR_COST_WARNINGSoff三个档位profile的语义为minimal仅保留必要生命周期与安全 Hookstandard为默认的均衡档质量安全检查strict启用额外提醒与更严的护栏。这与规则文档「对可信计划放宽、对探索收紧」的原则在操作层面对应起来探索阶段可切minimal交付前可切strict并配合ECC_GATEGUARD保持门禁开启。七、小结.cursor/rules/common-hooks.md 虽然只有 30 行但它把 ECC Hooks 体系压缩成了三条可执行的工程约定按生命周期分工PreToolUse 管「执行前拦截」唯一可 exit 2 阻止的时机PostToolUse 管「执行后分析」不可阻止Stop 管「响应级最终校验」——仓库的 hooks/hooks.json 与 .cursor/hooks.json 给出了两套 Harness 下的完整落地样例权限收窄而非跳过按计划可信度决定 auto-accept 开关用~/.claude.json的allowedTools白名单替代dangerously-skip-permissions并依靠配置保护类 Hook 兜底用 TodoWrite 前置理解验证在实现前以细粒度清单呈现任务分解借助「顺序、遗漏、多余、粒度、误解」五个信号在编码前拦截偏差。读者可以进一步深入的文件Hook 图定义 hooks/hooks.json 与 hooks/codex-hooks.json、事件与动作类型约束 schemas/hooks.schema.json、Hook 编写契约与全部内置 Hook 说明 hooks/README.md以及 Claude 侧同名规则 rules/common/hooks.md。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考