第10章 钩子与中间件管线

SessionStart → Setup → [UserPromptSubmit →
  PreToolUse → (PermissionRequest) → 工具执行 →
  PostToolUse / PostToolUseFailure → (PermissionDenied) →
  ... → Stop / StopFailure] → SessionEnd

// 伪代码：事件元数据配置
const hookEventMetadata = {
  PreToolUse: {
    matcherField: 'tool_name',     // 按工具名匹配
    values: toolNames,              // 可选的工具名列表
  },
  SessionStart: {
    matcherField: 'source',         // 按启动来源匹配
    values: ['startup', 'resume', 'clear', 'compact'],
  },
  Notification: {
    matcherField: 'notification_type',
    values: ['permission_prompt', 'idle_prompt', ...],
  },
  // ... 其他事件类似
}

// 伪代码：钩子类型的判别联合
type HookCommand =
  | { type: 'command'; command: string; shell?: 'bash' | 'powershell'; ... }
  | { type: 'prompt';  prompt: string;  model?: string; ... }
  | { type: 'agent';   prompt: string;  model?: string; ... }
  | { type: 'http';    url: string;     headers?: Record<string, string>; ... }

// 内部类型（不可序列化到配置文件）
type InternalHook =
  | { type: 'callback'; callback: (input, ...) => Promise<HookJSONOutput>; ... }
  | { type: 'function'; callback: (messages, signal?) => boolean; ... }

退出码 0  → 成功，stdout 可选包含 JSON 控制指令
退出码 2  → 阻塞错误，stderr 内容会反馈给模型
其他退出码 → 非阻塞错误，stderr 仅展示给用户

// 伪代码
function extractMatchQuery(hookInput: HookInput): string | undefined {
  switch (hookInput.hook_event_name) {
    case 'PreToolUse':
    case 'PostToolUse':
    case 'PermissionRequest':
      return hookInput.tool_name        // 例如 "Bash"
    case 'SessionStart':
      return hookInput.source           // 例如 "startup"
    case 'Notification':
      return hookInput.notification_type // 例如 "permission_prompt"
    case 'FileChanged':
      return basename(hookInput.file_path) // 例如 ".envrc"
    // ...
    default:
      return undefined                   // 无匹配字段，所有钩子均触发
  }
}

// 伪代码
filteredMatchers = hookMatchers.filter(matcher =>
  !matcher.matcher || matchesPattern(matchQuery, matcher.matcher)
)

// 伪代码：按 (命名空间, 命令内容, if条件) 三元组去重
const dedupKey = `${pluginRoot ?? ''}\0${hook.command}\0${hook.if ?? ''}`
const uniqueHooks = new Map(hooks.map(h => [dedupKey(h), h]))

// 伪代码
if (hook.if && !ifMatcher(hook.if)) {
  skip(hook)  // 避免 spawn 开销
}

// 伪代码：并行执行所有钩子
const hookPromises = matchingHooks.map(async function* (hook, index) {
  switch (hook.type) {
    case 'callback': yield executeCallback(hook, ...); return;
    case 'function': yield executeFunctionHook(hook, ...); return;
    case 'prompt':   yield execPromptHook(hook, ...); return;
    case 'agent':    yield execAgentHook(hook, ...); return;
    case 'http':     yield execHttpHook(hook, ...); return;
    case 'command':  yield execCommandHook(hook, ...); return;
  }
})

// 逐个消费结果并聚合
for await (const result of all(hookPromises)) {
  aggregate(result)
}

deny > ask > allow > passthrough

// 伪代码：权限决策聚合
function aggregatePermission(current, incoming) {
  if (incoming === 'deny')  return 'deny'      // deny 永远最高优先
  if (incoming === 'ask') {
    if (current !== 'deny') return 'ask'        // ask 仅次于 deny
  }
  if (incoming === 'allow') {
    if (current === undefined) return 'allow'   // allow 仅在无其他决策时生效
  }
  // passthrough 不改变当前决策
  return current
}

userSettings (最高) → projectSettings → localSettings → pluginHook → builtinHook (最低)

// 伪代码
function sortMatchersByPriority(matchers, hooksByEvent, event) {
  const sourcePriority = {
    userSettings: 0,     // 最高优先级
    projectSettings: 1,
    localSettings: 2,
    pluginHook: 999,     // 最低优先级
    builtinHook: 999,
  }

  return matchers.sort((a, b) => {
    const aPriority = min(a.hooks.map(h => sourcePriority[h.source]))
    const bPriority = min(b.hooks.map(h => sourcePriority[h.source]))
    if (aPriority !== bPriority) return aPriority - bPriority
    return a.localeCompare(b)  // 同优先级按名称排序
  })
}

// 伪代码
function shouldSkipHookDueToTrust(): boolean {
  // SDK 模式下信任是隐式的——无需检查
  if (isNonInteractiveSession()) return false

  // 交互模式下，ALL 钩子都需要用户明确授予信任
  return !hasTrustDialogAccepted()
}

