Hooks钩子是 Deep Agents Code 中用于观察和控制生命周期事件的机制。当特定事件触发时系统会找到匹配的处理器把 JSON 载荷通过 stdin 传给外部命令并根据其退出码和 stdout 决定允许/拒绝操作、注入上下文或继续对话轮次。安全提示Hooks 以当前用户权限运行任意代码配置等同于可执行代码只应从可信来源安装。配置与加载位置用户级~/.deepagents/hooks.json全局生效项目级{project_root}/.deepagents/hooks.json需授予工作区信任后才加载插件也可贡献 hooks结构事件名 → matcher 组 → handlers 数组优先级项目 hooks 用户 hooks 插件 hooks所有匹配的都会并发执行结果按优先级合并快照机制配置在会话中固定修改后需/reload或新会话才生效项目信任交互式会提示确认CI/无头模式需加--trust-project-hooksHandler 定义每个 handler 目前只支持type: commandcommand要执行的 shell 命令必填argv可选直接传参数列表绕过 shelltimeout超时秒数默认 600sUserPromptSubmit默认 30sstatusMessage运行时在 UI 显示的临时提示环境特点工作目录为 payload 中的cwd包含 KEY/TOKEN/SECRET/PASSWORD/APIKEY 的环境变量会被剥离。Matcher匹配器根据事件类型匹配不同字段省略 / 空 /*→ 匹配全部精确名称如Bash|或,分隔多选其他视为正则如mcp__.*UserPromptSubmit和Stop没有 matcher 字段。支持的事件事件所有者退出码 2 的效果匹配字段SessionStartClient诊断sourceUserPromptSubmitClient阻止提示无SessionEndClient诊断reasonPermissionRequestClient拒绝tool_nameNotificationClient诊断notification_typePreToolUseServer拒绝工具tool_namePostToolUseServer反馈tool_namePreCompactServer阻止压缩triggerStopServer继续轮次无SubagentStart / SubagentStopServer诊断 / 添加上下文agent_type工具调用主路径Agent 请求工具 →PreToolUse可 allow/ask/deny→ 工具执行 →PostToolUse。输入 Payload所有事件共享通用字段session_id、transcript_path、cwd、hook_event_name、permission_mode、effort等再加事件专属字段如PreToolUse的tool_name、tool_input、tool_use_id。公开工具名包括Bash、Write、Edit、Read、Glob、Grep、LS、mcp__server__tool等。Handler 输出规则退出码 0成功。stdout 若为合法 JSON 则解析应用非 JSON 在部分事件中作为额外上下文。退出码 2阻塞/反馈路径具体效果见上表主要用 stderr 传原因。其他非零非阻塞错误记录诊断后继续。常用控制方式PreToolUse返回permissionDecisionallow/ask/deny优先级为 deny ask allow。PermissionRequest返回decision.behaviorallow/deny。Stop返回decision: block可让 agent 继续工作有连续 8 次硬限制注意检查stop_hook_active。注入上下文SessionStart、UserPromptSubmit、SubagentStart、PostToolUse、SubagentStop等可返回additionalContext。部分兼容字段如修改工具输入、更新权限规则等会被解析但不生效。典型用例拦截危险 Bash 命令PreToolUse matcherBashSessionStart 时注入最近 git 提交等项目上下文Stop 时发送桌面通知用 Python/其他语言读取 stdin JSON 做自定义逻辑调试与安全运行中会显示 statusMessage错误/警告以 Hook warning/error 形式出现。设置DEEPAGENTS_CODE_DEBUG1可获取更详细诊断。旧版列表式配置仍兼容但已弃用。原则只信任可靠来源、优先使用明确可执行文件、避免把敏感信息暴露给 hook。整体上Hooks 提供了一套灵活的扩展点让你在工具执行前后、会话启停、权限询问等关键节点插入自定义逻辑同时通过优先级、匹配器和输出协议保持可控性。