@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/dist/agents/skills.js

@@ -0,0 +1,570 @@
+/**
+ * Skill resolution and caching for subagent extension
+ */
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir } from "../shared/utils.js";
+const skillCache = new Map();
+const MAX_CACHE_SIZE = 50;
+let loadSkillsCache = null;
+const LOAD_SKILLS_CACHE_TTL_MS = 5000;
+const CONFIG_DIR = ".pi";
+const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
+const SOURCE_PRIORITY = {
+    project: 700,
+    "project-settings": 650,
+    "project-package": 600,
+    user: 300,
+    "user-settings": 250,
+    "user-package": 200,
+    extension: 150,
+    builtin: 100,
+    unknown: 0,
+};
+function stripSkillFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---"))
+        return normalized;
+    const endIndex = normalized.indexOf("\n---", 3);
+    if (endIndex === -1)
+        return normalized;
+    return normalized.slice(endIndex + 4).trim();
+}
+function isWithinPath(filePath, dir) {
+    const relative = path.relative(dir, filePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function readOptionalJsonFile(filePath, label) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error
+            ? error.code
+            : undefined;
+        if (code === "ENOENT")
+            return null;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read ${label} '${filePath}': ${message}`, {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+}
+function readJsonFileBestEffort(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        // Package scans over installed dependencies are opportunistic.
+        return null;
+    }
+}
+function extractSkillPathsFromPackageRoot(packageRoot, source, bestEffort = false) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const pkg = bestEffort
+        ? readJsonFileBestEffort(packageJsonPath)
+        : readOptionalJsonFile(packageJsonPath, "package manifest");
+    if (!pkg || typeof pkg !== "object" || Array.isArray(pkg))
+        return [];
+    const pi = pkg.pi;
+    if (!pi || typeof pi !== "object" || Array.isArray(pi))
+        return [];
+    const skills = pi.skills;
+    if (!Array.isArray(skills))
+        return [];
+    return skills
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => ({ path: path.resolve(packageRoot, entry), source }));
+}
+let cachedGlobalNpmRoot = null;
+function getGlobalNpmRoot() {
+    if (cachedGlobalNpmRoot !== null)
+        return cachedGlobalNpmRoot;
+    try {
+        cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+        return cachedGlobalNpmRoot;
+    }
+    catch {
+        // Global npm root is optional in constrained environments.
+        cachedGlobalNpmRoot = ""; // Empty string means "tried but failed"
+        return null;
+    }
+}
+function collectInstalledPackageSkillPaths(cwd, agentDir, projectTrusted) {
+    const dirs = [
+        ...(projectTrusted ? [{ path: path.join(cwd, CONFIG_DIR, "npm", "node_modules"), source: "project-package" }] : []),
+        { path: path.join(agentDir, "npm", "node_modules"), source: "user-package" },
+    ];
+    const globalRoot = getGlobalNpmRoot();
+    if (globalRoot) {
+        dirs.push({ path: globalRoot, source: "user-package" });
+    }
+    const results = [];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir.path))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir.path, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            if (entry.name.startsWith("@")) {
+                const scopeDir = path.join(dir.path, entry.name);
+                let scopeEntries;
+                try {
+                    scopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const scopeEntry of scopeEntries) {
+                    if (scopeEntry.name.startsWith("."))
+                        continue;
+                    if (!scopeEntry.isDirectory() && !scopeEntry.isSymbolicLink())
+                        continue;
+                    const pkgRoot = path.join(scopeDir, scopeEntry.name);
+                    results.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));
+                }
+                continue;
+            }
+            const pkgRoot = path.join(dir.path, entry.name);
+            results.push(...extractSkillPathsFromPackageRoot(pkgRoot, dir.source, true));
+        }
+    }
+    return results;
+}
+function collectSettingsSkillPaths(cwd, agentDir, projectTrusted) {
+    const results = [];
+    const settingsFiles = [
+        { file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-settings" },
+        { file: path.join(agentDir, "settings.json"), base: agentDir, source: "user-settings" },
+    ];
+    for (const { file, base, source } of settingsFiles) {
+        if (!projectTrusted && source.startsWith("project-"))
+            continue;
+        const settings = readOptionalJsonFile(file, "skills settings file");
+        if (!settings || typeof settings !== "object" || Array.isArray(settings))
+            continue;
+        const skills = settings.skills;
+        if (!Array.isArray(skills))
+            continue;
+        for (const entry of skills) {
+            if (typeof entry !== "string")
+                continue;
+            let resolved = entry;
+            if (resolved.startsWith("~/")) {
+                resolved = path.join(os.homedir(), resolved.slice(2));
+            }
+            else if (!path.isAbsolute(resolved)) {
+                resolved = path.resolve(base, resolved);
+            }
+            results.push({ path: resolved, source });
+        }
+    }
+    return results;
+}
+function isSafePackagePath(value) {
+    return value.length > 0
+        && !path.isAbsolute(value)
+        && value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+function parseNpmPackageName(source) {
+    const spec = source.slice(4).trim();
+    if (!spec)
+        return undefined;
+    const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
+    const packageName = match?.[1] ?? spec;
+    return isSafePackagePath(packageName) ? packageName : undefined;
+}
+function stripGitRef(repoPath) {
+    const atIndex = repoPath.indexOf("@");
+    const hashIndex = repoPath.indexOf("#");
+    const refIndex = [atIndex, hashIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];
+    return refIndex === undefined ? repoPath : repoPath.slice(0, refIndex);
+}
+function parseGitPackagePath(source) {
+    const spec = source.slice(4).trim();
+    if (!spec)
+        return undefined;
+    let host = "";
+    let repoPath = "";
+    const scpLike = spec.match(/^git@([^:]+):(.+)$/);
+    if (scpLike) {
+        host = scpLike[1] ?? "";
+        repoPath = scpLike[2] ?? "";
+    }
+    else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec)) {
+        try {
+            const url = new URL(spec);
+            host = url.hostname;
+            repoPath = url.pathname.replace(/^\/+/, "");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else {
+        const slashIndex = spec.indexOf("/");
+        if (slashIndex < 0)
+            return undefined;
+        host = spec.slice(0, slashIndex);
+        repoPath = spec.slice(slashIndex + 1);
+    }
+    const normalizedPath = stripGitRef(repoPath).replace(/\.git$/, "").replace(/^\/+/, "");
+    if (!host || !isSafePackagePath(host) || !isSafePackagePath(normalizedPath) || normalizedPath.split(/[\\/]/).length < 2) {
+        return undefined;
+    }
+    return { host, repoPath: normalizedPath };
+}
+function resolveSettingsPackageRoot(source, baseDir) {
+    const trimmed = source.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("git:")) {
+        const parsed = parseGitPackagePath(trimmed);
+        return parsed ? path.join(baseDir, "git", parsed.host, parsed.repoPath) : undefined;
+    }
+    if (trimmed.startsWith("npm:")) {
+        const packageName = parseNpmPackageName(trimmed);
+        return packageName ? path.join(baseDir, "npm", "node_modules", packageName) : undefined;
+    }
+    const normalized = trimmed.startsWith("file:") ? trimmed.slice(5) : trimmed;
+    if (normalized === "~")
+        return os.homedir();
+    if (normalized.startsWith("~/"))
+        return path.join(os.homedir(), normalized.slice(2));
+    if (path.isAbsolute(normalized))
+        return normalized;
+    if (normalized === "." || normalized === ".." || normalized.startsWith("./") || normalized.startsWith("../")) {
+        return path.resolve(baseDir, normalized);
+    }
+    return undefined;
+}
+function collectSettingsPackageSkillPaths(cwd, agentDir, projectTrusted) {
+    const settingsFiles = [
+        { file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-package" },
+        { file: path.join(agentDir, "settings.json"), base: agentDir, source: "user-package" },
+    ];
+    const results = [];
+    for (const { file, base, source } of settingsFiles) {
+        if (!projectTrusted && source.startsWith("project-"))
+            continue;
+        const settings = readOptionalJsonFile(file, "skills settings file");
+        if (!settings || typeof settings !== "object" || Array.isArray(settings))
+            continue;
+        const packages = settings.packages;
+        if (!Array.isArray(packages))
+            continue;
+        for (const entry of packages) {
+            const packageSource = typeof entry === "string"
+                ? entry
+                : typeof entry === "object" && entry !== null && typeof entry.source === "string"
+                    ? entry.source
+                    : undefined;
+            if (!packageSource)
+                continue;
+            const packageRoot = resolveSettingsPackageRoot(packageSource, base);
+            if (!packageRoot)
+                continue;
+            results.push(...extractSkillPathsFromPackageRoot(packageRoot, source));
+        }
+    }
+    return results;
+}
+function buildSkillPaths(cwd, agentDir, projectTrusted = true) {
+    const projectSkillPaths = projectTrusted
+        ? [
+            { path: path.join(cwd, CONFIG_DIR, "skills"), source: "project" },
+            { path: path.join(cwd, ".agents", "skills"), source: "project" },
+        ]
+        : [];
+    const skillPaths = [
+        ...projectSkillPaths,
+        ...collectInstalledPackageSkillPaths(cwd, agentDir, projectTrusted),
+        ...collectSettingsPackageSkillPaths(cwd, agentDir, projectTrusted),
+        ...(projectTrusted ? extractSkillPathsFromPackageRoot(cwd, "project-package") : []),
+        ...collectSettingsSkillPaths(cwd, agentDir, projectTrusted),
+        { path: path.join(agentDir, "skills"), source: "user" },
+        { path: path.join(os.homedir(), ".agents", "skills"), source: "user" },
+    ];
+    const deduped = new Map();
+    for (const entry of skillPaths) {
+        const resolvedPath = path.resolve(entry.path);
+        if (!deduped.has(resolvedPath)) {
+            deduped.set(resolvedPath, { path: resolvedPath, source: entry.source });
+        }
+    }
+    return [...deduped.values()];
+}
+function inferSkillSource(filePath, cwd, agentDir, sourceHint) {
+    if (sourceHint)
+        return sourceHint;
+    const projectConfigRoot = path.resolve(cwd, CONFIG_DIR);
+    const projectSkillsRoot = path.resolve(cwd, CONFIG_DIR, "skills");
+    const projectPackagesRoot = path.resolve(cwd, CONFIG_DIR, "npm", "node_modules");
+    const projectAgentsRoot = path.resolve(cwd, ".agents");
+    const userSkillsRoot = path.resolve(agentDir, "skills");
+    const userPackagesRoot = path.resolve(agentDir, "npm", "node_modules");
+    const userAgentRoot = path.resolve(agentDir);
+    const userAgentsRoot = path.resolve(os.homedir(), ".agents");
+    if (isWithinPath(filePath, projectPackagesRoot))
+        return "project-package";
+    if (isWithinPath(filePath, projectSkillsRoot) || isWithinPath(filePath, projectAgentsRoot))
+        return "project";
+    if (isWithinPath(filePath, projectConfigRoot))
+        return "project-settings";
+    if (isWithinPath(filePath, userPackagesRoot))
+        return "user-package";
+    if (isWithinPath(filePath, userSkillsRoot) || isWithinPath(filePath, userAgentsRoot))
+        return "user";
+    if (isWithinPath(filePath, userAgentRoot))
+        return "user-settings";
+    const globalRoot = getGlobalNpmRoot();
+    if (globalRoot && isWithinPath(filePath, globalRoot))
+        return "user-package";
+    return "unknown";
+}
+function chooseHigherPrioritySkill(existing, candidate) {
+    if (!existing)
+        return candidate;
+    const existingPriority = SOURCE_PRIORITY[existing.source] ?? 0;
+    const candidatePriority = SOURCE_PRIORITY[candidate.source] ?? 0;
+    if (candidatePriority > existingPriority)
+        return candidate;
+    if (candidatePriority < existingPriority)
+        return existing;
+    return candidate.order < existing.order ? candidate : existing;
+}
+function maybeReadSkillDescription(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const normalized = content.replace(/\r\n/g, "\n");
+        if (!normalized.startsWith("---"))
+            return undefined;
+        const endIndex = normalized.indexOf("\n---", 3);
+        if (endIndex === -1)
+            return undefined;
+        const frontmatter = normalized.slice(3, endIndex).trim();
+        const match = frontmatter.match(/^description:\s*(.+)$/m);
+        if (!match)
+            return undefined;
+        return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+    }
+    catch {
+        // Description parsing is best-effort metadata extraction.
+        return undefined;
+    }
+}
+function collectFilesystemSkills(cwd, agentDir, skillPaths) {
+    const entries = [];
+    const seen = new Set();
+    let order = 0;
+    const pushEntry = (name, filePath, sourceHint) => {
+        const resolvedFile = path.resolve(filePath);
+        if (seen.has(resolvedFile))
+            return;
+        if (!fs.existsSync(resolvedFile))
+            return;
+        seen.add(resolvedFile);
+        entries.push({
+            name,
+            filePath: resolvedFile,
+            source: inferSkillSource(resolvedFile, cwd, agentDir, sourceHint),
+            description: maybeReadSkillDescription(resolvedFile),
+            order: order++,
+        });
+    };
+    for (const skillPath of skillPaths) {
+        if (!fs.existsSync(skillPath.path))
+            continue;
+        let stat;
+        try {
+            stat = fs.statSync(skillPath.path);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isFile()) {
+            const fileName = path.basename(skillPath.path);
+            if (!fileName.toLowerCase().endsWith(".md"))
+                continue;
+            const skillName = fileName.toLowerCase() === "skill.md"
+                ? path.basename(path.dirname(skillPath.path))
+                : path.basename(fileName, path.extname(fileName));
+            pushEntry(skillName, skillPath.path, skillPath.source);
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const rootSkillFile = path.join(skillPath.path, "SKILL.md");
+        if (fs.existsSync(rootSkillFile)) {
+            pushEntry(path.basename(skillPath.path), rootSkillFile, skillPath.source);
+        }
+        let childEntries;
+        try {
+            childEntries = fs.readdirSync(skillPath.path, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of childEntries) {
+            if (child.name.startsWith("."))
+                continue;
+            const childPath = path.join(skillPath.path, child.name);
+            if (child.isDirectory() || child.isSymbolicLink()) {
+                const nestedSkillPath = path.join(childPath, "SKILL.md");
+                if (fs.existsSync(nestedSkillPath)) {
+                    pushEntry(child.name, nestedSkillPath, skillPath.source);
+                }
+                continue;
+            }
+            if (child.isFile() && child.name.toLowerCase().endsWith(".md")) {
+                pushEntry(path.basename(child.name, path.extname(child.name)), childPath, skillPath.source);
+            }
+        }
+    }
+    return entries;
+}
+function getCachedSkills(cwd, projectTrusted = true) {
+    const now = Date.now();
+    const agentDir = getAgentDir();
+    if (loadSkillsCache && loadSkillsCache.cwd === cwd && loadSkillsCache.agentDir === agentDir && loadSkillsCache.projectTrusted === projectTrusted && now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS) {
+        return loadSkillsCache.skills;
+    }
+    const skillPaths = buildSkillPaths(cwd, agentDir, projectTrusted);
+    const loaded = collectFilesystemSkills(cwd, agentDir, skillPaths);
+    const dedupedByName = new Map();
+    for (const entry of loaded) {
+        const current = dedupedByName.get(entry.name);
+        dedupedByName.set(entry.name, chooseHigherPrioritySkill(current, entry));
+    }
+    const skills = [...dedupedByName.values()].sort((a, b) => a.order - b.order);
+    loadSkillsCache = { cwd, agentDir, projectTrusted, skills, timestamp: now };
+    return skills;
+}
+export function resolveSkillPath(skillName, cwd, options = {}) {
+    const skills = getCachedSkills(cwd, options.projectTrusted ?? true);
+    const skill = skills.find((s) => s.name === skillName);
+    if (!skill)
+        return undefined;
+    return { path: skill.filePath, source: skill.source };
+}
+function readSkill(skillName, skillPath, source) {
+    try {
+        const stat = fs.statSync(skillPath);
+        const cached = skillCache.get(skillPath);
+        if (cached && cached.mtime === stat.mtimeMs) {
+            return cached.skill;
+        }
+        const raw = fs.readFileSync(skillPath, "utf-8");
+        const content = stripSkillFrontmatter(raw);
+        const skill = {
+            name: skillName,
+            path: skillPath,
+            content,
+            source,
+        };
+        skillCache.set(skillPath, { mtime: stat.mtimeMs, skill });
+        if (skillCache.size > MAX_CACHE_SIZE) {
+            const firstKey = skillCache.keys().next().value;
+            if (firstKey)
+                skillCache.delete(firstKey);
+        }
+        return skill;
+    }
+    catch {
+        // Treat unreadable skill files as unresolved so callers can surface as missing.
+        return undefined;
+    }
+}
+export function resolveSkills(skillNames, cwd, options = {}) {
+    const resolved = [];
+    const missing = [];
+    for (const name of skillNames) {
+        const trimmed = name.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed === SUBAGENT_ORCHESTRATION_SKILL) {
+            missing.push(trimmed);
+            continue;
+        }
+        const location = resolveSkillPath(trimmed, cwd, options);
+        if (!location) {
+            missing.push(trimmed);
+            continue;
+        }
+        const skill = readSkill(trimmed, location.path, location.source);
+        if (skill) {
+            resolved.push(skill);
+        }
+        else {
+            missing.push(trimmed);
+        }
+    }
+    return { resolved, missing };
+}
+export function resolveSkillsWithFallback(skillNames, primaryCwd, fallbackCwd, options = {}) {
+    const primary = resolveSkills(skillNames, primaryCwd, options);
+    if (!fallbackCwd || primary.missing.length === 0)
+        return primary;
+    if (path.resolve(primaryCwd) === path.resolve(fallbackCwd))
+        return primary;
+    const fallback = resolveSkills(primary.missing, fallbackCwd, options);
+    return {
+        resolved: [...primary.resolved, ...fallback.resolved],
+        missing: fallback.missing,
+    };
+}
+export function buildSkillInjection(skills) {
+    if (skills.length === 0)
+        return "";
+    return skills
+        .map((s) => `<skill name="${s.name}">\n${s.content}\n</skill>`)
+        .join("\n\n");
+}
+export function normalizeSkillInput(input) {
+    if (input === false)
+        return false;
+    if (input === true || input === undefined)
+        return undefined;
+    if (Array.isArray(input)) {
+        return [...new Set(input.map((s) => s.trim()).filter((s) => s.length > 0))];
+    }
+    // Guard against JSON-encoded arrays arriving as strings (e.g. '["a","b"]').
+    // Models sometimes serialise the skill parameter as a JSON string instead of
+    // a native array, and naively splitting on "," would embed brackets/quotes
+    // into the skill names, causing resolution to silently fail.
+    const trimmed = input.trim();
+    if (trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                return normalizeSkillInput(parsed);
+            }
+        }
+        catch {
+            // Not valid JSON – fall through to comma-split
+        }
+    }
+    return [...new Set(input.split(",").map((s) => s.trim()).filter((s) => s.length > 0))];
+}
+export function discoverAvailableSkills(cwd, options = {}) {
+    const skills = getCachedSkills(cwd, options.projectTrusted ?? true);
+    return skills
+        .filter((s) => s.name !== SUBAGENT_ORCHESTRATION_SKILL)
+        .map((s) => ({
+        name: s.name,
+        source: s.source,
+        description: s.description,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/extension/build-info.js

@@ -0,0 +1 @@
+export const EXTENSION_BUILD = Object.freeze({"version":"0.44.5","sha256":"53f1d8cd3c71b05fdfc903bfcecd06eb5d80bb367a16a09d235199d3f93266f2"});

package/dist/extension/compact-tools.js

@@ -0,0 +1,112 @@
+import { Type } from "../shared/native-typebox.js";
+import { createSubagentExecutor, normalizeSubagentParamsLike } from "../runs/foreground/subagent-executor.js";
+import { activateTools, restoreLazyTools } from "../shared/lazy-tools.js";
+import { runHistoryIndex } from "../runs/shared/history-index.js";
+import { listSupervisorQuestionsAsync } from "../runs/shared/supervisor-questions.js";
+import { renderSubagentResult } from "../tui/render.js";
+import { AgentRunsParams, DelegateParams } from "./schemas.js";
+import { normalizeEverydayParams } from "./tool-input.js";
+export function registerCompactSubagentTools(pi, options) {
+    const { executor, adapt, guidelines, childSafe, asyncByDefault, state } = options;
+    let checking;
+    const checkRuns = () => {
+        if (pi.getActiveTools().includes("agent_runs") || !state.ownedRuns?.size)
+            return Promise.resolve();
+        const owner = state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId;
+        if (checking?.owner === owner)
+            return checking.promise;
+        const promise = Promise.resolve().then(async () => {
+            try {
+                const index = await runHistoryIndex(state);
+                const needed = await index.needsControls();
+                if (state.historyIndex === index && needed)
+                    activateTools(pi, ["agent_runs"]);
+            }
+            catch {
+                // An unavailable browse index cannot establish that genuine owned work is inert.
+                if ((state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId) === owner && state.ownedRuns?.size)
+                    activateTools(pi, ["agent_runs"]);
+            }
+            finally {
+                if (checking?.promise === promise)
+                    checking = undefined;
+            }
+        });
+        checking = { owner, promise };
+        return promise;
+    };
+    const reconcileRuns = () => checkRuns();
+    const onRunsChanged = state.onRunsChanged;
+    state.onRunsChanged = () => { reconcileRuns(); onRunsChanged?.(); };
+    const asyncDescription = asyncByDefault ? "Background by default; false waits for the result." : "Foreground by default; true detaches work. Use false when the result must appear in your report.";
+    pi.registerTool({
+        name: "delegate",
+        label: "Delegate",
+        description: `Delegate one bounded task to a configured agent. For profiles/history, load_subagent({advanced:false}) enables agent_runs. Delegation enables run controls automatically. ${asyncDescription} Use worktree for an isolated writer, acceptance for explicit requirements, and fresh context for independent review. Fresh handoffs must include relevant exact user instructions and settled decisions or readable source references, not just summaries, alongside the bounded task. Advanced workflows remain behind load_subagent.`,
+        ...(childSafe ? { promptGuidelines: [...guidelines] } : {}),
+        parameters: Type.Object({ ...DelegateParams.properties, async: Type.Optional(Type.Boolean({ description: asyncDescription })) }, { additionalProperties: false }),
+        async execute(id, params, signal, onUpdate, ctx) {
+            const { worktree, context, async: background, ...task } = normalizeEverydayParams(params);
+            const request = worktree
+                ? { tasks: [task], worktree: true, context, async: background, cwd: task.cwd }
+                : { ...task, context, async: background };
+            const result = await executor.execute(id, normalizeSubagentParamsLike(request), signal, onUpdate, ctx);
+            await checkRuns();
+            return adapt(result, ctx);
+        },
+        renderResult: renderSubagentResult,
+    });
+    pi.registerTool({
+        name: "agent_runs",
+        defaultActive: false,
+        label: "Agent Runs",
+        description: `List ${childSafe ? "only this child's directly owned" : "your delegated"} runs across working directories (questions/failures, then live work, then unreviewed results; 20 per page). Filter globally by agent/state/text, sort, and page with the returned cursor. history reads 100 bounded native-entry previews; search finds saved visible text using words or quoted phrases, not operators or prefixes. questions pages 20 compact previews (offset/limit); questionId selects one, and questionPath/answerPath retain full records. Browse freshness is not completion or delivery proof. Inspect concise results, paths and continuations; full:true includes the full task/configuration. Answer durable questions, nudge, stop, continue, or save parent-only review. Review notes are not sent to children; put actionable instructions in continue/nudge. Inspect/review/nudge never restart finished work. Continue/answer can launch a saved child; async:false waits for its actual result. Saved continuations keep settings unless agent selects a current profile; model overrides win. Live guidance never mutates model or acceptance. profiles lists roles, sources, context and model/thinking/fallback defaults. History survives reload.`,
+        parameters: AgentRunsParams,
+        async execute(id, params, signal, onUpdate, ctx) {
+            const normalized = normalizeEverydayParams(params, true);
+            if (params.action === "list" && !params.id && options.listRuns)
+                return adapt(await options.listRuns({ ...normalized, signal }, ctx), ctx);
+            const actions = { list: "status", inspect: "status", history: "history", search: "search", nudge: "nudge", stop: "interrupt", continue: "resume", profiles: "list", questions: "questions", answer: "answer", review: "review" };
+            return adapt(await executor.execute(id, normalizeSubagentParamsLike({ ...normalized, action: actions[params.action] }), signal, onUpdate, ctx), ctx);
+        },
+        renderResult: renderSubagentResult,
+    });
+    pi.registerTool({
+        name: "load_subagent",
+        label: "Load Subagent",
+        description: `Enable agent_runs for profiles, history and run controls; advanced:false loads only those controls. By default also enable advanced subagent orchestration: parallel groups, chains, saved workflows, detailed overrides, get, extend and doctor.${childSafe ? " Agent-definition mutations remain blocked." : " Includes agent-definition management."} Ordinary delegation and control use delegate and agent_runs. After loading advanced workflows, call subagent with { action: "list" } before execution.`,
+        promptSnippet: "Discover profiles/history with advanced:false, or load full subagent orchestration by default.",
+        parameters: Type.Object({ advanced: Type.Optional(Type.Boolean({ description: "Also enable advanced orchestration (default true); false loads only agent_runs for profiles, history and controls." })) }),
+        async execute(_id, params) {
+            const advanced = params.advanced !== false;
+            if (advanced && !pi.getAllTools().some((tool) => tool.name === "subagent" && !("namespace" in tool && tool.namespace))) {
+                throw new Error("Subagent is unavailable because the full tool is excluded from this session.");
+            }
+            if (!advanced && !pi.getAllTools().some((tool) => tool.name === "agent_runs" && !("namespace" in tool && tool.namespace)))
+                throw new Error("Run controls are excluded from this session.");
+            const added = !pi.getActiveTools().includes(advanced ? "subagent" : "agent_runs");
+            activateTools(pi, advanced ? ["agent_runs", "subagent"] : ["agent_runs"]);
+            return {
+                content: [{ type: "text", text: advanced ? [`Subagent ${added ? "enabled" : "already enabled"}.`, ...guidelines.map((line) => `- ${line}`)].join("\n") : "Run controls enabled. Use agent_runs({action:'profiles'}) to discover agents; list, history, or search browses owned saved work." }],
+                details: {},
+            };
+        },
+    });
+    const reconcile = async (ctx) => {
+        if (options.keepAdvancedActive)
+            activateTools(pi, ["subagent"]);
+        await checkRuns();
+        if (!pi.getActiveTools().includes("agent_runs") && (await listSupervisorQuestionsAsync(ctx.sessionManager.getSessionId())).some((question) => question.state === "awaiting_input" || question.state === "answer_pending"))
+            activateTools(pi, ["agent_runs"]);
+    };
+    const restore = async (event, ctx) => {
+        if (event.reason !== "reload")
+            restoreLazyTools(pi, ctx, "load_subagent", ["subagent", "agent_runs"]);
+        await reconcile(ctx);
+    };
+    pi.on("session_start", restore);
+    pi.on("session_tree", (_event, ctx) => reconcile(ctx));
+    pi.on("session_compact", (_event, ctx) => reconcile(ctx));
+    pi.on("before_agent_start", (_event, ctx) => reconcile(ctx));
+    return reconcileRuns;
+}