codeep 2.1.3 → 2.3.0

package/dist/utils/agent.js

@@ -11,8 +11,9 @@ const debug = (...args) => {
     }
 };
 // Import chat layer (prompt building + API calls)
-import { agentChat, getAgentSystemPrompt, getFallbackSystemPrompt, loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent, } from './agentChat.js';
+import { agentChat, getAgentSystemPrompt, getFallbackSystemPrompt, loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent, summarizeEarlierHistory, } from './agentChat.js';
 import { ApiError } from '../api/index.js';
+import { loadUserProfilePrompt } from './userProfile.js';
 export { loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent };
 /**
  * Calculate dynamic timeout based on task complexity
@@ -127,8 +128,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
     const startTime = Date.now();
     const actions = [];
     const messages = [];
-    // Start history session for undo support
-    const sessionId = startSession(prompt, projectContext.root || process.cwd());
+    // Start history session for undo support. Skipped for nested (delegated)
+    // runs so we don't reset the parent's currentSession singleton — the
+    // sub-agent's actions still record into the parent's open session.
+    const sessionId = opts.nested ? '' : startSession(prompt, projectContext.root || process.cwd());
     // Task planning phase (if enabled)
     // Use planning for complex keywords or multi-word prompts
     let taskPlan = null;
@@ -221,10 +224,53 @@ export async function runAgent(prompt, projectContext, options = {}) {
     catch {
         // Skill loading failure shouldn't fail the whole agent run.
     }
+    // Sub-agents — the `delegate` tool lets the top-level agent hand a
+    // self-contained sub-task to a specialist that runs in its own context and
+    // returns a summary. Only advertised at depth 0, so sub-agents can't recurse
+    // (delegation depth is capped at 1 for v1).
+    let agentsCatalogBlock = '';
+    if ((opts.depth ?? 0) === 0) {
+        try {
+            const { loadAgents, formatAgentsForSysprompt } = await import('./agents.js');
+            const agents = loadAgents(projectContext.root);
+            if (agents.length > 0) {
+                mcpToolDefs.push({
+                    name: 'delegate',
+                    description: 'Delegate a self-contained sub-task to a specialist sub-agent that runs in its own fresh context and returns a summary. Use it to keep your own context focused.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            agent: { type: 'string', description: 'Sub-agent name from the catalog (e.g. "researcher"). Omit for a general-purpose sub-agent.' },
+                            task: { type: 'string', description: 'A clear, self-contained instruction for the sub-agent.' },
+                        },
+                        required: ['task'],
+                    },
+                });
+                agentsCatalogBlock = formatAgentsForSysprompt(agents);
+            }
+        }
+        catch {
+            // Agent loading must never block the run.
+        }
+    }
     // Build system prompt - use fallback format if native tools not supported
     let systemPrompt = useNativeTools
         ? getAgentSystemPrompt(projectContext)
         : getFallbackSystemPrompt(projectContext, mcpToolDefs);
+    // Delegated sub-agent role — its defining instruction. Injected right after
+    // the base prompt so it frames everything that follows. Empty for normal runs.
+    if (opts.roleAddendum) {
+        systemPrompt += '\n\n## Your role (delegated sub-agent)\n' + opts.roleAddendum;
+    }
+    // Inject the user profile (global ~/.codeep/profile.md + project
+    // .codeep/profile.md) so the agent adapts to who it's working with —
+    // reply language, style, stack, hard preferences. User-authored and gated
+    // by config.userProfile. Lives here (not in the base prompt) so every
+    // surface — CLI, ACP, VS Code, Zed — inherits it via this single path.
+    const userProfileBlock = loadUserProfilePrompt(projectContext.root);
+    if (userProfileBlock) {
+        systemPrompt += userProfileBlock;
+    }
     // Inject project rules (from .codeep/rules.md or CODEEP.md)
     const projectRules = loadProjectRules(projectContext.root);
     if (projectRules) {
@@ -242,7 +288,13 @@ export async function runAgent(prompt, projectContext, options = {}) {
     if (taskCtx) {
         systemPrompt += taskCtx;
     }
-    // Inject prior chat session context
+    // Inject prior chat session context. When the history overflows the budget,
+    // prepend an LLM recap of the dropped (oldest) messages so long sessions
+    // keep early decisions/constraints, then the recent messages verbatim.
+    const earlierSummary = await summarizeEarlierHistory(opts.chatHistory);
+    if (earlierSummary) {
+        systemPrompt += earlierSummary;
+    }
     const chatHistoryStr = formatChatHistoryForAgent(opts.chatHistory);
     if (chatHistoryStr) {
         systemPrompt += chatHistoryStr;
@@ -253,6 +305,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
     if (skillCatalogBlock) {
         systemPrompt += '\n\n' + skillCatalogBlock;
     }
+    // Sub-agent catalog (delegate) — only present at depth 0.
+    if (agentsCatalogBlock) {
+        systemPrompt += agentsCatalogBlock;
+    }
     // Active personality goes LAST — appended after skills / project rules /
     // smart context so its tone overrides earlier conventions. Set via
     // `/personality <name>`; empty when no personality is active.
@@ -291,6 +347,95 @@ export async function runAgent(prompt, projectContext, options = {}) {
         ...(config.get('agentConfirmExecuteCommand') !== false ? ['execute_command'] : []),
         ...(config.get('agentConfirmWriteFile') === true ? ['write_file', 'edit_file'] : []),
     ]);
+    // Delegation handler: run a named (or generic) sub-agent in its own fresh
+    // context and return its summary as the tool result. Reachable only when the
+    // `delegate` tool was advertised (depth 0). The sub-agent runs nested (no own
+    // undo session) at depth 1 and never gets `delegate`, so depth is capped at 1.
+    const runDelegate = async (toolCall) => {
+        const params = (toolCall.parameters || {});
+        const task = String(params.task || '').trim();
+        const fail = (error) => ({ success: false, output: '', error, tool: 'delegate', parameters: toolCall.parameters });
+        if (!task)
+            return fail('delegate requires a non-empty "task".');
+        let def = null;
+        try {
+            const { findAgent } = await import('./agents.js');
+            def = params.agent ? findAgent(params.agent, projectContext.root) : null;
+            if (params.agent && !def)
+                return fail(`No sub-agent named "${params.agent}". Run /agents to see available agents.`);
+        }
+        catch { /* fall back to a generic sub-agent */ }
+        let roleAddendum = def?.prompt
+            || 'You are a general-purpose sub-agent. Complete the task in your own context and return a concise, self-contained summary of what you did and the outcome.';
+        if (def?.tools)
+            roleAddendum += `\n\nYou may use ONLY these tools: ${def.tools.join(', ')}.`;
+        if (def?.personality) {
+            try {
+                const { findPersonality } = await import('./personalities.js');
+                const p = findPersonality(def.personality, projectContext.root);
+                if (p)
+                    roleAddendum += '\n' + p.prompt;
+            }
+            catch { /* ignore */ }
+        }
+        const label = def?.name || 'agent';
+        opts.onIteration?.(iteration, `⤷ delegating to ${label}…`);
+        const tag = (text) => `⤷ ${label}: ${text}`;
+        // Model override — swap config for the nested run, restore in finally.
+        const prevModel = config.get('model');
+        const prevProvider = config.get('provider');
+        let swapped = false;
+        if (def?.model) {
+            try {
+                const m = String(def.model);
+                if (m.includes('/')) {
+                    const { setProvider } = await import('../config/index.js');
+                    setProvider(m.slice(0, m.indexOf('/')));
+                    config.set('model', m.slice(m.indexOf('/') + 1));
+                }
+                else {
+                    config.set('model', m);
+                }
+                swapped = true;
+            }
+            catch { /* keep parent's model */ }
+        }
+        try {
+            const sub = await runAgent(task, projectContext, {
+                ...DEFAULT_OPTIONS,
+                nested: true,
+                depth: (opts.depth ?? 0) + 1,
+                allowedTools: def?.tools,
+                roleAddendum,
+                maxIterations: def?.maxIterations ?? Math.min(15, opts.maxIterations),
+                maxDuration: opts.maxDuration,
+                abortSignal: opts.abortSignal,
+                onRequestPermission: opts.onRequestPermission,
+                onExecuteCommand: opts.onExecuteCommand,
+                fs: opts.fs,
+                mcpSessionId: opts.mcpSessionId,
+                autoVerify: false,
+                onIteration: (_i, msg) => opts.onIteration?.(iteration, tag(msg)),
+                onThinking: (t) => opts.onThinking?.(tag(t)),
+                // No chatHistory → the sub-agent gets a fresh context window.
+            });
+            const summary = sub.finalResponse?.trim() || '(sub-agent finished without a summary)';
+            return { success: sub.success, output: `[${label}] ${summary}`, tool: 'delegate', parameters: toolCall.parameters };
+        }
+        catch (err) {
+            return fail(`Sub-agent "${label}" failed: ${err.message}`);
+        }
+        finally {
+            if (swapped) {
+                try {
+                    const { setProvider } = await import('../config/index.js');
+                    setProvider(String(prevProvider));
+                    config.set('model', prevModel);
+                }
+                catch { /* ignore restore failure */ }
+            }
+        }
+    };
     const maxTimeoutRetries = 3;
     const maxConsecutiveTimeouts = 30; // Allow more consecutive timeouts before giving up
     const maxConsecutiveRateLimits = 5; // Stop after 5 consecutive rate-limited iterations
