minovative-mind-cli 2.0.0 → 2.1.0

package/dist/services/ai.js

@@ -5,6 +5,20 @@ import { getAuthorizedIdToken } from './auth.js';
 import { debugLog } from '../utils/logger.js';
 import { GENERAL_CHAT_INSTRUCTION, PLAN_EXECUTION_INSTRUCTION, PLAN_MODE_INSTRUCTION, CONTEXT_SYSTEM_INSTRUCTION, INTENT_ROUTER_SYSTEM_INSTRUCTION, WEB_SEARCH_SYSTEM_INSTRUCTION, EXECUTION_COMPLEXITY_SYSTEM_INSTRUCTION, INVESTIGATION_COMPLEXITY_SYSTEM_INSTRUCTION, } from '../utils/systemPrompts.js';
 import { getMetricCollector } from './metrics.js';
+import { workspaceRegistry } from './workspaceRegistry.js';
+function getMultiWorkspaceBlock() {
+    const summary = workspaceRegistry.buildPromptSummary();
+    if (!summary)
+        return '';
+    return `<multi_workspace>
+The user has registered external workspaces that you can access using the @alias/ prefix:
+${summary}
+
+To read, modify, or search files in an external workspace, prefix the file path with the alias (e.g., "@backend/src/routes.ts"). To search across ALL workspaces, use grep_search with workspace="all".
+
+When the user asks to "transfer", "sync", or "port" features between projects, read the source files from one workspace and apply the changes to the target.
+</multi_workspace>`;
+}
 // ─── Model Overrides (for Regression Testing) ────────────────────────
 let contextModelOverride = null;
 let contextTempOverride = null;
@@ -261,7 +275,7 @@ export function getGeneralChatConfig() {
 }
 export function getPlanExecutionConfig() {
     return {
-        systemInstruction: PLAN_EXECUTION_INSTRUCTION,
+        systemInstruction: PLAN_EXECUTION_INSTRUCTION.replace('{{MULTI_WORKSPACE_BLOCK}}', getMultiWorkspaceBlock()),
         tools: [{ functionDeclarations: getToolDeclarations() }],
     };
 }
