Skip to content

[0.38] feat(native): project-scope native plugins for Claude and Copilot - #4047

Closed
Daniel Meppiel (danielmeppiel) wants to merge 3 commits into
danielmeppiel-native-hook-deliveryfrom
danielmeppiel-psychic-barnacle
Closed

Daniel Meppiel (danielmeppiel) wants to merge 3 commits into
danielmeppiel-native-hook-deliveryfrom
danielmeppiel-psychic-barnacle

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

Description

Stacked on #3290 (includes the 0.37 stack); retarget to main after the 0.37 tag.

Project-scope native plugins for Claude and Copilot, built on #3290's native seams (lock record, layout, shared settings writer) rather than beside them.

apm install in a project that targets claude or copilot now installs an eligible Claude plugin, or an Agent Plugin, intact and committed:

  1. apm_modules/<pkg>/ stays the gitignored source.
  2. The approved plugin root is copied to .agents/plugins/<plugin>/ and .agents/plugins/.claude-plugin/marketplace.json is generated. Both are committed; nothing is added to .gitignore.
  3. The marketplace is declared with the relative path ./.agents/plugins under apm-p-<sha256("project:" + apm.yml name)[:8]> (same in every clone and worktree, different per project), through fix(claude): install intact user plugins through Claude settings, owned by the lock #3290's settings writer, in .claude/settings.json and/or .github/copilot/settings.json following each dependency's targets. Only extraKnownMarketplaces and enabledPlugins are written.

A fresh clone without APM loads the plugin in Copilot CLI after folder trust (verified on Copilot CLI 1.0.112). Claude has no binary in this sandbox; its project route uses the same documented keys and relative-path rule (code.claude.com/docs/en/plugins/org).

Ownership comes only from apm.lock.yaml native_plugin records (previous and next lock), as in #3290: APM writes true only when a key is absent, keeps user entries and explicit false, removes only what its lock produced, refuses a same-name marketplace pointing elsewhere in any file the harness reads (including .claude/settings.local.json for Copilot), and commits deployed roots plus both settings files as one rollback unit (settings bytes are snapshotted and restored). A settings section or file emptied by APM's own removal is dropped.

Copilot file precedence (the contract for cross-harness spill): observed on Copilot CLI 1.0.112 with copilot plugin list, later wins: .claude/settings.json < .claude/settings.local.json < .github/copilot/settings.json < .github/copilot/settings.local.json. Pinned in native_plugins/harnesses.py (COPILOT_PROJECT_READ_ORDER), by a unit test, and by a gated e2e that runs the live CLI on a fresh clone.

Copilot route moved onto the shared writer. Admitted Agent Plugins are queued into the same native set (harness: Copilot only), recorded in the lock, deployed to .agents/plugins/ and declared in the committed .github/copilot/settings.json (user scope: ~/.agents/plugins, $COPILOT_HOME/settings.json). copilot_plugins/registrar.py now only migrates: a legacy apm_modules/.github/plugin/apm-registration.json registration is removed exactly as its ledger records (on install, uninstall and prune), then the ledger and its catalog. Dropped with the ledger: the apm marketplace, settings.local.json writes and plugin-name precedence (same-name or case-folded collisions now fail closed).

Decisions applied (Daniel): committed .agents/plugins/<plugin>/ with apm_modules as the source; the pin covers path plus bytes (exec bit per machine only); plugins that declare dependencies are refused (parked, as at user scope); Claude reads extraKnownMarketplaces and enabledPlugins from .claude/settings.json.

Fingerprint. The project lock records a path+bytes digest. Until the restacked #3290 brings #3989's compute_native_plugin_pin, a private native_plugins/binding.compute_native_plugin_portable_hash produces the same bytes (# TODO(#3989)), and a test asserts the exact byte layout so the swap is a one-line change. User scope is unchanged (mode-including digest).

