🔥 Claude Code 源码解析（三）：揭秘工具系统的精妙设计

一、引言

大家好！我是一个源码爱好者。在上一篇文章中，我们深入了解了 Claude Code 的对话引擎机制。今天，让我们来探索其核心能力的基石------工具系统设计与沙箱安全机制。

相信很多人都好奇，Claude 是如何安全地执行命令、编辑文件、访问网络的？这个工具系统背后隐藏着怎样的设计哲学和安全保障？

在深入源码之前，我想分享一个令人震惊的发现：Claude Code 的沙箱机制竟然实现了完整的文件系统和网络隔离！这意味着即使在复杂环境中，用户数据也能得到充分保护。

二、工具系统架构概览

2.1 整体架构

让我们先来看一下工具系统的整体架构：

┌─────────────────────────────────────────────────────────────┐
│                      工具定义层                            │
│    Tool.ts         工具接口定义                            │
│    buildTool()     工具构建工厂                            │
├─────────────────────────────────────────────────────────────┤
│                      工具实现层                            │
│    BashTool        命令执行工具                            │
│    FileEditTool    文件编辑工具                            │
│    FileReadTool    文件读取工具                            │
│    GrepTool        代码搜索工具                            │
│    LSPTool         语言服务工具                            │
│    ...             其他工具...                            │
├─────────────────────────────────────────────────────────────┤
│                      权限管理层                            │
│    permissions.ts  权限规则引擎                            │
│    hooks.ts        钩子系统                                │
├─────────────────────────────────────────────────────────────┤
│                      沙箱层                                │
│    sandbox-adapter.ts   沙箱适配器                         │
│    @anthropic-ai/sandbox-runtime   底层沙箱运行时          │
└─────────────────────────────────────────────────────────────┘

2.2 核心工具接口

Tool.ts 定义了工具的核心接口，这是整个工具系统的基石：

export type Tool<Input, Output, P> = {
name: string                    // 工具名称
aliases?: string[]             // 别名
searchHint?: string            // 搜索关键词提示
inputSchema: Input             // 输入schema
outputSchema?: Output          // 输出schema
call(                         // 核心执行方法
    args: z.infer<Input>,
    context: ToolUseContext,
    canUseTool: CanUseToolFn,
    parentMessage: AssistantMessage,
    onProgress?: ToolCallProgress<P>,
): Promise<ToolResult<Output>>
description(input, options): Promise<string>  // 描述生成
prompt(options): Promise<string>              // 提示词生成
isConcurrencySafe(input): boolean             // 是否并发安全
isReadOnly(input): boolean                    // 是否只读操作
isDestructive?(input): boolean                // 是否破坏性操作
checkPermissions(input, context): Promise<PermissionResult>  // 权限检查
validateInput?(input, context): Promise<ValidationResult>    // 输入验证
}

这里我踩了个大坑！ 一开始我以为工具只是简单的函数调用，但深入后发现每个工具都需要实现多个接口方法，这是一个非常完整的设计！

三、BashTool：命令执行的安全卫士

3.1 核心功能

BashTool 是最常用的工具之一，它的设计体现了安全性和灵活性的平衡：

export const BashTool = buildTool({
name: BASH_TOOL_NAME,
searchHint: 'execute shell commands',
maxResultSizeChars: 30_000,
strict: true,

// 并发安全判断
isConcurrencySafe(input) {
    return this.isReadOnly(input) ?? false;
},

// 只读判断
isReadOnly(input) {
    const compoundCommandHasCd = commandHasAnyCd(input.command);
    const result = checkReadOnlyConstraints(input, compoundCommandHasCd);
    return result.behavior === 'allow';
},

// 权限检查
async checkPermissions(input, context): Promise<PermissionResult> {
    return bashToolHasPermission(input, context);
},

// 核心执行方法
async call(input, toolUseContext, _canUseTool, parentMessage, onProgress) {
    // 执行命令
    const commandGenerator = runShellCommand({
    input,
    abortController: toolUseContext.abortController,
    setAppState: toolUseContext.setAppStateForTasks ?? setAppState,
    });
    
    // 处理命令执行结果...
}
});

3.2 安全性设计

BashTool 实现了多重安全机制：

1. 只读命令检测

