Claude Code 分层多Agent架构篇

https://github.com/shareAI-lab/analysis_claude_code

一、架构概述

1.1 整体架构设计

Claude Code采用了一种创新的分层多Agent架构，通过主Agent和SubAgent的协作来处理复杂任务：

否是用户请求主Agent nO函数是否调用Task工具直接处理工具调用Task工具 p_2对象创建SubAgent I2A函数Agent生命周期管理并发执行协调 UH1函数结果合成器 KN5函数返回合成结果返回处理结果

1.2 核心技术特点

1. 1. 完全隔离的执行环境：每个SubAgent在独立上下文中运行
2. 2. 智能并发调度：支持多Agent并发执行，动态负载均衡
3. 3. 安全权限控制：细粒度的工具权限管理和资源限制
4. 4. 高效结果合成：智能的多Agent结果聚合和冲突解决
5. 5. 弹性错误处理：多层错误隔离和恢复机制

二、Task工具Agent实例化机制

2.1 Task工具核心定义

Task工具是Claude Code多Agent架构的入口点，其核心实现如下：

// Task工具常量定义 (improved-claude-code-5.mjs:25993)
cX = "Task"

// Task工具输入Schema (improved-claude-code-5.mjs:62321-62324)
CN5 = n.object({
    description: n.string().describe("A short (3-5 word) description of the task"),
    prompt: n.string().describe("The task for the agent to perform")
})

// Task工具完整对象结构 (improved-claude-code-5.mjs:62435-62569)
p_2 = {
    // 动态描述生成
    async prompt({ tools: A }) {
        return await u_2(A)  // 调用描述生成函数
    },
    
    name: cX,  // "Task"
    
    async description() {
        return "Launch a new task"
    },
    
    inputSchema: CN5,
    
    // 核心执行函数
    async * call({ prompt: A }, context, J, F) {
        // 实际的Agent启动和管理逻辑
        // 详见后续分析
    },
    
    // 工具特性定义
    isReadOnly() { return true },
    isConcurrencySafe() { return true },
    isEnabled() { return true },
    userFacingName() { return "Task" },
    
    // 权限检查
    async checkPermissions(A) {
        return { behavior: "allow", updatedInput: A }
    }
}

2.2 动态描述生成机制

Task工具的描述是动态生成的，包含了当前可用工具的列表：

// 工具描述生成器 (improved-claude-code-5.mjs:62298-62316)
async function u_2(availableTools) {
    return `Launch a new agent that has access to the following tools: ${
        availableTools
            .filter((tool) => tool.name !== cX)  // 排除Task工具本身，防止递归
            .map((tool) => tool.name)
            .join(", ")
    }. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries, use the Agent tool to perform the search for you.

When to use the Agent tool:
- If you are searching for a keyword like "config" or "logger", or for questions like "which file does X?", the Agent tool is strongly recommended

When NOT to use the Agent tool:
- If you want to read a specific file path, use the ${OB.name} or ${g$.name} tool instead of the Agent tool, to find the match more quickly
- If you are searching for a specific class definition like "class Foo", use the ${g$.name} tool instead, to find the match more quickly
- If you are searching for code within a specific file or set of 2-3 files, use the ${OB.name} tool instead of the Agent tool, to find the match more quickly
- Writing code and running bash commands (use other tools for that)
- Other tasks that are not related to searching for a keyword or file

Usage notes:
1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
4. The agent's outputs should generally be trusted
5. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent`
}

2.3 SubAgent创建流程

SubAgent的创建由I2A函数负责，该函数实现了完整的Agent实例化流程：