@@ -505,7 +519,7 @@ export function createContextAgentSession() {
     let model = contextModelOverride || getGlobalActiveModel();
     if (model === 'auto')
         model = GEMINI_MODELS.FLASH_3_5;
-    return new ProxyChatSession(model, CONTEXT_SYSTEM_INSTRUCTION, contextTools, {
+    return new ProxyChatSession(model, CONTEXT_SYSTEM_INSTRUCTION.replace('{{MULTI_WORKSPACE_BLOCK}}', getMultiWorkspaceBlock()), contextTools, {
         maxOutputTokens: MAX_OUTPUT_TOKENS,
         temperature: contextTempOverride !== null ? contextTempOverride : 1,
         topP: 0.95,

package/dist/services/contextAgent.js

@@ -192,12 +192,24 @@ export async function gatherContext(workspaceRoot, userRequest, chatHistory = ''
     if (!needsContext) {
         return { contextResult: null, targetAgent, chainedMessages: [] };
     }
-    const projectTreeResult = await listDirectory(workspaceRoot, '.', 10);
-    let projectTree = projectTreeResult.output;
-    if (projectTree.length > 30000) {
-        projectTree = projectTree.substring(0, 30000) + '\n... (Project tree truncated due to size)';
+    const { workspaceRegistry } = await import('./workspaceRegistry.js');
+    const allRoots = workspaceRegistry.getAllRoots(workspaceRoot);
+    let projectTree = '';
+    let primaryProjectType = 'Unknown';
+    for (const { alias, root } of allRoots) {
+        const label = alias ? `@${alias} (${root})` : `Primary Workspace (${root})`;
+        const treeResult = await listDirectory(root, '.', 10);
+        let tree = treeResult.output;
+        if (tree.length > 30000) {
+            tree = tree.substring(0, 30000) + '\\n... (Project tree truncated due to size)';
+        }
+        const type = await detectProjectType(root);
+        if (!alias) {
+            primaryProjectType = type;
+        }
+        projectTree += `=== ${label} ===\\nProject Type: ${type}\\n${tree}\\n\\n`;
     }
-    const projectType = await detectProjectType(workspaceRoot);
+    const projectType = primaryProjectType;
     // ─── Parallel Investigation Gate ─────────────────────────────
     if (isSubAgentsEnabled()) {
         // Determine complexity and domain breakdown

package/dist/services/orchestration/investigationAgent.js

@@ -11,7 +11,7 @@
  * components" + "Auth UI styling") and produces an `InvestigationResult` containing
  * the files it found and a summary of its findings.
  */
-import { ProxyChatSession, getContextToolDeclarations } from '../ai.js';
+import { ProxyChatSession, getContextToolDeclarations, getGlobalActiveModel } from '../ai.js';
 import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
 import { CONTEXT_SYSTEM_INSTRUCTION } from '../../utils/systemPrompts.js';
 import { debugLog } from '../../utils/logger.js';
@@ -47,7 +47,10 @@ export class InvestigationAgentRunner {
         this.readCache = readCache;
         this.projectTree = projectTree;
         this.projectType = projectType;
-        this.chat = new ProxyChatSession(GEMINI_MODELS.FLASH_3_5, this.buildSystemInstruction(), getContextToolDeclarations(), {
+        let model = getGlobalActiveModel();
+        if (model === GEMINI_MODELS.AUTO)
+            model = GEMINI_MODELS.FLASH_3_5;
+        this.chat = new ProxyChatSession(model, this.buildSystemInstruction(), getContextToolDeclarations(), {
             maxOutputTokens: MAX_OUTPUT_TOKENS,
             temperature: 1,
             topP: 0.95,

package/dist/services/orchestration/orchestrator.js

@@ -10,7 +10,7 @@
  */
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { ProxyChatSession } from '../ai.js';
+import { ProxyChatSession, getGlobalActiveModel } from '../ai.js';
 import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
 import { debugLog } from '../../utils/logger.js';
 import { MessageBus } from './messageBus.js';
@@ -61,7 +61,10 @@ export class Orchestrator {
         this.inputHandler = inputHandler;
         this.bus = new MessageBus(workspaceRoot, conversationId);
         this.locks = new FileLockRegistry();
-        this.pmChat = new ProxyChatSession(GEMINI_MODELS.FLASH_3_5, PM_SYSTEM_INSTRUCTION, [], {
+        let model = getGlobalActiveModel();
+        if (model === GEMINI_MODELS.AUTO)
+            model = GEMINI_MODELS.FLASH_3_5;
+        this.pmChat = new ProxyChatSession(model, PM_SYSTEM_INSTRUCTION, [], {
             maxOutputTokens: MAX_OUTPUT_TOKENS,
             temperature: 0.1,
             responseMimeType: 'application/json',

package/dist/services/orchestration/subAgent.js

@@ -4,7 +4,7 @@
  * Implements the lifecycle, health monitoring, and tool-loop execution for a single
  * parallelized sub-agent.
  */
-import { ProxyChatSession } from '../ai.js';
+import { ProxyChatSession, getGlobalActiveModel } from '../ai.js';
 import { GEMINI_MODELS, MAX_OUTPUT_TOKENS } from '../../utils/config.js';
 import { executeScopedTool, getScopedToolDeclarations } from './scopedTools.js';
 import { debugLog } from '../../utils/logger.js';
@@ -32,8 +32,11 @@ export class SubAgentRunner {
         this.bus = bus;
         this.locks = locks;
         this.globalContext = globalContext;
+        let model = getGlobalActiveModel();
+        if (model === GEMINI_MODELS.AUTO)
+            model = GEMINI_MODELS.FLASH_3_5;
         // Sub-agents default to flash-3.5 for better reasoning capabilities
-        this.chat = new ProxyChatSession(GEMINI_MODELS.FLASH_3_5, this.buildSystemInstruction(), [{ functionDeclarations: getScopedToolDeclarations() }], {
+        this.chat = new ProxyChatSession(model, this.buildSystemInstruction(), [{ functionDeclarations: getScopedToolDeclarations() }], {
             maxOutputTokens: MAX_OUTPUT_TOKENS,
             temperature: 0.3, // Lower temperature for more focused execution
             topP: 0.95,

package/dist/services/workspaceRegistry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Represents a single registered external workspace entry in the global registry.
+ */
+export interface RegisteredWorkspace {
+    /** User-chosen short alias (e.g., "backend", "shared-lib"). Used as the `@alias/` prefix. */
+    alias: string;
+    /** Validated, normalized absolute path on disk. */
+    absolutePath: string;
+    /** Unix epoch timestamp (ms) when this workspace was registered. */
+    registeredAt: number;
+}
+/**
+ * Result of resolving an `@alias/relative/path` string against the workspace registry.
+ */
+export interface ResolvedWorkspacePath {
+    /** The alias that was matched (e.g., "backend"). */
+    alias: string;
+    /** The absolute root directory of the matched registered workspace. */
+    workspaceRoot: string;
+    /** The relative path within that workspace (e.g., "src/routes.ts"). */
+    relativePath: string;
+    /** The fully resolved absolute path to the target file or directory. */
+    absolutePath: string;
+}
+/**
+ * Service that manages a global registry of external workspace roots.
+ *
+ * Workspaces are registered with short aliases (e.g., "backend") and referenced
+ * in file paths using the `@alias/path` prefix syntax. The registry is persisted
+ * globally at `~/.minovative-mind-cli/workspaces.json` so registrations carry
+ * across different primary workspaces.
+ *
+ * @remarks
+ * This is a singleton — use the exported `workspaceRegistry` instance.
+ * All filesystem access goes through this service to maintain the security
+ * boundary: the agent can only touch the primary workspace and explicitly
+ * registered secondary workspaces.
+ */
+declare class WorkspaceRegistry {
+    /** In-memory map of alias → registered workspace. */
+    private workspaces;
+    /** Whether the registry has been loaded from disk. */
+    private initialized;
+    /**
+     * Initializes the registry by loading persisted workspace entries from disk.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    init(): void;
+    /**
+     * Registers a new external workspace root with the given alias.
+     *
+     * @param alias - Short identifier for the workspace (e.g., "backend").
+     *   Must be lowercase alphanumeric with hyphens/underscores, 1–30 chars.
+     * @param absolutePath - Absolute path to the workspace root directory.
+     *   Must exist on disk and be a directory.
+     * @returns The created `RegisteredWorkspace`, or throws on validation failure.
+     * @throws Error if the alias is invalid, the path doesn't exist, or the alias is already taken.
+     */
+    register(alias: string, absolutePath: string): RegisteredWorkspace;
+    /**
+     * Removes a registered workspace by alias.
+     *
+     * @param alias - The alias to unregister.
+     * @returns `true` if the workspace was found and removed, `false` otherwise.
+     */
+    unregister(alias: string): boolean;
+    /**
+     * Returns all registered workspaces as an array, sorted by alias.
+     */
+    list(): RegisteredWorkspace[];
+    /**
+     * Returns the number of registered workspaces.
+     */
+    get size(): number;
+    /**
+     * Checks whether any external workspaces are registered.
+     */
+    hasWorkspaces(): boolean;
+    /**
+     * Looks up a workspace by alias.
+     *
+     * @param alias - The alias to find (without the `@` prefix).
+     * @returns The registered workspace, or `undefined` if not found.
+     */
+    get(alias: string): RegisteredWorkspace | undefined;
+    /**
+     * Returns all workspace roots (primary + registered secondaries).
+     *
+     * @param primaryRoot - The primary workspace root (from `process.cwd()`).
+     * @returns An array of `{ alias: string | null, root: string }` entries.
+     *   The primary workspace has `alias: null`.
+     */
+    getAllRoots(primaryRoot: string): Array<{
+        alias: string | null;
+        root: string;
+    }>;
+    /**
+     * Resolves an `@alias/relative/path` string into its constituent parts.
+     *
+     * @param filePath - A file path that may or may not start with `@alias/`.
+     * @returns A `ResolvedWorkspacePath` if the path has a valid `@alias/` prefix
+     *   and the alias is registered, or `null` if the path is a standard
+     *   workspace-relative path (no `@` prefix or unrecognized alias).
+     * @throws Error if the path has an `@` prefix but the alias is not registered.
+     */
+    resolve(filePath: string): ResolvedWorkspacePath | null;
+    /**
+     * Checks if a given file path uses the `@alias/` prefix syntax.
+     *
+     * @param filePath - The path to check.
+     * @returns `true` if the path starts with `@`.
+     */
+    isAliasedPath(filePath: string): boolean;
+    /**
+     * Builds a formatted summary of all registered workspaces for system prompt injection.
+     *
+     * @returns A human-readable string listing all aliases and their paths,
+     *   or an empty string if no workspaces are registered.
+     */
+    buildPromptSummary(): string;
+    /**
+     * Loads the workspace registry from the global config file.
+     * Silently handles missing or corrupted files.
+     */
+    private loadFromDisk;
+    /**
+     * Persists the current workspace registry to the global config file.
+     * Creates the config directory if it doesn't exist.
+     */
+    private saveToDisk;
+}
+/**
+ * Singleton instance of the WorkspaceRegistry service.
+ * Initialize with `workspaceRegistry.init()` during CLI startup.
+ */
+export declare const workspaceRegistry: WorkspaceRegistry;
+export {};

package/dist/services/workspaceRegistry.js

@@ -0,0 +1,270 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { debugLog } from '../utils/logger.js';
+/** Regex for valid alias names: lowercase alphanumeric, hyphens, underscores, 1–30 chars. */
+const ALIAS_PATTERN = /^[a-z0-9][a-z0-9_-]{0,29}$/;
+/** Global config directory for cross-project persistence. */
+const GLOBAL_CONFIG_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '~', '.minovative-mind-cli');
+/** Path to the global workspace registry file. */
+const REGISTRY_FILE = path.join(GLOBAL_CONFIG_DIR, 'workspaces.json');
+/**
+ * Service that manages a global registry of external workspace roots.
+ *
+ * Workspaces are registered with short aliases (e.g., "backend") and referenced
+ * in file paths using the `@alias/path` prefix syntax. The registry is persisted
+ * globally at `~/.minovative-mind-cli/workspaces.json` so registrations carry
+ * across different primary workspaces.
+ *
+ * @remarks
+ * This is a singleton — use the exported `workspaceRegistry` instance.
+ * All filesystem access goes through this service to maintain the security
+ * boundary: the agent can only touch the primary workspace and explicitly
+ * registered secondary workspaces.
+ */
+class WorkspaceRegistry {
+    /** In-memory map of alias → registered workspace. */
+    workspaces = new Map();
+    /** Whether the registry has been loaded from disk. */
+    initialized = false;
+    /**
+     * Initializes the registry by loading persisted workspace entries from disk.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    init() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        this.loadFromDisk();
+    }
+    /**
+     * Registers a new external workspace root with the given alias.
+     *
+     * @param alias - Short identifier for the workspace (e.g., "backend").
+     *   Must be lowercase alphanumeric with hyphens/underscores, 1–30 chars.
+     * @param absolutePath - Absolute path to the workspace root directory.
+     *   Must exist on disk and be a directory.
+     * @returns The created `RegisteredWorkspace`, or throws on validation failure.
+     * @throws Error if the alias is invalid, the path doesn't exist, or the alias is already taken.
+     */
+    register(alias, absolutePath) {
+        const normalizedAlias = alias.toLowerCase().trim();
+        // Validate alias format
+        if (!ALIAS_PATTERN.test(normalizedAlias)) {
+            throw new Error(`Invalid workspace alias "${normalizedAlias}". Must be 1-30 characters, ` +
+                `lowercase alphanumeric, hyphens, or underscores, starting with a letter or digit.`);
+        }
+        // Check for duplicate aliases
+        if (this.workspaces.has(normalizedAlias)) {
+            throw new Error(`Workspace alias "${normalizedAlias}" is already registered ` +
+                `(→ ${this.workspaces.get(normalizedAlias).absolutePath}). ` +
+                `Remove it first with /workspaces → Remove.`);
+        }
+        // Normalize and validate the path
+        const normalizedPath = path.resolve(absolutePath);
+        if (!fs.existsSync(normalizedPath)) {
+            throw new Error(`Path does not exist: "${normalizedPath}"`);
+        }
+        const stats = fs.statSync(normalizedPath);
+        if (!stats.isDirectory()) {
+            throw new Error(`Path is not a directory: "${normalizedPath}"`);
+        }
+        // Prevent registering sensitive system directories
+        const blockedRoots = ['/', '/etc', '/usr', '/bin', '/sbin', '/var', '/tmp', '/System', '/Library'];
+        if (blockedRoots.includes(normalizedPath) || normalizedPath === path.parse(normalizedPath).root) {
+            throw new Error(`Cannot register system root directory "${normalizedPath}". ` +
+                `Only project directories are allowed.`);
+        }
+        // Prevent duplicate paths under different aliases
+        for (const [existingAlias, existing] of this.workspaces) {
+            if (existing.absolutePath === normalizedPath) {
+                throw new Error(`This path is already registered under alias "${existingAlias}". ` +
+                    `Remove it first if you want to re-register with a different alias.`);
+            }
+        }
+        const workspace = {
+            alias: normalizedAlias,
+            absolutePath: normalizedPath,
+            registeredAt: Date.now(),
+        };
+        this.workspaces.set(normalizedAlias, workspace);
+        this.saveToDisk();
+        debugLog(`Registered workspace: @${normalizedAlias} → ${normalizedPath}`);
+        return workspace;
+    }
+    /**
+     * Removes a registered workspace by alias.
+     *
+     * @param alias - The alias to unregister.
+     * @returns `true` if the workspace was found and removed, `false` otherwise.
+     */
+    unregister(alias) {
+        const normalizedAlias = alias.toLowerCase().trim();
+        const existed = this.workspaces.delete(normalizedAlias);
+        if (existed) {
+            this.saveToDisk();
+            debugLog(`Unregistered workspace: @${normalizedAlias}`);
+        }
+        return existed;
+    }
+    /**
+     * Returns all registered workspaces as an array, sorted by alias.
+     */
+    list() {
+        return Array.from(this.workspaces.values()).sort((a, b) => a.alias.localeCompare(b.alias));
+    }
+    /**
+     * Returns the number of registered workspaces.
+     */
+    get size() {
+        return this.workspaces.size;
+    }
+    /**
+     * Checks whether any external workspaces are registered.
+     */
+    hasWorkspaces() {
+        return this.workspaces.size > 0;
+    }
+    /**
+     * Looks up a workspace by alias.
+     *
+     * @param alias - The alias to find (without the `@` prefix).
+     * @returns The registered workspace, or `undefined` if not found.
+     */
+    get(alias) {
+        return this.workspaces.get(alias.toLowerCase().trim());
+    }
+    /**
+     * Returns all workspace roots (primary + registered secondaries).
+     *
+     * @param primaryRoot - The primary workspace root (from `process.cwd()`).
+     * @returns An array of `{ alias: string | null, root: string }` entries.
+     *   The primary workspace has `alias: null`.
+     */
+    getAllRoots(primaryRoot) {
+        const roots = [{ alias: null, root: primaryRoot }];
+        for (const ws of this.workspaces.values()) {
+            // Skip if a registered workspace happens to be the same as the primary
+            if (ws.absolutePath !== path.resolve(primaryRoot)) {
+                roots.push({ alias: ws.alias, root: ws.absolutePath });
+            }
+        }
+        return roots;
+    }
+    /**
+     * Resolves an `@alias/relative/path` string into its constituent parts.
+     *
+     * @param filePath - A file path that may or may not start with `@alias/`.
+     * @returns A `ResolvedWorkspacePath` if the path has a valid `@alias/` prefix
+     *   and the alias is registered, or `null` if the path is a standard
+     *   workspace-relative path (no `@` prefix or unrecognized alias).
+     * @throws Error if the path has an `@` prefix but the alias is not registered.
+     */
+    resolve(filePath) {
+        if (!filePath.startsWith('@')) {
+            return null;
+        }
+        // Extract alias and relative path from "@alias/relative/path"
+        const withoutAt = filePath.substring(1);
+        const slashIndex = withoutAt.indexOf('/');
+        const alias = slashIndex === -1 ? withoutAt : withoutAt.substring(0, slashIndex);
+        const relativePath = slashIndex === -1 ? '.' : withoutAt.substring(slashIndex + 1);
+        const workspace = this.workspaces.get(alias.toLowerCase());
+        if (!workspace) {
+            throw new Error(`Unknown workspace alias "@${alias}". ` +
+                `Registered workspaces: ${this.list().map((w) => `@${w.alias}`).join(', ') || '(none)'}. ` +
+                `Use /workspaces to add one.`);
+        }
+        const absolutePath = path.resolve(workspace.absolutePath, relativePath);
+        return {
+            alias: workspace.alias,
+            workspaceRoot: workspace.absolutePath,
+            relativePath,
+            absolutePath,
+        };
+    }
+    /**
+     * Checks if a given file path uses the `@alias/` prefix syntax.
+     *
+     * @param filePath - The path to check.
+     * @returns `true` if the path starts with `@`.
+     */
+    isAliasedPath(filePath) {
+        return filePath.startsWith('@');
+    }
+    /**
+     * Builds a formatted summary of all registered workspaces for system prompt injection.
+     *
+     * @returns A human-readable string listing all aliases and their paths,
+     *   or an empty string if no workspaces are registered.
+     */
+    buildPromptSummary() {
+        if (this.workspaces.size === 0)
+            return '';
+        const lines = this.list().map((ws) => `- @${ws.alias} → ${ws.absolutePath}`);
+        return lines.join('\n');
+    }
+    // ─── Persistence ───────────────────────────────────────────────────
+    /**
+     * Loads the workspace registry from the global config file.
+     * Silently handles missing or corrupted files.
+     */
+    loadFromDisk() {
+        try {
+            if (!fs.existsSync(REGISTRY_FILE)) {
+                debugLog('Workspace registry file not found, starting fresh.');
+                return;
+            }
+            const raw = fs.readFileSync(REGISTRY_FILE, 'utf-8');
+            const data = JSON.parse(raw);
+            if (!Array.isArray(data)) {
+                debugLog('Workspace registry file has invalid format, starting fresh.');
+                return;
+            }
+            // Validate each entry and skip invalid ones
+            for (const entry of data) {
+                if (typeof entry.alias === 'string' &&
+                    typeof entry.absolutePath === 'string' &&
+                    ALIAS_PATTERN.test(entry.alias)) {
+                    // Only load if the directory still exists
+                    if (fs.existsSync(entry.absolutePath)) {
+                        this.workspaces.set(entry.alias, entry);
+                    }
+                    else {
+                        debugLog(`Skipping stale workspace @${entry.alias} — path no longer exists: ${entry.absolutePath}`);
+                    }
+                }
+            }
+            debugLog(`Loaded ${this.workspaces.size} workspace(s) from global registry.`);
+        }
+        catch (err) {
+            debugLog(`Failed to load workspace registry: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Persists the current workspace registry to the global config file.
+     * Creates the config directory if it doesn't exist.
+     */
+    saveToDisk() {
+        try {
+            // Ensure the global config directory exists
+            if (!fs.existsSync(GLOBAL_CONFIG_DIR)) {
+                fs.mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
+            }
+            const data = Array.from(this.workspaces.values());
+            const tempPath = `${REGISTRY_FILE}.${Date.now()}.tmp`;
+            fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), 'utf-8');
+            // Atomic rename to prevent corruption
+            fs.renameSync(tempPath, REGISTRY_FILE);
+            debugLog(`Saved ${data.length} workspace(s) to global registry.`);
+        }
+        catch (err) {
+            debugLog(`Failed to save workspace registry: ${err instanceof Error ? err.message : String(err)}`);
+            // Non-fatal: the in-memory state is still correct
+        }
+    }
+}
+/**
+ * Singleton instance of the WorkspaceRegistry service.
+ * Initialize with `workspaceRegistry.init()` during CLI startup.
+ */
+export const workspaceRegistry = new WorkspaceRegistry();

package/dist/utils/contextPrompts.js

@@ -43,7 +43,13 @@ ${context.webSearchSummary}
         injection += `\n## Relevant File Contents\n`;
         for (const [filePath, contentObj] of context.relevantFiles.entries()) {
             const contentText = contentObj.text;
-            injection += `<workspace_file path="${filePath}">
+            let aliasAttr = '';
+            if (filePath.startsWith('@')) {
+                const slashIndex = filePath.indexOf('/');
+                const alias = slashIndex === -1 ? filePath.substring(1) : filePath.substring(1, slashIndex);
+                aliasAttr = ` workspace="${alias}"`;
+            }
+            injection += `<workspace_file path="${filePath}"${aliasAttr}>
 <content_data><![CDATA[
 ${sanitizeForCDATA(contentText)}
 ]]\\u200B></content_data>

package/dist/utils/pathSecurity.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Result of resolving a path in a multi-workspace environment.
+ * Contains the resolved absolute path along with metadata about which workspace was matched.
+ */
+export interface ResolvedPath {
+    /** The fully resolved, validated absolute path. */
+    absolutePath: string;
+    /** The workspace root directory that this path resolved against. */
+    workspaceRoot: string;
+    /** The relative path within the matched workspace. */
+    relativePath: string;
+    /** The workspace alias if an external workspace was matched, or `null` for the primary workspace. */
+    alias: string | null;
+}
 /**
  * Resolves a file path against the workspace root and ensures it does not
  * break out of the workspace directory (path traversal defense).
@@ -8,3 +22,20 @@
  * @throws Error if the resolved path is outside the workspace
  */
 export declare function resolveAndValidatePath(workspaceRoot: string, filePath: string): string;
+/**
+ * Resolves a file path that may use the `@alias/path` multi-workspace prefix syntax.
+ *
+ * If the path starts with `@`, it is resolved against the matching registered workspace.
+ * Otherwise, it falls through to standard single-workspace resolution against `primaryRoot`.
+ *
+ * Security guarantees are identical to `resolveAndValidatePath`:
+ * - Path traversal via `..` is blocked (resolved path must remain within the matched root)
+ * - Absolute paths (outside `@alias/` syntax) are rejected
+ * - Only explicitly registered workspace roots are accessible
+ *
+ * @param primaryRoot - The primary workspace root (from `process.cwd()`).
+ * @param filePath - A file path that may or may not use `@alias/` prefix syntax.
+ * @returns A `ResolvedPath` with the absolute path and workspace metadata.
+ * @throws Error on path traversal, unknown alias, or invalid path.
+ */
+export declare function resolveAndValidateMultiWorkspacePath(primaryRoot: string, filePath: string): ResolvedPath;

package/dist/utils/pathSecurity.js

@@ -1,4 +1,5 @@
 import * as path from 'path';
+import { workspaceRegistry } from '../services/workspaceRegistry.js';
 /**
  * Resolves a file path against the workspace root and ensures it does not
  * break out of the workspace directory (path traversal defense).
@@ -24,3 +25,50 @@ export function resolveAndValidatePath(workspaceRoot, filePath) {
     }
     return normalizedResolved;
 }
+/**
+ * Resolves a file path that may use the `@alias/path` multi-workspace prefix syntax.
+ *
+ * If the path starts with `@`, it is resolved against the matching registered workspace.
+ * Otherwise, it falls through to standard single-workspace resolution against `primaryRoot`.
+ *
+ * Security guarantees are identical to `resolveAndValidatePath`:
+ * - Path traversal via `..` is blocked (resolved path must remain within the matched root)
+ * - Absolute paths (outside `@alias/` syntax) are rejected
+ * - Only explicitly registered workspace roots are accessible
+ *
+ * @param primaryRoot - The primary workspace root (from `process.cwd()`).
+ * @param filePath - A file path that may or may not use `@alias/` prefix syntax.
+ * @returns A `ResolvedPath` with the absolute path and workspace metadata.
+ * @throws Error on path traversal, unknown alias, or invalid path.
+ */
+export function resolveAndValidateMultiWorkspacePath(primaryRoot, filePath) {
+    // ─── @alias/ Resolution Path ─────────────────────────────────────
+    if (filePath.startsWith('@')) {
+        const resolved = workspaceRegistry.resolve(filePath);
+        if (!resolved) {
+            // resolve() returns null if the alias is not recognized — this shouldn't
+            // happen because resolve() throws on unknown aliases, but guard defensively.
+            throw new Error(`Failed to resolve workspace path: "${filePath}"`);
+        }
+        // Apply the same traversal check: resolved path must stay within the workspace root
+        const normalizedRoot = path.normalize(resolved.workspaceRoot);
+        const normalizedResolved = path.normalize(resolved.absolutePath);
+        if (!normalizedResolved.startsWith(normalizedRoot + path.sep) && normalizedResolved !== normalizedRoot) {
+            throw new Error(`Path security violation: Path "${filePath}" escapes workspace @${resolved.alias} root.`);
+        }
+        return {
+            absolutePath: normalizedResolved,
+            workspaceRoot: resolved.workspaceRoot,
+            relativePath: resolved.relativePath,
+            alias: resolved.alias,
+        };
+    }
+    // ─── Standard Single-Workspace Path ──────────────────────────────
+    const absolutePath = resolveAndValidatePath(primaryRoot, filePath);
+    return {
+        absolutePath,
+        workspaceRoot: primaryRoot,
+        relativePath: filePath,
+        alias: null,
+    };
+}