Rem biaya Claude Code ternyata bukan di limit turn
Kupikir --max-turns cukup buat nahan biaya delegasi. Ternyata flag itu cuma ngitung putaran; yang benar-benar nahan dolar adalah --max-budget-usd.
Ringkasan
Penulis ngira --max-turns bisa nahan biaya Claude Code, ternyata cuma nahan jumlah putaran, bukan uang. Tesnya, tugas selesai di satu turn senilai 0.045 dolar tanpa nyentuh cap dua, sedangkan --max-budget-usd beneran menghentikan proses begitu biaya lewat batas. Jadi buat nahan tagihan, pasang cap dalam dolar, limit turn cukup buat nahan loop muter-muter.
Jam tujuh malam saya buka dokumen acceptance di repo, bagian hasil tes cap delegasi. Baris yang ditunggu ternyata cuma dua angka: tugas sepele yang saya lempar ke Claude Code dengan --max-turns 2 selesai sukses di satu turn, biaya sekitar 0.045 dolar, tanpa satu pun error. Berarti rem yang saya pasang selama ini nggak pernah masuk ke jalur rem sama sekali.
Bulan-bulan sebelumnya, dokumen kerja project ini nempel satu aturan: semua pemanggilan Claude Code wajib bawa --max-turns. Logikanya masuk akal di kepala saya. Kalo jumlah putarannya dibatasi, kerusakan juga kecil. Anggap aja tiap turn itu satu permintaan dengan harga yang kira-kira sama semua. Ternyata asumsi harga-per-turn yang seragam itulah titik lemahnya.
Angka dari tes malam itu
Tesnya sengaja dibikin sepele. Print mode, tugas cuma disuruh balas singkat, cap dua turn. Hasilnya num_turns satu, sukses, dan cap dua nggak pernah tersentuh karena tugasnya selesai duluan. Bayaran tetap keluar: sekitar 0.045 dolar untuk satu turn itu.
Lalu kontrol keduanya dijalankan. Kali ini tanpa limit turn, tapi dengan --max-budget-usd 0.01. Baru di sini remnya terasa. Proses berhenti paksa dengan error_max_budget_usd, exit code 1, biaya berhenti di 0.0403 dolar, masih di tengah turn pertama. Angka cap-nya tertembus sedikit sebelum pemeriksaan mengejar, tapi keberhentiannya nyata dan dipicu uang, bukan hitungan putaran.
Dua flag, dua ukuran yang beda
Dokumen CLI resmi Claude Code mendeskripsikan --max-turns sebagai pembatas jumlah agentic turn di print mode, dan error baru muncul ketika batasnya tercapai [1]. Jadi flag ini ngukur progres pekerjaan, bukan uang. Selama tugas selesai di bawah cap, dia cuma penumpang di baris perintah.
Bandingkan dengan --max-budget-usd: didefinisikan sebagai jumlah dolar maksimal buat panggilan API sebelum berhenti, khusus print mode juga [1]. Halaman biaya menambahkan detail yang bikin flag ini kredibel: angka yang dibandingkan ke cap adalah angka yang sama dengan biaya sesi di status line [2]. Satu sumber kebenaran, satu titik potong.
Historinya juga terbaca di changelog resmi. Flag ini masuk lewat jalur SDK [3], lalu perilaku penegakannya terus dirapikan; di catatan perbaikan ada baris soal subagent background yang dulu lolos dari cap dan sekarang ikut dihentikan [3]. Untuk fitur penghentian subagent itu sendiri, halaman CLI menyebut butuh Claude Code versi 2.1.217 ke atas [1]. Di mesin saya yang berjalan versi 2.1.269, flag ini emang udah ada di --help, dengan catatan cuma bekerja di print mode.
Detail yang emang belum dijelasin dokumen: seberapa rapat pemeriksaan anggaran itu dijalankan, sekali per panggilan API atau lebih sering lagi. Yang bisa saya pastikan dari tes sendiri, pemeriksaannya cukup granular sampai menghentikan proses di tengah turn yang sedang jalan. Buat kebutuhan rem, presisi segitu udah lebih dari cukup.
Tiap delegasi bawa angka dolar
Konsekuensinya langsung nempel di dokumen kerja saya: pemanggilan delegasi kini wajib bawa --max-budget-usd. Limit turn boleh tetap dipasang, tapi fungsinya nahan loop kusut yang muter-muter tanpa selesai, bukan nahan biaya. Konteks biayanya sendiri bukan hal sepele: halaman resmi Claude Code mencatat rata-rata biaya di deployment enterprise sekitar 13 dolar per developer per hari aktif, dengan rentang 150 sampai 250 dolar per bulan [2].
Sementara itu, --max-turns tetap punya tempat. Di loop otomatis yang jalan tanpa pengawasan, cap turn berguna buat memotong sesi yang muter di tempat tanpa selesai-selesai; dokumen resmi nyebut error muncul begitu batasnya tercapai [1]. Anggap dia saklar darurat buat perilaku, bukan buat tagihan. Dan sesi yang kena error_max_turns nggak pernah saya ulang mentah-mentah: cek dulu apa yang udah sempat dia tulis ke disk, baru putuskan lanjut atau bongkar.
Pola yang sama berlaku buat siapa saja yang menjalankan agen otomatis semalaman. Jumlah turn nggak pernah jadi satuan uang; satu turn bisa murah karena konteksnya pendek, bisa juga mahal karena model mengerjakan banyak hal dalam satu giliran. Kalo yang mau dibatasi biaya, pasang cap dalam dolar. Satu angka dolar lebih jujur daripada hitungan putaran yang nggak pernah disentuh.