[FEATURE] Plugin Version Compatibility: Add 'engines' field to plugin.json

Preflight Checklist

• [x] I have searched for existing issues and this feature has not been requested
• [x] This is a single feature request (not multiple features)
• [x] I have provided concrete use cases and examples

Problem Statement

Summary

Plugin authors currently have no way to specify minimum Claude Code version requirements in plugin.json. When plugins use features from newer Claude Code versions (e.g., agent_type from 2.1.2, context: fork from 2.1.0), users on older versions experience silent failures or unexpected behavior.

Motivation

Current Limitation:

1. No engines field exists in the plugin.json schema (verified in official docs)
2. Plugin authors must document version requirements in description text (workaround)
3. Users have no way to know if a plugin is compatible before installing
4. Claude Code doesn't warn users when installing incompatible plugins

Real-World Example:
The ACE plugin v5.4.11 introduced agent_type capture which requires Claude Code 2.1.2+:

• SessionStart hook reads agent_type from stdin JSON (new in 2.1.2)
• On older versions, this field doesn't exist → silent fallback to "main"
• Users on 2.1.0 or 2.1.1 get degraded functionality without warning

Current Workaround (suboptimal):

{
  "name": "ace",
  "version": "5.4.12",
  "description": "... Requires: Claude Code >= 2.1.2, ace-cli >= 3.4.1."
}

This is not machine-readable and doesn't prevent installation on incompatible versions.

Related Issues

• #9444 - Plugin Dependencies (discusses dependency management but not version constraints)
• #16705 - Version comparison issues in update command

Proposed Solution

1. Add engines field to plugin.json schema

Following npm's package.json pattern:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My plugin description",
  "engines": {
    "claude-code": ">=2.1.2"
  }
}

2. Version constraint syntax

Support semver range syntax (like npm):

• ">=2.1.2" - Minimum version
• "^2.1.0" - Compatible with 2.x.x (>=2.1.0 <3.0.0)
• "~2.1.0" - Approximately equivalent (~2.1.0 >=2.1.0 <2.2.0)
• "2.1.x" - Any 2.1.x version
• ">=2.0.0 <3.0.0" - Range

3. Installation behavior

# User on Claude Code 2.0.50 tries to install plugin requiring 2.1.2+
/plugin install ace@claude-marketplace

⚠️ Warning: Plugin 'ace' requires Claude Code >= 2.1.2
   Your version: 2.0.50
   
   Options:
   1. Update Claude Code: claude update
   2. Install anyway (may not work correctly): /plugin install ace --force

4. Plugin listing behavior

/plugin browse

Available Plugins:
  ✅ plugin-a (v1.0.0) - Compatible
  ⚠️ plugin-b (v2.0.0) - Requires Claude Code >= 2.1.2
  ❌ plugin-c (v3.0.0) - Requires Claude Code >= 3.0.0

Benefits

For Plugin Authors

• ✅ Declare version requirements formally (machine-readable)
• ✅ Prevent support issues from version mismatches
• ✅ Clear communication of compatibility

For Users

• ✅ Know compatibility before installing
• ✅ Get clear warnings about version requirements
• ✅ Avoid silent failures from incompatible plugins

For Marketplace

• ✅ Filter plugins by compatibility
• ✅ Show compatibility badges
• ✅ Better user experience

Design Considerations

Version Resolution

• Use semver library for version comparison (already used in Claude Code per #16705)
• Parse engines.claude-code field during plugin installation
• Compare against current Claude Code version

Backwards Compatibility

• Field is optional (existing plugins without engines work as before)
• Only enforced during installation, not at runtime
• --force flag allows override for testing

Performance

• Version check is a simple string comparison
• No network requests needed
• Negligible impact on installation time

Examples from Other Systems

npm (Node.js)

{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

VSCode Extensions

{
  "engines": {
    "vscode": "^1.80.0"
  }
}

Gradle Plugins

gradlePlugin {
    plugins {
        myPlugin {
            compatibleGradleVersions = ">=7.0"
        }
    }
}

Additional Context

Priority: Medium - Improves plugin ecosystem reliability

Feature Category: Plugin System / Developer Experience

Use Case Example:

1. Plugin author releases v2.0.0 using new hook feature from Claude Code 2.2.0
2. User on Claude Code 2.1.0 installs plugin
3. Current: Silent failure, confusing errors
4. With this feature: Clear warning, user knows to update

References:

• Plugin Reference Docs - Current schema (no engines field)
• npm engines field - Prior art