@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/agents/tool-images.js

@@ -1,5 +1,5 @@
 import { createSubsystemLogger } from "../logging/subsystem.js";
-import { getImageMetadata, resizeToJpeg } from "../media/image-ops.js";
+import { buildImageResizeSideGrid, getImageMetadata, IMAGE_REDUCE_QUALITY_STEPS, resizeToJpeg, } from "../media/image-ops.js";
 import { DEFAULT_IMAGE_MAX_BYTES, DEFAULT_IMAGE_MAX_DIMENSION_PX, } from "./image-sanitization.js";
 // Anthropic Messages API limitations (observed in Pool Bot sessions):
 // - Images over ~2000px per side can fail in multi-image requests.
@@ -49,6 +49,68 @@ function formatBytesShort(bytes) {
     }
     return `${(bytes / (1024 * 1024)).toFixed(2)}MB`;
 }
+function parseMediaPathFromText(text) {
+    for (const line of text.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("MEDIA:")) {
+            continue;
+        }
+        const raw = trimmed.slice("MEDIA:".length).trim();
+        if (!raw) {
+            continue;
+        }
+        const backtickWrapped = raw.match(/^`([^`]+)`$/u);
+        return (backtickWrapped?.[1] ?? raw).trim();
+    }
+    return undefined;
+}
+function fileNameFromPathLike(pathLike) {
+    const value = pathLike.trim();
+    if (!value) {
+        return undefined;
+    }
+    try {
+        const url = new URL(value);
+        const candidate = url.pathname.split("/").filter(Boolean).at(-1);
+        return candidate && candidate.length > 0 ? candidate : undefined;
+    }
+    catch {
+        // Not a URL; continue with path-like parsing.
+    }
+    const normalized = value.replaceAll("\\", "/");
+    const candidate = normalized.split("/").filter(Boolean).at(-1);
+    return candidate && candidate.length > 0 ? candidate : undefined;
+}
+function inferImageFileName(params) {
+    const rec = params.block;
+    const explicitKeys = ["fileName", "filename", "path", "url"];
+    for (const key of explicitKeys) {
+        const raw = rec[key];
+        if (typeof raw !== "string" || raw.trim().length === 0) {
+            continue;
+        }
+        const candidate = fileNameFromPathLike(raw);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    if (typeof rec.name === "string" && rec.name.trim().length > 0) {
+        return rec.name.trim();
+    }
+    if (params.mediaPathHint) {
+        const candidate = fileNameFromPathLike(params.mediaPathHint);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    if (typeof params.label === "string" && params.label.startsWith("read:")) {
+        const candidate = fileNameFromPathLike(params.label.slice("read:".length));
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
 async function resizeImageBase64IfNeeded(params) {
     const buf = Buffer.from(params.base64, "base64");
     const meta = await getImageMetadata(buf);
@@ -69,16 +131,12 @@ async function resizeImageBase64IfNeeded(params) {
             height,
         };
     }
-    const qualities = [85, 75, 65, 55, 45, 35];
     const maxDim = hasDimensions ? Math.max(width ?? 0, height ?? 0) : params.maxDimensionPx;
     const sideStart = maxDim > 0 ? Math.min(params.maxDimensionPx, maxDim) : params.maxDimensionPx;
-    const sideGrid = [sideStart, 1800, 1600, 1400, 1200, 1000, 800]
-        .filter((v) => v > 0 && v <= params.maxDimensionPx)
-        .filter((v, i, arr) => v > 0 && arr.indexOf(v) === i)
-        .toSorted((a, b) => b - a);
+    const sideGrid = buildImageResizeSideGrid(params.maxDimensionPx, sideStart);
     let smallest = null;
     for (const side of sideGrid) {
-        for (const quality of qualities) {
+        for (const quality of IMAGE_REDUCE_QUALITY_STEPS) {
             const out = await resizeToJpeg({
                 buffer: buf,
                 maxSide: side,
@@ -92,11 +150,15 @@ async function resizeImageBase64IfNeeded(params) {
                 const sourcePixels = typeof width === "number" && typeof height === "number"
                     ? `${width}x${height}px`
                     : "unknown";
+                const sourceWithFile = params.fileName
+                    ? `${params.fileName} ${sourcePixels}`
+                    : sourcePixels;
                 const byteReductionPct = buf.byteLength > 0
                     ? Number((((buf.byteLength - out.byteLength) / buf.byteLength) * 100).toFixed(1))
                     : 0;
-                log.info(`Image resized to fit limits: ${sourcePixels} ${formatBytesShort(buf.byteLength)} -> ${formatBytesShort(out.byteLength)} (-${byteReductionPct}%)`, {
+                log.info(`Image resized to fit limits: ${sourceWithFile} ${formatBytesShort(buf.byteLength)} -> ${formatBytesShort(out.byteLength)} (-${byteReductionPct}%)`, {
                     label: params.label,
+                    fileName: params.fileName,
                     sourceMimeType: params.mimeType,
                     sourceWidth: width,
                     sourceHeight: height,
@@ -125,8 +187,10 @@ async function resizeImageBase64IfNeeded(params) {
     const maxMb = (params.maxBytes / (1024 * 1024)).toFixed(0);
     const gotMb = (best.byteLength / (1024 * 1024)).toFixed(2);
     const sourcePixels = typeof width === "number" && typeof height === "number" ? `${width}x${height}px` : "unknown";
-    log.warn(`Image resize failed to fit limits: ${sourcePixels} best=${formatBytesShort(best.byteLength)} limit=${formatBytesShort(params.maxBytes)}`, {
+    const sourceWithFile = params.fileName ? `${params.fileName} ${sourcePixels}` : sourcePixels;
+    log.warn(`Image resize failed to fit limits: ${sourceWithFile} best=${formatBytesShort(best.byteLength)} limit=${formatBytesShort(params.maxBytes)}`, {
         label: params.label,
+        fileName: params.fileName,
         sourceMimeType: params.mimeType,
         sourceWidth: width,
         sourceHeight: height,
@@ -143,7 +207,14 @@ export async function sanitizeContentBlocksImages(blocks, label, opts = {}) {
     const maxDimensionPx = Math.max(opts.maxDimensionPx ?? MAX_IMAGE_DIMENSION_PX, 1);
     const maxBytes = Math.max(opts.maxBytes ?? MAX_IMAGE_BYTES, 1);
     const out = [];
+    let mediaPathHint;
     for (const block of blocks) {
+        if (isTextBlock(block)) {
+            const mediaPath = parseMediaPathFromText(block.text);
+            if (mediaPath) {
+                mediaPathHint = mediaPath;
+            }
+        }
         if (!isImageBlock(block)) {
             out.push(block);
             continue;
@@ -159,12 +230,14 @@ export async function sanitizeContentBlocksImages(blocks, label, opts = {}) {
         try {
             const inferredMimeType = inferMimeTypeFromBase64(data);
             const mimeType = inferredMimeType ?? block.mimeType;
+            const fileName = inferImageFileName({ block, label, mediaPathHint });
             const resized = await resizeImageBase64IfNeeded({
                 base64: data,
                 mimeType,
                 maxDimensionPx,
                 maxBytes,
                 label,
+                fileName,
             });
             out.push({
                 ...block,

package/dist/agents/tool-policy.js

@@ -1,3 +1,15 @@
+// Keep tool-policy browser-safe: do not import tools/common at runtime.
+function wrapOwnerOnlyToolExecution(tool, senderIsOwner) {
+    if (tool.ownerOnly !== true || senderIsOwner || !tool.execute) {
+        return tool;
+    }
+    return {
+        ...tool,
+        execute: async () => {
+            throw new Error("Tool restricted to owner senders.");
+        },
+    };
+}
 const TOOL_NAME_ALIASES = {
     bash: "exec",
     "apply-patch": "apply_patch",
@@ -16,6 +28,7 @@ export const TOOL_GROUPS = {
         "sessions_history",
         "sessions_send",
         "sessions_spawn",
+        "subagents",
         "session_status",
     ],
     // UI helpers
@@ -26,7 +39,7 @@ export const TOOL_GROUPS = {
     "group:messaging": ["message"],
     // Nodes + device tools
     "group:nodes": ["nodes"],
-    // All Poolbot native tools (excludes provider plugins).
+    // All Pool Bot native tools (excludes provider plugins).
     "group:poolbot": [
         "browser",
         "canvas",
@@ -39,6 +52,7 @@ export const TOOL_GROUPS = {
         "sessions_history",
         "sessions_send",
         "sessions_spawn",
+        "subagents",
         "session_status",
         "memory_search",
         "memory_get",
@@ -47,7 +61,7 @@ export const TOOL_GROUPS = {
         "image",
     ],
 };
-const OWNER_ONLY_TOOL_NAMES = new Set(["whatsapp_login"]);
+const OWNER_ONLY_TOOL_NAME_FALLBACKS = new Set(["whatsapp_login", "cron", "gateway"]);
 const TOOL_PROFILES = {
     minimal: {
         allow: ["session_status"],
@@ -71,31 +85,27 @@ export function normalizeToolName(name) {
     return TOOL_NAME_ALIASES[normalized] ?? normalized;
 }
 export function isOwnerOnlyToolName(name) {
-    return OWNER_ONLY_TOOL_NAMES.has(normalizeToolName(name));
+    return OWNER_ONLY_TOOL_NAME_FALLBACKS.has(normalizeToolName(name));
+}
+function isOwnerOnlyTool(tool) {
+    return tool.ownerOnly === true || isOwnerOnlyToolName(tool.name);
 }
 export function applyOwnerOnlyToolPolicy(tools, senderIsOwner) {
     const withGuard = tools.map((tool) => {
-        if (!isOwnerOnlyToolName(tool.name)) {
+        if (!isOwnerOnlyTool(tool)) {
             return tool;
         }
-        if (senderIsOwner || !tool.execute) {
-            return tool;
-        }
-        return {
-            ...tool,
-            execute: async () => {
-                throw new Error("Tool restricted to owner senders.");
-            },
-        };
+        return wrapOwnerOnlyToolExecution(tool, senderIsOwner);
     });
     if (senderIsOwner) {
         return withGuard;
     }
-    return withGuard.filter((tool) => !isOwnerOnlyToolName(tool.name));
+    return withGuard.filter((tool) => !isOwnerOnlyTool(tool));
 }
 export function normalizeToolList(list) {
-    if (!list)
+    if (!list) {
         return [];
+    }
     return list.map(normalizeToolName).filter(Boolean);
 }
 export function expandToolGroups(list) {
@@ -114,14 +124,17 @@ export function expandToolGroups(list) {
 export function collectExplicitAllowlist(policies) {
     const entries = [];
     for (const policy of policies) {
-        if (!policy?.allow)
+        if (!policy?.allow) {
             continue;
+        }
         for (const value of policy.allow) {
-            if (typeof value !== "string")
+            if (typeof value !== "string") {
                 continue;
+            }
             const trimmed = value.trim();
-            if (trimmed)
+            if (trimmed) {
                 entries.push(trimmed);
+            }
         }
     }
     return entries;
@@ -131,8 +144,9 @@ export function buildPluginToolGroups(params) {
     const byPlugin = new Map();
     for (const tool of params.tools) {
         const meta = params.toolMeta(tool);
-        if (!meta)
+        if (!meta) {
             continue;
+        }
         const name = normalizeToolName(tool.name);
         all.push(name);
         const pluginId = meta.pluginId.toLowerCase();
@@ -143,8 +157,9 @@ export function buildPluginToolGroups(params) {
     return { all, byPlugin };
 }
 export function expandPluginGroups(list, groups) {
-    if (!list || list.length === 0)
+    if (!list || list.length === 0) {
         return list;
+    }
     const expanded = [];
     for (const entry of list) {
         const normalized = normalizeToolName(entry);
@@ -167,8 +182,9 @@ export function expandPluginGroups(list, groups) {
     return Array.from(new Set(expanded));
 }
 export function expandPolicyWithPluginGroups(policy, groups) {
-    if (!policy)
+    if (!policy) {
         return undefined;
+    }
     return {
         allow: expandPluginGroups(policy.allow, groups),
         deny: expandPluginGroups(policy.deny, groups),
@@ -187,13 +203,19 @@ export function stripPluginOnlyAllowlist(policy, groups, coreTools) {
     const unknownAllowlist = [];
     let hasCoreEntry = false;
     for (const entry of normalized) {
+        if (entry === "*") {
+            hasCoreEntry = true;
+            continue;
+        }
         const isPluginEntry = entry === "group:plugins" || pluginIds.has(entry) || pluginTools.has(entry);
         const expanded = expandToolGroups([entry]);
         const isCoreEntry = expanded.some((tool) => coreTools.has(tool));
-        if (isCoreEntry)
+        if (isCoreEntry) {
             hasCoreEntry = true;
-        if (!isCoreEntry && !isPluginEntry)
+        }
+        if (!isCoreEntry && !isPluginEntry) {
             unknownAllowlist.push(entry);
+        }
     }
     const strippedAllowlist = !hasCoreEntry;
     // When an allowlist contains only plugin tools, we strip it to avoid accidentally
@@ -209,13 +231,16 @@ export function stripPluginOnlyAllowlist(policy, groups, coreTools) {
     };
 }
 export function resolveToolProfilePolicy(profile) {
-    if (!profile)
+    if (!profile) {
         return undefined;
+    }
     const resolved = TOOL_PROFILES[profile];
-    if (!resolved)
+    if (!resolved) {
         return undefined;
-    if (!resolved.allow && !resolved.deny)
+    }
+    if (!resolved.allow && !resolved.deny) {
         return undefined;
+    }
     return {
         allow: resolved.allow ? [...resolved.allow] : undefined,
         deny: resolved.deny ? [...resolved.deny] : undefined,

package/dist/agents/tools/browser-tool.js

@@ -3,7 +3,7 @@ import { browserAct, browserArmDialog, browserArmFileChooser, browserConsoleMess
 import { browserCloseTab, browserFocusTab, browserOpenTab, browserProfiles, browserSnapshot, browserStart, browserStatus, browserStop, browserTabs, } from "../../browser/client.js";
 import { resolveBrowserConfig } from "../../browser/config.js";
 import { DEFAULT_AI_SNAPSHOT_MAX_CHARS } from "../../browser/constants.js";
-import { DEFAULT_UPLOAD_DIR, resolvePathsWithinRoot } from "../../browser/paths.js";
+import { DEFAULT_UPLOAD_DIR, resolveExistingPathsWithinRoot } from "../../browser/paths.js";
 import { applyBrowserProxyPaths, persistBrowserProxyFiles } from "../../browser/proxy-files.js";
 import { loadConfig } from "../../config/config.js";
 import { wrapExternalContent } from "../../security/external-content.js";
@@ -587,7 +587,7 @@ export function createBrowserTool(opts) {
                     if (paths.length === 0) {
                         throw new Error("paths required");
                     }
-                    const uploadPathsResult = resolvePathsWithinRoot({
+                    const uploadPathsResult = await resolveExistingPathsWithinRoot({
                         rootDir: DEFAULT_UPLOAD_DIR,
                         requestedPaths: paths,
                         scopeLabel: `uploads directory (${DEFAULT_UPLOAD_DIR})`,

package/dist/agents/tools/canvas-tool.js

@@ -1,8 +1,12 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { Type } from "@sinclair/typebox";
 import { writeBase64ToFile } from "../../cli/nodes-camera.js";
 import { canvasSnapshotTempPath, parseCanvasSnapshotPayload } from "../../cli/nodes-canvas.js";
+import { logVerbose, shouldLogVerbose } from "../../globals.js";
+import { isInboundPathAllowed } from "../../media/inbound-path-policy.js";
+import { getDefaultMediaLocalRoots } from "../../media/local-roots.js";
 import { imageMimeFromFormat } from "../../media/mime.js";
 import { resolveImageSanitizationLimits } from "../image-sanitization.js";
 import { optionalStringEnum, stringEnum } from "../schema/typebox.js";
@@ -19,6 +23,28 @@ const CANVAS_ACTIONS = [
     "a2ui_reset",
 ];
 const CANVAS_SNAPSHOT_FORMATS = ["png", "jpg", "jpeg"];
+async function readJsonlFromPath(jsonlPath) {
+    const trimmed = jsonlPath.trim();
+    if (!trimmed) {
+        return "";
+    }
+    const resolved = path.resolve(trimmed);
+    const roots = getDefaultMediaLocalRoots();
+    if (!isInboundPathAllowed({ filePath: resolved, roots })) {
+        if (shouldLogVerbose()) {
+            logVerbose(`Blocked canvas jsonlPath outside allowed roots: ${resolved}`);
+        }
+        throw new Error("jsonlPath outside allowed roots");
+    }
+    const canonical = await fs.realpath(resolved).catch(() => resolved);
+    if (!isInboundPathAllowed({ filePath: canonical, roots })) {
+        if (shouldLogVerbose()) {
+            logVerbose(`Blocked canvas jsonlPath outside allowed roots: ${canonical}`);
+        }
+        throw new Error("jsonlPath outside allowed roots");
+    }
+    return await fs.readFile(canonical, "utf8");
+}
 // Flattened schema: runtime validates per-action requirements.
 const CanvasToolSchema = Type.Object({
     action: stringEnum(CANVAS_ACTIONS),
@@ -145,7 +171,7 @@ export function createCanvasTool(options) {
                     const jsonl = typeof params.jsonl === "string" && params.jsonl.trim()
                         ? params.jsonl
                         : typeof params.jsonlPath === "string" && params.jsonlPath.trim()
-                            ? await fs.readFile(params.jsonlPath.trim(), "utf8")
+                            ? await readJsonlFromPath(params.jsonlPath)
                             : "";
                     if (!jsonl.trim()) {
                         throw new Error("jsonl or jsonlPath required");

package/dist/agents/tools/common.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import { detectMime } from "../../media/mime.js";
 import { sanitizeToolResultImages } from "../tool-images.js";
+export const OWNER_ONLY_TOOL_ERROR = "Tool restricted to owner senders.";
 export class ToolInputError extends Error {
     status = 400;
     constructor(message) {
@@ -8,6 +9,13 @@ export class ToolInputError extends Error {
         this.name = "ToolInputError";
     }
 }
+export class ToolAuthorizationError extends ToolInputError {
+    status = 403;
+    constructor(message) {
+        super(message);
+        this.name = "ToolAuthorizationError";
+    }
+}
 export function createActionGate(actions) {
     return (key, defaultValue = true) => {
         const value = actions?.[key];
@@ -131,6 +139,17 @@ export function jsonResult(payload) {
         details: payload,
     };
 }
+export function wrapOwnerOnlyToolExecution(tool, senderIsOwner) {
+    if (tool.ownerOnly !== true || senderIsOwner || !tool.execute) {
+        return tool;
+    }
+    return {
+        ...tool,
+        execute: async () => {
+            throw new Error(OWNER_ONLY_TOOL_ERROR);
+        },
+    };
+}
 export async function imageResult(params) {
     const content = [
         {
@@ -162,3 +181,29 @@ export async function imageResultFromFile(params) {
         imageSanitization: params.imageSanitization,
     });
 }
+/**
+ * Validate and parse an `availableTags` parameter from untrusted input.
+ * Returns `undefined` when the value is missing or not an array.
+ * Entries that lack a string `name` are silently dropped.
+ */
+export function parseAvailableTags(raw) {
+    if (raw === undefined || raw === null) {
+        return undefined;
+    }
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const result = raw
+        .filter((t) => typeof t === "object" && t !== null && typeof t.name === "string")
+        .map((t) => ({
+        ...(t.id !== undefined && typeof t.id === "string" ? { id: t.id } : {}),
+        name: t.name,
+        ...(typeof t.moderated === "boolean" ? { moderated: t.moderated } : {}),
+        ...(t.emoji_id === null || typeof t.emoji_id === "string" ? { emoji_id: t.emoji_id } : {}),
+        ...(t.emoji_name === null || typeof t.emoji_name === "string"
+            ? { emoji_name: t.emoji_name }
+            : {}),
+    }));
+    // Return undefined instead of empty array to avoid accidentally clearing all tags
+    return result.length ? result : undefined;
+}

package/dist/agents/tools/discord-actions-guild.js

@@ -1,6 +1,6 @@
 import { getPresence } from "../../discord/monitor/presence-cache.js";
 import { addRoleDiscord, createChannelDiscord, createScheduledEventDiscord, deleteChannelDiscord, editChannelDiscord, fetchChannelInfoDiscord, fetchMemberInfoDiscord, fetchRoleInfoDiscord, fetchVoiceStatusDiscord, listGuildChannelsDiscord, listGuildEmojisDiscord, listScheduledEventsDiscord, moveChannelDiscord, removeChannelPermissionDiscord, removeRoleDiscord, setChannelPermissionDiscord, uploadEmojiDiscord, uploadStickerDiscord, } from "../../discord/send.js";
-import { jsonResult, readNumberParam, readStringArrayParam, readStringParam, } from "./common.js";
+import { jsonResult, readNumberParam, parseAvailableTags, readStringArrayParam, readStringParam, } from "./common.js";
 function readParentIdParam(params) {
     if (params.clearParent === true)
         return null;
@@ -280,6 +280,7 @@ export async function handleDiscordGuildAction(action, params, isActionEnabled)
             const rateLimitPerUser = readNumberParam(params, "rateLimitPerUser", {
                 integer: true,
             });
+            const availableTags = parseAvailableTags(params.availableTags);
             const channel = accountId
                 ? await editChannelDiscord({
                     channelId,
@@ -289,6 +290,7 @@ export async function handleDiscordGuildAction(action, params, isActionEnabled)
                     parentId,
                     nsfw,
                     rateLimitPerUser: rateLimitPerUser ?? undefined,
+                    availableTags,
                 }, { accountId })
                 : await editChannelDiscord({
                     channelId,
@@ -298,6 +300,7 @@ export async function handleDiscordGuildAction(action, params, isActionEnabled)
                     parentId,
                     nsfw,
                     rateLimitPerUser: rateLimitPerUser ?? undefined,
+                    availableTags,
                 });
             return jsonResult({ ok: true, channel });
         }

package/dist/agents/tools/gateway-tool.js

@@ -6,6 +6,8 @@ import { formatDoctorNonInteractiveHint, writeRestartSentinel, } from "../../inf
 import { stringEnum } from "../schema/typebox.js";
 import { jsonResult, readStringParam } from "./common.js";
 import { callGatewayTool } from "./gateway.js";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+const log = createSubsystemLogger("gateway-tool");
 function resolveBaseHashFromSnapshot(snapshot) {
     if (!snapshot || typeof snapshot !== "object")
         return undefined;
@@ -121,7 +123,7 @@ export function createGatewayTool(opts) {
                 catch {
                     // ignore: sentinel is best-effort
                 }
-                console.info(`gateway tool: restart requested (delayMs=${delayMs ?? "default"}, reason=${reason ?? "none"})`);
+                log.info(`gateway tool: restart requested (delayMs=${delayMs ?? "default"}, reason=${reason ?? "none"})`);
                 const scheduled = scheduleGatewaySigusr1Restart({
                     delayMs,
                     reason,

package/dist/agents/tools/nodes-utils.js

@@ -1,15 +1,6 @@
+import { parseNodeList, parsePairingList } from "../../shared/node-list-parse.js";
 import { resolveNodeIdFromCandidates } from "../../shared/node-match.js";
 import { callGatewayTool } from "./gateway.js";
-function parseNodeList(value) {
-    const obj = typeof value === "object" && value !== null ? value : {};
-    return Array.isArray(obj.nodes) ? obj.nodes : [];
-}
-function parsePairingList(value) {
-    const obj = typeof value === "object" && value !== null ? value : {};
-    const pending = Array.isArray(obj.pending) ? obj.pending : [];
-    const paired = Array.isArray(obj.paired) ? obj.paired : [];
-    return { pending, paired };
-}
 async function loadNodes(opts) {
     try {
         const res = await callGatewayTool("node.list", opts, {});

package/dist/agents/tools/sessions-send-helpers.js

@@ -7,11 +7,13 @@ const MAX_PING_PONG_TURNS = 5;
 export function resolveAnnounceTargetFromKey(sessionKey) {
     const rawParts = sessionKey.split(":").filter(Boolean);
     const parts = rawParts.length >= 3 && rawParts[0] === "agent" ? rawParts.slice(2) : rawParts;
-    if (parts.length < 3)
+    if (parts.length < 3) {
         return null;
+    }
     const [channelRaw, kind, ...rest] = parts;
-    if (kind !== "group" && kind !== "channel")
+    if (kind !== "group" && kind !== "channel") {
         return null;
+    }
     // Extract topic/thread ID from rest (supports both :topic: and :thread:)
     // Telegram uses :topic:, other platforms use :thread:
     let threadId;
@@ -24,15 +26,18 @@ export function resolveAnnounceTargetFromKey(sessionKey) {
     }
     // Remove :topic:N or :thread:N suffix from ID for target
     const id = match ? restJoined.replace(/:(topic|thread):\d+$/, "") : restJoined.trim();
-    if (!id)
+    if (!id) {
         return null;
-    if (!channelRaw)
+    }
+    if (!channelRaw) {
         return null;
+    }
     const normalizedChannel = normalizeAnyChannelId(channelRaw) ?? normalizeChatChannelId(channelRaw);
     const channel = normalizedChannel ?? channelRaw.toLowerCase();
     const kindTarget = (() => {
-        if (!normalizedChannel)
+        if (!normalizedChannel) {
             return id;
+        }
         if (normalizedChannel === "discord" || normalizedChannel === "slack") {
             return `channel:${id}`;
         }
@@ -109,8 +114,9 @@ export function isReplySkip(text) {
 export function resolvePingPongTurns(cfg) {
     const raw = cfg?.session?.agentToAgent?.maxPingPongTurns;
     const fallback = DEFAULT_PING_PONG_TURNS;
-    if (typeof raw !== "number" || !Number.isFinite(raw))
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
         return fallback;
+    }
     const rounded = Math.floor(raw);
     return Math.max(0, Math.min(MAX_PING_PONG_TURNS, rounded));
 }

package/dist/agents/tools/sessions-spawn-tool.js

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { optionalStringEnum } from "../schema/typebox.js";
-import { spawnSubagentDirect } from "../subagent-spawn.js";
+import { SUBAGENT_SPAWN_MODES, spawnSubagentDirect } from "../subagent-spawn.js";
 import { jsonResult, readStringParam } from "./common.js";
 const SessionsSpawnToolSchema = Type.Object({
     task: Type.String(),
@@ -11,13 +11,15 @@ const SessionsSpawnToolSchema = Type.Object({
     runTimeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
     // Back-compat: older callers used timeoutSeconds for this tool.
     timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),
+    thread: Type.Optional(Type.Boolean()),
+    mode: optionalStringEnum(SUBAGENT_SPAWN_MODES),
     cleanup: optionalStringEnum(["delete", "keep"]),
 });
 export function createSessionsSpawnTool(opts) {
     return {
         label: "Sessions",
         name: "sessions_spawn",
-        description: "Spawn a background sub-agent run in an isolated session and announce the result back to the requester chat.",
+        description: 'Spawn a sub-agent in an isolated session (mode="run" one-shot or mode="session" persistent) and route results back to the requester chat/thread.',
         parameters: SessionsSpawnToolSchema,
         execute: async (_toolCallId, args) => {
             const params = args;
@@ -26,6 +28,7 @@ export function createSessionsSpawnTool(opts) {
             const requestedAgentId = readStringParam(params, "agentId");
             const modelOverride = readStringParam(params, "model");
             const thinkingOverrideRaw = readStringParam(params, "thinking");
+            const mode = params.mode === "run" || params.mode === "session" ? params.mode : undefined;
             const cleanup = params.cleanup === "keep" || params.cleanup === "delete" ? params.cleanup : "keep";
             // Back-compat: older callers used timeoutSeconds for this tool.
             const timeoutSecondsCandidate = typeof params.runTimeoutSeconds === "number"
@@ -36,6 +39,7 @@ export function createSessionsSpawnTool(opts) {
             const runTimeoutSeconds = typeof timeoutSecondsCandidate === "number" && Number.isFinite(timeoutSecondsCandidate)
                 ? Math.max(0, Math.floor(timeoutSecondsCandidate))
                 : undefined;
+            const thread = params.thread === true;
             const result = await spawnSubagentDirect({
                 task,
                 label: label || undefined,
@@ -43,6 +47,8 @@ export function createSessionsSpawnTool(opts) {
                 model: modelOverride,
                 thinking: thinkingOverrideRaw,
                 runTimeoutSeconds,
+                thread,
+                mode,
                 cleanup,
                 expectsCompletionMessage: true,
             }, {

package/dist/agents/tools/subagents-tool.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { Type } from "@sinclair/typebox";
 import { clearSessionQueues } from "../../auto-reply/reply/queue.js";
+import { DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH } from "../../config/agent-limits.js";
 import { loadConfig } from "../../config/config.js";
 import { loadSessionStore, resolveStorePath, updateSessionStore } from "../../config/sessions.js";
 import { callGateway } from "../../gateway/call.js";
@@ -181,7 +182,7 @@ function resolveRequesterKey(params) {
     // Check if this sub-agent can spawn children (orchestrator).
     // If so, it should see its own children, not its parent's children.
     const callerDepth = getSubagentDepthFromSessionStore(callerSessionKey, { cfg: params.cfg });
-    const maxSpawnDepth = params.cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? 1;
+    const maxSpawnDepth = params.cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH;
     if (callerDepth < maxSpawnDepth) {
         // Orchestrator sub-agent: use its own session key as requester
         // so it sees children it spawned.