@compilr-dev/agents 0.3.9 → 0.3.10

package/dist/agent.d.ts

@@ -1231,6 +1231,11 @@ export declare class Agent {
      * Get the context manager (if configured)
      */
     getContextManager(): ContextManager | undefined;
+    /**
+     * Get the tool registry instance.
+     * Useful for setting up fallback handlers or inspecting registered tools.
+     */
+    getToolRegistry(): ToolRegistry;
     /**
      * Get context statistics
      */

package/dist/agent.js

@@ -756,6 +756,13 @@ export class Agent {
     getContextManager() {
         return this.contextManager;
     }
+    /**
+     * Get the tool registry instance.
+     * Useful for setting up fallback handlers or inspecting registered tools.
+     */
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
     /**
      * Get context statistics
      */
@@ -1525,247 +1532,237 @@ export class Agent {
         // Tool loop detection: track consecutive identical calls
         let lastToolCallHash = '';
         let consecutiveIdenticalCalls = 0;
-        // Hash function for tool call comparison
-        const hashToolCall = (name, input) => {
-            return `${name}:${JSON.stringify(input, Object.keys(input).sort())}`;
-        };
-        // Agentic loop
-        while (iterations < maxIterations) {
-            // Check for abort
-            if (signal?.aborted) {
-                aborted = true;
-                break;
-            }
-            iterations++;
-            emit({ type: 'iteration_start', iteration: iterations });
-            // Hook context for this iteration
-            const hookContext = {
-                sessionId: this._sessionId,
-                iteration: iterations,
-                signal,
-                metadata: {},
-            };
-            // Track tool calls for this iteration (for afterIteration hook)
-            const iterationToolCalls = [];
-            // Run beforeIteration hooks
-            if (this.hooksManager) {
-                const shouldContinue = await this.hooksManager.runBeforeIteration({
-                    ...hookContext,
-                    maxIterations,
-                    messages,
-                });
-                if (!shouldContinue) {
-                    emit({ type: 'iteration_end', iteration: iterations });
-                    continue;
-                }
-            }
-            // Get tool definitions
-            let tools = this.toolRegistry.getDefinitions();
-            // Apply tool filter if specified (reduces token usage)
-            if (options?.toolFilter && options.toolFilter.length > 0) {
-                const filterSet = new Set(options.toolFilter);
-                tools = tools.filter((tool) => filterSet.has(tool.name));
-            }
-            // Run beforeLLM hooks (can modify messages and tools)
-            if (this.hooksManager) {
-                const llmHookResult = await this.hooksManager.runBeforeLLM({
-                    ...hookContext,
-                    messages,
-                    tools,
-                });
-                messages = llmHookResult.messages;
-                tools = llmHookResult.tools;
-            }
-            // Call LLM
-            emit({ type: 'llm_start' });
-            const llmStartTime = Date.now();
-            const chunks = [];
-            try {
-                for await (const chunk of this.chatWithRetry(messages, {
-                    ...chatOptions,
-                    tools: tools.length > 0 ? tools : undefined,
-                }, emit, signal)) {
-                    // Check for abort during streaming
-                    if (signal?.aborted) {
-                        aborted = true;
-                        break;
+        // Hash function for tool call comparison.
+        // Uses a JSON replacer that recursively sorts object keys for stable hashing.
+        // NOTE: A simple `JSON.stringify(input, Object.keys(input).sort())` only sorts
+        // top-level keys — nested objects are serialized as `{}` because the replacer
+        // array doesn't include their keys. This caused false positives for meta-tools
+        // like `use_tool` where the actual arguments are nested inside `args`.
+        const stableStringify = (obj) => {
+            return JSON.stringify(obj, (_key, value) => {
+                if (value && typeof value === 'object' && !Array.isArray(value)) {
+                    const sorted = {};
+                    for (const k of Object.keys(value).sort()) {
+                        sorted[k] = value[k];
                     }
-                    chunks.push(chunk);
-                    emit({ type: 'llm_chunk', chunk });
+                    return sorted;
                 }
-            }
-            catch (error) {
+                return value;
+            });
+        };
+        const hashToolCall = (name, input) => {
+            return `${name}:${stableStringify(input)}`;
+        };
+        // Wrap agentic loop in try/finally to ensure conversation history is always
+        // preserved, even when ToolLoopError or MaxIterationsError is thrown.
+        // Without this, a thrown error skips the history append and the agent
+        // loses all memory of the current run.
+        try {
+            // Agentic loop
+            while (iterations < maxIterations) {
+                // Check for abort
                 if (signal?.aborted) {
                     aborted = true;
                     break;
                 }
-                // Run onError hooks
-                if (this.hooksManager && error instanceof Error) {
-                    const errorResult = await this.hooksManager.runOnError({
+                iterations++;
+                emit({ type: 'iteration_start', iteration: iterations });
+                // Hook context for this iteration
+                const hookContext = {
+                    sessionId: this._sessionId,
+                    iteration: iterations,
+                    signal,
+                    metadata: {},
+                };
+                // Track tool calls for this iteration (for afterIteration hook)
+                const iterationToolCalls = [];
+                // Run beforeIteration hooks
+                if (this.hooksManager) {
+                    const shouldContinue = await this.hooksManager.runBeforeIteration({
                         ...hookContext,
-                        error,
-                        phase: 'llm',
+                        maxIterations,
+                        messages,
                     });
-                    if (errorResult.handled) {
-                        // Error was handled by hook, continue with next iteration
+                    if (!shouldContinue) {
+                        emit({ type: 'iteration_end', iteration: iterations });
                         continue;
                     }
-                    if (errorResult.error) {
-                        throw errorResult.error;
-                    }
                 }
-                throw error;
-            }
-            if (aborted) {
-                break;
-            }
-            // Process response
-            const { text, toolUses, usage, model } = this.processChunks(chunks);
-            emit({ type: 'llm_end', text, hasToolUses: toolUses.length > 0 });
-            // Record usage if available
-            if (usage && model) {
-                this.recordUsage(model, this.provider.name, {
-                    inputTokens: usage.inputTokens,
-                    outputTokens: usage.outputTokens,
-                    totalTokens: usage.inputTokens + usage.outputTokens,
-                    cacheReadTokens: usage.cacheReadTokens,
-                    cacheCreationTokens: usage.cacheCreationTokens,
-                });
-            }
-            // Run afterLLM hooks
-            if (this.hooksManager) {
-                await this.hooksManager.runAfterLLM({
-                    ...hookContext,
-                    messages,
-                    tools,
-                    text,
-                    toolUses,
-                    usage: usage
-                        ? { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens }
-                        : undefined,
-                    model,
-                    durationMs: Date.now() - llmStartTime,
-                });
-            }
-            // If no tool uses, we're done
-            if (toolUses.length === 0) {
-                finalResponse = text;
-                // Add final assistant response to history (only if non-empty)
-                // Empty responses can occur after silent tools like 'suggest'
-                if (text) {
-                    const finalAssistantMsg = {
-                        role: 'assistant',
-                        content: text,
-                    };
-                    newMessages.push(finalAssistantMsg);
+                // Get tool definitions
+                let tools = this.toolRegistry.getDefinitions();
+                // Apply tool filter if specified (reduces token usage)
+                if (options?.toolFilter && options.toolFilter.length > 0) {
+                    const filterSet = new Set(options.toolFilter);
+                    tools = tools.filter((tool) => filterSet.has(tool.name));
                 }
-                // Run afterIteration hooks
+                // Run beforeLLM hooks (can modify messages and tools)
                 if (this.hooksManager) {
-                    await this.hooksManager.runAfterIteration({
+                    const llmHookResult = await this.hooksManager.runBeforeLLM({
                         ...hookContext,
-                        maxIterations,
                         messages,
-                        toolCalls: iterationToolCalls,
-                        completedWithText: true,
+                        tools,
                     });
+                    messages = llmHookResult.messages;
+                    tools = llmHookResult.tools;
                 }
-                emit({ type: 'iteration_end', iteration: iterations });
-                break;
-            }
-            // Add assistant message with tool uses
-            const assistantMsg = {
-                role: 'assistant',
-                content: [
-                    ...(text ? [{ type: 'text', text }] : []),
-                    ...toolUses.map((tu) => ({
-                        type: 'tool_use',
-                        id: tu.id,
-                        name: tu.name,
-                        input: tu.input,
-                        signature: tu.signature, // Gemini 3 thought signature (required for multi-turn)
-                    })),
-                ],
-            };
-            messages.push(assistantMsg);
-            newMessages.push(assistantMsg);
-            // Execute tools and add results
-            // Check if we can parallelize - only parallelize tools marked as parallel-safe
-            const parallelTools = toolUses.filter((tu) => {
-                const tool = this.toolRegistry.get(tu.name);
-                return tool?.parallel === true;
-            });
-            const canParallelize = parallelTools.length > 1 && parallelTools.length === toolUses.length;
-            // Helper to execute a single tool with all checks
-            const executeSingleTool = async (toolUse) => {
-                // Check for abort
-                if (signal?.aborted) {
-                    return {
-                        result: { success: false, error: 'Aborted' },
-                        toolResultMsg: {
-                            role: 'user',
-                            content: [
-                                { type: 'tool_result', toolUseId: toolUse.id, content: 'Aborted', isError: true },
-                            ],
-                        },
-                        skipped: true,
-                        aborted: true,
-                    };
+                // Call LLM
+                emit({ type: 'llm_start' });
+                const llmStartTime = Date.now();
+                const chunks = [];
+                try {
+                    for await (const chunk of this.chatWithRetry(messages, {
+                        ...chatOptions,
+                        tools: tools.length > 0 ? tools : undefined,
+                    }, emit, signal)) {
+                        // Check for abort during streaming
+                        if (signal?.aborted) {
+                            aborted = true;
+                            break;
+                        }
+                        chunks.push(chunk);
+                        emit({ type: 'llm_chunk', chunk });
+                    }
                 }
-                emit({
-                    type: 'tool_start',
-                    name: toolUse.name,
-                    input: toolUse.input,
-                    toolUseId: toolUse.id,
-                });
-                let result;
-                // Check permissions before execution
-                if (this.permissionManager) {
-                    const permResult = await this.permissionManager.check(toolUse.name, toolUse.input);
-                    if (permResult.askedUser) {
-                        emit({ type: 'permission_asked', toolName: toolUse.name, level: permResult.level });
+                catch (error) {
+                    if (signal?.aborted) {
+                        aborted = true;
+                        break;
                     }
-                    if (!permResult.allowed) {
-                        emit({
-                            type: 'permission_denied',
-                            toolName: toolUse.name,
-                            level: permResult.level,
-                            reason: permResult.reason,
+                    // Run onError hooks
+                    if (this.hooksManager && error instanceof Error) {
+                        const errorResult = await this.hooksManager.runOnError({
+                            ...hookContext,
+                            error,
+                            phase: 'llm',
                         });
-                        result = {
-                            success: false,
-                            error: `Permission denied: ${permResult.reason ?? 'Tool execution not allowed'}`,
+                        if (errorResult.handled) {
+                            // Error was handled by hook, continue with next iteration
+                            continue;
+                        }
+                        if (errorResult.error) {
+                            throw errorResult.error;
+                        }
+                    }
+                    throw error;
+                }
+                if (aborted) {
+                    break;
+                }
+                // Process response
+                const { text, toolUses, usage, model } = this.processChunks(chunks);
+                emit({ type: 'llm_end', text, hasToolUses: toolUses.length > 0 });
+                // Record usage if available
+                if (usage && model) {
+                    this.recordUsage(model, this.provider.name, {
+                        inputTokens: usage.inputTokens,
+                        outputTokens: usage.outputTokens,
+                        totalTokens: usage.inputTokens + usage.outputTokens,
+                        cacheReadTokens: usage.cacheReadTokens,
+                        cacheCreationTokens: usage.cacheCreationTokens,
+                    });
+                }
+                // Run afterLLM hooks
+                if (this.hooksManager) {
+                    await this.hooksManager.runAfterLLM({
+                        ...hookContext,
+                        messages,
+                        tools,
+                        text,
+                        toolUses,
+                        usage: usage
+                            ? { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens }
+                            : undefined,
+                        model,
+                        durationMs: Date.now() - llmStartTime,
+                    });
+                }
+                // If no tool uses, we're done
+                if (toolUses.length === 0) {
+                    finalResponse = text;
+                    // Add final assistant response to history (only if non-empty)
+                    // Empty responses can occur after silent tools like 'suggest'
+                    if (text) {
+                        const finalAssistantMsg = {
+                            role: 'assistant',
+                            content: text,
                         };
-                        emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                        newMessages.push(finalAssistantMsg);
+                    }
+                    // Run afterIteration hooks
+                    if (this.hooksManager) {
+                        await this.hooksManager.runAfterIteration({
+                            ...hookContext,
+                            maxIterations,
+                            messages,
+                            toolCalls: iterationToolCalls,
+                            completedWithText: true,
+                        });
+                    }
+                    emit({ type: 'iteration_end', iteration: iterations });
+                    break;
+                }
+                // Add assistant message with tool uses
+                const assistantMsg = {
+                    role: 'assistant',
+                    content: [
+                        ...(text ? [{ type: 'text', text }] : []),
+                        ...toolUses.map((tu) => ({
+                            type: 'tool_use',
+                            id: tu.id,
+                            name: tu.name,
+                            input: tu.input,
+                            signature: tu.signature, // Gemini 3 thought signature (required for multi-turn)
+                        })),
+                    ],
+                };
+                messages.push(assistantMsg);
+                newMessages.push(assistantMsg);
+                // Execute tools and add results
+                // Check if we can parallelize - only parallelize tools marked as parallel-safe
+                const parallelTools = toolUses.filter((tu) => {
+                    const tool = this.toolRegistry.get(tu.name);
+                    return tool?.parallel === true;
+                });
+                const canParallelize = parallelTools.length > 1 && parallelTools.length === toolUses.length;
+                // Helper to execute a single tool with all checks
+                const executeSingleTool = async (toolUse) => {
+                    // Check for abort
+                    if (signal?.aborted) {
                         return {
-                            result,
+                            result: { success: false, error: 'Aborted' },
                             toolResultMsg: {
                                 role: 'user',
                                 content: [
-                                    {
-                                        type: 'tool_result',
-                                        toolUseId: toolUse.id,
-                                        content: `Error: ${result.error ?? 'Permission denied'}`,
-                                        isError: true,
-                                    },
+                                    { type: 'tool_result', toolUseId: toolUse.id, content: 'Aborted', isError: true },
                                 ],
                             },
                             skipped: true,
-                            aborted: false,
+                            aborted: true,
                         };
                     }
-                    emit({ type: 'permission_granted', toolName: toolUse.name, level: permResult.level });
-                }
-                // Check guardrails before execution
-                if (this.guardrailManager) {
-                    const { proceed, result: guardrailResult } = await this.guardrailManager.checkAndHandle(toolUse.name, toolUse.input);
-                    if (guardrailResult.triggered) {
-                        emit({ type: 'guardrail_triggered', result: guardrailResult });
-                        if (!proceed) {
-                            const message = guardrailResult.guardrail?.message ?? 'Operation blocked by guardrail';
-                            emit({ type: 'guardrail_blocked', result: guardrailResult, message });
+                    emit({
+                        type: 'tool_start',
+                        name: toolUse.name,
+                        input: toolUse.input,
+                        toolUseId: toolUse.id,
+                    });
+                    let result;
+                    // Check permissions before execution
+                    if (this.permissionManager) {
+                        const permResult = await this.permissionManager.check(toolUse.name, toolUse.input);
+                        if (permResult.askedUser) {
+                            emit({ type: 'permission_asked', toolName: toolUse.name, level: permResult.level });
+                        }
+                        if (!permResult.allowed) {
+                            emit({
+                                type: 'permission_denied',
+                                toolName: toolUse.name,
+                                level: permResult.level,
+                                reason: permResult.reason,
+                            });
                             result = {
                                 success: false,
-                                error: `Guardrail blocked: ${message}`,
+                                error: `Permission denied: ${permResult.reason ?? 'Tool execution not allowed'}`,
                             };
                             emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
                             return {
@@ -1776,7 +1773,7 @@ export class Agent {
                                         {
                                             type: 'tool_result',
                                             toolUseId: toolUse.id,
-                                            content: `Error: ${result.error ?? 'Blocked by guardrail'}`,
+                                            content: `Error: ${result.error ?? 'Permission denied'}`,
                                             isError: true,
                                         },
                                     ],
@@ -1785,302 +1782,341 @@ export class Agent {
                                 aborted: false,
                             };
                         }
-                        else if (guardrailResult.action === 'warn') {
-                            const message = guardrailResult.guardrail?.message ?? 'Warning from guardrail';
-                            emit({ type: 'guardrail_warning', result: guardrailResult, message });
-                        }
+                        emit({ type: 'permission_granted', toolName: toolUse.name, level: permResult.level });
                     }
-                }
-                // Run beforeTool hooks (can skip or modify input)
-                let toolInput = toolUse.input;
-                if (this.hooksManager) {
-                    const beforeToolResult = await this.hooksManager.runBeforeTool({
-                        ...hookContext,
-                        toolName: toolUse.name,
-                        input: toolInput,
-                    });
-                    if (!beforeToolResult.proceed) {
-                        result = beforeToolResult.skipResult ?? { success: false, error: 'Skipped by hook' };
-                        emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
-                        return {
-                            result,
-                            toolResultMsg: {
-                                role: 'user',
-                                content: [
-                                    {
-                                        type: 'tool_result',
-                                        toolUseId: toolUse.id,
-                                        content: result.success
-                                            ? JSON.stringify(result.result)
-                                            : `Error: ${result.error ?? 'Unknown error'}`,
-                                        isError: !result.success,
+                    // Check guardrails before execution
+                    if (this.guardrailManager) {
+                        const { proceed, result: guardrailResult } = await this.guardrailManager.checkAndHandle(toolUse.name, toolUse.input);
+                        if (guardrailResult.triggered) {
+                            emit({ type: 'guardrail_triggered', result: guardrailResult });
+                            if (!proceed) {
+                                const message = guardrailResult.guardrail?.message ?? 'Operation blocked by guardrail';
+                                emit({ type: 'guardrail_blocked', result: guardrailResult, message });
+                                result = {
+                                    success: false,
+                                    error: `Guardrail blocked: ${message}`,
+                                };
+                                emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                                return {
+                                    result,
+                                    toolResultMsg: {
+                                        role: 'user',
+                                        content: [
+                                            {
+                                                type: 'tool_result',
+                                                toolUseId: toolUse.id,
+                                                content: `Error: ${result.error ?? 'Blocked by guardrail'}`,
+                                                isError: true,
+                                            },
+                                        ],
                                     },
-                                ],
+                                    skipped: true,
+                                    aborted: false,
+                                };
+                            }
+                            else if (guardrailResult.action === 'warn') {
+                                const message = guardrailResult.guardrail?.message ?? 'Warning from guardrail';
+                                emit({ type: 'guardrail_warning', result: guardrailResult, message });
+                            }
+                        }
+                    }
+                    // Run beforeTool hooks (can skip or modify input)
+                    let toolInput = toolUse.input;
+                    if (this.hooksManager) {
+                        const beforeToolResult = await this.hooksManager.runBeforeTool({
+                            ...hookContext,
+                            toolName: toolUse.name,
+                            input: toolInput,
+                        });
+                        if (!beforeToolResult.proceed) {
+                            result = beforeToolResult.skipResult ?? { success: false, error: 'Skipped by hook' };
+                            emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                            return {
+                                result,
+                                toolResultMsg: {
+                                    role: 'user',
+                                    content: [
+                                        {
+                                            type: 'tool_result',
+                                            toolUseId: toolUse.id,
+                                            content: result.success
+                                                ? JSON.stringify(result.result)
+                                                : `Error: ${result.error ?? 'Unknown error'}`,
+                                            isError: !result.success,
+                                        },
+                                    ],
+                                },
+                                skipped: true,
+                                aborted: false,
+                            };
+                        }
+                        toolInput = beforeToolResult.input;
+                    }
+                    const toolStartTime = Date.now();
+                    try {
+                        // Get additional context from caller (e.g., for bash backgrounding)
+                        const additionalContext = getToolContext?.(toolUse.name, toolUse.id) ?? {};
+                        const toolContext = {
+                            toolUseId: toolUse.id,
+                            onOutput: (output, stream) => {
+                                emit({
+                                    type: 'tool_output',
+                                    toolUseId: toolUse.id,
+                                    toolName: toolUse.name,
+                                    output,
+                                    stream,
+                                });
                             },
-                            skipped: true,
-                            aborted: false,
+                            // Merge in additional context (abortSignal, onBackground, etc.)
+                            ...additionalContext,
                         };
+                        result = await this.toolRegistry.execute(toolUse.name, toolInput, toolContext);
                     }
-                    toolInput = beforeToolResult.input;
-                }
-                const toolStartTime = Date.now();
-                try {
-                    // Get additional context from caller (e.g., for bash backgrounding)
-                    const additionalContext = getToolContext?.(toolUse.name, toolUse.id) ?? {};
-                    const toolContext = {
-                        toolUseId: toolUse.id,
-                        onOutput: (output, stream) => {
-                            emit({
-                                type: 'tool_output',
-                                toolUseId: toolUse.id,
+                    catch (error) {
+                        if (this.hooksManager && error instanceof Error) {
+                            const errorResult = await this.hooksManager.runOnError({
+                                ...hookContext,
+                                error,
+                                phase: 'tool',
                                 toolName: toolUse.name,
-                                output,
-                                stream,
                             });
-                        },
-                        // Merge in additional context (abortSignal, onBackground, etc.)
-                        ...additionalContext,
-                    };
-                    result = await this.toolRegistry.execute(toolUse.name, toolInput, toolContext);
-                }
-                catch (error) {
-                    if (this.hooksManager && error instanceof Error) {
+                            if (errorResult.recovery) {
+                                result = errorResult.recovery;
+                            }
+                            else {
+                                result = {
+                                    success: false,
+                                    error: errorResult.error?.message ?? error.message,
+                                };
+                            }
+                        }
+                        else {
+                            result = {
+                                success: false,
+                                error: error instanceof Error ? error.message : String(error),
+                            };
+                        }
+                    }
+                    // Run onError hooks for failed tool results
+                    if (this.hooksManager && !result.success) {
+                        const syntheticError = new Error(result.error);
                         const errorResult = await this.hooksManager.runOnError({
                             ...hookContext,
-                            error,
+                            error: syntheticError,
                             phase: 'tool',
                             toolName: toolUse.name,
                         });
                         if (errorResult.recovery) {
                             result = errorResult.recovery;
                         }
-                        else {
-                            result = {
-                                success: false,
-                                error: errorResult.error?.message ?? error.message,
-                            };
+                    }
+                    // Run afterTool hooks (can modify result)
+                    if (this.hooksManager) {
+                        result = await this.hooksManager.runAfterTool({
+                            ...hookContext,
+                            toolName: toolUse.name,
+                            input: toolInput,
+                            result,
+                            durationMs: Date.now() - toolStartTime,
+                        });
+                    }
+                    emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
+                    // Build tool result content
+                    let toolResultContent = result.success
+                        ? JSON.stringify(result.result)
+                        : `Error: ${result.error ?? 'Unknown error'}`;
+                    // Context management (only for sequential - parallel handles this after)
+                    if (!canParallelize && this.contextManager && this.autoContextManagement) {
+                        const estimatedTokens = this.contextManager.estimateTokens(toolResultContent);
+                        const preflight = this.contextManager.canAddContent(estimatedTokens, 'toolResults');
+                        if (!preflight.allowed) {
+                            if (preflight.action === 'reject') {
+                                const filtered = this.contextManager.filterContent(toolResultContent, 'tool_result');
+                                toolResultContent = filtered.content;
+                            }
+                            // Note: compact/summarize actions are complex with parallel execution
+                            // For now, only filter is applied during parallel; full context mgmt happens after
                         }
+                        const finalTokens = this.contextManager.estimateTokens(toolResultContent);
+                        this.contextManager.addToCategory('toolResults', finalTokens);
                     }
-                    else {
-                        result = {
-                            success: false,
-                            error: error instanceof Error ? error.message : String(error),
-                        };
+                    return {
+                        result,
+                        toolResultMsg: {
+                            role: 'user',
+                            content: [
+                                {
+                                    type: 'tool_result',
+                                    toolUseId: toolUse.id,
+                                    content: toolResultContent,
+                                    isError: !result.success,
+                                },
+                            ],
+                        },
+                        skipped: false,
+                        aborted: false,
+                    };
+                };
+                // Execute tools - parallel if all are parallel-safe, otherwise sequential
+                if (canParallelize) {
+                    // Parallel execution
+                    const results = await Promise.all(toolUses.map((tu) => executeSingleTool(tu)));
+                    for (let i = 0; i < toolUses.length; i++) {
+                        const toolUse = toolUses[i];
+                        const { result, toolResultMsg, aborted: wasAborted } = results[i];
+                        if (wasAborted) {
+                            aborted = true;
+                            break;
+                        }
+                        // Tool loop detection (still applies per-tool)
+                        if (this.maxConsecutiveToolCalls > 0) {
+                            const currentHash = hashToolCall(toolUse.name, toolUse.input);
+                            if (currentHash === lastToolCallHash) {
+                                consecutiveIdenticalCalls++;
+                                if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
+                                    throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                }
+                                emit({
+                                    type: 'tool_loop_warning',
+                                    toolName: toolUse.name,
+                                    consecutiveCalls: consecutiveIdenticalCalls,
+                                });
+                            }
+                            else {
+                                lastToolCallHash = currentHash;
+                                consecutiveIdenticalCalls = 1;
+                            }
+                        }
+                        const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                        toolCalls.push(toolCallEntry);
+                        iterationToolCalls.push(toolCallEntry);
+                        messages.push(toolResultMsg);
+                        newMessages.push(toolResultMsg);
                     }
                 }
-                // Run onError hooks for failed tool results
-                if (this.hooksManager && !result.success) {
-                    const syntheticError = new Error(result.error);
-                    const errorResult = await this.hooksManager.runOnError({
-                        ...hookContext,
-                        error: syntheticError,
-                        phase: 'tool',
-                        toolName: toolUse.name,
-                    });
-                    if (errorResult.recovery) {
-                        result = errorResult.recovery;
+                else {
+                    // Sequential execution (original loop, but using the helper)
+                    for (const toolUse of toolUses) {
+                        const { result, toolResultMsg, skipped, aborted: wasAborted, } = await executeSingleTool(toolUse);
+                        if (wasAborted) {
+                            aborted = true;
+                            break;
+                        }
+                        // Tool loop detection
+                        if (this.maxConsecutiveToolCalls > 0) {
+                            const currentHash = hashToolCall(toolUse.name, toolUse.input);
+                            if (currentHash === lastToolCallHash) {
+                                consecutiveIdenticalCalls++;
+                                if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
+                                    throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                }
+                                emit({
+                                    type: 'tool_loop_warning',
+                                    toolName: toolUse.name,
+                                    consecutiveCalls: consecutiveIdenticalCalls,
+                                });
+                            }
+                            else {
+                                lastToolCallHash = currentHash;
+                                consecutiveIdenticalCalls = 1;
+                            }
+                        }
+                        const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                        toolCalls.push(toolCallEntry);
+                        iterationToolCalls.push(toolCallEntry);
+                        messages.push(toolResultMsg);
+                        newMessages.push(toolResultMsg);
+                        if (skipped) {
+                            continue;
+                        }
                     }
                 }
-                // Run afterTool hooks (can modify result)
+                if (aborted) {
+                    break;
+                }
+                // Run afterIteration hooks
                 if (this.hooksManager) {
-                    result = await this.hooksManager.runAfterTool({
+                    await this.hooksManager.runAfterIteration({
                         ...hookContext,
-                        toolName: toolUse.name,
-                        input: toolInput,
-                        result,
-                        durationMs: Date.now() - toolStartTime,
+                        maxIterations,
+                        messages,
+                        toolCalls: iterationToolCalls,
+                        completedWithText: false,
                     });
                 }
-                emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
-                // Build tool result content
-                let toolResultContent = result.success
-                    ? JSON.stringify(result.result)
-                    : `Error: ${result.error ?? 'Unknown error'}`;
-                // Context management (only for sequential - parallel handles this after)
-                if (!canParallelize && this.contextManager && this.autoContextManagement) {
-                    const estimatedTokens = this.contextManager.estimateTokens(toolResultContent);
-                    const preflight = this.contextManager.canAddContent(estimatedTokens, 'toolResults');
-                    if (!preflight.allowed) {
-                        if (preflight.action === 'reject') {
-                            const filtered = this.contextManager.filterContent(toolResultContent, 'tool_result');
-                            toolResultContent = filtered.content;
-                        }
-                        // Note: compact/summarize actions are complex with parallel execution
-                        // For now, only filter is applied during parallel; full context mgmt happens after
+                emit({ type: 'iteration_end', iteration: iterations });
+                // Check if we're about to hit the iteration limit
+                // If callback is defined, ask if we should continue
+                if (iterations >= maxIterations && this.onIterationLimitReached) {
+                    emit({
+                        type: 'iteration_limit_reached',
+                        iteration: iterations,
+                        maxIterations,
+                    });
+                    const result = await this.onIterationLimitReached({
+                        iteration: iterations,
+                        maxIterations,
+                        toolCallCount: toolCalls.length,
+                    });
+                    if (typeof result === 'number' && result > 0) {
+                        // Extend the limit and continue
+                        maxIterations += result;
+                        emit({
+                            type: 'iteration_limit_extended',
+                            newMaxIterations: maxIterations,
+                            addedIterations: result,
+                        });
                     }
-                    const finalTokens = this.contextManager.estimateTokens(toolResultContent);
-                    this.contextManager.addToCategory('toolResults', finalTokens);
-                }
-                return {
-                    result,
-                    toolResultMsg: {
-                        role: 'user',
-                        content: [
-                            {
-                                type: 'tool_result',
-                                toolUseId: toolUse.id,
-                                content: toolResultContent,
-                                isError: !result.success,
-                            },
-                        ],
-                    },
-                    skipped: false,
-                    aborted: false,
-                };
-            };
-            // Execute tools - parallel if all are parallel-safe, otherwise sequential
-            if (canParallelize) {
-                // Parallel execution
-                const results = await Promise.all(toolUses.map((tu) => executeSingleTool(tu)));
-                for (let i = 0; i < toolUses.length; i++) {
-                    const toolUse = toolUses[i];
-                    const { result, toolResultMsg, aborted: wasAborted } = results[i];
-                    if (wasAborted) {
+                    else {
+                        // User chose to stop - set aborted to prevent error throw
                         aborted = true;
-                        break;
-                    }
-                    // Tool loop detection (still applies per-tool)
-                    if (this.maxConsecutiveToolCalls > 0) {
-                        const currentHash = hashToolCall(toolUse.name, toolUse.input);
-                        if (currentHash === lastToolCallHash) {
-                            consecutiveIdenticalCalls++;
-                            if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                            }
-                            emit({
-                                type: 'tool_loop_warning',
-                                toolName: toolUse.name,
-                                consecutiveCalls: consecutiveIdenticalCalls,
-                            });
-                        }
-                        else {
-                            lastToolCallHash = currentHash;
-                            consecutiveIdenticalCalls = 1;
-                        }
+                        emit({ type: 'done', response: finalResponse });
                     }
-                    const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                    toolCalls.push(toolCallEntry);
-                    iterationToolCalls.push(toolCallEntry);
-                    messages.push(toolResultMsg);
-                    newMessages.push(toolResultMsg);
                 }
             }
-            else {
-                // Sequential execution (original loop, but using the helper)
-                for (const toolUse of toolUses) {
-                    const { result, toolResultMsg, skipped, aborted: wasAborted, } = await executeSingleTool(toolUse);
-                    if (wasAborted) {
-                        aborted = true;
-                        break;
+            // Check if we hit max iterations without completing
+            if (!aborted && iterations >= maxIterations && finalResponse === '') {
+                if (this.iterationLimitBehavior === 'summarize') {
+                    // Generate a summary response before throwing
+                    try {
+                        finalResponse = await this.generateIterationLimitSummary(messages, maxIterations, toolCalls);
+                        emit({ type: 'done', response: finalResponse });
                     }
-                    // Tool loop detection
-                    if (this.maxConsecutiveToolCalls > 0) {
-                        const currentHash = hashToolCall(toolUse.name, toolUse.input);
-                        if (currentHash === lastToolCallHash) {
-                            consecutiveIdenticalCalls++;
-                            if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                            }
-                            emit({
-                                type: 'tool_loop_warning',
-                                toolName: toolUse.name,
-                                consecutiveCalls: consecutiveIdenticalCalls,
-                            });
-                        }
-                        else {
-                            lastToolCallHash = currentHash;
-                            consecutiveIdenticalCalls = 1;
-                        }
-                    }
-                    const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                    toolCalls.push(toolCallEntry);
-                    iterationToolCalls.push(toolCallEntry);
-                    messages.push(toolResultMsg);
-                    newMessages.push(toolResultMsg);
-                    if (skipped) {
-                        continue;
+                    catch {
+                        // If summary generation fails, still throw the error
+                        throw new MaxIterationsError(maxIterations);
                     }
                 }
-            }
-            if (aborted) {
-                break;
-            }
-            // Run afterIteration hooks
-            if (this.hooksManager) {
-                await this.hooksManager.runAfterIteration({
-                    ...hookContext,
-                    maxIterations,
-                    messages,
-                    toolCalls: iterationToolCalls,
-                    completedWithText: false,
-                });
-            }
-            emit({ type: 'iteration_end', iteration: iterations });
-            // Check if we're about to hit the iteration limit
-            // If callback is defined, ask if we should continue
-            if (iterations >= maxIterations && this.onIterationLimitReached) {
-                emit({
-                    type: 'iteration_limit_reached',
-                    iteration: iterations,
-                    maxIterations,
-                });
-                const result = await this.onIterationLimitReached({
-                    iteration: iterations,
-                    maxIterations,
-                    toolCallCount: toolCalls.length,
-                });
-                if (typeof result === 'number' && result > 0) {
-                    // Extend the limit and continue
-                    maxIterations += result;
-                    emit({
-                        type: 'iteration_limit_extended',
-                        newMaxIterations: maxIterations,
-                        addedIterations: result,
-                    });
+                else if (this.iterationLimitBehavior === 'continue') {
+                    // Return partial result without throwing
+                    finalResponse =
+                        `[Agent reached maximum iterations (${String(maxIterations)}) without completing. ` +
+                            `${String(toolCalls.length)} tool calls were made.]`;
                 }
                 else {
-                    // User chose to stop - set aborted to prevent error throw
-                    aborted = true;
-                    emit({ type: 'done', response: finalResponse });
-                }
-            }
-        }
-        // Check if we hit max iterations without completing
-        if (!aborted && iterations >= maxIterations && finalResponse === '') {
-            if (this.iterationLimitBehavior === 'summarize') {
-                // Generate a summary response before throwing
-                try {
-                    finalResponse = await this.generateIterationLimitSummary(messages, maxIterations, toolCalls);
-                    emit({ type: 'done', response: finalResponse });
-                }
-                catch {
-                    // If summary generation fails, still throw the error
+                    // Default: throw error
                     throw new MaxIterationsError(maxIterations);
                 }
             }
-            else if (this.iterationLimitBehavior === 'continue') {
-                // Return partial result without throwing
-                finalResponse =
-                    `[Agent reached maximum iterations (${String(maxIterations)}) without completing. ` +
-                        `${String(toolCalls.length)} tool calls were made.]`;
-            }
-            else {
-                // Default: throw error
-                throw new MaxIterationsError(maxIterations);
+            if (!aborted && !(iterations >= maxIterations && this.iterationLimitBehavior === 'summarize')) {
+                emit({ type: 'done', response: finalResponse });
             }
         }
-        if (!aborted && !(iterations >= maxIterations && this.iterationLimitBehavior === 'summarize')) {
-            emit({ type: 'done', response: finalResponse });
-        }
-        // Context management: increment turn count and update token count
-        if (this.contextManager) {
-            this.contextManager.incrementTurn();
-            await this.contextManager.updateTokenCount(messages);
+        finally {
+            // CRITICAL: Always preserve conversation history, even on ToolLoopError
+            // or MaxIterationsError. Without this, the agent loses all memory of the
+            // current run and the user's next message starts with no context.
+            if (newMessages.length > 0) {
+                this.conversationHistory.push(...newMessages);
+            }
+            // Context management: increment turn count and update token count
+            if (this.contextManager) {
+                this.contextManager.incrementTurn();
+                await this.contextManager.updateTokenCount(messages);
+            }
+            // Update internal state tracking
+            this._currentIteration = iterations;
         }
-        // Append new messages to conversation history (persists for next run)
-        this.conversationHistory.push(...newMessages);
-        // Update internal state tracking
-        this._currentIteration = iterations;
         // Note: token tracking would require provider-specific token counting
         // Build result with optional context stats
         const result = {

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { PerplexityProvider, createPerplexityProvider } from './providers/index.
 export type { PerplexityProviderConfig } from './providers/index.js';
 export { OpenRouterProvider, createOpenRouterProvider } from './providers/index.js';
 export type { OpenRouterProviderConfig } from './providers/index.js';
-export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, SuggestInput, SuggestToolOptions, } from './tools/index.js';
+export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, ToolFallbackHandler, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, SuggestInput, SuggestToolOptions, } from './tools/index.js';
 export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
 export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, suggestTool, createSuggestTool, builtinTools, allBuiltinTools, TOOL_NAMES, TOOL_SETS, } from './tools/index.js';
 export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, repairToolPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';

package/dist/tools/registry.d.ts

@@ -1,7 +1,8 @@
 /**
  * ToolRegistry - Manages available tools for an agent
  */
-import type { Tool, ToolDefinition, ToolRegistry as IToolRegistry, ToolExecutionResult, ToolExecutionContext } from './types.js';
+import type { Tool, ToolDefinition, ToolRegistry as IToolRegistry, ToolExecutionResult, ToolExecutionContext, ToolFallbackHandler } from './types.js';
+export type { ToolFallbackHandler } from './types.js';
 /**
  * Options for creating a DefaultToolRegistry
  */
@@ -15,6 +16,11 @@ export interface ToolRegistryOptions {
      * Per-tool timeout overrides (tool name -> timeout in ms)
      */
     toolTimeouts?: Record<string, number>;
+    /**
+     * Fallback handler for tools not found in the primary registry.
+     * Enables transparent routing to secondary registries (e.g., meta-tools).
+     */
+    fallbackHandler?: ToolFallbackHandler;
 }
 /**
  * Default implementation of ToolRegistry
@@ -23,7 +29,13 @@ export declare class DefaultToolRegistry implements IToolRegistry {
     private readonly tools;
     private readonly defaultTimeoutMs;
     private readonly toolTimeouts;
+    private fallbackHandler;
     constructor(options?: ToolRegistryOptions);
+    /**
+     * Set a fallback handler for tools not found in the primary registry.
+     * Enables transparent routing to secondary registries (e.g., meta-tools).
+     */
+    setFallbackHandler(handler: ToolFallbackHandler | null): void;
     /**
      * Register a tool
      */

package/dist/tools/registry.js

@@ -13,9 +13,18 @@ export class DefaultToolRegistry {
     tools = new Map();
     defaultTimeoutMs;
     toolTimeouts;
+    fallbackHandler;
     constructor(options) {
         this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
         this.toolTimeouts = options?.toolTimeouts ?? {};
+        this.fallbackHandler = options?.fallbackHandler ?? null;
+    }
+    /**
+     * Set a fallback handler for tools not found in the primary registry.
+     * Enables transparent routing to secondary registries (e.g., meta-tools).
+     */
+    setFallbackHandler(handler) {
+        this.fallbackHandler = handler;
     }
     /**
      * Register a tool
@@ -81,6 +90,14 @@ export class DefaultToolRegistry {
     async execute(name, input, contextOrTimeout, timeoutMs) {
         const tool = this.tools.get(name);
         if (!tool) {
+            // Try fallback handler (e.g., meta-tools registry)
+            if (this.fallbackHandler) {
+                const context = typeof contextOrTimeout === 'object' ? contextOrTimeout : undefined;
+                const fallbackResult = await this.fallbackHandler(name, input, context);
+                if (fallbackResult !== null) {
+                    return fallbackResult;
+                }
+            }
             return {
                 success: false,
                 error: `Tool not found: ${name}`,

package/dist/tools/types.d.ts

@@ -79,6 +79,16 @@ export interface Tool<T = object> {
      */
     silent?: boolean;
 }
+/**
+ * Fallback handler for tools not found in the primary registry.
+ * Used by meta-tools to transparently route calls to a secondary registry.
+ *
+ * @param name - Tool name that was not found
+ * @param input - Tool input parameters
+ * @param context - Optional execution context
+ * @returns Result if handled, or null to return the default "not found" error
+ */
+export type ToolFallbackHandler = (name: string, input: Record<string, unknown>, context?: ToolExecutionContext) => Promise<ToolExecutionResult | null>;
 /**
  * Tool registry for managing available tools
  */
@@ -102,4 +112,9 @@ export interface ToolRegistry {
      * @param context - Optional execution context for streaming
      */
     execute(name: string, input: Record<string, unknown>, context?: ToolExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * Set a fallback handler for tools not found in the primary registry.
+     * Enables transparent routing to secondary registries (e.g., meta-tools).
+     */
+    setFallbackHandler(handler: ToolFallbackHandler | null): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",