claude-dev-env 8.51.3 → 8.52.0

package/bin/install-pstack-plugin.mjs

@@ -15,7 +15,7 @@ export const PSTACK_PLUGIN_SPEC = Object.freeze({
     label: 'Pstack',
     marketplaceRepository: PSTACK_MARKETPLACE_REPOSITORY,
     marketplaceName: PSTACK_MARKETPLACE_NAME,
-    marketplaceAddArguments: Object.freeze([]),
+    sparsePaths: Object.freeze([]),
     pluginIdentifier: PSTACK_PLUGIN_IDENTIFIER,
     hosts: PSTACK_PLUGIN_HOSTS,
     optOutFlag: PSTACK_PLUGIN_OPT_OUT_FLAG,
@@ -27,13 +27,25 @@ export const USAGE_WRAPUP_PLUGIN_SPEC = Object.freeze({
     label: 'Usage-wrapup',
     marketplaceRepository: 'jl-cmd/claude-dev-env',
     marketplaceName: 'claude-dev-env',
-    marketplaceAddArguments: Object.freeze(['--sparse', '.claude-plugin', 'packages/usage-wrapup']),
+    sparsePaths: Object.freeze(['.claude-plugin', 'packages/usage-wrapup']),
     pluginIdentifier: 'usage-wrapup@claude-dev-env',
     hosts: Object.freeze(['claude']),
     optOutFlag: '--no-usage-wrapup',
     optOutVariable: 'CDE_INSTALL_USAGE_WRAPUP',
 });
 
+export const SUBAGENT_MODELS_PLUGIN_SPEC = Object.freeze({
+    name: 'subagent-models',
+    label: 'Subagent-models',
+    marketplaceRepository: 'jl-cmd/claude-dev-env',
+    marketplaceName: 'claude-dev-env',
+    sparsePaths: Object.freeze(['.claude-plugin', 'packages/subagent-models']),
+    pluginIdentifier: 'subagent-models@claude-dev-env',
+    hosts: Object.freeze(['claude']),
+    optOutFlag: '--no-subagent-models',
+    optOutVariable: 'CDE_INSTALL_SUBAGENT_MODELS',
+});
+
 const HOST_DEFINITIONS = Object.freeze({
     claude: Object.freeze({
         executable: 'claude',
@@ -55,42 +67,60 @@ const HOST_DEFINITIONS = Object.freeze({
 });
 
 /**
- * Read the marketplace and plugin commands one host installs a plugin with.
+ * Read the marketplace and plugin commands one host installs a set of plugins with.
  *
- * The removal commands run first and take out the installed plugin, its
- * cached versions, and the marketplace clone, so the install commands that
- * follow fetch the newest published version into an empty slot.
+ * Every plugin in the set comes from one marketplace. Removing a marketplace
+ * uninstalls each plugin it supplied, so the plan removes and adds that
+ * marketplace once for the whole set. The removal commands run first and take
+ * out each installed plugin, its cached versions, and the marketplace clone,
+ * so the install commands that follow fetch the newest published version into
+ * an empty slot.
  *
  * Claude Code and Codex publish a marketplace under different plugin verbs, so
  * the install verb belongs to the host and the marketplace and identifier
  * belong to the plugin spec. A spec whose marketplace is a large repository
- * passes `--sparse .claude-plugin` among its marketplace add arguments, so the
- * clone holds only the catalog and stays clear of Windows path-length limits.
+ * names its sparse paths, and the one marketplace add checks out every path
+ * the set names, so the clone holds only the catalog and those plugin folders
+ * and stays clear of Windows path-length limits.
  *
- * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
- * @param {string} host A host the spec names, `claude` or `codex`.
+ * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
+ * @param {string} host A host every spec names, `claude` or `codex`.
  * @returns {{executable: string, executableVariable: string, homeVariable: string,
  *   removalCommands: ReadonlyArray<ReadonlyArray<string>>,
  *   commands: ReadonlyArray<ReadonlyArray<string>>}} The host's install plan.
  */
-export function marketplacePluginPlan(spec, host) {
+export function marketplacePluginsPlan(allSpecs, host) {
     const hostDefinition = HOST_DEFINITIONS[host];
-    if (!hostDefinition || !spec.hosts.includes(host)) {
+    for (const eachSpec of allSpecs) {
+        if (!hostDefinition || !eachSpec.hosts.includes(host)) {
+            throw new Error(
+                `Unsupported ${eachSpec.name} plugin host ${host}: this installer knows ${eachSpec.hosts.join(', ')}.`,
+            );
+        }
+    }
+    const [firstSpec] = allSpecs;
+    const otherMarketplaceSpec = allSpecs.find(
+        eachSpec => eachSpec.marketplaceRepository !== firstSpec.marketplaceRepository,
+    );
+    if (otherMarketplaceSpec) {
         throw new Error(
-            `Unsupported ${spec.name} plugin host ${host}: this installer knows ${spec.hosts.join(', ')}.`,
+            `${otherMarketplaceSpec.name} comes from ${otherMarketplaceSpec.marketplaceRepository}, `
+            + `and one plan installs from ${firstSpec.marketplaceRepository} only.`,
         );
     }
+    const allSparsePaths = [...new Set(allSpecs.flatMap(eachSpec => eachSpec.sparsePaths))];
+    const sparseArguments = allSparsePaths.length > 0 ? ['--sparse', ...allSparsePaths] : [];
     return {
         executable: hostDefinition.executable,
         executableVariable: hostDefinition.executableVariable,
         homeVariable: hostDefinition.homeVariable,
         removalCommands: [
-            ['plugin', hostDefinition.uninstallVerb, spec.pluginIdentifier],
-            ['plugin', 'marketplace', 'remove', spec.marketplaceName],
+            ...allSpecs.map(eachSpec => ['plugin', hostDefinition.uninstallVerb, eachSpec.pluginIdentifier]),
+            ['plugin', 'marketplace', 'remove', firstSpec.marketplaceName],
         ],
         commands: [
-            ['plugin', 'marketplace', 'add', spec.marketplaceRepository, ...spec.marketplaceAddArguments],
-            ['plugin', hostDefinition.installVerb, spec.pluginIdentifier],
+            ['plugin', 'marketplace', 'add', firstSpec.marketplaceRepository, ...sparseArguments],
+            ...allSpecs.map(eachSpec => ['plugin', hostDefinition.installVerb, eachSpec.pluginIdentifier]),
         ],
     };
 }
@@ -198,30 +228,31 @@ export function removeOrphanedPluginVersions(versionsDirectory) {
     return removedPaths;
 }
 
-function absentHostOutcome(spec, host, executable) {
+function absentHostOutcome(allSpecs, host, executable) {
+    const pluginNames = allSpecs.map(eachSpec => eachSpec.name).join(', ');
     return {
         host,
         executable,
         status: 'skipped',
-        warning: `${executable} is not on PATH, so ${spec.name} was not installed for ${host}.`,
+        warning: `${executable} is not on PATH, so ${pluginNames} was not installed for ${host}.`,
     };
 }
 
-function installForHost(spec, host, homeDirectory, environment, runCommand) {
-    const plan = marketplacePluginPlan(spec, host);
+function installForHost(allSpecs, host, homeDirectory, environment, runCommand) {
+    const plan = marketplacePluginsPlan(allSpecs, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
     for (const commandArguments of plan.removalCommands) {
         const outcome = runCommand(executable, [...commandArguments], {
             environment: commandEnvironment,
         });
-        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(spec, host, executable);
+        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
     }
     for (const commandArguments of plan.commands) {
         const outcome = runCommand(executable, [...commandArguments], {
             environment: commandEnvironment,
         });
-        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(spec, host, executable);
+        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
         if (outcome.status !== 0 || outcome.error) {
             const detail = firstLine(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
             return {
@@ -234,17 +265,19 @@ function installForHost(spec, host, homeDirectory, environment, runCommand) {
     }
     const hostDefinition = HOST_DEFINITIONS[host];
     if (hostDefinition.orphanedVersionsDirectory && homeDirectory) {
-        removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, spec));
+        for (const eachSpec of allSpecs) {
+            removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, eachSpec));
+        }
     }
     return { host, executable, status: 'installed', warning: null };
 }
 
 /**
- * Install one plugin from its marketplace into each host's own home.
+ * Install a set of plugins from one marketplace into each host's own home.
  *
- * Each host first removes the plugin and its marketplace, so an older
- * version never survives beside the new one. A removal that finds nothing
- * to remove exits non-zero on a fresh home, and the install goes on.
+ * Each host first removes every plugin in the set and then the marketplace,
+ * so an older version never survives beside the new one. A removal that finds
+ * nothing to remove exits non-zero on a fresh home, and the install goes on.
  *
  * Each host is one member of the batch. A host without its command-line tool
  * is skipped and a host whose command fails is reported, so the rules, hooks,
@@ -253,22 +286,24 @@ function installForHost(spec, host, homeDirectory, environment, runCommand) {
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
  * skipped.
  *
- * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
+ * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {object} [options] Install targets.
  * @param {string} [options.claudeRoot] The managed Claude root to install into.
  * @param {string} [options.codexHome] The Codex home to install into.
- * @param {string[]} [options.hosts] The hosts to install. Defaults to the spec's hosts.
+ * @param {string[]} [options.hosts] The hosts to install. Defaults to the hosts every spec names.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
  * @param {object} [dependencies] Seams for the command runner.
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
  */
-export function installMarketplacePlugin(spec, options = {}, dependencies = {}) {
+export function installMarketplacePlugins(allSpecs, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
     const runCommand = dependencies.runCommand ?? runHostCommand;
     const homeDirectories = { claude: options.claudeRoot, codex: options.codexHome };
-    const hosts = options.hosts ?? spec.hosts;
+    const hosts = options.hosts ?? allSpecs[0].hosts.filter(
+        eachHost => allSpecs.every(eachSpec => eachSpec.hosts.includes(eachHost)),
+    );
     const hostOutcomes = hosts.map(host => installForHost(
-        spec,
+        allSpecs,
         host,
         homeDirectories[host],
         environment,

package/bin/install-pstack-plugin.test.mjs

@@ -8,10 +8,11 @@ import {
     PSTACK_PLUGIN_HOSTS,
     PSTACK_PLUGIN_IDENTIFIER,
     PSTACK_PLUGIN_SPEC,
+    SUBAGENT_MODELS_PLUGIN_SPEC,
     USAGE_WRAPUP_PLUGIN_SPEC,
     hostCommandInvocation,
-    installMarketplacePlugin,
-    marketplacePluginPlan,
+    installMarketplacePlugins,
+    marketplacePluginsPlan,
     removeOrphanedPluginVersions,
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
@@ -36,7 +37,7 @@ const ROOTS = Object.freeze({
 const WINDOWS_ENVIRONMENT = Object.freeze({ ComSpec: 'C:\\Windows\\system32\\cmd.exe' });
 
 test('the Claude plan carries the two documented plugin commands', () => {
-    const plan = marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'claude');
+    const plan = marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'claude');
     assert.equal(plan.executable, 'claude');
     assert.deepEqual(plan.commands, [
         ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
@@ -45,7 +46,7 @@ test('the Claude plan carries the two documented plugin commands', () => {
 });
 
 test('the Codex plan adds the plugin with the Codex verb', () => {
-    const plan = marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'codex');
+    const plan = marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'codex');
     assert.equal(plan.executable, 'codex');
     assert.deepEqual(plan.commands, [
         ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
@@ -54,13 +55,13 @@ test('the Codex plan adds the plugin with the Codex verb', () => {
 });
 
 test('an unsupported host names the hosts this installer knows', () => {
-    assert.throws(() => marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'cursor'), /cursor/);
+    assert.throws(() => marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'cursor'), /cursor/);
     assert.deepEqual(PSTACK_PLUGIN_HOSTS, ['claude', 'codex']);
 });
 
 test('each host installs into the managed root this run wrote', () => {
     const runner = recordingRunner();
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
         ['claude', 'plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
@@ -77,11 +78,11 @@ test('each host installs into the managed root this run wrote', () => {
 });
 
 test('each host removes the installed plugin and marketplace before it installs', () => {
-    assert.deepEqual(marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'claude').removalCommands, [
+    assert.deepEqual(marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'claude').removalCommands, [
         ['plugin', 'uninstall', PSTACK_PLUGIN_IDENTIFIER],
         ['plugin', 'marketplace', 'remove', 'pstack-claude'],
     ]);
-    assert.deepEqual(marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'codex').removalCommands, [
+    assert.deepEqual(marketplacePluginsPlan([PSTACK_PLUGIN_SPEC], 'codex').removalCommands, [
         ['plugin', 'remove', PSTACK_PLUGIN_IDENTIFIER],
         ['plugin', 'marketplace', 'remove', 'pstack-claude'],
     ]);
@@ -92,7 +93,7 @@ test('a removal that finds nothing installed still lets the install run', () =>
         commandArguments.includes('uninstall') || commandArguments.includes('remove')
             ? { status: 1, stderr: 'not installed' }
             : { status: 0, stderr: '' }));
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, { ...ROOTS, hosts: ['claude'] }, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(runner.calls.at(-1).commandArguments, ['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER]);
 });
@@ -101,7 +102,7 @@ test('an absent host command skips that host and leaves the other installed', ()
     const runner = recordingRunner((executable) => (executable === 'codex'
         ? { status: null, error: Object.assign(new Error('spawn codex ENOENT'), { code: 'ENOENT' }) }
         : { status: 0, stderr: '' }));
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.hosts.find(host => host.host === 'claude').status, 'installed');
     const codex = outcome.hosts.find(host => host.host === 'codex');
     assert.equal(codex.status, 'skipped');
@@ -114,7 +115,7 @@ test('a failing command reports that host and still installs the next one', () =
         executable === 'claude' && commandArguments[2] === 'add'
             ? { status: 1, stderr: 'marketplace unreachable' }
             : { status: 0, stderr: '' }));
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.status, 'failed');
     const claude = outcome.hosts.find(host => host.host === 'claude');
     assert.equal(claude.status, 'failed');
@@ -126,8 +127,8 @@ test('a failing command reports that host and still installs the next one', () =
 
 test('an executable override replaces the host command for that host only', () => {
     const runner = recordingRunner();
-    installMarketplacePlugin(
-        PSTACK_PLUGIN_SPEC,
+    installMarketplacePlugins(
+        [PSTACK_PLUGIN_SPEC],
         { ...ROOTS, environment: { CDE_CODEX_EXECUTABLE: '/opt/codex/bin/codex' } },
         runner,
     );
@@ -146,7 +147,7 @@ test('the opt-out flag and variable both turn the step off', () => {
 
 test('a selected host list installs only that host', () => {
     const runner = recordingRunner();
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, { ...ROOTS, hosts: ['codex'] }, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['codex'] }, runner);
     assert.deepEqual(outcome.hosts.map(host => host.host), ['codex']);
     assert.deepEqual([...new Set(runner.calls.map(call => call.executable))], ['codex']);
 });
@@ -199,7 +200,7 @@ test("cmd.exe's command-not-found exit code reads as an absent host, not a failu
             stderr: "'codex' is not recognized as an internal or external command,\noperable program or batch file.",
         }
         : { status: 0, stderr: '' }));
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, runner);
     const codex = outcome.hosts.find(host => host.host === 'codex');
     assert.equal(codex.status, 'skipped');
     assert.equal(outcome.status, 'installed');
@@ -208,13 +209,13 @@ test("cmd.exe's command-not-found exit code reads as an absent host, not a failu
 
 test('a non-zero exit that is not command-not-found still reads as a failure', () => {
     const runner = recordingRunner(() => ({ status: 9009, stderr: 'the marketplace rejected the catalog' }));
-    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, { ...ROOTS, hosts: ['claude'] }, runner);
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], { ...ROOTS, hosts: ['claude'] }, runner);
     assert.equal(outcome.hosts[0].status, 'failed');
     assert.match(outcome.hosts[0].warning, /rejected the catalog/);
 });
 
 test('the usage-wrapup plan adds this repository marketplace and installs the plugin on Claude', () => {
-    const plan = marketplacePluginPlan(USAGE_WRAPUP_PLUGIN_SPEC, 'claude');
+    const plan = marketplacePluginsPlan([USAGE_WRAPUP_PLUGIN_SPEC], 'claude');
     assert.equal(plan.executable, 'claude');
     assert.equal(plan.homeVariable, 'CLAUDE_CONFIG_DIR');
     assert.deepEqual(plan.commands, [
@@ -225,12 +226,12 @@ test('the usage-wrapup plan adds this repository marketplace and installs the pl
 
 test('usage-wrapup is a Claude-only plugin and refuses a Codex plan', () => {
     assert.deepEqual(USAGE_WRAPUP_PLUGIN_SPEC.hosts, ['claude']);
-    assert.throws(() => marketplacePluginPlan(USAGE_WRAPUP_PLUGIN_SPEC, 'codex'), /usage-wrapup plugin host codex/);
+    assert.throws(() => marketplacePluginsPlan([USAGE_WRAPUP_PLUGIN_SPEC], 'codex'), /usage-wrapup plugin host codex/);
 });
 
 test('installing usage-wrapup runs only the Claude commands, inside the managed Claude root', () => {
     const runner = recordingRunner();
-    const outcome = installMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ROOTS, runner);
+    const outcome = installMarketplacePlugins([USAGE_WRAPUP_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(outcome.hosts.map(host => host.host), ['claude']);
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
@@ -249,7 +250,7 @@ test('an absent claude command skips usage-wrapup and names the plugin in the wa
         status: null,
         error: Object.assign(new Error('spawn claude ENOENT'), { code: 'ENOENT' }),
     }));
-    const outcome = installMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ROOTS, runner);
+    const outcome = installMarketplacePlugins([USAGE_WRAPUP_PLUGIN_SPEC], ROOTS, runner);
     assert.equal(outcome.status, 'skipped');
     assert.match(outcome.warning, /usage-wrapup was not installed for claude/);
 });
@@ -268,16 +269,60 @@ test('the usage-wrapup opt-out flag and variable turn off only usage-wrapup', ()
     );
 });
 
-test('the repository marketplace lists usage-wrapup from its package folder in this repository', () => {
-    const marketplace = JSON.parse(readFileSync(
-        new URL('../../../.claude-plugin/marketplace.json', import.meta.url),
-        'utf8',
-    ));
-    const [pluginName, marketplaceName] = USAGE_WRAPUP_PLUGIN_SPEC.pluginIdentifier.split('@');
-    assert.equal(marketplace.name, marketplaceName);
-    const entry = marketplace.plugins.find(plugin => plugin.name === pluginName);
-    assert.ok(entry, `the marketplace lists ${pluginName}`);
-    assert.equal(entry.source, './packages/usage-wrapup');
+for (const [spec, packageFolder] of [
+    [USAGE_WRAPUP_PLUGIN_SPEC, './packages/usage-wrapup'],
+    [SUBAGENT_MODELS_PLUGIN_SPEC, './packages/subagent-models'],
+]) {
+    test(`the repository marketplace lists ${spec.name} from its package folder in this repository`, () => {
+        const marketplace = JSON.parse(readFileSync(
+            new URL('../../../.claude-plugin/marketplace.json', import.meta.url),
+            'utf8',
+        ));
+        const [pluginName, marketplaceName] = spec.pluginIdentifier.split('@');
+        assert.equal(marketplace.name, marketplaceName);
+        const entry = marketplace.plugins.find(plugin => plugin.name === pluginName);
+        assert.ok(entry, `the marketplace lists ${pluginName}`);
+        assert.equal(entry.source, packageFolder);
+        assert.ok(spec.sparsePaths.includes(packageFolder.slice(2)), `the sparse checkout holds ${packageFolder}`);
+    });
+}
+
+test('should remove and add the shared marketplace once when installing usage-wrapup and subagent-models together', () => {
+    const runner = recordingRunner();
+    const outcome = installMarketplacePlugins([USAGE_WRAPUP_PLUGIN_SPEC, SUBAGENT_MODELS_PLUGIN_SPEC], ROOTS, runner);
+    assert.equal(outcome.status, 'installed');
+    assert.deepEqual(outcome.hosts.map(host => host.host), ['claude']);
+    assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
+        ['claude', 'plugin', 'uninstall', 'usage-wrapup@claude-dev-env'],
+        ['claude', 'plugin', 'uninstall', 'subagent-models@claude-dev-env'],
+        ['claude', 'plugin', 'marketplace', 'remove', 'claude-dev-env'],
+        [
+            'claude', 'plugin', 'marketplace', 'add', 'jl-cmd/claude-dev-env',
+            '--sparse', '.claude-plugin', 'packages/usage-wrapup', 'packages/subagent-models',
+        ],
+        ['claude', 'plugin', 'install', 'usage-wrapup@claude-dev-env'],
+        ['claude', 'plugin', 'install', 'subagent-models@claude-dev-env'],
+    ]);
+});
+
+test('should refuse one plan for plugins from two marketplaces', () => {
+    assert.throws(
+        () => marketplacePluginsPlan([PSTACK_PLUGIN_SPEC, SUBAGENT_MODELS_PLUGIN_SPEC], 'claude'),
+        /subagent-models comes from jl-cmd\/claude-dev-env/,
+    );
+});
+
+test('should turn off only subagent-models with its opt-out flag or variable', () => {
+    assert.equal(shouldInstallMarketplacePlugin(SUBAGENT_MODELS_PLUGIN_SPEC, [], {}), true);
+    assert.equal(shouldInstallMarketplacePlugin(SUBAGENT_MODELS_PLUGIN_SPEC, ['--no-subagent-models'], {}), false);
+    assert.equal(
+        shouldInstallMarketplacePlugin(SUBAGENT_MODELS_PLUGIN_SPEC, [], { CDE_INSTALL_SUBAGENT_MODELS: '0' }),
+        false,
+    );
+    assert.equal(
+        shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ['--no-subagent-models'], { CDE_INSTALL_SUBAGENT_MODELS: '0' }),
+        true,
+    );
 });
 
 test('a clean install deletes the orphaned pstack versions and keeps the installed one', () => {
@@ -286,8 +331,8 @@ test('a clean install deletes the orphaned pstack versions and keeps the install
     mkdirSync(join(versionsDirectory, '0.9.55'), { recursive: true });
     writeFileSync(join(versionsDirectory, '0.9.55', '.orphaned_at'), '1');
     mkdirSync(join(versionsDirectory, '0.9.64'), { recursive: true });
-    const outcome = installMarketplacePlugin(
-        PSTACK_PLUGIN_SPEC,
+    const outcome = installMarketplacePlugins(
+        [PSTACK_PLUGIN_SPEC],
         { claudeRoot, hosts: ['claude'], environment: {} },
         recordingRunner(),
     );

package/bin/install.agents-home.test.mjs

@@ -52,6 +52,7 @@ function runInstaller(homeDirectory, extraArguments, environmentOverrides = {})
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/bin/install.codex-rules.test.mjs

@@ -58,6 +58,7 @@ function runInstaller(homeDirectory, extraArguments) {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -87,6 +88,7 @@ function scanTextWithProductionPiiScanner(scannedText) {
                     ...process.env,
                     CDE_INSTALL_PSTACK: '0',
                     CDE_INSTALL_USAGE_WRAPUP: '0',
+                    CDE_INSTALL_SUBAGENT_MODELS: '0',
                     PYTHONPATH: BLOCKING_HOOKS_DIRECTORY,
                     CLAUDE_LOCAL_IDENTITY_PATH: join(
                         temporaryDirectory,

package/bin/install.cursor-rules.test.mjs

@@ -33,6 +33,7 @@ function runInstaller(homeDirectory, extraArguments, environmentOverrides = {})
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             CODEX_HOME: join(homeDirectory, '.codex'),

package/bin/install.mjs

@@ -49,8 +49,9 @@ import {
 } from './install-constants.mjs';
 import {
     PSTACK_PLUGIN_SPEC,
+    SUBAGENT_MODELS_PLUGIN_SPEC,
     USAGE_WRAPUP_PLUGIN_SPEC,
-    installMarketplacePlugin,
+    installMarketplacePlugins,
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
@@ -407,17 +408,19 @@ export function pythonFileAndPrefixArguments(pythonCommand) {
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome.
  */
 export function installPstackPluginForHosts() {
-    return installMarketplacePlugin(PSTACK_PLUGIN_SPEC, {
+    return installMarketplacePlugins([PSTACK_PLUGIN_SPEC], {
         claudeRoot: CLAUDE_HOME,
         codexHome: INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
     });
 }
 
-function printPluginHostOutcomes(spec, pluginOutcome) {
-    for (const eachHost of pluginOutcome.hosts) {
-        console.log(eachHost.warning
-            ? `  ${spec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
-            : `  ${spec.label} (${eachHost.host}): ${eachHost.status}`);
+function printPluginHostOutcomes(allSpecs, pluginOutcome) {
+    for (const eachSpec of allSpecs) {
+        for (const eachHost of pluginOutcome.hosts) {
+            console.log(eachHost.warning
+                ? `  ${eachSpec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
+                : `  ${eachSpec.label} (${eachHost.host}): ${eachHost.status}`);
+        }
     }
 }
 
@@ -2890,14 +2893,16 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
                 console.log(`  \u2713 ${skillLoadGuidancePath} (Codex skill-load line)`);
             }
         }
-        printPluginHostOutcomes(PSTACK_PLUGIN_SPEC, pstackPlugin);
+        printPluginHostOutcomes([PSTACK_PLUGIN_SPEC], pstackPlugin);
     }
-    if (!selectedGroups && shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC)) {
-        const usageWrapupPlugin = installMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, {
+    const allRepositoryPluginSpecs = [USAGE_WRAPUP_PLUGIN_SPEC, SUBAGENT_MODELS_PLUGIN_SPEC]
+        .filter(eachSpec => shouldInstallMarketplacePlugin(eachSpec));
+    if (!selectedGroups && allRepositoryPluginSpecs.length > 0) {
+        const repositoryPlugins = installMarketplacePlugins(allRepositoryPluginSpecs, {
             claudeRoot: CLAUDE_HOME,
         });
-        summary.usageWrapupPlugin = usageWrapupPlugin;
-        printPluginHostOutcomes(USAGE_WRAPUP_PLUGIN_SPEC, usageWrapupPlugin);
+        summary.repositoryPlugins = repositoryPlugins;
+        printPluginHostOutcomes(allRepositoryPluginSpecs, repositoryPlugins);
     }
     if (!selectedGroups) {
         const packageGuidancePath = writeCodexPackageGuidance(
@@ -3412,6 +3417,7 @@ Usage:
   npx ${PACKAGE_NAME} --profiles A,B  Install into each selected profile (one ownership manifest per target)
   npx ${PACKAGE_NAME} --no-pstack  Full install without the pstack plugin (also CDE_INSTALL_PSTACK=0)
   npx ${PACKAGE_NAME} --no-usage-wrapup  Full install without the usage-wrapup plugin (also CDE_INSTALL_USAGE_WRAPUP=0)
+  npx ${PACKAGE_NAME} --no-subagent-models  Full install without the subagent-models plugin (also CDE_INSTALL_SUBAGENT_MODELS=0)
   npx ${PACKAGE_NAME} --uninstall  Remove installed files from the selected root
   npx ${PACKAGE_NAME} --help       Show this help
 

package/bin/install.prune.test.mjs

@@ -261,6 +261,7 @@ function resolveInstallerInvocation(homeDirectory) {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/bin/install.question-presentation.test.mjs

@@ -24,6 +24,7 @@ function installInScratchHome(homeDirectory, argumentsList = [], extraEnvironmen
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             CODEX_HOME: join(homeDirectory, '.codex'),
@@ -179,6 +180,7 @@ test('a successful pstack install retains its skill block and gains the question
     const installation = installInScratchHome(homeDirectory, [], {
         CDE_INSTALL_PSTACK: '1',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         CDE_CODEX_EXECUTABLE: commandPath,
         CDE_CLAUDE_EXECUTABLE: commandPath,
     });
@@ -206,6 +208,7 @@ test('enabling pstack after a pstack-off install preserves question guidance', (
     const secondInstallation = installInScratchHome(homeDirectory, [], {
         CDE_INSTALL_PSTACK: '1',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         CDE_CODEX_EXECUTABLE: commandPath,
         CDE_CLAUDE_EXECUTABLE: commandPath,
     });
@@ -234,6 +237,7 @@ test('a failed pstack transition restores question-only guidance and removes its
     const failedInstallation = installInScratchHome(homeDirectory, [], {
         CDE_INSTALL_PSTACK: '1',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         CDE_CODEX_EXECUTABLE: commandPath,
         CDE_CLAUDE_EXECUTABLE: commandPath,
         CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',

package/bin/install.settings-defaults.test.mjs

@@ -58,6 +58,7 @@ function runInstallerInSandbox(sandboxHome, installerArguments = []) {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             HOME: sandboxHome,
             USERPROFILE: sandboxHome,
             GIT_CONFIG_GLOBAL: gitConfigGlobal,
@@ -257,9 +258,16 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
     }
 });
 
-test('package settings.json publishes the advisor model default', () => {
+test('package settings.json publishes the advisor model and auto mode defaults', () => {
     const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
-    assert.deepEqual(settingsDefaultsFromPackageSettings(packageSettings), { advisorModel: 'fable' });
+    const settingsDefaults = settingsDefaultsFromPackageSettings(packageSettings);
+    assert.deepEqual(Object.keys(settingsDefaults).sort(), ['advisorModel', 'autoMode']);
+    assert.equal(settingsDefaults.advisorModel, 'fable');
+    const [firstAllowRule, ...allCustomAllowRules] = settingsDefaults.autoMode.allow;
+    assert.equal(firstAllowRule, '$defaults');
+    assert.equal(allCustomAllowRules.length, 2);
+    assert.match(allCustomAllowRules[0], /npx claude-dev-env@latest --update/);
+    assert.match(allCustomAllowRules[1], /claude-dev-env repository/);
 });
 
 test('a missing default is added and a user-set value is kept', () => {

package/bin/install.shared-settings.test.mjs

@@ -31,6 +31,7 @@ function installEnvironment(homeDirectory) {
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
     };
 }
 

package/bin/install.test.mjs

@@ -3026,6 +3026,7 @@ test('a failed update preserves an existing skills lookup pointer', () => {
             GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
         };
         const argumentsForCoreInstall = [PSTACK_TEST_INSTALLER_PATH, '--only', 'core'];
         const firstRun = spawnSync(process.execPath, argumentsForCoreInstall, {
@@ -3077,6 +3078,7 @@ function runPstackInstaller(homeDirectory, extraArguments, environmentOverrides
             GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
             CDE_INSTALL_PSTACK: '1',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             ...environmentOverrides,
         },
     });
@@ -3391,6 +3393,60 @@ test('the help output names the usage-wrapup opt-out beside the pstack one', ()
     assert.match(helpRun.stdout, /--no-pstack .*\n.*--no-usage-wrapup .*CDE_INSTALL_USAGE_WRAPUP=0/);
 });
 
+const REPOSITORY_PLUGIN_CLAUDE_COMMANDS = Object.freeze([
+    'claude plugin uninstall usage-wrapup@claude-dev-env',
+    'claude plugin uninstall subagent-models@claude-dev-env',
+    'claude plugin marketplace remove claude-dev-env',
+    'claude plugin marketplace add jl-cmd/claude-dev-env --sparse .claude-plugin packages/usage-wrapup packages/subagent-models',
+    'claude plugin install usage-wrapup@claude-dev-env',
+    'claude plugin install subagent-models@claude-dev-env',
+]);
+
+test('should install subagent-models beside usage-wrapup with one marketplace add on a full install', t => {
+    const sandbox = pstackPluginSandbox(t);
+
+    const installerOutput = runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], {
+        ...sandbox.environment,
+        CDE_INSTALL_USAGE_WRAPUP: '1',
+        CDE_INSTALL_SUBAGENT_MODELS: '1',
+    });
+
+    assert.deepEqual(usageWrapupCommands(sandbox.recordedCommands()), REPOSITORY_PLUGIN_CLAUDE_COMMANDS);
+    assert.match(installerOutput, /Usage-wrapup \(claude\): installed/);
+    assert.match(installerOutput, /Subagent-models \(claude\): installed/);
+});
+
+for (const [caseName, extraArguments, environmentOverrides] of [
+    ['--no-subagent-models', ['--no-subagent-models'], { CDE_INSTALL_SUBAGENT_MODELS: '1' }],
+    ['CDE_INSTALL_SUBAGENT_MODELS=0', [], { CDE_INSTALL_SUBAGENT_MODELS: '0' }],
+    ['an --only run', ['--only', 'core'], { CDE_INSTALL_SUBAGENT_MODELS: '1' }],
+]) {
+    test(`should skip subagent-models on ${caseName}`, t => {
+        const sandbox = pstackPluginSandbox(t);
+
+        const installerOutput = runPstackInstaller(sandbox.homeDirectory, extraArguments, {
+            ...sandbox.environment,
+            ...environmentOverrides,
+        });
+
+        assert.equal(
+            sandbox.recordedCommands().some(eachCommand => eachCommand.includes('subagent-models')),
+            false,
+        );
+        assert.doesNotMatch(installerOutput, /Subagent-models \(/);
+    });
+}
+
+test('should name the subagent-models opt-out in the help output', () => {
+    const helpRun = spawnSync(process.execPath, [PSTACK_TEST_INSTALLER_PATH, '--help'], {
+        encoding: 'utf8',
+        env: process.env,
+    });
+
+    assert.equal(helpRun.status, 0, helpRun.stderr);
+    assert.match(helpRun.stdout, /--no-subagent-models .*CDE_INSTALL_SUBAGENT_MODELS=0/);
+});
+
 function continuityCommandCount(configurationPath) {
     if (!existsSync(configurationPath)) return 0;
     const configuration = JSON.parse(readFileSync(configurationPath, 'utf8'));

package/bin/install.transaction.test.mjs

@@ -87,6 +87,7 @@ test('capture and restore recover settings, manifest, files, and hooksPath', ()
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: box.root,
         USERPROFILE: box.root,
         GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -149,6 +150,7 @@ test('capture and restore recover an additional host settings file', () => {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             HOME: box.root,
             USERPROFILE: box.root,
             GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -184,6 +186,7 @@ test('runWithInstallTransaction restores prior state on injected fault', () => {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: box.root,
         USERPROFILE: box.root,
         GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -238,6 +241,7 @@ test('runWithInstallTransaction commits and discards journal on success', () =>
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
             CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
             HOME: box.root,
             USERPROFILE: box.root,
             GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -281,6 +285,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -316,6 +321,7 @@ test('a later install fault removes newly seeded Codex pstack files', () => {
             environment: {
                 CDE_INSTALL_PSTACK: '1',
                 CDE_INSTALL_USAGE_WRAPUP: '0',
+                CDE_INSTALL_SUBAGENT_MODELS: '0',
                 CDE_CODEX_EXECUTABLE: codexCommandPath,
             },
         });
@@ -459,6 +465,7 @@ test('installer fault after_git_config restores prior core.hooksPath', () => {
                 ...process.env,
                 CDE_INSTALL_PSTACK: '0',
                 CDE_INSTALL_USAGE_WRAPUP: '0',
+                CDE_INSTALL_SUBAGENT_MODELS: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -476,6 +483,7 @@ test('installer fault after_git_config restores prior core.hooksPath', () => {
                 ...process.env,
                 CDE_INSTALL_PSTACK: '0',
                 CDE_INSTALL_USAGE_WRAPUP: '0',
+                CDE_INSTALL_SUBAGENT_MODELS: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/bin/install.uninstall-transaction.test.mjs

@@ -73,6 +73,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -307,6 +308,7 @@ test('uninstall fault after_git_config restores prior core.hooksPath', () => {
                 ...process.env,
                 CDE_INSTALL_PSTACK: '0',
                 CDE_INSTALL_USAGE_WRAPUP: '0',
+                CDE_INSTALL_SUBAGENT_MODELS: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/bin/install.update-keeps-hooks.test.mjs

@@ -24,6 +24,7 @@ function installerEnvironment(homeDirectory) {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
         CDE_INSTALL_USAGE_WRAPUP: '0',
+        CDE_INSTALL_SUBAGENT_MODELS: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.51.3",
+    "version": "8.52.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/settings.json

@@ -1,8 +1,15 @@
 {
-    "permissions": {
-        "allow": [
-            "WebFetch(domain:docs.github.com)"
-        ]
-    },
-    "advisorModel": "fable"
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:docs.github.com)"
+    ]
+  },
+  "advisorModel": "fable",
+  "autoMode": {
+    "allow": [
+      "$defaults",
+      "Updating or installing the claude-dev-env package is allowed: running `npx claude-dev-env@latest --update` or `npx --yes claude-dev-env@latest --update --target <claude config dir>` is the user's own daily environment sync from the user's own public package, and its writes to the Claude config directory are the intended result. This covers only that package and command.",
+      "Developing the claude-dev-env repository is allowed: editing, testing, committing and pushing its settings, hooks, scripts and tests is the user's requested work on the user's own public package. It changes the package source in the repository; it does not change the running session's own configuration."
+    ]
+  }
 }