agentbundle 0.29.5__tar.gz → 0.31.0__tar.gz

{agentbundle-0.29.5 → agentbundle-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.29.5
+Version: 0.31.0
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License: Apache-2.0 OR MIT
@@ -269,7 +269,13 @@ ignore them there; the separation is structural, not incidental.
 `keywords` once; the build projects the cleanly-mappable subset — plus the
 pack's `README.md` — into each distribution route's manifest (the `plugin.json`
 / `marketplace.json` entry), so the catalogue describes each pack richly rather
-than with a single sentence. Extra fields stay in `pack.toml`; the projection
+than with a single sentence. The Claude-plugin route carries only packs whose
+`[pack.install] allowed-scopes` admits `user`: a plugin's code lands in the
+adopter's global cache, so a repo-only pack gets no `marketplace.json` entry
+and is reached with `agentbundle install` instead. A marketplace entry's `source` is a `git-subdir`
+object (`url`, `path`, and one of `ref`/`sha`) pointing at the pack's directory
+on the published distribution branch, and every entry is schema-validated at
+build time against `marketplace-entry.schema.json`. Extra fields stay in `pack.toml`; the projection
 is deliberately lossy per tool.
 
 Point a catalogue URI (a git URL or a local path) at the repo that holds your packs. Then `validate` a pack against the adapter contract, `render` it to preview the projection, and `install` it into a target repo. `scaffold` drops a pack's seeds into a fresh directory to start from. The build pipeline (`agentbundle.build`) is the same engine `make build` runs.
@@ -285,8 +291,9 @@ The org hint fires after the user-config but before the on-disk IDE probe — so
 
 **Bundled contracts** — the wheel ships the machine contracts used for offline validation:
 `pack.schema.json`, `skill.schema.json`, `guide.schema.json`, `skill-manifest.schema.json`,
-`profile.schema.json`, `catalogue.schema.json`, `target-vocab.toml`, and the adapter
-contract files. All are available without network access via `importlib.resources`.
+`profile.schema.json`, `catalogue.schema.json`, `plugin-manifest.schema.json`,
+`plugin-manifest.derived.schema.json`, `marketplace-entry.schema.json`,
+`target-vocab.toml`, and the adapter contract files. All are available without network access via `importlib.resources`.
 
 **Lint your catalogue** — shallow structural checks run without extra dependencies:
 
@@ -301,13 +308,30 @@ pip install 'agentbundle[lint]'
 agentbundle catalogue lint --root . --deep
 ```
 
-**Check self-host projection drift** — verifies that adapter-projected files (skills, agents, hooks) match their `.apm/` sources without writing anything:
+**Verify a catalogue before you ship it** — runs the full read-only contract and
+self-host checks in one command:
+
+```bash
+agentbundle catalogue verify --root .
+```
+
+For a self-host-enabled catalogue with `.adapt-discovery.toml`, that includes the
+self-host classifier. It treats generated targets as projected and known
+repository-owned paths as excluded from projection. A genuinely unknown Git-visible
+path remains an informational `unclassified` notice; it does not fail an otherwise
+clean catalogue. Missing, modified, or orphaned projections do fail verification,
+including generated executables under `.agentbundle/bin/` and vendored user libraries
+under `.agentbundle/lib/`. Git filenames are read losslessly, and a failed Git listing
+is reported as a warning rather than mistaken for a fully classified inventory.
+
+To check only self-host projection drift, or to regenerate projected files locally:
 
 ```bash
 agentbundle catalogue self-host --check --root .
+agentbundle catalogue self-host --write --root .
 ```
 
-Exits non-zero if any projected file is out of date. Safe to run in CI as a required check; use `--write` locally to regenerate.
+Both check commands are safe to run in CI. The write command changes projected files.
 
 By default projects for `claude-code` and `codex`. Downstream repos that use a single adapter (e.g. `kiro-ide`) can declare it in `catalogue.toml` — only that adapter is then projected, and its output files participate in the drift check:
 

{agentbundle-0.29.5 → agentbundle-0.31.0}/README-pypi.md

@@ -247,7 +247,13 @@ ignore them there; the separation is structural, not incidental.
 `keywords` once; the build projects the cleanly-mappable subset — plus the
 pack's `README.md` — into each distribution route's manifest (the `plugin.json`
 / `marketplace.json` entry), so the catalogue describes each pack richly rather
-than with a single sentence. Extra fields stay in `pack.toml`; the projection
+than with a single sentence. The Claude-plugin route carries only packs whose
+`[pack.install] allowed-scopes` admits `user`: a plugin's code lands in the
+adopter's global cache, so a repo-only pack gets no `marketplace.json` entry
+and is reached with `agentbundle install` instead. A marketplace entry's `source` is a `git-subdir`
+object (`url`, `path`, and one of `ref`/`sha`) pointing at the pack's directory
+on the published distribution branch, and every entry is schema-validated at
+build time against `marketplace-entry.schema.json`. Extra fields stay in `pack.toml`; the projection
 is deliberately lossy per tool.
 
 Point a catalogue URI (a git URL or a local path) at the repo that holds your packs. Then `validate` a pack against the adapter contract, `render` it to preview the projection, and `install` it into a target repo. `scaffold` drops a pack's seeds into a fresh directory to start from. The build pipeline (`agentbundle.build`) is the same engine `make build` runs.
@@ -263,8 +269,9 @@ The org hint fires after the user-config but before the on-disk IDE probe — so
 
 **Bundled contracts** — the wheel ships the machine contracts used for offline validation:
 `pack.schema.json`, `skill.schema.json`, `guide.schema.json`, `skill-manifest.schema.json`,
-`profile.schema.json`, `catalogue.schema.json`, `target-vocab.toml`, and the adapter
-contract files. All are available without network access via `importlib.resources`.
+`profile.schema.json`, `catalogue.schema.json`, `plugin-manifest.schema.json`,
+`plugin-manifest.derived.schema.json`, `marketplace-entry.schema.json`,
+`target-vocab.toml`, and the adapter contract files. All are available without network access via `importlib.resources`.
 
 **Lint your catalogue** — shallow structural checks run without extra dependencies:
 
@@ -279,13 +286,30 @@ pip install 'agentbundle[lint]'
 agentbundle catalogue lint --root . --deep
 ```
 
-**Check self-host projection drift** — verifies that adapter-projected files (skills, agents, hooks) match their `.apm/` sources without writing anything:
+**Verify a catalogue before you ship it** — runs the full read-only contract and
+self-host checks in one command:
+
+```bash
+agentbundle catalogue verify --root .
+```
+
+For a self-host-enabled catalogue with `.adapt-discovery.toml`, that includes the
+self-host classifier. It treats generated targets as projected and known
+repository-owned paths as excluded from projection. A genuinely unknown Git-visible
+path remains an informational `unclassified` notice; it does not fail an otherwise
+clean catalogue. Missing, modified, or orphaned projections do fail verification,
+including generated executables under `.agentbundle/bin/` and vendored user libraries
+under `.agentbundle/lib/`. Git filenames are read losslessly, and a failed Git listing
+is reported as a warning rather than mistaken for a fully classified inventory.
+
+To check only self-host projection drift, or to regenerate projected files locally:
 
 ```bash
 agentbundle catalogue self-host --check --root .
+agentbundle catalogue self-host --write --root .
 ```
 
-Exits non-zero if any projected file is out of date. Safe to run in CI as a required check; use `--write` locally to regenerate.
+Both check commands are safe to run in CI. The write command changes projected files.
 
 By default projects for `claude-code` and `codex`. Downstream repos that use a single adapter (e.g. `kiro-ide`) can declare it in `catalogue.toml` — only that adapter is then projected, and its output files participate in the drift check:
 

{agentbundle-0.29.5 → agentbundle-0.31.0}/agentbundle/_data/adapter.toml

@@ -188,12 +188,14 @@ install-routes = ["cli", "claude-plugins", "apm"]
 primitive = "skill"
 mode = "direct-directory"
 target-path = ".claude/skills/"
+plugin-target-path = "skills/"
 on-conflict = "prompt-then-preserve"
 
 [[adapter."claude-code".projection]]
 primitive = "agent"
 mode = "direct-file"
 target-path = ".claude/agents/"
+plugin-target-path = "agents/"
 on-conflict = "prompt-then-preserve"
 
 [[adapter."claude-code".projection]]
@@ -213,6 +215,7 @@ on-conflict = "merge-managed-key-only"
 primitive = "command"
 mode = "direct-file"
 target-path = ".claude/commands/"
+plugin-target-path = "commands/"
 on-conflict = "prompt-then-preserve"
 
 # hook-body — scope-conditional target.

{agentbundle-0.29.5 → agentbundle-0.31.0}/agentbundle/_data/catalogue-scaffold/guides/_shared/reference/catalogue-authoring-standards.md

@@ -36,6 +36,62 @@ and `version`; `[pack.adapter-contract]` with `version`.
 - [packs/README.md](../../../packs/README.md) — pack layout, versioning rules, lint commands.
 - [packs/AGENTS.md](../../../packs/AGENTS.md) — agent-facing schema map and primary workflow.
 
+### `[pack].description` — display copy
+
+`[pack].description` is read by a **person** deciding whether to install: in a
+marketplace browser, a catalogue listing, or CLI output. It is not read by the model.
+
+That makes it a different artifact from a skill's or agent's `description`, which the
+model reads to decide whether to **activate** the primitive. Length is load-bearing
+there and shortening it degrades activation; per-target caps in
+`contracts/target-vocab.toml` govern it. Do not carry habits from one to the other.
+
+**Shape.** Open on the job the adopter accomplishes, in their words. Say what they
+get. Then stop.
+
+Beyond that, let the pack decide the shape. Some need one sentence:
+
+> Write the OpenAPI or AsyncAPI contract before anyone writes a handler.
+
+Others earn three:
+
+> Ship it the way production will see it. Deploy to a throwaway environment, run
+> the tests, read the telemetry, and go round again until it holds. Then it stops
+> and asks, because the next step is the one you cannot undo.
+
+**Do not run every description through one mould.** An earlier pass here applied a
+single shape — verb-first sentence, then a comma-list of capabilities — to all
+22 packs. The result measured as 20 of 22 at exactly two sentences, 14 with a
+comma-list second sentence, four opening on the identical "Turn X into Y" frame.
+Every fact was right and the set still read as machine-written, because uniform
+rhythm and symmetrical construction are themselves the tell. Vary sentence count
+and length to match what each pack actually is.
+
+Reach for the concrete. A real thing the user says (`"convert this PDF to
+Markdown"`), a real artifact (`a Google-style design doc`), or a real check
+(`the empty state and the focus ring you forgot`) all beat an abstract capability
+noun.
+
+**Anti-patterns**, each of which has shipped here before:
+
+| Anti-pattern | Instead |
+| --- | --- |
+| Opening with a component inventory (`Core: work-loop, new-spec, bug-fix, …`) | Lead with the outcome; the inventory belongs in the README |
+| Repo-insider vocabulary (`forked-context`, `the grown-up successor to X`) | Words a first-time reader resolves without this repo |
+| Cross-pack references (`co-installs with X`, `feeds Y's queue`) | Nothing that assumes another pack is known |
+| Provenance name-drops (`(STORM, PRISMA, ACH, GRADE)`) | Name a framework only when the reader is buying it |
+| Negative space (`no stack, no values tables, no pixel comps`) | Say what it does; the README can scope what it doesn't |
+| Internal paths (`~/.agentbundle/bin/`) | Nothing an adopter cannot act on from a listing |
+
+**Discoverability is carried elsewhere** — `[pack].keywords` and `[pack].categories`
+— so prose does not need to be keyword-dense to stay findable.
+
+There is no target-imposed length limit. `tools/lint-pack-descriptions.py` fails the
+build past a deliberately loose backstop, which exists only to stop runaway drift (the
+field once reached 1122 characters); it is not the quality bar. **This section is.** A
+description inside the backstop can still be bad, and a length check cannot tell —
+review against the shape and the table above.
+
 ---
 
 ## 3. Pack README standard

{agentbundle-0.29.5 → agentbundle-0.31.0}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,14 +1,14 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "cec0f7afd7a0bf61d7bedd9facd096b083cb7413679a6fbcd0af28d40bece58c",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "ff4bdc203affda0a2f41641c1155b3f4e90aade022e122999a82e7093e94d2ee",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
-    "packs/AGENTS.md": "861a029007741cd7645cdfcc018e5ac85cf218d332f6688115156c9c676381b8",
+    "packs/AGENTS.md": "9bfeda4069826e518a4f4fdae45bd40f4393c1c5aaf146149d3eb4aece30be83",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",
     "packs/_example/.apm/skills/example-skill/SKILL.md": "33be8cbf4b2c014a5a63e788b7d0b350ad8061c6c4b2579369a3e984135bf9f1",
     "packs/_example/.apm/skills/example-skill/evals/eval_queries.json": "f41ecda0834a22f3b4823c81ab02e58b0e4beba610e3b40c185579abff9cfeee",
-    "packs/_example/.claude-plugin/plugin.json": "d38c8456640d5e2f9296361f7e3e675e368ddd3eb22a6245267560f460155f41",
+    "packs/_example/.claude-plugin/plugin.json": "7f94084a56260eed225ec47ac82042fe9029c594557cca760a459885d03ccc26",
     "packs/_example/README.md": "ef130c9c1f97a75a07cc59fc55fc5b3bf71846dd2f06c3cddf5a1154023b6ef6",
-    "packs/_example/pack.toml": "94e2c7fd25d4d115858728c7ecb8f739adfd0f594b29596c106daba0791a4b94",
+    "packs/_example/pack.toml": "f19a0be9fca99a6a0e3ce2d5cd188bf98000f0a4f186954fb42a0c99c6859701",
     "profiles/AGENTS.md": "8950438d9e0f57c13613104c88c90b598b53196c91bfdced6d63e4e01b5e9254",
     "profiles/README.md": "a0b0268edc57fc575f7fea08f3363ba7da9f6e67dc4a0a6f8bd38c9668c97922",
     "profiles/_example/README.md": "164494df049ddce3e57cb44ed604cb3d39be0a6ec2072e609ea3fa4bbfc74c72",

{agentbundle-0.29.5 → agentbundle-0.31.0}/agentbundle/_data/catalogue-scaffold/packs/AGENTS.md

@@ -6,9 +6,11 @@ Read `packs/AGENTS.local.md` when present — it carries host-specific overrides
 ## Pack layout
 
 The pack is the ownership and test-execution boundary; `.apm/` is the runtime export boundary; a skill is the
-evaluation-fixture boundary. Tests go in `packs/<pack>/tests/`, never under `.apm/`; evals stay skill-local at
-`.apm/skills/<skill>/evals/` and project with the skill. `tools/lint-pack-test-boundary.py` enforces both across
-every pack, plus one pytest process per skill test dir. Shape: `docs/architecture/pack-layout.md`.
+evaluation-fixture boundary. Skill tests go in `packs/<pack>/tests/skills/<skill>/` and hook tests in
+`packs/<pack>/tests/hooks/` — never under `.apm/`, which adapters project verbatim into an installed tree.
+Evals stay skill-local at `.apm/skills/<skill>/evals/` and project with the skill. Run **one pytest process
+per skill test directory**: two skills may ship the same test basename, and a shared `sys.path` binds one
+skill's module for both suites and passes green.
 
 | Path | Purpose |
 |------|---------|
@@ -28,14 +30,13 @@ every pack, plus one pytest process per skill test dir. Shape: `docs/architectur
 
 ## Reserved authoring assets
 
-Any immediate child of the packs root whose name begins with `_` is a reserved authoring asset.
-Reserved directories are not catalogue payload — they do not appear in `list-packs`, are not
-installed, and are not included in packaged archives. See `packs/README.md`.
+Any immediate child of the packs root whose name begins with `_` is a reserved authoring asset: not
+catalogue payload, absent from `list-packs`, never installed or packaged. See `packs/README.md`.
 
 ## pack.toml schema map
 
-> The machine source of truth for pack.toml format is `contracts/pack.schema.json`.
-> The table below is a navigational summary; the JSON Schema is normative.
+> The normative source for pack.toml format is the `pack` JSON Schema that ships inside `agentbundle`;
+> `agentbundle catalogue lint --root .` validates against it. The table below is a navigational summary.
 
 | Table | Required fields | Notable optional fields |
 |-------|----------------|------------------------|
@@ -64,14 +65,14 @@ For CI pipeline orchestration — publication ordering, exit codes, JSON output
 
 ## Version bump rule
 
-Every **non-cosmetic** change to pack content requires a version bump in both:
-1. `pack.toml` → `[pack] version`
-2. `.claude-plugin/plugin.json` → `"version"`
+Every **non-cosmetic** change to pack content requires a version bump in **both** `pack.toml` →
+`[pack] version` and `.claude-plugin/plugin.json` → `"version"`.
 
 Which increment: **patch** for changed bodies/directives/conventions; **minor** for new primitives;
 **major** for removals. Never ride an unreleased version from another in-flight PR.
 
-Host-specific post-bump steps (changelog, marketplace regeneration) are in `packs/AGENTS.local.md`.
+Further post-bump steps (changelog, marketplace regeneration) are host-specific — see `AGENTS.local.md` if
+your catalogue has one.
 
 ## Self-hosting projection
 
@@ -80,52 +81,50 @@ projects them to every shipped adapter's layout. Never edit a projected output d
 
 On a dirty working tree: `agentbundle catalogue self-host --root . --write --force`.
 
-**Critical ordering:** when a session edits both seeds and non-seed pack sources (`.apm/**`,
-`pack.toml`), run self-host AFTER all edits — not between them.
+**Critical ordering:** when a session edits both seeds and non-seed pack sources (`.apm/**`, `pack.toml`),
+run self-host AFTER all edits — not between them.
 
 ## Claude plugin JSON format
 
-Each pack's `.claude-plugin/plugin.json` is validated against `contracts/plugin-manifest.schema.json`.
-Non-compliant manifests block publishing.
+Each pack's `.claude-plugin/plugin.json` is validated against the plugin-manifest JSON Schema that ships
+inside `agentbundle`; `agentbundle catalogue lint --root .` reports violations. Non-compliant manifests
+block publishing.
 
 **Required:** `name` (string), `version` (string matching `pack.toml`), `description` (string).
 
-**Allowed optional fields** — `skills`, `agents` (arrays of strings); `author` (`{name, email?}`);
-`license`, `homepage`, `repository`, `category`, `displayName` (strings); `keywords` (array);
-`source` (`{source, repo, branch, directory}`).
+**Allowed optional fields** — `skills`, `agents` (arrays of strings); `author` (`{name, email?}`); `license`,
+`homepage`, `repository`, `category`, `displayName` (strings); `keywords` (array); `source`
+(`{source, repo, branch, directory}`).
 
 `additionalProperties: false` — any unknown key fails validation.
 
 ## Authoring or editing a skill
 
-`README.md` states pack intent and the user journey it serves — not a contributor capability list.
-Edit `.apm/skills/<name>/SKILL.md`. Run self-host to project. Run
-`agentbundle catalogue lint --root . --deep` to confirm spec compliance.
+`README.md` states pack intent and the user journey it serves — not a contributor capability list. Edit
+`.apm/skills/<name>/SKILL.md`, run self-host to project, then `agentbundle catalogue lint --root . --deep`.
 
-Full authoring standards — frontmatter key whitelist, body structure, naming, three-tier dependency
-policy, and evals — live in [`guides/_shared/how-to/author-a-skill.md`](../guides/_shared/how-to/author-a-skill.md).
+Full authoring standards — frontmatter key whitelist, body structure, naming, three-tier dependency policy,
+evals — live in [`catalogue-authoring-standards.md`](../guides/_shared/reference/catalogue-authoring-standards.md).
 
 ## Eval coverage
 
 A non-cosmetic pack update must also update the pack's eval harness:
-- **Tier-A activation** — `evals/eval_queries.json` (~8–10 should-trigger + ~8–10 near-miss) and
-  a `[pack.evals]` block in `pack.toml` listing every user-triggered skill.
+- **Tier-A activation** — `evals/eval_queries.json` (~8–10 should-trigger + ~8–10 near-miss) and a
+  `[pack.evals]` block in `pack.toml` listing every user-triggered skill.
 - **Tier-4 LLM-judge rubric** — `evals/evals.json` for judgment/authoring skills.
 - **Tier-B-lite behavior check** — add an `expect` block to an `evals/evals.json` entry (non-destructive,
-  non-credentialed skills only). Four things that must be explicit to avoid format churn:
-  - Field name is **`files`** (not `fixture`): paths are relative to the **skill root**
-    (e.g. `"evals/files/sample.md"`), not relative to `evals/`. The runner seeds a temp workspace
-    with these files before invoking the skill.
+  non-credentialed skills only). Four things must be explicit, or the format churns:
+  - The field is **`files`**, not `fixture`, and its paths are relative to the **skill root**
+    (`"evals/files/sample.md"`) — not to `evals/`. The runner seeds a temp workspace with them first.
   - `expect.produces`: filenames the run must create in the workspace.
   - `expect.output_contains` / `expect.output_excludes`: substrings in captured output.
-  - **Your skill script must accept the workspace path** — via a `--fixture`/`--root` flag or by
-    treating CWD as the workspace — so the runner can confine writes and verify `produces`.
-  Full procedure: [`guides/_shared/how-to/author-a-skill.md`](../guides/_shared/how-to/author-a-skill.md).
+  - **Your skill script must accept the workspace path** — a `--fixture`/`--root` flag, or treat CWD as
+    the workspace — so the runner can confine writes and verify `produces`.
+  Full procedure: [`guides/_shared/reference/catalogue-authoring-standards.md`](../guides/_shared/reference/catalogue-authoring-standards.md).
 
 ## Windows-safe Python scripts
 
-Any script under `.apm/` that prints to stdout or stderr must include the UTF-8 reconfigure guard
-immediately after `import sys`, before any `print()` call:
+Any script under `.apm/` that prints to stdout or stderr must include the UTF-8 reconfigure guard immediately after `import sys`, before any `print()` call:
 
 ```python
 sys.stdout.reconfigure(encoding="utf-8", errors="strict")
@@ -145,6 +144,7 @@ Stubs in `plan.md` tasks must be `raise NotImplementedError  # STUB: ACn` — no
 
 ## Shipped pack content carries no internal-governance citations
 
-Anywhere under `packs/` — `.apm/**`, `pack.toml`, `README`/`JOURNEY`/`DESIGN`, `seeds/**` —
-never cite this catalogue's own governance: `RFC-0NNN`, `ADR-0NNN`, spec/plan or AC citations,
-internal doc paths. Keep the rule, drop the citation. Detail: `packs/AGENTS.local.md`.
+Anywhere under `packs/` — `.apm/**`, `pack.toml`, `README`/`JOURNEY`/`DESIGN`, `seeds/**` — never cite your
+catalogue's own governance: decision-record or proposal numbers, spec/plan or acceptance-criterion citations,
+or repository-only paths. Shipped content lands in someone else's tree, where each is a dead end. **Keep the
+rule, drop the citation** — state what the reader must do, in full.

{agentbundle-0.29.5 → agentbundle-0.31.0}/agentbundle/_data/catalogue-scaffold/packs/_example/pack.toml

@@ -1,7 +1,7 @@
 [pack]
 name            = "example-pack"
 version         = "0.1.0"
-description     = "A minimal example pack demonstrating the standard authoring layout."
+description     = "The skeleton to copy when you start a new pack."
 display_name    = "Example Pack"
 categories      = ["productivity"]
 keywords        = ["example", "template"]

{agentbundle-0.29.5 → agentbundle-0.31.0}/agentbundle/_data/install-marker.py

@@ -1,9 +1,13 @@
 """Canonical stdlib-only install-marker writer for the Claude-plugins and APM install routes.
 
 This script is invoked by a ``SessionStart`` hook derived by ``agentbundle build``
-into every pack's projected output:
-  - ``dist/claude-plugins/<pack>/.claude-plugin/plugin.json``  — claude-plugins route
-  - ``dist/apm/<pack>/.apm/hooks/install-marker.json``         — APM route
+into each pack's projected output:
+  - ``dist/claude-plugins/<pack>/.claude-plugin/plugin.json``  — claude-plugins
+    route, for user-capable packs only (a plugin's code lands in the adopter's
+    global cache, so a pack whose ``allowed-scopes`` omits ``user`` is not
+    projected onto this route at all)
+  - ``dist/apm/<pack>/.apm/hooks/install-marker.json``         — APM route,
+    every pack
 
 It detects first-install-or-update and writes a ``[[packs-installed]]`` entry
 to the scope-correct ``.adapt-install-marker.toml`` file so the existing core
@@ -213,11 +217,66 @@ def _assert_portable_name(component: str) -> None:
 # ---------------------------------------------------------------------------
 
 
+# Settings files are read under an adopter's ``${CLAUDE_PROJECT_DIR}``, whose
+# contents a cloned repo controls. Bound the read itself — measuring after
+# `read_text()` has already pulled the whole file in is no bound at all.
+_SETTINGS_READ_CAP = 1_048_576  # 1 MiB
+
+
+def _plugin_marketplace(
+    plugin_root: pathlib.Path,
+    plugin_name: str,
+) -> "str | None":
+    """Return the marketplace this pack was installed from, or ``None``.
+
+    The Claude-plugins client installs into
+    ``<config>/plugins/cache/<marketplace>/<plugin>/<version>``, so the pack
+    can read its own marketplace identity back out of ``${CLAUDE_PLUGIN_ROOT}``.
+    Verified against Claude Code 2.1.223.
+
+    Returns ``None`` when ``plugin_root`` does not have that shape. The caller
+    then matches on bare pack name alone — a layout we do not recognise must
+    degrade to the historical behaviour, not to "never opted in" (that is the
+    very failure this function's caller exists to fix).
+    """
+    parts = plugin_root.parts
+    if len(parts) < 4:
+        return None
+    if parts[-4] != "cache" or parts[-2] != plugin_name:
+        return None
+    return parts[-3] or None
+
+
+def _entry_matches(
+    entry: str,
+    plugin_name: str,
+    marketplace: "str | None",
+) -> bool:
+    """Does one ``enabledPlugins`` identifier name *this* pack?
+
+    Current clients write a qualified ``name@marketplace``; older ones wrote a
+    bare ``name``. A qualified identifier must agree on *both* halves whenever
+    we know our own marketplace, so another vendor's ``core@other-marketplace``
+    does not opt in a ``core`` that came from somewhere else.
+    """
+    name, sep, entry_marketplace = entry.strip().partition("@")
+    if name.strip() != plugin_name:
+        return False
+    if not sep:
+        # Bare name — the identifier makes no marketplace claim to check.
+        return True
+    if marketplace is None:
+        # Our own identity is unknown; the name is all there is to compare.
+        return True
+    return entry_marketplace.strip() == marketplace
+
+
 def _detect_origin(
     *,
     plugin_name: str,
     home: pathlib.Path,
     project_dir: pathlib.Path | None,
+    marketplace: "str | None",
 ) -> str | None:
     """Walk the three ``enabledPlugins`` settings files in precedence order.
 
@@ -226,9 +285,17 @@ def _detect_origin(
     (pack is not enabled at any scope).
 
     Precedence: local → project → user (most-specific wins).
-    Missing file, malformed JSON, absent ``enabledPlugins`` key, or
-    ``enabledPlugins`` present but not a JSON array are each treated as
-    "not opted in at that scope" and fall through.
+
+    ``enabledPlugins`` carries two shapes. Current clients write an **object**
+    keyed by plugin identifier whose boolean value is the enabled state — only
+    ``true`` counts as opted in, since ``false`` is an adopter who deliberately
+    disabled the pack. Older clients wrote a **JSON array** of identifiers;
+    both are accepted.
+
+    Every other outcome is "not opted in at that scope" and falls through: a
+    missing file, a non-regular path, a file past ``_SETTINGS_READ_CAP``,
+    undecodable bytes, malformed JSON, an absent ``enabledPlugins`` key, or a
+    value of any other type. A hostile settings file must never raise.
     """
     candidates: list[tuple[str, pathlib.Path]] = []
 
@@ -239,32 +306,38 @@ def _detect_origin(
     candidates.append(("user", home / ".claude" / "settings.json"))
 
     for origin, settings_path in candidates:
-        if not settings_path.exists():
+        # `.is_file()` where the old code used `.exists()`: a FIFO exists, and
+        # opening one for reading blocks until a writer appears. A character
+        # device such as /dev/zero exists too, and reads forever.
+        if not settings_path.is_file():
             continue
         try:
-            read_text = settings_path.read_text(encoding="utf-8")
+            with settings_path.open("rb") as fh:
+                blob = fh.read(_SETTINGS_READ_CAP + 1)
         except OSError:
             continue
-        # Cap read size to 1 MiB to guard against DoS via giant file.
-        if len(read_text) > 1_048_576:
+        if len(blob) > _SETTINGS_READ_CAP:
             continue
         try:
-            raw = json.loads(read_text)
-        except (json.JSONDecodeError, OSError):
+            # `json.loads` decodes UTF-8 itself; undecodable bytes raise
+            # UnicodeDecodeError and malformed JSON raises JSONDecodeError,
+            # both subclasses of ValueError.
+            raw = json.loads(blob)
+        except ValueError:
             continue
         if not isinstance(raw, dict):
             continue
         enabled = raw.get("enabledPlugins")
-        if not isinstance(enabled, list):
+        if isinstance(enabled, dict):
+            entries: list = [key for key, value in enabled.items() if value is True]
+        elif isinstance(enabled, list):
+            entries = enabled
+        else:
             continue
-        # Check whether this pack is in the list; compare by name prefix
-        # since installed plugins may appear as "name@marketplace-url".
-        for entry in enabled:
-            if not isinstance(entry, str):
-                continue
-            # Match by pack name as a prefix component (before '@').
-            entry_name = entry.split("@")[0].strip()
-            if entry_name == plugin_name:
+        for entry in entries:
+            if isinstance(entry, str) and _entry_matches(
+                entry, plugin_name, marketplace
+            ):
                 return origin
 
     return None
@@ -837,6 +910,7 @@ def _main_claude_plugins(args: argparse.Namespace) -> int:
         plugin_name=pack_name,
         home=home,
         project_dir=project_dir,
+        marketplace=_plugin_marketplace(plugin_root, pack_name),
     )
 
     if origin is None: