thaddeus 1.0.26 → 1.0.28

package/src/tools/AgentTool/forkSubagent.js

@@ -0,0 +1,177 @@
+import { feature } from 'bun:bundle';
+import { randomUUID } from 'crypto';
+import { getIsNonInteractiveSession } from '../../bootstrap/state.js';
+import { FORK_BOILERPLATE_TAG, FORK_DIRECTIVE_PREFIX, } from '../../constants/xml.js';
+import { isCoordinatorMode } from '../../coordinator/coordinatorMode.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { createUserMessage } from '../../utils/messages.js';
+/**
+ * Fork subagent feature gate.
+ *
+ * When enabled:
+ * - `subagent_type` becomes optional on the Agent tool schema
+ * - Omitting `subagent_type` triggers an implicit fork: the child inherits
+ *   the parent's full conversation context and system prompt
+ * - All agent spawns run in the background (async) for a unified
+ *   `<task-notification>` interaction model
+ * - `/fork <directive>` slash command is available
+ *
+ * Mutually exclusive with coordinator mode — coordinator already owns the
+ * orchestration role and has its own delegation model.
+ */
+export function isForkSubagentEnabled() {
+    if (feature('FORK_SUBAGENT')) {
+        if (isCoordinatorMode())
+            return false;
+        if (getIsNonInteractiveSession())
+            return false;
+        return true;
+    }
+    return false;
+}
+/** Synthetic agent type name used for analytics when the fork path fires. */
+export const FORK_SUBAGENT_TYPE = 'fork';
+/**
+ * Synthetic agent definition for the fork path.
+ *
+ * Not registered in builtInAgents — used only when `!subagent_type` and the
+ * experiment is active. `tools: ['*']` with `useExactTools` means the fork
+ * child receives the parent's exact tool pool (for cache-identical API
+ * prefixes). `permissionMode: 'bubble'` surfaces permission prompts to the
+ * parent terminal. `model: 'inherit'` keeps the parent's model for context
+ * length parity.
+ *
+ * The getSystemPrompt here is unused: the fork path passes
+ * `override.systemPrompt` with the parent's already-rendered system prompt
+ * bytes, threaded via `toolUseContext.renderedSystemPrompt`. Reconstructing
+ * by re-calling getSystemPrompt() can diverge (GrowthBook cold→warm) and
+ * bust the prompt cache; threading the rendered bytes is byte-exact.
+ */
+export const FORK_AGENT = {
+    agentType: FORK_SUBAGENT_TYPE,
+    whenToUse: 'Implicit fork — inherits full conversation context. Not selectable via subagent_type; triggered by omitting subagent_type when the fork experiment is active.',
+    tools: ['*'],
+    maxTurns: 200,
+    model: 'inherit',
+    permissionMode: 'bubble',
+    source: 'built-in',
+    baseDir: 'built-in',
+    getSystemPrompt: () => '',
+};
+/**
+ * Guard against recursive forking. Fork children keep the Agent tool in their
+ * tool pool for cache-identical tool definitions, so we reject fork attempts
+ * at call time by detecting the fork boilerplate tag in conversation history.
+ */
+export function isInForkChild(messages) {
+    return messages.some(m => {
+        if (m.type !== 'user')
+            return false;
+        const content = m.message.content;
+        if (!Array.isArray(content))
+            return false;
+        return content.some(block => block.type === 'text' &&
+            block.text.includes(`<${FORK_BOILERPLATE_TAG}>`));
+    });
+}
+/** Placeholder text used for all tool_result blocks in the fork prefix.
+ * Must be identical across all fork children for prompt cache sharing. */
+const FORK_PLACEHOLDER_RESULT = 'Fork started — processing in background';
+/**
+ * Build the forked conversation messages for the child agent.
+ *
+ * For prompt cache sharing, all fork children must produce byte-identical
+ * API request prefixes. This function:
+ * 1. Keeps the full parent assistant message (all tool_use blocks, thinking, text)
+ * 2. Builds a single user message with tool_results for every tool_use block
+ *    using an identical placeholder, then appends a per-child directive text block
+ *
+ * Result: [...history, assistant(all_tool_uses), user(placeholder_results..., directive)]
+ * Only the final text block differs per child, maximizing cache hits.
+ */
+export function buildForkedMessages(directive, assistantMessage) {
+    // Clone the assistant message to avoid mutating the original, keeping all
+    // content blocks (thinking, text, and every tool_use)
+    const fullAssistantMessage = {
+        ...assistantMessage,
+        uuid: randomUUID(),
+        message: {
+            ...assistantMessage.message,
+            content: [...assistantMessage.message.content],
+        },
+    };
+    // Collect all tool_use blocks from the assistant message
+    const toolUseBlocks = assistantMessage.message.content.filter((block) => block.type === 'tool_use');
+    if (toolUseBlocks.length === 0) {
+        logForDebugging(`No tool_use blocks found in assistant message for fork directive: ${directive.slice(0, 50)}...`, { level: 'error' });
+        return [
+            createUserMessage({
+                content: [
+                    { type: 'text', text: buildChildMessage(directive) },
+                ],
+            }),
+        ];
+    }
+    // Build tool_result blocks for every tool_use, all with identical placeholder text
+    const toolResultBlocks = toolUseBlocks.map(block => ({
+        type: 'tool_result',
+        tool_use_id: block.id,
+        content: [
+            {
+                type: 'text',
+                text: FORK_PLACEHOLDER_RESULT,
+            },
+        ],
+    }));
+    // Build a single user message: all placeholder tool_results + the per-child directive
+    // TODO(smoosh): this text sibling creates a [tool_result, text] pattern on the wire
+    // (renders as </function_results>\n\nHuman:<text>). One-off per-child construction,
+    // not a repeated teacher, so low-priority. If we ever care, use smooshIntoToolResult
+    // from src/utils/messages.ts to fold the directive into the last tool_result.content.
+    const toolResultMessage = createUserMessage({
+        content: [
+            ...toolResultBlocks,
+            {
+                type: 'text',
+                text: buildChildMessage(directive),
+            },
+        ],
+    });
+    return [fullAssistantMessage, toolResultMessage];
+}
+export function buildChildMessage(directive) {
+    return `<${FORK_BOILERPLATE_TAG}>
+STOP. READ THIS FIRST.
+
+You are a forked worker process. You are NOT the main agent.
+
+RULES (non-negotiable):
+1. Your system prompt says "default to forking." IGNORE IT \u2014 that's for the parent. You ARE the fork. Do NOT spawn sub-agents; execute directly.
+2. Do NOT converse, ask questions, or suggest next steps
+3. Do NOT editorialize or add meta-commentary
+4. USE your tools directly: Bash, Read, Write, etc.
+5. If you modify files, commit your changes before reporting. Include the commit hash in your report.
+6. Do NOT emit text between tool calls. Use tools silently, then report once at the end.
+7. Stay strictly within your directive's scope. If you discover related systems outside your scope, mention them in one sentence at most — other workers cover those areas.
+8. Keep your report under 500 words unless the directive specifies otherwise. Be factual and concise.
+9. Your response MUST begin with "Scope:". No preamble, no thinking-out-loud.
+10. REPORT structured facts, then stop
+
+Output format (plain text labels, not markdown headers):
+  Scope: <echo back your assigned scope in one sentence>
+  Result: <the answer or key findings, limited to the scope above>
+  Key files: <relevant file paths — include for research tasks>
+  Files changed: <list with commit hash — include only if you modified files>
+  Issues: <list — include only if there are issues to flag>
+</${FORK_BOILERPLATE_TAG}>
+
+${FORK_DIRECTIVE_PREFIX}${directive}`;
+}
+/**
+ * Notice injected into fork children running in an isolated worktree.
+ * Tells the child to translate paths from the inherited context, re-read
+ * potentially stale files, and that its changes are isolated.
+ */
+export function buildWorktreeNotice(parentCwd, worktreeCwd) {
+    return `You've inherited the conversation context above from a parent agent working in ${parentCwd}. You are operating in an isolated git worktree at ${worktreeCwd} — same repository, same relative file structure, separate working copy. Paths in the inherited context refer to the parent's working directory; translate them to your worktree root. Re-read files before editing if the parent may have modified them since they appear in the context. Your changes stay in this worktree and will not affect the parent's files.`;
+}