// SubAgent启动函数 (improved-claude-code-5.mjs:62353-62433)
async function* I2A(taskPrompt, agentIndex, parentContext, globalConfig, options = {}) {
    const {
        abortController: D,
        options: {
            debug: Y,
            verbose: W,
            isNonInteractiveSession: J
        },
        getToolPermissionContext: F,
        readFileState: X,
        setInProgressToolUseIDs: V,
        tools: C
    } = parentContext;
    
    const {
        isSynthesis: K = false,
        systemPrompt: E,
        model: N
    } = options;
    
    // 生成唯一的Agent ID
    const agentId = VN5();
    
    // 创建初始消息
    const initialMessages = [K2({ content: taskPrompt })];
    
    // 获取配置信息
    const [modelConfig, resourceConfig, selectedModel] = await Promise.all([
        qW(),  // getModelConfiguration
        RE(),  // getResourceConfiguration  
        N ?? J7()  // getDefaultModel
    ]);
    
    // 生成Agent系统提示
    const agentSystemPrompt = await (
        E ?? ma0(selectedModel, Array.from(parentContext.getToolPermissionContext().additionalWorkingDirectories))
    );
    
    // 执行Agent主循环
    let messageHistory = [];
    let toolUseCount = 0;
    let exitPlanInput = undefined;
    
    for await (let agentResponse of nO(  // 主Agent循环函数
        initialMessages,
        agentSystemPrompt,
        modelConfig,
        resourceConfig,
        globalConfig,
        {
            abortController: D,
            options: {
                isNonInteractiveSession: J ?? false,
                tools: C,  // 继承工具集合（但会被过滤）
                commands: [],
                debug: Y,
                verbose: W,
                mainLoopModel: selectedModel,
                maxThinkingTokens: s$(initialMessages),  // 计算思考token限制
                MCPClients: [],
                mcpResources: {}
            },
            getToolPermissionContext: F,
            readFileState: X,
            getQueuedCommands: () => [],
            removeQueuedCommands: () => {},
            setInProgressToolUseIDs: V,
            agentId: agentId
        }
    )) {
        // 过滤和处理Agent响应
        if (agentResponse.type !== "assistant" && 
            agentResponse.type !== "user" && 
            agentResponse.type !== "progress") continue;
            
        messageHistory.push(agentResponse);
        
        // 处理工具使用统计和特殊情况
        if (agentResponse.type === "assistant" || agentResponse.type === "user") {
            const normalizedMessages = AQ(messageHistory);
            
            for (let messageGroup of AQ([agentResponse])) {
                for (let content of messageGroup.message.content) {
                    if (content.type !== "tool_use" && content.type !== "tool_result") continue;
                    
                    if (content.type === "tool_use") {
                        toolUseCount++;
                        
                        // 检查退出计划模式
                        if (content.name === "exit_plan_mode" && content.input) {
                            let validation = hO.inputSchema.safeParse(content.input);
                            if (validation.success) {
                                exitPlanInput = { plan: validation.data.plan };
                            }
                        }
                    }
                    
                    // 生成进度事件
                    yield {
                        type: "progress",
                        toolUseID: K ? `synthesis_${globalConfig.message.id}` : `agent_${agentIndex}_${globalConfig.message.id}`,
                        data: {
                            message: messageGroup,
                            normalizedMessages: normalizedMessages,
                            type: "agent_progress"
                        }
                    };
                }
            }
        }
    }
    
    // 处理最终结果
    const lastMessage = UD(messageHistory);  // 获取最后一条消息
    
    if (lastMessage && oK1(lastMessage)) throw new NG;  // 检查中断
    if (lastMessage?.type !== "assistant") {
        throw new Error(K ? "Synthesis: Last message was not an assistant message" : 
                           `Agent ${agentIndex + 1}: Last message was not an assistant message`);
    }
    
    // 计算token使用量
    const totalTokens = (lastMessage.message.usage.cache_creation_input_tokens ?? 0) + 
                       (lastMessage.message.usage.cache_read_input_tokens ?? 0) + 
                       lastMessage.message.usage.input_tokens + 
                       lastMessage.message.usage.output_tokens;
    
    // 提取文本内容
    const textContent = lastMessage.message.content.filter(content => content.type === "text");
    
    // 保存对话历史
    await CZ0([...initialMessages, ...messageHistory]);
    
    // 返回最终结果
    yield {
        type: "result",
        data: {
            agentIndex: agentIndex,
            content: textContent,
            toolUseCount: toolUseCount,
            tokens: totalTokens,
            usage: lastMessage.message.usage,
            exitPlanModeInput: exitPlanInput
        }
    };
}

三、SubAgent执行上下文分析

3.1 上下文隔离机制

每个SubAgent都在完全隔离的执行上下文中运行，确保安全性和稳定性：

// SubAgent上下文创建（基于代码分析推断）
class SubAgentContext {
    constructor(parentContext, agentId) {
        this.agentId = agentId;
        this.parentContext = parentContext;
        
        // 隔离的工具集合
        this.tools = this.filterToolsForSubAgent(parentContext.tools);
        
        // 继承的权限上下文
        this.getToolPermissionContext = parentContext.getToolPermissionContext;
        
        // 文件状态访问器
        this.readFileState = parentContext.readFileState;
        
        // 资源限制
        this.resourceLimits = {
            maxExecutionTime: 300000,  // 5分钟
            maxToolCalls: 50,
            maxTokens: 100000
        };
        
        // 独立的中断控制器
        this.abortController = new AbortController();
        
        // 独立的工具使用状态管理
        this.setInProgressToolUseIDs = new Set();
    }
    
    // 过滤SubAgent可用的工具
    filterToolsForSubAgent(allTools) {
        // SubAgent被禁用的工具列表
        const blockedTools = ['Task'];  // 防止递归调用
        
        return allTools.filter(tool => !blockedTools.includes(tool.name));
    }
}

3.2 工具权限继承和限制

SubAgent继承了主Agent的基本权限，但受到额外的限制：

