@bubblebrain-ai/bubble 0.0.8 → 0.0.9

package/dist/main.js

@@ -56,6 +56,20 @@ async function main() {
         })
         : createUnavailableProvider(unavailableProviderMessage);
     const createProvider = (providerId, apiKey, baseURL) => createProviderInstance({ providerId, apiKey, baseURL, thinkingLevel: args.thinkingLevel });
+    const createProviderForRoute = async (route) => {
+        const providerId = route.providerId;
+        if (!providerId) {
+            throw new Error(`Subagent route for model "${route.model}" did not include a provider.`);
+        }
+        if (registry.supportsOAuth(providerId) && registry.getAuthStorage().has(providerId)) {
+            await registry.prepareProvider(providerId);
+        }
+        const target = registry.getConfigured().find((item) => item.id === providerId);
+        if (!target?.enabled || !target.apiKey) {
+            throw new Error(`Subagent route requires provider "${providerId}", but it is not configured or has no active credentials.`);
+        }
+        return createProvider(providerId, target.apiKey, target.baseURL);
+    };
     let agentRef;
     const todoStore = {
         getTodos: () => agentRef?.getTodos() ?? [],
@@ -250,6 +264,8 @@ async function main() {
         skills: skillSummaries,
         memoryPrompt,
         fileStateTracker,
+        agentCategories: userConfig.getAgentCategories(),
+        providerFactory: createProviderForRoute,
     });
     agentRef = agent;
     if (sessionManager) {
@@ -335,10 +351,8 @@ async function main() {
             return;
         }
         const tuiRuntime = process.env.BUBBLE_TUI === "opentui" ? "opentui" : "ink";
-        const { runTui } = tuiRuntime === "opentui"
-            ? await import("./tui/run.js")
-            : await import("./tui-ink/run.js");
-        await runTui(agent, args, {
+        const themeConfig = userConfig.getTheme();
+        const commonOptions = {
             sessionManager,
             createProvider,
             registry,
@@ -350,12 +364,35 @@ async function main() {
             settingsManager,
             lspService,
             mcpManager,
-            theme: userConfig.getTheme(),
             flushMemory,
             runMemoryCompaction,
             runMemorySummary,
             runMemoryRefresh,
-        });
+        };
+        if (tuiRuntime === "opentui") {
+            const { runTui } = await import("./tui/run.js");
+            await runTui(agent, args, {
+                ...commonOptions,
+                theme: themeConfig.overrides,
+            });
+        }
+        else {
+            // Probe the terminal background BEFORE Ink takes over stdin. OSC 11
+            // needs raw mode, and once Ink owns stdin the reply never reaches us.
+            let detectedTheme = "dark";
+            if (themeConfig.mode === "auto") {
+                const { detectTerminalTheme } = await import("./tui-ink/detect-theme.js");
+                detectedTheme = await detectTerminalTheme();
+            }
+            const { runTui } = await import("./tui-ink/run.js");
+            await runTui(agent, args, {
+                ...commonOptions,
+                themeMode: themeConfig.mode,
+                themeOverrides: themeConfig.overrides,
+                detectedTheme,
+                onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
+            });
+        }
     }
     finally {
         await shutdownRuntime();

package/dist/model-catalog.d.ts

@@ -11,10 +11,19 @@ export interface BuiltinModelDefinition {
     providerId: string;
     reasoningLevels: ReasoningEffort[];
     contextWindow?: number;
+    /**
+     * Server-declared cap on per-tool-output tokens. When set, the agent must
+     * truncate each tool result to this token budget before adding it to history
+     * — otherwise the server's input window is exceeded by raw tool dumps.
+     * (For codex models this comes from the API's `truncation_policy.limit`.)
+     */
+    toolOutputTokenLimit?: number;
 }
 export declare const BUILTIN_PROVIDERS: BuiltinProviderDefinition[];
 export declare const BUILTIN_MODELS: BuiltinModelDefinition[];
 export declare function listBuiltinModels(providerId: string): BuiltinModelDefinition[];
+export declare function registerDynamicModelMetadata(model: BuiltinModelDefinition): void;
 export declare function getBuiltinModel(providerId: string, modelId: string): BuiltinModelDefinition | undefined;
 export declare function getBuiltinProvider(providerId: string): BuiltinProviderDefinition | undefined;
 export declare function getModelContextWindow(providerId: string, modelId: string): number | undefined;
+export declare function getToolOutputTokenLimit(providerId: string, modelId: string): number | undefined;

package/dist/model-catalog.js

@@ -85,7 +85,20 @@ export const BUILTIN_MODELS = [
 export function listBuiltinModels(providerId) {
     return BUILTIN_MODELS.filter((model) => model.providerId === providerId);
 }
+// Runtime overlay populated from provider-side discovery (e.g. ChatGPT codex /models).
+// Looked up before the static catalog so newly-released models work without a code change.
+const dynamicOverlay = new Map();
+function overlayKey(providerId, modelId) {
+    return `${providerId}:${modelId}`;
+}
+export function registerDynamicModelMetadata(model) {
+    dynamicOverlay.set(overlayKey(model.providerId, model.id), model);
+}
 export function getBuiltinModel(providerId, modelId) {
+    const overlayHit = dynamicOverlay.get(overlayKey(providerId, modelId))
+        || (providerId === "openai" ? dynamicOverlay.get(overlayKey("openai-codex", modelId)) : undefined);
+    if (overlayHit)
+        return overlayHit;
     return BUILTIN_MODELS.find((model) => model.providerId === providerId && model.id === modelId)
         || (providerId === "openai"
             ? BUILTIN_MODELS.find((model) => model.providerId === "openai-codex" && model.id === modelId)
@@ -97,3 +110,6 @@ export function getBuiltinProvider(providerId) {
 export function getModelContextWindow(providerId, modelId) {
     return getBuiltinModel(providerId, modelId)?.contextWindow;
 }
+export function getToolOutputTokenLimit(providerId, modelId) {
+    return getBuiltinModel(providerId, modelId)?.toolOutputTokenLimit;
+}

package/dist/orchestrator/default-hooks.js

@@ -6,6 +6,7 @@ import { arbitrateToolCall } from "../agent/tool-arbiter.js";
 import { buildEditRetryEscalationReminder, buildSmallTaskHint, buildTaskSummaryReminder, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
 import { reminderForTaskType } from "../prompt/task-reminders.js";
 import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
+import { buildSubagentLifecycleReminder } from "../agent/subagent-lifecycle-reminder.js";
 export function createDefaultHooks() {
     return [
         {
@@ -127,6 +128,12 @@ export function createDefaultHooks() {
                 }
             },
             beforeContinuation(ctx) {
+                if (hasSubagentLifecycleActivity(ctx.toolCalls, ctx.toolResults)) {
+                    const reminder = buildSubagentLifecycleReminder(ctx.agent.listSubAgents(), ctx.toolResults);
+                    if (reminder) {
+                        ctx.queueReminder(reminder);
+                    }
+                }
                 if (ctx.state.taskType === "security_investigation" && ctx.state.evidenceTracker?.isCoreCoverageComplete()) {
                     ctx.requestTextOnlyTurn("Core security investigation evidence has been collected. Summarize the findings instead of continuing with more tool calls.");
                     return;
@@ -149,6 +156,17 @@ function isCodeWriteResult(_toolCall, result) {
     }
     return result.metadata?.kind === "write" || result.metadata?.kind === "edit";
 }
+function hasSubagentLifecycleActivity(toolCalls, toolResults) {
+    return toolCalls.some((toolCall) => isSubagentLifecycleTool(toolCall.name))
+        || toolResults.some((result) => result.metadata?.kind === "subagent");
+}
+function isSubagentLifecycleTool(name) {
+    return name === "spawn_agent"
+        || name === "wait_agent"
+        || name === "send_input"
+        || name === "close_agent"
+        || name === "task";
+}
 function hashEditCall(toolCall) {
     // Cheap fingerprint that identifies "same edit/write call". JSON of the
     // sorted parsed args is good enough — we only need stable equality between

package/dist/provider-openai-codex.d.ts

@@ -1,4 +1,14 @@
-import type { Provider, ThinkingLevel } from "./types.js";
+import type { Provider, ReasoningEffort, ThinkingLevel } from "./types.js";
+export interface CodexModelDescriptor {
+    id: string;
+    displayName?: string;
+    contextWindow?: number;
+    reasoningLevels?: ReasoningEffort[];
+    visibility?: string;
+    minimalClientVersion?: string;
+    /** Server-declared per-tool-output token cap (truncation_policy.limit when mode=tokens). */
+    toolOutputTokenLimit?: number;
+}
 export declare function isOpenAICodexBaseUrl(baseURL: string): boolean;
 export declare function getOpenAICodexFallbackModels(): string[];
 export declare function extractChatGptAccountId(accessToken: string): string | undefined;
@@ -11,4 +21,5 @@ export declare function createOpenAICodexProvider(options: {
 export declare function fetchOpenAICodexModels(options: {
     baseURL: string;
     accessToken: string;
-}): Promise<string[]>;
+}): Promise<CodexModelDescriptor[]>;
+export declare function sortCodexModelDescriptors(descriptors: CodexModelDescriptor[]): CodexModelDescriptor[];

package/dist/provider-openai-codex.js

@@ -2,7 +2,10 @@ import { listBuiltinModels } from "./model-catalog.js";
 import { resolveProviderRequestConfig } from "./provider-transform.js";
 const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
 const OPENAI_BETA_RESPONSES = "responses=experimental";
-const CODEX_CLIENT_VERSION = "0.121.0";
+// OpenAI gates new codex models server-side by client_version (each model carries a
+// `minimal_client_version`). Track a recent real Codex CLI release; override via env
+// when OpenAI lifts the gate again before we cut a new release.
+const CODEX_CLIENT_VERSION = process.env.BUBBLE_CODEX_CLIENT_VERSION?.trim() || "0.150.0";
 const MODEL_DISCOVERY_PATHS = [
     `/codex/models?client_version=${CODEX_CLIENT_VERSION}`,
     "/models",
@@ -205,9 +208,9 @@ export async function fetchOpenAICodexModels(options) {
         if (!response?.ok)
             continue;
         const payload = await response.json().catch(() => undefined);
-        const ids = extractModelIds(payload);
-        if (ids.length > 0) {
-            return sortCodexModelIds(ids);
+        const descriptors = extractCodexModelDescriptors(payload);
+        if (descriptors.length > 0) {
+            return sortCodexModelDescriptors(descriptors);
         }
     }
     return [];
@@ -361,18 +364,54 @@ function resolveRelativeUrl(baseURL, path) {
     const normalized = (baseURL.trim() || DEFAULT_CODEX_BASE_URL).replace(/\/+$/, "");
     return `${normalized}${path}`;
 }
-function extractModelIds(payload) {
-    const ids = [];
+const REASONING_EFFORTS = [
+    "off", "minimal", "low", "medium", "high", "xhigh", "max",
+];
+function extractCodexModelDescriptors(payload) {
+    const out = [];
     const seen = new Set();
-    const maybeAdd = (value) => {
-        if (typeof value !== "string")
-            return;
-        if (!/^gpt-|^codex-/i.test(value))
-            return;
-        if (seen.has(value))
-            return;
-        seen.add(value);
-        ids.push(value);
+    const isCodexId = (value) => typeof value === "string" && /^gpt-|^codex-/i.test(value);
+    const pickId = (record) => {
+        for (const key of ["slug", "id", "model_slug", "model"]) {
+            const v = record[key];
+            if (isCodexId(v))
+                return v;
+        }
+        return undefined;
+    };
+    const buildDescriptor = (record, id) => {
+        const desc = { id };
+        const displayName = record.display_name;
+        if (typeof displayName === "string" && displayName)
+            desc.displayName = displayName;
+        const ctx = record.context_window;
+        if (typeof ctx === "number" && ctx > 0)
+            desc.contextWindow = ctx;
+        const visibility = record.visibility;
+        if (typeof visibility === "string")
+            desc.visibility = visibility;
+        const minVer = record.minimal_client_version;
+        if (typeof minVer === "string")
+            desc.minimalClientVersion = minVer;
+        const levels = record.supported_reasoning_levels;
+        if (Array.isArray(levels)) {
+            const efforts = new Set(["off"]);
+            for (const level of levels) {
+                const effort = level?.effort;
+                if (typeof effort === "string" && REASONING_EFFORTS.includes(effort)) {
+                    efforts.add(effort);
+                }
+            }
+            desc.reasoningLevels = REASONING_EFFORTS.filter((e) => efforts.has(e));
+        }
+        const truncPolicy = record.truncation_policy;
+        if (truncPolicy && truncPolicy.mode === "tokens") {
+            const limit = truncPolicy.limit;
+            if (typeof limit === "number" && limit > 0) {
+                desc.toolOutputTokenLimit = limit;
+            }
+        }
+        return desc;
     };
     const visit = (value) => {
         if (Array.isArray(value)) {
@@ -380,32 +419,42 @@ function extractModelIds(payload) {
                 visit(item);
             return;
         }
-        if (!value || typeof value !== "object") {
-            maybeAdd(value);
+        if (!value || typeof value !== "object")
             return;
-        }
         const record = value;
-        maybeAdd(record.id);
-        maybeAdd(record.slug);
-        maybeAdd(record.model);
-        maybeAdd(record.model_slug);
+        const id = pickId(record);
+        if (id && !seen.has(id)) {
+            seen.add(id);
+            out.push(buildDescriptor(record, id));
+        }
         for (const child of Object.values(record)) {
-            if (child !== record.id && child !== record.slug && child !== record.model && child !== record.model_slug) {
+            if (child && typeof child === "object")
                 visit(child);
-            }
         }
     };
     visit(payload);
-    return ids;
+    return out;
+}
+// Extracts the family version from a codex slug (e.g. "gpt-5.5-codex" → 5005).
+// Used so models from a newer family float to the top even before the static
+// catalog knows about them.
+function parseCodexFamilyRank(id) {
+    const match = id.match(/(\d+)\.(\d+)/);
+    if (!match)
+        return 0;
+    return parseInt(match[1], 10) * 1000 + parseInt(match[2], 10);
 }
-function sortCodexModelIds(ids) {
-    const preferredModels = getOpenAICodexFallbackModels();
-    const preferred = new Map(preferredModels.map((id, index) => [id, index]));
-    return [...ids].sort((left, right) => {
-        const leftRank = preferred.get(left) ?? Number.MAX_SAFE_INTEGER;
-        const rightRank = preferred.get(right) ?? Number.MAX_SAFE_INTEGER;
+export function sortCodexModelDescriptors(descriptors) {
+    const preferred = new Map(getOpenAICodexFallbackModels().map((id, index) => [id, index]));
+    return [...descriptors].sort((left, right) => {
+        const leftFamily = parseCodexFamilyRank(left.id);
+        const rightFamily = parseCodexFamilyRank(right.id);
+        if (leftFamily !== rightFamily)
+            return rightFamily - leftFamily;
+        const leftRank = preferred.get(left.id) ?? Number.MAX_SAFE_INTEGER;
+        const rightRank = preferred.get(right.id) ?? Number.MAX_SAFE_INTEGER;
         if (leftRank !== rightRank)
             return leftRank - rightRank;
-        return left.localeCompare(right);
+        return left.id.localeCompare(right.id);
     });
 }

package/dist/provider-registry.js

@@ -4,7 +4,7 @@
  * Supports OpenAI-compatible providers with dynamic or static model lists.
  * Reads provider configuration from models.json first, then falls back to config.json.
  */
-import { BUILTIN_PROVIDERS as CATALOG_PROVIDERS, getBuiltinModel, getBuiltinProvider, listBuiltinModels, } from "./model-catalog.js";
+import { BUILTIN_PROVIDERS as CATALOG_PROVIDERS, getBuiltinModel, getBuiltinProvider, listBuiltinModels, registerDynamicModelMetadata, } from "./model-catalog.js";
 import { ModelConfig } from "./model-config.js";
 import { AuthStorage } from "./oauth/index.js";
 import { fetchOpenAICodexModels } from "./provider-openai-codex.js";
@@ -194,12 +194,28 @@ export class ProviderRegistry {
         }
         if (provider.id === "openai" && provider.authType === "oauth" && provider.apiKey) {
             try {
-                const models = await fetchOpenAICodexModels({
+                const descriptors = await fetchOpenAICodexModels({
                     baseURL: provider.baseURL,
                     accessToken: provider.apiKey,
                 });
-                if (models.length > 0) {
-                    return models.map((id) => ({ id, name: id, providerId: provider.id }));
+                const visible = descriptors.filter((d) => d.visibility !== "hide");
+                if (visible.length > 0) {
+                    for (const d of visible) {
+                        const catalogEntry = getBuiltinModel("openai-codex", d.id);
+                        registerDynamicModelMetadata({
+                            id: d.id,
+                            name: d.displayName || catalogEntry?.name || d.id,
+                            providerId: "openai-codex",
+                            reasoningLevels: d.reasoningLevels ?? catalogEntry?.reasoningLevels ?? ["off"],
+                            contextWindow: d.contextWindow ?? catalogEntry?.contextWindow,
+                            toolOutputTokenLimit: d.toolOutputTokenLimit ?? catalogEntry?.toolOutputTokenLimit,
+                        });
+                    }
+                    return visible.map((d) => ({
+                        id: d.id,
+                        name: d.displayName || d.id,
+                        providerId: provider.id,
+                    }));
                 }
             }
             catch {

package/dist/slash-commands/commands.js

@@ -308,6 +308,30 @@ const builtinSlashCommandEntries = [
             ctx.exit();
         },
     },
+    {
+        name: "theme",
+        description: "Switch the color theme. Usage: /theme [auto|light|dark]",
+        async handler(args, ctx) {
+            if (!ctx.setThemeMode || !ctx.getThemeMode || !ctx.getResolvedTheme) {
+                return "Theme switching is only available inside the TUI.";
+            }
+            const arg = args.trim().toLowerCase();
+            if (!arg) {
+                const order = ["auto", "light", "dark"];
+                const current = ctx.getThemeMode();
+                const next = order[(order.indexOf(current) + 1) % order.length];
+                ctx.setThemeMode(next);
+                const resolved = next === "auto" ? ctx.getResolvedTheme() : next;
+                return `Theme: ${next}${next === "auto" ? ` (resolved to ${resolved})` : ""}`;
+            }
+            if (arg !== "auto" && arg !== "light" && arg !== "dark") {
+                return "Usage: /theme [auto|light|dark]";
+            }
+            ctx.setThemeMode(arg);
+            const resolved = arg === "auto" ? ctx.getResolvedTheme() : arg;
+            return `Theme set to ${arg}${arg === "auto" ? ` (resolved to ${resolved})` : ""}.`;
+        },
+    },
     {
         name: "clear",
         description: "Clear the current conversation history",

package/dist/slash-commands/types.d.ts

@@ -8,6 +8,7 @@ import type { SettingsManager } from "../permissions/settings.js";
 import type { McpManager } from "../mcp/manager.js";
 import type { LspService } from "../lsp/index.js";
 import type { MemoryScope } from "../memory/index.js";
+import type { ThemeMode } from "../config.js";
 export interface SlashCommandContext {
     agent: Agent;
     addMessage: (role: "user" | "assistant" | "error", content: string) => void;
@@ -27,6 +28,12 @@ export interface SlashCommandContext {
     runMemoryCompaction?: () => Promise<string>;
     runMemorySummary?: (scope?: MemoryScope) => Promise<string>;
     runMemoryRefresh?: (scope?: MemoryScope) => Promise<string>;
+    /** Get the current theme mode (auto/light/dark) — undefined when running in non-TUI contexts. */
+    getThemeMode?: () => ThemeMode;
+    /** Get the resolved active theme (always light or dark) — undefined when running in non-TUI contexts. */
+    getResolvedTheme?: () => "light" | "dark";
+    /** Persist a new theme mode AND apply it to the running TUI. */
+    setThemeMode?: (mode: ThemeMode) => void;
 }
 /**
  * Return types for a slash command handler:

package/dist/tools/agent-lifecycle.js

@@ -1,4 +1,5 @@
 import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
+import { formatSubagentRoute } from "../agent/subagent-route-format.js";
 export function createSpawnAgentTool() {
     return {
         name: "spawn_agent",
@@ -16,6 +17,7 @@ export function createSpawnAgentTool() {
             properties: {
                 agent_type: { type: "string", description: "Subagent profile or role name. Defaults to default." },
                 agent: { type: "string", description: "Alias for agent_type." },
+                category: { type: "string", description: "Optional semantic category for model/thinking routing, such as quick, deep, explore, review, frontend, or writing." },
                 message: { type: "string", description: "Initial task for the subagent." },
                 task: { type: "string", description: "Alias for message." },
                 fork_context: { type: "boolean", description: "When true, copy recent parent conversation into the child thread." },
@@ -55,15 +57,18 @@ export function createSpawnAgentTool() {
                 const snapshot = await ctx.agent.spawnSubAgent(message, ctx.cwd, {
                     profile: resolved.profile,
                     parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
+                    category: stringArg(args.category),
                     approval: parseApproval(args.approval),
                     abortSignal: ctx.abortSignal,
                     forkContext: args.fork_context === true,
                 });
                 return formatLifecycleResult("spawn_agent", [snapshot], [
-                    `Spawned ${snapshot.nickname} (${snapshot.agentName})`,
+                    `Spawned ${snapshot.nickname} (${formatSnapshotRole(snapshot)})`,
                     `agent_id: ${snapshot.agentId}`,
                     `status: ${snapshot.status}`,
-                    `next: call wait_agent for ${snapshot.agentId} to collect the delegated result`,
+                    ...formatRouteLines(snapshot),
+                    `next: call wait_agent for ${snapshot.agentId} before reporting this subagent's current status or final result`,
+                    "counting: this spawn result creates one unique subagent; later wait_agent results for the same agent_id are updates, not additional subagents",
                 ]);
             }
             catch (error) {
@@ -278,13 +283,17 @@ function isFinalSnapshotStatus(status) {
         || status === "closed";
 }
 function formatSnapshot(snapshot) {
-    const label = `${snapshot.nickname} (${snapshot.agentName})`;
+    const label = `${snapshot.nickname} (${formatSnapshotRole(snapshot)})`;
     const lines = [
         `## ${label}`,
         `agent_id: ${snapshot.agentId}`,
         `status: ${snapshot.status}`,
-        `task: ${snapshot.task}`,
     ];
+    if (snapshot.category) {
+        lines.push(`category: ${snapshot.category}`);
+    }
+    lines.push(...formatRouteLines(snapshot));
+    lines.push(`task: ${snapshot.task}`);
     if (snapshot.summary) {
         lines.push("", "Summary:", snapshot.summary);
     }
@@ -299,6 +308,13 @@ function formatSnapshot(snapshot) {
     }
     return lines;
 }
+function formatSnapshotRole(snapshot) {
+    return [snapshot.agentName, snapshot.category ? `/${snapshot.category}` : ""].join("") || "default";
+}
+function formatRouteLines(snapshot) {
+    const route = formatSubagentRoute(snapshot.route, { includeThinking: true });
+    return route ? [`route: ${route}`] : [];
+}
 function snapshotToMetadata(snapshot) {
     return {
         subAgentId: snapshot.agentId,
@@ -306,6 +322,8 @@ function snapshotToMetadata(snapshot) {
         nickname: snapshot.nickname,
         status: snapshot.status === "closed" ? "cancelled" : snapshot.status,
         profileSource: snapshot.profileSource,
+        category: snapshot.category,
+        route: snapshot.route,
         task: snapshot.task,
         summary: snapshot.summary,
         toolNotes: snapshot.toolNotes,

package/dist/tools/edit.js

@@ -5,7 +5,6 @@
  */
 import { constants } from "node:fs";
 import { access, readFile, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { countUnifiedDiffChanges } from "../diff-stats.js";
@@ -13,6 +12,7 @@ import { formatDiagnosticBlocks } from "../lsp/index.js";
 import { applyEditsToContent, EditApplyError, formatEditMatchNotes } from "./edit-apply.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { isWithinWorkspace } from "./file-state.js";
+import { resolveToolPath } from "./path-utils.js";
 export function createEditTool(cwd, approval, lsp, fileState) {
     return {
         name: "edit",
@@ -39,7 +39,7 @@ export function createEditTool(cwd, approval, lsp, fileState) {
             required: ["path", "edits"],
         },
         async execute(args) {
-            const filePath = resolve(cwd, args.path);
+            const filePath = resolveToolPath(cwd, args.path);
             if (!isWithinWorkspace(cwd, filePath)) {
                 return {
                     content: `Error: Edit path is outside the workspace: ${filePath}`,

package/dist/tools/glob.js

@@ -5,6 +5,7 @@ import { readdir, stat } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import picomatch from "picomatch";
 import { isSensitivePath } from "./sensitive-paths.js";
+import { resolveToolPath } from "./path-utils.js";
 const MAX_RESULTS = 100;
 const DEFAULT_IGNORES = new Set([
     ".git",
@@ -31,7 +32,7 @@ export function createGlobTool(cwd) {
             required: ["pattern"],
         },
         async execute(args, ctx) {
-            const root = resolve(cwd, typeof args.path === "string" && args.path.trim() ? args.path : ".");
+            const root = resolveToolPath(cwd, typeof args.path === "string" && args.path.trim() ? args.path : ".");
             const pattern = String(args.pattern || "").trim();
             if (!pattern) {
                 return { content: "Error: glob pattern is required", isError: true, status: "command_error" };

package/dist/tools/grep.js

@@ -2,9 +2,9 @@
  * Grep tool - search file contents using ripgrep.
  */
 import { execFile } from "node:child_process";
-import { resolve } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
 import { analyzeToolIntent } from "../agent/tool-intent.js";
+import { resolveToolPath } from "./path-utils.js";
 const MAX_MATCHES = 100;
 export function createGrepTool(cwd) {
     return {
@@ -22,7 +22,7 @@ export function createGrepTool(cwd) {
             required: ["pattern"],
         },
         async execute(args) {
-            const searchPath = args.path ? resolve(cwd, args.path) : cwd;
+            const searchPath = args.path ? resolveToolPath(cwd, args.path) : cwd;
             const pattern = String(args.pattern);
             const intent = analyzeToolIntent({
                 name: "grep",

package/dist/tools/lsp.js

@@ -1,8 +1,8 @@
 import { access } from "node:fs/promises";
 import { constants } from "node:fs";
-import { resolve } from "node:path";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { getLspService } from "../lsp/index.js";
+import { resolveToolPath } from "./path-utils.js";
 const OPERATIONS = [
     "goToDefinition",
     "findReferences",
@@ -37,7 +37,7 @@ export function createLspTool(cwd, lsp = getLspService(cwd), approval) {
             if (!OPERATIONS.includes(operation)) {
                 return { content: `Error: Unsupported LSP operation: ${args.operation}`, isError: true };
             }
-            const file = resolve(cwd, String(args.filePath));
+            const file = resolveToolPath(cwd, args.filePath);
             try {
                 await access(file, constants.R_OK);
             }

package/dist/tools/path-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function expandHomePath(value: unknown): string;
+export declare function resolveToolPath(cwd: string, value: unknown, fallback?: string): string;

package/dist/tools/path-utils.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function expandHomePath(value) {
+    const text = String(value ?? "");
+    if (text === "~")
+        return homedir();
+    if (text.startsWith("~/") || text.startsWith("~\\")) {
+        return join(homedir(), text.slice(2));
+    }
+    return text;
+}
+export function resolveToolPath(cwd, value, fallback = ".") {
+    const text = String(value ?? "");
+    const path = text === "" ? fallback : text;
+    return resolve(cwd, expandHomePath(path));
+}