# Upgrade Plugin Claude Code: Version Pinning dan Rollback

> Upgrade plugin tidak merusak build. Ia mengubah cara agent berperilaku, diam-diam, di tengah sprint. Cara pin versi, mendeteksi pergeseran, dan rollback.

URL: https://www.matthewswong.com/id/blog/claude-code-plugin-rollback-version-pinning/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-09-10
- Updated: 2026-09-10
- Category: DevOps

> **Key takeaway:** Upgrade plugin Claude Code jarang merusak build; yang berubah adalah cara agent berperilaku. Pin versi yang persis, jadikan eval run dan diff claude plugin details sebagai gate setiap upgrade, dan simpan changelog efek perilaku, karena tidak ada command downgrade yang bisa Anda andalkan.

Minggu ketika sebuah upgrade plugin masuk adalah minggu ketika tidak ada yang menyalahkan plugin itu. Auto-update jalan di background beberapa menit setelah tiap session dimulai, versi di disk bergeser, tidak ada error, dan satu-satunya tanda yang terlihat hanyalah ajakan menjalankan reload-plugins. Tiga hari kemudian keluhannya adalah agent terasa lebih buruk minggu ini, bukan bahwa ada yang rusak.

Tulisan ini soal failure mode yang khas ketika Anda mengirimkan instruksi sebagai dependency, dan cara membuatnya bisa ditangani: mengapa pin versi yang persis adalah default dan bukan paranoia, cara mengetahui bahwa sebuah marketplace menggeser tag di bawah Anda, cara mengubah perilaku berubah menjadi angka, dan cara rollback sebuah plugin ketika CLI-nya tidak punya command downgrade. Semua command di sini dicek terhadap Claude Code 2.1.259 dan dokumentasi plugin.

## Upgrade tanpa satu pun pesan error

Plugin adalah bundle berversi berisi skills, subagents, hooks, definisi MCP server dan instruksi, jadi muatannya adalah perilaku, bukan kode yang dikompilasi build Anda. Ketika upgrade library rusak, ada yang throw dan stack trace menyebut nama library itu. Ketika upgrade plugin rusak, agent tetap jalan dan diam-diam bekerja dengan cara lain, sehingga laporannya datang sebagai suasana hati, bukan sebagai bug.

| Kata tim Anda | Yang sebenarnya berubah | Di mana itu terlihat |
| --- | --- | --- |
| Checklist migration kami berhenti dipakai | Description sebuah skill diperketat dan tidak lagi cocok dengan cara orang menuliskan permintaannya | Tidak di mana pun. Skill itu memang tidak pernah fire |
| Hari ini setiap edit terasa lambat | Ada hook PostToolUse baru yang menjalankan formatter atas file itu pada setiap write | Wall-clock time per turn, dan debug log |
| Test runner yang dipilih selalu salah | Satu kalimat di file instruksi ditulis ulang, sehingga default yang lain yang menang | Transcript, tetapi hanya kalau Anda sudah mencurigai plugin |
| Sebuah tool call gagal karena namanya | Satu MCP server di dalam bundle mengganti nama tool-nya | Transcript, langsung. Ini yang paling mudah |

Dua mekanisme membuat penelusurannya sulit. Claude Code memeriksa update marketplace dan plugin setelah session Anda mulai, dengan jeda acak sampai sepuluh menit, jadi versi saat Anda membuka session belum tentu versi saat Anda menutupnya, dan notifikasi yang Anda terima adalah ajakan reload, bukan ringkasan apa yang berubah. Lalu plugin yang update di tengah session membiarkan hooks, monitors, MCP server dan LSP server menunjuk path versi sebelumnya sampai Anda reload, jadi sebagian siang itu separuh plugin lama dan separuh baru.

## Default-nya bukan sebuah versi

Claude Code memakai versi plugin sebagai cache key yang menentukan ada tidaknya update, dan untuk semua source type kecuali command versi itu diambil dari yang pertama terisi di antara lima sumber: field version di plugin.json, lalu version di entry marketplace, lalu git commit SHA dari source untuk github, url, git-subdir dan source berpath relatif, lalu digest SHA-256 sebuah archive source yang dipotong dua belas karakter, dan terakhir unknown untuk npm source atau direktori lokal di luar git repository.

