权限与钩子 —— 两道闸门如何拦住一次工具调用
Q07 讲了工具怎么注册、怎么调。但「能调」不等于「该调」。
一次工具调用要过两道闸门:
- 钩子(hooks)——外部脚本可以改输入、可以拦下、可以塞上下文;
- 权限(permissions)——按模式与规则判定 allow / ask / deny。
两道闸门的顺序、返回值的形状、以及出错时的默认值, 决定了这套 Harness 是不是「安全默认」。
一、29 个钩子事件
HookEventName(packages/core/src/hooks/types.ts:41-70)是一份 29 项枚举。
按阶段分组:
| 阶段 | 事件 |
|---|---|
| 会话 | SessionStart SessionEnd Setup QueryEnd |
| 提示 | UserPromptSubmit InstructionsLoaded |
| 工具 | PreToolUse PostToolUse PostToolUseFailure |
| 权限 | PermissionRequest PermissionDenied |
| 压缩 | PreCompact PostCompact |
| 代理 | SubagentStart SubagentStop TeammateIdle |
| 任务 | TaskCreated TaskCompleted |
| 工作区 | CwdChanged FileChanged |
| 工作树 | WorktreeCreate WorktreeRemove |
| 交互 | Elicitation ElicitationResult Notification |
| 其它 | ImagePrepare ConfigChange Stop StopFailure |
29 个事件不是拍脑袋列的。注意几个成对出现的:
PreToolUse/PostToolUse/PostToolUseFailure—— 成功与失败分开;PreCompact/PostCompact—— 压缩前后各一次;Elicitation/ElicitationResult—— 提问与回答。
失败事件单独列出这件事值得注意。很多 Agent 框架只有「工具执行完」一个钩子, 失败时也走那一条,钩子脚本要自己判断成功与否。 这里拆开,钩子不必再判断。
二、五种钩子实现
HookType(:120-125)只有五个值:
export enum HookType { Command = 'command', Runtime = 'runtime', Http = 'http', Prompt = 'prompt', Agent = 'agent',}这五种的差别不在「什么时候触发」,而在「谁来响应」:
| 类型 | 响应者 | 典型用途 |
|---|---|---|
command |
本地子进程 | shell 脚本检查 |
runtime |
进程内函数 | 内置逻辑 |
http |
远程端点 | 集中式策略服务 |
prompt |
模型 | 用 LLM 判断 |
agent |
子代理 | 复杂判断 |
prompt 和 agent 这两种意味着:钩子本身可以调用模型。
这带来一个递归风险——钩子里再触发钩子。
所以 hookPlanner.ts(423 行)要处理「钩子链深度」的问题。
三、钩子的七种来源
ConfigSource(:19-27)七个值,决定钩子配置的优先级:
export enum ConfigSource { Runtime = 'runtime', Project = 'project', User = 'user', Local = 'local', System = 'system', Plugins = 'plugins', Flag = 'flag',}七层来源,等于七种优先级。这跟权限规则是同一套思路: 项目级配置可以覆盖用户级,但系统级和命令行的不能被子项目覆盖。
四、权限判定的主循环
ToolCheck.run()(packages/core/src/permissions/manager/tool-check.ts:124-225)
是权限判定的入口,102 行里有一条清晰的主线:
const first = await this.runFirstCheck();if (first.kind !== 'ask') { return this.buildDecision(this.request, first, first.kind, 'toolCheck', []);}if (this.askHandler === undefined) { return this.buildDecision(this.request, first, 'deny', 'ask', []);}三步:
- 跑第一次检查 —— allow 或 deny 就直接返回;
- 是 ask 但没有提问处理器 —— 降级成 deny;
- 有提问处理器 —— 弹给用户,等回答。
第 2 步是关键的安全默认:无法提问时,一律拒绝。 反过来如果降级成 allow,「headless 模式 + 有风险工具」就成了绕过权限的口子。
用户批准之后还有一次复查(:196-215):
// Local edits do not revoke an unchanged manual approval. Managed rules// are read live by runChecker; amended inputs still use the latest rules.if (handleResult.input === undefined) snapshot.rules = approvedRules;// Approval settles the ask. Recheck rules without invoking Auto judges again.const recheck = await this.runCheckFor( approvedRequest, snapshot, snapshot.permissionMode !== PermissionModes.Auto,);两件事:
- 用户改了输入(
handleResult.input !== undefined)→ 用新输入复查; - 用户没改 → 用批准前的规则快照复查,避免规则在弹窗期间变化导致反复。
注释里那句「Approval settles the ask」说的是: 用户点了同意,不能再因为 Auto 判定器又弹一次。 否则用户会陷入无限弹窗。
五、三种核心模式
createPermissionModes(packages/core/src/permissions/manager/permission-manager.ts:97-)
定义每个模式怎么处理 ask。AcceptEdits 的实现最能说明问题(:119-140):
[PermissionModes.AcceptEdits]: { resolve: (ask, ctx) => { if (isUnskippable(ask)) { return stampPoint(ask, 'mode.needs_user.keep_ask'); } if (isSafetyObjection(ask)) { return stampPoint(ask, 'mode.safety_objection.keep_ask'); } if ( (ctx.coveredByAcceptEdits !== true && ask.extra?.acceptEditsEligible !== true) || ask.reason.attribution.type === 'hook' ) { return stampPoint(ask, 'mode.accept_edits.ineligible.keep_ask'); } return { kind: 'allow', extra: { ...ask.extra, decisionPoint: 'mode.accept_edits.allow' }, }; },四个判断,前三个都是「保持询问」:
isUnskippable—— 不可跳过的(比如明确的高危操作);isSafetyObjection—— 安全异议;- 不满足编辑条件,或来源是钩子。
第 3 条的后半句很有意思:ask.reason.attribution.type === 'hook'。
钩子拦下的请求,即使在 AcceptEdits 模式下也要问用户。
因为钩子代表外部策略,用户开「自动接受编辑」不等于同意外部策略。
stampPoint 打的是决策点标记(mode.accept_edits.allow 等)。
这让每一次判定都能事后归因到具体规则——出问题能查是哪条规则放行的。
六、Auto 模式的三级判定
permissions/permission-modes/auto/ 目录下有五个判定器:
| 文件 | 行数 | 作用 |
|---|---|---|
classifier.ts |
1,511 | 主判定器 |
llm-transcript.ts |
687 | 把上下文整理成 LLM 可读 |
auto-classifier.ts |
431 | 判定器封装 |
dangerous-rules.ts |
398 | 危险规则表 |
jev-classifier.ts |
352 | JEV 判定 |
三级结构:规则表 → 判定器 → LLM 兜底。
dangerous-rules.ts 是最快的一层,硬编码匹配;
classifier.ts 处理规则表覆盖不到的;
llm-transcript.ts 负责把会话上下文压成提示词,交给模型判断。
层级的意义是成本:规则表几乎零成本, LLM 判定要一次请求。能用规则解决就不该调模型。
七、工程暗坑
1. runChecker 的 catch 返回 deny
:344-346:
} catch { return { kind: 'deny' };}判定器抛异常时一律拒绝。不是 allow 也不是 ask。 这条保证了「判定器写错了也不会放行」。
2. askHandler 抛异常等价于 aborted
:164-168:
try { handleResult = await this.askHandler(ctx);} catch { handleResult = { kind: 'aborted' as const };}提问处理器崩了,按「用户中止」处理,随后走 kind !== 'approved' 的分支降级成 deny。
不重试、不静默放行。
3. 未注册工具的错误处理看调用方
:216-224:
if ( !fallbackUnregistered || (error as Error | undefined)?.name !== 'UnregisteredToolError') { throw error;}return unregisteredToolDecision(this.request);fallbackUnregistered 只对 UnregisteredToolError 生效。
别的错误照抛——不做无差别兜底。
4. 钩子来源的 ask 不能被模式跳过
回到第五节:attribution.type === 'hook' 是保持询问的充分条件。
实现自定义模式时如果漏了这条,等于给钩子开了旁路。
5. 钩子输出有 10,000 字符上限
hooks/types.ts:560:
export const MAX_HOOK_OUTPUT_LENGTH = 10000;超出部分写到文件,只回一段 Full output saved to: 前缀提示(:567)。
避免钩子脚本吐一大坨内容把上下文塞爆。
6. PreToolUse 的裁决进判定上下文
runChecker 里 preToolUseHookVerdict 是 ToolCheckContext 的字段(:304)。
也就是说钩子可以先行表态,判定器能看到它。
两道闸门不是串行无关,而是后者读前者的输出。
八、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/core/src/hooks/types.ts |
1,865 | :19-27 ConfigSource,:41-70 29 个事件 |
:120-125 HookType,:560-567 输出上限 |
||
packages/core/src/hooks/hookRunner.ts |
2,602 | 钩子执行器 |
packages/core/src/hooks/hookEventHandler.ts |
1,797 | 事件分发 |
packages/core/src/hooks/hookSystem.ts |
834 | 系统装配 |
packages/core/src/hooks/hookRegistry.ts |
800 | 注册表 |
packages/core/src/hooks/hookPlanner.ts |
423 | 钩子链规划 |
packages/core/src/hooks/hookAggregator.ts |
381 | 多钩子结果聚合 |
packages/core/src/permissions/manager/tool-check.ts |
411 | :124-225 run 主循环 |
:292-347 runChecker |
||
packages/core/src/permissions/manager/permission-manager.ts |
412 | :97- createPermissionModes |
packages/core/src/permissions/manager/session-permission-manager.ts |
771 | 会话级权限 |
packages/core/src/permissions/permission-modes/auto/classifier.ts |
1,511 | Auto 主判定器 |
packages/core/src/permissions/permission-modes/auto/dangerous-rules.ts |
398 | 危险规则表 |
packages/core/src/permissions/settings/permissionsLoader.ts |
460 | 规则加载 |
九、自己动手验证
node qw-examples/check/08-permission-hooks.mjs预期输出:
hook events: 29hook types: 5config sources: 7permission modes: 5checker catch -> deny: trueask without handler -> deny: true 1865 hooks/types.ts 2602 hooks/hookRunner.ts 1797 hooks/hookEventHandler.ts 411 permissions/manager/tool-check.ts 412 permissions/manager/permission-manager.ts 398 permissions/permission-modes/auto/dangerous-rules.ts改一处试试:把 runChecker 的 catch 分支从 { kind: 'deny' } 改成
{ kind: 'allow' }。
然后故意让某个判定器抛异常(比如传一个畸形输入)。
结果是:所有判定器崩溃的场景都变成静默放行——
包括本该拒绝的写文件操作。这一行就是整套权限体系的地基。
十、下一步
Part B 到此结束。我们已经拆完内核的四层:
- 入口与总线(Q03);
- 对话与回合(Q04);
- 请求装配(Q05);
- 消息协议(Q06);
- 工具与 MCP(Q07);
- 权限与钩子(Q08)。
Part C 转向「上下文与资产」: 上下文怎么攒、怎么压(Q09、Q10), 技能与插件怎么挂进来(Q11), Agent 与 Workflow 怎么编排(Q12)。
本章读完你应该能回答: ① 钩子和权限谁先谁后? ——钩子的裁决(
preToolUseHookVerdict)进入权限判定的上下文,后者读前者。 ② 想 ask 但没人能问,怎么办? ——降级成 deny,不是 allow。 ③ 为什么钩子来源的 ask 在 AcceptEdits 下也要问? ——用户开自动接受编辑,不等于同意外部钩子策略。 ④ 判定器抛异常时怎么处理? ——一律 deny。判定器写错也不会放行。 ⑤ 钩子能不能触发钩子? ——能(prompt/agent型),所以需要hookPlanner管理链深度。