@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

package/dist/plugins/installer/paths.js

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PluginInstallError } from "./types.js";
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+/** A plugin name must be a single safe path segment — no separators, no traversal. */
+export function assertSafePluginName(name) {
+    if (!name || name === "." || name === "..") {
+        throw new PluginInstallError(`invalid plugin name: ${JSON.stringify(name)}`);
+    }
+    if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+        throw new PluginInstallError(`plugin name must be a single path segment: ${JSON.stringify(name)}`);
+    }
+}
+export function pluginsRoot() {
+    return join(userHome(), ".code-shell", "plugins");
+}
+export function pluginInstallDir(name) {
+    assertSafePluginName(name);
+    return join(pluginsRoot(), name);
+}
+export function pluginMetaPath(name) {
+    return join(pluginInstallDir(name), ".cs-meta.json");
+}

package/dist/plugins/installer/pruneDisabled.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prune a plugin's orphaned entries from a settings object's `disabledSkills`
+ * (entries shaped `name:skill`) and `disabledPlugins` (bare `name`). Called on
+ * uninstall so a removed plugin leaves no dangling disable flags behind.
+ *
+ * Pure + immutable: returns a NEW object (shallow clone) with the two arrays
+ * replaced by filtered copies. Settings lacking these fields pass through
+ * unchanged. A plugin name that is a prefix of another (`mimi-video` vs
+ * `mimi-video-pro`) only matches its own exact name / `name:` prefix.
+ */
+export interface PrunableSettings {
+    disabledSkills?: string[];
+    disabledPlugins?: string[];
+    [key: string]: unknown;
+}
+export declare function pruneDisabledEntriesForPlugin<T extends PrunableSettings>(settings: T, pluginName: string): T;
+/**
+ * Read the user settings.json (under {@link userHome}, so HOME-isolated tests
+ * are honored), prune the plugin's orphaned disable entries, and write back —
+ * only when something actually changed. Never throws: a missing/corrupt file or
+ * any IO error is swallowed (uninstall already succeeded; settings cleanup is
+ * best-effort). Atomic write via .tmp + rename mirrors SettingsManager.
+ */
+export declare function pruneDisabledSettingsForPlugin(pluginName: string): void;

package/dist/plugins/installer/pruneDisabled.js