const BASH_READ_COMMANDS = new Set([
'cat', 'head', 'tail', 'less', 'more',
'wc', 'stat', 'file', 'strings',
'jq', 'awk', 'cut', 'sort', 'uniq', 'tr'
]);

const BASH_LIST_COMMANDS = new Set(['ls', 'tree', 'du']);

2. 危险命令警告

const BASH_SILENT_COMMANDS = new Set([
'mv', 'cp', 'rm', 'mkdir', 'rmdir', 
'chmod', 'chown', 'chgrp', 'touch', 'ln'
]);

四、沙箱机制深度解析

4.1 沙箱适配器架构

沙箱机制的核心实现在 sandbox-adapter.ts 中，它是一个适配器层，包装了外部的 @anthropic-ai/sandbox-runtime 包：

import {
SandboxManager as BaseSandboxManager,
SandboxRuntimeConfigSchema,
} from '@anthropic-ai/sandbox-runtime'

export const SandboxManager: ISandboxManager = {
// Claude CLI 自定义实现
initialize,
isSandboxingEnabled,
isSandboxEnabledInSettings: getSandboxEnabledSetting,
isPlatformInEnabledList,
getSandboxUnavailableReason,
// ...

// 转发到基础沙箱管理器
getFsReadConfig: BaseSandboxManager.getFsReadConfig,
getFsWriteConfig: BaseSandboxManager.getFsWriteConfig,
getNetworkRestrictionConfig: BaseSandboxManager.getNetworkRestrictionConfig,
// ...
}

4.2 配置转换机制

convertToSandboxRuntimeConfig 函数负责将 Claude Code 的设置格式转换为沙箱运行时所需的格式：

export function convertToSandboxRuntimeConfig(
settings: SettingsJson,
): SandboxRuntimeConfig {
const permissions = settings.permissions || {};

// 提取网络域名
const allowedDomains: string[] = [];
const deniedDomains: string[] = [];

// 提取文件系统路径
const allowWrite: string[] = ['.', getClaudeTempDir()];
const denyWrite: string[] = [];
const denyRead: string[] = [];
const allowRead: string[] = [];

// 始终拒绝写入 settings.json 文件，防止沙箱逃逸
const settingsPaths = SETTING_SOURCES.map(source =>
    getSettingsFilePathForSource(source),
).filter((p): p is string => p !== undefined);
denyWrite.push(...settingsPaths);
denyWrite.push(getManagedSettingsDropInDir());

// 阻止写入 .claude/skills 目录
denyWrite.push(resolve(originalCwd, '.claude', 'skills'));
if (cwd !== originalCwd) {
    denyWrite.push(resolve(cwd, '.claude', 'skills'));
}

return {
    network: {
    allowedDomains,
    deniedDomains,
    allowUnixSockets: settings.sandbox?.network?.allowUnixSockets,
    // ...
    },
    filesystem: {
    denyRead,
    allowRead,
    allowWrite,
    denyWrite,
    },
    // ...
};
}

4.3 安全防护机制

沙箱实现了多项安全防护：

1. Git 裸仓库攻击防护

// SECURITY: Git 的 is_git_directory() 会将 cwd 视为裸仓库
// 如果存在 HEAD + objects/ + refs/。攻击者植入这些文件可以
// 在 Claude 的非沙箱 git 运行时逃逸沙箱。
const bareGitRepoFiles = ['HEAD', 'objects', 'refs', 'hooks', 'config'];
for (const dir of cwd === originalCwd ? [originalCwd] : [originalCwd, cwd]) {
for (const gitFile of bareGitRepoFiles) {
    const p = resolve(dir, gitFile);
    try {
    statSync(p);
    denyWrite.push(p);  // 已存在的文件：拒绝写入
    } catch {
    bareGitRepoScrubPaths.push(p);  // 不存在的文件：后续清理
    }
}
}

2. 清理植入的裸仓库文件

function scrubBareGitRepoFiles(): void {
for (const p of bareGitRepoScrubPaths) {
    try {
    rmSync(p, { recursive: true });
    logForDebugging(`[Sandbox] scrubbed planted bare-repo file: ${p}`);
    } catch {
    // ENOENT 是预期的常见情况 --- 没有被植入任何文件
    }
}
}

4.4 沙箱初始化流程

