@nexrall/code-core 1.4.71 → 1.4.73

package/dist/agent/skills.d.ts

@@ -34,6 +34,23 @@ export interface Skill {
     metadata?: Record<string, string>;
     /** agentskills.io spec field (experimental) — space-separated tool names the skill declares it needs. Not yet enforced as an allowlist; informational. */
     allowedTools?: string[];
+    /**
+     * `'fork'` = run the expanded skill as an ISOLATED sub-agent (Claude Code's
+     * `context: fork`): the body becomes the child's prompt, the parent
+     * conversation is NOT copied in, and only the child's report comes back —
+     * the invoking context stays clean. Absent = inject the body inline.
+     */
+    context?: 'fork';
+    /** Sub-agent type a forked run uses (only with `context: 'fork'`). Default `general-purpose`. */
+    agent?: string;
+    /**
+     * Forked runs are backgrounded by default (CC 2.1.x): the invocation returns
+     * as soon as the child starts and the report arrives as a <task-notification>.
+     * `background: false` awaits the child and returns its report as the tool
+     * result. Only meaningful with `context: 'fork'`; hosts without a background
+     * hub always await.
+     */
+    background?: boolean;
 }
 /**
  * Discover all skills, with diagnostics.
@@ -68,6 +85,68 @@ export declare function autoInvokableSkills(skills: Skill[]): Skill[];
 export declare function userInvokableSkills(skills: Skill[]): Skill[];
 /** A compact catalogue injected into the system prompt so the model knows what it can auto-invoke via use_skill. */
 export declare function summariseSkills(skills: Skill[]): string;
