@nexrall/code-core 1.4.63 → 1.4.66

package/dist/agent/agentTypes.js

@@ -34,13 +34,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MODEL_TIER_ALIASES = exports.VALID_MODELS = void 0;
+exports.normaliseToolName = normaliseToolName;
 exports.parseModel = parseModel;
+exports.parseAgentHooks = parseAgentHooks;
 exports.loadAgentTypes = loadAgentTypes;
 exports.loadAgentTypesWithWarnings = loadAgentTypesWithWarnings;
 exports.knownToolNames = knownToolNames;
 exports.builtinAgents = builtinAgents;
 exports.summariseAgents = summariseAgents;
 exports.findAgentType = findAgentType;
+const miniYaml_1 = require("../util/miniYaml");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -62,7 +65,7 @@ function parseMemoryScope(v) {
 // capability on whichever client it runs.
 //
 // This exists because it was previously inlined per agent, and the one agent that
-// had it (`reviewer`) listed five VS Code-only tools, leaving it with just five
+// had it listed five VS Code-only tools, leaving that agent with just five
 // usable tools when run from the CLI — a silent capability gap that is very easy
 // to reintroduce by copy-pasting a list.
 const READ_ONLY_TOOLS = [
@@ -79,7 +82,7 @@ const READ_ONLY_TOOLS = [
     // edit Z directly" does better work, and withholding it meant every sub-agent
     // rediscovered project conventions from scratch. Writing is a different thing
     // entirely — memory is durable, cross-session, SHARED state, while sub-agents run
-    // up to 4-wide in parallel with their reasoning hidden from the user. A wrong fact
+    // up to 10-wide (configurable) in parallel with their reasoning hidden from the user. A wrong fact
     // written there is invisible and permanent, and it competes for a capped, shared
     // budget that gets periodically condensed.
     //
@@ -107,19 +110,9 @@ const READ_ONLY_TOOLS = [
  * without it can still search) and denies nothing. Naming the absence is the
  * only way to stop it being "helpfully" re-added.
  */
-const RESEARCH_TOOLS = [...READ_ONLY_TOOLS, 'fetch_url'];
-/** Read-only + the write tools, for agents that produce code. */
-const WRITE_TOOLS = [
-    ...READ_ONLY_TOOLS,
-    'write_file', 'edit_file', 'multi_edit', 'create_directory', 'move_file', 'copy_file',
-    // notebook_edit is a write tool like any other, and allowsTestOnlyWrite already
-    // knows its shape (`source` is cell CONTENT, not a path). Omitting it just meant
-    // test-writer silently could not touch notebooks.
-    'notebook_edit',
-    // Office document generation — same write-access tier as write_file, just a
-    // structured content shape instead of raw text (see tools/executor.ts).
-    'write_docx', 'write_xlsx', 'write_pptx',
-];
+// web_search is a client-side tool now (executor.ts webSearch), so it must be granted
+// explicitly — planner was told to use it and then refused.
+const RESEARCH_TOOLS = [...READ_ONLY_TOOLS, 'fetch_url', 'web_search'];
 const BUILTIN_AGENTS = [
     {
         // The catch-all, matching Claude Code's `general-purpose`.
@@ -160,66 +153,6 @@ const BUILTIN_AGENTS = [
             '(with file paths), what you ran and its outcome, and anything you deliberately left undone.',
         source: 'builtin',
     },
-    {
-        name: 'reviewer',
-        description: 'Read-only code reviewer — finds correctness bugs, edge cases, and security issues in a diff or file set. Cannot modify files.',
-        tools: READ_ONLY_TOOLS,
-        source: 'builtin',
-        prompt: [
-            'You are a meticulous senior code reviewer. You NEVER modify files — you only read, search, and report.',
-            '',
-            'Method:',
-            '1. Read the full context around every change you are asked to review; never judge a hunk in isolation.',
-            '2. Hunt specifically for: correctness bugs, unhandled edge cases (empty/null/unicode/concurrency/timezone),',
-            '   security issues (injection, path traversal, secrets in code, unsafe deserialization), breaking API',
-            '   changes (search for callers first), silent behaviour changes, and swallowed errors.',
-            '3. Verify test coverage: are the changed paths tested? Were assertions weakened or tests deleted?',
-            '4. Only use bash for read-only commands (git diff/log/show, grep, test runs). Never run mutating commands.',
-            '',
-            'Report format: 🔴 Critical / 🟡 Warning / 🟢 Suggestion, each with file:line and a concrete fix,',
-            'then a final verdict (APPROVE or REQUEST CHANGES) with a one-paragraph rationale.',
-        ].join('\n'),
-    },
-    // Promoted from the security-audit plugin to a builtin.
-    //
-    // Leaving it plugin-only was indefensible next to `reviewer` being builtin:
-    // reviewer's own prompt already tells it to look for security issues, so
-    // security IS treated as default work — yet the specialist agent for it was
-    // invisible unless the user happened to know the plugin existed. For an agent
-    // that WRITES code, "you only get a security review if you knew to install
-    // something" is the wrong default.
-    {
-        name: 'security-auditor',
-        description: 'Read-only security auditor — hunts injection, authz, secrets, and validation flaws in a path or diff. Cannot modify files.',
-        tools: READ_ONLY_TOOLS,
-        // No `model` override — inherits the session's, same as general-purpose.
-        // A previous version forced 'pro' (Claude Opus 5) here, which silently
-        // billed Anthropic even for a session running entirely on OpenAI/DeepSeek/
-        // Qwen. Consistency with the main conversation's provider matters more
-        // than defaulting every specialist to a fixed tier.
-        source: 'builtin',
-        prompt: [
-            'You are a security auditor. You find real, exploitable flaws — not style issues.',
-            '',
-            'Method:',
-            '1. Map the attack surface FIRST: entry points (HTTP routes, message handlers, CLI args, file/network',
-            '   input, deserialization), then trace user-controlled data inward to where it is used.',
-            '2. For each finding: file:line, the flaw class, a one-line exploit scenario, and the concrete fix.',
-            '3. Grade severity honestly: Critical = remote compromise or data breach; High = auth bypass/IDOR;',
-            '   Medium = needs unusual preconditions; Low = hardening.',
-            '',
-            'Classes worth the most attention, in order: injection (SQL/command/template/prototype), broken',
-            'authz (missing ownership checks, IDOR, trusting client-supplied ids), secrets committed to source,',
-            'path traversal, SSRF, unsafe deserialization, missing rate limits on expensive or auth endpoints,',
-            'and crypto misuse (hand-rolled comparison, predictable randomness).',
-            '',
-            'Hard rules:',
-            '- READ-ONLY: never modify, create or delete files. bash only for read-only inspection.',
-            '- NEVER print a discovered secret\'s value. Report its location and advise rotation.',
-            '- Distinguish EXPLOITABLE from theoretical, and say which one each finding is.',
-            '- "No issues found in scope X" is a valid, useful result. Do not pad the report to look thorough.',
-        ].join('\n'),
-    },
     // The gap Claude Code fills with its built-in `Explore`: read-heavy codebase
     // search that would otherwise flood the parent's context. Defaults to the
     // cheapest model on purpose — "find every caller of X" has no need of a
@@ -231,10 +164,13 @@ const BUILTIN_AGENTS = [
         lightPrompt: true,
         description: 'Fast read-only codebase explorer — locates files, symbols, and call sites and reports concise findings. Use to keep bulk searching out of the main context. Cannot modify files.',
         tools: READ_ONLY_TOOLS,
-        // No `model` override — inherits the session's. A previous version forced
-        // 'turbo' (Claude Sonnet 5) on the theory that bulk search doesn't need a
-        // frontier model, but that silently billed Anthropic regardless of which
-        // provider the user actually selected for the conversation.
+        // The cheapest model of the SESSION'S OWN provider (Opus → Sonnet, GPT-6 Sol →
+        // Luna), like Claude Code's Explore on Haiku. A previous version forced 'turbo'
+        // (Claude Sonnet 5), which billed Anthropic even for DeepSeek/OpenAI sessions;
+        // 'cheapest' never leaves the provider and falls back to inheriting.
+        model: 'cheapest',
+        // Search-and-report needs breadth, not deep reasoning (Claude Code's Explore runs fast).
+        effort: 'low',
         source: 'builtin',
         prompt: [
             'You map code. You NEVER modify anything.',
@@ -257,10 +193,14 @@ const BUILTIN_AGENTS = [
     // quietly become "start editing".
     {
         name: 'planner',
+        // Lean prompt, as Claude Code's Plan builtin: it researches and reports, and the MAIN
+        // agent (which has nexrall.md and the conversation) judges the plan against project
+        // rules. Conventions that must bind the plan belong in the delegation prompt.
+        lightPrompt: true,
         description: 'Read-only planning agent — researches a change and returns a concrete step-by-step implementation plan with risks and affected files. Cannot modify files.',
         tools: RESEARCH_TOOLS,
         // No `model` override — inherits the session's, for the same reason as
-        // explorer/security-auditor above: a fixed alias silently billed Anthropic
+        // explorer above: a fixed alias silently billed Anthropic
         // regardless of the user's chosen provider.
         source: 'builtin',
         prompt: [
@@ -281,74 +221,6 @@ const BUILTIN_AGENTS = [
             '- Anything genuinely ambiguous, stated as an open question rather than a silent assumption.',
         ].join('\n'),
     },
-    // Promoted from the test-gen plugin. Needs write access — it produces test
-    // files — but is deliberately forbidden from touching source, because "make the
-    // tests pass" is the single most common way an agent destroys signal.
-    {
-        name: 'test-writer',
-        description: 'Writes tests that follow the project\'s existing conventions. May create/edit TEST files only — never production source.',
-        tools: WRITE_TOOLS,
-        // Enforced, not merely requested: the permission gate refuses a write whose
-        // path is not a test file. Without this the allowlist would grant edit_file
-        // for every path and the rule below would be a suggestion the model is free
-        // to rationalise its way past.
-        testFilesOnly: true,
-        source: 'builtin',
-        prompt: [
-            'You write tests. You may create and edit TEST files only.',
-            '',
-            'Hard rules — these are the ways test-writing agents destroy value, so they are non-negotiable:',
-            '- NEVER modify production source to make a test pass. If the code looks wrong, REPORT it and stop.',
-            '- NEVER weaken, delete or skip an existing assertion or test.',
-            '- A test that cannot fail is worse than no test. Every test must be able to fail for one clear reason.',
-            '',
-            'Method:',
-            '1. Read the existing tests FIRST and copy their conventions exactly — runner, file naming, layout,',
-            '   assertion style, fixture/helper patterns. Never introduce a new framework.',
-            '2. Test observable behaviour and the contract, not private internals.',
-            '3. Cover the boring-but-real cases: empty input, null/undefined, unicode and non-BMP characters,',
-            '   boundaries, error paths, concurrency where it applies.',
-            '4. No sleeps or wall-clock dependence — those produce the flaky tests that get deleted later.',
-            '5. RUN the tests you wrote and report the real output. Never claim a test passes without running it.',
-        ].join('\n'),
-    },
-    // The DevOps gap — answered with a READ-ONLY advisor, not an operator.
-    //
-    // A "DevOps agent" with write/apply access is a genuinely different risk class
-    // from the others here: its mistakes are `kubectl delete`, a bad `terraform
-    // apply`, a broken deploy pipeline — often not revertible and affecting
-    // production rather than a working tree. So this one diagnoses and proposes a
-    // diff; a human applies it. That asymmetry is the whole design.
-    {
-        name: 'devops-advisor',
-        description: 'Read-only CI/CD, container, and infrastructure advisor — diagnoses pipelines, Dockerfiles, and k8s manifests and proposes concrete fixes as a diff. Never applies changes.',
-        tools: RESEARCH_TOOLS,
-        // No `model` override — inherits the session's, for the same reason as the
-        // other specialists above.
-        source: 'builtin',
-        prompt: [
-            'You are an infrastructure and delivery advisor. You DIAGNOSE and PROPOSE. You never apply changes.',
-            '',
-            'Hard rules:',
-            '- READ-ONLY, and stricter than the other read-only agents: bash is for INSPECTION only',
-            '  (git log/diff, cat, grep, `kubectl get/describe`, `docker images`, `terraform plan`).',
-            '  NEVER run anything that mutates infrastructure — no apply/delete/scale/rollout/restart/push,',
-            '  no `terraform apply`, no `helm upgrade`. If a fix needs such a command, WRITE IT OUT for a human.',
-            '- Never print secret values from env files, k8s Secrets or CI variables. Reference them by name.',
-            '',
-            'Method:',
-            '1. Read what actually exists — workflow files, Dockerfiles, manifests, kustomize overlays, the',
-            '   deploy scripts — before drawing any conclusion. Never reason from what a stack "usually" looks like.',
-            '2. Follow the real path a change takes to production, and name the step that is broken or missing.',
-            '3. Check the failure modes that bite hardest: CI path filters that skip files a workload actually',
-            '   needs, image tags that do not match what is deployed, missing health probes, absent resource',
-            '   limits, secrets baked into images, ports/timeouts inconsistent between proxy and app, and',
-            '   migrations that must run before the new image is live.',
-            '',
-            'Output: the diagnosis, the evidence (file:line or command output), the proposed change as a diff or',
-            'exact file content, and the command a human should run to apply and verify it.',
-        ].join('\n'),
-    },
 ];
 /**
  * Every tool name a client may offer, for validating a hand-written allowlist.
@@ -383,7 +255,37 @@ const KNOWN_TOOL_NAMES = new Set([
 const KNOWN_META_KEYS = new Set([
     'name', 'description', 'tools', 'model', 'test_files_only', 'testfilesonly',
     'memory',
+    // Claude Code-compatible fields (keys arrive lowercased from parseFrontmatter).
+    'disallowedtools', 'disallowed_tools', 'maxturns', 'max_turns', 'effort', 'background',
+    'isolation', 'permissionmode', 'permission_mode', 'color',
+    'skills', 'mcpservers', 'mcp_servers', 'hooks',
 ]);
+/** Claude Code fields Nexrall recognises but does not implement — warned about by name. */
+/** Claude Code fields Nexrall recognises but does not implement — warned about by name. */
+const UNSUPPORTED_CC_KEYS = new Set([]);
+const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+/**
+ * Claude Code tool names → Nexrall's, so an agent file written for Claude Code works
+ * when dropped into .nexrall/agents/ (`tools: Read, Grep, Glob` instead of a typo warning
+ * and an agent that silently cannot read). `mcp__server__tool` → `server__tool`.
+ */
+const CLAUDE_CODE_TOOL_ALIASES = {
+    read: 'read_file', write: 'write_file', edit: 'edit_file', multiedit: 'multi_edit',
+    grep: 'search_files', glob: 'glob', ls: 'list_directory', bash: 'bash',
+    bashoutput: 'bash_output', killshell: 'kill_shell', killbash: 'kill_shell',
+    webfetch: 'fetch_url', websearch: 'web_search', todowrite: 'todo_write',
+    notebookread: 'notebook_read', notebookedit: 'notebook_edit', task: 'task', agent: 'task',
+};
+function normaliseToolName(t) {
+    if (t.startsWith('mcp__'))
+        return t.slice('mcp__'.length);
+    if (/[A-Z]/.test(t)) {
+        const alias = CLAUDE_CODE_TOOL_ALIASES[t.toLowerCase()];
+        if (alias)
+            return alias;
+    }
+    return t;
+}
 // Models this build knows how to NAME. Used only for the frontmatter warning
 // below, never to reject a value — see parseModel for why an allowlist must not
 // gate what is sent.
@@ -399,7 +301,7 @@ const KNOWN_META_KEYS = new Set([
 // at all. Two independently-maintained model lists are exactly the kind of
 // drift the shared parseFrontmatter migration was meant to end.
 exports.VALID_MODELS = [
-    'claude-sonnet-5', 'claude-opus-5-5', 'claude-fable-5-1',
+    'claude-sonnet-5-5', 'claude-opus-5-5', 'claude-fable-5-1',
     'gpt-5.4', 'gpt-5.4-mini', 'gpt-4.1',
     // Legacy tier aliases — still accepted, still resolved by the backend.
     'turbo', 'pro', 'ultra', 'fast',
@@ -433,6 +335,11 @@ function parseModel(v) {
     const lower = raw.toLowerCase();
     if (exports.MODEL_TIER_ALIASES.includes(lower))
         return lower;
+    // Resolved at dispatch against the parent's model (modelCatalogue.resolveSubAgentModel).
+    if (lower === 'inherit')
+        return undefined;
+    if (lower === 'cheapest')
+        return lower;
     return raw;
 }
 /** Parse a frontmatter boolean, accepting the usual truthy spellings. */
@@ -445,9 +352,19 @@ function parseToolList(v) {
     const tools = v
         .replace(/^\[|\]$/g, '') // tolerate [a, b] style
         .split(/[,\s]+/)
-        .map((t) => t.trim())
+        .map((t) => normaliseToolName(t.trim()))
         .filter(Boolean);
-    return tools.length ? tools : undefined;
+    return tools.length ? [...new Set(tools)] : undefined;
+}
+function parseNameList(v) {
+    if (!v)
+        return undefined;
+    const names = v.replace(/^\[|\]$/g, '').split(',').map((x) => x.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+    return names.length ? [...new Set(names)] : undefined;
+}
+function parsePositiveInt(v) {
+    const n = Number((v ?? '').trim());
+    return Number.isInteger(n) && n > 0 ? n : undefined;
 }
 function loadDir(dir, source, into, warnings) {
     let entries;
@@ -487,6 +404,7 @@ function loadDir(dir, source, into, warnings) {
             continue;
         const tools = parseToolList(meta.tools);
         let effectiveTools = tools;
+        let agentHooks;
         // ── FAIL CLOSED on a definition we could not parse ────────────────────────
         //
         // A file with no `---` frontmatter block used to yield tools === undefined,
@@ -568,7 +486,44 @@ function loadDir(dir, source, into, warnings) {
                     message: 'lists `task` as its ONLY tool, so it can delegate but cannot read, write or run anything itself — it has no way to do or verify work. Add the tools it needs, or drop the `tools:` line to inherit its parent\'s.',
                 });
             }
-            const strayKeys = Object.keys(meta).filter((k) => !KNOWN_META_KEYS.has(k));
+            const unsupported = Object.keys(meta).filter((k) => UNSUPPORTED_CC_KEYS.has(k));
+            if (unsupported.length) {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: `uses Claude Code field(s) Nexrall does not support yet: ${unsupported.join(', ')} — ignored.`,
+                });
+            }
+            const pm = (meta.permissionmode ?? meta.permission_mode)?.trim();
+            if (pm && pm !== 'plan' && pm !== 'default') {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: `has permissionMode: "${pm}" — only "plan" (read-only) is honoured; a definition file cannot widen the session's permissions. Ignored.`,
+                });
+            }
+            const eff = meta.effort?.trim().toLowerCase();
+            if (eff && !VALID_EFFORTS.includes(eff)) {
+                warnings.push({ file: full, agent: name, message: `has effort: "${meta.effort}" — expected one of ${VALID_EFFORTS.join(', ')}. Ignored.` });
+            }
+            const mt = meta.maxturns ?? meta.max_turns;
+            if (mt !== undefined && parsePositiveInt(mt) === undefined) {
+                warnings.push({ file: full, agent: name, message: `has maxTurns: "${mt}" — expected a positive integer. Ignored.` });
+            }
+            const iso = meta.isolation?.trim().toLowerCase();
+            if (iso && iso !== 'worktree') {
+                warnings.push({ file: full, agent: name, message: `has isolation: "${meta.isolation}" — only "worktree" is supported. Ignored.` });
+            }
+            if (meta.hooks !== undefined) {
+                const parsed = parseAgentHooks(raw);
+                if (parsed.error) {
+                    warnings.push({ file: full, agent: name, message: `has an unusable hooks: block (${parsed.error}) — no hooks will run for this agent.` });
+                }
+                else {
+                    agentHooks = parsed.hooks;
+                }
+            }
+            const strayKeys = Object.keys(meta).filter((k) => !KNOWN_META_KEYS.has(k) && !UNSUPPORTED_CC_KEYS.has(k));
             if (strayKeys.length) {
                 warnings.push({
                     file: full,
@@ -602,8 +557,100 @@ function loadDir(dir, source, into, warnings) {
             // definition never receives a writable store — should survive parseFrontmatter
             // being changed to salvage partial metadata, which is a plausible future edit.
             ...(ok && parseMemoryScope(meta.memory) ? { memory: parseMemoryScope(meta.memory) } : {}),
+            // Claude Code-compatible fields. Every one only NARROWS or tunes the agent — none
+            // can grant a tool or relax a permission, so an unreadable file (ok=false) simply
+            // has none of them.
+            ...(ok ? parseCcFields(meta) : {}),
+            ...(ok && agentHooks ? { hooks: agentHooks } : {}),
+        });
+    }
+}
+/**
+ * Read and validate an agent file's `hooks:` block. Accepts Claude Code's shape —
+ * `{ PreToolUse|PostToolUse: [{ matcher?, hooks: [{ type: command, command, timeout? }] }],
+ *    Stop|SubagentStop: [{ hooks: [...] }] }` — with `timeout` in SECONDS (Claude Code)
+ * or `timeout_ms`. Anything else is an error, never a partial guess.
+ */
+function parseAgentHooks(raw) {
+    let v;
+    try {
+        v = (0, miniYaml_1.frontmatterBlock)(raw, 'hooks');
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+    if (v == null)
+        return {};
+    if (typeof v !== 'object' || Array.isArray(v))
+        return { error: 'expected a map of events' };
+    const defs = (list, where) => {
+        if (!Array.isArray(list))
+            throw new Error(`${where}: expected a list of hooks`);
+        return list.map((h, i) => {
+            const o = h;
+            if (!o || o.type !== 'command' || typeof o.command !== 'string' || !o.command.trim()) {
+                throw new Error(`${where}[${i}]: each hook needs type: command and a command`);
+            }
+            const ms = typeof o.timeout_ms === 'number' ? o.timeout_ms
+                : typeof o.timeout === 'number' ? o.timeout * 1000 : undefined;
+            return { type: 'command', command: o.command, ...(ms && ms > 0 ? { timeout_ms: ms } : {}) };
+        });
+    };
+    const entries = (list, ev) => {
+        if (!Array.isArray(list))
+            throw new Error(`${ev}: expected a list`);
+        return list.map((e, i) => {
+            const o = e;
+            if (!o || typeof o !== 'object')
+                throw new Error(`${ev}[${i}]: expected { matcher, hooks }`);
+            return {
+                ...(typeof o.matcher === 'string' && o.matcher ? { matcher: o.matcher } : {}),
+                hooks: defs(o.hooks, `${ev}[${i}].hooks`),
+            };
         });
+    };
+    try {
+        const out = {};
+        for (const [ev, val] of Object.entries(v)) {
+            if (ev === 'PreToolUse' || ev === 'PostToolUse')
+                out[ev] = entries(val, ev);
+            else if (ev === 'Stop' || ev === 'SubagentStop')
+                out.Stop = [...(out.Stop ?? []), ...entries(val, ev).flatMap((e) => e.hooks)];
+            else
+                throw new Error(`unsupported event "${ev}" (supported: PreToolUse, PostToolUse, Stop)`);
+        }
+        return { hooks: out };
     }
+    catch (e) {
+        return { error: e.message };
+    }
+}
+function parseCcFields(meta) {
+    const out = {};
+    const disallowed = parseToolList(meta.disallowedtools ?? meta.disallowed_tools);
+    if (disallowed)
+        out.disallowedTools = disallowed;
+    const mt = parsePositiveInt(meta.maxturns ?? meta.max_turns);
+    if (mt)
+        out.maxTurns = mt;
+    const eff = meta.effort?.trim().toLowerCase();
+    if (eff && VALID_EFFORTS.includes(eff))
+        out.effort = eff;
+    if (parseBool(meta.background))
+        out.background = true;
+    if (meta.isolation?.trim().toLowerCase() === 'worktree')
+        out.isolation = 'worktree';
+    if ((meta.permissionmode ?? meta.permission_mode)?.trim() === 'plan')
+        out.permissionMode = 'plan';
+    if (meta.color?.trim())
+        out.color = meta.color.trim();
+    const skills = parseNameList(meta.skills);
+    if (skills)
+        out.skills = skills;
+    const servers = parseNameList(meta.mcpservers ?? meta.mcp_servers);
+    if (servers)
+        out.mcpServers = servers;
+    return out;
 }
 /**
  * Discover all agent types. Precedence: project > global > plugin > builtin.
@@ -697,7 +744,7 @@ function summariseAgents(types) {
         const access = t.testFilesOnly
             ? 'writes TEST files only'
             : canWrite ? 'can modify files' : 'read-only';
-        const model = t.model ? `, ${t.model} model` : '';
+        const model = t.model === 'cheapest' ? ', fast low-cost model' : t.model ? `, ${t.model} model` : '';
         return `- ${t.name} (${access}${model}): ${t.description}`;
     })
         .join('\n');

package/dist/agent/backgroundAgents.d.ts

@@ -0,0 +1,66 @@
+import type { ToolResult } from '../types';
+export type BackgroundStatus = 'running' | 'completed' | 'failed' | 'stopped';
+export interface BackgroundAgentInfo {
+    id: string;
+    description: string;
+    agentType: string;
+    status: BackgroundStatus;
+    startedAt: number;
+    finishedAt?: number;
+    toolCalls: number;
+    lastTool?: string;
+}
+export interface BackgroundNotification {
+    id: string;
+    description: string;
+    agentType: string;
+    status: Exclude<BackgroundStatus, 'running'>;
+    durationMs: number;
+    toolCalls: number;
+    /** The sub-agent's final report (or error + salvaged partial work). */
+    text: string;
+}
+/** Hard ceiling on simultaneously running background agents per session. */
+export declare const MAX_BACKGROUND_AGENTS = 8;
+export declare class BackgroundAgentHub {
+    private readonly entries;
+    private readonly pending;
+    private readonly listeners;
+    private counter;
+    /**
+     * Start `run` detached. `run` receives this agent's own abort signal and progress
+     * hooks, and must resolve (never reject) with the sub-agent's ToolResult.
+     */
+    start(meta: {
+        description: string;
+        agentType: string;
+    }, run: (ctx: {
+        abort: {
+            aborted: boolean;
+        };
+        onToolUse: (name: string) => void;
+    }) => Promise<ToolResult>): {
+        id: string;
+    } | {
+        error: string;
+    };
+    private finish;
+    /** Running agents, oldest first. */
+    list(): BackgroundAgentInfo[];
+    runningCount(): number;
+    hasPending(): boolean;
+    /** Remove and return every undelivered completion. */
+    takeNotifications(): BackgroundNotification[];
+    /** Ask one agent to stop. Its (partial) result is still delivered as a notification. */
+    stop(id: string): boolean;
+    /** Stop everything and drop undelivered notifications (session cleared / closed). */
+    stopAll(opts?: {
+        dropPending?: boolean;
+    }): void;
+    /** Subscribe to any change (start, progress, finish, delivery). Returns an unsubscribe. */
+    onChange(cb: () => void): () => void;
+    private emit;
+}
+/** The text block a notification becomes in the model's context. */
+export declare function formatBackgroundNotifications(list: BackgroundNotification[]): string;
+//# sourceMappingURL=backgroundAgents.d.ts.map

package/dist/agent/backgroundAgents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundAgents.d.ts","sourceRoot":"","sources":["../../src/agent/backgroundAgents.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,OAAO,CAAK;IAEpB;;;OAGG;IACH,KAAK,CACH,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAChD,GAAG,EAAE,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC;QAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,UAAU,CAAC,GACpG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IA4BrC,OAAO,CAAC,MAAM;IAqBd,oCAAoC;IACpC,IAAI,IAAI,mBAAmB,EAAE;IAM7B,YAAY,IAAI,MAAM;IAMtB,UAAU,IAAI,OAAO;IAErB,sDAAsD;IACtD,iBAAiB,IAAI,sBAAsB,EAAE;IAM7C,wFAAwF;IACxF,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAOzB,qFAAqF;IACrF,OAAO,CAAC,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAMnD,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKpC,OAAO,CAAC,IAAI;CAKb;AAOD,oEAAoE;AACpE,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,MAAM,CAYpF"}