// 工具权限过滤器（基于代码分析推断）
class ToolPermissionFilter {
    constructor() {
        this.allowedTools = [
            'Bash', 'Glob', 'Grep', 'LS', 'exit_plan_mode',
            'Read', 'Edit', 'MultiEdit', 'Write',
            'NotebookRead', 'NotebookEdit', 'WebFetch',
            'TodoRead', 'TodoWrite', 'WebSearch'
        ];
        
        this.restrictedOperations = {
            'Write': { maxFileSize: '5MB', requiresValidation: true },
            'Edit': { maxChangesPerCall: 10, requiresBackup: true },
            'Bash': { timeoutSeconds: 120, forbiddenCommands: ['rm -rf', 'sudo'] },
            'WebFetch': { allowedDomains: ['docs.anthropic.com', 'github.com'] }
        };
    }
    
    validateToolAccess(toolName, parameters, agentContext) {
        // 检查工具是否在允许列表中
        if (!this.allowedTools.includes(toolName)) {
            throw new Error(`Tool ${toolName} not allowed for SubAgent`);
        }
        
        // 检查特定工具的限制
        const restrictions = this.restrictedOperations[toolName];
        if (restrictions) {
            this.applyToolRestrictions(toolName, parameters, restrictions);
        }
        
        return true;
    }
}

3.3 资源分配的独立性

每个SubAgent都有独立的资源分配和监控：

// 资源监控器（基于代码分析推断）
class SubAgentResourceMonitor {
    constructor(agentId, limits) {
        this.agentId = agentId;
        this.limits = limits;
        this.usage = {
            startTime: Date.now(),
            tokenCount: 0,
            toolCallCount: 0,
            fileOperations: 0,
            networkRequests: 0
        };
    }
    
    recordTokenUsage(tokens) {
        this.usage.tokenCount += tokens;
        if (this.usage.tokenCount > this.limits.maxTokens) {
            throw new Error(`Token limit exceeded for agent ${this.agentId}`);
        }
    }
    
    recordToolCall(toolName) {
        this.usage.toolCallCount++;
        if (this.usage.toolCallCount > this.limits.maxToolCalls) {
            throw new Error(`Tool call limit exceeded for agent ${this.agentId}`);
        }
    }
    
    checkTimeLimit() {
        const elapsed = Date.now() - this.usage.startTime;
        if (elapsed > this.limits.maxExecutionTime) {
            throw new Error(`Execution time limit exceeded for agent ${this.agentId}`);
        }
    }
}

四、并发执行协调机制

4.1 并发执行策略

Task工具支持两种执行模式：单Agent模式和多Agent并发模式。执行模式由parallelTasksCount配置决定：

// Task工具的并发执行逻辑 (improved-claude-code-5.mjs:62474-62526)
async * call({ prompt: A }, context, J, F) {
    const startTime = Date.now();
    const config = ZA();  // 获取配置
    const executionContext = {
        abortController: context.abortController,
        options: context.options,
        getToolPermissionContext: context.getToolPermissionContext,
        readFileState: context.readFileState,
        setInProgressToolUseIDs: context.setInProgressToolUseIDs,
        tools: context.options.tools.filter((tool) => tool.name !== cX)  // 排除Task工具本身
    };
    
    if (config.parallelTasksCount > 1) {
        // 多Agent并发执行模式
        yield* this.executeParallelAgents(A, executionContext, config, F, J);
    } else {
        // 单Agent执行模式
        yield* this.executeSingleAgent(A, executionContext, F, J);
    }
}

// 并发执行多个Agents
async * executeParallelAgents(taskPrompt, context, config, F, J) {
    let totalToolUseCount = 0;
    let totalTokens = 0;
    
    // 创建多个相同的Agent任务
    const agentTasks = Array(config.parallelTasksCount)
        .fill(`${taskPrompt}\n\nProvide a thorough and complete analysis.`)
        .map((prompt, index) => I2A(prompt, index, context, F, J));
    
    const agentResults = [];
    
    // 并发执行所有Agent任务（最大并发数：10）
    for await (let result of UH1(agentTasks, 10)) {
        if (result.type === "progress") {
            yield result;
        } else if (result.type === "result") {
            agentResults.push(result.data);
            totalToolUseCount += result.data.toolUseCount;
            totalTokens += result.data.tokens;
        }
    }
    
    // 检查是否被中断
    if (context.abortController.signal.aborted) throw new NG;
    
    // 使用合成器合并结果
    const synthesisPrompt = KN5(taskPrompt, agentResults);
    const synthesisAgent = I2A(synthesisPrompt, 0, context, F, J, { isSynthesis: true });
    
    let synthesisResult = null;
    for await (let result of synthesisAgent) {
        if (result.type === "progress") {
            totalToolUseCount++;
            yield result;
        } else if (result.type === "result") {
            synthesisResult = result.data;
            totalTokens += synthesisResult.tokens;
        }
    }
    
    if (!synthesisResult) throw new Error("Synthesis agent did not return a result");
    
    // 检查退出计划模式
    const exitPlanInput = agentResults.find(r => r.exitPlanModeInput)?.exitPlanModeInput;
    
    yield {
        type: "result",
        data: {
            content: synthesisResult.content,
            totalDurationMs: Date.now() - startTime,
            totalTokens: totalTokens,
            totalToolUseCount: totalToolUseCount,
            usage: synthesisResult.usage,
            wasInterrupted: context.abortController.signal.aborted,
            exitPlanModeInput: exitPlanInput
        }
    };
}