@@ -0,0 +1,73 @@
+/**
+ * Prune a plugin's orphaned entries from a settings object's `disabledSkills`
+ * (entries shaped `name:skill`) and `disabledPlugins` (bare `name`). Called on
+ * uninstall so a removed plugin leaves no dangling disable flags behind.
+ *
+ * Pure + immutable: returns a NEW object (shallow clone) with the two arrays
+ * replaced by filtered copies. Settings lacking these fields pass through
+ * unchanged. A plugin name that is a prefix of another (`mimi-video` vs
+ * `mimi-video-pro`) only matches its own exact name / `name:` prefix.
+ */
+import { writeFileSync, mkdirSync, existsSync, readFileSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Resolve the user's home dir, preferring `process.env.HOME` so HOME-isolated
+ * tests (and runtime overrides) take effect — same contract as
+ * SettingsManager.userHome and installer/paths.ts, without dragging in the
+ * settings module's heavier transitive deps.
+ */
+function userHome() {
+    return process.env.HOME ?? homedir();
+}
+export function pruneDisabledEntriesForPlugin(settings, pluginName) {
+    const skillPrefix = `${pluginName}:`;
+    const out = { ...settings };
+    if (Array.isArray(settings.disabledSkills)) {
+        out.disabledSkills = settings.disabledSkills.filter((s) => !s.startsWith(skillPrefix));
+    }
+    if (Array.isArray(settings.disabledPlugins)) {
+        out.disabledPlugins = settings.disabledPlugins.filter((p) => p !== pluginName);
+    }
+    return out;
+}
+/**
+ * Read the user settings.json (under {@link userHome}, so HOME-isolated tests
+ * are honored), prune the plugin's orphaned disable entries, and write back —
+ * only when something actually changed. Never throws: a missing/corrupt file or
+ * any IO error is swallowed (uninstall already succeeded; settings cleanup is
+ * best-effort). Atomic write via .tmp + rename mirrors SettingsManager.
+ */
+export function pruneDisabledSettingsForPlugin(pluginName) {
+    try {
+        const path = join(userHome(), ".code-shell", "settings.json");
+        if (!existsSync(path))
+            return;
+        let current;
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf-8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            current = parsed;
+        }
+        catch {
+            return; // corrupt file — leave it alone
+        }
+        const pruned = pruneDisabledEntriesForPlugin(current, pluginName);
+        const changed = JSON.stringify(pruned.disabledSkills) !== JSON.stringify(current.disabledSkills) ||
+            JSON.stringify(pruned.disabledPlugins) !== JSON.stringify(current.disabledPlugins);
+        if (!changed)
+            return;
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+        // mode 0o600 — settings.json can hold plaintext API keys, so the pruned
+        // rewrite must stay owner-only (matching settings/manager.ts), not fall back
+        // to the umask default 0o644 (world-readable). The tmp IS the final file
+        // after renameSync, so the mode must be set at create time, not via chmod.
+        writeFileSync(tmp, JSON.stringify(pruned, null, 2), { encoding: "utf-8", mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch {
+        // best-effort cleanup — never fail the uninstall over settings IO
+    }
+}

package/dist/plugins/installer/types.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/** Codex `.codex-plugin/plugin.json`. v1 reads required fields; unknowns pass through. */
+export declare const CodexPluginManifest: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    mcpServers: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>>;
+    skills: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    mcpServers: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>>;
+    skills: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    mcpServers: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>>;
+    skills: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type CodexPluginManifest = z.infer<typeof CodexPluginManifest>;
+/** `.cs-meta.json` written into every installed plugin dir. */
+export declare const CSMeta: z.ZodObject<{
+    name: z.ZodString;
+    format: z.ZodEnum<["cc", "codex"]>;
+    version: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+    installedAt: z.ZodString;
+    commit: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    name: string;
+    format: "cc" | "codex";
+    installedAt: string;
+    version?: string | undefined;
+    commit?: string | undefined;
+}, {
+    source: string;
+    name: string;
+    format: "cc" | "codex";
+    installedAt: string;
+    version?: string | undefined;
+    commit?: string | undefined;
+}>;
+export type CSMeta = z.infer<typeof CSMeta>;
+export declare class PluginInstallError extends Error {
+    constructor(message: string);
+}

package/dist/plugins/installer/types.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/** Codex `.codex-plugin/plugin.json`. v1 reads required fields; unknowns pass through. */
+export const CodexPluginManifest = z
+    .object({
+    name: z.string(),
+    version: z.string(),
+    description: z.string().optional(),
+    // string → relative path to a .mcp.json; object → inline mcpServers map
+    mcpServers: z.union([z.string(), z.record(z.any())]).optional(),
+    skills: z.string().optional(),
+    agents: z.string().optional(),
+})
+    .passthrough();
+/** `.cs-meta.json` written into every installed plugin dir. */
+export const CSMeta = z.object({
+    name: z.string(),
+    format: z.enum(["cc", "codex"]),
+    version: z.string().optional(),
+    source: z.string(),
+    installedAt: z.string(),
+    commit: z.string().optional(), // remote (git) source: the HEAD SHA we installed
+});
+export class PluginInstallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginInstallError";
+    }
+}

package/dist/plugins/installer/uninstall.d.ts

@@ -0,0 +1,2 @@
+/** Remove a locally-installed plugin dir + its installed_plugins.json entry. */
+export declare function uninstallPluginByName(name: string): void;

package/dist/plugins/installer/uninstall.js

@@ -0,0 +1,18 @@
+import { existsSync, rmSync } from "node:fs";
+import { pluginInstallDir, assertSafePluginName } from "./paths.js";
+import { removeInstallEntries, pluginInstallKey } from "../installedPlugins.js";
+import { PluginInstallError } from "./types.js";
+import { pruneDisabledSettingsForPlugin } from "./pruneDisabled.js";
+/** Remove a locally-installed plugin dir + its installed_plugins.json entry. */
+export function uninstallPluginByName(name) {
+    assertSafePluginName(name);
+    const dir = pluginInstallDir(name);
+    if (!existsSync(dir)) {
+        throw new PluginInstallError(`no plugin named '${name}'`);
+    }
+    rmSync(dir, { recursive: true, force: true });
+    removeInstallEntries(pluginInstallKey(name, "local"));
+    // Clear orphaned disable flags (disabledSkills "name:skill" /
+    // disabledPlugins "name") so a removed plugin leaves no dangling entries.
+    pruneDisabledSettingsForPlugin(name);
+}

package/dist/plugins/installer/unzip.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reject path traversal ("zip slip"): a malicious archive can carry entries
+ * like `../../etc/foo` that escape the extraction root. We normalize and
+ * require the resolved path to stay within `destDir`.
+ */
+export declare function safeJoin(destDir: string, entryName: string): string;
+/**
+ * Extract a .zip into destDir (must already exist). Streams each entry to disk
+ * so a large archive doesn't buffer in memory. Directory entries (trailing
+ * "/") just create the dir; symlinks and other special entries are skipped —
+ * we only materialize regular files and directories, which is all a plugin
+ * needs and keeps the surface safe.
+ */
+export declare function extractZip(zipPath: string, destDir: string): Promise<void>;

package/dist/plugins/installer/unzip.js

@@ -0,0 +1,82 @@
+import { createRequire } from "node:module";
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join, normalize, sep } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { PluginInstallError } from "./types.js";
+let _yauzl;
+function yauzl() {
+    if (!_yauzl) {
+        _yauzl = createRequire(import.meta.url ?? __filename)("yauzl");
+    }
+    return _yauzl;
+}
+/**
+ * Reject path traversal ("zip slip"): a malicious archive can carry entries
+ * like `../../etc/foo` that escape the extraction root. We normalize and
+ * require the resolved path to stay within `destDir`.
+ */
+export function safeJoin(destDir, entryName) {
+    // Zip entries always use forward slashes; normalize to the host separator.
+    const target = normalize(join(destDir, entryName));
+    const root = normalize(destDir.endsWith(sep) ? destDir : destDir + sep);
+    if (target !== normalize(destDir) && !target.startsWith(root)) {
+        throw new PluginInstallError(`refusing zip entry that escapes target: ${entryName}`);
+    }
+    return target;
+}
+/**
+ * Extract a .zip into destDir (must already exist). Streams each entry to disk
+ * so a large archive doesn't buffer in memory. Directory entries (trailing
+ * "/") just create the dir; symlinks and other special entries are skipped —
+ * we only materialize regular files and directories, which is all a plugin
+ * needs and keeps the surface safe.
+ */
+export async function extractZip(zipPath, destDir) {
+    const zip = await openZip(zipPath);
+    try {
+        await drainEntries(zip, destDir);
+    }
+    finally {
+        zip.close();
+    }
+}
+function openZip(zipPath) {
+    return new Promise((resolve, reject) => {
+        yauzl().open(zipPath, { lazyEntries: true }, (err, z) => {
+            if (err || !z) {
+                reject(new PluginInstallError(`cannot open zip: ${err?.message ?? "unknown"}`));
+                return;
+            }
+            resolve(z);
+        });
+    });
+}
+function drainEntries(zip, destDir) {
+    return new Promise((resolve, reject) => {
+        zip.on("error", (e) => reject(e));
+        zip.on("end", () => resolve());
+        zip.on("entry", (entry) => {
+            const onErr = (e) => reject(e);
+            // Directory entry — yauzl signals these with a trailing slash.
+            if (/\/$/.test(entry.fileName)) {
+                mkdir(safeJoin(destDir, entry.fileName), { recursive: true })
+                    .then(() => zip.readEntry())
+                    .catch(onErr);
+                return;
+            }
+            const outPath = safeJoin(destDir, entry.fileName);
+            zip.openReadStream(entry, (err, stream) => {
+                if (err || !stream) {
+                    onErr(new PluginInstallError(`cannot read zip entry ${entry.fileName}: ${err?.message ?? "unknown"}`));
+                    return;
+                }
+                mkdir(dirname(outPath), { recursive: true })
+                    .then(() => pipeline(stream, createWriteStream(outPath)))
+                    .then(() => zip.readEntry())
+                    .catch(onErr);
+            });
+        });
+        zip.readEntry();
+    });
+}

