@nexrall/code-core 1.4.23 → 1.4.25

package/dist/agent/agentTypes.d.ts

@@ -8,10 +8,74 @@ export interface AgentType {
     /** System instructions (the markdown body below the frontmatter). */
     prompt: string;
     source: 'project' | 'global' | 'builtin' | 'plugin';
+    /**
+     * When true, this agent's write tools may only target TEST files.
+     *
+     * Needed because a tool allowlist is all-or-nothing per tool: granting
+     * `edit_file` grants it for every path. The `test-writer` agent must be able to
+     * write tests while being unable to "fix" production source to make a test
+     * pass — the single most common way a test-writing agent destroys signal — and
+     * a prompt instruction alone cannot guarantee that. Enforced in loop.ts's
+     * permission gate, where it is a real refusal rather than a request.
+     */
+    testFilesOnly?: boolean;
 }
-/** Discover all custom agent types (project overrides global overrides builtin). */
+/**
+ * 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.
+ *
+ * Results are returned in a STABLE order (builtins in declared order, then
+ * user-supplied ones alphabetically) rather than in discovery order. The
+ * system-prompt catalogue is built from this, and a set that reshuffles between
+ * runs would silently bust the prompt cache on the block it lives in — filesystem
+ * readdir order is not guaranteed to be stable across machines or platforms.
+ */
 export declare function loadAgentTypes(workDir: string): AgentType[];
-/** A compact catalogue injected into the system prompt so the model can pick a type. */
+/**
+ * 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.
+ *
+ * Reports each agent's CAPABILITY CLASS rather than enumerating its allowlist.
+ * The full lists (~15 tool names each) went into every single request while
+ * telling the model nothing it needs in order to choose: what matters when
+ * delegating is "can this one edit files?" and "what is it for?", not whether
+ * `get_hover` happens to be included. With six builtins the verbatim lists cost
+ * ~670 tokens per request, most of it near-identical boilerplate that also
+ * weakens the signal it was meant to carry.
+ *
+ * The per-agent description already states its own restrictions in prose, and the
+ * allowlist is enforced at the permission gate regardless of what is advertised
+ * here — so this is purely a summary, never the mechanism.
+ */
 export declare function summariseAgents(types: AgentType[]): string;
 export declare function findAgentType(types: AgentType[], name: string | undefined): AgentType | undefined;
 //# sourceMappingURL=agentTypes.d.ts.map

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;CACrD;AAoFD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAS3D;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAQ1D;AAED,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"));
@@ -43,11 +46,58 @@ const index_1 = require("../plugins/index");
 // ── Built-in agent types ──────────────────────────────────────────────────────
 // Shipped defaults; lowest precedence (project > global > builtin), so a user
 // can override any of them with a same-name .nexrall/agents/<name>.md file.
