export type Tool<Input, Output, Progress> = {
  name: string

searchHint?: string  // 3-10 字的能力提示

// 核心执行
call(args, context, canUseTool, parentMessage, onProgress): Promise<ToolResult>

// 模式 (Zod)
readonly inputSchema: Input
readonly outputSchema?: z.ZodType<unknown>

// 安全声明
isConcurrencySafe(input): boolean
isReadOnly(input): boolean

isDestructive?(input): boolean

// 权限钩子
validateInput?(input, context): Promise<ValidationResult>
checkPermissions(input, context): Promise<PermissionResult>
}

洞察力并不在于任何单一领域，而在于类型强制你声明的内容。

每个工具在运行之前必须回答三个问题：它能否与其他工具并行运行？它是否会修改状态？它可能会破坏某些东西吗？这些不是可选注释，而是类型系统所要求的。

我见过的大多数AI工具框架将安全性视为事后考虑——一个你后期添加的包装。Claude Code则将其结构化。你不能在没有事先决定它是否安全的情况下构建工具。

buildTool(): 失败关闭的默认值

所有58个工具都通过一个名为buildTool()的工厂函数进行处理。它提供默认值：

const TOOL_DEFAULTS = {
  isConcurrencySafe: () => false,   // 假设为不安全

isReadOnly: () => false,          // 假设可以写入
  isDestructive: () => false,
  checkPermissions: (input) =>
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
}

再读一遍第一行：isConcurrencySafe: () => false。

如果你忘记声明并发安全性，你的工具默认将以串行执行。如果你忘记声明只读，系统会假设你的工具会进行写操作。默认设置是悲观的。

这是我现在在构建的每个工具系统中使用的模式。当 GrepTool 重写它时：

export const GrepTool = buildTool({
  name: 'Grep',
  searchHint: '使用正则表达式搜索文件内容（ripgrep）',

  isConcurrencySafe() { return true },

isReadOnly() { return true },
})

这个 true 是一个明确的、有意识的声明。开发者必须对此进行思考。

与此相比，LangChain 的 @tool 装饰器中，并没有涉及并发和安全性的问题。你获得了便利，但失去了强制性。

BashTool: 执行前的 22 个安全验证器

BashTool是系统中最复杂的工具。在任何命令运行之前，它会经过22个不同的安全验证器：

const BASH_SECURITY_CHECK_IDS = {
  INCOMPLETE_COMMANDS: 1,
  JQ_SYSTEM_FUNCTION: 2,
  OBFUSCATED_FLAGS: 4,
  SHELL_METACHARACTERS: 5,
  DANGEROUS_PATTERNS_COMMAND_SUBSTITUTION: 8,
  IFS_INJECTION: 11,
  PROC_ENVIRON_ACCESS: 13,
  MALFORMED_TOKEN_INJECTION: 14,
  BRACE_EXPANSION: 16,

控制字符: 17,
Unicode空白: 18,
ZSH危险命令: 20,
注释引号不同步: 22,
// ... 还有9个
}

每个验证器捕获特定类别的shell注入。UNICODE_WHITESPACE 捕获看起来像空格但实际上不是的不可见字符。COMMENT_QUOTE_DESYNC 捕获利用注释和引号解析之间差距的有效载荷。

这是一种深度防御。权限系统处理“这个命令应该执行吗？”安全验证器处理“这个命令看起来是它所声称的那样吗？”

我统计了一下：一个工具有22个验证器。大多数AI代理框架在执行bash时没有任何输入验证。如果你正在构建一个运行shell命令的工具，这就是最低标准。

三层权限架构

Claude Code没有一个权限检查。它有三层，并且按顺序运行：

第一层：validateInput() — 在其他任何操作之前进行语义检查。

// FileEditTool 示例
async validateInput(input, context) {

if (oldString === newString) {
    return { result: false, message: '没有需要更改的内容' }
  }
  const { size } = await fs.stat(fullFilePath)
  if (size > MAX_EDIT_FILE_SIZE) {
    return { result: false, message: '文件过大' }
  }

return { result: true }
}

第2层：checkPermissions() — 用于允许/拒绝/询问决策的规则引擎。

第3层：canUseTool 回调 — 钩子集成。外部系统（工具使用前钩子）可以进行否决。

关键设计决策：验证在权限检查之前进行。如果输入在语义上无效，系统会在检查您是否有权限之前拒绝该输入。这可以防止用户的权限批准被浪费在本来就会失败的请求上。

我已经开始在自己的Python工具中应用这个模式。首先验证，其次授权，最后执行。

ToolSearch：节省令牌的懒加载

Claude Code有58个工具，但模型并不会在每个提示中看到所有58个模式。这会消耗数千个令牌在模型永远不会调用的工具上。

相反，大多数工具是“延迟加载”的。模型只看到它们的名称。当它需要一个工具时，它会调用ToolSearch:

async function searchToolsWithKeywords(query, deferredTools, maxResults) {
  // 快速路径：工具名称的精确匹配
  const exactMatch = deferredTools.find(

t => t.name.toLowerCase() === queryLower
  )
  if (exactMatch) return [exactMatch]

  // 关键字搜索：将 CamelCase 名称解析为单词
  // 根据名称和 searchHint 中的单词边界匹配进行评分
  const matches = scoreAndRankTools(query, deferredTools)
  return matches.slice(0, maxResults)
}

只有在 ToolSearch 返回匹配结果后，完整的架构才会被注入到对话中。

这是一种智能的令牌经济学。searchHint 字段——每个工具声明的 3-10 个单词的描述——就是整个搜索语料库。没有嵌入，没有向量数据库。仅仅是对简短提示的关键词匹配。

如果你正在构建一个拥有超过 10 个工具的代理，借鉴这个模式。保持工具描述简短。懒加载架构。让模型搜索它所需的内容。

我在自己的系统中应用的内容

我维护一个自主内容引擎（Herald），它向 dev.to 发布内容。它具有文章创建、评论监控、参与度跟踪和浏览器自动化的工具。在阅读了 Claude Code 的源代码后，我改变了三件事：

1. 每个工具现在都声明安全属性。 我的 Python 工具具有 is_read_only 和 is_concurrent_safe 作为必需属性，而不是可选的。默认值为 False。

2. 授权前的验证。 我的 Playwright 交互工具现在在检查浏览器会话权限之前验证评论内容（质量门）。这可以在浪费浏览器启动之前捕捉到 LLM 生成的垃圾信息。

3. 懒惰的工具注册。 我的代理不再在启动时加载所有工具架构。工具通过一行描述进行注册。完整的架构在首次使用时加载。

这些都不是革命性的想法。但在大规模、生产代码中为数百万用户提供服务时看到它们的实施，使得这些模式的理解变得更加深刻，而不是仅仅依赖文档。

关键要点

Claude Code 的工具架构并不聪明，而是有纪律的。每个工具都声明其安全属性。默认情况下是安全关闭的。验证在授权之前进行。架构懒加载。安全检查是具体的，而不是通用的。

源代码本不应该公开。但现在既然它已经公开，它就是我见过的最佳 AI 工具设计参考实现。请研究它。

关注 @klement_gunndu 获取更多 AI 工程分析。我们正在公开构建。