如何用 hooks 字段拦截并限制 Archon 单个工作流节点的工具调用【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon在 Archon 的 DAG 工作流中节点一旦开始执行AI 会自主地读文件、写代码、跑命令。如果你想控制其中某一个节点能调用哪些工具——比如禁止它执行 shell、禁止它修改文件或者把它的写文件路径重定向到沙箱——就在工作流 YAML 的该节点上配置hooks字段。hooks 在节点的 AI 执行期间拦截工具调用可以允许、拒绝、修改工具入参或向模型注入上下文。需要明确的边界仅 Claude 可用——hooks 是 Claude Agent SDK 的能力Codex 节点会告警并忽略hooks字段。hooks 只对配置了它的那个节点生效节点级字段不是工作流级。hooks属于 AI 节点选项适用于command:和prompt:节点Authoring Workflows 的 Node Fields 表中将其标注为 Per-node SDK hook callbacks. Claude only.。hooks 字段放在哪里、结构是什么工作流文件位于工作目录下的.archon/workflows/。在目标节点上添加hooks按事件名分组每个事件下是一个 matcher 数组nodes: - id: generate prompt: Generate a database migration for $ARGUMENTS hooks: PreToolUse: - matcher: Bash response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: No shell access during SQL generation每个 matcher 条目有三个字段hooks 指南字段必填说明matcher否按工具名过滤的正则省略则匹配所有工具response是hook 触发时返回的 SDKSyncHookJSONOutput原样透传timeout否hook 超时秒数默认 60运行时 Archon 把每个 YAML hook 包装成一个返回response的简单回调没有自定义 DSL——response就是 SDK 类型。一个容易踩的 SDK 要求使用hookSpecificOutput时必须包含与事件键一致的hookEventName字段例如PreToolUsehook 里写hookEventName: PreToolUseSDK 靠它决定处理哪些事件特定字段。事件名有严格的白名单源码见 schema 定义PreToolUse、PostToolUse、PostToolUseFailure、Notification、Stop、SubagentStart、SubagentStop、PreCompact、SessionStart、SessionEnd、UserPromptSubmit、PermissionRequest、Setup、TeammateIdle、TaskCompleted、Elicitation、ElicitationResult、ConfigChange、WorktreeCreate、WorktreeRemove、InstructionsLoaded。schema 使用了.strict()拼错的事件名如preToolUse会在加载时产生明确的校验错误而不是静默忽略。拦截方式一拒绝工具调用PreToolUse deny在PreToolUse的hookSpecificOutput里设置permissionDecisionhooks: PreToolUse: - matcher: Bash response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: Shell access not allowed in this nodepermissionDecision可取deny、allow、ask控制工具是否执行permissionDecisionReason给出原因会显示在日志和模型端。要拒绝多个工具matcher 用正则合并即可hooks: PreToolUse: - matcher: Write|Edit response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: Only read operations are allowed — do not modify filesmatcher 是匹配工具名的正则。文档给出的工具名包括Bash、Read、Write、Edit、Glob、Grep、WebFetch、AgentMCP 工具形如mcp__server__action。拦截方式二不拦截只注入上下文或改写入参additionalContext向模型注入指导文本但不会阻止工具执行——模型会在工具运行前看到这段文字hooks: PreToolUse: - matcher: Write|Edit response: hookSpecificOutput: hookEventName: PreToolUse additionalContext: Only write to files in the src/ directoryupdatedInput直接改写工具的入参例如把Write的目标路径重定向到沙箱hooks: PreToolUse: - matcher: Write response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: allow updatedInput: file_path: /sandbox/output.tsresponse顶层还支持这些字段与hookSpecificOutput并列systemMessage注入一条模型可见的消息、continue: false停止 agent、decision顶层approve/block、stopReason停止原因、suppressOutput。紧急停止的写法hooks: PreToolUse: - matcher: Bash response: continue: false stopReason: Emergency halt — shell access attempted工具成功执行之后用PostToolUse在工具结果后追加上下文hooks: PostToolUse: - matcher: Read response: hookSpecificOutput: hookEventName: PostToolUse additionalContext: You just read a file. Do NOT modify it — analysis only.同一个节点可以同时挂多个 matcher也可以同时启用PreToolUse和PostToolUsematcher 命中时都会触发。一个完整示例只读代码评审节点下面这个工作流里review节点可以读文件但不能执行命令、不能写文件尝试越界时工具调用被拦截模型会看到拒绝原因Hooks and Quality Loops 中的 Permission Denial 示例name: safe-code-review description: Review code without modifying it. nodes: - id: fetch-diff bash: git diff main...HEAD - id: review prompt: Review this diff for bugs and security issues: $fetch-diff.output depends_on: [fetch-diff] hooks: PreToolUse: - matcher: Bash response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: Code review should not execute commands - matcher: Write|Edit response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: Code review is read-only — do not modify files这里fetch-diff是bash:节点没有 AI 执行过程所以不需要也不适合配 hookshooks 只挂在review这一个 AI 节点上。如何判断 hooks 是否生效文档给出的判断依据按时间顺序有三层加载期YAML 校验hooks事件名拼错会在加载时产生校验错误schema 为.strict()未知键直接报错。加载逻辑对每个 hook 校验失败会输出形如node-id: hooks path message的错误。matcher 数组为空的条目会被过滤掉全部为空则整个hooks视为未设置。provider 能力检查如果节点解析到的 provider 不支持 hooks校验器会发出告警Hooks are not supported by provider provider — this will be ignored并提示删除hooks字段或换用支持的 provider。这也是为什么标题强调 Claude 节点同一个 YAML 在 Codex 上只是告警加忽略不会产生错误。运行期deny 命中时工具调用被拦截模型看到permissionDecisionReasoncontinue: false会直接停止 agent。需要注意的是文档明确说明hook 生命周期事件hook_started、hook_progress不会转发到 Web UI所以不要在界面上等这些事件来确认 hook 是否触发只能从模型行为和日志中的拒绝原因观察。hooks 与 allowed_tools/denied_tools 的取舍如果你的需求只是这个节点只能用/不能用某几个工具文档建议直接用allowed_tools/denied_tools——简单的包含/排除即可。两者能力对比hooks 指南原文能力allowed_tools/denied_toolshooks完全阻止某工具是是注入上下文否是additionalContext、systemMessage修改工具入参否是updatedInput覆写工具输出否是updatedMCPToolOutput停止 agent否是continue: false工具使用后的反应否是PostToolUseallowed_tools: []表示禁用所有内置工具字段缺省与空列表语义不同。补充一点allowed_tools/denied_tools支持除 Codex 外的所有 provider而hooks仅 Claude。限制条件静态响应YAML 中的 hook 每次都返回同一个response无法按运行时状态分支。需要条件逻辑时用下游节点的when:条件或用会输出结构化结果的 bash 节点在上游做门控。Claude onlyCodex 节点只告警、忽略 hooks。无 hook 事件流Web UI 看不到 hook 的触发/进度事件。matcher省略意味着匹配所有工具调用配 deny 时相当于拦截该节点的全部工具。继续深入Per-Node Hooks 指南完整的事件表含SessionStart、PreCompact、WorktreeCreate等 21 个事件与各类hookSpecificOutput字段。Hooks and Quality Loops用PostToolUse在每次写文件后触发复查提示的 quality loop 写法。需要外部工具接入而不是限制内置工具时参考 Per-Node MCP Servers 的mcp:字段。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考