wave-agent-sdk 1.1.5 → 1.3.0

package/dist/managers/permissionManager.js

@@ -6,12 +6,14 @@
  * handles custom callback integration.
  */
 import path from "node:path";
+import os from "node:os";
 import { minimatch } from "minimatch";
-import { RESTRICTED_TOOLS } from "../types/permissions.js";
-import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, stripGitScopePrefix, DANGEROUS_COMMANDS, READ_ONLY_COMMANDS, } from "../utils/bashParser.js";
+import { RESTRICTED_TOOLS, USER_INTERACTION_REQUIRED_TOOLS, } from "../types/permissions.js";
+import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, stripGitScopePrefix, DANGEROUS_COMMANDS, READ_ONLY_COMMANDS, PATH_COMMANDS, extractPathArgs, } from "../utils/bashParser.js";
+import { parseBashStructure, } from "../utils/bashStructure/index.js";
 import { isPathInside } from "../utils/pathSafety.js";
 import { toWindowsPath } from "../utils/path.js";
-import { BASH_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, READ_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
+import { BASH_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, READ_TOOL_NAME, } from "../constants/tools.js";
 const DEFAULT_ALLOWED_RULES = [
     "Bash(git status*)",
     "Bash(git diff*)",
@@ -55,6 +57,22 @@ const DEFAULT_ALLOWED_RULES = [
     "Bash(sleep*)",
 ];
 import { logger } from "../utils/globalLogger.js";
+/**
+ * Resolve an additional-directory config entry to an absolute path.
+ * Supports `~` / `~/` prefixes (expanded against the user home directory,
+ * aligned with Claude Code's expandPath) alongside absolute paths and paths
+ * relative to the working directory.
+ */
+export function resolveAdditionalDirectory(dir, workdir) {
+    if (dir === "~" || dir.startsWith("~/")) {
+        const expanded = dir === "~" ? os.homedir() : path.join(os.homedir(), dir.slice(2));
+        return path.resolve(expanded);
+    }
+    if (workdir && !path.isAbsolute(dir)) {
+        return path.resolve(workdir, dir);
+    }
+    return path.resolve(dir);
+}
 export class PermissionManager {
     constructor(container, options = {}) {
         this.container = container;
@@ -69,6 +87,7 @@ export class PermissionManager {
         this.hasExitedPlanMode = false;
         this.needsPlanModeExitAttachment = false;
         this.configuredPermissionMode = options.configuredPermissionMode;
+        this.bypassAuthorization = options.bypassAuthorization;
         this.allowedRules = options.allowedRules || [];
         this.deniedRules = options.deniedRules || [];
         this.instanceAllowedRules = options.instanceAllowedRules || [];
@@ -117,6 +136,28 @@ export class PermissionManager {
     getConfiguredPermissionMode() {
         return this.configuredPermissionMode;
     }
+    /**
+     * Freeze the session-level bypass authorization from the permission mode in
+     * effect when the session was created (CLI mode > configured default mode >
+     * `default`). No-op once captured, so switching to `bypassPermissions`
+     * mid-session does not grant it.
+     */
+    captureBypassAuthorization() {
+        if (this.bypassAuthorization !== undefined) {
+            return;
+        }
+        const sessionMode = this.container.has("PermissionMode")
+            ? this.container.get("PermissionMode")
+            : undefined;
+        this.bypassAuthorization =
+            this.getCurrentEffectiveMode(sessionMode) === "bypassPermissions";
+    }
+    /**
+     * Whether this session keeps bypass semantics while in plan mode
+     */
+    getBypassAuthorization() {
+        return this.bypassAuthorization === true;
+    }
     /**
      * Get all currently allowed rules (user-defined)
      */
@@ -150,6 +191,20 @@ export class PermissionManager {
             this.instanceAllowedRules.push(rule);
         }
     }
+    /**
+     * Remove an instance-level allowed rule added via addInstanceAllowedRule.
+     * Used when a builtin plugin that contributed a helper-script grant is
+     * unloaded, so the grant does not outlive the plugin.
+     * @returns true if the rule was present
+     */
+    removeInstanceAllowedRule(rule) {
+        const index = this.instanceAllowedRules.indexOf(rule);
+        if (index === -1) {
+            return false;
+        }
+        this.instanceAllowedRules.splice(index, 1);
+        return true;
+    }
     /**
      * Get all additional directories
      */
@@ -220,22 +275,13 @@ export class PermissionManager {
      * Update the additional directories (e.g., when configuration reloads)
      */
     updateAdditionalDirectories(directories) {
-        const workdir = this.workdir;
-        this.additionalDirectories = directories.map((dir) => {
-            if (workdir && !path.isAbsolute(dir)) {
-                return path.resolve(workdir, dir);
-            }
-            return path.resolve(dir);
-        });
+        this.additionalDirectories = directories.map((dir) => resolveAdditionalDirectory(dir, this.workdir));
     }
     /**
      * Add an instance-level additional directory (session-level, e.g. /add-dir command)
      */
     addInstanceAdditionalDirectory(directory) {
-        const workdir = this.workdir;
-        const resolvedPath = workdir && !path.isAbsolute(directory)
-            ? path.resolve(workdir, directory)
-            : path.resolve(directory);
+        const resolvedPath = resolveAdditionalDirectory(directory, this.workdir);
         if (!this.instanceAdditionalDirectories.includes(resolvedPath)) {
             this.instanceAdditionalDirectories.push(resolvedPath);
         }
@@ -244,14 +290,21 @@ export class PermissionManager {
      * Add a system-level additional directory that is persistent across configuration reloads
      */
     addSystemAdditionalDirectory(directory) {
-        const workdir = this.workdir;
-        const resolvedPath = workdir && !path.isAbsolute(directory)
-            ? path.resolve(workdir, directory)
-            : path.resolve(directory);
+        const resolvedPath = resolveAdditionalDirectory(directory, this.workdir);
         if (!this.systemAdditionalDirectories.includes(resolvedPath)) {
             this.systemAdditionalDirectories.push(resolvedPath);
         }
     }
+    /**
+     * Remove a system-level additional directory (idempotent). Used when a
+     * settings.json change revokes a privilege that was granted at construction
+     * time — e.g. turning auto-memory off removes its directory from the safe
+     * zone (core/agent-config.md scenario 6).
+     */
+    removeSystemAdditionalDirectory(directory) {
+        const resolvedPath = resolveAdditionalDirectory(directory, this.workdir);
+        this.systemAdditionalDirectories = this.systemAdditionalDirectories.filter((dir) => dir !== resolvedPath);
+    }
     /**
      * Set the current plan file path
      */
@@ -428,12 +481,17 @@ export class PermissionManager {
                 }
             }
         }
-        // If bypassPermissions mode, always allow
-        // Exception: tools that require user interaction (e.g. AskUserQuestion)
-        // must still prompt the user, matching Claude Code's requiresUserInteraction behavior.
+        // If bypassPermissions mode — or plan mode in a session that was authorized
+        // to bypass at creation time — always allow.
+        // Exception: tools that require user interaction (AskUserQuestion and
+        // ExitPlanMode) must still prompt, matching Claude Code's
+        // requiresUserInteraction behavior (its step 1e returns the tool's ask
+        // result before the bypass step).
         // Worktree safety check above runs unconditionally, so bypass never skips it.
-        if (context.permissionMode === "bypassPermissions") {
-            const requiresUserInteraction = context.toolName === ASK_USER_QUESTION_TOOL_NAME;
+        const bypassesPermissionChecks = context.permissionMode === "bypassPermissions" ||
+            (context.permissionMode === "plan" && this.getBypassAuthorization());
+        if (bypassesPermissionChecks) {
+            const requiresUserInteraction = USER_INTERACTION_REQUIRED_TOOLS.includes(context.toolName);
             if (!requiresUserInteraction) {
                 return { behavior: "allow" };
             }
@@ -609,9 +667,12 @@ export class PermissionManager {
             const targetPath = toolInput?.file_path;
             const workdir = toolInput?.workdir;
             if (targetPath) {
-                const { isInside } = this.isInsideSafeZone(targetPath, workdir);
+                const { isInside, resolvedPath } = this.isInsideSafeZone(targetPath, workdir);
                 if (!isInside) {
                     context.hidePersistentOption = true;
+                    // Surface the target's directory so the confirmation UI can offer
+                    // adding it to the session Safe Zone.
+                    context.outsideSafeZoneDirectory = path.dirname(resolvedPath);
                 }
             }
         }
@@ -634,20 +695,12 @@ export class PermissionManager {
                 const commandMatch = processedPart.match(/^(\w+)(\s+.*)?$/);
                 if (commandMatch) {
                     const cmd = commandMatch[1];
-                    const args = commandMatch[2]?.trim() || "";
                     // Check blacklist
                     if (DANGEROUS_COMMANDS.includes(cmd)) {
                         return true;
                     }
-                    // Check out-of-bounds for cd
-                    if (cmd === "cd") {
-                        const pathArgs = (args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || []).filter((arg) => !arg.startsWith("-")) || [];
-                        return pathArgs.some((pathArg) => {
-                            const cleanPath = pathArg.replace(/^['"](.*)['"]$/, "$1");
-                            const { isInside } = this.isInsideSafeZone(cleanPath, workdir);
-                            return !isInside;
-                        });
-                    }
+                    // Check out-of-bounds for cd and path-taking read-only commands
+                    return this.isOutOfSafeZonePart(part, workdir);
                 }
                 return false;
             });
@@ -758,6 +811,19 @@ export class PermissionManager {
             // find with dangerous flags (e.g. -exec, -delete) disqualifies
             if (cmd === "find" && isDangerousFind(part))
                 return false;
+            // Path-taking read-only commands must stay within the Safe Zone:
+            // accessing a path outside workdir / additional directories
+            // disqualifies (aligned with Claude Code's path constraints)
+            if (PATH_COMMANDS.includes(cmd)) {
+                const pathArgs = extractPathArgs(args);
+                if (pathArgs.length > 0) {
+                    if (!workdir)
+                        return false;
+                    if (!pathArgs.every((pathArg) => this.isInsideSafeZone(pathArg, workdir).isInside)) {
+                        return false;
+                    }
+                }
+            }
             return true;
         }
         // cd is not read-only but is safe if all paths are within the Safe Zone
@@ -775,6 +841,26 @@ export class PermissionManager {
         }
         return false;
     }
+    /**
+     * Check whether a bash command part takes path arguments (cd or a
+     * path-taking read-only command) that escape the Safe Zone. Used to
+     * disqualify auto-allow via DEFAULT_ALLOWED_RULES and to hide the
+     * "don't ask again" persistence option for out-of-bounds access.
+     */
+    isOutOfSafeZonePart(part, workdir) {
+        const processedPart = stripRedirections(stripEnvVars(part));
+        const commandMatch = processedPart.match(/^(\w+)(\s+.*)?$/);
+        if (!commandMatch)
+            return false;
+        const cmd = commandMatch[1];
+        if (cmd !== "cd" && !PATH_COMMANDS.includes(cmd))
+            return false;
+        const args = commandMatch[2]?.trim() || "";
+        const pathArgs = extractPathArgs(args);
+        if (pathArgs.length === 0)
+            return false;
+        return pathArgs.some((pathArg) => !this.isInsideSafeZone(pathArg, workdir).isInside);
+    }
     /**
      * Check if a tool call is allowed by persistent or temporary rules
      */
@@ -789,42 +875,80 @@ export class PermissionManager {
         ];
         if (context.toolName === BASH_TOOL_NAME && context.toolInput?.command) {
             const command = String(context.toolInput.command);
-            const parts = splitBashCommand(command);
-            if (parts.length === 0)
-                return false;
             const workdir = context.toolInput?.workdir;
-            return parts.every((part) => {
-                // Check for auto-allowed read-only commands (FR-019.2 through FR-019.7)
-                if (this.isAutoAllowedPart(part, workdir)) {
-                    return true;
-                }
-                // We create a temporary context with just this part of the command
-                const partContext = {
-                    ...context,
-                    toolInput: { ...context.toolInput, command: part },
-                };
-                if (explicitRules.some((rule) => this.matchesRule(partContext, rule))) {
-                    return true;
-                }
-                // Default rules must not auto-allow dangerous variants (write
-                // redirections, substitutions, sed -i, dangerous find) through broad
-                // rules like Bash(echo*) or Bash(cat*)
-                const isDangerousVariant = hasWriteRedirections(part) ||
-                    isDangerousFind(part) ||
-                    hasCommandSubstitution(part) ||
-                    hasProcessSubstitution(part) ||
-                    hasSedInPlace(part);
-                if (!isDangerousVariant &&
-                    DEFAULT_ALLOWED_RULES.some((rule) => this.matchesRule(partContext, rule))) {
-                    return true;
-                }
-                return !this.isRestrictedTool(context.toolName);
-            });
+            // Structure-aware expansion: compound commands and command substitutions
+            // are reduced to their leaf simple commands; each leaf is classified
+            // exactly like a top-level part of a chained command would be (spec:
+            // "复合命令与命令替换的结构感知判定").
+            const structure = parseBashStructure(command);
+            if (structure.status === "ok") {
+                if (structure.leaves.length === 0)
+                    return false;
+                return structure.leaves.every((leaf) => this.isBashLeafAllowed(leaf, workdir, context, explicitRules));
+            }
+            // Fail-closed (heredoc / process substitution / arithmetic / brace /
+            // parse failure / eval / trap / …): the command cannot be statically
+            // reduced to leaves, so it is never auto-allowed and never matches the
+            // built-in default rules. Only an explicit user rule covering the whole
+            // command may allow it.
+            const wholeContext = {
+                ...context,
+                toolInput: { ...context.toolInput, command },
+            };
+            return explicitRules.some((rule) => this.matchesRule(wholeContext, rule));
         }
         // For other tools, check if any rule matches
         const allRules = [...explicitRules, ...DEFAULT_ALLOWED_RULES];
         return allRules.some((rule) => this.matchesRule(context, rule));
     }
+    /**
+     * Classify one expanded leaf command. Every leaf of a compound command or
+     * command substitution is judged with the exact rules used for a plain
+     * command, with two structure-aware additions:
+     *
+     *  - a leaf the parser flagged `unsafe` (a bare reference to a variable whose
+     *    value is not statically known, or a command substitution inside the
+     *    leaf's own argument words) is never auto-allowed and never matches the
+     *    built-in default rules — only an explicit allow rule may cover it;
+     *  - `read` (e.g. the condition of `while read …`) only reads stdin, so it
+     *    is treated as safe when it carries no redirection of its own.
+     */
+    isBashLeafAllowed(leaf, workdir, context, explicitRules) {
+        // Check for auto-allowed read-only commands (FR-019.2 through FR-019.7)
+        if (!leaf.unsafe) {
+            if (leaf.command === "read" && !/[<>]/.test(leaf.text))
+                return true;
+            if (this.isAutoAllowedPart(leaf.text, workdir))
+                return true;
+        }
+        if (explicitRules.some((rule) => this.matchesRule(this.ruleContext(context, leaf.text), rule)) ||
+            explicitRules.some((rule) => this.matchesRule(this.ruleContext(context, unquotedLeafCommand(leaf)), rule))) {
+            return true;
+        }
+        // Default rules must not auto-allow dangerous variants (write
+        // redirections, substitutions, sed -i, dangerous find, out-of-safe-zone
+        // paths, bare-unknown-variable / in-word substitution leaves) through
+        // broad rules like Bash(echo*) or Bash(cat*)
+        const isDangerousVariant = leaf.unsafe ||
+            hasWriteRedirections(leaf.text) ||
+            isDangerousFind(leaf.text) ||
+            hasCommandSubstitution(leaf.text) ||
+            hasProcessSubstitution(leaf.text) ||
+            hasSedInPlace(leaf.text) ||
+            this.isOutOfSafeZonePart(leaf.text, workdir);
+        if (!isDangerousVariant &&
+            DEFAULT_ALLOWED_RULES.some((rule) => this.matchesRule(this.ruleContext(context, leaf.text), rule))) {
+            return true;
+        }
+        return !this.isRestrictedTool(context.toolName);
+    }
+    /** A context whose Bash command is a single part/leaf text. */
+    ruleContext(context, command) {
+        return {
+            ...context,
+            toolInput: { ...context.toolInput, command },
+        };
+    }
     /**
      * Expand a bash command into individual permission rules, filtering out safe commands.
      * Used when saving permissions to the allow list.
@@ -834,7 +958,13 @@ export class PermissionManager {
      * @returns Array of permission rules in "Bash(cmd)" format
      */
     expandBashRule(command, workdir) {
-        const parts = splitBashCommand(command);
+        // Expand compound commands structurally when possible so control-structure
+        // keywords (do/done/then/…) never leak into persisted rules. Constructs the
+        // parser cannot reduce fall back to the legacy textual part splitter.
+        const structure = parseBashStructure(command);
+        const parts = structure.status === "ok" && structure.leaves.length > 0
+            ? structure.leaves.map((leaf) => leaf.text)
+            : splitBashCommand(command);
         const rules = [];
         for (const part of parts) {
             const hasWrite = hasWriteRedirections(part);
@@ -846,23 +976,12 @@ export class PermissionManager {
                 const commandMatch = processedPart.match(/^(\w+)(\s+.*)?$/);
                 if (commandMatch) {
                     const cmd = commandMatch[1];
-                    const args = commandMatch[2]?.trim() || "";
                     if (DANGEROUS_COMMANDS.includes(cmd) ||
                         isDangerousFind(part) ||
-                        hasSedInPlace(part)) {
+                        hasSedInPlace(part) ||
+                        this.isOutOfSafeZonePart(part, workdir)) {
                         continue;
                     }
-                    if (cmd === "cd") {
-                        const pathArgs = (args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || []).filter((arg) => !arg.startsWith("-")) || [];
-                        const isOutOfBounds = pathArgs.some((pathArg) => {
-                            const cleanPath = pathArg.replace(/^['"](.*)['"]$/, "$1");
-                            const { isInside } = this.isInsideSafeZone(cleanPath, workdir);
-                            return !isInside;
-                        });
-                        if (isOutOfBounds) {
-                            continue;
-                        }
-                    }
                 }
                 const smartPrefix = hasWrite ? null : getSmartPrefix(processedPart);
                 if (smartPrefix) {
@@ -918,3 +1037,27 @@ export class PermissionManager {
         }
     }
 }
+/**
+ * Build a rule-matching form of a leaf command with quoting removed from words
+ * that are a single quoted segment (`node "scripts/x"` → `node scripts/x`).
+ * Shell quoting that does not change the executed words must not prevent a
+ * rule such as `Bash(node scripts*)` from matching a leaf like
+ * `node "scripts/$f" --dry-run`. Redirect operators/targets (the text tail
+ * beyond argv) are preserved verbatim so write-redirection guards still apply.
+ */
+function unquotedLeafCommand(leaf) {
+    const rawCommand = leaf.argv.join(" ");
+    const tail = leaf.text.slice(rawCommand.length);
+    return leaf.argv.map(unquoteWord).join(" ") + tail;
+}
+/** Strip one layer of enclosing single/double quotes from a whole word. */
+function unquoteWord(raw) {
+    if (raw.length < 2)
+        return raw;
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if ((first === '"' || first === "'") && first === last) {
+        return raw.slice(1, -1);
+    }
+    return raw;
+}

package/dist/managers/planManager.d.ts

@@ -5,6 +5,9 @@ export declare class PlanManager {
     private planDir;
     private currentPlanFilePath;
     private planEntryReminderPending;
+    /** Promise for the in-flight plan file path generation, resolved when the
+     * path is set on the PermissionManager. Cleared when leaving plan mode. */
+    private planFilePathPromise;
     constructor(container: Container);
     /**
      * Ensures the plan directory exists and generates a new plan file path with a random name
@@ -22,6 +25,12 @@ export declare class PlanManager {
      * @param mode - The current effective permission mode
      */
     handlePlanModeTransition(mode: PermissionMode): void;
+    /**
+     * Resolve once the plan file path for the current plan-mode entry has been
+     * generated and set on the PermissionManager. Resolves `undefined` when no
+     * path generation is in flight (not in plan mode, or generation failed).
+     */
+    awaitPlanFilePath(): Promise<string | undefined>;
     isPlanEntryReminderPending(): boolean;
     consumePlanEntryReminder(): void;
 }

package/dist/managers/planManager.js

@@ -11,6 +11,9 @@ export class PlanManager {
         this.container = container;
         this.currentPlanFilePath = null;
         this.planEntryReminderPending = false;
+        /** Promise for the in-flight plan file path generation, resolved when the
+         * path is set on the PermissionManager. Cleared when leaving plan mode. */
+        this.planFilePathPromise = null;
         this.planDir = path.join(os.homedir(), ".wave", "plans");
     }
     /**
@@ -60,13 +63,18 @@ export class PlanManager {
             // (prevents sending both plan_mode and plan_mode_exit on rapid toggle)
             permissionManager?.setNeedsPlanModeExitAttachment(false);
             this.planEntryReminderPending = true;
-            this.getOrGeneratePlanFilePath(messageManager?.getRootSessionId())
+            // Store the promise so callers (e.g. the CLI /plan command) can await
+            // path readiness before triggering a query — the plan mode reminder
+            // injected by AIManager only fires once the path is set.
+            this.planFilePathPromise = this.getOrGeneratePlanFilePath(messageManager?.getRootSessionId())
                 .then(({ path }) => {
                 logger?.debug("Plan file path generated", { path });
                 permissionManager?.setPlanFilePath(path);
+                return path;
             })
                 .catch((error) => {
                 logger?.error("Failed to generate plan file path", error);
+                return undefined;
             });
         }
         else if (previousMode === "plan") {
@@ -75,11 +83,21 @@ export class PlanManager {
             permissionManager?.setNeedsPlanModeExitAttachment(true);
             permissionManager?.setPlanFilePath(undefined);
             this.planEntryReminderPending = false;
+            this.planFilePathPromise = null;
         }
         else {
             permissionManager?.setPlanFilePath(undefined);
+            this.planFilePathPromise = null;
         }
     }
+    /**
+     * Resolve once the plan file path for the current plan-mode entry has been
+     * generated and set on the PermissionManager. Resolves `undefined` when no
+     * path generation is in flight (not in plan mode, or generation failed).
+     */
+    awaitPlanFilePath() {
+        return this.planFilePathPromise ?? Promise.resolve(undefined);
+    }
     isPlanEntryReminderPending() {
         return this.planEntryReminderPending;
     }

package/dist/managers/pluginManager.d.ts

@@ -1,4 +1,4 @@
-import { Plugin, PluginConfig } from "../types/index.js";
+import { Plugin, PluginConfig, PluginLoadFailure, PluginReloadResult } from "../types/index.js";
 import { Container } from "../utils/container.js";
 export interface PluginManagerOptions {
     workdir: string;
@@ -17,6 +17,17 @@ export declare class PluginManager {
     private plugins;
     private workdir;
     private enabledPlugins;
+    /** Explicit configs from the last load, replayed by reloadAllPlugins(). */
+    private lastLoadConfigs;
+    /** Failures collected by the current loadPlugins() run. */
+    private loadFailures;
+    /**
+     * Serializes plugin (re)loads. A managed-settings sync (or an early
+     * `/reload-plugins`) can ask for a reload while the startup load is still
+     * running; interleaving them would leave half-unloaded capability registries.
+     */
+    private loadChain;
+    private serialize;
     constructor(container: Container, options: PluginManagerOptions);
     private get permissionManager();
     private get skillManager();
@@ -41,8 +52,41 @@ export declare class PluginManager {
     /**
      * Load plugins from configuration
      * @param configs Array of plugin configurations
+     * @returns the plugins that failed to load
+     */
+    loadPlugins(configs: PluginConfig[]): Promise<PluginLoadFailure[]>;
+    /**
+     * The actual load. Reached through [loadPlugins] (which serializes concurrent
+     * requests) and directly from [reloadAllPlugins], which already holds the slot.
+     */
+    private doLoadPlugins;
+    /**
+     * Unload a single plugin: drop everything it contributed from the six
+     * capability registries, then forget it. Other plugins and the running
+     * session are untouched.
+     * @returns true if the plugin was loaded
+     */
+    unloadPlugin(name: string): Promise<boolean>;
+    /**
+     * Re-read every plugin in place — the `/reload-plugins` command.
+     *
+     * Unloads everything currently loaded, re-reads `enabledPlugins` from the
+     * configuration chain (so a settings edit is honored), then replays the
+     * original load order (explicit configs → installed → builtin). The session,
+     * transcript and sessionId are untouched; only the capability registries are
+     * swapped, which is what makes this an in-place reload instead of a rebuild.
+     *
+     * Unload must happen before any caller-side mutation of the plugin cache dir:
+     * hooks, MCP, LSP, skills and agents all bake absolute plugin paths at
+     * registration time, so an entry left pointing at a deleted directory is
+     * worse than a merely stale one.
+     */
+    reloadAllPlugins(): Promise<PluginReloadResult>;
+    /**
+     * Re-read enabled plugins from the merged configuration chain, falling back
+     * to the last known value when the service is unavailable.
      */
-    loadPlugins(configs: PluginConfig[]): Promise<void>;
+    private refreshEnabledPlugins;
     /**
      * Load built-in plugins bundled with the SDK (e.g. sdd).
      * Opt-in via `enabledPlugins`, keyed `<name>@builtin` (default off, consistent