wave-agent-sdk 1.0.7 → 1.0.9

package/builtin/skills/artifact/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: artifact
+description: Publish a local HTML or Markdown file as a shareable web page
+disable-model-invocation: true
+---
+
+# Artifact: Publish a File as a Shareable Web Page
+
+Publish a local `.html` or `.md` file as a default-private, shareable web page.
+
+- If a file path was provided ($ARGUMENTS / $1), use it directly as the `file_path`.
+- Otherwise, infer which file to publish from the conversation context; if it is not clear, ask the user which file to publish.
+
+Call the `Artifact` tool with the resolved `file_path` (and `favicon` if relevant), then report the resulting URL to the user.

package/builtin/skills/settings/ENV.md

@@ -23,10 +23,11 @@ Wave uses several environment variables to control its core functionality. Varia
 | :--- | :--- | :--- |
 | `WAVE_API_KEY` | API key for the AI gateway. | - |
 | `WAVE_BASE_URL` | Base URL for the AI gateway. | - |
-| `WAVE_SERVER_URL` | Server URL for SSO authentication. **OS env only** — set via OS env or `options.serverUrl`; not read from settings.json `env` (avoids a startup 401 race). | `https://codechat.codewave.163.com` |
+| `WAVE_SERVER_URL` | Server URL for SSO authentication. Resolution order: `options.serverUrl` → `process.env.WAVE_SERVER_URL` → default. Unlike other `WAVE_*` vars, a settings.json `env` value is also mirrored to `process.env` so process-level singletons (AuthService) see it without a per-session snapshot. | `https://codechat.codewave.163.com` |
 | `WAVE_CUSTOM_HEADERS` | Custom HTTP headers for the AI gateway. Newline-separated `Key: Value` pairs (e.g., `"X-Foo: bar\nAuthorization: Bearer xxx"`). | - |
 | `WAVE_MODEL` | The primary AI model to use for the agent. | `gemini-3-flash` |
 | `WAVE_FAST_MODEL` | The fast AI model to use for quick tasks. | `gemini-2.5-flash` |
+| `WAVE_VISION_MODEL` | Vision-capable model used by the built-in `vision` subagent for image recognition. When set, the built-in `vision` subagent is registered (its frontmatter `model: visionModel` resolves to this value); when unset, the subagent is not loaded. Useful when the main model is fast but non-vision (e.g. DeepSeek). | - (not registered) |
 | `WAVE_MAX_INPUT_TOKENS` | Maximum number of input tokens allowed. | `200000` |
 | `WAVE_MAX_OUTPUT_TOKENS` | Maximum number of output tokens allowed. | `32000` |
 | `WAVE_DISABLE_AUTO_MEMORY` | Set to `1` or `true` to disable the auto-memory feature. | `false` |

package/builtin/skills/settings/MODELS.md

@@ -105,12 +105,15 @@ You can also set the default models Wave uses via environment variables in `sett
   "env": {
     "WAVE_MODEL": "gemini-3-flash",
     "WAVE_FAST_MODEL": "gemini-2.5-flash",
+    "WAVE_VISION_MODEL": "qwen-vl-max",
     "WAVE_MAX_INPUT_TOKENS": "100000",
     "WAVE_MAX_OUTPUT_TOKENS": "4096"
   }
 }
 ```
 
+`WAVE_VISION_MODEL` names a vision-capable model for the built-in `vision` subagent. Setting it registers the subagent, whose frontmatter `model: visionModel` resolves to this value — so a fast non-vision main model can delegate image recognition. Leave it unset to disable the built-in `vision` subagent.
+
 ## Live Reload
 
 Model configurations support **live reload**. When you modify the `models` field or model-related environment variables in `settings.json`, the changes take effect immediately without restarting Wave.

package/builtin/skills/settings/SKILL.md