Area Files
Shared native owner (moved from the Claude registrar, extended) native_plugins/{reconcile,binding,harnesses,errors}.py; settings.py (relative path, emptied sections) and record.py (is_plugin_name)
Claude owner claude_plugins/registrar.py (delegates to the shared reconcile; legacy migration; audit per scope), admission.py (project scope, harness set)
Copilot owner copilot_plugins/registrar.py (migration only), install/native_plugin_admission.py (queue Agent Plugins), install/phases/copilot_plugins.py
Wiring install/phases/{claude_plugins,lockfile}.py (records, per-record carry-forward), deployment_plan.py, services.py, pipeline.py, drift.py, commands/{prune,approve}.py, one small hunk in commands/uninstall/cli.py
Guards owner registry entry, Claude ownership guard retargeted at native_plugins/reconcile.py, mutation cases

No change under src/apm_cli/integration/ or to any shared target registry or adapter base.

Residuals (unverified, documented):

Issue and approved scope

Issue: Fixes #3921

Human scope-approval comment: #3921 (comment) (Review contact: Daniel Meppiel (@danielmeppiel); eligibility record-present).

Does this PR complete the issue? Yes for the code, tests, docs, apm-usage and CHANGELOG. The last commit, spec(normative, pending Daniel), is isolated and droppable: a decision for Daniel.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

