@nexrall/code-core 1.4.24 → 1.4.25

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":"AAAA,OAAO,KAAK,EACV,OAAO,EAMP,gBAAgB,EAChB,UAAU,EACX,MAAM,UAAU,CAAC;AAyKlB,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;AAiLD;;;;;;;;;;;;;;;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;AAwLD,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,CAquBpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAqCtE"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}

package/dist/agent/loop.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = void 0;
+exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = exports.ToolNotAllowedError = void 0;
 exports.resolveMaxIterations = resolveMaxIterations;
 exports.createLimiter = createLimiter;
 exports.extractSubTaskText = extractSubTaskText;
@@ -406,6 +406,24 @@ const SUBTASK_TIMEOUT_MS = Number(process.env.NEXRALL_SUBTASK_TIMEOUT_MS) > 0
 /** Cap on the text a sub-task hands back, so one verbose sub-agent can't blow up
  *  the PARENT's context in a single tool_result. */
 const SUBTASK_MAX = 48000; // chars (~12k tokens)
+/**
+ * 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.
+ */
+class ToolNotAllowedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolNotAllowedError';
+    }
+}
+exports.ToolNotAllowedError = ToolNotAllowedError;
 /**
  * Slice `s` to at most `max` UTF-16 units without splitting a surrogate pair.
  *
@@ -511,11 +529,32 @@ async function runSubTask(input, options, agentTypes) {
         return { error: 'Sub-agents cannot spawn further sub-agents. Do this work directly, or report back so the main agent can delegate it.' };
     }
     // Resolve an optional custom agent type (subagent_type).
+    //
+    // `agentTypes` is a snapshot taken once at the top of runAgentLoop, before the
+    // model said anything. That made "write .nexrall/agents/x.md, then use it"
+    // impossible within a single turn: the file existed on disk, but this lookup
+    // consulted a list captured before it was written, and the model was told the
+    // agent did not exist — which reads as "creating it failed".
+    //
+    // So on a MISS ONLY, re-read from disk before giving up. The hit path (every
+    // normal call) still costs zero syscalls, and the miss path costs ~4 mostly-
+    // ENOENT stats — against a sub-agent that is about to run for seconds to
+    // minutes. Note runAgentLoop re-reads for the sub-agent anyway, so the old
+    // behaviour was already inconsistent: fresh for the child, stale for the lookup.
     const requestedType = typeof input.subagent_type === 'string' ? input.subagent_type : '';
-    const agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
+    let agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
+    let knownTypes = agentTypes;
     if (requestedType && !agent) {
-        const known = agentTypes.map((a) => a.name).join(', ') || '(none defined)';
-        return { error: `Unknown subagent_type "${requestedType}". Available types: ${known}.` };
+        knownTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir);
+        agent = (0, agentTypes_1.findAgentType)(knownTypes, requestedType);
+    }
+    if (requestedType && !agent) {
+        const known = knownTypes.map((a) => a.name).join(', ') || '(none defined)';
+        return {
+            error: `Unknown subagent_type "${requestedType}". Available types: ${known}.\n` +
+                'If you just created .nexrall/agents/' + requestedType + '.md, make sure the write finished in an ' +
+                'EARLIER tool call than this one — a file written in the same batch may not be on disk yet.',
+        };
     }
     // A custom agent's persona is delivered through the project-instructions
     // channel (authoritative in the system prompt), layered above the project's
@@ -525,14 +564,24 @@ async function runSubTask(input, options, agentTypes) {
             (options.nexrallMd ? `\n\n---\n\n${options.nexrallMd}` : '')
         : options.nexrallMd;
     // Optional tool allowlist — deny anything outside it for this sub-agent.
+    //
+    // A refusal here is reported through `deniedReason` rather than the generic
+    // "Permission denied by user", which was actively misleading: the user denied
+    // nothing, and a model told that will re-ask for approval instead of noticing
+    // that the agent's own allowlist (often a typo'd tool name) is what stopped it.
     const allowed = agent?.tools ? new Set(agent.tools) : null;
     const gatedPermission = async (req) => {
-        if (allowed && !allowed.has(req.tool))
-            return false;
+        if (allowed && !allowed.has(req.tool)) {
+            throw new ToolNotAllowedError(`The "${agent.name}" sub-agent is not allowed to use \`${req.tool}\` — it is not in that agent's ` +
+                'tool allowlist. This is a restriction of the agent definition, NOT a user decision: do not ask ' +
+                'for approval, use one of the tools you do have, or report back that the task needs a different agent.');
+        }
         // Path-scoped write restriction (agent.testFilesOnly) — see
         // allowsTestOnlyWrite for the reasoning and its known limit.
-        if (agent?.testFilesOnly && !allowsTestOnlyWrite(req.tool, req.input))
-            return false;
+        if (agent?.testFilesOnly && !allowsTestOnlyWrite(req.tool, req.input)) {
+            throw new ToolNotAllowedError(`The "${agent.name}" sub-agent may only write to TEST files, so \`${req.tool}\` was refused for this ` +
+                'path. Do not try to work around it: if production code must change, say so in your report instead.');
+        }
         return options.requestPermission(req);
     };
     const subMessages = [
@@ -1748,14 +1797,19 @@ async function runAgentLoop(initialMessages, options) {
                 // Request permission
                 const description = humanDescription(name, input);
                 let permitted;
+                // A definition-level refusal carries its own explanation and must not be
+                // flattened into the generic user-denial message below.
+                let deniedReason = null;
                 try {
                     permitted = await options.requestPermission({ tool: name, input, description });
                 }
-                catch {
+                catch (err) {
                     permitted = false;
+                    if (err instanceof ToolNotAllowedError)
+                        deniedReason = err.message;
                 }
                 if (!permitted) {
-                    result = { error: 'Permission denied by user' };
+                    result = { error: deniedReason ?? 'Permission denied by user' };
                 }
                 else if (name === 'task') {
                     // Gated so a burst of `task` blocks in one message becomes a QUEUE

package/dist/index.d.ts

@@ -21,4 +21,5 @@ export * from './permissions/rules';
 export * from './permissions/destructive';
 export * from './plugins/index';
 export * from './plugins/installer';
+export * from './plugins/sources';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -37,4 +37,5 @@ __exportStar(require("./permissions/rules"), exports);
 __exportStar(require("./permissions/destructive"), exports);
 __exportStar(require("./plugins/index"), exports);
 __exportStar(require("./plugins/installer"), exports);
+__exportStar(require("./plugins/sources"), exports);
 //# sourceMappingURL=index.js.map

package/dist/plugins/index.d.ts

@@ -7,6 +7,26 @@ export interface PluginInfo {
     dir: string;
     scope: 'project' | 'global';
 }
+/**
+ * Where each single-file component may live, in priority order.
+ *
+ * Our own layout is checked first so a plugin shipping both is unambiguous, and
+ * so this stays additive: nothing that worked before changes behaviour.
+ *
+ * SECURITY: `hooks` and `mcp` here are code-execution surfaces. Every reader
+ * below and `inspectPluginDir` in installer.ts MUST resolve through this same
+ * table — if the loader reads a path the inspector does not check, a plugin can
+ * run commands that the install-time warning never mentioned. Adding a candidate
+ * without updating the inspector is exactly that bug, so the two are pinned
+ * together by a test.
+ */
+export declare const FILE_CANDIDATES: {
+    readonly manifest: readonly ["plugin.json", string];
+    readonly hooks: readonly ["hooks.json", string];
+    readonly mcp: readonly ["mcp.json", ".mcp.json"];
+};
+/** First existing candidate path for a component, or null. */
+export declare function resolvePluginFile(dir: string, kind: keyof typeof FILE_CANDIDATES): string | null;
 /** Discover installed plugins (project scope shadows global on name clash). */
 export declare function loadPlugins(workDir: string): PluginInfo[];
 /** Subdirectories of every installed plugin that hold `kind` assets (existing only). */

