wave-agent-sdk 1.0.7 → 1.0.8

package/builtin/skills/settings/ENV.md

@@ -27,6 +27,7 @@ Wave uses several environment variables to control its core functionality. Varia
 | `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/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/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/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.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);

package/dist/services/aiService.d.ts

@@ -28,7 +28,7 @@ export interface CallAgentOptions {
     onToolUpdate?: (toolCall: {
         id: string;
         name: string;
-        parameters: string;
+        parameters?: string;
         parametersChunk?: string;
         stage?: "start" | "streaming" | "running" | "end";
     }) => void;

package/dist/services/aiService.js

@@ -425,7 +425,9 @@ async function processStreamingResponse(stream, onContentUpdate, onToolUpdate, o
                     if (functionDelta.arguments) {
                         existingCall.function.arguments += functionDelta.arguments;
                     }
-                    // Emit streaming updates for all chunks with actual content (including first chunk)
+                    // Emit streaming updates for all chunks with actual content (including first chunk).
+                    // Streaming carries only the delta `parametersChunk` — consumers accumulate it;
+                    // authoritative `parameters` arrives at `start` (empty) / `running` / `end`.
                     if (onToolUpdate &&
                         existingCall.function.name &&
                         functionDelta.arguments &&
@@ -434,7 +436,6 @@ async function processStreamingResponse(stream, onContentUpdate, onToolUpdate, o
                         onToolUpdate({
                             id: existingCall.id,
                             name: existingCall.function.name,
-                            parameters: existingCall.function.arguments,
                             parametersChunk: functionDelta.arguments,
                             stage: "streaming",
                         });

package/dist/services/artifactAvailability.d.ts

@@ -0,0 +1,7 @@
+/** Code default for Artifact availability. Flip to true after the frame backend goes live. */
+export declare const ARTIFACT_DEFAULT_ENABLED = false;
+/**
+ * Whether the Artifact tool should be registered / usable for the given workdir.
+ * Explicit `enableArtifact` in merged settings wins over the code default.
+ */
+export declare function isArtifactEnabled(workdir?: string): boolean;

package/dist/services/artifactAvailability.js

@@ -0,0 +1,26 @@
+/**
+ * Artifact feature availability.
+ *
+ * The frame backend (`POST /api/frame/deploy/direct`) is not live yet, so the
+ * code default is DISABLED. Internal beta / gradual rollout enables the feature
+ * via settings.json `enableArtifact: true` without code changes. Once the
+ * backend goes live, flip `ARTIFACT_DEFAULT_ENABLED` to `true` so an unset
+ * `enableArtifact` defaults to enabled (matching Claude Code's `enableArtifact`
+ * "unset follows feature availability" semantics).
+ */
+import { loadMergedWaveConfig } from "./configurationService.js";
+/** Code default for Artifact availability. Flip to true after the frame backend goes live. */
+export const ARTIFACT_DEFAULT_ENABLED = false;
+/**
+ * Whether the Artifact tool should be registered / usable for the given workdir.
+ * Explicit `enableArtifact` in merged settings wins over the code default.
+ */
+export function isArtifactEnabled(workdir) {
+    if (workdir) {
+        const config = loadMergedWaveConfig(workdir);
+        if (config?.enableArtifact !== undefined) {
+            return config.enableArtifact;
+        }
+    }
+    return ARTIFACT_DEFAULT_ENABLED;
+}

package/dist/services/artifactSession.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Session-scoped state shared between the Artifact tool and the WebFetch tool.
+ *
+ * - file_path → artifact record: lets a model republish a file it already
+ *   published this session without passing `url` again, and enables the
+ *   same-session auto-allow (the publish was already confirmed once).
+ * - slug → latest known version: powers the stale-version guard
+ *   (local knowledge older than the live version blocks a redeploy
+ *   unless `force` is set) and lets WebFetch record versions it observed.
+ *
+ * State is keyed by sessionId so parallel sessions never observe each other.
+ */
+export interface ArtifactRecord {
+    url: string;
+    slug: string;
+    version: string;
+}
+/** Record a successful publish so same-session republishes auto-allow. */
+export declare function recordArtifact(sessionId: string, filePath: string, record: ArtifactRecord): void;
+/** Look up an artifact previously published in this session by file path. */
+export declare function getArtifactByFilePath(sessionId: string, filePath: string): ArtifactRecord | undefined;
+/** Latest version of a slug this session has observed (publish, conflict, or read). */
+export declare function getRecordedVersion(sessionId: string, slug: string): string | undefined;
+/** Record an observed version (from a publish, a 409 conflict, or a WebFetch read). */
+export declare function recordVersion(sessionId: string, slug: string, version: string): void;
+/** Clear all session-scoped artifact state (used when a session ends). */
+export declare function clearArtifactSession(sessionId: string): void;

package/dist/services/artifactSession.js

@@ -0,0 +1,52 @@
+/**
+ * Session-scoped state shared between the Artifact tool and the WebFetch tool.
+ *
+ * - file_path → artifact record: lets a model republish a file it already
+ *   published this session without passing `url` again, and enables the
+ *   same-session auto-allow (the publish was already confirmed once).
+ * - slug → latest known version: powers the stale-version guard
+ *   (local knowledge older than the live version blocks a redeploy
+ *   unless `force` is set) and lets WebFetch record versions it observed.
+ *
+ * State is keyed by sessionId so parallel sessions never observe each other.
+ */
+const sessionArtifacts = new Map();
+const sessionSlugVersions = new Map();
+function fileMapFor(sessionId) {
+    let map = sessionArtifacts.get(sessionId);
+    if (!map) {
+        map = new Map();
+        sessionArtifacts.set(sessionId, map);
+    }
+    return map;
+}
+function slugMapFor(sessionId) {
+    let map = sessionSlugVersions.get(sessionId);
+    if (!map) {
+        map = new Map();
+        sessionSlugVersions.set(sessionId, map);
+    }
+    return map;
+}
+/** Record a successful publish so same-session republishes auto-allow. */
+export function recordArtifact(sessionId, filePath, record) {
+    fileMapFor(sessionId).set(filePath, record);
+    slugMapFor(sessionId).set(record.slug, record.version);
+}
+/** Look up an artifact previously published in this session by file path. */
+export function getArtifactByFilePath(sessionId, filePath) {
+    return sessionArtifacts.get(sessionId)?.get(filePath);
+}
+/** Latest version of a slug this session has observed (publish, conflict, or read). */
+export function getRecordedVersion(sessionId, slug) {
+    return sessionSlugVersions.get(sessionId)?.get(slug);
+}
+/** Record an observed version (from a publish, a 409 conflict, or a WebFetch read). */
+export function recordVersion(sessionId, slug, version) {
+    slugMapFor(sessionId).set(slug, version);
+}
+/** Clear all session-scoped artifact state (used when a session ends). */
+export function clearArtifactSession(sessionId) {
+    sessionArtifacts.delete(sessionId);
+    sessionSlugVersions.delete(sessionId);
+}

package/dist/services/configurationService.d.ts

@@ -81,9 +81,10 @@ export declare class ConfigurationService {
      * @param fastModel - Fast model override (optional)
      * @param maxTokens - Max output tokens override (optional)
      * @param permissionMode - Permission mode override (optional)
+     * @param visionModel - Vision model override (optional)
      * @returns Resolved model configuration with defaults
      */
-    resolveModelConfig(model?: string, fastModel?: string, maxTokens?: number, permissionMode?: PermissionMode): ModelConfig;
+    resolveModelConfig(model?: string, fastModel?: string, maxTokens?: number, permissionMode?: PermissionMode, visionModel?: string): ModelConfig;
     /**
      * Resolves token limit with fallbacks
      * Resolution priority: override > options > env (from settings.json) > process.env > default

package/dist/services/configurationService.js

@@ -459,9 +459,10 @@ export class ConfigurationService {
      * @param fastModel - Fast model override (optional)
      * @param maxTokens - Max output tokens override (optional)
      * @param permissionMode - Permission mode override (optional)
+     * @param visionModel - Vision model override (optional)
      * @returns Resolved model configuration with defaults
      */
-    resolveModelConfig(model, fastModel, maxTokens, permissionMode) {
+    resolveModelConfig(model, fastModel, maxTokens, permissionMode, visionModel) {
         // Resolve agent model: override > options > currentConfiguration (settings.json model, possibly remote-merged) > process.env
         // Priority: user's explicit model field > admin's env.WAVE_MODEL default.
         // If admin wants hard enforcement, they set the `model` scalar field (overwrites local in mergeRemoteSettings).
@@ -473,11 +474,16 @@ export class ConfigurationService {
         const resolvedFastModel = fastModel ||
             this.options.fastModel ||
             (this.envSnapshot.WAVE_FAST_MODEL ?? process.env.WAVE_FAST_MODEL);
+        // Resolve vision model: override > options > process.env (includes settings.json env)
+        const resolvedVisionModel = visionModel ||
+            this.options.visionModel ||
+            (this.envSnapshot.WAVE_VISION_MODEL ?? process.env.WAVE_VISION_MODEL);
         // Resolve max output tokens
         const resolvedMaxTokens = this.resolveMaxOutputTokens(maxTokens);
         const baseConfig = {
             model: resolvedAgentModel,
             fastModel: resolvedFastModel,
+            visionModel: resolvedVisionModel,
             maxTokens: resolvedMaxTokens,
             permissionMode: permissionMode ?? this.options.permissionMode,
         };
@@ -1062,9 +1068,13 @@ export function loadWaveConfigFromFile(filePath) {
             autoMemoryEnabled: config.autoMemoryEnabled !== undefined
                 ? config.autoMemoryEnabled
                 : undefined,
+            autoMemoryFrequency: config.autoMemoryFrequency !== undefined
+                ? config.autoMemoryFrequency
+                : undefined,
             models: config.models || undefined,
             marketplaces: config.marketplaces || undefined,
             worktree: config.worktree || undefined,
+            enableArtifact: config.enableArtifact !== undefined ? config.enableArtifact : undefined,
         };
     }
     catch (error) {
@@ -1209,6 +1219,10 @@ export function loadMergedWaveConfig(workdir) {
         if (config.worktree !== undefined) {
             mergedConfig.worktree = config.worktree;
         }
+        // Merge enableArtifact (last one wins)
+        if (config.enableArtifact !== undefined) {
+            mergedConfig.enableArtifact = config.enableArtifact;
+        }
         // Merge models
         if (config.models) {
             if (!mergedConfig.models)
@@ -1247,5 +1261,6 @@ export function loadMergedWaveConfig(workdir) {
             ? mergedConfig.models
             : undefined,
         worktree: mergedConfig.worktree,
+        enableArtifact: mergedConfig.enableArtifact,
     };
 }

package/dist/services/initializationService.js

@@ -64,6 +64,11 @@ export class InitializationService {
             const phaseStart = performance.now();
             // Load hooks configuration using ConfigurationService
             const configResult = await configurationService.loadMergedConfiguration(workdir);
+            // Rebuild subagent configurations now that settings.json env is loaded
+            // into the snapshot: conditional builtin subagents (model: visionModel
+            // → WAVE_VISION_MODEL) can only register once the env is available.
+            // Plugin agents are preserved by refreshConfigurations.
+            await subagentManager.refreshConfigurations();
             hookManager.loadConfigurationFromWaveConfig(configResult.configuration);
             // Update plugin manager with enabled plugins configuration
             if (configResult.configuration?.enabledPlugins) {

package/dist/tools/agentTool.js

@@ -172,7 +172,8 @@ When using the Agent tool, you must specify a subagent_type parameter to select
                                     success: true,
                                     content: `Agent backgrounded with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
                                     shortResult: "Agent backgrounded",
-                                    isManuallyBackgrounded: true,
+                                    backgroundedByUser: true,
+                                    backgroundTaskId: taskId,
                                 });
                             },
                         });

package/dist/tools/artifactTool.d.ts

@@ -0,0 +1,2 @@
+import type { ToolPlugin } from "./types.js";
+export declare const artifactTool: ToolPlugin;