4.2 并发调度器实现

UH1函数是核心的并发调度器，实现了异步生成器的并发执行：

// 并发执行调度器 (improved-claude-code-5.mjs:45024-45057)
async function* UH1(generators, maxConcurrency = Infinity) {
    // 包装生成器，添加Promise追踪
    const wrapGenerator = (generator) => {
        const promise = generator.next().then(({ done, value }) => ({
            done,
            value,
            generator,
            promise
        }));
        return promise;
    };
    
    const remainingGenerators = [...generators];
    const activePromises = new Set();
    
    // 启动初始的并发任务
    while (activePromises.size < maxConcurrency && remainingGenerators.length > 0) {
        const generator = remainingGenerators.shift();
        activePromises.add(wrapGenerator(generator));
    }
    
    // 并发执行循环
    while (activePromises.size > 0) {
        // 等待任何一个生成器产生结果
        const { done, value, generator, promise } = await Promise.race(activePromises);
        
        // 移除已完成的Promise
        activePromises.delete(promise);
        
        if (!done) {
            // 生成器还有更多数据，继续执行
            activePromises.add(wrapGenerator(generator));
            if (value !== undefined) yield value;
        } else if (remainingGenerators.length > 0) {
            // 当前生成器完成，启动新的生成器
            const nextGenerator = remainingGenerators.shift();
            activePromises.add(wrapGenerator(nextGenerator));
        }
    }
}

4.3 Agent间通信和同步

Agents之间的通信通过结构化的消息系统实现：

// Agent通信消息类型
const AgentMessageTypes = {
    PROGRESS: "progress",
    RESULT: "result", 
    ERROR: "error",
    STATUS_UPDATE: "status_update"
};

// Agent进度消息结构
interface AgentProgressMessage {
    type: "progress";
    toolUseID: string;
    data: {
        message: any;
        normalizedMessages: any[];
        type: "agent_progress";
    };
}

// Agent结果消息结构
interface AgentResultMessage {
    type: "result";
    data: {
        agentIndex: number;
        content: any[];
        toolUseCount: number;
        tokens: number;
        usage: any;
        exitPlanModeInput?: any;
    };
}

五、Agent生命周期管理

5.1 Agent创建和初始化

每个Agent都有明确的生命周期阶段：

// Agent生命周期状态枚举
const AgentLifecycleStates = {
    INITIALIZING: 'initializing',
    RUNNING: 'running', 
    WAITING: 'waiting',
    COMPLETED: 'completed',
    FAILED: 'failed',
    ABORTED: 'aborted'
};

// Agent实例管理器（基于代码分析推断）
class AgentInstanceManager {
    constructor() {
        this.activeAgents = new Map();
        this.completedAgents = new Map();
        this.agentCounter = 0;
    }
    
    createAgent(taskDescription, taskPrompt, parentContext) {
        const agentId = this.generateAgentId();
        const agentInstance = {
            id: agentId,
            index: this.agentCounter++,
            description: taskDescription,
            prompt: taskPrompt,
            state: AgentLifecycleStates.INITIALIZING,
            startTime: Date.now(),
            context: this.createIsolatedContext(parentContext, agentId),
            resourceMonitor: new SubAgentResourceMonitor(agentId, this.getDefaultLimits()),
            messageHistory: [],
            results: null,
            error: null
        };
        
        this.activeAgents.set(agentId, agentInstance);
        return agentInstance;
    }
    
