Modulo 5.7 Plugin System - Claude Code Deep Dive

1

🏗️ Five Conceptual Layers

Layer 1: Marketplace Sources

GitHub repos, git URLs, npm packages, local directories, URL-hosted JSON

Layer 2: Manifest Schema

plugin.json declara commands, hooks, MCP servers, LSP, skills, agents

Layer 3: Versioned Cache

~/.claude/plugins/cache/{mkt}/{plugin}/{version}/ -- snapshots imutaveis por versao

Layer 4: Dependency Resolution

DFS closure walk no install; fixed-point demote no load. Cross-marketplace deps bloqueadas

Layer 5: Lifecycle

reconcile -> autoupdate -> load -> hook registration -> command registration -> MCP connect

2

🌍 Marketplace Sources

Seis tipos de fonte suportados:

GitHub Repo

Clona owner/repo via SSH/HTTPS

Git URL

HTTPS, SSH, file://

Monorepo Subdir

Partial clone + sparse-checkout

HTTP/HTTPS URL

Fetch JSON direto

npm Package

Instalado em cache compartilhado

Local Path

Diretorio ou JSON local

Name Protection: BLOCKED_OFFICIAL_NAME_PATTERN regex bloqueia nomes como official-claude-plugins. Nomes reservados verificam que a org fonte e anthropics/ no GitHub.

3

📄 The Manifest Schema

Cada plugin opcionalmente entrega um plugin.json. Campos-chave:

Campo	Descricao
name	Kebab-case, usado para namespacing: `/plugin:cmd`
dependencies	Nomes bare herdam marketplace do plugin declarante
commands	Diretorio auto-scan + inline content
mcpServers	Suporta .mcpb/.dxt bundles ou config inline
userConfig	Valores configuraveis. Sensitive -> keychain, nao settings.json

Sem plugin.json, auto-discovery encontra commands/*.md, agents/*.md, skills/*/SKILL.md, hooks/hooks.json.

4

📦 Versioned Cache

Plugins sao instalados em cache imutavel content-addressed:

~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/

// Prioridade de versao:
1. plugin.json version field
2. Versao fornecida pelo marketplace
3. Git SHA pre-resolvido (12 chars)
4. 'unknown' como fallback

Para monorepo plugins, versao = {sha12}-{pathHash8} para evitar colisoes no mesmo commit.

5

🔗 Dependency Resolution

Install-time: DFS Closure

Deteccao de ciclo via DFS stack
Cross-marketplace bloqueado por default
Deps ja habilitadas sao puladas

Load-time: Fixed-Point Demote

Roda em cada sessao do cache-only set
Loop fixed-point: demotar A pode revelar que B depende de A
Semantica apt-style: presenca, nao import

6

🛡️ Security & Policy

Enterprise admins podem forcar-desabilitar plugins via managed-settings.json. Check isPluginBlockedByPolicy() roda no install, no enable e na UI.

Plugins podem ser instalados em 4 escopos: User, Project, Local e Managed (read-only).

Sensitive userConfig: valores marcados sensitive: true vao para o OS keychain, nao settings.json. Disponiveis em MCP server env mas nunca substituidos em conteudo skill/agent enviado ao modelo.

7

🔄 Background Autoupdate

No startup, autoupdate roda silenciosamente sem bloquear o REPL. Updates sao non-in-place: nova versao e cacheada em novo path, sessao atual continua com versao antiga. REPL e notificado e mostra prompt de restart.

📋 Resumo do Modulo

✅Plugin e um diretorio com plugin.json opcional -- auto-discovery encontra commands, agents, skills, hooks por convencao

✅Cache versionado imutavel previne colisoes; monorepo plugins codificam path hash na versao

✅Resolucao de dependencia usa DFS no install e fixed-point demote no load

✅Policy blocking via managed-settings.json e enforced em install, enable e UI

✅Autoupdate e background-only e non-blocking; sessao atual ve codigo antigo