@nexrall/code-core 1.4.23 → 1.4.25

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

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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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;
@@ -42,6 +42,7 @@ exports.summariseSubTaskProgress = summariseSubTaskProgress;
 exports.contextWindowFor = contextWindowFor;
 exports.compactionThresholds = compactionThresholds;
 exports.estimateBodyBytes = estimateBodyBytes;
+exports.allowsTestOnlyWrite = allowsTestOnlyWrite;
 exports.findSafeCutIndex = findSafeCutIndex;
 exports.transcriptOf = transcriptOf;
 exports.createLedger = createLedger;
@@ -405,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.
  *
@@ -510,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
@@ -524,10 +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)) {
+            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 = [
@@ -757,6 +811,56 @@ function resolveVerificationNudge(rawSettings) {
 }
 /** Tools that mutate the filesystem — used by the verification nudge (GAP D). */
 exports.WRITE_TOOL_NAMES = new Set(['write_file', 'edit_file', 'multi_edit', 'delete_file', 'move_file', 'copy_file', 'notebook_edit']);
+/**
+ * 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.
+ */
+function allowsTestOnlyWrite(tool, input) {
+    // Non-write tools are unaffected: reading, searching and running tests are all
+    // essential to writing a test.
+    //
+    // WRITE_TOOL_NAMES deliberately excludes `create_directory`: isTestFile matches
+    // FILE paths, so a legitimate `create_directory('test/helpers')` would be
+    // refused and the agent could not scaffold the tree it needs — while an empty
+    // directory cannot damage production code, and files placed in it are still
+    // checked individually.
+    if (!exports.WRITE_TOOL_NAMES.has(tool))
+        return true;
+    // EVERY path the call could affect must be a test file, not just `path`:
+    // move_file takes {source, dest} and copy_file {source, destination}, so
+    // checking `path` alone would let `move_file src/index.ts -> /tmp/x` through and
+    // remove production code by relocating it.
+    //
+    // `source` is skipped for notebook_edit specifically, where it is the CELL
+    // CONTENT rather than a path — treating a blob of code as a path would refuse
+    // every legitimate notebook edit.
+    const pathKeys = tool === 'notebook_edit'
+        ? ['path']
+        : ['path', 'source', 'dest', 'destination'];
+    const candidates = pathKeys
+        .map((k) => input?.[k])
+        .filter((v) => typeof v === 'string' && v.length > 0);
+    // An unrecognised write shape (no path-like argument at all) is refused rather
+    // than allowed through, so a future tool cannot silently become a hole here.
+    if (candidates.length === 0)
+        return false;
+    return candidates.every((p) => (0, testIntegrity_1.isTestFile)(p));
+}
 /** Heuristic: does a bash command look like it's running tests/build/lint/typecheck? (GAP D) */
 exports.VERIFY_CMD_RE = /\b(npm|yarn|pnpm)\s+(run\s+)?(test|build|lint|typecheck|tsc)\b|\bpytest\b|\bgo\s+(test|vet|build)\b|\btsc\b|\beslint\b|\bcargo\s+(test|build|check)\b/i;
 /**
@@ -1693,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/agent/securityLint.d.ts

@@ -0,0 +1,27 @@
+export interface SecurityFinding {
+    /** Machine-readable class, e.g. 'hardcoded-secret'. */
+    kind: string;
+    /** One-line explanation aimed at the model, phrased as what to do. */
+    message: string;
+    /** 1-based line number within the written content. */
+    line: number;
+    /** The offending line, truncated and with any secret value redacted. */
+    sample: string;
+}
+/**
+ * Scan file content for flagrant security problems.
+ *
+ * Returns at most `max` findings (default 5) — enough to be useful, few enough
+ * that the note appended to a tool result stays readable and cheap.
+ */
+export declare function checkSecurity(content: string, max?: number): SecurityFinding[];
+/**
+ * Render findings as a note to append to a successful write's tool result.
+ *
+ * Phrased as a review comment rather than an error: the write HAS happened, and
+ * the model is being asked to look again. Deliberately explicit that it may be a
+ * false positive — otherwise the model tends to "fix" flagged-but-correct code,
+ * which is its own kind of damage.
+ */
+export declare function securityNoteText(findings: SecurityFinding[]): string;
+//# sourceMappingURL=securityLint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"securityLint.d.ts","sourceRoot":"","sources":["../../src/agent/securityLint.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AA6GD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,eAAe,EAAE,CA6CzE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,CAepE"}

package/dist/agent/securityLint.js

@@ -0,0 +1,195 @@
+"use strict";
+// ─── Inline security lint ─────────────────────────────────────────────────────
+//
+// The gap this closes: six checks already run automatically on every write —
+// editCompleteness, crossFile, testIntegrity, claimEvidence, flaky, destructive —
+// and not one of them is about security. For an agent that WRITES production code,
+// nothing stopped it committing a hardcoded credential, an `eval` over
+// user-controlled input, or a SQL string built by concatenation. The only security
+// review available was an agent the user had to know to ask for.
+//
+// DESIGN: WARN, NEVER BLOCK.
+//
+// This runs on every single write, so a false positive is expensive — it would
+// train the model (and the user) to ignore the channel, or worse, stall a
+// legitimate edit. `editCompleteness` can afford to refuse outright because
+// "// ... rest unchanged" is unambiguous; "this looks like SQL injection" is not.
+// So findings are appended to the tool RESULT as a note the model sees and can act
+// on, and the write still succeeds.
+//
+// Consequently every pattern here is tuned for PRECISION over recall. A check that
+// fires on ordinary code was removed rather than loosened. Deep analysis is the
+// `security-auditor` agent's job; this only catches the flagrant cases at the
+// moment they are written.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSecurity = checkSecurity;
+exports.securityNoteText = securityNoteText;
+/** Max characters of the offending line to echo back. */
+const SAMPLE_MAX = 160;
+/**
+ * Redact anything that looks like a literal secret value before echoing a line.
+ *
+ * The whole point of flagging a hardcoded credential is to get it removed — so
+ * this must not copy the value into the transcript (and from there into logs, or
+ * the next request's context) on the way to reporting it.
+ */
+function redact(line) {
+    const masked = line
+        // key = "value" / key: 'value' → keep the key, mask the value
+        .replace(/(['"`]?[\w.-]*(?:secret|password|passwd|token|api[_-]?key|apikey|auth|credential|private[_-]?key)[\w.-]*['"`]?\s*[:=]\s*)(['"`])([^'"`]{4,})\2/gi, (_m, head, q) => `${head}${q}[REDACTED]${q}`)
+        // Bare high-entropy provider tokens appearing anywhere on the line
+        .replace(/\b(sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,})\b/g, '[REDACTED]');
+    return masked.length > SAMPLE_MAX ? masked.slice(0, SAMPLE_MAX) + '…' : masked;
+}
+/** Strip string/comment noise that causes false positives, keeping length stable. */
+function isLikelyCommentLine(line) {
+    return /^\s*(\/\/|\*|#|--|<!--)/.test(line);
+}
+const RULES = [
+    // ── Hardcoded credentials ───────────────────────────────────────────────────
+    // Provider-prefixed tokens are near-zero false positive: the prefixes are
+    // registered formats, not something that occurs naturally in source. Checked
+    // inside comments too — a key commented out is still a committed key.
+    {
+        kind: 'hardcoded-secret',
+        re: /\b(sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{30,})\b/,
+        message: 'Looks like a real API key/token committed to source. Move it to an environment variable and rotate the exposed key.',
+        includeComments: true,
+    },
+    // NOTE: the `private-key` check is NOT here — it needs to span multiple lines
+    // (BEGIN header on one, base64 body on the next), which this per-line loop
+    // cannot express. It runs separately in checkSecurity below.
+    {
+        kind: 'hardcoded-password',
+        // An ASSIGNMENT of a credential-ish name to a non-trivial literal.
+        //
+        // Tightened after measuring against the real backend, where the looser version
+        // fired on `missingSecret:'FIREBASE_TOKEN'` — code that NAMES a secret in an
+        // error message, the opposite of leaking one. So a value that is itself just a
+        // SCREAMING_SNAKE identifier (an env-var name) is excluded, along with the
+        // usual placeholder vocabulary. The value must also look like actual secret
+        // material: mixed case or digits, not a lone lowercase word.
+        re: /(?:password|passwd|secret|api[_-]?key|apikey|access[_-]?token)['"`]?\s*[:=]\s*['"`](?![A-Z0-9_]+['"`])(?!.*(?:\$\{|process\.env|os\.environ|example|changeme|placeholder|redacted|xxx|test|dummy|fake|sample|your[_-]?|<|\*{3}))(?=[^'"`]*[0-9A-Z])[^'"`\s]{10,}['"`]/,
+        message: 'Hardcoded credential literal. Read it from the environment/secret store instead, and rotate the exposed value.',
+        includeComments: true,
+    },
+    // ── Injection ───────────────────────────────────────────────────────────────
+    {
+        kind: 'dynamic-eval',
+        // The negative lookbehind for `.` is what makes this usable: `redisClient.eval`
+        // (a Redis Lua script), `page.eval` (Playwright), `vm.eval` and friends are
+        // METHOD calls on an object and have nothing to do with JavaScript's global
+        // eval. Without it, the real backend's Redis idempotency script was flagged.
+        // Only a bare `eval(` / `new Function(` with a non-literal argument counts.
+        re: /(?<![.\w$])(?:eval|new\s+Function)\s*\(\s*(?!['"`][^'"`]*['"`]\s*\))[^)]*[a-zA-Z_$][\w$]*/,
+        message: 'eval / new Function on a non-literal value executes arbitrary code if that value is ever user-controlled. Use an explicit parser or a lookup table.',
+    },
+    {
+        kind: 'sql-injection',
+        // Only fires when the interpolated expression is plausibly REQUEST-DERIVED.
+        //
+        // The obvious pattern — any `${...}` inside a SQL string — was measured
+        // against the real backend and flagged 15 of 183 files, essentially all of
+        // them safe and idiomatic: `${sets.join(', ')}` for a dynamic UPDATE, `${field}`
+        // for a server-chosen column, `${CONSUMPTION}` for a module constant. At that
+        // hit rate the warning is pure noise, and noise is worse than silence because
+        // it teaches everyone to skip the channel.
+        //
+        // So the interpolation must name something that plausibly came from the
+        // outside: req/request/params/query/body/input/user/args, or a bare
+        // `'...' + ident`. This trades recall for precision on purpose — thorough SQL
+        // review is the security-auditor agent's job, not an inline regex's.
+        re: /\b(?:SELECT|INSERT\s+INTO|UPDATE|DELETE\s+FROM)\b[^;'"`]{0,160}(?:\$\{\s*(?:req|request|params?|query|body|input|user|args|ctx)\b|['"`]\s*\+\s*(?:req|request|params?|query|body|input|user|args|ctx)\b|%\s*\(\s*(?:request|params?|query|body|input|user)\b)/i,
+        message: 'SQL built by interpolating a request-derived value. Use a parameterised query ($1 / ? placeholders) — this is the classic injection sink.',
+    },
+    {
+        kind: 'command-injection',
+        // Shell execution with an interpolated or concatenated argument.
+        re: /\b(?:exec|execSync|spawnSync?|system|popen|os\.system|subprocess\.(?:call|run|Popen))\s*\(\s*(?:[`'"][^`'"]*(?:\$\{|['"]\s*\+)|[a-zA-Z_$][\w$]*\s*\+)/,
+        message: 'Shell command built from a variable. Pass arguments as an array (no shell), or validate against an allowlist — a value containing ; or $() becomes command execution.',
+    },
+    // ── Transport / verification ────────────────────────────────────────────────
+    {
+        kind: 'tls-verification-disabled',
+        re: /(?:rejectUnauthorized\s*:\s*false|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*['"]?0|verify\s*=\s*False|InsecureSkipVerify\s*:\s*true)/,
+        message: 'TLS certificate verification is disabled, which removes protection against man-in-the-middle attacks. Trust a specific CA instead if the cert is self-signed.',
+    },
+];
+/**
+ * Scan file content for flagrant security problems.
+ *
+ * Returns at most `max` findings (default 5) — enough to be useful, few enough
+ * that the note appended to a tool result stays readable and cheap.
+ */
+function checkSecurity(content, max = 5) {
+    if (!content)
+        return [];
+    const findings = [];
+    const lines = content.split(/\r?\n/);
+    // Private keys are matched across lines, unlike every other rule.
+    //
+    // A real PEM block is inherently multi-line: the BEGIN header sits on one line
+    // and the base64 body on the next. Requiring both on ONE line (which the
+    // line-by-line loop below does) meant the single highest-severity finding here
+    // only fired for keys embedded in a "\n"-escaped string literal, and missed the
+    // far more common case of a key pasted in verbatim.
+    const pemIdx = lines.findIndex((l) => /-----BEGIN\s+(?:RSA|EC|DSA|OPENSSH|PGP)?\s*PRIVATE KEY-----/.test(l));
+    if (pemIdx !== -1) {
+        // Require actual key material nearby, so a bare header — placeholder text in a
+        // config UI, documentation, a PEM parser — does not trip it.
+        const following = lines.slice(pemIdx, pemIdx + 4).join('\n');
+        if (/[A-Za-z0-9+/]{40,}/.test(following.replace(/-----[^-]+-----/g, ''))) {
+            findings.push({
+                kind: 'private-key',
+                message: 'A private key with real key material is being written into source. Store it outside the repo (secret manager / env var) and rotate it.',
+                line: pemIdx + 1,
+                sample: '-----BEGIN PRIVATE KEY----- [REDACTED]',
+            });
+        }
+    }
+    // One finding per (kind, line) at most, and one finding per kind overall —
+    // a file with fifty interpolated queries should say "SQL injection" once, not
+    // fill the model's context with fifty copies of the same advice.
+    const seenKinds = new Set();
+    for (let i = 0; i < lines.length && findings.length < max; i++) {
+        const line = lines[i];
+        if (!line || line.length > 2000)
+            continue; // minified/bundled — not hand-written source
+        const commentish = isLikelyCommentLine(line);
+        for (const rule of RULES) {
+            if (seenKinds.has(rule.kind))
+                continue;
+            if (commentish && !rule.includeComments)
+                continue;
+            if (!rule.re.test(line))
+                continue;
+            seenKinds.add(rule.kind);
+            findings.push({ kind: rule.kind, message: rule.message, line: i + 1, sample: redact(line.trim()) });
+            break; // at most one rule per line
+        }
+    }
+    return findings;
+}
+/**
+ * Render findings as a note to append to a successful write's tool result.
+ *
+ * Phrased as a review comment rather than an error: the write HAS happened, and
+ * the model is being asked to look again. Deliberately explicit that it may be a
+ * false positive — otherwise the model tends to "fix" flagged-but-correct code,
+ * which is its own kind of damage.
+ */
+function securityNoteText(findings) {
+    // Opt-out, mirroring NEXRALL_ALLOW_ELIDED_WRITE. Someone working in a codebase
+    // that trips a rule constantly (a SQL-builder library, a crypto implementation,
+    // a test-fixture directory full of fake keys) needs a way to silence this
+    // without disabling the write path itself.
+    if (process.env.NEXRALL_SECURITY_LINT === 'off')
+        return '';
+    if (!findings.length)
+        return '';
+    const lines = findings.map((f) => `  • line ${f.line} [${f.kind}]: ${f.message}\n    ${f.sample}`);
+    return (`\n\n⚠ SECURITY REVIEW (${findings.length} finding${findings.length > 1 ? 's' : ''}) — the write succeeded; check these before moving on:\n` +
+        lines.join('\n') +
+        `\nIf a finding is a false positive (test fixture, placeholder, intentionally dynamic), say so and continue — do NOT rewrite correct code to silence it.`);
+}
+//# sourceMappingURL=securityLint.js.map

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './tools/executor';
 export * from './agent/loop';
 export * from './agent/testIntegrity';
 export * from './agent/editCompleteness';
+export * from './agent/securityLint';
 export * from './agent/crossFile';
 export * from './agent/flaky';
 export * from './agent/claimEvidence';
@@ -20,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,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

@@ -21,6 +21,7 @@ __exportStar(require("./tools/executor"), exports);
 __exportStar(require("./agent/loop"), exports);
 __exportStar(require("./agent/testIntegrity"), exports);
 __exportStar(require("./agent/editCompleteness"), exports);
+__exportStar(require("./agent/securityLint"), exports);
 __exportStar(require("./agent/crossFile"), exports);
 __exportStar(require("./agent/flaky"), exports);
 __exportStar(require("./agent/claimEvidence"), exports);
@@ -36,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;