    generateAgentId() {
        return `agent_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
    }
    
    getDefaultLimits() {
        return {
            maxExecutionTime: 300000,  // 5分钟
            maxTokens: 100000,
            maxToolCalls: 50,
            maxFileOperations: 100
        };
    }
}

5.2 资源管理和清理机制

Agent执行完成后需要进行资源清理：

// 资源清理管理器（基于代码分析推断）
class AgentResourceCleaner {
    constructor() {
        this.cleanupTasks = new Map();
        this.tempFiles = new Set();
        this.activeConnections = new Set();
    }
    
    registerCleanupTask(agentId, cleanupFn) {
        if (!this.cleanupTasks.has(agentId)) {
            this.cleanupTasks.set(agentId, []);
        }
        this.cleanupTasks.get(agentId).push(cleanupFn);
    }
    
    async cleanupAgent(agentId) {
        const tasks = this.cleanupTasks.get(agentId) || [];
        
        // 执行所有清理任务
        const cleanupPromises = tasks.map(async (cleanupFn) => {
            try {
                await cleanupFn();
            } catch (error) {
                console.error(`Cleanup task failed for agent ${agentId}:`, error);
            }
        });
        
        await Promise.all(cleanupPromises);
        
        // 移除清理任务记录
        this.cleanupTasks.delete(agentId);
        
        // 清理临时文件
        await this.cleanupTempFiles(agentId);
        
        // 关闭网络连接
        await this.closeConnections(agentId);
    }
    
    async cleanupTempFiles(agentId) {
        // 清理Agent创建的临时文件
        const agentTempFiles = Array.from(this.tempFiles)
            .filter(file => file.includes(agentId));
            
        for (const file of agentTempFiles) {
            try {
                if (x1().existsSync(file)) {
                    x1().unlinkSync(file);
                }
                this.tempFiles.delete(file);
            } catch (error) {
                console.error(`Failed to delete temp file ${file}:`, error);
            }
        }
    }
}

5.3 超时控制和错误恢复

Agent执行过程中的超时和错误处理：

// Agent超时控制器（基于代码分析推断）
class AgentTimeoutController {
    constructor(agentId, timeoutMs = 300000) {  // 默认5分钟
        this.agentId = agentId;
        this.timeoutMs = timeoutMs;
        this.abortController = new AbortController();
        this.timeoutId = null;
        this.startTime = Date.now();
    }
    
    start() {
        this.timeoutId = setTimeout(() => {
            console.warn(`Agent ${this.agentId} timed out after ${this.timeoutMs}ms`);
            this.abort('timeout');
        }, this.timeoutMs);
        
        return this.abortController.signal;
    }
    
    abort(reason = 'manual') {
        if (this.timeoutId) {
            clearTimeout(this.timeoutId);
            this.timeoutId = null;
        }
        
        this.abortController.abort();
        
        console.log(`Agent ${this.agentId} aborted due to: ${reason}`);
    }
    
    getElapsedTime() {
        return Date.now() - this.startTime;
    }
    
    getRemainingTime() {
        return Math.max(0, this.timeoutMs - this.getElapsedTime());
    }
}

// Agent错误恢复机制（基于代码分析推断）
class AgentErrorRecovery {
    constructor() {
        this.maxRetries = 3;
        this.backoffMultiplier = 2;
        this.baseDelayMs = 1000;
    }
    
    async executeWithRetry(agentFn, agentId, attempt = 1) {
        try {
            return await agentFn();
        } catch (error) {
            if (attempt >= this.maxRetries) {
                throw new Error(`Agent ${agentId} failed after ${this.maxRetries} attempts: ${error.message}`);
            }
            
            const delay = this.baseDelayMs * Math.pow(this.backoffMultiplier, attempt - 1);
            console.warn(`Agent ${agentId} attempt ${attempt} failed, retrying in ${delay}ms: ${error.message}`);
            
            await this.sleep(delay);
            return this.executeWithRetry(agentFn, agentId, attempt + 1);
        }
    }
    
    sleep(ms) {
        return new Promise(resolve => setTimeout(resolve, ms));
    }
}

六、工具白名单和权限控制

6.1 SubAgent工具白名单

SubAgent只能访问预定义的安全工具集合：

// SubAgent可用工具列表（基于代码分析）
const SUBAGENT_ALLOWED_TOOLS = [
    // 文件操作工具
    'Read',         // 文件读取
    'Write',        // 文件写入
    'Edit',         // 文件编辑
    'MultiEdit',    // 批量文件编辑
    'LS',           // 目录列表
    
    // 搜索工具
    'Glob',         // 文件模式匹配
    'Grep',         // 内容搜索
    
    // 系统交互工具
    'Bash',         // 命令执行（受限）
    
    // Notebook工具
    'NotebookRead', // Notebook读取
    'NotebookEdit', // Notebook编辑
    
    // 网络工具
    'WebFetch',     // 网页内容获取（受限域名）
    'WebSearch',    // 网络搜索
    
    // 任务管理工具
    'TodoRead',     // 任务列表读取
    'TodoWrite',    // 任务列表写入
    
    // 计划模式工具
    'exit_plan_mode' // 退出计划模式
];

// 被禁用的工具（不可用于SubAgent）
const SUBAGENT_BLOCKED_TOOLS = [
    'Task',         // 防止递归调用
    // 可能还有其他敏感工具
];

// 工具过滤函数（improved-claude-code-5.mjs:62472）
function filterToolsForSubAgent(allTools) {
    return allTools.filter((tool) => tool.name !== cX);  // cX = "Task"
}

6.2 工具权限验证器

每个工具调用都经过严格的权限验证：

// 工具权限验证系统（基于代码分析推断）
class ToolPermissionValidator {
    constructor() {
        this.permissionMatrix = this.buildPermissionMatrix();
        this.securityPolicies = this.loadSecurityPolicies();
    }
    
    buildPermissionMatrix() {
        return {
            'Read': {
                allowedExtensions: ['.js', '.ts', '.json', '.md', '.txt', '.yaml', '.yml', '.py'],
                maxFileSize: 10 * 1024 * 1024,  // 10MB
                forbiddenPaths: ['/etc/passwd', '/etc/shadow', '~/.ssh', '~/.aws'],
                maxConcurrent: 5
            },
            
            'Write': {
                maxFileSize: 5 * 1024 * 1024,   // 5MB
                forbiddenPaths: ['/etc', '/usr', '/bin', '/sbin'],
                requiresBackup: true,
                maxFilesPerOperation: 10
            },
            
            'Edit': {
                maxChangesPerCall: 10,
                forbiddenPatterns: ['eval(', 'exec(', '__import__', 'subprocess.'],
                requiresValidation: true,
                backupRequired: true
            },
            
            'Bash': {
                timeoutSeconds: 120,
                forbiddenCommands: [
                    'rm -rf', 'dd if=', 'mkfs', 'fdisk', 'chmod 777',
                    'sudo', 'su', 'passwd', 'chown', 'mount'
                ],
                allowedCommands: [
                    'ls', 'cat', 'grep', 'find', 'echo', 'pwd', 'whoami',
                    'ps', 'top', 'df', 'du', 'date', 'uname'
                ],
                maxOutputSize: 1024 * 1024,  // 1MB
                sandboxed: true
            },
            
            'WebFetch': {
                allowedDomains: [
                    'docs.anthropic.com',
                    'github.com',
                    'raw.githubusercontent.com',
                    'api.github.com'
                ],
                maxResponseSize: 5 * 1024 * 1024,  // 5MB
                timeoutSeconds: 30,
                cacheDuration: 900,  // 15分钟
                maxRequestsPerMinute: 10
            },
            
            'WebSearch': {
                maxResults: 10,
                allowedRegions: ['US'],
                timeoutSeconds: 15,
                maxQueriesPerMinute: 5
            }
        };
    }
    
    async validateToolCall(toolName, parameters, agentContext) {
        // 1. 检查工具是否在白名单中
        if (!SUBAGENT_ALLOWED_TOOLS.includes(toolName)) {
            throw new PermissionError(`Tool ${toolName} not allowed for SubAgent`);
        }
        
        // 2. 检查工具特定权限
        const permissions = this.permissionMatrix[toolName];
        if (permissions) {
            await this.enforceToolPermissions(toolName, parameters, permissions, agentContext);
        }
        
        // 3. 检查全局安全策略
        await this.enforceSecurityPolicies(toolName, parameters, agentContext);
        
        // 4. 记录工具使用
        this.logToolUsage(toolName, parameters, agentContext);
        
        return true;
    }
    
    async enforceToolPermissions(toolName, parameters, permissions, agentContext) {
        switch (toolName) {
            case 'Read':
                await this.validateReadPermissions(parameters, permissions);
                break;
            case 'Write':
                await this.validateWritePermissions(parameters, permissions);
                break;
            case 'Edit':
                await this.validateEditPermissions(parameters, permissions);
                break;
            case 'Bash':
                await this.validateBashPermissions(parameters, permissions);
                break;
            case 'WebFetch':
                await this.validateWebFetchPermissions(parameters, permissions);
                break;
            default:
                // 使用默认验证逻辑
                break;
        }
    }
    
    async validateBashPermissions(parameters, permissions) {
        const command = parameters.command.toLowerCase();
        
        // 检查禁止的命令
        for (const forbidden of permissions.forbiddenCommands) {
            if (command.includes(forbidden.toLowerCase())) {
                throw new PermissionError(`Forbidden command: ${forbidden}`);
            }
        }
        
        // 检查命令长度
        if (command.length > 1000) {
            throw new PermissionError('Command too long');
        }
        
        // 检查危险字符
        const dangerousChars = ['|', '&', ';', '`', '$', '(', ')'];
        for (const char of dangerousChars) {
            if (command.includes(char)) {
                console.warn(`Potentially dangerous character in command: ${char}`);
            }
        }
    }
    
