@nexrall/code-core 1.4.24 → 1.4.26

package/dist/agent/agentRegistry.d.ts

@@ -0,0 +1,45 @@
+import type { Message } from '../types';
+export interface StoredAgent {
+    id: string;
+    /**
+     * The agent type this ran as, or null for an unnamed (general-purpose) run.
+     *
+     * Stored so resumption can be re-authorised against the CURRENT permission
+     * rules. Without it, an id would be a permanent bypass of any deny rule added
+     * after the agent first ran.
+     */
+    agentName: string | null;
+    /** Full conversation: the sub-agent's own user/assistant/tool messages. */
+    messages: Message[];
+    /** The description shown in the UI, for `/agents --resumable` style listings. */
+    description: string;
+    createdAt: number;
+    updatedAt: number;
+    /**
+     * Monotonic touch counter, used for ordering instead of `updatedAt`.
+     *
+     * Date.now() has millisecond resolution and these operations take
+     * microseconds, so two agents touched in the same tick compare EQUAL and a
+     * stable sort silently falls back to insertion order — i.e. "most recent"
+     * would have been wrong exactly when several things happen at once, which is
+     * the normal case for parallel sub-tasks. The timestamps are kept because
+     * they are meaningful to humans; the ordering does not depend on them.
+     */
+    seq: number;
+    /** Rough JSON size, cached so the byte cap doesn't re-serialise on every write. */
+    bytes: number;
+}
+/** Store a finished sub-agent's transcript. Returns its resumable id. */
+export declare function rememberAgent(agentName: string | null, description: string, messages: Message[]): string;
+/** Append a resumed run's new messages to an existing agent. */
+export declare function updateAgent(id: string, messages: Message[]): void;
+export declare function getAgent(id: string): StoredAgent | undefined;
+/** Newest first — the order a "which agents can I resume?" list wants. */
+export declare function listAgents(): StoredAgent[];
+/** Test seam. Not exported through index.ts's public surface by intent. */
+export declare function _resetAgentRegistry(): void;
+export declare const _limits: {
+    MAX_AGENTS: number;
+    MAX_TOTAL_BYTES: number;
+};
+//# sourceMappingURL=agentRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agentRegistry.d.ts","sourceRoot":"","sources":["../../src/agent/agentRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AA8CxC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;CACf;AA4CD,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,OAAO,EAAE,GAClB,MAAM,CAeR;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAYjE;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE5D;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,IAAI,WAAW,EAAE,CAE1C;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAED,eAAO,MAAM,OAAO;;;CAAkC,CAAC"}

