[Bug] Config-file hooks (PreToolUse/PostToolUse) are not dispatched for subagent tool calls

环境

• ZCode 3.9.1(macOS,arm64,build 2026-08-23)
• 配置:~/.zcode/cli/config.json → hooks.enabled: true + hooks.events.PreToolUse / PostToolUse(command 型 hook)

问题描述

configuration-file hooks(PreToolUse / PostToolUse)只挂载到主会话的工具调用管道;subagent(Agent/Explore 等子代理)的工具调用不经过这些 hooks。

主会话的每次工具调用都会触发 PreToolUse hook(已用执行侧日志验证),但子代理的 Bash 调用完全不触发——导致:

1. 通过 PreToolUse 返回 permissionDecision: "allow" 的自定义权限守卫对子代理无效;
2. 子代理的每条新 pattern Bash 命令都会触发内置权限询问弹窗,即使该命令在主会话中已被 hook 放行。

复现步骤

1. 在 ~/.zcode/cli/config.json 配置一个最简 PreToolUse hook(脚本:每次被调用时向 ~/.zcode/log/hook-exec.log 追加一行时间戳,stdin 读取后输出 {}),设置 hooks.enabled: true;
2. 主会话执行一条 Bash 命令 → 日志文件 +1(正常);
3. 通过 Agent 工具 spawn 一个子代理,让子代理执行一条 Bash 命令;
4. 观察:子代理的 Bash 触发权限弹窗,且 hook-exec.log 没有新增记录。

证据(客户端日志分析)

~/.zcode/cli/log/zcode-2026-08-25.jsonl 中 06:30–06:43Z(本地 14:30–14:43)时段的 tool.permission.resolved 事件按 sessionId 分布:

22  sess_subagent_agent_<uuid>   Bash   (其中 20 次 "Approved once"、2 次 "Approved for this project")
 3  <主会话 sessionId>           Bash
 1  <另一会话>                   Bash

同一时段 hook 执行侧日志仅 12 次调用(对应主会话命令);子代理的 22 次权限解析全部无对应 hook 执行记录。

subagent 会话的 sessionId 命名含 sess_subagent_agent_ 前缀,可直接区分来源。

期望行为

• 期望一:子代理的工具调用同样派发 configuration-file hooks(与主会话一致);
• 或期望二:提供独立配置项(如 hooks.applyToSubagents),允许用户显式控制 hooks 是否覆盖子代理管道。

影响

• 自定义权限守卫(防灾难命令)对子代理存在覆盖盲区;
• 子代理工作流(搜索/探索类任务大量使用 Bash)弹窗频繁,打断体验;当前只能靠"总是允许(本项目)"的 project rules 逐步缓解(该机制对子代理生效,已验证)。

补充诊断线索

• 触发/未触发可用双通道验证:① hook 脚本自身执行侧日志;② 客户端 tool.permission.resolved 事件的 sessionId 是否含 subagent;
• 同一配置在主会话工作正常,可排除配置格式与 hooks.enabled 问题;
• 另附相关历史观察供参考:早期版本(约 8/14)tool 级 config hook 曾完全不派发,后续版本修复了主会话链路——猜测子代理管道是在该修复中遗漏的分支。

Start with the hook settings in ~/.zcode/cli/config.json and compare the hook-execution log with tool.permission.resolved events from sessions whose IDs contain sess_subagent_agent_. Confirm the subagent Bash path that bypasses the hooks; done means the expected hook behavior is defined and verified for subagent tool calls, including the requested configuration alternative if needed.