claude-code: shorten generated plugin name to "hm"

The synthesized plugin that delivers managed MCP and LSP configuration to
Claude Code was named `claude-code-home-manager`. Claude Code derives the
MCP tool namespace from the plugin manifest (`plugin.json`), so that name
appeared in the prefix of every plugin-loaded MCP tool
(`mcp__plugin_<name>_<server>__<tool>`), adding 22 characters of overhead per
tool name.

Shorten the manifest name to `hm`, centralizing it in a `generatedPluginName`
binding, so tool prefixes become `mcp__plugin_hm_<server>__<tool>`. The
personal-plugin directory entry keeps the stable `claude-code-home-manager`
name (the path under `~/.claude/skills/`); a short name there would collide
with valid `programs.claude-code.plugins.hm` or `skills.hm` and fail the
uniqueness assertions.

This is a breaking change: users who allow or deny these tools by name in
their settings must update references from `claude-code-home-manager` to
`hm`. A news entry documents the migration.

Closes #9446

Assisted-by: Claude-Code:GLM-5.2

Author: yzx9

modules/misc/news/2026/08/2026-08-06_01-29-34.nix

@@ -0,0 +1,40 @@
+{ config, ... }:
+{
+  time = "2026-08-06T01:29:34+00:00";
+  # Mirrors the generated-plugin trigger in the module: the plugin is created
+  # whenever MCP or LSP servers are produced, including shared MCP servers
+  # pulled in via `enableMcpIntegration`, not just direct `mcpServers`.
+  condition =
+    config.programs.claude-code.enable
+    && (
+      config.programs.claude-code.enableMcpIntegration
+      && config.programs.mcp.enable
+      && config.programs.mcp.servers != { }
+      || config.programs.claude-code.mcpServers != { }
+      || config.programs.claude-code.lspServers != { }
+    );
+  message = ''
+    The generated plugin that delivers managed MCP and LSP configuration to
+    Claude Code now uses the manifest name `hm` (previously
+    `claude-code-home-manager`). Claude Code derives the MCP tool namespace from
+    the plugin manifest, so this shortens every plugin-loaded MCP tool prefix to
+    `mcp__plugin_hm_<server>__<tool>`. See
+    [issue #9446](https://github.com/nix-community/home-manager/issues/9446).
+
+    The personal skills directory stays `~/.claude/skills/claude-code-home-manager`
+    unchanged, so it does not collide with user plugins or skills.
+
+    This is a breaking change. If you allow or deny these tools by name in
+    {file}`<project>/.claude/settings.{, local.}json` or via
+    {option}`programs.claude-code.settings`, update any references from
+    `claude-code-home-manager` to `hm`, for example:
+
+    ```json
+    {
+      "permissions": {
+        "allow": ["mcp__plugin_hm_github"]
+      }
+    }
+    ```
+  '';
+}

modules/programs/claude-code/default.nix

@@ -92,6 +92,14 @@ in
         mkSkillEntry
         ;
 
+      # Manifest name of the synthesized plugin that carries generated MCP and
+      # LSP config. Claude Code derives the MCP tool namespace from this name
+      # (`mcp__plugin_<name>_<server>__<tool>`), so it is kept short to reduce
+      # token overhead. The personal-plugin directory entry keeps the longer,
+      # stable `claude-code-home-manager` name to avoid colliding with user
+      # plugins or skills. See issue #9446.
+      generatedPluginName = "hm";
+
       mergedMcpServers =
         transformedMcpServers
         // lib.mapAttrs (_: server: removeAttrs (lib.hm.mcp.addType server) [ "enabled" ]) cfg.mcpServers;
@@ -110,7 +118,7 @@ in
         ''
           install -Dm644 ${
             jsonFormat.generate "claude-code-plugin.json" {
-              name = "claude-code-home-manager";
+              name = generatedPluginName;
             }
           } $out/.claude-plugin/plugin.json
         ''
@@ -133,6 +141,12 @@ in
 
       pluginEntries =
         lib.optional (generatedPluginFiles != [ ]) {
+          # Keep the directory name as the long, stable `claude-code-home-manager`
+          # rather than the short `generatedPluginName`: this entry becomes a
+          # personal-plugin directory under `skills/`, and a short name like `hm`
+          # would collide with valid `programs.claude-code.plugins.hm` or
+          # `skills.hm`, failing the uniqueness assertions. The MCP tool prefix
+          # already uses the short manifest name above.
           name = "claude-code-home-manager";
           source = generatedPlugin;
         }

tests/modules/programs/claude-code/expected-plugin-manifest.json

@@ -1,3 +1,3 @@
 {
-  "name": "claude-code-home-manager"
+  "name": "hm"
 }