Anak tangga ketiga itulah yang mengejutkan banyak orang. Kalau publisher tidak mendeklarasikan field version di mana pun, commit SHA yang menjadi versinya, jadi setiap commit yang mereka push ke ref yang Anda ikuti adalah rilis untuk Anda. Dokumentasinya justru menyarankan pola itu untuk plugin internal yang sedang aktif dikembangkan, dan itu wajar bagi penulisnya tetapi buruk bagi tim berisi dua belas orang, karena penulisnya yang lalu menentukan ritme update Anda. Baca entry marketplace-nya sebelum install: plugin tanpa version yang dideklarasikan tidak punya rilis yang bisa Anda sebut namanya di sebuah incident review.

## Auto-update adalah keputusan yang mungkin belum Anda buat

Default-nya tidak simetris, dan itu perlu diketahui sebelum Anda menganggap ada yang sudah beku. Marketplace resmi dan sebagian besar marketplace resmi Anthropic lain punya auto-update aktif secara default; marketplace pihak ketiga dan marketplace pengembangan lokal justru nonaktif secara default. Jadi katalog yang paling sedikit Anda periksa adalah yang paling diam, dan plugin yang paling Anda percayai adalah yang bergerak tanpa bertanya. Tidak ada default yang salah di sini, tetapi hanya satu yang cocok dengan apa yang tim Anda kira sedang terjadi.

Mematikan auto-update tidak sama dengan pinning. Yang berhenti adalah refresh di background, sedangkan install atau update yang Anda jalankan dengan menyebut nama marketplace tetap melakukan refresh marketplace itu lebih dulu, bahkan dengan auto-update mati dan DISABLE_AUTOUPDATER terpasang. Satu-satunya pin yang benar-benar tidak bergeser adalah sha pada sebuah plugin source di dalam katalog yang Anda kendalikan. Marketplace source menerima ref tanpa sha; plugin source menerima keduanya, dan ketika keduanya diisi, sha yang menang dan Claude Code langsung checkout commit itu.

> Pin lalu lupa adalah bentuk gangguan tersendiri. Plugin yang dibekukan di satu commit tidak akan pernah menerima perbaikan upstream untuk hook yang menggantung di repository besar, dan Anda menemukannya kembali berbulan-bulan kemudian tanpa ingat kenapa pin itu ada. Tulis alasan dan tanggal reviewnya di commit yang sama dengan pin-nya, atau Anda hanya menukar upgrade yang mengejutkan dengan kegagalan upgrade yang mengejutkan.

## Mengikuti sebuah ref bukan berarti mengikuti sebuah versi

Anda bisa menambahkan marketplace pada sebuah branch atau tag dengan menempelkan ref, dan itu terbaca seperti pin. Padahal bukan. Marketplace yang ditambahkan dengan ref berupa branch atau tag akan update ke commit terbaru dari ref itu, bukan ke default branch repository-nya, jadi publisher yang menghapus lalu membuat ulang v2.3.0 di commit yang lebih baru, hal yang wajar dilakukan tim kecil, menggeser Anda pada refresh berikutnya tanpa sepatah kata. Mengikuti sebuah branch adalah pengaturan yang sama tanpa kepura-puraan: Anda punya nama, bukan versi.

Deteksinya hanya dua command dan tempatnya di repository Anda, bukan di ingatan seseorang. Listing marketplace memberi Anda path clone lokalnya, dan git di path itu memberi Anda commit yang sebenarnya di-checkout. Commit kedua snapshot itu dan biarkan CI mendiff keduanya setiap run, karena tag yang bergeser muncul sebagai SHA yang berubah di sebelah version string yang tidak berubah, dan pasangan itu satu-satunya tanda yang tidak bisa Anda lihat dengan cara lain.

*Baca tag-nya dari atas ke bawah. Band yang error adalah yang Anda perbaiki dalam satu jam; band paling bawah adalah yang dirasakan tim selama seminggu tanpa pernah bisa disebut namanya.*