Validation (Linux x86_64 sandbox, at f9c1b0b):

  • Lint mirror: ruff check / ruff format --check over the CI scope: passed. pylint R0801: 10.00/10. bash scripts/lint-auth-signals.sh and bash scripts/lint-architecture-boundaries.sh: clean. 2100-line, relative_to and YAML guards: clean.
  • pytest tests/unit/native_plugins tests/unit/install/test_claude_native_*.py tests/unit/copilot_plugins: passed (incl. the byte-layout swap guard for fix(0.37): finish owner hardening for bundle MCP, audit copies, failed installs, MCP targets and plugin pins #3989's pin and the Copilot precedence pin).
  • pytest tests/spec_conformance: 660 passed, 4 skipped, 3 xfailed. orphan_check OK (148 requirements); gen_statement regenerated with no diff after the spec commit.
  • Architecture: owner-rule mutation suite, tests/unit/scripts, invariants: passed (after retargeting the Claude guard and the owner registry).
  • APM_E2E_TESTS=1 APM_RUN_INTEGRATION_TESTS=1 pytest on test_project_native_plugin_lifecycle.py (fresh git clone without APM, live copilot plugin list: enabled; flipping .github/copilot/settings.json to false wins over .claude/settings.json), test_claude_native_hook_lifecycle.py, test_claude_plugin_hook_approval_lifecycle.py, test_copilot_native_plugin_binary_lifecycle.py (Copilot CLI 1.0.112; MCP handshake skipped, no Copilot login), the native audit/cache suites: passed.
  • pytest tests/unit tests/spec_conformance -n 8: all failures are host-environment and also fail on main here: test_unix_install_ownership.py and test_public_release_metadata.py (installer run as root), test_isolated_network_guard.py (no IPv6), 5 git-transport/auth-helper tests (host credentials).
  • Lifecycle smoke subset: stale project-scope split-install expectations are being updated in a follow-up push; remaining host-only failures: test_unix_installer_path_integration.py (root), test_marketplace_explicit_refresh_lifecycle.py (local HTTPS cert), one pwsh test.
  • Real installs: apm install obra/superpowers (v7.0.2, #main@22f0b463) at project scope with targets: [claude, copilot]: .agents/plugins/superpowers is byte-identical to the apm_modules source minus APM's pin file; copilot plugin list shows superpowers@apm-p-... enabled from .agents/plugins; its SessionStart hook (${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start) runs from the deployed root and emits the bundled using-superpowers skill. A live Copilot session was not possible (token without Copilot access), and no Claude binary is available, so the in-harness hook witness is still owed. A local Agent Plugin at project scope also lists as a live, enabled plugin in Copilot.

Changelog

  • One line in one section under ## [Unreleased] in CHANGELOG.md, at the bottom of Added.
  • N/A -- internal-only change (CI, tests, refactor).

Spec conformance (OpenAPM v0.1)

  • Spec edit: isolated last commit, amendment 0.1.68 (proposed, on top of 0.1.66): (a) A5 met by an observed precedence a conformance test pins, Part C Copilot project scope native-eligible with the 1.0.112 order; (b) the project-scope root digest omits the exec-bit byte. req-na-005 untouched. No statement added.
  • Manifest edit: not needed (no new requirement IDs).
  • Test edit: project-scope behaviour covered in tests/unit/native_plugins/test_project_scope.py and tests/integration/test_project_native_plugin_lifecycle.py; req-na waivers unchanged.
  • CONFORMANCE.{md,json} regenerated: ran gen_statement; CONFORMANCE.json picked up the re-expressed Copilot tests in the feature commit, no diff after the spec commit.

Docs re-home after #3996

All docs and apm-usage edits are in one docs: commit, written against the current layout; redo it on #3996's layout after the 0.37 tag.

Change (current layout) Intent Target in #3996's layout
consumer/installing-from-marketplaces.md: new section "APM-managed project plugins (Claude and Copilot)"; drops "Project scope comes later (#3921)" Project route: committed .agents/plugins, relative path, apm-p-<hash>, per-target settings files, Copilot file precedence, worktree/one-session residuals, split-to-native switch consumer/install-plugins.md: "Where plugins land" (Claude Code plugin row: native when the project targets claude/copilot) and replace the "Planned" note; "Known gaps" rows for #2824/#3191/#3181 become resolved for claude/copilot; precedence list as a short subsection
consumer/copilot-agent-plugins.md (removed by #3996): "What APM writes", lifecycle rows, collision troubleshooting Agent Plugins deploy to .agents/plugins and declare in committed .github/copilot/settings.json; legacy apm-registration.json migration consumer/install-plugins.md "Where plugins land", Agent Plugin row (replace apm_modules + settings.local.json) plus one migration sentence
reference/cli/install.md: one paragraph after the user-scope Claude paragraph Project-scope native route summary + link Same page in #3996
reference/cli/uninstall.md: step 8 covers project and user scope Removal of lock-owned roots and keys at both scopes Same page in #3996
packages/apm-guide/.apm/skills/apm-usage/commands.md: one paragraph after the -g --target claude paragraph Project route, precedence, Agent Plugin migration Same file (also edited by #3996; re-apply as one paragraph)

A project that targets Claude or Copilot installs an eligible Claude plugin,
or an Agent Plugin, intact: the approved root is copied to the committed
.agents/plugins/<plugin>/, .agents/plugins/.claude-plugin/marketplace.json is
generated, and the marketplace is declared with the relative path
./.agents/plugins under apm-p-<hash(apm.yml name)> in .claude/settings.json
and/or .github/copilot/settings.json, following each dependency's targets.

- Move #3290's reconcile out of the Claude registrar into the shared
  native_plugins owner (reconcile, binding, harnesses, claimants) and reuse
  its record, layout and settings writer. Ownership stays lock-only; all
  settings files are one rollback unit with the deployed roots.
- Pin Copilot CLI 1.0.112's observed file precedence (.github/copilot over
  .claude) and refuse a foreign same-name marketplace in any file a harness
  reads.
- Project locks record a path+bytes digest (interim helper, byte-identical
  to #3989's compute_native_plugin_pin; swap on rebase).
- Move the Copilot Agent Plugin route onto the shared owner; copilot_plugins
  now only migrates a legacy apm-registration.json registration.
- Keep req-tg-013 claimant selection, split install with a warning for
  ineligible plugins at project scope, and refusal of plugins that declare
  dependencies.
- Wire install, uninstall, prune, approve and audit replay; retarget the
  ownership guard and owner registry.

Fixes #3921

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Document the committed .agents/plugins route, Copilot's settings file
precedence, the Agent Plugin route on the shared native owner and the
legacy registration migration; update apm-usage.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…q-na-002

Proposed amendment 0.1.68 (on top of 0.1.66): (a) criterion A5 is met when
a target documents which other targets' files it reads but not their
precedence, for a client version whose observed precedence the consumer
discloses and a conformance test pins; Part C records Copilot CLI 1.0.112
as native-eligible at project scope with the observed order. (b) At
project scope the req-na-002 root digest omits the executable-bit byte.
req-na-005 untouched; no statement added. Droppable as one commit.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

Closing as a duplicate of #4010, the canonical PR for #3921. This draft came from a superseded session.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant