wave-agent-sdk 1.1.4 → 1.2.0

package/dist/managers/permissionManager.js

@@ -6,9 +6,11 @@
  * 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 { 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";
@@ -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;
@@ -220,22 +238,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,10 +253,7 @@ 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);
         }
@@ -634,20 +640,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 +756,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 +786,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 +820,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 +903,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 +921,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 +982,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/skillManager.d.ts

@@ -16,6 +16,11 @@ export declare class SkillManager extends EventEmitter {
     private pluginSkillMetadata;
     private pluginSkillContent;
     private initialized;
+    /** Serializes full rescans (initialize / file-watcher events / deleteSkill
+     *  convergence). Overlapping scans over the shared caches must not interleave:
+     *  chaining them keeps the last completed scan in sync with the newest disk
+     *  state instead of letting an older snapshot win a race. */
+    private refreshChain;
     private fileWatcher;
     private watchEnabled;
     constructor(container: Container, options?: SkillManagerOptions);
@@ -27,6 +32,7 @@ export declare class SkillManager extends EventEmitter {
      * Refresh skills by re-discovering them
      */
     private refreshSkills;
+    private performRefresh;
     /**
      * Setup file watcher for skill directories
      */
@@ -113,4 +119,29 @@ export declare class SkillManager extends EventEmitter {
      * Register skills provided by a plugin
      */
     registerPluginSkills(pluginName: string, skills: Skill[]): void;
+    /**
+     * Directory roots that may hold deletable copies of a skill in the given
+     * discovery scope. Personal skills are scanned from three user-level dirs
+     * (~/.wave|~/.claude|~/.agents/skills) and project skills from the current
+     * project's three project dirs (.wave|.claude|.agents/skills). The discovery
+     * map merges same-named copies from these roots into a single name-keyed
+     * entry, so deleteSkill must sweep the whole set to remove a skill fully.
+     */
+    private scopeSkillRoots;
+    /**
+     * Delete a user/personal or project skill by removing its directory
+     * (containing SKILL.md). Builtin and plugin skills are read-only and
+     * cannot be deleted.
+     *
+     * A same-named skill may physically live in several same-scope directories
+     * (~/.wave/skills + ~/.claude/skills + ~/.agents/skills for user skills,
+     * .wave/.claude/.agents/skills under the project for project skills) while
+     * only the highest-priority copy is listed; every copy is removed so one
+     * delete removes the skill completely instead of re-surfacing the next
+     * copy on the next scan. Caches are then re-converged with disk before
+     * returning so the caller's follow-up metadata read reflects the result.
+     * @param name - The skill name as shown in skill metadata
+     * @returns true if the skill was deleted
+     */
+    deleteSkill(name: string): Promise<boolean>;
 }

package/dist/managers/skillManager.js

@@ -1,4 +1,4 @@
-import { readdir, stat } from "fs/promises";
+import { readdir, stat, rm } from "fs/promises";
 import { join } from "path";
 import { homedir } from "os";
 import { EventEmitter } from "events";
@@ -21,6 +21,11 @@ export class SkillManager extends EventEmitter {
         this.pluginSkillMetadata = new Map();
         this.pluginSkillContent = new Map();
         this.initialized = false;
+        /** Serializes full rescans (initialize / file-watcher events / deleteSkill
+         *  convergence). Overlapping scans over the shared caches must not interleave:
+         *  chaining them keeps the last completed scan in sync with the newest disk
+         *  state instead of letting an older snapshot win a race. */
+        this.refreshChain = Promise.resolve();
         this.fileWatcher = null;
         this.personalSkillsPath =
             options.personalSkillsPath || join(homedir(), ".wave", "skills");
@@ -53,27 +58,52 @@ export class SkillManager extends EventEmitter {
     /**
      * Refresh skills by re-discovering them
      */
-    async refreshSkills() {
-        // Clear only discovered skills (builtin/personal/project), preserve plugin skills
-        this.skillMetadata.clear();
-        this.skillContent.clear();
-        const discovery = await this.discoverSkills();
-        // Store discovered skill metadata
+    refreshSkills() {
+        // Serialize rescans: initialize / file-watcher events / deleteSkill all
+        // trigger full re-scans; running them concurrently makes a stale snapshot
+        // or a partial cache (see performRefresh's atomic swap) observable to
+        // metadata readers such as the settings-page skill list.
+        const run = this.refreshChain.then(() => this.performRefresh());
+        this.refreshChain = run.catch(() => { });
+        return run;
+    }
+    async performRefresh() {
+        // Route this scan's incremental skill-content writes into a scratch map
+        // (processSkillDirs writes to this.skillContent) and rebuild both caches
+        // fully before swapping them in — readers must never observe a
+        // half-refreshed (e.g. momentarily empty) skill list mid-scan.
+        const scratchContent = new Map();
+        const previousContent = this.skillContent;
+        this.skillContent = scratchContent;
+        let discovery;
+        try {
+            discovery = await this.discoverSkills();
+        }
+        catch (error) {
+            this.skillContent = previousContent;
+            throw error;
+        }
+        const nextMetadata = new Map();
+        const nextContent = new Map();
+        // Store discovered skills (builtin/personal/project)
         discovery.builtinSkills.forEach((skill, name) => {
-            this.skillMetadata.set(name, skill);
+            nextMetadata.set(name, skill);
         });
         discovery.personalSkills.forEach((skill, name) => {
-            this.skillMetadata.set(name, skill);
+            nextMetadata.set(name, skill);
         });
         discovery.projectSkills.forEach((skill, name) => {
-            this.skillMetadata.set(name, skill);
+            nextMetadata.set(name, skill);
+        });
+        scratchContent.forEach((skill, name) => {
+            nextContent.set(name, skill);
         });
         // Restore plugin skills
         this.pluginSkillMetadata.forEach((metadata, name) => {
-            this.skillMetadata.set(name, metadata);
+            nextMetadata.set(name, metadata);
         });
         this.pluginSkillContent.forEach((skill, name) => {
-            this.skillContent.set(name, skill);
+            nextContent.set(name, skill);
         });
         // Log any discovery errors
         if (discovery.errors.length > 0) {
@@ -82,6 +112,9 @@ export class SkillManager extends EventEmitter {
                 logger?.warn(`Skill error in ${error.skillPath}: ${error.message}`);
             });
         }
+        // Atomic swap: from this point on readers see the complete new snapshot
+        this.skillMetadata = nextMetadata;
+        this.skillContent = nextContent;
         this.emit("refreshed", Array.from(this.skillMetadata.values()));
     }
     /**
@@ -463,4 +496,81 @@ export class SkillManager extends EventEmitter {
         }
         logger?.debug(`Registered ${skills.length} plugin skills from ${pluginName}. Total skills: ${this.skillMetadata.size}`);
     }
+    /**
+     * Directory roots that may hold deletable copies of a skill in the given
+     * discovery scope. Personal skills are scanned from three user-level dirs
+     * (~/.wave|~/.claude|~/.agents/skills) and project skills from the current
+     * project's three project dirs (.wave|.claude|.agents/skills). The discovery
+     * map merges same-named copies from these roots into a single name-keyed
+     * entry, so deleteSkill must sweep the whole set to remove a skill fully.
+     */
+    scopeSkillRoots(type) {
+        if (type === "personal") {
+            return [
+                this.personalSkillsPath,
+                this.personalClaudeSkillsPath,
+                this.personalAgentsSkillsPath,
+            ];
+        }
+        if (type === "project") {
+            return [
+                join(this.workdir, ".wave", "skills"),
+                join(this.workdir, ".claude", "skills"),
+                join(this.workdir, ".agents", "skills"),
+            ];
+        }
+        return [];
+    }
+    /**
+     * Delete a user/personal or project skill by removing its directory
+     * (containing SKILL.md). Builtin and plugin skills are read-only and
+     * cannot be deleted.
+     *
+     * A same-named skill may physically live in several same-scope directories
+     * (~/.wave/skills + ~/.claude/skills + ~/.agents/skills for user skills,
+     * .wave/.claude/.agents/skills under the project for project skills) while
+     * only the highest-priority copy is listed; every copy is removed so one
+     * delete removes the skill completely instead of re-surfacing the next
+     * copy on the next scan. Caches are then re-converged with disk before
+     * returning so the caller's follow-up metadata read reflects the result.
+     * @param name - The skill name as shown in skill metadata
+     * @returns true if the skill was deleted
+     */
+    async deleteSkill(name) {
+        if (!this.initialized) {
+            throw new Error("SkillManager not initialized. Call initialize() first.");
+        }
+        const metadata = this.skillMetadata.get(name);
+        if (!metadata) {
+            return false;
+        }
+        // Builtin and plugin skills are read-only
+        if (metadata.type === "builtin" || metadata.pluginName) {
+            return false;
+        }
+        if (!metadata.skillPath) {
+            return false;
+        }
+        const dirsToRemove = new Set([metadata.skillPath]);
+        for (const root of this.scopeSkillRoots(metadata.type)) {
+            dirsToRemove.add(join(root, name));
+        }
+        for (const dir of dirsToRemove) {
+            await rm(dir, { recursive: true, force: true });
+        }
+        // Converge caches with disk: the serialized full refresh both drops the
+        // deleted entries and reflects any copy that survived deletion. If the
+        // refresh itself fails, fall back to dropping the entry from memory so
+        // the deleted skill does not keep being served.
+        try {
+            await this.refreshSkills();
+        }
+        catch (error) {
+            logger?.warn(`Failed to refresh skills after deleting '${name}': ${error}`);
+            this.skillMetadata.delete(name);
+            this.skillContent.delete(name);
+        }
+        logger?.debug(`Deleted skill '${name}' at ${metadata.skillPath}`);
+        return true;
+    }
 }