Bir Claude Code'un araçları nasıl keşfettiği, dağıttığı ve yürüttüğü üzerine derinlemesine bir inceleme
Giriş
Önceki bir yazıda, sızdırılmış kaynak kodundan Anthropic Harness'ın bellek sistemini tersine mühendislikle inceledik. Bellek şaşırtıcı derecede basit çıktı — markdown dosyaları, frontmatter ve prompt mühendisliği. Araç sistemi ise tam tersi. Tüm kod tabanındaki en mühendislik ürünü alt sistemdir: 43'ten fazla araç, bir akış yürütme hattı, katmanlı bir izin sistemi, bir hook framework'ü ve bir eşzamanlılık zamanlayıcısı — tümü, durumsuz bir dil modelini dosyaları okuyabilen, shell komutları çalıştırabilen, internette arama yapabilen ve alt-ajanlar oluşturabilen bir şeye dönüştürmek için birbirine bağlanmıştır.
Bu yazı, bir aracın yaşam döngüsünde size rehberlik eder: bir aracın nasıl tanımlandığından, modelin araç çağrılarının nasıl dağıtıldığına ve sonuçların nasıl sohbete geri aktığına kadar. Genel olarak sistem dört katmandan oluşur: her aracın uyguladığı bir tool interface, araç havuzunu bir araya getiren bir registry, her çağrıyı doğrulayan, izin kontrollerini yapan ve yürüten bir dispatch pipeline ve neyin paralel çalışacağına karar veren bir concurrency scheduler.
Mimariye Genel Bakış
Tool Interface
Claude Code'daki her araç, Tool.ts içinde tanımlanan aynı interface'i uygular. Tür, üç parametre üzerinde geneldir: Input (bir Zod şeması), Output (sonuç türü) ve P (ilerleme verisi). Pratikte bir araç, yaklaşık 30 metodu olan bir nesnedir, ancak sistemi anlamak için sadece birkaçı önemlidir.
Temel yapı:
1type Tool<Input, Output, P> = {2 name: string3 inputSchema: ZodType // Giriş doğrulaması için Zod şeması4 call(input, context, canUseTool,5 parentMessage, onProgress): Promise<ToolResult>67 // Davranış bildirimleri8 isConcurrencySafe(input): boolean // Paralel çalışabilir mi?9 isReadOnly(input): boolean // Salt okunur işlem mi?10 isDestructive(input): boolean // Bozucu eylem mi?1112 // İzin ve doğrulama13 checkPermissions(input, context): Promise<PermissionResult>14 validateInput(input, context): Promise<ValidationResult>1516 // API entegrasyonu17 description(input, options): Promise<string>18 prompt(options): Promise<string> // Bu araç için sistem prompt metni19 mapToolResultToToolResultBlockParam(result, toolUseId): ToolResultBlockParam2021 // UI oluşturma (React)22 renderToolUseMessage(input, options): ReactNode23 renderToolResultMessage(content, ...): ReactNode24}
Hiçbir araç bunu sıfırdan uygulamaz. buildTool() adlı bir fabrika fonksiyonu güvenli varsayılanları doldurur:
Varsayılanlar kasıtlı olarak muhafazakârdır. Eşzamanlılık güvenliğini bildirmeyi unutan bir araç yazarı, sıralı yürütme alır. İzin kontrollerini uygulamayı unutan bir araç yazarı, varsayılan izin akışını alır. Sistem, varsayılan olarak güvenli tarafa kapanır (fail-closed).
ToolResult türü not edilmeye değer:
1type ToolResult<T> = {2 data: T // Gerçek çıktı3 newMessages?: Message[] // İsteğe bağlı takip mesajları4 contextModifier?: (ctx) => ToolUseContext // Sonraki araç için bağlamı değiştir5 mcpMeta?: { ... } // MCP protokol meta verileri6}
contextModifier önemlidir — bir aracın, aynı turdaki sonraki araçlar için yürütme bağlamını değiştirmesine olanak tanır. EnterWorktree gibi araçlar, sonraki her şey için çalışma dizinini bu şekilde değiştirir. Kritik olarak, context modifier'lar yalnızca eşzamanlılık açısından güvenli olmayan araçlar için izin verilir. Bir araç paralel çalışıyorsa, paylaşılan durumu değiştiremez.
Tool Registry
Tüm araçlar, tools.ts dosyasındaki getAllBaseTools() adlı tek bir fonksiyonda kaydedilir. Düz bir dizi döndürür. Bazı araçlar her zaman mevcuttur; diğerleri ise özellik bayrakları, ortam değişkenleri veya platform kontrollerinin arkasına gizlenmiştir.
Her Zaman Mevcut Olanlar (16 araç)
Özellik Bayraklarıyla Gelen Araçlar (~27 araç)
Kalan araçlar koşullu olarak dahil edilir. Bazıları ortam değişkenlerinin arkasına gizlenmiştir (USER_TYPE=ant, config ve tungsten gibi Anthropic iç araçları için). Bazıları Statsig üzerinden özellik bayraklarının arkasına gizlenmiştir (web_browser, sleep, monitor). Bazıları platforma özeldir (Windows'ta powershell). Bazıları ise bileşik koşulların arkasına gizlenmiştir — repl aracı, hem USER_TYPE=ant hem de bir REPL özellik bayrağı gerektirir.
Özellik bayraklarıyla gelen araçların tam listesi
Yalnızca Ant: config, tungsten, suggest_background_pr, repl (ayrıca REPL bayrağı gerekir)
Özellik bayrakları: web_browser, web_search, sleep, monitor, overflow_test, ctx_inspect, terminal_capture, list_peers, workflow, snip
Ajan tetikleyicileri: cron_create, cron_delete, cron_list, remote_trigger
Kairos (proaktif ajan): sleep, send_user_file, push_notification, subscribe_pr
Çoklu ajan sürüleri: team_create, team_delete, send_message
Todo v2: task_create, task_get, task_update, task_list
Ortam: lsp (ENABLE_LSP_TOOL), enter_worktree / exit_worktree (worktree modu), powershell (Windows)
Araç keşfi: tool_search (araç havuzu büyük olduğunda)
Yalnızca test: testing_permission (NODE_ENV=test)
MCP Araçları
Yerleşik araçların ötesinde, Claude Code Model Context Protocol (MCP) sunucularını destekler — standart bir protokol üzerinden kendi araçlarını açığa çıkaran harici süreçler. MCP araçları, bağlı sunuculardan çalışma zamanında dinamik olarak kaydedilir ve aynı Tool interface'i ile sarılır. Dispatch pipeline perspektifinden bakıldığında, bir MCP aracı yerleşik bir araçtan ayırt edilemez.
Her MCP aracı, kaynak sunucusu hakkında meta veriler taşır (mcpInfo: { serverName, toolName }), bu da izin kuralları, hata yönetimi ve kimlik doğrulama için kullanılır. Bir MCP aracı bir kimlik doğrulama hatasıyla başarısız olduğunda, sistem otomatik olarak sunucunun durumunu needs-auth olarak günceller ve sorunu kullanıcıya bildirir.
Araç Havuzunun Oluşturulması
Üç fonksiyon nihai araç setini bir araya getirir:
- getAllBaseTools() — özellik bayrakları uygulanmış 43+ yerleşik aracın ham listesini döndürür
- getTools(permissionContext) — reddetme kurallarına ve isEnabled()'a göre filtreler
- assembleToolPool(permissionContext, mcpTools) — yerleşik ve MCP araçlarını birleştirir
assembleToolPool()'daki birleştirme stratejisi kasıtlıdır:
Yerleşik araçlar önce gelir, böylece bir ad çakışması durumunda yerleşik olan kazanır. Her bölüm içinde alfabetik sıralama, sıralamayı oturumlar arasında sabit tutar; bu, prompt önbelleğe alma için önemlidir — araç dizisi API isteğinin bir parçasıdır ve yeniden sıralamak önbelleği bozabilir.
assembleToolPool()'daki birleştirme stratejisi kasıtlıdır:
1// Her bölümü alfabetik olarak sırala, birleştir, yinelenenleri kaldır2const byName = (a, b) => a.name.localeCompare(b.name)3return uniqBy(4 [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),5 'name',6)
API Serileştirme
Araçlar Claude API'sine ulaşmadan önce, toolToAPISchema() her aracın Zod şemasını Anthropic API'sinin JSON Schema formatına dönüştürür.
Dispatch Pipeline
Claude yanıt verdiğinde, mesajı tool_use blokları içerebilir — araçları çağırmak için yapılandırılmış istekler. Dispatch pipeline, bu blokları yedi aşamada işler. Her araç çağrısı, sırayla her aşamadan geçer.
1. Aşama: Çıkarma (Extraction)
Ana sorgu döngüsünde (query.ts), tool_use blokları asistan mesajından filtrelenir:
1const msgToolUseBlocks = message.message.content.filter(2 content => content.type === 'tool_use',3) as ToolUseBlock[]
Her blok bir name, bir input nesnesi ve benzersiz bir id'ye sahiptir. id kritiktir — araç sonucu, API'ye geri gönderildiğinde aynı id'ye başvurmalıdır, aksi takdirde sohbet bozulur.
2. Aşama: Giriş Doğrulaması (Input Validation)
Aracın Zod şeması, ham girdiyi safeParse() kullanarak doğrular — bu, fırlatma yapmayan bir varyanttır ve ya geçerli veri ya da yapılandırılmış bir hata döndürür. Doğrulama başarısız olursa, model şema ipuçlarıyla biçimlendirilmiş bir hata mesajı alır ve o araç için yürütme durur. Geçersiz girdide hiçbir kod çalışmaz.
1const parsedInput = tool.inputSchema.safeParse(input)2if (!parsedInput.success) {3 let errorContent = formatZodValidationError(tool.name, parsedInput.error)4 // Hatayı modele döndür, yürütmeyi atla5}
Zod doğrulamasından sonra, bazı araçlar bir şemada ifade edilemeyen anlamsal doğrulama için ikinci bir validateInput() kontrollü çalıştırır — örneğin, bir dosya yolunun göreli değil mutlak olduğunu doğrulamak gibi.
3. Aşama: Araç Öncesi Hook'lar (Pre-Tool Hooks)
İzin kontrollerinden önce, kullanıcı tarafından yapılandırılmış hook'lar yürütülür. Bunlar, araç çağrılarında tetiklenen harici shell komutları veya betiklerdir. Bir araç öncesi hook şunları yapabilir:
- Araç çağrısına izin ver (Allow) ve etkileşimli izin istemini atla
- Araç çağrısını doğrudan reddet (Deny)
- Yürütmeden önce girdiyi değiştir (Modify the input)
- Yürütmeyi bir hata mesajıyla engelle (Block execution)
- Kullanıcıya ek bağlam sağla (Provide additional context)
Kritik bir değişmez: bir hook'un allow'u, ayarlardaki reddetme kurallarını atlamaz. Kaynak kodda bu konuda açık bir yorum vardır: "Hook 'allow' does NOT bypass settings.json deny/ask rules." Amaç, hook'ların kapıları açabileceği ancak kilitleri geçersiz kılamayacağıdır.
4. Aşama: İzin Kontrolü (Permission Check)
İzin sistemi, pipeline'ın en karmaşık parçasıdır. Sırayla birden çok katmanı çözer:
- Reddetme kuralları (Deny rules) — önce kontrol edilir. Herhangi bir reddetme kuralı eşleşirse, yürütme hemen durur. Reddetme kuralları nihaidir ve başka hiçbir katman tarafından geçersiz kılınamaz.
- Sorma kuralları (Ask rules) — eşleşirse, kullanıcıdan onay istenir (Bash için sandbox otomatik izni geçerli olmadığı sürece).
- Araca özel izinler (Tool-specific permissions) — aracın kendi checkPermissions() metodu çalışır. Örneğin BashTool, alt komut düzeyindeki kuralları kontrol etmek için komutu ayrıştırır.
- Güvenlik kontrolleri (Safety checks) — hassas yollar için sabit kodlanmış korumalar (.git/, .claude/, shell yapılandırmaları). Bunlar baypas edilemez — tam baypas modunda bile etkileşimli onay gerektirirler.
- İzin modu (Permission mode) — kullanıcının yapılandırılmış modu varsayılan davranışı belirler.
- İzin verme kuralları (Allow rules) — en son kontrol edilir. Bir izin verme kuralı eşleşirse ve hiçbir reddetme/sorma kuralı tetiklenmemişse, araç devam eder.
İzin modları
default — "ask" kararları için her zaman kullanıcıya sor.
acceptEdits — Güvenli dosya işlemlerine (okumalar, düzenlemeler) otomatik izin ver, diğer her şey için sor.
bypassPermissions — Reddetme kuralları ve güvenlik kontrolleri dışında her şeye otomatik izin ver.
plan — Önce bir planı onayla, ardından yürütme için önceki modu izle.
auto — İzin verip vermemeye veya sormaya karar vermek için bir AI sınıflandırıcı kullan.
dontAsk — Tüm "ask" kararlarını "deny" olarak dönüştür — asla sorma, sadece reddet.
İzin kuralları, öncelik sırasına göre çözümlenen birden çok kaynaktan gelir: policySettings, localSettings, projectSettings, userSettings, flagSettings, cliArg, command, session. Bu, kuruluş politikalarının kullanıcı tercihlerini geçersiz kılmasına ve CLI argümanlarının her ikisini de geçersiz kılmasına olanak tanır.
5. Aşama: Yürütme (Execution)
İzin verilirse, aracın call() metodu çağrılır:
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)
Beş argüman: doğrulanmış girdi, bir yürütme bağlamı (çalışma dizini, iptal denetleyicisi, uygulama durumu), bir izin geri çağrısı (yürütme sırasında ek izinler talep etmesi gereken araçlar için), ana asistan mesajı ve gerçek zamanlı güncellemeler için bir ilerleme geri çağrısı. Süre, küresel olarak izlenir.
İnce bir ayrıntı: call()'a aktarılan girdi, modelin orijinal girdisidir, hook'ların ve izinlerin gördüğü backfill edilmiş sürüm değil. Bu, konuşma kaydının tutarlılığını korur — konuşmaya kaydedilen araç çağrısı, modelin ürettiğiyle tam olarak eşleşir.
6. Aşama: Araç Sonrası Hook'lar (Post-Tool Hooks)
Yürütmeden sonra, araç sonrası hook'lar tetiklenir. Bunlar, MCP aracı çıktısını değiştirebilir, ek bağlam sağlayabilir veya konuşmanın devam etmesini engelleyebilir. Ayrıca, yalnızca hatalarda tetiklenen ayrı bir PostToolUseFailure hook'u vardır ve harici sistemlere hataları günlüğe kaydetme veya düzeltme önerme şansı verir.
7. Aşama: Sonuç Eşlemesi (Result Mapping)
Her araç, çıktısını Anthropic API'sinin ToolResultBlockParam formatına dönüştürmek için mapToolResultToToolResultBlockParam() işlevini uygular — bu, bir tool_use_id başvurusu ve dize veya yapılandırılmış içerik içeren bir tool_result bloğudur.
Sonuç bir boyut eşiğini aşarsa, sessionDir/tool-results/{toolUseId}.txt yolunda diske kaydedilir ve bunun yerine API'ye bir dosya başvurusu ile bir önizleme gönderilir. Bu, büyük çıktıların (10.000 satırlık bir dosya okuması, ayrıntılı bir komut çıktısı) konuşma bağlamını şişirmesini önler.
Concurrency Scheduler
Model, tek bir mesajda birden çok araç çağrısı yaydığında, hepsi aynı anda çalışmaz. Bir zamanlayıcı, bunları eşzamanlılık güvenliğine göre gruplara ayırır.
Algoritma basittir. Araç çağrılarını sırayla yürütün. Her biri için isConcurrencySafe(input)'u kontrol edin. Güvenliyse ve önceki grup da güvenliyse, gruba ekleyin. Aksi takdirde, yeni bir grup başlatın.
1// toolOrchestration.ts'den basitleştirilmiştir2for (const toolUse of toolUseMessages) {3 const isSafe = tool.isConcurrencySafe(parsedInput)4 if (isSafe && lastBatch.isConcurrencySafe) {5 lastBatch.blocks.push(toolUse) // Eşzamanlı gruba birleştir6 } else {7 batches.push({ isConcurrencySafe: isSafe, blocks: [toolUse] })8 }9}
Güvenli gruplar eşzamanlı olarak çalışır (limit 10'a kadar, CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY ile yapılandırılabilir). Güvenli olmayan gruplar sırayla, her seferinde bir araç olacak şekilde çalışır. Context modifier'lar yalnızca gruplar arasında uygulanır, grup içinde uygulanmaz.
Pratikte bu, "bu 5 dosyayı oku" gibi bir mesajın bir eşzamanlı grup ürettiği, "bu dosyayı oku, sonra düzenle" gibi bir mesajın ise iki sıralı grup ürettiği anlamına gelir. Model, tek bir turda her iki deseni de tetikleyebilir — ardışık salt okunur çağrılar gruplanır ve ilk yazma işlemi grubu bozar.
Streaming Executor
İkinci bir yürütme yolu vardır: StreamingToolExecutor. Akış etkinleştirildiğinde, araçlar model yanıtını üretmeye devam ederken yürütülmeye başlar. Akıştaki her tool_use bloğu tamamlandığında, tam yanıt beklenmek yerine hemen yürütme kuyruğuna alınır.
Streaming executor, aynı eşzamanlılık kurallarını kullanır ancak bir davranış ekler: Bash hata yayılımı (Bash error cascading). Bir Bash komutu başarısız olurken kardeş araçlar paralel olarak çalışıyorsa, executor tüm kardeşleri iptal eder. Gerekçe, başarısız bir Bash komutunun muhtemelen diğer araçların üzerinde çalıştığı bağlamı geçersiz kılmasıdır — bunlara devam etmek zaman kaybına neden olur ve kafa karıştırıcı hatalara yol açabilir.
1if (isErrorResult && tool.block.name === BASH_TOOL_NAME) {2 this.hasErrored = true3 this.siblingAbortController.abort('sibling_error')4}
Çalışılmış Bir Örnek
Bunu somutlaştırmak için, modelin bir dosyayı okumaya karar verdiğinde neler olduğunu izleyelim. Model şunu yayar:
1{2 "type": "tool_use",3 "id": "toolu_01XYZ",4 "name": "read",5 "input": { "file_path": "/src/index.ts" }6}
Çıkarma: query.ts bunu asistan mesaj içeriğinden filtreler.
- Araç arama: findToolByName(tools, "read"), FileReadTool'u bulur.
- Giriş doğrulaması: Zod, { file_path: "/src/index.ts" }'yi z.object({ file_path: z.string(), offset: z.number().optional(), limit: z.number().optional(), pages: z.string().optional() }) ile ayrıştırır. Geçer.
- Araç öncesi hook'lar: Kullanıcı tarafından yapılandırılmış tüm hook'lar tetiklenir. Hiçbiri girdiyi değiştirmez.
- İzin kontrolü: FileReadTool'un checkPermissions() metodu checkReadPermissionForTool()'u çağırır. Okuma araçlarına çoğu izin modunda genellikle izin verilir.
- Yürütme: FileReadTool.call() dosyayı okur, satır numaralandırması uygular (cat -n formatı), PDF'leri/görselleri/notebook'ları özel durumlar olarak ele alır.
- Sonuç eşlemesi: Dosya içeriği, "toolu_01XYZ"'ye başvuran bir tool_result bloğu haline gelir.
- Dönüş: Sonuç, bir kullanıcı mesajı olarak konuşmaya eklenir ve bir sonraki API çağrısında gönderilir.
FileReadTool, isConcurrencySafe: () => true ve isReadOnly: () => true bildirdiğinden, model aynı mesajda beş okuma çağrısı yaymış olsaydı, beşi de paralel olarak yürütülürdü.
Özet
Araç sistemi, Claude Code'un yürütme omurgasıdır. Modelin niyetini — yapılandırılmış tool_use blokları olarak ifade edilen — alır ve her adımda doğrulama, izinler ve eşzamanlılık kontrolü ile makinenizde gerçek eylemlere dönüştürür.
Tasarım katmanlıdır: muhafazakâr bir buildTool() fabrikası güvenli varsayılanlar sağlar, özellik bayraklarıyla yönetilen bir kayıt defteri nelerin mevcut olduğunu kontrol eder, yedi aşamalı bir dispatch pipeline her çağrıyı doğrular ve izinlerini kontrol eder ve bir concurrency scheduler doğruluğu korurken paralelliği en üst düzeye çıkarır. Streaming executor, model düşünmeyi bitirmeden önce araçların çalışmaya başlamasıyla üstüne bir performans optimizasyonu ekler.
Bellek sistemiyle (5 yol, bir markdown dosyaları dizini ve prompt mühendisliği) karşılaştırıldığında, araç sistemi gerçek bir çalışma zamanıdır. Bir dosya dolabı ile bir işletim sistemi arasındaki fark gibidir.
İlginç Olan Noktalar
Model Zamanlayıcı Olarak
Concurrency scheduler tepkiseldir — modelin yaydığı her şeyi gruplar. Ancak modelin kendisi gerçek zamanlayıcıdır. Sistem prompt'u, "tüm bağımsız araç çağrılarını paralel yap" ve "bağımlı komutları zincirlemek için && ile tek bir Bash çağrısı kullan" talimatını verir. Çalışma zamanı buna güvenir. Model beş okuma ve ardından bir yazma yayarsa, zamanlayıcı okumaları paralel hale getirir ve yazmayı sıraya koyar. Ancak bu sıraya model karar vermiştir. Zamanlayıcı, modelin planını uygulamaktadır, kendi planını yapmamaktadır.
Varsayılan Olarak Güvenli Tarafa Kapanma (Fail-Closed by Default)
En tutarlı tasarım ilkesi: her şey varsayılan olarak güvenli tarafa kapanır. Bilinmeyen araç? Hata. Geçersiz girdi? Hata. Eşzamanlılık bildirimi yok? Sıralı yürütme. İzin bildirimi yok? Kullanıcıya sor. Özellik bayrağı yok? Araç mevcut değil. Bu, birincil kullanıcısı araç adlarını hayal edebilecek veya girdileri yanlış biçimlendirebilecek bir AI modeli olan bir sistem için alışılmadık bir durumdur. Sistem, modelin hatalarını barındırmak için değil, onları sınırlamak için tasarlanmıştır.
Bir Genişletme Noktası Olarak Hook'lar
Hook sistemi — araç öncesi, araç sonrası ve başarısızlık sonrası — birincil genişletme noktasıdır. Kuruluşların politikaları (ön hook'lardaki reddetme kuralları) bu şekilde uygulaması, günlükleme sistemlerinin araç kullanımını (sonraki hook'lar) bu şekilde yakalaması ve CI/CD pipeline'larının (başarısızlık hook'ları) bu şekilde entegre olmasıdır. Önemli olarak, hook'lar yalnızca kısıtlamaları sıkılaştırabilir, gevşetemez. Bir hook, ayarların izin verdiği bir aracı reddedebilir, ancak ayarların reddettiği bir araca izin veremez.
43 Araç, 1 Interface
Belki de en çarpıcı olan şey tekdüzeliktir. Bir bash komutu, bir web_fetch, bir alt-ajan oluşturma, bir cron işi oluşturma ve bir push bildirimi, aynı 30 metodlu interface'i uygular, aynı yedi aşamalı pipeline'dan geçer ve aynı izin sistemine saygı gösterir. Dağıtıcıda özel durum yoktur. Karmaşıklık, bireysel araç uygulamalarında ve izin kurallarındadır, yönlendirmede değil.