+// Shared read-only tool set.
+//
+// An allowlist only ever GRANTS — a name that doesn't exist on the current client
+// is simply never offered to the model, so listing the VS Code language-server
+// tools alongside the CLI ones is safe and gives each agent the best available
+// 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
+// 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 = [
+    // 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.
+ *
+ * `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 = [
     {
         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_file', 'search_files', 'glob', 'list_directory', 'bash', 'get_symbols', 'get_workspace_symbols', 'find_references', 'go_to_definition', 'get_diagnostics'],
+        tools: READ_ONLY_TOOLS,
         source: 'builtin',
         prompt: [
             'You are a meticulous senior code reviewer. You NEVER modify files — you only read, search, and report.',
@@ -64,23 +114,209 @@ const BUILTIN_AGENTS = [
             '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,
+        model: 'pro',
+        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
+    // frontier model, and this is the agent most likely to be spawned in bulk.
+    {
+        name: 'explorer',
+        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,
+        model: 'turbo',
+        source: 'builtin',
+        prompt: [
+            'You map code. You NEVER modify anything.',
+            '',
+            'Method:',
+            '1. Prefer structural search over text search where available (get_workspace_symbols, find_references,',
+            '   go_to_definition); fall back to search_files/glob otherwise.',
+            '2. Read only the sections you need — use read_file with offset/limit on large files instead of',
+            '   pulling in thousands of lines.',
+            '3. Follow the real call graph rather than guessing from names.',
+            '',
+            'Your ONLY output is a compact report: the file:line locations that matter, how they relate, and the',
+            'direct answer to the question you were given. This exists to keep bulk search OUT of the parent\'s',
+            'context, so do not paste large file contents back — cite locations and summarise. Say plainly when',
+            'something does not exist; a confident wrong answer is far worse than "not found".',
+        ].join('\n'),
+    },
+    // Matches Claude Code's built-in `Plan`: research a change and return a
+    // strategy, deliberately WITHOUT write access so "make a plan" can never
+    // quietly become "start editing".
+    {
+        name: 'planner',
+        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,
+        model: 'pro',
+        source: 'builtin',
+        prompt: [
+            'You produce implementation plans. You NEVER modify files — planning and doing are separate steps,',
+            'and this agent exists so "plan it" cannot silently turn into "change it".',
+            '',
+            'Method:',
+            '1. Read the actual code before proposing anything. No plan may rest on an assumed API shape.',
+            '2. Find every affected call site (find_references / search_files) and list them.',
+            '3. Order the steps so the tree stays working after each one — types, then implementation, then',
+            '   tests, then exports/registration.',
+            '',
+            'Output:',
+            '- Goal, in one sentence.',
+            '- Numbered steps, each with the exact files touched and what changes in them.',
+            '- Risks + the specific thing that could break, and how it would be detected.',
+            '- How to verify (the exact test/build command for THIS project, taken from package.json/Makefile).',
+            '- 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,
+        model: 'pro',
+        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.
+ *
+ * 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();
     return s === 'turbo' || s === 'pro' || s === 'ultra' ? s : undefined;
 }
+/** Parse a frontmatter boolean, accepting the usual truthy spellings. */
+function parseBool(v) {
+    return /^(true|yes|1|on)$/i.test((v ?? '').trim());
+}
 function parseToolList(v) {
     if (!v)
         return undefined;
@@ -91,62 +327,210 @@ 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,
+            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 } : {}),
+        });
     }
 }
-/** Discover all custom agent types (project overrides global overrides builtin). */
+/**
+ * Discover all agent types. Precedence: project > global > plugin > builtin.
+ *
+ * Results are returned in a STABLE order (builtins in declared order, then
+ * user-supplied ones alphabetically) rather than in discovery order. The
+ * system-prompt catalogue is built from this, and a set that reshuffles between
+ * runs would silently bust the prompt cache on the block it lives in — filesystem
+ * 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);
     }
-    return [...out.values()];
+    // 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]));
+    const types = [...out.values()].sort((a, b) => {
+        const ai = builtinOrder.get(a.name);
+        const bi = builtinOrder.get(b.name);
+        if (ai !== undefined && bi !== undefined)
+            return ai - bi;
+        if (ai !== undefined)
+            return -1;
+        if (bi !== undefined)
+            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;
 }
-/** A compact catalogue injected into the system prompt so the model can pick a type. */
+/**
+ * One line per agent for the system prompt's <available_subagents> block.
+ *
+ * Reports each agent's CAPABILITY CLASS rather than enumerating its allowlist.
+ * The full lists (~15 tool names each) went into every single request while
+ * telling the model nothing it needs in order to choose: what matters when
+ * delegating is "can this one edit files?" and "what is it for?", not whether
+ * `get_hover` happens to be included. With six builtins the verbatim lists cost
+ * ~670 tokens per request, most of it near-identical boilerplate that also
+ * weakens the signal it was meant to carry.
+ *
+ * The per-agent description already states its own restrictions in prose, and the
+ * allowlist is enforced at the permission gate regardless of what is advertised
+ * here — so this is purely a summary, never the mechanism.
+ */
 function summariseAgents(types) {
     if (!types.length)
         return '';
     return types
         .map((t) => {
-        const tools = t.tools ? ` (tools: ${t.tools.join(', ')})` : '';
-        return `- ${t.name}: ${t.description}${tools}`;
+        const canWrite = !t.tools || t.tools.some((x) => WRITE_TOOL_HINTS.has(x));
+        const access = t.testFilesOnly
+            ? 'writes TEST files only'
+            : canWrite ? 'can modify files' : 'read-only';
+        const model = t.model ? `, ${t.model} model` : '';
+        return `- ${t.name} (${access}${model}): ${t.description}`;
     })
         .join('\n');
 }
+/** Tool names that imply write access, for the summary line above. */
+const WRITE_TOOL_HINTS = new Set([
+    'write_file', 'edit_file', 'multi_edit', 'notebook_edit',
+    'delete_file', 'move_file', 'copy_file',
+]);
 function findAgentType(types, name) {
     if (!name)
         return undefined;

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.
  *
@@ -47,6 +61,26 @@ export declare function compactionThresholds(): {
 export declare function estimateBodyBytes(messages: Message[]): number;
 /** Tools that mutate the filesystem — used by the verification nudge (GAP D). */
 export declare const WRITE_TOOL_NAMES: Set<string>;
+/**
+ * May an agent restricted to `testFilesOnly` perform this tool call?
+ *
+ * A tool allowlist is all-or-nothing per tool: granting `edit_file` grants it for
+ * every path in the repo. The `test-writer` agent needs write access to produce
+ * tests, but must NOT be able to "fix" production source so a failing test goes
+ * green — the single most common way a test-writing agent destroys the signal it
+ * was asked to create. Its prompt says so; this makes it a refusal rather than a
+ * request.
+ *
+ * Pure + exported so the rules are testable directly, without running a real
+ * sub-agent.
+ *
+ * KNOWN LIMIT, stated rather than hidden: this gates the file TOOLS, not `bash`.
+ * A determined model could still write source via `bash: echo ... > src/x.ts`.
+ * Closing that means parsing shell redirection, which is not reliably doable — so
+ * this is a strong guardrail against the realistic failure mode, not a sandbox.
+ * Real isolation is the sandbox config (tools/sandbox.ts), a separate mechanism.
+ */
+export declare function allowsTestOnlyWrite(tool: string, input: Record<string, unknown> | undefined): boolean;
 /** Heuristic: does a bash command look like it's running tests/build/lint/typecheck? (GAP D) */
 export declare const VERIFY_CMD_RE: RegExp;
 /**