package/dist/plugins/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAsCD,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAKzD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,EAAE,CAMjG;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAetE;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAsCA,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,eAAe,GAAG,MAAM,GAAG,IAAI,CAQhG;AAwCD,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAKzD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,EAAE,CAMjG;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAiBtE;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezE"}

package/dist/plugins/index.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_CANDIDATES = void 0;
+exports.resolvePluginFile = resolvePluginFile;
 exports.loadPlugins = loadPlugins;
 exports.pluginAssetDirs = pluginAssetDirs;
 exports.pluginHooks = pluginHooks;
@@ -40,9 +42,42 @@ exports.pluginMcpServers = pluginMcpServers;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
+/**
+ * Where each single-file component may live, in priority order.
+ *
+ * Our own layout is checked first so a plugin shipping both is unambiguous, and
+ * so this stays additive: nothing that worked before changes behaviour.
+ *
+ * SECURITY: `hooks` and `mcp` here are code-execution surfaces. Every reader
+ * below and `inspectPluginDir` in installer.ts MUST resolve through this same
+ * table — if the loader reads a path the inspector does not check, a plugin can
+ * run commands that the install-time warning never mentioned. Adding a candidate
+ * without updating the inspector is exactly that bug, so the two are pinned
+ * together by a test.
+ */
+exports.FILE_CANDIDATES = {
+    manifest: ['plugin.json', path.join('.claude-plugin', 'plugin.json')],
+    hooks: ['hooks.json', path.join('hooks', 'hooks.json')],
+    mcp: ['mcp.json', '.mcp.json'],
+};
+/** First existing candidate path for a component, or null. */
+function resolvePluginFile(dir, kind) {
+    for (const rel of exports.FILE_CANDIDATES[kind]) {
+        const full = path.join(dir, rel);
+        try {
+            if (fs.statSync(full).isFile())
+                return full;
+        }
+        catch { /* try the next candidate */ }
+    }
+    return null;
+}
 function readMeta(dir) {
+    const file = resolvePluginFile(dir, 'manifest');
+    if (!file)
+        return {};
     try {
-        const raw = fs.readFileSync(path.join(dir, 'plugin.json'), 'utf-8');
+        const raw = fs.readFileSync(file, 'utf-8');
         const j = JSON.parse(raw);
         return {
             name: typeof j.name === 'string' ? j.name : undefined,
@@ -104,8 +139,11 @@ function pluginAssetDirs(workDir, kind) {
 function pluginHooks(workDir) {
     const merged = {};
     for (const p of loadPlugins(workDir)) {
+        const file = resolvePluginFile(p.dir, 'hooks');
+        if (!file)
+            continue;
         try {
-            const raw = fs.readFileSync(path.join(p.dir, 'hooks.json'), 'utf-8');
+            const raw = fs.readFileSync(file, 'utf-8');
             const j = JSON.parse(raw);
             // Accept either { hooks: {...} } or the bare hooks object.
             const hooks = (j.hooks ?? j);
@@ -123,8 +161,11 @@ function pluginHooks(workDir) {
 function pluginMcpServers(workDir) {
     const merged = {};
     for (const p of loadPlugins(workDir)) {
+        const file = resolvePluginFile(p.dir, 'mcp');
+        if (!file)
+            continue;
         try {
-            const raw = fs.readFileSync(path.join(p.dir, 'mcp.json'), 'utf-8');
+            const raw = fs.readFileSync(file, 'utf-8');
             const j = JSON.parse(raw);
             const servers = (j.mcpServers ?? j);
             for (const [name, cfg] of Object.entries(servers)) {

package/dist/plugins/installer.d.ts

@@ -26,12 +26,29 @@ export interface InstallReceipt {
     ref?: string;
     subdir?: string;
     installedAt: string;
+    /**
+     * The exact commit these files came from.
+     *
+     * Without it an install was not reproducible and, worse, not auditable: the
+     * receipt recorded `"owner/repo"`, so nobody — including `nex plugin update` —
+     * could say WHICH code had been reviewed and approved. Recording the resolved
+     * SHA lets an update report `abc1234 → def5678` instead of silently swapping
+     * the contents of a plugin the user already trusted.
+     *
+     * Optional because resolution needs a network call that must never be the
+     * reason an install fails (see resolveCommitSha).
+     */
+    sha?: string;
 }
 export interface InstallResult {
     name: string;
     dir: string;
     scope: 'project' | 'global';
     inspection: PluginInspection;
+    /** Commit installed, when known. */
+    sha?: string;
+    /** For an update: the commit that was previously installed, when known. */
+    previousSha?: string;
 }
 export interface RegistryPlugin {
     name: string;
@@ -57,7 +74,17 @@ export declare function getRegistryPlugin(name: string): Promise<RegistryPlugin
 export declare function reportInstall(name: string): void;
 /** Parse a user-supplied plugin spec into a structured source. Throws on junk. */
 export declare function parsePluginSource(spec: string): PluginSource;
-/** What does this plugin contain? Callers must warn on hasHooks/hasMcp. */
+/**
+ * What does this plugin contain? Callers must warn on hasHooks/hasMcp.
+ *
+ * Resolves every single-file component through the SAME candidate table the
+ * loader uses (plugins/index.ts FILE_CANDIDATES). That shared lookup is a
+ * security requirement, not tidiness: this function produces the warning shown
+ * before install, so any path the loader would execute but the inspector does
+ * not check is a plugin that runs code the user was never told about. A Claude
+ * Code plugin shipping `.mcp.json` used to be exactly that — reported as
+ * containing no MCP servers.
+ */
 export declare function inspectPluginDir(dir: string): PluginInspection;
 export interface InstallOptions {
     /** 'global' (default) → ~/.nexrall/plugins; 'project' → <workDir>/.nexrall/plugins */
@@ -71,7 +98,18 @@ export interface InstallOptions {
      * Called after inspection, before finalising. Return false to abort.
      * Callers should surface hooks/MCP warnings here.
      */
-    confirm?: (inspection: PluginInspection, name: string) => Promise<boolean> | boolean;
+    confirm?: (inspection: PluginInspection, name: string, ctx?: InstallContext) => Promise<boolean> | boolean;
+    /** Internal: SHA previously installed, so an update can be described as a change. */
+    _previousSha?: string;
+}
+/** Extra facts about what is being installed, for the confirmation prompt. */
+export interface InstallContext {
+    /** Commit about to be installed, when it could be resolved. */
+    sha?: string;
+    /** Commit currently installed (updates only). */
+    previousSha?: string;
+    /** True when this replaces an existing install of the same name. */
+    isUpdate: boolean;
 }
 export declare function installPlugin(spec: string, opts?: InstallOptions): Promise<InstallResult>;
 export declare function readReceipt(pluginDir: string): InstallReceipt | null;

package/dist/plugins/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/plugins/installer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/plugins/installer.ts"],"names":[],"mappings":"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"}

package/dist/plugins/installer.js

@@ -47,6 +47,8 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const client_1 = require("../api/client");
+const index_1 = require("./index");
+const sources_1 = require("./sources");
 const RECEIPT_FILE = '_install.json';
 /** Search the registry (empty query = list all, official first). */
 async function searchRegistry(query, limit = 50) {
@@ -134,23 +136,36 @@ function listMd(dir) {
         return [];
     }
 }
-/** What does this plugin contain? Callers must warn on hasHooks/hasMcp. */
+/**
+ * What does this plugin contain? Callers must warn on hasHooks/hasMcp.
+ *
+ * Resolves every single-file component through the SAME candidate table the
+ * loader uses (plugins/index.ts FILE_CANDIDATES). That shared lookup is a
+ * security requirement, not tidiness: this function produces the warning shown
+ * before install, so any path the loader would execute but the inspector does
+ * not check is a plugin that runs code the user was never told about. A Claude
+ * Code plugin shipping `.mcp.json` used to be exactly that — reported as
+ * containing no MCP servers.
+ */
 function inspectPluginDir(dir) {
     let meta = {};
-    try {
-        const j = JSON.parse(fs.readFileSync(path.join(dir, 'plugin.json'), 'utf-8'));
-        meta = {
-            name: typeof j.name === 'string' ? j.name : undefined,
-            version: typeof j.version === 'string' ? j.version : undefined,
-            description: typeof j.description === 'string' ? j.description : undefined,
-        };
+    const manifest = (0, index_1.resolvePluginFile)(dir, 'manifest');
+    if (manifest) {
+        try {
+            const j = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+            meta = {
+                name: typeof j.name === 'string' ? j.name : undefined,
+                version: typeof j.version === 'string' ? j.version : undefined,
+                description: typeof j.description === 'string' ? j.description : undefined,
+            };
+        }
+        catch { /* optional */ }
     }
-    catch { /* optional */ }
     return {
         commands: listMd(path.join(dir, 'commands')),
         agents: listMd(path.join(dir, 'agents')),
-        hasHooks: fs.existsSync(path.join(dir, 'hooks.json')),
-        hasMcp: fs.existsSync(path.join(dir, 'mcp.json')),
+        hasHooks: (0, index_1.resolvePluginFile)(dir, 'hooks') !== null,
+        hasMcp: (0, index_1.resolvePluginFile)(dir, 'mcp') !== null,
         meta,
     };
 }
@@ -160,6 +175,30 @@ function looksLikePlugin(dir) {
     return i.commands.length > 0 || i.agents.length > 0 || i.hasHooks || i.hasMcp || i.meta.name !== undefined;
 }
 // ─── Download & extract ───────────────────────────────────────────────────────
+/**
+ * Resolve a ref (branch/tag/HEAD/sha) to the commit SHA it points at right now.
+ *
+ * Deliberately best-effort: returns null on any failure instead of throwing.
+ * Pinning is an audit and reproducibility feature, and making it mandatory would
+ * mean a GitHub API hiccup or an exhausted unauthenticated rate limit could block
+ * an install that would otherwise succeed — trading a real capability for a
+ * bookkeeping nicety. An unknown SHA is recorded as absent and said out loud,
+ * rather than guessed.
+ */
+async function resolveCommitSha(repo, ref) {
+    try {
+        const res = await fetch(`https://api.github.com/repos/${repo}/commits/${encodeURIComponent(ref || 'HEAD')}`, {
+            headers: { Accept: 'application/vnd.github.sha', 'User-Agent': 'nexrall-code' },
+        });
+        if (!res.ok)
+            return null;
+        const sha = (await res.text()).trim();
+        return /^[0-9a-f]{40}$/i.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function downloadTarball(repo, ref, destFile) {
     const r = ref || 'HEAD';
     const url = `https://codeload.github.com/${repo}/tar.gz/${encodeURIComponent(r)}`;
@@ -219,6 +258,16 @@ function pluginsRoot(scope, workDir) {
 async function installPlugin(spec, opts = {}) {
     const source = parsePluginSource(spec);
     const scope = opts.scope ?? 'global';
+    // Enterprise policy, enforced HERE rather than in each command.
+    //
+    // Every install path in every client funnels through this function, so this is
+    // the one place a restriction cannot be routed around by a caller that forgot
+    // to check — the CLI, the VS Code UI and `update` all inherit it for free. A
+    // check in the CLI command alone would have been decorative.
+    const patterns = (0, sources_1.allowedSourcePatterns)();
+    if (patterns && source.kind === 'github' && !(0, sources_1.isSourceAllowed)(source.raw, patterns)) {
+        throw new Error(`Blocked by your organisation's policy: plugins may only be installed from ${patterns.join(', ')}.`);
+    }
     const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'nexrall-plugin-'));
     try {
         // 1. Materialise the source into tmp
@@ -234,6 +283,12 @@ async function installPlugin(spec, opts = {}) {
             await downloadTarball(source.repo, source.ref, tarFile);
             repoRoot = extractTarball(tarFile, path.join(tmpBase, 'x'));
         }
+        // Resolve the commit alongside the download. Note this is a SEPARATE request
+        // from the tarball, so in principle the branch could move between the two;
+        // the SHA is therefore an audit record of what we asked for, not a checksum
+        // of the bytes on disk. Saying that plainly is better than implying a
+        // guarantee we do not verify.
+        const sha = source.kind === 'github' ? await resolveCommitSha(source.repo, source.ref) : null;
         // 2. Locate the plugin root
         let pluginRoot = source.subdir ? path.join(repoRoot, source.subdir) : repoRoot;
         pluginRoot = path.resolve(pluginRoot);
@@ -264,7 +319,11 @@ async function installPlugin(spec, opts = {}) {
             throw new Error(`Invalid plugin name "${name}".`);
         // 4. Caller confirmation (safety gate — hooks/MCP warnings live here)
         if (opts.confirm) {
-            const ok = await opts.confirm(inspection, name);
+            const ok = await opts.confirm(inspection, name, {
+                sha: sha ?? undefined,
+                previousSha: opts._previousSha,
+                isUpdate: Boolean(opts._previousSha) || Boolean(opts.force),
+            });
             if (!ok)
                 throw new Error('Installation cancelled.');
         }
@@ -284,9 +343,10 @@ async function installPlugin(spec, opts = {}) {
             ref: source.ref,
             subdir: source.subdir,
             installedAt: new Date().toISOString(),
+            ...(sha ? { sha } : {}),
         };
         fs.writeFileSync(path.join(dest, RECEIPT_FILE), JSON.stringify(receipt, null, 2));
-        return { name, dir: dest, scope, inspection };
+        return { name, dir: dest, scope, inspection, sha: sha ?? undefined, previousSha: opts._previousSha };
     }
     finally {
         fs.rmSync(tmpBase, { recursive: true, force: true });
@@ -328,7 +388,18 @@ async function updatePlugin(name, opts = {}) {
         if (receipt.kind === 'local') {
             throw new Error(`Plugin "${name}" was installed from a local path — re-run 'nex plugin install ${receipt.source} --force'.`);
         }
-        return installPlugin(receipt.source, { scope: s, workDir: opts.workDir, name, force: true, confirm: opts.confirm });
+        // Re-installs from the ORIGINAL spec, so an unpinned source still tracks its
+        // branch — that is what "update" means. The recorded SHA is carried through so
+        // the confirmation can show what is actually changing rather than presenting a
+        // possibly wholesale content swap as a routine refresh.
+        return installPlugin(receipt.source, {
+            scope: s,
+            workDir: opts.workDir,
+            name,
+            force: true,
+            confirm: opts.confirm,
+            _previousSha: receipt.sha,
+        });
     }
     throw new Error(`Plugin "${name}" is not installed.`);
 }

package/dist/plugins/sources.d.ts

@@ -0,0 +1,49 @@
+/** Where a declared source came from, which decides how much it is trusted. */
+export type SourceTier = 'managed' | 'user' | 'project';
+export interface DeclaredSource {
+    /** Short alias used as `nex plugin install <alias>`. */
+    name: string;
+    /** A spec parsePluginSource understands: owner/repo, owner/repo#ref, owner/repo/subdir. */
+    spec: string;
+    tier: SourceTier;
+    /** Absolute path of the settings file that declared it (for display/debugging). */
+    file: string;
+}
+/**
+ * All declared sources, most-trusted tier first.
+ *
+ * `includeProject` is false by default. Project-tier entries come from the
+ * repository, so a caller must consciously opt in AFTER workspace trust has been
+ * established — making the safe path the default one and the risky path an
+ * explicit argument.
+ */
+export declare function loadDeclaredSources(workDir: string, opts?: {
+    includeProject?: boolean;
+}): DeclaredSource[];
+/**
+ * Enterprise restriction: which sources may be installed from at all.
+ *
+ * Read ONLY from the managed policy file — a repository or a user cannot widen
+ * their own allowlist, which is the entire point of a managed setting. Absent
+ * (the normal case) means unrestricted.
+ */
+export declare function allowedSourcePatterns(): string[] | null;
+/**
+ * Is this spec permitted by enterprise policy?
+ *
+ * Patterns match `owner/repo` with a trailing `*` wildcard, e.g. `acme/*`. The
+ * comparison strips any `#ref` and subdirectory so a policy cannot be defeated
+ * by appending to the spec.
+ */
+export declare function isSourceAllowed(spec: string, patterns?: string[] | null): boolean;
+/** Resolve an alias to its declared spec, or null when it is not a known alias. */
+export declare function resolveSourceAlias(alias: string, workDir: string, opts?: {
+    includeProject?: boolean;
+}): DeclaredSource | null;
+/** Add or update a source in a settings file, creating it when absent. */
+export declare function writeDeclaredSource(file: string, name: string, spec: string): void;
+/** Remove a source from a settings file. Returns false when it was not there. */
+export declare function removeDeclaredSource(file: string, name: string): boolean;
+/** The settings file a given scope writes to. */
+export declare function sourcesFileFor(scope: 'user' | 'project', workDir: string): string;
+//# sourceMappingURL=sources.d.ts.map

package/dist/plugins/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../../src/plugins/sources.ts"],"names":[],"mappings":"AA0CA,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACd;AA0DD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,cAAc,EAAE,CASlB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,GAAG,IAAI,CAMvD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,EAAE,GAAG,IAA8B,GAAG,OAAO,CAU1G;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,cAAc,GAAG,IAAI,CAGvB;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,IAAI,CAWN;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIjF"}

package/dist/plugins/sources.js

@@ -0,0 +1,197 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDeclaredSources = loadDeclaredSources;
+exports.allowedSourcePatterns = allowedSourcePatterns;
+exports.isSourceAllowed = isSourceAllowed;
+exports.resolveSourceAlias = resolveSourceAlias;
+exports.writeDeclaredSource = writeDeclaredSource;
+exports.removeDeclaredSource = removeDeclaredSource;
+exports.sourcesFileFor = sourcesFileFor;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+function managedSettingsPath() {
+    if (process.platform === 'darwin')
+        return '/Library/Application Support/Nexrall/managed-settings.json';
+    if (process.platform === 'win32')
+        return path.join(process.env.PROGRAMDATA ?? 'C:\\ProgramData', 'Nexrall', 'managed-settings.json');
+    return '/etc/nexrall/managed-settings.json';
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Alias syntax. Kept strict so an alias can never be confused with a path or a ref. */
+const ALIAS_RE = /^[a-z0-9][\w.-]{0,63}$/i;
+/**
+ * A source entry may be a bare string or `{ source: "..." }`.
+ *
+ * The object form exists only to match what people already write in Claude Code
+ * settings, so a team migrating does not have to rewrite their config to find
+ * out whether we accept it.
+ */
+function readSpec(value) {
+    if (typeof value === 'string')
+        return value.trim() || null;
+    if (value && typeof value === 'object') {
+        const v = value;
+        const inner = v.source ?? v.repo ?? v.url;
+        if (typeof inner === 'string')
+            return inner.trim() || null;
+        // Claude Code nests one deeper: { source: { source: "github", repo: "o/r" } }
+        if (inner && typeof inner === 'object') {
+            const deep = inner.repo ?? inner.url;
+            if (typeof deep === 'string')
+                return deep.trim() || null;
+        }
+    }
+    return null;
+}
+function collect(file, tier, into) {
+    const obj = readJson(file);
+    const raw = obj?.pluginSources;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return;
+    for (const [name, value] of Object.entries(raw)) {
+        if (!ALIAS_RE.test(name))
+            continue;
+        const spec = readSpec(value);
+        if (!spec)
+            continue;
+        // First tier to declare a name wins, and tiers are visited most-trusted
+        // first. So a repository cannot redefine an alias the user or an
+        // administrator already bound — otherwise a project file could point a
+        // familiar, trusted-looking name at somewhere else entirely.
+        if (into.has(name))
+            continue;
+        into.set(name, { name, spec, tier, file });
+    }
+}
+/**
+ * All declared sources, most-trusted tier first.
+ *
+ * `includeProject` is false by default. Project-tier entries come from the
+ * repository, so a caller must consciously opt in AFTER workspace trust has been
+ * established — making the safe path the default one and the risky path an
+ * explicit argument.
+ */
+function loadDeclaredSources(workDir, opts = {}) {
+    const out = new Map();
+    collect(managedSettingsPath(), 'managed', out);
+    collect(path.join(os.homedir(), '.nexrall', 'settings.json'), 'user', out);
+    if (opts.includeProject) {
+        collect(path.join(workDir, '.nexrall', 'settings.json'), 'project', out);
+        collect(path.join(workDir, '.nexrall', 'settings.local.json'), 'project', out);
+    }
+    return [...out.values()];
+}
+/**
+ * Enterprise restriction: which sources may be installed from at all.
+ *
+ * Read ONLY from the managed policy file — a repository or a user cannot widen
+ * their own allowlist, which is the entire point of a managed setting. Absent
+ * (the normal case) means unrestricted.
+ */
+function allowedSourcePatterns() {
+    const obj = readJson(managedSettingsPath());
+    const v = obj?.allowedPluginSources;
+    if (!Array.isArray(v))
+        return null;
+    const pats = v.filter((x) => typeof x === 'string' && x.trim().length > 0);
+    return pats.length ? pats : null;
+}
+/**
+ * Is this spec permitted by enterprise policy?
+ *
+ * Patterns match `owner/repo` with a trailing `*` wildcard, e.g. `acme/*`. The
+ * comparison strips any `#ref` and subdirectory so a policy cannot be defeated
+ * by appending to the spec.
+ */
+function isSourceAllowed(spec, patterns = allowedSourcePatterns()) {
+    if (!patterns)
+        return true;
+    const cleaned = spec.trim().replace(/^https?:\/\/(?:www\.)?github\.com\//i, '').replace(/\.git$/, '');
+    const base = cleaned.split('#')[0].split('/').slice(0, 2).join('/').toLowerCase();
+    return patterns.some((p) => {
+        const pat = p.trim().toLowerCase().replace(/^https?:\/\/(?:www\.)?github\.com\//i, '');
+        if (pat === '*')
+            return true;
+        if (pat.endsWith('/*'))
+            return base.startsWith(pat.slice(0, -1));
+        return base === pat.split('#')[0].split('/').slice(0, 2).join('/');
+    });
+}
+/** Resolve an alias to its declared spec, or null when it is not a known alias. */
+function resolveSourceAlias(alias, workDir, opts = {}) {
+    const want = alias.trim().toLowerCase();
+    return loadDeclaredSources(workDir, opts).find((s) => s.name.toLowerCase() === want) ?? null;
+}
+/** Add or update a source in a settings file, creating it when absent. */
+function writeDeclaredSource(file, name, spec) {
+    if (!ALIAS_RE.test(name)) {
+        throw new Error(`Invalid source name "${name}". Use letters, numbers, dot, dash or underscore.`);
+    }
+    const obj = readJson(file) ?? {};
+    const existing = (obj.pluginSources && typeof obj.pluginSources === 'object' && !Array.isArray(obj.pluginSources))
+        ? obj.pluginSources
+        : {};
+    obj.pluginSources = { ...existing, [name]: spec };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+/** Remove a source from a settings file. Returns false when it was not there. */
+function removeDeclaredSource(file, name) {
+    const obj = readJson(file);
+    if (!obj?.pluginSources || typeof obj.pluginSources !== 'object')
+        return false;
+    const sources = obj.pluginSources;
+    if (!(name in sources))
+        return false;
+    delete sources[name];
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+    return true;
+}
+/** The settings file a given scope writes to. */
+function sourcesFileFor(scope, workDir) {
+    return scope === 'user'
+        ? path.join(os.homedir(), '.nexrall', 'settings.json')
+        : path.join(workDir, '.nexrall', 'settings.json');
+}
+//# sourceMappingURL=sources.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.4.24",
+  "version": "1.4.25",
   "description": "Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.",
   "license": "MIT",
   "author": "Nexrall <support@nexrall.com> (https://nexrall.com)",