fix(cli): reduce plugin hook fallback noise (#100554)

* fix(cli): reduce plugin hook fallback noise

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

* docs(changelog): defer plugin diagnostic note

---------

Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

src/cli/plugins-cli-test-helpers.ts

@@ -624,6 +624,10 @@ vi.mock("../plugins/git-install.js", () => ({
 }));
 
 vi.mock("../hooks/install.js", () => ({
+  HOOK_INSTALL_ERROR_CODE: {
+    MISSING_OPENCLAW_HOOKS: "missing_openclaw_hooks",
+    EMPTY_OPENCLAW_HOOKS: "empty_openclaw_hooks",
+  },
   installHooksFromNpmSpec: ((
     ...args: Parameters<(typeof import("../hooks/install.js"))["installHooksFromNpmSpec"]>
   ) =>

src/cli/plugins-cli.install.test.ts

@@ -1984,6 +1984,7 @@ describe("plugins cli install", () => {
     installHooksFromNpmSpec.mockResolvedValue({
       ok: false,
       error: "package.json missing openclaw.hooks",
+      code: "missing_openclaw_hooks",
     });
 
     await expect(runPluginsCommand(["plugins", "install", "npm:demo"])).rejects.toThrow(
@@ -1992,6 +1993,28 @@ describe("plugins cli install", () => {
 
     expect(installPluginFromClawHub).not.toHaveBeenCalled();
     expect(runtimeErrors.at(-1)).toContain("npm install failed");
+    expect(runtimeErrors.at(-1)).not.toContain("Also not a valid hook pack");
+  });
+
+  it("keeps actionable hook-pack fallback details", async () => {
+    loadConfig.mockReturnValue({} as OpenClawConfig);
+    installPluginFromNpmSpec.mockResolvedValue({
+      ok: false,
+      error: "npm install failed",
+    });
+    installHooksFromNpmSpec.mockResolvedValue({
+      ok: false,
+      error: "HOOK.md missing in /tmp/demo-hook",
+    });
+
+    await expect(runPluginsCommand(["plugins", "install", "npm:demo-hook"])).rejects.toThrow(
+      "__exit__:1",
+    );
+
+    expect(runtimeErrors.at(-1)).toContain("npm install failed");
+    expect(runtimeErrors.at(-1)).toContain(
+      "Also not a valid hook pack: HOOK.md missing in /tmp/demo-hook",
+    );
   });
 
   it("adds a Git PATH hint when npm plugin dependency install cannot spawn git", async () => {
@@ -2008,6 +2031,7 @@ describe("plugins cli install", () => {
     installHooksFromNpmSpec.mockResolvedValue({
       ok: false,
       error: "package.json missing openclaw.hooks",
+      code: "missing_openclaw_hooks",
     });
 
     await expect(
@@ -2019,7 +2043,7 @@ describe("plugins cli install", () => {
       "one of this plugin's npm dependencies is fetched from a git URL",
     );
     expect(runtimeErrors.at(-1)).toContain("winget install --id Git.Git -e");
-    expect(runtimeErrors.at(-1)).toContain("Also not a valid hook pack");
+    expect(runtimeErrors.at(-1)).not.toContain("Also not a valid hook pack");
   });
 
   it("does not resolve npm: prefixed bundled plugin ids through bundled installs", async () => {
@@ -2032,6 +2056,7 @@ describe("plugins cli install", () => {
     installHooksFromNpmSpec.mockResolvedValue({
       ok: false,
       error: "package.json missing openclaw.hooks",
+      code: "missing_openclaw_hooks",
     });
 
     await expect(runPluginsCommand(["plugins", "install", "npm:memory-lancedb"])).rejects.toThrow(
@@ -2042,6 +2067,7 @@ describe("plugins cli install", () => {
     expect(installPluginFromClawHub).not.toHaveBeenCalled();
     expect(writeConfigFile).not.toHaveBeenCalled();
     expect(runtimeErrors.at(-1)).toContain("Package not found on npm: memory-lancedb.");
+    expect(runtimeErrors.at(-1)).not.toContain("Also not a valid hook pack");
   });
 
   it("rejects empty npm: prefix installs before resolver lookup", async () => {

src/cli/plugins-command-helpers.ts

@@ -2,6 +2,7 @@
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { theme } from "../../packages/terminal-core/src/theme.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { HOOK_INSTALL_ERROR_CODE } from "../hooks/install.js";
 import type { PluginKind } from "../plugins/plugin-kind.types.js";
 import { loadPluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import { applyExclusiveSlotSelection } from "../plugins/slots.js";
@@ -169,10 +170,10 @@ export function enableInternalHookEntries(
 
 export function formatPluginInstallWithHookFallbackError(
   pluginError: string,
-  hookError: string,
+  hookFallback: { error: string; code?: string },
 ): string {
   const formattedPluginError = formatPluginInstallAttemptError(pluginError);
-  const formattedHookError = formatPluginInstallAttemptError(hookError);
+  const formattedHookError = formatPluginInstallAttemptError(hookFallback.error);
   if (/plugin already exists: .+ \(delete it first\)/.test(pluginError)) {
     return `${formattedPluginError}\nUse \`openclaw plugins update <id-or-npm-spec>\` to upgrade the tracked plugin, or rerun install with \`--force\` to replace it.`;
   }
@@ -182,6 +183,9 @@ export function formatPluginInstallWithHookFallbackError(
   ) {
     return formattedPluginError;
   }
+  if (hookFallback.code === HOOK_INSTALL_ERROR_CODE.MISSING_OPENCLAW_HOOKS) {
+    return formattedPluginError;
+  }
   return `${formattedPluginError}\nAlso not a valid hook pack: ${formattedHookError}`;
 }
 

src/cli/plugins-install-command.ts

@@ -266,7 +266,7 @@ async function tryInstallHookPackFromLocalPath(params: {
   link?: boolean;
   expectedPackageKind?: "hook-only";
   runtime?: RuntimeEnv;
-}): Promise<{ ok: true } | { ok: false; error: string }> {
+}): Promise<{ ok: true } | Extract<InstallHooksResult, { ok: false }>> {
   if (params.snapshot.hookMutation.mode === "blocked") {
     return { ok: false, error: params.snapshot.hookMutation.reason };
   }
@@ -358,7 +358,7 @@ async function tryInstallHookPackFromNpmSpec(params: {
   expectedIntegrity?: string;
   expectedPackageKind?: "hook-only";
   runtime?: RuntimeEnv;
-}): Promise<{ ok: true } | { ok: false; error: string }> {
+}): Promise<{ ok: true } | Extract<InstallHooksResult, { ok: false }>> {
   if (params.snapshot.hookMutation.mode === "blocked") {
     return { ok: false, error: params.snapshot.hookMutation.reason };
   }
@@ -497,7 +497,7 @@ async function tryInstallPluginOrHookPackFromNpmSpec(params: {
       return { ok: true };
     }
     (params.runtime ?? defaultRuntime).error(
-      formatPluginInstallWithHookFallbackError(result.error, hookFallback.error),
+      formatPluginInstallWithHookFallbackError(result.error, hookFallback),
     );
     return { ok: false };
   }
@@ -1093,7 +1093,7 @@ export async function runPluginInstallCommand(params: {
         if (hookFallback.ok) {
           return;
         }
-        runtime.error(formatPluginInstallWithHookFallbackError(probe.error, hookFallback.error));
+        runtime.error(formatPluginInstallWithHookFallbackError(probe.error, hookFallback));
         return runtime.exit(1);
       }
 
@@ -1147,7 +1147,7 @@ export async function runPluginInstallCommand(params: {
       if (hookFallback.ok) {
         return;
       }
-      runtime.error(formatPluginInstallWithHookFallbackError(result.error, hookFallback.error));
+      runtime.error(formatPluginInstallWithHookFallbackError(result.error, hookFallback));
       return runtime.exit(1);
     }