@@ -322,7 +467,8 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     finalResponse: partialLines.join('\n'),
                     error: `Exceeded maximum duration of ${durationMin} min`,
                 };
-                writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
+                if (!opts.nested)
+                    writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
                 return result;
             }
             // Check abort signal
@@ -584,6 +730,21 @@ export async function runAgent(prompt, projectContext, options = {}) {
             const toolResults = [];
             for (const toolCall of toolCalls) {
                 opts.onToolCall?.(toolCall);
+                // Tool scoping for delegated sub-agents: reject any tool outside the
+                // agent's allowlist up front — no permission prompt, no execution.
+                if (opts.allowedTools && !opts.allowedTools.includes(toolCall.tool)) {
+                    const denied = {
+                        success: false,
+                        output: '',
+                        error: `Tool "${toolCall.tool}" is not available to this sub-agent.`,
+                        tool: toolCall.tool,
+                        parameters: toolCall.parameters,
+                    };
+                    opts.onToolResult?.(denied, toolCall);
+                    actions.push(createActionLog(toolCall, denied));
+                    toolResults.push(`Tool ${toolCall.tool} is not allowed for this sub-agent. Use only: ${opts.allowedTools.join(', ')}.`);
+                    continue;
+                }
                 // Permission check for dangerous tools (only when callback is provided, e.g. ACP/Zed)
                 if (opts.onRequestPermission && dangerousTools.has(toolCall.tool) && !alwaysAllowedTools.has(toolCall.tool)) {
                     const rejectResult = () => {
@@ -619,7 +780,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     }
                 }
                 let toolResult;
-                if (opts.dryRun) {
+                if (toolCall.tool === 'delegate') {
+                    toolResult = await runDelegate(toolCall);
+                }
+                else if (opts.dryRun) {
                     toolResult = {
                         success: true,
                         output: `[DRY RUN] Would execute: ${toolCall.tool}`,
@@ -744,7 +908,8 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 finalResponse: partialLines.join('\n'),
                 error: `Exceeded maximum of ${opts.maxIterations} iterations`,
             };
-            writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
+            if (!opts.nested)
+                writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
             return result;
         }
         // Self-verification: Run build/test and fix errors if needed
@@ -870,13 +1035,39 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 }
             }
         }
