@intellectronica/ruler 0.3.41 → 0.3.42

package/dist/core/UnifiedConfigLoader.js

@@ -42,8 +42,7 @@ const RuleProcessor_1 = require("./RuleProcessor");
 const FileSystemUtils = __importStar(require("./FileSystemUtils"));
 async function loadUnifiedConfig(options) {
     // Resolve the effective .ruler directory (local or global), mirroring the main loader behavior
-    const resolvedRulerDir = (await FileSystemUtils.findRulerDir(options.projectRoot, true)) ||
-        path.join(options.projectRoot, '.ruler');
+    const resolvedRulerDir = (await FileSystemUtils.findRulerDir(options.projectRoot, options.checkGlobal ?? true)) || path.join(options.projectRoot, '.ruler');
     const meta = {
         projectRoot: options.projectRoot,
         rulerDir: resolvedRulerDir,
@@ -62,11 +61,14 @@ async function loadUnifiedConfig(options) {
         meta.configFile = tomlFile;
     }
     catch (err) {
-        if (err.code !== 'ENOENT') {
+        if (options.configPath ||
+            err.code !== 'ENOENT') {
             diagnostics.push({
-                severity: 'warning',
+                severity: options.configPath ? 'error' : 'warning',
                 code: 'TOML_READ_ERROR',
-                message: 'Failed to read ruler.toml',
+                message: options.configPath
+                    ? 'Failed to read explicit config file'
+                    : 'Failed to read ruler.toml',
                 file: tomlFile,
                 detail: err.message,
             });
@@ -104,37 +106,41 @@ async function loadUnifiedConfig(options) {
         nested,
         skills: skillsConfig,
     };
+    const includeAgentsInRules = (() => {
+        if (!tomlRaw || typeof tomlRaw !== 'object')
+            return false;
+        const raw = tomlRaw;
+        const agents = raw.agents;
+        const subagents = raw.subagents;
+        return ((agents &&
+            typeof agents === 'object' &&
+            agents.include_in_rules === true) ||
+            (subagents &&
+                typeof subagents === 'object' &&
+                subagents.include_in_rules === true));
+    })();
     // Collect rule markdown files
     let ruleFiles = [];
     try {
-        const dirEntries = await fs_1.promises.readdir(meta.rulerDir, { withFileTypes: true });
-        const mdFiles = dirEntries
-            .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
-            .map((e) => path.join(meta.rulerDir, e.name));
-        // Sort lexicographically then ensure AGENTS.md first
-        mdFiles.sort((a, b) => a.localeCompare(b));
-        mdFiles.sort((a, b) => {
-            const aIs = /agents\.md$/i.test(a);
-            const bIs = /agents\.md$/i.test(b);
-            if (aIs && !bIs)
-                return -1;
-            if (bIs && !aIs)
-                return 1;
-            return 0;
+        const mdFiles = await FileSystemUtils.readMarkdownFiles(meta.rulerDir, {
+            includeAgents: includeAgentsInRules,
         });
         let order = 0;
         ruleFiles = await Promise.all(mdFiles.map(async (file) => {
-            const content = await fs_1.promises.readFile(file, 'utf8');
-            const stat = await fs_1.promises.stat(file);
+            const stat = await fs_1.promises.stat(file.path);
+            const relativeFromRuler = path.relative(meta.rulerDir, file.path);
+            const relativePath = relativeFromRuler.startsWith('..')
+                ? path.relative(path.dirname(meta.rulerDir), file.path)
+                : relativeFromRuler;
             return {
-                path: file,
-                relativePath: path.basename(file),
-                content,
-                contentHash: (0, hash_1.sha256)(content),
+                path: file.path,
+                relativePath: relativePath.replace(/\\/g, '/'),
+                content: file.content,
+                contentHash: (0, hash_1.sha256)(file.content),
                 mtimeMs: stat.mtimeMs,
                 size: stat.size,
                 order: order++,
-                primary: /agents\.md$/i.test(file),
+                primary: /(^|[/\\])agents\.md$/i.test(relativePath),
             };
         }));
     }
@@ -221,6 +227,11 @@ async function loadUnifiedConfig(options) {
                         file: tomlFile,
                     });
                 }
+                if (hasCommand && hasUrl) {
+                    delete server.command;
+                    delete server.args;
+                    delete server.env;
+                }
                 // Derive type - remote takes precedence if both are present
                 if (server.url) {
                     server.type = 'remote';
@@ -282,13 +293,32 @@ async function loadUnifiedConfig(options) {
                 }
             }
             const parsedObj = parsed;
-            const serversRaw = parsedObj.mcpServers ||
-                parsedObj.servers ||
-                {};
-            if (serversRaw && typeof serversRaw === 'object') {
+            const serversRaw = 'mcpServers' in parsedObj
+                ? parsedObj.mcpServers
+                : 'servers' in parsedObj
+                    ? parsedObj.servers
+                    : undefined;
+            if (!serversRaw ||
+                typeof serversRaw !== 'object' ||
+                Array.isArray(serversRaw)) {
+                diagnostics.push({
+                    severity: 'warning',
+                    code: 'MCP_INVALID_SHAPE',
+                    message: 'mcp.json must contain a non-array object in "mcpServers" or "servers"',
+                    file: mcpFile,
+                });
+            }
+            else {
                 for (const [name, def] of Object.entries(serversRaw)) {
-                    if (!def || typeof def !== 'object')
+                    if (!def || typeof def !== 'object' || Array.isArray(def)) {
+                        diagnostics.push({
+                            severity: 'warning',
+                            code: 'MCP_INVALID_SERVER',
+                            message: `MCP server '${name}' must be an object`,
+                            file: mcpFile,
+                        });
                         continue;
+                    }
                     const server = {};
                     if (typeof def.command === 'string')
                         server.command = def.command;

package/dist/core/UnifiedConfigTypes.d.ts

@@ -0,0 +1,95 @@
+import { McpConfig, GitignoreConfig, SkillsConfig, SubagentsConfig, McpStrategy } from '../types';
+export interface RulerUnifiedConfig {
+    meta: ConfigMeta;
+    toml: TomlConfig;
+    rules: RulesBundle;
+    mcp: McpBundle | null;
+    agents: Record<string, EffectiveAgentConfig>;
+    diagnostics: ConfigDiagnostic[];
+    hash: string;
+}
+export interface ConfigMeta {
+    projectRoot: string;
+    rulerDir: string;
+    configFile?: string;
+    mcpFile?: string;
+    loadedAt: Date;
+    version: string;
+}
+export interface TomlConfig {
+    raw: unknown;
+    schemaVersion: number;
+    defaultAgents?: string[];
+    agents: Record<string, AgentTomlConfig>;
+    mcp?: McpToggleConfig;
+    mcpServers?: Record<string, McpServerDef>;
+    gitignore?: GitignoreConfig;
+    skills?: SkillsConfig;
+    subagents?: SubagentsConfig;
+    nested?: boolean;
+}
+export type McpToggleConfig = McpConfig;
+export interface AgentTomlConfig {
+    enabled?: boolean;
+    outputPath?: string;
+    outputPathInstructions?: string;
+    outputPathConfig?: string;
+    mcp?: McpConfig;
+    source: AgentConfigSourceMeta;
+}
+export interface AgentConfigSourceMeta {
+    sectionPath: string;
+}
+export interface RulesBundle {
+    files: RuleFile[];
+    concatenated: string;
+    concatenatedHash: string;
+}
+export interface RuleFile {
+    path: string;
+    relativePath: string;
+    content: string;
+    contentHash: string;
+    mtimeMs: number;
+    size: number;
+    order: number;
+    primary: boolean;
+}
+export interface McpBundle {
+    servers: Record<string, McpServerDef>;
+    raw: Record<string, unknown>;
+    hash: string;
+}
+export interface McpServerDef {
+    type?: 'stdio' | 'local' | 'remote';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+export interface EffectiveAgentConfig {
+    identifier: string;
+    enabled: boolean;
+    output: AgentOutputPaths;
+    mcp: EffectiveMcpConfig;
+    toml?: AgentTomlConfig;
+}
+export interface AgentOutputPaths {
+    instructions?: string;
+    config?: string;
+    generic?: string;
+}
+export interface EffectiveMcpConfig {
+    enabled: boolean;
+    strategy: McpStrategy;
+}
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+export interface ConfigDiagnostic {
+    severity: DiagnosticSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    detail?: string;
+}

package/dist/core/agent-selection.d.ts

@@ -0,0 +1,12 @@
+import { IAgent } from '../agents/IAgent';
+import { LoadedConfig } from './ConfigLoader';
+export declare function agentMatchesFilter(agent: IAgent, filter: string, validAgentIdentifiers: Set<string>): boolean;
+/**
+ * Resolves which agents should be selected based on configuration.
+ * Handles precedence: CLI agents > default_agents > per-agent enabled flags > all agents
+ *
+ * @param config Loaded configuration containing CLI agents, default agents, and per-agent configs
+ * @param allAgents Array of all available agents
+ * @returns Array of agents that should be processed
+ */
+export declare function resolveSelectedAgents(config: LoadedConfig, allAgents: IAgent[]): IAgent[];

package/dist/core/agent-selection.js

@@ -1,7 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentMatchesFilter = agentMatchesFilter;
 exports.resolveSelectedAgents = resolveSelectedAgents;
 const constants_1 = require("../constants");
+function agentMatchesFilter(agent, filter, validAgentIdentifiers) {
+    const identifier = agent.getIdentifier().toLowerCase();
+    // Exact identifier matches take precedence over fuzzy display-name matching.
+    if (validAgentIdentifiers.has(filter)) {
+        return identifier === filter;
+    }
+    return agent.getName().toLowerCase().includes(filter);
+}
 /**
  * Resolves which agents should be selected based on configuration.
  * Handles precedence: CLI agents > default_agents > per-agent enabled flags > all agents
@@ -23,8 +32,7 @@ function resolveSelectedAgents(config, allAgents) {
         if (invalidAgents.length > 0) {
             throw (0, constants_1.createRulerError)(`Invalid agent specified: ${invalidAgents.join(', ')}`, `Valid agents are: ${[...validAgentIdentifiers].join(', ')}`);
         }
-        selected = allAgents.filter((agent) => filters.some((f) => agent.getIdentifier() === f ||
-            agent.getName().toLowerCase().includes(f)));
+        selected = allAgents.filter((agent) => filters.some((f) => agentMatchesFilter(agent, f, validAgentIdentifiers)));
     }
     else if (config.defaultAgents && config.defaultAgents.length > 0) {
         const defaults = config.defaultAgents.map((n) => n.toLowerCase());
@@ -42,7 +50,7 @@ function resolveSelectedAgents(config, allAgents) {
             if (override !== undefined) {
                 return override;
             }
-            return defaults.some((d) => identifier === d || agent.getName().toLowerCase().includes(d));
+            return defaults.some((d) => agentMatchesFilter(agent, d, validAgentIdentifiers));
         });
     }
     else {

package/dist/core/apply-engine.d.ts

@@ -0,0 +1,69 @@
+import { LoadedConfig } from './ConfigLoader';
+import { IAgent } from '../agents/IAgent';
+import { McpStrategy } from '../types';
+/**
+ * Configuration data loaded from the ruler setup
+ */
+export interface RulerConfiguration {
+    config: LoadedConfig;
+    concatenatedRules: string;
+    rulerMcpJson: Record<string, unknown> | null;
+}
+/**
+ * Configuration data for a specific .ruler directory in hierarchical mode
+ */
+export interface HierarchicalRulerConfiguration extends RulerConfiguration {
+    rulerDir: string;
+}
+export declare function loadNestedConfigurations(projectRoot: string, configPath: string | undefined, localOnly: boolean, resolvedNested: boolean): Promise<HierarchicalRulerConfiguration[]>;
+/**
+ * Loads configuration for single-directory mode (existing behavior).
+ */
+export declare function loadSingleConfiguration(projectRoot: string, configPath: string | undefined, localOnly: boolean): Promise<RulerConfiguration>;
+/**
+ * Processes hierarchical configurations by applying rules to each .ruler directory independently.
+ * Each directory gets its own set of rules and generates its own agent files.
+ * @param agents Array of agents to process
+ * @param configurations Array of hierarchical configurations for each .ruler directory
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @param cliMcpEnabled Whether MCP is enabled via CLI
+ * @param cliMcpStrategy MCP strategy from CLI
+ * @returns Promise resolving to array of generated file paths
+ */
+export declare function processHierarchicalConfigurations(agents: IAgent[], configurations: HierarchicalRulerConfiguration[], verbose: boolean, dryRun: boolean, cliMcpEnabled: boolean, cliMcpStrategy?: McpStrategy, backup?: boolean): Promise<string[]>;
+/**
+ * Processes a single configuration by applying rules to all selected agents.
+ * All rules are concatenated and applied to generate agent files in the project root.
+ * @param agents Array of agents to process
+ * @param configuration Single ruler configuration with concatenated rules
+ * @param projectRoot Root directory of the project
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @param cliMcpEnabled Whether MCP is enabled via CLI
+ * @param cliMcpStrategy MCP strategy from CLI
+ * @returns Promise resolving to array of generated file paths
+ */
+export declare function processSingleConfiguration(agents: IAgent[], configuration: RulerConfiguration, projectRoot: string, verbose: boolean, dryRun: boolean, cliMcpEnabled: boolean, cliMcpStrategy?: McpStrategy, backup?: boolean): Promise<string[]>;
+/**
+ * Applies configurations to the selected agents (internal function).
+ * @param agents Array of agents to process
+ * @param concatenatedRules Concatenated rule content
+ * @param rulerMcpJson MCP configuration JSON
+ * @param config Loaded configuration
+ * @param projectRoot Root directory of the project
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @returns Promise resolving to array of generated file paths
+ */
+export declare function applyConfigurationsToAgents(agents: IAgent[], concatenatedRules: string, rulerMcpJson: Record<string, unknown> | null, config: LoadedConfig, projectRoot: string, verbose: boolean, dryRun: boolean, cliMcpEnabled?: boolean, cliMcpStrategy?: McpStrategy, backup?: boolean): Promise<string[]>;
+/**
+ * Updates the .gitignore file with generated paths.
+ * @param projectRoot Root directory of the project
+ * @param generatedPaths Array of generated file paths
+ * @param config Loaded configuration
+ * @param cliGitignoreEnabled CLI gitignore setting
+ * @param dryRun Whether to perform a dry run
+ * @param cliGitignoreLocal CLI toggle for .git/info/exclude usage
+ */
+export declare function updateGitignore(projectRoot: string, generatedPaths: string[], config: LoadedConfig, cliGitignoreEnabled: boolean | undefined, dryRun: boolean, cliGitignoreLocal?: boolean): Promise<void>;

package/dist/core/apply-engine.js

@@ -52,6 +52,7 @@ const propagateOpenHandsMcp_1 = require("../mcp/propagateOpenHandsMcp");
 const propagateOpenCodeMcp_1 = require("../mcp/propagateOpenCodeMcp");
 const agent_utils_1 = require("../agents/agent-utils");
 const capabilities_1 = require("../mcp/capabilities");
+const path_utils_1 = require("./path-utils");
 const constants_1 = require("../constants");
 async function loadNestedConfigurations(projectRoot, configPath, localOnly, resolvedNested) {
     const { dirs: rulerDirs } = await findRulerDirectories(projectRoot, localOnly, true);
@@ -59,11 +60,11 @@ async function loadNestedConfigurations(projectRoot, configPath, localOnly, reso
     // Load config first so we know whether `.ruler/agents/` should be included
     // in the rule concatenation for each directory.
     for (const rulerDir of rulerDirs) {
-        const config = await loadConfigForRulerDir(rulerDir, configPath, resolvedNested);
+        const config = await loadConfigForRulerDir(rulerDir, configPath, resolvedNested, localOnly);
         const files = await FileSystemUtils.readMarkdownFiles(rulerDir, {
             includeAgents: shouldIncludeAgentsInRules(config),
         });
-        results.push(await createHierarchicalConfiguration(rulerDir, files, config, configPath));
+        results.push(await createHierarchicalConfiguration(rulerDir, files, config, configPath, localOnly));
     }
     return results;
 }
@@ -74,7 +75,7 @@ async function loadNestedConfigurations(projectRoot, configPath, localOnly, reso
 function shouldIncludeAgentsInRules(config) {
     return config.subagents?.include_in_rules === true;
 }
-async function createHierarchicalConfiguration(rulerDir, files, config, cliConfigPath) {
+async function createHierarchicalConfiguration(rulerDir, files, config, cliConfigPath, localOnly) {
     await warnAboutLegacyMcpJson(rulerDir);
     const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(rulerDir));
     const directoryRoot = path.dirname(rulerDir);
@@ -91,6 +92,7 @@ async function createHierarchicalConfiguration(rulerDir, files, config, cliConfi
     const unifiedConfig = await loadUnifiedConfig({
         projectRoot: directoryRoot,
         configPath: configPathToUse,
+        checkGlobal: !localOnly,
     });
     let rulerMcpJson = null;
     if (unifiedConfig.mcp && Object.keys(unifiedConfig.mcp.servers).length > 0) {
@@ -105,7 +107,7 @@ async function createHierarchicalConfiguration(rulerDir, files, config, cliConfi
         rulerMcpJson,
     };
 }
-async function loadConfigForRulerDir(rulerDir, cliConfigPath, resolvedNested) {
+async function loadConfigForRulerDir(rulerDir, cliConfigPath, resolvedNested, localOnly) {
     const directoryRoot = path.dirname(rulerDir);
     const localConfigPath = path.join(rulerDir, 'ruler.toml');
     let hasLocalConfig = false;
@@ -119,6 +121,7 @@ async function loadConfigForRulerDir(rulerDir, cliConfigPath, resolvedNested) {
     const loaded = await (0, ConfigLoader_1.loadConfig)({
         projectRoot: directoryRoot,
         configPath: hasLocalConfig ? localConfigPath : cliConfigPath,
+        checkGlobal: !localOnly,
     });
     const cloned = cloneLoadedConfig(loaded);
     if (resolvedNested) {
@@ -144,6 +147,7 @@ function cloneLoadedConfig(config) {
         cliAgents: config.cliAgents ? [...config.cliAgents] : undefined,
         mcp: config.mcp ? { ...config.mcp } : undefined,
         gitignore: config.gitignore ? { ...config.gitignore } : undefined,
+        backup: config.backup ? { ...config.backup } : undefined,
         skills: config.skills ? { ...config.skills } : undefined,
         subagents: config.subagents ? { ...config.subagents } : undefined,
         nested: config.nested,
@@ -156,18 +160,10 @@ function cloneLoadedConfig(config) {
 async function findRulerDirectories(projectRoot, localOnly, hierarchical) {
     if (hierarchical) {
         const dirs = await FileSystemUtils.findAllRulerDirs(projectRoot);
-        const allDirs = [...dirs];
-        // Add global config if not local-only
-        if (!localOnly) {
-            const globalDir = await FileSystemUtils.findGlobalRulerDir();
-            if (globalDir) {
-                allDirs.push(globalDir);
-            }
-        }
-        if (allDirs.length === 0) {
+        if (dirs.length === 0) {
             throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
         }
-        return { dirs: allDirs, primaryDir: allDirs[0] };
+        return { dirs, primaryDir: dirs[0] };
     }
     else {
         const dir = await FileSystemUtils.findRulerDir(projectRoot, !localOnly);
@@ -202,6 +198,7 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
     const config = await (0, ConfigLoader_1.loadConfig)({
         projectRoot,
         configPath,
+        checkGlobal: !localOnly,
     });
     // Read rule files. `.ruler/agents/` is only included when
     // `[agents] include_in_rules = true`.
@@ -212,7 +209,11 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
     const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(primaryDir));
     // Load unified config to get merged MCP configuration
     const { loadUnifiedConfig } = await Promise.resolve().then(() => __importStar(require('./UnifiedConfigLoader')));
-    const unifiedConfig = await loadUnifiedConfig({ projectRoot, configPath });
+    const unifiedConfig = await loadUnifiedConfig({
+        projectRoot,
+        configPath,
+        checkGlobal: !localOnly,
+    });
     // Synthesize rulerMcpJson from unified MCP bundle for backward compatibility
     let rulerMcpJson = null;
     if (unifiedConfig.mcp && Object.keys(unifiedConfig.mcp.servers).length > 0) {
@@ -306,22 +307,27 @@ async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJs
                     agentsMdWritten = true;
                 }
             }
-            let finalAgentConfig = agentConfig;
-            if (agent.getIdentifier() === 'augmentcode' && agentRulerMcpJson) {
-                const resolvedStrategy = cliMcpStrategy ??
-                    agentConfig?.mcp?.strategy ??
-                    config.mcp?.strategy ??
-                    'merge';
-                finalAgentConfig = {
-                    ...agentConfig,
-                    mcp: {
-                        ...agentConfig?.mcp,
-                        strategy: resolvedStrategy,
-                    },
-                };
-            }
+            const effectiveMcpEnabled = cliMcpEnabled &&
+                (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
+            const effectiveMcpStrategy = cliMcpStrategy ??
+                agentConfig?.mcp?.strategy ??
+                config.mcp?.strategy ??
+                'merge';
+            const finalAgentConfig = {
+                ...agentConfig,
+                mcp: {
+                    ...agentConfig?.mcp,
+                    enabled: effectiveMcpEnabled,
+                    strategy: effectiveMcpStrategy,
+                },
+            };
+            const mcpForAgentApply = shouldUseEngineManagedMcp(agent)
+                ? null
+                : effectiveMcpEnabled
+                    ? agentRulerMcpJson
+                    : null;
             if (!skipApplyForThisAgent) {
-                await agent.applyRulerConfig(concatenatedRules, projectRoot, agentRulerMcpJson, finalAgentConfig, backup);
+                await agent.applyRulerConfig(concatenatedRules, projectRoot, mcpForAgentApply, finalAgentConfig, backup);
             }
         }
         // Handle MCP configuration
@@ -334,7 +340,7 @@ async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson,
         (0, constants_1.logVerbose)(`Agent ${agent.getName()} does not support MCP - skipping MCP configuration`, verbose);
         return;
     }
-    const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+    const dest = await resolveMcpDestination(agent, agentConfig, projectRoot);
     const mcpEnabledForAgent = cliMcpEnabled && (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
     if (!dest || !mcpEnabledForAgent) {
         return;
@@ -349,8 +355,17 @@ async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson,
     await updateGitignoreForMcpFile(dest, projectRoot, generatedPaths, backup);
     await applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, projectRoot, cliMcpStrategy, dryRun, verbose, backup);
 }
+function shouldUseEngineManagedMcp(agent) {
+    return (agent.getIdentifier() === 'codex' || agent.getIdentifier() === 'opencode');
+}
+async function resolveMcpDestination(agent, agentConfig, projectRoot) {
+    if (agentConfig?.outputPathConfig) {
+        return path.resolve(projectRoot, agentConfig.outputPathConfig);
+    }
+    return await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+}
 async function updateGitignoreForMcpFile(dest, projectRoot, generatedPaths, backup = true) {
-    if (dest.startsWith(projectRoot)) {
+    if ((0, path_utils_1.isPathInsideOrEqual)(projectRoot, dest)) {
         const relativeDest = path.relative(projectRoot, dest);
         generatedPaths.push(relativeDest);
         if (backup) {
@@ -391,16 +406,16 @@ function sanitizeMcpTimeoutsForAgent(agent, mcpJson, dryRun) {
 }
 async function applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, projectRoot, cliMcpStrategy, dryRun, verbose, backup = true) {
     // Prevent writing MCP configs outside the project root (e.g., legacy home-directory targets)
-    if (!dest.startsWith(projectRoot)) {
+    if (!(0, path_utils_1.isPathInsideOrEqual)(projectRoot, dest)) {
         (0, constants_1.logVerbose)(`Skipping MCP config for ${agent.getName()} because target path is outside project: ${dest}`, verbose);
         return;
     }
     const agentMcpJson = sanitizeMcpTimeoutsForAgent(agent, filteredMcpJson, dryRun);
     if (agent.getIdentifier() === 'openhands') {
-        return await applyOpenHandsMcpConfiguration(agentMcpJson, dest, dryRun, verbose, backup);
+        return await applyOpenHandsMcpConfiguration(agentMcpJson, dest, cliMcpStrategy ?? agentConfig?.mcp?.strategy ?? config.mcp?.strategy, dryRun, verbose, backup);
     }
     if (agent.getIdentifier() === 'opencode') {
-        return await applyOpenCodeMcpConfiguration(agentMcpJson, dest, dryRun, verbose, backup);
+        return await applyOpenCodeMcpConfiguration(agentMcpJson, dest, cliMcpStrategy ?? agentConfig?.mcp?.strategy ?? config.mcp?.strategy, dryRun, verbose, backup);
     }
     // Agents that handle MCP configuration internally should not have external MCP handling
     if (agent.getIdentifier() === 'zed' ||
@@ -412,20 +427,20 @@ async function applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig,
     }
     return await applyStandardMcpConfiguration(agent, agentMcpJson, dest, agentConfig, config, cliMcpStrategy, dryRun, verbose, backup);
 }
-async function applyOpenHandsMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
+async function applyOpenHandsMcpConfiguration(filteredMcpJson, dest, strategy, dryRun, verbose, backup = true) {
     if (dryRun) {
         (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating TOML file: ${dest}`, verbose);
     }
     else {
-        await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(filteredMcpJson, dest, backup);
+        await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(filteredMcpJson, dest, backup, strategy);
     }
 }
-async function applyOpenCodeMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
+async function applyOpenCodeMcpConfiguration(filteredMcpJson, dest, strategy, dryRun, verbose, backup = true) {
     if (dryRun) {
         (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating OpenCode config file: ${dest}`, verbose);
     }
     else {
-        await (0, propagateOpenCodeMcp_1.propagateMcpToOpenCode)(filteredMcpJson, dest, backup);
+        await (0, propagateOpenCodeMcp_1.propagateMcpToOpenCode)(filteredMcpJson, dest, backup, strategy);
     }
 }
 /**
@@ -550,17 +565,9 @@ async function applyStandardMcpConfiguration(agent, filteredMcpJson, dest, agent
         }
         const CODEX_AGENT_ID = 'codex';
         const isCodexToml = agent.getIdentifier() === CODEX_AGENT_ID && dest.endsWith('.toml');
-        let existing = await (0, mcp_1.readNativeMcp)(dest);
-        if (isCodexToml) {
-            try {
-                const tomlContent = await fs_1.promises.readFile(dest, 'utf8');
-                existing = (0, toml_1.parse)(tomlContent);
-            }
-            catch (error) {
-                (0, constants_1.logVerbose)(`Failed to read Codex MCP TOML at ${dest}: ${error.message}`, verbose);
-                // ignore missing or invalid TOML, fall back to previously read value
-            }
-        }
+        const existing = isCodexToml
+            ? await (0, mcp_1.readNativeMcpToml)(dest, (text) => (0, toml_1.parse)(text))
+            : await (0, mcp_1.readNativeMcp)(dest);
         let merged = (0, merge_1.mergeMcp)(existing, mcpToMerge, strategy, serverKey);
         if (isCodexToml) {
             const { [serverKey]: servers, ...rest } = merged;

package/dist/core/config-utils.d.ts

@@ -0,0 +1,14 @@
+import { IAgent, IAgentConfig } from '../agents/IAgent';
+/**
+ * Maps raw agent configuration keys to their corresponding agent identifiers.
+ *
+ * This function normalizes configuration keys by matching them against agent identifiers
+ * and display names. It performs both exact matching (case-insensitive) with agent
+ * identifiers and substring matching (case-insensitive) with agent display names
+ * for backwards compatibility.
+ *
+ * @param raw Raw agent configurations with user-provided keys
+ * @param agents Array of all available agents
+ * @returns Record with agent identifiers as keys and their configurations as values
+ */
+export declare function mapRawAgentConfigs(raw: Record<string, IAgentConfig>, agents: IAgent[]): Record<string, IAgentConfig>;

package/dist/core/config-utils.js

@@ -17,11 +17,17 @@ function mapRawAgentConfigs(raw, agents) {
     const mappedConfigs = {};
     for (const [key, cfg] of Object.entries(raw)) {
         const lowerKey = key.toLowerCase();
+        const exactMatches = agents.filter((agent) => agent.getIdentifier().toLowerCase() === lowerKey);
+        // Exact identifier matches take precedence over fuzzy display-name matching.
+        if (exactMatches.length > 0) {
+            for (const agent of exactMatches) {
+                mappedConfigs[agent.getIdentifier()] = cfg;
+            }
+            continue;
+        }
         for (const agent of agents) {
             const identifier = agent.getIdentifier();
-            // Exact match with identifier or substring match with display name for backwards compatibility
-            if (identifier === lowerKey ||
-                agent.getName().toLowerCase().includes(lowerKey)) {
+            if (agent.getName().toLowerCase().includes(lowerKey)) {
                 mappedConfigs[identifier] = cfg;
             }
         }

package/dist/core/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function sha256(data: string): string;
+export declare function stableJson(value: unknown): string;

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

@@ -0,0 +1 @@
+export declare function isPathInsideOrEqual(parentPath: string, targetPath: string): boolean;