package/dist/agent/agentRegistry.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._limits = void 0;
+exports.rememberAgent = rememberAgent;
+exports.updateAgent = updateAgent;
+exports.getAgent = getAgent;
+exports.listAgents = listAgents;
+exports._resetAgentRegistry = _resetAgentRegistry;
+// ─── Resumable sub-agents ────────────────────────────────────────────────────
+//
+// A sub-agent normally starts with a blank slate: fresh context, no memory of a
+// previous run. That is the whole point for one-shot research — but it makes
+// follow-up work absurdly expensive. "Now also check the auth path" re-reads
+// every file the last run already read, because the only way to add to a
+// finished sub-task is to describe the whole job again from scratch.
+//
+// This registry keeps a completed sub-agent's transcript in memory so a later
+// `task` call can continue it instead of restarting it. Claude Code does the
+// same thing; the design decisions worth writing down are the ones about what
+// NOT to do:
+//
+//   • IN-MEMORY, process-lifetime only. Deliberately not written to disk. A
+//     transcript is unredacted tool output — file contents, command output,
+//     whatever a repo happens to contain. Persisting it would create a new
+//     durable copy of material the user never asked us to store, in a new place
+//     they would have to know to clean up. Losing resumability when the process
+//     exits is a much smaller cost than that.
+//
+//   • BOUNDED, by entries and by bytes. A transcript is the largest object this
+//     process handles, and an agent loop that spawns sub-agents in a cycle would
+//     otherwise grow the heap until the CLI dies — a leak that shows up only in
+//     the longest sessions, i.e. the ones where losing work hurts most.
+//
+//   • Resumption re-checks permission at the CALL SITE, not here. An id is a
+//     capability: if a rule denies `task(explorer)` after an explorer agent has
+//     already run, resuming by id must not hand that agent back. This module
+//     therefore stores the agent's NAME alongside its history, so the caller can
+//     re-evaluate the current rules against it. See runSubTask.
+/** Max resumable agents kept alive. Oldest is evicted first. */
+const MAX_AGENTS = 20;
+/**
+ * Max total transcript bytes across all stored agents (~8 MB of JSON).
+ *
+ * Sized to comfortably hold a handful of long research runs while staying far
+ * below the point where it competes with the model context for memory. Eviction
+ * is by age, not by size, so one enormous transcript cannot pin out many small
+ * useful ones.
+ */
+const MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+/**
+ * Insertion-ordered store. A Map is enough: Maps iterate in insertion order, so
+ * "oldest" is simply the first key, and re-inserting on update moves an entry to
+ * the back — giving LRU-by-touch for free without a second data structure.
+ */
+const _agents = new Map();
+let _counter = 0;
+let _seq = 0;
+function totalBytes() {
+    let n = 0;
+    for (const a of _agents.values())
+        n += a.bytes;
+    return n;
+}
+function evictUntilWithinLimits() {
+    while (_agents.size > MAX_AGENTS) {
+        const oldest = _agents.keys().next().value;
+        if (oldest === undefined)
+            break;
+        _agents.delete(oldest);
+    }
+    // Byte cap is checked second: an entry that is individually enormous should
+    // still be storable (it is the most expensive thing to recompute), but it
+    // must not drag the total past the cap alongside its neighbours.
+    while (totalBytes() > MAX_TOTAL_BYTES && _agents.size > 1) {
+        const oldest = _agents.keys().next().value;
+        if (oldest === undefined)
+            break;
+        _agents.delete(oldest);
+    }
+}
+function sizeOf(messages) {
+    try {
+        return JSON.stringify(messages).length;
+    }
+    catch {
+        // A transcript that cannot be serialised (cycles shouldn't happen, but a
+        // crash here would take down a completed sub-task's result) is treated as
+        // large so it gets evicted early rather than silently counted as free.
+        return MAX_TOTAL_BYTES;
+    }
+}
+/** Store a finished sub-agent's transcript. Returns its resumable id. */
+function rememberAgent(agentName, description, messages) {
+    const id = `agent_${++_counter}`;
+    const now = Date.now();
+    _agents.set(id, {
+        id,
+        agentName,
+        description,
+        messages,
+        createdAt: now,
+        updatedAt: now,
+        seq: ++_seq,
+        bytes: sizeOf(messages),
+    });
+    evictUntilWithinLimits();
+    return id;
+}
+/** Append a resumed run's new messages to an existing agent. */
+function updateAgent(id, messages) {
+    const existing = _agents.get(id);
+    if (!existing)
+        return;
+    existing.messages = messages;
+    existing.updatedAt = Date.now();
+    existing.seq = ++_seq;
+    existing.bytes = sizeOf(messages);
+    // Re-insert so this becomes the most recently used entry, protecting an
+    // actively-continued agent from being evicted by a burst of new one-shots.
+    _agents.delete(id);
+    _agents.set(id, existing);
+    evictUntilWithinLimits();
+}
+function getAgent(id) {
+    return _agents.get(id);
+}
+/** Newest first — the order a "which agents can I resume?" list wants. */
+function listAgents() {
+    return [..._agents.values()].sort((a, b) => b.seq - a.seq);
+}
+/** Test seam. Not exported through index.ts's public surface by intent. */
+function _resetAgentRegistry() {
+    _agents.clear();
+    _counter = 0;
+    _seq = 0;
+}
+exports._limits = { MAX_AGENTS, MAX_TOTAL_BYTES };
+//# sourceMappingURL=agentRegistry.js.map

package/dist/agent/agentTypes.d.ts

@@ -20,6 +20,20 @@ export interface AgentType {
      */
     testFilesOnly?: boolean;
 }