+        // Pipeline (Phase 2): optional automatic review pass. After a top-level run
+        // that changed files, delegate to the `reviewer` sub-agent and append its
+        // findings — guaranteeing a review stage without relying on the model to
+        // self-delegate one. Opt-in (agentAutoReview); depth-0 only; never fatal.
+        if (!opts.nested
+            && (opts.depth ?? 0) === 0
+            && !opts.dryRun
+            && config.get('agentAutoReview') === true
+            && !opts.abortSignal?.aborted
+            && actions.some(a => a.type === 'write' || a.type === 'edit' || a.type === 'delete')) {
+            try {
+                const reviewTask = `Review the changes just made for this task:\n\n${prompt}\n\nInspect the current state of the changed files (and the git diff). Report concrete issues by severity — correctness/bugs, security, then design — with file:line and a one-line fix each. If it's solid, say so briefly.`;
+                const review = await runDelegate({
+                    id: 'auto-review',
+                    tool: 'delegate',
+                    parameters: { agent: 'reviewer', task: reviewTask },
+                });
+                const body = (review.output || '').replace(/^\[reviewer\]\s*/, '').trim();
+                if (body)
+                    finalResponse += `\n\n---\n### Auto-review (reviewer)\n${body}`;
+            }
+            catch {
+                // A failed review must never fail the run.
+            }
+        }
         result = {
             success: true,
             iterations: iteration,
             actions,
             finalResponse,
         };
