@claudetools/tools 0.8.2 → 0.8.4

package/dist/hooks/post-tool-use.js

@@ -0,0 +1,234 @@
+// =============================================================================
+// Post-Tool-Use Hook: Automatic Context Management
+// =============================================================================
+// This hook runs after each tool execution (Read, Edit, Write, Bash, etc.)
+// Updates session state with tool output size and triggers eviction if needed
+//
+// Trigger Points:
+// - estimated_fill > 0.60 → Standard eviction cycle
+// - estimated_fill > 0.70 → Emergency eviction
+//
+// =============================================================================
+import { mcpLogger } from '../logger.js';
+import { getSessionId } from '../helpers/engagement-tracker.js';
+import { estimateTokens } from '../context/usage-estimator.js';
+const sessions = new Map();
+// Default context limit for Claude Code (Sonnet 4.5)
+const DEFAULT_CONTEXT_LIMIT = 200000;
+// Eviction thresholds
+const STANDARD_EVICTION_THRESHOLD = 0.60; // 60%
+const EMERGENCY_EVICTION_THRESHOLD = 0.70; // 70%
+// =============================================================================
+// Session Store
+// =============================================================================
+class SessionStore {
+    /**
+     * Get or create session data
+     */
+    getSession(sessionId) {
+        let session = sessions.get(sessionId);
+        if (!session) {
+            session = {
+                session_id: sessionId,
+                tool_executions: 0,
+                estimated_tokens: 0,
+                context_limit: DEFAULT_CONTEXT_LIMIT,
+                estimated_fill: 0,
+                last_updated: new Date(),
+                tool_output_tokens: 0,
+            };
+            sessions.set(sessionId, session);
+        }
+        return session;
+    }
+    /**
+     * Update session with tool output tokens
+     */
+    updateSession(sessionId, outputTokens) {
+        const session = this.getSession(sessionId);
+        // Increment tool execution count
+        session.tool_executions += 1;
+        // Add output tokens to total
+        session.tool_output_tokens += outputTokens;
+        session.estimated_tokens += outputTokens;
+        // Update estimated fill
+        session.estimated_fill = session.estimated_tokens / session.context_limit;
+        // Update timestamp
+        session.last_updated = new Date();
+        sessions.set(sessionId, session);
+        return session;
+    }
+    /**
+     * Clear session (for cleanup)
+     */
+    clearSession(sessionId) {
+        sessions.delete(sessionId);
+    }
+    /**
+     * Get all sessions (for debugging)
+     */
+    getAllSessions() {
+        return Array.from(sessions.values());
+    }
+}
+const sessionStore = new SessionStore();
+// =============================================================================
+// Eviction Trigger Logic
+// =============================================================================
+class EvictionTriggerEngine {
+    /**
+     * Check if eviction should be triggered based on fill percentage
+     */
+    checkEvictionTrigger(session) {
+        const fill = session.estimated_fill;
+        if (fill > EMERGENCY_EVICTION_THRESHOLD) {
+            return {
+                triggered: true,
+                level: 'emergency',
+                estimated_fill: fill,
+                message: `EMERGENCY: Context fill at ${(fill * 100).toFixed(1)}% - triggering emergency eviction`,
+            };
+        }
+        if (fill > STANDARD_EVICTION_THRESHOLD) {
+            return {
+                triggered: true,
+                level: 'standard',
+                estimated_fill: fill,
+                message: `Context fill at ${(fill * 100).toFixed(1)}% - triggering standard eviction`,
+            };
+        }
+        return {
+            triggered: false,
+            level: 'none',
+            estimated_fill: fill,
+            message: `Context fill at ${(fill * 100).toFixed(1)}% - no eviction needed`,
+        };
+    }
+    /**
+     * Run standard eviction cycle
+     * NOTE: This is a placeholder - actual implementation would call into
+     * the context rotation/eviction system when it's built
+     */
+    async runStandardEviction(session) {
+        mcpLogger.info('EVICTION', `Running standard eviction for session ${session.session_id}`);
+        mcpLogger.debug('EVICTION', `Fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+        // TODO: Integrate with actual eviction engine
+        // This would call into packages/tools/src/context/rotation-engine.ts (when built)
+        // For now, just log the trigger
+        console.warn(`\n⚠️  [ClaudeTools] Context Rotation Triggered`);
+        console.warn(`    Fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+        console.warn(`    Action: Standard eviction cycle\n`);
+    }
+    /**
+     * Run emergency eviction cycle
+     * More aggressive eviction for critical situations
+     */
+    async runEmergencyEviction(session) {
+        mcpLogger.info('EVICTION', `Running EMERGENCY eviction for session ${session.session_id}`);
+        mcpLogger.debug('EVICTION', `Fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+        // TODO: Integrate with actual eviction engine
+        // Emergency mode would evict more aggressively
+        console.error(`\n🚨 [ClaudeTools] EMERGENCY Context Rotation`);
+        console.error(`    Fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+        console.error(`    Action: Emergency eviction - aggressive cleanup\n`);
+    }
+}
+const evictionEngine = new EvictionTriggerEngine();
+// =============================================================================
+// Post-Tool-Use Hook Handler
+// =============================================================================
+/**
+ * Handle PostToolUse hook event
+ * Updates session state with tool output and triggers eviction if needed
+ */
+export async function handlePostToolUseHook(input) {
+    try {
+        // Get session ID (from input or fallback to tracker)
+        const sessionId = input.session_id || getSessionId();
+        // CRITICAL: Prevent infinite loops
+        if (input.post_tool_use_active) {
+            mcpLogger.debug('HOOK', 'PostToolUse hook already active - skipping');
+            return;
+        }
+        // Only track tools that generate significant output
+        // Read, Edit, Write, Bash, etc. - not memory tools
+        if (!shouldTrackTool(input.tool_name)) {
+            mcpLogger.debug('HOOK', `Skipping tracking for tool: ${input.tool_name}`);
+            return;
+        }
+        // Estimate tokens from tool output
+        const outputTokens = input.tool_output ? estimateTokens(input.tool_output) : 0;
+        if (outputTokens === 0) {
+            mcpLogger.debug('HOOK', `No output tokens for ${input.tool_name} - skipping`);
+            return;
+        }
+        // Update session state
+        const session = sessionStore.updateSession(sessionId, outputTokens);
+        // Log tool execution
+        mcpLogger.info('HOOK', `PostToolUse: ${input.tool_name} (+${outputTokens} tokens)`);
+        mcpLogger.debug('HOOK', `Session: ${sessionId}`);
+        mcpLogger.debug('HOOK', `Total estimated: ${session.estimated_tokens} tokens`);
+        mcpLogger.debug('HOOK', `Fill: ${(session.estimated_fill * 100).toFixed(1)}%`);
+        // Check eviction trigger
+        const trigger = evictionEngine.checkEvictionTrigger(session);
+        if (trigger.triggered) {
+            mcpLogger.info('HOOK', trigger.message);
+            if (trigger.level === 'emergency') {
+                await evictionEngine.runEmergencyEviction(session);
+            }
+            else if (trigger.level === 'standard') {
+                await evictionEngine.runStandardEviction(session);
+            }
+        }
+        else {
+            mcpLogger.debug('HOOK', trigger.message);
+        }
+        // Output verbose status if significant
+        if (outputTokens > 1000 || trigger.triggered) {
+            outputToolOutputSummary(input.tool_name, outputTokens, session, trigger);
+        }
+    }
+    catch (error) {
+        // Don't fail the tool execution on hook errors
+        mcpLogger.error('HOOK', `Error in PostToolUse hook: ${error}`);
+    }
+}
+/**
+ * Determine if a tool should be tracked for context usage
+ * Only track tools that generate significant output (Read, Bash, etc.)
+ * Skip memory tools (they're tracked separately)
+ */
+function shouldTrackTool(toolName) {
+    // Tools that generate significant output
+    const trackedTools = [
+        'Read',
+        'Bash',
+        'Grep',
+        'Glob',
+        'WebFetch',
+        'WebSearch',
+        // Add other tools as needed
+    ];
+    return trackedTools.includes(toolName);
+}
+/**
+ * Output tool execution summary
+ * Shown when tool generates significant output or triggers eviction
+ */
+function outputToolOutputSummary(toolName, outputTokens, session, trigger) {
+    const fillPercentage = (session.estimated_fill * 100).toFixed(1);
+    const statusEmoji = trigger.triggered ? '⚠️' : '✓';
+    console.log(`\n${statusEmoji} Tool Output Tracking:`);
+    console.log(`  Tool: ${toolName}`);
+    console.log(`  Output: +${outputTokens.toLocaleString()} tokens`);
+    console.log(`  Total: ${session.estimated_tokens.toLocaleString()}/${session.context_limit.toLocaleString()} tokens (${fillPercentage}%)`);
+    console.log(`  Executions: ${session.tool_executions}`);
+    if (trigger.triggered) {
+        console.log(`  Eviction: ${trigger.level.toUpperCase()} triggered`);
+    }
+    console.log('');
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export { sessionStore, evictionEngine };

package/dist/hooks/stop-hook-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hooks/stop-hook-cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// =============================================================================
+// Stop Hook CLI Entry Point
+// =============================================================================
+// Called by Claude Code when Stop event occurs
+// Reads hook input from stdin, processes it, and outputs to stdout/stderr
+import { handleStopHook } from './stop.js';
+async function main() {
+    try {
+        // Read JSON input from stdin
+        let inputData = '';
+        // Set up stdin reading
+        process.stdin.setEncoding('utf8');
+        for await (const chunk of process.stdin) {
+            inputData += chunk;
+        }
+        // Parse hook input
+        const hookInput = JSON.parse(inputData);
+        // Validate hook event
+        if (hookInput.hook_event_name !== 'Stop') {
+            console.error(`Error: Expected Stop event, got ${hookInput.hook_event_name}`);
+            process.exit(1);
+        }
+        // Process the hook
+        await handleStopHook(hookInput);
+        // Success - exit code 0
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error processing Stop hook:', error);
+        process.exit(1);
+    }
+}
+main();

package/dist/hooks/stop.d.ts

@@ -0,0 +1,64 @@
+import { getSessionStats } from '../helpers/session-validation.js';
+interface StopHookInput {
+    session_id?: string;
+    hook_event_name: 'Stop';
+    stop_hook_reason: 'end_turn' | 'max_turns' | 'error';
+    stop_hook_active?: boolean;
+    last_assistant_message?: string;
+}
+interface ContextHealth {
+    estimated_fill: number;
+    warning_level: 'healthy' | 'caution' | 'critical';
+    message: string;
+}
+interface SessionData {
+    session_id: string;
+    exchanges: number;
+    estimated_tokens: number;
+    context_limit: number;
+    estimated_fill: number;
+    last_updated: Date;
+    engagement_score: number;
+}
+declare class UsageEstimator {
+    /**
+     * Estimate tokens used in current session
+     * Uses session statistics to calculate rough estimate
+     */
+    getEstimatedTokens(sessionStats: ReturnType<typeof getSessionStats>): number;
+    /**
+     * Calculate estimated fill percentage
+     */
+    getEstimatedFill(contextLimit: number, estimatedTokens: number): number;
+    /**
+     * Determine health status based on fill percentage
+     */
+    getHealthStatus(fill: number): ContextHealth;
+}
+declare const usageEstimator: UsageEstimator;
+declare class SessionStore {
+    /**
+     * Get or create session data
+     */
+    getSession(sessionId: string): SessionData;
+    /**
+     * Update session with latest stats
+     */
+    updateSession(sessionId: string, stats: ReturnType<typeof getSessionStats>): SessionData;
+    /**
+     * Get all sessions (for debugging)
+     */
+    getAllSessions(): SessionData[];
+    /**
+     * Clear session (for cleanup)
+     */
+    clearSession(sessionId: string): void;
+}
+declare const sessionStore: SessionStore;
+/**
+ * Handle Stop hook event
+ * Updates session state and logs context health warnings
+ */
+export declare function handleStopHook(input: StopHookInput): Promise<void>;
+export { sessionStore, usageEstimator };
+export type { StopHookInput, SessionData, ContextHealth };

package/dist/hooks/stop.js

@@ -0,0 +1,192 @@
+// =============================================================================
+// Stop Hook: Usage Dashboard and Context Health Monitoring
+// =============================================================================
+// This hook runs when the main agent finishes responding (Stop event)
+// Updates session state with latest exchange data and warns if context fill > 60%
+import { mcpLogger } from '../logger.js';
+import { getSessionId } from '../helpers/engagement-tracker.js';
+import { getSessionStats } from '../helpers/session-validation.js';
+const sessions = new Map();
+// Default context limit for Claude Code (Sonnet 4.5)
+const DEFAULT_CONTEXT_LIMIT = 200000;
+// Token estimation heuristic (rough estimate)
+// Average tokens per exchange based on typical usage patterns
+const AVG_TOKENS_PER_EXCHANGE = 2000; // Conservative estimate
+// =============================================================================
+// Usage Estimator
+// =============================================================================
+class UsageEstimator {
+    /**
+     * Estimate tokens used in current session
+     * Uses session statistics to calculate rough estimate
+     */
+    getEstimatedTokens(sessionStats) {
+        // Base estimation from tool calls
+        const toolCallTokens = sessionStats.totalCalls * 200; // ~200 tokens per tool call
+        // Add engagement-based estimation
+        const engagementTokens = sessionStats.engagement.score * 100; // More engagement = more context
+        // Add base conversation overhead
+        const baseOverhead = 5000; // Initial prompt + system context
+        return baseOverhead + toolCallTokens + engagementTokens;
+    }
+    /**
+     * Calculate estimated fill percentage
+     */
+    getEstimatedFill(contextLimit, estimatedTokens) {
+        return estimatedTokens / contextLimit;
+    }
+    /**
+     * Determine health status based on fill percentage
+     */
+    getHealthStatus(fill) {
+        if (fill < 0.6) {
+            return {
+                estimated_fill: fill,
+                warning_level: 'healthy',
+                message: 'Context usage is healthy',
+            };
+        }
+        else if (fill < 0.8) {
+            return {
+                estimated_fill: fill,
+                warning_level: 'caution',
+                message: 'Context fill approaching limits - consider eviction strategies',
+            };
+        }
+        else {
+            return {
+                estimated_fill: fill,
+                warning_level: 'critical',
+                message: 'CRITICAL: Context fill very high - eviction strongly recommended',
+            };
+        }
+    }
+}
+const usageEstimator = new UsageEstimator();
+// =============================================================================
+// Session Store
+// =============================================================================
+class SessionStore {
+    /**
+     * Get or create session data
+     */
+    getSession(sessionId) {
+        let session = sessions.get(sessionId);
+        if (!session) {
+            session = {
+                session_id: sessionId,
+                exchanges: 0,
+                estimated_tokens: 0,
+                context_limit: DEFAULT_CONTEXT_LIMIT,
+                estimated_fill: 0,
+                last_updated: new Date(),
+                engagement_score: 0,
+            };
+            sessions.set(sessionId, session);
+        }
+        return session;
+    }
+    /**
+     * Update session with latest stats
+     */
+    updateSession(sessionId, stats) {
+        const session = this.getSession(sessionId);
+        // Update exchange count (each Stop = 1 exchange)
+        session.exchanges += 1;
+        // Update estimated tokens
+        session.estimated_tokens = usageEstimator.getEstimatedTokens(stats);
+        // Update estimated fill
+        session.estimated_fill = usageEstimator.getEstimatedFill(session.context_limit, session.estimated_tokens);
+        // Update engagement score
+        session.engagement_score = stats.engagement.score;
+        // Update timestamp
+        session.last_updated = new Date();
+        sessions.set(sessionId, session);
+        return session;
+    }
+    /**
+     * Get all sessions (for debugging)
+     */
+    getAllSessions() {
+        return Array.from(sessions.values());
+    }
+    /**
+     * Clear session (for cleanup)
+     */
+    clearSession(sessionId) {
+        sessions.delete(sessionId);
+    }
+}
+const sessionStore = new SessionStore();
+// =============================================================================
+// Stop Hook Handler
+// =============================================================================
+/**
+ * Handle Stop hook event
+ * Updates session state and logs context health warnings
+ */
+export async function handleStopHook(input) {
+    try {
+        // Get session ID (from input or fallback to tracker)
+        const sessionId = input.session_id || getSessionId();
+        // CRITICAL: Prevent infinite loops
+        if (input.stop_hook_active) {
+            mcpLogger.debug('HOOK', 'Stop hook already active - allowing stop');
+            return;
+        }
+        // Get current session statistics
+        const stats = getSessionStats();
+        // Update session state
+        const session = sessionStore.updateSession(sessionId, stats);
+        // Get health status
+        const health = usageEstimator.getHealthStatus(session.estimated_fill);
+        // Log session statistics
+        mcpLogger.info('HOOK', `Stop event processed - Session: ${sessionId}`);
+        mcpLogger.debug('HOOK', `Exchanges: ${session.exchanges}`);
+        mcpLogger.debug('HOOK', `Estimated tokens: ${session.estimated_tokens}`);
+        mcpLogger.debug('HOOK', `Engagement score: ${session.engagement_score}/100`);
+        // Warn if approaching limits
+        if (health.warning_level === 'caution') {
+            console.warn(`\n⚠️  [ClaudeTools] Context fill at ${(health.estimated_fill * 100).toFixed(1)}%`);
+            console.warn(`    ${health.message}\n`);
+        }
+        else if (health.warning_level === 'critical') {
+            console.error(`\n🚨 [ClaudeTools] CRITICAL: Context fill at ${(health.estimated_fill * 100).toFixed(1)}%`);
+            console.error(`    ${health.message}\n`);
+        }
+        else {
+            mcpLogger.debug('HOOK', `Context health: ${health.warning_level} (${(health.estimated_fill * 100).toFixed(1)}%)`);
+        }
+        // Output context health status (for verbose mode)
+        outputContextHealth(session, health);
+    }
+    catch (error) {
+        // Don't fail the stop event on errors
+        mcpLogger.error('HOOK', `Error in Stop hook: ${error}`);
+    }
+}
+/**
+ * Output context health status
+ * Shown in verbose mode via stdout
+ */
+function outputContextHealth(session, health) {
+    const fillPercentage = (health.estimated_fill * 100).toFixed(1);
+    const statusEmoji = health.warning_level === 'healthy'
+        ? '✓'
+        : health.warning_level === 'caution'
+            ? '⚠'
+            : '🚨';
+    console.log(`\n${statusEmoji} Context Health Status:`);
+    console.log(`  Fill: ${fillPercentage}% (${session.estimated_tokens.toLocaleString()}/${session.context_limit.toLocaleString()} tokens)`);
+    console.log(`  Exchanges: ${session.exchanges}`);
+    console.log(`  Engagement: ${session.engagement_score}/100`);
+    console.log(`  Status: ${health.warning_level.toUpperCase()}`);
+    if (health.warning_level !== 'healthy') {
+        console.log(`  Message: ${health.message}`);
+    }
+    console.log('');
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export { sessionStore, usageEstimator };

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export type { ExpertWorker } from './helpers/workers.js';
 export type { Task, TaskContext, DispatchableTask } from './helpers/tasks.js';
+export type { DeduplicationTracker } from './context/index.js';
 export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
 export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
 export { injectContext } from './helpers/api-client.js';
+export { recordToolCall, getToolCallWarnings, getSessionStats, clearSessionState, recordContextReference, calculateEngagementScore, getEngagementStats } from './helpers/session-validation.js';
+export { createDeduplicationTracker, InMemoryDeduplicationTracker } from './context/index.js';
 export declare function startServer(): Promise<void>;

package/dist/index.js

@@ -15,6 +15,8 @@ import { registerPromptHandlers } from './prompts.js';
 export { EXPERT_WORKERS, matchTaskToWorker } from './helpers/workers.js';
 export { parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask } from './helpers/tasks.js';
 export { injectContext } from './helpers/api-client.js';
+export { recordToolCall, getToolCallWarnings, getSessionStats, clearSessionState, recordContextReference, calculateEngagementScore, getEngagementStats } from './helpers/session-validation.js';
+export { createDeduplicationTracker, InMemoryDeduplicationTracker } from './context/index.js';
 // =============================================================================
 // Server Initialization
 // =============================================================================

package/dist/logger.d.ts

@@ -1,4 +1,4 @@
-export type LogCategory = 'TOOL' | 'API' | 'MEMORY' | 'SEARCH' | 'INJECT' | 'EXTRACT' | 'STORE' | 'QUERY' | 'IMPACT' | 'PATTERN' | 'CONFIG' | 'REGISTRATION' | 'ERROR';
+export type LogCategory = 'TOOL' | 'API' | 'MEMORY' | 'SEARCH' | 'INJECT' | 'EXTRACT' | 'STORE' | 'QUERY' | 'IMPACT' | 'PATTERN' | 'CONFIG' | 'REGISTRATION' | 'HOOK' | 'ERROR' | 'SESSION_HELPER' | 'EVICTION' | 'CONTEXT';
 declare class MCPLogger {
     private logFile;
     private logDir;

package/dist/logger.js

@@ -19,7 +19,11 @@ const CATEGORY_ICONS = {
     PATTERN: '🔬',
     CONFIG: '⚙️',
     REGISTRATION: '📝',
+    HOOK: '🪝',
     ERROR: '❌',
+    SESSION_HELPER: '📋',
+    EVICTION: '🗑️',
+    CONTEXT: '📦',
 };
 const LEVEL_ICONS = {
     DEBUG: '🔹',

package/dist/resources.js

@@ -5,6 +5,7 @@ import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcon
 import { getSummary, getEntities, getContext } from './helpers/api-client.js';
 import { formatContextForClaude } from './helpers/formatter.js';
 import { getDefaultProjectId } from './helpers/config.js';
+import { recordContextReference } from './helpers/session-validation.js';
 export function registerResourceHandlers(server) {
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
         resources: [
@@ -59,6 +60,8 @@ export function registerResourceHandlers(server) {
             }
             if (uri === 'memory://context') {
                 const context = await getContext(projectId);
+                // Track context reference for engagement scoring (+20 points)
+                recordContextReference(projectId);
                 return {
                     contents: [
                         {