package/src/tools/AgentTool/loadAgentsDir.js

@@ -0,0 +1,497 @@
+import { feature } from 'bun:bundle';
+import memoize from 'lodash-es/memoize.js';
+import { basename } from 'path';
+import { z } from 'zod/v4';
+import { isAutoMemoryEnabled } from '../../memdir/paths.js';
+import { logEvent, } from '../../services/analytics/index.js';
+import { McpServerConfigSchema, } from '../../services/mcp/types.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { EFFORT_LEVELS, parseEffortValue, } from '../../utils/effort.js';
+import { isEnvTruthy } from '../../utils/envUtils.js';
+import { parsePositiveIntFromFrontmatter } from '../../utils/frontmatterParser.js';
+import { lazySchema } from '../../utils/lazySchema.js';
+import { logError } from '../../utils/log.js';
+import { loadMarkdownFilesForSubdir, parseAgentToolsFromFrontmatter, parseSlashCommandToolsFromFrontmatter, } from '../../utils/markdownConfigLoader.js';
+import { PERMISSION_MODES, } from '../../utils/permissions/PermissionMode.js';
+import { clearPluginAgentCache, loadPluginAgents, } from '../../utils/plugins/loadPluginAgents.js';
+import { HooksSchema } from '../../utils/settings/types.js';
+import { jsonStringify } from '../../utils/slowOperations.js';
+import { FILE_EDIT_TOOL_NAME } from '../FileEditTool/constants.js';
+import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js';
+import { FILE_WRITE_TOOL_NAME } from '../FileWriteTool/prompt.js';
+import { AGENT_COLORS, setAgentColor, } from './agentColorManager.js';
+import { loadAgentMemoryPrompt } from './agentMemory.js';
+import { checkAgentMemorySnapshot, initializeFromSnapshot, } from './agentMemorySnapshot.js';
+import { getBuiltInAgents } from './builtInAgents.js';
+// Zod schema for agent MCP server specs
+const AgentMcpServerSpecSchema = lazySchema(() => z.union([
+    z.string(), // Reference by name
+    z.record(z.string(), McpServerConfigSchema()), // Inline as { name: config }
+]));
+// Zod schemas for JSON agent validation
+// Note: HooksSchema is lazy so the circular chain AppState -> loadAgentsDir -> settings/types
+// is broken at module load time
+const AgentJsonSchema = lazySchema(() => z.object({
+    description: z.string().min(1, 'Description cannot be empty'),
+    tools: z.array(z.string()).optional(),
+    disallowedTools: z.array(z.string()).optional(),
+    prompt: z.string().min(1, 'Prompt cannot be empty'),
+    model: z
+        .string()
+        .trim()
+        .min(1, 'Model cannot be empty')
+        .transform(m => (m.toLowerCase() === 'inherit' ? 'inherit' : m))
+        .optional(),
+    effort: z.union([z.enum(EFFORT_LEVELS), z.number().int()]).optional(),
+    permissionMode: z.enum(PERMISSION_MODES).optional(),
+    mcpServers: z.array(AgentMcpServerSpecSchema()).optional(),
+    hooks: HooksSchema().optional(),
+    maxTurns: z.number().int().positive().optional(),
+    skills: z.array(z.string()).optional(),
+    initialPrompt: z.string().optional(),
+    memory: z.enum(['user', 'project', 'local']).optional(),
+    background: z.boolean().optional(),
+    isolation: (process.env.USER_TYPE === 'ant'
+        ? z.enum(['worktree', 'remote'])
+        : z.enum(['worktree'])).optional(),
+}));
+const AgentsJsonSchema = lazySchema(() => z.record(z.string(), AgentJsonSchema()));
+// Type guards for runtime type checking
+export function isBuiltInAgent(agent) {
+    return agent.source === 'built-in';
+}
+export function isCustomAgent(agent) {
+    return agent.source !== 'built-in' && agent.source !== 'plugin';
+}
+export function isPluginAgent(agent) {
+    return agent.source === 'plugin';
+}
+export function getActiveAgentsFromList(allAgents) {
+    const builtInAgents = allAgents.filter(a => a.source === 'built-in');
+    const pluginAgents = allAgents.filter(a => a.source === 'plugin');
+    const userAgents = allAgents.filter(a => a.source === 'userSettings');
+    const projectAgents = allAgents.filter(a => a.source === 'projectSettings');
+    const managedAgents = allAgents.filter(a => a.source === 'policySettings');
+    const flagAgents = allAgents.filter(a => a.source === 'flagSettings');
+    const agentGroups = [
+        builtInAgents,
+        pluginAgents,
+        userAgents,
+        projectAgents,
+        flagAgents,
+        managedAgents,
+    ];
+    const agentMap = new Map();
+    for (const agents of agentGroups) {
+        for (const agent of agents) {
+            agentMap.set(agent.agentType, agent);
+        }
+    }
+    return Array.from(agentMap.values());
+}
+/**
+ * Checks if an agent's required MCP servers are available.
+ * Returns true if no requirements or all requirements are met.
+ * @param agent The agent to check
+ * @param availableServers List of available MCP server names (e.g., from mcp.clients)
+ */
+export function hasRequiredMcpServers(agent, availableServers) {
+    if (!agent.requiredMcpServers || agent.requiredMcpServers.length === 0) {
+        return true;
+    }
+    // Each required pattern must match at least one available server (case-insensitive)
+    return agent.requiredMcpServers.every(pattern => availableServers.some(server => server.toLowerCase().includes(pattern.toLowerCase())));
+}
+/**
+ * Filters agents based on MCP server requirements.
+ * Only returns agents whose required MCP servers are available.
+ * @param agents List of agents to filter
+ * @param availableServers List of available MCP server names
+ */
+export function filterAgentsByMcpRequirements(agents, availableServers) {
+    return agents.filter(agent => hasRequiredMcpServers(agent, availableServers));
+}
+/**
+ * Check for and initialize agent memory from project snapshots.
+ * For agents with memory enabled, copies snapshot to local if no local memory exists.
+ * For agents with newer snapshots, logs a debug message (user prompt TODO).
+ */
+async function initializeAgentMemorySnapshots(agents) {
+    await Promise.all(agents.map(async (agent) => {
+        if (agent.memory !== 'user')
+            return;
+        const result = await checkAgentMemorySnapshot(agent.agentType, agent.memory);
+        switch (result.action) {
+            case 'initialize':
+                logForDebugging(`Initializing ${agent.agentType} memory from project snapshot`);
+                await initializeFromSnapshot(agent.agentType, agent.memory, result.snapshotTimestamp);
+                break;
+            case 'prompt-update':
+                agent.pendingSnapshotUpdate = {
+                    snapshotTimestamp: result.snapshotTimestamp,
+                };
+                logForDebugging(`Newer snapshot available for ${agent.agentType} memory (snapshot: ${result.snapshotTimestamp})`);
+                break;
+        }
+    }));
+}
+export const getAgentDefinitionsWithOverrides = memoize(async (cwd) => {
+    // Simple mode: skip custom agents, only return built-ins
+    if (isEnvTruthy(process.env.THADDEUS_SIMPLE)) {
+        const builtInAgents = getBuiltInAgents();
+        return {
+            activeAgents: builtInAgents,
+            allAgents: builtInAgents,
+        };
+    }
+    try {
+        const markdownFiles = await loadMarkdownFilesForSubdir('agents', cwd);
+        const failedFiles = [];
+        const customAgents = markdownFiles
+            .map(({ filePath, baseDir, frontmatter, content, source }) => {
+            const agent = parseAgentFromMarkdown(filePath, baseDir, frontmatter, content, source);
+            if (!agent) {
+                // Skip non-agent markdown files silently (e.g., reference docs
+                // co-located with agent definitions). Only report errors for files
+                // that look like agent attempts (have a 'name' field in frontmatter).
+                if (!frontmatter['name']) {
+                    return null;
+                }
+                const errorMsg = getParseError(frontmatter);
+                failedFiles.push({ path: filePath, error: errorMsg });
+                logForDebugging(`Failed to parse agent from ${filePath}: ${errorMsg}`);
+                logEvent('thaddeus_agent_parse_error', {
+                    error: errorMsg,
+                    location: source,
+                });
+                return null;
+            }
+            return agent;
+        })
+            .filter(agent => agent !== null);
+        // Kick off plugin agent loading concurrently with memory snapshot init —
+        // loadPluginAgents is memoized and takes no args, so it's independent.
+        // Join both so neither becomes a floating promise if the other throws.
+        let pluginAgentsPromise = loadPluginAgents();
+        if (feature('AGENT_MEMORY_SNAPSHOT') && isAutoMemoryEnabled()) {
+            const [pluginAgents_] = await Promise.all([
+                pluginAgentsPromise,
+                initializeAgentMemorySnapshots(customAgents),
+            ]);
+            pluginAgentsPromise = Promise.resolve(pluginAgents_);
+        }
+        const pluginAgents = await pluginAgentsPromise;
+        const builtInAgents = getBuiltInAgents();
+        const allAgentsList = [
+            ...builtInAgents,
+            ...pluginAgents,
+            ...customAgents,
+        ];
+        const activeAgents = getActiveAgentsFromList(allAgentsList);
+        // Initialize colors for all active agents
+        for (const agent of activeAgents) {
+            if (agent.color) {
+                setAgentColor(agent.agentType, agent.color);
+            }
+        }
+        return {
+            activeAgents,
+            allAgents: allAgentsList,
+            failedFiles: failedFiles.length > 0 ? failedFiles : undefined,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logForDebugging(`Error loading agent definitions: ${errorMessage}`);
+        logError(error);
+        // Even on error, return the built-in agents
+        const builtInAgents = getBuiltInAgents();
+        return {
+            activeAgents: builtInAgents,
+            allAgents: builtInAgents,
+            failedFiles: [{ path: 'unknown', error: errorMessage }],
+        };
+    }
+});
+export function clearAgentDefinitionsCache() {
+    getAgentDefinitionsWithOverrides.cache.clear?.();
+    clearPluginAgentCache();
+}
+/**
+ * Helper to determine the specific parsing error for an agent file
+ */
+function getParseError(frontmatter) {
+    const agentType = frontmatter['name'];
+    const description = frontmatter['description'];
+    if (!agentType || typeof agentType !== 'string') {
+        return 'Missing required "name" field in frontmatter';
+    }
+    if (!description || typeof description !== 'string') {
+        return 'Missing required "description" field in frontmatter';
+    }
+    return 'Unknown parsing error';
+}
+/**
+ * Parse hooks from frontmatter using the HooksSchema
+ * @param frontmatter The frontmatter object containing potential hooks
+ * @param agentType The agent type for logging purposes
+ * @returns Parsed hooks settings or undefined if invalid/missing
+ */
+function parseHooksFromFrontmatter(frontmatter, agentType) {
+    if (!frontmatter.hooks) {
+        return undefined;
+    }
+    const result = HooksSchema().safeParse(frontmatter.hooks);
+    if (!result.success) {
+        logForDebugging(`Invalid hooks in agent '${agentType}': ${result.error.message}`);
+        return undefined;
+    }
+    return result.data;
+}
+/**
+ * Parses agent definition from JSON data
+ */
+export function parseAgentFromJson(name, definition, source = 'flagSettings') {
+    try {
+        const parsed = AgentJsonSchema().parse(definition);
+        let tools = parseAgentToolsFromFrontmatter(parsed.tools);
+        // If memory is enabled, inject Write/Edit/Read tools for memory access
+        if (isAutoMemoryEnabled() && parsed.memory && tools !== undefined) {
+            const toolSet = new Set(tools);
+            for (const tool of [
+                FILE_WRITE_TOOL_NAME,
+                FILE_EDIT_TOOL_NAME,
+                FILE_READ_TOOL_NAME,
+            ]) {
+                if (!toolSet.has(tool)) {
+                    tools = [...tools, tool];
+                }
+            }
+        }
+        const disallowedTools = parsed.disallowedTools !== undefined
+            ? parseAgentToolsFromFrontmatter(parsed.disallowedTools)
+            : undefined;
+        const systemPrompt = parsed.prompt;
+        const agent = {
+            agentType: name,
+            whenToUse: parsed.description,
+            ...(tools !== undefined ? { tools } : {}),
+            ...(disallowedTools !== undefined ? { disallowedTools } : {}),
+            getSystemPrompt: () => {
+                if (isAutoMemoryEnabled() && parsed.memory) {
+                    return (systemPrompt + '\n\n' + loadAgentMemoryPrompt(name, parsed.memory));
+                }
+                return systemPrompt;
+            },
+            source,
+            ...(parsed.model ? { model: parsed.model } : {}),
+            ...(parsed.effort !== undefined ? { effort: parsed.effort } : {}),
+            ...(parsed.permissionMode
+                ? { permissionMode: parsed.permissionMode }
+                : {}),
+            ...(parsed.mcpServers && parsed.mcpServers.length > 0
+                ? { mcpServers: parsed.mcpServers }
+                : {}),
+            ...(parsed.hooks ? { hooks: parsed.hooks } : {}),
+            ...(parsed.maxTurns !== undefined ? { maxTurns: parsed.maxTurns } : {}),
+            ...(parsed.skills && parsed.skills.length > 0
+                ? { skills: parsed.skills }
+                : {}),
+            ...(parsed.initialPrompt ? { initialPrompt: parsed.initialPrompt } : {}),
+            ...(parsed.background ? { background: parsed.background } : {}),
+            ...(parsed.memory ? { memory: parsed.memory } : {}),
+            ...(parsed.isolation ? { isolation: parsed.isolation } : {}),
+        };
+        return agent;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logForDebugging(`Error parsing agent '${name}' from JSON: ${errorMessage}`);
+        logError(error);
+        return null;
+    }
+}
+/**
+ * Parses multiple agents from a JSON object
+ */
+export function parseAgentsFromJson(agentsJson, source = 'flagSettings') {
+    try {
+        const parsed = AgentsJsonSchema().parse(agentsJson);
+        return Object.entries(parsed)
+            .map(([name, def]) => parseAgentFromJson(name, def, source))
+            .filter((agent) => agent !== null);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logForDebugging(`Error parsing agents from JSON: ${errorMessage}`);
+        logError(error);
+        return [];
+    }
+}
+/**
+ * Parses agent definition from markdown file data
+ */
+export function parseAgentFromMarkdown(filePath, baseDir, frontmatter, content, source) {
+    try {
+        const agentType = frontmatter['name'];
+        let whenToUse = frontmatter['description'];
+        // Validate required fields — silently skip files without any agent
+        // frontmatter (they're likely co-located reference documentation)
+        if (!agentType || typeof agentType !== 'string') {
+            return null;
+        }
+        if (!whenToUse || typeof whenToUse !== 'string') {
+            logForDebugging(`Agent file ${filePath} is missing required 'description' in frontmatter`);
+            return null;
+        }
+        // Unescape newlines in whenToUse that were escaped for YAML parsing
+        whenToUse = whenToUse.replace(/\\n/g, '\n');
+        const color = frontmatter['color'];
+        const modelRaw = frontmatter['model'];
+        let model;
+        if (typeof modelRaw === 'string' && modelRaw.trim().length > 0) {
+            const trimmed = modelRaw.trim();
+            model = trimmed.toLowerCase() === 'inherit' ? 'inherit' : trimmed;
+        }
+        // Parse background flag
+        const backgroundRaw = frontmatter['background'];
+        if (backgroundRaw !== undefined &&
+            backgroundRaw !== 'true' &&
+            backgroundRaw !== 'false' &&
+            backgroundRaw !== true &&
+            backgroundRaw !== false) {
+            logForDebugging(`Agent file ${filePath} has invalid background value '${backgroundRaw}'. Must be 'true', 'false', or omitted.`);
+        }
+        const background = backgroundRaw === 'true' || backgroundRaw === true ? true : undefined;
+        // Parse memory scope
+        const VALID_MEMORY_SCOPES = ['user', 'project', 'local'];
+        const memoryRaw = frontmatter['memory'];
+        let memory;
+        if (memoryRaw !== undefined) {
+            if (VALID_MEMORY_SCOPES.includes(memoryRaw)) {
+                memory = memoryRaw;
+            }
+            else {
+                logForDebugging(`Agent file ${filePath} has invalid memory value '${memoryRaw}'. Valid options: ${VALID_MEMORY_SCOPES.join(', ')}`);
+            }
+        }
+        const VALID_ISOLATION_MODES = process.env.USER_TYPE === 'ant' ? ['worktree', 'remote'] : ['worktree'];
+        const isolationRaw = frontmatter['isolation'];
+        let isolation;
+        if (isolationRaw !== undefined) {
+            if (VALID_ISOLATION_MODES.includes(isolationRaw)) {
+                isolation = isolationRaw;
+            }
+            else {
+                logForDebugging(`Agent file ${filePath} has invalid isolation value '${isolationRaw}'. Valid options: ${VALID_ISOLATION_MODES.join(', ')}`);
+            }
+        }
+        // Parse effort from frontmatter (supports string levels and integers)
+        const effortRaw = frontmatter['effort'];
+        const parsedEffort = effortRaw !== undefined ? parseEffortValue(effortRaw) : undefined;
+        if (effortRaw !== undefined && parsedEffort === undefined) {
+            logForDebugging(`Agent file ${filePath} has invalid effort '${effortRaw}'. Valid options: ${EFFORT_LEVELS.join(', ')} or an integer`);
+        }
+        // Parse permissionMode from frontmatter
+        const permissionModeRaw = frontmatter['permissionMode'];
+        const isValidPermissionMode = permissionModeRaw &&
+            PERMISSION_MODES.includes(permissionModeRaw);
+        if (permissionModeRaw && !isValidPermissionMode) {
+            const errorMsg = `Agent file ${filePath} has invalid permissionMode '${permissionModeRaw}'. Valid options: ${PERMISSION_MODES.join(', ')}`;
+            logForDebugging(errorMsg);
+        }
+        // Parse maxTurns from frontmatter
+        const maxTurnsRaw = frontmatter['maxTurns'];
+        const maxTurns = parsePositiveIntFromFrontmatter(maxTurnsRaw);
+        if (maxTurnsRaw !== undefined && maxTurns === undefined) {
+            logForDebugging(`Agent file ${filePath} has invalid maxTurns '${maxTurnsRaw}'. Must be a positive integer.`);
+        }
+        // Extract filename without extension
+        const filename = basename(filePath, '.md');
+        // Parse tools from frontmatter
+        let tools = parseAgentToolsFromFrontmatter(frontmatter['tools']);
+        // If memory is enabled, inject Write/Edit/Read tools for memory access
+        if (isAutoMemoryEnabled() && memory && tools !== undefined) {
+            const toolSet = new Set(tools);
+            for (const tool of [
+                FILE_WRITE_TOOL_NAME,
+                FILE_EDIT_TOOL_NAME,
+                FILE_READ_TOOL_NAME,
+            ]) {
+                if (!toolSet.has(tool)) {
+                    tools = [...tools, tool];
+                }
+            }
+        }
+        // Parse disallowedTools from frontmatter
+        const disallowedToolsRaw = frontmatter['disallowedTools'];
+        const disallowedTools = disallowedToolsRaw !== undefined
+            ? parseAgentToolsFromFrontmatter(disallowedToolsRaw)
+            : undefined;
+        // Parse skills from frontmatter
+        const skills = parseSlashCommandToolsFromFrontmatter(frontmatter['skills']);
+        const initialPromptRaw = frontmatter['initialPrompt'];
+        const initialPrompt = typeof initialPromptRaw === 'string' && initialPromptRaw.trim()
+            ? initialPromptRaw
+            : undefined;
+        // Parse mcpServers from frontmatter using same Zod validation as JSON agents
+        const mcpServersRaw = frontmatter['mcpServers'];
+        let mcpServers;
+        if (Array.isArray(mcpServersRaw)) {
+            mcpServers = mcpServersRaw
+                .map(item => {
+                const result = AgentMcpServerSpecSchema().safeParse(item);
+                if (result.success) {
+                    return result.data;
+                }
+                logForDebugging(`Agent file ${filePath} has invalid mcpServers item: ${jsonStringify(item)}. Error: ${result.error.message}`);
+                return null;
+            })
+                .filter((item) => item !== null);
+        }
+        // Parse hooks from frontmatter
+        const hooks = parseHooksFromFrontmatter(frontmatter, agentType);
+        const systemPrompt = content.trim();
+        const agentDef = {
+            baseDir,
+            agentType: agentType,
+            whenToUse: whenToUse,
+            ...(tools !== undefined ? { tools } : {}),
+            ...(disallowedTools !== undefined ? { disallowedTools } : {}),
+            ...(skills !== undefined ? { skills } : {}),
+            ...(initialPrompt !== undefined ? { initialPrompt } : {}),
+            ...(mcpServers !== undefined && mcpServers.length > 0
+                ? { mcpServers }
+                : {}),
+            ...(hooks !== undefined ? { hooks } : {}),
+            getSystemPrompt: () => {
+                if (isAutoMemoryEnabled() && memory) {
+                    const memoryPrompt = loadAgentMemoryPrompt(agentType, memory);
+                    return systemPrompt + '\n\n' + memoryPrompt;
+                }
+                return systemPrompt;
+            },
+            source,
+            filename,
+            ...(color && typeof color === 'string' && AGENT_COLORS.includes(color)
+                ? { color }
+                : {}),
+            ...(model !== undefined ? { model } : {}),
+            ...(parsedEffort !== undefined ? { effort: parsedEffort } : {}),
+            ...(isValidPermissionMode
+                ? { permissionMode: permissionModeRaw }
+                : {}),
+            ...(maxTurns !== undefined ? { maxTurns } : {}),
+            ...(background ? { background } : {}),
+            ...(memory ? { memory } : {}),
+            ...(isolation ? { isolation } : {}),
+        };
+        return agentDef;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logForDebugging(`Error parsing agent from ${filePath}: ${errorMessage}`);
+        logError(error);
+        return null;
+    }
+}