+/**
+ * A problem found while loading an agent definition.
+ *
+ * These used to be silently swallowed. Every one of them changed what an agent
+ * could DO — a mistyped tool name removed a capability, a missing frontmatter
+ * block removed the allowlist entirely — and the user was told nothing.
+ */
+export interface AgentWarning {
+    /** Absolute path of the definition file the problem was found in. */
+    file: string;
+    /** Agent name, when one could be determined. */
+    agent: string;
+    message: string;
+}
 /**
  * Discover all agent types. Precedence: project > global > plugin > builtin.
  *
@@ -30,6 +44,23 @@ export interface AgentType {
  * readdir order is not guaranteed to be stable across machines or platforms.
  */
 export declare function loadAgentTypes(workDir: string): AgentType[];
+/**
+ * As `loadAgentTypes`, but also reports what was wrong with the definitions.
+ *
+ * Split in two so the common caller stays a one-liner while the CLI's `/agents`
+ * and the agent loop can surface problems. Warnings never hide an agent: a
+ * flawed definition still loads (fail-closed on PERMISSIONS, not on existence),
+ * because making a user's agent vanish over a typo is its own kind of silent
+ * failure.
+ */
+export declare function loadAgentTypesWithWarnings(workDir: string): {
+    types: AgentType[];
+    warnings: AgentWarning[];
+};
+/** The tool names a hand-written allowlist may use (exported for validation + tests). */
+export declare function knownToolNames(): string[];
+/** The built-in agents, for clients that want to show them alongside user-defined ones. */
+export declare function builtinAgents(): AgentType[];
 /**
  * One line per agent for the system prompt's <available_subagents> block.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA4RD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAmB3D;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAY1D;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}
+{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA6QD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AA0JD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAqB5G;AAED,yFAAyF;AACzF,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAE3C;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAY1D;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}

package/dist/agent/agentTypes.js

@@ -34,6 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadAgentTypes = loadAgentTypes;
+exports.loadAgentTypesWithWarnings = loadAgentTypesWithWarnings;
+exports.knownToolNames = knownToolNames;
+exports.builtinAgents = builtinAgents;
 exports.summariseAgents = summariseAgents;
 exports.findAgentType = findAgentType;
 const fs = __importStar(require("fs"));
@@ -57,17 +60,38 @@ const index_1 = require("../plugins/index");
 const READ_ONLY_TOOLS = [
     // Universal
     'read_file', 'search_files', 'glob', 'list_directory', 'bash', 'bash_output',
+    // kill_shell belongs next to bash_output: an agent that can start a background
+    // process and poll it but never stop it leaks that process past its own
+    // lifetime. Stopping a shell you started is not a write to the repo.
+    'kill_shell',
     'notebook_read', 'todo_write', 'todo_read',
+    // Skills are reusable prompt playbooks, and loop.ts advertises the skills
+    // catalogue to sub-agents at EVERY depth — so withholding the tool that loads
+    // one meant showing every sub-agent a menu it could not order from.
+    'use_skill',
     // VS Code language server (ignored on the CLI)
     'get_symbols', 'get_workspace_symbols', 'find_references', 'go_to_definition',
     'get_hover', 'get_diagnostics',
 ];
-/** Read-only + the network, for agents that must consult external sources. */
-const RESEARCH_TOOLS = [...READ_ONLY_TOOLS, 'web_search', 'fetch_url'];
+/**
+ * Read-only + the network, for agents that must consult external sources.
+ *
+ * `web_search` is deliberately ABSENT despite the name of this list. It is a
+ * SERVER-SIDE tool: Anthropic executes it and returns the result inside the same
+ * assistant message, so loop.ts filters those blocks out before the permission
+ * gate ever runs. Listing it here would be theatre — it grants nothing (agents
+ * 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',
 ];
 const BUILTIN_AGENTS = [
     {
@@ -247,17 +271,43 @@ const BUILTIN_AGENTS = [
         ].join('\n'),
     },
 ];
+/**
+ * Every tool name a client may offer, for validating a hand-written allowlist.
+ *
+ * Deliberately a SEPARATE list rather than an import from tools/executor.ts:
+ * that module's TOOL_MAP is the CLI's local dispatch table and legitimately
+ * lacks `get_diagnostics` (intercepted by VS Code before the executor) and
+ * `web_search` (run server-side by Anthropic). Validating against it would
+ * reject two perfectly valid names. A canary test asserts every name used by the
+ * builtin agents appears here, so the two cannot drift apart unnoticed.
+ */
+const KNOWN_TOOL_NAMES = new Set([
+    'read_file', 'write_file', 'edit_file', 'multi_edit', 'list_directory', 'create_directory',
+    'move_file', 'copy_file', 'delete_file', 'search_files', 'glob',
+    'bash', 'bash_output', 'kill_shell',
+    'notebook_read', 'notebook_edit',
+    'todo_write', 'todo_read', 'memory_write', 'memory_read', 'use_skill',
+    'fetch_url', 'web_search', 'generate_image', 'stock_photo', 'open_in_browser',
+    'task',
+    'get_symbols', 'get_workspace_symbols', 'find_references', 'go_to_definition',
+    'get_hover', 'get_diagnostics',
+]);
+/** Frontmatter keys this parser understands, for typo detection. */
+const KNOWN_META_KEYS = new Set([
+    'name', 'description', 'tools', 'model', 'test_files_only', 'testfilesonly',
+]);
+const VALID_MODELS = ['turbo', 'pro', 'ultra'];
 function parseFrontmatter(raw) {
     const m = /^\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
     if (!m)
-        return { meta: {}, body: raw.trim() };
+        return { meta: {}, body: raw.trim(), ok: false };
     const meta = {};
     for (const line of m[1].split(/\r?\n/)) {
         const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim());
         if (kv)
             meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
     }
