knowledge-extension-ecosystem-hooks-and-behavior-interception

name	knowledge-extension-ecosystem-hooks-and-behavior-interception
description	覆盖 Tool、Permission、Session、Stop、Subagent、Compaction、Notification 与 MCP Elicitation 的 Hook 分支、匹配、执行后端、错误策略和摘要信任。进入条件：修改 Hook 事件或输出、排查 Hook 未执行/误阻塞、调整 Session 开关、HTTP 安全或跨领域执行顺序。 不包含：通用 Workspace Trust（见 ../../workspace-policy-and-shared-foundations/）、 MCP 表单协议细节（见 ../mcp-protocol-runtime/）。关键词：HookManager、 HookExecutor、PreToolUse、PermissionRequest、Hook Trust、Function Hook、HTTP Hook。

Module Structure

Hooks 不是独立业务流程，而是在工具、权限、会话、Agent 控制流、上下文压缩和 MCP 交互处改变后续行为的横切分支；HookManager 绑定 Session 配置，HookExecutor 执行 Command、Prompt、Function 或 HTTP 后端并归并事件特定结果。

Directory Layout

• packages/cli/src/hooks/ — 配置、管理、匹配、执行、输出校验、信任与安全后端
• packages/cli/src/tools/execution/ToolExecutionHooks.ts — 工具执行管线的 Pre/Post 适配
• packages/cli/src/server/routes/hooks.ts — Web Session 开关与 trust/revoke API
• packages/cli/src/slash-commands/hooks.ts — TUI/ACP Hook 管理命令
• packages/cli/src/ui/components/HooksManager.tsx — TUI 配置与信任界面
• packages/cli/web/src/components/settings/HookTrustPanel.tsx — Web 信任审阅界面

Key Entry Points

• HookManager.bindSessionConfig() in packages/cli/src/hooks/HookManager.ts — 冻结并关联 source/worktree 的 Session 配置
• HookManager.executePreToolHooks() in packages/cli/src/hooks/HookManager.ts — 工具前置决策与输入改写
• HookExecutor.executeHook() in packages/cli/src/hooks/HookExecutor.ts — trust gate 与后端分派
• runPreToolUseHooks() in packages/cli/src/tools/execution/ToolExecutionHooks.ts — 将 Hook 决策合并回工具准入
• HookTrustService.getStatus() in packages/cli/src/hooks/HookTrustService.ts — 校验当前外部 Hook 摘要

Branching Table

分支维度	分支条件	实际行为
配置与宿主开关	config disabled、进程禁用或 Session 暂停	所有事件返回各自的 pass-through 默认值，不调用 executor
Hook 类型信任	Function Hook	不进入 Hook Trust 摘要，可作为进程内宿主策略直接执行
Hook 类型信任	Command、Prompt、HTTP Hook	仅 trusted 摘要执行；untrusted、modified、error 均跳过并给 warning
工具权限模式	Plan 的 PreToolUse/PostToolUse	直接跳过这两个工具 Hook；其他生命周期事件不因 Plan 自动跳过
工具权限模式	YOLO 的 PreToolUse	保留 deny 和输入修改，把 ask 收敛为 allow
执行顺序	PreToolUse / PermissionRequest / Stop / Compaction	串行执行，可短路或累积前序结果
执行顺序	PostToolUse / PostToolUseFailure / SessionEnd	受 maxConcurrentHooks 限制并行执行，再按配置顺序归并结果
HTTP 目标	默认策略与 allowedHosts 命中	默认要求 HTTPS 且拒绝 loopback/私网/link-local；allowlist 命中会绕过这些限制
失败或超时	behavior=ignore / ask / deny	分别继续并警告、返回确认分支、或立即产生阻塞结果

Affected Scope

