@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/plugins/bundled-dir.js

@@ -2,16 +2,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 export function resolveBundledPluginsDir() {
-    const override = process.env.POOLBOT_BUNDLED_PLUGINS_DIR?.trim() ||
-        process.env.CLAWDBOT_BUNDLED_PLUGINS_DIR?.trim();
-    if (override)
+    const override = process.env.POOLBOT_BUNDLED_PLUGINS_DIR?.trim();
+    if (override) {
         return override;
+    }
     // bun --compile: ship a sibling `extensions/` next to the executable.
     try {
         const execDir = path.dirname(process.execPath);
         const sibling = path.join(execDir, "extensions");
-        if (fs.existsSync(sibling))
+        if (fs.existsSync(sibling)) {
             return sibling;
+        }
     }
     catch {
         // ignore
@@ -21,11 +22,13 @@ export function resolveBundledPluginsDir() {
         let cursor = path.dirname(fileURLToPath(import.meta.url));
         for (let i = 0; i < 6; i += 1) {
             const candidate = path.join(cursor, "extensions");
-            if (fs.existsSync(candidate))
+            if (fs.existsSync(candidate)) {
                 return candidate;
+            }
             const parent = path.dirname(cursor);
-            if (parent === cursor)
+            if (parent === cursor) {
                 break;
+            }
             cursor = parent;
         }
     }

package/dist/plugins/discovery.js

@@ -1,19 +1,145 @@
 import fs from "node:fs";
 import path from "node:path";
+import { isPathInsideWithRealpath } from "../security/scan-paths.js";
 import { resolveConfigDir, resolveUserPath } from "../utils.js";
 import { resolveBundledPluginsDir } from "./bundled-dir.js";
 import { getPackageManifestMetadata, } from "./manifest.js";
+import { formatPosixMode, isPathInside, safeRealpathSync, safeStatSync } from "./path-safety.js";
 const EXTENSION_EXTS = new Set([".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"]);
+function currentUid(overrideUid) {
+    if (overrideUid !== undefined) {
+        return overrideUid;
+    }
+    if (process.platform === "win32") {
+        return null;
+    }
+    if (typeof process.getuid !== "function") {
+        return null;
+    }
+    return process.getuid();
+}
+function checkSourceEscapesRoot(params) {
+    const sourceRealPath = safeRealpathSync(params.source);
+    const rootRealPath = safeRealpathSync(params.rootDir);
+    if (!sourceRealPath || !rootRealPath) {
+        return null;
+    }
+    if (isPathInside(rootRealPath, sourceRealPath)) {
+        return null;
+    }
+    return {
+        reason: "source_escapes_root",
+        sourcePath: params.source,
+        rootPath: params.rootDir,
+        targetPath: params.source,
+        sourceRealPath,
+        rootRealPath,
+    };
+}
+function checkPathStatAndPermissions(params) {
+    if (process.platform === "win32") {
+        return null;
+    }
+    const pathsToCheck = [params.rootDir, params.source];
+    const seen = new Set();
+    for (const targetPath of pathsToCheck) {
+        const normalized = path.resolve(targetPath);
+        if (seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        const stat = safeStatSync(targetPath);
+        if (!stat) {
+            return {
+                reason: "path_stat_failed",
+                sourcePath: params.source,
+                rootPath: params.rootDir,
+                targetPath,
+            };
+        }
+        const modeBits = stat.mode & 0o777;
+        if ((modeBits & 0o002) !== 0) {
+            return {
+                reason: "path_world_writable",
+                sourcePath: params.source,
+                rootPath: params.rootDir,
+                targetPath,
+                modeBits,
+            };
+        }
+        if (params.origin !== "bundled" &&
+            params.uid !== null &&
+            typeof stat.uid === "number" &&
+            stat.uid !== params.uid &&
+            stat.uid !== 0) {
+            return {
+                reason: "path_suspicious_ownership",
+                sourcePath: params.source,
+                rootPath: params.rootDir,
+                targetPath,
+                foundUid: stat.uid,
+                expectedUid: params.uid,
+            };
+        }
+    }
+    return null;
+}
+function findCandidateBlockIssue(params) {
+    const escaped = checkSourceEscapesRoot({
+        source: params.source,
+        rootDir: params.rootDir,
+    });
+    if (escaped) {
+        return escaped;
+    }
+    return checkPathStatAndPermissions({
+        source: params.source,
+        rootDir: params.rootDir,
+        origin: params.origin,
+        uid: currentUid(params.ownershipUid),
+    });
+}
+function formatCandidateBlockMessage(issue) {
+    if (issue.reason === "source_escapes_root") {
+        return `blocked plugin candidate: source escapes plugin root (${issue.sourcePath} -> ${issue.sourceRealPath}; root=${issue.rootRealPath})`;
+    }
+    if (issue.reason === "path_stat_failed") {
+        return `blocked plugin candidate: cannot stat path (${issue.targetPath})`;
+    }
+    if (issue.reason === "path_world_writable") {
+        return `blocked plugin candidate: world-writable path (${issue.targetPath}, mode=${formatPosixMode(issue.modeBits ?? 0)})`;
+    }
+    return `blocked plugin candidate: suspicious ownership (${issue.targetPath}, uid=${issue.foundUid}, expected uid=${issue.expectedUid} or root)`;
+}
+function isUnsafePluginCandidate(params) {
+    const issue = findCandidateBlockIssue({
+        source: params.source,
+        rootDir: params.rootDir,
+        origin: params.origin,
+        ownershipUid: params.ownershipUid,
+    });
+    if (!issue) {
+        return false;
+    }
+    params.diagnostics.push({
+        level: "warn",
+        source: issue.targetPath,
+        message: formatCandidateBlockMessage(issue),
+    });
+    return true;
+}
 function isExtensionFile(filePath) {
     const ext = path.extname(filePath);
-    if (!EXTENSION_EXTS.has(ext))
+    if (!EXTENSION_EXTS.has(ext)) {
         return false;
+    }
     return !filePath.endsWith(".d.ts");
 }
 function readPackageManifest(dir) {
     const manifestPath = path.join(dir, "package.json");
-    if (!fs.existsSync(manifestPath))
+    if (!fs.existsSync(manifestPath)) {
         return null;
+    }
     try {
         const raw = fs.readFileSync(manifestPath, "utf-8");
         return JSON.parse(raw);
@@ -24,34 +150,48 @@ function readPackageManifest(dir) {
 }
 function resolvePackageExtensions(manifest) {
     const raw = getPackageManifestMetadata(manifest)?.extensions;
-    if (!Array.isArray(raw))
+    if (!Array.isArray(raw)) {
         return [];
+    }
     return raw.map((entry) => (typeof entry === "string" ? entry.trim() : "")).filter(Boolean);
 }
 function deriveIdHint(params) {
     const base = path.basename(params.filePath, path.extname(params.filePath));
     const rawPackageName = params.packageName?.trim();
-    if (!rawPackageName)
+    if (!rawPackageName) {
         return base;
+    }
     // Prefer the unscoped name so config keys stay stable even when the npm
     // package is scoped (example: @poolbot/voice-call -> voice-call).
     const unscoped = rawPackageName.includes("/")
         ? (rawPackageName.split("/").pop() ?? rawPackageName)
         : rawPackageName;
-    if (!params.hasMultipleExtensions)
+    if (!params.hasMultipleExtensions) {
         return unscoped;
+    }
     return `${unscoped}/${base}`;
 }
 function addCandidate(params) {
     const resolved = path.resolve(params.source);
-    if (params.seen.has(resolved))
+    if (params.seen.has(resolved)) {
         return;
+    }
+    const resolvedRoot = path.resolve(params.rootDir);
+    if (isUnsafePluginCandidate({
+        source: resolved,
+        rootDir: resolvedRoot,
+        origin: params.origin,
+        diagnostics: params.diagnostics,
+        ownershipUid: params.ownershipUid,
+    })) {
+        return;
+    }
     params.seen.add(resolved);
     const manifest = params.manifest ?? null;
     params.candidates.push({
         idHint: params.idHint,
         source: resolved,
-        rootDir: path.resolve(params.rootDir),
+        rootDir: resolvedRoot,
         origin: params.origin,
         workspaceDir: params.workspaceDir,
         packageName: manifest?.name?.trim() || undefined,
@@ -61,9 +201,24 @@ function addCandidate(params) {
         packagePoolbot: getPackageManifestMetadata(manifest ?? undefined),
     });
 }
+function resolvePackageEntrySource(params) {
+    const source = path.resolve(params.packageDir, params.entryPath);
+    if (!isPathInsideWithRealpath(params.packageDir, source, {
+        requireRealpath: true,
+    })) {
+        params.diagnostics.push({
+            level: "error",
+            message: `extension entry escapes package directory: ${params.entryPath}`,
+            source: params.sourceLabel,
+        });
+        return null;
+    }
+    return source;
+}
 function discoverInDirectory(params) {
-    if (!fs.existsSync(params.dir))
+    if (!fs.existsSync(params.dir)) {
         return;
+    }
     let entries = [];
     try {
         entries = fs.readdirSync(params.dir, { withFileTypes: true });
@@ -79,27 +234,40 @@ function discoverInDirectory(params) {
     for (const entry of entries) {
         const fullPath = path.join(params.dir, entry.name);
         if (entry.isFile()) {
-            if (!isExtensionFile(fullPath))
+            if (!isExtensionFile(fullPath)) {
                 continue;
+            }
             addCandidate({
                 candidates: params.candidates,
+                diagnostics: params.diagnostics,
                 seen: params.seen,
                 idHint: path.basename(entry.name, path.extname(entry.name)),
                 source: fullPath,
                 rootDir: path.dirname(fullPath),
                 origin: params.origin,
+                ownershipUid: params.ownershipUid,
                 workspaceDir: params.workspaceDir,
             });
         }
-        if (!entry.isDirectory())
+        if (!entry.isDirectory()) {
             continue;
+        }
         const manifest = readPackageManifest(fullPath);
         const extensions = manifest ? resolvePackageExtensions(manifest) : [];
         if (extensions.length > 0) {
             for (const extPath of extensions) {
-                const resolved = path.resolve(fullPath, extPath);
+                const resolved = resolvePackageEntrySource({
+                    packageDir: fullPath,
+                    entryPath: extPath,
+                    sourceLabel: fullPath,
+                    diagnostics: params.diagnostics,
+                });
+                if (!resolved) {
+                    continue;
+                }
                 addCandidate({
                     candidates: params.candidates,
+                    diagnostics: params.diagnostics,
                     seen: params.seen,
                     idHint: deriveIdHint({
                         filePath: resolved,
@@ -109,6 +277,7 @@ function discoverInDirectory(params) {
                     source: resolved,
                     rootDir: fullPath,
                     origin: params.origin,
+                    ownershipUid: params.ownershipUid,
                     workspaceDir: params.workspaceDir,
                     manifest,
                     packageDir: fullPath,
@@ -123,11 +292,13 @@ function discoverInDirectory(params) {
         if (indexFile && isExtensionFile(indexFile)) {
             addCandidate({
                 candidates: params.candidates,
+                diagnostics: params.diagnostics,
                 seen: params.seen,
                 idHint: entry.name,
                 source: indexFile,
                 rootDir: fullPath,
                 origin: params.origin,
+                ownershipUid: params.ownershipUid,
                 workspaceDir: params.workspaceDir,
                 manifest,
                 packageDir: fullPath,
@@ -157,11 +328,13 @@ function discoverFromPath(params) {
         }
         addCandidate({
             candidates: params.candidates,
+            diagnostics: params.diagnostics,
             seen: params.seen,
             idHint: path.basename(resolved, path.extname(resolved)),
             source: resolved,
             rootDir: path.dirname(resolved),
             origin: params.origin,
+            ownershipUid: params.ownershipUid,
             workspaceDir: params.workspaceDir,
         });
         return;
@@ -171,9 +344,18 @@ function discoverFromPath(params) {
         const extensions = manifest ? resolvePackageExtensions(manifest) : [];
         if (extensions.length > 0) {
             for (const extPath of extensions) {
-                const source = path.resolve(resolved, extPath);
+                const source = resolvePackageEntrySource({
+                    packageDir: resolved,
+                    entryPath: extPath,
+                    sourceLabel: resolved,
+                    diagnostics: params.diagnostics,
+                });
+                if (!source) {
+                    continue;
+                }
                 addCandidate({
                     candidates: params.candidates,
+                    diagnostics: params.diagnostics,
                     seen: params.seen,
                     idHint: deriveIdHint({
                         filePath: source,
@@ -183,6 +365,7 @@ function discoverFromPath(params) {
                     source,
                     rootDir: resolved,
                     origin: params.origin,
+                    ownershipUid: params.ownershipUid,
                     workspaceDir: params.workspaceDir,
                     manifest,
                     packageDir: resolved,
@@ -197,11 +380,13 @@ function discoverFromPath(params) {
         if (indexFile && isExtensionFile(indexFile)) {
             addCandidate({
                 candidates: params.candidates,
+                diagnostics: params.diagnostics,
                 seen: params.seen,
                 idHint: path.basename(resolved),
                 source: indexFile,
                 rootDir: resolved,
                 origin: params.origin,
+                ownershipUid: params.ownershipUid,
                 workspaceDir: params.workspaceDir,
                 manifest,
                 packageDir: resolved,
@@ -211,6 +396,7 @@ function discoverFromPath(params) {
         discoverInDirectory({
             dir: resolved,
             origin: params.origin,
+            ownershipUid: params.ownershipUid,
             workspaceDir: params.workspaceDir,
             candidates: params.candidates,
             diagnostics: params.diagnostics,
@@ -226,14 +412,17 @@ export function discoverPoolBotPlugins(params) {
     const workspaceDir = params.workspaceDir?.trim();
     const extra = params.extraPaths ?? [];
     for (const extraPath of extra) {
-        if (typeof extraPath !== "string")
+        if (typeof extraPath !== "string") {
             continue;
+        }
         const trimmed = extraPath.trim();
-        if (!trimmed)
+        if (!trimmed) {
             continue;
+        }
         discoverFromPath({
             rawPath: trimmed,
             origin: "config",
+            ownershipUid: params.ownershipUid,
             workspaceDir: workspaceDir?.trim() || undefined,
             candidates,
             diagnostics,
@@ -242,20 +431,24 @@ export function discoverPoolBotPlugins(params) {
     }
     if (workspaceDir) {
         const workspaceRoot = resolveUserPath(workspaceDir);
-        const workspaceExt = path.join(workspaceRoot, ".poolbot", "extensions");
-        discoverInDirectory({
-            dir: workspaceExt,
-            origin: "workspace",
-            workspaceDir: workspaceRoot,
-            candidates,
-            diagnostics,
-            seen,
-        });
+        const workspaceExtDirs = [path.join(workspaceRoot, ".poolbot", "extensions")];
+        for (const dir of workspaceExtDirs) {
+            discoverInDirectory({
+                dir,
+                origin: "workspace",
+                ownershipUid: params.ownershipUid,
+                workspaceDir: workspaceRoot,
+                candidates,
+                diagnostics,
+                seen,
+            });
+        }
     }
     const globalDir = path.join(resolveConfigDir(), "extensions");
     discoverInDirectory({
         dir: globalDir,
         origin: "global",
+        ownershipUid: params.ownershipUid,
         candidates,
         diagnostics,
         seen,
@@ -265,6 +458,7 @@ export function discoverPoolBotPlugins(params) {
         discoverInDirectory({
             dir: bundledDir,
             origin: "bundled",
+            ownershipUid: params.ownershipUid,
             candidates,
             diagnostics,
             seen,

package/dist/plugins/hook-runner-global.js

@@ -48,6 +48,22 @@ export function getGlobalPluginRegistry() {
 export function hasGlobalHooks(hookName) {
     return globalHookRunner?.hasHooks(hookName) ?? false;
 }
+export async function runGlobalGatewayStopSafely(params) {
+    const hookRunner = getGlobalHookRunner();
+    if (!hookRunner?.hasHooks("gateway_stop")) {
+        return;
+    }
+    try {
+        await hookRunner.runGatewayStop(params.event, params.ctx);
+    }
+    catch (err) {
+        if (params.onError) {
+            params.onError(err);
+            return;
+        }
+        log.warn(`gateway_stop hook failed: ${String(err)}`);
+    }
+}
 /**
  * Reset the global hook runner (for testing).
  */

package/dist/plugins/hooks.js

@@ -29,6 +29,24 @@ export function createHookRunner(registry, options = {}) {
             ? `${acc.prependContext}\n\n${next.prependContext}`
             : (next.prependContext ?? acc?.prependContext),
     });
+    const mergeSubagentSpawningResult = (acc, next) => {
+        if (acc?.status === "error") {
+            return acc;
+        }
+        if (next.status === "error") {
+            return next;
+        }
+        return {
+            status: "ok",
+            threadBindingReady: Boolean(acc?.threadBindingReady || next.threadBindingReady),
+        };
+    };
+    const mergeSubagentDeliveryTargetResult = (acc, next) => {
+        if (acc?.origin) {
+            return acc;
+        }
+        return next;
+    };
     /**
      * Run a hook that doesn't return a value (fire-and-forget style).
      * All handlers are executed in parallel for performance.
@@ -338,6 +356,34 @@ export function createHookRunner(registry, options = {}) {
     async function runSessionEnd(event, ctx) {
         return runVoidHook("session_end", event, ctx);
     }
+    /**
+     * Run subagent_spawning hook.
+     * Runs sequentially so channel plugins can deterministically provision session bindings.
+     */
+    async function runSubagentSpawning(event, ctx) {
+        return runModifyingHook("subagent_spawning", event, ctx, mergeSubagentSpawningResult);
+    }
+    /**
+     * Run subagent_delivery_target hook.
+     * Runs sequentially so channel plugins can deterministically resolve routing.
+     */
+    async function runSubagentDeliveryTarget(event, ctx) {
+        return runModifyingHook("subagent_delivery_target", event, ctx, mergeSubagentDeliveryTargetResult);
+    }
+    /**
+     * Run subagent_spawned hook.
+     * Runs in parallel (fire-and-forget).
+     */
+    async function runSubagentSpawned(event, ctx) {
+        return runVoidHook("subagent_spawned", event, ctx);
+    }
+    /**
+     * Run subagent_ended hook.
+     * Runs in parallel (fire-and-forget).
+     */
+    async function runSubagentEnded(event, ctx) {
+        return runVoidHook("subagent_ended", event, ctx);
+    }
     // =========================================================================
     // Gateway Hooks
     // =========================================================================
@@ -394,6 +440,10 @@ export function createHookRunner(registry, options = {}) {
         // Session hooks
         runSessionStart,
         runSessionEnd,
+        runSubagentSpawning,
+        runSubagentDeliveryTarget,
+        runSubagentSpawned,
+        runSubagentEnded,
         // Gateway hooks
         runGatewayStart,
         runGatewayStop,

package/dist/plugins/install.js

@@ -4,7 +4,8 @@ import { MANIFEST_KEY } from "../compat/legacy-names.js";
 import { extractArchive, fileExists, readJsonFile, resolveArchiveKind, resolvePackedRootDir, } from "../infra/archive.js";
 import { installPackageDir } from "../infra/install-package-dir.js";
 import { resolveSafeInstallDir, safeDirName, unscopedPackageName, } from "../infra/install-safe-path.js";
-import { packNpmSpecToArchive, resolveArchiveSourcePath, withTempDir, } from "../infra/install-source-utils.js";
+import { resolveArchiveSourcePath, withTempDir, } from "../infra/install-source-utils.js";
+import { installFromNpmSpecArchive } from "../infra/npm-pack-install.js";
 import { validateRegistryNpmSpec } from "../infra/npm-registry-spec.js";
 import { extensionUsesSkippedScannerPath, isPathInside } from "../security/scan-paths.js";
 import * as skillScanner from "../security/skill-scanner.js";
@@ -25,7 +26,7 @@ function validatePluginId(pluginId) {
     }
     return null;
 }
-async function ensurePoolbotExtensions(manifest) {
+async function ensurePoolBotExtensions(manifest) {
     const extensions = manifest[MANIFEST_KEY]?.extensions;
     if (!Array.isArray(extensions)) {
         throw new Error("package.json missing poolbot.extensions");
@@ -92,7 +93,7 @@ async function installPluginFromPackageDir(params) {
     }
     let extensions;
     try {
-        extensions = await ensurePoolbotExtensions(manifest);
+        extensions = await ensurePoolBotExtensions(manifest);
     }
     catch (err) {
         return { ok: false, error: String(err) };
@@ -302,26 +303,37 @@ export async function installPluginFromNpmSpec(params) {
     if (specError) {
         return { ok: false, error: specError };
     }
-    return await withTempDir("poolbot-npm-pack-", async (tmpDir) => {
-        logger.info?.(`Downloading ${spec}…`);
-        const packedResult = await packNpmSpecToArchive({
-            spec,
-            timeoutMs,
-            cwd: tmpDir,
-        });
-        if (!packedResult.ok) {
-            return packedResult;
-        }
-        return await installPluginFromArchive({
-            archivePath: packedResult.archivePath,
+    logger.info?.(`Downloading ${spec}…`);
+    const flowResult = await installFromNpmSpecArchive({
+        tempDirPrefix: "poolbot-npm-pack-",
+        spec,
+        timeoutMs,
+        expectedIntegrity: params.expectedIntegrity,
+        onIntegrityDrift: params.onIntegrityDrift,
+        warn: (message) => {
+            logger.warn?.(message);
+        },
+        installFromArchive: async ({ archivePath }) => await installPluginFromArchive({
+            archivePath,
             extensionsDir: params.extensionsDir,
             timeoutMs,
             logger,
             mode,
             dryRun,
             expectedPluginId,
-        });
+        }),
     });
+    if (!flowResult.ok) {
+        return flowResult;
+    }
+    if (!flowResult.installResult.ok) {
+        return flowResult.installResult;
+    }
+    return {
+        ...flowResult.installResult,
+        npmResolution: flowResult.npmResolution,
+        integrityDrift: flowResult.integrityDrift,
+    };
 }
 export async function installPluginFromPath(params) {
     const resolved = resolveUserPath(params.path);