wave-agent-sdk 1.2.0 → 1.3.0

package/dist/managers/messageManager.d.ts

@@ -1,8 +1,9 @@
 import { UserMessageParams, type AgentToolBlockUpdateParams, type ToolBlockUpdateCallbackParams, type AddNotificationMessageParams } from "../utils/messageOperations.js";
-import type { Message, Usage } from "../types/index.js";
+import type { Message, Usage, InvokedSkillRecord } from "../types/index.js";
 import { SessionData } from "../services/session.js";
 import { ChatCompletionMessageFunctionToolCall } from "openai/resources.js";
 import type { MemoryRule } from "../types/memoryRule.js";
+import { type NestedMemoryFile } from "../utils/nestedMemory.js";
 import { Container } from "../utils/container.js";
 export interface MessageManagerCallbacks {
     onSessionIdChange?: (sessionId: string) => void;
@@ -59,11 +60,21 @@ export declare class MessageManager {
     private savedMessageCount;
     private pendingFileReadTriggers;
     private loadedRuleIds;
+    private pendingNestedMemoryTriggers;
+    private loadedNestedMemoryPaths;
     private recentFileReads;
     private invokedSkills;
     private sessionType;
     private subagentType?;
     private _usages;
+    /**
+     * This session's user-set title, as last known to this process (set on
+     * rename, or recovered from the transcript on resume). It is the fallback
+     * `reAppendSessionMetadata` writes back at EOF once the `custom-title` entry
+     * has been pushed out of the listing's tail window — at which point the file
+     * itself can no longer answer "what was this session called".
+     */
+    private customTitle?;
     constructor(container: Container, options: MessageManagerOptions);
     private get memoryRuleManager();
     private get memoryService();
@@ -74,6 +85,13 @@ export declare class MessageManager {
     getDisplayMessages(): Message[];
     getUsages(): Usage[];
     getLatestTotalTokens(): number;
+    /**
+     * Re-point this manager at another working directory (in-session session
+     * switch). The encoded workdir and the transcript path are both derived from
+     * it, so they must move together with it: otherwise the next append would
+     * create a second copy of the same session file under the old project dir.
+     */
+    setWorkdir(workdir: string): void;
     getWorkdir(): string;
     /**
      * Process pending file read triggers: match against conditional rules,
@@ -111,6 +129,19 @@ export declare class MessageManager {
      * conditional memory rules before the next AI call.
      */
     triggerFileRead(filePath: string): void;
+    /**
+     * Record an absolute path whose read may pull in a nested memory file
+     * (`AGENTS.md` in one of its ancestor directories). Separate from
+     * `triggerFileRead`: rule matching needs workdir-relative paths, the nested
+     * walk needs absolute ones.
+     */
+    triggerNestedMemory(filePath: string): void;
+    /**
+     * Resolve nested memory files for the paths read since the last call,
+     * outermost first. Clears the pending set; dedup is session-scoped via
+     * `loadedNestedMemoryPaths`.
+     */
+    collectNestedMemoryFiles(): Promise<NestedMemoryFile[]>;
     /**
      * Check if a file has been read (for read-before-edit enforcement).
      * Uses recentFileReads Map populated from Read tool execution.
@@ -124,6 +155,16 @@ export declare class MessageManager {
      */
     saveSession(): Promise<void>;
     setlatestTotalTokens(latestTotalTokens: number): void;
+    getCustomTitle(): string | undefined;
+    setCustomTitle(customTitle: string | undefined): void;
+    /**
+     * Re-append the session's metadata entries at EOF, so they stay inside the
+     * tail window the session list reads. Called at the sparse points where the
+     * transcript is about to be read back by another process (exit, compaction,
+     * resume, rewind); doing it per save would cost a tail read plus a line on
+     * every message.
+     */
+    reAppendSessionMetadata(): Promise<void>;
     /**
      * Clear messages
      */
@@ -214,7 +255,9 @@ export declare class MessageManager {
      */
     truncateHistory(index: number, reversionManager?: import("./reversionManager.js").ReversionManager): Promise<void>;
     /**
-     * Rewrite the session file with the current messages.
+     * Drop everything past the first `keepMessageCount` messages from the
+     * session file. The rewrite is a filter over the file's own lines, so the
+     * metadata header, the user-set title and any other reserved entry survive.
      */
     private rewriteSessionFile;
     /**
@@ -242,11 +285,11 @@ export declare class MessageManager {
      */
     private extractSkillInvocationsFromMessage;
     /**
-     * Get recently invoked skill names, sorted by timestamp (newest first).
+     * Get recently invoked skills, sorted by timestamp (newest first).
      * @param maxSkills - Maximum number of skills to return
-     * @returns Array of skill names sorted by recency
+     * @returns Invoked skill records sorted by recency
      */
-    getInvokedSkillNames(maxSkills?: number): string[];
+    getInvokedSkills(maxSkills?: number): InvokedSkillRecord[];
     /**
      * Clear all invoked skills (e.g., after compaction).
      */

package/dist/managers/messageManager.js

@@ -1,9 +1,12 @@
 import { addAssistantMessageToMessages, updateToolBlockInMessage, addErrorBlockToMessage, addUserMessageToMessages, updateUserMessageInMessages, removeLastUserMessage, addToolBlockToMessageInMessages, addNotificationMessageToMessages, generateMessageId, sliceFromLastCompact, } from "../utils/messageOperations.js";
 import { getLastApiRounds } from "../utils/groupMessagesByApiRound.js";
-import { join, isAbsolute, relative } from "path";
-import { appendMessages, createSession, generateSessionId, SESSION_DIR, } from "../services/session.js";
+import { join, isAbsolute, relative, resolve } from "path";
+import { appendMessages, createSession, generateSessionId, 
+// Aliased: this class exposes a `reAppendSessionMetadata` method of its own.
+reAppendSessionMetadata as reAppendSessionMetadataToFile, truncateSession, SESSION_DIR, } from "../services/session.js";
 import { pathEncoder } from "../utils/pathEncoder.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
+import { findNestedMemoryFiles, } from "../utils/nestedMemory.js";
 import { READ_TOOL_NAME } from "../constants/tools.js";
 // Cap for recentFileReads: content is only consumed by getRecentFileReads
 // (top 5 for post-compact restoration), so bound both the entry count and the
@@ -25,8 +28,10 @@ export class MessageManager {
         this.displayMessages = [];
         this.pendingFileReadTriggers = new Set(); // File paths read via Read tool, awaiting rule matching
         this.loadedRuleIds = new Set(); // IDs of conditional rules already injected as meta messages
+        this.pendingNestedMemoryTriggers = new Set(); // Absolute paths read since the last nested-memory scan
+        this.loadedNestedMemoryPaths = new Set(); // Nested memory files already injected (session-scoped, never evicted)
         this.recentFileReads = new Map(); // Track file read contents
-        this.invokedSkills = new Map(); // Track invoked skill names
+        this.invokedSkills = new Map(); // Track invoked skills
         this._usages = [];
         this.sessionId = generateSessionId();
         this.messages = [];
@@ -72,6 +77,20 @@ export class MessageManager {
     getLatestTotalTokens() {
         return this.latestTotalTokens;
     }
+    /**
+     * Re-point this manager at another working directory (in-session session
+     * switch). The encoded workdir and the transcript path are both derived from
+     * it, so they must move together with it: otherwise the next append would
+     * create a second copy of the same session file under the old project dir.
+     */
+    setWorkdir(workdir) {
+        if (this.workdir === workdir) {
+            return;
+        }
+        this.workdir = workdir;
+        this.encodedWorkdir = pathEncoder.encodeSync(workdir);
+        this.transcriptPath = this.computeTranscriptPath();
+    }
     getWorkdir() {
         return this.workdir;
     }
@@ -174,6 +193,31 @@ export class MessageManager {
             : filePath;
         this.pendingFileReadTriggers.add(normalizedPath);
     }
+    /**
+     * Record an absolute path whose read may pull in a nested memory file
+     * (`AGENTS.md` in one of its ancestor directories). Separate from
+     * `triggerFileRead`: rule matching needs workdir-relative paths, the nested
+     * walk needs absolute ones.
+     */
+    triggerNestedMemory(filePath) {
+        this.pendingNestedMemoryTriggers.add(isAbsolute(filePath) ? filePath : resolve(this.workdir, filePath));
+    }
+    /**
+     * Resolve nested memory files for the paths read since the last call,
+     * outermost first. Clears the pending set; dedup is session-scoped via
+     * `loadedNestedMemoryPaths`.
+     */
+    async collectNestedMemoryFiles() {
+        if (this.pendingNestedMemoryTriggers.size === 0)
+            return [];
+        const filePaths = Array.from(this.pendingNestedMemoryTriggers);
+        this.pendingNestedMemoryTriggers.clear();
+        const memories = [];
+        for (const filePath of filePaths) {
+            memories.push(...(await findNestedMemoryFiles(filePath, this.workdir, this.loadedNestedMemoryPaths)));
+        }
+        return memories;
+    }
     /**
      * Check if a file has been read (for read-before-edit enforcement).
      * Uses recentFileReads Map populated from Read tool execution.
@@ -268,6 +312,27 @@ export class MessageManager {
             this.callbacks.onLatestTotalTokensChange?.(latestTotalTokens);
         }
     }
+    getCustomTitle() {
+        return this.customTitle;
+    }
+    setCustomTitle(customTitle) {
+        this.customTitle = customTitle;
+    }
+    /**
+     * Re-append the session's metadata entries at EOF, so they stay inside the
+     * tail window the session list reads. Called at the sparse points where the
+     * transcript is about to be read back by another process (exit, compaction,
+     * resume, rewind); doing it per save would cost a tail read plus a line on
+     * every message.
+     */
+    async reAppendSessionMetadata() {
+        try {
+            await reAppendSessionMetadataToFile(this.sessionId, this.workdir, this.customTitle, this.sessionType);
+        }
+        catch (error) {
+            logger?.error("Failed to re-append session metadata:", error);
+        }
+    }
     /**
      * Clear messages
      */
@@ -277,6 +342,9 @@ export class MessageManager {
         this.setSessionId(newSessionId);
         this.setlatestTotalTokens(0);
         this.savedMessageCount = 0; // Reset saved message count
+        // The title belongs to the session that was just abandoned: the new
+        // session id starts untitled until the user renames it.
+        this.customTitle = undefined;
     }
     /**
      * Trigger the rewind UI callback
@@ -295,6 +363,10 @@ export class MessageManager {
         });
         this.displayMessages = [...sessionData.messages];
         this.setlatestTotalTokens(sessionData.metadata.latestTotalTokens);
+        // Recovered by the whole-file scan on load: from here on it is the
+        // in-memory fallback that survives the title entry sliding out of the
+        // tail window.
+        this.customTitle = sessionData.metadata.customTitle;
         // Rebuild loadedRuleIds from persisted meta messages (session restore)
         this.rebuildLoadedRuleIds();
         // Set saved message count to the number of loaded messages since they're already saved
@@ -448,6 +520,9 @@ export class MessageManager {
         // message id appearing exactly once (dedup-skipped, aligned with CC).
         const { appendMessages } = await import("../services/session.js");
         await appendMessages(this.sessionId, [compactMessage], this.workdir, this.sessionType);
+        // Compaction leaves the transcript readable by the next process that
+        // lists sessions, so this is a flush point for the metadata entries.
+        await this.reAppendSessionMetadata();
         // Update in-memory state: the API context folds to [compact, ...last
         // rounds], while the UI display stream keeps the full history and appends
         // the compact block at the end.
@@ -459,6 +534,11 @@ export class MessageManager {
         // Clear and rebuild loaded rule IDs from remaining meta messages
         this.clearLoadedRuleIds();
         this.rebuildLoadedRuleIds();
+        // Nested memory has no marker to rebuild from, so the dedup set is dropped
+        // outright: compaction may have summarized the injected text away, and
+        // re-injecting it on the next read of that subtree beats never showing it
+        // again in this session.
+        this.loadedNestedMemoryPaths.clear();
         // Trigger compaction callback
         this.callbacks.onCompactBlockAdded?.(compactedContent);
     }
@@ -737,8 +817,16 @@ export class MessageManager {
         if (reversionManager && messageIdsToRemove.length > 0) {
             await reversionManager.revertTo(messageIdsToRemove, messages);
         }
-        // Rewrite file with truncated messages (full history kept on disk)
-        await this.rewriteSessionFile(newMessages);
+        // Keep the first `newMessages.length` messages on disk. Note the count is
+        // the message index, not a file operation: the rewrite walks the file's own
+        // lines and carries reserved entries (metadata header, custom-title) over.
+        await this.rewriteSessionFile(newMessages.length);
+        // The rewrite drops messages but keeps the reserved entries where they sit,
+        // which is not enough for the title: the session list reads only the file's
+        // tail window, and a title written early can end up outside it (the
+        // rewrite keeps the *first* messages, so the survivors after it are exactly
+        // what pushes it away). Re-append it at EOF like the other flush points do.
+        await this.reAppendSessionMetadata();
         // The UI keeps the full truncated thread; the agent context folds at the
         // last compact boundary so the agent only sees messages from the latest
         // compact summary forward — matching the compact and resume behaviors.
@@ -751,18 +839,13 @@ export class MessageManager {
         this.savedMessageCount = this.messages.length;
     }
     /**
-     * Rewrite the session file with the current messages.
+     * Drop everything past the first `keepMessageCount` messages from the
+     * session file. The rewrite is a filter over the file's own lines, so the
+     * metadata header, the user-set title and any other reserved entry survive.
      */
-    async rewriteSessionFile(messages) {
+    async rewriteSessionFile(keepMessageCount) {
         try {
-            const { writeFile } = await import("fs/promises");
-            const content = messages
-                .map((m) => {
-                const { timestamp, ...rest } = m;
-                return JSON.stringify({ timestamp, ...rest });
-            })
-                .join("\n") + (messages.length > 0 ? "\n" : "");
-            await writeFile(this.transcriptPath, content, "utf8");
+            await truncateSession(this.sessionId, keepMessageCount, this.workdir, this.sessionType);
         }
         catch (error) {
             logger?.error("Failed to rewrite session file:", error);
@@ -859,6 +942,10 @@ export class MessageManager {
                         this.invokedSkills.set(skillName, {
                             skillName,
                             timestamp: Date.now(),
+                            // 模型当时实际看到的那份正文（已替换 ${WAVE_SKILL_DIR} 等占位符、
+                            // 首行带 `Base directory for this skill:`）——压缩后回灌直接复用它，
+                            // 不能重新读文件原文（spec core/message-compact 场景 4）。
+                            content: block.result,
                         });
                     }
                 }
@@ -869,15 +956,14 @@ export class MessageManager {
         }
     }
     /**
-     * Get recently invoked skill names, sorted by timestamp (newest first).
+     * Get recently invoked skills, sorted by timestamp (newest first).
      * @param maxSkills - Maximum number of skills to return
-     * @returns Array of skill names sorted by recency
+     * @returns Invoked skill records sorted by recency
      */
-    getInvokedSkillNames(maxSkills = 10) {
-        const sorted = Array.from(this.invokedSkills.entries())
-            .sort(([, a], [, b]) => b.timestamp - a.timestamp)
+    getInvokedSkills(maxSkills = 10) {
+        return Array.from(this.invokedSkills.values())
+            .sort((a, b) => b.timestamp - a.timestamp)
             .slice(0, maxSkills);
-        return sorted.map(([, { skillName }]) => skillName);
     }
     /**
      * Clear all invoked skills (e.g., after compaction).

package/dist/managers/permissionManager.d.ts

@@ -18,6 +18,12 @@ export declare function resolveAdditionalDirectory(dir: string, workdir: string
 export interface PermissionManagerOptions {
     /** Configured permission mode from settings */
     configuredPermissionMode?: PermissionMode;
+    /**
+     * Session-level bypass authorization (see `captureBypassAuthorization`).
+     * Passed explicitly by subagents so they inherit the parent session's value
+     * instead of re-deriving it from their own (mid-session) mode.
+     */
+    bypassAuthorization?: boolean;
     /** Allowed rules from settings */
     allowedRules?: string[];
     /** Denied rules from settings */
@@ -40,6 +46,15 @@ export interface PermissionManagerOptions {
 export declare class PermissionManager {
     private container;
     private configuredPermissionMode?;
+    /**
+     * Session-level bypass authorization: the permission mode in effect when the
+     * session was created was `bypassPermissions`. Frozen at session start, so a
+     * later mode switch (or config reload) can never grant it. Its only effect is
+     * that plan mode skips permission checks instead of re-asking — mirroring
+     * Claude Code's `isBypassPermissionsModeAvailable`. `undefined` = not
+     * captured yet (subagents get an explicit value instead).
+     */
+    private bypassAuthorization?;
     private allowedRules;
     private deniedRules;
     private instanceAllowedRules;
@@ -73,6 +88,17 @@ export declare class PermissionManager {
      * Get the configured default mode
      */
     getConfiguredPermissionMode(): PermissionMode | undefined;
+    /**
+     * 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(): void;
+    /**
+     * Whether this session keeps bypass semantics while in plan mode
+     */
+    getBypassAuthorization(): boolean;
     /**
      * Get all currently allowed rules (user-defined)
      */
@@ -94,6 +120,13 @@ export declare class PermissionManager {
      * Unlike addPermissionRule, this does NOT persist to settings.local.json.
      */
     addInstanceAllowedRule(rule: string): void;
+    /**
+     * 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: string): boolean;
     /**
      * Get all additional directories
      */
@@ -143,6 +176,13 @@ export declare class PermissionManager {
      * Add a system-level additional directory that is persistent across configuration reloads
      */
     addSystemAdditionalDirectory(directory: string): void;
+    /**
+     * 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: string): void;
     /**
      * Set the current plan file path
      */

package/dist/managers/permissionManager.js

@@ -8,12 +8,12 @@
 import path from "node:path";
 import os from "node:os";
 import { minimatch } from "minimatch";
-import { RESTRICTED_TOOLS } from "../types/permissions.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*)",
@@ -87,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 || [];
@@ -135,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)
      */
@@ -168,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
      */
@@ -258,6 +295,16 @@ export class PermissionManager {
             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
      */
@@ -434,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" };
             }
@@ -615,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);
                 }
             }
         }

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