package/dist/plugins/installer/update.d.ts

@@ -0,0 +1,28 @@
+export interface UpdateResult {
+    updated: boolean;
+    reason: string;
+}
+/**
+ * Reinstall a plugin atomically: a failed update leaves the OLD plugin intact.
+ *
+ * The installers (installPluginFromPath / installPluginFromSource) build into a
+ * temp dir then rename into pluginInstallDir(name), and THROW if the final dir
+ * already exists. So we must free the final dir *before* installing — we do that
+ * by renaming the live dir to a sibling backup. On success we drop the backup;
+ * on failure we delete any partial install and rename the backup back.
+ *
+ * Async fs only — this runs in the Electron main process, so we never block the
+ * event loop with sync fs. process.pid (not Date.now(), unavailable here) makes
+ * the backup name unique.
+ */
+export declare function reinstallAtomic(name: string, source: string, doInstall: () => Promise<unknown>): Promise<void>;
+/**
+ * Reinstall a plugin from its recorded source.
+ *
+ * - Local source: reinstall when the source version changed, or when `force`.
+ *   CC plugins have no version → only `force` updates them.
+ * - Remote (git) source: re-clone and reinstall every time — git sources carry
+ *   no local version file to compare, so update is always a fresh pull
+ *   (equivalent to `--force`; cheap and reliable). See spec §9.
+ */
+export declare function updatePluginByName(name: string, installedAt: string, force: boolean): Promise<UpdateResult>;

