Claude Code 2.1.289: 27 Changes, Permission-Rule Fixes and Mods Stability

The official Claude Code changelog lists 27 changes for version 2.1.289. There is no headline feature this time. The release is mostly three things: stability fixes for mods and plugins, fixes for several permission-rule gaps, and a new agent.spawn for teammates. This post sorts the official list by impact and says who should update first. The changelog does not state a release date for this version.

The short version

• If you run mods or plugins: many fixes stop a broken pane from ending the whole session. Worth updating.
• If you rely on managed settings or deny/ask rules: five fixes close cases where a rule was bypassed or did not apply. Update first.
• If you build multi-agent setups: agent.spawn is new, plus idle and waiting states for agents.

Check your version with claude --version. Mods need v2.1.287 or later; background in our earlier mods guide.

1. Permission and security rules (5 items)

1. A deny or ask rule on a nested part of a compound shell command did not hold over a user-installed mod's approval on managed machines.
2. Read deny rules did not apply to files @-mentioned, changed, or selected in the IDE through a symlink.
3. A user-installed plugin could rewrite the descriptions of an organization-managed MCP server's sign-in tools.
4. Bash deny and ask rules missed a command behind an environment-variable prefix with an expanded value.
5. Under sandbox auto-allow, a Bash deny or ask rule was skipped when a bare variable assignment came before the command.

The common thread: the rule existed but did not catch a particular spelling or path. If your team uses deny rules to restrict reads or commands, update and re-check your rules.

2. New: agent.spawn and agent states

The changelog says agent.spawn is added for teammates, plugin hook events now use one agent id, and $.agent.list() gains idle and waiting states. That is the only new capability in this release. The changelog gives no further detail; check the mods docs and reference pages for usage.

3. Mods and plugin stability (the largest group)

Most of the list is about one failing mod or plugin no longer taking down the session:

• Installed mods not loading in the first session after an upgrade.
• Supervised and background sessions ending when a plugin's on-screen handler threw asynchronously.
• Sessions ending with an interface error when a plugin region with no height kept growing.
• Sessions ending with "unrecoverable interface error" when a value a mod's ui.render hook wrote made a row throw.
• A freeze or forced quit at launch when a plugin drew a Box with a border style the terminal does not know.
• A mod's Client failing while drawn taking down everything the mod drew around it, and a Client region staying failed for the whole session after the terminal threw while drawing it.
• A mod's band that failed to draw briefly telling cards under it to step aside.
• Display fixes: right-aligned content drawing under the close mark, plugin panes drawing nothing for links with a localhost address, an @ in the path, an uppercase host or a file: path, text with a tab, stray escape or C1 control drawing over rows below, and a plugin's rows above the prompt showing a stale row while the Background tasks dialog was open.
• Improvements: large files open faster in a plugin code pane; a mod author sees a clearer line when a band or pane fails to draw; a failed plugin component with no message no longer shows just Error or nothing.

4. Plugin commands and validation (3 items)

• plugin list, plugin eval and plugin update no longer show a stale copy of a plugin installed from a local-folder marketplace.
• claude plugin validate no longer skips the plugin when the folder also holds a marketplace manifest.
• claude plugin validate no longer fails an Anthropic marketplace's own plugin or lists a clean plugin.json as an error.

5. Terminal and other (3 items)

• The terminal no longer freezes on short code blocks with many unclosed <script> tags or deeply nested ${ substitutions.
• Published artifact pages no longer freeze or crash the reader's browser tab on the same kind of code block.
• [VS Code] A 2.1.288 change to claude auth status that may have made sign-outs more frequent was reverted.

What it means for you

If you only use Claude Code to write code and have no mods installed, most fixes do not touch you, but the five permission-rule fixes and the terminal-freeze fix are still worth having. If you install or write mods, open /plugin after updating and check that your mods load.

FAQ

What changed in Claude Code 2.1.289?

The official changelog lists 27 changes: new agent.spawn and agent idle/waiting states, five fixes for permission rules that were bypassed or did not apply, and mostly stability fixes for mods and plugins.

Is there a new feature in 2.1.289?

One: agent.spawn for teammates, with a single agent id across plugin hook events and idle and waiting states in $.agent.list().

Are there security fixes in this release?

Yes. Five permission-rule fixes: nested shell-command deny/ask rules, Read deny rules for symlinked files, organization-managed MCP server descriptions, and Bash rule gaps around environment-variable prefixes.

How do I check my version?

Run claude --version in your shell.

Further reading

• ClaudeMods (claudemods.dev): a collection of Claude Code mods

Sources

• Claude Code official CHANGELOG (GitHub)
• Claude Code docs: Mods overview

TWD billing · Taiwan invoices · leading AI models · OpenAI-compatible API