    async validateWebFetchPermissions(parameters, permissions) {
        const url = new URL(parameters.url);
        
        // 检查域名白名单
        const isAllowed = permissions.allowedDomains.some(domain => 
            url.hostname === domain || url.hostname.endsWith('.' + domain)
        );
        
        if (!isAllowed) {
            throw new PermissionError(`Domain not allowed: ${url.hostname}`);
        }
        
        // 检查协议
        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
            throw new PermissionError(`Protocol not allowed: ${url.protocol}`);
        }
    }
}

// 权限错误类
class PermissionError extends Error {
    constructor(message, code = 'PERMISSION_DENIED') {
        super(message);
        this.name = 'PermissionError';
        this.code = code;
    }
}

6.3 递归调用防护机制

防止SubAgent递归调用Task工具的多层保护：

// 递归调用防护系统（基于代码分析推断）
class RecursionGuard {
    constructor() {
        this.callStack = new Map();  // agentId -> call depth
        this.maxDepth = 3;
        this.maxAgentsPerLevel = 5;
    }
    
    checkRecursionLimit(agentId, toolName) {
        // 严格禁止Task工具的递归调用
        if (toolName === 'Task') {
            throw new RecursionError('Task tool cannot be called from SubAgent');
        }
        
        // 检查调用深度
        const currentDepth = this.callStack.get(agentId) || 0;
        if (currentDepth >= this.maxDepth) {
            throw new RecursionError(`Maximum recursion depth exceeded: ${currentDepth}`);
        }
        
        return true;
    }
    