package/dist/plugins/installer/update.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from "node:fs";
+import { rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { detectPluginFormat } from "./detectFormat.js";
+import { pluginInstallDir } from "./paths.js";
+import { installPluginFromPath } from "./install.js";
+import { installPluginFromSource } from "./installFromSource.js";
+import { parseSource } from "./parseSource.js";
+import { pluginInstallKey, readInstalledPlugins, removeInstallEntries, writeInstalledPlugins } from "../installedPlugins.js";
+import { CodexPluginManifest, CSMeta, PluginInstallError } from "./types.js";
+/**
+ * Reinstall a plugin atomically: a failed update leaves the OLD plugin intact.
+ *
+ * The installers (installPluginFromPath / installPluginFromSource) build into a
+ * temp dir then rename into pluginInstallDir(name), and THROW if the final dir
+ * already exists. So we must free the final dir *before* installing — we do that
+ * by renaming the live dir to a sibling backup. On success we drop the backup;
+ * on failure we delete any partial install and rename the backup back.
+ *
+ * Async fs only — this runs in the Electron main process, so we never block the
+ * event loop with sync fs. process.pid (not Date.now(), unavailable here) makes
+ * the backup name unique.
+ */
+export async function reinstallAtomic(name, source, doInstall) {
+    const dir = pluginInstallDir(name);
+    const backup = `${dir}.bak-${process.pid}`;
+    // Capture the existing install_plugins.json entries so a failed reinstall can
+    // restore them (uninstall-then-install used to drop them on failure; here the
+    // old plugin survives, so its registration must survive too).
+    const key = pluginInstallKey(name, "local");
+    const savedEntries = readInstalledPlugins().plugins[key];
+    await rm(backup, { recursive: true, force: true });
+    await rename(dir, backup);
+    // The installer re-adds the entry on success; remove the stale one first so a
+    // successful reinstall doesn't accumulate a duplicate.
+    removeInstallEntries(key);
+    try {
+        await doInstall();
+    }
+    catch (err) {
+        // Roll back: drop any partial install, restore the old dir + its entries.
+        await rm(dir, { recursive: true, force: true });
+        await rename(backup, dir);
+        if (savedEntries) {
+            // Restore in a single read-modify-write rather than one append per entry,
+            // which both narrows the race window against any concurrent writer and
+            // avoids re-appending onto whatever partial state doInstall() may have
+            // left for this key.
+            const data = readInstalledPlugins();
+            data.plugins[key] = savedEntries;
+            writeInstalledPlugins(data);
+        }
+        throw new PluginInstallError(`update failed; the old version of '${name}' was kept: ` +
+            `${err instanceof Error ? err.message : String(err)}. Source: ${source}.`);
+    }
+    // Success — drop the backup (best-effort; a leftover backup is harmless but
+    // we clean it up so it never shows up in the plugins root).
+    await rm(backup, { recursive: true, force: true });
+}
+/**
+ * Reinstall a plugin from its recorded source.
+ *
+ * - Local source: reinstall when the source version changed, or when `force`.
+ *   CC plugins have no version → only `force` updates them.
+ * - Remote (git) source: re-clone and reinstall every time — git sources carry
+ *   no local version file to compare, so update is always a fresh pull
+ *   (equivalent to `--force`; cheap and reliable). See spec §9.
+ */
+export async function updatePluginByName(name, installedAt, force) {
+    const dir = pluginInstallDir(name);
+    const metaPath = join(dir, ".cs-meta.json");
+    if (!existsSync(metaPath))
+        throw new PluginInstallError(`no plugin named '${name}'`);
+    const meta = CSMeta.parse(JSON.parse(readFileSync(metaPath, "utf-8")));
+    const parsed = parseSource(meta.source);
+    if (parsed.kind === "remote") {
+        // No local version to diff against — always re-clone and reinstall.
+        await reinstallAtomic(name, meta.source, () => installPluginFromSource(parsed, name, installedAt));
+        return { updated: true, reason: "reinstalled from git source" };
+    }
+    if (!existsSync(meta.source)) {
+        throw new PluginInstallError(`source no longer exists: ${meta.source}`);
+    }
+    if (!force) {
+        if (detectPluginFormat(meta.source) === "codex") {
+            const manifest = CodexPluginManifest.parse(JSON.parse(readFileSync(join(meta.source, ".codex-plugin", "plugin.json"), "utf-8")));
+            if (manifest.version === meta.version) {
+                return { updated: false, reason: "already up to date" };
+            }
+        }
+        else {
+            return { updated: false, reason: "CC plugin needs --force to reinstall" };
+        }
+    }
+    await reinstallAtomic(name, meta.source, () => installPluginFromPath(meta.source, name, installedAt));
+    return { updated: true, reason: "reinstalled" };
+}

package/dist/plugins/loadPluginHooks.d.ts

@@ -42,11 +42,64 @@
  * Errors are swallowed per-plugin: a malformed hooks.json from one plugin
  * must not block other plugins from loading.
  */
+import type { HookEventName } from "../hooks/events.js";
 import type { HookRegistry } from "../hooks/registry.js";
+/**
+ * Stable identity for ONE plugin-provided hook, used as the record key in
+ * `capabilityOverrides.pluginHooks` (per-hook project off-switch). Derived
+ * from content (`plugin:RawEvent:command`) rather than scan order so it
+ * survives plugin reinstalls and hooks.json reordering. Two entries that
+ * differ only by matcher collide — acceptable: toggling one toggles both,
+ * and identical commands on the same event are in practice the same hook.
+ */
+export declare function pluginHookKey(hook: {
+    plugin: string;
+    rawEvent: string;
+    command: string;
+}): string;
 /**
  * Walk installed plugins and register their command hooks. Safe to call
  * multiple times — the caller is responsible for not double-registering
  * (HookRegistry has no de-dup; the engine constructor calls this exactly
  * once after creating the registry).
+ *
+ * `disabledPlugins` is the coarse "plugin total switch" — bare plugin names
+ * (no `@marketplace`, no `:` suffix), matching scanSkills' semantics. A
+ * disabled plugin contributes NO hooks, so e.g. disabling "superpowers"
+ * also suppresses its SessionStart injection — not just its Skill-tool
+ * entries. Without this, `disabledPlugins` only filtered the skill list and
+ * the plugin's hooks still fired regardless.
+ *
+ * `disabledPluginHooks` is the fine-grained per-hook switch — a list of
+ * {@link pluginHookKey} keys (folded from the project's
+ * `capabilityOverrides.pluginHooks` by readDisabledLists). A matching hook
+ * is skipped while the rest of the plugin keeps working.
+ */
+export declare function loadPluginHooks(registry: HookRegistry, disabledPlugins?: string[], disabledPluginHooks?: string[]): void;
+/** A single plugin-provided hook, surfaced read-only to the settings UI. */
+export interface PluginHookEntry {
+    /** Source plugin name (bare, no @marketplace). */
+    plugin: string;
+    /** Mapped codeshell event name. */
+    event: HookEventName;
+    /** Original CC event name as written in hooks.json (for display). */
+    rawEvent: string;
+    /** The shell command the hook runs. */
+    command: string;
+    /** Optional matcher (regex) from the hooks.json group. */
+    matcher?: string;
+    /** Whether the owning plugin is currently disabled (its hooks don't fire). */
+    disabled: boolean;
+    /** Stable per-hook identity ({@link pluginHookKey}) — the record key the
+     *  UI writes to `capabilityOverrides.pluginHooks` to toggle just this hook. */
+    key: string;
+}
+/**
+ * Read-only counterpart to {@link loadPluginHooks}: scan installed plugins and
+ * RETURN their command hooks (instead of registering them), so the settings
+ * "钩子" page can show plugin-provided hooks alongside the user's hand-written
+ * ones, labelled by owner plugin. `disabledPlugins` doesn't filter the list —
+ * disabled plugins are still listed but flagged `disabled:true` (so the UI can
+ * show "由 xxx 插件提供（已禁用）"); pass it so that flag is accurate.
  */
-export declare function loadPluginHooks(registry: HookRegistry): void;
+export declare function listPluginHooks(disabledPlugins?: string[]): PluginHookEntry[];

package/dist/plugins/loadPluginHooks.js

@@ -109,15 +109,42 @@ function pluginNameFromKey(key) {
     const at = key.lastIndexOf("@");
     return at > 0 ? key.slice(0, at) : key;
 }
+/**
+ * Stable identity for ONE plugin-provided hook, used as the record key in
+ * `capabilityOverrides.pluginHooks` (per-hook project off-switch). Derived
+ * from content (`plugin:RawEvent:command`) rather than scan order so it
+ * survives plugin reinstalls and hooks.json reordering. Two entries that
+ * differ only by matcher collide — acceptable: toggling one toggles both,
+ * and identical commands on the same event are in practice the same hook.
+ */
+export function pluginHookKey(hook) {
+    return `${hook.plugin}:${hook.rawEvent}:${hook.command}`;
+}
 /**
  * Walk installed plugins and register their command hooks. Safe to call
  * multiple times — the caller is responsible for not double-registering
  * (HookRegistry has no de-dup; the engine constructor calls this exactly
  * once after creating the registry).
+ *
+ * `disabledPlugins` is the coarse "plugin total switch" — bare plugin names
+ * (no `@marketplace`, no `:` suffix), matching scanSkills' semantics. A
+ * disabled plugin contributes NO hooks, so e.g. disabling "superpowers"
+ * also suppresses its SessionStart injection — not just its Skill-tool
+ * entries. Without this, `disabledPlugins` only filtered the skill list and
+ * the plugin's hooks still fired regardless.
+ *
+ * `disabledPluginHooks` is the fine-grained per-hook switch — a list of
+ * {@link pluginHookKey} keys (folded from the project's
+ * `capabilityOverrides.pluginHooks` by readDisabledLists). A matching hook
+ * is skipped while the rest of the plugin keeps working.
  */
-export function loadPluginHooks(registry) {
+export function loadPluginHooks(registry, disabledPlugins = [], disabledPluginHooks = []) {
     const data = readInstalledPlugins();
+    const disabledSet = new Set(disabledPlugins);
+    const disabledHookSet = new Set(disabledPluginHooks);
     for (const [key, entries] of Object.entries(data.plugins)) {
+        if (disabledSet.has(pluginNameFromKey(key)))
+            continue;
         for (const entry of entries) {
             const installPath = entry.installPath;
             if (!installPath || !existsSync(installPath))
@@ -140,6 +167,13 @@ export function loadPluginHooks(registry) {
                         if (cmd.type !== "command" || typeof cmd.command !== "string") {
                             continue;
                         }
+                        if (disabledHookSet.has(pluginHookKey({
+                            plugin: pluginNameFromKey(key),
+                            rawEvent: eventNameRaw,
+                            command: cmd.command,
+                        }))) {
+                            continue;
+                        }
                         const commandLine = cmd.command;
                         const timeoutMs = cmd.timeout_ms;
                         const matcher = group.matcher;
@@ -160,3 +194,51 @@ export function loadPluginHooks(registry) {
         }
     }
 }
+/**
+ * Read-only counterpart to {@link loadPluginHooks}: scan installed plugins and
+ * RETURN their command hooks (instead of registering them), so the settings
+ * "钩子" page can show plugin-provided hooks alongside the user's hand-written
+ * ones, labelled by owner plugin. `disabledPlugins` doesn't filter the list —
+ * disabled plugins are still listed but flagged `disabled:true` (so the UI can
+ * show "由 xxx 插件提供（已禁用）"); pass it so that flag is accurate.
+ */
+export function listPluginHooks(disabledPlugins = []) {
+    const data = readInstalledPlugins();
+    const disabledSet = new Set(disabledPlugins);
+    const out = [];
+    for (const [key, entries] of Object.entries(data.plugins)) {
+        const plugin = pluginNameFromKey(key);
+        const disabled = disabledSet.has(plugin);
+        for (const entry of entries) {
+            const installPath = entry.installPath;
+            if (!installPath || !existsSync(installPath))
+                continue;
+            const raw = readHooksJson(installPath);
+            if (!raw?.hooks)
+                continue;
+            for (const [eventNameRaw, groups] of Object.entries(raw.hooks)) {
+                const mapped = EVENT_NAME_MAP[eventNameRaw];
+                if (mapped === null || mapped === undefined)
+                    continue;
+                if (!Array.isArray(groups))
+                    continue;
+                for (const group of groups) {
+                    for (const cmd of group.hooks ?? []) {
+                        if (cmd.type !== "command" || typeof cmd.command !== "string")
+                            continue;
+                        out.push({
+                            plugin,
+                            event: mapped,
+                            rawEvent: eventNameRaw,
+                            command: cmd.command,
+                            matcher: group.matcher,
+                            disabled,
+                            key: pluginHookKey({ plugin, rawEvent: eventNameRaw, command: cmd.command }),
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}