-    return { meta, body: (m[2] ?? '').trim() };
+    return { meta, body: (m[2] ?? '').trim(), ok: true };
 }
 function parseModel(v) {
     const s = (v ?? '').toLowerCase();
@@ -277,41 +327,118 @@ function parseToolList(v) {
         .filter(Boolean);
     return tools.length ? tools : undefined;
 }
-function loadDir(dir, source, into) {
+function loadDir(dir, source, into, warnings) {
     let entries;
     try {
-        entries = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+        entries = fs.readdirSync(dir, { withFileTypes: true });
     }
     catch {
+        // Overwhelmingly "no .nexrall/agents here", which is the normal case and not
+        // worth a word. A genuine permission error is rare enough that the cost of
+        // staying quiet is lower than warning on every repo that has no agents.
         return;
     }
-    for (const file of entries) {
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        // Recurse into subfolders so definitions can be organised (agents/review/…),
+        // matching Claude Code. Identity still comes only from the name field / filename.
+        if (entry.isDirectory()) {
+            loadDir(full, source, into, warnings);
+            continue;
+        }
+        if (!entry.name.endsWith('.md'))
+            continue;
+        let raw;
         try {
-            const raw = fs.readFileSync(path.join(dir, file), 'utf-8');
-            const { meta, body } = parseFrontmatter(raw);
-            const name = (meta.name || path.basename(file, '.md')).trim();
-            if (!name)
-                continue;
-            // Earlier tiers win (project > global > plugin).
-            if (source !== 'project' && into.has(name))
-                continue;
-            into.set(name, {
-                name,
-                description: meta.description || `Custom ${name} agent`,
-                tools: parseToolList(meta.tools),
-                model: parseModel(meta.model),
-                prompt: body,
-                source,
-                // Exposed to user/plugin definitions too — `test_files_only: true` (or
-                // `testFilesOnly`) lets anyone build a test-writing agent that genuinely
-                // cannot touch production source, rather than only the builtin getting
-                // that guarantee.
-                ...(parseBool(meta.test_files_only ?? meta.testfilesonly) ? { testFilesOnly: true } : {}),
+            raw = fs.readFileSync(full, 'utf-8');
+        }
+        catch (err) {
+            warnings.push({ file: full, agent: path.basename(entry.name, '.md'), message: `could not be read (${err.message}) — this agent was skipped` });
+            continue;
+        }
+        const { meta, body, ok } = parseFrontmatter(raw);
+        const name = (meta.name || path.basename(entry.name, '.md')).trim();
+        if (!name)
+            continue;
+        // Earlier tiers win (project > global > plugin).
+        if (source !== 'project' && into.has(name))
+            continue;
+        const tools = parseToolList(meta.tools);
+        let effectiveTools = tools;
+        // ── FAIL CLOSED on a definition we could not parse ────────────────────────
+        //
+        // A file with no `---` frontmatter block used to yield tools === undefined,
+        // which means "no allowlist" — i.e. FULL access, including write_file, bash
+        // and delete_file. So the worse the file, the more power it got: the exact
+        // inversion you do not want in a permission system. A malformed definition
+        // is now read-only, which is both the safe reading and, for anyone hand-
+        // writing an agent, almost always the intended one.
+        if (!ok) {
+            effectiveTools = READ_ONLY_TOOLS;
+            warnings.push({
+                file: full,
+                agent: name,
+                message: 'has no valid YAML frontmatter (a `---` block must be the first thing in the file), so no ' +
+                    'tool allowlist could be read. Treating it as READ-ONLY. Add frontmatter with a `tools:` line ' +
+                    'to grant more.',
             });
         }
-        catch {
-            /* skip unreadable / malformed definitions */
+        else {
+            if (!meta.description) {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: 'has no `description:` — that text is the ONLY thing the model uses to decide when to delegate to this agent, so it will rarely be picked.',
+                });
+            }
+            if (meta.model !== undefined && parseModel(meta.model) === undefined) {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: `has model: "${meta.model}", which is not valid — use one of ${VALID_MODELS.join(', ')}, or omit the line to inherit the current session's model.`,
+                });
+            }
+            // The highest-value warning of the lot. An allowlist only ever GRANTS, so a
+            // misspelled name is not an error anywhere — the tool is simply never
+            // permitted, and the model is told "Permission denied", which points it at
+            // the user rather than at the typo.
+            const unknown = (tools ?? []).filter((t) => !KNOWN_TOOL_NAMES.has(t) && !t.includes('__'));
+            if (unknown.length) {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: `lists unknown tool name(s): ${unknown.join(', ')}. An allowlist only grants, so these silently do nothing and the agent cannot use them. Tool names are lower_snake_case (read_file, search_files, glob, bash).`,
+                });
+            }
+            const strayKeys = Object.keys(meta).filter((k) => !KNOWN_META_KEYS.has(k));
+            if (strayKeys.length) {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: `has unrecognised frontmatter key(s): ${strayKeys.join(', ')} — these are ignored.`,
+                });
+            }
+            if (!body) {
+                warnings.push({
+                    file: full,
+                    agent: name,
+                    message: 'has an empty body — the text below the frontmatter IS the agent\'s system prompt, so it currently has no instructions.',
+                });
+            }
         }
