Hooks 安全、性能与排障

Hook 可以用当前用户权限执行命令，读取输入、输出和继承的环境。其权限不由“只记录日志”的名称决定，应审阅脚本与依赖实际行为。

项目 Hook 身份

CLI 按 Hook name 与 command 生成身份，未见过的项目 Hook 会显示警告，并可能执行后记为受信任。command 改变会触发新身份；警告不是一律要求交互批准的保证。

身份描述没有承诺散列脚本全部内容，因此同一路径脚本内容被修改时，不能仅凭命令字符串没变就认定实现未变。更新第三方项目或扩展后仍需审阅脚本。

环境变量

最佳实践明确环境脱敏默认关闭，与概览笼统的 sanitized environment 说法不同。需要时显式配置：

{
  "security": {
    "environmentVariableRedaction": {
      "enabled": true,
      "allowed": []
    }
  }
}

放入 allowed 的变量绕过脱敏，应只列确需传递的名称；修改需重启。不要为排障把全部 env 输出到可共享日志。

性能

BeforeTool 等频繁事件应使用精确 matcher，独立读取可并行，昂贵结果可缓存。默认超时 60000ms，可为快速校验明确设更短值。AfterModel 每个流块触发，最终质量检查通常放 AfterAgent。

缓存应考虑项目和输入变化，不能仅为了减少耗时复用已经过期的授权决定。

不执行或超时

先在 /hooks panel 确认名称、启用状态、最近输出和耗时；再查 matcher、脚本路径、解释器与执行权限。当前禁用列表是 hooksConfig.disabled，最佳实践旧 hooks.disabled 示例不应直接沿用。

脚本超时应先定位外部依赖与阻塞步骤，不能假设普通失败码会安全阻断工具；阻断语义见协议。

日志隐私

telemetry.logPrompts 开启时 Hook 数据可进入日志，用于调试前应理解包含的提示或代码。suppressOutput: true 隐藏内部元数据，不隐藏终端上的 systemMessage 或 reason，也不撤销脚本自己写出的日志。敏感场景应缩小日志内容并明确设置 logPrompts false。