@poolzin/pool-bot 2026.1.39 → 2026.2.1

package/dist/agents/pi-tool-definition-adapter.js

@@ -1,6 +1,16 @@
 import { logDebug, logError } from "../logger.js";
+import { isPlainObject } from "../utils.js";
+import { runBeforeToolCallHook } from "./pi-tools.before-tool-call.js";
 import { normalizeToolName } from "./tool-policy.js";
 import { jsonResult } from "./tools/common.js";
+function isAbortSignal(value) {
+    return typeof value === "object" && value !== null && "aborted" in value;
+}
+function isLegacyToolExecuteArgs(args) {
+    const third = args[2];
+    const fourth = args[3];
+    return isAbortSignal(third) || typeof fourth === "function";
+}
 function describeToolExecutionError(err) {
     if (err instanceof Error) {
         const message = err.message?.trim() ? err.message : String(err);
@@ -8,6 +18,24 @@ function describeToolExecutionError(err) {
     }
     return { message: String(err) };
 }
+function splitToolExecuteArgs(args) {
+    if (isLegacyToolExecuteArgs(args)) {
+        const [toolCallId, params, signal, onUpdate] = args;
+        return {
+            toolCallId,
+            params,
+            onUpdate,
+            signal,
+        };
+    }
+    const [toolCallId, params, onUpdate, _ctx, signal] = args;
+    return {
+        toolCallId,
+        params,
+        onUpdate,
+        signal,
+    };
+}
 export function toToolDefinitions(tools) {
     return tools.map((tool) => {
         const name = tool.name || "tool";
@@ -16,22 +44,22 @@ export function toToolDefinitions(tools) {
             name,
             label: tool.label ?? name,
             description: tool.description ?? "",
-            // biome-ignore lint/suspicious/noExplicitAny: TypeBox schema from pi-agent-core uses a different module instance.
             parameters: tool.parameters,
-            execute: async (toolCallId, params, onUpdate, _ctx, signal) => {
-                // KNOWN: pi-coding-agent `ToolDefinition.execute` has a different signature/order
-                // than pi-agent-core `AgentTool.execute`. This adapter keeps our existing tools intact.
+            execute: async (...args) => {
+                const { toolCallId, params, onUpdate, signal } = splitToolExecuteArgs(args);
                 try {
                     return await tool.execute(toolCallId, params, signal, onUpdate);
                 }
                 catch (err) {
-                    if (signal?.aborted)
+                    if (signal?.aborted) {
                         throw err;
+                    }
                     const name = err && typeof err === "object" && "name" in err
                         ? String(err.name)
                         : "";
-                    if (name === "AbortError")
+                    if (name === "AbortError") {
                         throw err;
+                    }
                     const described = describeToolExecutionError(err);
                     if (described.stack && described.stack !== described.message) {
                         logDebug(`tools: ${normalizedName} failed stack:\n${described.stack}`);
@@ -49,18 +77,31 @@ export function toToolDefinitions(tools) {
 }
 // Convert client tools (OpenResponses hosted tools) to ToolDefinition format
 // These tools are intercepted to return a "pending" result instead of executing
-export function toClientToolDefinitions(tools, onClientToolCall) {
+export function toClientToolDefinitions(tools, onClientToolCall, hookContext) {
     return tools.map((tool) => {
         const func = tool.function;
         return {
             name: func.name,
             label: func.name,
             description: func.description ?? "",
+            // oxlint-disable-next-line typescript/no-explicit-any
             parameters: func.parameters,
-            execute: async (toolCallId, params, _onUpdate, _ctx, _signal) => {
+            execute: async (...args) => {
+                const { toolCallId, params } = splitToolExecuteArgs(args);
+                const outcome = await runBeforeToolCallHook({
+                    toolName: func.name,
+                    params,
+                    toolCallId,
+                    ctx: hookContext,
+                });
+                if (outcome.blocked) {
+                    throw new Error(outcome.reason);
+                }
+                const adjustedParams = outcome.params;
+                const paramsRecord = isPlainObject(adjustedParams) ? adjustedParams : {};
                 // Notify handler that a client tool was called
                 if (onClientToolCall) {
-                    onClientToolCall(func.name, params);
+                    onClientToolCall(func.name, paramsRecord);
                 }
                 // Return a pending result - the client will execute this tool
                 return jsonResult({

package/dist/agents/pi-tools.before-tool-call.js

@@ -0,0 +1,67 @@
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
+import { isPlainObject } from "../utils.js";
+import { normalizeToolName } from "./tool-policy.js";
+const log = createSubsystemLogger("agents/tools");
+export async function runBeforeToolCallHook(args) {
+    const hookRunner = getGlobalHookRunner();
+    if (!hookRunner?.hasHooks("before_tool_call")) {
+        return { blocked: false, params: args.params };
+    }
+    const toolName = normalizeToolName(args.toolName || "tool");
+    const params = args.params;
+    try {
+        const normalizedParams = isPlainObject(params) ? params : {};
+        const hookResult = await hookRunner.runBeforeToolCall({
+            toolName,
+            params: normalizedParams,
+        }, {
+            toolName,
+            agentId: args.ctx?.agentId,
+            sessionKey: args.ctx?.sessionKey,
+        });
+        if (hookResult?.block) {
+            return {
+                blocked: true,
+                reason: hookResult.blockReason || "Tool call blocked by plugin hook",
+            };
+        }
+        if (hookResult?.params && isPlainObject(hookResult.params)) {
+            if (isPlainObject(params)) {
+                return { blocked: false, params: { ...params, ...hookResult.params } };
+            }
+            return { blocked: false, params: hookResult.params };
+        }
+    }
+    catch (err) {
+        const toolCallId = args.toolCallId ? ` toolCallId=${args.toolCallId}` : "";
+        log.warn(`before_tool_call hook failed: tool=${toolName}${toolCallId} error=${String(err)}`);
+    }
+    return { blocked: false, params };
+}
+export function wrapToolWithBeforeToolCallHook(tool, ctx) {
+    const execute = tool.execute;
+    if (!execute) {
+        return tool;
+    }
+    const toolName = tool.name || "tool";
+    return {
+        ...tool,
+        execute: async (toolCallId, params, signal, onUpdate) => {
+            const outcome = await runBeforeToolCallHook({
+                toolName,
+                params,
+                toolCallId,
+                ctx,
+            });
+            if (outcome.blocked) {
+                throw new Error(outcome.reason);
+            }
+            return await execute(toolCallId, outcome.params, signal, onUpdate);
+        },
+    };
+}
+export const __testing = {
+    runBeforeToolCallHook,
+    isPlainObject,
+};

package/dist/agents/pi-tools.js

@@ -6,10 +6,11 @@ import { createExecTool, createProcessTool, } from "./bash-tools.js";
 import { listChannelAgentTools } from "./channel-tools.js";
 import { createPoolBotTools } from "./poolbot-tools.js";
 import { wrapToolWithAbortSignal } from "./pi-tools.abort.js";
+import { wrapToolWithBeforeToolCallHook } from "./pi-tools.before-tool-call.js";
 import { filterToolsByPolicy, isToolAllowedByPolicies, resolveEffectiveToolPolicy, resolveGroupToolPolicy, resolveSubagentToolPolicy, } from "./pi-tools.policy.js";
-import { assertRequiredParams, CLAUDE_PARAM_GROUPS, createMoltbotReadTool, createSandboxedEditTool, createSandboxedReadTool, createSandboxedWriteTool, normalizeToolParams, patchToolSchemaForClaudeCompatibility, wrapToolParamNormalization, } from "./pi-tools.read.js";
+import { assertRequiredParams, CLAUDE_PARAM_GROUPS, createPoolbotReadTool, createSandboxedEditTool, createSandboxedReadTool, createSandboxedWriteTool, normalizeToolParams, patchToolSchemaForClaudeCompatibility, wrapToolParamNormalization, } from "./pi-tools.read.js";
 import { cleanToolSchemaForGemini, normalizeToolParameters } from "./pi-tools.schema.js";
-import { buildPluginToolGroups, collectExplicitAllowlist, expandPolicyWithPluginGroups, normalizeToolName, resolveToolProfilePolicy, stripPluginOnlyAllowlist, } from "./tool-policy.js";
+import { buildPluginToolGroups, collectExplicitAllowlist, expandPolicyWithPluginGroups, normalizeToolName, resolveToolProfilePolicy, stripPluginOnlyAllowlist, applyOwnerOnlyToolPolicy, } from "./tool-policy.js";
 import { getPluginToolMeta } from "../plugins/tools.js";
 import { logWarn } from "../logger.js";
 function isOpenAIProvider(provider) {
@@ -59,7 +60,7 @@ export const __testing = {
     wrapToolParamNormalization,
     assertRequiredParams,
 };
-export function createMoltbotCodingTools(options) {
+export function createPoolbotCodingTools(options) {
     const execToolName = "exec";
     const sandbox = options?.sandbox?.enabled ? options.sandbox : undefined;
     const { agentId, globalPolicy, globalProviderPolicy, agentPolicy, agentProviderPolicy, profile, providerProfile, profileAlsoAllow, providerProfileAlsoAllow, } = resolveEffectiveToolPolicy({
@@ -124,7 +125,7 @@ export function createMoltbotCodingTools(options) {
                 return [createSandboxedReadTool(sandboxRoot)];
             }
             const freshReadTool = createReadTool(workspaceRoot);
-            return [createMoltbotReadTool(freshReadTool)];
+            return [createPoolbotReadTool(freshReadTool)];
         }
         if (tool.name === "bash" || tool.name === execToolName)
             return [];
@@ -226,15 +227,20 @@ export function createMoltbotCodingTools(options) {
             replyToMode: options?.replyToMode,
             hasRepliedRef: options?.hasRepliedRef,
             modelHasVision: options?.modelHasVision,
+            requireExplicitMessageTarget: options?.requireExplicitMessageTarget,
+            disableMessageTool: options?.disableMessageTool,
             requesterAgentIdOverride: agentId,
         }),
     ];
-    const coreToolNames = new Set(tools
+    // Security: treat unknown/undefined as unauthorized (opt-in, not opt-out)
+    const senderIsOwner = options?.senderIsOwner === true;
+    const toolsByAuthorization = applyOwnerOnlyToolPolicy(tools, senderIsOwner);
+    const coreToolNames = new Set(toolsByAuthorization
         .filter((tool) => !getPluginToolMeta(tool))
         .map((tool) => normalizeToolName(tool.name))
         .filter(Boolean));
     const pluginGroups = buildPluginToolGroups({
-        tools,
+        tools: toolsByAuthorization,
         toolMeta: (tool) => getPluginToolMeta(tool),
     });
     const resolvePolicy = (policy, label) => {
@@ -258,8 +264,8 @@ export function createMoltbotCodingTools(options) {
     const sandboxPolicyExpanded = expandPolicyWithPluginGroups(sandbox?.tools, pluginGroups);
     const subagentPolicyExpanded = expandPolicyWithPluginGroups(subagentPolicy, pluginGroups);
     const toolsFiltered = profilePolicyExpanded
-        ? filterToolsByPolicy(tools, profilePolicyExpanded)
-        : tools;
+        ? filterToolsByPolicy(toolsByAuthorization, profilePolicyExpanded)
+        : toolsByAuthorization;
     const providerProfileFiltered = providerProfileExpanded
         ? filterToolsByPolicy(toolsFiltered, providerProfileExpanded)
         : toolsFiltered;
@@ -287,9 +293,13 @@ export function createMoltbotCodingTools(options) {
     // Always normalize tool JSON Schemas before handing them to pi-agent/pi-ai.
     // Without this, some providers (notably OpenAI) will reject root-level union schemas.
     const normalized = subagentFiltered.map(normalizeToolParameters);
+    const withHooks = normalized.map((tool) => wrapToolWithBeforeToolCallHook(tool, {
+        agentId,
+        sessionKey: options?.sessionKey,
+    }));
     const withAbort = options?.abortSignal
-        ? normalized.map((tool) => wrapToolWithAbortSignal(tool, options.abortSignal))
-        : normalized;
+        ? withHooks.map((tool) => wrapToolWithAbortSignal(tool, options.abortSignal))
+        : withHooks;
     // NOTE: Keep canonical (lowercase) tool names here.
     // pi-ai's Anthropic OAuth transport remaps tool names to Claude Code-style names
     // on the wire and maps them back for tool dispatch.

package/dist/agents/pi-tools.read.js

@@ -199,7 +199,7 @@ function wrapSandboxPathGuard(tool, root) {
 }
 export function createSandboxedReadTool(root) {
     const base = createReadTool(root);
-    return wrapSandboxPathGuard(createMoltbotReadTool(base), root);
+    return wrapSandboxPathGuard(createPoolbotReadTool(base), root);
 }
 export function createSandboxedWriteTool(root) {
     const base = createWriteTool(root);
@@ -209,7 +209,7 @@ export function createSandboxedEditTool(root) {
     const base = createEditTool(root);
     return wrapSandboxPathGuard(wrapToolParamNormalization(base, CLAUDE_PARAM_GROUPS.edit), root);
 }
-export function createMoltbotReadTool(base) {
+export function createPoolbotReadTool(base) {
     const patched = patchToolSchemaForClaudeCompatibility(base);
     return {
         ...patched,

package/dist/agents/poolbot-tools.js

@@ -32,6 +32,20 @@ export function createPoolBotTools(options) {
         config: options?.config,
         sandboxed: options?.sandboxed,
     });
+    const messageTool = options?.disableMessageTool
+        ? null
+        : createMessageTool({
+            agentAccountId: options?.agentAccountId,
+            agentSessionKey: options?.agentSessionKey,
+            config: options?.config,
+            currentChannelId: options?.currentChannelId,
+            currentChannelProvider: options?.agentChannel,
+            currentThreadTs: options?.currentThreadTs,
+            replyToMode: options?.replyToMode,
+            hasRepliedRef: options?.hasRepliedRef,
+            sandboxRoot: options?.sandboxRoot,
+            requireExplicitTarget: options?.requireExplicitMessageTarget,
+        });
     const tools = [
         createBrowserTool({
             sandboxBridgeUrl: options?.sandboxBrowserBridgeUrl,
@@ -45,16 +59,7 @@ export function createPoolBotTools(options) {
         createCronTool({
             agentSessionKey: options?.agentSessionKey,
         }),
-        createMessageTool({
-            agentAccountId: options?.agentAccountId,
-            agentSessionKey: options?.agentSessionKey,
-            config: options?.config,
-            currentChannelId: options?.currentChannelId,
-            currentChannelProvider: options?.agentChannel,
-            currentThreadTs: options?.currentThreadTs,
-            replyToMode: options?.replyToMode,
-            hasRepliedRef: options?.hasRepliedRef,
-        }),
+        ...(messageTool ? [messageTool] : []),
         createTtsTool({
             agentChannel: options?.agentChannel,
             config: options?.config,

package/dist/agents/sandbox-paths.js

@@ -1,6 +1,9 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+const HTTP_URL_RE = /^https?:\/\//i;
+const DATA_URL_RE = /^data:/i;
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 function normalizeUnicodeSpaces(str) {
     return str.replace(UNICODE_SPACES, " ");
@@ -38,6 +41,34 @@ export async function assertSandboxPath(params) {
     await assertNoSymlink(resolved.relative, path.resolve(params.root));
     return resolved;
 }
+export function assertMediaNotDataUrl(media) {
+    const raw = media.trim();
+    if (DATA_URL_RE.test(raw)) {
+        throw new Error("data: URLs are not supported for media. Use buffer instead.");
+    }
+}
+export async function resolveSandboxedMediaSource(params) {
+    const raw = params.media.trim();
+    if (!raw)
+        return raw;
+    if (HTTP_URL_RE.test(raw))
+        return raw;
+    let candidate = raw;
+    if (/^file:\/\//i.test(candidate)) {
+        try {
+            candidate = fileURLToPath(candidate);
+        }
+        catch {
+            throw new Error(`Invalid file:// URL for sandboxed media: ${raw}`);
+        }
+    }
+    const resolved = await assertSandboxPath({
+        filePath: candidate,
+        cwd: params.sandboxRoot,
+        root: params.sandboxRoot,
+    });
+    return resolved.resolved;
+}
 async function assertNoSymlink(relative, root) {
     if (!relative)
         return;

package/dist/agents/session-file-repair.js

@@ -0,0 +1,83 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+function isSessionHeader(entry) {
+    if (!entry || typeof entry !== "object") {
+        return false;
+    }
+    const record = entry;
+    return record.type === "session" && typeof record.id === "string" && record.id.length > 0;
+}
+export async function repairSessionFileIfNeeded(params) {
+    const sessionFile = params.sessionFile.trim();
+    if (!sessionFile) {
+        return { repaired: false, droppedLines: 0, reason: "missing session file" };
+    }
+    let content;
+    try {
+        content = await fs.readFile(sessionFile, "utf-8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT") {
+            return { repaired: false, droppedLines: 0, reason: "missing session file" };
+        }
+        const reason = `failed to read session file: ${err instanceof Error ? err.message : "unknown error"}`;
+        params.warn?.(`session file repair skipped: ${reason} (${path.basename(sessionFile)})`);
+        return { repaired: false, droppedLines: 0, reason };
+    }
+    const lines = content.split(/\r?\n/);
+    const entries = [];
+    let droppedLines = 0;
+    for (const line of lines) {
+        if (!line.trim()) {
+            continue;
+        }
+        try {
+            const entry = JSON.parse(line);
+            entries.push(entry);
+        }
+        catch {
+            droppedLines += 1;
+        }
+    }
+    if (entries.length === 0) {
+        return { repaired: false, droppedLines, reason: "empty session file" };
+    }
+    if (!isSessionHeader(entries[0])) {
+        params.warn?.(`session file repair skipped: invalid session header (${path.basename(sessionFile)})`);
+        return { repaired: false, droppedLines, reason: "invalid session header" };
+    }
+    if (droppedLines === 0) {
+        return { repaired: false, droppedLines: 0 };
+    }
+    const cleaned = `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+    const backupPath = `${sessionFile}.bak-${process.pid}-${Date.now()}`;
+    const tmpPath = `${sessionFile}.repair-${process.pid}-${Date.now()}.tmp`;
+    try {
+        const stat = await fs.stat(sessionFile).catch(() => null);
+        await fs.writeFile(backupPath, content, "utf-8");
+        if (stat) {
+            await fs.chmod(backupPath, stat.mode);
+        }
+        await fs.writeFile(tmpPath, cleaned, "utf-8");
+        if (stat) {
+            await fs.chmod(tmpPath, stat.mode);
+        }
+        await fs.rename(tmpPath, sessionFile);
+    }
+    catch (err) {
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch (cleanupErr) {
+            params.warn?.(`session file repair cleanup failed: ${cleanupErr instanceof Error ? cleanupErr.message : "unknown error"} (${path.basename(tmpPath)})`);
+        }
+        return {
+            repaired: false,
+            droppedLines,
+            reason: `repair failed: ${err instanceof Error ? err.message : "unknown error"}`,
+        };
+    }
+    params.warn?.(`session file repaired: dropped ${droppedLines} malformed line(s) (${path.basename(sessionFile)})`);
+    return { repaired: true, droppedLines, backupPath };
+}

package/dist/agents/session-tool-result-guard.js

@@ -1,16 +1,76 @@
-import { makeMissingToolResult } from "./session-transcript-repair.js";
 import { emitSessionTranscriptUpdate } from "../sessions/transcript-events.js";
+import { HARD_MAX_TOOL_RESULT_CHARS } from "./pi-embedded-runner/tool-result-truncation.js";
+import { makeMissingToolResult, sanitizeToolCallInputs } from "./session-transcript-repair.js";
+const GUARD_TRUNCATION_SUFFIX = "\n\n⚠️ [Content truncated during persistence — original exceeded size limit. " +
+    "Use offset/limit parameters or request specific sections for large content.]";
+/**
+ * Truncate oversized text content blocks in a tool result message.
+ * Returns the original message if under the limit, or a new message with
+ * truncated text blocks otherwise.
+ */
+function capToolResultSize(msg) {
+    const role = msg.role;
+    if (role !== "toolResult") {
+        return msg;
+    }
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+        return msg;
+    }
+    // Calculate total text size
+    let totalTextChars = 0;
+    for (const block of content) {
+        if (block && typeof block === "object" && block.type === "text") {
+            const text = block.text;
+            if (typeof text === "string") {
+                totalTextChars += text.length;
+            }
+        }
+    }
+    if (totalTextChars <= HARD_MAX_TOOL_RESULT_CHARS) {
+        return msg;
+    }
+    // Truncate proportionally
+    const newContent = content.map((block) => {
+        if (!block || typeof block !== "object" || block.type !== "text") {
+            return block;
+        }
+        const textBlock = block;
+        if (typeof textBlock.text !== "string") {
+            return block;
+        }
+        const blockShare = textBlock.text.length / totalTextChars;
+        const blockBudget = Math.max(2_000, Math.floor(HARD_MAX_TOOL_RESULT_CHARS * blockShare) - GUARD_TRUNCATION_SUFFIX.length);
+        if (textBlock.text.length <= blockBudget) {
+            return block;
+        }
+        // Try to cut at a newline boundary
+        let cutPoint = blockBudget;
+        const lastNewline = textBlock.text.lastIndexOf("\n", blockBudget);
+        if (lastNewline > blockBudget * 0.8) {
+            cutPoint = lastNewline;
+        }
+        return {
+            ...textBlock,
+            text: textBlock.text.slice(0, cutPoint) + GUARD_TRUNCATION_SUFFIX,
+        };
+    });
+    return { ...msg, content: newContent };
+}
 function extractAssistantToolCalls(msg) {
     const content = msg.content;
-    if (!Array.isArray(content))
+    if (!Array.isArray(content)) {
         return [];
+    }
     const toolCalls = [];
     for (const block of content) {
-        if (!block || typeof block !== "object")
+        if (!block || typeof block !== "object") {
             continue;
+        }
         const rec = block;
-        if (typeof rec.id !== "string" || !rec.id)
+        if (typeof rec.id !== "string" || !rec.id) {
             continue;
+        }
         if (rec.type === "toolCall" || rec.type === "toolUse" || rec.type === "functionCall") {
             toolCalls.push({
                 id: rec.id,
@@ -22,11 +82,13 @@ function extractAssistantToolCalls(msg) {
 }
 function extractToolResultId(msg) {
     const toolCallId = msg.toolCallId;
-    if (typeof toolCallId === "string" && toolCallId)
+    if (typeof toolCallId === "string" && toolCallId) {
         return toolCallId;
+    }
     const toolUseId = msg.toolUseId;
-    if (typeof toolUseId === "string" && toolUseId)
+    if (typeof toolUseId === "string" && toolUseId) {
         return toolUseId;
+    }
     return null;
 }
 export function installSessionToolResultGuard(sessionManager, opts) {
@@ -38,8 +100,9 @@ export function installSessionToolResultGuard(sessionManager, opts) {
     };
     const allowSyntheticToolResults = opts?.allowSyntheticToolResults ?? true;
     const flushPendingToolResults = () => {
-        if (pending.size === 0)
+        if (pending.size === 0) {
             return;
+        }
         if (allowSyntheticToolResults) {
             for (const [id, name] of pending.entries()) {
                 const synthetic = makeMissingToolResult({ toolCallId: id, toolName: name });
@@ -53,24 +116,40 @@ export function installSessionToolResultGuard(sessionManager, opts) {
         pending.clear();
     };
     const guardedAppend = (message) => {
+        let nextMessage = message;
         const role = message.role;
-        if (role === "toolResult") {
-            const id = extractToolResultId(message);
+        if (role === "assistant") {
+            const sanitized = sanitizeToolCallInputs([message]);
+            if (sanitized.length === 0) {
+                if (allowSyntheticToolResults && pending.size > 0) {
+                    flushPendingToolResults();
+                }
+                return undefined;
+            }
+            nextMessage = sanitized[0];
+        }
+        const nextRole = nextMessage.role;
+        if (nextRole === "toolResult") {
+            const id = extractToolResultId(nextMessage);
             const toolName = id ? pending.get(id) : undefined;
-            if (id)
+            if (id) {
                 pending.delete(id);
-            return originalAppend(persistToolResult(message, {
+            }
+            // Apply hard size cap before persistence to prevent oversized tool results
+            // from consuming the entire context window on subsequent LLM calls.
+            const capped = capToolResultSize(nextMessage);
+            return originalAppend(persistToolResult(capped, {
                 toolCallId: id ?? undefined,
                 toolName,
                 isSynthetic: false,
             }));
         }
-        const toolCalls = role === "assistant"
-            ? extractAssistantToolCalls(message)
+        const toolCalls = nextRole === "assistant"
+            ? extractAssistantToolCalls(nextMessage)
             : [];
         if (allowSyntheticToolResults) {
             // If previous tool calls are still pending, flush before non-tool results.
-            if (pending.size > 0 && (toolCalls.length === 0 || role !== "assistant")) {
+            if (pending.size > 0 && (toolCalls.length === 0 || nextRole !== "assistant")) {
                 flushPendingToolResults();
             }
             // If new tool calls arrive while older ones are pending, flush the old ones first.
@@ -78,7 +157,7 @@ export function installSessionToolResultGuard(sessionManager, opts) {
                 flushPendingToolResults();
             }
         }
-        const result = originalAppend(message);
+        const result = originalAppend(nextMessage);
         const sessionFile = sessionManager.getSessionFile?.();
         if (sessionFile) {
             emitSessionTranscriptUpdate(sessionFile);