// 伪代码：策略层级的钩子控制
function getHooksFromAllowedSources() {
  // 组织策略可以完全禁用所有钩子
  if (policySettings.disableAllHooks) return {}

  // 组织策略可以限制只运行管理员定义的钩子
  if (policySettings.allowManagedHooksOnly) return policySettings.hooks

  // 否则合并所有来源
  return mergeAllSettings().hooks
}

// 伪代码：asyncRewake 的唤醒机制
shellCommand.result.then(result => {
  if (result.exitCode === 2) {
    // 退出码 2 表示阻塞错误——注入为通知唤醒模型
    enqueuePendingNotification({
      value: `Stop hook blocking error: ${stderr}`,
      mode: 'task-notification',
    })
  }
})

// 伪代码：会话钩子的存储结构
type SessionHooksState = Map<sessionId, {
  hooks: {
    [event in HookEvent]?: Array<{
      matcher: string
      hooks: Array<{ hook: HookCommand | FunctionHook; onSuccess?: callback }>
    }>
  }
}>

// 伪代码：注册 Stop 事件的函数钩子
addFunctionHook(setAppState, sessionId, 'Stop', '',
  (messages) => hasSuccessfulToolCall(messages, 'StructuredOutput'),
  'You MUST call the StructuredOutput tool to complete this request.'
)

模型输出完成
  ↓
执行 Stop / SubagentStop 钩子（所有匹配的钩子并行）
  ↓
如果有 blockingError → 将错误消息注入模型，模型继续推理
如果 preventContinuation → 终止推理循环
  ↓
（仅团队模式）执行 TaskCompleted 钩子
  ↓
（仅团队模式）执行 TeammateIdle 钩子
  ↓
返回最终结果

// 伪代码：Agent 钩子执行
async function execAgentHook(hook, ...) {
  const agentId = generateUniqueId()
  const tools = availableTools.filter(t => !disallowedForAgent(t))
  tools.push(structuredOutputTool)

  // 运行多轮 Agent 循环
  for await (const message of query({
    messages: [userMessage(processedPrompt)],
    systemPrompt: verificationPrompt,
    tools,
  })) {
    if (message is structuredOutput) {
      return message.data.ok ? success : blocking(message.data.reason)
    }
    if (turnCount >= MAX_AGENT_TURNS) {
      abort()
      break
    }
  }
}

// 伪代码
const postSamplingHooks: PostSamplingHook[] = []

async function executePostSamplingHooks(context: REPLHookContext) {
  for (const hook of postSamplingHooks) {
    try {
      await hook(context)
    } catch (error) {
      logError(error)  // 记录但不中断
    }
  }
}

┌──────────────────────────────────────────────────────────────────┐
│                     Agent 主循环 (queryLoop)                      │
│                                                                  │
│  ┌─────────────┐                                                 │
│  │SessionStart │─── SessionStart 钩子 ──→ 注入环境变量/上下文     │
│  └──────┬──────┘                                                 │
│         │                                                        │
│  ┌──────▼──────┐                                                 │
│  │ 用户输入     │─── UserPromptSubmit 钩子 ──→ 拦截/增强/阻塞     │
│  └──────┬──────┘                                                 │
│         │                                                        │
│  ┌──────▼──────┐                                                 │
│  │  LLM 推理   │                                                 │
│  └──────┬──────┘                                                 │
│         │           后采样钩子（内部：记忆提取、提示建议）          │
│  ┌──────▼──────────────────────────────────────────┐             │
│  │ 工具调用处理                                     │             │
│  │                                                  │             │
│  │  ┌──────────────┐    ┌──────────────────────┐   │             │
│  │  │ PreToolUse   │───→│ 匹配 → 并行执行      │   │             │
│  │  │   钩子       │    │ → 权限聚合            │   │             │
│  │  └──────┬───────┘    │  deny > ask > allow   │   │             │
│  │         │            └──────────┬───────────┘   │             │
│  │         ▼                       │                │             │
│  │  PermissionRequest 钩子 ←───────┘                │             │
│  │         │                                        │             │
│  │  ┌──────▼──────┐                                 │             │
│  │  │ 工具执行     │                                 │             │
│  │  └──────┬──────┘                                 │             │
│  │         │                                        │             │
│  │  ┌──────▼──────┐    ┌──────────────────────┐   │             │
│  │  │ PostToolUse │───→│ 注入上下文            │   │             │
│  │  │   钩子      │    │ 修改 MCP 输出         │   │             │
│  │  └─────────────┘    │ 阻塞/继续            │   │             │
│  │                     └──────────────────────┘   │             │
│  └─────────────────────────────────────────────────┘             │
│         │                                                        │
│  ┌──────▼──────┐                                                 │
│  │  Stop 钩子  │─── 阻塞 → 错误消息注入模型，模型继续推理        │
│  │             │─── preventContinuation → 终止循环               │
│  │             │─── 成功 → 正常结束                              │
│  └──────┬──────┘                                                 │
│         │                                                        │
│  ┌──────▼──────┐                                                 │
│  │ SessionEnd  │─── 清理资源，超时 1.5 秒                        │
│  └─────────────┘                                                 │
└──────────────────────────────────────────────────────────────────┘

                  ┌──────────────────────────────┐
                  │     钩子执行器选择             │
                  │                              │
                  │  command → spawn 子进程       │
                  │  prompt  → LLM 单轮推理      │
                  │  agent   → LLM 多轮 Agent    │
                  │  http    → HTTP POST 请求    │
                  │  callback → 内存回调函数      │
                  │  function → 会话函数钩子      │
                  └──────────────────────────────┘