+/**
+ * Every directory skill discovery reads (see loadSkillsWithWarnings), whether or
+ * not it exists. Used by watchSkills; plugin asset dirs are in the list only
+ * while the plugin is installed — installing or removing one already reloads
+ * skills through its own path, so a stale watcher would be harmless anyway.
+ */
+export declare function skillRoots(workDir: string): string[];
+/**
+ * Watch every skill root and call `onChange` (debounced) when anything under
+ * one moves — the hot reload behind the CLI's mid-session refresh (CC 2.1.x
+ * hot-reloads skill files; before this only `/reload` re-read them).
+ *
+ * Two layers, because neither alone is reliable: fs.watch is the fast path
+ * (recursive where the platform allows it — a non-recursive fallback keeps a
+ * root that predates a skill dir from going dark), and a low-frequency stat
+ * poll backstops the events editors and network filesystems are known to
+ * drop. The poll also notices a root that did not exist yet when we started,
+ * which is exactly when a user creates their first skill. Returns a disposer.
+ */
+export declare function watchSkills(workDir: string, onChange: () => void, opts?: {
+    pollMs?: number;
+    roots?: string[];
+}): () => void;
+/**
+ * Input fields that name a filesystem path. Drives nested discovery — both the skill
+ * scanner below and the nested-instruction scanner in nestedInstructions.ts. Nothing
+ * else may read them: the list is a discovery hint, not a general path extractor.
+ */
+export declare const NESTED_PATH_INPUT_KEYS: readonly ["path", "file_path", "source", "destination"];
+/**
+ * Is `dir` (absolute, under `workDir`) a place nested discovery should skip? One policy
+ * shared by the nested skill and nested instruction scanners: a generated or dependency
+ * checkout is not where the user keeps playbooks or briefs, and `node_modules` alone
+ * would turn every read of a dependency into a candidate. `node_modules`/`.git` are
+ * decided without a git call; everything else asks `git check-ignore`. Cached per
+ * directory by the CALLER (the maps live with the scanners so their lifetime matches).
+ */
+export declare function isIgnoredNestedDir(workDir: string, dir: string, cache: Map<string, boolean>): boolean;
+/** Discovers nested `.nexrall/skills` directories as the agent works (see the section comment above). */
+export declare class NestedSkillScanner {
+    private readonly workDir;
+    private readonly scanned;
+    private readonly ignored;
+    constructor(workDir: string);
+    /**
+     * Scan the tool input of one call for filesystem paths and return any skills
+     * discovered by this call (usually none). Stateful on purpose: each directory
+     * is checked at most once per run, however many files under it are touched.
+     */
+    scanInput(input: Record<string, unknown>): Skill[];
+    /** Scan the ancestor chain of one touched path. */
+    scanPath(touched: string): Skill[];
+}
+/**
+ * Resolve a `<dir>:<name>` reference to a nested skill. The scope must be a
+ * relative path that stays inside the project — `../elsewhere:x` or an absolute
+ * scope is rejected, so a skill reference can never read outside the workdir.
+ * Deliberately not cache-backed: callers use this for a MISS (a hit resolves
+ * against the list they already hold), and re-reading a few files on a miss is
+ * cheaper than keeping a second index honest.
+ */
+export declare function resolveNestedSkill(workDir: string, ref: string): Skill | undefined;
 /**
  * Expand a skill body into a final prompt (same $ARGUMENTS / @file / !`cmd`
  * substitution as slash commands — see commands/loader.ts#expandBody), then

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

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/agent/skills.ts"],"names":[],"mappings":"AA0EA,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,cAAc,CAAC;IACrE,0IAA0I;IAC1I,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kHAAkH;IAClH,sBAAsB,EAAE,OAAO,CAAC;IAChC,iGAAiG;IACjG,aAAa,EAAE,OAAO,CAAC;IACvB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8GAA8G;IAC9G,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kHAAkH;IAClH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,0JAA0J;IAC1J,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AA6MD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,KAAK,EAAO,GAAG;IAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAwB1H;AAED,kKAAkK;AAClK,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CAEnD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAG1E;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,oHAAoH;AACpH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAIvD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcpF"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/agent/skills.ts"],"names":[],"mappings":"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"}

package/dist/agent/skills.js

@@ -33,25 +33,41 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestedSkillScanner = exports.NESTED_PATH_INPUT_KEYS = void 0;
 exports.loadSkillsWithWarnings = loadSkillsWithWarnings;
 exports.loadSkills = loadSkills;
 exports.findSkill = findSkill;
 exports.autoInvokableSkills = autoInvokableSkills;
 exports.userInvokableSkills = userInvokableSkills;
 exports.summariseSkills = summariseSkills;
+exports.skillRoots = skillRoots;
+exports.watchSkills = watchSkills;
+exports.isIgnoredNestedDir = isIgnoredNestedDir;
+exports.resolveNestedSkill = resolveNestedSkill;
 exports.expandSkill = expandSkill;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
 const index_1 = require("../plugins/index");
 const loader_1 = require("../commands/loader");
 const frontmatter_1 = require("../util/frontmatter");
 const agentTypes_1 = require("./agentTypes");
 /** Frontmatter keys this parser understands, for typo/unrecognised-key detection (see SkillWarning). */
 const KNOWN_META_KEYS = new Set([
-    'name', 'description', 'model', 'mode',
-    'disable-model-invocation', 'user-invocable',
-    'license', 'compatibility', 'metadata', 'allowed-tools',
+    'name',
+    'description',
+    'model',
+    'mode',
+    'disable-model-invocation',
+    'user-invocable',
+    'license',
+    'compatibility',
+    'metadata',
+    'allowed-tools',
+    'context',
+    'agent',
+    'background',
 ]);
 // agentskills.io's `name` constraint: 1-64 chars, lowercase alphanumeric and
 // hyphens, no leading/trailing/consecutive hyphens. Validated LENIENTLY here
