@claudetools/tools 0.8.3 → 0.8.5

package/dist/setup.js

@@ -747,11 +747,22 @@ fi
 # Escape the query for JSON (handle quotes and newlines)
 ESCAPED_QUERY=$(echo "$USER_QUERY" | head -c 500 | jq -Rs '.')
 
+# Get session state for query-aware budget allocation (if SESSION_ID available)
+SESSION_STATE_JSON='{}'
+if [ -n "$SESSION_ID" ]; then
+  # Try to get session state from SessionStore
+  TOOLS_DIR="$HOME/.claudetools/node_modules/@claudetools/tools"
+  if [ -f "$TOOLS_DIR/dist/context/session-helper.js" ]; then
+    SESSION_STATE_JSON=$(node "$TOOLS_DIR/dist/context/session-helper.js" "$SESSION_ID" 2>/dev/null || echo '{}')
+  fi
+fi
+
 # Inject context with semantic search based on the user's prompt
+# Include session_state if available for dynamic budget calculation
 RESULT=$(curl -s --max-time 2 -X POST "$API_URL/api/v1/context/inject" \\
   -H "Authorization: Bearer $API_KEY" \\
   -H "Content-Type: application/json" \\
-  -d "{\\"query\\": $ESCAPED_QUERY, \\"project_id\\": \\"$PROJECT_ID\\", \\"cwd\\": \\"$CWD\\"}" \\
+  -d "{\\"query\\": $ESCAPED_QUERY, \\"project_id\\": \\"$PROJECT_ID\\", \\"cwd\\": \\"$CWD\\", \\"session_state\\": $SESSION_STATE_JSON}" \\
   2>/dev/null)
 
 # Output context as additionalContext JSON for Claude Code
@@ -1330,6 +1341,170 @@ export async function runUninstall() {
     console.log('\n' + chalk.green('ClaudeTools removed from Claude Code.'));
     console.log(chalk.dim('Your ~/.claudetools/ config and data are preserved.\n'));
 }
