profclaw 2.0.0 → 2.4.0

package/dist/agents/executor.js

@@ -11,7 +11,16 @@ import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { EFFORT_BUDGET_MAP } from "./types.js";
 import { defaultStopConditions, taskCompleted } from "./stop-conditions.js";
+import { ToolCircuitBreaker } from "./circuit-breaker.js";
 import { logger } from "../utils/logger.js";
+import { applyAnthropicMessageCache, applyAnthropicToolCache, extractCacheUsage, } from "../providers/prompt-cache.js";
+import { trackChatUsage } from "../costs/token-tracker.js";
+import { ResultStore } from "./result-store.js";
+import { getAgentSummaryTracker } from "./agent-summary.js";
+import { getHookRegistry } from "../hooks/registry.js";
+import { ContextCompactor } from "./context-compactor.js";
+import { getSleepPreventer } from "../utils/prevent-sleep.js";
+import { getCheckpointManager } from "./checkpoint-manager.js";
 // Default Configuration
 const DEFAULT_CONFIG = {
     maxSteps: 100,
@@ -123,10 +132,21 @@ export class AgentExecutor extends EventEmitter {
     config;
     abortController;
     isRunning = false;
+    resultStore;
+    circuitBreaker = new ToolCircuitBreaker();
+    hooks;
+    compactor;
+    checkpointManager = getCheckpointManager();
     constructor(sessionId, conversationId, goal, config = {}) {
         super();
         this.abortController = new AbortController();
         this.config = { ...DEFAULT_CONFIG, ...config };
+        this.resultStore = new ResultStore(sessionId);
+        this.hooks = getHookRegistry();
+        this.compactor = new ContextCompactor({
+            maxContextTokens: this.config.maxBudget,
+            compactionThreshold: Math.floor(this.config.maxBudget * 0.7),
+        });
         // Ensure taskCompleted is always included in stop conditions
         if (!this.config.stopConditions.some((c) => c.name === "taskCompleted")) {
             this.config.stopConditions.push(taskCompleted());
@@ -154,14 +174,20 @@ export class AgentExecutor extends EventEmitter {
             maxSteps: this.config.maxSteps,
             maxBudget: this.config.maxBudget,
         });
+        // Register this session with the summary tracker
+        getAgentSummaryTracker().start(sessionId);
     }
     // Public API
     /**
-     * Run the agent until completion or stop condition.
-     * Uses AI SDK's native multi-step execution — a single generateText call
-     * with stopWhen + onStepFinish replaces the old manual loop.
+     * Async generator that streams agent events as they happen.
+     *
+     * Yields AgentEvent values in real time: session:start, step:start,
+     * tool:call, tool:result/tool:error, content, cost:update, step:complete,
+     * and finally session:complete, session:error, or session:abort.
+     *
+     * This is the canonical implementation; run() delegates here.
      */
-    async run(model, messages, tools, onToolExecute, providerHint) {
+    async *stream(model, messages, tools, onToolExecute, providerHint) {
         if (this.isRunning) {
             throw new Error("Agent is already running");
         }
@@ -169,140 +195,343 @@ export class AgentExecutor extends EventEmitter {
         this.state.status = "running";
         this.state.updatedAt = Date.now();
         this.emit("start", this.state);
-        logger.info("[AgentExecutor] Starting agent run", {
+        getSleepPreventer().start();
+        logger.info("[AgentExecutor] Starting agent stream", {
             sessionId: this.state.sessionId,
             goal: this.state.goal,
         });
-        try {
-            // Inject failure hint if applicable (from prior runs / retries)
-            this.injectFailureHint(messages);
-            // Wire execute functions into tools so the SDK can auto-execute them
-            const executableTools = this.wrapToolsWithExecute(tools, onToolExecute);
-            const hasTools = Object.keys(executableTools).length > 0;
-            // Build provider-specific options (e.g. Anthropic thinking/effort)
-            const providerOptions = this.buildProviderOptions(providerHint);
-            // Single generateText call — the SDK handles multi-step chaining
-            const result = await generateText({
-                model,
-                messages,
-                tools: hasTools ? executableTools : undefined,
-                ...(providerOptions ? { providerOptions } : {}),
-                stopWhen: [
-                    sdkStepCountIs(this.config.maxSteps),
-                    sdkHasToolCall("complete_task"),
-                ],
-                abortSignal: this.abortController.signal,
-                onStepFinish: (step) => {
-                    this.state.currentStep++;
-                    this.state.updatedAt = Date.now();
-                    // Track token budget (AI SDK v6 uses inputTokens/outputTokens)
-                    const stepInput = getUsageInputTokens(step.usage);
-                    const stepOutput = getUsageOutputTokens(step.usage);
-                    const tokensUsed = stepInput + stepOutput;
-                    this.state.usedBudget += tokensUsed;
-                    this.state.inputTokensUsed += stepInput;
-                    this.state.outputTokensUsed += stepOutput;
-                    // Store text response for summary extraction
-                    if (step.text) {
-                        this.state.context.lastTextResponse = step.text;
-                    }
-                    // Record tool calls in history
-                    for (const tc of step.toolCalls ?? []) {
-                        const record = {
-                            id: tc.toolCallId ?? randomUUID(),
-                            name: tc.toolName,
-                            args: getToolCallInput(tc),
-                            status: "pending",
-                            startedAt: Date.now(),
-                        };
-                        // Find the matching tool result
-                        const tr = (step.toolResults ?? []).find((toolResult) => toolResult.toolCallId === tc.toolCallId);
-                        if (tr) {
-                            record.result = getToolResultOutput(tr);
-                            record.completedAt = Date.now();
-                            // Check if the tool result indicates a failure
-                            if (typeof record.result === "object" && record.result !== null) {
-                                const resultObj = record.result;
-                                const isPending = resultObj.pending === true;
-                                const hasError = Boolean(resultObj.error);
-                                const isFailure = resultObj.success === false || hasError;
-                                if (isPending) {
-                                    record.status = "pending";
-                                }
-                                else if (isFailure) {
-                                    record.status = "failed";
-                                    record.error =
-                                        resultObj.error ||
-                                            "Tool returned unsuccessful result";
+        // --- Async event channel ---
+        // onStepFinish is a synchronous callback inside generateText. We bridge it
+        // into the async generator by queuing events and signalling the consumer.
+        const queue = [];
+        let resolveNext;
+        let generateDone = false;
+        let generateError;
+        const push = (event) => {
+            queue.push(event);
+            if (resolveNext) {
+                const r = resolveNext;
+                resolveNext = undefined;
+                r();
+            }
+        };
+        // Yield session:start immediately
+        push({
+            type: 'session:start',
+            sessionId: this.state.sessionId,
+            config: {
+                maxSteps: this.config.maxSteps,
+                maxBudget: this.config.maxBudget,
+                effort: this.config.effort,
+                securityMode: this.config.securityMode,
+                stepTimeoutMs: this.config.stepTimeoutMs,
+            },
+        });
+        // Run generateText in the background, pushing events via push()
+        const generatePromise = (async () => {
+            try {
+                // Fire onSessionStart hook
+                await this.hooks.run('onSessionStart', {
+                    hookPoint: 'onSessionStart',
+                    sessionId: this.state.sessionId,
+                    metadata: {},
+                });
+                this.injectFailureHint(messages);
+                // Use the streaming-aware wrapper so tool events are pushed in real time
+                const executableTools = this.wrapToolsWithExecuteAndEvents(tools, onToolExecute, push);
+                // Compact context before the API call if messages are large
+                const compactionResult = await this.compactor.compact(messages);
+                if (compactionResult.compacted) {
+                    logger.info("[AgentExecutor] Context compacted before API call", {
+                        originalTokens: compactionResult.originalTokens,
+                        compactedTokens: compactionResult.compactedTokens,
+                        turnsCompacted: compactionResult.turnsCompacted,
+                    });
+                    messages = compactionResult.messages;
+                }
+                const hasTools = Object.keys(executableTools).length > 0;
+                const providerOptions = this.buildProviderOptions(providerHint);
+                const result = await generateText({
+                    model,
+                    messages: applyAnthropicMessageCache(messages, providerHint ?? ''),
+                    tools: hasTools ? applyAnthropicToolCache(executableTools, providerHint ?? '') : undefined,
+                    ...(providerOptions ? { providerOptions } : {}),
+                    stopWhen: [
+                        sdkStepCountIs(this.config.maxSteps),
+                        sdkHasToolCall("complete_task"),
+                    ],
+                    abortSignal: this.abortController.signal,
+                    onStepFinish: (step) => {
+                        const stepIndex = this.state.currentStep;
+                        push({ type: 'step:start', stepIndex });
+                        this.state.currentStep++;
+                        this.state.updatedAt = Date.now();
+                        const stepInput = getUsageInputTokens(step.usage);
+                        const stepOutput = getUsageOutputTokens(step.usage);
+                        const tokensUsed = stepInput + stepOutput;
+                        this.state.usedBudget += tokensUsed;
+                        this.state.inputTokensUsed += stepInput;
+                        this.state.outputTokensUsed += stepOutput;
+                        const cacheUsage = extractCacheUsage(step.usage);
+                        this.trackStepUsage(model, stepInput, stepOutput, cacheUsage);
+                        if (cacheUsage.cacheReadTokens > 0 || cacheUsage.cacheWriteTokens > 0) {
+                            logger.debug("[AgentExecutor] Prompt cache usage", {
+                                sessionId: this.state.sessionId,
+                                cacheReadTokens: cacheUsage.cacheReadTokens,
+                                cacheWriteTokens: cacheUsage.cacheWriteTokens,
+                                promptTokens: cacheUsage.promptTokens,
+                            });
+                        }
+                        // Update summary tracker with step progress
+                        getAgentSummaryTracker().update(this.state.sessionId, {
+                            status: 'thinking',
+                            stepCount: this.state.currentStep,
+                            tokensUsed: this.state.usedBudget,
+                        });
+                        push({
+                            type: 'cost:update',
+                            inputTokens: this.state.inputTokensUsed,
+                            outputTokens: this.state.outputTokensUsed,
+                            estimatedCost: 0,
+                        });
+                        if (step.text) {
+                            this.state.context.lastTextResponse = step.text;
+                            push({ type: 'content', text: step.text, delta: step.text });
+                        }
+                        let stepToolCalls = 0;
+                        for (const tc of step.toolCalls ?? []) {
+                            stepToolCalls++;
+                            const record = {
+                                id: tc.toolCallId ?? randomUUID(),
+                                name: tc.toolName,
+                                args: getToolCallInput(tc),
+                                status: "pending",
+                                startedAt: Date.now(),
+                            };
+                            const tr = (step.toolResults ?? []).find((toolResult) => toolResult.toolCallId === tc.toolCallId);
+                            if (tr) {
+                                record.result = getToolResultOutput(tr);
+                                record.completedAt = Date.now();
+                                if (typeof record.result === "object" && record.result !== null) {
+                                    const resultObj = record.result;
+                                    const isPending = resultObj.pending === true;
+                                    const hasError = Boolean(resultObj.error);
+                                    const isFailure = resultObj.success === false || hasError;
+                                    if (isPending) {
+                                        record.status = "pending";
+                                    }
+                                    else if (isFailure) {
+                                        record.status = "failed";
+                                        record.error =
+                                            resultObj.error ||
+                                                "Tool returned unsuccessful result";
+                                    }
+                                    else {
+                                        record.status = "executed";
+                                    }
                                 }
                                 else {
                                     record.status = "executed";
                                 }
                             }
-                            else {
-                                record.status = "executed";
+                            this.state.toolCallHistory.push(record);
+                            this.emit("tool:call", this.state, record);
+                            this.extractContext(record);
+                            if (record.status === "executed") {
+                                this.emit("tool:result", this.state, record);
                             }
                         }
-                        this.state.toolCallHistory.push(record);
-                        this.emit("tool:call", this.state, record);
-                        // Extract context from tool results (projects, tickets, etc.)
-                        this.extractContext(record);
-                        if (record.status === "executed") {
-                            this.emit("tool:result", this.state, record);
+                        this.emit("step:start", this.state);
+                        this.emit("step:complete", this.state, step);
+                        push({
+                            type: 'step:complete',
+                            stepIndex: this.state.currentStep,
+                            toolCalls: stepToolCalls,
+                            hasContent: Boolean(step.text),
+                        });
+                        logger.debug("[AgentExecutor] Step completed", {
+                            step: this.state.currentStep,
+                            toolCalls: step.toolCalls?.length ?? 0,
+                            tokensUsed,
+                            text: step.text?.substring(0, 100),
+                        });
+                        this.checkCustomStopConditions(step);
+                        // Emit a budget warning when 80% of the token budget is consumed
+                        const usedPercent = this.state.maxBudget > 0
+                            ? (this.state.usedBudget / this.state.maxBudget) * 100
+                            : 0;
+                        if (usedPercent >= 80 && usedPercent < 100) {
+                            push({
+                                type: 'budget:warning',
+                                usedPercent: Math.round(usedPercent),
+                                tokensUsed: this.state.usedBudget,
+                                tokensMax: this.state.maxBudget,
+                            });
                         }
-                    }
-                    // Emit step events
-                    this.emit("step:start", this.state);
-                    this.emit("step:complete", this.state, step);
-                    logger.debug("[AgentExecutor] Step completed", {
-                        step: this.state.currentStep,
-                        toolCalls: step.toolCalls?.length ?? 0,
-                        tokensUsed,
-                        text: step.text?.substring(0, 100),
+                        // Save a checkpoint every 5 steps so the session can be resumed
+                        // (re-use stepIndex which was declared at the top of onStepFinish)
+                        const currentStepForCheckpoint = this.state.currentStep;
+                        if (currentStepForCheckpoint > 0 && currentStepForCheckpoint % 5 === 0) {
+                            const checkpoint = {
+                                sessionId: this.state.sessionId,
+                                taskDescription: this.state.goal,
+                                currentStep: currentStepForCheckpoint,
+                                totalSteps: this.config.maxSteps,
+                                messages: [...messages],
+                                tokensUsed: this.state.usedBudget,
+                                estimatedCost: 0,
+                                toolCallHistory: this.state.toolCallHistory.map((tc) => ({
+                                    name: tc.name,
+                                    success: tc.status === 'executed',
+                                    step: currentStepForCheckpoint,
+                                })),
+                                completedFiles: (this.state.context.modifiedFiles ?? []).slice(),
+                                createdAt: this.state.createdAt,
+                                updatedAt: Date.now(),
+                            };
+                            void this.checkpointManager.save(checkpoint).then(() => {
+                                push({ type: 'checkpoint:saved', sessionId: this.state.sessionId, step: currentStepForCheckpoint });
+                            }).catch((err) => {
+                                logger.warn("[AgentExecutor] Failed to save checkpoint", { err });
+                            });
+                        }
+                        if (this.state.usedBudget >= this.state.maxBudget) {
+                            logger.info("[AgentExecutor] Budget exceeded, aborting", {
+                                used: this.state.usedBudget,
+                                max: this.state.maxBudget,
+                            });
+                            this.abortController.abort();
+                        }
+                    },
+                });
+                const totalUsage = result.totalUsage;
+                if (totalUsage) {
+                    const totalInput = getUsageInputTokens(totalUsage);
+                    const totalOutput = getUsageOutputTokens(totalUsage);
+                    this.state.usedBudget = totalInput + totalOutput;
+                    this.state.inputTokensUsed = totalInput;
+                    this.state.outputTokensUsed = totalOutput;
+                }
+                if (result.text) {
+                    this.state.context.lastTextResponse = result.text;
+                }
+                this.finalize();
+                // Fire onSessionEnd hook after finalization
+                await this.hooks.run('onSessionEnd', {
+                    hookPoint: 'onSessionEnd',
+                    sessionId: this.state.sessionId,
+                    metadata: {},
+                });
+                const finalResult = this.state.finalResult ?? {
+                    success: false,
+                    summary: 'No result',
+                    artifacts: [],
+                    stopReason: 'unknown',
+                    totalSteps: this.state.currentStep,
+                    totalTokens: this.state.usedBudget,
+                };
+                push({
+                    type: 'session:complete',
+                    result: finalResult,
+                    totalSteps: this.state.currentStep,
+                    totalTokens: this.state.usedBudget,
+                });
+            }
+            catch (error) {
+                const err = error;
+                if (err.name === "AbortError") {
+                    logger.info("[AgentExecutor] Agent aborted");
+                    this.finalize();
+                    // Fire onSessionEnd even on abort
+                    await this.hooks.run('onSessionEnd', {
+                        hookPoint: 'onSessionEnd',
+                        sessionId: this.state.sessionId,
+                        metadata: { aborted: true },
                     });
-                    // Check custom stop conditions (consecutive failures, same tool repeated, etc.)
-                    this.checkCustomStopConditions(step);
-                    // Budget abort
-                    if (this.state.usedBudget >= this.state.maxBudget) {
-                        logger.info("[AgentExecutor] Budget exceeded, aborting", {
-                            used: this.state.usedBudget,
-                            max: this.state.maxBudget,
-                        });
-                        this.abortController.abort();
+                    push({ type: 'session:abort', reason: 'aborted' });
+                }
+                else {
+                    generateError = err;
+                    // Fire onError hook before emitting the event
+                    await this.hooks.run('onError', {
+                        hookPoint: 'onError',
+                        sessionId: this.state.sessionId,
+                        error: err,
+                        metadata: {},
+                    });
+                    // Push the event BEFORE handleError so it is always emitted even if
+                    // the EventEmitter 'error' event throws due to missing listener.
+                    push({ type: 'session:error', error: err.message, stack: err.stack });
+                    try {
+                        this.handleError(err);
                     }
-                },
-            });
-            // Update budget from total usage (AI SDK v6 uses inputTokens/outputTokens)
-            const totalUsage = result.totalUsage;
-            if (totalUsage) {
-                const totalInput = getUsageInputTokens(totalUsage);
-                const totalOutput = getUsageOutputTokens(totalUsage);
-                // totalUsage is the authoritative sum; overwrite our step-by-step estimate
-                this.state.usedBudget = totalInput + totalOutput;
-                this.state.inputTokensUsed = totalInput;
-                this.state.outputTokensUsed = totalOutput;
+                    catch {
+                        // Swallow re-throw from EventEmitter if no 'error' listener is attached
+                    }
+                }
             }
-            // Store final text from the result (last step's text)
-            if (result.text) {
-                this.state.context.lastTextResponse = result.text;
+            finally {
+                generateDone = true;
+                this.isRunning = false;
+                getSleepPreventer().stop();
+                if (resolveNext) {
+                    const r = resolveNext;
+                    resolveNext = undefined;
+                    r();
+                }
             }
-            // Finalize
-            this.finalize();
-            return this.state;
-        }
-        catch (error) {
-            if (error.name === "AbortError") {
-                // Aborted by budget or cancellation — still finalize
-                logger.info("[AgentExecutor] Agent aborted");
-                this.finalize();
-                return this.state;
+        })();
+        // Drain the queue; wait for more events when it is empty
+        while (true) {
+            while (queue.length > 0) {
+                yield queue.shift();
             }
-            this.handleError(error);
-            throw error;
+            if (generateDone)
+                break;
+            await new Promise((resolve) => {
+                resolveNext = resolve;
+            });
+        }
+        // Drain any remaining events that arrived while we were awaiting
+        while (queue.length > 0) {
+            yield queue.shift();
         }
-        finally {
-            this.isRunning = false;
+        // Propagate errors after the consumer has seen all events
+        await generatePromise;
+        if (generateError) {
+            throw generateError;
+        }
+    }
+    /**
+     * Run the agent until completion or stop condition.
+     * Uses AI SDK's native multi-step execution — a single generateText call
+     * with stopWhen + onStepFinish replaces the old manual loop.
+     *
+     * Backward-compatible: delegates to stream() and returns the final AgentState.
+     */
+    async run(model, messages, tools, onToolExecute, providerHint) {
+        // Consume the stream — stream() handles all state mutation and error handling
+        for await (const _event of this.stream(model, messages, tools, onToolExecute, providerHint)) {
+            // Individual events are not needed here; state is updated in-place
         }
+        return this.state;
+    }
+    /**
+     * Resume execution from a saved checkpoint.
+     *
+     * Restores the message history and step counter from the checkpoint, emits a
+     * checkpoint:resumed event, then continues with generateText from that point.
+     */
+    async *resume(checkpoint, model, tools, onToolExecute, providerHint) {
+        // Restore step counter so subsequent checkpoints use the right step index
+        this.state.currentStep = checkpoint.currentStep;
+        this.state.usedBudget = checkpoint.tokensUsed;
+        this.state.goal = checkpoint.taskDescription ?? this.state.goal;
+        this.state.createdAt = checkpoint.createdAt;
+        // Emit resumed event before the stream starts
+        yield { type: 'checkpoint:resumed', sessionId: checkpoint.sessionId, step: checkpoint.currentStep };
+        // Delegate to stream() with the restored messages
+        yield* this.stream(model, checkpoint.messages, tools, onToolExecute, providerHint);
     }
     /**
      * Cancel the running agent.
@@ -375,14 +604,67 @@ export class AgentExecutor extends EventEmitter {
         for (const [name, toolDef] of Object.entries(tools)) {
             wrapped[name] = {
                 ...toolDef,
-                execute: async (args) => {
+                execute: async (args, opts) => {
+                    // Circuit breaker check — prevent repeated calls to a failing tool
+                    const cbCheck = this.circuitBreaker.canExecute(name);
+                    if (!cbCheck.allowed) {
+                        logger.warn("[AgentExecutor] Circuit breaker blocked tool call", {
+                            tool: name,
+                            reason: cbCheck.reason,
+                        });
+                        return {
+                            error: cbCheck.reason ?? `Circuit breaker open for ${name}`,
+                            success: false,
+                            canRetry: false,
+                            suggestion: "Try an alternative approach",
+                        };
+                    }
+                    const toolCallId = opts?.toolCallId ?? randomUUID();
+                    const timeoutMs = this.config.stepTimeoutMs;
+                    // Update summary tracker — tool is now executing
+                    const summaryTracker = getAgentSummaryTracker();
+                    const currentAction = summaryTracker.summarizeToolCall(this.state.sessionId, name, args);
+                    summaryTracker.update(this.state.sessionId, {
+                        status: 'executing',
+                        currentAction,
+                        lastToolName: name,
+                        lastToolArgs: JSON.stringify(args).substring(0, 100),
+                    });
+                    let timeoutHandle;
+                    const timeoutPromise = new Promise((_, reject) => {
+                        timeoutHandle = setTimeout(() => {
+                            reject(new Error(`__TOOL_TIMEOUT__:${timeoutMs}`));
+                        }, timeoutMs);
+                    });
                     try {
-                        const result = await onToolExecute(name, args);
-                        return result;
+                        const raw = await Promise.race([
+                            onToolExecute(name, args),
+                            timeoutPromise,
+                        ]);
+                        clearTimeout(timeoutHandle);
+                        this.circuitBreaker.recordSuccess(name);
+                        const stored = await this.resultStore.store(toolCallId, raw);
+                        // Return the inline representation (summary or full result)
+                        return JSON.parse(stored.inline);
                     }
                     catch (error) {
-                        // Return error as a structured result so the AI can see it and adjust
+                        clearTimeout(timeoutHandle);
                         const errorMsg = error instanceof Error ? error.message : "Unknown error";
+                        // Timeout path
+                        if (errorMsg.startsWith("__TOOL_TIMEOUT__:")) {
+                            const ms = errorMsg.split(":")[1];
+                            logger.warn("[AgentExecutor] Tool execution timed out", {
+                                tool: name,
+                                timeoutMs,
+                            });
+                            this.circuitBreaker.recordFailure(name);
+                            return {
+                                error: `Tool execution timed out after ${ms}ms`,
+                                success: false,
+                                canRetry: true,
+                            };
+                        }
+                        // Regular error path
                         const isPermError = errorMsg.toLowerCase().includes("permission") ||
                             errorMsg.toLowerCase().includes("unauthorized") ||
                             errorMsg.toLowerCase().includes("forbidden") ||
@@ -391,12 +673,183 @@ export class AgentExecutor extends EventEmitter {
                             tool: name,
                             error: errorMsg,
                         });
+                        this.circuitBreaker.recordFailure(name);
+                        return {
+                            error: errorMsg,
+                            success: false,
+                            suggestion: "This tool failed. Consider trying a different approach or asking the user for help.",
+                            canRetry: !isPermError,
+                        };
+                    }
+                },
+            };
+        }
+        return wrapped;
+    }
+    /**
+     * Like wrapToolsWithExecute, but additionally pushes tool:call, tool:result,
+     * and tool:error AgentEvents via the provided push callback so that the
+     * stream() generator can yield them in real time.
+     */
+    wrapToolsWithExecuteAndEvents(tools, onToolExecute, push) {
+        if (!onToolExecute)
+            return tools;
+        const wrapped = {};
+        for (const [name, toolDef] of Object.entries(tools)) {
+            wrapped[name] = {
+                ...toolDef,
+                execute: async (args, opts) => {
+                    const toolCallId = opts?.toolCallId ?? randomUUID();
+                    // Circuit breaker check
+                    const cbCheck = this.circuitBreaker.canExecute(name);
+                    if (!cbCheck.allowed) {
+                        const reason = cbCheck.reason ?? `Circuit breaker open for ${name}`;
+                        logger.warn("[AgentExecutor] Circuit breaker blocked tool call", {
+                            tool: name,
+                            reason,
+                        });
+                        // Emit circuit:open so the consumer knows the breaker tripped
+                        push({ type: 'circuit:open', toolName: name, cooldownMs: 0 });
+                        push({ type: 'tool:error', toolCallId, error: reason });
                         return {
+                            error: reason,
+                            success: false,
+                            canRetry: false,
+                            suggestion: "Try an alternative approach",
+                        };
+                    }
+                    const timeoutMs = this.config.stepTimeoutMs;
+                    // Update summary tracker — tool is now executing
+                    const summaryTracker = getAgentSummaryTracker();
+                    const currentAction = summaryTracker.summarizeToolCall(this.state.sessionId, name, args);
+                    summaryTracker.update(this.state.sessionId, {
+                        status: 'executing',
+                        currentAction,
+                        lastToolName: name,
+                        lastToolArgs: JSON.stringify(args).substring(0, 100),
+                    });
+                    // beforeToolCall hook — may abort tool execution
+                    const beforeResult = await this.hooks.run('beforeToolCall', {
+                        hookPoint: 'beforeToolCall',
+                        sessionId: this.state.sessionId,
+                        toolName: name,
+                        toolArgs: args,
+                        metadata: {},
+                    });
+                    if (!beforeResult.proceed) {
+                        const blockReason = `Tool "${name}" blocked by hook`;
+                        logger.info("[AgentExecutor] Tool blocked by beforeToolCall hook", {
+                            tool: name,
+                        });
+                        push({ type: 'tool:error', toolCallId, error: blockReason });
+                        const blockedResult = {
+                            error: blockReason,
+                            success: false,
+                            canRetry: false,
+                            suggestion: 'A lifecycle hook prevented this tool from running.',
+                        };
+                        push({
+                            type: 'tool:result',
+                            toolCallId,
+                            result: blockedResult,
+                            duration: 0,
+                            success: false,
+                        });
+                        return blockedResult;
+                    }
+                    // Use potentially modified args from the hook
+                    const effectiveArgs = beforeResult.modified !== undefined && typeof beforeResult.modified === 'object' && beforeResult.modified !== null
+                        ? beforeResult.modified
+                        : args;
+                    // Push tool:call event before execution
+                    push({ type: 'tool:call', toolName: name, args: effectiveArgs, toolCallId });
+                    let timeoutHandle;
+                    const timeoutPromise = new Promise((_, reject) => {
+                        timeoutHandle = setTimeout(() => {
+                            reject(new Error(`__TOOL_TIMEOUT__:${timeoutMs}`));
+                        }, timeoutMs);
+                    });
+                    const startedAt = Date.now();
+                    try {
+                        const raw = await Promise.race([
+                            onToolExecute(name, effectiveArgs),
+                            timeoutPromise,
+                        ]);
+                        clearTimeout(timeoutHandle);
+                        this.circuitBreaker.recordSuccess(name);
+                        const stored = await this.resultStore.store(toolCallId, raw);
+                        const inlineResult = JSON.parse(stored.inline);
+                        const duration = Date.now() - startedAt;
+                        // afterToolCall hook — receives the result
+                        await this.hooks.run('afterToolCall', {
+                            hookPoint: 'afterToolCall',
+                            sessionId: this.state.sessionId,
+                            toolName: name,
+                            toolArgs: effectiveArgs,
+                            toolResult: inlineResult,
+                            metadata: {},
+                        });
+                        push({
+                            type: 'tool:result',
+                            toolCallId,
+                            result: inlineResult,
+                            duration,
+                            success: true,
+                        });
+                        return inlineResult;
+                    }
+                    catch (error) {
+                        clearTimeout(timeoutHandle);
+                        const errorMsg = error instanceof Error ? error.message : "Unknown error";
+                        const duration = Date.now() - startedAt;
+                        // Timeout path
+                        if (errorMsg.startsWith("__TOOL_TIMEOUT__:")) {
+                            const ms = errorMsg.split(":")[1];
+                            logger.warn("[AgentExecutor] Tool execution timed out", {
+                                tool: name,
+                                timeoutMs,
+                            });
+                            this.circuitBreaker.recordFailure(name);
+                            const timeoutResult = {
+                                error: `Tool execution timed out after ${ms}ms`,
+                                success: false,
+                                canRetry: true,
+                            };
+                            push({ type: 'tool:error', toolCallId, error: timeoutResult.error });
+                            push({
+                                type: 'tool:result',
+                                toolCallId,
+                                result: timeoutResult,
+                                duration,
+                                success: false,
+                            });
+                            return timeoutResult;
+                        }
+                        // Regular error path
+                        const isPermError = errorMsg.toLowerCase().includes("permission") ||
+                            errorMsg.toLowerCase().includes("unauthorized") ||
+                            errorMsg.toLowerCase().includes("forbidden") ||
+                            errorMsg.toLowerCase().includes("not allowed");
+                        logger.warn("[AgentExecutor] Tool execution failed", {
+                            tool: name,
+                            error: errorMsg,
+                        });
+                        this.circuitBreaker.recordFailure(name);
+                        push({ type: 'tool:error', toolCallId, error: errorMsg });
+                        const errorResult = {
                             error: errorMsg,
                             success: false,
                             suggestion: "This tool failed. Consider trying a different approach or asking the user for help.",
                             canRetry: !isPermError,
                         };
+                        push({
+                            type: 'tool:result',
+                            toolCallId,
+                            result: errorResult,
+                            duration,
+                            success: false,
+                        });
+                        return errorResult;
                     }
                 },
             };
@@ -524,8 +977,37 @@ export class AgentExecutor extends EventEmitter {
             }
         }
     }
+    /** Route one step's usage (with cache tokens) into the cost tracker. */
+    trackStepUsage(model, inputTokens, outputTokens, cache) {
+        const total = inputTokens + outputTokens;
+        if (total <= 0)
+            return;
+        const modelId = typeof model === "string" ? model : getRecord(model)?.modelId;
+        if (typeof modelId !== "string" || modelId.length === 0)
+            return;
+        try {
+            trackChatUsage(modelId, total, inputTokens, outputTokens, {
+                cacheReadTokens: cache.cacheReadTokens,
+                cacheWriteTokens: cache.cacheWriteTokens,
+            });
+        }
+        catch (err) {
+            logger.warn("[AgentExecutor] Usage tracking failed", {
+                sessionId: this.state.sessionId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
     // Finalization
     finalize() {
+        // Clean up any temp files written by the result store (fire-and-forget)
+        this.resultStore.cleanup().catch((err) => {
+            logger.warn("[AgentExecutor] ResultStore cleanup failed", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        // Remove this session from the summary tracker
+        getAgentSummaryTracker().end(this.state.sessionId);
         const completedViaTask = this.state.toolCallHistory.some((t) => t.name === "complete_task" && t.status === "executed");
         // Check if agent completed via text response (no tool calls)
         const completedViaTextResponse = this.state.toolCallHistory.length === 0 ||