@claudetools/tools 0.8.2 → 0.8.3

package/dist/helpers/session-validation.js

@@ -0,0 +1,221 @@
+// =============================================================================
+// Session-level Tool Call Validation
+// =============================================================================
+// Tracks tool call sequences within a session to enforce best practices:
+// - memory_search before task_start
+// - codebase_map before code modifications
+// - No code in task descriptions (enforced via validateTaskDescription)
+import { mcpLogger } from '../logger.js';
+import { trackEngagementEvent, getSessionId } from './engagement-tracker.js';
+const sessionState = {
+    toolCalls: [],
+    taskStarts: new Set(),
+    memorySearches: new Set(),
+    codebaseMapCalled: false,
+    engagement: {
+        searchCount: 0,
+        detailCount: 0,
+        injectCount: 0,
+        storeFactCount: 0,
+        contextReferencedCount: 0,
+    },
+};
+/**
+ * Record a tool call in the session
+ */
+export function recordToolCall(name, args) {
+    sessionState.toolCalls.push({
+        name,
+        timestamp: Date.now(),
+        args,
+    });
+    // Track specific tool types
+    if (name === 'task_start' && args?.task_id) {
+        sessionState.taskStarts.add(args.task_id);
+    }
+    if (name === 'memory_search' && args?.query) {
+        sessionState.memorySearches.add(args.query);
+    }
+    if (name === 'codebase_map') {
+        sessionState.codebaseMapCalled = true;
+    }
+    // Track engagement and persist to API
+    const projectId = args?.project_id;
+    let eventType;
+    switch (name) {
+        case 'memory_search':
+            sessionState.engagement.searchCount++;
+            eventType = 'search';
+            break;
+        case 'memory_detail':
+            sessionState.engagement.detailCount++;
+            eventType = 'detail';
+            break;
+        case 'memory_inject':
+            sessionState.engagement.injectCount++;
+            eventType = 'inject';
+            break;
+        case 'memory_store_fact':
+            sessionState.engagement.storeFactCount++;
+            eventType = 'store_fact';
+            break;
+    }
+    // Track to API if this is a memory tool
+    if (eventType && projectId) {
+        trackEngagementEvent(getSessionId(), projectId, eventType).catch(() => {
+            // Silently fail - don't block the tool call
+        });
+    }
+    mcpLogger.debug('TOOL', `Recorded tool call: ${name}`);
+}
+/**
+ * Validate that memory_search was called before task_start
+ * Returns validation result with warnings if violated
+ */
+export function validateTaskStartSequence(taskId) {
+    const warnings = [];
+    // Check if any memory_search happened in this session
+    if (sessionState.memorySearches.size === 0) {
+        warnings.push('BEST PRACTICE: Call memory_search() before task_start() to recall relevant context and past decisions.');
+    }
+    // Check recent tool calls (last 10 calls)
+    const recentCalls = sessionState.toolCalls.slice(-10).map(c => c.name);
+    const hasRecentMemorySearch = recentCalls.includes('memory_search');
+    if (!hasRecentMemorySearch && sessionState.memorySearches.size > 0) {
+        warnings.push('RECOMMENDATION: Consider calling memory_search() to check for updated context since your last search.');
+    }
+    return {
+        valid: warnings.length === 0,
+        warnings,
+    };
+}
+/**
+ * Validate that codebase_map was called before code modification tools
+ * Code modification tools: codedna_generate_*, or any task involving file changes
+ */
+export function validateCodebaseMapSequence() {
+    const warnings = [];
+    if (!sessionState.codebaseMapCalled) {
+        warnings.push('BEST PRACTICE: Call codebase_map() before making code changes to understand project structure and prevent conflicts.');
+    }
+    return {
+        valid: warnings.length === 0,
+        warnings,
+    };
+}
+/**
+ * Check if a tool name indicates code modification
+ */
+export function isCodeModificationTool(toolName) {
+    const codeTools = [
+        'codedna_generate_api',
+        'codedna_generate_frontend',
+        'codedna_generate_component',
+        'task_start', // Tasks often involve code changes
+    ];
+    return codeTools.includes(toolName);
+}
+/**
+ * Record when auto-injected context is used
+ * This tracks the +20 point event when context is automatically provided
+ */
+export function recordContextReference(projectId) {
+    sessionState.engagement.contextReferencedCount++;
+    // Track to API if project ID is available
+    if (projectId) {
+        trackEngagementEvent(getSessionId(), projectId, 'context_referenced').catch(() => {
+            // Silently fail - don't block the resource read
+        });
+    }
+    mcpLogger.debug('TOOL', 'Recorded context reference (auto-inject)');
+}
+/**
+ * Calculate engagement score (0-100)
+ * - memory_search: +30
+ * - memory_detail: +20
+ * - memory_inject: +20
+ * - memory_store_fact: +10
+ * - context_referenced: +20
+ */
+export function calculateEngagementScore() {
+    const { searchCount, detailCount, injectCount, storeFactCount, contextReferencedCount } = sessionState.engagement;
+    const rawScore = searchCount * 30 +
+        detailCount * 20 +
+        injectCount * 20 +
+        storeFactCount * 10 +
+        contextReferencedCount * 20;
+    // Cap at 100
+    return Math.min(rawScore, 100);
+}
+/**
+ * Get engagement statistics
+ */
+export function getEngagementStats() {
+    const { searchCount, detailCount, injectCount, storeFactCount, contextReferencedCount } = sessionState.engagement;
+    return {
+        score: calculateEngagementScore(),
+        breakdown: {
+            searchCount,
+            searchPoints: searchCount * 30,
+            detailCount,
+            detailPoints: detailCount * 20,
+            injectCount,
+            injectPoints: injectCount * 20,
+            storeFactCount,
+            storeFactPoints: storeFactCount * 10,
+            contextReferencedCount,
+            contextReferencedPoints: contextReferencedCount * 20,
+        },
+    };
+}
+/**
+ * Get session statistics for debugging
+ */
+export function getSessionStats() {
+    return {
+        totalCalls: sessionState.toolCalls.length,
+        uniqueTaskStarts: sessionState.taskStarts.size,
+        uniqueSearches: sessionState.memorySearches.size,
+        codebaseMapCalled: sessionState.codebaseMapCalled,
+        recentCalls: sessionState.toolCalls.slice(-10).map(c => c.name),
+        engagement: getEngagementStats(),
+    };
+}
+/**
+ * Clear session state (for testing or manual reset)
+ */
+export function clearSessionState() {
+    sessionState.toolCalls = [];
+    sessionState.taskStarts.clear();
+    sessionState.memorySearches.clear();
+    sessionState.codebaseMapCalled = false;
+    sessionState.engagement = {
+        searchCount: 0,
+        detailCount: 0,
+        injectCount: 0,
+        storeFactCount: 0,
+        contextReferencedCount: 0,
+    };
+    mcpLogger.debug('TOOL', 'Session state cleared');
+}
+/**
+ * Get formatted warnings for tool execution
+ * Returns null if no warnings
+ */
+export function getToolCallWarnings(toolName, args) {
+    const warnings = [];
+    // Validate task_start sequence
+    if (toolName === 'task_start' && args?.task_id) {
+        const validation = validateTaskStartSequence(args.task_id);
+        warnings.push(...validation.warnings);
+    }
+    // Validate codebase_map before code changes
+    if (isCodeModificationTool(toolName)) {
+        const validation = validateCodebaseMapSequence();
+        warnings.push(...validation.warnings);
+    }
+    if (warnings.length === 0) {
+        return null;
+    }
+    return `\n⚠️  WORKFLOW RECOMMENDATIONS:\n${warnings.map(w => `  - ${w}`).join('\n')}\n`;
+}

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export type { Task, TaskContext, DispatchableTask } from './helpers/tasks.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 declare function startServer(): Promise<void>;