@@ -73,11 +89,18 @@ function parseBool(v, fallback) {
 function parseSpaceList(v) {
     if (!v)
         return undefined;
-    const items = v.split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
+    const items = v
+        .split(/[,\s]+/)
+        .map((t) => t.trim())
+        .filter(Boolean);
     return items.length ? items : undefined;
 }
 function toSkill(meta, body, name, source, dir, nested) {
     const model = (0, agentTypes_1.parseModel)(meta.model);
+    // `agent:` / `background:` only mean something for a forked skill (CC: "Only
+    // applies when context: fork is set") — dropped otherwise, so a stray line
+    // cannot quietly change how an inline skill runs. validateSkillMeta warns.
+    const isFork = meta.context?.trim().toLowerCase() === 'fork';
     return {
         name,
         description: meta.description || `Custom /${name} skill`,
@@ -92,6 +115,9 @@ function toSkill(meta, body, name, source, dir, nested) {
         compatibility: meta.compatibility || undefined,
         metadata: nested?.metadata,
         allowedTools: parseSpaceList(meta['allowed-tools']),
+        context: isFork ? 'fork' : undefined,
+        agent: isFork ? meta.agent?.trim() || undefined : undefined,
+        background: isFork && meta.background !== undefined ? parseBool(meta.background, true) : undefined,
     };
 }
 /**
@@ -110,22 +136,32 @@ function validateSkillMeta(meta, rawName, effectiveName, dirName, file, warnings
         return;
     if (!SPEC_NAME_RE.test(rawName)) {
         warnings.push({
-            file, name: effectiveName,
+            file,
+            name: effectiveName,
             message: `name "${rawName}" does not match the agentskills.io convention (lowercase letters, numbers, and single hyphens only) — loaded anyway, but other clients reading this skill may warn or reject it.`,
         });
     }
     else if (rawName.length > 64) {
-        warnings.push({ file, name: effectiveName, message: `name is ${rawName.length} characters — the spec caps this at 64. Loaded anyway.` });
+        warnings.push({
+            file,
+            name: effectiveName,
+            message: `name is ${rawName.length} characters — the spec caps this at 64. Loaded anyway.`,
+        });
     }
     if (dirName !== undefined && meta.name && meta.name.trim().toLowerCase() !== dirName.toLowerCase()) {
         warnings.push({
-            file, name: effectiveName,
+            file,
+            name: effectiveName,
             message: `frontmatter name "${meta.name}" does not match its directory name "${dirName}" — the spec requires them to match for cross-client compatibility. Loaded anyway, using the frontmatter name.`,
         });
     }
     const strayKeys = Object.keys(meta).filter((k) => !KNOWN_META_KEYS.has(k));
     if (strayKeys.length) {
-        warnings.push({ file, name: effectiveName, message: `has unrecognised frontmatter key(s): ${strayKeys.join(', ')} — these are ignored.` });
+        warnings.push({
+            file,
+            name: effectiveName,
+            message: `has unrecognised frontmatter key(s): ${strayKeys.join(', ')} — these are ignored.`,
+        });
     }
     // Same class of mistake agentTypes.ts already guards against for sub-agents:
     // pass the value through regardless (parseModel never rejects), but say
@@ -134,14 +170,39 @@ function validateSkillMeta(meta, rawName, effectiveName, dirName, file, warnings
     // (a valid tier alias) silently parsed to undefined in a skill because this
     // file carried its own, shorter, independently-drifted copy of the model list.
     const declaredModel = meta.model === undefined ? undefined : (0, agentTypes_1.parseModel)(meta.model);
-    if (meta.model !== undefined
-        && (declaredModel === undefined
-            || !agentTypes_1.VALID_MODELS.includes(declaredModel))) {
+    if (meta.model !== undefined &&
+        (declaredModel === undefined || !agentTypes_1.VALID_MODELS.includes(declaredModel))) {
         warnings.push({
-            file, name: effectiveName,
+            file,
+            name: effectiveName,
             message: `has model: "${meta.model}", which this version does not recognise — expected one of ${agentTypes_1.VALID_MODELS.join(', ')}, or omit the line to inherit the current session's model. It will still be sent; the server decides whether it is valid.`,
         });
     }
+    // `context: fork` is the only supported value (CC 2.1.x); anything else is a
+    // typo the user wants to hear about, not a silent no-op. `agent:`/`background:`
+    // are fork-only (CC: "Only applies when context: fork is set") — same reasoning.
+    const ctx = meta.context?.trim().toLowerCase();
+    if (meta.context !== undefined && ctx !== 'fork') {
+        warnings.push({
+            file,
+            name: effectiveName,
+            message: `has context: "${meta.context}" — the only supported value is "fork" (run the skill as an isolated sub-agent). Ignored: the skill will run inline.`,
+        });
+    }
+    if (ctx !== 'fork' && meta.agent !== undefined) {
+        warnings.push({
+            file,
+            name: effectiveName,
+            message: `has agent: "${meta.agent}", which only applies together with context: fork — ignored.`,
+        });
+    }
+    if (ctx !== 'fork' && meta.background !== undefined) {
+        warnings.push({
+            file,
+            name: effectiveName,
+            message: `has background:, which only applies together with context: fork — ignored.`,
+        });
+    }
 }
 // Legacy flat-file skills: .nexrall/commands/<name>.md (and plugin commands/).
 // Kept as its own loader (rather than merged into loadSkillDir below) since the
@@ -170,7 +231,11 @@ function loadFlatCommandDir(dir, source, into, warnings) {
             into.set(name, toSkill(meta, body, name, source));
         }
         catch (err) {
-            warnings?.push({ file: full, name: path.basename(file, '.md'), message: `could not be read or parsed (${err.message}) — skipped.` });
+            warnings?.push({
+                file: full,
+                name: path.basename(file, '.md'),
+                message: `could not be read or parsed (${err.message}) — skipped.`,
+            });
         }
     }
 }
@@ -212,7 +277,11 @@ function loadSkillDir(root, source, into, warnings) {
             into.set(name, toSkill(meta, body, name, source, skillDir, nested));
         }
         catch (err) {
-            warnings?.push({ file: skillFile, name: entry.name, message: `could not be read or parsed (${err.message}) — skipped.` });
+            warnings?.push({
+                file: skillFile,
+                name: entry.name,
+                message: `could not be read or parsed (${err.message}) — skipped.`,
+            });
         }
     }
 }
@@ -325,6 +394,326 @@ function summariseSkills(skills) {
         return '';
     return list.map((s) => `- ${s.name}: ${s.description}`).join('\n');
 }
+/**
+ * Every directory skill discovery reads (see loadSkillsWithWarnings), whether or
+ * not it exists. Used by watchSkills; plugin asset dirs are in the list only
+ * while the plugin is installed — installing or removing one already reloads
+ * skills through its own path, so a stale watcher would be harmless anyway.
+ */
+function skillRoots(workDir) {
+    const home = os.homedir();
+    return [
+        path.join(workDir, '.agents', 'skills'),
+        path.join(workDir, '.nexrall', 'commands'),
+        path.join(workDir, '.nexrall', 'skills'),
+        path.join(home, '.nexrall', 'commands'),
+        path.join(home, '.nexrall', 'skills'),
+        path.join(home, '.agents', 'skills'),
+        ...(0, index_1.pluginAssetDirs)(workDir, 'skills'),
+        ...(0, index_1.pluginAssetDirs)(workDir, 'commands'),
+    ];
+}
+/**
+ * Cheap stat signature of everything under the roots: entry names + mtimes, plus
+ * the mtime of a directory skill's SKILL.md (the file edits actually land in).
+ * Two calls with the same string mean discovery has nothing new to find.
+ */
+function rootFingerprint(roots) {
+    const lines = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            lines.push(`${root} -`);
+            continue;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const e of entries) {
+            const p = path.join(root, e.name);
+            let mtime = 0;
+            try {
+                mtime = fs.statSync(p).mtimeMs;
+            }
+            catch {
+                /* vanished between readdir and stat */
+            }
+            let inner = 0;
+            if (e.isDirectory()) {
+                try {
+                    inner = fs.statSync(path.join(p, 'SKILL.md')).mtimeMs;
+                }
+                catch {
+                    /* not a directory-style skill (or gone) */
+                }
+            }
+            lines.push(`${p} ${mtime} ${inner}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Watch every skill root and call `onChange` (debounced) when anything under
+ * one moves — the hot reload behind the CLI's mid-session refresh (CC 2.1.x
+ * hot-reloads skill files; before this only `/reload` re-read them).
+ *
+ * Two layers, because neither alone is reliable: fs.watch is the fast path
+ * (recursive where the platform allows it — a non-recursive fallback keeps a
+ * root that predates a skill dir from going dark), and a low-frequency stat
+ * poll backstops the events editors and network filesystems are known to
+ * drop. The poll also notices a root that did not exist yet when we started,
+ * which is exactly when a user creates their first skill. Returns a disposer.
+ */
+function watchSkills(workDir, onChange, opts = {}) {
+    const roots = opts.roots ?? skillRoots(workDir);
+    const pollMs = opts.pollMs ?? 5000;
+    let disposed = false;
+    let pending = null;
+    let last = rootFingerprint(roots);
+    // Everything funnels through the fingerprint before the callback runs. That is
+    // not just for the poll: fs.watch is documented as unreliable event-wise, and
+    // on macOS a freshly armed recursive watcher fires a synthetic event on the
+    // watched dir itself - verified, 2026-10-03 - which would otherwise reload on
+    // every startup. "The stats moved" is the one honest signal both layers share.
+    const settle = () => {
+        pending = null;
+        if (disposed)
+            return;
+        const now = rootFingerprint(roots);
+        if (now === last)
+            return; // stray arm event, or a rename+change pair already seen
+        last = now;
+        onChange();
+    };
+    const fire = () => {
+        // Coalesce, never reset: re-arming the timer on every event starves the
+        // settle pass whenever events keep arriving inside the window (the poll
+        // ticks every 5s by default but tests and busy trees go faster - verified
+        // stalling at 100ms, 2026-10-03).
+        if (disposed || pending)
+            return;
+        pending = setTimeout(settle, 150);
+    };
+    const watchers = [];
+    for (const root of roots) {
+        try {
+            if (!fs.statSync(root).isDirectory())
+                continue;
+        }
+        catch {
+            continue; // not there yet - the poll notices when it appears
+        }
+        try {
+            const w = fs.watch(root, { recursive: true }, fire);
+            w.on('error', () => { });
+            watchers.push(w);
+        }
+        catch {
+            try {
+                const w = fs.watch(root, fire);
+                w.on('error', () => { });
+                watchers.push(w);
+            }
+            catch {
+                /* no watcher for this root - the poll still covers it */
+            }
+        }
+    }
+    const timer = setInterval(() => {
+        if (rootFingerprint(roots) !== last)
+            fire();
+    }, pollMs);
+    if (typeof timer.unref === 'function')
+        timer.unref();
+    return () => {
+        disposed = true;
+        if (pending)
+            clearTimeout(pending);
+        clearInterval(timer);
+        for (const w of watchers) {
+            try {
+                w.close();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    };
+}
+// ── Nested skills: <dir>/.nexrall/skills discovered as the agent works ────────
+//
+// Claude Code 2.1.x discovers `.claude/skills` in SUBdirectories lazily: the
+// skill only matters once Claude works with files in (or under) that directory,
+// so it is surfaced then instead of at startup. Same here, one level per
+// ancestor: as a tool call touches `packages/cli/src/x.ts`, every directory from
+// `packages/cli/src` up to (but excluding) the project root gets checked for its
+// own `.nexrall/skills`.
+//
+// Nested skills are ALWAYS addressed as `<dir>:<name>` (the project-relative
+// directory, `/`-separated), which is what makes them self-describing: name
+// resolution needs no memory of what was discovered where — the scope in the
+// name IS the lookup path (see resolveNestedSkill). It also means a nested
+// skill can never silently shadow a top-level one.
+//
+// Gitignored directories are skipped: a generated or dependency checkout is not
+// where the user keeps playbooks, and `node_modules` alone would make every
+// read of a dependency a candidate. (Resolution is deliberately more permissive:
+// naming `<dir>:<name>` explicitly still works even inside an ignored dir.)
+/**
+ * Input fields that name a filesystem path. Drives nested discovery — both the skill
+ * scanner below and the nested-instruction scanner in nestedInstructions.ts. Nothing
+ * else may read them: the list is a discovery hint, not a general path extractor.
+ */
+exports.NESTED_PATH_INPUT_KEYS = ['path', 'file_path', 'source', 'destination'];
+/**
+ * Is `dir` (absolute, under `workDir`) a place nested discovery should skip? One policy
+ * shared by the nested skill and nested instruction scanners: a generated or dependency
+ * checkout is not where the user keeps playbooks or briefs, and `node_modules` alone
+ * would turn every read of a dependency into a candidate. `node_modules`/`.git` are
+ * decided without a git call; everything else asks `git check-ignore`. Cached per
+ * directory by the CALLER (the maps live with the scanners so their lifetime matches).
+ */
+function isIgnoredNestedDir(workDir, dir, cache) {
+    const cached = cache.get(dir);
+    if (cached !== undefined)
+        return cached;
+    const rel = path.relative(workDir, dir);
+    let verdict;
+    if (rel.split(/[\\/]/).includes('node_modules') || rel.split(/[\\/]/).includes('.git')) {
+        verdict = true; // no git call needed for the two dirs that matter most
+    }
+    else {
+        try {
+            const r = (0, child_process_1.spawnSync)('git', ['-C', workDir, 'check-ignore', '-q', '--', dir], {
+                stdio: 'ignore',
+                timeout: 3000,
+            });
+            verdict = r.status === 0; // 0 = ignored; 1 = not; anything else (no git, not a repo) = not
+        }
+        catch {
+            verdict = false;
+        }
+    }
+    cache.set(dir, verdict);
+    return verdict;
+}
+/** Discovers nested `.nexrall/skills` directories as the agent works (see the section comment above). */
+class NestedSkillScanner {
+    constructor(workDir) {
+        this.workDir = workDir;
+        this.scanned = new Set();
+        this.ignored = new Map();
+    }
+    /**
+     * Scan the tool input of one call for filesystem paths and return any skills
+     * discovered by this call (usually none). Stateful on purpose: each directory
+     * is checked at most once per run, however many files under it are touched.
+     */
+    scanInput(input) {
+        const out = [];
+        for (const key of exports.NESTED_PATH_INPUT_KEYS) {
+            const v = input[key];
+            if (typeof v !== 'string' || !v || v.length > 4096)
+                continue;
+            out.push(...this.scanPath(v));
+        }
+        return out;
+    }
+    /** Scan the ancestor chain of one touched path. */
+    scanPath(touched) {
+        let abs;
+        try {
+            abs = path.isAbsolute(touched) ? touched : path.join(this.workDir, touched);
+        }
+        catch {
+            return [];
+        }
+        let base = abs;
+        try {
+            if (!fs.statSync(abs).isDirectory())
+                base = path.dirname(abs);
+        }
+        catch {
+            base = path.dirname(abs); // a path being created: its directory is the claim
+        }
+        const work = path.resolve(this.workDir);
+        const out = [];
+        let dir = base;
+        for (;;) {
+            const rel = path.relative(work, dir);
+            if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+                break;
+            if (!this.scanned.has(dir)) {
+                this.scanned.add(dir);
+                const root = path.join(dir, '.nexrall', 'skills');
+                let hasRoot = false;
+                try {
+                    hasRoot = fs.statSync(root).isDirectory();
+                }
+                catch {
+                    /* the common case - most directories carry no skills */
+                }
+                if (hasRoot && !isIgnoredNestedDir(this.workDir, dir, this.ignored)) {
+                    const scope = rel.split(path.sep).join('/');
+                    const found = new Map();
+                    loadSkillDir(root, 'project', found);
+                    for (const skill of found.values()) {
+                        skill.name = `${scope}:${skill.name}`;
+                        out.push(skill);
+                    }
+                }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return out;
+    }
+}
+exports.NestedSkillScanner = NestedSkillScanner;
+/**
+ * Resolve a `<dir>:<name>` reference to a nested skill. The scope must be a
+ * relative path that stays inside the project — `../elsewhere:x` or an absolute
+ * scope is rejected, so a skill reference can never read outside the workdir.
+ * Deliberately not cache-backed: callers use this for a MISS (a hit resolves
+ * against the list they already hold), and re-reading a few files on a miss is
+ * cheaper than keeping a second index honest.
+ */
+function resolveNestedSkill(workDir, ref) {
+    const bare = ref.replace(/^\//, '').trim();
+    const idx = bare.lastIndexOf(':');
+    if (idx <= 0 || idx >= bare.length - 1)
+        return undefined;
+    const scope = bare.slice(0, idx).trim();
+    const name = bare
+        .slice(idx + 1)
+        .trim()
+        .toLowerCase();
+    if (!scope || !name)
+        return undefined;
+    const work = path.resolve(workDir);
+    let dir;
+    try {
+        dir = path.resolve(work, scope);
+    }
+    catch {
+        return undefined;
+    }
+    const rel = path.relative(work, dir);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        return undefined;
+    const found = new Map();
+    loadSkillDir(path.join(dir, '.nexrall', 'skills'), 'project', found);
+    const skill = found.get(name);
+    if (skill) {
+        // Same scoped identity the scanner hands out, so console output, error
+        // messages and the model all name the skill the same way.
+        skill.name = `${rel.split(path.sep).join('/')}:${skill.name}`;
+    }
+    return skill;
+}
 /**
  * Expand a skill body into a final prompt (same $ARGUMENTS / @file / !`cmd`
  * substitution as slash commands — see commands/loader.ts#expandBody), then

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

@@ -1 +1 @@
-{"version":3,"file":"subAgentBudget.d.ts","sourceRoot":"","sources":["../../src/agent/subAgentBudget.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAW9F;AAoBD,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAa/F;AAED;;;;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;AA8BD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,qBAA4B,CAAC;AAE1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;IAC/D,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb,CAuBA;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C;AAkBD,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAQ9C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAGpE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuB7H;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAGnE;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE"}
+{"version":3,"file":"subAgentBudget.d.ts","sourceRoot":"","sources":["../../src/agent/subAgentBudget.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAW9F;AAoBD,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,MAAM,CAa/F;AAED;;;;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;AA8BD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,qBAA4B,CAAC;AAE1D,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf;IACD,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb,CAuBA;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C;AAsBD,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAW9C;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAGpE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAC9B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAuBf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAGnE;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE"}

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

@@ -1 +1 @@
-{"version":3,"file":"subTask.d.ts","sourceRoot":"","sources":["../../src/agent/subTask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAiB,MAAM,UAAU,CAAC;AAGrF,OAAO,EAA6C,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAazF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,SAAS,EAAE,EAQvB,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,EAEvC,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,EAIhF,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC,CAmvBrB"}
+{"version":3,"file":"subTask.d.ts","sourceRoot":"","sources":["../../src/agent/subTask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAiB,MAAM,UAAU,CAAC;AAGrF,OAAO,EAA6C,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAuCzF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,SAAS,EAAE,EAQvB,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,EAEvC,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,EAIhF,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC,CA+yBrB"}