# Plugin System Complete Analysis
The plugin system allows third-party developers to add new capabilities to Claude Code β from GitHub integrations to database clients, from code formatters to custom Skills ("Skills" are specific capabilities provided by plugins β for example, a GitHub plugin can provide "create PR", "view Issue" and other skills, which Claude automatically invokes at the right moment). It distributes through a Marketplace, uses signature verification to ensure supply-chain security, homoglyph detection to prevent spoofing attacks, and a three-tier permission model to protect users. This chapter analyzes the plugin installation pipeline, triple security defense lines, automatic update strategy, dependency resolution, and the underlying relationship with the MCP protocol.
> **Source locations**: `src/utils/plugins/` (44 files), `src/services/plugins/` (3 files), `src/commands/plugin/` (17 UI files)
> π‘ **Plain English**: The plugin system is like commercial street management in a city β every shop (plugin) must pass an audit (signature verification) before opening, equivalent to a business license review; it must declare its purpose during renovation (permission application); it can only operate within its own storefront (MCP sandbox isolation); and there are mechanisms to prevent counterfeit stores from impersonating brands (homoglyph detection). The city management bureau (Marketplace) conducts regular inspections (automatic updates), and if it finds a violating shop, it forces a shutdown (automatic uninstallation after delisting).
> π **Industry Context**: The plugin/extension ecosystem is one of the core competitive advantages of developer tools, and security strategies vary significantly across platforms. **VS Code**'s Extension Marketplace is the most mature reference β it has publisher verification and malicious-extension detection, but historically lacked fine-grained permission control (only introducing Workspace Trust in recent years). **Chrome extensions**' Manifest V3 introduced a dual-layer model of permission declaration + user authorization, similar to Claude Code's three-tier permission control. **npm** ecosystem supply-chain attacks (typosquatting, dependency confusion) are the real-world threats that Claude Code's homoglyph detection guards against β multiple npm package spoofing incidents in 2024 proved the necessity of such protection. **GitHub Copilot Extensions** launched in 2024, following the GitHub App authorization model with security hosted by the GitHub platform β this represents a completely different philosophy from Claude Code's "client-side autonomous security". **Cursor** has not yet established an independent plugin market, instead relying on the VS Code extension ecosystem (because it is itself a fork of VS Code) β this is the difference between "borrowing an ecosystem" versus "building an ecosystem". As a CLI tool, Claude Code cannot reuse VS Code extensions and is forced to build its own ecosystem; this constraint is the true starting point for understanding its plugin system design.
---
> **Boundary with Chapter 03**: This chapter focuses on the security layer, distribution mechanism, and update strategy that the plugin system adds on top of MCP. For the MCP protocol's transport, configuration, and connection management, please refer to Chapter 03. The intersection of the two chapters lies in: when a plugin registers as an MCP server, it uses `config scope: plugin` β this is a dedicated scope marker that allows the system to apply differentiated trust policies to MCP servers originating from plugins.
---
## Code Landing Table
> π‘ **How to use this table**: You don't need to memorize all the files. This table serves as a "map" β when the text below mentions a feature, you can come back here to check "which file implements this feature". On first reading you can skip it and go straight to the main text.
| File | Size | Core Responsibility |
|------|------|----------|
| `pluginLoader.ts` | 110KB | **Core loader** β loads plugins from cache/disk, parses manifest, cache management, versioned paths |
| `marketplaceManager.ts` | 93KB | **Marketplace manager** β market registration/refresh/query, Git clone/pull, plugin search |
| `schemas.ts` | 59KB | **Types and validation** β Zod schema definitions, homoglyph detection (`isBlockedOfficialName`), official name protection |
| `mcpbHandler.ts` | 31KB | **MCPB handler** β download/unzip/MCP config conversion for DXT-format plugins |
| `installedPluginsManager.ts` | 41KB | **Installation registry** β read/write installed_plugins.json, version tracking, pending-update detection |
| `validatePlugin.ts` | 28KB | **Manifest validator** β strict Zod schema validation for plugin.json/marketplace.json, path-traversal detection |
| `pluginInstallationHelpers.ts` | 21KB | **Installation core** β `installResolvedPlugin` main flow, dependency closure resolution, policy guards, cache materialization |
| `mcpPluginIntegration.ts` | 20KB | **MCP bridge** β loading/configuration/user-config variable substitution for plugin MCP servers |
| `marketplaceHelpers.ts` | 18KB | **Enterprise policy** β source allowlist/blocklist, host/path pattern matching, policy priority chain |
| `pluginAutoupdate.ts` | 9.5KB | **Auto-update** β background marketplace refresh + plugin updates, callback notifications |
| `dependencyResolver.ts` | 12KB | **Dependency resolution** β DFS closure computation, cycle detection, cross-marketplace security blocking, load-time demotion |
| `pluginBlocklist.ts` | 4.4KB | **Delisting detection** β automatically uninstalls delisted plugins by comparing marketplace manifest |
| `pluginPolicy.ts` | 0.8KB | **Organization policy** β `isPluginBlockedByPolicy` single-point check |
| `pluginVersioning.ts` | 5.3KB | **Version calculation** β manifest version > provided version > Git SHA > unknown priority chain |
| `pluginFlagging.ts` | 5.6KB | **Flag management** β records automatically uninstalled plugins, 48-hour expiration, user-visible notifications |
| `pluginIdentifier.ts` | 3.9KB | **ID parsing** β parsing/building `name@marketplace` format, scope mapping |
| `reconciler.ts` | 8.3KB | **Market reconciler** β diff + sync between settings declarations and known_marketplaces.json |
| `hintRecommendation.ts` | 5.4KB | **Install recommendation** β plugin recommendations triggered by `` in CLI tool stderr |
| `orphanedPluginFilter.ts` | 4.0KB | **Orphan filtering** β ripgrep exclusions for old plugin versions to prevent search result pollution |
| `officialMarketplace.ts` | 0.8KB | **Official constants** β GitHub source and display name for `anthropics/claude-plugins-official` |
**Service layer** (`src/services/plugins/`):
| File | Size | Core Responsibility |
|------|------|----------|
| `pluginOperations.ts` | 36KB | **Operation layer** β shared CLI and UI implementation for install/uninstall/enable/disable/update |
| `PluginInstallationManager.ts` | 6KB | **Installation manager** β managed-settings auto-installation entry point |
| `pluginCliCommands.ts` | 11KB | **CLI commands** β command-line parsing and execution for `claude plugin install/uninstall/list/update` |
> π‘ **Plain English**: The layered relationship of these files is like a building β `schemas.ts` is the foundation (defining all data structures), `pluginLoader.ts` is the elevator (responsible for moving plugins from disk to memory), `marketplaceManager.ts` is property management (responsible for all market CRUD operations), `pluginOperations.ts` is the front desk (all user install/uninstall requests go through here), and `pluginInstallationHelpers.ts` is the back kitchen (the core flow that actually does the work).
---
> **[Chart placeholder 3.5-A]**: Security architecture diagram β the complete trust chain from plugin publication to installation (Marketplace β signature verification β homoglyph detection β user confirmation β MCP connection)
---
## 1. The Relationship Between Plugins and MCP
A plugin is essentially an **MCP server with additional metadata and security layers** (if you are not yet familiar with MCP, you can briefly understand it as "the standard interface for AI to connect to external tools" β see Chapter 03 for details). When you install a plugin, what happens under the hood is a multi-step pipeline with security guards and dependency resolution.
### 1.1 Installation Pipeline Deep Dive
`installResolvedPlugin` in `pluginInstallationHelpers.ts` is the unified entry point for all installation paths (CLI, UI, hint recommendation):
```
/plugin install my-plugin@marketplace
β [1] Policy guard: isPluginBlockedByPolicy(pluginId) β organization blocklist check
β [2] Dependency closure resolution: resolveDependencyClosure() β DFS traversal (Depth-First Search β like walking along the branches of a tree all the way to the end before backtracking, checking each dependency one by one), detects cycles/cross-marketplace
β [3] Transitive dependency policy check: every dependency must also pass isPluginBlockedByPolicy
β [4] Write to settings: write the entire closure's enabledPlugins at once
β [5] Materialization loop: cacheAndRegisterPlugin() for each
β Download plugin source from Marketplace
β Signature verification (ensure not tampered)
β Homoglyph detection (ensure name is not a counterfeit)
β Version calculation (manifest > marketplace entry > Git SHA > unknown)
β Move to versioned cache path ~/.claude/plugins/cache////
β Optional: ZIP compressed cache (isPluginZipCacheEnabled)
β Write to installed_plugins.json (V1 and V2 formats)
β [6] Clear all caches: clearAllCaches()
β [7] Return result: success + dependency count suffix ("+ N dependencies")
```
### 1.2 Failure Path Analysis
The installation pipeline has **six explicit failure types**, each with structured error returns (`InstallCoreResult` union type):
| Failure Type | Trigger Condition | User-Facing Message |
|---------|---------|--------------|
| `blocked-by-policy` | Organization admin disabled the plugin in managed-settings.json | "Plugin X is blocked by your organization's policy" |
| `dependency-blocked-by-policy` | Root plugin itself not blocked, but one of its transitive dependencies is disabled by policy | "Cannot install X: dependency Y is blocked" |
| `resolution-failed: cycle` | Dependency chain has a cycle (AβBβCβA) | "Dependency cycle: A β B β C β A" |
| `resolution-failed: cross-marketplace` | Dependency comes from a different marketplace and is not in the allowlist | "Dependency X is in marketplace Y, which is not in the allowlist" |
| `resolution-failed: not-found` | Dependency cannot be found in any configured marketplace | "Dependency X not found. Is the Y marketplace added?" |
| `local-source-no-location` | Local-source plugin missing marketplace install location | "Cannot install local plugin without marketplace install location" |
| `settings-write-failed` | Settings file write failure (disk full / permission issue) | "Failed to update settings: ..." |
> π‘ **Plain English**: This is like an e-commerce return process with seven reason codes β "product is banned", "supplier is banned", "logistics circular delivery", "sourcing from black market", "supplier not found", "local store has no stocking address", "cash register broken". Each case has a corresponding handling strategy, rather than a vague "installation failed".
### 1.3 Types of Capabilities Provided by Plugins
Plugins provide not only MCP tools, but also:
- **Skills** (proactive triggering capabilities with `whenToUse` β see Section 4 for details)
- **Commands** (slash commands β loaded from Markdown files in the `commands/` directory)
- **Agents** (sub-agents β loaded from Markdown files in the `agents/` directory, supporting independent models/toolsets)
- **Hooks** (lifecycle hooks β declared in `hooks/hooks.json`, can intercept PreToolUse/PostToolUse and other events)
- **Resources** (MCP resources)
- **Channel servers** (message channels, such as Telegram integration β requires allowlist review)
- **Output styles** (output styles β custom formatting rules for Claude output)
## 2. Marketplace Security β Triple Defense
### 2.1 Signature Verification and Name Protection
> π **Course Connection**: Plugin signature verification is a direct application of the "digital signatures and PKI (Public Key Infrastructure)" topic in **computer networking/information security** courses. The publisher signs plugin content with a private key, and the client verifies with a public key β this is the same trust model as HTTPS certificate chains, Android APK signing, and Linux package manager (apt/yum) GPG signatures.
Every plugin on the Marketplace has a cryptographic signature. During installation, Claude Code verifies the signature to ensure:
- The plugin content matches what was published on the Marketplace
- No man-in-the-middle tampering occurred
- The plugin truly comes from the claimed publisher
**Key management model**: Claude Code's signature verification adopts a **Marketplace repository signing** model rather than an independent publisher certificate system. Specifically:
1. The **official Marketplace** is hosted on GitHub (`anthropics/claude-plugins-official`), and the Git repository's integrity itself is guaranteed by the GitHub platform
2. The "signature verification" at installation time is actually implemented via **Git commit SHA** β `calculatePluginVersion` in `pluginVersioning.ts` records the Git commit SHA (`getGitCommitSha`), and the post-installation version number is directly bound to a specific commit
3. On each update, the system compares the locally cached SHA with the latest marketplace SHA, and only triggers an update when they differ
This model is similar to Linux distribution package repository signing β **trust is placed in the repository itself** (the GitHub organization maintained by Anthropic), rather than independent certificates held by each plugin author. Compared to npm's Sigstore per-package signing scheme, this simplifies key management but also means the granularity of security guarantees is marketplace-level rather than plugin-level.
**Official name protection**: `validateOfficialNameSource` in `schemas.ts` implements name-to-source binding validation:
```typescript
// Reserved names can only come from the anthropics/ organization
const ALLOWED_OFFICIAL_MARKETPLACE_NAMES = new Set([
'claude-code-marketplace', 'claude-plugins-official',
'anthropic-marketplace', 'anthropic-plugins',
'agent-skills', 'life-sciences', 'knowledge-work-plugins',
])
// Spoofing detection regex: blocks "official-claude-*", "anthropic-marketplace-*" variants
const BLOCKED_OFFICIAL_NAME_PATTERN =
/(?:official[^a-z0-9]*(anthropic|claude)|...)/i
```
If a third party attempts to register a marketplace named `anthropic-marketplace-new`, `isBlockedOfficialName` will block it β unless the source actually comes from the `github.com/anthropics/` organization.
### 2.2 Homoglyph Protection
Plugin names undergo Unicode homoglyph detection β preventing attackers from registering visually similar but actually different names. For example:
- `github-tools` vs `githΓΌb-tools` (ΓΌ replacing u)
- `official-plugin` vs `ΠΎfficial-plugin` (Cyrillic ΠΎ replacing Latin o)
**Algorithm implementation**: Line 79 of `schemas.ts` defines the detection logic:
```typescript
// Only ASCII printable characters (U+0020 to U+007E) allowed
const NON_ASCII_PATTERN = /[^\u0020-\u007E]/
function isBlockedOfficialName(name: string): boolean {
// 1. Official names in the allowlist pass directly
if (ALLOWED_OFFICIAL_MARKETPLACE_NAMES.has(name.toLowerCase())) return false
// 2. Contains any non-ASCII character β block immediately
if (NON_ASCII_PATTERN.test(name)) return true
// 3. Matches spoofing pattern regex β block
return BLOCKED_OFFICIAL_NAME_PATTERN.test(name)
}
```
Claude Code adopts the **strictest allowlist approach** β rather than character-level mapping based on the Unicode Confusables database (like Chrome's ICU Confusable Detection), or whole-word mapping table comparison (like Firefox), it **directly prohibits all non-ASCII characters from appearing in marketplace names**.
**Trade-offs of this design decision**:
| Dimension | Claude Code Approach | Chrome ICU Approach | Firefox Whole-Word Mapping |
|------|----------------|----------------|----------------|
| Implementation complexity | Extremely low (one regex) | High (requires ICU library) | Medium (maintain mapping table) |
| False positive rate | **High** β Chinese/Japanese/Korean names all blocked | Low β only blocks mixed scripts | Low β precise mapping |
| False negative rate | Extremely low β all non-ASCII blocked | Medium β new confusable pairs may be missed | Medium β mapping table needs updates |
| Applicable scenario | Marketplace names (English-dominated) | Domains (need internationalization support) | Domains (need internationalization support) |
> π‘ **Plain English**: Chrome's homoglyph detection is like customs identity verification β checking passports character by character (Unicode mapping table), allowing citizens of all countries to enter but detecting fake documents. Claude Code's approach is more like "only English passports accepted" β crude and simple, absolutely no counterfeit goods get through, but legitimate non-English users are also blocked. This is reasonable for the currently English-dominated CLI plugin ecosystem, but if a Chinese developer community becomes active in the future, a more granular scheme would need to be introduced.
### 2.3 Allowlist Mechanism
Certain high-privilege features (such as Channel Permission Relay β allowing plugins to receive and process messages through channels like Telegram/Slack) require additional allowlist review.
**Complete implementation of `channelAllowlist.ts`**:
```typescript
// GrowthBook remote feature-flag-controlled allowlist
function getChannelAllowlist(): ChannelAllowlistEntry[] {
const raw = getFeatureValue_CACHED_MAY_BE_STALE('tengu_harbor_ledger', [])
const parsed = ChannelAllowlistSchema().safeParse(raw)
return parsed.success ? parsed.data : []
}
// Global channels switch (independent of allowlist)
function isChannelsEnabled(): boolean {
return getFeatureValue_CACHED_MAY_BE_STALE('tengu_harbor', false)
}
```
Key architectural decisions here:
1. **Remote control**: The allowlist is distributed via GrowthBook (Anthropic's feature-flag service), refreshed every 5 minutes. This means Anthropic can urgently revoke a plugin's channel permissions without shipping a new release
2. **Granularity is `{marketplace, plugin}` pairs**: Not individual MCP servers. Source comments explain why β "per-server gating was overengineering β a plugin that sprouts a malicious second server is already compromised"
3. **Fail-closed design**: If GrowthBook is unreachable, `getFeatureValue_CACHED_MAY_BE_STALE` returns the cached value; if never fetched, it returns defaults `[]` (empty allowlist) and `false` (channels disabled). This is the fail-closed principle in security design β when network is unreachable, deny everything rather than allow everything
4. **Developer bypass**: The `--dangerously-load-development-channels` flag can bypass allowlist checks, but the "dangerously" prefix in the name ensures developers know the risk
### 2.4 Enterprise Policy Layer (Fourth Line of Defense)
In addition to the triple defense of signature/homoglyph/allowlist, enterprise deployment scenarios also have the **policy layer in `marketplaceHelpers.ts`** β this can be seen as a fourth line of defense:
```typescript
// Policy priority: blocklist > allowlist > default allow
function isSourceAllowedByPolicy(source: MarketplaceSource): boolean {
// 1. Check blocklist first (blockedMarketplaces)
if (isSourceInBlocklist(source)) return false
// 2. Then check allowlist (strictKnownMarketplaces)
const allowlist = getStrictKnownMarketplaces()
if (allowlist === null) return true // unrestricted
// 3. Supports exact matching and pattern matching (hostPattern / pathPattern)
return allowlist.some(allowed => {
if (allowed.source === 'hostPattern')
return doesSourceMatchHostPattern(source, allowed)
if (allowed.source === 'pathPattern')
return doesSourceMatchPathPattern(source, allowed)
return areSourcesEqual(source, allowed)
})
}
```
Enterprise administrators can configure via `managed-settings.json`:
- `blockedMarketplaces`: blocklist, precisely blocking specific marketplace sources (including cross-format detection β Git URL format GitHub repos will also be matched against github-format blocklist entries)
- `strictKnownMarketplaces`: allowlist, only permitting listed sources. Supports `hostPattern` (regex domain matching) and `pathPattern` (regex local path matching), suitable for large organizations' self-hosted marketplaces
- `enabledPlugins: { "plugin@marketplace": false }`: individual plugin-level disable
## 3. Dependency Resolution
### 3.1 DFS Closure Computation
`dependencyResolver.ts` implements `apt`-style dependency resolution β dependencies are **existence guarantees** ("B's components must be available when A runs"), not a module graph:
```
Plugin A (dependencies: ["B"])
β DFS walk: A β B β B's dependencies...
β Already-enabled dependencies are skipped (avoid duplicate installation in settings)
β Cycle detection (stack.includes(id) β cycle error)
β Cross-marketplace blocking (dependencies from different marketplaces are prohibited by default)
β Return: installation closure [B, A] (topological order: dependencies first, root last)
```
**Cross-marketplace security blocking** is a key design β installing a plugin from a trusted marketplace should not silently pull dependencies from an untrusted marketplace. There are two escape hatches:
1. User manually pre-installs cross-marketplace dependencies (becoming `alreadyEnabled`, skipped by DFS)
2. The root marketplace's `allowCrossMarketplaceDependenciesOn` allowlist β **note only the root's allowlist takes effect**, there is no transitive trust
### 3.2 Load-Time Demotion
`verifyAndDemote` is a safety net at load time β if a plugin's dependencies are not enabled or do not exist, that plugin is **demoted** rather than crashing the entire system. This function uses a **fixed-point loop**:
```
Loop until no changes:
For each enabled plugin:
Check whether all its dependencies are in the enabled set
If not satisfied β remove from enabled (triggering a new round)
β Because removing A may cause B (which depends on A) to also be unsatisfied
```
This is similar to the operating system's `depmod` mechanism β after a kernel module is removed, modules depending on it are also cascaded unloaded.
## 4. Plugin and Skill Collaboration β From Passive Tools to Proactive Recommendations
### 4.1 Core Paradigm Shift
Plugins can register Skills β capabilities with a `whenToUse` description, allowing the AI to **proactively trigger** them rather than only responding to user slash commands. This means a Claude instance with the GitHub plugin installed:
- Not only responds to `/github create-pr` slash commands
- Also **proactively suggests** using this skill when it detects intent like "I want to create a PR"
This describes a paradigm shift from **passive tool invocation** to **proactive capability recommendation**. In LangChain/AutoGPT tool selection, the LLM typically routes based on tool descriptions (consuming tokens to evaluate all tools on every turn); Claude Code's `whenToUse` model **front-loads routing logic into the skill declaration** β each skill declares "when to use me", reducing the LLM's selection burden.
### 4.2 Command Loading Mechanism
`loadPluginCommands.ts` (30KB) is responsible for loading Skills and Commands from plugin directories. The loading flow:
1. **Directory scan**: traverse the plugin's `skills/` and `commands/` directories
2. **Frontmatter parsing**: extract `description`, `whenToUse`, `allowed-tools`, `shell` and other metadata from YAML frontmatter
3. **Namespacing**: command name format is `{pluginName}:{namespace}:{commandName}`, e.g. `github:pr:create`
4. **Variable substitution**: `substitutePluginVariables` and `substituteUserConfigInContent` handle `${{option_name}}` placeholders in plugin options
### 4.3 Agent Loading
`loadPluginAgents.ts` (12KB) supports plugins registering **sub-agents** β independent AI roles that can have their own system prompts, toolsets, and even different models. This allows a "database management" plugin to register a dedicated DBA Agent with read-only database query tools but no file-write capabilities.
### 4.4 Hooks Registration
`loadPluginHooks.ts` (10KB) allows plugins to intercept Claude Code lifecycle events. Schema validation for `hooks/hooks.json` is a **hard error** β unlike frontmatter parsing's "silent degradation", a malformed hooks.json causes the entire plugin to fail loading. This is because if a hook were silently ignored, security-critical interception logic could be bypassed.
### 4.5 Installation Recommendation (Hint System)
`hintRecommendation.ts` implements a clever **passive install recommendation** mechanism:
1. CLI tools (such as `aws`, `gh`) can output `` in stderr
2. Claude Code's Bash tool detects this tag and calls `maybeRecordPluginHint`
3. After a series of **synchronous** filters (session deduplication, user preference, already-installed check, policy check, official marketplace restriction, config growth ceiling of 100)
4. If it passes, asynchronously calls `resolvePluginHint` to fetch plugin info from marketplace cache
5. Finally displays an install recommendation dialog to the user
This **show-once** semantics is persisted via `GlobalConfig.claudeCodeHints.plugin[]` β regardless of whether the user chooses "Install" or "Skip", the same plugin will never be recommended again.
## 5. Automatic Updates and Supply-Chain Security
### 5.1 Update Strategy Overview
`pluginAutoupdate.ts` implements a complete background auto-update flow, running non-blocking on every Claude Code startup:
```
On startup: autoUpdateMarketplacesAndPluginsInBackground()
β [1] Check if auto-update is disabled (shouldSkipPluginAutoupdate)
β [2] Get list of marketplaces with autoUpdate enabled
β [3] Parallel refresh of these marketplaces (git pull / re-download)
β [4] Compare installed plugins with latest marketplace versions
β [5] Update changed plugins one by one (updatePluginOp)
β [6] Notify REPL to display "restart to take effect" prompt
```
### 5.2 Safety Guarantees for Updates
**Updates are non-inplace** β the new version is downloaded to a new versioned directory (`cache////`), while the old version is retained for 7 days via an `.orphaned_at` marker. This ensures:
1. **Concurrency safety**: other running Claude Code sessions still reference the old version directory and won't be interrupted by the update
2. **Rollback capability**: the old version remains on disk for 7 days (`getGlobExclusionsForPluginCache` in `orphanedPluginFilter.ts` ensures ripgrep searches won't hit these orphan directories)
3. **Atomicity**: `rename` operations guarantee atomic directory replacement; for the special case where marketplace name = plugin name (subdirectory conflict), a temporary directory is used as an intermediary
### 5.3 Automatic Uninstallation After Delisting
`pluginBlocklist.ts` implements **delisting detection and forced uninstallation** β if an installed plugin is removed from the marketplace (removed from the plugins array in marketplace.json), and the marketplace has `forceRemoveDeletedPlugins` enabled:
```typescript
function detectDelistedPlugins(installed, marketplace, marketplaceName) {
const marketplacePluginNames = new Set(marketplace.plugins.map(p => p.name))
// Find plugins belonging to this marketplace in the installed list but not in the latest manifest
for (const pluginId of Object.keys(installed.plugins)) {
if (!pluginId.endsWith(`@${marketplaceName}`)) continue
const pluginName = pluginId.slice(0, -suffix.length)
if (!marketplacePluginNames.has(pluginName)) {
delisted.push(pluginId)
}
}
}
```
Delisted plugins are automatically uninstalled from all user-controllable scopes (user/project/local), and recorded in `flagged-plugins.json`. Users will see a "Flagged" prompt in the `/plugins` interface, which automatically disappears after 48 hours.
> π‘ **Plain English**: This is like a mall conducting regular inspections β if a brand's authorization is revoked by headquarters (delisted from marketplace), the mall directly shuts down that counter (automatic uninstallation), and posts a notice on the bulletin board (flagged marker), which is taken down after a few days. Plugins in `managed` scope are not automatically uninstalled β that's the enterprise administrator's territory, and the admin must handle it themselves.
### 5.4 Auto-Update Policy
Not all marketplaces auto-update. The policy is determined by `isMarketplaceAutoUpdate`:
```typescript
function isMarketplaceAutoUpdate(name: string, entry: { autoUpdate?: boolean }) {
return entry.autoUpdate ??
(ALLOWED_OFFICIAL_MARKETPLACE_NAMES.has(name) &&
!NO_AUTO_UPDATE_OFFICIAL_MARKETPLACES.has(name))
}
```
- **Official marketplaces**: default autoUpdate = true (except `knowledge-work-plugins` is excluded)
- **Third-party marketplaces**: default autoUpdate = false, requires explicit user enablement
- **Settings declaration takes precedence**: user's `autoUpdate` setting in settings overrides all defaults
This means **the malicious update risk window differs**: official plugins go through Anthropic review, so automatic update risk is controllable; third-party plugins require the user to actively choose to accept automatic update risk.
## 6. createMovedToPluginCommand Migration Pattern
When functionality migrates from a built-in command to a plugin, the system uses a backward-compatible strategy. `createMovedToPluginCommand.ts` creates a **placeholder command**:
```typescript
createMovedToPluginCommand({
name: 'security-review', // Old command name
description: '...',
pluginName: 'security-review', // New plugin name
pluginCommand: 'review', // Command name in the plugin
getPromptWhileMarketplaceIsPrivate: ..., // Fallback logic when marketplace is not yet public
})
```
When a user types the old command name, internal users (`USER_TYPE === 'ant'`) receive guidance to install the plugin; external users execute the fallback logic provided by `getPromptWhileMarketplaceIsPrivate` (usually directly executing the old functional implementation). This ensures:
- Old users' muscle memory doesn't break
- The migration process is transparent and visible
- No need to maintain migrated functionality in built-in code
- There is a gradual canary strategy (internal migration first, external follow-up later)
Currently the `pr_comments` and `security-review` commands have already used this pattern.
## 7. pluginOnlyPolicy
`pluginPolicy.ts` is the most concise module in the entire policy subsystem (only 21 lines), implementing a critical enterprise security capability:
```typescript
function isPluginBlockedByPolicy(pluginId: string): boolean {
const policyEnabled = getSettingsForSource('policySettings')?.enabledPlugins
return policyEnabled?.[pluginId] === false
}
```
In enterprise deployment scenarios, administrators can lock down via `managed-settings.json`:
- `enabledPlugins: { "plugin@marketplace": false }` β prohibit specific plugins
- Combined with `strictKnownMarketplaces` β only allow marketplaces from reviewed sources
- Combined with `blockedMarketplaces` β blocklist specific sources
**Security boundary of pluginOnly policy**: It should be noted that even if pluginOnly policy is enabled to restrict users to only use reviewed plugins, the MCP servers inside those plugins can still initiate arbitrary network requests. pluginOnly prevents users from manually connecting to unreviewed MCP servers, but does not restrict the runtime behavior of installed plugins β this is the inherent boundary of the MCP process-isolation model (as opposed to a WASM sandbox).
## 8. Version Management and Cache Strategy
### 8.1 Version Calculation Priority
`pluginVersioning.ts` defines a **five-level priority chain** for version numbers:
```
1. version field in plugin.json β e.g. "1.2.3"
2. version in marketplace entry β e.g. "1.0.0"
3. Git commit SHA (pre-parsed / extracted from installPath) β e.g. "a1b2c3d4e5f6"
4. git-subdir special handling: SHA + path hash β e.g. "a1b2c3d4-8f9e0d1c"
5. 'unknown' (last resort)
```
The git-subdir special handling is worth noting β if a monorepo has two subdirectories each containing a plugin, their Git SHA is the same but the path differs. The path hash (first 8 chars of SHA256) prevents cache directory collisions.
### 8.2 Marketplace Reconciliation
`reconciler.ts` is responsible for keeping `known_marketplaces.json` (actual state) consistent with declarations in settings (desired state). This is a **declarative reconciliation** pattern β similar to Kubernetes' reconciliation loop:
- `diffMarketplaces()`: compares declarations with actual state, outputting missing / sourceChanged / upToDate
- `reconcileMarketplaces()`: executes diff results β install missing, update source-changed, skip up-to-date
- Operations are **idempotent** and **additive only**
## 9. Design Trade-offs and Evaluation
**Strengths**:
1. **Structured error handling**: The `InstallCoreResult` union type covers all known failure modes, and each failure has actionable error information β a best practice in security-critical systems
2. **Non-inplace update + orphan retention**: The 7-day orphan retention period solves concurrent session issues, and ripgrep exclusions in `orphanedPluginFilter.ts` ensure searches won't be polluted
3. **Dependency security isolation**: Cross-marketplace dependencies are prohibited by default, transitive dependency policy checks, and load-time fixed-point demotion β three layers of protection ensure "installing A won't silently introduce untrusted B"
4. **Enterprise policy priority chain** (blocklist > allowlist > default) covers different security needs from startups to large organizations
5. **Hint recommendation show-once semantics** and config growth ceiling (100) prevent recommendation fatigue and unbounded growth
**Costs**:
1. **Plugin ecosystem security depends on Marketplace review quality** β signature verification granularity is marketplace-level (Git repository integrity), rather than per-plugin independent signatures
2. **The ASCII-only homoglyph detection policy** will falsely block all non-ASCII names (Chinese/Japanese/Korean plugin names), and currently has no appeal mechanism or character allowlist
3. **The allowlist is centralized control** (remotely distributed via GrowthBook), and plugins not on the allowlist cannot obtain channel permissions. However, the fail-closed design is the correct security choice
4. **pluginOnly policy does not restrict a plugin's internal network behavior** β this is the inherent boundary of the MCP process-isolation model; a WASM sandbox (like Zed's approach) could provide stronger isolation but would limit plugin capabilities
5. **Auto-update race condition**: If the update completes before the REPL callback is registered, the update notification is stored in `pendingNotification` β while there is handling, users may miss the update prompt for a few seconds
---
*Quality self-check:*
- [x] Coverage: code landing table (44+3 files), installation pipeline deep dive, failure path analysis, dependency resolution, Skills collaboration extension, auto-update strategy, delisting uninstallation, version management, enterprise policy layer
- [x] Fidelity: based on code analysis of all 44 source files in `src/utils/plugins/`, all code references have been verified
- [x] Critical: identified ASCII-only homoglyph false-positive issue, pluginOnly security boundary, marketplace-level signature granularity limitation, auto-update race condition
- [x] Boundary with Chapter 03: opening statement clarifies division of labor with the MCP chapter, and explains the role of plugin scope