stratus-sdk 0.7.6 → 0.9.0

package/dist/core/run.js

@@ -1,6 +1,6 @@
 import { RunContext } from "./context";
-import { MaxBudgetExceededError, MaxTurnsExceededError, OutputParseError, RunAbortedError, StratusError, } from "./errors";
-import { runInputGuardrails, runOutputGuardrails } from "./guardrails";
+import { MaxBudgetExceededError, MaxTurnsExceededError, OutputParseError, RunAbortedError, StratusError, ToolTimeoutError, } from "./errors";
+import { runInputGuardrails, runOutputGuardrails, runToolInputGuardrails, runToolOutputGuardrails, } from "./guardrails";
 import { handoffToDefinition } from "./handoff";
 import { isHostedTool, isFunctionTool } from "./hosted-tool";
 import { subagentToDefinition, subagentToTool } from "./subagent";
@@ -70,6 +70,33 @@ async function resolveAfterToolCallHook(hook, params) {
         }
     }
 }
+/** Check if a tool/handoff isEnabled field resolves to true */
+async function checkEnabled(isEnabled, context) {
+    if (isEnabled === undefined)
+        return true;
+    if (typeof isEnabled === "boolean")
+        return isEnabled;
+    return isEnabled(context);
+}
+/** Execute a tool with optional timeout */
+async function executeWithTimeout(fn, timeout, toolName) {
+    if (!timeout)
+        return fn();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new ToolTimeoutError(toolName, timeout));
+        }, timeout);
+        Promise.resolve(fn())
+            .then((result) => {
+            clearTimeout(timer);
+            resolve(result);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 function checkAborted(signal) {
     if (signal?.aborted) {
         throw new RunAbortedError();
@@ -90,6 +117,11 @@ function checkBudget(ctx, maxBudgetUsd) {
         throw new MaxBudgetExceededError(maxBudgetUsd, ctx.totalCostUsd);
     }
 }
+function formatToolError(toolName, error, formatter) {
+    if (formatter)
+        return formatter(toolName, error);
+    return `Error executing tool "${toolName}": ${getErrorMessage(error)}`;
+}
 export async function run(agent, input, options) {
     validateBudgetOptions(options);
     const model = options?.model ?? agent.model;
@@ -103,24 +135,30 @@ export async function run(agent, input, options) {
     const maxBudgetUsd = options?.maxBudgetUsd;
     const ctx = new RunContext(options?.context);
     const trace = getCurrentTrace();
+    const runHooks = options?.runHooks;
+    const toolErrorFmt = options?.toolErrorFormatter;
+    const callModelInputFilter = options?.callModelInputFilter;
+    const toolInputGuardrails = options?.toolInputGuardrails ?? [];
+    const toolOutputGuardrails = options?.toolOutputGuardrails ?? [];
     // Fire beforeRun hook on the entry agent
     const inputText = typeof input === "string" ? input : extractUserText(input);
     if (agent.hooks.beforeRun) {
         await agent.hooks.beforeRun({ agent, input: inputText, context: ctx.context });
     }
     // Run input guardrails on the starting agent
+    let inputGuardrailResults = [];
     if (agent.inputGuardrails.length > 0) {
         if (trace) {
             const span = trace.startSpan("input_guardrails", "guardrail");
             try {
-                await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
+                inputGuardrailResults = await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
             }
             finally {
                 trace.endSpan(span);
             }
         }
         else {
-            await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
+            inputGuardrailResults = await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
         }
     }
     const messages = [];
@@ -137,16 +175,33 @@ export async function run(agent, input, options) {
     }
     let lastFinishReason;
     let lastResponseId;
+    // Fire run-level onAgentStart
+    if (runHooks?.onAgentStart) {
+        await runHooks.onAgentStart({ agent: currentAgent, context: ctx.context });
+    }
     for (let turn = 0; turn < maxTurns; turn++) {
         checkAborted(signal);
-        const toolDefs = buildToolDefs(currentAgent);
-        const request = {
+        const toolDefs = await buildToolDefs(currentAgent, ctx.context);
+        let request = {
             messages,
             tools: toolDefs.length > 0 ? toolDefs : undefined,
-            modelSettings: currentAgent.modelSettings,
+            modelSettings: currentAgent.modelSettings
+                ? applyResetToolChoice(currentAgent.modelSettings, turn, options?.resetToolChoice)
+                : undefined,
             responseFormat: currentAgent.getResponseFormat(),
             previousResponseId: lastResponseId,
         };
+        // Apply callModelInputFilter
+        if (callModelInputFilter) {
+            request = callModelInputFilter({ agent: currentAgent, request, context: ctx.context });
+        }
+        // Fire onLlmStart hooks
+        if (currentAgent.hooks.onLlmStart) {
+            await currentAgent.hooks.onLlmStart({ agent: currentAgent, messages, context: ctx.context });
+        }
+        if (runHooks?.onLlmStart) {
+            await runHooks.onLlmStart({ agent: currentAgent, request, context: ctx.context });
+        }
         let response;
         if (trace) {
             const span = trace.startSpan(`model_call:${currentAgent.name}`, "model_call", {
@@ -168,6 +223,14 @@ export async function run(agent, input, options) {
         else {
             response = await model.getResponse(request, { signal });
         }
+        // Fire onLlmEnd hooks
+        const llmEndInfo = { content: response.content, toolCallCount: response.toolCalls.length };
+        if (currentAgent.hooks.onLlmEnd) {
+            await currentAgent.hooks.onLlmEnd({ agent: currentAgent, response: llmEndInfo, context: ctx.context });
+        }
+        if (runHooks?.onLlmEnd) {
+            await runHooks.onLlmEnd({ agent: currentAgent, response: llmEndInfo, context: ctx.context });
+        }
         checkAborted(signal);
         lastFinishReason = response.finishReason;
         if (response.responseId)
@@ -196,12 +259,16 @@ export async function run(agent, input, options) {
         };
         messages.push(assistantMsg);
         if (response.toolCalls.length === 0) {
-            return buildFinalResult(agent, currentAgent, messages, ctx, trace, lastFinishReason, lastResponseId);
+            // Fire run-level onAgentEnd
+            if (runHooks?.onAgentEnd) {
+                await runHooks.onAgentEnd({ agent: currentAgent, output: response.content ?? "", context: ctx.context });
+            }
+            return buildFinalResult(agent, currentAgent, messages, ctx, trace, lastFinishReason, lastResponseId, inputGuardrailResults);
         }
-        const { toolMessages, handoffAgent } = await executeToolCallsWithHandoffs(currentAgent, ctx, response.toolCalls, trace, signal);
+        const { toolMessages, handoffAgent } = await executeToolCallsWithHandoffs(currentAgent, ctx, response.toolCalls, trace, signal, toolErrorFmt, runHooks, toolInputGuardrails, toolOutputGuardrails);
         messages.push(...toolMessages);
         // Check toolUseBehavior — should we stop instead of calling the LLM again?
-        if (shouldStopAfterToolCalls(currentAgent, response.toolCalls)) {
+        if (await shouldStopAfterToolCalls(currentAgent, response.toolCalls, toolMessages)) {
             const toolOutput = toolMessages.map((m) => m.content).join("\n");
             return new RunResult({
                 output: toolOutput,
@@ -212,6 +279,7 @@ export async function run(agent, input, options) {
                 numTurns: ctx.numTurns,
                 totalCostUsd: ctx.totalCostUsd,
                 responseId: lastResponseId,
+                inputGuardrailResults,
             });
         }
         if (handoffAgent) {
@@ -238,10 +306,25 @@ export async function run(agent, input, options) {
                 }
             }
             if (allowHandoff) {
+                // Fire run-level onAgentEnd for current agent
+                if (runHooks?.onAgentEnd) {
+                    await runHooks.onAgentEnd({ agent: currentAgent, output: response.content ?? "", context: ctx.context });
+                }
+                // Fire run-level onHandoff
+                if (runHooks?.onHandoff) {
+                    await runHooks.onHandoff({ fromAgent: currentAgent, toAgent: handoffAgent, context: ctx.context });
+                }
                 if (trace) {
                     const span = trace.startSpan(`handoff:${currentAgent.name}->${handoffAgent.name}`, "handoff", { fromAgent: currentAgent.name, toAgent: handoffAgent.name });
                     trace.endSpan(span);
                 }
+                // Apply handoff inputFilter if present
+                const matchedHandoff = currentAgent.handoffs.find((h) => h.agent === handoffAgent || h.agent.name === handoffAgent.name);
+                if (matchedHandoff?.inputFilter) {
+                    const filtered = matchedHandoff.inputFilter({ history: [...messages] });
+                    messages.length = 0;
+                    messages.push(...filtered);
+                }
                 currentAgent = handoffAgent;
                 // Replace system message with new agent's prompt
                 const newSystemPrompt = await currentAgent.getSystemPrompt(ctx.context);
@@ -257,6 +340,10 @@ export async function run(agent, input, options) {
                 else if (systemIdx >= 0) {
                     messages.splice(systemIdx, 1);
                 }
+                // Fire run-level onAgentStart for new agent
+                if (runHooks?.onAgentStart) {
+                    await runHooks.onAgentStart({ agent: currentAgent, context: ctx.context });
+                }
             }
         }
     }
@@ -268,6 +355,15 @@ export async function run(agent, input, options) {
             reason: "max_turns",
         });
     }
+    // Check for error handler
+    if (options?.errorHandlers?.maxTurns) {
+        return options.errorHandlers.maxTurns({
+            agent: currentAgent,
+            messages,
+            context: ctx.context,
+            maxTurns,
+        });
+    }
     throw new MaxTurnsExceededError(maxTurns);
 }
 export function stream(agent, input, options) {
@@ -294,24 +390,30 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
         const maxBudgetUsd = options?.maxBudgetUsd;
         const ctx = new RunContext(options?.context);
         const trace = getCurrentTrace();
+        const runHooks = options?.runHooks;
+        const toolErrorFmt = options?.toolErrorFormatter;
+        const callModelInputFilter = options?.callModelInputFilter;
+        const toolInputGuardrails = options?.toolInputGuardrails ?? [];
+        const toolOutputGuardrails = options?.toolOutputGuardrails ?? [];
         // Fire beforeRun hook on the entry agent
         const inputText = typeof input === "string" ? input : extractUserText(input);
         if (agent.hooks.beforeRun) {
             await agent.hooks.beforeRun({ agent, input: inputText, context: ctx.context });
         }
         // Run input guardrails on the starting agent
+        let inputGuardrailResults = [];
         if (agent.inputGuardrails.length > 0) {
             if (trace) {
                 const span = trace.startSpan("input_guardrails", "guardrail");
                 try {
-                    await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
+                    inputGuardrailResults = await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
                 }
                 finally {
                     trace.endSpan(span);
                 }
             }
             else {
-                await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
+                inputGuardrailResults = await runInputGuardrails(agent.inputGuardrails, inputText, ctx.context);
             }
         }
         const messages = [];
@@ -328,16 +430,33 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
         }
         let lastFinishReason;
         let lastResponseId;
+        // Fire run-level onAgentStart
+        if (runHooks?.onAgentStart) {
+            await runHooks.onAgentStart({ agent: currentAgent, context: ctx.context });
+        }
         for (let turn = 0; turn < maxTurns; turn++) {
             checkAborted(signal);
-            const toolDefs = buildToolDefs(currentAgent);
-            const request = {
+            const toolDefs = await buildToolDefs(currentAgent, ctx.context);
+            let request = {
                 messages,
                 tools: toolDefs.length > 0 ? toolDefs : undefined,
-                modelSettings: currentAgent.modelSettings,
+                modelSettings: currentAgent.modelSettings
+                    ? applyResetToolChoice(currentAgent.modelSettings, turn, options?.resetToolChoice)
+                    : undefined,
                 responseFormat: currentAgent.getResponseFormat(),
                 previousResponseId: lastResponseId,
             };
+            // Apply callModelInputFilter
+            if (callModelInputFilter) {
+                request = callModelInputFilter({ agent: currentAgent, request, context: ctx.context });
+            }
+            // Fire onLlmStart hooks
+            if (currentAgent.hooks.onLlmStart) {
+                await currentAgent.hooks.onLlmStart({ agent: currentAgent, messages, context: ctx.context });
+            }
+            if (runHooks?.onLlmStart) {
+                await runHooks.onLlmStart({ agent: currentAgent, request, context: ctx.context });
+            }
             let finalResponse;
             let gotDone = false;
             for await (const event of model.getStreamedResponse(request, { signal })) {
@@ -350,6 +469,14 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
             if (!gotDone) {
                 throw new StratusError("Stream ended without a done event");
             }
+            // Fire onLlmEnd hooks
+            const llmEndInfo = { content: finalResponse.content, toolCallCount: finalResponse.toolCalls.length };
+            if (currentAgent.hooks.onLlmEnd) {
+                await currentAgent.hooks.onLlmEnd({ agent: currentAgent, response: llmEndInfo, context: ctx.context });
+            }
+            if (runHooks?.onLlmEnd) {
+                await runHooks.onLlmEnd({ agent: currentAgent, response: llmEndInfo, context: ctx.context });
+            }
             checkAborted(signal);
             lastFinishReason = finalResponse.finishReason;
             if (finalResponse.responseId)
@@ -380,14 +507,17 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
             };
             messages.push(assistantMsg);
             if (finalResponse.toolCalls.length === 0) {
-                const result = await buildFinalResult(agent, currentAgent, messages, ctx, trace, lastFinishReason, lastResponseId);
+                if (runHooks?.onAgentEnd) {
+                    await runHooks.onAgentEnd({ agent: currentAgent, output: finalResponse.content ?? "", context: ctx.context });
+                }
+                const result = await buildFinalResult(agent, currentAgent, messages, ctx, trace, lastFinishReason, lastResponseId, inputGuardrailResults);
                 resolveResult(result);
                 return;
             }
-            const { toolMessages, handoffAgent } = await executeToolCallsWithHandoffs(currentAgent, ctx, finalResponse.toolCalls, trace, signal);
+            const { toolMessages, handoffAgent } = await executeToolCallsWithHandoffs(currentAgent, ctx, finalResponse.toolCalls, trace, signal, toolErrorFmt, runHooks, toolInputGuardrails, toolOutputGuardrails);
             messages.push(...toolMessages);
             // Check toolUseBehavior
-            if (shouldStopAfterToolCalls(currentAgent, finalResponse.toolCalls)) {
+            if (await shouldStopAfterToolCalls(currentAgent, finalResponse.toolCalls, toolMessages)) {
                 const toolOutput = toolMessages.map((m) => m.content).join("\n");
                 resolveResult(new RunResult({
                     output: toolOutput,
@@ -398,6 +528,7 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
                     numTurns: ctx.numTurns,
                     totalCostUsd: ctx.totalCostUsd,
                     responseId: lastResponseId,
+                    inputGuardrailResults,
                 }));
                 return;
             }
@@ -423,6 +554,19 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
                     }
                 }
                 if (allowHandoff) {
+                    if (runHooks?.onAgentEnd) {
+                        await runHooks.onAgentEnd({ agent: currentAgent, output: finalResponse.content ?? "", context: ctx.context });
+                    }
+                    if (runHooks?.onHandoff) {
+                        await runHooks.onHandoff({ fromAgent: currentAgent, toAgent: handoffAgent, context: ctx.context });
+                    }
+                    // Apply handoff inputFilter if present
+                    const matchedHandoff = currentAgent.handoffs.find((h) => h.agent === handoffAgent || h.agent.name === handoffAgent.name);
+                    if (matchedHandoff?.inputFilter) {
+                        const filtered = matchedHandoff.inputFilter({ history: [...messages] });
+                        messages.length = 0;
+                        messages.push(...filtered);
+                    }
                     currentAgent = handoffAgent;
                     const newSystemPrompt = await currentAgent.getSystemPrompt(ctx.context);
                     const systemIdx = messages.findIndex((m) => m.role === "system");
@@ -437,6 +581,9 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
                     else if (systemIdx >= 0) {
                         messages.splice(systemIdx, 1);
                     }
+                    if (runHooks?.onAgentStart) {
+                        await runHooks.onAgentStart({ agent: currentAgent, context: ctx.context });
+                    }
                 }
             }
         }
@@ -448,6 +595,16 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
                 reason: "max_turns",
             });
         }
+        // Check for error handler
+        if (options?.errorHandlers?.maxTurns) {
+            resolveResult(await options.errorHandlers.maxTurns({
+                agent: currentAgent,
+                messages,
+                context: ctx.context,
+                maxTurns,
+            }));
+            return;
+        }
         throw new MaxTurnsExceededError(maxTurns);
     }
     catch (error) {
@@ -455,22 +612,23 @@ async function* streamInternal(agent, input, options, resolveResult, rejectResul
         throw error;
     }
 }
-async function buildFinalResult(entryAgent, currentAgent, messages, ctx, trace, finishReason, responseId) {
+async function buildFinalResult(entryAgent, currentAgent, messages, ctx, trace, finishReason, responseId, inputGuardrailResults) {
     const lastMessage = messages[messages.length - 1];
     const rawOutput = lastMessage && lastMessage.role === "assistant" ? (lastMessage.content ?? "") : "";
     // Run output guardrails on the current (possibly handed-off) agent
+    let outputGuardrailResults = [];
     if (currentAgent.outputGuardrails.length > 0) {
         if (trace) {
             const span = trace.startSpan("output_guardrails", "guardrail");
             try {
-                await runOutputGuardrails(currentAgent.outputGuardrails, rawOutput, ctx.context);
+                outputGuardrailResults = await runOutputGuardrails(currentAgent.outputGuardrails, rawOutput, ctx.context);
             }
             finally {
                 trace.endSpan(span);
             }
         }
         else {
-            await runOutputGuardrails(currentAgent.outputGuardrails, rawOutput, ctx.context);
+            outputGuardrailResults = await runOutputGuardrails(currentAgent.outputGuardrails, rawOutput, ctx.context);
         }
     }
     // Parse structured output if outputType is set
@@ -494,6 +652,8 @@ async function buildFinalResult(entryAgent, currentAgent, messages, ctx, trace,
         numTurns: ctx.numTurns,
         totalCostUsd: ctx.totalCostUsd,
         responseId,
+        inputGuardrailResults,
+        outputGuardrailResults,
     });
     // Fire afterRun hook on the entry agent
     if (entryAgent.hooks.afterRun) {
@@ -501,13 +661,16 @@ async function buildFinalResult(entryAgent, currentAgent, messages, ctx, trace,
     }
     return result;
 }
-function buildToolDefs(agent) {
+async function buildToolDefs(agent, context) {
     const defs = [];
     for (const t of agent.tools) {
         if (isHostedTool(t)) {
             defs.push(t.definition);
         }
         else {
+            // Check isEnabled for function tools
+            if (!(await checkEnabled(t.isEnabled, context)))
+                continue;
             defs.push(toolToDefinition(t));
         }
     }
@@ -515,6 +678,9 @@ function buildToolDefs(agent) {
         defs.push(subagentToDefinition(sa));
     }
     for (const h of agent.handoffs) {
+        // Check isEnabled for handoffs
+        if (!(await checkEnabled(h.isEnabled, context)))
+            continue;
         defs.push(handoffToDefinition(h));
     }
     return defs;
@@ -537,18 +703,36 @@ function extractUserText(messages) {
     }
     return texts.join("\n");
 }
-function shouldStopAfterToolCalls(agent, toolCalls) {
-    if (agent.toolUseBehavior === "run_llm_again")
+async function shouldStopAfterToolCalls(agent, toolCalls, toolMessages) {
+    const behavior = agent.toolUseBehavior;
+    if (behavior === "run_llm_again")
         return false;
-    if (agent.toolUseBehavior === "stop_on_first_tool")
+    if (behavior === "stop_on_first_tool")
         return true;
-    if ("stopAtToolNames" in agent.toolUseBehavior) {
-        const stopNames = new Set(agent.toolUseBehavior.stopAtToolNames);
+    if (typeof behavior === "function") {
+        // Custom function variant
+        const results = toolCalls.map((tc, i) => ({
+            toolName: tc.function.name,
+            result: toolMessages[i]?.content ?? "",
+        }));
+        return behavior(results);
+    }
+    if (typeof behavior === "object" && "stopAtToolNames" in behavior) {
+        const stopNames = new Set(behavior.stopAtToolNames);
         return toolCalls.some((tc) => stopNames.has(tc.function.name));
     }
     return false;
 }
-async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal) {
+function applyResetToolChoice(settings, turn, resetToolChoice) {
+    if (!resetToolChoice || turn === 0)
+        return settings;
+    // After the first turn, reset tool_choice to "auto" to prevent infinite loops
+    if (settings.toolChoice && settings.toolChoice !== "auto") {
+        return { ...settings, toolChoice: "auto" };
+    }
+    return settings;
+}
+async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal, toolErrorFmt, runHooks, toolInputGuardrails, toolOutputGuardrails) {
     let handoffAgent;
     // Build O(1) lookup maps
     const handoffsByName = new Map(agent.handoffs.map((h) => [h.toolName, h]));
@@ -597,6 +781,10 @@ async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal
                         context: ctx.context,
                     });
                 }
+                // Fire run-level onToolStart
+                if (runHooks?.onToolStart) {
+                    await runHooks.onToolStart({ agent, toolName: tcName, context: ctx.context });
+                }
                 let result;
                 if (trace) {
                     const span = trace.startSpan(`subagent:${matchedSubagent.agent.name}`, "subagent", { toolName: tcName });
@@ -619,6 +807,10 @@ async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal
                         context: ctx.context,
                     });
                 }
+                // Fire run-level onToolEnd
+                if (runHooks?.onToolEnd) {
+                    await runHooks.onToolEnd({ agent, toolName: tcName, result, context: ctx.context });
+                }
                 await resolveAfterToolCallHook(agent.hooks.afterToolCall, {
                     agent,
                     toolCall: fullToolCall,
@@ -635,7 +827,7 @@ async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal
                 return {
                     role: "tool",
                     tool_call_id: tc.id,
-                    content: `Error executing sub-agent "${matchedSubagent.agent.name}": ${getErrorMessage(error)}`,
+                    content: formatToolError(matchedSubagent.agent.name, error, toolErrorFmt),
                 };
             }
         }
@@ -667,6 +859,22 @@ async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal
             if (decision?.decision === "modify") {
                 params = decision.modifiedParams;
             }
+            // Run tool input guardrails
+            if (toolInputGuardrails && toolInputGuardrails.length > 0) {
+                const guardrailResults = await runToolInputGuardrails(toolInputGuardrails, tcName, params, ctx.context);
+                const tripped = guardrailResults.find((r) => r.result.tripwireTriggered);
+                if (tripped) {
+                    return {
+                        role: "tool",
+                        tool_call_id: tc.id,
+                        content: `Tool input guardrail "${tripped.guardrailName}" blocked execution of "${tcName}"`,
+                    };
+                }
+            }
+            // Fire run-level onToolStart
+            if (runHooks?.onToolStart) {
+                await runHooks.onToolStart({ agent, toolName: tcName, context: ctx.context });
+            }
             checkAborted(signal);
             let result;
             if (trace) {
@@ -674,14 +882,26 @@ async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal
                     toolName: tcName,
                 });
                 try {
-                    result = await tool.execute(ctx.context, params, { signal });
+                    result = await executeWithTimeout(() => tool.execute(ctx.context, params, { signal }), tool.timeout, tcName);
                 }
                 finally {
                     trace.endSpan(span);
                 }
             }
             else {
-                result = await tool.execute(ctx.context, params, { signal });
+                result = await executeWithTimeout(() => tool.execute(ctx.context, params, { signal }), tool.timeout, tcName);
+            }
+            // Run tool output guardrails
+            if (toolOutputGuardrails && toolOutputGuardrails.length > 0) {
+                const guardrailResults = await runToolOutputGuardrails(toolOutputGuardrails, tcName, result, ctx.context);
+                const tripped = guardrailResults.find((r) => r.result.tripwireTriggered);
+                if (tripped) {
+                    result = `Tool output guardrail "${tripped.guardrailName}" flagged the output of "${tcName}"`;
+                }
+            }
+            // Fire run-level onToolEnd
+            if (runHooks?.onToolEnd) {
+                await runHooks.onToolEnd({ agent, toolName: tcName, result, context: ctx.context });
             }
             // Fire afterToolCall hook
             await resolveAfterToolCallHook(agent.hooks.afterToolCall, {
@@ -700,7 +920,7 @@ async function executeToolCallsWithHandoffs(agent, ctx, toolCalls, trace, signal
             return {
                 role: "tool",
                 tool_call_id: tc.id,
-                content: `Error executing tool "${tcName}": ${getErrorMessage(error)}`,
+                content: formatToolError(tcName, error, toolErrorFmt),
             };
         }
     }));