DEV Community

Cover image for Claude Code 2.1.323 pins plugins to version ranges: what the engines field enforces and 6 things to check
Piekwerk
Piekwerk

Posted on

Claude Code 2.1.323 pins plugins to version ranges: what the engines field enforces and 6 things to check

Anthropic shipped Claude Code 2.1.323 on November 12. By one third-party count it bundles 294 changes, and 20 of them are breaking changes or deprecations (DevelopersIO counted them). The headline everyone will quote is Code Mode, where Claude writes JavaScript to call its tools. If you maintain plugins, marketplaces, or permission rules, the quieter items matter more. I read the full changelog end to end and checked the doc pages it points at. Here is what actually changes for your config.

Plugins now carry a version range

The changelog adds engines["claude-code"] to plugin.json. The stated behavior: plugins outside their declared Claude Code version range are not installed, not updated, and not loaded, and install plus update pick the newest plugin version that fits.

This is npm's package.json engines field, applied to agent tooling. If your plugin's hooks lean on CLI internals (hook event names, tool schemas, the permission check flow), you can now declare the range you actually tested, and Claude Code enforces it instead of letting your plugin load into a CLI that silently broke it.

The shape, per the field name in the changelog:

{
  "name": "my-team-plugin",
  "version": "1.4.0",
  "engines": {
    "claude-code": ">=2.1.323 <2.2.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

One honest caveat: that range syntax is my illustration, modeled on npm. The plugin manifest reference does not document the field yet. I fetched that page today (November 13) and it contains zero mentions of engines. The changelog line is the entire public spec right now, so verify the accepted syntax there before you publish a marketplace entry.

Code Mode is opt-in, and its doc page 404s

Code Mode lets Claude write JavaScript to compose its tool calls instead of emitting them one at a time. It is experimental and opt-in, and the changelog says you can turn it off for an organization.

The changelog links a doc page for turning it on and off. That page returned a 404 when I checked it today. If your org policy is "no undocumented experimental modes", there is no public doc to point at yet. The better reason to wait: how Code Mode interacts with permission rules is not written down anywhere. When tool calls get composed inside generated JavaScript, what your allow rules actually gate can change shape. Keep it off until the docs exist, then re-read your rules.

Permission defaults moved, in the right direction

Three changes tighten what your permission files mean.

First, startup now warns about Bash allow rules with a * inside a variable's value, such as Bash(PORT=* npm run dev). A wildcard in the middle of an allow rule is a common accidental over-grant, and now the CLI names it at startup.

Second, "don't ask again" got a memory limit. An allow rule that looks like it holds a secret, or that would be saved into a git-tracked settings.local.json, now lasts for the session only and is not written to disk. This descends directly from the Apiiro census that found 1,122 public repos holding real secrets inside tracked settings files. I covered that census and the remediation angle last week; this change closes the write path that produced those files.

Third, hook answers no longer outrank failing checks. If a permission check errors after a PreToolUse hook returned "allow", Claude Code now decides the call as if no hook had answered. A PermissionRequest hook that rewrote input which then fails its check gets asked again, or refused where nobody can answer. Belt and suspenders now both have to pass.

Git hooks lost their tokens

Claude Code's internal ripgrep and most of its internal git commands now run without most of its sign-in tokens and API keys. A credential helper or hook running under one of those git commands no longer finds them.

That is a real security win: a hook planted under a git command cannot exfiltrate tokens it cannot read. The flip side is silent breakage. If your setup relied on a git credential helper seeing Claude Code's tokens, it stopped working without an error that names the cause. Audit any custom git hooks that run inside sessions.

Unknown models now assume 1M context

The context window assumed for a model ID Claude Code does not recognize went from 200K to 1M. On vendors' models with a smaller real window, a full session can now fail every turn until /clear, because the CLI keeps feeding context the model cannot hold. CLAUDE_CODE_DISABLE_1M_CONTEXT=1 restores the 200K assumption.

This lands hardest behind LLM gateways, where model IDs are custom or proxied and therefore unrecognized. Same audience affected by the 2.1.319 auto-mode change, which also hit gateway users hardest. Set the env var before you need it, not after a week of mystery failures.

MCP sign-ins and supply-chain checks

Two smaller tightenings.

The MCP server sign-in flow now asks you to confirm before finishing, even in bypass and auto modes. Where nobody can be asked (headless dontAsk runs), complete it manually with /mcp. Project-level .mcp.json approvals must also match the server's exact name now, and an approval written in a different spelling asks again. Check your .mcp.json spellings if a server that used to be pre-approved starts prompting.

Plugin and marketplace installs also fail when a git submodule is not on the commit its repository records. That is a supply-chain gate, and a welcome one after malware posed as a Claude Code plugin in a third-party marketplace last month.

Startup fails closed on bad sandbox settings

A --settings file that is not valid JSON and contains a sandbox key now stops startup outright, even when the key turns the sandbox off. The failure default is the safe one: an unparseable sandbox config used to be a gamble, now it is a halt. Claude Code tightened failure defaults before, in 2.1.317, and the direction is consistent.

What to check this week

grep -rn 'Bash(' .claude/settings.json .claude/settings.local.json | grep '\*'
Enter fullscreen mode Exit fullscreen mode
  1. Run that grep and rewrite any wildcard-in-variable allow rules it finds.
  2. If you maintain a plugin, decide your engines["claude-code"] range now, and run claude plugin validate --strict, which now type-checks TypeScript hooks and fails on findings under --strict.
  3. Re-test any git credential helper that depended on Claude Code's tokens.
  4. Behind a gateway with custom model IDs, set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 if the real window is under 1M.
  5. Verify .mcp.json server names match installed servers exactly.
  6. Leave Code Mode off until its doc page resolves.

The through-line of this release: the config surface is becoming enforced instead of advisory. Version ranges get enforced at install time, secret-looking rules stop persisting, hooks stop overriding failing checks, and unparseable sandbox settings stop sessions. If you treat agent config as infrastructure, this release does part of your governance work for you.

Top comments (0)