Repository navigation
[0.38] feat(native): project-scope native plugins for Claude and Copilot - #4047
Closed
Daniel Meppiel (danielmeppiel) wants to merge 3 commits into
Closed
Daniel Meppiel (danielmeppiel) wants to merge 3 commits into
Daniel Meppiel (danielmeppiel) wants to merge 3 commits into
Conversation
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>
Daniel Meppiel (danielmeppiel)
force-pushed
the
danielmeppiel-psychic-barnacle
branch
from
November 20, 2026 01:33
f9c1b0b to
fbcd2df
Compare
Collaborator
Author
8 of 13 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 installin a project that targetsclaudeorcopilotnow installs an eligible Claude plugin, or an Agent Plugin, intact and committed:apm_modules/<pkg>/stays the gitignored source..agents/plugins/<plugin>/and.agents/plugins/.claude-plugin/marketplace.jsonis generated. Both are committed; nothing is added to.gitignore../.agents/pluginsunderapm-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.jsonand/or.github/copilot/settings.jsonfollowing each dependency's targets. OnlyextraKnownMarketplacesandenabledPluginsare 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.yamlnative_pluginrecords (previous and next lock), as in #3290: APM writestrueonly when a key is absent, keeps user entries and explicitfalse, removes only what its lock produced, refuses a same-name marketplace pointing elsewhere in any file the harness reads (including.claude/settings.local.jsonfor 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 innative_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.pynow only migrates: a legacyapm_modules/.github/plugin/apm-registration.jsonregistration is removed exactly as its ledger records (on install, uninstall and prune), then the ledger and its catalog. Dropped with the ledger: theapmmarketplace,settings.local.jsonwrites and plugin-name precedence (same-name or case-folded collisions now fail closed).Decisions applied (Daniel): committed
.agents/plugins/<plugin>/withapm_modulesas the source; the pin covers path plus bytes (exec bit per machine only); plugins that declaredependenciesare refused (parked, as at user scope); Claude readsextraKnownMarketplacesandenabledPluginsfrom.claude/settings.json.Fingerprint. The project lock records a path+bytes digest. Until the restacked #3290 brings #3989's
compute_native_plugin_pin, a privatenative_plugins/binding.compute_native_plugin_portable_hashproduces 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).native_plugins/{reconcile,binding,harnesses,errors}.py;settings.py(relative path, emptied sections) andrecord.py(is_plugin_name)claude_plugins/registrar.py(delegates to the shared reconcile; legacy migration; audit per scope),admission.py(project scope, harness set)copilot_plugins/registrar.py(migration only),install/native_plugin_admission.py(queue Agent Plugins),install/phases/copilot_plugins.pyinstall/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 incommands/uninstall/cli.pynative_plugins/reconcile.py, mutation casesNo change under
src/apm_cli/integration/or to any shared target registry or adapter base.Residuals (unverified, documented):
<workspace>/.agents/plugins/activates in that project, so a plugin deployed for Claude/Copilot may also go live in Antigravity. Not testable here (no binary)..claude/settings.jsonmarketplaces; the [FEATURE] Qualify remaining targets against the native activation profile #3922 survey observed it did not load. Not testable here.apm uninstalled and reinstalled to switch (fix(claude): install intact user plugins through Claude settings, owned by the lock #3290's transition refusal, now worded for both scopes).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
Testing
Validation (Linux x86_64 sandbox, at f9c1b0b):
ruff check/ruff format --checkover the CI scope: passed.pylint R0801: 10.00/10.bash scripts/lint-auth-signals.shandbash scripts/lint-architecture-boundaries.sh: clean. 2100-line,relative_toand 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_checkOK (148 requirements);gen_statementregenerated with no diff after the spec commit.tests/unit/scripts, invariants: passed (after retargeting the Claude guard and the owner registry).APM_E2E_TESTS=1 APM_RUN_INTEGRATION_TESTS=1 pytestontest_project_native_plugin_lifecycle.py(fresh git clone without APM, livecopilot plugin list: enabled; flipping.github/copilot/settings.jsonto 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 onmainhere:test_unix_install_ownership.pyandtest_public_release_metadata.py(installer run as root),test_isolated_network_guard.py(no IPv6), 5 git-transport/auth-helper tests (host credentials).test_unix_installer_path_integration.py(root),test_marketplace_explicit_refresh_lifecycle.py(local HTTPS cert), onepwshtest.apm install obra/superpowers(v7.0.2,#main@22f0b463) at project scope withtargets: [claude, copilot]:.agents/plugins/superpowersis byte-identical to theapm_modulessource minus APM's pin file;copilot plugin listshowssuperpowers@apm-p-...enabled from.agents/plugins; itsSessionStarthook (${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd session-start) runs from the deployed root and emits the bundledusing-superpowersskill. 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
## [Unreleased]inCHANGELOG.md, at the bottom of Added.Spec conformance (OpenAPM v0.1)
tests/unit/native_plugins/test_project_scope.pyandtests/integration/test_project_native_plugin_lifecycle.py; req-na waivers unchanged.CONFORMANCE.{md,json}regenerated: rangen_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.consumer/installing-from-marketplaces.md: new section "APM-managed project plugins (Claude and Copilot)"; drops "Project scope comes later (#3921)".agents/plugins, relative path,apm-p-<hash>, per-target settings files, Copilot file precedence, worktree/one-session residuals, split-to-native switchconsumer/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 subsectionconsumer/copilot-agent-plugins.md(removed by #3996): "What APM writes", lifecycle rows, collision troubleshooting.agents/pluginsand declare in committed.github/copilot/settings.json; legacyapm-registration.jsonmigrationconsumer/install-plugins.md"Where plugins land", Agent Plugin row (replaceapm_modules+settings.local.json) plus one migration sentencereference/cli/install.md: one paragraph after the user-scope Claude paragraphreference/cli/uninstall.md: step 8 covers project and user scopepackages/apm-guide/.apm/skills/apm-usage/commands.md: one paragraph after the-g --target claudeparagraph