> Simpan snapshot claude plugin list --json ke dalam repository pada setiap rilis. Isinya version, scope, installPath, installedAt dan lastUpdated untuk tiap plugin, jadi pertanyaan kapan ini berubah berhenti menjadi percakapan dan menjadi git log.

## Ubah rasanya lebih buruk menjadi sebuah angka

Lakukan pemeriksaan yang murah dulu, karena hanya butuh beberapa detik dan tidak memanggil model. claude plugin details mencetak inventaris komponen plugin itu yang dikelompokkan sebagai Skills, Agents, Hooks, MCP server dan LSP server, beserta angka always-on untuk token yang ditambahkan teks listing-nya ke setiap session. Ambil snapshot sebelum update dan sesudahnya, lalu diff keduanya. Komponen yang muncul dan angka always-on yang bertambah keduanya adalah perubahan pada default agent, bukan pada pilihannya.

Lalu pemeriksaan yang terukur. claude plugin eval menerima plugin yang sudah terinstall lewat id yang menggabungkan namanya dengan nama marketplace-nya, tidak hanya sebuah path, dan ketika sebuah plugin ter-resolve ia menambahkan baseline arm tanpa plugin secara default, sehingga run-nya melaporkan delta bukan skor tunggal. Flag threshold keluar dengan exit 1 kalau ada case yang di bawahnya, dan itu seluruh perbedaan antara sebuah gate dan sebuah laporan. Batas jujurnya: eval suite hanya mengukur apa yang Anda tulis case-nya, jadi case yang paling layak ditulis lebih dulu adalah prompt yang benar-benar diketik tim Anda.

## Tidak ada command downgrade

CLI plugin punya details, disable, enable, eval, init, install, list, marketplace, prune, tag, uninstall, update dan validate. Tidak ada downgrade, dan install tidak menerima argumen versi, jadi install yang lama bukan sesuatu yang bisa Anda ketik. Karena itu rollback disusun dari empat langkah, dan hanya langkah ketiga yang tahan lama.

Memastikan rollback berhasil butuh lebih dari sebuah version string. Versi di claude plugin list memberi tahu apa yang terinstall di disk; reload-plugins yang memindahkan hooks, MCP server dan LSP server dari path versi yang lain; monitors baru ikut setelah session direstart penuh; dan eval case yang tadi turun itulah yang memberi tahu bahwa perilakunya kembali, bukan hanya byte-nya. Periksa dalam urutan itu, karena satu langkah bisa lulus sementara langkah berikutnya masih gagal.

*Panel tengah adalah yang paling sering dilewati, dan di situlah rollback biasanya melenceng: version string yang berubah belum jadi bukti sebelum hooks dan monitors ikut berpindah.*

## Simpan changelog efek perilaku

Semantic versioning mencatat maksud publisher-nya. Changelog Anda mencatat pengalaman tim Anda, dan keduanya dokumen yang berbeda: rilis patch yang menulis ulang satu instruksi adalah kenaikan sepele di hulu dan satu hari kerja penuh kebingungan di sini. Satu entry per upgrade yang Anda terima, lima isian, disimpan di repository tepat di sebelah pin-nya.

1. Kedua version string dan kedua commit SHA, karena yang baru saja tidak memberi tahu apa pun kepada orang berikutnya.
2. Prompt yang perilakunya berubah, dikutip sebagaimana seseorang benar-benar mengetiknya, bukan diparafrase.
3. Delta token always-on dari diff details itu, dan komponen apa pun yang muncul atau hilang.
4. Eval case yang bergeser, dengan skornya sebelum dan sesudah, atau catatan bahwa tidak ada case yang menutupinya, yang justru merupakan temuannya.
5. Apa yang mengakhirinya: sebuah pin, perbaikan di upstream, atau keputusan menerimanya, bertanggal, dengan tanggal review kalau Anda memasang pin.

Hasilnya terasa pada insiden kedua. Yang pertama memakan tiga hari untuk tidak tahu harus melihat ke mana. Dengan file ini yang kedua memakan satu siang, karena seseorang melakukan grep atas nama skill-nya dan menemukan entry yang menyebut bahwa description ini diperketat di 2.4.0 dan berhenti fire pada susunan kata yang dipakai tim ini.

