Skip to content

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

Draft
Daniel Meppiel (danielmeppiel) wants to merge 4 commits into
danielmeppiel-native-hook-deliveryfrom
danielmeppiel-miniature-robot
Draft

Daniel Meppiel (danielmeppiel) wants to merge 4 commits into
danielmeppiel-native-hook-deliveryfrom
danielmeppiel-miniature-robot

Conversation

@danielmeppiel

@danielmeppiel Daniel Meppiel (danielmeppiel) commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Description

TL;DR. At project scope, apm install now deploys each approved plugin intact to the committed .agents/plugins/<plugin>/, generates the catalog under a marketplace name unique to the repo, and declares it with a relative path in .claude/settings.json and .github/copilot/settings.json, following each plugin's targets. A fresh clone loads the plugins in Claude Code and GitHub Copilot after the folder-trust prompt, with no APM. The Copilot Agent Plugin route moves onto the same owner, and apm-registration.json registrations are migrated away.

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

Problem (WHY)

  • At project scope APM split Claude-format plugins into loose files; plugins that depend on their own layout broke (Superpowers v7.0.2 fails once its hooks are approved, [EPIC] Native plugin installation and lifecycle across all APM targets #3094).
  • The Copilot native route kept its own apm-registration.json receipt in apm_modules and wrote only the uncommitted .github/copilot/settings.local.json, so a fresh clone got nothing without APM.
  • Claude's per-user marketplace registry is keyed by name: two repos with the same marketplace name ran the other repo's hook after a project switch (Claude Code 2.1.322), so names must differ per repo.

Approach (WHAT)

Decision (Daniel's design, recorded on #3921) Where
APM downloads into apm_modules; agents load from .agents. APM resolves, locks and approves whole plugins, deploys the approved root to .agents/plugins (committed at project scope) and declares it only through each harness's documented settings keys. No vendor CLI/RPC, no receipt; ownership = apm.lock.yaml. claude_plugins/registrar.py
One shared settings writer for both harnesses; each harness file follows the plugin's targets; add/remove only entries the previous or next lock produced; keep user entries and explicit false. native_plugins/settings.py, native_plugins/scopes.py
Marketplace name per repo: apm-p-<8 hex> from the origin remote (host/owner/repo), else the apm.yml name; once recorded in the lock or committed catalog, that name is reused (forks keep it). native_plugins/scopes.py
Committed project-scope root digest = paths + bytes (same value as the portable approval pin); the exec bit is checked per machine (deployed copy vs apm_modules source at deploy), never recorded. claude_plugins/admission.py, registrar.py
Cross-harness spill relies on Copilot's file priority: for a plugin declared to Claude only, APM writes its own "<plugin>@<market>": false into .github/copilot/settings.json (read later, so it wins). APM owns that Copilot key for every plugin it declares to Claude, so it flips or retires it as targets change; every other false is kept. A test pins the order against the real CLI. native_plugins/settings.py, registrar.py (_suppression), tests/integration/test_copilot_project_settings_precedence.py

Implementation (HOW)

File Change
claude_plugins/registrar.py reconcile_claude_plugins → reconcile_native_plugins: both scopes, both harnesses. Previews every harness file before any root deploys; snapshots and restores all of them on failure (one rollback unit). A plugin admitted this run goes to the harnesses its targets select; a harness the run did not evaluate (--target narrowing, uninstall, prune) keeps its declarations.
claude_plugins/admission.py Lifts the user-scope-only gate: harnesses = {claude} at user scope, {claude, copilot} ∩ targets at project scope. Project scope records the portable digest.
native_plugins/scopes.py (new) Harness settings paths per scope, ./.agents/plugins, per-repo/per-home names, COPILOT_PROJECT_SETTINGS_PRECEDENCE.
native_plugins/uninstall.py (new) One helper so uninstall and prune converge through the same owner and restore the lock on failure; commands/uninstall/cli.py calls it from one small hunk.
copilot_plugins/*, install/native_plugin_admission.py Agent Plugins queue into the shared owner (harness {copilot}, both scopes). The apm_modules catalog/ledger/apm marketplace code is removed. plan_legacy_copilot_retirement plans the migration without writing; the owner applies it inside its transaction (legacy settings snapshotted, written through the shared writer, restored on rollback) and deletes the ledger and catalog only after commit. It runs only in a run that evaluated copilot and declares every legacy plugin from .agents/plugins; otherwise (uninstall, prune, --target claude, an old lock, an unreadable ledger) the legacy state is kept with a warning to run apm install.
install/phases/lockfile.py, drift.py, deps/cli.py, services.py Scope-aware lock records; audit checks source and deployed copy (portable digest at project scope); apm deps list reads the lock; scope-correct transition hints.
.apm/architecture, scripts/architecture_linter Owner registry and guards follow the moved owners; mutation cases updated.

Diagram

Legend: how one locked plugin reaches each harness at project scope (dashed: Copilot also reads Claude's file, at lower priority).

flowchart LR
  A["apm_modules/pkg (gitignored source)"] -->|"admit: targets, trust, intact"| B["apm.lock.yaml native_plugin record"]
  B -->|"deploy copy, exec bit checked per machine"| C[".agents/plugins/plugin (committed)"]
  B --> D[".agents/plugins/.claude-plugin/marketplace.json"]
  B -->|"claude in targets"| E[".claude/settings.json"]
  B -->|"copilot in targets"| F[".github/copilot/settings.json"]
  E --> G["Claude Code"]
  E -.->|"also read, lower priority"| H["GitHub Copilot CLI"]
  F --> H
Loading

Trade-offs

  • Copy, not live link. Deployed roots are copies, so a local-path plugin edit shows up on the next install (the old Copilot route loaded apm_modules live). Required for a clone without APM.
  • APM-owned false for Claude-only plugins. Copilot also reads .claude/settings.json, so APM writes false for a Claude-only plugin in .github/copilot/settings.json. Ownership is exact without a lock-schema change: APM owns the Copilot key of every plugin it declares to Claude. The cost: to keep a Claude+Copilot plugin off in Copilot, narrow its targets: (APM then writes the false) rather than hand-editing that key; when APM overrides a value it did not write, it prints one [!] line naming the key and pointing to targets:. What APM last wrote is recorded beside each native row as native_declared (a per-entry field 0.37 readers already preserve as unknown; advisory, not trust-bearing), so values a narrowed run left behind change silently. A false for a Copilot-only plugin, or in Claude's file, is still kept.
  • Per-dependency carry-over. A run whose targets, narrowed by a dependency's own targets:, never reach that plugin keeps its whole previous lock row, deployed root and declarations, even if its source changed, and says the update waits (same shape as req-na-005's "keep the previous entry"). Such a run also deploys nothing loose for that dependency (for example its cursor files), so the kept row and disk agree. apm audit --ci and apm install --frozen then report only the deferred update itself (a local source newer than the lock) until a full install, after which both pass.
  • Migration is conservative. Legacy registrations move only in an install that re-declares every legacy plugin for Copilot; other commands warn instead of silently switching plugins off.
  • Collisions refuse. Two plugins whose names match ignoring case fail the install naming both; the old Copilot direct-over-transitive precedence is not carried over.
  • Loose-to-native with hooks. A plugin whose hooks were installed loose before is refused with apm uninstall <pkg> && apm install <pkg> (inherited fix(claude): install intact user plugins through Claude settings, owned by the lock #3290 guard, now with a scope-correct hint); plugins without loose hooks switch automatically.
  • Name identity. Without an origin remote, the name derives from the apm.yml name, so two remote-less repos with the same name on one machine share a name.

Benefits

  1. A plugin targeting only claude stays off in Copilot (real CLI: (disabled)), and turns on when copilot is added to its targets.
  2. A fresh clone with only committed files loads the plugin in Copilot after trust (copilot plugin list → demo-plug@apm-p-… (enabled) from <clone>/.agents/plugins), none before trust.
  3. Superpowers v7.0.2 deploys byte-identical (hooks included) and lists in Copilot as superpowers@apm-p-… (v7.0.2) (enabled).
  4. Uninstall removes only APM's entries: a user marketplace and mine@team: true survive; explicit false survives.
  5. Teammates on Windows or core.fileMode=false pass apm audit against the committed lock.

Validation evidence (local, CI runs after retarget to main)

Note

CI does not run on a PR whose base is not main. Everything below ran locally on head caa0ede9 (2 CPUs, git commit signing disabled for tests via GIT_CONFIG_*). Every remaining failure also fails on base ce7f86b9.

Command Result
uv run --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ All checks passed
uv run --extra dev ruff format --check … (same paths) 2484 files already formatted
uv run --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ 10.00/10
YAML I/O guard, file-length guard (2100), relative_to guard (from ci.yml) clean
bash scripts/lint-auth-signals.sh auth-signal lint clean
uv run --extra dev python scripts/lint_architecture_boundaries.py --root . clean
pytest tests/unit -q -n auto 28379 passed, 294 failed — all 294 also fail on base (test_unix_install_ownership ×246 run as root, test_public_release_metadata ×35, test_isolated_network_guard ×8, git env/transport ×5)
APM_BINARY_PATH=.venv/bin/apm pytest native lifecycle set¹ 158 passed
pytest tests/spec_conformance -n 2 650 passed, 2 failed (test_marketplace_directory_reqs, also on base)
pytest tests/integration/test_architecture_owner_rule_mutations.py -k "claude or copilot or native or marketplace" 212 passed, 1 failed (removal-baseline, also on base)
pytest tests/integration/test_copilot_project_settings_precedence.py (real Copilot CLI 1.0.112, isolated COPILOT_HOME; skips without the client) 9 passed
¹ Native lifecycle set

test_claude_native_hook_lifecycle.py, test_native_plugin_audit_lifecycle.py, test_native_plugin_cache_audit.py, test_native_plugin_cache_replay.py, test_dependency_replacement_lifecycle.py, test_unmanaged_skill_preflight_matrix.py, test_plugin_bin_trust_posture.py, test_copilot_project_settings_precedence.py, test_global_audit_external_apm_home_lifecycle.py, test_install_dry_run_transitive_lifecycle.py, plus tests/unit/install/test_native_project_scope.py, tests/unit/copilot_plugins/, tests/spec_conformance/test_copilot_plugins_reqs.py.

Scenario evidence

Scenario (done-when) Proof
Fresh clone without APM loads in Claude and Copilot after trust Copilot: precedence test test_a_fresh_checkout_loads_the_apm_declared_plugin + manual clone run; Claude: settings/catalog shape per test_install_commits_a_relative_declaration_to_both_harness_files (no Claude binary here)
Superpowers installs intact manual: diff -r apm_modules/obra/superpowers .agents/plugins/superpowers → only APM's .apm-pin differs; Copilot lists it enabled
Uninstall removes only APM-owned entries test_removal_keeps_user_entries_and_explicit_false, test_dependency_replacement_lifecycle.py native case, manual run
Which Copilot file wins when both name the plugin test_the_later_file_wins_when_both_name_the_plugin (all 6 file pairs, real CLI)
A narrowed --target never retires a plugin it did not evaluate (targets: [claude] + --target copilot; targets: [copilot] + --target claude), even when its source changed: both settings files, the deployed root and the whole lock row (to_dict()) stay byte-identical, with a default-visible "Kept the previous version" note test_a_narrowed_target_never_retires_a_plugin_it_did_not_evaluate (separate CLI processes; 4 cases; the 2 changed-content cases fail on 45e0b51e)
A narrowed run (targets: edited, then --target claude) leaves APM's Copilot value to change silently on the next full install test_a_narrowed_run_leaves_apms_copilot_value_to_change_silently (fails on 71dffff9)
A kept plugin deploys nothing loose: after --target cursor the loose and native files and lock row stay at v1 with no deployed drift; a full install applies v2 and audit --ci and install --frozen pass test_a_kept_plugin_deploys_nothing_loose_so_lock_and_disk_agree (fails on 71dffff9)
A kept plugin converges on the next full install: its deployment-ledger records are carried unchanged (never re-attributed to the narrowed run's target), the lock is byte-identical after --target cursor, and the full install applies v2 with --frozen passing test_a_kept_plugin_converges_on_the_next_full_install (fails on 48dc338f)
A record co-owned by a kept and an evaluated dependency goes to the evaluated one, whatever the dependency order (kept rows seed the ledger first and claim nothing this run) test_an_evaluated_dependency_wins_a_ledger_record_it_shares_with_a_kept_one (fails with a8706e0e's ordering)
APM reports a hand edit it overrides, once; a value it wrote under the previous row's targets: changes silently, and a targets: narrow or widen retires the stale declaration test_apm_reports_when_it_flips_a_copilot_value_it_owns, test_a_targets_edit_retires_the_stale_declaration_quietly (narrow and widen), test_a_value_apm_wrote_under_earlier_targets_changes_without_a_warning (the last 3 fail on 45e0b51e)
A Claude-only plugin does not load in Copilot test_a_plugin_targeting_claude_only_stays_off_in_copilot (real CLI), test_apm_owned_suppression_follows_the_targets_both_ways, test_cross_target_suppression_is_the_consumers_own_false (req-na-004)
Migration of apm-registration.json is one rollback unit and never silently deactivates test_legacy_registration_moves_when_copilot_declares_its_plugins, test_a_failure_after_retirement_restores_the_legacy_registration, test_legacy_registration_is_kept_unless_copilot_declares_its_plugins (uninstall/prune, --target claude, plugin no longer for Copilot), test_an_unreadable_ledger_is_never_deleted, lifecycle migration test
Committed digest portable across exec-bit semantics test_committed_digest_ignores_the_exec_bit_a_teammate_checkout_drops

Warning

Residuals, not verified here. (1) Superpowers' SessionStart hook running: no claude binary in this environment, and a Copilot session needs a login an isolated COPILOT_HOME cannot borrow; needs a human witness. (2) Cross-harness spill for Antigravity (documents that <workspace>/.agents/plugins/ folders activate in that project, our profile root) and Grok Build (docs say it reads project .claude/settings.json marketplaces; observed not loading): no binaries here, listed only. (3) Accepted Claude residuals: per-user name registry (handled by the per-repo name), worktrees resolving the relative path against the main checkout, one-session lag with relative paths. (4) Pre-existing: apm prune does not see an orphaned Agent Plugin root that has only plugin.json, so it is not retired by prune (uninstall retires it).

Manual verification for the reviewer

About 2 minutes. Needs claude (Claude Code) and, optionally, copilot on PATH. It closes the one residual this environment could not witness: Superpowers' SessionStart hook running from the committed root.

  1. Set up a throwaway repo that uses this branch's APM:
    mkdir -p /tmp/sp-check && cd /tmp/sp-check && git init -q
    git remote add origin https://github.com/acme/sp-check.git   # gives the repo its marketplace name
    printf 'name: sp-check\nversion: 0.1.0\ntargets: [claude, copilot]\ndependencies:\n  apm:\n    - obra/superpowers\n' > apm.yml
    uvx --from git+https://github.com/microsoft/apm@danielmeppiel-miniature-robot apm install
    Observe: 1 native plugin(s) deployed to /tmp/sp-check/.agents/plugins and declared in Claude Code and GitHub Copilot settings; .agents/plugins/superpowers/hooks/hooks.json exists; .claude/settings.json has superpowers@apm-p-…: true and "path": "./.agents/plugins".
  2. Commit and test a clone without APM: git add -A && git commit -qm t && git clone -q /tmp/sp-check /tmp/sp-clone && cd /tmp/sp-clone.
  3. Run claude, accept the folder-trust prompt, then /exit and run claude again (relative-path plugins can load from the second session). In that session run /plugin.
    Observe: superpowers@apm-p-… is listed and enabled.
  4. In the same session ask: Did a SessionStart hook inject context? Quote its first sentence.
    Observe: Claude quotes the Superpowers session-start context: an <EXTREMELY_IMPORTANT> block whose first sentence is You have superpowers. For extra certainty, claude --debug prints the SessionStart hook from .agents/plugins/superpowers/hooks/run-hook.cmd running with exit 0.
  5. Optional (Copilot): in /tmp/sp-clone, run copilot plugin list after trusting the folder.
    Observe: superpowers@apm-p-… (v7.0.2) (enabled) from /tmp/sp-clone/.agents/plugins.

Clean up: rm -rf /tmp/sp-check /tmp/sp-clone.

How to test

  • In a git repo with origin, apm.yml targets [claude, copilot] and a Claude-format plugin dependency: apm install; check .agents/plugins/<p>/, the catalog and both settings files ("path": "./.agents/plugins", apm-p-…).
  • Commit, clone elsewhere, trust the folder, copilot plugin list → enabled from <clone>/.agents/plugins.
  • Set the dependency's targets: [claude] and apm install → .github/copilot/settings.json holds "<p>@apm-p-…": false and copilot plugin list shows it disabled; add copilot back → true, enabled.
  • apm uninstall <dep> → APM keys and .agents/plugins/<p> gone, your own keys kept.
  • chmod -x a deployed hook script, apm audit → no drift at project scope.

Docs re-home after #3996

Done: the docs commit (last) is written directly on the #3996 layout. Main home consumer/install-plugins.md (#native-plugins); also consumer/install-packages.md (what to commit), consumer/install-mcp-servers.md, consumer/installing-from-marketplaces.md, consumer/approve-executables.mdx, quickstart.mdx (re-run end to end), concepts/how-apm-works.md, reference/cli/{install,uninstall,audit,approve,pack}.md, reference/{lockfile-spec,package-types,policy-schema}.md, producer/{write-primitives.md,build-a-plugin.mdx,publish-to-a-marketplace.mdx}, troubleshooting/index.md, and apm-usage commands.md, package-authoring.md, governance.md, workflow.md.

Issue and approved scope

Issue: Fixes #3921

Human scope-approval comment: #3921 (comment)

Completes the issue's code, tests, docs and changelog. The runtime witness that Superpowers' hooks run in Claude Code needs a human with the claude binary (see residuals).

Type of change

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

Testing

  • Tested locally
  • All existing tests pass — all except failures that also fail on base ce7f86b9 (listed above)
  • Added tests for new functionality (if applicable)

Changelog

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

Spec conformance (OpenAPM v0.1)

Important

The normative change is isolated in one commit, spec(normative, pending Daniel): project-scope clause for Part C / req-na-002, amendment 0.1.68 (provisional; 0.1.67 is taken by #3993; renumbered at merge). It revises the req-na-002 root-digest clause for project scope (paths + bytes recorded; exec bit compared per machine), the req-na-004 false rule (cross-target suppression: the consumer owns the Copilot key of a plugin it declares to Claude), and criterion A5 (a disclosed file priority, verified against Copilot CLI 1.0.112 by a test that skips without the client), and updates Part C and the Section 5.2 native_plugin row. req-na-005 is untouched; statement count unchanged (148). The implementation commits do not depend on it.

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md (amendment row in Appendix D).
  • Manifest edit: none needed (no new requirement ID).
  • Test edit: @pytest.mark.req("req-na-002"), req-na-003, req-na-004, req-na-007 tests in tests/spec_conformance/test_native_activation_profile_reqs.py.
  • CONFORMANCE.{md,json} regenerated via uv run --extra dev python -m tests.spec_conformance.gen_statement and committed.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

)

Deploy approved plugin roots to committed .agents/plugins/<plugin>/,
generate the catalog under a per-repo marketplace name, and declare it with
a relative path in .claude/settings.json and .github/copilot/settings.json
through the shared settings writer, following each plugin's targets.
Ownership comes from the previous and next apm.lock.yaml; every harness
file is previewed before any root deploys and restored on failure. The
committed root digest covers paths and bytes; the exec bit is checked per
machine against the apm_modules source at deploy.

Agent Plugins move onto the same owner at both scopes; registrations kept
in apm_modules/.github/plugin/apm-registration.json are migrated away.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…le priority (#3921)

Cover committed relative declarations, target-following harness files,
lock-derived removal that keeps user entries and explicit false, the
multi-file rollback unit, the exec-bit-free committed digest, the per-repo
marketplace name and the apm-registration.json migration. Move the Agent
Plugin lifecycle tests onto the deployed .agents/plugins copy, and pin
Copilot's project settings priority against the real CLI when it is on PATH.

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

Amendment 0.1.68 (provisional; renumbered at merge). At project scope the
committed root digest omits the executable-bit byte (it equals the approval
digest construction), and the consumer compares the bit per machine between
the materialized source and the deployed root before writing activation
entries. Criterion A5 accepts, at project scope, an observed file-priority
order the consumer discloses and pins with a conformance test; Part C records
GitHub Copilot CLI as native-eligible at project scope under that test, and
the Copilot req-tg-013 route as moved to this profile. req-na-005 is
unchanged; no statement count changes.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Document committed .agents/plugins deployment at project scope, the per-repo
marketplace name, the two harness settings files and Copilot's file
priority, lock-only ownership, the portable committed digest, the move off
the apm-registration.json route, and what to commit. Rebuilt on the #3996
layout; apm-usage updated to match.

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

This branch has not been deployed

No deployments
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