@hover-dev/core 0.6.0 → 0.7.2

package/dist/service/saveHandlers.js

@@ -28,14 +28,12 @@ export async function handleSaveArtifact(ws, msg, devRoot, cfg) {
         send(ws, { type: 'error', payload: { message: `${cfg.requestName}: no steps to save` } });
         return;
     }
+    let result;
     try {
-        const result = await cfg.write({
+        result = await cfg.write({
             devRoot, name, description, steps, assertions,
             payload: msg.payload, overwrite,
         });
-        send(ws, { type: cfg.savedType, payload: { name: result.slug, path: result.path } });
-        if (cfg.onSaved)
-            await cfg.onSaved(ws, devRoot);
     }
     catch (err) {
         if (err instanceof cfg.ExistsError) {
@@ -44,6 +42,19 @@ export async function handleSaveArtifact(ws, msg, devRoot, cfg) {
         }
         const message = err instanceof Error ? err.message : String(err);
         send(ws, { type: 'error', payload: { message: `${cfg.requestName} failed: ${message}` } });
+        return;
+    }
+    send(ws, { type: cfg.savedType, payload: { name: result.slug, path: result.path } });
+    // The artifact is already on disk; an onSaved failure (e.g. listSkills
+    // re-scan) shouldn't surface as if the save itself failed — log and move on.
+    if (cfg.onSaved) {
+        try {
+            await cfg.onSaved(ws, devRoot);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[hover] ${cfg.requestName} onSaved failed: ${message}`);
+        }
     }
 }
 export const SKILL_CONFIG = {

package/dist/service/types.d.ts

@@ -9,7 +9,7 @@
  * back to the widget. Centralised so the JSON.stringify happens in exactly
  * one place.
  */
-import type { WebSocket } from 'ws';
+import { WebSocket } from 'ws';
 import type { SkillStep } from '../skills/writeSkill.js';
 import type { SpecAssertion } from '../specs/writeSpec.js';
 export interface ClientMessage {
@@ -32,10 +32,22 @@ export interface ClientMessage {
         pageUrl?: string;
         /** switch-agent only — id of the agent to switch the service to. */
         agentId?: string;
+        /** set-mode only — id of the plugin-contributed mode to activate,
+         *  or null to return to normal (unmoded) operation. */
+        modeId?: string | null;
     };
 }
 export declare function send(ws: WebSocket, message: {
     type: string;
     payload?: unknown;
 }): void;
+/** Send a message only if the socket is still open. Use this from delayed
+ *  callbacks (promise `.then`, timers) where the client may have disconnected
+ *  between scheduling and firing — calling `ws.send` on a closed socket
+ *  is a silent no-op for some states and throws for others, so a single
+ *  guarded helper makes the intent obvious and prevents surprises. */
+export declare function sendIfOpen(ws: WebSocket, message: {
+    type: string;
+    payload?: unknown;
+}): boolean;
 //# sourceMappingURL=types.d.ts.map

package/dist/service/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/service/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;QACpB,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB;uDAC+C;QAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;2DAEmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;+DACuD;QACvD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAEtF;AAED;;;;sEAIsE;AACtE,wBAAgB,UAAU,CACxB,EAAE,EAAE,SAAS,EACb,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,OAAO,CAIT"}

package/dist/service/types.js

@@ -9,6 +9,18 @@
  * back to the widget. Centralised so the JSON.stringify happens in exactly
  * one place.
  */
+import { WebSocket } from 'ws';
 export function send(ws, message) {
     ws.send(JSON.stringify(message));
 }
+/** Send a message only if the socket is still open. Use this from delayed
+ *  callbacks (promise `.then`, timers) where the client may have disconnected
+ *  between scheduling and firing — calling `ws.send` on a closed socket
+ *  is a silent no-op for some states and throws for others, so a single
+ *  guarded helper makes the intent obvious and prevents surprises. */
+export function sendIfOpen(ws, message) {
+    if (ws.readyState !== WebSocket.OPEN)
+        return false;
+    ws.send(JSON.stringify(message));
+    return true;
+}

package/dist/service.d.ts

@@ -1,3 +1,4 @@
+import { type HoverPluginManifest } from './plugin-api.js';
 export interface ServiceOptions {
     port: number;
     agentId?: string;
@@ -11,6 +12,12 @@ export interface ServiceOptions {
      *  In Vite plugin context, set to `server.config.root` so Claude
      *  auto-discovers skills the user previously saved from this project. */
     devRoot?: string;
+    /** Plugins contributed by the bundler-plugin wrapper. Each manifest can
+     *  add a widget mode, MCP servers, Chrome flags, and lifecycle hooks.
+     *  Empty array (default) means "no plugins, behaviour identical to
+     *  pre-plugin Hover" — important for the long tail of users who never
+     *  install one. */
+    plugins?: HoverPluginManifest[];
 }
 export interface ServiceHandle {
     /** The port the WebSocketServer actually bound to. May differ from

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA+DA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAiV/E"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAqEA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmrB/E"}

package/dist/service.js

@@ -34,6 +34,12 @@
  *
  *   server → client (in addition to those documented in the file body):
  *     { type: 'agents',        payload: { current: string, available: AgentAvailability[] } }
+ *     { type: 'modes',         payload: { current: string|null, available: ModeEntry[] } }
+ *     { type: '<plugin-namespaced>', payload: <plugin-specific> }
+ *
+ *   client → server (plugin-aware additions):
+ *     { type: 'set-mode',      payload: { modeId: string|null } }   // null = exit moded operation
+ *     { type: 'list-modes' }
  */
 import { WebSocketServer, WebSocket } from 'ws';
 import { invokeAgent } from './agents/invoke.js';
@@ -42,10 +48,11 @@ import { getAgent } from './agents/registry.js';
 import { getPreflight, invalidatePreflight } from './playwright/preflightCache.js';
 import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
 import { listSkills } from './skills/writeSkill.js';
-import { send } from './service/types.js';
+import { send, sendIfOpen } from './service/types.js';
 import { buildCdpHint, buildCdpHintResume } from './service/cdpHint.js';
 import { handleCheckCdp, handleLaunchChrome, handleFocusDebug, } from './service/cdpHandlers.js';
 import { handleSaveArtifact, SKILL_CONFIG, SPEC_CONFIG, CASE_CSV_CONFIG, } from './service/saveHandlers.js';
+import { CURRENT_API_VERSION, } from './plugin-api.js';
 // ClientMessage + send moved to ./service/types.ts so the cdp + save
 // handler modules can share them. See those files for the wire shape.
 const PROTOCOL_VERSION = 1;
@@ -122,15 +129,219 @@ export async function startService(opts) {
     const devRoot = opts.devRoot ?? process.cwd();
     const wss = await pickAndBind('127.0.0.1', requestedPort, PORT_RETRIES);
     const port = wss.address().port;
-    // Resolve a CDP-pinned MCP config pointing at our local
-    // `@playwright/mcp` install. See resolveMcpConfig.ts for the rationale
-    // (avoids `npx -y @playwright/mcp@latest`'s registry round-trip on
-    // every command — 300 ms - 2 s of hot-path latency).
-    const mcpConfig = opts.mcpConfig ?? resolveMcpConfig({ cdpUrl, port });
+    // Build a fresh MCP config per command, so the currently-active mode's
+    // contributed servers (plus runtime env from setMcpServerEnv) land in
+    // the file the agent reads. `opts.mcpConfig` still wins if the host
+    // forced an explicit one, but in that case mode-contributed servers
+    // are silently dropped — we log a warning the first time it happens.
+    let warnedExplicitMcpOverride = false;
+    const buildMcpConfig = () => {
+        if (opts.mcpConfig) {
+            const activePlugin = currentModeId ? pluginsByModeId.get(currentModeId) : null;
+            if (activePlugin?.mcpServers?.length && !warnedExplicitMcpOverride) {
+                process.stderr.write(`[hover] explicit opts.mcpConfig overrides plugin-contributed MCP servers ` +
+                    `(plugin "${activePlugin.name}" wanted ${activePlugin.mcpServers
+                        .map((s) => s.id)
+                        .join(', ')}).\n`);
+                warnedExplicitMcpOverride = true;
+            }
+            return opts.mcpConfig;
+        }
+        const extra = [];
+        if (currentModeId) {
+            for (const p of plugins) {
+                for (const srv of p.mcpServers ?? []) {
+                    const scope = srv.activeInModes ?? (p.mode ? [p.mode.id] : []);
+                    const inMode = scope.includes('*') || scope.includes(currentModeId);
+                    if (!inMode)
+                        continue;
+                    extra.push({
+                        id: srv.id,
+                        command: srv.command,
+                        args: srv.args,
+                        env: {
+                            ...(srv.env ?? {}),
+                            ...(mcpEnvOverrides.get(srv.id) ?? {}),
+                        },
+                    });
+                }
+            }
+        }
+        // In an active mode, the Playwright MCP must point at THAT mode's
+        // Chrome (e.g. security mode's 9333), not the default 9222.
+        // effectiveLaunchExtras().cdpPort is the source of truth.
+        const extras = effectiveLaunchExtras();
+        const effectiveCdpUrl = extras?.cdpPort
+            ? `http://localhost:${extras.cdpPort}`
+            : cdpUrl;
+        return resolveMcpConfig({
+            cdpUrl: effectiveCdpUrl,
+            port,
+            extra,
+            // Suffix the filename by the mode so different mode toggles within
+            // one service produce distinct config files (debugging aid).
+            suffix: currentModeId ?? undefined,
+        });
+    };
     // Surface post-listen errors instead of crashing the host process.
     wss.on('error', err => {
         process.stderr.write(`[hover] WebSocketServer error: ${err.message}\n`);
     });
+    // ──────────────────────────────────────────────────────────────────
+    // Plugin registry
+    // ──────────────────────────────────────────────────────────────────
+    // Validate + index plugins once at startup. Reasons we fail loud here
+    // (rather than at first use): mode-id collisions are a configuration
+    // bug, not a runtime one — the widget mode-picker would silently miss
+    // entries, which is worse than a startup error the user has to fix.
+    const plugins = opts.plugins ?? [];
+    const pluginsByName = new Map();
+    const pluginsByModeId = new Map();
+    for (const p of plugins) {
+        if (p.apiVersion !== CURRENT_API_VERSION) {
+            throw new Error(`[hover] plugin "${p.name}" targets apiVersion ${String(p.apiVersion)} but this Hover supports ${CURRENT_API_VERSION}.`);
+        }
+        if (pluginsByName.has(p.name)) {
+            throw new Error(`[hover] duplicate plugin name: ${p.name}`);
+        }
+        pluginsByName.set(p.name, p);
+        if (p.mode) {
+            if (pluginsByModeId.has(p.mode.id)) {
+                throw new Error(`[hover] two plugins contribute the same mode id "${p.mode.id}": ` +
+                    `${pluginsByModeId.get(p.mode.id)?.name} and ${p.name}`);
+            }
+            pluginsByModeId.set(p.mode.id, p);
+        }
+    }
+    /** id of the currently-active mode, or null for normal (unmoded) mode. */
+    let currentModeId = null;
+    /** Chrome-proxy settings the active mode's activate hook set on us.
+     *  Read by `effectiveLaunchExtras()` and threaded into the cdp handlers
+     *  (check-cdp / launch-chrome / focus-debug) so the secured Chrome on
+     *  9333 actually gets `--proxy-server` + SPKI pin when the user clicks
+     *  Launch from the widget. */
+    let modeChromeProxy = null;
+    /** Runtime env overrides keyed by mcpServer id, set by plugin
+     *  activate hooks (via ctx.setMcpServerEnv). Cleared on mode change.
+     *  Merged with the manifest-declared env when the agent's spawn-time
+     *  MCP config is built. */
+    const mcpEnvOverrides = new Map();
+    /** The cdp-handler extras (port, userDataDir, proxy) for the active
+     *  mode's chromeFlags manifest field, or undefined when no mode is
+     *  active. The widget's launch-chrome / check-cdp / focus-debug paths
+     *  all consume these so a Chrome relaunch obeys the mode's needs. */
+    const effectiveLaunchExtras = () => {
+        if (!currentModeId)
+            return undefined;
+        const plugin = pluginsByModeId.get(currentModeId);
+        const flags = plugin?.chromeFlags;
+        if (!flags && !modeChromeProxy)
+            return undefined;
+        // Belt + suspenders — flags.activeInModes is honoured if set, but
+        // since chromeFlags lives on the plugin that contributed this mode,
+        // the default of "applies in own mode" matches what we want.
+        if (flags?.activeInModes && !flags.activeInModes.includes('*') && !flags.activeInModes.includes(currentModeId)) {
+            // Plugin explicitly restricted its chromeFlags to a different mode.
+            // Honour that and only carry modeChromeProxy (set by setChromeProxy).
+            return modeChromeProxy ? { proxy: modeChromeProxy } : undefined;
+        }
+        return {
+            cdpPort: flags?.cdpPort,
+            userDataDir: flags?.userDataDir,
+            // modeChromeProxy wins over flags.proxy because it's the runtime
+            // value the activate hook computed (after starting mockttp);
+            // flags.proxy is only ever set by tests stubbing the manifest.
+            proxy: modeChromeProxy ?? flags?.proxy,
+        };
+    };
+    /** Send the current mode catalogue to one ws (or all if undefined). */
+    const broadcastModes = (target) => {
+        const available = plugins
+            .filter((p) => Boolean(p.mode))
+            .map((p) => ({
+            id: p.mode.id,
+            label: p.mode.label,
+            description: p.mode.description,
+            pluginName: p.name,
+        }));
+        const payload = { current: currentModeId, available };
+        const targets = target ? [target] : [...wss.clients];
+        for (const client of targets) {
+            if (client.readyState === WebSocket.OPEN) {
+                send(client, { type: 'modes', payload });
+            }
+        }
+    };
+    /** Broadcast helper passed to plugin hooks. Plugin-side events should
+     *  be namespaced ("security:flow:added") to avoid collisions with
+     *  core's protocol vocabulary. */
+    const broadcastPluginEvent = (event) => {
+        for (const client of wss.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                send(client, event);
+            }
+        }
+    };
+    const switchMode = async (newModeId) => {
+        if (newModeId === currentModeId)
+            return;
+        // Tear down old mode
+        if (currentModeId) {
+            const old = pluginsByModeId.get(currentModeId);
+            if (old?.hooks?.['hover:mode:deactivate']) {
+                try {
+                    await old.hooks['hover:mode:deactivate']({
+                        devRoot,
+                        broadcast: broadcastPluginEvent,
+                        modeId: currentModeId,
+                    });
+                }
+                catch (err) {
+                    process.stderr.write(`[hover] plugin "${old.name}" deactivate failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+        }
+        modeChromeProxy = null;
+        mcpEnvOverrides.clear();
+        currentModeId = null;
+        // Bring up new mode
+        if (newModeId) {
+            const next = pluginsByModeId.get(newModeId);
+            if (!next) {
+                throw new Error(`[hover] unknown modeId "${newModeId}"`);
+            }
+            currentModeId = newModeId;
+            if (next.hooks?.['hover:mode:activate']) {
+                const ctx = {
+                    devRoot,
+                    broadcast: broadcastPluginEvent,
+                    modeId: newModeId,
+                    setChromeProxy(proxy) {
+                        modeChromeProxy = proxy;
+                    },
+                    setMcpServerEnv(id, env) {
+                        mcpEnvOverrides.set(id, env);
+                    },
+                };
+                try {
+                    await next.hooks['hover:mode:activate'](ctx);
+                }
+                catch (err) {
+                    // Activate failed half-way — roll back state so we don't
+                    // pretend to be in `newModeId` with no sidecars running.
+                    // Widget still trusts the broadcast below to learn we're back
+                    // to default. The error is rethrown so the caller can surface
+                    // it to the user.
+                    modeChromeProxy = null;
+                    mcpEnvOverrides.clear();
+                    currentModeId = null;
+                    broadcastModes();
+                    throw err;
+                }
+            }
+        }
+        broadcastModes();
+    };
     // Cache the agent-availability list. The PATH scan is cheap (one `which`
     // per registered agent) but we still don't want to re-run it on every
     // hello; a single Vite dev server typically sees the widget connect and
@@ -161,10 +372,23 @@ export async function startService(opts) {
             payload: { agentId: currentAgentId, model, version: PROTOCOL_VERSION },
         });
         // Send the agent list as a follow-up event so the widget can render the
-        // dropdown immediately on connect / reconnect (e.g. after HMR).
-        void getAvailability(false).then(available => {
-            send(ws, { type: 'agents', payload: { current: currentAgentId, available } });
+        // dropdown immediately on connect / reconnect (e.g. after HMR). The
+        // socket may have closed between scheduling and firing, so guard the
+        // send and catch any availability-probe rejection — otherwise it
+        // surfaces as an unhandled rejection in strict-mode Node.
+        void getAvailability(false)
+            .then(available => {
+            sendIfOpen(ws, {
+                type: 'agents',
+                payload: { current: currentAgentId, available },
+            });
+        })
+            .catch(err => {
+            console.warn('[hover] agents broadcast failed:', err);
         });
+        // Send the mode catalogue too, so the widget can render the mode
+        // toggle immediately. Empty list when no plugins are loaded.
+        broadcastModes(ws);
         let busy = false;
         let inflight = null;
         let cancelled = false;
@@ -210,6 +434,46 @@ export async function startService(opts) {
                 cancel();
                 return;
             }
+            if (msg.type === 'list-modes') {
+                broadcastModes(ws);
+                return;
+            }
+            if (msg.type === 'set-mode') {
+                if (busy) {
+                    send(ws, {
+                        type: 'error',
+                        payload: { message: 'set-mode: a command is already running; stop it first' },
+                    });
+                    return;
+                }
+                const wanted = msg.payload?.modeId ?? null;
+                if (wanted !== null && typeof wanted !== 'string') {
+                    send(ws, {
+                        type: 'error',
+                        payload: { message: 'set-mode: modeId must be a string or null' },
+                    });
+                    return;
+                }
+                if (wanted !== null && !pluginsByModeId.has(wanted)) {
+                    send(ws, {
+                        type: 'error',
+                        payload: { message: `set-mode: unknown modeId "${wanted}"` },
+                    });
+                    return;
+                }
+                try {
+                    await switchMode(wanted);
+                }
+                catch (err) {
+                    send(ws, {
+                        type: 'error',
+                        payload: {
+                            message: `set-mode failed: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    });
+                }
+                return;
+            }
             if (msg.type === 'list-agents') {
                 // Force a refresh — the user may have just installed a new CLI
                 // and clicked the dropdown to see the change.
@@ -270,15 +534,15 @@ export async function startService(opts) {
                 return;
             }
             if (msg.type === 'check-cdp') {
-                await handleCheckCdp(ws, msg, cdpUrl);
+                await handleCheckCdp(ws, msg, cdpUrl, effectiveLaunchExtras());
                 return;
             }
             if (msg.type === 'launch-chrome') {
-                await handleLaunchChrome(ws, msg, cdpUrl);
+                await handleLaunchChrome(ws, msg, cdpUrl, effectiveLaunchExtras());
                 return;
             }
             if (msg.type === 'focus-debug') {
-                await handleFocusDebug(ws, msg, cdpUrl);
+                await handleFocusDebug(ws, msg, cdpUrl, effectiveLaunchExtras());
                 return;
             }
             if (msg.type !== 'command')
@@ -300,11 +564,22 @@ export async function startService(opts) {
             cancelled = false;
             inflight = new AbortController();
             try {
+                // Build the MCP config first — it's pure local file IO and lets
+                // us assert plugin-contributed servers landed in the config even
+                // when CDP preflight subsequently fails (useful for smoke tests
+                // that don't have a real debug Chrome wired up).
+                const mcpConfig = buildMcpConfig();
                 // Preflight: refuse to invoke if CDP isn't reachable. Otherwise the
                 // Playwright MCP server would silently launch its own Chromium —
                 // and Hover's premise is to drive the user's existing Chrome (with
                 // their dev state, cookies, devtools open), never spawn a fresh one.
-                const cdp = await getPreflight(cdpUrl);
+                // In an active mode, the relevant CDP endpoint may be the mode's
+                // own port (e.g. 9333 for security), not the default cdpUrl.
+                const preflightExtras = effectiveLaunchExtras();
+                const preflightCdpUrl = preflightExtras?.cdpPort
+                    ? `http://localhost:${preflightExtras.cdpPort}`
+                    : cdpUrl;
+                const cdp = await getPreflight(preflightCdpUrl);
                 if (!cdp.ok) {
                     send(ws, {
                         type: 'event',
@@ -328,9 +603,28 @@ export async function startService(opts) {
                 // re-sending them fragments Anthropic's prompt-cache fingerprint
                 // (cache hits require byte-identical system prompts across turns).
                 // See cdpHint.ts for the why.
-                const appendSystemPrompt = resumeSessionId
+                let appendSystemPrompt = resumeSessionId
                     ? buildCdpHintResume(cdp.tabs)
                     : buildCdpHint(cdp.tabs);
+                // Add plugin-contributed prompt additions whose scope includes the
+                // current mode (or '*' for always-on). Walks ALL loaded plugins,
+                // not just the active-mode plugin — a plugin that contributes
+                // an always-on prompt without contributing a mode is a valid
+                // shape (e.g. a future "always remind the agent of these
+                // project conventions" plugin).
+                for (const p of plugins) {
+                    for (const add of p.systemPromptAdditions ?? []) {
+                        // Default scope: if the plugin has a mode, the prompt is
+                        // gated to that mode; if it doesn't have a mode, the prompt
+                        // is always-on (treated as if activeInModes was '*').
+                        const scope = add.activeInModes ?? (p.mode ? [p.mode.id] : ['*']);
+                        const inScope = scope.includes('*') ||
+                            (currentModeId !== null && scope.includes(currentModeId));
+                        if (inScope) {
+                            appendSystemPrompt = `${appendSystemPrompt}\n\n${add.text}`;
+                        }
+                    }
+                }
                 // Snapshot the agent id so a switch-agent message during the run
                 // can't smear two agents across one invocation. (We also gate
                 // switch-agent on `busy`, but defense in depth.)
@@ -343,6 +637,25 @@ export async function startService(opts) {
                 // a soft one gets nothing and relies on its descriptor's built-in
                 // sandbox flags + developer_instructions.
                 const isHardSandbox = invokedDescriptor?.sandboxStrength === 'hard';
+                // Active mode's plugin-contributed MCP server ids — added to the
+                // hard-sandbox allow list so Claude can actually call them. Claude
+                // sanitises non-alphanumeric chars in the id when forming tool
+                // names (e.g. "@hover-dev/security:flows" → "mcp__hover_dev_security_flows"),
+                // and `--allowedTools mcp__foo` matches every tool under that
+                // prefix. We pass the prefix `mcp__<sanitized>` so all of the
+                // server's tools are reachable.
+                const sanitize = (s) => s.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+                const activePluginMcpIds = [];
+                if (currentModeId) {
+                    for (const p of plugins) {
+                        for (const srv of p.mcpServers ?? []) {
+                            const scope = srv.activeInModes ?? (p.mode ? [p.mode.id] : []);
+                            if (scope.includes('*') || scope.includes(currentModeId)) {
+                                activePluginMcpIds.push(`mcp__${sanitize(srv.id)}`);
+                            }
+                        }
+                    }
+                }
                 for await (const ev of invokeAgent({
                     agentId: invokedAgentId,
                     prompt: text,
@@ -354,27 +667,15 @@ export async function startService(opts) {
                     appendSystemPrompt,
                     // Skill stays in the allow list so saved skills under
                     // <devRoot>/.claude/skills/ can be invoked. mcp__playwright covers
-                    // every browser tool.
-                    allowedTools: isHardSandbox ? ['mcp__playwright', 'Skill'] : undefined,
+                    // every browser tool. Plugin-contributed MCPs are appended when
+                    // the corresponding mode is active.
+                    allowedTools: isHardSandbox
+                        ? ['mcp__playwright', 'Skill', ...activePluginMcpIds]
+                        : undefined,
                     disallowedTools: isHardSandbox
-                        ? [
-                            // file / shell / data access — never appropriate for browser driving
-                            'Bash', 'BashOutput', 'KillBash',
-                            'Edit', 'MultiEdit', 'Write', 'Read', 'NotebookEdit',
-                            'Grep', 'Glob', 'Task', 'TodoWrite',
-                            'WebFetch', 'WebSearch',
-                            // plan / worktree / cron / notification — irrelevant in -p mode
-                            'EnterPlanMode', 'ExitPlanMode',
-                            'EnterWorktree', 'ExitWorktree',
-                            'CronCreate', 'CronDelete', 'CronList',
-                            'PushNotification', 'RemoteTrigger',
-                            // task & tool introspection added in claude 2.1.x — let through and
-                            // the agent will burn turns exploring instead of executing
-                            'ToolSearch',
-                            'Monitor', 'TaskOutput', 'TaskStop',
-                            'AskUserQuestion',
-                            'ShareOnboardingGuide',
-                        ]
+                        ? (invokedDescriptor?.defaultDisallowedTools
+                            ? [...invokedDescriptor.defaultDisallowedTools]
+                            : undefined)
                         : undefined,
                     maxBudgetUsd,
                     model,
@@ -386,20 +687,32 @@ export async function startService(opts) {
                 }
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                const errorEvent = {
-                    kind: 'session_end',
-                    isError: true,
-                    summary: message,
-                };
-                if (ws.readyState === WebSocket.OPEN) {
-                    send(ws, { type: 'event', payload: errorEvent });
+                // A user-initiated cancel() already sent a synthetic session_end
+                // {cancelled:true}. The subsequent AbortError surfacing here would
+                // otherwise produce a second session_end{isError:true}, leaving the
+                // widget to reconcile two terminal events for one run. CDP isn't
+                // suspect either — the user just stopped — so skip preflight
+                // invalidation too.
+                if (!cancelled) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    const errorEvent = {
+                        kind: 'session_end',
+                        isError: true,
+                        summary: message,
+                    };
+                    sendIfOpen(ws, { type: 'event', payload: errorEvent });
+                    // Force the next command to re-probe CDP. The error could be from
+                    // Chrome dying, MCP spawning a stray Chromium, the user closing
+                    // their debug window — anything that would make a cached "all
+                    // healthy" result lie. Invalidate the mode-effective URL (see
+                    // preflightCdpUrl above) — not the static cdpUrl — so security
+                    // mode invalidations don't no-op against the default port.
+                    const invalExtras = effectiveLaunchExtras();
+                    const invalCdpUrl = invalExtras?.cdpPort
+                        ? `http://localhost:${invalExtras.cdpPort}`
+                        : cdpUrl;
+                    invalidatePreflight(invalCdpUrl);
                 }
-                // Force the next command to re-probe CDP. The error could be from
-                // Chrome dying, MCP spawning a stray Chromium, the user closing
-                // their debug window — anything that would make a cached "all
-                // healthy" result lie.
-                invalidatePreflight(cdpUrl);
             }
             finally {
                 busy = false;
@@ -409,8 +722,34 @@ export async function startService(opts) {
     });
     return {
         port,
-        close: () => new Promise((res, rej) => {
-            wss.close(err => (err ? rej(err) : res()));
-        }),
+        async close() {
+            // Deactivate the active mode first, then run every plugin's
+            // shutdown hook (regardless of which mode is active — a plugin may
+            // own background state even outside its mode). Best-effort: log
+            // and continue on individual failures so one buggy plugin doesn't
+            // strand the others' sidecars.
+            if (currentModeId) {
+                try {
+                    await switchMode(null);
+                }
+                catch (err) {
+                    process.stderr.write(`[hover] error deactivating mode during shutdown: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            for (const p of plugins) {
+                const hook = p.hooks?.['hover:service:shutdown'];
+                if (!hook)
+                    continue;
+                try {
+                    await hook({ devRoot, broadcast: broadcastPluginEvent });
+                }
+                catch (err) {
+                    process.stderr.write(`[hover] plugin "${p.name}" shutdown failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            await new Promise((res, rej) => {
+                wss.close(err => (err ? rej(err) : res()));
+            });
+        },
     };
 }