[KongchangAI]
· 3 min read· 1,541 words

Claude Code v2.1.323 Released: Experimental Code Mode Goes Live, Plugin Version Constraints Strengthened

Claude Code v2.1.323 Released: Experimental Code Mode Goes Live, Plugin Version Constraints Strengthened

Claude Code v2.1.323 introduces experimental Code Mode and fixes numerous permission, session, and login issues.

Claude Code v2.1.323 is primarily a reinforcement release. The most anticipated new feature is the experimentally gated Code Mode, which lets Claude orchestrate tool calls by writing JavaScript code rather than calling tools one at a time directly, with official documentation and an organization-level disable switch. The plugin ecosystem gains substantive enhancements: plugin.json now supports engines["claude-code"] version range declarations, and out-of-range plugins are not installed, updated, or loaded; claude plugin validate now type-checks TypeScript hooks modules, with --strict failing on warnings. The densest area of fixes is permissions and sandboxing, covering wildcard rules that skip prompts, wrapper commands like sudo/env bypassing deny rules, sandbox escapes, and auto mode falling back to Manual. Session and login fixes address message appending on resume, duplicate /compact summaries, background session identity mismatches, and token expiration retries.

Claude Code v2.1.323 Released

Claude Code has received the v2.1.323 update, a release that strikes a careful balance between feature expansion and stability fixes. The most notable addition is the experimental Code Mode feature, alongside a series of improvements to the plugin ecosystem and permission system. For users who rely on Claude Code for daily development, this update resolves a large number of edge cases that previously affected the experience.

Code Mode: Letting Claude Call Tools via JavaScript

v2.1.323 introduces Code Mode, an experimental option that must be manually enabled. Once enabled, Claude writes JavaScript code to invoke its tools rather than using the traditional direct-call approach. The official documentation is available at code.claude.com/docs/en/code-mode, where users can find instructions for enabling it. Organization administrators also have the option to disable the feature at the organization level.

This shift in design philosophy is worth noting. Having the model orchestrate tool calls by writing code theoretically enables handling more complex tool-chain combinations and makes logic easier to reuse. However, as an experimental feature, its stability and applicable scenarios still require further validation by the community.

Tool Calling is the core mechanism through which large language models interact with the outside world: the model does not execute operations directly but instead outputs structured call requests (such as function name + parameters), which the host program parses and executes before passing results back to the model. The traditional approach has the model initiate calls one at a time, serially, with each step depending on the previous round's result—so complex tasks can easily generate many round trips. Code Mode's approach is to have the model generate an executable script that orchestrates multiple tool calls within a single script, thereby supporting loops, conditional branches, variable reuse, and intermediate result processing. This is similar to the "model as programmer" paradigm; the trade-off is the need for stricter sandbox isolation and code execution security boundaries—which is also why it is marked as experimental and can be disabled at the organization level.

Plugin System: Enhanced Version Constraints and Validation

The plugin ecosystem received several substantive improvements in this update. A new engines["claude-code"] field has been added to plugin.json for declaring the range of Claude Code versions the plugin supports. Plugins outside this range will not be installed, updated, or loaded, and the install and update flows will automatically select the latest version that meets the version requirements.

The claude plugin validate command has also been extended: it now performs type checking on the plugin's TypeScript hooks modules, presenting each finding as a warning, and with the --strict flag it will fail directly when issues are found. Additionally, the command validates the $nouns added, retained, or replaced by the mod's engine.create hook. These changes mean plugin developers can catch potential issues earlier, before publishing.

A new unsetOptionCount field has been added to the installation result JSON, indicating how many userConfig options remain unset. For cases where a plugin was enabled but silently failed to take effect, /plugin and claude plugin list now provide specific reasons.

Semantic versioning (SemVer) range declarations are foundational infrastructure for plugin ecosystem governance. The engines field borrows from the npm package.json convention, allowing plugins to declare the host version range they are compatible with (e.g., >=2.1.0 <3.0.0). The host validates at three stages—installation, update, and loading—which prevents plugins from silently failing on newer versions of Claude Code due to API changes, and also prevents older hosts from loading plugins that depend on new features. The accompanying claude plugin validate serves as a lint gate for plugins: type checking catches interface mismatches in hooks modules before publishing, while --strict upgrades warnings to errors, making it suitable for CI pipelines. Such mechanisms are typically a necessary addition when a plugin ecosystem grows from dozens to thousands of plugins.

Permissions and Sandbox: Patching Numerous Edge-Case Vulnerabilities