    enterCall(agentId) {
        const currentDepth = this.callStack.get(agentId) || 0;
        this.callStack.set(agentId, currentDepth + 1);
    }
    
    exitCall(agentId) {
        const currentDepth = this.callStack.get(agentId) || 0;
        if (currentDepth > 0) {
            this.callStack.set(agentId, currentDepth - 1);
        }
    }
}

class RecursionError extends Error {
    constructor(message) {
        super(message);
        this.name = 'RecursionError';
    }
}

七、结果合成和报告机制

7.1 多Agent结果收集逻辑

多个Agent的执行结果通过专门的收集器统一管理：

// 多Agent结果收集器（基于代码分析）
class MultiAgentResultCollector {
    constructor() {
        this.results = new Map();  // agentIndex -> result
        this.metadata = {
            totalTokens: 0,
            totalToolCalls: 0,
            totalExecutionTime: 0,
            errorCount: 0
        };
    }
    
    addResult(agentIndex, result) {
        this.results.set(agentIndex, result);
        
        // 更新统计信息
        this.metadata.totalTokens += result.tokens || 0;
        this.metadata.totalToolCalls += result.toolUseCount || 0;
        
        if (result.error) {
            this.metadata.errorCount++;
        }
    }
    
    getAllResults() {
        // 按Agent索引排序返回结果
        const sortedResults = Array.from(this.results.entries())
            .sort(([indexA], [indexB]) => indexA - indexB)
            .map(([index, result]) => ({ agentIndex: index, ...result }));
            
        return sortedResults;
    }
    
    getSuccessfulResults() {
        return this.getAllResults().filter(result => !result.error);
    }
    
    hasErrors() {
        return this.metadata.errorCount > 0;
    }
}

7.2 结果格式化和合并

KN5函数负责将多个Agent的结果合并成统一的格式：

// 多Agent结果合成器 (improved-claude-code-5.mjs:62326-62351)
function KN5(originalTask, agentResults) {
    // 按Agent索引排序结果
    const sortedResults = agentResults.sort((a, b) => a.agentIndex - b.agentIndex);
    
    // 提取每个Agent的文本内容
    const agentResponses = sortedResults.map((result, index) => {
        const textContent = result.content
            .filter((content) => content.type === "text")
            .map((content) => content.text)
            .join("\n\n");
        
        return `== AGENT ${index + 1} RESPONSE ==
${textContent}`;
    }).join("\n\n");
    
    // 生成合成提示
    const synthesisPrompt = `Original task: ${originalTask}

I've assigned multiple agents to tackle this task. Each agent has analyzed the problem and provided their findings.

${agentResponses}

Based on all the information provided by these agents, synthesize a comprehensive and cohesive response that:
1. Combines the key insights from all agents
2. Resolves any contradictions between agent findings
3. Presents a unified solution that addresses the original task
4. Includes all important details and code examples from the individual responses
5. Is well-structured and complete

Your synthesis should be thorough but focused on the original task.`;
    
    return synthesisPrompt;
}

7.3 智能总结生成机制

合成Agent使用专门的提示来生成智能总结：

// 智能总结生成器（基于代码分析推断）
class IntelligentSynthesizer {
    constructor() {
        this.synthesisStrategies = {
            'code_analysis': this.synthesizeCodeAnalysis,
            'problem_solving': this.synthesizeProblemSolving,
            'research': this.synthesizeResearch,
            'implementation': this.synthesizeImplementation
        };
    }
    
