Track Claude Code plugin contract parity beyond the current adapter

[ScriptedAlchemy]

Summary

Documentation-coverage follow-up for the Claude Code plugin surface observed on 2026-09-01. This is a host-specific child of #100 and the #107 plan; it turns the current Claude adapter's implicit omissions into an explicit checklist.

Current implemented baseline: skills/SKILL.md emission, command hook wrappers for the canonical route families, MCP, marketplace stub, and LSP are in packages/agent-bundle/src/adapters/claude.ts and adapters/capabilities/claude-2.1.250.json. Skill lowering stays on #108, semantic event-family work stays on #97, schema/validator adoption stays on #133, and end-user installation stays on #181/#101.

Documented contract to account for

Sources (read 2026-09-01):

• https://code.claude.com/docs/en/plugins
• https://code.claude.com/docs/en/plugins-reference
• https://code.claude.com/docs/en/plugin-marketplaces
• https://code.claude.com/docs/en/plugin-dependencies
• https://code.claude.com/docs/en/skills
• https://code.claude.com/docs/en/hooks

Every item below must end as implemented with pinned evidence, delegated to the linked lane, or explicitly unavailable/prohibited in the capability table with a reason.

Plugin components and manifest

• Commands (commands/) including flat Markdown discovery and custom paths — flat .md emission landed earlier; custom-path replace/add rules pinned as capability evidence with native proof in feat(claude): emit manifest metadata fields and pin component path rules (#187) #293 (slice 2)
• Agents (agents/) with name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, and isolation: worktree — feat(claude): record agents-component parity evidence under G5 gate #346 (slice 4; recorded unavailable under the Compile capability-aware host component bundles #100 stage-2 G5 gate per docs(capabilities): record the #100 stage 2 agents-component deferral in pinned capability notes #220/meta-framework: execution plan and sequencing #107 revision 3: 15 dated capability rows cover the component, every documented frontmatter field, and the security contract; native proof records Claude Code 2.1.257 strict validation accepts all documented fields; re-admitting agents emission needs its own evidence-backed increment)
• Enforce the plugin-agent security contract: reject/omit hooks, mcpServers, and permissionMode for plugin-shipped agents — feat(claude): record agents-component parity evidence under G5 gate #346 (slice 4; recorded as capability evidence under the same G5 deferral: the docs state all three are ignored for plugin-shipped agents, and native proof records strict validation accepts even permissionMode: bypassPermissions without warning, so the loader-side ignore contract has no validator enforcement; compiler-side rejection lands with the gated agents emission increment)
• Workflows (workflows/ and manifest path field) — feat(claude): emit plugin workflows and output styles (#187) #300 (slice 2; canonical workflows/ directory emission via the hardened shared payload-directory normalizer with realpath containment; the optional manifest path field is deliberately not emitted since the adapter only uses the default location, and workflow file contents stay opaque because the reference defines no file schema)
• Output styles (output-styles/ / outputStyles) — feat(claude): emit plugin workflows and output styles (#187) #300 (slice 2; tightened to .md files per the output-styles doc; frontmatter is not validated — native proof records Claude Code 2.1.257 strict validation accepts an output style with no frontmatter; default-location emission only, no outputStyles manifest field)
• Experimental themes and monitors, including when and host-availability constraints — feat(claude): emit experimental themes and monitors (#187) #302 (slice 2; pinned monitors/theme schemas, when limited to always/on-skill-invoke:<skill> with a skill-existence tightening, ${user_config.*} rejected in monitor commands, host-availability warnings emitted; native proof records 2.1.257 strict validation does not inspect either default-location document's contents, so the pinned schemas and compiler diagnostics are the only content guard)
• bin/ PATH executables and the organization-distribution prohibition on top-level bin/ — feat(claude): emit plugin bin/ executables (#187 slice 1) #282 (slice 1)
• Root settings.json defaults (agent, subagentStatusLine) and precedence over manifest settings — feat(claude): emit plugin-root settings.json defaults (#187 slice 1) #284 (slice 1)
• Complete metadata/component path fields (displayName, metadata, defaultEnabled, custom path replace/add rules) — feat(claude): emit manifest metadata fields and pin component path rules (#187) #293 (slice 2)
• userConfig, including supported types, validation fields, sensitive storage, source precedence, and shell-substitution prohibitions — feat(claude): emit userConfig manifest options (#187 slice 1) #287 (slice 1; substitution enforcement inside hook/MCP planning recorded as evidence, deferred to the hooks-fidelity slice)
• channels declarations bound to plugin MCP servers — feat(claude): emit channel declarations bound to plugin MCP servers (#187) #294 (slice 2; native proof records the CLI does not cross-check the server binding, so the compiler diagnostic is the only guard)
• Plugin dependencies: same/cross-marketplace resolution, semver ranges, auto-install/enable, conflicts, prune, and command/headersHelper exceptions — feat(claude): emit plugin dependencies (#187 slice 1) #290 (slice 1; declaration validation + manifest emission + pinned evidence; marketplace-side allowCrossMarketplaceDependenciesOn emission landed in feat(claude): complete marketplace manifest contract (#187) #310, slice 3)

Package/cache/data lifecycle

• Eligible Node dependency install contract: root package.json plus Bun/npm lockfile, frozen install, --ignore-scripts, 60-second limit, deterministic lockfile precedence — feat(claude): validate substitution tokens and record lifecycle contract #347 (slice 5; recorded unavailable with the full documented contract pinned in the capability row — lockfile-to-command map, precedence order, 60-second timeout; native proof records strict validation accepts package metadata without running any install)
• Explicitly reject/defer automatic Yarn/pnpm installs and document the ${CLAUDE_PLUGIN_DATA} alternative — feat(claude): validate substitution tokens and record lifecycle contract #347 (slice 5; recorded unavailable: the host skips yarn.lock/pnpm-lock.yaml because resolution-time hooks can bypass --ignore-scripts, and the documented ${CLAUDE_PLUGIN_DATA} hook-install alternative is pinned in the evidence)
• Cache copy/link semantics, version resolution, orphan grace/sweep, symlink containment, and path-escape rejection — feat(claude): validate substitution tokens and record lifecycle contract #347 (slice 5; recorded unavailable as host install-time behavior with the full documented lifecycle pinned; native proof records strict validation does not catch a path-escaping symlink, so containment is an install-copy check)
• ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, and ${CLAUDE_PROJECT_DIR} substitution by component/field — feat(claude): validate substitution tokens and record lifecycle contract #347 (slice 5; recorded degraded with the closed documented field table pinned and enforced: token-bearing MCP stdio cwd and undocumented LSP fields now fail with claude.substitution.token.unsupported, and the previously emitted never-substituted cwd: "${CLAUDE_PLUGIN_ROOT}" is omitted; Skill content and target-native hook documents remain opaque payloads)
• Persistent-data deletion on last uninstall and --keep-data — feat(claude): validate substitution tokens and record lifecycle contract #347 (slice 5; recorded unavailable with dated evidence: last-scope deletion, the interactive prompt, CLI default deletion, and --keep-data are host uninstall behavior)

Marketplace/distribution/policy

• Full marketplace.json top-level and plugin-entry fields, including strict, renames, relevance, headers, and headersHelper — feat(claude): complete marketplace manifest contract (#187) #310 (slice 3; authored claude.marketplace overlay with closed schema re-pinned in PROVENANCE; tightening: headers/headersHelper are rejected as inapplicable on non-archive sources rather than emitted, since the native CLI's strict validation fails them there — the archive-source path landed with feat(claude): support marketplace source matrix #314)
• Source matrix: relative, github, git URL, git-subdir, npm, archive, and command (copy/link) with pin/integrity rules — feat(claude): support marketplace source matrix #314 (slice 3; all seven documented source forms with plan-time pin/integrity validation — 40-hex commit SHAs, sha256: digests, HTTPS-only archives, documented command modes — and native strict-validation proofs including negative proofs for short SHA, HTTP archive URL, and unknown command mode)
• @skills-dir plugins and their project trust/MCP/LSP/monitor restrictions — feat(claude): pin distribution policy capability evidence (#187) #308 (slice 3; recorded unavailable with dated evidence: Agent Bundle emits plugin directories but does not register host-owned @skills-dir identities or satisfy the trust/MCP-approval/LSP/monitor gates, which are runtime host behavior)
• Install scopes, reload behavior, trust gates, synced plugins, and managed scope — feat(claude): pin distribution policy capability evidence (#187) #308 (slice 3; recorded unavailable with dated evidence: these are host-owned install-time/runtime behaviors outside compile-time artifact emission)
• Managed restrictions: strictKnownMarketplaces, blockedMarketplaces, disableSideloadFlags, disableCommandPluginSources, allowManagedHooksOnly, and plugin suggestions — feat(claude): pin distribution policy capability evidence (#187) #308 (slice 3; recorded unavailable with dated evidence: managed-settings enforcement is administrator/host-owned)
• CLI lifecycle coverage (init/new, install/uninstall/prune/enable/disable/update/list/details/tag, marketplace add/list/remove/update) — feat(claude): pin distribution policy capability evidence (#187) #308 (slice 3; recorded as capability rows with dated evidence, plus native proofs exercising claude plugin/claude plugin marketplace lifecycle commands against the real binary in an isolated config directory)

Acceptance

• The capability table names every documented component/lifecycle area above as supported, degraded, unavailable, or prohibited with dated evidence.
• The compiler never silently drops a documented component requested by an author.
• Supported fields validate against pinned schemas and real-host fixtures; unsupported fields fail with a precise diagnostic and recovery.
• Compile semantic Agent event routes into native host hooks #97, Compile target-aware Skills with host frontmatter and interpolation #108, Adopt pinned schemas and ecosystem validators for generated plugin conformance (build-time + doctor) #133, Feature: emit ready-to-install host packs (and/or an 'agent-bundle install <host>' command) so projects don't hand-maintain install scripts #181, and Add safe managed lifecycle for generated host bundles #101 are linked from the resulting capability evidence instead of duplicating their work.

Related: #107 #100 #97 #101 #108 #133 #181

[ScriptedAlchemy]

Additional hook/MCP contract checklist from the same 2026-09-01 reference pass:

• Handler types: command, http, mcp_tool, prompt, and experimental agent; current generated schema/wrappers support command only.
• Common/command fields and semantics: if, args exec form, timeout, statusMessage, skill-only once, async, asyncRewake, and shell selection.
• Per-event input/output, exit-code, timeout, and blocking rules rather than treating every event like PreToolUse/Stop.
• Exact matcher modes and per-event matched fields, including events that ignore matchers and FileChanged's literal watch-list behavior.
• Plugin MCP scoping: tool matchers use mcp__plugin_<plugin>_<server>__<tool> and mcp_tool.server uses plugin:<plugin>:<server>; bare server keys are not equivalent.
• MCP-tool-hook connected-server timing and nonblocking error behavior.

Canonical event-family selection remains on #97; this checklist is native Claude hook-document fidelity.

[ScriptedAlchemy]

#193 records and proves the validate, strict-warning, --plugin-dir, and JSON list developer-tool surfaces against Claude Code 2.1.251 while keeping the capability pin at 2.1.250. The plugin details component inventory remains tracked here; the PR does not reimplement Claude's count_tokens/character-fallback costing.

[ScriptedAlchemy]

Decision (2026-09-01): systematic parity pass adopted — every stable documented surface gets implemented, host by host, Claude (#187) first. Recorded gate deferrals (e.g. G5 agents via #220) stand unless explicitly lifted. Slice 1 of #187 is in flight.