+async function runOnboarding(apiUrl, apiKey, projectId, projectName) {
+    header('Project Onboarding');
+    info('Answer a few questions to help Claude understand your project better.');
+    console.log(chalk.dim('This creates memory facts that provide context in future sessions.\n'));
+    const spinner = ora('Starting onboarding session...').start();
+    try {
+        // Start onboarding session
+        const startResponse = await fetch(`${apiUrl}/api/v1/onboarding/start`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ project_id: projectId }),
+        });
+        if (!startResponse.ok) {
+            spinner.fail('Could not start onboarding');
+            const errorData = await startResponse.json().catch(() => ({}));
+            error(errorData.error || `HTTP ${startResponse.status}`);
+            return;
+        }
+        const startData = await startResponse.json();
+        if (!startData.success || !startData.data) {
+            spinner.fail('Failed to start onboarding');
+            return;
+        }
+        spinner.succeed('Onboarding session started');
+        const sessionId = startData.data.session_id;
+        let questions = startData.data.questions;
+        let state = startData.data.state;
+        let questionCount = 0;
+        const maxQuestions = 8; // Limit to avoid fatigue
+        // Interactive question loop
+        while (questions.length > 0 && questionCount < maxQuestions) {
+            const question = questions[0];
+            questionCount++;
+            console.log('');
+            console.log(chalk.cyan(`Question ${questionCount}`) + (question.category ? chalk.dim(` [${question.category}]`) : ''));
+            console.log(chalk.bold(question.question));
+            let answer;
+            if (question.options && question.options.length > 0) {
+                // Multiple choice question
+                const { selected } = await prompts({
+                    type: 'select',
+                    name: 'selected',
+                    message: 'Select an option:',
+                    choices: [
+                        ...question.options.map(opt => ({ title: opt, value: opt })),
+                        { title: 'Skip this question', value: '__skip__' },
+                    ],
+                });
+                if (selected === '__skip__' || !selected) {
+                    questions.shift();
+                    continue;
+                }
+                answer = selected;
+            }
+            else {
+                // Free text question
+                const { response } = await prompts({
+                    type: 'text',
+                    name: 'response',
+                    message: '>',
+                    validate: (v) => v.length > 0 || 'Please enter a response (or type "skip" to skip)',
+                });
+                if (!response || response.toLowerCase() === 'skip') {
+                    questions.shift();
+                    continue;
+                }
+                answer = response;
+            }
+            // Submit answer
+            const answerSpinner = ora('Processing...').start();
+            try {
+                const answerResponse = await fetch(`${apiUrl}/api/v1/onboarding/answer`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${apiKey}`,
+                    },
+                    body: JSON.stringify({
+                        session_id: sessionId,
+                        question_id: question.id,
+                        answer,
+                    }),
+                });
+                if (answerResponse.ok) {
+                    const answerData = await answerResponse.json();
+                    if (answerData.success && answerData.data) {
+                        const factsCount = answerData.data.facts_extracted || 0;
+                        if (factsCount > 0) {
+                            answerSpinner.succeed(`Recorded (${factsCount} fact${factsCount > 1 ? 's' : ''} extracted)`);
+                        }
+                        else {
+                            answerSpinner.succeed('Recorded');
+                        }
+                        // Update questions and state
+                        if (answerData.data.next_questions) {
+                            questions = answerData.data.next_questions;
+                        }
+                        else {
+                            questions.shift();
+                        }
+                        if (answerData.data.state) {
+                            state = answerData.data.state;
+                        }
+                    }
+                    else {
+                        answerSpinner.warn('Answer recorded (no facts extracted)');
+                        questions.shift();
+                    }
+                }
+                else {
+                    answerSpinner.fail('Could not submit answer');
+                    questions.shift();
+                }
+            }
+            catch {
+                answerSpinner.fail('Network error');
+                questions.shift();
+            }
+            // Check if we should stop
+            if (state.phase === 'confirmation' || state.phase === 'done') {
+                break;
+            }
+        }
+        // Complete onboarding
+        console.log('');
+        const completeSpinner = ora('Completing onboarding...').start();
+        try {
+            const completeResponse = await fetch(`${apiUrl}/api/v1/onboarding/complete`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    session_id: sessionId,
+                    project_id: projectId,
+                }),
+            });
+            if (completeResponse.ok) {
+                const completeData = await completeResponse.json();
+                if (completeData.success && completeData.data) {
+                    const totalFacts = completeData.data.facts_extracted || 0;
+                    completeSpinner.succeed(`Onboarding complete! ${totalFacts} facts stored in memory.`);
+                }
+                else {
+                    completeSpinner.succeed('Onboarding complete!');
+                }
+            }
+            else {
+                completeSpinner.warn('Onboarding session saved (completion had issues)');
+            }
+        }
+        catch {
+            completeSpinner.warn('Could not finalize onboarding');
+        }
+    }
+    catch (err) {
+        spinner.fail('Onboarding failed');
+        error(err instanceof Error ? err.message : String(err));
+    }
+}
 // -----------------------------------------------------------------------------
 // Project Init
 // -----------------------------------------------------------------------------
@@ -1491,12 +1666,41 @@ export async function runInit() {
     const newContent = existingContent.trimEnd() + '\n' + projectContent;
     writeFileSync(projectClaudeMd, newContent);
     success('Created .claude/CLAUDE.md');
+    // Ensure hooks are installed and configured
+    // (User might have run init without setup, or hooks might have been deleted)
+    header('Hook Configuration');
+    try {
+        await installHooks();
+        await configureSettings();
+        info('Hooks configured successfully');
+    }
+    catch (err) {
+        // Non-fatal - just warn
+        console.log(chalk.yellow('⚠ Warning: Could not configure hooks. Run "claudetools --setup" to fix.'));
+    }
     // Summary
     console.log('\n' + chalk.green('  Project initialized!\n'));
     console.log('  ' + chalk.bold('Project:') + ` ${projectName}`);
     console.log('  ' + chalk.bold('ID:') + ` ${projectId}`);
     console.log('  ' + chalk.bold('Config:') + ` ${projectClaudeMd}\n`);
-    console.log(chalk.dim('  Memory tools are now configured for this project.\n'));
+    // Offer onboarding
+    if (config.apiKey) {
+        const { runOnboard } = await prompts({
+            type: 'confirm',
+            name: 'runOnboard',
+            message: 'Run project onboarding? (Helps Claude understand your project)',
+            initial: true,
+        });
+        if (runOnboard) {
+            await runOnboarding(config.apiUrl || DEFAULT_CONFIG.apiUrl, config.apiKey, projectId, projectName);
+        }
+        else {
+            console.log(chalk.dim('\n  You can run onboarding later with: claudetools onboard\n'));
+        }
+    }
+    else {
+        console.log(chalk.dim('  Memory tools are now configured for this project.\n'));
+    }
 }
 // -----------------------------------------------------------------------------
 // Cleanup Command (standalone)

package/dist/tools.js

@@ -146,6 +146,10 @@ EXAMPLES:
                             type: 'string',
                             description: 'Project ID (optional, uses default if not provided)',
                         },
+                        is_critical: {
+                            type: 'boolean',
+                            description: 'Mark as critical fact - always injected regardless of query relevance. Use sparingly for truly essential facts.',
+                        },
                     },
                     required: ['entity1', 'relationship', 'entity2', 'context'],
                 },
@@ -461,6 +465,54 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['goal', 'epic_title', 'tasks'],
                 },
             },
+            {
+                name: 'task_plan_revise',
+                description: 'Modify an existing epic by adding new tasks, removing tasks, or updating task details. Enables iterative planning without recreating the entire plan.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'The ID of the epic to revise',
+                        },
+                        add_tasks: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    effort: { type: 'string', enum: ['xs', 's', 'm', 'l', 'xl'] },
+                                    domain: { type: 'string' },
+                                    blocked_by: { type: 'array', items: { type: 'string' } },
+                                },
+                                required: ['title'],
+                            },
+                            description: 'New tasks to add to the epic',
+                        },
+                        remove_task_ids: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Task IDs to cancel (sets status to cancelled)',
+                        },
+                        update_tasks: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    task_id: { type: 'string' },
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                    effort: { type: 'string', enum: ['xs', 's', 'm', 'l', 'xl'] },
+                                },
+                                required: ['task_id'],
+                            },
+                            description: 'Tasks to update (adds context about changes)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             {
                 name: 'task_start',
                 description: 'PROACTIVE: When starting work on a task, claim it and get all context. Use this before beginning any task work.',
@@ -604,7 +656,16 @@ High hit rate memories (frequently fetched after being indexed) are good candida
             },
             {
                 name: 'task_claim',
-                description: 'Claim a task for working on it. Creates a lock preventing other agents from working on it.',
+                description: `Claim a task for working on it. Creates a lock preventing other agents from working on it.
+
+Lock duration is automatically scaled based on task effort:
+- xs: 15 minutes
+- s: 30 minutes (default if no effort specified)
+- m: 60 minutes (1 hour)
+- l: 120 minutes (2 hours)
+- xl: 240 minutes (4 hours)
+
+Explicit lock_duration_minutes parameter overrides the effort-based default.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -618,7 +679,7 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                         },
                         lock_duration_minutes: {
                             type: 'number',
-                            description: 'Lock duration in minutes (default: 30)',
+                            description: 'Optional: Override effort-based lock duration (in minutes)',
                         },
                     },
                     required: ['task_id', 'agent_id'],
@@ -735,6 +796,32 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['task_id', 'agent_id'],
                 },
             },