@@ -104,6 +104,13 @@ For detailed guidance on creating plugins and marketplaces, see [PLUGINS.md](${W
 - `language`: Preferred language for agent communication (e.g., `"en"`, `"zh"`).
 - `autoMemoryEnabled`: Enable or disable auto-memory (default: `true`).
 - `autoMemoryFrequency`: Frequency of auto-memory extraction turns (default: `1`).
+- `enableArtifact`: Enable the Artifact tool, which publishes local `.html`/`.md` files as shareable (default-private) web pages. Defaults to `false` while the frame backend is not live; set to `true` to register the tool and enable WebFetch interception for artifact URLs. Toggling it hot-reloads the tool registry.
+
+```json
+{
+  "enableArtifact": true
+}
+```
 
 ## How to use this skill
 

package/builtin/skills/settings/SUBAGENTS.md

@@ -35,7 +35,7 @@ You are a specialized subagent for a specific task. Your goal is to:
 - `name`: (Required) Unique identifier.
 - `description`: (Required) Explains the subagent's expertise and when to use it.
 - `tools`: (Optional) List of tools the subagent can use.
-- `model`: (Optional) Overrides the default model for this subagent.
+- `model`: (Optional) Overrides the default model for this subagent. The special values `fastModel` and `visionModel` resolve to the `WAVE_FAST_MODEL` / `WAVE_VISION_MODEL` env vars respectively. Built-in subagents declaring `model: visionModel` (e.g. the built-in `vision` agent) are only registered when `WAVE_VISION_MODEL` is set; for user-defined subagents the value simply resolves to the configured vision model.
 
 ## Subagent Locations
 

package/builtin/subagents/vision.md

@@ -0,0 +1,18 @@
+---
+name: vision
+description: 'Image recognition specialist that runs on the model specified by the WAVE_VISION_MODEL environment variable. Use this when the current model does not support image recognition but the user has shared an image (identify the image by its "[Image source: <path>]" metadata). Pass the image file path(s) in the prompt; this agent reads the image with the Read tool and returns a detailed text description of its contents.'
+tools: [Read]
+model: visionModel
+---
+
+You are an image recognition specialist. You run on a vision-capable model and your job is to look at image files and return detailed text descriptions of their contents.
+
+When given image file path(s):
+- Use the Read tool on each image path to load it. The Read tool returns the image as base64 image data that you can see directly.
+- Describe the image contents in detail: what is shown, any visible text (transcribe verbatim where relevant), layout, colors, objects, and anything else the caller asked about.
+- If an image cannot be read (file missing, not an image, or too large), report the error clearly and state which path failed.
+- Do not invent or guess content you cannot see — only describe what the image actually shows.
+- Return your description directly as a text message. Do NOT create files.
+- Avoid using emojis in your response.
+
+Complete the image recognition task and report your findings clearly.

package/dist/constants/tools.d.ts

@@ -22,3 +22,4 @@ export declare const WEB_FETCH_TOOL_NAME = "WebFetch";
 export declare const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export declare const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
 export declare const WORKFLOW_TOOL_NAME = "Workflow";
+export declare const ARTIFACT_TOOL_NAME = "Artifact";

package/dist/constants/tools.js

@@ -22,3 +22,4 @@ export const WEB_FETCH_TOOL_NAME = "WebFetch";
 export const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
 export const WORKFLOW_TOOL_NAME = "Workflow";
+export const ARTIFACT_TOOL_NAME = "Artifact";

package/dist/managers/aiManager.js

@@ -20,6 +20,14 @@ import { logOTelEvent } from "../telemetry/events.js";
 const MAX_FORK_TURNS = 3;
 /** Max turns for the auto-memory extraction fork. */
 const MAX_AUTO_MEMORY_FORK_TURNS = 5;
+/**
+ * Max consecutive auto-resumes after `finish_reason === "length"` when the
+ * truncated turn produced NO tool calls (aligned with Claude Code's
+ * MAX_OUTPUT_TOKENS_RECOVERY_LIMIT). A tool call resets the counter — it is
+ * real progress. Exhausting the limit terminates the turn with an error
+ * instead of re-planning forever.
+ */
+const MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3;
 // Truncate text to `max` chars and append a "… [+N chars]" marker when exceeded.
 // Used for background_tasks description/command fields (≤1000 chars per spec FR-063).
 function truncateWithMarker(text, max) {
@@ -138,6 +146,9 @@ export class AIManager {
             if (this.modelOverride === "fastModel") {
                 modelToUse = parentModelConfig.fastModel;
             }
+            else if (this.modelOverride === "visionModel") {
+                modelToUse = parentModelConfig.visionModel;
+            }
             else if (this.modelOverride !== "inherit") {
                 modelToUse = this.modelOverride;
             }
@@ -1217,6 +1228,10 @@ ${question}`;
                 toolAbortController = this.toolAbortController;
             }
             let turnDepth = turnOffset;
+            // Consecutive truncation recoveries within this turn (no tool calls
+            // in between). Reset to 0 on tool calls / at each sendAIMessage entry,
+            // matching Claude Code's maxOutputTokensRecoveryCount semantics.
+            let maxOutputTokensRecoveryCount = 0;
             inner: while (true) {
                 let llmSpan;
                 try {
@@ -1300,10 +1315,15 @@ ${question}`;
                             // Use parametersChunk as compact param for better performance
                             // No need to extract params or generate compact params during streaming
                             // Update tool block with streaming parameters using parametersChunk as compact param
+                            // `parameters` is only present on start/running/end (authoritative); streaming
+                            // carries only `parametersChunk`, so don't forward `parameters: undefined`
+                            // (it would overwrite the accumulated block params in consumers)
                             this.messageManager.updateToolBlock({
                                 id: toolCall.id,
                                 name: toolCall.name,
-                                parameters: toolCall.parameters,
+                                ...(toolCall.parameters !== undefined
+                                    ? { parameters: toolCall.parameters }
+                                    : {}),
                                 parametersChunk: toolCall.parametersChunk,
                                 stage: toolCall.stage || "streaming", // Default to streaming if stage not provided
                             });
@@ -1462,13 +1482,34 @@ ${question}`;
                             const lastMessage = this.messageManager.getMessages()[this.messageManager.getMessages().length - 1];
                             const toolBlocks = lastMessage?.blocks.filter((block) => block.type === "tool") || [];
                             const hasBackgrounded = toolBlocks.length > 0 &&
-                                toolBlocks.some((block) => block.isManuallyBackgrounded);
+                                toolBlocks.some((block) => block.backgroundedByUser);
                             if (hasBackgrounded) {
                                 logger?.info("Some tools were manually backgrounded, stopping.");
                             }
                             else if (!isCurrentlyAborted) {
+                                // If the response was truncated WITHOUT any tool calls,
+                                // enforce the consecutive recovery limit (aligned with Claude
+                                // Code's MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3). Re-planning
+                                // loops that never produce output would otherwise continue
+                                // until the platform kills the task.
+                                if (result.finish_reason === "length" &&
+                                    toolCalls.length === 0 &&
+                                    maxOutputTokensRecoveryCount >=
+                                        MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {
+                                    this.messageManager.addErrorBlock(`Response exceeded the output token limit ${MAX_OUTPUT_TOKENS_RECOVERY_LIMIT + 1} consecutive times without producing output or tool calls. Stopped to avoid an infinite loop. Break the remaining work into smaller pieces and try again.`);
+                                    break inner;
+                                }
                                 // If response was truncated, add a hidden continuation message
                                 if (result.finish_reason === "length") {
+                                    if (toolCalls.length === 0) {
+                                        // Pure truncation — count toward the recovery limit.
+                                        maxOutputTokensRecoveryCount++;
+                                    }
+                                    else {
+                                        // Truncated with tool calls — real progress, reset the
+                                        // consecutive counter.
+                                        maxOutputTokensRecoveryCount = 0;
+                                    }
                                     this.messageManager.addUserMessage({
                                         content: "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces.",
                                         isMeta: true,
@@ -1881,7 +1922,9 @@ ${question}`;
                 name: toolName,
                 compactParams,
                 shortResult: toolResult.shortResult,
-                isManuallyBackgrounded: toolResult.isManuallyBackgrounded,
+                backgroundTaskId: toolResult.backgroundTaskId,
+                backgroundedByUser: toolResult.backgroundedByUser,
+                assistantAutoBackgrounded: toolResult.assistantAutoBackgrounded,
                 startLineNumber: toolResult.startLineNumber,
                 images: toolResult.images,
                 timestamp: Date.now(),
@@ -1900,7 +1943,6 @@ ${question}`;
                 stage: "end",
                 name: toolName,
                 compactParams,
-                isManuallyBackgrounded: false,
                 timestamp: Date.now(),
             });
         }

package/dist/managers/backgroundTaskManager.js

@@ -3,6 +3,7 @@ import * as os from "os";
 import * as fs from "fs";
 import * as path from "path";
 import { stripAnsiColors } from "../utils/stringUtils.js";
+import { WindowsStreamDecoder } from "../utils/encoding.js";
 import { logger } from "../utils/globalLogger.js";
 import { resolveShellPath } from "../utils/shellResolver.js";
 export class BackgroundTaskManager {
@@ -116,8 +117,12 @@ export class BackgroundTaskManager {
                 }
             }, timeout);
         }
+        // On Windows, native tools (taskkill, powershell, ...) write GBK (cp936)
+        // instead of UTF-8; decode their byte streams accordingly (issue #1753).
+        const stdoutDecoder = process.platform === "win32" ? new WindowsStreamDecoder() : null;
+        const stderrDecoder = process.platform === "win32" ? new WindowsStreamDecoder() : null;
         const onStdout = (data) => {
-            const stripped = stripAnsiColors(data.toString());
+            const stripped = stripAnsiColors(stdoutDecoder ? stdoutDecoder.push(data) : data.toString());
             shell.stdout += stripped;
             if (logStream.writable) {
                 logStream.write(stripped);
@@ -125,7 +130,7 @@ export class BackgroundTaskManager {
             this.notifyTasksChange();
         };
         const onStderr = (data) => {
-            const stripped = stripAnsiColors(data.toString());
+            const stripped = stripAnsiColors(stderrDecoder ? stderrDecoder.push(data) : data.toString());
             shell.stderr += stripped;
             if (logStream.writable) {
                 logStream.write(stripped);
@@ -136,6 +141,26 @@ export class BackgroundTaskManager {
             if (timeoutHandle) {
                 clearTimeout(timeoutHandle);
             }
+            // Decode any bytes still held at stream end (e.g. a trailing UTF-8
+            // character split across the last chunk).
+            if (stdoutDecoder) {
+                const rest = stdoutDecoder.flush();
+                if (rest) {
+                    shell.stdout += rest;
+                    if (logStream.writable) {
+                        logStream.write(rest);
+                    }
+                }
+            }
+            if (stderrDecoder) {
+                const rest = stderrDecoder.flush();
+                if (rest) {
+                    shell.stderr += rest;
+                    if (logStream.writable) {
+                        logStream.write(rest);
+                    }
+                }
+            }
             if (logStream.writable) {
                 logStream.end();
             }
@@ -256,8 +281,12 @@ export class BackgroundTaskManager {
         };
         this.tasks.set(id, shell);
         this.notifyTasksChange();
+        // On Windows, native tools write GBK (cp936) instead of UTF-8; decode
+        // their byte streams accordingly (issue #1753).
+        const stdoutDecoder = process.platform === "win32" ? new WindowsStreamDecoder() : null;
+        const stderrDecoder = process.platform === "win32" ? new WindowsStreamDecoder() : null;
         child.stdout?.on("data", (data) => {
-            const stripped = stripAnsiColors(data.toString());
+            const stripped = stripAnsiColors(stdoutDecoder ? stdoutDecoder.push(data) : data.toString());
             shell.stdout += stripped;
             if (logStream.writable) {
                 logStream.write(stripped);
@@ -265,7 +294,7 @@ export class BackgroundTaskManager {
             this.notifyTasksChange();
         });
         child.stderr?.on("data", (data) => {
-            const stripped = stripAnsiColors(data.toString());
+            const stripped = stripAnsiColors(stderrDecoder ? stderrDecoder.push(data) : data.toString());
             shell.stderr += stripped;
             if (logStream.writable) {
                 logStream.write(stripped);
@@ -273,6 +302,25 @@ export class BackgroundTaskManager {
             this.notifyTasksChange();
         });
         child.on("exit", (code) => {
+            // Decode any bytes still held at stream end
+            if (stdoutDecoder) {
+                const rest = stdoutDecoder.flush();
+                if (rest) {
+                    shell.stdout += rest;
+                    if (logStream.writable) {
+                        logStream.write(rest);
+                    }
+                }
+            }
+            if (stderrDecoder) {
+                const rest = stderrDecoder.flush();
+                if (rest) {
+                    shell.stderr += rest;
+                    if (logStream.writable) {
+                        logStream.write(rest);
+                    }
+                }
+            }
             if (logStream.writable) {
                 logStream.end();
             }

package/dist/managers/messageManager.js

@@ -686,7 +686,9 @@ export class MessageManager {
                 stage: "end",
                 success: false,
                 error: errorMessage,
-                isManuallyBackgrounded: block.isManuallyBackgrounded,
+                backgroundTaskId: block.backgroundTaskId,
+                backgroundedByUser: block.backgroundedByUser,
+                assistantAutoBackgrounded: block.assistantAutoBackgrounded,
                 timestamp,
             });
         }
@@ -730,7 +732,11 @@ export class MessageManager {
         // only sees messages from the latest compact summary forward — matching
         // the compact and resume behaviors (which also fold memory).
         this.setMessages(sliceFromLastCompact(newMessages));
-        this.savedMessageCount = newMessages.length;
+        // savedMessageCount tracks in-memory progress, so it must be the folded
+        // length. Using the full disk count here would make saveSession's
+        // slice(savedMessageCount) empty after a rewind past a compact boundary
+        // and silently drop every subsequent message from the session file.
+        this.savedMessageCount = this.messages.length;
     }
     /**
      * Rewrite the session file with the current messages.

package/dist/managers/permissionManager.d.ts

@@ -82,6 +82,11 @@ export declare class PermissionManager {
      * Get all instance-specific denied rules
      */
     getInstanceDeniedRules(): string[];
+    /**
+     * Add an instance-level allowed rule (session-level, in-memory only).
+     * Unlike addPermissionRule, this does NOT persist to settings.local.json.
+     */
+    addInstanceAllowedRule(rule: string): void;
     /**
      * Get all additional directories
      */

package/dist/managers/permissionManager.js

@@ -8,7 +8,7 @@
 import path from "node:path";
 import { minimatch } from "minimatch";
 import { RESTRICTED_TOOLS } from "../types/permissions.js";
-import { splitBashCommand, stripEnvVars, stripRedirections, hasWriteRedirections, getSmartPrefix, isDangerousFind, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, 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, } from "../utils/bashParser.js";
 import { isPathInside } from "../utils/pathSafety.js";
 import { BASH_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, READ_TOOL_NAME, ASK_USER_QUESTION_TOOL_NAME, } from "../constants/tools.js";
 const DEFAULT_ALLOWED_RULES = [
@@ -140,6 +140,15 @@ export class PermissionManager {
     getInstanceDeniedRules() {
         return [...this.instanceDeniedRules];
     }
+    /**
+     * Add an instance-level allowed rule (session-level, in-memory only).
+     * Unlike addPermissionRule, this does NOT persist to settings.local.json.
+     */
+    addInstanceAllowedRule(rule) {
+        if (!this.instanceAllowedRules.includes(rule)) {
+            this.instanceAllowedRules.push(rule);
+        }
+    }
     /**
      * Get all additional directories
      */
@@ -676,7 +685,14 @@ export class PermissionManager {
                 .replace(/\*/g, ".*"); // Replace * with .*
             const regex = new RegExp(`^${regexPattern}$`, "s");
             const matched = regex.test(processedPart);
-            return matched;
+            if (matched)
+                return true;
+            // Leading git global scope flags (e.g. `git -C <path>`) only change the
+            // target repository, not the subcommand being run, so rules like
+            // Bash(git status*) also cover `git -C <path> status`. The raw command
+            // is checked first so path-specific rules (e.g. deny rules on
+            // `git -C /secret status`) still match.
+            return regex.test(stripGitScopePrefix(processedPart));
         }
         // Handle path-based rules (e.g., "Read(**/*.env)")
         const pathTools = [READ_TOOL_NAME, WRITE_TOOL_NAME, EDIT_TOOL_NAME];

package/dist/managers/pluginManager.d.ts

@@ -6,10 +6,19 @@ export interface PluginManagerOptions {
 }
 export declare class PluginManager {
     private container;
+    /**
+     * Read-only helper scripts shipped by builtin plugins that the agent runs via
+     * Bash. When such a plugin is enabled, its rules are registered as instance
+     * level allow rules (in-memory only, never persisted) so the scripts run
+     * without a permission prompt. Wildcards keep the rules valid across install
+     * locations; each rule anchors on the script filename.
+     */
+    private static readonly BUILTIN_PLUGIN_ALLOW_RULES;
     private plugins;
     private workdir;
     private enabledPlugins;
     constructor(container: Container, options: PluginManagerOptions);
+    private get permissionManager();
     private get skillManager();
     private get hookManager();
     private get lspManager();

package/dist/managers/pluginManager.js

@@ -11,6 +11,9 @@ export class PluginManager {
         this.workdir = options.workdir;
         this.enabledPlugins = options.enabledPlugins || {};
     }
+    get permissionManager() {
+        return this.container.get("PermissionManager");
+    }
     get skillManager() {
         return this.container.get("SkillManager");
     }
@@ -221,6 +224,13 @@ export class PluginManager {
                 if (this.enabledPlugins[`${entry.name}@builtin`] !== true)
                     continue;
                 await this.loadSinglePlugin(path.join(builtinDir, entry.name));
+                // Register allow rules only after the plugin actually loaded, so a
+                // failed load never leaves permission grants behind.
+                if (this.plugins.has(entry.name)) {
+                    for (const rule of PluginManager.BUILTIN_PLUGIN_ALLOW_RULES[entry.name] || []) {
+                        this.permissionManager?.addInstanceAllowedRule(rule);
+                    }
+                }
             }
         }
         catch (error) {
@@ -240,3 +250,13 @@ export class PluginManager {
         return this.plugins.get(name);
     }
 }
+/**
+ * Read-only helper scripts shipped by builtin plugins that the agent runs via
+ * Bash. When such a plugin is enabled, its rules are registered as instance
+ * level allow rules (in-memory only, never persisted) so the scripts run
+ * without a permission prompt. Wildcards keep the rules valid across install
+ * locations; each rule anchors on the script filename.
+ */
+PluginManager.BUILTIN_PLUGIN_ALLOW_RULES = {
+    sdd: ["Bash(node *spec-count.js*)"],
+};

package/dist/managers/skillManager.d.ts

@@ -66,6 +66,19 @@ export declare class SkillManager extends EventEmitter {
      * Find all directories that could contain skills
      */
     private findSkillDirectories;
+    /**
+     * Whether a discovered skill is a feature-gated builtin skill whose gate
+     * is currently off. Mirrors ToolManager's gate for the Artifact tool so
+     * the /artifact skill command stays in sync with enableArtifact.
+     */
+    private isSkillGatedOff;
+    /**
+     * Re-evaluate feature-gated builtin skills after a live configuration
+     * reload (same hook as ToolManager.reloadFeatureGatedTools). Re-scans
+     * skill directories and emits "refreshed" so slash-command registration
+     * follows the gate.
+     */
+    reloadFeatureGatedSkills(): Promise<void>;
     /**
      * Execute a skill by name
      */

package/dist/managers/skillManager.js

@@ -7,6 +7,7 @@ import { parseSkillFile, formatSkillError } from "../utils/skillParser.js";
 import { substituteCommandParameters } from "../utils/commandArgumentParser.js";
 import { parseBashCommands, replaceBashCommandsWithOutput, executeBashCommands, } from "../utils/markdownParser.js";
 import { getBuiltinSkillsDir } from "../utils/configPaths.js";
+import { isArtifactEnabled } from "../services/artifactAvailability.js";
 import { logger } from "../utils/globalLogger.js";
 /**
  * Manages skill discovery and loading
@@ -247,6 +248,12 @@ export class SkillManager extends EventEmitter {
                         ...parsed.skillMetadata,
                         type: collection.type,
                     };
+                    // Feature-gated builtin skills (e.g. artifact behind
+                    // enableArtifact) are skipped while the gate is off, mirroring
+                    // ToolManager's registration gate for the Artifact tool.
+                    if (this.isSkillGatedOff(skillMetadata)) {
+                        continue;
+                    }
                     // Create full skill object with content
                     const skill = {
                         ...skillMetadata,
@@ -304,6 +311,29 @@ export class SkillManager extends EventEmitter {
         }
         return directories;
     }
+    /**
+     * Whether a discovered skill is a feature-gated builtin skill whose gate
+     * is currently off. Mirrors ToolManager's gate for the Artifact tool so
+     * the /artifact skill command stays in sync with enableArtifact.
+     */
+    isSkillGatedOff(metadata) {
+        if (metadata.type !== "builtin") {
+            return false;
+        }
+        if (metadata.name === "artifact") {
+            return !isArtifactEnabled(this.workdir);
+        }
+        return false;
+    }
+    /**
+     * Re-evaluate feature-gated builtin skills after a live configuration
+     * reload (same hook as ToolManager.reloadFeatureGatedTools). Re-scans
+     * skill directories and emits "refreshed" so slash-command registration
+     * follows the gate.
+     */
+    async reloadFeatureGatedSkills() {
+        await this.refreshSkills();
+    }
     /**
      * Execute a skill by name
      */

package/dist/managers/subagentManager.d.ts

@@ -87,6 +87,18 @@ export declare class SubagentManager {
      * Load all available subagent configurations and cache them
      */
     loadConfigurations(): Promise<SubagentConfiguration[]>;
+    /**
+     * Rebuild the cached subagent configurations. Called after settings.json
+     * env becomes available (post loadMergedConfiguration) so conditional
+     * builtin subagents (e.g. `model: visionModel` requiring WAVE_VISION_MODEL)
+     * register correctly. Plugin agents are preserved across the rebuild.
+     */
+    refreshConfigurations(): Promise<SubagentConfiguration[]>;
+    /**
+     * Get the merged environment (OS env overlaid with settings.json env) used
+     * for conditional subagent registration (e.g. WAVE_VISION_MODEL).
+     */
+    private getMergedEnv;
     /**
      * Get cached configurations synchronously (must call loadConfigurations first)
      */

package/dist/managers/subagentManager.js

@@ -70,10 +70,40 @@ export class SubagentManager {
     async loadConfigurations() {
         if (this.cachedConfigurations === null) {
             const { loadSubagentConfigurations } = await import("../utils/subagentParser.js");
-            this.cachedConfigurations = await loadSubagentConfigurations(this.workdir);
+            this.cachedConfigurations = await loadSubagentConfigurations(this.workdir, this.getMergedEnv());
         }
         return this.cachedConfigurations;
     }
+    /**
+     * Rebuild the cached subagent configurations. Called after settings.json
+     * env becomes available (post loadMergedConfiguration) so conditional
+     * builtin subagents (e.g. `model: visionModel` requiring WAVE_VISION_MODEL)
+     * register correctly. Plugin agents are preserved across the rebuild.
+     */
+    async refreshConfigurations() {
+        // Preserve plugin agents (namespaced `pluginName:agentName`) across the rebuild
+        const pluginAgents = (this.cachedConfigurations ?? []).filter((config) => config.name.includes(":"));
+        this.cachedConfigurations = null;
+        await this.loadConfigurations();
+        for (const agent of pluginAgents) {
+            this.cachedConfigurations.push(agent);
+        }
+        // Re-sort by priority then name (matches registerPluginAgents)
+        this.cachedConfigurations.sort((a, b) => {
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return a.name.localeCompare(b.name);
+        });
+        return this.cachedConfigurations;
+    }
+    /**
+     * Get the merged environment (OS env overlaid with settings.json env) used
+     * for conditional subagent registration (e.g. WAVE_VISION_MODEL).
+     */
+    getMergedEnv() {
+        return (this.configurationService?.getMergedEnv?.() ??
+            process.env);
+    }
     /**
      * Get cached configurations synchronously (must call loadConfigurations first)
      */
@@ -95,7 +125,7 @@ export class SubagentManager {
         }
         // Fall back to filesystem scan for non-plugin agents
         const { findSubagentByName } = await import("../utils/subagentParser.js");
-        return findSubagentByName(name, this.workdir);
+        return findSubagentByName(name, this.workdir, this.getMergedEnv());
     }
     /**
      * Register plugin agents into the cached configurations.

package/dist/managers/toolManager.d.ts

@@ -53,6 +53,14 @@ declare class ToolManager {
      * ```
      */
     initializeBuiltInTools(): void;
+    /**
+     * Re-evaluate feature-gated built-in tools after a live configuration
+     * reload. Currently gates the Artifact tool on settings.json
+     * `enableArtifact`. Safe to call multiple times: gated tools are removed
+     * from the registry first, then initializeBuiltInTools() re-registers them
+     * only if still enabled (so toggling the flag off actually unregisters).
+     */
+    reloadFeatureGatedTools(): void;
     /**
      * Check if a tool should be enabled based on tools configuration and permission rules
      */

package/dist/managers/toolManager.js

@@ -9,6 +9,8 @@ import { cronCreateTool } from "../tools/cronCreateTool.js";
 import { cronDeleteTool } from "../tools/cronDeleteTool.js";
 import { cronListTool } from "../tools/cronListTool.js";
 import { webFetchTool } from "../tools/webFetchTool.js";
+import { artifactTool } from "../tools/artifactTool.js";
+import { isArtifactEnabled } from "../services/artifactAvailability.js";
 // New tools
 import { globTool } from "../tools/globTool.js";
 import { grepTool } from "../tools/grepTool.js";
@@ -95,6 +97,11 @@ class ToolManager {
             exitWorktreeTool,
             workflowTool,
         ];
+        // Artifact is a feature-gated tool: not registered at all while the frame
+        // backend is not live, unless settings.json opts in via enableArtifact: true.
+        if (isArtifactEnabled(this.container.get("Workdir"))) {
+            builtInTools.push(artifactTool);
+        }
         for (const tool of builtInTools) {
             if (this.shouldEnableTool(tool.name)) {
                 this.toolsRegistry.set(tool.name, tool);
@@ -107,6 +114,17 @@ class ToolManager {
             }
         }
     }
+    /**
+     * Re-evaluate feature-gated built-in tools after a live configuration
+     * reload. Currently gates the Artifact tool on settings.json
+     * `enableArtifact`. Safe to call multiple times: gated tools are removed
+     * from the registry first, then initializeBuiltInTools() re-registers them
+     * only if still enabled (so toggling the flag off actually unregisters).
+     */
+    reloadFeatureGatedTools() {
+        this.toolsRegistry.delete(artifactTool.name);
+        this.initializeBuiltInTools();
+    }
     /**
      * Check if a tool should be enabled based on tools configuration and permission rules
      */