Skip to main content
控制

Hooks

Hooks 允许你在 AI 会话的关键生命周期节点注入自定义逻辑，支持审计日志、安全控制、上下文注入和动态行为修改。

事件概览

事件触发时机可控行为
PreToolUse工具调用前拦截 / 放行 / 修改输入
PostToolUse工具执行成功后审计 / 注入上下文 / 覆盖输出
PostToolUseFailure工具执行失败后错误处理 / 日志记录
UserPromptSubmit用户 prompt 发送前注入上下文 / 拦截
SessionStart会话开始时初始化 / 注入上下文
SessionEnd会话结束时清理 / 日志记录
StopAI 停止生成时阻止停止，强制继续
SubagentStart子 Agent 启动时观察 / 日志记录
SubagentStop子 Agent 停止时观察 / 日志记录
PreCompact上下文压缩前观察 / 日志记录
PostCompact上下文压缩后观察 / 日志记录
CwdChanged工作目录变更时观察 / 日志记录
InstructionsLoaded指令文件加载时观察 / 日志记录
FileChanged文件创建/修改/删除时观察 / 日志记录
PermissionRequest权限申请时自动批准 / 拒绝权限请求
完整事件类型定义见 SDK References。

配置

在 options 的 hooks 字段中配置 hooks： 
import { query } from '@qodercn-ai/qodercn-agent-sdk';
import type { HookCallback, HookCallbackMatcher } from '@qodercn-ai/qodercn-agent-sdk';

const result = query({
  prompt: 'perform task',
  options: {
    hooks: {
      PreToolUse: [{ matcher: 'Bash', hooks: [myHook] }],
      PostToolUse: [{ hooks: [auditHook] }],
      SessionEnd: [{ hooks: [logHook] }],
    },
  },
});

for await (const message of result) {
  // process messages
}

Matcher

matcher 字段为正则表达式，只有工具名称匹配时 hook 才会触发： 
const result = query({
  prompt: 'perform task',
  options: {
    hooks: {
      PreToolUse: [
        { matcher: 'Bash', hooks: [bashAuditHook] },           // Bash only
        { matcher: 'File.*|Write|Edit', hooks: [fileAuditHook] },  // File operations
        { hooks: [generalLogHook] },                            // All tools (no matcher)
      ],
    },
  },
});

回调函数

每个 hook 回调接收事件输入、工具调用 ID 和上下文（TypeScript 中为 abort signal）： 
type HookCallback = (
  input: HookInput,
  toolUseID: string | undefined,
  options: { signal: AbortSignal },
) => Promise<HookJSONOutput>;

输入

所有事件共享通用字段：hook_event_name（事件类型）、session_id（会话 ID）、transcript_path（记录文件路径）、cwd（工作目录）。每个事件还有专属字段，如 PreToolUse 的 tool_name 和 tool_input。 完整输入类型定义见 SDK References。

输出

回调返回一个对象 / dict，通过以下字段控制行为：
  • continue: false — 终止会话（Python 中字段名为 continue_，序列化为 JSON "continue"）
  • decision: "block" + reason — 阻止工具执行或阻止 AI 停止
  • hookSpecificOutput — 事件专属输出，如修改工具输入（updatedInput）、覆盖工具输出（updatedToolOutput）、注入上下文（additionalContext）
完整输出类型定义见 SDK References。

示例

安全拦截（PreToolUse）

拦截危险的 shell 命令： 
const securityHook: HookCallback = async (input) => {
  if (input.hook_event_name !== 'PreToolUse') return {};

  if (input.tool_name === 'Bash') {
    const cmd = String((input.tool_input as any)?.command ?? '');
    if (cmd.includes('rm -rf')) {
      return {
        hookSpecificOutput: {
          hookEventName: 'PreToolUse',
          permissionDecision: 'deny',
          permissionDecisionReason: 'Destructive delete operations are not allowed',
        },
      };
    }
  }

  return {};
};

脱敏敏感信息（PostToolUse）