+        into.set(name, {
+            name,
+            description: meta.description || `Custom ${name} agent`,
+            tools: effectiveTools,
+            model: parseModel(meta.model),
+            prompt: body,
+            source,
+            // Exposed to user/plugin definitions too — `test_files_only: true` (or
+            // `testFilesOnly`) lets anyone build a test-writing agent that genuinely
+            // cannot touch production source, rather than only the builtin getting
+            // that guarantee.
+            ...(parseBool(meta.test_files_only ?? meta.testfilesonly) ? { testFilesOnly: true } : {}),
+        });
     }
 }
 /**
@@ -324,11 +451,24 @@ function loadDir(dir, source, into) {
  * readdir order is not guaranteed to be stable across machines or platforms.
  */
 function loadAgentTypes(workDir) {
+    return loadAgentTypesWithWarnings(workDir).types;
+}
+/**
+ * As `loadAgentTypes`, but also reports what was wrong with the definitions.
+ *
+ * Split in two so the common caller stays a one-liner while the CLI's `/agents`
+ * and the agent loop can surface problems. Warnings never hide an agent: a
+ * flawed definition still loads (fail-closed on PERMISSIONS, not on existence),
+ * because making a user's agent vanish over a typo is its own kind of silent
+ * failure.
+ */
+function loadAgentTypesWithWarnings(workDir) {
     const out = new Map();
-    loadDir(path.join(workDir, '.nexrall', 'agents'), 'project', out);
-    loadDir(path.join(os.homedir(), '.nexrall', 'agents'), 'global', out);
+    const warnings = [];
+    loadDir(path.join(workDir, '.nexrall', 'agents'), 'project', out, warnings);
+    loadDir(path.join(os.homedir(), '.nexrall', 'agents'), 'global', out, warnings);
     for (const dir of (0, index_1.pluginAssetDirs)(workDir, 'agents'))
-        loadDir(dir, 'plugin', out);
+        loadDir(dir, 'plugin', out, warnings);
     for (const agent of BUILTIN_AGENTS) {
         if (!out.has(agent.name))
             out.set(agent.name, agent);
@@ -336,7 +476,7 @@ function loadAgentTypes(workDir) {
     // Builtins first in their declared order (the common, cache-friendly case), then
     // everything user-supplied alphabetically.
     const builtinOrder = new Map(BUILTIN_AGENTS.map((a, i) => [a.name, i]));
-    return [...out.values()].sort((a, b) => {
+    const types = [...out.values()].sort((a, b) => {
         const ai = builtinOrder.get(a.name);
         const bi = builtinOrder.get(b.name);
         if (ai !== undefined && bi !== undefined)
@@ -347,6 +487,15 @@ function loadAgentTypes(workDir) {
             return 1;
         return a.name.localeCompare(b.name);
     });
+    return { types, warnings };
+}
+/** The tool names a hand-written allowlist may use (exported for validation + tests). */
+function knownToolNames() {
+    return [...KNOWN_TOOL_NAMES].sort();
+}
+/** The built-in agents, for clients that want to show them alongside user-defined ones. */
+function builtinAgents() {
+    return BUILTIN_AGENTS;
 }
 /**
  * One line per agent for the system prompt's <available_subagents> block.

package/dist/agent/loop.d.ts

@@ -6,6 +6,20 @@ export declare function resolveMaxIterations(optionValue: number | undefined, se
  * dozen lines.
  */
 export declare function createLimiter(max: number): <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * Thrown by a sub-agent's permission gate when the AGENT DEFINITION forbids a
+ * tool — as opposed to the user declining it.
+ *
+ * The distinction matters to the model, which is why this is an exception rather
+ * than a `false`: both used to collapse into "Permission denied by user", so an
+ * agent blocked by its own allowlist (very often a mistyped tool name) was told
+ * the human had refused. The rational response to that is to ask again, which
+ * can never succeed. Carrying a reason lets the tool_result say what is actually
+ * true and what to do instead.
+ */
+export declare class ToolNotAllowedError extends Error {
+    constructor(message: string);
+}
 /**
  * Reduce a sub-agent's message history to the text its parent should receive.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAMP,gBAAgB,EAChB,UAAU,EACX,MAAM,UAAU,CAAC;AA2KlB,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAWR;AAkED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAgBlF;AAuJD;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AA4BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,UAAO,GAAG,MAAM,CAYjF;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAc,GAAG,MAAM,CAKtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAoBpE;AAkTD,oGAAoG;AACpG,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAE1E;AA8BD,kHAAkH;AAClH,wBAAgB,oBAAoB,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAEzE;AAuBD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAM7D;AAsBD,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,aAA+G,CAAC;AAC7I;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,OAAO,CA8BrG;AAED,gGAAgG;AAChG,eAAO,MAAM,aAAa,QAA2J,CAAC;AAEtL;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK5E;AAUD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAwBxD;AAoBD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,qFAAqF;IACrF,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,EAAE,EAAE,OAAO,EACX,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAoDN;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA6B5D;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,eAAe,SAAI,GAAG,MAAM,CAgCpF;AAsKD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,GACA,OAAO,CAAC,OAAO,CAAC,CAqElB;AAID,wBAAsB,YAAY,CAChC,eAAe,EAAE,OAAO,EAAE,EAC1B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC,CAgxBpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAqCtE"}