Perlakukan plugin sebagai dependency instruksi, bukan dependency kode, dan praktiknya menyusul sendiri: pin sebuah commit yang persis di katalog yang Anda kendalikan, jadikan diff details dan eval run sebagai gate setiap upgrade, simpan snapshot apa yang terinstall ke dalam repository agar tag yang bergeser jadi terlihat, dan catat efek perilakunya alih-alih nomor versinya. Upgrade yang tidak mengubah apa pun yang bisa Anda lihat justru yang paling layak diberi catatan.

## Sumber dan bacaan lanjutan

- Dokumentasi Claude Code, Plugins reference: version management, plugin cache dan CLI plugin
- Dokumentasi Claude Code, Discover and install plugins: default auto-update per marketplace
- Dokumentasi Claude Code, Create and distribute a plugin marketplace: pinning ref dan sha pada plugin source
- Dokumentasi Claude Code, Settings reference: extraKnownMarketplaces dan field autoUpdate-nya
- Dokumentasi Claude Code, Create plugins: pengujian dengan plugin-dir dan cara ia menimpa plugin terinstall

## Source links

- https://code.claude.com/docs/en/plugins-reference
- https://code.claude.com/docs/en/discover-plugins
- https://code.claude.com/docs/en/plugin-marketplaces
- https://code.claude.com/docs/en/settings-reference
- https://code.claude.com/docs/en/plugins

## FAQ

### Bisakah saya menginstall versi tertentu dari plugin Claude Code?

Tidak secara langsung. Command claude plugin install tidak menerima argumen versi, jadi versi yang Anda dapat adalah apa pun yang di-resolve katalog marketplace saat itu. Untuk mengendalikan versinya Anda harus mengendalikan katalognya: tambahkan sha pada source plugin itu di marketplace.json milik Anda sendiri agar terpaku pada satu commit yang persis.

### Bagaimana cara rollback upgrade plugin Claude Code?

Tidak ada command downgrade, jadi rollback harus disusun sendiri. Disable plugin itu untuk menghentikan perilakunya, jalankan ulang dengan --plugin-dir yang menunjuk direktori versi sebelumnya di plugin cache agar hari itu bisa diselesaikan, lalu geser sha di katalog Anda kembali ke commit terakhir yang sudah Anda evaluasi dan jalankan claude plugin update. Pastikan lewat claude plugin list dan sebuah reload.

### Apakah plugin Claude Code update secara otomatis?

Tergantung marketplace-nya. Marketplace resmi Anthropic punya auto-update aktif secara default, sedangkan marketplace pihak ketiga dan marketplace pengembangan lokal nonaktif secara default. Ketika aktif, Claude Code memeriksa update setelah session Anda mulai dengan jeda acak sampai sepuluh menit, lalu meminta Anda reload kalau ada yang berubah.

### Apa yang terjadi kalau sebuah plugin sama sekali tidak mendeklarasikan versi?

Untuk source berbasis git, commit SHA yang ter-resolve menjadi versinya. Artinya setiap commit yang publisher push ke ref yang Anda ikuti terhitung sebagai rilis baru bagi Anda, dan update datang setiap kali commit itu berubah. Ini default yang wajar untuk plugin internal yang sedang aktif dikembangkan dan buruk untuk apa pun yang diandalkan sebuah tim.

### Bagaimana saya tahu sebuah upgrade plugin mengubah perilaku agent?

Pakai dua pemeriksaan. Diff claude plugin details sebelum dan sesudah update untuk melihat komponen yang muncul atau hilang dan pergeseran biaya token always-on. Lalu jalankan claude plugin eval terhadap id plugin yang terinstall dengan sebuah threshold, yang menambahkan baseline arm tanpa plugin dan keluar dengan exit 1 saat ada case di bawah batas yang Anda tetapkan.

---

- HTML version: https://www.matthewswong.com/id/blog/claude-code-plugin-rollback-version-pinning/
- English: https://www.matthewswong.com/en/blog/claude-code-plugin-rollback-version-pinning/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json