覆盖工具输出，替换 AK/Token 等敏感信息： 
const secretRedactHook: HookCallback = async (input) => {
  if (input.hook_event_name !== 'PostToolUse') return {};

  const content = typeof input.tool_response === 'string'
    ? input.tool_response
    : JSON.stringify(input.tool_response);

  const redacted = content
    .replace(/(?:LTAI|AKID)[A-Za-z0-9]{16,}/g, '<REDACTED_AK>')
    .replace(/Bearer\s+[A-Za-z0-9\-._~+/]+=*/g, 'Bearer <REDACTED>');

  if (redacted === content) return {};

  return {
    hookSpecificOutput: {
      hookEventName: 'PostToolUse',
      updatedToolOutput: redacted,
    },
  };
};

裁剪过长输出（PostToolUse）

截断超长的 Bash 输出，保留头尾： 
const bashSummarizeHook: HookCallback = async (input) => {
  if (input.hook_event_name !== 'PostToolUse') return {};
  if (input.tool_name !== 'Bash') return {};

  const content = String(input.tool_response ?? '');
  const THRESHOLD = 50 * 1024;
  if (content.length <= THRESHOLD) return {};

  const head = content.slice(0, 8 * 1024);
  const tail = content.slice(-4 * 1024);
  const omitted = content.length - head.length - tail.length;
  return {
    hookSpecificOutput: {
      hookEventName: 'PostToolUse',
      updatedToolOutput: `${head}\n\n[... OMITTED ${omitted} chars ...]\n\n${tail}`,
    },
  };
};

强制继续（Stop）

阻止 AI 在任务未完成时停止： 
const keepGoingHook: HookCallback = async (input) => {
  if (input.hook_event_name !== 'Stop') return {};

  if (!isTaskComplete()) {
    return {
      decision: 'block',
      reason: 'Please continue completing the remaining tasks',
    };
  }
  return {};
};

自动批准权限（PermissionRequest）

自动放行 Read 工具的权限请求： 
const autoApproveRead: HookCallback = async (input) => {
  if (input.hook_event_name !== 'PermissionRequest') return {};

  if (input.tool_name === 'Read') {
    return {
      hookSpecificOutput: {
        hookEventName: 'PermissionRequest',
        decision: { behavior: 'allow' },
      },
    };
  }
  return {};
};
完整权限模型请参见权限文档。

审计与安全控制（综合）

组合审计日志和安全拦截： 
import { query } from '@qodercn-ai/qodercn-agent-sdk';
import type { HookCallback } from '@qodercn-ai/qodercn-agent-sdk';
import * as fs from 'fs';

const auditLog = fs.createWriteStream('audit.log', { flags: 'a' });

const securityHook: HookCallback = async (input, toolUseID) => {
  if (input.hook_event_name === 'PreToolUse') {
    // Audit log
    auditLog.write(JSON.stringify({
      event: 'tool_call',
      tool: input.tool_name,
      input: input.tool_input,
      timestamp: new Date().toISOString(),
    }) + '\n');

    // Security check: block curl to external domains
    if (input.tool_name === 'Bash') {
      const cmd = String((input.tool_input as any)?.command ?? '');
      if (/curl\s+https?:\/\/(?!localhost)/.test(cmd)) {
        return {
          hookSpecificOutput: {
            hookEventName: 'PreToolUse',
            permissionDecision: 'deny',
            permissionDecisionReason: 'HTTP requests to external domains are not allowed',
          },
        };
      }
    }
  }

  return {};
};

const result = query({
  prompt: 'run deployment',
  options: {
    hooks: {
      PreToolUse: [{ hooks: [securityHook] }],
    },
  },
});

for await (const message of result) {
  // process messages
}

注意事项

  • Hook 回调应尽快返回，避免阻塞 AI 执行。
  • matcher 匹配 tool_name 字段，正则语法按各自语言解释（TypeScript 为 JavaScript 正则，Python 为 re 模块）。
  • continue: false（Python 中为 continue_: False）可终止会话——仅对 PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、Stop、SubagentStop 事件有效，观察类事件（如 SessionEnd、CwdChanged）会忽略此字段。
  • 当多个 hook 返回冲突的 decision 值时，"deny" / "block" 优先（最严格的规则生效）。
  • 当多个 hook 都设置了 updatedToolOutput 时，最后一个非空值生效。如需链式执行多个转换（如先脱敏再裁剪），请在单个回调内按顺序执行。
  • Python SDK 使用尾部下划线字段名（continue_）以避免与 Python 关键字冲突。SDK 在序列化时会自动转换为线路协议名称（continue）。
快速开始
输入与输出
扩展能力
控制
参考