thaddeus 1.0.18 → 1.0.27

package/src/tools/AgentTool/agentToolUtils.js

@@ -0,0 +1,456 @@
+import { feature } from 'bun:bundle';
+import { z } from 'zod/v4';
+import { clearInvokedSkillsForAgent } from '../../bootstrap/state.js';
+import { ALL_AGENT_DISALLOWED_TOOLS, ASYNC_AGENT_ALLOWED_TOOLS, CUSTOM_AGENT_DISALLOWED_TOOLS, IN_PROCESS_TEAMMATE_ALLOWED_TOOLS, } from '../../constants/tools.js';
+import { startAgentSummarization } from '../../services/AgentSummary/agentSummary.js';
+import { logEvent, } from '../../services/analytics/index.js';
+import { clearDumpState } from '../../services/api/dumpPrompts.js';
+import { toolMatchesName } from '../../Tool.js';
+import { completeAgentTask as completeAsyncAgent, createActivityDescriptionResolver, createProgressTracker, enqueueAgentNotification, failAgentTask as failAsyncAgent, getProgressUpdate, getTokenCountFromTracker, isLocalAgentTask, killAsyncAgent, updateAgentProgress as updateAsyncAgentProgress, updateProgressFromMessage, } from '../../tasks/LocalAgentTask/LocalAgentTask.js';
+import { asAgentId } from '../../types/ids.js';
+import { isAgentSwarmsEnabled } from '../../utils/agentSwarmsEnabled.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { isInProtectedNamespace } from '../../utils/envUtils.js';
+import { AbortError, errorMessage } from '../../utils/errors.js';
+import { lazySchema } from '../../utils/lazySchema.js';
+import { extractTextContent, getLastAssistantMessage, } from '../../utils/messages.js';
+import { permissionRuleValueFromString } from '../../utils/permissions/permissionRuleParser.js';
+import { buildTranscriptForClassifier, classifyYoloAction, } from '../../utils/permissions/yoloClassifier.js';
+import { emitTaskProgress as emitTaskProgressEvent } from '../../utils/task/sdkProgress.js';
+import { isInProcessTeammate } from '../../utils/teammateContext.js';
+import { getTokenCountFromUsage } from '../../utils/tokens.js';
+import { EXIT_PLAN_MODE_V2_TOOL_NAME } from '../ExitPlanModeTool/constants.js';
+import { AGENT_TOOL_NAME, LEGACY_AGENT_TOOL_NAME } from './constants.js';
+export function filterToolsForAgent({ tools, isBuiltIn, isAsync = false, permissionMode, }) {
+    return tools.filter(tool => {
+        // Allow MCP tools for all agents
+        if (tool.name.startsWith('mcp__')) {
+            return true;
+        }
+        // Allow ExitPlanMode for agents in plan mode (e.g., in-process teammates)
+        // This bypasses both the ALL_AGENT_DISALLOWED_TOOLS and async tool filters
+        if (toolMatchesName(tool, EXIT_PLAN_MODE_V2_TOOL_NAME) &&
+            permissionMode === 'plan') {
+            return true;
+        }
+        if (ALL_AGENT_DISALLOWED_TOOLS.has(tool.name)) {
+            return false;
+        }
+        if (!isBuiltIn && CUSTOM_AGENT_DISALLOWED_TOOLS.has(tool.name)) {
+            return false;
+        }
+        if (isAsync && !ASYNC_AGENT_ALLOWED_TOOLS.has(tool.name)) {
+            if (isAgentSwarmsEnabled() && isInProcessTeammate()) {
+                // Allow AgentTool for in-process teammates to spawn sync subagents.
+                // Validation in AgentTool.call() prevents background agents and teammate spawning.
+                if (toolMatchesName(tool, AGENT_TOOL_NAME)) {
+                    return true;
+                }
+                // Allow task tools for in-process teammates to coordinate via shared task list
+                if (IN_PROCESS_TEAMMATE_ALLOWED_TOOLS.has(tool.name)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Resolves and validates agent tools against available tools
+ * Handles wildcard expansion and validation in one place
+ */
+export function resolveAgentTools(agentDefinition, availableTools, isAsync = false, isMainThread = false) {
+    const { tools: agentTools, disallowedTools, source, permissionMode, } = agentDefinition;
+    // When isMainThread is true, skip filterToolsForAgent entirely — the main
+    // thread's tool pool is already properly assembled by useMergedTools(), so
+    // the sub-agent disallow lists shouldn't apply.
+    const filteredAvailableTools = isMainThread
+        ? availableTools
+        : filterToolsForAgent({
+            tools: availableTools,
+            isBuiltIn: source === 'built-in',
+            isAsync,
+            permissionMode,
+        });
+    // Create a set of disallowed tool names for quick lookup
+    const disallowedToolSet = new Set(disallowedTools?.map(toolSpec => {
+        const { toolName } = permissionRuleValueFromString(toolSpec);
+        return toolName;
+    }) ?? []);
+    // Filter available tools based on disallowed list
+    const allowedAvailableTools = filteredAvailableTools.filter(tool => !disallowedToolSet.has(tool.name));
+    // If tools is undefined or ['*'], allow all tools (after filtering disallowed)
+    const hasWildcard = agentTools === undefined ||
+        (agentTools.length === 1 && agentTools[0] === '*');
+    if (hasWildcard) {
+        return {
+            hasWildcard: true,
+            validTools: [],
+            invalidTools: [],
+            resolvedTools: allowedAvailableTools,
+        };
+    }
+    const availableToolMap = new Map();
+    for (const tool of allowedAvailableTools) {
+        availableToolMap.set(tool.name, tool);
+    }
+    const validTools = [];
+    const invalidTools = [];
+    const resolved = [];
+    const resolvedToolsSet = new Set();
+    let allowedAgentTypes;
+    for (const toolSpec of agentTools) {
+        // Parse the tool spec to extract the base tool name and any permission pattern
+        const { toolName, ruleContent } = permissionRuleValueFromString(toolSpec);
+        // Special case: Agent tool carries allowedAgentTypes metadata in its spec
+        if (toolName === AGENT_TOOL_NAME) {
+            if (ruleContent) {
+                // Parse comma-separated agent types: "worker, researcher" → ["worker", "researcher"]
+                allowedAgentTypes = ruleContent.split(',').map(s => s.trim());
+            }
+            // For sub-agents, Agent is excluded by filterToolsForAgent — mark the spec
+            // valid for allowedAgentTypes tracking but skip tool resolution.
+            if (!isMainThread) {
+                validTools.push(toolSpec);
+                continue;
+            }
+            // For main thread, filtering was skipped so Agent is in availableToolMap —
+            // fall through to normal resolution below.
+        }
+        const tool = availableToolMap.get(toolName);
+        if (tool) {
+            validTools.push(toolSpec);
+            if (!resolvedToolsSet.has(tool)) {
+                resolved.push(tool);
+                resolvedToolsSet.add(tool);
+            }
+        }
+        else {
+            invalidTools.push(toolSpec);
+        }
+    }
+    return {
+        hasWildcard: false,
+        validTools,
+        invalidTools,
+        resolvedTools: resolved,
+        allowedAgentTypes,
+    };
+}
+export const agentToolResultSchema = lazySchema(() => z.object({
+    agentId: z.string(),
+    // Optional: older persisted sessions won't have this (resume replays
+    // results verbatim without re-validation). Used to gate the sync
+    // result trailer — one-shot built-ins skip the SendMessage hint.
+    agentType: z.string().optional(),
+    content: z.array(z.object({ type: z.literal('text'), text: z.string() })),
+    totalToolUseCount: z.number(),
+    totalDurationMs: z.number(),
+    totalTokens: z.number(),
+    usage: z.object({
+        input_tokens: z.number(),
+        output_tokens: z.number(),
+        cache_creation_input_tokens: z.number().nullable(),
+        cache_read_input_tokens: z.number().nullable(),
+        server_tool_use: z
+            .object({
+            web_search_requests: z.number(),
+            web_fetch_requests: z.number(),
+        })
+            .nullable(),
+        service_tier: z.enum(['standard', 'priority', 'batch']).nullable(),
+        cache_creation: z
+            .object({
+            ephemeral_1h_input_tokens: z.number(),
+            ephemeral_5m_input_tokens: z.number(),
+        })
+            .nullable(),
+    }),
+}));
+export function countToolUses(messages) {
+    let count = 0;
+    for (const m of messages) {
+        if (m.type === 'assistant') {
+            for (const block of m.message.content) {
+                if (block.type === 'tool_use') {
+                    count++;
+                }
+            }
+        }
+    }
+    return count;
+}
+export function finalizeAgentTool(agentMessages, agentId, metadata) {
+    const { prompt, resolvedAgentModel, isBuiltInAgent, startTime, agentType, isAsync, } = metadata;
+    const lastAssistantMessage = getLastAssistantMessage(agentMessages);
+    if (lastAssistantMessage === undefined) {
+        throw new Error('No assistant messages found');
+    }
+    // Extract text content from the agent's response. If the final assistant
+    // message is a pure tool_use block (loop exited mid-turn), fall back to
+    // the most recent assistant message that has text content.
+    let content = lastAssistantMessage.message.content.filter(_ => _.type === 'text');
+    if (content.length === 0) {
+        for (let i = agentMessages.length - 1; i >= 0; i--) {
+            const m = agentMessages[i];
+            if (m.type !== 'assistant')
+                continue;
+            const textBlocks = m.message.content.filter(_ => _.type === 'text');
+            if (textBlocks.length > 0) {
+                content = textBlocks;
+                break;
+            }
+        }
+    }
+    const totalTokens = getTokenCountFromUsage(lastAssistantMessage.message.usage);
+    const totalToolUseCount = countToolUses(agentMessages);
+    logEvent('thaddeus_agent_tool_completed', {
+        agent_type: agentType,
+        model: resolvedAgentModel,
+        prompt_char_count: prompt.length,
+        response_char_count: content.length,
+        assistant_message_count: agentMessages.length,
+        total_tool_uses: totalToolUseCount,
+        duration_ms: Date.now() - startTime,
+        total_tokens: totalTokens,
+        is_built_in_agent: isBuiltInAgent,
+        is_async: isAsync,
+    });
+    // Signal to inference that this subagent's cache chain can be evicted.
+    const lastRequestId = lastAssistantMessage.requestId;
+    if (lastRequestId) {
+        logEvent('thaddeus_cache_eviction_hint', {
+            scope: 'subagent_end',
+            last_request_id: lastRequestId,
+        });
+    }
+    return {
+        agentId,
+        agentType,
+        content,
+        totalDurationMs: Date.now() - startTime,
+        totalTokens,
+        totalToolUseCount,
+        usage: lastAssistantMessage.message.usage,
+    };
+}
+/**
+ * Returns the name of the last tool_use block in an assistant message,
+ * or undefined if the message is not an assistant message with tool_use.
+ */
+export function getLastToolUseName(message) {
+    if (message.type !== 'assistant')
+        return undefined;
+    const block = message.message.content.findLast(b => b.type === 'tool_use');
+    return block?.type === 'tool_use' ? block.name : undefined;
+}
+export function emitTaskProgress(tracker, taskId, toolUseId, description, startTime, lastToolName) {
+    const progress = getProgressUpdate(tracker);
+    emitTaskProgressEvent({
+        taskId,
+        toolUseId,
+        description: progress.lastActivity?.activityDescription ?? description,
+        startTime,
+        totalTokens: progress.tokenCount,
+        toolUses: progress.toolUseCount,
+        lastToolName,
+    });
+}
+export async function classifyHandoffIfNeeded({ agentMessages, tools, toolPermissionContext, abortSignal, subagentType, totalToolUseCount, }) {
+    if (feature('TRANSCRIPT_CLASSIFIER')) {
+        if (toolPermissionContext.mode !== 'auto')
+            return null;
+        const agentTranscript = buildTranscriptForClassifier(agentMessages, tools);
+        if (!agentTranscript)
+            return null;
+        const classifierResult = await classifyYoloAction(agentMessages, {
+            role: 'user',
+            content: [
+                {
+                    type: 'text',
+                    text: "Sub-agent has finished and is handing back control to the main agent. Review the sub-agent's work based on the block rules and let the main agent know if any file is dangerous (the main agent will see the reason).",
+                },
+            ],
+        }, tools, toolPermissionContext, abortSignal);
+        const handoffDecision = classifierResult.unavailable
+            ? 'unavailable'
+            : classifierResult.shouldBlock
+                ? 'blocked'
+                : 'allowed';
+        logEvent('thaddeus_auto_mode_decision', {
+            decision: handoffDecision,
+            toolName: 
+            // Use legacy name for analytics continuity across the Task→Agent rename
+            LEGACY_AGENT_TOOL_NAME,
+            inProtectedNamespace: isInProtectedNamespace(),
+            classifierModel: classifierResult.model,
+            agentType: subagentType,
+            toolUseCount: totalToolUseCount,
+            isHandoff: true,
+            // For handoff, the relevant agent completion is the subagent's final
+            // assistant message — the last thing the classifier transcript shows
+            // before the handoff review prompt.
+            agentMsgId: getLastAssistantMessage(agentMessages)?.message
+                .id,
+            classifierStage: classifierResult.stage,
+            classifierStage1RequestId: classifierResult.stage1RequestId,
+            classifierStage1MsgId: classifierResult.stage1MsgId,
+            classifierStage2RequestId: classifierResult.stage2RequestId,
+            classifierStage2MsgId: classifierResult.stage2MsgId,
+        });
+        if (classifierResult.shouldBlock) {
+            // When classifier is unavailable, still propagate the sub-agent's
+            // results but with a warning so the parent agent can verify the work.
+            if (classifierResult.unavailable) {
+                logForDebugging('Handoff classifier unavailable, allowing sub-agent output with warning', { level: 'warn' });
+                return `Note: The safety classifier was unavailable when reviewing this sub-agent's work. Please carefully verify the sub-agent's actions and output before acting on them.`;
+            }
+            logForDebugging(`Handoff classifier flagged sub-agent output: ${classifierResult.reason}`, { level: 'warn' });
+            return `SECURITY WARNING: This sub-agent performed actions that may violate security policy. Reason: ${classifierResult.reason}. Review the sub-agent's actions carefully before acting on its output.`;
+        }
+    }
+    return null;
+}
+/**
+ * Extract a partial result string from an agent's accumulated messages.
+ * Used when an async agent is killed to preserve what it accomplished.
+ * Returns undefined if no text content is found.
+ */
+export function extractPartialResult(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.type !== 'assistant')
+            continue;
+        const text = extractTextContent(m.message.content, '\n');
+        if (text) {
+            return text;
+        }
+    }
+    return undefined;
+}
+/**
+ * Drives a background agent from spawn to terminal notification.
+ * Shared between AgentTool's async-from-start path and resumeAgentBackground.
+ */
+export async function runAsyncAgentLifecycle({ taskId, abortController, makeStream, metadata, description, toolUseContext, rootSetAppState, agentIdForCleanup, enableSummarization, getWorktreeResult, }) {
+    let stopSummarization;
+    const agentMessages = [];
+    try {
+        const tracker = createProgressTracker();
+        const resolveActivity = createActivityDescriptionResolver(toolUseContext.options.tools);
+        const onCacheSafeParams = enableSummarization
+            ? (params) => {
+                const { stop } = startAgentSummarization(taskId, asAgentId(taskId), params, rootSetAppState);
+                stopSummarization = stop;
+            }
+            : undefined;
+        for await (const message of makeStream(onCacheSafeParams)) {
+            agentMessages.push(message);
+            // Append immediately when UI holds the task (retain). Bootstrap reads
+            // disk in parallel and UUID-merges the prefix — disk-write-before-yield
+            // means live is always a suffix of disk, so merge is order-correct.
+            rootSetAppState(prev => {
+                const t = prev.tasks[taskId];
+                if (!isLocalAgentTask(t) || !t.retain)
+                    return prev;
+                const base = t.messages ?? [];
+                return {
+                    ...prev,
+                    tasks: {
+                        ...prev.tasks,
+                        [taskId]: { ...t, messages: [...base, message] },
+                    },
+                };
+            });
+            updateProgressFromMessage(tracker, message, resolveActivity, toolUseContext.options.tools);
+            updateAsyncAgentProgress(taskId, getProgressUpdate(tracker), rootSetAppState);
+            const lastToolName = getLastToolUseName(message);
+            if (lastToolName) {
+                emitTaskProgress(tracker, taskId, toolUseContext.toolUseId, description, metadata.startTime, lastToolName);
+            }
+        }
+        stopSummarization?.();
+        const agentResult = finalizeAgentTool(agentMessages, taskId, metadata);
+        // Mark task completed FIRST so TaskOutput(block=true) unblocks
+        // immediately. classifyHandoffIfNeeded (API call) and getWorktreeResult
+        // (git exec) are notification embellishments that can hang — they must
+        // not gate the status transition (gh-20236).
+        completeAsyncAgent(agentResult, rootSetAppState);
+        let finalMessage = extractTextContent(agentResult.content, '\n');
+        if (feature('TRANSCRIPT_CLASSIFIER')) {
+            const handoffWarning = await classifyHandoffIfNeeded({
+                agentMessages,
+                tools: toolUseContext.options.tools,
+                toolPermissionContext: toolUseContext.getAppState().toolPermissionContext,
+                abortSignal: abortController.signal,
+                subagentType: metadata.agentType,
+                totalToolUseCount: agentResult.totalToolUseCount,
+            });
+            if (handoffWarning) {
+                finalMessage = `${handoffWarning}\n\n${finalMessage}`;
+            }
+        }
+        const worktreeResult = await getWorktreeResult();
+        enqueueAgentNotification({
+            taskId,
+            description,
+            status: 'completed',
+            setAppState: rootSetAppState,
+            finalMessage,
+            usage: {
+                totalTokens: getTokenCountFromTracker(tracker),
+                toolUses: agentResult.totalToolUseCount,
+                durationMs: agentResult.totalDurationMs,
+            },
+            toolUseId: toolUseContext.toolUseId,
+            ...worktreeResult,
+        });
+    }
+    catch (error) {
+        stopSummarization?.();
+        if (error instanceof AbortError) {
+            // killAsyncAgent is a no-op if TaskStop already set status='killed' —
+            // but only this catch handler has agentMessages, so the notification
+            // must fire unconditionally. Transition status BEFORE worktree cleanup
+            // so TaskOutput unblocks even if git hangs (gh-20236).
+            killAsyncAgent(taskId, rootSetAppState);
+            logEvent('thaddeus_agent_tool_terminated', {
+                agent_type: metadata.agentType,
+                model: metadata.resolvedAgentModel,
+                duration_ms: Date.now() - metadata.startTime,
+                is_async: true,
+                is_built_in_agent: metadata.isBuiltInAgent,
+                reason: 'user_kill_async',
+            });
+            const worktreeResult = await getWorktreeResult();
+            const partialResult = extractPartialResult(agentMessages);
+            enqueueAgentNotification({
+                taskId,
+                description,
+                status: 'killed',
+                setAppState: rootSetAppState,
+                toolUseId: toolUseContext.toolUseId,
+                finalMessage: partialResult,
+                ...worktreeResult,
+            });
+            return;
+        }
+        const msg = errorMessage(error);
+        failAsyncAgent(taskId, msg, rootSetAppState);
+        const worktreeResult = await getWorktreeResult();
+        enqueueAgentNotification({
+            taskId,
+            description,
+            status: 'failed',
+            error: msg,
+            setAppState: rootSetAppState,
+            toolUseId: toolUseContext.toolUseId,
+            ...worktreeResult,
+        });
+    }
+    finally {
+        clearInvokedSkillsForAgent(agentIdForCleanup);
+        clearDumpState(agentIdForCleanup);
+    }
+}

package/src/tools/AgentTool/built-in/exploreAgent.js

@@ -0,0 +1,76 @@
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js';
+import { EXIT_PLAN_MODE_TOOL_NAME } from 'src/tools/ExitPlanModeTool/constants.js';
+import { FILE_EDIT_TOOL_NAME } from 'src/tools/FileEditTool/constants.js';
+import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js';
+import { FILE_WRITE_TOOL_NAME } from 'src/tools/FileWriteTool/prompt.js';
+import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js';
+import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js';
+import { NOTEBOOK_EDIT_TOOL_NAME } from 'src/tools/NotebookEditTool/constants.js';
+import { hasEmbeddedSearchTools } from 'src/utils/embeddedTools.js';
+import { AGENT_TOOL_NAME } from '../constants.js';
+function getExploreSystemPrompt() {
+    // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the
+    // dedicated Glob/Grep tools, so point at find/grep via Bash instead.
+    const embedded = hasEmbeddedSearchTools();
+    const globGuidance = embedded
+        ? `- Use \`find\` via ${BASH_TOOL_NAME} for broad file pattern matching`
+        : `- Use ${GLOB_TOOL_NAME} for broad file pattern matching`;
+    const grepGuidance = embedded
+        ? `- Use \`grep\` via ${BASH_TOOL_NAME} for searching file contents with regex`
+        : `- Use ${GREP_TOOL_NAME} for searching file contents with regex`;
+    return `You are a file search specialist for Thaddeus, Delphi Labs' official CLI agent. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+${globGuidance}
+${grepGuidance}
+- Use ${FILE_READ_TOOL_NAME} when you know the specific file path you need to read
+- Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find${embedded ? ', grep' : ''}, cat, head, tail)
+- NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.`;
+}
+export const EXPLORE_AGENT_MIN_QUERIES = 3;
+const EXPLORE_WHEN_TO_USE = 'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.';
+export const EXPLORE_AGENT = {
+    agentType: 'Explore',
+    whenToUse: EXPLORE_WHEN_TO_USE,
+    disallowedTools: [
+        AGENT_TOOL_NAME,
+        EXIT_PLAN_MODE_TOOL_NAME,
+        FILE_EDIT_TOOL_NAME,
+        FILE_WRITE_TOOL_NAME,
+        NOTEBOOK_EDIT_TOOL_NAME,
+    ],
+    source: 'built-in',
+    baseDir: 'built-in',
+    // Ants get inherit to use the main agent's model; external users get haiku for speed
+    // Note: For ants, getAgentModel() checks thaddeus_explore_agent GrowthBook flag at runtime
+    model: process.env.USER_TYPE === 'ant' ? 'inherit' : 'haiku',
+    // Explore is a fast read-only search agent — it doesn't need commit/PR/lint
+    // rules from THADDEUS.md. The main agent has full context and interprets results.
+    omitClaudeMd: true,
+    getSystemPrompt: () => getExploreSystemPrompt(),
+};

package/src/tools/AgentTool/built-in/generalPurposeAgent.js

@@ -0,0 +1,28 @@
+const SHARED_PREFIX = `You are an agent for Thaddeus, Delphi Labs' official CLI agent. Given the user's message, you should use the tools available to complete the task. Complete the task fully—don't gold-plate, but don't leave it half-done.`;
+const SHARED_GUIDELINES = `Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: search broadly when you don't know where something lives. Use Read when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.`;
+// Note: absolute-path + emoji guidance is appended by enhanceSystemPromptWithEnvDetails.
+function getGeneralPurposeSystemPrompt() {
+    return `${SHARED_PREFIX} When you complete the task, respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials.
+
+${SHARED_GUIDELINES}`;
+}
+export const GENERAL_PURPOSE_AGENT = {
+    agentType: 'general-purpose',
+    whenToUse: 'General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.',
+    tools: ['*'],
+    source: 'built-in',
+    baseDir: 'built-in',
+    // model is intentionally omitted - uses getDefaultSubagentModel().
+    getSystemPrompt: getGeneralPurposeSystemPrompt,
+};

package/src/tools/AgentTool/built-in/planAgent.js

@@ -0,0 +1,87 @@
+import { BASH_TOOL_NAME } from 'src/tools/BashTool/toolName.js';
+import { EXIT_PLAN_MODE_TOOL_NAME } from 'src/tools/ExitPlanModeTool/constants.js';
+import { FILE_EDIT_TOOL_NAME } from 'src/tools/FileEditTool/constants.js';
+import { FILE_READ_TOOL_NAME } from 'src/tools/FileReadTool/prompt.js';
+import { FILE_WRITE_TOOL_NAME } from 'src/tools/FileWriteTool/prompt.js';
+import { GLOB_TOOL_NAME } from 'src/tools/GlobTool/prompt.js';
+import { GREP_TOOL_NAME } from 'src/tools/GrepTool/prompt.js';
+import { NOTEBOOK_EDIT_TOOL_NAME } from 'src/tools/NotebookEditTool/constants.js';
+import { hasEmbeddedSearchTools } from 'src/utils/embeddedTools.js';
+import { AGENT_TOOL_NAME } from '../constants.js';
+import { EXPLORE_AGENT } from './exploreAgent.js';
+function getPlanV2SystemPrompt() {
+    // Ant-native builds alias find/grep to embedded bfs/ugrep and remove the
+    // dedicated Glob/Grep tools, so point at find/grep instead.
+    const searchToolsHint = hasEmbeddedSearchTools()
+        ? `\`find\`, \`grep\`, and ${FILE_READ_TOOL_NAME}`
+        : `${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, and ${FILE_READ_TOOL_NAME}`;
+    return `You are a software architect and planning specialist for Thaddeus. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using ${searchToolsHint}
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use ${BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find${hasEmbeddedSearchTools() ? ', grep' : ''}, cat, head, tail)
+   - NEVER use ${BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts
+- path/to/file2.ts
+- path/to/file3.ts
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.`;
+}
+export const PLAN_AGENT = {
+    agentType: 'Plan',
+    whenToUse: 'Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.',
+    disallowedTools: [
+        AGENT_TOOL_NAME,
+        EXIT_PLAN_MODE_TOOL_NAME,
+        FILE_EDIT_TOOL_NAME,
+        FILE_WRITE_TOOL_NAME,
+        NOTEBOOK_EDIT_TOOL_NAME,
+    ],
+    source: 'built-in',
+    tools: EXPLORE_AGENT.tools,
+    baseDir: 'built-in',
+    model: 'inherit',
+    // Plan is read-only and can Read THADDEUS.md directly if it needs conventions.
+    // Dropping it from context saves tokens without blocking access.
+    omitClaudeMd: true,
+    getSystemPrompt: () => getPlanV2SystemPrompt(),
+};