Giới thiệu
Trong bài viết trước, chúng tôi đã phân tích ngược hệ thống bộ nhớ của Anthropic Harness từ mã nguồn bị rò rỉ. Hóa ra bộ nhớ khá đơn giản — các tệp markdown, frontmatter và prompt engineering. Hệ thống công cụ thì ngược lại. Đây là hệ thống con được thiết kế công phu nhất trong toàn bộ codebase: hơn 43 công cụ, một pipeline thực thi theo luồng, một hệ thống phân quyền nhiều lớp, một khung hook và một bộ lập lịch đồng thời — tất cả được kết nối để biến một mô hình ngôn ngữ không trạng thái thành thứ có thể đọc tệp, chạy lệnh shell, tìm kiếm web và sinh ra các tác tử con.
Bài viết này sẽ đi qua vòng đời của một công cụ, từ cách một công cụ được định nghĩa, cách các lệnh gọi công cụ của mô hình được phân phối, cho đến cách kết quả được đưa trở lại cuộc trò chuyện. Nhìn chung, hệ thống được cấu tạo từ bốn lớp: một giao diện công cụ mà mọi công cụ đều triển khai, một registry tập hợp các pool công cụ, một pipeline phân phối xác thực, kiểm tra quyền và thực thi mỗi lệnh gọi, và một bộ lập lịch đồng thời quyết định tác vụ nào chạy song song.
Tổng quan kiến trúc
Giao diện công cụ
Mọi công cụ trong Claude Code đều triển khai cùng một giao diện, được định nghĩa trong Tool.ts. Kiểu dữ liệu là generic với ba tham số: Input (một lược đồ Zod), Output (kiểu kết quả) và P (dữ liệu tiến trình). Trong thực tế, một công cụ là một đối tượng với khoảng 30 phương thức, nhưng chỉ một số phương thức quan trọng để hiểu hệ thống.
Hình dạng cốt lõi:
1type Tool<Input, Output, P> = {2 name: string3 inputSchema: ZodType // Lược đồ Zod để xác thực đầu vào4 call(input, context, canUseTool,5 parentMessage, onProgress): Promise<ToolResult>67 // Khai báo hành vi8 isConcurrencySafe(input): boolean // Có thể chạy song song?9 isReadOnly(input): boolean // Thao tác chỉ đọc?10 isDestructive(input): boolean // Hành động phá hủy?1112 // Quyền và xác thực13 checkPermissions(input, context): Promise<PermissionResult>14 validateInput(input, context): Promise<ValidationResult>1516 // Tích hợp API17 description(input, options): Promise<string>18 prompt(options): Promise<string> // Văn bản system prompt cho công cụ này19 mapToolResultToToolResultBlockParam(result, toolUseId): ToolResultBlockParam2021 // Hiển thị giao diện (React)22 renderToolUseMessage(input, options): ReactNode23 renderToolResultMessage(content, ...): ReactNode24}
Không có công cụ nào triển khai từ đầu. Một hàm factory có tên buildTool() sẽ điền các giá trị mặc định an toàn:
Các giá trị mặc định được cố tình thận trọng. Một tác giả công cụ quên khai báo an toàn đồng thời sẽ nhận được thực thi tuần tự. Một tác giả công cụ quên triển khai kiểm tra quyền sẽ nhận được luồng quyền mặc định. Hệ thống sẽ fail-closed.
Kiểu ToolResult đáng chú ý:
1type ToolResult<T> = {2 data: T // Đầu ra thực tế3 newMessages?: Message[] // Tin nhắn theo dõi tùy chọn4 contextModifier?: (ctx) => ToolUseContext // Thay đổi ngữ cảnh cho công cụ tiếp theo5 mcpMeta?: { ... } // Siêu dữ liệu giao thức MCP6}
contextModifier rất quan trọng — nó cho phép một công cụ thay đổi ngữ cảnh thực thi cho các công cụ tiếp theo trong cùng một lượt. Đây là cách các công cụ như EnterWorktree thay đổi thư mục làm việc cho mọi thứ tiếp theo. Quan trọng là, context modifier chỉ được phép cho các công cụ không an toàn đồng thời. Nếu một công cụ chạy song song, nó không thể sửa đổi trạng thái chia sẻ.
Registry công cụ
Tất cả các công cụ được đăng ký trong một hàm duy nhất: getAllBaseTools() trong tools.ts. Hàm này trả về một mảng phẳng. Một số công cụ luôn có mặt; số khác bị chặn sau các cờ tính năng, biến môi trường hoặc kiểm tra nền tảng.
Luôn khả dụng (16 công cụ)
Công cụ có cờ tính năng (~27 công cụ)
Các công cụ còn lại được bao gồm có điều kiện. Một số bị chặn sau các biến môi trường (USER_TYPE=ant cho các công cụ nội bộ của Anthropic như config và tungsten). Một số bị chặn sau các cờ tính năng thông qua Statsig (web_browser, sleep, monitor). Một số cụ thể cho nền tảng (powershell trên Windows). Một số bị chặn sau các điều kiện kết hợp — công cụ repl yêu cầu cả USER_TYPE=ant và một cờ tính năng REPL.
Danh sách đầy đủ các công cụ có cờ tính năng
Chỉ dành cho Ant: config, tungsten, suggest_background_pr, repl (cũng cần cờ REPL)
Cờ tính năng: web_browser, web_search, sleep, monitor, overflow_test, ctx_inspect, terminal_capture, list_peers, workflow, snip
Trình kích hoạt tác tử: cron_create, cron_delete, cron_list, remote_trigger
Kairos (tác tử chủ động): sleep, send_user_file, push_notification, subscribe_pr
Bầy đa tác tử: team_create, team_delete, send_message
Todo v2: task_create, task_get, task_update, task_list
Môi trường: lsp (ENABLE_LSP_TOOL), enter_worktree / exit_worktree (chế độ worktree), powershell (Windows)
Khám phá công cụ: tool_search (khi pool công cụ lớn)
Chỉ thử nghiệm: testing_permission (NODE_ENV=test)
Công cụ MCP
Ngoài các công cụ tích hợp sẵn, Claude Code hỗ trợ các máy chủ Model Context Protocol (MCP) — các quy trình bên ngoài hiển thị các công cụ riêng của chúng qua một giao thức chuẩn hóa. Các công cụ MCP được đăng ký động trong thời gian chạy từ các máy chủ đã kết nối và được bọc trong cùng một giao diện Tool. Từ góc nhìn của pipeline phân phối, một công cụ MCP không thể phân biệt được với một công cụ tích hợp sẵn.
Mỗi công cụ MCP mang siêu dữ liệu về máy chủ nguồn của nó (mcpInfo: { serverName, toolName }), được sử dụng cho các quy tắc quyền, xử lý lỗi và xác thực. Khi một công cụ MCP thất bại với lỗi xác thực, hệ thống sẽ tự động cập nhật trạng thái của máy chủ thành needs-auth và thông báo vấn đề cho người dùng.
Lắp ráp pool công cụ
Ba hàm lắp ráp tập hợp công cụ cuối cùng:
- getAllBaseTools() — trả về danh sách thô của hơn 43 công cụ tích hợp sẵn với các cờ tính năng được áp dụng
- getTools(permissionContext) — lọc theo các quy tắc deny và isEnabled()
- assembleToolPool(permissionContext, mcpTools) — hợp nhất các công cụ tích hợp sẵn và MCP
Chiến lược hợp nhất trong assembleToolPool() được cân nhắc kỹ lưỡng:
Các công cụ tích hợp sẵn được ưu tiên trước, vì vậy khi xảy ra xung đột tên, công cụ tích hợp sẵn sẽ thắng. Sắp xếp theo thứ tự bảng chữ cái trong mỗi phân vùng giữ cho thứ tự ổn định qua các phiên, điều này quan trọng cho prompt caching — mảng công cụ là một phần của yêu cầu API và việc sắp xếp lại nó sẽ phá vỡ bộ nhớ đệm.
Chiến lược hợp nhất trong assembleToolPool() được cân nhắc kỹ lưỡng:
1// Sắp xếp từng phân vùng theo bảng chữ cái, nối, loại bỏ trùng lặp2const byName = (a, b) => a.name.localeCompare(b.name)3return uniqBy(4 [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),5 'name',6)
Tuần tự hóa API
Trước khi các công cụ đến được API Claude, toolToAPISchema() sẽ chuyển đổi lược đồ Zod của mỗi công cụ sang định dạng JSON Schema của API Anthropic.
Pipeline phân phối
Khi Claude phản hồi, tin nhắn của nó có thể chứa các khối tool_use — các yêu cầu có cấu trúc để gọi các công cụ. Pipeline phân phối xử lý các khối này qua bảy giai đoạn. Mọi lệnh gọi công cụ đều đi qua mọi giai đoạn, theo thứ tự.
Giai đoạn 1: Trích xuất
Trong vòng lặp truy vấn chính (query.ts), các khối tool_use được lọc ra khỏi tin nhắn trợ lý:
1const msgToolUseBlocks = message.message.content.filter(2 content => content.type === 'tool_use',3) as ToolUseBlock[]
Mỗi khối có một name, một đối tượng input và một id duy nhất. Id rất quan trọng — kết quả công cụ phải tham chiếu đến cùng id khi được gửi lại API, nếu không cuộc trò chuyện sẽ bị hỏng.
Giai đoạn 2: Xác thực đầu vào
Lược đồ Zod của công cụ xác thực đầu vào thô bằng safeParse() — một biến thể không ném lỗi trả về dữ liệu hợp lệ hoặc lỗi có cấu trúc. Nếu xác thực thất bại, mô hình sẽ nhận được một thông báo lỗi đã được định dạng với các gợi ý lược đồ và quá trình thực thi sẽ dừng lại cho công cụ đó. Không có mã nào chạy trên đầu vào không hợp lệ.
1const parsedInput = tool.inputSchema.safeParse(input)2if (!parsedInput.success) {3 let errorContent = formatZodValidationError(tool.name, parsedInput.error)4 // Trả về lỗi cho mô hình, bỏ qua thực thi5}
Sau xác thực Zod, một số công cụ chạy kiểm tra validateInput() thứ hai để xác thực ngữ nghĩa không thể diễn đạt trong lược đồ — ví dụ: xác minh rằng một đường dẫn tệp là tuyệt đối, không phải tương đối.
Giai đoạn 3: Hook tiền công cụ
Trước khi kiểm tra quyền, các hook do người dùng cấu hình sẽ thực thi. Đây là các lệnh shell hoặc script bên ngoài kích hoạt khi gọi công cụ. Một hook tiền công cụ có thể:
- Cho phép lệnh gọi công cụ, bỏ qua lời nhắc quyền tương tác
- Từ chối lệnh gọi công cụ hoàn toàn
- Sửa đổi đầu vào trước khi thực thi
- Chặn thực thi bằng thông báo lỗi
- Cung cấp thêm ngữ cảnh cho người dùng
Một bất biến quan trọng: allow của hook không bỏ qua các quy tắc deny từ cài đặt. Mã nguồn có một bình luận rõ ràng về điều này: "Hook 'allow' KHÔNG bỏ qua các quy tắc deny/ask của settings.json." Mục đích là các hook có thể mở cửa, nhưng không thể ghi đè khóa.
Giai đoạn 4: Kiểm tra quyền
Hệ thống quyền là phần phức tạp nhất của pipeline. Nó giải quyết qua nhiều lớp, theo thứ tự:
- Quy tắc deny — được kiểm tra trước. Nếu bất kỳ quy tắc deny nào khớp, quá trình thực thi dừng lại ngay lập tức. Các quy tắc deny là cuối cùng và không thể bị ghi đè bởi bất kỳ lớp nào khác.
- Quy tắc ask — nếu khớp, người dùng sẽ được nhắc phê duyệt (trừ khi sandbox auto-allow được áp dụng cho Bash).
- Quyền cụ thể của công cụ — phương thức checkPermissions() của chính công cụ chạy. Ví dụ, BashTool phân tích lệnh để kiểm tra các quy tắc cấp lệnh con.
- Kiểm tra an toàn — các biện pháp bảo vệ được mã hóa cứng cho các đường dẫn nhạy cảm (.git/, .claude/, cấu hình shell). Các biện pháp này miễn nhiễm với việc bỏ qua — ngay cả ở chế độ full bypass, chúng vẫn yêu cầu phê duyệt tương tác.
- Chế độ quyền — chế độ được cấu hình của người dùng xác định hành vi mặc định.
- Quy tắc allow — được kiểm tra cuối cùng. Nếu một quy tắc allow khớp và không có quy tắc deny/ask nào được kích hoạt, công cụ sẽ tiến hành.
Chế độ quyền
default — Luôn nhắc người dùng cho các quyết định "ask".
acceptEdits — Tự động cho phép các thao tác tệp an toàn (đọc, chỉnh sửa), nhắc cho mọi thứ khác.
bypassPermissions — Tự động cho phép mọi thứ ngoại trừ các quy tắc deny và kiểm tra an toàn.
plan — Phê duyệt một kế hoạch trước, sau đó tuân theo chế độ trước đó để thực thi.
auto — Sử dụng một bộ phân loại AI để quyết định cho phép hay nhắc.
dontAsk — Chuyển đổi tất cả các quyết định "ask" thành "deny" — không bao giờ nhắc, chỉ từ chối.
Các quy tắc quyền đến từ nhiều nguồn, được giải quyết theo thứ tự ưu tiên: policySettings, localSettings, projectSettings, userSettings, flagSettings, cliArg, command, session. Điều này cho phép các chính sách của tổ chức ghi đè tùy chọn người dùng và các đối số CLI ghi đè cả hai.
Giai đoạn 5: Thực thi
Nếu quyền được cấp, phương thức call() của công cụ được gọi:
1const result = await tool.call(2 callInput,3 { ...toolUseContext, toolUseId: toolUseID },4 canUseTool,5 assistantMessage,6 progress => onToolProgress({ toolUseID: progress.toolUseID, data: progress.data })7)
Năm đối số: đầu vào đã được xác thực, ngữ cảnh thực thi (thư mục làm việc, bộ điều khiển hủy bỏ, trạng thái ứng dụng), một callback quyền (cho các công cụ cần yêu cầu thêm quyền trong quá trình thực thi), tin nhắn trợ lý cha và một callback tiến trình cho các cập nhật thời gian thực. Thời lượng được theo dõi trên toàn cầu.
Một chi tiết tinh tế: đầu vào được truyền cho call() là đầu vào gốc của mô hình, không phải phiên bản đã được backfill mà các hook và quyền đã thấy. Điều này bảo toàn tính nhất quán của bản ghi — lệnh gọi công cụ được ghi lại trong cuộc trò chuyện khớp chính xác với những gì mô hình đã tạo ra.
Giai đoạn 6: Hook hậu công cụ
Sau khi thực thi, các hook hậu công cụ kích hoạt. Chúng có thể sửa đổi đầu ra của công cụ MCP, cung cấp thêm ngữ cảnh hoặc chặn cuộc trò chuyện tiếp tục. Cũng có một hook PostToolUseFailure riêng biệt chỉ kích hoạt khi có lỗi, cho các hệ thống bên ngoài cơ hội ghi lại lỗi hoặc đề xuất biện pháp khắc phục.
Giai đoạn 7: Ánh xạ kết quả
Mỗi công cụ triển khai mapToolResultToToolResultBlockParam() để chuyển đổi đầu ra của nó sang định dạng ToolResultBlockParam của API Anthropic — một khối tool_result với tham chiếu tool_use_id và nội dung dạng chuỗi hoặc có cấu trúc.
Nếu kết quả vượt quá một ngưỡng kích thước, nó sẽ được lưu vào đĩa tại sessionDir/tool-results/{toolUseId}.txt và một bản xem trước với tham chiếu tệp sẽ được gửi đến API thay thế. Điều này ngăn các đầu ra lớn (đọc tệp 10.000 dòng, đầu ra lệnh dài dòng) làm phình to ngữ cảnh cuộc trò chuyện.
Bộ lập lịch đồng thời
Khi mô hình phát ra nhiều lệnh gọi công cụ trong một tin nhắn duy nhất, chúng không chạy cùng lúc. Một bộ lập lịch phân vùng chúng thành các lô dựa trên an toàn đồng thời.
Thuật toán rất đơn giản. Duyệt qua các lệnh gọi công cụ theo thứ tự. Với mỗi lệnh, kiểm tra isConcurrencySafe(input). Nếu nó an toàn và lô trước đó cũng an toàn, hãy thêm nó vào lô. Nếu không, hãy bắt đầu một lô mới.
1// Đã đơn giản hóa từ toolOrchestration.ts2for (const toolUse of toolUseMessages) {3 const isSafe = tool.isConcurrencySafe(parsedInput)4 if (isSafe && lastBatch.isConcurrencySafe) {5 lastBatch.blocks.push(toolUse) // Hợp nhất vào lô đồng thời6 } else {7 batches.push({ isConcurrencySafe: isSafe, blocks: [toolUse] })8 }9}
Các lô an toàn chạy đồng thời (tối đa 10, có thể cấu hình qua CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY). Các lô không an toàn chạy tuần tự, mỗi lần một công cụ. Context modifier chỉ được áp dụng giữa các lô, không phải trong chúng.
Trong thực tế, điều này có nghĩa là một tin nhắn như "đọc 5 tệp này" tạo ra một lô đồng thời, trong khi "đọc tệp này, sau đó chỉnh sửa nó" tạo ra hai lô tuần tự. Mô hình thậm chí có thể kích hoạt cả hai mẫu trong một lượt — các lệnh gọi chỉ đọc liên tiếp được gộp lô và lần ghi đầu tiên sẽ phá vỡ lô.
Trình thực thi luồng
Có một đường dẫn thực thi thứ hai: StreamingToolExecutor. Khi tính năng streaming được bật, các công cụ bắt đầu thực thi trong khi mô hình vẫn đang tạo phản hồi của nó. Khi mỗi khối tool_use hoàn thành trong luồng, nó ngay lập tức được xếp hàng để thực thi thay vì chờ phản hồi đầy đủ.
Trình thực thi luồng sử dụng cùng các quy tắc đồng thời nhưng thêm một hành vi: Bash error cascading. Nếu một lệnh Bash thất bại trong khi các công cụ cùng cấp đang chạy song song, trình thực thi sẽ hủy bỏ tất cả các công cụ cùng cấp. Lý do là một lệnh Bash thất bại có khả năng làm mất hiệu lực ngữ cảnh mà các công cụ khác đang hoạt động — tiếp tục chúng sẽ lãng phí thời gian và có thể gây ra các lỗi khó hiểu.
1if (isErrorResult && tool.block.name === BASH_TOOL_NAME) {2 this.hasErrored = true3 this.siblingAbortController.abort('sibling_error')4}
Ví dụ cụ thể
Để làm rõ điều này, hãy xem xét điều gì xảy ra khi mô hình quyết định đọc một tệp. Mô hình phát ra:
1{2 "type": "tool_use",3 "id": "toolu_01XYZ",4 "name": "read",5 "input": { "file_path": "/src/index.ts" }6}
Trích xuất: query.ts lọc cái này khỏi nội dung tin nhắn trợ lý.
- Tra cứu công cụ: findToolByName(tools, "read") tìm FileReadTool.
- Xác thực đầu vào: Zod phân tích cú pháp { file_path: "/src/index.ts" } so với z.object({ file_path: z.string(), offset: z.number().optional(), limit: z.number().optional(), pages: z.string().optional() }). Nó vượt qua.
- Hook tiền công cụ: Bất kỳ hook nào do người dùng cấu hình sẽ kích hoạt. Không hook nào sửa đổi đầu vào.
- Kiểm tra quyền: checkPermissions() của FileReadTool gọi checkReadPermissionForTool(). Các công cụ đọc thường được cho phép trong hầu hết các chế độ quyền.
- Thực thi: FileReadTool.call() đọc tệp, áp dụng đánh số dòng (định dạng cat -n), xử lý PDF/hình ảnh/notebook như các trường hợp đặc biệt.
- Ánh xạ kết quả: Nội dung tệp trở thành một khối tool_result tham chiếu đến "toolu_01XYZ".
- Trả về: Kết quả được thêm vào cuộc trò chuyện dưới dạng tin nhắn người dùng và được gửi trong lệnh gọi API tiếp theo.
Vì FileReadTool khai báo isConcurrencySafe: () => true và isReadOnly: () => true, nếu mô hình đã phát ra năm lệnh gọi đọc trong cùng một tin nhắn, cả năm sẽ thực thi song song.
Tóm tắt
Hệ thống công cụ là xương sống thực thi của Claude Code. Nó nhận ý định của mô hình — được thể hiện dưới dạng các khối tool_use có cấu trúc — và biến nó thành các hành động thực tế trên máy của bạn, với xác thực, quyền và kiểm soát đồng thời ở mọi bước.
Thiết kế có nhiều lớp: một hàm factory buildTool() thận trọng đảm bảo các giá trị mặc định an toàn, một registry có cờ tính năng kiểm soát những gì có sẵn, một pipeline phân phối bảy giai đoạn xác thực và kiểm tra quyền mọi lệnh gọi và một bộ lập lịch đồng thời tối đa hóa song song trong khi vẫn bảo toàn tính chính xác. Trình thực thi luồng thêm một tối ưu hóa hiệu suất bên trên — các công cụ bắt đầu chạy trước khi mô hình kết thúc suy nghĩ.
So với hệ thống bộ nhớ (5 đường dẫn, một thư mục các tệp markdown và prompt engineering), hệ thống công cụ là một runtime thực thụ. Đó là sự khác biệt giữa một tủ hồ sơ và một hệ điều hành.
Điều thú vị
Mô hình với tư cách là bộ lập lịch
Bộ lập lịch đồng thời có tính phản ứng — nó gộp lô bất cứ thứ gì mô hình phát ra. Nhưng bản thân mô hình mới là bộ lập lịch thực sự. System prompt yêu cầu nó "thực hiện tất cả các lệnh gọi công cụ độc lập song song" và "sử dụng một lệnh Bash duy nhất với && để xâu chuỗi các lệnh phụ thuộc." Runtime tin tưởng điều này. Nếu mô hình phát ra năm lệnh đọc theo sau là một lệnh ghi, bộ lập lịch sẽ song song hóa các lệnh đọc và tuần tự hóa lệnh ghi. Nhưng mô hình đã quyết định thứ tự đó. Bộ lập lịch đang thực thi kế hoạch của mô hình, chứ không phải tự đưa ra kế hoạch.
Fail-Closed theo mặc định
Nguyên tắc thiết kế nhất quán nhất: mọi thứ đều fail-closed. Công cụ không xác định? Lỗi. Đầu vào không hợp lệ? Lỗi. Không khai báo đồng thời? Thực thi tuần tự. Không khai báo quyền? Hỏi người dùng. Không có cờ tính năng? Công cụ không tồn tại. Điều này khác thường đối với một hệ thống mà người dùng chính là một mô hình AI có thể ảo tưởng về tên công cụ hoặc tạo ra đầu vào sai định dạng. Hệ thống được thiết kế để chứa đựng các lỗi của mô hình, chứ không phải để thích ứng với chúng.
Hook như một điểm mở rộng
Hệ thống hook — tiền công cụ, hậu công cụ và hậu lỗi — là điểm mở rộng chính. Đây là cách các tổ chức thực thi chính sách (quy tắc deny trong pre-hook), cách hệ thống ghi nhật ký thu thập việc sử dụng công cụ (post-hook) và cách các pipeline CI/CD tích hợp (failure hook). Quan trọng là, hook chỉ có thể thắt chặt các hạn chế, chứ không thể nới lỏng chúng. Một hook có thể từ chối một công cụ mà cài đặt cho phép, nhưng nó không thể cho phép một công cụ mà cài đặt từ chối.
43 Công cụ, 1 Giao diện
Có lẽ điều nổi bật nhất là tính đồng nhất. Một lệnh bash, một web_fetch, một subagent spawn, một cron job creation và một push notification đều triển khai cùng một giao diện 30 phương thức, đi qua cùng một pipeline bảy giai đoạn và tuân theo cùng một hệ thống quyền. Không có trường hợp đặc biệt nào trong bộ phân phối. Sự phức tạp nằm trong các triển khai công cụ riêng lẻ và trong các quy tắc quyền, chứ không phải trong định tuyến.