+            {
+                name: 'task_handoff',
+                description: 'Hand off a task to a different expert worker type during execution. Releases current lock, updates agent_type, and sets task back to ready status for re-dispatch.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task_id: {
+                            type: 'string',
+                            description: 'The task ID to hand off',
+                        },
+                        new_worker_type: {
+                            type: 'string',
+                            description: 'Target worker type (e.g., "api-expert", "frontend-expert", "database-expert")',
+                        },
+                        reason: {
+                            type: 'string',
+                            description: 'Why the handoff is needed (e.g., "requires database expertise", "needs API integration")',
+                        },
+                        agent_id: {
+                            type: 'string',
+                            description: 'Your agent identifier (default: claude-code)',
+                        },
+                    },
+                    required: ['task_id', 'new_worker_type', 'reason'],
+                },
+            },
             // =========================================================================
             // ORCHESTRATION TOOLS
             // =========================================================================
@@ -917,6 +1004,24 @@ High hit rate memories (frequently fetched after being indexed) are good candida
                     required: ['epic_id'],
                 },
             },
+            {
+                name: 'task_aggregate',
+                description: 'Aggregate work_log context from all sibling tasks under an epic for orchestrator synthesis. Returns structured summary of completed work across all tasks in the epic.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        epic_id: {
+                            type: 'string',
+                            description: 'Epic ID to aggregate from',
+                        },
+                        include_pending: {
+                            type: 'boolean',
+                            description: 'Include non-completed tasks (default: false)',
+                        },
+                    },
+                    required: ['epic_id'],
+                },
+            },
             // =========================================================================
             // CODEBASE MAPPING TOOLS
             // =========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudetools/tools",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Persistent AI memory, task management, and codebase intelligence for Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -14,22 +14,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "prepublishOnly": "npm run build",