• packages/cli/src/tools/execution/ — 工具规则、输入重建、审批、成功/失败结果与后续诊断
• packages/cli/src/agent/runtime/SessionRuntime.ts — SessionStart 环境、配置快照、worktree 别名与 dispose 清理
• packages/cli/src/agent/loop/completionPolicy.ts — 主 Agent Stop Hook 的继续/停止决策
• packages/cli/src/tools/builtin/task/task.ts — SubagentStop 后续提示与再次执行
• packages/cli/src/context/CompactionService.ts — 手动/自动压缩前的阻断分支
• packages/cli/src/mcp/McpClient.ts — Elicitation 展示前和响应回传前的改写或取消
• packages/cli/src/services/GracefulShutdown.ts — 进程退出时触发 SessionEnd
• packages/cli/src/plugins/PluginIntegrator.ts — 插件 Hooks 的整批合并、来源标记与刷新恢复
• packages/cli/src/ui/ — 用户提示提交、Session 级启停与 TUI 信任审阅
• packages/cli/web/src/components/settings/HookTrustPanel.tsx — Web 摘要审阅和 Session 开关

Gotchas

• 默认配置虽然内置 PostToolUse 代码审查 sensor，但 enabled=false；仅把 Hooks 打开且不覆盖 PostToolUse 时才会同时启用这个默认 Prompt Hook(packages/cli/src/hooks/HookConfig.ts)
• Plan 模式只在 executePreToolHooks() 和 executePostToolHooks() 中显式跳过；PermissionRequest、Session、Stop、Compaction 和 Elicitation 不能据此假设自动禁用(packages/cli/src/hooks/HookManager.ts)
• Workspace Trust 与 Hook Trust 是两道独立门：外部 Hook 定义变化会使摘要变为 modified 并立即停止执行，Function Hook 则不计入摘要(packages/cli/src/hooks/HookTrustService.ts)
• 不带 projectDir 注册的 Function Hook 是 manager 级 managed matcher，会作用于所有启用了 Hooks 的项目；带 projectDir 才只进入该项目配置(packages/cli/src/hooks/HookManager.ts, packages/cli/tests/unit/hooks/hook-trust-execution.test.ts)
• YOLO 只把 PreToolUse 的 ask 转为 allow，不能覆盖 Hook deny；原始规则已 deny 时甚至不会运行 PreToolUse Hook(packages/cli/src/hooks/HookManager.ts, packages/cli/src/tools/execution/ToolExecutionHooks.ts)
• PreToolUse 改写参数后会重新构建 invocation、重新校验 worktree isolation 并重新计算规则权限；无效 schema 改写会作为 validation error 拒绝，而不是回退原参数(packages/cli/src/tools/execution/ToolExecutionHooks.ts, packages/cli/src/tools/execution/ToolExecutor.ts)
• PermissionRequest 只在合并后的决策仍为 ask 时运行，并且多个确认由 mutex 串行；它可以批准 ask 或拒绝，但不会获得改写已 deny 规则的机会(packages/cli/src/tools/execution/ToolApprovalController.ts)
• HTTP allowedHosts 命中会同时绕过 HTTPS、loopback 和私网限制，不只是添加域名白名单；配置该字段等价于显式承担目标网络边界(packages/cli/src/hooks/HttpHookSecurity.ts)
• HttpHook.allowInsecureTLS 存在于类型中，但当前 fetch 执行路径未读取该字段；不能依赖它连接自签名 HTTPS 服务(packages/cli/src/hooks/types/HookTypes.ts, packages/cli/src/hooks/HookExecutor.ts)
• Function Hook 超时只能让调用方停止等待，无法强制终止已经运行的 handler；handler 必须自行监听 abortSignal 并清理副作用(packages/cli/src/hooks/HookExecutor.ts)
• Command Hook 的 stdin 限制 100 KiB、stdout/stderr 各 1 MiB，超时或 abort 会终止完整 owned process tree；不要在 Hook 输出中传递无界工具结果(packages/cli/src/hooks/SecureProcessExecutor.ts, git:61a78ea9)
• OutputParser 只把完整 stdout 为单个 JSON object 时视为结构化 HookOutput；JSON 前后混入日志会退回退出码语义(packages/cli/src/hooks/OutputParser.ts)
• ApplyPatch matcher 会提取 Add/Delete/Update 和 Move to 的全部路径，任一路径命中即可触发；只检查第一个 patch 文件会漏掉后续敏感目标(, )