async function* executeHooks({ hookInput, toolUseID, signal, ... }) {
  // 1. 安全门控
  if (disableAllHooksIncludingManaged()) return
  if (shouldSkipHookDueToTrust()) return

  // 2. 匹配钩子
  const matchingHooks = await getMatchingHooks(appState, sessionId, ...)
  if (matchingHooks.length === 0) return

  // 3. 快速路径：纯内部回调跳过序列化/进度/聚合开销
  if (matchingHooks.every(h => isInternalHook(h))) {
    for (const { hook } of matchingHooks) {
      await hook.callback(hookInput, toolUseID, signal)
    }
    return
  }

  // 4. 发射进度消息
  for (const { hook } of matchingHooks) {
    yield { message: progressMessage(hook) }
  }

  // 5. 惰性序列化输入（所有钩子共享同一份 JSON）
  let jsonInput: string | undefined
  function getJsonInput() {
    return jsonInput ??= JSON.stringify(hookInput)
  }

  // 6. 并行执行所有钩子
  const hookPromises = matchingHooks.map(async function* (hook, i) {
    switch (hook.type) {
      case 'callback': yield await executeCallback(hook, ...); return
      case 'function': yield await executeFunctionHook(hook, ...); return
      case 'prompt':   yield await execPromptHook(hook, getJsonInput(), ...); return
      case 'agent':    yield await execAgentHook(hook, getJsonInput(), ...); return
      case 'http':     yield await execHttpHook(hook, getJsonInput(), ...); return
      case 'command':  yield await execCommandHook(hook, getJsonInput(), ...); return
    }
  })

  // 7. 聚合结果
  let permissionBehavior = undefined
  for await (const result of all(hookPromises)) {
    // 权限聚合：deny > ask > allow
    if (result.permissionBehavior === 'deny') {
      permissionBehavior = 'deny'
    } else if (result.permissionBehavior === 'ask' && permissionBehavior !== 'deny') {
      permissionBehavior = 'ask'
    } else if (result.permissionBehavior === 'allow' && !permissionBehavior) {
      permissionBehavior = 'allow'
    }

    // 逐个 yield 阻塞错误、上下文、消息等
    if (result.blockingError) yield { blockingError: result.blockingError }
    if (result.additionalContext) yield { additionalContexts: [result.additionalContext] }
    if (result.preventContinuation) yield { preventContinuation: true, stopReason: ... }
    if (permissionBehavior) yield { permissionBehavior, updatedInput: ... }
  }
}

async function resolveHookPermissionDecision(hookResult, tool, input, ...) {
  if (hookResult?.behavior === 'allow') {
    const hookInput = hookResult.updatedInput ?? input

    // 关键：即使钩子 allow，deny/ask 规则仍然生效
    const ruleCheck = await checkRuleBasedPermissions(tool, hookInput, ...)
    if (ruleCheck === null) {
      // 无规则冲突，接受钩子的 allow
      return { decision: hookResult, input: hookInput }
    }
    if (ruleCheck.behavior === 'deny') {
      // deny 规则覆盖钩子的 allow
      return { decision: ruleCheck, input: hookInput }
    }
    // ask 规则覆盖钩子的 allow——仍需用户确认
    return { decision: await canUseTool(...), input: hookInput }
  }

  if (hookResult?.behavior === 'deny') {
    return { decision: hookResult, input }  // 钩子 deny 立即生效
  }

  // 无钩子决策或 ask——走正常权限流程
  return { decision: await canUseTool(...), input }
}

let initialHooksConfig: HooksSettings | null = null

function captureHooksConfigSnapshot() {
  initialHooksConfig = getHooksFromAllowedSources()
}

function updateHooksConfigSnapshot() {
  resetSettingsCache()  // 清除缓存确保读取最新磁盘数据
  initialHooksConfig = getHooksFromAllowedSources()
}

function getHooksConfigFromSnapshot() {
  if (initialHooksConfig === null) {
    captureHooksConfigSnapshot()
  }
  return initialHooksConfig
}