package/dist/index.js

@@ -15,6 +15,7 @@ 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';
 // =============================================================================
 // Server Initialization
 // =============================================================================

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: [
                         {

package/dist/templates/claude-md.d.ts

@@ -5,7 +5,7 @@ export declare const PROJECT_SECTION_END = "<!-- CLAUDETOOLS:PROJECT:END -->";
 /**
  * Global CLAUDE.md content - added to ~/.claude/CLAUDE.md
  */
-export declare const GLOBAL_TEMPLATE = "\n<!-- CLAUDETOOLS:START -->\n# ClaudeTools Memory System\n\nYou have access to a persistent memory system via the `claudetools_memory` MCP server. Use it to remember context across sessions.\n\n## Memory Tools\n\n### Searching Memory\n```\nmemory_search(query: \"authentication patterns\")\n```\nSearch for relevant facts, entities, and past context. Use this when:\n- Starting work on a feature to recall past decisions\n- Looking for patterns or conventions used before\n- Finding related code or architectural context\n\n### Storing Facts\n```\nmemory_store_fact(\n  entity1: \"UserService\",\n  relationship: \"USES\",\n  entity2: \"bcrypt\",\n  context: \"Password hashing uses bcrypt with 12 rounds\"\n)\n```\nStore important facts as relationships between entities. Use for:\n- Architectural decisions\n- Code patterns and conventions\n- Dependencies and relationships\n- User preferences learned during conversation\n\n### Context Injection\nContext is automatically injected at the start of each session based on the current project. Check `~/.claudetools/session-context.md` for project-specific context.\n\n## Task Management\n\n### Creating Work Plans with Auto-Dispatch\n```\ntask_plan(\n  goal: \"Add user authentication\",\n  epic_title: \"User Auth System\",\n  tasks: [...]\n)\n```\nBreak down complex work into tracked tasks. **Tasks are automatically set to `ready` status.**\n\nAfter `task_plan` completes, you will receive Task tool invocations to spawn parallel agents.\n**Execute ALL Task tool calls in a SINGLE message** to enable parallel execution.\n\n### Parallel Agent Workflow\n1. User describes work needed\n2. Call `task_plan_draft` to present the plan\n3. User says \"go\" to approve\n4. Call `task_plan` - tasks created in `ready` status\n5. Execute the provided Task tool calls in ONE message\n6. Agents work in parallel, each calling `task_complete` when done\n\n### Manual Task Start (Sequential)\n```\ntask_start(task_id: \"task_xxx\")\n```\nClaim a task before working on it. Use for sequential execution.\n\n### Completing Tasks\n```\ntask_complete(task_id: \"task_xxx\", summary: \"Implemented JWT auth with refresh tokens\")\n```\nMark tasks done with a summary of work completed. **Always call this when a task is finished.**\n\n## Codebase Intelligence\n\n### Start with codebase_map() - ALWAYS\n```\ncodebase_map()  # FIRST TOOL when exploring unfamiliar code\n```\n**When to use:** Starting a new task, exploring unfamiliar code, understanding project structure, finding entry points.\n\nThe map shows:\n- Project structure and key directories\n- Entry points and their exports\n- Framework detection (React, Express, etc.)\n- Key symbols and their locations\n\n**Use codebase_map BEFORE using Grep/Glob** - it gives you the lay of the land so you know where to look.\n\n### Then use targeted tools\n```\ncodebase_find(\"UserService\")  # Find specific symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\nanalyze_impact(\"validateToken\")  # See what changing a function affects\n```\n\n## CodeDNA: Generate Code, Save 99% Tokens\n\n**When creating APIs/CRUD operations:** Call `codedna_generate_api` instead of writing code manually.\n\n```\ncodedna_generate_api({\n  spec: \"User(email:string:unique, password:string:hashed, age:integer:min(18))\",\n  framework: \"express\",\n  options: { auth: true, validation: true, tests: true }\n})\n```\n\n**Generates 6 production files** (models, controllers, routes, validators, auth, tests) in ~5 seconds.\n**Saves:** 30,000 tokens \u2192 200 tokens (99% reduction)\n\n## Best Practices\n\n1. **Search before implementing** - Check memory for existing patterns\n2. **Store decisions** - Save architectural choices as facts\n3. **Use task tracking** - Break complex work into tasks\n4. **Use CodeDNA for APIs** - Generate instead of write (99% token savings)\n<!-- CLAUDETOOLS:END -->\n";
+export declare const GLOBAL_TEMPLATE = "\n<!-- CLAUDETOOLS:START -->\n# ClaudeTools Memory System\n\nYou have access to a persistent memory system. **Context is AUTO-INJECTED via hooks** - you rarely need to call memory tools explicitly.\n\n## \u26A0\uFE0F IMPORTANT: Hooks vs MCP Tools\n\n**AUTOMATIC (via hooks - zero context cost):**\n- Context injection \u2192 `user-prompt-submit` hook runs on every message\n- Fact extraction \u2192 `post-tool-use` hook extracts from your work\n- Session context \u2192 `session-start` hook provides initial context\n\n**EXPLICIT (MCP tools - costs context):**\n- `memory_store_fact` \u2192 Store a specific fact you learned\n- `task_plan` / `task_start` / `task_complete` \u2192 Task management\n\n**DO NOT CALL these tools routinely (context already injected):**\n- `memory_search` - only if you need DIFFERENT search params\n- `memory_inject` - only if you need to refresh for a different query\n- `memory_get_context` - only for debugging\n- `memory_index` - only for debugging\n\n## Storing Facts (DO use this)\n```\nmemory_store_fact(\n  entity1: \"UserService\",\n  relationship: \"USES\",\n  entity2: \"bcrypt\",\n  context: \"Password hashing uses bcrypt with 12 rounds\"\n)\n```\nStore important facts when you learn something concrete. The `post-tool-use` hook also extracts facts automatically.\n\n## Task Management\n\n### Creating Work Plans with Auto-Dispatch\n```\ntask_plan(\n  goal: \"Add user authentication\",\n  epic_title: \"User Auth System\",\n  tasks: [...]\n)\n```\nBreak down complex work into tracked tasks. **Tasks are automatically set to `ready` status.**\n\nAfter `task_plan` completes, you will receive Task tool invocations to spawn parallel agents.\n**Execute ALL Task tool calls in a SINGLE message** to enable parallel execution.\n\n### Parallel Agent Workflow\n1. User describes work needed\n2. Call `task_plan_draft` to present the plan\n3. User says \"go\" to approve\n4. Call `task_plan` - tasks created in `ready` status\n5. Execute the provided Task tool calls in ONE message\n6. Agents work in parallel, each calling `task_complete` when done\n\n### Manual Task Start (Sequential)\n```\ntask_start(task_id: \"task_xxx\")\n```\nClaim a task before working on it. Use for sequential execution.\n\n### Completing Tasks\n```\ntask_complete(task_id: \"task_xxx\", summary: \"Implemented JWT auth with refresh tokens\")\n```\nMark tasks done with a summary of work completed. **Always call this when a task is finished.**\n\n## Codebase Intelligence\n\n### Start with codebase_map() - ALWAYS\n```\ncodebase_map()  # FIRST TOOL when exploring unfamiliar code\n```\n**When to use:** Starting a new task, exploring unfamiliar code, understanding project structure, finding entry points.\n\nThe map shows:\n- Project structure and key directories\n- Entry points and their exports\n- Framework detection (React, Express, etc.)\n- Key symbols and their locations\n\n**Use codebase_map BEFORE using Grep/Glob** - it gives you the lay of the land so you know where to look.\n\n### Then use targeted tools\n```\ncodebase_find(\"UserService\")  # Find specific symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\nanalyze_impact(\"validateToken\")  # See what changing a function affects\n```\n\n## CodeDNA: Generate Code, Save 99% Tokens\n\n**When creating APIs/CRUD operations:** Call `codedna_generate_api` instead of writing code manually.\n\n```\ncodedna_generate_api({\n  spec: \"User(email:string:unique, password:string:hashed, age:integer:min(18))\",\n  framework: \"express\",\n  options: { auth: true, validation: true, tests: true }\n})\n```\n\n**Generates 6 production files** (models, controllers, routes, validators, auth, tests) in ~5 seconds.\n**Saves:** 30,000 tokens \u2192 200 tokens (99% reduction)\n\n## Best Practices\n\n1. **Trust auto-injection** - Context is injected automatically, don't call memory_search\n2. **Store decisions** - Use `memory_store_fact` for architectural choices\n3. **Use task tracking** - Break complex work into tasks\n4. **Use CodeDNA for APIs** - Generate instead of write (99% token savings)\n5. **Minimize tool calls** - Every MCP call costs context tokens\n<!-- CLAUDETOOLS:END -->\n";
 /**
  * Project-level CLAUDE.md content - added to .claude/CLAUDE.md
  */

package/dist/templates/claude-md.js

@@ -14,20 +14,26 @@ export const GLOBAL_TEMPLATE = `
 ${SECTION_START}
 # ClaudeTools Memory System
 
-You have access to a persistent memory system via the \`claudetools_memory\` MCP server. Use it to remember context across sessions.
+You have access to a persistent memory system. **Context is AUTO-INJECTED via hooks** - you rarely need to call memory tools explicitly.
 
-## Memory Tools
+## ⚠️ IMPORTANT: Hooks vs MCP Tools
 
-### Searching Memory
-\`\`\`
-memory_search(query: "authentication patterns")
-\`\`\`
-Search for relevant facts, entities, and past context. Use this when:
-- Starting work on a feature to recall past decisions
-- Looking for patterns or conventions used before
-- Finding related code or architectural context
+**AUTOMATIC (via hooks - zero context cost):**
+- Context injection → \`user-prompt-submit\` hook runs on every message
+- Fact extraction → \`post-tool-use\` hook extracts from your work
+- Session context → \`session-start\` hook provides initial context
+
+**EXPLICIT (MCP tools - costs context):**
+- \`memory_store_fact\` → Store a specific fact you learned
+- \`task_plan\` / \`task_start\` / \`task_complete\` → Task management
 
-### Storing Facts
+**DO NOT CALL these tools routinely (context already injected):**
+- \`memory_search\` - only if you need DIFFERENT search params
+- \`memory_inject\` - only if you need to refresh for a different query
+- \`memory_get_context\` - only for debugging
+- \`memory_index\` - only for debugging
+
+## Storing Facts (DO use this)
 \`\`\`
 memory_store_fact(
   entity1: "UserService",
@@ -36,14 +42,7 @@ memory_store_fact(
   context: "Password hashing uses bcrypt with 12 rounds"
 )
 \`\`\`
-Store important facts as relationships between entities. Use for:
-- Architectural decisions
-- Code patterns and conventions
-- Dependencies and relationships
-- User preferences learned during conversation
-
-### Context Injection
-Context is automatically injected at the start of each session based on the current project. Check \`~/.claudetools/session-context.md\` for project-specific context.
+Store important facts when you learn something concrete. The \`post-tool-use\` hook also extracts facts automatically.
 
 ## Task Management
 
@@ -120,10 +119,11 @@ codedna_generate_api({
 
 ## Best Practices
 
-1. **Search before implementing** - Check memory for existing patterns
-2. **Store decisions** - Save architectural choices as facts
+1. **Trust auto-injection** - Context is injected automatically, don't call memory_search
+2. **Store decisions** - Use \`memory_store_fact\` for architectural choices
 3. **Use task tracking** - Break complex work into tasks
 4. **Use CodeDNA for APIs** - Generate instead of write (99% token savings)
+5. **Minimize tool calls** - Every MCP call costs context tokens
 ${SECTION_END}
 `;
 /**
@@ -134,31 +134,19 @@ export function getProjectTemplate(projectId, projectName) {
 ${SECTION_START}
 # Project: ${projectName}
 
-This project is registered with ClaudeTools Memory.
-
 **Project ID:** \`${projectId}\`
 
-## Project Memory
-
-Use memory tools to search and store project-specific context:
+Context is **auto-injected** via hooks. Only use \`memory_store_fact\` to store new facts:
 
 \`\`\`
-# Search this project's memory
-memory_search(query: "your search", project_id: "${projectId}")
-
-# Store a project fact
 memory_store_fact(
   entity1: "ComponentName",
   relationship: "IMPLEMENTS",
   entity2: "PatternName",
-  context: "Description of the relationship",
+  context: "Why this decision was made",
   project_id: "${projectId}"
 )
 \`\`\`
-
-## Session Context
-
-Project-specific context is injected automatically. Check \`~/.claudetools/session-context.md\` for current context.
 ${SECTION_END}
 `;
 }