    async generateSynthesis(originalTask, agentResults, taskType = 'general') {
        // 预处理结果
        const processedResults = this.preprocessResults(agentResults);
        
        // 检测任务类型
        const detectedType = this.detectTaskType(originalTask, processedResults);
        const strategy = this.synthesisStrategies[detectedType] || this.synthesizeGeneral;
        
        // 生成合成内容
        const synthesis = await strategy.call(this, originalTask, processedResults);
        
        return {
            originalTask,
            taskType: detectedType,
            agentCount: agentResults.length,
            synthesis,
            metadata: this.extractMetadata(processedResults)
        };
    }
    
    preprocessResults(agentResults) {
        return agentResults.map(result => ({
            agentIndex: result.agentIndex,
            content: this.extractTextContent(result.content),
            toolsUsed: this.extractToolsUsed(result),
            codeBlocks: this.extractCodeBlocks(result.content),
            findings: this.extractFindings(result.content),
            errors: this.extractErrors(result)
        }));
    }
    
    synthesizeCodeAnalysis(originalTask, processedResults) {
        const allCodeBlocks = processedResults.flatMap(r => r.codeBlocks);
        const allFindings = processedResults.flatMap(r => r.findings);
        
        return {
            summary: this.generateCodeAnalysisSummary(allFindings),
            codeExamples: this.deduplicateCodeBlocks(allCodeBlocks),
            recommendations: this.generateCodeRecommendations(allFindings),
            technicalDetails: this.mergeTechnicalDetails(processedResults)
        };
    }
    
    synthesizeProblemSolving(originalTask, processedResults) {
        const solutions = processedResults.map(r => r.findings);
        const bestSolution = this.rankSolutions(solutions)[0];
        
        return {
            problem: originalTask,
            recommendedSolution: bestSolution,
            alternativeSolutions: solutions.slice(1),
            implementationSteps: this.extractImplementationSteps(processedResults),
            potentialIssues: this.identifyPotentialIssues(processedResults)
        };
    }
    
    extractCodeBlocks(content) {
        const codeBlockRegex = /```[\s\S]*?```/g;
        return content.map(c => c.text || '').join('\n').match(codeBlockRegex) || [];
    }
    
    deduplicateCodeBlocks(codeBlocks) {
        const seen = new Set();
        return codeBlocks.filter(block => {
            const normalized = block.replace(/\s+/g, ' ').trim();
            if (seen.has(normalized)) return false;
            seen.add(normalized);
            return true;
        });
    }
}

7.4 结果一致性保证

确保多Agent结果的一致性和准确性：

// 结果一致性验证器（基于代码分析推断）
class ResultConsistencyValidator {
    constructor() {
        this.consistencyChecks = [
            this.checkFactualConsistency,
            this.checkCodeConsistency,
            this.checkRecommendationConsistency,
            this.checkTimelineConsistency
        ];
    }
    
    async validateConsistency(agentResults) {
        const inconsistencies = [];
        
        for (const check of this.consistencyChecks) {
            try {
                const issues = await check.call(this, agentResults);
                inconsistencies.push(...issues);
            } catch (error) {
                console.error('Consistency check failed:', error);
            }
        }
        
        return {
            isConsistent: inconsistencies.length === 0,
            inconsistencies,
            confidence: this.calculateConfidence(agentResults, inconsistencies)
        };
    }
    
    checkFactualConsistency(agentResults) {
        const facts = this.extractFacts(agentResults);
        const contradictions = [];
        
        // 检查事实性陈述的一致性
        for (let i = 0; i < facts.length; i++) {
            for (let j = i + 1; j < facts.length; j++) {
                if (this.areContradictory(facts[i], facts[j])) {
                    contradictions.push({
                        type: 'factual_contradiction',
                        fact1: facts[i],
                        fact2: facts[j],
                        severity: 'high'
                    });
                }
            }
        }
        
        return contradictions;
    }
    
    checkCodeConsistency(agentResults) {
        const codeBlocks = agentResults.flatMap(r => this.extractCodeBlocks(r.content));
        const inconsistencies = [];
        
        // 检查代码示例的一致性
        const functionNames = this.extractFunctionNames(codeBlocks);
        const variableNames = this.extractVariableNames(codeBlocks);
        
        // 检查命名一致性
        if (this.hasNamingInconsistencies(functionNames)) {
            inconsistencies.push({
                type: 'naming_inconsistency',
                category: 'functions',
                details: functionNames
            });
        }
        
        return inconsistencies;
    }
    
    calculateConfidence(agentResults, inconsistencies) {
        const baseConfidence = 0.8;
        const penaltyPerInconsistency = 0.1;
        const agreementBonus = this.calculateAgreementBonus(agentResults);
        
        return Math.max(0.1, Math.min(1.0, 
            baseConfidence - (inconsistencies.length * penaltyPerInconsistency) + agreementBonus
        ));
    }
}