LLM Digest
Subscribe

Agent Know-How

Agent engineering · know-how

Version pinning, compatibility ranges, and staged upgrades

🛠️ Solution·active·11 entries·18 sources·updated 2026-10-06

Treat the model, agent SDK, framework, and serving runtime as version-controlled dependencies, not a rolling stream: pin exact versions, declare the compatibility range you support, heed deprecation warnings, and promote upgrades through a staged, tested path instead of tracking latest. It doesn't stop the substrate from changing; it stops the change reaching production unnoticed.

Latest updates
  1. Drift packages agent-behavior versioning as a dedicated open-source tool
  2. Four more "bundled CLI only" SDK releases forward CLI changes in four days
  3. SDK 0.2.127 fixes background tasks silently bypassing PreToolUse hooks
  4. SDK 0.2.126 adds terminal_reason and typed model_usage on a patch bump
  5. Codex 0.144.6 quietly corrected bundled models' context windows to 272,000 tokens
State of the art

The levers exist, but defaults still favor latest. Pinning is a discipline you impose, not one you inherit.

Pins have to reach the whole chain. The clearest lesson comes from agent SDKs that vendor an executable. Claude Agent SDK releases often list only "updated bundled CLI", yet the forwarded CLI can carry permission-check fixes, and one patch release fixed background tasks silently skipping PreToolUse hooks. Codex showed the same on another vendor's stack, correcting bundled models' context windows inside a release billed as an instructions refresh. A lockfile that pins the SDK alone cannot tell a cosmetic bump from a security-relevant one.

Compatibility signals are arriving. LangGraph's CLI accepts declared API version ranges, and Claude Code warns when a requested model is deprecated or auto-updated. Both turn a silent substrate change into something CI or an operator can act on.

Upgrade tooling is the newer front. Vulnerability checks on resolved versions (deptrust) make a pin safe, not just consistent. Google Cloud cut a model migration from months to hours by replacing a rigid conversion script with an adaptive agent graded by autoraters. Dedicated behavior-versioning tools such as Drift are appearing but unproven.

The open problem is reading the changelog chain. Nothing yet surfaces, automatically, which transitive bump changed behavior or security posture; teams still diff release notes by hand.

Trade-offs

Pinning trades freshness and security currency for stability. Stay pinned too long and you miss fixes, including permission and hook-bypass fixes shipped as "internal" bumps, and you build up a painful catch-up upgrade. Pin too loosely and a patch bump reintroduces a regression. Ranges and staged rollouts add CI and release machinery. A pin is only as good as the regression suite that gates the unpin: without agent benchmarks you have frozen the version but not proven the behavior.

Why it matters for platform engineers

This is ordinary dependency hygiene applied to a substrate most teams treat as a service. The deliverable is a lockfile that reaches all the way down (model id, SDK, bundled CLI, framework, serving runtime) plus a staged upgrade path gated by regression evals, so a model deprecation or framework patch is a planned migration, not a surprise in prod. It pairs with model drift: pinning decides when drift reaches you instead of letting it arrive on the vendor's schedule.

Developments 11

Pinning the whole chain, not just the SDK

6 entries · latest Aug 14, 2026

Agent SDK patch releases routinely forward bundled CLI and model-metadata changes, including permission fixes, so a pin must reach SDK, bundled CLI, and model to mean anything.

·5 sources

Four more "bundled CLI only" SDK releases forward CLI changes in four days

claude-agent-sdk 0.2.135, 0.2.136, 0.2.138, and 0.2.139 each list only a bundled CLI update, to 2.1.227, 2.1.228, 2.1.232, and 2.1.233. The forwarded CLIs are not cosmetic: 2.1.233, for example, closes a path-validation bypass for Windows paths using the NT \??\ device prefix.

A version-only SDK pin cannot tell "safe to skip" from "actually changed". Read the bundled CLI's changelog on every SDK bump, or pin the CLI explicitly.

·1 source

SDK 0.2.127 fixes background tasks silently bypassing PreToolUse hooks

Before claude-agent-sdk 0.2.127, query() closed stdin on the first result frame even while background tasks were running. Their SDK-MCP tool calls failed with "Stream closed" and silently bypassed PreToolUse hooks. The release fixes that and bumps the bundled CLI to 2.1.219.

A pin held one version too early keeps a real defect, here one that skips your own guard hooks. "Patch" does not mean "safe to skip".

·1 source

SDK 0.2.126 adds terminal_reason and typed model_usage on a patch bump

claude-agent-sdk 0.2.126 added real API surface on a patch release: ResultMessage.terminal_reason reports why the query loop ended (completed, max_turns, aborted_tools, and others), and model_usage is now typed, with canonicalModel and provider fields for stable model identity across aliases. It also bumped the bundled CLI to 2.1.218.

Integrations that pin the SDK have to decide when to adopt behavior that exists only past an exact patch version.

Show 3 earlier entries

·3 sources

A "bundled CLI update" SDK release carried a batch of permission-check fixes

claude-agent-sdk 0.2.122's only listed change is a bundled CLI bump to 2.1.214. That CLI fixed several permission checks: a Windows PowerShell 5.1 bypass, Bash redirect forms that now fail closed, commands over 10,000 characters that now always prompt, and dir/** allow rules that auto-approved nested writes. SDK 0.2.125 again forwarded only a CLI bump, to 2.1.217.

A lockfile that pins only the SDK version silently accepts, or silently misses, security-relevant behavior changes. Chain-deep pinning is a standing requirement every release repeats, not a one-off fix.

Compatibility ranges and deprecation signals

2 entries · latest Jun 21, 2026

Frameworks now let you declare supported API version ranges, and agent CLIs warn when a requested model is deprecated or auto-updated, turning silent substrate changes into checkable signals.

·1 source

Claude Code now warns when the requested model is deprecated or auto-updated

Claude Code v2.1.183 added a warning when the requested model is deprecated or automatically updated to a newer one. It prints on stderr in print mode (-p) and also covers models set in agent frontmatter.

A model swapped out underneath a running agent becomes a visible signal an operator can schedule a migration from, instead of an unexplained behavior change. Headless jobs should capture stderr to see it.

Tooling for safe pins and tractable upgrades

3 entries · latest Aug 16, 2026

Vulnerability checks on agent-chosen versions, agentic model-migration pipelines graded by autoraters, and early behavior-versioning tools make pins safer and upgrades cheaper.

·1 source

Google Cloud cut foundation model upgrades from months to hours with an adaptive agent

Google Cloud's Applied ML team found that converting hand-built migration guidelines into a fixed conversion script gave quick wins but was too rigid for varied data formats and edge cases. They replaced it with an agent that analyzes each project's data, adapts its own prompts, and is graded by model-based autoraters instead of manual review. A video-translation migration went from months to hours.

Staying pinned only works if the eventual upgrade is tractable. This applies regression-gated discipline to the migration itself. It is a vendor case study built on Google's own agent platform.

·1 source

deptrust checks the package versions an agent picks against vulnerability databases

deptrust is a CLI and MCP server that checks package versions for known vulnerabilities across npm, PyPI, crates.io, Go modules, RubyGems, Maven, GitHub Actions, and other ecosystems, calling public registry and OSV APIs directly with no hosted service. Its author built it because coding agents kept suggesting vulnerable versions.

A pin, or an upgrade an agent proposes, can be validated as safe, not just consistent.

Evidence · 18 sources
All sources behind this page