async function initialize(
sandboxAskCallback?: SandboxAskCallback,
): Promise<void> {
// 检查沙箱是否启用
if (!isSandboxingEnabled()) {
    return;
}

// 包装回调以强制执行 allowManagedDomainsOnly 策略
const wrappedCallback: SandboxAskCallback | undefined = sandboxAskCallback
    ? async (hostPattern: NetworkHostPattern) => {
        if (shouldAllowManagedSandboxDomainsOnly()) {
        logForDebugging(
            `[sandbox] Blocked network request to ${hostPattern.host} (allowManagedDomainsOnly)`,
        );
        return false;
        }
        return sandboxAskCallback(hostPattern);
    }
    : undefined;

// 创建初始化 promise（在任何 await 之前同步创建）
initializationPromise = (async () => {
    // 检测 git worktree
    if (worktreeMainRepoPath === undefined) {
    worktreeMainRepoPath = await detectWorktreeMainRepoPath(getCwdState());
    }

    const settings = getSettings_DEPRECATED();
    const runtimeConfig = convertToSandboxRuntimeConfig(settings);

    // 初始化基础沙箱管理器
    await BaseSandboxManager.initialize(runtimeConfig, wrappedCallback);

    // 订阅设置变化以动态更新沙箱配置
    settingsSubscriptionCleanup = settingsChangeDetector.subscribe(() => {
    const settings = getSettings_DEPRECATED();
    const newConfig = convertToSandboxRuntimeConfig(settings);
    BaseSandboxManager.updateConfig(newConfig);
    });
})();

return initializationPromise;
}

五、文件编辑工具的精密控制

5.1 输入验证体系

FileEditTool 实现了完整的输入验证流程：

async validateInput(input: FileEditInput, toolUseContext: ToolUseContext) {
const { file_path, old_string, new_string } = input;
const fullFilePath = expandPath(file_path);

// 1. 团队记忆文件秘密检查
const secretError = checkTeamMemSecrets(fullFilePath, new_string);
if (secretError) {
    return { result: false, message: secretError, errorCode: 0 };
}

// 2. 空编辑检查
if (old_string === new_string) {
    return {
    result: false,
    message: 'No changes to make: old_string and new_string are the same.',
    errorCode: 1,
    };
}

// 3. 文件大小限制 (1 GiB)
const { size } = await fs.stat(fullFilePath);
if (size > MAX_EDIT_FILE_SIZE) {
    return {
    result: false,
    message: `File is too large to edit (${formatFileSize(size)}).`,
    errorCode: 10,
    };
}

// 4. 文件修改时间检查
if (lastWriteTime > readTimestamp.timestamp) {
    return {
    result: false,
    message: 'File has been modified since read. Read it again.',
    errorCode: 7,
    };
}

return { result: true };
}

六、权限管理机制

6.1 权限规则引擎

export type ToolPermissionContext = DeepImmutable<{
mode: PermissionMode  // default | plan | auto | bypass
additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
alwaysAllowRules: ToolPermissionRulesBySource
alwaysDenyRules: ToolPermissionRulesBySource
alwaysAskRules: ToolPermissionRulesBySource
isBypassPermissionsModeAvailable: boolean
shouldAvoidPermissionPrompts?: boolean
}>

6.2 权限检查流程

async checkPermissions(input, context): Promise<PermissionResult> {
const appState = context.getAppState();
return checkWritePermissionForTool(
    FileEditTool,
    input,
    appState.toolPermissionContext,
);
}

权限模式对比：

模式	说明	安全性
default	默认模式，需要用户确认	高
plan	计划模式，显示操作预览	高
auto	自动模式，自动批准	中
bypass	绕过权限检查	低

七、总结与思考

通过深入分析 Claude Code 的工具系统和沙箱机制，我有以下几点深刻体会：

1. 安全性优先：多重验证、权限检查、沙箱隔离，构建了完整的安全防护体系
2. 类型安全：使用 Zod 进行严格的输入验证
3. 可扩展性：统一的工具接口，易于添加新工具
4. 防御性编程：针对 Git 裸仓库攻击等安全漏洞进行了专门防护

下一篇预告： 我们将深入分析 Claude Code 的状态管理与数据流机制！

八、互动交流

你们觉得这个工具系统和沙箱机制设计得怎么样？还有什么更好的方法来保证工具执行的安全性？欢迎在评论区交流！

如果觉得这篇文章对你有帮助，请点赞关注支持一下，我们下一篇见！🚀

---

原创不易，点赞关注支持一下！