Architecture

• HookManager 保留进程级宿主开关、LRU 有界项目配置和不受 LRU 淘汰影响的 Session 快照；活动 Session 即使项目配置缓存被逐出仍保持原行为(packages/cli/src/hooks/HookManager.ts, git:dff75aca)
• PreToolUse 串行累积 updatedInput 并在首个 deny/ask 短路，PostToolUse 并行执行并合并 additionalContext 与最后一个有效 updatedOutput(packages/cli/src/hooks/HookExecutor.ts)
• Command、Prompt、Function、HTTP 四种后端统一归一到 HookExecutionResult，再由事件专用 reducer 转成权限、继续执行、内容注入、环境或压缩决策(packages/cli/src/hooks/HookExecutor.ts, packages/cli/src/hooks/OutputParser.ts)
• 插件 Hooks 不逐个热插拔；Integrator 保存无插件 base config，将所有 active plugins 的 Hook 追加后一次 load，刷新时再恢复 base，避免残留已卸载插件行为(packages/cli/src/plugins/PluginIntegrator.ts)

Decisions

• Hook Trust 使用 canonical workspace identity 与完整外部配置摘要，而非简单目录布尔值；摘要包含 matcher、策略和插件来源，但排除不可序列化的 Function Hook(packages/cli/src/hooks/HookTrustService.ts, git:a172a7c0)
• 外部 Command Hook 只继承显式 Session 环境和 PATH/HOME/USER/SHELL 最小宿主环境，避免把任意进程凭据泄漏给仓库脚本(packages/cli/src/hooks/SecureProcessExecutor.ts, git:a172a7c0)
• 项目配置缓存限制为 64 项而 Session 配置独立持有，是为了给长期 serve 进程设驻留上限，同时不改变活动会话快照(packages/cli/src/hooks/HookManager.ts, git:dff75aca)

Patterns

• 事件输入统一携带 hook_execution_id、时间戳、project、session 和 permission mode；新增事件必须同时扩展输入联合、输出 schema、manager 构造和 executor reducer(packages/cli/src/hooks/types/HookTypes.ts, packages/cli/src/hooks/schemas/HookSchemas.ts)
• Matcher 对 tools 支持精确、管道和正则，对参数支持 glob；文件工具从约定字段和 patch header 提取路径，Bash 则只从 command 提取匹配值(packages/cli/src/hooks/Matcher.ts, packages/cli/src/hooks/HookManager.ts)

Branching Behavior

• 工具主链路固定为规则权限 → PreToolUse → 改写后重验 → 合并决策 → PermissionRequest/用户确认 → 执行 → PostToolUse → LSP → AutoVerify；移动 Hook 会改变权限和诊断可见性(packages/cli/src/tools/execution/ToolExecutor.ts)
• SessionStart 可阻止初始化或追加环境；其环境在 LSP 和 stdio MCP 创建前冻结并绑定给 HookExecutor，因此启动后修改配置不会追改这些子进程(packages/cli/src/agent/runtime/SessionRuntime.ts)
• Stop Hook 超时或异常按“允许停止”处理，只有明确 continue:false 才让 Agent 继续一轮；外层另有 30 秒保护，不能只依赖单 Hook timeout(packages/cli/src/agent/loop/completionPolicy.ts)
• Compaction Hook 明确 blockCompaction:true 才抛 CompactionBlockedError；Hook 自身异常 fail open，继续正常压缩或 fallback(packages/cli/src/context/CompactionService.ts)
• SubagentStop 明确阻止停止时，会用 continueReason 和已有 messages 再执行一次子代理，而不是把原因仅显示给用户(packages/cli/src/tools/builtin/task/task.ts)
• Elicitation Hook 可以在 UI 前直接回答或拒绝，也可以在用户回答后替换/取消；无论哪条分支，最终都必须通过原 MCP requested schema(packages/cli/src/mcp/McpClient.ts, packages/cli/src/mcp/McpElicitation.ts)