-    "codedna:monitor": "tsx -e \"import { runMonitoring } from './src/helpers/codedna-monitoring.js'; runMonitoring()\"",
-    "codedna:analytics": "tsx -e \"import { weeklyAnalyticsSummary } from './src/helpers/usage-analytics.js'; weeklyAnalyticsSummary()\"",
-    "codedna:analytics:24h": "tsx -e \"import { getLast24HoursAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast24HoursAnalytics(); printAnalytics(r, 'Last 24 Hours')\"",
-    "codedna:analytics:30d": "tsx -e \"import { getLast30DaysAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast30DaysAnalytics(); printAnalytics(r, 'Last 30 Days')\"",
-    "prompt:verify": "scripts/verify-prompt-compliance.sh",
-    "eval:build-dataset": "tsx src/evaluation/build-dataset.ts",
-    "eval:threshold": "tsx src/evaluation/threshold-eval.ts"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/claudetools/memory.git"
@@ -65,12 +49,29 @@
     "typescript": "^5.3.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^20.10.0",
     "@types/nunjucks": "^3.2.6",
     "@types/prompts": "^2.4.9",
     "@vitest/ui": "^4.0.15",
+    "better-sqlite3": "^12.5.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
     "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "codedna:monitor": "tsx -e \"import { runMonitoring } from './src/helpers/codedna-monitoring.js'; runMonitoring()\"",
+    "codedna:analytics": "tsx -e \"import { weeklyAnalyticsSummary } from './src/helpers/usage-analytics.js'; weeklyAnalyticsSummary()\"",
+    "codedna:analytics:24h": "tsx -e \"import { getLast24HoursAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast24HoursAnalytics(); printAnalytics(r, 'Last 24 Hours')\"",
+    "codedna:analytics:30d": "tsx -e \"import { getLast30DaysAnalytics, printAnalytics } from './src/helpers/usage-analytics.js'; const r = await getLast30DaysAnalytics(); printAnalytics(r, 'Last 30 Days')\"",
+    "prompt:verify": "scripts/verify-prompt-compliance.sh",
+    "eval:build-dataset": "tsx src/evaluation/build-dataset.ts",
+    "eval:threshold": "tsx src/evaluation/threshold-eval.ts"
   }
-}
+}