-        writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
+        if (!opts.nested)
+            writeProgressLog(projectContext.root || '', prompt, result, projectContext.name);
         return result;
     }
     catch (error) {
@@ -891,8 +1082,10 @@ export async function runAgent(prompt, projectContext, options = {}) {
         return result;
     }
     finally {
-        // End session and save history
-        endSession();
+        // End session and save history. Skipped for nested runs so we don't write
+        // a separate session file or null out the parent's open session.
+        if (!opts.nested)
+            endSession();
     }
 }
 /**

package/dist/utils/agentChat.d.ts

@@ -52,6 +52,21 @@ export declare function formatChatHistoryForAgent(history?: Array<{
     role: 'user' | 'assistant';
     content: string;
 }>, maxChars?: number): string;
+/**
+ * Summarize the OVERFLOW that `formatChatHistoryForAgent` drops. When prior
+ * history exceeds `maxChars`, that function keeps only the most recent messages
+ * and silently discards the older ones — losing early decisions/constraints on
+ * long sessions. This condenses those dropped messages into a short recap that
+ * the caller prepends *before* the recent verbatim history.
+ *
+ * Returns '' when: opted out (`autoSummarizeHistory === false`), nothing
+ * overflows, or the summarization call fails (graceful fallback — the recent
+ * history still goes in, we just don't add a recap).
+ */
+export declare function summarizeEarlierHistory(history?: Array<{
+    role: 'user' | 'assistant';
+    content: string;
+}>, maxChars?: number): Promise<string>;
 export declare function getAgentSystemPrompt(projectContext: ProjectContext): string;
 export declare function getFallbackSystemPrompt(projectContext: ProjectContext, additionalTools?: AdditionalToolDef[]): string;
 /**

package/dist/utils/agentChat.js

@@ -13,6 +13,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { createHash } from 'crypto';
 import { config, getApiKey, resolveBaseUrl } from '../config/index.js';
 import { loadProjectIntelligence, generateContextFromIntelligence } from './projectIntelligence.js';
 import { syncProgress, generateProjectId } from './codeepCloud.js';
@@ -180,6 +181,84 @@ export function formatChatHistoryForAgent(history, maxChars = 16000) {
     const lines = selected.map(m => `**${m.role === 'user' ? 'User' : 'Assistant'}:** ${m.content}`).join('\n\n');
     return `\n\n## Prior Conversation Context\nThe following is the recent chat history from this session. Use it as background context to understand the user's intent, but focus on completing the current task.\n\n${lines}`;
 }
+// Same noise filter formatChatHistoryForAgent uses — kept in sync so the two
+// functions agree on which messages are "real" conversation.
+function filterAgentHistory(history) {
+    return history.filter(m => {
+        const content = m.content.trimStart();
+        if (content.startsWith('[AGENT]') || content.startsWith('[DRY RUN]'))
+            return false;
+        if (content.startsWith('Agent completed') || content.startsWith('Agent failed') || content.startsWith('Agent stopped'))
+            return false;
+        return true;
+    });
+}
+// Cache summaries by a hash of the dropped messages, so re-running the agent in
+// the same session (same overflow) doesn't re-summarize on every task.
+const earlierSummaryCache = new Map();
+/**
+ * Summarize the OVERFLOW that `formatChatHistoryForAgent` drops. When prior
+ * history exceeds `maxChars`, that function keeps only the most recent messages
+ * and silently discards the older ones — losing early decisions/constraints on
+ * long sessions. This condenses those dropped messages into a short recap that
+ * the caller prepends *before* the recent verbatim history.
+ *
+ * Returns '' when: opted out (`autoSummarizeHistory === false`), nothing
+ * overflows, or the summarization call fails (graceful fallback — the recent
+ * history still goes in, we just don't add a recap).
+ */
+export async function summarizeEarlierHistory(history, maxChars = 16000) {
+    if (config.get('autoSummarizeHistory') === false)
+        return '';
+    if (!history || history.length === 0)
+        return '';
+    const filtered = filterAgentHistory(history);
+    if (filtered.length === 0)
+        return '';
+    // Mirror formatChatHistoryForAgent's newest→oldest budget walk to find which
+    // messages it KEEPS; everything older than the oldest kept message is dropped.
+    let totalChars = 0;
+    let firstKept = filtered.length;
+    for (let i = filtered.length - 1; i >= 0; i--) {
+        const entry = `${filtered[i].role === 'user' ? 'User' : 'Assistant'}: ${filtered[i].content}`;
+        if (totalChars + entry.length > maxChars && firstKept < filtered.length)
+            break;
+        if (entry.length > maxChars) {
+            firstKept = i;
+            break;
+        }
+        firstKept = i;
+        totalChars += entry.length;
+    }
+    const dropped = filtered.slice(0, firstKept);
+    if (dropped.length === 0)
+        return '';
+    const key = createHash('sha256')
+        .update(dropped.map(m => `${m.role}:${m.content}`).join(''))
+        .digest('hex');
+    const cached = earlierSummaryCache.get(key);
+    if (cached)
+        return cached;
+    // Compact transcript of the dropped messages, capped so the summarization
+    // prompt stays cheap even when a lot has overflowed.
+    const transcript = dropped
+        .map(m => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content.replace(/\s+/g, ' ').slice(0, 600)}`)
+        .join('\n')
+        .slice(0, 24000);
+    const system = 'You are condensing the EARLIER part of an ongoing coding session that no longer fits the context window. Summarize what happened in 3-6 sentences: concrete decisions made, constraints/requirements stated, files or APIs involved, and anything still unfinished. Past tense, no preamble, no bullet headers — just the recap.';
+    try {
+        const { chat } = await import('../api/index.js');
+        const summary = (await chat(transcript, [{ role: 'system', content: system }])).trim();
+        if (!summary)
+            return '';
+        const block = `\n\n## Earlier Conversation (summarized)\nThe earlier part of this session was condensed to fit context. Treat it as established background:\n\n${summary}`;
+        earlierSummaryCache.set(key, block);
+        return block;
+    }
+    catch {
+        return ''; // graceful — recent verbatim history still gets injected
+    }
+}
 export function getAgentSystemPrompt(projectContext) {
     const root = projectContext.root || process.cwd();
     // State the real underlying model/provider so "which model are you"

package/dist/utils/agents.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Sub-agents — named, scoped agent definitions the main ("orchestrator") agent
+ * can delegate work to via the `delegate` tool. Each runs as a NESTED agent
+ * loop with its own fresh context window, an optional tool allowlist, an
+ * optional model override, and a role system prompt — then returns only its
+ * final summary to the parent. This keeps the parent's context small and lets
+ * each sub-task run with a specialist persona.
+ *
+ * Storage (mirrors personalities/skills):
+ *   - **Built-in**: hardcoded below (researcher, reviewer, tester).
+ *   - **Project**: `<workspace>/.codeep/agents/<name>.md`
+ *   - **Global**:  `~/.codeep/agents/<name>.md`
+ * Project shadows global shadows built-in, by name.
+ *
+ * File format — YAML-ish frontmatter + Markdown body (the role prompt):
+ *   ```
+ *   ---
+ *   name: reviewer
+ *   description: Reviews a diff for correctness & security
+ *   tools: [read_file, search_code, execute_command]   # allowlist; omit = all
+ *   model: glm-5.1            # optional provider/model or model override
+ *   personality: security     # optional — reuse a personality preset
+ *   maxIterations: 15         # optional budget
+ *   ---
+ *   You are a senior reviewer. Find correctness & security issues…
+ *   ```
+ */
+export type AgentScope = 'builtin' | 'project' | 'global';
+export interface AgentDef {
+    /** Slug (filename without .md, or built-in id). Lowercase, hyphens. */
+    name: string;
+    /** Human display label. */
+    displayName: string;
+    /** One-line description shown in the catalog + `/agents`. */
+    description: string;
+    /** Markdown body — the role system prompt for the sub-agent. */
+    prompt: string;
+    /** Tool allowlist. Undefined = inherit all of the parent's tools. */
+    tools?: string[];
+    /** Optional model override ("provider/model" or just "model"). */
+    model?: string;
+    /** Optional personality preset to layer on (by name). */
+    personality?: string;
+    /** Optional per-run iteration budget. */
+    maxIterations?: number;
+    scope: AgentScope;
+}
+export declare function loadAgents(workspaceRoot?: string): AgentDef[];
+export declare function findAgent(name: string, workspaceRoot?: string): AgentDef | null;
+/**
+ * The catalog block appended to the orchestrator's system prompt so the model
+ * knows which sub-agents it can `delegate` to. Empty string is never returned
+ * (built-ins always exist), but callers can choose not to inject it.
+ */
+export declare function formatAgentsForSysprompt(agents: AgentDef[]): string;
+/** `/agents` list view (mirrors formatPersonalityList). */
+export declare function formatAgentList(workspaceRoot?: string): string;

package/dist/utils/agents.js

@@ -0,0 +1,188 @@
+/**
+ * Sub-agents — named, scoped agent definitions the main ("orchestrator") agent
+ * can delegate work to via the `delegate` tool. Each runs as a NESTED agent
+ * loop with its own fresh context window, an optional tool allowlist, an
+ * optional model override, and a role system prompt — then returns only its
+ * final summary to the parent. This keeps the parent's context small and lets
+ * each sub-task run with a specialist persona.
+ *
+ * Storage (mirrors personalities/skills):
+ *   - **Built-in**: hardcoded below (researcher, reviewer, tester).
+ *   - **Project**: `<workspace>/.codeep/agents/<name>.md`
+ *   - **Global**:  `~/.codeep/agents/<name>.md`
+ * Project shadows global shadows built-in, by name.
+ *
+ * File format — YAML-ish frontmatter + Markdown body (the role prompt):
+ *   ```
+ *   ---
+ *   name: reviewer
+ *   description: Reviews a diff for correctness & security
+ *   tools: [read_file, search_code, execute_command]   # allowlist; omit = all
+ *   model: glm-5.1            # optional provider/model or model override
+ *   personality: security     # optional — reuse a personality preset
+ *   maxIterations: 15         # optional budget
+ *   ---
+ *   You are a senior reviewer. Find correctness & security issues…
+ *   ```
+ */
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+const BUILTIN = [
+    {
+        name: 'planner',
+        displayName: 'Planner',
+        description: 'Read-only planner — investigates, then returns a concrete step-by-step implementation plan.',
+        scope: 'builtin',
+        tools: ['read_file', 'search_code', 'list_files', 'find_files'],
+        prompt: `You are a planning sub-agent. Investigate, then produce a plan — do NOT write code or run commands.
+- Read the relevant files to ground the plan in how the code actually works.
+- Return a concise, numbered, step-by-step plan: each step names the file(s) to touch and what changes.
+- Call out risks, assumptions, and anything the implementer must verify.
+- Keep it actionable — the implementer will follow it directly. No code, just the plan.`,
+    },
+    {
+        name: 'researcher',
+        displayName: 'Researcher',
+        description: 'Read-only explorer — digs through the codebase / web and returns a tight summary.',
+        scope: 'builtin',
+        tools: ['read_file', 'search_code', 'list_files', 'find_files', 'web_search', 'web_read', 'fetch_url'],
+        prompt: `You are a research sub-agent. Your job is to investigate and report — never modify anything.
+- Explore the codebase (and the web when relevant) to answer the task precisely.
+- You CANNOT write or edit files or run commands — read and search only.
+- Return a tight, structured summary: the answer first, then the specific files/lines/sources that back it up.
+- Omit dead ends. The caller only sees your final message, so make it self-contained.`,
+    },
+    {
+        name: 'reviewer',
+        displayName: 'Reviewer',
+        description: 'Read-only senior review — finds correctness, security, and design issues.',
+        scope: 'builtin',
+        tools: ['read_file', 'search_code', 'list_files', 'find_files', 'execute_command'],
+        personality: 'security',
+        prompt: `You are a senior code-review sub-agent. Review only — do not change code.
+- Read the relevant files (and run read-only git/inspection commands) to understand the change in context.
+- Report concrete issues grouped by severity: correctness/bugs, security, then design/naming/tests.
+- Cite file:line for each finding and suggest the fix in one sentence.
+- If it's solid, say so briefly — don't invent problems.`,
+    },
+    {
+        name: 'tester',
+        displayName: 'Tester',
+        description: 'Writes and runs tests for a target, then reports pass/fail.',
+        scope: 'builtin',
+        tools: ['read_file', 'write_file', 'edit_file', 'search_code', 'list_files', 'find_files', 'execute_command'],
+        prompt: `You are a testing sub-agent. Write focused tests for the target and run them.
+- Match the project's existing test framework and conventions (look at neighbouring tests first).
+- Cover the happy path plus the obvious edge cases; don't over-test.
+- Run the tests and iterate until they pass (or you've found a real bug — then report it).
+- Final message: what you added, the command to run them, and the pass/fail result.`,
+    },
+];
+/** Parse `tools: [a, b]` or `tools: a, b` out of a frontmatter line value. */
+function parseToolsValue(raw) {
+    const inner = raw.trim().replace(/^\[/, '').replace(/\]$/, '');
+    const list = inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    return list.length > 0 ? list : undefined;
+}
+/** Load custom agents from a `.codeep/agents/` directory. */
+function loadFromDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const slug = entry.slice(0, -3).toLowerCase();
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(slug))
+            continue;
+        try {
+            const raw = readFileSync(join(dir, entry), 'utf8');
+            if (raw.length > 64 * 1024)
+                continue;
+            const fm = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+            const meta = {};
+            let body = raw;
+            if (fm) {
+                body = fm[2];
+                for (const line of fm[1].split('\n')) {
+                    const m = line.match(/^([a-zA-Z]+):\s*(.*)$/);
+                    if (m)
+                        meta[m[1].toLowerCase()] = m[2].trim();
+                }
+            }
+            const displayName = meta.name || slug;
+            const description = meta.description || `Custom agent from ${entry}`;
+            const tools = meta.tools ? parseToolsValue(meta.tools) : undefined;
+            const maxIterations = meta.maxiterations ? parseInt(meta.maxiterations, 10) : undefined;
+            out.push({
+                name: slug,
+                displayName,
+                description: description.length > 200 ? description.slice(0, 197) + '…' : description,
+                prompt: body.trim(),
+                tools,
+                model: meta.model || undefined,
+                personality: meta.personality || undefined,
+                maxIterations: Number.isFinite(maxIterations) ? maxIterations : undefined,
+                scope,
+            });
+        }
+        catch {
+            // Skip broken files — never crash agent loading.
+        }
+    }
+    return out;
+}
+export function loadAgents(workspaceRoot) {
+    const project = workspaceRoot ? loadFromDir(join(workspaceRoot, '.codeep', 'agents'), 'project') : [];
+    const global = loadFromDir(join(homedir(), '.codeep', 'agents'), 'global');
+    const byName = new Map();
+    for (const a of BUILTIN)
+        byName.set(a.name, a);
+    for (const a of global)
+        byName.set(a.name, a);
+    for (const a of project)
+        byName.set(a.name, a);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findAgent(name, workspaceRoot) {
+    const lower = name.toLowerCase();
+    return loadAgents(workspaceRoot).find((a) => a.name === lower) ?? null;
+}
+/**
+ * The catalog block appended to the orchestrator's system prompt so the model
+ * knows which sub-agents it can `delegate` to. Empty string is never returned
+ * (built-ins always exist), but callers can choose not to inject it.
+ */
+export function formatAgentsForSysprompt(agents) {
+    if (agents.length === 0)
+        return '';
+    const lines = [
+        '\n\n## Sub-agents (delegation)',
+        'You can delegate a self-contained sub-task to a specialist sub-agent with the `delegate` tool. It runs in its own fresh context and returns only a summary — use it to keep your own context focused (e.g. send a researcher to explore, a reviewer to critique, a tester to write tests). Available agents:',
+        '',
+    ];
+    for (const a of agents)
+        lines.push(`- \`${a.name}\` — ${a.description}`);
+    lines.push('', 'Call `delegate({ "agent": "<name>", "task": "<clear, self-contained instruction>" })`. Omit `agent` for a general-purpose sub-agent. Do the work yourself for small/quick tasks — delegation has overhead.');
+    return lines.join('\n');
+}
+/** `/agents` list view (mirrors formatPersonalityList). */
+export function formatAgentList(workspaceRoot) {
+    const list = loadAgents(workspaceRoot);
+    const lines = ['## Sub-agents', '', 'The agent can `delegate` self-contained sub-tasks to these. Each runs in its own context and returns a summary.', '', '| Name | Scope | Tools | Description |', '|---|---|---|---|'];
+    for (const a of list) {
+        const tag = a.scope === 'builtin' ? 'built-in' : a.scope;
+        const tools = a.tools ? `${a.tools.length} scoped` : 'all';
+        lines.push(`| \`${a.name}\` | ${tag} | ${tools} | ${a.description} |`);
+    }
+    lines.push('', 'Add your own: drop a `<name>.md` with frontmatter (name, description, tools, model, personality) in `.codeep/agents/` (project) or `~/.codeep/agents/` (global).');
+    return lines.join('\n');
+}