The permission system is the area with the densest concentration of fixes in this update. Several scenarios that could previously cause permission prompts to be skipped or misjudged have been corrected:

  • Cases where variable values in Bash allow rules contain * (e.g., Bash(PORT=* npm run dev)) now produce a warning at startup; the issue where rules with additional wildcards (e.g., Bash(ls*)) could skip permission prompts in some cases has been fixed; rules with named variables (e.g., Bash(NODE_ENV*)) now prompt correctly.
  • Bash deny and ask rules previously missed commands executed through wrappers such as sudo and env; this gap has been patched.
  • The issue where sandbox.excludedCommands allowed unnamed commands to escape the sandbox in some cases has been fixed.
  • --permission-mode auto or defaultMode: auto in settings, when auto mode is unavailable, could previously start in a more permissive mode; it now falls back to Manual mode, asking the user first.

The common thread across these fixes is that the reliability of permission boundaries under complex command combinations and special environments has been improved. For teams using Claude Code on sensitive projects, the value of such low-level patches often exceeds that of new features.

Command wrapper bypass is a classic challenge in command allowlist/denylist mechanisms. Programs like sudo, env, nice, and xargs merely forward arguments—the actual operation is performed by the subcommand that follows. If permission rules only match the program name at the start of the command line, then sudo rm -rf or env FOO=1 curl ... could bypass deny rules targeting rm or curl. Related issues include variable assignment prefixes (PORT=3000 npm run dev) and the greediness of wildcard matching—Bash(ls*) matches ls -la but may also match commands beyond what was intended. Modern permission systems therefore need to lexically parse commands, strip wrappers and environment variable prefixes before matching, and adopt more conservative default policies for rules containing wildcards.

Sessions and Login: Reducing Unexpected Interruptions and Identity Mismatches

Several frustrating issues in session management have been fixed. When resuming a session, new messages are no longer appended to unrestored old interrupted messages; the issue where /compact executed repeatedly on a message Claude had not yet replied to caused content to be summarized away has been resolved.

Login-state-related fixes are similarly dense. When a background session's named Anthropic profile is missing, changed, or overwritten, it could previously send conversations under a different identity; it now stops and provides a prompt. The issue where sessions using API keys, auth tokens, or workload identity switched to other login methods in the background has also been fixed. Cases where MCP tool calls terminated due to login server errors (such as TOKEN_EXPIRED) now correctly prompt the user to log in again.

For macOS users, the issue where "Not logged in" appeared immediately after a successful /login when the keychain responded slowly has been fixed. In Claude Desktop, cases where an organization gateway returning 403 for an expired token caused a turn to fail now request a new token and retry.

Credential refresh and 403 retry involve the lifecycle management of OAuth-style tokens. Access tokens have short validity periods, and after expiration the server typically returns 401 or 403; the client should recognize such errors, use the refresh token to obtain a new token, and replay the request, rather than surfacing the failure directly to the user. The TOKEN_EXPIRED mentioned above is a custom error code from the MCP server, which the client needs to recognize semantically and trigger a re-login flow. Another pitfall is "identity mismatch": when multiple Anthropic profiles or multiple login methods (API key, auth token, workload identity) exist on the same machine, a background session holding a stale identity snapshot may send requests under the wrong identity. The correct approach is to invalidate the session and explicitly notify the user when identity changes, rather than silently continuing.

Other Notable Improvements

  • Long-task heartbeat: In claude -p and SDK sessions, when hooks run for an extended time, a progress heartbeat is sent every 30 seconds to prevent hosts like Claude Desktop from mistakenly treating the turn as hung and terminating it.
  • Artifact upload: Added support for the .docx format.
  • New environment variables: CLAUDE_CODE_RESUME_HINT_COMMAND allows programs that launch Claude Code to customize the resume command shown in the exit hint; CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES (available since 2.1.318) can be set to 1 to disable sub-agent progress summaries and their write requests.
  • Performance fixes: Memory spikes on the next prompt after Claude modifies very large files, memory overflow in Edit and Bash on /proc files, and Edit hangs on named pipes have all been fixed.
  • Windows compatibility: The issue where plugin and marketplace installation failed when cloned file paths reached 260 characters has been resolved.

Summary

v2.1.323 is primarily a "reinforcement" release. Code Mode offers a new experimental direction for future tool-calling paradigms, but what truly affects the daily development experience is the large number of fixes across three main threads: permission validation, session resumption, and login state. The enhancements to plugin version constraints and validation capabilities indicate that Claude Code is preparing for a larger-scale plugin ecosystem.

For plugin developers, it is recommended to add the engines["claude-code"] declaration to plugin.json as soon as possible and run claude plugin validate --strict to check hooks modules. For regular users, if you have previously encountered abnormal permission prompts or session identity mismatches, it is worth re-verifying those scenarios after upgrading.

#Claude Code#v2.1.323#Code Mode#plugin system#permission sandbox#session management#login state
Share:

Related articles